cref.txt

一个C格式的脚本处理函数库源代码,可让你的C程序具有执行C格式的脚本文件

 EXAMPLE
   The jed editor uses `SLang_run_hooks' to setup the mode of a
   buffer based on the filename extension of the file associated with
   the buffer:

         char *ext = get_filename_extension (filename);
         if (ext == NULL) return -1;
         if (-1 == SLang_run_hooks ("mode_hook", 1, ext))
           return -1;
         return 0;


 SEE ALSO
   SLang_is_defined, SLang_execute_function
--------------------------------------------------------------

SLang_execute_function

 SYNOPSIS
   Execute a user or intrinsic function

 USAGE
   int SLang_execute_function (char *fname)

 DESCRIPTION
   This function may be used to execute either a user-defined function
   or an intrinisic function.  The name of the function is specified
   by `fname'.  It returns zero if `fname' is not defined, or
   `1' if the function was successfully executed, or -1 upon
   error.

 NOTES
   The function `SLexecute_function' may be a better alternative
   for some uses.

 SEE ALSO
   SLang_run_hooks, SLexecute_function, SLang_is_defined
--------------------------------------------------------------

SLang_verror

 SYNOPSIS
   Signal an error with a message

 USAGE
   void SLang_verror (int code, char *fmt, ...);

 DESCRIPTION
   The `SLang_verror' function sets `SLang_Error' to
   `code' if `SLang_Error' is 0.  It also displays the error
   message implied by the `printf' variable argument list using
   `fmt' as the format.

 EXAMPLE

         FILE *open_file (char *file)
         {
            char *file = "my_file.dat";
   	 if (NULL == (fp = fopen (file, "w")))
   	   SLang_verror (SL_INTRINSIC_ERROR, "Unable to open %s", file);
   	 return fp;
         }


 SEE ALSO
   SLang_vmessage, SLang_exit_error
--------------------------------------------------------------

SLang_doerror

 SYNOPSIS
   Signal an error

 USAGE
   void SLang_doerror (char *err_str)

 DESCRIPTION
   The `SLang_doerror' function displays the string `err_str'
   to the error device and signals a S-Lang error.

 NOTES
   `SLang_doerror' is considered to obsolete.  Applications should
   use the `SLang_verror' function instead.

 SEE ALSO
   SLang_verror, SLang_exit_error
--------------------------------------------------------------

SLang_get_function

 SYNOPSIS
   Get a pointer to a slang function

 USAGE
   SLang_Name_Type *SLang_get_function (char *fname)

 DESCRIPTION
   This function returns a pointer to the internal S-Lang table entry
   of a function whose name is given by `fname'.  It returns
   `NULL' upon failure.  The value returned by this function can be
   used `SLexecute_function' to call the function directly
   from C.

 SEE ALSO
   SLexecute_function
--------------------------------------------------------------

SLexecute_function

 SYNOPSIS
   Execute a slang or intrinsic function

 USAGE
   int SLexecute_function (SLang_Name_Type *nt)

 DESCRIPTION
   The `SLexecute_function' allows an application to call the
   S-Lang function specified by the `SLang_Name_Type' pointer
   `nt'.  This parameter must be non `NULL' and must have been
   previously obtained by a call to `SLang_get_function'.

 EXAMPLE
   Consider the S-Lang function:

        define my_fun (x)
        {
           return x^2 - 2;
        }

   Suppose that it is desired to call this function many times with
   different values of x.  There are at least two ways to do this.
   The easiest way is to use `SLang_execute_function' by passing
   the string `"my_fun"'.  A better way that is much faster is to
   use `SLexecute_function':

         int sum_a_function (char *fname, double *result)
         {
            double sum, x, y;
   	 SLang_Name_Type *nt;
   
   	 if (NULL == (nt = SLang_get_function (fname)))
   	   return -1;
   	 
   	 sum = 0;
   	 for (x = 0; x < 10.0; x += 0.1)
   	   {
   	      SLang_start_arg_list ();
   	      if (-1 == SLang_push_double (x))
   	        return -1;
   	      SLang_end_arg_list ();
   	      if (-1 == SLexecute_function (nt))
   	        return -1;
   	      if (-1 == SLang_pop_double (&y, NULL, NULL))
   	        return -1;
   	      
   	      sum += y;
   	   }
   	 return sum;
         }

   Although not necessary in this case, `SLang_start_arg_list' and
   `SLang_end_arg_list' were used to provide the function with
   information about the number of parameters passed to it.

 SEE ALSO
   SLang_get_function, SLang_start_arg_list, SLang_end_arg_list
