lib/libc/README

   1         $NetBSD: README,v 1.5 2015/07/11 15:23:57 riastradh Exp $
   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,
  11 (c) internal symbols, and
  12 (d) old versions of any published library routines.
  13
  14 ** Standard library routines
  15
  16 If a library routine is standard and its signature has never changed,
  17 it is provided as an ELF global symbol.  Its name is declared normally
  18 in 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
  46 If a library routine is nonstandard but published and its signature has
  47 never changed, it is provided as an ELF weak symbol aliasing an ELF
  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
  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.
  63
  64 Alongside the definition in the .c file is a __weak_alias directive to
  65 create 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
 108 If a library routine is internal to libc, it is defined as an ELF
 109 global symbol with an underscore prefix.  Its name is declared in the
 110 appropriate 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
 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
 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__.  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'.
 228
 229    Finally, alongside the definition in compat_time.c is
 230
 231         __weak_alias(time,_time)
 232
 233    to define `time' as an ELF weak symbol aliasing `_time'.
 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.