[BACK]Return to README CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc

Annotation of src/lib/libc/README, Revision 1.7

1.7     ! riastrad    1:        $NetBSD: README,v 1.6 2017/01/12 00:38:25 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.7     ! riastrad  212:    __LIBC12_SOURCE__ and thus gets it from <compat/include/time.h>
        !           213:    instead.  Then compat_time.c defines `time' normally:
1.5       riastrad  214:
1.6       riastrad  215:        int32_t
                    216:        time(int32_t *t)
1.5       riastrad  217:        {
                    218:        ...
                    219:
                    220:    Again, macro expansion replaces `time' by `_time', but since there
                    221:    is no __RENAME directive in <compat/include/time.h>, the resulting
1.6       riastrad  222:    ELF global symbol is `_time'.  (Actually, compat_time.c just has
                    223:    `#define time_t int32_t' and `#include "gen/time.c"' to get the same
                    224:    text of the definition of time.  The above definition is what we get
                    225:    effectively by substituting int32_t for the type time_t.)
1.2       riastrad  226:
                    227:    Finally, alongside the definition in compat_time.c is
                    228:
                    229:        __weak_alias(time,_time)
                    230:
1.5       riastrad  231:    to define `time' as an ELF weak symbol aliasing `_time'.
1.2       riastrad  232:
                    233:    The net effect is that NetBSD 6's libc provides the same definitions
                    234:    as NetBSD 5's libc for the symbols `time' and `_time', so that old
                    235:    programs that were compiled in NetBSD 5 will continue to work with
                    236:    NetBSD 6's libc.  But programs compiled in NetBSD 6 will have 64-bit
                    237:    time_t.

CVSweb <webmaster@jp.NetBSD.org>