X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Flibrary.sgml;h=b2f8800513be91e420a4eac29a042849d9e6252d;hb=2eac69a94361323bf7556d2cdde8f61c85c5ef99;hp=79ef010041ce429c27346b9033e04ddca65f215f;hpb=e15f01a88280ed02ba3366e7cae6cc4d91c75a7c;p=cc65 diff --git a/doc/library.sgml b/doc/library.sgml index 79ef01004..b2f880051 100644 --- a/doc/library.sgml +++ b/doc/library.sgml @@ -1,10 +1,8 @@
- cc65 Library Overview -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>02.12.2000 +<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz"> <abstract> An overview over the runtime and C libraries that come with the cc65 compiler, @@ -18,10 +16,13 @@ including a discussion of the differences to the ISO standard. <sect>Overview<p> -This file contains a description of the library routines available for the -cc65 C compiler. It is not complete in some areas, so if you miss something, -have a look into the header files. All functions, that are not defined by the -ISO C standard have a short comment in the headers, explaining their use. +This file contains a short overview of the libraries available for the cc65 C +compiler. Please have a look at the <url url="funcref.html" name="function +reference"> for a list function by function. Since the function reference is +not complete (I'm working on that) it may happen that you don't find a +specific function. In this case, have a look into the header files. All +functions, that are not defined by the ISO C standard have a short comment in +the headers, explaining their use. @@ -35,66 +36,59 @@ I will not go into detail about the ISO functions. If a function is not mentioned here explicitly, expect it to be available and to behave as defined in the C standard. -Functions that are NOT available: +Functions that are <em/not/ available: <itemize> - - <item>ftell/fseek/fgetpos/fsetpos - - <item>tmpfile/tmpnam - - <item>The scanf family of functions - - <item>time/asctime/ctime/difftime/asctime/gmtime/localtime/mktime/strftime - - <item>system - + <item><tt>tmpfile/tmpnam</tt> + <p> + <item><tt>system</tt> (cc65 alternative <tt>exec</tt>) + <p> <item>All functions that handle floating point numbers in some manner. - - <item>The div and ldiv functions (because cc65 is not able to return - structs). - + <p> + <item>The <tt/ldiv/ function (cc65 is currently not able to return structs + with a size not equal to 1, 2 or 4 bytes by value). + <p> <item>All functions handling wide character strings. - - <item>Signals and all related functions (having SIGSEGV would be cool:-) - - <item>rename/remove/rewind - - <item>setbuf/setvbuf/ungetc - + <p> + <item>Signals and all related functions (having <tt/SIGSEGV/ would be + cool:-) + <p> + <item><tt>setbuf/setvbuf</tt> </itemize> -Functions that are limited in any way: +Functions not available on all supported systems: <itemize> + <item><tt>fopen/fread/fwrite/fclose/fputs/fgets/fscanf</tt>: The functions + are built on open/read/write/close. These latter functions are not available + on all systems. + <p> + <item><tt>ftell/fseek/fgetpos/fsetpos</tt>: Support depends on the + capabilities of the target machine. + <p> + <item><tt>rename/remove/rewind</tt>: Support depends on the capabilities of + the target machine. + <p> + <item><tt>time</tt>: Since many of the supported systems do not have a real + time clock, which means that the <tt/time/ function is not available. Please + note that the other functions from <tt/time.h/ <em/are/ available. +</itemize> - <item>fopen/fread/fwrite/fclose/fputs/fgets/fscanf.... - - These functions are built on open/read/write/close. Neither of these low - level functions is currently available for the supported systems, and so, - fopen and friends do not work. However, the functions exist and are tested - to some degree under the ACE operating systems (which is no longer - supported). - - - <item>strcspn/strpbrk/strspn - - These functions have a length limitation of 256 for the second string - argument. Since this string gives a character set, and there are only 256 - distinct characters, this shouldn't be a problem. - - - <item>getenv - - Since there is no such thing as an environment on all supported systems, the - getenv function will always return a NULL pointer. - - - <item>locale - There is no other locale than the "C" locale. The native locale is identical - to the "C" locale. +Functions that are limited in any way: +<itemize> + <item><tt>strcspn/strpbrk/strspn</tt>: These functions have a length + limitation of 256 for the second string argument. Since this string gives a + character set, and there are only 256 distinct characters, this shouldn't be + a problem. + <p> + <item><tt>getenv</tt>: Since there is no such thing as an environment on all + supported systems, the <tt/getenv/ function will always return a <tt/NULL/ + pointer. + <p> + <item><tt>locale</tt>: There is no other locale than the "C" locale. The + native locale is identical to the "C" locale. </itemize> @@ -102,17 +96,15 @@ In addition to these limitations, some more functions are limited if inlined versions are requested by using -Os: <itemize> - - <item>The strlen function only works for strings with a maximum length of - 255 characters. - - <item>The isxxx character classification functions from <tt/<ctype.h>/ - will give unpredictable results if the argument is not in character range - (0..255). This limitation may be removed by #undef'ing the function name - (when using -Os, the functions are actually macros that expand to inline - assembler code, but the real functions are still available if the macro - definition is removed). - + <item>The <tt/strlen/ function only works for strings with a maximum length + of 255 characters. + <p> + <item>The <tt/isxxx/ character classification functions from + <tt/<ctype.h>/ will give unpredictable results if the argument is not + in character range (0..255). This limitation may be removed by #undef'ing + the function name (when using <tt/-Os/, the functions are actually macros + that expand to inline assembler code, but the real functions are still + available if the macro definition is removed). </itemize> @@ -167,14 +159,27 @@ This has some disadvantages, but on the other side it's fast and reasonably portable. conio implementations exist for the following targets: <itemize> + <item>apple2 + <item>apple2enh <item>atari + <item>atarixl + <item>atmos + <item>c16 (works also for the c116 with up to 32K memory) <item>c64 <item>c128 - <item>plus4 + <item>plus4 (or expanded c16/c116) <item>cbm510 (40 column video) <item>cbm610 (all CBM series-II computers with 80 column video) + <item>creativision + <item>gamate + <item>geos-apple + <item>geos-cbm + <item>nes + <item>osic1p + <item>pce <item>pet (all CBM PET systems except the 2001) - <item>apple2 + <item>telestrat + <item>vic20 </itemize> The conio.h header file does also include the system specific header files @@ -186,8 +191,7 @@ which define constants for special characters and keys. For systems that have a joystick, <tt/joystick.h/ will define a subroutine to read the current value, including constants to evaluate the result of this -function. To help in writing portable code, the header file will define the -symbol <tt/__JOYSTICK__/ on systems that have a joystick. +function. @@ -197,30 +201,22 @@ Some target machines support a mouse. Mouse support is currently available for the following targets: <itemize> + <item>apple2 + <item>apple2enh <item>atari + <item>atarixl <item>c64 <item>c128 <item>cbm510 </itemize> -The available functions are declared in <tt/mouse.h/ To help writing portable -code, the header file will define the symbol <tt/__MOUSE__/ in systems that -support a mouse. - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - +The available functions are declared in <tt/mouse.h/. <sect>Copyright<p> This C runtime library implementation for the cc65 compiler is (C) -Copyright 1998-2001 Ullrich von Bassewitz. For usage of the binaries +Copyright 1998-2002 Ullrich von Bassewitz. For usage of the binaries and/or sources the following conditions do apply: This software is provided 'as-is', without any expressed or implied @@ -243,6 +239,3 @@ freely, subject to the following restrictions: </enum> </article> - - -