mirror of https://github.com/adtools/clib2.git
518 lines
27 KiB
HTML
518 lines
27 KiB
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>
|