From e4f9d1b7f628ecf4bef81c22aaa74408f83427c7 Mon Sep 17 00:00:00 2001 From: Olaf Barthel Date: Sun, 20 Nov 2005 19:02:44 +0000 Subject: [PATCH] - Updated the general documentation and started to document the implementation-specific behaviour of the library functions. git-svn-id: file:///Users/olsen/Code/migration-svn-zu-git/logical-line-staging/clib2/trunk@15065 87f5fb63-7c3d-0410-a384-fd976d0f7a62 --- documentation/README.html | 205 +++++++++++++++++++++++++++++++++++--- 1 file changed, 190 insertions(+), 15 deletions(-) diff --git a/documentation/README.html b/documentation/README.html index f27e6f1..bd91602 100644 --- a/documentation/README.html +++ b/documentation/README.html @@ -71,13 +71,13 @@ underlying bsdsocket.library API is not supposed to be used by any proc other than the one that 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. Any attempt to enable it by default would introduce incompatibilities which -might be difficult to support.

+feature. If the TCP/IP stack supports this feature, then the global variable +__can_share_socket_library_base will be set to a non-zero value.

-

Also yet unsolved is the issue of reading -error codes from the errno variable which currently always contains the -error code left by the last caller. This is also the case for the global h_errno -variable, which the socket I/O name resolution functions may change.

+

Errors reported by the socket I/O functions which modify the global variables +errno and h_errno may be directed to call the __set_errno() +and __set_h_errno() functions instead if the TCP/IP stack supports this feature. The global +variable __thread_safe_errno_h_errno will be set to a non-zero value if it does.

A much more serious problem resides with the exit(), abort(), assert() and raise() functions, and the how SIGINT signal is @@ -137,15 +137,6 @@ 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.

-

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 malloc() 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 free() 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 NDEBUG preprocessor symbol at compile time (see <assert.h>).

-

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 @@ -221,6 +212,190 @@ is available on all PowerPC models supported by AmigaOS 4 except for the 603 embedded versions of the PowerPC like the 405 and 440 series. Consult the manual of the appropriate chip for more information.

+

5.6 Implementation defined behaviour

+ +

5.6.1. 'C' language

+ +
5.6.1.1. Environment
+ +

The main(int argc,char **argv); function may be called with an argc value of 0, +in which case the argv variable will contain a pointer to the Amiga Workbench startup +message, which is of type struct WBStartup *, and is defined in the Amiga system header +file <workbench/startup.h>.

+ +
5.6.1.2. Characters
+ +

The current locale is derived from the current Amiga operating system locale settings. The +setlocale("") function call will choose the current Amiga operating system locale settings. +Any other name passed to the setlocale() function, with the except of "C", +which selects the 'C' locale, must be a locale name, as used by the Amiga operating system +function OpenLocale() in locale.library.

+ +
5.6.1.3. Floating-point
+ +

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 +operating system libraries mathieeesingbas.library, mathieeedoubbas.library +and mathieeedoubtrans.library. The hardware floating point number support uses +the M68881/M68882/M68040/M68060 floating point unit intead.

+ +

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.

+ +

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 sqrt(). These functions come from +Sun Microsystems fdlibm 5.3 library.

+ +

Unless your software is linked against libm.a 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 -lm -lc to the linker command line.

+ +

The exception handling is currently entirely out of control of the developer +and solely subject to the rules imposed by the operating system itself.

+ +

5.6.2. Library functions

+ +
5.6.2.1. NULL
+ +

The NULL pointer constant is defined in the <stddef.h> header and +will expand to ((void *)0L) if the 'C' compiler is used. For a C++ compiler the constant +will expand to 0L instead.

+ +
5.6.2.2. assert() diagnostic messages
+ +

The diagnostic messages printed by the assert() function take the following form:

+ +
[program name] file:line: failed assertion "condition".
+ +

where:

+ + + + + +
program nameOptional program name; if the program name is not yet known, then the +entire text enclosed in square brackets will be omitted.
fileThe value of the __FILE__ symbol at the location of the assert() call.
lineThe value of the __LINE__ symbol at the location of the assert() call.
conditionThe condition passed to the assert() function.
+ +

