mirror of https://github.com/adtools/clib2.git
7f0f7929ba
- Replaced ISO Latin 1 code #160 with a plain blank space (ASCII code #32) where necessary git-svn-id: file:///Users/olsen/Code/migration-svn-zu-git/logical-line-staging/clib2/trunk@15305 87f5fb63-7c3d-0410-a384-fd976d0f7a62 |
||
|---|---|---|
| .. | ||
| BUILDING.html | ||
| GCC-68K.html | ||
| README.html | ||
| specs | ||
README.html
<!DOCTYPE html public "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>An ISO 'C' (1994) compliant runtime library for the Amiga</title>
<body>
<h1>An ISO 'C' (1994) compliant runtime library for the Amiga</h1>
<h2>1. What is this?</h2>
<p>This is my attempt to get Samba 2.2.x ported to the Amiga. My first Amiga
port required SAS/C and a number of strange tricks had to be pulled to get
it to support the kind of environment Samba needed. But with the
introduction of Samba 2.2.x many of those tricks did not work any more,
which is why I decided to attack the problem at the root, namely the
runtime library.</p>
<p>Because it was no longer possible to build Samba with SAS/C on the new
Amiga platform, the idea came up to move development to the GNU 'C'
compiler. This turned out to be a challenge due to its somewhat
underdeveloped runtime library and header files. Eventually, I decided to
rewrite that library from scratch.</p>
<h2>2. What does it do?</h2>
<p>Using <i>'C' - A reference manual</i> (4th edition) as a reference I wrote a set of
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. 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
programming in the Unix environent</i>.</p>
<p>This is not a portable implementation of the library in the sense that you
could move it from one 'C' compiler on one operating system to another.
This is an Amiga specific implementation.</p>
<p>The library supports floating point math, which, for the 68k platform, is
limited to IEEE single and double precision or M68881 inline math. There is no
support for the fast floating point (FFP) format or exclusive IEEE single
precision. You either get double precision (IEEE math) or extended precision
(M68881 inline math). What it is that you get is determined at compile time.
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 <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>
<h2>3. What does it not do?</h2>
<p>This library is a departure from the typical 'C' runtime environments of the
past which had to run on all AmigaOS releases, down to Kickstart 1.1. This
very library was designed to take advantage of the routines available since
Kickstart 2.04 was introduced and virtually nobody ever put to use. This helps
to cut the code size, and it also helps to keep bugs out of the library by
falling back onto well-tested implementations. However, the catch is that the
code won't run under Kickstart 1.3 and below. But then these operating system
releases have been obsolete for more than a decade, and you can always go back
to a compiler environment which supports them.</p>
<p>There is very little support for <tt>amiga.lib</tt> functionality. There is <tt>NewList()</tt>,
<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 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. 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
unlike <tt>memcpy()</tt> is documented to, <tt>bcopy()</tt> supports overlapping copies.</p>
<p>Eventually, I wrote virtually all the code myself, borrowing algorithmic ideas
from the BSD libc and the Manx Aztec 'C' runtime library. Because I don't know
much about the environment GCC expects, I borrowed code snippets from libnix,
which was written by Matthias Fleischer and Gunther Nikl. This in particular
concerns the integer and floating point math support, the <tt>setjmp</tt>/<tt>longjmp</tt>
routines and the startup code. The M68881 inline math code comes from the
<tt><math-68881.h></tt> file written by Matthew Self <tt>(self [at] bayes.arc.nasa.gov)</tt>.</p>
<h2>5. Limitations and caveats</h2>
<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
autodocs for this library.</p>
<p>The exception handling in the math code is not particularly effective. For one
part this is due to the fact that there is no exception handler installed by
the runtime library when it starts up which could catch and process the error
conditions the CPU or FPU generates. The idea was to provide for a portable
runtime library with little to no assembly language involved. To make the
exception handling complete, such code would be necessary.</p>
<p>The library currently builds under SAS/C, but because the 'normal' program
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 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>
<p>The plain <tt>libc.a</tt>, which your software would be linked against by default, does not contain
any floating point support code. This means, for example, that <tt>printf("%f",...)</tt> will not produce
the desired output and that <tt>scanf("%f",...)</tt> may not read any data at all. If your
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. <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>
<h3>5.2 The thread-safe library</h3>
<p>Thread-safety does not imply that you can have multiple callers
access and close the same file. There is no resource tracking to that degree
yet. All that the thread-safety tries to afford you is not to get into big trouble
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 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 <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 problematic because the
underlying <tt>bsdsocket.library</tt> API is not supposed to be used by any process
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
<tt>__can_share_socket_library_base</tt> will be set to a non-zero value.</p>
<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
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 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
likely to crash, too, because <tt>exit()</tt> will clean up after all memory allocations
and files currently in use. Functions such as <tt>abort()</tt> and <tt>raise()</tt> may
call the <tt>exit()</tt> function indirectly. And the <tt>raise()</tt> function may
be invoked as part of the <tt>Control+C</tt> checking. You should make sure that the
signal handling does not affect any child processes. This can be done by replacing the
<tt>__check_abort()</tt> function or by disabling <tt>SIGINT</tt> processing altogether,
such as through a <tt>signal(SIGINT,SIG_IGN)</tt> call.</p>
<p> Also take care with file I/O involving the <tt>stdin</tt>/<tt>stdout</tt>/<tt>stderr</tt>
streams; read/write operations on these streams will be mapped to the <tt>Input()</tt>/<tt>Output()</tt>/<tt>ErrorOutput()</tt>
file handles of the process performing these operations. Since only this small set of
operations is mapped, functions such as <tt>fcntl()</tt> or <tt>select()</tt> will not
work on the <tt>stdin</tt>/<tt>stdout</tt>/<tt>stderr</tt> streams and the corresponding
file descriptors <tt>STDIN_FILENO</tt>/<tt>STDOUT_FILENO</tt>/<tt>STDERR_FILENO</tt>.
It is therefore strongly recommended to use the thread-safe library only for applications
which can cope with the limitations described above.</p>
<h3>5.3 Using gmon (PowerPC only)</h3>
<p>To use profiling, two steps are required. First of all, your program must be compiled with
the gcc command line option <tt>-pg</tt>. This instructs the compiler to generate special
profiling code in the prologue and epilogue of each function. Additionally, the program
must be linked with <tt>libprofile.a</tt>. To do this, either manually add
<tt>-lprofile</tt> to the linker command line, or modify the specs file as follows.
Find the lines that look like this (it may actually differ silghtily from your specs file,
but the important thing is that the line before the line to be modified reads <tt>lib:</tt>):
<pre>
lib:
--start-group -lc --end-group
</pre>
You will have to modify this to look like this:
<pre>
lib:
%{pg: -lprofile} --start-group -lc --end-group
</pre>
<p>Normally, the specs file is located at the compilers installation directory. For cross-compilers,
this is <tt>/usr/local/amiga/lib/gcc/ppc-amigaos/<i>compiler-version</i>/specs</tt>. For a native compiler,
it's in <tt>gcc:lib/gcc/ppc-amigaos/<i>compiler-version</i>/specs</tt>. Most likely, your compiler will already have this added to it's specs file.</p>
<p>Profiling makes use of a special PowerPC facility called the Performance Monitor. It
allows to "mark" tasks and count only during while a marked task is running. This allows
performance analysis to be made independant of the actual system load. The Performace Monitor
is available on all PowerPC models supported by AmigaOS 4 except for the <tt>603e</tt>, and
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.4 Implementation defined behaviour</h3>
<h4>5.4.1. 'C' language</h4>
<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><workbench/startup.h></tt>.</p>
<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 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.4.1.3. Floating-point</h5>
<p>The 68k version of clib2 supports single and double precision floating point numbers,
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 <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
simple addition and multiplication, such as <tt>sqrt()</tt>. These functions come from
Sun Microsystems <i>fdlibm 5.3</i> library.</p>
<p>Unless your software is linked against <tt>libm.a</tt> no floating point functions will
be available to it, possibly causing a linker error. When using the GNU 'C' compiler, you will
want to add the option <tt>-lm -lc</tt> to the linker command line.</p>
<p>The exception handling is currently entirely out of control of the developer
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.4.2. Library functions</h4>
<h5>5.4.2.1. <tt>NULL</tt></h5>
<p>The <tt>NULL</tt> pointer constant is defined in the <tt><stddef.h></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.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>
<blockquote><tt>[<i>program name</i>] <i>file</i>:<i>line</i>: failed assertion "<i>condition</i>".</tt></blockquote>
<p>where:</p>
<table border=0>
<tr><th align=right>program name</th><td>Optional program name; if the program name is not yet known, then the
entire text enclosed in square brackets will be omitted.</td></tr>
<tr><th align=right>file</th><td>The value of the <tt>__FILE__</tt> symbol at the location of the <tt>assert()</tt> call.</td></tr>
<tr><th align=right>line</th><td>The value of the <tt>__LINE__</tt> symbol at the location of the <tt>assert()</tt> call.</td></tr>
<tr><th align=right>condition</th><td>The condition passed to the <tt>assert()</tt> function.</td></tr>
</table>
<p>If available, the diagnostic messages will be sent to <tt>stderr</tt>.</p>
<p>If the program was launched from Workbench or if the global variable <tt>__no_standard_io</tt> is set
to a non-zero value, then the assertion failure message will not be displayed in the shell window, but
in a requester window. The diagnostic message shown in this window will take the following form:</p>
<blockquote><tt>Assertion of condition "<i>condition</i>" failed in file "<i>file</i>", line <i>line</i>.</tt></blockquote>
<p>The name of the program, if it is know at that time, will be displayed in the requester window title.</p>
<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 be delayed
until a library function which polls for the signal examines it. This means, for example, that
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.4.2.4. Files</h5>
<p>No new line characters are written unless specifically requested.</p>
<p>Space characters in a text stream before a new line character are read in and not discarded.</p>
<p>When data is read from a file, the last character does not have to be a new line character.</p>
<p>No NUL byte will be appended to data written to a binary stream.</p>
<p>There is no difference between text and binary streams.</p>
<p>Writing to a text or binary stream does not truncate the associated file. A stream may be
truncated by the initial <tt>fopen()</tt> call if the <tt>mode</tt> parameter starts with
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.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>
<p>The <tt>%a</tt>, <tt>%e</tt>, <tt>%f</tt>, <tt>%g</tt>, <tt>%A</tt>,
<tt>%E</tt>, <tt>%F</tt> and <tt>%G</tt> specifiers will produce the string <tt>inf</tt>
for infinity.</p>
<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>
<p>In the <tt>%[</tt> conversion a <tt>-</tt> (dash) character that is neither the
first nor the last character in the scanset indicates that a subrange of
characters should be used. Thus <tt>%[a-d]</tt> is equivalent to <tt>%[abcd]</tt>.</p>
<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.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
the global <tt>errno</tt> variable will be set to <tt>EINVAL</tt>.</p>
<p>In the <tt>libunix.a</tt> implementation a request to allocate
0 (zero) bytes will result in an allocation of at least 4 bytes, which will
be set to zero. Each zero length allocation will return a different
memory address.</p>
<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>
<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.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>
<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.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.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
to <tt>RETURN_FAIL</tt> as defined in the Amiga system header file
<tt><dos/dos.h></tt>; this value maps to the number 20. The value
of <tt>EXIT_SUCCESS</tt> is equivalent to <tt>RETURN_OK</tt> as defined in
the Amiga system header file <tt><dos/dos.h></tt>; this value maps to
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.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.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.
This follows the behaviour of the Amiga operating system function <tt>dos.library/System()</tt>.
A return value of 0 typically indicates successful execution and a value > 0
typically indicates failure.</p>
<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>,
respectively, in which <i>hh</i> stands for the difference between the local
time zone and Greenwich Mean Time.</p>
<p>The <tt>clock_t</tt> and <tt>time_t</tt> types are unsigned 32 bit integers.
The <tt>time_t</tt> epoch starts with midnight January 1st, 1970.</p>
<p>Daylight savings time is not supported.</p>
<p>The reference point used by the <tt>clock()</tt> function is the time
when the program was started.</p>
<h4>5.4.3. Locale specific behaviour</h4>
<p>The direction of printing is from left to right.</p>
<p>The period (.) is the decimal-point character.</p>
<p>The <tt>strftime()</tt> behaviour follows the Amiga operating system locale
settings. If the 'C' locale is in effect, then the output generated by the
<tt>%Z</tt> takes the form <tt>GMT+<i>hh</i></tt> or <tt>GMT-<i>hh</i></tt>,
respectively, in which <i>hh</i> stands for the difference between the local
time zone and Greenwich Mean Time.</p>
<h2>6. Conventions and design issues</h2>
<p>You will have noticed the 330+ files in this directory. This is not the best
way to organize a runtime library, but at least all the bits and pieces are in
plain sight. Each file stands for the one or two routines it contains. The
name indicates what routine(s) that might be. Each file name is prefixed by
the name of the header file in which the corresponding routine is defined. So,
for example, you will find that <tt>unistd_lchown.c</tt> contains the definition of
the <tt>lchown()</tt> routine, which has its prototype defined in the <tt><unistd.h></tt> header
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>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.</p>
<h2>7. The startup code</h2>
<p>There are three program startup files provided. The most simplistic is in
<tt>startup.c</tt> which I use for SAS/C. It just invokes the setup routine which
eventually calls <tt>main()</tt> and drops straight into <tt>exit()</tt>.</p>
<p>The <tt>ncrt0.S</tt> file was adapted from the libnix startup code which sets up the
base relative data area, if necessary (the <tt>SMALL_DATA</tt> preprocessor symbol must
be defined).</p>
<p>The <tt>nrcrt0.S</tt> file was adapted from libnix startup code, too, and sets up the
base relative data area for programs to be made resident. Note that the
<tt>geta4()</tt> stub is missing here; it wouldn't work in a resident program anyway.</p>
<p>The <tt>ncrt0.S</tt> and <tt>nrcrt0.S</tt> files are considerably smaller and less complex than
the libnix code they are based on. This is because in this library design all
the more complex tasks are performed in the <tt>stdlib_main.c</tt> file rather than in
assembly language.</p>
<h2>8. Documentation</h2>
<p>Well, you're reading it. There isn't anything much yet. You can consult the book
<i>'C' - A reference manual</i> and you could look at the
<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><dos.h></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>
<p>Because this library is in part based upon free software it would be
uncourteous not to make it free software itself. The BSD license would
probably be appropriate here.</p>
<p>The PowerPC math library is based in part on work by Sun Microsystems:</p>
<pre>
====================================================
Copyright (C) 1993 by Sun Microsystems, Inc. All rights reserved.
Developed at SunPro, a Sun Microsystems, Inc. business.
Permission to use, copy, modify, and distribute this
software is freely granted, provided that this notice
is preserved.
====================================================
</pre>
<h2>10. Contacting the author</h2>
<p>The basic work was done by Olaf Barthel during two weeks in July 2002. You
can reach me at:</p>
<p>Olaf Barthel<br>
Gneisenaustr. 43<br>
D-31275 Lehrte<br></p>
<p>Or via e-mail:</p>
<p>obarthel [at] gmx.net</p>
</body>
</html>