home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / dirs / cclib_399.lzh / CCLib / CClib.Doc < prev    next >
Text File  |  1990-11-02  |  165KB  |  4,809 lines
  1. |**************************************************************************|
  2. |****************       Shareware         **************************|
  3. |**************** $50 registration fee requested **************************|
  4. |****************      (from authors only)       **************************|
  5. |**************************************************************************|
  6.  
  7.          Documentation for CClib.library V3.0
  8.  
  9.     Copyright (C) 1989,1990 by Robert W. Albrecht, All Rights Reserved.
  10.  
  11.        Software and Documentation written and distributed by:
  12.  
  13.                Robert W. Albrecht
  14.                1457 Zion Way
  15.                Ventura, CA 93003, USA
  16.  
  17.  
  18.   Special thanks to Paul Gittings for his contributions to the library.
  19.  
  20. -------------------------------------------------------------------------
  21.  
  22.    INTRODUCTION
  23.  
  24.    This is an implementation of the standard C library, with a few extra
  25.    goodies thrown in, that is done as an Amiga loadable library. This
  26.    allows many applications to share the same library code, saving disk
  27.    space, and probably RAM if more than one application is running at a
  28.    time. The other advantage of the library is that as improvements are
  29.    made to it improvements are made to the programs that use it, and the
  30.    programmer doesn't even have to know about it. From the very early Amiga
  31.    days I have thought that this should have been done by CBM, but it
  32.    wasn't, and I was a little suprised that no one else had either. Well,
  33.    after I started I found out why it hadn't been done; It is real tricky
  34.    to make the C library re-entrant. Also it turns out that there are over
  35.    one hundred and forty functions in the library.
  36.  
  37.  
  38. -------------------------------------------------------------------------
  39.  
  40.             CONTENTS
  41.  
  42.    I) LICENSE
  43.       Transfer
  44.       Term
  45.       Robert W. Albrecht's rights
  46.       Disclaimer of other Warranties, and Liabilities
  47.  
  48.    II) RUN-TIME IMPLEMENTATION OF CCLIB.LIBRARY
  49.  
  50.    III) FUNCTION DOCUMENTATION
  51.  
  52.       1) SUPPORT FUNCTIONS
  53.         ClearSTDIO          closeall         cli_parse        GetSTDIO
  54.         offsetof          scdir         scdir_clean    SetSTDIO
  55.         SetupSTDIO          wb_parse
  56.  
  57.       2) STREAM I/O FUNCTIONS
  58.         agetc           aputc         clearerr        fclose
  59.         fdopen           feof         ferror        fflush
  60.         fgetc           fgetpos         fgets        fopen
  61.         fprintf           fputc         fputs        fread
  62.         freopen           fscanf         fseek        fsetpos
  63.         ftell           fwrite         getbuff        getc
  64.         getchar           getchar         gets        getw
  65.         mktemp           printf         putc        putchar
  66.         putchar           puterr         puts        putw
  67.         remove           rename         rewind        scanf
  68.         setbuf           setvbuf         sprintf        sscanf
  69.         stat           stat_         tmpfile        tmpnam
  70.         ungetc           vfprintf      vprintf        vsprintf
  71.  
  72.       3) NON-STANDARD AND LOW-LEVEL I/O FUNCTIONS
  73.         access           close         creat        fileno
  74.         isatty           lseek         open        read
  75.         unlink           write
  76.  
  77.       4) CHARACTER TEST MACROS
  78.         isalpha           isupper         islower        isdigit
  79.         isxdigit           isalnum         isspace        ispunct
  80.         iscntrl           isprint         isgraph        isascii
  81.         toascii           tolower         _tolower        toupper
  82.         _toupper
  83.  
  84.        5) STRING FUNCTIONS
  85.         bcpl_strcpy        index         rindex        stpcrlf
  86.         strcat           strchr         strcmp        strcmpa
  87.         strcpy           strcspn         strerror        strlen
  88.         strncat           strncmp         strncpy        strnrv
  89.         strpbrk           strrchr         strrv        strspn
  90.         strstr           strtok         strupr
  91.  
  92.       6) MEMORY OPERATION FUNCTIONS
  93.         bcpm           bcopy         bzero        memccpy
  94.         memchr           memcpy         memmove        memset
  95.         memswap
  96.  
  97.       7) FORMAT CONVERSION FUNCTIONS
  98.         atof           atoi         atol        ltoa
  99.         stoa
  100.  
  101.       8) MEMORY ALLOCATION FUNCTIONS
  102.         be_free           calloc         free freeall
  103.         heap_alloc           heap_free     malloc malloc_size
  104.         realloc           sbrk _alloc   _fre
  105.         _freall
  106.  
  107.       9) LINKED LIST FUNCTIONS
  108.         add_head           add_tail      inst_node        put_head
  109.         put_tail           remv_head     remv_list        remv_node
  110.         remv_tail           r_node
  111.  
  112.       10) SORTING FUNCTIONS
  113.         qsort           quicksort     vquicksort
  114.  
  115.       11) TIME FUNCTIONS
  116.         asctime           clock         ctime        difftime
  117.         gmtime           localtime     mktime        strftime
  118.         time
  119.  
  120.       12) PROCESS CONTROL FUNCTIONS
  121.         abort           atexit         ClearAbortFunc cliexec
  122.         exec           exit         _exit getenv   kill
  123.         kill_children      longjmp         perror        SetAbortFunc
  124.         setenv           setjmp         signal_child   system
  125.         wait_child           wait_children wb_exec        wbAexec
  126.  
  127.    IV) STRUCTURE DOCUMENTATION
  128.       Child         clock_t       FILE FileDesc
  129.       fpos_t         union           header (alias HEADER) LastFree
  130.       _list         MemBlk        _node ptrdiff_t size_t
  131.       stat         task_UserData time_t          struct tm
  132.       va_list wchar_t
  133.  
  134.    V) GLOBAL VARIABLES
  135.       blocksize      CCLibBase     DOSBase          errno
  136.       exit_fcn         _math           MathIeeeDoubBasBase   stderr
  137.       stdin         stdout        sys_errlist and sys_nerr SysBase
  138.       type         WBenchMsg
  139.  
  140.    VI) INSTALLATION
  141.  
  142.    VII) THE NUKELIB PROGRAM
  143.  
  144.    VIII) RELEASE INFORMATION
  145.  
  146.    IX) NOTES ON LATTICE C
  147.  
  148.    X) NOTES FOR PUBLIC DOMAIN COMPILERS
  149.  
  150.    XI) REVISION HISTORY
  151.  
  152.    XII) COPYRIGHTS AND TRADEMARKS
  153.  
  154.    XIII) INDEX
  155.  
  156. -------------------------------------------------------------------------
  157.  
  158. ``    I) LICENSE
  159.  
  160.       Robert W. Albrecht is the exclusive owner of the enclosed Software
  161.       and Documentation. You are granted non-exclusive license to use the
  162.       Software and Documentation, but you are not the owner of them.
  163.      Your right to use the Software and Documentation under this
  164.       agreement is the "License". "You" means the individual or legal
  165.       entity whose agent receives this software and accepts this Agreement.
  166.       "Software" means the computer program recorded on the floppy-disk or
  167.       other media, any update to them Robert W. Albrecht may later provide
  168.       you, and any back-up copies made. "Documentation" means the user
  169.       manual and other materials packaged with this Software.
  170.  
  171.                 Transfer
  172.  
  173.       You may transfer this software and documentation to other persons so
  174.       long as no fee is charged for it. This is "shareware" and a $50
  175.       registration fee is requested from authors of software that use the
  176.       library. Registered users will gets free updates of CClib.library as
  177.       they come out.
  178.  
  179.                   Term
  180.  
  181.       The license is effective for twenty (20) years from the time you
  182.       receive the software. You may terminate the license at any time by
  183.       returning all software and documentation.
  184.  
  185.             Robert W. Albrecht's rights.
  186.  
  187.       The CClib.library Software and Documentation is protected by copyright,
  188.       trade secret and trademark laws. You may not disclose the Software or
  189.       Documentation to others, except as allowed in this license agreement,
  190.       or remove or alter ownership, trademark and copyright notices on
  191.       Documentation or Software. YOU MUST MAKE A GOOD FAITH EFFORT TO
  192.       PREVENT ANY UNAUTHORIZED USE, COPYING, OR DISCLOSURE OF THE SOFTWARE
  193.       OR DOCUMENTATION. THESE OBLIGATIONS WILL SURVIVE ANY TERMINATION OF
  194.       THE LICENSE AGREEMENT.
  195.  
  196.          Disclaimer of other Warranties, and Liabilities.
  197.  
  198.       THERE ARE NO WARRANTIES, EITHER EXPRESSED OR IMPLIED, FOR THE
  199.       SOFTWARE OR DOCUMENTATION, WHICH ARE BOTH LICENSED TO YOU "AS IS".
  200.       ROBERT W. ALBRECHT EXPRESSLY DISCLAIMS ANY WARRANTY AS TO THE
  201.       PERFORMANCE OF THE SOFTWARE, OR DOCUMENTATION. HE ALSO DISCLAIMS ALL
  202.       OTHER WARRANTIES, INCLUDING (WITHOUT LIMITATION) IMPLIED WARRANTIES
  203.       OF MERCANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
  204.       SHALL ANYONE INVOLVED IN THE CREATION, PRODUCTION, OR DISTRIBUTION,
  205.       OF THE SOFTWARE OR DOCUMENTATION BE LIABLE FOR ANY INDIRECT, SPECIAL,
  206.       INCEDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OF THE
  207.       SOFTWARE OR DOCUMENTATION OR ARISING FROM ANY BREACH OF ANY WARRANTY.
  208.       Some states do not allow the exclusion or limitation of implied
  209.       warranties or liability for incedental or consequential damages so
  210.       the above exclusion and limitation may not apply to you. IN ADDITON
  211.       TO THE ABOVE LIMITATION, OUR LIABILITY TO YOU OR TO ANYONE ELSE FOR
  212.       DAMAGES SHALL NOT EXCEED THE LICENSE FEE PAID BY YOU FOR THE SOFTWARE
  213.       AND DOCUMENTATION.
  214.  
  215. -------------------------------------------------------------------------
  216.  
  217. `` II) RUN-TIME IMPLEMENTATION OF CCLIB.LIBRARY
  218.  
  219.    The implementation of this library is designed to be as transparent as
  220.    possible to the C programmer, but is good to be aware of the actions that
  221.    are taken by the library accomplish this.
  222.  
  223.    The actual code for most of the standard C library functions is in the
  224.    file CClib.library. This is a standard Amiga dynamic link library (DLL)
  225.    and can be shared by many application programs at the same time. For the
  226.    library to work correctly it must be installed in the LIBS: directory of
  227.    your system disk.
  228.  
  229.    DLL's on the Amiga are accessed through the OpenLibrary and CloseLibrary
  230.    system (Exec) functions. When a library is opened with the OpenLibrary
  231.    function, and it is not yet loaded into RAM, Amiga DOS will go to the
  232.    LIBS: directory and load the library specified in the OpenLibrary
  233.    function. The OpenLibrary function will return the memory location of
  234.    the Library structure for the requested library, this is called the
  235.    Library Base Pointer (LBP). A table of jump instructions is located at a
  236.    negative offset to the LBP and the actual functions in the library are
  237.    accessed through this table. For each function in CClib.library there is
  238.    a connection routine in CClib.lib that will allow the application
  239.    program access to the functions in the library. The connection routines
  240.    contain two 68000 instructions: move the LBP into address register A6,
  241.    and jump to an entry in the table of jump instructions in the library.
  242.    The offset from the LBP that gets jumped to in the DLL depends on the
  243.    specific function in the library. All of these details are, of course,
  244.    transparent to the normal user of CClib.library. In order to make the
  245.    interface to the C language more efficient, the convention of placing
  246.    arguments to functions in registers was not used. Instead the
  247.    C calling convention of placing arguments on the stack in reverse
  248.    order was followed. This greatly simplified the connection routines
  249.    that get linked into your application.
  250.  
  251.    To create an implementation of the C library that is as transparent as
  252.    possible to the application the _main function, or initialization code,
  253.    and the _exit function, had to be re-written such that the _main
  254.    function opens the C library and the _exit function closes the C
  255.    library. For this reason these routines could not be included in the
  256.    DLL. You must link with the special version of _main and _exit that are
  257.    contained in the file _main.o. The _main routine must also set up stdin,
  258.    stdout, and stderr for the application, as well as handle the Amiga
  259.    Workbench environment. Also if your program needs access to functions in
  260.    the DLL that use floating point numbers the _main routine must open the
  261.    IEEE floating point library and give a pointer to this library to
  262.    CClib.library. As you may know there are a number of different floating
  263.    point options on the Amiga.
  264.  
  265.    In order to implement floating point operations in the DLL it was
  266.    necessacary to choose just one of the possible floating point options of
  267.    the Amiga. The one that is used by the DLL is the
  268.    MathIeeeDoubBas.library. The reason for using this one is that it is has
  269.    standard 64 bit IEEE floating point numbers and there is a version of
  270.    this library for the 68881 and 68882 MPUs. This means that users of
  271.    Aztec C will have to link with ma32.lib if there are any floating point
  272.    operations in the application. For users of the DLL who will have no
  273.    need for floating point numbers in their application the global short
  274.    integer _math can be declared with a value of zero and
  275.    MathIeeeDoubBas.library will not be loaded by the _main function. The
  276.    whole reason for the Ieee floating point number requirement comes from the
  277.    fact that the code for the DLL can be shared by many applications. There
  278.    are other restrictions as well that arise from this fact.
  279.  
  280.    The C data type 'int' is a 32 bit quantity. The reason that ints are 32
  281.    bits instead of 16 bits is that the 68000 is a 32 bit processor and ints
  282.    are 32 bits in Lattice C. Aztec C has compiler switches that make ints
  283.    32 bits. The DLL really doesn't care what an int is inside your program
  284.    but it does care what the arguments passed to it's functions are. When
  285.    an argument is passed to a CClib function it must be promoted to an int
  286.    before being put on the stack, if it is smaller that an int. In Aztec C
  287.    the easest way to ensure this is to use the +L compiler switch. Another
  288.    way to handle this is to cast 8 and 16 bit arguments to a 32 bit
  289.    quantity.
  290.  
  291.    Another issue that arises from the fact that the DLL code is shared, is
  292.    the problem of re-entrancy. CClib must not modify it's own data in such
  293.    a way it can't be re-used by another application, but some functions in
  294.    any C library implementation must, by nature, use global data. For
  295.    instance the heap memory manager must keep track of a list of free
  296.    memory blocks, and must do so in a way that is transparent to the
  297.    application. It would not due for all of the users of the DLL to share
  298.    the same free memory list. This means that the DLL must allocate a block
  299.    of memory for each of it's users and somehow know which block to use. It
  300.    turns out that there is a very simple way to implement this on the
  301.    Amiga. Every Amiga task must have a Task structure associated with it so
  302.    that Exec can keep track of it. To obtain a pointer to the currently
  303.    running task you call the Exec function FindTask with an argument of
  304.    zero. Also there is an unused member of the Task structure called
  305.    tc_UserData. When the DLL initializes your task it allocates some memory
  306.    from Exec and makes tc_UserData point to that memory. Whenever you call
  307.    a CClib function that requires the use of global data it acceses the
  308.    memory block attached to your task's tc_UserData field. For this reason
  309.    you had better not mess around with your task's tc_UserData member and
  310.    expect CClib to work.
  311.  
  312.    The implementation of file handles and FILE pointers is quite different
  313.    than the implementation in other C libraries. Most C libraries keep a
  314.    static array of FILE structures and a static array of file handles. This
  315.    method is just fine for systems which have a built-in limit as to the
  316.    number of open files a single task can have, but it doesn't make any
  317.    sense for a computer that has no such limitation. For this reason the
  318.    FILE structures and file handles are implemented as linked lists in
  319.    the DLL. This improvement does have one side effect though, there are
  320.    no pre-opened file handles, for example 1 is not the low-level file handle
  321.    for stdio. Instead of hard-coding the low-level file handles you will
  322.    have to use the fileno() macro defined in stdio.h, for example:
  323.    write(fileno(stdin),"Hello World",11L);
  324.  
  325.    Despite these restrictions due to the implementation of the library
  326.    it is hoped that you will find this library useful. Be sure to look at
  327.    the example programs for more information.
  328.  
  329. -------------------------------------------------------------------------
  330.  
  331. `` III) FUNCTION DOCUMENTATION
  332.  
  333.    The documentation of the functions in the library follows this format:
  334.  
  335. -------------------------------------------------------------------------
  336. Name:           The name of the C function or macro    [MACRO] =
  337.                               this is a macro
  338.  
  339. Synopsis:      The outline of the function with the type of the argumets
  340.            and the return value.
  341.  
  342. Function:      What actions are taken by this function.
  343.  
  344. Arguments:     An explanation of the arguments to this function.
  345.  
  346. Return:        The return value of the function, and what indicates an
  347.            error condition. It is also indicated if any global variables
  348.            are set by this function.
  349.  
  350. See Also:      Other documentation that will lead to a further understanding
  351.            of the function.
  352. -------------------------------------------------------------------------
  353.  
  354. `` 1) SUPPORT FUNCTIONS
  355.  
  356.    Some of these functions are not a normal part of a C library but are
  357.    used to support this implementation. Other functions are here because
  358.    they don't fit into another category.
  359.  
  360. -------------------------------------------------------------------------
  361. Name:        ClearSTDIO
  362.  
  363. Synopsis:   void ClearSTDIO()
  364.  
  365. Function:   Returns resources to the system that were used by a process
  366.         using CClib.library. All files are closed and all allocated
  367.         memory is freed. The task's tc_UserData field is re-set to
  368.         it's original condition.
  369.  
  370. See Also:   SetSTDIO, SetupSTDIO
  371. -------------------------------------------------------------------------
  372. Name:        closeall
  373.  
  374. Synopsis:   void closeall()
  375.  
  376. Function:   Closes all opened stream files and low-level files.
  377.  
  378. See Also:   ClearSTDIO
  379. -------------------------------------------------------------------------
  380. Name:        cli_parse
  381.  
  382. Synopsis:   void cli_parse(ud,alen,aptr)
  383.         task_UserData *ud;
  384.         long alen;
  385.         char *aptr;
  386.  
  387. Function:   Parses the command line arguments into argc and argv for
  388.         the main routine. Called only when the program is executed
  389.         from the CLI.
  390.  
  391. Arguments:  ud - a pointer to the task's user data structure.
  392.         alen - the length of the command string passed to the program
  393.         from AmigaDOS.
  394.         aptr - a pointer to the command string passed to the program from
  395.         AmigaDOS.
  396.  
  397. See Also:   wb_parse
  398. -------------------------------------------------------------------------
  399. Name:        GetSTDIO
  400.  
  401. Synopsis    task_UserData *GetSTDIO()
  402.  
  403. Function:   Gets a pointer to the block of memory used for global data
  404.         for this task. This function is written in assembly language
  405.         because it is used quite frequently by the library. The
  406.         task_UserData structure is defined in iolib.h.
  407.  
  408. Return:     A pointer to the task's user data block, or NULL if it isn't
  409.         initialized yet.
  410.  
  411. See Also:   SetSTDIO
  412. -------------------------------------------------------------------------
  413. Name:        offsetof                      MACRO
  414.  
  415. Synopsis:   #include "stddef.h"
  416.         size_t offsetof(Structure, Member)
  417.  
  418.  
  419. Function:   returns the offset in bytes of a member of a structure from
  420.         the beginning of the structure.
  421.  
  422. Arguments:  Structure - the name of a C data structure, for example
  423.            "struct stat".
  424.         Member - the name of a member of "Structure".
  425.  
  426. Return:     the offset in bytes of the beginning of the member from the
  427.         beginning of the structure.
  428. -------------------------------------------------------------------------
  429. Name:        scdir
  430.  
  431. Synopsis:   char *scdir(pattern)
  432.         char *pattern;
  433.  
  434. Function:   This function is used to support wild card file names using
  435.         '*' and '?' where '*' matches any number of characters and
  436.         '?' matches any single character. To use the function simply
  437.         pass the pattern to the function and keep calling it until
  438.         NULL is returned. For example:
  439.         while( name = scdir("*.c") ) do_something(name);
  440.  
  441. Warning:    This function allocates memory from the system that is not
  442.         freed until it returns NULL. So that the memory gets returned
  443.         to the system be sure keep calling it until NULL is returned,
  444.         if you don't the memory will remain allocated until the program
  445.         exits. Also the file pattern is irrelavent after the first call
  446.         to scdir because it remembers the pattern in it's own memory.
  447.         The memory used by scdir is pointed to by
  448.         task_UserData.scdir_mem and if you wish to scan another directory
  449.         before the current one is finished you can save this pointer,
  450.         set it to NULL, scan the other directory, restore the pointer
  451.         and then keep calling scdir until NULL is returned.
  452.  
  453. Arguments:  pattern - the file name pattern.
  454.  
  455. Return:     A pointer to a file name that matches the pattern or NULL.
  456.  
  457. See Also:   scdir_clean
  458. -------------------------------------------------------------------------
  459. Name:        scdir_clean
  460.  
  461. Synopsis:   void scdir_clean(void)
  462.  
  463. Function:   cleans up any mess made by scdir, allocted memory, open locks
  464.         etc. It only needs to be called if scdir has never returned
  465.         NULL and you want to use scdir again.
  466.  
  467. See Also:   scdir
  468. -------------------------------------------------------------------------
  469. Name:        SetSTDIO
  470.  
  471. Synopsis:   long SetSTDIO()
  472.  
  473. Function:   Allocates memory for a task_UserData structure and attaches
  474.         it to the tc_UserData field of the task structure.
  475.  
  476. Return:     Zero is returned if the operation was a success, otherwise
  477.         one is returned.
  478.  
  479. See Also:   SetupSTDIO
  480. -------------------------------------------------------------------------
  481. Name:        SetupSTDIO
  482.  
  483. Synopsis:   long SetupSTDIO(in, out, err, errno, bsize, ctyp, mathbase,
  484.                 alen, aptr, wbm, _xit)
  485.         FILE **in, **out, **err;
  486.         long *errno, *bsize;
  487.         char **ctyp;
  488.         void *mathbase;
  489.         long alen;
  490.         char *aptr;
  491.         struct WBStartup *wbm;
  492.         void (*_xit)();
  493.  
  494. Function:   Gives the library access to global variables that reside in the
  495.         application program and opens standard input, output and error
  496.         streams and allocates the SetSTDIO to allocate the memory that
  497.         is pointed to by task->tc_UserData. Standard I/O will not be
  498.         opened for programs run from the workbench that have no
  499.         "WINDOW" tooltype in their tool icon, or for programs run
  500.         from the workbench by projects.
  501.  
  502. Arguments:  in, out, err - memory locations where pointers to the standard
  503.         stream files are stored in the application program.
  504.         errno - the memory location where the global variable errno
  505.         is stored.
  506.         bsize - the memory location where the global variable blocksize
  507.         is stored. blocksize is used by the heap manager to determine the
  508.         minimum size of the memory blocks to be allocated from AmigaDOS.
  509.         ctyp - this is the 'type' array that is used by the macros in
  510.         ctype.h. The array is actually in the library and the
  511.         application just gets a pointer to it.
  512.         mathbase - The address of the MathIeeDoubBas library base pointer
  513.         to be used for programs that use floating point numbers.
  514.         alen - the length of the command line passed to the program by
  515.         the CLI process, if run from the CLI.
  516.         aptr - a pointer to the command line passed to the program by the
  517.         CLI process, if run form the CLI.
  518.         wbm - a pointer to the workbench startup message sent by the
  519.         workbench program. This will be used by wb_parse to open a
  520.         standard I/O window for the application if the Tooltype
  521.         "WINDOW" is set.
  522.         _xit - a pointer to the applications exit routine. This is set
  523.         to be exit() by the _main routine.
  524.  
  525. Return:     One is returned if all of the initialization was successful,
  526.         otherwise zero is returned.
  527. -------------------------------------------------------------------------
  528. Name:        wb_parse
  529.  
  530.         long wb_parse(ud, wbmsg)
  531.         task_UserData *ud;
  532.         struct WBStartup **wbmsg;
  533.  
  534. Function:   Checks the Tool Types of the icon associated with this program.
  535.         If the Tool Type WINDOW is found a window is opened using the
  536.         Tool Type's value. This window is used for standard input and
  537.         output. If the WINDOW tool type is not found then a program
  538.         run from the workbench will have NO standard input, output, and
  539.         error, and any attempt to write to these non-existant devices
  540.         will almost certainly cause a system crash. A good example of
  541.         a valid tool type would be:
  542.         WINDOW=CON:20/10/300/100/WindowTitle
  543.  
  544. Arguments:  ud - a pointer to the task's task_UserData structure.
  545.         wbmsg - a pointer to the workbench startup message for this
  546.         program.
  547.  
  548. Return:     Non-zero is returned if a window was opened for standard
  549.         input and output.
  550.  
  551. See Also:   cli_parse
  552. -------------------------------------------------------------------------
  553.  
  554. `` 2) STREAM I/O FUNCTIONS
  555.  
  556.    These functions send and receive bytes from "streams". A stream is the
  557.    data type FILE that is defined in stdio.h. Some of the functions
  558.    are implemented as macros that are defined in stdio.h. Other functions
  559.    read and write to the standard pre-opened stream files "stdin", "stdout"
  560.    and "stderr". When an error occurs with one of these functions the
  561.    global variable errno will contain further information.
  562.  
  563. -------------------------------------------------------------------------
  564. Name:        agetc
  565.  
  566. Synopsis:   short agetc(fp)
  567.         FILE *fp;
  568.  
  569. Function:   Gets one character from the designated stream. This function
  570.         is here to support existing implementations of the C library
  571.         and should not be used in new code.
  572.  
  573. Arguments:  fp - a pointer to the stream file to receive input from.
  574.  
  575. Return:     The character received as input, of EOF if the end of the
  576.         file has been reached, or if an error has occured.
  577.  
  578. See Also:   getc
  579. -------------------------------------------------------------------------
  580. Name:        aputc
  581.  
  582. Synopsis:   short aputc(c,fp)
  583.         short c;
  584.         FILE *fp;
  585.  
  586. Function:   Writes one character to the specified stream. This function is
  587.         here to support existing implementations of the C library and
  588.         should not be used in new code.
  589.  
  590. Arguments:  c - the character to write
  591.         fp - the stream to write to.
  592.  
  593. Return:     EOF is returned on error.
  594.  
  595. See Also:   putc
  596. -------------------------------------------------------------------------
  597. Name:        clearerr                 MACRO
  598.  
  599. Synopsis:   #include "stdio.h"
  600.         int clearerr(fp)
  601.         FILE *fp;
  602.  
  603. Function:   Clears end of file and error indicators in a stream.
  604.  
  605. Arguments:  fp - pointer to a stream file
  606.  
  607. See Also:   feof, ferror
  608. -------------------------------------------------------------------------
  609. Name:        fclose
  610.  
  611. Synopsis:   long fclose(fp)
  612.         FILE *fp;
  613.  
  614. Function:   Closes a stream file.
  615.  
  616. Arguments:  fp - stream file to close
  617.  
  618. Return:     Zero is returned if the operation was successful, otherwise
  619.         non-zero is returned.
  620.  
  621. See Also:   fopen
  622. -------------------------------------------------------------------------
  623. Name:        fdopen
  624.  
  625. Synopsis:   FILE *fdopen(fh,fmode)
  626.         long fh;
  627.         char *fmode;
  628.  
  629. Function:   Creates a stream file from a low-level file handle.
  630.         This function is here to support existing C library
  631.         implementations and should not be used in new code.
  632.  
  633. Arguments:  fh - the low-level file handle
  634.         fmode - not used in this implementation, but used to contain the
  635.         file open modes.
  636.  
  637. Return:     A pointer to the new stream file is returned, otherwise NULL.
  638.  
  639. See Also:   fopen
  640. -------------------------------------------------------------------------
  641. Name:        feof                 MACRO
  642.  
  643. Synopsis:   #include "stdio.h"
  644.         int feof(fp)
  645.         FILE *fp;
  646.  
  647. Function:   Tests for end of file.
  648.  
  649. Arguments:  fp - pointer to a stream file
  650.  
  651. Return:     Retuns non-zero if the end of file bit is set in the stream.
  652. -------------------------------------------------------------------------
  653. Name:        ferror                 MACRO
  654.  
  655. Synopsis:   #include "stdio.h"
  656.         int ferror(fp)
  657.         FILE *fp;
  658.  
  659. Function:   Tests for file error.
  660.  
  661. Arguments:  fp - pointer to a stream file
  662.  
  663. Return:     Returns non-zero if the error bit is set in the stream.
  664. -------------------------------------------------------------------------
  665. Name:        fflush
  666.  
  667. Synopsis:   long fflush(fp)
  668.         FILE *fp;
  669.  
  670. Function:   Causes buffered but unwritten data to be written on an output
  671.         file. The operation is undefined for input streams.
  672.  
  673. Arguments:  fp - the stream file to flush
  674.  
  675. Return:     EOF is returned on a write error, otherwise zero is returned.
  676. -------------------------------------------------------------------------
  677. Name:        fgetc                 MACRO
  678.  
  679. Synopsis:   #include "stdio.h"
  680.         int fgetc(fp)
  681.         FILE *fp;
  682.  
  683. Function:   Gets one character from the designated stream.
  684.  
  685. Arguments:  fp - a pointer to the stream file to receive input from.
  686.  
  687. Return:     The character received as input, of EOF if the end of the
  688.         file has been reached, or if an error has occured.
  689.  
  690. See Also:   getc
  691.  
  692. -------------------------------------------------------------------------
  693. Name:        fgetpos
  694.  
  695. Synopsis:   #inlude "stdio.h"
  696.         long fgetpos(fp,pos)
  697.         FILE *fp;
  698.         fpos_t *pos;
  699.  
  700. Function:   Saves the current position in a stream file into a variable
  701.         that is suitable for a call to fsetpos.
  702.  
  703. Arguments:  fp - stream to get the current position of
  704.         pos - current position is saved to this address. The data
  705.         type fpos_t is defined in stdio.h.
  706.  
  707. Return:     Non-zero is returned on an error.
  708.  
  709. See Also:   fsetpos
  710. -------------------------------------------------------------------------
  711. Name:        fgets
  712.  
  713. Synopsis:   char *fgets(buf,n,fp)
  714.         char *buf;
  715.         long n;
  716.         FILE *fp;
  717.  
  718. Function:   Reads at most n-1 bytes from a stream file into an array,
  719.         if a '\n' character is encountered it is included
  720.         in the array which is then NULL terminated.
  721.  
  722. Arguments:  buf - pointer to the array of bytes to store the input.
  723.         n - maximum number of bytes to read.
  724.         fp - pointer to the stream file to read from.
  725.  
  726. Return:     buf is returned unless the end of file is reached or an error
  727.         occurs in which case NULL is returned.
  728.  
  729. See Also:   fputs
  730. -------------------------------------------------------------------------
  731. Name:        fopen
  732.  
  733. Synopsis:   FILE *fopen(fname,fmode)
  734.         char *fname;
  735.         char *fmode;
  736.  
  737. Function:   Opens a sream file.
  738.  
  739. Arguments:  fname - the name of the file to open. The file name may be up
  740.         to FILENAME_MAX characters long.
  741.         fmode - the mode to open the file in. Legal values include:
  742.         "r"   open a file for reading
  743.         "w"   create a file for writing, discard contents if any.
  744.         "a"   append; open or create a file for writing at the end.
  745.         "r+"  open a file for update, reading and writing)
  746.         "w+"  create a file for update, discard previous contents
  747.         "a+"  append; open or create a file for update, write at end
  748.         Optionally a 'b' may be added to the open mode, but this is not
  749.         needed for the Amiga system because there is no distinction
  750.         between text files and binary files.
  751.  
  752. Return:     A pointer to a stream file is returned, if an error occurs NULL
  753.         is returned.
  754.  
  755. See Also:   fclose
  756. -------------------------------------------------------------------------
  757. Name:        fprintf
  758.  
  759. Synopsis:   long fprintf(fp,fmt,...)
  760.         FILE *fp;
  761.         char *fmt;
  762.  
  763. Function:   Sends formatted output to a stream file. For a more detailed
  764.         description of formatted output please see printf.
  765.  
  766. Arguments:  fp - pointer to the stream file
  767.         fmt - format to print the arguments with.
  768.         ... - a variable number of arguments that is specified in fmt.
  769.  
  770.  
  771. Return:     The number of characters written is returned.
  772.  
  773. See Also:   printf
  774. -------------------------------------------------------------------------
  775. Name:        fputc                 MACRO
  776.  
  777. Synopsis:   #include "stdio.h"
  778.         int fputc(c,fp)
  779.         short c;
  780.         FILE *fp;
  781.  
  782. Function:   Writes one character to the specified stream.
  783.  
  784. Arguments:  c - character to write
  785.         fp - stream to write to
  786.  
  787. Return:     EOF is returned on error
  788.  
  789. See Also:   putc
  790. -------------------------------------------------------------------------
  791. Name:        fputs
  792.  
  793. Synopsis:   long fputs(string,fp)
  794.         char *string;
  795.         FILE *fp;
  796.  
  797. Function:   Sends a string to the specified stream file.
  798.  
  799. Arguments:  string - NULL terminated string to send.
  800.         fp - stream to send the string to.
  801.  
  802. Return:     EOF is returned on error, otherwise > 0.
  803.  
  804. See Also:   fgets
  805. -------------------------------------------------------------------------
  806. Name:        fread
  807.  
  808. Synopsis:   #include "stdio.h"
  809.         size_t fread(buf,size,nobj,fp)
  810.         void *buf;
  811.         size_t size;
  812.         size_t nobj;
  813.         FILE *fp;
  814.  
  815. Function:   Reads from a stream into an array at most nobj elements of
  816.         size. (number of bytes = size*nobj).
  817.  
  818. Arguments:  buf - buffer to store the data
  819.         size - size of each element to read
  820.         nobj - number of elements to read
  821.         fp - stream to read from
  822.  
  823. Return:     The number of elements read, which may be less than nobj due
  824.         to an end of file or error condition.
  825.  
  826. See Also:   fwrite
  827. -------------------------------------------------------------------------
  828. Name:        freopen
  829.  
  830. Synopsis:   FILE *freopen(fname, fmode, oldfp)
  831.         char *fname;
  832.         char *fmode;
  833.         FILE *oldfp;
  834.  
  835. Function:   Re-opens a stream file with a different name and possibly a
  836.         different file mode. It is most commonly used to re-direct
  837.         stdin, stdout, and stderr.
  838.  
  839. Arguments:  fname - name of the stream to open
  840.         fmode - mode to open the stream in. See the description of
  841.         fopen for the legal file modes.
  842.         oldfp - the stream to re-open.
  843.  
  844. Return:     A pointer to the new stream is returned if the operation was
  845.         successful, otherwise NULL is returned.
  846.  
  847. See Also:   fopen
  848. -------------------------------------------------------------------------
  849. Name:        fscanf
  850.  
  851. Synopsis:   long fscanf(fp,fmt,...);
  852.         FILE *fp;
  853.         char *fmt;
  854.  
  855. Function:   Reads formatted input from a stream. For a further explanation
  856.         of formatted input please see scanf.
  857.  
  858. Arguments:  fp - stream to read the formatted input from.
  859.         fmt - format of the arguments to be read.
  860.         ... - a variable number of arguments that are specified in fmt.
  861.         Each of the arguments to fscanf must be a pointer.
  862.  
  863. Return:     The number of items converted and assigned is returned.
  864.  
  865. See Also:   scanf
  866. -------------------------------------------------------------------------
  867. Name:        fseek
  868.  
  869. Synopsis:   #include "stdio.h"
  870.         long fseek(fp,offset,origin)
  871.         FILE *fp;
  872.         long offset;
  873.         long origin;
  874.  
  875. Function:   Sets the position in a stream relative to "origin".
  876.  
  877. Arguments:  fp - stream to set the position of.
  878.         offset - offset in bytes to set the position to.
  879.         origin - position realtive to which the new position will
  880.         be set. The values for origin may be SEEK_SET (beginning),
  881.         SEEK_CUR, (current position), SEEK_END (end of file).
  882.  
  883. Return:     Non-zero is returned when an error occurs.
  884.  
  885. See Also:   ftell, fsetpos
  886. -------------------------------------------------------------------------
  887. Name:        fsetpos
  888.  
  889. Synopsis:   long fsetpos(fp,pos)
  890.         FILE *fp;
  891.         fpos_t *pos;
  892.  
  893. Function:   Positions a stream to a position saved by fgetpos.
  894.  
  895. Arguments:  fp - stream to set the position of.
  896.         pos - pointer to the position saved by fgetpos.
  897.  
  898. Return:     Non-zero is returned when an error occurs.
  899.  
  900. See Also:   fseek
  901. -------------------------------------------------------------------------
  902. Name:        ftell
  903.  
  904. Synopsis:   long ftell(fp)
  905.         FILE *fp;
  906.  
  907. Arguments:  fp - a stream file.
  908.  
  909. Return:     Returns the current file position, of -1 if an error occurs.
  910.  
  911. See Also:   fgetpos
  912. -------------------------------------------------------------------------
  913. Name:        fwrite
  914.  
  915. Synopsis:   #include "stdio.h"
  916.         size_t fwrite(buf,size,nobj,fp)
  917.         void *buf;
  918.         size_t size, nobj;
  919.         FILE *fp;
  920.  
  921. Function:   Writes from an array to a stream, at most nobj elements of size
  922.         size are written.
  923.  
  924. Arguments:  buf -  array to write from.
  925.         size - size of the elements to write.
  926.         nobj - number of elements to write.
  927.         fp - stream to write to.
  928.  
  929. Return:     The number of element written is returned, which is less than
  930.         nobj on error.
  931.  
  932. See Also:   fread
  933. -------------------------------------------------------------------------
  934. Name:        getbuff
  935.  
  936. Synopsis:   void getbuff(fp)
  937.         FILE *fp;
  938.  
  939. Function:   Allocates the standard sized buffer for buffered input and
  940.         output. The function must be called before any reading or
  941.         writing is done. It will be called for you otherwise.
  942.  
  943. Arguments:  fp - stream to attach the buffer to.
  944.  
  945. See Also:   setvbuf
  946. -------------------------------------------------------------------------
  947. Name:        getc
  948.  
  949. Synopsis:   short getc(fp)
  950.         FILE *fp;
  951.  
  952. Function:   Gets one character from the designated stream.
  953.  
  954. Arguments:  stream - a pointer to the stream file to receive input from.
  955.  
  956. Return:     The character received as input, or EOF if the end of the
  957.         file has been reached, or if an error has occured.
  958.  
  959. See Also:   fgetc
  960. -------------------------------------------------------------------------
  961. Name:        getchar                 MACRO
  962.  
  963. Synopsis:   #include "stdio.h"
  964.         short getchar();
  965.  
  966. Function:   Reads one character from the standard input.
  967.  
  968. Return:     The character received as input, of EOF if the end of the
  969.         file has been reached, or if an error has occured.
  970.  
  971. See Also:   getc
  972. -------------------------------------------------------------------------
  973. Name:        getchar
  974.  
  975. Synopsis:   #define NOMACROS
  976.         #include stdio.h     or     short getchar();
  977.         short getchar();
  978.  
  979. Function:   Reads one character from the standard input.
  980.  
  981. Return:     The character received as input, of EOF if the end of the
  982.         file has been reached, or if an error has occured.
  983.  
  984. See Also:   getc
  985. -------------------------------------------------------------------------
  986. Name:        gets
  987.  
  988. Synopsis:   char *gets(buf)
  989.         char *buf;
  990.  
  991. Function:   Reads a line from the standard input. The newline '\n' is
  992.         replaced by a '\0'.
  993.  
  994. Arguments:  buf - array of characters where the input line is stored.
  995.  
  996. Return:     Returns buf unless end of file or an error occurs in which
  997.         case NULL is returned.
  998.  
  999. See Also:   puts,fputs
  1000. -------------------------------------------------------------------------
  1001. Name:        getw
  1002.  
  1003. Synopsis:   short getw(fp)
  1004.         FILE *fp;
  1005.  
  1006. Function:   Reads a 16 bit word from the specified stream.
  1007.  
  1008. Arguments:  fp - stream to read the word from.
  1009.  
  1010. Return:     EOF is returned on error, otherwise the data read from the
  1011.         stream is returned.
  1012.  
  1013. See Also:   putw
  1014. -------------------------------------------------------------------------
  1015. Name:        mktemp
  1016.  
  1017. Synopsis:   char *mktemp(buf)
  1018.  
  1019. Function:   Creates a temporary file name from a template whose last few
  1020.         characters are 'X'. For example "BOBXXXX.XX".
  1021.  
  1022. Arguments:  buf - template to create the file name from.
  1023.  
  1024. Return:     buf is returned.
  1025.  
  1026. See Also:   tmpnam
  1027. -------------------------------------------------------------------------
  1028. Name:        printf
  1029.  
  1030. Synopsis:   long printf(fmt,...)
  1031.         char *fmt;
  1032.  
  1033. Function:   Writes formatted output to stdout under control of a
  1034.         format string.
  1035.  
  1036. Arguments:  fmt - format of the following arguments.
  1037.         fmt contains two things, regular characters which are copied
  1038.         to stdout, and conversion specifications, each of which causes
  1039.         conversion and printing of the next argument in the variable
  1040.         argument list. Every conversion specification begins with a
  1041.         '%' character and ends with a converson character. Before the
  1042.         conversion character there may be one or more modifiers. Below
  1043.         is a list of the modifiers in the order that they must appear.
  1044.  
  1045.         1) Flags (in any order) [-+0 ]
  1046.            '-'   specifies left justification within the field
  1047.            '+'   specifies that the number will be printed with a sign
  1048.            ' '   space is printed if the first character isn't a sign
  1049.            '0'   for numeric conversions leading zeros will be printed
  1050.              instead of spaces
  1051.            '#'   is NOT supported yet
  1052.         2) Field Width [0123456789]
  1053.            The minimum field width that the converted argument will
  1054.            be printed in. The argument may be printed in a wider field
  1055.            if it would overflow the field. If the converted argument
  1056.            has fewer characters it will be padded with spaces, unless
  1057.            zeros are specified.
  1058.         3) A period, [.]
  1059.            seperating the field width from the precision.
  1060.         4) Precision number [0123456789]
  1061.            o  For character strings; specifies the maximum number of
  1062.           characters to be printed.
  1063.            o  For floating point numbers in e, E, or f formats the number
  1064.           of digits to be printed after the decimal point.
  1065.            o  For floating point numbers in the G or g formats the number
  1066.           of significant digits to be printed.
  1067.            o  For integral numbers the minimum number of digits to be
  1068.           printed, leading zeros will be added if the number isn't
  1069.           big enough to be prited.
  1070.         5) Argument length specifier [lh]
  1071.            If the length specifier is not present then the argument
  1072.            is taken to be the short ('h') form.
  1073.           For integral values:
  1074.            The length specifier is completly optional for integral values
  1075.            because all 16 bit arguments must be promoted to a 32 bit
  1076.            quantity before passing them to a CClib.library function.
  1077.            o  'l' prints the argument as long or unsigned long.
  1078.            o  'h' prints the argument as short or unsigned short.
  1079.           For floating point values:
  1080.            o  'h' prints the argument as a float.
  1081.            o  'l' prints the argument as a double.
  1082.            o  'L' is NOT supported due to the lack of the long double
  1083.           data type on the Amiga.
  1084.  
  1085.              Printf conversion characters.
  1086.  
  1087.            d, i    signed decimal number
  1088.            o    unsigned octal number
  1089.            x, X    unsigned hexadecimal number using lowercase letters
  1090.             for 'x' and upper case letters for 'X'
  1091.            u    unsigned decimal number
  1092.            c    a single character
  1093.            s    a NULL terminated string
  1094.            f    float or double depending on the length specifier to
  1095.             be printed with a fixed decimal point
  1096.            e, E    float or double depending on the length specifier to
  1097.             be printed in exponential notation
  1098.            g, G    float or double depending on the length specifier to
  1099.             be printed with whatever is shorter, 'e' of 'f'
  1100.             format
  1101.            p    print as a pointer (this is really the same as
  1102.             'x' format on the Amiga).
  1103.            n    this is NOT supported yet, but should put the
  1104.             number of characters printed so far into the
  1105.             argument.
  1106.            %    prints the '%' character
  1107.  
  1108. Return:        The number of characters printed is returned or negative
  1109.            if an error occurs.
  1110.  
  1111. See Also:      fprintf, vprintf, vfprintf
  1112. -------------------------------------------------------------------------
  1113. Name:        putc
  1114.  
  1115. Synopsis:   short putc(c,fp)
  1116.         short c;
  1117.         FILE *fp;
  1118.  
  1119. Function:   Writes one byte to the specified stream.
  1120.  
  1121. Arguments:  c - character to write
  1122.         fp - stream to write to
  1123.  
  1124. Return:     EOF is returned on error
  1125.  
  1126. See Also:   getc
  1127. -------------------------------------------------------------------------
  1128. Name:        putchar                 MACRO
  1129.  
  1130. Synopsis:   #include "stdio.h"
  1131.         short putchar(c)
  1132.         short c;
  1133.  
  1134. Function:   Writes one character to the standard output.
  1135.  
  1136. Arguments:  c - the character to write
  1137.  
  1138. Return:     EOF is returned on error.
  1139.  
  1140. See Also:   putc
  1141. -------------------------------------------------------------------------
  1142. Name:        putchar
  1143.  
  1144. Synopsis:   #defile NOMACROS 1
  1145.         #include "stdio.h"         or    short putchar(c)
  1146.         short putchar(c)                 short c;
  1147.         short c;
  1148.  
  1149. Function:   Writes one character to the standard output.
  1150.  
  1151. Arguments:  c - the character to write
  1152.  
  1153. Return:     EOF is returned on error.
  1154.  
  1155. See Also:   putc
  1156. -------------------------------------------------------------------------
  1157. Name:        puterr
  1158.  
  1159. Synopsis:   short puterr(c)
  1160.         short c;
  1161.  
  1162. Function:   Writes one character to stderr.
  1163.  
  1164. Arguments:  c - character to write
  1165.  
  1166. Return:     EOF is returned on error
  1167.  
  1168. See Also:   perror
  1169. -------------------------------------------------------------------------
  1170. Name:        puts
  1171.  
  1172. Synopsis:   short puts(str)
  1173.         char *str;
  1174.  
  1175. Function:   Writes a NULL terminated string and a newline ('\n') character
  1176.         to stdout.
  1177.  
  1178. Arguments:  str - string to write
  1179.  
  1180. Return:     EOF is returned on error
  1181.  
  1182. See Also:   gets
  1183. -------------------------------------------------------------------------
  1184. Name:        putw
  1185.  
  1186. Synopsis:   unsigned short putw(w,fp)
  1187.         unsigned short w;
  1188.         FILE *fp;
  1189.  
  1190. Function:   Writes a 16 bit word to the specified stream.
  1191.  
  1192. Arguments:  w - word to write
  1193.         fp - stream to write to
  1194.  
  1195. Return:     w is returned when no error occurs, otherwise EOF.
  1196.  
  1197. See Also:   putc
  1198. -------------------------------------------------------------------------
  1199. Name:        remove                 MACRO
  1200.  
  1201. Synopsis:   #include "stdio.h"
  1202.         long remove(fname)
  1203.         char *fname;
  1204.  
  1205. Function:   Deletes a file.
  1206.  
  1207. Arguments:  fname - name of the file to delete
  1208.  
  1209. Return:     Non-zero is returned on error.
  1210.  
  1211. See Also:   unlink
  1212. -------------------------------------------------------------------------
  1213. Name:        rename
  1214.  
  1215. Synopsis:   long rename(oldfname,newfname)
  1216.         char *oldfname;
  1217.         char *newfname;
  1218.  
  1219. Function:   Renames a file. In AmigaDOS files may be renamed across
  1220.         directories but not across volumes. For example
  1221.         rename("RAM:t/junk","RAM:t/stuff/junk); would be legal but
  1222.         rename("RAM:t/junk","DF0:junk"); would not be.
  1223.  
  1224. Arguments:  oldfname - name of the file to rename
  1225.         newfname - new name of the file
  1226.  
  1227. Return:     Non-zero is returned on error.
  1228. -------------------------------------------------------------------------
  1229. Name:        rewind                 MACRO
  1230.  
  1231. Synopsis:   #include "stdio.h"
  1232.         void rewind(fp)
  1233.         FILE *fp;
  1234.  
  1235. Function:   Sets the position of a stream file to the beginning of the file.
  1236.  
  1237. Arguments:  fp - stream file pointer
  1238.  
  1239. See Also:   fseek
  1240. -------------------------------------------------------------------------
  1241. Name:        scanf
  1242.  
  1243. Synopsis:   long scanf(fmt,...)
  1244.         char *fmt;
  1245.  
  1246. Function:   Reads formatted input from stdin under control of a format
  1247.         string.
  1248.  
  1249. Arguments:  fmt - format conversion string. The format sring is used to
  1250.         direct the interpretation of input. The format string may
  1251.         contain;
  1252.         1) whitespace (blanks and tabs) which is ignored.
  1253.         2) Characters other than '%' which are expected to match
  1254.            the next non-whitespace character of input.
  1255.         3) All conversion specifications are preceeded with a '%'
  1256.            character.
  1257.         4) Field Width [0123456789]
  1258.            Specifies the maximum width of a field.
  1259.         5) Argument length specifier [lh]
  1260.            The argument length specifier determines the size of the
  1261.            variable pointed to by the corresponding argument.
  1262.            If the length specifier is not present then the argument
  1263.            is taken to be the short ('h') form.
  1264.           For integral values:
  1265.            o  'l' converts the input as long or unsigned long.
  1266.            o  'h' converts the input as short or unsigned short.
  1267.           For floating point values:
  1268.            o  'h' converts the argument as a float.
  1269.            o  'l' converts the argument as a double.
  1270.            o  'L' is NOT supported due to the lack of the long double
  1271.           data type on the Amiga.
  1272.         6) Conversion specifications. Each conversion specification
  1273.            determines the conversion of the next field of input. Unless
  1274.            the suppression character '*' is used the input is stored in
  1275.            the next variable corresponding to the next argument. For
  1276.            each variable conversion continues until a whitespace
  1277.            character is encountered, or until the number of characters
  1278.            specified in the maximum field width of the conversion specification
  1279.            are encountered.
  1280.  
  1281.                 Scanf conversion characters.
  1282.  
  1283.            d, i    signed decimal number
  1284.            o    unsigned octal number
  1285.            x    unsigned hexadecimal number
  1286.            u    unsigned decimal number
  1287.            c    input characters are placed in the indicated array
  1288.             up to the number specified in the field width; the
  1289.             default is 1, No '\0' os added. %c will convert the
  1290.             next character INCLUDING whitespace. To read the
  1291.             next non-whitespace character use %1s.
  1292.            s    a NULL terminated string
  1293.            e,f,g    float or double depending on the length specifier
  1294.            p    pointer (this is really the same as 'x' format
  1295.             on the Amiga).
  1296.            n    this is NOT supported yet, but should put the
  1297.             number of characters read so far into the
  1298.             argument.
  1299.            [...]    Null terminated string. Matches the longest
  1300.             non-empty string of input characters from the set
  1301.             of characters between brackets. The string is NULL
  1302.             terminated. []...] includes ']' in the set.
  1303.            [^...]    Null terminated string. Matches the longest
  1304.             non-empty string of input characters NOT from the
  1305.             set of characters between the brackets. The string
  1306.             in NULL terminated. [^]...] excludes ']' from the
  1307.             set.
  1308.            %    the '%' character, no assignment is made
  1309.  
  1310.  
  1311.         ...   - a variable number of arguments each of which is a pointer
  1312.           to a variable whose type is determined by the contents of
  1313.           the format string.
  1314.  
  1315.  
  1316. Return:     The number of items converted and assigned (stored) is
  1317.         returned. If an error occurs or if end of file is reached
  1318.         EOF is returned.
  1319.  
  1320. See Also:   fscanf, sscanf, printf
  1321. -------------------------------------------------------------------------
  1322. Name:        setbuf                 MACRO
  1323.  
  1324. Synopsis:   #include "stdio.h"
  1325.         void setbuf(fp,buf)
  1326.         FILE *fp;
  1327.         char *buf;
  1328.  
  1329. Function:   If buf is NULL buffering for this stream is eliminated,
  1330.         otherwise setbuf is the same as setvbuf(fp,buf,_IOFBF,BUFSIZ).
  1331.  
  1332. Arguments:  fp - stream file pointer
  1333.         buf - buffer to set
  1334.  
  1335. See Also:   setvbuf
  1336. -------------------------------------------------------------------------
  1337. Name:        setvbuf
  1338.  
  1339. Synopsis:   #include "stdio.h"
  1340.         long setvbuf(fp,buf,mode,size)
  1341.         FILE *fp;
  1342.         char *buf;
  1343.         long mode;
  1344.         size_t size;
  1345.  
  1346. Function:   Controls buffering for a stream by attaching an application
  1347.         specific buffer to the stream. If setvbuf is to be used then
  1348.         it must be called before any reading or writing is done on the
  1349.         stream.
  1350.  
  1351. Arguments:  fp - stream to add the buffer to
  1352.         buf - buffer to be used, if the buf argument is NULL then a
  1353.         buffer will be allocated for the stream using malloc that is the
  1354.         size specified by the size argument.
  1355.         mode - the mode of buffering, _IOFBF causes full buffering,
  1356.         _IOLBF should cause the buffering of text lines but is the same
  1357.         as _IOFBF for this implementation, _IONBF causes no buffering.
  1358.         size - size of the buffer provided or to be allocated.
  1359.  
  1360. Return:     Non-zero is returned for any error.
  1361.  
  1362. See Also:   setbuf
  1363. -------------------------------------------------------------------------
  1364. Name:        sprintf
  1365.  
  1366. Synopsis:   long sprintf(buf,fmt,...)
  1367.         char *buf;
  1368.         char *fmt;
  1369.  
  1370. Function:   Prints formatted output to a NULL terminated string under control
  1371.         of a format string.
  1372.  
  1373. Arguments:  buf - buffer to write the output to
  1374.         fmt - format string, see the documentation for the printf
  1375.         function for a description of the format string.
  1376.         ... - variable number of arguments under control of the
  1377.         format string.
  1378.  
  1379. Return:     The number of characters printed not including the NULL
  1380.         terminator.
  1381.  
  1382. See Also:   printf
  1383. -------------------------------------------------------------------------
  1384. Name:        sscanf
  1385.  
  1386. Synopsis:   long sscanf(str,fmt,...)
  1387.         char *str, *fmt;
  1388.  
  1389. Function:   Identical to scanf except that input characters are taken
  1390.         from the string str instead of stdin.
  1391.  
  1392. Arguments:  str - string to take input from
  1393.         fmt - format string, see documentation for the scanf function
  1394.         ... - variable number of arguments each of which is a pointer
  1395.  
  1396. Return:        The number of items converted and assigned (stored) is
  1397.            returned.
  1398.  
  1399. See Also:   scanf
  1400. -------------------------------------------------------------------------
  1401. Name:        stat
  1402.  
  1403. Synopsis:   #include "stat.h"
  1404.         long stat(fname,stat)
  1405.         char *fname;
  1406.         struct stat *stat;
  1407.  
  1408. Function:   Retrieves information about a file.
  1409.  
  1410. Arguments:  fname - name of the file to get the information about
  1411.         stat - structure to hold the results. The stat structure
  1412.         is described below;
  1413.  
  1414.         struct stat
  1415.         {
  1416.         unsigned short st_attr;
  1417.         long st_mtime;
  1418.         long st_size;
  1419.         };
  1420.  
  1421.         st_attr - file attributes which may be or'd together including:
  1422.           This Bit On       Means
  1423.            ST_DELETE   -  file is NOT deletable
  1424.            ST_EXECUTE  -  file is NOT executable
  1425.            ST_WRITE    -  file is NOT writeable
  1426.            ST_READ       -  file is NOT readable
  1427.            ST_ARCHIVE  -  file HAS been archived
  1428.         A warning about attribute bits; It is unsafe to assume that
  1429.         the other bits available in the attribute field will be un-used.
  1430.         This is because they may be used in future implementations of
  1431.         the Amiga operating system. This has already happened in the
  1432.         case of the ST_ARCHIVE bit.
  1433.  
  1434.         st_mtime - File modification date, in seconds since Jan, 1 1978
  1435.         st_size - of file in bytes
  1436.  
  1437. Return:     Non-zero is returned on error.
  1438.  
  1439. See Also:   stat_
  1440. -------------------------------------------------------------------------
  1441. Name:        stat_
  1442.  
  1443. Synopsis:   #include "stat.h"
  1444.         long stat(fname,stat)
  1445.         char *fname;
  1446.         struct stat *stat;
  1447.  
  1448. Function:   Retrieves information about a file. This is the newer version
  1449.         of the stat function. At version 3.0 of CClib.library the stat
  1450.         stucture was expanded by popular demand. The old version of
  1451.         stat() had to be left unchanged so that older programs will
  1452.         still work with newer versions of CClib.library. If you want
  1453.         you can modify stat.h by adding a macro that reads:
  1454.         #define stat(STAT) (_stat(STAT)) This will force the use of
  1455.         the newer stat function in a more transparent way.
  1456.  
  1457. Arguments:  fname - name of the file to get the information about
  1458.         stat - structure to hold the results. The extended stat
  1459.         structure is described below;
  1460.  
  1461.         struct stat
  1462.         {
  1463.         unsigned short st_attr;
  1464.         long st_mtime;
  1465.         long st_size;
  1466.  
  1467.         unsigned short st_mode;
  1468.         short st_nlink;
  1469.         time_t st_atime;
  1470.         time_t st_ctime;
  1471.         };
  1472.  
  1473.         st_attr -  see stat()
  1474.         st_mtime - see stat()
  1475.         st_size -  see stat()
  1476.         st_mode - file type bits
  1477.            S_IFMT - all file type bits
  1478.            S_IFDIR - a directory
  1479.            S_IFCHR - character special (used for interactive streams)
  1480.            S_IFBLK - block special (not used yet)
  1481.            S_IFREG - a reqular file (not interactive)
  1482.         st_atime - currently the same as st_mtime
  1483.         st_ctime - currently the same as st_mtime
  1484.  
  1485. Return:     Non-zero is returned on error.
  1486.  
  1487. See Also:   stat
  1488. -------------------------------------------------------------------------
  1489. Name:        tmpfile
  1490.  
  1491. Synopsis:   FILE *tmpfile()
  1492.  
  1493. Function:   Creates a temporary stream file.
  1494.  
  1495. Return:     A pointer to the new stream file, or NULL if an error occurs.
  1496.  
  1497. See Also:   tmpnam
  1498. -------------------------------------------------------------------------
  1499. Name:        tmpnam
  1500.  
  1501. Synopsis:   #include "stdio.h"
  1502.         char *tmpnam(buf)
  1503.         char *buf;
  1504.  
  1505. Function:   Creates a string that is not the name of an existing file.
  1506.  
  1507. Arguments:  buf - buffer to store the string in. This buffer must be at
  1508.         least L_tmpnam characters long. If this argument is NULL then
  1509.         a pointer to a "static" string is returned. This string may be
  1510.         over-written by other calls to cclib.library functions, so
  1511.         it is best to make a local copy of the string or immediatly
  1512.         open a file using this string.
  1513.  
  1514. Return:     buf, or a pointer to the "static" area of memory used by tmpnam.
  1515.         The "static" memory is really located in the task_UserData
  1516.         structure for your process.
  1517.  
  1518. See Also:   tmpfile
  1519. -------------------------------------------------------------------------
  1520. Name:        ungetc
  1521.  
  1522. Synopsis:   short ungetc(c,fp)
  1523.         short c;
  1524.         FILE *fp;
  1525.  
  1526. Function:   Pushes a single character 'c' back into a stream file where it
  1527.         will be read as the next character of input. c may not be EOF.
  1528.  
  1529. Arguments:  c - character to put
  1530.         fp - stream to push into
  1531.  
  1532. Return:     The character puched back is returned, EOF on error.
  1533.  
  1534. See Also:   getc
  1535. -------------------------------------------------------------------------
  1536. Name:        vfprintf
  1537.  
  1538. Synopsis:   long vfprintf(fp,fmt,arg)
  1539.         FILE *fp;
  1540.         char *fmt;
  1541.         va_list arg;
  1542.  
  1543. Function:   Works the same as fprintf except that the variable argument
  1544.         list has been replaced by arg, which is a pointer into the
  1545.         stack. vfprintf is useful for implementing your own functions
  1546.         that use variable argument lists. Here is an example of a
  1547.         function you could write using a variable number of arguments:
  1548.  
  1549.         yourfprintf(fp,ymsg,fmt,arg)
  1550.         FILE *fp;
  1551.         char *ymsg, *fmt;
  1552.         int arg;
  1553.         {
  1554.         fprintf(fp,"Your Message: %s ",ymsg);
  1555.         vfprintf(fp,fmt,(va_list)&arg);
  1556.         }
  1557.  
  1558.         You could call this function like this:
  1559.  
  1560.         yourfprintf(fp,"Oops","%s %d","The number was",10);
  1561.  
  1562.         And the output would be:
  1563.  
  1564.         Your Message: Oops The number was 10
  1565.  
  1566. Arguments:  fp - pointer to stream
  1567.         fmt - format string, see printf for a complete discription
  1568.         arg - pointer to the first argument in a variable argument list
  1569.  
  1570. Return:     The number of characters written is returned, or negative
  1571.         if an error occured.
  1572.  
  1573. See Also:   printf
  1574. -------------------------------------------------------------------------
  1575. Name:        vprintf
  1576.  
  1577. Synopsis:   long vprintf(fmt,arg)
  1578.         char *fmt;
  1579.         va_list arg;
  1580.  
  1581. Function:   Works the same as printf except that the variable argument
  1582.         list has been replaced by arg, which is a pointer into the
  1583.         stack. See vfprintf to find out how to use arg.
  1584.  
  1585. Arguments:  fmt - format string, see printf for a complete discription
  1586.         arg - pointer to the first argument in a variable argument list
  1587.  
  1588. Return:     The number of characters written is returned, or negative
  1589.         if an error occured.
  1590.  
  1591. See Also:   printf, vfprintf
  1592. -------------------------------------------------------------------------
  1593. Name:        vsprintf
  1594.  
  1595. Synopsis:   long vsprintf(buf,fmt,arg)
  1596.         char *buf, *fmt;
  1597.         va_list arg;
  1598.  
  1599. Function:   Works the same as sprintf except that the variable argument
  1600.         list has been replaced by arg, which is a pointer into the
  1601.         stack. See vfprintf to find out how to use arg.
  1602.  
  1603. Arguments:  fmt - format string, see printf for a complete discription
  1604.         arg - pointer to the first argument in a variable argument list
  1605.  
  1606. Return:     The number of characters written is returned, or negative
  1607.         if an error occured.
  1608.  
  1609. See Also:   printf, vfprintf
  1610. -------------------------------------------------------------------------
  1611.  
  1612. `` 3) NON-STANDARD AND LOW-LEVEL I/O FUNCTIONS
  1613.  
  1614.       Many of these functions have become widely used and must be supported
  1615.       even though they are not part of the ANSI standard C library.
  1616.  
  1617. -------------------------------------------------------------------------
  1618. Name:        access
  1619.  
  1620. Synopsis:   long access(fname,mode)
  1621.         char *fname;
  1622.         long mode;
  1623.  
  1624. Function:   Tells if a file or directory can be used for a particular
  1625.         purpose.
  1626.  
  1627. Arguments:  fname - the name of the file or directory.
  1628.         mode - asks for a certain type of access for the file or
  1629.         directory. mode = 4 (read access), 2 = write access, 1 =
  1630.         executable program, 0 = test for existance of the file.
  1631.  
  1632. Return:     Zero is returned if the requested accecc rights can be granted,
  1633.         otherwise -1 is retuned.
  1634.  
  1635. See Also:
  1636. -------------------------------------------------------------------------
  1637. Name:        close
  1638.  
  1639. Synopsis:   long close(fd)
  1640.         long fd;
  1641.  
  1642. Function:   Closes the specified low-level file.
  1643.  
  1644. Arguments:  fd - the descriptor for the low-level file obtained from
  1645.         open().
  1646.  
  1647. Return:     Zero is returned if the close was successful, -1 is returned if
  1648.         an error occured.
  1649.  
  1650. See Also:   open
  1651. -------------------------------------------------------------------------
  1652. Name:        creat
  1653.  
  1654. Synopsis:   long creat(fname,mode)
  1655.         char *fname;
  1656.         long mode;
  1657.  
  1658. Function:   creats a new file called 'fname'. This function is equivalent to:
  1659.         open(fname, O_WRONLY|O_TRUNC|O_CREAT, mode).
  1660.  
  1661. Arguments:  fname - the name of the file to create.
  1662.  
  1663. Return:     A file descriptor that can be used by the low-level I/O
  1664.         functions is returned. If an error occurs -1 is returned.
  1665.  
  1666. See Also:   open
  1667. -------------------------------------------------------------------------
  1668. Name:        fileno                 MACRO
  1669.  
  1670. Synopsis:   #include "stdio.h"
  1671.         long fileno(fp)
  1672.         FILE *fp;
  1673.  
  1674. Function:   Gets the low-level file descriptor for a stream file. This is
  1675.         most commonly used on non-bufferd streams such as stdin, stdout
  1676.         and stderr.
  1677.  
  1678. Arguments:  fp - stream file pointer
  1679.  
  1680. Return:     The file descrioptor for the stream file is returned.
  1681. -------------------------------------------------------------------------
  1682. Name:        isatty
  1683.  
  1684. Synopsis:   long isatty(fd)
  1685.         long fd;
  1686.  
  1687. Function:   Determines if a file descriptor is attached to an interactive
  1688.         device (virtual terminal) such as CON: or RAW:.
  1689.  
  1690. Arguments:  fd - file descriptor returned from open etc.
  1691.  
  1692. Return:     Non-zero is retuned if the file descriptor is an interactive
  1693.         device.
  1694. -------------------------------------------------------------------------
  1695. Name:        lseek
  1696.  
  1697. Synopsis:   long lseek(fd,offset,origin)
  1698.         long fd;
  1699.         long offset;
  1700.         unsigned long origin;
  1701.  
  1702. Function:   Sets the current position in a file.
  1703.  
  1704. Arguments:  fd - file descriptor for the file.
  1705.         offset - number of bytes to position the file from the origin.
  1706.         origin - 0 is beginning of the file, 1 is current position,
  1707.         2 is end of the file.
  1708.  
  1709. Return:     The new position in the file, or -1 on error.
  1710.  
  1711. See Also:   fseek
  1712. -------------------------------------------------------------------------
  1713. Name:        open
  1714.  
  1715. Synopsis:   #include "fcntl.h"
  1716.         long open(fname,flag,mode)
  1717.         char *fname;
  1718.         long flag;
  1719.         long mode;
  1720.  
  1721. Function:   Opens a file for low-level I/O.
  1722.  
  1723. Arguments:  fname - name of the file to open, may include path name as well.
  1724.         flag - specifies how the file is to be opened. The acceptable
  1725.         values (listed in fcntl.h) are listed below:
  1726.  
  1727.         O_RDONLY    -  open for reading only
  1728.         O_WRONLY    -  open for writing only
  1729.         O_RDWR    -  open for reading and writing
  1730.         O_CREAT    -  open the file after creating it
  1731.         O_TRUNC    -  remove contents then open the file
  1732.         O_EXCL    -  open fails if the file exists or'd with O_CREAT
  1733.         O_APPEND    -  open for appending only
  1734.  
  1735.         These flags may be or'd together to giver further meanings,
  1736.         for example:
  1737.  
  1738.         O_WRONLY|O_TRUNC - open for writing, nuke existing files
  1739.         O_RDWR|O_APPEND - open for reading and appending
  1740.  
  1741. Return:     fd - descriptor for the open file. This file descriptor is
  1742.         really a pointer to a FileDesc structure that is defined in
  1743.         iolib.h. The FileDesc structure is linked into the OpenFiles
  1744.         list attached to the task_UserData structure for your process.
  1745.         This is so that the library can close all of your open files
  1746.         before your process is terminated.
  1747.  
  1748. See Also:   close
  1749. -------------------------------------------------------------------------
  1750. Name:        read
  1751.  
  1752. Synopsis:   long read(fd,buf,size)
  1753.         long fd;
  1754.         char *buf;
  1755.         long size;
  1756.  
  1757. Function:   Reads bytes from a low-level file.
  1758.  
  1759. Arguments:  fd - file descriptor for the low-level file
  1760.         buf - buffer to store the data read from the file
  1761.         size - number of bytes to read
  1762.  
  1763. Return:     The number of bytes read is returned, -1L is returned on error
  1764.         or end of file. errno will be set on an error.
  1765.  
  1766. See Also:   open, write
  1767. -------------------------------------------------------------------------
  1768. Name:        unlink
  1769.  
  1770. Synopsis:   long unlink(fname)
  1771.         char *fname;
  1772.  
  1773. Function:   Deletes a file.
  1774.  
  1775. Arguments:  fname - name of the file to delete
  1776.  
  1777. Return:     Non-zero is returned on error.
  1778.  
  1779. See Also:   remove
  1780. -------------------------------------------------------------------------
  1781. Name:        write
  1782.  
  1783. Synopsis:   long write(fd,buf,n)
  1784.         long fd;
  1785.         char *buf;
  1786.         long n;
  1787.  
  1788. Function:   Low-level write to a file.
  1789.  
  1790. Arguments:  fd - low-level file descriptor obtained from open.
  1791.         buf - buffer to write
  1792.         n - number bytes to write
  1793.  
  1794. Return:     The number of bytes actually written, which may be less than n,
  1795.         is returned. -1 is returned on error.
  1796.  
  1797. See Also:   open, read
  1798. -------------------------------------------------------------------------
  1799.  
  1800. `` 4) CHARACTER TEST MACROS
  1801.  
  1802.       All of these macros are defined in the file "ctype.h". They access a
  1803.       static array that is located in cclib.library. At initialization time
  1804.       a pointer is taken to this static array and that pointer is used for
  1805.       the characher test macros. Because the array is located in shared
  1806.       memory it would be unwise to change it's contents.
  1807.  
  1808. -------------------------------------------------------------------------
  1809.    #include "ctype.h"
  1810.  
  1811.    All of the macros take a character or integral value as an argument and
  1812.    "return" an int that is non-zero if the test passes.
  1813.  
  1814.     isalpha(c)  -  a letter a-z or A-Z
  1815.     isupper(c)  -  upper case letter A-Z
  1816.     islower(c)  -  lower case letter a-z
  1817.     isdigit(c)  -  decimal digit 0-9
  1818.     isxdigit(c) -  hexadecimal digit 0-9 or a-f or A-F
  1819.     isalnum(c)  -  alphanumeric 0-9 or a-z or A-Z
  1820.     isspace(c)  -  space, formfeed, newline, carrige return, tab, v-tab
  1821.     ispunct(c)  -  printing character except space letter or digit
  1822.     iscntrl(c)  -  control character
  1823.     isprint(c)  -  printable character spece included
  1824.     isgraph(c)  -  printing character except space
  1825.     isascii(c)  -  member of the ASCII character set
  1826.  
  1827.     The following macros don't do character tests but character conversions
  1828.     and are commonly found in ctype.h. The "return" values are the converted
  1829.     character.
  1830.  
  1831.     toascii(c)  -  converts a character to ASCII
  1832.     tolower(c)  -  Function converts upper case letters to lower case.
  1833.     _tolower(c) -  Macro converts upper case letters to lower case. The
  1834.            letter must be upper case to start with or the conversion
  1835.            will be incorrect. This is faster than tolower().
  1836.     toupper(c)  -  Function converts lower case letters to upper case
  1837.     _toupper(c) -  Macro converts lower case letters to upper case The
  1838.            letter must be lower case to start with of the conversion
  1839.            will be incorrect. This is faster than touooer().
  1840.  
  1841.     NOTE: For versions 2.7 and above the toupper and tolower macros have
  1842.       been converted to functions.
  1843.  
  1844. -------------------------------------------------------------------------
  1845.  
  1846. `` 5) STRING FUNCTIONS
  1847.  
  1848.       These functions operate on NULL terminated strings. A NULL terminated
  1849.       string is an array of type char whose last element is '\0' (zero).
  1850.  
  1851. -------------------------------------------------------------------------
  1852. Name:        bcpl_strcpy
  1853.  
  1854. Synopsis:   char *bcpl_strcpy(str,bstr)
  1855.         char *str;
  1856.         BSTR *bstr;
  1857.  
  1858. Function:   Copies a BCPL string into a C string. BCPL is the language that
  1859.         much of Amiga DOS was written in, and strings are different.
  1860.         First BCPL adresses only point to long words so... ptr =
  1861.         bcpl_ptr << 2 and BCPL strings start with a character count and
  1862.         then the number of characters in the string. This function is
  1863.         provided so that you can access strings in Amiga DOS data
  1864.         structures.
  1865.  
  1866. Arguments:  str - pointer to the character array where the BCPL string is
  1867.         to be placed.
  1868.         bstr - BCPL pointer to a BCPL string.
  1869.  
  1870. Return:     str is returned.
  1871. -------------------------------------------------------------------------
  1872. Name:        index
  1873.  
  1874. Synopsis:   char *index(str,c)
  1875.         char *str;
  1876.         short c;
  1877.  
  1878. Function:   Finds the first occurence of a character in a string.
  1879.  
  1880. Arguments:  str - string to search
  1881.         c - character to search for
  1882.  
  1883. Return:     A pointer to the found character or NULL if the character
  1884.         was not found.
  1885.  
  1886. See Also:   strchr
  1887. -------------------------------------------------------------------------
  1888. Name:        rindex
  1889.  
  1890. Synopsis:   char *rindex(str,c)
  1891.         char *str;
  1892.         short c;
  1893.  
  1894.  
  1895. Function:   Finds the last occurence of a character in a string.
  1896.  
  1897. Arguments:  str - string to search
  1898.         c - character to search for
  1899.  
  1900. Return:     A pointer to the found character of NULL if the character
  1901.         was not found.
  1902.  
  1903. See Also:   strrchr
  1904. -------------------------------------------------------------------------
  1905. Name:        stpcrlf
  1906.  
  1907. Synopsis:   char *stpcrlf(str)
  1908.         char *str;
  1909.  
  1910. Function:   Strips carriage return of linefeed characters from a string.
  1911.         At the first encounter of a '\r' or '\n' character that
  1912.         character is replaced by a '\0' (NULL terminator.
  1913.  
  1914. Arguments:  str - string to strip
  1915.  
  1916. Return:     str is returned
  1917. -------------------------------------------------------------------------
  1918. Name:        strcat
  1919.  
  1920. Synopsis:   char *strcat(dest,source)
  1921.         char *dest;
  1922.         char *source;
  1923.  
  1924. Function:   Concatenates two strings. The destination string is assumed to
  1925.         be long enough to hold the concatenation.
  1926.  
  1927. Arguments:  dest - string to concatenate onto
  1928.         source - string to concatenate from
  1929.  
  1930. Return:     dest, the result, is returned
  1931.  
  1932. See Also:   strcpy
  1933. -------------------------------------------------------------------------
  1934. Name:        strchr
  1935.  
  1936. Synopsis:   char *strchr(str,c)
  1937.         char *str;
  1938.         short c;
  1939.  
  1940. Function:   Finds the first occurence of a character in a string.
  1941.  
  1942. Arguments:  str - string to search
  1943.         c - character to search for
  1944.  
  1945. Return:     A pointer to the found character or NULL if the character
  1946.         was not found.
  1947. -------------------------------------------------------------------------
  1948. Name:        strcmp
  1949.  
  1950. Synopsis:   short strcmp(str1,str2)
  1951.         char *str1, *str2;
  1952.  
  1953. Function:   Compares two strings.
  1954.  
  1955. Arguments:  str1, str2 - strings to compare
  1956.  
  1957. Return:     Negative is returned if str1 < str2, zero is returned if
  1958.         str1 == str2, positive is returned if str1 > str2.
  1959.  
  1960. See Also:   strncmp, strcmpa
  1961. -------------------------------------------------------------------------
  1962. Name:        strcmpa
  1963.  
  1964. Synopsis:   short strcmpa(str1,str2)
  1965.         char *str1, *str2;
  1966.  
  1967. Function:   Compares two strings, ignoring the case of the letters. For
  1968.         example: 0 == strcmpa("BOB","bob");
  1969.  
  1970. Arguments:  str1, str2 - strings to compare
  1971.  
  1972. Return:     Negative is returned if str1 < str2, zero is returned if
  1973.         str1 == str2, positive is returned if str1 > str2.
  1974.  
  1975. See Also:   strncmp, strcmp
  1976. -------------------------------------------------------------------------
  1977. Name:        strcpy
  1978.  
  1979. Synopsis:   char *strcpy(dest,source)
  1980.         char *dest, *source;
  1981.  
  1982. Function:   Copies one string onto another, the NULL terminator is copied.
  1983.  
  1984. Arguments:  dest - destination string
  1985.         source - source string
  1986.  
  1987. Return:     dest is returned
  1988.  
  1989. See Also:   strncpy
  1990. -------------------------------------------------------------------------
  1991. Name:        strcspn
  1992.  
  1993. Synopsis:   long strcspn(str,reject)
  1994.         char *str, *reject;
  1995.  
  1996. Function:   Finds the length of a string not consisting of characters
  1997.         in another string.
  1998.  
  1999. Arguments:  str - string to search
  2000.         reject - string of characters that str is searched for
  2001.  
  2002. Return:     Length of prefix of str consisting of characters NOT in reject.
  2003.  
  2004. See Also:   strspn
  2005. -------------------------------------------------------------------------
  2006. Name:        strerror
  2007.  
  2008. Synopsis:   char *strerror(err)
  2009.         long err;
  2010.  
  2011. Arguments:  err - an error code, usually the global variable errno
  2012.  
  2013. Return:     Returns a string corresponding to an error number.
  2014. -------------------------------------------------------------------------
  2015. Name:        strlen
  2016.  
  2017. Synopsis:   long strlen(str)
  2018.         char *str;
  2019.  
  2020. Function:   Computes the length of string.
  2021.  
  2022. Arguments:  str - string to compute the length of
  2023.  
  2024. Return:     Length of the string
  2025. -------------------------------------------------------------------------
  2026. Name:        strncat
  2027.  
  2028. Synopsis:   char *strncat(dest,source,n)
  2029.         char *dest, *source;
  2030.         long n;
  2031.  
  2032. Function:   Concatenates up to n characters onto dest from source.
  2033.  
  2034. Arguments:  dest - destination string
  2035.         source - source string
  2036.         n - maximum number of characters to concatenate
  2037.  
  2038. Return:     dest is returned.
  2039.  
  2040. See Also:   strcat
  2041. -------------------------------------------------------------------------
  2042. Name:        strncmp
  2043.  
  2044. Synopsis:   short strncmp(str1,str2,n)
  2045.         char *str1, *str2;
  2046.         long n;
  2047.  
  2048. Function:   Compare at most n characters of two strings.
  2049.  
  2050. Arguments:  str1, str2 - strings to compare
  2051.         n - maximum number of characters to copy
  2052.  
  2053. Return:     Negative is returned if str1 < str2, zero is returned if
  2054.         str1 == str2, positive is returned if str1 > str2.
  2055.  
  2056. See Also:   strcmpa, strcmp
  2057. -------------------------------------------------------------------------
  2058. Name:        strncpy
  2059.  
  2060. Synopsis:   char *strncpy(dest,source,n)
  2061.         char *dest, *source;
  2062.         long n;
  2063.  
  2064. Function:   Copies at most n characters from source to dest. The string is
  2065.         NULL terminated.
  2066.  
  2067. Arguments:  dest - destination string
  2068.         source - source string
  2069.         n - maximum number of characters to copy
  2070.  
  2071. Return:     dest is returned
  2072.  
  2073. See Also:   strcpy
  2074. -------------------------------------------------------------------------
  2075. Name:        strnrv
  2076.  
  2077. Synopsis:   char *strnrv(str,n)
  2078.         char *str;
  2079.         long n;
  2080.  
  2081. Function:   Reverses at most n characters of a string. For example
  2082.         strnrv("Hello World",5) => "olleH World".
  2083.  
  2084. Arguments:  str - string to reverse
  2085.         n - maximum length of the string to reverse
  2086.  
  2087. Return:     str is returned
  2088.  
  2089. See Also:   strrv
  2090. -------------------------------------------------------------------------
  2091. Name:        strpbrk
  2092.  
  2093. Synopsis:   char *strpbrk(str,search)
  2094.         char *str, *search;
  2095.  
  2096. Function:   Searches for one of a string of characters in a string.
  2097.  
  2098. Arguments:  str - string to search
  2099.         search - string of characters to search for
  2100.  
  2101. Return:     A pointer to the first character of str belonging to search is
  2102.         returned, if no match is found NULL is returned.
  2103.  
  2104. See Also:   strspn
  2105. -------------------------------------------------------------------------
  2106. Name:        strrchr
  2107.  
  2108. Synopsis:   char *strrchr(str,c)
  2109.         char *str;
  2110.         short c;
  2111.  
  2112. Function:   Finds the last occurence of a character in a string.
  2113.  
  2114. Arguments:  str - string to search
  2115.         c - string to search for
  2116.  
  2117. Return:     A pointer to the last occurence of c in str is returned, if
  2118.         no match is found NULL is returned.
  2119.  
  2120. See Also:   strchr
  2121. -------------------------------------------------------------------------
  2122. Name:        strrv
  2123.  
  2124. Synopsis:   char *strrv(str)
  2125.         char *str;
  2126.  
  2127. Function:   Reverses the characters in a string. For example:
  2128.         strrv("Kasak") => "kasaK"
  2129.  
  2130. Arguments:  str - string to reverse
  2131.  
  2132. Return:     str is returned
  2133.  
  2134. See Also:   strnrv
  2135. -------------------------------------------------------------------------
  2136. Name:        strspn
  2137.  
  2138. Synopsis:   long strspn(str,search)
  2139.         char *str, *search;
  2140.  
  2141. Function:   Finds the length of a string consisting of characters
  2142.         in another string.
  2143.  
  2144. Arguments:  str - string to search
  2145.         search - string of characters that str is searched for
  2146.  
  2147. Return:     Length of prefix of str consisting of characters in search.
  2148.  
  2149. See Also:   strcspn
  2150. -------------------------------------------------------------------------
  2151. Name:        strstr
  2152.  
  2153. Synopsis:   char *strstr(str,search)
  2154.         char *str;
  2155.         char *search;
  2156.  
  2157. Function:   Finds a string in another string.
  2158.  
  2159. Arguments:  str - string to search
  2160.         search - string to search for
  2161.  
  2162. Return:     Returns a pointer to the string in str that matches search,
  2163.         if the string is not found NULL is returned.
  2164. -------------------------------------------------------------------------
  2165. Name:        strtok
  2166.  
  2167. Synopsis:   char *strtok(str,delim)
  2168.         char *str;
  2169.         char *delim;
  2170.  
  2171. Function:   A sequence of calls splits the string str into tokens, each
  2172.         delimited by a character in delim. The first call to strtok
  2173.         must be with a non-NULL str argument. The argument is remembered
  2174.         by strtok for subsequent calls. The first token is found by
  2175.         searching for characters not in delim. When a token is found
  2176.         the character just after the token is over-written with a NULL
  2177.         and a pointer to the token is returned. Each subsequent call to
  2178.         strtok, indicated by a NULL str argument, will return the next
  2179.         token in str. NULL is returned when there are no further tokens
  2180.         in str.
  2181.  
  2182. Arguments:  str - string to split tokens out of
  2183.         delim - string consisting of legal delimiters
  2184.  
  2185. Return:     Tokens split out from the string are returned, or NULL when
  2186.         there are no more tokens in the string.
  2187. -------------------------------------------------------------------------
  2188. Name:        strupr
  2189.  
  2190. Synopsis:   char *strupr(str)
  2191.         char *str;
  2192.  
  2193. Function:   Converts a string to all upper case letters.
  2194.  
  2195. Arguments:  str - string to convert
  2196.  
  2197. Return:     str is returned
  2198. -------------------------------------------------------------------------
  2199.  
  2200. ``    6) MEMORY OPERATION FUNCTIONS
  2201.  
  2202.      These functiuons have become common for most implementations of
  2203.      the C library. They all operate on blocks of memory of a certain
  2204.      size instead of null terminated strings as with the string
  2205.      functions.
  2206.  
  2207. -------------------------------------------------------------------------
  2208. Name:        bcpm
  2209.  
  2210. Synopsis:   short bcmp(ptr1,ptr2,size)
  2211.         void *ptr1, *ptr2;
  2212.         long size;
  2213.  
  2214. Function:   Compares two blocks of memory.
  2215.  
  2216. Arguments:  ptr1, ptr2 - pointers to two blocks of memory to compare
  2217.         size - maximum number of bytes to compare
  2218.  
  2219. Return:     Negative is returned if ptr1 > ptr2, zero is returned if
  2220.         ptr1 == ptr2, positive is returned if ptr1 < ptr2.
  2221.  
  2222. See Also:   memcmp
  2223. -------------------------------------------------------------------------
  2224. Name:        bcopy
  2225.  
  2226. Synopsis:   void bcopy(source,dest,size)
  2227.         void *source, *dest;
  2228.         long size;
  2229.  
  2230. Function:   Copies a block of memory making sure that overlapping blocks
  2231.         are copied correctly.
  2232.  
  2233. Arguments:  source - pointer to source block of memory
  2234.         dest - pointer to destination block of memory
  2235.         size - number of bytes to copy
  2236.  
  2237. See Also:   memcpy
  2238. -------------------------------------------------------------------------
  2239. Name:        bzero
  2240.  
  2241. Synopsis:   void bzero(ptr,size)
  2242.         void *ptr;
  2243.         long size;
  2244.  
  2245. Function:   Sets a block of memory to all zeros.
  2246.  
  2247. Arguments:  ptr - pointer to block of memory
  2248.         size - number of bytes to set to zero
  2249.  
  2250. See Also:   memset
  2251. -------------------------------------------------------------------------
  2252. Name:        memccpy
  2253.  
  2254. Synopsis:   void *memccpy(dest,source,stop,size)
  2255.         void *dest, *source;
  2256.         unsigned short stop;
  2257.         long size;
  2258.  
  2259. Function:   Copies a block of memory until a certain byte is reached or
  2260.         until the maximum number of bytes is reached.
  2261.  
  2262. Arguments:  dest - pointer to block of memory to copy to
  2263.         source - pointer to block of memory to copy from
  2264.         stop - if the stop character is encoutered then the copy
  2265.         operation is stopped after the stop character is copied to
  2266.         the destination block.
  2267.         size - maximum number of bytes to copy
  2268.  
  2269. Return:     If the stop character is encountered then a pointer to the
  2270.         next byte after the stop character is returned, if the stop
  2271.         character is never encounterd then NULL is returned.
  2272. -------------------------------------------------------------------------
  2273. Name:        memchr
  2274.  
  2275. Synopsis:   void *memchr(ptr,chr,size)
  2276.         void *ptr;
  2277.         unsigned short chr;
  2278.         long size;
  2279.  
  2280. Function:   Finds a character in a block of memory.
  2281.  
  2282. Arguments:  ptr - block of memory to search
  2283.         chr - character to search for
  2284.         size - maximum number of bytes to search
  2285.  
  2286. Return:     If the character is found then a pointer to it is returned.
  2287.         NULL is returned if the character is not found.
  2288. -------------------------------------------------------------------------
  2289. Synopsis:   short memcmp(ptr1,ptr2,size)
  2290.         void *ptr1, *ptr2;
  2291.         long size;
  2292.  
  2293. Function:   Compares two blocks of memory.
  2294.  
  2295. Arguments:  ptr1, ptr2 - pointers to two blocks of memory to compare
  2296.         size - maximum number of bytes to compare
  2297.  
  2298. Return:     Negative is returned if ptr1 < ptr2, zero is returned if
  2299.         ptr1 == ptr2, positive is returned if ptr1 > ptr2.
  2300. -------------------------------------------------------------------------
  2301. Name:        memcpy
  2302.  
  2303. Synopsis:   void *memcpy(dest,source,size)
  2304.         void *dest, *source;
  2305.         long size;
  2306.  
  2307. Function:   Copies a block of memory making sure that overlapping blocks
  2308.         are copied correctly.
  2309.  
  2310. Arguments:  dest - pointer to destination block of memory
  2311.         source - pointer to source block of memory
  2312.         size - number of bytes to copy
  2313.  
  2314. Return:     dest is returned
  2315. -------------------------------------------------------------------------
  2316. Name:        memmove                 MACRO
  2317.  
  2318. Synopsis:   #include "string.h"
  2319.         void *memmove(dest,source,size)
  2320.         void *dest, *source;
  2321.         long size;
  2322.  
  2323. Function:   Copies a block of memory making sure that overlapping blocks
  2324.         are copied correctly.
  2325.  
  2326. Arguments:  dest - pointer to destination block of memory
  2327.         source - pointer to source block of memory
  2328.         size - number of bytes to copy
  2329.  
  2330. Return:     dest is returned
  2331. -------------------------------------------------------------------------
  2332. Name:        memset
  2333.  
  2334. Synopsis:   void *memset(ptr,chr,long)
  2335.         void *ptr;
  2336.         unsigned short chr;
  2337.         long size;
  2338.  
  2339. Function:   Sets all bytes in a block of memory to a single value.
  2340.  
  2341. Arguments:  ptr - pointer to a block of memory
  2342.         chr - value to set each byte to
  2343.         size - number of bytes to set
  2344.  
  2345. Return:     ptr is returned
  2346. -------------------------------------------------------------------------
  2347. Name:        memswap
  2348.  
  2349. Synopsis:   void memswap(ptr1,ptr2,size)
  2350.         void *ptr1, *ptr2;
  2351.         long size;
  2352.  
  2353. Function:   Swaps the contents of two blocks of memory.
  2354.  
  2355. Arguments:  ptr1, ptr2 - blocks of memory to swap
  2356.         size - number of bytes to swap
  2357. -------------------------------------------------------------------------
  2358.  
  2359. ``    7) FORMAT CONVERSION FUNCTIONS
  2360.  
  2361.      Conversions from numbers to ASCII characters and back.
  2362.  
  2363. -------------------------------------------------------------------------
  2364. Name:        atof
  2365.  
  2366. Synopsis:   double atof(str)
  2367.         char *str;
  2368.  
  2369. Function:   Converts a character string representing a floating point number
  2370.         into an IEEE format double precision floating pointer number.
  2371.  
  2372. Arguments:  str - string to convert
  2373.  
  2374. Return:     A floating point number, zero is returned if no conversion can
  2375.         be made.
  2376. -------------------------------------------------------------------------
  2377. Name:        atoi
  2378.  
  2379. Synopsis:   short atoi(str)
  2380.         char *str;
  2381.  
  2382. Function:   Converts a string representing an integer into a short integer.
  2383.  
  2384. Arguments:  str - string to convert
  2385.  
  2386. Return:     A short integer, zero is returned if no conversion can be made.
  2387.  
  2388. See Also:   stoa
  2389. -------------------------------------------------------------------------
  2390. Name:        atol
  2391.  
  2392. Synopsis:   long atol(str)
  2393.         char *str;
  2394.  
  2395. Function:   Converts a string representing an integer into a long integer.
  2396.  
  2397. Arguments:  str - string to convert
  2398.  
  2399. Return:     A long integer, zero is returned if no conversion can be made.
  2400.  
  2401. See Also:   ltoa
  2402. -------------------------------------------------------------------------
  2403. Name:        ltoa
  2404.  
  2405. Synopsis:   void ltoa(n,str)
  2406.         long n;
  2407.         char *str;
  2408.  
  2409. Function:   Converts a long integer into a string.
  2410.  
  2411. Arguments:  n - number to convert
  2412.         str - string to store the result in
  2413.  
  2414. See Also:   atol
  2415. -------------------------------------------------------------------------
  2416. Name:        stoa
  2417.  
  2418. Synopsis:   void stoa(n,str)
  2419.         short n;
  2420.         char *str;
  2421.  
  2422. Function:   Converts a short integer into a string.
  2423.  
  2424. Arguments:  n - number to convert
  2425.         str - string to store the result in
  2426.  
  2427. See Also:   atoi
  2428. -------------------------------------------------------------------------
  2429.  
  2430. ``    8) MEMORY ALLOCATION FUNCTIONS
  2431.  
  2432.       These functions include the standard heap managment functions as well
  2433.       as lower level functions that were used to implement the heap
  2434.       managment system. When the program that has allocated memory through
  2435.       the functions in this section terminates execution through the exit
  2436.       function all memory allocated from Amiga DOS is returned to the
  2437.       system. All of the heap managment functions will try to allocate
  2438.       memory first from FAST memory and then from CHIP RAM. To allocate
  2439.       memory that is guaranteed to be CHIP RAM (accesable by the Amiga
  2440.       custom chips) you can use the _alloc() function. The heap manager
  2441.       operates by allocating blocks of memory from Amiga DOS in large
  2442.       chunks, then it breaks these blocks up into the sizes that are
  2443.       requested through heap memory allocation functions. The minimum size
  2444.       of the blocks allocated from Amiga DOS can be controlled directly by
  2445.       declaring a global long integer called blocksize and setting it to
  2446.       some value. The default value for blocksize is 256 blocks (2K bytes),
  2447.       in increments of 8 bytes. Each time the heap manager allocates memory
  2448.       from Amiga DOS the blocksize variable is checked, which makes it
  2449.       possible to change the variable on the fly.
  2450.  
  2451. -------------------------------------------------------------------------
  2452. Name:        be_free
  2453.  
  2454. Synopsis:   void be_free(ptr,size)
  2455.         void *ptr;
  2456.         long size;
  2457.  
  2458. Function:   Makes static memory available to malloc and calloc. If you have
  2459.         static data structures that will NEVER be used as such again
  2460.         then you can add them to the free memory list with this
  2461.         function. If you write into the data pointed to by ptr after
  2462.         you have added that block to the free memory list then you
  2463.         stand a good chance of corrupting the free memory list. When the
  2464.         free memory list for your task is corrupt the system will
  2465.         when you try to access it with calloc, malloc, or free.
  2466.  
  2467.  
  2468. Arguments:  ptr - pointer to the block of memory to give to the heap
  2469.         manager.
  2470.         size - size of the block of memory
  2471. -------------------------------------------------------------------------
  2472. Name:        calloc
  2473.  
  2474. Synopsis:   void *calloc(nobj,size)
  2475.         unsigned long nobj, size;
  2476.  
  2477. Function:   Allocates and sets to zero an area of memory that is at least
  2478.         nobj * size bytes. This is a standard C function.
  2479.  
  2480. Arguments:  nobj - number of objects to allocate
  2481.         size - size of each object to allocate
  2482.  
  2483. Return:     A pointer to the newly allocated block of memory. NULL is
  2484.         returned when the block of memory can't be provided.
  2485.  
  2486. See Also:   malloc
  2487. -------------------------------------------------------------------------
  2488. Name:        free
  2489.  
  2490. Synopsis:   free(ptr)
  2491.         void *ptr;
  2492.  
  2493. Function:   Returns a block of memory allocated through malloc, calloc or
  2494.         realloc to the heap manager for future use. This is a
  2495.         standard C function.
  2496.  
  2497. Arguments:  ptr - pointer to the block of memory obtained from malloc, calloc
  2498.         or realloc.
  2499.  
  2500. See Also:   be_free
  2501. -------------------------------------------------------------------------
  2502. Name:        freeall
  2503.  
  2504. Synopsis:   freeall()
  2505.  
  2506. Function:   Returns ALL of the memory allocated by any of the functions
  2507.         in this section to the system and re-initializes the free
  2508.         memory list for the heap manager. This will also free all of
  2509.         the memory used by any files that may be open. Normally this
  2510.         function is only called when the program has called the exit
  2511.         function.
  2512. -------------------------------------------------------------------------
  2513. Name:        heap_alloc
  2514.  
  2515. Synopsis:   void *heap_alloc(size)
  2516.         long size;
  2517.  
  2518. Function:   Allocates memory from the heap manager. This function is
  2519.         used internally to implement malloc and calloc.
  2520.  
  2521. Arguments:  size - size in bytes of the requested block of memory
  2522.  
  2523. Return:     A pointer to the newly allocated block of memory. NULL is
  2524.         returned when the block of memory can't be provided.
  2525.  
  2526. See Also:   malloc, calloc
  2527. -------------------------------------------------------------------------
  2528. Name:        heap_free
  2529.  
  2530. Synopsis:   void heap_free(ptr)
  2531.         void *ptr;
  2532.  
  2533. Function:   Returns memory to the free list of the heap manager. This
  2534.         function is used internally to implement free().
  2535.  
  2536. Arguments:  ptr - pointer to a block of memory obtained from heap_alloc.
  2537.  
  2538. See Also:   free
  2539. -------------------------------------------------------------------------
  2540. Name:        malloc
  2541.  
  2542. Synopsis:   void *malloc(size)
  2543.         unsigned long size;
  2544.  
  2545. Function:   Allocates memory from the heap manager that is at least
  2546.         "size" bytes. This is a standard C function.
  2547.  
  2548. Arguments:  size - size of the requested block of memory
  2549.  
  2550. Return:     A pointer to the newly allocated block of memory. NULL is
  2551.         returned when the block of memory can't be provided.
  2552.  
  2553. See Also:   free
  2554. -------------------------------------------------------------------------
  2555. Name:        malloc_size
  2556.  
  2557. Synopsis:   unsigned long malloc_size(ptr)
  2558.         void *ptr;
  2559.  
  2560. Function:   Computes the number of bytes in an allocated block of memory
  2561.         that was obtained from malloc, calloc, realloc, or heap_alloc.
  2562.         The size is rounded up to the nearest eight bytes.
  2563.  
  2564. Arguments:  ptr - a pointer to the allocated block of memory.
  2565.  
  2566. Return:     The size of the allocated block is returned.
  2567. -------------------------------------------------------------------------
  2568. Name:        realloc
  2569.  
  2570. Synopsis:   void *realloc(ptr,newsize)
  2571.         void *ptr;
  2572.         unsigned long newsize;
  2573.  
  2574. Function:   Changes the size of a block block of memory. The contents will
  2575.         be un-changed up to the minimum of the old and new sizes. The
  2576.         block of memory can be freed using free() prior to a call to
  2577.         realloc so long as no intervening calls to any of the heap
  2578.         managment functions is made. In order to make enough space
  2579.         for a larger block of memory is may be necessary to move the
  2580.         block. This is a standard C function.
  2581.  
  2582. Arguments:  ptr - pointer to the block of memory to change the size of
  2583.  
  2584. Return:     A pointer to the new block of memory is returned or NULL if the
  2585.         request can't be satisfied.
  2586.  
  2587. See Also:   free
  2588. -------------------------------------------------------------------------
  2589. Name:        sbrk
  2590.  
  2591. Synopsis:   void *sbrk(size)
  2592.         unsigned long size;
  2593.  
  2594. Function:   Allocates memory through Amiga DOS and attaches the block
  2595.         of memory to the allocated memory list for the current task.
  2596.         This is a lower level function than the heap managment
  2597.         functions. The sbrk function has become a standard part of many
  2598.         C libraries.
  2599.  
  2600. Arguments:  size - size in bytes of the requested block of memory
  2601.  
  2602. Return:     A pointer to the newly allocated block of memory is returned, or
  2603.         -1L if the request can't be satisfied.
  2604. -------------------------------------------------------------------------
  2605. Name:        _alloc
  2606.  
  2607. Synopsis:   void _alloc(ud,size,requirements)
  2608.         task_UserData *ud;
  2609.         long size;
  2610.         long requirements;
  2611.  
  2612. Function:   Allocates memory from Amiga DOS and links it into the allocated
  2613.         memory list for your task. This is the lowest level of memory
  2614.         allocation available through this library and is used to
  2615.         implement all of the other memory allocation functions. The
  2616.         task_UserData pointer can be obtained by a call to GetSTDIO.
  2617.  
  2618. Arguments:  ud - pointer to the task_UserData structure for your task
  2619.         size - size in bytes of the memory to be allocated
  2620.         requirements - memory requirements as described in
  2621.         exec/memory.h, 0L being just any old block of memory.
  2622.         The requirements are used directly in a call to the Amiga
  2623.         AllocMem function.
  2624.  
  2625. Return:     A pointer to the new block of memory is returned or NULL if the
  2626.         request can't be satisfied.
  2627.  
  2628. See Also:   _fre
  2629. -------------------------------------------------------------------------
  2630. Name:        _fre
  2631.  
  2632. Synopsis:   void _fre(ud,ptr)
  2633.         task_UserData *ud;
  2634.         void *ptr;
  2635.  
  2636. Function:   Frees a block of memory allocated by _alloc or sbrk.
  2637.         The task_UserData pointer can be obtained by a call to GetSTDIO.
  2638.  
  2639. Arguments:  ud - pointer to the task_UserData structure for your task
  2640.         ptr - pointer to a block of memory obtained from _alloc or sbrk.
  2641. -------------------------------------------------------------------------
  2642. Name:        _freall
  2643.  
  2644. Synopsis:   void _freall(ud)
  2645.         task_UserData *ud;
  2646.  
  2647. Function:   Returns all memory allocated by through any of the functions
  2648.         in this section to Amiga DOS, but does NOT re-initialize the
  2649.         free list used by the heap manager. The task_UserData pointer
  2650.         can be obtained by a call to GetSTDIO.
  2651.  
  2652. Arguments:  ud - pointer to the task_UserData structure for your task
  2653. -------------------------------------------------------------------------
  2654.  
  2655. ``    9) LINKED LIST FUNCTIONS
  2656.  
  2657.       Linked lists are used internally in CClib.library and since the
  2658.       linked list functions are already in the library they were made
  2659.       public. The structure definitions for linked lists and nodes are in
  2660.       stdlist.h.
  2661.  
  2662. -------------------------------------------------------------------------
  2663. Name:        add_head
  2664.  
  2665. Synopsis:   void *add_head(l,size)
  2666.         _list *l;
  2667.         long size;
  2668.  
  2669. Function:   Allocates and clears to zero memory from the heap manager for
  2670.         a _node structure plus "size" bytes. The node is then added
  2671.         to the beginning of the linked list.
  2672.  
  2673. Arguments:  l - linked list to add to
  2674.         size - size in bytes of the data for this node
  2675.  
  2676. Return:     A pointer to the data for this node is returned, or NULL if
  2677.         there is not enough memory.
  2678.  
  2679. See Also:   remv_node
  2680. -------------------------------------------------------------------------
  2681. Name:        add_tail
  2682.  
  2683. Synopsis:   void *add_tail(l,size)
  2684.         _list *l;
  2685.         long size;
  2686.  
  2687. Function:   Allocates and clears to zero memory from the heap manager for
  2688.         a _node structure plus "size" bytes. The node is then added
  2689.         to the end of the linked list.
  2690.  
  2691. Arguments:  l - linked list to add to
  2692.         size - size in bytes of the data for this node
  2693.  
  2694. Return:     A pointer to the data for this node is returned, or NULL if
  2695.         there is not enough memory.
  2696.  
  2697. See Also:   remv_node
  2698. -------------------------------------------------------------------------
  2699. Name:        inst_node
  2700.  
  2701. Synopsis:   _node *inst_node(size)
  2702.         long size;
  2703.  
  2704. Function:   Allocates and clears to zero memory from the heap manager for
  2705.         a _node structure plus "size" bytes. This function is used
  2706.         by all of the functions that create a new node.
  2707.  
  2708. Arguments:  size - size in bytes of the data for this node
  2709.  
  2710. Return:     A pointer to the new node is returned, or NULL if there isn't
  2711.         enough memory.
  2712. -------------------------------------------------------------------------
  2713. Name:        put_head
  2714.  
  2715. Synopsis:   void put_head(l,n)
  2716.         _list *l;
  2717.         _node *n;
  2718.  
  2719. Function:   Adds a node at the beginning of a linked list.
  2720.  
  2721. Arguments:  l - linked list to add to
  2722.         n - node to add to the linked list
  2723.  
  2724. See Also:   remv_head
  2725. -------------------------------------------------------------------------
  2726. Name:        put_tail
  2727.  
  2728. Synopsis:   void put_tail(l,n)
  2729.         _list *l;
  2730.         _node *n;
  2731.  
  2732. Function:   Adds a node at the end of a linked list.
  2733.  
  2734. Arguments:  l - linked list to add to
  2735.         n - node to add to the linked list
  2736.  
  2737. See Also:   remv_tail
  2738. -------------------------------------------------------------------------
  2739. Name:        remv_head
  2740.  
  2741. Synopsis:   void *remv_head(l,data)
  2742.         _list *l;
  2743.         void **data;
  2744.  
  2745. Function:   Removes a node from the beginning of a linked list and gives
  2746.         a pointer to the data for that node. The memory for the
  2747.         node is not freed.
  2748.  
  2749. Arguments:  l - linked list to remove from
  2750.         data - pointer to a memory location where a pointer to the
  2751.         data for the node will be stored after removing the node
  2752.         from the beginning of the list
  2753.  
  2754. Return:     A pointer to the block of memory that was allocated for the
  2755.         node and its data is returned, or NULL if there are no more
  2756.         nodes on the list. This memory should be freed using the
  2757.         free function. For example:
  2758.         _list *l;
  2759.         char *data, *ptr;
  2760.         .
  2761.         .
  2762.         .
  2763.         if( ptr = remv_head(l,&data) )
  2764.            free(ptr)
  2765.  
  2766. See Also:   add_head
  2767. -------------------------------------------------------------------------
  2768. Name:        remv_list
  2769.  
  2770. Synopsis:   void remv_list(l)
  2771.         _list *l;
  2772.  
  2773. Function:   Frees all memory associated with a linked list by calling
  2774.         free for every node in the list and then for the list
  2775.         header.
  2776.  
  2777. Arguments:  l - linked list to free, it is assumed that all of the nodes
  2778.         on the list and the list header itself are allocated using
  2779.         heap_alloc, malloc, calloc, or realloc.
  2780. -------------------------------------------------------------------------
  2781. Name:        remv_node
  2782.  
  2783. Synopsis:   void *remv_node(l,data)
  2784.         _list *l;
  2785.         void *data;
  2786.  
  2787. Function:   Removes a node from a list by first scanning the list for the
  2788.         data associated with the node and then removing the node from
  2789.         the list.
  2790.  
  2791. Arguments:  l - pointer to the list to remove the node from.
  2792.         data - pointer to the data associated with the node to be
  2793.         removed
  2794.  
  2795. Return:     A pointer to the memory allocated for the node and it's data
  2796.         is returned, NULL is returned if the node with the specified
  2797.         data can't be found on the list. The pointer can then be used
  2798.         to free the node and it's data, for example:
  2799.         if( ptr = remv_node(l,data) )
  2800.            free(ptr);
  2801. -------------------------------------------------------------------------
  2802. Name:        remv_tail
  2803.  
  2804. Synopsis:   void *remv_tail(l,data)
  2805.         _list *l;
  2806.         void **data;
  2807.  
  2808. Function:   Removes a node from the end of a linked list and gives
  2809.         a pointer to the data for that node. The memory for the
  2810.         node is not freed.
  2811.  
  2812. Arguments:  l - linked list to remove from
  2813.         data - pointer to a memory location where a pointer to the
  2814.         data for the node will be stored after removing the node
  2815.         from the end of the list
  2816.  
  2817. Return:     A pointer to the block of memory that was allocated for the
  2818.         node and its data is returned, or NULL if there are no more
  2819.         nodes on the list. This memory should be freed using the
  2820.         free function.
  2821.  
  2822. See Also:   add_tail
  2823. -------------------------------------------------------------------------
  2824. Name:        r_node
  2825.  
  2826. Synopsis:   void *r_node(l,n,data)
  2827.         _list *l;
  2828.         _node *n;
  2829.         void **data;
  2830.  
  2831. Function:   Removes a specific node from a linked list and gives a pointer
  2832.         to the data for the node. Memory for the node is not freed.
  2833.  
  2834. Arguments:  l - linked list to remove the node from
  2835.         n - node to remove from the list
  2836.         data - a pointer to the data for this node is stored here
  2837.  
  2838. Return:     n is returned, or NULL if the list is empty
  2839.  
  2840. See Also:   remv_node
  2841. -------------------------------------------------------------------------
  2842.  
  2843. ``    10) SORTING FUNCTIONS
  2844.  
  2845.       These are all modifications of C. A. R. Hoare's quicksort algorithm.
  2846.       Two of the functions are written in C and a third is written in 68000
  2847.       assembler for speed.
  2848.  
  2849. -------------------------------------------------------------------------
  2850. Name:        qsort
  2851.  
  2852. Synopsis:   void qsort(base,n,size,cmp)
  2853.         void *base;
  2854.         unsigned long n, size;
  2855.         short (*cmp)();
  2856.  
  2857. Function:   Sorts into ascending order an array base[0]...base[n-1] of
  2858.         objects of size "size".
  2859.  
  2860. Arguments:  base - pointer to the first element in the array of elements
  2861.         tp sort.
  2862.         n - number of elements to sort
  2863.         size - size of each element of the array
  2864.         cmp - pointer to comparison function. The comparison function
  2865.         is passed a pointer to two elements of the array and returns
  2866.         zero if the two elements are equivalent, negative must be
  2867.         returned if the first element is less than the second and
  2868.         and positive must be returned if the first element is greater
  2869.         than the second. To sort in the opposite order negative is
  2870.         returned if the first element is greater than the second and
  2871.         positive is returned if the first element is less than the
  2872.         second. Here is an example of a comparison function that
  2873.         will sort strings in descending order:
  2874.  
  2875.         short cmp(str1,str2)
  2876.         char *str1, *str2;
  2877.         {
  2878.         return( strcmp(str2,str1) );
  2879.         }
  2880.  
  2881. -------------------------------------------------------------------------
  2882. Name:        quicksort
  2883.  
  2884. Synopsis:   void quicksort(n,comp,swap,ptr)
  2885.         unsigned long n;
  2886.         short (*comp)();
  2887.         void (*swap)();
  2888.         void *ptr;
  2889.  
  2890. Function:   The quicksort function uses the same sorting algorithm as
  2891.         qsort but it is designed to sort anything, not just arrays
  2892.         in memory.
  2893.  
  2894. Arguments:  n - number of elements to sort.
  2895.         comp - comparison function. The comparison function is passed
  2896.         the index of the two elements to compare and an auxilery
  2897.         pointer that you provide. It returns zero if the two elements
  2898.         are equivalent, negative must be returned if the first element
  2899.         is less than the second and and positive must be returned if
  2900.         the first element is greater than the second. To sort in the
  2901.         opposite order negative is returned if the first element is
  2902.         greater than the second and positive is returned if the first
  2903.         element is less than the second.
  2904.         swap - swaps two elements. The swap function is passed the
  2905.         index of the two elements to swap and an auxilery pointer you
  2906.         provide.
  2907.         ptr - auxilery pointer, can point to anything. This variable
  2908.         is passed to the comp and swap functions in order to facilitate
  2909.         the writing of re-entrant code.
  2910.  
  2911. -------------------------------------------------------------------------
  2912. Name:        vquicksort
  2913.  
  2914. Synopsis:   void vquicksort(n,comp,swap)
  2915.         unsigned short n;
  2916.         short (*comp();
  2917.         void (*swap)();
  2918.  
  2919. Function:   The vquicksort function is much the same as the quicksort
  2920.         function except that only up to 64K elements can be sorted
  2921.         and there is no auxilery argument pointer. Vquicksort is
  2922.         written in 100% hand optomized assembly language, hence it's
  2923.         name, very quicksort.
  2924.  
  2925. Arguments:  n - number of elements to sort.
  2926.         comp - comparison function. The comparison function is passed
  2927.         the index of the two elements to compare. It returns zero if
  2928.         the two elements are equivalent, negative must be returned if
  2929.         the first element is less than the second and positive must be
  2930.         returned if the first element is greater than the second. To
  2931.         sort in the opposite order negative is returned if the first
  2932.         element is greater than the second and positive is returned if
  2933.         the first element is less than the second. swap - swaps two
  2934.         elements. The swap function is passed the index of the two
  2935.         elements to swap.
  2936.  
  2937. See Also:   quicksort
  2938. -------------------------------------------------------------------------
  2939.  
  2940. ``    11) TIME FUNCTIONS
  2941.  
  2942.       These are the standard time functions as
  2943.       described in K&R edition II. Most of these functions use typedefs
  2944.       and structure definitions that are found in time.h. The tm structure
  2945.       is explained here.
  2946.  
  2947.       struct tm
  2948.       {
  2949.       short tm_sec;    seconds after the minute
  2950.       short tm_min;    minutes after the hour
  2951.       short tm_hour;    hours since midnight
  2952.       short tm_mday;    day of the month
  2953.       short tm_mon;    months since January
  2954.       short tm_year;    years since 1900
  2955.       short tm_wday;    days since sunday
  2956.       short tm_yday;    days since January, 1
  2957.       short tm_isdst;    Not Used
  2958.       };
  2959.  
  2960. -------------------------------------------------------------------------
  2961. Name:        asctime
  2962.  
  2963. Synopsis:   char *asctime(tm)
  2964.         struct tm *tm;
  2965.  
  2966. Function:   Converts the time in the structure tm to a string of the
  2967.         form: Sun Jan 1 12:00:00 1989
  2968.  
  2969. Arguments:  tm - structure obtained from localtime
  2970.  
  2971. Return:     A pointer to a string is returned. The string is in "static"
  2972.         memory and may be overwritten by other calls.
  2973.  
  2974. See Also:   localtime
  2975. -------------------------------------------------------------------------
  2976. Name:        clock
  2977.  
  2978. Synopsis:   clock_t clock()
  2979.  
  2980. Function:   Obtains the number of ticks since program execution.
  2981.  
  2982. Return:     The number of ticks that have passed since the program was
  2983.         first executed is returned. clock()/CLOCK_TCK gives the time
  2984.         in seconds.
  2985. -------------------------------------------------------------------------
  2986. Name:        ctime
  2987.  
  2988. Synopsis:   char *ctime(t)
  2989.         time_t *t;
  2990.  
  2991. Function:   Equivalent to asctime(localtime(t)).
  2992.  
  2993. Arguments:  t - pointer to a time_t obtained from time().
  2994.  
  2995. Return:     A pointer to a string is returned. The string is in "static"
  2996.         memory and may be overwritten by other calls.
  2997.  
  2998. See Also:   asctime, localtime, time
  2999. -------------------------------------------------------------------------
  3000. Name:        difftime
  3001.  
  3002. Synopsis:   long difftime(t1,t2)
  3003.         time_t t1, t2;
  3004.  
  3005. Function:   Obtains the difference between two times in seconds.
  3006.         t2 - t1.
  3007.  
  3008. Arguments:  t1, t2 - times to take the difference of
  3009.  
  3010. Return:     Time difference in seconds.
  3011.  
  3012. See Also:   time
  3013. -------------------------------------------------------------------------
  3014. Name:        gmtime
  3015.  
  3016. Synopsis:   struct tm *gmtime(t)
  3017.         time_t *t;
  3018.  
  3019. Function:   Same as localtime because Coordinated Universal Time is not
  3020.         readily available on the amiga.
  3021.  
  3022. Arguments:  t - pointer to a time_t obtained from time().
  3023.  
  3024. Return:     Same as localtime.
  3025. -------------------------------------------------------------------------
  3026. Name:        localtime
  3027.  
  3028. Synopsis:   struct tm *localtime(t)
  3029.         time_t *t;
  3030.  
  3031. Function:   Fills out a tm structure from the time obtained from time().
  3032.  
  3033. Arguments:  t - pointer to a time_t obtained from time().
  3034.  
  3035. Return:     A tm structure is returned. This structure is located in
  3036.         "static" memory and will be overwritten by later calls. For
  3037.         an explanation of the tm structure see the heading for this
  3038.         section.
  3039.  
  3040. See Also:   time
  3041. -------------------------------------------------------------------------
  3042. Name:        mktime
  3043.  
  3044. Synopsis:   time_t mktime(tm)
  3045.         struct tm *tm;
  3046.  
  3047. Function:   This function is the opposite of localtime, it converts a
  3048.         tm structure into a time_t.
  3049.  
  3050. Arguments:  tm - pointer to a tm structure
  3051.  
  3052. Return:     A time_t that can be used by the other time functions is
  3053.         returned.
  3054.  
  3055. Note:        The members of the tm structure that are used to make the
  3056.         time_t are: tm_year, tm_yday, tm_hour, tm_min, and tm_sec.
  3057.         This is certainly library dependant.
  3058. -------------------------------------------------------------------------
  3059. Name:        strftime
  3060.  
  3061. Synopsis:   size_t strftime(s,smax,fmt,tm)
  3062.         char *s;
  3063.         size_t smax;
  3064.         char *fmt;
  3065.         struct tm *tm;
  3066.  
  3067. Function:   Formats date and time information into a string according to
  3068.         a format string.
  3069.  
  3070. Arguments:  s - string to store the result
  3071.         smax - maximum number of characters to place in the string
  3072.         fmt - format string, ordinary characters including the NULL
  3073.         terminator are copied to the result string. Format specifiers
  3074.         have the the following possible values:
  3075.  
  3076.            %a    abbreviated weekday name
  3077.            %A    full weekday name
  3078.            %b    abbreviated month name
  3079.            %B    full month name
  3080.            %c    local date and time representation
  3081.            %d    day of the month
  3082.            %H    hour, 24 hour clock
  3083.            %I    hour, 12 hour clock
  3084.            %j    day of the year, 1-366
  3085.            %m    month, 1-12
  3086.            %M    minute, 00-59
  3087.            %p    AM or PM
  3088.            %S    second 00-59
  3089.            %U    week number of year 00-53
  3090.            %w    weekday, 0-6
  3091.            %W    same as U
  3092.            %x    local date representation
  3093.            %X    local time representation
  3094.            %y    year without century
  3095.            %Y    year with century
  3096.            %Z    "Local"
  3097.            %%    '%'
  3098.  
  3099. Return:     The number of characters written excluding the NULL terminator
  3100.         is returned, zero is returned if the result string would be
  3101.         overflowed.
  3102. -------------------------------------------------------------------------
  3103. Name:        time
  3104.  
  3105. Synopsis:   time_t time(t)
  3106.         time_t *t;
  3107.  
  3108. Function:   Obtains the current time, if the t argument is not NULL then
  3109.         the time is also assigned to *t.
  3110.  
  3111. Arguments:  t - pointer to variable to store the current time, or NULL.
  3112.  
  3113. Return:     The current time is returned.
  3114. -------------------------------------------------------------------------
  3115. ``    12) PROCESS CONTROL FUNCTIONS
  3116.  
  3117.       Any self respecting C library should include a set of functions for
  3118.       controlling processes. The process control functions outlined here
  3119.       fall into two categories, one for controlling your own process and
  3120.       the other for controlling processes that are spawned.
  3121.  
  3122.       Since the Amiga is somewhat unique in the way it handles spawned
  3123.       processes the process spawning functions are non standard. The reason
  3124.       this route was chosen was the fact that there appeared to be no
  3125.       _safe_ way to implement the standard spawn type functions, and have
  3126.       them work for both workbench and CLI programs. Just the fact that
  3127.       programs can be spawned in two entirely different ways poses some
  3128.       significant problems. I have opted for an approach that solves the
  3129.       problem in Amiga specific way and is very safe.
  3130.  
  3131. -------------------------------------------------------------------------
  3132. Name:        abort                 MACRO
  3133.  
  3134. Synopsis:   #include "stdlib.h"
  3135.         void abort()
  3136.  
  3137. Function:   This is a macro that causes abnormal program termination. It
  3138.         is equivalent to exit(EXIT_FAILURE).
  3139.  
  3140. See Also:   exit
  3141. -------------------------------------------------------------------------
  3142. Name:        atexit                 MACRO
  3143.  
  3144. Synopsis:   #include "stdlib.h"
  3145.         void atexit( func )
  3146.         void (*func)();
  3147.  
  3148. Function:   Sets the atexit function that is executed when the program
  3149.         terminates through a call to exit or _exit. Any existing
  3150.         atexit function is over-written. This is defined as a macro
  3151.         in stdlib.h.
  3152.  
  3153. Arguments:  func - a pointer to your atexit function
  3154.  
  3155. See Also:   exit
  3156. -------------------------------------------------------------------------
  3157. Name:        ClearAbortFunc
  3158.  
  3159. Synopsis:   void ClearAbortFunc()
  3160.  
  3161. Function:   Clears the break signal abort function. A call to this function
  3162.         will disable program termination when a ^C or a break is sent
  3163.         to it with the AmigaDOS break command.
  3164.  
  3165. See Also:   SetAbortFunc
  3166. -------------------------------------------------------------------------
  3167. Name:        cliexec
  3168.  
  3169. Synopsis:   long cliexec()
  3170.         char *cmd;
  3171.  
  3172. Function:   Spawns a cli command. An error will occur if this function is
  3173.         called from a workbench program.
  3174.  
  3175. Arguments:  cmd - A null-terminated string containing the cli command to
  3176.           execute. The string must contain the name of the program
  3177.           followed by the command line arguments delimited by
  3178.           spaces. If you wish to execute the new process in parallel
  3179.           with the current one then place the "run" command in front
  3180.           of the command string.
  3181.  
  3182. Return:     Zero is retured on failure.
  3183.  
  3184. See Also: system, wbexec
  3185. -------------------------------------------------------------------------
  3186. Name:        exec
  3187.  
  3188. Synopsis:   long exec()
  3189.         char *command;
  3190.  
  3191. Function:   runs another (child) program, waiting for the child program to
  3192.         finish running before continuing execution. The mode that the
  3193.         child program is exected in depends on the mode of the current
  3194.         program. If the current program has been executed using the CLI
  3195.         then the child program will be executed as a CLI process. If
  3196.         the current program is a Workbench process then the child will
  3197.         be executed as a Workbench process and all command line
  3198.         arguments will be ignored. For CLI processes the standard
  3199.         search path as specified by the Amiga DOS path command will be
  3200.         searched after the current directory. For Workbench processes
  3201.         the C: directory will be searched after the current directory.
  3202.  
  3203. Arguments:  command - The command to execute, including any command line
  3204.         arguments. For Workbench programs the command line arguments
  3205.         will be striped off befor an attempt is made to execute the
  3206.         child process. CLI programs can be executed asyncronously by
  3207.         prefixing the command with the Amiga DOS "RUN" command.
  3208.  
  3209. Return:     FALSE ( 0 ) is returned on failure.
  3210.  
  3211. See Also:   cliexec, wbexec
  3212. -------------------------------------------------------------------------
  3213. Name:        exit and _exit()
  3214.  
  3215. Synopsis:   void exit(code)     void _exit(code)
  3216.         long code;        long code;
  3217.  
  3218. Function:   Causes normal program termination. The atexit() function is
  3219.         executed  Open files and streams are closed and flushed, memory
  3220.         is de-allocated and returned to the system. Exit may also be
  3221.         called when a break signal is received from Amiga DOS.
  3222.  
  3223. Arguments:  code - the return code of the program. The values EXIT_SUCCESS
  3224.         and EXIT_FAILURE may also be used.
  3225.  
  3226. See Also:   abort, atexit
  3227. -------------------------------------------------------------------------
  3228. Name:        getenv
  3229.  
  3230. Synopsis:   char *getenv(name)
  3231.         char *name;
  3232.  
  3233. Function:   retrieves an environment variable. On the Amiga environment
  3234.         variables are stored as files in the ENV: directory. The getenv
  3235.         function is designed to be compatible with the Amiga DOS
  3236.         GETENV command.
  3237.  
  3238. Arguments:  name - the name of the environment variable to retreive
  3239.  
  3240. Return:     a pointer to a null-terminated string that contains the
  3241.         value of the environment variable. NULL is returned if
  3242.         the environment variable could not be found or if an error
  3243.         occured. An error can be detected by inspecting the value
  3244.         of the global variable errno, which will be set to ENOMEM
  3245.         if not enough memory is available. The string pointer returned
  3246.         by getenv points to allocated memory, which will be freed
  3247.         by another call to getenv.
  3248.  
  3249. See Also:   setenv
  3250. -------------------------------------------------------------------------
  3251. Name:        kill
  3252.  
  3253. Synopsis:   long kill(child)
  3254.         Child *child;
  3255.  
  3256. Function:   attempts to remove a child process. On the Amiga it is not
  3257.         possible to forcibly remove a child process and free all of
  3258.         it's resources the way it is on UNIX for example. What this
  3259.         function does is signal the process with all of the break
  3260.         signals (^C, ^D, ^E, and ^F) then wait for the process to reply
  3261.         to it's workbench message. CClib.library IO functions will
  3262.         always check for the break signals and attempt to abort the
  3263.         program if any of them are detected. All programs should
  3264.         check for break signals returned from the Wait() function,
  3265.         but many don't. When the child process has finished execution
  3266.         it's code is unloaded.
  3267.  
  3268. Arguments:  child - a pointer to a Child structure, as returned from the
  3269.         wbAexec function.
  3270.  
  3271. Return:     FALSE is returned if an error occured. TRUE is returned if the
  3272.         child process was killed or if it has already terminated itself.
  3273.  
  3274. See Also:   wbAexec
  3275. -------------------------------------------------------------------------
  3276. Name:        kill_children
  3277.  
  3278. Synopsis:   long kill_children
  3279.  
  3280. Function:   terminates all child processes as if they had each been killed
  3281.         with the kill function.
  3282.  
  3283. Arguments:  NONE
  3284.  
  3285. Return:     FALSE is returned if an error occured.
  3286.  
  3287. See Also:   kill
  3288. -------------------------------------------------------------------------
  3289. Name:        longjmp
  3290.  
  3291. Synopsis:   void longjmp(env, return_code )
  3292.         jmp_buf env;
  3293.         int return_code;
  3294.  
  3295. Function:   Provides a way to avoid the normal call and return sequence.
  3296.         longjmp restores the state retained in env by a call to setjmp.
  3297.         Execution continues as if setjmp had just returned the non-zero
  3298.         value return_code. The function containing setjmp must not have
  3299.         terminated when this call is made. setjmp/longjmp are similar
  3300.         to a "super goto" and except for rare necessary circumstances
  3301.         should be avoided.
  3302.  
  3303. Arguments:  return_code - a non-zero return code that is used as tht faux
  3304.         return code from setjmp.
  3305.  
  3306. Return:     doesn't
  3307.  
  3308. See Also:   setjmp
  3309.  
  3310. Note:     The setjmp and longjmp routines have been donted by Paul Gittings.
  3311.      He writes:
  3312.      "the setjmp and longjmp routines do not fully comply with ANSI C.
  3313.      To do so would require saving the state of all local variables
  3314.      (ok not to save register variables) at the time of the call to
  3315.      setjmp and restore them when longjmp is called. This is left as an
  3316.      exercise for the gentle reader..."
  3317. -------------------------------------------------------------------------
  3318. Name:        perror
  3319.  
  3320. Synopsis:   long perror(msg)
  3321.         char *msg;
  3322.  
  3323. Function:   Prints an error message corresponding to the number in errno
  3324.         along with a message you provide to stderr.
  3325.  
  3326. Arguments:  msg - supplimental error message, or NULL if you don't have one.
  3327.  
  3328. Return:     Zero is returned on success, -1 is returned if the error number
  3329.         in errno has no corresponding error message or if an error
  3330.         error occurs with the execution of perror.
  3331.  
  3332. See Also:   puterr
  3333. Name:        SetAbortFunc
  3334.  
  3335. Synopsis:   void SetAbortFunc(func)
  3336.         long (*func)();
  3337.  
  3338. Function:   Sets the break signal abort function. Whenever a break signal
  3339.         is detected from AmigaDOS, sent either by a ^C from the console
  3340.         or from an AmigaDOS break command, the library will see if there
  3341.         is an abort function, and if there is it will be executed with
  3342.         the signals that caused it to be executed as an argument. The
  3343.         signals will be in a 32 bit integer. During normal operation
  3344.         the function _exit is the abort function, however you may wish
  3345.         to set it to something else so that you can clean up whatever
  3346.         your application is doing at the time. If you intend to exit
  3347.         from the program call the exit or _exit functions, not the
  3348.         AmigaDOS Exit function,  or else resources allocated by
  3349.         the library will not be de-allocated.
  3350.  
  3351. Arguments:  func - a pointer to the abort function to be used when a
  3352.         break signal is received.
  3353.  
  3354. See Also:   ClearAbortFunc
  3355. -------------------------------------------------------------------------
  3356. Name:        setenv
  3357.  
  3358. Synopsis:   long setenv(name,value)
  3359.         char *name;
  3360.         char *value;
  3361.  
  3362. Function:   Sets the value of an environment variable. On the Amiga this
  3363.         means that a file is created in the ENV: directory with the
  3364.         name "name" and the contents of the file is the the string
  3365.         pointed to by "value". The setenv function is designed to
  3366.         have the same effect as the Amiga DOS SETENV command.
  3367.  
  3368. Arguments:  name - a pointer to a null-terminated string that contains
  3369.         the name of the environment variable to set.
  3370.         value - a pointer to a null-terminated string that contains
  3371.         the value of the environment variable to set. If a NULL value
  3372.         or a null string (one of zero length) is passed here the
  3373.         environment variable is removed from the system.
  3374.  
  3375. Return:     Non-zero is returned on error. If setenv failed due to an
  3376.         out of memory condition the global variable "errno" will be
  3377.         set to ENOMEM.
  3378.  
  3379. See Also:   getenv
  3380. -------------------------------------------------------------------------
  3381. Name:        setjmp
  3382.  
  3383. Synopsis:   #include "setjmp.h"
  3384.         int setjmp(env)
  3385.         jmp_buf env;
  3386.  
  3387. Function:   Provides a way to avoid the normal call and return sequence.
  3388.         setjmp saves state information in env for use by longjmp.
  3389.  
  3390. Arguments:  env - environment buffer for setjmp and longjmp
  3391.  
  3392. Return:     Zero from a direct call to setjmp, non-zero from an indirect
  3393.         call through longjmp.
  3394.  
  3395. See Also:   longjmp
  3396.  
  3397. Note:     The setjmp and longjmp routines have been donted by Paul Gittings.
  3398.      He writes:
  3399.      "the setjmp and longjmp routines do not fully comply with ANSI C.
  3400.      To do so would require saving the state of all local variables
  3401.      (ok not to save register variables) at the time of the call to
  3402.      setjmp and restore them when longjmp is called. This is left as an
  3403.      exercise for the gentle reader..."
  3404. -------------------------------------------------------------------------
  3405. Name:        signal_child
  3406.  
  3407. Synopsis:   long signal_child(child,signals)
  3408.         Child *child;
  3409.         long signals;
  3410.  
  3411. Function:   signals a child process with any set of signals. Signals are
  3412.         used by the Amiga OS as the lowest level of inter-process
  3413.         communication. When Amiga tasks are suspended they are
  3414.         generally waiting for some signal to arrive. This function
  3415.         is used by the kill functions.
  3416.  
  3417. Arguments:  child - a pointer to the child process as returned by the
  3418.         wbAexec function.
  3419.  
  3420. Return:     FALSE is returned if an error occured.
  3421.  
  3422. See Also:   wbAexec
  3423. -------------------------------------------------------------------------
  3424. Name:        system                 MACRO
  3425.  
  3426. Synopsis:   #include "stdlib.h"
  3427.         system(command)
  3428.         char *command;
  3429.  
  3430. Function:   Executes a command as if it was typed in on the CLI command
  3431.         line. The RUN command must be in the path or in the C: directory
  3432.         for this function to work.
  3433.  
  3434. Arguments:  command - The command to execute, for example:
  3435.         system("FORMAT DRIVE DH0: NAME TRASHED") will format
  3436.         your hard drive immediatly without asking.
  3437.  
  3438. Return:     Zero is returned on failure.
  3439. -------------------------------------------------------------------------
  3440. Name:        wait_child
  3441.  
  3442. Synopsis:   long wait_child(child)
  3443.         Child *child;
  3444.  
  3445. Function:   waits for a child process that was spawned by the wbAexec
  3446.         function to complete execution. After the child process has
  3447.         terminated the code for the process unloaded.
  3448.  
  3449. Arguments:  child - a pointer to a child process as returned by wbAexec.
  3450.         If child is set to NULL then the wait_child function will
  3451.         wait for all child processes to complete.
  3452.  
  3453. Return:     TRUE is returned if the operation was successful, FALSE is
  3454.         returned on error.
  3455.  
  3456. See Also:   wbAexec
  3457. -------------------------------------------------------------------------
  3458. Name:        wait_children
  3459.  
  3460. Synopsis:   long wait_children(void)
  3461.  
  3462. Function:   waits for all child processes to terminate. This function is
  3463.         called by exit because the process that starts a program on the
  3464.         Amiga is the one that must unload the code. If all processes
  3465.         are finished executing, or if no child processes have been
  3466.         spawned then this function will return immediatly.
  3467.  
  3468. Arguments:  NONE
  3469.  
  3470. Return:     FALSE is returned on error
  3471.  
  3472. See Also:   wbAexec
  3473. -------------------------------------------------------------------------
  3474. Name:        wb_exec
  3475.  
  3476. Synopsis:   long wb_exec(filename, procname, toolname, toolwindow,
  3477.              curdir, rport, stk, pri, child)
  3478.         char *filename;
  3479.         char *procname;
  3480.         char *toolname;
  3481.         char *toolwindow;
  3482.         BPTR curdir;
  3483.         struct MsgPort *rport;
  3484.         long stk;
  3485.         long pri;
  3486.         REGS Child *child;
  3487.  
  3488.  
  3489. Function:   This is the lowest level process spawning function that is used
  3490.         to spawn a process as if it were a workbench program. It is
  3491.         used by both wbAexec and wbexec. The interface to this function
  3492.         is somewhat complicated but it allows greater flexibility than
  3493.         either wbexec or wbAexec.
  3494.  
  3495. Arguments:  filename - the name of the Amiga DOS program to execute. If the
  3496.         program file is not found in the current directory then the
  3497.         C: directory is searched.
  3498.  
  3499.         procname - the name the process will be given in the process
  3500.         list. If you don't care what goes here use filename.
  3501.  
  3502.         toolname - the name of the "tool" for this program. Tool is
  3503.         another name for Icon. If you want an Icon to be assocated with
  3504.         the program specify the name of it here, otherwise use a null
  3505.         string here ("").
  3506.  
  3507.         toolwindow - this is a description of the window. I don't
  3508.         exactly know what this is for but it gets attached to the
  3509.         workbench startup message at the sm_ToolWindow member. If you
  3510.         set it to NULL everything will work fine.
  3511.  
  3512.         curdir - is a pointer to a lock (obtained by Lock()) to the
  3513.         current directory for this program. A value of NULL here means
  3514.         the root directory of the current volume. If a value of -1L is
  3515.         used wb_exec will use the current directory of the calling
  3516.         program.
  3517.  
  3518.         rport - a pointer to a valid message port. The message port is
  3519.         used so that the child process can reply to the workbench
  3520.         startup message. Child processes only reply to the startup
  3521.         message after they have finished execution and expect their
  3522.         code to be unloaded. The code for a child process must be
  3523.         unloaded by the parent process.
  3524.  
  3525.         stk - the size of the stack to use for the new process. If a
  3526.         value of 0 or less is used here then the stack size of the
  3527.         parent process will be used.
  3528.  
  3529.         pri - the priority that the child task will run at. A normal
  3530.         process would have a priority of 0. Values of -128 to +127 are
  3531.         possible but values from -5 to 5 are more typical.
  3532.  
  3533.         child - a pointer to the Child structure that is to be used for
  3534.         this process. Here is the definition of the Child structure
  3535.         as found in iolib.h
  3536.  
  3537.            typedef struct
  3538.            {
  3539.            struct WBStartup startup;
  3540.            struct WBArg arg;
  3541.            struct Process *pid;
  3542.            } Child;
  3543.  
  3544.            startup - the workbench startup message that is sent to the
  3545.            child process.
  3546.            arg - the first argument for the workbench startup message
  3547.            pid - a pointer to the Process structure  for the child
  3548.              process.
  3549.  
  3550.         All of the members of the child structure are filled by wb_exec.
  3551.  
  3552. Return:     zero is returned on failure.
  3553.  
  3554. See Also:   wbexe, wbAexec
  3555. -------------------------------------------------------------------------
  3556. Name:        wbAexec
  3557.  
  3558. Synopsis:   #include "iolib.h"
  3559.         Child *wbAexec(name, stack, priority)
  3560.         char *name;
  3561.         long stack;
  3562.         long priority;
  3563.  
  3564. Function:   Executes a program as a workbench process asynchronously with
  3565.         the parent process. The "Child" structure is attached to the
  3566.         task_UserData structure of the parent process (the caller).
  3567.  
  3568. Arguments:  name - the name of the program to execute. If the executable
  3569.         file is not found in the current directory then the C: directory
  3570.         is searched.
  3571.  
  3572.         stack - the size of the stack to use for the new process. If a
  3573.         value of 0 or less is used here then the stack size of the
  3574.         parent process will be used.
  3575.  
  3576.         priority - the priority that the child task will run at. A
  3577.         normal process would have a priority of 0. Values of -128 to
  3578.         +127 are possible but values from -5 to +5 are more typical.
  3579.  
  3580. Return:     A pointer to a Child structure is returned, or NULL if an error
  3581.         occured.
  3582.  
  3583. See Also:   wait_chldren, kill_children
  3584. -------------------------------------------------------------------------
  3585. ``    IV) STRUCTURE DOCUMENTATION
  3586.  
  3587.    Here is the explantion of all of the data structures that are associated
  3588.    with CClib.library and are accessible to the application program. Some
  3589.    of the structures are also defined in other sections of the manual as
  3590.    well as in this section.
  3591. -------------------------------------------------------------------------
  3592. Name:        Child
  3593.  
  3594. Location:   iolib.h
  3595.  
  3596. Definition:
  3597.      typedef struct
  3598.      {
  3599.      struct WBStartup startup;
  3600.      struct WBArg arg;
  3601.      struct Process *pid;
  3602.      } Child;
  3603.  
  3604. Purpose:    This is what the Chidren _list in the task_UserData structure
  3605.         consists of. It is a list of the child processes that were
  3606.         spawned asynchronously, and that need to have their code
  3607.         unloaded before the parent can terminate itself. A pointer to
  3608.         this structure is returned by the wbAexec() function.
  3609.  
  3610. Members:    startup - the workbench startup message sent to the child
  3611.            process.
  3612.         arg - the first argument for the workbench startup message.
  3613.         pid - a pointer to the actual process structure for the
  3614.            child.
  3615.  
  3616. See Also: task_UserData
  3617. -------------------------------------------------------------------------
  3618. Name:        clock_t
  3619.  
  3620. Location:   stddef.h
  3621.  
  3622. Definition:
  3623.      typedef long clock_t;
  3624.  
  3625. Purpose:    contains the clock "ticks" since a program started execution
  3626. -------------------------------------------------------------------------
  3627. Name:        FILE                   PRIVATE
  3628.  
  3629. Location:   stdio.h
  3630.  
  3631. Definition:
  3632.      typedef struct
  3633.      {
  3634.      long _unit;         /* token returned by open -> FileDesc */
  3635.      char *_bp;         /* position in character buffer */
  3636.      char *_bend;         /* end of buffer */
  3637.      char *_buff;         /* start */
  3638.      char _flags;         /* open mode  */
  3639.      char _bytbuf;         /* single character buffer (non-bufered files) */
  3640.      short _buflen;      /* # characters in buffer */
  3641.      char *_tmpname;     /* temporary file name */
  3642.      } FILE;
  3643.  
  3644. Purpose:    The structure used for Stream file access, used with all of the
  3645.         ANSI standard IO functions. This structure should be considered
  3646.         PRIVATE and must not be tampered with directly by applications.
  3647.         The documentation is provided here for informative purposes
  3648.         only.
  3649.  
  3650. Members:    _unit - file descriptor, as returned by open()
  3651.         _bp - current position in character buffer
  3652.         _bend - end of character buffer
  3653.         _buff - start of character buffer
  3654.         _flags - saved open() mode
  3655.         _bytbuf - a single charecter buffer for non-buffered files, or
  3656.            for when the library cannot allocate a buffer
  3657.         _buflen - number of characters currently in the buffer
  3658.         _tmpname - the name of a temporary file that may or may not
  3659.            be associated with this stream
  3660.  
  3661. See Also:   fopen() function
  3662. -------------------------------------------------------------------------
  3663. Name:        FileDesc                   PRIVATE
  3664.  
  3665. Location:   iolib.h
  3666.  
  3667. Definition:
  3668.      typedef struct
  3669.      {
  3670.      BPTR fh;
  3671.      short mode;
  3672.      } FileDesc;
  3673.  
  3674. Purpose:    A FileDesc is what a file descriptor returned by open() actually
  3675.         points to. It should not be accessed by the application and
  3676.         is described here only for informative purposes.
  3677.  
  3678. Members:    fh - a pointer to the Amiga DOS file handle returned by the
  3679.            Amiga Open() function.
  3680.         mode - the mode the file was opened under, as specified by the
  3681.            mode argunent to the open() function.
  3682. -------------------------------------------------------------------------
  3683. Name:        fpos_t
  3684.  
  3685. Location:   stddef.h
  3686.  
  3687. Definition:
  3688.      typedef long fpos_t;
  3689.  
  3690. Purpose:    used by the fgetpos and fsetpos functions to store the position
  3691.         within a file
  3692. -------------------------------------------------------------------------
  3693. Name:        union header (alias HEADER)            PRIVATE
  3694.  
  3695. Location:   heapmem.h
  3696.  
  3697. Definition:
  3698.  
  3699.       typedef long ALIGN;
  3700.  
  3701.       union header
  3702.       {
  3703.       struct
  3704.      {
  3705.      union header *ptr;
  3706.      unsigned long size;
  3707.      } s;
  3708.       ALIGN x;
  3709.       };
  3710.  
  3711. Purpose:    Used internally to keep track of free heap memory. It sould not
  3712.         be accessed by the application but is documented for
  3713.         informative purposes. The free memory blocks can be examined
  3714.         from the task_UserData structure.
  3715.  
  3716. Members:    ptr - pointer to the next header in the chain
  3717.         size - the size of the free memory block in multiples of
  3718.             sizeof(union header)
  3719.         x - forces longword alignment
  3720.  
  3721. See Also:   task_UserData
  3722. -------------------------------------------------------------------------
  3723. Name:        LastFree                   PRIVATE
  3724.  
  3725. Location:   heapmem.h
  3726.  
  3727. Definition:
  3728.  
  3729.      typedef struct
  3730.      {
  3731.      void *ptr;
  3732.      unsigned long size;
  3733.      } LastFree;
  3734.  
  3735. Purpose:    used internally to support the realloc function. It holds a
  3736.         pointer to and the size of the last freed block of memory and
  3737.         is part of the task_UserData structure.
  3738.  
  3739.  
  3740. Members:    ptr - pointer to the last freed block of memory
  3741.         size - size of the last block of memory to be freed
  3742.  
  3743. See Also:   task_UserData
  3744. -------------------------------------------------------------------------
  3745. Name:        _list
  3746.  
  3747. Location:   stdlist.h
  3748.  
  3749. Definition:
  3750.      typedef struct
  3751.      {
  3752.      _node *first, *last;
  3753.      long length;
  3754.      } _list;
  3755.  
  3756. Purpose:    CClib.library uses simple linked lists internally and the the
  3757.         linked list functions are available for application use. This
  3758.         is the structure that is used to maintain one of these linked
  3759.         lists.
  3760.  
  3761. Members:    first - pointer to the first node in the linked list or
  3762.            NULL if the list is empty.
  3763.         last - pointer to the last node in the linked list of
  3764.            NULL if the list is empty.
  3765.         length - a count of the number of nodes that are currently
  3766.            in the linked list.
  3767.  
  3768. See Also:   _node
  3769. -------------------------------------------------------------------------
  3770. Name:        MemBlk                   PRIVATE
  3771.  
  3772. Location:   iolib.h
  3773.  
  3774. Definition:
  3775.  
  3776.       typedef struct
  3777.       {
  3778.       _node n;
  3779.       long size;
  3780.       } MemBlk;
  3781.  
  3782.  
  3783. Purpose:    This structure is used to keep track of all of the memory that
  3784.         has been allocated from the operating system using the low-level
  3785.         memory allocation functions. The heap memory allocation functions
  3786.         use the lower level functions to get larger blocks of memory.
  3787.         These structures are attached to two lists in the task_UserData
  3788.         structure and are freed before the program terminates.
  3789.  
  3790. Members:    n - a node that is used to link toghther the list of allocated
  3791.         memory blocks.
  3792.         size - the total size of the allocated memory block in bytes
  3793.         including the additional size of the MemBlk itself.
  3794.  
  3795. See Also: _node, task_UserData
  3796. -------------------------------------------------------------------------
  3797. Name:        _node
  3798.  
  3799. Location:   stdlist.h
  3800.  
  3801. Definition:
  3802.      typedef struct _node
  3803.      {
  3804.      struct _node *prev, *next;
  3805.      } _node;
  3806.  
  3807. Purpose:    CClib.library uses simple linked lists internally and the the
  3808.         linked list functions are available for application use. This
  3809.         is the structure of the header of a node in a doubly linked
  3810.         list. The entire node usually consists of the node structure
  3811.         followed immediatly by the data associated with the node.
  3812.  
  3813. Members:    prev - pointer to the previous node in a list or NULL if this
  3814.            is the first node.
  3815.         next - pointer to the next node in a list or NULL if this is
  3816.            the last node.
  3817.  
  3818. See Also: _list
  3819. -------------------------------------------------------------------------
  3820. Name:        ptrdiff_t
  3821.  
  3822. Location:   stddef.h
  3823.  
  3824. Definition:
  3825.      typedef long ptrdiff_t;
  3826.  
  3827. Purpose:    ptrdiff_t is a data type that can hold the difference between
  3828.         two pointers
  3829. -------------------------------------------------------------------------
  3830. Name:        size_t
  3831.  
  3832. Location:   stddef.h
  3833.  
  3834. Definition:
  3835.      typedef unsigned long size_t;
  3836.  
  3837. Purpose:    size_t is what is returned by the sizeof() operator
  3838. -------------------------------------------------------------------------
  3839. Name:        stat
  3840.  
  3841. Location:   stat.h
  3842.  
  3843. Definition:
  3844.      struct stat
  3845.      {
  3846.      unsigned short st_attr;
  3847.      time_t st_mtime;
  3848.      long st_size;
  3849.  
  3850.      /* THESE ARE ONLY FILLED OUT BY THE stat_() FUNCTION!
  3851.       * (in order to maintain compatibility with the older
  3852.       * versions of CClib.library)                  */
  3853.  
  3854.      unsigned short st_mode;
  3855.      short st_nlink;
  3856.      time_t st_atime;
  3857.      time_t st_ctime;
  3858.      };
  3859.  
  3860. Purpose:    The stat structure is returned by the stat functions so as to
  3861.         retrieve some inofrmation about a file, directory, or device.
  3862.  
  3863. Members:    st_attr - file attributes which may be or'd together including:
  3864.           This Bit On       Means
  3865.            ST_DELETE   -  file is NOT deletable
  3866.            ST_EXECUTE  -  file is NOT executable
  3867.            ST_WRITE    -  file is NOT writeable
  3868.            ST_READ       -  file is NOT readable
  3869.            ST_ARCHIVE  -  file HAS been archived
  3870.         A warning about attribute bits; It is unsafe to assume that
  3871.         the other bits available in the attribute field will be un-used.
  3872.         This is because they may be used in future implementations of
  3873.         the Amiga operating system. This has already happened in the
  3874.         case of the ST_ARCHIVE bit.
  3875.  
  3876.         st_mtime - File modification date, in seconds since Jan, 1 1978
  3877.         st_size - of file in bytes
  3878.         st_mode - file type bits
  3879.            S_IFMT - all file type bits
  3880.            S_IFDIR - a directory
  3881.            S_IFCHR - character special (used for interactive streams)
  3882.            S_IFBLK - block special (not used yet)
  3883.            S_IFREG - a reqular file (not interactive)
  3884.         st_atime - currently the same as st_mtime
  3885.         st_ctime - currently the same as st_mtime
  3886.  
  3887. See Also:   stat_, stat (functions)
  3888. -------------------------------------------------------------------------
  3889. Name:        task_UserData               PRIVATE
  3890.  
  3891. Location:   iolib.h
  3892.  
  3893. Definition:
  3894.  
  3895.      typedef void (*ABORT_FUNC)(long);
  3896.  
  3897.      typedef struct
  3898.      {
  3899.      void *old_ud;
  3900.      struct Task *parent;
  3901.      _list RAM;
  3902.      HEADER base, *allocp;
  3903.      long *blocksize;
  3904.      LastFree lastfree;
  3905.      _list OpenFiles;
  3906.      _list StreamFiles;
  3907.      FILE **stdout, **stdin, **stderr;
  3908.      void *scnfp;
  3909.      long *errno;
  3910.      ABORT_FUNC abort_func;
  3911.      void *wbmsg;
  3912.      short _argc, _arg_len;
  3913.      char **_argv, *_arg_lin;
  3914.      char *scanpoint;
  3915.      char *tempname;
  3916.      short scnlast;
  3917.      struct tm tm;
  3918.      clock_t start;
  3919.      char buffer[80];
  3920.      void *scdir_mem;
  3921.      void *getenv_mem;
  3922.      struct MsgPort *exeport;
  3923.      _list Children;
  3924.      } task_UserData;
  3925.  
  3926. Purpose:    the structure used by CClib.library client programs that is
  3927.         pointed to by the its task.tc_UserData member. It is used to
  3928.         keep track of all "global" variables that are used by the
  3929.         library. The structure is allocated and initialized in the
  3930.         startup code and should probably not be modified manually. Its
  3931.         documentation is provided for informative purposes.
  3932.  
  3933. Members:    old_ud - the previous value of task.tc_UserData, restored in the
  3934.              exit code.
  3935.         parent - pointer to your Task.
  3936.         RAM - list of allocated memory. The nodes in the list are of
  3937.              type MemBlk.
  3938.         base - the initial memory header used for the the heap manager.
  3939.         allocp - a marker for the circular free memory list.
  3940.         blocksize - a pointer to a long integer that specifies the
  3941.              minimum size of a block of memory that is allocated
  3942.              from the operating system for the heap manager. The
  3943.              units are 8 bytes in size.
  3944.         lastfree - a structure that contains information
  3945.              about the last freed block of memory.
  3946.         OpenFiles - a list
  3947.              of AmigaDOS files that need be closed before program
  3948.              termination. The nodes in the list are of type
  3949.              FileDesc.
  3950.         StreamFiles - a list of stream files that need to be closed
  3951.              before the program terminated. The data for the list
  3952.              nodes is the FILE data type (stdio.h).
  3953.         stdout - a pointer to the global FILE pointer by the same name
  3954.              in the application program. It is used to support
  3955.              console output.
  3956.         stdin - a pointer to the global FILE pointer by the same name
  3957.              in the application porgram. It is used to support
  3958.              console input.
  3959.         stderr - a pointer to the global FILE pointer by the same name
  3960.              in the application program. It is used to support
  3961.              console output for error messages.
  3962.         scnfp - used internally by formatted input and output functions.
  3963.         errno - pointer to global variable in application by the same
  3964.              name.
  3965.         abort_func - function called during an exit, abort, or ^C
  3966.              termination.
  3967.         wbmsg - pointer to the workbench startup message for the
  3968.              application. NULL if started from the CLI. This
  3969.              message needs to be replied to before the program
  3970.              terminates.
  3971.         _argc - the number of commnad line arguments for CLI startup.
  3972.         _arg_len - sum of the lengths of all command line arguments.
  3973.         _argv - array of pointers to parsed argument strings.
  3974.         _arg_lin - pointer to the memory allocated for arguments.
  3975.         scanpoint - used internally by strtok to remember last place.
  3976.         tempname - used internally by tmpnam to remember the name of
  3977.              a temporary file.
  3978.         scnlast - used internally by gchar.
  3979.         tm - used internally by time the routines to return a pointer
  3980.              to a tm structure.
  3981.         start - time at the start of program execution.
  3982.         buffer - character buffer for general internal use.
  3983.         scdir_mem - memory allocated and used internally by scdir.
  3984.         getenv_mem - memory allocated and used internally be getenv.
  3985.         exeport - pointer to a message port used for spawning
  3986.              asynchronous processes.
  3987.         Children - a linked list of asynchronous child processes, the
  3988.              node data of the list consists of Child structures.
  3989.  
  3990. See Also: _list, header, LastFree, FILE, tm, FileDesc
  3991. -------------------------------------------------------------------------
  3992. Name:        time_t
  3993.  
  3994. Location:   stdef.h
  3995.  
  3996. Definition:
  3997.      typedef long time_t;
  3998.  
  3999. Purpose:    contains a time value in a system dependent manner
  4000. -------------------------------------------------------------------------
  4001. Name:        struct tm
  4002.  
  4003. Location:   time.h
  4004.  
  4005. Definition:
  4006.      struct tm
  4007.      {
  4008.      short tm_sec;
  4009.      short tm_min;
  4010.      short tm_hour;
  4011.      short tm_mday;
  4012.      short tm_mon;
  4013.      short tm_year;
  4014.      short tm_wday;
  4015.      short tm_yday;
  4016.      short tm_isdst;
  4017.      short tm_hsec;
  4018.      };
  4019.  
  4020. Purpose:    Used by the time routines to return a time value that is
  4021.         more palettable to human beings.
  4022.  
  4023. Members:
  4024.         tm_sec - seconds after the minute
  4025.         tm_min - minutes after the hour
  4026.         tm_hour - hours since midnight
  4027.         tm_mday - day of the month
  4028.         tm_mon - months since January
  4029.         tm_year - years since 1900
  4030.         tm_wday - days since sunday
  4031.         tm_yday - days since January, 1
  4032.         tm_isdst - Not Used
  4033.         tm_hsec - Not Used
  4034.  
  4035. See Also:   time_t
  4036. -------------------------------------------------------------------------
  4037. Name:        va_list
  4038.  
  4039. Location:   stdarg.h
  4040.  
  4041. Definition:
  4042.      typedef unsigned char *va_list;
  4043.  
  4044. Purpose:    used to keep track of variable length argument lists. The
  4045.         va_start, va_arg, and va_end macros all use it.
  4046.  
  4047. See Also:   va_start, va_arg, va_end
  4048. -------------------------------------------------------------------------
  4049. Name:        wchar_t
  4050.  
  4051. Location:   stddef.h
  4052.  
  4053. Definition:
  4054.      typedef char wchar_t;
  4055.  
  4056. Purpose:    holds a "wide character", same as a regular character here
  4057.  
  4058. -------------------------------------------------------------------------
  4059. ``    V) GLOBAL VARIABLES
  4060.  
  4061.       Most of the global variables are defined in the CClib startup code
  4062.       and declared external in header files so that they can be easily
  4063.       accessed.
  4064.  
  4065. -------------------------------------------------------------------------
  4066. Name:        blocksize
  4067.  
  4068. Declared:   in your program
  4069.  
  4070. Definition: in blocksize.c (cclib.lib)
  4071.         long blocksize = 0L;
  4072.  
  4073. Purpose:    blocksize controls the size of memory blocks that will be
  4074.         allocated from the operating system for use by the heap memory
  4075.         manager. Blocksize is in units of 8 bytes. If blocksize is 0
  4076.         a default size of 256 is used (2048 bytes).
  4077. -------------------------------------------------------------------------
  4078. Name:        CCLibBase                PRIVATE
  4079.  
  4080. Declared:   _main.c
  4081.  
  4082. Definition: void *CCLibBase;
  4083.  
  4084. Purpose:    library base pointer for CClib.library
  4085. -------------------------------------------------------------------------
  4086. Name:        DOSBase                PRIVATE
  4087.  
  4088. Declared:   _main.c
  4089.  
  4090. Definition: void *DOSBase;
  4091.  
  4092. Purpose:    library base pointer for dos.library
  4093. -------------------------------------------------------------------------
  4094. Name:        errno
  4095.  
  4096. Declared:   errno.h
  4097.  
  4098. Definition: in _main.c
  4099.         long errno;
  4100.  
  4101. Purpose:    used to contain the value of an IO error number. If the CClib
  4102.         IO functions fail one can usually check the value of errno for
  4103.         a further explanation of the problem. The possible values are
  4104.         defined below.
  4105.  
  4106.        Values           Meaning
  4107.  
  4108.         ENOENT    Amiga DOS Open() can't open the file
  4109.         EBADF    invalid file handle passed to close()
  4110.         ENOMEM    not enough memory to allocate another file handle
  4111.         EEXIST    file already exists
  4112.         EINVAL    invalid function number
  4113.         EMFILE    no file handles left (should never occur)
  4114.         ENOTTY    not a console device (should never occur)
  4115.         EACCES    invalid mode used in open()
  4116. -------------------------------------------------------------------------
  4117. Name:        exit_fcn
  4118.  
  4119. Declared:   in _main.c
  4120.  
  4121. Definition: void (*exit_fcn)();
  4122.  
  4123. Purpose:    points to the atexit function, or is NULL if no atexit
  4124.         function has been specified.
  4125.  
  4126. See Also:   atexit
  4127. -------------------------------------------------------------------------
  4128. Name:        _math
  4129.  
  4130. Declared:   in your program
  4131.  
  4132. Definition: in math.c (cclib.lib)
  4133.         short _math = 1;
  4134.  
  4135. Purpose:    if the gloabal variable _math is not defined to be 0 somewhere
  4136.         in your program then the IEEE math library
  4137.         "mathieeedoubbas.library" is opened for use by your program and
  4138.         by CClib.library. The default is a value of 1, which can be
  4139.         overridden by defining _math in your program.
  4140. -------------------------------------------------------------------------
  4141. Name:        MathIeeeDoubBasBase
  4142.  
  4143. Declared:   _main.c
  4144.  
  4145. Definition: void *MathIeeeDoubBasBase;
  4146.  
  4147. Purpose:    library base pointer for mathieeedoubbas.library
  4148. ---------------------------------------------------------------------
  4149. Name:        stderr
  4150.  
  4151. Declared:   stdio.h
  4152.  
  4153. Definition: in _main.c
  4154.         FILE *stderr;
  4155.  
  4156. Purpose:    a pointer to the stream used for standard error message output
  4157.  
  4158. See Also:   stdout
  4159. -------------------------------------------------------------------------
  4160. Name:        stdin
  4161.  
  4162. Declared:   stdio.h
  4163.  
  4164. Definition: in _main.c
  4165.         FILE *stdin;
  4166.  
  4167. Purpose:    a pointer to the stream used for standard input
  4168.  
  4169. See Also:   stdout, stderr
  4170. -------------------------------------------------------------------------
  4171. Name:        stdout
  4172.  
  4173. Declared:   stdio.h
  4174.  
  4175. Definition: in _main.c
  4176.         FILE *stdout;
  4177.  
  4178. Purpose:    a pointer to the stream used for standard output
  4179.  
  4180. See Also:   stdin
  4181. -------------------------------------------------------------------------
  4182. Name:        sys_errlist and sys_nerr
  4183.  
  4184. Declared:   stdio.h
  4185.  
  4186. Definition: syserr.c (cclib.lib)
  4187.         char *sys_errlist[] =
  4188.         {
  4189.         "No Error",
  4190.         "File Not Found",
  4191.         "Bad File Handle",
  4192.         "Not Enough Memory",
  4193.         "File Exists",
  4194.         "Invalid Function Number",
  4195.         "Too Many Files Opened",
  4196.         "Not A Console Device",
  4197.         "Invalid Access Code",
  4198.         };
  4199.         #define sys_nerr 9     /* the size of sys_errlist */
  4200.  
  4201. Purpose:    a listing of the error messages that correspond to the error
  4202.         codes returned in errno
  4203.  
  4204. See Also:   errno
  4205. -------------------------------------------------------------------------
  4206. Name:        SysBase                PRIVATE
  4207.  
  4208. Declared:   _main.c
  4209.  
  4210. Definition: void *SysBase;
  4211.  
  4212. Purpose:    library base pointer for exec.library
  4213. -------------------------------------------------------------------------
  4214. Name:        type                   PRIVATE
  4215.  
  4216. Declared:   ctype.h
  4217.  
  4218. Definition: in _main.c
  4219.         extern char *type;
  4220.  
  4221. Purpose:    points to the type array inside CClib.library that is used
  4222.         with the character test macros. ( islower() etc )
  4223. -------------------------------------------------------------------------
  4224. Name:        WBenchMsg
  4225.  
  4226. Declared:   _main.c
  4227.         struct WBStartup    is declared in workbench/startup.h
  4228.  
  4229. Definition: in _main.c
  4230.         struct WBStartup *WBenchMsg;
  4231.  
  4232. Purpose:    WBenchMsg is a pointer to the workbench startup message for
  4233.         your program, or NULL if the program was not started in the
  4234.         workbench environment.
  4235. -------------------------------------------------------------------------
  4236.  
  4237. ``    VI) INSTALLATION
  4238.  
  4239.    In order to use CClib.library you will first have to install the
  4240.    provided header files in a directory. Some of these header files
  4241.    have the same name as the ones used by your C and you will have to
  4242.    make sure that the CClib.library header files are found first. The
  4243.    best way to assure this is to use the -I or -i option of the compiler.
  4244.    When using floating point you will have to use the +FI or -fi options
  4245.    to ensure that IEEE floating point numbers are used, and you will
  4246.    have to link with the appropriate IEEE floating point library, ma.lib
  4247.    or lcmieee.lib. Before a prorgam that is linked with the CCLib.library
  4248.    can execute properly you must copy the file CCLib.library into the
  4249.    libs: directory on your system disk.
  4250.  
  4251.              For Aztec C
  4252.    When you link your program you will have to make sure that it gets
  4253.    linked in this order: _main.o yourstuff.o ... cclib.lib.... It would
  4254.    also be a good idea to look at the makefile for the test program;
  4255.    test.mke.
  4256.  
  4257.             For Lattice C
  4258.    When you link your program you will have to make sure that it gets
  4259.    linked in this order: cc.o lcmain.o yourstuff.o ... lcclib.lib.... It
  4260.    would also be a good idea to look at the makefile for the test program;
  4261.    test.lmk.
  4262.  
  4263.  
  4264. -------------------------------------------------------------------------
  4265.  
  4266. ``    VII) THE NUKELIB PROGRAM
  4267.  
  4268.       The nukelib program is used to remove a library from memory. The
  4269.       syntax of the program is very simple;
  4270.  
  4271.       NukeLib <library name>
  4272.  
  4273.       for example:
  4274.  
  4275.       NukeLib CClib.library
  4276.  
  4277.       This will clear CClib.library from memory if no applications are using
  4278.       it at the time.
  4279.  
  4280. -------------------------------------------------------------------------
  4281.  
  4282. ``    VIII) RELEASE INFORMATION
  4283.  
  4284.       This release contains:
  4285.  
  4286.       cclib.doc     this Documentation
  4287.       CClib.library    the loadable Amiga C library
  4288.       test        test program, (written in Aztec)
  4289.       install        installation script
  4290.  
  4291.       utils (dir)    Utilities directory
  4292.      utils.doc       utility program documentation
  4293.      bites           shows disk useage
  4294.      exec           shows Exec lists
  4295.      IFFCheck       checks IFF files
  4296.      noibm           changes \r\n to \n in files
  4297.      now           shows date in english
  4298.      setpri        sets tasks priorities
  4299.      nukelib       deletes libraries from memory
  4300.      loc           counts lines of C code
  4301.      xwait           waits for a specified time
  4302.  
  4303.       lib (dir)      Libraries directory
  4304.      cclib.lib       Aztec 5.0 library of connection routines
  4305.                (small code and data )
  4306.      cclibl.lib       (large code and data )
  4307.      lcclib.lib       Lattice library of connection routines
  4308.                (please see Lattice Notes)
  4309.  
  4310.       obj (dir)         Object code directory
  4311.      _main.o       Aztec 5.0  _main replacement
  4312.      lcmain.o       Lattice _main replacement
  4313.      cc.o           Modified Lattice startup routine
  4314.  
  4315.       source (dir)      Source code directory
  4316.      test.c        test program
  4317.      test.mke       Aztec 5.0 makefile
  4318.      test.lmk       Lattice makefile
  4319.      loc.c           utility counts lines of C
  4320.      loc.mke       Aztec 5.0 makefile
  4321.      _main.c       Aztec 5.0 _main routine
  4322.      lcmain.c       Lattice _main routine
  4323.      xwait.c       utility waits for a specified time
  4324.      xwait.mke       Azetec 5.0 makefile
  4325.  
  4326.       include (dir)     Include files required for CClib.library
  4327.     assert.h ccfunc.h ctype.h errno.h fcntl.h heapmem.h iolib.h
  4328.     limits.h process.h setjmp.h stat.h stdarg.h stddef.h stdio.h
  4329.     stdlib.h stdlist.h string.h time.h
  4330.  
  4331.       lharc (dir) Archiving program, use with con.lzh
  4332.      lharc           archiving program
  4333.      lharc.doc       archiving program documentation
  4334.      changes.txt       more documentation
  4335.  
  4336.       c (dir)
  4337.      muchmore       A text file viewer
  4338.  
  4339.       gcc (dir) PD compiler support
  4340.      CClib.lib       GCC compatible library (old)
  4341.      crt0.asm       regular startup code source
  4342.      crt0.o        regular startup code object
  4343.      crt0_no_fp.asm    no floating point startup code source
  4344.      crt0_no_fp.o       no floating point startup code source
  4345.  
  4346.       con (dir) Source to connection routine libraries
  4347.  
  4348.       con.lzh        Archived source for connection routine library
  4349.  
  4350.            Contents of con.lzh (Actual Connection routines)
  4351.       102.con 108.con 114.con 120.con  126.con 132.con 138.con 144.con
  4352.       150.con 156.con 162.con 168.con 174.con 180.con 186.con 192.con
  4353.       198.con 204.con 210.con 216.con 222.con 228.con 234.con 240.con
  4354.       246.con 252.con 258.con 264.con 270.con 276.con 282.con 288.con
  4355.       294.con  30.con 300.con 306.con 312.con 318.con 324.con 330.con
  4356.       336.con 342.con 348.con 354.con  36.con 360.con 366.con 372.con
  4357.       378.con 384.con 390.con 396.con 402.con 408.con 414.con  42.con
  4358.       420.con 426.con 432.con 438.con 444.con 450.con 456.con 462.con
  4359.       468.con 474.con  48.con 480.con 486.con 492.con 498.con 504.con
  4360.       510.con 516.con 522.con 528.con 534.con  54.con 540.con 546.con
  4361.       552.con 558.con 564.con 570.con 576.con 582.con 588.con 594.con
  4362.        60.con 600.con 606.con 612.con 618.con 624.con 630.con 636.con
  4363.       642.con 648.con 654.co   66.con 660.con 666.con 672.con 678.con
  4364.       684.con 690.con 696.con 702.con 708.con 714.con  72.con 720.con
  4365.       726.con 732.con 738.con 744.con 750.con 756.con 762.con 768.con
  4366.       774.con  78.con 780.con 786.con 792.con 798.con 804.con 810.con
  4367.       816.con 822.con 828.con 834.con  84.con 840.con 846.con 852.con
  4368.       858.con 864.con 870.con 876.con 882.con 888.con 894.con  90.con
  4369.       900.con 906.con 912.con  96.con
  4370.  
  4371.        all.con       Concatenation of connection routines
  4372.        blocksize.c       Contains blocksize global variable
  4373.        syserr.c       Contains sys_errlist[]
  4374.        cclib.mke       Aztec makefile for library (small code and data)
  4375.        cclibl.mke       Aztec makefile for library (large code and data)
  4376.        cclib.lmk       Lattice makefile for library
  4377.        libfile       Command file for Lattice librarian
  4378.        mclibcon.i       Metacomco Assembler include file
  4379.        aclibcon.i       Aztec Assembler include file
  4380.        lclibcon.i       Lattice Assembler include file
  4381.        cclibcon.i       Aztec Assembler include file
  4382.        math.c       Contains _math global variable
  4383.        setjmp.asm       Assembly source for setjmp & longjmp
  4384.  
  4385. -------------------------------------------------------------------------
  4386. ``    IX) NOTES ON LATTICE C
  4387.  
  4388.       There is now full support for the Lattice compiler. However due to
  4389.       some unforseen complications the Lattice startup code had to be
  4390.       changed in order for this to work. There is an object module called
  4391.       cc.o that should be used as the replacement for the standard Lattice
  4392.       startup routine (c.o).
  4393.  
  4394.       The specific problem with the startup code was this: For programs
  4395.       that were executed from the CLI the Lattice startup code would place
  4396.       the name of the program into the commnad string that was passed to
  4397.       _main and since CCLib.library already does this for you it was
  4398.       unnecessary to do this in the startup code. The symptoms of the
  4399.       problem were that argv[0] and argv[1] were both set to the name of
  4400.       the program. The problem with Workbench programs was far more
  4401.       serious, the Lattice startup code would reply to the workbench
  4402.       message after CClib.library had already done so, causing a system
  4403.       crash.
  4404.  
  4405.       Because of copyright problems the source for the modified c.a (cc.a)
  4406.       can't be included here, but since the only changes are commented out
  4407.       lines, I will list which lines were commented out. If you wish you
  4408.       may want to do this to c.a so that you have the source to the startup
  4409.       code. The lines commented out of c.a are: 189-198, 201-206, 227-229,
  4410.       247-283, and 323-336. In addition the label 'main' on line 283 was
  4411.       moved to line 284.
  4412.  
  4413.       If you are doing any floating point in your program it is best to use
  4414.       IEEE floating point numbers. This is supported by the -fi compiler
  4415.       switch and lcmieee.lib. This will give you the advantage of extra
  4416.       speed if you run on a machine with a math coprocessor. IEEE is the
  4417.       only type used by CCLib.library.
  4418.  
  4419.       There are new makefiles used for the Lattice compiler. All of the
  4420.       Lattice makefiles end with .lmk, where the Aztec makefiles end
  4421.       with .mke.
  4422.  
  4423.       Lattice 5 supports function prototypes where Aztec 3.6a does not.
  4424.       The CCLib.library include files can use function prototypes if the
  4425.       symbol ANSIC is defined. Be sure to include the CCLib.Library
  4426.       include files ahead of the standard Lattice and Amiga include files.
  4427.  
  4428.       Thanks to Kevin Kenny for help in creating the Lattice version of
  4429.       the connection routines and startup code.
  4430.  
  4431.       NOTE: Due to a lack of availability of a Lattic C compiler the
  4432.       Lattice version of the 3.0 connection routine library wasn't built,
  4433.       the 2.4 version was included. The makefile cclib.lmk will easily
  4434.       build the library.
  4435.  
  4436. -------------------------------------------------------------------------
  4437. ``    X) NOTES FOR PUBLIC DOMAIN COMPILERS
  4438.  
  4439.       A set of startup routines has been provided that works for GCC from
  4440.       Paul Gittings. They sould work for other public domain C compilers as
  4441.       well. The libraries of connection routines will have to be rebuilt
  4442.       using your public domain assembler and compiler. The startup code and
  4443.       a GCC compatible library is in the "gcc" directory.
  4444.  
  4445. -------------------------------------------------------------------------
  4446.  
  4447. ``    XI) REVISION HISTORY
  4448.  
  4449.        Version numbers only change when the file CClib.library
  4450.        changes.
  4451.  
  4452.     8/89 - V2.0 Initial release, beta testing.
  4453.  
  4454.     9/89 - V2.1 Major bug fixes, documentation released, extensive testing,
  4455.        time functions added, nukelib program added.
  4456.  
  4457.    10/89 - V2.1 Release 2 Support for Lattice C added,
  4458.        doumentation improvements.
  4459.  
  4460.    10/89 - V2.2 A bug was fixed where programs that were executed from the
  4461.        workbench with no tooltype of the form
  4462.        WINDOW=CON:10/10/100/100/Title would fail because the startup
  4463.        code had required that standard I/O be opened. Now for workbench
  4464.        programs with no CON: window the standard I/O will not be opened.
  4465.  
  4466.    10/89 - V2.3 A bug in the quicksort function was fixed. The auxilery
  4467.        argument is now passed correctly to the swap function as well
  4468.        as the comp function. CClibl.lib was added to support large
  4469.        code and data in Aztec C. LOC a C code line counting program
  4470.        was added.
  4471.  
  4472.    11/89 - V2.4 A bug in the scdir function was fixed where the a path
  4473.        that contained only a volume name would not be searched.
  4474.  
  4475.    2/90  - V2.5  Conversion to Aztec C 5.0
  4476.  
  4477.    4/90  - V2.6 The scdir_clean function was added.
  4478.  
  4479.    6/90  - V2.7 toupper and tolower were converted to functions and added
  4480.         to the library, changes made in ctype.h. The macros
  4481.         _toupper and _tolower now do the same thing as the old
  4482.         macros; not check for isupper or islower first. The same
  4483.         bug would have caused problems with the strcmpa() function
  4484.         in the string library.
  4485.  
  4486.         Connection routine vector 172 was incorrect and was changed
  4487.         to 174, it is the vector for setvbuf.
  4488.  
  4489.         Thanks to Detlef Wurkner for pointing out some serious bugs
  4490.         with toupper, tolower and library entry number 172.
  4491.  
  4492.    9/90  - V3.0 Major Revision includes:
  4493.  
  4494.         Support for GCC from Paul Gittings
  4495.  
  4496.         The following new functions with documentation:
  4497.         stat_ getenv setenv wb_exec wbexec wbAexec wait_child
  4498.         wait_children signal_child kill kill_children cliexec
  4499.         exec offsetof setjmp longjmp
  4500.  
  4501.         A reorganization of the documentation to include the
  4502.         new section for process control functions.
  4503.  
  4504.         A new section of the documentation for the documentation
  4505.         of data structures used by and with the library.
  4506.  
  4507.         A new section of the documentation describing the global
  4508.         variables that are accessible to the application program.
  4509.  
  4510.         Improved table of contents
  4511.  
  4512.         New Index section of the manual
  4513.  
  4514. -------------------------------------------------------------------------
  4515.  
  4516. ``    XII) COPYRIGHTS AND TRADEMARKS
  4517.  
  4518.       Aztec C is a trademark of Manx Software Systems.
  4519.       Lattice C is a trademark of Lattice Inc.
  4520.       Amiga is a trademark of Commodore Business Machines Inc.
  4521.  
  4522. -------------------------------------------------------------------------
  4523.  
  4524. ``    XIII)  INDEX
  4525.  
  4526.              A
  4527.  
  4528.        Name          Section      Header
  4529.  
  4530.      abort              III-12      stdlib.h
  4531.      access           III-3      ccfunc.h
  4532.      add_head          III-9      stdlist.h
  4533.      add_tail          III-9      stdlist.h
  4534.      agetc              III-2      stdio.h
  4535.      _alloc           III-8      ccfunc.h
  4536.      aputc              III-2      stdio.h
  4537.      asctime          III-11      time.h
  4538.      atexit           III-12      stdlib.h
  4539.      atof              III-7      stdlib.h
  4540.      atoi              III-7      stdlib.h
  4541.      atol              III-7      stdlib.h
  4542.  
  4543.              B
  4544.  
  4545.      bcopy              III-6      string.h
  4546.      bcpl_strcpy          III-5      string.h
  4547.      bcpm              III-6      string.h
  4548.      be_free          III-8      ccfunc.h
  4549.      blocksize          V       ---
  4550.      bzero              III-6      string.h
  4551.  
  4552.              C
  4553.  
  4554.      calloc           III-8      stdlib.h
  4555.      CCLibBase          V       ---
  4556.      Child              IV      iolib.h
  4557.      ClearAbortFunc       III-12      ccfunc.h
  4558.      clearerr          III-2      stdio.h
  4559.      ClearSTDIO          III-1      ccfunc.h
  4560.      cliexec          III-12      process.h
  4561.      cli_parse          III-1      ccfunc.h
  4562.      clock              III-11      time.h
  4563.      clock_t          IV      time.h
  4564.      close              III-3      ccfunc.h
  4565.      closeall          III-1      ccfunc.h
  4566.      creat              III-3      ccfunc.h
  4567.      ctime              III-11      time.h
  4568.  
  4569.              D
  4570.  
  4571.      difftime          III-11      time.h
  4572.      DOSBase          V       ---
  4573.  
  4574.              E
  4575.  
  4576.      errno              V       errno.h
  4577.      exec              III-12      process.h
  4578.      exit and _exit()     III-12      stdlib.h
  4579.      exit_fcn          V       stdlib.h
  4580.  
  4581.              F
  4582.  
  4583.      fclose           III-2      stdio.h
  4584.      fdopen           III-2      ccfunc.h
  4585.      feof              III-2      stdio.h
  4586.      ferror           III-2      stdio.h
  4587.      fflush           III-2      stdio.h
  4588.      fgetc              III-2      stdio.h
  4589.      fgetpos          III-2      stdio.h
  4590.      fgets              III-2      stdio.h
  4591.      FILE              IV      stdio.h
  4592.      FileDesc          IV      iolib.h
  4593.      fileno           III-3      stdio.h
  4594.      fopen              III-2      stdio.h
  4595.      fpos_t           IV      stddef.h
  4596.      fprintf          III-2      stdio.h
  4597.      fputc              III-2      stdio.h
  4598.      fputs              III-2      stdio.h
  4599.      fread              III-2      stdio.h
  4600.      _fre              III-8      ccfunc.h
  4601.      _freall          III-8      ccfunc.h
  4602.      free              III-8      stdlib.h
  4603.      freeall          III-8      ccfunc.h
  4604.      freopen          III-2      stdio.h
  4605.      fscanf           III-2      stdio.h
  4606.      fseek              III-2      stdio.h
  4607.      fsetpos          III-2      stdio.h
  4608.      ftell              III-2      stdio.h
  4609.      fwrite           III-2      stdio.h
  4610.  
  4611.              G
  4612.  
  4613.      getbuff          III-2      ccfunc.h
  4614.      getc              III-2      stdio.h
  4615.      getchar          III-2      stdio.h
  4616.      getchar          III-2      stdio.h
  4617.      getenv           III-12      stdlib.h
  4618.      gets              III-2      stdio.h
  4619.      GetSTDIO          III-1      ccfunc.h
  4620.      getw              III-2      stdio.h
  4621.      gmtime           III-11      time.h
  4622.  
  4623.              H
  4624.  
  4625.      HEADER           IV      heapmem.h
  4626.      heap_alloc          III-8      ccfunc.h
  4627.      heap_free          III-8      ccfunc.h
  4628.  
  4629.              I
  4630.  
  4631.      index              III-5      string.h
  4632.      inst_node          III-9      stdlist.h
  4633.      isalnum          III-4      ctype.h
  4634.      isalpha          III-4      ctype.h
  4635.      isascii          III-4      ctype.h
  4636.      isatty           III-3      ccfunc.h
  4637.      iscntrl          III-4      ctype.h
  4638.      isdigit          III-4      ctype.h
  4639.      isgraph          III-4      ctype.h
  4640.      islower          III-4      ctype.h
  4641.      isprint          III-4      ctype.h
  4642.      ispunct          III-4      ctype.h
  4643.      isspace          III-4      ctype.h
  4644.      isupper          III-4      ctype.h
  4645.      isxdigit          III-4      ctype.h
  4646.  
  4647.              K
  4648.  
  4649.      kill              III-12      process.h
  4650.      kill_children          III-12      process.h
  4651.  
  4652.              L
  4653.  
  4654.      LastFree          IV      heapmem.h
  4655.      _list              IV      stdlist.h
  4656.      localtime          III-11      time.h
  4657.      longjmp          III-12      setjmp.h
  4658.      lseek              III-3      ccfunc.h
  4659.      ltoa              III-7      stdlib.h
  4660.  
  4661.              M
  4662.  
  4663.      malloc           III-8      stdlib.h
  4664.      malloc_size          III-8      ccfunc.h
  4665.      _math              V       ---
  4666.      MathIeeeDoubBasBase  V       ---
  4667.      MemBlk           IV      iolib.h
  4668.      memccpy          III-6      string.h
  4669.      memchr           III-6      string.h
  4670.      memcpy           III-6      string.h
  4671.      memmove          III-6      string.h
  4672.      memset           III-6      string.h
  4673.      memswap          III-6      string.h
  4674.      mktemp           III-2      ccfunc.h
  4675.      mktime           III-11      time.h
  4676.  
  4677.              N
  4678.  
  4679.      _node              IV      stdlist.h
  4680.  
  4681.              O
  4682.  
  4683.      offsetof          III-1      stddef.h
  4684.      open              III-3      ccfunc.h
  4685.  
  4686.              P
  4687.  
  4688.      perror           III-12      stdio.h
  4689.      printf           III-2      stdio.h
  4690.      ptrdiff_t          IV      stddef.h
  4691.      putc              III-2      stdio.h
  4692.      putchar          III-2      stdio.h
  4693.      putchar          III-2      stdio.h
  4694.      puterr           III-2      ccfunc.h
  4695.      puts              III-2      stdio.h
  4696.      putw              III-2      stdio.h
  4697.      put_head          III-9      stdlist.h
  4698.      put_tail          III-9      stdlist.h
  4699.  
  4700.              Q
  4701.  
  4702.      qsort              III-10      stdlib.h
  4703.      quicksort          III-10      ccfunc.h
  4704.  
  4705.              R
  4706.  
  4707.      read              III-3      ccfunc.h
  4708.      realloc          III-8      stdlib.h
  4709.      remove           III-2      stdio.h
  4710.      remv_head          III-9      stdlist.h
  4711.      remv_list          III-9      stdlist.h
  4712.      remv_node          III-9      stdlist.h
  4713.      remv_tail          III-9      stdlist.h
  4714.      rename           III-2      stdio.h
  4715.      rewind           III-2      stdio.h
  4716.      rindex           III-5      string.h
  4717.      r_node           III-9      stdlist.h
  4718.  
  4719.              S
  4720.  
  4721.      sbrk              III-8      ccfunc.h
  4722.      scanf              III-2      stdio.h
  4723.      scdir              III-1      ccfunc.h
  4724.      scdir_clean          III-1      ccfunc.h
  4725.      SetAbortFunc          III-12      ccfunc.h
  4726.      setbuf           III-2      stdio.h
  4727.      setenv           III-12      stdlib.h
  4728.      setjmp           III-12      setjmp.h
  4729.      SetSTDIO          III-1      ccfunc.h
  4730.      SetupSTDIO          III-1      ccfunc.h
  4731.      setvbuf          III-2      stdio.h
  4732.      signal_child          III-12      process.h
  4733.      size_t           IV      stddef.h
  4734.      sprintf          III-2      stdio.h
  4735.      sscanf           III-2      stdio.h
  4736.      stat              III-2      stat.h
  4737.      stat              IV      stat.h
  4738.      stat_              III-2      stdio.h
  4739.      stderr           V       stdio.h
  4740.      stdin              V       stdio.h
  4741.      stdout           V       stdio.h
  4742.      stoa              III-7      stdlib.h
  4743.      stpcrlf          III-5      string.h
  4744.      strcat           III-5      string.h
  4745.      strchr           III-5      string.h
  4746.      strcmp           III-5      string.h
  4747.      strcmpa          III-5      string.h
  4748.      strcpy           III-5      string.h
  4749.      strcspn          III-5      string.h
  4750.      strerror          III-5      string.h
  4751.      strftime          III-11      time.h
  4752.      strlen           III-5      string.h
  4753.      strncat          III-5      string.h
  4754.      strncmp          III-5      string.h
  4755.      strncpy          III-5      string.h
  4756.      strnrv           III-5      string.h
  4757.      strpbrk          III-5      string.h
  4758.      strrchr          III-5      string.h
  4759.      strrv              III-5      string.h
  4760.      strspn           III-5      string.h
  4761.      strstr           III-5      string.h
  4762.      strtok           III-5      string.h
  4763.      struct tm          IV      time.h
  4764.      strupr           III-5      string.h
  4765.      SysBase          V       ---
  4766.      system           III-12      stdlib.h
  4767.      sys_errlist/sys_nerr V       stdio.h
  4768.  
  4769.              T
  4770.  
  4771.      task_UserData          IV      iolib.h
  4772.      time              III-11      time.h
  4773.      time_t           IV      time.h
  4774.      tmpfile          III-2      stdio.h
  4775.      tmpnam           III-2      stdio.h
  4776.      toascii          III-4      ctype.h
  4777.      tolower          III-4      ctype.h
  4778.      _tolower          III-4      ctype.h
  4779.      toupper          III-4      ctype.h
  4780.      _toupper          III-4      ctype.h
  4781.      type              V       ctype.h
  4782.  
  4783.              U
  4784.  
  4785.      ungetc           III-2      stdio.h
  4786.      unlink           III-3      stdio.h
  4787.  
  4788.              V
  4789.  
  4790.      va_list          IV      stdarg.h
  4791.      vfprintf          III-2      stdio.h
  4792.      vprintf          III-2      stdio.h
  4793.      vquicksort          III-10      ccfunc.h
  4794.      vsprintf          III-2      stdio.h
  4795.  
  4796.              W
  4797.  
  4798.      wait_child          III-12      process.h
  4799.      wait_children          III-12      process.h
  4800.      wbAexec          III-12      process.h
  4801.      WBenchMsg          V       ---
  4802.      wb_exec          III-12      process.h
  4803.      wb_parse          III-1      ccfunc.h
  4804.      wchar_t          IV      stddef.h
  4805.      write              III-3      ccfunc.h
  4806.  
  4807. -------------------------------------------------------------------------
  4808.  
  4809.