--------------------------------------------------------------

SLang_peek_at_stack

 SYNOPSIS
   Find the type of object on the top of the stack

 USAGE
   int SLang_peek_at_stack (void)

 DESCRIPTION
   The `SLang_peek_at_stack' function is useful for determining the
   data type of the object at the top of the stack.  It returns the
   data type, or -1 upon a stack-underflow error.  It does not remove
   anything from the stack.

 SEE ALSO
   SLang_pop_string, SLang_pop_integer
--------------------------------------------------------------

SLmake_string

 SYNOPSIS
   Duplicate a string

 USAGE
   char *SLmake_string (char *s)

 DESCRIPTION
   The `SLmake_string' function creates a new copy of the string
   `s', via `malloc', and returns it.  Upon failure it returns
   `NULL'.  Since the resulting string is malloced, it should be
   freed when nolonger needed via a call to either `free' or
   `SLfree'.

 NOTES
   `SLmake_string' should not be confused with the function
   `SLang_create_slstring', which performs a similar function.

 SEE ALSO
   SLmake_nstring, SLfree, SLmalloc, SLang_create_slstring
--------------------------------------------------------------

SLmake_nstring

 SYNOPSIS
   Duplicate a substring

 USAGE
   char *SLmake_nstring (char *s, unsigned int n)

 DESCRIPTION
   This function is like `SLmake_nstring' except that it creates a
   null terminated string formed from the first `n' characters of
   `s'.  Upon failure, it returns `NULL', otherwise it returns
   the new string.  When nolonger needed, the returned string should be
   freed with either `free' or `SLfree'.

 SEE ALSO
   SLmake_nstring, SLfree, SLang_create_nslstring
--------------------------------------------------------------

SLang_create_nslstring

 SYNOPSIS
   Created a hashed substring

 USAGE
   char *SLang_create_nslstring (char *s, unsigned int n)

 DESCRIPTION
   `SLang_create_nslstring' is like `SLang_create_slstring'
   except that only the first `n' characters of `s' are used to
   perform the string.  Upon error, it returns `NULL', otherwise it
   returns the hashed substring.  Such a string must be freed by the
   function `SLang_free_slstring'.

 NOTES
   Do not use `free' or `SLfree' to free the string returned by
   `SLang_create_slstring' or `SLang_create_nslstring'.  Also
   it is important that no attempt is made to modify the hashed string
   returned by either of these functions.  If one needs to modify a
   string, the functions `SLmake_string' or `SLmake_nstring'
   should be used instead.

 SEE ALSO
   SLang_free_slstring, SLang_create_slstring, SLmake_nstring
--------------------------------------------------------------

SLang_create_slstring

 SYNOPSIS
   Create a hashed string

 USAGE
   char *SLang_create_slstring (char *s)

 DESCRIPTION
   The `SLang_create_slstring' creates a copy of `s' and
   returns it as a hashed string.  Upon error, the function returns
   `NULL', otherwise it returns the hashed string.  Such a string
   must only be freed via the `SLang_free_slstring' function.

 NOTES
   Do not use `free' or `SLfree' to free the string returned by
   `SLang_create_slstring' or `SLang_create_nslstring'.  Also
   it is important that no attempt is made to modify the hashed string
   returned by either of these functions.  If one needs to modify a
   string, the functions `SLmake_string' or `SLmake_nstring'
   should be used instead.

 SEE ALSO
   SLang_free_slstring, SLang_create_nslstring, SLmake_string
--------------------------------------------------------------

SLang_free_slstring

 SYNOPSIS
   Free a hashed string

 USAGE
   void SLang_free_slstring (char *s)

 DESCRIPTION
   The `SLang_free_slstring' function is used to free a hashed
   string such as one returned by `SLang_create_slstring',
   `SLang_create_nslstring', or `SLang_create_static_slstring'.
   If `s' is `NULL', the routine does nothing.

 SEE ALSO
   SLang_create_slstring, SLang_create_nslstring, SLang_create_static_slstring
--------------------------------------------------------------

