@(#)xdlibs.txt, SozobonX library docs Mar 29 1995

The Standard Library

              1. Introduction
              2. Header Files
              3. Standard Library Functions
              4. Standard Input/Output Functions
              5. Character Functions
              6. String Functions
              7. Assert, Stack, & Error Handling Functions
              8. Variable Argument List Functions
              9. Global Jump Functions
             10. Date/Time Functions
             11. Unistd Functions (including those from stat.h & fcntl.h)
             12. Miscellaneous Functions + Extensions
             13. TOS Related Functions
             14. Device Input/Output Functions

Standard Library Introduction

     The standard library is based on dLibs 1.2, by Dale Schumacher.
This library contains the bulk of the functions you will use in your
programs.  It is reasonably ANSI compliant, and MiNT functions are
used whenever possible, though not all MiNT functionality is implemented
this time.  Usually no MiNT version checking is done, but the EINVFN
return code, for other Atari OSs - like MagiC - implement some
MiNT functions.
     Many of the functions in this library are written entirely in
assembly language.

     The most common functions are found in libc.a (which is used as the
standard library by the compiler driver), and some functions (extensions)
are to find in libextra.a (which is a library that must be specified on
the linker command line to be used '-lextra' - you will find a "-lextra"
on the pages describing these functions).

     The library libci.a is nearly the same as libc.a, execept there is no
floating point support at all in this library. So if you gonna use floats or
doubles in your sourcecode specify the '-f' switch unless you use the
math library with the '-lm' switch in cc commandline.

The Standard Library Header Files
     The first two header files (listed below) are automatically
included by the 'stdlib.h' and 'stdio.h' header files. They contain basic
type definitions and macro declarations. 'support.h' is included too,
for access to all non-standard bindings.

 Standard             Almost-Standard       Atari-Specific

 1. STDDEF.H          14. MACROS.H          22. ATARI.H
 2. TYPES.H           15. UNISTD.H          23. FILE.H
 3. STDLIB.H          16. FCNTL.H           24. BASEPAGE.H
 4. STDIO.H           17. STAT.H            25. OSHEADER.H
 5. STRING.H          18. MALLOC.H          26. FILESYS.H
 6. CTYPE.H           19. OSBIND.H          27. BIOS.H
 7. ERRNO.H           20. SUPPORT.H
 8. LIMITS.H          21. SIGNAL.H
 9. TIME.H
10. ASSERT.H
11. STDARG.H
12. SETJMP.H
13. MATH.H

STDDEF.H
     Header File:  STDDEF.H

     This is the basic header file, and should be included in all
programs.  It defines FALSE, TRUE, NULL, size_t, ptrdiff_t, and the
offsetof() macro. It is included automaticly by stdlib.h and so by
stdio.h, too.

     TRUE & FALSE are integer constants.  NULL, as you would expect, is
a pointer type with a value of 0, (void *)0L, which can be thought of
as FALSE for pointers.  The size_t type is a type for the size of an
object in bytes.  The ptrdiff_t type is the type that results from a
pointer subtraction.

     The current version number of the XdLibs library is defined in the
macro _XDLIBS.  This fact can be tested by passing (in a source code
module) the following line of code to the compiler:

     assert(_xdlibs == _XDLIBS)

     A macro _XDLIBSVERSION contains this value as a string.

TYPES.H
     Header File:  TYPES.H

     This file contains type definitions for many special and/or
non-standard type names.  Many of the type definitions in this file
'typedef' type names which are ANSI and/or System V standard. This file
is included by several other header files, and includes the STDDEF.H
header file.

     The following types used by the library are defined here:
dev_t, fpos_t, time_t, and clock_t.

     The most common potability definitions are BYTE, UBYTE, CHAR, UCHAR,
WORD, UWORD, LONG, ULONG, BOOL, BOOOLEAN, uchar, ushort, uint, and ulong.
     They won't be defined if you have a line
#define _Portab
     in your souce code before including the header files.

dev_t
     Type:  dev_t

     typedef unsigned short dev_t;

     This type is commonly used for drive (device) identifications.

fpos_t
     Type:  fpos_t

     typedef unsigned long fpos_t;

     This type is commonly used to hold file position offsets.

time_t
     Type:  time_t

     typedef unsigned long time_t;

     This type is reserved for raw time/date values, where the highword
contains the date and the lowword the time, encoded as documented
by Atari.

clock_t
     Type:  clock_t

     typedef long clock_t;

     This type is reserved for clock ticks.

STDLIB.H
     Header File:  STDLIB.H

     This header file defines the dynamic memory managment functions,
string to number functions, environment access functions, and basic
process control functions.  Some extensions' prototypes are to find
there, too.  This header file  should be present in every source code
module you write.  It uses by include the 'types.h' and 'stddef.h'
header files. It is included by 'stdio.h', so you do not need to
explicitly specify it and both above when including 'stdio.h'.

     There are two important structures defined in this file:

     Structure:  div_t            Structure: ldiv_t

div_t
     This is the structure returned by the div() function:

     typedef struct {
          int         quot;   /* Quotient     */
          int         rem;    /* Remainder    */
     } div_t;

ldiv_t
     This is the structure returned by the ldiv() function:

     typedef struct {
          long         quot;   /* Quotient     */
          long         rem;    /* Remainder    */
     } ldiv_t;

STDIO.H
     Header File:  STDIO.H

     This header file should be present in nearly all C programs.  It
contains definitions for the FILE structure, various related macros, and
contains extern declarations for standard input/output and other
commonly used functions.  For convenience, the constants TRUE, FALSE
and ERROR are also defined in this header file, although this is
somewhat non-standard.

FILE
typedef struct
{
     int            _cnt;     /* # Of Bytes In Buffer                */
     unsigned char  *_ptr;    /* Current Buffer Pointer              */
     unsigned char  *_base;   /* Base Of File Buffer                 */
     unsigned int   _flag;    /* File Status Flags                   */
     int            _file;    /* File Handle                         */
     int            _bsiz;    /* Buffer Size                         */
     unsigned char  _ch;      /* Tiny Buffer (for "unbuffered" i/o)  */
} FILE;

STRING.H
     Header File:  STRING.H

     This header file defines aliases for string function names (since
some string functions have various names on different systems) and
contains external declarations for all string functions.  The number
to string functions are also found in this header file.

CTYPE.H
     Header File:  CTYPE.H

     The isxxxx() macros and toxxxx() macros are defined in this
header file.

ERRNO.H
     Header File:  ERRNO.H

     This header file defines the error code constants, the errno
variable, and related error handling functions.

LIMITS.H
     Header File:  LIMITS.H

     Various maximum and minimum values are defined in this header
file, including PATHSIZE and MAXINT.

TIME.H
     Header File:  TIME.H

     This header file defines time related constants and structures,
and contains external declarations for the time functions.  The time_t
type (TYPES.H) contains an encoded date/time value, while
struct tm holds a decoded date/time value.

     SEE:  TYPES.H

tm
typedef struct tm {
        int     tm_sec;         /* Seconds (0..61)             */
        int     tm_min;         /* Minutes (0..59)             */
        int     tm_hour;        /* Hours (0..23)               */
        int     tm_mday;        /* Day Of Month (1..31)        */
        int     tm_mon;         /* Month (0..11)               */
        int     tm_year;        /* Year - 1900                 */
        int     tm_wday;        /* Day Of Week (0=Sun..6=Sat)  */
        int     tm_yday;        /* Day Of Year (0..365)        */
        int     tm_isdst;       /* Daylight Savings Time?      */
                                /* (TRUE/FALSE/-1=Unknown)     */
};

ASSERT.H
     Header File:  ASSERT.H

     This header file defines the assert() run-time condition checking.
macro.


STDARG.H
     Header File:  STDARG.H

     This header file defines the types and macros needed for variable
argument list processing.

SETJMP.H
     Header File:  SETJMP.H

     This header file defines the buffer needed to save your context
when using the setjmp()/longjmp() or catch()/throw() functions.

MACROS.H
     Header File:  MACROS.H

     This header file contains a few useful macros, including min(),
max(), swap() and others.


UNISTD.H
     Header File:  UNISTD.H

     The standard operating system calls in C are the POSIX system
calls.  This header file contains function declarations and macros
definitions for translating the standardized functions to Atari TOS
functions.

FCNTL.H
     Header File:  FCNTL.H

     This header file defines the O_xxxx constants used by the open()
function.

STAT.H
     Header File:  STAT.H

     The structure stat and the file mode flag constants are defined
in this header file.  The constants are for use with creat(), open(),
stat(), and the macros used for examination of the st_mode value
of the filled stat buffer.

     The stat strcuture consists of several variables which contain
information about a file.  If a variable can not be set (because
_mint is not present) it is initialized to 0 (in the case of st_index,
st_uid, st_gid) or to -1 (in the case of st_size, st_nblocks for
directories).

     The macros defined in this header file can be used for easy access
to the file mode flags of the st_mode component of the stat structure.

stat
struct stat {
    ushort   st_mode;        /*  File Mode Flags                    */
    long     st_index;       /*  index Number In File System        */
    dev_t    st_dev;         /*  Device ID (0 == A, 1 == B [...])   */
    ushort   st_nlink;       /*  Number Of Links                    */
    ushort   st_uid;         /*  Owner's User ID                    */
    ushort   st_gid;         /*  Owner's Group ID                   */
    long     st_size;        /*  File Size (bytes)                  */
    time_t   st_mtime;       /*  Last Modification Date/Time        */
    time_t   st_atime;       /*  Last Access Date/Time              */
    time_t   st_ctime;       /*  Creation Time Of FIle              */
    short    st_attr;        /*  GEMDOS File Attributes             */
}
     The timestamps are in the XdLibs rawtime format:

     st_atime   Time when file     data was last read or modified.
                Changed by the     following system calls:  mknod(2),
                utimes(2), read(2), and write(2). For reasons of
                efficiency, st_atime is not set when a directory
                is searched, although this would be more logi-
                cal.

     st_mtime   Time when data     was last modified. It is not set
                by changes of owner, group, link count, or mode.
                Changed by the     following system calls:  mknod(2),
                utimes(2), write(2).

     st_ctime   Time when file     status was last     changed. It is
                set both both by writing and changing the i-
                node. Changed by the following    system calls:
                chmod(2) chown(2), link(2), mknod(2), rename(2),
                unlink(2), write(2).

     The status     information word st_mode has bits:

     #define S_IFMT     0170000    /* type   of file   */
     #define   S_IFCHR       0020000    /* character special */
     #define   S_IFDIR       0040000    /* directory file */
     #define   S_IFREG       0100000    /* regular */
     #define   S_IFIFO       0120000    /* FIFO */
     #define   S_IFMEM     0140000 /* process or memory region */
     #define   S_IFLNK       0160000    /* symbolic link */

     #define S_ISUID         0004000    /* set user id on execution */
     #define S_ISGID         0002000    /* set group id     on execution */
     #define S_ISVTX         0001000    /* sticky bit */
     #define S_IREAD         0000400    /* read   permission, owner */
     #define S_IWRITE        0000200    /* write permission, owner */
     #define S_IEXEC         0000100    /* execute/search permission, owner */
     The mode bits 0000070 and 0000007 encode group and     others
     permissions (see chmod(2)).

MALLOC.H
    Header File:  MALLOC.H

     This header file contains function declarations and constant
declarations for dynamic memory allocation from the stack and various
utility functions to deal with the memory once allocated.

OSBIND.H
     Header File:  OSBIND.H

     bios(), xbios() and gemdos() calls are defined in this header
file. This file includes 'tosbind.h' and 'mintbind.h' header files
with the mnemonics for OS calls.

     For a complete list of the functions available through the use of
these mnemonics, please consult the following reference texts:

     A Hitchhiker's Guide To The BIOS (Atari Corp.)
     Atari GEMDOS Reference Manual (Atari Corp.)
     The Atari Compendium, 1st Revision (SDS Publishing)
      MiNT Docs & Manual Pages

SUPPORT.H
     Header File:  SUPPORT.H

     All non standard function prototypes and variables of the XdLibs.
This file is included by STDLIB.H automatically. So it should be present
in any source code to be linked with XdLibs library.

ATARI.H
     Header File:  ATARI.H

     Usually you won't need this file, except you need some OS
strcutures or defines. So for direct TOS access, include this header
file.  It will include the OSBIND.H, BASEPAGE.H, and OSHEADER.H
header files.  And the MiNT header file 'FILE.H.
     Some operating system structures are declared in this header file,
such as DTA, DISKINFO, DOSTIME and KEYTAB.

DTA
typedef struct Dta {
     char           d_reserved[21];  /*  Reserved       */
     char           d_attrib;        /*  Attributes     */
     unsigned short d_time;          /*  Creation Time  */
     unsigned short d_date;          /*  Creation Date  */
     long           d_length;        /*  Size           */
     char           d_fname[14];     /*  Name           */
} DTA;

DISKINFO
typedef struct Diskinfo {
     long b_free;       /*  Free Clusters      */
     long b_total;      /*  Total Clusters     */
     long b_secsiz;     /*  Bytes / Sector     */
     long b_clsiz;      /*  Sectors / Cluster  */
} DISKINFO;

DOSTIME
typedef struct Dostime {
  unsigned short time;  /*  Encoded Time  */
  unsigned short date;  /*  Encoded Date  */
} DOSTIME;

KEYTAB
typedef struct Keytab {
     char *unshift;   /*  Unshifted Key Table  */
     char *shift;     /*  Shifted Key Table    */
     char *capslock;  /*  CAPSLOCK Key Table   */
} KEYTAB;

FILE.H
     Header File:  FILE.H

     This header file contains the most used structures and defines
known under MiNT. The defines for Fcntl() and Dcntl() calls, the
XATTR structure, etc..
     see 'FILESYS.H'

FILESYS.H
     Header File:  FILESYS.H

     This file contains the more sophisticated MiNT structures, you
only will need for dealing with device drivers, filesystems etc.

BASEPAGE.H
     Header File:  BASEPAGE.H

     The BASEPAGE structure and the _base variable, which is initialized
to point to the current process basepage, are defined in this header
file.

BASEPAGE
typedef struct basep
{
     char           *p_lowtpa;     /* Pointer To Self (Bottom Of TPA) */
     char           *p_hitpa;      /* Pointer To Top Of TPA + 1       */
     char           *p_tbase;      /* Base Of Text Segment            */
     long           p_tlen;        /* Length Of Text Segment          */
     char           *p_dbase;      /* Base Of Data Segment            */
     long           p_dlen;        /* Length Of Data Segment          */
     char           *p_bbase;      /* Base Of BSS Segment             */
     long           p_blen;        /* Length Of BSS Segment           */
     char           *p_dta;        /* Pointer To Current DTA          */
     struct basep   *p_parent;     /* Pointer To Parent's Basepage    */
     char           *p_resrvd0;    /* Reserved For Future Use         */
     char           *p_env;        /* Pointer To Environment String   */
     char           p_resrvd1[80]; /* Scratch Area... Do not touch!   */
     char           p_cmdlin[128]; /* Command Line Image              */
} BASEPAGE;
Cause accessories are not true processes in non multitasking environments
you shouldn't access the BASEPAGE there.

OSHEADER.H
     Header File:  OSHEADER.H

     The TOS header structure (_osheader) is defined in this header
file.

_osheader
typedef struct _osheader {
     unsigned int        os_entry;
     unsigned int        os_version;
     void                *reseth;
     struct _osheader    *os_beg;
     void                *os_end;
     long                os_rsv1;
     void                *os_magic;     /* (GEM_MUPB *)          */
     long                os_date;
     unsigned int        os_conf;
     unsigned int        os_dosdate;

     /* if (os_version >= 0x102) */

     char                **p_root;
     unsigned char       **pkbshift;
     BASEPAGE            **p_run;       /* (* -> act_pd)         */
     char                *p_rsv2;
} OSHEADER;

BIOS.H
     Header File:  BIOS.H

     This file contains the more sophisticated BIOS and XBIOS structures,
you will rarely need it. (BPB, IOREC, KBDVECS)


BPB
typedef struct Bpb {
     unsigned short recsiz;   /*  Bytes / Sector                    */
     unsigned short clsiz;    /*  Sectors / Cluster                 */
     unsigned short clsizb;   /*  Byes / Cluster                    */
     unsigned short rdlen;    /*  Sector Length Of Root Directory   */
     unsigned short fsiz;     /*  Sectors / FAT                     */
     unsigned short fatrec;   /*  Starting Sector Of Second FAT     */
     unsigned short datrec;   /*  Starting Sector Of Data           */
     unsigned short numcl;    /*  Clusters / Disk                   */
     unsigned short bflags;   /*  BIT 0==1? 16-Bit FAT : 12-Bit FAT */
} BPB;

IOREC
typedef struct Iorec {
     long      ibuf;     /*  Start Of Buffer            */
     short     ibufsiz;  /*  Size Of Buffer             */
     short     ibufhd;   /*  Head Index Mark Of Buffer  */
     short     ibuftl;   /*  Tail Index Mark Of Buffer  */
     short     ibuflow;  /*  Low Water Mark Of Buffer   */
     short     ibufhi;   /*  High Water Mark Of Buffer  */
} IOREC;

KBDVECS
typedef struct Kbdvecs {
     void (*midivec)();   /*  MIDI Input                             */
     void (*vkbderr)();   /*  IKBD Error                             */
     void (*vmiderr)();   /*  MIDI Error                             */
     void (*statvec)();   /*  IKBD Status                            */
     void (*mousevec)();  /*  IKBD Mouse                             */
     void (*clockvec)();  /*  IKBD Clock                             */
     void (*joyvec)();    /*  IKBD Joystick                          */
     void (*midisys)();   /*  Main MIDI Vector                       */
     void (*ikbdsys)();   /*  Main IKBD Vector                       */
     short drvstat;       /*  Remaining Bytes To Read In Multi-Byte  */
                          /*  Status Packet                          */
} KBDVECS;

Standard Library Functions
     This section of the manual documents some basic functions of the
standard library.  To make use of these functions, you must include the
STDLIB.H header file.


                        3.1 Process Control
                        3.2 Memory Management
                        3.3 String To Number
                        3.4 Miscellaneous
                        3.5 Internal Functions

                        Variable:  short _xdlibs;
                        Variable:  char __Ident_lib[];
                        Variable:  char __Ident_libx[];
                        Variable:  char _xdlibs_date[];

__Ident_lib
 char __Ident_lib[]

 An 'ident' string for the XdLibs library 
 'libc.a'. Automatically linked.

__Ident_libx
 char __Ident_libx[]

 An 'ident' string for the XdLibs library 
 'libextra.a'. Automatically linked.

_xdlibs_date
     char _xdlibs_date[]
     A string containing the version date of XdLibs.

_xdlibs
     short _xdlibs;

     This is the version number of the standard function library.
The high byte is the version number, and the low byte is the revision
number.

     There is a macro (_XDLIBS) in the STDDEF.H header file which
should have the same value.

Process Control
     These are the functions for process control to find in every C
library and some usefull variables. Non portable variables (Atari
specific ones) you will find in page Internal Functions.

          Function:  main()
          Function:  exit()
          Function:  abort()              Variable:  int errno;
          Function:  atexit()             Variable:  char *etext;
          Function:  getenv()             Variable:  char *edata;
          Function:  putenv()             Variable:  char *end;
          Function:  system()

errno
     int errno;

     This variable holds the error number of last error that occured in
a library function.  It is set to zero at program start, and is not set
to zero again by any library function.  It may, however, be set to a
non-zero error number by many library functions (particularly the
standard input/output and system service functions).  The meaning of
this error number may be found in the symbolic #defines in ERRNO.H, or
by calling the seterror() functions.

etext
     char *etext;

     This variable points to the first byte beyond the end of the text
segment.  It is provided for compatability.

edata
     char *edata;

     This variable points to the first byte beyond the end of the data
segment.  It is provided for compatability.

end
     char *end;

     This variable points to the first byte beyond the end of the BSS
segment.  It is provided for compatability.

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

     This function is not actually in the standard libraries, but must
be present somewhere in your source 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 initial
environment string.  The return value from main() is passed, by _main(),
to exit().  Therefore, you should always return() from main(). You may
also call exit() directly in any function.

     A return value of 0 indicates no error.  A positive value (<=127)
indicates an error or is any significant value in a special context.
Negative return values are reserved for operating system errors and
signals.

     WARNING:      Do not use the argument <envp> in accessories!!
                   With the distributed startup codes the <argv> and
                   <argc> arguments work with accessories (<argc> is 0,
                   and <argv[0]> points to a NULL pointer).

     SEE:  ERRNO.H

exit()
     void exit(int status)

     This function is called for normal program termination.  It calls
all atexit() functions (FILO), and flushes and closes all open data
streams.  It returns <status> value to the operating system.

     A return value of 0 indicates no error.  A positive value (<=127)
indicates an error.  Negative return values are reserved for operating
system errors and signals.

     SEE:  abort()
           atexit()

FILO
  FILO = [F]irst [I]n [L]ast [O]ut  

abort()
     void abort(void);                                         -lextra

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

     SEE:  exit()
           atexit()

atexit()
     int atexit(void (*fnc)())

     This function stores fnc() so that fnc() is called by exit() or if
main() returns.  If atexit() returns any other value than 0, then fnc()
could not be stored (there is space for 32 function pointers reserved).

     SEE:  exit()
           abort()

getenv()
     char *getenv(char *var)

     Search for <var> in the environment.  If <var> is found, a pointer
to its value is returned.  NULL is returned if <var> is not found.

     WARNING:  The returned pointer points into the environment and
               must not be modified!  The returned string may be
               empty or NULL!

     Do not use this function in accessories! Replace it in your source
code with the example in 'hints.txt' if you want to use environment
strings in accessories or if it is linked for any library function !!

     SEE:  putenv()

putenv()
     int putenv(char *entry)

     Add <entry> to the environment, where <entry> can be any of the
following forms:

     <VARIABLE>
     <VARIABLE>=
     <VARIABLE>=<value>

     The first form removes <VARIABLE> from the environment.  The
getenv() function will return NULL if looking for this variable.
The second form adds <VARIABLE> to the environment, with a null
value.  The getenv() function will return a pointer to a '\0'
character if looking for this variable.  Many environment handlers
do not support such "tag variables", so their use is not recommended.
The final form is the most common; <VARIABLE> is installed (or
replaced) with <value>.

     It should be noted that the putenv() function itself is not
supported on many systems and therefore may not be portable.

     This function uses malloc() if there is not enough space in the
last allocated environment block.

     The putenv() function returns TRUE for success or FALSE for
failure.  Failure may be due to insufficient memory (ENSMEM) or the
fact that the variable to be removed does not exist.

     Do not use this function in accessories!

     SEE:  getenv()

system()
     int system(char *command)

     If <command> is NULL, this function returns TRUE if a shell is
available and FALSE if not.

     If <command> has a value, this function attempts to pass <command>
to the shell.  The return value will be that from the shell.

     If MiNT is not present, and "_shell_p" is valid, the program
pointed to by the system variable "_shell_p" is used.  If a valid shell
cannot be found in the _shell_p variable, the "SHELL" environment
variable is searched for, too.  If it exists, and is not empty, it will
be the name of the shell program to execute the given command.

     If a new process with a new shell is created, there is an argument
added: the shell flags, cause most shells won't execute a commandline
if they are not called with option '-c'. To control this, there exists
a variable 'char *__SHELL_FLAGS__', which gets used if it is not NULL.
By default the string "-c" is passed as first argument. The <command>
string will be the second argument.

     If system() returns with ERROR, and errno is still zero, the shell
could not be executed.  In this case you can try to execute the shell
directly, using the spawn...() family of functions.  If some people
need a function like system(), but working without a shell, I can
implement it.  The only question is the functionality: I/O redirection,
wildcard expansion pipes, variable substitution, or even more?  I think
the better solution is using a full featured shell via system().

     Of course, this function uses the ARGV argument passing scheme,
which is ATARI's standard convention for calling programs.

Memory Allocation
     These are the standard functions for memory allocation. 'lalloc' and
'lrealloc' are not guaranteed to be portable.

                     Function:  malloc()
                     Function:  calloc()
                     Function:  lalloc()
                     Function:  realloc()
                     Function:  lrealloc()
                     Function:  free()

                     Variable:  long _BLKSIZ = 65536;

_BLKSIZ
     long _BLKSIZ = 65536;

     This variable controls the granularity of system memory allocation
used by malloc(), and others.  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 32 heaps can
be active at a time.  Therefore, (32 * _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.  (This will soon change.) Please note that _BLKSIZ should not
be too small.  To avoid wasting memory, 8K is the minimum size if
memory protection (68030, PMMU) is enabled under MiNT.

malloc()
     void *malloc(size_t 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.

calloc()
     void  *calloc(unsigned int n, size_t 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 if there is not enough free memory available.

lalloc()
     void *lalloc(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.

realloc()
     void *realloc(char *addr, size_t 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 completely moved) new
block will be returned.  If <addr> is NULL, realloc() will simply act
like malloc().  If <size> is 0, and <addr> is not NULL, realloc() will
work like free().

     SEE:  lrealloc()

lrealloc()
     void *lrealloc(char *addr, long 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
lrealloc() succeeds, a pointer to the (possibly completely moved) new
block will be returned.  If <addr> is NULL, lrealloc() will simply act
like malloc().  If <size> is 0, and <addr> is not NULL, lrealloc() will
work like free().

     SEE:  realloc()

free()
     void free(void *addr)

     Release the memory block at <addr> back into the free memory pool.

     WARNING: Unlike some implementations, you may not realloc() a block
              which has been free()ed.

     SEE:  malloc()

String to number
     Some string to number conversion functions. They can be found
     in any standard "C" library.

                           Function:  atof()
                           Function:  atoi()
                           Function:  atol()
                           Function:  strtod()
                           Function:  strtol()
                           Function:  strtoul()

atof()
     double atof(char *string)

     Convert a <string> to a double value.
     See strtod() for description.

     not present in the library file 'libci.a'.


atoi()
     int atoi(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.  The return value is undefined in an overflow
situation.

     SEE:  atol()

atol()
     long atol(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.  The return value is undefined in an overflow
situation.

     SEE:  atoi()

strtod()
    double strtod(char *s, char **endp)

     Convert the number in string <s> to a double value. If endp
     is not NULL, you will find there after return a pointer
     into <s> where the conversion stopped.

     It recognices values of the form:
          [spaces] [sign] digits [ [.] [ [digits] [ [e|E|d|D] \
               [space|sign] [int][F|L]]]]

     It returns
          on overflow: HUGE_VAL and errno = ERANGE
          on underflow: -HUGE_VAL and errno = ERANGE

    This function is not present in the library file 'libci.a'.

strtol()
     long strtol(char *number, char **nptr, int base)

     Convert the string <number> to a long value of base <base>.  Bases
from 0 to 36 are allowed.  Leading whitespace is ignored, and a leading
+/- is optional.  If the <base> is 0, a leading '0' indicates base 8
and a leading "0x" or "0X" indicates base 16.  Characters are processed
until a character is found which is not in the specified base.  If
<nptr> is non-NULL, it will be set to point to the character which
terminated the translation in <number>.  The return value is undefined
in an overflow situation.

     SEE:  strtoul()

strtoul()
     unsigned long strtoul(char *number, char **nptr, int base)

     Convert the string <number> to an unsigned long value of base
<base>.  Bases from 0 to 36 are allowed.  Leading whitespace is
ignored, and a leading +/- is optional.  If the <base> is 0, a leading
'0' indicates base 8 and a leading "0x" or "0X" indicates base 16.
Characters are processed until a character is found which is not in the
specified base.  If <nptr> is non-NULL, it will be set to point to the
character which terminated the translation in <number>.  The return
value is undefined in an overflow situation.

     SEE:  strtol()

Miscellaneous Functions
     Some more functions from the standard C library. 'getopt' isn't
part of ANSI C standard.

                      Function:  rand()
                      Function:  srand()
                      Function:  bsearch()
                      Function:  qsort()
                      Function:  getopt()
                      Function:  abs()
                      Function:  labs()
                         Macro:  _abs()
                         Macro:  _labs()
                      Function:  div()
                      Function:  ldiv()
                      arithmetic floating point functions

rand()
     int rand(void)

     Return a pseudo-random number in the range 0..32767.  This
function uses the system random number generator, but takes its value
out of the middle to avoid the exactly 50% behavior of the lowest order
bit.  Source code is also provided, though commented out, showing how
to generate your own random number sequence if the system random
numbers are not sufficient or for porting these routines to another
machine.

srand()
     void srand(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().

bsearch()
                                                                -lextra
     void *bsearch(char *key, char *base, int num, int size,
           int (*cmp)(void *keyval, void *datum))

     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 'int _bsearch' will contain the
index of either the matching element, or the index of the element that
the <key> value should be inserted after.  The use of "_bsearch" is not
supported by most implementations of bsearch(). See qsort() for compare
function description.

qsort()
                                                             -lextra
     void qsort(char *base, int num, int size,
           int (*cmp)(void *keyval, void *datum))

     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 function strcmp() e.g. satisfies this.

     This routine is optimized to avoid N*N sort times for ordered
data. In fact, performance on sorted or reverse-sorted data is actually
"best case" with this algorithm, rather than "worst case" as with most
qsort() implementations.

getopt()
     int getopt(int argc, char **argv, char *optstring)            -lextra

     This function eases the processing of the command line.  Each call
returns a character from <optstring>, with optarg set to a parameter if
one is required; or a '?' indicating that an invalid option was found;
or EOF indicating that all options have been processed.  The <argc> and
<argv> parameters are (of course) the argc and argv values passed to
main().  The <opstring> is a string of option characters.  If an option
takes a parameter, it is followed by a ':' in <optstring>, and the char
*optarg variable (global) will be set to point to the parameter string
from the command line. For example, "bno:v" defines the valid option
characters as 'b', 'n', 'o' and 'v', and 'o' takes a parameter.  All
options must be preceeded (in the command line) by a '-' character.  A
single '-' character is taken to indicate stdin as a file, and
terminates the argument processing.  A "--" string indicates the end of
options, and is skipped over.  When option processing is successfully
completed, the global variable optind will contain the index into
argv[] of the next argument to be processed.  Subsequent arguments
should be processed with a loop like this:

     while(optind < argc)
          process(argv[optind++]);

     If an error occurs during argument process, an error message is
written to stderr and '?' is returned by getopt().  Your program should
then give a usage message and abort.  If the global variable opterr is
set to zero, no error message will be given, but '?' will still be
returned.  Note that command lines accepted by getopt() are quite
flexible.  The command lines "-b -v -o filename -- - file",
"-vbofilename - file", and "-ofilename -bv - file" all will return the
'b', 'v', and 'o' options with the parameter to 'o' set to "filename"
and leave the arguments "-" and "file2" for further processing.  Please
examine the sample program "echo.c" for an example of getopt() usage.

abs()
     int  abs( int x)

     Return the absolute value of <x>.

     MACRO _abs(x)

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

     SEE:  labs()

labs()
     long  labs( long x )

     Return the absolute value of <x>.

     MACRO _labs(x)

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

     SEE:  abs()

div()
     div_t div(int num, int denom)

     Computes quotient and remainder from num/denom. The values are put
     in the returned structure div_t.

ldiv()
     ldiv_t ldiv(long num, long denom)

     Computes quotient and remainder from num/denom. The values are put
     in the returned structure ldiv_t.

floating point functions
     Most floating point arithm. functions are internals, but some are
for global access. (in some environments these functions are to find in
math library)
               frexp()
               ldexp()
               modf()
    These functions are not present in the library file 'libci.a'.


frexp()
     double frexp(double value, int *eptr)

     Returns significand (|significand| < 1) by removing exponent
from floating point value.
In *eptr it returns an exponent <n>, so that value = significand * 2**n.


ldexp()
     double ldexp(double value, unsigned int exp)

     Returns value * 2**exp


modf()
     double modf( double value, double *ip)

     Returns fractional part of value, and in <ip> the integral part
of value, so that (*ip + fractional) == value


Some Internals
     These variables maybe of some interest for you in your programs.
You are only allowed to read them! But you may assign a value to the
global constant _STKSIZ in your source code.

                 Variable:  short _app;
                 Variables: short _mint;    short _magx;
                 Variable:  short _tos;
                 Variable:  BASEPAGE *_base;
                 Variable:  char *_envp;
                 Variable:  long _STKSIZ = 4096L;

     The following functions are internal, and should not be called by
you in your programs.  They are called and linked automatically by the
SozobonX XdLibs library's startupcodes.

                 Function:  _initargs()
                 Function:  _crtinit()
                 Function:  _main()
                 Function:  _exit()

_app
    short _app;

     A flag to show how the program was started by the OS:
        as application if (_app == TRUE)
        or an accessory  if (_app == FALSE)

    This flag is set by the startupcode and is used for setup the stack.
You will need it in GEM programs to handle accesories correctly.

_mint
     short _mint;     short _magx;     short _tos;

     If <_mint> has a value of 0,  MiNT is not running.  If it is set
to -1, you will have to test for the presence of MiNT yourself.  Any
other value is the version number of MiNT.

     Nearly the same goes for <_magx> and MagiC OS.

     <_tos> will contain the TOS version number, it maybe set to 0,
e.g. if MagiC is running.

     Using a startup module will always include a MiNT, etc. test,
performed in the _crtinit() function.  With other startup modules, you can
test for the presence of MiNT with the GetMiNT() function.

     Example #1:

          if (__mint == -1)
               GetMiNT();

     Example #2:

          if (__mint == -1) {
               long val;
               if (Getcookie('MiNT', &val))
                    __mint = (int)val;
               else
                    __mint = 0;
          }

          if (__mint) {

               /*  Do something special.  */

          }

     The GetMiNT() function is a dummy function with the standard
startup modules, and must never be called.

_base
     BASEPAGE *_base;

     This is a pointer to the basepage of the process.

_envp
     char *_envp;

     This is a pointer to the start of the environment.  It can be
changed by the putenv() function. In accessories this value is not
supported by the OS usually. See 'hints.txt'.

_STKSIZ
     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.  If you need a larger stack, set this variable in
your source code; if not, forget about it. Accessories always will
have a stacksize of 4K unless you use a special startupcode,
see 'accx_s.o' for that.

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

     Process the command arguments, either parsing the command line or
retrieving the ARGV environment strings.  This function understands the
new ARGV argument passing scheme of ATARI, as well as empty arguments
and quoted arguments.
     With the switch 'short __STRICTLY_ARGV__' set (default it is 0)
it will only recognize ARGV arguments if _base->p_cmdlin[0] == 127, as
required by ARGV documentation.

     Never call this function!  It manipulates the heap/stack area.
This function is called from the startup module very early on.  Values
to be passed to the main() function are stored in the global variables
"_argc" and "_argv". The startup module initializes these variables to
indicate that no arguments are available, and sets "_envp" from the
value in the basepage.  If a program does not use arguments, use e.g.
the 'min_s.o' startup module to make the program smaller.

_crtinit()
     void _crtinit(void)
     void _acc_crtinit(void)

     The startup module calls this function.  It sets up some values, like
the _mint flag and the _starttime variable (for the clock() function). It
switches to MiNT domain if MiNT is running, for the library won't work
always correctly in TOS domain then.

     Clearing environment is done here, too (if not an Accessory).
Therefore exists a switch
     short __ASSUME_CONSISTENT_ENV__; (default it is TRUE)

     You can set it to FALSE if you expect an environment mixing up
correct
     "VAR=value\0"
strings with buggy ones.
     "VAR=\0value\0"
Default we assume: if we find no buggy ones at begin all will be correct.

_main()
     int _main(void)

     This function defines the standard streams, checks to see which of them
are devices, and calls the main() function.  The startup module calls this
function to start the C program.  The following standard streams are
initialized by _main():

     stdin      Standard Input (redirectable)
     stdout     Standard Output (redirectable)
     stderr     Standard error file  (redirectable)
                Usually the system console device, but since STDERR, ARGV
                and isatty(2) is checked, it may be redirected already.

     Atari Specific:

     stdprn     Standard Printer   (output only)  (handle 3)
     stdaux     Communication Port (input/output) (device file aux:)

     The variable __FWRT_BIN__ is initialized TRUE if the UNIXMODE
feature 'b' is set in the env variable $UNIXMODE. This has no effect on
device files!

     The global variables "_argc", "_argv" and "_envp" are used to
store the values to be passed to the main() function.  If main()
returns, exit() is called, with the return value as status.  If a
program does not use ANY standard input/output, you can use a startup
module which does not call the _main() function, but you will not get
arguments if you do so. If you want to get argument passing in such a
situation, use the _main() function from the MINIMUM.H header file.  If
you do not need 'argv[0]' and expect short arguments, you can use the
getcmdln() function from the MINIMUM.H header file.

_exit()
     void _exit(int status)

     Exits the program immediately, returning <status> to the operating
system.

     SEE:  exit()
           atexit()
           abort()


Standard Input/Output Functions
     These are the input/output functions of the standard library.  To
use the functions in this library, include the STDIO.H header file.  We
try to keep these functions as standard as possible.

                    4.1 File To Stream Operations
                    4.2 Process Communication
                    4.3 Formatted Input/Output
                    4.4 Formatting Input/Output
                    4.5 Stream Input/Output
                    4.6 Positioning In Streams
                    4.7 Standard Input/Output Error Handling
                    4.8 Extensions

                    Variable:  short __FWRT_BIN__
                    Variable:  short __FWRT_DEV_BIN__
                    Variable:  short __FRW_BIN__

__FWRT_BIN__
     short __FWRT_BIN__ = 0;
     short __FWRT_DEV_BIN__ = 0;

     Switches to handle <NL> -> <CR><NL> for output in textmode streams.
If TRUE no CR is added to a <newline> in an output stream. This has no
effect on input from a stream, so <CR><NL> is processed to a single <NL>,
and <NL>s without a <CR> in file don't make any problems at all.

     __FWRT_BIN__ only works on non-device streams, while
     __FWRT_DEV_BIN__ has no effect on non-device streams.

     If the UNIXMODE tag 'b' is set in the $UNIXMODE environment variable
__FWRT_BIN__ is set TRUE by the startup _main() function.

     See __FRW_BIN__, _unixmode

__FRW_BIN__
     short __FRW_BIN__ = 0;

     A switch to handle <NL> -> <CR<NL> processing more restrictive.
It works on any streams, for input and output: No <CR> processing is done at
all. This may cause problems if reading files with <CR><NL> as newline
marks.

     See also __FWRT_BIN__

File To Stream Operations
      These functions deal with files, filenames and streams.

                           Function:  fopen()
                           Function:  freopen()
                           Function:  fflush()
                           Function:  fclose()
                           Function:  remove()
                           Function:  rename()
                           Function:  tmpfile()
                           Function:  tmpnam()
                           Function:  setbuf()
                           Function:  setvbuf()

fopen()
     FILE *fopen(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
by default and may cause <CR> processing:
     that indicates <nl> is translated to <cr><lf> on output and
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 does not exists, or zero an existing
file.  If "r" is the only mode specified, the file must already exist.

     The "+" option maybe added to "r" or "w" to indicate the update mode,
that means you can read and write to that file.

     A (FILE *) is returned if the open succeeds, or NULL if it fails.

     SEE:  fdopen(), freopen(), __FWRT_BIN__, __FRW_BIN__
           fopenp(), fclose()

freopen()
     FILE *freopen(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.
     <fp> is returned for success, or NULL for failure.

     SEE:  fopen()
           fclose()

fflush()
     int fflush(FILE *fp)

     Flush the file I/O buffer of the stream <fp>.  The buffer is
automatically flushed when it is full, the stream is closed, the program
terminates through exit(), or you switch between reading and writing on
a stream which is opened for both.

     If you want to mix low level file operations and stream operations
or ensure that the output is written into a file, you will have to call
fflush().

     If <fp> is NULL, all open streams are flushed.

     fflush() returning something != 0 indicates an error, but the
buffer(s) is (are) cleared in any case.

fclose()
     int fclose(FILE *fp)

     Close the stream <fp>, flushing the buffer.  This function returns
0 if successful.

     SEE:  fopen()

remove()
     int remove(char *filename)

     Delete <filename>, if it exists.  This function returns 0 for
success, or ERROR, see errno. You can't remove directories with this
call.

rename()
     int rename(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.  This function returns 0 for success, or
ERROR, see errno then. Not all filesystems support moving directories
around!

tmpfile()
     FILE *tmpfile(void)

     This function has not yet been implemented.

     SEE:  tmpnam()

tmpnam()
     char *tmpnam(char *s)

     Generate a unique filename to be used for a temporary file.  The
filename will have the form "TEMP$nnn.TMP" where "nnn" is a sequence of
numeric digits.  The name will unique in the current working directory.
 If <s> is NULL, space will be obtained from malloc() to store the
filename and thus must be free()'d by the caller. If <s> is not NULL,
 the filename will be copied into the buffer provided.  This function
returns NULL for failure, or a pointer to the filename for success.

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

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

     SEE:  setvbuf()

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

     If <bmode> is _IONBF, make <fp> unbuffered.  If <buf> is NULL, a
buffer of <size> bytes is used.  If <size> is NULL as well, <BUFSIZE>
is used.  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:

     _IONBF     No Buffering
     _IOFBF     Full Buffering (normal)
     _IOLBF     Line Buffering (this increases output speed)

     SEE:  setbuf()

Process Communication
     These (unimplemented) functions may eventually become a standard
on multitasking systems.  They will be implemented soon.

                      Function:  popen()
                      Function:  pclose()

popen()
     FILE *popen(char *command, char *type, FILE *fp)

     This function has not yet been implemented.

     SEE:  pclose()

pclose()
     int pclose(FILE *fp)

     This function has not yet been implemented.

     SEE:  popen()

Formatted Input/Output
     The standard library functions for formatted input and output.

                       Function:  fprintf()
                       Function:  printf()
                       Function:  sprintf()
                       Function:  vfprintf()
                       Function:  vprintf()
                       Function:  vsprintf()
                       Function:  fscanf()
                       Function:  scanf()
                       Function:  sscanf()

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

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

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

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

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

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

vfprintf()
     int vfprintf(FILE *fp, char *fmt, va_list ap)

     Formatted output to the stream <fp> with a variable argument list.
See _printf() for formatting and va_start() for stdarg explaination.

vprintf()
     int vprintf(FILE *fp, va_list ap)

     Formatted output to the stdout stream with a variable argument
list.  See _printf() for formatting and va_start() for stdarg
explaination.

vsprintf()
     int vsprintf(char *buf, char *fmt, va_list ap)

     Formatted outout to the string <buf> with a variable argument
list.  See _printf() for formatting and va_start() for stdarg
explaination.

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

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

     When the input stream is a device, the _tttty() function is used
to obtain input.

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

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

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

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

Formatting Input/Output
     These functions are internal to the extended dLibs library.  They
document the formatting strings.

                      Function:  _printf()
                      Function:  _scanf()

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

     This function does all the work for printf(), et al.  Many systems
do not provide direct access to this function (or its equivalent), but
it is useful for writing your own printf()-like functions.  Since this
is a non-standard interface, and v[sf]print() is now available, you
should probably use the stdarg functions instead.  <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
or something like this, depending on put() function.
Calls to <put> are of the form:

     "(*put)(c, op);"

     <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|h|L]
               {d|i|u|o|x|X|b|c|s|f|e|E|g|G|p|n|%}

     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 '#' char alters the output form of numbers: Hex values are prefixed
by '0x' or '0X', octal ones by a '0'. The padding char will be a '0'.
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' specifies that the
associated value is a "long" type, the 'h' as a short type and the 'L'
is ignored for compatibility this time (long double).
The trailing character specifies the format type, as follows:

  format char   argument type
          d,i   int    Signed Decimal Integer
          u     int    Unsigned Decimal Integer
          o     int    Unsigned Octal Integer
          x     int    Unsigned Hexadecimal Integer
          X     int    Unsigned Hexadecimal Integer
          b     int    Unsigned Binary Integer
          c     int    Character
          s     char * String
          f     double
          e,E   double
          g,G   double
          p     void * Pointer (displayed in %06.8lX format)
          n     int *  the number of processed arguments is put to the
                       int pointer, no output
     So a float value is always to be casted to double, though you
will get rounding errors while casting sometimes.
     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.

     The return value, passed to the interface function, is the number
of charcaters written or (-1) for an error (stream not open for writing,
or something to detect with the strem-eror macros).

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

     This function does all the work for scanf(), et al.  Many systems
do not provide direct access to this function (or it's equivalent), but
it is useful for writing your own scanf()-like functions.  <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|f|e|g|F|E|G}

     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' (or capitalizing the conversion character) specifies that
the associated variable is a "long" type, where long int is a long value,
long float a double value.  The trailing character
specifies the format type, as follows:

format char    argument type
         d     int    Signed Decimal Integer
         u     int    Unsigned Decimal Integer
         o     int    Unsigned Octal Integer
         x     int    Unsigned Hexadecimal Integer
         b     int    Unsigned Binary Integer
         i     int    Unsigned Decimal/Octal/Hexadecimal/Binary Integer
         c     char   Character
         s     char * String
         e     float  Float
         f     float  Float
         g     float  Float
         E     double Double
         F     double Double
         G     double Double
     [...]     char * String
     [^...]     char * 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 first 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.  A right brace character
(']') can be included as one of the list of characters by placing it as
the first character in the list.  If the '^' negation character is the
first character, the included brace should be the next character after
the '^'.  For maximum portability, a range should be explicitly given
(a good example would be "%[0123456789]"), but to allow for porting
from systems with smarter scanf() functions, this version of scanf()
also supports ranges represented using a <first>-<last> form (eg:
"%[0-9]").  To use the first-last form, the character <first> must be
lexically less than or equal to the character <last>.  If this rule is
violated, or if the hyphen is the first or last character of the list,
the hyphen will be assumed to be just another character in the list and
no range expansion will be done.  The resulting string containing the
characters in (or not in) the list will be null terminated.  It should
be noted that, unlike most of the other formats, this conversion does
allow the programmer to specify that whitespace characters will be
included in the resulting string.

Stream Input/Output
     The list of functions for input and output on streams without any
formatting.
                       Function:  fgetc()
                       Function:  fgets()
                       Function:  fputc()
                       Function:  fputs()
                       Function:  getchar()
                       Function:  gets()
                       Function:  putchar()
                       Function:  puts()
                       Function:  fread()
                       Function:  fwrite()
              internal Function:  _tttty()
                          Macro:  getc()
                          Macro:  ungetc()
                          Macro:  putc()

fgetc()
     int fgetc(FILE *fp)

     Get a character from <fp>.  This function returns a character or
EOF.

     When the input stream is a device, the _tttty() function is used
to obtain input.

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

     Gets 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.

     When the input stream is a device, the _tttty() function is used
to obtain input.

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

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

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

     Write the characters in <data> to the stream <fp>.  There is no
<newline> character added at the end of the string.

     See puts().

getc()
     int getc(FILE *fp)

     This is the same as fgetc(), but it is implemented as a macro.

     When the input stream is a device, the _tttty() function is used
to obtain input.

getchar()
     int getchar(void)

     This is identical to "fgetc(stdin)".

     When the input stream is a device, the _tttty() function is used
to obtain input.

gets()
     char *gets(char *data)

     Gets 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.

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

     This is identical to fputc(), but it is implemented as a macro.

putchar()
     int putchar(char c)

     This is identical to "fputc(c, stdin)".

puts()
     void puts(char *data)

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

     See fputs().

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

     This is identical to fungetc(), but it is implemented as a macro.

fread()
     int fread(char *data, size_t size, size_t 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.

     SEE:  fwrite()

fwrite()
     int fwrite(char *data, size_t size, size_t 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.

     SEE:  fread()

_tttty()
     int _tttty(FILE *fp)

     "Teeny Tiny TTY" driver function.  This function is internal to
XdLibs, but its name is documented to allow you to replace it with a
tty driver of your own.  In brief, this function is supposed to read
from <fp> up to a newline character, putting the character in the FILE
buffer, and return the number of characters read (much like _fillbuf()
in some systems).  If the stream is in binary mode, a full buffer is to
be read, with no translation.  It outputs every character collected in
the buffer to stdout.
This function performs just a Fread() call when MiNT is active
because MiNT has a working tty driver.  Without MiNT running it emulates
a default tty as far as possible, so the following characters will
cause some action:

     ^U,^@   Kill Line
     ^V      Quote Next Character
     ^D      End Of File
     ^C, ^\  Break (Kill Process)
     ^H, ^?  Erase Last Character
     ^W      Erase Last Word
     ^J, ^M  Newline

     NON-STANDARD:

     ^[      Send to stdout, but do not keep this character (or the
             next character) in the buffer.

Positioning In Streams
     Positioning The File Pointer In Streams

                  Function:  fseek()
                  Function:  ftell()
                  Function:  rewind()
                  Function:  fgetpos()
                  Function:  fsetpos()

fseek()
     int fseek(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.

     WARNING:  fseek() returns 0 for success, non-zero for failure,
               according to the ANSI standard.  Some implementations
               use 0 for failure.  This function is maintained for
               compatibility with old programs.  The fsetpos() function
               should be used in new code.

     SEE:  ftell()
           fsetpos()

ftell()
     long ftell(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.  This function is maintained for compatibility
with old programs.  The fgetpos() function should be used in new code.

     SEE:  fseek()
           fgetpos()

rewind()
     void rewind(FILE *fp)

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

fgetpos()
     int fgetpos(FILE *fp, fpos_t *pos)

     Get the position of the stream <fp> and store it at the location
pointed to by <pos>.  This is the new X3J11 function to replace
ftell().  This function returns 0 for success and ERROR for failure.

     SEE:  fsetpos()

fsetpos()
     int fsetpos(FILE *fp, fpos_t *pos)

     Set the position of the stream <fp> to the value stored at the
location pointed to by <pos>.  Note that this function is only required
to work properly for a <pos> value which was previously obtained by
fgetpos() on the same stream.  This is the new X3J11 function to
replace fseek().  This function returns 0 for success and ERROR for
failure.

     SEE:  fgetpos()

Standard Input/Output Error Handling
        Standard Input/Output Error Handling

                   Function:  clearerr()
                   Function:  feof()
                   Function:  ferror()
                   Function:  perror()
                   Macro      fpending()

clearerr()
     void clearerr(FILE *fp)

     Clear the error flag on <fp>.

feof()
     int feof(FILE *fp)

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

ferror()
     int ferror(FILE *fp)

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

fpending()
     int fpending(FILE *fp)

     Returns the number of Bytes waiting in the stream <fp>'s buffer.
This maybe usefull if a fputc() or fwrite() returned an error.
In the stream buffers the <NL>s are expanded to <CR><NL> if this feature
isn't switched of writing (__FWRT_BIN__) or reading and writing
(binary mode stream,  __FRW_BIN__).

     fflush() resets a stream buffer to 0 bytes pending in any case!

perror()
     void perror(char *msg)

     Write <msg> (if non-NULL and non-empty) to the stderr stream,
followed by ": " and a system error message derived from the value of
errno.

Extensions to stdio

     These functions are non-standard, but sometiomes useful.

                     Function:  fileno()
                     Function:  fdopen()
                     Function:  fopenp()
                     Function:  fungetc()
                     Function:  ungetchar()
                     Function:  fgetw()
                     Function:  fputw()
                     Function:  fgetl()
                     Function:  fputl()
                     Function:  fgetf()
                     Function:  fputf()
                     Function:  fgetd()
                     Function:  fputd()

fileno()
     int fileno(FILE *fp)

     Return the file handle associated with the stream <fp>.
e.g. for use with fstat(), ...

     Think of calling fflush() on this stream before mixing stream
and low level file functions.


fdopen()
     FILE *fdopen(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 function allows a file opened with the low level open() call
to be used as a buffered or translated stream.  A pointer to a
FILE struct is returned, or NULL for errors.

fopenp()
                                                               -lextra
     FILE *fopenp(char *filename, char *mode, char *path)

     Find <filename> somewhere in the list of paths <path> and open it
with <mode>. Refer to the fopen() function for valid <mode> values.

     <path> maybe a NULL pointer, then the env variable $PATH is used for
searching the file.
     If <path> is a null-string ("") pointer, only the name <filename> is
modified by the pfindfile() function, e.g. according to $UNIXMODE, ... .
     <path> may point to any list of path strings seperated by commas,
semicolons or colons.

     Cause this function uses pfindfile() all implemented $UNIXMODE
translations are done (e.g. slashes as filename seperators, ...).

     See fopen() pfindfile()

fungetc()
     int fungetc(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.

ungetchar()
     int ungetchar(char c)

     Same as "fungetc(c, stdin)".

fgetw()
                                                               -lextra
     short fgetw(FILE *fp)

     Get a short value from the stream <fp>.  The high-order byte is
read first.  Use feof()/ferror() if you got a '-1' to test for
end-of-file. Think of '\n' translation if <fp> is not in binary mode
or __FRW_BIN__ is unset.

fputw()
                                                               -lextra
     short fputw(short n, FILE *fp)

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

fgetl()
                                                               -lextra
     long fgetl(FILE *fp)

     Get a long value from the stream <fp>.  The high-order byte is
read first.  Use feof()/ferror() if you got a '-1' to test for
end-of-file. Think of '\n' translation if <fp> is not in binary mode
or __FRW_BIN__ is unset.

fputl()
                                                               -lextra
     long fputl(long n, FILE *fp)

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

fgetf()
                                                               -lextra
     float fgetf(FILE *fp)

     Get a float value from the stream <fp>.  The high-order byte is
read first.  Use feof()/ferror() if you got a '-1' to test for
end-of-file. Think of '\n' translation if <fp> is not in binary mode
or __FRW_BIN__ is unset.

fputf()
                                                               -lextra
     float fputf(float n, FILE *fp)

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

fgetd()
                                                               -lextra
     double fgetd(FILE *fp)

     Get a double value from the stream <fp>.  The high-order byte is
read first.  Use feof()/ferror() if you got a '-1' to test for
end-of-file. Think of '\n' translation if <fp> is not in binary mode
or __FRW_BIN__ is unset.

fputd()
                                                               -lextra
     double fputd(double n, FILE *fp)

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

Character Functions
     These are the standard character type functions.  To use them,
include the CTYPE.H header file.  The macros in this section use a
table from the LIBC.A library.

     Please note that the isxxxx() functions, except the isascii()
function, only have defined values is isascii() is TRUE (which is to
say that they only work properly on values between 0x00 and 0x7F).

       Function:  toupper()            Function:  tolower()
          Macro:  _toupper()              Macro:  _tolower()
          Macro:  toascii()               Macro:  isalnum()
          Macro:  isalpha()               Macro:  isascii()
          Macro:  iscntrl()               Macro:  isdigit()
          Macro:  isgraph()               Macro:  islower()
          Macro:  isprint()               Macro:  ispunct()
          Macro:  isspace()               Macro:  isupper()
          Macro:  isxdigit()

toupper()
     int toupper(int c)

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

tolower()
     int tolower(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.

_toupper()
     MACRO _toupper(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.

_tolower()
     MACRO _tolower(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.

toascii()
     MACRO toascii(int c)

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

isalnum()
     MACRO isalnum(int c)

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

isalpha()
     MACRO isalpha(int c)

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

isascii()
     MACRO isascii(int c)

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

iscntrl()
     MACRO iscntrl(int c)

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

isdigit()
     MACRO isdigit(int c)

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

isgraph()
     MACRO isgraph(int c)

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

islower()
     MACRO islower(int c)

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

isprint()
     MACRO isprint(int c)

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

ispunct()
     MACRO ispunct(int c)

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

isspace()
     MACRO isspace(int c)

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

isupper()
     MACRO isupper(int c)

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

isxdigit()
     MACRO isxdigit(int c)

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

String Functions
     These functions are all related to strings in one way or another.
To use these functions, you must include the STRING.H header file.

        6.1 String Library Manipulate And Len
        6.2 String Library Copy And Cat
        6.3 String Library Compare And Find
        6.4 Number To String Functions

String Manipulation Library
    The functions to get the string length and to manipulate strings

           Function:  strlen()
           Function:  strset()           Function:  strnset()
           Function:  bzero()            Function:  memset()
           Function:  strlwr()           Function:  strupr()
           Function:  ctlcnv()
           Function:  strrev()
           Function:  strtrim()
           Function:  strtok()
           Function:  strrpl()           Function:  strirpl()
           Function:  stradj()

strlen()
     size_t strlen(char *string)

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

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

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

     SEE:  strnset()

strnset()
     char *strnset(char *string, char c, size_t n)

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

     SEE:  strset()

bzero()
     char *bzero(char *buf, size_t cnt)

     Zero (erase) <cnt> characters in <buf>.  This function returns a
pointer to <buf>.

memset()
     char *memset(char *dest, char data, size_t len)

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

strlwr()
     char *strlwr(char *string)

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

     SEE:  strupr()

strupr()
     char *strupr(char *string)

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

     SEE:  strlwr()

ctlcnv()
     char *ctlcnv(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 (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 are removed)

     A pointer to the modified <string> is returned.

strrev()
     char *strrev(char *string)

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

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

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

strtok()
     char *strtok(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.  Please 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.

strrpl()
     int strrpl(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.

     SEE:  strirpl()

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

     This function is the same as strrpl(), except it ignores the case
of alphabetic characters.

     SEE:  strrpl()

stradj()
     char *stradj(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.

String Library Copy And Cat
     The standard functions to copy or concatenate strings

           Function:  strcpy()              Function:  strncpy()
           Function:  strcat()              Function:  strncat()
           Function:  strpcpy()
           Function:  strdup()
           Function:  substr()              Function:  subnstr()
           Function:  memmove()             Function:  lmemmove()
           Function:  memcpy()              Function:  lmemcpy()
           Function:  memccpy()

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

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

     SEE:  strncpy()
           strpcpy()

strncpy()
     char *strncpy(char *dest, char *source, size_t 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.

     SEE:  strcpy()
           strpcpy()

strcat()
     char *strcat(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.

     SEE:  strncat()

strncat()
     char *strncat(char *dest, char *source, size_t 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.

     SEE:  strcat()

strpcpy()
     char *strpcpy(char *dest, char *start, char *stop)

     Copies characters from <start> up to <stop> into <dest>.  The
character pointed to by <stop> is not copied, and MUST be in the same
string as <start>.  The <dest> pointer is returned.

     SEE:  strcpy()
           strncpy()

strdup()
     char *strdup(char *string)

     Create a copy of <string> and return a pointer to the copy.
Storage for the copy is obtained from malloc().

substr()
     char *substr(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.

     SEE:  subnstr()

subnstr()
     char *subnstr(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.

     SEE:  substr()

memmove()
     char *memmove(char *dest, char *source, size_t 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.

     SEE:  lmemmove()

lmemmove()
     char *lmemmove(char *dest, char *source, long len)

     This function is the same as memmove(), except a long value is
used for <len>.

     SEE:  memmove()

memcpy()
     char *memcpy(char *dest, char *source, size_t 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 NOT done.

     SEE:  lmemcpy()

lmemcpy()
     char *lmemcpy(char *dest, char *source, long len)

     This function is the same as memcpy(), except a long value is used
for <len>.

     SEE:  memcpy()

memccpy()
     char *memccpy(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.  If <c> is found, a
pointer to the character following <c> in <dst> is returned, or NULL is
<cnt> reaches 0 before <c> is found.

String Library Compare And Find
     The standard functions to compare strings and to find a substring or
characters in a string.

           Function:  memchr()
           Function:  strcmp()              Function:  strncmp()
           Function:  stricmp()             Function:  strnicmp()
           Function:  memcmp()              Function:  memicmp()
           Function:  strstr()              Function:  stristr()
           Function:  strchr()              Function:  strrchr()
           Function:  strpos()              Function:  strrpos()
           Function:  strspn()              Function:  strcspn()
           Function:  strpbrk()             Function:  strrpbrk()

memchr()
     char *memchr(char *buf, char c, size_t cnt)

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

strcmp()
     int strcmp(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

     SEE:  strncmp()
           stricmp()
           strnicmp()

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

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

     SEE:  strcmp()
           stricmp()
           strnicmp()

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

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

     SEE:  strcmp()
           strncmp()
           strnicmp()

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

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

     SEE:  strcmp()
           strncmp()
           stricmp()

memcmp()
     int memcmp(char *blk1, char *blk2, size_t 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.

     SEE:  memicmp()

memicmp()
     int memicmp(char *blk1, char *blk2, size_t len)

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

     SEE:  memcmp()

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

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

     SEE:  stristr()

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

     This function is the same as strstr(), but ignore the case of any
alphabetic characters.

     SEE:  strstr()

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

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

     SEE:  strrchr()

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

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

     SEE:  strchr()

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

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

     SEE:  strrpos()

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

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

     SEE:  strpos()

strspn()
     int strspn(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.

     SEE:  strcspn()

strcspn()
     int strcspn(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.

     SEE:  strspn()

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

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

     SEE:  strrpbrk()

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

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

     SEE:  strpbrk()

Number To String Functions
     The standard functions to get numbers in string (digit) notation.
This is  usefull, if you want to print any number anywhere.

                          Function:  ltoa()
                          Function:  ultoa()
                          Function:  itoa()

ltoa()
     char *ltoa(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.

     SEE:  ultoa()
           itoa()

ultoa()
     char *ultoa(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.

     SEE:  ltoa()
           itoa()

itoa()
     char *itoa(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.

     SEE:  ltoa()
           ultoa()

Assert, Stack, & Error Handling Functions
     To use the assert() macro, you must include the ASSERT.H header
file. The other functions are not part of a standard C library.

                         Macro:  assert()

                      Function:  teststack()
                      Function:  strerror()
                      Function:  perrorf()

                      Variable:  int errno;

assert()
     MACRO assert(condition)

     If <condition> is not true at run-time, this macro causes an
assert failure message to be written to stderr, displaying the line
number and source file name, and aborts the program.  If the symbol
NDEBUG is #defined (usually with a -D option to cc), all assert() calls
are disabled.

teststack()
                                                               -lextra
     long teststack(void)

     This is a non-standard function, but helpful for debugging stack
problems.  It will return the number of bytes free stack. If the value
is negative, the stack growing into the program's code.


strerror()
     char *strerror(errnum)

     Return the system error message for error <errnum>.  If <errnum>
is outside the range of valid error numbers, NULL is returned.

perrorf()
     void perrorf(char *fmt[, arg1, ..., argN])

     Write the name of the program to the stderr stream, followed by
":", followed by a message formatted as by printf() from <fmt> and the
optional arguments, followed by ": " and a system error message derived
from the value of errno.  This is a non-standard extended version of
perror().

     SEE:  perror()

Variable Argument List Functions

     To use the macros in this section, you must include the STDARG.H
header file.

                            Macro:  va_start()
                            Macro:  va_arg()
                            Macro:  va_end()

                            Type:  va_list

va_list
     typedef ... va_list;

     This is the type required to perform a variable argument list
traversal. It is only used by the va_start(), va_end(), and va_arg()
macros.

va_start()
     MACRO va_start(list, param)

     This macro initializes the va_list variable <list> to begin
traversing variable argument lists.  <param> is the last parameter in
the function call before the variable arguments begin.  This parameter
MUST NOT be a register variable.

     SEE:  va_arg()
           va_end()

va_arg()
     MACRO va_arg(list, type)

     This macro retrieves a variable argument of type <type>, updates
the va_list variable <list>, and returns the value of the retrieved
argument.  The <type> should not be parenthesized.

     SEE:  va_start()
           va_end()

va_end()
     MACRO va_end(list)

     This macro must be called after all desired variable arguments
have been retrieved, to reset the context of the va_list variable
<list>.

     SEE:  va_start()
           va_arg()

Global Jump Functions

     To use these functions, you must include the SETJMP.H header file.

                        Function:  setjmp()
                        Function:  longjmp()
                        Function:  catch()
                        Function:  throw()

setjmp()
     int setjmp(jmp_buf context)

     Save <context> for longjmp().  You MUST include the SETJMP.H
header file to use this function.  Calling this function saves the
current program context in the context buffer provided and returns
zero.  A later call to the longjmp() function will cause the context to
be restored and your program will continue as if it just returned from
setjmp(), but this time with the (non-zero) return value specified in
the longjmp() call.  THE SAVED CONTEXT WILL NOT BE VALID IF YOU EXIT
THE FUNCTION THAT CALLED the setjmp() function.

     SEE:  longjmp()

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

     Return <rv> to the <context> saved by setjmp().  You MUST include
the SETJMP.H header file to use this function.

     SEE:  setjmp()

catch()
     int catch(jmp_buf context, int (*func)())                  -lextra

     Execute <func> with <context> saved for throw().  You MUST include
the SETJMP.H header file to use this function.  Return the value
returned by <func>.  The main advantage of these functions over
catch/throw is the ability to return zero from the function executed,
and the logically "cleaner" encapsulation of the non-local jump
operation.  These functions are patterned after similar functions in
LISP.

     SEE:  throw()

throw()
     void throw(jump_buf context, int rv)

     Return <rv> to <context> saved by catch().  You MUST include the
     SETJMP.H header file to use this function.

     SEE:  catch()

Date/Time Functions
     To use the functions in this section, you must include the TIME.H
header file in your source code.

     The type time_t, defined in TYPES.H, is used for rawtime values.
These are not seconds since 1970, but rather an encoded time value with
the date in the high word and the time in the low word (used for time
comparisons) because one cannot be sure to find a TIMEZONE environment
variable on TOS machines so that a proper encoding method can be used.

         Function:  time()           Function:  asctime()
         Function:  ctime()          Function:  mktime()
         Function:  localtime()      Function:  gmtime()

         Function:  clock()

         UNISTD Functions:

         Function:  utime()          Function:  stime()


     All time functions, including stat() and fstat() use this local
time time_t format.  No function makes any changes to the values,
but the encoding is changed!

     Soon gmtime(), unixtime() and tostime() will be implemented; these
functions will try to calculate the requested values if a TIMEZONE
environment variable (TZ=...) is available at runtime.

     To get the current local time, do this:

     time_t now;
     char time_string[26];
     time (&now);
     strcpy(time_string, ctime(&now));

     //  Remember the newline in time_string[25]!

     The stat structure contains a time_t value as well.  To print the
date of a file after calling stat() with mystat_buffer, do this:

     struct stat mystat_buffer;
     char time_string[26];
     // if(!stat(filename, &mystat_buffer));
     strcpy(time_string, ctime(&mystat_buffer->st_time));

     If you have a tm structure filled with some values, you can get a
time string from it by doing this:

     struct tm mytime;
     char time_string[_TIME_STRING];
     strcpy(time_string, asctime(&mytime));

     If you want to get an encoded time value from a tm structure (for
setting the time stamp of a file with the utime() function), do this:

     struct tm mytime;
     time_t thistime;
     // Fill in the values to struct tm mytime now.
     thistime = mktime(&mytime);

     If you want to get a tm structure filled with values according to
a time_t value, use the localtime() function.

     time_t thistime;
     struct tm *time_struct;
     // Set thistime to your value now.
     time_struct = localtime(&thistime);

time()
     time_t time(time_t *rawtime)

     Get the current system clock date/time value.  Usually this
function returns the number of seconds elapsed since 00:00:00 UTC (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
time_t variable <rawtime> points to.

ctime()
     char *ctime(time_t *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 two seconds is possible.  A pointer
to the formatted string, which is held in an internal buffer, is
returned.

localtime()
     struct tm *localtime(time_t *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.

gmtime()
     struct tm *gmtime(time_t *rawtime)

     Since this function is not really implemented it returns NULL, as
specified by the proposed ANSI standard.  This function will soon be
implemented.

asctime()
     char *asctime(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.

mktime()
     time_t mktime(struct tm *time)

     Convert <time> structure value to raw time format.

clock()
     clock_t clock(void)

     Returns the elapsed time since program start.  The value divded by
CLK_TCK, will give you elapsed seconds.  This works only with an
"*_s.o" startup module, because setting _starttime is done in the
_main() function.

UNISTD.H, STAT.H & FCNTL.H Functions

     This section contains standard operating system calls and library
functions.  Using these functions, your source code will remain
reasonably portable.  Include the bracketed header file shown beside
the name of each function to use that function.  Some functions will
return ERROR when there is an error, and set errno, but others may not.

                11.1 File Handling
                11.2 Input/Output Functions
                11.3 Process Control Operating System Calls
                11.4 Creation Of Child Processes

File Handling
     The unistd file handling functions. They are mostly UNIX system calls.

             Function:  access()           Function:  link()
             Function:  chdir()            Function:  lseek()
             Function:  chmod()            Function:  mkdir()
             Function:  chown()            Function:  open()
             Function:  close()            Function:  pipe()
             Function:  creat()            Function:  rmdir()
             Function:  dup()              Function:  stat()
             Function:  dup2()             Function:  tell()
             Function:  size()             Function:  unlink()
             Function:  getcwd()           Function:  sync()
             Function:  isatty()           Function:  utime()
                                           Function:  umask()

access()
     int access(char *name, int amode)                   (UNISTD.H)

     Return zero if a file with the given <name> can be accessed in the
given <amode>.  Possible <amode> values are:

     F_OK           File Exists
     X_OK           File Is Executable
     W_OK           File Can Be Written
     R_OK           File Can Be Read (TOS:  Not Hidden)
     (R_OK|W_OK)    File Can Be Read & Written

chdir()
     int chdir(char *pathname)                           (UNISTD.H)

     Changes the current working directory to <pathname>.  If a device
is specified in <pathname> (<dev_char>:\<path>), the current drive is
changed too. Returns 0 for success, or ERROR:
     Then you will find in 'errno' the error number
          'EDRIVE'  if the gemdos device doesn't exist
          'EPTHNF'  if the path doesn't exist

chmod()
     int chmod(char *filename, int pmode)                (STAT.H)

     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.

     SEE:  stat()

chown()
     int chown(void)                                     (UNISTD.H)

     This function has not yet been implemented.

close()
     int close(int handle)                               (UNISTD.H)

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

     SEE:  open()
           creat()

creat()
     int creat(char *filename, int pmode)          (FCNTL.H/STAT.H)

     Create a new file with the given <filename>.  This is just a
call of open() with the arguments:

     open(filename, O_WRONLY|O_CREAT|O_TRUNC, pmode);

     If a file with the name already exists, it will be truncated
to zero bytes.  The <pmode> parameter specifies the attributes
initially given to the file.  If <pmode> is 0, '0644' is assumed.
For valid <pmode> values see open(), too.


dup()
     int dup(int handle)                                 (UNISTD.H)

     Return a second file handle which refers to the same file as the
given <handle>, and is the smallest available handle >= 0. The
close-on-exec flag is unset in the returned handle.

     SEE:  dup2()

dup2()
     int dup2(int handle1, int handle2)                  (UNISTD.H)

     Make <handle2> referring to the same file as <handle1>. This is
slightly different for MiNT and plain TOS. The close-on-exec flag
is unset in <handle2>.

     It will return the new second handle, which should be == <handle2>
for success. It returns a negative value for error.

     You will need this function e.g. for making the read-end of a pipe
pointing to stdin of a child process while another process gets the write-
end as stdout.

     SEE:  dup()

size()
                                                               -lextra
     long size(char *name)                              (STAT.H)

     Return the size of the file <name> in bytes.  Note that this is a
long value.  Return -1L if the file is not found.  NON-PORTABLE!
(this function was former called fsize())
     SEE:  stat()

getcwd()
     char *getcwd(char *buffer, int size)                (UNISTD.H)

     Get the full pathname of the current working directory.  This
value will ALWAYS end with a '\\' character.  <pathbuf> is a pointer to
a buffer of <size> bytes that will be used to store the current working
directory.  If <buffer> is NULL, a buffer of <size> bytes will be
malloc()ed.  The function returns a pointer to the buffer for success,
or NULL for failure, either because malloc() failed, or the value is
larger than <size>.  This function uses fullpath() to get the pathname,
therefore the buffer internal to fullpath() is overwritten.

isatty()
     int isatty(int handle)                              (UNISTD.H)

     Return non-zero if <handle> refers to a character device.
Negative handles always refer to character devices.

link()
     int link(void)                                      (UNISTD.H)

     This function has not yet been implemented.

lseek()
     long lseek(int h, long offset, int origin)          (UNISTD.H)

     Move file pointer for file <h> to specified location.  <origin>
specifies the starting point for the <offset> distance.  Valid <origin>
values are:

     SEEK_SET     Seek from beginning of file.   (0)
     SEEK_CUR     Seek from current location.    (1)
     SEEK_END     Seek 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.

mkdir()
     int mkdir(char *pathname)                           (STAT.H)

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

open()
     int open(char *filename, int iomode[, int pmode])  (STAT.H, FCNTL.H)

     Attempt to open <filename> with the given <iomode>.  A file handle
is returned if the open succeeds.  A negative error code is returned
for errors.  Valid <iomode> values are:

     O_RDONLY  Read Mode
     O_WRONLY  Write Mode
     O_RDWR    Read/Write Mode

     In addition to the (mutually exclusive) modes above, one or more
of the following options may be |-ed with <iomode>:

     O_NDELAY  Don't block for i/o on this file.
     O_APPEND  Start file pointer at end of file.
     O_TRUNC   If file exists, truncate to 0 length.
     O_CREAT   Create (using the Fopen() function) <filename> if it
               does not exist. You will have to specify <pmode>
                  with this flag set!
     O_EXCL    Return EEXIST if file exists and O_CREAT is specified
               (exclusive mode).

     not all filesystems support the following iomodes:

     O_DENYRW   deny both read and write access for others
     O_DENYW    deny write access to others
     O_DENYR    deny read access to others
     O_DENYNONE don't deny any access to others

     O_NOINHERIT private file (not passed to child)

     Valid <pmode> values are:

     S_IRUSR/S_IRGRP/S_IROTH     Read
     S_IWUSR/S_IWGRP/S_IWOTH     Write
     S_IXOTH/S_IXGRP/S_IXUSR     Executable

     Not all file systems support these values, so they may be ignored,
      or set to the following ones:

     S_IREAD   Read       == (S_IRUSR|S_IRGRP|S_IROTH)
     S_IWRITE  Write      == (S_IWUSR|S_IWGRP|S_IWOTH)
     S_IEXEC   Executable == (S_IXUSR|S_IXGRP|S_IXOTH)


     NOTE:  It is possible to open the character devices "con:",
            "aux:", and "prn:" with this call, but don't do so
               with MiNT running - use (u:)\dev\<filename>!
               Negative handles (-1..-3) may be be returned.
               Error returns are always < -3.
            The FCNTL.H header file contains <iomode> constants.  For
            <pmode> constants, see stat.h header file.

     SEE:  creat()
           close()

pipe()
     int pipe(void)

     This function has not yet been implemented.

rmdir()
     int rmdir(char *pathname)                           (UNISTD.H)

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

stat()
     int stat(char *name, struct stat *statbuf)          (STAT.H)
     int lstat(char *name, struct stat *statbuf)
     int fstat(int fd, struct stat *statbuf)

     Get file status for file <name> or an open file with handle <fd>.
The status information about the file is written to buffer <*statbuf>.
Return 0 if okay, or ERROR (-1) if one. See errno for the error then.
Volume labels are not included in the search.  The file STAT.H header
file must be included if you use this function, since it defines
the stat structure.
     lstat() won't follow symbolic links like stat() does, so use lstat()
if you need some information about a link.

     The stat buffer soon will change and include informations about valid
fields after return.

tell()
     long tell(int h)                                    (UNISTD.H)

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

unlink()
     int unlink(char *filename)                          (UNISTD.H)

     Delete <filename>, if it exists.  Return 0 for success, or a
negative error code.  This function, of course, should really do
unlink() if the filesystem <filename> is in supports links. Returns
0 or ERROR - see errno then.


sync()
     sync()

     Not all filesystems support this. It will return ERROR and errno is
set to EINVAL then.

-    not implemented this time -

utime()
     int utime(char *pathname, time_t *rawtime)          (UNISTD.H)

     This function works like the 'touch' shell command.

     If <rawtime> is NULL, set file <pathname>'s time stamp to
current date and time. Otherwise <rawtime> points to an encoded time_t
value, and the file's time stamp is set to this date & time value.
If it returns not 0, but ERROR, see errno.
     Not all filesystems support changing the timestamps of directories.
This function tries to set errno to EINVFN then, and returns ERROR.

     SEE:  time()

umask()
     unsigned short umask(unsigned short complmode)     (STAT.H,UNISTD.H)

     Set the mode bits for file creation to <complmode>. The bits set
are not default bits - complement mode! Returns last <umask>.

Input/Output Functions
      The unistd input/output functions here are writing and reading from
files.

                      Function:  read()
                      Function:  lread()
                      Function:  write()
                      Function:  lwrite()

read()
     int read(int h, char *data, int length)             (UNISTD.H)

     Read <length> bytes from the file referenced 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.
Please note that the maximum number of bytes that can be read by this
function is MAXINT.

     SEE:  lread()

lread()
     long lread(int h, char *data, long length)          (UNISTD.H)

     This function is identical to read(), but uses a long value for
the number of bytes to read.

     SEE:  read()

write()
     int write(int h, char *data, int length)            (UNISTD.H)

     Write <length> bytes to the file referenced 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.  Please
note that the maximum number of bytes that can be written by this
function is MAXINT.

     SEE:  lwrite()

lwrite()
     long lwrite(int h, char *data, long length)         (UNISTD.H)

     This function is identical to write(), but uses a long value for
the number of bytes to write.

     SEE:  write()

Process Control Operating System Calls
     Some functions for process control.

            Function:  alarm()             Function:  brk()
            Functions: getpid(),getppid()  Functions: getuid(), etc.
            Function:  exit()              Function:  kill()
            Function:  nice()              Function:  pause()
            Function:  sbrk()              Functions: setuid(), etc
            Functions: signal(), etc       Function:  sleep()
            Function:  stime()             Function:  time()
            Function:  usleep()

alarm()
     int alarm(unsigned int seconds)

          <seconds> > 0
     Install an alarm (i.e. a signal SIGALARM) in <seconds> seconds.
You will have to install a signal handler first, or the signal will
kill the process.
      <seconds> == 0
     Cancel any previous alarm() call.
          <seconds> == -1
     Return the number of seconds remaining of the pending alarm.

     The function will return 0 or the number of remaining seconds, or
ERROR (-1) if the call failed. See errno.  The standard TOS itself
doesn't support alarm(), you will find EINVFN in errno then.

     See signal().

brk()
     int brk(void *address)                              (MALLOC.H)

     Set the "break" to <address>.  Return 0 for success.  If <address>
is not a valid break value, -1 will be returned and the break will not
be moved.  HANDS OFF! This function shrinks the stack size, and will
not work with accessories or programs using the ACCAPP_S.O startup
module.

getpid()
     int getpid(void)
     int getppid(void)

     getpid returns the process id if OS supports this function. If
not it returns an integer value unique for any process running.
getppid does the same for the parent process.


getuid()
     int getuid(void)                                       (UNISTD.H)
     int getgid(void)
     int geteuid(void)
     int getegid(void)

     These functions have not yet been implemented, but there are defines
in unistd.h which just call the matching MiNT functions.


kill()
     int kill(int pid, int sig)                      (SIGNAL.H,UNISTD.H)

     Send signal <sig> to process <pid>.
This function has not yet been implemented, but there is a define in
unistd.h which just calls the MiNT function.

nice()
     int nice(int p)

     This function has not yet been implemented, but there is a define
in unistd.h for calling just the MiNT function.

pause()
     int pause()

     Wait for a signal not masked or ignored is sent to the process.
This function has not yet been implemented, but there is a define in
unistd.h which just calls the MiNT function.

     SEE:  sleep()
           usleep()
             signal()

sbrk()
     char *sbrk(int amount)                              (MALLOC.H)

     Move the "break" by <amount>.  The break is the line between the
top of the heap and the bottom of the stack.  The size of the
stack/heap area is defined by _STKSIZ.  Initially, the heap uses zero
bytes.  Since the malloc() function does not use the heap, often the
heap will stay that way.  This function moves the location of the break
by <amount> bytes, positive or negative, and returns the old value of
the break.  If this causes a collision with the stack, or a negative
value reduces the heap below zero bytes, NULL is returned and the break
is not moved.  Please note that the heap pointer is moved by EXACTLY
the <amount> specified.  If you want to ensure that sbrk() will return
word-aligned memory segments, you must make sure that <amount> is
always even, since the heap is initially aligned properly.  HANDS OFF!
This function shrinks the stack, and will not work with accessories or
programs using the ACCAPP_S.O startup module.

setuid()
     int setuid(void)
     int seteuid(void)
     int setgid(void)
     int setegid(void)

     If these functions return ERROR (-1), check errno for the reason
they didn't work. This maybe EINVFN, if the OS doesn't support them.

signal()
     _Sigfunc signal(int sig, _Sigfunc func);        (SIGNAL.H, UNISTD.H)
     long sigsetmask(long mask)
     long sigblock(long mask)
     long sigpending()
     int sigaction (int isg, struct sigaction *act,
                         struct sigaction *oact)

     These functions have not yet been implemented (but soon will be).
But there are defines in signal.h for acces to the MiNT functions. They
return long values! instead of usuall int (short) values. Please look
at MiNT docs for usage of signal functions.
     Example:
        extern void nullfunc(long sig);
        _Sigfunc old_alarm_func;
        long old_sigmask, seconds = 3L;

        old_sigmask = sigblock(~0L);
        old_alarm_func = signal(SIGALRM, nullfunc);
        alarm(0L);       /* reset pending alarms  */
        alarm(seconds);
        pause();      /* now wait    */
        signal(SIGALRM, old_alarm_func);     /* restore     */
        sigsetmask(old_sigmask);


_Sigfunc
 _Sigfunc is a pointer to a 
 void function with one long
 argument. This argument is
 the signal.

sleep()
     unsigned int sleep(unsigned int seconds)         (TIME.H/UNISTD.H)

     Suspend process for <seconds> seconds.  If there is no OS function
available for doing this (i.e. the MiNT call), it is implemented as a
start_timer()/time_since() tight loop waiting for the specified amount
of time to pass.

     Bugs: any former alarm() call is canceled with this function.

     SEE:  usleep()

stime()
     int stime(long *rawtime)                            (UNISTD.H)

     Set the system clock to <rawtime>.

     SEE:  time()

usleep()
     void usleep(unsigned long usec)                  (TIME.H/UNISTD.H)

     Suspend operation for <usec> microseconds.  This function works
like sleep().  Only milliseconds (i.e. usec / 1000 )are taken into
account!  If no OS call is available it works like sleep().

     Bugs: any former alarm() call is canceled with this function.

     SEE:  sleep()

Creation Of Child Processes
     Since it is not possible to do a true UNIX fork() operation
without MiNT, we have to the exec...() functions some similar spawn...()
functions.  The missing wait() functions will be implemented soon.

     A spawn...() function runs a command in a subjob, while an
exec...() function will replace the program in the current process
by the executed command. So an exec...() function usually won't return.
If fork() or vfork() return an error like EINVFN you will have to use
a spanw...() function to run a subjob.

      The spawn...() and exec...() functions are not to find in 'libc.a'
library file;  to use them, you need to link your source code with the
'libextra.a' file.

     The return codes:

     If an exec...() function returns, see errno for the reason. (This
will something like EIFILNF, ENSMEM)

     After a program was executed with the spawn...() functions they
return the return value of the executed program in the high byte and the
status in the low byte like wait() does.

     int return_value;
     return_value = spawn... ;

      (char)(return_value)            The Status Value
      (char)(return_value >> 8)       The Process' Exit Code

     The low byte contains the status of the OS call Pexec() or an
encoded signal if the process was killed.  If it is '-1' there was an
error creating the process.  If it is '1', the process terminated with a
negative error code (something went wrong).  If it is (& 0x80) the
child was killed by a signal/exception.  If you mask off the 0x80 you
will get the signal number.  At this time, only SIGINT (^C) and SIGBUS
(for an exception error) are valid if MiNT is not running!

     The new ARGV argument passing scheme is always used, including
empty argument handling and quoted arguments.

     Please note that by convention, argv[0] should be the name of the
program being executed. There is a special feature implemented for
handling <char *arg0>.

     The $UNIXMODE features "/r<x>" are expanded always.

exec functions
     The list of exec... functions, and similiar spawn...
functions. To use these functions, you should include the UNISTD.H header
file. All these functions are in library file 'libextra.a'.

            Function:  fork()                vfork()

            Function:  execl()               spawnl()
            Function:  execv()               spawnv()
            Function:  execlp()              spawnlp()
            Function:  execvp()              spawnvp()
            Function:  execle()              spawnle()
            Function:  execlpe()             spawnlpe()
            Function:  execve()              spawnve()
            Function:  execvpe()             spawnvpe()
            Function:  execvep()             spawnvep()
            Function:  execvpep()            spawnvpep()
            Function:  shell()

fork()
                                                             -lextra
     int fork()
     int vfork()

     Returns in the old context the process id of the newly created
proccess or -1 for an error (e.g. ENSMEM). If errno is EINVFN the OS
don't supports fork().

     If successfull it returns 0 in the new process, and you can
use any exec...() function after eventually redirecting some file handles
(close standard handle and open some file or pipe on it).

     While with fork() the child process inherits a copy of the parent's
memory, it shares the same address space with vfork().

     See dup(), dup2(), wait()

execl()
                                                             -lextra
     int execl(char *program, char *arg0, [ ..., char *argN], NULL)
     int spawnl(char *program, char *arg0, [ ..., char *argN], NULL)

     This function will execute <program>, passing <arg0>..<argN> to
it.  The argument list is terminated by NULL.

     There is a special feature implemented for <char *arg0>.

char*arg0
 The first argument should be the name of the
 program being executed.
 If you pass an empty string to the arg0 para- 
 meter (i.e. argv[0] for  spawnv... functions)
 the command's name is put there by the func-
 tions, after the eventually path search and
 $UNIXMODE translations are done.

execv()
                                                             -lextra
     int execv(char *program, char **argv)
     int spawnv(char *program, char **argv)

     This function is like execl() except <argv> points to a NULL
terminated list of pointers to arguments.  This is particularly useful
if the number of arguments is not known at compile time.

     There is a special feature implemented for <char *argv[0]>.


execlp()
                                                             -lextra
     int execlp(char *program, char *arg0, [..., char *argN], NULL)
     int spawnlp(char *program, char *arg0, [..., char *argN], NULL)

     The same like execl(), except:

     Use the environment variable $PATH to find <program> with the
pfindfile() function.  If <program> has no extension, the list of
extensions pointed to by char *_extensions (possibly made by _getsuffix()
function) is used.

     There is a special feature implemented for <char *arg0>.

execvp()
                                                             -lextra
     int execvp(char *program, char **argv)
     int spawnvp(char *program, char **argv)

     This function is like execv() except:

     Use the environment variable $PATH to find <program> with the
pfindfile() function.  If <program> has no extension, the list of
extensions pointed to by char *_extensions (possibly made by _getsuffix()
function) is used.

     There is a special feature implemented for <char *argv[0]>.

execle()
                                                             -lextra
     int execle(char *program, char *arg0, [..., char *argN],
                NULL, char *env0, ... char *envN, NULL)
     int spawnle(char *program, char *arg0, [..., char *argN],
                NULL, char *env0, ... char *envN, NULL)

     The same like execl(), except:

     Pass the environment strings <env0>...<envN) to the child program.

execlpe()
                                                             -lextra
     int execlpe(char *program, char *arg0, [..., char *argN],
                 NULL, char *env0, ... char *envN, NULL)
     int spawnlpe(char *program, char *arg0, [..., char *argN],
                 NULL, char *env0, ... char *envN, NULL)

     The same like execlp(), except:

     Pass the environment strings <env0>...<envN) to the child process.

execve()
                                                             -lextra
     int execve(char *program, char **argv, char **envp)
     int spawnve(char *program, char **argv, char **envp)

     like spawnv(), except:

     Pass the environment strings from <envp> (a pointer to a NULL
terminated list of pointers to environment strings) to the child
program.

execvpe()
                                                             -lextra
     int execvpe(char *program, char **argv, char **envp)
     int spawnvpe(char *program, char **argv, char **envp)

     like execvp(), except:

     Pass the environment strings from <envp> (a pointer to a NULL
terminated list of pointers to environment strings) to the child
program.

execvep()
                                                             -lextra
     int execvep(char *program, char **argv, char *envp)
     int spawnvep(char *program, char **argv, char *envp)

     like execv(), except:

     Pass the environment <envp> (a pointer to a NULL terminated list
of environment strings) to the child process.  This
function is provided for compatability with old source code/compilers
(despite the fact that the name has changed).

execvpep()
                                                             -lextra
     int execvpep(char *program, char **argv, char *envp)
     int spawnvpep(char *program, char **argv, char *envp)

     like execvp(), except:

     Pass the environment <envp> (a pointer to a NULL terminated list
of environment strings) to the child program.  This
function is provided for compatability with old source code/compilers
(despite the fact that the name has changed).

wait()
     int wait(int *rvp)

     This function is not implemented this time.

shell()
                                                             -lextra
     void shell(void)

     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.

     This function may not work with the current version of the
library.  If not, it will be fixed soon.

Miscellaneous Functions
     The functions in this section can be found on most systems.

               12.1 Memory Management
               12.2 Searching & Sorting
               12.3 Filenames & Paths

Memory Management
     To use these functions, you must include the STDLIB.H header file.

                     Function:  malloc()
                     Function:  calloc()
                     Function:  lalloc()
                     Function:  realloc()
                     Function:  lrealloc()
                     Function:  free()

     To use following functions, you must include the MALLOC.H header
file.

                     Function:  msize()
                     Function:  memavail()
                     Function:  alloca()

                     Variable:  long _BLKSIZ = 65536;

msize()
     long msize(char *addr)

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

memavail()
     long memavail(void)

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

alloca()
     void *alloca(unsigned int size)

     Allocate at least <size> bytes of memory from the stack.  This is
"automatic" variable space and will be freed when the function which
called alloca() exits.  DO NOT use the other dynamic memory functions
like free(), realloc() and msize() on the block returned by this
function.  A pointer to the requested block is returned, or NULL if
there is not enough stack space available.

Searching & Sorting

     To use the functions in this section, you must include the MISC.H
header file.

                            Function:  qsort()
                            Function:  hsort()
                            Function:  bsearch()
                            Function:  lsearch()
                            Function:  lfind()
                            Function:  swab()

                            Macro:  max()
                            Macro:  min()
                            Macro:  swap()

hsort()
                                                               -lextra
     void hsort(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.

lsearch()
                                                               -lextra
     void *lsearch(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 and <num> will be incremented.
Note that, unlike bsearch() and qsort(), the <num> parameter is a
POINTER to a location which holds the number of elements to sort.

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

     Like lsearch(), but do not add elements which are not found.
Please note that <num> is a POINTER, even though it is not modified.

swab
     void swab(int *src, int *dst, int n)

     Swap adjacent bytes while copying <n> bytes from <src> to <dst>.
This allows bulk translation to/from Intel byte ordering.  Please note
the backward order of the <src> and <dst> parameters.  Do not blame
me... this is how Microsoft specifies it.

max
     MACRO max(x,y)


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

     SEE:  min()


min
     MACRO min(x,y)

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

     SEE:  max()


swap
     MACRO swap(a,b)

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

Filenames & Paths

     These utility functions deal with PATHS and FILES, and are not
guaranteed to be standard or to have been explicitly tested.
     To use the functions in this section, you must include the STDLIB.H
header file.

                    Function:  tempnam()
                    Function:  fullpath()
                    Function:  findfile()
                    Function:  pfindfile()
                    Function:  wildcard()
                    Function:  wild()
                    Function:  basename()
                    Function:  suffix()
                    Function:  _splitpath()
                    Function:  _makepath()
                    Function:  _getsuffixes()
                    Variable:  char *_extensions
                    Variable:  char _spawn_ext[]

tempnam()
     char *tempnam(char *dir, *pfx)

     This function is similar to tmpnam(), but is somewhat more
flexible.  <dir> specifies the directory part of the filename.  If
<dir> is NULL, the TMPDIR environment variable will be used.  If TMPDIR
is not found, the current directory is used.  <pfx> specifies the
filename prefix (up to 5 characters).  The form of the filename will be
"dir\pfxnnn.TMP", similar to tmpnam().  The storage for the filename is
always obtained from malloc(), so the caller must free() it after use.
This function returns NULL for failure, or a pointer to the fully
expanded filename for success.

     SEE:  tmpnam()

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

     <part> is a (possibly) ambiguous file/path specification.  A
non-ambiguous file/path specification 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.

     The $UNIXMODE features "/" and "r<x>" are expanded by this function.

     See findfile() pfindfile() _unixmode

findfile()
     char *findfile(char *afn, char *ext)

     Return full file specification 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\0.tos\0.prg\0"
(note that the final null is added by the compiler to any string
constant) or <NULL>. If <afn> already has an extension, <ext> is not
used. If ext is NULL, no extension is added for searching.
     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.

     NOTE:  Several XdLibs functions call filefind(), so do not make
            too many assumptions about how long the internal buffer is
            going to stay valid.

               The $UNIXMODE features "/" and "r<x>" are expanded.

     SEE:  pfindfile() _unixmode


pfindfile()
     char *pfindfile(char *path, char *afn, char *ext)

     Like findfile(), but search all directories (separated by ',' or
';' or ':') in <path>. If <path> is NULL, the "PATH" environment variable
is used instead.  The colon seperator works only if no drive chars are
specified in the paths in <path>.

     If <afn> specifies a root path (i.e.  'a:\...', '\...'), or is
related to cwd (i.e.  '.\...', '..\...') <path> is not used.  The internal
buffer for findfile() is used by pfindfile().

     <ext> maybe a list of extensions (see findfile()) or NULL.

     The $UNIXMODE features "/" and "r<x>" are expanded.

     SEE:  findfile() _unixmode

wildcard()
                                                               -lextra
     char *wildcard(char *pathname)

     Return matches for a wildcard filename.  If <pathname> is not
NULL, the first file which matches <pathname> will be returned.  The
<pathname> may contain wildcards only in the filename portion, not in
any sub-directories.  Subsequent calls to wildcard() with a NULL
argument return the next matching filename.  NULL is returned when no
more files match.

      NOTE: The pointer returned points to an internal buffer which is
            overwritten with each call.  It should not be modified, and
            should be copied into a safe place if you want to save the
            value.

      This function will be no longer supported, and replaced with a
      DIRENTRY *getdirentries(char *path, char *wildc) function soon,
      cause this is the only way to support new MiNT system calls.

wild()
     int wild(char *totest, char *pattern)

     It returns TRUE for a match of <totest> and <pattern>, case is
significant.

     This function implements a complex pattern matching algorithm, called
FNRE (FileName Regular Expressions) much like UNIX regular expressions.
(original author is Fred Fish). The following wildcards are allowed in
<pattern>:

     *    - Skip any sequence of characters, including "." (unlike TOS);
            it matches no character, too.
     ?    - Matches any single character, including "." (unlike TOS).
     \    - Treat one of the special characters as a character
            instead of an operator.
     \nnn - Octal Character Value (e.g. '\033' == ESCAPE)
     [    - Begin a list of characters.
     ]    - End a list of characters.
               Allow any one character of the list within brackets.
               This maybe an enumeration or a range.
     -    - Range character within square brackets:
               Any charcater of this range in square brackets does match.
     ^    - Exclude character first in square brackets:
               Any charcater of this list in square brackets doesn't match.

     For there are two different exclude characters known, you can
     switch the character by assigning the global variable
     'char __EXCLUDE_CHAR__' to the one you prefer:
     __EXCLUDE_CHAR__ = '^'; or __EXCLUDE_CHAR__ = '!';

     Example: Fr*d                     = Fred, Fraud, Fried
              Jo?n                     = John, Join
              L[ai]p                   = Lip, Lap (but NOT Lop)
              L[^ai]p                  = Lop (but NOT Lip or Lap)
              Fr\*d                    = Fr*d
           Fred[0-9]                = Fred0, Fred2, (but NOT Fred)
              This \[is\] bracketed\!  = This [is] bracketed!

basename()
     char *basename(char *path)

     Returns a pointer to the begining of the filename part in <path>,
that is the first char after the last path seperator '\'.


suffix()
     char *suffix(char *path)

     Returns a pointer to the begining of the last suffix in <path>,
that is the '.' char after the last path seperator '\'. If there is
none, the returned pointer points to the <path> ending '\0' char.


_splitpath()
     char *_splitpath(char *src, *drive, *path, *file, *ext)

     Parse the <src> filename into component parts. Returns <src>.  If
any of the component pointers is NULL, that component will be parsed,
but not saved.  If a given component does not exists int the <src>
string, the component will be empty, ("").  The <drive> component will
be a drive letter followed by a colon, ("a:").  The <path> component
will be the subdirectory names leading up to the filename, but will not
include a trailing '\' unless the path the simply the root path "\",
and there will only be a leading '\' if the path is fully qualified, or
"rooted" ("\this\is\a\path\name").  The <file> component is the base
filename without any extension ("filename").  The <ext> component is
the file extension with no leading '.' ("txt").  Recommended sizes for
the components are:

     Drive[4]
     Path[128]
     File[10]
     Ext[4]

     SEE:  _makepath()

_makepath()
     char *_makepath(char *dst, *drive, *path, *file, *ext)


     Build the <dst> filename from component parts.  This function
returns <dst>.  This function is basically an inverse of _splitpath(),
and will accept the components parsed by _splitpath() as input.  It
will also allow a little more flexibility in that it will treat any
component which is a NULL pointer as an empty field, and the <path>
component may optionally have a trailing '\'.

     SEE:  _splitpath()

_getsuffixes()
     char *_getsuffixes(void)

     This is an internal function that deals with the variables
char *_extensions and char _spawn_ext[]. It makes a list of possible
suffixes for the spawn...() functions and the system() call to make it
possible locate the binary.
     It only changes _extensions when it is NULL. After the first call,
_extensions points to a list of possible extensions either by using
the environment variable $SUFFIX or an internal builtin list called
_spawn_ext.
     You can of course assign _extensions any usefull value in your source.
It should point then to a string like the default builtin one:
     char _spawn_ext[] = "\0.ttp\0.tos\0.prg\0.app\0.gtp\0\0";
or be NULL. You can also built in an own string
     char _spawn_ext[] = "<anything>";
so that the default one don't gets linked.

     The produced or builtin list always begins with >no extension< as
first element of the list. If you program is a GEM program, and running
under MultiTOS or MagiC you should make _extensions pointing to a list
not containing any GEMSUFFIX extensions. (With MultiTOS you can use
the $TOSSUFFIX enviornment variable.) e.g.:
     _extensions = "\0.ttp\0.tos\0\0";

_unixmode
     int _unixmode_root()
     int _unixmode_slash()
     int _unixmode_bin()

     These functions get some information from the $UNIXMODE env variable
for handling of filenames and paths.

     _unixmode_root() returns 0 or the drive char of the assumed
'root' directory.

     _unixmode_slash() returns TRUE if slashes in a path string should
be converted to backslashes.

     int _unixmode_bin() returns TRUE if no <NL> -> <CR><NL> processing
should be performed when writing to files.

     These internal functions are used by pfindfile(), findfile(),
fullpath() and exec...() functions. Other functions using pfindfile(),
like fopenp(), will get $UNIXMODe translated filenames, too.

     The __FWRT_BIN__ variable is set TRUE if _unixmode_bin() returns
TRUE when initializing the streams in _main().

$UNIXMODE
 $UNIXMODE is a documented
 environment variable for any
 Atari OS based on TOS.
 Currently supported features of
 $UNIXMODE are '/' for slashes in
 path strings, 'b' for no <NL> to
 <CR><NL> expansion and "r<x>":
 <x> is the drive char any root
 '/' path gets located. That is
 where "/usr", "/etc", ... are
 to find in the filesystem

TOS related Functions

The functions in this section are not portable.


                  13.1 Timer Functions
                  13.2 Extra Process Control

Timer Functions

                            Function:  start_timer()
                            Function:  time_since()

start_timer()
     clock_t start_timer(clock_t *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.  To use this function, include the
TIME.H header file.

     SEE:  time_since()


time_since()
     clock_t time_since(clock_t *t)

     Returns the number of 200Hz ticks since start_timer() was called
for timer <t>.  To use this function, include the TIME.H header file.

     SEE:  start_timer()

Extra Process Control

     The functions in this section are from LIBC.A & LIBEXTRA.A

                            Function:  Getbpact_pd()
                            Function:  GetTOSvers()
                            Function:  Getcookie()
                            Function:  GetMiNT()
                            Function:  gemdos()
                            Function:  bios()
                            Function:  xbios()
                            Function:  bdos()

Getbpact_pd()
     BASEPAGE *Getbpact_pd(void)                                 -lextra

     Get basepage pointer of act_pd.

     This function is useful for memory control in accessories.  The
blocks malloc() has allocated from TOS are only valid after an AC_CLOSE
IF the value of Getbpact_pd() is the same as after malloc() (to
save!!), or you find the saved value in the parents (bp->p_parent)
basepage.  To use this function, you must include the ATARI.H header
file. See 'hints.txt' for usage.

GetTOSvers()
                                                                 -lextra
     unsigned int GetTOSvers( long *OS_date, unsigned int *OS_conf,
                              unsigned int * OS_dosdate);

     This function will determine the TOS version.  The pointers may be
NULL if you are not interested in these values.  To use this function,
you must include the ATARI.H header file. The TOS version number itself
you can find in the global variable '_tos'.

Getcookie()
                                                             -lextra
     int Getcookie( long cookie, long *value );

     This function determines whether or not a cookie exists.  If it
returns FALSE, the cookie does not exist.  If the pointer is NULL, you
cannot know the value of the cookie.  To use this function, you must
include the ATARI.H header file.

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

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

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

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

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

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

bdos()
                                                             -lextra
     int bdos(int func, long parameter)

     Call operating system trap #2 (BDOS) function number <func>,
passing the specified <parameter>.  Please note that <parameter> must
always be a long value, even if only a 16-bit value is required by the
specified BDOS function.

Device Input/Output Functions

     Since these functions refer to BIOS devices, they are not
portable.  Using them in any other environment will likely cause
problems.  Their use is not suggested.

                            Function:  cfg_ch()
                            Function:  getch()
                            Function:  getche()
                            Function:  putch()
                            Function:  kbhit()
                            Function:  getln()
                            Function:  cputs()
                            Function:  cprintf()

cfg_ch()
                                                             -lextra
     int cfg_ch(int cfg)

     Configure getch()/putch() operations.  The following are legal
values for <cfg> and may be combined with the | operator:

     _CIOB          Use BIOS Level I/O
     _CIOCH         8-BIT Character Codes Only
     _CIOVT         Enable VT-52 Escape Sequence Processing

     The initial configuration value at run time is _CIOCH.  This
function returns the previous configuration value, and if <cfg> is -1
the value is not set.

getch()
                                                             -lextra
     int getch(void)

     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 taken from
the BIOS Bconin() function instead.  The BIOS level functions do not
process ^C, ^S or ^Q; 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
operating system.

getche()
                                                             -lextra
     int getche(void)

     This function is identical to getch(), but calls putch() to echo
the character.

putch()
                                                             -lextra
     char putch(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 do not process ^C, ^S or ^Q; the GEMDOS functions do.  At the
BIOS level, passing the _CIOVT option to cfg_ch() allows VT-52 escape
code processing on output.  The GEMDOS functions always do VT-52
emulation.  The BIOS functions default to skipping this overhead.  If
VT-52 emulation is desired, though, it can still be used through the
faster BIOS level routines 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.

kbhit()
                                                             -lextra
     int kbhit(void)

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

getln()
                                                               -lextra
     char *getln(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.  This function is no longer needed to
handle editable input/output from stdin, since the pseduo-tty driver
code built into fgetc() now handles line editing, but this function is
still useful if you want to supply your own get/put functions.

cputs()
                                                               -lextra
     void cputs(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.

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

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

-eof
