README revision 1.1 
1	$NetBSD: README,v 1.1 2015/03/20 12:57:48 riastradh Exp $
2
3libc: The C library.
4
5* ELF symbols and source names
6
7libc contains symbols for:
8
9(a) standard library routines in C and POSIX,
10(b) published NetBSD-specific nonstandard extensions,
11(c) old versions of library routines, and
12(d) internal symbols.
13
14If a library routine is standard and its signature has never changed,
15it is defined as an ELF global symbol.  Its name is declared normally
16in the appropriate header file.
17
18=> Example: libc defines global symbols `malloc' and `free' for the
19   standard C memory allocator routines.  The names `malloc' and `free'
20   are declared normally in <stdlib.h> (src/include/stdlib.h).
21
22If a library routine is nonstandard but published and its signature has
23never changed, it is defined as an ELF weak symbol aliasing an ELF
24global symbol of the same name with an underscore prefix.
25
26The name is declared normally in the appropriate header file, provided
27that the relevant feature macro, such as _NETBSD_SOURCE, is defined.
28
29Within libc, the name is defined in "namespace.h"
30(src/lib/libc/include/namespace.h) as a macro expanding to the
31underscored name, so that the definition in a .c file will define the
32underscored ELF global symbol.
33
34Alongside the definition in the .c file is a __weak_alias directive to
35create the ELF weak symbol alias.
36
37=> Example: For the nonstandard extension consttime_memequal, libc
38   defines a weak symbol `consttime_memequal' aliasing a global symbol
39   `_consttime_memequal'.
40
41   The name `consttime_memequal' is declared in <string.h>
42   (src/include/string.h) if the caller defines _NETBSD_SOURCE.
43
44   The name `consttime_memequal' is defined as a macro in "namespace.h"
45   (src/lib/libc/include/namespace.h) expanding to
46   `_consttime_memequal'.  The source name `consttime_memequal' is
47   defined in src/common/lib/libc/string/consttime_memequal.c, causing
48   the ELF global symbol `_consttime_memequal' to be defined, after
49   macro expansion.
50
51   Alongside the definition is
52
53	__weak_alias(consttime_memequal,_consttime_memequal)
54
55   to provide `consttime_memequal' as an ELF weak symbol aliasing
56   `_consttime_memequal'.
57
58If a library routine is internal to libc, it is defined as an ELF
59global symbol with an underscore prefix.
60
61Its name is declared in the appropriate internal header file.
62
63=> Example: For the internal library routine _initdir, used by the
64   implementations of opendir and rewinddir, libc defines a global
65   symbol `_initdir'.
66
67   The name `_initdir' is declared normally in
68   src/lib/libc/gen/dirent_private.h.
69
70If the signature or semantics of a library routine foo changed in (for
71example) NetBSD 6.0, then libc provides
72
73(1) an ELF global symbol `_foo' implementing its old signature,
74(2) an ELF weak symbol `foo' aliasing `_foo', and
75(3) an ELF global symbol `__foo50' implementing its new signature (yes,
76    `__foo50', not `__foo60').
77
78The name foo is declared in the appropriate header file, under any
79relevant feature macros, with a __RENAME directive so that for calls to
80foo, the compiler will generate relocations for __foo50.  Old programs,
81compiled with the old signature, will continue to use the old symbol.
82
83=> Example: In NetBSD 5.0, time_t was int32_t on every machine.  In
84   NetBSD 6.0 and onward, time_t is int64_t on every machine.
85   Consequently, the signature of time(3), written as
86
87	time_t time(time_t *);
88
89   changed in NetBSD 6.0 from being effectively
90
91	int32_t time(int32_t *);
92
93   to being effectively
94
95	int64_t time(int64_t *);
96
97   Thus, libc provides
98
99   (1) the ELF global symbol `_time' implementing the old signature,
100   (2) the ELF weak symbol `time' aliasing `_time', and
101   (3) the ELF global symbol `__time50' implementing the new signature.
102
103   The header file <time.h> declares
104
105	time_t time(time_t *) __RENAME(__time50);
106
107   so that compiling C programs that call time will yield objects that
108   use the __time50 symbol from libc.  However, old programs that were
109   compiled against the 32-bit declaration will continue to use the
110   32-bit symbol from libc.
111