Annotation of src/lib/libc/README, Revision 1.3
1.3 ! riastrad 1: $NetBSD: README,v 1.2 2015/03/20 13:26:51 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,
11: (c) old versions of library routines, and
12: (d) internal symbols.
13:
14: If a library routine is standard and its signature has never changed,
15: it is defined as an ELF global symbol. Its name is declared normally
16: in 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:
22: If a library routine is nonstandard but published and its signature has
23: never changed, it is defined as an ELF weak symbol aliasing an ELF
24: global symbol of the same name with an underscore prefix.
25:
26: The name is declared normally in the appropriate header file, provided
27: that the relevant feature macro, such as _NETBSD_SOURCE, is defined.
28:
29: Within libc, the name is defined in "namespace.h"
30: (src/lib/libc/include/namespace.h) as a macro expanding to the
31: underscored name, so that the definition in a .c file will define the
32: underscored ELF global symbol.
33:
34: Alongside the definition in the .c file is a __weak_alias directive to
35: create 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:
1.3 ! riastrad 41: The header file <string.h> (src/include/string.h) declares
! 42: `consttime_memequal' normally, if the caller defines _NETBSD_SOURCE.
1.1 riastrad 43:
1.3 ! riastrad 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.
1.1 riastrad 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:
60: If a library routine is internal to libc, it is defined as an ELF
1.2 riastrad 61: global symbol with an underscore prefix. Its name is declared in the
62: appropriate internal header file.
1.1 riastrad 63:
64: => Example: For the internal library routine _initdir, used by the
65: implementations of opendir and rewinddir, libc defines a global
1.2 riastrad 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.
1.1 riastrad 69:
70: If the signature or semantics of a library routine foo changed in (for
71: example) 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:
78: The name foo is declared in the appropriate header file, under any
79: relevant feature macros, with a __RENAME directive so that for calls to
80: foo, the compiler will generate relocations for __foo50. Old programs,
81: compiled 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:
1.2 riastrad 103: The header file <time.h> (src/include/time.h) declares
1.1 riastrad 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.
1.2 riastrad 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.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc