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