SLang_concat_slstrings

 SYNOPSIS
   Concatenate two strings to produce a hashed string

 USAGE
   char *SLang_concat_slstrings (char *a, char *b)

 DESCRIPTION
   The `SLang_concat_slstrings' function concatenates two strings,
   `a' and `b', and returns the result as a hashed string.
   Upon failure, `NULL' is returned.

 NOTES
   A hashed string can only be freed using `SLang_free_slstring'.
   Never use either `free' or `SLfree' to free a hashed string,
   otherwise memory corruption will result.

 SEE ALSO
   SLang_free_slstring, SLang_create_slstring
--------------------------------------------------------------

SLang_create_static_slstring

 SYNOPSIS
   Create a hashed string

 USAGE
   char *SLang_create_static_slstring (char *s_literal)

 DESCRIPTION
   The `SLang_create_static_slstring' creates a hashed string from
   the string literal `s_literal' and returns the result.  Upon
   failure it returns `NULL'.

 EXAMPLE

        char *create_hello (void)
        {
           return SLang_create_static_slstring ("hello");
        }


 NOTES
   This function should only be used with string literals.

 SEE ALSO
   SLang_create_slstring, SLang_create_nslstring
--------------------------------------------------------------

SLmalloc

 SYNOPSIS
   Allocate some memory

 USAGE
   char *SLmalloc (unsigned int nbytes)

 DESCRIPTION
   This function uses `malloc' to allocate `nbytes' of memory.
   Upon error it returns `NULL'; otherwise it returns a pointer to
   the allocated memory.  One should use `SLfree' to free the
   memory after used.

 SEE ALSO
   SLfree, SLrealloc, SLcalloc
--------------------------------------------------------------

SLcalloc

 SYNOPSIS
   Allocate some memory

 USAGE
   char *SLcalloc (unsigned int num_elem, unsigned int elem_size)

 DESCRIPTION
   This function uses `calloc' to allocate memory for
   `num_elem' objects with each of size `elem_size' and returns
   the result.  In addition, the newly allocated memory is zeroed. 
   Upon error it returns `NULL'; otherwise it returns a pointer to
   the allocated memory.  One should use `SLfree' to free the
   memory after used.

 SEE ALSO
   SLmalloc, SLrealloc, SLfree
--------------------------------------------------------------

SLfree

 SYNOPSIS
   Free some allocated memory

 USAGE
   void SLfree (char *ptr)

 DESCRIPTION
   The `SLfree' function uses `free' to deallocate the memory
   specified by `ptr', which may be `NULL' in which case the
   function does nothing.

 NOTES
   Never use this function to free a hashed string returned by one of
   the family of `slstring' functions, e.g.,
   `SLang_pop_slstring'.

 SEE ALSO
   SLmalloc, SLcalloc, SLrealloc, SLmake_string
--------------------------------------------------------------

SLrealloc

 SYNOPSIS
   Resize a dynamic memory block

 USAGE
   char *SLrealloc (char *ptr, unsigned int new_size)

 DESCRIPTION
   The `SLrealloc' uses the `realloc' function to resize the
   memory block specified by `ptr' to the new size `new_size'.
   If `ptr' is `NULL', the function call is equivalent to
   `SLmalloc(new_size)'.  Similarly, if `new_size' is zero,
   the function call is equivalent to `SLfree(ptr)'.  
   
   If the function fails, or if `new_size' is zero, `NULL' is
   returned.  Otherwise a pointer is returned to the (possibly moved)
   new block of memory.

 SEE ALSO
   SLfree, SLmalloc, SLcalloc
--------------------------------------------------------------

SLcurrent_time_string

 SYNOPSIS
   Get the current time as a string

 USAGE
   char *SLcurrent_time_string (void)

 DESCRIPTION
   The `SLcurrent_time_string' function uses the C library function
   `ctime' to obtain a string representation of the
   current date and time in the form

        "Wed Dec 10 12:50:28 1997"

   However, unlike the `ctime' function, a newline character is not
   present in the string.  
   
   The returned value points to a statically allocated memory block
   which may get overwritten on subsequent function calls.

 SEE ALSO
   SLmake_string
--------------------------------------------------------------

SLatoi

 SYNOPSIS
   Convert a text string to an integer

 USAGE
   int SLatoi(unsigned char *str

 DESCRIPTION
   `SLato