If available, the diagnostic messages will be sent to stderr.

+ +

If the program was launched from Workbench or if the global variable __no_standard_io 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:

+ +
Assertion of condition "condition" failed in file "file", line line.
+ +

The name of the program, if it is know at that time, will be displayed in the requester window title.

+ +
5.6.2.3. Signal handling
+ +

Only the minimum of required signals are supported by this library. These are SIGABRT, SIGFPE, +SIGILL, SIGINT, SIGSEGV and SIGTERM.

+ +

As of this writing SIGFPE is never called by the floating point library functions.

+ +

The Ctrl+C event is translated into SIGINT. Signal delivery may 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 Ctrl+C event.

+ +

Processing of the Ctrl+C event involves the internal __check_abort() function which +polls for the presence of the event and which will call raise(SIGINT);. The __check_abort() +function may be replaced by user code.

+ +
5.6.2.4. Files
+ +

No new line characters are written unless specifically requested.

+ +

Space characters in a text stream before a new line character are read in and not discarded.

+ +

When data is read from a file, the last character does not have to be a new line character.

+ +

No NUL byte will be appended to data written to a binary stream.

+ +

There is no difference between text and binary streams.

+ +

Writing to a text or binary stream does not truncate the associated file.

+ +

The file position indicator is initially set to the end of an append mode stream.

+ +
5.6.2.5. printf() family
+ +

The %p conversion is the hexadecimal representation of the pointer, and +it is preceded by the string 0x.

+ +
5.6.2.6. scanf() family
+ +

The input for the %p conversion must be a hexadecimal number, +preceded by either the string 0x or 0X.

+ +

In the %[ conversion a - (dash) character that is neither the +first nor the last character in the scanset indicates that a subrange of +characters should be used. Thus %[a-d] is equivalent to %[abcd].

+ +

The period (.) is the decimal-point character. The locale specific decimal-point +character is accepted as an alternative to the period (.).

+ +
5.6.2.7. malloc(), realloc() and calloc()
+ +

In the standard libc.a implementation any request to allocate +0 (zero) bytes will fail. A result value of NULL will be returned and +the global errno variable will be set to EINVAL.

+ +

In the libunix.a implementation a request to allocate +0 (zero) bytes will result in an allocation of at least 1 byte, which will +be set to zero. Each zero length allocation will return a different +memory address.

+ +
5.6.2.8. rename()
+ +

In the standard libc.a implementation the rename() function +will fail if there already is a file or directory by the new name to be used.

+ +

In the libunix.a implementation the rename() function will +delete any existing file or directory by the new name.

+ +
5.6.2.9. remove()
+ +

In the standard libc.a implementation the remove() function +will fail if the file is protected by deletion or currently in use.

+ +

In the libunix.a implementation the remove() function +will remove the file when the program exits or the file is closed.

+ +
5.6.2.10. abort()
+ +

The abort() function will flush all buffered files and +close all the files currently open. Memory allocated will be freed. + +

5.6.2.11. exit()
+ +

The value passed to the exit() function will be passed to the +Amiga operating system. The value of EXIT_FAILURE is equivalent +to RETURN_FAIL as defined in the Amiga system header file +<dos/dos.h>; this value maps to the number 20. The value +of EXIT_SUCCESS is equivalent to RETURN_OK as defined in +the Amiga system header file <dos/dos.h>; this value maps to +the number 0.

+ +
5.6.2.11. Time
+ +

The default time zone is derived from the Amiga operating system locale +settings and takes the form GMT+hh or GMT-hh, +respectively in which hh stands for the difference between the local +time zone and Greenwich Mean Time.

+ +

Daylight savings time is not supported.

+ +

The reference point used by the clock() function is the time +when the program was started.

+ +

5.6.3. Locale specific behaviour

+ +

The direction of printing is from left to right.

+ +

The period (.) is the decimal-point character.

+

6. Conventions and design issues

You will have noticed the 330+ files in this directory. This is not the best