Annotation of src/lib/libc/README, Revision 1.5
1.5 ! riastrad 1: $NetBSD: README,v 1.4 2015/07/11 14:29:50 riastradh Exp $
1.1 riastrad 2:
3: libc: The C library.
4:
5: * ELF symbols and source names
6:
7: libc contains symbols for:
8:
9: (a) standard library routines in C and POSIX,
10: (b) published NetBSD-specific nonstandard extensions,
1.4 riastrad 11: (c) internal symbols, and
12: (d) old versions of any published library routines.
13:
14: ** Standard library routines
1.1 riastrad 15:
16: If a library routine is standard and its signature has never changed,
1.5 ! riastrad 17: it is provided as an ELF global symbol. Its name is declared normally
1.1 riastrad 18: in the appropriate header file.
19:
1.5 ! riastrad 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: ...
1.1 riastrad 43:
1.4 riastrad 44: ** NetBSD-specific nonstandard extensions
45:
1.1 riastrad 46: If a library routine is nonstandard but published and its signature has
1.5 ! riastrad 47: never changed, it is provided as an ELF weak symbol aliasing an ELF
1.1 riastrad 48: global symbol of the same name with an underscore prefix.
49:
50: The name is declared normally in the appropriate header file, provided
51: that the relevant feature macro, such as _NETBSD_SOURCE, is defined.
52:
53: Within libc, the name is defined in "namespace.h"
54: (src/lib/libc/include/namespace.h) as a macro expanding to the
1.5 ! riastrad 55: underscored name, which is included before the relevant header file, so
! 56: that
! 57:
! 58: (a) the definition in a .c file will define the underscored ELF global
! 59: symbol, and
! 60:
! 61: (b) the declaration in the standard header file will match the
! 62: definition in the .c file.
1.1 riastrad 63:
64: Alongside the definition in the .c file is a __weak_alias directive to
65: create the ELF weak symbol alias.
66:
1.5 ! riastrad 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':
1.1 riastrad 85:
1.5 ! riastrad 86: #define consttime_memequal _consttime_memequal
1.3 riastrad 87:
88: The source file src/common/lib/libc/string/consttime_memequal.c
89: includes "namespace.h" and <string.h>, and defines
1.5 ! riastrad 90: `consttime_memequal' normally:
1.1 riastrad 91:
1.5 ! riastrad 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.
1.1 riastrad 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:
1.4 riastrad 106: ** Internal symbols
107:
1.1 riastrad 108: If a library routine is internal to libc, it is defined as an ELF
1.2 riastrad 109: global symbol with an underscore prefix. Its name is declared in the
110: appropriate internal header file.
1.1 riastrad 111:
1.5 ! riastrad 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: ...
1.1 riastrad 132:
1.4 riastrad 133: ** Old versions of library routines
134:
1.1 riastrad 135: If the signature or semantics of a library routine foo changed in (for
136: example) 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:
143: The name foo is declared in the appropriate header file, under any
144: relevant feature macros, with a __RENAME directive so that for calls to
145: foo, the compiler will generate relocations for __foo50. Old programs,
146: compiled 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:
1.5 ! riastrad 152: time_t time(time_t *);
1.1 riastrad 153:
1.5 ! riastrad 154: was effectively
1.1 riastrad 155:
1.5 ! riastrad 156: int32_t time(int32_t *);
1.1 riastrad 157:
1.5 ! riastrad 158: before NetBSD 6.0. In NetBSD 6.0, it changed to be effectively
1.1 riastrad 159:
160: int64_t time(int64_t *);
161:
1.5 ! riastrad 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:
1.1 riastrad 168:
1.5 ! riastrad 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.)
1.1 riastrad 176:
1.2 riastrad 177: The header file <time.h> (src/include/time.h) declares
1.1 riastrad 178:
1.5 ! riastrad 179: time_t time(time_t *) __RENAME(__time50);
1.1 riastrad 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.
1.2 riastrad 185:
186: The header file "namespace.h" (src/lib/libc/include/namespace.h)
1.5 ! riastrad 187: defines `time' as a macro expanding to `_time':
! 188:
! 189: #define time _time
1.2 riastrad 190:
191: The source file src/lib/libc/gen/time.c includes "namespace.h" and
1.5 ! riastrad 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'.
1.2 riastrad 203:
204: The header file <compat/include/time.h>
205: (src/lib/libc/compat/include/time.h) declares
206:
1.5 ! riastrad 207: int32_t time(int32_t *);
1.2 riastrad 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
1.5 ! riastrad 212: __LIBC12_SOURCE__. Instead, <compat/include/time.h>
! 213: (src/lib/libc/compat/include/time.h) declares `time' with the
! 214: effective old signature:
! 215:
! 216: int32_t time(int32_t *);
! 217:
! 218: Then compat_time.c defines `time' normally:
! 219:
! 220: time_t
! 221: time(time_t *t)
! 222: {
! 223: ...
! 224:
! 225: Again, macro expansion replaces `time' by `_time', but since there
! 226: is no __RENAME directive in <compat/include/time.h>, the resulting
! 227: ELF global symbol is `_time'.
1.2 riastrad 228:
229: Finally, alongside the definition in compat_time.c is
230:
231: __weak_alias(time,_time)
232:
1.5 ! riastrad 233: to define `time' as an ELF weak symbol aliasing `_time'.
1.2 riastrad 234:
235: The net effect is that NetBSD 6's libc provides the same definitions
236: as NetBSD 5's libc for the symbols `time' and `_time', so that old
237: programs that were compiled in NetBSD 5 will continue to work with
238: NetBSD 6's libc. But programs compiled in NetBSD 6 will have 64-bit
239: time_t.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc