README revision 1.3
1 $NetBSD: README,v 1.3 2015/03/20 14:10:40 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 header file <string.h> (src/include/string.h) declares 42 `consttime_memequal' normally, if the caller defines _NETBSD_SOURCE. 43 44 The header file "namespace.h" (src/lib/libc/include/namespace.h) 45 defines `consttime_memequal' as a macro expanding to 46 `_consttime_memequal'. 47 48 The source file src/common/lib/libc/string/consttime_memequal.c 49 includes "namespace.h" and <string.h>, and defines 50 `consttime_memequal' normally, which, after macro expansion, causes 51 the ELF global symbol `_consttime_memequal' to be defined. 52 53 Alongside the definition is 54 55 __weak_alias(consttime_memequal,_consttime_memequal) 56 57 to provide `consttime_memequal' as an ELF weak symbol aliasing 58 `_consttime_memequal'. 59 60If a library routine is internal to libc, it is defined as an ELF 61global symbol with an underscore prefix. Its name is declared in the 62appropriate internal header file. 63 64=> Example: For the internal library routine _initdir, used by the 65 implementations of opendir and rewinddir, libc defines a global 66 symbol `_initdir'. The name `_initdir' is declared normally in 67 src/lib/libc/gen/dirent_private.h, and defined normally in 68 src/lib/libc/gen/initdir.c. 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> (src/include/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 112 The header file "namespace.h" (src/lib/libc/include/namespace.h) 113 defines `time' as a macro expanding to `_time'. 114 115 The source file src/lib/libc/gen/time.c includes "namespace.h" and 116 <time.h> and defines `time' normally. The declaration of `time' in 117 <time.h> is replaced after macro expansion by a declaration of 118 `_time', and the definition in time.c is replaced by a definition of 119 `_time'. But the __RENAME directive causes the resulting ELF global 120 symbol to be `__time50'. 121 122 The header file <compat/include/time.h> 123 (src/lib/libc/compat/include/time.h) declares 124 125 int32_t time(int32_t *); 126 127 The source file src/lib/libc/compat/gen/compat_time.c includes 128 "namespace.h", <compat/include/time.h>, and <time.h>, but suppresses 129 the normal declaration of `time' in <time.h> by defining 130 __LIBC12_SOURCE__. Then compat_time.c defines `time' normally. 131 Again, the name is replaced after macro expansion by `_time', but 132 since there is no __RENAME directive in <compat/include/time.h>, the 133 resulting ELF global symbol is `_time'. 134 135 Finally, alongside the definition in compat_time.c is 136 137 __weak_alias(time,_time) 138 139 to provide `time' as an ELF weak symbol aliasing `_time'. 140 141 The net effect is that NetBSD 6's libc provides the same definitions 142 as NetBSD 5's libc for the symbols `time' and `_time', so that old 143 programs that were compiled in NetBSD 5 will continue to work with 144 NetBSD 6's libc. But programs compiled in NetBSD 6 will have 64-bit 145 time_t. 146