Module Name: src
Committed By: riastradh
Date: Sat Jul 11 15:23:57 UTC 2015
Modified Files:
src/lib/libc: README
Log Message:
Elaborate documentation of libc symbol rules.
- Say `provide' for what libc does to a symbol.
- Say `define' for what source code does to a symbol or macro.
- Quote code fragments rather than just talking about them.
- Qualify ELF symbols as such.
- List provided ELF symbols in tables rather than in prose.
To generate a diff of this commit:
cvs rdiff -u -r1.4 -r1.5 src/lib/libc/README
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/README
diff -u src/lib/libc/README:1.4 src/lib/libc/README:1.5
--- src/lib/libc/README:1.4 Sat Jul 11 14:29:50 2015
+++ src/lib/libc/README Sat Jul 11 15:23:57 2015
@@ -1,4 +1,4 @@
- $NetBSD: README,v 1.4 2015/07/11 14:29:50 riastradh Exp $
+ $NetBSD: README,v 1.5 2015/07/11 15:23:57 riastradh Exp $
libc: The C library.
@@ -14,17 +14,37 @@ libc contains symbols for:
** Standard library routines
If a library routine is standard and its signature has never changed,
-it is defined as an ELF global symbol. Its name is declared normally
+it is provided as an ELF global symbol. Its name is declared normally
in the appropriate header file.
-=> Example: libc defines global symbols `malloc' and `free' for the
- standard C memory allocator routines. The names `malloc' and `free'
- are declared normally in <stdlib.h> (src/include/stdlib.h).
+=> Example: The names `malloc' and `free' are declared normally in
+ <stdlib.h> (src/include/stdlib.h):
+
+ void *malloc(size_t);
+ void free(void *);
+
+ libc provides the following ELF symbols:
+
+ malloc global
+ free global
+
+ In the implementation of libc, malloc and free are defined normally
+ in src/lib/libc/stdlib/jemalloc.c:
+
+ void *
+ malloc(size_t size)
+ {
+ ...
+
+ void
+ free(void *ptr)
+ {
+ ...
** NetBSD-specific nonstandard extensions
If a library routine is nonstandard but published and its signature has
-never changed, it is defined as an ELF weak symbol aliasing an ELF
+never changed, it is provided as an ELF weak symbol aliasing an ELF
global symbol of the same name with an underscore prefix.
The name is declared normally in the appropriate header file, provided
@@ -32,28 +52,50 @@ that the relevant feature macro, such as
Within libc, the name is defined in "namespace.h"
(src/lib/libc/include/namespace.h) as a macro expanding to the
-underscored name, so that the definition in a .c file will define the
-underscored ELF global symbol.
+underscored name, which is included before the relevant header file, so
+that
+
+(a) the definition in a .c file will define the underscored ELF global
+symbol, and
+
+(b) the declaration in the standard header file will match the
+definition in the .c file.
Alongside the definition in the .c file is a __weak_alias directive to
create the ELF weak symbol alias.
-=> Example: For the nonstandard extension consttime_memequal, libc
- defines a weak symbol `consttime_memequal' aliasing a global symbol
- `_consttime_memequal'.
-
- The header file <string.h> (src/include/string.h) declares
- `consttime_memequal' normally, if the caller defines _NETBSD_SOURCE.
+=> Example: For the nonstandard extension consttime_memequal, the
+ header file <string.h> (src/include/string.h) declares
+ `consttime_memequal' normally, if the caller defines _NETBSD_SOURCE:
+
+ #if defined(_NETBSD_SOURCE)
+ ...
+ int consttime_memequal(const void *, const void *, size_t);
+ ...
+ #endif /* _NETBSD_SOURCE */
+
+ libc provides the following ELF symbols:
+
+ _consttime_memequal global
+ consttime_memequal weak alias for _consttime_memequal
+
+ In the implementation of libc, the header file "namespace.h"
+ (src/lib/libc/include/namespace.h) defines `consttime_memequal' as a
+ macro expanding to `_consttime_memequal':
- The header file "namespace.h" (src/lib/libc/include/namespace.h)
- defines `consttime_memequal' as a macro expanding to
- `_consttime_memequal'.
+ #define consttime_memequal _consttime_memequal
The source file src/common/lib/libc/string/consttime_memequal.c
includes "namespace.h" and <string.h>, and defines
- `consttime_memequal' normally, which, after macro expansion, causes
- the ELF global symbol `_consttime_memequal' to be defined.
+ `consttime_memequal' normally:
+ int
+ consttime_memequal(const void *b1, const void *b2, size_t len)
+ {
+ ...
+
+ Macro expansion replaces `consttime_memequal' by
+ `_consttime_memequal', which is the ELF global symbol this defines.
Alongside the definition is
__weak_alias(consttime_memequal,_consttime_memequal)
@@ -67,11 +109,26 @@ If a library routine is internal to libc
global symbol with an underscore prefix. Its name is declared in the
appropriate internal header file.
-=> Example: For the internal library routine _initdir, used by the
- implementations of opendir and rewinddir, libc defines a global
- symbol `_initdir'. The name `_initdir' is declared normally in
- src/lib/libc/gen/dirent_private.h, and defined normally in
- src/lib/libc/gen/initdir.c.
+=> Example: The implementations of opendir and rewinddir use a common
+ subroutine _initdir, which is not part of the libc API or ABI -- it
+ is just an internal subroutine.
+
+ libc provides the following ELF symbols:
+
+ _initdir global
+
+ The name `_initdir' is declared normally in
+ src/lib/libc/gen/dirent_private.h:
+
+ int _initdir(DIR *, int, const char *);
+
+ The name `_initdir' is defined normally in
+ src/lib/libc/gen/initdir.c:
+
+ int
+ _initdir(DIR *dirp, int fd, const char *name)
+ {
+ ...
** Old versions of library routines
@@ -92,25 +149,34 @@ compiled with the old signature, will co
NetBSD 6.0 and onward, time_t is int64_t on every machine.
Consequently, the signature of time(3), written as
- time_t time(time_t *);
+ time_t time(time_t *);
- changed in NetBSD 6.0 from being effectively
+ was effectively
- int32_t time(int32_t *);
+ int32_t time(int32_t *);
- to being effectively
+ before NetBSD 6.0. In NetBSD 6.0, it changed to be effectively
int64_t time(int64_t *);
- Thus, libc provides
+ Before NetBSD 6.0, libc provided the following libc symbols:
+
+ _time global (implementing the old signature)
+ time weak alias for _time
+
+ In NetBSD 6.0 and later, libc provides the following ELF symbols:
- (1) the ELF global symbol `_time' implementing the old signature,
- (2) the ELF weak symbol `time' aliasing `_time', and
- (3) the ELF global symbol `__time50' implementing the new signature.
+ _time global (implementing the old signature)
+ time weak alias for _time
+ __time50 global (implementing the new signature)
+
+ (Note that the only change is to add __time50, so that existing
+ programs linked against old versions of libc will see the same
+ semantics for the symbols that were already there.)
The header file <time.h> (src/include/time.h) declares
- time_t time(time_t *) __RENAME(__time50);
+ time_t time(time_t *) __RENAME(__time50);
so that compiling C programs that call time will yield objects that
use the __time50 symbol from libc. However, old programs that were
@@ -118,33 +184,53 @@ compiled with the old signature, will co
32-bit symbol from libc.
The header file "namespace.h" (src/lib/libc/include/namespace.h)
- defines `time' as a macro expanding to `_time'.
+ defines `time' as a macro expanding to `_time':
+
+ #define time _time
The source file src/lib/libc/gen/time.c includes "namespace.h" and
- <time.h> and defines `time' normally. The declaration of `time' in
- <time.h> is replaced after macro expansion by a declaration of
- `_time', and the definition in time.c is replaced by a definition of
- `_time'. But the __RENAME directive causes the resulting ELF global
- symbol to be `__time50'.
+ <time.h> and defines `time' normally:
+
+ time_t
+ time(time_t *t)
+ {
+ ...
+
+ Macro expansion replaces `time' by `_time', but the
+ `__RENAME(__time50)' directive on the declaration <time.h> (to which
+ the "namespace.h" macro expansion also applies) means the ELF global
+ symbol defined here is actually `__time50'.
The header file <compat/include/time.h>
(src/lib/libc/compat/include/time.h) declares
- int32_t time(int32_t *);
+ int32_t time(int32_t *);
The source file src/lib/libc/compat/gen/compat_time.c includes
"namespace.h", <compat/include/time.h>, and <time.h>, but suppresses
the normal declaration of `time' in <time.h> by defining
- __LIBC12_SOURCE__. Then compat_time.c defines `time' normally.
- Again, the name is replaced after macro expansion by `_time', but
- since there is no __RENAME directive in <compat/include/time.h>, the
- resulting ELF global symbol is `_time'.
+ __LIBC12_SOURCE__. Instead, <compat/include/time.h>
+ (src/lib/libc/compat/include/time.h) declares `time' with the
+ effective old signature:
+
+ int32_t time(int32_t *);
+
+ Then compat_time.c defines `time' normally:
+
+ time_t
+ time(time_t *t)
+ {
+ ...
+
+ Again, macro expansion replaces `time' by `_time', but since there
+ is no __RENAME directive in <compat/include/time.h>, the resulting
+ ELF global symbol is `_time'.
Finally, alongside the definition in compat_time.c is
__weak_alias(time,_time)
- to provide `time' as an ELF weak symbol aliasing `_time'.
+ to define `time' as an ELF weak symbol aliasing `_time'.
The net effect is that NetBSD 6's libc provides the same definitions
as NetBSD 5's libc for the symbols `time' and `_time', so that old
