  The [1mS-Lang [22mC Library Reference
  John E. Davis, jed@jedsoft.org
  Aug 4, 2008
  ____________________________________________________________


  [1m1.  Functions dealing with UTF-8 encoded strings[0m

  [1m1.1.  SLutf8_skip_char[0m

      [1mSynopsis[0m
        Skip past a UTF-8 encoded character

      [1mUsage[0m
        SLuchar_Type *SLutf8_skip_char (SLuchar_Type *u, SLuchar_Type
        *umax)

      [1mDescription[0m
        The SLutf8_skip_char function returns a pointer to the character
        immediately following the UTF-8 encoded character at u.  It will
        make no attempt to examine the bytes at the position umax and
        beyond.  If the bytes at u do not represent a valid or legal
        UTF-8 encoded sequence, a pointer to the byte following u will
        be returned.

      [1mNotes[0m
        Unicode combining characters are treated as distinct characters
        by this function.

      [1mSee Also[0m
        SLutf8_skip_chars, SLutf8_bskip_char, SLutf8_strlen

  [1m1.2.  SLutf8_skip_chars[0m

      [1mSynopsis[0m
        Skip past a specified number of characters in a UTF-8 encoded
        string

      [1mUsage[0m
        SLuchar_Type *SLutf8_skip_chars (u, umax, num, dnum,
        ignore_combining)

              SLuchar_Type *u, *umax;
              unsigned int num;
              unsigned int *dnum;
              int ignore_combining;

      [1mDescription[0m
        This functions attempts to skip forward past num UTF-8 encoded
        characters at u returning the actual number skipped via the
        parameter dnum.  It will make no attempt to examine bytes at
        umax and beyond.  Unicode combining characters will not be
        counted if ignore_combining is non-zero, otherwise they will be
        treated as distinct characters.  If the input contains an
        invalid or illegal UTF-8 sequence, then each byte in the
        sequence will be treated as a single character.

      [1mSee Also[0m
        SLutf8_skip_char, SLutf8_bskip_chars

  [1m1.3.  SLutf8_bskip_char[0m

      [1mSynopsis[0m
        Skip backward past a UTF-8 encoded character

      [1mUsage[0m
        SLuchar_Type *SLutf8_bskip_char (SLuchar_Type *umin,
        SLuchar_Type *u)

      [1mDescription[0m
        The SLutf8_bskip_char skips backward to the start of the UTF-8
        encoded character immediately before the position u.  The
        function will make no attempt to examine characters before the
        position umin.  UTF-8 combining characters are treated as
        distinct characters.

      [1mSee Also[0m
        SLutf8_bskip_chars, SLutf8_skip_char

  [1m1.4.  SLutf8_bskip_chars[0m

      [1mSynopsis[0m
        Skip backward past a specified number of UTF-8 encoded
        characters

      [1mUsage[0m
        SLuchar_Type *SLutf8_bskip_chars (umin, u, num, dnum,
        ignore_combining)

        SLuchar_Type *umin, *u;
        unsigned int num;
        unsigned int *dnum;
        int ignore_combining;

      [1mDescription[0m
        This functions attempts to skip backward past num UTF-8 encoded
        characters occuring immediately before u.  It returns the the
        actual number skipped via the parameter dnum.  No attempt will
        be made to examine the bytes occuring before umin.  Unicode
        combining characters will not be counted if ignore_combining is
        non-zero, otherwise they will be treated as distinct characters.
        If the input contains an invalid or illegal UTF-8 sequence, then
        each byte in the sequence will be treated as a single character.

      [1mSee Also[0m
        SLutf8_skip_char, SLutf8_bskip_chars

  [1m1.5.  SLutf8_decode[0m

      [1mSynopsis[0m
        Decode a UTF-8 encoded character sequence

      [1mUsage[0m
        SLuchar_Type *SLutf8_decode (u, umax, w, nconsumedp

             SLuchar_Type *u, *umax;
             SLwchar_Type *w;
             unsigned int *nconsumedp;

      [1mDescription[0m
        The SLutf8_decode function decodes the UTF-8 encoded character
        occuring at u and returns the decoded character via the
        parameter w.  No attempt will be made to examine the bytes at
        umax and beyond.  If the parameter nconsumedp is non-NULL, then
        the number of bytes consumed by the function will be returned to
        it.  If the sequence at u is invalid or illegal, the function
        will return NULL and with the number of bytes consumed by the
        function equal to the size of the invalid sequence.  Otherwise
        the function will return a pointer to byte following encoded
        sequence.

      [1mSee Also[0m
        SLutf8_decode, SLutf8_strlen, SLutf8_skip_char

  [1m1.6.  SLutf8_encode[0m

      [1mSynopsis[0m
        UTF-8 encode a character

      [1mUsage[0m
        SLuchar_Type *SLutf8_encode (w, u, ulen)
             SLwchar_Type w;
             SLuchar_Type *u;
             unsigned int ulen;

      [1mDescription[0m
        This function UTF-8 encodes the Unicode character represented by
        w and stored the encoded representation in the buffer of size
        ulen bytes at u.  The function will return NULL if the size of
        the buffer is too small to represent the UTF-8 encoded
        character, otherwise it will return a pointer to the byte
        following encoded representation.

      [1mNotes[0m
        This function does not null terminate the resulting byte
        sequence.  The function SLutf8_encode_null_terminate may be used
        for that purpose.

        To guarantee that the buffer is large enough to hold the encoded
        bytes, its size should be at least SLUTF8_MAX_BLEN bytes.

        The function will encode illegal Unicode characters, i.e.,
        characters in the range 0xD800-0xFFFF (the UTF-16 surrogates)
        and 0xFFFE-0xFFFF.

      [1mSee Also[0m
        SLutf8_decode, SLutf8_encode_bytes, SLutf8_encode_null_terminate

  [1m1.7.  SLutf8_strlen[0m

      [1mSynopsis[0m
        Determine the number of characters in a UTF-8 sequence

      [1mUsage[0m
        unsigned int SLutf8_strlen (SLuchar_Type *s, int
        ignore_combining)

      [1mDescription[0m
        This function may be used to determine the number of characters
        represented by the null-terminated UTF-8 byte sequence.  If the
        ignore_combining parameter is non-zero, then Unicode combining
        characters will not be counted.

      [1mSee Also[0m
        SLutf8_skip_chars, SLutf8_decode

  [1m1.8.  SLutf8_extract_utf8_char[0m

      [1mSynopsis[0m
        Extract a UTF-8 encoded character

      [1mUsage[0m
        SLuchar_Type *SLutf8_extract_utf8_char (u, umax, buf)

             SLuchar_Type *u, *umax, *buf;

      [1mDescription[0m
        This function extracts the bytes representing UTF-8 encoded
        character at u and places them in the buffer buf, and then null
        terminates the result.  The buffer is assumed to consist of at
        least SLUTF8_MAX_BLEN+1 bytes, where the extra byte may be
        necessary for null termination.  No attempt will be made to
        examine the characters at umax and beyond.  If the byte-sequence
        at u is an illegal or invalid UTF-8 sequence, then the byte at u
        will be copied to the buffer.  The function returns a pointer to
        the byte following copied bytes.

      [1mNotes[0m
        One may think of this function as the single byte analogue of

               if (u < umax)
                 {
                    buf[0] = *u++;
                    buf[1] = 0;
                 }

      [1mSee Also[0m
        SLutf8_decode, SLutf8_skip_char

  [1m1.9.  SLutf8_encode_null_terminate[0m

      [1mSynopsis[0m
        UTF-8 encode a character and null terminate the result

      [1mUsage[0m
        SLuchar_Type *SLutf8_encode_null_terminate (w, buf)

             SLwchar_Type w;
             SLuchar_Type *buf;

      [1mDescription[0m
        This function has the same functionality as SLutf8_encode,
        except that it also null terminates the encoded sequences.  The
        buffer buf, where the encoded sequence is placed, is assumed to
        consist of at least SLUTF8_MAX_BLEN+1 bytes.

      [1mSee Also[0m
        SLutf8_encode

  [1m1.10.  SLutf8_strup[0m

      [1mSynopsis[0m
        Uppercase a UTF-8 encoded string

      [1mUsage[0m
        SLuchar_Type *SLutf8_strup (SLuchar_Type *u, SLuchar_Type *umax)

      [1mDescription[0m
        The SLutf8_strup function returns the uppercase equivalent of
        UTF-8 encoded sequence of umax-u bytes at u.  The result will be
        returned as a null-terminated SLstring and should be freed with
        SLang_free_slstring when it is nolonger needed.  If the function
        encounters an invalid of illegal byte sequence, then the byte-
        sequence will be copied as as-is.

      [1mSee Also[0m
        SLutf8_strlow, SLwchar_toupper

  [1m1.11.  SLutf8_strlo[0m

      [1mSynopsis[0m
        Lowercase a UTF-8 encoded string

      [1mUsage[0m
        SLuchar_Type *SLutf8_strlo (SLuchar_Type *u, SLuchar_Type *umax)

      [1mDescription[0m
        The SLutf8_strlo function returns the lowercase equivalent of
        UTF-8 encoded sequence of umax-u bytes at u.  The result will be
        returned as a null-terminated SLstring and should be freed with
        SLang_free_slstring when it is nolonger needed.  If the function
        encounters an invalid of illegal byte sequence, then the byte-
        sequence will be copied as as-is.

      [1mSee Also[0m
        SLutf8_strlow, SLwchar_toupper

  [1m1.12.  SLutf8_subst_wchar[0m

      [1mSynopsis[0m
        Replace a character in a UTF-8 encoded string

      [1mUsage[0m
        SLstr_Type *SLutf8_subst_wchar (u, umax, wch,
        nth,ignore_combining)

             SLuchar_Type *u, *umax;
             SLwchar_Type wch;
             unsigned int nth;
             int ignore_combining;

      [1mDescription[0m
        The SLutf8_subst_wchar function replaces the UTF-8 sequence
        representing the nth character of u by the UTF-8 representation
        of the character wch.  If the value of the ignore_combining
        parameter is non-zero, then combining characters will not be
        counted when computing the position of the nth character.  In
        addition, if the nth character contains any combining
        characters, then the byte-sequence associated with those
        characters will also be replaced.

        Since the byte sequence representing wch could be longer than
        the sequence of the nth character, the function returns a new
        copy of the resulting string as an SLSTRING.  Hence, the calling
        function should call SLang_free_slstring when the result is
        nolonger needed.

      [1mSee Also[0m
        SLutf8_strup, SLutf8_strlow, SLutf8_skip_chars, SLutf8_strlen

  [1m1.13.  SLutf8_compare[0m

      [1mSynopsis[0m
        Compare two UTF-8 encoded sequences

      [1mUsage[0m
        int SLutf8_compare (a, amax, b, bmax, nchars, case_sensitive)

             SLuchar_Type *a, *amax;
             SLuchar_Type *b, *bmax;
             unsigned int nchars;
             int case_sensitive;

      [1mDescription[0m
        This function compares nchars of one UTF-8 encoded character
        sequence to another by performing a character by character
        comparison.  The function returns 0, +1, or -1 according to
        whether the string a is is equal to, greater than, or less than
        the string at b.  At most nchars characters will be tested.  The
        parameters amax and bmax serve as upper boundaries of the
        strings a and b, resp.

        If the value of the case_sensitive parameter is non-zero, then a
        case-sensitive comparison will be performed, otherwise
        characters will be compared in a case-insensitive manner.

      [1mNotes[0m
        For case-sensitive comparisons, this function is analogous to
        the standard C library's strncmp function.  However,
        SLutf8_compare can also cope with invalid or illegal UTF-8
        sequences.

      [1mSee Also[0m
        SLutf8_strup, SLutf8_strlen, SLutf8_strlen

  [1m2.  Character classification functions[0m

  [1m2.1.  SLwchar_toupper[0m

      [1mSynopsis[0m
        Uppercase a Unicode character

      [1mUsage[0m
        SLwchar_Type SLwchar_toupper (SLwchar_Type wc)

      [1mDescription[0m
        SLwchar_toupper returns the uppercase equivalent of the
        specified character.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_tolower, SLwchar_isupper, SLutf8_strup

  [1m2.2.  SLwchar_tolower[0m

      [1mSynopsis[0m
        Lowercase a Unicode character

      [1mUsage[0m
        SLwchar_Type SLwchar_tolower (SLwchar_Type wc)

      [1mDescription[0m
        SLwchar_tolower returns the lowercase equivalent of the
        specified character.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_toupper, SLwchar_islower, SLutf8_strlow

  [1m2.3.  SLwchar_wcwidth[0m

      [1mSynopsis[0m
        Determine the displayable width of a wide character

      [1mUsage[0m
        int SLwchar_wcwidth (SLwchar_Type wc)

      [1mDescription[0m
        This function returns the number of columns necessary to display
        the specified Unicode character.  Combining characters are meant
        to be combined with other characters and, as such, have 0 width.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_isspace, SLwchar_iscntrl

  [1m2.4.  SLwchar_isalnum[0m

      [1mSynopsis[0m
        Determine if a Unicode character is alphanumeric
      [1mUsage[0m
        int SLwchar_isalnum (SLwchar_Type wc)

      [1mDescription[0m
        SLwchar_isalnum returns a non-zero value if the Unicode
        character is alphanumeric, otherwise it returns 0.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_isalpha, SLwchar_isdigit, SLwchar_iscntrl

  [1m2.5.  SLwchar_isalpha[0m

      [1mSynopsis[0m
        Determine if a Unicode character is an alphabetic character

      [1mUsage[0m
        int SLwchar_isalpha (SLwchar_Type wc)

      [1mDescription[0m
        SLwchar_isalpha returns a non-zero value if the Unicode
        character is alphabetic, otherwise it returns 0.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_isalnum, SLwchar_isalpha, SLwchar_isdigit,
        SLwchar_iscntrl

  [1m2.6.  SLwchar_isblank[0m

      [1mSynopsis[0m
        Determine if a Unicode character is a blank

      [1mUsage[0m
        int SLwchar_isblank (SLwchar_Type wc)

      [1mDescription[0m
        SLwchar_isblank returns a non-zero value if the Unicode
        character is a blank one (space or tab), otherwise it returns 0.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_isspace, SLwchar_isalpha, SLwchar_isdigit,
        SLwchar_iscntrl

  [1m2.7.  SLwchar_iscntrl[0m

      [1mSynopsis[0m
        Determine if a Unicode character is a control character

      [1mUsage[0m
        int SLwchar_iscntrl (SLwchar_Type wc)

      [1mDescription[0m
        SLwchar_isblank returns a non-zero value if the Unicode
        character is a control character, otherwise it returns 0.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_isspace, SLwchar_isalpha, SLwchar_isdigit,
        SLwchar_isprint

  [1m2.8.  SLwchar_isdigit[0m

      [1mSynopsis[0m
        Determine if a Unicode character is a digit

      [1mUsage[0m
        int SLwchar_isdigit (SLwchar_Type wc)

      [1mDescription[0m
        This function returns a non-zero value if the specified Unicode
        character is a digit, otherwise it returns 0.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_isspace, SLwchar_isalpha, SLwchar_isxdigit,
        SLwchar_isprint

  [1m2.9.  SLwchar_isgraph[0m

      [1mSynopsis[0m
        Determine if a non-space Unicode character is printable

      [1mUsage[0m
        int SLwchar_isgraph (SLwchar_Type wc)

      [1mDescription[0m
        This function returns a non-zero value if the specified Unicode
        character is a non-space printable character, otherwise it
        returns 0.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_isspace, SLwchar_isalpha, SLwchar_isdigit,
        SLwchar_isprint

  [1m2.10.  SLwchar_islower[0m

      [1mSynopsis[0m
        Determine if a Unicode character is alphanumeric

      [1mUsage[0m
        int SLwchar_islower (SLwchar_Type wc)

      [1mDescription[0m
        This function returns a non-zero value if the specified Unicode
        character is a lowercase one, otherwise it returns 0.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_isupper, SLwchar_isspace, SLwchar_isalpha,
        SLwchar_isdigit, SLwchar_iscntrl

  [1m2.11.  SLwchar_isprint[0m

      [1mSynopsis[0m
        Determine if a Unicode character is printable

      [1mUsage[0m
        int SLwchar_isprint (SLwchar_Type wc)

      [1mDescription[0m
        This function returns a non-zero value if the specified Unicode
        character is a printable one (includes space), otherwise it
        returns 0.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_isgraph, SLwchar_isspace, SLwchar_isalpha,
        SLwchar_isdigit

  [1m2.12.  SLwchar_ispunct[0m

      [1mSynopsis[0m
        Determine if a Unicode character is a punctuation character

      [1mUsage[0m
        int SLwchar_ispunct (SLwchar_Type wc)

      [1mDescription[0m
        This function returns a non-zero value if the specified Unicode
        character is a punctuation character, otherwise it returns 0.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_isspace, SLwchar_isalpha, SLwchar_isdigit,
        SLwchar_isprint

  [1m2.13.  SLwchar_isspace[0m

      [1mSynopsis[0m
        Determine if a Unicode character is a whitespace character

      [1mUsage[0m
        int SLwchar_isspace (SLwchar_Type wc)

      [1mDescription[0m
        This function returns a non-zero value if the specified Unicode
        character is a whitespace character, otherwise it returns 0.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_isblank, SLwchar_isalpha, SLwchar_isdigit,
        SLwchar_ispunct

  [1m2.14.  SLwchar_isupper[0m

      [1mSynopsis[0m
        Determine if a Unicode character is uppercase

      [1mUsage[0m
        int SLwchar_isupper (SLwchar_Type wc)

      [1mDescription[0m
        This function returns a non-zero value if the specified Unicode
        character is an uppercase character, otherwise it returns 0.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_islower, SLwchar_isspace, SLwchar_isalpha,
        SLwchar_isdigit

  [1m2.15.  SLwchar_isxdigit[0m

      [1mSynopsis[0m
        Determine if a Unicode character is a hexidecimal digit

      [1mUsage[0m
        int SLwchar_isxdigit (SLwchar_Type wc)

      [1mDescription[0m
        This function returns a non-zero value if the specified Unicode
        character is a hexadecimal digit character, otherwise it returns
        0.

      [1mNotes[0m
        If the library is not in UTF-8 mode, then the current locale
        will be used.

      [1mSee Also[0m
        SLwchar_isdigit, SLwchar_isspace, SLwchar_isalpha,
        SLwchar_ispunct

  [1m3.  SLsearch interface Functions[0m

  [1m3.1.  SLsearch_new[0m

      [1mSynopsis[0m
        Create an SLsearch_Type object

      [1mUsage[0m
        SLsearch_Type *SLsearch_new (SLuchar_Type *key, int
        search_flags)

      [1mDescription[0m
        The SLsearch_new function instantiates  an SLsearch_Type object
        for use in ordinary searches (non-regular expression) by the
        functions in the SLsearch interface.  The first argument key is
        a pointer to a null terminated string that specifies the
        character string to be searched.  This character string may not
        contain any embedded null characters.

        The second argument search_flags is used to specify how the
        search is to be performed.  It is a bit-mapped integer whose
        value is constructed by the bitwise-or of zero or more of the
        following:

             SLSEARCH_CASELESS
               The search shall be performed in a case-insensitive manner.

             SLSEARCH_UTF8
               Both the search string and the text to be searched is UTF-8
               encoded.

     Upon sucess, the function returns the newly created object, and
     NULL otherwise.  When the search object is nolonger needed, it
     should be freed via the SLsearch_delete function.

      [1mSee Also[0m
        SLsearch_delete, SLsearch_forward, SLsearch_backward

  [1m3.2.  SLsearch_delete[0m

      [1mSynopsis[0m
        Free the memory associated with a SLsearch_Type object

      [1mUsage[0m
        SLsearch_delete (SLsearch_Type *)

      [1mDescription[0m
        This function should be called to free the memory associated
        with a SLsearch_Type object created by the SLsearch_new
        function.  Failure to do so will result in a memory leak.

      [1mSee Also[0m
        SLsearch_new, SLsearch_forward, SLsearch_backward

  [1m3.3.  SLsearch_forward[0m

      [1mSynopsis[0m
        Search forward in a buffer

      [1mUsage[0m
        SLuchar_Type SLsearch_forward (st, pmin, pmax)

             SLsearch_Type *st;
             SLuchar_Type *pmin, *pmax;

      [1mDescription[0m
        The SLsearch_forward function searches forward in the buffer
        defined by the pointers pmin and pmax.  The starting point for
        the search is at the beginning of the buffer at pmin.  At no
        point will the bytes at pmax and beyond be examined.  The first
        parameter st, obtained by a prior call to SLsearch_new,
        specifies the object to found.  be found from a previous call to
        SLsearch_new.

        If the object was found, the pointer to the beginning of it will
        be returned.  Otherwise, SLsearch_forward will return NULL.  The
        length of the object may be obtained via the SLsearch_match_len
        function.

      [1mNotes[0m
        This function uses the Boyer-Moore search algorithm when
        possible.

      [1mSee Also[0m
        SLsearch_new, SLsearch_backward, SLsearch_delete,
        SLsearch_match_len

  [1m3.4.  SLsearch_backward[0m

      [1mSynopsis[0m
        Search backward in a buffer

      [1mUsage[0m
        SLuchar_Type SLsearch_forward (st, pmin, pstart, pmax)

             SLsearch_Type *st;
             SLuchar_Type *pmin, *pstart, *pmax;

      [1mDescription[0m
        The SLsearch_forward function searches backward in the buffer
        defined by the pointers pmin and pmax.  The starting point for
        the search is at the position pstart. At no point will the bytes
        at pmax and beyond be examined.  The first parameter st,
        obtained by a prior call to SLsearch_new, specifies the object
        to found.

        If the object was found, the pointer to the beginning of it will
        be returned.  Otherwise, SLsearch_forward will return NULL.  The
        length of the object may be obtained via the SLsearch_match_len
        function.

      [1mNotes[0m
        This function uses the Boyer-Moore search algorithm when
        possible.

        It is possible for the end of match to appear after the point
        where the search began (pstart).

      [1mSee Also[0m
        SLsearch_new, SLsearch_forward, SLsearch_delete,
        SLsearch_match_len

  [1m3.5.  SLsearch_match_len[0m

      [1mSynopsis[0m
        Get the length of the previous match

      [1mUsage[0m
        unsigned int SLsearch_match_len (SLsearch_Type *st)

      [1mDescription[0m
        The SLsearch_match_len function returns the length of the match
        from the most recent search involving the specified
        SLsearch_Type object.  If the most recent search was
        unsuccessful, the function will return 0.

      [1mSee Also[0m
        SLsearch_forward, SLsearch_backward, SLsearch_new,
        SLsearch_delete

  [1m4.  Screen Management (SLsmg) functions[0m

  [1m4.1.  SLsmg_fill_region[0m

      [1mSynopsis[0m
        Fill a rectangular region with a character

      [1mUsage[0m
        void SLsmg_fill_region (r, c, nr, nc, ch)

         int r
         int c
         unsigned int nr
         unsigned int nc
         unsigned char ch

      [1mDescription[0m
        The SLsmg_fill_region function may be used to a rectangular
        region with the character ch in the current color.  The
        rectangle's upper left corner is at row r and column c, and
        spans nr rows and nc columns.  The position of the virtual
        cursor will be left at (r, c).

      [1mSee Also[0m
        SLsmg_write_char, SLsmg_set_color

  [1m4.2.  SLsmg_set_char_set[0m

      [1mSynopsis[0m
        Turn on or off line drawing characters

      [1mUsage[0m
        void SLsmg_set_char_set (int a);

      [1mDescription[0m
        SLsmg_set_char_set may be used to select or deselect the line
        drawing character set as the current character set.  If a is
        non-zero, the line drawing character set will be selected.
        Otherwise, the standard character set will be selected.

      [1mNotes[0m
        There is no guarantee that this function will actually enable
        the use of line drawing characters.  All it does is cause
        subsequent characters to be rendered using the terminal's
        alternate character set.  Such character sets usually contain
        line drawing characters.

      [1mSee Also[0m
        SLsmg_write_char, SLtt_get_terminfo

  [1m4.3.  int SLsmg_Scroll_Hash_Border;[0m

      [1mSynopsis[0m
        Set the size of the border for the scroll hash

      [1mUsage[0m
        int SLsmg_Scroll_Hash_Border = 0;

      [1mDescription[0m
        This variable may be used to ignore the characters that occur at
        the beginning and the end of a row when performing the hash
        calculation to determine whether or not a line has scrolled.
        The default value is zero which means that all the characters on
        a line will be used.
      [1mSee Also[0m
        SLsmg_refresh

  [1m4.4.  SLsmg_suspend_smg[0m

      [1mSynopsis[0m
        Suspend screen management

      [1mUsage[0m
        int SLsmg_suspend_smg (void)

      [1mDescription[0m
        SLsmg_suspend_smg can be used to suspend the state of the screen
        management facility during suspension of the program.  Use of
        this function will reset the display back to its default state.
        The funtion SLsmg_resume_smg should be called after suspension.

        It returns zero upon success, or -1 upon error.

        This function is similar to SLsmg_reset_smg except that the
        state of the display prior to calling SLsmg_suspend_smg is
        saved.

      [1mSee Also[0m
        SLsmg_resume_smg, SLsmg_reset_smg

  [1m4.5.  SLsmg_resume_smg[0m

      [1mSynopsis[0m
        Resume screen management

      [1mUsage[0m
        int SLsmg_resume_smg (void)

      [1mDescription[0m
        SLsmg_resume_smg should be called after SLsmg_suspend_smg to
        redraw the display exactly like it was before SLsmg_suspend_smg
        was called.  It returns zero upon success, or -1 upon error.

      [1mSee Also[0m
        SLsmg_suspend_smg

  [1m4.6.  SLsmg_erase_eol[0m

      [1mSynopsis[0m
        Erase to the end of the row

      [1mUsage[0m
        void SLsmg_erase_eol (void);

      [1mDescription[0m
        SLsmg_erase_eol erases all characters from the current position
        to the end of the line.  The newly created space is given the
        color of the current color.  This function has no effect on the
        position of the virtual cursor.

      [1mSee Also[0m
        SLsmg_gotorc, SLsmg_erase_eos, SLsmg_fill_region

  [1m4.7.  SLsmg_gotorc[0m

      [1mSynopsis[0m
        Move the virtual cursor

      [1mUsage[0m
        void SLsmg_gotorc (int r, int c)

      [1mDescription[0m
        The SLsmg_gotorc function moves the virtual cursor to the row r
        and column c.  The first row and first column is specified by r
        = 0 and c = 0.

      [1mSee Also[0m
        SLsmg_refresh

  [1m4.8.  SLsmg_erase_eos[0m

      [1mSynopsis[0m
        Erase to the end of the screen

      [1mUsage[0m
        void SLsmg_erase_eos (void);

      [1mDescription[0m
        The SLsmg_erase_eos is like SLsmg_erase_eol except that it
        erases all text from the current position to the end of the
        display.  The current color will be used to set the background
        of the erased area.

      [1mSee Also[0m
        SLsmg_erase_eol

  [1m4.9.  SLsmg_reverse_video[0m

      [1mSynopsis[0m
        Set the current color to 1

      [1mUsage[0m
        void SLsmg_reverse_video (void);

      [1mDescription[0m
        This function is nothing more than SLsmg_set_color(1).

      [1mSee Also[0m
        SLsmg_set_color

  [1m4.10.  SLsmg_set_color (int)[0m

      [1mSynopsis[0m
        Set the current color

      [1mUsage[0m
        void SLsmg_set_color (int c);

      [1mDescription[0m
        SLsmg_set_color is used to set the current color.  The parameter
        c is really a color object descriptor.  Actual foreground and
        background colors as well as other visual attributes may be
        associated with a color descriptor via the SLtt_set_color
        function.

      [1mExample[0m
        This example defines color 7 to be green foreground on black
        background and then displays some text in this color:

                SLtt_set_color (7, NULL, "green", "black");
                SLsmg_set_color (7);
                SLsmg_write_string ("Hello");
                SLsmg_refresh ();

      [1mNotes[0m
        It is important to understand that the screen managment routines
        know nothing about the actual colors associated with a color
        descriptor.  Only the descriptor itself is used by the SLsmg
        routines.  The lower level SLtt interface converts the color
        descriptors to actual colors.  Thus

                SLtt_set_color (7, NULL, "green", "black");
                SLsmg_set_color (7);
                SLsmg_write_string ("Hello");
                SLtt_set_color (7, NULL, "red", "blue");
                SLsmg_write_string ("World");
                SLsmg_refresh ();

     will result in "hello" displayed in red on blue and [4mnot[24m green on
     black.

      [1mSee Also[0m
        SLtt_set_color, SLtt_set_color_object

  [1m4.11.  SLsmg_normal_video[0m

      [1mSynopsis[0m
        Set the current color to 0

      [1mUsage[0m
        void SLsmg_normal_video (void);

      [1mDescription[0m
        SLsmg_normal_video sets the current color descriptor to 0.

      [1mSee Also[0m
        SLsmg_set_color

  [1m4.12.  SLsmg_printf[0m

      [1mSynopsis[0m
        Format a string on the virtual display

      [1mUsage[0m
        void SLsmg_printf (char *fmt, ...)

      [1mDescription[0m
        SLsmg_printf format a printf style variable argument list and
        writes it on the virtual display.  The virtual cursor will be
        moved to the end of the string.

      [1mSee Also[0m
        SLsmg_write_string, SLsmg_vprintf

  [1m4.13.  SLsmg_vprintf[0m

      [1mSynopsis[0m
        Format a string on the virtual display

      [1mUsage[0m
        void SLsmg_vprintf (char *fmt, va_list ap)

      [1mDescription[0m
        SLsmg_vprintf formats a string in the manner of [4mvprintf[24m and
        writes the result to the display.  The virtual cursor is
        advanced to the end of the string.

      [1mSee Also[0m
        SLsmg_write_string, SLsmg_printf

  [1m4.14.  SLsmg_write_string[0m

      [1mSynopsis[0m
        Write a character string on the display

      [1mUsage[0m
        void SLsmg_write_string (char *s)

      [1mDescription[0m
        The function SLsmg_write_string displays the string s on the
        virtual display at the current position and moves the position
        to the end of the string.

      [1mSee Also[0m
        SLsmg_printf, SLsmg_write_nstring

  [1m4.15.  SLsmg_write_nstring[0m

      [1mSynopsis[0m
        Write the first n characters of a string on the display

      [1mUsage[0m
        void SLsmg_write_nstring (char *s, unsigned int n);

      [1mDescription[0m
        SLsmg_write_nstring writes the first n characters of s to this
        virtual display.  If the length of the string s is less than n,
        the spaces will used until n characters have been written.  s
        can be NULL, in which case n spaces will be written.

      [1mSee Also[0m
        SLsmg_write_string, SLsmg_write_nchars

  [1m4.16.  SLsmg_write_char[0m

      [1mSynopsis[0m
        Write a character to the virtual display

      [1mUsage[0m
        void SLsmg_write_char (char ch);

      [1mDescription[0m
        SLsmg_write_char writes the character ch to the virtual display.

      [1mSee Also[0m
        SLsmg_write_nchars, SLsmg_write_string

  [1m4.17.  SLsmg_write_nchars[0m

      [1mSynopsis[0m
        Write n characters to the virtual display

      [1mUsage[0m
        void SLsmg_write_nchars (char *s, unsigned int n);

      [1mDescription[0m
        SLsmg_write_nchars writes at most n characters from the string s
        to the display.  If the length of s is less than n, the whole
        length of the string will get written.

        This function differs from SLsmg_write_nstring in that
        SLsmg_write_nstring will pad the string to write exactly n
        characters.  SLsmg_write_nchars does not perform any padding.

      [1mSee Also[0m
        SLsmg_write_nchars, SLsmg_write_nstring

  [1m4.18.  SLsmg_write_wrapped_string[0m

      [1mSynopsis[0m
        Write a string to the display with wrapping

      [1mUsage[0m
        void SLsmg_write_wrapped_string (s, r, c, nr, nc, fill)

              char *s
              int r, c
              unsigned int nr, nc
              int fill

      [1mDescription[0m
        SLsmg_write_wrapped_string writes the string s to the virtual
        display.  The string will be confined to the rectangular region
        whose upper right corner is at row r and column c, and consists
        of nr rows and nc columns.  The string will be wrapped at the
        boundaries of the box.  If fill is non-zero, the last line to
        which characters have been written will get padded with spaces.

      [1mNotes[0m
        This function does not wrap on word boundaries.  However, it
        will wrap when a newline charater is encountered.

      [1mSee Also[0m
        SLsmg_write_string

  [1m4.19.  SLsmg_cls[0m

      [1mSynopsis[0m
        Clear the virtual display

      [1mUsage[0m
        void SLsmg_cls (void)

      [1mDescription[0m
        SLsmg_cls erases the virtual display using the current color.
        This will cause the physical display to get cleared the next
        time SLsmg_refresh is called.

      [1mNotes[0m
        This function is not the same as

               SLsmg_gotorc (0,0); SLsmg_erase_eos ();

     since these statements do not guarantee that the physical screen
     will get cleared.

      [1mSee Also[0m
        SLsmg_refresh, SLsmg_erase_eos

  [1m4.20.  SLsmg_refresh[0m

      [1mSynopsis[0m
        Update physical screen

      [1mUsage[0m
        void SLsmg_refresh (void)

      [1mDescription[0m
        The SLsmg_refresh function updates the physical display to look
        like the virtual display.

      [1mSee Also[0m
        SLsmg_suspend_smg, SLsmg_init_smg, SLsmg_reset_smg

  [1m4.21.  SLsmg_touch_lines[0m

      [1mSynopsis[0m
        Mark lines on the virtual display for redisplay

      [1mUsage[0m
        void SLsmg_touch_lines (int r, unsigned int nr)

      [1mDescription[0m
        SLsmg_touch_lines marks the nr lines on the virtual display
        starting at row r for redisplay upon the next call to
        SLsmg_refresh.

      [1mNotes[0m
        This function should rarely be called, if ever.  If you find
        that you need to call this function, then your application
        should be modified to properly use the SLsmg screen management
        routines.  This function is provided only for curses
        compatibility.

      [1mSee Also[0m
        SLsmg_refresh

  [1m4.22.  SLsmg_init_smg[0m

      [1mSynopsis[0m
        Initialize the SLsmg routines

      [1mUsage[0m
        int SLsmg_init_smg (void)

      [1mDescription[0m
        The SLsmg_init_smg function initializes the SLsmg screen
        management routines.   Specifically, this function allocates
        space for the virtual display and calls SLtt_init_video to put
        the terminal's physical display in the proper state.  It is up
        to the caller to make sure that the SLtt routines are
        initialized via SLtt_get_terminfo before calling SLsmg_init_smg.

        This function should also be called any time the size of the
        physical display has changed so that it can reallocate a new
        virtual display to match the physical display.

        It returns zero upon success, or -1 upon failure.

      [1mSee Also[0m
        SLsmg_reset_smg

  [1m4.23.  SLsmg_reset_smg[0m

      [1mSynopsis[0m
        Reset the SLsmg routines

      [1mUsage[0m
        int SLsmg_reset_smg (void);

      [1mDescription[0m
        SLsmg_reset_smg resets the SLsmg screen management routines by
        freeing all memory allocated while it was active.  It also calls
        SLtt_reset_video to put the terminal's display in it default
        state.

      [1mSee Also[0m
        SLsmg_init_smg

  [1m4.24.  SLsmg_char_at[0m

      [1mSynopsis[0m
        Get the character at the current position on the virtual display

      [1mUsage[0m
        unsigned short SLsmg_char_at(void)

      [1mDescription[0m
        The SLsmg_char_at function returns the character and its color
        at the current position on the virtual display.

      [1mSee Also[0m
        SLsmg_read_raw, SLsmg_write_char

  [1m4.25.  SLsmg_set_screen_start[0m

      [1mSynopsis[0m
        Set the origin of the virtual display

      [1mUsage[0m
        void SLsmg_set_screen_start (int *r, int *c)

      [1mDescription[0m
        SLsmg_set_screen_start sets the origin of the virtual display to
        the row *r and the column *c.  If either r or c is NULL, then
        the corresponding value will be set to 0.  Otherwise, the
        location specified by the pointers will be updated to reflect
        the old origin.

        See slang/demo/pager.c for how this function may be used to
        scroll horizontally.
      [1mSee Also[0m
        SLsmg_init_smg

  [1m4.26.  SLsmg_draw_hline[0m

      [1mSynopsis[0m
        Draw a horizontal line

      [1mUsage[0m
        void SLsmg_draw_hline (unsigned int len)

      [1mDescription[0m
        The SLsmg_draw_hline function draws a horizontal line of length
        len on the virtual display.  The position of the virtual cursor
        is left at the end of the line.

      [1mSee Also[0m
        SLsmg_draw_vline

  [1m4.27.  SLsmg_draw_vline[0m

      [1mSynopsis[0m
        Draw a vertical line

      [1mUsage[0m
        void SLsmg_draw_vline (unsigned int len);

      [1mDescription[0m
        The SLsmg_draw_vline function draws a vertical line of length
        len on the virtual display.  The position of the virtual cursor
        is left at the end of the line.

      [1mSee Also[0m
        ??

  [1m4.28.  SLsmg_draw_object[0m

      [1mSynopsis[0m
        Draw an object from the alternate character set

      [1mUsage[0m
        void SLsmg_draw_object (int r, int c, unsigned char obj)

      [1mDescription[0m
        The SLsmg_draw_object function may be used to place the object
        specified by obj at row r and column c.  The object is really a
        character from the alternate character set and may be specified
        using one of the following constants:

         SLSMG_HLINE_CHAR         Horizontal line
         SLSMG_VLINE_CHAR         Vertical line
         SLSMG_ULCORN_CHAR        Upper left corner
         SLSMG_URCORN_CHAR        Upper right corner
         SLSMG_LLCORN_CHAR        Lower left corner
         SLSMG_LRCORN_CHAR        Lower right corner
         SLSMG_CKBRD_CHAR         Checkboard character
         SLSMG_RTEE_CHAR          Right Tee
         SLSMG_LTEE_CHAR          Left Tee
         SLSMG_UTEE_CHAR          Up Tee
         SLSMG_DTEE_CHAR          Down Tee
         SLSMG_PLUS_CHAR          Plus or Cross character

      [1mSee Also[0m
        SLsmg_draw_vline, SLsmg_draw_hline, SLsmg_draw_box

  [1m4.29.  SLsmg_draw_box[0m

      [1mSynopsis[0m
        Draw a box on the virtual display

      [1mUsage[0m
        void SLsmg_draw_box (int r, int c, unsigned int dr, unsigned int
        dc)

      [1mDescription[0m
        SLsmg_draw_box uses the SLsmg_draw_hline and SLsmg_draw_vline
        functions to draw a rectangular box on the virtual display.  The
        box's upper left corner is placed at row r and column c.  The
        width and length of the box is specified by dc and dr,
        respectively.

      [1mSee Also[0m
        SLsmg_draw_vline, SLsmg_draw_hline, SLsmg_draw_object

  [1m4.30.  SLsmg_set_color_in_region[0m

      [1mSynopsis[0m
        Change the color of a specifed region

      [1mUsage[0m
        void SLsmg_set_color_in_region (color, r, c, dr, dc)

            int color;
            int r, c;
            unsigned int dr, dc;

      [1mDescription[0m
        SLsmg_set_color_in_region may be used to change the color of a
        rectangular region whose upper left corner is given by (r,c),
        and whose width and height is given by dc and dr, respectively.
        The color of the region is given by the color parameter.
      [1mSee Also[0m
        SLsmg_draw_box, SLsmg_set_color

  [1m4.31.  SLsmg_get_column[0m

      [1mSynopsis[0m
        Get the column of the virtual cursor

      [1mUsage[0m
        int SLsmg_get_column(void);

      [1mDescription[0m
        The SLsmg_get_column function returns the current column of the
        virtual cursor on the virtual display.

      [1mSee Also[0m
        SLsmg_get_row, SLsmg_gotorc

  [1m4.32.  SLsmg_get_row[0m

      [1mSynopsis[0m
        Get the row of the virtual cursor

      [1mUsage[0m
        int SLsmg_get_row(void);

      [1mDescription[0m
        The SLsmg_get_row function returns the current row of the
        virtual cursor on the virtual display.

      [1mSee Also[0m
        SLsmg_get_column, SLsmg_gotorc

  [1m4.33.  SLsmg_forward[0m

      [1mSynopsis[0m
        Move the virtual cursor forward n columns

      [1mUsage[0m
        void SLsmg_forward (int n);

      [1mDescription[0m
        The SLsmg_forward function moves the virtual cursor forward n
        columns.

      [1mSee Also[0m
        SLsmg_gotorc

  [1m4.34.  SLsmg_write_color_chars[0m

      [1mSynopsis[0m
        Write characters with color descriptors to virtual display

      [1mUsage[0m
        void SLsmg_write_color_chars (unsigned short *s, unsigned int
        len)

      [1mDescription[0m
        The SLsmg_write_color_chars function may be used to write len
        characters, each with a different color descriptor to the
        virtual display.  Each character and its associated color are
        encoded as an unsigned short such that the lower eight bits form
        the character and the next eight bits form the color.

      [1mSee Also[0m
        SLsmg_char_at, SLsmg_write_raw

  [1m4.35.  SLsmg_read_raw[0m

      [1mSynopsis[0m
        Read characters from the virtual display

      [1mUsage[0m
        unsigned int SLsmg_read_raw (unsigned short *buf, unsigned int
        len)

      [1mDescription[0m
        SLsmg_read_raw attempts to read len characters from the current
        position on the virtual display into the buffer specified by
        buf.  It returns the number of characters actually read.  This
        number will be less than len if an attempt is made to read past
        the right margin of the display.

      [1mNotes[0m
        The purpose of the pair of functions, SLsmg_read_raw and
        SLsmg_write_raw, is to permit one to copy the contents of one
        region of the virtual display to another region.

      [1mSee Also[0m
        SLsmg_char_at, SLsmg_write_raw

  [1m4.36.  SLsmg_write_raw[0m

      [1mSynopsis[0m
        Write characters directly to the virtual display

      [1mUsage[0m
        unsigned int SLsmg_write_raw (unsigned short *buf, unsigned int
        len)

      [1mDescription[0m
        The SLsmg_write_raw function attempts to write len characters
        specified by buf to the display at the current position.  It
        returns the number of characters successfully written, which
        will be less than len if an attempt is made to write past the
        right margin.

      [1mNotes[0m
        The purpose of the pair of functions, SLsmg_read_raw and
        SLsmg_write_raw, is to permit one to copy the contents of one
        region of the virtual display to another region.

      [1mSee Also[0m
        SLsmg_read_raw

  [1m5.  Functions that deal with the interpreter[0m

  [1m5.1.  SLallocate_load_type[0m

      [1mSynopsis[0m
        Allocate a SLang_Load_Type object

      [1mUsage[0m
        SLang_Load_Type *SLallocate_load_type (char *name)

      [1mDescription[0m
        The SLallocate_load_type function allocates and initializes
        space for a SLang_Load_Type object and returns it.  Upon
        failure, the function returns NULL.  The parameter name must
        uniquely identify the object.  For example, if the object
        represents a file, then name could be the absolute path name of
        the file.

      [1mSee Also[0m
        SLdeallocate_load_type, SLang_load_object

  [1m5.2.  SLdeallocate_load_type[0m

      [1mSynopsis[0m
        Free a SLang_Load_Type object

      [1mUsage[0m
        void SLdeallocate_load_type (SLang_Load_Type *slt)

      [1mDescription[0m
        This function frees the memory associated with a SLang_Load_Type
        object that was acquired from a call to the SLallocate_load_type
        function.

      [1mSee Also[0m
        SLallocate_load_type, SLang_load_object

  [1m5.3.  SLang_load_object[0m

      [1mSynopsis[0m
        Load an object into the interpreter

      [1mUsage[0m
        int SLang_load_object (SLang_Load_Type *obj)

      [1mDescription[0m
        The function SLang_load_object is a generic function that may be
        used to loaded an object of type SLang_Load_Type into the
        interpreter.  For example, the functions SLang_load_file and
        SLang_load_string are wrappers around this function to load a
        file and a string, respectively.

      [1mSee Also[0m
        SLang_load_file, SLang_load_string, SLallocate_load_type

  [1m5.4.  SLclass_allocate_class[0m

      [1mSynopsis[0m
        Allocate a class for a new data type

      [1mUsage[0m
        SLang_Class_Type *SLclass_allocate_class (char *name)

      [1mDescription[0m
        The purpose of this function is to allocate and initialize space
        that defines a new data type or class called name.  If
        successful, a pointer to the class is returned, or upon failure
        the function returns NULL.

        This function does not automatically create the new data type.
        Callback functions must first be associated with the data type
        via functions such as SLclass_set_push_function, and the data
        type must be registered with the interpreter via
        SLclass_register_class.  See the [1mS-Lang [22mlibrary programmer's
        guide for more information.

      [1mSee Also[0m
        SLclass_register_class, SLclass_set_push_function

  [1m5.5.  SLclass_register_class[0m

      [1mSynopsis[0m
        Register a new data type with the interpreter

      [1mUsage[0m
        int SLclass_register_class (cl, type, sizeof_type, class_type)

              SLang_Class_Type *cl
              SLtype type
              unsigned int sizeof_type
              SLclass_Type class_type

      [1mDescription[0m
        The SLclass_register_class function is used to register a new
        class or data type with the interpreter.  If successful, the
        function returns 0, or upon failure, it returns -1.
        The first parameter, cl, must have been previously obtained via
        the SLclass_allocate_class function.

        The second parameter, type specifies the data type of the new
        class.  If set to SLANG_VOID_TYPE then the library will
        automatically allocate an unused value for the class (the
        allocated value can then be found using the SLclass_get_class_id
        function), otherwise a value greater than 255 should be used.
        The values in the range 0-255 are reserved for internal use by
        the library.

        The size that the data type represents in bytes is specified by
        the third parameter, sizeof_type.   This value should not be
        confused with the sizeof the structure that represents the data
        type, unless the data type is of class SLANG_CLASS_TYPE_VECTOR
        or SLANG_CLASS_TYPE_SCALAR.  For pointer objects, the value of
        this parameter is just sizeof(void *).

        The final parameter specifies the class type of the data type.
        It must be one of the values:

               SLANG_CLASS_TYPE_SCALAR
               SLANG_CLASS_TYPE_VECTOR
               SLANG_CLASS_TYPE_PTR
               SLANG_CLASS_TYPE_MMT

     The SLANG_CLASS_TYPE_SCALAR indicates that the new data type is a
     scalar.  Examples of scalars in SLANG_INT_TYPE and SLANG_DOU-
     BLE_TYPE.

     Setting class_type to SLANG_CLASS_TYPE_VECTOR implies that the new
     data type is a vector, or a 1-d array of scalar types.  An example
     of a data type of this class is the SLANG_COMPLEX_TYPE, which
     represents complex numbers.

     SLANG_CLASS_TYPE_PTR specifies the data type is of a pointer type.
     Examples of data types of this class include SLANG_STRING_TYPE and
     SLANG_ARRAY_TYPE.  Such types must provide for their own memory
     management.

     Data types of class SLANG_CLASS_TYPE_MMT are pointer types except
     that the memory management, i.e., creation and destruction of the
     type, is handled by the interpreter.  Such a type is called a
     [4mmemory[24m [4mmanaged[24m [4mtype[24m.  An example of this data type is the
     SLANG_FILEPTR_TYPE.

      [1mNotes[0m
        See the [4mS-Lang[24m [4mLibrary[24m [4mC[24m [4mProgrammer's[24m [4mGuide[24m for more
        information.

      [1mSee Also[0m
        SLclass_allocate_class, SLclass_get_class_id

  [1m5.6.  SLclass_set_string_function[0m

      [1mSynopsis[0m
        Set a data type's string representation callback

      [1mUsage[0m
        int SLclass_set_string_function (cl, sfun)

             SLang_Class_Type *cl
             char *(*sfun) (SLtype, VOID_STAR);

      [1mDescription[0m
        The SLclass_set_string_function routine is used to define a
        callback function, sfun, that will be used when a string
        representation of an object of the data type represented by cl
        is needed.  cl must have already been obtained via a call to
        SLclass_allocate_class.  When called, sfun will be passed two
        arguments: an SLtype which represents the data type, and the
        address of the object for which a string represetation is
        required.  The callback function must return a [4mmalloced[24m string.

        Upon success, SLclass_set_string_function returns zero, or upon
        error it returns -1.

      [1mExample[0m
        A callback function that handles both SLANG_STRING_TYPE and
        SLANG_INT_TYPE variables looks like:

               char *string_and_int_callback (SLtype type, VOID_STAR addr)
               {
                  char buf[64];

                  switch (type)
                    {
                     case SLANG_STRING_TYPE:
                       return SLmake_string (*(char **)addr);

                     case SLANG_INTEGER_TYPE:
                       sprintf (buf, "%d", *(int *)addr);
                       return SLmake_string (buf);
                    }
                  return NULL;
               }

      [1mNotes[0m
        The default string callback simply returns the name of the data
        type.

      [1mSee Also[0m
        SLclass_allocate_class, SLclass_register_class

  [1m5.7.  SLclass_set_destroy_function[0m

      [1mSynopsis[0m
        Set the destroy method callback for a data type

      [1mUsage[0m
        int SLclass_set_destroy_function (cl, destroy_fun)

         SLang_Class_Type *cl
         void (*destroy_fun) (SLtype, VOID_STAR);

      [1mDescription[0m
        SLclass_set_destroy_function is used to set the destroy callback
        for a data type.  The data type's class cl must have been
        previously obtained via a call to SLclass_allocate_class.  When
        called, destroy_fun will be passed two arguments: an SLtype
        which represents the data type, and the address of the object to
        be destroyed.

        SLclass_set_destroy_function returns zero upon success, and -1
        upon failure.

      [1mExample[0m
        The destroy method for SLANG_STRING_TYPE looks like:

              static void string_destroy (SLtype type, VOID_STAR ptr)
              {
                 char *s = *(char **) ptr;
                 if (s != NULL) SLang_free_slstring (*(char **) s);
              }

      [1mNotes[0m
        Data types of class SLANG_CLASS_TYPE_SCALAR do not require a
        destroy callback.  However, other classes do.

      [1mSee Also[0m
        SLclass_allocate_class, SLclass_register_class

  [1m5.8.  SLclass_set_push_function[0m

      [1mSynopsis[0m
        Set the push callback for a new data type

      [1mUsage[0m
        int SLclass_set_push_function (cl, push_fun)

              SLang_Class_Type *cl
              int (*push_fun) (SLtype, VOID_STAR);

      [1mDescription[0m
        SLclass_set_push_function is used to set the push callback for a
        new data type specified by cl, which must have been previously
        obtained via SLclass_allocate_class.

        The parameter push_fun is a pointer to the push callback.  It is
        required to take two arguments: an SLtype representing the data
        type, and the address of the object to be pushed.  It must
        return zero upon success, or -1 upon failure.

        SLclass_set_push_function returns zero upon success, or -1 upon
        failure.

      [1mExample[0m
        The push callback for SLANG_COMPLEX_TYPE looks like:

                static int complex_push (SLtype type, VOID_STAR ptr)
                {
                   double *z = *(double **) ptr;
                   return SLang_push_complex (z[0], z[1]);
                }

      [1mSee Also[0m
        SLclass_allocate_class, SLclass_register_class

  [1m5.9.  SLclass_set_pop_function[0m

      [1mSynopsis[0m
        Set the pop callback for a new data type

      [1mUsage[0m
        int SLclass_set_pop_function (cl, pop_fun)

              SLang_Class_Type *cl
              int (*pop_fun) (SLtype, VOID_STAR);

      [1mDescription[0m
        SLclass_set_pop_function is used to set the callback for popping
        an object from the stack for a new data type specified by cl,
        which must have been previously obtained via
        SLclass_allocate_class.

        The parameter pop_fun is a pointer to the pop callback function,
        which is required to take two arguments: an unsigned character
        representing the data type, and the address of the object to be
        popped.  It must return zero upon success, or -1 upon failure.

        SLclass_set_pop_function returns zero upon success, or -1 upon
        failure.

      [1mExample[0m
        The pop callback for SLANG_COMPLEX_TYPE looks like:

                static int complex_push (SLtype type, VOID_STAR ptr)
                {
                   double *z = *(double **) ptr;
                   return SLang_pop_complex (&z[0], &z[1]);
                }

      [1mSee Also[0m
        SLclass_allocate_class, SLclass_register_class

  [1m5.10.  SLclass_get_datatype_name[0m

      [1mSynopsis[0m
        Get the name of a data type

      [1mUsage[0m
        char *SLclass_get_datatype_name (SLtype type)

      [1mDescription[0m
        The SLclass_get_datatype_name function returns the name of the
        data type specified by type.  For example, if type is
        SLANG_INT_TYPE, the string "Integer_Type" will be returned.

        This function returns a pointer that should not be modified or
        freed.

      [1mSee Also[0m
        SLclass_allocate_class, SLclass_register_class

  [1m5.11.  SLang_free_mmt[0m

      [1mSynopsis[0m
        Free a memory managed type

      [1mUsage[0m
        void SLang_free_mmt (SLang_MMT_Type *mmt)

      [1mDescription[0m
        The SLang_MMT_Type function is used to free a memory managed
        data type.

      [1mSee Also[0m
        SLang_object_from_mmt, SLang_create_mmt

  [1m5.12.  SLang_object_from_mmt[0m

      [1mSynopsis[0m
        Get a pointer to the value of a memory managed type

      [1mUsage[0m
        VOID_STAR SLang_object_from_mmt (SLang_MMT_Type *mmt)

      [1mDescription[0m
        The SLang_object_from_mmt function returns a pointer to the
        actual object whose memory is being managed by the interpreter.

      [1mSee Also[0m
        SLang_free_mmt, SLang_create_mmt

  [1m5.13.  SLang_create_mmt[0m

      [1mSynopsis[0m
        Create a memory managed data type

      [1mUsage[0m
        SLang_MMT_Type *SLang_create_mmt (SLtype t, VOID_STAR ptr)

      [1mDescription[0m
        The SLang_create_mmt function returns a pointer to a new memory
        managed object.  This object contains information necessary to
        manage the memory associated with the pointer ptr which
        represents the application defined data type of type t.

      [1mSee Also[0m
        SLang_object_from_mmt, SLang_push_mmt, SLang_free_mmt

  [1m5.14.  SLang_push_mmt[0m

      [1mSynopsis[0m
        Push a memory managed type

      [1mUsage[0m
        int SLang_push_mmt (SLang_MMT_Type *mmt)

      [1mDescription[0m
        This function is used to push a memory managed type onto the
        interpreter stack.  It returns zero upon success, or -1 upon
        failure.

      [1mSee Also[0m
        SLang_create_mmt, SLang_pop_mmt

  [1m5.15.  SLang_pop_mmt[0m

      [1mSynopsis[0m
        Pop a memory managed data type

      [1mUsage[0m
        SLang_MMT_Type *SLang_pop_mmt (SLtype t)

      [1mDescription[0m
        The SLang_pop_mmt function may be used to pop a memory managed
        type of type t from the stack.  It returns a pointer to the
        memory managed object upon success, or NULL upon failure.  The
        function SLang_object_from_mmt should be used to access the
        actual pointer to the data type.

      [1mSee Also[0m
        SLang_object_from_mmt, SLang_push_mmt

  [1m5.16.  SLang_inc_mmt[0m

      [1mSynopsis[0m
        Increment a memory managed type reference count

      [1mUsage[0m
        void SLang_inc_mmt (SLang_MMT_Type *mmt);

      [1mDescription[0m
        The SLang_inc_mmt function may be used to increment the
        reference count associated with the memory managed data type
        given by mmt.

      [1mSee Also[0m
        SLang_free_mmt, SLang_create_mmt, SLang_pop_mmt, SLang_pop_mmt

  [1m5.17.  SLadd_intrin_fun_table[0m

      [1mSynopsis[0m
        Add a table of intrinsic functions to the interpreter

      [1mUsage[0m
        int SLadd_intrin_fun_table(SLang_Intrin_Fun_Type *tbl, char
        *pp_name);

      [1mDescription[0m
        The SLadd_intrin_fun_table function adds an array, or table, of
        SLang_Intrin_Fun_Type objects to the interpreter.  The first
        parameter, tbl specifies the table to be added.  The second
        parameter pp_name, if non-NULL will be added to the list of
        preprocessor symbols.

        This function returns -1 upon failure or zero upon success.

      [1mNotes[0m
        A table should only be loaded one time and it is considered to
        be an error on the part of the application if it loads a table
        more than once.

      [1mSee Also[0m
        SLadd_intrin_var_table, SLadd_intrinsic_function,
        SLdefine_for_ifdef

  [1m5.18.  SLadd_intrin_var_table[0m

      [1mSynopsis[0m
        Add a table of intrinsic variables to the interpreter

      [1mUsage[0m
        int SLadd_intrin_var_table (SLang_Intrin_Var_Type *tbl, char
        *pp_name);

      [1mDescription[0m
        The SLadd_intrin_var_table function adds an array, or table, of
        SLang_Intrin_Var_Type objects to the interpreter.  The first
        parameter, tbl specifies the table to be added.  The second
        parameter pp_name, if non-NULL will be added to the list of
        preprocessor symbols.
        This function returns -1 upon failure or zero upon success.

      [1mNotes[0m
        A table should only be loaded one time and it is considered to
        be an error on the part of the application if it loads a table
        more than once.

      [1mSee Also[0m
        SLadd_intrin_var_table, SLadd_intrinsic_function,
        SLdefine_for_ifdef

  [1m5.19.  SLang_load_file[0m

      [1mSynopsis[0m
        Load a file into the interpreter

      [1mUsage[0m
        int SLang_load_file (char *fn)

      [1mDescription[0m
        The SLang_load_file function opens the file whose name is
        specified by fn and feeds it to the interpreter, line by line,
        for execution.  If fn is NULL, the function will take input from
        stdin.

        If no error occurs, it returns 0; otherwise, it returns -1, and
        sets SLang_Error accordingly.  For example, if it fails to open
        the file, it will return -1 with SLang_Error set to
        SL_OBJ_NOPEN.

      [1mNotes[0m
        If the hook SLang_Load_File_Hook declared as

                int (*SLang_Load_File_Hook)(char *);

     is non-NULL, the function point to by it will be used to load the
     file.  For example, the [1mjed [22meditor uses this hook to load files via
     its own routines.

      [1mSee Also[0m
        SLang_load_object, SLang_load_string

  [1m5.20.  SLang_restart[0m

      [1mSynopsis[0m
        Reset the interpreter after an error

      [1mUsage[0m
        void SLang_restart (int full)

      [1mDescription[0m
        The SLang_restart function should be called by the application
        at top level if an error occurs.  If the parameter full is non-
        zero, any objects on the [1mS-Lang [22mrun time stack will be removed
        from the stack; otherwise, the stack will be left intact.  Any
        time the stack is believed to be trashed, this routine should be
        called with a non-zero argument (e.g., if setjmp/longjmp is
        called).

        Calling SLang_restart does not reset the global variable
        SLang_Error to zero.  It is up to the application to reset that
        variable to zero after calling SLang_restart.

      [1mExample[0m

                while (1)
                  {
                     if (SLang_Error)
                       {
                          SLang_restart (1);
                          SLang_Error = 0;
                       }
                     (void) SLang_load_file (NULL);
                  }

      [1mSee Also[0m
        SLang_init_slang, SLang_load_file

  [1m5.21.  SLang_byte_compile_file[0m

      [1mSynopsis[0m
        Byte-compile a file for faster loading

      [1mUsage[0m
        int SLang_byte_compile_file(char *fn, int reserved)

      [1mDescription[0m
        The SLang_byte_compile_file function ``byte-compiles'' the file
        fn for faster loading by the interpreter.  This produces a new
        file whose filename is equivalent to the one specified by fn,
        except that a 'c' is appended to the name.  For example, if fn
        is set to init.sl, then the new file will have the name
        exmp{init.slc}.  The meaning of the second parameter, reserved,
        is reserved for future use.  For now, set it to 0.

        The function returns zero upon success, or -1 upon error and
        sets SLang_Error accordingly.

      [1mSee Also[0m
        SLang_load_file, SLang_init_slang

  [1m5.22.  SLang_autoload[0m

      [1mSynopsis[0m
        Autoload a function from a file

      [1mUsage[0m
        int SLang_autoload(char *funct, char *filename)
      [1mDescription[0m
        The SLang_autoload function may be used to associate a slang
        function name funct with the file filename such that if funct
        has not already been defined when needed, it will be loaded from
        filename.

        SLang_autoload has no effect if funct has already been defined.
        Otherwise it declares funct as a user-defined [1mS-Lang [22mfunction.
        It returns 0 upon success, or -1 upon error.

      [1mSee Also[0m
        SLang_load_file, SLang_is_defined

  [1m5.23.  SLang_load_string[0m

      [1mSynopsis[0m
        Interpret a string

      [1mUsage[0m
        int SLang_load_string(char *str)

      [1mDescription[0m
        The SLang_load_string function feeds the string specified by str
        to the interpreter for execution.  It returns zero upon success,
        or -1 upon failure.

      [1mSee Also[0m
        SLang_load_file, SLang_load_object

  [1m5.24.  SLdo_pop[0m

      [1mSynopsis[0m
        Delete an object from the stack

      [1mUsage[0m
        int SLdo_pop(void)

      [1mDescription[0m
        This function removes an object from the top of the interpeter's
        run-time stack and frees any memory associated with it.  It
        returns zero upon success, or -1 upon error (most likely due to
        a stack-underflow).

      [1mSee Also[0m
        SLdo_pop_n, SLang_pop_integer, SLang_pop_string

  [1m5.25.  SLdo_pop_n[0m

      [1mSynopsis[0m
        Delete n objects from the stack

      [1mUsage[0m
        int SLdo_pop_n (unsigned int n)

      [1mDescription[0m
        The SLdo_pop_n function removes the top n objects from the
        interpreter's run-time stack and frees all memory associated
        with the objects.  It returns zero upon success, or -1 upon
        error (most likely due to a stack-underflow).

      [1mSee Also[0m
        SLdo_pop, SLang_pop_integer, SLang_pop_string

  [1m5.26.  SLang_pop_integer[0m

      [1mSynopsis[0m
        Pop an integer off the stack

      [1mUsage[0m
        int SLang_pop_integer (int *i)

      [1mDescription[0m
        The SLang_pop_integer function removes an integer from the top
        of the interpreter's run-time stack and returns its value via
        the pointer i.  If successful, it returns zero.  However, if the
        top stack item is not of type SLANG_INT_TYPE, or the stack is
        empty, the function will return -1 and set SLang_Error
        accordingly.

      [1mSee Also[0m
        SLang_push_integer, SLang_pop_double

  [1m5.27.  SLpop_string[0m

      [1mSynopsis[0m
        Pop a string from the stack

      [1mUsage[0m
        int SLpop_string (char **strptr);

      [1mDescription[0m
        The SLpop_string function pops a string from the stack and
        returns it as a malloced pointer.  It is up to the calling
        routine to free this string via a call to free or SLfree.  If
        successful, SLpop_string returns zero.  However, if the top
        stack item is not of type SLANG_STRING_TYPE, or the stack is
        empty, the function will return -1 and set SLang_Error
        accordingly.

      [1mExample[0m

                define print_string (void)
                {
                   char *s;
                   if (-1 == SLpop_string (&s))
                     return;
                   fputs (s, stdout);
                   SLfree (s);
                }

      [1mNotes[0m
        This function should not be confused with SLang_pop_slstring,
        which pops a [4mhashed[24m string from the stack.

      [1mSee Also[0m
        SLang_pop_slstring. SLfree

  [1m5.28.  SLang_pop_string[0m

      [1mSynopsis[0m
        Pop a string from the stack

      [1mUsage[0m
        int SLang_pop_string(char **strptr, int *do_free)

      [1mDescription[0m
        The SLpop_string function pops a string from the stack and
        returns it as a malloced pointer via strptr.  After the function
        returns, the integer pointed to by the second parameter will be
        set to a non-zero value if *strptr should be freed via free or
        SLfree.  If successful, SLpop_string returns zero.  However, if
        the top stack item is not of type SLANG_STRING_TYPE, or the
        stack is empty, the function will return -1 and set SLang_Error
        accordingly.

      [1mNotes[0m
        This function is considered obsolete and should not be used by
        applications.  If one requires a malloced string for
        modification, SLpop_string should be used.  If one requires a
        constant string that will not be modifed by the application,
        SLang_pop_slstring should be used.

      [1mSee Also[0m
        SLang_pop_slstring, SLpop_string

  [1m5.29.  SLang_pop_slstring[0m

      [1mSynopsis[0m
        Pop a hashed string from the stack

      [1mUsage[0m
        int SLang_pop_slstring (char **s_ptr)

      [1mDescription[0m
        The SLang_pop_slstring function pops a hashed string from the [1mS-[0m
        [1mLang [22mrun-time stack and returns it via s_ptr.  It returns zero
        if successful, or -1 upon failure.  The resulting string should
        be freed via a call to SLang_free_slstring after use.

      [1mExample[0m

        void print_string (void)
        {
           char *s;
           if (-1 == SLang_pop_slstring (&s))
             return;
           fprintf (stdout, "%s\n", s);
           SLang_free_slstring (s);
        }

      [1mNotes[0m
        SLang_free_slstring is the preferred function for popping
        strings.  This is a result of the fact that the interpreter uses
        hashed strings as the native representation for string data.

        One must [4mnever[24m free a hashed string using free or SLfree.  In
        addition, one must never make any attempt to modify a hashed
        string and doing so will result in memory corruption.

      [1mSee Also[0m
        SLang_free_slstring, SLpop_string

  [1m5.30.  SLang_pop_double[0m

      [1mSynopsis[0m
        Pop a double from the stack

      [1mUsage[0m
        int SLang_pop_double (double *dptr)

      [1mDescription[0m
        The SLang_pop_double function pops a double precision number
        from the stack and returns it via dptr.  This function returns 0
        upon success, otherwise it returns -1 and sets SLang_Error
        accordingly.

      [1mSee Also[0m
        SLang_pop_integer, SLang_push_double

  [1m5.31.  SLang_pop_complex[0m

      [1mSynopsis[0m
        Pop a complex number from the stack

      [1mUsage[0m
        int SLang_pop_complex (double *re, double *im)

      [1mDescription[0m
        SLang_pop_complex pops a complex number from the stack and
        returns it via the parameters re and im as the real and
        imaginary parts of the complex number, respectively.  This
        function automatically converts objects of type
        SLANG_DOUBLE_TYPE and SLANG_INT_TYPE to SLANG_COMPLEX_TYPE, if
        necessary.  It returns zero upon success, or -1 upon error
        setting SLang_Error accordingly.

      [1mSee Also[0m
        SLang_pop_integer, SLang_pop_double, SLang_push_complex

  [1m5.32.  SLang_push_complex[0m

      [1mSynopsis[0m
        Push a complex number onto the stack

      [1mUsage[0m
        int SLang_push_complex (double re, double im)

      [1mDescription[0m
        SLang_push_complex may be used to push the complex number whose
        real and imaginary parts are given by re and im, respectively.
        It returns zero upon success, or -1 upon error setting
        SLang_Error accordingly.

      [1mSee Also[0m
        SLang_pop_complex, SLang_push_double

  [1m5.33.  SLang_push_double[0m

      [1mSynopsis[0m
        Push a double onto the stack

      [1mUsage[0m
        int SLang_push_double(double d)

      [1mDescription[0m
        SLang_push_double may be used to push the double precision
        floating point number d onto the interpreter's run-time stack.
        It returns zero upon success, or -1 upon error setting
        SLang_Error accordingly.

      [1mSee Also[0m
        SLang_pop_double, SLang_push_integer

  [1m5.34.  SLang_push_string[0m

      [1mSynopsis[0m
        Push a string onto the stack

      [1mUsage[0m
        int SLang_push_string (char *s)

      [1mDescription[0m
        SLang_push_string pushes a copy of the string specified by s
        onto the interpreter's run-time stack.  It returns zero upon
        success, or -1 upon error setting SLang_Error accordingly.

      [1mNotes[0m
        If s is NULL, this function pushes NULL (SLANG_NULL_TYPE) onto
        the stack.

      [1mSee Also[0m
        SLang_push_malloced_string

  [1m5.35.  SLang_push_integer[0m

      [1mSynopsis[0m
        Push an integer onto the stack

      [1mUsage[0m
        int SLang_push_integer (int i)

      [1mDescription[0m
        SLang_push_integer the integer i onto the interpreter's run-time
        stack.  It returns zero upon success, or -1 upon error setting
        SLang_Error accordingly.

      [1mSee Also[0m
        SLang_pop_integer, SLang_push_double, SLang_push_string

  [1m5.36.  SLang_push_malloced_string[0m

      [1mSynopsis[0m
        Push a malloced string onto the stack

      [1mUsage[0m
        int SLang_push_malloced_string (char *s);

      [1mDescription[0m
        SLang_push_malloced_string may be used to push a malloced string
        onto the interpreter's run-time stack.  It returns zero upon
        success, or -1 upon error setting SLang_Error accordingly.

      [1mExample[0m
        The following example illustrates that it is up to the calling
        routine to free the string if SLang_push_malloced_string fails:

                int push_hello (void)
                {
                   char *s = malloc (6);
                   if (s == NULL) return -1;
                   strcpy (s, "hello");
                   if (-1 == SLang_push_malloced_string (s))
                     {
                        free (s);
                        return -1;
                     }
                   return 0;
                }

      [1mExample[0m
        The function SLang_create_slstring returns a hashed string.
        Such a string may not be malloced and should not be passed to
        SLang_push_malloced_string.

      [1mNotes[0m
        If s is NULL, this function pushes NULL (SLANG_NULL_TYPE) onto
        the stack.

      [1mSee Also[0m
        SLang_push_string, SLmake_string

  [1m5.37.  SLang_is_defined[0m

      [1mSynopsis[0m
        Check to see if the interpreter defines an object

      [1mUsage[0m
        int SLang_is_defined (char *nm)

      [1mDescription[0m
        The SLang_is_defined function may be used to determine whether
        or not a variable or function whose name is given by em has been
        defined.  It returns zero if no such object has been defined.
        Otherwise it returns a non-zero value according to the following
        table:

                1    intrinsic function
                2    user-defined slang function
               -1    intrinsic variable
               -2    user-defined global variable

     Note that variables correspond to negative numbers and functions
     are represented by positive numbers.

      [1mSee Also[0m
        SLadd_intrinsic_function, SLang_run_hooks,
        SLang_execute_function

  [1m5.38.  SLang_run_hooks[0m

      [1mSynopsis[0m
        Run a user-defined hook with arguments

      [1mUsage[0m
        int SLang_run_hooks (char *fname, unsigned int n, ...)

      [1mDescription[0m
        The SLang_run_hooks function may be used to execute a user-
        defined function named fname.  Before execution of the function,
        the n string arguments specified by the variable parameter list
        are pushed onto the stack.  If the function fname does not
        exist, SLang_run_hooks returns zero; otherwise, it returns 1
        upon successful execution of the function, or -1 if an error
        occurred.

      [1mExample[0m
        The [1mjed [22meditor 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;

      [1mSee Also[0m
        SLang_is_defined, SLang_execute_function

  [1m5.39.  SLang_execute_function[0m

      [1mSynopsis[0m
        Execute a user or intrinsic function

      [1mUsage[0m
        int SLang_execute_function (char *fname)

      [1mDescription[0m
        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.

      [1mNotes[0m
        The function SLexecute_function may be a better alternative for
        some uses.

      [1mSee Also[0m
        SLang_run_hooks, SLexecute_function, SLang_is_defined

  [1m5.40.  SLang_get_function[0m

      [1mSynopsis[0m
        Get a pointer to a [1mS-Lang [22mfunction

      [1mUsage[0m
        SLang_Name_Type *SLang_get_function (char *fname)

      [1mDescription[0m
        This function returns a pointer to the internal [1mS-Lang [22mtable
        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.

      [1mSee Also[0m
        SLexecute_function

  [1m5.41.  SLexecute_function[0m

      [1mSynopsis[0m
        Execute a [1mS-Lang [22mor intrinsic function
      [1mUsage[0m
        int SLexecute_function (SLang_Name_Type *nt)

      [1mDescription[0m
        The SLexecute_function allows an application to call the [1mS-Lang[0m
        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.

      [1mExample[0m
        Consider the [1mS-Lang [22mfunction:

               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 SLexe-
     cute_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))
                          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 informa-
     tion about the number of parameters passed to it.

      [1mSee Also[0m
        SLang_get_function, SLang_start_arg_list, SLang_end_arg_list

  [1m5.42.  SLang_peek_at_stack[0m

      [1mSynopsis[0m
        Find the type of object on the top of the stack

      [1mUsage[0m
        int SLang_peek_at_stack (void)

      [1mDescription[0m
        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.

      [1mSee Also[0m
        SLang_pop_string, SLang_pop_integer

  [1m5.43.  SLang_pop_fileptr[0m

      [1mSynopsis[0m
        Pop a file pointer

      [1mUsage[0m
        int SLang_pop_fileptr (SLang_MMT_Type **mmt, FILE **fp)

      [1mDescription[0m
        SLang_pop_fileptr pops a file pointer from the [1mS-Lang [22mrun-time
        stack.  It returns zero upon success, or -1 upon failure.

        A [1mS-Lang [22mfile pointer (SLANG_FILEPTR_TYPE) is actually a memory
        managed object.  For this reason, SLang_pop_fileptr also returns
        the memory managed object via the argument list.  It is up to
        the calling routine to call SLang_free_mmt to free the object.

      [1mExample[0m
        The following example illustrates an application defined
        intrinsic function that writes a user defined double precision
        number to a file.  Note the use of SLang_free_mmt:

               int write_double (void)
               {
                  double t;
                  SLang_MMT_Type *mmt;
                  FILE *fp;
                  int status;

                  if (-1 == SLang_pop_double (&d, NULL, NULL))
                    return -1;
                  if (-1 == SLang_pop_fileptr (&mmt, &fp))
                    return -1;

                  status = fwrite (&d, sizeof (double), 1, fp);
                  SLang_free_mmt (mmt);
                  return status;
               }

     This function can be used by a [1mS-Lang [22mfunction as follows:
               define write_some_values ()
               {
                  variable fp, d;

                  fp = fopen ("myfile.dat", "wb");
                  if (fp == NULL)
                    error ("file failed to open");
                  for (d = 0; d < 10.0; d += 0.1)
                    {
                       if (-1 == write_double (fp, d))
                         error ("write failed");
                    }
                  if (-1 == fclose (fp))
                    error ("fclose failed");
               }

      [1mSee Also[0m
        SLang_free_mmt, SLang_pop_double

  [1m5.44.  SLadd_intrinsic_function[0m

      [1mSynopsis[0m
        Add a new intrinsic function to the interpreter

      [1mUsage[0m
        int SLadd_intrinsic_function (name, f, type, nargs, ...)

              char *name
              FVOID_STAR f
              SLtype type
              unsigned int nargs

      [1mDescription[0m
        The SLadd_intrinsic_function function may be used to add a new
        intrinsic function.  The [1mS-Lang [22mname of the function is
        specified by name and the actual function pointer is given by f,
        cast to FVOID_STAR.  The third parameter, type specifies the
        return type of the function and must be one of the following
        values:

              SLANG_VOID_TYPE   (returns nothing)
              SLANG_INT_TYPE    (returns int)
              SLANG_DOUBLE_TYPE (returns double)
              SLANG_STRING_TYPE (returns char *)

     The nargs parameter specifies the number of parameters to pass to
     the function.  The variable argument list following nargs must con-
     sists of nargs integers which specify the data type of each argu-
     ment.

     The function returns zero upon success or -1 upon failure.
      [1mExample[0m
        The [1mjed [22meditor uses this function to change the system intrinsic
        function to the following:

               static int jed_system (char *cmd)
               {
                  if (Jed_Secure_Mode)
                    {
                       msg_error ("Access denied.");
                       return -1;
                    }
                  return SLsystem (cmd);
               }

     After initializing the interpreter with SLang_init_slang, [1mjed [22mcalls
     SLadd_intrinsic_function to substitute the above definition for the
     default [1mS-Lang [22mdefinition:

               if (-1 == SLadd_intrinsic_function ("system", (FVOID_STAR)jed_system,
                                                   SLANG_INT_TYPE, 1,
                                                   SLANG_STRING_TYPE))
                 return -1;

      [1mSee Also[0m
        SLadd_intrinsic_variable, SLadd_intrinsic_array

  [1m5.45.  SLadd_intrinsic_variable[0m

      [1mSynopsis[0m
        Add an intrinsic variable to the interpreter

      [1mUsage[0m
        int SLadd_intrinsic_variable (name, addr, type, rdonly)

              char *name
              VOID_STAR addr
              SLtype type
              int rdonly

      [1mDescription[0m
        The SLadd_intrinsic_variable function adds an intrinsic variable
        called name to the interpeter.  The second parameter addr
        specifies the address of the variable (cast to VOID_STAR).  The
        third parameter, type, specifies the data type of the variable.
        If the fourth parameter, rdonly, is non-zero, the variable will
        interpreted by the interpreter as read-only.

        If successful, SLadd_intrinsic_variable returns zero, otherwise
        it returns -1.

      [1mExample[0m
        Suppose that My_Global_Int is a global variable (at least not a
        local one):

              int My_Global_Int;

     It can be added to the interpreter via the function call

              if (-1 == SLadd_intrinsic_variable ("MyGlobalInt",
                                                  (VOID_STAR)&My_Global_Int,
                                                  SLANG_INT_TYPE, 0))
                exit (1);

      [1mNotes[0m
        The current implementation requires all pointer type intrinsic
        variables to be read-only.  For example,

              char *My_Global_String;

     is of type SLANG_STRING_TYPE, and must be declared as read-only.
     Finally, not that

             char My_Global_Char_Buf[256];

     is [4mnot[24m a SLANG_STRING_TYPE object.  This difference is very impor-
     tant because internally the interpreter dereferences the address
     passed to it to get to the value of the variable.

      [1mSee Also[0m
        SLadd_intrinsic_function, SLadd_intrinsic_array

  [1m5.46.  SLclass_add_unary_op[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLclass_add_unary_op (SLtype,int (*) (int, SLtype,
        VOID_STAR, unsigned int, VOID_STAR), int (*) (int, SLtype,
        SLtype *));

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??
  [1m5.47.  SLclass_add_app_unary_op[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLclass_add_app_unary_op (SLtype, int (*) (int,SLtype,
        VOID_STAR, unsigned int,VOID_STAR),int (*) (int, SLtype, SLtype
        *));

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m5.48.  SLclass_add_binary_op[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLclass_add_binary_op (SLtype, SLtype,int (*)(int, SLtype,
        VOID_STAR, unsigned int,SLtype, VOID_STAR, unsigned
        int,VOID_STAR),int (*) (int, SLtype, SLtype, SLtype *));

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m5.49.  SLclass_add_math_op[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLclass_add_math_op (SLtype,int (*)(int,SLtype, VOID_STAR,
        unsigned int,VOID_STAR),int (*)(int, SLtype, SLtype *));

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m5.50.  SLclass_add_typecast[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLclass_add_typecast (SLtype, SLtype int (*)_PROTO((SLtype,
        VOID_STAR, unsigned int,SLtype, VOID_STAR)),int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m6.  Library Initialization Functions[0m

  [1m6.1.  SLang_init_slang[0m

      [1mSynopsis[0m
        Initialize the interpreter

      [1mUsage[0m
        int SLang_init_slang (void)

      [1mDescription[0m
        The SLang_init_slang function must be called by all applications
        that use the [1mS-Lang [22minterpreter.  It initializes the
        interpreter, defines the built-in data types, and adds a set of
        core intrinsic functions.

        The function returns 0 upon success, or -1 upon failure.

      [1mSee Also[0m
        SLang_init_slfile, SLang_init_slmath, SLang_init_slunix

  [1m6.2.  SLang_init_slfile[0m

      [1mSynopsis[0m
        Initialize the interpreter file I/O intrinsics

      [1mUsage[0m
        int SLang_init_slfile (void)

      [1mDescription[0m
        This function initializes the interpreters file I/O intrinsic
        functions.  This function adds intrinsic functions such as
        fopen, fclose, and fputs to the interpreter.  It returns 0 if
        successful, or -1 upon error.

      [1mNotes[0m
        Before this function can be called, it is first necessary to
        call SLang_init_slang.  It also adds the preprocessor symbol
        __SLFILE__ to the interpreter.

      [1mSee Also[0m
        SLang_init_slang, SLang_init_slunix, SLang_init_slmath

  [1m6.3.  SLang_init_slmath[0m

      [1mSynopsis[0m
        Initialize the interpreter math intrinsics

      [1mUsage[0m
        int SLang_init_slmath (void)

      [1mDescription[0m
        The SLang_init_slmath function initializes the interpreter's
        mathematical intrinsic functions and makes them available to the
        language.  The intrinsic functions include sin, cos, tan, etc...
        It returns 0 if successful, or -1 upon failure.

      [1mNotes[0m
        This function must be called after SLang_init_slang.  It adds
        the preprocessor symbol __SLMATH__ to the interpreter.

      [1mSee Also[0m
        SLang_init_slang, SLang_init_slfile, SLang_init_slunix

  [1m6.4.  SLang_init_slunix[0m

      [1mSynopsis[0m
        Make available some unix system calls to the interpreter

      [1mUsage[0m
        int SLang_init_slunix (void)

      [1mDescription[0m
        The SLang_init_slunix function initializes the interpreter's
        unix system call intrinsic functions and makes them available to
        the language.  Examples of functions made available by
        SLang_init_slunix include chmod, chown, and stat_file.  It
        returns 0 if successful, or -1 upon failure.

      [1mNotes[0m
        This function must be called after SLang_init_slang.  It adds
        the preprocessor symbol __SLUNIX__ to the interpreter.

      [1mSee Also[0m
        SLang_init_slang, SLang_init_slfile, SLang_init_slmath

  [1m7.  Miscellaneous Functions[0m

  [1m7.1.  SLcurrent_time_string[0m

      [1mSynopsis[0m
        Get the current time as a string

      [1mUsage[0m
        char *SLcurrent_time_string (void)

      [1mDescription[0m
        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.

      [1mSee Also[0m
        SLmake_string

  [1m7.2.  SLatoi[0m

      [1mSynopsis[0m
        Convert a text string to an integer

      [1mUsage[0m
        int SLatoi(unsigned char *str

      [1mDescription[0m
        SLatoi parses the string str to interpret it as an integer
        value.  Unlike atoi, SLatoi can also parse strings containing
        integers expressed in hexidecimal (e.g., "0x7F") and octal
        (e.g., "012".)  notation.

      [1mSee Also[0m
        SLang_guess_type

  [1m7.3.  SLextract_list_element[0m

      [1mSynopsis[0m
        Extract a substring of a delimited string

      [1mUsage[0m
        int SLextract_list_element (dlist, nth, delim, buf, buflen)

              char *dlist;
              unsigned int nth;
              char delim;
              char *buf;
              unsigned int buflen;

      [1mDescription[0m
        SLextract_list_element may be used to obtain the nth element of
        a list of strings, dlist, that are delimited by the character
        delim.  The routine copies the nth element of dlist to the
        buffer buf whose size is buflen characters.  It returns zero
        upon success, or -1 if dlist does not contain an nth element.

      [1mExample[0m
        A delimited list of strings may be turned into an array of
        strings as follows.  For conciseness, all malloc error checking
        has been omitted.

              int list_to_array (char *list, char delim, char ***ap)
              {
                 unsigned int nth;
                 char **a;
                 char buf[1024];

                 /* Determine the size of the array */
                 nth = 0;
                 while (0 == SLextract_list_element (list, nth, delim, buf, sizeof(buf)))
                   nth++;

                 ap = (char **) SLmalloc ((nth + 1) * sizeof (char **));
                 nth = 0;
                 while (0 == SLextract_list_element (list, nth, delim, buf, sizeof(buf)))
                   {
                       a[nth] = SLmake_string (buf);
                       nth++;
                   }
                 a[nth] = NULL;
                 *ap = a;
                 return 0;
              }

      [1mSee Also[0m
        SLmalloc, SLmake_string

  [1m8.  Error and Messaging Functions[0m

  [1m8.1.  SLang_verror[0m

      [1mSynopsis[0m
        Signal an error with a message

      [1mUsage[0m
        void SLang_verror (int code, char *fmt, ...);

      [1mDescription[0m
        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.

      [1mExample[0m

                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;
                }

      [1mSee Also[0m
        SLang_vmessage, SLang_exit_error

  [1m8.2.  SLang_doerror[0m

      [1mSynopsis[0m
        Signal an error

      [1mUsage[0m
        void SLang_doerror (char *err_str)

      [1mDescription[0m
        The SLang_doerror function displays the string err_str to the
        error device and signals a [1mS-Lang [22merror.

      [1mNotes[0m
        SLang_doerror is considered to obsolete.  Applications should
        use the SLang_verror function instead.

      [1mSee Also[0m
        SLang_verror, SLang_exit_error

  [1m8.3.  SLang_vmessage[0m

      [1mSynopsis[0m
        Display a message to the message device

      [1mUsage[0m
        void SLang_vmessage (char *fmt, ...)

      [1mDescription[0m
        This function prints a printf style formatted variable argument
        list to the message device.  The default message device is
        stdout.

      [1mSee Also[0m
        SLang_verror

  [1m8.4.  SLang_exit_error[0m

      [1mSynopsis[0m
        Exit the program and display an error message

      [1mUsage[0m
        void SLang_exit_error (char *fmt, ...)

      [1mDescription[0m
        The SLang_exit_error function terminates the program and
        displays an error message using a printf type variable argument
        list.  The default behavior to this function is to write the
        message to stderr and exit with the exit system call.

        If the function pointer SLang_Exit_Error_Hook is non-NULL, the
        function to which it points will be called.  This permits an
        application to perform whatever cleanup is necessary.  This hook
        has the prototype:

               void (*SLang_Exit_Error_Hook)(char *, va_list);

      [1mSee Also[0m
        SLang_verror, exit

  [1m9.  String and Memory Allocation Functions[0m

  [1m9.1.  SLmake_string[0m

      [1mSynopsis[0m
        Duplicate a string

      [1mUsage[0m
        char *SLmake_string (char *s)

      [1mDescription[0m
        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.

      [1mNotes[0m
        SLmake_string should not be confused with the function
        SLang_create_slstring, which performs a similar function.

      [1mSee Also[0m
        SLmake_nstring, SLfree, SLmalloc, SLang_create_slstring

  [1m9.2.  SLmake_nstring[0m

      [1mSynopsis[0m
        Duplicate a substring

      [1mUsage[0m
        char *SLmake_nstring (char *s, unsigned int n)

      [1mDescription[0m
        This function is like SLmake_string 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 SLfree.

      [1mSee Also[0m
        SLmake_string, SLfree, SLang_create_nslstring

  [1m9.3.  SLang_create_nslstring[0m

      [1mSynopsis[0m
        Created a hashed substring

      [1mUsage[0m
        char *SLang_create_nslstring (char *s, unsigned int n)

      [1mDescription[0m
        SLang_create_nslstring is like SLang_create_slstring except that
        only the first n characters of s are used to create the hashed
        string.  Upon error, it returns NULL, otherwise it returns the
        hashed substring.  Such a string must be freed by the function
        SLang_free_slstring.

      [1mNotes[0m
        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.

      [1mSee Also[0m
        SLang_free_slstring, SLang_create_slstring, SLmake_nstring

  [1m9.4.  SLang_create_slstring[0m

      [1mSynopsis[0m
        Create a hashed string

      [1mUsage[0m
        char *SLang_create_slstring (char *s)

      [1mDescription[0m
        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.

      [1mNotes[0m
        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.

      [1mSee Also[0m
        SLang_free_slstring, SLang_create_nslstring, SLmake_string

  [1m9.5.  SLang_free_slstring[0m

      [1mSynopsis[0m
        Free a hashed string

      [1mUsage[0m
        void SLang_free_slstring (char *s)
      [1mDescription[0m
        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.

      [1mSee Also[0m
        SLang_create_slstring, SLang_create_nslstring,
        SLang_create_static_slstring

  [1m9.6.  SLang_concat_slstrings[0m

      [1mSynopsis[0m
        Concatenate two strings to produce a hashed string

      [1mUsage[0m
        char *SLang_concat_slstrings (char *a, char *b)

      [1mDescription[0m
        The SLang_concat_slstrings function concatenates two strings, a
        and b, and returns the result as a hashed string.  Upon failure,
        NULL is returned.

      [1mNotes[0m
        A hashed string can only be freed using SLang_free_slstring.
        Never use free or SLfree to free a hashed string, otherwise
        memory corruption will result.

      [1mSee Also[0m
        SLang_free_slstring, SLang_create_slstring

  [1m9.7.  SLang_create_static_slstring[0m

      [1mSynopsis[0m
        Create a hashed string

      [1mUsage[0m
        char *SLang_create_static_slstring (char *s_literal)

      [1mDescription[0m
        The SLang_create_static_slstring creates a hashed string from
        the string literal s_literal and returns the result.  Upon
        failure it returns NULL.

      [1mExample[0m

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

      [1mNotes[0m
        This function should only be used with string literals.

      [1mSee Also[0m
        SLang_create_slstring, SLang_create_nslstring

  [1m9.8.  SLmalloc[0m

      [1mSynopsis[0m
        Allocate some memory

      [1mUsage[0m
        char *SLmalloc (unsigned int nbytes)

      [1mDescription[0m
        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 use.

      [1mSee Also[0m
        SLfree, SLrealloc, SLcalloc

  [1m9.9.  SLcalloc[0m

      [1mSynopsis[0m
        Allocate some memory

      [1mUsage[0m
        char *SLcalloc (unsigned int num_elem, unsigned int elem_size)

      [1mDescription[0m
        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 use.

      [1mSee Also[0m
        SLmalloc, SLrealloc, SLfree

  [1m9.10.  SLfree[0m

      [1mSynopsis[0m
        Free some allocated memory

      [1mUsage[0m
        void SLfree (char *ptr)

      [1mDescription[0m
        The SLfree function deallocates the memory specified by ptr,
        which may be NULL in which case the function does nothing.

      [1mNotes[0m
        Never use this function to free a hashed string returned by one
        of the family of slstring functions, e.g., SLang_pop_slstring.

      [1mSee Also[0m
        SLmalloc, SLcalloc, SLrealloc, SLmake_string

  [1m9.11.  SLrealloc[0m

      [1mSynopsis[0m
        Resize a dynamic memory block

      [1mUsage[0m
        char *SLrealloc (char *ptr, unsigned int new_size)

      [1mDescription[0m
        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.

      [1mSee Also[0m
        SLfree, SLmalloc, SLcalloc

  [1m10.  Keyboard Input Functions[0m

  [1m10.1.  SLang_init_tty[0m

      [1mSynopsis[0m
        Initialize the terminal keyboard interface

      [1mUsage[0m
        int SLang_init_tty (int intr_ch, int no_flow_ctrl, int opost)

      [1mDescription[0m
        SLang_init_tty initializes the terminal for single character
        input.  If the first parameter intr_ch is in the range 0-255, it
        will be used as the interrupt character, e.g., under Unix this
        character will generate a SIGINT signal.  Otherwise, if it is
        -1, the interrupt character will be left unchanged.

        If the second parameter no_flow_ctrl is non-zero, flow control
        (XON/XOFF) processing will be enabled.

        If the last parmeter opost is non-zero, output processing by the
        terminal will be enabled.  If one intends to use this function
        in conjunction with the [1mS-Lang [22mscreen management routines
        (SLsmg), this paramete shold be set to zero.

        SLang_init_tty returns zero upon success, or -1 upon error.

      [1mNotes[0m
        Terminal I/O is a complex subject.  The [1mS-Lang [22minterface
        presents a simplification that the author has found useful in
        practice.  For example, the only special character processing
        that SLang_init_tty enables is that of the SIGINT character, and
        the generation of other signals via the keyboard is disabled.
        However, generation of the job control signal SIGTSTP is
        possible via the SLtty_set_suspend_state function.

        Under Unix, the integer variable SLang_TT_Read_FD is used to
        specify the input descriptor for the terminal.  If
        SLang_TT_Read_FD represents a terminal device as determined via
        the isatty system call, then it will be used as the terminal
        file descriptor.  Otherwise, the terminal device /dev/tty will
        used as the input device.  The default value of SLang_TT_Read_FD
        is -1 which causes /dev/tty to be used.  So, if you prefer to
        use stdin for input, then set SLang_TT_Read_FD to fileno(stdin)
        [4mbefore[24m calling SLang_init_tty.

        If the variable SLang_TT_Baud_Rate is zero when this function is
        called, the function will attempt to determine the baud rate by
        querying the terminal driver and set SLang_TT_Baud_Rate to that
        value.

      [1mSee Also[0m
        SLang_reset_tty, SLang_getkey, SLtty_set_suspend_state

  [1m10.2.  SLang_reset_tty[0m

      [1mSynopsis[0m
        Reset the terminal

      [1mUsage[0m
        void SLang_reset_tty (void)

      [1mDescription[0m
        SLang_reset_tty resets the terminal interface back to the state
        it was in before SLang_init_tty was called.

      [1mSee Also[0m
        SLang_init_tty

  [1m10.3.  SLtty_set_suspend_state[0m

      [1mSynopsis[0m
        Enable or disable keyboard suspension

      [1mUsage[0m
        void SLtty_set_suspend_state (int s)

      [1mDescription[0m
        The SLtty_set_suspend_state function may be used to enable or
        disable keyboard generation of the SIGTSTP job control signal.
        If s is non-zero, generation of this signal via the terminal
        interface will be enabled, otherwise it will be disabled.

        This function should only be called after the terminal driver
        has be initialized via SLang_init_tty.  The SLang_init_tty
        always disables the generation of SIGTSTP via the keyboard.

      [1mSee Also[0m
        SLang_init_tty
  [1m10.4.  SLang_getkey[0m

      [1mSynopsis[0m
        Read a character from the keyboard

      [1mUsage[0m
        unsigned int SLang_getkey (void);

      [1mDescription[0m
        The SLang_getkey reads a single character from the terminal and
        returns it.  The terminal must first be initialized via a call
        to SLang_init_tty before this function can be called.  Upon
        success, SLang_getkey returns the character read from the
        terminal, otherwise it returns SLANG_GETKEY_ERROR.

      [1mSee Also[0m
        SLang_init_tty, SLang_input_pending, SLang_ungetkey

  [1m10.5.  SLang_ungetkey_string[0m

      [1mSynopsis[0m
        Unget a key string

      [1mUsage[0m
        int SLang_ungetkey_string (unsigned char *buf, unsigned int n)

      [1mDescription[0m
        The SLang_ungetkey_string function may be used to push the n
        characters pointed to by buf onto the buffered input stream that
        SLgetkey uses.  If there is not enough room for the characters,
        -1 is returned and none are buffered.  Otherwise, it returns
        zero.

      [1mNotes[0m
        The difference between SLang_buffer_keystring and
        SLang_ungetkey_string is that the SLang_buffer_keystring appends
        the characters to the end of the getkey buffer, whereas
        SLang_ungetkey_string inserts the characters at the beginning of
        the input buffer.

      [1mSee Also[0m
        SLang_ungetkey, SLang_getkey

  [1m10.6.  SLang_buffer_keystring[0m

      [1mSynopsis[0m
        Append a keystring to the input buffer

      [1mUsage[0m
        int SLang_buffer_keystring (unsigned char *b, unsigned int len)

      [1mDescription[0m
        SLang_buffer_keystring places the len characters specified by b
        at the [4mend[24m of the buffer that SLang_getkey uses.  Upon success
        it returns 0; otherwise, no characters are buffered and it
        returns -1.

      [1mNotes[0m
        The difference between SLang_buffer_keystring and
        SLang_ungetkey_string is that the SLang_buffer_keystring appends
        the characters to the end of the getkey buffer, whereas
        SLang_ungetkey_string inserts the characters at the beginning of
        the input buffer.

      [1mSee Also[0m
        SLang_getkey, SLang_ungetkey, SLang_ungetkey_string

  [1m10.7.  SLang_ungetkey[0m

      [1mSynopsis[0m
        Push a character back onto the input buffer

      [1mUsage[0m
        int SLang_ungetkey (unsigned char ch)

      [1mDescription[0m
        SLang_ungetkey pushes the character ch back onto the SLgetkey
        input stream.  Upon success, it returns zero, otherwise it
        returns 1.

      [1mExample[0m
        This function is implemented as:

              int SLang_ungetkey (unsigned char ch)
              {
                 return SLang_ungetkey_string(&ch, 1);
              }

      [1mSee Also[0m
        SLang_getkey, SLang_ungetkey_string

  [1m10.8.  SLang_flush_input[0m

      [1mSynopsis[0m
        Discard all keyboard input waiting to be read

      [1mUsage[0m
        void SLang_flush_input (void)

      [1mDescription[0m
        SLang_flush_input discards all input characters waiting to be
        read by the SLang_getkey function.

      [1mSee Also[0m
        SLang_getkey

  [1m10.9.  SLang_input_pending[0m

      [1mSynopsis[0m
        Check to see if input is pending

      [1mUsage[0m
        int SLang_input_pending (int tsecs)

      [1mDescription[0m
        SLang_input_pending may be used to see if an input character is
        available to be read without causing SLang_getkey to block.  It
        will wait up to tsecs tenths of a second if no characters are
        immediately available for reading.  If tsecs is less than zero,
        then SLang_input_pending will wait -tsecs milliseconds for
        input, otherwise tsecs represents 1/10 of a second intervals.

      [1mNotes[0m
        Not all systems support millisecond resolution.

      [1mSee Also[0m
        SLang_getkey

  [1m10.10.  SLang_set_abort_signal[0m

      [1mSynopsis[0m
        Set the signal to trap SIGINT

      [1mUsage[0m
        void SLang_set_abort_signal (void (*f)(int));

      [1mDescription[0m
        SLang_set_abort_signal sets the function that gets triggered
        when the user presses the interrupt key (SIGINT) to the function
        f.  If f is NULL the default handler will get installed.

      [1mExample[0m
        The default interrupt handler on a Unix system is:

               static void default_sigint (int sig)
               {
                  SLKeyBoard_Quit = 1;
                  if (SLang_Ignore_User_Abort == 0) SLang_Error = SL_USER_BREAK;
                  SLsignal_intr (SIGINT, default_sigint);
             }

      [1mNotes[0m
        For Unix programmers, the name of this function may appear
        misleading since it is associated with SIGINT and not SIGABRT.
        The origin of the name stems from the original intent of the
        function: to allow the user to abort the running of a [1mS-Lang[0m
        interpreter function.

      [1mSee Also[0m
        SLang_init_tty, SLsignal_intr

  [1m11.  Keymap Functions[0m

  [1m11.1.  SLkm_define_key[0m

      [1mSynopsis[0m
        Define a key in a keymap

      [1mUsage[0m
        int SLkm_define_key (char *seq, FVOID_STAR f, SLKeyMap_List_Type
        *km)

      [1mDescription[0m
        SLkm_define_key associates the key sequence seq with the
        function pointer f in the keymap specified by km.  Upon success,
        it returns zero, otherwise it returns a negative integer upon
        error.

      [1mSee Also[0m
        SLkm_define_keysym, SLang_define_key

  [1m11.2.  SLang_define_key[0m

      [1mSynopsis[0m
        Define a key in a keymap

      [1mUsage[0m
        int SLang_define_key(char *seq, char *fun, SLKeyMap_List_Type
        *km)

      [1mDescription[0m
        SLang_define_key associates the key sequence seq with the
        function whose name is fun in the keymap specified by km.

      [1mSee Also[0m
        SLkm_define_keysym, SLkm_define_key

  [1m11.3.  SLkm_define_keysym[0m

      [1mSynopsis[0m
        Define a keysym in a keymap

      [1mUsage[0m
        int SLkm_define_keysym (seq, ks, km)

                char *seq;
                unsigned int ks;
                SLKeyMap_List_Type *km;

      [1mDescription[0m
        SLkm_define_keysym associates the key sequence seq with the
        keysym ks in the keymap km.  Keysyms whose value is less than or
        equal to 0x1000 is reserved by the library and should not be
        used.

      [1mSee Also[0m
        SLkm_define_key, SLang_define_key

  [1m11.4.  SLang_undefine_key[0m

      [1mSynopsis[0m
        Undefined a key from a keymap

      [1mUsage[0m
        void SLang_undefine_key(char *seq, SLKeyMap_List_Type *km);

      [1mDescription[0m
        SLang_undefine_key removes the key sequence seq from the keymap
        km.

      [1mSee Also[0m
        SLang_define_key

  [1m11.5.  SLang_create_keymap[0m

      [1mSynopsis[0m
        Create a new keymap

      [1mUsage[0m
        SLKeyMap_List_Type *SLang_create_keymap (name, km)

               char *name;
               SLKeyMap_List_Type *km;

      [1mDescription[0m
        SLang_create_keymap creates a new keymap called name by copying
        the key definitions from the keymap km.  If km is NULL, the
        newly created keymap will be empty and it is up to the calling
        routine to initialize it via the SLang_define_key and
        SLkm_define_keysym functions.  SLang_create_keymap returns a
        pointer to the new keymap, or NULL upon failure.

      [1mSee Also[0m
        SLang_define_key, SLkm_define_keysym

  [1m11.6.  SLang_do_key[0m

      [1mSynopsis[0m
        Read a keysequence and return its keymap entry

      [1mUsage[0m
        SLang_Key_Type *SLang_do_key (kml, getkey)

          SLKeyMap_List_Type *kml;
          int (*getkey)(void);

      [1mDescription[0m
        The SLang_do_key function reads characters using the function
        specified by the getkey function pointer and uses the key
        sequence to return the appropriate entry in the keymap specified
        by kml.

        SLang_do_key returns NULL if the key sequence is not defined by
        the keymap, otherwise it returns a pointer to an object of type
        SLang_Key_Type, which is defined in slang.h as

               #define SLANG_MAX_KEYMAP_KEY_SEQ 14
               typedef struct SLang_Key_Type
               {
                 struct SLang_Key_Type *next;
                 union
                 {
                    char *s;
                    FVOID_STAR f;
                    unsigned int keysym;
                 }
                 f;
                 unsigned char type;             /* type of function */
               #define SLKEY_F_INTERPRET  0x01
               #define SLKEY_F_INTRINSIC  0x02
               #define SLKEY_F_KEYSYM     0x03
                 unsigned char str[SLANG_MAX_KEYMAP_KEY_SEQ + 1];/* key sequence */
               }
          SLang_Key_Type;

     The type field specifies which field of the union f should be used.
     If type is SLKEY_F_INTERPRET, then f.s is a string that should be
     passed to the interpreter for evaluation.  If type is
     SLKEY_F_INTRINSIC, then f.f refers to function that should be
     called.  Otherwise, type is SLKEY_F_KEYSYM and f.keysym represents
     the value of the keysym that is associated with the key sequence.

      [1mSee Also[0m
        SLkm_define_keysym, SLkm_define_key

  [1m11.7.  SLang_find_key_function[0m

      [1mSynopsis[0m
        Obtain a function pointer associated with a keymap

      [1mUsage[0m
        FVOID_STAR SLang_find_key_function (fname, km);

              char *fname;
              SLKeyMap_List_Type *km;

      [1mDescription[0m
        The SLang_find_key_function routine searches through the
        SLKeymap_Function_Type list of functions associated with the
        keymap km for the function with name fname.  If a matching
        function is found, a pointer to the function will be returned,
        otherwise SLang_find_key_function will return NULL.

      [1mSee Also[0m
        SLang_create_keymap, SLang_find_keymap

  [1m11.8.  SLang_find_keymap[0m

      [1mSynopsis[0m
        Find a keymap

      [1mUsage[0m
        SLKeyMap_List_Type *SLang_find_keymap (char *keymap_name);

      [1mDescription[0m
        The SLang_find_keymap function searches through the list of
        keymaps looking for one whose name is keymap_name.  If a
        matching keymap is found, the function returns a pointer to the
        keymap.  It returns NULL if no such keymap exists.

      [1mSee Also[0m
        SLang_create_keymap, SLang_find_key_function

  [1m11.9.  SLang_process_keystring[0m

      [1mSynopsis[0m
        Un-escape a key-sequence

      [1mUsage[0m
        char *SLang_process_keystring (char *kseq);

      [1mDescription[0m
        The SLang_process_keystring function converts an escaped key
        sequence to its raw form by converting two-character
        combinations such as ^A to the [4msingle[24m character Ctrl-A (ASCII
        1).  In addition, if the key sequence contains constructs such
        as ^(XX), where XX represents a two-character termcap specifier,
        the termcap escape sequence will be looked up and substituted.

        Upon success, SLang_process_keystring returns a raw key-sequence
        whose first character represents the total length of the key-
        sequence, including the length specifier itself.  It returns
        NULL upon failure.

      [1mExample[0m
        Consider the following examples:

               SLang_process_keystring ("^X^C");
               SLang_process_keystring ("^[[A");

     The first example will return a pointer to a buffer of three
     characters whose ASCII values are given by {3,24,3}.  Similarly,
     the second example will return a pointer to the four characters
     {4,27,91,65}.  Finally, the result of

               SLang_process_keystring ("^[^(ku)");

     will depend upon the termcap/terminfo capability "ku", which repre-
     sents the escape sequence associated with the terminal's UP arrow
     key.  For an ANSI terminal whose UP arrow produces "ESC [ A", the
     result will be 5,27,27,91,65.

      [1mNotes[0m
        SLang_process_keystring returns a pointer to a static area that
        will be overwritten on subsequent calls.

      [1mSee Also[0m
        SLang_define_key, SLang_make_keystring

  [1m11.10.  SLang_make_keystring[0m

      [1mSynopsis[0m
        Make a printable key sequence

      [1mUsage[0m
        char *SLang_make_keystring (unsigned char *ks);

      [1mDescription[0m
        The SLang_make_keystring function takes a raw key sequence ks
        and converts it to a printable form by converting characters
        such as ASCII 1 (ctrl-A) to ^A.  That is, it performs the
        opposite function of SLang_process_keystring.

      [1mNotes[0m
        This function returns a pointer to a static area that will be
        overwritten on the next call to SLang_make_keystring.

      [1mSee Also[0m
        SLang_process_keystring

  [1m12.  Undocumented Functions[0m

  The following functions are not yet documented:

  [1m12.1.  SLprep_open_prep[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLprep_open_prep (SLPreprocess_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.2.  SLprep_close_prep[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLprep_close_prep (SLPreprocess_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.3.  SLprep_line_ok[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLprep_line_ok (char *, SLPreprocess_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.4.  SLdefine_for_ifdef[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLdefine_for_ifdef (char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.5.  SLang_Read_Line_Type * SLang_rline_save_line[0m
  [1m(SLang_RLine_Info_Type *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        SLang_Read_Line_Type * SLang_rline_save_line
        (SLang_RLine_Info_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.6.  int SLang_init_readline (SLang_RLine_Info_Type *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLang_init_readline (SLang_RLine_Info_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.7.  int SLang_read_line (SLang_RLine_Info_Type *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLang_read_line (SLang_RLine_Info_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.8.  int SLang_rline_insert (char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLang_rline_insert (char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.9.  void SLrline_redraw (SLang_RLine_Info_Type *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLrline_redraw (SLang_RLine_Info_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.10.  int SLtt_flush_output (void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLtt_flush_output (void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.11.  void SLtt_set_scroll_region(int, int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_set_scroll_region(int, int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.12.  void SLtt_reset_scroll_region(void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_reset_scroll_region(void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.13.  void SLtt_reverse_video (int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_reverse_video (int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.14.  void SLtt_bold_video (void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_bold_video (void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.15.  void SLtt_begin_insert(void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_begin_insert(void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.16.  void SLtt_end_insert(void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_end_insert(void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.17.  void SLtt_del_eol(void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_del_eol(void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.18.  void SLtt_goto_rc (int, int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_goto_rc (int, int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.19.  void SLtt_delete_nlines(int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_delete_nlines(int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.20.  void SLtt_delete_char(void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_delete_char(void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.21.  void SLtt_erase_line(void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_erase_line(void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.22.  void SLtt_normal_video(void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_normal_video(void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.23.  void SLtt_cls(void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_cls(void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.24.  void SLtt_beep(void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_beep(void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.25.  void SLtt_reverse_index(int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_reverse_index(int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.26.  void SLtt_smart_puts(unsigned short *, unsigned short *, int,[0m
  [1mint);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_smart_puts(unsigned short *, unsigned short *, int,
        int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.27.  void SLtt_write_string (char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_write_string (char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.28.  void SLtt_putchar(char);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_putchar(char);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.29.  int SLtt_init_video (void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLtt_init_video (void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.30.  int SLtt_reset_video (void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLtt_reset_video (void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.31.  void SLtt_get_terminfo(void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_get_terminfo(void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.32.  void SLtt_get_screen_size (void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_get_screen_size (void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.33.  int SLtt_set_cursor_visibility (int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLtt_set_cursor_visibility (int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.34.  int SLtt_initialize (char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLtt_initialize (char *);

      [1mDescription[0m
        ??
      [1mSee Also[0m
        ??

  [1m12.35.  void SLtt_enable_cursor_keys(void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_enable_cursor_keys(void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.36.  void SLtt_set_term_vtxxx(int *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_set_term_vtxxx(int *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.37.  void SLtt_set_color_esc (int, char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_set_color_esc (int, char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.38.  void SLtt_wide_width(void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_wide_width(void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.39.  void SLtt_narrow_width(void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_narrow_width(void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.40.  int SLtt_set_mouse_mode (int, int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLtt_set_mouse_mode (int, int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.41.  void SLtt_set_alt_char_set (int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_set_alt_char_set (int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.42.  int SLtt_write_to_status_line (char *, int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLtt_write_to_status_line (char *, int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.43.  void SLtt_disable_status_line (void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_disable_status_line (void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.44.  char *SLtt_tgetstr (char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        char *SLtt_tgetstr (char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.45.  int SLtt_tgetnum (char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLtt_tgetnum (char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.46.  int SLtt_tgetflag (char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLtt_tgetflag (char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.47.  char *SLtt_tigetent (char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        char *SLtt_tigetent (char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.48.  char *SLtt_tigetstr (char *, char **);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        char *SLtt_tigetstr (char *, char **);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.49.  int SLtt_tigetnum (char *, char **);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLtt_tigetnum (char *, char **);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.50.  SLtt_Char_Type SLtt_get_color_object (int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        SLtt_Char_Type SLtt_get_color_object (int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.51.  void SLtt_set_color_object (int, SLtt_Char_Type);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_set_color_object (int, SLtt_Char_Type);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.52.  void SLtt_set_color (int, char *, char *, char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_set_color (int, char *, char *, char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.53.  void SLtt_set_mono (int, char *, SLtt_Char_Type);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_set_mono (int, char *, SLtt_Char_Type);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.54.  void SLtt_add_color_attribute (int, SLtt_Char_Type);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_add_color_attribute (int, SLtt_Char_Type);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.55.  void SLtt_set_color_fgbg (int, SLtt_Char_Type,[0m
  [1mSLtt_Char_Type);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLtt_set_color_fgbg (int, SLtt_Char_Type, SLtt_Char_Type);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.56.  int SLkp_define_keysym (char *, unsigned int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLkp_define_keysym (char *, unsigned int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.57.  int SLkp_init (void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLkp_init (void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.58.  int SLkp_getkey (void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLkp_getkey (void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.59.  int SLscroll_find_top (SLscroll_Window_Type *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLscroll_find_top (SLscroll_Window_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.60.  int SLscroll_find_line_num (SLscroll_Window_Type *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLscroll_find_line_num (SLscroll_Window_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.61.  unsigned int SLscroll_next_n (SLscroll_Window_Type *, unsigned[0m
  [1mint);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        unsigned int SLscroll_next_n (SLscroll_Window_Type *, unsigned
        int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.62.  unsigned int SLscroll_prev_n (SLscroll_Window_Type *, unsigned[0m
  [1mint);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        unsigned int SLscroll_prev_n (SLscroll_Window_Type *, unsigned
        int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.63.  int SLscroll_pageup (SLscroll_Window_Type *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLscroll_pageup (SLscroll_Window_Type *);
      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.64.  int SLscroll_pagedown (SLscroll_Window_Type *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLscroll_pagedown (SLscroll_Window_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.65.  SLSig_Fun_Type *SLsignal (int, SLSig_Fun_Type *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        SLSig_Fun_Type *SLsignal (int, SLSig_Fun_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.66.  SLSig_Fun_Type *SLsignal_intr (int, SLSig_Fun_Type *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        SLSig_Fun_Type *SLsignal_intr (int, SLSig_Fun_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.67.  int SLsig_block_signals (void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLsig_block_signals (void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.68.  int SLsig_unblock_signals (void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLsig_unblock_signals (void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.69.  int SLsystem (char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLsystem (char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.70.  void SLadd_at_handler (long *, char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLadd_at_handler (long *, char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.71.  void SLang_define_case(int *, int *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLang_define_case(int *, int *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.72.  void SLang_init_case_tables (void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLang_init_case_tables (void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.73.  unsigned char *SLang_regexp_match(unsigned char *, unsigned[0m
  [1mint, SLRegexp_Type *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        unsigned char *SLang_regexp_match(unsigned char *, unsigned int,
        SLRegexp_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.74.  int SLang_regexp_compile (SLRegexp_Type *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLang_regexp_compile (SLRegexp_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.75.  char *SLregexp_quote_string (char *, char *, unsigned int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        char *SLregexp_quote_string (char *, char *, unsigned int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.76.  int SLcmd_execute_string (char *, SLcmd_Cmd_Table_Type *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLcmd_execute_string (char *, SLcmd_Cmd_Table_Type *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.77.  SLcomplex_abs[0m

      [1mSynopsis[0m
        Returns the norm of a complex number

      [1mUsage[0m
        double SLcomplex_abs (double *z)}

      [1mDescription[0m
        The SLcomplex_abs function returns the absolute value or the
        norm of the complex number given by z.
      [1mSee Also[0m
        SLcomplex_times

  [1m12.78.  double *SLcomplex_times (double *, double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_times (double *, double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.79.  double *SLcomplex_divide (double *, double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_divide (double *, double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.80.  double *SLcomplex_sin (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_sin (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.81.  double *SLcomplex_cos (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_cos (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.82.  double *SLcomplex_tan (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_tan (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.83.  double *SLcomplex_asin (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_asin (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.84.  double *SLcomplex_acos (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_acos (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.85.  double *SLcomplex_atan (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_atan (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.86.  double *SLcomplex_exp (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_exp (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.87.  double *SLcomplex_log (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_log (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.88.  double *SLcomplex_log10 (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_log10 (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.89.  double *SLcomplex_sqrt (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_sqrt (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.90.  double *SLcomplex_sinh (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_sinh (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.91.  double *SLcomplex_cosh (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_cosh (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.92.  double *SLcomplex_tanh (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_tanh (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.93.  double *SLcomplex_pow (double *, double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_pow (double *, double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.94.  double SLmath_hypot (double x, double y);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double SLmath_hypot (double x, double y);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  extern double *SLcomplex_asinh (double *, double *);

  [1m12.95.  double *SLcomplex_acosh (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_acosh (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.96.  double *SLcomplex_atanh (double *, double *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        double *SLcomplex_atanh (double *, double *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.97.  char *SLdebug_malloc (unsigned long);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        char *SLdebug_malloc (unsigned long);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.98.  char *SLdebug_calloc (unsigned long, unsigned long);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        char *SLdebug_calloc (unsigned long, unsigned long);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.99.  char *SLdebug_realloc (char *, unsigned long);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        char *SLdebug_realloc (char *, unsigned long);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.100.  void SLdebug_free (char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLdebug_free (char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.101.  void SLmalloc_dump_statistics (void);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLmalloc_dump_statistics (void);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.102.  char *SLstrcpy(register char *, register char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        char *SLstrcpy(register char *, register char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.103.  int SLstrcmp(register char *, register char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLstrcmp(register char *, register char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.104.  char *SLstrncpy(char *, register char *, register  int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        char *SLstrncpy(char *, register char *, register  int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.105.  void SLmemset (char *, char, int);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLmemset (char *, char, int);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.106.  void SLexpand_escaped_string (register char *, register char[0m
  [1m*, register char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLexpand_escaped_string (register char *, register char *,
        register char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.107.  void SLmake_lut (unsigned char *, unsigned char *, unsigned[0m
  [1mchar);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        void SLmake_lut (unsigned char *, unsigned char *, unsigned
        char);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

  [1m12.108.  int SLang_guess_type (char *);[0m

      [1mSynopsis[0m
        ??

      [1mUsage[0m
        int SLang_guess_type (char *);

      [1mDescription[0m
        ??

      [1mSee Also[0m
        ??

