Microsoft Programmer's Library 1.3/Microsoft-Programers-Library-v1.3.iso/sampcode/alde_c/misc/lib/dlibs/dlibs.doc

Text File | 1987-10-12 | 53.2 KB | 1,742 lines

 _________________________________________________________________________
|                                      |
| Replacement standard library functions for Atari ST with Alcyon C v4.14 |
|       Version 1.00.0, by Dale Schumacher, last modified 10/12/87.      |
|_________________________________________________________________________|



CONSTANTS:

    dLibs        Conditional complilation flag    (0x1000)
    TRUE        Boolean true            (1)
    FALSE        Boolean false            (0)
    ERROR        General error value        (-1)
    NULL        Null pointer            ((char *) 0)
    MAXFILES    Maximum number of open streams    (20)
    MAXINT        Maximum signed integer value    (32767)
    MININT        Minimum signed integer value    (-32768)
    BUFSIZ        Standard stream buffer size    (1024)
    PATHSIZE    Maximum size of a pathname    (128)
    EOF        End of file indicator        (-1)
    EOS        End of string character        '\0'


PROCESS CONTROL:

long _STKSIZ = 4096L;

    This variable defines the amount of run-time stack space to be
    reserved.  The default value is 4K, which is more than enough
    for most applications.  Since dynamic memory is NOT allocated
    from the stack, this value need only be large enough to handle
    local variables and deep recursion.

void _main(cmdline, cmdlen)
char *cmdline;
int cmdlen;

    Parses command line, opens standard files, plus other assorted
    general setup. Then calls user's main() function.  If main()
    returns, exit() is called with a 0 return value.  The following
    standard streams are initialized by _main():
        stdin        Standard input, may be redirected
        stdout        Standard output, may be redirected
        stderr        Usually the system console
        stdprn        The standard printer (output only)
        stdaux        The communication port (input/output)
    The _initargs() function is called to process the command line.
    The global variables "_argc", "_argv" and "_envp" are used to
    store the values to be passed to the user's main().

void _initargs(cmdline, cmdlen)
char *cmdline;
int cmdlen;

    Process command line and retrieve the environment string.  This
    function is responsible for allocating space to hold the parsed
    command line arguments, etc.  Values to be passed to the user's
    main() function are stored in the global variables "_argc",
    "_argv" and "_envp".  _main() initiallizes these variables to
    indicate that no arguments are available.  If a program doesn't
    use command line arguments or the environment string, an
    _initargs() function, which does nothing, should be defined in
    the module containing main().  This will result in a smaller
    executable size and a smaller run-time image.  The default
    _initargs() function handles command line redirection, but does
    not expand wildcards.  #ifdef's in the source code provide for
    elimination of redirection processing and/or addition of wildcard
    expansion. If these features are desired, a copy of _initargs(),
    appropriately modified for your application, should be placed
    in the module containing your main() function.

void main(argc, argv, envp)
int argc;
char *argv[];
char *envp;

    This function is not actually in the standard libraries, but
    must be present somewhere in the user's code.  The parameters
    passed to it by _main() are the number of arguments in the
    command line, a pointer to a list of pointers to arguments, and
    a pointer to the environment string.  The return value from
    main() is ignored by _main().  If the program wishes to return
    a status code, it should call exit() directly.

void exit(status)
int status;

    Flushes and closes all open streams.  Returns <status> value to
    the operating system.

void _exit(status)
int status;

    Exits the program immediately, returning <status> to the OS.

void abort()

    Prints the message "Abnormal program termination" to stderr and
    calls _exit() with a status code of 3.

int getpid()

    Return an integer value unique for this process.

char *getenv(var)
register char *var;

    Search for <var> in the environment.  If <var> is found, a pointer
    to it's value is returned.  NULL is returned if <var> is not found.
    WARNING:  The returned pointer points into the environment and
    must not be modified!

int putenv(entry)
char *entry;

    Add <entry> to the environment.  <entry> can be any of the following
    forms:
        <VARIABLE>
        <VARIABLE>=
        <VARIABLE>=<value>
    The first form removes <VARIABLE> from the environment.  getenv()
    will return NULL if looking for this variable.  The second form adds
    <VARIABLE> to the environment, with a null value.  getenv() will
    return a pointer to a '\0' character if looking for this variable.
    Many environment handlers don't support such "tag variables", so
    their use is not recommended.  The final form is the most common,
    and safest to use.  <VARIABLE> is installed (or replaced) with the
    value <value>.  It should be noted that the putenv() function itself
    is not supported in many systems and therefore may not be portable.
    In addition, care should be taken to prevent overflowing the space
    allocated for the environment.  Returns TRUE for success or FALSE
    for failure.  NO OVERFLOW CHECKING IS DONE.

void shell()

    Invoke a command line interface shell.  If the "SHELL" environment
    variable is not defined, a prompt showing the current working
    directory will be given.  Each line entered will then be passed
    to the system() function for execution until the command "exit"
    is entered to terminate the shell.  If "SHELL" is defined, and
    the "_shell_p" variable is valid, the value of "SHELL" will be
    passed to the program pointed to by "_shell_p" in order to allow
    the shell to invoke a command line interaction of its own.  If
    the "_shell_p" variable is not valid, the program defined by
    "SHELL" will be searched for along the "PATH", and executed with
    no arguments.  If the "SHELL" can't be found, the internal command
    line described above will be used.

int system(command)
char *command;

    Attempts to pass <command> to the shell program pointed to by
    the system variable "_shell_p".  If a valid shell can't be found
    there, the "SHELL" environment variable is searched for.  If it
    exists and is not empty, it will be the name of the shell program
    to execute the given command.  If "SHELL" is not valid, the
    "PATH" variable is searched for.  This would specify the paths
    to search for the program name which is the first token of the
    <command>.  If "PATH" is not valid, the current directory is
    searched for the given command.  The extensions tried (if none
    is specified) are ".TTP", ".TOS", ".PRG" and ".APP".

int spawne(program, cmdline, envp)
char *program;
char *cmdline;
char *envp;

    Calls the OS "Pexec" trap with the parameters specified.  Since
    the OS uses a Pascal-like string for the command line, the
    <cmdline> parameter, which is a normal C-string, is used to
    create the actual command line which is passed to the OS trap.
    Returns the value returned by the program, or -1 for errors.

