Computer Club Elmshorn Atari PD/CCE_PD.iso/mac/1000/CCE_1024.ZIP/CCE_1024/SOZLIB07.LZH/SOZDISTR/DOC/XDLIBS.TXT

Text File | 1994-07-27 | 90KB | 2,262 lines

if there are conflicts between this dicument and soz_libs.hyp the last one
shoulde be right. This problem will vanish when the documentation is
completely written in Texinfo.
        -jerry

Xdlibs.a and extended.lib are the two files of standard library of SOZOBON C
2.00X. There are some libraries like float.a aesfast.a, etc.  with own docs.

XDLIBS
standard library for SOZOBON C, based on dlibs by Dale Schumacher.

Some special multitasking related functions will be implemented next
months according to MiNT docs. A checking for MiNT's presence will be
done there.

contents:

1. HEADER FILES
2. STDLIB
    2.1 PROCESS CONTROL
    2.2 MEMORY MANAGEMENT
    2.3 TYPE CONVERSION
    2.4 MISCELLANEOUS FUNCTIONS
    2.5 STANDARD INTERNALS
3. STDIO
    3.1 FILE TO STREAM OPERATIONS
    3.2 PROCESS COMMUNICATION
    3.3 FORMATTED I/O
    3.4 FORMATTING I/O
    3.5 STREAM I/O
    3.6 POSITIONING in STREAMS
    3.7 STD I/O ERROR HANDLING
    3.8 UTILITIES
    3.9 EXTENSIONS AND INTERNALS
4. CHARACTER TYPE FUNCTIONS
5. STRING FUNCTIONS
    5.1 STRING LIB
    5.2 FORMATTING/TYPE CONVERSION
6. ASSERT AND ERRORHANDLING
7. VARIABLE ARGUMENT LISTS
8. GLOBAL JUMPS
9. DATE/TIME FUNCTIONS
10. UNISTD, STAT AND FCNTL
    10.1 FILE HANDLING
    10.2 INPUT/OUTPUT FUNCTIONS
    10.3 PROCESS CONTROL
    10.4 CREATE CHILD PROCESSES
11. MISCELLANEOUS FUNCTIONS
    11.1 MALLOC
    11.2 SEARCHING AND SORTING
12. TOS
    12.1 TIMER
    12.2 PROCESS CONTROL
13. DEVICE I/O
-----------------

1. HEADER FILES

The first two files are included by stdlib.h and stdio.h. Thy contain
basic typedefs and macros.

stddef.h
    This is the root header file which should be included in all
    programs.  It defines FALSE, TRUE, NULL, size_t, ptrdiff_t and the
    offsetof() macro.
    The expected version number of the XDLIBS library is defined in
    macro _XDLIBS. To test write a program containing something like:
        assert( _xdlibs < _XDLIBS)

types.h
    This file contains typedefs for many special and/or non-standard
    type names.  Many of the typedefs in this file define type names
    which are ANSI and/or System V standard.  This file is included
    by several other header files, and includes <stddef.h>.

The next ones are standard header files, to find in every standard C-system.

stdlib.h
    This file is defines the dynamic memory managment functions,
    malloc(), et. al., string to number functions, environment access
    and basic process control functions. It should be present in every
    source code you write. It includes types.h.

stdio.h
    This header file should be present in nearly all C programs.
    It contains defines the FILE struct, EOF and contains extern
    declarations for standard i/o and other commonly used functions.
    For convenience, the constants TRUE, FALSE and ERROR are also
    defined in this file, although this is somewhat non-standard.

string.h
    This file defines aliases for string function names (since some
    string functions have various names on different systems) and
    extern declarations for all string functions.
    The number to string functions are there to find, too.

ctype.h
    The isxxxx() macros and toxxxx() macros are define in this file.

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

limits.h
    Various maximum and minimum values are defined by this file.
    Among these are PATHSIZE and MAXINT.

time.h
    This file defines time related constants and structures, and
    extern declarations for the time functions.

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

stdarg.h
    This header defines the type and macros needed for variable
    argument list processing.

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

Now follow some non standard header files. They are provided for
compatibility and easy ports.

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

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

fcntl.h
    This file defines the O_xxxx constants used by open().

stat.h
    The struct stat and the file mode flag constants are defined
    in this file.

Some extensions to standard libraries and direct TOS access is to find
in next files:

malloc.h
    Some functions dealing with memory block of malloc(), alloca()
    for allocating memory from stack, ... .

atari.h
    For direct TOS access include this file. It will include the
    following ones and errno.h. Some OS structures are declarated here.

osbind.h
    Mnemonics for bios(), xbios() and gemdos() calls are defined
    in this file.

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

osheader.h
    The TOS header struct is in here.


2. STDLIB

The standard library. Include stdlib.h for access to these functions.

int _xdlibs;
    This is the version number of your library 'xdlibs.a'.
    Highbyte is version, lowbyte is revision.

2.1 PROCESS CONTROL:

global variables: generally no write access at runtime!
some are from startup codes, others are to find in the libraries
ATARI specific:
int _app
    is TRUE if its an application, and FALSE for accessories

int _mint
    If it is 0 MiNT is not running. If -1 you will have to test this,
    any other value is the active's MiNT version number.
    Using a '*_s' startup code will always include a MiNT test, it is
    done in _main() function.
    With other startup codes either test with 'void GetMiNT()'
        if (__mint == -1)
            GetMiNT();
    or like this
        if (__mint == -1) {
            long    val;
            if (Getcookie('MiNT', &val))
                __mint = (int)val;
            else
                __mint = 0;
        }
    Now you can use the flag.
    if (__mint) {
    }
    void GetMiNT() is a dummy function with the standard stdio startup
    codes ('*_s.o'), and never called, in the above example.

