Annotation of /trunk/mkinitrd-magellan/klibc/usr/klibc/CAVEATS

	  -------------------------------------------------
	  Please note the following caveats when using klibc:
	  -------------------------------------------------

optimization:
-------------
Compiling with -O0 is not supported.  It may or may not work; please
use -O1 if you want to do maximize debuggability.

Compiling with -O0 is more likely to work on gcc 3.


setjmp()/longjmp():
-------------------
setjmp() and longjmp() *do not* save signal state.  sigsetjmp() and
siglongjmp() *do* save the signal mask -- regardless of the value of
the extra argument.

The standards actually state that if you pass longjmp() a final value
of zero the library should change that to a 1!  Presumably the reason
is so people who write broken code can get away with writing
longjmp(buf); or something equally bad.  If you pass longjmp() a final
value of 0 you get what you deserve -- setjmp() will happily return 0.


stdio:
------
Only a small subset of the stdio functions are implemented.  Those
that are implemented do not buffer, although they *do* trap EINTR or
short read/writes and iterate.

_fread() and _fwrite(), which take only one size argument (like
read/write), but do handle EINTR/short return are also available.


namespaces:
-----------
klibc frequently includes headers in other headers in a way that
exposes more symbols than POSIX says they should.  "Live with it."


theading:
---------
klibc is not thread-safe.  Consequently, clone() or any of the
pthreads functions are not included.


bsd_signal vs sysv_signal:
--------------------------
signal() now defaults to bsd_signal().
1	niro	532	-------------------------------------------------
2	niro	1297	Please note the following caveats when using klibc:
3	niro	532	-------------------------------------------------
4
5			optimization:
6			-------------
7			Compiling with -O0 is not supported. It may or may not work; please
8			use -O1 if you want to do maximize debuggability.
9
10			Compiling with -O0 is more likely to work on gcc 3.
11
12
13			setjmp()/longjmp():
14			-------------------
15			setjmp() and longjmp() do not save signal state. sigsetjmp() and
16			siglongjmp() do save the signal mask -- regardless of the value of
17			the extra argument.
18
19			The standards actually state that if you pass longjmp() a final value
20			of zero the library should change that to a 1! Presumably the reason
21			is so people who write broken code can get away with writing
22			longjmp(buf); or something equally bad. If you pass longjmp() a final
23			value of 0 you get what you deserve -- setjmp() will happily return 0.
24
25
26			stdio:
27			------
28			Only a small subset of the stdio functions are implemented. Those
29			that are implemented do not buffer, although they do trap EINTR or
30			short read/writes and iterate.
31
32			_fread() and _fwrite(), which take only one size argument (like
33			read/write), but do handle EINTR/short return are also available.
34
35
36			namespaces:
37			-----------
38			klibc frequently includes headers in other headers in a way that
39			exposes more symbols than POSIX says they should. "Live with it."
40
41
42			theading:
43			---------
44			klibc is not thread-safe. Consequently, clone() or any of the
45			pthreads functions are not included.
46
47
48			bsd_signal vs sysv_signal:
49			--------------------------
50	niro	815	signal() now defaults to bsd_signal().