int spawn(program, cmdline)
char *program;
char *cmdline;

    Like spawne() except that NULL is used for the environment pointer.
    This causes the child to inherit a copy of the parent's environment.

int spawnpe(program, cmdline, envp)
char *program;
char *cmdline;
char *envp;

    Operates like spawne() except that the "PATH" environment variable,
    if it is valid, is used to locate the program to be executed.
    Various extensions are tried, as described for system().  Returns
    the value returned by the program, or -1 for errors.

int spawnp(program, cmdline)
char *program;
char *cmdline;

    Like spawnpe() except that NULL is used for the environment pointer.
    This causes the child to inherit a copy of the parent's environment.

long gemdos(func[, arg1, ..., argN])
int func;

    Call operating system trap #1 (GEMDOS) function number <func> with
    the arguments given.  Returned value returned by the trap call.

long bios(func[, arg1, ..., argN])
int func;

    Call operating system trap #13 (BIOS) function number <func> with
    the arguments given.  Returned value returned by the trap call.

long xbios(func[, arg1, ..., argN])
int func;

    Call operating system trap #14 (XBIOS) function number <func> with
    the arguments given.  Returned value returned by the trap call.

int setjmp(context)
jmp_buf context;

    [save <context> for longjmp(). MUST include "SETJMP.H" to use.]

void longjmp(context, rv)
jmp_buf context;
int rv;

    [return <rv> to <context> saved by setjmp().
     MUST include "SETJMP.H" to use.]

int catch(context, func)
jmp_buf context;
int (*func)();

    [execute <func> with saved <context> for throw().
     MUST include "SETJMP.H" to use.]

void throw(context, func)
jmp_buf context;
int rv;

    [return <rv> to <context> saved by catch().
     MUST include "SETJMP.H" to use.]


MEMORY MANAGEMENT:

    You may want to include "MALLOC.H" in your program if you use
    functions in this section, otherwise you may have to declare
    the return types for some functions.

long _BLKSIZ = 65536;

    This variable controls the granularity of system memory allocation
    used by malloc(), et. al.  This is the amount of memory that is
    requested from the system each time a new "heap" is needed to fill
    dynamic memory requests.  To help avoid a GEMDOS bug, only 16
    heaps can be active at a time.  Therefore, (16 * _BLKSIZ) defines
    the maximum amount of memory which can be managed by these routines
    under normal circumstances.  The exception is if any single request
    for memory exceeds _BLKSIZ.  In this case, a heap will be allocated
    larger than _BLKSIZ.

char *malloc(size)
unsigned int size;

    Allocate at least <size> bytes of memory.  A pointer to the
    requested block is returned, or NULL if there is not enough
    free memory available.

char *calloc(n, size)
unsigned int n;
unsigned int size;

    Allocate space for an array of <n> element of <size> bytes each.
    If the storage can be allocated, it is initialized to all zero.
    NULL is returned is there is not enough free memory.

char *lalloc(size)
long size;

    Allocate at least <size> bytes of memory.  A pointer to the
    requested block is returned, or NULL if there is not enough
    free memory available.

char *realloc(addr, size)
char *addr;
unsigned int size;

    Attempt to change the memory block at <addr> to the new <size>.
    Making a block smaller will always work, but making it larger
    may fail if there is not enough free memory.  If there is not
    enough memory, NULL is returned and the block will still reside
    at <addr>.  If realloc() succeeds, a pointer to the (possibly
    moved) new block will be returned.

void free(addr)
char *addr;

    Release the memory block at <addr> back into the free memory pool.
    If <addr> doesn't point to a block allocated by calloc(), malloc(),
    lalloc() or realloc(), very bad, unpredictable things will happen.

long msize(addr)
char *addr;

    Return the size, in bytes, of the memory block at <addr>.  Note
    that the size is a long value, since the block may have been
    allocated by lalloc().

long memavail()

    Return the size, in bytes, of the largest block of free memory
    available for allocation.  Note that this value is a long.


FILE HANDLING:

    You may want to include "IO.H" in your program if you use
    functions in this section, otherwise you may have to declare
    the return types for some functions.  "IO.H" also contains
    the definitions of many symbolic constants used with these
    functions.

int chdir(pathname)
char *pathname;

    Changes the current working directory to <pathname>.  If a
    drive letter is specified in <pathname>, the current working
    directory for that drive is set.  Returns 0 for success, or
    a negative error code.

int mkdir(pathname)
char *pathname;

    Creates a new directory called <pathname>.  A drive letter may
    be specified.  Returns 0 for success, or a negative error code.

int rmdir(pathname)
char *pathname;

    Removes an existing directory called <pathname>.  A drive letter may
    be specified.  Returns 0 for success, or a negative error code.

char *fullpath(full, part)
char *full;
char *part;

    <part> is a (possibly) ambiguous file/path specification.  A
    non-ambiguous file/path spec is created which includes a drive
    letter and all intermediate sub-directories.  If the partial
    specification is not valid, NULL is returned, otherwise a
    pointer to <full> is returned.  If NULL is specified for <full>,
    an internal buffer is used and a pointer to it is returned.

int access(name, amode)
char *name;
int amode;

    Return non-zero if a file with the given <name> can be accessed
    in the given <amode>.  Possible <amode> values are:
        _ACCe        file exists
        _ACCr        file can be read
        _ACCw        file can be written
        _ACCrw        file can be read and written