BASEPAGE *_base
    pointer to process' basepage

char *_envp
    pointer to begin of current environment; it may be changed by
    putenv()

int errno
    holds the error number of last error occured in a library function
    (from stdlib.h, stdio.h unidstd.h)

char *etext;
char *edata;
char *end;
    These variables point to the first byte beyond the end of the
    text, data and BSS segments respectively.  They are provided
    for compatibility.

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 will need a larger stack put it in your source; if not,
    forget about it.

int main(int argc, char *argv[])
or:
int main(int argc, char *argv[], char *envp)
    This function is not actually in the standard libraries, but
    must be present somewhere in the user's code.  The parameters
    passed to it by _main() are the number of arguments in the
    command line, a pointer to a list of pointers to arguments, and
    a pointer to the initial environment string.  The return value
    from main() is passed, by _main(), to exit().  Therefore, you
    should always return() from main(). You may call exit() directly
    in any function, too.
    A return value of 0 means okay, a positiv value up to 127 means
    something happened. Negative values are reserved for OS errors
    and signals.

void exit(int status)
    Normal program termination. Calls all atexit functions (first
    the last stored), flushes and closes all open streams.
    Returns <status> value to the operating system.
    A return value of 0 means okay, a positiv value up to 127 means
    something happened. Negative values are reserved for OS errors
    and signals.

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

int atexit( void (*fnc)() )
    Stores fnc() so that this function is called by exit or if
    main() returns. If it returns not 0 the function couldn't be
    stored (there is space for 32 function pointers reserved).

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

int putenv(char *entry)
    Add <entry> to the environment.  <entry> can be any of the following
    forms:
        <VARIABLE>
        <VARIABLE>=
        <VARIABLE>=<value>
    The first form removes <VARIABLE> from the environment.  getenv()
    will return NULL if looking for this variable.  The second form adds
    <VARIABLE> to the environment, with a null value.  getenv() will
    return a pointer to a '\0' character if looking for this variable.
    Many environment handlers don't support such "tag variables", so
    their use is not recommended.  The final form is the most common.
    <VARIABLE> is installed (or replaced) with the value <value>.
    It should be noted that the putenv() function itself
    is not supported in many systems and therefore may not be portable.
    This function uses malloc() if there is not enough space in the
    last allocated environment block.
    It returns TRUE for success or FALSE for failure. Failure maybe
    ENSMEM or you tried to remove a nonexisting variable.

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
    couldn't be executed.  In this case you can try to execute the
    commandline directly, e.g.  using spawn...() 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, even
    more?  I think the better solution is using a fulll featured shell
    via system().

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


2.2 MEMORY MANAGEMENT:

long _BLKSIZ = 65536;
    This variable controls the granularity of system memory allocation
    used by malloc(), et. al.  This is the amount of memory that is
    requested from the system each time a new "heap" is needed to fill
    dynamic memory requests.  To help avoid a GEMDOS bug, only 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 change next time.)
    Note that _BLKSIZ should not be too small (8K is the minimum
    if Memory Protection with the 030's PMMU is active under MiNT),
    to avoid too many blocks, and not too large, cause this process
    will waste memory, which is not available for other processes.

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.

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 is there is not enough free memory.

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.

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

void *lrealloc(char *addr, long size)
    The same as realloc(), but the block size argument is a long value.

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.

2.3 TYPE CONVERSION:

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.  Return value is undefined in an
    overflow situation.

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.  Return value is undefined in an
    overflow situation.

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>.
    Return value is undefined in an overflow situation.

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.  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>.  Return value is undefined
    in an overflow situation.

2.4 MISCELLANEOUS FUNCTIONS:

int rand()
    Return a pseudo random number in the range 0..32767.  This
    function uses the system random number generator, but grabs
    it's 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 aren't
    sufficient or for porting these routines to another machine.

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

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

MACRO labs(x)
    see abs();

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

void qsort(char *base, int num, int size, int (*cmp)())
    Perform a recursive quick-sort on an array starting at <base>
    containing <num> elements of <size> bytes each.  The function
    pointed to by <cmp> is used to compare elements.  Pointers to
    two items in the array are passed to the function, which must
    return a number representing their relationship as follows:
        negative    item1 < item2
        0        item1 == item2
        positive    item1 > item2
    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.


Almost standard is this function, still not tested - jerry -.
declarated in unistd.h

int getopt(int argc, char **argv, char *optstring)
    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
    indicated 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.

2.5 STANDARD INTERNALS
Here follows the documentation of some internal xdlibs functions. You
shouldn't use them at all in you programs!! They are called and linked
automatically.

void _initargs(char *cmdline, int cmdlen)
    Process the command arguments, either parsing the command line
    or retrieving the ARGV environment strings.
    It understands the new ARGV scheme of ATARI including empty
    arguments and quoted arguments.
    Never call this function. It manipulates heap/stack area.
    This function is called from the startup module very early on.
    Values to be passed to the user's 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 doesn't use arguments, use the 'min_s.o' startup code.
    to make the program smaller.

int _main()
    This function defines the standard streams, check to see which
    of them are devices, and calls the user's main() function.  It sets
    up some other values, like _mint flag and _starttime (for clock()).
    The startup module calls this function to start the C program.  The
    following standard streams are initialized by _main():
        stdin        Standard input, may be redirected
        stdout        Standard output, may be redirected
        stderr        Usually the system console's device
                (environment STDERR is checked, so it
                maybe file handle 2)
    Atari special:
        stdprn        The standard printer (output only)
                (device file prn:)
        stdaux        The communication port (input/output)
                (device file aux:)
    The global variables "_argc", "_argv" and "_envp" are used to
    store the values to be passed to the user's main().  If main()
    returns, exit() is called, with the return value as status.  If a
    program doesn't use ANY standard I/O, you can use an other startup
    code, which doesn't call _main() function. But you won't get
    arguments, if you do so! If you want to get arguments passed, use
    the _main() function from 'minimum.h'. If you don't need argv[0]
    and expect only less arguments you can use the getcmdln() function
    from minimum.h.

void _exit(int status)
    Exits the program immediately, returning <status> to the OS.

3. STDIO

Standard input/ouput library. Include stdio.h to use this functions.
Portability is guranteed for this functions.
We try to keep them as closest to standard  as possible.

There are two flags to control the in and output functions, aside of
opening mode of single streams.

short  __FRW_BIN__ = 0;
    When non-zero, i/o functions will not do CR processing
    even for text mode files (ie: ignore file mode) at all.

short  __FWRT_BIN__ = 0;
    When non-zero, fwrite will not do CR processing
    even for text mode files, but fread will do if __FRW_BIN__
    is zero and the file is opened in text-mode.
    You can write files with lines ending only with '\n',
    but read those with '\r''\n' translated to '\n', too.


3.1 FILE to STREAM OPERATIONS

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
    and indicates that <nl> is translated to <cr><lf> on output and
    vica-versa on input.  If the stream is a character device, the
    translation is slightly different.  The output translation is the
    same, but on input <cr> and <lf> both become <nl> in all cases.
    The "b", for binary mode, overides "t" and indicated that characters
    are not translated during i/o operations.  "a" represents append
    mode and means that the file pointer will initially be placed at
    the end of the file.  "w" mode will create a file if it doesn't
    exists, or zero an existing file.  If "r" is the only mode specified,
    the file must already exist.  A (FILE *) is returned if the open
    succeeds, or NULL if it fails.

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

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,
    or the program terminates through exit(). Call this function
    before switching between reading and writing on a stream which
    is opened for both.

int fclose(FILE *fp)
    Close the stream <fp>, flushing the buffer.  Returns 0 on success.

int remove(char *filename)
    Delete <filename>, if it exists.  Return 0 for success, or a
    negative error code.

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.  Return 0 for success, or a
    negative error code.

FILE *tmpfile()
    sorry - missing function available soon.

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.

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 gets used, if <size> is
    NULL, too, <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 speeds up output)

