mirror of
https://github.com/adtools/clib2.git
synced 2025-12-08 14:59:05 +00:00
1fbe4bd0a5
git-svn-id: file:///Users/olsen/Code/migration-svn-zu-git/logical-line-staging/clib2/trunk@14900 87f5fb63-7c3d-0410-a384-fd976d0f7a62
<!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.</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 fdlibm 5.3, 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> <h3>2.1 Thread-safety</h3> <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 '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 variants of <tt>rand()</tt> and <tt>localtime()</tt> called <tt>rand_r()</tt>, <tt>localtime_r()</tt>, and others. The use of the socket I/O functions is still 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. Also yet unsolved is the issue of reading error codes from the <tt>errno</tt> variable which currently always contains the error code left by the last caller.</p> <p>Take care: 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> 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> <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 in 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 '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@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 code is currently plastered with assertions and debug code. It is therefore much larger than it ought to be and runs much slower than it ought to be. For example, the <tt>malloc()</tt> routine will set the contents of the memory allocated to a 'dirty' bit pattern which is likely to break software which makes assumptions about its contents. Likewise, the <tt>free()</tt> routine will trash the memory to deallocate with a different 'dirty' bit pattern to turn up reuse of memory after deallocation. All these debugging features can be disabled by defining the <tt>NDEBUG</tt> preprocessor symbol at compile time (see <tt><assert.h></tt>).</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 <tt>GNUmakefile.68k</tt> for the 68k platform and <tt>GNUmakefile.os4</tt> for the AmigaOS4 PowerPC version.</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>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> <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> <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>olsen@sourcery.han.de</p> </body> </html>