_traceback

 SYNOPSIS
   Generate a traceback upon error

 USAGE
   Integer_Type _traceback

 DESCRIPTION
  `_traceback' is an intrinsic integer variable whose value
  controls whether or not a traceback of the call stack is to be
  generated upon error.  If `_traceback' is greater than zero, a
  full traceback will be generated, which includes the values of local
  variables.  If the value is less than zero, a traceback will be
  generated without local variable information, and if
  `_traceback' is zero the traceback will not be generated.

  Local variables are represented in the form `$n' where `n' is an
  integer numbered from zero.  More explicitly, `$0' represents the
  first local variable, `$1' represents the second, and so on.
  Please note that function parameters are local variables and that the
  first parameter corresponds to `$0'.

 SEE ALSO
   _slangtrace, error
--------------------------------------------------------------

_slangtrace

 SYNOPSIS
   Turn function tracing on or off.

 USAGE
   Integer_Type _slangtrace

 DESCRIPTION
  The `_slangtrace' variable is a debugging aid that when set to a
  non-zero value enables tracing when function declared by
  `_trace_function' is entered.  If the value is greater than
  zero, both intrinsic and user defined functions will get traced.
  However, if set to a value less than zero, intrinsic functions will
  not get traced.

 SEE ALSO
   _trace_function, _traceback, _print_stack
--------------------------------------------------------------

errno

 SYNOPSIS
   Error code set by system functions.

 USAGE
   Integer_Type errno

 DESCRIPTION
  A system function can fail for a variety of reasons.  For example, a
  file operation may fail because lack of disk space, or the process
  does not have permission to perform the operation.  Such functions
  will return `-1' and set the variable `errno' to an error
  code describing the reason for failure.

  Particular values of `errno' may be specified by the following
  symbolic constants (read-only variables) and the corresponding
  `errno_string' value:

        EPERM            "Not owner"
        ENOENT           "No such file or directory"
        ESRCH            "No such process"
        ENXIO            "No such device or address"
        ENOEXEC          "Exec format error"
        EBADF            "Bad file number"
        ECHILD           "No children"
        ENOMEM           "Not enough core"
        EACCES           "Permission denied"
        EFAULT           "Bad address"
        ENOTBLK          "Block device required"
        EBUSY            "Mount device busy"
        EEXIST           "File exists"
        EXDEV            "Cross-device link"
        ENODEV           "No such device"
        ENOTDIR          "Not a directory"
        EISDIR           "Is a directory"
        EINVAL           "Invalid argument"
        ENFILE           "File table overflow"
        EMFILE           "Too many open files"
        ENOTTY           "Not a typewriter"
        ETXTBSY          "Text file busy"
        EFBIG            "File too large"
        ENOSPC           "No space left on device"
        ESPIPE           "Illegal seek"
        EROFS            "Read-only file system"
        EMLINK           "Too many links"
        EPIPE            "Broken pipe"
        ELOOP            "Too many levels of symbolic links"
        ENAMETOOLONG     "File name too long"


 EXAMPLE
  The `mkdir' function will attempt to create a directory.  If
  that directory already exists, the function will fail and set
  `errno' to `EEXIST'.

       define create_dir (dir)
       {
          if (0 == mkdir (dir)) return;
          if (errno != EEXIST)
            error ("mkdir %s failied: %s", dir, errno_string);
       }


 SEE ALSO
   errno_string, error, mkdir
--------------------------------------------------------------