char *findfile(afn[, ext])
char *afn;
char *ext;

    Return full file spec for <afn> if found. If <afn> has no extension,
    extensions from <ext> are tried until a match is found, or the list
    ends.  <ext> is a list of extensions separated by '\0' characters
    and ending with an additional '\0', ie. "ttp\0tos\0prg\0" (note that
    the final null is added by the compiler to any string constant.  If
    <afn> already has an extension, <ext> is not used.  If no matching
    files are found, NULL is returned.  The pointer returned when a match
    is found points to a buffer which is internal to fullpath().  If you
    want to save the value returned, you must make a copy before the
    buffer is overwritten by subsequent calls.

char *pfindfile(afn[, ext])
char *afn;
char *ext;

    Like findfile() but search all directories listed in the environment
    variable "PATH", if no match is found in the current directory. If
    <afn> specifies a drive or directory, "PATH" is not used.

int stat(name, statbuf)
char *name;
STAT *statbuf;

    Search for file <name> and load <statbuf> with information
    about that file, if it is found.  Return 0 if found, or
    ERROR (-1) if no file/directory matched <name>.  Volume
    labels are not included in the search.

long fsize(name)
char *name;

    Return the size of the file <name> in bytes.  Note that this
    is a long value.  Return -1L if the file is not found.

int isatty(h)
int h;

    Return non-zero if <h> refers to a character device.  Both the
    device handles (-1..-3) and the standard handles (0..5) are
    considered character devices by this function.

int creat(filename, pmode)
char *filename;
int pmode;

    Create a new file with the given <filename>.  If a file with
    the name already exists, it will be truncated to zero bytes.
    Since the OS doesn't do this properly, the file is actually
    deleted and then re-created.  <pmode> specifies the attributes
    initially given to the file.  Valid <pmode> values are:
        _CRErw        read/write
        _CREro        read only
        _CREh        hidden file
        _CREs        system file
        _CREv        volume label
    If _CRErw or _CREv modes are specified, they must be the only
    mode given.  Other modes may be combined with the | operator.

int chmod(filename, pmode)
char *filename;
int pmode;

    Change the mode attribute of <filename> to <pmode>.  Values for
    <pmode> are the same as for the creat() function.  Returns 0 for
    success, or a negative error code.

int open(filename, iomode)
char *filename;
int iomode;

    Attempt to open <filename> with the given <iomode>.  This is a
    direct hook into the OS "Fopen" call.  A file handle is returned
    if the open succeeds.  A negative error code is returned for
    errors.  Valid <iomode> values are:
        _OPNr        read mode
        _OPNw        write mode
        _OPNrw        read/write mode

int close(h)
int h;

    Close file referenced by the file handle <h>.  Return 0 for
    success, or a negative error code.

int dup(handle)
int handle;

    Return a second file handle which refers to the same file as
    the given <handle>.

int dup2(handle1, handle2)
int handle1;
int handle2;

    Force <handle2> to refer to the same file as <handle1>.  Return
    0 for success, or a negative error code.  Both dup() and dup2()
    are direct calls to Fdup() and Fforce() GEMDOS calls.  Refer to
    your GEMDOS documentation for further information.

int unlink(filename)
char *filename;

    Delete <filename>, if it exists.  Return 0 for success, or a
    negative error code.

int rename(oldname, newname)
char *oldname;
char *newname;

    Change the name of file <oldname> to <newname>.  You may use this
    function to move files from one directory (pathname) to another,
    but not from one drive to another.  Return 0 for success, or a
    negative error code.

long lseek(h, offset, origin)
int h;
long offset;
int origin;

    Move file pointer for file <h> to specified location.  <origin>
    specifies the starting point for the <offset> distance.  Valid
    <origin> values are:
        _LSKbeg        from beginning of file    (0)
        _LSKcur        from current location    (1)
        _LSKend        from end of file    (2)
    The <offset> value is the distance in bytes from the origin.
    The final file position, or a negative error code, is returned.

long tell(h)
int h;

    Return the current file position for the file <h>.

FILE *fopen(filename, mode)
char *filename;
char *mode;

    Open <filename> as a stream file.  This is the normal open way
    to open a file.  The <mode> is a string specifying the mode(s)
    that are relevent to the file open.  Valid <mode> characters are:
        r        read mode
        w        write mode
        a        append mode
        b        binary mode
        t        text (translated) mode
    At least one of "r", "w" or "a" must be specified.  "t" is assumed
    and indicates that <nl> is translated to <cr><lf> on output and
    vica-versa on input.  If the stream is a character device, the
    translation is slightly different.  The output translation is the
    same, but on input <cr> and <lf> both become <nl> in all cases.
    The "b", for binary mode, overides "t" and indicated that characters
    are not translated during i/o operations.  "a" represents append
    mode and means that the file pointer will initially be placed at
    the end of the file.  "w" mode will create a file if it doesn't
    exists, or zero an existing file.  If "r" is the only mode specified,
    the file must already exist.  A (FILE *) is returned if the open
    succeeds, or NULL if it fails.

FILE *freopen(filename, mode, fp)
char *filename;
char *mode;
FILE *fp;

    Closes the file associated with <fp> and opens the new file as with
    fopen(), except that a new FILE structure is not created.  The
    existing FILE structure pointed to by <fp> is re-initialized with
    the new file information.  This is typically used to redirect i/o
    to standard streams "stdin", "stdout", "stderr", "stdprn", "stdaux".
    <fp> is returned for success, or NULL for failure.

FILE *fdopen(h, mode)
int h;
char *mode;

    Associates a stream with the already open file <h>.  The <mode>
    values are the same as for fopen(), but MUST be compatible with
    the mode in which <h> was open()ed.  This functions allows use
    of a file opened with the low level open()/creat() calls to be
    used as a buffered/translated stream.  A pointer to a FILE struct
    is returned, or NULL for errors.

int fclose(fp)
FILE *fp;

    Close the stream <fp>, flushing the buffer.  Returns 0 on success.

void setbuf(fp, buf)
FILE *fp;
char *buf;

    If <buf> is NULL, make <fp> unbuffered; else <buf> points to a buffer
    of BUFSIZ characters to be used as the stream buffer for <fp>.

void setvbuf(fp, buf, bmode, size)
FILE *fp;
char *buf;
int bmode;
unsigned int size;

    If <buf> is NULL or <bmode> is _SVBn, make <fp> unbuffered;
    otherwise <buf> points to a buffer of <size> characters to be
    used as the stream buffer for <fp>.  The <bmode> variable
    indicates the type of buffering desired, as follows:
        _SVBn        No buffering
        _SVBf        Full buffering (normal)
        _SVBl        Line buffering (not supported, same as _SVBf)

long fseek(fp, offset, origin)
FILE *fp;
long offset;
int origin;

    Operates like lseek(), except it works on streams.  Note that
    stream file positions may be misleading due to translation of
    <nl> characters during i/o.  ftell() may be used reliably with
    fseek() to reposition a file to a prior location.

void rewind(fp)
FILE *fp;

    Operates like fseek(fp, 0L, _LSKbeg), except it also clears the
    end-of-file and error flags for <fp>.  There is no return value.

long ftell(fp)
FILE *fp;

    Operates like tell(), except it works on streams.  Note that
    stream file positions may be misleading due to translation of
    <nl> characters during i/o.

int fileno(fp)

    Return the file handle associated with the stream <fp>.

int feof(fp)

    Return non-zero if <fp>    is at end of file.

int ferror(fp)

    Return non-zero if and error has occurred on <fp>.

void clearerr(fp)

    Clear the error flag on <fp>.


INPUT/OUTPUT FUNCTIONS:

    You may want to include "IO.H" in your program if you use
    functions in this section, otherwise you may have to declare
    the return types for some functions.  "IO.H" also contains
    the definitions of many symbolic constants used with these
    functions.

int read(h, data, length)
int h;
char *data;
int length;

    Read <length> bytes from the file reference by file handle <h>.
    Data is stored in the buffer pointed to by <data>.  The number
    of bytes actually read is returned, 0 for end of file, or a
    negative error code.  Note that the maximum number of bytes
    that can be read by this function is MAXINT.

long lread(h, data, length)
int h;
char *data;
long length;

    Same as read(), but uses a long value for number of bytes to read.

int write(h, data, length)
int h;
char *data;
int length;

    Write <length> bytes to the file reference by file handle <h>.
    Data is written from the buffer pointed to by <data>.  The number
    of bytes actually written is returned, or a negative error code.
    Note that the maximum number of bytes that can be written by
    this function is MAXINT.

long lwrite(h, data, length)
int h;
char *data;
long length;

    Same as write(), but uses a long value for number of bytes to write.

int fread(data, size, count, fp)
char *data;
int size;
int count;
FILE *fp;

    Read <count> items of <size> characters each from stream <fp>.
    Data is stored in the buffer pointed to by <data>.  The number of
    full items actually read is returned, or a negative error code.
    This call DOES NOT translate characters, even if the stream is
    opened in translate mode.

int fwrite(data, size, count, fp)
char *data;
int size;
int count;
FILE *fp;

    Write <count> items of <size> characters each to stream <fp>.
    Data is read from the buffer pointed to by <data>.  The number of
    full items actually written is returned, or a negative error code.
    This call DOES NOT translate characters, even if the stream is
    opened in translate mode.

int fgetc(fp)
FILE *fp;

    Get a character from <fp>.  Returns the character or EOF.

int fungetc(c, fp)
char c;
FILE *fp;

    Push the character <c> back to be gotten by the next fgetc()
    call on <fp>.  Only 1 character may be ungotten at a time on
    each stream.  Subsequent calls to fungetc() will write over
    the currently saved character.

int fputc(c, fp)
char c;
FILE *fp;

    Put the character <c> to the stream <fp>.

int fflush(fp)
FILE *fp;

    Flush the output buffer of the stream <fp>.  The buffer is
    automatically flushed when it is full, the stream is closed,
    or the program terminates through exit().  This function has
    no effect if the stream in unbuffered.

int getc(fp)
FILE *fp;

    Same as fgetc() but implemented as a macro.

int ungetc(c, fp)
char c;
FILE *fp;

    Same as fungetc() but implemented as a macro.

int putc(c, fp)
char c;
FILE *fp;

    Same as fputc() but implemented as a macro.

int getw(fp)
FILE *fp;

    Get a 2-byte value from the stream <fp>.  The high-order byte is
    read first.

int putw(n, fp)
int n;
FILE *fp;

    Put the 2-byte value <n> to the stream <fp>.  The high-order byte
    is written first.

int getchar()

    Same as "fgetc(stdin)".

int ungetchar(c)
char c;

    Same as "fungetc(c, stdin)".  Note that this name will
    conflict with any function beginning "ungetch..." due to
    having only 7 significant characters in Alcyon C v4.14.

int putchar(c)
char c;

    Same as "fputc(c, stdin)".

int cfg_ch(cfg)
int cfg;

    Configure getch()/putch() operation.  The following are legal
    values for <cfg> and may be combined with the | operator:
        _CIOb        Use BIOS level i/o calls
        _CIOch        8-bit character codes only (cf:getch)
        _CIOvt        Enable VT-52 escape sequence processing
    The initial configuration value at run time is _CIOch.

int getch()

    Machine dependent console input function.  This function normally
    gets a character from the keyboard by calling the GEMDOS "Cconin"
    function.  If cfg_ch() is given the _CIOb option, input is gotten
    from the BIOS "Bconin" function instead.  The BIOS level functions
    don't process ^C, ^S or ^Q, while the GEMDOS functions do.  The
    most common use for getch() is when keyboard scan codes are needed
    to process special function keys.  The return value from getch()
    consists of the scan code in the high-order byte, and the ascii
    character code in the low-order byte.  If cfg_ch() is given the
    _CIOch option, the return value is always an 8-bit quantity,
    either the scan code with the 8th bit set, or the ascii code with
    the 8th bit clear.  This is somewhat less informative, since the
    scan code form is returned only if the ascii value is 0, but is the
    default configuration value for compatability with Microsoft C.
    In any case, the global unsigned long variable "_getch" will contain
    the full character code value returned by the OS.

int getche()

    Same as getch() but calls putch() to echo the character.

char putch(c)
char c;

    Machine dependent (typically quite fast) console output function.
    This function normally puts a character to the console by calling
    the GEMDOS "Cconout" function.  If cfg_ch() is given the _CIOb
    option, output is sent to the BIOS "Bconout" function instead.
    The BIOS level functions don't process ^C, ^S or ^Q, while the
    GEMDOS functions do.  At the BIOS level, the _CIOvt option to
    cfg_ch() allows VT-52 escape code processing on output.  The
    GEMDOS function always does VT-52 emulation.  The BIOS function
    defaults to skipping this overhead, but if VT-52 emulation is
    desired, it can still be used through the faster BIOS level
    routine    by using the _CIOvt option.  Control codes, like '\b'
    and '\r', are supported even without VT-52 emulation.  The return
    value of this function is simply the character sent.

int kbhit()

    Machine dependent function to detect if input is waiting for the
    getch() function.  Returns non-zero if the console has data ready.

char *getln(ip, get, put, buffer, limit)
char *ip;
int (*get)();
int (*put)();
char *buffer;
int limit;

    Get a line of input from the user.  Allow simple editing of the line
    with BS/DEL, ESC, and CR/LF to terminate input.  Characters are
    retreived by a (*get)(ip) and echoed with (*put)(c).  A pointer to
    <buffer> is returned in any case.

char *fgets(data, limit, fp)
char *data;
int limit;
FILE *fp;

    Get data from <fp> and puts it in the <data> buffer.  At most,
    <limit>-1 characters will be read.  Input will also be terminated
    when a newline is read.  <data> will be '\0' terminated and the
    newline, if read, will be included.  A pointer to the start of
    <data> is returned, or NULL for EOF.

void fputs(data, fp)
char *data;
FILE *fp;

    Write the characters in <data> to the stream <fp>.  A newline
    WILL NOT be added.

char *gets(data)
char *data;

    Get data from stdin and puts it in the <data> buffer.  Input is
    terminated when a newline is read.  The    newline will be replaced
    by a '\0' to terminate the string.  A backspace character will
    remove the preceeding character from the buffer, but will not
    backspace past the start of the buffer.  A pointer to the start
    of <data> is returned, or NULL for EOF.

void puts(data)
char *data;

    Write the characters in <data> to stdout.  A newline WILL be
    written after the data.

void cputs(data)
char *data;

    Write the characters in <data> directly to the console using the
    system dependent putch() function.  A newline WILL NOT be written
    after the data.

int fprintf(fp, fmt[, arg1, ..., argN])
FILE *fp;
char *fmt;

    Formatted output to the stream <fp>.  See the _printf() function
    for a description of the <fmt> formatting string.

int printf(fmt[, arg1, ..., argN])
char *fmt;

    Formatted output to the stdout stream.  See the _printf() function
    for a description of the <fmt> formatting string.

int sprintf(buf, fmt[, arg1, ..., argN])
char *buf;
char *fmt;

    Formatted output to the string <s>.  See the _printf() function
    for a description of the <fmt> formatting string.

int cprintf(fmt[, arg1, ..., argN])
char *fmt;

    Formatted output directly to the console.  This functions uses the
    system dependent putch() for output.  See the _printf() function
    for a description of the <fmt> formatting string.

int fscanf(fp, fmt[, arg1, ..., argN])
FILE *fp;
char *fmt;

    Formatted input from the stream <fp>.  See the _scanf() function
    for a description of the <fmt> formatting string.

int scanf(fmt[, arg1, ..., argN])
char *fmt;

    Formatted input from the stdin stream.  See the _scanf() function
    for a description of the <fmt> formatting string.

int sscanf(buf, fmt[, arg1, ..., argN])
char *buf;
char *fmt;

    Formatted input from the string <s>.  See the _scanf() function
    for a description of the <fmt> formatting string.


FORMATTING/TYPE CONVERSION:

int _printf(op, put, fmt, args)
char *op;
int (*put)();
char *fmt;
int *args;

    <fmt> points to a format control string.  <args> pointers to a
    list of arguments.  The format string is used to create and output
    stream with the arguments.  The <put> function is used to output
    each character.  The <op> parameter is given to the <put> function
    to specify the output stream.  Calls to <put> are of the form:
    "(*put)(c, op);" where <c> is the character to output.  The format
    string is composed of characters and format specifications.  The
    '%' character introduces a format specifier.  The general form of
    a format specifier is:
        %[-][ |+][0][<width>|*][.[<precision>|*]][l]{d|i|u|o|x|b|c|s}
    The '-' specifies left justification.  The ' ' or '+' specifies
    the character which preceeds positive numeric values.  The '0'
    specifies that numeric fields will be padded with '0' rather than
    ' '.  The <width> field is a numeric value specifying a minimum
    field width.  The <precision> field is a numeric value specifying
    the maximum number of data characters to display.  If '*' is
    specified for the width or the precision, an "int" value is taken
    from the argument list and used for that value.  If no width is
    specified, the field width varies according to the data width.  If
    no precision is specified, all data characters are included in the
    data width.  If the data width exceeds the field width, the field
    width will expand to allow all data characters to be printed.
    Including the 'l' or capitalizing the trailing character specifies
    that the associated value is a "long" type.  The trailing character
    specifies the format type, as follows:
        d    Signed decimal integer
        i    same as 'd'
        u    Unsigned decimal integer
        o    Unsigned octal integer
        x    Unsigned hexadecimal integer
        b    Unsigned binary integer
        c    Character
        s    String
    If the character following the '%' is not recognized, it is
    simply passed along to the output stream, thus "%%" is used to
    print a single '%' character.

char *ltoa(n, buffer, radix)
long n;
char *buffer;
int radix;

    Convert the long value <n> to a string in <buf> using <radix>
    as the number base.  If <n> is negative, '-' will be the first
    character in <buf>.  A pointer to <buf> is returned.

char *ultoa(n, buffer, radix)
unsigned long n;
char *buffer;
int radix;

    Convert the unsigned long value <n> to a string in <buf> using
    <radix>    as the number base.  A pointer to <buf> is returned.

char *itoa(n, buffer, radix)
int n;
char *buffer;
int radix;

    Convert the integer value <n> to a string in <buf> using <radix>
    as the number base.  If <n> is negative, '-' will be the first
    character in <buf>.  A pointer to <buf> is returned.

long atol(number)
char *number;

    Convert the string <number> to a long value.  Leading whitespace
    is ignored, a leading +/- is optional.  Characters are processed
    until a non-digit is reached.  Return value is undefined in an
    overflow situation.

int atoi(number)
char *number;

    Convert the string <number> to an int value.  Leading whitespace
    is ignored, a leading +/- is optional.  Characters are processed
    until a non-digit is reached.  Return value is undefined in an
    overflow situation.

int _scanf(ip, get, unget, fmt, args)
char *ip;
int (*get)();
int (*unget)();
char *fmt;
char **args;

    <fmt> points to a format control string.  <args> pointers to a
    list of arguments, each of which is the address of a variable in
    which input data may be stored.  The format string is used to
    control reading of characters from the <get> function.  As each
    character is needed <get> is called in the form "c = (*get)(ip);"
    where <c> is the character read (negative for errors) and <ip> is
    the auxiliary pointer specified by the <ip> parameter.  If a
    character needs to be un-gotten, a call to <unget> of the form
    "(*unget)(c, ip);" is made.  The format string is composed of
    characters and format specifications.  Any characters in <fmt>,
    except whitespace characters, which are not part of a format
    specifier are expected to be matched one-to-one by characters in
    the input stream.  Scanning terminates if a mismatch occurs or if
    any call to <get> results in an error.  Whitespace characters
    match 0 or more whitespace characters in the input stream.  The
    '%' character introduces a format specifier.  The general form
    of a format specifier is:
         %[*][<width>][l|h]{d|u|o|x|b|i|c|s}
    The '*' specifies that a field is to be scanned by not stored.
    No variable pointer should be provided for non-stored format
    specs.  The <width> field specifies that maximum number of
    characters to be process to fill the given format type.  Less
    than <width> characters will be processed if the field ends
    before <width> characters have been processed.  A field ends when
    either a whitespace character, or a character which does not fit
    the specified format, is read.  The preceding 'l' specifies that
    the associated variable is a "long" type.  The trailing character
    specifies the format type, as follows:
        d Signed decimal integer
        u Unsigned decimal integer
        o Unsigned octal integer
        x Unsigned hexadecimal integer
        b Unsigned binary integer
        i Unsigned decimal/octal/hexadecimal/binary integer
        c Character
        s String
    If a <width> is specified with the 'c' format, exactly <width>
    characters (including whitespace) are read from the input stream,
    and written to a string.  No '\0' character is added If the
    character following the '%' is not recognized, it is expected to
    match the input stream as a non-format character, thus "%%" is
    used to match a single '%' character.  One additional conversion is
    the brace-format.  Shown as "%[...]", the '...' represent a list of
    characters.  If the first character in the list is a '^', the field
    contains any characters NOT in the list (starting with the 1st
    character after the '^').  If the first character of the list is
    not a '^', then the field will only contain those characters found
    in the list.  The field will be stored as a null terminated string.
    Unlike most of the other formats, this conversion does allow the
    programmer to specify that whitespace characters will be included
    in the resulting string.

char *ctlcnv(string)
char *string;

    Convert \<char> notation in <string> to actual characters.  This
    is useful for reading strings from a stream when you want to allow
    insertion of control character or other characters that may have
    special meaning otherwise, or may not otherwise be allowed.  The
    following formats are supported:
        \n        newline or linefeed
        \r        carriage return
        \0        null character (value 0)
        \b        backspace
        \t        horizontal tab
        \v        vertical tab
        \f        form feed
        \a        alarm (bell)
        \\        backslash
        \'        single quote
        \"        double quote
        \NNN        octal constant
        \xNN        hexadecimal constant
        \<nl>        "folded" line (both characters removed)
    A pointer to the modified <string> is returned.


STRING MANIPULATION:

    You may want to include "STRING.H" in your program if you use
    functions in this section, otherwise you'll have to declare the
    return types for any functions you use.

char *blkcpy(dest, source, len)
char *dest;
char *source;
int len;

    Copies the <source> block to the <dest>.  <len> bytes are
    always copied.  No terminator is added to <dest>.  A pointer
    to <dest> is returned.  Overlap checking IS done.

char *lblkcpy(dest, source, len)
char *dest;
char *source;
long len;

    Same as blkcpy() except a long value is used for <len>.

char *blkfill(dest, data, len)
char *dest;
char data;
int len;

    Fill <dest> will <len> bytes of <data>.  A pointer to <dest>
    is returned.

int blkcmp(blk1, blk2, len)
char *blk1;
char *blk2;
int len;

    Lexicographically compare the two blocks.  Return a value
    indicating the relationship between the blocks.  Possible
    return values are:
        negative    blk1 < blk2
        0        blk1 == blk2
        positive    blk1 > blk2
    <len> bytes are always compared.

int blkicmp(blk1, blk2, len)
char *blk1;
char *blk2;
int len;

    Compare blocks as with blkcmp(), but ignore the case of any
    alphabetic characters.

char *memcpy(dst, src, cnt)
char *dst;
char *src;
int cnt;

    Same as blkcpy().

char *memccpy(dst, src, c, cnt)
char *dst;
char *src;
char c;
int cnt;

    Copy bytes from <src> to <dst> until either <cnt> bytes have been
    copied, or the character <c> has been copied.  Returns <dst>.

char *memset(dst, c, cnt)
char *dst;
char c;
int cnt;

    Same as blkfill().

char *memchr(buf, c, cnt)
char *buf;
char c;
int cnt;

    Search the first <cnt> bytes of <buf> for <c>.  Returns a pointer to
    the matching character, or NULL if not found.

int memcmp(buf1, buf2, cnt)
char *buf1;
char *buf2;
int cnt;

    Same as blkcmp().

int memicmp(buf1, buf2, cnt)
char *buf1;
char *buf2;
int cnt;

    Same as blkicmp().

int strlen(string)
char *string;

    Returns the number of characters in a string, not including the
    terminating '\0'.

char *strcpy(dest, source)
char *dest;
char *source;

    Copies the <source> string to the <dest> including the '\0'.  A
    pointer to the start of <dest> is returned.

char *strncpy(dest, source, limit)
char *dest;
char *source;
int limit;

    Copies the <source> string to the <dest>.  At most, <limit>
    characters are copied.  If <source> ends before <limit> characters
    have been copied, the '\0' is copied, otherwise <dest> is not
    terminated by the copy.

char *strdup(string)
char *string;

    Create a copy of <string> and return a pointer to the copy.

char *strset(string, c)
char *string;
char c;

    Fill <string> with <c> up the the terminating '\0' of <string>.

char *strnset(string, c, n)
char *string;
char c;
int n;

    Fill at most <n> characters of <string> with <c>, up the the
    terminating '\0' of <string>.

char *substr(dest, source, start, end)
char *dest;
char *source;
int start;
int end;

    Copy characters from <source> to <dest> starting with character
    <start> and ending with <end>.  A pointer to <dest>, which will
    be '\0' terminated, is returned.

char *subnstr(dest, source, start, length)
char *dest;
char *source;
int start;
int length;

    Copy <length> characters from <source> to <dest> starting with
    character <start>.  A pointer to <dest>, which will be '\0'
    terminated, is returned.

char *strcat(dest, source)
char *dest;
char *source;

    Concatenate <source> on the end of <dest>.  The terminator of
    <dest> will be overwritten by the first character of <source>.
    The termintor from <source> will be copied.  A pointer to
    the modified <dest> is returned.

char *strncat(dest, source, limit)
char *dest;
char *source;
int limit;

    Concatenate <limit> characters from <source> onto <dest>.  If
    <source> contains less than <limit> characters, the length of
    source is used for <limit>.  The terminating '\0' is always
    added.  A pointer to <dest> is returned.

char *strupr(string)
char *string;

    Convert all alphabetic characters in <string> to upper case.

char *strlwr(string)
char *string;

    Convert all alphabetic characters in <string> to lower case.

char *strrev(string)
char *string;

    Reverse the order of the characters in <string> in place.

int strcmp(str1, str2)
char *str1;
char *str2;

    Lexicographically compare the two strings.  Return a value
    indicating the relationship between the strings.  Possible
    return values are:
        negative    str1 < str2
        0        str1 == str2
        positive    str1 > str2

int strncmp(str1, str2, limit)
char *str1;
char *str2;
int limit;

    Compare strings as with strcmp(), but limit comparison to the
    <limit> characters.

int stricmp(str1, str2)
char *str1;
char *str2;

    Compare strings as with strcmp(), but ignore the case of any
    alphabetic characters.

int strnicmp(str1, str2, limit)
char *str1;
char *str2;
int limit;

    Compare strings as with strncmp(), but ignore the case of any
    alphabetic characters.

char *strstr(string, pattern)
char *string;
char *pattern;

    Return a pointer to the first occurance of <pattern> in <string>.
    NULL is returned if <pattern> is not found.

char *stristr(string, pattern)
char *string;
char *pattern;

    Same as strstr(), but ignore the case of any alphabetic characters.

char *strchr(string, symbol)
char *string;
char symbol;

    Return a pointer to the first occurance of <symbol> in <string>.
    NULL is returned if <symbol> is not found.

char *strrchr(string, symbol)
char *string;
char symbol;

    Return a pointer to the last occurance of <symbol> in <string>.
    NULL is returned if <symbol> is not found.

int strpos(string, symbol)
char *string;
char symbol;

    Return the index of the first occurance of <symbol> in <string>.
    -1 is returned if <symbol> is not found.

int strrpos(string, symbol)
char *string;
char symbol;

    Return the index of the last occurance of <symbol> in <string>.
    -1 is returned if <symbol> is not found.

int strspn(string, set)
char *string;
char *set;

    Return the length of the sub-string of <string> that consists
    entirely of characters found in <set>.  The terminating '\0'
    in <set> is not considered part of the match set.  If the first
    character if <string> is not in <set>, 0 is returned.

int strcspn(string, symbol)
char *string;
char *set;

    Return the length of the sub-string of <string> that consists
    entirely of characters not found in <set>.  The terminating '\0'
    in <set> is not considered part of the match set.  If the first
    character if <string> is in <set>, 0 is returned.

char *strpbrk(string, set)
char *string;
char *set;

    Return a pointer to the first occurace in <string> of any
    character in <set>.

char *strrpbrk(string, set)
char *string;
char *set;

    Return a pointer to the last occurace in <string> of any
    character in <set>.

char *strtok(string, delim)
char *string;
char *delim;

    Return a token from <string>.  If <string> is not NULL, it is
    the beginning of a string from which tokens are to be extracted.
    Characters found in <delim> are skipped over to find the start
    of a token, characters are then accumulated until a character in
    <delim> is found, or the terminator of <string> is reached.
    A pointer to the '\0' terminated token is then returned.  Note
    that this function modifies <string> (by inserting '\0's) in
    the process.  Subsequent calls to strtok() may specify NULL as
    the <string> argument, in which case subsequent tokens are
    returned, or NULL if there are no more tokens.

char *strtrim(string, junk)
char *string;
char *junk;

    Remove leading and trailing characters found in <junk>
    from <string>.  Return a pointer to the modified <string>.

char *stradj(string, dir)
char *string;
int dir;

    Adjust <string> by adding space if <dir> is positive, or removing
    space if <dir> is negative.  The magnitude of <dir> is the number
    of character positions to add or remove.  Characters are added or
    removed at the beginning of <string>.  A pointer to the modified
    <string> is returned.

int strrpl(string, ptrn, rpl, n)
char *string;
char *ptrn;
char *rpl;
int n;

    Replace at most <n> occurances of <ptrn> in <string> with <rpl>.
    If <n> is -1, replace all.  Return the number of replacments.

int strirpl(string, ptrn, rpl, n)
char *string;
char *ptrn;
char *rpl;
int n;

    Same as strrpl() except ignore the case of alphabetic characters.


CHARACTER FUNCTIONS:

    To use the functions in this section, you must include "CTYPE.H"
    in your source file.  Please note that the isXXXX() functions,
    except isascii(), only have defined results if isascii() is true.
    (ie. they only work properly on values 0x00 through 0x7F)

int toupper(c)
int c;

    Convert <c> to upper case, if alphabetic.  This is implemeted
    as a macro and also as a function.  You may force use of the
    function version rather than the macro (which evaluates its
    argument twice) by using the "#undef toupper" directive.

int tolower(c)
int c;

    Convert <c> to lower case, if alphabetic.  This is implemeted
    as a macro and also as a function.  You may force use of the
    function version rather than the macro (which evaluates its
    argument twice) by using the "#undef tolower" directive.

int _toupper(c)
int c;

    This macro should be used only if <c> is known to be lower case.
    It converts <c> to upper case.  Results are undefined if converting
    a character which is not lower case.

int _tolower(c)
int c;

    This macro should be used only if <c> is known to be upper case.
    It converts <c> to lower case.  Results are undefined if converting
    a character which is not upper case.

int toascii(c)
int c;

    Convert <c> to 7-bit ascii, putting it into the range 0x00..0x7F.

int isalnum(c)
int c;

    Return non-zero if <c> is '0'..'9','A'..'Z','a'..'z'.

int isalpha(c)
int c;

    Return non-zero if <c> is 'A'..'Z','a'..'z'.

int isascii(c)
int c;

    Return non-zero if <c> is 0x00..0x7F.

int iscntrl(c)
int c;

    Return non-zero if <c> is 0x00..0x1F,0x7F.

int isdigit(c)
int c;

    Return non-zero if <c> is '0'..'9'.

int islower(c)
int c;

    Return non-zero if <c> is 'a'..'z'.

int isprint(c)
int c;

    Return non-zero if <c> is 0x20..0x7E.

int ispunct(c)
int c;

    Return non-zero if <c> is not iscntrl(), isalnum() or isspace().

int isspace(c)
int c;

    Return non-zero if <c> is 0x09..0x0D,0x20.

int isupper(c)
int c;

    Return non-zero if <c> is 'A'..'Z'.

int isxdigit(c)
int c;

    Return non-zero if <c> is '0'..'9','A'..'F','a'..'f'.


DATE/TIME FUNCTIONS:

    To use the functions in this section, you must include "TIME.H"
    in your source file.

long time(rawtime)
long *rawtime;

    Get the current system clock date/time value.  Under many systems,
    this function returns the number of seconds since 00:00:00 GMT on
    Jan 1, 1970.  This implementation returns an encoded date/time
    value instead.  Therefore any programs which depend on this value
    being a number of seconds will not work properly.  However, other
    functions in this section which make use of the raw time value
    returned by time() are implemented to be compatible with this
    encoding, and will work properly.  In addition to returning the
    raw time value, if the <rawtime> pointer is not NULL, the value
    is stored in the long <rawtime> points to.

char *ctime(rawtime)
long *rawtime;

    Convert <rawtime> to a string.  A 26 character fixed field string
    is created from the raw time value.  The following is an example
    of what this string might look like:
        "Wed Jul 08 18:43:07 1987\n\0"
    A 24-hour clock is used, and due to a limitation in the ST system
    clock value, only a resolution of 2 seconds is possible.  A pointer
    to the formatted string, which is held in an internal buffer, is
    returned.

struct tm *gmtime(rawtime)
long *rawtime;

    Convert <rawtime> to fill time structure fields.  A pointer to an
    internal structure is returned.  Refer to "TIME.H" for the values
    of the various structure fields.

struct tm *localtime(rawtime)
long *rawtime;

    Since there is not concept of "time zone" on the ST, this function
    is identical to gmtime().

char *asctime(time)
struct tm *time;

    Convert <time> structure value to a string.  The same format, and
    the same internal buffer, as for ctime() is used for this function.

long cnvtime(rawtime, time)
long *rawtime;
struct tm *time;

    Convert <time> structure value to raw time format.  In addition to
    returning the raw time value, if the <rawtime> pointer in not NULL,
    the value is stored in the long <rawtime> points to. (cf: time)

void stime(rawtime)
long *rawtime;

    Set the system clock to <rawtime>.

int utime(pathname, rawtime)
char *pathname;
long *rawtime;

    Set the modification date of <pathname> to <rawtime>.  Returns zero
    for success, or a negative error code.

long start_timer(t)
TIMER *t;

    Start a 200Hz timer.  This timer value can later be checked with
    time_since() to determine elapsed time.  These functions provide
    a very low-overhead way of timing events.

long time_since(t)
TIMER *t;

    Returns the number of 200Hz ticks since start_timer() was called
    for timer <t>.

void sleep(dt)
int dt;

    Suspend operation for <dt> seconds.  This is implemented as a
    start_timer()/time_since() tight loop waiting for the specified
    amount of time to pass.  In a multi-tasking environment, this
    function should be replaced by a call which will de-activate
    this task for a period of time, allowing other tasks to run.


SEARCHING AND SORTING:

void qsort(base, num, size, cmp)
char *base;
int num;
int size;
int (*cmp)();

    Perform a recursive quick-sort on an array starting at <base>
    containing <num> elements of <size> bytes each.  The function
    pointed to by <cmp> is used to compare elements.  Pointers to
    two items in the array are passed to the function, which must
    return a number representing their relationship as follows:
        negative    item1 < item2
        0        item1 == item2
        positive    item1 > item2
    The qsort() function requires the use of a temporary data area
    that is large enough to hold <size> bytes.  The default space
    provided is 128 bytes large.  If your record size is larger than
    128 bytes, YOU MUST provide an alternative storage area.  The
    global variable "_qbuf" points to the storage qsort() will use.
    Setting "_qbuf" to NULL restores use of the internal buffer.
    This routine is optimized to avoid N*N sort times for ordered data.

void hsort(base, num, size, cmp)
char *base;
int num;
int size;
int (*cmp)();

    Perform an N*log(N) heap-sort on an array starting at <base>
    containing <num> elements of <size> bytes each.  The function
    pointed to by <cmp> is used to compare elements.  Pointers to
    two items in the array are passed to the function, which must
    return a number representing their relationship as follows:
        negative    item1 < item2
        0        item1 == item2
        positive    item1 > item2
    The hsort() function requires no extra storage, is not recursive,
    and has an almost constant N*log(N) sort time.  In the average
    case, it is about half as fast as qsort() on random data.  If
    portability is a concern, it should be noted that qsort() is
    almost always available, but hsort() is not.

char *bsearch(key, base, num, size, cmp)
char *key;
char *base;
int num;
int size;
int (*cmp)();

    Perform a binary search for <key> on the sorted data at <base>.
    <num>, <size> and <cmp> are like the corresponding parameters
    to qsort().  A pointer to the matching element is returned for
    success, or NULL for failure.  The global variable "_bsearch"
    will contain the index of either the matching element, or the
    place where <key> value should be inserted.  The use of "_bsearch"
    is not supported by many implementations of bsearch().

char *lsearch(key, base, num, size, cmp)
char *key;
char *base;
int num;
int size;
int (*cmp)();

    Perform a linear search for <key> on the data at <base>. The
    <num>, <size> and <cmp> parameters are like the corresponding
    parameters to qsort().  A pointer to the first matching element
    is returned for success, or NULL for failure.  If <key> is not
    found, it will be added to the end of the array.

char *lfind(key, base, num, size, cmp)
char *key;
char *base;
int num;
int size;
int (*cmp)();

    Like lsearch(), but do not add elements which are not found.


MISCELLANEOUS FUNCTIONS:

int rand()

    Return a pseudorandom number in the range 0..32767

void srand(seed)
unsigned int seed;

    Seed the random number generator.  This function is #defined as
    a comment, since no seeding is possible for this implementation
    of rand().

MACRO abs(x)

    Return the absolute value of <x>.  This macro evalutes it's
    argument twice.    ((x)<0?(-(x)):(x))

MACRO max(x,y)

    Return the larger of <x> and <y>.  This macro evaluates the
    larger argument twice and the smaller argument once.

MACRO min(x,y)

    Return the smaller of <x> and <y>.  This macro evaluates the
    smaller argument twice and the larger argument once.

MACRO swap(a,b)

    Exchange <a> and <b> by chained XORs.  The macro evaluates
    each argument several times.


----- END OF FILE -----