void setbuf(FILE *fp, char *buf)
    If <buf> is NULL, make <fp> unbuffered; else <buf> points to a buffer
    of BUFSIZ characters to be used as the stream buffer for <fp>.
    Full buffering is performed on this stream (_IOFBF) now.


3.2 PROCESS COMMUNICATION

Not provided as standard but it is some kind of standard on multitasking
systems. So I will implement this soon (MiNT).

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

int pclose(FILE *fp)
    still missing



3.3 FORMATTED I/O


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.

int printf(char *fmt[, arg1, ..., argN])
    Formatted output to the stdout stream.  See the _printf() function
    for a description of the <fmt> formatting string.

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.

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.

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.

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.

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.

int scanf(char *fmt[, arg1, ..., argN])
    Formatted input from the stdin stream.  See the _scanf() function
    for a description of the <fmt> formatting string.

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.

3.4 FORMATTING I/O:

These functions are internal to XDLIBS. They document the formatting
strings.

int _printf(char *op, int (*put)(), char *fmt, int *args)
    This function does all the work for printf(), et al.  Many systems
    don't provide direct access to this function (or it's 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.  Calls to <put> are of the form:
    "(*put)(c, op);" where <c> is the character to output.  The format
    string is composed of characters and format specifications.  The
    '%' character introduces a format specifier.  The general form of
    a format specifier is:
      %[-][ |+][0][<width>|*][.[<precision>|*]][l]{d|i|u|o|x|p|b|c|s}
    The '-' specifies left justification.  The ' ' or '+' specifies
    the character which preceeds positive numeric values.  The '0'
    specifies that numeric fields will be padded with '0' rather than
    ' '.  The <width> field is a numeric value specifying a minimum
    field width.  The <precision> field is a numeric value specifying
    the maximum number of data characters to display.  If '*' is
    specified for the width or the precision, an "int" value is taken
    from the argument list and used for that value.  If no width is
    specified, the field width varies according to the data width.  If
    no precision is specified, all data characters are included in the
    data width.  If the data width exceeds the field width, the field
    width will expand to allow all data characters to be printed.
    Including the 'l' or capitalizing the trailing character specifies
    that the associated value is a "long" type.  The trailing character
    specifies the format type, as follows:
        d    Signed decimal integer
        i    same as 'd'
        u    Unsigned decimal integer
        o    Unsigned octal integer
        x    Unsigned hexadecimal integer
        b    Unsigned binary integer
        p    Pointer (displayed in %06.8lX format)
        c    Character
        s    String
    If the character following the '%' is not recognized, it is
    simply passed along to the output stream, thus "%%" is used to
    print a single '%' character.

int _scanf(char *ip, int (*get)(), int (*unget)(), char *fmt, char **args)
    This function does all the work for scanf(), et al.  Many systems
    don't 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}
    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.  The trailing character
    specifies the format type, as follows:
        d Signed decimal integer
        u Unsigned decimal integer
        o Unsigned octal integer
        x Unsigned hexadecimal integer
        b Unsigned binary integer
        i Unsigned decimal/octal/hexadecimal/binary integer
        c Character
        s String
    If a <width> is specified with the 'c' format, exactly <width>
    characters (including whitespace) are read from the input stream,
    and written to a string.  No '\0' character is added If the
    character following the '%' is not recognized, it is expected to
    match the input stream as a non-format character, thus "%%" is
    used to match a single '%' character.
    One additional conversion is the brace-format.  Shown as "%[...]",
    the '...' represent a list of characters.  If the first character
    in the list is a '^', the field contains any characters -not- in
    the list (starting with the 1st character after the '^').  If the
    first character of the list is not a '^', then the field will
    only contain those characters found in the list.  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.