where

 SYNOPSIS
   Get indices where an integer array is non-zero

 USAGE
   Array_Type where (Array_Type a)

 DESCRIPTION
  The `where' function examines an integer array `a' and
  returns a 2-d integer array whose rows are the indices of `a'
  where the corresponding element of `a' is non-zero.

 EXAMPLE
  Consider the following:

       variable X = [0.0:10.0:0.01];
       variable A = sin (X);
       variable I = where (A < 0.0);
       A[I] = cos (X) [I];

  Here the variable `X' has been assigned an array of doubles
  whose elements range from `0.0' through `10.0' in
  increments of `0.01'.  The second statement assigns `A' to
  an array whose elements are the `sin' of the elements of `X'.
  The third statement uses the where function to get the indices of
  the elements of `A' that are less than `0.0'.  Finally, the
  last statement substitutes into `A' the `cos' of the
  elements of `X' at the positions of `A' where the
  corresponding `sin' is less than `0'.  The end result is
  that the elements of `A' are a mixture of sines and cosines.

 SEE ALSO
   array_info, sin, cos
--------------------------------------------------------------

vmessage

 SYNOPSIS
   Print a formatted string onto the message device

 USAGE
   vmessage (String_Type fmt, ...)

 DESCRIPTION
  The `vmessage' function formats a sprintf style argument list
  and displays the resulting string onto the message device.

 NOTES
  In the current implementation, strictly speaking, the `vmessage'
  function is not an intrinsic function.  Rather it is a predefined
  S-Lang function using a combination of `Sprintf' and
  `message'.

 SEE ALSO
   message, Sprintf, verror
--------------------------------------------------------------

_apropos

 SYNOPSIS
   Generate a list of functions and variable

 USAGE
   Integer_Type _apropos (String_Type s, Integer_Type flags)

 DESCRIPTION
  The `_apropos' function may be used to get a list of all defined
  objects whose name consists of the substring `s' and whose type
  matches those specified by `flags'.  It returns the number of
  matches.  If the number returned is non-zero, that number of strings
  which represent the names of the matched objects will also be
  present on the stack.
  
  The second parameter `flags' is a bit mapped value whose bits
  are defined according to the following table

        1          Intrinsic Function
        2          User-defined Function
        4          Intrinsic Variable
        8          User-defined Variable


 EXAMPLE

       define apropos (s)
       {
         variable n, name;
         n = _apropos (s, 0xF);
         if (n) vmessage ("Found %d matches:", n);
         else message ("No matches.");
         loop (n)
           {
              name = ();
              message (name);
           }
       }

  prints a list of all matches.

 NOTES
  Since the function returns the matches to the stack, it is possible
  that a stack overfow error could result if there are two many
  matches.  If this happens, the interpreter should be recompiled to
  use a larger stack size.

 SEE ALSO
   is_defined, sprintf
--------------------------------------------------------------

_clear_error

 SYNOPSIS
   Clear an error condition

 USAGE
   _clear_error ()

 DESCRIPTION
  This function may be used in error-blocks to clear the error that
  triggered execution of the error block.  Execution resumes following
  the statement, in the scope of the error-block, that triggered the
  error.

 EXAMPLE
  Consider the following wrapper around the `putenv' function:

       define try_putenv (name, value)
       {
          variable status;
          ERROR_BLOCK
           {
             _clear_error ();
             status = -1;
           }
          status = 0;
          putenv (sprintf ("%s=%s", name, value);
          return status;
       }

  If `putenv' fails, it generates an error condition, which the
  `try_putenv' function catches and clears.  Thus `try_putenv'
  is a function that returns `-1' upon failure and `0' upon
  success.

 SEE ALSO
   _trace_function, _slangtrace, _traceback
--------------------------------------------------------------

_function_name

 SYNOPSIS
   Returns the name of the currently executing function

 USAGE
   String _function_name ();

 DESCRIPTION
  This function returns the name of the currently executing function.
  If called from top-level, it returns the empty string.

 SEE ALSO
   _trace_function, is_defined
--------------------------------------------------------------

_pop_n

 SYNOPSIS
   Remove objects from the stack

 USAGE
   _pop_n (Integer_Type n);

 DESCRIPTION
  The `_pop_n' function pops `n' objects from the top of the
  stack.

 EXAMPLE

       define add3 ()
       {
          variable x, y, z;
          if (_NARGS != 3)
            {
               _pop_n (_NARGS);
               error ("add3: Expecting 3 arguments");
            }
          (x, y, z) = ();
          return x + y + z;
       }


 SEE ALSO
   _stkdepth, pop
--------------------------------------------------------------

_push_struct_field_values

 SYNOPSIS
   Push the values of a structure's fields onto the stack

 USAGE
   Integer_Type num = _push_struct_field_values (Struct_Type s)

 DESCRIPTION
  The `_push_struct_field_values' function pushes the values of
  all the fields of a structure onto the stack, returning the
  number of items pushed.  The fields are pushed such that the last
  field of the structure is pushed first.

 SEE ALSO
   get_struct_field_names, get_struct_field_value
_print_stack

 SYNOPSIS
   print the values on the stack.

 USAGE
   _print_stack ()

 DESCRIPTION
  This function dumps out what is currently on the S-Lang.  It does not
  alter the stack and it is usually used for debugging purposes.

 SEE ALSO
   _stkdepth, string
--------------------------------------------------------------

_slang_guess_type

 SYNOPSIS
   Guess the data type that a string represents.

 USAGE
   DataType_Type _slang_guess_type (String_Type s)

 DESCRIPTION
  This function tries to determine whether its argument `s' represents
  an integer or a floating point number.  If it appears to be neither,
  then a string is assumed.  It returns one of three values depending on
  the format of the string `s':

       Integer_Type     :   If it appears to be an integer
       Double_Type      :   If it appears to be a double
       String_Type      :   Anything else.

  For example, `_slang_guess_type("1e2")' returns
  `Double_Type' but `_slang_guess_type("e12")' returns
  `String_Type'.

 SEE ALSO
   integer, string, double
--------------------------------------------------------------

_stk_reverse

 SYNOPSIS
   Reverse the order of the objects on the stack.

 USAGE
   _stk_reverse (Integer_Type n)

 DESCRIPTION
   The `_stk_reverse' function reverses the order of the top
   `n' items on the stack.

 SEE ALSO
   _stkdepth, _stk_roll
--------------------------------------------------------------

_stk_roll

 SYNOPSIS
   Roll items on the stack

 USAGE
   _stk_roll (Integer_Type n);

 DESCRIPTION
  This function may be used to alter the arrangement of objects on the
  stack.  Specifically, if the integer `n' is positive, the top
  `n' items on the stack are rotated up.  If
  `n' is negative, the top `abs(n)' items on the stack are
  rotated down.

 EXAMPLE
  If the stack looks like:

       item-0
       item-1
       item-2
       item-3

  where `item-0' is at the top of the stack, then
  `_stk_roll(-3)' will change the stack to:

       item-2
       item-0
       item-1
       item-3


 NOTES
  This function only has an effect for `abs(n) > 1'.

 SEE ALSO
   _stkdepth, _stk_reverse, _pop_n, _print_stack
--------------------------------------------------------------

_stkdepth

 USAGE
   Get the number of objects currently on the stack.

 SYNOPSIS
   Integer_Type _stkdepth ()

 DESCRIPTION
  The `_stkdepth' function returns number of items on stack prior
  to the call of `_stkdepth'.

 SEE ALSO
   _print_stack, _stk_reverse, _stk_roll
--------------------------------------------------------------

_trace_function

 SYNOPSIS
   Set the function to trace

 USAGE
   _trace_function (String_Type f)

 DESCRIPTION
  `_trace_function' declares that the S-Lang function with name
  `f' is to be traced when it is called.  Calling
  `_trace_function' does not in itself turn tracing on.  Tracing
  is turned on only when the variable `_slangtrace' is non-zero.

 SEE ALSO
   _slangtrace, _traceback
--------------------------------------------------------------

array_info

 SYNOPSIS
   Returns information about an array

 USAGE
   (Array_Type, Integer_Type, DataType_Type) array_info (Array_Type a)

 DESCRIPTION
  The `array_info' function returns information about the array `a'.
  It returns three values: an 1-d integer array array specifying the
  size of each dimension of `a', the number of dimensions of
  `a', and the data type of `a'.

 EXAMPLE
  The `array_info' function may be used to find the number of rows
  of an array:

       define num_rows (a)
       {
          variable dims, num_dims, data_type;
   
          (dims, num_dims, data_type) = array_info (a);
          return dims [0];
       }


 SEE ALSO
   typeof, reshape
--------------------------------------------------------------

array_sort

 SYNOPSIS
   Sort an array

 USAGE
   Array_Type array_sort (Array_Type a, String_Type f)

 DESCRIPTION
  `array_sort' sorts the array `a' into ascending order
  according to the function specified by the name `f' and returns
  an integer array that represents the result of the sort.

  The sort function represented by `f' must be a S-Lang
  user-defined function that takes two arguments.  The function must
  return an integer that is less than zero if the first parameter is
  considered to be less than the second, zero if they are equal, and a
  value greater than zero if the first is greater than the second.

  The integer array returned by this function is simply an index that
  indicates the order of the sorted array.  The input array `a' is
  not changed.

 EXAMPLE
  An array of strings may be sorted using the `strcmp' function
  since it fits the specification for the sorting function described
  above:

        variable A = String_Type [3];
        A[0] = "gamma"; A[1] = "alpha"; A[2] = "beta";
   
        variable I = array_sort (A, "strcmp");

  After the `array_sort' has executed, the variable `I' will
  have the values `[2, 0, 1]'.  This array can be used to
  re-shuffle the elements of `A' into the sorted order via the
  array index expression `A = A[I]'.

 NOTES
  The current sorting algorithm is a heap-sort.

 SEE ALSO
   strcmp
--------------------------------------------------------------

atof

 SYNOPSIS
   Convert a string to a double precision number

 USAGE
   Double_Type atof (String_Type s)

 DESCRIPTION
  This function converts a string `s' to a double precision value
  and returns the result.  It performs no error checking on the format
  of the string.  The function `_slang_guess_type' may be used to
  check the syntax of the string.

 EXAMPLE

        define error_checked_atof (s)
        {
           switch (_slang_guess_type (s))
           {
              case Double_Type:
                return atof (s);
           }
           {
              case Integer_Type:
                return double (integer (s));
           }
   
           verror ("%s is is not a double", s);
       }


 SEE ALSO
   typecast, double, _slang_guess_type
--------------------------------------------------------------

autoload

 SYNOPSIS
   Load a function from a file

 USAGE
   autoload (String_Type funct, String_Type file)

 DESCRIPTION
    The `autoload' function is used to declare `funct' to the
    interpreter and indicate that it should be loaded from `file' when
    it is actually used.

 EXAMPLE
    Suppose `bessel_j0' is a function defined in the file
    `bessel.sl'.  Then the statement

         autoload ("bessel_j0", "bessel.sl");

    will cause `bessel.sl' to be loaded prior to the execution of
    `bessel_j0'

 SEE ALSO
   evalfile
--------------------------------------------------------------

byte_compile_file

 SYNOPSIS
   Compile a file to byte-code for faster loading.

 USAGE
   byte_compile_file (String_Type file, Integer_Type method)

 DESCRIPTION
  The `byte_compile_file' function byte-compiles `file'
  producing a new file with the same name except a `'c'' is added
  to the output file name.  For example, `file' is
  `"site.sl"', then the function produces a new file named
  `site.slc'.

 NOTES
  The `method' parameter is not used in the current
  implementation.  Its use is reserved for the future.  For now, set
  it to `0'.

 SEE ALSO
   evalfile
--------------------------------------------------------------

char

 SYNOPSIS
   Convert an ascii value into a string

 USAGE
   String_Type char (Integer_Type c)

 DESCRIPTION
  The `char' function converts an integer ascii value `c' to a string
  of unit length such that the first character of the string is `c'.
  For example, `char('a')' returns the string `"a"'.

 SEE ALSO
   integer, string, typedef
--------------------------------------------------------------

chdir

 SYNOPSIS
   Change the current working directory.

 USAGE
   Integer_Type chdir (String_Type dir)

 DESCRIPTION
  The `chdir' function may be used to changed the current working
  directory to the directory specified by `dir'.  Upon sucess it
  returns zero; however, upon failure it returns `-1' and sets
  `errno' accordingly.

 SEE ALSO
   mkdir, stat_file
--------------------------------------------------------------

chmod

 SYNOPSIS
   Change the mode of a file

 USAGE
   Integer_Type chmod (String_Type file, Integer_Type mode)

 DESCRIPTION
  The `chmod' function changes the permissions of `file' to those
  specified by `mode'.  It returns `0' upon success, or
  `-1' upon failure setting `errno' accordingly.

  See the system specific documentation for the C library
  function `chmod' for a discussion of the `mode' parameter.

 SEE ALSO
   chown, stat_file
--------------------------------------------------------------

chown

 SYNOPSIS
   Change the owner of a file

 USAGE
   Integer_Type chown (String_Type file, Integer_Type uid, Integer_Type gid)

 DESCRIPTION
  The `chown' function is used to change the user-id and group-id of
  `file' to `uid' and `gid', respectively.  It returns
  `zero' upon success and `-1' upon failure, with `errno'
  set accordingly.

 NOTES
  On most systems, only the super user can change the ownership of a
  file.

  Some systems do not support this function.

 SEE ALSO
   chmod, stat_file
--------------------------------------------------------------

create_delimited_string

 SYNOPSIS
   Concatenate strings using a delimiter

 USAGE
   String_Type create_delimited_string (delim, s_1, s_2, ..., s_n, n)

       String_Type delim, s_1, ..., s_n
       Integer_Type n


 DESCRIPTION
  `create_delimited_string' performs a concatenation operation on
  the `n' strings `s_1', ...,`s_n', using the string
  `delim' as a delimiter.  The resulting string is equivalent to
  one obtained via

         s_1 + delim + s_2 + delim + ... + s_n


 EXAMPLE
  One use for this function is to construct path names, e.g.,

       create_delimited_string ("/", "user", "local", "bin", 3);

  will produce `"usr/local/bin"'.

 NOTES
  The expression `strcat(a,b)' is equivalent to
  `create_delimited_string("", a, b, 2)'.

 SEE ALSO
   is_list_element, extract_element, strchop, strcat
--------------------------------------------------------------

define_case

 SYNOPSIS
   Define upper-lower case conversion.

 USAGE
   define_case (Integer_Type ch_up, Integer_Type ch_low);

 DESCRIPTION
  This function defines an upper and lowercase relationship between two
  characters specified by the arguments.  This relationship is used by
  routines which perform uppercase and lowercase conversions.
  The first integer `ch_up' is the ascii value of the uppercase character
  and the second parameter `ch_low' is the ascii value of its
  lowercase counterpart.

 SEE ALSO
   strlow, strup
--------------------------------------------------------------

double

 SYNOPSIS
   Convert an object to double precision

 USAGE
   result = double (x)

 DESCRIPTION
  The `double' function typecasts an object `x' to double
  precision.  For example, if `x' is an array of integers, an
  array of double types will be returned.  If an object cannot be
  converted to `Double_Type', a type-mismatch error will result.

 NOTES
  The `double' function is equivalent to the typecast operation

        typecast (x, Double_Type)

  To convert a string to a double precision number, use `atoi'
  function.

 SEE ALSO
   typecast, atoi, int
--------------------------------------------------------------

dup

 SYNOPSIS
   Duplicate the value at the top of the stack

 USAGE
   dup ()

 DESCRIPTION
  This function returns an exact duplicate of the object on top of the
  stack.  For some objects such as arrays or structures, it creates a
  new reference to the array.  However, for simple scalar S-Lang types such
  as strings, integers, and doubles, it creates a new copy of the
  object.

 SEE ALSO
   pop, typeof
--------------------------------------------------------------

errno_string

 SYNOPSIS
   Return a string describing an errno.

 USAGE
   String_Type errno_string (Integer_Type err)

 DESCRIPTION
  The `errno_string' function returns a string describing the
  integer error code `err'.  The variable `err' usually
  corresponds to the `errno' intrinsic function.  See the
  description for `errno' for more information.

 EXAMPLE
  The `errno_string' function may be used as follows:

       define sizeof_file (file)
       {
          variable st = stat (file);
          if (st == NULL)
            verror ("%s: %s", file, errno_string (errno);
          return st.st_size;
       }


 SEE ALSO
   errno, stat, verror
--------------------------------------------------------------

error

 SYNOPSIS
   Generate an error condition

 USAGE
   error (String_Type msg

 DESCRIPTION
  The `error' function generates a S-Lang error condition causing
  the interpreter to start unwinding to top-level.  It takes a single
  string parameter which is displayed on the stderr output device.
  The error condition may be cleared via an `ERROR_BLOCK' with the
  `_clear_error' function.  Consult \user-manual for more
  information.

 EXAMPLE

       define add_txt_extension (file)
       {
          if (typeof (file) != String_Type)
            error ("add_extension: parameter must be a string");
          file += ".txt";
          return file;
       }


 SEE ALSO
   verror, _clear_error, message
--------------------------------------------------------------

evalfile

 SYNOPSIS
   Interpret a file containing slang code.

 USAGE
   Integer_Type evalfile (String_Type file)

 DESCRIPTION
  The `evalfile' function loads `file' into the interpreter.
  If no errors were encountered, `1' will be returned; otherwise,
  a S-Lang error will be generated and the function will return zero.

 EXAMPLE

       define load_file (file)
       {
          ERROR_BLOCK { _clear_error (); }
          () = evalfile (file);
       }


 SEE ALSO
   eval, autoload
--------------------------------------------------------------

eval

 SYNOPSIS
   Interpret a string as slang code

 USAGE
   eval (String_Type expression)

 DESCRIPTION
  The `eval' function parses a string as S-Lang code and executes the
  result.  This is a useful function in many contexts such as dynamically
  generating function definitions where there is no way to generate
  them otherwise.

 EXAMPLE

       if (0 == is_defined ("my_function"))
         eval ("define my_function () { message (\"my_function\"); }");


 SEE ALSO
   is_defined, autoload, evalfile
--------------------------------------------------------------

extract_element

 SYNOPSIS
   Extract the nth element of a string with delimiters

 USAGE
   String_Type extract_element (String_Type list, Integer_Type nth, Integer_Type delim);

 DESCRIPTION
  The `extract_element' function may be used to extract the
  `nth' element of the `delim' delimited list of strings
  `list'.  The function will return the `nth' element of the
  list, unless `nth' specifies more elements than the list
  contains, in which case `NULL' will be returned.
  Elements in the list are numbered from `0'.

 EXAMPLE
  The expression

        extract_element ("element 0, element 1, element 2", 1, ',')

  returns the string `" element 1"', whereas

        extract_element ("element 0, element 1, element 2", 1, ' ')

  returns `"0,"'.

  The following function may be used to compute the number of elements
  in the list:

        define num_elements (list, delim)
        {
           variable nth = 0;
           while (NULL != extract_element (list, nth, delim))
             nth++;
           return nth;
        }


 SEE ALSO
   is_list_element, is_substr, strchop, create_delimited_string
--------------------------------------------------------------

fclose

 SYNOPSIS
   Close a file

 USAGE
   Integer_Type fclose (File_Type fp)

 DESCRIPTION
  The `fclose' function may be used to close an open file pointer
  `fp'.  Upon success it returns zero, and upon failure it sets
  `errno' and returns `-1'.  Failure usually indicates a that
  the file system is full or that `fp' does not refer to an open file.

 NOTES
  Many C programmers call `fclose' without checking the return
  value.  The S-Lang language requires the programmer to explicitly
  handle any value returned by a S-Lang function.  The simplest way to
  handle the return value from `fclose' is to use it as:

        () = fclose (fp);


 SEE ALSO
   fopen, fgets, fflush, errno
--------------------------------------------------------------

fflush

 SYNOPSIS
   Flush an output stream

 USAGE
   Integer_Type fflush (File_Type fp)

 DESCRIPTION
  The `fflush' function may be used to update the _output_
  stream specified by `fp'.  It returns `0' upon success, or
  `-1' upon failure and sets `errno' accordingly.  In
  particular, this function will fail if `fp' does not represent
  an output stream, or if `fp' is associated with a disk file and
  there is insufficient disk space.

 EXAMPLE
  This example illustrates how to use the `fflush' function
  without regard to the return value:

       () = fputs ("Enter value> ", stdout);
       () = fflush (stdout);


 NOTES
  Many C programmers disregard the return value from the `fflush'
  function.  The above example illustrates how to properly do this in
  the S-Lang langauge.

 SEE ALSO
   fopen, fclose
--------------------------------------------------------------

fgets

 SYNOPSIS
   Read a line from a file.

 USAGE
   Integer_Type fgets (SLang_Ref_Type ref, File_Type fp)

 DESCRIPTION
  `fgets' reads a line from the open file specified by `fp'
  and places the characters in the variable whose reference is
  specified by `ref'.
  It returns `-1' if `fp' is not associated with an open file
  or an attempt was made to read at the end the file; otherwise, it
  returns the number of characters read.

 EXAMPLE
  The following example returns the lines of a file via a linked list:

       define read_file (file)
       {
          variable buf, fp, root, tail;
          variable list_type = struct { text, next };
   
          root = NULL;
   
          fp = fopen(file, "r");
          if (fp == NULL)
            error("fopen %s failed." file);
          while (-1 != fgets (&buf, fp))
            {
               if (root == NULL)
                 {
                    root = @list_type;
                    tail = root;
                 }
               else
                 {
                    tail.next = @list_type;
                    tail = tail.next;
                 }
               tail.text = buf;
               tail.next = NULL;
            }
          () = fclose (fp);
          return root;
       }


 SEE ALSO
   fopen, fclose, fputs, error
--------------------------------------------------------------

fopen

 SYNOPSIS
   Open a file

 USAGE
   File_Type fopen (String_Type f, String_Type m)

 DESCRIPTION
  The `fopen' function opens a file `f' according to the mode
  string `m'.  Allowed values for `m' are:

        "r"    Read only
        "w"    Write only
        "a"    Append
        "r+"   Reading and writing at the beginning of the file.
        "w+"   Reading and writing.  The file is created if it does not
                 exist; otherwise, it is truncated.
        "a+"   Reading and writing at the end of the file.  The file is created
                 if it does not already exist.

  In addition, the mode string can also include the letter `'b''
  as the last character to indicate that the file is to be opened in
  binary mode.

  Upon success, `fopen' a `File_Type' object which is meant to
  be used in other operations that require an open file.  Upon
  failure, the function returns `NULL'.

 EXAMPLE
  The following function opens a file in append mode and writes a
  string to it:

       define append_string_to_file (file, str)
       {
          variable fp = fopen (file, "a");
          if (fp == NULL) verror ("%s could not be opened", file);
          () = fputs (string, fp);
          () = fclose (fp);
       }

  Note that the return values from `fputs' and `fclose' are
  ignored.

 NOTES
  There is no need to explicitly close a file opened with `fopen'.
  If the returned `File_Type' object goes out of scope, S-Lang
  will automatically close the file.  However, explicitly closing a
  file after use is recommended.

 SEE ALSO
   fclose, fgets, fputs
--------------------------------------------------------------

fputs

 SYNOPSIS
   Write a string to an open stream

 USAGE
   Integer_Type fputs (String_Type s, File_Type fp);

 DESCRIPTION
  The `fputs' function writes the string `s' to the open file
  pointer `fp'. It returns -1 upon failure and sets `errno',
  otherwise it returns the length of the string.

 EXAMPLE
  The following function opens a file in append mode and uses the
  `fputs' function to write to it.

       define append_string_to_file (str, file)
       {
          variable fp;
          fp = fopen (file, "a");
          if (fp == NULL) verror ("Unable to open %s", file);
          if ((-1 == fputs (s, fp))
              or (-1 == fclose (fp)))
            verror ("Error writing to %s", file);
       }


 NOTES
  One must not disregard the return value from the `fputs'
  function, as many C programmers do.  Doing so may lead to a stack
  overflow error.

 SEE ALSO
   fclose, fopen, fgets
--------------------------------------------------------------

getcwd

 SYNOPSIS
   Get the current working directory

 USAGE
   String_Type getcwd ()

 DESCRIPTION
  The `getcwd' function returns the absolute pathname of the
  current working directory.  If an error occurs or it cannot
  determine the working directory, it returns `NULL' and sets
  `errno' accordingly.

 NOTES
  Under Unix, OS/2, and MSDOS, the pathname returned by this function
  includes the trailing slash character.  Some versions also include
  the drive specifier.

 SEE ALSO
   mkdir, chdir, errno
--------------------------------------------------------------

get_doc_string_from_file

 SYNOPSIS
   Read documentation from a file

 USAGE
   String_Type get_doc_string_from_file (String_Type f, String_Type t)

 DESCRIPTION
  `get_doc_string_from_file' opens the documentation file `f'
  and searches it for topic `t'.  It returns the documentation for
  `t' upon success, otherwise it returns `NULL' upon error.
  It will fail if `f' could not be opened or does not contain
  documentation for the topic.

 SEE ALSO
   stat_file
--------------------------------------------------------------

get_struct_field_names

 SYNOPSIS
   Retrieve the field names associated with a structure

 USAGE
   String_Type[] = get_struct_field_names (Struct_Type s)

 DESCRIPTION
   The `get_struct_field_names' function returns an array of
   strings whose elements specify the names of the fields of the
   struct `s'.

 EXAMPLE
   The following example illustrates how the
   `get_struct_field_names' function may be used to print the
   value of a structure.

         define print_struct (s)
         {
            variable names, i, num;
   	 variable name, value;
   
            names = get_struct_field_names (s);
   
   	 % num values will be placed on stack by next call
   	 num = _push_struct_field_values (s);
   
            for (i = 0; i < num; i++)
   	   {
   	     name = names[i];
   	     value = ();
   
                vmessage ("s.%s = %s\n", name, string(value));
              }
         }


 SEE ALSO
   _push_struct_field_values, get_struct_field_value
--------------------------------------------------------------

get_struct_field_value

 SYNOPSIS
   Get the value associated with a structure field

 USAGE
   x = get_struct_field_value (Struct_Type s, String field_name)

 DESCRIPTION
   The `get_struct_field_value' function the value of the field
   whose name is specified by `field_name' of the structure `s'.

 EXAMPLE
   The following example illustrates how this function may be used to 
   to print the value of a structure.

         define print_struct (s)
         {
            variable names, i, num;
   	 variable name, value, dims;
   
            names = get_struct_field_names (s);
            (dims,,) = array_info (names);
   	 num = dims[0];
   
            for (i = 0; i < num; i++)
   	   {
   	     name = names[i];
   	     value = get_struct_field_value (s, name);
                vmessage ("s.%s = %s\n", name, string(value));
              }
         }


 SEE ALSO
   get_struct_field_names, _push_struct_field_values, array_info
--------------------------------------------------------------

getenv

 SYNOPSIS
   Get the value of an environment variable

 USAGE
   String_Type getenv(String_Type var)

 DESCRIPTION
   The `getenv' function returns a string that represents the
   value of an environment variable `var'.  It will return
   `NULL' if there is no environment variable whose name is given
   by `var'.

 EXAMPLE

       if (NULL != getenv ("USE_COLOR"))
         {
           set_color ("normal", "white", "blue");
           set_color ("status", "black", "gray");
           USE_ANSI_COLORS = 1;
         }


 SEE ALSO
   putenv, strlen, is_defined
--------------------------------------------------------------

init_char_array

 SYNOPSIS
   Initialize an array of characters

 USAGE
   init_char_array (Array_Type a, String_Type s)

 DESCRIPTION
  The `init_char_array' function may be used to initialize a
  character array `a' by settting the elements of the array
  `a' to the corresponding characters of the string `s'.

 EXAMPLE
  The statements

        variable a = Char_Type [10];
        init_char_array (a, "HelloWorld");

   creates an character array and initializes its elements to the
   characters in the string `"HelloWorld"'.

 NOTES
   The character array must be large enough to hold all the characters
   of the initialization string.

 SEE ALSO
   strlen, strcat
--------------------------------------------------------------

integer

 SYNOPSIS
   Convert a string to an integer

 USAGE
   Integer_Type integer (String_Type s)

 DESCRIPTION
  The `integer' function converts a string representation of an
  integer back to an integer.  If the string does not form a valid
  integer, a type-mismatch error will be generated.

 EXAMPLE
  `integer ("1234")' returns the integer value `1234'.

 NOTES
  This function operates only on strings and is not the same as the
  more general `typecast' operator.

 SEE ALSO
   typecast, _slang_guess_type, string, sprintf, char
--------------------------------------------------------------

int

 SYNOPSIS
   Typecast an object to an integer

 USAGE
   int (s)

 DESCRIPTION
  This function performs a typecast of `s' from its data type to
  an object of `Integer_Type'.  If `s' is a string, it returns
  returns the ascii value value of the first character of the string
  `s'.  If `s' is `Double_Type', `int' truncates the
  number to an integer and returns it.

 EXAMPLE
  `int' can be used to convert single character strings to
  integers.  As an example, the intrinsic function `isdigit' may
  be defined as

       define isdigit (s)
       {
         if ((int (s) >= '0') and (int (s) <= '9')) return 1;
         return 0;
       }


 NOTES
  This function is equalent to `typecast (s, Integer_Type)';

 SEE ALSO
   typecast, double, integer, char, isdigit
--------------------------------------------------------------

is_defined

 SYNOPSIS
   Indicate whether a variable or function defined.

 USAGE
   Integer_Type is_defined (String_Type obj)

 DESCRIPTION
   This function is used to determine whether or not a function or
   variable whose name is `obj' has been defined.  If `obj' is not
   defined, the function returns 0.  Otherwise, it returns a non-zero
   value that defpends on the type of object `obj' represents.
   Specifically, it returns one of the following values:

        +1 if an intrinsic function
        +2 if user defined function
        -1 if intrinsic variable
        -2 if user defined variable
         0 if undefined


 EXAMPLE
    For example, consider the function:

       define runhooks (hook)
       {
          if (2 == is_defined(hook)) eval(hook);
       }

    This function could be called from another S-Lang function to
    allow customization of that function, e.g., if the function
    represents a mode, the hook could be called to setup keybindings
    for the mode.

 SEE ALSO
   typeof, eval, autoload
--------------------------------------------------------------

is_list_element

 SYNOPSIS
   Test whether a delimited string contains a specific element

 USAGE
   Integer_Type is_list_element (String_Type list, String_Type elem, Integer_Type delim)

 DESCRIPTION
  The `is_list_element' function may be used to determine whether
  or not a delimited list of strings, `list', contains the element
  `elem'.  If `elem' is not an element of `list', the function
  will return zero, otherwise, it returns 1 plus the matching element
  number.

 EXAMPLE
  The expression

        is_list_element ("element 0, element 1, element 2", "0,", ' ');

  returns `2' since `"0,"' is element number one of the list
  (numbered from zero).

 SEE ALSO
   extract_element, is_substr, create_delimited_string
--------------------------------------------------------------

is_substr

 SYNOPSIS
   Test for a specified substring within a string.

 USAGE
   Integer_Type is_substr (String_Type a, String_Type b)

 DESCRIPTION
  This function may be used to determine if `a' contains the
  string `b'.  If it does not, the function returns 0; otherwise it
  returns the position of the first occurance of `b' in `a'.

 NOTES
  It is important to remember that the first character of a string
  corresponds to a position value of `1'.

 SEE ALSO
   substr, string_match, str_replace
--------------------------------------------------------------

isdigit

 SYNOPSIS
   Tests for a decimal digit character

 USAGE
   Integer_Type isdigit (String_Type s)

 DESCRIPTION
  This function returns a non-zero value if the first character in the
  string `s' is a digit; otherwise, it returns zero.

 EXAMPLE
  A simple, user defined implementation of `isdigit' is

       define isdigit (s)
       {
          return ((s[0] <= '9') and (s[0]  >= '0'));
       }

  However, the intrinsic function `isdigit' executes many times faster
  than the equivalent representation defined above.

 NOTES
  Unlike the C function with the same name, the S-Lang function takes
  a string argument.

 SEE ALSO
   int, integer
--------------------------------------------------------------

lstat_file

 SYNOPSIS
   Get information about a symbolic link

 USAGE
   Struct_Type lstat_file (String_Type file)

 DESCRIPTION
  The `lstat_file' function behaves identically to `stat_file'
  but if `file' is a symbolic link, `lstat_file' returns
  information about the link itself, and not the file that it
  references.

  See the documentation for `stat_file' for more information.

 NOTES
  On systems that do not support symbolic links, there is no
  difference between this function and the `stat_file' function.

 SEE ALSO
   stat_file
--------------------------------------------------------------

make_printable_string

 SYNOPSIS
   Format a string suitable for parsing

 USAGE
   String_Type make_printable_string(String_Type str)

 DESCRIPTION
  This function formats a string in such a way that it may be used as
  an argument to the `eval' function.  The resulting string is
  identical to `str' except that it is enclosed in double quotes and the
  backslash, newline, and double quote characters are expanded.

 SEE ALSO
   eval, str_quote_string
--------------------------------------------------------------

message

 SYNOPSIS
   Print a string onto the message device

 USAGE
   message (String_Type s

 DESCRIPTION
  The `message' function will print the string specified by
  `s' onto the message device.

 EXAMPLE

        define print_current_time ()
        {
          message (time ());
        }


 NOTES
  The message device will depend upon the application.  For example,
  the output message device for the `jed' editor correspond to the
  line at the bottom of the display window.  The default message
  device is the standard output device.

 SEE ALSO
   vmessage, sprintf, error
--------------------------------------------------------------

mkdir

 SYNOPSIS
   Create a new directory

 USAGE
   Integer_Type mkdir (String_Type dir, Integer_Type mode)

 DESCRIPTION
  The `mkdir' function creates a directory whose name is specified
  by the `dir' parameter with permissions specified by `mode'.
  Upon success `mkdir' returns zero, or it returns `-1' and
  sets `errno' accordingly.  In particular, if the directory
  already exists, the function will fail and set errno to
  `EEXIST'.

 EXAMPLE
     define my_mkdir (dir)
     {
        if (0 == mkdir (dir, 0777)) return;
        if (errno == EEXIST) return;
        verror ("mkdir %s failed: %s", dir, errno_string (errno));
     }

 NOTES
  The `mode' parameter may not be meaningful on all systems.  On
  systems where it is meaningful, the actual permissions on the newly
  created directory are modified by the process's umask.

 SEE ALSO
   rmdir, getcwd, chdir, fopen, errno
--------------------------------------------------------------

polynom

 SYNOPSIS
   Evaluate a polynomial

 USAGE
   Double_Type polynom(Double_Type a, b, ...c, Integer_Type n, Double_Type x)

 DESCRIPTION
  The `polynom' function returns the value of the polynomial expression:

        ax^n + bx^(n - 1) + ... c


 NOTES
  The `polynom' function should be extended to work with complex
  and array data types.  The current implementation is limited to
  `Double_Type' quantities.

 SEE ALSO
   exp
--------------------------------------------------------------

putenv

 SYNOPSIS
   Add or change an environment variable

 USAGE
   putenv (String_Type s)

 DESCRIPTION
    This functions adds string `s' to the environment.  Typically,
    `s' should of the form `"name=value"'.  The function
    signals a S-Lang error upon failure.

 NOTES
    This function is not available on all systems.

 SEE ALSO
   getenv, sprintf
--------------------------------------------------------------

reshape

 SYNOPSIS
   Reshape an array

 USAGE
   reshape (Array_Type A, Array_Type I)

 DESCRIPTION
  The `reshape' function changes the size of a to have the size
  specified by the 1-d integer array `I'.  The elements of `I'
  specify the new dimensions of `A' and must be consistent with
  the number of elements `A'.

 EXAMPLE
  If `A' is a `100' element 1-d array, it can be changed to a
  2-d `20' by `5' array via

         reshape (A, [20, 5]);

  However, `reshape(A, [11,5])' will result in an error because
  the the `[11,5]' array specifies `55' elements.

 SEE ALSO
   array_info
--------------------------------------------------------------

set_float_format

 SYNOPSIS
   Set the format for printing floating point values.

 USAGE
   set_float_format (String_Type fmt)

 DESCRIPTION
  The `set_float_format' function is used to set the floating
  point format to be used when floating point numbers are printed.
  The routines that use this are the traceback routines and the
  `string' function. The default value is `"%f"'

 EXAMPLE

        s = string (PI);                %  --> s = "3.14159"
        set_float_format ("%16.10f");
        s = string (PI);                %  --> s = "3.1415926536"
        set_float_format ("%10.6e");
        s = string (PI);                %  --> s = "3.141593e+00"


 SEE ALSO
   string, sprintf, double
--------------------------------------------------------------

Sprintf

 SYNOPSIS
   Format objects into a string

 USAGE
   String_Type Sprintf (String_Type format, ..., Integer_Type n)

 DESCRIPTION
  `Sprintf' formats a string from `n' objects according to
  `format'.  Unlike `sprintf', the `Sprintf' function
  requires the number of items to format.

 EXAMPLE

        s = Sprintf("%f is greater than %f but %s is better than %s\n",
                    PI, E, "Cake" "Pie", 4);

  The final argument to `Sprintf' is the number of items to format; in
  this case, there are 4 items.

 SEE ALSO
   sprintf, string
--------------------------------------------------------------

sprintf

 SYNOPSIS
   Format objects into a string

 USAGE
   String sprintf (String format, ...);

 DESCRIPTION
  This function performs a similar task as the C function with the same
  name.  It differs from the S-Lang function `Sprintf' in that it
  does not require the number of items to format.
  See the documentation for `Sprintf' for more information.

 SEE ALSO
   Sprintf, string, vmessage
--------------------------------------------------------------

stat_file

 SYNOPSIS
   Get information about a file

 USAGE
   Struct_Type stat_file (String_Type file)

 DESCRIPTION
  The `stat_file' function returns information about `file'
  through the use of the system `stat' call.  If the stat call
  fails, the function returns `NULL' and sets errno accordingly.
  If it is successful, it returns a stat structure with the following
  integer fields:

       st_dev
       st_ino
       st_mode
       st_nlink
       st_uid
       st_gid
       st_rdev
       st_size
       st_atime
       st_mtime
       st_ctime

  See the man page for `stat' for a discussion of these fields.

 EXAMPLE
  The following example shows how the `stat_file' function may be
  used to get the size of a file:

        define file_size (file)
        {
           variable st;
           st = stat_file(file);
           if (st == NULL) verror ("Unable to stat %s", file);
           return st.st_size;
        }


 SEE ALSO
   lstat_file, stat_is
--------------------------------------------------------------

stat_is

 SYNOPSIS
   Parse the var{st_mode

 USAGE
   Integer_Type stat_is (String_Type type, Integer_Type st_mode

 DESCRIPTION
  The `stat_is' function returns an integer value about the type of file
  specified by `st_mode'.  Specifically, `type' must be one of the
  strings:

        "sock"     (socket)
        "fifo"     (fifo)
        "blk"      (block device)
        "chr"      (character device)
        "reg"      (regular file)
        "lnk"      (link)
        "dir"      (dir)

  It returns a non-zero value if `st_mode' corresponds to
  `type'.

 EXAMPLE
  The following example illustrates how to use the `stat_is'
  function to determine whether or not a file is a directory:

        define is_directory (file)
        {
           variable st;
   
           st = stat_file (file);
           if (st == NULL) return 0;
           return stat_is ("dir", st.st_mode);
        }


 SEE ALSO
   stat_file, lstat_file
--------------------------------------------------------------

str_quote_string

 SYNOPSIS
   Escape characters in a string.

 USAGE
   String_Type str_quote_string(String_Type str, String_Type qlis, Integer_Type quote)

 DESCRIPTION
  The `str_quote_string' returns a string identical to `str'
  except that all characters in the set specified by the string
  `qlis' are escaped with the `quote' character, including the
  quote character itself.   This function is useful for making a
  string that can be used in a regular expression.

 EXAMPLE
  Execution of the statements

      node = "Is it [the coat] really worth $100?";
      tag = str_quote_string (node, "\\^$[]*.+?", '\\');

  will result in `tag' having the value:

       Is it \[the coat\] really worth \$100\?


 SEE ALSO
   str_uncomment_string, make_printable_string
--------------------------------------------------------------

str_replace

 SYNOPSIS
   Replace a substring of a string

 USAGE
   Integer_Type str_replace (String_Type a, String_Type b, String_Type c)

 DESCRIPTION
  The `str_replace' function replaces the first occurance of `b' in
  `a' with `c' and returns an integer that indicates whether a
  replacement was made or not. If `b' does not occur in `a', zero is
  returned.  However, if `b' occurs in `a', a non-zero integer is
  returned as well as the new string resulting from the replacement.

 EXAMPLE

     define str_replace_all (orig, match, replacement)
     {
        while (str_replace (orig, match, replacement))
           orig = ();
        return orig;
     }

  is a function that replaces all occurances in a string.

 SEE ALSO
   is_substr, strsub, strtrim
--------------------------------------------------------------

str_uncomment_string

 SYNOPSIS
   Remove comments from a string

 USAGE
   String_Type str_uncomment_string(String_Type s, String_Type beg, String_Type end)

 DESCRIPTION
  This function may be used to remove comments from a string `s'.
  The parameters, `beg' and `end', are strings of equal length
  whose corresponding characters specify the begin and end comment
  characters, respectively.  It returns the uncommented string.

 EXAMPLE
  The expression

        str_uncomment_string ("Hello (testing) 'example' World", "'(", "')")

  returns the string `"Hello   World"'.

 NOTES
  This routine does not handle multicharacter comment delimiters and it
  assumes that comments are not nested.

 SEE ALSO
   str_quote_string
--------------------------------------------------------------

strcat

 SYNOPSIS
   Concatenate two strings

 USAGE
   String_Type strcat (String_Type a, String_Type b)

 DESCRIPTION
   The `strcat' function takes two string valued quantities, `a' and
   `b', concatenates them together and returns the result.

 EXAMPLE

       strcat ("Hello ", "World");

   produces the string `"Hello World"'.

 NOTES
   This function is equivalent to the binary operation `a+b'.

 SEE ALSO
   sprintf, create_delimited_string
--------------------------------------------------------------

strchopr

 SYNOPSIS
   Chop or split a string into substrings.

 USAGE
   Integer_Type strchopr (String_Type str, String_Type delim, String_Type quote)

 DESCRIPTION
  This routine performs exactly the same function as `strchop' except
  that it returns the substrings in the reverse order.  See the
  documentation for `strchop' for more information.

 SEE ALSO
   strchop, extract_element
--------------------------------------------------------------

strchop

 SYNOPSIS
   Chop or split a string into substrings.

 USAGE
   Integer_Type strchop (String_Type str, Integer_Type delim, Integer_Type quote)

 DESCRIPTION
     The `strchop' function may be used to split-up a string
     `str' that consists of substrings delimited by the character
     specified by `delim'.  If the integer `quote' is
     non-zero, it will be taken as a quote character for the
     delimiter.  The function returns to the stack a variable number
     of objects.  The top stack object represents the number of
     substrings that are on the stack.  For example,

             strchop ("apples,oranges,pears", ',', 0);

     will return the integer `3' to the top of the stack followed
     by the three strings:  `"apples"', `"oranges"', and
     `"pears"'.

 EXAMPLE

          define list_to_array (list)
          {
             variable n, i, s, a;
             n = strchop (list, ',', '\\');
             a = String_Type [n];
             for (i = 0; i < n; i++)
               a[i] = ();             % substring is on stack
             return a;
          }

     This defines a function that converts a comma-separated list of
     strings to string array containing the substrings.

 NOTES
   Since this function returns a variable number of values to the
   stack, it cannot chop up arbitrarily long strings that consist of
   many substrings.

   The function `strchopr' should be used if it is desired to have
   the string chopped-up in the reverse order.

 SEE ALSO
   strchopr, extract_element, create_delimited_string
--------------------------------------------------------------

strcmp

 SYNOPSIS
   Compare two strings

 USAGE
   Interpret strcmp (String_Type a, String_Type b)

 DESCRIPTION
   The `strcmp' function may be used to perform a case-sensitive
   string comparison, in the lexicongraphic sense, on strings `a' and
   `b'.  It returns 0 if the strings are identical, a negative integer
   if `a' is less than `b', or a positive integer if `a' is greater
   than `b'.

 EXAMPLE
   The `strup' function may be used to perform a case-insensitive
   string comparison:

       define case_insensitive_strcmp (a, b)
       {
         return strcmp (strup(a), strup(b));
       }


 NOTES
   One may also use one of the binary comparison operators, e.g.,
   `a > b'.

 SEE ALSO
   strup, strncmp
--------------------------------------------------------------

strcompress

 SYNOPSIS
   Remove excess whitespace characters from a string

 USAGE
   String_Type strtrim (String_Type s, String_Type white)

 DESCRIPTION
  The `strcompress' function compresses the string `s' by
  removing all repeated characters specified by by the characters of
  `white' from the interior of `s'.  In addition, it also
  removes all leading and trailing characters from `s' that are
  part of `white'.

 EXAMPLE
  The expression

       strcompress (",;apple,,cherry;,banana", ",;");

  returns the string @"apple,cherry;banana"@.

 SEE ALSO
   strtrim
--------------------------------------------------------------

string_match_nth

 SYNOPSIS
   Get the result of the last call to string_match

 USAGE
   (Integer_Type, Integer_Type) = string_match_nth(Integer_Type nth)

 DESCRIPTION
  The `string_match_nth' function returns two integers describing
  the result of the last call to `string_match'.  It returns both
  the offset into the string and the length of characters matches by
  the `nth' submatch.

  By convention, `nth' equal to zero means the entire match.
  Otherwise, `nth' must be an integer with a value 1 through 9,
  and refers to the set of characters matched by the `nth' regular
  expression enclosed by the pairs `\(, \)'.

 EXAMPLE
  Consider:

        variable matched, pos, len;
        matched = string_match("hello world", "\\([a-z]+\\) \\([a-z]+\\)", 1);
        if (matched) (pos, len) = string_match_nth(2);

  This will set `matched' to 1 since a match will be found at the
  first position, `pos' to 6 since `w' is offset 6 characters
  from the beginning of the string, and `len' to 5 since
  `"world"' is 5 characters long.

 NOTES
  The position offset is _not_ affected by the value of the offset
  parameter to the `string_match' function. For example, if the
  value of the last parameter to the `string_match' function had
  been 3, `pos' would still have been set to 6.

  Note also that `string_match_nth' returns the _offset_ from
  the beginning of the string and not the position of the match.

 SEE ALSO
   string_match
--------------------------------------------------------------

string_match

 SYNOPSIS
   Match a string against a regular expression

 USAGE
   Integer_Type string_match(String_Type str, String_Type pat, Integer_Type pos)

 DESCRIPTION
  The `string_match' function returns zero if `str' does not
  match regular expression specified by `pat'.  This function
  performs the match starting at position `pos' (numbered from 1) in
  `str'.  This function returns the position of the start of the
  match.  To find the exact substring actually matched, use
  `string_match_nth'.

 SEE ALSO
   string_match_nth, strcmp, strncmp
--------------------------------------------------------------

string

 SYNOPSIS
   Convert an object to a string representation.

 USAGE
   Integer_Type string (obj)

 DESCRIPTION
   The `string' function may be used to convert an object
   `obj' of any type to a string representation.
   For example, `string(12.34)' returns `"12.34"'.

 EXAMPLE

        define print_anything (anything)
        {
           message (string (anything));
        }


 NOTES
   This function is _not_ the same as typecasting to a `String_Type'
   using the `typecast' function.

 SEE ALSO
   typecast, sprintf, integer, char
--------------------------------------------------------------

strlen

 SYNOPSIS
   Compute the length of a string

 USAGE
   Integer_Type strlen (String_Type a)

 DESCRIPTION
   The `strlen' function may be used to compute the length of a string.

 EXAMPLE
   After execution of

      variable len = strlen ("hello");

   `len' will have a value of `5'.

 SEE ALSO
   substr
--------------------------------------------------------------

strlow

 SYNOPSIS
   Convert a string to lowercase

 USAGE
   String_Type strlow (String_Type s)

 DESCRIPTION
  The `strlow' function takes a string `s' and returns another
  string identical to `s' except that all upper case characters
  that comprise `s' will be converted to lower case.

 EXAMPLE
  The function

       define Strcmp (a, b)
       {
         return strcmp (strlow (a), strlow (b));
       }

  performs a case-insensitive comparison operation of two strings by
  converting them to lower case first.

 SEE ALSO
   strup, tolower, strcmp, strtrim, define_case
--------------------------------------------------------------

strncmp

 SYNOPSIS
   Compare the first few characters of two strings

 USAGE
   Integer_Type strncmp (String_Type a, String_Type b, Integer_Type n)

 DESCRIPTION
  This function behaves like `strcmp' except that it compares only the
  first `n' characters in the strings `a' and `b'.  See
  the documentation for `strcmp' for information about the return
  value.

 EXAMPLE
  The expression

        strcmp ("apple", "appliance", 3);

  will return zero since the first three characters match.

 SEE ALSO
   strcmp, strlen
--------------------------------------------------------------

strsub

 SYNOPSIS
   Replace a character with another in a string.

 USAGE
   String_Type strsub (String_Type s, Integer_Type pos, Integer_Type ch)

 DESCRIPTION
  The `strsub' character may be used to substitute the character
  `ch' for the character at position `pos' of the string
  `s'.  The resulting string is returned.

 EXAMPLE

       define replace_spaces_with_comma (s)
       {
         variable n;
         while (n = is_substr (s, " "), n) s = strsub (s, n, ',');
         return s;
       }


 NOTES
  The first character in the string `s' is specified by `pos'
  equal to 1.

 SEE ALSO
   is_substr, str_replace, strlen
--------------------------------------------------------------

strtrim

 SYNOPSIS
   Remove whitespace from the ends of a string

 USAGE
   String_Type strtrim (String_Type s)

 DESCRIPTION
  The `strtrim' function removes all leading and trailing whitespace
  characters from the string `s' and returns the result.  Whitespace is
  defined to be any combination of spaces, tabs, and newline characters.

 SEE ALSO
   int, strlow, strup, strcompress
--------------------------------------------------------------

strup

 SYNOPSIS
   Convert a string to uppercase

 USAGE
   String_Type strup (String_Type s)

 DESCRIPTION
  The `strup' function takes a string `s' and returns another
  string identical to `s' except that all lower case characters
  that comprise `s' will be converted to upper case.

 EXAMPLE
  The function

       define Strcmp (a, b)
       {
         return strcmp (strup (a), strup (b));
       }

  performs a case-insensitive comparison operation of two strings by
  converting them to upper case first.

 SEE ALSO
   strlow, toupper, strcmp, strtrim, define_case
--------------------------------------------------------------

substr

 SYNOPSIS
   Extract a substring from a string

 USAGE
   String_Type substr (String_Type s, Integer_Type n, Integer_Type len)

 DESCRIPTION
  The `substr' function returns a substring with length `len'
  of the string `s' beginning at position `n'.  If `len' is
  `-1', the entire length of the string `s' will be used for
  `len'.  The first character of `s' is given by `n' equal
  to 1.

 EXAMPLE

        substr ("To be or not to be", 7, 5);

  returns `"or no"'

 NOTES
    The expression `substr(s, n, 1)' is equivalent to the array
    index expression `s[n-1]'.

 SEE ALSO
   is_substr, strlen
--------------------------------------------------------------

system

 SYNOPSIS
   Execute a shell command

 USAGE
   Integer_Type system (String_Type cmd)

 DESCRIPTION
  The `system' function may be used to execute the string
  expression `cmd' in an inferior shell.  This function is an
  interface to the C `system' function which returns an
  implementation-defined result.   On Linux, it returns 127 if the
  inferior shell could not be invoked, -1 if there was some other
  error, otherwise it returns the return code for `cmd'.

 EXAMPLE

       define dir ()
       {
          () = system ("DIR");
       }

  displays a directory listing of the current directory under MSDOS or
  VMS.
--------------------------------------------------------------

time

 SYNOPSIS
   Return the current data and time as a string

 USAGE
   String time ();

 DESCRIPTION
  This function returns the current time as a string of the form:

       Sun Apr 21 13:34:17 1996


 SEE ALSO
   message, substr
--------------------------------------------------------------

tolower

 SYNOPSIS
   Convert a character to lowercase.

 USAGE
   Integer_Type lower (Integer_Type ch)

 DESCRIPTION
  This function takes an integer `ch' and returns its lowercase
  equivalent.

 SEE ALSO
   toupper, strup, strlow, int, char, define_case
--------------------------------------------------------------

toupper

 SYNOPSIS
   Convert a character to uppercase.

 USAGE
   Integer_Type toupper (Integer_Type ch)

 DESCRIPTION
  This function takes an integer `ch' and returns its uppercase
  equivalent.

 SEE ALSO
   tolower, strup, strlow, int, char, define_case
--------------------------------------------------------------

typecast

 SYNOPSIS
   Convert an object from one data type to another.

 USAGE
   typecast (x, new_type)

 DESCRIPTION
  The `typecast' function performs a generic typecast operation on
  `x' to convert it to `new_type'.  If `x' represents an
  array, the function will attempt to convert all elements of `x'
  to `new_type'.  Not all objects can be converted and a
  type-mismatch error will result upon failure.

 EXAMPLE

       define to_complex (x)
       {
          return typecast (x, Complex_Type);
       }

  defines a function that converts its argument, `x' to a complex
  number.

 SEE ALSO
   int, double, typeof
--------------------------------------------------------------

typeof

 SYNOPSIS
   Get the data type of an object.

 USAGE
   DataType_Type typeof (x)

 DESCRIPTION
  This function returns the data type of `x'.

 EXAMPLE

     if (Integer_Type == typeof (x)) print ("x is an integer");


 SEE ALSO
   array_info, _slang_guess_type, typecast
--------------------------------------------------------------

unix_ctime

 SYNOPSIS
   Convert a calendar time to a string

 USAGE
   String_Type unix_ctime(Integer_Type secs)

 DESCRIPTION
  This function returns a string representation of the time as given
  by `secs' seconds since 1970.

 SEE ALSO
   time
--------------------------------------------------------------

unix_kill

 SYNOPSIS
   Send a signal to a process

 USAGE
   Integer_Type unix_kill (Integer_Type pid, Integer_Type sig)

 DESCRIPTION
  This function may be used to send a signal given by the integer `sig'
  to the process specified by `pid'.  The function returns zero upon
  sucess and `-1' upon failure setting errno accordingly.

 EXAMPLE
  The `unix_kill' function may be used to determine whether or not
  a specific process exists:

       define process_exists (pid)
       {
          if (-1 == unix_kill (pid, 0))
            return 0;     % Process does not exist
          return 1;
       }


 NOTES
  The `unix_kill' function is not available on all systems.

 SEE ALSO
   getpid
--------------------------------------------------------------

verror

 SYNOPSIS
   Generate an error condition

 USAGE
   verror (String_Type fmt, ...)

 DESCRIPTION
  The `verror' function performs the same role as the `error'
  function.  The only difference is that instead of a single string
  argument, `verror' takes a sprintf style argument list.

 EXAMPLE

       define open_file (file)
       {
          variable fp;
   
          fp = fopen (file, "r");
          if (fp == NULL) verror ("Unable to open %s", file);
          return fp;
       }


 NOTES
  In the current implementation, strictly speaking, the `verror'
  function is not an intrinsic function.  Rather it is a predefined
  S-Lang function using a combination of `Sprintf' and
  `error'.

 SEE ALSO
   error, Sprintf, vmessage
--------------------------------------------------------------

