1 $NetBSD: README,v 1.4 2015/07/11 14:29:50 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 defined as an ELF global symbol. Its name is declared normally 18in the appropriate header file. 19 20=> Example: libc defines global symbols `malloc' and `free' for the 21 standard C memory allocator routines. The names `malloc' and `free' 22 are declared normally in <stdlib.h> (src/include/stdlib.h). 23 24** NetBSD-specific nonstandard extensions 25 26If a library routine is nonstandard but published and its signature has 27never changed, it is defined as an ELF weak symbol aliasing an ELF 28global symbol of the same name with an underscore prefix. 29 30The name is declared normally in the appropriate header file, provided 31that the relevant feature macro, such as _NETBSD_SOURCE, is defined. 32 33Within libc, the name is defined in "namespace.h" 34(src/lib/libc/include/namespace.h) as a macro expanding to the 35underscored name, so that the definition in a .c file will define the 36underscored ELF global symbol. 37 38Alongside the definition in the .c file is a __weak_alias directive to 39create the ELF weak symbol alias. 40 41=> Example: For the nonstandard extension consttime_memequal, libc 42 defines a weak symbol `consttime_memequal' aliasing a global symbol 43 `_consttime_memequal'. 44 45 The header file <string.h> (src/include/string.h) declares 46 `consttime_memequal' normally, if the caller defines _NETBSD_SOURCE. 47 48 The header file "namespace.h" (src/lib/libc/include/namespace.h) 49 defines `consttime_memequal' as a macro expanding to 50 `_consttime_memequal'. 51 52 The source file src/common/lib/libc/string/consttime_memequal.c 53 includes "namespace.h" and <string.h>, and defines 54 `consttime_memequal' normally, which, after macro expansion, causes 55 the ELF global symbol `_consttime_memequal' to be defined. 56 57 Alongside the definition is 58 59 __weak_alias(consttime_memequal,_consttime_memequal) 60 61 to provide `consttime_memequal' as an ELF weak symbol aliasing 62 `_consttime_memequal'. 63 64** Internal symbols 65 66If a library routine is internal to libc, it is defined as an ELF 67global symbol with an underscore prefix. Its name is declared in the 68appropriate internal header file. 69 70=> Example: For the internal library routine _initdir, used by the 71 implementations of opendir and rewinddir, libc defines a global 72 symbol `_initdir'. The name `_initdir' is declared normally in 73 src/lib/libc/gen/dirent_private.h, and defined normally in 74 src/lib/libc/gen/initdir.c. 75 76** Old versions of library routines 77 78If the signature or semantics of a library routine foo changed in (for 79example) NetBSD 6.0, then libc provides 80 81(1) an ELF global symbol `_foo' implementing its old signature, 82(2) an ELF weak symbol `foo' aliasing `_foo', and 83(3) an ELF global symbol `__foo50' implementing its new signature (yes, 84 `__foo50', not `__foo60'). 85 86The name foo is declared in the appropriate header file, under any 87relevant feature macros, with a __RENAME directive so that for calls to 88foo, the compiler will generate relocations for __foo50. Old programs, 89compiled with the old signature, will continue to use the old symbol. 90 91=> Example: In NetBSD 5.0, time_t was int32_t on every machine. In 92 NetBSD 6.0 and onward, time_t is int64_t on every machine. 93 Consequently, the signature of time(3), written as 94 95 time_t time(time_t *); 96 97 changed in NetBSD 6.0 from being effectively 98 99 int32_t time(int32_t *); 100 101 to being effectively 102 103 int64_t time(int64_t *); 104 105 Thus, libc provides 106 107 (1) the ELF global symbol `_time' implementing the old signature, 108 (2) the ELF weak symbol `time' aliasing `_time', and 109 (3) the ELF global symbol `__time50' implementing the new signature. 110 111 The header file <time.h> (src/include/time.h) declares 112 113 time_t time(time_t *) __RENAME(__time50); 114 115 so that compiling C programs that call time will yield objects that 116 use the __time50 symbol from libc. However, old programs that were 117 compiled against the 32-bit declaration will continue to use the 118 32-bit symbol from libc. 119 120 The header file "namespace.h" (src/lib/libc/include/namespace.h) 121 defines `time' as a macro expanding to `_time'. 122 123 The source file src/lib/libc/gen/time.c includes "namespace.h" and 124 <time.h> and defines `time' normally. The declaration of `time' in 125 <time.h> is replaced after macro expansion by a declaration of 126 `_time', and the definition in time.c is replaced by a definition of 127 `_time'. But the __RENAME directive causes the resulting ELF global 128 symbol to be `__time50'. 129 130 The header file <compat/include/time.h> 131 (src/lib/libc/compat/include/time.h) declares 132 133 int32_t time(int32_t *); 134 135 The source file src/lib/libc/compat/gen/compat_time.c includes 136 "namespace.h", <compat/include/time.h>, and <time.h>, but suppresses 137 the normal declaration of `time' in <time.h> by defining 138 __LIBC12_SOURCE__. Then compat_time.c defines `time' normally. 139 Again, the name is replaced after macro expansion by `_time', but 140 since there is no __RENAME directive in <compat/include/time.h>, the 141 resulting ELF global symbol is `_time'. 142 143 Finally, alongside the definition in compat_time.c is 144 145 __weak_alias(time,_time) 146 147 to provide `time' as an ELF weak symbol aliasing `_time'. 148 149 The net effect is that NetBSD 6's libc provides the same definitions 150 as NetBSD 5's libc for the symbols `time' and `_time', so that old 151 programs that were compiled in NetBSD 5 will continue to work with 152 NetBSD 6's libc. But programs compiled in NetBSD 6 will have 64-bit 153 time_t. 154