home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / newlibs / cclib.lzh / cclib.doc < prev    next >
Text File  |  1989-09-25  |  112KB  |  3,243 lines
  1.  
  2.          Documentation for CClib.library V1.1
  3.  
  4.     Copyright (C) 1989 by Robert W. Albrecht, All Rights Reserved.
  5.  
  6.        Software and Documentation written and distributed by:
  7.  
  8.             Robert W. Albrecht Jr.
  9.             1457 Zion Way
  10.             Ventura, CA 93003, USA
  11.  
  12. -------------------------------------------------------------------------
  13.  
  14.    INTRODUCTION
  15.  
  16.    This is an implementation of the standard C library, with a few extra
  17.    goodies thrown in, that is done as an Amiga loadable library. This
  18.    allows many applications to share the same library code, saving disk
  19.    space, and probably RAM if more than one application is running at a
  20.    time. The other advantage of the library is that as improvements are
  21.    made to it improvements are made to the programs that use it, and the
  22.    programmer doesn't even have to know about it. From the very early Amiga
  23.    days I have thought that this should have been done by CBM, but it
  24.    wasn't, and I was a little suprised that no one else had either. Well,
  25.    after I started I found out why it hadn't been done; It is real tricky
  26.    to make the C library re-entrant. Also it turns out that there are over
  27.    one hundred and forty functions in the library.
  28.  
  29.    My motivation behind doing this project was that I needed a large
  30.    scientific application to be able to run effectivly on a single floppy
  31.    Amiga 500 system, and still have space left over for data files. Since
  32.    the only way to do what I wanted to do was to eliminate the overhead of
  33.    the C library from every program in the package, I had to write this
  34.    library.
  35.  
  36.    THIS IS NOT PUBLIC DOMAIN. You can however create public domain programs
  37.    that use it, but you MUST pay a $50 license fee for Version 2.0 or above
  38.    to use it with commercial software. For the $50 license fee you will
  39.    also get a library used for writing C programs with an "Object Oriented"
  40.    style. This library has objects for Windows, Buttons, Keyins, and many
  41.    more. Also the objects library will allow you to write interactive
  42.    programs much faster, and of better quality, than you could without it.
  43.    Also included in the object library is a help facility that allows the
  44.    user to press the right mouse button and get help for the object the
  45.    mouse pointer is over. So if you are a commercial software developer
  46.    or just a home hobbiest you will want a copy of Version 2.0.
  47.  
  48.    If anyone is interested in translating the software and/or documentation
  49.    to another language, I would be very interested. Please write me at
  50.    the above address if you are interested in the project. We might be
  51.    able to work out some kind of deal where you would get 100% of the
  52.    net receipts for the first 20 licenses, or something like that. I
  53.    would be particularly be interested in German, French, and Italian.
  54.  
  55. -------------------------------------------------------------------------
  56.  
  57.             CONTENTS
  58.  
  59.    I) LICENSE
  60.       Transfer
  61.       Backup Copies
  62.       Term
  63.       Robert W. Albrecht's rights
  64.       Disclaimer of other Warranties, and Liabilities
  65.  
  66.    II) RUN-TIME IMPLEMENTATION OF CCLIB.LIBRARY
  67.    III) FUNCTION DOCUMENTATION
  68.       1) SUPPORT FUNCTIONS
  69.       2) STREAM I/O FUNCTIONS
  70.       3) NON-STANDARD AND LOW-LEVEL I/O FUNCTIONS
  71.       4) CHARACTER TEST MACROS
  72.       5) STRING FUNCTIONS
  73.       6) MEMORY OPERATION FUNCTIONS
  74.       7) FORMAT CONVERSION FUNCTIONS
  75.       8) MEMORY ALLOCATION FUNCTIONS
  76.       9) LINKED LIST FUNCTIONS
  77.       10) SORTING FUNCTIONS
  78.       11) TIME FUNCTIONS
  79.    IV) INSTALLATION
  80.    V) THE NUKELIB PROGRAM
  81.    VI) RELEASE INFORMATION
  82.    VII) REVISION HISTORY
  83.    VIII) COPYRIGHTS AND TRADEMARKS
  84.  
  85. -------------------------------------------------------------------------
  86.  
  87.       I) LICENSE
  88.  
  89.       Robert W. Albrecht is the exclusive owner of the enclosed Software
  90.       and Documentation. You are granted non-exclusive license to use the
  91.       Software and Documentation, but you are not the owner of them.
  92.      Your right to use the Software and Documentation under this
  93.       agreement is the "License". "You" means the individual or legal
  94.       entity whose agent receives this software and accepts this Agreement.
  95.       "Software" means the computer program recorded on the floppy-disk or
  96.       other media, any update to them Robert W. Albrecht may later provide
  97.       you, and any back-up copies made. "Documentation" means the user
  98.       manual and other materials packaged with this Software.
  99.  
  100.                 Transfer
  101.  
  102.       You may transfer the license for the use of the Software or
  103.       Documentation to another person free of charge. No charge may
  104.       be made for the Software or Documentation, this includes Public
  105.       Domain Disks and Shareware Disks. If you are the distributor of
  106.       Public Domain disks and you wish to distribute the software at
  107.       a nominal charge please send a stamped self-addressed envelope
  108.       along with a letter stating your intent to the above address, all
  109.       reasonable requests will be granted. Also this version of
  110.       CClib.library can NOT be distributed with commercial software.
  111.       In order to distribute CClib.library with your commercial software
  112.       you MUST pay the one time $50 license fee for Version 2.0 or above
  113.       of CClib.library.
  114.  
  115.               Backup Copies
  116.  
  117.          Make as many copies as you want.
  118.  
  119.                   Term
  120.  
  121.       The license is effective for twenty (20) years from the time you
  122.       receive the software. You may terminate the license at any time by
  123.       returning all software and documentation.
  124.  
  125.             Robert W. Albrecht's rights.
  126.  
  127.       The CClib.library Software and Documentation is protected by copyright,
  128.       trade secret and trademark laws. You may not disclose the Software or
  129.       Documentation to others, except as allowed in this license agreement,
  130.       or remove or alter ownership, trademark and copyright notices on
  131.       Documentation or Software. YOU MUST MAKE A GOOD FAITH EFFORT TO
  132.       PREVENT ANY UNAUTHORIZED USE, COPYING, OR DISCLOSURE OF THE SOFTWARE
  133.       OR DOCUMENTATION. THESE OBLIGATIONS WILL SURVIVE ANY TERMINATION OF
  134.       THE LICENSE AGREEMENT.
  135.  
  136.          Disclaimer of other Warranties, and Liabilities.
  137.  
  138.       THERE ARE NO WARRANTIES, EITHER EXPRESSED OR IMPLIED, FOR THE
  139.       SOFTWARE OR DOCUMENTATION, WHICH ARE BOTH LICENSED TO YOU "AS IS".
  140.       ROBERT W. ALBRECHT EXPRESSLY DISCLAIMS ANY WARRANTY AS TO THE
  141.       PERFORMANCE OF THE SOFTWARE, OR DOCUMENTATION. HE ALSO DISCLAIMS ALL
  142.       OTHER WARRANTIES, INCLUDING (WITHOUT LIMITATION) IMPLIED WARRANTIES
  143.       OF MERCANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
  144.       SHALL ANYONE INVOLVED IN THE CREATION, PRODUCTION, OR DISTRIBUTION,
  145.       OF THE SOFTWARE OR DOCUMENTATION BE LIABLE FOR ANY INDIRECT, SPECIAL,
  146.       INCEDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OF THE
  147.       SOFTWARE OR DOCUMENTATION OR ARISING FROM ANY BREACH OF ANY WARRANTY.
  148.       Some states do not allow the exclusion or limitation of implied
  149.       warranties or liability for incedental or consequential damages so
  150.       the above exclusion and limitation may not apply to you. IN ADDITON
  151.       TO THE ABOVE LIMITATION, OUR LIABILITY TO YOU OR TO ANYONE ELSE FOR
  152.       DAMAGES SHALL NOT EXCEED THE LICENSE FEE PAID BY YOU FOR THE SOFTWARE
  153.       AND DOCUMENTATION.
  154.  
  155. -------------------------------------------------------------------------
  156.  
  157.    II) RUN-TIME IMPLEMENTATION OF CCLIB.LIBRARY
  158.  
  159.    The implementation of this library is designed to be as transparent as
  160.    possible to the C programmer, but is good to be aware of the actions that
  161.    are taken by the library accomplish this.
  162.  
  163.    The actual code for most of the standard C library functions is in the
  164.    file CClib.library. This is a standard Amiga dynamic link library (DLL)
  165.    and can be shared by many application programs at the same time. For the
  166.    library to work correctly it must be installed in the LIBS: directory of
  167.    your system disk.
  168.  
  169.    DLL's on the Amiga are accessed through the OpenLibrary and CloseLibrary
  170.    system (Exec) functions. When a library is opened with the OpenLibrary
  171.    function, and it is not yet loaded into RAM, Amiga DOS will go to the
  172.    LIBS: directory and load the library specified in the OpenLibrary
  173.    function. The OpenLibrary function will return the memory location of
  174.    the Library structure for the requested library, this is called the
  175.    Library Base Pointer (LBP). A table of jump instructions is located at a
  176.    negative offset to the LBP and the actual functions in the library are
  177.    accessed through this table. For each function in CClib.library there is
  178.    a connection routine in CClib.lib that will allow the application
  179.    program access to the functions in the library. The connection routines
  180.    contain two 68000 instructions: move the LBP into address register A6,
  181.    and jump to an entry in the table of jump instructions in the library.
  182.    The offset from the LBP that gets jumped to in the DLL depends on the
  183.    specific function in the library. All of these details are, of course,
  184.    transparent to the normal user of CClib.library. In order to make the
  185.    interface to the C language more efficient, the convention of placing
  186.    arguments to functions in registers was not used. Instead the
  187.    C calling convention of placing arguments on the stack in reverse
  188.    order was followed. This greatly simplified the connection routines
  189.    that get linked into your application.
  190.  
  191.    To create an implementation of the C library that is as transparent as
  192.    possible to the application the _main function, or initialization code,
  193.    and the _exit function, had to be re-written such that the _main
  194.    function opens the C library and the _exit function closes the C
  195.    library. For this reason these routines could not be included in the
  196.    DLL. You must link with the special version of _main and _exit that are
  197.    contained in the file _main.o. The _main routine must also set up stdin,
  198.    stdout, and stderr for the application, as well as handle the Amiga
  199.    Workbench environment. Also if your program needs access to functions in
  200.    the DLL that use floating point numbers the _main routine must open the
  201.    IEEE floating point library and give a pointer to this library to
  202.    CClib.library. As you may know there are a number of different floating
  203.    point options on the Amiga.
  204.  
  205.    In order to implement floating point operations in the DLL it was
  206.    necessacary to choose just one of the possible floating point options of
  207.    the Amiga. The one that is used by the DLL is the
  208.    MathIeeeDoubBas.library. The reason for using this one is that it is has
  209.    standard 64 bit IEEE floating point numbers and there is a version of
  210.    this library for the 68881 and 68882 MPUs. This means that users of
  211.    Aztec C will have to link with ma32.lib if there are any floating point
  212.    operations in the application. For users of the DLL who will have no
  213.    need for floating point numbers in their application the global short
  214.    integer _math can be declared with a value of zero and
  215.    MathIeeeDoubBas.library will not be loaded by the _main function. The
  216.    whole reason for the Ieee floating point number requirement comes from the
  217.    fact that the code for the DLL can be shared by many applications. There
  218.    are other restrictions as well that arise from this fact.
  219.  
  220.    The C data type 'int' is a 32 bit quantity. The reason that ints are 32
  221.    bits instead of 16 bits is that the 68000 is a 32 bit processor and ints
  222.    are 32 bits in Lattice C. Aztec C has compiler switches that make ints
  223.    32 bits. The DLL really doesn't care what an int is inside your program
  224.    but it does care what the arguments passed to it's functions are. When
  225.    an argument is passed to a CClib function it must be promoted to an int
  226.    before being put on the stack, if it is smaller that an int. In Aztec C
  227.    the easest way to ensure this is to use the +L compiler switch. Another
  228.    way to handle this is to cast 8 and 16 bit arguments to a 32 bit
  229.    quantity.
  230.  
  231.    Another issue that arises from the fact that the DLL code is shared, is
  232.    the problem of re-entrancy. CClib must not modify it's own data in such
  233.    a way it can't be re-used by another application, but some functions in
  234.    any C library implementation must, by nature, use global data. For
  235.    instance the heap memory manager must keep track of a list of free
  236.    memory blocks, and must do so in a way that is transparent to the
  237.    application. It would not due for all of the users of the DLL to share
  238.    the same free memory list. This means that the DLL must allocate a block
  239.    of memory for each of it's users and somehow know which block to use. It
  240.    turns out that there is a very simple way to implement this on the
  241.    Amiga. Every Amiga task must have a Task structure associated with it so
  242.    that Exec can keep track of it. To obtain a pointer to the currently
  243.    running task you call the Exec function FindTask with an argument of
  244.    zero. Also there is an unused member of the Task structure called
  245.    tc_UserData. When the DLL initializes your task it allocates some memory
  246.    from Exec and makes tc_UserData point to that memory. Whenever you call
  247.    a CClib function that requires the use of global data it acceses the
  248.    memory block attached to your task's tc_UserData field. For this reason
  249.    you had better not mess around with your task's tc_UserData member and
  250.    expect CClib to work.
  251.  
  252.    The implementation of file handles and FILE pointers is quite different
  253.    than the implementation in other C libraries. Most C libraries keep a
  254.    static array of FILE structures and a static array of file handles. This
  255.    method is just fine for systems which have a built-in limit as to the
  256.    number of open files a single task can have, but it doesn't make any
  257.    sense for a computer that has no such limitation. For this reason the
  258.    FILE structures and file handles are implemented as linked lists in
  259.    the DLL. This improvement does have one side effect though, there are
  260.    no pre-opened file handles, for example 1 is not the low-level file handle
  261.    for stdio. Instead of hard-coding the low-level file handles you will
  262.    have to use the fileno() macro defined in stdio.h, for example:
  263.    write(fileno(stdin),"Hello World",11L);
  264.  
  265.    Despite these restrictions due to the implementation of the library
  266.    it is hoped that you will find this library useful. Be sure to look at
  267.    the example programs for more information.
  268.  
  269. -------------------------------------------------------------------------
  270.  
  271.    III) FUNCTION DOCUMENTATION
  272.  
  273.    The documentation of the functions in the library follows this format:
  274.  
  275. -------------------------------------------------------------------------
  276. Name:           The name of the C function or macro    [MACRO] =
  277.                               this is a macro
  278.  
  279. Synopsis:      The outline of the function with the type of the argumets
  280.            and the return value.
  281.  
  282. Function:      What actions are taken by this function.
  283.  
  284. Arguments:     An explanation of the arguments to this function.
  285.  
  286. Return:        The return value of the function, and what indicates an
  287.            error condition. It is also indicated if any global variables
  288.            are set by this function.
  289.  
  290. See Also:      Other documentation that will lead to a further understanding
  291.            of the function.
  292. -------------------------------------------------------------------------
  293.  
  294.    1) SUPPORT FUNCTIONS
  295.  
  296.    Some of these functions are not a normal part of a C library but are
  297.    used to support this implementation. Other functions are here because
  298.    they don't fit into another category.
  299.  
  300. -------------------------------------------------------------------------
  301. Name:        abort                 MACRO
  302.  
  303. Synopsis:   #include "stdlib.h"
  304.         void abort()
  305.  
  306. Function:   This is a macro that causes abnormal program termination. It
  307.         is equivalent to exit(EXIT_FAILURE).
  308.  
  309. See Also:   exit
  310. -------------------------------------------------------------------------
  311. Name:        atexit                 MACRO
  312.  
  313. Synopsis:   #include "stdlib.h"
  314.         void atexit( func )
  315.         void (*func)();
  316.  
  317. Function:   Sets the atexit function that is executed when the program
  318.         terminates through a call to exit or _exit. Any existing
  319.         atexit function is over-written. This is defined as a macro
  320.         in stdlib.h.
  321.  
  322. Arguments:  func - a pointer to your atexit function
  323.  
  324. See Also:   exit
  325. -------------------------------------------------------------------------
  326. Name:        ClearAbortFunc
  327.  
  328. Synopsis:   void ClearAbortFunc()
  329.  
  330. Function:   Clears the break signal abort function. A call to this function
  331.         will disable program termination when a ^C or a break is sent
  332.         to it with the AmigaDOS break command.
  333.  
  334. See Also:   SetAbortFunc
  335. -------------------------------------------------------------------------
  336. Name:        ClearSTDIO
  337.  
  338. Synopsis:   void ClearSTDIO()
  339.  
  340. Function:   Returns resources to the system that were used by a process
  341.         using CClib.library. All files are closed and all allocated
  342.         memory is freed. The task's tc_UserData field is re-set to
  343.         it's original condition.
  344.  
  345. See Also:   SetSTDIO, SetupSTDIO
  346. -------------------------------------------------------------------------
  347. Name:        closeall
  348.  
  349. Synopsis:   void closeall()
  350.  
  351. Function:   Closes all opened stream files and low-level files.
  352.  
  353. See Also:   ClearSTDIO
  354. -------------------------------------------------------------------------
  355. Name:        cli_parse
  356.  
  357. Synopsis:   void cli_parse(ud,alen,aptr)
  358.         task_UserData *ud;
  359.         long alen;
  360.         char *aptr;
  361.  
  362. Function:   Parses the command line arguments into argc and argv for
  363.         the main routine. Called only when the program is executed
  364.         from the CLI.
  365.  
  366. Arguments:  ud - a pointer to the task's user data structure.
  367.         alen - the length of the command string passed to the program
  368.         from AmigaDOS.
  369.         aptr - a pointer to the command string passed to the program from
  370.         AmigaDOS.
  371.  
  372. See Also:   wb_parse
  373. -------------------------------------------------------------------------
  374. Name:        exit and _exit()
  375.  
  376. Synopsis:   void exit(code)     void _exit(code)
  377.         long code;        long code;
  378.  
  379. Function:   Causes normal program termination. The atexit() function is
  380.         executed  Open files and streams are closed and flushed, memory
  381.         is de-allocated and returned to the system. Exit may also be
  382.         called when a break signal is received from Amiga DOS.
  383.  
  384. Arguments:  code - the return code of the program. The values EXIT_SUCCESS
  385.         and EXIT_FAILURE may also be used.
  386.  
  387. See Also:   abort, atexit
  388. -------------------------------------------------------------------------
  389. Name:        GetSTDIO
  390.  
  391. Synopsis    task_UserData *GetSTDIO()
  392.  
  393. Function:   Gets a pointer to the block of memory used for global data
  394.         for this task. This function is written in assembly language
  395.         because it is used quite frequently by the library. The
  396.         task_UserData structure is defined in iolib.h.
  397.  
  398. Return:     A pointer to the task's user data block, or NULL if it isn't
  399.         initialized yet.
  400.  
  401. See Also:   SetSTDIO
  402. -------------------------------------------------------------------------
  403. Name:        scdir
  404.  
  405. Synopsis:   char *scdir(pattern)
  406.         char *pattern;
  407.  
  408. Function:   This function is used to support wild card file names using
  409.         '*' and '?' where '*' matches any number of characters and
  410.         '?' matches any single character. To use the function simply
  411.         pass the pattern to the function and keep calling it until
  412.         NULL is returned. For example:
  413.         while( name = scdir("*.c") ) do_something(name);
  414.  
  415. Warning:    This function allocates memory from the system that is not
  416.         freed until it returns NULL. So that the memory gets returned
  417.         to the system be sure keep calling it until NULL is returned,
  418.         if you don't the memory will remain allocated until the program
  419.         exits. Also the file pattern is irrelavent after the first call
  420.         to scdir because it remembers the pattern in it's own memory.
  421.         The memory used by scdir is pointed to by
  422.         task_UserData.scdir_mem and if you wish to scan another directory
  423.         before the current one is finished you can save this pointer,
  424.         set it to NULL, scan the other directory, restore the pointer
  425.         and then keep calling scdir until NULL is returned.
  426.  
  427. Arguments:  pattern - the file name pattern.
  428.  
  429. Return:     A pointer to a file name that matches the pattern or NULL.
  430. -------------------------------------------------------------------------
  431. Name:        SetAbortFunc
  432.  
  433. Synopsis:   void SetAbortFunc(func)
  434.         long (*func)();
  435.  
  436. Function:   Sets the break signal abort function. Whenever a break signal
  437.         is detected from AmigaDOS, sent either by a ^C from the console
  438.         or from an AmigaDOS break command, the library will see if there
  439.         is an abort function, and if there is it will be executed with
  440.         the signals that caused it to be executed as an argument. The
  441.         signals will be in a 32 bit integer. During normal operation
  442.         the function _exit is the abort function, however you may wish
  443.         to set it to something else so that you can clean up whatever
  444.         your application is doing at the time. If you intend to exit
  445.         from the program call the exit or _exit functions, not the
  446.         AmigaDOS Exit function,  or else resources allocated by
  447.         the library will not be de-allocated.
  448.  
  449. Arguments:  func - a pointer to the abort function to be used when a
  450.         break signal is received.
  451.  
  452. See Also:   ClearAbortFunc
  453. -------------------------------------------------------------------------
  454. Name:        SetSTDIO
  455.  
  456. Synopsis:   long SetSTDIO()
  457.  
  458. Function:   Allocates memory for a task_UserData structure and attaches
  459.         it to the tc_UserData field of the task structure.
  460.  
  461. Return:     Zero is returned if the operation was a success, otherwise
  462.         one is returned.
  463.  
  464. See Also:   SetupSTDIO
  465. -------------------------------------------------------------------------
  466. Name:        SetupSTDIO
  467.  
  468. Synopsis:   long SetupSTDIO(ud,in,out,err,errno,bsize,ctyp,mathbase)
  469.         FILE **in, **out, **err;
  470.         long *errno, *bsize;
  471.         char **ctyp;
  472.         void *mathbase;
  473.         long alen;
  474.         char *aptr;
  475.         struct WBStartup *wbm;
  476.         void (*_xit)();
  477.  
  478. Function:   Gives the library access to global variables that reside in the
  479.         application program and opens standard input, output and error
  480.         streams and allocates the SetSTDIO to allocate the memory that
  481.         is pointed to by task->tc_UserData.
  482.  
  483. Arguments:  in, out, err - memory locations where pointers to the standard
  484.         stream files are stored in the application program.
  485.         errno - the memory location where the global variable errno
  486.         is stored.
  487.         bsize - the memory location where the global variable blocksize
  488.         is stored. blocksize is used by the heap manager to determine the
  489.         minimum size of the memory blocks to be allocated from AmigaDOS.
  490.         ctyp - this is the 'type' array that is used by the macros in
  491.         ctype.h. The array is actually in the library and the
  492.         application just gets a pointer to it.
  493.         mathbase - The address of the MathIeeDoubBas library base pointer
  494.         to be used for programs that use floating point numbers.
  495.         alen - the length of the command line passed to the program by
  496.         the CLI process, if run from the CLI.
  497.         aptr - a pointer to the command line passed to the program by the
  498.         CLI process, if run form the CLI.
  499.         wbm - a pointer to the workbench startup message sent by the
  500.         workbench program.
  501.         _xit - a pointer to the applications exit routine. This is set
  502.         to be exit() by the _main routine.
  503.  
  504. Return:     One is returned if all of the initialization was successful,
  505.         otherwise zero is returned.
  506. -------------------------------------------------------------------------
  507. Name:        system                 MACRO
  508.  
  509. Synopsis:   #include "stdlib.h"
  510.         system(command)
  511.         char *command;
  512.  
  513. Function:   Executes a command as if it was typed in on the CLI command
  514.         line. The RUN command must be in the path or in the C: directory
  515.         for this function to work.
  516.  
  517. Arguments:  command - The command to execute, for example:
  518.         system("FORMAT DRIVE DH0: NAME TRASHED") will format
  519.         your hard drive immediatly without asking.
  520.  
  521. Return:     Zero is returned on failure.
  522. -------------------------------------------------------------------------
  523. Name:        wb_parse
  524.  
  525.         void wb_parse(ud, wbmsg)
  526.         task_UserData *ud;
  527.         struct WBStartup **wbmsg;
  528.  
  529. Function:   Checks the Tool Types of the icon associated with this program.
  530.         If the Tool Type WINDOW is found a window is opened using the
  531.         Tool Type's value. This window is used for standard input and
  532.         output. If the WINDOW tool type is not found then a program
  533.         run from the workbench will have NO standard input, output, and
  534.         error, and any attempt to write to these non-existant devices
  535.         will almost certainly cause a system crash. A good example of
  536.         a valid tool type would be:
  537.         WINDOW=CON:20/10/300/WindowTitle
  538.  
  539. Arguments:  ud - a pointer to the task's task_UserData structure.
  540.         wbmsg - a pointer to the workbench startup message for this
  541.         program.
  542.  
  543. See Also:   cli_parse
  544. -------------------------------------------------------------------------
  545.  
  546.    2) STREAM I/O FUNCTIONS
  547.  
  548.    These functions send and receive bytes from "streams". A stream is the
  549.    data type FILE that is defined in stdio.h. Some of the functions
  550.    are implemented as macros that are defined in stdio.h. Other functions
  551.    read and write to the standard pre-opened stream files "stdin", "stdout"
  552.    and "stderr". When an error occurs with one of these functions the
  553.    global variable errno will contain further information.
  554.  
  555. -------------------------------------------------------------------------
  556. Name:        agetc
  557.  
  558. Synopsis:   short agetc(fp)
  559.         FILE *fp;
  560.  
  561. Function:   Gets one character from the designated stream. This function
  562.         is here to support existing implementations of the C library
  563.         and should not be used in new code.
  564.  
  565. Arguments:  fp - a pointer to the stream file to receive input from.
  566.  
  567. Return:     The character received as input, of EOF if the end of the
  568.         file has been reached, or if an error has occured.
  569.  
  570. See Also:   getc
  571. -------------------------------------------------------------------------
  572. Name:        aputc
  573.  
  574. Synopsis:   short aputc(c,fp)
  575.         short c;
  576.         FILE *fp;
  577.  
  578. Function:   Writes one character to the specified stream. This function is
  579.         here to support existing implementations of the C library and
  580.         should not be used in new code.
  581.  
  582. Arguments:  c - the character to write
  583.         fp - the stream to write to.
  584.  
  585. Return:     EOF is returned on error.
  586.  
  587. See Also:   putc
  588. -------------------------------------------------------------------------
  589. Name:        clearerr                 MACRO
  590.  
  591. Synopsis:   #include "stdio.h"
  592.         int clearerr(fp)
  593.         FILE *fp;
  594.  
  595. Function:   Clears end of file and error indicators in a stream.
  596.  
  597. Arguments:  fp - pointer to a stream file
  598.  
  599. See Also:   feof, ferror
  600. -------------------------------------------------------------------------
  601. Name:        fclose
  602.  
  603. Synopsis:   long fclose(fp)
  604.         FILE *fp;
  605.  
  606. Function:   Closes a stream file.
  607.  
  608. Arguments:  fp - stream file to close
  609.  
  610. Return:     Zero is returned if the operation was successful, otherwise
  611.         non-zero is returned.
  612.  
  613. See Also:   fopen
  614. -------------------------------------------------------------------------
  615. Name:        fdopen
  616.  
  617. Synopsis:   FILE *fdopen(fh,fmode)
  618.         long fh;
  619.         char *fmode;
  620.  
  621. Function:   Creates a stream file from a low-level file handle.
  622.         This function is here to support existing C library
  623.         implementations and should not be used in new code.
  624.  
  625. Arguments:  fh - the low-level file handle
  626.         fmode - not used in this implementation, but used to contain the
  627.         file open modes.
  628.  
  629. Return:     A pointer to the new stream file is returned, otherwise NULL.
  630.  
  631. See Also:   fopen
  632. -------------------------------------------------------------------------
  633. Name:        feof                 MACRO
  634.  
  635. Synopsis:   #include "stdio.h"
  636.         int feof(fp)
  637.         FILE *fp;
  638.  
  639. Function:   Tests for end of file.
  640.  
  641. Arguments:  fp - pointer to a stream file
  642.  
  643. Return:     Retuns non-zero if the end of file bit is set in the stream.
  644. -------------------------------------------------------------------------
  645. Name:        ferror                 MACRO
  646.  
  647. Synopsis:   #include "stdio.h"
  648.         int ferror(fp)
  649.         FILE *fp;
  650.  
  651. Function:   Tests for file error.
  652.  
  653. Arguments:  fp - pointer to a stream file
  654.  
  655. Return:     Returns non-zero if the error bit is set in the stream.
  656. -------------------------------------------------------------------------
  657. Name:        fflush
  658.  
  659. Synopsis:   long fflush(fp)
  660.         FILE *fp;
  661.  
  662. Function:   Causes buffered but unwritten data to be written on an output
  663.         file. The operation is undefined for input streams.
  664.  
  665. Arguments:  fp - the stream file to flush
  666.  
  667. Return:     EOF is returned on a write error, otherwise zero is returned.
  668. -------------------------------------------------------------------------
  669. Name:        fgetc                 MACRO
  670.  
  671. Synopsis:   #include "stdio.h"
  672.         int fgetc(fp)
  673.         FILE *fp;
  674.  
  675. Function:   Gets one character from the designated stream.
  676.  
  677. Arguments:  fp - a pointer to the stream file to receive input from.
  678.  
  679. Return:     The character received as input, of EOF if the end of the
  680.         file has been reached, or if an error has occured.
  681.  
  682. See Also:   getc
  683.  
  684. -------------------------------------------------------------------------
  685. Name:        fgetpos
  686.  
  687. Synopsis:   #inlude "stdio.h"
  688.         long fgetpos(fp,pos)
  689.         FILE *fp;
  690.         fpos_t *pos;
  691.  
  692. Function:   Saves the current position in a stream file into a variable
  693.         that is suitable for a call to fsetpos.
  694.  
  695. Arguments:  fp - stream to get the current position of
  696.         pos - current position is saved to this address. The data
  697.         type fpos_t is defined in stdio.h.
  698.  
  699. Return:     Non-zero is returned on an error.
  700.  
  701. See Also:   fsetpos
  702. -------------------------------------------------------------------------
  703. Name:        fgets
  704.  
  705. Synopsis:   char *fgets(buf,n,fp)
  706.         char *buf;
  707.         long n;
  708.         FILE *fp;
  709.  
  710. Function:   Reads at most n-1 bytes from a stream file into an array,
  711.         if a '\n' character is encountered it is included
  712.         in the array which is then NULL terminated.
  713.  
  714. Arguments:  buf - pointer to the array of bytes to store the input.
  715.         n - maximum number of bytes to read.
  716.         fp - pointer to the stream file to read from.
  717.  
  718. Return:     buf is returned unless the end of file is reached or an error
  719.         occurs in which case NULL is returned.
  720.  
  721. See Also:   fputs
  722. -------------------------------------------------------------------------
  723. Name:        fopen
  724.  
  725. Synopsis:   FILE *fopen(fname,fmode)
  726.         char *fname;
  727.         char *fmode;
  728.  
  729. Function:   Opens a sream file.
  730.  
  731. Arguments:  fname - the name of the file to open. The file name may be up
  732.         to FILENAME_MAX characters long.
  733.         fmode - the mode to open the file in. Legal values include:
  734.         "r"   open a file for reading
  735.         "w"   create a file for writing, discard contents if any.
  736.         "a"   append; open or create a file for writing at the end.
  737.         "r+"  open a file for update, reading and writing)
  738.         "w+"  create a file for update, discard previous contents
  739.         "a+"  append; open or create a file for update, write at end
  740.         Optionally a 'b' may be added to the open mode, but this is not
  741.         needed for the Amiga system because there is no distinction
  742.         between text files and binary files.
  743.  
  744. Return:     A pointer to a stream file is returned, if an error occurs NULL
  745.         is returned.
  746.  
  747. See Also:   fclose
  748. -------------------------------------------------------------------------
  749. Name:        fprintf
  750.  
  751. Synopsis:   long fprintf(fp,fmt,...)
  752.         FILE *fp;
  753.         char *fmt;
  754.  
  755. Function:   Sends formatted output to a stream file. For a more detailed
  756.         description of formatted output please see printf.
  757.  
  758. Arguments:  fp - pointer to the stream file
  759.         fmt - format to print the arguments with.
  760.         ... - a variable number of arguments that is specified in fmt.
  761.  
  762.  
  763. Return:     The number of characters written is returned.
  764.  
  765. See Also:   printf
  766. -------------------------------------------------------------------------
  767. Name:        fputc                 MACRO
  768.  
  769. Synopsis:   #include "stdio.h"
  770.         int fputc(c,fp)
  771.         short c;
  772.         FILE *fp;
  773.  
  774. Function:   Writes one character to the specified stream.
  775.  
  776. Arguments:  c - character to write
  777.         fp - stream to write to
  778.  
  779. Return:     EOF is returned on error
  780.  
  781. See Also:   putc
  782. -------------------------------------------------------------------------
  783. Name:        fputs
  784.  
  785. Synopsis:   long fputs(string,fp)
  786.         char *string;
  787.         FILE *fp;
  788.  
  789. Function:   Sends a string to the specified stream file.
  790.  
  791. Arguments:  string - NULL terminated string to send.
  792.         fp - stream to send the string to.
  793.  
  794. Return:     EOF is returned on error, otherwise > 0.
  795.  
  796. See Also:   fgets
  797. -------------------------------------------------------------------------
  798. Name:        fread
  799.  
  800. Synopsis:   #include "stdio.h"
  801.         size_t fread(buf,size,nobj,fp)
  802.         void *buf;
  803.         size_t size;
  804.         size_t nobj;
  805.         FILE *fp;
  806.  
  807. Function:   Reads from a stream into an array at most nobj elements of
  808.         size. (number of bytes = size*nobj).
  809.  
  810. Arguments:  buf - buffer to store the data
  811.         size - size of each element to read
  812.         nobj - number of elements to read
  813.         fp - stream to read from
  814.  
  815. Return:     The number of elements read, which may be less than nobj due
  816.         to an end of file or error condition.
  817.  
  818. See Also:   fwrite
  819. -------------------------------------------------------------------------
  820. Name:        freopen
  821.  
  822. Synopsis:   FILE *freopen(fname, fmode, oldfp)
  823.         char *fname;
  824.         char *fmode;
  825.         FILE *oldfp;
  826.  
  827. Function:   Re-opens a stream file with a different name and possibly a
  828.         different file mode. It is most commonly used to re-direct
  829.         stdin, stdout, and stderr.
  830.  
  831. Arguments:  fname - name of the stream to open
  832.         fmode - mode to open the stream in. See the description of
  833.         fopen for the legal file modes.
  834.         oldfp - the stream to re-open.
  835.  
  836. Return:     A pointer to the new stream is returned if the operation was
  837.         successful, otherwise NULL is returned.
  838.  
  839. See Also:   fopen
  840. -------------------------------------------------------------------------
  841. Name:        fscanf
  842.  
  843. Synopsis:   long fscanf(fp,fmt,...);
  844.         FILE *fp;
  845.         char *fmt;
  846.  
  847. Function:   Reads formatted input from a stream. For a further explanation
  848.         of formatted input please see scanf.
  849.  
  850. Arguments:  fp - stream to read the formatted input from.
  851.         fmt - format of the arguments to be read.
  852.         ... - a variable number of arguments that are specified in fmt.
  853.         Each of the arguments to fscanf must be a pointer.
  854.  
  855. Return:     The number of items converted and assigned is returned.
  856.  
  857. See Also:   scanf
  858. -------------------------------------------------------------------------
  859. Name:        fseek
  860.  
  861. Synopsis:   #include "stdio.h"
  862.         long fseek(fp,offset,origin)
  863.         FILE *fp;
  864.         long offset;
  865.         long origin;
  866.  
  867. Function:   Sets the position in a stream relative to "origin".
  868.  
  869. Arguments:  fp - stream to set the position of.
  870.         offset - offset in bytes to set the position to.
  871.         origin - position realtive to which the new position will
  872.         be set. The values for origin may be SEEK_SET (beginning),
  873.         SEEK_CUR, (current position), SEEK_END (end of file).
  874.  
  875. Return:     Non-zero is returned when an error occurs.
  876.  
  877. See Also:   ftell, fsetpos
  878. -------------------------------------------------------------------------
  879. Name:        fsetpos
  880.  
  881. Synopsis:   long fsetpos(fp,pos)
  882.         FILE *fp;
  883.         fpos_t *pos;
  884.  
  885. Function:   Positions a stream to a position saved by fgetpos.
  886.  
  887. Arguments:  fp - stream to set the position of.
  888.         pos - pointer to the position saved by fgetpos.
  889.  
  890. Return:     Non-zero is returned when an error occurs.
  891.  
  892. See Also:   fseek
  893. -------------------------------------------------------------------------
  894. Name:        ftell
  895.  
  896. Synopsis:   long ftell(fp)
  897.         FILE *fp;
  898.  
  899. Arguments:  fp - a stream file.
  900.  
  901. Return:     Returns the current file position, of -1 if an error occurs.
  902.  
  903. See Also:   fgetpos
  904. -------------------------------------------------------------------------
  905. Name:       fwrite
  906.  
  907. Synopsis:   #include "stdio.h"
  908.         size_t fwrite(buf,size,nobj,fp)
  909.         void *buf;
  910.         size_t size, nobj;
  911.         FILE *fp;
  912.  
  913. Function:   Writes from an array to a stream, at most nobj elements of size
  914.         size are written.
  915.  
  916. Arguments:  buf -  array to write from.
  917.         size - size of the elements to write.
  918.         nobj - number of elements to write.
  919.         fp - stream to write to.
  920.  
  921. Return:     The number of element written is returned, which is less than
  922.         nobj on error.
  923.  
  924. See Also:   fread
  925. -------------------------------------------------------------------------
  926. Name:        getbuff
  927.  
  928. Synopsis:   void getbuff(fp)
  929.         FILE *fp;
  930.  
  931. Function:   Allocates the standard sized buffer for buffered input and
  932.         output. The function must be called before any reading or
  933.         writing is done. It will be called for you otherwise.
  934.  
  935. Arguments:  fp - stream to attach the buffer to.
  936.  
  937. See Also:   setvbuf
  938. -------------------------------------------------------------------------
  939. Name:        getc
  940.  
  941. Synopsis:   short getc(fp)
  942.         FILE *fp;
  943.  
  944. Function:   Gets one character from the designated stream.
  945.  
  946. Arguments:  stream - a pointer to the stream file to receive input from.
  947.  
  948. Return:     The character received as input, of EOF if the end of the
  949.         file has been reached, or if an error has occured.
  950.  
  951. See Also:   fgetc
  952. -------------------------------------------------------------------------
  953. Name:        getchar                 MACRO
  954.  
  955. Synopsis:   #include "stdio.h"
  956.         short getchar();
  957.  
  958. Function:   Reads one character from the standard input.
  959.  
  960. Return:     The character received as input, of EOF if the end of the
  961.         file has been reached, or if an error has occured.
  962.  
  963. See Also:   getc
  964. -------------------------------------------------------------------------
  965. Name:        getchar
  966.  
  967. Synopsis:   #define NOMACROS
  968.         #include stdio.h     or     short getchar();
  969.         short getchar();
  970.  
  971. Function:   Reads one character from the standard input.
  972.  
  973. Return:     The character received as input, of EOF if the end of the
  974.         file has been reached, or if an error has occured.
  975.  
  976. See Also:   getc
  977. -------------------------------------------------------------------------
  978. Name:        gets
  979.  
  980. Synopsis:   char *gets(buf)
  981.         char *buf;
  982.  
  983. Function:   Reads a line from the standard input. The newline '\n' is
  984.         replaced by a '\0'.
  985.  
  986. Arguments:  buf - array of characters where the input line is stored.
  987.  
  988. Return:     Returns buf unless end of file or an error occurs in which
  989.         case NULL is returned.
  990.  
  991. See Also:   puts,fputs
  992. -------------------------------------------------------------------------
  993. Name:        getw
  994.  
  995. Synopsis:   short getw(fp)
  996.         FILE *fp;
  997.  
  998. Function:   Reads a 16 bit word from the specified stream.
  999.  
  1000. Arguments:  fp - stream to read the word from.
  1001.  
  1002. Return:     EOF is returned on error, otherwise the data read from the
  1003.         stream is returned.
  1004.  
  1005. See Also:   putw
  1006. -------------------------------------------------------------------------
  1007. Name:        mktemp
  1008.  
  1009. Synopsis:   char *mktemp(buf)
  1010.  
  1011. Function:   Creates a temporary file name from a template whose last few
  1012.         characters are 'X'. For example "BOBXXXX.XX".
  1013.  
  1014. Arguments:  buf - template to create the file name from.
  1015.  
  1016. Return:     buf is returned.
  1017.  
  1018. See Also:   tmpnam
  1019. -------------------------------------------------------------------------
  1020. Name:        perror
  1021.  
  1022. Synopsis:   long perror(msg)
  1023.         char *msg;
  1024.  
  1025. Function:   Prints an error message corresponding to the number in errno
  1026.         along with a message you provide to stderr.
  1027.  
  1028. Arguments:  msg - supplimental error message, or NULL if you don't have one.
  1029.  
  1030. Return:     Zero is returned on success, -1 is returned if the error number
  1031.         in errno has no corresponding error message or if an error
  1032.         error occurs with the execution of perror.
  1033.  
  1034. See Also:   puterr
  1035. -------------------------------------------------------------------------
  1036. Name:        printf
  1037.  
  1038. Synopsis:   long printf(fmt,...)
  1039.         char *fmt;
  1040.  
  1041. Function:   Writes formatted output to stdout under control of a
  1042.         format string.
  1043.  
  1044. Arguments:  fmt - format of the following arguments.
  1045.         fmt contains two things, regular characters which are copied
  1046.         to stdout, and conversion specifications, each of which causes
  1047.         conversion and printing of the next argument in the variable
  1048.         argument list. Every conversion specification begins with a
  1049.         '%' character and ends with a converson character. Before the
  1050.         conversion character there may be one or more modifiers. Below
  1051.         is a list of the modifiers in the order that they must appear.
  1052.  
  1053.         1) Flags (in any order) [-+0 ]
  1054.            '-'   specifies left justification within the field
  1055.            '+'   specifies that the number will be printed with a sign
  1056.            ' '   space is printed if the first character isn't a sign
  1057.            '0'   for numeric conversions leading zeros will be printed
  1058.              instead of spaces
  1059.            '#'   is NOT supported yet
  1060.         2) Field Width [0123456789]
  1061.            The minimum field width that the converted argument will
  1062.            be printed in. The argument may be printed in a wider field
  1063.            if it would overflow the field. If the converted argument
  1064.            has fewer characters it will be padded with spaces, unless
  1065.            zeros are specified.
  1066.         3) A period, [.]
  1067.            seperating the field width from the precision.
  1068.         4) Precision number [0123456789]
  1069.            o  For character strings; specifies the maximum number of
  1070.           characters to be printed.
  1071.            o  For floating point numbers in e, E, or f formats the number
  1072.           of digits to be printed after the decimal point.
  1073.            o  For floating point numbers in the G or g formats the number
  1074.           of significant digits to be printed.
  1075.            o  For integral numbers the minimum number of digits to be
  1076.           printed, leading zeros will be added if the number isn't
  1077.           big enough to be prited.
  1078.         5) Argument length specifier [lh]
  1079.            If the length specifier is not present then the argument
  1080.            is taken to be the short ('h') form.
  1081.           For integral values:
  1082.            The length specifier is completly optional for integral values
  1083.            because all 16 bit arguments must be promoted to a 32 bit
  1084.            quantity before passing them to a CClib.library function.
  1085.            o  'l' prints the argument as long or unsigned long.
  1086.            o  'h' prints the argument as short or unsigned short.
  1087.           For floating point values:
  1088.            o  'h' prints the argument as a float.
  1089.            o  'l' prints the argument as a double.
  1090.            o  'L' is NOT supported due to the lack of the long double
  1091.           data type on the Amiga.
  1092.  
  1093.              Printf conversion characters.
  1094.  
  1095.            d, i    signed decimal number
  1096.            o    unsigned octal number
  1097.            x, X    unsigned hexadecimal number using lowercase letters
  1098.             for 'x' and upper case letters for 'X'
  1099.            u    unsigned decimal number
  1100.            c    a single character
  1101.            s    a NULL terminated string
  1102.            f    float or double depending on the length specifier to
  1103.             be printed with a fixed decimal point
  1104.            e, E    float or double depending on the length specifier to
  1105.             be printed in exponential notation
  1106.            g, G    float or double depending on the length specifier to
  1107.             be printed with whatever is shorter, 'e' of 'f'
  1108.             format
  1109.            p    print as a pointer (this is really the same as
  1110.             'x' format on the Amiga).
  1111.            n    this is NOT supported yet, but should put the
  1112.             number of characters printed so far into the
  1113.             argument.
  1114.            %    prints the '%' character
  1115.  
  1116. Return:        The number of characters printed is returned or negative
  1117.            if an error occurs.
  1118.  
  1119. See Also:      fprintf, vprintf, vfprintf
  1120. -------------------------------------------------------------------------
  1121. Name:        putc
  1122.  
  1123. Synopsis:   short putc(c,fp)
  1124.         short c;
  1125.         FILE *fp;
  1126.  
  1127. Function:   Writes one byte to the specified stream.
  1128.  
  1129. Arguments:  c - character to write
  1130.         fp - stream to write to
  1131.  
  1132. Return:     EOF is returned on error
  1133.  
  1134. See Also:   getc
  1135. -------------------------------------------------------------------------
  1136. Name:        putchar                 MACRO
  1137.  
  1138. Synopsis:   #include "stdio.h"
  1139.         short putchar(c)
  1140.         short c;
  1141.  
  1142. Function:   Writes one character to the standard output.
  1143.  
  1144. Arguments:  c - the character to write
  1145.  
  1146. Return:     EOF is returned on error.
  1147.  
  1148. See Also:   putc
  1149. -------------------------------------------------------------------------
  1150. Name:        putchar
  1151.  
  1152. Synopsis:   #defile NOMACROS 1
  1153.         #include "stdio.h"         or    short putchar(c)
  1154.         short putchar(c)                 short c;
  1155.         short c;
  1156.  
  1157. Function:   Writes one character to the standard output.
  1158.  
  1159. Arguments:  c - the character to write
  1160.  
  1161. Return:     EOF is returned on error.
  1162.  
  1163. See Also:   putc
  1164. -------------------------------------------------------------------------
  1165. Name:        puterr
  1166.  
  1167. Synopsis:   short puterr(c)
  1168.         short c;
  1169.  
  1170. Function:   Writes one character to stderr.
  1171.  
  1172. Arguments:  c - character to write
  1173.  
  1174. Return:     EOF is returned on error
  1175.  
  1176. See Also:   perror
  1177. -------------------------------------------------------------------------
  1178. Name:        puts
  1179.  
  1180. Synopsis:   short puts(str)
  1181.         char *str;
  1182.  
  1183. Function:   Writes a NULL terminated string and a newline ('\n') character
  1184.         to stdout.
  1185.  
  1186. Arguments:  str - string to write
  1187.  
  1188. Return:     EOF is returned on error
  1189.  
  1190. See Also:   gets
  1191. -------------------------------------------------------------------------
  1192. Name:        putw
  1193.  
  1194. Synopsis:   unsigned short putw(w,fp)
  1195.         unsigned short w;
  1196.         FILE *fp;
  1197.  
  1198. Function:   Writes a 16 bit word to the specified stream.
  1199.  
  1200. Arguments:  w - word to write
  1201.         fp - stream to write to
  1202.  
  1203. Return:     w is returned when no error occurs, otherwise EOF.
  1204.  
  1205. See Also:   putc
  1206. -------------------------------------------------------------------------
  1207. Name:        remove                 MACRO
  1208.  
  1209. Synopsis:   #include "stdio.h"
  1210.         long remove(fname)
  1211.         char *fname;
  1212.  
  1213. Function:   Deletes a file.
  1214.  
  1215. Arguments:  fname - name of the file to delete
  1216.  
  1217. Return:     Non-zero is returned on error.
  1218.  
  1219. See Also:   unlink
  1220. -------------------------------------------------------------------------
  1221. Name:        rename
  1222.  
  1223. Synopsis:   long rename(oldfname,newfname)
  1224.         char *oldfname;
  1225.         char *newfname;
  1226.  
  1227. Function:   Renames a file. In AmigaDOS files may be renamed across
  1228.         directories but not across volumes. For example
  1229.         rename("RAM:t/junk","RAM:t/stuff/junk); would be legal but
  1230.         rename("RAM:t/junk","DF0:junk"); would not be.
  1231.  
  1232. Arguments:  oldfname - name of the file to rename
  1233.         newfname - new name of the file
  1234.  
  1235. Return:     Non-zero is returned on error.
  1236. -------------------------------------------------------------------------
  1237. Name:        rewind                 MACRO
  1238.  
  1239. Synopsis:   #include "stdio.h"
  1240.         void rewind(fp)
  1241.         FILE *fp;
  1242.  
  1243. Function:   Sets the position of a stream file to the beginning of the file.
  1244.  
  1245. Arguments:  fp - stream file pointer
  1246.  
  1247. See Also:   fseek
  1248. -------------------------------------------------------------------------
  1249. Name:        scanf
  1250.  
  1251. Synopsis:   long scanf(fmt,...)
  1252.         char *fmt;
  1253.  
  1254. Function:   Reads formatted input from stdin under control of a format
  1255.         string.
  1256.  
  1257. Arguments:  fmt - format conversion string. The format sring is used to
  1258.         direct the interpretation of input. The format string may
  1259.         contain;
  1260.         1) whitespace (blanks and tabs) which is ignored.
  1261.         2) Characters other that % which are expected to match
  1262.            the next non-whitespace character of input.
  1263.         3) All conversion specifications are preceeded with a '%'
  1264.            character.
  1265.         4) Field Width [0123456789]
  1266.            Specifies the maimum width of a field.
  1267.         5) Argument length specifier [lh]
  1268.            The argument length specifier determines the size of the
  1269.            variable pointed to by the corresponding argument.
  1270.            If the length specifier is not present then the argument
  1271.            is taken to be the short ('h') form.
  1272.           For integral values:
  1273.            o  'l' converts the input as long or unsigned long.
  1274.            o  'h' converts the input as short or unsigned short.
  1275.           For floating point values:
  1276.            o  'h' converts the argument as a float.
  1277.            o  'l' converts the argument as a double.
  1278.            o  'L' is NOT supported due to the lack of the long double
  1279.           data type on the Amiga.
  1280.         6) Conversion specifications. Each conversion specification
  1281.            determines the conversion of the next field of input. Unless
  1282.            the suppression character '*' is used the input is stored in
  1283.            the next variable corresponding to the next argument. For
  1284.            each variable conversion continues until a whitespace
  1285.            character is encountered, or until the number of characters
  1286.            specified in the maximum field width of the conversion specification
  1287.            are encountered.
  1288.  
  1289.                 Scanf conversion characters.
  1290.  
  1291.            d, i    signed decimal number
  1292.            o    unsigned octal number
  1293.            x    unsigned hexadecimal number
  1294.            u    unsigned decimal number
  1295.            c    input characters are placed in the indicated array
  1296.             up to the number specified in the field width; the
  1297.             default is 1, No '\0' os added. %c will convert the
  1298.             next character INCLUDING whitespace. To read the
  1299.             next non-whitespace character use %1s.
  1300.            s    a NULL terminated string
  1301.            e,f,g    float or double depending on the length specifier
  1302.            p    pointer (this is really the same as 'x' format
  1303.             on the Amiga).
  1304.            n    this is NOT supported yet, but should put the
  1305.             number of characters read so far into the
  1306.             argument.
  1307.            [...]    Null terminated string. Matches the longest
  1308.             non-empty string of input characters from the set
  1309.             of characters between brackets. The string is NULL
  1310.             terminated. []...] includes ']' in the set.
  1311.            [^...]    Null terminated string. Matches the longest
  1312.             non-empty string of input characters NOT from the
  1313.             set of characters between the brackets. The string
  1314.             in NULL terminated. [^]...] excludes ']' from the
  1315.             set.
  1316.            %    the '%' character, no assignment is made
  1317.  
  1318.  
  1319.         ...   - a variable number of arguments each of which is a pointer
  1320.           to a variable whose type is determined by the contents of
  1321.           the format string.
  1322.  
  1323.  
  1324. Return:     The number of items converted and assigned (stored) is
  1325.         returned. If an error occurs or if end of file is reached
  1326.         EOF is returned.
  1327.  
  1328. See Also:   fscanf, sscanf, printf
  1329. -------------------------------------------------------------------------
  1330. Name:        setbuf                 MACRO
  1331.  
  1332. Synopsis:   #include "stdio.h"
  1333.         void setbuf(fp,buf)
  1334.         FILE *fp;
  1335.         char *buf;
  1336.  
  1337. Function:   If buf is NULL buffering for this stream is eliminated,
  1338.         otherwise setbuf is the same as setvbuf(fp,buf,_IOFBF,BUFSIZ).
  1339.  
  1340. Arguments:  fp - stream file pointer
  1341.         buf - buffer to set
  1342.  
  1343. See Also:   setvbuf
  1344. -------------------------------------------------------------------------
  1345. Name:        setvbuf
  1346.  
  1347. Synopsis:   #include "stdio.h"
  1348.         long setvbuf(fp,buf,mode,size)
  1349.         FILE *fp;
  1350.         char *buf;
  1351.         long mode;
  1352.         size_t size;
  1353.  
  1354. Function:   Controls buffering for a stream by attaching an application
  1355.         specific buffer to the stream. If setvbuf is to be used then
  1356.         it must be called before any reading or writing is done on the
  1357.         stream.
  1358.  
  1359. Arguments:  fp - stream to add the buffer to
  1360.         buf - buffer to be used, if the buf argument is NULL then a
  1361.         buffer will be allocated for the stream using malloc that is the
  1362.         size specified by the size argument.
  1363.         mode - the mode of buffering, _IOFBF causes full buffering,
  1364.         _IOLBF should cause the buffering of text lines but is the same
  1365.         as _IOFBF for this implementation, _IONBF causes no buffering.
  1366.         size - size of the buffer provided or to be allocated.
  1367.  
  1368. Return:     Non-zero is returned for any error.
  1369.  
  1370. See Also:   setbuf
  1371. -------------------------------------------------------------------------
  1372. Name:        sprintf
  1373.  
  1374. Synopsis:   long sprintf(buf,fmt,...)
  1375.         char *buf;
  1376.         char *fmt;
  1377.  
  1378. Function:   Prints formatted output to a NULL terminated string under control
  1379.         of a format string.
  1380.  
  1381. Arguments:  buf - buffer to write the output to
  1382.         fmt - format string, see the documentation for the printf
  1383.         function for a description of the format string.
  1384.         ... - variable number of arguments under control of the
  1385.         format string.
  1386.  
  1387. Return:     The number of characters printed not including the NULL
  1388.         terminator.
  1389.  
  1390. See Also:   printf
  1391. -------------------------------------------------------------------------
  1392. Name:        sscanf
  1393.  
  1394. Synopsis:   long sscanf(str,fmt,...)
  1395.         char *str, *fmt;
  1396.  
  1397. Function:   Identical to scanf except that input characters are taken
  1398.         from the string str instead of stdin.
  1399.  
  1400. Arguments:  str - string to take input from
  1401.         fmt - format string, see documentation for the scanf function
  1402.         ... - variable number of arguments each of which is a pointer
  1403.  
  1404. Return:        The number of items converted and assigned (stored) is
  1405.            returned.
  1406.  
  1407. See Also:   scanf
  1408. -------------------------------------------------------------------------
  1409. Name:        stat
  1410.  
  1411. Synopsis:   #include "stat.h"
  1412.         long stat(fname,stat)
  1413.         char *fname;
  1414.         struct stat *stat;
  1415.  
  1416. Function:   Retrieves information about a file.
  1417.  
  1418. Arguments:  fname - name of the file to get the information about
  1419.         stat - structure to hold the results. The stat structure
  1420.         is described below;
  1421.  
  1422.         struct stat
  1423.         {
  1424.         unsigned short st_attr;
  1425.         long st_mtime;
  1426.         long st_size;
  1427.         };
  1428.  
  1429.         st_attr - file attributes which may be or'd together including:
  1430.           This Bit On       Means
  1431.            ST_DELETE   -  file is NOT deletable
  1432.            ST_EXECUTE  -  file is NOT executable
  1433.            ST_WRITE    -  file is NOT writeable
  1434.            ST_READ       -  file is NOT readable
  1435.            ST_ARCHIVE  -  file HAS been archived
  1436.         A warning about attribute bits; It is unsafe to assume that
  1437.         the other bits available in the attribute field will be un-used.
  1438.         This is because they may be used in future implementations of
  1439.         the Amiga operating system. This has already happened in the
  1440.         case of the ST_ARCHIVE bit.
  1441.  
  1442.         st_mtime - File modification date, in seconds since Jan, 1 1978
  1443.  
  1444.         st_size - of file in bytes
  1445.  
  1446. Return:     Non-zero is returned on error.
  1447. -------------------------------------------------------------------------
  1448. Name:        tmpfile
  1449.  
  1450. Synopsis:   FILE *tmpfile()
  1451.  
  1452. Function:   Creates a temporary stream file.
  1453.  
  1454. Return:     A pointer to the new stream file, or NULL if an error occurs.
  1455.  
  1456. See Also:   tmpnam
  1457. -------------------------------------------------------------------------
  1458. Name:        tmpnam
  1459.  
  1460. Synopsis:   #include "stdio.h"
  1461.         char *tmpnam(buf)
  1462.         char *buf;
  1463.  
  1464. Function:   Creates a string that is not the name of an existing file.
  1465.  
  1466. Arguments:  buf - buffer to store the string in. This buffer must be at
  1467.         least L_tmpnam characters long. If this argument is NULL then
  1468.         a pointer to a "static" string is returned. This string may be
  1469.         over-written by other calls to cclib.library functions, so
  1470.         it is best to make a local copy of the string or immediatly
  1471.         open a file using this string.
  1472.  
  1473. Return:     buf, or a pointer to the "static" area of memory used by tmpnam.
  1474.         The "static" memory is really located in the task_UserData
  1475.         structure for your process.
  1476.  
  1477. See Also:   tmpfile
  1478. -------------------------------------------------------------------------
  1479. Name:        ungetc
  1480.  
  1481. Synopsis:   short ungetc(c,fp)
  1482.         short c;
  1483.         FILE *fp;
  1484.  
  1485. Function:   Pushes a single character 'c' back into a stream file where it
  1486.         will be read as the next character of input. c may not be EOF.
  1487.  
  1488. Arguments:  c - character to put
  1489.         fp - stream to push into
  1490.  
  1491. Return:     The character puched back is returned, EOF on error.
  1492.  
  1493. See Also:   getc
  1494. -------------------------------------------------------------------------
  1495. Name:        vfprintf
  1496.  
  1497. Synopsis:   long vfprintf(fp,fmt,arg)
  1498.         FILE *fp;
  1499.         char *fmt;
  1500.         va_list arg;
  1501.  
  1502. Function:   Works the same as fprintf except that the variable argument
  1503.         list has been replaced by arg, which is a pointer into the
  1504.         stack. vfprintf is useful for implementing your own functions
  1505.         that use variable argument lists. Here is an example of a
  1506.         function you could write using a variable number of arguments:
  1507.  
  1508.         yourfprintf(fp,ymsg,fmt,arg)
  1509.         FILE *fp;
  1510.         char *ymsg, *fmt;
  1511.         int arg;
  1512.         {
  1513.         fprintf(fp,"Your Message: %s ",ymsg);
  1514.         vfprintf(fp,fmt,(va_list)&arg);
  1515.         }
  1516.  
  1517.         You could call this function like this:
  1518.  
  1519.         yourfprintf(fp,"Oops","%s %d","The number was",10);
  1520.  
  1521.         And the output would be:
  1522.  
  1523.         Your Message: Oops The number was 10
  1524.  
  1525. Arguments:  fp - pointer to stream
  1526.         fmt - format string, see printf for a complete discription
  1527.         arg - pointer to the first argument in a variable argument list
  1528.  
  1529. Return:     The number of characters written is returned, or negative
  1530.         if an error occured.
  1531.  
  1532. See Also:   printf
  1533. -------------------------------------------------------------------------
  1534. Name:        vprintf
  1535.  
  1536. Synopsis:   long vprintf(fmt,arg)
  1537.         char *fmt;
  1538.         va_list arg;
  1539.  
  1540. Function:   Works the same as printf except that the variable argument
  1541.         list has been replaced by arg, which is a pointer into the
  1542.         stack. See vfprintf to find out how to use arg.
  1543.  
  1544. Arguments:  fmt - format string, see printf for a complete discription
  1545.         arg - pointer to the first argument in a variable argument list
  1546.  
  1547. Return:     The number of characters written is returned, or negative
  1548.         if an error occured.
  1549.  
  1550. See Also:   printf, vfprintf
  1551. -------------------------------------------------------------------------
  1552. Name:        vsprintf
  1553.  
  1554. Synopsis:   long vsprintf(buf,fmt,arg)
  1555.         char *buf, *fmt;
  1556.         va_list arg;
  1557.  
  1558. Function:   Works the same as sprintf except that the variable argument
  1559.         list has been replaced by arg, which is a pointer into the
  1560.         stack. See vfprintf to find out how to use arg.
  1561.  
  1562. Arguments:  fmt - format string, see printf for a complete discription
  1563.         arg - pointer to the first argument in a variable argument list
  1564.  
  1565. Return:     The number of characters written is returned, or negative
  1566.         if an error occured.
  1567.  
  1568. See Also:   printf, vfprintf
  1569. -------------------------------------------------------------------------
  1570.  
  1571.    3) NON-STANDARD AND LOW-LEVEL I/O FUNCTIONS. Many of these functions
  1572.       have become widely used and must be supported even though they are not
  1573.       part of the ANSI standard C library.
  1574.  
  1575. -------------------------------------------------------------------------
  1576. Name:        access
  1577.  
  1578. Synopsis:   long access(fname,mode)
  1579.         char *fname;
  1580.         long mode;
  1581.  
  1582. Function:   Tells if a file or directory can be used for a particular
  1583.         purpose.
  1584.  
  1585. Arguments:  fname - the name of the file or directory.
  1586.         mode - asks for a certain type of access for the file or
  1587.         directory. mode = 4 (read access), 2 = write access, 1 =
  1588.         executable program, 0 = test for existance of the file.
  1589.  
  1590. Return:     Zero is returned if the requested accecc rights can be granted,
  1591.         otherwise -1 is retuned.
  1592.  
  1593. See Also:
  1594. -------------------------------------------------------------------------
  1595. Name:        close
  1596.  
  1597. Synopsis:   long close(fd)
  1598.         long fd;
  1599.  
  1600. Function:   Closes the specified low-level file.
  1601.  
  1602. Arguments:  fd - the descriptor for the low-level file obtained from
  1603.         open().
  1604.  
  1605. Return:     Zero is returned if the close was successful, -1 is returned if
  1606.         an error occured.
  1607.  
  1608. See Also:   open
  1609. -------------------------------------------------------------------------
  1610. Name:        creat
  1611.  
  1612. Synopsis:   long creat(fname,mode)
  1613.         char *fname;
  1614.         long mode;
  1615.  
  1616. Function:   creats a new file called 'fname'. This function is equivalent to:
  1617.         open(fname, O_WRONLY|O_TRUNC|O_CREAT, mode).
  1618.  
  1619. Arguments:  fname - the name of the file to create.
  1620.  
  1621. Return:     A file descriptor that can be used by the low-level I/O
  1622.         functions is returned. If an error occurs -1 is returned.
  1623.  
  1624. See Also:   open
  1625. -------------------------------------------------------------------------
  1626. Name:        fileno                 MACRO
  1627.  
  1628. Synopsis:   #include "stdio.h"
  1629.         long fileno(fp)
  1630.         FILE *fp;
  1631.  
  1632. Function:   Gets the low-level file descriptor for a stream file. This is
  1633.         most commonly used on non-bufferd streams such as stdin, stdout
  1634.         and stderr.
  1635.  
  1636. Arguments:  fp - stream file pointer
  1637.  
  1638. Return:     The file descrioptor for the stream file is returned.
  1639. -------------------------------------------------------------------------
  1640. Name:        isatty
  1641.  
  1642. Synopsis:   long isatty(fd)
  1643.         long fd;
  1644.  
  1645. Function:   Determines if a file descriptor is attached to an interactive
  1646.         device (virtual terminal) such as CON: or RAW:.
  1647.  
  1648. Arguments:  fd - file descriptor returned from open etc.
  1649.  
  1650. Return:     Non-zero is retuned if the file descriptor is an interactive
  1651.         device.
  1652. -------------------------------------------------------------------------
  1653. Name:        lseek
  1654.  
  1655. Synopsis:   long lseek(fd,offset,origin)
  1656.         long fd;
  1657.         long offset;
  1658.         unsigned long origin;
  1659.  
  1660. Function:   Sets the current position in a file.
  1661.  
  1662. Arguments:  fd - file descriptor for the file.
  1663.         offset - number of bytes to position the file from the origin.
  1664.         origin - 0 is beginning of the file, 1 is current position,
  1665.         2 is end of the file.
  1666.  
  1667. Return:     The new position in the file, or -1 on error.
  1668.  
  1669. See Also:   fseek
  1670. -------------------------------------------------------------------------
  1671. Name:        open
  1672.  
  1673. Synopsis:   #include "fcntl.h"
  1674.         long open(fname,flag,mode)
  1675.         char *fname;
  1676.         long flag;
  1677.         long mode;
  1678.  
  1679. Function:   Opens a file for low-level I/O.
  1680.  
  1681. Arguments:  fname - name of the file to open, may include path name as well.
  1682.         flag - specifies how the file is to be opened. The acceptable
  1683.         values (listed in fcntl.h) are listed below:
  1684.  
  1685.         O_RDONLY    -  open for reading only
  1686.         O_WRONLY    -  open for writing only
  1687.         O_RDWR    -  open for reading and writing
  1688.         O_CREAT    -  open the file after creating it
  1689.         O_TRUNC    -  remove contents then open the file
  1690.         O_EXCL    -  open fails if the file exists or'd with O_CREAT
  1691.         O_APPEND    -  open for appending only
  1692.  
  1693.         These flags may be or'd together to giver further meanings,
  1694.         for example:
  1695.  
  1696.         O_WRONLY|O_TRUNC - open for writing, nuke existing files
  1697.         O_RDWR|O_APPEND - open for reading and appending
  1698.  
  1699. Return:     fd - descriptor for the open file. This file descriptor is
  1700.         really a pointer to a FileDesc structure that is defined in
  1701.         iolib.h. The FileDesc structure is linked into the OpenFiles
  1702.         list attached to the task_UserData structure for your process.
  1703.         This is so that the library can close all of your open files
  1704.         before your process is terminated.
  1705.  
  1706. See Also:   close
  1707. -------------------------------------------------------------------------
  1708. Name:        read
  1709.  
  1710. Synopsis:   long read(fd,buf,size)
  1711.         long fd;
  1712.         char *buf;
  1713.         long size;
  1714.  
  1715. Function:   Reads bytes from a low-level file.
  1716.  
  1717. Arguments:  fd - file descriptor for the low-level file
  1718.         buf - buffer to store the data read from the file
  1719.         size - number of bytes to read
  1720.  
  1721. Return:     The number of bytes read is returned, -1L is returned on error
  1722.         or end of file. errno will be set on an error.
  1723.  
  1724. See Also:   open, write
  1725. -------------------------------------------------------------------------
  1726. Name:        unlink
  1727.  
  1728. Synopsis:   long unlink(fname)
  1729.         char *fname;
  1730.  
  1731. Function:   Deletes a file.
  1732.  
  1733. Arguments:  fname - name of the file to delete
  1734.  
  1735. Return:     Non-zero is returned on error.
  1736.  
  1737. See Also:   remove
  1738. -------------------------------------------------------------------------
  1739. Name:        write
  1740.  
  1741. Synopsis:   long write(fd,buf,n)
  1742.         long fd;
  1743.         char *buf;
  1744.         long n;
  1745.  
  1746. Function:   Low-level write to a file.
  1747.  
  1748. Arguments:  fd - low-level file descriptor obtained from open.
  1749.         buf - buffer to write
  1750.         n - number bytes to write
  1751.  
  1752. Return:     The number of bytes actually written, which may be less than n,
  1753.         is returned. -1 is returned on error.
  1754.  
  1755. See Also:   open, read
  1756. -------------------------------------------------------------------------
  1757.  
  1758.    4) CHARACTER TEST MACROS. All of these macros are defined in the
  1759.       file "ctype.h". They access a static array that is located in
  1760.       cclib.library. At initialization time a pointer is taken to this
  1761.       static array and that pointer is used for the characher test macros.
  1762.       Because the array is located in shared memory it would be unwise to
  1763.       change it's contents.
  1764.  
  1765. -------------------------------------------------------------------------
  1766.    #include "ctype.h"
  1767.  
  1768.    All of the macros take a character or integral value as an argument and
  1769.    "return" an int that is non-zero if the test passes.
  1770.  
  1771.     isalpha(c)  -  a letter a-z or A-Z
  1772.     isupper(c)  -  upper case letter A-Z
  1773.     islower(c)  -  lower case letter a-z
  1774.     isdigit(c)  -  decimal digit 0-9
  1775.     isxdigit(c) -  hexadecimal digit 0-9 or a-f or A-F
  1776.     isalnum(c)  -  alphanumeric 0-9 or a-z or A-Z
  1777.     isspace(c)  -  space, formfeed, newline, carrige return, tab, v-tab
  1778.     ispunct(c)  -  printing character except space letter or digit
  1779.     iscntrl(c)  -  control character
  1780.     isprint(c)  -  printable character spece included
  1781.     isgraph(c)  -  printing character except space
  1782.     isascii(c)  -  member of the ASCII character set
  1783.  
  1784.     The following macros don't do character tests but character conversions
  1785.     and are commonly found in ctype.h. The "return" values are the converted
  1786.     character.
  1787.  
  1788.     toascii(c)  -  converts a character to ASCII
  1789.     tolower(c)  -  converts upper case letters to lower case
  1790.     toupper(c)  -  converts lower case letters to upper case
  1791.  
  1792. -------------------------------------------------------------------------
  1793.  
  1794.    5) STRING FUNCTIONS. These functions operate on NULL terminated
  1795.       strings. A NULL terminated string is an array of type char
  1796.       whose last element is '\0' (zero).
  1797.  
  1798. -------------------------------------------------------------------------
  1799. Name:        bcpl_strcpy
  1800.  
  1801. Synopsis:   char *bcpl_strcpy(str,bstr)
  1802.         char *str;
  1803.         BSTR *bstr;
  1804.  
  1805. Function:   Copies a BCPL string into a C string. BCPL is the language that
  1806.         much of Amiga DOS was written in, and strings are different.
  1807.         First BCPL adresses only point to long words so... ptr =
  1808.         bcpl_ptr << 2 and BCPL strings start with a character count and
  1809.         then the number of characters in the string. This function is
  1810.         provided so that you can access strings in Amiga DOS data
  1811.         structures.
  1812.  
  1813. Arguments:  str - pointer to the character array where the BCPL string is
  1814.         to be placed.
  1815.         bstr - BCPL pointer to a BCPL string.
  1816.  
  1817. Return:     str is returned.
  1818. -------------------------------------------------------------------------
  1819. Name:        index
  1820.  
  1821. Synopsis:   char *index(str,c)
  1822.         char *str;
  1823.         short c;
  1824.  
  1825. Function:   Finds the first occurence of a character in a string.
  1826.  
  1827. Arguments:  str - string to search
  1828.         c - character to search for
  1829.  
  1830. Return:     A pointer to the found character of NULL if the character
  1831.         was not found.
  1832.  
  1833. See Also:   strchr
  1834. -------------------------------------------------------------------------
  1835. Name:        rindex
  1836.  
  1837. Synopsis:   char *rindex(str,c)
  1838.         char *str;
  1839.         short c;
  1840.  
  1841.  
  1842. Function:   Finds the last occurence of a character in a string.
  1843.  
  1844. Arguments:  str - string to search
  1845.         c - character to search for
  1846.  
  1847. Return:     A pointer to the found character of NULL if the character
  1848.         was not found.
  1849.  
  1850. See Also:   strrchr
  1851. -------------------------------------------------------------------------
  1852. Name:        stpcrlf
  1853.  
  1854. Synopsis:   char stpcrlf(str)
  1855.         char *str;
  1856.  
  1857. Function:   Strips carriage return of linefeed characters from a string.
  1858.         At the first encounter of a '\r' or '\n' character that
  1859.         character is replaced by a '\0' (NULL terminator.
  1860.  
  1861. Arguments:  str - string to strip
  1862.  
  1863. Return:     str is returned
  1864. -------------------------------------------------------------------------
  1865. Name:        strcat
  1866.  
  1867. Synopsis:   char *strcat(dest,source)
  1868.         char *dest;
  1869.         char *source;
  1870.  
  1871. Function:   Concatenates two strings. The destination string is assumed to
  1872.         be long enough to hold the concatenation.
  1873.  
  1874. Arguments:  dest - string to concatenate onto
  1875.         source - string to concatenate from
  1876.  
  1877. Return:     dest, the result, is returned
  1878.  
  1879. See Also:   strcpy
  1880. -------------------------------------------------------------------------
  1881. Name:        strchr
  1882.  
  1883. Synopsis:   char *strchr(str,c)
  1884.         char *str;
  1885.         short c;
  1886.  
  1887. Function:   Finds the first occurence of a character in a string.
  1888.  
  1889. Arguments:  str - string to search
  1890.         c - character to search for
  1891.  
  1892. Return:     A pointer to the found character of NULL if the character
  1893.         was not found.
  1894. -------------------------------------------------------------------------
  1895. Name:        strcmp
  1896.  
  1897. Synopsis:   short strcmp(str1,str2)
  1898.         char *str1, *str2;
  1899.  
  1900. Function:   Compares two strings.
  1901.  
  1902. Arguments:  str1, str2 - strings to compare
  1903.  
  1904. Return:     Negative is returned if str1 < str2, zero is returned if
  1905.         str1 == str2, positive is returned if str1 > str2.
  1906.  
  1907. See Also:   strncmp, strcmpa
  1908. -------------------------------------------------------------------------
  1909. Name:        strcmpa
  1910.  
  1911. Synopsis:   char *strcmpa(str1,str2)
  1912.         char *str1, *str2;
  1913.  
  1914. Function:   Compares two strings, ignoring the case of the letters. For
  1915.         example: 0 == strcmpa("BOB","bob");
  1916.  
  1917. Arguments:  str1, str2 - strings to compare
  1918.  
  1919. Return:     Negative is returned if str1 < str2, zero is returned if
  1920.         str1 == str2, positive is returned if str1 > str2.
  1921.  
  1922. See Also:   strncmp, strcmp
  1923. -------------------------------------------------------------------------
  1924. Name:        strcpy
  1925.  
  1926. Synopsis:   char *strcpy(dest,source)
  1927.         char *dest, *source;
  1928.  
  1929. Function:   Copies one string onto another, the NULL terminator is copied.
  1930.  
  1931. Arguments:  dest - destination string
  1932.         source - source string
  1933.  
  1934. Return:     dest is returned
  1935.  
  1936. See Also:   strncpy
  1937. -------------------------------------------------------------------------
  1938. Name:        strcspn
  1939.  
  1940. Synopsis:   long strcspn(str,reject)
  1941.         char *str, *reject;
  1942.  
  1943. Function:   Finds the length of a string not consisting of characters
  1944.         in another string.
  1945.  
  1946. Arguments:  str - string to search
  1947.         reject - string of characters that str is searched for
  1948.  
  1949. Return:     Length of prefix of str consisting of characters NOT in reject.
  1950.  
  1951. See Also:   strspn
  1952. -------------------------------------------------------------------------
  1953. Name:        strerror
  1954.  
  1955. Synopsis:   char *strerror(err)
  1956.         long err;
  1957.  
  1958. Arguments:  err - an error code, usually the global variable errno
  1959.  
  1960. Return:     Returns a string corresponding to an error number.
  1961. -------------------------------------------------------------------------
  1962. Name:        strlen
  1963.  
  1964. Synopsis:   long strlen(str)
  1965.         char *str;
  1966.  
  1967. Function:   Computes the length of string.
  1968.  
  1969. Arguments:  str - string to compute the length of
  1970.  
  1971. Return:     Length of the string
  1972. -------------------------------------------------------------------------
  1973. Name:        strncat
  1974.  
  1975. Synopsis:   char *strncat(dest,source,n)
  1976.         char *dest, *source;
  1977.         long n;
  1978.  
  1979. Function:   Concatenates up to n characters onto dest from source.
  1980.  
  1981. Arguments:  dest - destination string
  1982.         source - source string
  1983.         n - maximum number of characters to concatenate
  1984.  
  1985. Return:     dest is returned.
  1986.  
  1987. See Also:   strcat
  1988. -------------------------------------------------------------------------
  1989. Name:        strncmp
  1990.  
  1991. Synopsis:   short strncmp(str1,str2,n)
  1992.         char *str1, *str2;
  1993.         long n;
  1994.  
  1995. Function:   Compare at most n characters of two strings.
  1996.  
  1997. Arguments:  str1, str2 - strings to compare
  1998.         n - maximum number of characters to copy
  1999.  
  2000. Return:     Negative is returned if str1 < str2, zero is returned if
  2001.         str1 == str2, positive is returned if str1 > str2.
  2002.  
  2003. See Also:   strcmpa, strcmp
  2004. -------------------------------------------------------------------------
  2005. Name:        strncpy
  2006.  
  2007. Synopsis:   char *strncpy(dest,source,n)
  2008.         char *dest, *source;
  2009.         long n;
  2010.  
  2011. Function:   Copies at most n characters from source to dest. The string is
  2012.         NULL terminated.
  2013.  
  2014. Arguments:  dest - destination string
  2015.         source - source string
  2016.         n - maximum number of characters to copy
  2017.  
  2018. Return:     dest is returned
  2019.  
  2020. See Also:   strcpy
  2021. -------------------------------------------------------------------------
  2022. Name:        strnrv
  2023.  
  2024. Synopsis:   char *strnrv(str,n)
  2025.         char *str;
  2026.         long n;
  2027.  
  2028. Function:   Reverses at most n characters of a string. For example
  2029.         strnrv("Hello World",5) => "olleH World".
  2030.  
  2031. Arguments:  str - string to reverse
  2032.         n - maximum length of the string to reverse
  2033.  
  2034. Return:     str is returned
  2035.  
  2036. See Also:   strrv
  2037. -------------------------------------------------------------------------
  2038. Name:        strpbrk
  2039.  
  2040. Synopsis:   char *strpbrk(str,search)
  2041.         char *str, *search;
  2042.  
  2043. Function:   Searches for one of a string of characters in a string.
  2044.  
  2045. Arguments:  str - string to search
  2046.         search - string of characters to search for
  2047.  
  2048. Return:     A pointer to the first character of str belonging to search is
  2049.         returned, if no match is found NULL is returned.
  2050.  
  2051. See Also:   strspn
  2052. -------------------------------------------------------------------------
  2053. Name:        strrchr
  2054.  
  2055. Synopsis:   char *strrchr(str,c)
  2056.         char *str;
  2057.         short c;
  2058.  
  2059. Function:   Finds the last occurence of a character in a string.
  2060.  
  2061. Arguments:  str - string to search
  2062.         c - string to search for
  2063.  
  2064. Return:     A pointer to the last occurence of c in str is returned, if
  2065.         no match is found NULL is returned.
  2066.  
  2067. See Also:   strchr
  2068. -------------------------------------------------------------------------
  2069. Name:        strrv
  2070.  
  2071. Synopsis:   char *strrv(str)
  2072.         char *str;
  2073.  
  2074. Function:   Reverses the characters in a string. For example:
  2075.         strrv("Kasak") => "kasaK"
  2076.  
  2077. Arguments:  str - string to reverse
  2078.  
  2079. Return:     str is returned
  2080.  
  2081. See Also:   strnrv
  2082. -------------------------------------------------------------------------
  2083. Name:        strspn
  2084.  
  2085. Synopsis:   long strspn(str,search)
  2086.         char *str, *search;
  2087.  
  2088. Function:   Finds the length of a string consisting of characters
  2089.         in another string.
  2090.  
  2091. Arguments:  str - string to search
  2092.         search - string of characters that str is searched for
  2093.  
  2094. Return:     Length of prefix of str consisting of characters in search.
  2095.  
  2096. See Also:   strcspn
  2097. -------------------------------------------------------------------------
  2098. Name:        strstr
  2099.  
  2100. Synopsis:   char *strstr(str,search)
  2101.         char *str;
  2102.         char *search;
  2103.  
  2104. Function:   Finds a string in another string.
  2105.  
  2106. Arguments:  str - string to search
  2107.         search - string to search for
  2108.  
  2109. Return:     Returns a pointer to the string in str that matches search,
  2110.         if the string is not found NULL is returned.
  2111. -------------------------------------------------------------------------
  2112. Name:        strtok
  2113.  
  2114. Synopsis:   char *strtok(str,delim)
  2115.         char *str;
  2116.         char *delim;
  2117.  
  2118. Function:   A sequence of calls splits the string str into tokens, each
  2119.         delimited by a character in delim. The first call to strtok
  2120.         must be with a non-NULL str argument. The argument is remembered
  2121.         by strtok for subsequent calls. The first token is found by
  2122.         searching for characters not in delim. When a token is found
  2123.         the character just after the token is over-written with a NULL
  2124.         and a pointer to the token is returned. Each subsequent call to
  2125.         strtok, indicated by a NULL str argument, will return the next
  2126.         token in str. NULL is returned when there are no further tokens
  2127.         in str.
  2128.  
  2129. Arguments:  str - string to split tokens out of
  2130.         delim - string consisting of legal delimiters
  2131.  
  2132. Return:     Tokens split out from the string are returned, or NULL when
  2133.         there are no more tokens in the string.
  2134. -------------------------------------------------------------------------
  2135. Name:        strupr
  2136.  
  2137. Synopsis:   char *strupr(str)
  2138.         char *str;
  2139.  
  2140. Function:   Converts a string to all upper case letters.
  2141.  
  2142. Arguments:  str - string to convert
  2143.  
  2144. Return:     str is returned
  2145. -------------------------------------------------------------------------
  2146.  
  2147.       6) MEMORY OPERATION FUNCTIONS. These functiuons have become common
  2148.      for most implementations of the C library. They all operate
  2149.      on blocks of memory of a certain size instead of null terminated
  2150.      strings as with the string functions.
  2151.  
  2152. -------------------------------------------------------------------------
  2153. Name:        bcpm
  2154.  
  2155. Synopsis:   short bcmp(ptr1,ptr2,size)
  2156.         void *ptr1, *ptr2;
  2157.         long size;
  2158.  
  2159. Function:   Compares two blocks of memory.
  2160.  
  2161. Arguments:  ptr1, ptr2 - pointers to two blocks of memory to compare
  2162.         size - maximum number of bytes to compare
  2163.  
  2164. Return:     Negative is returned if ptr1 > ptr2, zero is returned if
  2165.         ptr1 == ptr2, positive is returned if ptr1 < ptr2.
  2166.  
  2167. See Also:   memcmp
  2168. -------------------------------------------------------------------------
  2169. Name:        bcopy
  2170.  
  2171. Synopsis:   void bcopy(source,dest,size)
  2172.         void *source, *dest;
  2173.         long size;
  2174.  
  2175. Function:   Copies a block of memory making sure that overlapping blocks
  2176.         are copied correctly.
  2177.  
  2178. Arguments:  source - pointer to source block of memory
  2179.         dest - pointer to destination block of memory
  2180.         size - number of bytes to copy
  2181.  
  2182. See Also:   memcpy
  2183. -------------------------------------------------------------------------
  2184. Name:        bzero
  2185.  
  2186. Synopsis:   void bzero(ptr,size)
  2187.         void *ptr;
  2188.         long size;
  2189.  
  2190. Function:   Sets a block of memory to all zeros.
  2191.  
  2192. Arguments:  ptr - pointer to block of memory
  2193.         size - number of bytes to set to zero
  2194.  
  2195. See Also:   memset
  2196. -------------------------------------------------------------------------
  2197. Name:        memccpy
  2198.  
  2199. Synopsis:   void *memccpy(dest,source,stop,size)
  2200.         void *dest, *source;
  2201.         unsigned short stop;
  2202.         long size;
  2203.  
  2204. Function:   Copies a block of memory until a certain byte is reached or
  2205.         until the maximum number of bytes is reached.
  2206.  
  2207. Arguments:  dest - pointer to block of memory to copy to
  2208.         source - pointer to block of memory to copy from
  2209.         stop - if the stop character is encoutered then the copy
  2210.         operation is stopped after the stop character is copied to
  2211.         the destination block.
  2212.         size - maximum number of bytes to copy
  2213.  
  2214. Return:     If the stop character is encountered then a pointer to the
  2215.         next byte after the stop character is returned, if the stop
  2216.         character is never encounterd then NULL is returned.
  2217. -------------------------------------------------------------------------
  2218. Name:        memchr
  2219.  
  2220. Synopsis:   void *memchr(ptr,chr,size)
  2221.         void *ptr;
  2222.         unsigned short chr;
  2223.         long size;
  2224.  
  2225. Function:   Finds a character in a block of memory.
  2226.  
  2227. Arguments:  ptr - block of memory to search
  2228.         chr - character to search for
  2229.         size - maximum number of bytes to search
  2230.  
  2231. Return:     If the character is found then a pointer to it is returned.
  2232.         NULL is returned if the character is not found.
  2233. -------------------------------------------------------------------------
  2234. Synopsis:   short memcmp(ptr1,ptr2,size)
  2235.         void *ptr1, *ptr2;
  2236.         long size;
  2237.  
  2238. Function:   Compares two blocks of memory.
  2239.  
  2240. Arguments:  ptr1, ptr2 - pointers to two blocks of memory to compare
  2241.         size - maximum number of bytes to compare
  2242.  
  2243. Return:     Negative is returned if ptr1 < ptr2, zero is returned if
  2244.         ptr1 == ptr2, positive is returned if ptr1 > ptr2.
  2245. -------------------------------------------------------------------------
  2246. Name:        memcpy
  2247.  
  2248. Synopsis:   void *memcpy(dest,source,size)
  2249.         void *dest, *source;
  2250.         long size;
  2251.  
  2252. Function:   Copies a block of memory making sure that overlapping blocks
  2253.         are copied correctly.
  2254.  
  2255. Arguments:  dest - pointer to destination block of memory
  2256.         source - pointer to source block of memory
  2257.         size - number of bytes to copy
  2258.  
  2259. Return:     dest is returned
  2260. -------------------------------------------------------------------------
  2261. Name:        memmove                 MACRO
  2262.  
  2263. Synopsis:   #include "string.h"
  2264.         void *memmove(dest,source,size)
  2265.         void *dest, *source;
  2266.         long size;
  2267.  
  2268. Function:   Copies a block of memory making sure that overlapping blocks
  2269.         are copied correctly.
  2270.  
  2271. Arguments:  dest - pointer to destination block of memory
  2272.         source - pointer to source block of memory
  2273.         size - number of bytes to copy
  2274.  
  2275. Return:     dest is returned
  2276. -------------------------------------------------------------------------
  2277. Name:        memset
  2278.  
  2279. Synopsis:   void *memset(ptr,chr,long)
  2280.         void *ptr;
  2281.         unsigned short chr;
  2282.         long size;
  2283.  
  2284. Function:   Sets all bytes in a block of memory to a single value.
  2285.  
  2286. Arguments:  ptr - pointer to a block of memory
  2287.         chr - value to set each byte to
  2288.         size - number of bytes to set
  2289.  
  2290. Return:     ptr is returned
  2291. -------------------------------------------------------------------------
  2292. Name:        memswap
  2293.  
  2294. Synopsis:   void memswap(ptr1,ptr2,size)
  2295.         void *ptr1, *ptr2;
  2296.         long size;
  2297.  
  2298. Function:   Swaps the contents of two blocks of memory.
  2299.  
  2300. Arguments:  ptr1, ptr2 - blocks of memory to swap
  2301.         size - number of bytes to swap
  2302. -------------------------------------------------------------------------
  2303.  
  2304.       7) FORMAT CONVERSION FUNCTIONS. Conversions from numbers to
  2305.      ASCII characters and back.
  2306.  
  2307. -------------------------------------------------------------------------
  2308. Name:        atof
  2309.  
  2310. Synopsis:   double atof(str)
  2311.         char *str;
  2312.  
  2313. Function:   Converts a character string representing a floating point number
  2314.         into an IEEE format double precision floating pointer number.
  2315.  
  2316. Arguments:  str - string to convert
  2317.  
  2318. Return:     A floating point number, zero is returned if no conversion can
  2319.         be made.
  2320. -------------------------------------------------------------------------
  2321. Name:        atoi
  2322.  
  2323. Synopsis:   short atoi(str)
  2324.         char *str;
  2325.  
  2326. Function:   Converts a string representing an integer into a short integer.
  2327.  
  2328. Arguments:  str - string to convert
  2329.  
  2330. Return:     A short integer, zero is returned if no conversion can be made.
  2331.  
  2332. See Also:   stoa
  2333. -------------------------------------------------------------------------
  2334. Name:        atol
  2335.  
  2336. Synopsis:   long atol(str)
  2337.         char *str;
  2338.  
  2339. Function:   Converts a string representing an integer into a long integer.
  2340.  
  2341. Arguments:  str - string to convert
  2342.  
  2343. Return:     A long integer, zero is returned if no conversion can be made.
  2344.  
  2345. See Also:   ltoa
  2346. -------------------------------------------------------------------------
  2347. Name:        ltoa
  2348.  
  2349. Synopsis:   void ltoa(n,str)
  2350.         long n;
  2351.         char *str;
  2352.  
  2353. Function:   Converts a long integer into a string.
  2354.  
  2355. Arguments:  n - number to convert
  2356.         str - string to store the result in
  2357.  
  2358. See Also:   atol
  2359. -------------------------------------------------------------------------
  2360. Name:        stoa
  2361.  
  2362. Synopsis:   void ltoa(n,str)
  2363.         short n;
  2364.         char *str;
  2365.  
  2366. Function:   Converts a short integer into a string.
  2367.  
  2368. Arguments:  n - number to convert
  2369.         str - string to store the result in
  2370.  
  2371. See Also:   atoi
  2372. -------------------------------------------------------------------------
  2373.  
  2374.       8) MEMORY ALLOCATION FUNCTIONS. These functions include the standard
  2375.       heap managment functions as well as lower level functions that were
  2376.       used to implement the heap managment system. When the program that
  2377.       has allocated memory through the functions in this section terminates
  2378.       execution through the exit function all memory allocated from Amiga
  2379.       DOS is returned to the system. All of the heap managment functions
  2380.       will try to allocate memory first from FAST memory and then from CHIP
  2381.       RAM. To allocate memory that is guaranteed to be CHIP RAM (accesable
  2382.       by the Amiga custom chips) you can use the _alloc() function. The
  2383.       heap manager operates by allocating blocks of memory from Amiga DOS
  2384.       in large chunks, then it breaks these blocks up into the sizes that
  2385.       are requested through heap memory allocation functions. The minimum
  2386.       size of the blocks allocated from Amiga DOS can be controlled
  2387.       directly by declaring a global long integer called blocksize and
  2388.       setting it to some value. The default value for blocksize is 256
  2389.       blocks (2K bytes), in increments of 8 bytes. Each time the heap
  2390.       manager allocates memory from Amiga DOS the blocksize variable is
  2391.       checked, which makes it possible to change the variable on the fly.
  2392.  
  2393. -------------------------------------------------------------------------
  2394. Name:        be_free
  2395.  
  2396. Synopsis:   void be_free(ptr,size)
  2397.         void *ptr;
  2398.         long size;
  2399.  
  2400. Function:   Makes static memory available to malloc and calloc. If you have
  2401.         static data structures that will NEVER be used as such again
  2402.         then you can add them to the free memory list with this
  2403.         function. If you write into the data pointed to by ptr after
  2404.         you have added that block to the free memory list then you
  2405.         stand a good chance of corrupting the free memory list. When the
  2406.         free memory list for your task is corrupt the system will
  2407.         when you try to access it with calloc, malloc, or free.
  2408.  
  2409.  
  2410. Arguments:  ptr - pointer to the block of memory to give to the heap
  2411.         manager.
  2412.         size - size of the block of memory
  2413. -------------------------------------------------------------------------
  2414. Name:        calloc
  2415.  
  2416. Synopsis:   void *calloc(nobj,size)
  2417.         unsigned long nobj, size;
  2418.  
  2419. Function:   Allocates and sets to zero an area of memory that is at least
  2420.         nobj * size bytes. This is a standard C function.
  2421.  
  2422. Arguments:  nobj - number of objects to allocate
  2423.         size - size of each object to allocate
  2424.  
  2425. Return:     A pointer to the newly allocated block of memory. NULL is
  2426.         returned when the block of memory can't be provided.
  2427.  
  2428. See Also:   malloc
  2429. -------------------------------------------------------------------------
  2430. Name:        free
  2431.  
  2432. Synopsis:   free(ptr)
  2433.         void *ptr;
  2434.  
  2435. Function:   Returns a block of memory allocated through malloc, calloc or
  2436.         realloc to the heap manager for future use. This is a
  2437.         standard C function.
  2438.  
  2439. Arguments:  ptr - pointer to the block of memory obtained from malloc, calloc
  2440.         or realloc.
  2441.  
  2442. See Also:   be_free
  2443. -------------------------------------------------------------------------
  2444. Name:        freeall
  2445.  
  2446. Synopsis:   freeall()
  2447.  
  2448. Function:   Returns ALL of the memory allocated by any of the functions
  2449.         in this section to the system and re-initializes the free
  2450.         memory list for the heap manager. This will also free all of
  2451.         the memory used by any files that may be open. Normally this
  2452.         function is only called when the program has called the exit
  2453.         function.
  2454. -------------------------------------------------------------------------
  2455. Name:        heap_alloc
  2456.  
  2457. Synopsis:   void *heap_alloc(size)
  2458.         long size;
  2459.  
  2460. Function:   Allocates memory from the heap manager. This function is
  2461.         used internally to implement malloc and calloc.
  2462.  
  2463. Arguments:  size - size in bytes of the requested block of memory
  2464.  
  2465. Return:     A pointer to the newly allocated block of memory. NULL is
  2466.         returned when the block of memory can't be provided.
  2467.  
  2468. See Also:   malloc, calloc
  2469. -------------------------------------------------------------------------
  2470. Name:        heap_free
  2471.  
  2472. Synopsis:   void heap_free(ptr)
  2473.         void *ptr;
  2474.  
  2475. Function:   Returns memory to the free list of the heap manager. This
  2476.         function is used internally to implement free().
  2477.  
  2478. Arguments:  ptr - pointer to a block of memory obtained from heap_alloc.
  2479.  
  2480. See Also:   free
  2481. -------------------------------------------------------------------------
  2482. Name:        malloc
  2483.  
  2484. Synopsis:   void *malloc(size)
  2485.         unsigned long size;
  2486.  
  2487. Function:   Allocates memory from the heap manager that is at least
  2488.         "size" bytes. This is a standard C function.
  2489.  
  2490. Arguments:  size - size of the requested block of memory
  2491.  
  2492. Return:     A pointer to the newly allocated block of memory. NULL is
  2493.         returned when the block of memory can't be provided.
  2494.  
  2495. See Also:   free
  2496. -------------------------------------------------------------------------
  2497. Name:        malloc_size
  2498.  
  2499. Synopsis:   unsigned long malloc_size(ptr)
  2500.         void *ptr;
  2501.  
  2502. Function:   Computes the number of bytes in an allocated block of memory
  2503.         that was obtained from malloc, calloc, realloc, or heap_alloc.
  2504.         The size is rounded up to the nearest eight bytes.
  2505.  
  2506. Arguments:  ptr - a pointer to the allocated block of memory.
  2507.  
  2508. Return:     The size of the allocated block is returned.
  2509. -------------------------------------------------------------------------
  2510. Name:        realloc
  2511.  
  2512. Synopsis:   void *realloc(ptr,newsize)
  2513.         void *ptr;
  2514.         unsigned long newsize;
  2515.  
  2516. Function:   Changes the size of a block block of memory. The contents will
  2517.         be un-changed up to the minimum of the old and new sizes. The
  2518.         block of memory can be freed using free() prior to a call to
  2519.         realloc so long as no intervening calls to any of the heap
  2520.         managment functions is made. In order to make enough space
  2521.         for a larger block of memory is may be necessary to move the
  2522.         block. This is a standard C function.
  2523.  
  2524. Arguments:  ptr - pointer to the block of memory to change the size of
  2525.  
  2526. Return:     A pointer to the new block of memory is returned or NULL if the
  2527.         request can't be satisfied.
  2528.  
  2529. See Also:   free
  2530. -------------------------------------------------------------------------
  2531. Name:        sbrk
  2532.  
  2533. Synopsis:   void *sbrk(size)
  2534.         unsigned long size;
  2535.  
  2536. Function:   Allocates memory through Amiga DOS and attaches the block
  2537.         of memory to the allocated memory list for the current task.
  2538.         This is a lower level function than the heap managment
  2539.         functions. The sbrk function has become a standard part of many
  2540.         C libraries.
  2541.  
  2542. Arguments:  size - size in bytes of the requested block of memory
  2543.  
  2544. Return:     A pointer to the newly allocated block of memory is returned, or
  2545.         -1L if the request can't be satisfied.
  2546. -------------------------------------------------------------------------
  2547. Name:        _alloc
  2548.  
  2549. Synopsis:   void _alloc(ud,size,requirements)
  2550.         task_UserData *ud;
  2551.         long size;
  2552.         long requirements;
  2553.  
  2554. Function:   Allocates memory from Amiga DOS and links it into the allocated
  2555.         memory list for your task. This is the lowest level of memory
  2556.         allocation available through this library and is used to
  2557.         implement all of the other memory allocation functions. The
  2558.         task_UserData pointer can be obtained by a call to GetSTDIO.
  2559.  
  2560. Arguments:  ud - pointer to the task_UserData structure for your task
  2561.         size - size in bytes of the memory to be allocated
  2562.         requirements - memory requirements as described in
  2563.         exec/memory.h, 0L being just any old block of memory.
  2564.         The requirements are used directly in a call to the Amiga
  2565.         AllocMem function.
  2566.  
  2567. Return:     A pointer to the new block of memory is returned or NULL if the
  2568.         request can't be satisfied.
  2569.  
  2570. See Also:   _fre
  2571. -------------------------------------------------------------------------
  2572. Name:        _fre
  2573.  
  2574. Synopsis:   void _fre(ud,ptr)
  2575.         task_UserData *ud;
  2576.         void *ptr;
  2577.  
  2578. Function:   Frees a block of memory allocated by _alloc or sbrk.
  2579.         The task_UserData pointer can be obtained by a call to GetSTDIO.
  2580.  
  2581. Arguments:  ud - pointer to the task_UserData structure for your task
  2582.         ptr - pointer to a block of memory obtained from _alloc or sbrk.
  2583. -------------------------------------------------------------------------
  2584. Name:        _freall
  2585.  
  2586. Synopsis:   void _freall(ud)
  2587.         task_UserData *ud;
  2588.  
  2589. Function:   Returns all memory allocated by through any of the functions
  2590.         in this section to Amiga DOS, but does NOT re-initialize the
  2591.         free list used by the heap manager. The task_UserData pointer
  2592.         can be obtained by a call to GetSTDIO.
  2593.  
  2594. Arguments:  ud - pointer to the task_UserData structure for your task
  2595. -------------------------------------------------------------------------
  2596.  
  2597.       9) LINKED LIST FUNCTIONS. Linked lists are used internally in
  2598.       CClib.library and sizce the linked list functions are already
  2599.       in the library they were made public. The structure definitions
  2600.       for linked lists and nodes are in stdlist.h.
  2601.  
  2602. -------------------------------------------------------------------------
  2603. Name:        add_head
  2604.  
  2605. Synopsis:   void *add_head(l,size)
  2606.         _list *l;
  2607.         long size;
  2608.  
  2609. Function:   Allocates and clears to zero memory from the heap manager for
  2610.         a _node structure plus "size" bytes. The node is then added
  2611.         to the beginning of the linked list.
  2612.  
  2613. Arguments:  l - linked list to add to
  2614.         size - size in bytes of the data for this node
  2615.  
  2616. Return:     A pointer to the data for this node is returned, or NULL if
  2617.         there is not enough memory.
  2618.  
  2619. See Also:   remv_node
  2620. -------------------------------------------------------------------------
  2621. Name:        add_tail
  2622.  
  2623. Synopsis:   void *add_tail(l,size)
  2624.         _list *l;
  2625.         long size;
  2626.  
  2627. Function:   Allocates and clears to zero memory from the heap manager for
  2628.         a _node structure plus "size" bytes. The node is then added
  2629.         to the end of the linked list.
  2630.  
  2631. Arguments:  l - linked list to add to
  2632.         size - size in bytes of the data for this node
  2633.  
  2634. Return:     A pointer to the data for this node is returned, or NULL if
  2635.         there is not enough memory.
  2636.  
  2637. See Also:   remv_node
  2638. -------------------------------------------------------------------------
  2639. Name:        inst_node
  2640.  
  2641. Synopsis:   _node *inst_node(size)
  2642.         long size;
  2643.  
  2644. Function:   Allocates and clears to zero memory from the heap manager for
  2645.         a _node structure plus "size" bytes. This function is used
  2646.         by all of the functions that create a new node.
  2647.  
  2648. Arguments:  size - size in bytes of the data for this node
  2649.  
  2650. Return:     A pointer to the new node is returned, or NULL if there isn't
  2651.         enough memory.
  2652. -------------------------------------------------------------------------
  2653. Name:        put_head
  2654.  
  2655. Synopsis:   void put_head(l,n)
  2656.         _list *l;
  2657.         _node *n;
  2658.  
  2659. Function:   Adds a node at the beginning of a linked list.
  2660.  
  2661. Arguments:  l - linked list to add to
  2662.         n - node to add to the linked list
  2663.  
  2664. See Also:   remv_head
  2665. -------------------------------------------------------------------------
  2666. Name:        put_tail
  2667.  
  2668. Synopsis:   void put_tail(l,n)
  2669.         _list *l;
  2670.         _node *n;
  2671.  
  2672. Function:   Adds a node at the end of a linked list.
  2673.  
  2674. Arguments:  l - linked list to add to
  2675.         n - node to add to the linked list
  2676.  
  2677. See Also:   remv_tail
  2678. -------------------------------------------------------------------------
  2679. Name:        remv_head
  2680.  
  2681. Synopsis:   void *remv_head(l,data)
  2682.         _list *l;
  2683.         void **data;
  2684.  
  2685. Function:   Removes a node from the beginning of a linked list and gives
  2686.         a pointer to the data for that node. The memory for the
  2687.         node is not freed.
  2688.  
  2689. Arguments:  l - linked list to remove from
  2690.         data - pointer to a memory location where a pointer to the
  2691.         data for the node will be stored after removing the node
  2692.         from the beginning of the list
  2693.  
  2694. Return:     A pointer to the block of memory that was allocated for the
  2695.         node and its data is returned, or NULL if there are no more
  2696.         nodes on the list. This memory should be freed using the
  2697.         free function. For example:
  2698.         _list *l;
  2699.         char *data, *ptr;
  2700.         .
  2701.         .
  2702.         .
  2703.         if( ptr = remv_head(l,&data) )
  2704.            free(ptr)
  2705.  
  2706. See Also:   add_head
  2707. -------------------------------------------------------------------------
  2708. Name:        remv_list
  2709.  
  2710. Synopsis:   void remv_list(l)
  2711.         _list *l;
  2712.  
  2713. Function:   Frees all memory associated with a linked list by calling
  2714.         free for every nide in the list and then for the list
  2715.         header.
  2716.  
  2717. Arguments:  l - linked list to free, it is assumed that all of the nodes
  2718.         on the list and the list header itself are allocated using
  2719.         heap_alloc, malloc, calloc, or realloc.
  2720. -------------------------------------------------------------------------
  2721. Name:        remv_node
  2722.  
  2723. Synopsis:   void *remv_node(l,data)
  2724.         _list *l;
  2725.         void *data;
  2726.  
  2727. Function:   Removes a node from a list by first scanning the list for the
  2728.         data associated with the node and then removing the node from
  2729.         the list.
  2730.  
  2731. Arguments:  l - pointer to the list to remove the node from.
  2732.         data - pointer to the data associated with the node to be
  2733.         removed
  2734.  
  2735. Return:     A pointer to the memory allocated for the node and it's data
  2736.         is returned, NULL is returned if the node with the specified
  2737.         data can't be found on the list. The pointer can then be used
  2738.         to free the node and it's data, for example:
  2739.         if( ptr = remv_node(l,data) )
  2740.            free(ptr);
  2741. -------------------------------------------------------------------------
  2742. Name:        remv_tail
  2743.  
  2744. Synopsis:   void *remv_tail(l,data)
  2745.         _list *l;
  2746.         void **data;
  2747.  
  2748. Function:   Removes a node from the end of a linked list and gives
  2749.         a pointer to the data for that node. The memory for the
  2750.         node is not freed.
  2751.  
  2752. Arguments:  l - linked list to remove from
  2753.         data - pointer to a memory location where a pointer to the
  2754.         data for the node will be stored after removing the node
  2755.         from the end of the list
  2756.  
  2757. Return:     A pointer to the block of memory that was allocated for the
  2758.         node and its data is returned, or NULL if there are no more
  2759.         nodes on the list. This memory should be freed using the
  2760.         free function.
  2761.  
  2762. See Also:   add_tail
  2763. -------------------------------------------------------------------------
  2764. Name:        r_node
  2765.  
  2766. Synopsis:   void *r_node(l,n,data)
  2767.         _list *l;
  2768.         _node *n;
  2769.         void **data;
  2770.  
  2771. Function:   Removes a specific node from a linked list and gives a pointer
  2772.         to the data for the node.
  2773.  
  2774. Arguments:  l - linked list to remove the node from
  2775.         n - node to remove from the list
  2776.         data - a pointer to the data for this node is stored here
  2777.  
  2778. Return:     n is returned, or NULL if the list is empty
  2779.  
  2780. See Also:   remv_node
  2781. -------------------------------------------------------------------------
  2782.  
  2783.       10) SORTING FUNCTIONS, these are all modifications of
  2784.       C. A. R. Hoare's quicksort algorithm. Two of the functions
  2785.       are written in C and a third is written in 68000 assembler
  2786.       for speed.
  2787.  
  2788. -------------------------------------------------------------------------
  2789. Name:        qsort
  2790.  
  2791. Synopsis:   void qsort(base,n,size,cmp)
  2792.         void *base;
  2793.         unsigned long n, size;
  2794.         short (*cmp)();
  2795.  
  2796. Function:   Sorts into ascending order an array base[0]...base[n-1] of
  2797.         objects of size "size".
  2798.  
  2799. Arguments:  base - pointer to the first element in the array of elements
  2800.         tp sort.
  2801.         n - number of elements to sort
  2802.         size - size of each element of the array
  2803.         cmp - pointer to comparison function. The comparison function
  2804.         is passed a pointer to two elements of the array and returns
  2805.         zero if the two elements are equivalent, negative must be
  2806.         returned if the first element is less than the second and
  2807.         and positive must be returned if the first element is greater
  2808.         than the second. To sort in the opposite order negative is
  2809.         returned if the first element is greater than the second and
  2810.         positive is returned if the first element is less than the
  2811.         second. Here is an example of a comparison function that
  2812.         will sort strings in descending order:
  2813.  
  2814.         short cmp(str1,str2)
  2815.         char *str1, *str2;
  2816.         {
  2817.         return( strcmp(str2,str1) );
  2818.         }
  2819.  
  2820. -------------------------------------------------------------------------
  2821. Name:        quicksort
  2822.  
  2823. Synopsis:   void quicksort(n,comp,swap,ptr)
  2824.         unsigned long n;
  2825.         short (*comp)();
  2826.         void (*swap)();
  2827.         void *ptr;
  2828.  
  2829. Function:   The quicksort function uses the same sorting algorithm as
  2830.         qsort but it is designed to sort anything, not just arrays
  2831.         in memory.
  2832.  
  2833. Arguments:  n - number of elements to sort.
  2834.         comp - comparison function. The comparison function is passed
  2835.         the index of the two elements to compare and an auxilery
  2836.         pointer that you provide. It returns zero if the two elements
  2837.         are equivalent, negative must be returned if the first element
  2838.         is less than the second and and positive must be returned if
  2839.         the first element is greater than the second. To sort in the
  2840.         opposite order negative is returned if the first element is
  2841.         greater than the second and positive is returned if the first
  2842.         element is less than the second.
  2843.         swap - swaps two elements. The swap function is passed the
  2844.         index of the two elements to swap and an auxilery pointer you
  2845.         provide.
  2846.         ptr - auxilery pointer, can point to anything. This variable
  2847.         is passed to the comp and swap functions in order to facilitate
  2848.         the writing of re-entrant code.
  2849.  
  2850. Example:    Here is an example of a code fragment that would sort a
  2851.         disk file that consists of records of employees:
  2852.  
  2853.         include "stdio.h"
  2854.         #include "stdlib.h"
  2855.  
  2856.  
  2857.         typedef struct    /* employee record */
  2858.         {
  2859.         char name[80];
  2860.         char ssn[20];
  2861.         } Employee;
  2862.  
  2863.         typedef struct    /* auxillery buffer */
  2864.         {
  2865.         FILE *fp;
  2866.         Employee e1, e2;
  2867.         unsigned long i1, i2;
  2868.         } ESortBuf;
  2869.  
  2870.         static void read_record(fp,i,e)  /* reads a single record */
  2871.         FILE *fp;
  2872.         unsigned long i;
  2873.         Employee *e;
  2874.         {
  2875.         if( fseek(fp,(long)i*sizeof(Employee),SEEK_SET) )
  2876.            exit(EXIT_FAILURE);
  2877.         if( !fread(e,sizeof(Employee),1L,fp) )
  2878.            exit(EXIT_FAILURE);
  2879.         }
  2880.  
  2881.         static void write_record(fp,i,e) /* writes a record to a file */
  2882.         FILE *fp;
  2883.         unsigned long i;
  2884.         Employee *e;
  2885.         {
  2886.         if( fseek(fp,(long)i*sizeof(Employee),SEEK_SET) )
  2887.            exit(EXIT_FAILURE);
  2888.         if( !fwrite(e,sizeof(Employee),1L,fp) )
  2889.            exit(EXIT_FAILURE);
  2890.         }
  2891.  
  2892.         static void load_records(i1,i2,e) /* loads records */
  2893.         unsigned long i1, i2;
  2894.         ESortBuf *e;
  2895.         {
  2896.         if( e->i1 != i1 )
  2897.            {
  2898.            read_record(e->fp,i1,&e->e1);
  2899.            e->i1 = i1;
  2900.            }
  2901.         if( e->i2 != i2 )
  2902.            {
  2903.            read_record(e->fp,i2,&e->e2);
  2904.            e->i2 = i2;
  2905.            }
  2906.         }
  2907.  
  2908.         static void swap(i1,i2,e)      /* swaps two records */
  2909.         unsigned long i1, i2;
  2910.         ESortBuf *e;
  2911.         {
  2912.         unsigned long iswap;
  2913.  
  2914.         load_records(i1,i2,e);
  2915.         write_record(e->fp,i2,&e->e1);
  2916.         write_record(e->fp,i1,&e->e2);
  2917.         iswap = e->i1;
  2918.         e->i1 = e->i2;
  2919.         e->i2 = iswap;
  2920.         }
  2921.  
  2922.         static short comp(i1,i2,e)  /* compares two records */
  2923.         unsigned long i1, i2;
  2924.         ESortBuf *e;
  2925.         {
  2926.         load_records(i1,i2,e);
  2927.         return( strcmp(e->e1.name,e->e2.name) );
  2928.         }
  2929.  
  2930.         void employee_sort(fp,size) /* callable function */
  2931.         FILE *fp;
  2932.         unsigned long size;
  2933.         {
  2934.         ESortBuf e;
  2935.         e.fp = fp;          /* attach file pointer */
  2936.         e.i1 = e.i2 = size+1; /* set to invalid */
  2937.  
  2938.         quicksort(size,comp,swap,&e);
  2939.         }
  2940.  
  2941. -------------------------------------------------------------------------
  2942. Name:        vquicksort
  2943.  
  2944. Synopsis:   void vquicksort(n,comp,swap)
  2945.         unsigned short n;
  2946.         short (*comp();
  2947.         void (*swap)();
  2948.  
  2949. Function:   The vquicksort function is much the same as the quicksort
  2950.         function except that only up to 64K elements can be sorted
  2951.         and there is no auxilery argument pointer. Vquicksort is
  2952.         written in 100% hand optomized assembly language, hence it's
  2953.         name, very quicksort.
  2954.  
  2955. Arguments:  n - number of elements to sort.
  2956.         comp - comparison function. The comparison function is passed
  2957.         the index of the two elements to compare. It returns zero if
  2958.         the two elements are equivalent, negative must be returned if
  2959.         the first element is less than the second and and positive must
  2960.         be returned if the first element is greater than the second. To
  2961.         sort in the opposite order negative is returned if the first
  2962.         element is greater than the second and positive is returned if
  2963.         the first element is less than the second.
  2964.         swap - swaps two elements. The swap function is passed the
  2965.         index of the two elements to swap.
  2966.  
  2967. See Also:   quicksort
  2968. -------------------------------------------------------------------------
  2969.  
  2970.       11) TIME FUNCTIONS. These are the standard time functions as
  2971.       described in K&R edition II. Most of these functions use typedefs
  2972.       and structure definitions that are found in time.h. The tm structure
  2973.       is explained here.
  2974.  
  2975.       struct tm
  2976.       {
  2977.       short tm_sec;    seconds after the minute
  2978.       short tm_min;    minutes after the hour
  2979.       short tm_hour;    hours since midnight
  2980.       short tm_mday;    day of the month
  2981.       short tm_mon;    months since January
  2982.       short tm_year;    years since 1900
  2983.       short tm_wday;    days since sunday
  2984.       short tm_yday;    days since January, 1
  2985.       short tm_isdst;    Not Used
  2986.       };
  2987.  
  2988. -------------------------------------------------------------------------
  2989. Name:        asctime
  2990.  
  2991. Synopsis:   char *asctime(tm)
  2992.         struct tm *tm;
  2993.  
  2994. Function:   Converts the time in the structure tm to a string of the
  2995.         form: Sun Jan 1 12:00:00 1989
  2996.  
  2997. Arguments:  tm - structure obtained from localtime
  2998.  
  2999. Return:     A pointer to a string is returned. The string is in "static"
  3000.         memory and may be overwritten by other calls.
  3001.  
  3002. See Also:   localtime
  3003. -------------------------------------------------------------------------
  3004. Name:        clock
  3005.  
  3006. Synopsis:   clock_t clock()
  3007.  
  3008. Function:   Obtains the number of ticks since program execution.
  3009.  
  3010. Return:     The number of ticks that have passed since the program was
  3011.         first executed is returned. clock()/CLOCK_TCK gives the time
  3012.         in seconds.
  3013. -------------------------------------------------------------------------
  3014. Name:        ctime
  3015.  
  3016. Synopsis:   char *ctime(t)
  3017.         time_t *t;
  3018.  
  3019. Function:   Equivalent to asctime(localtime(t)).
  3020.  
  3021. Arguments:  t - pointer to a time_t obtained from time().
  3022.  
  3023. Return:     A pointer to a string is returned. The string is in "static"
  3024.         memory and may be overwritten by other calls.
  3025.  
  3026. See Also:   asctime, localtime, time
  3027. -------------------------------------------------------------------------
  3028. Name:        difftime
  3029.  
  3030. Synopsis:   long difftime(t1,t2)
  3031.         time_t t1, t2;
  3032.  
  3033. Function:   Obtains the difference between two times in seconds.
  3034.         t2 - t1.
  3035.  
  3036. Arguments:  t1, t2 - times to take the difference of
  3037.  
  3038. Return:     Time difference in seconds.
  3039.  
  3040. See Also:   time
  3041. -------------------------------------------------------------------------
  3042. Name:        gmtime
  3043.  
  3044. Synopsis:   struct tm *gmtime(t)
  3045.         time_t *t;
  3046.  
  3047. Function:   Same as localtime because Coordinated Universal Time is not
  3048.         readily available on the amiga.
  3049.  
  3050. Arguments:  t - pointer to a time_t obtained from time().
  3051.  
  3052. Return:     Same as localtime.
  3053. -------------------------------------------------------------------------
  3054. Name:        localtime
  3055.  
  3056. Synopsis:   struct tm *localtime(t)
  3057.         time_t *t;
  3058.  
  3059. Function:   Fills out a tm structure from the time obtained from time().
  3060.  
  3061. Arguments:  t - pointer to a time_t obtained from time().
  3062.  
  3063. Return:     A tm structure is returned. This structure is located in
  3064.         "static" memory and will be overwritten by later calls. For
  3065.         an explanation of the tm structure see the heading for this
  3066.         section.
  3067.  
  3068. See Also:   time
  3069. -------------------------------------------------------------------------
  3070. Name:        mktime
  3071.  
  3072. Synopsis:   time_t mktime(tm)
  3073.         struct tm *tm;
  3074.  
  3075. Function:   This function is the opposite of localtime, it converts a
  3076.         tm structure into a time_t.
  3077.  
  3078. Arguments:  tm - pointer to a tm structure
  3079.  
  3080. Return:     A time_t that can be used by the other time functions is
  3081.         returned.
  3082. -------------------------------------------------------------------------
  3083. Name:        strftime
  3084.  
  3085. Synopsis:   size_t strftime(s,smax,fmt,tm)
  3086.         char *s;
  3087.         size_t smax;
  3088.         char *fmt;
  3089.         struct tm *tm;
  3090.  
  3091. Function:   Formats date and time information into a string according to
  3092.         a format string.
  3093.  
  3094. Arguments:  s - string to store the result
  3095.         smax - maximum number of characters to place in the string
  3096.         fmt - format string, ordinary characters including the NULL
  3097.         terminator are copied to the result string. Format specifiers
  3098.         have the the following possible values:
  3099.  
  3100.            %a    abbreviated weekday name
  3101.            %A    full weekday name
  3102.            %b    abbreviated month name
  3103.            %B    full month name
  3104.            %c    local date and time representation
  3105.            %d    day of the month
  3106.            %H    hour, 24 hour clock
  3107.            %I    hour, 12 hour clock
  3108.            %j    day of the year, 1-366
  3109.            %m    month, 1-12
  3110.            %M    minute, 00-59
  3111.            %p    AM or PM
  3112.            %S    second 00-59
  3113.            %U    week number of year 00-53
  3114.            %w    weekday, 0-6
  3115.            %W    same as U
  3116.            %x    local date representation
  3117.            %X    local time representation
  3118.            %y    year without century
  3119.            %Y    year with century
  3120.            %Z    "Local"
  3121.            %%    '%'
  3122.  
  3123. Return:     The number of characters written excluding the NULL terminator
  3124.         is returned, zero is returned if the result string would be
  3125.         overflowed.
  3126. -------------------------------------------------------------------------
  3127. Name:        time
  3128.  
  3129. Synopsis:   time_t time(t)
  3130.         time_t *t;
  3131.  
  3132. Function:   Obtains the current time, if the t argument is not NULL then
  3133.         the time is also assigned to *t.
  3134.  
  3135. Arguments:  t - pointer to variable to store the current time, or NULL.
  3136.  
  3137. Return:     The current time is returned.
  3138. -------------------------------------------------------------------------
  3139.  
  3140.       IV) INSTALLATION
  3141.  
  3142.    In order to use CClib.library you will first have to install the
  3143.    provided header files in a directory. Some of these header files
  3144.    have the same name as the ones used by your C and you will have to
  3145.    make sure that the CClib.library header files are found first. The
  3146.    best way to assure this is to use the -I option of the compiler.
  3147.    When you link your program you will have to make sure that it gets
  3148.    linked in this order: _main.o yourstuff.o ... cclib.lib.
  3149.  
  3150.    The _main.c file and the provided object modules are compatable with
  3151.    Aztec C 3.6a so if you are a user of Lattice C you will have to modify
  3152.    the _main.c file so that it works with Lattice C. You will also have to
  3153.    re-build the library of connection routines. Full support for Lattice
  3154.    will be coming in a future release.
  3155.  
  3156. -------------------------------------------------------------------------
  3157.  
  3158.       V) THE NUKELIB PROGRAM
  3159.  
  3160.       The nukelib program is used to remove a library from memory. The
  3161.       syntax of the program is very simple;
  3162.  
  3163.       NukeLib <library name>
  3164.  
  3165.       for example:
  3166.  
  3167.       NukeLib CClib.library
  3168.  
  3169.       This will clear CClib.library from memory if no applications are using
  3170.       it at the time.
  3171.  
  3172. -------------------------------------------------------------------------
  3173.  
  3174.       VI) RELEASE INFORMATION
  3175.  
  3176.       This release contains:
  3177.  
  3178.       cclib.doc     This Documentation
  3179.       cclib.lib     Aztec 3.6 compatable library of connection routines
  3180.       CClib.library    The loadable Amiga C library
  3181.       nukelib        Utility program
  3182.       test        Test program
  3183.       _main.o        Aztec 3.6 compatable _main replacement.
  3184.  
  3185.       source (dir)      Source code directory
  3186.      test.c
  3187.      test.mke
  3188.      _main.c
  3189.  
  3190.       include (dir)     Include files
  3191.      alloc.h assert.h ccfunc.h ctype.h
  3192.      errno.h fcntl.h heapmem.h iolib.h
  3193.      limits.h stat.h stdarg.h stdio.h
  3194.      stdlib.h stdlist.h string.h time.h
  3195.  
  3196.       con.zoo         Source for connection routine library
  3197.        102.con 108.con 114.con 120.con 126.con 132.con
  3198.        138.con 144.con 150.con 156.con 162.con 168.con
  3199.        172.con 180.con 186.con 192.con 198.con 204.con
  3200.        210.con 216.con 222.con 228.con 234.con 240.con
  3201.        246.con 252.con 258.con 264.con 270.con 276.con
  3202.        282.con 288.con 294.con 30.con 300.con 306.con
  3203.        312.con 318.con 324.con 330.con 336.con 342.con
  3204.        348.con 354.con 36.con 360.con 366.con 372.con
  3205.        378.con 384.con 390.con 396.con 402.con 408.con
  3206.        414.con 42.con 420.con 426.con 432.con 438.con
  3207.        444.con 450.con 456.con 462.con 468.con 474.con
  3208.        48.con 480.con 486.con 492.con 498.con 504.con
  3209.        510.con 516.con 522.con 528.con 534.con 54.con
  3210.        540.con 546.con 552.con 558.con 564.con 570.con
  3211.        576.con 582.con 588.con 594.con 60.con 600.con
  3212.        606.con 612.con 618.con 624.con 630.con 636.con
  3213.        642.con 648.con 654.con 66.con 660.con 666.con
  3214.        672.con 678.con 684.con 690.con 696.con 702.con
  3215.        714.con 72.con 720.con 726.con 732.con 738.con
  3216.        744.con 750.con 756.con 762.con 768.con 774.con
  3217.        78.con 780.con 786.con 792.con 798.con 804.con
  3218.        810.con 816.con 822.con 84.con 90.con 96.con
  3219.        all.con blocksize.c
  3220.        cclib.mke
  3221.        cclibcon.i
  3222.        math.c
  3223.  
  3224. -------------------------------------------------------------------------
  3225.  
  3226.       VII) REVISION HISTORY
  3227.  
  3228.     8/89 - V1.0 Initial release, beta testing.
  3229.  
  3230.     9/89 - V1.1 Major bug fixes, documentation released, extensive testing,
  3231.        time functions added, nukelib program added.
  3232.  
  3233. -------------------------------------------------------------------------
  3234.  
  3235.       VIII) COPYRIGHTS AND TRADEMARKS
  3236.  
  3237.       Aztec C is a trademark of Manx Software Systems.
  3238.       Lattice C is a trademark of Lattice Inc.
  3239.       Amiga is a trademark of Commodore Business Machines Inc.
  3240.  
  3241. -------------------------------------------------------------------------
  3242.  
  3243.