1          $NetBSD: README,v 1.7 2017/02/08 13:31:36 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) internal symbols, and
12(d) old versions of any published library routines.
13
14** Standard library routines
15
16If a library routine is standard and its signature has never changed,
17it is provided as an ELF global symbol.  Its name is declared normally
18in the appropriate header file.
19
20=> Example: The names `malloc' and `free' are declared normally in
21   <stdlib.h> (src/include/stdlib.h):
22
23          void      *malloc(size_t);
24          void       free(void *);
25
26   libc provides the following ELF symbols:
27
28          malloc              global
29          free                global
30
31   In the implementation of libc, malloc and free are defined normally
32   in src/lib/libc/stdlib/jemalloc.c:
33
34          void *
35          malloc(size_t size)
36          {
37          ...
38
39          void
40          free(void *ptr)
41          {
42          ...
43
44** NetBSD-specific nonstandard extensions
45
46If a library routine is nonstandard but published and its signature has
47never changed, it is provided as an ELF weak symbol aliasing an ELF
48global symbol of the same name with an underscore prefix.
49
50The name is declared normally in the appropriate header file, provided
51that the relevant feature macro, such as _NETBSD_SOURCE, is defined.
52
53Within libc, the name is defined in "namespace.h"
54(src/lib/libc/include/namespace.h) as a macro expanding to the
55underscored name, which is included before the relevant header file, so
56that
57
58(a) the definition in a .c file will define the underscored ELF global
59symbol, and
60
61(b) the declaration in the standard header file will match the
62definition in the .c file.
63
64Alongside the definition in the .c file is a __weak_alias directive to
65create the ELF weak symbol alias.
66
67=> Example: For the nonstandard extension consttime_memequal, the
68   header file <string.h> (src/include/string.h) declares
69   `consttime_memequal' normally, if the caller defines _NETBSD_SOURCE:
70
71          #if defined(_NETBSD_SOURCE)
72          ...
73          int       consttime_memequal(const void *, const void *, size_t);
74          ...
75          #endif    /* _NETBSD_SOURCE */
76
77   libc provides the following ELF symbols:
78
79          _consttime_memequal global
80          consttime_memequal  weak alias for      _consttime_memequal
81
82   In the implementation of libc, the header file "namespace.h"
83   (src/lib/libc/include/namespace.h) defines `consttime_memequal' as a
84   macro expanding to `_consttime_memequal':
85
86          #define   consttime_memequal  _consttime_memequal
87
88   The source file src/common/lib/libc/string/consttime_memequal.c
89   includes "namespace.h" and <string.h>, and defines
90   `consttime_memequal' normally:
91
92          int
93          consttime_memequal(const void *b1, const void *b2, size_t len)
94          {
95          ...
96
97   Macro expansion replaces `consttime_memequal' by
98   `_consttime_memequal', which is the ELF global symbol this defines.
99   Alongside the definition is
100
101          __weak_alias(consttime_memequal,_consttime_memequal)
102
103   to provide `consttime_memequal' as an ELF weak symbol aliasing
104   `_consttime_memequal'.
105
106** Internal symbols
107
108If a library routine is internal to libc, it is defined as an ELF
109global symbol with an underscore prefix.  Its name is declared in the
110appropriate internal header file.
111
112=> Example: The implementations of opendir and rewinddir use a common
113   subroutine _initdir, which is not part of the libc API or ABI -- it
114   is just an internal subroutine.
115
116   libc provides the following ELF symbols:
117
118          _initdir  global
119
120   The name `_initdir' is declared normally in
121   src/lib/libc/gen/dirent_private.h:
122
123          int       _initdir(DIR *, int, const char *);
124
125   The name `_initdir' is defined normally in
126   src/lib/libc/gen/initdir.c:
127
128          int
129          _initdir(DIR *dirp, int fd, const char *name)
130          {
131          ...
132
133** Old versions of library routines
134
135If the signature or semantics of a library routine foo changed in (for
136example) NetBSD 6.0, then libc provides
137
138(1) an ELF global symbol `_foo' implementing its old signature,
139(2) an ELF weak symbol `foo' aliasing `_foo', and
140(3) an ELF global symbol `__foo50' implementing its new signature (yes,
141    `__foo50', not `__foo60').
142
143The name foo is declared in the appropriate header file, under any
144relevant feature macros, with a __RENAME directive so that for calls to
145foo, the compiler will generate relocations for __foo50.  Old programs,
146compiled with the old signature, will continue to use the old symbol.
147
148=> Example: In NetBSD 5.0, time_t was int32_t on every machine.  In
149   NetBSD 6.0 and onward, time_t is int64_t on every machine.
150   Consequently, the signature of time(3), written as
151
152          time_t    time(time_t *);
153
154   was effectively
155
156          int32_t   time(int32_t *);
157
158   before NetBSD 6.0.  In NetBSD 6.0, it changed to be effectively
159
160          int64_t time(int64_t *);
161
162   Before NetBSD 6.0, libc provided the following libc symbols:
163
164          _time               global (implementing the old signature)
165          time                weak alias for _time
166
167   In NetBSD 6.0 and later, libc provides the following ELF symbols:
168
169          _time               global (implementing the old signature)
170          time                weak alias for _time
171          __time50  global (implementing the new signature)
172
173   (Note that the only change is to add __time50, so that existing
174   programs linked against old versions of libc will see the same
175   semantics for the symbols that were already there.)
176
177   The header file <time.h> (src/include/time.h) declares
178
179          time_t    time(time_t *) __RENAME(__time50);
180
181   so that compiling C programs that call time will yield objects that
182   use the __time50 symbol from libc.  However, old programs that were
183   compiled against the 32-bit declaration will continue to use the
184   32-bit symbol from libc.
185
186   The header file "namespace.h" (src/lib/libc/include/namespace.h)
187   defines `time' as a macro expanding to `_time':
188
189          #define   time      _time
190
191   The source file src/lib/libc/gen/time.c includes "namespace.h" and
192   <time.h> and defines `time' normally:
193
194          time_t
195          time(time_t *t)
196          {
197          ...
198
199   Macro expansion replaces `time' by `_time', but the
200   `__RENAME(__time50)' directive on the declaration <time.h> (to which
201   the "namespace.h" macro expansion also applies) means the ELF global
202   symbol defined here is actually `__time50'.
203
204   The header file <compat/include/time.h>
205   (src/lib/libc/compat/include/time.h) declares
206
207          int32_t   time(int32_t *);
208
209   The source file src/lib/libc/compat/gen/compat_time.c includes
210   "namespace.h", <compat/include/time.h>, and <time.h>, but suppresses
211   the normal declaration of `time' in <time.h> by defining
212   __LIBC12_SOURCE__ and thus gets it from <compat/include/time.h>
213   instead.  Then compat_time.c defines `time' normally:
214
215          int32_t
216          time(int32_t *t)
217          {
218          ...
219
220   Again, macro expansion replaces `time' by `_time', but since there
221   is no __RENAME directive in <compat/include/time.h>, the resulting
222   ELF global symbol is `_time'.  (Actually, compat_time.c just has
223   `#define time_t int32_t' and `#include "gen/time.c"' to get the same
224   text of the definition of time.  The above definition is what we get
225   effectively by substituting int32_t for the type time_t.)
226
227   Finally, alongside the definition in compat_time.c is
228
229          __weak_alias(time,_time)
230
231   to define `time' as an ELF weak symbol aliasing `_time'.
232
233   The net effect is that NetBSD 6's libc provides the same definitions
234   as NetBSD 5's libc for the symbols `time' and `_time', so that old
235   programs that were compiled in NetBSD 5 will continue to work with
236   NetBSD 6's libc.  But programs compiled in NetBSD 6 will have 64-bit
237   time_t.
238