home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 13 / AACD13.ISO / AACD / Programming / vbcc_MorphOS / machines / amiga / doc / vclib68k.doc < prev    next >
Text File  |  2000-08-20  |  9KB  |  303 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 four 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 in d0/d1.
  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 040/060. Other functions use
  38.                     the Motorola emulation routines modified by
  39.                     Aki M Laukkanen.
  40.                     It should be used for programs compiled for 040 or 060
  41.                     with FPU and replaces the former m040.lib which is now
  42.                     called m040o.lib.
  43.                     Return values are passed in fp0.
  44.  
  45.         m040o.lib   This one uses only direct FPU instructions that do not
  46.                     have to be emulated on a 68040. For unsupported
  47.                     functions the MathIeee-libraries are called.
  48.                     Unfortunately the current C=-libraries still use the
  49.                     unsupported instructions, but there are replacement
  50.                     libraries available e.g. on aminet.
  51.                     Return values are passed in fp0.
  52.                     This library should be obsolete.
  53.  
  54.  
  55.     To link with one of those libraries add e.g. the -lmieee option to vc or
  56.     specify mieee.lib before vc.lib if you do the linking by hand.
  57.  
  58.     Some info about amiga.lib can be found in fd2lib.doc.
  59.  
  60.  
  61. LEGAL
  62.  
  63.     vc.lib is public domain. Certain parts have been taken from other
  64.     PD libraries (mainly libnix).
  65.     The same applies to m881.lib, m040.lib and mieee.lib.
  66.  
  67.  
  68. STARTUP etc.
  69.  
  70.     The startup code currently consists of a slightly modified standard
  71.     Amiga startup and the file _main.c. The startup code sets up some
  72.     global variables and initializes stdin, stdout and stderr.
  73.     The exit code closes all open files and frees all memory.
  74.     If you link with a math library the startup/exit code will be taken
  75.     from there if necessary.
  76.  
  77.  
  78. INLINING
  79.  
  80.     Several header-files provide support for inlining of certain library
  81.     functions. If the preprocessor-symbol __INLINE_<function> is defined
  82.     the corresponding function may be inlined. E.g if you compile with
  83.  
  84.         vc -O3 -D__INLINE_STRCPY
  85.  
  86.     then calls to strcpy() will be inlined. Note however that the symbol
  87.     must be defined at the time string.h is included and, of course, that
  88.     function inlining must be turned on.
  89.  
  90.     Not all library functions are prepared for inlining but only those
  91.     that are reasonably small, are not implemented as macros and can
  92.     safely be inlined. E.g. __INLINE_QSORT will be ignored.
  93.  
  94.     The symbol __INLINE_ALL will cause inlining of all functions which
  95.     can be inlined.
  96.  
  97.     You must have the source to the library functions in the appropriate
  98.     directories, e.g. strcpy must be reachable via
  99.  
  100.         #include "vbccm68k:libsrc/string/strcpy.c"
  101.  
  102.     (This could be a problem when cross-compiling.)
  103.  
  104.  
  105. STDIO
  106.  
  107.     The following functions are implemented at the moment:
  108.  
  109.     fopen()     binary and text modes are the same
  110.     fclose()
  111.     fflush()
  112.     fgetc()
  113.     ungetc()
  114.     fputc()
  115.     fgets()
  116.     fputs()
  117.     fread()
  118.     fwrite()
  119.     gets()      never use it...
  120.     puts()
  121.     ftell()
  122.     fseek()
  123.     remove()
  124.     rename()
  125.     rewind()
  126.     setvbuf()
  127.     setbuf()
  128.     feof()
  129.     ferror()
  130.     prerror()
  131.     tmpnam()
  132.     tmpfile()   always returns an error at the moment
  133.     fgetpos()
  134.     fsetpos()
  135.     printf()    taken from libnix; link with a math library if you need fp
  136.     fprintf()     "
  137.     sprintf()     "
  138.     vprintf()     "
  139.     vfprintf()    "
  140.     vsprintf()    "
  141.     scanf()       "
  142.     fscanf()      "
  143.     sscanf()      "
  144.  
  145.     There are macros for a few functions. Some of them will cause a
  146.     warning 129. This is necessary to make them fully conforming. You can
  147.     safely ignore those warnings or use -dontwarn=129.
  148.  
  149.  
  150. STDLIB
  151.  
  152.     The following functions do exist.
  153.  
  154.     malloc()    uses a variation of the example in K&R;
  155.                 currently allocates chunks of at least _nalloc*8 bytes;
  156.                 you can set _nalloc after an extern size_t _nalloc;
  157.  
  158.                 There is an alternative file (libsrc/stdlib/newmalloc.o)
  159.                 which provides malloc(), free() and realloc() functions
  160.                 that call the memory pool functions of amiga.lib.
  161.                 If you link this file to your program those will be used.
  162.                 These functions are probably slower for malloc(), but
  163.                 much faster for free(), so if free() is used often it may
  164.                 be useful to link with this file.
  165.                 _nalloc has a similar meaning here, but chunks of _nalloc
  166.                 bytes are allocated rather than _nalloc*8 bytes.
  167.     free()
  168.     calloc()
  169.     realloc()
  170.     rand()      taken from libnix
  171.     srand()       "
  172.     system()    uses SystemTagList or Execute depending on OS version
  173.     abs()
  174.     labs()
  175.     div()
  176.     ldiv()
  177.     abort()
  178.     atexit()
  179.     getenv()    taken from libnix
  180.     qsort()       "
  181.     bsearch()     "
  182.     strtol()      "
  183.     strtoul()     "
  184.     atol()        "
  185.     atoi()        "
  186.     atof()      taken from libnix; link with a math library to use this
  187.     strtod()      "
  188.  
  189.  
  190. TIME
  191.  
  192.     The standard functions should exist. Taken from libnix.
  193.     clock() always returns -1.
  194.     Link with a math library if you use difftime().
  195.  
  196.  
  197. STRING
  198.  
  199.     The standard functions should exist.
  200.  
  201.  
  202. CTYPE
  203.  
  204.     The standard functions should exist.
  205.  
  206.  
  207. LIMITS
  208.  
  209.     No functions.
  210.  
  211.  
  212. FLOAT
  213.  
  214.     I do not know what has to be there, yet, but the most important things
  215.     should be there (and approximately correct). No functions.
  216.  
  217.  
  218. MATH
  219.  
  220.     You have to link with a math library to use these functions.
  221.     The following functions should be there, but they may be not precise
  222.     enough or otherwise not fully ANSI conform in some cases (e.g. errno
  223.     is not set and pow() with m881 is probably not fully conforming):
  224.  
  225.     sin(), cos(), tan()
  226.     sinh(), cosh(), tanh()
  227.     asin(), acos(), atan(), atan2()
  228.     exp(), log(), log10(), pow()
  229.     ceil(), floor()
  230.     sqrt()
  231.     fabs()
  232.     fmod()
  233.     ldexp(). frexp()
  234.  
  235.     If _M68881, _M68040 or _M68060 is #defined when math.h is included
  236.     inline assembly will be generated for certain functions.
  237.  
  238.  
  239. STDDEF
  240.  
  241.     Currently defines size_t, fpos_t, ptrdiff_t, wchar_t, time_t, clock_t,
  242.     NULL and offsetof. No functions.
  243.  
  244.  
  245. STDARG
  246.  
  247.     Defines va_list, va_start, va_arg and va_end. Seems to work well, but
  248.     vbcc gives an 'offset equals size of object' warning. No functions.
  249.  
  250.  
  251. ASSERT
  252.  
  253.     Not really tested yet. No functions.
  254.  
  255.  
  256. ERRNO
  257.  
  258.     The include file and errno is there, but most functions do not set
  259.     errno. No functions.
  260.  
  261.  
  262. SETJMP
  263.  
  264.     Oh well...I only wrote down some lines, but never tested it.
  265.     Also I think maybe there should be a special version for fpu, but it
  266.     is not required by the ANSI standard AFAIK.
  267.  
  268.  
  269. SIGNAL
  270.  
  271.     signal() and raise() are there, but always return an error.
  272.  
  273.  
  274. LOCALE
  275.  
  276.     localeconv() and setlocale() are there, but setlocale() does not do
  277.     anything.
  278.  
  279.  
  280. Again, there may be some errors or missing things in the include files
  281. and the library.
  282.  
  283.  
  284. COMPILING
  285.  
  286.     If you want to compile the libraries yourself you should be able
  287.     to call the Make#?.script scripts from their directory and the rest
  288.     should be done automatically and the resulting .lib file will be
  289.     copied to vlib: (so take care you do not overwrite another library).
  290.     If you want to create special libraries (e.g. a vc.lib for 020+)
  291.     you have to edit the Make scripts.
  292.     E.g. to create the small-data-vcs.lib change add -sd in the
  293.     alias cc ... line and replace every following vc by vcs.
  294.  
  295.     Currently there is no small-data-version of the math libraries (it
  296.     should not make a difference with m881.lib, but with mieee.lib and
  297.     m040.lib).
  298.  
  299.  
  300.  
  301. Volker                                              volker@vb.franken.de
  302.  
  303.