home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / tools / developer-tools / c-tools / vbcc / machines / amiga68k / doc / vclib.doc < prev   
Encoding:
Text File  |  1996-06-18  |  7.6 KB  |  268 lines
  1. vc.lib - C library for the Amiga68k version of vbcc
  2.  
  3.  
  4. INTRODUCTION
  5.  
  6.     vc.lib is a (rather) ANSI compliant C library for use with the
  7.     Amiga68k version of vbcc.
  8.  
  9.     It is written largely in C and some parts are not Amiga specific.
  10.  
  11.     You can also create a small data library (this one will probably
  12.     be in the archive already as vcs.lib), a small-code-version, a
  13.     020-version etc. or combinations of this (see COMPILING).
  14.  
  15.     Note that you have to link with a math library if you want to use
  16.     floating point. All math functions, special startup code and
  17.     printf/scanf functions which support floating point are contained in
  18.     the math libraries only.
  19.     At the moment there are three math libraries:
  20.  
  21.         mieee.lib   This one uses the C= math libraries. The startup code
  22.                     will always open MathIeeeSingBas.library,
  23.                     MathIeeeDoubBas.library and MathIeeeDoubTrans.library.
  24.                     Float return values are passed in d0, double return
  25.                     values are passed via pointers.
  26.                     A 68000 is sufficient to use this library.
  27.                     You must not specify -fpu=... when you use this library.
  28.  
  29.         m881.lib    This one uses direct FPU instructions and function
  30.                     return values are passed in fp0. You must have a
  31.                     68020 or higher and an FPU to use this library. You
  32.                     also have to specify -fpu=68881.
  33.                     Several FPU instructions that have to be emulated on
  34.                     040/060 may be used.
  35.  
  36.         m040.lib    This one uses only direct FPU instructions that do not
  37.                     have to be emulated on a 68040. For unsupported
  38.                     functions the MathIeee-libraries are called.
  39.                     Unfortunately the current C=-libraries still use the
  40.                     unsupported instructions, but there are replacement
  41.                     libraries available e.g. on aminet.
  42.                     Return values are passed in fp0.
  43.                     (This library should be used for 68060, too.)
  44.  
  45.     To link with one of those libraries add e.g. the -lmieee option to vc or
  46.     specify mieee.lib before vc.lib if you do the linking by hand.
  47.  
  48.     Some info about amiga.lib can be found in fd2lib.doc.
  49.  
  50.  
  51. LEGAL
  52.  
  53.     vc.lib is public domain. Certain parts have been taken from other
  54.     PD libraries (mainly libnix).
  55.     The same applies to m881.lib, m040.lib and mieee.lib.
  56.  
  57.  
  58. STARTUP etc.
  59.  
  60.     The startup code currently consists of a slightly modified standard
  61.     Amiga startup and the file _main.c. The startup code sets up some
  62.     global variables and initializes stdin, stdout and stderr.
  63.     The exit code closes all open files and frees all memory.
  64.     If you link with a math library the startup/exit code will be taken
  65.     from there if necessary.
  66.  
  67.  
  68. STDIO
  69.  
  70.     The following functions are implemented at the moment:
  71.  
  72.     fopen()     binary and text modes are the same
  73.     fclose()
  74.     fflush()
  75.     fgetc()
  76.     ungetc()
  77.     fputc()
  78.     fgets()
  79.     fputs()
  80.     fread()
  81.     fwrite()
  82.     gets()      never use it...
  83.     puts()
  84.     ftell()
  85.     fseek()
  86.     remove()
  87.     rename()
  88.     rewind()
  89.     setvbuf()
  90.     setbuf()
  91.     feof()
  92.     ferror()
  93.     prerror()
  94.     tmpnam()
  95.     tmpfile()   always returns an error at the moment
  96.     fgetpos()
  97.     fsetpos()
  98.     printf()    taken from libnix; link with a math library if you need fp
  99.     fprintf()     "
  100.     sprintf()     "
  101.     vprintf()     "
  102.     vfprintf()    "
  103.     vsprintf()    "
  104.     scanf()       "
  105.     fscanf()      "
  106.     sscanf()      "
  107.  
  108.     There are macros for a few functions. Some of them will cause a
  109.     warning 129. This is necessary to make them fully conforming. You can
  110.     safely ignore those warnings or use -dontwarn=129.
  111.  
  112.  
  113. STDLIB
  114.  
  115.     The following functions do exist.
  116.  
  117.     malloc()    uses a variation of the example in K&R;
  118.                 currently allocates chunks of at least _nalloc*8 bytes;
  119.                 you can set _nalloc after an extern size_t _nalloc;
  120.  
  121.                 There is an alternative file (libsrc/stdlib/newmalloc.o)
  122.                 which provides malloc(), free() and realloc() functions
  123.                 that call the memory pool functions of amiga.lib.
  124.                 If you link this file to your program those will be used.
  125.                 These functions are probably slower for malloc(), but
  126.                 much faster for free(), so if free() is used often it may
  127.                 be useful to link with this file.
  128.                 _nalloc has a similar meaning here, but chunks of _nalloc
  129.                 bytes are allocated rather than _nalloc*8 bytes.
  130.     free()
  131.     calloc()
  132.     realloc()
  133.     rand()      taken from libnix
  134.     srand()       "
  135.     system()    uses SystemTagList or Execute depending on OS version
  136.     abs()
  137.     labs()
  138.     div()
  139.     ldiv()
  140.     abort()
  141.     atexit()
  142.     getenv()    taken from libnix
  143.     qsort()       "
  144.     bsearch()     "
  145.     strtol()      "
  146.     strtoul()     "
  147.     atol()        "
  148.     atoi()        "
  149.     atof()      taken from libnix; link with a math library to use this
  150.     strtod()      "
  151.  
  152.  
  153. TIME
  154.  
  155.     The standard functions should exist. Taken from libnix.
  156.     clock() always returns -1.
  157.     Link with a math library if you use difftime().
  158.  
  159.  
  160. STRING
  161.  
  162.     The standard functions should exist.
  163.  
  164.  
  165. CTYPE
  166.  
  167.     The standard functions should exist.
  168.  
  169.  
  170. LIMITS
  171.  
  172.     No functions.
  173.  
  174.  
  175. FLOAT
  176.  
  177.     I do not know what has to be there, yet, but the most important things
  178.     should be there (and approximately correct). No functions.
  179.  
  180.  
  181. MATH
  182.  
  183.     You have to link with a math library to use these functions.
  184.     The following functions should be there, but they may be not precise
  185.     enough or otherwise not fully ANSI conform in some cases (e.g. errno
  186.     is not set and pow() with m881 is probably not fully conforming):
  187.  
  188.     sin(), cos(), tan()
  189.     sinh(), cosh(), tanh()
  190.     asin(), acos(), atan(), atan2()
  191.     exp(), log(), log10(), pow()
  192.     ceil(), floor()
  193.     sqrt()
  194.     fabs()
  195.     fmod()
  196.     ldexp(). frexp()
  197.  
  198.  
  199. STDDEF
  200.  
  201.     Currently defines size_t, fpos_t, ptrdiff_t, wchar_t, time_t, clock_t,
  202.     NULL and offsetof. No functions.
  203.  
  204.  
  205. STDARG
  206.  
  207.     Defines va_list, va_start, va_arg and va_end. Seems to work well, but
  208.     vbcc gives an 'offset equals size of object' warning. No functions.
  209.  
  210.  
  211. ASSERT
  212.  
  213.     Not really tested yet. No functions.
  214.  
  215.  
  216. ERRNO
  217.  
  218.     The include file and errno is there, but most functions do not set
  219.     errno. No functions.
  220.  
  221.  
  222. SETJMP
  223.  
  224.     Oh well...I only wrote down some lines, but never tested it.
  225.     Also I think maybe there should be a special version for fpu, but it
  226.     is not required by the ANSI standard AFAIK.
  227.  
  228.  
  229. SIGNAL
  230.  
  231.     signal() and raise() are there, but always return an error.
  232.  
  233.  
  234. LOCALE
  235.  
  236.     localeconv() and setlocale() are there, but setlocale() does not do
  237.     anything.
  238.  
  239.  
  240. Again, there may be some errors or missing things in the include files
  241. and the library.
  242.  
  243.  
  244. COMPILING
  245.  
  246.     If you want to compile the libraries yourself you should be able
  247.     to call the Make#?.script scripts from their directory and the rest
  248.     should be done automatically and the resulting .lib file will be
  249.     copied to vlib: (so take care you do not overwrite another library).
  250.     If you want to create special libraries (e.g. a vc.lib for 020+)
  251.     you have to edit the Make scripts.
  252.     E.g. to create the small-data-vcs.lib change add -sd in the
  253.     alias cc ... line and replace every following vc by vcs.
  254.  
  255.     Currently there is no small-data-version of the math libraries (it
  256.     should not make a difference with m881.lib, but with mieee.lib and
  257.     m040.lib).
  258.  
  259.  
  260. KNOWN PROBLEMS
  261.  
  262.     The startup-code ignores the return code if the program did not call
  263.     exit(), but returned from main().
  264.  
  265.  
  266. Volker                                              volker@vb.franken.de
  267.  
  268.