[src/trunk]: src/lib/libc Elaborate documentation of libc symbol rules.

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/561b6951eaec
branches:  trunk
changeset: 339306:561b6951eaec
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sat Jul 11 15:23:57 2015 +0000

description:
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.

diffstat:

 lib/libc/README |  174 +++++++++++++++++++++++++++++++++++++++++--------------
 1 files changed, 130 insertions(+), 44 deletions(-)

diffs (257 lines):

diff -r 884df2a0a0fa -r 561b6951eaec lib/libc/README
--- a/lib/libc/README   Sat Jul 11 14:29:50 2015 +0000
+++ b/lib/libc/README   Sat Jul 11 15:23:57 2015 +0000
@@ -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 @@
 ** 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 @@
 
 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'.
+=> 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 */
 
-   The header file <string.h> (src/include/string.h) declares
-   `consttime_memequal' normally, if the caller defines _NETBSD_SOURCE.
+   libc provides the following ELF symbols:
+
+       _consttime_memequal     global
+       consttime_memequal      weak alias for  _consttime_memequal
 
-   The header file "namespace.h" (src/lib/libc/include/namespace.h)
-   defines `consttime_memequal' as a macro expanding to
-   `_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':
+
+       #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 @@
 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 @@
    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 @@
    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