3.5 STREAM I/O

3.5.1 CHARACTER INPUT

int fgetc(FILE *fp)
    Get a character from <fp>.  Returns the character or EOF.
    The function _tttty() is called if <fp> is a device.

char *fgets(char *data, int limit, FILE *fp)
    Get data from <fp> and puts it in the <data> buffer.  At most,
    <limit>-1 characters will be read.  Input will also be terminated
    when a newline is read.  <data> will be '\0' terminated and the
    newline, if read, will be included.  A pointer to the start of
    <data> is returned, or NULL for EOF.
    The function _tttty() is called if <fp> is a device.

int getc(FILE *fp)
    Same as fgetc() but implemented as a macro.

int getchar()
    Same as "fgetc(stdin)".

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

3.5.1 CHARACTER OUTPUT

int fputc(char c, FILE *fp)
    Put the character <c> to the stream <fp>.

void fputs(char *data, FILE *fp)
    Write the characters in <data> to the stream <fp>.  A newline
    is added if there is no one at end of string.

int putc(char c, FILE *fp)
    Same as fputc() but implemented as a macro.

int putchar(char c)
    Same as "fputc(c, stdin)".

void puts(char *data)
    Write the characters in <data> to stdout.  A newline WILL be
    written after the data.

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.

int ungetc(char c, FILE *fp)
    Same as fungetc() but implemented as a macro.

3.5.2 I/O of non char OBJECTS

int fread(char *data, int size, int count, FILE *fp)
    Read <count> items of <size> characters each from stream <fp>.
    Data is stored in the buffer pointed to by <data>.  The number of
    full items actually read is returned, or a negative error code.

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.

