--- jed-0.99.16.orig/doc/txt/slangfun.txt
+++ jed-0.99.16/doc/txt/slangfun.txt
@@ -0,0 +1,5604 @@
+_reshape
+
+ SYNOPSIS
+   Copy an array to a new shape
+
+ USAGE
+   Array_Type _reshape (Array_Type A, Array_Type I)
+
+ DESCRIPTION
+   The `_reshape' function creates a copy of an array `A',
+   reshapes it to the form specified by `I' and returns the result.
+   The elements of `I' specify the new dimensions of the copy of
+   `A' and must be consistent with the number of elements `A'.
+
+ EXAMPLE
+   If `A' is a `100' element 1-d array, a new array 2-d array of 
+   size `20' by `5' may be created from the elements of `A'
+   by
+
+         A = _reshape (A, [20, 5]);
+
+   In this example, the original array was no longer needed.  Hence, it
+   is preferable to make use of the `__tmp' operator to avoid the
+   creation of a new array, i.e.,
+
+         A = _reshape (__tmp(A), [20,5]);
+
+
+ NOTES
+   The `reshape' function performs a similar function to
+   `_reshape'.  In fact, the `_reshape' function could have been
+   implemented via:
+
+        define _reshape (a, i)
+        {
+           a = @a;     % Make a new copy
+           reshape (a, i);
+           return a;
+        }
+
+
+ SEE ALSO
+   reshape, array_info
+--------------------------------------------------------------
+
+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];
+       }
+
+   For 1-d arrays, this information is more easily obtained from the
+   `length' function.
+
+ SEE ALSO
+   typeof, reshape, length, _reshape
+--------------------------------------------------------------
+
+array_map
+
+ SYNOPSIS
+   Apply a function to each element of an array
+
+ USAGE
+   Array_Type array_map (type, func, arg0, ...)
+
+       DataType_Type type;
+       Ref_Type func;
+
+
+ DESCRIPTION
+   The `array_map' function may be used to apply a function to each
+   element of an array and returns the result as an array of a
+   specified type.  The `type' parameter indicates what kind of
+   array should be returned and generally corresponds to the return
+   type of the function.  The `arg0' parameter should be an array
+   and is used to determine the dimensions of the resulting array.  If
+   any subsequent arguments correspond to an array of the same size,
+   then those array elements will be passed in parallel with the first
+   arrays arguments.
+
+ EXAMPLE
+   The first example illustrates how to apply the `strlen' function
+   to an array of strings:
+
+        S = ["", "Train", "Subway", "Car"];
+        L = array_map (Integer_Type, &strlen, S);
+
+   This is equivalent to:
+
+        S = ["", "Train", "Subway", "Car"];
+        L = Integer_Type [length (S)];
+        for (i = 0; i < length (S); i++) L[i] = strlen (S[i]);
+
+   
+   Now consider an example involving the `strcat' function:
+
+        files = ["slang", "slstring", "slarray"];
+   
+        exts = ".c";
+        cfiles = array_map (String_Type, &strcat, files, exts);
+        % ==> cfiles = ["slang.c slstring.c slarray.c"];
+   
+        exts =  [".a",".b",".c"];
+        xfiles = array_map (String_Type, &strcat, files, exts);
+        % ==> xfiles = ["slang.a", "slstring.b", "slarray.c"];
+
+
+ NOTES
+   Many mathemetical functions already work transparantly on arrays.
+   For example, the following two statements produce identical results:
+
+        B = sin (A);
+        B = array_map (Double_Type, &sin, A);
+
+
+ SEE ALSO
+   array_info, strlen, strcat, sin
+--------------------------------------------------------------
+
+array_sort
+
+ SYNOPSIS
+   Sort an array
+
+ USAGE
+   Array_Type array_sort (Array_Type a [, String_Type or Ref_Type f])
+
+ DESCRIPTION
+   `array_sort' sorts the array `a' into ascending order and
+   returns an integer array that represents the result of the sort. If
+   the optional second parameter `f' is present, the function
+   specified by `f' will be used to compare elements of `a';
+   otherwise, a built-in sorting function will be used.  
+   
+   If `f' is present, then it must be either a string representing
+   the name of the comparison function, or a reference to the function.
+   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.
+   
+   If the comparision function is not specified, then a built-in comparison
+   function appropriate for the data type will be used.  For example,
+   if `a' is an array of character strings, then the sort will be
+   preformed using `strcmp'.
+   
+   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);
+
+   Alternatively, one may use
+
+        variable I = array_sort (A);     
+
+   to use the built-in comparison function.
+   
+   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]'.
+
+ SEE ALSO
+   strcmp
+--------------------------------------------------------------
+
+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 setting 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
+   bstring_to_array, strlen, strcat
+--------------------------------------------------------------
+
+length
+
+ SYNOPSIS
+   Get the length of an object
+
+ USAGE
+   Integer_Type length (obj)
+
+ DESCRIPTION
+   The `length' function may be used to get information about the
+   length of an object.  For simple scalar data-types, it returns 1.
+   For arrays, it returns the total number of elements of the array.
+
+ NOTES
+   If `obj' is a string, `length' returns 1 because a
+   `String_Type' object is considered to be a scalar.  To get the
+   number of characters in a string, use the `strlen' function.
+
+ SEE ALSO
+   array_info, typeof, strlen
+--------------------------------------------------------------
+
+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.
+
+ NOTES
+   Since `reshape' modifies the shape of an array, and arrays are
+   treated as references, then all references to the array will
+   reference the new shape.  If this effect is unwanted, then use the 
+   `_reshape' function instead.
+
+ SEE ALSO
+   _reshape, array_info
+--------------------------------------------------------------
+
+transpose
+
+ SYNOPSIS
+   Transpose a 2d array
+
+ USAGE
+   Array_Type transpose (Array_Type a)
+
+ DESCRIPTION
+   The `transpose' function returns the transpose of a specified
+   array.  By definition, the transpose of an array, say one with
+   elements `a[i,j,...k]' is an array whose elements are
+   `a[k,...,j,i]'.
+
+ SEE ALSO
+   _reshape, reshape, array_info
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+assoc_delete_key
+
+ SYNOPSIS
+   Delete a key from an Associative Array
+
+ USAGE
+   assoc_delete_key (Assoc_Type a, String_Type k)
+
+ DESCRIPTION
+   The `assoc_delete_key' function deletes a key given by `k'
+   from the associative array `a'.  If the specified key does not
+   exist in `a', then this function has no effect.
+
+ SEE ALSO
+   assoc_key_exists, assoc_get_keys
+--------------------------------------------------------------
+
+assoc_get_keys
+
+ SYNOPSIS
+   Return all the key names of an Associative Array
+
+ USAGE
+   String_Type[] assoc_get_keys (Assoc_Type a)
+
+ DESCRIPTION
+   This function returns all the key names of an associative array
+   `a' as an ordinary one dimensional array of strings.  If the
+   associative array contains no keys, an empty array will be returned.
+
+ EXAMPLE
+   The following function computes the number of keys in an associative
+   array:
+
+         define get_num_elements (a)
+         {
+            return length (assoc_get_keys (a));
+         }
+
+
+ SEE ALSO
+   assoc_get_values, assoc_key_exists, assoc_delete_key, length
+--------------------------------------------------------------
+
+assoc_get_values
+
+ SYNOPSIS
+   Return all the values of an Associative Array
+
+ USAGE
+   Array_Type assoc_get_keys (Assoc_Type a)
+
+ DESCRIPTION
+   This function returns all the values in the associative array
+   `a' as an array of proper type.  If the associative array
+   contains no keys, an empty array will be returned.
+
+ EXAMPLE
+   Suppose that `a' is an associative array of type
+   `Integer_Type', i.e., it was created via
+
+         variable a = Assoc_Type[Integer_Type];
+
+   The the following may be used to print the values of the array in
+   ascending order:
+
+         static define int_sort_fun (x, y)
+         {
+            return sign (x - y);
+         }
+         define sort_and_print_values (a)
+         {
+            variable i, v;
+   	 
+   	 v = assoc_get_values (a);
+   	 i = array_sort (v, &int_sort_fun);
+   	 v = v[i];
+   	 foreach (v)
+   	   {
+   	      variable vi = ();
+   	      () = fprintf (stdout, "%d\n", vi);
+   	   }
+         }
+
+
+ SEE ALSO
+   assoc_get_values, assoc_key_exists, assoc_delete_key, array_sort
+--------------------------------------------------------------
+
+assoc_key_exists
+
+ SYNOPSIS
+   Check to see whether a key exists in an Associative Array
+
+ USAGE
+   Integer_Type assoc_key_exists (Assoc_Type a, String_Type k)
+
+ DESCRIPTION
+   The `assoc_key_exists' function may be used to determine whether
+   or not a specified key `k' exists in an associative array `a'.
+   It returns 1 if the key exists, or 0 if it does not.
+
+ SEE ALSO
+   assoc_get_keys, assoc_get_values, assoc_delete_key
+--------------------------------------------------------------
+
+array_to_bstring
+
+ SYNOPSIS
+   Convert an array to a binary string
+
+ USAGE
+   BString_Type array_to_bstring (Array_Type a)
+
+ DESCRIPTION
+   The `array_to_bstring' function returns the elements of an
+   array `a' as a binary string.
+
+ SEE ALSO
+   bstring_to_array, init_char_array
+--------------------------------------------------------------
+
+bstring_to_array
+
+ SYNOPSIS
+   Convert a binary string to an array of characters
+
+ USAGE
+   UChar_Type[] bstring_to_array (BString_Type b)
+
+ DESCRIPTION
+   The `bstring_to_array' function returns an array of unsigned
+   characters whose elements correspond to the characters in the
+   binary string.
+
+ SEE ALSO
+   array_to_bstring, init_char_array
+--------------------------------------------------------------
+
+bstrlen
+
+ SYNOPSIS
+   Get the length of a binary string
+
+ USAGE
+   UInt_Type bstrlen (BString_Type s)
+
+ DESCRIPTION
+   The `bstrlen' function may be used to obtain the length of a
+   binary string.  A binary string differs from an ordinary string (a C
+   string) in that a binary string may include null chracters.
+
+ EXAMPLE
+
+       variable s = "hello\0";
+       len = bstrlen (s);      % ==> len = 6
+       len = strlen (s);       % ==> len = 5
+
+
+ SEE ALSO
+   strlen, length
+--------------------------------------------------------------
+
+pack
+
+ SYNOPSIS
+   Pack objects into a binary string
+
+ USAGE
+   BString_Type pack (String_Type fmt, ...)
+
+ DESCRIPTION
+   The `pack' function combines zero or more the objects (represented
+   by the ellipses above) into a binary string acording to the format
+   string `fmt'.
+   
+   The format string consists of one or more data-type specification
+   characters, and each may be followed by an optional decimal length
+   specifier. Specifically, the data-types are specified according to
+   the following table:
+
+        c     char
+        C     unsigned char
+        h     short
+        H     unsigned short
+        i     int
+        I     unsigned int
+        l     long
+        L     unsigned long
+        j     16 bit int
+        J     16 unsigned int
+        k     32 bit int
+        K     32 bit unsigned int
+        f     float
+        d     double
+        F     32 bit float
+        D     64 bit float
+        s     character string, null padded
+        S     character string, space padded
+        x     a null pad character
+
+   A decimal length specifier may follow the data-type specifier.  With
+   the exception of the `s' and `S' specifiers, the length
+   specifier indicates how many objects of that data type are to be
+   packed or unpacked from the string.  When used with the `s' or
+   `S' specifiers, it indicates the field width to be used.  If the
+   length specifier is not present, the length defaults to one.
+   
+   With the exception of `c', `C', `s', `S', and
+   `x', each of these may be prefixed by a character that indicates
+   the byte-order of the object:
+
+        >    big-endian order (network order)
+        <    little-endian order
+        =    native byte-order
+
+   The default is to use native byte order.
+   
+   When unpacking via the `unpack' function, if the length
+   specifier is greater than one, then an array of that length will be
+   returned.  In addition, trailing whitespace and null character are
+   stripped when unpacking an object given by the `S' specifier.
+
+ EXAMPLE
+
+        a = pack ("cc", 'A', 'B');         % ==> a = "AB";
+        a = pack ("c2", 'A', 'B');         % ==> a = "AB";
+        a = pack ("xxcxxc", 'A', 'B');     % ==> a = "\0\0A\0\0B";
+        a = pack ("h2", 'A', 'B');         % ==> a = "\0A\0B" or "\0B\0A"
+        a = pack (">h2", 'A', 'B');        % ==> a = "\0\xA\0\xB"
+        a = pack ("<h2", 'A', 'B');        % ==> a = "\0B\0A"
+        a = pack ("s4", "AB", "CD");       % ==> a = "AB\0\0"
+        a = pack ("s4s2", "AB", "CD");     % ==> a = "AB\0\0CD"
+        a = pack ("S4", "AB", "CD");       % ==> a = "AB  "
+        a = pack ("S4S2", "AB", "CD");     % ==> a = "AB  CD"
+
+
+ SEE ALSO
+   unpack, sizeof_pack, pad_pack_format, sprintf
+--------------------------------------------------------------
+
+pad_pack_format
+
+ SYNOPSIS
+   Add padding to a pack format
+
+ USAGE
+   BString_Type pad_pack_format (String_Type fmt)
+
+ DESCRIPTION
+   The `pad_pack_format' function may be used to add the
+   appropriate padding to the format `fmt' such that the data types
+   specified by the format will be properly aligned for the system.
+   This is especially important when reading or writing files that
+   assume the native alignment.
+   
+   See the S-Lang User's Guide for more information about the use of
+   this function.
+
+ SEE ALSO
+   pack, unpack, sizeof_pack
+--------------------------------------------------------------
+
+sizeof_pack
+
+ SYNOPSIS
+   Compute the size implied by a pack format string
+
+ USAGE
+   UInt_Type sizeof_pack (String_Type fmt)
+
+ DESCRIPTION
+   The `sizeof_pack' function returns the size of the binary string
+   represented by the format string `fmt'.  This information may be
+   needed when reading a structure from a file.
+
+ NOTES
+
+ SEE ALSO
+   pack, unpack, pad_pack_format
+--------------------------------------------------------------
+
+unpack
+
+ SYNOPSIS
+   Unpack Objects from a Binary String
+
+ USAGE
+   (...) = unpack (String_Type fmt, BString_Type s)
+
+ DESCRIPTION
+   The `unpack' function unpacks objects from a binary string
+   `s' according to the format `fmt' and returns the objects to
+   the stack in the order in which they were unpacked.  See the
+   documentation of the `pack' function for details about the
+   format string.
+
+ EXAMPLE
+
+       (x,y) = unpack ("cc", "AB");         % ==> x = 'A', y = 'B'
+       x = unpack ("c2", "AB");             % ==> x = ['A', 'B']
+       x = unpack ("x<H", "\0\xAB\xCD");    % ==> x = 0xCDABuh
+       x = unpack ("xxs4", "a b c\0d e f");  % ==> x = "b c\0"
+       x = unpack ("xxS4", "a b c\0d e f");  % ==> x = "b c"
+
+
+ SEE ALSO
+   pack, sizeof_pack, pad_pack_format
+--------------------------------------------------------------
+
+_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
+--------------------------------------------------------------
+
+_debug_info
+
+ SYNOPSIS
+   Configure debugging information
+
+ USAGE
+   Integer_Type _debug_info
+
+ DESCRIPTION
+   The `_debug_info' variable controls whether or not extra code
+   should be generated for additional debugging and traceback
+   information.  Currently, if `_debug_info' is zero, no extra code
+   will be generated; otherwise extra code will be inserted into the
+   compiled bytecode for additional debugging data.
+   
+   The value of this variable is is local to each compilation unit and
+   setting its value in one unit has no effect upon its value in other
+   units.
+
+ EXAMPLE
+
+       _debug_info = 1;   % Enable debugging information
+
+
+ NOTES
+   Setting this variable to a non-zero value may slow down the
+   interpreter somewhat.
+
+ SEE ALSO
+   _traceback, _slangtrace
+--------------------------------------------------------------
+
+_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
+--------------------------------------------------------------
+
+_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
+--------------------------------------------------------------
+
+_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
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+listdir
+
+ SYNOPSIS
+   Get a list of the files in a directory
+
+ USAGE
+   String_Type[] listdir (String_Type dir)
+
+ DESCRIPTION
+   The `listdir' function returns the directory listing of all the
+   files in the specified directory `dir' as an array of strings.
+   It does not return the special files `".."' and `"."' as
+   part of the list.
+
+ SEE ALSO
+   stat_file, stat_is, length
+--------------------------------------------------------------
+
+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, readlink
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+readlink
+
+ SYNOPSIS
+   String_Type readlink (String_Type path)
+
+ USAGE
+   Get the value of a symbolic link
+
+ DESCRIPTION
+   The `readlink' function returns the value of a symbolic link and
+   returns it as a string.  Upon failure, NULL is returned and
+   `errno' set accordingly.
+
+ NOTES
+   Not all systems support this function.
+
+ SEE ALSO
+   lstat_file, stat_file, stat_is
+--------------------------------------------------------------
+
+remove
+
+ SYNOPSIS
+   Delete a file
+
+ USAGE
+   Integer_Type remove (String_Type file)
+
+ DESCRIPTION
+   The `remove' function deletes a file.  It returns 0 upon
+   success, or -1 upon error and sets `errno' accordingly.
+
+ SEE ALSO
+   rename, rmdir
+--------------------------------------------------------------
+
+rename
+
+ SYNOPSIS
+   Rename a file
+
+ USAGE
+   Integer_Type rename (String_Type old, String_Type new)
+
+ DESCRIPTION
+   The `rename' function renames a file from `old' to `new'
+   moving it between directories if necessary.  This function may fail
+   if the directories do not refer to the same file system.  It returns
+   0 upon success, or -1 upon error and sets `errno' accordingly.
+
+ SEE ALSO
+   remove, errno
+--------------------------------------------------------------
+
+rmdir
+
+ SYNOPSIS
+   Remove a directory
+
+ USAGE
+   Integer_Type rmdir (String_Type dir)
+
+ DESCRIPTION
+   The `rmdir' function deletes a specified directory.  It returns
+   0 upon success or -1 upon error and sets `errno' accordingly.
+
+ NOTES
+   The directory must be empty before it can be removed.
+
+ SEE ALSO
+   rename, remove, mkdir
+--------------------------------------------------------------
+
+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
+   Char_Type stat_is (String_Type type, Integer_Type st_mode)
+
+ DESCRIPTION
+   The `stat_is' function returns a signed character 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
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+get_import_module_path
+
+ SYNOPSIS
+   Get the search path for dynamically loadable objects
+
+ USAGE
+   String_Type get_import_module_path ()
+
+ DESCRIPTION
+   The `get_import_module_path' may be used to get the search path
+   for dynamically shared objects.  Such objects may be made accessable
+   to the application via the `import' function.
+
+ SEE ALSO
+   import, set_import_module_path
+--------------------------------------------------------------
+
+import
+
+ SYNOPSIS
+   Dynamically link to a specified module
+
+ USAGE
+   import (String_Type module [, String_Type namespace])
+
+ DESCRIPTION
+   The `import' function causes the run-time linker to dynamically
+   link to the shared object specified by the `module' parameter.
+   It seaches for the shared object as follows: First a search is
+   performed along all module paths specified by the application.  Then
+   a search is made along the paths defined via the
+   `set_import_module_path' function.  If not found, a search is
+   performed along the paths given by the `SLANG_MODULE_PATH'
+   environment variable.  Finally, a system dependent search is
+   performed (e.g., using the `LD_LIBRARY_PATH' environment
+   variable).
+   
+   The optional second parameter may be used to specify a namespace
+   for the intrinsic functions and variables of the module.  If this
+   parameter is not present, the intrinsic objects will be placed into
+   the global namespace.
+   
+   This function signals an error if the specified module is not found.
+
+ NOTES
+   The `import' function is not available on all systems.
+
+ SEE ALSO
+   set_import_module_path, use_namespace, current_namespace, getenv, evalfile
+--------------------------------------------------------------
+
+set_import_module_path
+
+ SYNOPSIS
+   Set the search path for dynamically loadable objects
+
+ USAGE
+   set_import_module_path (String_Type path_list)
+
+ DESCRIPTION
+   The `set_import_module_path' may be used to set the search path
+   for dynamically shared objects.  Such objects may be made accessable
+   to the application via the `import' function.
+   
+   The actual syntax for the specification of the set of paths will
+   vary according to the operating system.  Under Unix, a colon
+   character is used to separate paths in `path_list'.  For win32
+   systems a semi-colon is used.
+
+ SEE ALSO
+   import, get_import_module_path
+--------------------------------------------------------------
+
+_NARGS
+
+ SYNOPSIS
+   The number of parameters passed to a function
+
+ USAGE
+   Integer_Type _NARGS
+
+ EXAMPLE
+   This example uses the `_NARGS' variable to print the list of
+   values passed to the function:
+
+        define print_values ()
+        {
+           variable arg;
+           
+           if (_NARGS == 0)
+             {
+                message ("Nothing to print");
+                return;
+             }
+           foreach (__pop_args (_NARGS))
+             {
+                arg = ();
+                vmessage ("Argument value is: %S", arg.value);
+             }
+        }
+
+
+ SEE ALSO
+   __pop_args, __push_args, typeof
+--------------------------------------------------------------
+
+__get_defined_symbols
+
+ SYNOPSIS
+   Get the symbols defined by the preprocessor
+
+ USAGE
+   Integer_Type __get_defined_symbols ()
+
+ DESCRIPTION
+   The `__get_defined_symbols' functions is used to get the list of
+   all the symbols defined by the S-Lang preprocessor.  It pushes each
+   of the symbols on the stack followed by the number of items pushed.
+
+ SEE ALSO
+   is_defined, _apropos
+--------------------------------------------------------------
+
+__is_initialized
+
+ SYNOPSIS
+   Determine whether or not a variable has a value
+
+ USAGE
+   Integer_Type __is_initialized (Ref_Type r)
+
+ DESCRIPTION
+   This function returns non-zero of the object referenced by `r'
+   is initialized, i.e., whether it has a value.  It returns 0 if the
+   referenced object has not been initialized.
+
+ EXAMPLE
+   For example, the function:
+
+       define zero ()
+       {
+          variable f;
+          return __is_initialized (&f);
+       }
+
+   will always return zero, but
+
+       define one ()
+       {
+          variable f = 0;
+          return __is_initialized (&f);
+       }
+
+   will return one.
+
+ NOTES
+   It is easy to see why a reference to the variable must be passed to
+   `__is_initialized' and not the variable itself; otherwise, the
+   value of the variable would be passed and the variable may have no
+   value if it was not initialized.
+
+ SEE ALSO
+   __get_reference, __uninitialize, is_defined, typeof, eval
+--------------------------------------------------------------
+
+_apropos
+
+ SYNOPSIS
+   Generate a list of functions and variables
+
+ USAGE
+   Array_Type _apropos (String_Type ns, String_Type s, Integer_Type flags)
+
+ DESCRIPTION
+   The `_apropos' function may be used to get a list of all defined
+   objects in the namespace `ns' whose name matches the regular
+   expression `s' and whose type matches those specified by
+   `flags'.  It returns an array of strings representing the
+   matches. 
+   
+   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, a;
+         a = _apropos ("Global", s, 0xF);
+         
+         vmessage ("Found %d matches:", length (a));
+         foreach (a)
+           {
+              name = ();
+              message (name);
+           }
+       }
+
+   prints a list of all matches.
+
+ NOTES
+   If the namespace specifier `ns' is the empty string `""',
+   then the namespace will default to the static namespace of the
+   current compilation unit.
+
+ SEE ALSO
+   is_defined, sprintf
+--------------------------------------------------------------
+
+_function_name
+
+ SYNOPSIS
+   Returns the name of the currently executing function
+
+ USAGE
+   String_Type _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
+--------------------------------------------------------------
+
+_slang_doc_dir
+
+ SYNOPSIS
+   Installed documentation directory
+
+ USAGE
+   String_Type _slang_doc_dir;
+
+ DESCRIPTION
+   The `_slang_doc_dir' variable is a read-only whose value
+   specifies the installation location of the S-Lang documentation.
+
+ SEE ALSO
+   get_doc_string_from_file
+--------------------------------------------------------------
+
+_slang_version
+
+ SYNOPSIS
+   The S-Lang library version number
+
+ USAGE
+   Integer_Type _slang_version
+
+ DESCRIPTION
+   The `_slang_version' variable is read-only and and whose
+   value represents the number of the S-Lang library.
+
+ SEE ALSO
+   _slang_version_string
+--------------------------------------------------------------
+
+_slang_version_string
+
+ SYNOPSIS
+   The S-Lang library version number as a string
+
+ USAGE
+   String_Type _slang_version_string
+
+ DESCRIPTION
+   The `_slang_version_string' variable is read-only and whose
+   value represents the version number of the S-Lang library.
+
+ SEE ALSO
+   _slang_version
+--------------------------------------------------------------
+
+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
+
+ SEE ALSO
+   _slang_doc_dir
+--------------------------------------------------------------
+
+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, __get_reference, __is_initialized
+--------------------------------------------------------------
+
+Conj
+
+ SYNOPSIS
+   Compute the complex conjugate of a number
+
+ USAGE
+   z1 = Conj (z)
+
+ DESCRIPTION
+   The `Conj' function returns the complex conjugate of a number.
+   If its argument is an array, the `Conj' function will be applied to each
+   element and the result returned as an array.
+
+ SEE ALSO
+   Real, Imag, abs
+--------------------------------------------------------------
+
+Imag
+
+ SYNOPSIS
+   Compute the imaginary part of a number
+
+ USAGE
+   i = Imag (z)
+
+ DESCRIPTION
+   The `Imag' function returns the imaginary part of a number.
+   If its argument is an array, the `Imag' function will be applied to each
+   element and the result returned as an array.
+
+ SEE ALSO
+   Real, Conj, abs
+--------------------------------------------------------------
+
+Real
+
+ SYNOPSIS
+   Compute the real part of a number
+
+ USAGE
+   r = Real (z)
+
+ DESCRIPTION
+   The `Real' function returns the real part of a number. If its
+   argument is an array, the `Real' function will be applied to
+   each element and the result returned as an array.
+
+ SEE ALSO
+   Imag, Conj, abs
+--------------------------------------------------------------
+
+abs
+
+ SYNOPSIS
+   Compute the absolute value of a number
+
+ USAGE
+   y = abs(x)
+
+ DESCRIPTION
+   The `abs' function returns the absolute value of an arithmetic
+   type.  If its argument is a complex number (`Complex_Type'),
+   then it returns the modulus.  If the argument is an array, a new
+   array will be created whose elements are obtained from the original
+   array by using the `abs' function.
+
+ SEE ALSO
+   sign, sqr
+--------------------------------------------------------------
+
+acos
+
+ SYNOPSIS
+   Compute the arc-cosine of an number
+
+ USAGE
+   y = acos (x)
+
+ DESCRIPTION
+   The `acos' function computes the arc-cosine of a number and
+   returns the result as an array.  If its argument is an array, the
+   `acos' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+acosh
+
+ SYNOPSIS
+   Compute the inverse cosh of an number
+
+ USAGE
+   y = acosh (x)
+
+ DESCRIPTION
+   The `acosh' function computes the inverse cosh of a number and
+   returns the result as an array.  If its argument is an array, the
+   `acosh' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+asin
+
+ SYNOPSIS
+   Compute the arc-sine of an number
+
+ USAGE
+   y = asin (x)
+
+ DESCRIPTION
+   The `asin' function computes the arc-sine of a number and
+   returns the result as an array.  If its argument is an array, the
+   `asin' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+asinh
+
+ SYNOPSIS
+   Compute the inverse-sinh of an number
+
+ USAGE
+   y = asinh (x)
+
+ DESCRIPTION
+   The `asinh' function computes the inverse-sinh of a number and
+   returns the result as an array.  If its argument is an array, the
+   `asinh' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+atan
+
+ SYNOPSIS
+   Compute the arc-tangent of an number
+
+ USAGE
+   y = atan (x)
+
+ DESCRIPTION
+   The `atan' function computes the arc-tangent of a number and
+   returns the result as an array.  If its argument is an array, the
+   `atan' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+atanh
+
+ SYNOPSIS
+   Compute the inverse-tanh of an number
+
+ USAGE
+   y = atanh (x)
+
+ DESCRIPTION
+   The `atanh' function computes the inverse-tanh of a number and
+   returns the result as an array.  If its argument is an array, the
+   `atanh' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+cos
+
+ SYNOPSIS
+   Compute the cosine of an number
+
+ USAGE
+   y = cos (x)
+
+ DESCRIPTION
+   The `cos' function computes the cosine of a number and
+   returns the result as an array.  If its argument is an array, the
+   `cos' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+cosh
+
+ SYNOPSIS
+   Compute the hyperbolic cosine of an number
+
+ USAGE
+   y = cosh (x)
+
+ DESCRIPTION
+   The `cosh' function computes the hyperbolic cosine of a number and
+   returns the result as an array.  If its argument is an array, the
+   `cosh' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+exp
+
+ SYNOPSIS
+   Compute the exponential of an number
+
+ USAGE
+   y = exp (x)
+
+ DESCRIPTION
+   The `exp' function computes the exponential of a number and
+   returns the result as an array.  If its argument is an array, the
+   `exp' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+log
+
+ SYNOPSIS
+   Compute the logarithm of an number
+
+ USAGE
+   y = log (x)
+
+ DESCRIPTION
+   The `log' function computes the logarithm of a number and
+   returns the result as an array.  If its argument is an array, the
+   `log' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+log10
+
+ SYNOPSIS
+   Compute the base-10 logarithm of an number
+
+ USAGE
+   y = log10 (x)
+
+ DESCRIPTION
+   The `log10' function computes the base-10 logarithm of a number and
+   returns the result as an array.  If its argument is an array, the
+   `log10' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+mul2
+
+ SYNOPSIS
+   Multiply a number by 2
+
+ USAGE
+   y = mul2(x)
+
+ DESCRIPTION
+   The `mul2' function multiplies an arithmetic type by two and
+   returns the result.  If its argument is an array, a new array will
+   be created whose elements are obtained from the original array by
+   using the `mul2' function.
+
+ SEE ALSO
+   sqr, abs
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+sign
+
+ SYNOPSIS
+   Compute the sign of a number
+
+ USAGE
+   y = sign(x)
+
+ DESCRIPTION
+   The `sign' function returns the sign of an arithmetic type.  If
+   its argument is a complex number (`Complex_Type'), it returns
+   the sign of the imaginary part of the number. If the argument is an
+   array, a new array will be created whose elements are obtained from
+   the original array by using the `sign' function.
+   
+   When applied to a real number or an integer, the `sign' function
+   returns -1, 0, or `+1' according to whether the number is
+   less than zero, equal to zero, or greater than zero, respectively.
+
+ SEE ALSO
+   abs
+--------------------------------------------------------------
+
+sin
+
+ SYNOPSIS
+   Compute the sine of an number
+
+ USAGE
+   y = sin (x)
+
+ DESCRIPTION
+   The `sin' function computes the sine of a number and
+   returns the result as an array.  If its argument is an array, the
+   `sin' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+sinh
+
+ SYNOPSIS
+   Compute the hyperbolic sine of an number
+
+ USAGE
+   y = sinh (x)
+
+ DESCRIPTION
+   The `sinh' function computes the hyperbolic sine of a number and
+   returns the result as an array.  If its argument is an array, the
+   `sinh' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+sqr
+
+ SYNOPSIS
+   Compute the square of a number
+
+ USAGE
+   y = sqr(x)
+
+ DESCRIPTION
+   The `sqr' function returns the square of an arithmetic type.  If its
+   argument is a complex number (`Complex_Type'), then it returns
+   the square of the modulus.  If the argument is an array, a new array
+   will be created whose elements are obtained from the original array
+   by using the `sqr' function.
+
+ SEE ALSO
+   abs, mul2
+--------------------------------------------------------------
+
+sqrt
+
+ SYNOPSIS
+   Compute the square root of an number
+
+ USAGE
+   y = sqrt (x)
+
+ DESCRIPTION
+   The `sqrt' function computes the square root of a number and
+   returns the result as an array.  If its argument is an array, the
+   `sqrt' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   sqr, cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+tan
+
+ SYNOPSIS
+   Compute the tangent of an number
+
+ USAGE
+   y = tan (x)
+
+ DESCRIPTION
+   The `tan' function computes the tangent of a number and
+   returns the result as an array.  If its argument is an array, the
+   `tan' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+tanh
+
+ SYNOPSIS
+   Compute the hyperbolic tangent of an number
+
+ USAGE
+   y = tanh (x)
+
+ DESCRIPTION
+   The `tanh' function computes the hyperbolic tangent of a number and
+   returns the result as an array.  If its argument is an array, the
+   `tanh' function will be applied to each element and the result returned
+   as an array.
+
+ SEE ALSO
+   cos, atan, acosh, cosh
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+usage
+
+ SYNOPSIS
+   Generate a usage error
+
+ USAGE
+   usage (String_Type msg)
+
+ DESCRIPTION
+   The `usage' function generates a usage exception and displays
+   `msg' to the message device.
+
+ EXAMPLE
+   Suppose that some function `plot' plots an array of `x' and
+   `y' values.  The such a function could be written to issue a
+   usage message if the wrong number of arguments were passed:
+
+       define plot ()
+       { 
+          variable x, y;
+   
+          if (_NARGS != 2)
+            usage ("plot (x, y)");
+          
+          (x, y) = ();
+          % Now do the hard part
+             .
+   	  .
+       }
+
+
+ SEE ALSO
+   error, message
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+__get_reference
+
+ SYNOPSIS
+   Get a reference to a global object
+
+ USAGE
+   Ref_Type __get_reference (String_Type nm)
+
+ DESCRIPTION
+   This function returns a reference to a global variable or function
+   whose name is specified by `nm'.  If no such object exists, it
+   returns `NULL', otherwise it returns a reference.
+
+ EXAMPLE
+    For example, consider the function:
+
+       define runhooks (hook)
+       {
+          variable f;
+          f = __get_reference (hook);
+          if (f != NULL)
+            @f ();
+       }
+
+    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
+   is_defined, typeof, eval, autoload, __is_initialized, __uninitialize
+--------------------------------------------------------------
+
+__uninitialize
+
+ SYNOPSIS
+   Uninitialize a variable
+
+ USAGE
+   __uninitialize (Ref_Type x)
+
+ DESCRIPTION
+   The `__uninitialize' function may be used to uninitialize the
+   variable referenced by the parameter `x'.
+
+ EXAMPLE
+   The following two lines are equivalent:
+
+        () = __tmp(z);
+        __uninitialize (&z);
+
+
+ SEE ALSO
+   __tmp, __is_initialized
+--------------------------------------------------------------
+
+_auto_declare
+
+ SYNOPSIS
+   Set automatic variable declaration mode
+
+ USAGE
+   Integer_Type _auto_declare
+
+ DESCRIPTION
+   The `_auto_declare' may be used to have all undefined variables
+   implicitely declared as `static'.  If set to zero, any variable
+   must be declared witha `variable' declaration before it can be
+   used.  If set to one, then any undeclared variabled will be declared
+   as a `static' global variable.
+   
+   The `_auto_declare' variable is is local to each compilation unit and
+   setting its value in one unit has no effect upon its value in other
+   units.   The value of this variable has no effect upon the variables
+   in a function.
+
+ EXAMPLE
+   The following code will not compile if `X' not been
+   declared:
+
+       X = 1;
+
+   However, 
+
+       _auto_declare = 1;   % declare variables as static.
+       X = 1;
+
+   is equivalent to 
+
+       static variable X = 1;
+
+
+ NOTES
+   This variable should be used sparingly and is intended primarily for
+   interactive applications where one types S-Lang commands at a prompt.
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+implements
+
+ SYNOPSIS
+   Name a private namespace
+
+ USAGE
+   implements (String_Type name);
+
+ DESCRIPTION
+   The `implements' function may be used to name the private
+   namespace associated with the current compilation unit.  Doing so
+   will enable access to the members of the namespace from outside the
+   unit.  The name of the global namespace is `Global'.
+
+ EXAMPLE
+   Suppose that some file `t.sl' contains:
+
+        implements ("Ts_Private");
+        static define message (x)
+        {
+           Global->vmessage ("Ts_Private message: %s", x);
+        }
+        message ("hello");
+
+   will produce `"Ts_Private message: hello"'.  This `message'
+   function may be accessed from outside via:
+
+       Ts_Private->message ("hi");
+
+
+ NOTES
+   Since `message' is an intrinsic function, it is global and may
+   not be redefined in the global namespace.
+
+ SEE ALSO
+   use_namespace, current_namespace, import
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+use_namespace
+
+ SYNOPSIS
+   Change to another namespace
+
+ USAGE
+   use_namespace (String_Type name)
+
+ DESCRIPTION
+   The `use_namespace' function changes the current namespace to
+   the one specified by the parameter.  If the specified namespace
+   does not exist, an error will be generated.
+
+ SEE ALSO
+   implements, current_namespace, import
+--------------------------------------------------------------
+
+current_namespace
+
+ SYNOPSIS
+   Get the name of the current namespace
+
+ USAGE
+   String_Type current_namespace ()
+
+ DESCRIPTION
+   The `current_namespace' function returns the name of the
+   current namespace.  If the current namespace is anonymous, that is,
+   has not been given a name via the `implements' function, the
+   empty string `""' will be returned.
+
+ SEE ALSO
+   implements, use_namespace, import
+--------------------------------------------------------------
+
+path_basename
+
+ SYNOPSIS
+   Get the basename part of a pathname
+
+ USAGE
+   String_Type path_basename (String_Type path)
+
+ DESCRIPTION
+   The `path_basename' function returns the basename associated
+   with the `path' parameter.  The basename is the non-directory
+   part of the filename, e.g., on unix `c' is the basename of
+   `/a/b/c'.
+
+ SEE ALSO
+   path_dirname, path_extname, path_concat, path_is_absolute
+--------------------------------------------------------------
+
+path_concat
+
+ SYNOPSIS
+   Combine elements of a pathname
+
+ USAGE
+   String_Type path_concat (String_Type dir, String_Type basename)
+
+ DESCRIPTION
+   The `path_concat' function combines the arguments `dir' and
+   `basename' to produce a pathname.  For example, on unix is
+   `dir' is `x/y' and `basename' is `z', then the
+   function will return `x/y/z'.
+
+ SEE ALSO
+   path_dirname, path_basename, path_extname, path_is_absolute
+--------------------------------------------------------------
+
+path_dirname
+
+ SYNOPSIS
+   Get the directory name part of a pathname
+
+ USAGE
+   String_Type path_dirname (String_Type path)
+
+ DESCRIPTION
+   The `path_dirname' function returns the directory name
+   associated with a specified pathname.
+
+ NOTES
+   On systems that include a drive specifier as part of the pathname,
+   the value returned by this function will include the driver
+   specifier.
+
+ SEE ALSO
+   path_basename, path_extname, path_concat, path_is_absolute
+--------------------------------------------------------------
+
+path_extname
+
+ SYNOPSIS
+   Return the extension part of a pathname
+
+ USAGE
+   String_Type path_extname (String_Type path)
+
+ DESCRIPTION
+   The `path_extname' function returns the extension portion of a
+   specified pathname.  If an extension is present, this function will
+   also include the dot as part of the extension, i.e., if `path'
+   is `file.c', then this function returns `".c"'.  If no
+   extension is present, the function returns an empty string `""'.
+
+ NOTES
+   Under VMS, the file version number is not returned as part of the
+   extension.
+
+ SEE ALSO
+   path_sans_extname, path_dirname, path_basename, path_concat, path_is_absolute
+--------------------------------------------------------------
+
+path_is_absolute
+
+ SYNOPSIS
+   Determine whether or not a pathname is absolute
+
+ USAGE
+   Int_Type path_is_absolute (String_Type path)
+
+ DESCRIPTION
+   The `path_is_absolute' function will return non-zero is
+   `path' refers to an absolute pathname, otherwise it returns zero.
+
+ SEE ALSO
+   path_dirname, path_basename, path_extname, path_concat
+--------------------------------------------------------------
+
+path_sans_extname
+
+ SYNOPSIS
+   Strip the extension from a pathname
+
+ USAGE
+   String_Type path_sans_extname (String_Type path)
+
+ DESCRIPTION
+   The `path_sans_extname' function removes the file name extension
+   (including the dot) from the path and returns the result.
+
+ SEE ALSO
+   path_extname, path_basename, path_dirname, path_concat
+--------------------------------------------------------------
+
+close
+
+ SYNOPSIS
+   Close an open file descriptor
+
+ USAGE
+   Int_Type close (FD_Type fd)
+
+ DESCRIPTION
+   The `close' function is used to open file descriptor of type
+   `FD_Type'.  Upon success 0 is returned, otherwise the function
+   returns -1 and sets `errno' accordingly.
+
+ SEE ALSO
+   open, fclose, read, write
+--------------------------------------------------------------
+
+dup_fd
+
+ SYNOPSIS
+   Duplicate a file descriptor
+
+ USAGE
+   FD_Type dup_fd (FD_Type fd)
+
+ DESCRIPTION
+   The `dup_fd' function duplicates and file descriptor and returns
+   its duplicate.  If the function fails, NULL will be returned and
+   `errno' set accordingly.
+
+ NOTES
+   This function is essentually a wrapper around the POSIX `dup'
+   function.
+
+ SEE ALSO
+   open, close
+--------------------------------------------------------------
+
+fileno
+
+ SYNOPSIS
+   Convert a stdio File_Type object to a FD_Type descriptor
+
+ USAGE
+   FD_Type fileno (File_Type fp)
+
+ DESCRIPTION
+   The `fileno' function returns the `FD_Type' descriptor
+   associated with the `File_Type' file pointer.  Upon failure,
+   NULL is returned.
+
+ SEE ALSO
+   fopen, open, fclose, close, dup_fd
+--------------------------------------------------------------
+
+isatty
+
+ SYNOPSIS
+   Determine if an open file descriptor refers to a terminal
+
+ USAGE
+   Int_Type isatty (FD_Type or File_Type fd)
+
+ DESCRIPTION
+   This function returns 1 if the file descriptor `fd' refers to a
+   terminal; otherwise it returns 0.  The object `fd' may either
+   be a `File_Type' stdio descriptor or an `FD_Type' object.
+
+ SEE ALSO
+   fopen, fclose, fileno
+--------------------------------------------------------------
+
+lseek
+
+ SYNOPSIS
+   Reposition a file descriptor's file pointer
+
+ USAGE
+   Long_Type lseek (FD_Type fd, Long_Type ofs, int mode)
+
+        SEEK_SET   Set the offset to ofs
+        SEEK_CUR   Add ofs to the current offset
+        SEEK_END   Add ofs to the current file size
+
+
+ NOTES
+   Not all file descriptors are capable of supporting the seek
+   operation, e.g., a descriptor associated with a pipe.
+   
+   By using `SEEK_END' with a positive value of the `ofs'
+   parameter, it is possible to position the file pointer beyond the
+   current size of the file.
+
+ SEE ALSO
+   fseek, ftell, open, close
+--------------------------------------------------------------
+
+open
+
+ SYNOPSIS
+   Open a file
+
+ USAGE
+   FD_Type open (String_Type filename, Int_Type flags [,Int_Type mode])
+
+ DESCRIPTION
+   The `open' function attempts to open a file specified by the
+   `filename' parameter according to the `flags' parameter,
+   which must be one of the following values:
+
+        O_RDONLY   (read-only)
+        O_WRONLY   (write-only)
+        O_RDWR     (read/write)
+
+   In addition, `flags' may also be bitwise-or'd with any of the
+   following:
+
+        O_BINARY   (open the file in binary mode)
+        O_TEXT     (open the file in text mode)
+        O_CREAT    (create file if it does not exists)
+        O_EXCL     (fail if the file already exists)
+        O_NOCTTY   (do not make the device the controlling terminal)
+        O_TRUNC    (truncate the file if it exists)
+        O_APPEND   (open the file in append mode)
+        O_NONBLOCK (open the file in non-blocking mode)
+
+   If `O_CREAT' is used for the `flags' parameterm then the
+   `mode' parameter must be present. `mode' specifies the
+   permissions to use if a new file is created. The actual file
+   permissions will be affected by the process's `umask' via
+   `mode&~umask'.  The `mode' parameter's value is
+   constructed via bitwise-or of the following values:
+
+        S_IRWXU    (Owner has read/write/execute permission)
+        S_IRUSR    (Owner has read permission)
+        S_IWUSR    (Owner has write permission)
+        S_IXUSR    (Owner has execute permission)
+        S_IRWXG    (Group has read/write/execute permission)
+        S_IRGRP    (Group has read permission)
+        S_IWGRP    (Group has write permission)
+        S_IXGRP    (Group has execute permission)
+        S_IRWXO    (Others have read/write/execute permission)
+        S_IROTH    (Others have read permission)
+        S_IWOTH    (Others have write permission)
+        S_IXOTH    (Others have execute permission)
+
+   Upon success `open' returns a file descriptor object
+   (`FD_Type'), otherwise `NULL' is returned and `errno'
+   is set.
+
+ NOTES
+   If you are not familiar with the `open' system call, then it
+   is recommended that you use `fopen' instead.
+
+ SEE ALSO
+   fopen, close, read, write, stat_file
+--------------------------------------------------------------
+
+read
+
+ SYNOPSIS
+   Read from an open file descriptor
+
+ USAGE
+   UInt_Type read (FD_Type fd, Ref_Type buf, UInt_Type num)
+
+ DESCRIPTION
+   The `read' function attempts to read at most `num' bytes
+   into the variable indicated by `buf' from the open file
+   descriptor `fd'.  It returns the number of bytes read, or -1
+   and sets `errno' upon failure.  The number of bytes read may be
+   less than `num', and will be zero if an attempt is made to read
+   past the end of the file.
+
+ NOTES
+   `read' is a low-level function and may return -1 for a variety
+   of reasons.  For example, if non-blocking I/O has been specified for
+   the open file descriptor and no data is available for reading then
+   the function will return -1 and set `errno' to `EAGAIN'.
+
+ SEE ALSO
+   fread, open, close, write
+--------------------------------------------------------------
+
+write
+
+ SYNOPSIS
+   Write to an open file descriptor
+
+ USAGE
+   UInt_Type write (FD_Type fd, BString_Type buf)
+
+ DESCRIPTION
+   The `write' function attempts to write the bytes specified by
+   the `buf' parameter to the open file descriptor `fd'.  It
+   returns the number of bytes successfully written, or -1 and sets
+   `errno' upon failure.  The number of bytes written may be less
+   than `length(buf)'.
+
+ SEE ALSO
+   read, fwrite, open, close
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+getegid
+
+ SYNOPSIS
+   Get the effective group id
+
+ USAGE
+   Int_Type getegid ()
+
+ DESCRIPTION
+   The `getegid' function returns the effective group ID of the
+   current process.
+
+ NOTES
+   This function is not supported by all systems.
+
+ SEE ALSO
+   getgid, geteuid, setgid
+--------------------------------------------------------------
+
+geteuid
+
+ SYNOPSIS
+   Get the effective user-id of the current process
+
+ USAGE
+   Int_Type geteuid ()
+
+ DESCRIPTION
+   The `geteuid' function returns the effective user-id of the
+   current process.
+
+ NOTES
+   This function is not supported by all systems.
+
+ SEE ALSO
+   getuid, setuid, setgid
+--------------------------------------------------------------
+
+getgid
+
+ SYNOPSIS
+   Get the group id
+
+ USAGE
+   Integer_Type getgid ()
+
+ DESCRIPTION
+   The `getgid' function returns the real group id of the current
+   process.
+
+ NOTES
+   This function is not supported by all systems.
+
+ SEE ALSO
+   getpid, getppid
+--------------------------------------------------------------
+
+getpid
+
+ SYNOPSIS
+   Get the current process id
+
+ USAGE
+   Integer_Type getpid ()
+
+ DESCRIPTION
+   The `getpid' function returns the current process identification
+   number.
+
+ SEE ALSO
+   getppid, getgid
+--------------------------------------------------------------
+
+getppid
+
+ SYNOPSIS
+   Get the parent process id
+
+ USAGE
+   Integer_Type getppid ()
+
+ DESCRIPTION
+   The `getpid' function returns the process identification
+   number of the parent process.
+
+ NOTES
+   This function is not supported by all systems.
+
+ SEE ALSO
+   getpid, getgid
+--------------------------------------------------------------
+
+getuid
+
+ SYNOPSIS
+   Get the user-id of the current process
+
+ USAGE
+   Int_Type getuid ()
+
+ DESCRIPTION
+   The `getuid' function returns the user-id of the current
+   process.
+
+ NOTES
+   This function is not supported by all systems.
+
+ SEE ALSO
+   getuid, getegid
+--------------------------------------------------------------
+
+kill
+
+ SYNOPSIS
+   Send a signal to a process
+
+ USAGE
+   Integer_Type 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 `kill' function may be used to determine whether or not
+   a specific process exists:
+
+       define process_exists (pid)
+       {
+          if (-1 == kill (pid, 0))
+            return 0;     % Process does not exist
+          return 1;
+       }
+
+
+ NOTES
+   This function is not supported by all systems.
+
+ SEE ALSO
+   getpid
+--------------------------------------------------------------
+
+mkfifo
+
+ SYNOPSIS
+   Create a named pipe
+
+ USAGE
+   Int_Type mkfifo (String_Type name, Int_Type mode)
+
+ DESCRIPTION
+   The `mkfifo' attempts to create a named pipe with the specified
+   name and mode (modified by the process's umask).  The function
+   returns 0 upon success, or -1 and sets `errno' upon failure.
+
+ NOTES
+   Not all systems support the `mkfifo' function and even on
+   systems that do implement the `mkfifo' system call, the
+   underlying file system may not support the concept of a named pipe,
+   e.g, an NFS filesystem.
+
+ SEE ALSO
+   stat_file
+--------------------------------------------------------------
+
+setgid
+
+ SYNOPSIS
+   Set the group-id of the current process
+
+ USAGE
+   Int_Type setgid (Int_Type gid)
+
+ DESCRIPTION
+   The `setgid' function sets the effective group-id of the current
+   process.  It returns zero upon success, or -1 upon error and sets
+   `errno' appropriately.
+
+ NOTES
+   This function is not supported by all systems.
+
+ SEE ALSO
+   getgid, setuid
+--------------------------------------------------------------
+
+setpgid
+
+ SYNOPSIS
+   Set the process group-id
+
+ USAGE
+   Int_Type setpgid (Int_Type pid, Int_Type gid)
+
+ DESCRIPTION
+   The `setpgid' function sets the group-id `gid' of the
+   process whose process-id is `pid'.  If `pid' is 0, then the
+   current process-id will be used.  If `pgid' is 0, then the pid
+   of the affected process will be used.
+   
+   If successful zero will be returned, otherwise the function will
+   return -1 and set `errno' accordingly.
+
+ NOTES
+   This function is not supported by all systems.
+
+ SEE ALSO
+   setgid, setuid
+--------------------------------------------------------------
+
+setuid
+
+ SYNOPSIS
+   Set the user-id of the current process
+
+ USAGE
+   Int_Type setuid (Int_Type id)
+
+ DESCRIPTION
+   The `setuid' function sets the effective user-id of the current
+   process.  It returns zero upon success, or -1 upon error and sets
+   `errno' appropriately.
+
+ NOTES
+   This function is not supported by all systems.
+
+ SEE ALSO
+   setgid, setpgid, getuid, geteuid
+--------------------------------------------------------------
+
+sleep
+
+ SYNOPSIS
+   Pause for a specified number of seconds
+
+ USAGE
+   sleep (Double_Type n)
+
+ DESCRIPTION
+   The `sleep' function delays the current process for the
+   specified number of seconds.  If it is interrupted by a signal, it
+   will return prematurely.
+
+ NOTES
+   Not all system support sleeping for a fractional part of a second.
+--------------------------------------------------------------
+
+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.
+
+ SEE ALSO
+   popen, listdir
+--------------------------------------------------------------
+
+umask
+
+ SYNOPSIS
+   Set the file creation mask
+
+ USAGE
+   Int_Type umask (Int_Type m)
+
+ DESCRIPTION
+   The `umask' function sets the file creation mask to `m' and
+   returns the previous mask.
+
+ SEE ALSO
+   stat_file
+--------------------------------------------------------------
+
+uname
+
+ SYNOPSIS
+   Get the system name
+
+ USAGE
+   Struct_Tye uname ()
+
+ DESCRIPTION
+   The `uname' function returns a structure containing information
+   about the operating system.  The structure contains the following
+   fields:
+
+          sysname  (Name of the operating system)
+          nodename (Name of the node within the network)
+          release  (Release level of the OS)
+          version  (Current version of the release)
+          machine  (Name of the hardware)
+
+
+ NOTES
+   Not all systems support this function.
+
+ SEE ALSO
+   getenv, pack, unpack
+--------------------------------------------------------------
+
+__pop_args
+
+ SYNOPSIS
+   Remove n function arguments from the stack
+
+ USAGE
+   variable args = __pop_args(Integer_Type n);
+
+ DESCRIPTION
+   This function together with the companion function `__push_args'
+   is useful for passing the arguments of a function to another function.
+   `__pop_args' returns an array of `n' structures with a
+   single structure field called `value', which represents the value
+   of the argument.
+
+ EXAMPLE
+   Consider the following `print' function.  It prints all its
+   arguments to `stdout' separated by spaces:
+
+       define print ()
+       {
+          variable i;
+          variable args = __pop_args (_NARGS);
+      
+          for (i = 0; i < _NARGS; i++)
+            {
+               () = fputs (string (args[i].value), stdout);
+               () = fputs (" ", stdout);
+            }
+          () = fputs ("\n", stdout);
+          () = fflush (stdout);
+       }
+
+   Now consider the problem of defining a function called `ones'
+   that returns a multi-dimensional array with all the elements set to
+   1.  For example, `ones(10)' should return a 1-d array of ones,
+   whereas `ones(10,20)' should return a 10x20 array.
+
+       define ones ()
+       {
+         !if (_NARGS) return 1;
+         variable a;
+      
+         a = __pop_args (_NARGS);
+         return @Array_Type (Integer_Type, [__push_args (a)]) + 1;
+       }
+
+   Here, `__push_args' was used to push on the arguments passed to
+   the `ones' function onto the stack to be used when dereferencing
+   `Array_Type'.
+
+ SEE ALSO
+   __push_args, typeof, _pop_n
+--------------------------------------------------------------
+
+__push_args
+
+ SYNOPSIS
+   Remove n function arguments onto the stack
+
+ USAGE
+   __push_args (Struct_Type args);
+
+ DESCRIPTION
+   This function together with the companion function `__pop_args'
+   is useful for passing the arguments of one function to another.
+   See the desription of `__pop_args' for more information.
+
+ SEE ALSO
+   __pop_args, typeof, _pop_n
+--------------------------------------------------------------
+
+_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
+--------------------------------------------------------------
+
+_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
+--------------------------------------------------------------
+
+_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
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+exch
+
+ SYNOPSIS
+   Exchange two items on the stack
+
+ USAGE
+   exch ()
+
+ DESCRIPTION
+   The `exch' swaps the two top items on the stack.
+
+ SEE ALSO
+   pop, _stk_reverse, _stk_roll
+--------------------------------------------------------------
+
+pop
+
+ SYNOPSIS
+   Discard an item from the stack
+
+ USAGE
+   pop ()
+
+ DESCRIPTION
+   The `pop' function removes the top item from the stack.
+
+ SEE ALSO
+   _pop_n
+--------------------------------------------------------------
+
+clearerr
+
+ SYNOPSIS
+   Clear the error of a file stream
+
+ USAGE
+   clearerr (File_Type fp
+
+ DESCRIPTION
+   The `clearerr' function clears the error and end-of-file flags
+   associated with the open file stream `fp'.
+
+ SEE ALSO
+   ferror, feof, fopen
+--------------------------------------------------------------
+
+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, pclose, errno
+--------------------------------------------------------------
+
+fdopen
+
+ SYNOPSIS
+   Convert a FD_Type file descriptor to a stdio File_Type object
+
+ USAGE
+   File_Type fdopen (FD_Type, String_Type mode)
+
+ DESCRIPTION
+   The `fdopen' function creates and returns a stdio
+   `File_Type' object from the open `FD_Type'
+   descriptor `fd'.  The `mode' parameter corresponds to the
+   `mode' parameter of the `fopen' function and must be
+   consistent with the mode of the descriptor `fd'.  The function
+   returns NULL upon failure and sets `errno'.
+
+ NOTES
+   The `fclose' function does not close the `File_Type' object
+   returned from this function.  The underlying file object must be
+   closed by the `close' function.
+
+ SEE ALSO
+   fileno, fopen, open, close, fclose
+--------------------------------------------------------------
+
+feof
+
+ SYNOPSIS
+   Get the end-of-file status
+
+ USAGE
+   Integer_Type feof (File_Type fp)
+
+ DESCRIPTION
+   This function may be used to determine the state of the end-of-file
+   indicator of the open file descriptor `fp'.  It returns `0'
+   if the indicator is not set, or non-zero if it is.  The end-of-file
+   indicator may be cleared by the `clearerr' function.
+
+ SEE ALSO
+   ferror, clearerr, fopen
+--------------------------------------------------------------
+
+ferror
+
+ SYNOPSIS
+   Determine the error status of an open file descriptor
+
+ USAGE
+   Integer_Type ferror (File_Type fp)
+
+ DESCRIPTION
+   This function may be used to determine the state of the error
+   indicator of the open file descriptor `fp'.  It returns `0'
+   if the indicator is not set, or non-zero if it is.  The error
+   indicator may be cleared by the `clearerr' function.
+
+ SEE ALSO
+   feof, clearerr, fopen
+--------------------------------------------------------------
+
+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, fread, error
+--------------------------------------------------------------
+
+fgetslines
+
+ SYNOPSIS
+   Read all the lines from an open file
+
+ USAGE
+   String_Type[] fgetslines (File_Type fp)
+
+ DESCRIPTION
+   The `fgetslines' function returns all the remaining lines as an
+   array of strings in the file specified by the open file pointer
+   `fp'.  If the file is empty, an empty string array will be
+   returned.  The function returns `NULL' upon error.
+
+ EXAMPLE
+   The following function returns the number of lines in a file:
+
+       define count_lines_in_file (file)
+       {
+          variable fp, lines;
+   
+          fp = fopen (file, "r");
+          if (fp == NULL)
+            return -1;
+          
+          lines = fgetslines (fp);
+          if (lines == NULL)
+            return -1;
+          
+          return length (lines);
+       }
+
+   Note that the file was implicitly closed by the function.
+
+ NOTES
+   This function should not be used if the file contains many lines
+   since that would require that all the lines be read into memory.
+
+ SEE ALSO
+   fgets, fread, fopen
+--------------------------------------------------------------
+
+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, popen
+--------------------------------------------------------------
+
+fprintf
+
+ SYNOPSIS
+   Create and write a formatted string to a file
+
+ USAGE
+   Int_Type fprintf (File_Type fp, String_Type fmt, ...)
+
+ DESCRIPTION
+   `fprintf' formats the objects specified by the variable argument
+   list according to the format `fmt' and write the result to the
+   open file pointer `fp'.  
+   
+   The format string obeys the same syntax and semantics as the
+   `sprintf' format string.  See the description of the
+   `sprintf' function for more information.
+   
+   `fprintf' returns the number of characters written to the file,
+   or -1 upon error.
+
+ SEE ALSO
+   fputs, printf, fwrite, message
+--------------------------------------------------------------
+
+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.
+   
+   To write an object that contains embedded null characters, use the
+   `fwrite' function.
+
+ SEE ALSO
+   fclose, fopen, fgets, fwrite
+--------------------------------------------------------------
+
+fread
+
+ SYNOPSIS
+   Read binary data from a file
+
+ USAGE
+   UInt_Type fread (Ref_Type b, DataType_Type t, UInt_Type n, File_Type fp)
+
+ DESCRIPTION
+   The `fread' function may be used to read `n' objects of type
+   `t' from an open file pointer `fp'.  Upon success, it
+   returns the number of objects read from the file and places the
+   objects in the variable specified by `b'.  Upon error or end of
+   file, it returns `-1'.  If more than one object is read from the
+   file, those objects will be placed in an array of the appropriate
+   size.  The exception to this is when reading `Char_Type' or
+   `UChar_Type' objects from a file, in which case the data will be
+   returned as a BString_Type binary string.
+
+ EXAMPLE
+   The following example illustrates how to read 50 bytes from a file:
+
+        define read_50_bytes_from_file (file)
+        {
+           variable fp, n, buf;
+   	
+   	fp = fopen (file, "rb");
+   	if (fp == NULL) error ("Open failed");
+   	n = fread (&buf, Char_Type, 50, fp);
+   	if (n == -1)
+   	  error ("fread failed");
+   	() = fclose (fp);
+           return buf;
+        }
+
+
+ NOTES
+   Use the `pack' and `unpack' functions to read data with a
+   specific byte-ordering.
+
+ SEE ALSO
+   fwrite, fgets, fopen, pack, unpack
+--------------------------------------------------------------
+
+fseek
+
+ SYNOPSIS
+   Reposition a stream
+
+ USAGE
+   Integer_Type fseek (File_Type fp, Integer_Type ofs, Integer_Type whence
+
+ DESCRIPTION
+   The `fseek' function may be used to reposition the file position
+   pointer associated with the open file stream `fp'. Specifically,
+   it moves the pointer `ofs' bytes relative to the position
+   indicated by `whence'.  If whence is set to one of the symbolic
+   constants `SEEK_SET', `SEEK_CUR', or `SEEK_END', the
+   offset is relative to the start of the file, the current position
+   indicator, or end-of-file, respectively.
+   
+   The function return zero upon success, or -1 upon failure and sets
+   `errno' accordingly.
+
+ EXAMPLE
+    define rewind (fp)
+    {
+       if (0 == fseek (fp, 0, SEEK_SET)) return;
+       vmessage ("rewind failed, reason: %s", errno_string (errno));
+    }
+
+ NOTES
+   The current implementation uses an integer to specify the offset.
+   One some systems, a long integer may be required making this
+   function fail for very large files, i.e., files that are longer than
+   the maximum value of an integer.
+
+ SEE ALSO
+   ftell, fopen
+--------------------------------------------------------------
+
+ftell
+
+ SYNOPSIS
+   Obtain the current position in an open stream
+
+ USAGE
+   Integer_Type ftell (File_Type fp)
+
+ DESCRIPTION
+   The ftell function may be used to obtain the current position in the
+   stream associated with the open file pointer `fp'.  It returns
+   the position of the pointer measured in bytes from the beginning of
+   the file.  Upon error, it returns `-1' and sets `errno'.
+
+ SEE ALSO
+   fseek, fopen
+--------------------------------------------------------------
+
+fwrite
+
+ SYNOPSIS
+   Write binary data to a file
+
+ USAGE
+   UInt_Type fwrite (b, File_Type fp)
+
+ DESCRIPTION
+   The `fwrite' may be used to write the object represented by
+   `b' to an open file.  If `b' is a string or an array, the
+   function will attempt to write all elements of the object to the
+   file.  It returns the number of objects successfully written,
+   otherwise it returns -1 upon error and sets `errno'
+   accordingly.
+
+ EXAMPLE
+   The following example illustrates how to write an integer array to a
+   file.  In this example, `fp' is an open file descriptor:
+
+        variable a = [1:50];     % 50 element integer array
+        if (50 != fwrite (a, fp))
+          error ("fwrite failed");
+
+   Here is how to write the array one element at a time:
+
+        variable a = [1:50];
+        foreach (a)
+          {
+             variable ai = ();
+             if (1 != fwrite(ai, fp))
+   	    error ("fwrite failed");
+          }
+
+
+ NOTES
+   Not all data types may support the `fwrite' operation.  However,
+   it is supported by all vector, scalar, and string objects.
+
+ SEE ALSO
+   fread, fputs, fopen, pack, unpack
+--------------------------------------------------------------
+
+pclose
+
+ SYNOPSIS
+   Close an object opened with popen
+
+ USAGE
+   Integer_Type pclose (File_Type fp)
+
+ DESCRIPTION
+   The `pclose' function waits for the process associated with
+   `fp' to exit and the returns the exit status of the command.
+
+ SEE ALSO
+   pclose, fclose
+--------------------------------------------------------------
+
+popen
+
+ SYNOPSIS
+   Open a process
+
+ USAGE
+   File_Type popen (String_Type cmd, String_Type mode)
+
+ DESCRIPTION
+   The `popen' function executes a process specified by `cmd'
+   and opens a unidirectional pipe to the newly created process.  The
+   `mode' indicates whether or not the the pipe is open for reading
+   or writing.  Specifically, if `mode' is `"r"', then the
+   pipe is opened for reading, or if `mode' is `"w"', then the
+   pipe will be open for writing.
+   
+   Upon success, a `File_Type' pointer will be returned, otherwise
+   the function failed and `NULL' will be returned.
+
+ NOTES
+   This function is not available on all systems.
+
+ SEE ALSO
+   pclose, fopen
+--------------------------------------------------------------
+
+printf
+
+ SYNOPSIS
+   Create and write a formatted string to stdout
+
+ USAGE
+   Int_Type printf (String_Type fmt, ...)
+
+ DESCRIPTION
+   `fprintf' formats the objects specified by the variable argument
+   list according to the format `fmt' and write the result to
+   `stdout'.  This function is equivalent to `fprintf' used
+   with the `stdout' file pointer.  See `fprintf' for more
+   information.
+   
+   `printf' returns the number of characters written to the file,
+   or -1 upon error.
+
+ NOTES
+   Many C programmers do not check the return status of the
+   `printf' C library function.  Make sure that if you do not care
+   about whether or not the function succeeds, then code it as in the
+   following example:
+
+        () = printf ("%s laid %d eggs\n", chicken_name, num_egg);
+
+
+ SEE ALSO
+   fputs, printf, fwrite, message
+--------------------------------------------------------------
+
+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.
+   
+   The format string is a C library `sprintf' style format
+   descriptor.  Briefly, the format string may consist of ordinary
+   characters (not including the `%' character), which are copied
+   into the output string as-is, and a conversion specification
+   introduced by the `%' character.  The `%' character must be
+   followed by at least one other character to specify the conversion:
+
+        s    value is a string
+        f    value is a floating point number
+        e    print float in exponential form, e.g., 2.345e08
+        g    print float as e or g, depending upon its value
+        c    value is an ascii character
+        %    print the percent character
+        d    print a signed decimal integer
+        u    print an unsigned decimal integer
+        o    print an integer as octal
+        X    print an integer as hexadecimal
+        S    convert value to a string and format as string
+
+   Note that `%S' is a S-Lang extension which will cause the value
+   to be formatted as string.  In fact, `sprintf("%S",x)' is
+   equivalent to `sprintf("%s",string(x))'.
+
+        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, sscanf
+--------------------------------------------------------------
+
+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
+   strjoin, is_list_element, extract_element, strchop, strcat
+--------------------------------------------------------------
+
+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;
+        }
+
+   
+   Alternatively, the `strchop' function may be more useful.  In
+   fact, `extract_element' may be expressed in terms of the
+   function `strchop' as
+
+       define extract_element (list, nth, delim)
+       {
+          list = strchop(list, delim, 0);
+          if (nth >= length (list))
+            return NULL;
+          else
+            return list[nth];
+       }
+
+   and the `num_elements' function used above may be recoded more
+   simply as:
+
+       define num_elements (list, delim)
+       {
+          return length (strchop (length, delim, 0));
+       }
+
+
+ SEE ALSO
+   is_list_element, is_substr, strtok, strchop, create_delimited_string
+--------------------------------------------------------------
+
+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, strreplace
+--------------------------------------------------------------
+
+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
+--------------------------------------------------------------
+
+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, sscanf, vmessage
+--------------------------------------------------------------
+
+sscanf
+
+ SYNOPSIS
+   Parse a formatted string
+
+ USAGE
+   Int_Type sscanf (s, fmt, r1, ... rN)
+
+       String_Type s, fmt;
+       Ref_Type r1, ..., rN
+
+
+ DESCRIPTION
+   The `sscanf' function parses the string `s' according to the
+   format `fmt' and sets the variables whose references are given by
+   `r1', ..., `rN'.  The function returns the number of
+   references assigned, or `-1' upon error.
+   
+   The format string `fmt' consists of ordinary characters and
+   conversion specifiers.  A conversion specifier begins with the
+   special character `%' and is described more fully below.  A white
+   space character in the format string matches any amount of whitespace
+   in the input string.  Parsing of the format string stops whenever a
+   match fails.
+   
+   The `%' is used to denote a conversion specifier whose general
+   form is given by `%[*][width][type]format' where the brackets
+   indicate optional items.  If `*' is present, then the conversion
+   will be performed by no assignment to a reference will be made.  The
+   `width' specifier specifies the maximum field width to use for
+   the conversion.  The `type' modifier is used to indicate size of
+   the object, e.g., a short integer, as follows. 
+   
+   If _type_ is given as the character `h', then if the format
+   conversion is for an integer (`dioux'), the object assigned will
+   be a short integer.  If _type_ is `l', then the conversion
+   will be to a long integer for integer conversions, or to a double
+   precession floating point number for floating point conversions.
+   
+   The format specifier is a character that specifies the conversion:
+
+          %     Matches a literal percent character.  No assigment is
+                performed.
+          d     Matches a signed decimal integer.
+          D     Matches a long decimal integer (equiv to `ld')
+          u     Matches an unsigned decimal integer
+          U     Matches an unsigned long decimal integer (equiv to `lu')
+          i     Matches either a hexidecimal integer, decimal integer, or 
+                octal integer.
+          I     Equivalent to `li'.
+          x     Matches a hexidecimal integer.
+          X     Matches a long hexidecimal integer (same as `lx').
+          e,f,g Matches a decimal floating point number (Float_Type).
+          E,F,G Matches a double precision floating point number, same as `lf'.
+          s     Matches a string of non-whitespace characters (String_Type).
+          c     Matches one character.  If width is given, width
+                characters are matched.
+          n     Assigns the number of characters scanned so far.
+          [...] Matches zero or more characters from the set of characters
+                enclosed by the square brackets.  If '^' is given as the
+                first character, then the complement set is matched. 
+
+
+ EXAMPLE
+   Suppose that `s' is `"Coffee: (3,4,12.4)"'.  Then
+
+       n = sscanf (s, "%[a-zA-Z]: (%d,%d,%lf)", &item, &x, &y, &z);
+
+   will set `n' to 4, `item' to `"Coffee"', `x' to 3,
+   `y' to 4, and `z' to the double precision number
+   `12.4'.  However,
+
+       n = sscanf (s, "%s: (%d,%d,%lf)", &item, &x, &y, &z);
+
+   will set `n' to 1, `item' to `"Coffee:"' and the
+   remaining variables will not be assigned.
+
+ SEE ALSO
+   sprintf, unpack, string, atof, int, integer, string_match
+--------------------------------------------------------------
+
+str_delete_chars
+
+ SYNOPSIS
+   Delete characters from a string
+
+ USAGE
+   String_Type str_delete_chars (String_Type str, String_Type del_set
+
+ DESCRIPTION
+   This function may be used to delete the set of characters specified
+   by `del_set' from the string `str'.  The result is returned.
+
+ EXAMPLE
+
+       str = str_delete_chars (str, "^A-Za-z");
+
+   will remove all characters except `A-Z' and `a-z' from
+   `str'.
+--------------------------------------------------------------
+
+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.
+
+ NOTES
+   This function has been superceded by `strreplace'.
+
+ SEE ALSO
+   strreplace
+--------------------------------------------------------------
+
+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 strings
+
+ USAGE
+   String_Type strcat (String_Type a_1, ...,  String_Type a_N)
+
+ DESCRIPTION
+   The `strcat' function concatenates its N `String_Type'
+   arguments `a_1', ... `a_N' together and returns the result.
+
+ EXAMPLE
+
+       strcat ("Hello", " ", "World");
+
+   produces the string `"Hello World"'.
+
+ NOTES
+   This function is equivalent to the binary operation `a_1+...+a_N'.
+   However, `strcat' is much faster making it the preferred method
+   to concatenate string.
+
+ SEE ALSO
+   sprintf, create_delimited_string
+--------------------------------------------------------------
+
+strchop
+
+ SYNOPSIS
+   Chop or split a string into substrings.
+
+ USAGE
+   String_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 the substrings as an array.
+
+ EXAMPLE
+   The following function illustrates how to sort a comma separated
+   list of strings:
+
+        define sort_string_list (a)
+        { 
+           variable i, b, c;
+           b = strchop (a, ',', 0);
+           
+           i = array_sort (b, &strcmp);
+           b = b[i];   % rearrange
+           
+           % Convert array back into comma separated form
+           return strjoin (b, ",");
+        }
+
+
+ NOTES
+   The semantics of this `strchop' and `strchopr' have been
+   changed since version 1.2.x of the interpreter.  Old versions of
+   these functions returned the values on the stack, which meant that
+   one could not 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, strjoin, strtok
+--------------------------------------------------------------
+
+strchopr
+
+ SYNOPSIS
+   Chop or split a string into substrings.
+
+ USAGE
+   String_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, strtok, strjoin
+--------------------------------------------------------------
+
+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 strcompress (String_Type s, String_Type white)
+
+ DESCRIPTION
+   The `strcompress' function compresses the string `s' by
+   replacing a sequence of one or more characters from the set
+   `white' by the first character of `white'. 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, strtrans
+--------------------------------------------------------------
+
+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_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
+--------------------------------------------------------------
+
+strjoin
+
+ SYNOPSIS
+   Concatenate elements of a string array
+
+ USAGE
+   String_Type strjoin (Array_Type a, String_Type delim)
+
+ DESCRIPTION
+   The `strjoin' function operates on an array of strings by joining
+   successive elements together separated with a delimiter `delim'.
+   If `delim' is the empty string `""', then the result will
+   simply be the concatenation of the elements.
+
+ EXAMPLE
+   Suppose that
+
+         days = ["Sun","Mon","Tue","Wed","Thu","Fri","Sat","Sun"];
+
+   Then `strjoin (days,"+")' will produce
+   `"Sun+Mon+Tue+Wed+Thu+Fri+Sat+Sun"'.  Similarly,
+   `strjoin (["","",""], "X")' will produce `"XX"'.
+
+ SEE ALSO
+   create_delimited_string, strchop, strcat
+--------------------------------------------------------------
+
+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
+   bstrlen, length, 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
+--------------------------------------------------------------
+
+strreplace
+
+ SYNOPSIS
+   Replace one or more substrings
+
+ USAGE
+   (new, n) = strreplace (a, b, c, max_n)
+
+      String_Type a, b, c, rep;
+      Int_Type n, max_n;
+
+
+ DESCRIPTION
+   The `strreplace' function may be used to replace one or more
+   occurances of `b' in `a' with `c'.  If the integer
+   `max_n' is positive, then the first `max_n' occurances of
+   `b' in `a' will be replaced.  Otherwise, if `max_n' is
+   negative, then the last `abs(max_n)' occurances will be replaced.
+   
+   The function returns the resulting string and an integer indicating
+   how many replacements were made.
+
+ EXAMPLE
+   The following function illustrates how `strreplace' may be used
+   to remove all occurances of a specified substring
+
+     define delete_substrings (a, b)
+     {
+        (a, ) = strreplace (a, b, "", strlen (a));
+        return a;
+     }
+
+
+ SEE ALSO
+   is_substr, strsub, strtrim, strtrans, str_delete_chars
+--------------------------------------------------------------
+
+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;
+       }
+
+   For uses such as this, the `strtrans' function is a better choice.
+
+ NOTES
+   The first character in the string `s' is specified by `pos'
+   equal to 1.
+
+ SEE ALSO
+   is_substr, strreplace, strlen
+--------------------------------------------------------------
+
+strtok
+
+ SYNOPSIS
+   Extract tokens from a string
+
+ USAGE
+   String_Type[] strtok (String_Type str [,String_Type white])
+
+ DESCRIPTION
+   `strtok' breaks the string `str' into a series of tokens and
+   returns them as an array of strings.  If the second parameter
+   `white' is present, then it specifies the set of characters that
+   are to be regarded as whitespace when extracting the tokens, and may
+   consist of the whitespace characters or a range of such characters.
+   If the first character of `white' is `'^'', then the
+   whitespace characters consist of all characters except those in
+   `white'. For example, if `white' is `" \t\n,;."',
+   then those characters specifiy the whitespace characters.  However,
+   if `white' is given by `"^a-zA-Z0-9_"', then any character
+   is a whitespace character except those in the ranges `a-z',
+   `A-Z', `0-9', and the underscore character.
+   
+   If the second parameter is not present, then it defaults to 
+   `" \t\r\n\f"'.
+
+ EXAMPLE
+   The following example may be used to count the words in a text file:
+
+       define count_words (file)
+       {
+          variable fp, line, count;
+          
+          fp = fopen (file, "r");
+          if