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