int _tttty(FILE *fp)
    "Teeny Tiny TTY" driver function.  This function is internal to
    XdLibs, but it's 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 (similar to
    _fillbuf() in some systems). If the stream is in binary mode, a full
    buffer is to be read, with no translation.
    It outputs every char collected in the buffer to stdout.
    It is never used when Mint is active any more, cause Mint has a
    working tty driver.  It emulates a default tty as far as possible,
    so the following characters will cause some action:
        ^U,^@    kill line
        ^V    quote next char
        ^D    end of file
        ^C    break (kill process)
        ^H, ^?    erase last character
        ^W    erase last word
        ^J, ^M    newline
    non std:
        ^[    send to stdout but don't keep this in buffer,
            nor the next character


3.6 POSITIONING in STREAMS

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.
    fsetpos() should be used in new code.  (cf: fsetpos)

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.  fsetpos() should be used in
    new code.  (cf: fsetpos)

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.

int fgetpos(FILE *fp, fpos_t *pos)
    Get the position of the stream <fp> and store it at the location
    pointed to be <pos>.  This is the new X3J11 function to replace
    ftell().  Returns 0 for success and ERROR for failure.

int fsetpos(FILE *fp, fpos_t *pos)
    Set the position of the stream <fp> to the valued stored at the
    location pointed to be <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().  Returns 0 for success and ERROR for
    failure.


3.7 I/O ERROR HANDLING

void clearerr(FILE *fp)
    Clear the error flag on <fp>.

int feof(FILE *fp)
    Return non-zero if <fp>    is at end of file.

int ferror(FILE *fp)
    Return non-zero if and error has occurred on <fp>.

void perror(char *msg)
    Write, to stream stderr, <msg> (if non-null and non-empty),
    followed by ": " and a system error messaged derived from the
    value of errno.


3.8 UTILITY functions dealing with PATHS and FILES.
Not guaranteed but almost standard. I didn't test them explicitly,
until now. -jerry-

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.

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


char *findfile(char *afn[, *ext])
    Return full file spec for <afn> if found. If <afn> has no extension,
    extensions from <ext> are tried until a match is found, or the list
    ends.  <ext> is a list of extensions separated by '\0' characters
    and ending with an additional '\0', ie. ".ttp\0.tos\0.prg\0" (note
    that the final null is added by the compiler to any string constant.
    If <afn> already has an extension, <ext> is not used.  If no matching
    files are found, NULL is returned.  The pointer returned when a match
    is found points to a buffer which is internal to fullpath().  If you
    want to save the value returned, you must make a copy before the
    buffer is overwritten by subsequent calls.  Note: several dLibs
    functions call filefind(), so don't make too many assumptions about
    how long the internal buffer is going to stay valid.

char *pfindfile(char *path, *afn[, *ext])
    Like findfile() but search all directories (separated by ',' or ';')
    in <path>.  If <path> is NULL, the "PATH" environment variable is
    used instead.  If <afn> specifies a drive or directory, <path> is
    not used.  The internal buffer for findfile() is used by pfindfile().


The fowllowing ones are non standard. Taken from Dlibs without test and
changes.

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.

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, (ie.: "").
    The <drive> component will be a drive letter followed by a colon,
    (ie.: "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", ie.:
    "\this\is\a\path\name".  The <file> component is the base filename
    without any extension, ie.: "filename".  The <ext> component is
    the file extention with no leading '.', ie.: "txt".  Recommended
    sizes for the components is Drive[4], Path[128], File[10], Ext[4].

char *_makepath(char *dst, *drive, *path, *file, *ext)
    Build the <dst> filename from component parts. Returns <dst>.
    This function is basically in 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 '\'.


3.9 EXTENSIONS AND INTERNALS

The following functions are non standard but usefull sometimes.
Some are more internal dLib's functions.


int fileno(FILE *fp)
    Return the file handle associated with the stream <fp>.


int ungetchar(char c)
    Same as "fungetc(c, stdin)".  Note that this name will conflict
    with any function beginning "ungetch..." due to having only 7
    significant characters in external identifiers.

int getw(FILE *fp)
    Get a 2-byte value from the stream <fp>.  The high-order byte is
    read first.  Use feof() to test for end-of-file.

int putw(int n, FILE *fp)
    Put the 2-byte value <n> to the stream <fp>.  The high-order byte
    is written first.

int getl(FILE *fp)
    Get a 4-byte value from the stream <fp>.  The high-order byte is
    read first.  Use feof() to test for end-of-file.

int putl(long n, FILE *fp)
    Put the 4-byte value <n> to the stream <fp>.  The high-order byte
    is written first.

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

?????????????????????????????
FILE *fopenp(char *filename, char *mode)
    Find <filename> somewhere on the PATH and open it with <mode>.
    Refer to the fopen() function for valid <mode> values.  If you
    want to use a search path other than the PATH environment
    variable, use the pfindfile() function to locate the file, and
    pass that filename to fopen().  (cf: pfindfile, fopen)


4. CHARACTER TYPE FUNCTIONS:

Standard character type functions. Include ctype.h to use them.
The macros use a table from the xdlibs.a library


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

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

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

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.

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.

MACRO toascii(int c)
    Convert <c> to 7-bit ascii, putting it into the range 0x00..0x7F.

MACRO isalnum(int c)
    Return non-zero if <c> is '0'..'9','A'..'Z','a'..'z'.

MACRO isalpha(int c)
    Return non-zero if <c> is 'A'..'Z','a'..'z'.

MACRO isascii(int c)
    Return non-zero if <c> is 0x00..0x7F.

MACRO iscntrl(int c)
    Return non-zero if <c> is 0x00..0x1F,0x7F.

MACRO isdigit(int c)
    Return non-zero if <c> is '0'..'9'.

MACRO isgraph(int c)
    Return non-zero if <c> is 0x21..0x7E.

MACRO islower(int c)
    Return non-zero if <c> is 'a'..'z'.

MACRO isprint(int c)
    Return non-zero if <c> is 0x20..0x7E.

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

MACRO isspace(int c)
    Return non-zero if <c> is 0x09..0x0D,0x20.

MACRO isupper(int c)
    Return non-zero if <c> is 'A'..'Z'.

MACRO isxdigit(int c)
    Return non-zero if <c> is '0'..'9','A'..'F','a'..'f'.

5.STRING FUNCTIONS:

String related functions. Some conversion functions are put in here too.
Include string.h for using them.

STRING MANIPULATION:

int strlen(char *string)
    Returns the number of characters in a string, not including the
    terminating '\0'.

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.

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

char *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.

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

char *strset(char *string, char c)
    Fill <string> with <c> up the the terminating '\0' of <string>.

char *strnset(char *string, char c, int n)
    Fill at most <n> characters of <string> with <c>, up the the
    terminating '\0' of <string>.

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.

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.

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.

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

char *strupr(char *string)
    Convert all alphabetic characters in <string> to upper case.

char *strlwr(char *string)
    Convert all alphabetic characters in <string> to lower case.

char *strrev(char *string)
    Reverse the order of the characters in <string> in place.

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

int strncmp(char *str1, char *str2, int limit)
    Compare strings as with strcmp(), but limit comparison to the
    <limit> characters.

int stricmp(char *str1, char *str2)
    Compare strings as with strcmp(), but ignore the case of any
    alphabetic characters.

int strnicmp(char *str1, char *str2, int limit)
    Compare strings as with strncmp(), but ignore the case of any
    alphabetic characters.

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.

char *stristr(char *string, char *pattern)
    Same as strstr(), but ignore the case of any alphabetic characters.

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.

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.

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.

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.

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.

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.

char *strpbrk(char *string, char *set)
    Return a pointer to the first occurance in <string> of any
    character in <set>.

char *strrpbrk(char *string, char *set)
    Return a pointer to the last occurance in <string> of any
    character in <set>.

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.  Note
    that this function modifies <string> (by inserting '\0's) in
    the process.  Subsequent calls to strtok() may specify NULL as
    the <string> argument, in which case subsequent tokens are
    returned, or NULL if there are no more tokens.

char *strtrim(char *string, char *junk)
    Remove leading and trailing characters found in <junk>
    from <string>.  Return a pointer to the modified <string>.

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.

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.

int strirpl(char *string, char *ptrn, char *rpl, int n)
    Same as strrpl() except ignore the case of alphabetic characters.

char *memmove(char *dest, char *source, int len)
    Copies the <source> block to the <dest>.  <len> bytes are
    always copied.  No terminator is added to <dest>.  A pointer
    to <dest> is returned.  Overlap checking IS done.

char *lmemmove(char *dest, char *source, long len)
    Same as memmove() except a long value is used for <len>.

char *memcpy(char *dest, char *source, int len)
    Copies the <source> block to the <dest>.  <len> bytes are
    always copied.  No terminator is added to <dest>.  A pointer
    to <dest> is returned.  Overlap checking IS NOT done.

char *lmemcpy(char *dest, char *source, long len)
    Same as memcpy() except a long value is used for <len>.

char *memset(char *dest, char data, int len)
        Set <len> bytes of <dest> to <data>.  A pointer to <dest>
    is returned.

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

int memicmp(char *blk1, char *blk2, int len)
    Compare blocks as with memcmp(), but ignore the case of any
    alphabetic characters.

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.

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

char *bzero(char *buf, int cnt)
    Zero <cnt> characters in <buf>.  Returns <buf>.


FORMATTING /TYPE CONVERSION

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.

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.

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.

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 (value 0)
        \b        backspace
        \t        horizontal tab
        \v        vertical tab
        \f        form feed
        \a        alarm (bell)
        \\        backslash
        \'        single quote
        \"        double quote
        \NNN        octal constant
        \xNN        hexadecimal constant
        \<nl>        "folded" line (both characters removed)
    A pointer to the modified <string> is returned.


6. ASSERT AND ERRORHANDLING

error handling:
To use the assert macro include assert.h.

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.

long    teststack()
    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.
    (extended.lib)


ERROR HANDLING FUNCTIONS:

extern int errno;
    This variable is set to zero when the program is loaded.  It is
    not zeroed by any library functions, but may be set to a non-zero
    error number by many of them (particularly the standard i/o 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 as described below.  (cf: seterror)

void perror(char *msg)
    Write, to stderr, <msg> (if non-null and non-empty), followed by
    ": " and a system error messaged derived from the value of errno.
(from stdio.h)

char *strerror(errnum)
    Return the system error message for error <errnum>.  If <errnum>
    is outside the range of valid error numbers, NULL is returned.
(from string.h)

non standard function:

void perrorf(char *fmt[, arg1, ..., argN])
    Write, to stderr, the name of the program, 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().  (cf: printf, perror)
(from misc.h)


7. VARIABLE ARGUMENT LISTS:
The macros in this section are defined in the <stdarg.h> header file.

typedef    ... va_list;
    This is the type for a variable argument list traversal variable.

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.

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

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


8. GLOBAL JUMPS:

Some more process control. Include setjmp.h for using this functions.

int setjmp(jmp_buf context)
    Save <context> for longjmp(). You MUST include <setjmp.h> to use.
    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 setjmp().

void longjmp(jmp_buf context, int rv)
    Return <rv> to the <context> saved by setjmp(). (cf: setjmp)
    You MUST include <setjmp.h> to use.


The following two are non-standard.

int catch(jmp_buf context, int (*func)())
    Execute <func> with <context> saved for throw().  You MUST include
    <setjmp.h> to use.  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.  (cf: setjmp/longjmp)

void throw(jump_buf context, int rv)
    Return <rv> to <context> saved by catch().  You MUST include
    <setjmp.h> to use.




9. DATE/TIME FUNCTIONS:
To use the functions in this section, you must include <time.h>
in your source file.

TYPE time_t, defined in types.h is used for rawtime values.  These are NOT
seconds since 1970, but a encoded time value with DATE in highword and TIME
in lowword (for time comparisons) cause on ATARI TOS machines one can't be
shure to find a TIMEZONE environment variable to do a propper encoding.

   All time functions, including stat and fstat use this local time time_t
   format. No function makes any changes to the values, just the encoding
   is changed!
   Soon gmtime(), unixtime() and tostime() will be implemented, these
   functions will try to calculate the asked values if a
   TIMEZONE environment variable (TZ=...) is available on runtime.

   To get a current local time string do this:
 * time_t now;
 * char    time_string[26];
 * time (&now);
 * strcpy(time_string, ctime(&now));
   Think of the newline in time_string[25]!

   The stat structure contains a time_t value, too. To print a file's date
   after calling stat with mystat_buffer write:
 * 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 this by:
 * 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 (e.g
   for setting a file's time stamp with utime())
 * struct tm mytime;
 * // fill in the values
 * time_t thistime;
 * thistime = mktime(&mytime);

   If you want to get a tm structure filled with values according to a
   time_t value use localtime() function.
 * time_t thistime;
 * struct tm *time_struct;
 * // get a value in thistime
 * time_struct = localtime(&thistime);

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

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 2 seconds is possible.  A pointer
    to the formatted string, which is held in an internal buffer, is
    returned.

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.

struct tm *gmtime(time_t *rawtime)
    Since there is not concept of "time zone" on the ST, this function
    returns NULL, as specified by the proposed ANSI standard.
    (will work soon)

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.

time_t mktime(struct tm *time)
    Convert <time> structure value to raw time format.

int utime(char *pathname, long *rawtime)
    Set the modification date of <pathname> to <rawtime>.  Returns zero
    for success, or a negative error code.

clock_t clock()
    Returns the elapsed time since progstart.  The value divded by
    CLK_TCK, will give you elapsed seconds.
    This works only with an '*_s.o' startup code, cause setting
    _starttime is done in _main().


10. UNISTD, STAT AND FCNTL

Standard OS calls library functions. Using this calls your code will be
still portable in most cases.
Include the files in brackets at aeach function, if you make use of one of
these functions. Some functions return with ERROR if there was one, and
should set errno, but some still don't do this.

10.1 FILE HANDLING:

int access(char *name, int amode)
    Returns 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 and written
    (unistd.h)

int chdir(char *pathname)
    Changes the current working directory to <pathname>.  If a
    device is specified in <pathname>, the current drive is
    changed too. Returns 0 for success, or ERROR if there was an
    error.
    (unistd.h)

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

int chown()
    still missing
    (unistd.h)

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

int creat(char *filename, int pmode)
    Create a new file with the given <filename>.  If a file with
    the name already exists, it will be truncated to zero bytes.
    <pmode> specifies the attributes, initially given to the file.
    If 0 `0644' is assumed other valid <pmode> values are:
        S_IREAD    readable
        S_IWRITE    writeable
        S_IEXEC    executeable
    If Mint is active the following values make sense:
        S_IRUSR/S_IRGRP/S_IROTH    read
        S_IWUSR/S_IWGRP/S_IWOTH    write
        S_IXOTH/S_IXGRP/S_IXUSR    execute
    Not all filesystems support these bits, so maybe some are ignored.
    (fcntl.h, stat.h)

int dup(int handle)
    Return a second file handle which refers to the same file as
    the given <handle>. (cf: dup2)
    (unistd.h)

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

long fsize(char *name)
    Return the size of the file <name> in bytes.  Note that this
    is a long value.  Return -1L if the file is not found.
    NON PORTABLE
    (unistd.h.h)

char *getcwd(char *buffer, int size)
    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.
    (unistd.h.h)

int isatty(int handle)
    Return non-zero if <handle> refers to a character device.
    Negative handles always refer to character devices.
    (unistd.h.h)

int link()
    still missing

long lseek(int h, long offset, int origin)
    Move file pointer for file <h> to specified location.  <origin>
    specifies the starting point for the <offset> distance.  Valid
    <origin> values are:
        SEEK_SET    from beginning of file    (0)
        SEEK_CUR    from current location    (1)
        SEEK_END    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.
    (unistd.h.h)

int mkdir(char *pathname)
    Creates a new directory called <pathname>.  A drive letter may
    be specified.  Returns 0 for success, or a negative error code.
    THIS FUNCTION MAYBE NOT PORTABLE.
    (stat.h)

int open(char *filename, int iomode[, pmode])
    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_APPEND    start file pointer at end of file
        O_TRUNC        if file exists, truncate to 0 length
        O_CREAT        creat() file if none exists (uses <pmode>!!)
        O_EXCL        return EEXIST if file exists and
                O_CREAT is specified (exclusive mode).
    Note: It is possible to open the character devices "con:", "aux:",
    and "prn:" with this call, and negative handles (-1..-3) will be
    returned.  Error returns are always < -3.  The <fcntl.h> file
    contains iomode constants.  For pmode constants see creat().
    (fcntl.h)

int pipe()
    still missing

int rmdir(char *pathname)
    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.
    (unistd.h)

int stat(char *name, struct stat *statbuf)
    Search for file <name> and load <statbuf> with information
    about that file, if it is found.  Return 0 if found, or
    ERROR (-1) if no file/directory matched <name>.  Volume
    labels are not included in the search.  The file <stat.h>
    must be included if you use this functions, since it defines
    struct stat you have to allocate first.
    (stat.h)

long tell(int h)
    Return the current file position for the file <h>.
    (unistd.h)

int unlink(char *filename)
    Delete <filename>, if it exists.  Return 0 for success, or a
    negative error code.
    Of course it should really do unlink() if MiNT is present, it
    doesn't yet.
    (unistd.h)

sync()
    Provided for compatibility.  #define'ed as a comment.


10.2 INPUT/OUTPUT FUNCTIONS:

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

long lread(int h, char *data, long length)
    Same as read(), but uses a long value for number of bytes to read.
    (unistd.h)

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

long lwrite(int h, char *data, long length)
    Same as write(), but uses a long value for number of bytes to write.
    (unistd.h)

10.3 PROCESS CONTROL:

int alarm()
    still missing

int brk(void *address)
    Set the "break" to <address>.  Return 0 for success.  If <address>
    is not a valid break value, return -1 and don't move the break.
    HANDS OFF, this shrinks stacksize, and won't work with
    accessories or programs using the accapp_s.o startup code.
    (malloc.h)

int getpid()
    Return an integer value unique for this process.
    (fake function, will be fixed soon)

int getuid()
int getgid()
int geteuid()
int getegid()
    non existing

void exit()
void _exit()
    see chapter to stdlib.h

int kill()
    will be implemented soon

int nice()
    still missing

int pause()
    will be implemented soon

char *sbrk(int amount)
    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 malloc() doesn't 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.  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 shrinks stacksize, and won't work with
    accessories or programs using the accapp_s.o startup code.
    (malloc.h)

int setuid()
int setgid()
    still missing

int (* signal(int sig, int (*func)()));
    will be implemented soon

unsigned int sleep(unsigned int seconds)
    Suspend process for seconds.

    This is implemented as a start_timer()/time_since() tight loop
    waiting for the specified amount of time to pass.
    If MiNT is present this is done by a alarm signal.
    include <time.h>
    (unistd.h)

int stime(time_t *rawtime)
    Set the system clock to <rawtime>. See time.h.
    (unistd.h)

time_t time(time_t *rawtime)
    Get the current system clock date/time value.
    include <time.h>, see chapter Date/time functions

void usleep(unsigned long usec)
    was: void usleep(int dt) !!!!!!!!!!!!!!!
    Suspend operation for usec microseconds.  Works like sleep().
    Only milliseconds are taken into account!
    If MiNT is present it calls sleep() to get usec small enough for
    Fselect() calls.     include <time.h>
    (unistd.h)


10.4 CREATE CHILD PROCESSES:

include <unistd.h> for access to this functions

int exec...
int fork()
    missing, will be implemented, for MiNT can handle this

Since it is not possible to do a true Unix-style fork() without MiNT,
the functionality of the fork()/exec() pair is provided by these
following fork...() functions.  They are to find in 'extended.lib',
not in 'xdlibs.a' itself.
A program is executed, it's return-value is returnded by this fork..()
functions. With the pseudo wait() function you will get status and
return value. errno is set if an error occurs, it is set to 0 if no
error ocurred.

Note that by convention <arg0> should be the name of the program that
is being called, if it is empty the function will do this for you.

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

int forkl(char *program[, char *arg0, char *arg1, ..., char *argN], NULL)

int forkv(char *program, char **argv)
    Like forkl() 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.

int forklp(char *program[, char *arg0, char *arg1, ..., char *argN], NULL)
    Use the environment variable "PATH" to find <program>.
    And if no extension, try the default ones. (cf: forkl)

int forkvp(char *program, char **argv)
    Like forklp() except <argv> points to a NULL terminated list of
    pointers to arguments.

int forkle(char *program[, char *arg0, char *arg1, ..., char *argN],
                NULL, char *env0, ... char *envn, NULL)
    Pass the environment strings <env0> etc to the child process.
    (cf: forkl)

int forklpe(char *program[, char *arg0, char *arg1, ..., char *argN],
                 NULL, char *env0, ... char *envn, NULL)
    Use the environment variable "PATH" to find <program> and
    pass the environment strings <env0> etc. to the child process.

int forkve(char *program, char **argv, char **envp)
    Pass the environment strings from <envp> (<envp> points to a NULL
    terminated list of pointers to env strings)
    to the child process. (cf: forkv)

int forkvpe(char *program, char **argv, char **envp)
    Use the environment variable "PATH" to find <program> and
    pass the environment strings from <envp> to the child
    process. (cf: forkve)

int forkvep(char *program, char **argv, char *envp)
    Pass the environment <envp> to the child process. (cf: forkv)
    (provided for compatibility with elder versions, though the
    functions name changed!!)

int forkvpep(char *program, char **argv, char *envp)
    Use the environment variable "PATH" to find <program> and
    pass the environment <envp> to the child process. (cf: forkv)
    (provided for compatibility with elder versions, though the
    functions name changed!!)

int wait(int *rvp)
    fake function
    Wait for a child process to terminate.  Return -1 if there are
    no children.  Normal return is the process id number of the
    terminated child.  <rvp> is an pointer to the place to store
    the return value and exit status.  The high byte of the word
    pointed to be <rvp> will contain the value returned from the
    child through exit().  The low byte will contain 0 if the process
    terminated normally, or an error code if abnormally:
    If it is -1 the return value is a GEMDOS error from Pexec,
    that means no process was created; if it is 1, the process returned
    with an error (mostly ENSMEM).
    If it is (& 0x80) the child was killed by signal/exception.
    If you mask off 0x80 you will get the signal number. This time you
    will only find SIGINT (terminated by ^C) or SIGBUS (for an exception)
    (unistd.h)


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

Mabe be this function will not work in current library version, problems
will be fixed soon.



11. MISCELLANEOUS FUNCTIONS:
They are to find on almost systems.

11.1 MALLOC:
include malloc.h for access to this functions.

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

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

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.


11.2 SEARCHING AND SORTING:
include  misc.h   for access to this functions.

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

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.

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

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.

void *lfind(char *key, char *base, int *num, int size, int (*cmp)())
    Like lsearch(), but do not add elements which are not found.
    Note that <num> is a POINTER, even though it is not modified.



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.  Don't
    blame me... this is how Microsoft specifies it.

MACRO max(x,y)
    Return the larger of <x> and <y>.  This macro evaluates the
    larger argument twice and the smaller argument once.

MACRO min(x,y)
    Return the smaller of <x> and <y>.  This macro evaluates the
    smaller argument twice and the larger argument once.

MACRO swap(a,b)
    Exchange <a> and <b> by chained XORs.  The macro evaluates
    each argument several times.



12. TOS related functions. Non portable

12.1 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. include <time.h>

clock_t time_since(clock_t *t)
    Returns the number of 200Hz ticks since start_timer() was called
    for timer <t>. include <time.h>


12.2 PROCESS CONTROL:

The functions are to find in xdlibs.a and extended.lib.

BASEPAGE *Getbpact_pd()
    Get basepage pointer of act_pd.
    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 actual's value's
    parents (bp->p_parent). Include atari.h

unsigned int GetTOSvers( long *OS_date,
         unsigned int *OS_conf, unsigned int * OS_dosdate);
    Get TOS version.
    The pointers maybe NULL if you are not interested in this
    values. Include atari.h

int Getcookie( long cookie, long *value );
    Exists a special cookie?
    If it returns FALSE, it doesn't exit. If the pointer is NULL,
    you won't get the cookie's value. Include atari.h

void GetMiNT()
    Either a dummy function from main.o xdlibs' module, cause you won't
    need it together with _main(),or a function to set up _mint flag
    if it is -1.

long gemdos(int func[, arg1, ..., argN])
    Call operating system trap #1 (GEMDOS) function number <func> with
    the arguments given.  Return value returned by the trap call.

long bios(int func[, arg1, ..., argN])
    Call operating system trap #13 (BIOS) function number <func> with
    the arguments given.  Return value returned by the trap call.

long xbios(int func[, arg1, ..., argN])
    Call operating system trap #14 (XBIOS) function number <func> with
    the arguments given.  Return value returned by the trap call.

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



13. DEVICE I/O FUNCTIONS:
(mostl of them are to find in 'extended.lib')
NON portable functions, they refere to BIOS devices. This will cause
problems in standard environments.
Better forget about most of them. -jerry-

int cfg_ch(int cfg)
    Configure getch()/putch() operation.  The following are legal
    values for <cfg> and may be combined with the | operator:
        _CIOB        Use BIOS level i/o calls
        _CIOCH        8-bit character codes only (cf:getch)
        _CIOVT        Enable VT-52 escape sequence processing
    The initial configuration value at run time is _CIOCH.  This
    function returns the previous configuration value, and if <cfg>
    is -1 the value is not set.

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

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

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

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

char *getln(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 i/o 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 (like curses?).


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.

FORMATTING/TYPE CONVERSION:
int cprintf(char *fmt[, arg1, ..., argN])
    Formatted output directly to the console.  This functions uses the
    system dependent putch() for output.  See the _printf() function
    for a description of the <fmt> formatting string.


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