github/amiga-clib2
1
0
Fork 0
mirror of https://github.com/adtools/clib2.git synced 2025-12-08 14:59:05 +00:00
Code Issues Releases Wiki Activity

- More corrections and clarifications.

Browse Source 
git-svn-id: file:///Users/olsen/Code/migration-svn-zu-git/logical-line-staging/clib2/trunk@15080 87f5fb63-7c3d-0410-a384-fd976d0f7a62
This commit is contained in:
Olaf Barthel
2006-01-18 10:23:17 +00:00
parent b2bc0096dc
commit 9be142d251
1 changed files with 53 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
documentation/README.html
View File

@ -28,7 +28,8 @@ rewrite that library from scratch.</p>
header files, then proceeded to implement each single function referenced in
them. With few exceptions in the area of wide character support, the result
should be a feature complete implementation of the ISO 'C' (1994) runtime
library.</p>
library. The library was subsequently updated to offer functionality defined in
<i>ISO/IEC 9899:1999</i>, also known as <i>C99</i>.</p>
<p>Because Samba needs a few POSIX-like routines to be supported, the library
functionality is complemented by a set of routines described in <i>Advanced
@ -46,17 +47,10 @@ precision. You either get double precision (IEEE math) or extended precision
Use the <tt>IEEE_FLOATING_POINT_SUPPORT</tt> preprocessor symbol to activate IEEE math
code and the <tt>M68881_FLOATING_POINT_SUPPORT</tt> symbol for M68881 inline math.</p>
<p>For the PowerPC platform, the library uses code borrowed from fdlibm 5.3,
<p>For the PowerPC platform, the library uses code borrowed from <i>fdlibm 5.3</i>,
which is a portable library of arithmetic functions developed by Sun
Microsystems which, for example, is also used within the Java platform.</p>
<p>Not unlike SAS/C, you can configure a minimum stack size the program is to use
when it starts up. This is controlled via the <tt>__stack_size</tt> variable (see
<tt>stdlib_main.c</tt>).</p>
<p>I added some <tt>amiga.lib</tt> and <tt>debug.lib</tt> functionality to the library, but don't
count on it to be complete.</p>
<h2>3. What does it not do?</h2>
<p>This library is a departure from the typical 'C' runtime environments of the
@ -73,13 +67,13 @@ to a compiler environment which supports them.</p>
<tt>HookEntry()</tt>, <tt>CallHook()</tt>, <tt>CallHookA()</tt>, the <tt>DoMethod()</tt> family, the RexxVars
family, but that's all. If you need more, you would have to implement it
yourself. Put another way, if you absolutely need functionality that is only
found in <tt>amiga.lib</tt>, you really shouldn't need in in the first place.</p>
found in <tt>amiga.lib</tt>, you really shouldn't need it in the first place.</p>
<h2>4. Where does the source code come from?</h2>
<p>I originally thought that it might be helpful to piece this library together
from various sources, such as the BSD libc. Turned out that this code was so
from various sources, such as the BSD libc. It turned out that this code was so
'portable' that it became much more complex than it ought to be. Also, some
side-effects were present which considerably changed the behaviour of the
library. For example, the BSD libc uses <tt>bcopy()</tt> as an alias for <tt>memcpy()</tt>, and
@ -99,7 +93,7 @@ routines and the startup code. The M68881 inline math code comes from the
<p>There is hardly any documentation on the code I wrote. In part this is due to
the fact that the code itself is very simple in design. It should speak for
itself. However, to make a usable runtime library you have to have a user
documentation as in man pages or autodocs. We will eventually have to have
documentation as in man pages or AutoDocs. We will eventually have to have
autodocs for this library.</p>
<p>The exception handling in the math code is not particularly effective. For one
@ -114,8 +108,8 @@ startup code is not utilized, the base relative (A4) addressing does not work.
If you are going to test it, use the <tt>data=faronly</tt> option to compile the
library and the programs.</p>
<p>Different build makefiles are supplied for use with GCC. There is
<tt>GNUmakefile.68k</tt> for the 68k platform and <tt>GNUmakefile.os4</tt> for the AmigaOS4
<p>Different build makefiles are supplied for use with GCC. There is a
<tt>GNUmakefile.68k</tt> for the 68k platform and a <tt>GNUmakefile.os4</tt> for the AmigaOS4
PowerPC version.</p>
<h3>5.1 Floating point math and functions (<tt>scanf()</tt>, <tt>printf()</tt>, etc.) </h3>
@ -126,7 +120,7 @@ the desired output and that <tt>scanf("%f",...)</tt> may not read any data at al
program needs functions such as these or <tt>atod()</tt> then you must link against <tt>libm.a</tt> or
the equivalent.</p>
<p>To link the floating point support code with your software, use the <tt>-lm</tt> compiler option. Careful!
<p>To link the floating point support code with your software, use the <tt>-lm</tt> compiler option. <em>Careful!</em>
The order in which you specify the libraries to link against is important here. Thus, <tt>gcc -o test test.c -lm -lc</tt>
would correctly link the program <tt>test</tt> against the proper floating point math library, but
<tt>gcc -o test test.c -lc -lm</tt> would not.</p>
@ -140,15 +134,15 @@ if simultaneous and overlapping accesses to files, memory allocation and other
resources are taking place.</p>
<p>The library code is supposed to be thread-safe if built with the <tt>__THREAD_SAFE</tt>
preprocesssor symbold defined. Note that 'thread-safe' does <em>not</em> mean
preprocesssor symbol defined. Note that 'thread-safe' does <em>not</em> mean
'reentrant'. Multiple callers for certain library functions are permitted, but
not for all of them. For example, <tt>mkdtemp()</tt> is not thread-safe, and neither is
<tt>rand()</tt> or <tt>localtime()</tt>. But as per <b>POSIX 1003.1c-1995</b> there are thread-safe
<tt>rand()</tt> or <tt>localtime()</tt>. But as per <i>POSIX 1003.1c-1995</i> there are thread-safe
variants of <tt>rand()</tt> and <tt>localtime()</tt> called <tt>rand_r()</tt>, <tt>localtime_r()</tt>, and others.</p>
<p>The use of the socket I/O functions is still problematic because the
<p>The use of the socket I/O functions is problematic because the
underlying <tt>bsdsocket.library</tt> API is not supposed to be used by any process
other than the one that opened it. While one TCP/IP stack (my own "Roadshow") allows you
other than the one which opened it. While one TCP/IP stack (my own "Roadshow") allows you
to share the library base among different processes, if so configured, it is the
exception. No other TCP/IP stack available for the Amiga robustly supports a similar
feature. If the TCP/IP stack supports this feature, then the global variable
@ -156,11 +150,11 @@ feature. If the TCP/IP stack supports this feature, then the global variable
<p>Errors reported by the socket I/O functions which modify the global variables
<tt>errno</tt> and <tt>h_errno</tt> may be directed to call the <tt>__set_errno()</tt>
and <tt>__set_h_errno()</tt> functions instead if the TCP/IP stack supports this feature. The global
and <tt>__set_h_errno()</tt> functions instead, if the TCP/IP stack supports this feature. The global
variable <tt>__thread_safe_errno_h_errno</tt> will be set to a non-zero value if it does.</p>
<p>A much more serious problem resides with the <tt>exit()</tt>, <tt>abort()</tt>,
<tt>assert()</tt> and <tt>raise()</tt> functions, and the how <tt>SIGINT</tt> signal is
<tt>assert()</tt> and <tt>raise()</tt> functions, and how the <tt>SIGINT</tt> signal is
processed. In the thread-safe library only the <tt>main()</tt> function may directly
or indirectly call the <tt>exit()</tt> function. No child process may do so, since this
would wreck its stack context, crashing it instantly; the main program would be very
@ -210,36 +204,39 @@ is available on all PowerPC models supported by AmigaOS 4 except for the <tt>603
embedded versions of the PowerPC like the <tt>405</tt> and <tt>440</tt> series. Consult the manual
of the appropriate chip for more information.</p>
<h3>5.6 Implementation defined behaviour</h3>
<h3>5.4 Implementation defined behaviour</h3>
<h4>5.6.1. 'C' language</h4>
<h4>5.4.1. 'C' language</h4>
<h5>5.6.1.1. Environment</h5>
<h5>5.4.1.1. Environment</h5>
<p>The <tt>main(int argc,char **argv);</tt> function may be called with an <tt>argc</tt> value of 0,
in which case the <tt>argv</tt> variable will contain a pointer to the Amiga Workbench startup
message, which is of type <tt>struct WBStartup *</tt>, and is defined in the Amiga system header
file <tt>&lt;workbench/startup.h&gt;</tt>.</p>
<h5>5.6.1.2. Characters</h5>
<h5>5.4.1.2. Characters</h5>
<p>The current locale is derived from the current Amiga operating system locale settings. The
<tt>setlocale("")</tt> function call will choose the current Amiga operating system locale settings.
Any other name passed to the <tt>setlocale()</tt> function, with the except of <tt>"C"</tt>,
Any other name passed to the <tt>setlocale()</tt> function, with the exception of <tt>"C"</tt>,
which selects the 'C' locale, must be a locale name, as used by the Amiga operating system
function <tt>OpenLocale()</tt> in <tt>locale.library</tt>.</p>
<h5>5.6.1.3. Floating-point</h5>
<h5>5.4.1.3. Floating-point</h5>
<p>The 68k version of clib2 supports single and double precision floating point numbers,
according to the IEEE 754 standard. The software floating point number support is built upon the Amiga
according to the <i>IEEE 754</i> standard. The software floating point number support is built upon the Amiga
operating system libraries <tt>mathieeesingbas.library</tt>, <tt>mathieeedoubbas.library</tt>
and <tt>mathieeedoubtrans.library</tt>. The hardware floating point number support uses
the M68881/M68882/M68040/M68060 floating point unit intead.</p>
<p>The PowerPC version of clib2 supports only double precision floating point numbers, according to
the IEEE 754 standard, because that is exactly what the PowerPC CPU supports. Single precision
numbers may be implicitly converted to double precision numbers.</p>
the <i>IEEE 754</i> standard, because that is exactly what the PowerPC CPU supports. Single precision
numbers may be implicitly converted to double precision numbers. This also means that the <i>C99</i>
data type <tt>long double</tt> is identical to the <tt>double</tt> data type. Because there is no
difference between these two, the library omits support for <i>C99</i> functions specifically designed
to operate on <tt>long double</tt> data types, such as <tt>rintl()</tt>.</p>
<p>Both the 68k and the PowerPC versions of clib2 may call software floating point support
routines in order to perform double and single precision operations that go beyond
@ -256,15 +253,15 @@ and solely subject to the rules imposed by the operating system itself.</p>
<p>The <tt>fmod()</tt> function returns the value of the <tt>x</tt> parameter and
sets <tt>errno</tt> to <tt>EDOM</tt> if the <tt>y</tt> parameter value is 0.</p>
<h4>5.6.2. Library functions</h4>
<h4>5.4.2. Library functions</h4>
<h5>5.6.2.1. <tt>NULL</tt></h5>
<h5>5.4.2.1. <tt>NULL</tt></h5>
<p>The <tt>NULL</tt> pointer constant is defined in the <tt>&lt;stddef.h&gt;</tt> header and
will expand to <tt>((void *)0L)</tt> if the 'C' compiler is used. For a C++ compiler the constant
will expand to <tt>0L</tt> instead.</p>
<h5>5.6.2.2. <tt>assert()</tt> diagnostic messages</h5>
<h5>5.4.2.2. <tt>assert()</tt> diagnostic messages</h5>
<p>The diagnostic messages printed by the <tt>assert()</tt> function take the following form:</p>
@ -289,22 +286,23 @@ in a requester window. The diagnostic message shown in this window will take the
<p>The name of the program, if it is know at that time, will be displayed in the requester window title.</p>
<h5>5.6.2.3. Signal handling</h5>
<h5>5.4.2.3. Signal handling</h5>
<p>Only the minimum of required signals are supported by this library. These are <tt>SIGABRT</tt>, <tt>SIGFPE</tt>,
<tt>SIGILL</tt>, <tt>SIGINT</tt>, <tt>SIGSEGV</tt> and <tt>SIGTERM</tt>.</p>
<p>As of this writing <tt>SIGFPE</tt> is never called by the floating point library functions.</p>
<p>The <tt>Ctrl+C</tt> event is translated into <tt>SIGINT</tt>. Signal delivery may delayed
<p>The <tt>Ctrl+C</tt> event is translated into <tt>SIGINT</tt>. Signal delivery may be delayed
until a library function which polls for the signal examines it. This means, for example, that
a runaway program called in an infinite loop cannot be aborted by sending it a <tt>Ctrl+C</tt> event.</p>
a runaway program caught in an infinite loop cannot be aborted by sending it a <tt>Ctrl+C</tt> event unless special code
is added which tests for the presence of the signal and calls the <tt>__check_abort()</tt> all on its own.</p>
<p>Processing of the <tt>Ctrl+C</tt> event involves the internal <tt>__check_abort()</tt> function which
polls for the presence of the event and which will call <tt>raise(SIGINT);</tt>. The <tt>__check_abort()</tt>
function may be replaced by user code.</p>
<h5>5.6.2.4. Files</h5>
<h5>5.4.2.4. Files</h5>
<p>No new line characters are written unless specifically requested.</p>
@ -322,7 +320,7 @@ the letter <tt>w</tt>.</p>
<p>The file position indicator is initially set to the end of an append mode stream.</p>
<h5>5.6.2.5. <tt>printf()</tt> family</h5>
<h5>5.4.2.5. <tt>printf()</tt> family</h5>
<p>The <tt>%p</tt> conversion is the hexadecimal representation of the pointer, and
it is preceded by the string <tt>0x</tt>.</p>
@ -331,7 +329,7 @@ it is preceded by the string <tt>0x</tt>.</p>
<tt>%E</tt>, <tt>%F</tt> and <tt>%G</tt> specifiers will produce the string <tt>inf</tt>
for infinity.</p>
<h5>5.6.2.6. <tt>scanf()</tt> family</h5>
<h5>5.4.2.6. <tt>scanf()</tt> family</h5>
<p>The input for the <tt>%p</tt> conversion must be a hexadecimal number,
preceded by either the string <tt>0x</tt> or <tt>0X</tt>.</p>
@ -343,7 +341,7 @@ characters should be used. Thus <tt>%[a-d]</tt> is equivalent to <tt>%[abcd]</tt
<p>The period (.) is the decimal-point character. The locale specific decimal-point
character is accepted as an alternative to the period (.).</p>
<h5>5.6.2.7. <tt>malloc()</tt>, <tt>realloc()</tt> and <tt>calloc()</tt></h5>
<h5>5.4.2.7. <tt>malloc()</tt>, <tt>realloc()</tt> and <tt>calloc()</tt></h5>
<p>In the standard <tt>libc.a</tt> implementation any request to allocate
0 (zero) bytes will fail. A result value of <tt>NULL</tt> will be returned and
@ -354,7 +352,7 @@ the global <tt>errno</tt> variable will be set to <tt>EINVAL</tt>.</p>
be set to zero. Each zero length allocation will return a different
memory address.</p>
<h5>5.6.2.8. <tt>rename()</tt></h5>
<h5>5.4.2.8. <tt>rename()</tt></h5>
<p>In the standard <tt>libc.a</tt> implementation the <tt>rename()</tt> function
will fail if there already is a file or directory by the new name to be used.</p>
@ -362,7 +360,7 @@ will fail if there already is a file or directory by the new name to be used.</p
<p>In the <tt>libunix.a</tt> implementation the <tt>rename()</tt> function will
delete any existing file or directory by the new name.</p>
<h5>5.6.2.9. <tt>remove()</tt></h5>
<h5>5.4.2.9. <tt>remove()</tt></h5>
<p>In the standard <tt>libc.a</tt> implementation the <tt>remove()</tt> function
will fail if the file is protected by deletion or currently in use.</p>
@ -370,12 +368,12 @@ will fail if the file is protected by deletion or currently in use.</p>
<p>In the <tt>libunix.a</tt> implementation the <tt>remove()</tt> function
will remove the file when the program exits or the file is closed.</p>
<h5>5.6.2.10. <tt>abort()</tt></h5>
<h5>5.4.2.10. <tt>abort()</tt></h5>
<p>The <tt>abort()</tt> function will flush all buffered files,
close all the files currently open and delete temporary files.</p>
<h5>5.6.2.11. <tt>exit()</tt> and <tt>_Exit()</tt></h5>
<h5>5.4.2.11. <tt>exit()</tt> and <tt>_Exit()</tt></h5>
<p>The value passed to the <tt>exit()</tt> function will be passed to the
Amiga operating system. The value of <tt>EXIT_FAILURE</tt> is equivalent
@ -388,13 +386,13 @@ the number 0.</p>
<p>The <tt>_Exit()</tt> function will flush all buffered files,
close all the files currently open and delete temporary files.</p>
<h5>5.6.2.12. <tt>getenv()</tt></h5>
<h5>5.4.2.12. <tt>getenv()</tt></h5>
<p>Environment data is retrieved from the global Amiga operating system environment
storage area through the <tt>dos.library/GetEnv()</tt> function. Global variables are
stored in files in the <tt>ENV:</tt> directory.</p>
<h5>5.6.2.13. <tt>system()</tt></h5>
<h5>5.4.2.13. <tt>system()</tt></h5>
<p>If the <tt>command</tt> parameter is not NULL and the <tt>system()</tt> function returns, then the result will
be equivalent to the exit code of the program invoked, or -1 if the program could not be started.
@ -402,7 +400,7 @@ This follows the behaviour of the Amiga operating system function <tt>dos.librar
A return value of 0 typically indicates successful execution and a value &gt; 0
typically indicates failure.</p>
<h5>5.6.2.14. Time</h5>
<h5>5.4.2.14. Time</h5>
<p>The default time zone is derived from the Amiga operating system locale
settings and takes the form <tt>GMT+<i>hh</i></tt> or <tt>GMT-<i>hh</i></tt>,
@ -417,7 +415,7 @@ The <tt>time_t</tt> epoch starts with midnight January 1st, 1970.</p>
<p>The reference point used by the <tt>clock()</tt> function is the time
when the program was started.</p>
<h4>5.6.3. Locale specific behaviour</h4>
<h4>5.4.3. Locale specific behaviour</h4>
<p>The direction of printing is from left to right.</p>
@ -443,30 +441,11 @@ file.</p>
<p>Internal function and variables which need to be visible across several
modules have names prefixed with two underscores, as in <tt>__stdio_init()</tt>.</p>
<p>All routines attempt to do error checking on their parameters. They will
either drop into an <tt>assert()</tt> or set an errno value and refuse to go any
further. This cuts performance but should help to catch the simple bugs quite
easily (<tt>NULL</tt> pointers).</p>
<p>Just like any halfway sane Amiga 'C' runtime library, this one performs its <tt>^C</tt>
checking in the I/O routines. Typically once upon entry and in every iteration
of the loop there might be it will quickly poll the <tt>^C</tt> signal and drop into
<tt>raise(SIGINT)</tt> in case the signal is set. This is just about the safest method
to solve the problem and should be much more robust than the ixemul approach
of 'interrupt anywhere - crash anywhere' using the task switch/launch hooks to
test for signals.</p>
<p>By default all library routines follow the ISO 'C' conventions in that where
implementation defined behaviour is permitted, the AmigaOS rules are followed.
For example, <tt>unlink()</tt> will by default operate like <tt>DeleteFile()</tt> and <tt>rename()</tt>
will return with an error code set if the name of the file/directory to be
renamed would collide with an existing directory entry. However, your program
can set a global variable <tt>__unix_semantics</tt> which will cause some routines to
perform like their Unix counterparts. This is necessary for Samba to work but
not a generally desirable feature. You have some Unix-like behaviour, but the
environment itself is not completely Unix- or POSIX-compliant. And it
shouldn't be. Don't make the mistake of trying to mold the environment into a
POSIX emulation. It doesn't work; AmigaOS is not Unix.</p>
renamed would collide with an existing directory entry.</p>
<h2>7. The startup code</h2>
@ -496,6 +475,12 @@ assembly language.</p>
<a href="http://www.opengroup.org/onlinepubs/007904975">Open Group's Single Unix
Specification</a>.</p>
<p>It is recommended to browse the contents of the <tt>include</tt> directory. The
header files contain information on library behaviour and not just data type and
function prototype definitions. Specifically, the <tt>&lt;dos.h&gt;</tt> header file
contains documentation about special libraries and global variables which may be
used or replaced by user code.</p>
<h2>9. Legal status</h2>