$NetBSD: README,v 1.3 2015/03/20 14:10:40 riastradh Exp $
libc: The C library.
* ELF symbols and source names
libc contains symbols for:
(a) standard library routines in C and POSIX,
(b) published NetBSD-specific nonstandard extensions,
(c) old versions of library routines, and
(d) internal symbols.
If a library routine is standard and its signature has never changed,
it is defined as an ELF global symbol. Its name is declared normally
in the appropriate header file.
=> Example: libc defines global symbols `malloc' and `free' for the
standard C memory allocator routines. The names `malloc' and `free'
are declared normally in <stdlib.h> (src/include/stdlib.h).
If a library routine is nonstandard but published and its signature has
never changed, it is defined as an ELF weak symbol aliasing an ELF
global symbol of the same name with an underscore prefix.
The name is declared normally in the appropriate header file, provided
that the relevant feature macro, such as _NETBSD_SOURCE, is defined.
Within libc, the name is defined in "namespace.h"
(src/lib/libc/include/namespace.h) as a macro expanding to the
underscored name, so that the definition in a .c file will define the
underscored ELF global symbol.
Alongside the definition in the .c file is a __weak_alias directive to
create the ELF weak symbol alias.
=> Example: For the nonstandard extension consttime_memequal, libc
defines a weak symbol `consttime_memequal' aliasing a global symbol
`_consttime_memequal'.
The header file <string.h> (src/include/string.h) declares
`consttime_memequal' normally, if the caller defines _NETBSD_SOURCE.
The header file "namespace.h" (src/lib/libc/include/namespace.h)
defines `consttime_memequal' as a macro expanding to
`_consttime_memequal'.
The source file src/common/lib/libc/string/consttime_memequal.c
includes "namespace.h" and <string.h>, and defines
`consttime_memequal' normally, which, after macro expansion, causes
the ELF global symbol `_consttime_memequal' to be defined.
Alongside the definition is
__weak_alias(consttime_memequal,_consttime_memequal)
to provide `consttime_memequal' as an ELF weak symbol aliasing
`_consttime_memequal'.
If a library routine is internal to libc, it is defined as an ELF
global symbol with an underscore prefix. Its name is declared in the
appropriate internal header file.
=> Example: For the internal library routine _initdir, used by the
implementations of opendir and rewinddir, libc defines a global
symbol `_initdir'. The name `_initdir' is declared normally in
src/lib/libc/gen/dirent_private.h, and defined normally in
src/lib/libc/gen/initdir.c.
If the signature or semantics of a library routine foo changed in (for
example) NetBSD 6.0, then libc provides
(1) an ELF global symbol `_foo' implementing its old signature,
(2) an ELF weak symbol `foo' aliasing `_foo', and
(3) an ELF global symbol `__foo50' implementing its new signature (yes,
`__foo50', not `__foo60').
The name foo is declared in the appropriate header file, under any
relevant feature macros, with a __RENAME directive so that for calls to
foo, the compiler will generate relocations for __foo50. Old programs,
compiled with the old signature, will continue to use the old symbol.
=> Example: In NetBSD 5.0, time_t was int32_t on every machine. In
NetBSD 6.0 and onward, time_t is int64_t on every machine.
Consequently, the signature of time(3), written as
time_t time(time_t *);
changed in NetBSD 6.0 from being effectively
int32_t time(int32_t *);
to being effectively
int64_t time(int64_t *);
Thus, libc provides
(1) the ELF global symbol `_time' implementing the old signature,
(2) the ELF weak symbol `time' aliasing `_time', and
(3) the ELF global symbol `__time50' implementing the new signature.
The header file <time.h> (src/include/time.h) declares
time_t time(time_t *) __RENAME(__time50);
so that compiling C programs that call time will yield objects that
use the __time50 symbol from libc. However, old programs that were
compiled against the 32-bit declaration will continue to use the
32-bit symbol from libc.
The header file "namespace.h" (src/lib/libc/include/namespace.h)
defines `time' as a macro expanding to `_time'.
The source file src/lib/libc/gen/time.c includes "namespace.h" and
<time.h> and defines `time' normally. The declaration of `time' in
<time.h> is replaced after macro expansion by a declaration of
`_time', and the definition in time.c is replaced by a definition of
`_time'. But the __RENAME directive causes the resulting ELF global
symbol to be `__time50'.
The header file <compat/include/time.h>
(src/lib/libc/compat/include/time.h) declares
int32_t time(int32_t *);
The source file src/lib/libc/compat/gen/compat_time.c includes
"namespace.h", <compat/include/time.h>, and <time.h>, but suppresses
the normal declaration of `time' in <time.h> by defining
__LIBC12_SOURCE__. Then compat_time.c defines `time' normally.
Again, the name is replaced after macro expansion by `_time', but
since there is no __RENAME directive in <compat/include/time.h>, the
resulting ELF global symbol is `_time'.
Finally, alongside the definition in compat_time.c is
__weak_alias(time,_time)
to provide `time' as an ELF weak symbol aliasing `_time'.
The net effect is that NetBSD 6's libc provides the same definitions
as NetBSD 5's libc for the symbols `time' and `_time', so that old
programs that were compiled in NetBSD 5 will continue to work with
NetBSD 6's libc. But programs compiled in NetBSD 6 will have 64-bit
time_t.
6011d36bd6