home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 6 / FreshFish_September1994.bin / new / dev / c / hce / docs / lib.doc < prev    next >
Text File  |  1992-09-02  |  62KB  |  1,442 lines
  1. The C libraries provided with HCE are the original Sozobon-C libraries
  2. by Dale Schumacher, which were partially ported from the ATARI ST by 
  3. Jeff Lydiatt on the 17th june 1989 (ZC distribution). The only changes
  4. I have made to these libraries since, are bug fixes to 'stdio.lib',
  5. the addition of 'environment.c' to 'Misc.lib', and also changed 
  6. parts of the maths library for math routines from Detlef Wuerkner`s 
  7. 'HCC.lib' (HCC distribution).
  8.  
  9. Note about this document.
  10. -------------------------
  11. This document is based on the 'zc.lib.doc' by Jeff Lydiatt, which was based
  12. on the original 'dlibs.libs' document by Dale Schumacher for the ATARI ST.
  13. I have rewritten many parts, added some new stuff and also taken out 
  14. the parts which were only meant for the ATARI ST.
  15.  
  16. Note about error return values.
  17. -------------------------------
  18. On the ATARI ST functions return negative values on error.
  19. On the AMIGA functions may generate a positive value on error.
  20. If the global variable 'errno' contains a positve value, consider it to be
  21. an error returned from AmigaDos, via IoErr().
  22.  
  23. Note about 'Math.lib'.
  24. ----------------------
  25. The maths library uses the motorola fast floating point routines exclusively.
  26. The keyword 'float' acts the same as 'double'.
  27. The 'mathffp.library' and the 'mathtrans.library' are opened and closed
  28. each time you use one of there functions. If you open these libraries 
  29. yourself then you most also close them yourself.
  30.  
  31. Note about all libs.
  32. ---------------------
  33. The standard C libraries comprise of the following:
  34.  
  35.                               Maths.lib
  36.                               Misc.lib
  37.                               Stdio.lib
  38.                               String.lib
  39.  
  40. Normally all of the above files (except Maths.lib) would be joined to
  41. make a single C library. I have kept them seperate to try and make
  42. bug fixing and updating a bit easier.
  43.  
  44.  
  45.                         TABLE OF CONTENTS
  46.                       
  47.       Header files .................................. L64
  48.       Process control ............................... L151
  49.       Memory management ............................. L271
  50.       File handling ................................. L301
  51.       Input & Output ................................ L538
  52.       Formatting & Type conversion .................. L688
  53.       String manipulation ........................... L891
  54.       Charater functions ............................ L1102
  55.       Date & Time functions ......................... L1172
  56.       Searching & Sorting ........................... L1215
  57.       Error handling ................................ L1288
  58.       Variable argument lists ....................... L1310
  59.       Miscellaneous ................................. L1335
  60.       Revision record ............................... L1418
  61.       Final note .................................... L1427
  62.  
  63. **********************************************************************
  64. *                         HEADER FILES:                              *
  65. **********************************************************************
  66.  
  67. ar.h
  68.  This header defines the library archive header used by 'ar'.
  69.  
  70. assert.h
  71.  This header defines the assert() run-time condition checking macro.
  72.  
  73. basepage.h
  74.  The BASEPAGE struct and the _base variable, which is initialized
  75.  to point to the current process basepage, are defined in this file.
  76.  
  77. ctype.h
  78.  Character classification and conversion.
  79.  The isxxxx() macros and toxxxx() macros are defined in this file.
  80.  
  81. errno.h
  82.  This file defines the error code constants, the errno variable
  83.  and related error handling functions.
  84.  
  85. fcntl.h
  86.  This file defines the O_xxxx constants used by open().
  87.  
  88. limits.h
  89.  Various maximum and minimum values are defined by this file.
  90.  Among these are PATHSIZE and MAXINT.
  91.  
  92. macros.h
  93.  This file contains a few useful macros including min(), max(),
  94.  abs() and swap().
  95.  
  96. math.h
  97.  This file contains difines such as MAXDOUBLE and MAXFLOAT
  98.  and also contains function return values for all math functions.
  99.  
  100. setjmp.h
  101.  This file defines the buffer needed to save your context when
  102.  using setjmp()/longjmp() or catch()/throw().
  103.  
  104. stat.h
  105.  The struct stat and the file mode flag constants are defined
  106.  in this file.
  107.  
  108. stdarg.h
  109.  This header defines the type and macros needed for variable
  110.  argument list processing.
  111.  
  112. stddef.h
  113.  This is the root header file which should be included in all
  114.  programs.  It defines NULL, size_t, ptrdiff_t and the
  115.  offsetof() macro. (this file is included in stdio.h)
  116.  
  117. stdio.h
  118.  This header file should be present in nearly all C programs.
  119.  It defines the 'FILE' struct, EOF and contains extern
  120.  declarations for standard i/o (Stdio.lib) and other commonly 
  121.  used functions. For convenience, the constants TRUE, FALSE and 
  122.  ERROR are also defined in this file, although this is 
  123.  somewhat non-standard. Also this header file includes 
  124.  the <stddef.h> and the <stdlib.h> as these files are 
  125.  needed in most C programs anyway.
  126.  
  127. stdlib.h
  128.  Function prototypes and defines for Misc.lib.
  129.  This file defines the return values for the dynamic memory
  130.  managment functions, malloc(),calloc(),lalloc(),free() etc.
  131.  It also defines the return values for rand(),time(),mkdir() and
  132.  chk_abort().It also contains the defines for exit(), such as
  133.  EXIT_SUCCESS and EXIT_FAILURE.(this file is included by stdio.h)
  134.  
  135. string.h
  136.  This file defines aliases for string function names (since some
  137.  string functions have various names on different systems) and
  138.  extern declarations for all string functions.
  139.  
  140. time.h
  141.  This file defines time related constants and structures, and
  142.  extern declarations for the time functions.(Misc.lib)
  143.  
  144. types.h
  145.  Thie file contains typedefs for many special and/or non-standard
  146.  type names.  Many of the typedefs in this file define type names
  147.  which are ANSI and/or System V standard.  This file is included
  148.  by several other header files, and includes <stddef.h>.
  149.  
  150. ***********************************************************************
  151. *                  PROCESS CONTROL: (misc.lib)                        *
  152. ***********************************************************************
  153.  
  154.     You should include <stdlib.h> in your program if you use functions
  155.     from this section.(contains prototypes)
  156.  
  157. int _main()
  158.      This function defines the standard streams, checks to see which
  159.      of them are devices, and calls the user's main() function.
  160.      The startup module calls this function to start the C program. 
  161.      The following standard streams are initialized by _main():
  162.  
  163.      stdin   - Standard input, may be redirected
  164.      stdout  - Standard output, may be redirected
  165.      stderr  - Usually the system console
  166.  
  167.      The global variables '_argc', and  '_argv' are used to
  168.      store the values to be passed to the user's main().  If main()
  169.      returns then exit() is called with an EXIT_SUCCESS status.
  170.  
  171. int main(int argc, char *argv[])
  172.      This function is not actually in the standard libraries, 
  173.      but must be present somewhere in the user's code. 
  174.      The parameters passed to it by '_main()' are the number of 
  175.      arguments in the command line and a pointer to the arguments.
  176.      The return value from 'main()' is passed, by '_main()', to 'exit()'. 
  177.      Therefore, you should always 'return()' from 'main()', or call 
  178.      'exit()' directly.
  179.  
  180. void exit(int status)
  181.      Flushes and closes all open streams.
  182.      Returns <status> to the computers operating system.
  183.  
  184. void abort()
  185.      Prints the message "^C" to stderr and calls exit() with a 
  186.      status code of 3.
  187.  
  188. char *getenv(char *v)
  189.      Search for environment variable *v.  
  190.      If *v is found, a pointer to the string contained in the env variable
  191.      is returned. A NULL return value indicates, not found.
  192.  
  193. int setenv(char *v, *s)
  194.     Sets environment variable *v to string *s.
  195.     Returns success/failure indicator.(0=failure,1=success)
  196.     note: To embed a space in a file name, precede it with 
  197.           the escape delimiter.(usually a backslash).
  198.           This applies to all env functions.
  199.  
  200. int putenv(char *s)
  201.     The form is:
  202.                  
  203.     <VARIABLE>=<value>
  204.  
  205.     Set an envirenment varible to <value>.
  206.     Returns success/failure indicator.(0=failure,1=success)
  207.  
  208. char *ParseEnv(char *s)
  209.     ParseEnv(