guix-commits
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

79/176: gnu: glibc-boot: Update to 2.2.5.


From: Jan Nieuwenhuizen
Subject: 79/176: gnu: glibc-boot: Update to 2.2.5.
Date: Fri, 31 Aug 2018 11:20:18 -0400 (EDT)

janneke pushed a commit to branch wip-bootstrap
in repository guix.

commit 8812901d29c6624b8ed2926ea08befcc8f9e650c
Author: Jan Nieuwenhuizen <address@hidden>
Date:   Sun Jun 10 11:15:05 2018 +0200

    gnu: glibc-boot: Update to 2.2.5.
    
    * gnu/packages/mes.scm (glibc-boot): Update to 2.2.5.
    * gnu/packages/patches/glibc-boot-2.2.5.patch: New file.
    * gnu/packages/patches/glibc-boot.patch: Remove.
    * gnu/local.mk (dist_patch_DATA): Rename it.
---
 gnu/local.mk                                |     2 +-
 gnu/packages/mes.scm                        |    90 +-
 gnu/packages/patches/glibc-boot-2.2.5.patch |   204 +
 gnu/packages/patches/glibc-boot.patch       | 43015 --------------------------
 4 files changed, 255 insertions(+), 43056 deletions(-)

diff --git a/gnu/local.mk b/gnu/local.mk
index fbc42ef..262c300 100644
--- a/gnu/local.mk
+++ b/gnu/local.mk
@@ -742,7 +742,7 @@ dist_patch_DATA =                                           
\
   %D%/packages/patches/glibc-CVE-2017-1000366-pt2.patch                \
   %D%/packages/patches/glibc-CVE-2017-1000366-pt3.patch                \
   %D%/packages/patches/glibc-allow-kernel-2.6.32.patch         \
-  %D%/packages/patches/glibc-boot.patch                                \
+  %D%/packages/patches/glibc-boot-2.2.5.patch                  \
   %D%/packages/patches/glibc-bootstrap-system.patch            \
   %D%/packages/patches/glibc-hidden-visibility-ldconfig.patch  \
   %D%/packages/patches/glibc-ldd-x86_64.patch                  \
diff --git a/gnu/packages/mes.scm b/gnu/packages/mes.scm
index cc44c59..9667579 100644
--- a/gnu/packages/mes.scm
+++ b/gnu/packages/mes.scm
@@ -682,61 +682,71 @@ ac_cv_c_float_format='IEEE (little-endian)'
   (package
     (inherit glibc)
     (name "glibc-boot")
-    (version "2.0.1")
+    (version "2.2.5")
     (source (origin
               (method url-fetch)
-              (uri (string-append 
"https://gcc.gnu.org/pub/glibc/old-releases/glibc-";
-                                  version ".tar.bz2"))
-              (patches (search-patches "glibc-boot.patch"))
+              (uri (string-append "mirror://gnu/glibc/glibc-"
+                                  version
+                                  ".tar.gz"))
+              (patches (search-patches "glibc-boot-2.2.5.patch"))
               (sha256
                (base32
-                "1cckm2242wcc0i0zbs7djjp2z215fdca0j3ay6ydxhchvw4vir2v"))))
+                "1vl48i16gx6h68whjyhgnn1s57vqq32f9ygfa2fls7pdkbsqvp2q"))))
     (supported-systems '("i686-linux"))
     (native-inputs `(("binutils" ,binutils-boot)
-                     ("gcc" ,gcc-boot)
-                     ("tcc" ,tcc-boot)))
+                     ("gcc" ,gcc-boot)))
     (propagated-inputs `(("kernel-headers" ,(linux-libre-headers-boot0))))
+    (outputs '("out"))
     (arguments
-     `(#:tests? #f                      ; runtest: command not found
+     `(#:tests? #f
        #:strip-binaries? #f
-       #:parallel-build? #f
-       #:make-flags `(,(string-append "sysincludedir=" (assoc-ref 
%build-inputs "tcc") "/include"))
-       #:modules ((guix build gnu-build-system)
-                  (guix build utils)
-                  (srfi srfi-1))
+       #:parallel-build? #f     ; gcc-2.95.3 ICEs on massively parallel builds
+       #:configure-flags
+       (let ((out (assoc-ref %outputs "out"))
+             (headers (assoc-ref %build-inputs "kernel-headers")))
+         #:configure-flags
+         (list
+          "--disable-shared"
+          "--enable-static"
+          "--disable-sanity-checks"
+          "--host=i386-unknown-linux"
+          "--target=i386-unknown-linux"
+          (string-append "--with-headers=" headers "/include")
+          "--enable-static-nss"
+          "--without-__thread"
+          "--without-cvs"
+          "--without-gd"
+          "--without-tls"
+          (string-append "--prefix=" out)))
+       #:make-flags '("lib")
        #:phases
        (modify-phases %standard-phases
-         (replace 'configure
+         (add-before 'configure 'setenv
            (lambda* (#:key outputs #:allow-other-keys)
-             (let ((out (assoc-ref outputs "out"))
-                   (headers (assoc-ref %build-inputs "kernel-headers"))
-                   (binutils (assoc-ref %build-inputs "binutils"))
-                   (tcc (assoc-ref %build-inputs "tcc")))
-               (setenv "PATH" (string-append
-                               binutils "/i686-unknown-linux-gnu/bin"
-                               ":" (getenv "PATH")))
+             (let* ((out (assoc-ref outputs "out"))
+                    (headers (assoc-ref %build-inputs "kernel-headers"))
+                    (gcc (assoc-ref %build-inputs "gcc"))
+                    (cppflags (string-append
+                               " -D __STDC__=1"
+                               " -D MES_BOOTSTRAP=1"))
+                    (cflags (string-append " -L " (getcwd))))
                (setenv "CONFIG_SHELL" (string-append
                                        (assoc-ref %build-inputs "bash")
                                        "/bin/sh"))
-               (setenv "CPPLAGS" (string-append "-I" headers "/include"))
-               (setenv "CC" (string-append
-                             "gcc"
-                             " -I " headers "/include "
-                             " -D _POSIX_OPEN_MAX=16" ;; how to move to mes?
-                             " -DSTDOUT_FILENO=1"
-                             " -Dstderr=2"
-                             " -L " (getcwd)))
-               (setenv "CPP" "gcc -E")
-               (system* "ar" "r" "libc.a"
-                        (string-append tcc "/lib/libg.o"))
-               (system* "ls" "-ltrF")
-               (and
-                (zero?
-                 (system* "./configure"
-                          "--host=i386-unknown-linux"
-                          "--target=i386-unknown-linux"
-                          "--disable-sanity-checks"
-                          (string-append "--prefix=" out))))))))))))
+               (setenv "CPP" (string-append gcc "/bin/gcc -E " cppflags))
+               (setenv "CC" (string-append gcc "/bin/gcc " cppflags cflags))
+               (unsetenv "C_INCLUDE_PATH")
+               (unsetenv "LIBRARY_PATH"))))
+         ;; glibc-2.2.5 needs a slightly more classical invocation of configure
+         ;; configure: warning: 
CONFIG_SHELL=/gnu/store/kpxi8h3669afr9r1bgvaf9ij3y4wdyyn-bash-minimal-4.4.12/bin/bash:
 invalid host type
+         (replace 'configure
+           (lambda* (#:key configure-flags #:allow-other-keys)
+             (zero?
+              (apply system* "./configure" configure-flags))))
+         (replace 'install
+           (lambda* (#:key make-flags #:allow-other-keys)
+             (zero?
+              (apply system* "make" "install-lib-all" "install-headers" 
make-flags)))))))))
 
 ;;;
 
diff --git a/gnu/packages/patches/glibc-boot-2.2.5.patch 
b/gnu/packages/patches/glibc-boot-2.2.5.patch
new file mode 100644
index 0000000..e8b9c52
--- /dev/null
+++ b/gnu/packages/patches/glibc-boot-2.2.5.patch
@@ -0,0 +1,204 @@
+odiff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x 
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/adiff glibc-2.2.5/adiff
+--- ../glibc-2.2.5/adiff       1970-01-01 01:00:00.000000000 +0100
++++ glibc-2.2.5/adiff  2018-06-09 10:43:27.954899327 +0200
+@@ -0,0 +1,26 @@
++make 4.x should be fine
++
++sed: unterminated `s' command
++
++    fopen_max=16
++    16
++
++timex.h:
++
++gcc: Internal compiler error: program cc1 got fatal signal 11
++
++syslog.c:
++syslog.c:219: `cancel_handler' undeclared (first use in this function)
++
++Makefile:250: *** mixed implicit and normal rules: deprecated syntax
++make[1]: *** No rule to make target 'stamp.o', needed by 'lib'.  Stop.
++make[1]: Leaving directory 
'/tmp/guix-build-glibc-boot-2.2.5.drv-0/glibc-2.2.5/manual'
++
++math/ftestexcept.c:
++/tmp/guix-build-glibc-boot-2.2.5.drv-0/cce9CKia.s: Assembler messages:
++/tmp/guix-build-glibc-boot-2.2.5.drv-0/cce9CKia.s:61: Error: operand type 
mismatch for `fnstsw'
++make[1]: *** [../sysd-rules:256: ftestexcept.o] Error 1
++make[1]: Leaving directory 
'/tmp/guix-build-glibc-boot-2.2.5.drv-0/glibc-2.2.5/math'
++
++
++glibc-2.2.5/stdio-common/perror.c:68: undefined reference to `fileno_unlocked'
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x 
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/configure glibc-2.2.5/configure
+--- ../glibc-2.2.5/configure   2002-01-08 23:16:44.000000000 +0100
++++ glibc-2.2.5/configure      2018-06-07 20:47:26.608895319 +0200
+@@ -1530,7 +1530,7 @@ echo "configure:1530: checking version o
+   ac_prog_version=`$MAKE --version 2>&1 | sed -n 's/^.*GNU 
Make[^0-9]*\([0-9][0-9.]*\).*$/\1/p'`
+   case $ac_prog_version in
+     '') ac_prog_version="v. ?.??, bad"; ac_verc_fail=yes;;
+-    3.79* | 3.[89]*)
++    3.79* | 3.[89]* | 4.*)
+        ac_prog_version="$ac_prog_version, ok"; ac_verc_fail=no;;
+     *) ac_prog_version="$ac_prog_version, bad"; ac_verc_fail=yes;;
+ 
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x 
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/Makerules glibc-2.2.5/Makerules
+--- ../glibc-2.2.5/Makerules   2001-11-16 02:02:19.000000000 +0100
++++ glibc-2.2.5/Makerules      2018-06-10 14:54:18.152989789 +0200
+@@ -748,6 +748,18 @@ endef
+ installed-libcs := $(foreach o,$(filter-out .os,$(object-suffixes-for-libc)),\
+                            $(inst_libdir)/$(patsubst %,$(libtype$o),\
+                                                    $(libprefix)$(libc-name)))
++
++ifeq (yes,$(build-shared))
++install-lib-all: $(inst_libdir)/libc.a \
++                $(inst_slibdir)/libc.so$(libc.so-version) \
++              $(inst_slibdir)/libc-$(version).so \
++              $(inst_libdir)/libc.so \
++      install-lib
++else
++install-lib-all: $(inst_libdir)/libc.a \
++      install-lib
++endif
++
+ install: $(installed-libcs)
+ $(installed-libcs): $(inst_libdir)/lib$(libprefix)%: lib $(+force)
+       $(make-target-directory)
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x 
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/misc/syslog.c 
glibc-2.2.5/misc/syslog.c
+--- ../glibc-2.2.5/misc/syslog.c       2001-08-31 01:13:49.000000000 +0200
++++ glibc-2.2.5/misc/syslog.c  2018-06-09 09:01:20.008918690 +0200
+@@ -216,9 +216,11 @@ vsyslog(pri, fmt, ap)
+ 
+       /* Prepare for multiple users.  We have to take care: open and
+          write are cancellation points.  */
++#if _LIBC_REENTRANT
+       __libc_cleanup_region_start (1, (void (*) (void *)) cancel_handler,
+                                    &oldaction_ptr);
+       __libc_lock_lock (syslog_lock);
++#endif
+ 
+       /* Prepare for a broken connection.  */
+       memset (&action, 0, sizeof (action));
+@@ -268,9 +270,11 @@ vsyslog(pri, fmt, ap)
+       if (sigpipe == 0)
+               __sigaction (SIGPIPE, &oldaction, (struct sigaction *) NULL);
+ 
++#if _LIBC_REENTRANT
+       /* End of critical section.  */
+       __libc_cleanup_region_end (0);
+       __libc_lock_unlock (syslog_lock);
++#endif
+ 
+       free (buf);
+ }
+@@ -326,16 +330,20 @@ openlog_internal(const char *ident, int
+ void
+ openlog (const char *ident, int logstat, int logfac)
+ {
++#if _LIBC_REENTRANT
+   /* Protect against multiple users.  */
+   __libc_cleanup_region_start (1,
+                              (void (*) __P ((void *))) __libc_mutex_unlock,
+                              &syslog_lock);
+   __libc_lock_lock (syslog_lock);
++#endif
+ 
+   openlog_internal (ident, logstat, logfac);
+ 
++#if _LIBC_REENTRANT
+   /* Free the lock.  */
+   __libc_cleanup_region_end (1);
++#endif
+ }
+ 
+ static void
+@@ -358,18 +366,22 @@ closelog_internal()
+ void
+ closelog ()
+ {
++#if _LIBC_REENTRANT
+   /* Protect against multiple users.  */
+   __libc_cleanup_region_start (1,
+                              (void (*) __P ((void *))) __libc_mutex_unlock,
+                              &syslog_lock);
+   __libc_lock_lock (syslog_lock);
++#endif
+ 
+   closelog_internal ();
+   LogTag = NULL;
+   LogType = SOCK_DGRAM; /* this is the default */
+ 
++#if _LIBC_REENTRANT
+   /* Free the lock.  */
+   __libc_cleanup_region_end (1);
++#endif
+ }
+ 
+ #ifdef _LIBC_REENTRANT
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x 
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/Rules glibc-2.2.5/Rules
+--- ../glibc-2.2.5/Rules       2001-08-30 00:44:35.000000000 +0200
++++ glibc-2.2.5/Rules  2018-06-09 08:15:54.880683675 +0200
+@@ -218,7 +218,7 @@ endif
+       fopen_max=`sed -n 's/^#define OPEN_MAX //1p' $(@:st=hT)`;       \
+       filename_max=`sed -n 's/^#define PATH_MAX //1p' $(@:st=hT)`;    \
+       iov_max=`sed -n 's/^#define UIO_MAXIOV //p' $(@:st=hT)`;        \
+-      fopen_max=$${fopen_max:-16};                                    \
++      fopen_max=$${fu_fopen_max:-16};                                 \
+       filename_max=$${filename_max:-1024};                            \
+       if [ -z $$iov_max ]; then                                       \
+         define_iov_max="# undef IOV_MAX";                             \
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x 
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/stdio-common/perror.c 
glibc-2.2.5/stdio-common/perror.c
+--- ../glibc-2.2.5/stdio-common/perror.c       2001-09-01 07:33:01.000000000 
+0200
++++ glibc-2.2.5/stdio-common/perror.c  2018-06-09 10:42:25.909899529 +0200
+@@ -48,6 +48,8 @@ perror_internal (FILE *fp, const char *s
+ }
+ 
+ 
++#define fileno_unlocked(x) 1
++
+ /* Print a line on stderr consisting of the text in S, a colon, a space,
+    a message describing the meaning of the contents of `errno' and a newline.
+    If S is NULL or "", the colon and space are omitted.  */
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x 
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/sysdeps/i386/fpu/ftestexcept.c 
glibc-2.2.5/sysdeps/i386/fpu/ftestexcept.c
+--- ../glibc-2.2.5/sysdeps/i386/fpu/ftestexcept.c      2001-07-06 
06:55:53.000000000 +0200
++++ glibc-2.2.5/sysdeps/i386/fpu/ftestexcept.c 2018-06-09 09:45:13.363031424 
+0200
+@@ -25,8 +25,10 @@ fetestexcept (int excepts)
+ {
+   int temp;
+ 
++#if 0
+   /* Get current exceptions.  */
+   __asm__ ("fnstsw %0" : "=a" (temp));
++#endif
+ 
+   return temp & excepts & FE_ALL_EXCEPT;
+ }
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x 
BOOT-GCC -x texis -x '*.info*' 
../glibc-2.2.5/sysdeps/unix/sysv/linux/sys/timex.h 
glibc-2.2.5/sysdeps/unix/sysv/linux/sys/timex.h
+--- ../glibc-2.2.5/sysdeps/unix/sysv/linux/sys/timex.h 2001-07-06 
06:56:21.000000000 +0200
++++ glibc-2.2.5/sysdeps/unix/sysv/linux/sys/timex.h    2018-06-09 
20:09:07.713806647 +0200
+@@ -54,10 +54,12 @@ struct timex
+   long int errcnt;    /* calibration errors (ro) */
+   long int stbcnt;    /* stability limit exceeded (ro) */
+ 
++#if !MES_BOOTSTRAP
+   /* ??? */
+   int  :32; int  :32; int  :32; int  :32;
+   int  :32; int  :32; int  :32; int  :32;
+   int  :32; int  :32; int  :32; int  :32;
++#endif
+ };
+ 
+ /* Mode codes (timex.mode) */
+--- ../glibc-2.2.5/manual/Makefile     2001-08-28 10:05:40.000000000 +0200
++++ glibc-2.2.5/manual/Makefile        2018-06-09 10:13:03.093633660 +0200
+@@ -247,7 +247,11 @@
+ .PHONY: stubs
+ stubs: $(objpfx)stubs
+ endif
+-$(objpfx)stubs ../po/manual.pot $(objpfx)stamp%:
++po/manual.pot $(objpfx)stubs:
++      $(make-target-directory)
++      touch $@
++
++$(objpfx)stamp%:
+       $(make-target-directory)
+       touch $@
+ 
diff --git a/gnu/packages/patches/glibc-boot.patch 
b/gnu/packages/patches/glibc-boot.patch
deleted file mode 100644
index e702fcd..0000000
--- a/gnu/packages/patches/glibc-boot.patch
+++ /dev/null
@@ -1,43015 +0,0 @@
-diff -purN -x BOOT ../glibc-2.0.1/assert/assert.c glibc-2.0.1/assert/assert.c
---- ../glibc-2.0.1/assert/assert.c     1996-12-02 16:40:23.000000000 +0100
-+++ glibc-2.0.1/assert/assert.c        2018-06-05 21:00:54.777209397 +0200
-@@ -21,6 +21,9 @@
- #include <stdlib.h>
- #include <sysdep.h>
- 
-+#ifndef stderr
-+#define stderr 2
-+#endif
- 
- const char *__assert_program_name;
- 
-diff -purN -x BOOT ../glibc-2.0.1/csu/errno-loc.d glibc-2.0.1/csu/errno-loc.d
---- ../glibc-2.0.1/csu/errno-loc.d     1970-01-01 01:00:00.000000000 +0100
-+++ glibc-2.0.1/csu/errno-loc.d        2018-06-05 20:53:03.897575013 +0200
-@@ -0,0 +1 @@
-+errno-loc.o errno-loc.so errno-loc.po errno-loc.d: 
../sysdeps/generic/errno-loc.c
-Binary files ../glibc-2.0.1/csu/errno-loc.o and glibc-2.0.1/csu/errno-loc.o 
differ
-Binary files ../glibc-2.0.1/csu/errno-loc.po and glibc-2.0.1/csu/errno-loc.po 
differ
-Binary files ../glibc-2.0.1/csu/errno-loc.so and glibc-2.0.1/csu/errno-loc.so 
differ
-diff -purN -x BOOT ../glibc-2.0.1/ctype/ctype.c glibc-2.0.1/ctype/ctype.c
---- ../glibc-2.0.1/ctype/ctype.c       1992-10-07 23:22:36.000000000 +0100
-+++ glibc-2.0.1/ctype/ctype.c  2018-06-05 22:08:32.547406861 +0200
-@@ -21,8 +21,6 @@ Cambridge, MA 02139, USA.  */
- #define       __NO_CTYPE
- #include <ctype.h>
- 
--/* Provide real-function versions of all the ctype macros.  */
--
- #define       func(name, type) \
-   int DEFUN(name, (c), int c) { return __isctype(c, type); }
- 
-diff -purN -x BOOT ../glibc-2.0.1/ctype/ctype.E glibc-2.0.1/ctype/ctype.E
---- ../glibc-2.0.1/ctype/ctype.E       1970-01-01 01:00:00.000000000 +0100
-+++ glibc-2.0.1/ctype/ctype.E  2018-06-05 21:55:56.987061510 +0200
-@@ -0,0 +1,222 @@
-+# 1 "ctype.c"
-+# 1 "../libc-symbols.h" 1
-+ 
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+ 
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+ 
-+
-+
-+
-+
-+
-+
-+
-+
-+ 
-+
-+ 
-+
-+
-+
-+ 
-+
-+
-+
-+
-+
-+ 
-+
-+
-+
-+
-+
-+extern const char _libc_intl_domainname[];
-+
-+
-+
-+
-+
-+ 
-+
-+
-+
-+
-+
-+
-+ 
-+
-+
-+ 
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+ 
-+# 119 "../libc-symbols.h"
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+ 
-+
-+
-+
-+
-+# 184 "../libc-symbols.h"
-+
-+
-+
-+
-+
-+
-+# 210 "../libc-symbols.h"
-+
-+
-+
-+
-+ 
-+
-+
-+
-+
-+
-+
-+
-+
-+ 
-+
-+# 248 "../libc-symbols.h"
-+
-+ 
-+
-+
-+
-+ 
-+
-+
-+
-+
-+ 
-+
-+
-+
-+# 320 "../libc-symbols.h"
-+
-+
-+
-+# 1 "ctype.c" 2
-+ 
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+ 
-+
-+
-+
-+
-+int DEFUN( isalnum , (c), int c) { return __isctype(c,   _ISalnum ); } 
-+int DEFUN( isalpha , (c), int c) { return __isctype(c,   _ISalpha ); } 
-+int DEFUN( iscntrl , (c), int c) { return __isctype(c,   _IScntrl ); } 
-+int DEFUN( isdigit , (c), int c) { return __isctype(c,   _ISdigit ); } 
-+int DEFUN( islower , (c), int c) { return __isctype(c,   _ISlower ); } 
-+int DEFUN( isgraph , (c), int c) { return __isctype(c,   _ISgraph ); } 
-+int DEFUN( isprint , (c), int c) { return __isctype(c,   _ISprint ); } 
-+int DEFUN( ispunct , (c), int c) { return __isctype(c,   _ISpunct ); } 
-+int DEFUN( isspace , (c), int c) { return __isctype(c,   _ISspace ); } 
-+int DEFUN( isupper , (c), int c) { return __isctype(c,   _ISupper ); } 
-+int DEFUN( isxdigit , (c), int c) { return __isctype(c,   _ISxdigit ); } 
-+
-+int
-+DEFUN(tolower, (c), int c)
-+{
-+  return __tolower (c);
-+}
-+
-+int
-+DEFUN(toupper, (c), int c)
-+{
-+  return __toupper (c);
-+}
-diff -purN -x BOOT ../glibc-2.0.1/ctype/ctype.h glibc-2.0.1/ctype/ctype.h
---- ../glibc-2.0.1/ctype/ctype.h       1996-11-08 13:22:43.000000000 +0100
-+++ glibc-2.0.1/ctype/ctype.h  2018-06-05 22:05:26.852368283 +0200
-@@ -25,7 +25,7 @@
- #define       _CTYPE_H        1
- #include <features.h>
- 
--__BEGIN_DECLS
-+/*__BEGIN_DECLS*/
- 
- #ifndef _ISbit
- /* These are all the characteristics of characters.
-diff -purN -x BOOT ../glibc-2.0.1/glibcbug glibc-2.0.1/glibcbug
---- ../glibc-2.0.1/glibcbug    1970-01-01 01:00:00.000000000 +0100
-+++ glibc-2.0.1/glibcbug       2018-06-05 22:08:58.423830274 +0200
-@@ -0,0 +1,244 @@
-+#! /bin/sh
-+#
-+# glibcbug - create a bug report and mail it to the bug address.
-+#
-+# configuration section:
-+#       these variables are filled in by configure
-+#
-+VERSION="2.0.1"
-+BUGGLIBC="address@hidden"
-+ADDONS=""
-+
-+PATH=/bin:/usr/bin:/usr/local/bin:$PATH
-+export PATH
-+
-+TEMP=/tmp/glibcbug.$$
-+
-+BUGADDR=${1-$BUGGLIBC}
-+ENVIRONMENT=`uname -a`
-+
-+: ${EDITOR=emacs}
-+
-+: ${USER=${LOGNAME-`whoami`}}
-+
-+trap 'rm -f $TEMP $TEMP.x; exit 1' 1 2 3 13 15
-+trap 'rm -f $TEMP $TEMP.x' 0
-+
-+
-+# How to read the passwd database.
-+PASSWD="cat /etc/passwd"
-+
-+if [ -f /usr/lib/sendmail ] ; then
-+        MAIL_AGENT="/usr/lib/sendmail -oi -t"
-+elif [ -f /usr/sbin/sendmail ] ; then
-+        MAIL_AGENT="/usr/sbin/sendmail -oi -t"
-+else
-+        MAIL_AGENT=rmail
-+fi
-+
-+# Figure out how to echo a string without a trailing newline
-+N=`echo 'hi there\c'`
-+case "$N" in
-+*c)   ECHON1='echo -n' ECHON2= ;;
-+*)    ECHON1=echo ECHON2='\c' ;;
-+esac
-+
-+# Find out the name of the originator of this PR.
-+if [ -n "$NAME" ]; then
-+  ORIGINATOR="$NAME"
-+elif [ -f $HOME/.fullname ]; then
-+  ORIGINATOR="`sed -e '1q' $HOME/.fullname`"
-+else
-+  # Must use temp file due to incompatibilities in quoting behavior
-+  # and to protect shell metacharacters in the expansion of $LOGNAME
-+  $PASSWD | grep "^$LOGNAME:" | awk -F: '{print $5}' | sed -e 's/,.*//' > 
$TEMP
-+  ORIGINATOR="`cat $TEMP`"
-+  rm -f $TEMP
-+fi
-+
-+if [ -n "$ORGANIZATION" ]; then
-+  if [ -f "$ORGANIZATION" ]; then
-+    ORGANIZATION="`cat $ORGANIZATION`"
-+  fi
-+else
-+  if [ -f $HOME/.organization ]; then
-+    ORGANIZATION="`cat $HOME/.organization`"
-+  elif [ -f $HOME/.signature ]; then
-+    ORGANIZATION=`sed -e "s/^/  /" $HOME/.signature; echo ">"`
-+  fi
-+fi
-+
-+# If they don't have a preferred editor set, then use
-+if [ -z "$VISUAL" ]; then
-+  if [ -z "$EDITOR" ]; then
-+    EDIT=vi
-+  else
-+    EDIT="$EDITOR"
-+  fi
-+else
-+  EDIT="$VISUAL"
-+fi
-+
-+# Find out some information.
-+SYSTEM=`( [ -f /bin/uname ] && /bin/uname -a ) || \
-+        ( [ -f /usr/bin/uname ] && /usr/bin/uname -a ) || echo ""`
-+ARCH=`[ -f /bin/arch ] && /bin/arch`
-+MACHINE=`[ -f /bin/machine ] && /bin/machine`
-+
-+ORGANIZATION_C='<organization of PR author (multiple lines)>'
-+SYNOPSIS_C='<synopsis of the problem (one line)>'
-+SEVERITY_C='<[ non-critical | serious | critical ] (one line)>'
-+PRIORITY_C='<[ low | medium | high ] (one line)>'
-+CLASS_C='<[ sw-bug | doc-bug | change-request | support ] (one line)>'
-+RELEASE_C='<release number or tag (one line)>'
-+ENVIRONMENT_C='<machine, os, target, libraries (multiple lines)>'
-+DESCRIPTION_C='<precise description of the problem (multiple lines)>'
-+HOW_TO_REPEAT_C='<code/input/activities to reproduce the problem (multiple 
lines)>'
-+FIX_C='<how to correct or work around the problem, if known (multiple lines)>'
-+
-+
-+cat > $TEMP <<EOF
-+SEND-PR: -*- send-pr -*-
-+SEND-PR: Lines starting with \`SEND-PR' will be removed automatically, as
-+SEND-PR: will all comments (text enclosed in \`<' and \`>').
-+SEND-PR:
-+From: ${USER}
-+To: ${BUGADDR}
-+Subject: [50 character or so descriptive subject here (for reference)]
-+
-+>Submitter-Id:        net
-+>Originator:  ${ORIGINATOR}
-+>Organization:
-+${ORGANIZATION- $ORGANIZATION_C}
-+>Confidential:        no
-+>Synopsis:    $SYNOPSIS_C
-+>Severity:    $SEVERITY_C
-+>Priority:    $PRIORITY_C
-+>Category:    libc
-+>Class:               $CLASS_C
-+>Release:     libc-${VERSION}
-+>Environment:
-+      $ENVIRONMENT_C
-+`[ -n "$SYSTEM" ] && echo System: $SYSTEM`
-+`[ -n "$ARCH" ] && echo Architecture: $ARCH`
-+`[ -n "$MACHINE" ] && echo Machine: $MACHINE`
-+`[ -n "$ADDONS" ] && echo Addons: $ADDONS`
-+
-+>Description:
-+      $DESCRIPTION_C
-+>How-To-Repeat:
-+      $HOW_TO_REPEAT_C
-+>Fix:
-+      $FIX_C
-+EOF
-+
-+chmod u+w $TEMP
-+cp $TEMP $TEMP.x
-+
-+eval $EDIT $TEMP
-+
-+if cmp -s $TEMP $TEMP.x; then
-+      echo "File not changed, no bug report submitted."
-+      exit 1
-+fi
-+
-+#
-+#       Check the enumeration fields
-+
-+# This is a "sed-subroutine" with one keyword parameter
-+# (with workaround for Sun sed bug)
-+#
-+SED_CMD='
-+/$PATTERN/{
-+s|||
-+s|<.*>||
-+s|^[  ]*||
-+s|[   ]*$||
-+p
-+q
-+}'
-+
-+
-+while :; do
-+  CNT=0
-+
-+  #
-+  # 1) Severity
-+  #
-+  PATTERN=">Severity:"
-+  SEVERITY=`eval sed -n -e "\"$SED_CMD\"" $TEMP`
-+  case "$SEVERITY" in
-+    ""|non-critical|serious|critical) CNT=`expr $CNT + 1` ;;
-+    *)  echo "$COMMAND: \`$SEVERITY' is not a valid value for \`Severity'."
-+  esac
-+  #
-+  # 2) Priority
-+  #
-+  PATTERN=">Priority:"
-+  PRIORITY=`eval sed -n -e "\"$SED_CMD\"" $TEMP`
-+  case "$PRIORITY" in
-+    ""|low|medium|high) CNT=`expr $CNT + 1` ;;
-+    *)  echo "$COMMAND: \`$PRIORITY' is not a valid value for \`Priority'."
-+  esac
-+  #
-+  # 3) Class
-+  #
-+  PATTERN=">Class:"
-+  CLASS=`eval sed -n -e "\"$SED_CMD\"" $TEMP`
-+  case "$CLASS" in
-+    ""|sw-bug|doc-bug|change-request|support) CNT=`expr $CNT + 1` ;;
-+    *)  echo "$COMMAND: \`$CLASS' is not a valid value for \`Class'."
-+  esac
-+
-+  [ $CNT -lt 3 ] &&
-+    echo "Errors were found with the problem report."
-+
-+  while :; do
-+    $ECHON1 "a)bort, e)dit or s)end? $ECHON2"
-+    read input
-+    case "$input" in
-+      a*)
-+      echo "$COMMAND: problem report saved in $HOME/dead.glibcbug."
-+      cat $TEMP >> $HOME/dead.glibcbug
-+        xs=1; exit
-+        ;;
-+      e*)
-+        eval $EDIT $TEMP
-+        continue 2
-+        ;;
-+      s*)
-+        break 2
-+        ;;
-+    esac
-+  done
-+done
-+#
-+#       Remove comments and send the problem report
-+#       (we have to use patterns, where the comment contains regex chars)
-+#
-+# /^>Originator:/s;$ORIGINATOR;;
-+sed  -e "
-+/^SEND-PR:/d
-+/^>Organization:/,/^>[A-Za-z-]*:/s;$ORGANIZATION_C;;
-+/^>Confidential:/s;<.*>;;
-+/^>Synopsis:/s;$SYNOPSIS_C;;
-+/^>Severity:/s;<.*>;;
-+/^>Priority:/s;<.*>;;
-+/^>Class:/s;<.*>;;
-+/^>Release:/,/^>[A-Za-z-]*:/s;$RELEASE_C;;
-+/^>Environment:/,/^>[A-Za-z-]*:/s;$ENVIRONMENT_C;;
-+/^>Description:/,/^>[A-Za-z-]*:/s;$DESCRIPTION_C;;
-+/^>How-To-Repeat:/,/^>[A-Za-z-]*:/s;$HOW_TO_REPEAT_C;;
-+/^>Fix:/,/^>[A-Za-z-]*:/s;$FIX_C;;
-+" $TEMP > $TEMP.x
-+
-+if $MAIL_AGENT $BUGGLIBC < $TEMP.x; then
-+  echo "$COMMAND: problem report sent"
-+  xs=0; exit
-+else
-+  echo "$COMMAND: mysterious mail failure, report not sent."
-+  echo "$COMMAND: problem report saved in $HOME/dead.glibcbug."
-+  cat $TEMP >> $HOME/dead.glibcbug
-+fi
-+
-+exit 0
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info glibc-2.0.1/manual/libc.info
---- ../glibc-2.0.1/manual/libc.info    1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info       1970-01-01 01:00:00.000000000 +0100
-@@ -1,596 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--Indirect:
--libc.info-1: 1168
--libc.info-2: 50130
--libc.info-3: 97453
--libc.info-4: 144446
--libc.info-5: 193430
--libc.info-6: 237807
--libc.info-7: 285360
--libc.info-8: 334723
--libc.info-9: 379684
--libc.info-10: 428359
--libc.info-11: 477650
--libc.info-12: 526627
--libc.info-13: 576207
--libc.info-14: 625641
--libc.info-15: 673159
--libc.info-16: 720930
--libc.info-17: 769559
--libc.info-18: 816715
--libc.info-19: 864190
--libc.info-20: 914097
--libc.info-21: 963959
--libc.info-22: 1011044
--libc.info-23: 1058556
--libc.info-24: 1108289
--libc.info-25: 1158030
--libc.info-26: 1207860
--libc.info-27: 1256153
--libc.info-28: 1305051
--libc.info-29: 1410972
--libc.info-30: 1453346
--libc.info-31: 1480210
--libc.info-32: 1530394
--libc.info-33: 1567426
--
--Tag Table:
--(Indirect)
--Node: Top1168
--Node: Introduction40477
--Node: Getting Started41825
--Node: Standards and Portability43285
--Node: ISO C44670
--Node: POSIX46187
--Node: Berkeley Unix47867
--Node: SVID48635
--Node: Using the Library49407
--Node: Header Files50130
--Node: Macro Definitions54082
--Node: Reserved Names56432
--Node: Feature Test Macros61114
--Node: Roadmap to the Manual66998
--Node: Error Reporting74211
--Node: Checking for Errors75139
--Node: Error Codes79354
--Node: Error Messages97453
--Node: Memory Allocation102288
--Node: Memory Concepts103291
--Node: Dynamic Allocation and C104561
--Node: Unconstrained Allocation106645
--Node: Basic Allocation107972
--Node: Malloc Examples109676
--Node: Freeing after Malloc111657
--Node: Changing Block Size113473
--Node: Allocating Cleared Space116037
--Node: Efficiency and Malloc116828
--Node: Aligned Memory Blocks118326
--Node: Heap Consistency Checking119694
--Node: Hooks for Malloc122487
--Node: Statistics of Malloc124736
--Node: Summary of Malloc126242
--Node: Obstacks128081
--Node: Creating Obstacks129699
--Node: Preparing for Obstacks131598
--Node: Allocation in an Obstack133938
--Node: Freeing Obstack Objects136633
--Node: Obstack Functions137969
--Node: Growing Objects140199
--Node: Extra Fast Growing144446
--Node: Status of an Obstack148065
--Node: Obstacks Data Alignment149484
--Node: Obstack Chunks151170
--Node: Summary of Obstacks153527
--Node: Variable Size Automatic156941
--Node: Alloca Example158497
--Node: Advantages of Alloca159614
--Node: Disadvantages of Alloca161506
--Node: GNU C Variable-Size Arrays162251
--Node: Relocating Allocator163409
--Node: Relocator Concepts163971
--Node: Using Relocator165484
--Node: Memory Warnings166869
--Node: Character Handling168181
--Node: Classification of Characters169130
--Node: Case Conversion172791
--Node: String and Array Utilities174639
--Node: Representation of Strings176450
--Node: String/Array Conventions179392
--Node: String Length181224
--Node: Copying and Concatenation182209
--Node: String/Array Comparison193430
--Node: Collation Functions198493
--Node: Search Functions205455
--Node: Finding Tokens in a String209726
--Node: I/O Overview215868
--Node: I/O Concepts217381
--Node: Streams and File Descriptors218526
--Node: File Position221617
--Node: File Names223751
--Node: Directories224637
--Node: File Name Resolution226374
--Node: File Name Errors229303
--Node: File Name Portability230852
--Node: I/O on Streams232844
--Node: Streams234800
--Node: Standard Streams236141
--Node: Opening Streams237807
--Node: Closing Streams243664
--Node: Simple Output246208
--Node: Character Input248544
--Node: Line Input251653
--Node: Unreading256641
--Node: Unreading Idea257450
--Node: How Unread258276
--Node: Block Input/Output260759
--Node: Formatted Output262988
--Node: Formatted Output Basics264755
--Node: Output Conversion Syntax267248
--Node: Table of Output Conversions270974
--Node: Integer Conversions273507
--Node: Floating-Point Conversions278171
--Node: Other Output Conversions282200
--Node: Formatted Output Functions285360
--Node: Dynamic Output289041
--Node: Variable Arguments Output290678
--Node: Parsing a Template String296190
--Node: Example of Parsing300017
--Node: Customizing Printf302305
--Node: Registering New Conversions304154
--Node: Conversion Specifier Options306145
--Node: Defining the Output Handler309818
--Node: Printf Extension Example312284
--Node: Formatted Input314592
--Node: Formatted Input Basics315671
--Node: Input Conversion Syntax318351
--Node: Table of Input Conversions321713
--Node: Numeric Input Conversions324010
--Node: String Input Conversions327788
--Node: Dynamic String Input331881
--Node: Other Input Conversions333071
--Node: Formatted Input Functions334723
--Node: Variable Arguments Input336289
--Node: EOF and Errors337924
--Node: Binary Streams340144
--Node: File Positioning342668
--Node: Portable Positioning346501
--Node: Stream Buffering349972
--Node: Buffering Concepts351557
--Node: Flushing Buffers352920
--Node: Controlling Buffering354416
--Node: Other Kinds of Streams358851
--Node: String Streams360113
--Node: Obstack Streams364233
--Node: Custom Streams366267
--Node: Streams and Cookies366920
--Node: Hook Functions369967
--Node: Low-Level I/O372353
--Node: Opening and Closing Files375005
--Node: I/O Primitives379684
--Node: File Position Primitive387937
--Node: Descriptors and Streams393372
--Node: Stream/Descriptor Precautions395792
--Node: Linked Channels396999
--Node: Independent Channels398227
--Node: Cleaning Streams400130
--Node: Waiting for I/O402333
--Node: Control Operations410084
--Node: Duplicating Descriptors412368
--Node: Descriptor Flags416630
--Node: File Status Flags420036
--Node: Access Modes421490
--Node: Open-time Flags423779
--Node: Operating Modes428359
--Node: Getting File Status Flags431125
--Node: File Locks433736
--Node: Interrupt Input442639
--Node: File System Interface445058
--Node: Working Directory446458
--Node: Accessing Directories450212
--Node: Directory Entries451418
--Node: Opening a Directory454218
--Node: Reading/Closing Directory455910
--Node: Simple Directory Lister458844
--Node: Random Access Directory459823
--Node: Hard Links461290
--Node: Symbolic Links464083
--Node: Deleting Files467849
--Node: Renaming Files470779
--Node: Creating Directories474406
--Node: File Attributes476154
--Node: Attribute Meanings477650
--Node: Reading Attributes482733
--Node: Testing File Type484635
--Node: File Owner487851
--Node: Permission Bits491544
--Node: Access Permission496651
--Node: Setting Permissions497801
--Node: Testing File Access503016
--Node: File Times506659
--Node: Making Special Files511167
--Node: Temporary Files512844
--Node: Pipes and FIFOs519051
--Node: Creating a Pipe520634
--Node: Pipe to a Subprocess523787
--Node: FIFO Special Files526627
--Node: Pipe Atomicity528200
--Node: Sockets529084
--Node: Socket Concepts530959
--Node: Communication Styles534173
--Node: Socket Addresses536025
--Node: Address Formats538066
--Node: Setting Address540749
--Node: Reading Address542453
--Node: File Namespace544211
--Node: File Namespace Concepts544701
--Node: File Namespace Details546296
--Node: File Socket Example547910
--Node: Internet Namespace549234
--Node: Internet Address Format550961
--Node: Host Addresses552330
--Node: Abstract Host Addresses553390
--Node: Host Address Data Type556183
--Node: Host Address Functions558074
--Node: Host Names560501
--Node: Ports565513
--Node: Services Database567551
--Node: Byte Order570378
--Node: Protocols Database572666
--Node: Inet Example576207
--Node: Misc Namespaces578237
--Node: Open/Close Sockets578987
--Node: Creating a Socket579485
--Node: Closing a Socket581153
--Node: Socket Pairs582683
--Node: Connections584693
--Node: Connecting585787
--Node: Listening588343
--Node: Accepting Connections590428
--Node: Who is Connected593284
--Node: Transferring Data594380
--Node: Sending Data595490
--Node: Receiving Data597738
--Node: Socket Data Options599202
--Node: Byte Stream Example600065
--Node: Server Example602043
--Node: Out-of-Band Data606090
--Node: Datagrams611944
--Node: Sending Datagrams612973
--Node: Receiving Datagrams614630
--Node: Datagram Example616431
--Node: Example Receiver618349
--Node: Inetd620916
--Node: Inetd Servers621724
--Node: Configuring Inetd622967
--Node: Socket Options625641
--Node: Socket Option Functions626349
--Node: Socket-Level Options627907
--Node: Networks Database631541
--Node: Low-Level Terminal Interface634403
--Node: Is It a Terminal635738
--Node: I/O Queues636954
--Node: Canonical or Not638924
--Node: Terminal Modes640771
--Node: Mode Data Types642047
--Node: Mode Functions643875
--Node: Setting Modes647815
--Node: Input Modes649803
--Node: Output Modes655070
--Node: Control Modes656683
--Node: Local Modes660773
--Node: Line Speed667087
--Node: Special Characters671247
--Node: Editing Characters673159
--Node: Signal Characters677500
--Node: Start/Stop Characters680369
--Node: Other Special682240
--Node: Noncanonical Input684054
--Node: Line Control688867
--Node: Noncanon Example693179
--Node: Mathematics695374
--Node: Domain and Range Errors696578
--Node: Trig Functions699801
--Node: Inverse Trig Functions701171
--Node: Exponents and Logarithms703609
--Node: Hyperbolic Functions706510
--Node: Pseudo-Random Numbers708089
--Node: ISO Random709675
--Node: BSD Random710848
--Node: Arithmetic712765
--Node: Not a Number713674
--Node: Predicates on Floats715016
--Node: Absolute Value716590
--Node: Normalization Functions718088
--Node: Rounding and Remainders720930
--Node: Integer Division724298
--Node: Parsing of Numbers726448
--Node: Parsing of Integers727100
--Node: Parsing of Floats734575
--Node: Searching and Sorting739039
--Node: Comparison Functions739830
--Node: Array Search Function740944
--Node: Array Sort Function742367
--Node: Search/Sort Example744339
--Node: Pattern Matching747789
--Node: Wildcard Matching748591
--Node: Globbing751469
--Node: Calling Glob752259
--Node: Flags for Globbing755840
--Node: Regular Expressions759338
--Node: POSIX Regexp Compilation760322
--Node: Flags for POSIX Regexps764437
--Node: Matching POSIX Regexps765344
--Node: Regexp Subexpressions767505
--Node: Subexpression Complications769559
--Node: Regexp Cleanup771918
--Node: Word Expansion774244
--Node: Expansion Stages775412
--Node: Calling Wordexp776905
--Node: Flags for Wordexp780868
--Node: Wordexp Example782821
--Node: Date and Time784796
--Node: Processor Time785920
--Node: Basic CPU Time786678
--Node: Detailed CPU Time788697
--Node: Calendar Time791162
--Node: Simple Calendar Time792740
--Node: High-Resolution Calendar794497
--Node: Broken-down Time800217
--Node: Formatting Date and Time805433
--Node: TZ Variable816715
--Node: Time Zone Functions822776
--Node: Time Functions Example825441
--Node: Setting an Alarm826556
--Node: Sleeping831783
--Node: Resource Usage834439
--Node: Limits on Resources837950
--Node: Priority842324
--Node: Extended Characters845586
--Node: Extended Char Intro847194
--Node: Locales and Extended Chars849131
--Node: Multibyte Char Intro850181
--Node: Wide Char Intro857475
--Node: Wide String Conversion859242
--Node: Length of Char862479
--Node: Converting One Char864190
--Node: Example of Conversion867587
--Node: Shift State870477
--Node: Locales873130
--Node: Effects of Locale874698
--Node: Choosing Locale876634
--Node: Locale Categories877958
--Node: Setting the Locale879605
--Node: Standard Locales883499
--Node: Numeric Formatting884739
--Node: General Numeric886249
--Node: Currency Symbol889171
--Node: Sign of Money Amount893781
--Node: Non-Local Exits896085
--Node: Non-Local Intro896704
--Node: Non-Local Details900431
--Node: Non-Local Exits and Signals903507
--Node: Signal Handling904977
--Node: Concepts of Signals907012
--Node: Kinds of Signals907576
--Node: Signal Generation908973
--Node: Delivery of Signal911240
--Node: Standard Signals914097
--Node: Program Error Signals915690
--Node: Termination Signals923148
--Node: Alarm Signals926986
--Node: Asynchronous I/O Signals928226
--Node: Job Control Signals929417
--Node: Operation Error Signals934029
--Node: Miscellaneous Signals935968
--Node: Signal Messages937664
--Node: Signal Actions939550
--Node: Basic Signal Handling940495
--Node: Advanced Signal Handling945428
--Node: Signal and Sigaction948384
--Node: Sigaction Function Example950136
--Node: Flags for Sigaction952452
--Node: Initial Signal Actions954830
--Node: Defining Handlers956213
--Node: Handler Returns958398
--Node: Termination in Handler960448
--Node: Longjmp in Handler961864
--Node: Signals in Handler963959
--Node: Merged Signals966079
--Node: Nonreentrancy971789
--Node: Atomic Data Access977337
--Node: Non-atomic Example978373
--Node: Atomic Types980144
--Node: Atomic Usage981152
--Node: Interrupted Primitives982622
--Node: Generating Signals985922
--Node: Signaling Yourself986515
--Node: Signaling Another Process988497
--Node: Permission for kill991880
--Node: Kill Example993676
--Node: Blocking Signals996020
--Node: Why Block997792
--Node: Signal Sets999329
--Node: Process Signal Mask1002355
--Node: Testing for Delivery1005363
--Node: Blocking for Handler1006613
--Node: Checking for Pending Signals1009032
--Node: Remembering a Signal1011044
--Node: Waiting for a Signal1014593
--Node: Using Pause1015138
--Node: Pause Problems1016358
--Node: Sigsuspend1018082
--Node: Signal Stack1020792
--Node: BSD Signal Handling1026136
--Node: BSD Handler1027410
--Node: Blocking in BSD1029844
--Node: Process Startup1031298
--Node: Program Arguments1032333
--Node: Argument Syntax1035062
--Node: Parsing Options1037692
--Node: Example of Getopt1040983
--Node: Long Options1043699
--Node: Long Option Example1047760
--Node: Suboptions1050609
--Node: Suboptions Example1052558
--Node: Environment Variables1054653
--Node: Environment Access1056514
--Node: Standard Environment1058556
--Node: Program Termination1062239
--Node: Normal Termination1063458
--Node: Exit Status1064684
--Node: Cleanups on Exit1067703
--Node: Aborting a Program1069520
--Node: Termination Internals1070419
--Node: Processes1072195
--Node: Running a Command1074218
--Node: Process Creation Concepts1075711
--Node: Process Identification1077721
--Node: Creating a Process1078645
--Node: Executing a File1082261
--Node: Process Completion1089296
--Node: Process Completion Status1094305
--Node: BSD Wait Functions1095949
--Node: Process Creation Example1097841
--Node: Job Control1100091
--Node: Concepts of Job Control1101371
--Node: Job Control is Optional1104728
--Node: Controlling Terminal1105778
--Node: Access to the Terminal1106685
--Node: Orphaned Process Groups1108289
--Node: Implementing a Shell1109281
--Node: Data Structures1110164
--Node: Initializing the Shell1112807
--Node: Launching Jobs1116543
--Node: Foreground and Background1123996
--Node: Stopped and Terminated Jobs1127105
--Node: Continuing Stopped Jobs1132287
--Node: Missing Pieces1133914
--Node: Functions for Job Control1135538
--Node: Identifying the Terminal1136018
--Node: Process Group Functions1137592
--Node: Terminal Access Functions1141144
--Node: Name Service Switch1144045
--Node: NSS Basics1145379
--Node: NSS Configuration File1146956
--Node: Services in the NSS configuration1148654
--Node: Actions in the NSS configuration1149935
--Node: Notes on NSS Configuration File1153094
--Node: NSS Module Internals1154970
--Node: NSS Module Names1155666
--Node: NSS Modules Interface1158030
--Node: Extending NSS1161514
--Node: Adding another Service to NSS1162445
--Node: NSS Module Function Internals1164664
--Node: Users and Groups1169065
--Node: User and Group IDs1171541
--Node: Process Persona1172448
--Node: Why Change Persona1173959
--Node: How Change Persona1175840
--Node: Reading Persona1177322
--Node: Setting User ID1179592
--Node: Setting Groups1181802
--Node: Enable/Disable Setuid1184359
--Node: Setuid Program Example1186398
--Node: Tips for Setuid1189867
--Node: Who Logged In1191955
--Node: User Database1194123
--Node: User Data Structure1194784
--Node: Lookup User1196063
--Node: Scanning All Users1199153
--Node: Writing a User Entry1202532
--Node: Group Database1203431
--Node: Group Data Structure1204018
--Node: Lookup Group1204804
--Node: Scanning All Groups1207860
--Node: Netgroup Database1211141
--Node: Netgroup Data1211575
--Node: Lookup Netgroup1213139
--Node: Netgroup Membership1216551
--Node: Database Example1217881
--Node: System Information1220055
--Node: Host Identification1220652
--Node: Hardware/Software Type ID1223871
--Node: System Configuration1226570
--Node: General Limits1228137
--Node: System Options1231776
--Node: Version Supported1235108
--Node: Sysconf1236945
--Node: Sysconf Definition1237581
--Node: Constants for Sysconf1238253
--Node: Examples of Sysconf1241386
--Node: Minimums1242379
--Node: Limits for Files1244455
--Node: Options for Files1247457
--Node: File Minimums1249746
--Node: Pathconf1251408
--Node: Utility Limits1254095
--Node: Utility Minimums1256153
--Node: String Parameters1257905
--Node: Language Features1259959
--Node: Consistency Checking1260890
--Node: Variadic Functions1265528
--Node: Why Variadic1266600
--Node: How Variadic1268565
--Node: Variadic Prototypes1269854
--Node: Receiving Arguments1271012
--Node: How Many Arguments1273726
--Node: Calling Variadics1275397
--Node: Argument Macros1277534
--Node: Variadic Example1279174
--Node: Old Varargs1280326
--Node: Null Pointer Constant1281996
--Node: Important Data Types1283081
--Node: Data Type Measurements1285647
--Node: Width of Type1286504
--Node: Range of Type1287410
--Node: Floating Type Macros1290674
--Node: Floating Point Concepts1291934
--Node: Floating Point Parameters1295669
--Node: IEEE Floating Point1302603
--Node: Structure Measurement1304356
--Node: Library Summary1305051
--Node: Maintenance1410972
--Node: Installation1411717
--Node: Tools for Installation1418563
--Node: Supported Configurations1419651
--Node: Reporting Bugs1421162
--Node: Source Layout1423539
--Node: Porting1427495
--Node: Hierarchy Conventions1435283
--Node: Porting to Unix1440203
--Node: Contributors1442048
--Node: Copying1453346
--Node: Concept Index1480210
--Node: Type Index1530394
--Node: Function Index1535184
--Node: Variable Index1567426
--Node: File Index1598743
--
--End Tag Table
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-1 
glibc-2.0.1/manual/libc.info-1
---- ../glibc-2.0.1/manual/libc.info-1  1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-1     1970-01-01 01:00:00.000000000 +0100
-@@ -1,1089 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
--
--Main Menu
--*********
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta of the GNU C Library.
--
--* Menu:
--
--* Introduction::                Purpose of the GNU C Library.
--* Error Reporting::             How the GNU Library functions report
--                                 error conditions.
--* Memory Allocation::           Your program can allocate memory dynamically
--                                 and manipulate it via pointers.
--* Character Handling::          Character testing and conversion functions.
--* String and Array Utilities::  Utilities for copying and comparing
--                                 strings and arrays.
--* Extended Characters::         Support for extended character sets.
--* Locales::                     The country and language can affect
--                                 the behavior of library functions.
--* Searching and Sorting::       General searching and sorting functions.
--* Pattern Matching::            Matching wildcards and regular expressions,
--                                 and shell-style "word expansion".
--* I/O Overview::                Introduction to the I/O facilities.
--* Streams: I/O on Streams.      High-level, portable I/O facilities.
--* Low-Level I/O::               Low-level, less portable I/O.
--* File System Interface::       Functions for manipulating files.
--* Pipes and FIFOs::             A simple interprocess communication mechanism.
--* Sockets::                     A more complicated interprocess communication
--                                 mechanism, with support for networking.
--* Low-Level Terminal Interface::How to change the characteristics
--                                 of a terminal device.
--* Mathematics::                 Math functions (transcendental functions,
--                                 random numbers, absolute value, etc.).
--* Arithmetic::                  Low-level arithmetic functions.
--* Date and Time::               Functions for getting the date and time,
--                                 and for conversion between formats.
--* Non-Local Exits::             The `setjmp' and `longjmp' facilities.
--* Signal Handling::             All about signals; how to send them,
--                                 block them, and handle them.
--* Process Startup::             Writing the beginning and end of your program.
--* Processes::                   How to create processes and run other 
programs.
--* Job Control::                 All about process groups and sessions.
--* Name Service Switch::         Accessing the various system databases.
--* Users and Groups::            How users are identified and classified.
--* System Information::          Getting information about the
--                                 hardware and software configuration
--                                 of the machine a program runs on.
--* System Configuration::        Parameters describing operating system limits.
--
--Appendices
--
--* Language Features::           C language features provided by the library.
--
--* Library Summary::             A summary showing the syntax, header file,
--                                 and derivation of each library feature.
--* Maintenance::                 How to install and maintain the GNU C Library.
--* Copying::                     The GNU Library General Public License says
--                                 how you can copy and share the GNU C Library.
--
--Indices
--
--* Concept Index::               Index of concepts and names.
--* Type Index::                  Index of types and type qualifiers.
--* Function Index::              Index of functions and function-like macros.
--* Variable Index::              Index of variables and variable-like macros.
--* File Index::                  Index of programs and files.
--
-- -- The Detailed Node Listing --
--
--Introduction
--
--* Getting Started::             Getting Started
--* Standards and Portability::   Standards and Portability
--* Using the Library::           Using the Library
--* Roadmap to the Manual::       Roadmap to the Manual
--
--Standards and Portability
--
--* ISO C::                       The American National Standard for the
--                                 C programming language.
--* POSIX::                       The ISO/IEC 9945 (aka IEEE 1003) standards
--                                 for operating systems.
--* Berkeley Unix::               BSD and SunOS.
--* SVID::                        The System V Interface Description.
--
--Using the Library
--
--* Header Files::                How to use the header files in your programs.
--* Macro Definitions::           Some functions in the library may really
--                                 be implemented as macros.
--* Reserved Names::              The C standard reserves some names for
--                                 the library, and some for users.
--* Feature Test Macros::         How to control what names are defined.
--
--Error Reporting
--
--* Checking for Errors::         How errors are reported by library functions.
--* Error Codes::                 What all the error codes are.
--* Error Messages::              Mapping error codes onto error messages.
--
--Memory Allocation
--
--* Memory Concepts::             An introduction to concepts and terminology.
--* Dynamic Allocation and C::    How to get different kinds of allocation in C.
--* Unconstrained Allocation::    The `malloc' facility allows fully general
--                                 dynamic allocation.
--* Obstacks::                    Obstacks are less general than malloc
--                                 but more efficient and convenient.
--* Variable Size Automatic::     Allocation of variable-sized blocks
--                                 of automatic storage that are freed when the
--                                 calling function returns.
--* Relocating Allocator::        Waste less memory, if you can tolerate
--                                 automatic relocation of the blocks you get.
--* Memory Warnings::             Getting warnings when memory is nearly full.
--
--Unconstrained Allocation
--
--* Basic Allocation::            Simple use of `malloc'.
--* Malloc Examples::             Examples of `malloc'.  `xmalloc'.
--* Freeing after Malloc::        Use `free' to free a block you
--                                 got with `malloc'.
--* Changing Block Size::         Use `realloc' to make a block
--                                 bigger or smaller.
--* Allocating Cleared Space::    Use `calloc' to allocate a
--                                 block and clear it.
--* Efficiency and Malloc::       Efficiency considerations in use of
--                                 these functions.
--* Aligned Memory Blocks::       Allocating specially aligned memory:
--                                 `memalign' and `valloc'.
--* Heap Consistency Checking::   Automatic checking for errors.
--* Hooks for Malloc::            You can use these hooks for debugging
--                               programs that use `malloc'.
--* Statistics of Malloc::        Getting information about how much
--                               memory your program is using.
--* Summary of Malloc::           Summary of `malloc' and related functions.
--
--Obstacks
--
--* Creating Obstacks::         How to declare an obstack in your program.
--* Preparing for Obstacks::    Preparations needed before you can
--                               use obstacks.
--* Allocation in an Obstack::    Allocating objects in an obstack.
--* Freeing Obstack Objects::     Freeing objects in an obstack.
--* Obstack Functions::         The obstack functions are both
--                               functions and macros.
--* Growing Objects::             Making an object bigger by stages.
--* Extra Fast Growing::                Extra-high-efficiency (though more
--                               complicated) growing objects.
--* Status of an Obstack::        Inquiries about the status of an obstack.
--* Obstacks Data Alignment::     Controlling alignment of objects in obstacks.
--* Obstack Chunks::              How obstacks obtain and release chunks.
--                              Efficiency considerations.
--* Summary of Obstacks::
--
--Automatic Storage with Variable Size
--
--* Alloca Example::              Example of using `alloca'.
--* Advantages of Alloca::        Reasons to use `alloca'.
--* Disadvantages of Alloca::     Reasons to avoid `alloca'.
--* GNU C Variable-Size Arrays::  Only in GNU C, here is an alternative
--                               method of allocating dynamically and
--                               freeing automatically.
--Relocating Allocator
--
--* Relocator Concepts::                How to understand relocating allocation.
--* Using Relocator::           Functions for relocating allocation.
--
--Character Handling
--
--* Classification of Characters::Testing whether characters are
--                                 letters, digits, punctuation, etc.
--* Case Conversion::             Case mapping, and the like.
--
--String and Array Utilities
--
--* Representation of Strings::   Introduction to basic concepts.
--* String/Array Conventions::    Whether to use a string function or an
--                               arbitrary array function.
--* String Length::               Determining the length of a string.
--* Copying and Concatenation::   Functions to copy the contents of strings
--                               and arrays.
--* String/Array Comparison::     Functions for byte-wise and character-wise
--                               comparison.
--* Collation Functions::         Functions for collating strings.
--* Search Functions::            Searching for a specific element or substring.
--* Finding Tokens in a String::  Splitting a string into tokens by looking
--                               for delimiters.
--
--Extended Characters
--
--* Extended Char Intro::         Multibyte codes versus wide characters.
--* Locales and Extended Chars::  The locale selects the character codes.
--* Multibyte Char Intro::        How multibyte codes are represented.
--* Wide Char Intro::             How wide characters are represented.
--* Wide String Conversion::      Converting wide strings to multibyte code
--                                   and vice versa.
--* Length of Char::              how many bytes make up one multibyte char.
--* Converting One Char::         Converting a string character by character.
--* Example of Conversion::       Example showing why converting
--                                 one character at a time may be useful.
--* Shift State::                 Multibyte codes with "shift characters".
--
--Locales and Internationalization
--
--* Effects of Locale::           Actions affected by the choice of locale.
--* Choosing Locale::             How the user specifies a locale.
--* Locale Categories::           Different purposes for which
--                                 you can select a locale.
--* Setting the Locale::          How a program specifies the locale.
--* Standard Locales::            Locale names available on all systems.
--* Numeric Formatting::          How to format numbers for the chosen locale.
--
--Searching and Sorting
--
--* Comparison Functions::        Defining how to compare two objects.
--                              Since the sort and search facilities are
--                              general, you have to specify the ordering.
--* Array Search Function::       The `bsearch' function.
--* Array Sort Function::         The `qsort' function.
--* Search/Sort Example::         An example program.
--
--Pattern Matching
--
--* Wildcard Matching::    Matching a wildcard pattern against a single string.
--* Globbing::             Finding the files that match a wildcard pattern.
--* Regular Expressions::  Matching regular expressions against strings.
--* Word Expansion::       Expanding shell variables, nested commands,
--                          arithmetic, and wildcards.
--                        This is what the shell does with shell commands.
--
--I/O Overview
--
--* I/O Concepts::                Some basic information and terminology.
--* File Names::                  How to refer to a file.
--
--I/O Concepts
--
--* Streams and File Descriptors:: The GNU Library provides two ways
--                                  to access the contents of files.
--* File Position::               The number of bytes from the
--                                 beginning of the file.
--
--File Names
--
--* Directories::                 Directories contain entries for files.
--* File Name Resolution::        A file name specifies how to look up a file.
--* File Name Errors::            Error conditions relating to file names.
--* File Name Portability::       File name portability and syntax issues.
--
--I/O on Streams
--
--* Streams::                     About the data type representing a stream.
--* Standard Streams::            Streams to the standard input and output
--                                 devices are created for you.
--* Opening Streams::             How to create a stream to talk to a file.
--* Closing Streams::             Close a stream when you are finished with it.
--* Simple Output::               Unformatted output by characters and lines.
--* Character Input::             Unformatted input by characters and words.
--* Line Input::                  Reading a line or a record from a stream.
--* Unreading::                   Peeking ahead/pushing back input just read.
--* Formatted Output::            `printf' and related functions.
--* Customizing Printf::          You can define new conversion specifiers for
--                                 `printf' and friends.
--* Formatted Input::             `scanf' and related functions.
--* Block Input/Output::          Input and output operations on blocks of data.
--* EOF and Errors::              How you can tell if an I/O error happens.
--* Binary Streams::              Some systems distinguish between text files
--                                 and binary files.
--* File Positioning::            About random-access streams.
--* Portable Positioning::        Random access on peculiar ISO C systems.
--* Stream Buffering::            How to control buffering of streams.
--* Temporary Files::             How to open a temporary file.
--* Other Kinds of Streams::      Other Kinds of Streams
--
--Unreading
--
--* Unreading Idea::              An explanation of unreading with pictures.
--* How Unread::                  How to call `ungetc' to do unreading.
--
--Formatted Output
--
--* Formatted Output Basics::     Some examples to get you started.
--* Output Conversion Syntax::    General syntax of conversion specifications.
--* Table of Output Conversions:: Summary of output conversions, what they do.
--* Integer Conversions::         Details of formatting integers.
--* Floating-Point Conversions::  Details of formatting floating-point numbers.
--* Other Output Conversions::    Details about formatting of strings,
--                                 characters, pointers, and the like.
--* Formatted Output Functions::  Descriptions of the actual functions.
--* Variable Arguments Output::   `vprintf' and friends.
--* Parsing a Template String::   What kinds of arguments does
--                                 a given template call for?
--
--Customizing Printf
--
--* Registering New Conversions::
--* Conversion Specifier Options::
--* Defining the Output Handler::
--* Printf Extension Example::
--
--Formatted Input
--
--* Formatted Input Basics::      Some basics to get you started.
--* Input Conversion Syntax::     Syntax of conversion specifications.
--* Table of Input Conversions::  Summary of input conversions and what they do.
--* Numeric Input Conversions::   Details of conversions for reading numbers.
--* String Input Conversions::    Details of conversions for reading strings.
--* Other Input Conversions::     Details of miscellaneous other conversions.
--* Formatted Input Functions::   Descriptions of the actual functions.
--* Variable Arguments Input::    `vscanf' and friends.
--
--Stream Buffering
--
--* Buffering Concepts::          Terminology is defined here.
--* Flushing Buffers::            How to ensure that output buffers are flushed.
--* Controlling Buffering::       How to specify what kind of buffering to use.
--
--Other Kinds of Streams
--
--* String Streams::
--* Custom Streams::
--
--Programming Your Own Custom Streams
--
--* Streams and Cookies::
--* Hook Functions::
--
--Low-Level I/O
--
--* Opening and Closing Files::   How to open and close file descriptors.
--* I/O Primitives::              Reading and writing data.
--* File Position Primitive::     Setting a descriptor's file position.
--* Descriptors and Streams::     Converting descriptor to stream or vice-versa.
--* Stream/Descriptor Precautions::  Precautions needed if you use both
--                                    descriptors and streams.
--* Waiting for I/O::             How to check for input or output
--                                 on multiple file descriptors.
--* Control Operations::          Various other operations on file descriptors.
--* Duplicating Descriptors::     Fcntl commands for duplicating descriptors.
--* Descriptor Flags::            Fcntl commands for manipulating flags
--                                 associated with file descriptors.
--* File Status Flags::           Fcntl commands for manipulating flags
--                                 associated with open files.
--* File Locks::                  Fcntl commands for implementing file locking.
--* Interrupt Input::             Getting a signal when input arrives.
--
--File System Interface
--
--* Working Directory::           This is used to resolve relative file names.
--* Accessing Directories::       Finding out what files a directory contains.
--* Hard Links::                  Adding alternate names to a file.
--* Symbolic Links::              A file that "points to" a file name.
--* Deleting Files::              How to delete a file, and what that means.
--* Renaming Files::              Changing a file's name.
--* Creating Directories::        A system call just for creating a directory.
--* File Attributes::             Attributes of individual files.
--* Making Special Files::        How to create special files.
--
--Accessing Directories
--
--* Directory Entries::           Format of one directory entry.
--* Opening a Directory::         How to open a directory stream.
--* Reading/Closing Directory::   How to read directory entries from the stream.
--* Simple Directory Lister::     A very simple directory listing program.
--* Random Access Directory::     Rereading part of the directory
--                                  already read with the same stream.
--
--File Attributes
--
--* Attribute Meanings::          The names of the file attributes,
--                                 and what their values mean.
--* Reading Attributes::          How to read the attributes of a file.
--* Testing File Type::           Distinguishing ordinary files,
--                                 directories, links...
--* File Owner::                  How ownership for new files is determined,
--                                 and how to change it.
--* Permission Bits::             How information about a file's access mode
--                                 is stored.
--* Access Permission::           How the system decides who can access a file.
--* Setting Permissions::         How permissions for new files are assigned,
--                                 and how to change them.
--* Testing File Access::         How to find out if your process can
--                                 access a file.
--* File Times::                  About the time attributes of a file.
--
--Pipes and FIFOs
--
--* Creating a Pipe::             Making a pipe with the `pipe' function.
--* Pipe to a Subprocess::        Using a pipe to communicate with a child.
--* FIFO Special Files::          Making a FIFO special file.
--
--Sockets
--
--* Socket Concepts::             Basic concepts you need to know about.
--* Communication Styles::        Stream communication, datagrams, and others.
--* Socket Addresses::            How socket names ("addresses") work.
--* File Namespace::              Details about the file namespace.
--* Internet Namespace::          Details about the Internet namespace.
--* Open/Close Sockets::          Creating sockets and destroying them.
--* Connections::                 Operations on sockets with connection state.
--* Datagrams::                   Operations on datagram sockets.
--* Socket Options::              Miscellaneous low-level socket options.
--* Networks Database::           Accessing the database of network names.
--
--Socket Addresses
--
--* Address Formats::             About `struct sockaddr'.
--* Setting Address::             Binding an address to a socket.
--* Reading Address::             Reading the address of a socket.
--
--Internet Domain
--
--* Internet Address Format::     How socket addresses are specified in the
--                                 Internet namespace.
--* Host Addresses::              All about host addresses of Internet hosts.
--* Protocols Database::          Referring to protocols by name.
--* Services Database::           Ports may have symbolic names.
--* Byte Order::                  Different hosts may use different byte
--                                 ordering conventions; you need to
--                                 canonicalize host address and port number.
--* Inet Example::                Putting it all together.
--
--Host Addresses
--
--* Abstract Host Addresses::             What a host number consists of.
--* Data type: Host Address Data Type.    Data type for a host number.
--* Functions: Host Address Functions.    Functions to operate on them.
--* Names: Host Names.                    Translating host names to host 
numbers.
--
--Open/Close Sockets
--
--* Creating a Socket::           How to open a socket.
--* Closing a Socket::            How to close a socket.
--* Socket Pairs::                These are created like pipes.
--
--Connections
--
--* Connecting::                  What the client program must do.
--* Listening::                   How a server program waits for requests.
--* Accepting Connections::       What the server does when it gets a request.
--* Who is Connected::            Getting the address of the
--                                 other side of a connection.
--* Transferring Data::           How to send and receive data.
--* Byte Stream Example::         An example client for communicating over a
--                                 byte stream socket in the Internet namespace.
--* Server Example::              A corresponding server program.
--* Out-of-Band Data::            This is an advanced feature.
--
--Transferring Data
--
--* Sending Data::                Sending data with `write'.
--* Receiving Data::              Reading data with `read'.
--* Socket Data Options::         Using `send' and `recv'.
--
--Datagrams
--
--* Sending Datagrams::           Sending packets on a datagram socket.
--* Receiving Datagrams::         Receiving packets on a datagram socket.
--* Datagram Example::            An example program: packets sent over a
--                                 datagram stream in the file namespace.
--* Example Receiver::            Another program, that receives those packets.
--
--Socket Options
--
--* Socket Option Functions::     The basic functions for setting and getting
--                                 socket options.
--* Socket-Level Options::        Details of the options at the socket level.
--
--Low-Level Terminal Interface
--
--* Is It a Terminal::            How to determine if a file is a terminal
--                                 device, and what its name is.
--* I/O Queues::                  About flow control and typeahead.
--* Canonical or Not::            Two basic styles of input processing.
--* Terminal Modes::              How to examine and modify flags controlling
--                                 terminal I/O: echoing, signals, editing.
--* Line Control::                Sending break sequences, clearing  buffers...
--* Noncanon Example::            How to read single characters without echo.
--
--Terminal Modes
--
--* Mode Data Types::             The data type `struct termios' and related 
types.
--* Mode Functions::              Functions to read and set terminal attributes.
--* Setting Modes::               The right way to set attributes reliably.
--* Input Modes::                 Flags controlling low-level input handling.
--* Output Modes::                Flags controlling low-level output handling.
--* Control Modes::               Flags controlling serial port behavior.
--* Local Modes::                 Flags controlling high-level input handling.
--* Line Speed::                  How to read and set the terminal line speed.
--* Special Characters::          Characters that have special effects,
--                                 and how to change them.
--* Noncanonical Input::          Controlling how long to wait for input.
--
--Special Characters
--
--* Editing Characters::
--* Signal Characters::
--* Start/Stop Characters::
--
--Mathematics
--
--* Domain and Range Errors::     How overflow conditions and the
--                                 like are reported.
--* Not a Number::                Making NANs and testing for NANs.
--* Trig Functions::              Sine, cosine, and tangent.
--* Inverse Trig Functions::      Arc sine, arc cosine, and arc tangent.
--* Exponents and Logarithms::    Also includes square root.
--* Hyperbolic Functions::        Hyperbolic sine and friends.
--* Pseudo-Random Numbers::       Functions for generating pseudo-random 
numbers.
--* Absolute Value::              Absolute value functions.
--
--Pseudo-Random Numbers
--
--* ISO Random::                  `rand' and friends.
--* BSD Random::                  `random' and friends.
--
--Low-Level Arithmetic Functions
--
--* Normalization Functions::     Hacks for radix-2 representations.
--* Rounding and Remainders::     Determining the integer and
--                                 fractional parts of a float.
--* Integer Division::            Functions for performing integer division.
--* Parsing of Numbers::          Functions for "reading" numbers from strings.
--* Predicates on Floats::        Some miscellaneous test functions.
--
--Parsing of Numbers
--
--* Parsing of Integers::         Functions for conversion of integer values.
--* Parsing of Floats::           Functions for conversion of floating-point.
--
--Date and Time
--
--* Processor Time::              Measures processor time used by a program.
--* Calendar Time::               Manipulation of "real" dates and times.
--* Setting an Alarm::            Sending a signal after a specified time.
--* Sleeping::                    Waiting for a period of time.
--
--Processor Time
--
--* Basic CPU Time::              The `clock' function.
--* Detailed CPU Time::           The `times' function.
--
--Calendar Time
--
--* Simple Calendar Time::        Facilities for manipulating calendar time.
--* High-Resolution Calendar::    A time representation with greater precision.
--* Broken-down Time::            Facilities for manipulating local time.
--* Formatting Date and Time::    Converting times to strings.
--* TZ Variable::                 How users specify the time zone.
--* Time Zone Functions::         Functions to examine or specify the time zone.
--* Time Functions Example::      An example program showing use of some of
--                                 the time functions.
--
--Signal Handling
--
--* Concepts of Signals::         Introduction to the signal facilities.
--* Standard Signals::            Particular kinds of signals with standard
--                                 names and meanings.
--* Signal Actions::              Specifying what happens when a particular
--                                 signal is delivered.
--* Defining Handlers::           How to write a signal handler function.
--* Generating Signals::          How to send a signal to a process.
--* Blocking Signals::            Making the system hold signals temporarily.
--* Waiting for a Signal::        Suspending your program until a signal 
arrives.
--* Signal Stack::                Using a Separate Signal Stack
--* BSD Signal Handling::         Additional functions for backward
--                                 compatibility with BSD.
--
--Basic Concepts of Signals
--
--* Kinds of Signals::            Some examples of what can cause a signal.
--* Signal Generation::           Concepts of why and how signals occur.
--* Delivery of Signal::          Concepts of what a signal does to the process.
--
--Standard Signals
--
--* Program Error Signals::       Used to report serious program errors.
--* Termination Signals::         Used to interrupt and/or terminate the 
program.
--* Alarm Signals::               Used to indicate expiration of timers.
--* Asynchronous I/O Signals::    Used to indicate input is available.
--* Job Control Signals::         Signals used to support job control.
--* Operation Error Signals::     Used to report operational system errors.
--* Miscellaneous Signals::       Miscellaneous Signals.
--* Signal Messages::             Printing a message describing a signal.
--
--Specifying Signal Actions
--
--* Basic Signal Handling::       The simple `signal' function.
--* Advanced Signal Handling::    The more powerful `sigaction' function.
--* Signal and Sigaction::        How those two functions interact.
--* Sigaction Function Example::  An example of using the sigaction function.
--* Flags for Sigaction::         Specifying options for signal handling.
--* Initial Signal Actions::      How programs inherit signal actions.
--
--Defining Signal Handlers
--
--* Handler Returns::
--* Termination in Handler::
--* Longjmp in Handler::
--* Signals in Handler::
--* Nonreentrancy::
--* Atomic Data Access::
--
--Generating Signals
--
--* Signaling Yourself::          Signaling Yourself
--* Signaling Another Process::   Send a signal to another process.
--* Permission for kill::         Permission for using `kill'
--* Kill Example::                Using `kill' for Communication
--
--Blocking Signals
--
--* Why Block::                   The purpose of blocking signals.
--* Signal Sets::                 How to specify which signals to block.
--* Process Signal Mask::         Blocking delivery of signals to your
--                                 process during normal execution.
--* Testing for Delivery::        Blocking to Test for Delivery of a Signal
--* Blocking for Handler::        Blocking additional signals while a
--                                 handler is being run.
--* Checking for Pending Signals::Checking for Pending Signals
--* Remembering a Signal::        How you can get almost the same effect
--                                 as blocking a signal, by handling it
--                                 and setting a flag to be tested later.
--
--Waiting for a Signal
--
--* Using Pause::                 The simple way, using `pause'.
--* Pause Problems::              Why the simple way is often not very good.
--* Sigsuspend::                  Reliably waiting for a specific signal.
--
--BSD Signal Handling
--
--* BSD Handler::                 BSD Function to Establish a Handler.
--* Blocking in BSD::             BSD Functions for Blocking Signals
--
--Process Startup and Termination
--
--* Program Arguments::           Parsing your program's command-line arguments.
--* Environment Variables::       How to access parameters inherited from
--                                 a parent process.
--* Program Termination::         How to cause a process to terminate and
--                                 return status information to its parent.
--
--Program Arguments
--
--* Argument Syntax::             By convention, options start with a hyphen.
--* Parsing Options::             The `getopt' function.
--* Example of Getopt::           An example of parsing options with `getopt'.
--* Long Options::                GNU utilities should accept long-named 
options.
--                                 Here is how to do that.
--* Long Option Example::         An example of using `getopt_long'.
--
--Environment Variables
--
--* Environment Access::          How to get and set the values of
--                                 environment variables.
--* Standard Environment::        These environment variables have
--                                 standard interpretations.
--
--Program Termination
--
--* Normal Termination::          If a program calls `exit', a
--                                 process terminates normally.
--* Exit Status::                 The `exit status' provides information
--                                 about why the process terminated.
--* Cleanups on Exit::            A process can run its own cleanup
--                                 functions upon normal termination.
--* Aborting a Program::          The `abort' function causes
--                                 abnormal program termination.
--* Termination Internals::       What happens when a process terminates.
--
--
--Child Processes
--
--* Running a Command::           The easy way to run another program.
--* Process Creation Concepts::   An overview of the hard way to do it.
--* Process Identification::      How to get the process ID of a process.
--* Creating a Process::          How to fork a child process.
--* Executing a File::            How to make a child execute another program.
--* Process Completion::          How to tell when a child process has 
completed.
--* Process Completion Status::   How to interpret the status value
--                                 returned from a child process.
--* BSD Wait Functions::          More functions, for backward compatibility.
--* Process Creation Example::    A complete example program.
--
--Job Control
--
--* Concepts of Job Control ::    Concepts of Job Control
--* Job Control is Optional::     Not all POSIX systems support job control.
--* Controlling Terminal::        How a process gets its controlling terminal.
--* Access to the Terminal::      How processes share the controlling terminal.
--* Orphaned Process Groups::     Jobs left after the user logs out.
--* Implementing a Shell::        What a shell must do to implement job control.
--* Functions for Job Control::   Functions to control process groups.
--
--Implementing a Job Control Shell
--
--* Data Structures::             Introduction to the sample shell.
--* Initializing the Shell::      What the shell must do to take
--                                 responsibility for job control.
--* Launching Jobs::              Creating jobs to execute commands.
--* Foreground and Background::   Putting a job in foreground of background.
--* Stopped and Terminated Jobs:: Reporting job status.
--* Continuing Stopped Jobs::     How to continue a stopped job in
--                                 the foreground or background.
--* Missing Pieces::              Other parts of the shell.
--
--Functions for Job Control
--
--* Identifying the Terminal::    Determining the controlling terminal's name.
--* Process Group Functions::     Functions for manipulating process groups.
--* Terminal Access Functions::   Functions for controlling terminal access.
--
--Name Service Switch
--
--* NSS Basics::                  What is this NSS good for.
--* NSS Configuration File::      Configuring NSS.
--* NSS Module Internals::        How does it work internally.
--* Extending NSS::               What to do to add services or databases.
--
--Users and Groups
--
--* User and Group IDs::          Each user and group has a unique numeric ID.
--* Process Persona::             The user IDs and group IDs of a process.
--* Why Change Persona::          Why a program might need to change
--                                 its user and/or group IDs.
--* How Change Persona::          Restrictions on changing user and group IDs.
--* Reading Persona::             Examining the process's user and group IDs.
--* Setting User ID::
--* Setting Groups::
--* Enable/Disable Setuid::
--* Setuid Program Example::      Setuid Program Example
--* Tips for Setuid::
--* Who Logged In::               Getting the name of the user who logged in,
--                                 or of the real user ID of the current 
process.
--
--* User Database::               Functions and data structures for
--                                 accessing the user database.
--* Group Database::              Functions and data structures for
--                                 accessing the group database.
--* Database Example::            Example program showing use of database
--                                 inquiry functions.
--
--User Database
--
--* User Data Structure::
--* Lookup User::
--* Scanning All Users::          Scanning the List of All Users
--* Writing a User Entry::
--
--Group Database
--
--* Group Data Structure::
--* Lookup Group::
--* Scanning All Groups::         Scanning the List of All Groups
--
--System Information
--
--* Host Identification::         Determining the name of the machine.
--* Hardware/Software Type ID::   Determining the hardware type and
--                                 operating system type.
--
--System Configuration Limits
--
--* General Limits::            Constants and functions that describe
--                               various process-related limits that have
--                               one uniform value for any given machine.
--* System Options::            Optional POSIX features.
--* Version Supported::         Version numbers of POSIX.1 and POSIX.2.
--* Sysconf::                   Getting specific configuration values
--                               of general limits and system options.
--* Minimums::                  Minimum values for general limits.
--
--* Limits for Files::          Size limitations on individual files.
--                               These can vary between file systems
--                                or even from file to file.
--* Options for Files::         Optional features that some files may support.
--* File Minimums::             Minimum values for file limits.
--* Pathconf::                  Getting the limit values for a particular file.
--
--* Utility Limits::            Capacity limits of POSIX.2 utility programs.
--* Utility Minimums::          Minimum allowable values of those limits.
--
--* String Parameters::         Getting the default search path.
--
--Library Facilities that are Part of the C Language
--
--* Consistency Checking::        Using `assert' to abort
--                               if something "impossible" happens.
--* Variadic Functions::          Defining functions with varying
--                                 numbers of arguments.
--* Null Pointer Constant::       The macro `NULL'.
--* Important Data Types::        Data types for object sizes.
--* Data Type Measurements::      Parameters of data type representations.
--
--Variadic Functions
--
--* Why Variadic::                Reasons for making functions take
--                                 variable arguments.
--* How Variadic::                How to define and call variadic functions.
--* Argument Macros::             Detailed specification of the macros
--                               for accessing variable arguments.
--* Variadic Example::            A complete example.
--
--How Variadic Functions are Defined and Used
--
--* Variadic Prototypes::         How to make a prototype for a function
--                               with variable arguments.
--* Receiving Arguments::               Steps you must follow to access the
--                               optional argument values.
--* How Many Arguments::          How to decide whether there are more 
arguments.
--* Calling Variadics::         Things you need to know about calling
--                               variable arguments functions.
--
--Data Type Measurements
--
--* Width of Type::             How many bits does an integer type hold?
--* Range of Type::             What are the largest and smallest values
--                               that an integer type can hold?
--* Floating Type Macros::        Parameters that measure floating-point types.
--* Structure Measurement::       Getting measurements on structure types.
--
--Floating Type Macros
--
--* Floating Point Concepts::     Definitions of terminology.
--* Floating Point Parameters::   Dimensions, limits of floating point types.
--* IEEE Floating Point::         How one common representation is described.
--
--Library Maintenance
--
--* Installation::                How to configure, compile and install
--                                 the GNU C library.
--* Reporting Bugs::              How to report bugs (if you want to
--                                 get them fixed) and other troubles
--                                 you may have with the GNU C library.
--* Porting::                     How to port the GNU C library to
--                                 a new machine or operating system.
--* Contributors::              Who wrote what parts of the GNU C Library.
--
--Porting the GNU C Library
--
--* Hierarchy Conventions::       How the `sysdeps' hierarchy is
--                                 layed out.
--* Porting to Unix::             Porting the library to an average
--                                 Unix-like system.
--
--
--File: libc.info,  Node: Introduction,  Next: Error Reporting,  Prev: Top,  
Up: Top
--
--Introduction
--************
--
--   The C language provides no built-in facilities for performing such
--common operations as input/output, memory management, string
--manipulation, and the like.  Instead, these facilities are defined in a
--standard "library", which you compile and link with your programs.
--
--   The GNU C library, described in this document, defines all of the
--library functions that are specified by the ISO C standard, as well as
--additional features specific to POSIX and other derivatives of the Unix
--operating system, and extensions specific to the GNU system.
--
--   The purpose of this manual is to tell you how to use the facilities
--of the GNU library.  We have mentioned which features belong to which
--standards to help you identify things that are potentially nonportable
--to other systems.  But the emphasis in this manual is not on strict
--portability.
--
--* Menu:
--
--* Getting Started::             What this manual is for and how to use it.
--* Standards and Portability::   Standards and sources upon which the GNU
--                                 C library is based.
--* Using the Library::           Some practical uses for the library.
--* Roadmap to the Manual::       Overview of the remaining chapters in
--                                 this manual.
--
--
--File: libc.info,  Node: Getting Started,  Next: Standards and Portability,  
Up: Introduction
--
--Getting Started
--===============
--
--   This manual is written with the assumption that you are at least
--somewhat familiar with the C programming language and basic programming
--concepts.  Specifically, familiarity with ISO standard C (*note ISO
--C::.), rather than "traditional" pre-ISO C dialects, is assumed.
--
--   The GNU C library includes several "header files", each of which
--provides definitions and declarations for a group of related facilities;
--this information is used by the C compiler when processing your program.
--For example, the header file `stdio.h' declares facilities for
--performing input and output, and the header file `string.h' declares
--string processing utilities.  The organization of this manual generally
--follows the same division as the header files.
--
--   If you are reading this manual for the first time, you should read
--all of the introductory material and skim the remaining chapters.
--There are a *lot* of functions in the GNU C library and it's not
--realistic to expect that you will be able to remember exactly *how* to
--use each and every one of them.  It's more important to become
--generally familiar with the kinds of facilities that the library
--provides, so that when you are writing your programs you can recognize
--*when* to make use of library functions, and *where* in this manual you
--can find more specific information about them.
--
--
--File: libc.info,  Node: Standards and Portability,  Next: Using the Library,  
Prev: Getting Started,  Up: Introduction
--
--Standards and Portability
--=========================
--
--   This section discusses the various standards and other sources that
--the GNU C library is based upon.  These sources include the ISO C and
--POSIX standards, and the System V and Berkeley Unix implementations.
--
--   The primary focus of this manual is to tell you how to make effective
--use of the GNU library facilities.  But if you are concerned about
--making your programs compatible with these standards, or portable to
--operating systems other than GNU, this can affect how you use the
--library.  This section gives you an overview of these standards, so that
--you will know what they are when they are mentioned in other parts of
--the manual.
--
--   *Note Library Summary::, for an alphabetical list of the functions
--and other symbols provided by the library.  This list also states which
--standards each function or symbol comes from.
--
--* Menu:
--
--* ISO C::                      The international standard for the C
--                                 programming language.
--* POSIX::                       The ISO/IEC 9945 (aka IEEE 1003) standards
--                                 for operating systems.
--* Berkeley Unix::               BSD and SunOS.
--* SVID::                        The System V Interface Description.
--
--
--File: libc.info,  Node: ISO C,  Next: POSIX,  Up: Standards and Portability
--
--ISO C
-------
--
--   The GNU C library is compatible with the C standard adopted by the
--American National Standards Institute (ANSI): `American National
--Standard X3.159-1989--"ANSI C"' and later by the International
--Standardization Organization (ISO): `ISO/IEC 9899:1990, "Programming
--languages--C"'.  We here refer to the standard as ISO C since this is
--the more general standard in respect of ratification.  The header files
--and library facilities that make up the GNU library are a superset of
--those specified by the ISO C standard.
--
--   If you are concerned about strict adherence to the ISO C standard,
--you should use the `-ansi' option when you compile your programs with
--the GNU C compiler.  This tells the compiler to define *only* ISO
--standard features from the library header files, unless you explicitly
--ask for additional features.  *Note Feature Test Macros::, for
--information on how to do this.
--
--   Being able to restrict the library to include only ISO C features is
--important because ISO C puts limitations on what names can be defined
--by the library implementation, and the GNU extensions don't fit these
--limitations.  *Note Reserved Names::, for more information about these
--restrictions.
--
--   This manual does not attempt to give you complete details on the
--differences between ISO C and older dialects.  It gives advice on how
--to write programs to work portably under multiple C dialects, but does
--not aim for completeness.
--
--
--File: libc.info,  Node: POSIX,  Next: Berkeley Unix,  Prev: ISO C,  Up: 
Standards and Portability
--
--POSIX (The Portable Operating System Interface)
-------------------------------------------------
--
--   The GNU library is also compatible with the IEEE "POSIX" family of
--standards, known more formally as the "Portable Operating System
--Interface for Computer Environments".  POSIX is derived mostly from
--various versions of the Unix operating system.
--
--   The library facilities specified by the POSIX standards are a
--superset of those required by ISO C; POSIX specifies additional
--features for ISO C functions, as well as specifying new additional
--functions.  In general, the additional requirements and functionality
--defined by the POSIX standards are aimed at providing lower-level
--support for a particular kind of operating system environment, rather
--than general programming language support which can run in many diverse
--operating system environments.
--
--   The GNU C library implements all of the functions specified in `IEEE
--Std 1003.1-1990, the POSIX System Application Program Interface',
--commonly referred to as POSIX.1.  The primary extensions to the ISO C
--facilities specified by this standard include file system interface
--primitives (*note File System Interface::.), device-specific terminal
--control functions (*note Low-Level Terminal Interface::.), and process
--control functions (*note Processes::.).
--
--   Some facilities from `IEEE Std 1003.2-1992, the POSIX Shell and
--Utilities standard' (POSIX.2) are also implemented in the GNU library.
--These include utilities for dealing with regular expressions and other
--pattern matching facilities (*note Pattern Matching::.).
--
--
--File: libc.info,  Node: Berkeley Unix,  Next: SVID,  Prev: POSIX,  Up: 
Standards and Portability
--
--Berkeley Unix
---------------
--
--   The GNU C library defines facilities from some versions of Unix which
--are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD,
--and 4.4 BSD Unix systems (also known as "Berkeley Unix") and from
--"SunOS" (a popular 4.2 BSD derivative that includes some Unix System V
--functionality).  These systems support most of the ISO C and POSIX
--facilities, and 4.4 BSD and newer releases of SunOS in fact support
--them all.
--
--   The BSD facilities include symbolic links (*note Symbolic Links::.),
--the `select' function (*note Waiting for I/O::.), the BSD signal
--functions (*note BSD Signal Handling::.), and sockets (*note
--Sockets::.).
--
--
--File: libc.info,  Node: SVID,  Prev: Berkeley Unix,  Up: Standards and 
Portability
--
--SVID (The System V Interface Description)
-------------------------------------------
--
--   The "System V Interface Description" (SVID) is a document describing
--the AT&T Unix System V operating system.  It is to some extent a
--superset of the POSIX standard (*note POSIX::.).
--
--   The GNU C library defines some of the facilities required by the SVID
--that are not also required by the ISO C or POSIX standards, for
--compatibility with  System V Unix and other Unix systems (such as
--SunOS) which include these facilities.  However, many of the more
--obscure and less generally useful facilities required by the SVID are
--not included.  (In fact, Unix System V itself does not provide them
--all.)
--
--
--File: libc.info,  Node: Using the Library,  Next: Roadmap to the Manual,  
Prev: Standards and Portability,  Up: Introduction
--
--Using the Library
--=================
--
--   This section describes some of the practical issues involved in using
--the GNU C library.
--
--* Menu:
--
--* Header Files::                How to include the header files in your
--                                 programs.
--* Macro Definitions::           Some functions in the library may really
--                                 be implemented as macros.
--* Reserved Names::              The C standard reserves some names for
--                                 the library, and some for users.
--* Feature Test Macros::         How to control what names are defined.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-10 
glibc-2.0.1/manual/libc.info-10
---- ../glibc-2.0.1/manual/libc.info-10 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-10    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1251 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Operating Modes,  Next: Getting File Status Flags,  
Prev: Open-time Flags,  Up: File Status Flags
--
--I/O Operating Modes
---------------------
--
--   The operating modes affect how input and output operations using a
--file descriptor work.  These flags are set by `open' and can be fetched
--and changed with `fcntl'.
--
-- - Macro: int O_APPEND
--     The bit that enables append mode for the file.  If set, then all
--     `write' operations write the data at the end of the file, extending
--     it, regardless of the current file position.  This is the only
--     reliable way to append to a file.  In append mode, you are
--     guaranteed that the data you write will always go to the current
--     end of the file, regardless of other processes writing to the
--     file.  Conversely, if you simply set the file position to the end
--     of file and write, then another process can extend the file after
--     you set the file position but before you write, resulting in your
--     data appearing someplace before the real end of file.
--
-- - Macro: int O_NONBLOCK
--     The bit that enables nonblocking mode for the file.  If this bit
--     is set, `read' requests on the file can return immediately with a
--     failure status if there is no input immediately available, instead
--     of blocking.  Likewise, `write' requests can also return
--     immediately with a failure status if the output can't be written
--     immediately.
--
--     Note that the `O_NONBLOCK' flag is overloaded as both an I/O
--     operating mode and a file name translation flag; *note Open-time
--     Flags::..
--
-- - Macro: int O_NDELAY
--     This is an obsolete name for `O_NONBLOCK', provided for
--     compatibility with BSD.  It is not defined by the POSIX.1 standard.
--
--   The remaining operating modes are BSD and GNU extensions.  They
--exist only on some systems.  On other systems, these macros are not
--defined.
--
-- - Macro: int O_ASYNC
--     The bit that enables asynchronous input mode.  If set, then `SIGIO'
--     signals will be generated when input is available.  *Note
--     Interrupt Input::.
--
--     Asynchronous input mode is a BSD feature.
--
-- - Macro: int O_FSYNC
--     The bit that enables synchronous writing for the file.  If set,
--     each `write' call will make sure the data is reliably stored on
--     disk before returning.  Synchronous writing is a BSD feature.
--
-- - Macro: int O_SYNC
--     This is another name for `O_FSYNC'.  They have the same value.
--
-- - Macro: int O_NOATIME
--     If this bit is set, `read' will not update the access time of the
--     file.  *Note File Times::.  This is used by programs that do
--     backups, so that backing a file up does not count as reading it.
--     Only the owner of the file or the superuser may use this bit.
--
--     This is a GNU extension.
--
--
--File: libc.info,  Node: Getting File Status Flags,  Prev: Operating Modes,  
Up: File Status Flags
--
--Getting and Setting File Status Flags
---------------------------------------
--
--   The `fcntl' function can fetch or change file status flags.
--
-- - Macro: int F_GETFL
--     This macro is used as the COMMAND argument to `fcntl', to read the
--     file status flags for the open file with descriptor FILEDES.
--
--     The normal return value from `fcntl' with this command is a
--     nonnegative number which can be interpreted as the bitwise OR of
--     the individual flags.  Since the file access modes are not
--     single-bit values, you can mask off other bits in the returned
--     flags with `O_ACCMODE' to compare them.
--
--     In case of an error, `fcntl' returns `-1'.  The following `errno'
--     error conditions are defined for this command:
--
--    `EBADF'
--          The FILEDES argument is invalid.
--
-- - Macro: int F_SETFL
--     This macro is used as the COMMAND argument to `fcntl', to set the
--     file status flags for the open file corresponding to the FILEDES
--     argument.  This command requires a third `int' argument to specify
--     the new flags, so the call looks like this:
--
--          fcntl (FILEDES, F_SETFL, NEW-FLAGS)
--
--     You can't change the access mode for the file in this way; that is,
--     whether the file descriptor was opened for reading or writing.
--
--     The normal return value from `fcntl' with this command is an
--     unspecified value other than `-1', which indicates an error.  The
--     error conditions are the same as for the `F_GETFL' command.
--
--   If you want to modify the file status flags, you should get the
--current flags with `F_GETFL' and modify the value.  Don't assume that
--the flags listed here are the only ones that are implemented; your
--program may be run years from now and more flags may exist then.  For
--example, here is a function to set or clear the flag `O_NONBLOCK'
--without altering any other flags:
--
--     /* Set the `O_NONBLOCK' flag of DESC if VALUE is nonzero,
--        or clear the flag if VALUE is 0.
--        Return 0 on success, or -1 on error with `errno' set. */
--     
--     int
--     set_nonblock_flag (int desc, int value)
--     {
--       int oldflags = fcntl (desc, F_GETFL, 0);
--       /* If reading the flags failed, return error indication now. */
--       if (oldflags == -1)
--         return -1;
--       /* Set just the flag we want to set. */
--       if (value != 0)
--         oldflags |= O_NONBLOCK;
--       else
--         oldflags &= ~O_NONBLOCK;
--       /* Store modified flag word in the descriptor. */
--       return fcntl (desc, F_SETFL, oldflags);
--     }
--
--
--File: libc.info,  Node: File Locks,  Next: Interrupt Input,  Prev: File 
Status Flags,  Up: Low-Level I/O
--
--File Locks
--==========
--
--   The remaining `fcntl' commands are used to support "record locking",
--which permits multiple cooperating programs to prevent each other from
--simultaneously accessing parts of a file in error-prone ways.
--
--   An "exclusive" or "write" lock gives a process exclusive access for
--writing to the specified part of the file.  While a write lock is in
--place, no other process can lock that part of the file.
--
--   A "shared" or "read" lock prohibits any other process from
--requesting a write lock on the specified part of the file.  However,
--other processes can request read locks.
--
--   The `read' and `write' functions do not actually check to see
--whether there are any locks in place.  If you want to implement a
--locking protocol for a file shared by multiple processes, your
--application must do explicit `fcntl' calls to request and clear locks
--at the appropriate points.
--
--   Locks are associated with processes.  A process can only have one
--kind of lock set for each byte of a given file.  When any file
--descriptor for that file is closed by the process, all of the locks
--that process holds on that file are released, even if the locks were
--made using other descriptors that remain open.  Likewise, locks are
--released when a process exits, and are not inherited by child processes
--created using `fork' (*note Creating a Process::.).
--
--   When making a lock, use a `struct flock' to specify what kind of
--lock and where.  This data type and the associated macros for the
--`fcntl' function are declared in the header file `fcntl.h'.
--
-- - Data Type: struct flock
--     This structure is used with the `fcntl' function to describe a file
--     lock.  It has these members:
--
--    `short int l_type'
--          Specifies the type of the lock; one of `F_RDLCK', `F_WRLCK',
--          or `F_UNLCK'.
--
--    `short int l_whence'
--          This corresponds to the WHENCE argument to `fseek' or
--          `lseek', and specifies what the offset is relative to.  Its
--          value can be one of `SEEK_SET', `SEEK_CUR', or `SEEK_END'.
--
--    `off_t l_start'
--          This specifies the offset of the start of the region to which
--          the lock applies, and is given in bytes relative to the point
--          specified by `l_whence' member.
--
--    `off_t l_len'
--          This specifies the length of the region to be locked.  A
--          value of `0' is treated specially; it means the region
--          extends to the end of the file.
--
--    `pid_t l_pid'
--          This field is the process ID (*note Process Creation
--          Concepts::.) of the process holding the lock.  It is filled
--          in by calling `fcntl' with the `F_GETLK' command, but is
--          ignored when making a lock.
--
-- - Macro: int F_GETLK
--     This macro is used as the COMMAND argument to `fcntl', to specify
--     that it should get information about a lock.  This command
--     requires a third argument of type `struct flock *' to be passed to
--     `fcntl', so that the form of the call is:
--
--          fcntl (FILEDES, F_GETLK, LOCKP)
--
--     If there is a lock already in place that would block the lock
--     described by the LOCKP argument, information about that lock
--     overwrites `*LOCKP'.  Existing locks are not reported if they are
--     compatible with making a new lock as specified.  Thus, you should
--     specify a lock type of `F_WRLCK' if you want to find out about both
--     read and write locks, or `F_RDLCK' if you want to find out about
--     write locks only.
--
--     There might be more than one lock affecting the region specified
--     by the LOCKP argument, but `fcntl' only returns information about
--     one of them.  The `l_whence' member of the LOCKP structure is set
--     to `SEEK_SET' and the `l_start' and `l_len' fields set to identify
--     the locked region.
--
--     If no lock applies, the only change to the LOCKP structure is to
--     update the `l_type' to a value of `F_UNLCK'.
--
--     The normal return value from `fcntl' with this command is an
--     unspecified value other than `-1', which is reserved to indicate an
--     error.  The following `errno' error conditions are defined for
--     this command:
--
--    `EBADF'
--          The FILEDES argument is invalid.
--
--    `EINVAL'
--          Either the LOCKP argument doesn't specify valid lock
--          information, or the file associated with FILEDES doesn't
--          support locks.
--
-- - Macro: int F_SETLK
--     This macro is used as the COMMAND argument to `fcntl', to specify
--     that it should set or clear a lock.  This command requires a third
--     argument of type `struct flock *' to be passed to `fcntl', so that
--     the form of the call is:
--
--          fcntl (FILEDES, F_SETLK, LOCKP)
--
--     If the process already has a lock on any part of the region, the
--     old lock on that part is replaced with the new lock.  You can
--     remove a lock by specifying a lock type of `F_UNLCK'.
--
--     If the lock cannot be set, `fcntl' returns immediately with a value
--     of `-1'.  This function does not block waiting for other processes
--     to release locks.  If `fcntl' succeeds, it return a value other
--     than `-1'.
--
--     The following `errno' error conditions are defined for this
--     function:
--
--    `EAGAIN'
--    `EACCES'
--          The lock cannot be set because it is blocked by an existing
--          lock on the file.  Some systems use `EAGAIN' in this case,
--          and other systems use `EACCES'; your program should treat
--          them alike, after `F_SETLK'.  (The GNU system always uses
--          `EAGAIN'.)
--
--    `EBADF'
--          Either: the FILEDES argument is invalid; you requested a read
--          lock but the FILEDES is not open for read access; or, you
--          requested a write lock but the FILEDES is not open for write
--          access.
--
--    `EINVAL'
--          Either the LOCKP argument doesn't specify valid lock
--          information, or the file associated with FILEDES doesn't
--          support locks.
--
--    `ENOLCK'
--          The system has run out of file lock resources; there are
--          already too many file locks in place.
--
--          Well-designed file systems never report this error, because
--          they have no limitation on the number of locks.  However, you
--          must still take account of the possibility of this error, as
--          it could result from network access to a file system on
--          another machine.
--
-- - Macro: int F_SETLKW
--     This macro is used as the COMMAND argument to `fcntl', to specify
--     that it should set or clear a lock.  It is just like the `F_SETLK'
--     command, but causes the process to block (or wait) until the
--     request can be specified.
--
--     This command requires a third argument of type `struct flock *', as
--     for the `F_SETLK' command.
--
--     The `fcntl' return values and errors are the same as for the
--     `F_SETLK' command, but these additional `errno' error conditions
--     are defined for this command:
--
--    `EINTR'
--          The function was interrupted by a signal while it was waiting.
--          *Note Interrupted Primitives::.
--
--    `EDEADLK'
--          The specified region is being locked by another process.  But
--          that process is waiting to lock a region which the current
--          process has locked, so waiting for the lock would result in
--          deadlock.  The system does not guarantee that it will detect
--          all such conditions, but it lets you know if it notices one.
--
--   The following macros are defined for use as values for the `l_type'
--member of the `flock' structure.  The values are integer constants.
--
--`F_RDLCK'
--     This macro is used to specify a read (or shared) lock.
--
--`F_WRLCK'
--     This macro is used to specify a write (or exclusive) lock.
--
--`F_UNLCK'
--     This macro is used to specify that the region is unlocked.
--
--   As an example of a situation where file locking is useful, consider a
--program that can be run simultaneously by several different users, that
--logs status information to a common file.  One example of such a program
--might be a game that uses a file to keep track of high scores.  Another
--example might be a program that records usage or accounting information
--for billing purposes.
--
--   Having multiple copies of the program simultaneously writing to the
--file could cause the contents of the file to become mixed up.  But you
--can prevent this kind of problem by setting a write lock on the file
--before actually writing to the file.
--
--   If the program also needs to read the file and wants to make sure
--that the contents of the file are in a consistent state, then it can
--also use a read lock.  While the read lock is set, no other process can
--lock that part of the file for writing.
--
--   Remember that file locks are only a *voluntary* protocol for
--controlling access to a file.  There is still potential for access to
--the file by programs that don't use the lock protocol.
--
--
--File: libc.info,  Node: Interrupt Input,  Prev: File Locks,  Up: Low-Level I/O
--
--Interrupt-Driven Input
--======================
--
--   If you set the `O_ASYNC' status flag on a file descriptor (*note
--File Status Flags::.), a `SIGIO' signal is sent whenever input or
--output becomes possible on that file descriptor.  The process or
--process group to receive the signal can be selected by using the
--`F_SETOWN' command to the `fcntl' function.  If the file descriptor is
--a socket, this also selects the recipient of `SIGURG' signals that are
--delivered when out-of-band data arrives on that socket; see *Note
--Out-of-Band Data::.  (`SIGURG' is sent in any situation where `select'
--would report the socket as having an "exceptional condition".  *Note
--Waiting for I/O::.)
--
--   If the file descriptor corresponds to a terminal device, then `SIGIO'
--signals are sent to the foreground process group of the terminal.
--*Note Job Control::.
--
--   The symbols in this section are defined in the header file `fcntl.h'.
--
-- - Macro: int F_GETOWN
--     This macro is used as the COMMAND argument to `fcntl', to specify
--     that it should get information about the process or process group
--     to which `SIGIO' signals are sent.  (For a terminal, this is
--     actually the foreground process group ID, which you can get using
--     `tcgetpgrp'; see *Note Terminal Access Functions::.)
--
--     The return value is interpreted as a process ID; if negative, its
--     absolute value is the process group ID.
--
--     The following `errno' error condition is defined for this command:
--
--    `EBADF'
--          The FILEDES argument is invalid.
--
-- - Macro: int F_SETOWN
--     This macro is used as the COMMAND argument to `fcntl', to specify
--     that it should set the process or process group to which `SIGIO'
--     signals are sent.  This command requires a third argument of type
--     `pid_t' to be passed to `fcntl', so that the form of the call is:
--
--          fcntl (FILEDES, F_SETOWN, PID)
--
--     The PID argument should be a process ID.  You can also pass a
--     negative number whose absolute value is a process group ID.
--
--     The return value from `fcntl' with this command is `-1' in case of
--     error and some other value if successful.  The following `errno'
--     error conditions are defined for this command:
--
--    `EBADF'
--          The FILEDES argument is invalid.
--
--    `ESRCH'
--          There is no process or process group corresponding to PID.
--
--
--File: libc.info,  Node: File System Interface,  Next: Pipes and FIFOs,  Prev: 
Low-Level I/O,  Up: Top
--
--File System Interface
--*********************
--
--   This chapter describes the GNU C library's functions for manipulating
--files.  Unlike the input and output functions described in *Note I/O on
--Streams:: and *Note Low-Level I/O::, these functions are concerned with
--operating on the files themselves, rather than on their contents.
--
--   Among the facilities described in this chapter are functions for
--examining or modifying directories, functions for renaming and deleting
--files, and functions for examining and setting file attributes such as
--access permissions and modification times.
--
--* Menu:
--
--* Working Directory::           This is used to resolve relative
--                               file names.
--* Accessing Directories::       Finding out what files a directory
--                               contains.
--* Hard Links::                  Adding alternate names to a file.
--* Symbolic Links::              A file that "points to" a file name.
--* Deleting Files::              How to delete a file, and what that means.
--* Renaming Files::              Changing a file's name.
--* Creating Directories::        A system call just for creating a directory.
--* File Attributes::             Attributes of individual files.
--* Making Special Files::        How to create special files.
--* Temporary Files::             Naming and creating temporary files.
--
--
--File: libc.info,  Node: Working Directory,  Next: Accessing Directories,  Up: 
File System Interface
--
--Working Directory
--=================
--
--   Each process has associated with it a directory, called its "current
--working directory" or simply "working directory", that is used in the
--resolution of relative file names (*note File Name Resolution::.).
--
--   When you log in and begin a new session, your working directory is
--initially set to the home directory associated with your login account
--in the system user database.  You can find any user's home directory
--using the `getpwuid' or `getpwnam' functions; see *Note User Database::.
--
--   Users can change the working directory using shell commands like
--`cd'.  The functions described in this section are the primitives used
--by those commands and by other programs for examining and changing the
--working directory.
--
--   Prototypes for these functions are declared in the header file
--`unistd.h'.
--
-- - Function: char * getcwd (char *BUFFER, size_t SIZE)
--     The `getcwd' function returns an absolute file name representing
--     the current working directory, storing it in the character array
--     BUFFER that you provide.  The SIZE argument is how you tell the
--     system the allocation size of BUFFER.
--
--     The GNU library version of this function also permits you to
--     specify a null pointer for the BUFFER argument.  Then `getcwd'
--     allocates a buffer automatically, as with `malloc' (*note
--     Unconstrained Allocation::.).  If the SIZE is greater than zero,
--     then the buffer is that large; otherwise, the buffer is as large
--     as necessary to hold the result.
--
--     The return value is BUFFER on success and a null pointer on
--     failure.  The following `errno' error conditions are defined for
--     this function:
--
--    `EINVAL'
--          The SIZE argument is zero and BUFFER is not a null pointer.
--
--    `ERANGE'
--          The SIZE argument is less than the length of the working
--          directory name.  You need to allocate a bigger array and try
--          again.
--
--    `EACCES'
--          Permission to read or search a component of the file name was
--          denied.
--
--   Here is an example showing how you could implement the behavior of
--GNU's `getcwd (NULL, 0)' using only the standard behavior of `getcwd':
--
--     char *
--     gnu_getcwd ()
--     {
--       int size = 100;
--       char *buffer = (char *) xmalloc (size);
--     
--       while (1)
--         {
--           char *value = getcwd (buffer, size);
--           if (value != 0)
--             return buffer;
--           size *= 2;
--           free (buffer);
--           buffer = (char *) xmalloc (size);
--         }
--     }
--
--*Note Malloc Examples::, for information about `xmalloc', which is not
--a library function but is a customary name used in most GNU software.
--
-- - Function: char * getwd (char *BUFFER)
--     This is similar to `getcwd', but has no way to specify the size of
--     the buffer.  The GNU library provides `getwd' only for backwards
--     compatibility with BSD.
--
--     The BUFFER argument should be a pointer to an array at least
--     `PATH_MAX' bytes long (*note Limits for Files::.).  In the GNU
--     system there is no limit to the size of a file name, so this is not
--     necessarily enough space to contain the directory name.  That is
--     why this function is deprecated.
--
-- - Function: int chdir (const char *FILENAME)
--     This function is used to set the process's working directory to
--     FILENAME.
--
--     The normal, successful return value from `chdir' is `0'.  A value
--     of `-1' is returned to indicate an error.  The `errno' error
--     conditions defined for this function are the usual file name
--     syntax errors (*note File Name Errors::.), plus `ENOTDIR' if the
--     file FILENAME is not a directory.
--
--
--File: libc.info,  Node: Accessing Directories,  Next: Hard Links,  Prev: 
Working Directory,  Up: File System Interface
--
--Accessing Directories
--=====================
--
--   The facilities described in this section let you read the contents
--of a directory file.  This is useful if you want your program to list
--all the files in a directory, perhaps as part of a menu.
--
--   The `opendir' function opens a "directory stream" whose elements are
--directory entries.  You use the `readdir' function on the directory
--stream to retrieve these entries, represented as `struct dirent'
--objects.  The name of the file for each entry is stored in the `d_name'
--member of this structure.  There are obvious parallels here to the
--stream facilities for ordinary files, described in *Note I/O on
--Streams::.
--
--* Menu:
--
--* Directory Entries::           Format of one directory entry.
--* Opening a Directory::         How to open a directory stream.
--* Reading/Closing Directory::   How to read directory entries from the stream.
--* Simple Directory Lister::     A very simple directory listing program.
--* Random Access Directory::     Rereading part of the directory
--                                 already read with the same stream.
--
--
--File: libc.info,  Node: Directory Entries,  Next: Opening a Directory,  Up: 
Accessing Directories
--
--Format of a Directory Entry
-----------------------------
--
--   This section describes what you find in a single directory entry, as
--you might obtain it from a directory stream.  All the symbols are
--declared in the header file `dirent.h'.
--
-- - Data Type: struct dirent
--     This is a structure type used to return information about directory
--     entries.  It contains the following fields:
--
--    `char d_name[]'
--          This is the null-terminated file name component.  This is the
--          only field you can count on in all POSIX systems.
--
--    `ino_t d_fileno'
--          This is the file serial number.  For BSD compatibility, you
--          can also refer to this member as `d_ino'.  In the GNU system
--          and most POSIX systems, for most files this the same as the
--          `st_ino' member that `stat' will return for the file.  *Note
--          File Attributes::.
--
--    `unsigned char d_namlen'
--          This is the length of the file name, not including the
--          terminating null character.  Its type is `unsigned char'
--          because that is the integer type of the appropriate size
--
--    `unsigned char d_type'
--          This is the type of the file, possibly unknown.  The
--          following constants are defined for its value:
--
--         `DT_UNKNOWN'
--               The type is unknown.  On some systems this is the only
--               value returned.
--
--         `DT_REG'
--               A regular file.
--
--         `DT_DIR'
--               A directory.
--
--         `DT_FIFO'
--               A named pipe, or FIFO.  *Note FIFO Special Files::.
--
--         `DT_SOCK'
--               A local-domain socket.
--
--         `DT_CHR'
--               A character device.
--
--         `DT_BLK'
--               A block device.
--
--          This member is a BSD extension.  Each value except DT_UNKNOWN
--          corresponds to the file type bits in the `st_mode' member of
--          `struct statbuf'.  These two macros convert between `d_type'
--          values and `st_mode' values:
--
--           - Function: int IFTODT (mode_t MODE)
--               This returns the `d_type' value corresponding to MODE.
--
--           - Function: mode_t DTTOIF (int DIRTYPE)
--               This returns the `st_mode' value corresponding to
--               DIRTYPE.
--
--     This structure may contain additional members in the future.
--
--     When a file has multiple names, each name has its own directory
--     entry.  The only way you can tell that the directory entries
--     belong to a single file is that they have the same value for the
--     `d_fileno' field.
--
--     File attributes such as size, modification times, and the like are
--     part of the file itself, not any particular directory entry.
--     *Note File Attributes::.
--
--
--File: libc.info,  Node: Opening a Directory,  Next: Reading/Closing 
Directory,  Prev: Directory Entries,  Up: Accessing Directories
--
--Opening a Directory Stream
----------------------------
--
--   This section describes how to open a directory stream.  All the
--symbols are declared in the header file `dirent.h'.
--
-- - Data Type: DIR
--     The `DIR' data type represents a directory stream.
--
--   You shouldn't ever allocate objects of the `struct dirent' or `DIR'
--data types, since the directory access functions do that for you.
--Instead, you refer to these objects using the pointers returned by the
--following functions.
--
-- - Function: DIR * opendir (const char *DIRNAME)
--     The `opendir' function opens and returns a directory stream for
--     reading the directory whose file name is DIRNAME.  The stream has
--     type `DIR *'.
--
--     If unsuccessful, `opendir' returns a null pointer.  In addition to
--     the usual file name errors (*note File Name Errors::.), the
--     following `errno' error conditions are defined for this function:
--
--    `EACCES'
--          Read permission is denied for the directory named by
--          `dirname'.
--
--    `EMFILE'
--          The process has too many files open.
--
--    `ENFILE'
--          The entire system, or perhaps the file system which contains
--          the directory, cannot support any additional open files at
--          the moment.  (This problem cannot happen on the GNU system.)
--
--     The `DIR' type is typically implemented using a file descriptor,
--     and the `opendir' function in terms of the `open' function.  *Note
--     Low-Level I/O::.  Directory streams and the underlying file
--     descriptors are closed on `exec' (*note Executing a File::.).
--
--
--File: libc.info,  Node: Reading/Closing Directory,  Next: Simple Directory 
Lister,  Prev: Opening a Directory,  Up: Accessing Directories
--
--Reading and Closing a Directory Stream
----------------------------------------
--
--   This section describes how to read directory entries from a directory
--stream, and how to close the stream when you are done with it.  All the
--symbols are declared in the header file `dirent.h'.
--
-- - Function: struct dirent * readdir (DIR *DIRSTREAM)
--     This function reads the next entry from the directory.  It normally
--     returns a pointer to a structure containing information about the
--     file.  This structure is statically allocated and can be rewritten
--     by a subsequent call.
--
--     *Portability Note:* On some systems, `readdir' may not return
--     entries for `.' and `..', even though these are always valid file
--     names in any directory.  *Note File Name Resolution::.
--
--     If there are no more entries in the directory or an error is
--     detected, `readdir' returns a null pointer.  The following `errno'
--     error conditions are defined for this function:
--
--    `EBADF'
--          The DIRSTREAM argument is not valid.
--
--     `readdir' is not thread safe.  Multiple threads using `readdir' on
--     the same DIRSTREAM may overwrite the return value.  Use
--     `readdir_r' when this is critical.
--
-- - Function: int readdir_r (DIR *DIRSTREAM, struct *ENTRY, struct
--          **RESULT)
--     This function is the reentrant version of `readdir'.  Like
--     `readdir' it returns the next entry from the directory.  But to
--     prevent conflicts for simultaneously running threads the result is
--     not stored in some internal memory.  Instead the argument ENTRY
--     has to point to a place where the result is stored.
--
--     The return value is `0' in case the next entry was read
--     successfully.  In this case a pointer to the result is returned in
--     *RESULT.  It is not required that *RESULT is the same as ENTRY.
--     If something goes wrong while executing `readdir_r' the function
--     returns `-1'.  The `errno' variable is set like described for
--     `readdir'.
--
--     *Portability Note:* On some systems, `readdir_r' may not return a
--     terminated string as the file name even if no `d_reclen' element
--     is available in `struct dirent' and the file name as the maximal
--     allowed size.  Modern systems all have the `d_reclen' field and on
--     old systems multi threading is not critical.  In any case, there
--     is no such problem with the `readdir' function so that even on
--     systems without `d_reclen' field one could use multiple threads by
--     using external locking.
--
-- - Function: int closedir (DIR *DIRSTREAM)
--     This function closes the directory stream DIRSTREAM.  It returns
--     `0' on success and `-1' on failure.
--
--     The following `errno' error conditions are defined for this
--     function:
--
--    `EBADF'
--          The DIRSTREAM argument is not valid.
--
--
--File: libc.info,  Node: Simple Directory Lister,  Next: Random Access 
Directory,  Prev: Reading/Closing Directory,  Up: Accessing Directories
--
--Simple Program to List a Directory
------------------------------------
--
--   Here's a simple program that prints the names of the files in the
--current working directory:
--
--     #include <stddef.h>
--     #include <stdio.h>
--     #include <sys/types.h>
--     #include <dirent.h>
--     
--     int
--     main (void)
--     {
--       DIR *dp;
--       struct dirent *ep;
--     
--       dp = opendir ("./");
--       if (dp != NULL)
--         {
--           while (ep = readdir (dp))
--             puts (ep->d_name);
--           (void) closedir (dp);
--         }
--       else
--         puts ("Couldn't open the directory.");
--     
--       return 0;
--     }
--
--   The order in which files appear in a directory tends to be fairly
--random.  A more useful program would sort the entries (perhaps by
--alphabetizing them) before printing them; see *Note Array Sort
--Function::.
--
--
--File: libc.info,  Node: Random Access Directory,  Prev: Simple Directory 
Lister,  Up: Accessing Directories
--
--Random Access in a Directory Stream
-------------------------------------
--
--   This section describes how to reread parts of a directory that you
--have already read from an open directory stream.  All the symbols are
--declared in the header file `dirent.h'.
--
-- - Function: void rewinddir (DIR *DIRSTREAM)
--     The `rewinddir' function is used to reinitialize the directory
--     stream DIRSTREAM, so that if you call `readdir' it returns
--     information about the first entry in the directory again.  This
--     function also notices if files have been added or removed to the
--     directory since it was opened with `opendir'.  (Entries for these
--     files might or might not be returned by `readdir' if they were
--     added or removed since you last called `opendir' or `rewinddir'.)
--
-- - Function: off_t telldir (DIR *DIRSTREAM)
--     The `telldir' function returns the file position of the directory
--     stream DIRSTREAM.  You can use this value with `seekdir' to
--     restore the directory stream to that position.
--
-- - Function: void seekdir (DIR *DIRSTREAM, off_t POS)
--     The `seekdir' function sets the file position of the directory
--     stream DIRSTREAM to POS.  The value POS must be the result of a
--     previous call to `telldir' on this particular stream; closing and
--     reopening the directory can invalidate values returned by
--     `telldir'.
--
--
--File: libc.info,  Node: Hard Links,  Next: Symbolic Links,  Prev: Accessing 
Directories,  Up: File System Interface
--
--Hard Links
--==========
--
--   In POSIX systems, one file can have many names at the same time.
--All of the names are equally real, and no one of them is preferred to
--the others.
--
--   To add a name to a file, use the `link' function.  (The new name is
--also called a "hard link" to the file.)  Creating a new link to a file
--does not copy the contents of the file; it simply makes a new name by
--which the file can be known, in addition to the file's existing name or
--names.
--
--   One file can have names in several directories, so the the
--organization of the file system is not a strict hierarchy or tree.
--
--   In most implementations, it is not possible to have hard links to the
--same file in multiple file systems.  `link' reports an error if you try
--to make a hard link to the file from another file system when this
--cannot be done.
--
--   The prototype for the `link' function is declared in the header file
--`unistd.h'.
--
-- - Function: int link (const char *OLDNAME, const char *NEWNAME)
--     The `link' function makes a new link to the existing file named by
--     OLDNAME, under the new name NEWNAME.
--
--     This function returns a value of `0' if it is successful and `-1'
--     on failure.  In addition to the usual file name errors (*note File
--     Name Errors::.) for both OLDNAME and NEWNAME, the following
--     `errno' error conditions are defined for this function:
--
--    `EACCES'
--          You are not allowed to write the directory in which the new
--          link is to be written.
--
--    `EEXIST'
--          There is already a file named NEWNAME.  If you want to replace
--          this link with a new link, you must remove the old link
--          explicitly first.
--
--    `EMLINK'
--          There are already too many links to the file named by OLDNAME.
--          (The maximum number of links to a file is `LINK_MAX'; see
--          *Note Limits for Files::.)
--
--    `ENOENT'
--          The file named by OLDNAME doesn't exist.  You can't make a
--          link to a file that doesn't exist.
--
--    `ENOSPC'
--          The directory or file system that would contain the new link
--          is full and cannot be extended.
--
--    `EPERM'
--          In the GNU system and some others, you cannot make links to
--          directories.  Many systems allow only privileged users to do
--          so.  This error is used to report the problem.
--
--    `EROFS'
--          The directory containing the new link can't be modified
--          because it's on a read-only file system.
--
--    `EXDEV'
--          The directory specified in NEWNAME is on a different file
--          system than the existing file.
--
--    `EIO'
--          A hardware error occurred while trying to read or write the
--          to filesystem.
--
--
--File: libc.info,  Node: Symbolic Links,  Next: Deleting Files,  Prev: Hard 
Links,  Up: File System Interface
--
--Symbolic Links
--==============
--
--   The GNU system supports "soft links" or "symbolic links".  This is a
--kind of "file" that is essentially a pointer to another file name.
--Unlike hard links, symbolic links can be made to directories or across
--file systems with no restrictions.  You can also make a symbolic link
--to a name which is not the name of any file.  (Opening this link will
--fail until a file by that name is created.)  Likewise, if the symbolic
--link points to an existing file which is later deleted, the symbolic
--link continues to point to the same file name even though the name no
--longer names any file.
--
--   The reason symbolic links work the way they do is that special things
--happen when you try to open the link.  The `open' function realizes you
--have specified the name of a link, reads the file name contained in the
--link, and opens that file name instead.  The `stat' function likewise
--operates on the file that the symbolic link points to, instead of on
--the link itself.
--
--   By contrast, other operations such as deleting or renaming the file
--operate on the link itself.  The functions `readlink' and `lstat' also
--refrain from following symbolic links, because their purpose is to
--obtain information about the link.  So does `link', the function that
--makes a hard link--it makes a hard link to the symbolic link, which one
--rarely wants.
--
--   Prototypes for the functions listed in this section are in
--`unistd.h'.
--
-- - Function: int symlink (const char *OLDNAME, const char *NEWNAME)
--     The `symlink' function makes a symbolic link to OLDNAME named
--     NEWNAME.
--
--     The normal return value from `symlink' is `0'.  A return value of
--     `-1' indicates an error.  In addition to the usual file name
--     syntax errors (*note File Name Errors::.), the following `errno'
--     error conditions are defined for this function:
--
--    `EEXIST'
--          There is already an existing file named NEWNAME.
--
--    `EROFS'
--          The file NEWNAME would exist on a read-only file system.
--
--    `ENOSPC'
--          The directory or file system cannot be extended to make the
--          new link.
--
--    `EIO'
--          A hardware error occurred while reading or writing data on
--          the disk.
--
--
-- - Function: int readlink (const char *FILENAME, char *BUFFER, size_t
--          SIZE)
--     The `readlink' function gets the value of the symbolic link
--     FILENAME.  The file name that the link points to is copied into
--     BUFFER.  This file name string is *not* null-terminated;
--     `readlink' normally returns the number of characters copied.  The
--     SIZE argument specifies the maximum number of characters to copy,
--     usually the allocation size of BUFFER.
--
--     If the return value equals SIZE, you cannot tell whether or not
--     there was room to return the entire name.  So make a bigger buffer
--     and call `readlink' again.  Here is an example:
--
--          char *
--          readlink_malloc (char *filename)
--          {
--            int size = 100;
--          
--            while (1)
--              {
--                char *buffer = (char *) xmalloc (size);
--                int nchars = readlink (filename, buffer, size);
--                if (nchars < size)
--                  return buffer;
--                free (buffer);
--                size *= 2;
--              }
--          }
--
--     A value of `-1' is returned in case of error.  In addition to the
--     usual file name errors (*note File Name Errors::.), the following
--     `errno' error conditions are defined for this function:
--
--    `EINVAL'
--          The named file is not a symbolic link.
--
--    `EIO'
--          A hardware error occurred while reading or writing data on
--          the disk.
--
--
--File: libc.info,  Node: Deleting Files,  Next: Renaming Files,  Prev: 
Symbolic Links,  Up: File System Interface
--
--Deleting Files
--==============
--
--   You can delete a file with the functions `unlink' or `remove'.
--
--   Deletion actually deletes a file name.  If this is the file's only
--name, then the file is deleted as well.  If the file has other names as
--well (*note Hard Links::.), it remains accessible under its other names.
--
-- - Function: int unlink (const char *FILENAME)
--     The `unlink' function deletes the file name FILENAME.  If this is
--     a file's sole name, the file itself is also deleted.  (Actually,
--     if any process has the file open when this happens, deletion is
--     postponed until all processes have closed the file.)
--
--     The function `unlink' is declared in the header file `unistd.h'.
--
--     This function returns `0' on successful completion, and `-1' on
--     error.  In addition to the usual file name errors (*note File Name
--     Errors::.), the following `errno' error conditions are defined for
--     this function:
--
--    `EACCES'
--          Write permission is denied for the directory from which the
--          file is to be removed, or the directory has the sticky bit
--          set and you do not own the file.
--
--    `EBUSY'
--          This error indicates that the file is being used by the
--          system in such a way that it can't be unlinked.  For example,
--          you might see this error if the file name specifies the root
--          directory or a mount point for a file system.
--
--    `ENOENT'
--          The file name to be deleted doesn't exist.
--
--    `EPERM'
--          On some systems, `unlink' cannot be used to delete the name
--          of a directory, or can only be used this way by a privileged
--          user.  To avoid such problems, use `rmdir' to delete
--          directories.  (In the GNU system `unlink' can never delete
--          the name of a directory.)
--
--    `EROFS'
--          The directory in which the file name is to be deleted is on a
--          read-only file system, and can't be modified.
--
-- - Function: int rmdir (const char *FILENAME)
--     The `rmdir' function deletes a directory.  The directory must be
--     empty before it can be removed; in other words, it can only contain
--     entries for `.' and `..'.
--
--     In most other respects, `rmdir' behaves like `unlink'.  There are
--     two additional `errno' error conditions defined for `rmdir':
--
--    `ENOTEMPTY'
--    `EEXIST'
--          The directory to be deleted is not empty.
--
--     These two error codes are synonymous; some systems use one, and
--     some use the other.  The GNU system always uses `ENOTEMPTY'.
--
--     The prototype for this function is declared in the header file
--     `unistd.h'.
--
-- - Function: int remove (const char *FILENAME)
--     This is the ISO C function to remove a file.  It works like
--     `unlink' for files and like `rmdir' for directories.  `remove' is
--     declared in `stdio.h'.
--
--
--File: libc.info,  Node: Renaming Files,  Next: Creating Directories,  Prev: 
Deleting Files,  Up: File System Interface
--
--Renaming Files
--==============
--
--   The `rename' function is used to change a file's name.
--
-- - Function: int rename (const char *OLDNAME, const char *NEWNAME)
--     The `rename' function renames the file name OLDNAME with NEWNAME.
--     The file formerly accessible under the name OLDNAME is afterward
--     accessible as NEWNAME instead.  (If the file had any other names
--     aside from OLDNAME, it continues to have those names.)
--
--     The directory containing the name NEWNAME must be on the same file
--     system as the file (as indicated by the name OLDNAME).
--
--     One special case for `rename' is when OLDNAME and NEWNAME are two
--     names for the same file.  The consistent way to handle this case
--     is to delete OLDNAME.  However, POSIX requires that in this case
--     `rename' do nothing and report success--which is inconsistent.  We
--     don't know what your operating system will do.
--
--     If the OLDNAME is not a directory, then any existing file named
--     NEWNAME is removed during the renaming operation.  However, if
--     NEWNAME is the name of a directory, `rename' fails in this case.
--
--     If the OLDNAME is a directory, then either NEWNAME must not exist
--     or it must name a directory that is empty.  In the latter case,
--     the existing directory named NEWNAME is deleted first.  The name
--     NEWNAME must not specify a subdirectory of the directory `oldname'
--     which is being renamed.
--
--     One useful feature of `rename' is that the meaning of the name
--     NEWNAME changes "atomically" from any previously existing file by
--     that name to its new meaning (the file that was called OLDNAME).
--     There is no instant at which NEWNAME is nonexistent "in between"
--     the old meaning and the new meaning.  If there is a system crash
--     during the operation, it is possible for both names to still
--     exist; but NEWNAME will always be intact if it exists at all.
--
--     If `rename' fails, it returns `-1'.  In addition to the usual file
--     name errors (*note File Name Errors::.), the following `errno'
--     error conditions are defined for this function:
--
--    `EACCES'
--          One of the directories containing NEWNAME or OLDNAME refuses
--          write permission; or NEWNAME and OLDNAME are directories and
--          write permission is refused for one of them.
--
--    `EBUSY'
--          A directory named by OLDNAME or NEWNAME is being used by the
--          system in a way that prevents the renaming from working.
--          This includes directories that are mount points for
--          filesystems, and directories that are the current working
--          directories of processes.
--
--    `ENOTEMPTY'
--    `EEXIST'
--          The directory NEWNAME isn't empty.  The GNU system always
--          returns `ENOTEMPTY' for this, but some other systems return
--          `EEXIST'.
--
--    `EINVAL'
--          The OLDNAME is a directory that contains NEWNAME.
--
--    `EISDIR'
--          The NEWNAME names a directory, but the OLDNAME doesn't.
--
--    `EMLINK'
--          The parent directory of NEWNAME would have too many links.
--
--    `ENOENT'
--          The file named by OLDNAME doesn't exist.
--
--    `ENOSPC'
--          The directory that would contain NEWNAME has no room for
--          another entry, and there is no space left in the file system
--          to expand it.
--
--    `EROFS'
--          The operation would involve writing to a directory on a
--          read-only file system.
--
--    `EXDEV'
--          The two file names NEWNAME and OLDNAMES are on different file
--          systems.
--
--
--File: libc.info,  Node: Creating Directories,  Next: File Attributes,  Prev: 
Renaming Files,  Up: File System Interface
--
--Creating Directories
--====================
--
--   Directories are created with the `mkdir' function.  (There is also a
--shell command `mkdir' which does the same thing.)
--
-- - Function: int mkdir (const char *FILENAME, mode_t MODE)
--     The `mkdir' function creates a new, empty directory whose name is
--     FILENAME.
--
--     The argument MODE specifies the file permissions for the new
--     directory file.  *Note Permission Bits::, for more information
--     about this.
--
--     A return value of `0' indicates successful completion, and `-1'
--     indicates failure.  In addition to the usual file name syntax
--     errors (*note File Name Errors::.), the following `errno' error
--     conditions are defined for this function:
--
--    `EACCES'
--          Write permission is denied for the parent directory in which
--          the new directory is to be added.
--
--    `EEXIST'
--          A file named FILENAME already exists.
--
--    `EMLINK'
--          The parent directory has too many links.
--
--          Well-designed file systems never report this error, because
--          they permit more links than your disk could possibly hold.
--          However, you must still take account of the possibility of
--          this error, as it could result from network access to a file
--          system on another machine.
--
--    `ENOSPC'
--          The file system doesn't have enough room to create the new
--          directory.
--
--    `EROFS'
--          The parent directory of the directory being created is on a
--          read-only file system, and cannot be modified.
--
--     To use this function, your program should include the header file
--     `sys/stat.h'.
--
--
--File: libc.info,  Node: File Attributes,  Next: Making Special Files,  Prev: 
Creating Directories,  Up: File System Interface
--
--File Attributes
--===============
--
--   When you issue an `ls -l' shell command on a file, it gives you
--information about the size of the file, who owns it, when it was last
--modified, and the like.  This kind of information is called the "file
--attributes"; it is associated with the file itself and not a particular
--one of its names.
--
--   This section contains information about how you can inquire about and
--modify these attributes of files.
--
--* Menu:
--
--* Attribute Meanings::          The names of the file attributes,
--                                 and what their values mean.
--* Reading Attributes::          How to read the attributes of a file.
--* Testing File Type::           Distinguishing ordinary files,
--                                 directories, links...
--* File Owner::                  How ownership for new files is determined,
--                               and how to change it.
--* Permission Bits::             How information about a file's access
--                                 mode is stored.
--* Access Permission::           How the system decides who can access a file.
--* Setting Permissions::         How permissions for new files are assigned,
--                               and how to change them.
--* Testing File Access::         How to find out if your process can
--                                 access a file.
--* File Times::                  About the time attributes of a file.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-11 
glibc-2.0.1/manual/libc.info-11
---- ../glibc-2.0.1/manual/libc.info-11 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-11    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1248 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Attribute Meanings,  Next: Reading Attributes,  Up: 
File Attributes
--
--What the File Attribute Values Mean
-------------------------------------
--
--   When you read the attributes of a file, they come back in a structure
--called `struct stat'.  This section describes the names of the
--attributes, their data types, and what they mean.  For the functions to
--read the attributes of a file, see *Note Reading Attributes::.
--
--   The header file `sys/stat.h' declares all the symbols defined in
--this section.
--
-- - Data Type: struct stat
--     The `stat' structure type is used to return information about the
--     attributes of a file.  It contains at least the following members:
--
--    `mode_t st_mode'
--          Specifies the mode of the file.  This includes file type
--          information (*note Testing File Type::.) and the file
--          permission bits (*note Permission Bits::.).
--
--    `ino_t st_ino'
--          The file serial number, which distinguishes this file from
--          all other files on the same device.
--
--    `dev_t st_dev'
--          Identifies the device containing the file.  The `st_ino' and
--          `st_dev', taken together, uniquely identify the file.  The
--          `st_dev' value is not necessarily consistent across reboots or
--          system crashes, however.
--
--    `nlink_t st_nlink'
--          The number of hard links to the file.  This count keeps track
--          of how many directories have entries for this file.  If the
--          count is ever decremented to zero, then the file itself is
--          discarded as soon as no process still holds it open.
--          Symbolic links are not counted in the total.
--
--    `uid_t st_uid'
--          The user ID of the file's owner.  *Note File Owner::.
--
--    `gid_t st_gid'
--          The group ID of the file.  *Note File Owner::.
--
--    `off_t st_size'
--          This specifies the size of a regular file in bytes.  For
--          files that are really devices and the like, this field isn't
--          usually meaningful.  For symbolic links, this specifies the
--          length of the file name the link refers to.
--
--    `time_t st_atime'
--          This is the last access time for the file.  *Note File
--          Times::.
--
--    `unsigned long int st_atime_usec'
--          This is the fractional part of the last access time for the
--          file.  *Note File Times::.
--
--    `time_t st_mtime'
--          This is the time of the last modification to the contents of
--          the file.  *Note File Times::.
--
--    `unsigned long int st_mtime_usec'
--          This is the fractional part of the time of last modification
--          to the contents of the file.  *Note File Times::.
--
--    `time_t st_ctime'
--          This is the time of the last modification to the attributes
--          of the file.  *Note File Times::.
--
--    `unsigned long int st_ctime_usec'
--          This is the fractional part of the time of last modification
--          to the attributes of the file.  *Note File Times::.
--
--    `unsigned int st_blocks'
--          This is the amount of disk space that the file occupies,
--          measured in units of 512-byte blocks.
--
--          The number of disk blocks is not strictly proportional to the
--          size of the file, for two reasons: the file system may use
--          some blocks for internal record keeping; and the file may be
--          sparse--it may have "holes" which contain zeros but do not
--          actually take up space on the disk.
--
--          You can tell (approximately) whether a file is sparse by
--          comparing this value with `st_size', like this:
--
--               (st.st_blocks * 512 < st.st_size)
--
--          This test is not perfect because a file that is just slightly
--          sparse might not be detected as sparse at all.  For practical
--          applications, this is not a problem.
--
--    `unsigned int st_blksize'
--          The optimal block size for reading of writing this file, in
--          bytes.  You might use this size for allocating the buffer
--          space for reading of writing the file.  (This is unrelated to
--          `st_blocks'.)
--
--   Some of the file attributes have special data type names which exist
--specifically for those attributes.  (They are all aliases for well-known
--integer types that you know and love.)  These typedef names are defined
--in the header file `sys/types.h' as well as in `sys/stat.h'.  Here is a
--list of them.
--
-- - Data Type: mode_t
--     This is an integer data type used to represent file modes.  In the
--     GNU system, this is equivalent to `unsigned int'.
--
-- - Data Type: ino_t
--     This is an arithmetic data type used to represent file serial
--     numbers.  (In Unix jargon, these are sometimes called "inode
--     numbers".) In the GNU system, this type is equivalent to `unsigned
--     long int'.
--
-- - Data Type: dev_t
--     This is an arithmetic data type used to represent file device
--     numbers.  In the GNU system, this is equivalent to `int'.
--
-- - Data Type: nlink_t
--     This is an arithmetic data type used to represent file link counts.
--     In the GNU system, this is equivalent to `unsigned short int'.
--
--
--File: libc.info,  Node: Reading Attributes,  Next: Testing File Type,  Prev: 
Attribute Meanings,  Up: File Attributes
--
--Reading the Attributes of a File
----------------------------------
--
--   To examine the attributes of files, use the functions `stat',
--`fstat' and `lstat'.  They return the attribute information in a
--`struct stat' object.  All three functions are declared in the header
--file `sys/stat.h'.
--
-- - Function: int stat (const char *FILENAME, struct stat *BUF)
--     The `stat' function returns information about the attributes of the
--     file named by FILENAME in the structure pointed at by BUF.
--
--     If FILENAME is the name of a symbolic link, the attributes you get
--     describe the file that the link points to.  If the link points to a
--     nonexistent file name, then `stat' fails, reporting a nonexistent
--     file.
--
--     The return value is `0' if the operation is successful, and `-1'
--     on failure.  In addition to the usual file name errors (*note File
--     Name Errors::., the following `errno' error conditions are defined
--     for this function:
--
--    `ENOENT'
--          The file named by FILENAME doesn't exist.
--
-- - Function: int fstat (int FILEDES, struct stat *BUF)
--     The `fstat' function is like `stat', except that it takes an open
--     file descriptor as an argument instead of a file name.  *Note
--     Low-Level I/O::.
--
--     Like `stat', `fstat' returns `0' on success and `-1' on failure.
--     The following `errno' error conditions are defined for `fstat':
--
--    `EBADF'
--          The FILEDES argument is not a valid file descriptor.
--
-- - Function: int lstat (const char *FILENAME, struct stat *BUF)
--     The `lstat' function is like `stat', except that it does not
--     follow symbolic links.  If FILENAME is the name of a symbolic
--     link, `lstat' returns information about the link itself; otherwise,
--     `lstat' works like `stat'.  *Note Symbolic Links::.
--
--
--File: libc.info,  Node: Testing File Type,  Next: File Owner,  Prev: Reading 
Attributes,  Up: File Attributes
--
--Testing the Type of a File
----------------------------
--
--   The "file mode", stored in the `st_mode' field of the file
--attributes, contains two kinds of information: the file type code, and
--the access permission bits.  This section discusses only the type code,
--which you can use to tell whether the file is a directory, whether it is
--a socket, and so on.  For information about the access permission,
--*Note Permission Bits::.
--
--   There are two predefined ways you can access the file type portion of
--the file mode.  First of all, for each type of file, there is a
--"predicate macro" which examines a file mode value and returns true or
--false--is the file of that type, or not.  Secondly, you can mask out
--the rest of the file mode to get just a file type code.  You can
--compare this against various constants for the supported file types.
--
--   All of the symbols listed in this section are defined in the header
--file `sys/stat.h'.
--
--   The following predicate macros test the type of a file, given the
--value M which is the `st_mode' field returned by `stat' on that file:
--
-- - Macro: int S_ISDIR (mode_t M)
--     This macro returns nonzero if the file is a directory.
--
-- - Macro: int S_ISCHR (mode_t M)
--     This macro returns nonzero if the file is a character special file
--     (a device like a terminal).
--
-- - Macro: int S_ISBLK (mode_t M)
--     This macro returns nonzero if the file is a block special file (a
--     device like a disk).
--
-- - Macro: int S_ISREG (mode_t M)
--     This macro returns nonzero if the file is a regular file.
--
-- - Macro: int S_ISFIFO (mode_t M)
--     This macro returns nonzero if the file is a FIFO special file, or a
--     pipe.  *Note Pipes and FIFOs::.
--
-- - Macro: int S_ISLNK (mode_t M)
--     This macro returns nonzero if the file is a symbolic link.  *Note
--     Symbolic Links::.
--
-- - Macro: int S_ISSOCK (mode_t M)
--     This macro returns nonzero if the file is a socket.  *Note
--     Sockets::.
--
--   An alterate non-POSIX method of testing the file type is supported
--for compatibility with BSD.  The mode can be bitwise ANDed with
--`S_IFMT' to extract the file type code, and compared to the appropriate
--type code constant.  For example,
--
--     S_ISCHR (MODE)
--
--is equivalent to:
--
--     ((MODE & S_IFMT) == S_IFCHR)
--
-- - Macro: int S_IFMT
--     This is a bit mask used to extract the file type code portion of a
--     mode value.
--
--   These are the symbolic names for the different file type codes:
--
--`S_IFDIR'
--     This macro represents the value of the file type code for a
--     directory file.
--
--`S_IFCHR'
--     This macro represents the value of the file type code for a
--     character-oriented device file.
--
--`S_IFBLK'
--     This macro represents the value of the file type code for a
--     block-oriented device file.
--
--`S_IFREG'
--     This macro represents the value of the file type code for a
--     regular file.
--
--`S_IFLNK'
--     This macro represents the value of the file type code for a
--     symbolic link.
--
--`S_IFSOCK'
--     This macro represents the value of the file type code for a socket.
--
--`S_IFIFO'
--     This macro represents the value of the file type code for a FIFO
--     or pipe.
--
--
--File: libc.info,  Node: File Owner,  Next: Permission Bits,  Prev: Testing 
File Type,  Up: File Attributes
--
--File Owner
------------
--
--   Every file has an "owner" which is one of the registered user names
--defined on the system.  Each file also has a "group", which is one of
--the defined groups.  The file owner can often be useful for showing you
--who edited the file (especially when you edit with GNU Emacs), but its
--main purpose is for access control.
--
--   The file owner and group play a role in determining access because
--the file has one set of access permission bits for the user that is the
--owner, another set that apply to users who belong to the file's group,
--and a third set of bits that apply to everyone else.  *Note Access
--Permission::, for the details of how access is decided based on this
--data.
--
--   When a file is created, its owner is set from the effective user ID
--of the process that creates it (*note Process Persona::.).  The file's
--group ID may be set from either effective group ID of the process, or
--the group ID of the directory that contains the file, depending on the
--system where the file is stored.  When you access a remote file system,
--it behaves according to its own rule, not according to the system your
--program is running on.  Thus, your program must be prepared to encounter
--either kind of behavior, no matter what kind of system you run it on.
--
--   You can change the owner and/or group owner of an existing file using
--the `chown' function.  This is the primitive for the `chown' and
--`chgrp' shell commands.
--
--   The prototype for this function is declared in `unistd.h'.
--
-- - Function: int chown (const char *FILENAME, uid_t OWNER, gid_t GROUP)
--     The `chown' function changes the owner of the file FILENAME to
--     OWNER, and its group owner to GROUP.
--
--     Changing the owner of the file on certain systems clears the
--     set-user-ID and set-group-ID bits of the file's permissions.
--     (This is because those bits may not be appropriate for the new
--     owner.)  The other file permission bits are not changed.
--
--     The return value is `0' on success and `-1' on failure.  In
--     addition to the usual file name errors (*note File Name Errors::.),
--     the following `errno' error conditions are defined for this
--     function:
--
--    `EPERM'
--          This process lacks permission to make the requested change.
--
--          Only privileged users or the file's owner can change the
--          file's group.  On most file systems, only privileged users
--          can change the file owner; some file systems allow you to
--          change the owner if you are currently the owner.  When you
--          access a remote file system, the behavior you encounter is
--          determined by the system that actually holds the file, not by
--          the system your program is running on.
--
--          *Note Options for Files::, for information about the
--          `_POSIX_CHOWN_RESTRICTED' macro.
--
--    `EROFS'
--          The file is on a read-only file system.
--
-- - Function: int fchown (int FILEDES, int OWNER, int GROUP)
--     This is like `chown', except that it changes the owner of the file
--     with open file descriptor FILEDES.
--
--     The return value from `fchown' is `0' on success and `-1' on
--     failure.  The following `errno' error codes are defined for this
--     function:
--
--    `EBADF'
--          The FILEDES argument is not a valid file descriptor.
--
--    `EINVAL'
--          The FILEDES argument corresponds to a pipe or socket, not an
--          ordinary file.
--
--    `EPERM'
--          This process lacks permission to make the requested change.
--          For details, see `chmod', above.
--
--    `EROFS'
--          The file resides on a read-only file system.
--
--
--File: libc.info,  Node: Permission Bits,  Next: Access Permission,  Prev: 
File Owner,  Up: File Attributes
--
--The Mode Bits for Access Permission
-------------------------------------
--
--   The "file mode", stored in the `st_mode' field of the file
--attributes, contains two kinds of information: the file type code, and
--the access permission bits.  This section discusses only the access
--permission bits, which control who can read or write the file.  *Note
--Testing File Type::, for information about the file type code.
--
--   All of the symbols listed in this section are defined in the header
--file `sys/stat.h'.
--
--   These symbolic constants are defined for the file mode bits that
--control access permission for the file:
--
--`S_IRUSR'
--`S_IREAD'
--     Read permission bit for the owner of the file.  On many systems,
--     this bit is 0400.  `S_IREAD' is an obsolete synonym provided for
--     BSD compatibility.
--
--`S_IWUSR'
--`S_IWRITE'
--     Write permission bit for the owner of the file.  Usually 0200.
--     `S_IWRITE' is an obsolete synonym provided for BSD compatibility.
--
--`S_IXUSR'
--`S_IEXEC'
--     Execute (for ordinary files) or search (for directories)
--     permission bit for the owner of the file.  Usually 0100.
--     `S_IEXEC' is an obsolete synonym provided for BSD compatibility.
--
--`S_IRWXU'
--     This is equivalent to `(S_IRUSR | S_IWUSR | S_IXUSR)'.
--
--`S_IRGRP'
--     Read permission bit for the group owner of the file.  Usually 040.
--
--`S_IWGRP'
--     Write permission bit for the group owner of the file.  Usually 020.
--
--`S_IXGRP'
--     Execute or search permission bit for the group owner of the file.
--     Usually 010.
--
--`S_IRWXG'
--     This is equivalent to `(S_IRGRP | S_IWGRP | S_IXGRP)'.
--
--`S_IROTH'
--     Read permission bit for other users.  Usually 04.
--
--`S_IWOTH'
--     Write permission bit for other users.  Usually 02.
--
--`S_IXOTH'
--     Execute or search permission bit for other users.  Usually 01.
--
--`S_IRWXO'
--     This is equivalent to `(S_IROTH | S_IWOTH | S_IXOTH)'.
--
--`S_ISUID'
--     This is the set-user-ID on execute bit, usually 04000.  *Note How
--     Change Persona::.
--
--`S_ISGID'
--     This is the set-group-ID on execute bit, usually 02000.  *Note How
--     Change Persona::.
--
--`S_ISVTX'
--     This is the "sticky" bit, usually 01000.
--
--     On a directory, it gives permission to delete a file in the
--     directory only if you own that file.  Ordinarily, a user either
--     can delete all the files in the directory or cannot delete any of
--     them (based on whether the user has write permission for the
--     directory).  The same restriction applies--you must both have
--     write permission for the directory and own the file you want to
--     delete.  The one exception is that the owner of the directory can
--     delete any file in the directory, no matter who owns it (provided
--     the owner has given himself write permission for the directory).
--     This is commonly used for the `/tmp' directory, where anyone may
--     create files, but not delete files created by other users.
--
--     Originally the sticky bit on an executable file modified the
--     swapping policies of the system.  Normally, when a program
--     terminated, its pages in core were immediately freed and reused.
--     If the sticky bit was set on the executable file, the system kept
--     the pages in core for a while as if the program were still
--     running.  This was advantageous for a program likely to be run
--     many times in succession.  This usage is obsolete in modern
--     systems.  When a program terminates, its pages always remain in
--     core as long as there is no shortage of memory in the system.
--     When the program is next run, its pages will still be in core if
--     no shortage arose since the last run.
--
--     On some modern systems where the sticky bit has no useful meaning
--     for an executable file, you cannot set the bit at all for a
--     non-directory.  If you try, `chmod' fails with `EFTYPE'; *note
--     Setting Permissions::..
--
--     Some systems (particularly SunOS) have yet another use for the
--     sticky bit.  If the sticky bit is set on a file that is *not*
--     executable, it means the opposite: never cache the pages of this
--     file at all.  The main use of this is for the files on an NFS
--     server machine which are used as the swap area of diskless client
--     machines.  The idea is that the pages of the file will be cached
--     in the client's memory, so it is a waste of the server's memory to
--     cache them a second time.  In this use the sticky bit also says
--     that the filesystem may fail to record the file's modification
--     time onto disk reliably (the idea being that noone cares for a
--     swap file).
--
--   The actual bit values of the symbols are listed in the table above
--so you can decode file mode values when debugging your programs.  These
--bit values are correct for most systems, but they are not guaranteed.
--
--   *Warning:* Writing explicit numbers for file permissions is bad
--practice.  It is not only nonportable, it also requires everyone who
--reads your program to remember what the bits mean.  To make your
--program clean, use the symbolic names.
--
--
--File: libc.info,  Node: Access Permission,  Next: Setting Permissions,  Prev: 
Permission Bits,  Up: File Attributes
--
--How Your Access to a File is Decided
--------------------------------------
--
--   Recall that the operating system normally decides access permission
--for a file based on the effective user and group IDs of the process,
--and its supplementary group IDs, together with the file's owner, group
--and permission bits.  These concepts are discussed in detail in *Note
--Process Persona::.
--
--   If the effective user ID of the process matches the owner user ID of
--the file, then permissions for read, write, and execute/search are
--controlled by the corresponding "user" (or "owner") bits.  Likewise, if
--any of the effective group ID or supplementary group IDs of the process
--matches the group owner ID of the file, then permissions are controlled
--by the "group" bits.  Otherwise, permissions are controlled by the
--"other" bits.
--
--   Privileged users, like `root', can access any file, regardless of
--its file permission bits.  As a special case, for a file to be
--executable even for a privileged user, at least one of its execute bits
--must be set.
--
--
--File: libc.info,  Node: Setting Permissions,  Next: Testing File Access,  
Prev: Access Permission,  Up: File Attributes
--
--Assigning File Permissions
----------------------------
--
--   The primitive functions for creating files (for example, `open' or
--`mkdir') take a MODE argument, which specifies the file permissions for
--the newly created file.  But the specified mode is modified by the
--process's "file creation mask", or "umask", before it is used.
--
--   The bits that are set in the file creation mask identify permissions
--that are always to be disabled for newly created files.  For example, if
--you set all the "other" access bits in the mask, then newly created
--files are not accessible at all to processes in the "other" category,
--even if the MODE argument specified to the creation function would
--permit such access.  In other words, the file creation mask is the
--complement of the ordinary access permissions you want to grant.
--
--   Programs that create files typically specify a MODE argument that
--includes all the permissions that make sense for the particular file.
--For an ordinary file, this is typically read and write permission for
--all classes of users.  These permissions are then restricted as
--specified by the individual user's own file creation mask.
--
--   To change the permission of an existing file given its name, call
--`chmod'.  This function ignores the file creation mask; it uses exactly
--the specified permission bits.
--
--   In normal use, the file creation mask is initialized in the user's
--login shell (using the `umask' shell command), and inherited by all
--subprocesses.  Application programs normally don't need to worry about
--the file creation mask.  It will do automatically what it is supposed to
--do.
--
--   When your program should create a file and bypass the umask for its
--access permissions, the easiest way to do this is to use `fchmod' after
--opening the file, rather than changing the umask.
--
--   In fact, changing the umask is usually done only by shells.  They use
--the `umask' function.
--
--   The functions in this section are declared in `sys/stat.h'.
--
-- - Function: mode_t umask (mode_t MASK)
--     The `umask' function sets the file creation mask of the current
--     process to MASK, and returns the previous value of the file
--     creation mask.
--
--     Here is an example showing how to read the mask with `umask'
--     without changing it permanently:
--
--          mode_t
--          read_umask (void)
--          {
--            mask = umask (0);
--            umask (mask);
--          }
--
--     However, it is better to use `getumask' if you just want to read
--     the mask value, because that is reentrant (at least if you use the
--     GNU operating system).
--
-- - Function: mode_t getumask (void)
--     Return the current value of the file creation mask for the current
--     process.  This function is a GNU extension.
--
-- - Function: int chmod (const char *FILENAME, mode_t MODE)
--     The `chmod' function sets the access permission bits for the file
--     named by FILENAME to MODE.
--
--     If the FILENAME names a symbolic link, `chmod' changes the
--     permission of the file pointed to by the link, not those of the
--     link itself.
--
--     This function returns `0' if successful and `-1' if not.  In
--     addition to the usual file name errors (*note File Name
--     Errors::.), the following `errno' error conditions are defined for
--     this function:
--
--    `ENOENT'
--          The named file doesn't exist.
--
--    `EPERM'
--          This process does not have permission to change the access
--          permission of this file.  Only the file's owner (as judged by
--          the effective user ID of the process) or a privileged user
--          can change them.
--
--    `EROFS'
--          The file resides on a read-only file system.
--
--    `EFTYPE'
--          MODE has the `S_ISVTX' bit (the "sticky bit") set, and the
--          named file is not a directory.  Some systems do not allow
--          setting the sticky bit on non-directory files, and some do
--          (and only some of those assign a useful meaning to the bit
--          for non-directory files).
--
--          You only get `EFTYPE' on systems where the sticky bit has no
--          useful meaning for non-directory files, so it is always safe
--          to just clear the bit in MODE and call `chmod' again.  *Note
--          Permission Bits::, for full details on the sticky bit.
--
-- - Function: int fchmod (int FILEDES, int MODE)
--     This is like `chmod', except that it changes the permissions of
--     the file currently open via descriptor FILEDES.
--
--     The return value from `fchmod' is `0' on success and `-1' on
--     failure.  The following `errno' error codes are defined for this
--     function:
--
--    `EBADF'
--          The FILEDES argument is not a valid file descriptor.
--
--    `EINVAL'
--          The FILEDES argument corresponds to a pipe or socket, or
--          something else that doesn't really have access permissions.
--
--    `EPERM'
--          This process does not have permission to change the access
--          permission of this file.  Only the file's owner (as judged by
--          the effective user ID of the process) or a privileged user
--          can change them.
--
--    `EROFS'
--          The file resides on a read-only file system.
--
--
--File: libc.info,  Node: Testing File Access,  Next: File Times,  Prev: 
Setting Permissions,  Up: File Attributes
--
--Testing Permission to Access a File
-------------------------------------
--
--   When a program runs as a privileged user, this permits it to access
--files off-limits to ordinary users--for example, to modify
--`/etc/passwd'.  Programs designed to be run by ordinary users but
--access such files use the setuid bit feature so that they always run
--with `root' as the effective user ID.
--
--   Such a program may also access files specified by the user, files
--which conceptually are being accessed explicitly by the user.  Since the
--program runs as `root', it has permission to access whatever file the
--user specifies--but usually the desired behavior is to permit only
--those files which the user could ordinarily access.
--
--   The program therefore must explicitly check whether *the user* would
--have the necessary access to a file, before it reads or writes the file.
--
--   To do this, use the function `access', which checks for access
--permission based on the process's *real* user ID rather than the
--effective user ID.  (The setuid feature does not alter the real user ID,
--so it reflects the user who actually ran the program.)
--
--   There is another way you could check this access, which is easy to
--describe, but very hard to use.  This is to examine the file mode bits
--and mimic the system's own access computation.  This method is
--undesirable because many systems have additional access control
--features; your program cannot portably mimic them, and you would not
--want to try to keep track of the diverse features that different systems
--have.  Using `access' is simple and automatically does whatever is
--appropriate for the system you are using.
--
--   `access' is *only* only appropriate to use in setuid programs.  A
--non-setuid program will always use the effective ID rather than the
--real ID.
--
--   The symbols in this section are declared in `unistd.h'.
--
-- - Function: int access (const char *FILENAME, int HOW)
--     The `access' function checks to see whether the file named by
--     FILENAME can be accessed in the way specified by the HOW argument.
--     The HOW argument either can be the bitwise OR of the flags
--     `R_OK', `W_OK', `X_OK', or the existence test `F_OK'.
--
--     This function uses the *real* user and group ID's of the calling
--     process, rather than the *effective* ID's, to check for access
--     permission.  As a result, if you use the function from a `setuid'
--     or `setgid' program (*note How Change Persona::.), it gives
--     information relative to the user who actually ran the program.
--
--     The return value is `0' if the access is permitted, and `-1'
--     otherwise.  (In other words, treated as a predicate function,
--     `access' returns true if the requested access is *denied*.)
--
--     In addition to the usual file name errors (*note File Name
--     Errors::.), the following `errno' error conditions are defined for
--     this function:
--
--    `EACCES'
--          The access specified by HOW is denied.
--
--    `ENOENT'
--          The file doesn't exist.
--
--    `EROFS'
--          Write permission was requested for a file on a read-only file
--          system.
--
--   These macros are defined in the header file `unistd.h' for use as
--the HOW argument to the `access' function.  The values are integer
--constants.
--
-- - Macro: int R_OK
--     Argument that means, test for read permission.
--
-- - Macro: int W_OK
--     Argument that means, test for write permission.
--
-- - Macro: int X_OK
--     Argument that means, test for execute/search permission.
--
-- - Macro: int F_OK
--     Argument that means, test for existence of the file.
--
--
--File: libc.info,  Node: File Times,  Prev: Testing File Access,  Up: File 
Attributes
--
--File Times
------------
--
--   Each file has three timestamps associated with it:  its access time,
--its modification time, and its attribute modification time.  These
--correspond to the `st_atime', `st_mtime', and `st_ctime' members of the
--`stat' structure; see *Note File Attributes::.
--
--   All of these times are represented in calendar time format, as
--`time_t' objects.  This data type is defined in `time.h'.  For more
--information about representation and manipulation of time values, see
--*Note Calendar Time::.
--
--   Reading from a file updates its access time attribute, and writing
--updates its modification time.  When a file is created, all three
--timestamps for that file are set to the current time.  In addition, the
--attribute change time and modification time fields of the directory that
--contains the new entry are updated.
--
--   Adding a new name for a file with the `link' function updates the
--attribute change time field of the file being linked, and both the
--attribute change time and modification time fields of the directory
--containing the new name.  These same fields are affected if a file name
--is deleted with `unlink', `remove', or `rmdir'.  Renaming a file with
--`rename' affects only the attribute change time and modification time
--fields of the two parent directories involved, and not the times for
--the file being renamed.
--
--   Changing attributes of a file (for example, with `chmod') updates
--its attribute change time field.
--
--   You can also change some of the timestamps of a file explicitly using
--the `utime' function--all except the attribute change time.  You need
--to include the header file `utime.h' to use this facility.
--
-- - Data Type: struct utimbuf
--     The `utimbuf' structure is used with the `utime' function to
--     specify new access and modification times for a file.  It contains
--     the following members:
--
--    `time_t actime'
--          This is the access time for the file.
--
--    `time_t modtime'
--          This is the modification time for the file.
--
-- - Function: int utime (const char *FILENAME, const struct utimbuf
--          *TIMES)
--     This function is used to modify the file times associated with the
--     file named FILENAME.
--
--     If TIMES is a null pointer, then the access and modification times
--     of the file are set to the current time.  Otherwise, they are set
--     to the values from the `actime' and `modtime' members
--     (respectively) of the `utimbuf' structure pointed at by TIMES.
--
--     The attribute modification time for the file is set to the current
--     time in either case (since changing the timestamps is itself a
--     modification of the file attributes).
--
--     The `utime' function returns `0' if successful and `-1' on
--     failure.  In addition to the usual file name errors (*note File
--     Name Errors::.), the following `errno' error conditions are
--     defined for this function:
--
--    `EACCES'
--          There is a permission problem in the case where a null
--          pointer was passed as the TIMES argument.  In order to update
--          the timestamp on the file, you must either be the owner of
--          the file, have write permission on the file, or be a
--          privileged user.
--
--    `ENOENT'
--          The file doesn't exist.
--
--    `EPERM'
--          If the TIMES argument is not a null pointer, you must either
--          be the owner of the file or be a privileged user.  This error
--          is used to report the problem.
--
--    `EROFS'
--          The file lives on a read-only file system.
--
--   Each of the three time stamps has a corresponding microsecond part,
--which extends its resolution.  These fields are called `st_atime_usec',
--`st_mtime_usec', and `st_ctime_usec'; each has a value between 0 and
--999,999, which indicates the time in microseconds.  They correspond to
--the `tv_usec' field of a `timeval' structure; see *Note High-Resolution
--Calendar::.
--
--   The `utimes' function is like `utime', but also lets you specify the
--fractional part of the file times.  The prototype for this function is
--in the header file `sys/time.h'.
--
-- - Function: int utimes (const char *FILENAME, struct timeval TVP[2])
--     This function sets the file access and modification times for the
--     file named by FILENAME.  The new file access time is specified by
--     `TVP[0]', and the new modification time by `TVP[1]'.  This
--     function comes from BSD.
--
--     The return values and error conditions are the same as for the
--     `utime' function.
--
--
--File: libc.info,  Node: Making Special Files,  Next: Temporary Files,  Prev: 
File Attributes,  Up: File System Interface
--
--Making Special Files
--====================
--
--   The `mknod' function is the primitive for making special files, such
--as files that correspond to devices.  The GNU library includes this
--function for compatibility with BSD.
--
--   The prototype for `mknod' is declared in `sys/stat.h'.
--
-- - Function: int mknod (const char *FILENAME, int MODE, int DEV)
--     The `mknod' function makes a special file with name FILENAME.  The
--     MODE specifies the mode of the file, and may include the various
--     special file bits, such as `S_IFCHR' (for a character special file)
--     or `S_IFBLK' (for a block special file).  *Note Testing File
--     Type::.
--
--     The DEV argument specifies which device the special file refers to.
--     Its exact interpretation depends on the kind of special file being
--     created.
--
--     The return value is `0' on success and `-1' on error.  In addition
--     to the usual file name errors (*note File Name Errors::.), the
--     following `errno' error conditions are defined for this function:
--
--    `EPERM'
--          The calling process is not privileged.  Only the superuser
--          can create special files.
--
--    `ENOSPC'
--          The directory or file system that would contain the new file
--          is full and cannot be extended.
--
--    `EROFS'
--          The directory containing the new file can't be modified
--          because it's on a read-only file system.
--
--    `EEXIST'
--          There is already a file named FILENAME.  If you want to
--          replace this file, you must remove the old file explicitly
--          first.
--
--
--File: libc.info,  Node: Temporary Files,  Prev: Making Special Files,  Up: 
File System Interface
--
--Temporary Files
--===============
--
--   If you need to use a temporary file in your program, you can use the
--`tmpfile' function to open it.  Or you can use the `tmpnam' (better:
--`tmpnam_r') function make a name for a temporary file and then open it
--in the usual way with `fopen'.
--
--   The `tempnam' function is like `tmpnam' but lets you choose what
--directory temporary files will go in, and something about what their
--file names will look like.  Important for multi threaded programs is
--that `tempnam' is reentrant while `tmpnam' is not since it returns a
--pointer to a static buffer.
--
--   These facilities are declared in the header file `stdio.h'.
--
-- - Function: FILE * tmpfile (void)
--     This function creates a temporary binary file for update mode, as
--     if by calling `fopen' with mode `"wb+"'.  The file is deleted
--     automatically when it is closed or when the program terminates.
--     (On some other ISO C systems the file may fail to be deleted if
--     the program terminates abnormally).
--
--     This function is reentrant.
--
-- - Function: char * tmpnam (char *RESULT)
--     This function constructs and returns a file name that is a valid
--     file name and that does not name any existing file.  If the RESULT
--     argument is a null pointer, the return value is a pointer to an
--     internal static string, which might be modified by subsequent
--     calls and therefore makes this function non-reentrant.  Otherwise,
--     the RESULT argument should be a pointer to an array of at least
--     `L_tmpnam' characters, and the result is written into that array.
--
--     It is possible for `tmpnam' to fail if you call it too many times
--     without removing previously created files.  This is because the
--     fixed length of a temporary file name gives room for only a finite
--     number of different names.  If `tmpnam' fails, it returns a null
--     pointer.
--
-- - Function: char * tmpnam_r (char *RESULT)
--     This function is nearly identical to the `tmpnam' function.  But it
--     does not allow RESULT to be a null pointer.  In the later case a
--     null pointer is returned.
--
--     This function is reentrant because the non-reentrant situation of
--     `tmpnam' cannot happen here.
--
-- - Macro: int L_tmpnam
--     The value of this macro is an integer constant expression that
--     represents the minimum allocation size of a string large enough to
--     hold the file name generated by the `tmpnam' function.
--
-- - Macro: int TMP_MAX
--     The macro `TMP_MAX' is a lower bound for how many temporary names
--     you can create with `tmpnam'.  You can rely on being able to call
--     `tmpnam' at least this many times before it might fail saying you
--     have made too many temporary file names.
--
--     With the GNU library, you can create a very large number of
--     temporary file names--if you actually create the files, you will
--     probably run out of disk space before you run out of names.  Some
--     other systems have a fixed, small limit on the number of temporary
--     files.  The limit is never less than `25'.
--
-- - Function: char * tempnam (const char *DIR, const char *PREFIX)
--     This function generates a unique temporary filename.  If PREFIX is
--     not a null pointer, up to five characters of this string are used
--     as a prefix for the file name.  The return value is a string newly
--     allocated with `malloc'; you should release its storage with
--     `free' when it is no longer needed.
--
--     Because the string is dynamically allocated this function is
--     reentrant.
--
--     The directory prefix for the temporary file name is determined by
--     testing each of the following, in sequence.  The directory must
--     exist and be writable.
--
--        * The environment variable `TMPDIR', if it is defined.  For
--          security reasons this only happens if the program is not SUID
--          or SGID enabled.
--
--        * The DIR argument, if it is not a null pointer.
--
--        * The value of the `P_tmpdir' macro.
--
--        * The directory `/tmp'.
--
--     This function is defined for SVID compatibility.
--
-- - SVID Macro: char * P_tmpdir
--     This macro is the name of the default directory for temporary
--     files.
--
--   Older Unix systems did not have the functions just described.
--Instead they used `mktemp' and `mkstemp'.  Both of these functions work
--by modifying a file name template string you pass.  The last six
--characters of this string must be `XXXXXX'.  These six `X's are
--replaced with six characters which make the whole string a unique file
--name.  Usually the template string is something like
--`/tmp/PREFIXXXXXXX', and each program uses a unique PREFIX.
--
--   *Note:* Because `mktemp' and `mkstemp' modify the template string,
--you *must not* pass string constants to them.  String constants are
--normally in read-only storage, so your program would crash when
--`mktemp' or `mkstemp' tried to modify the string.
--
-- - Function: char * mktemp (char *TEMPLATE)
--     The `mktemp' function generates a unique file name by modifying
--     TEMPLATE as described above.  If successful, it returns TEMPLATE
--     as modified.  If `mktemp' cannot find a unique file name, it makes
--     TEMPLATE an empty string and returns that.  If TEMPLATE does not
--     end with `XXXXXX', `mktemp' returns a null pointer.
--
-- - Function: int mkstemp (char *TEMPLATE)
--     The `mkstemp' function generates a unique file name just as
--     `mktemp' does, but it also opens the file for you with `open'
--     (*note Opening and Closing Files::.).  If successful, it modifies
--     TEMPLATE in place and returns a file descriptor open on that file
--     for reading and writing.  If `mkstemp' cannot create a
--     uniquely-named file, it makes TEMPLATE an empty string and returns
--     `-1'.  If TEMPLATE does not end with `XXXXXX', `mkstemp' returns
--     `-1' and does not modify TEMPLATE.
--
--   Unlike `mktemp', `mkstemp' is actually guaranteed to create a unique
--file that cannot possibly clash with any other program trying to create
--a temporary file.  This is because it works by calling `open' with the
--`O_EXCL' flag bit, which says you want to always create a new file, and
--get an error if the file already exists.
--
--
--File: libc.info,  Node: Pipes and FIFOs,  Next: Sockets,  Prev: File System 
Interface,  Up: Top
--
--Pipes and FIFOs
--***************
--
--   A "pipe" is a mechanism for interprocess communication; data written
--to the pipe by one process can be read by another process.  The data is
--handled in a first-in, first-out (FIFO) order.  The pipe has no name; it
--is created for one use and both ends must be inherited from the single
--process which created the pipe.
--
--   A "FIFO special file" is similar to a pipe, but instead of being an
--anonymous, temporary connection, a FIFO has a name or names like any
--other file.  Processes open the FIFO by name in order to communicate
--through it.
--
--   A pipe or FIFO has to be open at both ends simultaneously.  If you
--read from a pipe or FIFO file that doesn't have any processes writing
--to it (perhaps because they have all closed the file, or exited), the
--read returns end-of-file.  Writing to a pipe or FIFO that doesn't have a
--reading process is treated as an error condition; it generates a
--`SIGPIPE' signal, and fails with error code `EPIPE' if the signal is
--handled or blocked.
--
--   Neither pipes nor FIFO special files allow file positioning.  Both
--reading and writing operations happen sequentially; reading from the
--beginning of the file and writing at the end.
--
--* Menu:
--
--* Creating a Pipe::             Making a pipe with the `pipe' function.
--* Pipe to a Subprocess::        Using a pipe to communicate with a
--                               child process.
--* FIFO Special Files::          Making a FIFO special file.
--* Pipe Atomicity::            When pipe (or FIFO) I/O is atomic.
--
--
--File: libc.info,  Node: Creating a Pipe,  Next: Pipe to a Subprocess,  Up: 
Pipes and FIFOs
--
--Creating a Pipe
--===============
--
--   The primitive for creating a pipe is the `pipe' function.  This
--creates both the reading and writing ends of the pipe.  It is not very
--useful for a single process to use a pipe to talk to itself.  In typical
--use, a process creates a pipe just before it forks one or more child
--processes (*note Creating a Process::.).  The pipe is then used for
--communication either between the parent or child processes, or between
--two sibling processes.
--
--   The `pipe' function is declared in the header file `unistd.h'.
--
-- - Function: int pipe (int FILEDES[2])
--     The `pipe' function creates a pipe and puts the file descriptors
--     for the reading and writing ends of the pipe (respectively) into
--     `FILEDES[0]' and `FILEDES[1]'.
--
--     An easy way to remember that the input end comes first is that file
--     descriptor `0' is standard input, and file descriptor `1' is
--     standard output.
--
--     If successful, `pipe' returns a value of `0'.  On failure, `-1' is
--     returned.  The following `errno' error conditions are defined for
--     this function:
--
--    `EMFILE'
--          The process has too many files open.
--
--    `ENFILE'
--          There are too many open files in the entire system.  *Note
--          Error Codes::, for more information about `ENFILE'.  This
--          error never occurs in the GNU system.
--
--   Here is an example of a simple program that creates a pipe.  This
--program uses the `fork' function (*note Creating a Process::.) to create
--a child process.  The parent process writes data to the pipe, which is
--read by the child process.
--
--     #include <sys/types.h>
--     #include <unistd.h>
--     #include <stdio.h>
--     #include <stdlib.h>
--     
--     /* Read characters from the pipe and echo them to `stdout'. */
--     
--     void
--     read_from_pipe (int file)
--     {
--       FILE *stream;
--       int c;
--       stream = fdopen (file, "r");
--       while ((c = fgetc (stream)) != EOF)
--         putchar (c);
--       fclose (stream);
--     }
--     
--     /* Write some random text to the pipe. */
--     
--     void
--     write_to_pipe (int file)
--     {
--       FILE *stream;
--       stream = fdopen (file, "w");
--       fprintf (stream, "hello, world!\n");
--       fprintf (stream, "goodbye, world!\n");
--       fclose (stream);
--     }
--     
--     int
--     main (void)
--     {
--       pid_t pid;
--       int mypipe[2];
--     /* Create the pipe. */
--       if (pipe (mypipe))
--         {
--           fprintf (stderr, "Pipe failed.\n");
--           return EXIT_FAILURE;
--         }
--     
--       /* Create the child process. */
--       pid = fork ();
--       if (pid == (pid_t) 0)
--         {
--           /* This is the child process. */
--           read_from_pipe (mypipe[0]);
--           return EXIT_SUCCESS;
--         }
--       else if (pid < (pid_t) 0)
--         {
--           /* The fork failed. */
--           fprintf (stderr, "Fork failed.\n");
--           return EXIT_FAILURE;
--         }
--       else
--         {
--           /* This is the parent process. */
--           write_to_pipe (mypipe[1]);
--           return EXIT_SUCCESS;
--         }
--     }
--
--
--File: libc.info,  Node: Pipe to a Subprocess,  Next: FIFO Special Files,  
Prev: Creating a Pipe,  Up: Pipes and FIFOs
--
--Pipe to a Subprocess
--====================
--
--   A common use of pipes is to send data to or receive data from a
--program being run as subprocess.  One way of doing this is by using a
--combination of `pipe' (to create the pipe), `fork' (to create the
--subprocess), `dup2' (to force the subprocess to use the pipe as its
--standard input or output channel), and `exec' (to execute the new
--program).  Or, you can use `popen' and `pclose'.
--
--   The advantage of using `popen' and `pclose' is that the interface is
--much simpler and easier to use.  But it doesn't offer as much
--flexibility as using the low-level functions directly.
--
-- - Function: FILE * popen (const char *COMMAND, const char *MODE)
--     The `popen' function is closely related to the `system' function;
--     see *Note Running a Command::.  It executes the shell command
--     COMMAND as a subprocess.  However, instead of waiting for the
--     command to complete, it creates a pipe to the subprocess and
--     returns a stream that corresponds to that pipe.
--
--     If you specify a MODE argument of `"r"', you can read from the
--     stream to retrieve data from the standard output channel of the
--     subprocess.  The subprocess inherits its standard input channel
--     from the parent process.
--
--     Similarly, if you specify a MODE argument of `"w"', you can write
--     to the stream to send data to the standard input channel of the
--     subprocess.  The subprocess inherits its standard output channel
--     from the parent process.
--
--     In the event of an error, `popen' returns a null pointer.  This
--     might happen if the pipe or stream cannot be created, if the
--     subprocess cannot be forked, or if the program cannot be executed.
--
-- - Function: int pclose (FILE *STREAM)
--     The `pclose' function is used to close a stream created by `popen'.
--     It waits for the child process to terminate and returns its status
--     value, as for the `system' function.
--
--   Here is an example showing how to use `popen' and `pclose' to filter
--output through another program, in this case the paging program `more'.
--
--     #include <stdio.h>
--     #include <stdlib.h>
--     
--     void
--     write_data (FILE * stream)
--     {
--       int i;
--       for (i = 0; i < 100; i++)
--         fprintf (stream, "%d\n", i);
--       if (ferror (stream))
--         {
--           fprintf (stderr, "Output to stream failed.\n");
--           exit (EXIT_FAILURE);
--         }
--     }
--     int
--     main (void)
--     {
--       FILE *output;
--     
--       output = popen ("more", "w");
--       if (!output)
--         {
--           fprintf (stderr, "Could not run more.\n");
--           return EXIT_FAILURE;
--         }
--       write_data (output);
--       pclose (output);
--       return EXIT_SUCCESS;
--     }
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-12 
glibc-2.0.1/manual/libc.info-12
---- ../glibc-2.0.1/manual/libc.info-12 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-12    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1219 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: FIFO Special Files,  Next: Pipe Atomicity,  Prev: 
Pipe to a Subprocess,  Up: Pipes and FIFOs
--
--FIFO Special Files
--==================
--
--   A FIFO special file is similar to a pipe, except that it is created
--in a different way.  Instead of being an anonymous communications
--channel, a FIFO special file is entered into the file system by calling
--`mkfifo'.
--
--   Once you have created a FIFO special file in this way, any process
--can open it for reading or writing, in the same way as an ordinary file.
--However, it has to be open at both ends simultaneously before you can
--proceed to do any input or output operations on it.  Opening a FIFO for
--reading normally blocks until some other process opens the same FIFO for
--writing, and vice versa.
--
--   The `mkfifo' function is declared in the header file `sys/stat.h'.
--
-- - Function: int mkfifo (const char *FILENAME, mode_t MODE)
--     The `mkfifo' function makes a FIFO special file with name
--     FILENAME.  The MODE argument is used to set the file's
--     permissions; see *Note Setting Permissions::.
--
--     The normal, successful return value from `mkfifo' is `0'.  In the
--     case of an error, `-1' is returned.  In addition to the usual file
--     name errors (*note File Name Errors::.), the following `errno'
--     error conditions are defined for this function:
--
--    `EEXIST'
--          The named file already exists.
--
--    `ENOSPC'
--          The directory or file system cannot be extended.
--
--    `EROFS'
--          The directory that would contain the file resides on a
--          read-only file system.
--
--
--File: libc.info,  Node: Pipe Atomicity,  Prev: FIFO Special Files,  Up: Pipes 
and FIFOs
--
--Atomicity of Pipe I/O
--=====================
--
--   Reading or writing pipe data is "atomic" if the size of data written
--is not greater than `PIPE_BUF'.  This means that the data transfer
--seems to be an instantaneous unit, in that nothing else in the system
--can observe a state in which it is partially complete.  Atomic I/O may
--not begin right away (it may need to wait for buffer space or for data),
--but once it does begin, it finishes immediately.
--
--   Reading or writing a larger amount of data may not be atomic; for
--example, output data from other processes sharing the descriptor may be
--interspersed.  Also, once `PIPE_BUF' characters have been written,
--further writes will block until some characters are read.
--
--   *Note Limits for Files::, for information about the `PIPE_BUF'
--parameter.
--
--
--File: libc.info,  Node: Sockets,  Next: Low-Level Terminal Interface,  Prev: 
Pipes and FIFOs,  Up: Top
--
--Sockets
--*******
--
--   This chapter describes the GNU facilities for interprocess
--communication using sockets.
--
--   A "socket" is a generalized interprocess communication channel.
--Like a pipe, a socket is represented as a file descriptor.  But, unlike
--pipes, sockets support communication between unrelated processes, and
--even between processes running on different machines that communicate
--over a network.  Sockets are the primary means of communicating with
--other machines; `telnet', `rlogin', `ftp', `talk', and the other
--familiar network programs use sockets.
--
--   Not all operating systems support sockets.  In the GNU library, the
--header file `sys/socket.h' exists regardless of the operating system,
--and the socket functions always exist, but if the system does not
--really support sockets, these functions always fail.
--
--   *Incomplete:* We do not currently document the facilities for
--broadcast messages or for configuring Internet interfaces.
--
--* Menu:
--
--* Socket Concepts::   Basic concepts you need to know about.
--* Communication Styles::Stream communication, datagrams, and other styles.
--* Socket Addresses::  How socket names ("addresses") work.
--* File Namespace::    Details about the file namespace.
--* Internet Namespace::        Details about the Internet namespace.
--* Misc Namespaces::   Other namespaces not documented fully here.
--* Open/Close Sockets::  Creating sockets and destroying them.
--* Connections::               Operations on sockets with connection state.
--* Datagrams::         Operations on datagram sockets.
--* Inetd::             Inetd is a daemon that starts servers on request.
--                         The most convenient way to write a server
--                         is to make it work with Inetd.
--* Socket Options::    Miscellaneous low-level socket options.
--* Networks Database::   Accessing the database of network names.
--
--
--File: libc.info,  Node: Socket Concepts,  Next: Communication Styles,  Up: 
Sockets
--
--Socket Concepts
--===============
--
--   When you create a socket, you must specify the style of communication
--you want to use and the type of protocol that should implement it.  The
--"communication style" of a socket defines the user-level semantics of
--sending and receiving data on the socket.  Choosing a communication
--style specifies the answers to questions such as these:
--
--   * *What are the units of data transmission?*  Some communication
--     styles regard the data as a sequence of bytes, with no larger
--     structure; others group the bytes into records (which are known in
--     this context as "packets").
--
--   * *Can data be lost during normal operation?*  Some communication
--     styles guarantee that all the data sent arrives in the order it was
--     sent (barring system or network crashes); other styles occasionally
--     lose data as a normal part of operation, and may sometimes deliver
--     packets more than once or in the wrong order.
--
--     Designing a program to use unreliable communication styles usually
--     involves taking precautions to detect lost or misordered packets
--     and to retransmit data as needed.
--
--   * *Is communication entirely with one partner?*  Some communication
--     styles are like a telephone call--you make a "connection" with one
--     remote socket, and then exchange data freely.  Other styles are
--     like mailing letters--you specify a destination address for each
--     message you send.
--
--   You must also choose a "namespace" for naming the socket.  A socket
--name ("address") is meaningful only in the context of a particular
--namespace.  In fact, even the data type to use for a socket name may
--depend on the namespace.  Namespaces are also called "domains", but we
--avoid that word as it can be confused with other usage of the same
--term.  Each namespace has a symbolic name that starts with `PF_'.  A
--corresponding symbolic name starting with `AF_' designates the address
--format for that namespace.
--
--   Finally you must choose the "protocol" to carry out the
--communication.  The protocol determines what low-level mechanism is used
--to transmit and receive data.  Each protocol is valid for a particular
--namespace and communication style; a namespace is sometimes called a
--"protocol family" because of this, which is why the namespace names
--start with `PF_'.
--
--   The rules of a protocol apply to the data passing between two
--programs, perhaps on different computers; most of these rules are
--handled by the operating system, and you need not know about them.
--What you do need to know about protocols is this:
--
--   * In order to have communication between two sockets, they must
--     specify the *same* protocol.
--
--   * Each protocol is meaningful with particular style/namespace
--     combinations and cannot be used with inappropriate combinations.
--     For example, the TCP protocol fits only the byte stream style of
--     communication and the Internet namespace.
--
--   * For each combination of style and namespace, there is a "default
--     protocol" which you can request by specifying 0 as the protocol
--     number.  And that's what you should normally do--use the default.
--
--
--File: libc.info,  Node: Communication Styles,  Next: Socket Addresses,  Prev: 
Socket Concepts,  Up: Sockets
--
--Communication Styles
--====================
--
--   The GNU library includes support for several different kinds of
--sockets, each with different characteristics.  This section describes
--the supported socket types.  The symbolic constants listed here are
--defined in `sys/socket.h'.
--
-- - Macro: int SOCK_STREAM
--     The `SOCK_STREAM' style is like a pipe (*note Pipes and FIFOs::.);
--     it operates over a connection with a particular remote socket, and
--     transmits data reliably as a stream of bytes.
--
--     Use of this style is covered in detail in *Note Connections::.
--
-- - Macro: int SOCK_DGRAM
--     The `SOCK_DGRAM' style is used for sending individually-addressed
--     packets, unreliably.  It is the diametrical opposite of
--     `SOCK_STREAM'.
--
--     Each time you write data to a socket of this kind, that data
--     becomes one packet.  Since `SOCK_DGRAM' sockets do not have
--     connections, you must specify the recipient address with each
--     packet.
--
--     The only guarantee that the system makes about your requests to
--     transmit data is that it will try its best to deliver each packet
--     you send.  It may succeed with the sixth packet after failing with
--     the fourth and fifth packets; the seventh packet may arrive before
--     the sixth, and may arrive a second time after the sixth.
--
--     The typical use for `SOCK_DGRAM' is in situations where it is
--     acceptable to simply resend a packet if no response is seen in a
--     reasonable amount of time.
--
--     *Note Datagrams::, for detailed information about how to use
--     datagram sockets.
--
-- - Macro: int SOCK_RAW
--     This style provides access to low-level network protocols and
--     interfaces.  Ordinary user programs usually have no need to use
--     this style.
--
--
--File: libc.info,  Node: Socket Addresses,  Next: File Namespace,  Prev: 
Communication Styles,  Up: Sockets
--
--Socket Addresses
--================
--
--   The name of a socket is normally called an "address".  The functions
--and symbols for dealing with socket addresses were named
--inconsistently, sometimes using the term "name" and sometimes using
--"address".  You can regard these terms as synonymous where sockets are
--concerned.
--
--   A socket newly created with the `socket' function has no address.
--Other processes can find it for communication only if you give it an
--address.  We call this "binding" the address to the socket, and the way
--to do it is with the `bind' function.
--
--   You need be concerned with the address of a socket if other processes
--are to find it and start communicating with it.  You can specify an
--address for other sockets, but this is usually pointless; the first time
--you send data from a socket, or use it to initiate a connection, the
--system assigns an address automatically if you have not specified one.
--
--   Occasionally a client needs to specify an address because the server
--discriminates based on addresses; for example, the rsh and rlogin
--protocols look at the client's socket address and don't bypass password
--checking unless it is less than `IPPORT_RESERVED' (*note Ports::.).
--
--   The details of socket addresses vary depending on what namespace you
--are using.  *Note File Namespace::, or *Note Internet Namespace::, for
--specific information.
--
--   Regardless of the namespace, you use the same functions `bind' and
--`getsockname' to set and examine a socket's address.  These functions
--use a phony data type, `struct sockaddr *', to accept the address.  In
--practice, the address lives in a structure of some other data type
--appropriate to the address format you are using, but you cast its
--address to `struct sockaddr *' when you pass it to `bind'.
--
--* Menu:
--
--* Address Formats::           About `struct sockaddr'.
--* Setting Address::           Binding an address to a socket.
--* Reading Address::           Reading the address of a socket.
--
--
--File: libc.info,  Node: Address Formats,  Next: Setting Address,  Up: Socket 
Addresses
--
--Address Formats
-----------------
--
--   The functions `bind' and `getsockname' use the generic data type
--`struct sockaddr *' to represent a pointer to a socket address.  You
--can't use this data type effectively to interpret an address or
--construct one; for that, you must use the proper data type for the
--socket's namespace.
--
--   Thus, the usual practice is to construct an address in the proper
--namespace-specific type, then cast a pointer to `struct sockaddr *'
--when you call `bind' or `getsockname'.
--
--   The one piece of information that you can get from the `struct
--sockaddr' data type is the "address format" designator which tells you
--which data type to use to understand the address fully.
--
--   The symbols in this section are defined in the header file
--`sys/socket.h'.
--
-- - Date Type: struct sockaddr
--     The `struct sockaddr' type itself has the following members:
--
--    `short int sa_family'
--          This is the code for the address format of this address.  It
--          identifies the format of the data which follows.
--
--    `char sa_data[14]'
--          This is the actual socket address data, which is
--          format-dependent.  Its length also depends on the format, and
--          may well be more than 14.  The length 14 of `sa_data' is
--          essentially arbitrary.
--
--   Each address format has a symbolic name which starts with `AF_'.
--Each of them corresponds to a `PF_' symbol which designates the
--corresponding namespace.  Here is a list of address format names:
--
--`AF_FILE'
--     This designates the address format that goes with the file
--     namespace.  (`PF_FILE' is the name of that namespace.)  *Note File
--     Namespace Details::, for information about this address format.
--
--`AF_UNIX'
--     This is a synonym for `AF_FILE', for compatibility.  (`PF_UNIX' is
--     likewise a synonym for `PF_FILE'.)
--
--`AF_INET'
--     This designates the address format that goes with the Internet
--     namespace.  (`PF_INET' is the name of that namespace.) *Note
--     Internet Address Format::.
--
--`AF_UNSPEC'
--     This designates no particular address format.  It is used only in
--     rare cases, such as to clear out the default destination address
--     of a "connected" datagram socket.  *Note Sending Datagrams::.
--
--     The corresponding namespace designator symbol `PF_UNSPEC' exists
--     for completeness, but there is no reason to use it in a program.
--
--   `sys/socket.h' defines symbols starting with `AF_' for many
--different kinds of networks, all or most of which are not actually
--implemented.  We will document those that really work, as we receive
--information about how to use them.
--
--
--File: libc.info,  Node: Setting Address,  Next: Reading Address,  Prev: 
Address Formats,  Up: Socket Addresses
--
--Setting the Address of a Socket
---------------------------------
--
--   Use the `bind' function to assign an address to a socket.  The
--prototype for `bind' is in the header file `sys/socket.h'.  For
--examples of use, see *Note File Namespace::, or see *Note Inet
--Example::.
--
-- - Function: int bind (int SOCKET, struct sockaddr *ADDR, size_t LENGTH)
--     The `bind' function assigns an address to the socket SOCKET.  The
--     ADDR and LENGTH arguments specify the address; the detailed format
--     of the address depends on the namespace.  The first part of the
--     address is always the format designator, which specifies a
--     namespace, and says that the address is in the format for that
--     namespace.
--
--     The return value is `0' on success and `-1' on failure.  The
--     following `errno' error conditions are defined for this function:
--
--    `EBADF'
--          The SOCKET argument is not a valid file descriptor.
--
--    `ENOTSOCK'
--          The descriptor SOCKET is not a socket.
--
--    `EADDRNOTAVAIL'
--          The specified address is not available on this machine.
--
--    `EADDRINUSE'
--          Some other socket is already using the specified address.
--
--    `EINVAL'
--          The socket SOCKET already has an address.
--
--    `EACCES'
--          You do not have permission to access the requested address.
--          (In the Internet domain, only the super-user is allowed to
--          specify a port number in the range 0 through
--          `IPPORT_RESERVED' minus one; see *Note Ports::.)
--
--     Additional conditions may be possible depending on the particular
--     namespace of the socket.
--
--
--File: libc.info,  Node: Reading Address,  Prev: Setting Address,  Up: Socket 
Addresses
--
--Reading the Address of a Socket
---------------------------------
--
--   Use the function `getsockname' to examine the address of an Internet
--socket.  The prototype for this function is in the header file
--`sys/socket.h'.
--
-- - Function: int getsockname (int SOCKET, struct sockaddr *ADDR, size_t
--          *LENGTH-PTR)
--     The `getsockname' function returns information about the address
--     of the socket SOCKET in the locations specified by the ADDR and
--     LENGTH-PTR arguments.  Note that the LENGTH-PTR is a pointer; you
--     should initialize it to be the allocation size of ADDR, and on
--     return it contains the actual size of the address data.
--
--     The format of the address data depends on the socket namespace.
--     The length of the information is usually fixed for a given
--     namespace, so normally you can know exactly how much space is
--     needed and can provide that much.  The usual practice is to
--     allocate a place for the value using the proper data type for the
--     socket's namespace, then cast its address to `struct sockaddr *'
--     to pass it to `getsockname'.
--
--     The return value is `0' on success and `-1' on error.  The
--     following `errno' error conditions are defined for this function:
--
--    `EBADF'
--          The SOCKET argument is not a valid file descriptor.
--
--    `ENOTSOCK'
--          The descriptor SOCKET is not a socket.
--
--    `ENOBUFS'
--          There are not enough internal buffers available for the
--          operation.
--
--   You can't read the address of a socket in the file namespace.  This
--is consistent with the rest of the system; in general, there's no way to
--find a file's name from a descriptor for that file.
--
--
--File: libc.info,  Node: File Namespace,  Next: Internet Namespace,  Prev: 
Socket Addresses,  Up: Sockets
--
--The File Namespace
--==================
--
--   This section describes the details of the file namespace, whose
--symbolic name (required when you create a socket) is `PF_FILE'.
--
--* Menu:
--
--* Concepts: File Namespace Concepts.  What you need to understand.
--* Details: File Namespace Details.    Address format, symbolic names, etc.
--* Example: File Socket Example.               Example of creating a socket.
--
--
--File: libc.info,  Node: File Namespace Concepts,  Next: File Namespace 
Details,  Up: File Namespace
--
--File Namespace Concepts
-------------------------
--
--   In the file namespace, socket addresses are file names.  You can
--specify any file name you want as the address of the socket, but you
--must have write permission on the directory containing it.  In order to
--connect to a socket, you must have read permission for it.  It's common
--to put these files in the `/tmp' directory.
--
--   One peculiarity of the file namespace is that the name is only used
--when opening the connection; once that is over with, the address is not
--meaningful and may not exist.
--
--   Another peculiarity is that you cannot connect to such a socket from
--another machine-not even if the other machine shares the file system
--which contains the name of the socket.  You can see the socket in a
--directory listing, but connecting to it never succeeds.  Some programs
--take advantage of this, such as by asking the client to send its own
--process ID, and using the process IDs to distinguish between clients.
--However, we recommend you not use this method in protocols you design,
--as we might someday permit connections from other machines that mount
--the same file systems.  Instead, send each new client an identifying
--number if you want it to have one.
--
--   After you close a socket in the file namespace, you should delete the
--file name from the file system.  Use `unlink' or `remove' to do this;
--see *Note Deleting Files::.
--
--   The file namespace supports just one protocol for any communication
--style; it is protocol number `0'.
--
--
--File: libc.info,  Node: File Namespace Details,  Next: File Socket Example,  
Prev: File Namespace Concepts,  Up: File Namespace
--
--Details of File Namespace
---------------------------
--
--   To create a socket in the file namespace, use the constant `PF_FILE'
--as the NAMESPACE argument to `socket' or `socketpair'.  This constant
--is defined in `sys/socket.h'.
--
-- - Macro: int PF_FILE
--     This designates the file namespace, in which socket addresses are
--     file names, and its associated family of protocols.
--
-- - Macro: int PF_UNIX
--     This is a synonym for `PF_FILE', for compatibility's sake.
--
--   The structure for specifying socket names in the file namespace is
--defined in the header file `sys/un.h':
--
-- - Data Type: struct sockaddr_un
--     This structure is used to specify file namespace socket addresses.
--     It has the following members:
--
--    `short int sun_family'
--          This identifies the address family or format of the socket
--          address.  You should store the value `AF_FILE' to designate
--          the file namespace.  *Note Socket Addresses::.
--
--    `char sun_path[108]'
--          This is the file name to use.
--
--          *Incomplete:*  Why is 108 a magic number?  RMS suggests making
--          this a zero-length array and tweaking the example following
--          to use `alloca' to allocate an appropriate amount of storage
--          based on the length of the filename.
--
--   You should compute the LENGTH parameter for a socket address in the
--file namespace as the sum of the size of the `sun_family' component and
--the string length (*not* the allocation size!) of the file name string.
--
--
--File: libc.info,  Node: File Socket Example,  Prev: File Namespace Details,  
Up: File Namespace
--
--Example of File-Namespace Sockets
-----------------------------------
--
--   Here is an example showing how to create and name a socket in the
--file namespace.
--
--     #include <stddef.h>
--     #include <stdio.h>
--     #include <errno.h>
--     #include <stdlib.h>
--     #include <sys/socket.h>
--     #include <sys/un.h>
--     
--     int
--     make_named_socket (const char *filename)
--     {
--       struct sockaddr_un name;
--       int sock;
--       size_t size;
--     
--       /* Create the socket. */
--     
--       sock = socket (PF_UNIX, SOCK_DGRAM, 0);
--       if (sock < 0)
--         {
--           perror ("socket");
--           exit (EXIT_FAILURE);
--         }
--     
--       /* Bind a name to the socket. */
--     
--       name.sun_family = AF_FILE;
--       strcpy (name.sun_path, filename);
--     
--       /* The size of the address is
--          the offset of the start of the filename,
--          plus its length,
--          plus one for the terminating null byte. */
--       size = (offsetof (struct sockaddr_un, sun_path)
--               + strlen (name.sun_path) + 1);
--     
--       if (bind (sock, (struct sockaddr *) &name, size) < 0)
--         {
--           perror ("bind");
--           exit (EXIT_FAILURE);
--         }
--     
--       return sock;
--     }
--
--
--File: libc.info,  Node: Internet Namespace,  Next: Misc Namespaces,  Prev: 
File Namespace,  Up: Sockets
--
--The Internet Namespace
--======================
--
--   This section describes the details the protocols and socket naming
--conventions used in the Internet namespace.
--
--   To create a socket in the Internet namespace, use the symbolic name
--`PF_INET' of this namespace as the NAMESPACE argument to `socket' or
--`socketpair'.  This macro is defined in `sys/socket.h'.
--
-- - Macro: int PF_INET
--     This designates the Internet namespace and associated family of
--     protocols.
--
--   A socket address for the Internet namespace includes the following
--components:
--
--   * The address of the machine you want to connect to.  Internet
--     addresses can be specified in several ways; these are discussed in
--     *Note Internet Address Format::, *Note Host Addresses::, and *Note
--     Host Names::.
--
--   * A port number for that machine.  *Note Ports::.
--
--   You must ensure that the address and port number are represented in a
--canonical format called "network byte order".  *Note Byte Order::, for
--information about this.
--
--* Menu:
--
--* Internet Address Format::     How socket addresses are specified in the
--                                 Internet namespace.
--* Host Addresses::            All about host addresses of internet host.
--* Protocols Database::                Referring to protocols by name.
--* Ports::                     Internet port numbers.
--* Services Database::           Ports may have symbolic names.
--* Byte Order::                        Different hosts may use different byte
--                                 ordering conventions; you need to
--                                 canonicalize host address and port number.
--* Inet Example::              Putting it all together.
--
--
--File: libc.info,  Node: Internet Address Format,  Next: Host Addresses,  Up: 
Internet Namespace
--
--Internet Socket Address Format
--------------------------------
--
--   In the Internet namespace, a socket address consists of a host
--address and a port on that host.  In addition, the protocol you choose
--serves effectively as a part of the address because local port numbers
--are meaningful only within a particular protocol.
--
--   The data type for representing socket addresses in the Internet
--namespace is defined in the header file `netinet/in.h'.
--
-- - Data Type: struct sockaddr_in
--     This is the data type used to represent socket addresses in the
--     Internet namespace.  It has the following members:
--
--    `short int sin_family'
--          This identifies the address family or format of the socket
--          address.  You should store the value of `AF_INET' in this
--          member.  *Note Socket Addresses::.
--
--    `struct in_addr sin_addr'
--          This is the Internet address of the host machine.  *Note Host
--          Addresses::, and *Note Host Names::, for how to get a value
--          to store here.
--
--    `unsigned short int sin_port'
--          This is the port number.  *Note Ports::.
--
--   When you call `bind' or `getsockname', you should specify `sizeof
--(struct sockaddr_in)' as the LENGTH parameter if you are using an
--Internet namespace socket address.
--
--
--File: libc.info,  Node: Host Addresses,  Next: Protocols Database,  Prev: 
Internet Address Format,  Up: Internet Namespace
--
--Host Addresses
----------------
--
--   Each computer on the Internet has one or more "Internet addresses",
--numbers which identify that computer among all those on the Internet.
--Users typically write numeric host addresses as sequences of four
--numbers, separated by periods, as in `128.52.46.32'.
--
--   Each computer also has one or more "host names", which are strings
--of words separated by periods, as in `churchy.gnu.ai.mit.edu'.
--
--   Programs that let the user specify a host typically accept both
--numeric addresses and host names.  But the program needs a numeric
--address to open a connection; to use a host name, you must convert it
--to the numeric address it stands for.
--
--* Menu:
--
--* Abstract Host Addresses::   What a host number consists of.
--* Data type: Host Address Data Type.  Data type for a host number.
--* Functions: Host Address Functions.  Functions to operate on them.
--* Names: Host Names.          Translating host names to host numbers.
--
--
--File: libc.info,  Node: Abstract Host Addresses,  Next: Host Address Data 
Type,  Up: Host Addresses
--
--Internet Host Addresses
--.......................
--
--   Each computer on the Internet has one or more Internet addresses,
--numbers which identify that computer among all those on the Internet.
--
--   An Internet host address is a number containing four bytes of data.
--These are divided into two parts, a "network number" and a "local
--network address number" within that network.  The network number
--consists of the first one, two or three bytes; the rest of the bytes
--are the local address.
--
--   Network numbers are registered with the Network Information Center
--(NIC), and are divided into three classes--A, B, and C.  The local
--network address numbers of individual machines are registered with the
--administrator of the particular network.
--
--   Class A networks have single-byte numbers in the range 0 to 127.
--There are only a small number of Class A networks, but they can each
--support a very large number of hosts.  Medium-sized Class B networks
--have two-byte network numbers, with the first byte in the range 128 to
--191.  Class C networks are the smallest; they have three-byte network
--numbers, with the first byte in the range 192-255.  Thus, the first 1,
--2, or 3 bytes of an Internet address specifies a network.  The
--remaining bytes of the Internet address specify the address within that
--network.
--
--   The Class A network 0 is reserved for broadcast to all networks.  In
--addition, the host number 0 within each network is reserved for
--broadcast to all hosts in that network.
--
--   The Class A network 127 is reserved for loopback; you can always use
--the Internet address `127.0.0.1' to refer to the host machine.
--
--   Since a single machine can be a member of multiple networks, it can
--have multiple Internet host addresses.  However, there is never
--supposed to be more than one machine with the same host address.
--
--   There are four forms of the "standard numbers-and-dots notation" for
--Internet addresses:
--
--`A.B.C.D'
--     This specifies all four bytes of the address individually.
--
--`A.B.C'
--     The last part of the address, C, is interpreted as a 2-byte
--     quantity.  This is useful for specifying host addresses in a Class
--     B network with network address number `A.B'.
--
--`A.B'
--     The last part of the address, C, is interpreted as a 3-byte
--     quantity.  This is useful for specifying host addresses in a Class
--     A network with network address number A.
--
--`A'
--     If only one part is given, this corresponds directly to the host
--     address number.
--
--   Within each part of the address, the usual C conventions for
--specifying the radix apply.  In other words, a leading `0x' or `0X'
--implies hexadecimal radix; a leading `0' implies octal; and otherwise
--decimal radix is assumed.
--
--
--File: libc.info,  Node: Host Address Data Type,  Next: Host Address 
Functions,  Prev: Abstract Host Addresses,  Up: Host Addresses
--
--Host Address Data Type
--......................
--
--   Internet host addresses are represented in some contexts as integers
--(type `unsigned long int').  In other contexts, the integer is packaged
--inside a structure of type `struct in_addr'.  It would be better if the
--usage were made consistent, but it is not hard to extract the integer
--from the structure or put the integer into a structure.
--
--   The following basic definitions for Internet addresses appear in the
--header file `netinet/in.h':
--
-- - Data Type: struct in_addr
--     This data type is used in certain contexts to contain an Internet
--     host address.  It has just one field, named `s_addr', which
--     records the host address number as an `unsigned long int'.
--
-- - Macro: unsigned long int INADDR_LOOPBACK
--     You can use this constant to stand for "the address of this
--     machine," instead of finding its actual address.  It is the
--     Internet address `127.0.0.1', which is usually called `localhost'.
--     This special constant saves you the trouble of looking up the
--     address of your own machine.  Also, the system usually implements
--     `INADDR_LOOPBACK' specially, avoiding any network traffic for the
--     case of one machine talking to itself.
--
-- - Macro: unsigned long int INADDR_ANY
--     You can use this constant to stand for "any incoming address," when
--     binding to an address.  *Note Setting Address::.  This is the usual
--     address to give in the `sin_addr' member of `struct sockaddr_in'
--     when you want to accept Internet connections.
--
-- - Macro: unsigned long int INADDR_BROADCAST
--     This constant is the address you use to send a broadcast message.
--
-- - Macro: unsigned long int INADDR_NONE
--     This constant is returned by some functions to indicate an error.
--
--
--File: libc.info,  Node: Host Address Functions,  Next: Host Names,  Prev: 
Host Address Data Type,  Up: Host Addresses
--
--Host Address Functions
--......................
--
--   These additional functions for manipulating Internet addresses are
--declared in `arpa/inet.h'.  They represent Internet addresses in
--network byte order; they represent network numbers and
--local-address-within-network numbers in host byte order.  *Note Byte
--Order::, for an explanation of network and host byte order.
--
-- - Function: int inet_aton (const char *NAME, struct in_addr *ADDR)
--     This function converts the Internet host address NAME from the
--     standard numbers-and-dots notation into binary data and stores it
--     in the `struct in_addr' that ADDR points to.  `inet_aton' returns
--     nonzero if the address is valid, zero if not.
--
-- - Function: unsigned long int inet_addr (const char *NAME)
--     This function converts the Internet host address NAME from the
--     standard numbers-and-dots notation into binary data.  If the input
--     is not valid, `inet_addr' returns `INADDR_NONE'.  This is an
--     obsolete interface to `inet_aton', described immediately above; it
--     is obsolete because `INADDR_NONE' is a valid address
--     (255.255.255.255), and `inet_aton' provides a cleaner way to
--     indicate error return.
--
-- - Function: unsigned long int inet_network (const char *NAME)
--     This function extracts the network number from the address NAME,
--     given in the standard numbers-and-dots notation.  If the input is
--     not valid, `inet_network' returns `-1'.
--
-- - Function: char * inet_ntoa (struct in_addr ADDR)
--     This function converts the Internet host address ADDR to a string
--     in the standard numbers-and-dots notation.  The return value is a
--     pointer into a statically-allocated buffer.  Subsequent calls will
--     overwrite the same buffer, so you should copy the string if you
--     need to save it.
--
-- - Function: struct in_addr inet_makeaddr (int NET, int LOCAL)
--     This function makes an Internet host address by combining the
--     network number NET with the local-address-within-network number
--     LOCAL.
--
-- - Function: int inet_lnaof (struct in_addr ADDR)
--     This function returns the local-address-within-network part of the
--     Internet host address ADDR.
--
-- - Function: int inet_netof (struct in_addr ADDR)
--     This function returns the network number part of the Internet host
--     address ADDR.
--
--
--File: libc.info,  Node: Host Names,  Prev: Host Address Functions,  Up: Host 
Addresses
--
--Host Names
--..........
--
--   Besides the standard numbers-and-dots notation for Internet
--addresses, you can also refer to a host by a symbolic name.  The
--advantage of a symbolic name is that it is usually easier to remember.
--For example, the machine with Internet address `128.52.46.32' is also
--known as `churchy.gnu.ai.mit.edu'; and other machines in the
--`gnu.ai.mit.edu' domain can refer to it simply as `churchy'.
--
--   Internally, the system uses a database to keep track of the mapping
--between host names and host numbers.  This database is usually either
--the file `/etc/hosts' or an equivalent provided by a name server.  The
--functions and other symbols for accessing this database are declared in
--`netdb.h'.  They are BSD features, defined unconditionally if you
--include `netdb.h'.
--
-- - Data Type: struct hostent
--     This data type is used to represent an entry in the hosts
--     database.  It has the following members:
--
--    `char *h_name'
--          This is the "official" name of the host.
--
--    `char **h_aliases'
--          These are alternative names for the host, represented as a
--          null-terminated vector of strings.
--
--    `int h_addrtype'
--          This is the host address type; in practice, its value is
--          always `AF_INET'.  In principle other kinds of addresses
--          could be represented in the data base as well as Internet
--          addresses; if this were done, you might find a value in this
--          field other than `AF_INET'.  *Note Socket Addresses::.
--
--    `int h_length'
--          This is the length, in bytes, of each address.
--
--    `char **h_addr_list'
--          This is the vector of addresses for the host.  (Recall that
--          the host might be connected to multiple networks and have
--          different addresses on each one.)  The vector is terminated
--          by a null pointer.
--
--    `char *h_addr'
--          This is a synonym for `h_addr_list[0]'; in other words, it is
--          the first host address.
--
--   As far as the host database is concerned, each address is just a
--block of memory `h_length' bytes long.  But in other contexts there is
--an implicit assumption that you can convert this to a `struct in_addr'
--or an `unsigned long int'.  Host addresses in a `struct hostent'
--structure are always given in network byte order; see *Note Byte
--Order::.
--
--   You can use `gethostbyname' or `gethostbyaddr' to search the hosts
--database for information about a particular host.  The information is
--returned in a statically-allocated structure; you must copy the
--information if you need to save it across calls.
--
-- - Function: struct hostent * gethostbyname (const char *NAME)
--     The `gethostbyname' function returns information about the host
--     named NAME.  If the lookup fails, it returns a null pointer.
--
-- - Function: struct hostent * gethostbyaddr (const char *ADDR, int
--          LENGTH, int FORMAT)
--     The `gethostbyaddr' function returns information about the host
--     with Internet address ADDR.  The LENGTH argument is the size (in
--     bytes) of the address at ADDR.  FORMAT specifies the address
--     format; for an Internet address, specify a value of `AF_INET'.
--
--     If the lookup fails, `gethostbyaddr' returns a null pointer.
--
--   If the name lookup by `gethostbyname' or `gethostbyaddr' fails, you
--can find out the reason by looking at the value of the variable
--`h_errno'.  (It would be cleaner design for these functions to set
--`errno', but use of `h_errno' is compatible with other systems.)
--Before using `h_errno', you must declare it like this:
--
--     extern int h_errno;
--
--   Here are the error codes that you may find in `h_errno':
--
--`HOST_NOT_FOUND'
--     No such host is known in the data base.
--
--`TRY_AGAIN'
--     This condition happens when the name server could not be
--     contacted.  If you try again later, you may succeed then.
--
--`NO_RECOVERY'
--     A non-recoverable error occurred.
--
--`NO_ADDRESS'
--     The host database contains an entry for the name, but it doesn't
--     have an associated Internet address.
--
--   You can also scan the entire hosts database one entry at a time using
--`sethostent', `gethostent', and `endhostent'.  Be careful in using
--these functions, because they are not reentrant.
--
-- - Function: void sethostent (int STAYOPEN)
--     This function opens the hosts database to begin scanning it.  You
--     can then call `gethostent' to read the entries.
--
--     If the STAYOPEN argument is nonzero, this sets a flag so that
--     subsequent calls to `gethostbyname' or `gethostbyaddr' will not
--     close the database (as they usually would).  This makes for more
--     efficiency if you call those functions several times, by avoiding
--     reopening the database for each call.
--
-- - Function: struct hostent * gethostent ()
--     This function returns the next entry in the hosts database.  It
--     returns a null pointer if there are no more entries.
--
-- - Function: void endhostent ()
--     This function closes the hosts database.
--
--
--File: libc.info,  Node: Ports,  Next: Services Database,  Prev: Protocols 
Database,  Up: Internet Namespace
--
--Internet Ports
----------------
--
--   A socket address in the Internet namespace consists of a machine's
--Internet address plus a "port number" which distinguishes the sockets
--on a given machine (for a given protocol).  Port numbers range from 0
--to 65,535.
--
--   Port numbers less than `IPPORT_RESERVED' are reserved for standard
--servers, such as `finger' and `telnet'.  There is a database that keeps
--track of these, and you can use the `getservbyname' function to map a
--service name onto a port number; see *Note Services Database::.
--
--   If you write a server that is not one of the standard ones defined in
--the database, you must choose a port number for it.  Use a number
--greater than `IPPORT_USERRESERVED'; such numbers are reserved for
--servers and won't ever be generated automatically by the system.
--Avoiding conflicts with servers being run by other users is up to you.
--
--   When you use a socket without specifying its address, the system
--generates a port number for it.  This number is between
--`IPPORT_RESERVED' and `IPPORT_USERRESERVED'.
--
--   On the Internet, it is actually legitimate to have two different
--sockets with the same port number, as long as they never both try to
--communicate with the same socket address (host address plus port
--number).  You shouldn't duplicate a port number except in special
--circumstances where a higher-level protocol requires it.  Normally, the
--system won't let you do it; `bind' normally insists on distinct port
--numbers.  To reuse a port number, you must set the socket option
--`SO_REUSEADDR'.  *Note Socket-Level Options::.
--
--   These macros are defined in the header file `netinet/in.h'.
--
-- - Macro: int IPPORT_RESERVED
--     Port numbers less than `IPPORT_RESERVED' are reserved for
--     superuser use.
--
-- - Macro: int IPPORT_USERRESERVED
--     Port numbers greater than or equal to `IPPORT_USERRESERVED' are
--     reserved for explicit use; they will never be allocated
--     automatically.
--
--
--File: libc.info,  Node: Services Database,  Next: Byte Order,  Prev: Ports,  
Up: Internet Namespace
--
--The Services Database
-----------------------
--
--   The database that keeps track of "well-known" services is usually
--either the file `/etc/services' or an equivalent from a name server.
--You can use these utilities, declared in `netdb.h', to access the
--services database.
--
-- - Data Type: struct servent
--     This data type holds information about entries from the services
--     database.  It has the following members:
--
--    `char *s_name'
--          This is the "official" name of the service.
--
--    `char **s_aliases'
--          These are alternate names for the service, represented as an
--          array of strings.  A null pointer terminates the array.
--
--    `int s_port'
--          This is the port number for the service.  Port numbers are
--          given in network byte order; see *Note Byte Order::.
--
--    `char *s_proto'
--          This is the name of the protocol to use with this service.
--          *Note Protocols Database::.
--
--   To get information about a particular service, use the
--`getservbyname' or `getservbyport' functions.  The information is
--returned in a statically-allocated structure; you must copy the
--information if you need to save it across calls.
--
-- - Function: struct servent * getservbyname (const char *NAME, const
--          char *PROTO)
--     The `getservbyname' function returns information about the service
--     named NAME using protocol PROTO.  If it can't find such a service,
--     it returns a null pointer.
--
--     This function is useful for servers as well as for clients; servers
--     use it to determine which port they should listen on (*note
--     Listening::.).
--
-- - Function: struct servent * getservbyport (int PORT, const char
--          *PROTO)
--     The `getservbyport' function returns information about the service
--     at port PORT using protocol PROTO.  If it can't find such a
--     service, it returns a null pointer.
--
--   You can also scan the services database using `setservent',
--`getservent', and `endservent'.  Be careful in using these functions,
--because they are not reentrant.
--
-- - Function: void setservent (int STAYOPEN)
--     This function opens the services database to begin scanning it.
--
--     If the STAYOPEN argument is nonzero, this sets a flag so that
--     subsequent calls to `getservbyname' or `getservbyport' will not
--     close the database (as they usually would).  This makes for more
--     efficiency if you call those functions several times, by avoiding
--     reopening the database for each call.
--
-- - Function: struct servent * getservent (void)
--     This function returns the next entry in the services database.  If
--     there are no more entries, it returns a null pointer.
--
-- - Function: void endservent (void)
--     This function closes the services database.
--
--
--File: libc.info,  Node: Byte Order,  Next: Inet Example,  Prev: Services 
Database,  Up: Internet Namespace
--
--Byte Order Conversion
-----------------------
--
--   Different kinds of computers use different conventions for the
--ordering of bytes within a word.  Some computers put the most
--significant byte within a word first (this is called "big-endian"
--order), and others put it last ("little-endian" order).
--
--   So that machines with different byte order conventions can
--communicate, the Internet protocols specify a canonical byte order
--convention for data transmitted over the network.  This is known as the
--"network byte order".
--
--   When establishing an Internet socket connection, you must make sure
--that the data in the `sin_port' and `sin_addr' members of the
--`sockaddr_in' structure are represented in the network byte order.  If
--you are encoding integer data in the messages sent through the socket,
--you should convert this to network byte order too.  If you don't do
--this, your program may fail when running on or talking to other kinds
--of machines.
--
--   If you use `getservbyname' and `gethostbyname' or `inet_addr' to get
--the port number and host address, the values are already in the network
--byte order, and you can copy them directly into the `sockaddr_in'
--structure.
--
--   Otherwise, you have to convert the values explicitly.  Use `htons'
--and `ntohs' to convert values for the `sin_port' member.  Use `htonl'
--and `ntohl' to convert values for the `sin_addr' member.  (Remember,
--`struct in_addr' is equivalent to `unsigned long int'.)  These
--functions are declared in `netinet/in.h'.
--
-- - Function: unsigned short int htons (unsigned short int HOSTSHORT)
--     This function converts the `short' integer HOSTSHORT from host
--     byte order to network byte order.
--
-- - Function: unsigned short int ntohs (unsigned short int NETSHORT)
--     This function converts the `short' integer NETSHORT from network
--     byte order to host byte order.
--
-- - Function: unsigned long int htonl (unsigned long int HOSTLONG)
--     This function converts the `long' integer HOSTLONG from host byte
--     order to network byte order.
--
-- - Function: unsigned long int ntohl (unsigned long int NETLONG)
--     This function converts the `long' integer NETLONG from network
--     byte order to host byte order.
--
--
--File: libc.info,  Node: Protocols Database,  Next: Ports,  Prev: Host 
Addresses,  Up: Internet Namespace
--
--Protocols Database
--------------------
--
--   The communications protocol used with a socket controls low-level
--details of how data is exchanged.  For example, the protocol implements
--things like checksums to detect errors in transmissions, and routing
--instructions for messages.  Normal user programs have little reason to
--mess with these details directly.
--
--   The default communications protocol for the Internet namespace
--depends on the communication style.  For stream communication, the
--default is TCP ("transmission control protocol").  For datagram
--communication, the default is UDP ("user datagram protocol").  For
--reliable datagram communication, the default is RDP ("reliable datagram
--protocol").  You should nearly always use the default.
--
--   Internet protocols are generally specified by a name instead of a
--number.  The network protocols that a host knows about are stored in a
--database.  This is usually either derived from the file
--`/etc/protocols', or it may be an equivalent provided by a name server.
--You look up the protocol number associated with a named protocol in
--the database using the `getprotobyname' function.
--
--   Here are detailed descriptions of the utilities for accessing the
--protocols database.  These are declared in `netdb.h'.
--
-- - Data Type: struct protoent
--     This data type is used to represent entries in the network
--     protocols database.  It has the following members:
--
--    `char *p_name'
--          This is the official name of the protocol.
--
--    `char **p_aliases'
--          These are alternate names for the protocol, specified as an
--          array of strings.  The last element of the array is a null
--          pointer.
--
--    `int p_proto'
--          This is the protocol number (in host byte order); use this
--          member as the PROTOCOL argument to `socket'.
--
--   You can use `getprotobyname' and `getprotobynumber' to search the
--protocols database for a specific protocol.  The information is
--returned in a statically-allocated structure; you must copy the
--information if you need to save it across calls.
--
-- - Function: struct protoent * getprotobyname (const char *NAME)
--     The `getprotobyname' function returns information about the
--     network protocol named NAME.  If there is no such protocol, it
--     returns a null pointer.
--
-- - Function: struct protoent * getprotobynumber (int PROTOCOL)
--     The `getprotobynumber' function returns information about the
--     network protocol with number PROTOCOL.  If there is no such
--     protocol, it returns a null pointer.
--
--   You can also scan the whole protocols database one protocol at a
--time by using `setprotoent', `getprotoent', and `endprotoent'.  Be
--careful in using these functions, because they are not reentrant.
--
-- - Function: void setprotoent (int STAYOPEN)
--     This function opens the protocols database to begin scanning it.
--
--     If the STAYOPEN argument is nonzero, this sets a flag so that
--     subsequent calls to `getprotobyname' or `getprotobynumber' will
--     not close the database (as they usually would).  This makes for
--     more efficiency if you call those functions several times, by
--     avoiding reopening the database for each call.
--
-- - Function: struct protoent * getprotoent (void)
--     This function returns the next entry in the protocols database.  It
--     returns a null pointer if there are no more entries.
--
-- - Function: void endprotoent (void)
--     This function closes the protocols database.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-13 
glibc-2.0.1/manual/libc.info-13
---- ../glibc-2.0.1/manual/libc.info-13 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-13    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1376 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Inet Example,  Prev: Byte Order,  Up: Internet 
Namespace
--
--Internet Socket Example
-------------------------
--
--   Here is an example showing how to create and name a socket in the
--Internet namespace.  The newly created socket exists on the machine that
--the program is running on.  Rather than finding and using the machine's
--Internet address, this example specifies `INADDR_ANY' as the host
--address; the system replaces that with the machine's actual address.
--
--     #include <stdio.h>
--     #include <stdlib.h>
--     #include <sys/socket.h>
--     #include <netinet/in.h>
--     
--     int
--     make_socket (unsigned short int port)
--     {
--       int sock;
--       struct sockaddr_in name;
--     
--       /* Create the socket. */
--       sock = socket (PF_INET, SOCK_STREAM, 0);
--       if (sock < 0)
--         {
--           perror ("socket");
--           exit (EXIT_FAILURE);
--         }
--     
--       /* Give the socket a name. */
--       name.sin_family = AF_INET;
--       name.sin_port = htons (port);
--       name.sin_addr.s_addr = htonl (INADDR_ANY);
--       if (bind (sock, (struct sockaddr *) &name, sizeof (name)) < 0)
--         {
--           perror ("bind");
--           exit (EXIT_FAILURE);
--         }
--     
--       return sock;
--     }
--
--   Here is another example, showing how you can fill in a `sockaddr_in'
--structure, given a host name string and a port number:
--
--     #include <stdio.h>
--     #include <stdlib.h>
--     #include <sys/socket.h>
--     #include <netinet/in.h>
--     #include <netdb.h>
--     
--     void
--     init_sockaddr (struct sockaddr_in *name,
--                    const char *hostname,
--                    unsigned short int port)
--     {
--       struct hostent *hostinfo;
--     
--       name->sin_family = AF_INET;
--       name->sin_port = htons (port);
--       hostinfo = gethostbyname (hostname);
--       if (hostinfo == NULL)
--         {
--           fprintf (stderr, "Unknown host %s.\n", hostname);
--           exit (EXIT_FAILURE);
--         }
--       name->sin_addr = *(struct in_addr *) hostinfo->h_addr;
--     }
--
--
--File: libc.info,  Node: Misc Namespaces,  Next: Open/Close Sockets,  Prev: 
Internet Namespace,  Up: Sockets
--
--Other Namespaces
--================
--
--   Certain other namespaces and associated protocol families are
--supported but not documented yet because they are not often used.
--`PF_NS' refers to the Xerox Network Software protocols.  `PF_ISO' stands
--for Open Systems Interconnect.  `PF_CCITT' refers to protocols from
--CCITT.  `socket.h' defines these symbols and others naming protocols
--not actually implemented.
--
--   `PF_IMPLINK' is used for communicating between hosts and Internet
--Message Processors.  For information on this, and on `PF_ROUTE', an
--occasionally-used local area routing protocol, see the GNU Hurd Manual
--(to appear in the future).
--
--
--File: libc.info,  Node: Open/Close Sockets,  Next: Connections,  Prev: Misc 
Namespaces,  Up: Sockets
--
--Opening and Closing Sockets
--===========================
--
--   This section describes the actual library functions for opening and
--closing sockets.  The same functions work for all namespaces and
--connection styles.
--
--* Menu:
--
--* Creating a Socket::           How to open a socket.
--* Closing a Socket::            How to close a socket.
--* Socket Pairs::                These are created like pipes.
--
--
--File: libc.info,  Node: Creating a Socket,  Next: Closing a Socket,  Up: 
Open/Close Sockets
--
--Creating a Socket
-------------------
--
--   The primitive for creating a socket is the `socket' function,
--declared in `sys/socket.h'.
--
-- - Function: int socket (int NAMESPACE, int STYLE, int PROTOCOL)
--     This function creates a socket and specifies communication style
--     STYLE, which should be one of the socket styles listed in *Note
--     Communication Styles::.  The NAMESPACE argument specifies the
--     namespace; it must be `PF_FILE' (*note File Namespace::.) or
--     `PF_INET' (*note Internet Namespace::.).  PROTOCOL designates the
--     specific protocol (*note Socket Concepts::.); zero is usually
--     right for PROTOCOL.
--
--     The return value from `socket' is the file descriptor for the new
--     socket, or `-1' in case of error.  The following `errno' error
--     conditions are defined for this function:
--
--    `EPROTONOSUPPORT'
--          The PROTOCOL or STYLE is not supported by the NAMESPACE
--          specified.
--
--    `EMFILE'
--          The process already has too many file descriptors open.
--
--    `ENFILE'
--          The system already has too many file descriptors open.
--
--    `EACCESS'
--          The process does not have privilege to create a socket of the
--          specified STYLE or PROTOCOL.
--
--    `ENOBUFS'
--          The system ran out of internal buffer space.
--
--     The file descriptor returned by the `socket' function supports both
--     read and write operations.  But, like pipes, sockets do not
--     support file positioning operations.
--
--   For examples of how to call the `socket' function, see *Note File
--Namespace::, or *Note Inet Example::.
--
--
--File: libc.info,  Node: Closing a Socket,  Next: Socket Pairs,  Prev: 
Creating a Socket,  Up: Open/Close Sockets
--
--Closing a Socket
------------------
--
--   When you are finished using a socket, you can simply close its file
--descriptor with `close'; see *Note Opening and Closing Files::.  If
--there is still data waiting to be transmitted over the connection,
--normally `close' tries to complete this transmission.  You can control
--this behavior using the `SO_LINGER' socket option to specify a timeout
--period; see *Note Socket Options::.
--
--   You can also shut down only reception or only transmission on a
--connection by calling `shutdown', which is declared in `sys/socket.h'.
--
-- - Function: int shutdown (int SOCKET, int HOW)
--     The `shutdown' function shuts down the connection of socket
--     SOCKET.  The argument HOW specifies what action to perform:
--
--    `0'
--          Stop receiving data for this socket.  If further data arrives,
--          reject it.
--
--    `1'
--          Stop trying to transmit data from this socket.  Discard any
--          data waiting to be sent.  Stop looking for acknowledgement of
--          data already sent; don't retransmit it if it is lost.
--
--    `2'
--          Stop both reception and transmission.
--
--     The return value is `0' on success and `-1' on failure.  The
--     following `errno' error conditions are defined for this function:
--
--    `EBADF'
--          SOCKET is not a valid file descriptor.
--
--    `ENOTSOCK'
--          SOCKET is not a socket.
--
--    `ENOTCONN'
--          SOCKET is not connected.
--
--
--File: libc.info,  Node: Socket Pairs,  Prev: Closing a Socket,  Up: 
Open/Close Sockets
--
--Socket Pairs
--------------
--
--   A "socket pair" consists of a pair of connected (but unnamed)
--sockets.  It is very similar to a pipe and is used in much the same
--way.  Socket pairs are created with the `socketpair' function, declared
--in `sys/socket.h'.  A socket pair is much like a pipe; the main
--difference is that the socket pair is bidirectional, whereas the pipe
--has one input-only end and one output-only end (*note Pipes and
--FIFOs::.).
--
-- - Function: int socketpair (int NAMESPACE, int STYLE, int PROTOCOL,
--          int FILEDES[2])
--     This function creates a socket pair, returning the file
--     descriptors in `FILEDES[0]' and `FILEDES[1]'.  The socket pair is
--     a full-duplex communications channel, so that both reading and
--     writing may be performed at either end.
--
--     The NAMESPACE, STYLE, and PROTOCOL arguments are interpreted as
--     for the `socket' function.  STYLE should be one of the
--     communication styles listed in *Note Communication Styles::.  The
--     NAMESPACE argument specifies the namespace, which must be
--     `AF_FILE' (*note File Namespace::.); PROTOCOL specifies the
--     communications protocol, but zero is the only meaningful value.
--
--     If STYLE specifies a connectionless communication style, then the
--     two sockets you get are not *connected*, strictly speaking, but
--     each of them knows the other as the default destination address,
--     so they can send packets to each other.
--
--     The `socketpair' function returns `0' on success and `-1' on
--     failure.  The following `errno' error conditions are defined for
--     this function:
--
--    `EMFILE'
--          The process has too many file descriptors open.
--
--    `EAFNOSUPPORT'
--          The specified namespace is not supported.
--
--    `EPROTONOSUPPORT'
--          The specified protocol is not supported.
--
--    `EOPNOTSUPP'
--          The specified protocol does not support the creation of
--          socket pairs.
--
--
--File: libc.info,  Node: Connections,  Next: Datagrams,  Prev: Open/Close 
Sockets,  Up: Sockets
--
--Using Sockets with Connections
--==============================
--
--   The most common communication styles involve making a connection to a
--particular other socket, and then exchanging data with that socket over
--and over.  Making a connection is asymmetric; one side (the "client")
--acts to request a connection, while the other side (the "server") makes
--a socket and waits for the connection request.
--
--* Menu:
--
--* Connecting::             What the client program must do.
--* Listening::              How a server program waits for requests.
--* Accepting Connections::    What the server does when it gets a request.
--* Who is Connected::       Getting the address of the
--                              other side of a connection.
--* Transferring Data::        How to send and receive data.
--* Byte Stream Example::            An example program: a client for 
communicating
--                            over a byte stream socket in the Internet 
namespace.
--* Server Example::         A corresponding server program.
--* Out-of-Band Data::         This is an advanced feature.
--
--
--File: libc.info,  Node: Connecting,  Next: Listening,  Up: Connections
--
--Making a Connection
---------------------
--
--   In making a connection, the client makes a connection while the
--server waits for and accepts the connection.  Here we discuss what the
--client program must do, using the `connect' function, which is declared
--in `sys/socket.h'.
--
-- - Function: int connect (int SOCKET, struct sockaddr *ADDR, size_t
--          LENGTH)
--     The `connect' function initiates a connection from the socket with
--     file descriptor SOCKET to the socket whose address is specified by
--     the ADDR and LENGTH arguments.  (This socket is typically on
--     another machine, and it must be already set up as a server.)
--     *Note Socket Addresses::, for information about how these
--     arguments are interpreted.
--
--     Normally, `connect' waits until the server responds to the request
--     before it returns.  You can set nonblocking mode on the socket
--     SOCKET to make `connect' return immediately without waiting for
--     the response.  *Note File Status Flags::, for information about
--     nonblocking mode.
--
--     The normal return value from `connect' is `0'.  If an error
--     occurs, `connect' returns `-1'.  The following `errno' error
--     conditions are defined for this function:
--
--    `EBADF'
--          The socket SOCKET is not a valid file descriptor.
--
--    `ENOTSOCK'
--          File descriptor SOCKET is not a socket.
--
--    `EADDRNOTAVAIL'
--          The specified address is not available on the remote machine.
--
--    `EAFNOSUPPORT'
--          The namespace of the ADDR is not supported by this socket.
--
--    `EISCONN'
--          The socket SOCKET is already connected.
--
--    `ETIMEDOUT'
--          The attempt to establish the connection timed out.
--
--    `ECONNREFUSED'
--          The server has actively refused to establish the connection.
--
--    `ENETUNREACH'
--          The network of the given ADDR isn't reachable from this host.
--
--    `EADDRINUSE'
--          The socket address of the given ADDR is already in use.
--
--    `EINPROGRESS'
--          The socket SOCKET is non-blocking and the connection could
--          not be established immediately.  You can determine when the
--          connection is completely established with `select'; *note
--          Waiting for I/O::..  Another `connect' call on the same
--          socket, before the connection is completely established, will
--          fail with `EALREADY'.
--
--    `EALREADY'
--          The socket SOCKET is non-blocking and already has a pending
--          connection in progress (see `EINPROGRESS' above).
--
--
--File: libc.info,  Node: Listening,  Next: Accepting Connections,  Prev: 
Connecting,  Up: Connections
--
--Listening for Connections
---------------------------
--
--   Now let us consider what the server process must do to accept
--connections on a socket.  First it must use the `listen' function to
--enable connection requests on the socket, and then accept each incoming
--connection with a call to `accept' (*note Accepting Connections::.).
--Once connection requests are enabled on a server socket, the `select'
--function reports when the socket has a connection ready to be accepted
--(*note Waiting for I/O::.).
--
--   The `listen' function is not allowed for sockets using
--connectionless communication styles.
--
--   You can write a network server that does not even start running
--until a connection to it is requested.  *Note Inetd Servers::.
--
--   In the Internet namespace, there are no special protection mechanisms
--for controlling access to connect to a port; any process on any machine
--can make a connection to your server.  If you want to restrict access to
--your server, make it examine the addresses associated with connection
--requests or implement some other handshaking or identification protocol.
--
--   In the File namespace, the ordinary file protection bits control who
--has access to connect to the socket.
--
-- - Function: int listen (int SOCKET, unsigned int N)
--     The `listen' function enables the socket SOCKET to accept
--     connections, thus making it a server socket.
--
--     The argument N specifies the length of the queue for pending
--     connections.  When the queue fills, new clients attempting to
--     connect fail with `ECONNREFUSED' until the server calls `accept' to
--     accept a connection from the queue.
--
--     The `listen' function returns `0' on success and `-1' on failure.
--     The following `errno' error conditions are defined for this
--     function:
--
--    `EBADF'
--          The argument SOCKET is not a valid file descriptor.
--
--    `ENOTSOCK'
--          The argument SOCKET is not a socket.
--
--    `EOPNOTSUPP'
--          The socket SOCKET does not support this operation.
--
--
--File: libc.info,  Node: Accepting Connections,  Next: Who is Connected,  
Prev: Listening,  Up: Connections
--
--Accepting Connections
-----------------------
--
--   When a server receives a connection request, it can complete the
--connection by accepting the request.  Use the function `accept' to do
--this.
--
--   A socket that has been established as a server can accept connection
--requests from multiple clients.  The server's original socket *does not
--become part* of the connection; instead, `accept' makes a new socket
--which participates in the connection.  `accept' returns the descriptor
--for this socket.  The server's original socket remains available for
--listening for further connection requests.
--
--   The number of pending connection requests on a server socket is
--finite.  If connection requests arrive from clients faster than the
--server can act upon them, the queue can fill up and additional requests
--are refused with a `ECONNREFUSED' error.  You can specify the maximum
--length of this queue as an argument to the `listen' function, although
--the system may also impose its own internal limit on the length of this
--queue.
--
-- - Function: int accept (int SOCKET, struct sockaddr *ADDR, size_t
--          *LENGTH-PTR)
--     This function is used to accept a connection request on the server
--     socket SOCKET.
--
--     The `accept' function waits if there are no connections pending,
--     unless the socket SOCKET has nonblocking mode set.  (You can use
--     `select' to wait for a pending connection, with a nonblocking
--     socket.)  *Note File Status Flags::, for information about
--     nonblocking mode.
--
--     The ADDR and LENGTH-PTR arguments are used to return information
--     about the name of the client socket that initiated the connection.
--     *Note Socket Addresses::, for information about the format of the
--     information.
--
--     Accepting a connection does not make SOCKET part of the
--     connection.  Instead, it creates a new socket which becomes
--     connected.  The normal return value of `accept' is the file
--     descriptor for the new socket.
--
--     After `accept', the original socket SOCKET remains open and
--     unconnected, and continues listening until you close it.  You can
--     accept further connections with SOCKET by calling `accept' again.
--
--     If an error occurs, `accept' returns `-1'.  The following `errno'
--     error conditions are defined for this function:
--
--    `EBADF'
--          The SOCKET argument is not a valid file descriptor.
--
--    `ENOTSOCK'
--          The descriptor SOCKET argument is not a socket.
--
--    `EOPNOTSUPP'
--          The descriptor SOCKET does not support this operation.
--
--    `EWOULDBLOCK'
--          SOCKET has nonblocking mode set, and there are no pending
--          connections immediately available.
--
--   The `accept' function is not allowed for sockets using
--connectionless communication styles.
--
--
--File: libc.info,  Node: Who is Connected,  Next: Transferring Data,  Prev: 
Accepting Connections,  Up: Connections
--
--Who is Connected to Me?
-------------------------
--
-- - Function: int getpeername (int SOCKET, struct sockaddr *ADDR, size_t
--          *LENGTH-PTR)
--     The `getpeername' function returns the address of the socket that
--     SOCKET is connected to; it stores the address in the memory space
--     specified by ADDR and LENGTH-PTR.  It stores the length of the
--     address in `*LENGTH-PTR'.
--
--     *Note Socket Addresses::, for information about the format of the
--     address.  In some operating systems, `getpeername' works only for
--     sockets in the Internet domain.
--
--     The return value is `0' on success and `-1' on error.  The
--     following `errno' error conditions are defined for this function:
--
--    `EBADF'
--          The argument SOCKET is not a valid file descriptor.
--
--    `ENOTSOCK'
--          The descriptor SOCKET is not a socket.
--
--    `ENOTCONN'
--          The socket SOCKET is not connected.
--
--    `ENOBUFS'
--          There are not enough internal buffers available.
--
--
--File: libc.info,  Node: Transferring Data,  Next: Byte Stream Example,  Prev: 
Who is Connected,  Up: Connections
--
--Transferring Data
-------------------
--
--   Once a socket has been connected to a peer, you can use the ordinary
--`read' and `write' operations (*note I/O Primitives::.) to transfer
--data.  A socket is a two-way communications channel, so read and write
--operations can be performed at either end.
--
--   There are also some I/O modes that are specific to socket operations.
--In order to specify these modes, you must use the `recv' and `send'
--functions instead of the more generic `read' and `write' functions.
--The `recv' and `send' functions take an additional argument which you
--can use to specify various flags to control the special I/O modes.  For
--example, you can specify the `MSG_OOB' flag to read or write
--out-of-band data, the `MSG_PEEK' flag to peek at input, or the
--`MSG_DONTROUTE' flag to control inclusion of routing information on
--output.
--
--* Menu:
--
--* Sending Data::              Sending data with `send'.
--* Receiving Data::            Reading data with `recv'.
--* Socket Data Options::               Using `send' and `recv'.
--
--
--File: libc.info,  Node: Sending Data,  Next: Receiving Data,  Up: 
Transferring Data
--
--Sending Data
--............
--
--   The `send' function is declared in the header file `sys/socket.h'.
--If your FLAGS argument is zero, you can just as well use `write'
--instead of `send'; see *Note I/O Primitives::.  If the socket was
--connected but the connection has broken, you get a `SIGPIPE' signal for
--any use of `send' or `write' (*note Miscellaneous Signals::.).
--
-- - Function: int send (int SOCKET, void *BUFFER, size_t SIZE, int FLAGS)
--     The `send' function is like `write', but with the additional flags
--     FLAGS.  The possible values of FLAGS are described in *Note Socket
--     Data Options::.
--
--     This function returns the number of bytes transmitted, or `-1' on
--     failure.  If the socket is nonblocking, then `send' (like `write')
--     can return after sending just part of the data.  *Note File Status
--     Flags::, for information about nonblocking mode.
--
--     Note, however, that a successful return value merely indicates that
--     the message has been sent without error, not necessarily that it
--     has been received without error.
--
--     The following `errno' error conditions are defined for this
--     function:
--
--    `EBADF'
--          The SOCKET argument is not a valid file descriptor.
--
--    `EINTR'
--          The operation was interrupted by a signal before any data was
--          sent.  *Note Interrupted Primitives::.
--
--    `ENOTSOCK'
--          The descriptor SOCKET is not a socket.
--
--    `EMSGSIZE'
--          The socket type requires that the message be sent atomically,
--          but the message is too large for this to be possible.
--
--    `EWOULDBLOCK'
--          Nonblocking mode has been set on the socket, and the write
--          operation would block.  (Normally `send' blocks until the
--          operation can be completed.)
--
--    `ENOBUFS'
--          There is not enough internal buffer space available.
--
--    `ENOTCONN'
--          You never connected this socket.
--
--    `EPIPE'
--          This socket was connected but the connection is now broken.
--          In this case, `send' generates a `SIGPIPE' signal first; if
--          that signal is ignored or blocked, or if its handler returns,
--          then `send' fails with `EPIPE'.
--
--
--File: libc.info,  Node: Receiving Data,  Next: Socket Data Options,  Prev: 
Sending Data,  Up: Transferring Data
--
--Receiving Data
--..............
--
--   The `recv' function is declared in the header file `sys/socket.h'.
--If your FLAGS argument is zero, you can just as well use `read' instead
--of `recv'; see *Note I/O Primitives::.
--
-- - Function: int recv (int SOCKET, void *BUFFER, size_t SIZE, int FLAGS)
--     The `recv' function is like `read', but with the additional flags
--     FLAGS.  The possible values of FLAGS are described In *Note Socket
--     Data Options::.
--
--     If nonblocking mode is set for SOCKET, and no data is available to
--     be read, `recv' fails immediately rather than waiting.  *Note File
--     Status Flags::, for information about nonblocking mode.
--
--     This function returns the number of bytes received, or `-1' on
--     failure.  The following `errno' error conditions are defined for
--     this function:
--
--    `EBADF'
--          The SOCKET argument is not a valid file descriptor.
--
--    `ENOTSOCK'
--          The descriptor SOCKET is not a socket.
--
--    `EWOULDBLOCK'
--          Nonblocking mode has been set on the socket, and the read
--          operation would block.  (Normally, `recv' blocks until there
--          is input available to be read.)
--
--    `EINTR'
--          The operation was interrupted by a signal before any data was
--          read.  *Note Interrupted Primitives::.
--
--    `ENOTCONN'
--          You never connected this socket.
--
--
--File: libc.info,  Node: Socket Data Options,  Prev: Receiving Data,  Up: 
Transferring Data
--
--Socket Data Options
--...................
--
--   The FLAGS argument to `send' and `recv' is a bit mask.  You can
--bitwise-OR the values of the following macros together to obtain a
--value for this argument.  All are defined in the header file
--`sys/socket.h'.
--
-- - Macro: int MSG_OOB
--     Send or receive out-of-band data.  *Note Out-of-Band Data::.
--
-- - Macro: int MSG_PEEK
--     Look at the data but don't remove it from the input queue.  This is
--     only meaningful with input functions such as `recv', not with
--     `send'.
--
-- - Macro: int MSG_DONTROUTE
--     Don't include routing information in the message.  This is only
--     meaningful with output operations, and is usually only of interest
--     for diagnostic or routing programs.  We don't try to explain it
--     here.
--
--
--File: libc.info,  Node: Byte Stream Example,  Next: Server Example,  Prev: 
Transferring Data,  Up: Connections
--
--Byte Stream Socket Example
----------------------------
--
--   Here is an example client program that makes a connection for a byte
--stream socket in the Internet namespace.  It doesn't do anything
--particularly interesting once it has connected to the server; it just
--sends a text string to the server and exits.
--
--     #include <stdio.h>
--     #include <errno.h>
--     #include <stdlib.h>
--     #include <unistd.h>
--     #include <sys/types.h>
--     #include <sys/socket.h>
--     #include <netinet/in.h>
--     #include <netdb.h>
--     
--     #define PORT            5555
--     #define MESSAGE         "Yow!!! Are we having fun yet?!?"
--     #define SERVERHOST      "churchy.gnu.ai.mit.edu"
--     
--     void
--     write_to_server (int filedes)
--     {
--       int nbytes;
--     
--       nbytes = write (filedes, MESSAGE, strlen (MESSAGE) + 1);
--       if (nbytes < 0)
--         {
--           perror ("write");
--           exit (EXIT_FAILURE);
--         }
--     }
--     
--     
--     int
--     main (void)
--     {
--       extern void init_sockaddr (struct sockaddr_in *name,
--                                  const char *hostname,
--                                  unsigned short int port);
--       int sock;
--       struct sockaddr_in servername;
--     
--       /* Create the socket. */
--       sock = socket (PF_INET, SOCK_STREAM, 0);
--       if (sock < 0)
--         {
--           perror ("socket (client)");
--           exit (EXIT_FAILURE);
--         }
--     
--       /* Connect to the server. */
--       init_sockaddr (&servername, SERVERHOST, PORT);
--       if (0 > connect (sock,
--                        (struct sockaddr *) &servername,
--                        sizeof (servername)))
--         {
--           perror ("connect (client)");
--           exit (EXIT_FAILURE);
--         }
--     
--       /* Send data to the server. */
--       write_to_server (sock);
--       close (sock);
--       exit (EXIT_SUCCESS);
--     }
--
--
--File: libc.info,  Node: Server Example,  Next: Out-of-Band Data,  Prev: Byte 
Stream Example,  Up: Connections
--
--Byte Stream Connection Server Example
---------------------------------------
--
--   The server end is much more complicated.  Since we want to allow
--multiple clients to be connected to the server at the same time, it
--would be incorrect to wait for input from a single client by simply
--calling `read' or `recv'.  Instead, the right thing to do is to use
--`select' (*note Waiting for I/O::.) to wait for input on all of the
--open sockets.  This also allows the server to deal with additional
--connection requests.
--
--   This particular server doesn't do anything interesting once it has
--gotten a message from a client.  It does close the socket for that
--client when it detects an end-of-file condition (resulting from the
--client shutting down its end of the connection).
--
--   This program uses `make_socket' and `init_sockaddr' to set up the
--socket address; see *Note Inet Example::.
--
--     #include <stdio.h>
--     #include <errno.h>
--     #include <stdlib.h>
--     #include <unistd.h>
--     #include <sys/types.h>
--     #include <sys/socket.h>
--     #include <netinet/in.h>
--     #include <netdb.h>
--     
--     #define PORT    5555
--     #define MAXMSG  512
--     
--     int
--     read_from_client (int filedes)
--     {
--       char buffer[MAXMSG];
--       int nbytes;
--     
--       nbytes = read (filedes, buffer, MAXMSG);
--       if (nbytes < 0)
--         {
--           /* Read error. */
--           perror ("read");
--           exit (EXIT_FAILURE);
--         }
--       else if (nbytes == 0)
--         /* End-of-file. */
--         return -1;
--       else
--         {
--           /* Data read. */
--           fprintf (stderr, "Server: got message: `%s'\n", buffer);
--           return 0;
--         }
--     }
--     
--     int
--     main (void)
--     {
--       extern int make_socket (unsigned short int port);
--       int sock;
--       fd_set active_fd_set, read_fd_set;
--       int i;
--       struct sockaddr_in clientname;
--       size_t size;
--     
--       /* Create the socket and set it up to accept connections. */
--       sock = make_socket (PORT);
--       if (listen (sock, 1) < 0)
--         {
--           perror ("listen");
--           exit (EXIT_FAILURE);
--         }
--     
--       /* Initialize the set of active sockets. */
--       FD_ZERO (&active_fd_set);
--       FD_SET (sock, &active_fd_set);
--     
--       while (1)
--         {
--           /* Block until input arrives on one or more active sockets. */
--           read_fd_set = active_fd_set;
--           if (select (FD_SETSIZE, &read_fd_set, NULL, NULL, NULL) < 0)
--             {
--               perror ("select");
--               exit (EXIT_FAILURE);
--             }
--     
--           /* Service all the sockets with input pending. */
--           for (i = 0; i < FD_SETSIZE; ++i)
--             if (FD_ISSET (i, &read_fd_set))
--               {
--                 if (i == sock)
--                   {
--                     /* Connection request on original socket. */
--                     int new;
--                     size = sizeof (clientname);
--                     new = accept (sock,
--                                   (struct sockaddr *) &clientname,
--                                   &size);
--                     if (new < 0)
--                       {
--                         perror ("accept");
--                         exit (EXIT_FAILURE);
--                       }
--                     fprintf (stderr,
--                              "Server: connect from host %s, port %hd.\n",
--                              inet_ntoa (clientname.sin_addr),
--                              ntohs (clientname.sin_port));
--                     FD_SET (new, &active_fd_set);
--                   }
--                 else
--                   {
--                     /* Data arriving on an already-connected socket. */
--                     if (read_from_client (i) < 0)
--                       {
--                         close (i);
--                         FD_CLR (i, &active_fd_set);
--                       }
--                   }
--               }
--         }
--     }
--
--
--File: libc.info,  Node: Out-of-Band Data,  Prev: Server Example,  Up: 
Connections
--
--Out-of-Band Data
------------------
--
--   Streams with connections permit "out-of-band" data that is delivered
--with higher priority than ordinary data.  Typically the reason for
--sending out-of-band data is to send notice of an exceptional condition.
--The way to send out-of-band data is using `send', specifying the flag
--`MSG_OOB' (*note Sending Data::.).
--
--   Out-of-band data is received with higher priority because the
--receiving process need not read it in sequence; to read the next
--available out-of-band data, use `recv' with the `MSG_OOB' flag (*note
--Receiving Data::.).  Ordinary read operations do not read out-of-band
--data; they read only the ordinary data.
--
--   When a socket finds that out-of-band data is on its way, it sends a
--`SIGURG' signal to the owner process or process group of the socket.
--You can specify the owner using the `F_SETOWN' command to the `fcntl'
--function; see *Note Interrupt Input::.  You must also establish a
--handler for this signal, as described in *Note Signal Handling::, in
--order to take appropriate action such as reading the out-of-band data.
--
--   Alternatively, you can test for pending out-of-band data, or wait
--until there is out-of-band data, using the `select' function; it can
--wait for an exceptional condition on the socket.  *Note Waiting for
--I/O::, for more information about `select'.
--
--   Notification of out-of-band data (whether with `SIGURG' or with
--`select') indicates that out-of-band data is on the way; the data may
--not actually arrive until later.  If you try to read the out-of-band
--data before it arrives, `recv' fails with an `EWOULDBLOCK' error.
--
--   Sending out-of-band data automatically places a "mark" in the stream
--of ordinary data, showing where in the sequence the out-of-band data
--"would have been".  This is useful when the meaning of out-of-band data
--is "cancel everything sent so far".  Here is how you can test, in the
--receiving process, whether any ordinary data was sent before the mark:
--
--     success = ioctl (socket, SIOCATMARK, &result);
--
--   Here's a function to discard any ordinary data preceding the
--out-of-band mark:
--
--     int
--     discard_until_mark (int socket)
--     {
--       while (1)
--         {
--           /* This is not an arbitrary limit; any size will do.  */
--           char buffer[1024];
--           int result, success;
--     
--           /* If we have reached the mark, return.  */
--           success = ioctl (socket, SIOCATMARK, &result);
--           if (success < 0)
--             perror ("ioctl");
--           if (result)
--             return;
--     
--           /* Otherwise, read a bunch of ordinary data and discard it.
--              This is guaranteed not to read past the mark
--              if it starts before the mark.  */
--           success = read (socket, buffer, sizeof buffer);
--           if (success < 0)
--             perror ("read");
--         }
--     }
--
--   If you don't want to discard the ordinary data preceding the mark,
--you may need to read some of it anyway, to make room in internal system
--buffers for the out-of-band data.  If you try to read out-of-band data
--and get an `EWOULDBLOCK' error, try reading some ordinary data (saving
--it so that you can use it when you want it) and see if that makes room.
--Here is an example:
--
--     struct buffer
--     {
--       char *buffer;
--       int size;
--       struct buffer *next;
--     };
--     
--     /* Read the out-of-band data from SOCKET and return it
--        as a `struct buffer', which records the address of the data
--        and its size.
--     
--        It may be necessary to read some ordinary data
--        in order to make room for the out-of-band data.
--        If so, the ordinary data is saved as a chain of buffers
--        found in the `next' field of the value.  */
--     
--     struct buffer *
--     read_oob (int socket)
--     {
--       struct buffer *tail = 0;
--       struct buffer *list = 0;
--     
--       while (1)
--         {
--           /* This is an arbitrary limit.
--              Does anyone know how to do this without a limit?  */
--           char *buffer = (char *) xmalloc (1024);
--           struct buffer *link;
--           int success;
--           int result;
--     
--           /* Try again to read the out-of-band data.  */
--           success = recv (socket, buffer, sizeof buffer, MSG_OOB);
--           if (success >= 0)
--             {
--               /* We got it, so return it.  */
--               struct buffer *link
--                 = (struct buffer *) xmalloc (sizeof (struct buffer));
--               link->buffer = buffer;
--               link->size = success;
--               link->next = list;
--               return link;
--             }
--     
--           /* If we fail, see if we are at the mark.  */
--           success = ioctl (socket, SIOCATMARK, &result);
--           if (success < 0)
--             perror ("ioctl");
--           if (result)
--             {
--               /* At the mark; skipping past more ordinary data cannot help.
--                  So just wait a while.  */
--               sleep (1);
--               continue;
--             }
--     
--           /* Otherwise, read a bunch of ordinary data and save it.
--              This is guaranteed not to read past the mark
--              if it starts before the mark.  */
--           success = read (socket, buffer, sizeof buffer);
--           if (success < 0)
--             perror ("read");
--     
--           /* Save this data in the buffer list.  */
--           {
--             struct buffer *link
--               = (struct buffer *) xmalloc (sizeof (struct buffer));
--             link->buffer = buffer;
--             link->size = success;
--     
--             /* Add the new link to the end of the list.  */
--             if (tail)
--               tail->next = link;
--             else
--               list = link;
--             tail = link;
--           }
--         }
--     }
--
--
--File: libc.info,  Node: Datagrams,  Next: Inetd,  Prev: Connections,  Up: 
Sockets
--
--Datagram Socket Operations
--==========================
--
--   This section describes how to use communication styles that don't use
--connections (styles `SOCK_DGRAM' and `SOCK_RDM').  Using these styles,
--you group data into packets and each packet is an independent
--communication.  You specify the destination for each packet
--individually.
--
--   Datagram packets are like letters: you send each one independently,
--with its own destination address, and they may arrive in the wrong
--order or not at all.
--
--   The `listen' and `accept' functions are not allowed for sockets
--using connectionless communication styles.
--
--* Menu:
--
--* Sending Datagrams::    Sending packets on a datagram socket.
--* Receiving Datagrams::  Receiving packets on a datagram socket.
--* Datagram Example::     An example program: packets sent over a
--                           datagram socket in the file namespace.
--* Example Receiver::   Another program, that receives those packets.
--
--
--File: libc.info,  Node: Sending Datagrams,  Next: Receiving Datagrams,  Up: 
Datagrams
--
--Sending Datagrams
-------------------
--
--   The normal way of sending data on a datagram socket is by using the
--`sendto' function, declared in `sys/socket.h'.
--
--   You can call `connect' on a datagram socket, but this only specifies
--a default destination for further data transmission on the socket.
--When a socket has a default destination, then you can use `send' (*note
--Sending Data::.) or even `write' (*note I/O Primitives::.) to send a
--packet there.  You can cancel the default destination by calling
--`connect' using an address format of `AF_UNSPEC' in the ADDR argument.
--*Note Connecting::, for more information about the `connect' function.
--
-- - Function: int sendto (int SOCKET, void *BUFFER. size_t SIZE, int
--          FLAGS, struct sockaddr *ADDR, size_t LENGTH)
--     The `sendto' function transmits the data in the BUFFER through the
--     socket SOCKET to the destination address specified by the ADDR and
--     LENGTH arguments.  The SIZE argument specifies the number of bytes
--     to be transmitted.
--
--     The FLAGS are interpreted the same way as for `send'; see *Note
--     Socket Data Options::.
--
--     The return value and error conditions are also the same as for
--     `send', but you cannot rely on the system to detect errors and
--     report them; the most common error is that the packet is lost or
--     there is no one at the specified address to receive it, and the
--     operating system on your machine usually does not know this.
--
--     It is also possible for one call to `sendto' to report an error
--     due to a problem related to a previous call.
--
--
--File: libc.info,  Node: Receiving Datagrams,  Next: Datagram Example,  Prev: 
Sending Datagrams,  Up: Datagrams
--
--Receiving Datagrams
---------------------
--
--   The `recvfrom' function reads a packet from a datagram socket and
--also tells you where it was sent from.  This function is declared in
--`sys/socket.h'.
--
-- - Function: int recvfrom (int SOCKET, void *BUFFER, size_t SIZE, int
--          FLAGS, struct sockaddr *ADDR, size_t *LENGTH-PTR)
--     The `recvfrom' function reads one packet from the socket SOCKET
--     into the buffer BUFFER.  The SIZE argument specifies the maximum
--     number of bytes to be read.
--
--     If the packet is longer than SIZE bytes, then you get the first
--     SIZE bytes of the packet, and the rest of the packet is lost.
--     There's no way to read the rest of the packet.  Thus, when you use
--     a packet protocol, you must always know how long a packet to
--     expect.
--
--     The ADDR and LENGTH-PTR arguments are used to return the address
--     where the packet came from.  *Note Socket Addresses::.  For a
--     socket in the file domain, the address information won't be
--     meaningful, since you can't read the address of such a socket
--     (*note File Namespace::.).  You can specify a null pointer as the
--     ADDR argument if you are not interested in this information.
--
--     The FLAGS are interpreted the same way as for `recv' (*note Socket
--     Data Options::.).  The return value and error conditions are also
--     the same as for `recv'.
--
--   You can use plain `recv' (*note Receiving Data::.) instead of
--`recvfrom' if you know don't need to find out who sent the packet
--(either because you know where it should come from or because you treat
--all possible senders alike).  Even `read' can be used if you don't want
--to specify FLAGS (*note I/O Primitives::.).
--
--
--File: libc.info,  Node: Datagram Example,  Next: Example Receiver,  Prev: 
Receiving Datagrams,  Up: Datagrams
--
--Datagram Socket Example
-------------------------
--
--   Here is a set of example programs that send messages over a datagram
--stream in the file namespace.  Both the client and server programs use
--the `make_named_socket' function that was presented in *Note File
--Namespace::, to create and name their sockets.
--
--   First, here is the server program.  It sits in a loop waiting for
--messages to arrive, bouncing each message back to the sender.
--Obviously, this isn't a particularly useful program, but it does show
--the general ideas involved.
--
--     #include <stdio.h>
--     #include <errno.h>
--     #include <stdlib.h>
--     #include <sys/socket.h>
--     #include <sys/un.h>
--     
--     #define SERVER  "/tmp/serversocket"
--     #define MAXMSG  512
--     
--     int
--     main (void)
--     {
--       int sock;
--       char message[MAXMSG];
--       struct sockaddr_un name;
--       size_t size;
--       int nbytes;
--     
--       /* Make the socket, then loop endlessly. */
--     
--       sock = make_named_socket (SERVER);
--       while (1)
--         {
--           /* Wait for a datagram. */
--           size = sizeof (name);
--           nbytes = recvfrom (sock, message, MAXMSG, 0,
--                              (struct sockaddr *) & name, &size);
--           if (nbytes < 0)
--             {
--               perror ("recfrom (server)");
--               exit (EXIT_FAILURE);
--             }
--     
--           /* Give a diagnostic message. */
--           fprintf (stderr, "Server: got message: %s\n", message);
--     
--           /* Bounce the message back to the sender. */
--           nbytes = sendto (sock, message, nbytes, 0,
--                            (struct sockaddr *) & name, size);
--           if (nbytes < 0)
--             {
--               perror ("sendto (server)");
--               exit (EXIT_FAILURE);
--             }
--         }
--     }
--
--
--File: libc.info,  Node: Example Receiver,  Prev: Datagram Example,  Up: 
Datagrams
--
--Example of Reading Datagrams
------------------------------
--
--   Here is the client program corresponding to the server above.
--
--   It sends a datagram to the server and then waits for a reply.  Notice
--that the socket for the client (as well as for the server) in this
--example has to be given a name.  This is so that the server can direct
--a message back to the client.  Since the socket has no associated
--connection state, the only way the server can do this is by referencing
--the name of the client.
--
--     #include <stdio.h>
--     #include <errno.h>
--     #include <unistd.h>
--     #include <stdlib.h>
--     #include <sys/socket.h>
--     #include <sys/un.h>
--     
--     #define SERVER  "/tmp/serversocket"
--     #define CLIENT  "/tmp/mysocket"
--     #define MAXMSG  512
--     #define MESSAGE "Yow!!! Are we having fun yet?!?"
--     
--     int
--     main (void)
--     {
--       extern int make_named_socket (const char *name);
--       int sock;
--       char message[MAXMSG];
--       struct sockaddr_un name;
--       size_t size;
--       int nbytes;
--     
--       /* Make the socket. */
--       sock = make_named_socket (CLIENT);
--     
--       /* Initialize the server socket address. */
--       name.sun_family = AF_UNIX;
--       strcpy (name.sun_path, SERVER);
--       size = strlen (name.sun_path) + sizeof (name.sun_family);
--     
--       /* Send the datagram. */
--       nbytes = sendto (sock, MESSAGE, strlen (MESSAGE) + 1, 0,
--                        (struct sockaddr *) & name, size);
--       if (nbytes < 0)
--         {
--           perror ("sendto (client)");
--           exit (EXIT_FAILURE);
--         }
--     
--       /* Wait for a reply. */
--       nbytes = recvfrom (sock, message, MAXMSG, 0, NULL, 0);
--       if (nbytes < 0)
--         {
--           perror ("recfrom (client)");
--           exit (EXIT_FAILURE);
--         }
--     
--       /* Print a diagnostic message. */
--       fprintf (stderr, "Client: got message: %s\n", message);
--     
--       /* Clean up. */
--       remove (CLIENT);
--       close (sock);
--     }
--
--   Keep in mind that datagram socket communications are unreliable.  In
--this example, the client program waits indefinitely if the message
--never reaches the server or if the server's response never comes back.
--It's up to the user running the program to kill it and restart it, if
--desired.  A more automatic solution could be to use `select' (*note
--Waiting for I/O::.) to establish a timeout period for the reply, and in
--case of timeout either resend the message or shut down the socket and
--exit.
--
--
--File: libc.info,  Node: Inetd,  Next: Socket Options,  Prev: Datagrams,  Up: 
Sockets
--
--The `inetd' Daemon
--==================
--
--   We've explained above how to write a server program that does its own
--listening.  Such a server must already be running in order for anyone
--to connect to it.
--
--   Another way to provide service for an Internet port is to let the
--daemon program `inetd' do the listening.  `inetd' is a program that
--runs all the time and waits (using `select') for messages on a
--specified set of ports.  When it receives a message, it accepts the
--connection (if the socket style calls for connections) and then forks a
--child process to run the corresponding server program.  You specify the
--ports and their programs in the file `/etc/inetd.conf'.
--
--* Menu:
--
--* Inetd Servers::
--* Configuring Inetd::
--
--
--File: libc.info,  Node: Inetd Servers,  Next: Configuring Inetd,  Up: Inetd
--
--`inetd' Servers
-----------------
--
--   Writing a server program to be run by `inetd' is very simple.  Each
--time someone requests a connection to the appropriate port, a new server
--process starts.  The connection already exists at this time; the socket
--is available as the standard input descriptor and as the standard
--output descriptor (descriptors 0 and 1) in the server process.  So the
--server program can begin reading and writing data right away.  Often
--the program needs only the ordinary I/O facilities; in fact, a
--general-purpose filter program that knows nothing about sockets can
--work as a byte stream server run by `inetd'.
--
--   You can also use `inetd' for servers that use connectionless
--communication styles.  For these servers, `inetd' does not try to accept
--a connection, since no connection is possible.  It just starts the
--server program, which can read the incoming datagram packet from
--descriptor 0.  The server program can handle one request and then exit,
--or you can choose to write it to keep reading more requests until no
--more arrive, and then exit.  You must specify which of these two
--techniques the server uses, when you configure `inetd'.
--
--
--File: libc.info,  Node: Configuring Inetd,  Prev: Inetd Servers,  Up: Inetd
--
--Configuring `inetd'
---------------------
--
--   The file `/etc/inetd.conf' tells `inetd' which ports to listen to
--and what server programs to run for them.  Normally each entry in the
--file is one line, but you can split it onto multiple lines provided all
--but the first line of the entry start with whitespace.  Lines that
--start with `#' are comments.
--
--   Here are two standard entries in `/etc/inetd.conf':
--
--     ftp      stream  tcp     nowait  root    /libexec/ftpd   ftpd
--     talk     dgram   udp     wait    root    /libexec/talkd  talkd
--
--   An entry has this format:
--
--     SERVICE STYLE PROTOCOL WAIT USERNAME PROGRAM ARGUMENTS
--
--   The SERVICE field says which service this program provides.  It
--should be the name of a service defined in `/etc/services'.  `inetd'
--uses SERVICE to decide which port to listen on for this entry.
--
--   The fields STYLE and PROTOCOL specify the communication style and
--the protocol to use for the listening socket.  The style should be the
--name of a communication style, converted to lower case and with `SOCK_'
--deleted--for example, `stream' or `dgram'.  PROTOCOL should be one of
--the protocols listed in `/etc/protocols'.  The typical protocol names
--are `tcp' for byte stream connections and `udp' for unreliable
--datagrams.
--
--   The WAIT field should be either `wait' or `nowait'.  Use `wait' if
--STYLE is a connectionless style and the server, once started, handles
--multiple requests, as many as come in.  Use `nowait' if `inetd' should
--start a new process for each message or request that comes in.  If
--STYLE uses connections, then WAIT *must* be `nowait'.
--
--   USER is the user name that the server should run as.  `inetd' runs
--as root, so it can set the user ID of its children arbitrarily.  It's
--best to avoid using `root' for USER if you can; but some servers, such
--as Telnet and FTP, read a username and password themselves.  These
--servers need to be root initially so they can log in as commanded by
--the data coming over the network.
--
--   PROGRAM together with ARGUMENTS specifies the command to run to
--start the server.  PROGRAM should be an absolute file name specifying
--the executable file to run.  ARGUMENTS consists of any number of
--whitespace-separated words, which become the command-line arguments of
--PROGRAM.  The first word in ARGUMENTS is argument zero, which should by
--convention be the program name itself (sans directories).
--
--   If you edit `/etc/inetd.conf', you can tell `inetd' to reread the
--file and obey its new contents by sending the `inetd' process the
--`SIGHUP' signal.  You'll have to use `ps' to determine the process ID
--of the `inetd' process, as it is not fixed.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-14 
glibc-2.0.1/manual/libc.info-14
---- ../glibc-2.0.1/manual/libc.info-14 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-14    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1159 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Socket Options,  Next: Networks Database,  Prev: 
Inetd,  Up: Sockets
--
--Socket Options
--==============
--
--   This section describes how to read or set various options that modify
--the behavior of sockets and their underlying communications protocols.
--
--   When you are manipulating a socket option, you must specify which
--"level" the option pertains to.  This describes whether the option
--applies to the socket interface, or to a lower-level communications
--protocol interface.
--
--* Menu:
--
--* Socket Option Functions::     The basic functions for setting and getting
--                                 socket options.
--* Socket-Level Options::        Details of the options at the socket level.
--
--
--File: libc.info,  Node: Socket Option Functions,  Next: Socket-Level Options, 
 Up: Socket Options
--
--Socket Option Functions
-------------------------
--
--   Here are the functions for examining and modifying socket options.
--They are declared in `sys/socket.h'.
--
-- - Function: int getsockopt (int SOCKET, int LEVEL, int OPTNAME, void
--          *OPTVAL, size_t *OPTLEN-PTR)
--     The `getsockopt' function gets information about the value of
--     option OPTNAME at level LEVEL for socket SOCKET.
--
--     The option value is stored in a buffer that OPTVAL points to.
--     Before the call, you should supply in `*OPTLEN-PTR' the size of
--     this buffer; on return, it contains the number of bytes of
--     information actually stored in the buffer.
--
--     Most options interpret the OPTVAL buffer as a single `int' value.
--
--     The actual return value of `getsockopt' is `0' on success and `-1'
--     on failure.  The following `errno' error conditions are defined:
--
--    `EBADF'
--          The SOCKET argument is not a valid file descriptor.
--
--    `ENOTSOCK'
--          The descriptor SOCKET is not a socket.
--
--    `ENOPROTOOPT'
--          The OPTNAME doesn't make sense for the given LEVEL.
--
-- - Function: int setsockopt (int SOCKET, int LEVEL, int OPTNAME, void
--          *OPTVAL, size_t OPTLEN)
--     This function is used to set the socket option OPTNAME at level
--     LEVEL for socket SOCKET.  The value of the option is passed in the
--     buffer OPTVAL, which has size OPTLEN.
--
--     The return value and error codes for `setsockopt' are the same as
--     for `getsockopt'.
--
--
--File: libc.info,  Node: Socket-Level Options,  Prev: Socket Option Functions, 
 Up: Socket Options
--
--Socket-Level Options
----------------------
--
-- - Constant: int SOL_SOCKET
--     Use this constant as the LEVEL argument to `getsockopt' or
--     `setsockopt' to manipulate the socket-level options described in
--     this section.
--
--   Here is a table of socket-level option names; all are defined in the
--header file `sys/socket.h'.
--
--`SO_DEBUG'
--     This option toggles recording of debugging information in the
--     underlying protocol modules.  The value has type `int'; a nonzero
--     value means "yes".
--
--`SO_REUSEADDR'
--     This option controls whether `bind' (*note Setting Address::.)
--     should permit reuse of local addresses for this socket.  If you
--     enable this option, you can actually have two sockets with the
--     same Internet port number; but the system won't allow you to use
--     the two identically-named sockets in a way that would confuse the
--     Internet.  The reason for this option is that some higher-level
--     Internet protocols, including FTP, require you to keep reusing the
--     same socket number.
--
--     The value has type `int'; a nonzero value means "yes".
--
--`SO_KEEPALIVE'
--     This option controls whether the underlying protocol should
--     periodically transmit messages on a connected socket.  If the peer
--     fails to respond to these messages, the connection is considered
--     broken.  The value has type `int'; a nonzero value means "yes".
--
--`SO_DONTROUTE'
--     This option controls whether outgoing messages bypass the normal
--     message routing facilities.  If set, messages are sent directly to
--     the network interface instead.  The value has type `int'; a nonzero
--     value means "yes".
--
--`SO_LINGER'
--     This option specifies what should happen when the socket of a type
--     that promises reliable delivery still has untransmitted messages
--     when it is closed; see *Note Closing a Socket::.  The value has
--     type `struct linger'.
--
--      - Data Type: struct linger
--          This structure type has the following members:
--
--         `int l_onoff'
--               This field is interpreted as a boolean.  If nonzero,
--               `close' blocks until the data is transmitted or the
--               timeout period has expired.
--
--         `int l_linger'
--               This specifies the timeout period, in seconds.
--
--`SO_BROADCAST'
--     This option controls whether datagrams may be broadcast from the
--     socket.  The value has type `int'; a nonzero value means "yes".
--
--`SO_OOBINLINE'
--     If this option is set, out-of-band data received on the socket is
--     placed in the normal input queue.  This permits it to be read using
--     `read' or `recv' without specifying the `MSG_OOB' flag.  *Note
--     Out-of-Band Data::.  The value has type `int'; a nonzero value
--     means "yes".
--
--`SO_SNDBUF'
--     This option gets or sets the size of the output buffer.  The value
--     is a `size_t', which is the size in bytes.
--
--`SO_RCVBUF'
--     This option gets or sets the size of the input buffer.  The value
--     is a `size_t', which is the size in bytes.
--
--`SO_STYLE'
--`SO_TYPE'
--     This option can be used with `getsockopt' only.  It is used to get
--     the socket's communication style.  `SO_TYPE' is the historical
--     name, and `SO_STYLE' is the preferred name in GNU.  The value has
--     type `int' and its value designates a communication style; see
--     *Note Communication Styles::.
--
--`SO_ERROR'
--     This option can be used with `getsockopt' only.  It is used to
--     reset the error status of the socket.  The value is an `int',
--     which represents the previous error status.
--
--
--File: libc.info,  Node: Networks Database,  Prev: Socket Options,  Up: Sockets
--
--Networks Database
--=================
--
--   Many systems come with a database that records a list of networks
--known to the system developer.  This is usually kept either in the file
--`/etc/networks' or in an equivalent from a name server.  This data base
--is useful for routing programs such as `route', but it is not useful
--for programs that simply communicate over the network.  We provide
--functions to access this data base, which are declared in `netdb.h'.
--
-- - Data Type: struct netent
--     This data type is used to represent information about entries in
--     the networks database.  It has the following members:
--
--    `char *n_name'
--          This is the "official" name of the network.
--
--    `char **n_aliases'
--          These are alternative names for the network, represented as a
--          vector of strings.  A null pointer terminates the array.
--
--    `int n_addrtype'
--          This is the type of the network number; this is always equal
--          to `AF_INET' for Internet networks.
--
--    `unsigned long int n_net'
--          This is the network number.  Network numbers are returned in
--          host byte order; see *Note Byte Order::.
--
--   Use the `getnetbyname' or `getnetbyaddr' functions to search the
--networks database for information about a specific network.  The
--information is returned in a statically-allocated structure; you must
--copy the information if you need to save it.
--
-- - Function: struct netent * getnetbyname (const char *NAME)
--     The `getnetbyname' function returns information about the network
--     named NAME.  It returns a null pointer if there is no such network.
--
-- - Function: struct netent * getnetbyaddr (long NET, int TYPE)
--     The `getnetbyaddr' function returns information about the network
--     of type TYPE with number NET.  You should specify a value of
--     `AF_INET' for the TYPE argument for Internet networks.
--
--     `getnetbyaddr' returns a null pointer if there is no such network.
--
--   You can also scan the networks database using `setnetent',
--`getnetent', and `endnetent'.  Be careful in using these functions,
--because they are not reentrant.
--
-- - Function: void setnetent (int STAYOPEN)
--     This function opens and rewinds the networks database.
--
--     If the STAYOPEN argument is nonzero, this sets a flag so that
--     subsequent calls to `getnetbyname' or `getnetbyaddr' will not
--     close the database (as they usually would).  This makes for more
--     efficiency if you call those functions several times, by avoiding
--     reopening the database for each call.
--
-- - Function: struct netent * getnetent (void)
--     This function returns the next entry in the networks database.  It
--     returns a null pointer if there are no more entries.
--
-- - Function: void endnetent (void)
--     This function closes the networks database.
--
--
--File: libc.info,  Node: Low-Level Terminal Interface,  Next: Mathematics,  
Prev: Sockets,  Up: Top
--
--Low-Level Terminal Interface
--****************************
--
--   This chapter describes functions that are specific to terminal
--devices.  You can use these functions to do things like turn off input
--echoing; set serial line characteristics such as line speed and flow
--control; and change which characters are used for end-of-file,
--command-line editing, sending signals, and similar control functions.
--
--   Most of the functions in this chapter operate on file descriptors.
--*Note Low-Level I/O::, for more information about what a file
--descriptor is and how to open a file descriptor for a terminal device.
--
--* Menu:
--
--* Is It a Terminal::            How to determine if a file is a terminal
--                               device, and what its name is.
--* I/O Queues::                  About flow control and typeahead.
--* Canonical or Not::            Two basic styles of input processing.
--* Terminal Modes::              How to examine and modify flags controlling
--                               details of terminal I/O: echoing,
--                                 signals, editing.
--* Line Control::                Sending break sequences, clearing
--                                 terminal buffers ...
--* Noncanon Example::            How to read single characters without echo.
--
--
--File: libc.info,  Node: Is It a Terminal,  Next: I/O Queues,  Up: Low-Level 
Terminal Interface
--
--Identifying Terminals
--=====================
--
--   The functions described in this chapter only work on files that
--correspond to terminal devices.  You can find out whether a file
--descriptor is associated with a terminal by using the `isatty' function.
--
--   Prototypes for both `isatty' and `ttyname' are declared in the
--header file `unistd.h'.
--
-- - Function: int isatty (int FILEDES)
--     This function returns `1' if FILEDES is a file descriptor
--     associated with an open terminal device, and `0' otherwise.
--
--   If a file descriptor is associated with a terminal, you can get its
--associated file name using the `ttyname' function.  See also the
--`ctermid' function, described in *Note Identifying the Terminal::.
--
-- - Function: char * ttyname (int FILEDES)
--     If the file descriptor FILEDES is associated with a terminal
--     device, the `ttyname' function returns a pointer to a
--     statically-allocated, null-terminated string containing the file
--     name of the terminal file.  The value is a null pointer if the
--     file descriptor isn't associated with a terminal, or the file name
--     cannot be determined.
--
--
--File: libc.info,  Node: I/O Queues,  Next: Canonical or Not,  Prev: Is It a 
Terminal,  Up: Low-Level Terminal Interface
--
--I/O Queues
--==========
--
--   Many of the remaining functions in this section refer to the input
--and output queues of a terminal device.  These queues implement a form
--of buffering *within the kernel* independent of the buffering
--implemented by I/O streams (*note I/O on Streams::.).
--
--   The "terminal input queue" is also sometimes referred to as its
--"typeahead buffer".  It holds the characters that have been received
--from the terminal but not yet read by any process.
--
--   The size of the terminal's input queue is described by the
--`MAX_INPUT' and `_POSIX_MAX_INPUT' parameters; see *Note Limits for
--Files::.  You are guaranteed a queue size of at least `MAX_INPUT', but
--the queue might be larger, and might even dynamically change size.  If
--input flow control is enabled by setting the `IXOFF' input mode bit
--(*note Input Modes::.), the terminal driver transmits STOP and START
--characters to the terminal when necessary to prevent the queue from
--overflowing.  Otherwise, input may be lost if it comes in too fast from
--the terminal.  In canonical mode, all input stays in the queue until a
--newline character is received, so the terminal input queue can fill up
--when you type a very long line.  *Note Canonical or Not::.
--
--   The "terminal output queue" is like the input queue, but for output;
--it contains characters that have been written by processes, but not yet
--transmitted to the terminal.  If output flow control is enabled by
--setting the `IXON' input mode bit (*note Input Modes::.), the terminal
--driver obeys STOP and STOP characters sent by the terminal to stop and
--restart transmission of output.
--
--   "Clearing" the terminal input queue means discarding any characters
--that have been received but not yet read.  Similarly, clearing the
--terminal output queue means discarding any characters that have been
--written but not yet transmitted.
--
--
--File: libc.info,  Node: Canonical or Not,  Next: Terminal Modes,  Prev: I/O 
Queues,  Up: Low-Level Terminal Interface
--
--Two Styles of Input: Canonical or Not
--=====================================
--
--   POSIX systems support two basic modes of input: canonical and
--noncanonical.
--
--   In "canonical input processing" mode, terminal input is processed in
--lines terminated by newline (`'\n''), EOF, or EOL characters.  No input
--can be read until an entire line has been typed by the user, and the
--`read' function (*note I/O Primitives::.) returns at most a single line
--of input, no matter how many bytes are requested.
--
--   In canonical input mode, the operating system provides input editing
--facilities: some characters are interpreted specially to perform editing
--operations within the current line of text, such as ERASE and KILL.
--*Note Editing Characters::.
--
--   The constants `_POSIX_MAX_CANON' and `MAX_CANON' parameterize the
--maximum number of bytes which may appear in a single line of canonical
--input.  *Note Limits for Files::.  You are guaranteed a maximum line
--length of at least `MAX_CANON' bytes, but the maximum might be larger,
--and might even dynamically change size.
--
--   In "noncanonical input processing" mode, characters are not grouped
--into lines, and ERASE and KILL processing is not performed.  The
--granularity with which bytes are read in noncanonical input mode is
--controlled by the MIN and TIME settings.  *Note Noncanonical Input::.
--
--   Most programs use canonical input mode, because this gives the user a
--way to edit input line by line.  The usual reason to use noncanonical
--mode is when the program accepts single-character commands or provides
--its own editing facilities.
--
--   The choice of canonical or noncanonical input is controlled by the
--`ICANON' flag in the `c_lflag' member of `struct termios'.  *Note Local
--Modes::.
--
--
--File: libc.info,  Node: Terminal Modes,  Next: Line Control,  Prev: Canonical 
or Not,  Up: Low-Level Terminal Interface
--
--Terminal Modes
--==============
--
--   This section describes the various terminal attributes that control
--how input and output are done.  The functions, data structures, and
--symbolic constants are all declared in the header file `termios.h'.
--
--* Menu:
--
--* Mode Data Types::             The data type `struct termios' and
--                                 related types.
--* Mode Functions::              Functions to read and set the terminal
--                                 attributes.
--* Setting Modes::               The right way to set terminal attributes
--                                 reliably.
--* Input Modes::                 Flags controlling low-level input handling.
--* Output Modes::                Flags controlling low-level output handling.
--* Control Modes::               Flags controlling serial port behavior.
--* Local Modes::                 Flags controlling high-level input handling.
--* Line Speed::                  How to read and set the terminal line speed.
--* Special Characters::          Characters that have special effects,
--                               and how to change them.
--* Noncanonical Input::          Controlling how long to wait for input.
--
--
--File: libc.info,  Node: Mode Data Types,  Next: Mode Functions,  Up: Terminal 
Modes
--
--Terminal Mode Data Types
--------------------------
--
--   The entire collection of attributes of a terminal is stored in a
--structure of type `struct termios'.  This structure is used with the
--functions `tcgetattr' and `tcsetattr' to read and set the attributes.
--
-- - Data Type: struct termios
--     Structure that records all the I/O attributes of a terminal.  The
--     structure includes at least the following members:
--
--    `tcflag_t c_iflag'
--          A bit mask specifying flags for input modes; see *Note Input
--          Modes::.
--
--    `tcflag_t c_oflag'
--          A bit mask specifying flags for output modes; see *Note
--          Output Modes::.
--
--    `tcflag_t c_cflag'
--          A bit mask specifying flags for control modes; see *Note
--          Control Modes::.
--
--    `tcflag_t c_lflag'
--          A bit mask specifying flags for local modes; see *Note Local
--          Modes::.
--
--    `cc_t c_cc[NCCS]'
--          An array specifying which characters are associated with
--          various control functions; see *Note Special Characters::.
--
--     The `struct termios' structure also contains members which encode
--     input and output transmission speeds, but the representation is
--     not specified.  *Note Line Speed::, for how to examine and store
--     the speed values.
--
--   The following sections describe the details of the members of the
--`struct termios' structure.
--
-- - Data Type: tcflag_t
--     This is an unsigned integer type used to represent the various bit
--     masks for terminal flags.
--
-- - Data Type: cc_t
--     This is an unsigned integer type used to represent characters
--     associated with various terminal control functions.
--
-- - Macro: int NCCS
--     The value of this macro is the number of elements in the `c_cc'
--     array.
--
--
--File: libc.info,  Node: Mode Functions,  Next: Setting Modes,  Prev: Mode 
Data Types,  Up: Terminal Modes
--
--Terminal Mode Functions
-------------------------
--
-- - Function: int tcgetattr (int FILEDES, struct termios *TERMIOS-P)
--     This function is used to examine the attributes of the terminal
--     device with file descriptor FILEDES.  The attributes are returned
--     in the structure that TERMIOS-P points to.
--
--     If successful, `tcgetattr' returns `0'.  A return value of `-1'
--     indicates an error.  The following `errno' error conditions are
--     defined for this function:
--
--    `EBADF'
--          The FILEDES argument is not a valid file descriptor.
--
--    `ENOTTY'
--          The FILEDES is not associated with a terminal.
--
-- - Function: int tcsetattr (int FILEDES, int WHEN, const struct termios
--          *TERMIOS-P)
--     This function sets the attributes of the terminal device with file
--     descriptor FILEDES.  The new attributes are taken from the
--     structure that TERMIOS-P points to.
--
--     The WHEN argument specifies how to deal with input and output
--     already queued.  It can be one of the following values:
--
--    `TCSANOW'
--          Make the change immediately.
--
--    `TCSADRAIN'
--          Make the change after waiting until all queued output has
--          been written.  You should usually use this option when
--          changing parameters that affect output.
--
--    `TCSAFLUSH'
--          This is like `TCSADRAIN', but also discards any queued input.
--
--    `TCSASOFT'
--          This is a flag bit that you can add to any of the above
--          alternatives.  Its meaning is to inhibit alteration of the
--          state of the terminal hardware.  It is a BSD extension; it is
--          only supported on BSD systems and the GNU system.
--
--          Using `TCSASOFT' is exactly the same as setting the `CIGNORE'
--          bit in the `c_cflag' member of the structure TERMIOS-P points
--          to.  *Note Control Modes::, for a description of `CIGNORE'.
--
--     If this function is called from a background process on its
--     controlling terminal, normally all processes in the process group
--     are sent a `SIGTTOU' signal, in the same way as if the process
--     were trying to write to the terminal.  The exception is if the
--     calling process itself is ignoring or blocking `SIGTTOU' signals,
--     in which case the operation is performed and no signal is sent.
--     *Note Job Control::.
--
--     If successful, `tcsetattr' returns `0'.  A return value of `-1'
--     indicates an error.  The following `errno' error conditions are
--     defined for this function:
--
--    `EBADF'
--          The FILEDES argument is not a valid file descriptor.
--
--    `ENOTTY'
--          The FILEDES is not associated with a terminal.
--
--    `EINVAL'
--          Either the value of the `when' argument is not valid, or
--          there is something wrong with the data in the TERMIOS-P
--          argument.
--
--   Although `tcgetattr' and `tcsetattr' specify the terminal device
--with a file descriptor, the attributes are those of the terminal device
--itself and not of the file descriptor.  This means that the effects of
--changing terminal attributes are persistent; if another process opens
--the terminal file later on, it will see the changed attributes even
--though it doesn't have anything to do with the open file descriptor you
--originally specified in changing the attributes.
--
--   Similarly, if a single process has multiple or duplicated file
--descriptors for the same terminal device, changing the terminal
--attributes affects input and output to all of these file descriptors.
--This means, for example, that you can't open one file descriptor or
--stream to read from a terminal in the normal line-buffered, echoed
--mode; and simultaneously have another file descriptor for the same
--terminal that you use to read from it in single-character, non-echoed
--mode.  Instead, you have to explicitly switch the terminal back and
--forth between the two modes.
--
--
--File: libc.info,  Node: Setting Modes,  Next: Input Modes,  Prev: Mode 
Functions,  Up: Terminal Modes
--
--Setting Terminal Modes Properly
---------------------------------
--
--   When you set terminal modes, you should call `tcgetattr' first to
--get the current modes of the particular terminal device, modify only
--those modes that you are really interested in, and store the result with
--`tcsetattr'.
--
--   It's a bad idea to simply initialize a `struct termios' structure to
--a chosen set of attributes and pass it directly to `tcsetattr'.  Your
--program may be run years from now, on systems that support members not
--documented in this manual.  The way to avoid setting these members to
--unreasonable values is to avoid changing them.
--
--   What's more, different terminal devices may require different mode
--settings in order to function properly.  So you should avoid blindly
--copying attributes from one terminal device to another.
--
--   When a member contains a collection of independent flags, as the
--`c_iflag', `c_oflag' and `c_cflag' members do, even setting the entire
--member is a bad idea, because particular operating systems have their
--own flags.  Instead, you should start with the current value of the
--member and alter only the flags whose values matter in your program,
--leaving any other flags unchanged.
--
--   Here is an example of how to set one flag (`ISTRIP') in the `struct
--termios' structure while properly preserving all the other data in the
--structure:
--
--     int
--     set_istrip (int desc, int value)
--     {
--       struct termios settings;
--       int result;
--
--     result = tcgetattr (desc, &settings);
--       if (result < 0)
--         {
--           perror ("error in tcgetattr");
--           return 0;
--         }
--
--     settings.c_iflag &= ~ISTRIP;
--       if (value)
--         settings.c_iflag |= ISTRIP;
--
--     result = tcsetattr (desc, TCSANOW, &settings);
--       if (result < 0)
--         {
--           perror ("error in tcgetattr");
--           return;
--        }
--       return 1;
--     }
--
--
--File: libc.info,  Node: Input Modes,  Next: Output Modes,  Prev: Setting 
Modes,  Up: Terminal Modes
--
--Input Modes
-------------
--
--   This section describes the terminal attribute flags that control
--fairly low-level aspects of input processing: handling of parity errors,
--break signals, flow control, and <RET> and <LFD> characters.
--
--   All of these flags are bits in the `c_iflag' member of the `struct
--termios' structure.  The member is an integer, and you change flags
--using the operators `&', `|' and `^'.  Don't try to specify the entire
--value for `c_iflag'--instead, change only specific flags and leave the
--rest untouched (*note Setting Modes::.).
--
-- - Macro: tcflag_t INPCK
--     If this bit is set, input parity checking is enabled.  If it is
--     not set, no checking at all is done for parity errors on input; the
--     characters are simply passed through to the application.
--
--     Parity checking on input processing is independent of whether
--     parity detection and generation on the underlying terminal
--     hardware is enabled; see *Note Control Modes::.  For example, you
--     could clear the `INPCK' input mode flag and set the `PARENB'
--     control mode flag to ignore parity errors on input, but still
--     generate parity on output.
--
--     If this bit is set, what happens when a parity error is detected
--     depends on whether the `IGNPAR' or `PARMRK' bits are set.  If
--     neither of these bits are set, a byte with a parity error is
--     passed to the application as a `'\0'' character.
--
-- - Macro: tcflag_t IGNPAR
--     If this bit is set, any byte with a framing or parity error is
--     ignored.  This is only useful if `INPCK' is also set.
--
-- - Macro: tcflag_t PARMRK
--     If this bit is set, input bytes with parity or framing errors are
--     marked when passed to the program.  This bit is meaningful only
--     when `INPCK' is set and `IGNPAR' is not set.
--
--     The way erroneous bytes are marked is with two preceding bytes,
--     `377' and `0'.  Thus, the program actually reads three bytes for
--     one erroneous byte received from the terminal.
--
--     If a valid byte has the value `0377', and `ISTRIP' (see below) is
--     not set, the program might confuse it with the prefix that marks a
--     parity error.  So a valid byte `0377' is passed to the program as
--     two bytes, `0377' `0377', in this case.
--
-- - Macro: tcflag_t ISTRIP
--     If this bit is set, valid input bytes are stripped to seven bits;
--     otherwise, all eight bits are available for programs to read.
--
-- - Macro: tcflag_t IGNBRK
--     If this bit is set, break conditions are ignored.
--
--     A "break condition" is defined in the context of asynchronous
--     serial data transmission as a series of zero-value bits longer
--     than a single byte.
--
-- - Macro: tcflag_t BRKINT
--     If this bit is set and `IGNBRK' is not set, a break condition
--     clears the terminal input and output queues and raises a `SIGINT'
--     signal for the foreground process group associated with the
--     terminal.
--
--     If neither `BRKINT' nor `IGNBRK' are set, a break condition is
--     passed to the application as a single `'\0'' character if `PARMRK'
--     is not set, or otherwise as a three-character sequence `'\377'',
--     `'\0'', `'\0''.
--
-- - Macro: tcflag_t IGNCR
--     If this bit is set, carriage return characters (`'\r'') are
--     discarded on input.  Discarding carriage return may be useful on
--     terminals that send both carriage return and linefeed when you
--     type the <RET> key.
--
-- - Macro: tcflag_t ICRNL
--     If this bit is set and `IGNCR' is not set, carriage return
--     characters (`'\r'') received as input are passed to the
--     application as newline characters (`'\n'').
--
-- - Macro: tcflag_t INLCR
--     If this bit is set, newline characters (`'\n'') received as input
--     are passed to the application as carriage return characters
--     (`'\r'').
--
-- - Macro: tcflag_t IXOFF
--     If this bit is set, start/stop control on input is enabled.  In
--     other words, the computer sends STOP and START characters as
--     necessary to prevent input from coming in faster than programs are
--     reading it.  The idea is that the actual terminal hardware that is
--     generating the input data responds to a STOP character by
--     suspending transmission, and to a START character by resuming
--     transmission.  *Note Start/Stop Characters::.
--
-- - Macro: tcflag_t IXON
--     If this bit is set, start/stop control on output is enabled.  In
--     other words, if the computer receives a STOP character, it
--     suspends output until a START character is received.  In this
--     case, the STOP and START characters are never passed to the
--     application program.  If this bit is not set, then START and STOP
--     can be read as ordinary characters.  *Note Start/Stop Characters::.
--
-- - Macro: tcflag_t IXANY
--     If this bit is set, any input character restarts output when
--     output has been suspended with the STOP character.  Otherwise,
--     only the START character restarts output.
--
--     This is a BSD extension; it exists only on BSD systems and the GNU
--     system.
--
-- - Macro: tcflag_t IMAXBEL
--     If this bit is set, then filling up the terminal input buffer
--     sends a BEL character (code `007') to the terminal to ring the
--     bell.
--
--     This is a BSD extension.
--
--
--File: libc.info,  Node: Output Modes,  Next: Control Modes,  Prev: Input 
Modes,  Up: Terminal Modes
--
--Output Modes
--------------
--
--   This section describes the terminal flags and fields that control how
--output characters are translated and padded for display.  All of these
--are contained in the `c_oflag' member of the `struct termios' structure.
--
--   The `c_oflag' member itself is an integer, and you change the flags
--and fields using the operators `&', `|', and `^'.  Don't try to specify
--the entire value for `c_oflag'--instead, change only specific flags and
--leave the rest untouched (*note Setting Modes::.).
--
-- - Macro: tcflag_t OPOST
--     If this bit is set, output data is processed in some unspecified
--     way so that it is displayed appropriately on the terminal device.
--     This typically includes mapping newline characters (`'\n'') onto
--     carriage return and linefeed pairs.
--
--     If this bit isn't set, the characters are transmitted as-is.
--
--   The following three bits are BSD features, and they exist only BSD
--systems and the GNU system.  They are effective only if `OPOST' is set.
--
-- - Macro: tcflag_t ONLCR
--     If this bit is set, convert the newline character on output into a
--     pair of characters, carriage return followed by linefeed.
--
-- - Macro: tcflag_t OXTABS
--     If this bit is set, convert tab characters on output into the
--     appropriate number of spaces to emulate a tab stop every eight
--     columns.
--
-- - Macro: tcflag_t ONOEOT
--     If this bit is set, discard `C-d' characters (code `004') on
--     output.  These characters cause many dial-up terminals to
--     disconnect.
--
--
--File: libc.info,  Node: Control Modes,  Next: Local Modes,  Prev: Output 
Modes,  Up: Terminal Modes
--
--Control Modes
---------------
--
--   This section describes the terminal flags and fields that control
--parameters usually associated with asynchronous serial data
--transmission.  These flags may not make sense for other kinds of
--terminal ports (such as a network connection pseudo-terminal).  All of
--these are contained in the `c_cflag' member of the `struct termios'
--structure.
--
--   The `c_cflag' member itself is an integer, and you change the flags
--and fields using the operators `&', `|', and `^'.  Don't try to specify
--the entire value for `c_cflag'--instead, change only specific flags and
--leave the rest untouched (*note Setting Modes::.).
--
-- - Macro: tcflag_t CLOCAL
--     If this bit is set, it indicates that the terminal is connected
--     "locally" and that the modem status lines (such as carrier detect)
--     should be ignored.
--
--     On many systems if this bit is not set and you call `open' without
--     the `O_NONBLOCK' flag set, `open' blocks until a modem connection
--     is established.
--
--     If this bit is not set and a modem disconnect is detected, a
--     `SIGHUP' signal is sent to the controlling process group for the
--     terminal (if it has one).  Normally, this causes the process to
--     exit; see *Note Signal Handling::.  Reading from the terminal
--     after a disconnect causes an end-of-file condition, and writing
--     causes an `EIO' error to be returned.  The terminal device must be
--     closed and reopened to clear the condition.
--
-- - Macro: tcflag_t HUPCL
--     If this bit is set, a modem disconnect is generated when all
--     processes that have the terminal device open have either closed
--     the file or exited.
--
-- - Macro: tcflag_t CREAD
--     If this bit is set, input can be read from the terminal.
--     Otherwise, input is discarded when it arrives.
--
-- - Macro: tcflag_t CSTOPB
--     If this bit is set, two stop bits are used.  Otherwise, only one
--     stop bit is used.
--
-- - Macro: tcflag_t PARENB
--     If this bit is set, generation and detection of a parity bit are
--     enabled.  *Note Input Modes::, for information on how input parity
--     errors are handled.
--
--     If this bit is not set, no parity bit is added to output
--     characters, and input characters are not checked for correct
--     parity.
--
-- - Macro: tcflag_t PARODD
--     This bit is only useful if `PARENB' is set.  If `PARODD' is set,
--     odd parity is used, otherwise even parity is used.
--
--   The control mode flags also includes a field for the number of bits
--per character.  You can use the `CSIZE' macro as a mask to extract the
--value, like this: `settings.c_cflag & CSIZE'.
--
-- - Macro: tcflag_t CSIZE
--     This is a mask for the number of bits per character.
--
-- - Macro: tcflag_t CS5
--     This specifies five bits per byte.
--
-- - Macro: tcflag_t CS6
--     This specifies six bits per byte.
--
-- - Macro: tcflag_t CS7
--     This specifies seven bits per byte.
--
-- - Macro: tcflag_t CS8
--     This specifies eight bits per byte.
--
--   The following four bits are BSD extensions; this exist only on BSD
--systems and the GNU system.
--
-- - Macro: tcflag_t CCTS_OFLOW
--     If this bit is set, enable flow control of output based on the CTS
--     wire (RS232 protocol).
--
-- - Macro: tcflag_t CRTS_IFLOW
--     If this bit is set, enable flow control of input based on the RTS
--     wire (RS232 protocol).
--
-- - Macro: tcflag_t MDMBUF
--     If this bit is set, enable carrier-based flow control of output.
--
-- - Macro: tcflag_t CIGNORE
--     If this bit is set, it says to ignore the control modes and line
--     speed values entirely.  This is only meaningful in a call to
--     `tcsetattr'.
--
--     The `c_cflag' member and the line speed values returned by
--     `cfgetispeed' and `cfgetospeed' will be unaffected by the call.
--     `CIGNORE' is useful if you want to set all the software modes in
--     the other members, but leave the hardware details in `c_cflag'
--     unchanged.  (This is how the `TCSASOFT' flag to `tcsettattr'
--     works.)
--
--     This bit is never set in the structure filled in by `tcgetattr'.
--
--
--File: libc.info,  Node: Local Modes,  Next: Line Speed,  Prev: Control Modes, 
 Up: Terminal Modes
--
--Local Modes
-------------
--
--   This section describes the flags for the `c_lflag' member of the
--`struct termios' structure.  These flags generally control higher-level
--aspects of input processing than the input modes flags described in
--*Note Input Modes::, such as echoing, signals, and the choice of
--canonical or noncanonical input.
--
--   The `c_lflag' member itself is an integer, and you change the flags
--and fields using the operators `&', `|', and `^'.  Don't try to specify
--the entire value for `c_lflag'--instead, change only specific flags and
--leave the rest untouched (*note Setting Modes::.).
--
-- - Macro: tcflag_t ICANON
--     This bit, if set, enables canonical input processing mode.
--     Otherwise, input is processed in noncanonical mode.  *Note
--     Canonical or Not::.
--
-- - Macro: tcflag_t ECHO
--     If this bit is set, echoing of input characters back to the
--     terminal is enabled.
--
-- - Macro: tcflag_t ECHOE
--     If this bit is set, echoing indicates erasure of input with the
--     ERASE character by erasing the last character in the current line
--     from the screen.  Otherwise, the character erased is re-echoed to
--     show what has happened (suitable for a printing terminal).
--
--     This bit only controls the display behavior; the `ICANON' bit by
--     itself controls actual recognition of the ERASE character and
--     erasure of input, without which `ECHOE' is simply irrelevant.
--
-- - Macro: tcflag_t ECHOPRT
--     This bit is like `ECHOE', enables display of the ERASE character in
--     a way that is geared to a hardcopy terminal.  When you type the
--     ERASE character, a `\' character is printed followed by the first
--     character erased.  Typing the ERASE character again just prints
--     the next character erased.  Then, the next time you type a normal
--     character, a `/' character is printed before the character echoes.
--
--     This is a BSD extension, and exists only in BSD systems and the
--     GNU system.
--
-- - Macro: tcflag_t ECHOK
--     This bit enables special display of the KILL character by moving
--     to a new line after echoing the KILL character normally.  The
--     behavior of `ECHOKE' (below) is nicer to look at.
--
--     If this bit is not set, the KILL character echoes just as it would
--     if it were not the KILL character.  Then it is up to the user to
--     remember that the KILL character has erased the preceding input;
--     there is no indication of this on the screen.
--
--     This bit only controls the display behavior; the `ICANON' bit by
--     itself controls actual recognition of the KILL character and
--     erasure of input, without which `ECHOK' is simply irrelevant.
--
-- - Macro: tcflag_t ECHOKE
--     This bit is similar to `ECHOK'.  It enables special display of the
--     KILL character by erasing on the screen the entire line that has
--     been killed.  This is a BSD extension, and exists only in BSD
--     systems and the GNU system.
--
-- - Macro: tcflag_t ECHONL
--     If this bit is set and the `ICANON' bit is also set, then the
--     newline (`'\n'') character is echoed even if the `ECHO' bit is not
--     set.
--
-- - Macro: tcflag_t ECHOCTL
--     If this bit is set and the `ECHO' bit is also set, echo control
--     characters with `^' followed by the corresponding text character.
--     Thus, control-A echoes as `^A'.  This is usually the preferred mode
--     for interactive input, because echoing a control character back to
--     the terminal could have some undesired effect on the terminal.
--
--     This is a BSD extension, and exists only in BSD systems and the
--     GNU system.
--
-- - Macro: tcflag_t ISIG
--     This bit controls whether the INTR, QUIT, and SUSP characters are
--     recognized.  The functions associated with these characters are
--     performed if and only if this bit is set.  Being in canonical or
--     noncanonical input mode has no affect on the interpretation of
--     these characters.
--
--     You should use caution when disabling recognition of these
--     characters.  Programs that cannot be interrupted interactively are
--     very user-unfriendly.  If you clear this bit, your program should
--     provide some alternate interface that allows the user to
--     interactively send the signals associated with these characters,
--     or to escape from the program.
--
--     *Note Signal Characters::.
--
-- - Macro: tcflag_t IEXTEN
--     POSIX.1 gives `IEXTEN' implementation-defined meaning, so you
--     cannot rely on this interpretation on all systems.
--
--     On BSD systems and the GNU system, it enables the LNEXT and
--     DISCARD characters.  *Note Other Special::.
--
-- - Macro: tcflag_t NOFLSH
--     Normally, the INTR, QUIT, and SUSP characters cause input and
--     output queues for the terminal to be cleared.  If this bit is set,
--     the queues are not cleared.
--
-- - Macro: tcflag_t TOSTOP
--     If this bit is set and the system supports job control, then
--     `SIGTTOU' signals are generated by background processes that
--     attempt to write to the terminal.  *Note Access to the Terminal::.
--
--   The following bits are BSD extensions; they exist only in BSD systems
--and the GNU system.
--
-- - Macro: tcflag_t ALTWERASE
--     This bit determines how far the WERASE character should erase.  The
--     WERASE character erases back to the beginning of a word; the
--     question is, where do words begin?
--
--     If this bit is clear, then the beginning of a word is a
--     nonwhitespace character following a whitespace character.  If the
--     bit is set, then the beginning of a word is an alphanumeric
--     character or underscore following a character which is none of
--     those.
--
--     *Note Editing Characters::, for more information about the WERASE
--     character.
--
-- - Macro: tcflag_t FLUSHO
--     This is the bit that toggles when the user types the DISCARD
--     character.  While this bit is set, all output is discarded.  *Note
--     Other Special::.
--
-- - Macro: tcflag_t NOKERNINFO
--     Setting this bit disables handling of the STATUS character.  *Note
--     Other Special::.
--
-- - Macro: tcflag_t PENDIN
--     If this bit is set, it indicates that there is a line of input that
--     needs to be reprinted.  Typing the REPRINT character sets this
--     bit; the bit remains set until reprinting is finished.  *Note
--     Editing Characters::.
--
--
--File: libc.info,  Node: Line Speed,  Next: Special Characters,  Prev: Local 
Modes,  Up: Terminal Modes
--
--Line Speed
------------
--
--   The terminal line speed tells the computer how fast to read and write
--data on the terminal.
--
--   If the terminal is connected to a real serial line, the terminal
--speed you specify actually controls the line--if it doesn't match the
--terminal's own idea of the speed, communication does not work.  Real
--serial ports accept only certain standard speeds.  Also, particular
--hardware may not support even all the standard speeds.  Specifying a
--speed of zero hangs up a dialup connection and turns off modem control
--signals.
--
--   If the terminal is not a real serial line (for example, if it is a
--network connection), then the line speed won't really affect data
--transmission speed, but some programs will use it to determine the
--amount of padding needed.  It's best to specify a line speed value that
--matches the actual speed of the actual terminal, but you can safely
--experiment with different values to vary the amount of padding.
--
--   There are actually two line speeds for each terminal, one for input
--and one for output.  You can set them independently, but most often
--terminals use the same speed for both directions.
--
--   The speed values are stored in the `struct termios' structure, but
--don't try to access them in the `struct termios' structure directly.
--Instead, you should use the following functions to read and store them:
--
-- - Function: speed_t cfgetospeed (const struct termios *TERMIOS-P)
--     This function returns the output line speed stored in the structure
--     `*TERMIOS-P'.
--
-- - Function: speed_t cfgetispeed (const struct termios *TERMIOS-P)
--     This function returns the input line speed stored in the structure
--     `*TERMIOS-P'.
--
-- - Function: int cfsetospeed (struct termios *TERMIOS-P, speed_t SPEED)
--     This function stores SPEED in `*TERMIOS-P' as the output speed.
--     The normal return value is `0'; a value of `-1' indicates an
--     error.  If SPEED is not a speed, `cfsetospeed' returns `-1'.
--
-- - Function: int cfsetispeed (struct termios *TERMIOS-P, speed_t SPEED)
--     This function stores SPEED in `*TERMIOS-P' as the input speed.
--     The normal return value is `0'; a value of `-1' indicates an
--     error.  If SPEED is not a speed, `cfsetospeed' returns `-1'.
--
-- - Function: int cfsetspeed (struct termios *TERMIOS-P, speed_t SPEED)
--     This function stores SPEED in `*TERMIOS-P' as both the input and
--     output speeds.  The normal return value is `0'; a value of `-1'
--     indicates an error.  If SPEED is not a speed, `cfsetspeed' returns
--     `-1'.  This function is an extension in 4.4 BSD.
--
-- - Data Type: speed_t
--     The `speed_t' type is an unsigned integer data type used to
--     represent line speeds.
--
--   The functions `cfsetospeed' and `cfsetispeed' report errors only for
--speed values that the system simply cannot handle.  If you specify a
--speed value that is basically acceptable, then those functions will
--succeed.  But they do not check that a particular hardware device can
--actually support the specified speeds--in fact, they don't know which
--device you plan to set the speed for.  If you use `tcsetattr' to set
--the speed of a particular device to a value that it cannot handle,
--`tcsetattr' returns `-1'.
--
--   *Portability note:* In the GNU library, the functions above accept
--speeds measured in bits per second as input, and return speed values
--measured in bits per second.  Other libraries require speeds to be
--indicated by special codes.  For POSIX.1 portability, you must use one
--of the following symbols to represent the speed; their precise numeric
--values are system-dependent, but each name has a fixed meaning: `B110'
--stands for 110 bps, `B300' for 300 bps, and so on.  There is no
--portable way to represent any speed but these, but these are the only
--speeds that typical serial lines can support.
--
--     B0  B50  B75  B110  B134  B150  B200
--     B300  B600  B1200  B1800  B2400  B4800
--     B9600  B19200  B38400
--
--   BSD defines two additional speed symbols as aliases: `EXTA' is an
--alias for `B19200' and `EXTB' is an alias for `B38400'.  These aliases
--are obsolete.
--
--
--File: libc.info,  Node: Special Characters,  Next: Noncanonical Input,  Prev: 
Line Speed,  Up: Terminal Modes
--
--Special Characters
--------------------
--
--   In canonical input, the terminal driver recognizes a number of
--special characters which perform various control functions.  These
--include the ERASE character (usually <DEL>) for editing input, and
--other editing characters.  The INTR character (normally `C-c') for
--sending a `SIGINT' signal, and other signal-raising characters, may be
--available in either canonical or noncanonical input mode.  All these
--characters are described in this section.
--
--   The particular characters used are specified in the `c_cc' member of
--the `struct termios' structure.  This member is an array; each element
--specifies the character for a particular role.  Each element has a
--symbolic constant that stands for the index of that element--for
--example, `INTR' is the index of the element that specifies the INTR
--character, so storing `'='' in `TERMIOS.c_cc[INTR]' specifies `=' as
--the INTR character.
--
--   On some systems, you can disable a particular special character
--function by specifying the value `_POSIX_VDISABLE' for that role.  This
--value is unequal to any possible character code.  *Note Options for
--Files::, for more information about how to tell whether the operating
--system you are using supports `_POSIX_VDISABLE'.
--
--* Menu:
--
--* Editing Characters::          Special characters that terminate lines and
--                                  delete text, and other editing functions.
--* Signal Characters::           Special characters that send or raise signals
--                                  to or for certain classes of processes.
--* Start/Stop Characters::       Special characters that suspend or resume
--                                  suspended output.
--* Other Special::             Other special characters for BSD systems:
--                                they can discard output, and print status.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-15 
glibc-2.0.1/manual/libc.info-15
---- ../glibc-2.0.1/manual/libc.info-15 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-15    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1220 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Editing Characters,  Next: Signal Characters,  Up: 
Special Characters
--
--Characters for Input Editing
--............................
--
--   These special characters are active only in canonical input mode.
--*Note Canonical or Not::.
--
-- - Macro: int VEOF
--     This is the subscript for the EOF character in the special control
--     character array.  `TERMIOS.c_cc[VEOF]' holds the character itself.
--
--     The EOF character is recognized only in canonical input mode.  It
--     acts as a line terminator in the same way as a newline character,
--     but if the EOF character is typed at the beginning of a line it
--     causes `read' to return a byte count of zero, indicating
--     end-of-file.  The EOF character itself is discarded.
--
--     Usually, the EOF character is `C-d'.
--
-- - Macro: int VEOL
--     This is the subscript for the EOL character in the special control
--     character array.  `TERMIOS.c_cc[VEOL]' holds the character itself.
--
--     The EOL character is recognized only in canonical input mode.  It
--     acts as a line terminator, just like a newline character.  The EOL
--     character is not discarded; it is read as the last character in
--     the input line.
--
--     You don't need to use the EOL character to make <RET> end a line.
--     Just set the ICRNL flag.  In fact, this is the default state of
--     affairs.
--
-- - Macro: int VEOL2
--     This is the subscript for the EOL2 character in the special control
--     character array.  `TERMIOS.c_cc[VEOL2]' holds the character itself.
--
--     The EOL2 character works just like the EOL character (see above),
--     but it can be a different character.  Thus, you can specify two
--     characters to terminate an input line, by setting EOL to one of
--     them and EOL2 to the other.
--
--     The EOL2 character is a BSD extension; it exists only on BSD
--     systems and the GNU system.
--
-- - Macro: int VERASE
--     This is the subscript for the ERASE character in the special
--     control character array.  `TERMIOS.c_cc[VERASE]' holds the
--     character itself.
--
--     The ERASE character is recognized only in canonical input mode.
--     When the user types the erase character, the previous character
--     typed is discarded.  (If the terminal generates multibyte
--     character sequences, this may cause more than one byte of input to
--     be discarded.)  This cannot be used to erase past the beginning of
--     the current line of text.  The ERASE character itself is discarded.
--
--     Usually, the ERASE character is <DEL>.
--
-- - Macro: int VWERASE
--     This is the subscript for the WERASE character in the special
--     control character array.  `TERMIOS.c_cc[VWERASE]' holds the
--     character itself.
--
--     The WERASE character is recognized only in canonical mode.  It
--     erases an entire word of prior input, and any whitespace after it;
--     whitespace characters before the word are not erased.
--
--     The definition of a "word" depends on the setting of the
--     `ALTWERASE' mode; *note Local Modes::..
--
--     If the `ALTWERASE' mode is not set, a word is defined as a sequence
--     of any characters except space or tab.
--
--     If the `ALTWERASE' mode is set, a word is defined as a sequence of
--     characters containing only letters, numbers, and underscores,
--     optionally followed by one character that is not a letter, number,
--     or underscore.
--
--     The WERASE character is usually `C-w'.
--
--     This is a BSD extension.
--
-- - Macro: int VKILL
--     This is the subscript for the KILL character in the special control
--     character array.  `TERMIOS.c_cc[VKILL]' holds the character itself.
--
--     The KILL character is recognized only in canonical input mode.
--     When the user types the kill character, the entire contents of the
--     current line of input are discarded.  The kill character itself is
--     discarded too.
--
--     The KILL character is usually `C-u'.
--
-- - Macro: int VREPRINT
--     This is the subscript for the REPRINT character in the special
--     control character array.  `TERMIOS.c_cc[VREPRINT]' holds the
--     character itself.
--
--     The REPRINT character is recognized only in canonical mode.  It
--     reprints the current input line.  If some asynchronous output has
--     come while you are typing, this lets you see the line you are
--     typing clearly again.
--
--     The REPRINT character is usually `C-r'.
--
--     This is a BSD extension.
--
--
--File: libc.info,  Node: Signal Characters,  Next: Start/Stop Characters,  
Prev: Editing Characters,  Up: Special Characters
--
--Characters that Cause Signals
--.............................
--
--   These special characters may be active in either canonical or
--noncanonical input mode, but only when the `ISIG' flag is set (*note
--Local Modes::.).
--
-- - Macro: int VINTR
--     This is the subscript for the INTR character in the special control
--     character array.  `TERMIOS.c_cc[VINTR]' holds the character itself.
--
--     The INTR (interrupt) character raises a `SIGINT' signal for all
--     processes in the foreground job associated with the terminal.  The
--     INTR character itself is then discarded.  *Note Signal Handling::,
--     for more information about signals.
--
--     Typically, the INTR character is `C-c'.
--
-- - Macro: int VQUIT
--     This is the subscript for the QUIT character in the special control
--     character array.  `TERMIOS.c_cc[VQUIT]' holds the character itself.
--
--     The QUIT character raises a `SIGQUIT' signal for all processes in
--     the foreground job associated with the terminal.  The QUIT
--     character itself is then discarded.  *Note Signal Handling::, for
--     more information about signals.
--
--     Typically, the QUIT character is `C-\'.
--
-- - Macro: int VSUSP
--     This is the subscript for the SUSP character in the special control
--     character array.  `TERMIOS.c_cc[VSUSP]' holds the character itself.
--
--     The SUSP (suspend) character is recognized only if the
--     implementation supports job control (*note Job Control::.).  It
--     causes a `SIGTSTP' signal to be sent to all processes in the
--     foreground job associated with the terminal.  The SUSP character
--     itself is then discarded.  *Note Signal Handling::, for more
--     information about signals.
--
--     Typically, the SUSP character is `C-z'.
--
--   Few applications disable the normal interpretation of the SUSP
--character.  If your program does this, it should provide some other
--mechanism for the user to stop the job.  When the user invokes this
--mechanism, the program should send a `SIGTSTP' signal to the process
--group of the process, not just to the process itself.  *Note Signaling
--Another Process::.
--
-- - Macro: int VDSUSP
--     This is the subscript for the DSUSP character in the special
--     control character array.  `TERMIOS.c_cc[VDSUSP]' holds the
--     character itself.
--
--     The DSUSP (suspend) character is recognized only if the
--     implementation supports job control (*note Job Control::.).  It
--     sends a `SIGTSTP' signal, like the SUSP character, but not right
--     away--only when the program tries to read it as input.  Not all
--     systems with job control support DSUSP; only BSD-compatible
--     systems (including the GNU system).
--
--     *Note Signal Handling::, for more information about signals.
--
--     Typically, the DSUSP character is `C-y'.
--
--
--File: libc.info,  Node: Start/Stop Characters,  Next: Other Special,  Prev: 
Signal Characters,  Up: Special Characters
--
--Special Characters for Flow Control
--...................................
--
--   These special characters may be active in either canonical or
--noncanonical input mode, but their use is controlled by the flags
--`IXON' and `IXOFF' (*note Input Modes::.).
--
-- - Macro: int VSTART
--     This is the subscript for the START character in the special
--     control character array.  `TERMIOS.c_cc[VSTART]' holds the
--     character itself.
--
--     The START character is used to support the `IXON' and `IXOFF'
--     input modes.  If `IXON' is set, receiving a START character resumes
--     suspended output; the START character itself is discarded.  If
--     `IXANY' is set, receiving any character at all resumes suspended
--     output; the resuming character is not discarded unless it is the
--     START character.  `IXOFF' is set, the system may also transmit
--     START characters to the terminal.
--
--     The usual value for the START character is `C-q'.  You may not be
--     able to change this value--the hardware may insist on using `C-q'
--     regardless of what you specify.
--
-- - Macro: int VSTOP
--     This is the subscript for the STOP character in the special control
--     character array.  `TERMIOS.c_cc[VSTOP]' holds the character itself.
--
--     The STOP character is used to support the `IXON' and `IXOFF' input
--     modes.  If `IXON' is set, receiving a STOP character causes output
--     to be suspended; the STOP character itself is discarded.  If
--     `IXOFF' is set, the system may also transmit STOP characters to the
--     terminal, to prevent the input queue from overflowing.
--
--     The usual value for the STOP character is `C-s'.  You may not be
--     able to change this value--the hardware may insist on using `C-s'
--     regardless of what you specify.
--
--
--File: libc.info,  Node: Other Special,  Prev: Start/Stop Characters,  Up: 
Special Characters
--
--Other Special Characters
--........................
--
--   These special characters exist only in BSD systems and the GNU
--system.
--
-- - Macro: int VLNEXT
--     This is the subscript for the LNEXT character in the special
--     control character array.  `TERMIOS.c_cc[VLNEXT]' holds the
--     character itself.
--
--     The LNEXT character is recognized only when `IEXTEN' is set, but in
--     both canonical and noncanonical mode.  It disables any special
--     significance of the next character the user types.  Even if the
--     character would normally perform some editing function or generate
--     a signal, it is read as a plain character.  This is the analogue
--     of the `C-q' command in Emacs.  "LNEXT" stands for "literal next."
--
--     The LNEXT character is usually `C-v'.
--
-- - Macro: int VDISCARD
--     This is the subscript for the DISCARD character in the special
--     control character array.  `TERMIOS.c_cc[VDISCARD]' holds the
--     character itself.
--
--     The DISCARD character is recognized only when `IEXTEN' is set, but
--     in both canonical and noncanonical mode.  Its effect is to toggle
--     the discard-output flag.  When this flag is set, all program
--     output is discarded.  Setting the flag also discards all output
--     currently in the output buffer.  Typing any other character resets
--     the flag.
--
-- - Macro: int VSTATUS
--     This is the subscript for the STATUS character in the special
--     control character array.  `TERMIOS.c_cc[VSTATUS]' holds the
--     character itself.
--
--     The STATUS character's effect is to print out a status message
--     about how the current process is running.
--
--     The STATUS character is recognized only in canonical mode, and
--     only if `NOKERNINFO' is not set.
--
--
--File: libc.info,  Node: Noncanonical Input,  Prev: Special Characters,  Up: 
Terminal Modes
--
--Noncanonical Input
--------------------
--
--   In noncanonical input mode, the special editing characters such as
--ERASE and KILL are ignored.  The system facilities for the user to edit
--input are disabled in noncanonical mode, so that all input characters
--(unless they are special for signal or flow-control purposes) are passed
--to the application program exactly as typed.  It is up to the
--application program to give the user ways to edit the input, if
--appropriate.
--
--   Noncanonical mode offers special parameters called MIN and TIME for
--controlling whether and how long to wait for input to be available.  You
--can even use them to avoid ever waiting--to return immediately with
--whatever input is available, or with no input.
--
--   The MIN and TIME are stored in elements of the `c_cc' array, which
--is a member of the `struct termios' structure.  Each element of this
--array has a particular role, and each element has a symbolic constant
--that stands for the index of that element.  `VMIN' and `VMAX' are the
--names for the indices in the array of the MIN and TIME slots.
--
-- - Macro: int VMIN
--     This is the subscript for the MIN slot in the `c_cc' array.  Thus,
--     `TERMIOS.c_cc[VMIN]' is the value itself.
--
--     The MIN slot is only meaningful in noncanonical input mode; it
--     specifies the minimum number of bytes that must be available in the
--     input queue in order for `read' to return.
--
-- - Macro: int VTIME
--     This is the subscript for the TIME slot in the `c_cc' array.  Thus,
--     `TERMIOS.c_cc[VTIME]' is the value itself.
--
--     The TIME slot is only meaningful in noncanonical input mode; it
--     specifies how long to wait for input before returning, in units of
--     0.1 seconds.
--
--   The MIN and TIME values interact to determine the criterion for when
--`read' should return; their precise meanings depend on which of them
--are nonzero.  There are four possible cases:
--
--   * Both TIME and MIN are nonzero.
--
--     In this case, TIME specifies how long to wait after each input
--     character to see if more input arrives.  After the first character
--     received, `read' keeps waiting until either MIN bytes have arrived
--     in all, or TIME elapses with no further input.
--
--     `read' always blocks until the first character arrives, even if
--     TIME elapses first.  `read' can return more than MIN characters if
--     more than MIN happen to be in the queue.
--
--   * Both MIN and TIME are zero.
--
--     In this case, `read' always returns immediately with as many
--     characters as are available in the queue, up to the number
--     requested.  If no input is immediately available, `read' returns a
--     value of zero.
--
--   * MIN is zero but TIME has a nonzero value.
--
--     In this case, `read' waits for time TIME for input to become
--     available; the availability of a single byte is enough to satisfy
--     the read request and cause `read' to return.  When it returns, it
--     returns as many characters as are available, up to the number
--     requested.  If no input is available before the timer expires,
--     `read' returns a value of zero.
--
--   * TIME is zero but MIN has a nonzero value.
--
--     In this case, `read' waits until at least MIN bytes are available
--     in the queue.  At that time, `read' returns as many characters as
--     are available, up to the number requested.  `read' can return more
--     than MIN characters if more than MIN happen to be in the queue.
--
--   What happens if MIN is 50 and you ask to read just 10 bytes?
--Normally, `read' waits until there are 50 bytes in the buffer (or, more
--generally, the wait condition described above is satisfied), and then
--reads 10 of them, leaving the other 40 buffered in the operating system
--for a subsequent call to `read'.
--
--   *Portability note:* On some systems, the MIN and TIME slots are
--actually the same as the EOF and EOL slots.  This causes no serious
--problem because the MIN and TIME slots are used only in noncanonical
--input and the EOF and EOL slots are used only in canonical input, but it
--isn't very clean.  The GNU library allocates separate slots for these
--uses.
--
-- - Function: int cfmakeraw (struct termios *TERMIOS-P)
--     This function provides an easy way to set up `*TERMIOS-P' for what
--     has traditionally been called "raw mode" in BSD.  This uses
--     noncanonical input, and turns off most processing to give an
--     unmodified channel to the terminal.
--
--     It does exactly this:
--            TERMIOS-P->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
--                                          |INLCR|IGNCR|ICRNL|IXON);
--            TERMIOS-P->c_oflag &= ~OPOST;
--            TERMIOS-P->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
--            TERMIOS-P->c_cflag &= ~(CSIZE|PARENB);
--            TERMIOS-P->c_cflag |= CS8;
--
--
--File: libc.info,  Node: Line Control,  Next: Noncanon Example,  Prev: 
Terminal Modes,  Up: Low-Level Terminal Interface
--
--Line Control Functions
--======================
--
--   These functions perform miscellaneous control actions on terminal
--devices.  As regards terminal access, they are treated like doing
--output: if any of these functions is used by a background process on its
--controlling terminal, normally all processes in the process group are
--sent a `SIGTTOU' signal.  The exception is if the calling process
--itself is ignoring or blocking `SIGTTOU' signals, in which case the
--operation is performed and no signal is sent.  *Note Job Control::.
--
-- - Function: int tcsendbreak (int FILEDES, int DURATION)
--     This function generates a break condition by transmitting a stream
--     of zero bits on the terminal associated with the file descriptor
--     FILEDES.  The duration of the break is controlled by the DURATION
--     argument.  If zero, the duration is between 0.25 and 0.5 seconds.
--     The meaning of a nonzero value depends on the operating system.
--
--     This function does nothing if the terminal is not an asynchronous
--     serial data port.
--
--     The return value is normally zero.  In the event of an error, a
--     value of `-1' is returned.  The following `errno' error conditions
--     are defined for this function:
--
--    `EBADF'
--          The FILEDES is not a valid file descriptor.
--
--    `ENOTTY'
--          The FILEDES is not associated with a terminal device.
--
-- - Function: int tcdrain (int FILEDES)
--     The `tcdrain' function waits until all queued output to the
--     terminal FILEDES has been transmitted.
--
--     The return value is normally zero.  In the event of an error, a
--     value of `-1' is returned.  The following `errno' error conditions
--     are defined for this function:
--
--    `EBADF'
--          The FILEDES is not a valid file descriptor.
--
--    `ENOTTY'
--          The FILEDES is not associated with a terminal device.
--
--    `EINTR'
--          The operation was interrupted by delivery of a signal.  *Note
--          Interrupted Primitives::.
--
-- - Function: int tcflush (int FILEDES, int QUEUE)
--     The `tcflush' function is used to clear the input and/or output
--     queues associated with the terminal file FILEDES.  The QUEUE
--     argument specifies which queue(s) to clear, and can be one of the
--     following values:
--
--    `TCIFLUSH'
--          Clear any input data received, but not yet read.
--
--    `TCOFLUSH'
--          Clear any output data written, but not yet transmitted.
--
--    `TCIOFLUSH'
--          Clear both queued input and output.
--
--     The return value is normally zero.  In the event of an error, a
--     value of `-1' is returned.  The following `errno' error conditions
--     are defined for this function:
--
--    `EBADF'
--          The FILEDES is not a valid file descriptor.
--
--    `ENOTTY'
--          The FILEDES is not associated with a terminal device.
--
--    `EINVAL'
--          A bad value was supplied as the QUEUE argument.
--
--     It is unfortunate that this function is named `tcflush', because
--     the term "flush" is normally used for quite another
--     operation--waiting until all output is transmitted--and using it
--     for discarding input or output would be confusing.  Unfortunately,
--     the name `tcflush' comes from POSIX and we cannot change it.
--
-- - Function: int tcflow (int FILEDES, int ACTION)
--     The `tcflow' function is used to perform operations relating to
--     XON/XOFF flow control on the terminal file specified by FILEDES.
--
--     The ACTION argument specifies what operation to perform, and can
--     be one of the following values:
--
--    `TCOOFF'
--          Suspend transmission of output.
--
--    `TCOON'
--          Restart transmission of output.
--
--    `TCIOFF'
--          Transmit a STOP character.
--
--    `TCION'
--          Transmit a START character.
--
--     For more information about the STOP and START characters, see
--     *Note Special Characters::.
--
--     The return value is normally zero.  In the event of an error, a
--     value of `-1' is returned.  The following `errno' error conditions
--     are defined for this function:
--
--    `EBADF'
--          The FILEDES is not a valid file descriptor.
--
--    `ENOTTY'
--          The FILEDES is not associated with a terminal device.
--
--    `EINVAL'
--          A bad value was supplied as the ACTION argument.
--
--
--File: libc.info,  Node: Noncanon Example,  Prev: Line Control,  Up: Low-Level 
Terminal Interface
--
--Noncanonical Mode Example
--=========================
--
--   Here is an example program that shows how you can set up a terminal
--device to read single characters in noncanonical input mode, without
--echo.
--
--     #include <unistd.h>
--     #include <stdio.h>
--     #include <stdlib.h>
--     #include <termios.h>
--     
--     /* Use this variable to remember original terminal attributes. */
--     
--     struct termios saved_attributes;
--     
--     void
--     reset_input_mode (void)
--     {
--       tcsetattr (STDIN_FILENO, TCSANOW, &saved_attributes);
--     }
--     
--     void
--     set_input_mode (void)
--     {
--       struct termios tattr;
--       char *name;
--     
--       /* Make sure stdin is a terminal. */
--       if (!isatty (STDIN_FILENO))
--         {
--           fprintf (stderr, "Not a terminal.\n");
--           exit (EXIT_FAILURE);
--         }
--     
--       /* Save the terminal attributes so we can restore them later. */
--       tcgetattr (STDIN_FILENO, &saved_attributes);
--       atexit (reset_input_mode);
--     /* Set the funny terminal modes. */
--       tcgetattr (STDIN_FILENO, &tattr);
--       tattr.c_lflag &= ~(ICANON|ECHO); /* Clear ICANON and ECHO. */
--       tattr.c_cc[VMIN] = 1;
--       tattr.c_cc[VTIME] = 0;
--       tcsetattr (STDIN_FILENO, TCSAFLUSH, &tattr);
--     }
--     
--     int
--     main (void)
--     {
--       char c;
--     
--       set_input_mode ();
--     
--       while (1)
--         {
--           read (STDIN_FILENO, &c, 1);
--           if (c == '\004')          /* `C-d' */
--             break;
--           else
--             putchar (c);
--         }
--     
--       return EXIT_SUCCESS;
--     }
--
--   This program is careful to restore the original terminal modes before
--exiting or terminating with a signal.  It uses the `atexit' function
--(*note Cleanups on Exit::.) to make sure this is done by `exit'.
--
--   The shell is supposed to take care of resetting the terminal modes
--when a process is stopped or continued; see *Note Job Control::.  But
--some existing shells do not actually do this, so you may wish to
--establish handlers for job control signals that reset terminal modes.
--The above example does so.
--
--
--File: libc.info,  Node: Mathematics,  Next: Arithmetic,  Prev: Low-Level 
Terminal Interface,  Up: Top
--
--Mathematics
--***********
--
--   This chapter contains information about functions for performing
--mathematical computations, such as trigonometric functions.  Most of
--these functions have prototypes declared in the header file `math.h'.
--
--   All of the functions that operate on floating-point numbers accept
--arguments and return results of type `double'.  In the future, there
--may be additional functions that operate on `float' and `long double'
--values.  For example, `cosf' and `cosl' would be versions of the `cos'
--function that operate on `float' and `long double' arguments,
--respectively.  In the meantime, you should avoid using these names
--yourself.  *Note Reserved Names::.
--
--* Menu:
--
--* Domain and Range Errors::     Detecting overflow conditions and the like.
--* Trig Functions::              Sine, cosine, and tangent.
--* Inverse Trig Functions::      Arc sine, arc cosine, and arc tangent.
--* Exponents and Logarithms::    Also includes square root.
--* Hyperbolic Functions::        Hyperbolic sine and friends.
--* Pseudo-Random Numbers::       Functions for generating pseudo-random
--                               numbers.
--
--
--File: libc.info,  Node: Domain and Range Errors,  Next: Trig Functions,  Up: 
Mathematics
--
--Domain and Range Errors
--=======================
--
--   Many of the functions listed in this chapter are defined
--mathematically over a domain that is only a subset of real numbers.
--For example, the `acos' function is defined over the domain between
--`-1' and `1'.  If you pass an argument to one of these functions that is
--outside the domain over which it is defined, the function sets `errno'
--to `EDOM' to indicate a "domain error".  On machines that support
--IEEE 754 floating point, functions reporting error `EDOM' also return a
--NaN.
--
--   Some of these functions are defined mathematically to result in a
--complex value over parts of their domains.  The most familiar example of
--this is taking the square root of a negative number.  The functions in
--this chapter take only real arguments and return only real values;
--therefore, if the value ought to be nonreal, this is treated as a domain
--error.
--
--   A related problem is that the mathematical result of a function may
--not be representable as a floating point number.  If magnitude of the
--correct result is too large to be represented, the function sets
--`errno' to `ERANGE' to indicate a "range error", and returns a
--particular very large value (named by the macro `HUGE_VAL') or its
--negation (`- HUGE_VAL').
--
--   If the magnitude of the result is too small, a value of zero is
--returned instead.  In this case, `errno' might or might not be set to
--`ERANGE'.
--
--   The only completely reliable way to check for domain and range
--errors is to set `errno' to `0' before you call the mathematical
--function and test `errno' afterward.  As a consequence of this use of
--`errno', use of the mathematical functions is not reentrant if you
--check for errors.
--
--   None of the mathematical functions ever generates signals as a
--result of domain or range errors.  In particular, this means that you
--won't see `SIGFPE' signals generated within these functions.  (*Note
--Signal Handling::, for more information about signals.)
--
-- - Macro: double HUGE_VAL
--     An expression representing a particular very large number.  On
--     machines that use IEEE 754/IEEE 854 floating point format, the
--     value is "infinity".  On other machines, it's typically the
--     largest positive number that can be represented.
--
--     The value of this macro is used as the return value from various
--     mathematical `double' returning functions in overflow situations.
--
-- - Macro: float HUGE_VALf
--     This macro is similar to the `HUGE_VAL' macro except that it is
--     used by functions returning `float' values.
--
--     This macro is a GNU extension.
--
-- - Macro: long double HUGE_VALl
--     This macro is similar to the `HUGE_VAL' macro except that it is
--     used by functions returning `long double' values.  The value is
--     only different from `HUGE_VAL' if the architecture really supports
--     `long double' values.
--
--     This macro is a GNU extension.
--
--   For more information about floating-point representations and limits,
--see *Note Floating Point Parameters::.  In particular, the macro
--`DBL_MAX' might be more appropriate than `HUGE_VAL' for many uses other
--than testing for an error in a mathematical function.
--
--
--File: libc.info,  Node: Trig Functions,  Next: Inverse Trig Functions,  Prev: 
Domain and Range Errors,  Up: Mathematics
--
--Trigonometric Functions
--=======================
--
--   These are the familiar `sin', `cos', and `tan' functions.  The
--arguments to all of these functions are in units of radians; recall
--that pi radians equals 180 degrees.
--
--   The math library doesn't define a symbolic constant for pi, but you
--can define your own if you need one:
--
--     #define PI 3.14159265358979323846264338327
--
--You can also compute the value of pi with the expression `acos (-1.0)'.
--
-- - Function: double sin (double X)
--     This function returns the sine of X, where X is given in radians.
--     The return value is in the range `-1' to `1'.
--
-- - Function: double cos (double X)
--     This function returns the cosine of X, where X is given in
--     radians.  The return value is in the range `-1' to `1'.
--
-- - Function: double tan (double X)
--     This function returns the tangent of X, where X is given in
--     radians.
--
--     The following `errno' error conditions are defined for this
--     function:
--
--    `ERANGE'
--          Mathematically, the tangent function has singularities at odd
--          multiples of pi/2.  If the argument X is too close to one of
--          these singularities, `tan' sets `errno' to `ERANGE' and
--          returns either positive or negative `HUGE_VAL'.
--
--
--File: libc.info,  Node: Inverse Trig Functions,  Next: Exponents and 
Logarithms,  Prev: Trig Functions,  Up: Mathematics
--
--Inverse Trigonometric Functions
--===============================
--
--   These are the usual arc sine, arc cosine and arc tangent functions,
--which are the inverses of the sine, cosine and tangent functions,
--respectively.
--
-- - Function: double asin (double X)
--     This function computes the arc sine of X--that is, the value whose
--     sine is X.  The value is in units of radians.  Mathematically,
--     there are infinitely many such values; the one actually returned
--     is the one between `-pi/2' and `pi/2' (inclusive).
--
--     `asin' fails, and sets `errno' to `EDOM', if X is out of range.
--     The arc sine function is defined mathematically only over the
--     domain `-1' to `1'.
--
-- - Function: double acos (double X)
--     This function computes the arc cosine of X--that is, the value
--     whose cosine is X.  The value is in units of radians.
--     Mathematically, there are infinitely many such values; the one
--     actually returned is the one between `0' and `pi' (inclusive).
--
--     `acos' fails, and sets `errno' to `EDOM', if X is out of range.
--     The arc cosine function is defined mathematically only over the
--     domain `-1' to `1'.
--
-- - Function: double atan (double X)
--     This function computes the arc tangent of X--that is, the value
--     whose tangent is X.  The value is in units of radians.
--     Mathematically, there are infinitely many such values; the one
--     actually returned is the one between `-pi/2' and `pi/2'
--     (inclusive).
--
-- - Function: double atan2 (double Y, double X)
--     This is the two argument arc tangent function.  It is similar to
--     computing the arc tangent of Y/X, except that the signs of both
--     arguments are used to determine the quadrant of the result, and X
--     is permitted to be zero.  The return value is given in radians and
--     is in the range `-pi' to `pi', inclusive.
--
--     If X and Y are coordinates of a point in the plane, `atan2'
--     returns the signed angle between the line from the origin to that
--     point and the x-axis.  Thus, `atan2' is useful for converting
--     Cartesian coordinates to polar coordinates.  (To compute the
--     radial coordinate, use `hypot'; see *Note Exponents and
--     Logarithms::.)
--
--     The function `atan2' sets `errno' to `EDOM' if both X and Y are
--     zero; the return value is not defined in this case.
--
--
--File: libc.info,  Node: Exponents and Logarithms,  Next: Hyperbolic 
Functions,  Prev: Inverse Trig Functions,  Up: Mathematics
--
--Exponentiation and Logarithms
--=============================
--
-- - Function: double exp (double X)
--     The `exp' function returns the value of e (the base of natural
--     logarithms) raised to power X.
--
--     The function fails, and sets `errno' to `ERANGE', if the magnitude
--     of the result is too large to be representable.
--
-- - Function: double log (double X)
--     This function returns the natural logarithm of X.  `exp (log (X))'
--     equals X, exactly in mathematics and approximately in C.
--
--     The following `errno' error conditions are defined for this
--     function:
--
--    `EDOM'
--          The argument X is negative.  The log function is defined
--          mathematically to return a real result only on positive
--          arguments.
--
--    `ERANGE'
--          The argument is zero.  The log of zero is not defined.
--
-- - Function: double log10 (double X)
--     This function returns the base-10 logarithm of X.  Except for the
--     different base, it is similar to the `log' function.  In fact,
--     `log10 (X)' equals `log (X) / log (10)'.
--
-- - Function: double pow (double BASE, double POWER)
--     This is a general exponentiation function, returning BASE raised
--     to POWER.
--
--     The following `errno' error conditions are defined for this
--     function:
--
--    `EDOM'
--          The argument BASE is negative and POWER is not an integral
--          value.  Mathematically, the result would be a complex number
--          in this case.
--
--    `ERANGE'
--          An underflow or overflow condition was detected in the result.
--
-- - Function: double sqrt (double X)
--     This function returns the nonnegative square root of X.
--
--     The `sqrt' function fails, and sets `errno' to `EDOM', if X is
--     negative.  Mathematically, the square root would be a complex
--     number.
--
-- - Function: double cbrt (double X)
--     This function returns the cube root of X.  This function cannot
--     fail; every representable real value has a representable real cube
--     root.
--
-- - Function: double hypot (double X, double Y)
--     The `hypot' function returns `sqrt (X*X + Y*Y)'.  (This is the
--     length of the hypotenuse of a right triangle with sides of length
--     X and Y, or the distance of the point (X, Y) from the origin.)
--     See also the function `cabs' in *Note Absolute Value::.
--
-- - Function: double expm1 (double X)
--     This function returns a value equivalent to `exp (X) - 1'.  It is
--     computed in a way that is accurate even if the value of X is near
--     zero--a case where `exp (X) - 1' would be inaccurate due to
--     subtraction of two numbers that are nearly equal.
--
-- - Function: double log1p (double X)
--     This function returns a value equivalent to `log (1 + X)'.  It is
--     computed in a way that is accurate even if the value of X is near
--     zero.
--
--
--File: libc.info,  Node: Hyperbolic Functions,  Next: Pseudo-Random Numbers,  
Prev: Exponents and Logarithms,  Up: Mathematics
--
--Hyperbolic Functions
--====================
--
--   The functions in this section are related to the exponential
--functions; see *Note Exponents and Logarithms::.
--
-- - Function: double sinh (double X)
--     The `sinh' function returns the hyperbolic sine of X, defined
--     mathematically as `exp (X) - exp (-X) / 2'.  The function fails,
--     and sets `errno' to `ERANGE', if the value of X is too large; that
--     is, if overflow occurs.
--
-- - Function: double cosh (double X)
--     The `cosh' function returns the hyperbolic cosine of X, defined
--     mathematically as `exp (X) + exp (-X) / 2'.  The function fails,
--     and sets `errno' to `ERANGE', if the value of X is too large; that
--     is, if overflow occurs.
--
-- - Function: double tanh (double X)
--     This function returns the hyperbolic tangent of X, whose
--     mathematical definition is `sinh (X) / cosh (X)'.
--
-- - Function: double asinh (double X)
--     This function returns the inverse hyperbolic sine of X--the value
--     whose hyperbolic sine is X.
--
-- - Function: double acosh (double X)
--     This function returns the inverse hyperbolic cosine of X--the
--     value whose hyperbolic cosine is X.  If X is less than `1',
--     `acosh' returns `HUGE_VAL'.
--
-- - Function: double atanh (double X)
--     This function returns the inverse hyperbolic tangent of X--the
--     value whose hyperbolic tangent is X.  If the absolute value of X
--     is greater than or equal to `1', `atanh' returns `HUGE_VAL'.
--
--
--File: libc.info,  Node: Pseudo-Random Numbers,  Prev: Hyperbolic Functions,  
Up: Mathematics
--
--Pseudo-Random Numbers
--=====================
--
--   This section describes the GNU facilities for generating a series of
--pseudo-random numbers.  The numbers generated are not truly random;
--typically, they form a sequence that repeats periodically, with a
--period so large that you can ignore it for ordinary purposes.  The
--random number generator works by remembering at all times a "seed"
--value which it uses to compute the next random number and also to
--compute a new seed.
--
--   Although the generated numbers look unpredictable within one run of a
--program, the sequence of numbers is *exactly the same* from one run to
--the next.  This is because the initial seed is always the same.  This
--is convenient when you are debugging a program, but it is unhelpful if
--you want the program to behave unpredictably.  If you want truly random
--numbers, not just pseudo-random, specify a seed based on the current
--time.
--
--   You can get repeatable sequences of numbers on a particular machine
--type by specifying the same initial seed value for the random number
--generator.  There is no standard meaning for a particular seed value;
--the same seed, used in different C libraries or on different CPU types,
--will give you different random numbers.
--
--   The GNU library supports the standard ISO C random number functions
--plus another set derived from BSD.  We recommend you use the standard
--ones, `rand' and `srand'.
--
--* Menu:
--
--* ISO Random::       `rand' and friends.
--* BSD Random::       `random' and friends.
--
--
--File: libc.info,  Node: ISO Random,  Next: BSD Random,  Up: Pseudo-Random 
Numbers
--
--ISO C Random Number Functions
-------------------------------
--
--   This section describes the random number functions that are part of
--the ISO C standard.
--
--   To use these facilities, you should include the header file
--`stdlib.h' in your program.
--
-- - Macro: int RAND_MAX
--     The value of this macro is an integer constant expression that
--     represents the maximum possible value returned by the `rand'
--     function.  In the GNU library, it is `037777777', which is the
--     largest signed integer representable in 32 bits.  In other
--     libraries, it may be as low as `32767'.
--
-- - Function: int rand ()
--     The `rand' function returns the next pseudo-random number in the
--     series.  The value is in the range from `0' to `RAND_MAX'.
--
-- - Function: void srand (unsigned int SEED)
--     This function establishes SEED as the seed for a new series of
--     pseudo-random numbers.  If you call `rand' before a seed has been
--     established with `srand', it uses the value `1' as a default seed.
--
--     To produce truly random numbers (not just pseudo-random), do `srand
--     (time (0))'.
--
--
--File: libc.info,  Node: BSD Random,  Prev: ISO Random,  Up: Pseudo-Random 
Numbers
--
--BSD Random Number Functions
-----------------------------
--
--   This section describes a set of random number generation functions
--that are derived from BSD.  There is no advantage to using these
--functions with the GNU C library; we support them for BSD compatibility
--only.
--
--   The prototypes for these functions are in `stdlib.h'.
--
-- - Function: long int random ()
--     This function returns the next pseudo-random number in the
--     sequence.  The range of values returned is from `0' to `RAND_MAX'.
--
-- - Function: void srandom (unsigned int SEED)
--     The `srandom' function sets the seed for the current random number
--     state based on the integer SEED.  If you supply a SEED value of
--     `1', this will cause `random' to reproduce the default set of
--     random numbers.
--
--     To produce truly random numbers (not just pseudo-random), do
--     `srandom (time (0))'.
--
-- - Function: void * initstate (unsigned int SEED, void *STATE, size_t
--          SIZE)
--     The `initstate' function is used to initialize the random number
--     generator state.  The argument STATE is an array of SIZE bytes,
--     used to hold the state information.  The size must be at least 8
--     bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The
--     bigger the STATE array, the better.
--
--     The return value is the previous value of the state information
--     array.  You can use this value later as an argument to `setstate'
--     to restore that state.
--
-- - Function: void * setstate (void *STATE)
--     The `setstate' function restores the random number state
--     information STATE.  The argument must have been the result of a
--     previous call to INITSTATE or SETSTATE.
--
--     The return value is the previous value of the state information
--     array.  You can use thise value later as an argument to `setstate'
--     to restore that state.
--
--
--File: libc.info,  Node: Arithmetic,  Next: Date and Time,  Prev: Mathematics, 
 Up: Top
--
--Low-Level Arithmetic Functions
--******************************
--
--   This chapter contains information about functions for doing basic
--arithmetic operations, such as splitting a float into its integer and
--fractional parts.  These functions are declared in the header file
--`math.h'.
--
--* Menu:
--
--* Not a Number::                Making NaNs and testing for NaNs.
--* Predicates on Floats::        Testing for infinity and for NaNs.
--* Absolute Value::              Absolute value functions.
--* Normalization Functions::     Hacks for radix-2 representations.
--* Rounding and Remainders::     Determining the integer and
--                               fractional parts of a float.
--* Integer Division::            Functions for performing integer
--                               division.
--* Parsing of Numbers::          Functions for "reading" numbers
--                               from strings.
--
--
--File: libc.info,  Node: Not a Number,  Next: Predicates on Floats,  Up: 
Arithmetic
--
--"Not a Number" Values
--=====================
--
--   The IEEE floating point format used by most modern computers supports
--values that are "not a number".  These values are called "NaNs".  "Not
--a number" values result from certain operations which have no
--meaningful numeric result, such as zero divided by zero or infinity
--divided by infinity.
--
--   One noteworthy property of NaNs is that they are not equal to
--themselves.  Thus, `x == x' can be 0 if the value of `x' is a NaN.  You
--can use this to test whether a value is a NaN or not: if it is not
--equal to itself, then it is a NaN.  But the recommended way to test for
--a NaN is with the `isnan' function (*note Predicates on Floats::.).
--
--   Almost any arithmetic operation in which one argument is a NaN
--returns a NaN.
--
-- - Macro: double NAN
--     An expression representing a value which is "not a number".  This
--     macro is a GNU extension, available only on machines that support
--     "not a number" values--that is to say, on all machines that
--     support IEEE floating point.
--
--     You can use `#ifdef NAN' to test whether the machine supports
--     NaNs.  (Of course, you must arrange for GNU extensions to be
--     visible, such as by defining `_GNU_SOURCE', and then you must
--     include `math.h'.)
--
--
--File: libc.info,  Node: Predicates on Floats,  Next: Absolute Value,  Prev: 
Not a Number,  Up: Arithmetic
--
--Predicates on Floats
--====================
--
--   This section describes some miscellaneous test functions on doubles.
--Prototypes for these functions appear in `math.h'.  These are BSD
--functions, and thus are available if you define `_BSD_SOURCE' or
--`_GNU_SOURCE'.
--
-- - Function: int isinf (double X)
--     This function returns `-1' if X represents negative infinity, `1'
--     if X represents positive infinity, and `0' otherwise.
--
-- - Function: int isnan (double X)
--     This function returns a nonzero value if X is a "not a number"
--     value, and zero otherwise.  (You can just as well use `X != X' to
--     get the same result).
--
-- - Function: int finite (double X)
--     This function returns a nonzero value if X is finite or a "not a
--     number" value, and zero otherwise.
--
-- - Function: double infnan (int ERROR)
--     This function is provided for compatibility with BSD.  The other
--     mathematical functions use `infnan' to decide what to return on
--     occasion of an error.  Its argument is an error code, `EDOM' or
--     `ERANGE'; `infnan' returns a suitable value to indicate this with.
--     `-ERANGE' is also acceptable as an argument, and corresponds to
--     `-HUGE_VAL' as a value.
--
--     In the BSD library, on certain machines, `infnan' raises a fatal
--     signal in all cases.  The GNU library does not do likewise,
--     because that does not fit the ISO C specification.
--
--   *Portability Note:* The functions listed in this section are BSD
--extensions.
--
--
--File: libc.info,  Node: Absolute Value,  Next: Normalization Functions,  
Prev: Predicates on Floats,  Up: Arithmetic
--
--Absolute Value
--==============
--
--   These functions are provided for obtaining the "absolute value" (or
--"magnitude") of a number.  The absolute value of a real number X is X
--is X is positive, -X if X is negative.  For a complex number Z, whose
--real part is X and whose imaginary part is Y, the absolute value is
--`sqrt (X*X + Y*Y)'.
--
--   Prototypes for `abs' and `labs' are in `stdlib.h'; `fabs' and `cabs'
--are declared in `math.h'.
--
-- - Function: int abs (int NUMBER)
--     This function returns the absolute value of NUMBER.
--
--     Most computers use a two's complement integer representation, in
--     which the absolute value of `INT_MIN' (the smallest possible `int')
--     cannot be represented; thus, `abs (INT_MIN)' is not defined.
--
-- - Function: long int labs (long int NUMBER)
--     This is similar to `abs', except that both the argument and result
--     are of type `long int' rather than `int'.
--
-- - Function: double fabs (double NUMBER)
--     This function returns the absolute value of the floating-point
--     number NUMBER.
--
-- - Function: double cabs (struct { double real, imag; } Z)
--     The `cabs' function returns the absolute value of the complex
--     number Z, whose real part is `Z.real' and whose imaginary part is
--     `Z.imag'.  (See also the function `hypot' in *Note Exponents and
--     Logarithms::.)  The value is:
--
--          sqrt (Z.real*Z.real + Z.imag*Z.imag)
--
--
--File: libc.info,  Node: Normalization Functions,  Next: Rounding and 
Remainders,  Prev: Absolute Value,  Up: Arithmetic
--
--Normalization Functions
--=======================
--
--   The functions described in this section are primarily provided as a
--way to efficiently perform certain low-level manipulations on floating
--point numbers that are represented internally using a binary radix; see
--*Note Floating Point Concepts::.  These functions are required to have
--equivalent behavior even if the representation does not use a radix of
--2, but of course they are unlikely to be particularly efficient in
--those cases.
--
--   All these functions are declared in `math.h'.
--
-- - Function: double frexp (double VALUE, int *EXPONENT)
--     The `frexp' function is used to split the number VALUE into a
--     normalized fraction and an exponent.
--
--     If the argument VALUE is not zero, the return value is VALUE times
--     a power of two, and is always in the range 1/2 (inclusive) to 1
--     (exclusive).  The corresponding exponent is stored in `*EXPONENT';
--     the return value multiplied by 2 raised to this exponent equals
--     the original number VALUE.
--
--     For example, `frexp (12.8, &exponent)' returns `0.8' and stores
--     `4' in `exponent'.
--
--     If VALUE is zero, then the return value is zero and zero is stored
--     in `*EXPONENT'.
--
-- - Function: double ldexp (double VALUE, int EXPONENT)
--     This function returns the result of multiplying the floating-point
--     number VALUE by 2 raised to the power EXPONENT.  (It can be used
--     to reassemble floating-point numbers that were taken apart by
--     `frexp'.)
--
--     For example, `ldexp (0.8, 4)' returns `12.8'.
--
--   The following functions which come from BSD provide facilities
--equivalent to those of `ldexp' and `frexp':
--
-- - Function: double scalb (double VALUE, int EXPONENT)
--     The `scalb' function is the BSD name for `ldexp'.
--
-- - Function: double logb (double X)
--     This BSD function returns the integer part of the base-2 logarithm
--     of X, an integer value represented in type `double'.  This is the
--     highest integer power of `2' contained in X.  The sign of X is
--     ignored.  For example, `logb (3.5)' is `1.0' and `logb (4.0)' is
--     `2.0'.
--
--     When `2' raised to this power is divided into X, it gives a
--     quotient between `1' (inclusive) and `2' (exclusive).
--
--     If X is zero, the value is minus infinity (if the machine supports
--     such a value), or else a very small number.  If X is infinity, the
--     value is infinity.
--
--     The value returned by `logb' is one less than the value that
--     `frexp' would store into `*EXPONENT'.
--
-- - Function: double copysign (double VALUE, double SIGN)
--     The `copysign' function returns a value whose absolute value is the
--     same as that of VALUE, and whose sign matches that of SIGN.  This
--     is a BSD function.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-16 
glibc-2.0.1/manual/libc.info-16
---- ../glibc-2.0.1/manual/libc.info-16 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-16    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1257 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Rounding and Remainders,  Next: Integer Division,  
Prev: Normalization Functions,  Up: Arithmetic
--
--Rounding and Remainder Functions
--================================
--
--   The functions listed here perform operations such as rounding,
--truncation, and remainder in division of floating point numbers.  Some
--of these functions convert floating point numbers to integer values.
--They are all declared in `math.h'.
--
--   You can also convert floating-point numbers to integers simply by
--casting them to `int'.  This discards the fractional part, effectively
--rounding towards zero.  However, this only works if the result can
--actually be represented as an `int'--for very large numbers, this is
--impossible.  The functions listed here return the result as a `double'
--instead to get around this problem.
--
-- - Function: double ceil (double X)
--     The `ceil' function rounds X upwards to the nearest integer,
--     returning that value as a `double'.  Thus, `ceil (1.5)' is `2.0'.
--
-- - Function: double floor (double X)
--     The `ceil' function rounds X downwards to the nearest integer,
--     returning that value as a `double'.  Thus, `floor (1.5)' is `1.0'
--     and `floor (-1.5)' is `-2.0'.
--
-- - Function: double rint (double X)
--     This function rounds X to an integer value according to the
--     current rounding mode.  *Note Floating Point Parameters::, for
--     information about the various rounding modes.  The default
--     rounding mode is to round to the nearest integer; some machines
--     support other modes, but round-to-nearest is always used unless
--     you explicit select another.
--
-- - Function: double modf (double VALUE, double *INTEGER-PART)
--     This function breaks the argument VALUE into an integer part and a
--     fractional part (between `-1' and `1', exclusive).  Their sum
--     equals VALUE.  Each of the parts has the same sign as VALUE, so
--     the rounding of the integer part is towards zero.
--
--     `modf' stores the integer part in `*INTEGER-PART', and returns the
--     fractional part.  For example, `modf (2.5, &intpart)' returns
--     `0.5' and stores `2.0' into `intpart'.
--
-- - Function: double fmod (double NUMERATOR, double DENOMINATOR)
--     This function computes the remainder from the division of
--     NUMERATOR by DENOMINATOR.  Specifically, the return value is
--     `NUMERATOR - N * DENOMINATOR', where N is the quotient of
--     NUMERATOR divided by DENOMINATOR, rounded towards zero to an
--     integer.  Thus, `fmod (6.5, 2.3)' returns `1.9', which is `6.5'
--     minus `4.6'.
--
--     The result has the same sign as the NUMERATOR and has magnitude
--     less than the magnitude of the DENOMINATOR.
--
--     If DENOMINATOR is zero, `fmod' fails and sets `errno' to `EDOM'.
--
-- - Function: double drem (double NUMERATOR, double DENOMINATOR)
--     The function `drem' is like `fmod' except that it rounds the
--     internal quotient N to the nearest integer instead of towards zero
--     to an integer.  For example, `drem (6.5, 2.3)' returns `-0.4',
--     which is `6.5' minus `6.9'.
--
--     The absolute value of the result is less than or equal to half the
--     absolute value of the DENOMINATOR.  The difference between `fmod
--     (NUMERATOR, DENOMINATOR)' and `drem (NUMERATOR, DENOMINATOR)' is
--     always either DENOMINATOR, minus DENOMINATOR, or zero.
--
--     If DENOMINATOR is zero, `drem' fails and sets `errno' to `EDOM'.
--
--
--File: libc.info,  Node: Integer Division,  Next: Parsing of Numbers,  Prev: 
Rounding and Remainders,  Up: Arithmetic
--
--Integer Division
--================
--
--   This section describes functions for performing integer division.
--These functions are redundant in the GNU C library, since in GNU C the
--`/' operator always rounds towards zero.  But in other C
--implementations, `/' may round differently with negative arguments.
--`div' and `ldiv' are useful because they specify how to round the
--quotient: towards zero.  The remainder has the same sign as the
--numerator.
--
--   These functions are specified to return a result R such that the
--value `R.quot*DENOMINATOR + R.rem' equals NUMERATOR.
--
--   To use these facilities, you should include the header file
--`stdlib.h' in your program.
--
-- - Data Type: div_t
--     This is a structure type used to hold the result returned by the
--     `div' function.  It has the following members:
--
--    `int quot'
--          The quotient from the division.
--
--    `int rem'
--          The remainder from the division.
--
-- - Function: div_t div (int NUMERATOR, int DENOMINATOR)
--     This function `div' computes the quotient and remainder from the
--     division of NUMERATOR by DENOMINATOR, returning the result in a
--     structure of type `div_t'.
--
--     If the result cannot be represented (as in a division by zero), the
--     behavior is undefined.
--
--     Here is an example, albeit not a very useful one.
--
--          div_t result;
--          result = div (20, -6);
--
--     Now `result.quot' is `-3' and `result.rem' is `2'.
--
-- - Data Type: ldiv_t
--     This is a structure type used to hold the result returned by the
--     `ldiv' function.  It has the following members:
--
--    `long int quot'
--          The quotient from the division.
--
--    `long int rem'
--          The remainder from the division.
--
--     (This is identical to `div_t' except that the components are of
--     type `long int' rather than `int'.)
--
-- - Function: ldiv_t ldiv (long int NUMERATOR, long int DENOMINATOR)
--     The `ldiv' function is similar to `div', except that the arguments
--     are of type `long int' and the result is returned as a structure
--     of type `ldiv'.
--
--
--File: libc.info,  Node: Parsing of Numbers,  Prev: Integer Division,  Up: 
Arithmetic
--
--Parsing of Numbers
--==================
--
--   This section describes functions for "reading" integer and
--floating-point numbers from a string.  It may be more convenient in some
--cases to use `sscanf' or one of the related functions; see *Note
--Formatted Input::.  But often you can make a program more robust by
--finding the tokens in the string by hand, then converting the numbers
--one by one.
--
--* Menu:
--
--* Parsing of Integers::         Functions for conversion of integer values.
--* Parsing of Floats::           Functions for conversion of floating-point
--                               values.
--
--
--File: libc.info,  Node: Parsing of Integers,  Next: Parsing of Floats,  Up: 
Parsing of Numbers
--
--Parsing of Integers
---------------------
--
--   These functions are declared in `stdlib.h'.
--
-- - Function: long int strtol (const char *STRING, char **TAILPTR, int
--          BASE)
--     The `strtol' ("string-to-long") function converts the initial part
--     of STRING to a signed integer, which is returned as a value of
--     type `long int'.
--
--     This function attempts to decompose STRING as follows:
--
--        * A (possibly empty) sequence of whitespace characters.  Which
--          characters are whitespace is determined by the `isspace'
--          function (*note Classification of Characters::.).  These are
--          discarded.
--
--        * An optional plus or minus sign (`+' or `-').
--
--        * A nonempty sequence of digits in the radix specified by BASE.
--
--          If BASE is zero, decimal radix is assumed unless the series of
--          digits begins with `0' (specifying octal radix), or `0x' or
--          `0X' (specifying hexadecimal radix); in other words, the same
--          syntax used for integer constants in C.
--
--          Otherwise BASE must have a value between `2' and `35'.  If
--          BASE is `16', the digits may optionally be preceded by `0x'
--          or `0X'.  If base has no legal value the value returned is
--          `0l' and the global variable `errno' is set to `EINVAL'.
--
--        * Any remaining characters in the string.  If TAILPTR is not a
--          null pointer, `strtol' stores a pointer to this tail in
--          `*TAILPTR'.
--
--     If the string is empty, contains only whitespace, or does not
--     contain an initial substring that has the expected syntax for an
--     integer in the specified BASE, no conversion is performed.  In
--     this case, `strtol' returns a value of zero and the value stored in
--     `*TAILPTR' is the value of STRING.
--
--     In a locale other than the standard `"C"' locale, this function
--     may recognize additional implementation-dependent syntax.
--
--     If the string has valid syntax for an integer but the value is not
--     representable because of overflow, `strtol' returns either
--     `LONG_MAX' or `LONG_MIN' (*note Range of Type::.), as appropriate
--     for the sign of the value.  It also sets `errno' to `ERANGE' to
--     indicate there was overflow.
--
--     Because the value `0l' is a correct result for `strtol' the user
--     who is interested in handling errors should set the global variable
--     `errno' to `0' before calling this function, so that the program
--     can later test whether an error occurred.
--
--     There is an example at the end of this section.
--
-- - Function: unsigned long int strtoul (const char *STRING, char
--          **TAILPTR, int BASE)
--     The `strtoul' ("string-to-unsigned-long") function is like
--     `strtol' except it deals with unsigned numbers, and returns its
--     value with type `unsigned long int'.  No `+' or `-' sign may
--     appear before the number, but the syntax is otherwise the same as
--     described above for `strtol'.  The value returned in case of
--     overflow is `ULONG_MAX' (*note Range of Type::.).
--
--     Like `strtol' this function sets `errno' and returns the value
--     `0ul' in case the value for BASE is not in the legal range.  For
--     `strtoul' this can happen in another situation.  In case the
--     number to be converted is negative `strtoul' also sets `errno' to
--     `EINVAL' and returns `0ul'.
--
-- - Function: long long int strtoq (const char *STRING, char **TAILPTR,
--          int BASE)
--     The `strtoq' ("string-to-quad-word") function is like `strtol'
--     except that is deals with extra long numbers and it returns its
--     value with type `long long int'.
--
--     If the string has valid syntax for an integer but the value is not
--     representable because of overflow, `strtoq' returns either
--     `LONG_LONG_MAX' or `LONG_LONG_MIN' (*note Range of Type::.), as
--     appropriate for the sign of the value.  It also sets `errno' to
--     `ERANGE' to indicate there was overflow.
--
-- - Function: long long int strtoll (const char *STRING, char **TAILPTR,
--          int BASE)
--     `strtoll' is only an commonly used other name for the `strtoq'
--     function.  Everything said for `strtoq' applies to `strtoll' as
--     well.
--
-- - Function: unsigned long long int strtouq (const char *STRING, char
--          **TAILPTR, int BASE)
--     The `strtouq' ("string-to-unsigned-quad-word") function is like
--     `strtoul' except that is deals with extra long numbers and it
--     returns its value with type `unsigned long long int'.  The value
--     returned in case of overflow is `ULONG_LONG_MAX' (*note Range of
--     Type::.).
--
-- - Function: unsigned long long int strtoull (const char *STRING, char
--          **TAILPTR, int BASE)
--     `strtoull' is only an commonly used other name for the `strtouq'
--     function.  Everything said for `strtouq' applies to `strtoull' as
--     well.
--
-- - Function: long int atol (const char *STRING)
--     This function is similar to the `strtol' function with a BASE
--     argument of `10', except that it need not detect overflow errors.
--     The `atol' function is provided mostly for compatibility with
--     existing code; using `strtol' is more robust.
--
-- - Function: int atoi (const char *STRING)
--     This function is like `atol', except that it returns an `int'
--     value rather than `long int'.  The `atoi' function is also
--     considered obsolete; use `strtol' instead.
--
--   The POSIX locales contain some information about how to format
--numbers (*note General Numeric::.).  This mainly deals with
--representing numbers for better readability for humans.  The functions
--present so far in this section cannot handle numbers in this form.
--
--   If this functionality is needed in a program one can use the
--functions from the `scanf' family which know about the flag `'' for
--parsing numeric input (*note Numeric Input Conversions::.).  Sometimes
--it is more desirable to have finer control.
--
--   In these situation one could use the function `__strtoXXX_internal'.
--XXX here stands for any of the above forms.  All numeric conversion
--functions (including the functions to process floating-point numbers)
--have such a counterpart.  The difference to the normal form is the
--extra argument at the end of the parameter list.  If this value has an
--non-zero value the handling of number grouping is enabled.  The
--advantage of using these functions is that the TAILPTR parameters allow
--to determine which part of the input is processed.  The `scanf'
--functions don't provide this information.  The drawback of using these
--functions is that they are not portable.  They only exist in the GNU C
--library.
--
--   Here is a function which parses a string as a sequence of integers
--and returns the sum of them:
--
--     int
--     sum_ints_from_string (char *string)
--     {
--       int sum = 0;
--     
--       while (1) {
--         char *tail;
--         int next;
--     
--         /* Skip whitespace by hand, to detect the end.  */
--         while (isspace (*string)) string++;
--         if (*string == 0)
--           break;
--     
--         /* There is more nonwhitespace,  */
--         /* so it ought to be another number.  */
--         errno = 0;
--         /* Parse it.  */
--         next = strtol (string, &tail, 0);
--         /* Add it in, if not overflow.  */
--         if (errno)
--           printf ("Overflow\n");
--         else
--           sum += next;
--         /* Advance past it.  */
--         string = tail;
--       }
--     
--       return sum;
--     }
--
--
--File: libc.info,  Node: Parsing of Floats,  Prev: Parsing of Integers,  Up: 
Parsing of Numbers
--
--Parsing of Floats
-------------------
--
--   These functions are declared in `stdlib.h'.
--
-- - Function: double strtod (const char *STRING, char **TAILPTR)
--     The `strtod' ("string-to-double") function converts the initial
--     part of STRING to a floating-point number, which is returned as a
--     value of type `double'.
--
--     This function attempts to decompose STRING as follows:
--
--        * A (possibly empty) sequence of whitespace characters.  Which
--          characters are whitespace is determined by the `isspace'
--          function (*note Classification of Characters::.).  These are
--          discarded.
--
--        * An optional plus or minus sign (`+' or `-').
--
--        * A nonempty sequence of digits optionally containing a
--          decimal-point character--normally `.', but it depends on the
--          locale (*note Numeric Formatting::.).
--
--        * An optional exponent part, consisting of a character `e' or
--          `E', an optional sign, and a sequence of digits.
--
--        * Any remaining characters in the string.  If TAILPTR is not a
--          null pointer, a pointer to this tail of the string is stored
--          in `*TAILPTR'.
--
--     If the string is empty, contains only whitespace, or does not
--     contain an initial substring that has the expected syntax for a
--     floating-point number, no conversion is performed.  In this case,
--     `strtod' returns a value of zero and the value returned in
--     `*TAILPTR' is the value of STRING.
--
--     In a locale other than the standard `"C"' or `"POSIX"' locales,
--     this function may recognize additional locale-dependent syntax.
--
--     If the string has valid syntax for a floating-point number but the
--     value is not representable because of overflow, `strtod' returns
--     either positive or negative `HUGE_VAL' (*note Mathematics::.),
--     depending on the sign of the value.  Similarly, if the value is
--     not representable because of underflow, `strtod' returns zero.  It
--     also sets `errno' to `ERANGE' if there was overflow or underflow.
--
--     Since the value zero which is returned in the error case is also a
--     valid result the user should set the global variable `errno' to
--     zero before calling this function.  So one can test for failures
--     after the call since all failures set `errno' to a non-zero value.
--
-- - Function: float strtof (const char *STRING, char **TAILPTR)
--     This function is similar to the `strtod' function but it returns a
--     `float' value instead of a `double' value.  If the precision of a
--     `float' value is sufficient this function should be used since it
--     is much faster than `strtod' on some architectures.  The reasons
--     are obvious: IEEE 754 defines `float' to have a mantissa of 23
--     bits while `double' has 53 bits and every additional bit of
--     precision can require additional computation.
--
--     If the string has valid syntax for a floating-point number but the
--     value is not representable because of overflow, `strtof' returns
--     either positive or negative `HUGE_VALf' (*note Mathematics::.),
--     depending on the sign of the value.
--
--     This function is a GNU extension.
--
-- - Function: long double strtold (const char *STRING, char **TAILPTR)
--     This function is similar to the `strtod' function but it returns a
--     `long double' value instead of a `double' value.  It should be
--     used when high precision is needed.  On systems which define a
--     `long double' type (i.e., on which it is not the same as `double')
--     running this function might take significantly more time since
--     more bits of precision are required.
--
--     If the string has valid syntax for a floating-point number but the
--     value is not representable because of overflow, `strtold' returns
--     either positive or negative `HUGE_VALl' (*note Mathematics::.),
--     depending on the sign of the value.
--
--     This function is a GNU extension.
--
--   As for the integer parsing functions there are additional functions
--which will handle numbers represented using the grouping scheme of the
--current locale (*note Parsing of Integers::.).
--
-- - Function: double atof (const char *STRING)
--     This function is similar to the `strtod' function, except that it
--     need not detect overflow and underflow errors.  The `atof' function
--     is provided mostly for compatibility with existing code; using
--     `strtod' is more robust.
--
--
--File: libc.info,  Node: Searching and Sorting,  Next: Pattern Matching,  
Prev: Locales,  Up: Top
--
--Searching and Sorting
--*********************
--
--   This chapter describes functions for searching and sorting arrays of
--arbitrary objects.  You pass the appropriate comparison function to be
--applied as an argument, along with the size of the objects in the array
--and the total number of elements.
--
--* Menu:
--
--* Comparison Functions::        Defining how to compare two objects.
--                               Since the sort and search facilities
--                                 are general, you have to specify the
--                                 ordering.
--* Array Search Function::       The `bsearch' function.
--* Array Sort Function::         The `qsort' function.
--* Search/Sort Example::         An example program.
--
--
--File: libc.info,  Node: Comparison Functions,  Next: Array Search Function,  
Up: Searching and Sorting
--
--Defining the Comparison Function
--================================
--
--   In order to use the sorted array library functions, you have to
--describe how to compare the elements of the array.
--
--   To do this, you supply a comparison function to compare two elements
--of the array.  The library will call this function, passing as arguments
--pointers to two array elements to be compared.  Your comparison function
--should return a value the way `strcmp' (*note String/Array
--Comparison::.) does: negative if the first argument is "less" than the
--second, zero if they are "equal", and positive if the first argument is
--"greater".
--
--   Here is an example of a comparison function which works with an
--array of numbers of type `double':
--
--     int
--     compare_doubles (const double *a, const double *b)
--     {
--       return (int) (*a - *b);
--     }
--
--   The header file `stdlib.h' defines a name for the data type of
--comparison functions.  This type is a GNU extension.
--
--     int comparison_fn_t (const void *, const void *);
--
--
--File: libc.info,  Node: Array Search Function,  Next: Array Sort Function,  
Prev: Comparison Functions,  Up: Searching and Sorting
--
--Array Search Function
--=====================
--
--   To search a sorted array for an element matching the key, use the
--`bsearch' function.  The prototype for this function is in the header
--file `stdlib.h'.
--
-- - Function: void * bsearch (const void *KEY, const void *ARRAY, size_t
--          COUNT, size_t SIZE, comparison_fn_t COMPARE)
--     The `bsearch' function searches the sorted array ARRAY for an
--     object that is equivalent to KEY.  The array contains COUNT
--     elements, each of which is of size SIZE bytes.
--
--     The COMPARE function is used to perform the comparison.  This
--     function is called with two pointer arguments and should return an
--     integer less than, equal to, or greater than zero corresponding to
--     whether its first argument is considered less than, equal to, or
--     greater than its second argument.  The elements of the ARRAY must
--     already be sorted in ascending order according to this comparison
--     function.
--
--     The return value is a pointer to the matching array element, or a
--     null pointer if no match is found.  If the array contains more
--     than one element that matches, the one that is returned is
--     unspecified.
--
--     This function derives its name from the fact that it is implemented
--     using the binary search algorithm.
--
--
--File: libc.info,  Node: Array Sort Function,  Next: Search/Sort Example,  
Prev: Array Search Function,  Up: Searching and Sorting
--
--Array Sort Function
--===================
--
--   To sort an array using an arbitrary comparison function, use the
--`qsort' function.  The prototype for this function is in `stdlib.h'.
--
-- - Function: void qsort (void *ARRAY, size_t COUNT, size_t SIZE,
--          comparison_fn_t COMPARE)
--     The QSORT function sorts the array ARRAY.  The array contains
--     COUNT elements, each of which is of size SIZE.
--
--     The COMPARE function is used to perform the comparison on the
--     array elements.  This function is called with two pointer
--     arguments and should return an integer less than, equal to, or
--     greater than zero corresponding to whether its first argument is
--     considered less than, equal to, or greater than its second
--     argument.
--
--     *Warning:* If two objects compare as equal, their order after
--     sorting is unpredictable.  That is to say, the sorting is not
--     stable.  This can make a difference when the comparison considers
--     only part of the elements.  Two elements with the same sort key
--     may differ in other respects.
--
--     If you want the effect of a stable sort, you can get this result by
--     writing the comparison function so that, lacking other reason
--     distinguish between two elements, it compares them by their
--     addresses.  Note that doing this may make the sorting algorithm
--     less efficient, so do it only if necessary.
--
--     Here is a simple example of sorting an array of doubles in
--     numerical order, using the comparison function defined above
--     (*note Comparison Functions::.):
--
--          {
--            double *array;
--            int size;
--            ...
--            qsort (array, size, sizeof (double), compare_doubles);
--          }
--
--     The `qsort' function derives its name from the fact that it was
--     originally implemented using the "quick sort" algorithm.
--
--
--File: libc.info,  Node: Search/Sort Example,  Prev: Array Sort Function,  Up: 
Searching and Sorting
--
--Searching and Sorting Example
--=============================
--
--   Here is an example showing the use of `qsort' and `bsearch' with an
--array of structures.  The objects in the array are sorted by comparing
--their `name' fields with the `strcmp' function.  Then, we can look up
--individual objects based on their names.
--
--     #include <stdlib.h>
--     #include <stdio.h>
--     #include <string.h>
--     
--     /* Define an array of critters to sort. */
--     
--     struct critter
--       {
--         const char *name;
--         const char *species;
--       };
--     
--     struct critter muppets[] =
--       {
--         {"Kermit", "frog"},
--         {"Piggy", "pig"},
--         {"Gonzo", "whatever"},
--         {"Fozzie", "bear"},
--         {"Sam", "eagle"},
--         {"Robin", "frog"},
--         {"Animal", "animal"},
--         {"Camilla", "chicken"},
--         {"Sweetums", "monster"},
--         {"Dr. Strangepork", "pig"},
--         {"Link Hogthrob", "pig"},
--         {"Zoot", "human"},
--         {"Dr. Bunsen Honeydew", "human"},
--         {"Beaker", "human"},
--         {"Swedish Chef", "human"}
--       };
--     
--     int count = sizeof (muppets) / sizeof (struct critter);
--     
--     
--     
--     /* This is the comparison function used for sorting and searching. */
--     
--     int
--     critter_cmp (const struct critter *c1, const struct critter *c2)
--     {
--       return strcmp (c1->name, c2->name);
--     }
--     
--     
--     /* Print information about a critter. */
--     
--     void
--     print_critter (const struct critter *c)
--     {
--       printf ("%s, the %s\n", c->name, c->species);
--     }
--     /* Do the lookup into the sorted array. */
--     
--     void
--     find_critter (const char *name)
--     {
--       struct critter target, *result;
--       target.name = name;
--       result = bsearch (&target, muppets, count, sizeof (struct critter),
--                         critter_cmp);
--       if (result)
--         print_critter (result);
--       else
--         printf ("Couldn't find %s.\n", name);
--     }
--     
--     /* Main program. */
--     
--     int
--     main (void)
--     {
--       int i;
--     
--       for (i = 0; i < count; i++)
--         print_critter (&muppets[i]);
--       printf ("\n");
--     
--       qsort (muppets, count, sizeof (struct critter), critter_cmp);
--     
--       for (i = 0; i < count; i++)
--         print_critter (&muppets[i]);
--       printf ("\n");
--     
--       find_critter ("Kermit");
--       find_critter ("Gonzo");
--       find_critter ("Janice");
--     
--       return 0;
--     }
--
--   The output from this program looks like:
--
--     Kermit, the frog
--     Piggy, the pig
--     Gonzo, the whatever
--     Fozzie, the bear
--     Sam, the eagle
--     Robin, the frog
--     Animal, the animal
--     Camilla, the chicken
--     Sweetums, the monster
--     Dr. Strangepork, the pig
--     Link Hogthrob, the pig
--     Zoot, the human
--     Dr. Bunsen Honeydew, the human
--     Beaker, the human
--     Swedish Chef, the human
--     
--     Animal, the animal
--     Beaker, the human
--     Camilla, the chicken
--     Dr. Bunsen Honeydew, the human
--     Dr. Strangepork, the pig
--     Fozzie, the bear
--     Gonzo, the whatever
--     Kermit, the frog
--     Link Hogthrob, the pig
--     Piggy, the pig
--     Robin, the frog
--     Sam, the eagle
--     Swedish Chef, the human
--     Sweetums, the monster
--     Zoot, the human
--     
--     Kermit, the frog
--     Gonzo, the whatever
--     Couldn't find Janice.
--
--
--File: libc.info,  Node: Pattern Matching,  Next: I/O Overview,  Prev: 
Searching and Sorting,  Up: Top
--
--Pattern Matching
--****************
--
--   The GNU C Library provides pattern matching facilities for two kinds
--of patterns: regular expressions and file-name wildcards.  The library
--also provides a facility for expanding variable and command references
--and parsing text into words in the way the shell does.
--
--* Menu:
--
--* Wildcard Matching::    Matching a wildcard pattern against a single string.
--* Globbing::             Finding the files that match a wildcard pattern.
--* Regular Expressions::  Matching regular expressions against strings.
--* Word Expansion::       Expanding shell variables, nested commands,
--                          arithmetic, and wildcards.
--                          This is what the shell does with shell commands.
--
--
--File: libc.info,  Node: Wildcard Matching,  Next: Globbing,  Up: Pattern 
Matching
--
--Wildcard Matching
--=================
--
--   This section describes how to match a wildcard pattern against a
--particular string.  The result is a yes or no answer: does the string
--fit the pattern or not.  The symbols described here are all declared in
--`fnmatch.h'.
--
-- - Function: int fnmatch (const char *PATTERN, const char *STRING, int
--          FLAGS)
--     This function tests whether the string STRING matches the pattern
--     PATTERN.  It returns `0' if they do match; otherwise, it returns
--     the nonzero value `FNM_NOMATCH'.  The arguments PATTERN and STRING
--     are both strings.
--
--     The argument FLAGS is a combination of flag bits that alter the
--     details of matching.  See below for a list of the defined flags.
--
--     In the GNU C Library, `fnmatch' cannot experience an "error"--it
--     always returns an answer for whether the match succeeds.  However,
--     other implementations of `fnmatch' might sometimes report "errors".
--     They would do so by returning nonzero values that are not equal to
--     `FNM_NOMATCH'.
--
--   These are the available flags for the FLAGS argument:
--
--`FNM_FILE_NAME'
--     Treat the `/' character specially, for matching file names.  If
--     this flag is set, wildcard constructs in PATTERN cannot match `/'
--     in STRING.  Thus, the only way to match `/' is with an explicit
--     `/' in PATTERN.
--
--`FNM_PATHNAME'
--     This is an alias for `FNM_FILE_NAME'; it comes from POSIX.2.  We
--     don't recommend this name because we don't use the term "pathname"
--     for file names.
--
--`FNM_PERIOD'
--     Treat the `.' character specially if it appears at the beginning of
--     STRING.  If this flag is set, wildcard constructs in PATTERN
--     cannot match `.' as the first character of STRING.
--
--     If you set both `FNM_PERIOD' and `FNM_FILE_NAME', then the special
--     treatment applies to `.' following `/' as well as to `.' at the
--     beginning of STRING.  (The shell uses the `FNM_PERIOD' and
--     `FNM_FILE_NAME' falgs together for matching file names.)
--
--`FNM_NOESCAPE'
--     Don't treat the `\' character specially in patterns.  Normally,
--     `\' quotes the following character, turning off its special meaning
--     (if any) so that it matches only itself.  When quoting is enabled,
--     the pattern `\?' matches only the string `?', because the question
--     mark in the pattern acts like an ordinary character.
--
--     If you use `FNM_NOESCAPE', then `\' is an ordinary character.
--
--`FNM_LEADING_DIR'
--     Ignore a trailing sequence of characters starting with a `/' in
--     STRING; that is to say, test whether STRING starts with a
--     directory name that PATTERN matches.
--
--     If this flag is set, either `foo*' or `foobar' as a pattern would
--     match the string `foobar/frobozz'.
--
--`FNM_CASEFOLD'
--     Ignore case in comparing STRING to PATTERN.
--
--
--File: libc.info,  Node: Globbing,  Next: Regular Expressions,  Prev: Wildcard 
Matching,  Up: Pattern Matching
--
--Globbing
--========
--
--   The archetypal use of wildcards is for matching against the files in
--a directory, and making a list of all the matches.  This is called
--"globbing".
--
--   You could do this using `fnmatch', by reading the directory entries
--one by one and testing each one with `fnmatch'.  But that would be slow
--(and complex, since you would have to handle subdirectories by hand).
--
--   The library provides a function `glob' to make this particular use
--of wildcards convenient.  `glob' and the other symbols in this section
--are declared in `glob.h'.
--
--* Menu:
--
--* Calling Glob::        Basic use of `glob'.
--* Flags for Globbing::  Flags that enable various options in `glob'.
--
--
--File: libc.info,  Node: Calling Glob,  Next: Flags for Globbing,  Up: Globbing
--
--Calling `glob'
----------------
--
--   The result of globbing is a vector of file names (strings).  To
--return this vector, `glob' uses a special data type, `glob_t', which is
--a structure.  You pass `glob' the address of the structure, and it
--fills in the structure's fields to tell you about the results.
--
-- - Data Type: glob_t
--     This data type holds a pointer to a word vector.  More precisely,
--     it records both the address of the word vector and its size.
--
--    `gl_pathc'
--          The number of elements in the vector.
--
--    `gl_pathv'
--          The address of the vector.  This field has type `char **'.
--
--    `gl_offs'
--          The offset of the first real element of the vector, from its
--          nominal address in the `gl_pathv' field.  Unlike the other
--          fields, this is always an input to `glob', rather than an
--          output from it.
--
--          If you use a nonzero offset, then that many elements at the
--          beginning of the vector are left empty.  (The `glob' function
--          fills them with null pointers.)
--
--          The `gl_offs' field is meaningful only if you use the
--          `GLOB_DOOFFS' flag.  Otherwise, the offset is always zero
--          regardless of what is in this field, and the first real
--          element comes at the beginning of the vector.
--
-- - Function: int glob (const char *PATTERN, int FLAGS, int (*ERRFUNC)
--          (const char *FILENAME, int ERROR-CODE), glob_t *VECTOR-PTR)
--     The function `glob' does globbing using the pattern PATTERN in the
--     current directory.  It puts the result in a newly allocated
--     vector, and stores the size and address of this vector into
--     `*VECTOR-PTR'.  The argument FLAGS is a combination of bit flags;
--     see *Note Flags for Globbing::, for details of the flags.
--
--     The result of globbing is a sequence of file names.  The function
--     `glob' allocates a string for each resulting word, then allocates
--     a vector of type `char **' to store the addresses of these
--     strings.  The last element of the vector is a null pointer.  This
--     vector is called the "word vector".
--
--     To return this vector, `glob' stores both its address and its
--     length (number of elements, not counting the terminating null
--     pointer) into `*VECTOR-PTR'.
--
--     Normally, `glob' sorts the file names alphabetically before
--     returning them.  You can turn this off with the flag `GLOB_NOSORT'
--     if you want to get the information as fast as possible.  Usually
--     it's a good idea to let `glob' sort them--if you process the files
--     in alphabetical order, the users will have a feel for the rate of
--     progress that your application is making.
--
--     If `glob' succeeds, it returns 0.  Otherwise, it returns one of
--     these error codes:
--
--    `GLOB_ABORTED'
--          There was an error opening a directory, and you used the flag
--          `GLOB_ERR' or your specified ERRFUNC returned a nonzero value.
--          *Note Flags for Globbing::, for an explanation of the
--          `GLOB_ERR' flag and ERRFUNC.
--
--    `GLOB_NOMATCH'
--          The pattern didn't match any existing files.  If you use the
--          `GLOB_NOCHECK' flag, then you never get this error code,
--          because that flag tells `glob' to *pretend* that the pattern
--          matched at least one file.
--
--    `GLOB_NOSPACE'
--          It was impossible to allocate memory to hold the result.
--
--     In the event of an error, `glob' stores information in
--     `*VECTOR-PTR' about all the matches it has found so far.
--
--
--File: libc.info,  Node: Flags for Globbing,  Prev: Calling Glob,  Up: Globbing
--
--Flags for Globbing
--------------------
--
--   This section describes the flags that you can specify in the FLAGS
--argument to `glob'.  Choose the flags you want, and combine them with
--the C bitwise OR operator `|'.
--
--`GLOB_APPEND'
--     Append the words from this expansion to the vector of words
--     produced by previous calls to `glob'.  This way you can
--     effectively expand several words as if they were concatenated with
--     spaces between them.
--
--     In order for appending to work, you must not modify the contents
--     of the word vector structure between calls to `glob'.  And, if you
--     set `GLOB_DOOFFS' in the first call to `glob', you must also set
--     it when you append to the results.
--
--     Note that the pointer stored in `gl_pathv' may no longer be valid
--     after you call `glob' the second time, because `glob' might have
--     relocated the vector.  So always fetch `gl_pathv' from the
--     `glob_t' structure after each `glob' call; *never* save the
--     pointer across calls.
--
--`GLOB_DOOFFS'
--     Leave blank slots at the beginning of the vector of words.  The
--     `gl_offs' field says how many slots to leave.  The blank slots
--     contain null pointers.
--
--`GLOB_ERR'
--     Give up right away and report an error if there is any difficulty
--     reading the directories that must be read in order to expand
--     PATTERN fully.  Such difficulties might include a directory in
--     which you don't have the requisite access.  Normally, `glob' tries
--     its best to keep on going despite any errors, reading whatever
--     directories it can.
--
--     You can exercise even more control than this by specifying an
--     error-handler function ERRFUNC when you call `glob'.  If ERRFUNC
--     is not a null pointer, then `glob' doesn't give up right away when
--     it can't read a directory; instead, it calls ERRFUNC with two
--     arguments, like this:
--
--          (*ERRFUNC) (FILENAME, ERROR-CODE)
--
--     The argument FILENAME is the name of the directory that `glob'
--     couldn't open or couldn't read, and ERROR-CODE is the `errno'
--     value that was reported to `glob'.
--
--     If the error handler function returns nonzero, then `glob' gives up
--     right away.  Otherwise, it continues.
--
--`GLOB_MARK'
--     If the pattern matches the name of a directory, append `/' to the
--     directory's name when returning it.
--
--`GLOB_NOCHECK'
--     If the pattern doesn't match any file names, return the pattern
--     itself as if it were a file name that had been matched.
--     (Normally, when the pattern doesn't match anything, `glob' returns
--     that there were no matches.)
--
--`GLOB_NOSORT'
--     Don't sort the file names; return them in no particular order.
--     (In practice, the order will depend on the order of the entries in
--     the directory.)  The only reason *not* to sort is to save time.
--
--`GLOB_NOESCAPE'
--     Don't treat the `\' character specially in patterns.  Normally,
--     `\' quotes the following character, turning off its special meaning
--     (if any) so that it matches only itself.  When quoting is enabled,
--     the pattern `\?' matches only the string `?', because the question
--     mark in the pattern acts like an ordinary character.
--
--     If you use `GLOB_NOESCAPE', then `\' is an ordinary character.
--
--     `glob' does its work by calling the function `fnmatch' repeatedly.
--     It handles the flag `GLOB_NOESCAPE' by turning on the
--     `FNM_NOESCAPE' flag in calls to `fnmatch'.
--
--
--File: libc.info,  Node: Regular Expressions,  Next: Word Expansion,  Prev: 
Globbing,  Up: Pattern Matching
--
--Regular Expression Matching
--===========================
--
--   The GNU C library supports two interfaces for matching regular
--expressions.  One is the standard POSIX.2 interface, and the other is
--what the GNU system has had for many years.
--
--   Both interfaces are declared in the header file `regex.h'.  If you
--define `_POSIX_C_SOURCE', then only the POSIX.2 functions, structures,
--and constants are declared.
--
--* Menu:
--
--* POSIX Regexp Compilation::    Using `regcomp' to prepare to match.
--* Flags for POSIX Regexps::     Syntax variations for `regcomp'.
--* Matching POSIX Regexps::      Using `regexec' to match the compiled
--                                 pattern that you get from `regcomp'.
--* Regexp Subexpressions::       Finding which parts of the string were 
matched.
--* Subexpression Complications:: Find points of which parts were matched.
--* Regexp Cleanup::            Freeing storage; reporting errors.
--
--
--File: libc.info,  Node: POSIX Regexp Compilation,  Next: Flags for POSIX 
Regexps,  Up: Regular Expressions
--
--POSIX Regular Expression Compilation
--------------------------------------
--
--   Before you can actually match a regular expression, you must
--"compile" it.  This is not true compilation--it produces a special data
--structure, not machine instructions.  But it is like ordinary
--compilation in that its purpose is to enable you to "execute" the
--pattern fast.  (*Note Matching POSIX Regexps::, for how to use the
--compiled regular expression for matching.)
--
--   There is a special data type for compiled regular expressions:
--
-- - Data Type: regex_t
--     This type of object holds a compiled regular expression.  It is
--     actually a structure.  It has just one field that your programs
--     should look at:
--
--    `re_nsub'
--          This field holds the number of parenthetical subexpressions
--          in the regular expression that was compiled.
--
--     There are several other fields, but we don't describe them here,
--     because only the functions in the library should use them.
--
--   After you create a `regex_t' object, you can compile a regular
--expression into it by calling `regcomp'.
--
-- - Function: int regcomp (regex_t *COMPILED, const char *PATTERN, int
--          CFLAGS)
--     The function `regcomp' "compiles" a regular expression into a data
--     structure that you can use with `regexec' to match against a
--     string.  The compiled regular expression format is designed for
--     efficient matching.  `regcomp' stores it into `*COMPILED'.
--
--     It's up to you to allocate an object of type `regex_t' and pass its
--     address to `regcomp'.
--
--     The argument CFLAGS lets you specify various options that control
--     the syntax and semantics of regular expressions.  *Note Flags for
--     POSIX Regexps::.
--
--     If you use the flag `REG_NOSUB', then `regcomp' omits from the
--     compiled regular expression the information necessary to record
--     how subexpressions actually match.  In this case, you might as well
--     pass `0' for the MATCHPTR and NMATCH arguments when you call
--     `regexec'.
--
--     If you don't use `REG_NOSUB', then the compiled regular expression
--     does have the capacity to record how subexpressions match.  Also,
--     `regcomp' tells you how many subexpressions PATTERN has, by
--     storing the number in `COMPILED->re_nsub'.  You can use that value
--     to decide how long an array to allocate to hold information about
--     subexpression matches.
--
--     `regcomp' returns `0' if it succeeds in compiling the regular
--     expression; otherwise, it returns a nonzero error code (see the
--     table below).  You can use `regerror' to produce an error message
--     string describing the reason for a nonzero value; see *Note Regexp
--     Cleanup::.
--
--
--   Here are the possible nonzero values that `regcomp' can return:
--
--`REG_BADBR'
--     There was an invalid `\{...\}' construct in the regular
--     expression.  A valid `\{...\}' construct must contain either a
--     single number, or two numbers in increasing order separated by a
--     comma.
--
--`REG_BADPAT'
--     There was a syntax error in the regular expression.
--
--`REG_BADRPT'
--     A repetition operator such as `?' or `*' appeared in a bad
--     position (with no preceding subexpression to act on).
--
--`REG_ECOLLATE'
--     The regular expression referred to an invalid collating element
--     (one not defined in the current locale for string collation).
--     *Note Locale Categories::.
--
--`REG_ECTYPE'
--     The regular expression referred to an invalid character class name.
--
--`REG_EESCAPE'
--     The regular expression ended with `\'.
--
--`REG_ESUBREG'
--     There was an invalid number in the `\DIGIT' construct.
--
--`REG_EBRACK'
--     There were unbalanced square brackets in the regular expression.
--
--`REG_EPAREN'
--     An extended regular expression had unbalanced parentheses, or a
--     basic regular expression had unbalanced `\(' and `\)'.
--
--`REG_EBRACE'
--     The regular expression had unbalanced `\{' and `\}'.
--
--`REG_ERANGE'
--     One of the endpoints in a range expression was invalid.
--
--`REG_ESPACE'
--     `regcomp' ran out of memory.
--
--
--File: libc.info,  Node: Flags for POSIX Regexps,  Next: Matching POSIX 
Regexps,  Prev: POSIX Regexp Compilation,  Up: Regular Expressions
--
--Flags for POSIX Regular Expressions
-------------------------------------
--
--   These are the bit flags that you can use in the CFLAGS operand when
--compiling a regular expression with `regcomp'.
--
--`REG_EXTENDED'
--     Treat the pattern as an extended regular expression, rather than
--     as a basic regular expression.
--
--`REG_ICASE'
--     Ignore case when matching letters.
--
--`REG_NOSUB'
--     Don't bother storing the contents of the MATCHES-PTR array.
--
--`REG_NEWLINE'
--     Treat a newline in STRING as dividing STRING into multiple lines,
--     so that `$' can match before the newline and `^' can match after.
--     Also, don't permit `.' to match a newline, and don't permit
--     `[^...]' to match a newline.
--
--     Otherwise, newline acts like any other ordinary character.
--
--
--File: libc.info,  Node: Matching POSIX Regexps,  Next: Regexp Subexpressions, 
 Prev: Flags for POSIX Regexps,  Up: Regular Expressions
--
--Matching a Compiled POSIX Regular Expression
----------------------------------------------
--
--   Once you have compiled a regular expression, as described in *Note
--POSIX Regexp Compilation::, you can match it against strings using
--`regexec'.  A match anywhere inside the string counts as success,
--unless the regular expression contains anchor characters (`^' or `$').
--
-- - Function: int regexec (regex_t *COMPILED, char *STRING, size_t
--          NMATCH, regmatch_t MATCHPTR [], int EFLAGS)
--     This function tries to match the compiled regular expression
--     `*COMPILED' against STRING.
--
--     `regexec' returns `0' if the regular expression matches;
--     otherwise, it returns a nonzero value.  See the table below for
--     what nonzero values mean.  You can use `regerror' to produce an
--     error message string describing the reason for a nonzero value;
--     see *Note Regexp Cleanup::.
--
--     The argument EFLAGS is a word of bit flags that enable various
--     options.
--
--     If you want to get information about what part of STRING actually
--     matched the regular expression or its subexpressions, use the
--     arguments MATCHPTR and NMATCH.  Otherwise, pass `0' for NMATCH,
--     and `NULL' for MATCHPTR.  *Note Regexp Subexpressions::.
--
--   You must match the regular expression with the same set of current
--locales that were in effect when you compiled the regular expression.
--
--   The function `regexec' accepts the following flags in the EFLAGS
--argument:
--
--`REG_NOTBOL'
--     Do not regard the beginning of the specified string as the
--     beginning of a line; more generally, don't make any assumptions
--     about what text might precede it.
--
--`REG_NOTEOL'
--     Do not regard the end of the specified string as the end of a
--     line; more generally, don't make any assumptions about what text
--     might follow it.
--
--   Here are the possible nonzero values that `regexec' can return:
--
--`REG_NOMATCH'
--     The pattern didn't match the string.  This isn't really an error.
--
--`REG_ESPACE'
--     `regexec' ran out of memory.
--
--
--File: libc.info,  Node: Regexp Subexpressions,  Next: Subexpression 
Complications,  Prev: Matching POSIX Regexps,  Up: Regular Expressions
--
--Match Results with Subexpressions
-----------------------------------
--
--   When `regexec' matches parenthetical subexpressions of PATTERN, it
--records which parts of STRING they match.  It returns that information
--by storing the offsets into an array whose elements are structures of
--type `regmatch_t'.  The first element of the array (index `0') records
--the part of the string that matched the entire regular expression.
--Each other element of the array records the beginning and end of the
--part that matched a single parenthetical subexpression.
--
-- - Data Type: regmatch_t
--     This is the data type of the MATCHARRAY array that you pass to
--     `regexec'.  It contains two structure fields, as follows:
--
--    `rm_so'
--          The offset in STRING of the beginning of a substring.  Add
--          this value to STRING to get the address of that part.
--
--    `rm_eo'
--          The offset in STRING of the end of the substring.
--
-- - Data Type: regoff_t
--     `regoff_t' is an alias for another signed integer type.  The
--     fields of `regmatch_t' have type `regoff_t'.
--
--   The `regmatch_t' elements correspond to subexpressions positionally;
--the first element (index `1') records where the first subexpression
--matched, the second element records the second subexpression, and so
--on.  The order of the subexpressions is the order in which they begin.
--
--   When you call `regexec', you specify how long the MATCHPTR array is,
--with the NMATCH argument.  This tells `regexec' how many elements to
--store.  If the actual regular expression has more than NMATCH
--subexpressions, then you won't get offset information about the rest of
--them.  But this doesn't alter whether the pattern matches a particular
--string or not.
--
--   If you don't want `regexec' to return any information about where
--the subexpressions matched, you can either supply `0' for NMATCH, or
--use the flag `REG_NOSUB' when you compile the pattern with `regcomp'.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-17 
glibc-2.0.1/manual/libc.info-17
---- ../glibc-2.0.1/manual/libc.info-17 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-17    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1227 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Subexpression Complications,  Next: Regexp Cleanup,  
Prev: Regexp Subexpressions,  Up: Regular Expressions
--
--Complications in Subexpression Matching
-----------------------------------------
--
--   Sometimes a subexpression matches a substring of no characters.  This
--happens when `f\(o*\)' matches the string `fum'.  (It really matches
--just the `f'.)  In this case, both of the offsets identify the point in
--the string where the null substring was found.  In this example, the
--offsets are both `1'.
--
--   Sometimes the entire regular expression can match without using some
--of its subexpressions at all--for example, when `ba\(na\)*' matches the
--string `ba', the parenthetical subexpression is not used.  When this
--happens, `regexec' stores `-1' in both fields of the element for that
--subexpression.
--
--   Sometimes matching the entire regular expression can match a
--particular subexpression more than once--for example, when `ba\(na\)*'
--matches the string `bananana', the parenthetical subexpression matches
--three times.  When this happens, `regexec' usually stores the offsets
--of the last part of the string that matched the subexpression.  In the
--case of `bananana', these offsets are `6' and `8'.
--
--   But the last match is not always the one that is chosen.  It's more
--accurate to say that the last *opportunity* to match is the one that
--takes precedence.  What this means is that when one subexpression
--appears within another, then the results reported for the inner
--subexpression reflect whatever happened on the last match of the outer
--subexpression.  For an example, consider `\(ba\(na\)*s \)*' matching
--the string `bananas bas '.  The last time the inner expression actually
--matches is near the end of the first word.  But it is *considered*
--again in the second word, and fails to match there.  `regexec' reports
--nonuse of the "na" subexpression.
--
--   Another place where this rule applies is when the regular expression
--`\(ba\(na\)*s \|nefer\(ti\)* \)*' matches `bananas nefertiti'.  The
--"na" subexpression does match in the first word, but it doesn't match
--in the second word because the other alternative is used there.  Once
--again, the second repetition of the outer subexpression overrides the
--first, and within that second repetition, the "na" subexpression is not
--used.  So `regexec' reports nonuse of the "na" subexpression.
--
--
--File: libc.info,  Node: Regexp Cleanup,  Prev: Subexpression Complications,  
Up: Regular Expressions
--
--POSIX Regexp Matching Cleanup
-------------------------------
--
--   When you are finished using a compiled regular expression, you can
--free the storage it uses by calling `regfree'.
--
-- - Function: void regfree (regex_t *COMPILED)
--     Calling `regfree' frees all the storage that `*COMPILED' points
--     to.  This includes various internal fields of the `regex_t'
--     structure that aren't documented in this manual.
--
--     `regfree' does not free the object `*COMPILED' itself.
--
--   You should always free the space in a `regex_t' structure with
--`regfree' before using the structure to compile another regular
--expression.
--
--   When `regcomp' or `regexec' reports an error, you can use the
--function `regerror' to turn it into an error message string.
--
-- - Function: size_t regerror (int ERRCODE, regex_t *COMPILED, char
--          *BUFFER, size_t LENGTH)
--     This function produces an error message string for the error code
--     ERRCODE, and stores the string in LENGTH bytes of memory starting
--     at BUFFER.  For the COMPILED argument, supply the same compiled
--     regular expression structure that `regcomp' or `regexec' was
--     working with when it got the error.  Alternatively, you can supply
--     `NULL' for COMPILED; you will still get a meaningful error
--     message, but it might not be as detailed.
--
--     If the error message can't fit in LENGTH bytes (including a
--     terminating null character), then `regerror' truncates it.  The
--     string that `regerror' stores is always null-terminated even if it
--     has been truncated.
--
--     The return value of `regerror' is the minimum length needed to
--     store the entire error message.  If this is less than LENGTH, then
--     the error message was not truncated, and you can use it.
--     Otherwise, you should call `regerror' again with a larger buffer.
--
--     Here is a function which uses `regerror', but always dynamically
--     allocates a buffer for the error message:
--
--          char *get_regerror (int errcode, regex_t *compiled)
--          {
--            size_t length = regerror (errcode, compiled, NULL, 0);
--            char *buffer = xmalloc (length);
--            (void) regerror (errcode, compiled, buffer, length);
--            return buffer;
--          }
--
--
--File: libc.info,  Node: Word Expansion,  Prev: Regular Expressions,  Up: 
Pattern Matching
--
--Shell-Style Word Expansion
--==========================
--
--   "Word expansion" means the process of splitting a string into
--"words" and substituting for variables, commands, and wildcards just as
--the shell does.
--
--   For example, when you write `ls -l foo.c', this string is split into
--three separate words--`ls', `-l' and `foo.c'.  This is the most basic
--function of word expansion.
--
--   When you write `ls *.c', this can become many words, because the
--word `*.c' can be replaced with any number of file names.  This is
--called "wildcard expansion", and it is also a part of word expansion.
--
--   When you use `echo $PATH' to print your path, you are taking
--advantage of "variable substitution", which is also part of word
--expansion.
--
--   Ordinary programs can perform word expansion just like the shell by
--calling the library function `wordexp'.
--
--* Menu:
--
--* Expansion Stages::  What word expansion does to a string.
--* Calling Wordexp::   How to call `wordexp'.
--* Flags for Wordexp::   Options you can enable in `wordexp'.
--* Wordexp Example::   A sample program that does word expansion.
--
--
--File: libc.info,  Node: Expansion Stages,  Next: Calling Wordexp,  Up: Word 
Expansion
--
--The Stages of Word Expansion
------------------------------
--
--   When word expansion is applied to a sequence of words, it performs
--the following transformations in the order shown here:
--
--  1. "Tilde expansion": Replacement of `~foo' with the name of the home
--     directory of `foo'.
--
--  2. Next, three different transformations are applied in the same step,
--     from left to right:
--
--        * "Variable substitution": Environment variables are
--          substituted for references such as `$foo'.
--
--        * "Command substitution": Constructs such as ``cat foo`' and
--          the equivalent `$(cat foo)' are replaced with the output from
--          the inner command.
--
--        * "Arithmetic expansion": Constructs such as `$(($x-1))' are
--          replaced with the result of the arithmetic computation.
--
--  3. "Field splitting": subdivision of the text into "words".
--
--  4. "Wildcard expansion": The replacement of a construct such as `*.c'
--     with a list of `.c' file names.  Wildcard expansion applies to an
--     entire word at a time, and replaces that word with 0 or more file
--     names that are themselves words.
--
--  5. "Quote removal": The deletion of string-quotes, now that they have
--     done their job by inhibiting the above transformations when
--     appropriate.
--
--   For the details of these transformations, and how to write the
--constructs that use them, see `The BASH Manual' (to appear).
--
--
--File: libc.info,  Node: Calling Wordexp,  Next: Flags for Wordexp,  Prev: 
Expansion Stages,  Up: Word Expansion
--
--Calling `wordexp'
-------------------
--
--   All the functions, constants and data types for word expansion are
--declared in the header file `wordexp.h'.
--
--   Word expansion produces a vector of words (strings).  To return this
--vector, `wordexp' uses a special data type, `wordexp_t', which is a
--structure.  You pass `wordexp' the address of the structure, and it
--fills in the structure's fields to tell you about the results.
--
-- - Data Type: wordexp_t
--     This data type holds a pointer to a word vector.  More precisely,
--     it records both the address of the word vector and its size.
--
--    `we_wordc'
--          The number of elements in the vector.
--
--    `we_wordv'
--          The address of the vector.  This field has type `char **'.
--
--    `we_offs'
--          The offset of the first real element of the vector, from its
--          nominal address in the `we_wordv' field.  Unlike the other
--          fields, this is always an input to `wordexp', rather than an
--          output from it.
--
--          If you use a nonzero offset, then that many elements at the
--          beginning of the vector are left empty.  (The `wordexp'
--          function fills them with null pointers.)
--
--          The `we_offs' field is meaningful only if you use the
--          `WRDE_DOOFFS' flag.  Otherwise, the offset is always zero
--          regardless of what is in this field, and the first real
--          element comes at the beginning of the vector.
--
-- - Function: int wordexp (const char *WORDS, wordexp_t
--          *WORD-VECTOR-PTR, int FLAGS)
--     Perform word expansion on the string WORDS, putting the result in
--     a newly allocated vector, and store the size and address of this
--     vector into `*WORD-VECTOR-PTR'.  The argument FLAGS is a
--     combination of bit flags; see *Note Flags for Wordexp::, for
--     details of the flags.
--
--     You shouldn't use any of the characters `|&;<>' in the string
--     WORDS unless they are quoted; likewise for newline.  If you use
--     these characters unquoted, you will get the `WRDE_BADCHAR' error
--     code.  Don't use parentheses or braces unless they are quoted or
--     part of a word expansion construct.  If you use quotation
--     characters `'"`', they should come in pairs that balance.
--
--     The results of word expansion are a sequence of words.  The
--     function `wordexp' allocates a string for each resulting word, then
--     allocates a vector of type `char **' to store the addresses of
--     these strings.  The last element of the vector is a null pointer.
--     This vector is called the "word vector".
--
--     To return this vector, `wordexp' stores both its address and its
--     length (number of elements, not counting the terminating null
--     pointer) into `*WORD-VECTOR-PTR'.
--
--     If `wordexp' succeeds, it returns 0.  Otherwise, it returns one of
--     these error codes:
--
--    `WRDE_BADCHAR'
--          The input string WORDS contains an unquoted invalid character
--          such as `|'.
--
--    `WRDE_BADVAL'
--          The input string refers to an undefined shell variable, and
--          you used the flag `WRDE_UNDEF' to forbid such references.
--
--    `WRDE_CMDSUB'
--          The input string uses command substitution, and you used the
--          flag `WRDE_NOCMD' to forbid command substitution.
--
--    `WRDE_NOSPACE'
--          It was impossible to allocate memory to hold the result.  In
--          this case, `wordexp' can store part of the results--as much
--          as it could allocate room for.
--
--    `WRDE_SYNTAX'
--          There was a syntax error in the input string.  For example,
--          an unmatched quoting character is a syntax error.
--
-- - Function: void wordfree (wordexp_t *WORD-VECTOR-PTR)
--     Free the storage used for the word-strings and vector that
--     `*WORD-VECTOR-PTR' points to.  This does not free the structure
--     `*WORD-VECTOR-PTR' itself--only the other data it points to.
--
--
--File: libc.info,  Node: Flags for Wordexp,  Next: Wordexp Example,  Prev: 
Calling Wordexp,  Up: Word Expansion
--
--Flags for Word Expansion
--------------------------
--
--   This section describes the flags that you can specify in the FLAGS
--argument to `wordexp'.  Choose the flags you want, and combine them
--with the C operator `|'.
--
--`WRDE_APPEND'
--     Append the words from this expansion to the vector of words
--     produced by previous calls to `wordexp'.  This way you can
--     effectively expand several words as if they were concatenated with
--     spaces between them.
--
--     In order for appending to work, you must not modify the contents
--     of the word vector structure between calls to `wordexp'.  And, if
--     you set `WRDE_DOOFFS' in the first call to `wordexp', you must also
--     set it when you append to the results.
--
--`WRDE_DOOFFS'
--     Leave blank slots at the beginning of the vector of words.  The
--     `we_offs' field says how many slots to leave.  The blank slots
--     contain null pointers.
--
--`WRDE_NOCMD'
--     Don't do command substitution; if the input requests command
--     substitution, report an error.
--
--`WRDE_REUSE'
--     Reuse a word vector made by a previous call to `wordexp'.  Instead
--     of allocating a new vector of words, this call to `wordexp' will
--     use the vector that already exists (making it larger if necessary).
--
--     Note that the vector may move, so it is not safe to save an old
--     pointer and use it again after calling `wordexp'.  You must fetch
--     `we_pathv' anew after each call.
--
--`WRDE_SHOWERR'
--     Do show any error messages printed by commands run by command
--     substitution.  More precisely, allow these commands to inherit the
--     standard error output stream of the current process.  By default,
--     `wordexp' gives these commands a standard error stream that
--     discards all output.
--
--`WRDE_UNDEF'
--     If the input refers to a shell variable that is not defined,
--     report an error.
--
--
--File: libc.info,  Node: Wordexp Example,  Prev: Flags for Wordexp,  Up: Word 
Expansion
--
--`wordexp' Example
-------------------
--
--   Here is an example of using `wordexp' to expand several strings and
--use the results to run a shell command.  It also shows the use of
--`WRDE_APPEND' to concatenate the expansions and of `wordfree' to free
--the space allocated by `wordexp'.
--
--     int
--     expand_and_execute (const char *program, const char *options)
--     {
--       wordexp_t result;
--       pid_t pid
--       int status, i;
--     
--       /* Expand the string for the program to run.  */
--       switch (wordexp (program, &result, 0))
--         {
--         case 0:                      /* Successful.  */
--           break;
--         case WRDE_NOSPACE:
--           /* If the error was `WRDE_NOSPACE',
--              then perhaps part of the result was allocated.  */
--           wordfree (&result);
--         default:                    /* Some other error.  */
--           return -1;
--         }
--     
--       /* Expand the strings specified for the arguments.  */
--       for (i = 0; args[i]; i++)
--         {
--           if (wordexp (options, &result, WRDE_APPEND))
--             {
--               wordfree (&result);
--               return -1;
--             }
--         }
--     
--       pid = fork ();
--       if (pid == 0)
--         {
--           /* This is the child process.  Execute the command. */
--           execv (result.we_wordv[0], result.we_wordv);
--           exit (EXIT_FAILURE);
--         }
--       else if (pid < 0)
--         /* The fork failed.  Report failure.  */
--         status = -1;
--       else
--         /* This is the parent process.  Wait for the child to complete.  */
--         if (waitpid (pid, &status, 0) != pid)
--           status = -1;
--     
--       wordfree (&result);
--       return status;
--     }
--
--   In practice, since `wordexp' is executed by running a subshell, it
--would be faster to do this by concatenating the strings with spaces
--between them and running that as a shell command using `sh -c'.
--
--
--File: libc.info,  Node: Date and Time,  Next: Non-Local Exits,  Prev: 
Arithmetic,  Up: Top
--
--Date and Time
--*************
--
--   This chapter describes functions for manipulating dates and times,
--including functions for determining what the current time is and
--conversion between different time representations.
--
--   The time functions fall into three main categories:
--
--   * Functions for measuring elapsed CPU time are discussed in *Note
--     Processor Time::.
--
--   * Functions for measuring absolute clock or calendar time are
--     discussed in *Note Calendar Time::.
--
--   * Functions for setting alarms and timers are discussed in *Note
--     Setting an Alarm::.
--
--* Menu:
--
--* Processor Time::              Measures processor time used by a program.
--* Calendar Time::               Manipulation of "real" dates and times.
--* Setting an Alarm::            Sending a signal after a specified time.
--* Sleeping::                    Waiting for a period of time.
--* Resource Usage::            Measuring various resources used.
--* Limits on Resources::               Specifying limits on resource usage.
--* Priority::                  Reading or setting process run priority.
--
--
--File: libc.info,  Node: Processor Time,  Next: Calendar Time,  Up: Date and 
Time
--
--Processor Time
--==============
--
--   If you're trying to optimize your program or measure its efficiency,
--it's very useful to be able to know how much "processor time" or "CPU
--time" it has used at any given point.  Processor time is different from
--actual wall clock time because it doesn't include any time spent waiting
--for I/O or when some other process is running.  Processor time is
--represented by the data type `clock_t', and is given as a number of
--"clock ticks" relative to an arbitrary base time marking the beginning
--of a single program invocation.
--
--* Menu:
--
--* Basic CPU Time::              The `clock' function.
--* Detailed CPU Time::           The `times' function.
--
--
--File: libc.info,  Node: Basic CPU Time,  Next: Detailed CPU Time,  Up: 
Processor Time
--
--Basic CPU Time Inquiry
------------------------
--
--   To get the elapsed CPU time used by a process, you can use the
--`clock' function.  This facility is declared in the header file
--`time.h'.
--
--   In typical usage, you call the `clock' function at the beginning and
--end of the interval you want to time, subtract the values, and then
--divide by `CLOCKS_PER_SEC' (the number of clock ticks per second), like
--this:
--
--     #include <time.h>
--     
--     clock_t start, end;
--     double elapsed;
--     
--     start = clock();
--     ... /* Do the work. */
--     end = clock();
--     elapsed = ((double) (end - start)) / CLOCKS_PER_SEC;
--
--   Different computers and operating systems vary wildly in how they
--keep track of processor time.  It's common for the internal processor
--clock to have a resolution somewhere between hundredths and millionths
--of a second.
--
--   In the GNU system, `clock_t' is equivalent to `long int' and
--`CLOCKS_PER_SEC' is an integer value.  But in other systems, both
--`clock_t' and the type of the macro `CLOCKS_PER_SEC' can be either
--integer or floating-point types.  Casting processor time values to
--`double', as in the example above, makes sure that operations such as
--arithmetic and printing work properly and consistently no matter what
--the underlying representation is.
--
-- - Macro: int CLOCKS_PER_SEC
--     The value of this macro is the number of clock ticks per second
--     measured by the `clock' function.
--
-- - Macro: int CLK_TCK
--     This is an obsolete name for `CLOCKS_PER_SEC'.
--
-- - Data Type: clock_t
--     This is the type of the value returned by the `clock' function.
--     Values of type `clock_t' are in units of clock ticks.
--
-- - Function: clock_t clock (void)
--     This function returns the elapsed processor time.  The base time is
--     arbitrary but doesn't change within a single process.  If the
--     processor time is not available or cannot be represented, `clock'
--     returns the value `(clock_t)(-1)'.
--
--
--File: libc.info,  Node: Detailed CPU Time,  Prev: Basic CPU Time,  Up: 
Processor Time
--
--Detailed Elapsed CPU Time Inquiry
-----------------------------------
--
--   The `times' function returns more detailed information about elapsed
--processor time in a `struct tms' object.  You should include the header
--file `sys/times.h' to use this facility.
--
-- - Data Type: struct tms
--     The `tms' structure is used to return information about process
--     times.  It contains at least the following members:
--
--    `clock_t tms_utime'
--          This is the CPU time used in executing the instructions of
--          the calling process.
--
--    `clock_t tms_stime'
--          This is the CPU time used by the system on behalf of the
--          calling process.
--
--    `clock_t tms_cutime'
--          This is the sum of the `tms_utime' values and the `tms_cutime'
--          values of all terminated child processes of the calling
--          process, whose status has been reported to the parent process
--          by `wait' or `waitpid'; see *Note Process Completion::.  In
--          other words, it represents the total CPU time used in
--          executing the instructions of all the terminated child
--          processes of the calling process, excluding child processes
--          which have not yet been reported by `wait' or `waitpid'.
--
--    `clock_t tms_cstime'
--          This is similar to `tms_cutime', but represents the total CPU
--          time used by the system on behalf of all the terminated child
--          processes of the calling process.
--
--     All of the times are given in clock ticks.  These are absolute
--     values; in a newly created process, they are all zero.  *Note
--     Creating a Process::.
--
-- - Function: clock_t times (struct tms *BUFFER)
--     The `times' function stores the processor time information for the
--     calling process in BUFFER.
--
--     The return value is the same as the value of `clock()': the elapsed
--     real time relative to an arbitrary base.  The base is a constant
--     within a particular process, and typically represents the time
--     since system start-up.  A value of `(clock_t)(-1)' is returned to
--     indicate failure.
--
--   *Portability Note:* The `clock' function described in *Note Basic
--CPU Time::, is specified by the ISO C standard.  The `times' function
--is a feature of POSIX.1.  In the GNU system, the value returned by the
--`clock' function is equivalent to the sum of the `tms_utime' and
--`tms_stime' fields returned by `times'.
--
--
--File: libc.info,  Node: Calendar Time,  Next: Setting an Alarm,  Prev: 
Processor Time,  Up: Date and Time
--
--Calendar Time
--=============
--
--   This section describes facilities for keeping track of dates and
--times according to the Gregorian calendar.
--
--   There are three representations for date and time information:
--
--   * "Calendar time" (the `time_t' data type) is a compact
--     representation, typically giving the number of seconds elapsed
--     since some implementation-specific base time.
--
--   * There is also a "high-resolution time" representation (the `struct
--     timeval' data type) that includes fractions of a second.  Use this
--     time representation instead of ordinary calendar time when you
--     need greater precision.
--
--   * "Local time" or "broken-down time" (the `struct tm' data type)
--     represents the date and time as a set of components specifying the
--     year, month, and so on, for a specific time zone.  This time
--     representation is usually used in conjunction with formatting date
--     and time values.
--
--* Menu:
--
--* Simple Calendar Time::        Facilities for manipulating calendar time.
--* High-Resolution Calendar::    A time representation with greater precision.
--* Broken-down Time::            Facilities for manipulating local time.
--* Formatting Date and Time::    Converting times to strings.
--* TZ Variable::                 How users specify the time zone.
--* Time Zone Functions::         Functions to examine or specify the time zone.
--* Time Functions Example::      An example program showing use of some of
--                               the time functions.
--
--
--File: libc.info,  Node: Simple Calendar Time,  Next: High-Resolution 
Calendar,  Up: Calendar Time
--
--Simple Calendar Time
----------------------
--
--   This section describes the `time_t' data type for representing
--calendar time, and the functions which operate on calendar time objects.
--These facilities are declared in the header file `time.h'.
--
-- - Data Type: time_t
--     This is the data type used to represent calendar time.  When
--     interpreted as an absolute time value, it represents the number of
--     seconds elapsed since 00:00:00 on January 1, 1970, Coordinated
--     Universal Time.  (This date is sometimes referred to as the
--     "epoch".)  POSIX requires that this count ignore leap seconds, but
--     on some hosts this count includes leap seconds if you set `TZ' to
--     certain values (*note TZ Variable::.).
--
--     In the GNU C library, `time_t' is equivalent to `long int'.  In
--     other systems, `time_t' might be either an integer or
--     floating-point type.
--
-- - Function: double difftime (time_t TIME1, time_t TIME0)
--     The `difftime' function returns the number of seconds elapsed
--     between time TIME1 and time TIME0, as a value of type `double'.
--     The difference ignores leap seconds unless leap second support is
--     enabled.
--
--     In the GNU system, you can simply subtract `time_t' values.  But on
--     other systems, the `time_t' data type might use some other encoding
--     where subtraction doesn't work directly.
--
-- - Function: time_t time (time_t *RESULT)
--     The `time' function returns the current time as a value of type
--     `time_t'.  If the argument RESULT is not a null pointer, the time
--     value is also stored in `*RESULT'.  If the calendar time is not
--     available, the value `(time_t)(-1)' is returned.
--
--
--File: libc.info,  Node: High-Resolution Calendar,  Next: Broken-down Time,  
Prev: Simple Calendar Time,  Up: Calendar Time
--
--High-Resolution Calendar
--------------------------
--
--   The `time_t' data type used to represent calendar times has a
--resolution of only one second.  Some applications need more precision.
--
--   So, the GNU C library also contains functions which are capable of
--representing calendar times to a higher resolution than one second.  The
--functions and the associated data types described in this section are
--declared in `sys/time.h'.
--
-- - Data Type: struct timeval
--     The `struct timeval' structure represents a calendar time.  It has
--     the following members:
--
--    `long int tv_sec'
--          This represents the number of seconds since the epoch.  It is
--          equivalent to a normal `time_t' value.
--
--    `long int tv_usec'
--          This is the fractional second value, represented as the
--          number of microseconds.
--
--          Some times struct timeval values are used for time intervals.
--          Then the `tv_sec' member is the number of seconds in the
--          interval, and `tv_usec' is the number of additional
--          microseconds.
--
-- - Data Type: struct timezone
--     The `struct timezone' structure is used to hold minimal information
--     about the local time zone.  It has the following members:
--
--    `int tz_minuteswest'
--          This is the number of minutes west of UTC.
--
--    `int tz_dsttime'
--          If nonzero, daylight saving time applies during some part of
--          the year.
--
--     The `struct timezone' type is obsolete and should never be used.
--     Instead, use the facilities described in *Note Time Zone
--     Functions::.
--
--   It is often necessary to subtract two values of type
--`struct timeval'.  Here is the best way to do this.  It works even on
--some peculiar operating systems where the `tv_sec' member has an
--unsigned type.
--
--     /* Subtract the `struct timeval' values X and Y,
--        storing the result in RESULT.
--        Return 1 if the difference is negative, otherwise 0.  */
--     
--     int
--     timeval_subtract (result, x, y)
--          struct timeval *result, *x, *y;
--     {
--       /* Perform the carry for the later subtraction by updating Y. */
--       if (x->tv_usec < y->tv_usec) {
--         int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
--         y->tv_usec -= 1000000 * nsec;
--         y->tv_sec += nsec;
--       }
--       if (x->tv_usec - y->tv_usec > 1000000) {
--         int nsec = (y->tv_usec - x->tv_usec) / 1000000;
--         y->tv_usec += 1000000 * nsec;
--         y->tv_sec -= nsec;
--       }
--     
--       /* Compute the time remaining to wait.
--          `tv_usec' is certainly positive. */
--       result->tv_sec = x->tv_sec - y->tv_sec;
--       result->tv_usec = x->tv_usec - y->tv_usec;
--     
--       /* Return 1 if result is negative. */
--       return x->tv_sec < y->tv_sec;
--     }
--
-- - Function: int gettimeofday (struct timeval *TP, struct timezone *TZP)
--     The `gettimeofday' function returns the current date and time in
--     the `struct timeval' structure indicated by TP.  Information about
--     the time zone is returned in the structure pointed at TZP.  If the
--     TZP argument is a null pointer, time zone information is ignored.
--
--     The return value is `0' on success and `-1' on failure.  The
--     following `errno' error condition is defined for this function:
--
--    `ENOSYS'
--          The operating system does not support getting time zone
--          information, and TZP is not a null pointer.  The GNU
--          operating system does not support using `struct timezone' to
--          represent time zone information; that is an obsolete feature
--          of 4.3 BSD.  Instead, use the facilities described in *Note
--          Time Zone Functions::.
--
-- - Function: int settimeofday (const struct timeval *TP, const struct
--          timezone *TZP)
--     The `settimeofday' function sets the current date and time
--     according to the arguments.  As for `gettimeofday', time zone
--     information is ignored if TZP is a null pointer.
--
--     You must be a privileged user in order to use `settimeofday'.
--
--     The return value is `0' on success and `-1' on failure.  The
--     following `errno' error conditions are defined for this function:
--
--    `EPERM'
--          This process cannot set the time because it is not privileged.
--
--    `ENOSYS'
--          The operating system does not support setting time zone
--          information, and TZP is not a null pointer.
--
-- - Function: int adjtime (const struct timeval *DELTA, struct timeval
--          *OLDDELTA)
--     This function speeds up or slows down the system clock in order to
--     make gradual adjustments in the current time.  This ensures that
--     the time reported by the system clock is always monotonically
--     increasing, which might not happen if you simply set the current
--     time.
--
--     The DELTA argument specifies a relative adjustment to be made to
--     the current time.  If negative, the system clock is slowed down
--     for a while until it has lost this much time.  If positive, the
--     system clock is speeded up for a while.
--
--     If the OLDDELTA argument is not a null pointer, the `adjtime'
--     function returns information about any previous time adjustment
--     that has not yet completed.
--
--     This function is typically used to synchronize the clocks of
--     computers in a local network.  You must be a privileged user to
--     use it.  The return value is `0' on success and `-1' on failure.
--     The following `errno' error condition is defined for this function:
--
--    `EPERM'
--          You do not have privilege to set the time.
--
--   *Portability Note:*  The `gettimeofday', `settimeofday', and
--`adjtime' functions are derived from BSD.
--
--
--File: libc.info,  Node: Broken-down Time,  Next: Formatting Date and Time,  
Prev: High-Resolution Calendar,  Up: Calendar Time
--
--Broken-down Time
------------------
--
--   Calendar time is represented as a number of seconds.  This is
--convenient for calculation, but has no resemblance to the way people
--normally represent dates and times.  By contrast, "broken-down time" is
--a binary representation separated into year, month, day, and so on.
--Broken down time values are not useful for calculations, but they are
--useful for printing human readable time.
--
--   A broken-down time value is always relative to a choice of local time
--zone, and it also indicates which time zone was used.
--
--   The symbols in this section are declared in the header file `time.h'.
--
-- - Data Type: struct tm
--     This is the data type used to represent a broken-down time.  The
--     structure contains at least the following members, which can
--     appear in any order:
--
--    `int tm_sec'
--          This is the number of seconds after the minute, normally in
--          the range `0' through `59'.  (The actual upper limit is `60',
--          to allow for leap seconds if leap second support is
--          available.)
--
--    `int tm_min'
--          This is the number of minutes after the hour, in the range
--          `0' through `59'.
--
--    `int tm_hour'
--          This is the number of hours past midnight, in the range `0'
--          through `23'.
--
--    `int tm_mday'
--          This is the day of the month, in the range `1' through `31'.
--
--    `int tm_mon'
--          This is the number of months since January, in the range `0'
--          through `11'.
--
--    `int tm_year'
--          This is the number of years since `1900'.
--
--    `int tm_wday'
--          This is the number of days since Sunday, in the range `0'
--          through `6'.
--
--    `int tm_yday'
--          This is the number of days since January 1, in the range `0'
--          through `365'.
--
--    `int tm_isdst'
--          This is a flag that indicates whether Daylight Saving Time is
--          (or was, or will be) in effect at the time described.  The
--          value is positive if Daylight Saving Time is in effect, zero
--          if it is not, and negative if the information is not
--          available.
--
--    `long int tm_gmtoff'
--          This field describes the time zone that was used to compute
--          this broken-down time value, including any adjustment for
--          daylight saving; it is the number of seconds that you must
--          add to UTC to get local time.  You can also think of this as
--          the number of seconds east of UTC.  For example, for U.S.
--          Eastern Standard Time, the value is `-5*60*60'.  The
--          `tm_gmtoff' field is derived from BSD and is a GNU library
--          extension; it is not visible in a strict ISO C environment.
--
--    `const char *tm_zone'
--          This field is the name for the time zone that was used to
--          compute this broken-down time value.  Like `tm_gmtoff', this
--          field is a BSD and GNU extension, and is not visible in a
--          strict ISO C environment.
--
-- - Function: struct tm * localtime (const time_t *TIME)
--     The `localtime' function converts the calendar time pointed to by
--     TIME to broken-down time representation, expressed relative to the
--     user's specified time zone.
--
--     The return value is a pointer to a static broken-down time
--     structure, which might be overwritten by subsequent calls to
--     `ctime', `gmtime', or `localtime'.  (But no other library function
--     overwrites the contents of this object.)
--
--     Calling `localtime' has one other effect: it sets the variable
--     `tzname' with information about the current time zone.  *Note Time
--     Zone Functions::.
--
-- - Function: struct tm * gmtime (const time_t *TIME)
--     This function is similar to `localtime', except that the
--     broken-down time is expressed as Coordinated Universal Time
--     (UTC)--that is, as Greenwich Mean Time (GMT)--rather than relative
--     to the local time zone.
--
--     Recall that calendar times are *always* expressed in coordinated
--     universal time.
--
-- - Function: time_t mktime (struct tm *BROKENTIME)
--     The `mktime' function is used to convert a broken-down time
--     structure to a calendar time representation.  It also "normalizes"
--     the contents of the broken-down time structure, by filling in the
--     day of week and day of year based on the other date and time
--     components.
--
--     The `mktime' function ignores the specified contents of the
--     `tm_wday' and `tm_yday' members of the broken-down time structure.
--     It uses the values of the other components to compute the
--     calendar time; it's permissible for these components to have
--     unnormalized values outside of their normal ranges.  The last
--     thing that `mktime' does is adjust the components of the BROKENTIME
--     structure (including the `tm_wday' and `tm_yday').
--
--     If the specified broken-down time cannot be represented as a
--     calendar time, `mktime' returns a value of `(time_t)(-1)' and does
--     not modify the contents of BROKENTIME.
--
--     Calling `mktime' also sets the variable `tzname' with information
--     about the current time zone.  *Note Time Zone Functions::.
--
--
--File: libc.info,  Node: Formatting Date and Time,  Next: TZ Variable,  Prev: 
Broken-down Time,  Up: Calendar Time
--
--Formatting Date and Time
--------------------------
--
--   The functions described in this section format time values as
--strings.  These functions are declared in the header file `time.h'.
--
-- - Function: char * asctime (const struct tm *BROKENTIME)
--     The `asctime' function converts the broken-down time value that
--     BROKENTIME points to into a string in a standard format:
--
--          "Tue May 21 13:46:22 1991\n"
--
--     The abbreviations for the days of week are: `Sun', `Mon', `Tue',
--     `Wed', `Thu', `Fri', and `Sat'.
--
--     The abbreviations for the months are: `Jan', `Feb', `Mar', `Apr',
--     `May', `Jun', `Jul', `Aug', `Sep', `Oct', `Nov', and `Dec'.
--
--     The return value points to a statically allocated string, which
--     might be overwritten by subsequent calls to `asctime' or `ctime'.
--     (But no other library function overwrites the contents of this
--     string.)
--
-- - Function: char * ctime (const time_t *TIME)
--     The `ctime' function is similar to `asctime', except that the time
--     value is specified as a `time_t' calendar time value rather than
--     in broken-down local time format.  It is equivalent to
--
--          asctime (localtime (TIME))
--
--     `ctime' sets the variable `tzname', because `localtime' does so.
--     *Note Time Zone Functions::.
--
-- - Function: size_t strftime (char *S, size_t SIZE, const char
--          *TEMPLATE, const struct tm *BROKENTIME)
--     This function is similar to the `sprintf' function (*note
--     Formatted Input::.), but the conversion specifications that can
--     appear in the format template TEMPLATE are specialized for
--     printing components of the date and time BROKENTIME according to
--     the locale currently specified for time conversion (*note
--     Locales::.).
--
--     Ordinary characters appearing in the TEMPLATE are copied to the
--     output string S; this can include multibyte character sequences.
--     Conversion specifiers are introduced by a `%' character, followed
--     by an optional flag which can be one of the following.  These
--     flags, which are GNU extensions, affect only the output of numbers:
--
--    `_'
--          The number is padded with spaces.
--
--    `-'
--          The number is not padded at all.
--
--    `0'
--          The number is padded with zeros even if the format specifies
--          padding with spaces.
--
--    `^'
--          The output uses uppercase characters, but only if this is
--          possible (*note Case Conversion::.).
--
--     The default action is to pad the number with zeros to keep it a
--     constant width.  Numbers that do not have a range indicated below
--     are never padded, since there is no natural width for them.
--
--     Following the flag an optional specification of the width is
--     possible.  This is specified in decimal notation.  If the natural
--     size of the output is of the field has less than the specified
--     number of characters, the result is written right adjusted and
--     space padded to the given size.
--
--     An optional modifier can follow the optional flag and width
--     specification.  The modifiers, which are POSIX.2 extensions, are:
--
--    `E'
--          Use the locale's alternate representation for date and time.
--          This modifier applies to the `%c', `%C', `%x', `%X', `%y' and
--          `%Y' format specifiers.  In a Japanese locale, for example,
--          `%Ex' might yield a date format based on the Japanese
--          Emperors' reigns.
--
--    `O'
--          Use the locale's alternate numeric symbols for numbers.  This
--          modifier applies only to numeric format specifiers.
--
--     If the format supports the modifier but no alternate representation
--     is available, it is ignored.
--
--     The conversion specifier ends with a format specifier taken from
--     the following list.  The whole `%' sequence is replaced in the
--     output string as follows:
--
--    `%a'
--          The abbreviated weekday name according to the current locale.
--
--    `%A'
--          The full weekday name according to the current locale.
--
--    `%b'
--          The abbreviated month name according to the current locale.
--
--    `%B'
--          The full month name according to the current locale.
--
--    `%c'
--          The preferred date and time representation for the current
--          locale.
--
--    `%C'
--          The century of the year.  This is equivalent to the greatest
--          integer not greater than the year divided by 100.
--
--          This format is a POSIX.2 extension.
--
--    `%d'
--          The day of the month as a decimal number (range `01' through
--          `31').
--
--    `%D'
--          The date using the format `%m/%d/%y'.
--
--          This format is a POSIX.2 extension.
--
--    `%e'
--          The day of the month like with `%d', but padded with blank
--          (range ` 1' through `31').
--
--          This format is a POSIX.2 extension.
--
--    `%g'
--          The year corresponding to the ISO week number, but without
--          the century (range `00' through `99').  This has the same
--          format and value as `%y', except that if the ISO week number
--          (see `%V') belongs to the previous or next year, that year is
--          used instead.
--
--          This format is a GNU extension.
--
--    `%G'
--          The year corresponding to the ISO week number.  This has the
--          same format and value as `%Y', except that if the ISO week
--          number (see `%V') belongs to the previous or next year, that
--          year is used instead.
--
--          This format is a GNU extension.
--
--    `%h'
--          The abbreviated month name according to the current locale.
--          The action is the same as for `%b'.
--
--          This format is a POSIX.2 extension.
--
--    `%H'
--          The hour as a decimal number, using a 24-hour clock (range
--          `00' through `23').
--
--    `%I'
--          The hour as a decimal number, using a 12-hour clock (range
--          `01' through `12').
--
--    `%j'
--          The day of the year as a decimal number (range `001' through
--          `366').
--
--    `%k'
--          The hour as a decimal number, using a 24-hour clock like
--          `%H', but padded with blank (range ` 0' through `23').
--
--          This format is a GNU extension.
--
--    `%l'
--          The hour as a decimal number, using a 12-hour clock like
--          `%I', but padded with blank (range ` 1' through `12').
--
--          This format is a GNU extension.
--
--    `%m'
--          The month as a decimal number (range `01' through `12').
--
--    `%M'
--          The minute as a decimal number (range `00' through `59').
--
--    `%n'
--          A single `\n' (newline) character.
--
--          This format is a POSIX.2 extension.
--
--    `%p'
--          Either `AM' or `PM', according to the given time value; or the
--          corresponding strings for the current locale.  Noon is
--          treated as `PM' and midnight as `AM'.
--
--    `%P'
--          Either `am' or `pm', according to the given time value; or the
--          corresponding strings for the current locale, printed in
--          lowercase characters.  Noon is treated as `pm' and midnight
--          as `am'.
--
--          This format is a GNU extension.
--
--    `%r'
--          The complete time using the AM/PM format of the current
--          locale.
--
--          This format is a POSIX.2 extension.
--
--    `%R'
--          The hour and minute in decimal numbers using the format
--          `%H:%M'.
--
--          This format is a GNU extension.
--
--    `%s'
--          The number of seconds since the epoch, i.e., since 1970-01-01
--          00:00:00 UTC.  Leap seconds are not counted unless leap
--          second support is available.
--
--          This format is a GNU extension.
--
--    `%S'
--          The second as a decimal number (range `00' through `60').
--
--    `%t'
--          A single `\t' (tabulator) character.
--
--          This format is a POSIX.2 extension.
--
--    `%T'
--          The time using decimal numbers using the format `%H:%M:%S'.
--
--          This format is a POSIX.2 extension.
--
--    `%u'
--          The day of the week as a decimal number (range `1' through
--          `7'), Monday being `1'.
--
--          This format is a POSIX.2 extension.
--
--    `%U'
--          The week number of the current year as a decimal number
--          (range `00' through `53'), starting with the first Sunday as
--          the first day of the first week.  Days preceding the first
--          Sunday in the year are considered to be in week `00'.
--
--    `%V'
--          The ISO 8601:1988 week number as a decimal number (range `01'
--          through `53').  ISO weeks start with Monday and end with
--          Sunday.  Week `01' of a year is the first week which has the
--          majority of its days in that year; this is equivalent to the
--          week containing the year's first Thursday, and it is also
--          equivalent to the week containing January 4.  Week `01' of a
--          year can contain days from the previous year.  The week
--          before week `01' of a year is the last week (`52' or `53') of
--          the previous year even if it contains days from the new year.
--
--          This format is a POSIX.2 extension.
--
--    `%w'
--          The day of the week as a decimal number (range `0' through
--          `6'), Sunday being `0'.
--
--    `%W'
--          The week number of the current year as a decimal number
--          (range `00' through `53'), starting with the first Monday as
--          the first day of the first week.  All days preceding the
--          first Monday in the year are considered to be in week `00'.
--
--    `%x'
--          The preferred date representation for the current locale, but
--          without the time.
--
--    `%X'
--          The preferred time representation for the current locale, but
--          with no date.
--
--    `%y'
--          The year without a century as a decimal number (range `00'
--          through `99').  This is equivalent to the year modulo 100.
--
--    `%Y'
--          The year as a decimal number, using the Gregorian calendar.
--          Years before the year `1' are numbered `0', `-1', and so on.
--
--    `%z'
--          RFC 822/ISO 8601:1988 style numeric time zone (e.g., `-0600'
--          or `+0100'), or nothing if no time zone is determinable.
--
--          This format is a GNU extension.
--
--    `%Z'
--          The time zone abbreviation (empty if the time zone can't be
--          determined).
--
--    `%%'
--          A literal `%' character.
--
--     The SIZE parameter can be used to specify the maximum number of
--     characters to be stored in the array S, including the terminating
--     null character.  If the formatted time requires more than SIZE
--     characters, the excess characters are discarded.  The return value
--     from `strftime' is the number of characters placed in the array S,
--     not including the terminating null character.  If the value equals
--     SIZE, it means that the array S was too small; you should repeat
--     the call, providing a bigger array.
--
--     If S is a null pointer, `strftime' does not actually write
--     anything, but instead returns the number of characters it would
--     have written.
--
--     According to POSIX.1 every call to `strftime' implies a call to
--     `tzset'.  So the contents of the environment variable `TZ' is
--     examined before any output is produced.
--
--     For an example of `strftime', see *Note Time Functions Example::.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-18 
glibc-2.0.1/manual/libc.info-18
---- ../glibc-2.0.1/manual/libc.info-18 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-18    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1165 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: TZ Variable,  Next: Time Zone Functions,  Prev: 
Formatting Date and Time,  Up: Calendar Time
--
--Specifying the Time Zone with `TZ'
------------------------------------
--
--   In POSIX systems, a user can specify the time zone by means of the
--`TZ' environment variable.  For information about how to set
--environment variables, see *Note Environment Variables::.  The functions
--for accessing the time zone are declared in `time.h'.
--
--   You should not normally need to set `TZ'.  If the system is
--configured properly, the default time zone will be correct.  You might
--set `TZ' if you are using a computer over the network from a different
--time zone, and would like times reported to you in the time zone that
--local for you, rather than what is local for the computer.
--
--   In POSIX.1 systems the value of the `TZ' variable can be of one of
--three formats.  With the GNU C library, the most common format is the
--last one, which can specify a selection from a large database of time
--zone information for many regions of the world.  The first two formats
--are used to describe the time zone information directly, which is both
--more cumbersome and less precise.  But the POSIX.1 standard only
--specifies the details of the first two formats, so it is good to be
--familiar with them in case you come across a POSIX.1 system that doesn't
--support a time zone information database.
--
--   The first format is used when there is no Daylight Saving Time (or
--summer time) in the local time zone:
--
--     STD OFFSET
--
--   The STD string specifies the name of the time zone.  It must be
--three or more characters long and must not contain a leading colon or
--embedded digits, commas, or plus or minus signs.  There is no space
--character separating the time zone name from the OFFSET, so these
--restrictions are necessary to parse the specification correctly.
--
--   The OFFSET specifies the time value one must add to the local time
--to get a Coordinated Universal Time value.  It has syntax like
--[`+'|`-']HH[`:'MM[`:'SS]].  This is positive if the local time zone is
--west of the Prime Meridian and negative if it is east.  The hour must
--be between `0' and `23', and the minute and seconds between `0' and
--`59'.
--
--   For example, here is how we would specify Eastern Standard Time, but
--without any daylight saving time alternative:
--
--     EST+5
--
--   The second format is used when there is Daylight Saving Time:
--
--     STD OFFSET DST [OFFSET]`,'START[`/'TIME]`,'END[`/'TIME]
--
--   The initial STD and OFFSET specify the standard time zone, as
--described above.  The DST string and OFFSET specify the name and offset
--for the corresponding daylight saving time time zone; if the OFFSET is
--omitted, it defaults to one hour ahead of standard time.
--
--   The remainder of the specification describes when daylight saving
--time is in effect.  The START field is when daylight saving time goes
--into effect and the END field is when the change is made back to
--standard time.  The following formats are recognized for these fields:
--
--`JN'
--     This specifies the Julian day, with N between `1' and `365'.
--     February 29 is never counted, even in leap years.
--
--`N'
--     This specifies the Julian day, with N between `0' and `365'.
--     February 29 is counted in leap years.
--
--`MM.W.D'
--     This specifies day D of week W of month M.  The day D must be
--     between `0' (Sunday) and `6'.  The week W must be between `1' and
--     `5'; week `1' is the first week in which day D occurs, and week
--     `5' specifies the *last* D day in the month.  The month M should be
--     between `1' and `12'.
--
--   The TIME fields specify when, in the local time currently in effect,
--the change to the other time occurs.  If omitted, the default is
--`02:00:00'.
--
--   For example, here is how one would specify the Eastern time zone in
--the United States, including the appropriate daylight saving time and
--its dates of applicability.  The normal offset from UTC is 5 hours;
--since this is west of the prime meridian, the sign is positive.  Summer
--time begins on the first Sunday in April at 2:00am, and ends on the
--last Sunday in October at 2:00am.
--
--     EST+5EDT,M4.1.0/2,M10.5.0/2
--
--   The schedule of daylight saving time in any particular jurisdiction
--has changed over the years.  To be strictly correct, the conversion of
--dates and times in the past should be based on the schedule that was in
--effect then.  However, this format has no facilities to let you specify
--how the schedule has changed from year to year.  The most you can do is
--specify one particular schedule--usually the present day schedule--and
--this is used to convert any date, no matter when.  For precise time zone
--specifications, it is best to use the time zone information database
--(see below).
--
--   The third format looks like this:
--
--     :CHARACTERS
--
--   Each operating system interprets this format differently; in the GNU
--C library, CHARACTERS is the name of a file which describes the time
--zone.
--
--   If the `TZ' environment variable does not have a value, the
--operation chooses a time zone by default.  In the GNU C library, the
--default time zone is like the specification `TZ=:/etc/localtime' (or
--`TZ=:/usr/local/etc/localtime', depending on how GNU C library was
--configured; *note Installation::.).  Other C libraries use their own
--rule for choosing the default time zone, so there is little we can say
--about them.
--
--   If CHARACTERS begins with a slash, it is an absolute file name;
--otherwise the library looks for the file
--`/share/lib/zoneinfo/CHARACTERS'.  The `zoneinfo' directory contains
--data files describing local time zones in many different parts of the
--world.  The names represent major cities, with subdirectories for
--geographical areas; for example, `America/New_York', `Europe/London',
--`Asia/Hong_Kong'.  These data files are installed by the system
--administrator, who also sets `/etc/localtime' to point to the data file
--for the local time zone.  The GNU C library comes with a large database
--of time zone information for most regions of the world, which is
--maintained by a community of volunteers and put in the public domain.
--
--
--File: libc.info,  Node: Time Zone Functions,  Next: Time Functions Example,  
Prev: TZ Variable,  Up: Calendar Time
--
--Functions and Variables for Time Zones
----------------------------------------
--
-- - Variable: char * tzname
--     The array `tzname' contains two strings, which are the standard
--     names of the pair of time zones (standard and daylight saving)
--     that the user has selected.  `tzname[0]' is the name of the
--     standard time zone (for example, `"EST"'), and `tzname[1]' is the
--     name for the time zone when daylight saving time is in use (for
--     example, `"EDT"').  These correspond to the STD and DST strings
--     (respectively) from the `TZ' environment variable.  If daylight
--     saving time is never used, `tzname[1]' is the empty string.
--
--     The `tzname' array is initialized from the `TZ' environment
--     variable whenever `tzset', `ctime', `strftime', `mktime', or
--     `localtime' is called.  If multiple abbreviations have been used
--     (e.g. `"EWT"' and `"EDT"' for U.S. Eastern War Time and Eastern
--     Daylight Time), the array contains the most recent abbreviation.
--
--     The `tzname' array is required for POSIX.1 compatibility, but in
--     GNU programs it is better to use the `tm_zone' member of the
--     broken-down time structure, since `tm_zone' reports the correct
--     abbreviation even when it is not the latest one.
--
--
-- - Function: void tzset (void)
--     The `tzset' function initializes the `tzname' variable from the
--     value of the `TZ' environment variable.  It is not usually
--     necessary for your program to call this function, because it is
--     called automatically when you use the other time conversion
--     functions that depend on the time zone.
--
--   The following variables are defined for compatibility with System V
--Unix.  Like `tzname', these variables are set by calling `tzset' or the
--other time conversion functions.
--
-- - Variable: long int timezone
--     This contains the difference between UTC and the latest local
--     standard time, in seconds west of UTC.  For example, in the U.S.
--     Eastern time zone, the value is `5*60*60'.  Unlike the `tm_gmtoff'
--     member of the broken-down time structure, this value is not
--     adjusted for daylight saving, and its sign is reversed.  In GNU
--     programs it is better to use `tm_gmtoff', since it contains the
--     correct offset even when it is not the latest one.
--
-- - Variable: int daylight
--     This variable has a nonzero value if daylight savings time rules
--     apply.  A nonzero value does not necessarily mean that daylight
--     savings time is now in effect; it means only that daylight savings
--     time is sometimes in effect.
--
--
--File: libc.info,  Node: Time Functions Example,  Prev: Time Zone Functions,  
Up: Calendar Time
--
--Time Functions Example
------------------------
--
--   Here is an example program showing the use of some of the local time
--and calendar time functions.
--
--     #include <time.h>
--     #include <stdio.h>
--     
--     #define SIZE 256
--     
--     int
--     main (void)
--     {
--       char buffer[SIZE];
--       time_t curtime;
--       struct tm *loctime;
--     
--       /* Get the current time. */
--       curtime = time (NULL);
--     
--       /* Convert it to local time representation. */
--       loctime = localtime (&curtime);
--     
--       /* Print out the date and time in the standard format. */
--       fputs (asctime (loctime), stdout);
--     /* Print it out in a nice format. */
--       strftime (buffer, SIZE, "Today is %A, %B %d.\n", loctime);
--       fputs (buffer, stdout);
--       strftime (buffer, SIZE, "The time is %I:%M %p.\n", loctime);
--       fputs (buffer, stdout);
--     
--       return 0;
--     }
--
--   It produces output like this:
--
--     Wed Jul 31 13:02:36 1991
--     Today is Wednesday, July 31.
--     The time is 01:02 PM.
--
--
--File: libc.info,  Node: Setting an Alarm,  Next: Sleeping,  Prev: Calendar 
Time,  Up: Date and Time
--
--Setting an Alarm
--================
--
--   The `alarm' and `setitimer' functions provide a mechanism for a
--process to interrupt itself at some future time.  They do this by
--setting a timer; when the timer expires, the process receives a signal.
--
--   Each process has three independent interval timers available:
--
--   * A real-time timer that counts clock time.  This timer sends a
--     `SIGALRM' signal to the process when it expires.
--
--   * A virtual timer that counts CPU time used by the process.  This
--     timer sends a `SIGVTALRM' signal to the process when it expires.
--
--   * A profiling timer that counts both CPU time used by the process,
--     and CPU time spent in system calls on behalf of the process.  This
--     timer sends a `SIGPROF' signal to the process when it expires.
--
--     This timer is useful for profiling in interpreters.  The interval
--     timer mechanism does not have the fine granularity necessary for
--     profiling native code.
--
--   You can only have one timer of each kind set at any given time.  If
--you set a timer that has not yet expired, that timer is simply reset to
--the new value.
--
--   You should establish a handler for the appropriate alarm signal using
--`signal' or `sigaction' before issuing a call to `setitimer' or
--`alarm'.  Otherwise, an unusual chain of events could cause the timer
--to expire before your program establishes the handler, and in that case
--it would be terminated, since that is the default action for the alarm
--signals.  *Note Signal Handling::.
--
--   The `setitimer' function is the primary means for setting an alarm.
--This facility is declared in the header file `sys/time.h'.  The `alarm'
--function, declared in `unistd.h', provides a somewhat simpler interface
--for setting the real-time timer.
--
-- - Data Type: struct itimerval
--     This structure is used to specify when a timer should expire.  It
--     contains the following members:
--    `struct timeval it_interval'
--          This is the interval between successive timer interrupts.  If
--          zero, the alarm will only be sent once.
--
--    `struct timeval it_value'
--          This is the interval to the first timer interrupt.  If zero,
--          the alarm is disabled.
--
--     The `struct timeval' data type is described in *Note
--     High-Resolution Calendar::.
--
-- - Function: int setitimer (int WHICH, struct itimerval *NEW, struct
--          itimerval *OLD)
--     The `setitimer' function sets the timer specified by WHICH
--     according to NEW.  The WHICH argument can have a value of
--     `ITIMER_REAL', `ITIMER_VIRTUAL', or `ITIMER_PROF'.
--
--     If OLD is not a null pointer, `setitimer' returns information
--     about any previous unexpired timer of the same kind in the
--     structure it points to.
--
--     The return value is `0' on success and `-1' on failure.  The
--     following `errno' error conditions are defined for this function:
--
--    `EINVAL'
--          The timer interval was too large.
--
-- - Function: int getitimer (int WHICH, struct itimerval *OLD)
--     The `getitimer' function stores information about the timer
--     specified by WHICH in the structure pointed at by OLD.
--
--     The return value and error conditions are the same as for
--     `setitimer'.
--
--`ITIMER_REAL'
--     This constant can be used as the WHICH argument to the `setitimer'
--     and `getitimer' functions to specify the real-time timer.
--
--`ITIMER_VIRTUAL'
--     This constant can be used as the WHICH argument to the `setitimer'
--     and `getitimer' functions to specify the virtual timer.
--
--`ITIMER_PROF'
--     This constant can be used as the WHICH argument to the `setitimer'
--     and `getitimer' functions to specify the profiling timer.
--
-- - Function: unsigned int alarm (unsigned int SECONDS)
--     The `alarm' function sets the real-time timer to expire in SECONDS
--     seconds.  If you want to cancel any existing alarm, you can do
--     this by calling `alarm' with a SECONDS argument of zero.
--
--     The return value indicates how many seconds remain before the
--     previous alarm would have been sent.  If there is no previous
--     alarm, `alarm' returns zero.
--
--   The `alarm' function could be defined in terms of `setitimer' like
--this:
--
--     unsigned int
--     alarm (unsigned int seconds)
--     {
--       struct itimerval old, new;
--       new.it_interval.tv_usec = 0;
--       new.it_interval.tv_sec = 0;
--       new.it_value.tv_usec = 0;
--       new.it_value.tv_sec = (long int) seconds;
--       if (setitimer (ITIMER_REAL, &new, &old) < 0)
--         return 0;
--       else
--         return old.it_value.tv_sec;
--     }
--
--   There is an example showing the use of the `alarm' function in *Note
--Handler Returns::.
--
--   If you simply want your process to wait for a given number of
--seconds, you should use the `sleep' function.  *Note Sleeping::.
--
--   You shouldn't count on the signal arriving precisely when the timer
--expires.  In a multiprocessing environment there is typically some
--amount of delay involved.
--
--   *Portability Note:* The `setitimer' and `getitimer' functions are
--derived from BSD Unix, while the `alarm' function is specified by the
--POSIX.1 standard.  `setitimer' is more powerful than `alarm', but
--`alarm' is more widely used.
--
--
--File: libc.info,  Node: Sleeping,  Next: Resource Usage,  Prev: Setting an 
Alarm,  Up: Date and Time
--
--Sleeping
--========
--
--   The function `sleep' gives a simple way to make the program wait for
--short periods of time.  If your program doesn't use signals (except to
--terminate), then you can expect `sleep' to wait reliably for the
--specified amount of time.  Otherwise, `sleep' can return sooner if a
--signal arrives; if you want to wait for a given period regardless of
--signals, use `select' (*note Waiting for I/O::.) and don't specify any
--descriptors to wait for.
--
-- - Function: unsigned int sleep (unsigned int SECONDS)
--     The `sleep' function waits for SECONDS or until a signal is
--     delivered, whichever happens first.
--
--     If `sleep' function returns because the requested time has
--     elapsed, it returns a value of zero.  If it returns because of
--     delivery of a signal, its return value is the remaining time in
--     the sleep period.
--
--     The `sleep' function is declared in `unistd.h'.
--
--   Resist the temptation to implement a sleep for a fixed amount of
--time by using the return value of `sleep', when nonzero, to call
--`sleep' again.  This will work with a certain amount of accuracy as
--long as signals arrive infrequently.  But each signal can cause the
--eventual wakeup time to be off by an additional second or so.  Suppose a
--few signals happen to arrive in rapid succession by bad luck--there is
--no limit on how much this could shorten or lengthen the wait.
--
--   Instead, compute the time at which the program should stop waiting,
--and keep trying to wait until that time.  This won't be off by more
--than a second.  With just a little more work, you can use `select' and
--make the waiting period quite accurate.  (Of course, heavy system load
--can cause unavoidable additional delays--unless the machine is
--dedicated to one application, there is no way you can avoid this.)
--
--   On some systems, `sleep' can do strange things if your program uses
--`SIGALRM' explicitly.  Even if `SIGALRM' signals are being ignored or
--blocked when `sleep' is called, `sleep' might return prematurely on
--delivery of a `SIGALRM' signal.  If you have established a handler for
--`SIGALRM' signals and a `SIGALRM' signal is delivered while the process
--is sleeping, the action taken might be just to cause `sleep' to return
--instead of invoking your handler.  And, if `sleep' is interrupted by
--delivery of a signal whose handler requests an alarm or alters the
--handling of `SIGALRM', this handler and `sleep' will interfere.
--
--   On the GNU system, it is safe to use `sleep' and `SIGALRM' in the
--same program, because `sleep' does not work by means of `SIGALRM'.
--
--
--File: libc.info,  Node: Resource Usage,  Next: Limits on Resources,  Prev: 
Sleeping,  Up: Date and Time
--
--Resource Usage
--==============
--
--   The function `getrusage' and the data type `struct rusage' are used
--for examining the usage figures of a process.  They are declared in
--`sys/resource.h'.
--
-- - Function: int getrusage (int PROCESSES, struct rusage *RUSAGE)
--     This function reports the usage totals for processes specified by
--     PROCESSES, storing the information in `*RUSAGE'.
--
--     In most systems, PROCESSES has only two valid values:
--
--    `RUSAGE_SELF'
--          Just the current process.
--
--    `RUSAGE_CHILDREN'
--          All child processes (direct and indirect) that have
--          terminated already.
--
--     In the GNU system, you can also inquire about a particular child
--     process by specifying its process ID.
--
--     The return value of `getrusage' is zero for success, and `-1' for
--     failure.
--
--    `EINVAL'
--          The argument PROCESSES is not valid.
--
--   One way of getting usage figures for a particular child process is
--with the function `wait4', which returns totals for a child when it
--terminates.  *Note BSD Wait Functions::.
--
-- - Data Type: struct rusage
--     This data type records a collection usage amounts for various
--     sorts of resources.  It has the following members, and possibly
--     others:
--
--    `struct timeval ru_utime'
--          Time spent executing user instructions.
--
--    `struct timeval ru_stime'
--          Time spent in operating system code on behalf of PROCESSES.
--
--    `long int ru_maxrss'
--          The maximum resident set size used, in kilobytes.  That is,
--          the maximum number of kilobytes that PROCESSES used in real
--          memory simultaneously.
--
--    `long int ru_ixrss'
--          An integral value expressed in kilobytes times ticks of
--          execution, which indicates the amount of memory used by text
--          that was shared with other processes.
--
--    `long int ru_idrss'
--          An integral value expressed the same way, which is the amount
--          of unshared memory used in data.
--
--    `long int ru_isrss'
--          An integral value expressed the same way, which is the amount
--          of unshared memory used in stack space.
--
--    `long int ru_minflt'
--          The number of page faults which were serviced without
--          requiring any I/O.
--
--    `long int ru_majflt'
--          The number of page faults which were serviced by doing I/O.
--
--    `long int ru_nswap'
--          The number of times PROCESSES was swapped entirely out of
--          main memory.
--
--    `long int ru_inblock'
--          The number of times the file system had to read from the disk
--          on behalf of PROCESSES.
--
--    `long int ru_oublock'
--          The number of times the file system had to write to the disk
--          on behalf of PROCESSES.
--
--    `long int ru_msgsnd'
--          Number of IPC messages sent.
--
--    `long ru_msgrcv'
--          Number of IPC messages received.
--
--    `long int ru_nsignals'
--          Number of signals received.
--
--    `long int ru_nvcsw'
--          The number of times PROCESSES voluntarily invoked a context
--          switch (usually to wait for some service).
--
--    `long int ru_nivcsw'
--          The number of times an involuntary context switch took place
--          (because the time slice expired, or another process of higher
--          priority became runnable).
--
--   An additional historical function for examining usage figures,
--`vtimes', is supported but not documented here.  It is declared in
--`sys/vtimes.h'.
--
--
--File: libc.info,  Node: Limits on Resources,  Next: Priority,  Prev: Resource 
Usage,  Up: Date and Time
--
--Limiting Resource Usage
--=======================
--
--   You can specify limits for the resource usage of a process.  When the
--process tries to exceed a limit, it may get a signal, or the system call
--by which it tried to do so may fail, depending on the limit.  Each
--process initially inherits its limit values from its parent, but it can
--subsequently change them.
--
--   The symbols in this section are defined in `sys/resource.h'.
--
-- - Function: int getrlimit (int RESOURCE, struct rlimit *RLP)
--     Read the current value and the maximum value of resource RESOURCE
--     and store them in `*RLP'.
--
--     The return value is `0' on success and `-1' on failure.  The only
--     possible `errno' error condition is `EFAULT'.
--
-- - Function: int setrlimit (int RESOURCE, struct rlimit *RLP)
--     Store the current value and the maximum value of resource RESOURCE
--     in `*RLP'.
--
--     The return value is `0' on success and `-1' on failure.  The
--     following `errno' error condition is possible:
--
--    `EPERM'
--          You tried to change the maximum permissible limit value, but
--          you don't have privileges to do so.
--
-- - Data Type: struct rlimit
--     This structure is used with `getrlimit' to receive limit values,
--     and with `setrlimit' to specify limit values.  It has two fields:
--
--    `rlim_cur'
--          The current value of the limit in question.  This is also
--          called the "soft limit".
--
--    `rlim_max'
--          The maximum permissible value of the limit in question.  You
--          cannot set the current value of the limit to a larger number
--          than this maximum.  Only the super user can change the
--          maximum permissible value.  This is also called the "hard
--          limit".
--
--     In `getrlimit', the structure is an output; it receives the current
--     values.  In `setrlimit', it specifies the new values.
--
--   Here is a list of resources that you can specify a limit for.  Those
--that are sizes are measured in bytes.
--
--`RLIMIT_CPU'
--     The maximum amount of cpu time the process can use.  If it runs for
--     longer than this, it gets a signal: `SIGXCPU'.  The value is
--     measured in seconds.  *Note Operation Error Signals::.
--
--`RLIMIT_FSIZE'
--     The maximum size of file the process can create.  Trying to write a
--     larger file causes a signal: `SIGXFSZ'.  *Note Operation Error
--     Signals::.
--
--`RLIMIT_DATA'
--     The maximum size of data memory for the process.  If the process
--     tries to allocate data memory beyond this amount, the allocation
--     function fails.
--
--`RLIMIT_STACK'
--     The maximum stack size for the process.  If the process tries to
--     extend its stack past this size, it gets a `SIGSEGV' signal.
--     *Note Program Error Signals::.
--
--`RLIMIT_CORE'
--     The maximum size core file that this process can create.  If the
--     process terminates and would dump a core file larger than this
--     maximum size, then no core file is created.  So setting this limit
--     to zero prevents core files from ever being created.
--
--`RLIMIT_RSS'
--     The maximum amount of physical memory that this process should get.
--     This parameter is a guide for the system's scheduler and memory
--     allocator; the system may give the process more memory when there
--     is a surplus.
--
--`RLIMIT_MEMLOCK'
--     The maximum amount of memory that can be locked into physical
--     memory (so it will never be paged out).
--
--`RLIMIT_NPROC'
--     The maximum number of processes that can be created with the same
--     user ID.  If you have reached the limit for your user ID, `fork'
--     will fail with `EAGAIN'.  *Note Creating a Process::.
--
--`RLIMIT_NOFILE'
--`RLIMIT_OFILE'
--     The maximum number of files that the process can open.  If it
--     tries to open more files than this, it gets error code `EMFILE'.
--     *Note Error Codes::.  Not all systems support this limit; GNU
--     does, and 4.4 BSD does.
--
--`RLIM_NLIMITS'
--     The number of different resource limits.  Any valid RESOURCE
--     operand must be less than `RLIM_NLIMITS'.
--
-- - Constant: int
--     This constant stands for a value of "infinity" when supplied as
--     the limit value in `setrlimit'.
--
--   Two historical functions for setting resource limits, `ulimit' and
--`vlimit', are not documented here.  The latter is declared in
--`sys/vlimit.h' and comes from BSD.
--
--
--File: libc.info,  Node: Priority,  Prev: Limits on Resources,  Up: Date and 
Time
--
--Process Priority
--================
--
--   When several processes try to run, their respective priorities
--determine what share of the CPU each process gets.  This section
--describes how you can read and set the priority of a process.  All
--these functions and macros are declared in `sys/resource.h'.
--
--   The range of valid priority values depends on the operating system,
--but typically it runs from `-20' to `20'.  A lower priority value means
--the process runs more often.  These constants describe the range of
--priority values:
--
--`PRIO_MIN'
--     The smallest valid priority value.
--
--`PRIO_MAX'
--     The smallest valid priority value.
--
-- - Function: int getpriority (int CLASS, int ID)
--     Read the priority of a class of processes; CLASS and ID specify
--     which ones (see below).  If the processes specified do not all
--     have the same priority, this returns the smallest value that any
--     of them has.
--
--     The return value is the priority value on success, and `-1' on
--     failure.  The following `errno' error condition are possible for
--     this function:
--
--    `ESRCH'
--          The combination of CLASS and ID does not match any existing
--          process.
--
--    `EINVAL'
--          The value of CLASS is not valid.
--
--     When the return value is `-1', it could indicate failure, or it
--     could be the priority value.  The only way to make certain is to
--     set `errno = 0' before calling `getpriority', then use `errno !=
--     0' afterward as the criterion for failure.
--
-- - Function: int setpriority (int CLASS, int ID, int PRIORITY)
--     Set the priority of a class of processes to PRIORITY; CLASS and ID
--     specify which ones (see below).
--
--     The return value is `0' on success and `-1' on failure.  The
--     following `errno' error condition are defined for this function:
--
--    `ESRCH'
--          The combination of CLASS and ID does not match any existing
--          process.
--
--    `EINVAL'
--          The value of CLASS is not valid.
--
--    `EPERM'
--          You tried to set the priority of some other user's process,
--          and you don't have privileges for that.
--
--    `EACCES'
--          You tried to lower the priority of a process, and you don't
--          have privileges for that.
--
--   The arguments CLASS and ID together specify a set of processes you
--are interested in.  These are the possible values for CLASS:
--
--`PRIO_PROCESS'
--     Read or set the priority of one process.  The argument ID is a
--     process ID.
--
--`PRIO_PGRP'
--     Read or set the priority of one process group.  The argument ID is
--     a process group ID.
--
--`PRIO_USER'
--     Read or set the priority of one user's processes.  The argument ID
--     is a user ID.
--
--   If the argument ID is 0, it stands for the current process, current
--process group, or the current user, according to CLASS.
--
-- - Function: int nice (int INCREMENT)
--     Increment the priority of the current process by INCREMENT.  The
--     return value is the same as for `setpriority'.
--
--     Here is an equivalent definition for `nice':
--
--          int
--          nice (int increment)
--          {
--            int old = getpriority (PRIO_PROCESS, 0);
--            return setpriority (PRIO_PROCESS, 0, old + increment);
--          }
--
--
--File: libc.info,  Node: Extended Characters,  Next: Locales,  Prev: String 
and Array Utilities,  Up: Top
--
--Extended Characters
--*******************
--
--   A number of languages use character sets that are larger than the
--range of values of type `char'.  Japanese and Chinese are probably the
--most familiar examples.
--
--   The GNU C library includes support for two mechanisms for dealing
--with extended character sets: multibyte characters and wide characters.
--This chapter describes how to use these mechanisms, and the functions
--for converting between them.
--
--   The behavior of the functions in this chapter is affected by the
--current locale for character classification--the `LC_CTYPE' category;
--see *Note Locale Categories::.  This choice of locale selects which
--multibyte code is used, and also controls the meanings and
--characteristics of wide character codes.
--
--* Menu:
--
--* Extended Char Intro::         Multibyte codes versus wide characters.
--* Locales and Extended Chars::  The locale selects the character codes.
--* Multibyte Char Intro::        How multibyte codes are represented.
--* Wide Char Intro::             How wide characters are represented.
--* Wide String Conversion::      Converting wide strings to multibyte code
--                                 and vice versa.
--* Length of Char::              how many bytes make up one multibyte char.
--* Converting One Char::         Converting a string character by character.
--* Example of Conversion::       Example showing why converting
--                               one character at a time may be useful.
--* Shift State::                 Multibyte codes with "shift characters".
--
--
--File: libc.info,  Node: Extended Char Intro,  Next: Locales and Extended 
Chars,  Up: Extended Characters
--
--Introduction to Extended Characters
--===================================
--
--   You can represent extended characters in either of two ways:
--
--   * As "multibyte characters" which can be embedded in an ordinary
--     string, an array of `char' objects.  Their advantage is that many
--     programs and operating systems can handle occasional multibyte
--     characters scattered among ordinary ASCII characters, without any
--     change.
--
--   * As "wide characters", which are like ordinary characters except
--     that they occupy more bits.  The wide character data type,
--     `wchar_t', has a range large enough to hold extended character
--     codes as well as old-fashioned ASCII codes.
--
--     An advantage of wide characters is that each character is a single
--     data object, just like ordinary ASCII characters.  There are a few
--     disadvantages:
--
--        * Each existing program must be modified and recompiled to make
--          it use wide characters.
--
--        * Files of wide characters cannot be read by programs that
--          expect ordinary characters.
--
--   Typically, you use the multibyte character representation as part of
--the external program interface, such as reading or writing text to
--files.  However, it's usually easier to perform internal manipulations
--on strings containing extended characters on arrays of `wchar_t'
--objects, since the uniform representation makes most editing operations
--easier.  If you do use multibyte characters for files and wide
--characters for internal operations, you need to convert between them
--when you read and write data.
--
--   If your system supports extended characters, then it supports them
--both as multibyte characters and as wide characters.  The library
--includes functions you can use to convert between the two
--representations.  These functions are described in this chapter.
--
--
--File: libc.info,  Node: Locales and Extended Chars,  Next: Multibyte Char 
Intro,  Prev: Extended Char Intro,  Up: Extended Characters
--
--Locales and Extended Characters
--===============================
--
--   A computer system can support more than one multibyte character code,
--and more than one wide character code.  The user controls the choice of
--codes through the current locale for character classification (*note
--Locales::.).  Each locale specifies a particular multibyte character
--code and a particular wide character code.  The choice of locale
--influences the behavior of the conversion functions in the library.
--
--   Some locales support neither wide characters nor nontrivial multibyte
--characters.  In these locales, the library conversion functions still
--work, even though what they do is basically trivial.
--
--   If you select a new locale for character classification, the internal
--shift state maintained by these functions can become confused, so it's
--not a good idea to change the locale while you are in the middle of
--processing a string.
--
--
--File: libc.info,  Node: Multibyte Char Intro,  Next: Wide Char Intro,  Prev: 
Locales and Extended Chars,  Up: Extended Characters
--
--Multibyte Characters
--====================
--
--   In the ordinary ASCII code, a sequence of characters is a sequence of
--bytes, and each character is one byte.  This is very simple, but allows
--for only 256 distinct characters.
--
--   In a "multibyte character code", a sequence of characters is a
--sequence of bytes, but each character may occupy one or more consecutive
--bytes of the sequence.
--
--   There are many different ways of designing a multibyte character
--code; different systems use different codes.  To specify a particular
--code means designating the "basic" byte sequences--those which represent
--a single character--and what characters they stand for.  A code that a
--computer can actually use must have a finite number of these basic
--sequences, and typically none of them is more than a few characters
--long.
--
--   These sequences need not all have the same length.  In fact, many of
--them are just one byte long.  Because the basic ASCII characters in the
--range from `0' to `0177' are so important, they stand for themselves in
--all multibyte character codes.  That is to say, a byte whose value is
--`0' through `0177' is always a character in itself.  The characters
--which are more than one byte must always start with a byte in the range
--from `0200' through `0377'.
--
--   The byte value `0' can be used to terminate a string, just as it is
--often used in a string of ASCII characters.
--
--   Specifying the basic byte sequences that represent single characters
--automatically gives meanings to many longer byte sequences, as more than
--one character.  For example, if the two byte sequence `0205 049' stands
--for the Greek letter alpha, then `0205 049 065' must stand for an alpha
--followed by an `A' (ASCII code 065), and `0205 049 0205 049' must stand
--for two alphas in a row.
--
--   If any byte sequence can have more than one meaning as a sequence of
--characters, then the multibyte code is ambiguous--and no good.  The
--codes that systems actually use are all unambiguous.
--
--   In most codes, there are certain sequences of bytes that have no
--meaning as a character or characters.  These are called "invalid".
--
--   The simplest possible multibyte code is a trivial one:
--
--     The basic sequences consist of single bytes.
--
--   This particular code is equivalent to not using multibyte characters
--at all.  It has no invalid sequences.  But it can handle only 256
--different characters.
--
--   Here is another possible code which can handle 9376 different
--characters:
--
--     The basic sequences consist of
--
--        * single bytes with values in the range `0' through `0237'.
--
--        * two-byte sequences, in which both of the bytes have values in
--          the range from `0240' through `0377'.
--
--This code or a similar one is used on some systems to represent Japanese
--characters.  The invalid sequences are those which consist of an odd
--number of consecutive bytes in the range from `0240' through `0377'.
--
--   Here is another multibyte code which can handle more distinct
--extended characters--in fact, almost thirty million:
--
--     The basic sequences consist of
--
--        * single bytes with values in the range `0' through `0177'.
--
--        * sequences of up to four bytes in which the first byte is in
--          the range from `0200' through `0237', and the remaining bytes
--          are in the range from `0240' through `0377'.
--
--In this code, any sequence that starts with a byte in the range from
--`0240' through `0377' is invalid.
--
--   And here is another variant which has the advantage that removing the
--last byte or bytes from a valid character can never produce another
--valid character.  (This property is convenient when you want to search
--strings for particular characters.)
--
--     The basic sequences consist of
--
--        * single bytes with values in the range `0' through `0177'.
--
--        * two-byte sequences in which the first byte is in the range
--          from `0200' through `0207', and the second byte is in the
--          range from `0240' through `0377'.
--
--        * three-byte sequences in which the first byte is in the range
--          from `0210' through `0217', and the other bytes are in the
--          range from `0240' through `0377'.
--
--        * four-byte sequences in which the first byte is in the range
--          from `0220' through `0227', and the other bytes are in the
--          range from `0240' through `0377'.
--
--The list of invalid sequences for this code is long and not worth
--stating in full; examples of invalid sequences include `0240' and `0220
--0300 065'.
--
--   The number of *possible* multibyte codes is astronomical.  But a
--given computer system will support at most a few different codes.  (One
--of these codes may allow for thousands of different characters.)
--Another computer system may support a completely different code.  The
--library facilities described in this chapter are helpful because they
--package up the knowledge of the details of a particular computer
--system's multibyte code, so your programs need not know them.
--
--   You can use special standard macros to find out the maximum possible
--number of bytes in a character in the currently selected multibyte code
--with `MB_CUR_MAX', and the maximum for *any* multibyte code supported
--on your computer with `MB_LEN_MAX'.
--
-- - Macro: int MB_LEN_MAX
--     This is the maximum length of a multibyte character for any
--     supported locale.  It is defined in `limits.h'.
--
-- - Macro: int MB_CUR_MAX
--     This macro expands into a (possibly non-constant) positive integer
--     expression that is the maximum number of bytes in a multibyte
--     character in the current locale.  The value is never greater than
--     `MB_LEN_MAX'.
--
--     `MB_CUR_MAX' is defined in `stdlib.h'.
--
--   Normally, each basic sequence in a particular character code stands
--for one character, the same character regardless of context.  Some
--multibyte character codes have a concept of "shift state"; certain
--codes, called "shift sequences", change to a different shift state, and
--the meaning of some or all basic sequences varies according to the
--current shift state.  In fact, the set of basic sequences might even be
--different depending on the current shift state.  *Note Shift State::,
--for more information on handling this sort of code.
--
--   What happens if you try to pass a string containing multibyte
--characters to a function that doesn't know about them?  Normally, such
--a function treats a string as a sequence of bytes, and interprets
--certain byte values specially; all other byte values are "ordinary".
--As long as a multibyte character doesn't contain any of the special
--byte values, the function should pass it through as if it were several
--ordinary characters.
--
--   For example, let's figure out what happens if you use multibyte
--characters in a file name.  The functions such as `open' and `unlink'
--that operate on file names treat the name as a sequence of byte values,
--with `/' as the only special value.  Any other byte values are copied,
--or compared, in sequence, and all byte values are treated alike.  Thus,
--you may think of the file name as a sequence of bytes or as a string
--containing multibyte characters; the same behavior makes sense equally
--either way, provided no multibyte character contains a `/'.
--
--
--File: libc.info,  Node: Wide Char Intro,  Next: Wide String Conversion,  
Prev: Multibyte Char Intro,  Up: Extended Characters
--
--Wide Character Introduction
--===========================
--
--   "Wide characters" are much simpler than multibyte characters.  They
--are simply characters with more than eight bits, so that they have room
--for more than 256 distinct codes.  The wide character data type,
--`wchar_t', has a range large enough to hold extended character codes as
--well as old-fashioned ASCII codes.
--
--   An advantage of wide characters is that each character is a single
--data object, just like ordinary ASCII characters.  Wide characters also
--have some disadvantages:
--
--   * A program must be modified and recompiled in order to use wide
--     characters at all.
--
--   * Files of wide characters cannot be read by programs that expect
--     ordinary characters.
--
--   Wide character values `0' through `0177' are always identical in
--meaning to the ASCII character codes.  The wide character value zero is
--often used to terminate a string of wide characters, just as a single
--byte with value zero often terminates a string of ordinary characters.
--
-- - Data Type: wchar_t
--     This is the "wide character" type, an integer type whose range is
--     large enough to represent all distinct values in any extended
--     character set in the supported locales.  *Note Locales::, for more
--     information about locales.  This type is defined in the header
--     file `stddef.h'.
--
--   If your system supports extended characters, then each extended
--character has both a wide character code and a corresponding multibyte
--basic sequence.
--
--   In this chapter, the term "code" is used to refer to a single
--extended character object to emphasize the distinction from the `char'
--data type.
--
--
--File: libc.info,  Node: Wide String Conversion,  Next: Length of Char,  Prev: 
Wide Char Intro,  Up: Extended Characters
--
--Conversion of Extended Strings
--==============================
--
--   The `mbstowcs' function converts a string of multibyte characters to
--a wide character array.  The `wcstombs' function does the reverse.
--These functions are declared in the header file `stdlib.h'.
--
--   In most programs, these functions are the only ones you need for
--conversion between wide strings and multibyte character strings.  But
--they have limitations.  If your data is not null-terminated or is not
--all in core at once, you probably need to use the low-level conversion
--functions to convert one character at a time.  *Note Converting One
--Char::.
--
-- - Function: size_t mbstowcs (wchar_t *WSTRING, const char *STRING,
--          size_t SIZE)
--     The `mbstowcs' ("multibyte string to wide character string")
--     function converts the null-terminated string of multibyte
--     characters STRING to an array of wide character codes, storing not
--     more than SIZE wide characters into the array beginning at WSTRING.
--     The terminating null character counts towards the size, so if SIZE
--     is less than the actual number of wide characters resulting from
--     STRING, no terminating null character is stored.
--
--     The conversion of characters from STRING begins in the initial
--     shift state.
--
--     If an invalid multibyte character sequence is found, this function
--     returns a value of `-1'.  Otherwise, it returns the number of wide
--     characters stored in the array WSTRING.  This number does not
--     include the terminating null character, which is present if the
--     number is less than SIZE.
--
--     Here is an example showing how to convert a string of multibyte
--     characters, allocating enough space for the result.
--
--          wchar_t *
--          mbstowcs_alloc (const char *string)
--          {
--            size_t size = strlen (string) + 1;
--            wchar_t *buf = xmalloc (size * sizeof (wchar_t));
--          
--            size = mbstowcs (buf, string, size);
--            if (size == (size_t) -1)
--              return NULL;
--            buf = xrealloc (buf, (size + 1) * sizeof (wchar_t));
--            return buf;
--          }
--
--
-- - Function: size_t wcstombs (char *STRING, const wchar_t WSTRING,
--          size_t SIZE)
--     The `wcstombs' ("wide character string to multibyte string")
--     function converts the null-terminated wide character array WSTRING
--     into a string containing multibyte characters, storing not more
--     than SIZE bytes starting at STRING, followed by a terminating null
--     character if there is room.  The conversion of characters begins in
--     the initial shift state.
--
--     The terminating null character counts towards the size, so if SIZE
--     is less than or equal to the number of bytes needed in WSTRING, no
--     terminating null character is stored.
--
--     If a code that does not correspond to a valid multibyte character
--     is found, this function returns a value of `-1'.  Otherwise, the
--     return value is the number of bytes stored in the array STRING.
--     This number does not include the terminating null character, which
--     is present if the number is less than SIZE.
--
--
--File: libc.info,  Node: Length of Char,  Next: Converting One Char,  Prev: 
Wide String Conversion,  Up: Extended Characters
--
--Multibyte Character Length
--==========================
--
--   This section describes how to scan a string containing multibyte
--characters, one character at a time.  The difficulty in doing this is
--to know how many bytes each character contains.  Your program can use
--`mblen' to find this out.
--
-- - Function: int mblen (const char *STRING, size_t SIZE)
--     The `mblen' function with a non-null STRING argument returns the
--     number of bytes that make up the multibyte character beginning at
--     STRING, never examining more than SIZE bytes.  (The idea is to
--     supply for SIZE the number of bytes of data you have in hand.)
--
--     The return value of `mblen' distinguishes three possibilities: the
--     first SIZE bytes at STRING start with valid multibyte character,
--     they start with an invalid byte sequence or just part of a
--     character, or STRING points to an empty string (a null character).
--
--     For a valid multibyte character, `mblen' returns the number of
--     bytes in that character (always at least `1', and never more than
--     SIZE).  For an invalid byte sequence, `mblen' returns `-1'.  For
--     an empty string, it returns `0'.
--
--     If the multibyte character code uses shift characters, then `mblen'
--     maintains and updates a shift state as it scans.  If you call
--     `mblen' with a null pointer for STRING, that initializes the shift
--     state to its standard initial value.  It also returns nonzero if
--     the multibyte character code in use actually has a shift state.
--     *Note Shift State::.
--
--     The function `mblen' is declared in `stdlib.h'.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-19 
glibc-2.0.1/manual/libc.info-19
---- ../glibc-2.0.1/manual/libc.info-19 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-19    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1234 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Converting One Char,  Next: Example of Conversion,  
Prev: Length of Char,  Up: Extended Characters
--
--Conversion of Extended Characters One by One
--============================================
--
--   You can convert multibyte characters one at a time to wide characters
--with the `mbtowc' function.  The `wctomb' function does the reverse.
--These functions are declared in `stdlib.h'.
--
-- - Function: int mbtowc (wchar_t *RESULT, const char *STRING, size_t
--          SIZE)
--     The `mbtowc' ("multibyte to wide character") function when called
--     with non-null STRING converts the first multibyte character
--     beginning at STRING to its corresponding wide character code.  It
--     stores the result in `*RESULT'.
--
--     `mbtowc' never examines more than SIZE bytes.  (The idea is to
--     supply for SIZE the number of bytes of data you have in hand.)
--
--     `mbtowc' with non-null STRING distinguishes three possibilities:
--     the first SIZE bytes at STRING start with valid multibyte
--     character, they start with an invalid byte sequence or just part
--     of a character, or STRING points to an empty string (a null
--     character).
--
--     For a valid multibyte character, `mbtowc' converts it to a wide
--     character and stores that in `*RESULT', and returns the number of
--     bytes in that character (always at least `1', and never more than
--     SIZE).
--
--     For an invalid byte sequence, `mbtowc' returns `-1'.  For an empty
--     string, it returns `0', also storing `0' in `*RESULT'.
--
--     If the multibyte character code uses shift characters, then
--     `mbtowc' maintains and updates a shift state as it scans.  If you
--     call `mbtowc' with a null pointer for STRING, that initializes the
--     shift state to its standard initial value.  It also returns
--     nonzero if the multibyte character code in use actually has a
--     shift state.  *Note Shift State::.
--
-- - Function: int wctomb (char *STRING, wchar_t WCHAR)
--     The `wctomb' ("wide character to multibyte") function converts the
--     wide character code WCHAR to its corresponding multibyte character
--     sequence, and stores the result in bytes starting at STRING.  At
--     most `MB_CUR_MAX' characters are stored.
--
--     `wctomb' with non-null STRING distinguishes three possibilities
--     for WCHAR: a valid wide character code (one that can be translated
--     to a multibyte character), an invalid code, and `0'.
--
--     Given a valid code, `wctomb' converts it to a multibyte character,
--     storing the bytes starting at STRING.  Then it returns the number
--     of bytes in that character (always at least `1', and never more
--     than `MB_CUR_MAX').
--
--     If WCHAR is an invalid wide character code, `wctomb' returns `-1'.
--     If WCHAR is `0', it returns `0', also storing `0' in `*STRING'.
--
--     If the multibyte character code uses shift characters, then
--     `wctomb' maintains and updates a shift state as it scans.  If you
--     call `wctomb' with a null pointer for STRING, that initializes the
--     shift state to its standard initial value.  It also returns
--     nonzero if the multibyte character code in use actually has a
--     shift state.  *Note Shift State::.
--
--     Calling this function with a WCHAR argument of zero when STRING is
--     not null has the side-effect of reinitializing the stored shift
--     state *as well as* storing the multibyte character `0' and
--     returning `0'.
--
--
--File: libc.info,  Node: Example of Conversion,  Next: Shift State,  Prev: 
Converting One Char,  Up: Extended Characters
--
--Character-by-Character Conversion Example
--=========================================
--
--   Here is an example that reads multibyte character text from
--descriptor `input' and writes the corresponding wide characters to
--descriptor `output'.  We need to convert characters one by one for this
--example because `mbstowcs' is unable to continue past a null character,
--and cannot cope with an apparently invalid partial character by reading
--more input.
--
--     int
--     file_mbstowcs (int input, int output)
--     {
--       char buffer[BUFSIZ + MB_LEN_MAX];
--       int filled = 0;
--       int eof = 0;
--     
--       while (!eof)
--         {
--           int nread;
--           int nwrite;
--           char *inp = buffer;
--           wchar_t outbuf[BUFSIZ];
--           wchar_t *outp = outbuf;
--     
--           /* Fill up the buffer from the input file.  */
--           nread = read (input, buffer + filled, BUFSIZ);
--           if (nread < 0)
--             {
--               perror ("read");
--               return 0;
--             }
--           /* If we reach end of file, make a note to read no more. */
--           if (nread == 0)
--             eof = 1;
--     
--           /* `filled' is now the number of bytes in `buffer'. */
--           filled += nread;
--     
--           /* Convert those bytes to wide characters-as many as we can. */
--           while (1)
--             {
--               int thislen = mbtowc (outp, inp, filled);
--               /* Stop converting at invalid character;
--                  this can mean we have read just the first part
--                  of a valid character.  */
--               if (thislen == -1)
--                 break;
--               /* Treat null character like any other,
--                  but also reset shift state. */
--               if (thislen == 0) {
--                 thislen = 1;
--                 mbtowc (NULL, NULL, 0);
--               }
--               /* Advance past this character. */
--               inp += thislen;
--               filled -= thislen;
--               outp++;
--             }
--     
--           /* Write the wide characters we just made.  */
--           nwrite = write (output, outbuf,
--                           (outp - outbuf) * sizeof (wchar_t));
--           if (nwrite < 0)
--             {
--               perror ("write");
--               return 0;
--             }
--     
--           /* See if we have a *real* invalid character. */
--           if ((eof && filled > 0) || filled >= MB_CUR_MAX)
--             {
--               error ("invalid multibyte character");
--               return 0;
--             }
--     
--           /* If any characters must be carried forward,
--              put them at the beginning of `buffer'. */
--           if (filled > 0)
--             memcpy (inp, buffer, filled);
--           }
--         }
--     
--       return 1;
--     }
--
--
--File: libc.info,  Node: Shift State,  Prev: Example of Conversion,  Up: 
Extended Characters
--
--Multibyte Codes Using Shift Sequences
--=====================================
--
--   In some multibyte character codes, the *meaning* of any particular
--byte sequence is not fixed; it depends on what other sequences have come
--earlier in the same string.  Typically there are just a few sequences
--that can change the meaning of other sequences; these few are called
--"shift sequences" and we say that they set the "shift state" for other
--sequences that follow.
--
--   To illustrate shift state and shift sequences, suppose we decide that
--the sequence `0200' (just one byte) enters Japanese mode, in which
--pairs of bytes in the range from `0240' to `0377' are single
--characters, while `0201' enters Latin-1 mode, in which single bytes in
--the range from `0240' to `0377' are characters, and interpreted
--according to the ISO Latin-1 character set.  This is a multibyte code
--which has two alternative shift states ("Japanese mode" and "Latin-1
--mode"), and two shift sequences that specify particular shift states.
--
--   When the multibyte character code in use has shift states, then
--`mblen', `mbtowc' and `wctomb' must maintain and update the current
--shift state as they scan the string.  To make this work properly, you
--must follow these rules:
--
--   * Before starting to scan a string, call the function with a null
--     pointer for the multibyte character address--for example, `mblen
--     (NULL, 0)'.  This initializes the shift state to its standard
--     initial value.
--
--   * Scan the string one character at a time, in order.  Do not "back
--     up" and rescan characters already scanned, and do not intersperse
--     the processing of different strings.
--
--   Here is an example of using `mblen' following these rules:
--
--     void
--     scan_string (char *s)
--     {
--       int length = strlen (s);
--     
--       /* Initialize shift state. */
--       mblen (NULL, 0);
--     
--       while (1)
--         {
--           int thischar = mblen (s, length);
--           /* Deal with end of string and invalid characters. */
--           if (thischar == 0)
--             break;
--           if (thischar == -1)
--             {
--               error ("invalid multibyte character");
--               break;
--             }
--           /* Advance past this character. */
--           s += thischar;
--           length -= thischar;
--         }
--     }
--
--   The functions `mblen', `mbtowc' and `wctomb' are not reentrant when
--using a multibyte code that uses a shift state.  However, no other
--library functions call these functions, so you don't have to worry that
--the shift state will be changed mysteriously.
--
--
--File: libc.info,  Node: Locales,  Next: Searching and Sorting,  Prev: 
Extended Characters,  Up: Top
--
--Locales and Internationalization
--********************************
--
--   Different countries and cultures have varying conventions for how to
--communicate.  These conventions range from very simple ones, such as the
--format for representing dates and times, to very complex ones, such as
--the language spoken.
--
--   "Internationalization" of software means programming it to be able
--to adapt to the user's favorite conventions.  In ISO C,
--internationalization works by means of "locales".  Each locale
--specifies a collection of conventions, one convention for each purpose.
--The user chooses a set of conventions by specifying a locale (via
--environment variables).
--
--   All programs inherit the chosen locale as part of their environment.
--Provided the programs are written to obey the choice of locale, they
--will follow the conventions preferred by the user.
--
--* Menu:
--
--* Effects of Locale::           Actions affected by the choice of
--                                 locale.
--* Choosing Locale::             How the user specifies a locale.
--* Locale Categories::           Different purposes for which you can
--                                 select a locale.
--* Setting the Locale::          How a program specifies the locale
--                                 with library functions.
--* Standard Locales::            Locale names available on all systems.
--* Numeric Formatting::          How to format numbers according to the
--                                 chosen locale.
--
--
--File: libc.info,  Node: Effects of Locale,  Next: Choosing Locale,  Up: 
Locales
--
--What Effects a Locale Has
--=========================
--
--   Each locale specifies conventions for several purposes, including the
--following:
--
--   * What multibyte character sequences are valid, and how they are
--     interpreted (*note Extended Characters::.).
--
--   * Classification of which characters in the local character set are
--     considered alphabetic, and upper- and lower-case conversion
--     conventions (*note Character Handling::.).
--
--   * The collating sequence for the local language and character set
--     (*note Collation Functions::.).
--
--   * Formatting of numbers and currency amounts (*note Numeric
--     Formatting::.).
--
--   * Formatting of dates and times (*note Formatting Date and Time::.).
--
--   * What language to use for output, including error messages.  (The C
--     library doesn't yet help you implement this.)
--
--   * What language to use for user answers to yes-or-no questions.
--
--   * What language to use for more complex user input.  (The C library
--     doesn't yet help you implement this.)
--
--   Some aspects of adapting to the specified locale are handled
--automatically by the library subroutines.  For example, all your program
--needs to do in order to use the collating sequence of the chosen locale
--is to use `strcoll' or `strxfrm' to compare strings.
--
--   Other aspects of locales are beyond the comprehension of the library.
--For example, the library can't automatically translate your program's
--output messages into other languages.  The only way you can support
--output in the user's favorite language is to program this more or less
--by hand.  (Eventually, we hope to provide facilities to make this
--easier.)
--
--   This chapter discusses the mechanism by which you can modify the
--current locale.  The effects of the current locale on specific library
--functions are discussed in more detail in the descriptions of those
--functions.
--
--
--File: libc.info,  Node: Choosing Locale,  Next: Locale Categories,  Prev: 
Effects of Locale,  Up: Locales
--
--Choosing a Locale
--=================
--
--   The simplest way for the user to choose a locale is to set the
--environment variable `LANG'.  This specifies a single locale to use for
--all purposes.  For example, a user could specify a hypothetical locale
--named `espana-castellano' to use the standard conventions of most of
--Spain.
--
--   The set of locales supported depends on the operating system you are
--using, and so do their names.  We can't make any promises about what
--locales will exist, except for one standard locale called `C' or
--`POSIX'.
--
--   A user also has the option of specifying different locales for
--different purposes--in effect, choosing a mixture of multiple locales.
--
--   For example, the user might specify the locale `espana-castellano'
--for most purposes, but specify the locale `usa-english' for currency
--formatting.  This might make sense if the user is a Spanish-speaking
--American, working in Spanish, but representing monetary amounts in US
--dollars.
--
--   Note that both locales `espana-castellano' and `usa-english', like
--all locales, would include conventions for all of the purposes to which
--locales apply.  However, the user can choose to use each locale for a
--particular subset of those purposes.
--
--
--File: libc.info,  Node: Locale Categories,  Next: Setting the Locale,  Prev: 
Choosing Locale,  Up: Locales
--
--Categories of Activities that Locales Affect
--============================================
--
--   The purposes that locales serve are grouped into "categories", so
--that a user or a program can choose the locale for each category
--independently.  Here is a table of categories; each name is both an
--environment variable that a user can set, and a macro name that you can
--use as an argument to `setlocale'.
--
--`LC_COLLATE'
--     This category applies to collation of strings (functions `strcoll'
--     and `strxfrm'); see *Note Collation Functions::.
--
--`LC_CTYPE'
--     This category applies to classification and conversion of
--     characters, and to multibyte and wide characters; see *Note
--     Character Handling:: and *Note Extended Characters::.
--
--`LC_MONETARY'
--     This category applies to formatting monetary values; see *Note
--     Numeric Formatting::.
--
--`LC_NUMERIC'
--     This category applies to formatting numeric values that are not
--     monetary; see *Note Numeric Formatting::.
--
--`LC_TIME'
--     This category applies to formatting date and time values; see
--     *Note Formatting Date and Time::.
--
--`LC_MESSAGES'
--     This category applies to selecting the language used in the user
--     interface for message translation.
--
--`LC_ALL'
--     This is not an environment variable; it is only a macro that you
--     can use with `setlocale' to set a single locale for all purposes.
--
--`LANG'
--     If this environment variable is defined, its value specifies the
--     locale to use for all purposes except as overridden by the
--     variables above.
--
--
--File: libc.info,  Node: Setting the Locale,  Next: Standard Locales,  Prev: 
Locale Categories,  Up: Locales
--
--How Programs Set the Locale
--===========================
--
--   A C program inherits its locale environment variables when it starts
--up.  This happens automatically.  However, these variables do not
--automatically control the locale used by the library functions, because
--ISO C says that all programs start by default in the standard `C'
--locale.  To use the locales specified by the environment, you must call
--`setlocale'.  Call it as follows:
--
--     setlocale (LC_ALL, "");
--
--to select a locale based on the appropriate environment variables.
--
--   You can also use `setlocale' to specify a particular locale, for
--general use or for a specific category.
--
--   The symbols in this section are defined in the header file
--`locale.h'.
--
-- - Function: char * setlocale (int CATEGORY, const char *LOCALE)
--     The function `setlocale' sets the current locale for category
--     CATEGORY to LOCALE.
--
--     If CATEGORY is `LC_ALL', this specifies the locale for all
--     purposes.  The other possible values of CATEGORY specify an
--     individual purpose (*note Locale Categories::.).
--
--     You can also use this function to find out the current locale by
--     passing a null pointer as the LOCALE argument.  In this case,
--     `setlocale' returns a string that is the name of the locale
--     currently selected for category CATEGORY.
--
--     The string returned by `setlocale' can be overwritten by subsequent
--     calls, so you should make a copy of the string (*note Copying and
--     Concatenation::.) if you want to save it past any further calls to
--     `setlocale'.  (The standard library is guaranteed never to call
--     `setlocale' itself.)
--
--     You should not modify the string returned by `setlocale'.  It
--     might be the same string that was passed as an argument in a
--     previous call to `setlocale'.
--
--     When you read the current locale for category `LC_ALL', the value
--     encodes the entire combination of selected locales for all
--     categories.  In this case, the value is not just a single locale
--     name.  In fact, we don't make any promises about what it looks
--     like.  But if you specify the same "locale name" with `LC_ALL' in
--     a subsequent call to `setlocale', it restores the same combination
--     of locale selections.
--
--     When the LOCALE argument is not a null pointer, the string returned
--     by `setlocale' reflects the newly modified locale.
--
--     If you specify an empty string for LOCALE, this means to read the
--     appropriate environment variable and use its value to select the
--     locale for CATEGORY.
--
--     If you specify an invalid locale name, `setlocale' returns a null
--     pointer and leaves the current locale unchanged.
--
--   Here is an example showing how you might use `setlocale' to
--temporarily switch to a new locale.
--
--     #include <stddef.h>
--     #include <locale.h>
--     #include <stdlib.h>
--     #include <string.h>
--     
--     void
--     with_other_locale (char *new_locale,
--                        void (*subroutine) (int),
--                        int argument)
--     {
--       char *old_locale, *saved_locale;
--     
--       /* Get the name of the current locale.  */
--       old_locale = setlocale (LC_ALL, NULL);
--     
--       /* Copy the name so it won't be clobbered by `setlocale'. */
--       saved_locale = strdup (old_locale);
--       if (old_locale == NULL)
--         fatal ("Out of memory");
--     
--       /* Now change the locale and do some stuff with it. */
--       setlocale (LC_ALL, new_locale);
--       (*subroutine) (argument);
--     
--       /* Restore the original locale. */
--       setlocale (LC_ALL, saved_locale);
--       free (saved_locale);
--     }
--
--   *Portability Note:* Some ISO C systems may define additional locale
--categories.  For portability, assume that any symbol beginning with
--`LC_' might be defined in `locale.h'.
--
--
--File: libc.info,  Node: Standard Locales,  Next: Numeric Formatting,  Prev: 
Setting the Locale,  Up: Locales
--
--Standard Locales
--================
--
--   The only locale names you can count on finding on all operating
--systems are these three standard ones:
--
--`"C"'
--     This is the standard C locale.  The attributes and behavior it
--     provides are specified in the ISO C standard.  When your program
--     starts up, it initially uses this locale by default.
--
--`"POSIX"'
--     This is the standard POSIX locale.  Currently, it is an alias for
--     the standard C locale.
--
--`""'
--     The empty name says to select a locale based on environment
--     variables.  *Note Locale Categories::.
--
--   Defining and installing named locales is normally a responsibility of
--the system administrator at your site (or the person who installed the
--GNU C library).  Some systems may allow users to create locales, but we
--don't discuss that here.
--
--   If your program needs to use something other than the `C' locale, it
--will be more portable if you use whatever locale the user specifies
--with the environment, rather than trying to specify some non-standard
--locale explicitly by name.  Remember, different machines might have
--different sets of locales installed.
--
--
--File: libc.info,  Node: Numeric Formatting,  Prev: Standard Locales,  Up: 
Locales
--
--Numeric Formatting
--==================
--
--   When you want to format a number or a currency amount using the
--conventions of the current locale, you can use the function
--`localeconv' to get the data on how to do it.  The function
--`localeconv' is declared in the header file `locale.h'.
--
-- - Function: struct lconv * localeconv (void)
--     The `localeconv' function returns a pointer to a structure whose
--     components contain information about how numeric and monetary
--     values should be formatted in the current locale.
--
--     You shouldn't modify the structure or its contents.  The structure
--     might be overwritten by subsequent calls to `localeconv', or by
--     calls to `setlocale', but no other function in the library
--     overwrites this value.
--
-- - Data Type: struct lconv
--     This is the data type of the value returned by `localeconv'.
--
--   If a member of the structure `struct lconv' has type `char', and the
--value is `CHAR_MAX', it means that the current locale has no value for
--that parameter.
--
--* Menu:
--
--* General Numeric::             Parameters for formatting numbers and
--                                 currency amounts.
--* Currency Symbol::             How to print the symbol that identifies an
--                                 amount of money (e.g. `$').
--* Sign of Money Amount::        How to print the (positive or negative) sign
--                                 for a monetary amount, if one exists.
--
--
--File: libc.info,  Node: General Numeric,  Next: Currency Symbol,  Up: Numeric 
Formatting
--
--Generic Numeric Formatting Parameters
---------------------------------------
--
--   These are the standard members of `struct lconv'; there may be
--others.
--
--`char *decimal_point'
--`char *mon_decimal_point'
--     These are the decimal-point separators used in formatting
--     non-monetary and monetary quantities, respectively.  In the `C'
--     locale, the value of `decimal_point' is `"."', and the value of
--     `mon_decimal_point' is `""'.
--
--`char *thousands_sep'
--`char *mon_thousands_sep'
--     These are the separators used to delimit groups of digits to the
--     left of the decimal point in formatting non-monetary and monetary
--     quantities, respectively.  In the `C' locale, both members have a
--     value of `""' (the empty string).
--
--`char *grouping'
--`char *mon_grouping'
--     These are strings that specify how to group the digits to the left
--     of the decimal point.  `grouping' applies to non-monetary
--     quantities and `mon_grouping' applies to monetary quantities.  Use
--     either `thousands_sep' or `mon_thousands_sep' to separate the digit
--     groups.
--
--     Each string is made up of decimal numbers separated by semicolons.
--     Successive numbers (from left to right) give the sizes of
--     successive groups (from right to left, starting at the decimal
--     point).  The last number in the string is used over and over for
--     all the remaining groups.
--
--     If the last integer is `-1', it means that there is no more
--     grouping--or, put another way, any remaining digits form one large
--     group without separators.
--
--     For example, if `grouping' is `"4;3;2"', the correct grouping for
--     the number `123456787654321' is `12', `34', `56', `78', `765',
--     `4321'.  This uses a group of 4 digits at the end, preceded by a
--     group of 3 digits, preceded by groups of 2 digits (as many as
--     needed).  With a separator of `,', the number would be printed as
--     `12,34,56,78,765,4321'.
--
--     A value of `"3"' indicates repeated groups of three digits, as
--     normally used in the U.S.
--
--     In the standard `C' locale, both `grouping' and `mon_grouping'
--     have a value of `""'.  This value specifies no grouping at all.
--
--`char int_frac_digits'
--`char frac_digits'
--     These are small integers indicating how many fractional digits (to
--     the right of the decimal point) should be displayed in a monetary
--     value in international and local formats, respectively.  (Most
--     often, both members have the same value.)
--
--     In the standard `C' locale, both of these members have the value
--     `CHAR_MAX', meaning "unspecified".  The ISO standard doesn't say
--     what to do when you find this the value; we recommend printing no
--     fractional digits.  (This locale also specifies the empty string
--     for `mon_decimal_point', so printing any fractional digits would be
--     confusing!)
--
--
--File: libc.info,  Node: Currency Symbol,  Next: Sign of Money Amount,  Prev: 
General Numeric,  Up: Numeric Formatting
--
--Printing the Currency Symbol
------------------------------
--
--   These members of the `struct lconv' structure specify how to print
--the symbol to identify a monetary value--the international analog of
--`$' for US dollars.
--
--   Each country has two standard currency symbols.  The "local currency
--symbol" is used commonly within the country, while the "international
--currency symbol" is used internationally to refer to that country's
--currency when it is necessary to indicate the country unambiguously.
--
--   For example, many countries use the dollar as their monetary unit,
--and when dealing with international currencies it's important to specify
--that one is dealing with (say) Canadian dollars instead of U.S. dollars
--or Australian dollars.  But when the context is known to be Canada,
--there is no need to make this explicit--dollar amounts are implicitly
--assumed to be in Canadian dollars.
--
--`char *currency_symbol'
--     The local currency symbol for the selected locale.
--
--     In the standard `C' locale, this member has a value of `""' (the
--     empty string), meaning "unspecified".  The ISO standard doesn't
--     say what to do when you find this value; we recommend you simply
--     print the empty string as you would print any other string found
--     in the appropriate member.
--
--`char *int_curr_symbol'
--     The international currency symbol for the selected locale.
--
--     The value of `int_curr_symbol' should normally consist of a
--     three-letter abbreviation determined by the international standard
--     `ISO 4217 Codes for the Representation of Currency and Funds',
--     followed by a one-character separator (often a space).
--
--     In the standard `C' locale, this member has a value of `""' (the
--     empty string), meaning "unspecified".  We recommend you simply
--     print the empty string as you would print any other string found
--     in the appropriate member.
--
--`char p_cs_precedes'
--`char n_cs_precedes'
--     These members are `1' if the `currency_symbol' string should
--     precede the value of a monetary amount, or `0' if the string should
--     follow the value.  The `p_cs_precedes' member applies to positive
--     amounts (or zero), and the `n_cs_precedes' member applies to
--     negative amounts.
--
--     In the standard `C' locale, both of these members have a value of
--     `CHAR_MAX', meaning "unspecified".  The ISO standard doesn't say
--     what to do when you find this value, but we recommend printing the
--     currency symbol before the amount.  That's right for most
--     countries.  In other words, treat all nonzero values alike in
--     these members.
--
--     The POSIX standard says that these two members apply to the
--     `int_curr_symbol' as well as the `currency_symbol'.  The ISO C
--     standard seems to imply that they should apply only to the
--     `currency_symbol'--so the `int_curr_symbol' should always precede
--     the amount.
--
--     We can only guess which of these (if either) matches the usual
--     conventions for printing international currency symbols.  Our
--     guess is that they should always precede the amount.  If we find
--     out a reliable answer, we will put it here.
--
--`char p_sep_by_space'
--`char n_sep_by_space'
--     These members are `1' if a space should appear between the
--     `currency_symbol' string and the amount, or `0' if no space should
--     appear.  The `p_sep_by_space' member applies to positive amounts
--     (or zero), and the `n_sep_by_space' member applies to negative
--     amounts.
--
--     In the standard `C' locale, both of these members have a value of
--     `CHAR_MAX', meaning "unspecified".  The ISO standard doesn't say
--     what you should do when you find this value; we suggest you treat
--     it as one (print a space).  In other words, treat all nonzero
--     values alike in these members.
--
--     These members apply only to `currency_symbol'.  When you use
--     `int_curr_symbol', you never print an additional space, because
--     `int_curr_symbol' itself contains the appropriate separator.
--
--     The POSIX standard says that these two members apply to the
--     `int_curr_symbol' as well as the `currency_symbol'.  But an
--     example in the ISO C standard clearly implies that they should
--     apply only to the `currency_symbol'--that the `int_curr_symbol'
--     contains any appropriate separator, so you should never print an
--     additional space.
--
--     Based on what we know now, we recommend you ignore these members
--     when printing international currency symbols, and print no extra
--     space.
--
--
--File: libc.info,  Node: Sign of Money Amount,  Prev: Currency Symbol,  Up: 
Numeric Formatting
--
--Printing the Sign of an Amount of Money
-----------------------------------------
--
--   These members of the `struct lconv' structure specify how to print
--the sign (if any) in a monetary value.
--
--`char *positive_sign'
--`char *negative_sign'
--     These are strings used to indicate positive (or zero) and negative
--     (respectively) monetary quantities.
--
--     In the standard `C' locale, both of these members have a value of
--     `""' (the empty string), meaning "unspecified".
--
--     The ISO standard doesn't say what to do when you find this value;
--     we recommend printing `positive_sign' as you find it, even if it is
--     empty.  For a negative value, print `negative_sign' as you find it
--     unless both it and `positive_sign' are empty, in which case print
--     `-' instead.  (Failing to indicate the sign at all seems rather
--     unreasonable.)
--
--`char p_sign_posn'
--`char n_sign_posn'
--     These members have values that are small integers indicating how to
--     position the sign for nonnegative and negative monetary quantities,
--     respectively.  (The string used by the sign is what was specified
--     with `positive_sign' or `negative_sign'.)  The possible values are
--     as follows:
--
--    `0'
--          The currency symbol and quantity should be surrounded by
--          parentheses.
--
--    `1'
--          Print the sign string before the quantity and currency symbol.
--
--    `2'
--          Print the sign string after the quantity and currency symbol.
--
--    `3'
--          Print the sign string right before the currency symbol.
--
--    `4'
--          Print the sign string right after the currency symbol.
--
--    `CHAR_MAX'
--          "Unspecified".  Both members have this value in the standard
--          `C' locale.
--
--     The ISO standard doesn't say what you should do when the value is
--     `CHAR_MAX'.  We recommend you print the sign after the currency
--     symbol.
--
--   It is not clear whether you should let these members apply to the
--international currency format or not.  POSIX says you should, but
--intuition plus the examples in the ISO C standard suggest you should
--not.  We hope that someone who knows well the conventions for formatting
--monetary quantities will tell us what we should recommend.
--
--
--File: libc.info,  Node: Non-Local Exits,  Next: Signal Handling,  Prev: Date 
and Time,  Up: Top
--
--Non-Local Exits
--***************
--
--   Sometimes when your program detects an unusual situation inside a
--deeply nested set of function calls, you would like to be able to
--immediately return to an outer level of control.  This section
--describes how you can do such "non-local exits" using the `setjmp' and
--`longjmp' functions.
--
--* Menu:
--
--* Intro: Non-Local Intro.        When and how to use these facilities.
--* Details: Non-Local Details.   Functions for nonlocal exits.
--* Non-Local Exits and Signals::  Portability issues.
--
--
--File: libc.info,  Node: Non-Local Intro,  Next: Non-Local Details,  Up: 
Non-Local Exits
--
--Introduction to Non-Local Exits
--===============================
--
--   As an example of a situation where a non-local exit can be useful,
--suppose you have an interactive program that has a "main loop" that
--prompts for and executes commands.  Suppose the "read" command reads
--input from a file, doing some lexical analysis and parsing of the input
--while processing it.  If a low-level input error is detected, it would
--be useful to be able to return immediately to the "main loop" instead
--of having to make each of the lexical analysis, parsing, and processing
--phases all have to explicitly deal with error situations initially
--detected by nested calls.
--
--   (On the other hand, if each of these phases has to do a substantial
--amount of cleanup when it exits--such as closing files, deallocating
--buffers or other data structures, and the like--then it can be more
--appropriate to do a normal return and have each phase do its own
--cleanup, because a non-local exit would bypass the intervening phases
--and their associated cleanup code entirely.  Alternatively, you could
--use a non-local exit but do the cleanup explicitly either before or
--after returning to the "main loop".)
--
--   In some ways, a non-local exit is similar to using the `return'
--statement to return from a function.  But while `return' abandons only
--a single function call, transferring control back to the point at which
--it was called, a non-local exit can potentially abandon many levels of
--nested function calls.
--
--   You identify return points for non-local exits calling the function
--`setjmp'.  This function saves information about the execution
--environment in which the call to `setjmp' appears in an object of type
--`jmp_buf'.  Execution of the program continues normally after the call
--to `setjmp', but if a exit is later made to this return point by
--calling `longjmp' with the corresponding `jmp_buf' object, control is
--transferred back to the point where `setjmp' was called.  The return
--value from `setjmp' is used to distinguish between an ordinary return
--and a return made by a call to `longjmp', so calls to `setjmp' usually
--appear in an `if' statement.
--
--   Here is how the example program described above might be set up:
--
--     #include <setjmp.h>
--     #include <stdlib.h>
--     #include <stdio.h>
--     
--     jmp_buf main_loop;
--     
--     void
--     abort_to_main_loop (int status)
--     {
--       longjmp (main_loop, status);
--     }
--     
--     int
--     main (void)
--     {
--       while (1)
--         if (setjmp (main_loop))
--           puts ("Back at main loop....");
--         else
--           do_command ();
--     }
--     
--     
--     void
--     do_command (void)
--     {
--       char buffer[128];
--       if (fgets (buffer, 128, stdin) == NULL)
--         abort_to_main_loop (-1);
--       else
--         exit (EXIT_SUCCESS);
--     }
--
--   The function `abort_to_main_loop' causes an immediate transfer of
--control back to the main loop of the program, no matter where it is
--called from.
--
--   The flow of control inside the `main' function may appear a little
--mysterious at first, but it is actually a common idiom with `setjmp'.
--A normal call to `setjmp' returns zero, so the "else" clause of the
--conditional is executed.  If `abort_to_main_loop' is called somewhere
--within the execution of `do_command', then it actually appears as if
--the *same* call to `setjmp' in `main' were returning a second time with
--a value of `-1'.
--
--   So, the general pattern for using `setjmp' looks something like:
--
--     if (setjmp (BUFFER))
--       /* Code to clean up after premature return. */
--       ...
--     else
--       /* Code to be executed normally after setting up the return point. */
--       ...
--
--
--File: libc.info,  Node: Non-Local Details,  Next: Non-Local Exits and 
Signals,  Prev: Non-Local Intro,  Up: Non-Local Exits
--
--Details of Non-Local Exits
--==========================
--
--   Here are the details on the functions and data structures used for
--performing non-local exits.  These facilities are declared in
--`setjmp.h'.
--
-- - Data Type: jmp_buf
--     Objects of type `jmp_buf' hold the state information to be
--     restored by a non-local exit.  The contents of a `jmp_buf'
--     identify a specific place to return to.
--
-- - Macro: int setjmp (jmp_buf STATE)
--     When called normally, `setjmp' stores information about the
--     execution state of the program in STATE and returns zero.  If
--     `longjmp' is later used to perform a non-local exit to this STATE,
--     `setjmp' returns a nonzero value.
--
-- - Function: void longjmp (jmp_buf STATE, int VALUE)
--     This function restores current execution to the state saved in
--     STATE, and continues execution from the call to `setjmp' that
--     established that return point.  Returning from `setjmp' by means of
--     `longjmp' returns the VALUE argument that was passed to `longjmp',
--     rather than `0'.  (But if VALUE is given as `0', `setjmp' returns
--     `1').
--
--   There are a lot of obscure but important restrictions on the use of
--`setjmp' and `longjmp'.  Most of these restrictions are present because
--non-local exits require a fair amount of magic on the part of the C
--compiler and can interact with other parts of the language in strange
--ways.
--
--   The `setjmp' function is actually a macro without an actual function
--definition, so you shouldn't try to `#undef' it or take its address.
--In addition, calls to `setjmp' are safe in only the following contexts:
--
--   * As the test expression of a selection or iteration statement (such
--     as `if', `switch', or `while').
--
--   * As one operand of a equality or comparison operator that appears
--     as the test expression of a selection or iteration statement.  The
--     other operand must be an integer constant expression.
--
--   * As the operand of a unary `!' operator, that appears as the test
--     expression of a selection or iteration statement.
--
--   * By itself as an expression statement.
--
--   Return points are valid only during the dynamic extent of the
--function that called `setjmp' to establish them.  If you `longjmp' to a
--return point that was established in a function that has already
--returned, unpredictable and disastrous things are likely to happen.
--
--   You should use a nonzero VALUE argument to `longjmp'.  While
--`longjmp' refuses to pass back a zero argument as the return value from
--`setjmp', this is intended as a safety net against accidental misuse
--and is not really good programming style.
--
--   When you perform a non-local exit, accessible objects generally
--retain whatever values they had at the time `longjmp' was called.  The
--exception is that the values of automatic variables local to the
--function containing the `setjmp' call that have been changed since the
--call to `setjmp' are indeterminate, unless you have declared them
--`volatile'.
--
--
--File: libc.info,  Node: Non-Local Exits and Signals,  Prev: Non-Local 
Details,  Up: Non-Local Exits
--
--Non-Local Exits and Signals
--===========================
--
--   In BSD Unix systems, `setjmp' and `longjmp' also save and restore
--the set of blocked signals; see *Note Blocking Signals::.  However, the
--POSIX.1 standard requires `setjmp' and `longjmp' not to change the set
--of blocked signals, and provides an additional pair of functions
--(`sigsetjmp' and `sigsetjmp') to get the BSD behavior.
--
--   The behavior of `setjmp' and `longjmp' in the GNU library is
--controlled by feature test macros; see *Note Feature Test Macros::.  The
--default in the GNU system is the POSIX.1 behavior rather than the BSD
--behavior.
--
--   The facilities in this section are declared in the header file
--`setjmp.h'.
--
-- - Data Type: sigjmp_buf
--     This is similar to `jmp_buf', except that it can also store state
--     information about the set of blocked signals.
--
-- - Function: int sigsetjmp (sigjmp_buf STATE, int SAVESIGS)
--     This is similar to `setjmp'.  If SAVESIGS is nonzero, the set of
--     blocked signals is saved in STATE and will be restored if a
--     `siglongjmp' is later performed with this STATE.
--
-- - Function: void siglongjmp (sigjmp_buf STATE, int VALUE)
--     This is similar to `longjmp' except for the type of its STATE
--     argument.  If the `sigsetjmp' call that set this STATE used a
--     nonzero SAVESIGS flag, `siglongjmp' also restores the set of
--     blocked signals.
--
--
--File: libc.info,  Node: Signal Handling,  Next: Process Startup,  Prev: 
Non-Local Exits,  Up: Top
--
--Signal Handling
--***************
--
--   A "signal" is a software interrupt delivered to a process.  The
--operating system uses signals to report exceptional situations to an
--executing program.  Some signals report errors such as references to
--invalid memory addresses; others report asynchronous events, such as
--disconnection of a phone line.
--
--   The GNU C library defines a variety of signal types, each for a
--particular kind of event.  Some kinds of events make it inadvisable or
--impossible for the program to proceed as usual, and the corresponding
--signals normally abort the program.  Other kinds of signals that report
--harmless events are ignored by default.
--
--   If you anticipate an event that causes signals, you can define a
--handler function and tell the operating system to run it when that
--particular type of signal arrives.
--
--   Finally, one process can send a signal to another process; this
--allows a parent process to abort a child, or two related processes to
--communicate and synchronize.
--
--* Menu:
--
--* Concepts of Signals::         Introduction to the signal facilities.
--* Standard Signals::            Particular kinds of signals with
--                                 standard names and meanings.
--* Signal Actions::              Specifying what happens when a
--                                 particular signal is delivered.
--* Defining Handlers::           How to write a signal handler function.
--* Interrupted Primitives::    Signal handlers affect use of `open',
--                               `read', `write' and other functions.
--* Generating Signals::          How to send a signal to a process.
--* Blocking Signals::            Making the system hold signals temporarily.
--* Waiting for a Signal::        Suspending your program until a signal
--                                 arrives.
--* Signal Stack::                Using a Separate Signal Stack.
--* BSD Signal Handling::         Additional functions for backward
--                               compatibility with BSD.
--
--
--File: libc.info,  Node: Concepts of Signals,  Next: Standard Signals,  Up: 
Signal Handling
--
--Basic Concepts of Signals
--=========================
--
--   This section explains basic concepts of how signals are generated,
--what happens after a signal is delivered, and how programs can handle
--signals.
--
--* Menu:
--
--* Kinds of Signals::            Some examples of what can cause a signal.
--* Signal Generation::           Concepts of why and how signals occur.
--* Delivery of Signal::          Concepts of what a signal does to the
--                                 process.
--
--
--File: libc.info,  Node: Kinds of Signals,  Next: Signal Generation,  Up: 
Concepts of Signals
--
--Some Kinds of Signals
-----------------------
--
--   A signal reports the occurrence of an exceptional event.  These are
--some of the events that can cause (or "generate", or "raise") a signal:
--
--   * A program error such as dividing by zero or issuing an address
--     outside the valid range.
--
--   * A user request to interrupt or terminate the program.  Most
--     environments are set up to let a user suspend the program by
--     typing `C-z', or terminate it with `C-c'.  Whatever key sequence
--     is used, the operating system sends the proper signal to interrupt
--     the process.
--
--   * The termination of a child process.
--
--   * Expiration of a timer or alarm.
--
--   * A call to `kill' or `raise' by the same process.
--
--   * A call to `kill' from another process.  Signals are a limited but
--     useful form of interprocess communication.
--
--   * An attempt to perform an I/O operation that cannot be done.
--     Examples are reading from a pipe that has no writer (*note Pipes
--     and FIFOs::.), and reading or writing to a terminal in certain
--     situations (*note Job Control::.).
--
--   Each of these kinds of events (excepting explicit calls to `kill'
--and `raise') generates its own particular kind of signal.  The various
--kinds of signals are listed and described in detail in *Note Standard
--Signals::.
--
--
--File: libc.info,  Node: Signal Generation,  Next: Delivery of Signal,  Prev: 
Kinds of Signals,  Up: Concepts of Signals
--
--Concepts of Signal Generation
-------------------------------
--
--   In general, the events that generate signals fall into three major
--categories: errors, external events, and explicit requests.
--
--   An error means that a program has done something invalid and cannot
--continue execution.  But not all kinds of errors generate signals--in
--fact, most do not.  For example, opening a nonexistent file is an error,
--but it does not raise a signal; instead, `open' returns `-1'.  In
--general, errors that are necessarily associated with certain library
--functions are reported by returning a value that indicates an error.
--The errors which raise signals are those which can happen anywhere in
--the program, not just in library calls.  These include division by zero
--and invalid memory addresses.
--
--   An external event generally has to do with I/O or other processes.
--These include the arrival of input, the expiration of a timer, and the
--termination of a child process.
--
--   An explicit request means the use of a library function such as
--`kill' whose purpose is specifically to generate a signal.
--
--   Signals may be generated "synchronously" or "asynchronously".  A
--synchronous signal pertains to a specific action in the program, and is
--delivered (unless blocked) during that action.  Most errors generate
--signals synchronously, and so do explicit requests by a process to
--generate a signal for that same process.  On some machines, certain
--kinds of hardware errors (usually floating-point exceptions) are not
--reported completely synchronously, but may arrive a few instructions
--later.
--
--   Asynchronous signals are generated by events outside the control of
--the process that receives them.  These signals arrive at unpredictable
--times during execution.  External events generate signals
--asynchronously, and so do explicit requests that apply to some other
--process.
--
--   A given type of signal is either typically synchronous or typically
--asynchronous.  For example, signals for errors are typically synchronous
--because errors generate signals synchronously.  But any type of signal
--can be generated synchronously or asynchronously with an explicit
--request.
--
--
--File: libc.info,  Node: Delivery of Signal,  Prev: Signal Generation,  Up: 
Concepts of Signals
--
--How Signals Are Delivered
---------------------------
--
--   When a signal is generated, it becomes "pending".  Normally it
--remains pending for just a short period of time and then is "delivered"
--to the process that was signaled.  However, if that kind of signal is
--currently "blocked", it may remain pending indefinitely--until signals
--of that kind are "unblocked".  Once unblocked, it will be delivered
--immediately.  *Note Blocking Signals::.
--
--   When the signal is delivered, whether right away or after a long
--delay, the "specified action" for that signal is taken.  For certain
--signals, such as `SIGKILL' and `SIGSTOP', the action is fixed, but for
--most signals, the program has a choice: ignore the signal, specify a
--"handler function", or accept the "default action" for that kind of
--signal.  The program specifies its choice using functions such as
--`signal' or `sigaction' (*note Signal Actions::.).  We sometimes say
--that a handler "catches" the signal.  While the handler is running,
--that particular signal is normally blocked.
--
--   If the specified action for a kind of signal is to ignore it, then
--any such signal which is generated is discarded immediately.  This
--happens even if the signal is also blocked at the time.  A signal
--discarded in this way will never be delivered, not even if the program
--subsequently specifies a different action for that kind of signal and
--then unblocks it.
--
--   If a signal arrives which the program has neither handled nor
--ignored, its "default action" takes place.  Each kind of signal has its
--own default action, documented below (*note Standard Signals::.).  For
--most kinds of signals, the default action is to terminate the process.
--For certain kinds of signals that represent "harmless" events, the
--default action is to do nothing.
--
--   When a signal terminates a process, its parent process can determine
--the cause of termination by examining the termination status code
--reported by the `wait' or `waitpid' functions.  (This is discussed in
--more detail in *Note Process Completion::.)  The information it can get
--includes the fact that termination was due to a signal, and the kind of
--signal involved.  If a program you run from a shell is terminated by a
--signal, the shell typically prints some kind of error message.
--
--   The signals that normally represent program errors have a special
--property: when one of these signals terminates the process, it also
--writes a "core dump file" which records the state of the process at the
--time of termination.  You can examine the core dump with a debugger to
--investigate what caused the error.
--
--   If you raise a "program error" signal by explicit request, and this
--terminates the process, it makes a core dump file just as if the signal
--had been due directly to an error.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-2 
glibc-2.0.1/manual/libc.info-2
---- ../glibc-2.0.1/manual/libc.info-2  1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-2     1970-01-01 01:00:00.000000000 +0100
-@@ -1,1202 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Header Files,  Next: Macro Definitions,  Up: Using 
the Library
--
--Header Files
--------------
--
--   Libraries for use by C programs really consist of two parts: "header
--files" that define types and macros and declare variables and
--functions; and the actual library or "archive" that contains the
--definitions of the variables and functions.
--
--   (Recall that in C, a "declaration" merely provides information that
--a function or variable exists and gives its type.  For a function
--declaration, information about the types of its arguments might be
--provided as well.  The purpose of declarations is to allow the compiler
--to correctly process references to the declared variables and functions.
--A "definition", on the other hand, actually allocates storage for a
--variable or says what a function does.)
--
--   In order to use the facilities in the GNU C library, you should be
--sure that your program source files include the appropriate header
--files.  This is so that the compiler has declarations of these
--facilities available and can correctly process references to them.
--Once your program has been compiled, the linker resolves these
--references to the actual definitions provided in the archive file.
--
--   Header files are included into a program source file by the
--`#include' preprocessor directive.  The C language supports two forms
--of this directive; the first,
--
--     #include "HEADER"
--
--is typically used to include a header file HEADER that you write
--yourself; this would contain definitions and declarations describing the
--interfaces between the different parts of your particular application.
--By contrast,
--
--     #include <file.h>
--
--is typically used to include a header file `file.h' that contains
--definitions and declarations for a standard library.  This file would
--normally be installed in a standard place by your system administrator.
--You should use this second form for the C library header files.
--
--   Typically, `#include' directives are placed at the top of the C
--source file, before any other code.  If you begin your source files with
--some comments explaining what the code in the file does (a good idea),
--put the `#include' directives immediately afterwards, following the
--feature test macro definition (*note Feature Test Macros::.).
--
--   For more information about the use of header files and `#include'
--directives, *note Header Files: (cpp.info)Header Files..
--
--   The GNU C library provides several header files, each of which
--contains the type and macro definitions and variable and function
--declarations for a group of related facilities.  This means that your
--programs may need to include several header files, depending on exactly
--which facilities you are using.
--
--   Some library header files include other library header files
--automatically.  However, as a matter of programming style, you should
--not rely on this; it is better to explicitly include all the header
--files required for the library facilities you are using.  The GNU C
--library header files have been written in such a way that it doesn't
--matter if a header file is accidentally included more than once;
--including a header file a second time has no effect.  Likewise, if your
--program needs to include multiple header files, the order in which they
--are included doesn't matter.
--
--   *Compatibility Note:* Inclusion of standard header files in any
--order and any number of times works in any ISO C implementation.
--However, this has traditionally not been the case in many older C
--implementations.
--
--   Strictly speaking, you don't *have to* include a header file to use
--a function it declares; you could declare the function explicitly
--yourself, according to the specifications in this manual.  But it is
--usually better to include the header file because it may define types
--and macros that are not otherwise available and because it may define
--more efficient macro replacements for some functions.  It is also a sure
--way to have the correct declaration.
--
--
--File: libc.info,  Node: Macro Definitions,  Next: Reserved Names,  Prev: 
Header Files,  Up: Using the Library
--
--Macro Definitions of Functions
--------------------------------
--
--   If we describe something as a function in this manual, it may have a
--macro definition as well.  This normally has no effect on how your
--program runs--the macro definition does the same thing as the function
--would.  In particular, macro equivalents for library functions evaluate
--arguments exactly once, in the same way that a function call would.  The
--main reason for these macro definitions is that sometimes they can
--produce an inline expansion that is considerably faster than an actual
--function call.
--
--   Taking the address of a library function works even if it is also
--defined as a macro.  This is because, in this context, the name of the
--function isn't followed by the left parenthesis that is syntactically
--necessary to recognize a macro call.
--
--   You might occasionally want to avoid using the macro definition of a
--function--perhaps to make your program easier to debug.  There are two
--ways you can do this:
--
--   * You can avoid a macro definition in a specific use by enclosing
--     the name of the function in parentheses.  This works because the
--     name of the function doesn't appear in a syntactic context where
--     it is recognizable as a macro call.
--
--   * You can suppress any macro definition for a whole source file by
--     using the `#undef' preprocessor directive, unless otherwise stated
--     explicitly in the description of that facility.
--
--   For example, suppose the header file `stdlib.h' declares a function
--named `abs' with
--
--     extern int abs (int);
--
--and also provides a macro definition for `abs'.  Then, in:
--
--     #include <stdlib.h>
--     int f (int *i) { return (abs (++*i)); }
--
--the reference to `abs' might refer to either a macro or a function.  On
--the other hand, in each of the following examples the reference is to a
--function and not a macro.
--
--     #include <stdlib.h>
--     int g (int *i) { return ((abs)(++*i)); }
--     
--     #undef abs
--     int h (int *i) { return (abs (++*i)); }
--
--   Since macro definitions that double for a function behave in exactly
--the same way as the actual function version, there is usually no need
--for any of these methods.  In fact, removing macro definitions usually
--just makes your program slower.
--
--
--File: libc.info,  Node: Reserved Names,  Next: Feature Test Macros,  Prev: 
Macro Definitions,  Up: Using the Library
--
--Reserved Names
----------------
--
--   The names of all library types, macros, variables and functions that
--come from the ISO C standard are reserved unconditionally; your program
--*may not* redefine these names.  All other library names are reserved
--if your program explicitly includes the header file that defines or
--declares them.  There are several reasons for these restrictions:
--
--   * Other people reading your code could get very confused if you were
--     using a function named `exit' to do something completely different
--     from what the standard `exit' function does, for example.
--     Preventing this situation helps to make your programs easier to
--     understand and contributes to modularity and maintainability.
--
--   * It avoids the possibility of a user accidentally redefining a
--     library function that is called by other library functions.  If
--     redefinition were allowed, those other functions would not work
--     properly.
--
--   * It allows the compiler to do whatever special optimizations it
--     pleases on calls to these functions, without the possibility that
--     they may have been redefined by the user.  Some library
--     facilities, such as those for dealing with variadic arguments
--     (*note Variadic Functions::.) and non-local exits (*note Non-Local
--     Exits::.), actually require a considerable amount of cooperation
--     on the part of the C compiler, and implementationally it might be
--     easier for the compiler to treat these as built-in parts of the
--     language.
--
--   In addition to the names documented in this manual, reserved names
--include all external identifiers (global functions and variables) that
--begin with an underscore (`_') and all identifiers regardless of use
--that begin with either two underscores or an underscore followed by a
--capital letter are reserved names.  This is so that the library and
--header files can define functions, variables, and macros for internal
--purposes without risk of conflict with names in user programs.
--
--   Some additional classes of identifier names are reserved for future
--extensions to the C language or the POSIX.1 environment.  While using
--these names for your own purposes right now might not cause a problem,
--they do raise the possibility of conflict with future versions of the C
--or POSIX standards, so you should avoid these names.
--
--   * Names beginning with a capital `E' followed a digit or uppercase
--     letter may be used for additional error code names.  *Note Error
--     Reporting::.
--
--   * Names that begin with either `is' or `to' followed by a lowercase
--     letter may be used for additional character testing and conversion
--     functions.  *Note Character Handling::.
--
--   * Names that begin with `LC_' followed by an uppercase letter may be
--     used for additional macros specifying locale attributes.  *Note
--     Locales::.
--
--   * Names of all existing mathematics functions (*note Mathematics::.)
--     suffixed with `f' or `l' are reserved for corresponding functions
--     that operate on `float' and `long double' arguments, respectively.
--
--   * Names that begin with `SIG' followed by an uppercase letter are
--     reserved for additional signal names.  *Note Standard Signals::.
--
--   * Names that begin with `SIG_' followed by an uppercase letter are
--     reserved for additional signal actions.  *Note Basic Signal
--     Handling::.
--
--   * Names beginning with `str', `mem', or `wcs' followed by a
--     lowercase letter are reserved for additional string and array
--     functions.  *Note String and Array Utilities::.
--
--   * Names that end with `_t' are reserved for additional type names.
--
--   In addition, some individual header files reserve names beyond those
--that they actually define.  You only need to worry about these
--restrictions if your program includes that particular header file.
--
--   * The header file `dirent.h' reserves names prefixed with `d_'.
--
--   * The header file `fcntl.h' reserves names prefixed with `l_', `F_',
--     `O_', and `S_'.
--
--   * The header file `grp.h' reserves names prefixed with `gr_'.
--
--   * The header file `limits.h' reserves names suffixed with `_MAX'.
--
--   * The header file `pwd.h' reserves names prefixed with `pw_'.
--
--   * The header file `signal.h' reserves names prefixed with `sa_' and
--     `SA_'.
--
--   * The header file `sys/stat.h' reserves names prefixed with `st_'
--     and `S_'.
--
--   * The header file `sys/times.h' reserves names prefixed with `tms_'.
--
--   * The header file `termios.h' reserves names prefixed with `c_',
--     `V', `I', `O', and `TC'; and names prefixed with `B' followed by a
--     digit.
--
--
--File: libc.info,  Node: Feature Test Macros,  Prev: Reserved Names,  Up: 
Using the Library
--
--Feature Test Macros
---------------------
--
--   The exact set of features available when you compile a source file
--is controlled by which "feature test macros" you define.
--
--   If you compile your programs using `gcc -ansi', you get only the
--ISO C library features, unless you explicitly request additional
--features by defining one or more of the feature macros.  *Note GNU CC
--Command Options: (gcc.info)Invoking GCC, for more information about GCC
--options.
--
--   You should define these macros by using `#define' preprocessor
--directives at the top of your source code files.  These directives
--*must* come before any `#include' of a system header file.  It is best
--to make them the very first thing in the file, preceded only by
--comments.  You could also use the `-D' option to GCC, but it's better
--if you make the source files indicate their own meaning in a
--self-contained way.
--
-- - Macro: _POSIX_SOURCE
--     If you define this macro, then the functionality from the POSIX.1
--     standard (IEEE Standard 1003.1) is available, as well as all of the
--     ISO C facilities.
--
-- - Macro: _POSIX_C_SOURCE
--     If you define this macro with a value of `1', then the
--     functionality from the POSIX.1 standard (IEEE Standard 1003.1) is
--     made available.  If you define this macro with a value of `2',
--     then both the functionality from the POSIX.1 standard and the
--     functionality from the POSIX.2 standard (IEEE Standard 1003.2) are
--     made available.  This is in addition to the ISO C facilities.
--
-- - Macro: _BSD_SOURCE
--     If you define this macro, functionality derived from 4.3 BSD Unix
--     is included as well as the ISO C, POSIX.1, and POSIX.2 material.
--
--     Some of the features derived from 4.3 BSD Unix conflict with the
--     corresponding features specified by the POSIX.1 standard.  If this
--     macro is defined, the 4.3 BSD definitions take precedence over the
--     POSIX definitions.
--
--     Due to the nature of some of the conflicts between 4.3 BSD and
--     POSIX.1, you need to use a special "BSD compatibility library"
--     when linking programs compiled for BSD compatibility.  This is
--     because some functions must be defined in two different ways, one
--     of them in the normal C library, and one of them in the
--     compatibility library.  If your program defines `_BSD_SOURCE', you
--     must give the option `-lbsd-compat' to the compiler or linker when
--     linking the program, to tell it to find functions in this special
--     compatibility library before looking for them in the normal C
--     library.
--
-- - Macro: _SVID_SOURCE
--     If you define this macro, functionality derived from SVID is
--     included as well as the ISO C, POSIX.1, POSIX.2, and X/Open
--     material.
--
-- - Macro: _XOPEN_SOURCE
--     If you define this macro, functionality described in the X/Open
--     Portability Guide is included.  This is a superset of the POSIX.1
--     and POSIX.2 functionality and in fact `_POSIX_SOURCE' and
--     `_POSIX_C_SOURCE' are automatically defined.
--
--     As the unification of all Unices, functionality only available in
--     BSD and SVID is also included.
--
--     If the macro `_XOPEN_SOURCE_EXTENDED' is also defined, even more
--     functionality is available.  The extra functions will make all
--     functions available which are necessary for the X/Open Unix brand.
--
-- - Macro: _GNU_SOURCE
--     If you define this macro, everything is included: ISO C, POSIX.1,
--     POSIX.2, BSD, SVID, X/Open, and GNU extensions.  In the cases where
--     POSIX.1 conflicts with BSD, the POSIX definitions take precedence.
--
--     If you want to get the full effect of `_GNU_SOURCE' but make the
--     BSD definitions take precedence over the POSIX definitions, use
--     this sequence of definitions:
--
--          #define _GNU_SOURCE
--          #define _BSD_SOURCE
--          #define _SVID_SOURCE
--
--     Note that if you do this, you must link your program with the BSD
--     compatibility library by passing the `-lbsd-compat' option to the
--     compiler or linker.  *Note:* If you forget to do this, you may get
--     very strange errors at run time.
--
-- - Macro: _REENTRANT
-- - Macro: _THREAD_SAFE
--     If you define one of these macros, reentrant versions of several
--     functions get declared.  Some of the functions are specified in
--     POSIX.1c but many others are only available on a few other systems
--     or are unique to GNU libc.  The problem is that the
--     standardization of the thread safe C library interface still is
--     behind.
--
--     Unlike on some other systems no special version of the C library
--     must be used for linking.  There is only one version but while
--     compiling this it must have been specified to compile as thread
--     safe.
--
--   We recommend you use `_GNU_SOURCE' in new programs.  If you don't
--specify the `-ansi' option to GCC and don't define any of these macros
--explicitly, the effect is the same as defining `_POSIX_C_SOURCE' to 2
--and `_POSIX_SOURCE', `_SVID_SOURCE', and `_BSD_SOURCE' to 1.
--
--   When you define a feature test macro to request a larger class of
--features, it is harmless to define in addition a feature test macro for
--a subset of those features.  For example, if you define
--`_POSIX_C_SOURCE', then defining `_POSIX_SOURCE' as well has no effect.
--Likewise, if you define `_GNU_SOURCE', then defining either
--`_POSIX_SOURCE' or `_POSIX_C_SOURCE' or `_SVID_SOURCE' as well has no
--effect.
--
--   Note, however, that the features of `_BSD_SOURCE' are not a subset of
--any of the other feature test macros supported.  This is because it
--defines BSD features that take precedence over the POSIX features that
--are requested by the other macros.  For this reason, defining
--`_BSD_SOURCE' in addition to the other feature test macros does have an
--effect: it causes the BSD features to take priority over the conflicting
--POSIX features.
--
--
--File: libc.info,  Node: Roadmap to the Manual,  Prev: Using the Library,  Up: 
Introduction
--
--Roadmap to the Manual
--=====================
--
--   Here is an overview of the contents of the remaining chapters of
--this manual.
--
--   * *Note Error Reporting::, describes how errors detected by the
--     library are reported.
--
--   * *Note Language Features::, contains information about library
--     support for standard parts of the C language, including things
--     like the `sizeof' operator and the symbolic constant `NULL', how
--     to write functions accepting variable numbers of arguments, and
--     constants describing the ranges and other properties of the
--     numerical types.  There is also a simple debugging mechanism which
--     allows you to put assertions in your code, and have diagnostic
--     messages printed if the tests fail.
--
--   * *Note Memory Allocation::, describes the GNU library's facilities
--     for dynamic allocation of storage.  If you do not know in advance
--     how much storage your program needs, you can allocate it
--     dynamically instead, and manipulate it via pointers.
--
--   * *Note Character Handling::, contains information about character
--     classification functions (such as `isspace') and functions for
--     performing case conversion.
--
--   * *Note String and Array Utilities::, has descriptions of functions
--     for manipulating strings (null-terminated character arrays) and
--     general byte arrays, including operations such as copying and
--     comparison.
--
--   * *Note I/O Overview::, gives an overall look at the input and output
--     facilities in the library, and contains information about basic
--     concepts such as file names.
--
--   * *Note I/O on Streams::, describes I/O operations involving streams
--     (or `FILE *' objects).  These are the normal C library functions
--     from `stdio.h'.
--
--   * *Note Low-Level I/O::, contains information about I/O operations
--     on file descriptors.  File descriptors are a lower-level mechanism
--     specific to the Unix family of operating systems.
--
--   * *Note File System Interface::, has descriptions of operations on
--     entire files, such as functions for deleting and renaming them and
--     for creating new directories.  This chapter also contains
--     information about how you can access the attributes of a file,
--     such as its owner and file protection modes.
--
--   * *Note Pipes and FIFOs::, contains information about simple
--     interprocess communication mechanisms.  Pipes allow communication
--     between two related processes (such as between a parent and
--     child), while FIFOs allow communication between processes sharing
--     a common file system on the same machine.
--
--   * *Note Sockets::, describes a more complicated interprocess
--     communication mechanism that allows processes running on different
--     machines to communicate over a network.  This chapter also
--     contains information about Internet host addressing and how to use
--     the system network databases.
--
--   * *Note Low-Level Terminal Interface::, describes how you can change
--     the attributes of a terminal device.  If you want to disable echo
--     of characters typed by the user, for example, read this chapter.
--
--   * *Note Mathematics::, contains information about the math library
--     functions.  These include things like random-number generators and
--     remainder functions on integers as well as the usual trigonometric
--     and exponential functions on floating-point numbers.
--
--   * *Note Low-Level Arithmetic Functions: Arithmetic, describes
--     functions for simple arithmetic, analysis of floating-point
--     values, and reading numbers from strings.
--
--   * *Note Searching and Sorting::, contains information about functions
--     for searching and sorting arrays.  You can use these functions on
--     any kind of array by providing an appropriate comparison function.
--
--   * *Note Pattern Matching::, presents functions for matching regular
--     expressions and shell file name patterns, and for expanding words
--     as the shell does.
--
--   * *Note Date and Time::, describes functions for measuring both
--     calendar time and CPU time, as well as functions for setting
--     alarms and timers.
--
--   * *Note Extended Characters::, contains information about
--     manipulating characters and strings using character sets larger
--     than will fit in the usual `char' data type.
--
--   * *Note Locales::, describes how selecting a particular country or
--     language affects the behavior of the library.  For example, the
--     locale affects collation sequences for strings and how monetary
--     values are formatted.
--
--   * *Note Non-Local Exits::, contains descriptions of the `setjmp' and
--     `longjmp' functions.  These functions provide a facility for
--     `goto'-like jumps which can jump from one function to another.
--
--   * *Note Signal Handling::, tells you all about signals--what they
--     are, how to establish a handler that is called when a particular
--     kind of signal is delivered, and how to prevent signals from
--     arriving during critical sections of your program.
--
--   * *Note Process Startup::, tells how your programs can access their
--     command-line arguments and environment variables.
--
--   * *Note Processes::, contains information about how to start new
--     processes and run programs.
--
--   * *Note Job Control::, describes functions for manipulating process
--     groups and the controlling terminal.  This material is probably
--     only of interest if you are writing a shell or other program which
--     handles job control specially.
--
--   * *Note Name Service Switch::, describes the services which are
--     available for looking up names in the system databases, how to
--     determine which service is used for which database, and how these
--     services are implemented so that contributors can design their own
--     services.
--
--   * *Note User Database::, and *Note Group Database::, tell you how to
--     access the system user and group databases.
--
--   * *Note System Information::, describes functions for getting
--     information about the hardware and software configuration your
--     program is executing under.
--
--   * *Note System Configuration::, tells you how you can get
--     information about various operating system limits.  Most of these
--     parameters are provided for compatibility with POSIX.
--
--   * *Note Library Summary::, gives a summary of all the functions,
--     variables, and macros in the library, with complete data types and
--     function prototypes, and says what standard or system each is
--     derived from.
--
--   * *Note Maintenance::, explains how to build and install the GNU C
--     library on your system, how to report any bugs you might find, and
--     how to add new functions or port the library to a new system.
--
--   If you already know the name of the facility you are interested in,
--you can look it up in *Note Library Summary::.  This gives you a
--summary of its syntax and a pointer to where you can find a more
--detailed description.  This appendix is particularly useful if you just
--want to verify the order and type of arguments to a function, for
--example.  It also tells you what standard or system each function,
--variable, or macro is derived from.
--
--
--File: libc.info,  Node: Error Reporting,  Next: Memory Allocation,  Prev: 
Introduction,  Up: Top
--
--Error Reporting
--***************
--
--   Many functions in the GNU C library detect and report error
--conditions, and sometimes your programs need to check for these error
--conditions.  For example, when you open an input file, you should
--verify that the file was actually opened correctly, and print an error
--message or take other appropriate action if the call to the library
--function failed.
--
--   This chapter describes how the error reporting facility works.  Your
--program should include the header file `errno.h' to use this facility.
--
--* Menu:
--
--* Checking for Errors::         How errors are reported by library functions.
--* Error Codes::                 Error code macros; all of these expand
--                                 into integer constant values.
--* Error Messages::              Mapping error codes onto error messages.
--
--
--File: libc.info,  Node: Checking for Errors,  Next: Error Codes,  Up: Error 
Reporting
--
--Checking for Errors
--===================
--
--   Most library functions return a special value to indicate that they
--have failed.  The special value is typically `-1', a null pointer, or a
--constant such as `EOF' that is defined for that purpose.  But this
--return value tells you only that an error has occurred.  To find out
--what kind of error it was, you need to look at the error code stored in
--the variable `errno'.  This variable is declared in the header file
--`errno.h'.
--
-- - Variable: volatile int errno
--     The variable `errno' contains the system error number.  You can
--     change the value of `errno'.
--
--     Since `errno' is declared `volatile', it might be changed
--     asynchronously by a signal handler; see *Note Defining Handlers::.
--     However, a properly written signal handler saves and restores the
--     value of `errno', so you generally do not need to worry about this
--     possibility except when writing signal handlers.
--
--     The initial value of `errno' at program startup is zero.  Many
--     library functions are guaranteed to set it to certain nonzero
--     values when they encounter certain kinds of errors.  These error
--     conditions are listed for each function.  These functions do not
--     change `errno' when they succeed; thus, the value of `errno' after
--     a successful call is not necessarily zero, and you should not use
--     `errno' to determine *whether* a call failed.  The proper way to
--     do that is documented for each function.  *If* the call the
--     failed, you can examine `errno'.
--
--     Many library functions can set `errno' to a nonzero value as a
--     result of calling other library functions which might fail.  You
--     should assume that any library function might alter `errno' when
--     the function returns an error.
--
--     *Portability Note:* ISO C specifies `errno' as a "modifiable
--     lvalue" rather than as a variable, permitting it to be implemented
--     as a macro.  For example, its expansion might involve a function
--     call, like `*_errno ()'.  In fact, that is what it is on the GNU
--     system itself.  The GNU library, on non-GNU systems, does whatever
--     is right for the particular system.
--
--     There are a few library functions, like `sqrt' and `atan', that
--     return a perfectly legitimate value in case of an error, but also
--     set `errno'.  For these functions, if you want to check to see
--     whether an error occurred, the recommended method is to set `errno'
--     to zero before calling the function, and then check its value
--     afterward.
--
--   All the error codes have symbolic names; they are macros defined in
--`errno.h'.  The names start with `E' and an upper-case letter or digit;
--you should consider names of this form to be reserved names.  *Note
--Reserved Names::.
--
--   The error code values are all positive integers and are all distinct,
--with one exception: `EWOULDBLOCK' and `EAGAIN' are the same.  Since the
--values are distinct, you can use them as labels in a `switch'
--statement; just don't use both `EWOULDBLOCK' and `EAGAIN'.  Your
--program should not make any other assumptions about the specific values
--of these symbolic constants.
--
--   The value of `errno' doesn't necessarily have to correspond to any
--of these macros, since some library functions might return other error
--codes of their own for other situations.  The only values that are
--guaranteed to be meaningful for a particular library function are the
--ones that this manual lists for that function.
--
--   On non-GNU systems, almost any system call can return `EFAULT' if it
--is given an invalid pointer as an argument.  Since this could only
--happen as a result of a bug in your program, and since it will not
--happen on the GNU system, we have saved space by not mentioning
--`EFAULT' in the descriptions of individual functions.
--
--   In some Unix systems, many system calls can also return `EFAULT' if
--given as an argument a pointer into the stack, and the kernel for some
--obscure reason fails in its attempt to extend the stack.  If this ever
--happens, you should probably try using statically or dynamically
--allocated memory instead of stack memory on that system.
--
--
--File: libc.info,  Node: Error Codes,  Next: Error Messages,  Prev: Checking 
for Errors,  Up: Error Reporting
--
--Error Codes
--===========
--
--   The error code macros are defined in the header file `errno.h'.  All
--of them expand into integer constant values.  Some of these error codes
--can't occur on the GNU system, but they can occur using the GNU library
--on other systems.
--
-- - Macro: int EPERM
--     Operation not permitted; only the owner of the file (or other
--     resource) or processes with special privileges can perform the
--     operation.
--
-- - Macro: int ENOENT
--     No such file or directory.  This is a "file doesn't exist" error
--     for ordinary files that are referenced in contexts where they are
--     expected to already exist.
--
-- - Macro: int ESRCH
--     No process matches the specified process ID.
--
-- - Macro: int EINTR
--     Interrupted function call; an asynchronous signal occurred and
--     prevented completion of the call.  When this happens, you should
--     try the call again.
--
--     You can choose to have functions resume after a signal that is
--     handled, rather than failing with `EINTR'; see *Note Interrupted
--     Primitives::.
--
-- - Macro: int EIO
--     Input/output error; usually used for physical read or write errors.
--
-- - Macro: int ENXIO
--     No such device or address.  The system tried to use the device
--     represented by a file you specified, and it couldn't find the
--     device.  This can mean that the device file was installed
--     incorrectly, or that the physical device is missing or not
--     correctly attached to the computer.
--
-- - Macro: int E2BIG
--     Argument list too long; used when the arguments passed to a new
--     program being executed with one of the `exec' functions (*note
--     Executing a File::.) occupy too much memory space.  This condition
--     never arises in the GNU system.
--
-- - Macro: int ENOEXEC
--     Invalid executable file format.  This condition is detected by the
--     `exec' functions; see *Note Executing a File::.
--
-- - Macro: int EBADF
--     Bad file descriptor; for example, I/O on a descriptor that has been
--     closed or reading from a descriptor open only for writing (or vice
--     versa).
--
-- - Macro: int ECHILD
--     There are no child processes.  This error happens on operations
--     that are supposed to manipulate child processes, when there aren't
--     any processes to manipulate.
--
-- - Macro: int EDEADLK
--     Deadlock avoided; allocating a system resource would have resulted
--     in a deadlock situation.  The system does not guarantee that it
--     will notice all such situations.  This error means you got lucky
--     and the system noticed; it might just hang.  *Note File Locks::,
--     for an example.
--
-- - Macro: int ENOMEM
--     No memory available.  The system cannot allocate more virtual
--     memory because its capacity is full.
--
-- - Macro: int EACCES
--     Permission denied; the file permissions do not allow the attempted
--     operation.
--
-- - Macro: int EFAULT
--     Bad address; an invalid pointer was detected.  In the GNU system,
--     this error never happens; you get a signal instead.
--
-- - Macro: int ENOTBLK
--     A file that isn't a block special file was given in a situation
--     that requires one.  For example, trying to mount an ordinary file
--     as a file system in Unix gives this error.
--
-- - Macro: int EBUSY
--     Resource busy; a system resource that can't be shared is already
--     in use.  For example, if you try to delete a file that is the root
--     of a currently mounted filesystem, you get this error.
--
-- - Macro: int EEXIST
--     File exists; an existing file was specified in a context where it
--     only makes sense to specify a new file.
--
-- - Macro: int EXDEV
--     An attempt to make an improper link across file systems was
--     detected.  This happens not only when you use `link' (*note Hard
--     Links::.) but also when you rename a file with `rename' (*note
--     Renaming Files::.).
--
-- - Macro: int ENODEV
--     The wrong type of device was given to a function that expects a
--     particular sort of device.
--
-- - Macro: int ENOTDIR
--     A file that isn't a directory was specified when a directory is
--     required.
--
-- - Macro: int EISDIR
--     File is a directory; you cannot open a directory for writing, or
--     create or remove hard links to it.
--
-- - Macro: int EINVAL
--     Invalid argument.  This is used to indicate various kinds of
--     problems with passing the wrong argument to a library function.
--
-- - Macro: int EMFILE
--     The current process has too many files open and can't open any
--     more.  Duplicate descriptors do count toward this limit.
--
--     In BSD and GNU, the number of open files is controlled by a
--     resource limit that can usually be increased.  If you get this
--     error, you might want to increase the `RLIMIT_NOFILE' limit or
--     make it unlimited; *note Limits on Resources::..
--
-- - Macro: int ENFILE
--     There are too many distinct file openings in the entire system.
--     Note that any number of linked channels count as just one file
--     opening; see *Note Linked Channels::.  This error never occurs in
--     the GNU system.
--
-- - Macro: int ENOTTY
--     Inappropriate I/O control operation, such as trying to set terminal
--     modes on an ordinary file.
--
-- - Macro: int ETXTBSY
--     An attempt to execute a file that is currently open for writing, or
--     write to a file that is currently being executed.  Often using a
--     debugger to run a program is considered having it open for writing
--     and will cause this error.  (The name stands for "text file
--     busy".)  This is not an error in the GNU system; the text is
--     copied as necessary.
--
-- - Macro: int EFBIG
--     File too big; the size of a file would be larger than allowed by
--     the system.
--
-- - Macro: int ENOSPC
--     No space left on device; write operation on a file failed because
--     the disk is full.
--
-- - Macro: int ESPIPE
--     Invalid seek operation (such as on a pipe).
--
-- - Macro: int EROFS
--     An attempt was made to modify something on a read-only file system.
--
-- - Macro: int EMLINK
--     Too many links; the link count of a single file would become too
--     large.  `rename' can cause this error if the file being renamed
--     already has as many links as it can take (*note Renaming Files::.).
--
-- - Macro: int EPIPE
--     Broken pipe; there is no process reading from the other end of a
--     pipe.  Every library function that returns this error code also
--     generates a `SIGPIPE' signal; this signal terminates the program
--     if not handled or blocked.  Thus, your program will never actually
--     see `EPIPE' unless it has handled or blocked `SIGPIPE'.
--
-- - Macro: int EDOM
--     Domain error; used by mathematical functions when an argument
--     value does not fall into the domain over which the function is
--     defined.
--
-- - Macro: int ERANGE
--     Range error; used by mathematical functions when the result value
--     is not representable because of overflow or underflow.
--
-- - Macro: int EAGAIN
--     Resource temporarily unavailable; the call might work if you try
--     again later.  The macro `EWOULDBLOCK' is another name for `EAGAIN';
--     they are always the same in the GNU C library.
--
--     This error can happen in a few different situations:
--
--        * An operation that would block was attempted on an object that
--          has non-blocking mode selected.  Trying the same operation
--          again will block until some external condition makes it
--          possible to read, write, or connect (whatever the operation).
--          You can use `select' to find out when the operation will be
--          possible; *note Waiting for I/O::..
--
--          *Portability Note:* In older Unix many systems, this condition
--          was indicated by `EWOULDBLOCK', which was a distinct error
--          code different from `EAGAIN'.  To make your program portable,
--          you should check for both codes and treat them the same.
--
--        * A temporary resource shortage made an operation impossible.
--          `fork' can return this error.  It indicates that the shortage
--          is expected to pass, so your program can try the call again
--          later and it may succeed.  It is probably a good idea to
--          delay for a few seconds before trying it again, to allow time
--          for other processes to release scarce resources.  Such
--          shortages are usually fairly serious and affect the whole
--          system, so usually an interactive program should report the
--          error to the user and return to its command loop.
--
-- - Macro: int EWOULDBLOCK
--     In the GNU C library, this is another name for `EAGAIN' (above).
--     The values are always the same, on every operating system.
--
--     C libraries in many older Unix systems have `EWOULDBLOCK' as a
--     separate error code.
--
-- - Macro: int EINPROGRESS
--     An operation that cannot complete immediately was initiated on an
--     object that has non-blocking mode selected.  Some functions that
--     must always block (such as `connect'; *note Connecting::.) never
--     return `EAGAIN'.  Instead, they return `EINPROGRESS' to indicate
--     that the operation has begun and will take some time.  Attempts to
--     manipulate the object before the call completes return `EALREADY'.
--     You can use the `select' function to find out when the pending
--     operation has completed; *note Waiting for I/O::..
--
-- - Macro: int EALREADY
--     An operation is already in progress on an object that has
--     non-blocking mode selected.
--
-- - Macro: int ENOTSOCK
--     A file that isn't a socket was specified when a socket is required.
--
-- - Macro: int EMSGSIZE
--     The size of a message sent on a socket was larger than the
--     supported maximum size.
--
-- - Macro: int EPROTOTYPE
--     The socket type does not support the requested communications
--     protocol.
--
-- - Macro: int ENOPROTOOPT
--     You specified a socket option that doesn't make sense for the
--     particular protocol being used by the socket.  *Note Socket
--     Options::.
--
-- - Macro: int EPROTONOSUPPORT
--     The socket domain does not support the requested communications
--     protocol (perhaps because the requested protocol is completely
--     invalid.) *Note Creating a Socket::.
--
-- - Macro: int ESOCKTNOSUPPORT
--     The socket type is not supported.
--
-- - Macro: int EOPNOTSUPP
--     The operation you requested is not supported.  Some socket
--     functions don't make sense for all types of sockets, and others
--     may not be implemented for all communications protocols.  In the
--     GNU system, this error can happen for many calls when the object
--     does not support the particular operation; it is a generic
--     indication that the server knows nothing to do for that call.
--
-- - Macro: int EPFNOSUPPORT
--     The socket communications protocol family you requested is not
--     supported.
--
-- - Macro: int EAFNOSUPPORT
--     The address family specified for a socket is not supported; it is
--     inconsistent with the protocol being used on the socket.  *Note
--     Sockets::.
--
-- - Macro: int EADDRINUSE
--     The requested socket address is already in use.  *Note Socket
--     Addresses::.
--
-- - Macro: int EADDRNOTAVAIL
--     The requested socket address is not available; for example, you
--     tried to give a socket a name that doesn't match the local host
--     name.  *Note Socket Addresses::.
--
-- - Macro: int ENETDOWN
--     A socket operation failed because the network was down.
--
-- - Macro: int ENETUNREACH
--     A socket operation failed because the subnet containing the remote
--     host was unreachable.
--
-- - Macro: int ENETRESET
--     A network connection was reset because the remote host crashed.
--
-- - Macro: int ECONNABORTED
--     A network connection was aborted locally.
--
-- - Macro: int ECONNRESET
--     A network connection was closed for reasons outside the control of
--     the local host, such as by the remote machine rebooting or an
--     unrecoverable protocol violation.
--
-- - Macro: int ENOBUFS
--     The kernel's buffers for I/O operations are all in use.  In GNU,
--     this error is always synonymous with `ENOMEM'; you may get one or
--     the other from network operations.
--
-- - Macro: int EISCONN
--     You tried to connect a socket that is already connected.  *Note
--     Connecting::.
--
-- - Macro: int ENOTCONN
--     The socket is not connected to anything.  You get this error when
--     you try to transmit data over a socket, without first specifying a
--     destination for the data.  For a connectionless socket (for
--     datagram protocols, such as UDP), you get `EDESTADDRREQ' instead.
--
-- - Macro: int EDESTADDRREQ
--     No default destination address was set for the socket.  You get
--     this error when you try to transmit data over a connectionless
--     socket, without first specifying a destination for the data with
--     `connect'.
--
-- - Macro: int ESHUTDOWN
--     The socket has already been shut down.
--
-- - Macro: int ETOOMANYREFS
--     ???
--
-- - Macro: int ETIMEDOUT
--     A socket operation with a specified timeout received no response
--     during the timeout period.
--
-- - Macro: int ECONNREFUSED
--     A remote host refused to allow the network connection (typically
--     because it is not running the requested service).
--
-- - Macro: int ELOOP
--     Too many levels of symbolic links were encountered in looking up a
--     file name.  This often indicates a cycle of symbolic links.
--
-- - Macro: int ENAMETOOLONG
--     Filename too long (longer than `PATH_MAX'; *note Limits for
--     Files::.) or host name too long (in `gethostname' or
--     `sethostname'; *note Host Identification::.).
--
-- - Macro: int EHOSTDOWN
--     The remote host for a requested network connection is down.
--
-- - Macro: int EHOSTUNREACH
--     The remote host for a requested network connection is not
--     reachable.
--
-- - Macro: int ENOTEMPTY
--     Directory not empty, where an empty directory was expected.
--     Typically, this error occurs when you are trying to delete a
--     directory.
--
-- - Macro: int EPROCLIM
--     This means that the per-user limit on new process would be
--     exceeded by an attempted `fork'.  *Note Limits on Resources::, for
--     details on the `RLIMIT_NPROC' limit.
--
-- - Macro: int EUSERS
--     The file quota system is confused because there are too many users.
--
-- - Macro: int EDQUOT
--     The user's disk quota was exceeded.
--
-- - Macro: int ESTALE
--     Stale NFS file handle.  This indicates an internal confusion in
--     the NFS system which is due to file system rearrangements on the
--     server host.  Repairing this condition usually requires unmounting
--     and remounting the NFS file system on the local host.
--
-- - Macro: int EREMOTE
--     An attempt was made to NFS-mount a remote file system with a file
--     name that already specifies an NFS-mounted file.  (This is an
--     error on some operating systems, but we expect it to work properly
--     on the GNU system, making this error code impossible.)
--
-- - Macro: int EBADRPC
--     ???
--
-- - Macro: int ERPCMISMATCH
--     ???
--
-- - Macro: int EPROGUNAVAIL
--     ???
--
-- - Macro: int EPROGMISMATCH
--     ???
--
-- - Macro: int EPROCUNAVAIL
--     ???
--
-- - Macro: int ENOLCK
--     No locks available.  This is used by the file locking facilities;
--     see *Note File Locks::.  This error is never generated by the GNU
--     system, but it can result from an operation to an NFS server
--     running another operating system.
--
-- - Macro: int EFTYPE
--     Inappropriate file type or format.  The file was the wrong type
--     for the operation, or a data file had the wrong format.
--
--     On some systems `chmod' returns this error if you try to set the
--     sticky bit on a non-directory file; *note Setting Permissions::..
--
-- - Macro: int EAUTH
--     ???
--
-- - Macro: int ENEEDAUTH
--     ???
--
-- - Macro: int ENOSYS
--     Function not implemented.  Some functions have commands or options
--     defined that might not be supported in all implementations, and
--     this is the kind of error you get if you request them and they are
--     not supported.
--
-- - Macro: int EILSEQ
--     While decoding a multibyte character the function came along an
--     invalid or an incomplete sequence of bytes or the given wide
--     character is invalid.
--
-- - Macro: int EBACKGROUND
--     In the GNU system, servers supporting the `term' protocol return
--     this error for certain operations when the caller is not in the
--     foreground process group of the terminal.  Users do not usually
--     see this error because functions such as `read' and `write'
--     translate it into a `SIGTTIN' or `SIGTTOU' signal.  *Note Job
--     Control::, for information on process groups and these signals.
--
-- - Macro: int EDIED
--     In the GNU system, opening a file returns this error when the file
--     is translated by a program and the translator program dies while
--     starting up, before it has connected to the file.
--
-- - Macro: int ED
--     The experienced user will know what is wrong.
--
-- - Macro: int EGREGIOUS
--     You did *what*?
--
-- - Macro: int EIEIO
--     Go home and have a glass of warm, dairy-fresh milk.
--
-- - Macro: int EGRATUITOUS
--     This error code has no purpose.
--
-- - Macro: int EBADMSG
--
-- - Macro: int EIDRM
--
-- - Macro: int EMULTIHOP
--
-- - Macro: int ENODATA
--
-- - Macro: int ENOLINK
--
-- - Macro: int ENOMSG
--
-- - Macro: int ENOSR
--
-- - Macro: int ENOSTR
--
-- - Macro: int EOVERFLOW
--
-- - Macro: int EPROTO
--
-- - Macro: int ETIME
--
--   *The following error codes are defined by the Linux/i386 kernel.
--They are not yet documented.*
--
-- - Macro: int ERESTART
--
-- - Macro: int ECHRNG
--
-- - Macro: int EL2NSYNC
--
-- - Macro: int EL3HLT
--
-- - Macro: int EL3RST
--
-- - Macro: int ELNRNG
--
-- - Macro: int EUNATCH
--
-- - Macro: int ENOCSI
--
-- - Macro: int EL2HLT
--
-- - Macro: int EBADE
--
-- - Macro: int EBADR
--
-- - Macro: int EXFULL
--
-- - Macro: int ENOANO
--
-- - Macro: int EBADRQC
--
-- - Macro: int EBADSLT
--
-- - Macro: int EDEADLOCK
--
-- - Macro: int EBFONT
--
-- - Macro: int ENONET
--
-- - Macro: int ENOPKG
--
-- - Macro: int EADV
--
-- - Macro: int ESRMNT
--
-- - Macro: int ECOMM
--
-- - Macro: int EDOTDOT
--
-- - Macro: int ENOTUNIQ
--
-- - Macro: int EBADFD
--
-- - Macro: int EREMCHG
--
-- - Macro: int ELIBACC
--
-- - Macro: int ELIBBAD
--
-- - Macro: int ELIBSCN
--
-- - Macro: int ELIBMAX
--
-- - Macro: int ELIBEXEC
--
-- - Macro: int ESTRPIPE
--
-- - Macro: int EUCLEAN
--
-- - Macro: int ENOTNAM
--
-- - Macro: int ENAVAIL
--
-- - Macro: int EISNAM
--
-- - Macro: int EREMOTEIO
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-20 
glibc-2.0.1/manual/libc.info-20
---- ../glibc-2.0.1/manual/libc.info-20 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-20    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1220 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Standard Signals,  Next: Signal Actions,  Prev: 
Concepts of Signals,  Up: Signal Handling
--
--Standard Signals
--================
--
--   This section lists the names for various standard kinds of signals
--and describes what kind of event they mean.  Each signal name is a macro
--which stands for a positive integer--the "signal number" for that kind
--of signal.  Your programs should never make assumptions about the
--numeric code for a particular kind of signal, but rather refer to them
--always by the names defined here.  This is because the number for a
--given kind of signal can vary from system to system, but the meanings of
--the names are standardized and fairly uniform.
--
--   The signal names are defined in the header file `signal.h'.
--
-- - Macro: int NSIG
--     The value of this symbolic constant is the total number of signals
--     defined.  Since the signal numbers are allocated consecutively,
--     `NSIG' is also one greater than the largest defined signal number.
--
--* Menu:
--
--* Program Error Signals::       Used to report serious program errors.
--* Termination Signals::         Used to interrupt and/or terminate the
--                                 program.
--* Alarm Signals::               Used to indicate expiration of timers.
--* Asynchronous I/O Signals::    Used to indicate input is available.
--* Job Control Signals::         Signals used to support job control.
--* Operation Error Signals::     Used to report operational system errors.
--* Miscellaneous Signals::       Miscellaneous Signals.
--* Signal Messages::             Printing a message describing a signal.
--
--
--File: libc.info,  Node: Program Error Signals,  Next: Termination Signals,  
Up: Standard Signals
--
--Program Error Signals
-----------------------
--
--   The following signals are generated when a serious program error is
--detected by the operating system or the computer itself.  In general,
--all of these signals are indications that your program is seriously
--broken in some way, and there's usually no way to continue the
--computation which encountered the error.
--
--   Some programs handle program error signals in order to tidy up before
--terminating; for example, programs that turn off echoing of terminal
--input should handle program error signals in order to turn echoing back
--on.  The handler should end by specifying the default action for the
--signal that happened and then reraising it; this will cause the program
--to terminate with that signal, as if it had not had a handler.  (*Note
--Termination in Handler::.)
--
--   Termination is the sensible ultimate outcome from a program error in
--most programs.  However, programming systems such as Lisp that can load
--compiled user programs might need to keep executing even if a user
--program incurs an error.  These programs have handlers which use
--`longjmp' to return control to the command level.
--
--   The default action for all of these signals is to cause the process
--to terminate.  If you block or ignore these signals or establish
--handlers for them that return normally, your program will probably
--break horribly when such signals happen, unless they are generated by
--`raise' or `kill' instead of a real error.
--
--   When one of these program error signals terminates a process, it also
--writes a "core dump file" which records the state of the process at the
--time of termination.  The core dump file is named `core' and is written
--in whichever directory is current in the process at the time.  (On the
--GNU system, you can specify the file name for core dumps with the
--environment variable `COREFILE'.)  The purpose of core dump files is so
--that you can examine them with a debugger to investigate what caused
--the error.
--
-- - Macro: int SIGFPE
--     The `SIGFPE' signal reports a fatal arithmetic error.  Although the
--     name is derived from "floating-point exception", this signal
--     actually covers all arithmetic errors, including division by zero
--     and overflow.  If a program stores integer data in a location
--     which is then used in a floating-point operation, this often
--     causes an "invalid operation" exception, because the processor
--     cannot recognize the data as a floating-point number.
--
--     Actual floating-point exceptions are a complicated subject because
--     there are many types of exceptions with subtly different meanings,
--     and the `SIGFPE' signal doesn't distinguish between them.  The
--     `IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std
--     754-1985 and ANSI/IEEE Std 854-1987)' defines various
--     floating-point exceptions and requires conforming computer systems
--     to report their occurrences.  However, this standard does not
--     specify how the exceptions are reported, or what kinds of handling
--     and control the operating system can offer to the programmer.
--
--   BSD systems provide the `SIGFPE' handler with an extra argument that
--distinguishes various causes of the exception.  In order to access this
--argument, you must define the handler to accept two arguments, which
--means you must cast it to a one-argument function type in order to
--establish the handler.  The GNU library does provide this extra
--argument, but the value is meaningful only on operating systems that
--provide the information (BSD systems and GNU systems).
--
--`FPE_INTOVF_TRAP'
--     Integer overflow (impossible in a C program unless you enable
--     overflow trapping in a hardware-specific fashion).
--
--`FPE_INTDIV_TRAP'
--     Integer division by zero.
--
--`FPE_SUBRNG_TRAP'
--     Subscript-range (something that C programs never check for).
--
--`FPE_FLTOVF_TRAP'
--     Floating overflow trap.
--
--`FPE_FLTDIV_TRAP'
--     Floating/decimal division by zero.
--
--`FPE_FLTUND_TRAP'
--     Floating underflow trap.  (Trapping on floating underflow is not
--     normally enabled.)
--
--`FPE_DECOVF_TRAP'
--     Decimal overflow trap.  (Only a few machines have decimal
--     arithmetic and C never uses it.)
--
-- - Macro: int SIGILL
--     The name of this signal is derived from "illegal instruction"; it
--     usually means your program is trying to execute garbage or a
--     privileged instruction.  Since the C compiler generates only valid
--     instructions, `SIGILL' typically indicates that the executable
--     file is corrupted, or that you are trying to execute data.  Some
--     common ways of getting into the latter situation are by passing an
--     invalid object where a pointer to a function was expected, or by
--     writing past the end of an automatic array (or similar problems
--     with pointers to automatic variables) and corrupting other data on
--     the stack such as the return address of a stack frame.
--
--     `SIGILL' can also be generated when the stack overflows, or when
--     the system has trouble running the handler for a signal.
--
-- - Macro: int SIGSEGV
--     This signal is generated when a program tries to read or write
--     outside the memory that is allocated for it, or to write memory
--     that can only be read.  (Actually, the signals only occur when the
--     program goes far enough outside to be detected by the system's
--     memory protection mechanism.)  The name is an abbreviation for
--     "segmentation violation".
--
--     Common ways of getting a `SIGSEGV' condition include dereferencing
--     a null or uninitialized pointer, or when you use a pointer to step
--     through an array, but fail to check for the end of the array.  It
--     varies among systems whether dereferencing a null pointer generates
--     `SIGSEGV' or `SIGBUS'.
--
-- - Macro: int SIGBUS
--     This signal is generated when an invalid pointer is dereferenced.
--     Like `SIGSEGV', this signal is typically the result of
--     dereferencing an uninitialized pointer.  The difference between
--     the two is that `SIGSEGV' indicates an invalid access to valid
--     memory, while `SIGBUS' indicates an access to an invalid address.
--     In particular, `SIGBUS' signals often result from dereferencing a
--     misaligned pointer, such as referring to a four-word integer at an
--     address not divisible by four.  (Each kind of computer has its own
--     requirements for address alignment.)
--
--     The name of this signal is an abbreviation for "bus error".
--
-- - Macro: int SIGABRT
--     This signal indicates an error detected by the program itself and
--     reported by calling `abort'.  *Note Aborting a Program::.
--
-- - Macro: int SIGIOT
--     Generated by the PDP-11 "iot" instruction.  On most machines, this
--     is just another name for `SIGABRT'.
--
-- - Macro: int SIGTRAP
--     Generated by the machine's breakpoint instruction, and possibly
--     other trap instructions.  This signal is used by debuggers.  Your
--     program will probably only see `SIGTRAP' if it is somehow
--     executing bad instructions.
--
-- - Macro: int SIGEMT
--     Emulator trap; this results from certain unimplemented instructions
--     which might be emulated in software, or the operating system's
--     failure to properly emulate them.
--
-- - Macro: int SIGSYS
--     Bad system call; that is to say, the instruction to trap to the
--     operating system was executed, but the code number for the system
--     call to perform was invalid.
--
--
--File: libc.info,  Node: Termination Signals,  Next: Alarm Signals,  Prev: 
Program Error Signals,  Up: Standard Signals
--
--Termination Signals
---------------------
--
--   These signals are all used to tell a process to terminate, in one way
--or another.  They have different names because they're used for slightly
--different purposes, and programs might want to handle them differently.
--
--   The reason for handling these signals is usually so your program can
--tidy up as appropriate before actually terminating.  For example, you
--might want to save state information, delete temporary files, or restore
--the previous terminal modes.  Such a handler should end by specifying
--the default action for the signal that happened and then reraising it;
--this will cause the program to terminate with that signal, as if it had
--not had a handler.  (*Note Termination in Handler::.)
--
--   The (obvious) default action for all of these signals is to cause the
--process to terminate.
--
-- - Macro: int SIGTERM
--     The `SIGTERM' signal is a generic signal used to cause program
--     termination.  Unlike `SIGKILL', this signal can be blocked,
--     handled, and ignored.  It is the normal way to politely ask a
--     program to terminate.
--
--     The shell command `kill' generates `SIGTERM' by default.
--
-- - Macro: int SIGINT
--     The `SIGINT' ("program interrupt") signal is sent when the user
--     types the INTR character (normally `C-c').  *Note Special
--     Characters::, for information about terminal driver support for
--     `C-c'.
--
-- - Macro: int SIGQUIT
--     The `SIGQUIT' signal is similar to `SIGINT', except that it's
--     controlled by a different key--the QUIT character, usually
--     `C-\'--and produces a core dump when it terminates the process,
--     just like a program error signal.  You can think of this as a
--     program error condition "detected" by the user.
--
--     *Note Program Error Signals::, for information about core dumps.
--     *Note Special Characters::, for information about terminal driver
--     support.
--
--     Certain kinds of cleanups are best omitted in handling `SIGQUIT'.
--     For example, if the program creates temporary files, it should
--     handle the other termination requests by deleting the temporary
--     files.  But it is better for `SIGQUIT' not to delete them, so that
--     the user can examine them in conjunction with the core dump.
--
-- - Macro: int SIGKILL
--     The `SIGKILL' signal is used to cause immediate program
--     termination.  It cannot be handled or ignored, and is therefore
--     always fatal.  It is also not possible to block this signal.
--
--     This signal is usually generated only by explicit request.  Since
--     it cannot be handled, you should generate it only as a last
--     resort, after first trying a less drastic method such as `C-c' or
--     `SIGTERM'.  If a process does not respond to any other termination
--     signals, sending it a `SIGKILL' signal will almost always cause it
--     to go away.
--
--     In fact, if `SIGKILL' fails to terminate a process, that by itself
--     constitutes an operating system bug which you should report.
--
--     The system will generate `SIGKILL' for a process itself under some
--     unusual conditions where the program cannot possible continue to
--     run (even to run a signal handler).
--
-- - Macro: int SIGHUP
--     The `SIGHUP' ("hang-up") signal is used to report that the user's
--     terminal is disconnected, perhaps because a network or telephone
--     connection was broken.  For more information about this, see *Note
--     Control Modes::.
--
--     This signal is also used to report the termination of the
--     controlling process on a terminal to jobs associated with that
--     session; this termination effectively disconnects all processes in
--     the session from the controlling terminal.  For more information,
--     see *Note Termination Internals::.
--
--
--File: libc.info,  Node: Alarm Signals,  Next: Asynchronous I/O Signals,  
Prev: Termination Signals,  Up: Standard Signals
--
--Alarm Signals
---------------
--
--   These signals are used to indicate the expiration of timers.  *Note
--Setting an Alarm::, for information about functions that cause these
--signals to be sent.
--
--   The default behavior for these signals is to cause program
--termination.  This default is rarely useful, but no other default would
--be useful; most of the ways of using these signals would require
--handler functions in any case.
--
-- - Macro: int SIGALRM
--     This signal typically indicates expiration of a timer that
--     measures real or clock time.  It is used by the `alarm' function,
--     for example.
--
-- - Macro: int SIGVTALRM
--     This signal typically indicates expiration of a timer that
--     measures CPU time used by the current process.  The name is an
--     abbreviation for "virtual time alarm".
--
-- - Macro: int SIGPROF
--     This signal is typically indicates expiration of a timer that
--     measures both CPU time used by the current process, and CPU time
--     expended on behalf of the process by the system.  Such a timer is
--     used to implement code profiling facilities, hence the name of
--     this signal.
--
--
--File: libc.info,  Node: Asynchronous I/O Signals,  Next: Job Control Signals, 
 Prev: Alarm Signals,  Up: Standard Signals
--
--Asynchronous I/O Signals
--------------------------
--
--   The signals listed in this section are used in conjunction with
--asynchronous I/O facilities.  You have to take explicit action by
--calling `fcntl' to enable a particular file descriptor to generate
--these signals (*note Interrupt Input::.).  The default action for these
--signals is to ignore them.
--
-- - Macro: int SIGIO
--     This signal is sent when a file descriptor is ready to perform
--     input or output.
--
--     On most operating systems, terminals and sockets are the only
--     kinds of files that can generate `SIGIO'; other kinds, including
--     ordinary files, never generate `SIGIO' even if you ask them to.
--
--     In the GNU system `SIGIO' will always be generated properly if you
--     successfully set asynchronous mode with `fcntl'.
--
-- - Macro: int SIGURG
--     This signal is sent when "urgent" or out-of-band data arrives on a
--     socket.  *Note Out-of-Band Data::.
--
-- - Macro: int SIGPOLL
--     This is a System V signal name, more or less similar to `SIGIO'.
--     It is defined only for compatibility.
--
--
--File: libc.info,  Node: Job Control Signals,  Next: Operation Error Signals,  
Prev: Asynchronous I/O Signals,  Up: Standard Signals
--
--Job Control Signals
---------------------
--
--   These signals are used to support job control.  If your system
--doesn't support job control, then these macros are defined but the
--signals themselves can't be raised or handled.
--
--   You should generally leave these signals alone unless you really
--understand how job control works.  *Note Job Control::.
--
-- - Macro: int SIGCHLD
--     This signal is sent to a parent process whenever one of its child
--     processes terminates or stops.
--
--     The default action for this signal is to ignore it.  If you
--     establish a handler for this signal while there are child
--     processes that have terminated but not reported their status via
--     `wait' or `waitpid' (*note Process Completion::.), whether your
--     new handler applies to those processes or not depends on the
--     particular operating system.
--
-- - Macro: int SIGCLD
--     This is an obsolete name for `SIGCHLD'.
--
-- - Macro: int SIGCONT
--     You can send a `SIGCONT' signal to a process to make it continue.
--     This signal is special--it always makes the process continue if it
--     is stopped, before the signal is delivered.  The default behavior
--     is to do nothing else.  You cannot block this signal.  You can set
--     a handler, but `SIGCONT' always makes the process continue
--     regardless.
--
--     Most programs have no reason to handle `SIGCONT'; they simply
--     resume execution without realizing they were ever stopped.  You
--     can use a handler for `SIGCONT' to make a program do something
--     special when it is stopped and continued--for example, to reprint
--     a prompt when it is suspended while waiting for input.
--
-- - Macro: int SIGSTOP
--     The `SIGSTOP' signal stops the process.  It cannot be handled,
--     ignored, or blocked.
--
-- - Macro: int SIGTSTP
--     The `SIGTSTP' signal is an interactive stop signal.  Unlike
--     `SIGSTOP', this signal can be handled and ignored.
--
--     Your program should handle this signal if you have a special need
--     to leave files or system tables in a secure state when a process is
--     stopped.  For example, programs that turn off echoing should handle
--     `SIGTSTP' so they can turn echoing back on before stopping.
--
--     This signal is generated when the user types the SUSP character
--     (normally `C-z').  For more information about terminal driver
--     support, see *Note Special Characters::.
--
-- - Macro: int SIGTTIN
--     A process cannot read from the the user's terminal while it is
--     running as a background job.  When any process in a background job
--     tries to read from the terminal, all of the processes in the job
--     are sent a `SIGTTIN' signal.  The default action for this signal
--     is to stop the process.  For more information about how this
--     interacts with the terminal driver, see *Note Access to the
--     Terminal::.
--
-- - Macro: int SIGTTOU
--     This is similar to `SIGTTIN', but is generated when a process in a
--     background job attempts to write to the terminal or set its modes.
--     Again, the default action is to stop the process.  `SIGTTOU' is
--     only generated for an attempt to write to the terminal if the
--     `TOSTOP' output mode is set; *note Output Modes::..
--
--   While a process is stopped, no more signals can be delivered to it
--until it is continued, except `SIGKILL' signals and (obviously)
--`SIGCONT' signals.  The signals are marked as pending, but not
--delivered until the process is continued.  The `SIGKILL' signal always
--causes termination of the process and can't be blocked, handled or
--ignored.  You can ignore `SIGCONT', but it always causes the process to
--be continued anyway if it is stopped.  Sending a `SIGCONT' signal to a
--process causes any pending stop signals for that process to be
--discarded.  Likewise, any pending `SIGCONT' signals for a process are
--discarded when it receives a stop signal.
--
--   When a process in an orphaned process group (*note Orphaned Process
--Groups::.) receives a `SIGTSTP', `SIGTTIN', or `SIGTTOU' signal and
--does not handle it, the process does not stop.  Stopping the process
--would probably not be very useful, since there is no shell program that
--will notice it stop and allow the user to continue it.  What happens
--instead depends on the operating system you are using.  Some systems
--may do nothing; others may deliver another signal instead, such as
--`SIGKILL' or `SIGHUP'.  In the GNU system, the process dies with
--`SIGKILL'; this avoids the problem of many stopped, orphaned processes
--lying around the system.
--
--
--File: libc.info,  Node: Operation Error Signals,  Next: Miscellaneous 
Signals,  Prev: Job Control Signals,  Up: Standard Signals
--
--Operation Error Signals
-------------------------
--
--   These signals are used to report various errors generated by an
--operation done by the program.  They do not necessarily indicate a
--programming error in the program, but an error that prevents an
--operating system call from completing.  The default action for all of
--them is to cause the process to terminate.
--
-- - Macro: int SIGPIPE
--     Broken pipe.  If you use pipes or FIFOs, you have to design your
--     application so that one process opens the pipe for reading before
--     another starts writing.  If the reading process never starts, or
--     terminates unexpectedly, writing to the pipe or FIFO raises a
--     `SIGPIPE' signal.  If `SIGPIPE' is blocked, handled or ignored,
--     the offending call fails with `EPIPE' instead.
--
--     Pipes and FIFO special files are discussed in more detail in *Note
--     Pipes and FIFOs::.
--
--     Another cause of `SIGPIPE' is when you try to output to a socket
--     that isn't connected.  *Note Sending Data::.
--
-- - Macro: int SIGLOST
--     Resource lost.  This signal is generated when you have an advisory
--     lock on an NFS file, and the NFS server reboots and forgets about
--     your lock.
--
--     In the GNU system, `SIGLOST' is generated when any server program
--     dies unexpectedly.  It is usually fine to ignore the signal;
--     whatever call was made to the server that died just returns an
--     error.
--
-- - Macro: int SIGXCPU
--     CPU time limit exceeded.  This signal is generated when the process
--     exceeds its soft resource limit on CPU time.  *Note Limits on
--     Resources::.
--
-- - Macro: int SIGXFSZ
--     File size limit exceeded.  This signal is generated when the
--     process attempts to extend a file so it exceeds the process's soft
--     resource limit on file size.  *Note Limits on Resources::.
--
--
--File: libc.info,  Node: Miscellaneous Signals,  Next: Signal Messages,  Prev: 
Operation Error Signals,  Up: Standard Signals
--
--Miscellaneous Signals
-----------------------
--
--   These signals are used for various other purposes.  In general, they
--will not affect your program unless it explicitly uses them for
--something.
--
-- - Macro: int SIGUSR1
--
-- - Macro: int SIGUSR2
--     The `SIGUSR1' and `SIGUSR2' signals are set aside for you to use
--     any way you want.  They're useful for simple interprocess
--     communication, if you write a signal handler for them in the
--     program that receives the signal.
--
--     There is an example showing the use of `SIGUSR1' and `SIGUSR2' in
--     *Note Signaling Another Process::.
--
--     The default action is to terminate the process.
--
-- - Macro: int SIGWINCH
--     Window size change.  This is generated on some systems (including
--     GNU) when the terminal driver's record of the number of rows and
--     columns on the screen is changed.  The default action is to ignore
--     it.
--
--     If a program does full-screen display, it should handle `SIGWINCH'.
--     When the signal arrives, it should fetch the new screen size and
--     reformat its display accordingly.
--
-- - Macro: int SIGINFO
--     Information request.  In 4.4 BSD and the GNU system, this signal
--     is sent to all the processes in the foreground process group of
--     the controlling terminal when the user types the STATUS character
--     in canonical mode; *note Signal Characters::..
--
--     If the process is the leader of the process group, the default
--     action is to print some status information about the system and
--     what the process is doing.  Otherwise the default is to do nothing.
--
--
--File: libc.info,  Node: Signal Messages,  Prev: Miscellaneous Signals,  Up: 
Standard Signals
--
--Signal Messages
-----------------
--
--   We mentioned above that the shell prints a message describing the
--signal that terminated a child process.  The clean way to print a
--message describing a signal is to use the functions `strsignal' and
--`psignal'.  These functions use a signal number to specify which kind
--of signal to describe.  The signal number may come from the termination
--status of a child process (*note Process Completion::.) or it may come
--from a signal handler in the same process.
--
-- - Function: char * strsignal (int SIGNUM)
--     This function returns a pointer to a statically-allocated string
--     containing a message describing the signal SIGNUM.  You should not
--     modify the contents of this string; and, since it can be rewritten
--     on subsequent calls, you should save a copy of it if you need to
--     reference it later.
--
--     This function is a GNU extension, declared in the header file
--     `string.h'.
--
-- - Function: void psignal (int SIGNUM, const char *MESSAGE)
--     This function prints a message describing the signal SIGNUM to the
--     standard error output stream `stderr'; see *Note Standard
--     Streams::.
--
--     If you call `psignal' with a MESSAGE that is either a null pointer
--     or an empty string, `psignal' just prints the message
--     corresponding to SIGNUM, adding a trailing newline.
--
--     If you supply a non-null MESSAGE argument, then `psignal' prefixes
--     its output with this string.  It adds a colon and a space
--     character to separate the MESSAGE from the string corresponding to
--     SIGNUM.
--
--     This function is a BSD feature, declared in the header file
--     `signal.h'.
--
--   There is also an array `sys_siglist' which contains the messages for
--the various signal codes.  This array exists on BSD systems, unlike
--`strsignal'.
--
--
--File: libc.info,  Node: Signal Actions,  Next: Defining Handlers,  Prev: 
Standard Signals,  Up: Signal Handling
--
--Specifying Signal Actions
--=========================
--
--   The simplest way to change the action for a signal is to use the
--`signal' function.  You can specify a built-in action (such as to
--ignore the signal), or you can "establish a handler".
--
--   The GNU library also implements the more versatile `sigaction'
--facility.  This section describes both facilities and gives suggestions
--on which to use when.
--
--* Menu:
--
--* Basic Signal Handling::       The simple `signal' function.
--* Advanced Signal Handling::    The more powerful `sigaction' function.
--* Signal and Sigaction::        How those two functions interact.
--* Sigaction Function Example::  An example of using the sigaction function.
--* Flags for Sigaction::         Specifying options for signal handling.
--* Initial Signal Actions::      How programs inherit signal actions.
--
--
--File: libc.info,  Node: Basic Signal Handling,  Next: Advanced Signal 
Handling,  Up: Signal Actions
--
--Basic Signal Handling
-----------------------
--
--   The `signal' function provides a simple interface for establishing
--an action for a particular signal.  The function and associated macros
--are declared in the header file `signal.h'.
--
-- - Data Type: sighandler_t
--     This is the type of signal handler functions.  Signal handlers
--     take one integer argument specifying the signal number, and have
--     return type `void'.  So, you should define handler functions like
--     this:
--
--          void HANDLER (int `signum') { ... }
--
--     The name `sighandler_t' for this data type is a GNU extension.
--
-- - Function: sighandler_t signal (int SIGNUM, sighandler_t ACTION)
--     The `signal' function establishes ACTION as the action for the
--     signal SIGNUM.
--
--     The first argument, SIGNUM, identifies the signal whose behavior
--     you want to control, and should be a signal number.  The proper
--     way to specify a signal number is with one of the symbolic signal
--     names described in *Note Standard Signals::--don't use an explicit
--     number, because the numerical code for a given kind of signal may
--     vary from operating system to operating system.
--
--     The second argument, ACTION, specifies the action to use for the
--     signal SIGNUM.  This can be one of the following:
--
--    `SIG_DFL'
--          `SIG_DFL' specifies the default action for the particular
--          signal.  The default actions for various kinds of signals are
--          stated in *Note Standard Signals::.
--
--    `SIG_IGN'
--          `SIG_IGN' specifies that the signal should be ignored.
--
--          Your program generally should not ignore signals that
--          represent serious events or that are normally used to request
--          termination.  You cannot ignore the `SIGKILL' or `SIGSTOP'
--          signals at all.  You can ignore program error signals like
--          `SIGSEGV', but ignoring the error won't enable the program to
--          continue executing meaningfully.  Ignoring user requests such
--          as `SIGINT', `SIGQUIT', and `SIGTSTP' is unfriendly.
--
--          When you do not wish signals to be delivered during a certain
--          part of the program, the thing to do is to block them, not
--          ignore them.  *Note Blocking Signals::.
--
--    `HANDLER'
--          Supply the address of a handler function in your program, to
--          specify running this handler as the way to deliver the signal.
--
--          For more information about defining signal handler functions,
--          see *Note Defining Handlers::.
--
--     If you set the action for a signal to `SIG_IGN', or if you set it
--     to `SIG_DFL' and the default action is to ignore that signal, then
--     any pending signals of that type are discarded (even if they are
--     blocked).  Discarding the pending signals means that they will
--     never be delivered, not even if you subsequently specify another
--     action and unblock this kind of signal.
--
--     The `signal' function returns the action that was previously in
--     effect for the specified SIGNUM.  You can save this value and
--     restore it later by calling `signal' again.
--
--     If `signal' can't honor the request, it returns `SIG_ERR' instead.
--     The following `errno' error conditions are defined for this
--     function:
--
--    `EINVAL'
--          You specified an invalid SIGNUM; or you tried to ignore or
--          provide a handler for `SIGKILL' or `SIGSTOP'.
--
--   Here is a simple example of setting up a handler to delete temporary
--files when certain fatal signals happen:
--
--     #include <signal.h>
--     
--     void
--     termination_handler (int signum)
--     {
--       struct temp_file *p;
--     
--       for (p = temp_file_list; p; p = p->next)
--         unlink (p->name);
--     }
--     
--     int
--     main (void)
--     {
--       ...
--       if (signal (SIGINT, termination_handler) == SIG_IGN)
--         signal (SIGINT, SIG_IGN);
--       if (signal (SIGHUP, termination_handler) == SIG_IGN)
--         signal (SIGHUP, SIG_IGN);
--       if (signal (SIGTERM, termination_handler) == SIG_IGN)
--         signal (SIGTERM, SIG_IGN);
--       ...
--     }
--
--Note how if a given signal was previously set to be ignored, this code
--avoids altering that setting.  This is because non-job-control shells
--often ignore certain signals when starting children, and it is important
--for the children to respect this.
--
--   We do not handle `SIGQUIT' or the program error signals in this
--example because these are designed to provide information for debugging
--(a core dump), and the temporary files may give useful information.
--
-- - Function: sighandler_t ssignal (int SIGNUM, sighandler_t ACTION)
--     The `ssignal' function does the same thing as `signal'; it is
--     provided only for compatibility with SVID.
--
-- - Macro: sighandler_t SIG_ERR
--     The value of this macro is used as the return value from `signal'
--     to indicate an error.
--
--
--File: libc.info,  Node: Advanced Signal Handling,  Next: Signal and 
Sigaction,  Prev: Basic Signal Handling,  Up: Signal Actions
--
--Advanced Signal Handling
--------------------------
--
--   The `sigaction' function has the same basic effect as `signal': to
--specify how a signal should be handled by the process.  However,
--`sigaction' offers more control, at the expense of more complexity.  In
--particular, `sigaction' allows you to specify additional flags to
--control when the signal is generated and how the handler is invoked.
--
--   The `sigaction' function is declared in `signal.h'.
--
-- - Data Type: struct sigaction
--     Structures of type `struct sigaction' are used in the `sigaction'
--     function to specify all the information about how to handle a
--     particular signal.  This structure contains at least the following
--     members:
--
--    `sighandler_t sa_handler'
--          This is used in the same way as the ACTION argument to the
--          `signal' function.  The value can be `SIG_DFL', `SIG_IGN', or
--          a function pointer.  *Note Basic Signal Handling::.
--
--    `sigset_t sa_mask'
--          This specifies a set of signals to be blocked while the
--          handler runs.  Blocking is explained in *Note Blocking for
--          Handler::.  Note that the signal that was delivered is
--          automatically blocked by default before its handler is
--          started; this is true regardless of the value in `sa_mask'.
--          If you want that signal not to be blocked within its handler,
--          you must write code in the handler to unblock it.
--
--    `int sa_flags'
--          This specifies various flags which can affect the behavior of
--          the signal.  These are described in more detail in *Note
--          Flags for Sigaction::.
--
-- - Function: int sigaction (int SIGNUM, const struct sigaction *ACTION,
--          struct sigaction *OLD-ACTION)
--     The ACTION argument is used to set up a new action for the signal
--     SIGNUM, while the OLD-ACTION argument is used to return
--     information about the action previously associated with this
--     symbol.  (In other words, OLD-ACTION has the same purpose as the
--     `signal' function's return value--you can check to see what the
--     old action in effect for the signal was, and restore it later if
--     you want.)
--
--     Either ACTION or OLD-ACTION can be a null pointer.  If OLD-ACTION
--     is a null pointer, this simply suppresses the return of
--     information about the old action.  If ACTION is a null pointer,
--     the action associated with the signal SIGNUM is unchanged; this
--     allows you to inquire about how a signal is being handled without
--     changing that handling.
--
--     The return value from `sigaction' is zero if it succeeds, and `-1'
--     on failure.  The following `errno' error conditions are defined
--     for this function:
--
--    `EINVAL'
--          The SIGNUM argument is not valid, or you are trying to trap
--          or ignore `SIGKILL' or `SIGSTOP'.
--
--
--File: libc.info,  Node: Signal and Sigaction,  Next: Sigaction Function 
Example,  Prev: Advanced Signal Handling,  Up: Signal Actions
--
--Interaction of `signal' and `sigaction'
-----------------------------------------
--
--   It's possible to use both the `signal' and `sigaction' functions
--within a single program, but you have to be careful because they can
--interact in slightly strange ways.
--
--   The `sigaction' function specifies more information than the
--`signal' function, so the return value from `signal' cannot express the
--full range of `sigaction' possibilities.  Therefore, if you use
--`signal' to save and later reestablish an action, it may not be able to
--reestablish properly a handler that was established with `sigaction'.
--
--   To avoid having problems as a result, always use `sigaction' to save
--and restore a handler if your program uses `sigaction' at all.  Since
--`sigaction' is more general, it can properly save and reestablish any
--action, regardless of whether it was established originally with
--`signal' or `sigaction'.
--
--   On some systems if you establish an action with `signal' and then
--examine it with `sigaction', the handler address that you get may not
--be the same as what you specified with `signal'.  It may not even be
--suitable for use as an action argument with `signal'.  But you can rely
--on using it as an argument to `sigaction'.  This problem never happens
--on the GNU system.
--
--   So, you're better off using one or the other of the mechanisms
--consistently within a single program.
--
--   *Portability Note:* The basic `signal' function is a feature of
--ISO C, while `sigaction' is part of the POSIX.1 standard.  If you are
--concerned about portability to non-POSIX systems, then you should use
--the `signal' function instead.
--
--
--File: libc.info,  Node: Sigaction Function Example,  Next: Flags for 
Sigaction,  Prev: Signal and Sigaction,  Up: Signal Actions
--
--`sigaction' Function Example
------------------------------
--
--   In *Note Basic Signal Handling::, we gave an example of establishing
--a simple handler for termination signals using `signal'.  Here is an
--equivalent example using `sigaction':
--
--     #include <signal.h>
--     
--     void
--     termination_handler (int signum)
--     {
--       struct temp_file *p;
--     
--       for (p = temp_file_list; p; p = p->next)
--         unlink (p->name);
--     }
--     
--     int
--     main (void)
--     {
--       ...
--       struct sigaction new_action, old_action;
--     
--       /* Set up the structure to specify the new action. */
--       new_action.sa_handler = termination_handler;
--       sigemptyset (&new_action.sa_mask);
--       new_action.sa_flags = 0;
--     
--       sigaction (SIGINT, NULL, &old_action);
--       if (old_action.sa_handler != SIG_IGN)
--         sigaction (SIGINT, &new_action, NULL);
--       sigaction (SIGHUP, NULL, &old_action);
--       if (old_action.sa_handler != SIG_IGN)
--         sigaction (SIGHUP, &new_action, NULL);
--       sigaction (SIGTERM, NULL, &old_action);
--       if (old_action.sa_handler != SIG_IGN)
--         sigaction (SIGTERM, &new_action, NULL);
--       ...
--     }
--
--   The program just loads the `new_action' structure with the desired
--parameters and passes it in the `sigaction' call.  The usage of
--`sigemptyset' is described later; see *Note Blocking Signals::.
--
--   As in the example using `signal', we avoid handling signals
--previously set to be ignored.  Here we can avoid altering the signal
--handler even momentarily, by using the feature of `sigaction' that lets
--us examine the current action without specifying a new one.
--
--   Here is another example.  It retrieves information about the current
--action for `SIGINT' without changing that action.
--
--     struct sigaction query_action;
--     
--     if (sigaction (SIGINT, NULL, &query_action) < 0)
--       /* `sigaction' returns -1 in case of error. */
--     else if (query_action.sa_handler == SIG_DFL)
--       /* `SIGINT' is handled in the default, fatal manner. */
--     else if (query_action.sa_handler == SIG_IGN)
--       /* `SIGINT' is ignored. */
--     else
--       /* A programmer-defined signal handler is in effect. */
--
--
--File: libc.info,  Node: Flags for Sigaction,  Next: Initial Signal Actions,  
Prev: Sigaction Function Example,  Up: Signal Actions
--
--Flags for `sigaction'
-----------------------
--
--   The `sa_flags' member of the `sigaction' structure is a catch-all
--for special features.  Most of the time, `SA_RESTART' is a good value
--to use for this field.
--
--   The value of `sa_flags' is interpreted as a bit mask.  Thus, you
--should choose the flags you want to set, OR those flags together, and
--store the result in the `sa_flags' member of your `sigaction' structure.
--
--   Each signal number has its own set of flags.  Each call to
--`sigaction' affects one particular signal number, and the flags that
--you specify apply only to that particular signal.
--
--   In the GNU C library, establishing a handler with `signal' sets all
--the flags to zero except for `SA_RESTART', whose value depends on the
--settings you have made with `siginterrupt'.  *Note Interrupted
--Primitives::, to see what this is about.
--
--   These macros are defined in the header file `signal.h'.
--
-- - Macro: int SA_NOCLDSTOP
--     This flag is meaningful only for the `SIGCHLD' signal.  When the
--     flag is set, the system delivers the signal for a terminated child
--     process but not for one that is stopped.  By default, `SIGCHLD' is
--     delivered for both terminated children and stopped children.
--
--     Setting this flag for a signal other than `SIGCHLD' has no effect.
--
-- - Macro: int SA_ONSTACK
--     If this flag is set for a particular signal number, the system
--     uses the signal stack when delivering that kind of signal.  *Note
--     Signal Stack::.  If a signal with this flag arrives and you have
--     not set a signal stack, the system terminates the program with
--     `SIGILL'.
--
-- - Macro: int SA_RESTART
--     This flag controls what happens when a signal is delivered during
--     certain primitives (such as `open', `read' or `write'), and the
--     signal handler returns normally.  There are two alternatives: the
--     library function can resume, or it can return failure with error
--     code `EINTR'.
--
--     The choice is controlled by the `SA_RESTART' flag for the
--     particular kind of signal that was delivered.  If the flag is set,
--     returning from a handler resumes the library function.  If the
--     flag is clear, returning from a handler makes the function fail.
--     *Note Interrupted Primitives::.
--
--
--File: libc.info,  Node: Initial Signal Actions,  Prev: Flags for Sigaction,  
Up: Signal Actions
--
--Initial Signal Actions
------------------------
--
--   When a new process is created (*note Creating a Process::.), it
--inherits handling of signals from its parent process.  However, when
--you load a new process image using the `exec' function (*note Executing
--a File::.), any signals that you've defined your own handlers for
--revert to their `SIG_DFL' handling.  (If you think about it a little,
--this makes sense; the handler functions from the old program are
--specific to that program, and aren't even present in the address space
--of the new program image.)  Of course, the new program can establish
--its own handlers.
--
--   When a program is run by a shell, the shell normally sets the initial
--actions for the child process to `SIG_DFL' or `SIG_IGN', as
--appropriate.  It's a good idea to check to make sure that the shell has
--not set up an initial action of `SIG_IGN' before you establish your own
--signal handlers.
--
--   Here is an example of how to establish a handler for `SIGHUP', but
--not if `SIGHUP' is currently ignored:
--
--     ...
--     struct sigaction temp;
--     
--     sigaction (SIGHUP, NULL, &temp);
--     
--     if (temp.sa_handler != SIG_IGN)
--       {
--         temp.sa_handler = handle_sighup;
--         sigemptyset (&temp.sa_mask);
--         sigaction (SIGHUP, &temp, NULL);
--       }
--
--
--File: libc.info,  Node: Defining Handlers,  Next: Interrupted Primitives,  
Prev: Signal Actions,  Up: Signal Handling
--
--Defining Signal Handlers
--========================
--
--   This section describes how to write a signal handler function that
--can be established with the `signal' or `sigaction' functions.
--
--   A signal handler is just a function that you compile together with
--the rest of the program.  Instead of directly invoking the function,
--you use `signal' or `sigaction' to tell the operating system to call it
--when a signal arrives.  This is known as "establishing" the handler.
--*Note Signal Actions::.
--
--   There are two basic strategies you can use in signal handler
--functions:
--
--   * You can have the handler function note that the signal arrived by
--     tweaking some global data structures, and then return normally.
--
--   * You can have the handler function terminate the program or transfer
--     control to a point where it can recover from the situation that
--     caused the signal.
--
--   You need to take special care in writing handler functions because
--they can be called asynchronously.  That is, a handler might be called
--at any point in the program, unpredictably.  If two signals arrive
--during a very short interval, one handler can run within another.  This
--section describes what your handler should do, and what you should
--avoid.
--
--* Menu:
--
--* Handler Returns::             Handlers that return normally, and what
--                                 this means.
--* Termination in Handler::      How handler functions terminate a program.
--* Longjmp in Handler::          Nonlocal transfer of control out of a
--                                 signal handler.
--* Signals in Handler::          What happens when signals arrive while
--                                 the handler is already occupied.
--* Merged Signals::            When a second signal arrives before the
--                               first is handled.
--* Nonreentrancy::               Do not call any functions unless you know they
--                                 are reentrant with respect to signals.
--* Atomic Data Access::          A single handler can run in the middle of
--                                 reading or writing a single object.
--
--
--File: libc.info,  Node: Handler Returns,  Next: Termination in Handler,  Up: 
Defining Handlers
--
--Signal Handlers that Return
-----------------------------
--
--   Handlers which return normally are usually used for signals such as
--`SIGALRM' and the I/O and interprocess communication signals.  But a
--handler for `SIGINT' might also return normally after setting a flag
--that tells the program to exit at a convenient time.
--
--   It is not safe to return normally from the handler for a program
--error signal, because the behavior of the program when the handler
--function returns is not defined after a program error.  *Note Program
--Error Signals::.
--
--   Handlers that return normally must modify some global variable in
--order to have any effect.  Typically, the variable is one that is
--examined periodically by the program during normal operation.  Its data
--type should be `sig_atomic_t' for reasons described in *Note Atomic
--Data Access::.
--
--   Here is a simple example of such a program.  It executes the body of
--the loop until it has noticed that a `SIGALRM' signal has arrived.
--This technique is useful because it allows the iteration in progress
--when the signal arrives to complete before the loop exits.
--
--     #include <signal.h>
--     #include <stdio.h>
--     #include <stdlib.h>
--     
--     /* This flag controls termination of the main loop. */
--     volatile sig_atomic_t keep_going = 1;
--     
--     /* The signal handler just clears the flag and re-enables itself. */
--     void
--     catch_alarm (int sig)
--     {
--       keep_going = 0;
--       signal (sig, catch_alarm);
--     }
--     
--     void
--     do_stuff (void)
--     {
--       puts ("Doing stuff while waiting for alarm....");
--     }
--     
--     int
--     main (void)
--     {
--       /* Establish a handler for SIGALRM signals. */
--       signal (SIGALRM, catch_alarm);
--     
--       /* Set an alarm to go off in a little while. */
--       alarm (2);
--     
--       /* Check the flag once in a while to see when to quit. */
--       while (keep_going)
--         do_stuff ();
--     
--       return EXIT_SUCCESS;
--     }
--
--
--File: libc.info,  Node: Termination in Handler,  Next: Longjmp in Handler,  
Prev: Handler Returns,  Up: Defining Handlers
--
--Handlers That Terminate the Process
-------------------------------------
--
--   Handler functions that terminate the program are typically used to
--cause orderly cleanup or recovery from program error signals and
--interactive interrupts.
--
--   The cleanest way for a handler to terminate the process is to raise
--the same signal that ran the handler in the first place.  Here is how
--to do this:
--
--     volatile sig_atomic_t fatal_error_in_progress = 0;
--     
--     void
--     fatal_error_signal (int sig)
--     {
--     /* Since this handler is established for more than one kind of signal, 
--          it might still get invoked recursively by delivery of some other 
kind
--          of signal.  Use a static variable to keep track of that. */
--       if (fatal_error_in_progress)
--         raise (sig);
--       fatal_error_in_progress = 1;
--
--     /* Now do the clean up actions:
--          - reset terminal modes
--          - kill child processes
--          - remove lock files */
--       ...
--
--     /* Now reraise the signal.  Since the signal is blocked,
--          it will receive its default handling, which is
--          to terminate the process.  We could just call
--          `exit' or `abort', but reraising the signal
--          sets the return status from the process correctly. */
--       raise (sig);
--     }
--
--
--File: libc.info,  Node: Longjmp in Handler,  Next: Signals in Handler,  Prev: 
Termination in Handler,  Up: Defining Handlers
--
--Nonlocal Control Transfer in Handlers
---------------------------------------
--
--   You can do a nonlocal transfer of control out of a signal handler
--using the `setjmp' and `longjmp' facilities (*note Non-Local Exits::.).
--
--   When the handler does a nonlocal control transfer, the part of the
--program that was running will not continue.  If this part of the program
--was in the middle of updating an important data structure, the data
--structure will remain inconsistent.  Since the program does not
--terminate, the inconsistency is likely to be noticed later on.
--
--   There are two ways to avoid this problem.  One is to block the signal
--for the parts of the program that update important data structures.
--Blocking the signal delays its delivery until it is unblocked, once the
--critical updating is finished.  *Note Blocking Signals::.
--
--   The other way to re-initialize the crucial data structures in the
--signal handler, or make their values consistent.
--
--   Here is a rather schematic example showing the reinitialization of
--one global variable.
--
--     #include <signal.h>
--     #include <setjmp.h>
--     
--     jmp_buf return_to_top_level;
--     
--     volatile sig_atomic_t waiting_for_input;
--     
--     void
--     handle_sigint (int signum)
--     {
--       /* We may have been waiting for input when the signal arrived,
--          but we are no longer waiting once we transfer control. */
--       waiting_for_input = 0;
--       longjmp (return_to_top_level, 1);
--     }
--
--     int
--     main (void)
--     {
--       ...
--       signal (SIGINT, sigint_handler);
--       ...
--       while (1) {
--         prepare_for_command ();
--         if (setjmp (return_to_top_level) == 0)
--           read_and_execute_command ();
--       }
--     }
--
--     /* Imagine this is a subroutine used by various commands. */
--     char *
--     read_data ()
--     {
--       if (input_from_terminal) {
--         waiting_for_input = 1;
--         ...
--         waiting_for_input = 0;
--       } else {
--         ...
--       }
--     }
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-21 
glibc-2.0.1/manual/libc.info-21
---- ../glibc-2.0.1/manual/libc.info-21 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-21    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1178 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Signals in Handler,  Next: Merged Signals,  Prev: 
Longjmp in Handler,  Up: Defining Handlers
--
--Signals Arriving While a Handler Runs
---------------------------------------
--
--   What happens if another signal arrives while your signal handler
--function is running?
--
--   When the handler for a particular signal is invoked, that signal is
--automatically blocked until the handler returns.  That means that if two
--signals of the same kind arrive close together, the second one will be
--held until the first has been handled.  (The handler can explicitly
--unblock the signal using `sigprocmask', if you want to allow more
--signals of this type to arrive; see *Note Process Signal Mask::.)
--
--   However, your handler can still be interrupted by delivery of another
--kind of signal.  To avoid this, you can use the `sa_mask' member of the
--action structure passed to `sigaction' to explicitly specify which
--signals should be blocked while the signal handler runs.  These signals
--are in addition to the signal for which the handler was invoked, and
--any other signals that are normally blocked by the process.  *Note
--Blocking for Handler::.
--
--   When the handler returns, the set of blocked signals is restored to
--the value it had before the handler ran.  So using `sigprocmask' inside
--the handler only affects what signals can arrive during the execution of
--the handler itself, not what signals can arrive once the handler
--returns.
--
--   *Portability Note:* Always use `sigaction' to establish a handler
--for a signal that you expect to receive asynchronously, if you want
--your program to work properly on System V Unix.  On this system, the
--handling of a signal whose handler was established with `signal'
--automatically sets the signal's action back to `SIG_DFL', and the
--handler must re-establish itself each time it runs.  This practice,
--while inconvenient, does work when signals cannot arrive in succession.
--However, if another signal can arrive right away, it may arrive before
--the handler can re-establish itself.  Then the second signal would
--receive the default handling, which could terminate the process.
--
--
--File: libc.info,  Node: Merged Signals,  Next: Nonreentrancy,  Prev: Signals 
in Handler,  Up: Defining Handlers
--
--Signals Close Together Merge into One
---------------------------------------
--
--   If multiple signals of the same type are delivered to your process
--before your signal handler has a chance to be invoked at all, the
--handler may only be invoked once, as if only a single signal had
--arrived.  In effect, the signals merge into one.  This situation can
--arise when the signal is blocked, or in a multiprocessing environment
--where the system is busy running some other processes while the signals
--are delivered.  This means, for example, that you cannot reliably use a
--signal handler to count signals.  The only distinction you can reliably
--make is whether at least one signal has arrived since a given time in
--the past.
--
--   Here is an example of a handler for `SIGCHLD' that compensates for
--the fact that the number of signals recieved may not equal the number of
--child processes generate them.  It assumes that the program keeps track
--of all the child processes with a chain of structures as follows:
--
--     struct process
--     {
--       struct process *next;
--       /* The process ID of this child.  */
--       int pid;
--       /* The descriptor of the pipe or pseudo terminal
--          on which output comes from this child.  */
--       int input_descriptor;
--       /* Nonzero if this process has stopped or terminated.  */
--       sig_atomic_t have_status;
--       /* The status of this child; 0 if running,
--          otherwise a status value from `waitpid'.  */
--       int status;
--     };
--     
--     struct process *process_list;
--
--   This example also uses a flag to indicate whether signals have
--arrived since some time in the past--whenever the program last cleared
--it to zero.
--
--     /* Nonzero means some child's status has changed
--        so look at `process_list' for the details.  */
--     int process_status_change;
--
--   Here is the handler itself:
--
--     void
--     sigchld_handler (int signo)
--     {
--       int old_errno = errno;
--     
--       while (1) {
--         register int pid;
--         int w;
--         struct process *p;
--     
--         /* Keep asking for a status until we get a definitive result.  */
--         do
--           {
--             errno = 0;
--             pid = waitpid (WAIT_ANY, &w, WNOHANG | WUNTRACED);
--           }
--         while (pid <= 0 && errno == EINTR);
--     
--         if (pid <= 0) {
--           /* A real failure means there are no more
--              stopped or terminated child processes, so return.  */
--           errno = old_errno;
--           return;
--         }
--     
--         /* Find the process that signaled us, and record its status.  */
--     
--         for (p = process_list; p; p = p->next)
--           if (p->pid == pid) {
--             p->status = w;
--             /* Indicate that the `status' field
--                has data to look at.  We do this only after storing it.  */
--             p->have_status = 1;
--     
--             /* If process has terminated, stop waiting for its output.  */
--             if (WIFSIGNALED (w) || WIFEXITED (w))
--               if (p->input_descriptor)
--                 FD_CLR (p->input_descriptor, &input_wait_mask);
--     
--             /* The program should check this flag from time to time
--                to see if there is any news in `process_list'.  */
--             ++process_status_change;
--           }
--     
--         /* Loop around to handle all the processes
--            that have something to tell us.  */
--       }
--     }
--
--   Here is the proper way to check the flag `process_status_change':
--
--     if (process_status_change) {
--       struct process *p;
--       process_status_change = 0;
--       for (p = process_list; p; p = p->next)
--         if (p->have_status) {
--           ... Examine `p->status' ...
--         }
--     }
--
--It is vital to clear the flag before examining the list; otherwise, if a
--signal were delivered just before the clearing of the flag, and after
--the appropriate element of the process list had been checked, the status
--change would go unnoticed until the next signal arrived to set the flag
--again.  You could, of course, avoid this problem by blocking the signal
--while scanning the list, but it is much more elegant to guarantee
--correctness by doing things in the right order.
--
--   The loop which checks process status avoids examining `p->status'
--until it sees that status has been validly stored.  This is to make sure
--that the status cannot change in the middle of accessing it.  Once
--`p->have_status' is set, it means that the child process is stopped or
--terminated, and in either case, it cannot stop or terminate again until
--the program has taken notice.  *Note Atomic Usage::, for more
--information about coping with interruptions during accessings of a
--variable.
--
--   Here is another way you can test whether the handler has run since
--the last time you checked.  This technique uses a counter which is never
--changed outside the handler.  Instead of clearing the count, the program
--remembers the previous value and sees whether it has changed since the
--previous check.  The advantage of this method is that different parts of
--the program can check independently, each part checking whether there
--has been a signal since that part last checked.
--
--     sig_atomic_t process_status_change;
--     
--     sig_atomic_t last_process_status_change;
--     
--     ...
--     {
--       sig_atomic_t prev = last_process_status_change;
--       last_process_status_change = process_status_change;
--       if (last_process_status_change != prev) {
--         struct process *p;
--         for (p = process_list; p; p = p->next)
--           if (p->have_status) {
--             ... Examine `p->status' ...
--           }
--       }
--     }
--
--
--File: libc.info,  Node: Nonreentrancy,  Next: Atomic Data Access,  Prev: 
Merged Signals,  Up: Defining Handlers
--
--Signal Handling and Nonreentrant Functions
--------------------------------------------
--
--   Handler functions usually don't do very much.  The best practice is
--to write a handler that does nothing but set an external variable that
--the program checks regularly, and leave all serious work to the program.
--This is best because the handler can be called at asynchronously, at
--unpredictable times--perhaps in the middle of a primitive function, or
--even between the beginning and the end of a C operator that requires
--multiple instructions.  The data structures being manipulated might
--therefore be in an inconsistent state when the handler function is
--invoked.  Even copying one `int' variable into another can take two
--instructions on most machines.
--
--   This means you have to be very careful about what you do in a signal
--handler.
--
--   * If your handler needs to access any global variables from your
--     program, declare those variables `volatile'.  This tells the
--     compiler that the value of the variable might change
--     asynchronously, and inhibits certain optimizations that would be
--     invalidated by such modifications.
--
--   * If you call a function in the handler, make sure it is "reentrant"
--     with respect to signals, or else make sure that the signal cannot
--     interrupt a call to a related function.
--
--   A function can be non-reentrant if it uses memory that is not on the
--stack.
--
--   * If a function uses a static variable or a global variable, or a
--     dynamically-allocated object that it finds for itself, then it is
--     non-reentrant and any two calls to the function can interfere.
--
--     For example, suppose that the signal handler uses `gethostbyname'.
--     This function returns its value in a static object, reusing the
--     same object each time.  If the signal happens to arrive during a
--     call to `gethostbyname', or even after one (while the program is
--     still using the value), it will clobber the value that the program
--     asked for.
--
--     However, if the program does not use `gethostbyname' or any other
--     function that returns information in the same object, or if it
--     always blocks signals around each use, then you are safe.
--
--     There are a large number of library functions that return values
--     in a fixed object, always reusing the same object in this fashion,
--     and all of them cause the same problem.  The description of a
--     function in this manual always mentions this behavior.
--
--   * If a function uses and modifies an object that you supply, then it
--     is potentially non-reentrant; two calls can interfere if they use
--     the same object.
--
--     This case arises when you do I/O using streams.  Suppose that the
--     signal handler prints a message with `fprintf'.  Suppose that the
--     program was in the middle of an `fprintf' call using the same
--     stream when the signal was delivered.  Both the signal handler's
--     message and the program's data could be corrupted, because both
--     calls operate on the same data structure--the stream itself.
--
--     However, if you know that the stream that the handler uses cannot
--     possibly be used by the program at a time when signals can arrive,
--     then you are safe.  It is no problem if the program uses some
--     other stream.
--
--   * On most systems, `malloc' and `free' are not reentrant, because
--     they use a static data structure which records what memory blocks
--     are free.  As a result, no library functions that allocate or free
--     memory are reentrant.  This includes functions that allocate space
--     to store a result.
--
--     The best way to avoid the need to allocate memory in a handler is
--     to allocate in advance space for signal handlers to use.
--
--     The best way to avoid freeing memory in a handler is to flag or
--     record the objects to be freed, and have the program check from
--     time to time whether anything is waiting to be freed.  But this
--     must be done with care, because placing an object on a chain is
--     not atomic, and if it is interrupted by another signal handler
--     that does the same thing, you could "lose" one of the objects.
--
--     The relocating allocation functions (*note Relocating Allocator::.)
--     are certainly not safe to use in a signal handler.
--
--   * Any function that modifies `errno' is non-reentrant, but you can
--     correct for this: in the handler, save the original value of
--     `errno' and restore it before returning normally.  This prevents
--     errors that occur within the signal handler from being confused
--     with errors from system calls at the point the program is
--     interrupted to run the handler.
--
--     This technique is generally applicable; if you want to call in a
--     handler a function that modifies a particular object in memory,
--     you can make this safe by saving and restoring that object.
--
--   * Merely reading from a memory object is safe provided that you can
--     deal with any of the values that might appear in the object at a
--     time when the signal can be delivered.  Keep in mind that
--     assignment to some data types requires more than one instruction,
--     which means that the handler could run "in the middle of" an
--     assignment to the variable if its type is not atomic.  *Note
--     Atomic Data Access::.
--
--   * Merely writing into a memory object is safe as long as a sudden
--     change in the value, at any time when the handler might run, will
--     not disturb anything.
--
--
--File: libc.info,  Node: Atomic Data Access,  Prev: Nonreentrancy,  Up: 
Defining Handlers
--
--Atomic Data Access and Signal Handling
----------------------------------------
--
--   Whether the data in your application concerns atoms, or mere text,
--you have to be careful about the fact that access to a single datum is
--not necessarily "atomic".  This means that it can take more than one
--instruction to read or write a single object.  In such cases, a signal
--handler might in the middle of reading or writing the object.
--
--   There are three ways you can cope with this problem.  You can use
--data types that are always accessed atomically; you can carefully
--arrange that nothing untoward happens if an access is interrupted, or
--you can block all signals around any access that had better not be
--interrupted (*note Blocking Signals::.).
--
--* Menu:
--
--* Non-atomic Example::                A program illustrating interrupted 
access.
--* Types: Atomic Types.                Data types that guarantee no 
interruption.
--* Usage: Atomic Usage.                Proving that interruption is harmless.
--
--
--File: libc.info,  Node: Non-atomic Example,  Next: Atomic Types,  Up: Atomic 
Data Access
--
--Problems with Non-Atomic Access
--...............................
--
--   Here is an example which shows what can happen if a signal handler
--runs in the middle of modifying a variable.  (Interrupting the reading
--of a variable can also lead to paradoxical results, but here we only
--show writing.)
--
--     #include <signal.h>
--     #include <stdio.h>
--     
--     struct two_words { int a, b; } memory;
--     
--     void
--     handler(int signum)
--     {
--        printf ("%d,%d\n", memory.a, memory.b);
--        alarm (1);
--     }
--     int
--     main (void)
--     {
--        static struct two_words zeros = { 0, 0 }, ones = { 1, 1 };
--        signal (SIGALRM, handler);
--        memory = zeros;
--        alarm (1);
--        while (1)
--          {
--            memory = zeros;
--            memory = ones;
--          }
--     }
--
--   This program fills `memory' with zeros, ones, zeros, ones,
--alternating forever; meanwhile, once per second, the alarm signal
--handler prints the current contents.  (Calling `printf' in the handler
--is safe in this program because it is certainly not being called outside
--the handler when the signal happens.)
--
--   Clearly, this program can print a pair of zeros or a pair of ones.
--But that's not all it can do!  On most machines, it takes several
--instructions to store a new value in `memory', and the value is stored
--one word at a time.  If the signal is delivered in between these
--instructions, the handler might find that `memory.a' is zero and
--`memory.b' is one (or vice versa).
--
--   On some machines it may be possible to store a new value in `memory'
--with just one instruction that cannot be interrupted.  On these
--machines, the handler will always print two zeros or two ones.
--
--
--File: libc.info,  Node: Atomic Types,  Next: Atomic Usage,  Prev: Non-atomic 
Example,  Up: Atomic Data Access
--
--Atomic Types
--............
--
--   To avoid uncertainty about interrupting access to a variable, you can
--use a particular data type for which access is always atomic:
--`sig_atomic_t'.  Reading and writing this data type is guaranteed to
--happen in a single instruction, so there's no way for a handler to run
--"in the middle" of an access.
--
--   The type `sig_atomic_t' is always an integer data type, but which
--one it is, and how many bits it contains, may vary from machine to
--machine.
--
-- - Data Type: sig_atomic_t
--     This is an integer data type.  Objects of this type are always
--     accessed atomically.
--
--   In practice, you can assume that `int' and other integer types no
--longer than `int' are atomic.  You can also assume that pointer types
--are atomic; that is very convenient.  Both of these are true on all of
--the machines that the GNU C library supports, and on all POSIX systems
--we know of.
--
--
--File: libc.info,  Node: Atomic Usage,  Prev: Atomic Types,  Up: Atomic Data 
Access
--
--Atomic Usage Patterns
--.....................
--
--   Certain patterns of access avoid any problem even if an access is
--interrupted.  For example, a flag which is set by the handler, and
--tested and cleared by the main program from time to time, is always safe
--even if access actually requires two instructions.  To show that this is
--so, we must consider each access that could be interrupted, and show
--that there is no problem if it is interrupted.
--
--   An interrupt in the middle of testing the flag is safe because
--either it's recognized to be nonzero, in which case the precise value
--doesn't matter, or it will be seen to be nonzero the next time it's
--tested.
--
--   An interrupt in the middle of clearing the flag is no problem because
--either the value ends up zero, which is what happens if a signal comes
--in just before the flag is cleared, or the value ends up nonzero, and
--subsequent events occur as if the signal had come in just after the flag
--was cleared.  As long as the code handles both of these cases properly,
--it can also handle a signal in the middle of clearing the flag.  (This
--is an example of the sort of reasoning you need to do to figure out
--whether non-atomic usage is safe.)
--
--   Sometimes you can insure uninterrupted access to one object by
--protecting its use with another object, perhaps one whose type
--guarantees atomicity.  *Note Merged Signals::, for an example.
--
--
--File: libc.info,  Node: Interrupted Primitives,  Next: Generating Signals,  
Prev: Defining Handlers,  Up: Signal Handling
--
--Primitives Interrupted by Signals
--=================================
--
--   A signal can arrive and be handled while an I/O primitive such as
--`open' or `read' is waiting for an I/O device.  If the signal handler
--returns, the system faces the question: what should happen next?
--
--   POSIX specifies one approach: make the primitive fail right away.
--The error code for this kind of failure is `EINTR'.  This is flexible,
--but usually inconvenient.  Typically, POSIX applications that use signal
--handlers must check for `EINTR' after each library function that can
--return it, in order to try the call again.  Often programmers forget to
--check, which is a common source of error.
--
--   The GNU library provides a convenient way to retry a call after a
--temporary failure, with the macro `TEMP_FAILURE_RETRY':
--
-- - Macro: TEMP_FAILURE_RETRY (EXPRESSION)
--     This macro evaluates EXPRESSION once.  If it fails and reports
--     error code `EINTR', `TEMP_FAILURE_RETRY' evaluates it again, and
--     over and over until the result is not a temporary failure.
--
--     The value returned by `TEMP_FAILURE_RETRY' is whatever value
--     EXPRESSION produced.
--
--   BSD avoids `EINTR' entirely and provides a more convenient approach:
--to restart the interrupted primitive, instead of making it fail.  If
--you choose this approach, you need not be concerned with `EINTR'.
--
--   You can choose either approach with the GNU library.  If you use
--`sigaction' to establish a signal handler, you can specify how that
--handler should behave.  If you specify the `SA_RESTART' flag, return
--from that handler will resume a primitive; otherwise, return from that
--handler will cause `EINTR'.  *Note Flags for Sigaction::.
--
--   Another way to specify the choice is with the `siginterrupt'
--function.  *Note BSD Handler::.
--
--   When you don't specify with `sigaction' or `siginterrupt' what a
--particular handler should do, it uses a default choice.  The default
--choice in the GNU library depends on the feature test macros you have
--defined.  If you define `_BSD_SOURCE' or `_GNU_SOURCE' before calling
--`signal', the default is to resume primitives; otherwise, the default
--is to make them fail with `EINTR'.  (The library contains alternate
--versions of the `signal' function, and the feature test macros
--determine which one you really call.)  *Note Feature Test Macros::.
--
--   The description of each primitive affected by this issue lists
--`EINTR' among the error codes it can return.
--
--   There is one situation where resumption never happens no matter which
--choice you make: when a data-transfer function such as `read' or
--`write' is interrupted by a signal after transferring part of the data.
--In this case, the function returns the number of bytes already
--transferred, indicating partial success.
--
--   This might at first appear to cause unreliable behavior on
--record-oriented devices (including datagram sockets; *note
--Datagrams::.), where splitting one `read' or `write' into two would
--read or write two records.  Actually, there is no problem, because
--interruption after a partial transfer cannot happen on such devices;
--they always transfer an entire record in one burst, with no waiting
--once data transfer has started.
--
--
--File: libc.info,  Node: Generating Signals,  Next: Blocking Signals,  Prev: 
Interrupted Primitives,  Up: Signal Handling
--
--Generating Signals
--==================
--
--   Besides signals that are generated as a result of a hardware trap or
--interrupt, your program can explicitly send signals to itself or to
--another process.
--
--* Menu:
--
--* Signaling Yourself::          A process can send a signal to itself.
--* Signaling Another Process::   Send a signal to another process.
--* Permission for kill::         Permission for using `kill'.
--* Kill Example::                Using `kill' for Communication.
--
--
--File: libc.info,  Node: Signaling Yourself,  Next: Signaling Another Process, 
 Up: Generating Signals
--
--Signaling Yourself
--------------------
--
--   A process can send itself a signal with the `raise' function.  This
--function is declared in `signal.h'.
--
-- - Function: int raise (int SIGNUM)
--     The `raise' function sends the signal SIGNUM to the calling
--     process.  It returns zero if successful and a nonzero value if it
--     fails.  About the only reason for failure would be if the value of
--     SIGNUM is invalid.
--
-- - Function: int gsignal (int SIGNUM)
--     The `gsignal' function does the same thing as `raise'; it is
--     provided only for compatibility with SVID.
--
--   One convenient use for `raise' is to reproduce the default behavior
--of a signal that you have trapped.  For instance, suppose a user of your
--program types the SUSP character (usually `C-z'; *note Special
--Characters::.) to send it an interactive stop stop signal (`SIGTSTP'),
--and you want to clean up some internal data buffers before stopping.
--You might set this up like this:
--
--     #include <signal.h>
--     
--     /* When a stop signal arrives, set the action back to the default
--        and then resend the signal after doing cleanup actions. */
--     
--     void
--     tstp_handler (int sig)
--     {
--       signal (SIGTSTP, SIG_DFL);
--       /* Do cleanup actions here. */
--       ...
--       raise (SIGTSTP);
--     }
--     
--     /* When the process is continued again, restore the signal handler. */
--     
--     void
--     cont_handler (int sig)
--     {
--       signal (SIGCONT, cont_handler);
--       signal (SIGTSTP, tstp_handler);
--     }
--     /* Enable both handlers during program initialization. */
--     
--     int
--     main (void)
--     {
--       signal (SIGCONT, cont_handler);
--       signal (SIGTSTP, tstp_handler);
--       ...
--     }
--
--   *Portability note:* `raise' was invented by the ISO C committee.
--Older systems may not support it, so using `kill' may be more portable.
--*Note Signaling Another Process::.
--
--
--File: libc.info,  Node: Signaling Another Process,  Next: Permission for 
kill,  Prev: Signaling Yourself,  Up: Generating Signals
--
--Signaling Another Process
---------------------------
--
--   The `kill' function can be used to send a signal to another process.
--In spite of its name, it can be used for a lot of things other than
--causing a process to terminate.  Some examples of situations where you
--might want to send signals between processes are:
--
--   * A parent process starts a child to perform a task--perhaps having
--     the child running an infinite loop--and then terminates the child
--     when the task is no longer needed.
--
--   * A process executes as part of a group, and needs to terminate or
--     notify the other processes in the group when an error or other
--     event occurs.
--
--   * Two processes need to synchronize while working together.
--
--   This section assumes that you know a little bit about how processes
--work.  For more information on this subject, see *Note Processes::.
--
--   The `kill' function is declared in `signal.h'.
--
-- - Function: int kill (pid_t PID, int SIGNUM)
--     The `kill' function sends the signal SIGNUM to the process or
--     process group specified by PID.  Besides the signals listed in
--     *Note Standard Signals::, SIGNUM can also have a value of zero to
--     check the validity of the PID.
--
--     The PID specifies the process or process group to receive the
--     signal:
--
--    `PID > 0'
--          The process whose identifier is PID.
--
--    `PID == 0'
--          All processes in the same process group as the sender.
--
--    `PID < -1'
--          The process group whose identifier is -PID.
--
--    `PID == -1'
--          If the process is privileged, send the signal to all
--          processes except for some special system processes.
--          Otherwise, send the signal to all processes with the same
--          effective user ID.
--
--     A process can send a signal SIGNUM to itself with a call like
--     `kill (getpid(), SIGNUM)'.  If `kill' is used by a process to send
--     a signal to itself, and the signal is not blocked, then `kill'
--     delivers at least one signal (which might be some other pending
--     unblocked signal instead of the signal SIGNUM) to that process
--     before it returns.
--
--     The return value from `kill' is zero if the signal can be sent
--     successfully.  Otherwise, no signal is sent, and a value of `-1' is
--     returned.  If PID specifies sending a signal to several processes,
--     `kill' succeeds if it can send the signal to at least one of them.
--     There's no way you can tell which of the processes got the signal
--     or whether all of them did.
--
--     The following `errno' error conditions are defined for this
--     function:
--
--    `EINVAL'
--          The SIGNUM argument is an invalid or unsupported number.
--
--    `EPERM'
--          You do not have the privilege to send a signal to the process
--          or any of the processes in the process group named by PID.
--
--    `ESCRH'
--          The PID argument does not refer to an existing process or
--          group.
--
-- - Function: int killpg (int PGID, int SIGNUM)
--     This is similar to `kill', but sends signal SIGNUM to the process
--     group PGID.  This function is provided for compatibility with BSD;
--     using `kill' to do this is more portable.
--
--   As a simple example of `kill', the call `kill (getpid (), SIG)' has
--the same effect as `raise (SIG)'.
--
--
--File: libc.info,  Node: Permission for kill,  Next: Kill Example,  Prev: 
Signaling Another Process,  Up: Generating Signals
--
--Permission for using `kill'
-----------------------------
--
--   There are restrictions that prevent you from using `kill' to send
--signals to any random process.  These are intended to prevent antisocial
--behavior such as arbitrarily killing off processes belonging to another
--user.  In typical use, `kill' is used to pass signals between parent,
--child, and sibling processes, and in these situations you normally do
--have permission to send signals.  The only common exception is when you
--run a setuid program in a child process; if the program changes its
--real UID as well as its effective UID, you may not have permission to
--send a signal.  The `su' program does this.
--
--   Whether a process has permission to send a signal to another process
--is determined by the user IDs of the two processes.  This concept is
--discussed in detail in *Note Process Persona::.
--
--   Generally, for a process to be able to send a signal to another
--process, either the sending process must belong to a privileged user
--(like `root'), or the real or effective user ID of the sending process
--must match the real or effective user ID of the receiving process.  If
--the receiving process has changed its effective user ID from the
--set-user-ID mode bit on its process image file, then the owner of the
--process image file is used in place of its current effective user ID.
--In some implementations, a parent process might be able to send signals
--to a child process even if the user ID's don't match, and other
--implementations might enforce other restrictions.
--
--   The `SIGCONT' signal is a special case.  It can be sent if the
--sender is part of the same session as the receiver, regardless of user
--IDs.
--
--
--File: libc.info,  Node: Kill Example,  Prev: Permission for kill,  Up: 
Generating Signals
--
--Using `kill' for Communication
--------------------------------
--
--   Here is a longer example showing how signals can be used for
--interprocess communication.  This is what the `SIGUSR1' and `SIGUSR2'
--signals are provided for.  Since these signals are fatal by default,
--the process that is supposed to receive them must trap them through
--`signal' or `sigaction'.
--
--   In this example, a parent process forks a child process and then
--waits for the child to complete its initialization.  The child process
--tells the parent when it is ready by sending it a `SIGUSR1' signal,
--using the `kill' function.
--
--     #include <signal.h>
--     #include <stdio.h>
--     #include <sys/types.h>
--     #include <unistd.h>
--     
--     /* When a `SIGUSR1' signal arrives, set this variable. */
--     volatile sig_atomic_t usr_interrupt = 0;
--     
--     void
--     synch_signal (int sig)
--     {
--       usr_interrupt = 1;
--     }
--     
--     /* The child process executes this function. */
--     void
--     child_function (void)
--     {
--       /* Perform initialization. */
--       printf ("I'm here!!!  My pid is %d.\n", (int) getpid ());
--     
--       /* Let parent know you're done. */
--       kill (getppid (), SIGUSR1);
--     
--       /* Continue with execution. */
--       puts ("Bye, now....");
--       exit (0);
--     }
--     
--     int
--     main (void)
--     {
--       struct sigaction usr_action;
--       sigset_t block_mask;
--       pid_t child_id;
--     
--       /* Establish the signal handler. */
--       sigfillset (&block_mask);
--       usr_action.sa_handler = synch_signal;
--       usr_action.sa_mask = block_mask;
--       usr_action.sa_flags = 0;
--       sigaction (SIGUSR1, &usr_action, NULL);
--     
--       /* Create the child process. */
--       child_id = fork ();
--       if (child_id == 0)
--         child_function ();          /* Does not return. */
--     /* Busy wait for the child to send a signal. */
--       while (!usr_interrupt)
--         ;
--     
--       /* Now continue execution. */
--       puts ("That's all, folks!");
--     
--       return 0;
--     }
--
--   This example uses a busy wait, which is bad, because it wastes CPU
--cycles that other programs could otherwise use.  It is better to ask the
--system to wait until the signal arrives.  See the example in *Note
--Waiting for a Signal::.
--
--
--File: libc.info,  Node: Blocking Signals,  Next: Waiting for a Signal,  Prev: 
Generating Signals,  Up: Signal Handling
--
--Blocking Signals
--================
--
--   Blocking a signal means telling the operating system to hold it and
--deliver it later.  Generally, a program does not block signals
--indefinitely--it might as well ignore them by setting their actions to
--`SIG_IGN'.  But it is useful to block signals briefly, to prevent them
--from interrupting sensitive operations.  For instance:
--
--   * You can use the `sigprocmask' function to block signals while you
--     modify global variables that are also modified by the handlers for
--     these signals.
--
--   * You can set `sa_mask' in your `sigaction' call to block certain
--     signals while a particular signal handler runs.  This way, the
--     signal handler can run without being interrupted itself by signals.
--
--* Menu:
--
--* Why Block::                           The purpose of blocking signals.
--* Signal Sets::                         How to specify which signals to
--                                         block.
--* Process Signal Mask::                 Blocking delivery of signals to your
--                                       process during normal execution.
--* Testing for Delivery::                Blocking to Test for Delivery of
--                                         a Signal.
--* Blocking for Handler::                Blocking additional signals while a
--                                       handler is being run.
--* Checking for Pending Signals::        Checking for Pending Signals
--* Remembering a Signal::                How you can get almost the same
--                                         effect as blocking a signal, by
--                                         handling it and setting a flag
--                                         to be tested later.
--
--
--File: libc.info,  Node: Why Block,  Next: Signal Sets,  Up: Blocking Signals
--
--Why Blocking Signals is Useful
--------------------------------
--
--   Temporary blocking of signals with `sigprocmask' gives you a way to
--prevent interrupts during critical parts of your code.  If signals
--arrive in that part of the program, they are delivered later, after you
--unblock them.
--
--   One example where this is useful is for sharing data between a signal
--handler and the rest of the program.  If the type of the data is not
--`sig_atomic_t' (*note Atomic Data Access::.), then the signal handler
--could run when the rest of the program has only half finished reading
--or writing the data.  This would lead to confusing consequences.
--
--   To make the program reliable, you can prevent the signal handler from
--running while the rest of the program is examining or modifying that
--data--by blocking the appropriate signal around the parts of the
--program that touch the data.
--
--   Blocking signals is also necessary when you want to perform a certain
--action only if a signal has not arrived.  Suppose that the handler for
--the signal sets a flag of type `sig_atomic_t'; you would like to test
--the flag and perform the action if the flag is not set.  This is
--unreliable.  Suppose the signal is delivered immediately after you test
--the flag, but before the consequent action: then the program will
--perform the action even though the signal has arrived.
--
--   The only way to test reliably for whether a signal has yet arrived
--is to test while the signal is blocked.
--
--
--File: libc.info,  Node: Signal Sets,  Next: Process Signal Mask,  Prev: Why 
Block,  Up: Blocking Signals
--
--Signal Sets
-------------
--
--   All of the signal blocking functions use a data structure called a
--"signal set" to specify what signals are affected.  Thus, every
--activity involves two stages: creating the signal set, and then passing
--it as an argument to a library function.
--
--   These facilities are declared in the header file `signal.h'.
--
-- - Data Type: sigset_t
--     The `sigset_t' data type is used to represent a signal set.
--     Internally, it may be implemented as either an integer or structure
--     type.
--
--     For portability, use only the functions described in this section
--     to initialize, change, and retrieve information from `sigset_t'
--     objects--don't try to manipulate them directly.
--
--   There are two ways to initialize a signal set.  You can initially
--specify it to be empty with `sigemptyset' and then add specified
--signals individually.  Or you can specify it to be full with
--`sigfillset' and then delete specified signals individually.
--
--   You must always initialize the signal set with one of these two
--functions before using it in any other way.  Don't try to set all the
--signals explicitly because the `sigset_t' object might include some
--other information (like a version field) that needs to be initialized as
--well.  (In addition, it's not wise to put into your program an
--assumption that the system has no signals aside from the ones you know
--about.)
--
-- - Function: int sigemptyset (sigset_t *SET)
--     This function initializes the signal set SET to exclude all of the
--     defined signals.  It always returns `0'.
--
-- - Function: int sigfillset (sigset_t *SET)
--     This function initializes the signal set SET to include all of the
--     defined signals.  Again, the return value is `0'.
--
-- - Function: int sigaddset (sigset_t *SET, int SIGNUM)
--     This function adds the signal SIGNUM to the signal set SET.  All
--     `sigaddset' does is modify SET; it does not block or unblock any
--     signals.
--
--     The return value is `0' on success and `-1' on failure.  The
--     following `errno' error condition is defined for this function:
--
--    `EINVAL'
--          The SIGNUM argument doesn't specify a valid signal.
--
-- - Function: int sigdelset (sigset_t *SET, int SIGNUM)
--     This function removes the signal SIGNUM from the signal set SET.
--     All `sigdelset' does is modify SET; it does not block or unblock
--     any signals.  The return value and error conditions are the same
--     as for `sigaddset'.
--
--   Finally, there is a function to test what signals are in a signal
--set:
--
-- - Function: int sigismember (const sigset_t *SET, int SIGNUM)
--     The `sigismember' function tests whether the signal SIGNUM is a
--     member of the signal set SET.  It returns `1' if the signal is in
--     the set, `0' if not, and `-1' if there is an error.
--
--     The following `errno' error condition is defined for this function:
--
--    `EINVAL'
--          The SIGNUM argument doesn't specify a valid signal.
--
--
--File: libc.info,  Node: Process Signal Mask,  Next: Testing for Delivery,  
Prev: Signal Sets,  Up: Blocking Signals
--
--Process Signal Mask
---------------------
--
--   The collection of signals that are currently blocked is called the
--"signal mask".  Each process has its own signal mask.  When you create
--a new process (*note Creating a Process::.), it inherits its parent's
--mask.  You can block or unblock signals with total flexibility by
--modifying the signal mask.
--
--   The prototype for the `sigprocmask' function is in `signal.h'.
--
-- - Function: int sigprocmask (int HOW, const sigset_t *SET, sigset_t
--          *OLDSET)
--     The `sigprocmask' function is used to examine or change the calling
--     process's signal mask.  The HOW argument determines how the signal
--     mask is changed, and must be one of the following values:
--
--    `SIG_BLOCK'
--          Block the signals in `set'--add them to the existing mask.  In
--          other words, the new mask is the union of the existing mask
--          and SET.
--
--    `SIG_UNBLOCK'
--          Unblock the signals in SET--remove them from the existing
--          mask.
--
--    `SIG_SETMASK'
--          Use SET for the mask; ignore the previous value of the mask.
--
--     The last argument, OLDSET, is used to return information about the
--     old process signal mask.  If you just want to change the mask
--     without looking at it, pass a null pointer as the OLDSET argument.
--     Similarly, if you want to know what's in the mask without changing
--     it, pass a null pointer for SET (in this case the HOW argument is
--     not significant).  The OLDSET argument is often used to remember
--     the previous signal mask in order to restore it later.  (Since the
--     signal mask is inherited over `fork' and `exec' calls, you can't
--     predict what its contents are when your program starts running.)
--
--     If invoking `sigprocmask' causes any pending signals to be
--     unblocked, at least one of those signals is delivered to the
--     process before `sigprocmask' returns.  The order in which pending
--     signals are delivered is not specified, but you can control the
--     order explicitly by making multiple `sigprocmask' calls to unblock
--     various signals one at a time.
--
--     The `sigprocmask' function returns `0' if successful, and `-1' to
--     indicate an error.  The following `errno' error conditions are
--     defined for this function:
--
--    `EINVAL'
--          The HOW argument is invalid.
--
--     You can't block the `SIGKILL' and `SIGSTOP' signals, but if the
--     signal set includes these, `sigprocmask' just ignores them instead
--     of returning an error status.
--
--     Remember, too, that blocking program error signals such as `SIGFPE'
--     leads to undesirable results for signals generated by an actual
--     program error (as opposed to signals sent with `raise' or `kill').
--     This is because your program may be too broken to be able to
--     continue executing to a point where the signal is unblocked again.
--     *Note Program Error Signals::.
--
--
--File: libc.info,  Node: Testing for Delivery,  Next: Blocking for Handler,  
Prev: Process Signal Mask,  Up: Blocking Signals
--
--Blocking to Test for Delivery of a Signal
-------------------------------------------
--
--   Now for a simple example.  Suppose you establish a handler for
--`SIGALRM' signals that sets a flag whenever a signal arrives, and your
--main program checks this flag from time to time and then resets it.
--You can prevent additional `SIGALRM' signals from arriving in the
--meantime by wrapping the critical part of the code with calls to
--`sigprocmask', like this:
--
--     /* This variable is set by the SIGALRM signal handler. */
--     volatile sig_atomic_t flag = 0;
--     
--     int
--     main (void)
--     {
--       sigset_t block_alarm;
--     
--       ...
--     
--       /* Initialize the signal mask. */
--       sigemptyset (&block_alarm);
--       sigaddset (&block_alarm, SIGALRM);
--     while (1)
--         {
--           /* Check if a signal has arrived; if so, reset the flag. */
--           sigprocmask (SIG_BLOCK, &block_alarm, NULL);
--           if (flag)
--             {
--               ACTIONS-IF-NOT-ARRIVED
--               flag = 0;
--             }
--           sigprocmask (SIG_UNBLOCK, &block_alarm, NULL);
--     
--           ...
--         }
--     }
--
--
--File: libc.info,  Node: Blocking for Handler,  Next: Checking for Pending 
Signals,  Prev: Testing for Delivery,  Up: Blocking Signals
--
--Blocking Signals for a Handler
--------------------------------
--
--   When a signal handler is invoked, you usually want it to be able to
--finish without being interrupted by another signal.  From the moment the
--handler starts until the moment it finishes, you must block signals that
--might confuse it or corrupt its data.
--
--   When a handler function is invoked on a signal, that signal is
--automatically blocked (in addition to any other signals that are already
--in the process's signal mask) during the time the handler is running.
--If you set up a handler for `SIGTSTP', for instance, then the arrival
--of that signal forces further `SIGTSTP' signals to wait during the
--execution of the handler.
--
--   However, by default, other kinds of signals are not blocked; they can
--arrive during handler execution.
--
--   The reliable way to block other kinds of signals during the
--execution of the handler is to use the `sa_mask' member of the
--`sigaction' structure.
--
--   Here is an example:
--
--     #include <signal.h>
--     #include <stddef.h>
--     
--     void catch_stop ();
--     
--     void
--     install_handler (void)
--     {
--       struct sigaction setup_action;
--       sigset_t block_mask;
--     
--       sigemptyset (&block_mask);
--       /* Block other terminal-generated signals while handler runs. */
--       sigaddset (&block_mask, SIGINT);
--       sigaddset (&block_mask, SIGQUIT);
--       setup_action.sa_handler = catch_stop;
--       setup_action.sa_mask = block_mask;
--       setup_action.sa_flags = 0;
--       sigaction (SIGTSTP, &setup_action, NULL);
--     }
--
--   This is more reliable than blocking the other signals explicitly in
--the code for the handler.  If you block signals explicitly in the
--handler, you can't avoid at least a short interval at the beginning of
--the handler where they are not yet blocked.
--
--   You cannot remove signals from the process's current mask using this
--mechanism.  However, you can make calls to `sigprocmask' within your
--handler to block or unblock signals as you wish.
--
--   In any case, when the handler returns, the system restores the mask
--that was in place before the handler was entered.  If any signals that
--become unblocked by this restoration are pending, the process will
--receive those signals immediately, before returning to the code that was
--interrupted.
--
--
--File: libc.info,  Node: Checking for Pending Signals,  Next: Remembering a 
Signal,  Prev: Blocking for Handler,  Up: Blocking Signals
--
--Checking for Pending Signals
------------------------------
--
--   You can find out which signals are pending at any time by calling
--`sigpending'.  This function is declared in `signal.h'.
--
-- - Function: int sigpending (sigset_t *SET)
--     The `sigpending' function stores information about pending signals
--     in SET.  If there is a pending signal that is blocked from
--     delivery, then that signal is a member of the returned set.  (You
--     can test whether a particular signal is a member of this set using
--     `sigismember'; see *Note Signal Sets::.)
--
--     The return value is `0' if successful, and `-1' on failure.
--
--   Testing whether a signal is pending is not often useful.  Testing
--when that signal is not blocked is almost certainly bad design.
--
--   Here is an example.
--
--     #include <signal.h>
--     #include <stddef.h>
--     
--     sigset_t base_mask, waiting_mask;
--     
--     sigemptyset (&base_mask);
--     sigaddset (&base_mask, SIGINT);
--     sigaddset (&base_mask, SIGTSTP);
--     
--     /* Block user interrupts while doing other processing. */
--     sigprocmask (SIG_SETMASK, &base_mask, NULL);
--     ...
--     
--     /* After a while, check to see whether any signals are pending. */
--     sigpending (&waiting_mask);
--     if (sigismember (&waiting_mask, SIGINT)) {
--       /* User has tried to kill the process. */
--     }
--     else if (sigismember (&waiting_mask, SIGTSTP)) {
--       /* User has tried to stop the process. */
--     }
--
--   Remember that if there is a particular signal pending for your
--process, additional signals of that same type that arrive in the
--meantime might be discarded.  For example, if a `SIGINT' signal is
--pending when another `SIGINT' signal arrives, your program will
--probably only see one of them when you unblock this signal.
--
--   *Portability Note:* The `sigpending' function is new in POSIX.1.
--Older systems have no equivalent facility.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-22 
glibc-2.0.1/manual/libc.info-22
---- ../glibc-2.0.1/manual/libc.info-22 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-22    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1247 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Remembering a Signal,  Prev: Checking for Pending 
Signals,  Up: Blocking Signals
--
--Remembering a Signal to Act On Later
--------------------------------------
--
--   Instead of blocking a signal using the library facilities, you can
--get almost the same results by making the handler set a flag to be
--tested later, when you "unblock".  Here is an example:
--
--     /* If this flag is nonzero, don't handle the signal right away. */
--     volatile sig_atomic_t signal_pending;
--     
--     /* This is nonzero if a signal arrived and was not handled. */
--     volatile sig_atomic_t defer_signal;
--     
--     void
--     handler (int signum)
--     {
--       if (defer_signal)
--         signal_pending = signum;
--       else
--         ... /* "Really" handle the signal. */
--     }
--     
--     ...
--     
--     void
--     update_mumble (int frob)
--     {
--       /* Prevent signals from having immediate effect. */
--       defer_signal++;
--       /* Now update `mumble', without worrying about interruption. */
--       mumble.a = 1;
--       mumble.b = hack ();
--       mumble.c = frob;
--       /* We have updated `mumble'.  Handle any signal that came in. */
--       defer_signal--;
--       if (defer_signal == 0 && signal_pending != 0)
--         raise (signal_pending);
--     }
--
--   Note how the particular signal that arrives is stored in
--`signal_pending'.  That way, we can handle several types of
--inconvenient signals with the same mechanism.
--
--   We increment and decrement `defer_signal' so that nested critical
--sections will work properly; thus, if `update_mumble' were called with
--`signal_pending' already nonzero, signals would be deferred not only
--within `update_mumble', but also within the caller.  This is also why
--we do not check `signal_pending' if `defer_signal' is still nonzero.
--
--   The incrementing and decrementing of `defer_signal' require more
--than one instruction; it is possible for a signal to happen in the
--middle.  But that does not cause any problem.  If the signal happens
--early enough to see the value from before the increment or decrement,
--that is equivalent to a signal which came before the beginning of the
--increment or decrement, which is a case that works properly.
--
--   It is absolutely vital to decrement `defer_signal' before testing
--`signal_pending', because this avoids a subtle bug.  If we did these
--things in the other order, like this,
--
--       if (defer_signal == 1 && signal_pending != 0)
--         raise (signal_pending);
--       defer_signal--;
--
--then a signal arriving in between the `if' statement and the decrement
--would be effectively "lost" for an indefinite amount of time.  The
--handler would merely set `defer_signal', but the program having already
--tested this variable, it would not test the variable again.
--
--   Bugs like these are called "timing errors".  They are especially bad
--because they happen only rarely and are nearly impossible to reproduce.
--You can't expect to find them with a debugger as you would find a
--reproducible bug.  So it is worth being especially careful to avoid
--them.
--
--   (You would not be tempted to write the code in this order, given the
--use of `defer_signal' as a counter which must be tested along with
--`signal_pending'.  After all, testing for zero is cleaner than testing
--for one.  But if you did not use `defer_signal' as a counter, and gave
--it values of zero and one only, then either order might seem equally
--simple.  This is a further advantage of using a counter for
--`defer_signal': it will reduce the chance you will write the code in
--the wrong order and create a subtle bug.)
--
--
--File: libc.info,  Node: Waiting for a Signal,  Next: Signal Stack,  Prev: 
Blocking Signals,  Up: Signal Handling
--
--Waiting for a Signal
--====================
--
--   If your program is driven by external events, or uses signals for
--synchronization, then when it has nothing to do it should probably wait
--until a signal arrives.
--
--* Menu:
--
--* Using Pause::                 The simple way, using `pause'.
--* Pause Problems::              Why the simple way is often not very good.
--* Sigsuspend::                  Reliably waiting for a specific signal.
--
--
--File: libc.info,  Node: Using Pause,  Next: Pause Problems,  Up: Waiting for 
a Signal
--
--Using `pause'
---------------
--
--   The simple way to wait until a signal arrives is to call `pause'.
--Please read about its disadvantages, in the following section, before
--you use it.
--
-- - Function: int pause ()
--     The `pause' function suspends program execution until a signal
--     arrives whose action is either to execute a handler function, or to
--     terminate the process.
--
--     If the signal causes a handler function to be executed, then
--     `pause' returns.  This is considered an unsuccessful return (since
--     "successful" behavior would be to suspend the program forever), so
--     the return value is `-1'.  Even if you specify that other
--     primitives should resume when a system handler returns (*note
--     Interrupted Primitives::.), this has no effect on `pause'; it
--     always fails when a signal is handled.
--
--     The following `errno' error conditions are defined for this
--     function:
--
--    `EINTR'
--          The function was interrupted by delivery of a signal.
--
--     If the signal causes program termination, `pause' doesn't return
--     (obviously).
--
--     The `pause' function is declared in  `unistd.h'.
--
--
--File: libc.info,  Node: Pause Problems,  Next: Sigsuspend,  Prev: Using 
Pause,  Up: Waiting for a Signal
--
--Problems with `pause'
-----------------------
--
--   The simplicity of `pause' can conceal serious timing errors that can
--make a program hang mysteriously.
--
--   It is safe to use `pause' if the real work of your program is done
--by the signal handlers themselves, and the "main program" does nothing
--but call `pause'.  Each time a signal is delivered, the handler will do
--the next batch of work that is to be done, and then return, so that the
--main loop of the program can call `pause' again.
--
--   You can't safely use `pause' to wait until one more signal arrives,
--and then resume real work.  Even if you arrange for the signal handler
--to cooperate by setting a flag, you still can't use `pause' reliably.
--Here is an example of this problem:
--
--     /* `usr_interrupt' is set by the signal handler.  */
--     if (!usr_interrupt)
--       pause ();
--     
--     /* Do work once the signal arrives.  */
--     ...
--
--This has a bug: the signal could arrive after the variable
--`usr_interrupt' is checked, but before the call to `pause'.  If no
--further signals arrive, the process would never wake up again.
--
--   You can put an upper limit on the excess waiting by using `sleep' in
--a loop, instead of using `pause'.  (*Note Sleeping::, for more about
--`sleep'.)  Here is what this looks like:
--
--     /* `usr_interrupt' is set by the signal handler.
--     while (!usr_interrupt)
--       sleep (1);
--     
--     /* Do work once the signal arrives.  */
--     ...
--
--   For some purposes, that is good enough.  But with a little more
--complexity, you can wait reliably until a particular signal handler is
--run, using `sigsuspend'.  *Note Sigsuspend::.
--
--
--File: libc.info,  Node: Sigsuspend,  Prev: Pause Problems,  Up: Waiting for a 
Signal
--
--Using `sigsuspend'
--------------------
--
--   The clean and reliable way to wait for a signal to arrive is to
--block it and then use `sigsuspend'.  By using `sigsuspend' in a loop,
--you can wait for certain kinds of signals, while letting other kinds of
--signals be handled by their handlers.
--
-- - Function: int sigsuspend (const sigset_t *SET)
--     This function replaces the process's signal mask with SET and then
--     suspends the process until a signal is delivered whose action is
--     either to terminate the process or invoke a signal handling
--     function.  In other words, the program is effectively suspended
--     until one of the signals that is not a member of SET arrives.
--
--     If the process is woken up by deliver of a signal that invokes a
--     handler function, and the handler function returns, then
--     `sigsuspend' also returns.
--
--     The mask remains SET only as long as `sigsuspend' is waiting.  The
--     function `sigsuspend' always restores the previous signal mask
--     when it returns.
--
--     The return value and error conditions are the same as for `pause'.
--
--   With `sigsuspend', you can replace the `pause' or `sleep' loop in
--the previous section with something completely reliable:
--
--     sigset_t mask, oldmask;
--     
--     ...
--     
--     /* Set up the mask of signals to temporarily block. */
--     sigemptyset (&mask);
--     sigaddset (&mask, SIGUSR1);
--     
--     ...
--     
--     /* Wait for a signal to arrive. */
--     sigprocmask (SIG_BLOCK, &mask, &oldmask);
--     while (!usr_interrupt)
--       sigsuspend (&oldmask);
--     sigprocmask (SIG_UNBLOCK, &mask, NULL);
--
--   This last piece of code is a little tricky.  The key point to
--remember here is that when `sigsuspend' returns, it resets the process's
--signal mask to the original value, the value from before the call to
--`sigsuspend'--in this case, the `SIGUSR1' signal is once again blocked.
--The second call to `sigprocmask' is necessary to explicitly unblock
--this signal.
--
--   One other point: you may be wondering why the `while' loop is
--necessary at all, since the program is apparently only waiting for one
--`SIGUSR1' signal.  The answer is that the mask passed to `sigsuspend'
--permits the process to be woken up by the delivery of other kinds of
--signals, as well--for example, job control signals.  If the process is
--woken up by a signal that doesn't set `usr_interrupt', it just suspends
--itself again until the "right" kind of signal eventually arrives.
--
--   This technique takes a few more lines of preparation, but that is
--needed just once for each kind of wait criterion you want to use.  The
--code that actually waits is just four lines.
--
--
--File: libc.info,  Node: Signal Stack,  Next: BSD Signal Handling,  Prev: 
Waiting for a Signal,  Up: Signal Handling
--
--Using a Separate Signal Stack
--=============================
--
--   A signal stack is a special area of memory to be used as the
--execution stack during signal handlers.  It should be fairly large, to
--avoid any danger that it will overflow in turn; the macro `SIGSTKSZ' is
--defined to a canonical size for signal stacks.  You can use `malloc' to
--allocate the space for the stack.  Then call `sigaltstack' or
--`sigstack' to tell the system to use that space for the signal stack.
--
--   You don't need to write signal handlers differently in order to use a
--signal stack.  Switching from one stack to the other happens
--automatically.  (Some non-GNU debuggers on some machines may get
--confused if you examine a stack trace while a handler that uses the
--signal stack is running.)
--
--   There are two interfaces for telling the system to use a separate
--signal stack.  `sigstack' is the older interface, which comes from 4.2
--BSD.  `sigaltstack' is the newer interface, and comes from 4.4 BSD.
--The `sigaltstack' interface has the advantage that it does not require
--your program to know which direction the stack grows, which depends on
--the specific machine and operating system.
--
-- - Data Type: struct sigaltstack
--     This structure describes a signal stack.  It contains the
--     following members:
--
--    `void *ss_sp'
--          This points to the base of the signal stack.
--
--    `size_t ss_size'
--          This is the size (in bytes) of the signal stack which `ss_sp'
--          points to.  You should set this to however much space you
--          allocated for the stack.
--
--          There are two macros defined in `signal.h' that you should
--          use in calculating this size:
--
--         `SIGSTKSZ'
--               This is the canonical size for a signal stack.  It is
--               judged to be sufficient for normal uses.
--
--         `MINSIGSTKSZ'
--               This is the amount of signal stack space the operating
--               system needs just to implement signal delivery.  The
--               size of a signal stack *must* be greater than this.
--
--               For most cases, just using `SIGSTKSZ' for `ss_size' is
--               sufficient.  But if you know how much stack space your
--               program's signal handlers will need, you may want to use
--               a different size.  In this case, you should allocate
--               `MINSIGSTKSZ' additional bytes for the signal stack and
--               increase `ss_size' accordingly.
--
--    `int ss_flags'
--          This field contains the bitwise OR of these flags:
--
--         `SA_DISABLE'
--               This tells the system that it should not use the signal
--               stack.
--
--         `SA_ONSTACK'
--               This is set by the system, and indicates that the signal
--               stack is currently in use.  If this bit is not set, then
--               signals will be delivered on the normal user stack.
--
-- - Function: int sigaltstack (const struct sigaltstack *STACK, struct
--          sigaltstack *OLDSTACK)
--     The `sigaltstack' function specifies an alternate stack for use
--     during signal handling.  When a signal is received by the process
--     and its action indicates that the signal stack is used, the system
--     arranges a switch to the currently installed signal stack while
--     the handler for that signal is executed.
--
--     If OLDSTACK is not a null pointer, information about the currently
--     installed signal stack is returned in the location it points to.
--     If STACK is not a null pointer, then this is installed as the new
--     stack for use by signal handlers.
--
--     The return value is `0' on success and `-1' on failure.  If
--     `sigaltstack' fails, it sets `errno' to one of these values:
--
--    `'
--    `EINVAL'
--          You tried to disable a stack that was in fact currently in
--          use.
--
--    `ENOMEM'
--          The size of the alternate stack was too small.  It must be
--          greater than `MINSIGSTKSZ'.
--
--   Here is the older `sigstack' interface.  You should use
--`sigaltstack' instead on systems that have it.
--
-- - Data Type: struct sigstack
--     This structure describes a signal stack.  It contains the
--     following members:
--
--    `void *ss_sp'
--          This is the stack pointer.  If the stack grows downwards on
--          your machine, this should point to the top of the area you
--          allocated.  If the stack grows upwards, it should point to
--          the bottom.
--
--    `int ss_onstack'
--          This field is true if the process is currently using this
--          stack.
--
-- - Function: int sigstack (const struct sigstack *STACK, struct
--          sigstack *OLDSTACK)
--     The `sigstack' function specifies an alternate stack for use during
--     signal handling.  When a signal is received by the process and its
--     action indicates that the signal stack is used, the system
--     arranges a switch to the currently installed signal stack while
--     the handler for that signal is executed.
--
--     If OLDSTACK is not a null pointer, information about the currently
--     installed signal stack is returned in the location it points to.
--     If STACK is not a null pointer, then this is installed as the new
--     stack for use by signal handlers.
--
--     The return value is `0' on success and `-1' on failure.
--
--
--File: libc.info,  Node: BSD Signal Handling,  Prev: Signal Stack,  Up: Signal 
Handling
--
--BSD Signal Handling
--===================
--
--   This section describes alternative signal handling functions derived
--from BSD Unix.  These facilities were an advance, in their time; today,
--they are mostly obsolete, and supported mainly for compatibility with
--BSD Unix.
--
--   There are many similarities between the BSD and POSIX signal handling
--facilities, because the POSIX facilities were inspired by the BSD
--facilities.  Besides having different names for all the functions to
--avoid conflicts, the main differences between the two are:
--
--   * BSD Unix represents signal masks as an `int' bit mask, rather than
--     as a `sigset_t' object.
--
--   * The BSD facilities use a different default for whether an
--     interrupted primitive should fail or resume.  The POSIX facilities
--     make system calls fail unless you specify that they should resume.
--     With the BSD facility, the default is to make system calls resume
--     unless you say they should fail.  *Note Interrupted Primitives::.
--
--   The BSD facilities are declared in `signal.h'.
--
--* Menu:
--
--* BSD Handler::                 BSD Function to Establish a Handler.
--* Blocking in BSD::             BSD Functions for Blocking Signals.
--
--
--File: libc.info,  Node: BSD Handler,  Next: Blocking in BSD,  Up: BSD Signal 
Handling
--
--BSD Function to Establish a Handler
-------------------------------------
--
-- - Data Type: struct sigvec
--     This data type is the BSD equivalent of `struct sigaction' (*note
--     Advanced Signal Handling::.); it is used to specify signal actions
--     to the `sigvec' function.  It contains the following members:
--
--    `sighandler_t sv_handler'
--          This is the handler function.
--
--    `int sv_mask'
--          This is the mask of additional signals to be blocked while
--          the handler function is being called.
--
--    `int sv_flags'
--          This is a bit mask used to specify various flags which affect
--          the behavior of the signal.  You can also refer to this field
--          as `sv_onstack'.
--
--   These symbolic constants can be used to provide values for the
--`sv_flags' field of a `sigvec' structure.  This field is a bit mask
--value, so you bitwise-OR the flags of interest to you together.
--
-- - Macro: int SV_ONSTACK
--     If this bit is set in the `sv_flags' field of a `sigvec'
--     structure, it means to use the signal stack when delivering the
--     signal.
--
-- - Macro: int SV_INTERRUPT
--     If this bit is set in the `sv_flags' field of a `sigvec'
--     structure, it means that system calls interrupted by this kind of
--     signal should not be restarted if the handler returns; instead,
--     the system calls should return with a `EINTR' error status.  *Note
--     Interrupted Primitives::.
--
-- - Macro: int SV_RESETHAND
--     If this bit is set in the `sv_flags' field of a `sigvec'
--     structure, it means to reset the action for the signal back to
--     `SIG_DFL' when the signal is received.
--
-- - Function: int sigvec (int SIGNUM, const struct sigvec *ACTION,struct
--          sigvec *OLD-ACTION)
--     This function is the equivalent of `sigaction' (*note Advanced
--     Signal Handling::.); it installs the action ACTION for the signal
--     SIGNUM, returning information about the previous action in effect
--     for that signal in OLD-ACTION.
--
-- - Function: int siginterrupt (int SIGNUM, int FAILFLAG)
--     This function specifies which approach to use when certain
--     primitives are interrupted by handling signal SIGNUM.  If FAILFLAG
--     is false, signal SIGNUM restarts primitives.  If FAILFLAG is true,
--     handling SIGNUM causes these primitives to fail with error code
--     `EINTR'.  *Note Interrupted Primitives::.
--
--
--File: libc.info,  Node: Blocking in BSD,  Prev: BSD Handler,  Up: BSD Signal 
Handling
--
--BSD Functions for Blocking Signals
------------------------------------
--
-- - Macro: int sigmask (int SIGNUM)
--     This macro returns a signal mask that has the bit for signal SIGNUM
--     set.  You can bitwise-OR the results of several calls to `sigmask'
--     together to specify more than one signal.  For example,
--
--          (sigmask (SIGTSTP) | sigmask (SIGSTOP)
--           | sigmask (SIGTTIN) | sigmask (SIGTTOU))
--
--     specifies a mask that includes all the job-control stop signals.
--
-- - Function: int sigblock (int MASK)
--     This function is equivalent to `sigprocmask' (*note Process Signal
--     Mask::.) with a HOW argument of `SIG_BLOCK': it adds the signals
--     specified by MASK to the calling process's set of blocked signals.
--     The return value is the previous set of blocked signals.
--
-- - Function: int sigsetmask (int MASK)
--     This function equivalent to `sigprocmask' (*note Process Signal
--     Mask::.) with a HOW argument of `SIG_SETMASK': it sets the calling
--     process's signal mask to MASK.  The return value is the previous
--     set of blocked signals.
--
-- - Function: int sigpause (int MASK)
--     This function is the equivalent of `sigsuspend' (*note Waiting for
--     a Signal::.):  it sets the calling process's signal mask to MASK,
--     and waits for a signal to arrive.  On return the previous set of
--     blocked signals is restored.
--
--
--File: libc.info,  Node: Process Startup,  Next: Processes,  Prev: Signal 
Handling,  Up: Top
--
--Process Startup and Termination
--*******************************
--
--   "Processes" are the primitive units for allocation of system
--resources.  Each process has its own address space and (usually) one
--thread of control.  A process executes a program; you can have multiple
--processes executing the same program, but each process has its own copy
--of the program within its own address space and executes it
--independently of the other copies.
--
--   This chapter explains what your program should do to handle the
--startup of a process, to terminate its process, and to receive
--information (arguments and the environment) from the parent process.
--
--* Menu:
--
--* Program Arguments::           Parsing your program's command-line arguments.
--* Environment Variables::       How to access parameters inherited from
--                               a parent process.
--* Program Termination::         How to cause a process to terminate and
--                               return status information to its parent.
--
--
--File: libc.info,  Node: Program Arguments,  Next: Environment Variables,  Up: 
Process Startup
--
--Program Arguments
--=================
--
--   The system starts a C program by calling the function `main'.  It is
--up to you to write a function named `main'--otherwise, you won't even
--be able to link your program without errors.
--
--   In ISO C you can define `main' either to take no arguments, or to
--take two arguments that represent the command line arguments to the
--program, like this:
--
--     int main (int ARGC, char *ARGV[])
--
--   The command line arguments are the whitespace-separated tokens given
--in the shell command used to invoke the program; thus, in `cat foo
--bar', the arguments are `foo' and `bar'.  The only way a program can
--look at its command line arguments is via the arguments of `main'.  If
--`main' doesn't take arguments, then you cannot get at the command line.
--
--   The value of the ARGC argument is the number of command line
--arguments.  The ARGV argument is a vector of C strings; its elements
--are the individual command line argument strings.  The file name of the
--program being run is also included in the vector as the first element;
--the value of ARGC counts this element.  A null pointer always follows
--the last element: `ARGV[ARGC]' is this null pointer.
--
--   For the command `cat foo bar', ARGC is 3 and ARGV has three
--elements, `"cat"', `"foo"' and `"bar"'.
--
--   If the syntax for the command line arguments to your program is
--simple enough, you can simply pick the arguments off from ARGV by hand.
--But unless your program takes a fixed number of arguments, or all of the
--arguments are interpreted in the same way (as file names, for example),
--you are usually better off using `getopt' to do the parsing.
--
--   In Unix systems you can define `main' a third way, using three
--arguments:
--
--     int main (int ARGC, char *ARGV[], char *ENVP)
--
--   The first two arguments are just the same.  The third argument ENVP
--gives the process's environment; it is the same as the value of
--`environ'.  *Note Environment Variables::.  POSIX.1 does not allow this
--three-argument form, so to be portable it is best to write `main' to
--take two arguments, and use the value of `environ'.
--
--* Menu:
--
--* Argument Syntax::             By convention, options start with a hyphen.
--* Parsing Options::             The `getopt' function.
--* Example of Getopt::           An example of parsing options with `getopt'.
--* Long Options::                GNU suggests utilities accept long-named 
options.
--                         Here is how to do that.
--* Long Option Example::         An example of using `getopt_long'.
--* Suboptions::                  Some programs need more detailed options.
--* Suboptions Example::          This shows how it could be done for `mount'.
--
--
--File: libc.info,  Node: Argument Syntax,  Next: Parsing Options,  Up: Program 
Arguments
--
--Program Argument Syntax Conventions
-------------------------------------
--
--   POSIX recommends these conventions for command line arguments.
--`getopt' (*note Parsing Options::.) makes it easy to implement them.
--
--   * Arguments are options if they begin with a hyphen delimiter (`-').
--
--   * Multiple options may follow a hyphen delimiter in a single token if
--     the options do not take arguments.  Thus, `-abc' is equivalent to
--     `-a -b -c'.
--
--   * Option names are single alphanumeric characters (as for `isalnum';
--     see *Note Classification of Characters::).
--
--   * Certain options require an argument.  For example, the `-o' command
--     of the `ld' command requires an argument--an output file name.
--
--   * An option and its argument may or may not appear as separate
--     tokens.  (In other words, the whitespace separating them is
--     optional.)  Thus, `-o foo' and `-ofoo' are equivalent.
--
--   * Options typically precede other non-option arguments.
--
--     The implementation of `getopt' in the GNU C library normally makes
--     it appear as if all the option arguments were specified before all
--     the non-option arguments for the purposes of parsing, even if the
--     user of your program intermixed option and non-option arguments.
--     It does this by reordering the elements of the ARGV array.  This
--     behavior is nonstandard; if you want to suppress it, define the
--     `_POSIX_OPTION_ORDER' environment variable.  *Note Standard
--     Environment::.
--
--   * The argument `--' terminates all options; any following arguments
--     are treated as non-option arguments, even if they begin with a
--     hyphen.
--
--   * A token consisting of a single hyphen character is interpreted as
--     an ordinary non-option argument.  By convention, it is used to
--     specify input from or output to the standard input and output
--     streams.
--
--   * Options may be supplied in any order, or appear multiple times.
--     The interpretation is left up to the particular application
--     program.
--
--   GNU adds "long options" to these conventions.  Long options consist
--of `--' followed by a name made of alphanumeric characters and dashes.
--Option names are typically one to three words long, with hyphens to
--separate words.  Users can abbreviate the option names as long as the
--abbreviations are unique.
--
--   To specify an argument for a long option, write `--NAME=VALUE'.
--This syntax enables a long option to accept an argument that is itself
--optional.
--
--   Eventually, the GNU system will provide completion for long option
--names in the shell.
--
--
--File: libc.info,  Node: Parsing Options,  Next: Example of Getopt,  Prev: 
Argument Syntax,  Up: Program Arguments
--
--Parsing Program Options
-------------------------
--
--   Here are the details about how to call the `getopt' function.  To
--use this facility, your program must include the header file `unistd.h'.
--
-- - Variable: int opterr
--     If the value of this variable is nonzero, then `getopt' prints an
--     error message to the standard error stream if it encounters an
--     unknown option character or an option with a missing required
--     argument.  This is the default behavior.  If you set this variable
--     to zero, `getopt' does not print any messages, but it still
--     returns the character `?' to indicate an error.
--
-- - Variable: int optopt
--     When `getopt' encounters an unknown option character or an option
--     with a missing required argument, it stores that option character
--     in this variable.  You can use this for providing your own
--     diagnostic messages.
--
-- - Variable: int optind
--     This variable is set by `getopt' to the index of the next element
--     of the ARGV array to be processed.  Once `getopt' has found all of
--     the option arguments, you can use this variable to determine where
--     the remaining non-option arguments begin.  The initial value of
--     this variable is `1'.
--
-- - Variable: char * optarg
--     This variable is set by `getopt' to point at the value of the
--     option argument, for those options that accept arguments.
--
-- - Function: int getopt (int ARGC, char **ARGV, const char *OPTIONS)
--     The `getopt' function gets the next option argument from the
--     argument list specified by the ARGV and ARGC arguments.  Normally
--     these values come directly from the arguments received by `main'.
--
--     The OPTIONS argument is a string that specifies the option
--     characters that are valid for this program.  An option character
--     in this string can be followed by a colon (`:') to indicate that
--     it takes a required argument.
--
--     If the OPTIONS argument string begins with a hyphen (`-'), this is
--     treated specially.  It permits arguments that are not options to be
--     returned as if they were associated with option character `\0'.
--
--     The `getopt' function returns the option character for the next
--     command line option.  When no more option arguments are available,
--     it returns `-1'.  There may still be more non-option arguments; you
--     must compare the external variable `optind' against the ARGC
--     parameter to check this.
--
--     If the option has an argument, `getopt' returns the argument by
--     storing it in the variable OPTARG.  You don't ordinarily need to
--     copy the `optarg' string, since it is a pointer into the original
--     ARGV array, not into a static area that might be overwritten.
--
--     If `getopt' finds an option character in ARGV that was not
--     included in OPTIONS, or a missing option argument, it returns `?'
--     and sets the external variable `optopt' to the actual option
--     character.  If the first character of OPTIONS is a colon (`:'),
--     then `getopt' returns `:' instead of `?' to indicate a missing
--     option argument.  In addition, if the external variable `opterr'
--     is nonzero (which is the default), `getopt' prints an error
--     message.
--
--
--File: libc.info,  Node: Example of Getopt,  Next: Long Options,  Prev: 
Parsing Options,  Up: Program Arguments
--
--Example of Parsing Arguments with `getopt'
--------------------------------------------
--
--   Here is an example showing how `getopt' is typically used.  The key
--points to notice are:
--
--   * Normally, `getopt' is called in a loop.  When `getopt' returns
--     `-1', indicating no more options are present, the loop terminates.
--
--   * A `switch' statement is used to dispatch on the return value from
--     `getopt'.  In typical use, each case just sets a variable that is
--     used later in the program.
--
--   * A second loop is used to process the remaining non-option
--     arguments.
--
--     #include <unistd.h>
--     #include <stdio.h>
--     
--     int
--     main (int argc, char **argv)
--     {
--       int aflag = 0;
--       int bflag = 0;
--       char *cvalue = NULL;
--       int index;
--       int c;
--     
--       opterr = 0;
--
--     while ((c = getopt (argc, argv, "abc:")) != -1)
--         switch (c)
--           {
--           case 'a':
--             aflag = 1;
--             break;
--           case 'b':
--             bflag = 1;
--             break;
--           case 'c':
--             cvalue = optarg;
--             break;
--           case '?':
--             if (isprint (optopt))
--               fprintf (stderr, "Unknown option `-%c'.\n", optopt);
--             else
--               fprintf (stderr,
--                        "Unknown option character `\\x%x'.\n",
--                        optopt);
--             return 1;
--           default:
--             abort ();
--           }
--
--     printf ("aflag = %d, bflag = %d, cvalue = %s\n", aflag, bflag, cvalue);
--     
--       for (index = optind; index < argc; index++)
--         printf ("Non-option argument %s\n", argv[index]);
--       return 0;
--     }
--
--   Here are some examples showing what this program prints with
--different combinations of arguments:
--
--     % testopt
--     aflag = 0, bflag = 0, cvalue = (null)
--     
--     % testopt -a -b
--     aflag = 1, bflag = 1, cvalue = (null)
--     
--     % testopt -ab
--     aflag = 1, bflag = 1, cvalue = (null)
--     
--     % testopt -c foo
--     aflag = 0, bflag = 0, cvalue = foo
--     
--     % testopt -cfoo
--     aflag = 0, bflag = 0, cvalue = foo
--     
--     % testopt arg1
--     aflag = 0, bflag = 0, cvalue = (null)
--     Non-option argument arg1
--     
--     % testopt -a arg1
--     aflag = 1, bflag = 0, cvalue = (null)
--     Non-option argument arg1
--     
--     % testopt -c foo arg1
--     aflag = 0, bflag = 0, cvalue = foo
--     Non-option argument arg1
--     
--     % testopt -a -- -b
--     aflag = 1, bflag = 0, cvalue = (null)
--     Non-option argument -b
--     
--     % testopt -a -
--     aflag = 1, bflag = 0, cvalue = (null)
--     Non-option argument -
--
--
--File: libc.info,  Node: Long Options,  Next: Long Option Example,  Prev: 
Example of Getopt,  Up: Program Arguments
--
--Parsing Long Options
----------------------
--
--   To accept GNU-style long options as well as single-character options,
--use `getopt_long' instead of `getopt'.  This function is declared in
--`getopt.h', not `unistd.h'.  You should make every program accept long
--options if it uses any options, for this takes little extra work and
--helps beginners remember how to use the program.
--
-- - Data Type: struct option
--     This structure describes a single long option name for the sake of
--     `getopt_long'.  The argument LONGOPTS must be an array of these
--     structures, one for each long option.  Terminate the array with an
--     element containing all zeros.
--
--     The `struct option' structure has these fields:
--
--    `const char *name'
--          This field is the name of the option.  It is a string.
--
--    `int has_arg'
--          This field says whether the option takes an argument.  It is
--          an integer, and there are three legitimate values:
--          `no_argument', `required_argument' and `optional_argument'.
--
--    `int *flag'
--    `int val'
--          These fields control how to report or act on the option when
--          it occurs.
--
--          If `flag' is a null pointer, then the `val' is a value which
--          identifies this option.  Often these values are chosen to
--          uniquely identify particular long options.
--
--          If `flag' is not a null pointer, it should be the address of
--          an `int' variable which is the flag for this option.  The
--          value in `val' is the value to store in the flag to indicate
--          that the option was seen.
--
-- - Function: int getopt_long (int ARGC, char **ARGV, const char
--          *SHORTOPTS, struct option *LONGOPTS, int *INDEXPTR)
--     Decode options from the vector ARGV (whose length is ARGC).  The
--     argument SHORTOPTS describes the short options to accept, just as
--     it does in `getopt'.  The argument LONGOPTS describes the long
--     options to accept (see above).
--
--     When `getopt_long' encounters a short option, it does the same
--     thing that `getopt' would do: it returns the character code for the
--     option, and stores the options argument (if it has one) in
--     `optarg'.
--
--     When `getopt_long' encounters a long option, it takes actions based
--     on the `flag' and `val' fields of the definition of that option.
--
--     If `flag' is a null pointer, then `getopt_long' returns the
--     contents of `val' to indicate which option it found.  You should
--     arrange distinct values in the `val' field for options with
--     different meanings, so you can decode these values after
--     `getopt_long' returns.  If the long option is equivalent to a short
--     option, you can use the short option's character code in `val'.
--
--     If `flag' is not a null pointer, that means this option should just
--     set a flag in the program.  The flag is a variable of type `int'
--     that you define.  Put the address of the flag in the `flag' field.
--     Put in the `val' field the value you would like this option to
--     store in the flag.  In this case, `getopt_long' returns `0'.
--
--     For any long option, `getopt_long' tells you the index in the array
--     LONGOPTS of the options definition, by storing it into
--     `*INDEXPTR'.  You can get the name of the option with
--     `LONGOPTS[*INDEXPTR].name'.  So you can distinguish among long
--     options either by the values in their `val' fields or by their
--     indices.  You can also distinguish in this way among long options
--     that set flags.
--
--     When a long option has an argument, `getopt_long' puts the argument
--     value in the variable `optarg' before returning.  When the option
--     has no argument, the value in `optarg' is a null pointer.  This is
--     how you can tell whether an optional argument was supplied.
--
--     When `getopt_long' has no more options to handle, it returns `-1',
--     and leaves in the variable `optind' the index in ARGV of the next
--     remaining argument.
--
--
--File: libc.info,  Node: Long Option Example,  Next: Suboptions,  Prev: Long 
Options,  Up: Program Arguments
--
--Example of Parsing Long Options
---------------------------------
--
--     #include <stdio.h>
--     #include <stdlib.h>
--     #include <getopt.h>
--     
--     /* Flag set by `--verbose'. */
--     static int verbose_flag;
--     
--     int
--     main (argc, argv)
--          int argc;
--          char **argv;
--     {
--       int c;
--     
--       while (1)
--         {
--           static struct option long_options[] =
--             {
--               /* These options set a flag. */
--               {"verbose", 0, &verbose_flag, 1},
--               {"brief", 0, &verbose_flag, 0},
--               /* These options don't set a flag.
--                  We distinguish them by their indices. */
--               {"add", 1, 0, 0},
--               {"append", 0, 0, 0},
--               {"delete", 1, 0, 0},
--               {"create", 0, 0, 0},
--               {"file", 1, 0, 0},
--               {0, 0, 0, 0}
--             };
--           /* `getopt_long' stores the option index here. */
--           int option_index = 0;
--     
--           c = getopt_long (argc, argv, "abc:d:",
--                            long_options, &option_index);
--     
--           /* Detect the end of the options. */
--           if (c == -1)
--             break;
--     
--           switch (c)
--             {
--             case 0:
--               /* If this option set a flag, do nothing else now. */
--               if (long_options[option_index].flag != 0)
--                 break;
--               printf ("option %s", long_options[option_index].name);
--               if (optarg)
--                 printf (" with arg %s", optarg);
--               printf ("\n");
--               break;
--     
--             case 'a':
--               puts ("option -a\n");
--               break;
--     
--             case 'b':
--               puts ("option -b\n");
--               break;
--     
--             case 'c':
--               printf ("option -c with value `%s'\n", optarg);
--               break;
--     
--             case 'd':
--               printf ("option -d with value `%s'\n", optarg);
--               break;
--     
--             case '?':
--               /* `getopt_long' already printed an error message. */
--               break;
--     
--             default:
--               abort ();
--             }
--         }
--     
--       /* Instead of reporting `--verbose'
--          and `--brief' as they are encountered,
--          we report the final status resulting from them. */
--       if (verbose_flag)
--         puts ("verbose flag is set");
--     
--       /* Print any remaining command line arguments (not options). */
--       if (optind < argc)
--         {
--           printf ("non-option ARGV-elements: ");
--           while (optind < argc)
--             printf ("%s ", argv[optind++]);
--           putchar ('\n');
--         }
--     
--       exit (0);
--     }
--
--
--File: libc.info,  Node: Suboptions,  Next: Suboptions Example,  Prev: Long 
Option Example,  Up: Program Arguments
--
--Parsing of Suboptions
-----------------------
--
--   Having a single level of options is sometimes not enough.  There
--might be too many options which have to be available or a set of
--options is closely related.
--
--   For this case some programs use suboptions.  One of the most
--prominent programs is certainly `mount'(8).  The `-o' option take one
--argument which itself is a comma separated list of options.  To ease the
--programming of code like this the function `getsubopt' is available.
--
-- - Function: int getsubopt (char **OPTIONP, const char* const *TOKENS,
--          char **VALUEP)
--     The OPTIONP parameter must be a pointer to a variable containing
--     the address of the string to process.  When the function returns
--     the reference is updated to point to the next suboption or to the
--     terminating `\0' character if there is no more suboption available.
--
--     The TOKENS parameter references an array of strings containing the
--     known suboptions.  All strings must be `\0' terminated and to mark
--     the end a null pointer must be stored.  When `getsubopt' finds a
--     possible legal suboption it compares it with all strings available
--     in the TOKENS array and returns the index in the string as the
--     indicator.
--
--     In case the suboption has an associated value introduced by a `='
--     character, a pointer to the value is returned in VALUEP.  The
--     string is `\0' terminated.  If no argument is available VALUEP is
--     set to the null pointer.  By doing this the caller can check
--     whether a necessary value is given or whether no unexpected value
--     is present.
--
--     In case the next suboption in the string is not mentioned in the
--     TOKENS array the starting address of the suboption including a
--     possible value is returned in VALUEP and the return value of the
--     function is `-1'.
--
--
--File: libc.info,  Node: Suboptions Example,  Prev: Suboptions,  Up: Program 
Arguments
--
--Parsing of Suboptions Example
-------------------------------
--
--   The code which might appear in the `mount'(8) program is a perfect
--example of the use of `getsubopt':
--
--     #include <stdio.h>
--     #include <stdlib.h>
--     
--     int do_all;
--     const char *type;
--     int read_size;
--     int write_size;
--     int read_only;
--     
--     enum
--     {
--       RO_OPTION = 0,
--       RW_OPTION,
--       READ_SIZE_OPTION,
--       WRITE_SIZE_OPTION
--     };
--     
--     const char *mount_opts[] =
--     {
--       [RO_OPTION] = "ro",
--       [RW_OPTION] = "rw",
--       [READ_SIZE_OPTION] = "rsize",
--       [WRITE_SIZE_OPTION] = "wsize"
--     };
--     
--     int
--     main (int argc, char *argv[])
--     {
--       char *subopts, *value;
--       int opt;
--     
--       while ((opt = getopt (argc, argv, "at:o:")) != -1)
--         switch (opt)
--           {
--           case 'a':
--             do_all = 1;
--             break;
--           case 't':
--             type = optarg;
--             break;
--           case 'o':
--             subopts = optarg;
--             while (*subopts != '\0')
--               switch (getsubopt (&subopts, mount_opts, &value))
--                 {
--                 case RO_OPTION:
--                   read_only = 1;
--                   break;
--                 case RW_OPTION:
--                   read_only = 0;
--                   break;
--                 case READ_SIZE_OPTION:
--                   if (value == NULL)
--                     abort ();
--                   read_size = atoi (value);
--                   break;
--                 case WRITE_SIZE_OPTION:
--                   if (value == NULL)
--                     abort ();
--                   write_size = atoi (value);
--                   break;
--                 default:
--                   /* Unknown suboption. */
--                   printf ("Unknown suboption `%s'\n", value);
--                   break;
--                 }
--             break;
--           default:
--             abort ();
--           }
--     
--       /* Do the real work. */
--     
--       return 0;
--     }
--
--
--File: libc.info,  Node: Environment Variables,  Next: Program Termination,  
Prev: Program Arguments,  Up: Process Startup
--
--Environment Variables
--=====================
--
--   When a program is executed, it receives information about the
--context in which it was invoked in two ways.  The first mechanism uses
--the ARGV and ARGC arguments to its `main' function, and is discussed in
--*Note Program Arguments::.  The second mechanism uses "environment
--variables" and is discussed in this section.
--
--   The ARGV mechanism is typically used to pass command-line arguments
--specific to the particular program being invoked.  The environment, on
--the other hand, keeps track of information that is shared by many
--programs, changes infrequently, and that is less frequently used.
--
--   The environment variables discussed in this section are the same
--environment variables that you set using assignments and the `export'
--command in the shell.  Programs executed from the shell inherit all of
--the environment variables from the shell.
--
--   Standard environment variables are used for information about the
--user's home directory, terminal type, current locale, and so on; you
--can define additional variables for other purposes.  The set of all
--environment variables that have values is collectively known as the
--"environment".
--
--   Names of environment variables are case-sensitive and must not
--contain the character `='.  System-defined environment variables are
--invariably uppercase.
--
--   The values of environment variables can be anything that can be
--represented as a string.  A value must not contain an embedded null
--character, since this is assumed to terminate the string.
--
--* Menu:
--
--* Environment Access::          How to get and set the values of
--                         environment variables.
--* Standard Environment::        These environment variables have
--                         standard interpretations.
--
--
--File: libc.info,  Node: Environment Access,  Next: Standard Environment,  Up: 
Environment Variables
--
--Environment Access
--------------------
--
--   The value of an environment variable can be accessed with the
--`getenv' function.  This is declared in the header file `stdlib.h'.
--
-- - Function: char * getenv (const char *NAME)
--     This function returns a string that is the value of the environment
--     variable NAME.  You must not modify this string.  In some non-Unix
--     systems not using the GNU library, it might be overwritten by
--     subsequent calls to `getenv' (but not by any other library
--     function).  If the environment variable NAME is not defined, the
--     value is a null pointer.
--
-- - Function: int putenv (const char *STRING)
--     The `putenv' function adds or removes definitions from the
--     environment.  If the STRING is of the form `NAME=VALUE', the
--     definition is added to the environment.  Otherwise, the STRING is
--     interpreted as the name of an environment variable, and any
--     definition for this variable in the environment is removed.
--
--     The GNU library provides this function for compatibility with
--     SVID; it may not be available in other systems.
--
--   You can deal directly with the underlying representation of
--environment objects to add more variables to the environment (for
--example, to communicate with another program you are about to execute;
--see *Note Executing a File::).
--
-- - Variable: char ** environ
--     The environment is represented as an array of strings.  Each
--     string is of the format `NAME=VALUE'.  The order in which strings
--     appear in the environment is not significant, but the same NAME
--     must not appear more than once.  The last element of the array is
--     a null pointer.
--
--     This variable is declared in the header file `unistd.h'.
--
--     If you just want to get the value of an environment variable, use
--     `getenv'.
--
--   Unix systems, and the GNU system, pass the initial value of
--`environ' as the third argument to `main'.  *Note Program Arguments::.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-23 
glibc-2.0.1/manual/libc.info-23
---- ../glibc-2.0.1/manual/libc.info-23 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-23    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1202 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Standard Environment,  Prev: Environment Access,  Up: 
Environment Variables
--
--Standard Environment Variables
--------------------------------
--
--   These environment variables have standard meanings.  This doesn't
--mean that they are always present in the environment; but if these
--variables *are* present, they have these meanings.  You shouldn't try
--to use these environment variable names for some other purpose.
--
--`HOME'
--     This is a string representing the user's "home directory", or
--     initial default working directory.
--
--     The user can set `HOME' to any value.  If you need to make sure to
--     obtain the proper home directory for a particular user, you should
--     not use `HOME'; instead, look up the user's name in the user
--     database (*note User Database::.).
--
--     For most purposes, it is better to use `HOME', precisely because
--     this lets the user specify the value.
--
--`LOGNAME'
--     This is the name that the user used to log in.  Since the value in
--     the environment can be tweaked arbitrarily, this is not a reliable
--     way to identify the user who is running a process; a function like
--     `getlogin' (*note Who Logged In::.) is better for that purpose.
--
--     For most purposes, it is better to use `LOGNAME', precisely because
--     this lets the user specify the value.
--
--`PATH'
--     A "path" is a sequence of directory names which is used for
--     searching for a file.  The variable `PATH' holds a path used for
--     searching for programs to be run.
--
--     The `execlp' and `execvp' functions (*note Executing a File::.)
--     use this environment variable, as do many shells and other
--     utilities which are implemented in terms of those functions.
--
--     The syntax of a path is a sequence of directory names separated by
--     colons.  An empty string instead of a directory name stands for the
--     current directory (*note Working Directory::.).
--
--     A typical value for this environment variable might be a string
--     like:
--
--          :/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local/bin
--
--     This means that if the user tries to execute a program named `foo',
--     the system will look for files named `foo', `/bin/foo',
--     `/etc/foo', and so on.  The first of these files that exists is
--     the one that is executed.
--
--`TERM'
--     This specifies the kind of terminal that is receiving program
--     output.  Some programs can make use of this information to take
--     advantage of special escape sequences or terminal modes supported
--     by particular kinds of terminals.  Many programs which use the
--     termcap library (*note Find: (termcap)Finding a Terminal
--     Description.) use the `TERM' environment variable, for example.
--
--`TZ'
--     This specifies the time zone.  *Note TZ Variable::, for
--     information about the format of this string and how it is used.
--
--`LANG'
--     This specifies the default locale to use for attribute categories
--     where neither `LC_ALL' nor the specific environment variable for
--     that category is set.  *Note Locales::, for more information about
--     locales.
--
--`LC_COLLATE'
--     This specifies what locale to use for string sorting.
--
--`LC_CTYPE'
--     This specifies what locale to use for character sets and character
--     classification.
--
--`LC_MONETARY'
--     This specifies what locale to use for formatting monetary values.
--
--`LC_NUMERIC'
--     This specifies what locale to use for formatting numbers.
--
--`LC_TIME'
--     This specifies what locale to use for formatting date/time values.
--
--`_POSIX_OPTION_ORDER'
--     If this environment variable is defined, it suppresses the usual
--     reordering of command line arguments by `getopt'.  *Note Argument
--     Syntax::.
--
--
--File: libc.info,  Node: Program Termination,  Prev: Environment Variables,  
Up: Process Startup
--
--Program Termination
--===================
--
--   The usual way for a program to terminate is simply for its `main'
--function to return.  The "exit status value" returned from the `main'
--function is used to report information back to the process's parent
--process or shell.
--
--   A program can also terminate normally by calling the `exit' function.
--
--   In addition, programs can be terminated by signals; this is
--discussed in more detail in *Note Signal Handling::.  The `abort'
--function causes a signal that kills the program.
--
--* Menu:
--
--* Normal Termination::          If a program calls `exit', a
--                                 process terminates normally.
--* Exit Status::                 The `exit status' provides information
--                                 about why the process terminated.
--* Cleanups on Exit::            A process can run its own cleanup
--                                 functions upon normal termination.
--* Aborting a Program::          The `abort' function causes
--                                 abnormal program termination.
--* Termination Internals::       What happens when a process terminates.
--
--
--File: libc.info,  Node: Normal Termination,  Next: Exit Status,  Up: Program 
Termination
--
--Normal Termination
--------------------
--
--   A process terminates normally when the program calls `exit'.
--Returning from `main' is equivalent to calling `exit', and the value
--that `main' returns is used as the argument to `exit'.
--
-- - Function: void exit (int STATUS)
--     The `exit' function terminates the process with status STATUS.
--     This function does not return.
--
--   Normal termination causes the following actions:
--
--  1. Functions that were registered with the `atexit' or `on_exit'
--     functions are called in the reverse order of their registration.
--     This mechanism allows your application to specify its own
--     "cleanup" actions to be performed at program termination.
--     Typically, this is used to do things like saving program state
--     information in a file, or unlocking locks in shared data bases.
--
--  2. All open streams are closed, writing out any buffered output data.
--     See *Note Closing Streams::.  In addition, temporary files opened
--     with the `tmpfile' function are removed; see *Note Temporary
--     Files::.
--
--  3. `_exit' is called, terminating the program.  *Note Termination
--     Internals::.
--
--
--File: libc.info,  Node: Exit Status,  Next: Cleanups on Exit,  Prev: Normal 
Termination,  Up: Program Termination
--
--Exit Status
-------------
--
--   When a program exits, it can return to the parent process a small
--amount of information about the cause of termination, using the "exit
--status".  This is a value between 0 and 255 that the exiting process
--passes as an argument to `exit'.
--
--   Normally you should use the exit status to report very broad
--information about success or failure.  You can't provide a lot of
--detail about the reasons for the failure, and most parent processes
--would not want much detail anyway.
--
--   There are conventions for what sorts of status values certain
--programs should return.  The most common convention is simply 0 for
--success and 1 for failure.  Programs that perform comparison use a
--different convention: they use status 1 to indicate a mismatch, and
--status 2 to indicate an inability to compare.  Your program should
--follow an existing convention if an existing convention makes sense for
--it.
--
--   A general convention reserves status values 128 and up for special
--purposes.  In particular, the value 128 is used to indicate failure to
--execute another program in a subprocess.  This convention is not
--universally obeyed, but it is a good idea to follow it in your programs.
--
--   *Warning:* Don't try to use the number of errors as the exit status.
--This is actually not very useful; a parent process would generally not
--care how many errors occurred.  Worse than that, it does not work,
--because the status value is truncated to eight bits.  Thus, if the
--program tried to report 256 errors, the parent would receive a report
--of 0 errors--that is, success.
--
--   For the same reason, it does not work to use the value of `errno' as
--the exit status--these can exceed 255.
--
--   *Portability note:* Some non-POSIX systems use different conventions
--for exit status values.  For greater portability, you can use the
--macros `EXIT_SUCCESS' and `EXIT_FAILURE' for the conventional status
--value for success and failure, respectively.  They are declared in the
--file `stdlib.h'.
--
-- - Macro: int EXIT_SUCCESS
--     This macro can be used with the `exit' function to indicate
--     successful program completion.
--
--     On POSIX systems, the value of this macro is `0'.  On other
--     systems, the value might be some other (possibly non-constant)
--     integer expression.
--
-- - Macro: int EXIT_FAILURE
--     This macro can be used with the `exit' function to indicate
--     unsuccessful program completion in a general sense.
--
--     On POSIX systems, the value of this macro is `1'.  On other
--     systems, the value might be some other (possibly non-constant)
--     integer expression.  Other nonzero status values also indicate
--     future.  Certain programs use different nonzero status values to
--     indicate particular kinds of "non-success".  For example, `diff'
--     uses status value `1' to mean that the files are different, and
--     `2' or more to mean that there was difficulty in opening the files.
--
--
--File: libc.info,  Node: Cleanups on Exit,  Next: Aborting a Program,  Prev: 
Exit Status,  Up: Program Termination
--
--Cleanups on Exit
------------------
--
--   Your program can arrange to run its own cleanup functions if normal
--termination happens.  If you are writing a library for use in various
--application programs, then it is unreliable to insist that all
--applications call the library's cleanup functions explicitly before
--exiting.  It is much more robust to make the cleanup invisible to the
--application, by setting up a cleanup function in the library itself
--using `atexit' or `on_exit'.
--
-- - Function: int atexit (void (*FUNCTION) (void))
--     The `atexit' function registers the function FUNCTION to be called
--     at normal program termination.  The FUNCTION is called with no
--     arguments.
--
--     The return value from `atexit' is zero on success and nonzero if
--     the function cannot be registered.
--
-- - Function: int on_exit (void (*FUNCTION)(int STATUS, void *ARG), void
--          *ARG)
--     This function is a somewhat more powerful variant of `atexit'.  It
--     accepts two arguments, a function FUNCTION and an arbitrary
--     pointer ARG.  At normal program termination, the FUNCTION is
--     called with two arguments:  the STATUS value passed to `exit', and
--     the ARG.
--
--     This function is included in the GNU C library only for
--     compatibility for SunOS, and may not be supported by other
--     implementations.
--
--   Here's a trivial program that illustrates the use of `exit' and
--`atexit':
--
--     #include <stdio.h>
--     #include <stdlib.h>
--     
--     void
--     bye (void)
--     {
--       puts ("Goodbye, cruel world....");
--     }
--     
--     int
--     main (void)
--     {
--       atexit (bye);
--       exit (EXIT_SUCCESS);
--     }
--
--When this program is executed, it just prints the message and exits.
--
--
--File: libc.info,  Node: Aborting a Program,  Next: Termination Internals,  
Prev: Cleanups on Exit,  Up: Program Termination
--
--Aborting a Program
--------------------
--
--   You can abort your program using the `abort' function.  The prototype
--for this function is in `stdlib.h'.
--
-- - Function: void abort (void)
--     The `abort' function causes abnormal program termination.  This
--     does not execute cleanup functions registered with `atexit' or
--     `on_exit'.
--
--     This function actually terminates the process by raising a
--     `SIGABRT' signal, and your program can include a handler to
--     intercept this signal; see *Note Signal Handling::.
--
--   *Future Change Warning:* Proposed Federal censorship regulations may
--prohibit us from giving you information about the possibility of
--calling this function.  We would be required to say that this is not an
--acceptable way of terminating a program.
--
--
--File: libc.info,  Node: Termination Internals,  Prev: Aborting a Program,  
Up: Program Termination
--
--Termination Internals
-----------------------
--
--   The `_exit' function is the primitive used for process termination
--by `exit'.  It is declared in the header file `unistd.h'.
--
-- - Function: void _exit (int STATUS)
--     The `_exit' function is the primitive for causing a process to
--     terminate with status STATUS.  Calling this function does not
--     execute cleanup functions registered with `atexit' or `on_exit'.
--
--   When a process terminates for any reason--either by an explicit
--termination call, or termination as a result of a signal--the following
--things happen:
--
--   * All open file descriptors in the process are closed.  *Note
--     Low-Level I/O::.  Note that streams are not flushed automatically
--     when the process terminates; *Note I/O on Streams::.
--
--   * The low-order 8 bits of the return status code are saved to be
--     reported back to the parent process via `wait' or `waitpid'; see
--     *Note Process Completion::.
--
--   * Any child processes of the process being terminated are assigned a
--     new parent process.  (On most systems, including GNU, this is the
--     `init' process, with process ID 1.)
--
--   * A `SIGCHLD' signal is sent to the parent process.
--
--   * If the process is a session leader that has a controlling
--     terminal, then a `SIGHUP' signal is sent to each process in the
--     foreground job, and the controlling terminal is disassociated from
--     that session.  *Note Job Control::.
--
--   * If termination of a process causes a process group to become
--     orphaned, and any member of that process group is stopped, then a
--     `SIGHUP' signal and a `SIGCONT' signal are sent to each process in
--     the group.  *Note Job Control::.
--
--
--File: libc.info,  Node: Processes,  Next: Job Control,  Prev: Process 
Startup,  Up: Top
--
--Processes
--*********
--
--   "Processes" are the primitive units for allocation of system
--resources.  Each process has its own address space and (usually) one
--thread of control.  A process executes a program; you can have multiple
--processes executing the same program, but each process has its own copy
--of the program within its own address space and executes it
--independently of the other copies.
--
--   Processes are organized hierarchically.  Each process has a "parent
--process" which explicitly arranged to create it.  The processes created
--by a given parent are called its "child processes".  A child inherits
--many of its attributes from the parent process.
--
--   This chapter describes how a program can create, terminate, and
--control child processes.  Actually, there are three distinct operations
--involved: creating a new child process, causing the new process to
--execute a program, and coordinating the completion of the child process
--with the original program.
--
--   The `system' function provides a simple, portable mechanism for
--running another program; it does all three steps automatically.  If you
--need more control over the details of how this is done, you can use the
--primitive functions to do each step individually instead.
--
--* Menu:
--
--* Running a Command::           The easy way to run another program.
--* Process Creation Concepts::   An overview of the hard way to do it.
--* Process Identification::      How to get the process ID of a process.
--* Creating a Process::          How to fork a child process.
--* Executing a File::            How to make a process execute another program.
--* Process Completion::          How to tell when a child process has 
completed.
--* Process Completion Status::   How to interpret the status value
--                                 returned from a child process.
--* BSD Wait Functions::        More functions, for backward compatibility.
--* Process Creation Example::    A complete example program.
--
--
--File: libc.info,  Node: Running a Command,  Next: Process Creation Concepts,  
Up: Processes
--
--Running a Command
--=================
--
--   The easy way to run another program is to use the `system' function.
--This function does all the work of running a subprogram, but it
--doesn't give you much control over the details: you have to wait until
--the subprogram terminates before you can do anything else.
--
-- - Function: int system (const char *COMMAND)
--     This function executes COMMAND as a shell command.  In the GNU C
--     library, it always uses the default shell `sh' to run the command.
--     In particular, it searches the directories in `PATH' to find
--     programs to execute.  The return value is `-1' if it wasn't
--     possible to create the shell process, and otherwise is the status
--     of the shell process.  *Note Process Completion::, for details on
--     how this status code can be interpreted.
--
--     The `system' function is declared in the header file `stdlib.h'.
--
--   *Portability Note:* Some C implementations may not have any notion
--of a command processor that can execute other programs.  You can
--determine whether a command processor exists by executing
--`system (NULL)'; if the return value is nonzero, a command processor is
--available.
--
--   The `popen' and `pclose' functions (*note Pipe to a Subprocess::.)
--are closely related to the `system' function.  They allow the parent
--process to communicate with the standard input and output channels of
--the command being executed.
--
--
--File: libc.info,  Node: Process Creation Concepts,  Next: Process 
Identification,  Prev: Running a Command,  Up: Processes
--
--Process Creation Concepts
--=========================
--
--   This section gives an overview of processes and of the steps
--involved in creating a process and making it run another program.
--
--   Each process is named by a "process ID" number.  A unique process ID
--is allocated to each process when it is created.  The "lifetime" of a
--process ends when its termination is reported to its parent process; at
--that time, all of the process resources, including its process ID, are
--freed.
--
--   Processes are created with the `fork' system call (so the operation
--of creating a new process is sometimes called "forking" a process).
--The "child process" created by `fork' is a copy of the original "parent
--process", except that it has its own process ID.
--
--   After forking a child process, both the parent and child processes
--continue to execute normally.  If you want your program to wait for a
--child process to finish executing before continuing, you must do this
--explicitly after the fork operation, by calling `wait' or `waitpid'
--(*note Process Completion::.).  These functions give you limited
--information about why the child terminated--for example, its exit
--status code.
--
--   A newly forked child process continues to execute the same program as
--its parent process, at the point where the `fork' call returns.  You
--can use the return value from `fork' to tell whether the program is
--running in the parent process or the child.
--
--   Having several processes run the same program is only occasionally
--useful.  But the child can execute another program using one of the
--`exec' functions; see *Note Executing a File::.  The program that the
--process is executing is called its "process image".  Starting execution
--of a new program causes the process to forget all about its previous
--process image; when the new program exits, the process exits too,
--instead of returning to the previous process image.
--
--
--File: libc.info,  Node: Process Identification,  Next: Creating a Process,  
Prev: Process Creation Concepts,  Up: Processes
--
--Process Identification
--======================
--
--   The `pid_t' data type represents process IDs.  You can get the
--process ID of a process by calling `getpid'.  The function `getppid'
--returns the process ID of the parent of the current process (this is
--also known as the "parent process ID").  Your program should include
--the header files `unistd.h' and `sys/types.h' to use these functions.
--
-- - Data Type: pid_t
--     The `pid_t' data type is a signed integer type which is capable of
--     representing a process ID.  In the GNU library, this is an `int'.
--
-- - Function: pid_t getpid (void)
--     The `getpid' function returns the process ID of the current
--     process.
--
-- - Function: pid_t getppid (void)
--     The `getppid' function returns the process ID of the parent of the
--     current process.
--
--
--File: libc.info,  Node: Creating a Process,  Next: Executing a File,  Prev: 
Process Identification,  Up: Processes
--
--Creating a Process
--==================
--
--   The `fork' function is the primitive for creating a process.  It is
--declared in the header file `unistd.h'.
--
-- - Function: pid_t fork (void)
--     The `fork' function creates a new process.
--
--     If the operation is successful, there are then both parent and
--     child processes and both see `fork' return, but with different
--     values: it returns a value of `0' in the child process and returns
--     the child's process ID in the parent process.
--
--     If process creation failed, `fork' returns a value of `-1' in the
--     parent process.  The following `errno' error conditions are
--     defined for `fork':
--
--    `EAGAIN'
--          There aren't enough system resources to create another
--          process, or the user already has too many processes running.
--          This means exceeding the `RLIMIT_NPROC' resource limit, which
--          can usually be increased; *note Limits on Resources::..
--
--    `ENOMEM'
--          The process requires more space than the system can supply.
--
--   The specific attributes of the child process that differ from the
--parent process are:
--
--   * The child process has its own unique process ID.
--
--   * The parent process ID of the child process is the process ID of its
--     parent process.
--
--   * The child process gets its own copies of the parent process's open
--     file descriptors.  Subsequently changing attributes of the file
--     descriptors in the parent process won't affect the file
--     descriptors in the child, and vice versa.  *Note Control
--     Operations::.  However, the file position associated with each
--     descriptor is shared by both processes; *note File Position::..
--
--   * The elapsed processor times for the child process are set to zero;
--     see *Note Processor Time::.
--
--   * The child doesn't inherit file locks set by the parent process.
--     *Note Control Operations::.
--
--   * The child doesn't inherit alarms set by the parent process.  *Note
--     Setting an Alarm::.
--
--   * The set of pending signals (*note Delivery of Signal::.) for the
--     child process is cleared.  (The child process inherits its mask of
--     blocked signals and signal actions from the parent process.)
--
-- - Function: pid_t vfork (void)
--     The `vfork' function is similar to `fork' but on systems it is
--     more efficient; however, there are restrictions you must follow to
--     use it safely.
--
--     While `fork' makes a complete copy of the calling process's
--     address space and allows both the parent and child to execute
--     independently, `vfork' does not make this copy.  Instead, the
--     child process created with `vfork' shares its parent's address
--     space until it calls exits or one of the `exec' functions.  In the
--     meantime, the parent process suspends execution.
--
--     You must be very careful not to allow the child process created
--     with `vfork' to modify any global data or even local variables
--     shared with the parent.  Furthermore, the child process cannot
--     return from (or do a long jump out of) the function that called
--     `vfork'!  This would leave the parent process's control
--     information very confused.  If in doubt, use `fork' instead.
--
--     Some operating systems don't really implement `vfork'.  The GNU C
--     library permits you to use `vfork' on all systems, but actually
--     executes `fork' if `vfork' isn't available.  If you follow the
--     proper precautions for using `vfork', your program will still work
--     even if the system uses `fork' instead.
--
--
--File: libc.info,  Node: Executing a File,  Next: Process Completion,  Prev: 
Creating a Process,  Up: Processes
--
--Executing a File
--================
--
--   This section describes the `exec' family of functions, for executing
--a file as a process image.  You can use these functions to make a child
--process execute a new program after it has been forked.
--
--   The functions in this family differ in how you specify the arguments,
--but otherwise they all do the same thing.  They are declared in the
--header file `unistd.h'.
--
-- - Function: int execv (const char *FILENAME, char *const ARGV[])
--     The `execv' function executes the file named by FILENAME as a new
--     process image.
--
--     The ARGV argument is an array of null-terminated strings that is
--     used to provide a value for the `argv' argument to the `main'
--     function of the program to be executed.  The last element of this
--     array must be a null pointer.  By convention, the first element of
--     this array is the file name of the program sans directory names.
--     *Note Program Arguments::, for full details on how programs can
--     access these arguments.
--
--     The environment for the new process image is taken from the
--     `environ' variable of the current process image; see *Note
--     Environment Variables::, for information about environments.
--
-- - Function: int execl (const char *FILENAME, const char *ARG0, ...)
--     This is similar to `execv', but the ARGV strings are specified
--     individually instead of as an array.  A null pointer must be
--     passed as the last such argument.
--
-- - Function: int execve (const char *FILENAME, char *const ARGV[], char
--          *const ENV[])
--     This is similar to `execv', but permits you to specify the
--     environment for the new program explicitly as the ENV argument.
--     This should be an array of strings in the same format as for the
--     `environ' variable; see *Note Environment Access::.
--
-- - Function: int execle (const char *FILENAME, const char *ARG0, char
--          *const ENV[], ...)
--     This is similar to `execl', but permits you to specify the
--     environment for the new program explicitly.  The environment
--     argument is passed following the null pointer that marks the last
--     ARGV argument, and should be an array of strings in the same
--     format as for the `environ' variable.
--
-- - Function: int execvp (const char *FILENAME, char *const ARGV[])
--     The `execvp' function is similar to `execv', except that it
--     searches the directories listed in the `PATH' environment variable
--     (*note Standard Environment::.) to find the full file name of a
--     file from FILENAME if FILENAME does not contain a slash.
--
--     This function is useful for executing system utility programs,
--     because it looks for them in the places that the user has chosen.
--     Shells use it to run the commands that users type.
--
-- - Function: int execlp (const char *FILENAME, const char *ARG0, ...)
--     This function is like `execl', except that it performs the same
--     file name searching as the `execvp' function.
--
--   The size of the argument list and environment list taken together
--must not be greater than `ARG_MAX' bytes.  *Note General Limits::.  In
--the GNU system, the size (which compares against `ARG_MAX') includes,
--for each string, the number of characters in the string, plus the size
--of a `char *', plus one, rounded up to a multiple of the size of a
--`char *'.  Other systems may have somewhat different rules for counting.
--
--   These functions normally don't return, since execution of a new
--program causes the currently executing program to go away completely.
--A value of `-1' is returned in the event of a failure.  In addition to
--the usual file name errors (*note File Name Errors::.), the following
--`errno' error conditions are defined for these functions:
--
--`E2BIG'
--     The combined size of the new program's argument list and
--     environment list is larger than `ARG_MAX' bytes.  The GNU system
--     has no specific limit on the argument list size, so this error
--     code cannot result, but you may get `ENOMEM' instead if the
--     arguments are too big for available memory.
--
--`ENOEXEC'
--     The specified file can't be executed because it isn't in the right
--     format.
--
--`ENOMEM'
--     Executing the specified file requires more storage than is
--     available.
--
--   If execution of the new file succeeds, it updates the access time
--field of the file as if the file had been read.  *Note File Times::,
--for more details about access times of files.
--
--   The point at which the file is closed again is not specified, but is
--at some point before the process exits or before another process image
--is executed.
--
--   Executing a new process image completely changes the contents of
--memory, copying only the argument and environment strings to new
--locations.  But many other attributes of the process are unchanged:
--
--   * The process ID and the parent process ID.  *Note Process Creation
--     Concepts::.
--
--   * Session and process group membership.  *Note Concepts of Job
--     Control::.
--
--   * Real user ID and group ID, and supplementary group IDs.  *Note
--     Process Persona::.
--
--   * Pending alarms.  *Note Setting an Alarm::.
--
--   * Current working directory and root directory.  *Note Working
--     Directory::.  In the GNU system, the root directory is not copied
--     when executing a setuid program; instead the system default root
--     directory is used for the new program.
--
--   * File mode creation mask.  *Note Setting Permissions::.
--
--   * Process signal mask; see *Note Process Signal Mask::.
--
--   * Pending signals; see *Note Blocking Signals::.
--
--   * Elapsed processor time associated with the process; see *Note
--     Processor Time::.
--
--   If the set-user-ID and set-group-ID mode bits of the process image
--file are set, this affects the effective user ID and effective group ID
--(respectively) of the process.  These concepts are discussed in detail
--in *Note Process Persona::.
--
--   Signals that are set to be ignored in the existing process image are
--also set to be ignored in the new process image.  All other signals are
--set to the default action in the new process image.  For more
--information about signals, see *Note Signal Handling::.
--
--   File descriptors open in the existing process image remain open in
--the new process image, unless they have the `FD_CLOEXEC'
--(close-on-exec) flag set.  The files that remain open inherit all
--attributes of the open file description from the existing process image,
--including file locks.  File descriptors are discussed in *Note
--Low-Level I/O::.
--
--   Streams, by contrast, cannot survive through `exec' functions,
--because they are located in the memory of the process itself.  The new
--process image has no streams except those it creates afresh.  Each of
--the streams in the pre-`exec' process image has a descriptor inside it,
--and these descriptors do survive through `exec' (provided that they do
--not have `FD_CLOEXEC' set).  The new process image can reconnect these
--to new streams using `fdopen' (*note Descriptors and Streams::.).
--
--
--File: libc.info,  Node: Process Completion,  Next: Process Completion Status, 
 Prev: Executing a File,  Up: Processes
--
--Process Completion
--==================
--
--   The functions described in this section are used to wait for a child
--process to terminate or stop, and determine its status.  These functions
--are declared in the header file `sys/wait.h'.
--
-- - Function: pid_t waitpid (pid_t PID, int *STATUS-PTR, int OPTIONS)
--     The `waitpid' function is used to request status information from a
--     child process whose process ID is PID.  Normally, the calling
--     process is suspended until the child process makes status
--     information available by terminating.
--
--     Other values for the PID argument have special interpretations.  A
--     value of `-1' or `WAIT_ANY' requests status information for any
--     child process; a value of `0' or `WAIT_MYPGRP' requests
--     information for any child process in the same process group as the
--     calling process; and any other negative value - PGID requests
--     information for any child process whose process group ID is PGID.
--
--     If status information for a child process is available
--     immediately, this function returns immediately without waiting.
--     If more than one eligible child process has status information
--     available, one of them is chosen randomly, and its status is
--     returned immediately.  To get the status from the other eligible
--     child processes, you need to call `waitpid' again.
--
--     The OPTIONS argument is a bit mask.  Its value should be the
--     bitwise OR (that is, the `|' operator) of zero or more of the
--     `WNOHANG' and `WUNTRACED' flags.  You can use the `WNOHANG' flag
--     to indicate that the parent process shouldn't wait; and the
--     `WUNTRACED' flag to request status information from stopped
--     processes as well as processes that have terminated.
--
--     The status information from the child process is stored in the
--     object that STATUS-PTR points to, unless STATUS-PTR is a null
--     pointer.
--
--     The return value is normally the process ID of the child process
--     whose status is reported.  If the `WNOHANG' option was specified
--     and no child process is waiting to be noticed, the value is zero.
--     A value of `-1' is returned in case of error.  The following
--     `errno' error conditions are defined for this function:
--
--    `EINTR'
--          The function was interrupted by delivery of a signal to the
--          calling process.  *Note Interrupted Primitives::.
--
--    `ECHILD'
--          There are no child processes to wait for, or the specified PID
--          is not a child of the calling process.
--
--    `EINVAL'
--          An invalid value was provided for the OPTIONS argument.
--
--   These symbolic constants are defined as values for the PID argument
--to the `waitpid' function.
--
--`WAIT_ANY'
--     This constant macro (whose value is `-1') specifies that `waitpid'
--     should return status information about any child process.
--
--`WAIT_MYPGRP'
--     This constant (with value `0') specifies that `waitpid' should
--     return status information about any child process in the same
--     process group as the calling process.
--
--   These symbolic constants are defined as flags for the OPTIONS
--argument to the `waitpid' function.  You can bitwise-OR the flags
--together to obtain a value to use as the argument.
--
--`WNOHANG'
--     This flag specifies that `waitpid' should return immediately
--     instead of waiting, if there is no child process ready to be
--     noticed.
--
--`WUNTRACED'
--     This flag specifies that `waitpid' should report the status of any
--     child processes that have been stopped as well as those that have
--     terminated.
--
-- - Function: pid_t wait (int *STATUS-PTR)
--     This is a simplified version of `waitpid', and is used to wait
--     until any one child process terminates.  The call:
--
--          wait (&status)
--
--     is exactly equivalent to:
--
--          waitpid (-1, &status, 0)
--
-- - Function: pid_t wait4 (pid_t PID, int *STATUS-PTR, int OPTIONS,
--          struct rusage *USAGE)
--     If USAGE is a null pointer, `wait4' is equivalent to `waitpid
--     (PID, STATUS-PTR, OPTIONS)'.
--
--     If USAGE is not null, `wait4' stores usage figures for the child
--     process in `*RUSAGE' (but only if the child has terminated, not if
--     it has stopped).  *Note Resource Usage::.
--
--     This function is a BSD extension.
--
--   Here's an example of how to use `waitpid' to get the status from all
--child processes that have terminated, without ever waiting.  This
--function is designed to be a handler for `SIGCHLD', the signal that
--indicates that at least one child process has terminated.
--
--     void
--     sigchld_handler (int signum)
--     {
--       int pid;
--       int status;
--       while (1)
--         {
--           pid = waitpid (WAIT_ANY, &status, WNOHANG);
--           if (pid < 0)
--             {
--               perror ("waitpid");
--               break;
--             }
--           if (pid == 0)
--             break;
--           notice_termination (pid, status);
--         }
--     }
--
--
--File: libc.info,  Node: Process Completion Status,  Next: BSD Wait Functions, 
 Prev: Process Completion,  Up: Processes
--
--Process Completion Status
--=========================
--
--   If the exit status value (*note Program Termination::.) of the child
--process is zero, then the status value reported by `waitpid' or `wait'
--is also zero.  You can test for other kinds of information encoded in
--the returned status value using the following macros.  These macros are
--defined in the header file `sys/wait.h'.
--
-- - Macro: int WIFEXITED (int STATUS)
--     This macro returns a nonzero value if the child process terminated
--     normally with `exit' or `_exit'.
--
-- - Macro: int WEXITSTATUS (int STATUS)
--     If `WIFEXITED' is true of STATUS, this macro returns the low-order
--     8 bits of the exit status value from the child process.  *Note
--     Exit Status::.
--
-- - Macro: int WIFSIGNALED (int STATUS)
--     This macro returns a nonzero value if the child process terminated
--     because it received a signal that was not handled.  *Note Signal
--     Handling::.
--
-- - Macro: int WTERMSIG (int STATUS)
--     If `WIFSIGNALED' is true of STATUS, this macro returns the signal
--     number of the signal that terminated the child process.
--
-- - Macro: int WCOREDUMP (int STATUS)
--     This macro returns a nonzero value if the child process terminated
--     and produced a core dump.
--
-- - Macro: int WIFSTOPPED (int STATUS)
--     This macro returns a nonzero value if the child process is stopped.
--
-- - Macro: int WSTOPSIG (int STATUS)
--     If `WIFSTOPPED' is true of STATUS, this macro returns the signal
--     number of the signal that caused the child process to stop.
--
--
--File: libc.info,  Node: BSD Wait Functions,  Next: Process Creation Example,  
Prev: Process Completion Status,  Up: Processes
--
--BSD Process Wait Functions
--==========================
--
--   The GNU library also provides these related facilities for
--compatibility with BSD Unix.  BSD uses the `union wait' data type to
--represent status values rather than an `int'.  The two representations
--are actually interchangeable; they describe the same bit patterns.  The
--GNU C Library defines macros such as `WEXITSTATUS' so that they will
--work on either kind of object, and the `wait' function is defined to
--accept either type of pointer as its STATUS-PTR argument.
--
--   These functions are declared in `sys/wait.h'.
--
-- - Data Type: union wait
--     This data type represents program termination status values.  It
--     has the following members:
--
--    `int w_termsig'
--          The value of this member is the same as the result of the
--          `WTERMSIG' macro.
--
--    `int w_coredump'
--          The value of this member is the same as the result of the
--          `WCOREDUMP' macro.
--
--    `int w_retcode'
--          The value of this member is the same as the result of the
--          `WEXITSTATUS' macro.
--
--    `int w_stopsig'
--          The value of this member is the same as the result of the
--          `WSTOPSIG' macro.
--
--     Instead of accessing these members directly, you should use the
--     equivalent macros.
--
--   The `wait3' function is the predecessor to `wait4', which is more
--flexible.  `wait3' is now obsolete.
--
-- - Function: pid_t wait3 (union wait *STATUS-PTR, int OPTIONS, struct
--          rusage *USAGE)
--     If USAGE is a null pointer, `wait3' is equivalent to `waitpid (-1,
--     STATUS-PTR, OPTIONS)'.
--
--     If USAGE is not null, `wait3' stores usage figures for the child
--     process in `*RUSAGE' (but only if the child has terminated, not if
--     it has stopped).  *Note Resource Usage::.
--
--
--File: libc.info,  Node: Process Creation Example,  Prev: BSD Wait Functions,  
Up: Processes
--
--Process Creation Example
--========================
--
--   Here is an example program showing how you might write a function
--similar to the built-in `system'.  It executes its COMMAND argument
--using the equivalent of `sh -c COMMAND'.
--
--     #include <stddef.h>
--     #include <stdlib.h>
--     #include <unistd.h>
--     #include <sys/types.h>
--     #include <sys/wait.h>
--     
--     /* Execute the command using this shell program.  */
--     #define SHELL "/bin/sh"
--     int
--     my_system (const char *command)
--     {
--       int status;
--       pid_t pid;
--     
--       pid = fork ();
--       if (pid == 0)
--         {
--           /* This is the child process.  Execute the shell command. */
--           execl (SHELL, SHELL, "-c", command, NULL);
--           _exit (EXIT_FAILURE);
--         }
--       else if (pid < 0)
--         /* The fork failed.  Report failure.  */
--         status = -1;
--       else
--         /* This is the parent process.  Wait for the child to complete.  */
--         if (waitpid (pid, &status, 0) != pid)
--           status = -1;
--       return status;
--     }
--
--   There are a couple of things you should pay attention to in this
--example.
--
--   Remember that the first `argv' argument supplied to the program
--represents the name of the program being executed.  That is why, in the
--call to `execl', `SHELL' is supplied once to name the program to
--execute and a second time to supply a value for `argv[0]'.
--
--   The `execl' call in the child process doesn't return if it is
--successful.  If it fails, you must do something to make the child
--process terminate.  Just returning a bad status code with `return'
--would leave two processes running the original program.  Instead, the
--right behavior is for the child process to report failure to its parent
--process.
--
--   Call `_exit' to accomplish this.  The reason for using `_exit'
--instead of `exit' is to avoid flushing fully buffered streams such as
--`stdout'.  The buffers of these streams probably contain data that was
--copied from the parent process by the `fork', data that will be output
--eventually by the parent process.  Calling `exit' in the child would
--output the data twice.  *Note Termination Internals::.
--
--
--File: libc.info,  Node: Job Control,  Next: Name Service Switch,  Prev: 
Processes,  Up: Top
--
--Job Control
--***********
--
--   "Job control" refers to the protocol for allowing a user to move
--between multiple "process groups" (or "jobs") within a single "login
--session".  The job control facilities are set up so that appropriate
--behavior for most programs happens automatically and they need not do
--anything special about job control.  So you can probably ignore the
--material in this chapter unless you are writing a shell or login
--program.
--
--   You need to be familiar with concepts relating to process creation
--(*note Process Creation Concepts::.) and signal handling (*note Signal
--Handling::.) in order to understand this material presented in this
--chapter.
--
--* Menu:
--
--* Concepts of Job Control::     Jobs can be controlled by a shell.
--* Job Control is Optional::     Not all POSIX systems support job control.
--* Controlling Terminal::        How a process gets its controlling terminal.
--* Access to the Terminal::      How processes share the controlling terminal.
--* Orphaned Process Groups::     Jobs left after the user logs out.
--* Implementing a Shell::        What a shell must do to implement job control.
--* Functions for Job Control::   Functions to control process groups.
--
--
--File: libc.info,  Node: Concepts of Job Control,  Next: Job Control is 
Optional,  Up: Job Control
--
--Concepts of Job Control
--=======================
--
--   The fundamental purpose of an interactive shell is to read commands
--from the user's terminal and create processes to execute the programs
--specified by those commands.  It can do this using the `fork' (*note
--Creating a Process::.) and `exec' (*note Executing a File::.) functions.
--
--   A single command may run just one process--but often one command uses
--several processes.  If you use the `|' operator in a shell command, you
--explicitly request several programs in their own processes.  But even
--if you run just one program, it can use multiple processes internally.
--For example, a single compilation command such as `cc -c foo.c'
--typically uses four processes (though normally only two at any given
--time).  If you run `make', its job is to run other programs in separate
--processes.
--
--   The processes belonging to a single command are called a "process
--group" or "job".  This is so that you can operate on all of them at
--once.  For example, typing `C-c' sends the signal `SIGINT' to terminate
--all the processes in the foreground process group.
--
--   A "session" is a larger group of processes.  Normally all the
--processes that stem from a single login belong to the same session.
--
--   Every process belongs to a process group.  When a process is
--created, it becomes a member of the same process group and session as
--its parent process.  You can put it in another process group using the
--`setpgid' function, provided the process group belongs to the same
--session.
--
--   The only way to put a process in a different session is to make it
--the initial process of a new session, or a "session leader", using the
--`setsid' function.  This also puts the session leader into a new
--process group, and you can't move it out of that process group again.
--
--   Usually, new sessions are created by the system login program, and
--the session leader is the process running the user's login shell.
--
--   A shell that supports job control must arrange to control which job
--can use the terminal at any time.  Otherwise there might be multiple
--jobs trying to read from the terminal at once, and confusion about which
--process should receive the input typed by the user.  To prevent this,
--the shell must cooperate with the terminal driver using the protocol
--described in this chapter.
--
--   The shell can give unlimited access to the controlling terminal to
--only one process group at a time.  This is called the "foreground job"
--on that controlling terminal.  Other process groups managed by the shell
--that are executing without such access to the terminal are called
--"background jobs".
--
--   If a background job needs to read from its controlling terminal, it
--is "stopped" by the terminal driver; if the `TOSTOP' mode is set,
--likewise for writing.  The user can stop a foreground job by typing the
--SUSP character (*note Special Characters::.) and a program can stop any
--job by sending it a `SIGSTOP' signal.  It's the responsibility of the
--shell to notice when jobs stop, to notify the user about them, and to
--provide mechanisms for allowing the user to interactively continue
--stopped jobs and switch jobs between foreground and background.
--
--   *Note Access to the Terminal::, for more information about I/O to the
--controlling terminal,
--
--
--File: libc.info,  Node: Job Control is Optional,  Next: Controlling Terminal, 
 Prev: Concepts of Job Control,  Up: Job Control
--
--Job Control is Optional
--=======================
--
--   Not all operating systems support job control.  The GNU system does
--support job control, but if you are using the GNU library on some other
--system, that system may not support job control itself.
--
--   You can use the `_POSIX_JOB_CONTROL' macro to test at compile-time
--whether the system supports job control.  *Note System Options::.
--
--   If job control is not supported, then there can be only one process
--group per session, which behaves as if it were always in the foreground.
--The functions for creating additional process groups simply fail with
--the error code `ENOSYS'.
--
--   The macros naming the various job control signals (*note Job Control
--Signals::.) are defined even if job control is not supported.  However,
--the system never generates these signals, and attempts to send a job
--control signal or examine or specify their actions report errors or do
--nothing.
--
--
--File: libc.info,  Node: Controlling Terminal,  Next: Access to the Terminal,  
Prev: Job Control is Optional,  Up: Job Control
--
--Controlling Terminal of a Process
--=================================
--
--   One of the attributes of a process is its controlling terminal.
--Child processes created with `fork' inherit the controlling terminal
--from their parent process.  In this way, all the processes in a session
--inherit the controlling terminal from the session leader.  A session
--leader that has control of a terminal is called the "controlling
--process" of that terminal.
--
--   You generally do not need to worry about the exact mechanism used to
--allocate a controlling terminal to a session, since it is done for you
--by the system when you log in.
--
--   An individual process disconnects from its controlling terminal when
--it calls `setsid' to become the leader of a new session.  *Note Process
--Group Functions::.
--
--
--File: libc.info,  Node: Access to the Terminal,  Next: Orphaned Process 
Groups,  Prev: Controlling Terminal,  Up: Job Control
--
--Access to the Controlling Terminal
--==================================
--
--   Processes in the foreground job of a controlling terminal have
--unrestricted access to that terminal; background processes do not.  This
--section describes in more detail what happens when a process in a
--background job tries to access its controlling terminal.
--
--   When a process in a background job tries to read from its controlling
--terminal, the process group is usually sent a `SIGTTIN' signal.  This
--normally causes all of the processes in that group to stop (unless they
--handle the signal and don't stop themselves).  However, if the reading
--process is ignoring or blocking this signal, then `read' fails with an
--`EIO' error instead.
--
--   Similarly, when a process in a background job tries to write to its
--controlling terminal, the default behavior is to send a `SIGTTOU'
--signal to the process group.  However, the behavior is modified by the
--`TOSTOP' bit of the local modes flags (*note Local Modes::.).  If this
--bit is not set (which is the default), then writing to the controlling
--terminal is always permitted without sending a signal.  Writing is also
--permitted if the `SIGTTOU' signal is being ignored or blocked by the
--writing process.
--
--   Most other terminal operations that a program can do are treated as
--reading or as writing.  (The description of each operation should say
--which.)
--
--   For more information about the primitive `read' and `write'
--functions, see *Note I/O Primitives::.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-24 
glibc-2.0.1/manual/libc.info-24
---- ../glibc-2.0.1/manual/libc.info-24 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-24    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1332 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Orphaned Process Groups,  Next: Implementing a Shell, 
 Prev: Access to the Terminal,  Up: Job Control
--
--Orphaned Process Groups
--=======================
--
--   When a controlling process terminates, its terminal becomes free and
--a new session can be established on it.  (In fact, another user could
--log in on the terminal.)  This could cause a problem if any processes
--from the old session are still trying to use that terminal.
--
--   To prevent problems, process groups that continue running even after
--the session leader has terminated are marked as "orphaned process
--groups".
--
--   When a process group becomes an orphan, its processes are sent a
--`SIGHUP' signal.  Ordinarily, this causes the processes to terminate.
--However, if a program ignores this signal or establishes a handler for
--it (*note Signal Handling::.), it can continue running as in the orphan
--process group even after its controlling process terminates; but it
--still cannot access the terminal any more.
--
--
--File: libc.info,  Node: Implementing a Shell,  Next: Functions for Job 
Control,  Prev: Orphaned Process Groups,  Up: Job Control
--
--Implementing a Job Control Shell
--================================
--
--   This section describes what a shell must do to implement job
--control, by presenting an extensive sample program to illustrate the
--concepts involved.
--
--* Menu:
--
--* Data Structures::             Introduction to the sample shell.
--* Initializing the Shell::      What the shell must do to take
--                               responsibility for job control.
--* Launching Jobs::              Creating jobs to execute commands.
--* Foreground and Background::   Putting a job in foreground of background.
--* Stopped and Terminated Jobs::  Reporting job status.
--* Continuing Stopped Jobs::     How to continue a stopped job in
--                               the foreground or background.
--* Missing Pieces::              Other parts of the shell.
--
--
--File: libc.info,  Node: Data Structures,  Next: Initializing the Shell,  Up: 
Implementing a Shell
--
--Data Structures for the Shell
-------------------------------
--
--   All of the program examples included in this chapter are part of a
--simple shell program.  This section presents data structures and
--utility functions which are used throughout the example.
--
--   The sample shell deals mainly with two data structures.  The `job'
--type contains information about a job, which is a set of subprocesses
--linked together with pipes.  The `process' type holds information about
--a single subprocess.  Here are the relevant data structure declarations:
--
--     /* A process is a single process.  */
--     typedef struct process
--     {
--       struct process *next;       /* next process in pipeline */
--       char **argv;                /* for exec */
--       pid_t pid;                  /* process ID */
--       char completed;             /* true if process has completed */
--       char stopped;               /* true if process has stopped */
--       int status;                 /* reported status value */
--     } process;
--
--     /* A job is a pipeline of processes.  */
--     typedef struct job
--     {
--       struct job *next;           /* next active job */
--       char *command;              /* command line, used for messages */
--       process *first_process;     /* list of processes in this job */
--       pid_t pgid;                 /* process group ID */
--       char notified;              /* true if user told about stopped job */
--       struct termios tmodes;      /* saved terminal modes */
--       int stdin, stdout, stderr;  /* standard i/o channels */
--     } job;
--     
--     /* The active jobs are linked into a list.  This is its head.   */
--     job *first_job = NULL;
--
--   Here are some utility functions that are used for operating on `job'
--objects.
--
--     /* Find the active job with the indicated PGID.  */
--     job *
--     find_job (pid_t pgid)
--     {
--       job *j;
--     
--       for (j = first_job; j; j = j->next)
--         if (j->pgid == pgid)
--           return j;
--       return NULL;
--     }
--
--     /* Return true if all processes in the job have stopped or completed.  */
--     int
--     job_is_stopped (job *j)
--     {
--       process *p;
--     
--       for (p = j->first_process; p; p = p->next)
--         if (!p->completed && !p->stopped)
--           return 0;
--       return 1;
--     }
--
--     /* Return true if all processes in the job have completed.  */
--     int
--     job_is_completed (job *j)
--     {
--       process *p;
--     
--       for (p = j->first_process; p; p = p->next)
--         if (!p->completed)
--           return 0;
--       return 1;
--     }
--
--
--File: libc.info,  Node: Initializing the Shell,  Next: Launching Jobs,  Prev: 
Data Structures,  Up: Implementing a Shell
--
--Initializing the Shell
------------------------
--
--   When a shell program that normally performs job control is started,
--it has to be careful in case it has been invoked from another shell
--that is already doing its own job control.
--
--   A subshell that runs interactively has to ensure that it has been
--placed in the foreground by its parent shell before it can enable job
--control itself.  It does this by getting its initial process group ID
--with the `getpgrp' function, and comparing it to the process group ID
--of the current foreground job associated with its controlling terminal
--(which can be retrieved using the `tcgetpgrp' function).
--
--   If the subshell is not running as a foreground job, it must stop
--itself by sending a `SIGTTIN' signal to its own process group.  It may
--not arbitrarily put itself into the foreground; it must wait for the
--user to tell the parent shell to do this.  If the subshell is continued
--again, it should repeat the check and stop itself again if it is still
--not in the foreground.
--
--   Once the subshell has been placed into the foreground by its parent
--shell, it can enable its own job control.  It does this by calling
--`setpgid' to put itself into its own process group, and then calling
--`tcsetpgrp' to place this process group into the foreground.
--
--   When a shell enables job control, it should set itself to ignore all
--the job control stop signals so that it doesn't accidentally stop
--itself.  You can do this by setting the action for all the stop signals
--to `SIG_IGN'.
--
--   A subshell that runs non-interactively cannot and should not support
--job control.  It must leave all processes it creates in the same process
--group as the shell itself; this allows the non-interactive shell and its
--child processes to be treated as a single job by the parent shell.  This
--is easy to do--just don't use any of the job control primitives--but
--you must remember to make the shell do it.
--
--   Here is the initialization code for the sample shell that shows how
--to do all of this.
--
--     /* Keep track of attributes of the shell.  */
--     
--     #include <sys/types.h>
--     #include <termios.h>
--     #include <unistd.h>
--     
--     pid_t shell_pgid;
--     struct termios shell_tmodes;
--     int shell_terminal;
--     int shell_is_interactive;
--     
--     
--     /* Make sure the shell is running interactively as the foreground job
--        before proceeding. */
--     
--     void
--     init_shell ()
--     {
--     
--       /* See if we are running interactively.  */
--       shell_terminal = STDIN_FILENO;
--       shell_is_interactive = isatty (shell_terminal);
--     
--       if (shell_is_interactive)
--         {
--           /* Loop until we are in the foreground.  */
--           while (tcgetpgrp (shell_terminal) != (shell_pgid = getpgrp ()))
--             kill (- shell_pgid, SIGTTIN);
--     
--           /* Ignore interactive and job-control signals.  */
--           signal (SIGINT, SIG_IGN);
--           signal (SIGQUIT, SIG_IGN);
--           signal (SIGTSTP, SIG_IGN);
--           signal (SIGTTIN, SIG_IGN);
--           signal (SIGTTOU, SIG_IGN);
--           signal (SIGCHLD, SIG_IGN);
--     
--           /* Put ourselves in our own process group.  */
--           shell_pgid = getpid ();
--           if (setpgid (shell_pgid, shell_pgid) < 0)
--             {
--               perror ("Couldn't put the shell in its own process group");
--               exit (1);
--             }
--     
--           /* Grab control of the terminal.  */
--           tcsetpgrp (shell_terminal, shell_pgid);
--     
--           /* Save default terminal attributes for shell.  */
--           tcgetattr (shell_terminal, &shell_tmodes);
--         }
--     }
--
--
--File: libc.info,  Node: Launching Jobs,  Next: Foreground and Background,  
Prev: Initializing the Shell,  Up: Implementing a Shell
--
--Launching Jobs
----------------
--
--   Once the shell has taken responsibility for performing job control on
--its controlling terminal, it can launch jobs in response to commands
--typed by the user.
--
--   To create the processes in a process group, you use the same `fork'
--and `exec' functions described in *Note Process Creation Concepts::.
--Since there are multiple child processes involved, though, things are a
--little more complicated and you must be careful to do things in the
--right order.  Otherwise, nasty race conditions can result.
--
--   You have two choices for how to structure the tree of parent-child
--relationships among the processes.  You can either make all the
--processes in the process group be children of the shell process, or you
--can make one process in group be the ancestor of all the other processes
--in that group.  The sample shell program presented in this chapter uses
--the first approach because it makes bookkeeping somewhat simpler.
--
--   As each process is forked, it should put itself in the new process
--group by calling `setpgid'; see *Note Process Group Functions::.  The
--first process in the new group becomes its "process group leader", and
--its process ID becomes the "process group ID" for the group.
--
--   The shell should also call `setpgid' to put each of its child
--processes into the new process group.  This is because there is a
--potential timing problem: each child process must be put in the process
--group before it begins executing a new program, and the shell depends on
--having all the child processes in the group before it continues
--executing.  If both the child processes and the shell call `setpgid',
--this ensures that the right things happen no matter which process gets
--to it first.
--
--   If the job is being launched as a foreground job, the new process
--group also needs to be put into the foreground on the controlling
--terminal using `tcsetpgrp'.  Again, this should be done by the shell as
--well as by each of its child processes, to avoid race conditions.
--
--   The next thing each child process should do is to reset its signal
--actions.
--
--   During initialization, the shell process set itself to ignore job
--control signals; see *Note Initializing the Shell::.  As a result, any
--child processes it creates also ignore these signals by inheritance.
--This is definitely undesirable, so each child process should explicitly
--set the actions for these signals back to `SIG_DFL' just after it is
--forked.
--
--   Since shells follow this convention, applications can assume that
--they inherit the correct handling of these signals from the parent
--process.  But every application has a responsibility not to mess up the
--handling of stop signals.  Applications that disable the normal
--interpretation of the SUSP character should provide some other
--mechanism for the user to stop the job.  When the user invokes this
--mechanism, the program should send a `SIGTSTP' signal to the process
--group of the process, not just to the process itself.  *Note Signaling
--Another Process::.
--
--   Finally, each child process should call `exec' in the normal way.
--This is also the point at which redirection of the standard input and
--output channels should be handled.  *Note Duplicating Descriptors::,
--for an explanation of how to do this.
--
--   Here is the function from the sample shell program that is
--responsible for launching a program.  The function is executed by each
--child process immediately after it has been forked by the shell, and
--never returns.
--
--     void
--     launch_process (process *p, pid_t pgid,
--                     int infile, int outfile, int errfile,
--                     int foreground)
--     {
--       pid_t pid;
--     
--       if (shell_is_interactive)
--         {
--           /* Put the process into the process group and give the process 
group
--              the terminal, if appropriate.
--              This has to be done both by the shell and in the individual
--              child processes because of potential race conditions.  */
--           pid = getpid ();
--           if (pgid == 0) pgid = pid;
--           setpgid (pid, pgid);
--           if (foreground)
--             tcsetpgrp (shell_terminal, pgid);
--     
--           /* Set the handling for job control signals back to the default.  
*/
--           signal (SIGINT, SIG_DFL);
--           signal (SIGQUIT, SIG_DFL);
--           signal (SIGTSTP, SIG_DFL);
--           signal (SIGTTIN, SIG_DFL);
--           signal (SIGTTOU, SIG_DFL);
--           signal (SIGCHLD, SIG_DFL);
--         }
--     
--       /* Set the standard input/output channels of the new process.  */
--       if (infile != STDIN_FILENO)
--         {
--           dup2 (infile, STDIN_FILENO);
--           close (infile);
--         }
--       if (outfile != STDOUT_FILENO)
--         {
--           dup2 (outfile, STDOUT_FILENO);
--           close (outfile);
--         }
--       if (errfile != STDERR_FILENO)
--         {
--           dup2 (errfile, STDERR_FILENO);
--           close (errfile);
--         }
--     
--       /* Exec the new process.  Make sure we exit.  */
--       execvp (p->argv[0], p->argv);
--       perror ("execvp");
--       exit (1);
--     }
--
--   If the shell is not running interactively, this function does not do
--anything with process groups or signals.  Remember that a shell not
--performing job control must keep all of its subprocesses in the same
--process group as the shell itself.
--
--   Next, here is the function that actually launches a complete job.
--After creating the child processes, this function calls some other
--functions to put the newly created job into the foreground or
--background; these are discussed in *Note Foreground and Background::.
--
--     void
--     launch_job (job *j, int foreground)
--     {
--       process *p;
--       pid_t pid;
--       int mypipe[2], infile, outfile;
--     
--       infile = j->stdin;
--       for (p = j->first_process; p; p = p->next)
--         {
--           /* Set up pipes, if necessary.  */
--           if (p->next)
--             {
--               if (pipe (mypipe) < 0)
--                 {
--                   perror ("pipe");
--                   exit (1);
--                 }
--               outfile = mypipe[1];
--             }
--           else
--             outfile = j->stdout;
--     
--           /* Fork the child processes.  */
--           pid = fork ();
--           if (pid == 0)
--             /* This is the child process.  */
--             launch_process (p, j->pgid, infile,
--                             outfile, j->stderr, foreground);
--           else if (pid < 0)
--             {
--               /* The fork failed.  */
--               perror ("fork");
--               exit (1);
--             }
--           else
--             {
--               /* This is the parent process.  */
--               p->pid = pid;
--               if (shell_is_interactive)
--                 {
--                   if (!j->pgid)
--                     j->pgid = pid;
--                   setpgid (pid, j->pgid);
--                 }
--             }
--     
--           /* Clean up after pipes.  */
--           if (infile != j->stdin)
--             close (infile);
--           if (outfile != j->stdout)
--             close (outfile);
--           infile = mypipe[0];
--         }
--     
--       format_job_info (j, "launched");
--     
--       if (!shell_is_interactive)
--         wait_for_job (j);
--       else if (foreground)
--         put_job_in_foreground (j, 0);
--       else
--         put_job_in_background (j, 0);
--     }
--
--
--File: libc.info,  Node: Foreground and Background,  Next: Stopped and 
Terminated Jobs,  Prev: Launching Jobs,  Up: Implementing a Shell
--
--Foreground and Background
---------------------------
--
--   Now let's consider what actions must be taken by the shell when it
--launches a job into the foreground, and how this differs from what must
--be done when a background job is launched.
--
--   When a foreground job is launched, the shell must first give it
--access to the controlling terminal by calling `tcsetpgrp'.  Then, the
--shell should wait for processes in that process group to terminate or
--stop.  This is discussed in more detail in *Note Stopped and Terminated
--Jobs::.
--
--   When all of the processes in the group have either completed or
--stopped, the shell should regain control of the terminal for its own
--process group by calling `tcsetpgrp' again.  Since stop signals caused
--by I/O from a background process or a SUSP character typed by the user
--are sent to the process group, normally all the processes in the job
--stop together.
--
--   The foreground job may have left the terminal in a strange state, so
--the shell should restore its own saved terminal modes before
--continuing.  In case the job is merely been stopped, the shell should
--first save the current terminal modes so that it can restore them later
--if the job is continued.  The functions for dealing with terminal modes
--are `tcgetattr' and `tcsetattr'; these are described in *Note Terminal
--Modes::.
--
--   Here is the sample shell's function for doing all of this.
--
--     /* Put job J in the foreground.  If CONT is nonzero,
--        restore the saved terminal modes and send the process group a
--        `SIGCONT' signal to wake it up before we block.  */
--     
--     void
--     put_job_in_foreground (job *j, int cont)
--     {
--       /* Put the job into the foreground.  */
--       tcsetpgrp (shell_terminal, j->pgid);
--
--     /* Send the job a continue signal, if necessary.  */
--       if (cont)
--         {
--           tcsetattr (shell_terminal, TCSADRAIN, &j->tmodes);
--           if (kill (- j->pgid, SIGCONT) < 0)
--             perror ("kill (SIGCONT)");
--         }
--     
--       /* Wait for it to report.  */
--       wait_for_job (j);
--     
--       /* Put the shell back in the foreground.  */
--       tcsetpgrp (shell_terminal, shell_pgid);
--     /* Restore the shell's terminal modes.  */
--       tcgetattr (shell_terminal, &j->tmodes);
--       tcsetattr (shell_terminal, TCSADRAIN, &shell_tmodes);
--     }
--
--   If the process group is launched as a background job, the shell
--should remain in the foreground itself and continue to read commands
--from the terminal.
--
--   In the sample shell, there is not much that needs to be done to put
--a job into the background.  Here is the function it uses:
--
--     /* Put a job in the background.  If the cont argument is true, send
--        the process group a `SIGCONT' signal to wake it up.  */
--     
--     void
--     put_job_in_background (job *j, int cont)
--     {
--       /* Send the job a continue signal, if necessary.  */
--       if (cont)
--         if (kill (-j->pgid, SIGCONT) < 0)
--           perror ("kill (SIGCONT)");
--     }
--
--
--File: libc.info,  Node: Stopped and Terminated Jobs,  Next: Continuing 
Stopped Jobs,  Prev: Foreground and Background,  Up: Implementing a Shell
--
--Stopped and Terminated Jobs
-----------------------------
--
--   When a foreground process is launched, the shell must block until
--all of the processes in that job have either terminated or stopped.  It
--can do this by calling the `waitpid' function; see *Note Process
--Completion::.  Use the `WUNTRACED' option so that status is reported
--for processes that stop as well as processes that terminate.
--
--   The shell must also check on the status of background jobs so that it
--can report terminated and stopped jobs to the user; this can be done by
--calling `waitpid' with the `WNOHANG' option.  A good place to put a
--such a check for terminated and stopped jobs is just before prompting
--for a new command.
--
--   The shell can also receive asynchronous notification that there is
--status information available for a child process by establishing a
--handler for `SIGCHLD' signals.  *Note Signal Handling::.
--
--   In the sample shell program, the `SIGCHLD' signal is normally
--ignored.  This is to avoid reentrancy problems involving the global data
--structures the shell manipulates.  But at specific times when the shell
--is not using these data structures--such as when it is waiting for
--input on the terminal--it makes sense to enable a handler for
--`SIGCHLD'.  The same function that is used to do the synchronous status
--checks (`do_job_notification', in this case) can also be called from
--within this handler.
--
--   Here are the parts of the sample shell program that deal with
--checking the status of jobs and reporting the information to the user.
--
--     /* Store the status of the process PID that was returned by waitpid.
--        Return 0 if all went well, nonzero otherwise.  */
--     
--     int
--     mark_process_status (pid_t pid, int status)
--     {
--       job *j;
--       process *p;
--
--     if (pid > 0)
--         {
--           /* Update the record for the process.  */
--           for (j = first_job; j; j = j->next)
--             for (p = j->first_process; p; p = p->next)
--               if (p->pid == pid)
--                 {
--                   p->status = status;
--                   if (WIFSTOPPED (status))
--                     p->stopped = 1;
--                   else
--                     {
--                       p->completed = 1;
--                       if (WIFSIGNALED (status))
--                         fprintf (stderr, "%d: Terminated by signal %d.\n",
--                                  (int) pid, WTERMSIG (p->status));
--                     }
--                   return 0;
--                  }
--           fprintf (stderr, "No child process %d.\n", pid);
--           return -1;
--         }
--
--     else if (pid == 0 || errno == ECHILD)
--         /* No processes ready to report.  */
--         return -1;
--       else {
--         /* Other weird errors.  */
--         perror ("waitpid");
--         return -1;
--       }
--     }
--
--     /* Check for processes that have status information available,
--        without blocking.  */
--     
--     void
--     update_status (void)
--     {
--       int status;
--       pid_t pid;
--     
--       do
--         pid = waitpid (WAIT_ANY, &status, WUNTRACED|WNOHANG);
--       while (!mark_process_status (pid, status));
--     }
--
--     /* Check for processes that have status information available,
--        blocking until all processes in the given job have reported.  */
--     
--     void
--     wait_for_job (job *j)
--     {
--       int status;
--       pid_t pid;
--     
--       do
--         pid = waitpid (WAIT_ANY, &status, WUNTRACED);
--       while (!mark_process_status (pid, status)
--              && !job_is_stopped (j)
--              && !job_is_completed (j));
--     }
--
--     /* Format information about job status for the user to look at.  */
--     
--     void
--     format_job_info (job *j, const char *status)
--     {
--       fprintf (stderr, "%ld (%s): %s\n", (long)j->pgid, status, j->command);
--     }
--
--     /* Notify the user about stopped or terminated jobs.
--        Delete terminated jobs from the active job list.  */
--     
--     void
--     do_job_notification (void)
--     {
--       job *j, *jlast, *jnext;
--       process *p;
--     
--       /* Update status information for child processes.  */
--       update_status ();
--     
--       jlast = NULL;
--       for (j = first_job; j; j = jnext)
--         {
--           jnext = j->next;
--     
--           /* If all processes have completed, tell the user the job has
--              completed and delete it from the list of active jobs.  */
--           if (job_is_completed (j)) {
--             format_job_info (j, "completed");
--             if (jlast)
--               jlast->next = jnext;
--             else
--               first_job = jnext;
--             free_job (j);
--           }
--     
--           /* Notify the user about stopped jobs,
--              marking them so that we won't do this more than once.  */
--           else if (job_is_stopped (j) && !j->notified) {
--             format_job_info (j, "stopped");
--             j->notified = 1;
--             jlast = j;
--           }
--     
--           /* Don't say anything about jobs that are still running.  */
--           else
--             jlast = j;
--         }
--     }
--
--
--File: libc.info,  Node: Continuing Stopped Jobs,  Next: Missing Pieces,  
Prev: Stopped and Terminated Jobs,  Up: Implementing a Shell
--
--Continuing Stopped Jobs
-------------------------
--
--   The shell can continue a stopped job by sending a `SIGCONT' signal
--to its process group.  If the job is being continued in the foreground,
--the shell should first invoke `tcsetpgrp' to give the job access to the
--terminal, and restore the saved terminal settings.  After continuing a
--job in the foreground, the shell should wait for the job to stop or
--complete, as if the job had just been launched in the foreground.
--
--   The sample shell program handles both newly created and continued
--jobs with the same pair of functions, `put_job_in_foreground' and
--`put_job_in_background'.  The definitions of these functions were given
--in *Note Foreground and Background::.  When continuing a stopped job, a
--nonzero value is passed as the CONT argument to ensure that the
--`SIGCONT' signal is sent and the terminal modes reset, as appropriate.
--
--   This leaves only a function for updating the shell's internal
--bookkeeping about the job being continued:
--
--     /* Mark a stopped job J as being running again.  */
--     
--     void
--     mark_job_as_running (job *j)
--     {
--       Process *p;
--     
--       for (p = j->first_process; p; p = p->next)
--         p->stopped = 0;
--       j->notified = 0;
--     }
--
--     /* Continue the job J.  */
--     
--     void
--     continue_job (job *j, int foreground)
--     {
--       mark_job_as_running (j);
--       if (foreground)
--         put_job_in_foreground (j, 1);
--       else
--         put_job_in_background (j, 1);
--     }
--
--
--File: libc.info,  Node: Missing Pieces,  Prev: Continuing Stopped Jobs,  Up: 
Implementing a Shell
--
--The Missing Pieces
--------------------
--
--   The code extracts for the sample shell included in this chapter are
--only a part of the entire shell program.  In particular, nothing at all
--has been said about how `job' and `program' data structures are
--allocated and initialized.
--
--   Most real shells provide a complex user interface that has support
--for a command language; variables; abbreviations, substitutions, and
--pattern matching on file names; and the like.  All of this is far too
--complicated to explain here!  Instead, we have concentrated on showing
--how to implement the core process creation and job control functions
--that can be called from such a shell.
--
--   Here is a table summarizing the major entry points we have presented:
--
--`void init_shell (void)'
--     Initialize the shell's internal state.  *Note Initializing the
--     Shell::.
--
--`void launch_job (job *J, int FOREGROUND)'
--     Launch the job J as either a foreground or background job.  *Note
--     Launching Jobs::.
--
--`void do_job_notification (void)'
--     Check for and report any jobs that have terminated or stopped.
--     Can be called synchronously or within a handler for `SIGCHLD'
--     signals.  *Note Stopped and Terminated Jobs::.
--
--`void continue_job (job *J, int FOREGROUND)'
--     Continue the job J.  *Note Continuing Stopped Jobs::.
--
--   Of course, a real shell would also want to provide other functions
--for managing jobs.  For example, it would be useful to have commands to
--list all active jobs or to send a signal (such as `SIGKILL') to a job.
--
--
--File: libc.info,  Node: Functions for Job Control,  Prev: Implementing a 
Shell,  Up: Job Control
--
--Functions for Job Control
--=========================
--
--   This section contains detailed descriptions of the functions relating
--to job control.
--
--* Menu:
--
--* Identifying the Terminal::    Determining the controlling terminal's name.
--* Process Group Functions::     Functions for manipulating process groups.
--* Terminal Access Functions::   Functions for controlling terminal access.
--
--
--File: libc.info,  Node: Identifying the Terminal,  Next: Process Group 
Functions,  Up: Functions for Job Control
--
--Identifying the Controlling Terminal
--------------------------------------
--
--   You can use the `ctermid' function to get a file name that you can
--use to open the controlling terminal.  In the GNU library, it returns
--the same string all the time: `"/dev/tty"'.  That is a special "magic"
--file name that refers to the controlling terminal of the current
--process (if it has one).  To find the name of the specific terminal
--device, use `ttyname'; *note Is It a Terminal::..
--
--   The function `ctermid' is declared in the header file `stdio.h'.
--
-- - Function: char * ctermid (char *STRING)
--     The `ctermid' function returns a string containing the file name of
--     the controlling terminal for the current process.  If STRING is
--     not a null pointer, it should be an array that can hold at least
--     `L_ctermid' characters; the string is returned in this array.
--     Otherwise, a pointer to a string in a static area is returned,
--     which might get overwritten on subsequent calls to this function.
--
--     An empty string is returned if the file name cannot be determined
--     for any reason.  Even if a file name is returned, access to the
--     file it represents is not guaranteed.
--
-- - Macro: int L_ctermid
--     The value of this macro is an integer constant expression that
--     represents the size of a string large enough to hold the file name
--     returned by `ctermid'.
--
--   See also the `isatty' and `ttyname' functions, in *Note Is It a
--Terminal::.
--
--
--File: libc.info,  Node: Process Group Functions,  Next: Terminal Access 
Functions,  Prev: Identifying the Terminal,  Up: Functions for Job Control
--
--Process Group Functions
-------------------------
--
--   Here are descriptions of the functions for manipulating process
--groups.  Your program should include the header files `sys/types.h' and
--`unistd.h' to use these functions.
--
-- - Function: pid_t setsid (void)
--     The `setsid' function creates a new session.  The calling process
--     becomes the session leader, and is put in a new process group whose
--     process group ID is the same as the process ID of that process.
--     There are initially no other processes in the new process group,
--     and no other process groups in the new session.
--
--     This function also makes the calling process have no controlling
--     terminal.
--
--     The `setsid' function returns the new process group ID of the
--     calling process if successful.  A return value of `-1' indicates an
--     error.  The following `errno' error conditions are defined for this
--     function:
--
--    `EPERM'
--          The calling process is already a process group leader, or
--          there is already another process group around that has the
--          same process group ID.
--
--   The `getpgrp' function has two definitions: one derived from BSD
--Unix, and one from the POSIX.1 standard.  The feature test macros you
--have selected (*note Feature Test Macros::.) determine which definition
--you get.  Specifically, you get the BSD version if you define
--`_BSD_SOURCE'; otherwise, you get the POSIX version if you define
--`_POSIX_SOURCE' or `_GNU_SOURCE'.  Programs written for old BSD systems
--will not include `unistd.h', which defines `getpgrp' specially under
--`_BSD_SOURCE'.  You must link such programs with the `-lbsd-compat'
--option to get the BSD definition.
--
-- - POSIX.1 Function: pid_t getpgrp (void)
--     The POSIX.1 definition of `getpgrp' returns the process group ID of
--     the calling process.
--
-- - BSD Function: pid_t getpgrp (pid_t PID)
--     The BSD definition of `getpgrp' returns the process group ID of the
--     process PID.  You can supply a value of `0' for the PID argument
--     to get information about the calling process.
--
-- - Function: int setpgid (pid_t PID, pid_t PGID)
--     The `setpgid' function puts the process PID into the process group
--     PGID.  As a special case, either PID or PGID can be zero to
--     indicate the process ID of the calling process.
--
--     This function fails on a system that does not support job control.
--     *Note Job Control is Optional::, for more information.
--
--     If the operation is successful, `setpgid' returns zero.  Otherwise
--     it returns `-1'.  The following `errno' error conditions are
--     defined for this function:
--
--    `EACCES'
--          The child process named by PID has executed an `exec'
--          function since it was forked.
--
--    `EINVAL'
--          The value of the PGID is not valid.
--
--    `ENOSYS'
--          The system doesn't support job control.
--
--    `EPERM'
--          The process indicated by the PID argument is a session leader,
--          or is not in the same session as the calling process, or the
--          value of the PGID argument doesn't match a process group ID
--          in the same session as the calling process.
--
--    `ESRCH'
--          The process indicated by the PID argument is not the calling
--          process or a child of the calling process.
--
-- - Function: int setpgrp (pid_t PID, pid_t PGID)
--     This is the BSD Unix name for `setpgid'.  Both functions do exactly
--     the same thing.
--
--
--File: libc.info,  Node: Terminal Access Functions,  Prev: Process Group 
Functions,  Up: Functions for Job Control
--
--Functions for Controlling Terminal Access
-------------------------------------------
--
--   These are the functions for reading or setting the foreground
--process group of a terminal.  You should include the header files
--`sys/types.h' and `unistd.h' in your application to use these functions.
--
--   Although these functions take a file descriptor argument to specify
--the terminal device, the foreground job is associated with the terminal
--file itself and not a particular open file descriptor.
--
-- - Function: pid_t tcgetpgrp (int FILEDES)
--     This function returns the process group ID of the foreground
--     process group associated with the terminal open on descriptor
--     FILEDES.
--
--     If there is no foreground process group, the return value is a
--     number greater than `1' that does not match the process group ID
--     of any existing process group.  This can happen if all of the
--     processes in the job that was formerly the foreground job have
--     terminated, and no other job has yet been moved into the
--     foreground.
--
--     In case of an error, a value of `-1' is returned.  The following
--     `errno' error conditions are defined for this function:
--
--    `EBADF'
--          The FILEDES argument is not a valid file descriptor.
--
--    `ENOSYS'
--          The system doesn't support job control.
--
--    `ENOTTY'
--          The terminal file associated with the FILEDES argument isn't
--          the controlling terminal of the calling process.
--
-- - Function: int tcsetpgrp (int FILEDES, pid_t PGID)
--     This function is used to set a terminal's foreground process group
--     ID.  The argument FILEDES is a descriptor which specifies the
--     terminal; PGID specifies the process group.  The calling process
--     must be a member of the same session as PGID and must have the same
--     controlling terminal.
--
--     For terminal access purposes, this function is treated as output.
--     If it is called from a background process on its controlling
--     terminal, normally all processes in the process group are sent a
--     `SIGTTOU' signal.  The exception is if the calling process itself
--     is ignoring or blocking `SIGTTOU' signals, in which case the
--     operation is performed and no signal is sent.
--
--     If successful, `tcsetpgrp' returns `0'.  A return value of `-1'
--     indicates an error.  The following `errno' error conditions are
--     defined for this function:
--
--    `EBADF'
--          The FILEDES argument is not a valid file descriptor.
--
--    `EINVAL'
--          The PGID argument is not valid.
--
--    `ENOSYS'
--          The system doesn't support job control.
--
--    `ENOTTY'
--          The FILEDES isn't the controlling terminal of the calling
--          process.
--
--    `EPERM'
--          The PGID isn't a process group in the same session as the
--          calling process.
--
--
--File: libc.info,  Node: Name Service Switch,  Next: Users and Groups,  Prev: 
Job Control,  Up: Top
--
--System Databases and Name Service Switch
--****************************************
--
--   Various functions in the C Library need to be configured to work
--correctly in the local environment.  Traditionally, this was done by
--using files (e.g., `/etc/passwd'), but other nameservices (line the
--Network Information Service (NIS) and the Domain Name Service (DNS))
--became popular, and were hacked into the C library, usually with a fixed
--search order (*note frobnicate: (jargon)frobnicate.).
--
--   The GNU C Library contains a cleaner solution of this problem.  It is
--designed after a method used by Sun Microsystems in the C library of
--Solaris 2.  GNU C Library follows their name and calls this scheme
--"Name Service Switch" (NSS).
--
--   Though the interface might be similar to Sun's version there is no
--common code.  We never saw any source code of Sun's implementation and
--so the internal interface is incompatible.  This is also manifests in
--the file names we use as we will see later.
--
--* Menu:
--
--* NSS Basics::                  What is this NSS good for.
--* NSS Configuration File::      Configuring NSS.
--* NSS Module Internals::        How does it work internally.
--* Extending NSS::               What to do to add services or databases.
--
--
--File: libc.info,  Node: NSS Basics,  Next: NSS Configuration File,  Prev: 
Name Service Switch,  Up: Name Service Switch
--
--NSS Basics
--==========
--
--   The basic idea is to put the implementation of the different services
--offered to access the databases in separate modules.  This has some
--advantages:
--
--  1. Contributors can add new services without adding them to GNU C
--     Library.
--
--  2. The modules can be updated separately.
--
--  3. The C library image is smaller.
--
--   To fulfill the first goal above the ABI of the modules will be
--described below.  For getting the implementation of a new service right
--it is important to understand how the functions in the modules get
--called.  They are in no way designed to be used by the programmer
--directly.  Instead the programmer should only use the documented and
--standardized functions to access the databases.
--
--The databases available in the NSS are
--
--`ethers'
--     Ethernet numbers,
--
--`group'
--     Groups of users, *note Group Database::..
--
--`hosts'
--     Host names and numbers, *note Host Names::..
--
--`netgroup'
--     Network wide list of host and users, *note Netgroup Database::..
--
--`network'
--     Network names and numbers, *note Networks Database::..
--
--`protocols'
--     Network protocols, *note Protocols Database::..
--
--`passwd'
--     User passwords, *note User Database::..
--
--`rpc'
--     Remote procedure call names and numbers,
--
--`services'
--     Network services, *note Services Database::..
--
--`shadow'
--     Shadow user passwords,
--
--There will be some more added later (`aliases', `automount',
--`bootparams', `netmasks', and `publickey').
--
--
--File: libc.info,  Node: NSS Configuration File,  Next: NSS Module Internals,  
Prev: NSS Basics,  Up: Name Service Switch
--
--The NSS Configuration File
--==========================
--
--   Somehow the NSS code must be told about the wishes of the user.  For
--this reason there is the file `/etc/nsswitch.conf'.  For each database
--this file contain a specification how the lookup process should work.
--The file could look like this:
--
--     # /etc/nsswitch.conf
--     #
--     # Name Service Switch configuration file.
--     #
--     
--     passwd:     db files nis
--     shadow:     files
--     group:      db files nis
--     
--     hosts:      files nisplus nis dns
--     networks:   nisplus [NOTFOUND=return] files
--     
--     ethers:     nisplus [NOTFOUND=return] db files
--     protocols:  nisplus [NOTFOUND=return] db files
--     rpc:        nisplus [NOTFOUND=return] db files
--     services:   nisplus [NOTFOUND=return] db files
--
--   The first column is the database as you can guess from the table
--above.  The rest of the line specifies how the lookup process works.
--Please note that you specify the way it works for each database
--individually.  This cannot be done with the old way of a monolithic
--implementation.
--
--   The configuration specification for each database can contain two
--different items:
--
--   * the service specification like `files', `db', or `nis'.
--
--   * the reaction on lookup result line `[NOTFOUND=return]'.
--
--* Menu:
--
--* Services in the NSS configuration::  Service names in the NSS configuration.
--* Actions in the NSS configuration::  React appropriately to the lookup 
result.
--* Notes on NSS Configuration File::  Things to take care about while
--                                     configuring NSS.
--
--
--File: libc.info,  Node: Services in the NSS configuration,  Next: Actions in 
the NSS configuration,  Prev: NSS Configuration File,  Up: NSS Configuration 
File
--
--Services in the NSS configuration File
----------------------------------------
--
--   The above example file mentions four different services: `files',
--`db', `nis', and `nisplus'.  This does not mean these services are
--available on all sites and it does also not mean these are all the
--services which will ever be available.
--
--   In fact, these names are simply strings which the NSS code uses to
--find the implicitly addressed functions.  The internal interface will be
--described later.  Visible to the user are the modules which implement an
--individual service.
--
--   Assume the service NAME shall be used for a lookup.  The code for
--this service is implemented in a module called `libnss_NAME'.  On a
--system supporting shared libraries this is in fact a shared library
--with the name (for example) `libnss_NAME.so.1'.  The number at the end
--is the currently used version of the interface which will not change
--frequently.  Normally the user should not have to be cognizant of these
--files since they should be placed in a directory where they are found
--automatically.  Only the names of all available services are important.
--
--
--File: libc.info,  Node: Actions in the NSS configuration,  Next: Notes on NSS 
Configuration File,  Prev: Services in the NSS configuration,  Up: NSS 
Configuration File
--
--Actions in the NSS configuration
----------------------------------
--
--   The second item in the specification gives the user much finer
--control on the lookup process.  Action items are placed between two
--service names and are written within brackets.  The general form is
--
--     `[' ( `!'? STATUS `=' ACTION )+ `]'
--
--where
--
--     STATUS => success | notfound | unavail | tryagain
--     ACTION => return | continue
--
--   The case of the keywords is insignificant.  The STATUS values are
--the results of a call to a lookup function of a specific service.  They
--mean
--
--`success'
--     No error occurred and the wanted entry is returned.  The default
--     action for this is `return'.
--
--`notfound'
--     The lookup process works ok but the needed value was not found.
--     The default action is `continue'.
--
--`unavail'
--     The service is permanently unavailable.  This can either mean the
--     needed file is not available, or, for DNS, the server is not
--     available or does not allow queries.  The default action is
--     `continue'.
--
--`tryagain'
--     The service is temporarily unavailable.  This could mean a file is
--     locked or a server currently cannot accept more connections.  The
--     default action is `continue'.
--
--If we have a line like
--
--     ethers: nisplus [NOTFOUND=return] db files
--
--this is equivalent to
--
--     ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue
--                      TRYAGAIN=continue]
--             db      [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
--                      TRYAGAIN=continue]
--             files
--
--(except that it would have to be written on one line).  The default
--value for the actions are normally what you want, and only need to be
--changed in exceptional cases.
--
--   If the optional `!' is placed before the STATUS this means the
--following action is used for all statii but STATUS itself.  I.e., `!'
--is negation as in the C language (and others).
--
--   Before we explain the exception which makes this action item
--necessary one more remark: obviously it makes no sense to add another
--action item after the `files' service.  Since there is no other service
--following the action *always* is `return'.
--
--   Now, why is this `[NOTFOUND=return]' action useful?  To understand
--this we should know that the `nisplus' service is often complete; i.e.,
--if an entry is not available in the NIS+ tables it is not available
--anywhere else.  This is what is expressed by this action item: it is
--useless to examine further services since they will not give us a
--result.
--
--   The situation would be different if the NIS+ service is not available
--because the machine is booting.  In this case the return value of the
--lookup function is not `notfound' but instead `unavail'.  And as you
--can see in the complete form above: in this situation the `db' and
--`files' services are used.  Neat, isn't it?  The system administrator
--need not pay special care for the time the system is not completely
--ready to work (while booting or shutdown or network problems).
--
--
--File: libc.info,  Node: Notes on NSS Configuration File,  Prev: Actions in 
the NSS configuration,  Up: NSS Configuration File
--
--Notes on the NSS Configuration File
-------------------------------------
--
--   Finally a few more hints.  The NSS implementation is not completely
--helpless if `/etc/nsswitch.conf' does not exist.  For all supported
--databases there is a default value so it should normally be possible to
--get the system running even if the file is corrupted or missing.
--
--   For the `hosts' and `network' databases the default value is `dns
--[!UNAVAIL=return] files'.  I.e., the system is prepared for the DNS
--service not to be available but if it is available the answer it
--returns is ultimative.
--
--   The `passwd', `group', and `shadow' databases are traditionally
--handled in a special way.  The appropriate files in the `/etc'
--directory are read but if an entry with a name starting with a `+'
--character is found NIS is used.  This kind of lookup remains possible
--by using the special lookup service `compat' and the default value for
--the three databases above is `compat [NOTFOUND=return] files'.
--
--   For all other databases the default value is `nis [NOTFOUND=return]
--files'.  This solution give the best chance to be correct since NIS and
--file based lookup is used.
--
--   A second point is that the user should try to optimize the lookup
--process.  The different service have different response times.  A
--simple file look up on a local file could be fast, but if the file is
--long and the needed entry is near the end of the file this may take
--quite some time.  In this case it might be better to use the `db'
--service which allows fast local access to large data sets.
--
--   Often the situation is that some global information like NIS must be
--used.  So it is unavoidable to use service entries like `nis' etc.  But
--one should avoid slow services like this if possible.
--
--
--File: libc.info,  Node: NSS Module Internals,  Next: Extending NSS,  Prev: 
NSS Configuration File,  Up: Name Service Switch
--
--NSS Module Internals
--====================
--
--   Now it is time to described how the modules look like.  The functions
--contained in a module are identified by their names.  I.e., there is no
--jump table or the like.  How this is done is of no interest here; those
--interested in this topic should read about Dynamic Linking.
--
--* Menu:
--
--* NSS Module Names::            Construction of the interface function of
--                                the NSS modules.
--* NSS Modules Interface::       Programming interface in the NSS module
--                                functions.
--
--
--File: libc.info,  Node: NSS Module Names,  Next: NSS Modules Interface,  
Prev: NSS Module Internals,  Up: NSS Module Internals
--
--The Naming Scheme of the NSS Modules
--------------------------------------
--
--The name of each function consist of various parts:
--
--            _nss_SERVICE_FUNCTION
--
--   SERVICE of course corresponds to the name of the module this
--function is found in.(1)  The FUNCTION part is derived from the
--interface function in the C library itself.  If the user calls the
--function `gethostbyname' and the service used is `files' the function
--
--            _nss_files_gethostbyname_r
--
--in the module
--
--            libnss_files.so.1
--
--is used.  You see, what is explained above in not the whole truth.  In
--fact the NSS modules only contain reentrant versions of the lookup
--functions.  I.e., if the user would call the `gethostbyname_r' function
--this also would end in the above function.  For all user interface
--functions the C library maps this call to a call to the reentrant
--function.  For reentrant functions this is trivial since the interface
--is (nearly) the same.  For the non-reentrant version pointers to static
--buffers are used to replace the user supplied buffers.
--
--   I.e., the reentrant functions *can* have counterparts.  No service
--module is forced to have functions for all databases and all kinds to
--access them.  If a function is not available it is simply treated as if
--the function would return `unavail' (*note Actions in the NSS
--configuration::.).
--
--   The file name `libnss_files.so.1' would be on a Solaris 2 system
--`nss_files.so.1'.  This is the difference mentioned above.  Sun's NSS
--modules are usable as modules which get indirectly loaded only.
--
--   The NSS modules in the GNU C Library are prepared to be used as
--normal libraries itself.  This is *not* true in the moment, though.
--But the different organization of the name space in the modules does
--not make it impossible like it is for Solaris.  Now you can see why the
--modules are still libraries.(2)
--
--   ---------- Footnotes ----------
--
--   (1)  Now you might ask why to duplicate this information.  The
--answer is that we want to keep the possibility to link directly with
--these shared objects.
--
--   (2)  There is a second explanation: we were too lazy to change the
--Makefiles to allow the generation of shared objects not starting with
--`lib' but do not tell this anybody.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-25 
glibc-2.0.1/manual/libc.info-25
---- ../glibc-2.0.1/manual/libc.info-25 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-25    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1217 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: NSS Modules Interface,  Prev: NSS Module Names,  Up: 
NSS Module Internals
--
--The Interface of the Function in NSS Modules
----------------------------------------------
--
--   Now we know about the functions contained in the modules.  It is now
--time to describe the types.  When we mentioned the reentrant versions of
--the functions above, this means there are some additional arguments
--(compared with the standard, non-reentrant version).  The prototypes for
--the non-reentrant and reentrant versions of our function above are:
--
--     struct hostent *gethostbyname (const char *name)
--     
--     int gethostbyname_r (const char *name, struct hostent *result_buf,
--                          char *buf, size_t buflen, struct hostent **result,
--                          int *h_errnop)
--
--The actual prototype of the function in the NSS modules in this case is
--
--     enum nss_status _nss_files_gethostbyname_r (const char *name,
--                                                 struct hostent *result_buf,
--                                                 char *buf, size_t buflen,
--                                                 int *h_errnop)
--
--   I.e., the interface function is in fact the reentrant function with
--the change of the return value.  While the user-level function returns a
--pointer to the result the reentrant function return an `enum
--nss_status' value:
--
--`NSS_STATUS_TRYAGAIN'
--     numeric value `-2'
--
--`NSS_STATUS_UNAVAIL'
--     numeric value `-1'
--
--`NSS_STATUS_NOTFOUND'
--     numeric value `0'
--
--`NSS_STATUS_SUCCESS'
--     numeric value `1'
--
--Now you see where the action items of the `/etc/nsswitch.conf' file are
--used.
--
--   If you study the source code you will find there is a fifth value:
--`NSS_STATUS_RETURN'.  This is an internal use only value, used by a few
--functions in places where none of the above value can be used.  If
--necessary the source code should be examined to learn about the details.
--
--   The above function has something special which is missing for almost
--all the other module functions.  There is an argument H_ERRNOP.  This
--points to a variable which will be filled with the error code in case
--the execution of the function fails for some reason.  The reentrant
--function cannot use the global variable H_ERRNO; `gethostbyname' calls
--`gethostbyname_r' with the last argument set to `&h_errno'.
--
--   The `getXXXbyYYY' functions are the most important functions in the
--NSS modules.  But there are others which implement the other ways to
--access system databases (say for the password database, there are
--`setpwent', `getpwent', and `endpwent').  These will be described in
--more detail later.  Here we give a general way to determine the
--signature of the module function:
--
--   * the return value is `int';
--
--   * the name is as explain in *note NSS Module Names::.;
--
--   * the first arguments are identical to the arguments of the
--     non-reentrant function;
--
--   * the next three arguments are:
--
--    `STRUCT_TYPE result_buf'
--          pointer to buffer where the result is stored.  `STRUCT_TYPE'
--          is normally a struct which corresponds to the database.
--
--    `char *buffer'
--          pointer to a buffer where the function can store additional
--          adata for the result etc.
--
--    `int buflen'
--          length of the buffer pointed to by BUFFER.
--
--   * possibly a last argument H_ERRNOP, for the host name and network
--     name lookup functions.
--
--This table is correct for all functions but the `set...ent' and
--`end...ent' functions.
--
--
--File: libc.info,  Node: Extending NSS,  Prev: NSS Module Internals,  Up: Name 
Service Switch
--
--Extending NSS
--=============
--
--   One of the advantages of NSS mentioned above is that it can be
--extended quite easily.  There are two ways in which the extension can
--happen: adding another database or adding another service.  The former
--is normally done only by the C library developers.  It is here only
--important to remember that adding another database is independent from
--adding another service because a service need not support all databases
--or lookup functions.
--
--   A designer/implementor of a new service is therefore free to choose
--the databases s/he is interested in and leave the rest for later (or
--completely aside).
--
--* Menu:
--
--* Adding another Service to NSS::  What is to do to add a new service.
--* NSS Module Function Internals::  Guidelines for writing new NSS
--                                        service functions.
--
--
--File: libc.info,  Node: Adding another Service to NSS,  Next: NSS Module 
Function Internals,  Prev: Extending NSS,  Up: Extending NSS
--
--Adding another Service to NSS
-------------------------------
--
--   The sources for a new service need not (and should not) be part of
--the GNU C Library itself.  The developer retains complete control over
--the sources and its development.  The links between the C library and
--the new service module consists solely of the interface functions.
--
--   Each module is designed following a specific interface specification.
--For now the version is 1 and this manifests in the version number of the
--shared library object of the NSS modules: they have the extension `.1'.
--If the interface ever changes in an incompatible way, this number will
--be increased--hopefully this will never be necessary.  Modules using
--the old interface will still be usable.
--
--   Developers of a new service will have to make sure that their module
--is created using the correct interface number.  This means the file
--itself must have the correct name and on ElF systems the "soname"
--(Shared Object Name) must also have this number.  Building a module
--from a bunch of object files on an ELF system using GNU CC could be
--done like this:
--
--     gcc -shared -o libnss_NAME.so.1 -Wl,-soname,libnss_NAME.so.1 OBJECTS
--
--*Note Options for Linking: (gcc)Link Options, to learn more about this
--command line.
--
--   To use the new module the library must be able to find it.  This can
--be achieved by using options for the dynamic linker so that it will
--search directory where the binary is placed.  For an ELF system this
--could be done by adding the wanted directory to the value of
--`LD_LIBRARY_PATH'.
--
--   But this is not always possible since some program (those which run
--under IDs which do not belong to the user) ignore this variable.
--Therefore the stable version of the module should be placed into a
--directory which is searched by the dynamic linker.  Normally this should
--be the directory `$prefix/lib', where `$prefix' corresponds to the
--value given to configure using the `--prefix' option.  But be careful:
--this should only be done if it is clear the module does not cause any
--harm.  System administrators should be careful.
--
--
--File: libc.info,  Node: NSS Module Function Internals,  Prev: Adding another 
Service to NSS,  Up: Extending NSS
--
--Internals of the NSS Module Functions
---------------------------------------
--
--   Until now we only provided the syntactic interface for the functions
--in the NSS module.  In fact there is not more much we can tell since the
--implementation obviously is different for each function.  But a few
--general rules must be followed by all functions.
--
--   In fact there are four kinds of different functions which may appear
--in the interface.  All derive from the traditional ones for system
--databases.  DB in the following table is normally an abbreviation for
--the database (e.g., it is `pw' for the password database).
--
--`enum nss_status _nss_DATABASE_setDBent (void)'
--     This function prepares the service for following operations.  For a
--     simple file based lookup this means files could be opened, for
--     other services this function simply is a noop.
--
--     One special case for this function is that it takes an additional
--     argument for some DATABASEs (i.e., the interface is `int setDBent
--     (int)').  *Note Host Names::, which describes the `sethostent'
--     function.
--
--     The return value should be NSS_STATUS_SUCCESS or according to the
--     table above in case of an error (*note NSS Modules Interface::.).
--
--`enum nss_status _nss_DATABASE_endDBent (void)'
--     This function simply closes all files which are still open or
--     removes buffer caches.  If there are no files or buffers to remove
--     this is again a simple noop.
--
--     There normally is no return value different to NSS_STATUS_SUCCESS.
--
--`enum nss_status _nss_DATABASE_getDBent_r (STRUCTURE *result, char *buffer, 
size_t buflen)'
--     Since this function will be called several times in a row to
--     retrieve one entry after the other it must keep some kind of
--     state.  But this also means the functions are not really
--     reentrant.  They are reentrant only in that simultaneous calls to
--     this function will not try to write the retrieved data in the same
--     place (as it would be the case for the non-reentrant functions);
--     instead, it writes to the structure pointed to by the RESULT
--     parameter.  But the calls share a common state and in the case of
--     a file access this means they return neighboring entries in the
--     file.
--
--     The buffer of length BUFLEN pointed to by BUFFER can be used for
--     storing some additional data for the result.  It is *not*
--     guaranteed that the same buffer will be passed for the next call
--     of this function.  Therefore one must not misuse this buffer to
--     save some state information from one call to another.
--
--     As explained above this function could also have an additional last
--     argument.  This depends on the database used; it happens only for
--     `host' and `network'.
--
--     The function shall return `NSS_STATUS_SUCCESS' as long as their are
--     more entries.  When the last entry was read it should return
--     `NSS_STATUS_NOTFOUND'.  When the buffer given as an argument is too
--     small for the data to be returned `NSS_STATUS_TRYAGAIN' should be
--     returned.  When the service was not formerly initialized by a call
--     to `_nss_DATABASE_setDBent' all return value allowed for this
--     function can also be returned here.
--
--`enum nss_status _nss_DATABASE_getDBbyXX_r (PARAMS, STRUCTURE *result, char 
*buffer, size_t buflen)'
--     This function shall return the entry from the database which is
--     addressed by the PARAMS.  The type and number of these arguments
--     vary.  It must be individually determined by looking to the
--     user-level interface functions.  All arguments given to the
--     non-reentrant version are here described by PARAMS.
--
--     The result must be stored in the structure pointed to by RESULT.
--     If there is additional data to return (say strings, where the
--     RESULT structure only contains pointers) the function must use the
--     BUFFER or length BUFLEN.  There must not be any references to
--     non-constant global data.
--
--     The implementation of this function should honour the STAYOPEN
--     flag set by the `setDBent' function whenever this makes sense.
--
--     Again, this function takes an additional last argument for the
--     `host' and `network' database.
--
--     The return value should as always follow the rules given above
--     (*note NSS Modules Interface::.).
--
--
--File: libc.info,  Node: Users and Groups,  Next: System Information,  Prev: 
Name Service Switch,  Up: Top
--
--Users and Groups
--****************
--
--   Every user who can log in on the system is identified by a unique
--number called the "user ID".  Each process has an effective user ID
--which says which user's access permissions it has.
--
--   Users are classified into "groups" for access control purposes.  Each
--process has one or more "group ID values" which say which groups the
--process can use for access to files.
--
--   The effective user and group IDs of a process collectively form its
--"persona".  This determines which files the process can access.
--Normally, a process inherits its persona from the parent process, but
--under special circumstances a process can change its persona and thus
--change its access permissions.
--
--   Each file in the system also has a user ID and a group ID.  Access
--control works by comparing the user and group IDs of the file with those
--of the running process.
--
--   The system keeps a database of all the registered users, and another
--database of all the defined groups.  There are library functions you
--can use to examine these databases.
--
--* Menu:
--
--* User and Group IDs::          Each user has a unique numeric ID;
--                               likewise for groups.
--* Process Persona::             The user IDs and group IDs of a process.
--* Why Change Persona::          Why a program might need to change
--                               its user and/or group IDs.
--* How Change Persona::          Changing the user and group IDs.
--* Reading Persona::             How to examine the user and group IDs.
--
--* Setting User ID::             Functions for setting the user ID.
--* Setting Groups::              Functions for setting the group IDs.
--
--* Enable/Disable Setuid::       Turning setuid access on and off.
--* Setuid Program Example::      The pertinent parts of one sample program.
--* Tips for Setuid::             How to avoid granting unlimited access.
--
--* Who Logged In::               Getting the name of the user who logged in,
--                               or of the real user ID of the current process.
--
--* User Database::               Functions and data structures for
--                               accessing the user database.
--* Group Database::              Functions and data structures for
--                               accessing the group database.
--* Netgroup Database::           Functions for accessing the netgroup database.
--* Database Example::            Example program showing use of database
--                               inquiry functions.
--
--
--File: libc.info,  Node: User and Group IDs,  Next: Process Persona,  Prev: 
Users and Groups,  Up: Users and Groups
--
--User and Group IDs
--==================
--
--   Each user account on a computer system is identified by a "user
--name" (or "login name") and "user ID".  Normally, each user name has a
--unique user ID, but it is possible for several login names to have the
--same user ID.  The user names and corresponding user IDs are stored in
--a data base which you can access as described in *Note User Database::.
--
--   Users are classified in "groups".  Each user name also belongs to
--one or more groups, and has one "default group".  Users who are members
--of the same group can share resources (such as files) that are not
--accessible to users who are not a member of that group.  Each group has
--a "group name" and "group ID".  *Note Group Database::, for how to find
--information about a group ID or group name.
--
--
--File: libc.info,  Node: Process Persona,  Next: Why Change Persona,  Prev: 
User and Group IDs,  Up: Users and Groups
--
--The Persona of a Process
--========================
--
--   At any time, each process has a single user ID and a group ID which
--determine the privileges of the process.  These are collectively called
--the "persona" of the process, because they determine "who it is" for
--purposes of access control.  These IDs are also called the "effective
--user ID" and "effective group ID" of the process.
--
--   Your login shell starts out with a persona which consists of your
--user ID and your default group ID.  In normal circumstances, all your
--other processes inherit these values.
--
--   A process also has a "real user ID" which identifies the user who
--created the process, and a "real group ID" which identifies that user's
--default group.  These values do not play a role in access control, so
--we do not consider them part of the persona.  But they are also
--important.
--
--   Both the real and effective user ID can be changed during the
--lifetime of a process.  *Note Why Change Persona::.
--
--   In addition, a user can belong to multiple groups, so the persona
--includes "supplementary group IDs" that also contribute to access
--permission.
--
--   For details on how a process's effective user IDs and group IDs
--affect its permission to access files, see *Note Access Permission::.
--
--   The user ID of a process also controls permissions for sending
--signals using the `kill' function.  *Note Signaling Another Process::.
--
--
--File: libc.info,  Node: Why Change Persona,  Next: How Change Persona,  Prev: 
Process Persona,  Up: Users and Groups
--
--Why Change the Persona of a Process?
--====================================
--
--   The most obvious situation where it is necessary for a process to
--change its user and/or group IDs is the `login' program.  When `login'
--starts running, its user ID is `root'.  Its job is to start a shell
--whose user and group IDs are those of the user who is logging in.  (To
--accomplish this fully, `login' must set the real user and group IDs as
--well as its persona.  But this is a special case.)
--
--   The more common case of changing persona is when an ordinary user
--program needs access to a resource that wouldn't ordinarily be
--accessible to the user actually running it.
--
--   For example, you may have a file that is controlled by your program
--but that shouldn't be read or modified directly by other users, either
--because it implements some kind of locking protocol, or because you want
--to preserve the integrity or privacy of the information it contains.
--This kind of restricted access can be implemented by having the program
--change its effective user or group ID to match that of the resource.
--
--   Thus, imagine a game program that saves scores in a file.  The game
--program itself needs to be able to update this file no matter who is
--running it, but if users can write the file without going through the
--game, they can give themselves any scores they like.  Some people
--consider this undesirable, or even reprehensible.  It can be prevented
--by creating a new user ID and login name (say, `games') to own the
--scores file, and make the file writable only by this user.  Then, when
--the game program wants to update this file, it can change its effective
--user ID to be that for `games'.  In effect, the program must adopt the
--persona of `games' so it can write the scores file.
--
--
--File: libc.info,  Node: How Change Persona,  Next: Reading Persona,  Prev: 
Why Change Persona,  Up: Users and Groups
--
--How an Application Can Change Persona
--=====================================
--
--   The ability to change the persona of a process can be a source of
--unintentional privacy violations, or even intentional abuse.  Because of
--the potential for problems, changing persona is restricted to special
--circumstances.
--
--   You can't arbitrarily set your user ID or group ID to anything you
--want; only privileged processes can do that.  Instead, the normal way
--for a program to change its persona is that it has been set up in
--advance to change to a particular user or group.  This is the function
--of the setuid and setgid bits of a file's access mode.  *Note
--Permission Bits::.
--
--   When the setuid bit of an executable file is set, executing that file
--automatically changes the effective user ID to the user that owns the
--file.  Likewise, executing a file whose setgid bit is set changes the
--effective group ID to the group of the file.  *Note Executing a File::.
--Creating a file that changes to a particular user or group ID thus
--requires full access to that user or group ID.
--
--   *Note File Attributes::, for a more general discussion of file modes
--and accessibility.
--
--   A process can always change its effective user (or group) ID back to
--its real ID.  Programs do this so as to turn off their special
--privileges when they are not needed, which makes for more robustness.
--
--
--File: libc.info,  Node: Reading Persona,  Next: Setting User ID,  Prev: How 
Change Persona,  Up: Users and Groups
--
--Reading the Persona of a Process
--================================
--
--   Here are detailed descriptions of the functions for reading the user
--and group IDs of a process, both real and effective.  To use these
--facilities, you must include the header files `sys/types.h' and
--`unistd.h'.
--
-- - Data Type: uid_t
--     This is an integer data type used to represent user IDs.  In the
--     GNU library, this is an alias for `unsigned int'.
--
-- - Data Type: gid_t
--     This is an integer data type used to represent group IDs.  In the
--     GNU library, this is an alias for `unsigned int'.
--
-- - Function: uid_t getuid (void)
--     The `getuid' function returns the real user ID of the process.
--
-- - Function: gid_t getgid (void)
--     The `getgid' function returns the real group ID of the process.
--
-- - Function: uid_t geteuid (void)
--     The `geteuid' function returns the effective user ID of the
--     process.
--
-- - Function: gid_t getegid (void)
--     The `getegid' function returns the effective group ID of the
--     process.
--
-- - Function: int getgroups (int COUNT, gid_t *GROUPS)
--     The `getgroups' function is used to inquire about the supplementary
--     group IDs of the process.  Up to COUNT of these group IDs are
--     stored in the array GROUPS; the return value from the function is
--     the number of group IDs actually stored.  If COUNT is smaller than
--     the total number of supplementary group IDs, then `getgroups'
--     returns a value of `-1' and `errno' is set to `EINVAL'.
--
--     If COUNT is zero, then `getgroups' just returns the total number
--     of supplementary group IDs.  On systems that do not support
--     supplementary groups, this will always be zero.
--
--     Here's how to use `getgroups' to read all the supplementary group
--     IDs:
--
--          gid_t *
--          read_all_groups (void)
--          {
--            int ngroups = getgroups (0, NULL);
--            gid_t *groups
--              = (gid_t *) xmalloc (ngroups * sizeof (gid_t));
--            int val = getgroups (ngroups, groups);
--            if (val < 0)
--              {
--                free (groups);
--                return NULL;
--              }
--            return groups;
--          }
--
--
--File: libc.info,  Node: Setting User ID,  Next: Setting Groups,  Prev: 
Reading Persona,  Up: Users and Groups
--
--Setting the User ID
--===================
--
--   This section describes the functions for altering the user ID (real
--and/or effective) of a process.  To use these facilities, you must
--include the header files `sys/types.h' and `unistd.h'.
--
-- - Function: int setuid (uid_t NEWUID)
--     This function sets both the real and effective user ID of the
--     process to NEWUID, provided that the process has appropriate
--     privileges.
--
--     If the process is not privileged, then NEWUID must either be equal
--     to the real user ID or the saved user ID (if the system supports
--     the `_POSIX_SAVED_IDS' feature).  In this case, `setuid' sets only
--     the effective user ID and not the real user ID.
--
--     The `setuid' function returns a value of `0' to indicate
--     successful completion, and a value of `-1' to indicate an error.
--     The following `errno' error conditions are defined for this
--     function:
--
--    `EINVAL'
--          The value of the NEWUID argument is invalid.
--
--    `EPERM'
--          The process does not have the appropriate privileges; you do
--          not have permission to change to the specified ID.
--
-- - Function: int setreuid (uid_t RUID, uid_t EUID)
--     This function sets the real user ID of the process to RUID and the
--     effective user ID to EUID.  If RUID is `-1', it means not to
--     change the real user ID; likewise if EUID is `-1', it means not to
--     change the effective user ID.
--
--     The `setreuid' function exists for compatibility with 4.3 BSD Unix,
--     which does not support saved IDs.  You can use this function to
--     swap the effective and real user IDs of the process.  (Privileged
--     processes are not limited to this particular usage.)  If saved IDs
--     are supported, you should use that feature instead of this
--     function.  *Note Enable/Disable Setuid::.
--
--     The return value is `0' on success and `-1' on failure.  The
--     following `errno' error conditions are defined for this function:
--
--    `EPERM'
--          The process does not have the appropriate privileges; you do
--          not have permission to change to the specified ID.
--
--
--File: libc.info,  Node: Setting Groups,  Next: Enable/Disable Setuid,  Prev: 
Setting User ID,  Up: Users and Groups
--
--Setting the Group IDs
--=====================
--
--   This section describes the functions for altering the group IDs (real
--and effective) of a process.  To use these facilities, you must include
--the header files `sys/types.h' and `unistd.h'.
--
-- - Function: int setgid (gid_t NEWGID)
--     This function sets both the real and effective group ID of the
--     process to NEWGID, provided that the process has appropriate
--     privileges.
--
--     If the process is not privileged, then NEWGID must either be equal
--     to the real group ID or the saved group ID.  In this case, `setgid'
--     sets only the effective group ID and not the real group ID.
--
--     The return values and error conditions for `setgid' are the same
--     as those for `setuid'.
--
-- - Function: int setregid (gid_t RGID, fid_t EGID)
--     This function sets the real group ID of the process to RGID and
--     the effective group ID to EGID.  If RGID is `-1', it means not to
--     change the real group ID; likewise if EGID is `-1', it means not
--     to change the effective group ID.
--
--     The `setregid' function is provided for compatibility with 4.3 BSD
--     Unix, which does not support saved IDs.  You can use this function
--     to swap the effective and real group IDs of the process.
--     (Privileged processes are not limited to this usage.)  If saved
--     IDs are supported, you should use that feature instead of using
--     this function.  *Note Enable/Disable Setuid::.
--
--     The return values and error conditions for `setregid' are the same
--     as those for `setreuid'.
--
--   The GNU system also lets privileged processes change their
--supplementary group IDs.  To use `setgroups' or `initgroups', your
--programs should include the header file `grp.h'.
--
-- - Function: int setgroups (size_t COUNT, gid_t *GROUPS)
--     This function sets the process's supplementary group IDs.  It can
--     only be called from privileged processes.  The COUNT argument
--     specifies the number of group IDs in the array GROUPS.
--
--     This function returns `0' if successful and `-1' on error.  The
--     following `errno' error conditions are defined for this function:
--
--    `EPERM'
--          The calling process is not privileged.
--
-- - Function: int initgroups (const char *USER, gid_t GID)
--     The `initgroups' function effectively calls `setgroups' to set the
--     process's supplementary group IDs to be the normal default for the
--     user name USER.  The group ID GID is also included.
--
--
--File: libc.info,  Node: Enable/Disable Setuid,  Next: Setuid Program Example, 
 Prev: Setting Groups,  Up: Users and Groups
--
--Enabling and Disabling Setuid Access
--====================================
--
--   A typical setuid program does not need its special access all of the
--time.  It's a good idea to turn off this access when it isn't needed,
--so it can't possibly give unintended access.
--
--   If the system supports the saved user ID feature, you can accomplish
--this with `setuid'.  When the game program starts, its real user ID is
--`jdoe', its effective user ID is `games', and its saved user ID is also
--`games'.  The program should record both user ID values once at the
--beginning, like this:
--
--     user_user_id = getuid ();
--     game_user_id = geteuid ();
--
--   Then it can turn off game file access with
--
--     setuid (user_user_id);
--
--and turn it on with
--
--     setuid (game_user_id);
--
--Throughout this process, the real user ID remains `jdoe' and the saved
--user ID remains `games', so the program can always set its effective
--user ID to either one.
--
--   On other systems that don't support the saved user ID feature, you
--can turn setuid access on and off by using `setreuid' to swap the real
--and effective user IDs of the process, as follows:
--
--     setreuid (geteuid (), getuid ());
--
--This special case is always allowed--it cannot fail.
--
--   Why does this have the effect of toggling the setuid access?
--Suppose a game program has just started, and its real user ID is `jdoe'
--while its effective user ID is `games'.  In this state, the game can
--write the scores file.  If it swaps the two uids, the real becomes
--`games' and the effective becomes `jdoe'; now the program has only
--`jdoe' access.  Another swap brings `games' back to the effective user
--ID and restores access to the scores file.
--
--   In order to handle both kinds of systems, test for the saved user ID
--feature with a preprocessor conditional, like this:
--
--     #ifdef _POSIX_SAVED_IDS
--       setuid (user_user_id);
--     #else
--       setreuid (geteuid (), getuid ());
--     #endif
--
--
--File: libc.info,  Node: Setuid Program Example,  Next: Tips for Setuid,  
Prev: Enable/Disable Setuid,  Up: Users and Groups
--
--Setuid Program Example
--======================
--
--   Here's an example showing how to set up a program that changes its
--effective user ID.
--
--   This is part of a game program called `caber-toss' that manipulates
--a file `scores' that should be writable only by the game program
--itself.  The program assumes that its executable file will be installed
--with the set-user-ID bit set and owned by the same user as the `scores'
--file.  Typically, a system administrator will set up an account like
--`games' for this purpose.
--
--   The executable file is given mode `4755', so that doing an `ls -l'
--on it produces output like:
--
--     -rwsr-xr-x   1 games    184422 Jul 30 15:17 caber-toss
--
--The set-user-ID bit shows up in the file modes as the `s'.
--
--   The scores file is given mode `644', and doing an `ls -l' on it
--shows:
--
--     -rw-r--r--  1 games           0 Jul 31 15:33 scores
--
--   Here are the parts of the program that show how to set up the changed
--user ID.  This program is conditionalized so that it makes use of the
--saved IDs feature if it is supported, and otherwise uses `setreuid' to
--swap the effective and real user IDs.
--
--     #include <stdio.h>
--     #include <sys/types.h>
--     #include <unistd.h>
--     #include <stdlib.h>
--     
--     
--     /* Save the effective and real UIDs. */
--     
--     static uid_t euid, ruid;
--     
--     
--     /* Restore the effective UID to its original value. */
--     
--     void
--     do_setuid (void)
--     {
--       int status;
--     
--     #ifdef _POSIX_SAVED_IDS
--       status = setuid (euid);
--     #else
--       status = setreuid (ruid, euid);
--     #endif
--       if (status < 0) {
--         fprintf (stderr, "Couldn't set uid.\n");
--         exit (status);
--         }
--     }
--     /* Set the effective UID to the real UID. */
--     
--     void
--     undo_setuid (void)
--     {
--       int status;
--     
--     #ifdef _POSIX_SAVED_IDS
--       status = setuid (ruid);
--     #else
--       status = setreuid (euid, ruid);
--     #endif
--       if (status < 0) {
--         fprintf (stderr, "Couldn't set uid.\n");
--         exit (status);
--         }
--     }
--     
--     /* Main program. */
--     
--     int
--     main (void)
--     {
--       /* Save the real and effective user IDs.  */
--       ruid = getuid ();
--       euid = geteuid ();
--       undo_setuid ();
--     
--       /* Do the game and record the score.  */
--       ...
--     }
--
--   Notice how the first thing the `main' function does is to set the
--effective user ID back to the real user ID.  This is so that any other
--file accesses that are performed while the user is playing the game use
--the real user ID for determining permissions.  Only when the program
--needs to open the scores file does it switch back to the original
--effective user ID, like this:
--
--     /* Record the score. */
--     
--     int
--     record_score (int score)
--     {
--       FILE *stream;
--       char *myname;
--     
--       /* Open the scores file. */
--       do_setuid ();
--       stream = fopen (SCORES_FILE, "a");
--       undo_setuid ();
--     /* Write the score to the file. */
--       if (stream)
--         {
--           myname = cuserid (NULL);
--           if (score < 0)
--             fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
--           else
--             fprintf (stream, "%10s: %d feet.\n", myname, score);
--           fclose (stream);
--           return 0;
--         }
--       else
--         return -1;
--     }
--
--
--File: libc.info,  Node: Tips for Setuid,  Next: Who Logged In,  Prev: Setuid 
Program Example,  Up: Users and Groups
--
--Tips for Writing Setuid Programs
--================================
--
--   It is easy for setuid programs to give the user access that isn't
--intended--in fact, if you want to avoid this, you need to be careful.
--Here are some guidelines for preventing unintended access and
--minimizing its consequences when it does occur:
--
--   * Don't have `setuid' programs with privileged user IDs such as
--     `root' unless it is absolutely necessary.  If the resource is
--     specific to your particular program, it's better to define a new,
--     nonprivileged user ID or group ID just to manage that resource.
--
--   * Be cautious about using the `system' and `exec' functions in
--     combination with changing the effective user ID.  Don't let users
--     of your program execute arbitrary programs under a changed user ID.
--     Executing a shell is especially bad news.  Less obviously, the
--     `execlp' and `execvp' functions are a potential risk (since the
--     program they execute depends on the user's `PATH' environment
--     variable).
--
--     If you must `exec' another program under a changed ID, specify an
--     absolute file name (*note File Name Resolution::.) for the
--     executable, and make sure that the protections on that executable
--     and *all* containing directories are such that ordinary users
--     cannot replace it with some other program.
--
--   * Only use the user ID controlling the resource in the part of the
--     program that actually uses that resource.  When you're finished
--     with it, restore the effective user ID back to the actual user's
--     user ID.  *Note Enable/Disable Setuid::.
--
--   * If the `setuid' part of your program needs to access other files
--     besides the controlled resource, it should verify that the real
--     user would ordinarily have permission to access those files.  You
--     can use the `access' function (*note Access Permission::.) to
--     check this; it uses the real user and group IDs, rather than the
--     effective IDs.
--
--
--File: libc.info,  Node: Who Logged In,  Next: User Database,  Prev: Tips for 
Setuid,  Up: Users and Groups
--
--Identifying Who Logged In
--=========================
--
--   You can use the functions listed in this section to determine the
--login name of the user who is running a process, and the name of the
--user who logged in the current session.  See also the function `getuid'
--and friends (*note Reading Persona::.).
--
--   The `getlogin' function is declared in `unistd.h', while `cuserid'
--and `L_cuserid' are declared in `stdio.h'.
--
-- - Function: char * getlogin (void)
--     The `getlogin' function returns a pointer to a string containing
--     the name of the user logged in on the controlling terminal of the
--     process, or a null pointer if this information cannot be
--     determined.  The string is statically allocated and might be
--     overwritten on subsequent calls to this function or to `cuserid'.
--
-- - Function: char * cuserid (char *STRING)
--     The `cuserid' function returns a pointer to a string containing a
--     user name associated with the effective ID of the process.  If
--     STRING is not a null pointer, it should be an array that can hold
--     at least `L_cuserid' characters; the string is returned in this
--     array.  Otherwise, a pointer to a string in a static area is
--     returned.  This string is statically allocated and might be
--     overwritten on subsequent calls to this function or to `getlogin'.
--
--     The use of this function is deprecated since it is marked to be
--     withdrawn in XPG4.2 and it is already removed in POSIX.1.
--
-- - Macro: int L_cuserid
--     An integer constant that indicates how long an array you might
--     need to store a user name.
--
--   These functions let your program identify positively the user who is
--running or the user who logged in this session.  (These can differ when
--setuid programs are involved; *Note Process Persona::.)  The user cannot
--do anything to fool these functions.
--
--   For most purposes, it is more useful to use the environment variable
--`LOGNAME' to find out who the user is.  This is more flexible precisely
--because the user can set `LOGNAME' arbitrarily.  *Note Standard
--Environment::.
--
--
--File: libc.info,  Node: User Database,  Next: Group Database,  Prev: Who 
Logged In,  Up: Users and Groups
--
--User Database
--=============
--
--   This section describes all about how to search and scan the database
--of registered users.  The database itself is kept in the file
--`/etc/passwd' on most systems, but on some systems a special network
--server gives access to it.
--
--* Menu:
--
--* User Data Structure::         What each user record contains.
--* Lookup User::                 How to look for a particular user.
--* Scanning All Users::          Scanning the list of all users, one by one.
--* Writing a User Entry::        How a program can rewrite a user's record.
--
--
--File: libc.info,  Node: User Data Structure,  Next: Lookup User,  Prev: User 
Database,  Up: User Database
--
--The Data Structure that Describes a User
------------------------------------------
--
--   The functions and data structures for accessing the system user
--database are declared in the header file `pwd.h'.
--
-- - Data Type: struct passwd
--     The `passwd' data structure is used to hold information about
--     entries in the system user data base.  It has at least the
--     following members:
--
--    `char *pw_name'
--          The user's login name.
--
--    `char *pw_passwd.'
--          The encrypted password string.
--
--    `uid_t pw_uid'
--          The user ID number.
--
--    `gid_t pw_gid'
--          The user's default group ID number.
--
--    `char *pw_gecos'
--          A string typically containing the user's real name, and
--          possibly other information such as a phone number.
--
--    `char *pw_dir'
--          The user's home directory, or initial working directory.
--          This might be a null pointer, in which case the
--          interpretation is system-dependent.
--
--    `char *pw_shell'
--          The user's default shell, or the initial program run when the
--          user logs in.  This might be a null pointer, indicating that
--          the system default should be used.
--
--
--File: libc.info,  Node: Lookup User,  Next: Scanning All Users,  Prev: User 
Data Structure,  Up: User Database
--
--Looking Up One User
---------------------
--
--   You can search the system user database for information about a
--specific user using `getpwuid' or `getpwnam'.  These functions are
--declared in `pwd.h'.
--
-- - Function: struct passwd * getpwuid (uid_t UID)
--     This function returns a pointer to a statically-allocated structure
--     containing information about the user whose user ID is UID.  This
--     structure may be overwritten on subsequent calls to `getpwuid'.
--
--     A null pointer value indicates there is no user in the data base
--     with user ID UID.
--
-- - Function: int getpwuid_r (uid_t UID, struct passwd *RESULT_BUF, char
--          *BUFFER, size_t BUFLEN, struct passwd **RESULT)
--     This function is similar to `getpwuid' in that is returns
--     information about the user whose user ID is UID.  But the result
--     is not placed in a static buffer.  Instead the user supplied
--     structure pointed to by RESULT_BUF is filled with the information.
--     The first BUFLEN bytes of the additional buffer pointed to by
--     BUFFER are used to contain additional information, normally
--     strings which are pointed to by the elements of the result
--     structure.
--
--     If the return value is `0' the pointer returned in RESULT points
--     to the record which contains the wanted data (i.e., RESULT
--     contains the value RESULT_BUF).  In case the return value is non
--     null there is no user in the data base with user ID UID or the
--     buffer BUFFER is too small to contain all the needed information.
--     In the later case the global ERRNO variable is set to `ERANGE'.
--
-- - Function: struct passwd * getpwnam (const char *NAME)
--     This function returns a pointer to a statically-allocated structure
--     containing information about the user whose user name is NAME.
--     This structure may be overwritten on subsequent calls to
--     `getpwnam'.
--
--     A null pointer value indicates there is no user named NAME.
--
-- - Function: int getpwnam_r (const char *NAME, struct passwd
--          *RESULT_BUF, char *BUFFER, size_t BUFLEN, struct passwd
--          **RESULT)
--     This function is similar to `getpwnam' in that is returns
--     information about the user whose user name is NAME.  But the result
--     is not placed in a static buffer.  Instead the user supplied
--     structure pointed to by RESULT_BUF is filled with the information.
--     The first BUFLEN bytes of the additional buffer pointed to by
--     BUFFER are used to contain additional information, normally
--     strings which are pointed to by the elements of the result
--     structure.
--
--     If the return value is `0' the pointer returned in RESULT points
--     to the record which contains the wanted data (i.e., RESULT
--     contains the value RESULT_BUF).  In case the return value is non
--     null there is no user in the data base with user name NAME or the
--     buffer BUFFER is too small to contain all the needed information.
--     In the later case the global ERRNO variable is set to `ERANGE'.
--
--
--File: libc.info,  Node: Scanning All Users,  Next: Writing a User Entry,  
Prev: Lookup User,  Up: User Database
--
--Scanning the List of All Users
--------------------------------
--
--   This section explains how a program can read the list of all users in
--the system, one user at a time.  The functions described here are
--declared in `pwd.h'.
--
--   You can use the `fgetpwent' function to read user entries from a
--particular file.
--
-- - Function: struct passwd * fgetpwent (FILE *STREAM)
--     This function reads the next user entry from STREAM and returns a
--     pointer to the entry.  The structure is statically allocated and is
--     rewritten on subsequent calls to `fgetpwent'.  You must copy the
--     contents of the structure if you wish to save the information.
--
--     This stream must correspond to a file in the same format as the
--     standard password database file.  This function comes from System
--     V.
--
-- - Function: int fgetpwent_r (FILE *STREAM, struct passwd *RESULT_BUF,
--          char *BUFFER, size_t BUFLEN, struct passwd **RESULT)
--     This function is similar to `fgetpwent' in that it reads the next
--     user entry from STREAM.  But the result is returned in the
--     structure pointed to by RESULT_BUF.  The first BUFLEN bytes of the
--     additional buffer pointed to by BUFFER are used to contain
--     additional information, normally strings which are pointed to by
--     the elements of the result structure.
--
--     This stream must correspond to a file in the same format as the
--     standard password database file.
--
--     If the function returns null RESULT points to the structure with
--     the wanted data (normally this is in RESULT_BUF).  If errors
--     occurred the return value is non-null and RESULT contains a null
--     pointer.
--
--   The way to scan all the entries in the user database is with
--`setpwent', `getpwent', and `endpwent'.
--
-- - Function: void setpwent (void)
--     This function initializes a stream which `getpwent' and
--     `getpwent_r' use to read the user database.
--
-- - Function: struct passwd * getpwent (void)
--     The `getpwent' function reads the next entry from the stream
--     initialized by `setpwent'.  It returns a pointer to the entry.  The
--     structure is statically allocated and is rewritten on subsequent
--     calls to `getpwent'.  You must copy the contents of the structure
--     if you wish to save the information.
--
--     A null pointer is returned in case no further entry is available.
--
-- - Function: int getpwent_r (struct passwd *RESULT_BUF, char *BUFFER,
--          int BUFLEN, struct passwd **RESULT)
--     This function is similar to `getpwent' in that it returns the next
--     entry from the stream initialized by `setpwent'.  But in contrast
--     to the `getpwent' function this function is reentrant since the
--     result is placed in the user supplied structure pointed to by
--     RESULT_BUF.  Additional data, normally the strings pointed to by
--     the elements of the result structure, are placed in the additional
--     buffer or length BUFLEN starting at BUFFER.
--
--     If the function returns zero RESULT points to the structure with
--     the wanted data (normally this is in RESULT_BUF).  If errors
--     occurred the return value is non-zero and RESULT contains a null
--     pointer.
--
-- - Function: void endpwent (void)
--     This function closes the internal stream used by `getpwent' or
--     `getpwent_r'.
--
--
--File: libc.info,  Node: Writing a User Entry,  Prev: Scanning All Users,  Up: 
User Database
--
--Writing a User Entry
----------------------
--
-- - Function: int putpwent (const struct passwd *P, FILE *STREAM)
--     This function writes the user entry `*P' to the stream STREAM, in
--     the format used for the standard user database file.  The return
--     value is zero on success and nonzero on failure.
--
--     This function exists for compatibility with SVID.  We recommend
--     that you avoid using it, because it makes sense only on the
--     assumption that the `struct passwd' structure has no members
--     except the standard ones; on a system which merges the traditional
--     Unix data base with other extended information about users, adding
--     an entry using this function would inevitably leave out much of
--     the important information.
--
--     The function `putpwent' is declared in `pwd.h'.
--
--
--File: libc.info,  Node: Group Database,  Next: Netgroup Database,  Prev: User 
Database,  Up: Users and Groups
--
--Group Database
--==============
--
--   This section describes all about how to search and scan the database
--of registered groups.  The database itself is kept in the file
--`/etc/group' on most systems, but on some systems a special network
--service provides access to it.
--
--* Menu:
--
--* Group Data Structure::        What each group record contains.
--* Lookup Group::                How to look for a particular group.
--* Scanning All Groups::         Scanning the list of all groups.
--
--
--File: libc.info,  Node: Group Data Structure,  Next: Lookup Group,  Prev: 
Group Database,  Up: Group Database
--
--The Data Structure for a Group
--------------------------------
--
--   The functions and data structures for accessing the system group
--database are declared in the header file `grp.h'.
--
-- - Data Type: struct group
--     The `group' structure is used to hold information about an entry in
--     the system group database.  It has at least the following members:
--
--    `char *gr_name'
--          The name of the group.
--
--    `gid_t gr_gid'
--          The group ID of the group.
--
--    `char **gr_mem'
--          A vector of pointers to the names of users in the group.
--          Each user name is a null-terminated string, and the vector
--          itself is terminated by a null pointer.
--
--
--File: libc.info,  Node: Lookup Group,  Next: Scanning All Groups,  Prev: 
Group Data Structure,  Up: Group Database
--
--Looking Up One Group
----------------------
--
--   You can search the group database for information about a specific
--group using `getgrgid' or `getgrnam'.  These functions are declared in
--`grp.h'.
--
-- - Function: struct group * getgrgid (gid_t GID)
--     This function returns a pointer to a statically-allocated structure
--     containing information about the group whose group ID is GID.
--     This structure may be overwritten by subsequent calls to
--     `getgrgid'.
--
--     A null pointer indicates there is no group with ID GID.
--
-- - Function: int getgrgid_r (gid_t GID, struct group *RESULT_BUF, char
--          *BUFFER, size_t BUFLEN, struct group **RESULT)
--     This function is similar to `getgrgid' in that is returns
--     information about the group whose group ID is GID.  But the result
--     is not placed in a static buffer.  Instead the user supplied
--     structure pointed to by RESULT_BUF is filled with the information.
--     The first BUFLEN bytes of the additional buffer pointed to by
--     BUFFER are used to contain additional information, normally
--     strings which are pointed to by the elements of the result
--     structure.
--
--     If the return value is `0' the pointer returned in RESULT points
--     to the record which contains the wanted data (i.e., RESULT
--     contains the value RESULT_BUF).  If the return value is non-zero
--     there is no group in the data base with group ID GID or the buffer
--     BUFFER is too small to contain all the needed information.  In the
--     later case the global ERRNO variable is set to `ERANGE'.
--
-- - Function: struct group * getgrnam (const char *NAME)
--     This function returns a pointer to a statically-allocated structure
--     containing information about the group whose group name is NAME.
--     This structure may be overwritten by subsequent calls to
--     `getgrnam'.
--
--     A null pointer indicates there is no group named NAME.
--
-- - Function: int getgrnam_r (const char *NAME, struct group
--          *RESULT_BUF, char *BUFFER, size_t BUFLEN, struct group
--          **RESULT)
--     This function is similar to `getgrnam' in that is returns
--     information about the group whose group name is NAME.  But the
--     result is not placed in a static buffer.  Instead the user
--     supplied structure pointed to by RESULT_BUF is filled with the
--     information.  The first BUFLEN bytes of the additional buffer
--     pointed to by BUFFER are used to contain additional information,
--     normally strings which are pointed to by the elements of the
--     result structure.
--
--     If the return value is `0' the pointer returned in RESULT points
--     to the record which contains the wanted data (i.e., RESULT
--     contains the value RESULT_BUF).  If the return value is non-zero
--     there is no group in the data base with group name NAME or the
--     buffer BUFFER is too small to contain all the needed information.
--     In the later case the global ERRNO variable is set to `ERANGE'.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-26 
glibc-2.0.1/manual/libc.info-26
---- ../glibc-2.0.1/manual/libc.info-26 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-26    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1240 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Scanning All Groups,  Prev: Lookup Group,  Up: Group 
Database
--
--Scanning the List of All Groups
---------------------------------
--
--   This section explains how a program can read the list of all groups
--in the system, one group at a time.  The functions described here are
--declared in `grp.h'.
--
--   You can use the `fgetgrent' function to read group entries from a
--particular file.
--
-- - Function: struct group * fgetgrent (FILE *STREAM)
--     The `fgetgrent' function reads the next entry from STREAM.  It
--     returns a pointer to the entry.  The structure is statically
--     allocated and is rewritten on subsequent calls to `fgetgrent'.  You
--     must copy the contents of the structure if you wish to save the
--     information.
--
--     The stream must correspond to a file in the same format as the
--     standard group database file.
--
-- - Function: int fgetgrent_r (FILE *STREAM, struct group *RESULT_BUF,
--          char *BUFFER, size_t BUFLEN, struct group **RESULT)
--     This function is similar to `fgetgrent' in that it reads the next
--     user entry from STREAM.  But the result is returned in the
--     structure pointed to by RESULT_BUF.  The first BUFLEN bytes of the
--     additional buffer pointed to by BUFFER are used to contain
--     additional information, normally strings which are pointed to by
--     the elements of the result structure.
--
--     This stream must correspond to a file in the same format as the
--     standard group database file.
--
--     If the function returns zero RESULT points to the structure with
--     the wanted data (normally this is in RESULT_BUF).  If errors
--     occurred the return value is non-zero and RESULT contains a null
--     pointer.
--
--   The way to scan all the entries in the group database is with
--`setgrent', `getgrent', and `endgrent'.
--
-- - Function: void setgrent (void)
--     This function initializes a stream for reading from the group data
--     base.  You use this stream by calling `getgrent' or `getgrent_r'.
--
-- - Function: struct group * getgrent (void)
--     The `getgrent' function reads the next entry from the stream
--     initialized by `setgrent'.  It returns a pointer to the entry.  The
--     structure is statically allocated and is rewritten on subsequent
--     calls to `getgrent'.  You must copy the contents of the structure
--     if you wish to save the information.
--
-- - Function: int getgrent_r (struct group *RESULT_BUF, char *BUFFER,
--          size_t BUFLEN, struct group **RESULT)
--     This function is similar to `getgrent' in that it returns the next
--     entry from the stream initialized by `setgrent'.  But in contrast
--     to the `getgrent' function this function is reentrant since the
--     result is placed in the user supplied structure pointed to by
--     RESULT_BUF.  Additional data, normally the strings pointed to by
--     the elements of the result structure, are placed in the additional
--     buffer or length BUFLEN starting at BUFFER.
--
--     If the function returns zero RESULT points to the structure with
--     the wanted data (normally this is in RESULT_BUF).  If errors
--     occurred the return value is non-zero and RESULT contains a null
--     pointer.
--
-- - Function: void endgrent (void)
--     This function closes the internal stream used by `getgrent' or
--     `getgrent_r'.
--
--
--File: libc.info,  Node: Netgroup Database,  Next: Database Example,  Prev: 
Group Database,  Up: Users and Groups
--
--Netgroup Database
--=================
--
--* Menu:
--
--* Netgroup Data::                  Data in the Netgroup database and where
--                                   it comes from.
--* Lookup Netgroup::                How to look for a particular netgroup.
--* Netgroup Membership::            How to test for netgroup membership.
--
--
--File: libc.info,  Node: Netgroup Data,  Next: Lookup Netgroup,  Prev: 
Netgroup Database,  Up: Netgroup Database
--
--Netgroup Data
---------------
--
--   Sometimes it is useful group users according to other criterias like
--the ones used in the *Note Group Database::.  E.g., it is useful to
--associate a certain group of users with a certain machine.  On the
--other hand grouping of host names is not supported so far.
--
--   In Sun Microsystems SunOS appeared a new kind of database, the
--netgroup database.  It allows to group hosts, users, and domain freely,
--giving them individual names.  More concrete: a netgroup is a list of
--triples consisting of a host name, a user name, and a domain name,
--where any of the entries can be a wildcard entry, matching all inputs.
--A last possibility is that names of other netgroups can also be given
--in the list specifying a netgroup.  So one can construct arbitrary
--hierarchies without loops.
--
--   Sun's implementation allows netgroups only for the `nis' or
--`nisplus' service *note Services in the NSS configuration::..  The
--implementation in the GNU C library has no such restriction.  An entry
--in either of the input services must have the following form:
--
--     GROUPNAME ( GROUPNAME | `('HOSTNAME`,'USERNAME`,'`domainname'`)' )+
--
--   Any of the fields in the triple can be empty which means anything
--matches.  While describing the functions we will see that the opposite
--case is useful as well.  I.e., there may be entries which will not
--match any input.  For entries like a name consisting of the single
--character `-' shall be used.
--
--
--File: libc.info,  Node: Lookup Netgroup,  Next: Netgroup Membership,  Prev: 
Netgroup Data,  Up: Netgroup Database
--
--Looking up one Netgroup
-------------------------
--
--   The lookup functions for netgroups are a bit different to all other
--system database handling functions.  Since a single netgroup can contain
--many entries a two-step process is needed.  First a single netgroup is
--selected and then one can iterate over all entries in this netgroup.
--These functions are declared in `netdb.h'.
--
-- - Function: int setnetgrent (const char *NETGROUP)
--     A call to this function initializes the internal state of the
--     library to allow following calls of the `getnetgrent' iterate over
--     all entries in the netgroup with name NETGROUP.
--
--     When the call is successful (i.e., when a netgroup with this name
--     exist) the return value is `1'.  When the return value is `0' no
--     netgroup of this name is known or some other error occurred.
--
--   It is important to remember that there is only one single state for
--iterating the netgroups.  Even if the programmer uses the
--`getnetgrent_r' function the result is not really reentrant since
--always only one single netgroup at a time can be processed.  If the
--program needs to process more than one netgroup simultaneously she must
--protect this by using external locking.  This problem was introduced in
--the original netgroups implementation in SunOS and since we must stay
--compatible it is not possible to change this.
--
--   Some other functions also use the netgroups state.  Currently these
--are the `innetgr' function and parts of the implementation of the
--`compat' service part of the NSS implementation.
--
-- - Function: int getnetgrent (char **HOSTP, char **USERP, char
--          **DOMAINP)
--     This function returns the next unprocessed entry of the currently
--     selected netgroup.  The string pointers, which addresses are
--     passed in the arguments HOSTP, USERP, and DOMAINP, will contain
--     after a successful call pointers to appropriate strings.  If the
--     string in the next entry is empty the pointer has the value `NULL'.
--     The returned string pointers are only valid unless no of the
--     netgroup related functions are called.
--
--     The return value is `1' if the next entry was successfully read.  A
--     value of `0' means no further entries exist or internal errors
--     occurred.
--
-- - Function: int getnetgrent_r (char **HOSTP, char **USERP, char
--          **DOMAINP, char *BUFFER, int BUFLEN)
--     This function is similar to `getnetgrent' with only one exception:
--     the strings the three string pointers HOSTP, USERP, and DOMAINP
--     point to, are placed in the buffer of BUFLEN bytes starting at
--     BUFFER.  This means the returned values are valid even after other
--     netgroup related functions are called.
--
--     The return value is `1' if the next entry was successfully read and
--     the buffer contains enough room to place the strings in it.  `0' is
--     returned in case no more entries are found, the buffer is too
--     small, or internal errors occurred.
--
--     This function is a GNU extension.  The original implementation in
--     the SunOS libc does not provide this function.
--
-- - Function: void endnetgrent (void)
--     This function free all buffers which were allocated to process the
--     last selected netgroup.  As a result all string pointers returned
--     by calls to `getnetgrent' are invalid afterwards.
--
--
--File: libc.info,  Node: Netgroup Membership,  Prev: Lookup Netgroup,  Up: 
Netgroup Database
--
--Testing for Netgroup Membership
---------------------------------
--
--   It is often not necessary to scan the whole netgroup since often the
--only interesting question is whether a given entry is part of the
--selected netgroup.
--
-- - Function: int innetgr (const char *NETGROUP, const char *HOST, const
--          char *USER, const char *DOMAIN)
--     This function tests whether the triple specified by the parameters
--     HOSTP, USERP, and DOMAINP is part of the netgroup NETGROUP.  Using
--     this function has the advantage that
--
--       1. no other netgroup function can use the global netgroup state
--          since internal locking is used and
--
--       2. the function is implemented more efficiently than successive
--          calls to the other `set'/`get'/`endnetgrent' functions.
--
--     Any of the pointers HOSTP, USERP, and DOMAINP can be `NULL' which
--     means any value is excepted in this position.  This is also true
--     for the name `-' which should not match any other string otherwise.
--
--     The return value is `1' if an entry matching the given triple is
--     found in the netgroup.  The return value is `0' if the netgroup
--     itself is not found, the netgroup does not contain the triple or
--     internal errors occurred.
--
--
--File: libc.info,  Node: Database Example,  Prev: Netgroup Database,  Up: 
Users and Groups
--
--User and Group Database Example
--===============================
--
--   Here is an example program showing the use of the system database
--inquiry functions.  The program prints some information about the user
--running the program.
--
--     #include <grp.h>
--     #include <pwd.h>
--     #include <sys/types.h>
--     #include <unistd.h>
--     #include <stdlib.h>
--     
--     int
--     main (void)
--     {
--       uid_t me;
--       struct passwd *my_passwd;
--       struct group *my_group;
--       char **members;
--     
--       /* Get information about the user ID. */
--       me = getuid ();
--       my_passwd = getpwuid (me);
--       if (!my_passwd)
--         {
--           printf ("Couldn't find out about user %d.\n", (int) me);
--           exit (EXIT_FAILURE);
--         }
--     
--       /* Print the information. */
--       printf ("I am %s.\n", my_passwd->pw_gecos);
--       printf ("My login name is %s.\n", my_passwd->pw_name);
--       printf ("My uid is %d.\n", (int) (my_passwd->pw_uid));
--       printf ("My home directory is %s.\n", my_passwd->pw_dir);
--       printf ("My default shell is %s.\n", my_passwd->pw_shell);
--     
--       /* Get information about the default group ID. */
--       my_group = getgrgid (my_passwd->pw_gid);
--       if (!my_group)
--         {
--           printf ("Couldn't find out about group %d.\n",
--                   (int) my_passwd->pw_gid);
--           exit (EXIT_FAILURE);
--         }
--     
--       /* Print the information. */
--       printf ("My default group is %s (%d).\n",
--               my_group->gr_name, (int) (my_passwd->pw_gid));
--       printf ("The members of this group are:\n");
--       members = my_group->gr_mem;
--       while (*members)
--         {
--           printf ("  %s\n", *(members));
--           members++;
--         }
--     
--       return EXIT_SUCCESS;
--     }
--
--   Here is some output from this program:
--
--     I am Throckmorton Snurd.
--     My login name is snurd.
--     My uid is 31093.
--     My home directory is /home/fsg/snurd.
--     My default shell is /bin/sh.
--     My default group is guest (12).
--     The members of this group are:
--       friedman
--       tami
--
--
--File: libc.info,  Node: System Information,  Next: System Configuration,  
Prev: Users and Groups,  Up: Top
--
--System Information
--******************
--
--   This chapter describes functions that return information about the
--particular machine that is in use--the type of hardware, the type of
--software, and the individual machine's name.
--
--* Menu:
--
--* Host Identification::         Determining the name of the machine.
--* Hardware/Software Type ID::   Determining the hardware type of the
--                                 machine and what operating system it is
--                                 running.
--
--
--File: libc.info,  Node: Host Identification,  Next: Hardware/Software Type 
ID,  Up: System Information
--
--Host Identification
--===================
--
--   This section explains how to identify the particular machine that
--your program is running on.  The identification of a machine consists
--of its Internet host name and Internet address; see *Note Internet
--Namespace::.  The host name should always be a fully qualified domain
--name, like `crispy-wheats-n-chicken.ai.mit.edu', not a simple name like
--just `crispy-wheats-n-chicken'.
--
--   Prototypes for these functions appear in `unistd.h'.  The shell
--commands `hostname' and `hostid' work by calling them.
--
-- - Function: int gethostname (char *NAME, size_t SIZE)
--     This function returns the name of the host machine in the array
--     NAME.  The SIZE argument specifies the size of this array, in
--     bytes.
--
--     The return value is `0' on success and `-1' on failure.  In the
--     GNU C library, `gethostname' fails if SIZE is not large enough;
--     then you can try again with a larger array.  The following `errno'
--     error condition is defined for this function:
--
--    `ENAMETOOLONG'
--          The SIZE argument is less than the size of the host name plus
--          one.
--
--     On some systems, there is a symbol for the maximum possible host
--     name length: `MAXHOSTNAMELEN'.  It is defined in `sys/param.h'.
--     But you can't count on this to exist, so it is cleaner to handle
--     failure and try again.
--
--     `gethostname' stores the beginning of the host name in NAME even
--     if the host name won't entirely fit.  For some purposes, a
--     truncated host name is good enough.  If it is, you can ignore the
--     error code.
--
-- - Function: int sethostname (const char *NAME, size_t LENGTH)
--     The `sethostname' function sets the name of the host machine to
--     NAME, a string with length LENGTH.  Only privileged processes are
--     allowed to do this.  Usually it happens just once, at system boot
--     time.
--
--     The return value is `0' on success and `-1' on failure.  The
--     following `errno' error condition is defined for this function:
--
--    `EPERM'
--          This process cannot set the host name because it is not
--          privileged.
--
-- - Function: long int gethostid (void)
--     This function returns the "host ID" of the machine the program is
--     running on.  By convention, this is usually the primary Internet
--     address of that machine, converted to a `long int'.  However, some
--     systems it is a meaningless but unique number which is hard-coded
--     for each machine.
--
-- - Function: int sethostid (long int ID)
--     The `sethostid' function sets the "host ID" of the host machine to
--     ID.  Only privileged processes are allowed to do this.  Usually it
--     happens just once, at system boot time.
--
--     The return value is `0' on success and `-1' on failure.  The
--     following `errno' error condition is defined for this function:
--
--    `EPERM'
--          This process cannot set the host name because it is not
--          privileged.
--
--    `ENOSYS'
--          The operating system does not support setting the host ID.
--          On some systems, the host ID is a meaningless but unique
--          number hard-coded for each machine.
--
--
--File: libc.info,  Node: Hardware/Software Type ID,  Prev: Host 
Identification,  Up: System Information
--
--Hardware/Software Type Identification
--=====================================
--
--   You can use the `uname' function to find out some information about
--the type of computer your program is running on.  This function and the
--associated data type are declared in the header file `sys/utsname.h'.
--
-- - Data Type: struct utsname
--     The `utsname' structure is used to hold information returned by
--     the `uname' function.  It has the following members:
--
--    `char sysname[]'
--          This is the name of the operating system in use.
--
--    `char nodename[]'
--          This is the network name of this particular computer.  In the
--          GNU library, the value is the same as that returned by
--          `gethostname'; see *Note Host Identification::.
--
--    `char release[]'
--          This is the current release level of the operating system
--          implementation.
--
--    `char version[]'
--          This is the current version level within the release of the
--          operating system.
--
--    `char machine[]'
--          This is a description of the type of hardware that is in use.
--
--          Some systems provide a mechanism to interrogate the kernel
--          directly for this information.  On systems without such a
--          mechanism, the GNU C library fills in this field based on the
--          configuration name that was specified when building and
--          installing the library.
--
--          GNU uses a three-part name to describe a system
--          configuration; the three parts are CPU, MANUFACTURER and
--          SYSTEM-TYPE, and they are separated with dashes.  Any
--          possible combination of three names is potentially
--          meaningful, but most such combinations are meaningless in
--          practice and even the meaningful ones are not necessarily
--          supported by any particular GNU program.
--
--          Since the value in `machine' is supposed to describe just the
--          hardware, it consists of the first two parts of the
--          configuration name: `CPU-MANUFACTURER'.  For example, it
--          might be one of these:
--
--               `"sparc-sun"', `"i386-ANYTHING"', `"m68k-hp"',
--               `"m68k-sony"', `"m68k-sun"', `"mips-dec"'
--
-- - Function: int uname (struct utsname *INFO)
--     The `uname' function fills in the structure pointed to by INFO
--     with information about the operating system and host machine.  A
--     non-negative value indicates that the data was successfully stored.
--
--     `-1' as the value indicates an error.  The only error possible is
--     `EFAULT', which we normally don't mention as it is always a
--     possibility.
--
--
--File: libc.info,  Node: System Configuration,  Next: Language Features,  
Prev: System Information,  Up: Top
--
--System Configuration Parameters
--*******************************
--
--   The functions and macros listed in this chapter give information
--about configuration parameters of the operating system--for example,
--capacity limits, presence of optional POSIX features, and the default
--path for executable files (*note String Parameters::.).
--
--* Menu:
--
--* General Limits::           Constants and functions that describe
--                              various process-related limits that have
--                              one uniform value for any given machine.
--* System Options::           Optional POSIX features.
--* Version Supported::        Version numbers of POSIX.1 and POSIX.2.
--* Sysconf::                  Getting specific configuration values
--                                of general limits and system options.
--* Minimums::                 Minimum values for general limits.
--
--* Limits for Files::         Size limitations that pertain to individual 
files.
--                                These can vary between file systems
--                                or even from file to file.
--* Options for Files::        Optional features that some files may support.
--* File Minimums::            Minimum values for file limits.
--* Pathconf::                 Getting the limit values for a particular file.
--
--* Utility Limits::           Capacity limits of some POSIX.2 utility programs.
--* Utility Minimums::         Minimum allowable values of those limits.
--
--* String Parameters::        Getting the default search path.
--
--
--File: libc.info,  Node: General Limits,  Next: System Options,  Up: System 
Configuration
--
--General Capacity Limits
--=======================
--
--   The POSIX.1 and POSIX.2 standards specify a number of parameters that
--describe capacity limitations of the system.  These limits can be fixed
--constants for a given operating system, or they can vary from machine to
--machine.  For example, some limit values may be configurable by the
--system administrator, either at run time or by rebuilding the kernel,
--and this should not require recompiling application programs.
--
--   Each of the following limit parameters has a macro that is defined in
--`limits.h' only if the system has a fixed, uniform limit for the
--parameter in question.  If the system allows different file systems or
--files to have different limits, then the macro is undefined; use
--`sysconf' to find out the limit that applies at a particular time on a
--particular machine.  *Note Sysconf::.
--
--   Each of these parameters also has another macro, with a name starting
--with `_POSIX', which gives the lowest value that the limit is allowed
--to have on *any* POSIX system.  *Note Minimums::.
--
-- - Macro: int ARG_MAX
--     If defined, the unvarying maximum combined length of the ARGV and
--     ENVIRON arguments that can be passed to the `exec' functions.
--
-- - Macro: int CHILD_MAX
--     If defined, the unvarying maximum number of processes that can
--     exist with the same real user ID at any one time.  In BSD and GNU,
--     this is controlled by the `RLIMIT_NPROC' resource limit; *note
--     Limits on Resources::..
--
-- - Macro: int OPEN_MAX
--     If defined, the unvarying maximum number of files that a single
--     process can have open simultaneously.  In BSD and GNU, this is
--     controlled by the `RLIMIT_NOFILE' resource limit; *note Limits on
--     Resources::..
--
-- - Macro: int STREAM_MAX
--     If defined, the unvarying maximum number of streams that a single
--     process can have open simultaneously.  *Note Opening Streams::.
--
-- - Macro: int TZNAME_MAX
--     If defined, the unvarying maximum length of a time zone name.
--     *Note Time Zone Functions::.
--
--   These limit macros are always defined in `limits.h'.
--
-- - Macro: int NGROUPS_MAX
--     The maximum number of supplementary group IDs that one process can
--     have.
--
--     The value of this macro is actually a lower bound for the maximum.
--     That is, you can count on being able to have that many
--     supplementary group IDs, but a particular machine might let you
--     have even more.  You can use `sysconf' to see whether a particular
--     machine will let you have more (*note Sysconf::.).
--
-- - Macro: int SSIZE_MAX
--     The largest value that can fit in an object of type `ssize_t'.
--     Effectively, this is the limit on the number of bytes that can be
--     read or written in a single operation.
--
--     This macro is defined in all POSIX systems because this limit is
--     never configurable.
--
-- - Macro: int RE_DUP_MAX
--     The largest number of repetitions you are guaranteed is allowed in
--     the construct `\{MIN,MAX\}' in a regular expression.
--
--     The value of this macro is actually a lower bound for the maximum.
--     That is, you can count on being able to have that many
--     repetitions, but a particular machine might let you have even
--     more.  You can use `sysconf' to see whether a particular machine
--     will let you have more (*note Sysconf::.).  And even the value
--     that `sysconf' tells you is just a lower bound--larger values
--     might work.
--
--     This macro is defined in all POSIX.2 systems, because POSIX.2 says
--     it should always be defined even if there is no specific imposed
--     limit.
--
--
--File: libc.info,  Node: System Options,  Next: Version Supported,  Prev: 
General Limits,  Up: System Configuration
--
--Overall System Options
--======================
--
--   POSIX defines certain system-specific options that not all POSIX
--systems support.  Since these options are provided in the kernel, not
--in the library, simply using the GNU C library does not guarantee any
--of these features is supported; it depends on the system you are using.
--
--   You can test for the availability of a given option using the macros
--in this section, together with the function `sysconf'.  The macros are
--defined only if you include `unistd.h'.
--
--   For the following macros, if the macro is defined in `unistd.h',
--then the option is supported.  Otherwise, the option may or may not be
--supported; use `sysconf' to find out.  *Note Sysconf::.
--
-- - Macro: int _POSIX_JOB_CONTROL
--     If this symbol is defined, it indicates that the system supports
--     job control.  Otherwise, the implementation behaves as if all
--     processes within a session belong to a single process group.
--     *Note Job Control::.
--
-- - Macro: int _POSIX_SAVED_IDS
--     If this symbol is defined, it indicates that the system remembers
--     the effective user and group IDs of a process before it executes an
--     executable file with the set-user-ID or set-group-ID bits set, and
--     that explicitly changing the effective user or group IDs back to
--     these values is permitted.  If this option is not defined, then if
--     a nonprivileged process changes its effective user or group ID to
--     the real user or group ID of the process, it can't change it back
--     again.  *Note Enable/Disable Setuid::.
--
--   For the following macros, if the macro is defined in `unistd.h',
--then its value indicates whether the option is supported.  A value of
--`-1' means no, and any other value means yes.  If the macro is not
--defined, then the option may or may not be supported; use `sysconf' to
--find out.  *Note Sysconf::.
--
-- - Macro: int _POSIX2_C_DEV
--     If this symbol is defined, it indicates that the system has the
--     POSIX.2 C compiler command, `c89'.  The GNU C library always
--     defines this as `1', on the assumption that you would not have
--     installed it if you didn't have a C compiler.
--
-- - Macro: int _POSIX2_FORT_DEV
--     If this symbol is defined, it indicates that the system has the
--     POSIX.2 Fortran compiler command, `fort77'.  The GNU C library
--     never defines this, because we don't know what the system has.
--
-- - Macro: int _POSIX2_FORT_RUN
--     If this symbol is defined, it indicates that the system has the
--     POSIX.2 `asa' command to interpret Fortran carriage control.  The
--     GNU C library never defines this, because we don't know what the
--     system has.
--
-- - Macro: int _POSIX2_LOCALEDEF
--     If this symbol is defined, it indicates that the system has the
--     POSIX.2 `localedef' command.  The GNU C library never defines
--     this, because we don't know what the system has.
--
-- - Macro: int _POSIX2_SW_DEV
--     If this symbol is defined, it indicates that the system has the
--     POSIX.2 commands `ar', `make', and `strip'.  The GNU C library
--     always defines this as `1', on the assumption that you had to have
--     `ar' and `make' to install the library, and it's unlikely that
--     `strip' would be absent when those are present.
--
--
--File: libc.info,  Node: Version Supported,  Next: Sysconf,  Prev: System 
Options,  Up: System Configuration
--
--Which Version of POSIX is Supported
--===================================
--
-- - Macro: long int _POSIX_VERSION
--     This constant represents the version of the POSIX.1 standard to
--     which the implementation conforms.  For an implementation
--     conforming to the 1990 POSIX.1 standard, the value is the integer
--     `199009L'.
--
--     `_POSIX_VERSION' is always defined (in `unistd.h') in any POSIX
--     system.
--
--     *Usage Note:* Don't try to test whether the system supports POSIX
--     by including `unistd.h' and then checking whether `_POSIX_VERSION'
--     is defined.  On a non-POSIX system, this will probably fail
--     because there is no `unistd.h'.  We do not know of *any* way you
--     can reliably test at compilation time whether your target system
--     supports POSIX or whether `unistd.h' exists.
--
--     The GNU C compiler predefines the symbol `__POSIX__' if the target
--     system is a POSIX system.  Provided you do not use any other
--     compilers on POSIX systems, testing `defined (__POSIX__)' will
--     reliably detect such systems.
--
-- - Macro: long int _POSIX2_C_VERSION
--     This constant represents the version of the POSIX.2 standard which
--     the library and system kernel support.  We don't know what value
--     this will be for the first version of the POSIX.2 standard,
--     because the value is based on the year and month in which the
--     standard is officially adopted.
--
--     The value of this symbol says nothing about the utilities
--     installed on the system.
--
--     *Usage Note:* You can use this macro to tell whether a POSIX.1
--     system library supports POSIX.2 as well.  Any POSIX.1 system
--     contains `unistd.h', so include that file and then test `defined
--     (_POSIX2_C_VERSION)'.
--
--
--File: libc.info,  Node: Sysconf,  Next: Minimums,  Prev: Version Supported,  
Up: System Configuration
--
--Using `sysconf'
--===============
--
--   When your system has configurable system limits, you can use the
--`sysconf' function to find out the value that applies to any particular
--machine.  The function and the associated PARAMETER constants are
--declared in the header file `unistd.h'.
--
--* Menu:
--
--* Sysconf Definition::        Detailed specifications of `sysconf'.
--* Constants for Sysconf::     The list of parameters `sysconf' can read.
--* Examples of Sysconf::       How to use `sysconf' and the parameter
--                               macros properly together.
--
--
--File: libc.info,  Node: Sysconf Definition,  Next: Constants for Sysconf,  
Up: Sysconf
--
--Definition of `sysconf'
-------------------------
--
-- - Function: long int sysconf (int PARAMETER)
--     This function is used to inquire about runtime system parameters.
--     The PARAMETER argument should be one of the `_SC_' symbols listed
--     below.
--
--     The normal return value from `sysconf' is the value you requested.
--     A value of `-1' is returned both if the implementation does not
--     impose a limit, and in case of an error.
--
--     The following `errno' error conditions are defined for this
--     function:
--
--    `EINVAL'
--          The value of the PARAMETER is invalid.
--
--
--File: libc.info,  Node: Constants for Sysconf,  Next: Examples of Sysconf,  
Prev: Sysconf Definition,  Up: Sysconf
--
--Constants for `sysconf' Parameters
------------------------------------
--
--   Here are the symbolic constants for use as the PARAMETER argument to
--`sysconf'.  The values are all integer constants (more specifically,
--enumeration type values).
--
--`_SC_ARG_MAX'
--     Inquire about the parameter corresponding to `ARG_MAX'.
--
--`_SC_CHILD_MAX'
--     Inquire about the parameter corresponding to `CHILD_MAX'.
--
--`_SC_OPEN_MAX'
--     Inquire about the parameter corresponding to `OPEN_MAX'.
--
--`_SC_STREAM_MAX'
--     Inquire about the parameter corresponding to `STREAM_MAX'.
--
--`_SC_TZNAME_MAX'
--     Inquire about the parameter corresponding to `TZNAME_MAX'.
--
--`_SC_NGROUPS_MAX'
--     Inquire about the parameter corresponding to `NGROUPS_MAX'.
--
--`_SC_JOB_CONTROL'
--     Inquire about the parameter corresponding to `_POSIX_JOB_CONTROL'.
--
--`_SC_SAVED_IDS'
--     Inquire about the parameter corresponding to `_POSIX_SAVED_IDS'.
--
--`_SC_VERSION'
--     Inquire about the parameter corresponding to `_POSIX_VERSION'.
--
--`_SC_CLK_TCK'
--     Inquire about the parameter corresponding to `CLOCKS_PER_SEC';
--     *note Basic CPU Time::..
--
--`_SC_2_C_DEV'
--     Inquire about whether the system has the POSIX.2 C compiler
--     command, `c89'.
--
--`_SC_2_FORT_DEV'
--     Inquire about whether the system has the POSIX.2 Fortran compiler
--     command, `fort77'.
--
--`_SC_2_FORT_RUN'
--     Inquire about whether the system has the POSIX.2 `asa' command to
--     interpret Fortran carriage control.
--
--`_SC_2_LOCALEDEF'
--     Inquire about whether the system has the POSIX.2 `localedef'
--     command.
--
--`_SC_2_SW_DEV'
--     Inquire about whether the system has the POSIX.2 commands `ar',
--     `make', and `strip'.
--
--`_SC_BC_BASE_MAX'
--     Inquire about the maximum value of `obase' in the `bc' utility.
--
--`_SC_BC_DIM_MAX'
--     Inquire about the maximum size of an array in the `bc' utility.
--
--`_SC_BC_SCALE_MAX'
--     Inquire about the maximum value of `scale' in the `bc' utility.
--
--`_SC_BC_STRING_MAX'
--     Inquire about the maximum size of a string constant in the `bc'
--     utility.
--
--`_SC_COLL_WEIGHTS_MAX'
--     Inquire about the maximum number of weights that can necessarily
--     be used in defining the collating sequence for a locale.
--
--`_SC_EXPR_NEST_MAX'
--     Inquire about the maximum number of expressions nested within
--     parentheses when using the `expr' utility.
--
--`_SC_LINE_MAX'
--     Inquire about the maximum size of a text line that the POSIX.2 text
--     utilities can handle.
--
--`_SC_EQUIV_CLASS_MAX'
--     Inquire about the maximum number of weights that can be assigned
--     to an entry of the `LC_COLLATE' category `order' keyword in a
--     locale definition.  The GNU C library does not presently support
--     locale definitions.
--
--`_SC_VERSION'
--     Inquire about the version number of POSIX.1 that the library and
--     kernel support.
--
--`_SC_2_VERSION'
--     Inquire about the version number of POSIX.2 that the system
--     utilities support.
--
--`_SC_PAGESIZE'
--     Inquire about the virtual memory page size of the machine.
--     `getpagesize' returns the same value.
--
--
--File: libc.info,  Node: Examples of Sysconf,  Prev: Constants for Sysconf,  
Up: Sysconf
--
--Examples of `sysconf'
-----------------------
--
--   We recommend that you first test for a macro definition for the
--parameter you are interested in, and call `sysconf' only if the macro
--is not defined.  For example, here is how to test whether job control
--is supported:
--
--     int
--     have_job_control (void)
--     {
--     #ifdef _POSIX_JOB_CONTROL
--       return 1;
--     #else
--       int value = sysconf (_SC_JOB_CONTROL);
--       if (value < 0)
--         /* If the system is that badly wedged,
--            there's no use trying to go on.  */
--         fatal (strerror (errno));
--       return value;
--     #endif
--     }
--
--   Here is how to get the value of a numeric limit:
--
--     int
--     get_child_max ()
--     {
--     #ifdef CHILD_MAX
--       return CHILD_MAX;
--     #else
--       int value = sysconf (_SC_CHILD_MAX);
--       if (value < 0)
--         fatal (strerror (errno));
--       return value;
--     #endif
--     }
--
--
--File: libc.info,  Node: Minimums,  Next: Limits for Files,  Prev: Sysconf,  
Up: System Configuration
--
--Minimum Values for General Capacity Limits
--==========================================
--
--   Here are the names for the POSIX minimum upper bounds for the system
--limit parameters.  The significance of these values is that you can
--safely push to these limits without checking whether the particular
--system you are using can go that far.
--
--`_POSIX_ARG_MAX'
--     The value of this macro is the most restrictive limit permitted by
--     POSIX for the maximum combined length of the ARGV and ENVIRON
--     arguments that can be passed to the `exec' functions.  Its value
--     is `4096'.
--
--`_POSIX_CHILD_MAX'
--     The value of this macro is the most restrictive limit permitted by
--     POSIX for the maximum number of simultaneous processes per real
--     user ID.  Its value is `6'.
--
--`_POSIX_NGROUPS_MAX'
--     The value of this macro is the most restrictive limit permitted by
--     POSIX for the maximum number of supplementary group IDs per
--     process.  Its value is `0'.
--
--`_POSIX_OPEN_MAX'
--     The value of this macro is the most restrictive limit permitted by
--     POSIX for the maximum number of files that a single process can
--     have open simultaneously.  Its value is `16'.
--
--`_POSIX_SSIZE_MAX'
--     The value of this macro is the most restrictive limit permitted by
--     POSIX for the maximum value that can be stored in an object of type
--     `ssize_t'.  Its value is `32767'.
--
--`_POSIX_STREAM_MAX'
--     The value of this macro is the most restrictive limit permitted by
--     POSIX for the maximum number of streams that a single process can
--     have open simultaneously.  Its value is `8'.
--
--`_POSIX_TZNAME_MAX'
--     The value of this macro is the most restrictive limit permitted by
--     POSIX for the maximum length of a time zone name.  Its value is
--     `3'.
--
--`_POSIX2_RE_DUP_MAX'
--     The value of this macro is the most restrictive limit permitted by
--     POSIX for the numbers used in the `\{MIN,MAX\}' construct in a
--     regular expression.  Its value is `255'.
--
--
--File: libc.info,  Node: Limits for Files,  Next: Options for Files,  Prev: 
Minimums,  Up: System Configuration
--
--Limits on File System Capacity
--==============================
--
--   The POSIX.1 standard specifies a number of parameters that describe
--the limitations of the file system.  It's possible for the system to
--have a fixed, uniform limit for a parameter, but this isn't the usual
--case.  On most systems, it's possible for different file systems (and,
--for some parameters, even different files) to have different maximum
--limits.  For example, this is very likely if you use NFS to mount some
--of the file systems from other machines.
--
--   Each of the following macros is defined in `limits.h' only if the
--system has a fixed, uniform limit for the parameter in question.  If the
--system allows different file systems or files to have different limits,
--then the macro is undefined; use `pathconf' or `fpathconf' to find out
--the limit that applies to a particular file.  *Note Pathconf::.
--
--   Each parameter also has another macro, with a name starting with
--`_POSIX', which gives the lowest value that the limit is allowed to
--have on *any* POSIX system.  *Note File Minimums::.
--
-- - Macro: int LINK_MAX
--     The uniform system limit (if any) for the number of names for a
--     given file.  *Note Hard Links::.
--
-- - Macro: int MAX_CANON
--     The uniform system limit (if any) for the amount of text in a line
--     of input when input editing is enabled.  *Note Canonical or Not::.
--
-- - Macro: int MAX_INPUT
--     The uniform system limit (if any) for the total number of
--     characters typed ahead as input.  *Note I/O Queues::.
--
-- - Macro: int NAME_MAX
--     The uniform system limit (if any) for the length of a file name
--     component.
--
-- - Macro: int PATH_MAX
--     The uniform system limit (if any) for the length of an entire file
--     name (that is, the argument given to system calls such as `open').
--
-- - Macro: int PIPE_BUF
--     The uniform system limit (if any) for the number of bytes that can
--     be written atomically to a pipe.  If multiple processes are
--     writing to the same pipe simultaneously, output from different
--     processes might be interleaved in chunks of this size.  *Note
--     Pipes and FIFOs::.
--
--   These are alternative macro names for some of the same information.
--
-- - Macro: int MAXNAMLEN
--     This is the BSD name for `NAME_MAX'.  It is defined in `dirent.h'.
--
-- - Macro: int FILENAME_MAX
--     The value of this macro is an integer constant expression that
--     represents the maximum length of a file name string.  It is
--     defined in `stdio.h'.
--
--     Unlike `PATH_MAX', this macro is defined even if there is no actual
--     limit imposed.  In such a case, its value is typically a very large
--     number.  *This is always the case on the GNU system.*
--
--     *Usage Note:* Don't use `FILENAME_MAX' as the size of an array in
--     which to store a file name!  You can't possibly make an array that
--     big!  Use dynamic allocation (*note Memory Allocation::.) instead.
--
--
--File: libc.info,  Node: Options for Files,  Next: File Minimums,  Prev: 
Limits for Files,  Up: System Configuration
--
--Optional Features in File Support
--=================================
--
--   POSIX defines certain system-specific options in the system calls for
--operating on files.  Some systems support these options and others do
--not.  Since these options are provided in the kernel, not in the
--library, simply using the GNU C library does not guarantee any of these
--features is supported; it depends on the system you are using.  They can
--also vary between file systems on a single machine.
--
--   This section describes the macros you can test to determine whether a
--particular option is supported on your machine.  If a given macro is
--defined in `unistd.h', then its value says whether the corresponding
--feature is supported.  (A value of `-1' indicates no; any other value
--indicates yes.)  If the macro is undefined, it means particular files
--may or may not support the feature.
--
--   Since all the machines that support the GNU C library also support
--NFS, one can never make a general statement about whether all file
--systems support the `_POSIX_CHOWN_RESTRICTED' and `_POSIX_NO_TRUNC'
--features.  So these names are never defined as macros in the GNU C
--library.
--
-- - Macro: int _POSIX_CHOWN_RESTRICTED
--     If this option is in effect, the `chown' function is restricted so
--     that the only changes permitted to nonprivileged processes is to
--     change the group owner of a file to either be the effective group
--     ID of the process, or one of its supplementary group IDs.  *Note
--     File Owner::.
--
-- - Macro: int _POSIX_NO_TRUNC
--     If this option is in effect, file name components longer than
--     `NAME_MAX' generate an `ENAMETOOLONG' error.  Otherwise, file name
--     components that are too long are silently truncated.
--
-- - Macro: unsigned char _POSIX_VDISABLE
--     This option is only meaningful for files that are terminal devices.
--     If it is enabled, then handling for special control characters can
--     be disabled individually.  *Note Special Characters::.
--
--   If one of these macros is undefined, that means that the option
--might be in effect for some files and not for others.  To inquire about
--a particular file, call `pathconf' or `fpathconf'.  *Note Pathconf::.
--
--
--File: libc.info,  Node: File Minimums,  Next: Pathconf,  Prev: Options for 
Files,  Up: System Configuration
--
--Minimum Values for File System Limits
--=====================================
--
--   Here are the names for the POSIX minimum upper bounds for some of the
--above parameters.  The significance of these values is that you can
--safely push to these limits without checking whether the particular
--system you are using can go that far.
--
--`_POSIX_LINK_MAX'
--     The most restrictive limit permitted by POSIX for the maximum
--     value of a file's link count.  The value of this constant is `8';
--     thus, you can always make up to eight names for a file without
--     running into a system limit.
--
--`_POSIX_MAX_CANON'
--     The most restrictive limit permitted by POSIX for the maximum
--     number of bytes in a canonical input line from a terminal device.
--     The value of this constant is `255'.
--
--`_POSIX_MAX_INPUT'
--     The most restrictive limit permitted by POSIX for the maximum
--     number of bytes in a terminal device input queue (or typeahead
--     buffer).  *Note Input Modes::.  The value of this constant is
--     `255'.
--
--`_POSIX_NAME_MAX'
--     The most restrictive limit permitted by POSIX for the maximum
--     number of bytes in a file name component.  The value of this
--     constant is `14'.
--
--`_POSIX_PATH_MAX'
--     The most restrictive limit permitted by POSIX for the maximum
--     number of bytes in a file name.  The value of this constant is
--     `255'.
--
--`_POSIX_PIPE_BUF'
--     The most restrictive limit permitted by POSIX for the maximum
--     number of bytes that can be written atomically to a pipe.  The
--     value of this constant is `512'.
--
--
--File: libc.info,  Node: Pathconf,  Next: Utility Limits,  Prev: File 
Minimums,  Up: System Configuration
--
--Using `pathconf'
--================
--
--   When your machine allows different files to have different values
--for a file system parameter, you can use the functions in this section
--to find out the value that applies to any particular file.
--
--   These functions and the associated constants for the PARAMETER
--argument are declared in the header file `unistd.h'.
--
-- - Function: long int pathconf (const char *FILENAME, int PARAMETER)
--     This function is used to inquire about the limits that apply to
--     the file named FILENAME.
--
--     The PARAMETER argument should be one of the `_PC_' constants
--     listed below.
--
--     The normal return value from `pathconf' is the value you requested.
--     A value of `-1' is returned both if the implementation does not
--     impose a limit, and in case of an error.  In the former case,
--     `errno' is not set, while in the latter case, `errno' is set to
--     indicate the cause of the problem.  So the only way to use this
--     function robustly is to store `0' into `errno' just before calling
--     it.
--
--     Besides the usual file name errors (*note File Name Errors::.),
--     the following error condition is defined for this function:
--
--    `EINVAL'
--          The value of PARAMETER is invalid, or the implementation
--          doesn't support the PARAMETER for the specific file.
--
-- - Function: long int fpathconf (int FILEDES, int PARAMETER)
--     This is just like `pathconf' except that an open file descriptor
--     is used to specify the file for which information is requested,
--     instead of a file name.
--
--     The following `errno' error conditions are defined for this
--     function:
--
--    `EBADF'
--          The FILEDES argument is not a valid file descriptor.
--
--    `EINVAL'
--          The value of PARAMETER is invalid, or the implementation
--          doesn't support the PARAMETER for the specific file.
--
--   Here are the symbolic constants that you can use as the PARAMETER
--argument to `pathconf' and `fpathconf'.  The values are all integer
--constants.
--
--`_PC_LINK_MAX'
--     Inquire about the value of `LINK_MAX'.
--
--`_PC_MAX_CANON'
--     Inquire about the value of `MAX_CANON'.
--
--`_PC_MAX_INPUT'
--     Inquire about the value of `MAX_INPUT'.
--
--`_PC_NAME_MAX'
--     Inquire about the value of `NAME_MAX'.
--
--`_PC_PATH_MAX'
--     Inquire about the value of `PATH_MAX'.
--
--`_PC_PIPE_BUF'
--     Inquire about the value of `PIPE_BUF'.
--
--`_PC_CHOWN_RESTRICTED'
--     Inquire about the value of `_POSIX_CHOWN_RESTRICTED'.
--
--`_PC_NO_TRUNC'
--     Inquire about the value of `_POSIX_NO_TRUNC'.
--
--`_PC_VDISABLE'
--     Inquire about the value of `_POSIX_VDISABLE'.
--
--
--File: libc.info,  Node: Utility Limits,  Next: Utility Minimums,  Prev: 
Pathconf,  Up: System Configuration
--
--Utility Program Capacity Limits
--===============================
--
--   The POSIX.2 standard specifies certain system limits that you can
--access through `sysconf' that apply to utility behavior rather than the
--behavior of the library or the operating system.
--
--   The GNU C library defines macros for these limits, and `sysconf'
--returns values for them if you ask; but these values convey no
--meaningful information.  They are simply the smallest values that
--POSIX.2 permits.
--
-- - Macro: int BC_BASE_MAX
--     The largest value of `obase' that the `bc' utility is guaranteed
--     to support.
--
-- - Macro: int BC_SCALE_MAX
--     The largest value of `scale' that the `bc' utility is guaranteed
--     to support.
--
-- - Macro: int BC_DIM_MAX
--     The largest number of elements in one array that the `bc' utility
--     is guaranteed to support.
--
-- - Macro: int BC_STRING_MAX
--     The largest number of characters in one string constant that the
--     `bc' utility is guaranteed to support.
--
-- - Macro: int BC_DIM_MAX
--     The largest number of elements in one array that the `bc' utility
--     is guaranteed to support.
--
-- - Macro: int COLL_WEIGHTS_MAX
--     The largest number of weights that can necessarily be used in
--     defining the collating sequence for a locale.
--
-- - Macro: int EXPR_NEST_MAX
--     The maximum number of expressions that can be nested within
--     parenthesis by the `expr' utility.
--
-- - Macro: int LINE_MAX
--     The largest text line that the text-oriented POSIX.2 utilities can
--     support.  (If you are using the GNU versions of these utilities,
--     then there is no actual limit except that imposed by the available
--     virtual memory, but there is no way that the library can tell you
--     this.)
--
-- - Macro: int EQUIV_CLASS_MAX
--     The maximum number of weights that can be assigned to an entry of
--     the `LC_COLLATE' category `order' keyword in a locale definition.
--     The GNU C library does not presently support locale definitions.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-27 
glibc-2.0.1/manual/libc.info-27
---- ../glibc-2.0.1/manual/libc.info-27 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-27    1970-01-01 01:00:00.000000000 +0100
-@@ -1,1214 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Utility Minimums,  Next: String Parameters,  Prev: 
Utility Limits,  Up: System Configuration
--
--Minimum Values for Utility Limits
--=================================
--
--`_POSIX2_BC_BASE_MAX'
--     The most restrictive limit permitted by POSIX.2 for the maximum
--     value of `obase' in the `bc' utility.  Its value is `99'.
--
--`_POSIX2_BC_DIM_MAX'
--     The most restrictive limit permitted by POSIX.2 for the maximum
--     size of an array in the `bc' utility.  Its value is `2048'.
--
--`_POSIX2_BC_SCALE_MAX'
--     The most restrictive limit permitted by POSIX.2 for the maximum
--     value of `scale' in the `bc' utility.  Its value is `99'.
--
--`_POSIX2_BC_STRING_MAX'
--     The most restrictive limit permitted by POSIX.2 for the maximum
--     size of a string constant in the `bc' utility.  Its value is
--     `1000'.
--
--`_POSIX2_COLL_WEIGHTS_MAX'
--     The most restrictive limit permitted by POSIX.2 for the maximum
--     number of weights that can necessarily be used in defining the
--     collating sequence for a locale.  Its value is `2'.
--
--`_POSIX2_EXPR_NEST_MAX'
--     The most restrictive limit permitted by POSIX.2 for the maximum
--     number of expressions nested within parenthesis when using the
--     `expr' utility.  Its value is `32'.
--
--`_POSIX2_LINE_MAX'
--     The most restrictive limit permitted by POSIX.2 for the maximum
--     size of a text line that the text utilities can handle.  Its value
--     is `2048'.
--
--`_POSIX2_EQUIV_CLASS_MAX'
--     The most restrictive limit permitted by POSIX.2 for the maximum
--     number of weights that can be assigned to an entry of the
--     `LC_COLLATE' category `order' keyword in a locale definition.  Its
--     value is `2'.  The GNU C library does not presently support locale
--     definitions.
--
--
--File: libc.info,  Node: String Parameters,  Prev: Utility Minimums,  Up: 
System Configuration
--
--String-Valued Parameters
--========================
--
--   POSIX.2 defines a way to get string-valued parameters from the
--operating system with the function `confstr':
--
-- - Function: size_t confstr (int PARAMETER, char *BUF, size_t LEN)
--     This function reads the value of a string-valued system parameter,
--     storing the string into LEN bytes of memory space starting at BUF.
--     The PARAMETER argument should be one of the `_CS_' symbols listed
--     below.
--
--     The normal return value from `confstr' is the length of the string
--     value that you asked for.  If you supply a null pointer for BUF,
--     then `confstr' does not try to store the string; it just returns
--     its length.  A value of `0' indicates an error.
--
--     If the string you asked for is too long for the buffer (that is,
--     longer than `LEN - 1'), then `confstr' stores just that much
--     (leaving room for the terminating null character).  You can tell
--     that this has happened because `confstr' returns a value greater
--     than or equal to LEN.
--
--     The following `errno' error conditions are defined for this
--     function:
--
--    `EINVAL'
--          The value of the PARAMETER is invalid.
--
--   Currently there is just one parameter you can read with `confstr':
--
--`_CS_PATH'
--     This parameter's value is the recommended default path for
--     searching for executable files.  This is the path that a user has
--     by default just after logging in.
--
--   The way to use `confstr' without any arbitrary limit on string size
--is to call it twice: first call it to get the length, allocate the
--buffer accordingly, and then call `confstr' again to fill the buffer,
--like this:
--
--     char *
--     get_default_path (void)
--     {
--       size_t len = confstr (_CS_PATH, NULL, 0);
--       char *buffer = (char *) xmalloc (len);
--     
--       if (confstr (_CS_PATH, buf, len + 1) == 0)
--         {
--           free (buffer);
--           return NULL;
--         }
--     
--       return buffer;
--     }
--
--
--File: libc.info,  Node: Language Features,  Next: Library Summary,  Prev: 
System Configuration,  Up: Top
--
--C Language Facilities in the Library
--************************************
--
--   Some of the facilities implemented by the C library really should be
--thought of as parts of the C language itself.  These facilities ought to
--be documented in the C Language Manual, not in the library manual; but
--since we don't have the language manual yet, and documentation for these
--features has been written, we are publishing it here.
--
--* Menu:
--
--* Consistency Checking::        Using `assert' to abort if
--                               something "impossible" happens.
--* Variadic Functions::          Defining functions with varying numbers
--                                 of args.
--* Null Pointer Constant::       The macro `NULL'.
--* Important Data Types::        Data types for object sizes.
--* Data Type Measurements::      Parameters of data type representations.
--
--
--File: libc.info,  Node: Consistency Checking,  Next: Variadic Functions,  Up: 
Language Features
--
--Explicitly Checking Internal Consistency
--========================================
--
--   When you're writing a program, it's often a good idea to put in
--checks at strategic places for "impossible" errors or violations of
--basic assumptions.  These kinds of checks are helpful in debugging
--problems with the interfaces between different parts of the program,
--for example.
--
--   The `assert' macro, defined in the header file `assert.h', provides
--a convenient way to abort the program while printing a message about
--where in the program the error was detected.
--
--   Once you think your program is debugged, you can disable the error
--checks performed by the `assert' macro by recompiling with the macro
--`NDEBUG' defined.  This means you don't actually have to change the
--program source code to disable these checks.
--
--   But disabling these consistency checks is undesirable unless they
--make the program significantly slower.  All else being equal, more error
--checking is good no matter who is running the program.  A wise user
--would rather have a program crash, visibly, than have it return nonsense
--without indicating anything might be wrong.
--
-- - Macro: void assert (int EXPRESSION)
--     Verify the programmer's belief that EXPRESSION should be nonzero
--     at this point in the program.
--
--     If `NDEBUG' is not defined, `assert' tests the value of
--     EXPRESSION.  If it is false (zero), `assert' aborts the program
--     (*note Aborting a Program::.) after printing a message of the form:
--
--          `FILE':LINENUM: FUNCTION: Assertion `EXPRESSION' failed.
--
--     on the standard error stream `stderr' (*note Standard Streams::.).
--     The filename and line number are taken from the C preprocessor
--     macros `__FILE__' and `__LINE__' and specify where the call to
--     `assert' was written.  When using the GNU C compiler, the name of
--     the function which calls `assert' is taken from the built-in
--     variable `__PRETTY_FUNCTION__'; with older compilers, the function
--     name and following colon are omitted.
--
--     If the preprocessor macro `NDEBUG' is defined before `assert.h' is
--     included, the `assert' macro is defined to do absolutely nothing.
--
--     *Warning:* Even the argument expression EXPRESSION is not
--     evaluated if `NDEBUG' is in effect.  So never use `assert' with
--     arguments that involve side effects.  For example, `assert (++i >
--     0);' is a bad idea, because `i' will not be incremented if
--     `NDEBUG' is defined.
--
--   Sometimes the "impossible" condition you want to check for is an
--error return from an operating system function.  Then it is useful to
--display not only where the program crashes, but also what error was
--returned.  The `assert_perror' macro makes this easy.
--
-- - Macro: void assert_perror (int ERRNUM)
--     Similar to `assert', but verifies that ERRNUM is zero.
--
--     If `NDEBUG' is defined, `assert_perror' tests the value of ERRNUM.
--     If it is nonzero, `assert_perror' aborts the program after a
--     printing a message of the form:
--
--          `FILE':LINENUM: FUNCTION: ERROR TEXT
--
--     on the standard error stream.  The file name, line number, and
--     function name are as for `assert'.  The error text is the result of
--     `strerror (ERRNUM)'.  *Note Error Messages::.
--
--     Like `assert', if `NDEBUG' is defined before `assert.h' is
--     included, the `assert_perror' macro does absolutely nothing.  It
--     does not evaluate the argument, so ERRNUM should not have any side
--     effects.  It is best for ERRNUM to be a just simple variable
--     reference; often it will be `errno'.
--
--     This macro is a GNU extension.
--
--   *Usage note:* The `assert' facility is designed for detecting
--*internal inconsistency*; it is not suitable for reporting invalid
--input or improper usage by *the user* of the program.
--
--   The information in the diagnostic messages printed by the `assert'
--macro is intended to help you, the programmer, track down the cause of a
--bug, but is not really useful for telling a user of your program why his
--or her input was invalid or why a command could not be carried out.  So
--you can't use `assert' or `assert_perror' to print the error messages
--for these eventualities.
--
--   What's more, your program should not abort when given invalid input,
--as `assert' would do--it should exit with nonzero status (*note Exit
--Status::.) after printing its error messages, or perhaps read another
--command or move on to the next input file.
--
--   *Note Error Messages::, for information on printing error messages
--for problems that *do not* represent bugs in the program.
--
--
--File: libc.info,  Node: Variadic Functions,  Next: Null Pointer Constant,  
Prev: Consistency Checking,  Up: Language Features
--
--Variadic Functions
--==================
--
--   ISO C defines a syntax for declaring a function to take a variable
--number or type of arguments.  (Such functions are referred to as
--"varargs functions" or "variadic functions".)  However, the language
--itself provides no mechanism for such functions to access their
--non-required arguments; instead, you use the variable arguments macros
--defined in `stdarg.h'.
--
--   This section describes how to declare variadic functions, how to
--write them, and how to call them properly.
--
--   *Compatibility Note:* Many older C dialects provide a similar, but
--incompatible, mechanism for defining functions with variable numbers of
--arguments, using `varargs.h'.
--
--* Menu:
--
--* Why Variadic::                Reasons for making functions take
--                                 variable arguments.
--* How Variadic::                How to define and call variadic functions.
--* Variadic Example::            A complete example.
--
--
--File: libc.info,  Node: Why Variadic,  Next: How Variadic,  Up: Variadic 
Functions
--
--Why Variadic Functions are Used
---------------------------------
--
--   Ordinary C functions take a fixed number of arguments.  When you
--define a function, you specify the data type for each argument.  Every
--call to the function should supply the expected number of arguments,
--with types that can be converted to the specified ones.  Thus, if the
--function `foo' is declared with `int foo (int, char *);' then you must
--call it with two arguments, a number (any kind will do) and a string
--pointer.
--
--   But some functions perform operations that can meaningfully accept an
--unlimited number of arguments.
--
--   In some cases a function can handle any number of values by
--operating on all of them as a block.  For example, consider a function
--that allocates a one-dimensional array with `malloc' to hold a
--specified set of values.  This operation makes sense for any number of
--values, as long as the length of the array corresponds to that number.
--Without facilities for variable arguments, you would have to define a
--separate function for each possible array size.
--
--   The library function `printf' (*note Formatted Output::.) is an
--example of another class of function where variable arguments are
--useful.  This function prints its arguments (which can vary in type as
--well as number) under the control of a format template string.
--
--   These are good reasons to define a "variadic" function which can
--handle as many arguments as the caller chooses to pass.
--
--   Some functions such as `open' take a fixed set of arguments, but
--occasionally ignore the last few.  Strict adherence to ISO C requires
--these functions to be defined as variadic; in practice, however, the GNU
--C compiler and most other C compilers let you define such a function to
--take a fixed set of arguments--the most it can ever use--and then only
--*declare* the function as variadic (or not declare its arguments at
--all!).
--
--
--File: libc.info,  Node: How Variadic,  Next: Variadic Example,  Prev: Why 
Variadic,  Up: Variadic Functions
--
--How Variadic Functions are Defined and Used
---------------------------------------------
--
--   Defining and using a variadic function involves three steps:
--
--   * *Define* the function as variadic, using an ellipsis (`...') in
--     the argument list, and using special macros to access the variable
--     arguments.  *Note Receiving Arguments::.
--
--   * *Declare* the function as variadic, using a prototype with an
--     ellipsis (`...'), in all the files which call it.  *Note Variadic
--     Prototypes::.
--
--   * *Call* the function by writing the fixed arguments followed by the
--     additional variable arguments.  *Note Calling Variadics::.
--
--* Menu:
--
--* Variadic Prototypes::  How to make a prototype for a function
--                        with variable arguments.
--* Receiving Arguments::  Steps you must follow to access the
--                        optional argument values.
--* How Many Arguments::   How to decide whether there are more arguments.
--* Calling Variadics::    Things you need to know about calling
--                        variable arguments functions.
--* Argument Macros::      Detailed specification of the macros
--                        for accessing variable arguments.
--* Old Varargs::                The pre-ISO way of defining variadic functions.
--
--
--File: libc.info,  Node: Variadic Prototypes,  Next: Receiving Arguments,  Up: 
How Variadic
--
--Syntax for Variable Arguments
--.............................
--
--   A function that accepts a variable number of arguments must be
--declared with a prototype that says so.   You write the fixed arguments
--as usual, and then tack on `...' to indicate the possibility of
--additional arguments.  The syntax of ISO C requires at least one fixed
--argument before the `...'.  For example,
--
--     int
--     func (const char *a, int b, ...)
--     {
--       ...
--     }
--
--outlines a definition of a function `func' which returns an `int' and
--takes two required arguments, a `const char *' and an `int'.  These are
--followed by any number of anonymous arguments.
--
--   *Portability note:* For some C compilers, the last required argument
--must not be declared `register' in the function definition.
--Furthermore, this argument's type must be "self-promoting": that is,
--the default promotions must not change its type.  This rules out array
--and function types, as well as `float', `char' (whether signed or not)
--and `short int' (whether signed or not).  This is actually an ISO C
--requirement.
--
--
--File: libc.info,  Node: Receiving Arguments,  Next: How Many Arguments,  
Prev: Variadic Prototypes,  Up: How Variadic
--
--Receiving the Argument Values
--.............................
--
--   Ordinary fixed arguments have individual names, and you can use these
--names to access their values.  But optional arguments have no
--names--nothing but `...'.  How can you access them?
--
--   The only way to access them is sequentially, in the order they were
--written, and you must use special macros from `stdarg.h' in the
--following three step process:
--
--  1. You initialize an argument pointer variable of type `va_list' using
--     `va_start'.  The argument pointer when initialized points to the
--     first optional argument.
--
--  2. You access the optional arguments by successive calls to `va_arg'.
--     The first call to `va_arg' gives you the first optional argument,
--     the next call gives you the second, and so on.
--
--     You can stop at any time if you wish to ignore any remaining
--     optional arguments.  It is perfectly all right for a function to
--     access fewer arguments than were supplied in the call, but you
--     will get garbage values if you try to access too many arguments.
--
--  3. You indicate that you are finished with the argument pointer
--     variable by calling `va_end'.
--
--     (In practice, with most C compilers, calling `va_end' does nothing
--     and you do not really need to call it.  This is always true in the
--     GNU C compiler.  But you might as well call `va_end' just in case
--     your program is someday compiled with a peculiar compiler.)
--
--   *Note Argument Macros::, for the full definitions of `va_start',
--`va_arg' and `va_end'.
--
--   Steps 1 and 3 must be performed in the function that accepts the
--optional arguments.  However, you can pass the `va_list' variable as an
--argument to another function and perform all or part of step 2 there.
--
--   You can perform the entire sequence of the three steps multiple times
--within a single function invocation.  If you want to ignore the optional
--arguments, you can do these steps zero times.
--
--   You can have more than one argument pointer variable if you like.
--You can initialize each variable with `va_start' when you wish, and
--then you can fetch arguments with each argument pointer as you wish.
--Each argument pointer variable will sequence through the same set of
--argument values, but at its own pace.
--
--   *Portability note:* With some compilers, once you pass an argument
--pointer value to a subroutine, you must not keep using the same
--argument pointer value after that subroutine returns.  For full
--portability, you should just pass it to `va_end'.  This is actually an
--ISO C requirement, but most ANSI C compilers work happily regardless.
--
--
--File: libc.info,  Node: How Many Arguments,  Next: Calling Variadics,  Prev: 
Receiving Arguments,  Up: How Variadic
--
--How Many Arguments Were Supplied
--................................
--
--   There is no general way for a function to determine the number and
--type of the optional arguments it was called with.  So whoever designs
--the function typically designs a convention for the caller to tell it
--how many arguments it has, and what kind.  It is up to you to define an
--appropriate calling convention for each variadic function, and write all
--calls accordingly.
--
--   One kind of calling convention is to pass the number of optional
--arguments as one of the fixed arguments.  This convention works provided
--all of the optional arguments are of the same type.
--
--   A similar alternative is to have one of the required arguments be a
--bit mask, with a bit for each possible purpose for which an optional
--argument might be supplied.  You would test the bits in a predefined
--sequence; if the bit is set, fetch the value of the next argument,
--otherwise use a default value.
--
--   A required argument can be used as a pattern to specify both the
--number and types of the optional arguments.  The format string argument
--to `printf' is one example of this (*note Formatted Output
--Functions::.).
--
--   Another possibility is to pass an "end marker" value as the last
--optional argument.  For example, for a function that manipulates an
--arbitrary number of pointer arguments, a null pointer might indicate the
--end of the argument list.  (This assumes that a null pointer isn't
--otherwise meaningful to the function.)  The `execl' function works in
--just this way; see *Note Executing a File::.
--
--
--File: libc.info,  Node: Calling Variadics,  Next: Argument Macros,  Prev: How 
Many Arguments,  Up: How Variadic
--
--Calling Variadic Functions
--..........................
--
--   You don't have to write anything special when you call a variadic
--function.  Just write the arguments (required arguments, followed by
--optional ones) inside parentheses, separated by commas, as usual.  But
--you should prepare by declaring the function with a prototype, and you
--must know how the argument values are converted.
--
--   In principle, functions that are *defined* to be variadic must also
--be *declared* to be variadic using a function prototype whenever you
--call them.  (*Note Variadic Prototypes::, for how.)  This is because
--some C compilers use a different calling convention to pass the same set
--of argument values to a function depending on whether that function
--takes variable arguments or fixed arguments.
--
--   In practice, the GNU C compiler always passes a given set of argument
--types in the same way regardless of whether they are optional or
--required.  So, as long as the argument types are self-promoting, you can
--safely omit declaring them.  Usually it is a good idea to declare the
--argument types for variadic functions, and indeed for all functions.
--But there are a few functions which it is extremely convenient not to
--have to declare as variadic--for example, `open' and `printf'.
--
--   Since the prototype doesn't specify types for optional arguments, in
--a call to a variadic function the "default argument promotions" are
--performed on the optional argument values.  This means the objects of
--type `char' or `short int' (whether signed or not) are promoted to
--either `int' or `unsigned int', as appropriate; and that objects of
--type `float' are promoted to type `double'.  So, if the caller passes a
--`char' as an optional argument, it is promoted to an `int', and the
--function should get it with `va_arg (AP, int)'.
--
--   Conversion of the required arguments is controlled by the function
--prototype in the usual way: the argument expression is converted to the
--declared argument type as if it were being assigned to a variable of
--that type.
--
--
--File: libc.info,  Node: Argument Macros,  Next: Old Varargs,  Prev: Calling 
Variadics,  Up: How Variadic
--
--Argument Access Macros
--......................
--
--   Here are descriptions of the macros used to retrieve variable
--arguments.  These macros are defined in the header file `stdarg.h'.
--
-- - Data Type: va_list
--     The type `va_list' is used for argument pointer variables.
--
-- - Macro: void va_start (va_list AP, LAST-REQUIRED)
--     This macro initializes the argument pointer variable AP to point
--     to the first of the optional arguments of the current function;
--     LAST-REQUIRED must be the last required argument to the function.
--
--     *Note Old Varargs::, for an alternate definition of `va_start'
--     found in the header file `varargs.h'.
--
-- - Macro: TYPE va_arg (va_list AP, TYPE)
--     The `va_arg' macro returns the value of the next optional argument,
--     and modifies the value of AP to point to the subsequent argument.
--     Thus, successive uses of `va_arg' return successive optional
--     arguments.
--
--     The type of the value returned by `va_arg' is TYPE as specified in
--     the call.  TYPE must be a self-promoting type (not `char' or
--     `short int' or `float') that matches the type of the actual
--     argument.
--
-- - Macro: void va_end (va_list AP)
--     This ends the use of AP.  After a `va_end' call, further `va_arg'
--     calls with the same AP may not work.  You should invoke `va_end'
--     before returning from the function in which `va_start' was invoked
--     with the same AP argument.
--
--     In the GNU C library, `va_end' does nothing, and you need not ever
--     use it except for reasons of portability.
--
--
--
--File: libc.info,  Node: Variadic Example,  Prev: How Variadic,  Up: Variadic 
Functions
--
--Example of a Variadic Function
--------------------------------
--
--   Here is a complete sample function that accepts a variable number of
--arguments.  The first argument to the function is the count of remaining
--arguments, which are added up and the result returned.  While trivial,
--this function is sufficient to illustrate how to use the variable
--arguments facility.
--
--     #include <stdarg.h>
--     #include <stdio.h>
--     
--     int
--     add_em_up (int count,...)
--     {
--       va_list ap;
--       int i, sum;
--     
--       va_start (ap, count);         /* Initialize the argument list. */
--     
--       sum = 0;
--       for (i = 0; i < count; i++)
--         sum += va_arg (ap, int);    /* Get the next argument value. */
--     
--       va_end (ap);                  /* Clean up. */
--       return sum;
--     }
--     
--     int
--     main (void)
--     {
--       /* This call prints 16. */
--       printf ("%d\n", add_em_up (3, 5, 5, 6));
--     
--       /* This call prints 55. */
--       printf ("%d\n", add_em_up (10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10));
--     
--       return 0;
--     }
--
--
--File: libc.info,  Node: Old Varargs,  Prev: Argument Macros,  Up: How Variadic
--
--Old-Style Variadic Functions
--............................
--
--   Before ISO C, programmers used a slightly different facility for
--writing variadic functions.  The GNU C compiler still supports it;
--currently, it is more portable than the ISO C facility, since support
--for ISO C is still not universal.  The header file which defines the
--old-fashioned variadic facility is called `varargs.h'.
--
--   Using `varargs.h' is almost the same as using `stdarg.h'.  There is
--no difference in how you call a variadic function; *Note Calling
--Variadics::.  The only difference is in how you define them.  First of
--all, you must use old-style non-prototype syntax, like this:
--
--     tree
--     build (va_alist)
--          va_dcl
--     {
--
--   Secondly, you must give `va_start' just one argument, like this:
--
--       va_list p;
--       va_start (p);
--
--   These are the special macros used for defining old-style variadic
--functions:
--
-- - Macro: va_alist
--     This macro stands for the argument name list required in a variadic
--     function.
--
-- - Macro: va_dcl
--     This macro declares the implicit argument or arguments for a
--     variadic function.
--
-- - Macro: void va_start (va_list AP)
--     This macro, as defined in `varargs.h', initializes the argument
--     pointer variable AP to point to the first argument of the current
--     function.
--
--   The other argument macros, `va_arg' and `va_end', are the same in
--`varargs.h' as in `stdarg.h'; see *Note Argument Macros:: for details.
--
--   It does not work to include both `varargs.h' and `stdarg.h' in the
--same compilation; they define `va_start' in conflicting ways.
--
--
--File: libc.info,  Node: Null Pointer Constant,  Next: Important Data Types,  
Prev: Variadic Functions,  Up: Language Features
--
--Null Pointer Constant
--=====================
--
--   The null pointer constant is guaranteed not to point to any real
--object.  You can assign it to any pointer variable since it has type
--`void *'.  The preferred way to write a null pointer constant is with
--`NULL'.
--
-- - Macro: void * NULL
--     This is a null pointer constant.
--
--   You can also use `0' or `(void *)0' as a null pointer constant, but
--using `NULL' is cleaner because it makes the purpose of the constant
--more evident.
--
--   If you use the null pointer constant as a function argument, then for
--complete portability you should make sure that the function has a
--prototype declaration.  Otherwise, if the target machine has two
--different pointer representations, the compiler won't know which
--representation to use for that argument.  You can avoid the problem by
--explicitly casting the constant to the proper pointer type, but we
--recommend instead adding a prototype for the function you are calling.
--
--
--File: libc.info,  Node: Important Data Types,  Next: Data Type Measurements,  
Prev: Null Pointer Constant,  Up: Language Features
--
--Important Data Types
--====================
--
--   The result of subtracting two pointers in C is always an integer,
--but the precise data type varies from C compiler to C compiler.
--Likewise, the data type of the result of `sizeof' also varies between
--compilers.  ISO defines standard aliases for these two types, so you
--can refer to them in a portable fashion.  They are defined in the
--header file `stddef.h'.
--
-- - Data Type: ptrdiff_t
--     This is the signed integer type of the result of subtracting two
--     pointers.  For example, with the declaration `char *p1, *p2;', the
--     expression `p2 - p1' is of type `ptrdiff_t'.  This will probably
--     be one of the standard signed integer types (`short int', `int' or
--     `long int'), but might be a nonstandard type that exists only for
--     this purpose.
--
-- - Data Type: size_t
--     This is an unsigned integer type used to represent the sizes of
--     objects.  The result of the `sizeof' operator is of this type, and
--     functions such as `malloc' (*note Unconstrained Allocation::.) and
--     `memcpy' (*note Copying and Concatenation::.) accept arguments of
--     this type to specify object sizes.
--
--     *Usage Note:* `size_t' is the preferred way to declare any
--     arguments or variables that hold the size of an object.
--
--   In the GNU system `size_t' is equivalent to either `unsigned int' or
--`unsigned long int'.  These types have identical properties on the GNU
--system, and for most purposes, you can use them interchangeably.
--However, they are distinct as data types, which makes a difference in
--certain contexts.
--
--   For example, when you specify the type of a function argument in a
--function prototype, it makes a difference which one you use.  If the
--system header files declare `malloc' with an argument of type `size_t'
--and you declare `malloc' with an argument of type `unsigned int', you
--will get a compilation error if `size_t' happens to be `unsigned long
--int' on your system.  To avoid any possibility of error, when a
--function argument or value is supposed to have type `size_t', never
--declare its type in any other way.
--
--   *Compatibility Note:* Implementations of C before the advent of
--ISO C generally used `unsigned int' for representing object sizes and
--`int' for pointer subtraction results.  They did not necessarily define
--either `size_t' or `ptrdiff_t'.  Unix systems did define `size_t', in
--`sys/types.h', but the definition was usually a signed type.
--
--
--File: libc.info,  Node: Data Type Measurements,  Prev: Important Data Types,  
Up: Language Features
--
--Data Type Measurements
--======================
--
--   Most of the time, if you choose the proper C data type for each
--object in your program, you need not be concerned with just how it is
--represented or how many bits it uses.  When you do need such
--information, the C language itself does not provide a way to get it.
--The header files `limits.h' and `float.h' contain macros which give you
--this information in full detail.
--
--* Menu:
--
--* Width of Type::           How many bits does an integer type hold?
--* Range of Type::           What are the largest and smallest values
--                           that an integer type can hold?
--* Floating Type Macros::    Parameters that measure the floating point types.
--* Structure Measurement::   Getting measurements on structure types.
--
--
--File: libc.info,  Node: Width of Type,  Next: Range of Type,  Up: Data Type 
Measurements
--
--Computing the Width of an Integer Data Type
---------------------------------------------
--
--   The most common reason that a program needs to know how many bits
--are in an integer type is for using an array of `long int' as a bit
--vector.  You can access the bit at index N with
--
--     vector[N / LONGBITS] & (1 << (N % LONGBITS))
--
--provided you define `LONGBITS' as the number of bits in a `long int'.
--
--   There is no operator in the C language that can give you the number
--of bits in an integer data type.  But you can compute it from the macro
--`CHAR_BIT', defined in the header file `limits.h'.
--
--`CHAR_BIT'
--     This is the number of bits in a `char'--eight, on most systems.
--     The value has type `int'.
--
--     You can compute the number of bits in any data type TYPE like this:
--
--          sizeof (TYPE) * CHAR_BIT
--
--
--File: libc.info,  Node: Range of Type,  Next: Floating Type Macros,  Prev: 
Width of Type,  Up: Data Type Measurements
--
--Range of an Integer Type
--------------------------
--
--   Suppose you need to store an integer value which can range from zero
--to one million.  Which is the smallest type you can use?  There is no
--general rule; it depends on the C compiler and target machine.  You can
--use the `MIN' and `MAX' macros in `limits.h' to determine which type
--will work.
--
--   Each signed integer type has a pair of macros which give the smallest
--and largest values that it can hold.  Each unsigned integer type has one
--such macro, for the maximum value; the minimum value is, of course,
--zero.
--
--   The values of these macros are all integer constant expressions.  The
--`MAX' and `MIN' macros for `char' and `short int' types have values of
--type `int'.  The `MAX' and `MIN' macros for the other types have values
--of the same type described by the macro--thus, `ULONG_MAX' has type
--`unsigned long int'.
--
--`SCHAR_MIN'
--     This is the minimum value that can be represented by a
--     `signed char'.
--
--`SCHAR_MAX'
--`UCHAR_MAX'
--     These are the maximum values that can be represented by a
--     `signed char' and `unsigned char', respectively.
--
--`CHAR_MIN'
--     This is the minimum value that can be represented by a `char'.
--     It's equal to `SCHAR_MIN' if `char' is signed, or zero otherwise.
--
--`CHAR_MAX'
--     This is the maximum value that can be represented by a `char'.
--     It's equal to `SCHAR_MAX' if `char' is signed, or `UCHAR_MAX'
--     otherwise.
--
--`SHRT_MIN'
--     This is the minimum value that can be represented by a
--     `signed short int'.  On most machines that the GNU C library runs
--     on, `short' integers are 16-bit quantities.
--
--`SHRT_MAX'
--`USHRT_MAX'
--     These are the maximum values that can be represented by a
--     `signed short int' and `unsigned short int', respectively.
--
--`INT_MIN'
--     This is the minimum value that can be represented by a
--     `signed int'.  On most machines that the GNU C system runs on, an
--     `int' is a 32-bit quantity.
--
--`INT_MAX'
--`UINT_MAX'
--     These are the maximum values that can be represented by,
--     respectively, the type `signed int' and the type `unsigned int'.
--
--`LONG_MIN'
--     This is the minimum value that can be represented by a
--     `signed long int'.  On most machines that the GNU C system runs
--     on, `long' integers are 32-bit quantities, the same size as `int'.
--
--`LONG_MAX'
--`ULONG_MAX'
--     These are the maximum values that can be represented by a
--     `signed long int' and `unsigned long int', respectively.
--
--`LONG_LONG_MIN'
--     This is the minimum value that can be represented by a
--     `signed long long int'.  On most machines that the GNU C system
--     runs on, `long long' integers are 64-bit quantities.
--
--`LONG_LONG_MAX'
--`ULONG_LONG_MAX'
--     These are the maximum values that can be represented by a `signed
--     long long int' and `unsigned long long int', respectively.
--
--`WCHAR_MAX'
--     This is the maximum value that can be represented by a `wchar_t'.
--     *Note Wide Char Intro::.
--
--   The header file `limits.h' also defines some additional constants
--that parameterize various operating system and file system limits.
--These constants are described in *Note System Configuration::.
--
--
--File: libc.info,  Node: Floating Type Macros,  Next: Structure Measurement,  
Prev: Range of Type,  Up: Data Type Measurements
--
--Floating Type Macros
----------------------
--
--   The specific representation of floating point numbers varies from
--machine to machine.  Because floating point numbers are represented
--internally as approximate quantities, algorithms for manipulating
--floating point data often need to take account of the precise details of
--the machine's floating point representation.
--
--   Some of the functions in the C library itself need this information;
--for example, the algorithms for printing and reading floating point
--numbers (*note I/O on Streams::.) and for calculating trigonometric and
--irrational functions (*note Mathematics::.) use it to avoid round-off
--error and loss of accuracy.  User programs that implement numerical
--analysis techniques also often need this information in order to
--minimize or compute error bounds.
--
--   The header file `float.h' describes the format used by your machine.
--
--* Menu:
--
--* Floating Point Concepts::     Definitions of terminology.
--* Floating Point Parameters::   Details of specific macros.
--* IEEE Floating Point::         The measurements for one common
--                                 representation.
--
--
--File: libc.info,  Node: Floating Point Concepts,  Next: Floating Point 
Parameters,  Up: Floating Type Macros
--
--Floating Point Representation Concepts
--......................................
--
--   This section introduces the terminology for describing floating point
--representations.
--
--   You are probably already familiar with most of these concepts in
--terms of scientific or exponential notation for floating point numbers.
--For example, the number `123456.0' could be expressed in exponential
--notation as `1.23456e+05', a shorthand notation indicating that the
--mantissa `1.23456' is multiplied by the base `10' raised to power `5'.
--
--   More formally, the internal representation of a floating point number
--can be characterized in terms of the following parameters:
--
--   * The "sign" is either `-1' or `1'.
--
--   * The "base" or "radix" for exponentiation, an integer greater than
--     `1'.  This is a constant for a particular representation.
--
--   * The "exponent" to which the base is raised.  The upper and lower
--     bounds of the exponent value are constants for a particular
--     representation.
--
--     Sometimes, in the actual bits representing the floating point
--     number, the exponent is "biased" by adding a constant to it, to
--     make it always be represented as an unsigned quantity.  This is
--     only important if you have some reason to pick apart the bit
--     fields making up the floating point number by hand, which is
--     something for which the GNU library provides no support.  So this
--     is ignored in the discussion that follows.
--
--   * The "mantissa" or "significand", an unsigned integer which is a
--     part of each floating point number.
--
--   * The "precision" of the mantissa.  If the base of the representation
--     is B, then the precision is the number of base-B digits in the
--     mantissa.  This is a constant for a particular representation.
--
--     Many floating point representations have an implicit "hidden bit"
--     in the mantissa.  This is a bit which is present virtually in the
--     mantissa, but not stored in memory because its value is always 1
--     in a normalized number.  The precision figure (see above) includes
--     any hidden bits.
--
--     Again, the GNU library provides no facilities for dealing with such
--     low-level aspects of the representation.
--
--   The mantissa of a floating point number actually represents an
--implicit fraction whose denominator is the base raised to the power of
--the precision.  Since the largest representable mantissa is one less
--than this denominator, the value of the fraction is always strictly
--less than `1'.  The mathematical value of a floating point number is
--then the product of this fraction, the sign, and the base raised to the
--exponent.
--
--   We say that the floating point number is "normalized" if the
--fraction is at least `1/B', where B is the base.  In other words, the
--mantissa would be too large to fit if it were multiplied by the base.
--Non-normalized numbers are sometimes called "denormal"; they contain
--less precision than the representation normally can hold.
--
--   If the number is not normalized, then you can subtract `1' from the
--exponent while multiplying the mantissa by the base, and get another
--floating point number with the same value.  "Normalization" consists of
--doing this repeatedly until the number is normalized.  Two distinct
--normalized floating point numbers cannot be equal in value.
--
--   (There is an exception to this rule: if the mantissa is zero, it is
--considered normalized.  Another exception happens on certain machines
--where the exponent is as small as the representation can hold.  Then it
--is impossible to subtract `1' from the exponent, so a number may be
--normalized even if its fraction is less than `1/B'.)
--
--
--File: libc.info,  Node: Floating Point Parameters,  Next: IEEE Floating 
Point,  Prev: Floating Point Concepts,  Up: Floating Type Macros
--
--Floating Point Parameters
--.........................
--
--   These macro definitions can be accessed by including the header file
--`float.h' in your program.
--
--   Macro names starting with `FLT_' refer to the `float' type, while
--names beginning with `DBL_' refer to the `double' type and names
--beginning with `LDBL_' refer to the `long double' type.  (Currently GCC
--does not support `long double' as a distinct data type, so the values
--for the `LDBL_' constants are equal to the corresponding constants for
--the `double' type.)
--
--   Of these macros, only `FLT_RADIX' is guaranteed to be a constant
--expression.  The other macros listed here cannot be reliably used in
--places that require constant expressions, such as `#if' preprocessing
--directives or in the dimensions of static arrays.
--
--   Although the ISO C standard specifies minimum and maximum values for
--most of these parameters, the GNU C implementation uses whatever values
--describe the floating point representation of the target machine.  So in
--principle GNU C actually satisfies the ISO C requirements only if the
--target machine is suitable.  In practice, all the machines currently
--supported are suitable.
--
--`FLT_ROUNDS'
--     This value characterizes the rounding mode for floating point
--     addition.  The following values indicate standard rounding modes:
--
--    `-1'
--          The mode is indeterminable.
--
--    `0'
--          Rounding is towards zero.
--
--    `1'
--          Rounding is to the nearest number.
--
--    `2'
--          Rounding is towards positive infinity.
--
--    `3'
--          Rounding is towards negative infinity.
--
--     Any other value represents a machine-dependent nonstandard rounding
--     mode.
--
--     On most machines, the value is `1', in accordance with the IEEE
--     standard for floating point.
--
--     Here is a table showing how certain values round for each possible
--     value of `FLT_ROUNDS', if the other aspects of the representation
--     match the IEEE single-precision standard.
--
--                          0      1             2             3
--           1.00000003    1.0    1.0           1.00000012    1.0
--           1.00000007    1.0    1.00000012    1.00000012    1.0
--          -1.00000003   -1.0   -1.0          -1.0          -1.00000012
--          -1.00000007   -1.0   -1.00000012   -1.0          -1.00000012
--
--`FLT_RADIX'
--     This is the value of the base, or radix, of exponent
--     representation.  This is guaranteed to be a constant expression,
--     unlike the other macros described in this section.  The value is 2
--     on all machines we know of except the IBM 360 and derivatives.
--
--`FLT_MANT_DIG'
--     This is the number of base-`FLT_RADIX' digits in the floating point
--     mantissa for the `float' data type.  The following expression
--     yields `1.0' (even though mathematically it should not) due to the
--     limited number of mantissa digits:
--
--          float radix = FLT_RADIX;
--          
--          1.0f + 1.0f / radix / radix / ... / radix
--
--     where `radix' appears `FLT_MANT_DIG' times.
--
--`DBL_MANT_DIG'
--`LDBL_MANT_DIG'
--     This is the number of base-`FLT_RADIX' digits in the floating point
--     mantissa for the data types `double' and `long double',
--     respectively.
--
--`FLT_DIG'
--     This is the number of decimal digits of precision for the `float'
--     data type.  Technically, if P and B are the precision and base
--     (respectively) for the representation, then the decimal precision
--     Q is the maximum number of decimal digits such that any floating
--     point number with Q base 10 digits can be rounded to a floating
--     point number with P base B digits and back again, without change
--     to the Q decimal digits.
--
--     The value of this macro is supposed to be at least `6', to satisfy
--     ISO C.
--
--`DBL_DIG'
--`LDBL_DIG'
--     These are similar to `FLT_DIG', but for the data types `double'
--     and `long double', respectively.  The values of these macros are
--     supposed to be at least `10'.
--
--`FLT_MIN_EXP'
--     This is the smallest possible exponent value for type `float'.
--     More precisely, is the minimum negative integer such that the value
--     `FLT_RADIX' raised to this power minus 1 can be represented as a
--     normalized floating point number of type `float'.
--
--`DBL_MIN_EXP'
--`LDBL_MIN_EXP'
--     These are similar to `FLT_MIN_EXP', but for the data types
--     `double' and `long double', respectively.
--
--`FLT_MIN_10_EXP'
--     This is the minimum negative integer such that `10' raised to this
--     power minus 1 can be represented as a normalized floating point
--     number of type `float'.  This is supposed to be `-37' or even less.
--
--`DBL_MIN_10_EXP'
--`LDBL_MIN_10_EXP'
--     These are similar to `FLT_MIN_10_EXP', but for the data types
--     `double' and `long double', respectively.
--
--`FLT_MAX_EXP'
--     This is the largest possible exponent value for type `float'.  More
--     precisely, this is the maximum positive integer such that value
--     `FLT_RADIX' raised to this power minus 1 can be represented as a
--     floating point number of type `float'.
--
--`DBL_MAX_EXP'
--`LDBL_MAX_EXP'
--     These are similar to `FLT_MAX_EXP', but for the data types
--     `double' and `long double', respectively.
--
--`FLT_MAX_10_EXP'
--     This is the maximum positive integer such that `10' raised to this
--     power minus 1 can be represented as a normalized floating point
--     number of type `float'.  This is supposed to be at least `37'.
--
--`DBL_MAX_10_EXP'
--`LDBL_MAX_10_EXP'
--     These are similar to `FLT_MAX_10_EXP', but for the data types
--     `double' and `long double', respectively.
--
--`FLT_MAX'
--     The value of this macro is the maximum number representable in type
--     `float'.  It is supposed to be at least `1E+37'.  The value has
--     type `float'.
--
--     The smallest representable number is `- FLT_MAX'.
--
--`DBL_MAX'
--`LDBL_MAX'
--     These are similar to `FLT_MAX', but for the data types `double'
--     and `long double', respectively.  The type of the macro's value is
--     the same as the type it describes.
--
--`FLT_MIN'
--     The value of this macro is the minimum normalized positive floating
--     point number that is representable in type `float'.  It is supposed
--     to be no more than `1E-37'.
--
--`DBL_MIN'
--`LDBL_MIN'
--     These are similar to `FLT_MIN', but for the data types `double'
--     and `long double', respectively.  The type of the macro's value is
--     the same as the type it describes.
--
--`FLT_EPSILON'
--     This is the minimum positive floating point number of type `float'
--     such that `1.0 + FLT_EPSILON != 1.0' is true.  It's supposed to be
--     no greater than `1E-5'.
--
--`DBL_EPSILON'
--`LDBL_EPSILON'
--     These are similar to `FLT_EPSILON', but for the data types
--     `double' and `long double', respectively.  The type of the macro's
--     value is the same as the type it describes.  The values are not
--     supposed to be greater than `1E-9'.
--
--
--File: libc.info,  Node: IEEE Floating Point,  Prev: Floating Point 
Parameters,  Up: Floating Type Macros
--
--IEEE Floating Point
--...................
--
--   Here is an example showing how the floating type measurements come
--out for the most common floating point representation, specified by the
--`IEEE Standard for Binary Floating Point Arithmetic (ANSI/IEEE Std
--754-1985)'.  Nearly all computers designed since the 1980s use this
--format.
--
--   The IEEE single-precision float representation uses a base of 2.
--There is a sign bit, a mantissa with 23 bits plus one hidden bit (so
--the total precision is 24 base-2 digits), and an 8-bit exponent that
--can represent values in the range -125 to 128, inclusive.
--
--   So, for an implementation that uses this representation for the
--`float' data type, appropriate values for the corresponding parameters
--are:
--
--     FLT_RADIX                             2
--     FLT_MANT_DIG                         24
--     FLT_DIG                               6
--     FLT_MIN_EXP                        -125
--     FLT_MIN_10_EXP                      -37
--     FLT_MAX_EXP                         128
--     FLT_MAX_10_EXP                      +38
--     FLT_MIN                 1.17549435E-38F
--     FLT_MAX                 3.40282347E+38F
--     FLT_EPSILON             1.19209290E-07F
--
--   Here are the values for the `double' data type:
--
--     DBL_MANT_DIG                         53
--     DBL_DIG                              15
--     DBL_MIN_EXP                       -1021
--     DBL_MIN_10_EXP                     -307
--     DBL_MAX_EXP                        1024
--     DBL_MAX_10_EXP                      308
--     DBL_MAX         1.7976931348623157E+308
--     DBL_MIN         2.2250738585072014E-308
--     DBL_EPSILON     2.2204460492503131E-016
--
--
--File: libc.info,  Node: Structure Measurement,  Prev: Floating Type Macros,  
Up: Data Type Measurements
--
--Structure Field Offset Measurement
------------------------------------
--
--   You can use `offsetof' to measure the location within a structure
--type of a particular structure member.
--
-- - Macro: size_t offsetof (TYPE, MEMBER)
--     This expands to a integer constant expression that is the offset
--     of the structure member named MEMBER in a the structure type TYPE.
--     For example, `offsetof (struct s, elem)' is the offset, in bytes,
--     of the member `elem' in a `struct s'.
--
--     This macro won't work if MEMBER is a bit field; you get an error
--     from the C compiler in that case.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-28 
glibc-2.0.1/manual/libc.info-28
---- ../glibc-2.0.1/manual/libc.info-28 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-28    1970-01-01 01:00:00.000000000 +0100
-@@ -1,3847 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Library Summary,  Next: Maintenance,  Prev: Language 
Features,  Up: Top
--
--Summary of Library Facilities
--*****************************
--
--   This appendix is a complete list of the facilities declared within
--the header files supplied with the GNU C library.  Each entry also
--lists the standard or other source from which each facility is derived,
--and tells you where in the manual you can find more information about
--how to use it.
--
--`void abort (void)'
--     `stdlib.h' (ISO):  *Note Aborting a Program::.
--
--`int abs (int NUMBER)'
--     `stdlib.h' (ISO):  *Note Absolute Value::.
--
--`int accept (int SOCKET, struct sockaddr *ADDR, size_t *LENGTH-PTR)'
--     `sys/socket.h' (BSD):  *Note Accepting Connections::.
--
--`int access (const char *FILENAME, int HOW)'
--     `unistd.h' (POSIX.1):  *Note Testing File Access::.
--
--`double acosh (double X)'
--     `math.h' (BSD):  *Note Hyperbolic Functions::.
--
--`double acos (double X)'
--     `math.h' (ISO):  *Note Inverse Trig Functions::.
--
--`int adjtime (const struct timeval *DELTA, struct timeval *OLDDELTA)'
--     `sys/time.h' (BSD):  *Note High-Resolution Calendar::.
--
--`AF_FILE'
--     `sys/socket.h' (GNU):  *Note Address Formats::.
--
--`AF_INET'
--     `sys/socket.h' (BSD):  *Note Address Formats::.
--
--`AF_UNIX'
--     `sys/socket.h' (BSD):  *Note Address Formats::.
--
--`AF_UNSPEC'
--     `sys/socket.h' (BSD):  *Note Address Formats::.
--
--`unsigned int alarm (unsigned int SECONDS)'
--     `unistd.h' (POSIX.1):  *Note Setting an Alarm::.
--
--`void * alloca (size_t SIZE);'
--     `stdlib.h' (GNU, BSD):  *Note Variable Size Automatic::.
--
--`tcflag_t ALTWERASE'
--     `termios.h' (BSD):  *Note Local Modes::.
--
--`int ARG_MAX'
--     `limits.h' (POSIX.1):  *Note General Limits::.
--
--`char * asctime (const struct tm *BROKENTIME)'
--     `time.h' (ISO):  *Note Formatting Date and Time::.
--
--`double asinh (double X)'
--     `math.h' (BSD):  *Note Hyperbolic Functions::.
--
--`double asin (double X)'
--     `math.h' (ISO):  *Note Inverse Trig Functions::.
--
--`int asprintf (char **PTR, const char *TEMPLATE, ...)'
--     `stdio.h' (GNU):  *Note Dynamic Output::.
--
--`void assert (int EXPRESSION)'
--     `assert.h' (ISO):  *Note Consistency Checking::.
--
--`void assert_perror (int ERRNUM)'
--     `assert.h' (GNU):  *Note Consistency Checking::.
--
--`double atan2 (double Y, double X)'
--     `math.h' (ISO):  *Note Inverse Trig Functions::.
--
--`double atanh (double X)'
--     `math.h' (BSD):  *Note Hyperbolic Functions::.
--
--`double atan (double X)'
--     `math.h' (ISO):  *Note Inverse Trig Functions::.
--
--`int atexit (void (*FUNCTION) (void))'
--     `stdlib.h' (ISO):  *Note Cleanups on Exit::.
--
--`double atof (const char *STRING)'
--     `stdlib.h' (ISO):  *Note Parsing of Floats::.
--
--`int atoi (const char *STRING)'
--     `stdlib.h' (ISO):  *Note Parsing of Integers::.
--
--`long int atol (const char *STRING)'
--     `stdlib.h' (ISO):  *Note Parsing of Integers::.
--
--`B0'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B110'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B1200'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B134'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B150'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B1800'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B19200'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B200'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B2400'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B300'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B38400'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B4800'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B50'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B600'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B75'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`B9600'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`int BC_BASE_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Limits::.
--
--`int BC_DIM_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Limits::.
--
--`int BC_DIM_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Limits::.
--
--`int bcmp (const void *A1, const void *A2, size_t SIZE)'
--     `string.h' (BSD):  *Note String/Array Comparison::.
--
--`void * bcopy (void *FROM, const void *TO, size_t SIZE)'
--     `string.h' (BSD):  *Note Copying and Concatenation::.
--
--`int BC_SCALE_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Limits::.
--
--`int BC_STRING_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Limits::.
--
--`int bind (int SOCKET, struct sockaddr *ADDR, size_t LENGTH)'
--     `sys/socket.h' (BSD):  *Note Setting Address::.
--
--`tcflag_t BRKINT'
--     `termios.h' (POSIX.1):  *Note Input Modes::.
--
--`_BSD_SOURCE'
--     (GNU):  *Note Feature Test Macros::.
--
--`void * bsearch (const void *KEY, const void *ARRAY, size_t COUNT, size_t 
SIZE, comparison_fn_t COMPARE)'
--     `stdlib.h' (ISO):  *Note Array Search Function::.
--
--`int BUFSIZ'
--     `stdio.h' (ISO):  *Note Controlling Buffering::.
--
--`void * bzero (void *BLOCK, size_t SIZE)'
--     `string.h' (BSD):  *Note Copying and Concatenation::.
--
--`double cabs (struct { double real, imag; } Z)'
--     `math.h' (BSD):  *Note Absolute Value::.
--
--`void * calloc (size_t COUNT, size_t ELTSIZE)'
--     `malloc.h', `stdlib.h' (ISO):  *Note Allocating Cleared Space::.
--
--`double cbrt (double X)'
--     `math.h' (BSD):  *Note Exponents and Logarithms::.
--
--`cc_t'
--     `termios.h' (POSIX.1):  *Note Mode Data Types::.
--
--`tcflag_t CCTS_OFLOW'
--     `termios.h' (BSD):  *Note Control Modes::.
--
--`double ceil (double X)'
--     `math.h' (ISO):  *Note Rounding and Remainders::.
--
--`speed_t cfgetispeed (const struct termios *TERMIOS-P)'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`speed_t cfgetospeed (const struct termios *TERMIOS-P)'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`int cfmakeraw (struct termios *TERMIOS-P)'
--     `termios.h' (BSD):  *Note Noncanonical Input::.
--
--`void cfree (void *PTR)'
--     `stdlib.h' (Sun):  *Note Freeing after Malloc::.
--
--`int cfsetispeed (struct termios *TERMIOS-P, speed_t SPEED)'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`int cfsetospeed (struct termios *TERMIOS-P, speed_t SPEED)'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`int cfsetspeed (struct termios *TERMIOS-P, speed_t SPEED)'
--     `termios.h' (BSD):  *Note Line Speed::.
--
--`CHAR_BIT'
--     `limits.h' (ISO):  *Note Width of Type::.
--
--`CHAR_MAX'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`CHAR_MIN'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`int chdir (const char *FILENAME)'
--     `unistd.h' (POSIX.1):  *Note Working Directory::.
--
--`int CHILD_MAX'
--     `limits.h' (POSIX.1):  *Note General Limits::.
--
--`int chmod (const char *FILENAME, mode_t MODE)'
--     `sys/stat.h' (POSIX.1):  *Note Setting Permissions::.
--
--`int chown (const char *FILENAME, uid_t OWNER, gid_t GROUP)'
--     `unistd.h' (POSIX.1):  *Note File Owner::.
--
--`tcflag_t CIGNORE'
--     `termios.h' (BSD):  *Note Control Modes::.
--
--`void clearerr (FILE *STREAM)'
--     `stdio.h' (ISO):  *Note EOF and Errors::.
--
--`int CLK_TCK'
--     `time.h' (POSIX.1):  *Note Basic CPU Time::.
--
--`tcflag_t CLOCAL'
--     `termios.h' (POSIX.1):  *Note Control Modes::.
--
--`clock_t clock (void)'
--     `time.h' (ISO):  *Note Basic CPU Time::.
--
--`int CLOCKS_PER_SEC'
--     `time.h' (ISO):  *Note Basic CPU Time::.
--
--`clock_t'
--     `time.h' (ISO):  *Note Basic CPU Time::.
--
--`int closedir (DIR *DIRSTREAM)'
--     `dirent.h' (POSIX.1):  *Note Reading/Closing Directory::.
--
--`int close (int FILEDES)'
--     `unistd.h' (POSIX.1):  *Note Opening and Closing Files::.
--
--`int COLL_WEIGHTS_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Limits::.
--
--`size_t confstr (int PARAMETER, char *BUF, size_t LEN)'
--     `unistd.h' (POSIX.2):  *Note String Parameters::.
--
--`int connect (int SOCKET, struct sockaddr *ADDR, size_t LENGTH)'
--     `sys/socket.h' (BSD):  *Note Connecting::.
--
--`cookie_close_function'
--     `stdio.h' (GNU):  *Note Hook Functions::.
--
--`cookie_io_functions_t'
--     `stdio.h' (GNU):  *Note Streams and Cookies::.
--
--`cookie_read_function'
--     `stdio.h' (GNU):  *Note Hook Functions::.
--
--`cookie_seek_function'
--     `stdio.h' (GNU):  *Note Hook Functions::.
--
--`cookie_write_function'
--     `stdio.h' (GNU):  *Note Hook Functions::.
--
--`double copysign (double VALUE, double SIGN)'
--     `math.h' (BSD):  *Note Normalization Functions::.
--
--`double cosh (double X)'
--     `math.h' (ISO):  *Note Hyperbolic Functions::.
--
--`double cos (double X)'
--     `math.h' (ISO):  *Note Trig Functions::.
--
--`tcflag_t CREAD'
--     `termios.h' (POSIX.1):  *Note Control Modes::.
--
--`int creat (const char *FILENAME, mode_t MODE)'
--     `fcntl.h' (POSIX.1):  *Note Opening and Closing Files::.
--
--`tcflag_t CRTS_IFLOW'
--     `termios.h' (BSD):  *Note Control Modes::.
--
--`tcflag_t CS5'
--     `termios.h' (POSIX.1):  *Note Control Modes::.
--
--`tcflag_t CS6'
--     `termios.h' (POSIX.1):  *Note Control Modes::.
--
--`tcflag_t CS7'
--     `termios.h' (POSIX.1):  *Note Control Modes::.
--
--`tcflag_t CS8'
--     `termios.h' (POSIX.1):  *Note Control Modes::.
--
--`tcflag_t CSIZE'
--     `termios.h' (POSIX.1):  *Note Control Modes::.
--
--`_CS_PATH'
--     `unistd.h' (POSIX.2):  *Note String Parameters::.
--
--`tcflag_t CSTOPB'
--     `termios.h' (POSIX.1):  *Note Control Modes::.
--
--`char * ctermid (char *STRING)'
--     `stdio.h' (POSIX.1):  *Note Identifying the Terminal::.
--
--`char * ctime (const time_t *TIME)'
--     `time.h' (ISO):  *Note Formatting Date and Time::.
--
--`char * cuserid (char *STRING)'
--     `stdio.h' (POSIX.1):  *Note Who Logged In::.
--
--`int daylight'
--     `time.h' (SVID):  *Note Time Zone Functions::.
--
--`DBL_DIG'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`DBL_EPSILON'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`DBL_MANT_DIG'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`DBL_MAX_10_EXP'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`DBL_MAX_EXP'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`DBL_MAX'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`DBL_MIN_10_EXP'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`DBL_MIN_EXP'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`DBL_MIN'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`dev_t'
--     `sys/types.h' (POSIX.1):  *Note Attribute Meanings::.
--
--`double difftime (time_t TIME1, time_t TIME0)'
--     `time.h' (ISO):  *Note Simple Calendar Time::.
--
--`DIR'
--     `dirent.h' (POSIX.1):  *Note Opening a Directory::.
--
--`div_t div (int NUMERATOR, int DENOMINATOR)'
--     `stdlib.h' (ISO):  *Note Integer Division::.
--
--`div_t'
--     `stdlib.h' (ISO):  *Note Integer Division::.
--
--`double drem (double NUMERATOR, double DENOMINATOR)'
--     `math.h' (BSD):  *Note Rounding and Remainders::.
--
--`int dup2 (int OLD, int NEW)'
--     `unistd.h' (POSIX.1):  *Note Duplicating Descriptors::.
--
--`int dup (int OLD)'
--     `unistd.h' (POSIX.1):  *Note Duplicating Descriptors::.
--
--`int E2BIG'
--     `errno.h' (POSIX.1: Argument list too long):  *Note Error Codes::.
--
--`int EACCES'
--     `errno.h' (POSIX.1: Permission denied):  *Note Error Codes::.
--
--`int EADDRINUSE'
--     `errno.h' (BSD: Address already in use):  *Note Error Codes::.
--
--`int EADDRNOTAVAIL'
--     `errno.h' (BSD: Cannot assign requested address):  *Note Error
--     Codes::.
--
--`int EADV'
--     `errno.h' (Linux???: Advertise error):  *Note Error Codes::.
--
--`int EAFNOSUPPORT'
--     `errno.h' (BSD: Address family not supported by protocol):  *Note
--     Error Codes::.
--
--`int EAGAIN'
--     `errno.h' (POSIX.1: Resource temporarily unavailable):  *Note
--     Error Codes::.
--
--`int EALREADY'
--     `errno.h' (BSD: Operation already in progress):  *Note Error
--     Codes::.
--
--`int EAUTH'
--     `errno.h' (BSD: Authentication error):  *Note Error Codes::.
--
--`int EBACKGROUND'
--     `errno.h' (GNU: Inappropriate operation for background process):
--     *Note Error Codes::.
--
--`int EBADE'
--     `errno.h' (Linux???: Invalid exchange):  *Note Error Codes::.
--
--`int EBADFD'
--     `errno.h' (Linux???: File descriptor in bad state):  *Note Error
--     Codes::.
--
--`int EBADF'
--     `errno.h' (POSIX.1: Bad file descriptor):  *Note Error Codes::.
--
--`int EBADMSG'
--     `errno.h' (XOPEN: Bad message):  *Note Error Codes::.
--
--`int EBADR'
--     `errno.h' (Linux???: Invalid request descriptor):  *Note Error
--     Codes::.
--
--`int EBADRPC'
--     `errno.h' (BSD: RPC struct is bad):  *Note Error Codes::.
--
--`int EBADRQC'
--     `errno.h' (Linux???: Invalid request code):  *Note Error Codes::.
--
--`int EBADSLT'
--     `errno.h' (Linux???: Invalid slot):  *Note Error Codes::.
--
--`int EBFONT'
--     `errno.h' (Linux???: Bad font file format):  *Note Error Codes::.
--
--`int EBUSY'
--     `errno.h' (POSIX.1: Device or resource busy):  *Note Error Codes::.
--
--`int ECHILD'
--     `errno.h' (POSIX.1: No child processes):  *Note Error Codes::.
--
--`tcflag_t ECHOCTL'
--     `termios.h' (BSD):  *Note Local Modes::.
--
--`tcflag_t ECHOE'
--     `termios.h' (POSIX.1):  *Note Local Modes::.
--
--`tcflag_t ECHO'
--     `termios.h' (POSIX.1):  *Note Local Modes::.
--
--`tcflag_t ECHOKE'
--     `termios.h' (BSD):  *Note Local Modes::.
--
--`tcflag_t ECHOK'
--     `termios.h' (POSIX.1):  *Note Local Modes::.
--
--`tcflag_t ECHONL'
--     `termios.h' (POSIX.1):  *Note Local Modes::.
--
--`tcflag_t ECHOPRT'
--     `termios.h' (BSD):  *Note Local Modes::.
--
--`int ECHRNG'
--     `errno.h' (Linux???: Channel number out of range):  *Note Error
--     Codes::.
--
--`int ECOMM'
--     `errno.h' (Linux???: Communication error on send):  *Note Error
--     Codes::.
--
--`int ECONNABORTED'
--     `errno.h' (BSD: Software caused connection abort):  *Note Error
--     Codes::.
--
--`int ECONNREFUSED'
--     `errno.h' (BSD: Connection refused):  *Note Error Codes::.
--
--`int ECONNRESET'
--     `errno.h' (BSD: Connection reset by peer):  *Note Error Codes::.
--
--`int EDEADLK'
--     `errno.h' (POSIX.1: Resource deadlock avoided):  *Note Error
--     Codes::.
--
--`int EDEADLOCK'
--     `errno.h' (Linux???: File locking deadlock error):  *Note Error
--     Codes::.
--
--`int EDESTADDRREQ'
--     `errno.h' (BSD: Destination address required):  *Note Error
--     Codes::.
--
--`int EDIED'
--     `errno.h' (GNU: Translator died):  *Note Error Codes::.
--
--`int ED'
--     `errno.h' (GNU: ?):  *Note Error Codes::.
--
--`int EDOM'
--     `errno.h' (ISO: Numerical argument out of domain):  *Note Error
--     Codes::.
--
--`int EDOTDOT'
--     `errno.h' (Linux???: RFS specific error):  *Note Error Codes::.
--
--`int EDQUOT'
--     `errno.h' (BSD: Disc quota exceeded):  *Note Error Codes::.
--
--`int EEXIST'
--     `errno.h' (POSIX.1: File exists):  *Note Error Codes::.
--
--`int EFAULT'
--     `errno.h' (POSIX.1: Bad address):  *Note Error Codes::.
--
--`int EFBIG'
--     `errno.h' (POSIX.1: File too large):  *Note Error Codes::.
--
--`int EFTYPE'
--     `errno.h' (BSD: Inappropriate file type or format):  *Note Error
--     Codes::.
--
--`int EGRATUITOUS'
--     `errno.h' (GNU: Gratuitous error):  *Note Error Codes::.
--
--`int EGREGIOUS'
--     `errno.h' (GNU: You really blew it this time):  *Note Error
--     Codes::.
--
--`int EHOSTDOWN'
--     `errno.h' (BSD: Host is down):  *Note Error Codes::.
--
--`int EHOSTUNREACH'
--     `errno.h' (BSD: No route to host):  *Note Error Codes::.
--
--`int EIDRM'
--     `errno.h' (XOPEN: Identifier removed):  *Note Error Codes::.
--
--`int EIEIO'
--     `errno.h' (GNU: Computer bought the farm):  *Note Error Codes::.
--
--`int EILSEQ'
--     `errno.h' (ISO: Invalid or incomplete multibyte or wide
--     character):  *Note Error Codes::.
--
--`int EINPROGRESS'
--     `errno.h' (BSD: Operation now in progress):  *Note Error Codes::.
--
--`int EINTR'
--     `errno.h' (POSIX.1: Interrupted system call):  *Note Error Codes::.
--
--`int EINVAL'
--     `errno.h' (POSIX.1: Invalid argument):  *Note Error Codes::.
--
--`int EIO'
--     `errno.h' (POSIX.1: Input/output error):  *Note Error Codes::.
--
--`int EISCONN'
--     `errno.h' (BSD: Transport endpoint is already connected):  *Note
--     Error Codes::.
--
--`int EISDIR'
--     `errno.h' (POSIX.1: Is a directory):  *Note Error Codes::.
--
--`int EISNAM'
--     `errno.h' (Linux???: Is a named type file):  *Note Error Codes::.
--
--`int EL2HLT'
--     `errno.h' (Linux???: Level 2 halted):  *Note Error Codes::.
--
--`int EL2NSYNC'
--     `errno.h' (Linux???: Level 2 not synchronized):  *Note Error
--     Codes::.
--
--`int EL3HLT'
--     `errno.h' (Linux???: Level 3 halted):  *Note Error Codes::.
--
--`int EL3RST'
--     `errno.h' (Linux???: Level 3 reset):  *Note Error Codes::.
--
--`int ELIBACC'
--     `errno.h' (Linux???: Can not access a needed shared library):
--     *Note Error Codes::.
--
--`int ELIBBAD'
--     `errno.h' (Linux???: Accessing a corrupted shared library):  *Note
--     Error Codes::.
--
--`int ELIBEXEC'
--     `errno.h' (Linux???: Cannot exec a shared library directly):
--     *Note Error Codes::.
--
--`int ELIBMAX'
--     `errno.h' (Linux???: Attempting to link in too many shared
--     libraries):  *Note Error Codes::.
--
--`int ELIBSCN'
--     `errno.h' (Linux???: .lib section in a.out corrupted):  *Note
--     Error Codes::.
--
--`int ELNRNG'
--     `errno.h' (Linux???: Link number out of range):  *Note Error
--     Codes::.
--
--`int ELOOP'
--     `errno.h' (BSD: Too many levels of symbolic links):  *Note Error
--     Codes::.
--
--`int EMFILE'
--     `errno.h' (POSIX.1: Too many open files):  *Note Error Codes::.
--
--`int EMLINK'
--     `errno.h' (POSIX.1: Too many links):  *Note Error Codes::.
--
--`int EMSGSIZE'
--     `errno.h' (BSD: Message too long):  *Note Error Codes::.
--
--`int EMULTIHOP'
--     `errno.h' (XOPEN: Multihop attempted):  *Note Error Codes::.
--
--`int ENAMETOOLONG'
--     `errno.h' (POSIX.1: File name too long):  *Note Error Codes::.
--
--`int ENAVAIL'
--     `errno.h' (Linux???: No XENIX semaphores available):  *Note Error
--     Codes::.
--
--`void endgrent (void)'
--     `grp.h' (SVID, BSD):  *Note Scanning All Groups::.
--
--`void endhostent ()'
--     `netdb.h' (BSD):  *Note Host Names::.
--
--`void endnetent (void)'
--     `netdb.h' (BSD):  *Note Networks Database::.
--
--`void endnetgrent (void)'
--     `netdb.h' (netdb.h):  *Note Lookup Netgroup::.
--
--`void endprotoent (void)'
--     `netdb.h' (BSD):  *Note Protocols Database::.
--
--`void endpwent (void)'
--     `pwd.h' (SVID, BSD):  *Note Scanning All Users::.
--
--`void endservent (void)'
--     `netdb.h' (BSD):  *Note Services Database::.
--
--`int ENEEDAUTH'
--     `errno.h' (BSD: Need authenticator):  *Note Error Codes::.
--
--`int ENETDOWN'
--     `errno.h' (BSD: Network is down):  *Note Error Codes::.
--
--`int ENETRESET'
--     `errno.h' (BSD: Network dropped connection on reset):  *Note Error
--     Codes::.
--
--`int ENETUNREACH'
--     `errno.h' (BSD: Network is unreachable):  *Note Error Codes::.
--
--`int ENFILE'
--     `errno.h' (POSIX.1: Too many open files in system):  *Note Error
--     Codes::.
--
--`int ENOANO'
--     `errno.h' (Linux???: No anode):  *Note Error Codes::.
--
--`int ENOBUFS'
--     `errno.h' (BSD: No buffer space available):  *Note Error Codes::.
--
--`int ENOCSI'
--     `errno.h' (Linux???: No CSI structure available):  *Note Error
--     Codes::.
--
--`int ENODATA'
--     `errno.h' (XOPEN: No data available):  *Note Error Codes::.
--
--`int ENODEV'
--     `errno.h' (POSIX.1: Operation not supported by device):  *Note
--     Error Codes::.
--
--`int ENOENT'
--     `errno.h' (POSIX.1: No such file or directory):  *Note Error
--     Codes::.
--
--`int ENOEXEC'
--     `errno.h' (POSIX.1: Exec format error):  *Note Error Codes::.
--
--`int ENOLCK'
--     `errno.h' (POSIX.1: No locks available):  *Note Error Codes::.
--
--`int ENOLINK'
--     `errno.h' (XOPEN: Link has been severed):  *Note Error Codes::.
--
--`int ENOMEM'
--     `errno.h' (POSIX.1: Cannot allocate memory):  *Note Error Codes::.
--
--`int ENOMSG'
--     `errno.h' (XOPEN: No message of desired type):  *Note Error
--     Codes::.
--
--`int ENONET'
--     `errno.h' (Linux???: Machine is not on the network):  *Note Error
--     Codes::.
--
--`int ENOPKG'
--     `errno.h' (Linux???: Package not installed):  *Note Error Codes::.
--
--`int ENOPROTOOPT'
--     `errno.h' (BSD: Protocol not available):  *Note Error Codes::.
--
--`int ENOSPC'
--     `errno.h' (POSIX.1: No space left on device):  *Note Error Codes::.
--
--`int ENOSR'
--     `errno.h' (XOPEN: Out of streams resources):  *Note Error Codes::.
--
--`int ENOSTR'
--     `errno.h' (XOPEN: Device not a stream):  *Note Error Codes::.
--
--`int ENOSYS'
--     `errno.h' (POSIX.1: Function not implemented):  *Note Error
--     Codes::.
--
--`int ENOTBLK'
--     `errno.h' (BSD: Block device required):  *Note Error Codes::.
--
--`int ENOTCONN'
--     `errno.h' (BSD: Transport endpoint is not connected):  *Note Error
--     Codes::.
--
--`int ENOTDIR'
--     `errno.h' (POSIX.1: Not a directory):  *Note Error Codes::.
--
--`int ENOTEMPTY'
--     `errno.h' (POSIX.1: Directory not empty):  *Note Error Codes::.
--
--`int ENOTNAM'
--     `errno.h' (Linux???: Not a XENIX named type file):  *Note Error
--     Codes::.
--
--`int ENOTSOCK'
--     `errno.h' (BSD: Socket operation on non-socket):  *Note Error
--     Codes::.
--
--`int ENOTTY'
--     `errno.h' (POSIX.1: Inappropriate ioctl for device):  *Note Error
--     Codes::.
--
--`int ENOTUNIQ'
--     `errno.h' (Linux???: Name not unique on network):  *Note Error
--     Codes::.
--
--`char ** environ'
--     `unistd.h' (POSIX.1):  *Note Environment Access::.
--
--`int ENXIO'
--     `errno.h' (POSIX.1: Device not configured):  *Note Error Codes::.
--
--`int EOF'
--     `stdio.h' (ISO):  *Note EOF and Errors::.
--
--`int EOPNOTSUPP'
--     `errno.h' (BSD: Operation not supported):  *Note Error Codes::.
--
--`int EOVERFLOW'
--     `errno.h' (XOPEN: Value too large for defined data type):  *Note
--     Error Codes::.
--
--`int EPERM'
--     `errno.h' (POSIX.1: Operation not permitted):  *Note Error Codes::.
--
--`int EPFNOSUPPORT'
--     `errno.h' (BSD: Protocol family not supported):  *Note Error
--     Codes::.
--
--`int EPIPE'
--     `errno.h' (POSIX.1: Broken pipe):  *Note Error Codes::.
--
--`int EPROCLIM'
--     `errno.h' (BSD: Too many processes):  *Note Error Codes::.
--
--`int EPROCUNAVAIL'
--     `errno.h' (BSD: RPC bad procedure for program):  *Note Error
--     Codes::.
--
--`int EPROGMISMATCH'
--     `errno.h' (BSD: RPC program version wrong):  *Note Error Codes::.
--
--`int EPROGUNAVAIL'
--     `errno.h' (BSD: RPC program not available):  *Note Error Codes::.
--
--`int EPROTO'
--     `errno.h' (XOPEN: Protocol error):  *Note Error Codes::.
--
--`int EPROTONOSUPPORT'
--     `errno.h' (BSD: Protocol not supported):  *Note Error Codes::.
--
--`int EPROTOTYPE'
--     `errno.h' (BSD: Protocol wrong type for socket):  *Note Error
--     Codes::.
--
--`int EQUIV_CLASS_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Limits::.
--
--`int ERANGE'
--     `errno.h' (ISO: Numerical result out of range):  *Note Error
--     Codes::.
--
--`int EREMCHG'
--     `errno.h' (Linux???: Remote address changed):  *Note Error Codes::.
--
--`int EREMOTEIO'
--     `errno.h' (Linux???: Remote I/O error):  *Note Error Codes::.
--
--`int EREMOTE'
--     `errno.h' (BSD: Object is remote):  *Note Error Codes::.
--
--`int ERESTART'
--     `errno.h' (Linux???: Interrupted system call should be restarted):
--     *Note Error Codes::.
--
--`int EROFS'
--     `errno.h' (POSIX.1: Read-only file system):  *Note Error Codes::.
--
--`int ERPCMISMATCH'
--     `errno.h' (BSD: RPC version wrong):  *Note Error Codes::.
--
--`volatile int errno'
--     `errno.h' (ISO):  *Note Checking for Errors::.
--
--`int ESHUTDOWN'
--     `errno.h' (BSD: Cannot send after transport endpoint shutdown):
--     *Note Error Codes::.
--
--`int ESOCKTNOSUPPORT'
--     `errno.h' (BSD: Socket type not supported):  *Note Error Codes::.
--
--`int ESPIPE'
--     `errno.h' (POSIX.1: Illegal seek):  *Note Error Codes::.
--
--`int ESRCH'
--     `errno.h' (POSIX.1: No such process):  *Note Error Codes::.
--
--`int ESRMNT'
--     `errno.h' (Linux???: Srmount error):  *Note Error Codes::.
--
--`int ESTALE'
--     `errno.h' (BSD: Stale NFS file handle):  *Note Error Codes::.
--
--`int ESTRPIPE'
--     `errno.h' (Linux???: Streams pipe error):  *Note Error Codes::.
--
--`int ETIMEDOUT'
--     `errno.h' (BSD: Connection timed out):  *Note Error Codes::.
--
--`int ETIME'
--     `errno.h' (XOPEN: Timer expired):  *Note Error Codes::.
--
--`int ETOOMANYREFS'
--     `errno.h' (BSD: Too many references: cannot splice):  *Note Error
--     Codes::.
--
--`int ETXTBSY'
--     `errno.h' (BSD: Text file busy):  *Note Error Codes::.
--
--`int EUCLEAN'
--     `errno.h' (Linux???: Structure needs cleaning):  *Note Error
--     Codes::.
--
--`int EUNATCH'
--     `errno.h' (Linux???: Protocol driver not attached):  *Note Error
--     Codes::.
--
--`int EUSERS'
--     `errno.h' (BSD: Too many users):  *Note Error Codes::.
--
--`int EWOULDBLOCK'
--     `errno.h' (BSD: Operation would block):  *Note Error Codes::.
--
--`int EXDEV'
--     `errno.h' (POSIX.1: Invalid cross-device link):  *Note Error
--     Codes::.
--
--`int execle (const char *FILENAME, const char *ARG0, char *const ENV[], ...)'
--     `unistd.h' (POSIX.1):  *Note Executing a File::.
--
--`int execl (const char *FILENAME, const char *ARG0, ...)'
--     `unistd.h' (POSIX.1):  *Note Executing a File::.
--
--`int execlp (const char *FILENAME, const char *ARG0, ...)'
--     `unistd.h' (POSIX.1):  *Note Executing a File::.
--
--`int execve (const char *FILENAME, char *const ARGV[], char *const ENV[])'
--     `unistd.h' (POSIX.1):  *Note Executing a File::.
--
--`int execv (const char *FILENAME, char *const ARGV[])'
--     `unistd.h' (POSIX.1):  *Note Executing a File::.
--
--`int execvp (const char *FILENAME, char *const ARGV[])'
--     `unistd.h' (POSIX.1):  *Note Executing a File::.
--
--`int EXFULL'
--     `errno.h' (Linux???: Exchange full):  *Note Error Codes::.
--
--`int EXIT_FAILURE'
--     `stdlib.h' (ISO):  *Note Exit Status::.
--
--`void _exit (int STATUS)'
--     `unistd.h' (POSIX.1):  *Note Termination Internals::.
--
--`void exit (int STATUS)'
--     `stdlib.h' (ISO):  *Note Normal Termination::.
--
--`int EXIT_SUCCESS'
--     `stdlib.h' (ISO):  *Note Exit Status::.
--
--`double exp (double X)'
--     `math.h' (ISO):  *Note Exponents and Logarithms::.
--
--`double expm1 (double X)'
--     `math.h' (BSD):  *Note Exponents and Logarithms::.
--
--`int EXPR_NEST_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Limits::.
--
--`double fabs (double NUMBER)'
--     `math.h' (ISO):  *Note Absolute Value::.
--
--`int fchmod (int FILEDES, int MODE)'
--     `sys/stat.h' (BSD):  *Note Setting Permissions::.
--
--`int fchown (int FILEDES, int OWNER, int GROUP)'
--     `unistd.h' (BSD):  *Note File Owner::.
--
--`int fclean (FILE *STREAM)'
--     `stdio.h' (GNU):  *Note Cleaning Streams::.
--
--`int fcloseall (void)'
--     `stdio.h' (GNU):  *Note Closing Streams::.
--
--`int fclose (FILE *STREAM)'
--     `stdio.h' (ISO):  *Note Closing Streams::.
--
--`int fcntl (int FILEDES, int COMMAND, ...)'
--     `fcntl.h' (POSIX.1):  *Note Control Operations::.
--
--`int FD_CLOEXEC'
--     `fcntl.h' (POSIX.1):  *Note Descriptor Flags::.
--
--`void FD_CLR (int FILEDES, fd_set *SET)'
--     `sys/types.h' (BSD):  *Note Waiting for I/O::.
--
--`int FD_ISSET (int FILEDES, fd_set *SET)'
--     `sys/types.h' (BSD):  *Note Waiting for I/O::.
--
--`FILE * fdopen (int FILEDES, const char *OPENTYPE)'
--     `stdio.h' (POSIX.1):  *Note Descriptors and Streams::.
--
--`void FD_SET (int FILEDES, fd_set *SET)'
--     `sys/types.h' (BSD):  *Note Waiting for I/O::.
--
--`fd_set'
--     `sys/types.h' (BSD):  *Note Waiting for I/O::.
--
--`int FD_SETSIZE'
--     `sys/types.h' (BSD):  *Note Waiting for I/O::.
--
--`int F_DUPFD'
--     `fcntl.h' (POSIX.1):  *Note Duplicating Descriptors::.
--
--`void FD_ZERO (fd_set *SET)'
--     `sys/types.h' (BSD):  *Note Waiting for I/O::.
--
--`int feof (FILE *STREAM)'
--     `stdio.h' (ISO):  *Note EOF and Errors::.
--
--`int ferror (FILE *STREAM)'
--     `stdio.h' (ISO):  *Note EOF and Errors::.
--
--`int fflush (FILE *STREAM)'
--     `stdio.h' (ISO):  *Note Flushing Buffers::.
--
--`int fgetc (FILE *STREAM)'
--     `stdio.h' (ISO):  *Note Character Input::.
--
--`int F_GETFD'
--     `fcntl.h' (POSIX.1):  *Note Descriptor Flags::.
--
--`int F_GETFL'
--     `fcntl.h' (POSIX.1):  *Note Getting File Status Flags::.
--
--`struct group * fgetgrent (FILE *STREAM)'
--     `grp.h' (SVID):  *Note Scanning All Groups::.
--
--`int fgetgrent_r (FILE *STREAM, struct group *RESULT_BUF, char *BUFFER, 
size_t BUFLEN, struct group **RESULT)'
--     `grp.h' (GNU):  *Note Scanning All Groups::.
--
--`int F_GETLK'
--     `fcntl.h' (POSIX.1):  *Note File Locks::.
--
--`int F_GETOWN'
--     `fcntl.h' (BSD):  *Note Interrupt Input::.
--
--`int fgetpos (FILE *STREAM, fpos_t *POSITION)'
--     `stdio.h' (ISO):  *Note Portable Positioning::.
--
--`struct passwd * fgetpwent (FILE *STREAM)'
--     `pwd.h' (SVID):  *Note Scanning All Users::.
--
--`int fgetpwent_r (FILE *STREAM, struct passwd *RESULT_BUF, char *BUFFER, 
size_t BUFLEN, struct passwd **RESULT)'
--     `pwd.h' (GNU):  *Note Scanning All Users::.
--
--`char * fgets (char *S, int COUNT, FILE *STREAM)'
--     `stdio.h' (ISO):  *Note Line Input::.
--
--`FILE'
--     `stdio.h' (ISO):  *Note Streams::.
--
--`int FILENAME_MAX'
--     `stdio.h' (ISO):  *Note Limits for Files::.
--
--`int fileno (FILE *STREAM)'
--     `stdio.h' (POSIX.1):  *Note Descriptors and Streams::.
--
--`int finite (double X)'
--     `math.h' (BSD):  *Note Predicates on Floats::.
--
--`double floor (double X)'
--     `math.h' (ISO):  *Note Rounding and Remainders::.
--
--`FLT_DIG'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`FLT_EPSILON'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`FLT_MANT_DIG'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`FLT_MAX_10_EXP'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`FLT_MAX_EXP'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`FLT_MAX'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`FLT_MIN_10_EXP'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`FLT_MIN_EXP'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`FLT_MIN'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`FLT_RADIX'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`FLT_ROUNDS'
--     `float.h' (ISO):  *Note Floating Point Parameters::.
--
--`tcflag_t FLUSHO'
--     `termios.h' (BSD):  *Note Local Modes::.
--
--`FILE * fmemopen (void *BUF, size_t SIZE, const char *OPENTYPE)'
--     `stdio.h' (GNU):  *Note String Streams::.
--
--`double fmod (double NUMERATOR, double DENOMINATOR)'
--     `math.h' (ISO):  *Note Rounding and Remainders::.
--
--`int fnmatch (const char *PATTERN, const char *STRING, int FLAGS)'
--     `fnmatch.h' (POSIX.2):  *Note Wildcard Matching::.
--
--`FNM_CASEFOLD'
--     `fnmatch.h' (GNU):  *Note Wildcard Matching::.
--
--`FNM_FILE_NAME'
--     `fnmatch.h' (GNU):  *Note Wildcard Matching::.
--
--`FNM_LEADING_DIR'
--     `fnmatch.h' (GNU):  *Note Wildcard Matching::.
--
--`FNM_NOESCAPE'
--     `fnmatch.h' (POSIX.2):  *Note Wildcard Matching::.
--
--`FNM_PATHNAME'
--     `fnmatch.h' (POSIX.2):  *Note Wildcard Matching::.
--
--`FNM_PERIOD'
--     `fnmatch.h' (POSIX.2):  *Note Wildcard Matching::.
--
--`int F_OK'
--     `unistd.h' (POSIX.1):  *Note Testing File Access::.
--
--`FILE * fopencookie (void *COOKIE, const char *OPENTYPE, 
cookie_io_functions_t IO-FUNCTIONS)'
--     `stdio.h' (GNU):  *Note Streams and Cookies::.
--
--`FILE * fopen (const char *FILENAME, const char *OPENTYPE)'
--     `stdio.h' (ISO):  *Note Opening Streams::.
--
--`int FOPEN_MAX'
--     `stdio.h' (ISO):  *Note Opening Streams::.
--
--`pid_t fork (void)'
--     `unistd.h' (POSIX.1):  *Note Creating a Process::.
--
--`long int fpathconf (int FILEDES, int PARAMETER)'
--     `unistd.h' (POSIX.1):  *Note Pathconf::.
--
--`FPE_DECOVF_TRAP'
--     `signal.h' (BSD):  *Note Program Error Signals::.
--
--`FPE_FLTDIV_FAULT'
--     `signal.h' (BSD):  *Note Program Error Signals::.
--
--`FPE_FLTDIV_TRAP'
--     `signal.h' (BSD):  *Note Program Error Signals::.
--
--`FPE_FLTOVF_FAULT'
--     `signal.h' (BSD):  *Note Program Error Signals::.
--
--`FPE_FLTOVF_TRAP'
--     `signal.h' (BSD):  *Note Program Error Signals::.
--
--`FPE_FLTUND_FAULT'
--     `signal.h' (BSD):  *Note Program Error Signals::.
--
--`FPE_FLTUND_TRAP'
--     `signal.h' (BSD):  *Note Program Error Signals::.
--
--`FPE_INTDIV_TRAP'
--     `signal.h' (BSD):  *Note Program Error Signals::.
--
--`FPE_INTOVF_TRAP'
--     `signal.h' (BSD):  *Note Program Error Signals::.
--
--`FPE_SUBRNG_TRAP'
--     `signal.h' (BSD):  *Note Program Error Signals::.
--
--`fpos_t'
--     `stdio.h' (ISO):  *Note Portable Positioning::.
--
--`int fprintf (FILE *STREAM, const char *TEMPLATE, ...)'
--     `stdio.h' (ISO):  *Note Formatted Output Functions::.
--
--`int fputc (int C, FILE *STREAM)'
--     `stdio.h' (ISO):  *Note Simple Output::.
--
--`int fputs (const char *S, FILE *STREAM)'
--     `stdio.h' (ISO):  *Note Simple Output::.
--
--`F_RDLCK'
--     `fcntl.h' (POSIX.1):  *Note File Locks::.
--
--`size_t fread (void *DATA, size_t SIZE, size_t COUNT, FILE *STREAM)'
--     `stdio.h' (ISO):  *Note Block Input/Output::.
--
--`__free_hook'
--     `malloc.h' (GNU):  *Note Hooks for Malloc::.
--
--`void free (void *PTR)'
--     `malloc.h', `stdlib.h' (ISO):  *Note Freeing after Malloc::.
--
--`FILE * freopen (const char *FILENAME, const char *OPENTYPE, FILE *STREAM)'
--     `stdio.h' (ISO):  *Note Opening Streams::.
--
--`double frexp (double VALUE, int *EXPONENT)'
--     `math.h' (ISO):  *Note Normalization Functions::.
--
--`int fscanf (FILE *STREAM, const char *TEMPLATE, ...)'
--     `stdio.h' (ISO):  *Note Formatted Input Functions::.
--
--`int fseek (FILE *STREAM, long int OFFSET, int WHENCE)'
--     `stdio.h' (ISO):  *Note File Positioning::.
--
--`int F_SETFD'
--     `fcntl.h' (POSIX.1):  *Note Descriptor Flags::.
--
--`int F_SETFL'
--     `fcntl.h' (POSIX.1):  *Note Getting File Status Flags::.
--
--`int F_SETLK'
--     `fcntl.h' (POSIX.1):  *Note File Locks::.
--
--`int F_SETLKW'
--     `fcntl.h' (POSIX.1):  *Note File Locks::.
--
--`int F_SETOWN'
--     `fcntl.h' (BSD):  *Note Interrupt Input::.
--
--`int fsetpos (FILE *STREAM, const fpos_t POSITION)'
--     `stdio.h' (ISO):  *Note Portable Positioning::.
--
--`int fstat (int FILEDES, struct stat *BUF)'
--     `sys/stat.h' (POSIX.1):  *Note Reading Attributes::.
--
--`long int ftell (FILE *STREAM)'
--     `stdio.h' (ISO):  *Note File Positioning::.
--
--`F_UNLCK'
--     `fcntl.h' (POSIX.1):  *Note File Locks::.
--
--`size_t fwrite (const void *DATA, size_t SIZE, size_t COUNT, FILE *STREAM)'
--     `stdio.h' (ISO):  *Note Block Input/Output::.
--
--`F_WRLCK'
--     `fcntl.h' (POSIX.1):  *Note File Locks::.
--
--`int getchar (void)'
--     `stdio.h' (ISO):  *Note Character Input::.
--
--`int getc (FILE *STREAM)'
--     `stdio.h' (ISO):  *Note Character Input::.
--
--`char * getcwd (char *BUFFER, size_t SIZE)'
--     `unistd.h' (POSIX.1):  *Note Working Directory::.
--
--`ssize_t getdelim (char **LINEPTR, size_t *N, int DELIMITER, FILE *STREAM)'
--     `stdio.h' (GNU):  *Note Line Input::.
--
--`gid_t getegid (void)'
--     `unistd.h' (POSIX.1):  *Note Reading Persona::.
--
--`char * getenv (const char *NAME)'
--     `stdlib.h' (ISO):  *Note Environment Access::.
--
--`uid_t geteuid (void)'
--     `unistd.h' (POSIX.1):  *Note Reading Persona::.
--
--`gid_t getgid (void)'
--     `unistd.h' (POSIX.1):  *Note Reading Persona::.
--
--`struct group * getgrent (void)'
--     `grp.h' (SVID, BSD):  *Note Scanning All Groups::.
--
--`int getgrent_r (struct group *RESULT_BUF, char *BUFFER, size_t BUFLEN, 
struct group **RESULT)'
--     `grp.h' (GNU):  *Note Scanning All Groups::.
--
--`struct group * getgrgid (gid_t GID)'
--     `grp.h' (POSIX.1):  *Note Lookup Group::.
--
--`int getgrgid_r (gid_t GID, struct group *RESULT_BUF, char *BUFFER, size_t 
BUFLEN, struct group **RESULT)'
--     `grp.h' (POSIX.1c):  *Note Lookup Group::.
--
--`struct group * getgrnam (const char *NAME)'
--     `grp.h' (SVID, BSD):  *Note Lookup Group::.
--
--`int getgrnam_r (const char *NAME, struct group *RESULT_BUF, char *BUFFER, 
size_t BUFLEN, struct group **RESULT)'
--     `grp.h' (POSIX.1c):  *Note Lookup Group::.
--
--`int getgroups (int COUNT, gid_t *GROUPS)'
--     `unistd.h' (POSIX.1):  *Note Reading Persona::.
--
--`struct hostent * gethostbyaddr (const char *ADDR, int LENGTH, int FORMAT)'
--     `netdb.h' (BSD):  *Note Host Names::.
--
--`struct hostent * gethostbyname (const char *NAME)'
--     `netdb.h' (BSD):  *Note Host Names::.
--
--`struct hostent * gethostent ()'
--     `netdb.h' (BSD):  *Note Host Names::.
--
--`long int gethostid (void)'
--     `unistd.h' (BSD):  *Note Host Identification::.
--
--`int gethostname (char *NAME, size_t SIZE)'
--     `unistd.h' (BSD):  *Note Host Identification::.
--
--`int getitimer (int WHICH, struct itimerval *OLD)'
--     `sys/time.h' (BSD):  *Note Setting an Alarm::.
--
--`ssize_t getline (char **LINEPTR, size_t *N, FILE *STREAM)'
--     `stdio.h' (GNU):  *Note Line Input::.
--
--`char * getlogin (void)'
--     `unistd.h' (POSIX.1):  *Note Who Logged In::.
--
--`struct netent * getnetbyaddr (long NET, int TYPE)'
--     `netdb.h' (BSD):  *Note Networks Database::.
--
--`struct netent * getnetbyname (const char *NAME)'
--     `netdb.h' (BSD):  *Note Networks Database::.
--
--`struct netent * getnetent (void)'
--     `netdb.h' (BSD):  *Note Networks Database::.
--
--`int getnetgrent (char **HOSTP, char **USERP, char **DOMAINP)'
--     `netdb.h' (netdb.h):  *Note Lookup Netgroup::.
--
--`int getnetgrent_r (char **HOSTP, char **USERP, char **DOMAINP, char *BUFFER, 
int BUFLEN)'
--     `netdb.h' (netdb.h):  *Note Lookup Netgroup::.
--
--`int getopt (int ARGC, char **ARGV, const char *OPTIONS)'
--     `unistd.h' (POSIX.2):  *Note Parsing Options::.
--
--`int getopt_long (int ARGC, char **ARGV, const char *SHORTOPTS, struct option 
*LONGOPTS, int *INDEXPTR)'
--     `getopt.h' (GNU):  *Note Long Options::.
--
--`int getpeername (int SOCKET, struct sockaddr *ADDR, size_t *LENGTH-PTR)'
--     `sys/socket.h' (BSD):  *Note Who is Connected::.
--
--`pid_t getpgrp (pid_t PID)'
--     `unistd.h' (BSD):  *Note Process Group Functions::.
--
--`pid_t getpgrp (void)'
--     `unistd.h' (POSIX.1):  *Note Process Group Functions::.
--
--`pid_t getpid (void)'
--     `unistd.h' (POSIX.1):  *Note Process Identification::.
--
--`pid_t getppid (void)'
--     `unistd.h' (POSIX.1):  *Note Process Identification::.
--
--`int getpriority (int CLASS, int ID)'
--     `sys/resource.h' (BSD):  *Note Priority::.
--
--`struct protoent * getprotobyname (const char *NAME)'
--     `netdb.h' (BSD):  *Note Protocols Database::.
--
--`struct protoent * getprotobynumber (int PROTOCOL)'
--     `netdb.h' (BSD):  *Note Protocols Database::.
--
--`struct protoent * getprotoent (void)'
--     `netdb.h' (BSD):  *Note Protocols Database::.
--
--`struct passwd * getpwent (void)'
--     `pwd.h' (POSIX.1):  *Note Scanning All Users::.
--
--`int getpwent_r (struct passwd *RESULT_BUF, char *BUFFER, int BUFLEN, struct 
passwd **RESULT)'
--     `pwd.h' (GNU):  *Note Scanning All Users::.
--
--`struct passwd * getpwnam (const char *NAME)'
--     `pwd.h' (POSIX.1):  *Note Lookup User::.
--
--`int getpwnam_r (const char *NAME, struct passwd *RESULT_BUF, char *BUFFER, 
size_t BUFLEN, struct passwd **RESULT)'
--     `pwd.h' (POSIX.1c):  *Note Lookup User::.
--
--`struct passwd * getpwuid (uid_t UID)'
--     `pwd.h' (POSIX.1):  *Note Lookup User::.
--
--`int getpwuid_r (uid_t UID, struct passwd *RESULT_BUF, char *BUFFER, size_t 
BUFLEN, struct passwd **RESULT)'
--     `pwd.h' (POSIX.1c):  *Note Lookup User::.
--
--`int getrlimit (int RESOURCE, struct rlimit *RLP)'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`int getrusage (int PROCESSES, struct rusage *RUSAGE)'
--     `sys/resource.h' (BSD):  *Note Resource Usage::.
--
--`struct servent * getservbyname (const char *NAME, const char *PROTO)'
--     `netdb.h' (BSD):  *Note Services Database::.
--
--`struct servent * getservbyport (int PORT, const char *PROTO)'
--     `netdb.h' (BSD):  *Note Services Database::.
--
--`struct servent * getservent (void)'
--     `netdb.h' (BSD):  *Note Services Database::.
--
--`char * gets (char *S)'
--     `stdio.h' (ISO):  *Note Line Input::.
--
--`int getsockname (int SOCKET, struct sockaddr *ADDR, size_t *LENGTH-PTR)'
--     `sys/socket.h' (BSD):  *Note Reading Address::.
--
--`int getsockopt (int SOCKET, int LEVEL, int OPTNAME, void *OPTVAL, size_t 
*OPTLEN-PTR)'
--     `sys/socket.h' (BSD):  *Note Socket Option Functions::.
--
--`int getsubopt (char **OPTIONP, const char* const *TOKENS, char **VALUEP)'
--     `stdlib.h' (stdlib.h):  *Note Suboptions::.
--
--`int gettimeofday (struct timeval *TP, struct timezone *TZP)'
--     `sys/time.h' (BSD):  *Note High-Resolution Calendar::.
--
--`uid_t getuid (void)'
--     `unistd.h' (POSIX.1):  *Note Reading Persona::.
--
--`mode_t getumask (void)'
--     `sys/stat.h' (GNU):  *Note Setting Permissions::.
--
--`char * getwd (char *BUFFER)'
--     `unistd.h' (BSD):  *Note Working Directory::.
--
--`int getw (FILE *STREAM)'
--     `stdio.h' (SVID):  *Note Character Input::.
--
--`gid_t'
--     `sys/types.h' (POSIX.1):  *Note Reading Persona::.
--
--`GLOB_ABORTED'
--     `glob.h' (POSIX.2):  *Note Calling Glob::.
--
--`GLOB_APPEND'
--     `glob.h' (POSIX.2):  *Note Flags for Globbing::.
--
--`GLOB_DOOFFS'
--     `glob.h' (POSIX.2):  *Note Flags for Globbing::.
--
--`GLOB_ERR'
--     `glob.h' (POSIX.2):  *Note Flags for Globbing::.
--
--`int glob (const char *PATTERN, int FLAGS, int (*ERRFUNC) (const char 
*FILENAME, int ERROR-CODE), glob_t *VECTOR-PTR)'
--     `glob.h' (POSIX.2):  *Note Calling Glob::.
--
--`GLOB_MARK'
--     `glob.h' (POSIX.2):  *Note Flags for Globbing::.
--
--`GLOB_NOCHECK'
--     `glob.h' (POSIX.2):  *Note Flags for Globbing::.
--
--`GLOB_NOESCAPE'
--     `glob.h' (POSIX.2):  *Note Flags for Globbing::.
--
--`GLOB_NOMATCH'
--     `glob.h' (POSIX.2):  *Note Calling Glob::.
--
--`GLOB_NOSORT'
--     `glob.h' (POSIX.2):  *Note Flags for Globbing::.
--
--`GLOB_NOSPACE'
--     `glob.h' (POSIX.2):  *Note Calling Glob::.
--
--`glob_t'
--     `glob.h' (POSIX.2):  *Note Calling Glob::.
--
--`struct tm * gmtime (const time_t *TIME)'
--     `time.h' (ISO):  *Note Broken-down Time::.
--
--`_GNU_SOURCE'
--     (GNU):  *Note Feature Test Macros::.
--
--`int gsignal (int SIGNUM)'
--     `signal.h' (SVID):  *Note Signaling Yourself::.
--
--`HOST_NOT_FOUND'
--     `netdb.h' (BSD):  *Note Host Names::.
--
--`unsigned long int htonl (unsigned long int HOSTLONG)'
--     `netinet/in.h' (BSD):  *Note Byte Order::.
--
--`unsigned short int htons (unsigned short int HOSTSHORT)'
--     `netinet/in.h' (BSD):  *Note Byte Order::.
--
--`float HUGE_VALf'
--     `math.h' (GNU):  *Note Domain and Range Errors::.
--
--`double HUGE_VAL'
--     `math.h' (ISO):  *Note Domain and Range Errors::.
--
--`long double HUGE_VALl'
--     `math.h' (GNU):  *Note Domain and Range Errors::.
--
--`tcflag_t HUPCL'
--     `termios.h' (POSIX.1):  *Note Control Modes::.
--
--`double hypot (double X, double Y)'
--     `math.h' (BSD):  *Note Exponents and Logarithms::.
--
--`tcflag_t ICANON'
--     `termios.h' (POSIX.1):  *Note Local Modes::.
--
--`tcflag_t ICRNL'
--     `termios.h' (POSIX.1):  *Note Input Modes::.
--
--`tcflag_t IEXTEN'
--     `termios.h' (POSIX.1):  *Note Local Modes::.
--
--`tcflag_t IGNBRK'
--     `termios.h' (POSIX.1):  *Note Input Modes::.
--
--`tcflag_t IGNCR'
--     `termios.h' (POSIX.1):  *Note Input Modes::.
--
--`tcflag_t IGNPAR'
--     `termios.h' (POSIX.1):  *Note Input Modes::.
--
--`tcflag_t IMAXBEL'
--     `termios.h' (BSD):  *Note Input Modes::.
--
--`unsigned long int INADDR_ANY'
--     `netinet/in.h' (BSD):  *Note Host Address Data Type::.
--
--`unsigned long int INADDR_BROADCAST'
--     `netinet/in.h' (BSD):  *Note Host Address Data Type::.
--
--`unsigned long int INADDR_LOOPBACK'
--     `netinet/in.h' (BSD):  *Note Host Address Data Type::.
--
--`unsigned long int INADDR_NONE'
--     `netinet/in.h' (BSD):  *Note Host Address Data Type::.
--
--`char * index (const char *STRING, int C)'
--     `string.h' (BSD):  *Note Search Functions::.
--
--`unsigned long int inet_addr (const char *NAME)'
--     `arpa/inet.h' (BSD):  *Note Host Address Functions::.
--
--`int inet_aton (const char *NAME, struct in_addr *ADDR)'
--     `arpa/inet.h' (BSD):  *Note Host Address Functions::.
--
--`int inet_lnaof (struct in_addr ADDR)'
--     `arpa/inet.h' (BSD):  *Note Host Address Functions::.
--
--`struct in_addr inet_makeaddr (int NET, int LOCAL)'
--     `arpa/inet.h' (BSD):  *Note Host Address Functions::.
--
--`int inet_netof (struct in_addr ADDR)'
--     `arpa/inet.h' (BSD):  *Note Host Address Functions::.
--
--`unsigned long int inet_network (const char *NAME)'
--     `arpa/inet.h' (BSD):  *Note Host Address Functions::.
--
--`char * inet_ntoa (struct in_addr ADDR)'
--     `arpa/inet.h' (BSD):  *Note Host Address Functions::.
--
--`double infnan (int ERROR)'
--     `math.h' (BSD):  *Note Predicates on Floats::.
--
--`int initgroups (const char *USER, gid_t GID)'
--     `grp.h' (BSD):  *Note Setting Groups::.
--
--`void * initstate (unsigned int SEED, void *STATE, size_t SIZE)'
--     `stdlib.h' (BSD):  *Note BSD Random::.
--
--`tcflag_t INLCR'
--     `termios.h' (POSIX.1):  *Note Input Modes::.
--
--`int innetgr (const char *NETGROUP, const char *HOST, const char *USER, const 
char *DOMAIN)'
--     `netdb.h' (netdb.h):  *Note Netgroup Membership::.
--
--`ino_t'
--     `sys/types.h' (POSIX.1):  *Note Attribute Meanings::.
--
--`tcflag_t INPCK'
--     `termios.h' (POSIX.1):  *Note Input Modes::.
--
--`int RLIM_INFINITY'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`INT_MAX'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`INT_MIN'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`int _IOFBF'
--     `stdio.h' (ISO):  *Note Controlling Buffering::.
--
--`int _IOLBF'
--     `stdio.h' (ISO):  *Note Controlling Buffering::.
--
--`int _IONBF'
--     `stdio.h' (ISO):  *Note Controlling Buffering::.
--
--`int IPPORT_RESERVED'
--     `netinet/in.h' (BSD):  *Note Ports::.
--
--`int IPPORT_USERRESERVED'
--     `netinet/in.h' (BSD):  *Note Ports::.
--
--`int isalnum (int C)'
--     `ctype.h' (ISO):  *Note Classification of Characters::.
--
--`int isalpha (int C)'
--     `ctype.h' (ISO):  *Note Classification of Characters::.
--
--`int isascii (int C)'
--     `ctype.h' (SVID, BSD):  *Note Classification of Characters::.
--
--`int isatty (int FILEDES)'
--     `unistd.h' (POSIX.1):  *Note Is It a Terminal::.
--
--`int isblank (int C)'
--     `ctype.h' (GNU):  *Note Classification of Characters::.
--
--`int iscntrl (int C)'
--     `ctype.h' (ISO):  *Note Classification of Characters::.
--
--`int isdigit (int C)'
--     `ctype.h' (ISO):  *Note Classification of Characters::.
--
--`int isgraph (int C)'
--     `ctype.h' (ISO):  *Note Classification of Characters::.
--
--`tcflag_t ISIG'
--     `termios.h' (POSIX.1):  *Note Local Modes::.
--
--`int isinf (double X)'
--     `math.h' (BSD):  *Note Predicates on Floats::.
--
--`int islower (int C)'
--     `ctype.h' (ISO):  *Note Classification of Characters::.
--
--`int isnan (double X)'
--     `math.h' (BSD):  *Note Predicates on Floats::.
--
--`int isprint (int C)'
--     `ctype.h' (ISO):  *Note Classification of Characters::.
--
--`int ispunct (int C)'
--     `ctype.h' (ISO):  *Note Classification of Characters::.
--
--`int isspace (int C)'
--     `ctype.h' (ISO):  *Note Classification of Characters::.
--
--`tcflag_t ISTRIP'
--     `termios.h' (POSIX.1):  *Note Input Modes::.
--
--`int isupper (int C)'
--     `ctype.h' (ISO):  *Note Classification of Characters::.
--
--`int isxdigit (int C)'
--     `ctype.h' (ISO):  *Note Classification of Characters::.
--
--`ITIMER_PROF'
--     `sys/time.h' (BSD):  *Note Setting an Alarm::.
--
--`ITIMER_REAL'
--     `sys/time.h' (BSD):  *Note Setting an Alarm::.
--
--`ITIMER_VIRTUAL'
--     `sys/time.h' (BSD):  *Note Setting an Alarm::.
--
--`tcflag_t IXANY'
--     `termios.h' (BSD):  *Note Input Modes::.
--
--`tcflag_t IXOFF'
--     `termios.h' (POSIX.1):  *Note Input Modes::.
--
--`tcflag_t IXON'
--     `termios.h' (POSIX.1):  *Note Input Modes::.
--
--`jmp_buf'
--     `setjmp.h' (ISO):  *Note Non-Local Details::.
--
--`int kill (pid_t PID, int SIGNUM)'
--     `signal.h' (POSIX.1):  *Note Signaling Another Process::.
--
--`int killpg (int PGID, int SIGNUM)'
--     `signal.h' (BSD):  *Note Signaling Another Process::.
--
--`long int labs (long int NUMBER)'
--     `stdlib.h' (ISO):  *Note Absolute Value::.
--
--`LANG'
--     `locale.h' (ISO):  *Note Locale Categories::.
--
--`LC_ALL'
--     `locale.h' (ISO):  *Note Locale Categories::.
--
--`LC_COLLATE'
--     `locale.h' (ISO):  *Note Locale Categories::.
--
--`LC_CTYPE'
--     `locale.h' (ISO):  *Note Locale Categories::.
--
--`LC_MESSAGES'
--     `locale.h' (XOPEN):  *Note Locale Categories::.
--
--`LC_MONETARY'
--     `locale.h' (ISO):  *Note Locale Categories::.
--
--`LC_NUMERIC'
--     `locale.h' (ISO):  *Note Locale Categories::.
--
--`int L_ctermid'
--     `stdio.h' (POSIX.1):  *Note Identifying the Terminal::.
--
--`LC_TIME'
--     `locale.h' (ISO):  *Note Locale Categories::.
--
--`int L_cuserid'
--     `stdio.h' (POSIX.1):  *Note Who Logged In::.
--
--`double ldexp (double VALUE, int EXPONENT)'
--     `math.h' (ISO):  *Note Normalization Functions::.
--
--`ldiv_t ldiv (long int NUMERATOR, long int DENOMINATOR)'
--     `stdlib.h' (ISO):  *Note Integer Division::.
--
--`ldiv_t'
--     `stdlib.h' (ISO):  *Note Integer Division::.
--
--`L_INCR'
--     `sys/file.h' (BSD):  *Note File Positioning::.
--
--`int LINE_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Limits::.
--
--`int link (const char *OLDNAME, const char *NEWNAME)'
--     `unistd.h' (POSIX.1):  *Note Hard Links::.
--
--`int LINK_MAX'
--     `limits.h' (POSIX.1):  *Note Limits for Files::.
--
--`int listen (int SOCKET, unsigned int N)'
--     `sys/socket.h' (BSD):  *Note Listening::.
--
--`struct lconv * localeconv (void)'
--     `locale.h' (ISO):  *Note Numeric Formatting::.
--
--`struct tm * localtime (const time_t *TIME)'
--     `time.h' (ISO):  *Note Broken-down Time::.
--
--`double log10 (double X)'
--     `math.h' (ISO):  *Note Exponents and Logarithms::.
--
--`double log1p (double X)'
--     `math.h' (BSD):  *Note Exponents and Logarithms::.
--
--`double logb (double X)'
--     `math.h' (BSD):  *Note Normalization Functions::.
--
--`double log (double X)'
--     `math.h' (ISO):  *Note Exponents and Logarithms::.
--
--`void longjmp (jmp_buf STATE, int VALUE)'
--     `setjmp.h' (ISO):  *Note Non-Local Details::.
--
--`LONG_LONG_MAX'
--     `limits.h' (GNU):  *Note Range of Type::.
--
--`LONG_LONG_MIN'
--     `limits.h' (GNU):  *Note Range of Type::.
--
--`LONG_MAX'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`LONG_MIN'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`off_t lseek (int FILEDES, off_t OFFSET, int WHENCE)'
--     `unistd.h' (POSIX.1):  *Note File Position Primitive::.
--
--`L_SET'
--     `sys/file.h' (BSD):  *Note File Positioning::.
--
--`int lstat (const char *FILENAME, struct stat *BUF)'
--     `sys/stat.h' (BSD):  *Note Reading Attributes::.
--
--`int L_tmpnam'
--     `stdio.h' (ISO):  *Note Temporary Files::.
--
--`L_XTND'
--     `sys/file.h' (BSD):  *Note File Positioning::.
--
--`__malloc_hook'
--     `malloc.h' (GNU):  *Note Hooks for Malloc::.
--
--`void * malloc (size_t SIZE)'
--     `malloc.h', `stdlib.h' (ISO):  *Note Basic Allocation::.
--
--`int MAX_CANON'
--     `limits.h' (POSIX.1):  *Note Limits for Files::.
--
--`int MAX_INPUT'
--     `limits.h' (POSIX.1):  *Note Limits for Files::.
--
--`int MAXNAMLEN'
--     `dirent.h' (BSD):  *Note Limits for Files::.
--
--`int MB_CUR_MAX'
--     `stdlib.h' (ISO):  *Note Multibyte Char Intro::.
--
--`int mblen (const char *STRING, size_t SIZE)'
--     `stdlib.h' (ISO):  *Note Length of Char::.
--
--`int MB_LEN_MAX'
--     `limits.h' (ISO):  *Note Multibyte Char Intro::.
--
--`size_t mbstowcs (wchar_t *WSTRING, const char *STRING, size_t SIZE)'
--     `stdlib.h' (ISO):  *Note Wide String Conversion::.
--
--`int mbtowc (wchar_t *RESULT, const char *STRING, size_t SIZE)'
--     `stdlib.h' (ISO):  *Note Converting One Char::.
--
--`int mcheck (void (*ABORTFN) (enum mcheck_status STATUS))'
--     `malloc.h' (GNU):  *Note Heap Consistency Checking::.
--
--`tcflag_t MDMBUF'
--     `termios.h' (BSD):  *Note Control Modes::.
--
--`void * memalign (size_t BOUNDARY, size_t SIZE)'
--     `malloc.h', `stdlib.h' (BSD):  *Note Aligned Memory Blocks::.
--
--`void * memccpy (void *TO, const void *FROM, int C, size_t SIZE)'
--     `string.h' (SVID):  *Note Copying and Concatenation::.
--
--`void * memchr (const void *BLOCK, int C, size_t SIZE)'
--     `string.h' (ISO):  *Note Search Functions::.
--
--`int memcmp (const void *A1, const void *A2, size_t SIZE)'
--     `string.h' (ISO):  *Note String/Array Comparison::.
--
--`void * memcpy (void *TO, const void *FROM, size_t SIZE)'
--     `string.h' (ISO):  *Note Copying and Concatenation::.
--
--`void * memmem (const void *NEEDLE, size_t NEEDLE-LEN,
--     const void *HAYSTACK, size_t HAYSTACK-LEN)'
--     `string.h' (GNU):  *Note Search Functions::.
--
--`void * memmove (void *TO, const void *FROM, size_t SIZE)'
--     `string.h' (ISO):  *Note Copying and Concatenation::.
--
--`void memory_warnings (void *START, void (*WARN-FUNC) (const char *))'
--     `malloc.h' (GNU):  *Note Memory Warnings::.
--
--`void * memset (void *BLOCK, int C, size_t SIZE)'
--     `string.h' (ISO):  *Note Copying and Concatenation::.
--
--`int mkdir (const char *FILENAME, mode_t MODE)'
--     `sys/stat.h' (POSIX.1):  *Note Creating Directories::.
--
--`int mkfifo (const char *FILENAME, mode_t MODE)'
--     `sys/stat.h' (POSIX.1):  *Note FIFO Special Files::.
--
--`int mknod (const char *FILENAME, int MODE, int DEV)'
--     `sys/stat.h' (BSD):  *Note Making Special Files::.
--
--`int mkstemp (char *TEMPLATE)'
--     `unistd.h' (BSD):  *Note Temporary Files::.
--
--`char * mktemp (char *TEMPLATE)'
--     `unistd.h' (Unix):  *Note Temporary Files::.
--
--`time_t mktime (struct tm *BROKENTIME)'
--     `time.h' (ISO):  *Note Broken-down Time::.
--
--`mode_t'
--     `sys/types.h' (POSIX.1):  *Note Attribute Meanings::.
--
--`double modf (double VALUE, double *INTEGER-PART)'
--     `math.h' (ISO):  *Note Rounding and Remainders::.
--
--`int MSG_DONTROUTE'
--     `sys/socket.h' (BSD):  *Note Socket Data Options::.
--
--`int MSG_OOB'
--     `sys/socket.h' (BSD):  *Note Socket Data Options::.
--
--`int MSG_PEEK'
--     `sys/socket.h' (BSD):  *Note Socket Data Options::.
--
--`struct mstats mstats (void)'
--     `malloc.h' (GNU):  *Note Statistics of Malloc::.
--
--`int NAME_MAX'
--     `limits.h' (POSIX.1):  *Note Limits for Files::.
--
--`double NAN'
--     `math.h' (GNU):  *Note Not a Number::.
--
--`int NCCS'
--     `termios.h' (POSIX.1):  *Note Mode Data Types::.
--
--`int NGROUPS_MAX'
--     `limits.h' (POSIX.1):  *Note General Limits::.
--
--`int nice (int INCREMENT)'
--     `dunno.h' (dunno.h):  *Note Priority::.
--
--`nlink_t'
--     `sys/types.h' (POSIX.1):  *Note Attribute Meanings::.
--
--`NO_ADDRESS'
--     `netdb.h' (BSD):  *Note Host Names::.
--
--`tcflag_t NOFLSH'
--     `termios.h' (POSIX.1):  *Note Local Modes::.
--
--`tcflag_t NOKERNINFO'
--     `termios.h' (BSD):  *Note Local Modes::.
--
--`NO_RECOVERY'
--     `netdb.h' (BSD):  *Note Host Names::.
--
--`int NSIG'
--     `signal.h' (BSD):  *Note Standard Signals::.
--
--`unsigned long int ntohl (unsigned long int NETLONG)'
--     `netinet/in.h' (BSD):  *Note Byte Order::.
--
--`unsigned short int ntohs (unsigned short int NETSHORT)'
--     `netinet/in.h' (BSD):  *Note Byte Order::.
--
--`void * NULL'
--     `stddef.h' (ISO):  *Note Null Pointer Constant::.
--
--`int O_ACCMODE'
--     `fcntl.h' (POSIX.1):  *Note Access Modes::.
--
--`int O_APPEND'
--     `fcntl.h' (POSIX.1):  *Note Operating Modes::.
--
--`int O_ASYNC'
--     `fcntl.h' (BSD):  *Note Operating Modes::.
--
--`void obstack_1grow_fast (struct obstack *OBSTACK-PTR, char C)'
--     `obstack.h' (GNU):  *Note Extra Fast Growing::.
--
--`void obstack_1grow (struct obstack *OBSTACK-PTR, char C)'
--     `obstack.h' (GNU):  *Note Growing Objects::.
--
--`int obstack_alignment_mask (struct obstack *OBSTACK-PTR)'
--     `obstack.h' (GNU):  *Note Obstacks Data Alignment::.
--
--`void * obstack_alloc (struct obstack *OBSTACK-PTR, int SIZE)'
--     `obstack.h' (GNU):  *Note Allocation in an Obstack::.
--
--`void * obstack_base (struct obstack *OBSTACK-PTR)'
--     `obstack.h' (GNU):  *Note Status of an Obstack::.
--
--`void obstack_blank_fast (struct obstack *OBSTACK-PTR, int SIZE)'
--     `obstack.h' (GNU):  *Note Extra Fast Growing::.
--
--`void obstack_blank (struct obstack *OBSTACK-PTR, int SIZE)'
--     `obstack.h' (GNU):  *Note Growing Objects::.
--
--`int obstack_chunk_size (struct obstack *OBSTACK-PTR)'
--     `obstack.h' (GNU):  *Note Obstack Chunks::.
--
--`void * obstack_copy0 (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
--     `obstack.h' (GNU):  *Note Allocation in an Obstack::.
--
--`void * obstack_copy (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
--     `obstack.h' (GNU):  *Note Allocation in an Obstack::.
--
--`void * obstack_finish (struct obstack *OBSTACK-PTR)'
--     `obstack.h' (GNU):  *Note Growing Objects::.
--
--`void obstack_free (struct obstack *OBSTACK-PTR, void *OBJECT)'
--     `obstack.h' (GNU):  *Note Freeing Obstack Objects::.
--
--`void obstack_grow0 (struct obstack *OBSTACK-PTR, void *DATA, int SIZE)'
--     `obstack.h' (GNU):  *Note Growing Objects::.
--
--`void obstack_grow (struct obstack *OBSTACK-PTR, void *DATA, int SIZE)'
--     `obstack.h' (GNU):  *Note Growing Objects::.
--
--`int obstack_init (struct obstack *OBSTACK-PTR)'
--     `obstack.h' (GNU):  *Note Preparing for Obstacks::.
--
--`void obstack_int_grow_fast (struct obstack *OBSTACK-PTR, int DATA)'
--     `obstack.h' (GNU):  *Note Extra Fast Growing::.
--
--`void obstack_int_grow (struct obstack *OBSTACK-PTR, int DATA)'
--     `obstack.h' (GNU):  *Note Growing Objects::.
--
--`void * obstack_next_free (struct obstack *OBSTACK-PTR)'
--     `obstack.h' (GNU):  *Note Status of an Obstack::.
--
--`int obstack_object_size (struct obstack *OBSTACK-PTR)'
--     `obstack.h' (GNU):  *Note Growing Objects::.
--
--`int obstack_object_size (struct obstack *OBSTACK-PTR)'
--     `obstack.h' (GNU):  *Note Status of an Obstack::.
--
--`int obstack_printf (struct obstack *OBSTACK, const char *TEMPLATE, ...)'
--     `stdio.h' (GNU):  *Note Dynamic Output::.
--
--`void obstack_ptr_grow_fast (struct obstack *OBSTACK-PTR, void *DATA)'
--     `obstack.h' (GNU):  *Note Extra Fast Growing::.
--
--`void obstack_ptr_grow (struct obstack *OBSTACK-PTR, void *DATA)'
--     `obstack.h' (GNU):  *Note Growing Objects::.
--
--`int obstack_room (struct obstack *OBSTACK-PTR)'
--     `obstack.h' (GNU):  *Note Extra Fast Growing::.
--
--`int obstack_vprintf (struct obstack *OBSTACK, const char *TEMPLATE, va_list 
AP)'
--     `stdio.h' (GNU):  *Note Variable Arguments Output::.
--
--`int O_CREAT'
--     `fcntl.h' (POSIX.1):  *Note Open-time Flags::.
--
--`int O_EXCL'
--     `fcntl.h' (POSIX.1):  *Note Open-time Flags::.
--
--`int O_EXEC'
--     `fcntl.h' (GNU):  *Note Access Modes::.
--
--`int O_EXLOCK'
--     `fcntl.h' (BSD):  *Note Open-time Flags::.
--
--`size_t offsetof (TYPE, MEMBER)'
--     `stddef.h' (ISO):  *Note Structure Measurement::.
--
--`off_t'
--     `sys/types.h' (POSIX.1):  *Note File Position Primitive::.
--
--`int O_FSYNC'
--     `fcntl.h' (BSD):  *Note Operating Modes::.
--
--`int O_IGNORE_CTTY'
--     `fcntl.h' (GNU):  *Note Open-time Flags::.
--
--`int O_NDELAY'
--     `fcntl.h' (BSD):  *Note Operating Modes::.
--
--`int on_exit (void (*FUNCTION)(int STATUS, void *ARG), void *ARG)'
--     `stdlib.h' (SunOS):  *Note Cleanups on Exit::.
--
--`tcflag_t ONLCR'
--     `termios.h' (BSD):  *Note Output Modes::.
--
--`int O_NOATIME'
--     `fcntl.h' (GNU):  *Note Operating Modes::.
--
--`int O_NOCTTY'
--     `fcntl.h' (POSIX.1):  *Note Open-time Flags::.
--
--`tcflag_t ONOEOT'
--     `termios.h' (BSD):  *Note Output Modes::.
--
--`int O_NOLINK'
--     `fcntl.h' (GNU):  *Note Open-time Flags::.
--
--`int O_NONBLOCK'
--     `fcntl.h' (POSIX.1):  *Note Open-time Flags::.
--
--`int O_NONBLOCK'
--     `fcntl.h' (POSIX.1):  *Note Operating Modes::.
--
--`int O_NOTRANS'
--     `fcntl.h' (GNU):  *Note Open-time Flags::.
--
--`DIR * opendir (const char *DIRNAME)'
--     `dirent.h' (POSIX.1):  *Note Opening a Directory::.
--
--`int open (const char *FILENAME, int FLAGS[, mode_t MODE])'
--     `fcntl.h' (POSIX.1):  *Note Opening and Closing Files::.
--
--`int OPEN_MAX'
--     `limits.h' (POSIX.1):  *Note General Limits::.
--
--`FILE * open_memstream (char **PTR, size_t *SIZELOC)'
--     `stdio.h' (GNU):  *Note String Streams::.
--
--`FILE * open_obstack_stream (struct obstack *OBSTACK)'
--     `stdio.h' (GNU):  *Note Obstack Streams::.
--
--`tcflag_t OPOST'
--     `termios.h' (POSIX.1):  *Note Output Modes::.
--
--`char * optarg'
--     `unistd.h' (POSIX.2):  *Note Parsing Options::.
--
--`int opterr'
--     `unistd.h' (POSIX.2):  *Note Parsing Options::.
--
--`int optind'
--     `unistd.h' (POSIX.2):  *Note Parsing Options::.
--
--`int optopt'
--     `unistd.h' (POSIX.2):  *Note Parsing Options::.
--
--`int O_RDONLY'
--     `fcntl.h' (POSIX.1):  *Note Access Modes::.
--
--`int O_RDWR'
--     `fcntl.h' (POSIX.1):  *Note Access Modes::.
--
--`int O_READ'
--     `fcntl.h' (GNU):  *Note Access Modes::.
--
--`int O_SHLOCK'
--     `fcntl.h' (BSD):  *Note Open-time Flags::.
--
--`int O_SYNC'
--     `fcntl.h' (BSD):  *Note Operating Modes::.
--
--`int O_TRUNC'
--     `fcntl.h' (POSIX.1):  *Note Open-time Flags::.
--
--`int O_WRITE'
--     `fcntl.h' (GNU):  *Note Access Modes::.
--
--`int O_WRONLY'
--     `fcntl.h' (POSIX.1):  *Note Access Modes::.
--
--`tcflag_t OXTABS'
--     `termios.h' (BSD):  *Note Output Modes::.
--
--`PA_CHAR'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`PA_DOUBLE'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`PA_FLAG_LONG_DOUBLE'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`PA_FLAG_LONG'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`PA_FLAG_LONG_LONG'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`int PA_FLAG_MASK'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`PA_FLAG_PTR'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`PA_FLAG_SHORT'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`PA_FLOAT'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`PA_INT'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`PA_LAST'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`PA_POINTER'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`tcflag_t PARENB'
--     `termios.h' (POSIX.1):  *Note Control Modes::.
--
--`tcflag_t PARMRK'
--     `termios.h' (POSIX.1):  *Note Input Modes::.
--
--`tcflag_t PARODD'
--     `termios.h' (POSIX.1):  *Note Control Modes::.
--
--`size_t parse_printf_format (const char *TEMPLATE, size_t N, int *ARGTYPES)'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`PA_STRING'
--     `printf.h' (GNU):  *Note Parsing a Template String::.
--
--`long int pathconf (const char *FILENAME, int PARAMETER)'
--     `unistd.h' (POSIX.1):  *Note Pathconf::.
--
--`int PATH_MAX'
--     `limits.h' (POSIX.1):  *Note Limits for Files::.
--
--`int pause ()'
--     `unistd.h' (POSIX.1):  *Note Using Pause::.
--
--`_PC_CHOWN_RESTRICTED'
--     `unistd.h' (POSIX.1):  *Note Pathconf::.
--
--`_PC_LINK_MAX'
--     `unistd.h' (POSIX.1):  *Note Pathconf::.
--
--`int pclose (FILE *STREAM)'
--     `stdio.h' (POSIX.2, SVID, BSD):  *Note Pipe to a Subprocess::.
--
--`_PC_MAX_CANON'
--     `unistd.h' (POSIX.1):  *Note Pathconf::.
--
--`_PC_MAX_INPUT'
--     `unistd.h' (POSIX.1):  *Note Pathconf::.
--
--`_PC_NAME_MAX'
--     `unistd.h' (POSIX.1):  *Note Pathconf::.
--
--`_PC_NO_TRUNC'
--     `unistd.h' (POSIX.1):  *Note Pathconf::.
--
--`_PC_PATH_MAX'
--     `unistd.h' (POSIX.1):  *Note Pathconf::.
--
--`_PC_PIPE_BUF'
--     `unistd.h' (POSIX.1):  *Note Pathconf::.
--
--`_PC_VDISABLE'
--     `unistd.h' (POSIX.1):  *Note Pathconf::.
--
--`tcflag_t PENDIN'
--     `termios.h' (BSD):  *Note Local Modes::.
--
--`void perror (const char *MESSAGE)'
--     `stdio.h' (ISO):  *Note Error Messages::.
--
--`int PF_FILE'
--     `sys/socket.h' (GNU):  *Note File Namespace Details::.
--
--`int PF_INET'
--     `sys/socket.h' (BSD):  *Note Internet Namespace::.
--
--`int PF_UNIX'
--     `sys/socket.h' (BSD):  *Note File Namespace Details::.
--
--`pid_t'
--     `sys/types.h' (POSIX.1):  *Note Process Identification::.
--
--`int PIPE_BUF'
--     `limits.h' (POSIX.1):  *Note Limits for Files::.
--
--`int pipe (int FILEDES[2])'
--     `unistd.h' (POSIX.1):  *Note Creating a Pipe::.
--
--`FILE * popen (const char *COMMAND, const char *MODE)'
--     `stdio.h' (POSIX.2, SVID, BSD):  *Note Pipe to a Subprocess::.
--
--`_POSIX2_BC_BASE_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Minimums::.
--
--`_POSIX2_BC_DIM_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Minimums::.
--
--`_POSIX2_BC_SCALE_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Minimums::.
--
--`_POSIX2_BC_STRING_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Minimums::.
--
--`int _POSIX2_C_DEV'
--     `unistd.h' (POSIX.2):  *Note System Options::.
--
--`_POSIX2_COLL_WEIGHTS_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Minimums::.
--
--`long int _POSIX2_C_VERSION'
--     `unistd.h' (POSIX.2):  *Note Version Supported::.
--
--`_POSIX2_EQUIV_CLASS_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Minimums::.
--
--`_POSIX2_EXPR_NEST_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Minimums::.
--
--`int _POSIX2_FORT_DEV'
--     `unistd.h' (POSIX.2):  *Note System Options::.
--
--`int _POSIX2_FORT_RUN'
--     `unistd.h' (POSIX.2):  *Note System Options::.
--
--`_POSIX2_LINE_MAX'
--     `limits.h' (POSIX.2):  *Note Utility Minimums::.
--
--`int _POSIX2_LOCALEDEF'
--     `unistd.h' (POSIX.2):  *Note System Options::.
--
--`_POSIX2_RE_DUP_MAX'
--     `limits.h' (POSIX.2):  *Note Minimums::.
--
--`int _POSIX2_SW_DEV'
--     `unistd.h' (POSIX.2):  *Note System Options::.
--
--`_POSIX_ARG_MAX'
--     `limits.h' (POSIX.1):  *Note Minimums::.
--
--`_POSIX_CHILD_MAX'
--     `limits.h' (POSIX.1):  *Note Minimums::.
--
--`int _POSIX_CHOWN_RESTRICTED'
--     `unistd.h' (POSIX.1):  *Note Options for Files::.
--
--`_POSIX_C_SOURCE'
--     (POSIX.2):  *Note Feature Test Macros::.
--
--`int _POSIX_JOB_CONTROL'
--     `unistd.h' (POSIX.1):  *Note System Options::.
--
--`_POSIX_LINK_MAX'
--     `limits.h' (POSIX.1):  *Note File Minimums::.
--
--`_POSIX_MAX_CANON'
--     `limits.h' (POSIX.1):  *Note File Minimums::.
--
--`_POSIX_MAX_INPUT'
--     `limits.h' (POSIX.1):  *Note File Minimums::.
--
--`_POSIX_NAME_MAX'
--     `limits.h' (POSIX.1):  *Note File Minimums::.
--
--`_POSIX_NGROUPS_MAX'
--     `limits.h' (POSIX.1):  *Note Minimums::.
--
--`int _POSIX_NO_TRUNC'
--     `unistd.h' (POSIX.1):  *Note Options for Files::.
--
--`_POSIX_OPEN_MAX'
--     `limits.h' (POSIX.1):  *Note Minimums::.
--
--`_POSIX_PATH_MAX'
--     `limits.h' (POSIX.1):  *Note File Minimums::.
--
--`_POSIX_PIPE_BUF'
--     `limits.h' (POSIX.1):  *Note File Minimums::.
--
--`int _POSIX_SAVED_IDS'
--     `unistd.h' (POSIX.1):  *Note System Options::.
--
--`_POSIX_SOURCE'
--     (POSIX.1):  *Note Feature Test Macros::.
--
--`_POSIX_SSIZE_MAX'
--     `limits.h' (POSIX.1):  *Note Minimums::.
--
--`_POSIX_STREAM_MAX'
--     `limits.h' (POSIX.1):  *Note Minimums::.
--
--`_POSIX_TZNAME_MAX'
--     `limits.h' (POSIX.1):  *Note Minimums::.
--
--`unsigned char _POSIX_VDISABLE'
--     `unistd.h' (POSIX.1):  *Note Options for Files::.
--
--`long int _POSIX_VERSION'
--     `unistd.h' (POSIX.1):  *Note Version Supported::.
--
--`double pow (double BASE, double POWER)'
--     `math.h' (ISO):  *Note Exponents and Logarithms::.
--
--`printf_arginfo_function'
--     `printf.h' (GNU):  *Note Defining the Output Handler::.
--
--`printf_function'
--     `printf.h' (GNU):  *Note Defining the Output Handler::.
--
--`int printf (const char *TEMPLATE, ...)'
--     `stdio.h' (ISO):  *Note Formatted Output Functions::.
--
--`PRIO_MAX'
--     `sys/resource.h' (BSD):  *Note Priority::.
--
--`PRIO_MIN'
--     `sys/resource.h' (BSD):  *Note Priority::.
--
--`PRIO_PGRP'
--     `sys/resource.h' (BSD):  *Note Priority::.
--
--`PRIO_PROCESS'
--     `sys/resource.h' (BSD):  *Note Priority::.
--
--`PRIO_USER'
--     `sys/resource.h' (BSD):  *Note Priority::.
--
--`char * program_invocation_name'
--     `errno.h' (GNU):  *Note Error Messages::.
--
--`char * program_invocation_short_name'
--     `errno.h' (GNU):  *Note Error Messages::.
--
--`void psignal (int SIGNUM, const char *MESSAGE)'
--     `signal.h' (BSD):  *Note Signal Messages::.
--
--`char * P_tmpdir'
--     `stdio.h' (SVID):  *Note Temporary Files::.
--
--`ptrdiff_t'
--     `stddef.h' (ISO):  *Note Important Data Types::.
--
--`int putchar (int C)'
--     `stdio.h' (ISO):  *Note Simple Output::.
--
--`int putc (int C, FILE *STREAM)'
--     `stdio.h' (ISO):  *Note Simple Output::.
--
--`int putenv (const char *STRING)'
--     `stdlib.h' (SVID):  *Note Environment Access::.
--
--`int putpwent (const struct passwd *P, FILE *STREAM)'
--     `pwd.h' (SVID):  *Note Writing a User Entry::.
--
--`int puts (const char *S)'
--     `stdio.h' (ISO):  *Note Simple Output::.
--
--`int putw (int W, FILE *STREAM)'
--     `stdio.h' (SVID):  *Note Simple Output::.
--
--`void qsort (void *ARRAY, size_t COUNT, size_t SIZE, comparison_fn_t COMPARE)'
--     `stdlib.h' (ISO):  *Note Array Sort Function::.
--
--`int raise (int SIGNUM)'
--     `signal.h' (ISO):  *Note Signaling Yourself::.
--
--`void r_alloc_free (void **HANDLEPTR)'
--     `malloc.h' (GNU):  *Note Using Relocator::.
--
--`void * r_alloc (void **HANDLEPTR, size_t SIZE)'
--     `malloc.h' (GNU):  *Note Using Relocator::.
--
--`int rand ()'
--     `stdlib.h' (ISO):  *Note ISO Random::.
--
--`int RAND_MAX'
--     `stdlib.h' (ISO):  *Note ISO Random::.
--
--`long int random ()'
--     `stdlib.h' (BSD):  *Note BSD Random::.
--
--`struct dirent * readdir (DIR *DIRSTREAM)'
--     `dirent.h' (POSIX.1):  *Note Reading/Closing Directory::.
--
--`int readdir_r (DIR *DIRSTREAM, struct *ENTRY, struct **RESULT)'
--     `dirent.h' (GNU):  *Note Reading/Closing Directory::.
--
--`ssize_t read (int FILEDES, void *BUFFER, size_t SIZE)'
--     `unistd.h' (POSIX.1):  *Note I/O Primitives::.
--
--`int readlink (const char *FILENAME, char *BUFFER, size_t SIZE)'
--     `unistd.h' (BSD):  *Note Symbolic Links::.
--
--`__realloc_hook'
--     `malloc.h' (GNU):  *Note Hooks for Malloc::.
--
--`void * realloc (void *PTR, size_t NEWSIZE)'
--     `malloc.h', `stdlib.h' (ISO):  *Note Changing Block Size::.
--
--`int recvfrom (int SOCKET, void *BUFFER, size_t SIZE, int FLAGS, struct 
sockaddr *ADDR, size_t *LENGTH-PTR)'
--     `sys/socket.h' (BSD):  *Note Receiving Datagrams::.
--
--`int recv (int SOCKET, void *BUFFER, size_t SIZE, int FLAGS)'
--     `sys/socket.h' (BSD):  *Note Receiving Data::.
--
--`int recvmsg (int SOCKET, struct msghdr *MESSAGE, int FLAGS)'
--     `sys/socket.h' (BSD):  *Note Receiving Datagrams::.
--
--`int RE_DUP_MAX'
--     `limits.h' (POSIX.2):  *Note General Limits::.
--
--`_REENTRANT'
--     (GNU):  *Note Feature Test Macros::.
--
--`REG_BADBR'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`REG_BADPAT'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`REG_BADRPT'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`int regcomp (regex_t *COMPILED, const char *PATTERN, int CFLAGS)'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`REG_EBRACE'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`REG_EBRACK'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`REG_ECOLLATE'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`REG_ECTYPE'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`REG_EESCAPE'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`REG_EPAREN'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`REG_ERANGE'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`size_t regerror (int ERRCODE, regex_t *COMPILED, char *BUFFER, size_t 
LENGTH)'
--     `regex.h' (POSIX.2):  *Note Regexp Cleanup::.
--
--`REG_ESPACE'
--     `regex.h' (POSIX.2):  *Note Matching POSIX Regexps::.
--
--`REG_ESPACE'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`REG_ESUBREG'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`int regexec (regex_t *COMPILED, char *STRING, size_t NMATCH, regmatch_t 
MATCHPTR [], int EFLAGS)'
--     `regex.h' (POSIX.2):  *Note Matching POSIX Regexps::.
--
--`REG_EXTENDED'
--     `regex.h' (POSIX.2):  *Note Flags for POSIX Regexps::.
--
--`regex_t'
--     `regex.h' (POSIX.2):  *Note POSIX Regexp Compilation::.
--
--`void regfree (regex_t *COMPILED)'
--     `regex.h' (POSIX.2):  *Note Regexp Cleanup::.
--
--`REG_ICASE'
--     `regex.h' (POSIX.2):  *Note Flags for POSIX Regexps::.
--
--`int register_printf_function (int SPEC, printf_function HANDLER-FUNCTION, 
printf_arginfo_function ARGINFO-FUNCTION)'
--     `printf.h' (GNU):  *Note Registering New Conversions::.
--
--`regmatch_t'
--     `regex.h' (POSIX.2):  *Note Regexp Subexpressions::.
--
--`REG_NEWLINE'
--     `regex.h' (POSIX.2):  *Note Flags for POSIX Regexps::.
--
--`REG_NOMATCH'
--     `regex.h' (POSIX.2):  *Note Matching POSIX Regexps::.
--
--`REG_NOSUB'
--     `regex.h' (POSIX.2):  *Note Flags for POSIX Regexps::.
--
--`REG_NOTBOL'
--     `regex.h' (POSIX.2):  *Note Matching POSIX Regexps::.
--
--`REG_NOTEOL'
--     `regex.h' (POSIX.2):  *Note Matching POSIX Regexps::.
--
--`regoff_t'
--     `regex.h' (POSIX.2):  *Note Regexp Subexpressions::.
--
--`int remove (const char *FILENAME)'
--     `stdio.h' (ISO):  *Note Deleting Files::.
--
--`int rename (const char *OLDNAME, const char *NEWNAME)'
--     `stdio.h' (ISO):  *Note Renaming Files::.
--
--`void rewinddir (DIR *DIRSTREAM)'
--     `dirent.h' (POSIX.1):  *Note Random Access Directory::.
--
--`void rewind (FILE *STREAM)'
--     `stdio.h' (ISO):  *Note File Positioning::.
--
--`char * rindex (const char *STRING, int C)'
--     `string.h' (BSD):  *Note Search Functions::.
--
--`double rint (double X)'
--     `math.h' (BSD):  *Note Rounding and Remainders::.
--
--`RLIMIT_CORE'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`RLIMIT_CPU'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`RLIMIT_DATA'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`RLIMIT_FSIZE'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`RLIMIT_MEMLOCK'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`RLIMIT_NOFILE'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`RLIMIT_NPROC'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`RLIMIT_RSS'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`RLIMIT_STACK'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`RLIM_NLIMITS'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`int rmdir (const char *FILENAME)'
--     `unistd.h' (POSIX.1):  *Note Deleting Files::.
--
--`int R_OK'
--     `unistd.h' (POSIX.1):  *Note Testing File Access::.
--
--`void * r_re_alloc (void **HANDLEPTR, size_t SIZE)'
--     `malloc.h' (GNU):  *Note Using Relocator::.
--
--`RUSAGE_CHILDREN'
--     `sys/resource.h' (BSD):  *Note Resource Usage::.
--
--`RUSAGE_SELF'
--     `sys/resource.h' (BSD):  *Note Resource Usage::.
--
--`int SA_NOCLDSTOP'
--     `signal.h' (POSIX.1):  *Note Flags for Sigaction::.
--
--`int SA_ONSTACK'
--     `signal.h' (BSD):  *Note Flags for Sigaction::.
--
--`int SA_RESTART'
--     `signal.h' (BSD):  *Note Flags for Sigaction::.
--
--`_SC_2_C_DEV'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`_SC_2_FORT_DEV'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`_SC_2_FORT_RUN'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`_SC_2_LOCALEDEF'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`_SC_2_SW_DEV'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`_SC_2_VERSION'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`double scalb (double VALUE, int EXPONENT)'
--     `math.h' (BSD):  *Note Normalization Functions::.
--
--`int scanf (const char *TEMPLATE, ...)'
--     `stdio.h' (ISO):  *Note Formatted Input Functions::.
--
--`_SC_ARG_MAX'
--     `unistd.h' (POSIX.1):  *Note Constants for Sysconf::.
--
--`_SC_BC_BASE_MAX'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`_SC_BC_DIM_MAX'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`_SC_BC_SCALE_MAX'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`_SC_BC_STRING_MAX'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`_SC_CHILD_MAX'
--     `unistd.h' (POSIX.1):  *Note Constants for Sysconf::.
--
--`_SC_CLK_TCK'
--     `unistd.h' (POSIX.1):  *Note Constants for Sysconf::.
--
--`_SC_COLL_WEIGHTS_MAX'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`_SC_EQUIV_CLASS_MAX'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`_SC_EXPR_NEST_MAX'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`SCHAR_MAX'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`SCHAR_MIN'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`_SC_JOB_CONTROL'
--     `unistd.h' (POSIX.1):  *Note Constants for Sysconf::.
--
--`_SC_LINE_MAX'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`_SC_NGROUPS_MAX'
--     `unistd.h' (POSIX.1):  *Note Constants for Sysconf::.
--
--`_SC_OPEN_MAX'
--     `unistd.h' (POSIX.1):  *Note Constants for Sysconf::.
--
--`_SC_PAGESIZE'
--     `unistd.h' (GNU):  *Note Constants for Sysconf::.
--
--`_SC_SAVED_IDS'
--     `unistd.h' (POSIX.1):  *Note Constants for Sysconf::.
--
--`_SC_STREAM_MAX'
--     `unistd.h' (POSIX.1):  *Note Constants for Sysconf::.
--
--`_SC_TZNAME_MAX'
--     `unistd.h' (POSIX.1):  *Note Constants for Sysconf::.
--
--`_SC_VERSION'
--     `unistd.h' (POSIX.1):  *Note Constants for Sysconf::.
--
--`_SC_VERSION'
--     `unistd.h' (POSIX.2):  *Note Constants for Sysconf::.
--
--`int SEEK_CUR'
--     `stdio.h' (ISO):  *Note File Positioning::.
--
--`void seekdir (DIR *DIRSTREAM, off_t POS)'
--     `dirent.h' (BSD):  *Note Random Access Directory::.
--
--`int SEEK_END'
--     `stdio.h' (ISO):  *Note File Positioning::.
--
--`int SEEK_SET'
--     `stdio.h' (ISO):  *Note File Positioning::.
--
--`int select (int NFDS, fd_set *READ-FDS, fd_set *WRITE-FDS, fd_set 
*EXCEPT-FDS, struct timeval *TIMEOUT)'
--     `sys/types.h' (BSD):  *Note Waiting for I/O::.
--
--`int send (int SOCKET, void *BUFFER, size_t SIZE, int FLAGS)'
--     `sys/socket.h' (BSD):  *Note Sending Data::.
--
--`int sendmsg (int SOCKET, const struct msghdr *MESSAGE, int FLAGS)'
--     `sys/socket.h' (BSD):  *Note Receiving Datagrams::.
--
--`int sendto (int SOCKET, void *BUFFER. size_t SIZE, int FLAGS, struct 
sockaddr *ADDR, size_t LENGTH)'
--     `sys/socket.h' (BSD):  *Note Sending Datagrams::.
--
--`void setbuffer (FILE *STREAM, char *BUF, size_t SIZE)'
--     `stdio.h' (BSD):  *Note Controlling Buffering::.
--
--`void setbuf (FILE *STREAM, char *BUF)'
--     `stdio.h' (ISO):  *Note Controlling Buffering::.
--
--`int setgid (gid_t NEWGID)'
--     `unistd.h' (POSIX.1):  *Note Setting Groups::.
--
--`void setgrent (void)'
--     `grp.h' (SVID, BSD):  *Note Scanning All Groups::.
--
--`int setgroups (size_t COUNT, gid_t *GROUPS)'
--     `grp.h' (BSD):  *Note Setting Groups::.
--
--`void sethostent (int STAYOPEN)'
--     `netdb.h' (BSD):  *Note Host Names::.
--
--`int sethostid (long int ID)'
--     `unistd.h' (BSD):  *Note Host Identification::.
--
--`int sethostname (const char *NAME, size_t LENGTH)'
--     `unistd.h' (BSD):  *Note Host Identification::.
--
--`int setitimer (int WHICH, struct itimerval *NEW, struct itimerval *OLD)'
--     `sys/time.h' (BSD):  *Note Setting an Alarm::.
--
--`int setjmp (jmp_buf STATE)'
--     `setjmp.h' (ISO):  *Note Non-Local Details::.
--
--`void setlinebuf (FILE *STREAM)'
--     `stdio.h' (BSD):  *Note Controlling Buffering::.
--
--`char * setlocale (int CATEGORY, const char *LOCALE)'
--     `locale.h' (ISO):  *Note Setting the Locale::.
--
--`void setnetent (int STAYOPEN)'
--     `netdb.h' (BSD):  *Note Networks Database::.
--
--`int setnetgrent (const char *NETGROUP)'
--     `netdb.h' (netdb.h):  *Note Lookup Netgroup::.
--
--`int setpgid (pid_t PID, pid_t PGID)'
--     `unistd.h' (POSIX.1):  *Note Process Group Functions::.
--
--`int setpgrp (pid_t PID, pid_t PGID)'
--     `unistd.h' (BSD):  *Note Process Group Functions::.
--
--`int setpriority (int CLASS, int ID, int PRIORITY)'
--     `sys/resource.h' (BSD):  *Note Priority::.
--
--`void setprotoent (int STAYOPEN)'
--     `netdb.h' (BSD):  *Note Protocols Database::.
--
--`void setpwent (void)'
--     `pwd.h' (SVID, BSD):  *Note Scanning All Users::.
--
--`int setregid (gid_t RGID, fid_t EGID)'
--     `unistd.h' (BSD):  *Note Setting Groups::.
--
--`int setreuid (uid_t RUID, uid_t EUID)'
--     `unistd.h' (BSD):  *Note Setting User ID::.
--
--`int setrlimit (int RESOURCE, struct rlimit *RLP)'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`void setservent (int STAYOPEN)'
--     `netdb.h' (BSD):  *Note Services Database::.
--
--`pid_t setsid (void)'
--     `unistd.h' (POSIX.1):  *Note Process Group Functions::.
--
--`int setsockopt (int SOCKET, int LEVEL, int OPTNAME, void *OPTVAL, size_t 
OPTLEN)'
--     `sys/socket.h' (BSD):  *Note Socket Option Functions::.
--
--`void * setstate (void *STATE)'
--     `stdlib.h' (BSD):  *Note BSD Random::.
--
--`int settimeofday (const struct timeval *TP, const struct timezone *TZP)'
--     `sys/time.h' (BSD):  *Note High-Resolution Calendar::.
--
--`int setuid (uid_t NEWUID)'
--     `unistd.h' (POSIX.1):  *Note Setting User ID::.
--
--`int setvbuf (FILE *STREAM, char *BUF, int MODE, size_t SIZE)'
--     `stdio.h' (ISO):  *Note Controlling Buffering::.
--
--`SHRT_MAX'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`SHRT_MIN'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`int shutdown (int SOCKET, int HOW)'
--     `sys/socket.h' (BSD):  *Note Closing a Socket::.
--
--`S_IEXEC'
--     `sys/stat.h' (BSD):  *Note Permission Bits::.
--
--`S_IFBLK'
--     `sys/stat.h' (BSD):  *Note Testing File Type::.
--
--`S_IFCHR'
--     `sys/stat.h' (BSD):  *Note Testing File Type::.
--
--`S_IFDIR'
--     `sys/stat.h' (BSD):  *Note Testing File Type::.
--
--`S_IFIFO'
--     `sys/stat.h' (BSD):  *Note Testing File Type::.
--
--`S_IFLNK'
--     `sys/stat.h' (BSD):  *Note Testing File Type::.
--
--`int S_IFMT'
--     `sys/stat.h' (BSD):  *Note Testing File Type::.
--
--`S_IFREG'
--     `sys/stat.h' (BSD):  *Note Testing File Type::.
--
--`S_IFSOCK'
--     `sys/stat.h' (BSD):  *Note Testing File Type::.
--
--`int SIGABRT'
--     `signal.h' (ISO):  *Note Program Error Signals::.
--
--`int sigaction (int SIGNUM, const struct sigaction *ACTION, struct sigaction 
*OLD-ACTION)'
--     `signal.h' (POSIX.1):  *Note Advanced Signal Handling::.
--
--`int sigaddset (sigset_t *SET, int SIGNUM)'
--     `signal.h' (POSIX.1):  *Note Signal Sets::.
--
--`int SIGALRM'
--     `signal.h' (POSIX.1):  *Note Alarm Signals::.
--
--`int sigaltstack (const struct sigaltstack *STACK, struct sigaltstack 
*OLDSTACK)'
--     `signal.h' (BSD):  *Note Signal Stack::.
--
--`sig_atomic_t'
--     `signal.h' (ISO):  *Note Atomic Types::.
--
--`SIG_BLOCK'
--     `signal.h' (POSIX.1):  *Note Process Signal Mask::.
--
--`int sigblock (int MASK)'
--     `signal.h' (BSD):  *Note Blocking in BSD::.
--
--`int SIGBUS'
--     `signal.h' (BSD):  *Note Program Error Signals::.
--
--`int SIGCHLD'
--     `signal.h' (POSIX.1):  *Note Job Control Signals::.
--
--`int SIGCLD'
--     `signal.h' (SVID):  *Note Job Control Signals::.
--
--`int SIGCONT'
--     `signal.h' (POSIX.1):  *Note Job Control Signals::.
--
--`int sigdelset (sigset_t *SET, int SIGNUM)'
--     `signal.h' (POSIX.1):  *Note Signal Sets::.
--
--`int sigemptyset (sigset_t *SET)'
--     `signal.h' (POSIX.1):  *Note Signal Sets::.
--
--`int SIGEMT'
--     `signal.h' (BSD):  *Note Program Error Signals::.
--
--`sighandler_t SIG_ERR'
--     `signal.h' (ISO):  *Note Basic Signal Handling::.
--
--`int sigfillset (sigset_t *SET)'
--     `signal.h' (POSIX.1):  *Note Signal Sets::.
--
--`int SIGFPE'
--     `signal.h' (ISO):  *Note Program Error Signals::.
--
--`sighandler_t'
--     `signal.h' (GNU):  *Note Basic Signal Handling::.
--
--`int SIGHUP'
--     `signal.h' (POSIX.1):  *Note Termination Signals::.
--
--`int SIGILL'
--     `signal.h' (ISO):  *Note Program Error Signals::.
--
--`int SIGINFO'
--     `signal.h' (BSD):  *Note Miscellaneous Signals::.
--
--`int siginterrupt (int SIGNUM, int FAILFLAG)'
--     `signal.h' (BSD):  *Note BSD Handler::.
--
--`int SIGINT'
--     `signal.h' (ISO):  *Note Termination Signals::.
--
--`int SIGIO'
--     `signal.h' (BSD):  *Note Asynchronous I/O Signals::.
--
--`int SIGIOT'
--     `signal.h' (Unix):  *Note Program Error Signals::.
--
--`int sigismember (const sigset_t *SET, int SIGNUM)'
--     `signal.h' (POSIX.1):  *Note Signal Sets::.
--
--`sigjmp_buf'
--     `setjmp.h' (POSIX.1):  *Note Non-Local Exits and Signals::.
--
--`int SIGKILL'
--     `signal.h' (POSIX.1):  *Note Termination Signals::.
--
--`void siglongjmp (sigjmp_buf STATE, int VALUE)'
--     `setjmp.h' (POSIX.1):  *Note Non-Local Exits and Signals::.
--
--`int SIGLOST'
--     `signal.h' (GNU):  *Note Operation Error Signals::.
--
--`int sigmask (int SIGNUM)'
--     `signal.h' (BSD):  *Note Blocking in BSD::.
--
--`sighandler_t signal (int SIGNUM, sighandler_t ACTION)'
--     `signal.h' (ISO):  *Note Basic Signal Handling::.
--
--`int sigpause (int MASK)'
--     `signal.h' (BSD):  *Note Blocking in BSD::.
--
--`int sigpending (sigset_t *SET)'
--     `signal.h' (POSIX.1):  *Note Checking for Pending Signals::.
--
--`int SIGPIPE'
--     `signal.h' (POSIX.1):  *Note Operation Error Signals::.
--
--`int SIGPOLL'
--     `signal.h' (SVID):  *Note Asynchronous I/O Signals::.
--
--`int sigprocmask (int HOW, const sigset_t *SET, sigset_t *OLDSET)'
--     `signal.h' (POSIX.1):  *Note Process Signal Mask::.
--
--`int SIGPROF'
--     `signal.h' (BSD):  *Note Alarm Signals::.
--
--`int SIGQUIT'
--     `signal.h' (POSIX.1):  *Note Termination Signals::.
--
--`int SIGSEGV'
--     `signal.h' (ISO):  *Note Program Error Signals::.
--
--`int sigsetjmp (sigjmp_buf STATE, int SAVESIGS)'
--     `setjmp.h' (POSIX.1):  *Note Non-Local Exits and Signals::.
--
--`SIG_SETMASK'
--     `signal.h' (POSIX.1):  *Note Process Signal Mask::.
--
--`int sigsetmask (int MASK)'
--     `signal.h' (BSD):  *Note Blocking in BSD::.
--
--`sigset_t'
--     `signal.h' (POSIX.1):  *Note Signal Sets::.
--
--`int sigstack (const struct sigstack *STACK, struct sigstack *OLDSTACK)'
--     `signal.h' (BSD):  *Note Signal Stack::.
--
--`int SIGSTOP'
--     `signal.h' (POSIX.1):  *Note Job Control Signals::.
--
--`int sigsuspend (const sigset_t *SET)'
--     `signal.h' (POSIX.1):  *Note Sigsuspend::.
--
--`int SIGSYS'
--     `signal.h' (Unix):  *Note Program Error Signals::.
--
--`int SIGTERM'
--     `signal.h' (ISO):  *Note Termination Signals::.
--
--`int SIGTRAP'
--     `signal.h' (BSD):  *Note Program Error Signals::.
--
--`int SIGTSTP'
--     `signal.h' (POSIX.1):  *Note Job Control Signals::.
--
--`int SIGTTIN'
--     `signal.h' (POSIX.1):  *Note Job Control Signals::.
--
--`int SIGTTOU'
--     `signal.h' (POSIX.1):  *Note Job Control Signals::.
--
--`SIG_UNBLOCK'
--     `signal.h' (POSIX.1):  *Note Process Signal Mask::.
--
--`int SIGURG'
--     `signal.h' (BSD):  *Note Asynchronous I/O Signals::.
--
--`int SIGUSR1'
--     `signal.h' (POSIX.1):  *Note Miscellaneous Signals::.
--
--`int SIGUSR2'
--     `signal.h' (POSIX.1):  *Note Miscellaneous Signals::.
--
--`int sigvec (int SIGNUM, const struct sigvec *ACTION,struct sigvec 
*OLD-ACTION)'
--     `signal.h' (BSD):  *Note BSD Handler::.
--
--`int SIGVTALRM'
--     `signal.h' (BSD):  *Note Alarm Signals::.
--
--`int SIGWINCH'
--     `signal.h' (BSD):  *Note Miscellaneous Signals::.
--
--`int SIGXCPU'
--     `signal.h' (BSD):  *Note Operation Error Signals::.
--
--`int SIGXFSZ'
--     `signal.h' (BSD):  *Note Operation Error Signals::.
--
--`double sinh (double X)'
--     `math.h' (ISO):  *Note Hyperbolic Functions::.
--
--`double sin (double X)'
--     `math.h' (ISO):  *Note Trig Functions::.
--
--`S_IREAD'
--     `sys/stat.h' (BSD):  *Note Permission Bits::.
--
--`S_IRGRP'
--     `sys/stat.h' (POSIX.1):  *Note Permission Bits::.
--
--`S_IROTH'
--     `sys/stat.h' (POSIX.1):  *Note Permission Bits::.
--
--`S_IRUSR'
--     `sys/stat.h' (POSIX.1):  *Note Permission Bits::.
--
--`S_IRWXG'
--     `sys/stat.h' (POSIX.1):  *Note Permission Bits::.
--
--`S_IRWXO'
--     `sys/stat.h' (POSIX.1):  *Note Permission Bits::.
--
--`S_IRWXU'
--     `sys/stat.h' (POSIX.1):  *Note Permission Bits::.
--
--`int S_ISBLK (mode_t M)'
--     `sys/stat.h' (POSIX):  *Note Testing File Type::.
--
--`int S_ISCHR (mode_t M)'
--     `sys/stat.h' (POSIX):  *Note Testing File Type::.
--
--`int S_ISDIR (mode_t M)'
--     `sys/stat.h' (POSIX):  *Note Testing File Type::.
--
--`int S_ISFIFO (mode_t M)'
--     `sys/stat.h' (POSIX):  *Note Testing File Type::.
--
--`S_ISGID'
--     `sys/stat.h' (POSIX):  *Note Permission Bits::.
--
--`int S_ISLNK (mode_t M)'
--     `sys/stat.h' (GNU):  *Note Testing File Type::.
--
--`int S_ISREG (mode_t M)'
--     `sys/stat.h' (POSIX):  *Note Testing File Type::.
--
--`int S_ISSOCK (mode_t M)'
--     `sys/stat.h' (GNU):  *Note Testing File Type::.
--
--`S_ISUID'
--     `sys/stat.h' (POSIX):  *Note Permission Bits::.
--
--`S_ISVTX'
--     `sys/stat.h' (BSD):  *Note Permission Bits::.
--
--`S_IWGRP'
--     `sys/stat.h' (POSIX.1):  *Note Permission Bits::.
--
--`S_IWOTH'
--     `sys/stat.h' (POSIX.1):  *Note Permission Bits::.
--
--`S_IWRITE'
--     `sys/stat.h' (BSD):  *Note Permission Bits::.
--
--`S_IWUSR'
--     `sys/stat.h' (POSIX.1):  *Note Permission Bits::.
--
--`S_IXGRP'
--     `sys/stat.h' (POSIX.1):  *Note Permission Bits::.
--
--`S_IXOTH'
--     `sys/stat.h' (POSIX.1):  *Note Permission Bits::.
--
--`S_IXUSR'
--     `sys/stat.h' (POSIX.1):  *Note Permission Bits::.
--
--`size_t'
--     `stddef.h' (ISO):  *Note Important Data Types::.
--
--`unsigned int sleep (unsigned int SECONDS)'
--     `unistd.h' (POSIX.1):  *Note Sleeping::.
--
--`int snprintf (char *S, size_t SIZE, const char *TEMPLATE, ...)'
--     `stdio.h' (GNU):  *Note Formatted Output Functions::.
--
--`SO_BROADCAST'
--     `sys/socket.h' (BSD):  *Note Socket-Level Options::.
--
--`int SOCK_DGRAM'
--     `sys/socket.h' (BSD):  *Note Communication Styles::.
--
--`int socket (int NAMESPACE, int STYLE, int PROTOCOL)'
--     `sys/socket.h' (BSD):  *Note Creating a Socket::.
--
--`int socketpair (int NAMESPACE, int STYLE, int PROTOCOL, int FILEDES[2])'
--     `sys/socket.h' (BSD):  *Note Socket Pairs::.
--
--`int SOCK_RAW'
--     `sys/socket.h' (BSD):  *Note Communication Styles::.
--
--`int SOCK_RDM'
--     `sys/socket.h' (BSD):  *Note Communication Styles::.
--
--`int SOCK_SEQPACKET'
--     `sys/socket.h' (BSD):  *Note Communication Styles::.
--
--`int SOCK_STREAM'
--     `sys/socket.h' (BSD):  *Note Communication Styles::.
--
--`SO_DEBUG'
--     `sys/socket.h' (BSD):  *Note Socket-Level Options::.
--
--`SO_DONTROUTE'
--     `sys/socket.h' (BSD):  *Note Socket-Level Options::.
--
--`SO_ERROR'
--     `sys/socket.h' (BSD):  *Note Socket-Level Options::.
--
--`SO_KEEPALIVE'
--     `sys/socket.h' (BSD):  *Note Socket-Level Options::.
--
--`SO_LINGER'
--     `sys/socket.h' (BSD):  *Note Socket-Level Options::.
--
--`int SOL_SOCKET'
--     `sys/socket.h' (BSD):  *Note Socket-Level Options::.
--
--`SO_OOBINLINE'
--     `sys/socket.h' (BSD):  *Note Socket-Level Options::.
--
--`SO_RCVBUF'
--     `sys/socket.h' (BSD):  *Note Socket-Level Options::.
--
--`SO_REUSEADDR'
--     `sys/socket.h' (BSD):  *Note Socket-Level Options::.
--
--`SO_SNDBUF'
--     `sys/socket.h' (BSD):  *Note Socket-Level Options::.
--
--`SO_STYLE'
--     `sys/socket.h' (GNU):  *Note Socket-Level Options::.
--
--`SO_TYPE'
--     `sys/socket.h' (BSD):  *Note Socket-Level Options::.
--
--`speed_t'
--     `termios.h' (POSIX.1):  *Note Line Speed::.
--
--`int sprintf (char *S, const char *TEMPLATE, ...)'
--     `stdio.h' (ISO):  *Note Formatted Output Functions::.
--
--`double sqrt (double X)'
--     `math.h' (ISO):  *Note Exponents and Logarithms::.
--
--`void srand (unsigned int SEED)'
--     `stdlib.h' (ISO):  *Note ISO Random::.
--
--`void srandom (unsigned int SEED)'
--     `stdlib.h' (BSD):  *Note BSD Random::.
--
--`int sscanf (const char *S, const char *TEMPLATE, ...)'
--     `stdio.h' (ISO):  *Note Formatted Input Functions::.
--
--`sighandler_t ssignal (int SIGNUM, sighandler_t ACTION)'
--     `signal.h' (SVID):  *Note Basic Signal Handling::.
--
--`int SSIZE_MAX'
--     `limits.h' (POSIX.1):  *Note General Limits::.
--
--`ssize_t'
--     `unistd.h' (POSIX.1):  *Note I/O Primitives::.
--
--`int stat (const char *FILENAME, struct stat *BUF)'
--     `sys/stat.h' (POSIX.1):  *Note Reading Attributes::.
--
--`STDERR_FILENO'
--     `unistd.h' (POSIX.1):  *Note Descriptors and Streams::.
--
--`FILE * stderr'
--     `stdio.h' (ISO):  *Note Standard Streams::.
--
--`STDIN_FILENO'
--     `unistd.h' (POSIX.1):  *Note Descriptors and Streams::.
--
--`FILE * stdin'
--     `stdio.h' (ISO):  *Note Standard Streams::.
--
--`STDOUT_FILENO'
--     `unistd.h' (POSIX.1):  *Note Descriptors and Streams::.
--
--`FILE * stdout'
--     `stdio.h' (ISO):  *Note Standard Streams::.
--
--`char * stpcpy (char *TO, const char *FROM)'
--     `string.h' (Unknown origin):  *Note Copying and Concatenation::.
--
--`char * stpncpy (char *TO, const char *FROM, size_t SIZE)'
--     `string.h' (GNU):  *Note Copying and Concatenation::.
--
--`int strcasecmp (const char *S1, const char *S2)'
--     `string.h' (BSD):  *Note String/Array Comparison::.
--
--`char * strcat (char *TO, const char *FROM)'
--     `string.h' (ISO):  *Note Copying and Concatenation::.
--
--`char * strchr (const char *STRING, int C)'
--     `string.h' (ISO):  *Note Search Functions::.
--
--`int strcmp (const char *S1, const char *S2)'
--     `string.h' (ISO):  *Note String/Array Comparison::.
--
--`int strcoll (const char *S1, const char *S2)'
--     `string.h' (ISO):  *Note Collation Functions::.
--
--`char * strcpy (char *TO, const char *FROM)'
--     `string.h' (ISO):  *Note Copying and Concatenation::.
--
--`size_t strcspn (const char *STRING, const char *STOPSET)'
--     `string.h' (ISO):  *Note Search Functions::.
--
--`char * strdupa (const char *S)'
--     `string.h' (GNU):  *Note Copying and Concatenation::.
--
--`char * strdup (const char *S)'
--     `string.h' (SVID):  *Note Copying and Concatenation::.
--
--`int STREAM_MAX'
--     `limits.h' (POSIX.1):  *Note General Limits::.
--
--`char * strerror (int ERRNUM)'
--     `string.h' (ISO):  *Note Error Messages::.
--
--`size_t strftime (char *S, size_t SIZE, const char *TEMPLATE, const struct tm 
*BROKENTIME)'
--     `time.h' (POSIX.2):  *Note Formatting Date and Time::.
--
--`size_t strlen (const char *S)'
--     `string.h' (ISO):  *Note String Length::.
--
--`int strncasecmp (const char *S1, const char *S2, size_t N)'
--     `string.h' (BSD):  *Note String/Array Comparison::.
--
--`char * strncat (char *TO, const char *FROM, size_t SIZE)'
--     `string.h' (ISO):  *Note Copying and Concatenation::.
--
--`int strncmp (const char *S1, const char *S2, size_t SIZE)'
--     `string.h' (ISO):  *Note String/Array Comparison::.
--
--`char * strncpy (char *TO, const char *FROM, size_t SIZE)'
--     `string.h' (ISO):  *Note Copying and Concatenation::.
--
--`char * strndupa (const char *S, size_t SIZE)'
--     `string.h' (GNU):  *Note Copying and Concatenation::.
--
--`char * strndup (const char *S, size_t SIZE)'
--     `string.h' (GNU):  *Note Copying and Concatenation::.
--
--`char * strpbrk (const char *STRING, const char *STOPSET)'
--     `string.h' (ISO):  *Note Search Functions::.
--
--`char * strrchr (const char *STRING, int C)'
--     `string.h' (ISO):  *Note Search Functions::.
--
--`char * strsep (char **STRING_PTR, const char *DELIMITER)'
--     `string.h' (BSD):  *Note Finding Tokens in a String::.
--
--`char * strsignal (int SIGNUM)'
--     `string.h' (GNU):  *Note Signal Messages::.
--
--`size_t strspn (const char *STRING, const char *SKIPSET)'
--     `string.h' (ISO):  *Note Search Functions::.
--
--`char * strstr (const char *HAYSTACK, const char *NEEDLE)'
--     `string.h' (ISO):  *Note Search Functions::.
--
--`double strtod (const char *STRING, char **TAILPTR)'
--     `stdlib.h' (ISO):  *Note Parsing of Floats::.
--
--`float strtof (const char *STRING, char **TAILPTR)'
--     `stdlib.h' (GNU):  *Note Parsing of Floats::.
--
--`char * strtok (char *NEWSTRING, const char *DELIMITERS)'
--     `string.h' (ISO):  *Note Finding Tokens in a String::.
--
--`char * strtok_r (char *NEWSTRING, const char *DELIMITERS, char **SAVE_PTR)'
--     `string.h' (POSIX):  *Note Finding Tokens in a String::.
--
--`long double strtold (const char *STRING, char **TAILPTR)'
--     `stdlib.h' (GNU):  *Note Parsing of Floats::.
--
--`long int strtol (const char *STRING, char **TAILPTR, int BASE)'
--     `stdlib.h' (ISO):  *Note Parsing of Integers::.
--
--`long long int strtoll (const char *STRING, char **TAILPTR, int BASE)'
--     `stdlib.h' (GNU):  *Note Parsing of Integers::.
--
--`long long int strtoq (const char *STRING, char **TAILPTR, int BASE)'
--     `stdlib.h' (BSD):  *Note Parsing of Integers::.
--
--`unsigned long int strtoul (const char *STRING, char **TAILPTR, int BASE)'
--     `stdlib.h' (ISO):  *Note Parsing of Integers::.
--
--`unsigned long long int strtoull (const char *STRING, char **TAILPTR, int 
BASE)'
--     `stdlib.h' (GNU):  *Note Parsing of Integers::.
--
--`unsigned long long int strtouq (const char *STRING, char **TAILPTR, int 
BASE)'
--     `stdlib.h' (BSD):  *Note Parsing of Integers::.
--
--`struct dirent'
--     `dirent.h' (POSIX.1):  *Note Directory Entries::.
--
--`struct flock'
--     `fcntl.h' (POSIX.1):  *Note File Locks::.
--
--`struct group'
--     `grp.h' (POSIX.1):  *Note Group Data Structure::.
--
--`struct hostent'
--     `netdb.h' (BSD):  *Note Host Names::.
--
--`struct in_addr'
--     `netinet/in.h' (BSD):  *Note Host Address Data Type::.
--
--`struct itimerval'
--     `sys/time.h' (BSD):  *Note Setting an Alarm::.
--
--`struct lconv'
--     `locale.h' (ISO):  *Note Numeric Formatting::.
--
--`struct linger'
--     `sys/socket.h' (BSD):  *Note Socket-Level Options::.
--
--`struct msghdr'
--     `sys/socket.h' (BSD):  *Note Receiving Datagrams::.
--
--`struct mstats'
--     `malloc.h' (GNU):  *Note Statistics of Malloc::.
--
--`struct netent'
--     `netdb.h' (BSD):  *Note Networks Database::.
--
--`struct obstack'
--     `obstack.h' (GNU):  *Note Creating Obstacks::.
--
--`struct option'
--     `getopt.h' (GNU):  *Note Long Options::.
--
--`struct passwd'
--     `pwd.h' (POSIX.1):  *Note User Data Structure::.
--
--`struct printf_info'
--     `printf.h' (GNU):  *Note Conversion Specifier Options::.
--
--`struct protoent'
--     `netdb.h' (BSD):  *Note Protocols Database::.
--
--`struct rlimit'
--     `sys/resource.h' (BSD):  *Note Limits on Resources::.
--
--`struct rusage'
--     `sys/resource.h' (BSD):  *Note Resource Usage::.
--
--`struct servent'
--     `netdb.h' (BSD):  *Note Services Database::.
--
--`struct sigaction'
--     `signal.h' (POSIX.1):  *Note Advanced Signal Handling::.
--
--`struct sigaltstack'
--     `signal.h' (BSD):  *Note Signal Stack::.
--
--`struct sigstack'
--     `signal.h' (BSD):  *Note Signal Stack::.
--
--`struct sigvec'
--     `signal.h' (BSD):  *Note BSD Handler::.
--
--`struct sockaddr'
--     `sys/socket.h' (BSD):  *Note Address Formats::.
--
--`struct sockaddr_in'
--     `netinet/in.h' (BSD):  *Note Internet Address Format::.
--
--`struct sockaddr_un'
--     `sys/un.h' (BSD):  *Note File Namespace Details::.
--
--`struct stat'
--     `sys/stat.h' (POSIX.1):  *Note Attribute Meanings::.
--
--`struct termios'
--     `termios.h' (POSIX.1):  *Note Mode Data Types::.
--
--`struct timeval'
--     `sys/time.h' (BSD):  *Note High-Resolution Calendar::.
--
--`struct timezone'
--     `sys/time.h' (BSD):  *Note High-Resolution Calendar::.
--
--`struct tm'
--     `time.h' (ISO):  *Note Broken-down Time::.
--
--`struct tms'
--     `sys/times.h' (POSIX.1):  *Note Detailed CPU Time::.
--
--`struct utimbuf'
--     `time.h' (POSIX.1):  *Note File Times::.
--
--`struct utsname'
--     `sys/utsname.h' (POSIX.1):  *Note Hardware/Software Type ID::.
--
--`size_t strxfrm (char *TO, const char *FROM, size_t SIZE)'
--     `string.h' (ISO):  *Note Collation Functions::.
--
--`_SVID_SOURCE'
--     (GNU):  *Note Feature Test Macros::.
--
--`int SV_INTERRUPT'
--     `signal.h' (BSD):  *Note BSD Handler::.
--
--`int SV_ONSTACK'
--     `signal.h' (BSD):  *Note BSD Handler::.
--
--`int SV_RESETHAND'
--     `signal.h' (Sun):  *Note BSD Handler::.
--
--`int symlink (const char *OLDNAME, const char *NEWNAME)'
--     `unistd.h' (BSD):  *Note Symbolic Links::.
--
--`long int sysconf (int PARAMETER)'
--     `unistd.h' (POSIX.1):  *Note Sysconf Definition::.
--
--`int system (const char *COMMAND)'
--     `stdlib.h' (ISO):  *Note Running a Command::.
--
--`double tanh (double X)'
--     `math.h' (ISO):  *Note Hyperbolic Functions::.
--
--`double tan (double X)'
--     `math.h' (ISO):  *Note Trig Functions::.
--
--`int tcdrain (int FILEDES)'
--     `termios.h' (POSIX.1):  *Note Line Control::.
--
--`tcflag_t'
--     `termios.h' (POSIX.1):  *Note Mode Data Types::.
--
--`int tcflow (int FILEDES, int ACTION)'
--     `termios.h' (POSIX.1):  *Note Line Control::.
--
--`int tcflush (int FILEDES, int QUEUE)'
--     `termios.h' (POSIX.1):  *Note Line Control::.
--
--`int tcgetattr (int FILEDES, struct termios *TERMIOS-P)'
--     `termios.h' (POSIX.1):  *Note Mode Functions::.
--
--`pid_t tcgetpgrp (int FILEDES)'
--     `unistd.h' (POSIX.1):  *Note Terminal Access Functions::.
--
--`TCSADRAIN'
--     `termios.h' (POSIX.1):  *Note Mode Functions::.
--
--`TCSAFLUSH'
--     `termios.h' (POSIX.1):  *Note Mode Functions::.
--
--`TCSANOW'
--     `termios.h' (POSIX.1):  *Note Mode Functions::.
--
--`TCSASOFT'
--     `termios.h' (BSD):  *Note Mode Functions::.
--
--`int tcsendbreak (int FILEDES, int DURATION)'
--     `termios.h' (POSIX.1):  *Note Line Control::.
--
--`int tcsetattr (int FILEDES, int WHEN, const struct termios *TERMIOS-P)'
--     `termios.h' (POSIX.1):  *Note Mode Functions::.
--
--`int tcsetpgrp (int FILEDES, pid_t PGID)'
--     `unistd.h' (POSIX.1):  *Note Terminal Access Functions::.
--
--`off_t telldir (DIR *DIRSTREAM)'
--     `dirent.h' (BSD):  *Note Random Access Directory::.
--
--`TEMP_FAILURE_RETRY (EXPRESSION)'
--     `unistd.h' (GNU):  *Note Interrupted Primitives::.
--
--`char * tempnam (const char *DIR, const char *PREFIX)'
--     `stdio.h' (SVID):  *Note Temporary Files::.
--
--`time_t time (time_t *RESULT)'
--     `time.h' (ISO):  *Note Simple Calendar Time::.
--
--`clock_t times (struct tms *BUFFER)'
--     `sys/times.h' (POSIX.1):  *Note Detailed CPU Time::.
--
--`time_t'
--     `time.h' (ISO):  *Note Simple Calendar Time::.
--
--`long int timezone'
--     `time.h' (SVID):  *Note Time Zone Functions::.
--
--`FILE * tmpfile (void)'
--     `stdio.h' (ISO):  *Note Temporary Files::.
--
--`int TMP_MAX'
--     `stdio.h' (ISO):  *Note Temporary Files::.
--
--`char * tmpnam (char *RESULT)'
--     `stdio.h' (ISO):  *Note Temporary Files::.
--
--`char * tmpnam_r (char *RESULT)'
--     `stdio.h' (GNU):  *Note Temporary Files::.
--
--`int toascii (int C)'
--     `ctype.h' (SVID, BSD):  *Note Case Conversion::.
--
--`int _tolower (int C)'
--     `ctype.h' (SVID):  *Note Case Conversion::.
--
--`int tolower (int C)'
--     `ctype.h' (ISO):  *Note Case Conversion::.
--
--`tcflag_t TOSTOP'
--     `termios.h' (POSIX.1):  *Note Local Modes::.
--
--`int _toupper (int C)'
--     `ctype.h' (SVID):  *Note Case Conversion::.
--
--`int toupper (int C)'
--     `ctype.h' (ISO):  *Note Case Conversion::.
--
--`TRY_AGAIN'
--     `netdb.h' (BSD):  *Note Host Names::.
--
--`char * ttyname (int FILEDES)'
--     `unistd.h' (POSIX.1):  *Note Is It a Terminal::.
--
--`char * tzname [2]'
--     `time.h' (POSIX.1):  *Note Time Zone Functions::.
--
--`int TZNAME_MAX'
--     `limits.h' (POSIX.1):  *Note General Limits::.
--
--`void tzset (void)'
--     `time.h' (POSIX.1):  *Note Time Zone Functions::.
--
--`UCHAR_MAX'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`uid_t'
--     `sys/types.h' (POSIX.1):  *Note Reading Persona::.
--
--`UINT_MAX'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`ULONG_LONG_MAX'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`ULONG_MAX'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`mode_t umask (mode_t MASK)'
--     `sys/stat.h' (POSIX.1):  *Note Setting Permissions::.
--
--`int uname (struct utsname *INFO)'
--     `sys/utsname.h' (POSIX.1):  *Note Hardware/Software Type ID::.
--
--`int ungetc (int C, FILE *STREAM)'
--     `stdio.h' (ISO):  *Note How Unread::.
--
--`union wait'
--     `sys/wait.h' (BSD):  *Note BSD Wait Functions::.
--
--`int unlink (const char *FILENAME)'
--     `unistd.h' (POSIX.1):  *Note Deleting Files::.
--
--`USHRT_MAX'
--     `limits.h' (ISO):  *Note Range of Type::.
--
--`int utime (const char *FILENAME, const struct utimbuf *TIMES)'
--     `time.h' (POSIX.1):  *Note File Times::.
--
--`int utimes (const char *FILENAME, struct timeval TVP[2])'
--     `sys/time.h' (BSD):  *Note File Times::.
--
--`va_alist'
--     `varargs.h' (Unix):  *Note Old Varargs::.
--
--`TYPE va_arg (va_list AP, TYPE)'
--     `stdarg.h' (ISO):  *Note Argument Macros::.
--
--`va_dcl'
--     `varargs.h' (Unix):  *Note Old Varargs::.
--
--`void va_end (va_list AP)'
--     `stdarg.h' (ISO):  *Note Argument Macros::.
--
--`va_list'
--     `stdarg.h' (ISO):  *Note Argument Macros::.
--
--`void * valloc (size_t SIZE)'
--     `malloc.h', `stdlib.h' (BSD):  *Note Aligned Memory Blocks::.
--
--`int vasprintf (char **PTR, const char *TEMPLATE, va_list AP)'
--     `stdio.h' (GNU):  *Note Variable Arguments Output::.
--
--`void va_start (va_list AP)'
--     `varargs.h' (Unix):  *Note Old Varargs::.
--
--`void va_start (va_list AP, LAST-REQUIRED)'
--     `stdarg.h' (ISO):  *Note Argument Macros::.
--
--`int VDISCARD'
--     `termios.h' (BSD):  *Note Other Special::.
--
--`int VDSUSP'
--     `termios.h' (BSD):  *Note Signal Characters::.
--
--`int VEOF'
--     `termios.h' (POSIX.1):  *Note Editing Characters::.
--
--`int VEOL2'
--     `termios.h' (BSD):  *Note Editing Characters::.
--
--`int VEOL'
--     `termios.h' (POSIX.1):  *Note Editing Characters::.
--
--`int VERASE'
--     `termios.h' (POSIX.1):  *Note Editing Characters::.
--
--`pid_t vfork (void)'
--     `unistd.h' (BSD):  *Note Creating a Process::.
--
--`int vfprintf (FILE *STREAM, const char *TEMPLATE, va_list AP)'
--     `stdio.h' (ISO):  *Note Variable Arguments Output::.
--
--`int vfscanf (FILE *STREAM, const char *TEMPLATE, va_list AP)'
--     `stdio.h' (GNU):  *Note Variable Arguments Input::.
--
--`int VINTR'
--     `termios.h' (POSIX.1):  *Note Signal Characters::.
--
--`int VKILL'
--     `termios.h' (POSIX.1):  *Note Editing Characters::.
--
--`int VLNEXT'
--     `termios.h' (BSD):  *Note Other Special::.
--
--`int VMIN'
--     `termios.h' (POSIX.1):  *Note Noncanonical Input::.
--
--`int vprintf (const char *TEMPLATE, va_list AP)'
--     `stdio.h' (ISO):  *Note Variable Arguments Output::.
--
--`int VQUIT'
--     `termios.h' (POSIX.1):  *Note Signal Characters::.
--
--`int VREPRINT'
--     `termios.h' (BSD):  *Note Editing Characters::.
--
--`int vscanf (const char *TEMPLATE, va_list AP)'
--     `stdio.h' (GNU):  *Note Variable Arguments Input::.
--
--`int vsnprintf (char *S, size_t SIZE, const char *TEMPLATE, va_list AP)'
--     `stdio.h' (GNU):  *Note Variable Arguments Output::.
--
--`int vsprintf (char *S, const char *TEMPLATE, va_list AP)'
--     `stdio.h' (ISO):  *Note Variable Arguments Output::.
--
--`int vsscanf (const char *S, const char *TEMPLATE, va_list AP)'
--     `stdio.h' (GNU):  *Note Variable Arguments Input::.
--
--`int VSTART'
--     `termios.h' (POSIX.1):  *Note Start/Stop Characters::.
--
--`int VSTATUS'
--     `termios.h' (BSD):  *Note Other Special::.
--
--`int VSTOP'
--     `termios.h' (POSIX.1):  *Note Start/Stop Characters::.
--
--`int VSUSP'
--     `termios.h' (POSIX.1):  *Note Signal Characters::.
--
--`int VTIME'
--     `termios.h' (POSIX.1):  *Note Noncanonical Input::.
--
--`int VWERASE'
--     `termios.h' (BSD):  *Note Editing Characters::.
--
--`pid_t wait3 (union wait *STATUS-PTR, int OPTIONS, struct rusage *USAGE)'
--     `sys/wait.h' (BSD):  *Note BSD Wait Functions::.
--
--`pid_t wait4 (pid_t PID, int *STATUS-PTR, int OPTIONS, struct rusage *USAGE)'
--     `sys/wait.h' (BSD):  *Note Process Completion::.
--
--`pid_t wait (int *STATUS-PTR)'
--     `sys/wait.h' (POSIX.1):  *Note Process Completion::.
--
--`pid_t waitpid (pid_t PID, int *STATUS-PTR, int OPTIONS)'
--     `sys/wait.h' (POSIX.1):  *Note Process Completion::.
--
--`WCHAR_MAX'
--     `limits.h' (GNU):  *Note Range of Type::.
--
--`wchar_t'
--     `stddef.h' (ISO):  *Note Wide Char Intro::.
--
--`int WCOREDUMP (int STATUS)'
--     `sys/wait.h' (BSD):  *Note Process Completion Status::.
--
--`size_t wcstombs (char *STRING, const wchar_t WSTRING, size_t SIZE)'
--     `stdlib.h' (ISO):  *Note Wide String Conversion::.
--
--`int wctomb (char *STRING, wchar_t WCHAR)'
--     `stdlib.h' (ISO):  *Note Converting One Char::.
--
--`int WEXITSTATUS (int STATUS)'
--     `sys/wait.h' (POSIX.1):  *Note Process Completion Status::.
--
--`int WIFEXITED (int STATUS)'
--     `sys/wait.h' (POSIX.1):  *Note Process Completion Status::.
--
--`int WIFSIGNALED (int STATUS)'
--     `sys/wait.h' (POSIX.1):  *Note Process Completion Status::.
--
--`int WIFSTOPPED (int STATUS)'
--     `sys/wait.h' (POSIX.1):  *Note Process Completion Status::.
--
--`int W_OK'
--     `unistd.h' (POSIX.1):  *Note Testing File Access::.
--
--`int wordexp (const char *WORDS, wordexp_t *WORD-VECTOR-PTR, int FLAGS)'
--     `wordexp.h' (POSIX.2):  *Note Calling Wordexp::.
--
--`wordexp_t'
--     `wordexp.h' (POSIX.2):  *Note Calling Wordexp::.
--
--`void wordfree (wordexp_t *WORD-VECTOR-PTR)'
--     `wordexp.h' (POSIX.2):  *Note Calling Wordexp::.
--
--`WRDE_APPEND'
--     `wordexp.h' (POSIX.2):  *Note Flags for Wordexp::.
--
--`WRDE_BADCHAR'
--     `wordexp.h' (POSIX.2):  *Note Calling Wordexp::.
--
--`WRDE_BADVAL'
--     `wordexp.h' (POSIX.2):  *Note Calling Wordexp::.
--
--`WRDE_CMDSUB'
--     `wordexp.h' (POSIX.2):  *Note Calling Wordexp::.
--
--`WRDE_DOOFFS'
--     `wordexp.h' (POSIX.2):  *Note Flags for Wordexp::.
--
--`WRDE_NOCMD'
--     `wordexp.h' (POSIX.2):  *Note Flags for Wordexp::.
--
--`WRDE_NOSPACE'
--     `wordexp.h' (POSIX.2):  *Note Calling Wordexp::.
--
--`WRDE_REUSE'
--     `wordexp.h' (POSIX.2):  *Note Flags for Wordexp::.
--
--`WRDE_SHOWERR'
--     `wordexp.h' (POSIX.2):  *Note Flags for Wordexp::.
--
--`WRDE_SYNTAX'
--     `wordexp.h' (POSIX.2):  *Note Calling Wordexp::.
--
--`WRDE_UNDEF'
--     `wordexp.h' (POSIX.2):  *Note Flags for Wordexp::.
--
--`ssize_t write (int FILEDES, const void *BUFFER, size_t SIZE)'
--     `unistd.h' (POSIX.1):  *Note I/O Primitives::.
--
--`int WSTOPSIG (int STATUS)'
--     `sys/wait.h' (POSIX.1):  *Note Process Completion Status::.
--
--`int WTERMSIG (int STATUS)'
--     `sys/wait.h' (POSIX.1):  *Note Process Completion Status::.
--
--`int X_OK'
--     `unistd.h' (POSIX.1):  *Note Testing File Access::.
--
--`_XOPEN_SOURCE'
--     (XOPEN):  *Note Feature Test Macros::.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-29 
glibc-2.0.1/manual/libc.info-29
---- ../glibc-2.0.1/manual/libc.info-29 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-29    1970-01-01 01:00:00.000000000 +0100
-@@ -1,995 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Maintenance,  Next: Copying,  Prev: Library Summary,  
Up: Top
--
--Library Maintenance
--*******************
--
--* Menu:
--
--* Installation::          How to configure, compile and
--                             install the GNU C library.
--* Reporting Bugs::        How to report bugs (if you want to
--                             get them fixed) and other troubles
--                             you may have with the GNU C library.
--* Source Layout::         How to add new functions or header files
--                             to the GNU C library.
--* Porting::               How to port the GNU C library to
--                             a new machine or operating system.
--* Contributors::          Contributors to the GNU C Library.
--
--
--File: libc.info,  Node: Installation,  Next: Reporting Bugs,  Up: Maintenance
--
--How to Install the GNU C Library
--================================
--
--   Installation of the GNU C library is relatively simple, but usually
--requires several GNU tools to be installed already.
--
--* Menu:
--
--* Tools for Installation::      We recommend using these tools to build.
--* Supported Configurations::    What systems the GNU C library runs on.
--
--   To configure the GNU C library for your system, run the shell script
--`configure' with `sh'.  Use an argument which is the conventional GNU
--name for your system configuration--for example, `sparc-sun-sunos4.1',
--for a Sun 4 running SunOS 4.1.  *Note Installation:
--(gcc.info)Installation, for a full description of standard GNU
--configuration names.  If you omit the configuration name, `configure'
--will try to guess one for you by inspecting the system it is running
--on.  It may or may not be able to come up with a guess, and the its
--guess might be wrong.  `configure' will tell you the canonical name of
--the chosen configuration before proceeding.
--
--   Here are some options that you should specify (if appropriate) when
--you run `configure':
--
--`--with-gnu-ld'
--     Use this option if you plan to use GNU `ld' to link programs with
--     the GNU C Library.  (We strongly recommend that you do.)  This
--     option enables use of features that exist only in GNU `ld'; so if
--     you configure for GNU `ld' you must use GNU `ld' *every time* you
--     link with the GNU C Library, and when building it.
--
--`--with-gnu-as'
--     Use this option if you plan to use the GNU assembler, `gas', when
--     building the GNU C Library.  On some systems, the library may not
--     build properly if you do *not* use `gas'.
--
--`--with-gnu-binutils'
--     This option implies both `--with-gnu-ld' and `--with-gnu-as'.  On
--     systems where GNU tools are the system tools, there is no need to
--     specify this option.  These include GNU, GNU/Linux, and free BSD
--     systems.
--
--`--without-fp'
--`--nfp'
--     Use this option if your computer lacks hardware floating-point
--     support.
--
--`--prefix=DIRECTORY'
--     Install machine-independent data files in subdirectories of
--     `DIRECTORY'.  (You can also set this in `configparms'; see below.)
--
--`--exec-prefix=DIRECTORY'
--     Install the library and other machine-dependent files in
--     subdirectories of `DIRECTORY'.  (You can also set this in
--     `configparms'; see below.)
--
--`--enable-shared'
--`--disable-shared'
--     Enable or disable building of an ELF shared library on systems that
--     support it.  The default is to build the shared library on systems
--     using ELF when the GNU `binutils' are available.
--
--`--enable-profile'
--`--disable-profile'
--     Enable or disable building of the profiled C library, `-lc_p'.  The
--     default is to build the profiled library.  You may wish to disable
--     it if you don't plan to do profiling, because it doubles the build
--     time of compiling just the unprofiled static library.
--
--`--enable-omitfp'
--     Enable building a highly-optimized but possibly undebuggable
--     static C library.  This causes the normal static and shared (if
--     enabled) C libraries to be compiled with maximal optimization,
--     including the `-fomit-frame-pointer' switch that makes debugging
--     impossible on many machines, and without debugging information
--     (which makes the binaries substantially smaller).  An additional
--     static library is compiled with no optimization and full debugging
--     information, and installed as `-lc_g'.
--
--   The simplest way to run `configure' is to do it in the directory
--that contains the library sources.  This prepares to build the library
--in that very directory.
--
--   You can prepare to build the library in some other directory by going
--to that other directory to run `configure'.  In order to run configure,
--you will have to specify a directory for it, like this:
--
--     mkdir sun4
--     cd sun4
--     ../configure sparc-sun-sunos4.1
--
--`configure' looks for the sources in whatever directory you specified
--for finding `configure' itself.  It does not matter where in the file
--system the source and build directories are--as long as you specify the
--source directory when you run `configure', you will get the proper
--results.
--
--   This feature lets you keep sources and binaries in different
--directories, and that makes it easy to build the library for several
--different machines from the same set of sources.  Simply create a build
--directory for each target machine, and run `configure' in that
--directory specifying the target machine's configuration name.
--
--   The library has a number of special-purpose configuration parameters.
--These are defined in the file `Makeconfig'; see the comments in that
--file for the details.
--
--   But don't edit the file `Makeconfig' yourself--instead, create a
--file `configparms' in the directory where you are building the library,
--and define in that file the parameters you want to specify.
--`configparms' should *not* be an edited copy of `Makeconfig'; specify
--only the parameters that you want to override.  To see how to set these
--parameters, find the section of `Makeconfig' that says "These are the
--configuration variables." Then for each parameter that you want to
--change, copy the definition from `Makeconfig' to your new `configparms'
--file, and change the value as appropriate for your system.
--
--   It is easy to configure the GNU C library for cross-compilation by
--setting a few variables in `configparms'.  Set `CC' to the
--cross-compiler for the target you configured the library for; it is
--important to use this same `CC' value when running `configure', like
--this: `CC=TARGET-gcc configure TARGET'.  Set `BUILD_CC' to the compiler
--to use for for programs run on the build system as part of compiling
--the library.  You may need to set `AR' and `RANLIB' to cross-compiling
--versions of `ar' and `ranlib' if the native tools are not configured to
--work with object files for the target you configured for.
--
--   Some of the machine-dependent code for some machines uses extensions
--in the GNU C compiler, so you may need to compile the library with GCC.
--(In fact, all of the existing complete ports require GCC.)
--
--   To build the library and related programs, type `make'.  This will
--produce a lot of output, some of which may look like errors from `make'
--(but isn't).  Look for error messages from `make' containing `***'.
--Those indicate that something is really wrong.
--
--   To build and run some test programs which exercise some of the
--library facilities, type `make check'.  This will produce several files
--with names like `PROGRAM.out'.
--
--   To format the `GNU C Library Reference Manual' for printing, type
--`make dvi'.
--
--   To install the library and its header files, and the Info files of
--the manual, type `make install'.  This will build things if necessary,
--before installing them.
--
--
--File: libc.info,  Node: Tools for Installation,  Next: Supported 
Configurations,  Up: Installation
--
--Recommended Tools to Install the GNU C Library
------------------------------------------------
--
--   We recommend installing the following GNU tools before attempting to
--build the GNU C library:
--
--   * `make' 3.75
--
--     You need the latest version of GNU `make'.  Modifying the GNU C
--     Library to work with other `make' programs would be so hard that we
--     recommend you port GNU `make' instead.  *Really.* We recommend
--     version GNU `make' version 3.75 or later.
--
--   * GCC 2.7.2
--
--     On most platforms, the GNU C library can only be compiled with the
--     GNU C compiler.  We recommend GCC version 2.7.2 or later; earlier
--     versions may have problems.
--
--   * `binutils' 2.7
--
--     Using the GNU `binutils' (assembler, linker, and related tools) is
--     preferable when possible, and they are required to build an ELF
--     shared C library.  We recommend `binutils' version 2.7 or later;
--     earlier versions are known to have problems or to not support all
--     architectures.
--
--
--File: libc.info,  Node: Supported Configurations,  Prev: Tools for 
Installation,  Up: Installation
--
--Supported Configurations
--------------------------
--
--   The GNU C Library currently supports configurations that match the
--following patterns:
--
--     alpha-dec-osf1
--     alpha-ANYTHING-linux
--     alpha-ANYTHING-linuxecoff
--     iX86-ANYTHING-bsd4.3
--     iX86-ANYTHING-gnu
--     iX86-ANYTHING-isc2.2
--     iX86-ANYTHING-isc3.N
--     iX86-ANYTHING-linux
--     iX86-ANYTHING-sco3.2
--     iX86-ANYTHING-sco3.2v4
--     iX86-ANYTHING-sysv
--     iX86-ANYTHING-sysv4
--     iX86-force_cpu386-none
--     iX86-sequent-bsd
--     i960-nindy960-none
--     m68k-hp-bsd4.3
--     m68k-mvme135-none
--     m68k-mvme136-none
--     m68k-sony-newsos3
--     m68k-sony-newsos4
--     m68k-sun-sunos4.N
--     mips-dec-ultrix4.N
--     mips-sgi-irix4.N
--     sparc-sun-solaris2.N
--     sparc-sun-sunos4.N
--
--   Each case of `iX86' can be `i386', `i486', `i586', or `i686'..  All
--of those configurations produce a library that can run on any of these
--processors.  The library will be optimized for the specified processor,
--but will not use instructions not available on all of them.
--
--   While no other configurations are supported, there are handy aliases
--for these few.  (These aliases work in other GNU software as well.)
--
--     decstation
--     hp320-bsd4.3 hp300bsd
--     i486-gnu
--     i586-linux
--     i386-sco
--     i386-sco3.2v4
--     i386-sequent-dynix
--     i386-svr4
--     news
--     sun3-sunos4.N sun3
--     sun4-solaris2.N sun4-sunos5.N
--     sun4-sunos4.N sun4
--
--
--File: libc.info,  Node: Reporting Bugs,  Next: Source Layout,  Prev: 
Installation,  Up: Maintenance
--
--Reporting Bugs
--==============
--
--   There are probably bugs in the GNU C library.  There are certainly
--errors and omissions in this manual.  If you report them, they will get
--fixed.  If you don't, no one will ever know about them and they will
--remain unfixed for all eternity, if not longer.
--
--   To report a bug, first you must find it.  Hopefully, this will be the
--hard part.  Once you've found a bug, make sure it's really a bug.  A
--good way to do this is to see if the GNU C library behaves the same way
--some other C library does.  If so, probably you are wrong and the
--libraries are right (but not necessarily).  If not, one of the libraries
--is probably wrong.
--
--   Once you're sure you've found a bug, try to narrow it down to the
--smallest test case that reproduces the problem.  In the case of a C
--library, you really only need to narrow it down to one library function
--call, if possible.  This should not be too difficult.
--
--   The final step when you have a simple test case is to report the bug.
--When reporting a bug, send your test case, the results you got, the
--results you expected, what you think the problem might be (if you've
--thought of anything), your system type, and the version of the GNU C
--library which you are using.  Also include the files `config.status'
--and `config.make' which are created by running `configure'; they will
--be in whatever directory was current when you ran `configure'.
--
--   If you think you have found some way in which the GNU C library does
--not conform to the ISO and POSIX standards (*note Standards and
--Portability::.), that is definitely a bug.  Report it!
--
--   Send bug reports to the Internet address address@hidden'
--or the UUCP path `mit-eddie!prep.ai.mit.edu!bug-glibc'.  If you have
--other problems with installation or use, please report those as well.
--
--   If you are not sure how a function should behave, and this manual
--doesn't tell you, that's a bug in the manual.  Report that too!  If the
--function's behavior disagrees with the manual, then either the library
--or the manual has a bug, so report the disagreement.  If you find any
--errors or omissions in this manual, please report them to the Internet
--address address@hidden' or the UUCP path
--`mit-eddie!prep.ai.mit.edu!bug-glibc-manual'.
--
--
--File: libc.info,  Node: Source Layout,  Next: Porting,  Prev: Reporting Bugs, 
 Up: Maintenance
--
--Adding New Functions
--====================
--
--   The process of building the library is driven by the makefiles, which
--make heavy use of special features of GNU `make'.  The makefiles are
--very complex, and you probably don't want to try to understand them.
--But what they do is fairly straightforward, and only requires that you
--define a few variables in the right places.
--
--   The library sources are divided into subdirectories, grouped by
--topic.
--
--   The `string' subdirectory has all the string-manipulation functions,
--`math' has all the mathematical functions, etc.
--
--   Each subdirectory contains a simple makefile, called `Makefile',
--which defines a few `make' variables and then includes the global
--makefile `Rules' with a line like:
--
--     include ../Rules
--
--The basic variables that a subdirectory makefile defines are:
--
--`subdir'
--     The name of the subdirectory, for example `stdio'.  This variable
--     *must* be defined.
--
--`headers'
--     The names of the header files in this section of the library, such
--     as `stdio.h'.
--
--`routines'
--`aux'
--     The names of the modules (source files) in this section of the
--     library.  These should be simple names, such as `strlen' (rather
--     than complete file names, such as `strlen.c').  Use `routines' for
--     modules that define functions in the library, and `aux' for
--     auxiliary modules containing things like data definitions.  But the
--     values of `routines' and `aux' are just concatenated, so there
--     really is no practical difference.
--
--`tests'
--     The names of test programs for this section of the library.  These
--     should be simple names, such as `tester' (rather than complete file
--     names, such as `tester.c').  `make tests' will build and run all
--     the test programs.  If a test program needs input, put the test
--     data in a file called `TEST-PROGRAM.input'; it will be given to
--     the test program on its standard input.  If a test program wants
--     to be run with arguments, put the arguments (all on a single line)
--     in a file called `TEST-PROGRAM.args'.  Test programs should exit
--     with zero status when the test passes, and nonzero status when the
--     test indicates a bug in the library or error in building.
--
--`others'
--     The names of "other" programs associated with this section of the
--     library.  These are programs which are not tests per se, but are
--     other small programs included with the library.  They are built by
--     `make others'.
--
--`install-lib'
--`install-data'
--`install'
--     Files to be installed by `make install'.  Files listed in
--     `install-lib' are installed in the directory specified by `libdir'
--     in `configparms' or `Makeconfig' (*note Installation::.).  Files
--     listed in `install-data' are installed in the directory specified
--     by `datadir' in `configparms' or `Makeconfig'.  Files listed in
--     `install' are installed in the directory specified by `bindir' in
--     `configparms' or `Makeconfig'.
--
--`distribute'
--     Other files from this subdirectory which should be put into a
--     distribution tar file.  You need not list here the makefile itself
--     or the source and header files listed in the other standard
--     variables.  Only define `distribute' if there are files used in an
--     unusual way that should go into the distribution.
--
--`generated'
--     Files which are generated by `Makefile' in this subdirectory.
--     These files will be removed by `make clean', and they will never
--     go into a distribution.
--
--`extra-objs'
--     Extra object files which are built by `Makefile' in this
--     subdirectory.  This should be a list of file names like `foo.o';
--     the files will actually be found in whatever directory object
--     files are being built in.  These files will be removed by
--     `make clean'.  This variable is used for secondary object files
--     needed to build `others' or `tests'.
--
--
--File: libc.info,  Node: Porting,  Next: Contributors,  Prev: Source Layout,  
Up: Maintenance
--
--Porting the GNU C Library
--=========================
--
--   The GNU C library is written to be easily portable to a variety of
--machines and operating systems.  Machine- and operating system-dependent
--functions are well separated to make it easy to add implementations for
--new machines or operating systems.  This section describes the layout of
--the library source tree and explains the mechanisms used to select
--machine-dependent code to use.
--
--   All the machine-dependent and operating system-dependent files in the
--library are in the subdirectory `sysdeps' under the top-level library
--source directory.  This directory contains a hierarchy of
--subdirectories (*note Hierarchy Conventions::.).
--
--   Each subdirectory of `sysdeps' contains source files for a
--particular machine or operating system, or for a class of machine or
--operating system (for example, systems by a particular vendor, or all
--machines that use IEEE 754 floating-point format).  A configuration
--specifies an ordered list of these subdirectories.  Each subdirectory
--implicitly appends its parent directory to the list.  For example,
--specifying the list `unix/bsd/vax' is equivalent to specifying the list
--`unix/bsd/vax unix/bsd unix'.  A subdirectory can also specify that it
--implies other subdirectories which are not directly above it in the
--directory hierarchy.  If the file `Implies' exists in a subdirectory,
--it lists other subdirectories of `sysdeps' which are appended to the
--list, appearing after the subdirectory containing the `Implies' file.
--Lines in an `Implies' file that begin with a `#' character are ignored
--as comments.  For example, `unix/bsd/Implies' contains:
--     # BSD has Internet-related things.
--     unix/inet
--
--and `unix/Implies' contains:
--     posix
--
--So the final list is `unix/bsd/vax unix/bsd unix/inet unix posix'.
--
--   `sysdeps' has two "special" subdirectories, called `generic' and
--`stub'.  These two are always implicitly appended to the list of
--subdirectories (in that order), so you needn't put them in an `Implies'
--file, and you should not create any subdirectories under them intended
--to be new specific categories.  `generic' is for things that can be
--implemented in machine-independent C, using only other
--machine-independent functions in the C library.  `stub' is for "stub"
--versions of functions which cannot be implemented on a particular
--machine or operating system.  The stub functions always return an
--error, and set `errno' to `ENOSYS' (Function not implemented).  *Note
--Error Reporting::.
--
--   A source file is known to be system-dependent by its having a
--version in `generic' or `stub'; every generally-available function whose
--implementation is system-dependent in should have either a generic or
--stub implementation (there is no point in having both).  Some rare
--functions are only useful on specific systems and aren't defined at all
--on others; these do not appear anywhere in the system-independent
--source code or makefiles (including the `generic' and `stub'
--directories), only in the system-dependent `Makefile' in the specific
--system's subdirectory.
--
--   If you come across a file that is in one of the main source
--directories (`string', `stdio', etc.), and you want to write a machine-
--or operating system-dependent version of it, move the file into
--`sysdeps/generic' and write your new implementation in the appropriate
--system-specific subdirectory.  Note that if a file is to be
--system-dependent, it *must not* appear in one of the main source
--directories.
--
--   There are a few special files that may exist in each subdirectory of
--`sysdeps':
--
--`Makefile'
--     A makefile for this machine or operating system, or class of
--     machine or operating system.  This file is included by the library
--     makefile `Makerules', which is used by the top-level makefile and
--     the subdirectory makefiles.  It can change the variables set in the
--     including makefile or add new rules.  It can use GNU `make'
--     conditional directives based on the variable `subdir' (see above)
--     to select different sets of variables and rules for different
--     sections of the library.  It can also set the `make' variable
--     `sysdep-routines', to specify extra modules to be included in the
--     library.  You should use `sysdep-routines' rather than adding
--     modules to `routines' because the latter is used in determining
--     what to distribute for each subdirectory of the main source tree.
--
--     Each makefile in a subdirectory in the ordered list of
--     subdirectories to be searched is included in order.  Since several
--     system-dependent makefiles may be included, each should append to
--     `sysdep-routines' rather than simply setting it:
--
--          sysdep-routines := $(sysdep-routines) foo bar
--
--`Subdirs'
--     This file contains the names of new whole subdirectories under the
--     top-level library source tree that should be included for this
--     system.  These subdirectories are treated just like the
--     system-independent subdirectories in the library source tree, such
--     as `stdio' and `math'.
--
--     Use this when there are completely new sets of functions and header
--     files that should go into the library for the system this
--     subdirectory of `sysdeps' implements.  For example,
--     `sysdeps/unix/inet/Subdirs' contains `inet'; the `inet' directory
--     contains various network-oriented operations which only make sense
--     to put in the library on systems that support the Internet.
--
--`Dist'
--     This file contains the names of files (relative to the
--     subdirectory of `sysdeps' in which it appears) which should be
--     included in the distribution.  List any new files used by rules in
--     the `Makefile' in the same directory, or header files used by the
--     source files in that directory.  You don't need to list files that
--     are implementations (either C or assembly source) of routines
--     whose names are given in the machine-independent makefiles in the
--     main source tree.
--
--`configure'
--     This file is a shell script fragment to be run at configuration
--     time.  The top-level `configure' script uses the shell `.' command
--     to read the `configure' file in each system-dependent directory
--     chosen, in order.  The `configure' files are often generated from
--     `configure.in' files using Autoconf.
--
--     A system-dependent `configure' script will usually add things to
--     the shell variables `DEFS' and `config_vars'; see the top-level
--     `configure' script for details.  The script can check for
--     `--with-PACKAGE' options that were passed to the top-level
--     `configure'.  For an option `--with-PACKAGE=VALUE' `configure'
--     sets the shell variable `with_PACKAGE' (with any dashes in PACKAGE
--     converted to underscores) to VALUE; if the option is just
--     `--with-PACKAGE' (no argument), then it sets `with_PACKAGE' to
--     `yes'.
--
--`configure.in'
--     This file is an Autoconf input fragment to be processed into the
--     file `configure' in this subdirectory.  *Note Introduction:
--     (autoconf.info)Introduction, for a description of Autoconf.  You
--     should write either `configure' or `configure.in', but not both.
--     The first line of `configure.in' should invoke the `m4' macro
--     `GLIBC_PROVIDES'.  This macro does several `AC_PROVIDE' calls for
--     Autoconf macros which are used by the top-level `configure'
--     script; without this, those macros might be invoked again
--     unnecessarily by Autoconf.
--
--   That is the general system for how system-dependencies are isolated.
--
--* Menu:
--
--* Hierarchy Conventions::       The layout of the `sysdeps' hierarchy.
--* Porting to Unix::             Porting the library to an average
--                                   Unix-like system.
--
--
--File: libc.info,  Node: Hierarchy Conventions,  Next: Porting to Unix,  Up: 
Porting
--
--Layout of the `sysdeps' Directory Hierarchy
---------------------------------------------
--
--   A GNU configuration name has three parts: the CPU type, the
--manufacturer's name, and the operating system.  `configure' uses these
--to pick the list of system-dependent directories to look for.  If the
--`--nfp' option is *not* passed to `configure', the directory
--`MACHINE/fpu' is also used.  The operating system often has a "base
--operating system"; for example, if the operating system is `sunos4.1',
--the base operating system is `unix/bsd'.  The algorithm used to pick
--the list of directories is simple: `configure' makes a list of the base
--operating system, manufacturer, CPU type, and operating system, in that
--order.  It then concatenates all these together with slashes in
--between, to produce a directory name; for example, the configuration
--`sparc-sun-sunos4.1' results in `unix/bsd/sun/sparc/sunos4.1'.
--`configure' then tries removing each element of the list in turn, so
--`unix/bsd/sparc' and `sun/sparc' are also tried, among others.  Since
--the precise version number of the operating system is often not
--important, and it would be very inconvenient, for example, to have
--identical `sunos4.1.1' and `sunos4.1.2' directories, `configure' tries
--successively less specific operating system names by removing trailing
--suffixes starting with a period.
--
--   As an example, here is the complete list of directories that would be
--tried for the configuration `sparc-sun-sunos4.1' (without the `--nfp'
--option):
--
--     sparc/fpu
--     unix/bsd/sun/sunos4.1/sparc
--     unix/bsd/sun/sunos4.1
--     unix/bsd/sun/sunos4/sparc
--     unix/bsd/sun/sunos4
--     unix/bsd/sun/sunos/sparc
--     unix/bsd/sun/sunos
--     unix/bsd/sun/sparc
--     unix/bsd/sun
--     unix/bsd/sunos4.1/sparc
--     unix/bsd/sunos4.1
--     unix/bsd/sunos4/sparc
--     unix/bsd/sunos4
--     unix/bsd/sunos/sparc
--     unix/bsd/sunos
--     unix/bsd/sparc
--     unix/bsd
--     unix/sun/sunos4.1/sparc
--     unix/sun/sunos4.1
--     unix/sun/sunos4/sparc
--     unix/sun/sunos4
--     unix/sun/sunos/sparc
--     unix/sun/sunos
--     unix/sun/sparc
--     unix/sun
--     unix/sunos4.1/sparc
--     unix/sunos4.1
--     unix/sunos4/sparc
--     unix/sunos4
--     unix/sunos/sparc
--     unix/sunos
--     unix/sparc
--     unix
--     sun/sunos4.1/sparc
--     sun/sunos4.1
--     sun/sunos4/sparc
--     sun/sunos4
--     sun/sunos/sparc
--     sun/sunos
--     sun/sparc
--     sun
--     sunos4.1/sparc
--     sunos4.1
--     sunos4/sparc
--     sunos4
--     sunos/sparc
--     sunos
--     sparc
--
--   Different machine architectures are conventionally subdirectories at
--the top level of the `sysdeps' directory tree.  For example,
--`sysdeps/sparc' and `sysdeps/m68k'.  These contain files specific to
--those machine architectures, but not specific to any particular
--operating system.  There might be subdirectories for specializations of
--those architectures, such as `sysdeps/m68k/68020'. Code which is
--specific to the floating-point coprocessor used with a particular
--machine should go in `sysdeps/MACHINE/fpu'.
--
--   There are a few directories at the top level of the `sysdeps'
--hierarchy that are not for particular machine architectures.
--
--`generic'
--`stub'
--     As described above (*note Porting::.), these are the two
--     subdirectories that every configuration implicitly uses after all
--     others.
--
--`ieee754'
--     This directory is for code using the IEEE 754 floating-point
--     format, where the C type `float' is IEEE 754 single-precision
--     format, and `double' is IEEE 754 double-precision format.  Usually
--     this directory is referred to in the `Implies' file in a machine
--     architecture-specific directory, such as `m68k/Implies'.
--
--`posix'
--     This directory contains implementations of things in the library in
--     terms of POSIX.1 functions.  This includes some of the POSIX.1
--     functions themselves.  Of course, POSIX.1 cannot be completely
--     implemented in terms of itself, so a configuration using just
--     `posix' cannot be complete.
--
--`unix'
--     This is the directory for Unix-like things.  *Note Porting to
--     Unix::.  `unix' implies `posix'.  There are some special-purpose
--     subdirectories of `unix':
--
--    `unix/common'
--          This directory is for things common to both BSD and System V
--          release 4.  Both `unix/bsd' and `unix/sysv/sysv4' imply
--          `unix/common'.
--
--    `unix/inet'
--          This directory is for `socket' and related functions on Unix
--          systems.  The `inet' top-level subdirectory is enabled by
--          `unix/inet/Subdirs'.  `unix/common' implies `unix/inet'.
--
--`mach'
--     This is the directory for things based on the Mach microkernel
--     from CMU (including the GNU operating system).  Other basic
--     operating systems (VMS, for example) would have their own
--     directories at the top level of the `sysdeps' hierarchy, parallel
--     to `unix' and `mach'.
--
--
--File: libc.info,  Node: Porting to Unix,  Prev: Hierarchy Conventions,  Up: 
Porting
--
--Porting the GNU C Library to Unix Systems
-------------------------------------------
--
--   Most Unix systems are fundamentally very similar.  There are
--variations between different machines, and variations in what
--facilities are provided by the kernel.  But the interface to the
--operating system facilities is, for the most part, pretty uniform and
--simple.
--
--   The code for Unix systems is in the directory `unix', at the top
--level of the `sysdeps' hierarchy.  This directory contains
--subdirectories (and subdirectory trees) for various Unix variants.
--
--   The functions which are system calls in most Unix systems are
--implemented in assembly code in files in `sysdeps/unix'.  These files
--are named with a suffix of `.S'; for example, `__open.S'.  Files ending
--in `.S' are run through the C preprocessor before being fed to the
--assembler.
--
--   These files all use a set of macros that should be defined in
--`sysdep.h'.  The `sysdep.h' file in `sysdeps/unix' partially defines
--them; a `sysdep.h' file in another directory must finish defining them
--for the particular machine and operating system variant.  See
--`sysdeps/unix/sysdep.h' and the machine-specific `sysdep.h'
--implementations to see what these macros are and what they should do.
--
--   The system-specific makefile for the `unix' directory (that is, the
--file `sysdeps/unix/Makefile') gives rules to generate several files
--from the Unix system you are building the library on (which is assumed
--to be the target system you are building the library *for*).  All the
--generated files are put in the directory where the object files are
--kept; they should not affect the source tree itself.  The files
--generated are `ioctls.h', `errnos.h', `sys/param.h', and `errlist.c'
--(for the `stdio' section of the library).
--
--
--File: libc.info,  Node: Contributors,  Prev: Porting,  Up: Maintenance
--
--Contributors to the GNU C Library
--=================================
--
--   The GNU C library was written originally by Roland McGrath.  Some
--parts of the library were contributed or worked on by other people.
--
--   * The `getopt' function and related code were written by Richard
--     Stallman, David J. MacKenzie, and Roland McGrath.
--
--   * The merge sort function `qsort' was written by Michael J. Haertel.
--
--   * The quick sort function used as a fallback by `qsort' was written
--     by Douglas C. Schmidt.
--
--   * The memory allocation functions `malloc', `realloc' and `free' and
--     related code were written by Michael J. Haertel.
--
--   * Fast implementations of many of the string functions (`memcpy',
--     `strlen', etc.) were written by Torbjorn Granlund.
--
--   * The `tar.h' header file was written by David J. MacKenzie.
--
--   * The port to the MIPS DECStation running Ultrix 4
--     (`mips-dec-ultrix4') was contributed by Brendan Kehoe and Ian
--     Lance Taylor.
--
--   * The DES encryption function `crypt' and related functions were
--     contributed by Michael Glad.
--
--   * The `ftw' function was contributed by Ian Lance Taylor.
--
--   * The startup code to support SunOS shared libraries was contributed
--     by Tom Quinn.
--
--   * The `mktime' function was contributed by Paul Eggert.
--
--   * The port to the Sequent Symmetry running Dynix version 3
--     (`i386-sequent-bsd') was contributed by Jason Merrill.
--
--   * The timezone support code is derived from the public-domain
--     timezone package by Arthur David Olson and his many contributors.
--
--   * The port to the DEC Alpha running OSF/1 (`alpha-dec-osf1') was
--     contributed by Brendan Kehoe, using some code written by Roland
--     McGrath.
--
--   * The port to SGI machines running Irix 4 (`mips-sgi-irix4') was
--     contributed by Tom Quinn.
--
--   * The port of the Mach and Hurd code to the MIPS architecture
--     (`mips-ANYTHING-gnu') was contributed by Kazumoto Kojima.
--
--   * The floating-point printing function used by `printf' and friends
--     and the floating-point reading function used by `scanf', `strtod'
--     and friends were written by Ulrich Drepper.  The multi-precision
--     integer functions used in those functions are taken from GNU MP,
--     which was contributed by Torbjorn Granlund.
--
--   * The internationalization support in the library, and the support
--     programs `locale' and `localedef', were written by Ulrich Drepper.
--     Ulrich Drepper adapted the support code for message catalogs
--     (`libintl.h', etc.) from the GNU `gettext' package, which he also
--     wrote.  He also contributed the `catgets' support and the entire
--     suite of multi-byte and wide-character support functions
--     (`wctype.h', `wchar.h', etc.).
--
--   * The implementations of the `nsswitch.conf' mechanism and the files
--     and DNS backends for it were designed and written by Ulrich
--     Drepper and Roland McGrath, based on a backend interface defined
--     by Peter Eriksson.
--
--   * The port to Linux i386/ELF (`i386-ANYTHING-linux') was contributed
--     by Ulrich Drepper, based in large part on work done in Hongjiu
--     Lu's Linux version of the GNU C Library.
--
--   * The port to Linux/m68k (`m68k-ANYTHING-linux') was contributed by
--     Andreas Schwab.
--
--   * Richard Henderson contributed the ELF dynamic linking code and
--     other support for the Alpha processor.
--
--   * David Mosberger-Tang contributed the port to Linux/Alpha
--     (`alpha-ANYTHING-linux').
--
--   * Stephen R. van den Berg contributed a highly-optimized `strstr'
--     function.
--
--   * Ulrich Drepper contributed the `hsearch' and `drand48' families of
--     functions; reentrant `...`_r'' versions of the `random' family;
--     System V shared memory and IPC support code; and several
--     highly-optimized string functions for iX86 processors.
--
--   * The math functions are taken from `fdlibm-5.1' by Sun
--     Microsystems, as modified by J.T. Conklin, Ian Lance Taylor,
--     Ulrich Drepper, Andreas Schwab, and Roland McGrath.
--
--   * The `libio' library used to implement `stdio' functions on some
--     platforms was written by Per Bothner and modified by Ulrich
--     Drepper.
--
--   * The Internet-related code (most of the `inet' subdirectory) and
--     several other miscellaneous functions and header files have been
--     included from 4.4 BSD with little or no modification.
--
--     All code incorporated from 4.4 BSD is under the following
--     copyright:
--
--               Copyright (C) 1991 Regents of the University of California.
--               All rights reserved.
--
--          Redistribution and use in source and binary forms, with or
--          without modification, are permitted provided that the
--          following conditions are met:
--
--            1. Redistributions of source code must retain the above
--               copyright notice, this list of conditions and the
--               following disclaimer.
--
--            2. Redistributions in binary form must reproduce the above
--               copyright notice, this list of conditions and the
--               following disclaimer in the documentation and/or other
--               materials provided with the distribution.
--
--            3. All advertising materials mentioning features or use of
--               this software must display the following acknowledgement:
--                    This product includes software developed by the
--                    University of California, Berkeley and its
--                    contributors.
--
--            4. Neither the name of the University nor the names of its
--               contributors may be used to endorse or promote products
--               derived from this software without specific prior
--               written permission.
--
--          THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS
--          IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
--          LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
--          FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT
--          SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
--          INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
--          DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
--          SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
--          OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
--          LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
--          (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
--          THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
--          OF SUCH DAMAGE.
--
--   * The random number generation functions `random', `srandom',
--     `setstate' and `initstate', which are also the basis for the
--     `rand' and `srand' functions, were written by Earl T. Cohen for
--     the University of California at Berkeley and are copyrighted by the
--     Regents of the University of California.  They have undergone minor
--     changes to fit into the GNU C library and to fit the ISO C
--     standard, but the functional code is Berkeley's.
--
--   * The Internet resolver code is taken directly from BIND 4.9.5,
--     which is under both the Berkeley copyright above and also:
--
--          Portions Copyright (C) 1993 by Digital Equipment Corporation.
--
--          Permission to use, copy, modify, and distribute this software
--          for any purpose with or without fee is hereby granted,
--          provided that the above copyright notice and this permission
--          notice appear in all copies, and that the name of Digital
--          Equipment Corporation not be used in advertising or publicity
--          pertaining to distribution of the document or software
--          without specific, written prior permission.
--
--          THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP.
--          DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
--          INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
--          FITNESS.  IN NO EVENT SHALL DIGITAL EQUIPMENT CORPORATION BE
--          LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
--          DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
--          DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
--          OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
--          WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
--
--   * The code to support Sun RPC is taken verbatim from Sun's
--     RPCSRC-4.0 distribution, and is covered by this copyright:
--
--               Copyright (C) 1984, Sun Microsystems, Inc.
--
--          Sun RPC is a product of Sun Microsystems, Inc. and is
--          provided for unrestricted use provided that this legend is
--          included on all tape media and as a part of the software
--          program in whole or part.  Users may copy or modify Sun RPC
--          without charge, but are not authorized to license or
--          distribute it to anyone else except as part of a product or
--          program developed by the user.
--
--          SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND
--          INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND
--          FITNESS FOR A PARTICULAR PURPOSE, OR ARISING FROM A COURSE OF
--          DEALING, USAGE OR TRADE PRACTICE.
--
--          Sun RPC is provided with no support and without any
--          obligation on the part of Sun Microsystems, Inc. to assist in
--          its use, correction, modification or enhancement.
--
--          SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT
--          TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY
--          PATENTS BY SUN RPC OR ANY PART THEREOF.
--
--          In no event will Sun Microsystems, Inc. be liable for any
--          lost revenue or profits or other special, indirect and
--          consequential damages, even if Sun has been advised of the
--          possibility of such damages.
--
--               Sun Microsystems, Inc.
--               2550 Garcia Avenue
--               Mountain View, California  94043
--
--   * Some of the support code for Mach is taken from Mach 3.0 by CMU,
--     and is under the following copyright terms:
--
--               Mach Operating System
--               Copyright (C) 1991,1990,1989 Carnegie Mellon University
--               All Rights Reserved.
--
--          Permission to use, copy, modify and distribute this software
--          and its documentation is hereby granted, provided that both
--          the copyright notice and this permission notice appear in all
--          copies of the software, derivative works or modified
--          versions, and any portions thereof, and that both notices
--          appear in supporting documentation.
--
--          CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS
--          IS" CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF
--          ANY KIND FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF
--          THIS SOFTWARE.
--
--          Carnegie Mellon requests users of this software to return to
--
--                Software Distribution Coordinator
--                School of Computer Science
--                Carnegie Mellon University
--                Pittsburgh PA 15213-3890
--
--          or address@hidden' any improvements or
--          extensions that they make and grant Carnegie Mellon the
--          rights to redistribute these changes.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-3 
glibc-2.0.1/manual/libc.info-3
---- ../glibc-2.0.1/manual/libc.info-3  1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-3     1970-01-01 01:00:00.000000000 +0100
-@@ -1,1163 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Error Messages,  Prev: Error Codes,  Up: Error 
Reporting
--
--Error Messages
--==============
--
--   The library has functions and variables designed to make it easy for
--your program to report informative error messages in the customary
--format about the failure of a library call.  The functions `strerror'
--and `perror' give you the standard error message for a given error
--code; the variable `program_invocation_short_name' gives you convenient
--access to the name of the program that encountered the error.
--
-- - Function: char * strerror (int ERRNUM)
--     The `strerror' function maps the error code (*note Checking for
--     Errors::.) specified by the ERRNUM argument to a descriptive error
--     message string.  The return value is a pointer to this string.
--
--     The value ERRNUM normally comes from the variable `errno'.
--
--     You should not modify the string returned by `strerror'.  Also, if
--     you make subsequent calls to `strerror', the string might be
--     overwritten.  (But it's guaranteed that no library function ever
--     calls `strerror' behind your back.)
--
--     The function `strerror' is declared in `string.h'.
--
-- - Function: void perror (const char *MESSAGE)
--     This function prints an error message to the stream `stderr'; see
--     *Note Standard Streams::.
--
--     If you call `perror' with a MESSAGE that is either a null pointer
--     or an empty string, `perror' just prints the error message
--     corresponding to `errno', adding a trailing newline.
--
--     If you supply a non-null MESSAGE argument, then `perror' prefixes
--     its output with this string.  It adds a colon and a space
--     character to separate the MESSAGE from the error string
--     corresponding to `errno'.
--
--     The function `perror' is declared in `stdio.h'.
--
--   `strerror' and `perror' produce the exact same message for any given
--error code; the precise text varies from system to system.  On the GNU
--system, the messages are fairly short; there are no multi-line messages
--or embedded newlines.  Each error message begins with a capital letter
--and does not include any terminating punctuation.
--
--   *Compatibility Note:*  The `strerror' function is a new feature of
--ISO C.  Many older C systems do not support this function yet.
--
--   Many programs that don't read input from the terminal are designed to
--exit if any system call fails.  By convention, the error message from
--such a program should start with the program's name, sans directories.
--You can find that name in the variable `program_invocation_short_name';
--the full file name is stored the variable `program_invocation_name':
--
-- - Variable: char * program_invocation_name
--     This variable's value is the name that was used to invoke the
--     program running in the current process.  It is the same as
--     `argv[0]'.  Note that this is not necessarily a useful file name;
--     often it contains no directory names.  *Note Program Arguments::.
--
-- - Variable: char * program_invocation_short_name
--     This variable's value is the name that was used to invoke the
--     program running in the current process, with directory names
--     removed.  (That is to say, it is the same as
--     `program_invocation_name' minus everything up to the last slash,
--     if any.)
--
--   The library initialization code sets up both of these variables
--before calling `main'.
--
--   *Portability Note:* These two variables are GNU extensions.  If you
--want your program to work with non-GNU libraries, you must save the
--value of `argv[0]' in `main', and then strip off the directory names
--yourself.  We added these extensions to make it possible to write
--self-contained error-reporting subroutines that require no explicit
--cooperation from `main'.
--
--   Here is an example showing how to handle failure to open a file
--correctly.  The function `open_sesame' tries to open the named file for
--reading and returns a stream if successful.  The `fopen' library
--function returns a null pointer if it couldn't open the file for some
--reason.  In that situation, `open_sesame' constructs an appropriate
--error message using the `strerror' function, and terminates the
--program.  If we were going to make some other library calls before
--passing the error code to `strerror', we'd have to save it in a local
--variable instead, because those other library functions might overwrite
--`errno' in the meantime.
--
--     #include <errno.h>
--     #include <stdio.h>
--     #include <stdlib.h>
--     #include <string.h>
--     
--     FILE *
--     open_sesame (char *name)
--     {
--       FILE *stream;
--     
--       errno = 0;
--       stream = fopen (name, "r");
--       if (stream == NULL)
--         {
--           fprintf (stderr, "%s: Couldn't open file %s; %s\n",
--                    program_invocation_short_name, name, strerror (errno));
--           exit (EXIT_FAILURE);
--         }
--       else
--         return stream;
--     }
--
--
--File: libc.info,  Node: Memory Allocation,  Next: Character Handling,  Prev: 
Error Reporting,  Up: Top
--
--Memory Allocation
--*****************
--
--   The GNU system provides several methods for allocating memory space
--under explicit program control.  They vary in generality and in
--efficiency.
--
--* Menu:
--
--* Memory Concepts::             An introduction to concepts and terminology.
--* Dynamic Allocation and C::    How to get different kinds of allocation in C.
--* Unconstrained Allocation::    The `malloc' facility allows fully general
--                               dynamic allocation.
--* Obstacks::                    Obstacks are less general than malloc
--                               but more efficient and convenient.
--* Variable Size Automatic::     Allocation of variable-sized blocks
--                               of automatic storage that are freed when the
--                               calling function returns.
--* Relocating Allocator::        Waste less memory, if you can tolerate
--                               automatic relocation of the blocks you get.
--* Memory Warnings::           Getting warnings when memory is nearly full.
--
--
--File: libc.info,  Node: Memory Concepts,  Next: Dynamic Allocation and C,  
Up: Memory Allocation
--
--Dynamic Memory Allocation Concepts
--==================================
--
--   "Dynamic memory allocation" is a technique in which programs
--determine as they are running where to store some information.  You need
--dynamic allocation when the number of memory blocks you need, or how
--long you continue to need them, depends on the data you are working on.
--
--   For example, you may need a block to store a line read from an input
--file; since there is no limit to how long a line can be, you must
--allocate the storage dynamically and make it dynamically larger as you
--read more of the line.
--
--   Or, you may need a block for each record or each definition in the
--input data; since you can't know in advance how many there will be, you
--must allocate a new block for each record or definition as you read it.
--
--   When you use dynamic allocation, the allocation of a block of memory
--is an action that the program requests explicitly.  You call a function
--or macro when you want to allocate space, and specify the size with an
--argument.  If you want to free the space, you do so by calling another
--function or macro.  You can do these things whenever you want, as often
--as you want.
--
--
--File: libc.info,  Node: Dynamic Allocation and C,  Next: Unconstrained 
Allocation,  Prev: Memory Concepts,  Up: Memory Allocation
--
--Dynamic Allocation and C
--========================
--
--   The C language supports two kinds of memory allocation through the
--variables in C programs:
--
--   * "Static allocation" is what happens when you declare a static or
--     global variable.  Each static or global variable defines one block
--     of space, of a fixed size.  The space is allocated once, when your
--     program is started, and is never freed.
--
--   * "Automatic allocation" happens when you declare an automatic
--     variable, such as a function argument or a local variable.  The
--     space for an automatic variable is allocated when the compound
--     statement containing the declaration is entered, and is freed when
--     that compound statement is exited.
--
--     In GNU C, the length of the automatic storage can be an expression
--     that varies.  In other C implementations, it must be a constant.
--
--   Dynamic allocation is not supported by C variables; there is no
--storage class "dynamic", and there can never be a C variable whose
--value is stored in dynamically allocated space.  The only way to refer
--to dynamically allocated space is through a pointer.  Because it is less
--convenient, and because the actual process of dynamic allocation
--requires more computation time, programmers generally use dynamic
--allocation only when neither static nor automatic allocation will serve.
--
--   For example, if you want to allocate dynamically some space to hold a
--`struct foobar', you cannot declare a variable of type `struct foobar'
--whose contents are the dynamically allocated space.  But you can
--declare a variable of pointer type `struct foobar *' and assign it the
--address of the space.  Then you can use the operators `*' and `->' on
--this pointer variable to refer to the contents of the space:
--
--     {
--       struct foobar *ptr
--          = (struct foobar *) malloc (sizeof (struct foobar));
--       ptr->name = x;
--       ptr->next = current_foobar;
--       current_foobar = ptr;
--     }
--
--
--File: libc.info,  Node: Unconstrained Allocation,  Next: Obstacks,  Prev: 
Dynamic Allocation and C,  Up: Memory Allocation
--
--Unconstrained Allocation
--========================
--
--   The most general dynamic allocation facility is `malloc'.  It allows
--you to allocate blocks of memory of any size at any time, make them
--bigger or smaller at any time, and free the blocks individually at any
--time (or never).
--
--* Menu:
--
--* Basic Allocation::            Simple use of `malloc'.
--* Malloc Examples::             Examples of `malloc'.  `xmalloc'.
--* Freeing after Malloc::        Use `free' to free a block you
--                               got with `malloc'.
--* Changing Block Size::         Use `realloc' to make a block
--                               bigger or smaller.
--* Allocating Cleared Space::    Use `calloc' to allocate a
--                               block and clear it.
--* Efficiency and Malloc::       Efficiency considerations in use of
--                               these functions.
--* Aligned Memory Blocks::       Allocating specially aligned memory:
--                               `memalign' and `valloc'.
--* Heap Consistency Checking::   Automatic checking for errors.
--* Hooks for Malloc::            You can use these hooks for debugging
--                               programs that use `malloc'.
--* Statistics of Malloc::        Getting information about how much
--                               memory your program is using.
--* Summary of Malloc::           Summary of `malloc' and related functions.
--
--
--File: libc.info,  Node: Basic Allocation,  Next: Malloc Examples,  Up: 
Unconstrained Allocation
--
--Basic Storage Allocation
--------------------------
--
--   To allocate a block of memory, call `malloc'.  The prototype for
--this function is in `stdlib.h'.
--
-- - Function: void * malloc (size_t SIZE)
--     This function returns a pointer to a newly allocated block SIZE
--     bytes long, or a null pointer if the block could not be allocated.
--
--   The contents of the block are undefined; you must initialize it
--yourself (or use `calloc' instead; *note Allocating Cleared Space::.).
--Normally you would cast the value as a pointer to the kind of object
--that you want to store in the block.  Here we show an example of doing
--so, and of initializing the space with zeros using the library function
--`memset' (*note Copying and Concatenation::.):
--
--     struct foo *ptr;
--     ...
--     ptr = (struct foo *) malloc (sizeof (struct foo));
--     if (ptr == 0) abort ();
--     memset (ptr, 0, sizeof (struct foo));
--
--   You can store the result of `malloc' into any pointer variable
--without a cast, because ISO C automatically converts the type `void *'
--to another type of pointer when necessary.  But the cast is necessary
--in contexts other than assignment operators or if you might want your
--code to run in traditional C.
--
--   Remember that when allocating space for a string, the argument to
--`malloc' must be one plus the length of the string.  This is because a
--string is terminated with a null character that doesn't count in the
--"length" of the string but does need space.  For example:
--
--     char *ptr;
--     ...
--     ptr = (char *) malloc (length + 1);
--
--*Note Representation of Strings::, for more information about this.
--
--
--File: libc.info,  Node: Malloc Examples,  Next: Freeing after Malloc,  Prev: 
Basic Allocation,  Up: Unconstrained Allocation
--
--Examples of `malloc'
----------------------
--
--   If no more space is available, `malloc' returns a null pointer.  You
--should check the value of *every* call to `malloc'.  It is useful to
--write a subroutine that calls `malloc' and reports an error if the
--value is a null pointer, returning only if the value is nonzero.  This
--function is conventionally called `xmalloc'.  Here it is:
--
--     void *
--     xmalloc (size_t size)
--     {
--       register void *value = malloc (size);
--       if (value == 0)
--         fatal ("virtual memory exhausted");
--       return value;
--     }
--
--   Here is a real example of using `malloc' (by way of `xmalloc').  The
--function `savestring' will copy a sequence of characters into a newly
--allocated null-terminated string:
--
--     char *
--     savestring (const char *ptr, size_t len)
--     {
--       register char *value = (char *) xmalloc (len + 1);
--       memcpy (value, ptr, len);
--       value[len] = '\0';
--       return value;
--     }
--
--   The block that `malloc' gives you is guaranteed to be aligned so
--that it can hold any type of data.  In the GNU system, the address is
--always a multiple of eight; if the size of block is 16 or more, then the
--address is always a multiple of 16.  Only rarely is any higher boundary
--(such as a page boundary) necessary; for those cases, use `memalign' or
--`valloc' (*note Aligned Memory Blocks::.).
--
--   Note that the memory located after the end of the block is likely to
--be in use for something else; perhaps a block already allocated by
--another call to `malloc'.  If you attempt to treat the block as longer
--than you asked for it to be, you are liable to destroy the data that
--`malloc' uses to keep track of its blocks, or you may destroy the
--contents of another block.  If you have already allocated a block and
--discover you want it to be bigger, use `realloc' (*note Changing Block
--Size::.).
--
--
--File: libc.info,  Node: Freeing after Malloc,  Next: Changing Block Size,  
Prev: Malloc Examples,  Up: Unconstrained Allocation
--
--Freeing Memory Allocated with `malloc'
----------------------------------------
--
--   When you no longer need a block that you got with `malloc', use the
--function `free' to make the block available to be allocated again.  The
--prototype for this function is in `stdlib.h'.
--
-- - Function: void free (void *PTR)
--     The `free' function deallocates the block of storage pointed at by
--     PTR.
--
-- - Function: void cfree (void *PTR)
--     This function does the same thing as `free'.  It's provided for
--     backward compatibility with SunOS; you should use `free' instead.
--
--   Freeing a block alters the contents of the block.  *Do not expect to
--find any data (such as a pointer to the next block in a chain of
--blocks) in the block after freeing it.*  Copy whatever you need out of
--the block before freeing it!  Here is an example of the proper way to
--free all the blocks in a chain, and the strings that they point to:
--
--     struct chain
--       {
--         struct chain *next;
--         char *name;
--       }
--     
--     void
--     free_chain (struct chain *chain)
--     {
--       while (chain != 0)
--         {
--           struct chain *next = chain->next;
--           free (chain->name);
--           free (chain);
--           chain = next;
--         }
--     }
--
--   Occasionally, `free' can actually return memory to the operating
--system and make the process smaller.  Usually, all it can do is allow a
--later call to `malloc' to reuse the space.  In the meantime, the space
--remains in your program as part of a free-list used internally by
--`malloc'.
--
--   There is no point in freeing blocks at the end of a program, because
--all of the program's space is given back to the system when the process
--terminates.
--
--
--File: libc.info,  Node: Changing Block Size,  Next: Allocating Cleared Space, 
 Prev: Freeing after Malloc,  Up: Unconstrained Allocation
--
--Changing the Size of a Block
------------------------------
--
--   Often you do not know for certain how big a block you will
--ultimately need at the time you must begin to use the block.  For
--example, the block might be a buffer that you use to hold a line being
--read from a file; no matter how long you make the buffer initially, you
--may encounter a line that is longer.
--
--   You can make the block longer by calling `realloc'.  This function
--is declared in `stdlib.h'.
--
-- - Function: void * realloc (void *PTR, size_t NEWSIZE)
--     The `realloc' function changes the size of the block whose address
--     is PTR to be NEWSIZE.
--
--     Since the space after the end of the block may be in use, `realloc'
--     may find it necessary to copy the block to a new address where
--     more free space is available.  The value of `realloc' is the new
--     address of the block.  If the block needs to be moved, `realloc'
--     copies the old contents.
--
--     If you pass a null pointer for PTR, `realloc' behaves just like
--     `malloc (NEWSIZE)'.  This can be convenient, but beware that older
--     implementations (before ISO C) may not support this behavior, and
--     will probably crash when `realloc' is passed a null pointer.
--
--   Like `malloc', `realloc' may return a null pointer if no memory
--space is available to make the block bigger.  When this happens, the
--original block is untouched; it has not been modified or relocated.
--
--   In most cases it makes no difference what happens to the original
--block when `realloc' fails, because the application program cannot
--continue when it is out of memory, and the only thing to do is to give
--a fatal error message.  Often it is convenient to write and use a
--subroutine, conventionally called `xrealloc', that takes care of the
--error message as `xmalloc' does for `malloc':
--
--     void *
--     xrealloc (void *ptr, size_t size)
--     {
--       register void *value = realloc (ptr, size);
--       if (value == 0)
--         fatal ("Virtual memory exhausted");
--       return value;
--     }
--
--   You can also use `realloc' to make a block smaller.  The reason you
--would do this is to avoid tying up a lot of memory space when only a
--little is needed.  Making a block smaller sometimes necessitates
--copying it, so it can fail if no other space is available.
--
--   If the new size you specify is the same as the old size, `realloc'
--is guaranteed to change nothing and return the same address that you
--gave.
--
--
--File: libc.info,  Node: Allocating Cleared Space,  Next: Efficiency and 
Malloc,  Prev: Changing Block Size,  Up: Unconstrained Allocation
--
--Allocating Cleared Space
--------------------------
--
--   The function `calloc' allocates memory and clears it to zero.  It is
--declared in `stdlib.h'.
--
-- - Function: void * calloc (size_t COUNT, size_t ELTSIZE)
--     This function allocates a block long enough to contain a vector of
--     COUNT elements, each of size ELTSIZE.  Its contents are cleared to
--     zero before `calloc' returns.
--
--   You could define `calloc' as follows:
--
--     void *
--     calloc (size_t count, size_t eltsize)
--     {
--       size_t size = count * eltsize;
--       void *value = malloc (size);
--       if (value != 0)
--         memset (value, 0, size);
--       return value;
--     }
--
--
--File: libc.info,  Node: Efficiency and Malloc,  Next: Aligned Memory Blocks,  
Prev: Allocating Cleared Space,  Up: Unconstrained Allocation
--
--Efficiency Considerations for `malloc'
----------------------------------------
--
--   To make the best use of `malloc', it helps to know that the GNU
--version of `malloc' always dispenses small amounts of memory in blocks
--whose sizes are powers of two.  It keeps separate pools for each power
--of two.  This holds for sizes up to a page size.  Therefore, if you are
--free to choose the size of a small block in order to make `malloc' more
--efficient, make it a power of two.
--
--   Once a page is split up for a particular block size, it can't be
--reused for another size unless all the blocks in it are freed.  In many
--programs, this is unlikely to happen.  Thus, you can sometimes make a
--program use memory more efficiently by using blocks of the same size for
--many different purposes.
--
--   When you ask for memory blocks of a page or larger, `malloc' uses a
--different strategy; it rounds the size up to a multiple of a page, and
--it can coalesce and split blocks as needed.
--
--   The reason for the two strategies is that it is important to allocate
--and free small blocks as fast as possible, but speed is less important
--for a large block since the program normally spends a fair amount of
--time using it.  Also, large blocks are normally fewer in number.
--Therefore, for large blocks, it makes sense to use a method which takes
--more time to minimize the wasted space.
--
--
--File: libc.info,  Node: Aligned Memory Blocks,  Next: Heap Consistency 
Checking,  Prev: Efficiency and Malloc,  Up: Unconstrained Allocation
--
--Allocating Aligned Memory Blocks
----------------------------------
--
--   The address of a block returned by `malloc' or `realloc' in the GNU
--system is always a multiple of eight.  If you need a block whose
--address is a multiple of a higher power of two than that, use
--`memalign' or `valloc'.  These functions are declared in `stdlib.h'.
--
--   With the GNU library, you can use `free' to free the blocks that
--`memalign' and `valloc' return.  That does not work in BSD,
--however--BSD does not provide any way to free such blocks.
--
-- - Function: void * memalign (size_t BOUNDARY, size_t SIZE)
--     The `memalign' function allocates a block of SIZE bytes whose
--     address is a multiple of BOUNDARY.  The BOUNDARY must be a power
--     of two!  The function `memalign' works by calling `malloc' to
--     allocate a somewhat larger block, and then returning an address
--     within the block that is on the specified boundary.
--
-- - Function: void * valloc (size_t SIZE)
--     Using `valloc' is like using `memalign' and passing the page size
--     as the value of the second argument.  It is implemented like this:
--
--          void *
--          valloc (size_t size)
--          {
--            return memalign (getpagesize (), size);
--          }
--
--
--File: libc.info,  Node: Heap Consistency Checking,  Next: Hooks for Malloc,  
Prev: Aligned Memory Blocks,  Up: Unconstrained Allocation
--
--Heap Consistency Checking
---------------------------
--
--   You can ask `malloc' to check the consistency of dynamic storage by
--using the `mcheck' function.  This function is a GNU extension,
--declared in `malloc.h'.
--
-- - Function: int mcheck (void (*ABORTFN) (enum mcheck_status STATUS))
--     Calling `mcheck' tells `malloc' to perform occasional consistency
--     checks.  These will catch things such as writing past the end of a
--     block that was allocated with `malloc'.
--
--     The ABORTFN argument is the function to call when an inconsistency
--     is found.  If you supply a null pointer, then `mcheck' uses a
--     default function which prints a message and calls `abort' (*note
--     Aborting a Program::.).  The function you supply is called with
--     one argument, which says what sort of inconsistency was detected;
--     its type is described below.
--
--     It is too late to begin allocation checking once you have allocated
--     anything with `malloc'.  So `mcheck' does nothing in that case.
--     The function returns `-1' if you call it too late, and `0'
--     otherwise (when it is successful).
--
--     The easiest way to arrange to call `mcheck' early enough is to use
--     the option `-lmcheck' when you link your program; then you don't
--     need to modify your program source at all.
--
-- - Function: enum mcheck_status mprobe (void *POINTER)
--     The `mprobe' function lets you explicitly check for inconsistencies
--     in a particular allocated block.  You must have already called
--     `mcheck' at the beginning of the program, to do its occasional
--     checks; calling `mprobe' requests an additional consistency check
--     to be done at the time of the call.
--
--     The argument POINTER must be a pointer returned by `malloc' or
--     `realloc'.  `mprobe' returns a value that says what inconsistency,
--     if any, was found.  The values are described below.
--
-- - Data Type: enum mcheck_status
--     This enumerated type describes what kind of inconsistency was
--     detected in an allocated block, if any.  Here are the possible
--     values:
--
--    `MCHECK_DISABLED'
--          `mcheck' was not called before the first allocation.  No
--          consistency checking can be done.
--
--    `MCHECK_OK'
--          No inconsistency detected.
--
--    `MCHECK_HEAD'
--          The data immediately before the block was modified.  This
--          commonly happens when an array index or pointer is
--          decremented too far.
--
--    `MCHECK_TAIL'
--          The data immediately after the block was modified.  This
--          commonly happens when an array index or pointer is
--          incremented too far.
--
--    `MCHECK_FREE'
--          The block was already freed.
--
--
--File: libc.info,  Node: Hooks for Malloc,  Next: Statistics of Malloc,  Prev: 
Heap Consistency Checking,  Up: Unconstrained Allocation
--
--Storage Allocation Hooks
--------------------------
--
--   The GNU C library lets you modify the behavior of `malloc',
--`realloc', and `free' by specifying appropriate hook functions.  You
--can use these hooks to help you debug programs that use dynamic storage
--allocation, for example.
--
--   The hook variables are declared in `malloc.h'.
--
-- - Variable: __malloc_hook
--     The value of this variable is a pointer to function that `malloc'
--     uses whenever it is called.  You should define this function to
--     look like `malloc'; that is, like:
--
--          void *FUNCTION (size_t SIZE)
--
-- - Variable: __realloc_hook
--     The value of this variable is a pointer to function that `realloc'
--     uses whenever it is called.  You should define this function to
--     look like `realloc'; that is, like:
--
--          void *FUNCTION (void *PTR, size_t SIZE)
--
-- - Variable: __free_hook
--     The value of this variable is a pointer to function that `free'
--     uses whenever it is called.  You should define this function to
--     look like `free'; that is, like:
--
--          void FUNCTION (void *PTR)
--
--   You must make sure that the function you install as a hook for one of
--these functions does not call that function recursively without
--restoring the old value of the hook first!  Otherwise, your program
--will get stuck in an infinite recursion.
--
--   Here is an example showing how to use `__malloc_hook' properly.  It
--installs a function that prints out information every time `malloc' is
--called.
--
--     static void *(*old_malloc_hook) (size_t);
--     static void *
--     my_malloc_hook (size_t size)
--     {
--       void *result;
--       __malloc_hook = old_malloc_hook;
--       result = malloc (size);
--       /* `printf' might call `malloc', so protect it too. */
--       printf ("malloc (%u) returns %p\n", (unsigned int) size, result);
--       __malloc_hook = my_malloc_hook;
--       return result;
--     }
--     
--     main ()
--     {
--       ...
--       old_malloc_hook = __malloc_hook;
--       __malloc_hook = my_malloc_hook;
--       ...
--     }
--
--   The `mcheck' function (*note Heap Consistency Checking::.) works by
--installing such hooks.
--
--
--File: libc.info,  Node: Statistics of Malloc,  Next: Summary of Malloc,  
Prev: Hooks for Malloc,  Up: Unconstrained Allocation
--
--Statistics for Storage Allocation with `malloc'
-------------------------------------------------
--
--   You can get information about dynamic storage allocation by calling
--the `mstats' function.  This function and its associated data type are
--declared in `malloc.h'; they are a GNU extension.
--
-- - Data Type: struct mstats
--     This structure type is used to return information about the dynamic
--     storage allocator.  It contains the following members:
--
--    `size_t bytes_total'
--          This is the total size of memory managed by `malloc', in
--          bytes.
--
--    `size_t chunks_used'
--          This is the number of chunks in use.  (The storage allocator
--          internally gets chunks of memory from the operating system,
--          and then carves them up to satisfy individual `malloc'
--          requests; see *Note Efficiency and Malloc::.)
--
--    `size_t bytes_used'
--          This is the number of bytes in use.
--
--    `size_t chunks_free'
--          This is the number of chunks which are free - that is, that
--          have been allocated by the operating system to your program,
--          but which are not now being used.
--
--    `size_t bytes_free'
--          This is the number of bytes which are free.
--
-- - Function: struct mstats mstats (void)
--     This function returns information about the current dynamic memory
--     usage in a structure of type `struct mstats'.
--
--
--File: libc.info,  Node: Summary of Malloc,  Prev: Statistics of Malloc,  Up: 
Unconstrained Allocation
--
--Summary of `malloc'-Related Functions
---------------------------------------
--
--   Here is a summary of the functions that work with `malloc':
--
--`void *malloc (size_t SIZE)'
--     Allocate a block of SIZE bytes.  *Note Basic Allocation::.
--
--`void free (void *ADDR)'
--     Free a block previously allocated by `malloc'.  *Note Freeing
--     after Malloc::.
--
--`void *realloc (void *ADDR, size_t SIZE)'
--     Make a block previously allocated by `malloc' larger or smaller,
--     possibly by copying it to a new location.  *Note Changing Block
--     Size::.
--
--`void *calloc (size_t COUNT, size_t ELTSIZE)'
--     Allocate a block of COUNT * ELTSIZE bytes using `malloc', and set
--     its contents to zero.  *Note Allocating Cleared Space::.
--
--`void *valloc (size_t SIZE)'
--     Allocate a block of SIZE bytes, starting on a page boundary.
--     *Note Aligned Memory Blocks::.
--
--`void *memalign (size_t SIZE, size_t BOUNDARY)'
--     Allocate a block of SIZE bytes, starting on an address that is a
--     multiple of BOUNDARY.  *Note Aligned Memory Blocks::.
--
--`int mcheck (void (*ABORTFN) (void))'
--     Tell `malloc' to perform occasional consistency checks on
--     dynamically allocated memory, and to call ABORTFN when an
--     inconsistency is found.  *Note Heap Consistency Checking::.
--
--`void *(*__malloc_hook) (size_t SIZE)'
--     A pointer to a function that `malloc' uses whenever it is called.
--
--`void *(*__realloc_hook) (void *PTR, size_t SIZE)'
--     A pointer to a function that `realloc' uses whenever it is called.
--
--`void (*__free_hook) (void *PTR)'
--     A pointer to a function that `free' uses whenever it is called.
--
--`struct mstats mstats (void)'
--     Return information about the current dynamic memory usage.  *Note
--     Statistics of Malloc::.
--
--
--File: libc.info,  Node: Obstacks,  Next: Variable Size Automatic,  Prev: 
Unconstrained Allocation,  Up: Memory Allocation
--
--Obstacks
--========
--
--   An "obstack" is a pool of memory containing a stack of objects.  You
--can create any number of separate obstacks, and then allocate objects in
--specified obstacks.  Within each obstack, the last object allocated must
--always be the first one freed, but distinct obstacks are independent of
--each other.
--
--   Aside from this one constraint of order of freeing, obstacks are
--totally general: an obstack can contain any number of objects of any
--size.  They are implemented with macros, so allocation is usually very
--fast as long as the objects are usually small.  And the only space
--overhead per object is the padding needed to start each object on a
--suitable boundary.
--
--* Menu:
--
--* Creating Obstacks::         How to declare an obstack in your program.
--* Preparing for Obstacks::    Preparations needed before you can
--                               use obstacks.
--* Allocation in an Obstack::    Allocating objects in an obstack.
--* Freeing Obstack Objects::     Freeing objects in an obstack.
--* Obstack Functions::         The obstack functions are both
--                               functions and macros.
--* Growing Objects::             Making an object bigger by stages.
--* Extra Fast Growing::                Extra-high-efficiency (though more
--                               complicated) growing objects.
--* Status of an Obstack::        Inquiries about the status of an obstack.
--* Obstacks Data Alignment::     Controlling alignment of objects in obstacks.
--* Obstack Chunks::              How obstacks obtain and release chunks;
--                               efficiency considerations.
--* Summary of Obstacks::
--
--
--File: libc.info,  Node: Creating Obstacks,  Next: Preparing for Obstacks,  
Up: Obstacks
--
--Creating Obstacks
-------------------
--
--   The utilities for manipulating obstacks are declared in the header
--file `obstack.h'.
--
-- - Data Type: struct obstack
--     An obstack is represented by a data structure of type `struct
--     obstack'.  This structure has a small fixed size; it records the
--     status of the obstack and how to find the space in which objects
--     are allocated.  It does not contain any of the objects themselves.
--     You should not try to access the contents of the structure
--     directly; use only the functions described in this chapter.
--
--   You can declare variables of type `struct obstack' and use them as
--obstacks, or you can allocate obstacks dynamically like any other kind
--of object.  Dynamic allocation of obstacks allows your program to have a
--variable number of different stacks.  (You can even allocate an obstack
--structure in another obstack, but this is rarely useful.)
--
--   All the functions that work with obstacks require you to specify
--which obstack to use.  You do this with a pointer of type `struct
--obstack *'.  In the following, we often say "an obstack" when strictly
--speaking the object at hand is such a pointer.
--
--   The objects in the obstack are packed into large blocks called
--"chunks".  The `struct obstack' structure points to a chain of the
--chunks currently in use.
--
--   The obstack library obtains a new chunk whenever you allocate an
--object that won't fit in the previous chunk.  Since the obstack library
--manages chunks automatically, you don't need to pay much attention to
--them, but you do need to supply a function which the obstack library
--should use to get a chunk.  Usually you supply a function which uses
--`malloc' directly or indirectly.  You must also supply a function to
--free a chunk.  These matters are described in the following section.
--
--
--File: libc.info,  Node: Preparing for Obstacks,  Next: Allocation in an 
Obstack,  Prev: Creating Obstacks,  Up: Obstacks
--
--Preparing for Using Obstacks
------------------------------
--
--   Each source file in which you plan to use the obstack functions must
--include the header file `obstack.h', like this:
--
--     #include <obstack.h>
--
--   Also, if the source file uses the macro `obstack_init', it must
--declare or define two functions or macros that will be called by the
--obstack library.  One, `obstack_chunk_alloc', is used to allocate the
--chunks of memory into which objects are packed.  The other,
--`obstack_chunk_free', is used to return chunks when the objects in them
--are freed.  These macros should appear before any use of obstacks in
--the source file.
--
--   Usually these are defined to use `malloc' via the intermediary
--`xmalloc' (*note Unconstrained Allocation::.).  This is done with the
--following pair of macro definitions:
--
--     #define obstack_chunk_alloc xmalloc
--     #define obstack_chunk_free free
--
--Though the storage you get using obstacks really comes from `malloc',
--using obstacks is faster because `malloc' is called less often, for
--larger blocks of memory.  *Note Obstack Chunks::, for full details.
--
--   At run time, before the program can use a `struct obstack' object as
--an obstack, it must initialize the obstack by calling `obstack_init'.
--
-- - Function: int obstack_init (struct obstack *OBSTACK-PTR)
--     Initialize obstack OBSTACK-PTR for allocation of objects.  This
--     function calls the obstack's `obstack_chunk_alloc' function.  It
--     returns 0 if `obstack_chunk_alloc' returns a null pointer, meaning
--     that it is out of memory.  Otherwise, it returns 1.  If you supply
--     an `obstack_chunk_alloc' function that calls `exit' (*note Program
--     Termination::.) or `longjmp' (*note Non-Local Exits::.) when out
--     of memory, you can safely ignore the value that `obstack_init'
--     returns.
--
--   Here are two examples of how to allocate the space for an obstack and
--initialize it.  First, an obstack that is a static variable:
--
--     static struct obstack myobstack;
--     ...
--     obstack_init (&myobstack);
--
--Second, an obstack that is itself dynamically allocated:
--
--     struct obstack *myobstack_ptr
--       = (struct obstack *) xmalloc (sizeof (struct obstack));
--     
--     obstack_init (myobstack_ptr);
--
--
--File: libc.info,  Node: Allocation in an Obstack,  Next: Freeing Obstack 
Objects,  Prev: Preparing for Obstacks,  Up: Obstacks
--
--Allocation in an Obstack
--------------------------
--
--   The most direct way to allocate an object in an obstack is with
--`obstack_alloc', which is invoked almost like `malloc'.
--
-- - Function: void * obstack_alloc (struct obstack *OBSTACK-PTR, int
--          SIZE)
--     This allocates an uninitialized block of SIZE bytes in an obstack
--     and returns its address.  Here OBSTACK-PTR specifies which obstack
--     to allocate the block in; it is the address of the `struct obstack'
--     object which represents the obstack.  Each obstack function or
--     macro requires you to specify an OBSTACK-PTR as the first argument.
--
--     This function calls the obstack's `obstack_chunk_alloc' function if
--     it needs to allocate a new chunk of memory; it returns a null
--     pointer if `obstack_chunk_alloc' returns one.  In that case, it
--     has not changed the amount of memory allocated in the obstack.  If
--     you supply an `obstack_chunk_alloc' function that calls `exit'
--     (*note Program Termination::.) or `longjmp' (*note Non-Local
--     Exits::.) when out of memory, then `obstack_alloc' will never
--     return a null pointer.
--
--   For example, here is a function that allocates a copy of a string STR
--in a specific obstack, which is in the variable `string_obstack':
--
--     struct obstack string_obstack;
--     
--     char *
--     copystring (char *string)
--     {
--       char *s = (char *) obstack_alloc (&string_obstack,
--                                         strlen (string) + 1);
--       memcpy (s, string, strlen (string));
--       return s;
--     }
--
--   To allocate a block with specified contents, use the function
--`obstack_copy', declared like this:
--
-- - Function: void * obstack_copy (struct obstack *OBSTACK-PTR, void
--          *ADDRESS, int SIZE)
--     This allocates a block and initializes it by copying SIZE bytes of
--     data starting at ADDRESS.  It can return a null pointer under the
--     same conditions as `obstack_alloc'.
--
-- - Function: void * obstack_copy0 (struct obstack *OBSTACK-PTR, void
--          *ADDRESS, int SIZE)
--     Like `obstack_copy', but appends an extra byte containing a null
--     character.  This extra byte is not counted in the argument SIZE.
--
--   The `obstack_copy0' function is convenient for copying a sequence of
--characters into an obstack as a null-terminated string.  Here is an
--example of its use:
--
--     char *
--     obstack_savestring (char *addr, int size)
--     {
--       return obstack_copy0 (&myobstack, addr, size);
--     }
--
--Contrast this with the previous example of `savestring' using `malloc'
--(*note Basic Allocation::.).
--
--
--File: libc.info,  Node: Freeing Obstack Objects,  Next: Obstack Functions,  
Prev: Allocation in an Obstack,  Up: Obstacks
--
--Freeing Objects in an Obstack
-------------------------------
--
--   To free an object allocated in an obstack, use the function
--`obstack_free'.  Since the obstack is a stack of objects, freeing one
--object automatically frees all other objects allocated more recently in
--the same obstack.
--
-- - Function: void obstack_free (struct obstack *OBSTACK-PTR, void
--          *OBJECT)
--     If OBJECT is a null pointer, everything allocated in the obstack
--     is freed.  Otherwise, OBJECT must be the address of an object
--     allocated in the obstack.  Then OBJECT is freed, along with
--     everything allocated in OBSTACK since OBJECT.
--
--   Note that if OBJECT is a null pointer, the result is an
--uninitialized obstack.  To free all storage in an obstack but leave it
--valid for further allocation, call `obstack_free' with the address of
--the first object allocated on the obstack:
--
--     obstack_free (obstack_ptr, first_object_allocated_ptr);
--
--   Recall that the objects in an obstack are grouped into chunks.  When
--all the objects in a chunk become free, the obstack library
--automatically frees the chunk (*note Preparing for Obstacks::.).  Then
--other obstacks, or non-obstack allocation, can reuse the space of the
--chunk.
--
--
--File: libc.info,  Node: Obstack Functions,  Next: Growing Objects,  Prev: 
Freeing Obstack Objects,  Up: Obstacks
--
--Obstack Functions and Macros
------------------------------
--
--   The interfaces for using obstacks may be defined either as functions
--or as macros, depending on the compiler.  The obstack facility works
--with all C compilers, including both ISO C and traditional C, but there
--are precautions you must take if you plan to use compilers other than
--GNU C.
--
--   If you are using an old-fashioned non-ISO C compiler, all the obstack
--"functions" are actually defined only as macros.  You can call these
--macros like functions, but you cannot use them in any other way (for
--example, you cannot take their address).
--
--   Calling the macros requires a special precaution: namely, the first
--operand (the obstack pointer) may not contain any side effects, because
--it may be computed more than once.  For example, if you write this:
--
--     obstack_alloc (get_obstack (), 4);
--
--you will find that `get_obstack' may be called several times.  If you
--use `*obstack_list_ptr++' as the obstack pointer argument, you will get
--very strange results since the incrementation may occur several times.
--
--   In ISO C, each function has both a macro definition and a function
--definition.  The function definition is used if you take the address of
--the function without calling it.  An ordinary call uses the macro
--definition by default, but you can request the function definition
--instead by writing the function name in parentheses, as shown here:
--
--     char *x;
--     void *(*funcp) ();
--     /* Use the macro.  */
--     x = (char *) obstack_alloc (obptr, size);
--     /* Call the function.  */
--     x = (char *) (obstack_alloc) (obptr, size);
--     /* Take the address of the function.  */
--     funcp = obstack_alloc;
--
--This is the same situation that exists in ISO C for the standard library
--functions.  *Note Macro Definitions::.
--
--   *Warning:* When you do use the macros, you must observe the
--precaution of avoiding side effects in the first operand, even in ISO C.
--
--   If you use the GNU C compiler, this precaution is not necessary,
--because various language extensions in GNU C permit defining the macros
--so as to compute each argument only once.
--
--
--File: libc.info,  Node: Growing Objects,  Next: Extra Fast Growing,  Prev: 
Obstack Functions,  Up: Obstacks
--
--Growing Objects
-----------------
--
--   Because storage in obstack chunks is used sequentially, it is
--possible to build up an object step by step, adding one or more bytes
--at a time to the end of the object.  With this technique, you do not
--need to know how much data you will put in the object until you come to
--the end of it.  We call this the technique of "growing objects".  The
--special functions for adding data to the growing object are described
--in this section.
--
--   You don't need to do anything special when you start to grow an
--object.  Using one of the functions to add data to the object
--automatically starts it.  However, it is necessary to say explicitly
--when the object is finished.  This is done with the function
--`obstack_finish'.
--
--   The actual address of the object thus built up is not known until the
--object is finished.  Until then, it always remains possible that you
--will add so much data that the object must be copied into a new chunk.
--
--   While the obstack is in use for a growing object, you cannot use it
--for ordinary allocation of another object.  If you try to do so, the
--space already added to the growing object will become part of the other
--object.
--
-- - Function: void obstack_blank (struct obstack *OBSTACK-PTR, int SIZE)
--     The most basic function for adding to a growing object is
--     `obstack_blank', which adds space without initializing it.
--
-- - Function: void obstack_grow (struct obstack *OBSTACK-PTR, void
--          *DATA, int SIZE)
--     To add a block of initialized space, use `obstack_grow', which is
--     the growing-object analogue of `obstack_copy'.  It adds SIZE bytes
--     of data to the growing object, copying the contents from DATA.
--
-- - Function: void obstack_grow0 (struct obstack *OBSTACK-PTR, void
--          *DATA, int SIZE)
--     This is the growing-object analogue of `obstack_copy0'.  It adds
--     SIZE bytes copied from DATA, followed by an additional null
--     character.
--
-- - Function: void obstack_1grow (struct obstack *OBSTACK-PTR, char C)
--     To add one character at a time, use the function `obstack_1grow'.
--     It adds a single byte containing C to the growing object.
--
-- - Function: void obstack_ptr_grow (struct obstack *OBSTACK-PTR, void
--          *DATA)
--     Adding the value of a pointer one can use the function
--     `obstack_ptr_grow'.  It adds `sizeof (void *)' bytes containing
--     the value of DATA.
--
-- - Function: void obstack_int_grow (struct obstack *OBSTACK-PTR, int
--          DATA)
--     A single value of type `int' can be added by using the
--     `obstack_int_grow' function.  It adds `sizeof (int)' bytes to the
--     growing object and initializes them with the value of DATA.
--
-- - Function: void * obstack_finish (struct obstack *OBSTACK-PTR)
--     When you are finished growing the object, use the function
--     `obstack_finish' to close it off and return its final address.
--
--     Once you have finished the object, the obstack is available for
--     ordinary allocation or for growing another object.
--
--     This function can return a null pointer under the same conditions
--     as `obstack_alloc' (*note Allocation in an Obstack::.).
--
--   When you build an object by growing it, you will probably need to
--know afterward how long it became.  You need not keep track of this as
--you grow the object, because you can find out the length from the
--obstack just before finishing the object with the function
--`obstack_object_size', declared as follows:
--
-- - Function: int obstack_object_size (struct obstack *OBSTACK-PTR)
--     This function returns the current size of the growing object, in
--     bytes.  Remember to call this function *before* finishing the
--     object.  After it is finished, `obstack_object_size' will return
--     zero.
--
--   If you have started growing an object and wish to cancel it, you
--should finish it and then free it, like this:
--
--     obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
--
--This has no effect if no object was growing.
--
--   You can use `obstack_blank' with a negative size argument to make
--the current object smaller.  Just don't try to shrink it beyond zero
--length--there's no telling what will happen if you do that.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-30 
glibc-2.0.1/manual/libc.info-30
---- ../glibc-2.0.1/manual/libc.info-30 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-30    1970-01-01 01:00:00.000000000 +0100
-@@ -1,530 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Copying,  Next: Concept Index,  Prev: Maintenance,  
Up: Top
--
--GNU LIBRARY GENERAL PUBLIC LICENSE
--**********************************
--
--                         Version 2, June 1991
--
--     Copyright (C) 1991 Free Software Foundation, Inc.
--     675 Mass Ave, Cambridge, MA 02139, USA
--     Everyone is permitted to copy and distribute verbatim copies
--     of this license document, but changing it is not allowed.
--     
--     [This is the first released version of the library GPL.  It is
--      numbered 2 because it goes with version 2 of the ordinary GPL.]
--
--Preamble
--========
--
--   The licenses for most software are designed to take away your
--freedom to share and change it.  By contrast, the GNU General Public
--Licenses are intended to guarantee your freedom to share and change
--free software--to make sure the software is free for all its users.
--
--   This license, the Library General Public License, applies to some
--specially designated Free Software Foundation software, and to any
--other libraries whose authors decide to use it.  You can use it for
--your libraries, too.
--
--   When we speak of free software, we are referring to freedom, not
--price.  Our General Public Licenses are designed to make sure that you
--have the freedom to distribute copies of free software (and charge for
--this service if you wish), that you receive source code or can get it
--if you want it, that you can change the software or use pieces of it in
--new free programs; and that you know you can do these things.
--
--   To protect your rights, we need to make restrictions that forbid
--anyone to deny you these rights or to ask you to surrender the rights.
--These restrictions translate to certain responsibilities for you if you
--distribute copies of the library, or if you modify it.
--
--   For example, if you distribute copies of the library, whether gratis
--or for a fee, you must give the recipients all the rights that we gave
--you.  You must make sure that they, too, receive or can get the source
--code.  If you link a program with the library, you must provide
--complete object files to the recipients so that they can relink them
--with the library, after making changes to the library and recompiling
--it.  And you must show them these terms so they know their rights.
--
--   Our method of protecting your rights has two steps: (1) copyright
--the library, and (2) offer you this license which gives you legal
--permission to copy, distribute and/or modify the library.
--
--   Also, for each distributor's protection, we want to make certain
--that everyone understands that there is no warranty for this free
--library.  If the library is modified by someone else and passed on, we
--want its recipients to know that what they have is not the original
--version, so that any problems introduced by others will not reflect on
--the original authors' reputations.
--
--   Finally, any free program is threatened constantly by software
--patents.  We wish to avoid the danger that companies distributing free
--software will individually obtain patent licenses, thus in effect
--transforming the program into proprietary software.  To prevent this,
--we have made it clear that any patent must be licensed for everyone's
--free use or not licensed at all.
--
--   Most GNU software, including some libraries, is covered by the
--ordinary GNU General Public License, which was designed for utility
--programs.  This license, the GNU Library General Public License,
--applies to certain designated libraries.  This license is quite
--different from the ordinary one; be sure to read it in full, and don't
--assume that anything in it is the same as in the ordinary license.
--
--   The reason we have a separate public license for some libraries is
--that they blur the distinction we usually make between modifying or
--adding to a program and simply using it.  Linking a program with a
--library, without changing the library, is in some sense simply using
--the library, and is analogous to running a utility program or
--application program.  However, in a textual and legal sense, the linked
--executable is a combined work, a derivative of the original library,
--and the ordinary General Public License treats it as such.
--
--   Because of this blurred distinction, using the ordinary General
--Public License for libraries did not effectively promote software
--sharing, because most developers did not use the libraries.  We
--concluded that weaker conditions might promote sharing better.
--
--   However, unrestricted linking of non-free programs would deprive the
--users of those programs of all benefit from the free status of the
--libraries themselves.  This Library General Public License is intended
--to permit developers of non-free programs to use free libraries, while
--preserving your freedom as a user of such programs to change the free
--libraries that are incorporated in them.  (We have not seen how to
--achieve this as regards changes in header files, but we have achieved
--it as regards changes in the actual functions of the Library.)  The
--hope is that this will lead to faster development of free libraries.
--
--   The precise terms and conditions for copying, distribution and
--modification follow.  Pay close attention to the difference between a
--"work based on the library" and a "work that uses the library".  The
--former contains code derived from the library, while the latter only
--works together with the library.
--
--   Note that it is possible for a library to be covered by the ordinary
--General Public License rather than by this special one.
--
--    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
--
--  0. This License Agreement applies to any software library which
--     contains a notice placed by the copyright holder or other
--     authorized party saying it may be distributed under the terms of
--     this Library General Public License (also called "this License").
--     Each licensee is addressed as "you".
--
--     A "library" means a collection of software functions and/or data
--     prepared so as to be conveniently linked with application programs
--     (which use some of those functions and data) to form executables.
--
--     The "Library", below, refers to any such software library or work
--     which has been distributed under these terms.  A "work based on the
--     Library" means either the Library or any derivative work under
--     copyright law: that is to say, a work containing the Library or a
--     portion of it, either verbatim or with modifications and/or
--     translated straightforwardly into another language.  (Hereinafter,
--     translation is included without limitation in the term
--     "modification".)
--
--     "Source code" for a work means the preferred form of the work for
--     making modifications to it.  For a library, complete source code
--     means all the source code for all modules it contains, plus any
--     associated interface definition files, plus the scripts used to
--     control compilation and installation of the library.
--
--     Activities other than copying, distribution and modification are
--     not covered by this License; they are outside its scope.  The act
--     of running a program using the Library is not restricted, and
--     output from such a program is covered only if its contents
--     constitute a work based on the Library (independent of the use of
--     the Library in a tool for writing it).  Whether that is true
--     depends on what the Library does and what the program that uses
--     the Library does.
--
--  1. You may copy and distribute verbatim copies of the Library's
--     complete source code as you receive it, in any medium, provided
--     that you conspicuously and appropriately publish on each copy an
--     appropriate copyright notice and disclaimer of warranty; keep
--     intact all the notices that refer to this License and to the
--     absence of any warranty; and distribute a copy of this License
--     along with the Library.
--
--     You may charge a fee for the physical act of transferring a copy,
--     and you may at your option offer warranty protection in exchange
--     for a fee.
--
--  2. You may modify your copy or copies of the Library or any portion
--     of it, thus forming a work based on the Library, and copy and
--     distribute such modifications or work under the terms of Section 1
--     above, provided that you also meet all of these conditions:
--
--       a. The modified work must itself be a software library.
--
--       b. You must cause the files modified to carry prominent notices
--          stating that you changed the files and the date of any change.
--
--       c. You must cause the whole of the work to be licensed at no
--          charge to all third parties under the terms of this License.
--
--       d. If a facility in the modified Library refers to a function or
--          a table of data to be supplied by an application program that
--          uses the facility, other than as an argument passed when the
--          facility is invoked, then you must make a good faith effort
--          to ensure that, in the event an application does not supply
--          such function or table, the facility still operates, and
--          performs whatever part of its purpose remains meaningful.
--
--          (For example, a function in a library to compute square roots
--          has a purpose that is entirely well-defined independent of the
--          application.  Therefore, Subsection 2d requires that any
--          application-supplied function or table used by this function
--          must be optional: if the application does not supply it, the
--          square root function must still compute square roots.)
--
--     These requirements apply to the modified work as a whole.  If
--     identifiable sections of that work are not derived from the
--     Library, and can be reasonably considered independent and separate
--     works in themselves, then this License, and its terms, do not
--     apply to those sections when you distribute them as separate
--     works.  But when you distribute the same sections as part of a
--     whole which is a work based on the Library, the distribution of
--     the whole must be on the terms of this License, whose permissions
--     for other licensees extend to the entire whole, and thus to each
--     and every part regardless of who wrote it.
--
--     Thus, it is not the intent of this section to claim rights or
--     contest your rights to work written entirely by you; rather, the
--     intent is to exercise the right to control the distribution of
--     derivative or collective works based on the Library.
--
--     In addition, mere aggregation of another work not based on the
--     Library with the Library (or with a work based on the Library) on
--     a volume of a storage or distribution medium does not bring the
--     other work under the scope of this License.
--
--  3. You may opt to apply the terms of the ordinary GNU General Public
--     License instead of this License to a given copy of the Library.
--     To do this, you must alter all the notices that refer to this
--     License, so that they refer to the ordinary GNU General Public
--     License, version 2, instead of to this License.  (If a newer
--     version than version 2 of the ordinary GNU General Public License
--     has appeared, then you can specify that version instead if you
--     wish.)  Do not make any other change in these notices.
--
--     Once this change is made in a given copy, it is irreversible for
--     that copy, so the ordinary GNU General Public License applies to
--     all subsequent copies and derivative works made from that copy.
--
--     This option is useful when you wish to copy part of the code of
--     the Library into a program that is not a library.
--
--  4. You may copy and distribute the Library (or a portion or
--     derivative of it, under Section 2) in object code or executable
--     form under the terms of Sections 1 and 2 above provided that you
--     accompany it with the complete corresponding machine-readable
--     source code, which must be distributed under the terms of Sections
--     1 and 2 above on a medium customarily used for software
--     interchange.
--
--     If distribution of object code is made by offering access to copy
--     from a designated place, then offering equivalent access to copy
--     the source code from the same place satisfies the requirement to
--     distribute the source code, even though third parties are not
--     compelled to copy the source along with the object code.
--
--  5. A program that contains no derivative of any portion of the
--     Library, but is designed to work with the Library by being
--     compiled or linked with it, is called a "work that uses the
--     Library".  Such a work, in isolation, is not a derivative work of
--     the Library, and therefore falls outside the scope of this License.
--
--     However, linking a "work that uses the Library" with the Library
--     creates an executable that is a derivative of the Library (because
--     it contains portions of the Library), rather than a "work that
--     uses the library".  The executable is therefore covered by this
--     License.  Section 6 states terms for distribution of such
--     executables.
--
--     When a "work that uses the Library" uses material from a header
--     file that is part of the Library, the object code for the work may
--     be a derivative work of the Library even though the source code is
--     not.  Whether this is true is especially significant if the work
--     can be linked without the Library, or if the work is itself a
--     library.  The threshold for this to be true is not precisely
--     defined by law.
--
--     If such an object file uses only numerical parameters, data
--     structure layouts and accessors, and small macros and small inline
--     functions (ten lines or less in length), then the use of the object
--     file is unrestricted, regardless of whether it is legally a
--     derivative work.  (Executables containing this object code plus
--     portions of the Library will still fall under Section 6.)
--
--     Otherwise, if the work is a derivative of the Library, you may
--     distribute the object code for the work under the terms of Section
--     6.  Any executables containing that work also fall under Section 6,
--     whether or not they are linked directly with the Library itself.
--
--  6. As an exception to the Sections above, you may also compile or
--     link a "work that uses the Library" with the Library to produce a
--     work containing portions of the Library, and distribute that work
--     under terms of your choice, provided that the terms permit
--     modification of the work for the customer's own use and reverse
--     engineering for debugging such modifications.
--
--     You must give prominent notice with each copy of the work that the
--     Library is used in it and that the Library and its use are covered
--     by this License.  You must supply a copy of this License.  If the
--     work during execution displays copyright notices, you must include
--     the copyright notice for the Library among them, as well as a
--     reference directing the user to the copy of this License.  Also,
--     you must do one of these things:
--
--       a. Accompany the work with the complete corresponding
--          machine-readable source code for the Library including
--          whatever changes were used in the work (which must be
--          distributed under Sections 1 and 2 above); and, if the work
--          is an executable linked with the Library, with the complete
--          machine-readable "work that uses the Library", as object code
--          and/or source code, so that the user can modify the Library
--          and then relink to produce a modified executable containing
--          the modified Library.  (It is understood that the user who
--          changes the contents of definitions files in the Library will
--          not necessarily be able to recompile the application to use
--          the modified definitions.)
--
--       b. Accompany the work with a written offer, valid for at least
--          three years, to give the same user the materials specified in
--          Subsection 6a, above, for a charge no more than the cost of
--          performing this distribution.
--
--       c. If distribution of the work is made by offering access to copy
--          from a designated place, offer equivalent access to copy the
--          above specified materials from the same place.
--
--       d. Verify that the user has already received a copy of these
--          materials or that you have already sent this user a copy.
--
--     For an executable, the required form of the "work that uses the
--     Library" must include any data and utility programs needed for
--     reproducing the executable from it.  However, as a special
--     exception, the source code distributed need not include anything
--     that is normally distributed (in either source or binary form)
--     with the major components (compiler, kernel, and so on) of the
--     operating system on which the executable runs, unless that
--     component itself accompanies the executable.
--
--     It may happen that this requirement contradicts the license
--     restrictions of other proprietary libraries that do not normally
--     accompany the operating system.  Such a contradiction means you
--     cannot use both them and the Library together in an executable
--     that you distribute.
--
--  7. You may place library facilities that are a work based on the
--     Library side-by-side in a single library together with other
--     library facilities not covered by this License, and distribute
--     such a combined library, provided that the separate distribution
--     of the work based on the Library and of the other library
--     facilities is otherwise permitted, and provided that you do these
--     two things:
--
--       a. Accompany the combined library with a copy of the same work
--          based on the Library, uncombined with any other library
--          facilities.  This must be distributed under the terms of the
--          Sections above.
--
--       b. Give prominent notice with the combined library of the fact
--          that part of it is a work based on the Library, and explaining
--          where to find the accompanying uncombined form of the same
--          work.
--
--  8. You may not copy, modify, sublicense, link with, or distribute the
--     Library except as expressly provided under this License.  Any
--     attempt otherwise to copy, modify, sublicense, link with, or
--     distribute the Library is void, and will automatically terminate
--     your rights under this License.  However, parties who have
--     received copies, or rights, from you under this License will not
--     have their licenses terminated so long as such parties remain in
--     full compliance.
--
--  9. You are not required to accept this License, since you have not
--     signed it.  However, nothing else grants you permission to modify
--     or distribute the Library or its derivative works.  These actions
--     are prohibited by law if you do not accept this License.
--     Therefore, by modifying or distributing the Library (or any work
--     based on the Library), you indicate your acceptance of this
--     License to do so, and all its terms and conditions for copying,
--     distributing or modifying the Library or works based on it.
--
-- 10. Each time you redistribute the Library (or any work based on the
--     Library), the recipient automatically receives a license from the
--     original licensor to copy, distribute, link with or modify the
--     Library subject to these terms and conditions.  You may not impose
--     any further restrictions on the recipients' exercise of the rights
--     granted herein.  You are not responsible for enforcing compliance
--     by third parties to this License.
--
-- 11. If, as a consequence of a court judgment or allegation of patent
--     infringement or for any other reason (not limited to patent
--     issues), conditions are imposed on you (whether by court order,
--     agreement or otherwise) that contradict the conditions of this
--     License, they do not excuse you from the conditions of this
--     License.  If you cannot distribute so as to satisfy simultaneously
--     your obligations under this License and any other pertinent
--     obligations, then as a consequence you may not distribute the
--     Library at all.  For example, if a patent license would not permit
--     royalty-free redistribution of the Library by all those who
--     receive copies directly or indirectly through you, then the only
--     way you could satisfy both it and this License would be to refrain
--     entirely from distribution of the Library.
--
--     If any portion of this section is held invalid or unenforceable
--     under any particular circumstance, the balance of the section is
--     intended to apply, and the section as a whole is intended to apply
--     in other circumstances.
--
--     It is not the purpose of this section to induce you to infringe any
--     patents or other property right claims or to contest validity of
--     any such claims; this section has the sole purpose of protecting
--     the integrity of the free software distribution system which is
--     implemented by public license practices.  Many people have made
--     generous contributions to the wide range of software distributed
--     through that system in reliance on consistent application of that
--     system; it is up to the author/donor to decide if he or she is
--     willing to distribute software through any other system and a
--     licensee cannot impose that choice.
--
--     This section is intended to make thoroughly clear what is believed
--     to be a consequence of the rest of this License.
--
-- 12. If the distribution and/or use of the Library is restricted in
--     certain countries either by patents or by copyrighted interfaces,
--     the original copyright holder who places the Library under this
--     License may add an explicit geographical distribution limitation
--     excluding those countries, so that distribution is permitted only
--     in or among countries not thus excluded.  In such case, this
--     License incorporates the limitation as if written in the body of
--     this License.
--
-- 13. The Free Software Foundation may publish revised and/or new
--     versions of the Library General Public License from time to time.
--     Such new versions will be similar in spirit to the present version,
--     but may differ in detail to address new problems or concerns.
--
--     Each version is given a distinguishing version number.  If the
--     Library specifies a version number of this License which applies
--     to it and "any later version", you have the option of following
--     the terms and conditions either of that version or of any later
--     version published by the Free Software Foundation.  If the Library
--     does not specify a license version number, you may choose any
--     version ever published by the Free Software Foundation.
--
-- 14. If you wish to incorporate parts of the Library into other free
--     programs whose distribution conditions are incompatible with these,
--     write to the author to ask for permission.  For software which is
--     copyrighted by the Free Software Foundation, write to the Free
--     Software Foundation; we sometimes make exceptions for this.  Our
--     decision will be guided by the two goals of preserving the free
--     status of all derivatives of our free software and of promoting
--     the sharing and reuse of software generally.
--
--                                NO WARRANTY
--
-- 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
--     WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE
--     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
--     HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT
--     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
--     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
--     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
--     QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU.  SHOULD THE
--     LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
--     SERVICING, REPAIR OR CORRECTION.
--
-- 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
--     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
--     MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
--     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
--     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
--     INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF
--     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
--     OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY
--     OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
--     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
--
--                      END OF TERMS AND CONDITIONS
--
--How to Apply These Terms to Your New Libraries
--==============================================
--
--   If you develop a new library, and you want it to be of the greatest
--possible use to the public, we recommend making it free software that
--everyone can redistribute and change.  You can do so by permitting
--redistribution under these terms (or, alternatively, under the terms of
--the ordinary General Public License).
--
--   To apply these terms, attach the following notices to the library.
--It is safest to attach them to the start of each source file to most
--effectively convey the exclusion of warranty; and each file should have
--at least the "copyright" line and a pointer to where the full notice is
--found.
--
--     ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES.
--     Copyright (C) YEAR  NAME OF AUTHOR
--     
--     This library is free software; you can redistribute it and/or modify it
--     under the terms of the GNU Library General Public License as published
--     by the Free Software Foundation; either version 2 of the License, or (at
--     your option) any later version.
--     
--     This library is distributed in the hope that it will be useful, but
--     WITHOUT ANY WARRANTY; without even the implied warranty of
--     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
--     Library General Public License for more details.
--     
--     You should have received a copy of the GNU Library General Public
--     License along with this library; if not, write to the Free Software
--     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
--
--   Also add information on how to contact you by electronic and paper
--mail.
--
--   You should also get your employer (if you work as a programmer) or
--your school, if any, to sign a "copyright disclaimer" for the library,
--if necessary.  Here is a sample; alter the names:
--
--     Yoyodyne, Inc., hereby disclaims all copyright interest in the library
--     `Frob' (a library for tweaking knobs) written by James Random Hacker.
--     
--     SIGNATURE OF TY COON, 1 April 1990
--     Ty Coon, President of Vice
--
--   That's all there is to it!
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-31 
glibc-2.0.1/manual/libc.info-31
---- ../glibc-2.0.1/manual/libc.info-31 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-31    1970-01-01 01:00:00.000000000 +0100
-@@ -1,863 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Concept Index,  Next: Type Index,  Prev: Copying,  
Up: Top
--
--Concept Index
--*************
--
--* Menu:
--
--* /etc/nsswitch.conf:                    NSS Configuration File.
--* 4.N BSD Unix:                          Berkeley Unix.
--* _POSIX_OPTION_ORDER environment variable.: Standard Environment.
--* abort signal:                          Program Error Signals.
--* aborting a program:                    Aborting a Program.
--* absolute file name:                    File Name Resolution.
--* absolute value functions:              Absolute Value.
--* accepting connections:                 Accepting Connections.
--* access permission for a file:          Access Permission.
--* access, testing for:                   Testing File Access.
--* accessing directories:                 Accessing Directories.
--* address of socket:                     Socket Addresses.
--* alarm signal:                          Alarm Signals.
--* alarms, setting:                       Setting an Alarm.
--* alignment (in obstacks):               Obstacks Data Alignment.
--* alignment (with malloc):               Aligned Memory Blocks.
--* alloca disadvantages:                  Disadvantages of Alloca.
--* alloca function:                       Variable Size Automatic.
--* allocation (obstacks):                 Allocation in an Obstack.
--* allocation hooks, for malloc:          Hooks for Malloc.
--* allocation of memory with malloc:      Basic Allocation.
--* allocation size of string:             Representation of Strings.
--* allocation statistics:                 Statistics of Malloc.
--* alphabetic character:                  Classification of Characters.
--* alphanumeric character:                Classification of Characters.
--* append-access files:                   File Position.
--* argc (program argument count):         Program Arguments.
--* argument promotion:                    Calling Variadics.
--* arguments (variadic functions):        Receiving Arguments.
--* arguments, how many:                   How Many Arguments.
--* arguments, to program:                 Program Arguments.
--* argv (program argument vector):        Program Arguments.
--* arithmetic expansion:                  Expansion Stages.
--* array comparison functions:            String/Array Comparison.
--* array copy functions:                  Copying and Concatenation.
--* array search function:                 Array Search Function.
--* array sort function:                   Array Sort Function.
--* ASCII character:                       Classification of Characters.
--* assertions:                            Consistency Checking.
--* attributes of a file:                  Attribute Meanings.
--* automatic allocation:                  Memory Concepts.
--* automatic freeing:                     Variable Size Automatic.
--* automatic storage with variable size:  Variable Size Automatic.
--* background job:                        Concepts of Job Control.
--* background job, launching:             Foreground and Background.
--* base (of floating point number):       Floating Point Concepts.
--* basic byte sequence:                   Multibyte Char Intro.
--* baud rate:                             Line Speed.
--* Berkeley Unix:                         Berkeley Unix.
--* bias (of floating point number exponent): Floating Point Concepts.
--* big-endian:                            Byte Order.
--* binary I/O to a stream:                Block Input/Output.
--* binary search function (for arrays):   Array Search Function.
--* binary stream:                         Binary Streams.
--* binding a socket address:              Socket Addresses.
--* blank character:                       Classification of Characters.
--* block I/O to a stream:                 Block Input/Output.
--* blocked signals:                       Delivery of Signal.
--* blocked signals, checking for:         Checking for Pending Signals.
--* blocking signals:                      Blocking Signals.
--* blocking signals, in a handler:        Blocking for Handler.
--* bootstrapping, and services:           Actions in the NSS configuration.
--* break condition, detecting:            Input Modes.
--* break condition, generating:           Line Control.
--* breaking a string into tokens:         Finding Tokens in a String.
--* broken pipe signal:                    Operation Error Signals.
--* broken-down time <1>:                  Broken-down Time.
--* broken-down time:                      Calendar Time.
--* BSD compatibility library:             Process Group Functions.
--* BSD compatibility library.:            Feature Test Macros.
--* BSD Unix:                              Berkeley Unix.
--* buffering of streams:                  Stream Buffering.
--* buffering, controlling:                Controlling Buffering.
--* bugs, reporting:                       Reporting Bugs.
--* bus error:                             Program Error Signals.
--* byte order conversion, for socket:     Byte Order.
--* byte stream:                           Socket Concepts.
--* calendar time:                         Calendar Time.
--* calendar time and broken-down time:    Broken-down Time.
--* calling variadic functions:            Calling Variadics.
--* canonical input processing:            Canonical or Not.
--* capacity limits, POSIX:                General Limits.
--* carrier detect:                        Control Modes.
--* case conversion of characters:         Case Conversion.
--* catching signals:                      Delivery of Signal.
--* categories for locales:                Locale Categories.
--* change working directory:              Working Directory.
--* changing the locale:                   Setting the Locale.
--* changing the size of a block (malloc): Changing Block Size.
--* changing the size of a block (obstacks): Growing Objects.
--* channels:                              Stream/Descriptor Precautions.
--* character case conversion:             Case Conversion.
--* character code:                        Wide Char Intro.
--* character predicates:                  Classification of Characters.
--* character testing:                     Classification of Characters.
--* checking for pending signals:          Checking for Pending Signals.
--* child process <1>:                     Process Creation Concepts.
--* child process:                         Processes.
--* child process signal:                  Job Control Signals.
--* chunks:                                Obstack Chunks.
--* classification of characters:          Classification of Characters.
--* cleaning up a stream:                  Linked Channels.
--* clearing terminal input queue:         Line Control.
--* client:                                Connections.
--* clock ticks:                           Processor Time.
--* close-on-exec (file descriptor flag):  Descriptor Flags.
--* closing a file descriptor:             Opening and Closing Files.
--* closing a socket:                      Closing a Socket.
--* closing a stream:                      Closing Streams.
--* code, character:                       Wide Char Intro.
--* collating strings:                     Collation Functions.
--* combining locales:                     Choosing Locale.
--* command argument syntax:               Argument Syntax.
--* command arguments, parsing:            Parsing Options.
--* command line arguments:                Program Arguments.
--* command substitution:                  Expansion Stages.
--* communication style (of a socket):     Socket Concepts.
--* comparing strings and arrays:          String/Array Comparison.
--* Comparison Function:                   Comparison Functions.
--* concatenating strings:                 Copying and Concatenation.
--* configurations, all supported:         Supported Configurations.
--* connecting a socket:                   Connecting.
--* connection:                            Connections.
--* consistency checking:                  Consistency Checking.
--* consistency checking, of heap:         Heap Consistency Checking.
--* continue signal:                       Job Control Signals.
--* control character:                     Classification of Characters.
--* control operations on files:           Control Operations.
--* controlling process:                   Controlling Terminal.
--* controlling terminal:                  Concepts of Job Control.
--* controlling terminal, access to:       Access to the Terminal.
--* controlling terminal, determining:     Identifying the Terminal.
--* controlling terminal, setting:         Open-time Flags.
--* conversion specifications (printf):    Formatted Output Basics.
--* conversion specifications (scanf):     Formatted Input Basics.
--* converting byte order:                 Byte Order.
--* converting case of characters:         Case Conversion.
--* converting extended characters:        Converting One Char.
--* converting extended strings:           Wide String Conversion.
--* converting file descriptor to stream:  Descriptors and Streams.
--* converting floats to integers:         Rounding and Remainders.
--* converting group ID to group name:     Lookup Group.
--* converting group name to group ID:     Lookup Group.
--* converting host address to name:       Host Names.
--* converting host name to address:       Host Names.
--* converting network name to network number: Networks Database.
--* converting network number to network name: Networks Database.
--* converting port number to service name: Services Database.
--* converting service name to port number: Services Database.
--* converting string to collation order:  Collation Functions.
--* converting strings to numbers:         Parsing of Numbers.
--* converting user ID to user name:       Lookup User.
--* converting user name to user ID:       Lookup User.
--* cookie, for custom stream:             Streams and Cookies.
--* copying strings and arrays:            Copying and Concatenation.
--* CPU time:                              Processor Time.
--* create on open (file status flag):     Open-time Flags.
--* creating a directory:                  Creating Directories.
--* creating a FIFO special file:          FIFO Special Files.
--* creating a pipe:                       Creating a Pipe.
--* creating a pipe to a subprocess:       Pipe to a Subprocess.
--* creating a process:                    Process Creation Concepts.
--* creating a socket:                     Creating a Socket.
--* creating a socket pair:                Socket Pairs.
--* creating special files:                Making Special Files.
--* cube root function:                    Exponents and Logarithms.
--* currency symbols:                      Currency Symbol.
--* current working directory:             Working Directory.
--* custom streams:                        Custom Streams.
--* customizing printf:                    Customizing Printf.
--* data loss on sockets:                  Socket Concepts.
--* databases:                             Name Service Switch.
--* datagram socket:                       Datagrams.
--* datagrams, transmitting:               Sending Datagrams.
--* date and time:                         Calendar Time.
--* Daylight Saving Time:                  Broken-down Time.
--* decimal digit character:               Classification of Characters.
--* decimal-point separator:               General Numeric.
--* declaration (compared to definition):  Header Files.
--* declaring variadic functions:          Calling Variadics.
--* default action (for a signal):         Delivery of Signal.
--* default action for a signal:           Basic Signal Handling.
--* default argument promotions:           Calling Variadics.
--* default value, and NSS:                Notes on NSS Configuration File.
--* defining new printf conversions:       Customizing Printf.
--* definition (compared to declaration):  Header Files.
--* delayed suspend character:             Signal Characters.
--* deleting a directory:                  Deleting Files.
--* deleting a file:                       Deleting Files.
--* delivery of signals:                   Delivery of Signal.
--* descriptors and streams:               Stream/Descriptor Precautions.
--* digit character:                       Classification of Characters.
--* directories, accessing:                Accessing Directories.
--* directories, creating:                 Creating Directories.
--* directories, deleting:                 Deleting Files.
--* directory:                             Directories.
--* directory entry:                       Directories.
--* directory stream:                      Accessing Directories.
--* disadvantages of alloca:               Disadvantages of Alloca.
--* DISCARD character:                     Other Special.
--* DNS server unavailable:                Actions in the NSS configuration.
--* domain (of socket):                    Socket Concepts.
--* domain error:                          Domain and Range Errors.
--* dot notation, for Internet addresses:  Abstract Host Addresses.
--* DSUSP character:                       Signal Characters.
--* duplicating file descriptors:          Duplicating Descriptors.
--* dynamic allocation:                    Memory Concepts.
--* echo of terminal input:                Local Modes.
--* effective group ID:                    Process Persona.
--* effective user ID:                     Process Persona.
--* efficiency and malloc:                 Efficiency and Malloc.
--* efficiency and obstacks:               Extra Fast Growing.
--* efficiency of chunks:                  Obstack Chunks.
--* EINTR, and restarting interrupted primitives: Interrupted Primitives.
--* end of file, on a stream:              EOF and Errors.
--* end-of-file, on a file descriptor:     I/O Primitives.
--* environment:                           Environment Variables.
--* environment access:                    Environment Access.
--* environment representation:            Environment Access.
--* environment variable:                  Environment Variables.
--* EOF character:                         Editing Characters.
--* EOL character:                         Editing Characters.
--* EOL2 character:                        Editing Characters.
--* epoch:                                 Simple Calendar Time.
--* ERASE character:                       Editing Characters.
--* error codes:                           Error Reporting.
--* error reporting:                       Error Reporting.
--* establishing a handler:                Signal Actions.
--* ethers:                                NSS Basics.
--* exception:                             Program Error Signals.
--* exclusive lock:                        File Locks.
--* exec functions:                        Executing a File.
--* executing a file:                      Executing a File.
--* exit status:                           Exit Status.
--* exit status value:                     Program Termination.
--* expansion of shell words:              Word Expansion.
--* exponent (of floating point number):   Floating Point Concepts.
--* exponentiation functions:              Exponents and Logarithms.
--* extended character sets:               Extended Characters.
--* extended characters, converting:       Converting One Char.
--* extended strings, converting representations: Wide String Conversion.
--* extending printf:                      Customizing Printf.
--* extracting file descriptor from stream: Descriptors and Streams.
--* fcntl function:                        Control Operations.
--* feature test macros:                   Feature Test Macros.
--* field splitting:                       Expansion Stages.
--* FIFO special file:                     Pipes and FIFOs.
--* file access permission:                Access Permission.
--* file access time:                      File Times.
--* file attribute modification time:      File Times.
--* file attributes:                       Attribute Meanings.
--* file creation mask:                    Setting Permissions.
--* file descriptor flags:                 Descriptor Flags.
--* file descriptor sets, for select:      Waiting for I/O.
--* file descriptors, standard:            Descriptors and Streams.
--* file locks:                            File Locks.
--* file modification time:                File Times.
--* file name:                             File Names.
--* file name component:                   Directories.
--* file name errors:                      File Name Errors.
--* file name resolution:                  File Name Resolution.
--* file name translation flags:           Open-time Flags.
--* file names, multiple:                  Hard Links.
--* file namespace, for sockets:           File Namespace.
--* file owner:                            File Owner.
--* file permission bits:                  Permission Bits.
--* file pointer:                          Streams.
--* file position:                         File Position.
--* file positioning on a file descriptor: File Position Primitive.
--* file positioning on a stream:          File Positioning.
--* file status flags:                     File Status Flags.
--* filtering i/o through subprocess:      Pipe to a Subprocess.
--* flag character (printf):               Output Conversion Syntax.
--* flag character (scanf):                Input Conversion Syntax.
--* flags for sigaction:                   Flags for Sigaction.
--* flags, file name translation:          Open-time Flags.
--* flags, open-time action:               Open-time Flags.
--* floating point, IEEE:                  IEEE Floating Point.
--* floating type measurements:            Floating Type Macros.
--* floating-point exception:              Program Error Signals.
--* flow control, terminal:                Line Control.
--* flushing a stream:                     Flushing Buffers.
--* flushing terminal output queue:        Line Control.
--* foreground job:                        Concepts of Job Control.
--* foreground job, launching:             Foreground and Background.
--* forking a process:                     Process Creation Concepts.
--* format string, for printf:             Formatted Output.
--* format string, for scanf:              Formatted Input.
--* formatted input from a stream:         Formatted Input.
--* formatted output to a stream:          Formatted Output.
--* freeing (obstacks):                    Freeing Obstack Objects.
--* freeing memory allocated with malloc:  Freeing after Malloc.
--* fully buffered stream:                 Buffering Concepts.
--* function prototypes (variadic):        Variadic Prototypes.
--* generation of signals:                 Signal Generation.
--* globbing:                              Globbing.
--* graphic character:                     Classification of Characters.
--* Gregorian calendar:                    Calendar Time.
--* group:                                 NSS Basics.
--* group database:                        Group Database.
--* group ID:                              User and Group IDs.
--* group name:                            User and Group IDs.
--* group owner of a file:                 File Owner.
--* grouping of digits:                    General Numeric.
--* growing objects (in obstacks):         Growing Objects.
--* handle:                                Relocator Concepts.
--* handling multiple signals:             Merged Signals.
--* hangup signal:                         Termination Signals.
--* hard limit:                            Limits on Resources.
--* hard link:                             Hard Links.
--* header files:                          Header Files.
--* heap consistency checking:             Heap Consistency Checking.
--* heap, dynamic allocation from:         Unconstrained Allocation.
--* heap, freeing memory from:             Freeing after Malloc.
--* hexadecimal digit character:           Classification of Characters.
--* hidden bit (of floating point number mantissa): Floating Point Concepts.
--* high-priority data:                    Out-of-Band Data.
--* high-resolution time:                  Calendar Time.
--* holes in files:                        File Position Primitive.
--* home directory:                        Standard Environment.
--* HOME environment variable:             Standard Environment.
--* hook functions (of custom streams):    Hook Functions.
--* host address, Internet:                Abstract Host Addresses.
--* hosts:                                 NSS Basics.
--* hosts database:                        Host Names.
--* how many arguments:                    How Many Arguments.
--* hyperbolic functions:                  Hyperbolic Functions.
--* identifying terminals:                 Is It a Terminal.
--* IEEE floating point:                   Not a Number.
--* IEEE floating point representation:    IEEE Floating Point.
--* IEEE Std 1003.1:                       POSIX.
--* IEEE Std 1003.2:                       POSIX.
--* ignore action for a signal:            Basic Signal Handling.
--* illegal instruction:                   Program Error Signals.
--* impossible events:                     Consistency Checking.
--* independent channels:                  Independent Channels.
--* initial signal actions:                Initial Signal Actions.
--* inode number:                          Attribute Meanings.
--* input available signal:                Asynchronous I/O Signals.
--* input conversions, for scanf:          Table of Input Conversions.
--* input from multiple files:             Waiting for I/O.
--* installation tools:                    Tools for Installation.
--* installing the library:                Installation.
--* integer division functions:            Integer Division.
--* integer type range:                    Range of Type.
--* integer type width:                    Width of Type.
--* interactive signals, from terminal:    Local Modes.
--* interactive stop signal:               Job Control Signals.
--* internationalization:                  Locales.
--* Internet host address:                 Abstract Host Addresses.
--* Internet namespace, for sockets:       Internet Namespace.
--* interprocess communication, with FIFO: FIFO Special Files.
--* interprocess communication, with pipes: Creating a Pipe.
--* interprocess communication, with signals: Kill Example.
--* interprocess communication, with sockets: Sockets.
--* interrupt character:                   Signal Characters.
--* interrupt signal:                      Termination Signals.
--* interrupt-driven input:                Interrupt Input.
--* interrupting primitives:               Interrupted Primitives.
--* interval timer, setting:               Setting an Alarm.
--* INTR character:                        Signal Characters.
--* inverse hyperbolic functions:          Hyperbolic Functions.
--* inverse trigonometric functions:       Inverse Trig Functions.
--* invocation of program:                 Program Arguments.
--* ISO C:                                 ISO C.
--* job:                                   Job Control.
--* job control:                           Job Control.
--* job control functions:                 Functions for Job Control.
--* job control is optional:               Job Control is Optional.
--* job control signals:                   Job Control Signals.
--* job control, enabling:                 Initializing the Shell.
--* Kermit the frog:                       Search/Sort Example.
--* KILL character:                        Editing Characters.
--* kill signal:                           Termination Signals.
--* killing a process:                     Signaling Another Process.
--* LANG environment variable:             Standard Environment.
--* launching jobs:                        Launching Jobs.
--* LC_COLLATE environment variable:       Standard Environment.
--* LC_CTYPE environment variable:         Standard Environment.
--* LC_MONETARY environment variable:      Standard Environment.
--* LC_NUMERIC environment variable:       Standard Environment.
--* LC_TIME environment variable:          Standard Environment.
--* leap second:                           Broken-down Time.
--* length of multibyte character:         Length of Char.
--* length of string:                      Representation of Strings.
--* level, for socket options:             Socket Options.
--* library:                               Introduction.
--* limits on resource usage:              Limits on Resources.
--* limits, file name length:              Limits for Files.
--* limits, floating types:                Floating Type Macros.
--* limits, integer types:                 Range of Type.
--* limits, link count of files:           Limits for Files.
--* limits, number of open files:          General Limits.
--* limits, number of processes:           General Limits.
--* limits, number of supplementary group IDs: General Limits.
--* limits, pipe buffer size:              Limits for Files.
--* limits, POSIX:                         General Limits.
--* limits, program argument size:         General Limits.
--* limits, terminal input queue:          Limits for Files.
--* limits, time zone name length:         General Limits.
--* line buffered stream:                  Buffering Concepts.
--* line speed:                            Line Speed.
--* lines (in a text file):                Binary Streams.
--* link:                                  Directories.
--* link, hard:                            Hard Links.
--* link, soft:                            Symbolic Links.
--* link, symbolic:                        Symbolic Links.
--* linked channels:                       Linked Channels.
--* listening (sockets):                   Listening.
--* little-endian:                         Byte Order.
--* LNEXT character:                       Other Special.
--* local network address number:          Abstract Host Addresses.
--* local time:                            Calendar Time.
--* locale categories:                     Locale Categories.
--* locale, changing:                      Setting the Locale.
--* locales:                               Locales.
--* logarithm functions:                   Exponents and Logarithms.
--* login name:                            User and Group IDs.
--* login name, determining:               Who Logged In.
--* LOGNAME environment variable:          Standard Environment.
--* long jumps:                            Non-Local Exits.
--* long-named options:                    Argument Syntax.
--* longjmp:                               Advantages of Alloca.
--* loss of data on sockets:               Socket Concepts.
--* lost resource signal:                  Operation Error Signals.
--* lower-case character:                  Classification of Characters.
--* macros:                                Obstack Functions.
--* main function:                         Program Arguments.
--* malloc function:                       Unconstrained Allocation.
--* mantissa (of floating point number):   Floating Point Concepts.
--* matching failure, in scanf:            Formatted Input Basics.
--* maximum field width (scanf):           Input Conversion Syntax.
--* measurements of floating types:        Floating Type Macros.
--* memory allocation:                     Memory Allocation.
--* memory usage warnings:                 Memory Warnings.
--* merging of signals:                    Merged Signals.
--* MIN termios slot:                      Noncanonical Input.
--* minimum field width (printf):          Output Conversion Syntax.
--* mixing descriptors and streams:        Stream/Descriptor Precautions.
--* modem disconnect:                      Control Modes.
--* modem status lines:                    Control Modes.
--* monetary value formatting:             Numeric Formatting.
--* multibyte character, length of:        Length of Char.
--* multibyte characters:                  Multibyte Char Intro.
--* multiple names for one file:           Hard Links.
--* multiplexing input:                    Waiting for I/O.
--* name of running program:               Error Messages.
--* name of socket:                        Socket Addresses.
--* Name Service Switch:                   Name Service Switch.
--* name space:                            Reserved Names.
--* names of signals:                      Standard Signals.
--* namespace (of socket):                 Socket Concepts.
--* NaN:                                   Not a Number.
--* Netgroup:                              Netgroup Data.
--* netgroup:                              NSS Basics.
--* network:                               NSS Basics.
--* network byte order:                    Byte Order.
--* network number:                        Abstract Host Addresses.
--* network protocol:                      Socket Concepts.
--* networks database:                     Networks Database.
--* nisplus, and booting:                  Actions in the NSS configuration.
--* nisplus, and completeness:             Actions in the NSS configuration.
--* non-blocking open:                     Open-time Flags.
--* non-local exit, from signal handler:   Longjmp in Handler.
--* non-local exits:                       Non-Local Exits.
--* noncanonical input processing:         Canonical or Not.
--* normalization functions (floating-point): Normalization Functions.
--* normalized floating point number:      Floating Point Concepts.
--* not a number:                          Not a Number.
--* NSS:                                   Name Service Switch.
--* nsswitch.conf:                         NSS Configuration File.
--* null character:                        Representation of Strings.
--* null pointer constant:                 Null Pointer Constant.
--* number of arguments passed:            How Many Arguments.
--* number syntax, parsing:                Parsing of Numbers.
--* numeric value formatting:              Numeric Formatting.
--* obstack status:                        Status of an Obstack.
--* obstacks:                              Obstacks.
--* open-time action flags:                Open-time Flags.
--* opening a file:                        I/O Concepts.
--* opening a file descriptor:             Opening and Closing Files.
--* opening a pipe:                        Creating a Pipe.
--* opening a socket:                      Creating a Socket.
--* opening a socket pair:                 Socket Pairs.
--* opening a stream:                      Opening Streams.
--* optimizing NSS:                        Notes on NSS Configuration File.
--* optional arguments:                    Variadic Functions.
--* optional POSIX features:               System Options.
--* orphaned process group:                Orphaned Process Groups.
--* out-of-band data:                      Out-of-Band Data.
--* output conversions, for printf:        Table of Output Conversions.
--* output possible signal:                Asynchronous I/O Signals.
--* owner of a file:                       File Owner.
--* packet:                                Socket Concepts.
--* page boundary:                         Aligned Memory Blocks.
--* parent directory:                      File Name Resolution.
--* parent process <1>:                    Process Creation Concepts.
--* parent process:                        Processes.
--* parity checking:                       Input Modes.
--* parsing a template string:             Parsing a Template String.
--* parsing numbers (in formatted input):  Parsing of Numbers.
--* parsing program arguments:             Parsing Options.
--* parsing tokens from a string:          Finding Tokens in a String.
--* passwd:                                NSS Basics.
--* password database:                     User Database.
--* PATH environment variable:             Standard Environment.
--* pause function:                        Waiting for a Signal.
--* peeking at input:                      Unreading.
--* pending signals:                       Delivery of Signal.
--* pending signals, checking for:         Checking for Pending Signals.
--* permission to access a file:           Access Permission.
--* persona:                               Process Persona.
--* pi (trigonometric constant):           Trig Functions.
--* pipe:                                  Pipes and FIFOs.
--* pipe signal:                           Operation Error Signals.
--* pipe to a subprocess:                  Pipe to a Subprocess.
--* port number:                           Ports.
--* positioning a file descriptor:         File Position Primitive.
--* positioning a stream:                  File Positioning.
--* POSIX:                                 POSIX.
--* POSIX capacity limits:                 General Limits.
--* POSIX optional features:               System Options.
--* POSIX.1:                               POSIX.
--* POSIX.2:                               POSIX.
--* power functions:                       Exponents and Logarithms.
--* precision (of floating point number):  Floating Point Concepts.
--* precision (printf):                    Output Conversion Syntax.
--* predicates on arrays:                  String/Array Comparison.
--* predicates on characters:              Classification of Characters.
--* predicates on strings:                 String/Array Comparison.
--* primitives, interrupting:              Interrupted Primitives.
--* printing character:                    Classification of Characters.
--* priority of a process:                 Priority.
--* process <1>:                           Processes.
--* process:                               Process Startup.
--* process completion:                    Process Completion.
--* process group functions:               Functions for Job Control.
--* process group ID:                      Launching Jobs.
--* process group leader:                  Launching Jobs.
--* process groups:                        Job Control.
--* process ID:                            Process Creation Concepts.
--* process image:                         Process Creation Concepts.
--* process lifetime:                      Process Creation Concepts.
--* process priority:                      Priority.
--* process signal mask:                   Process Signal Mask.
--* process termination:                   Program Termination.
--* processor time:                        Processor Time.
--* profiling alarm signal:                Alarm Signals.
--* profiling timer:                       Setting an Alarm.
--* program argument syntax:               Argument Syntax.
--* program arguments:                     Program Arguments.
--* program arguments, parsing:            Parsing Options.
--* program error signals:                 Program Error Signals.
--* program name:                          Error Messages.
--* program startup:                       Program Arguments.
--* program termination:                   Program Termination.
--* program termination signals:           Termination Signals.
--* programming your own streams:          Custom Streams.
--* protocol (of socket):                  Socket Concepts.
--* protocol family:                       Socket Concepts.
--* protocols:                             NSS Basics.
--* protocols database:                    Protocols Database.
--* prototypes for variadic functions:     Variadic Prototypes.
--* pseudo-random numbers:                 Pseudo-Random Numbers.
--* punctuation character:                 Classification of Characters.
--* pushing input back:                    Unreading.
--* quick sort function (for arrays):      Array Sort Function.
--* QUIT character:                        Signal Characters.
--* quit signal:                           Termination Signals.
--* quote removal:                         Expansion Stages.
--* race conditions, relating to job control: Launching Jobs.
--* race conditions, relating to signals:  Signals in Handler.
--* radix (of floating point number):      Floating Point Concepts.
--* raising signals:                       Generating Signals.
--* random numbers:                        Pseudo-Random Numbers.
--* random-access files:                   File Position.
--* range error:                           Domain and Range Errors.
--* range of integer type:                 Range of Type.
--* read lock:                             File Locks.
--* reading from a directory:              Accessing Directories.
--* reading from a file descriptor:        I/O Primitives.
--* reading from a socket:                 Transferring Data.
--* reading from a stream, by blocks:      Block Input/Output.
--* reading from a stream, by characters:  Character Input.
--* reading from a stream, formatted:      Formatted Input.
--* real group ID:                         Process Persona.
--* real user ID:                          Process Persona.
--* real-time timer:                       Setting an Alarm.
--* receiving datagrams:                   Receiving Datagrams.
--* record locking:                        File Locks.
--* redirecting input and output:          Duplicating Descriptors.
--* reentrant functions:                   Nonreentrancy.
--* reentrant NSS functions:               NSS Module Names.
--* relative file name:                    File Name Resolution.
--* relocating memory allocator:           Relocating Allocator.
--* remainder functions:                   Rounding and Remainders.
--* removal of quotes:                     Expansion Stages.
--* removing a file:                       Deleting Files.
--* removing macros that shadow functions: Macro Definitions.
--* renaming a file:                       Renaming Files.
--* reporting bugs:                        Reporting Bugs.
--* reporting errors:                      Error Reporting.
--* REPRINT character:                     Editing Characters.
--* reserved names:                        Reserved Names.
--* resource limits:                       Limits on Resources.
--* restarting interrupted primitives:     Interrupted Primitives.
--* restrictions on signal handler functions: Nonreentrancy.
--* root directory:                        File Name Resolution.
--* rounding functions:                    Rounding and Remainders.
--* rpc:                                   NSS Basics.
--* running a command:                     Running a Command.
--* scanning the group list:               Scanning All Groups.
--* scanning the user list:                Scanning All Users.
--* search function (for arrays):          Array Search Function.
--* search functions (for strings):        Search Functions.
--* seed (for random numbers):             Pseudo-Random Numbers.
--* seeking on a file descriptor:          File Position Primitive.
--* seeking on a stream:                   File Positioning.
--* segmentation violation:                Program Error Signals.
--* sending a datagram:                    Sending Datagrams.
--* sending signals:                       Generating Signals.
--* sequential-access files:               File Position.
--* server:                                Connections.
--* services:                              NSS Basics.
--* services database:                     Services Database.
--* session <1>:                           Concepts of Job Control.
--* session:                               Job Control.
--* session leader:                        Concepts of Job Control.
--* setting an alarm:                      Setting an Alarm.
--* setuid programs:                       How Change Persona.
--* setuid programs and file access:       Testing File Access.
--* shadow:                                NSS Basics.
--* shadowing functions with macros:       Macro Definitions.
--* shared lock:                           File Locks.
--* shell:                                 Concepts of Job Control.
--* shrinking objects:                     Growing Objects.
--* shutting down a socket:                Closing a Socket.
--* sigaction flags:                       Flags for Sigaction.
--* sigaction function:                    Advanced Signal Handling.
--* SIGCHLD, handling of:                  Stopped and Terminated Jobs.
--* sign (of floating point number):       Floating Point Concepts.
--* signal:                                Signal Handling.
--* signal action:                         Delivery of Signal.
--* signal actions:                        Signal Actions.
--* signal flags:                          Flags for Sigaction.
--* signal function:                       Basic Signal Handling.
--* signal handler function:               Defining Handlers.
--* signal mask:                           Process Signal Mask.
--* signal messages:                       Signal Messages.
--* signal names:                          Standard Signals.
--* signal number:                         Standard Signals.
--* signal set:                            Signal Sets.
--* signals, generating:                   Generating Signals.
--* significand (of floating point number): Floating Point Concepts.
--* SIGTTIN, from background job:          Access to the Terminal.
--* SIGTTOU, from background job:          Access to the Terminal.
--* size of string:                        Representation of Strings.
--* socket:                                Sockets.
--* socket address (name) binding:         Socket Addresses.
--* socket domain:                         Socket Concepts.
--* socket namespace:                      Socket Concepts.
--* socket option level:                   Socket Options.
--* socket options:                        Socket Options.
--* socket pair:                           Socket Pairs.
--* socket protocol:                       Socket Concepts.
--* socket shutdown:                       Closing a Socket.
--* socket, client actions:                Connecting.
--* socket, closing:                       Closing a Socket.
--* socket, connecting:                    Connecting.
--* socket, creating:                      Creating a Socket.
--* socket, initiating a connection:       Connecting.
--* sockets, accepting connections:        Accepting Connections.
--* sockets, listening:                    Listening.
--* sockets, server actions:               Listening.
--* soft limit:                            Limits on Resources.
--* soft link:                             Symbolic Links.
--* sort function (for arrays):            Array Sort Function.
--* sparse files:                          File Position Primitive.
--* special files:                         Making Special Files.
--* specified action (for a signal):       Delivery of Signal.
--* square root function:                  Exponents and Logarithms.
--* stable sorting:                        Array Sort Function.
--* standard dot notation, for Internet addresses: Abstract Host Addresses.
--* standard environment variables:        Standard Environment.
--* standard error file descriptor:        Descriptors and Streams.
--* standard error stream:                 Standard Streams.
--* standard file descriptors:             Descriptors and Streams.
--* standard input file descriptor:        Descriptors and Streams.
--* standard input stream:                 Standard Streams.
--* standard output file descriptor:       Descriptors and Streams.
--* standard output stream:                Standard Streams.
--* standard streams:                      Standard Streams.
--* standards:                             Standards and Portability.
--* START character:                       Start/Stop Characters.
--* startup of program:                    Program Arguments.
--* static allocation:                     Memory Concepts.
--* STATUS character:                      Other Special.
--* status codes:                          Error Reporting.
--* status of a file:                      Attribute Meanings.
--* status of obstack:                     Status of an Obstack.
--* sticky bit:                            Permission Bits.
--* STOP character:                        Start/Stop Characters.
--* stop signal:                           Job Control Signals.
--* stopped job:                           Concepts of Job Control.
--* stopped jobs, continuing:              Continuing Stopped Jobs.
--* stopped jobs, detecting:               Stopped and Terminated Jobs.
--* storage allocation:                    Memory Allocation.
--* stream (sockets):                      Socket Concepts.
--* stream, for I/O to a string:           String Streams.
--* streams and descriptors:               Stream/Descriptor Precautions.
--* streams, and file descriptors:         Descriptors and Streams.
--* streams, standard:                     Standard Streams.
--* string:                                Representation of Strings.
--* string allocation:                     Representation of Strings.
--* string collation functions:            Collation Functions.
--* string comparison functions:           String/Array Comparison.
--* string concatenation functions:        Copying and Concatenation.
--* string copy functions:                 Copying and Concatenation.
--* string length:                         Representation of Strings.
--* string literal:                        Representation of Strings.
--* string search functions:               Search Functions.
--* string stream:                         String Streams.
--* string, representation of:             Representation of Strings.
--* style of communication (of a socket):  Socket Concepts.
--* subshell:                              Initializing the Shell.
--* substitution of variables and commands: Expansion Stages.
--* successive signals:                    Merged Signals.
--* summer time:                           Broken-down Time.
--* SunOS:                                 Berkeley Unix.
--* supplementary group IDs:               Process Persona.
--* SUSP character:                        Signal Characters.
--* suspend character:                     Signal Characters.
--* SVID:                                  SVID.
--* symbolic link:                         Symbolic Links.
--* symbolic link, opening:                Open-time Flags.
--* syntax, for program arguments:         Argument Syntax.
--* syntax, for reading numbers:           Parsing of Numbers.
--* System V Unix:                         SVID.
--* TCP (Internet protocol):               Protocols Database.
--* template, for printf:                  Formatted Output.
--* template, for scanf:                   Formatted Input.
--* TERM environment variable:             Standard Environment.
--* terminal flow control:                 Line Control.
--* terminal identification:               Is It a Terminal.
--* terminal input queue:                  I/O Queues.
--* terminal input queue, clearing:        Line Control.
--* terminal input signal:                 Job Control Signals.
--* terminal line control functions:       Line Control.
--* terminal line speed:                   Line Speed.
--* terminal mode data types:              Mode Data Types.
--* terminal mode functions:               Mode Functions.
--* terminal output queue:                 I/O Queues.
--* terminal output queue, flushing:       Line Control.
--* terminal output signal:                Job Control Signals.
--* terminated jobs, detecting:            Stopped and Terminated Jobs.
--* termination signal:                    Termination Signals.
--* testing access permission:             Testing File Access.
--* testing exit status of child process:  Process Completion.
--* text stream:                           Binary Streams.
--* ticks, clock:                          Processor Time.
--* tilde expansion:                       Expansion Stages.
--* TIME termios slot:                     Noncanonical Input.
--* time zone:                             TZ Variable.
--* time zone database:                    TZ Variable.
--* time, calendar:                        Calendar Time.
--* time, elapsed CPU:                     Processor Time.
--* timer, profiling:                      Setting an Alarm.
--* timer, real-time:                      Setting an Alarm.
--* timer, virtual:                        Setting an Alarm.
--* timers, setting:                       Setting an Alarm.
--* timing error in signal handling:       Remembering a Signal.
--* TMPDIR environment variable:           Temporary Files.
--* tokenizing strings:                    Finding Tokens in a String.
--* tools, for installing library:         Tools for Installation.
--* transmitting datagrams:                Sending Datagrams.
--* trigonometric functions:               Trig Functions.
--* type measurements, floating:           Floating Type Macros.
--* type measurements, integer:            Width of Type.
--* type modifier character (printf):      Output Conversion Syntax.
--* type modifier character (scanf):       Input Conversion Syntax.
--* typeahead buffer:                      I/O Queues.
--* TZ environment variable:               Standard Environment.
--* umask:                                 Setting Permissions.
--* unbuffered stream:                     Buffering Concepts.
--* unconstrained storage allocation:      Unconstrained Allocation.
--* undefining macros that shadow functions: Macro Definitions.
--* Unix, Berkeley:                        Berkeley Unix.
--* Unix, System V:                        SVID.
--* unlinking a file:                      Deleting Files.
--* unreading characters:                  Unreading.
--* upper-case character:                  Classification of Characters.
--* urgent data signal:                    Asynchronous I/O Signals.
--* urgent socket condition:               Out-of-Band Data.
--* usage limits:                          Limits on Resources.
--* user database:                         User Database.
--* user ID:                               User and Group IDs.
--* user ID, determining:                  Who Logged In.
--* user name:                             User and Group IDs.
--* user signals:                          Miscellaneous Signals.
--* usual file name errors:                File Name Errors.
--* variable number of arguments:          Variadic Functions.
--* variable substitution:                 Expansion Stages.
--* variable-sized arrays:                 GNU C Variable-Size Arrays.
--* variadic function argument access:     Receiving Arguments.
--* variadic function prototypes:          Variadic Prototypes.
--* variadic functions:                    Variadic Functions.
--* variadic functions, calling:           Calling Variadics.
--* virtual time alarm signal:             Alarm Signals.
--* virtual timer:                         Setting an Alarm.
--* volatile declarations:                 Nonreentrancy.
--* waiting for a signal:                  Waiting for a Signal.
--* waiting for completion of child process: Process Completion.
--* waiting for input or output:           Waiting for I/O.
--* warnings of memory almost full:        Memory Warnings.
--* WERASE character:                      Editing Characters.
--* whitespace character:                  Classification of Characters.
--* wide characters:                       Extended Char Intro.
--* width of integer type:                 Width of Type.
--* wildcard expansion:                    Expansion Stages.
--* word expansion:                        Word Expansion.
--* working directory:                     Working Directory.
--* write lock:                            File Locks.
--* writing to a file descriptor:          I/O Primitives.
--* writing to a socket:                   Transferring Data.
--* writing to a stream, by blocks:        Block Input/Output.
--* writing to a stream, by characters:    Simple Output.
--* writing to a stream, formatted:        Formatted Output.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-32 
glibc-2.0.1/manual/libc.info-32
---- ../glibc-2.0.1/manual/libc.info-32 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-32    1970-01-01 01:00:00.000000000 +0100
-@@ -1,646 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Type Index,  Next: Function Index,  Prev: Concept 
Index,  Up: Top
--
--Type Index
--**********
--
--* Menu:
--
--* cc_t:                                  Mode Data Types.
--* clock_t:                               Basic CPU Time.
--* comparison_fn_t:                       Comparison Functions.
--* cookie_close_function:                 Hook Functions.
--* cookie_io_functions_t:                 Streams and Cookies.
--* cookie_read_function:                  Hook Functions.
--* cookie_seek_function:                  Hook Functions.
--* cookie_write_function:                 Hook Functions.
--* dev_t:                                 Attribute Meanings.
--* DIR:                                   Opening a Directory.
--* div_t:                                 Integer Division.
--* enum mcheck_status:                    Heap Consistency Checking.
--* fd_set:                                Waiting for I/O.
--* FILE:                                  Streams.
--* fpos_t:                                Portable Positioning.
--* gid_t:                                 Reading Persona.
--* glob_t:                                Calling Glob.
--* ino_t:                                 Attribute Meanings.
--* jmp_buf:                               Non-Local Details.
--* ldiv_t:                                Integer Division.
--* mode_t:                                Attribute Meanings.
--* nlink_t:                               Attribute Meanings.
--* off_t:                                 File Position Primitive.
--* pid_t:                                 Process Identification.
--* printf_arginfo_function:               Defining the Output Handler.
--* printf_function:                       Defining the Output Handler.
--* ptrdiff_t:                             Important Data Types.
--* regex_t:                               POSIX Regexp Compilation.
--* regmatch_t:                            Regexp Subexpressions.
--* regoff_t:                              Regexp Subexpressions.
--* sig_atomic_t:                          Atomic Types.
--* sighandler_t:                          Basic Signal Handling.
--* sigjmp_buf:                            Non-Local Exits and Signals.
--* sigset_t:                              Signal Sets.
--* size_t:                                Important Data Types.
--* speed_t:                               Line Speed.
--* ssize_t:                               I/O Primitives.
--* struct dirent:                         Directory Entries.
--* struct flock:                          File Locks.
--* struct group:                          Group Data Structure.
--* struct hostent:                        Host Names.
--* struct in_addr:                        Host Address Data Type.
--* struct itimerval:                      Setting an Alarm.
--* struct lconv:                          Numeric Formatting.
--* struct linger:                         Socket-Level Options.
--* struct mstats:                         Statistics of Malloc.
--* struct netent:                         Networks Database.
--* struct obstack:                        Creating Obstacks.
--* struct option:                         Long Options.
--* struct passwd:                         User Data Structure.
--* struct printf_info:                    Conversion Specifier Options.
--* struct protoent:                       Protocols Database.
--* struct rlimit:                         Limits on Resources.
--* struct rusage:                         Resource Usage.
--* struct servent:                        Services Database.
--* struct sigaction:                      Advanced Signal Handling.
--* struct sigaltstack:                    Signal Stack.
--* struct sigstack:                       Signal Stack.
--* struct sigvec:                         BSD Handler.
--* struct sockaddr:                       Address Formats.
--* struct sockaddr_in:                    Internet Address Format.
--* struct sockaddr_un:                    File Namespace Details.
--* struct stat:                           Attribute Meanings.
--* struct termios:                        Mode Data Types.
--* struct timeval:                        High-Resolution Calendar.
--* struct timezone:                       High-Resolution Calendar.
--* struct tm:                             Broken-down Time.
--* struct tms:                            Detailed CPU Time.
--* struct utimbuf:                        File Times.
--* struct utsname:                        Hardware/Software Type ID.
--* tcflag_t:                              Mode Data Types.
--* time_t:                                Simple Calendar Time.
--* uid_t:                                 Reading Persona.
--* union wait:                            BSD Wait Functions.
--* va_list:                               Argument Macros.
--* wchar_t:                               Wide Char Intro.
--* wordexp_t:                             Calling Wordexp.
--
--
--File: libc.info,  Node: Function Index,  Next: Variable Index,  Prev: Type 
Index,  Up: Top
--
--Function and Macro Index
--************************
--
--* Menu:
--
--* _exit:                                 Termination Internals.
--* _tolower:                              Case Conversion.
--* _toupper:                              Case Conversion.
--* abort:                                 Aborting a Program.
--* abs:                                   Absolute Value.
--* accept:                                Accepting Connections.
--* access:                                Testing File Access.
--* acos:                                  Inverse Trig Functions.
--* acosh:                                 Hyperbolic Functions.
--* adjtime:                               High-Resolution Calendar.
--* alarm:                                 Setting an Alarm.
--* alloca:                                Variable Size Automatic.
--* asctime:                               Formatting Date and Time.
--* asin:                                  Inverse Trig Functions.
--* asinh:                                 Hyperbolic Functions.
--* asprintf:                              Dynamic Output.
--* assert:                                Consistency Checking.
--* assert_perror:                         Consistency Checking.
--* atan:                                  Inverse Trig Functions.
--* atan2:                                 Inverse Trig Functions.
--* atanh:                                 Hyperbolic Functions.
--* atexit:                                Cleanups on Exit.
--* atof:                                  Parsing of Floats.
--* atoi:                                  Parsing of Integers.
--* atol:                                  Parsing of Integers.
--* bcmp:                                  String/Array Comparison.
--* bcopy:                                 Copying and Concatenation.
--* bind:                                  Setting Address.
--* bsearch:                               Array Search Function.
--* bzero:                                 Copying and Concatenation.
--* cabs:                                  Absolute Value.
--* calloc:                                Allocating Cleared Space.
--* cbrt:                                  Exponents and Logarithms.
--* ceil:                                  Rounding and Remainders.
--* cfgetispeed:                           Line Speed.
--* cfgetospeed:                           Line Speed.
--* cfmakeraw:                             Noncanonical Input.
--* cfree:                                 Freeing after Malloc.
--* cfsetispeed:                           Line Speed.
--* cfsetospeed:                           Line Speed.
--* cfsetspeed:                            Line Speed.
--* chdir:                                 Working Directory.
--* chmod:                                 Setting Permissions.
--* chown:                                 File Owner.
--* clearerr:                              EOF and Errors.
--* clock:                                 Basic CPU Time.
--* close:                                 Opening and Closing Files.
--* closedir:                              Reading/Closing Directory.
--* confstr:                               String Parameters.
--* connect:                               Connecting.
--* copysign:                              Normalization Functions.
--* cos:                                   Trig Functions.
--* cosh:                                  Hyperbolic Functions.
--* creat:                                 Opening and Closing Files.
--* ctermid:                               Identifying the Terminal.
--* ctime:                                 Formatting Date and Time.
--* cuserid:                               Who Logged In.
--* difftime:                              Simple Calendar Time.
--* div:                                   Integer Division.
--* drem:                                  Rounding and Remainders.
--* DTTOIF:                                Directory Entries.
--* dup:                                   Duplicating Descriptors.
--* dup2:                                  Duplicating Descriptors.
--* endgrent:                              Scanning All Groups.
--* endhostent:                            Host Names.
--* endnetent:                             Networks Database.
--* endnetgrent:                           Lookup Netgroup.
--* endprotoent:                           Protocols Database.
--* endpwent:                              Scanning All Users.
--* endservent:                            Services Database.
--* execl:                                 Executing a File.
--* execle:                                Executing a File.
--* execlp:                                Executing a File.
--* execv:                                 Executing a File.
--* execve:                                Executing a File.
--* execvp:                                Executing a File.
--* exit:                                  Normal Termination.
--* exp:                                   Exponents and Logarithms.
--* expm1:                                 Exponents and Logarithms.
--* fabs:                                  Absolute Value.
--* fchmod:                                Setting Permissions.
--* fchown:                                File Owner.
--* fclean:                                Cleaning Streams.
--* fclose:                                Closing Streams.
--* fcloseall:                             Closing Streams.
--* fcntl:                                 Control Operations.
--* FD_CLR:                                Waiting for I/O.
--* FD_ISSET:                              Waiting for I/O.
--* FD_SET:                                Waiting for I/O.
--* FD_ZERO:                               Waiting for I/O.
--* fdopen:                                Descriptors and Streams.
--* feof:                                  EOF and Errors.
--* ferror:                                EOF and Errors.
--* fflush:                                Flushing Buffers.
--* fgetc:                                 Character Input.
--* fgetgrent:                             Scanning All Groups.
--* fgetgrent_r:                           Scanning All Groups.
--* fgetpos:                               Portable Positioning.
--* fgetpwent:                             Scanning All Users.
--* fgetpwent_r:                           Scanning All Users.
--* fgets:                                 Line Input.
--* fileno:                                Descriptors and Streams.
--* finite:                                Predicates on Floats.
--* floor:                                 Rounding and Remainders.
--* fmemopen:                              String Streams.
--* fmod:                                  Rounding and Remainders.
--* fnmatch:                               Wildcard Matching.
--* fopen:                                 Opening Streams.
--* fopencookie:                           Streams and Cookies.
--* fork:                                  Creating a Process.
--* fpathconf:                             Pathconf.
--* fprintf:                               Formatted Output Functions.
--* fputc:                                 Simple Output.
--* fputs:                                 Simple Output.
--* fread:                                 Block Input/Output.
--* free:                                  Freeing after Malloc.
--* freopen:                               Opening Streams.
--* frexp:                                 Normalization Functions.
--* fscanf:                                Formatted Input Functions.
--* fseek:                                 File Positioning.
--* fsetpos:                               Portable Positioning.
--* fstat:                                 Reading Attributes.
--* ftell:                                 File Positioning.
--* fwrite:                                Block Input/Output.
--* getc:                                  Character Input.
--* getchar:                               Character Input.
--* getcwd:                                Working Directory.
--* getdelim:                              Line Input.
--* getegid:                               Reading Persona.
--* getenv:                                Environment Access.
--* geteuid:                               Reading Persona.
--* getgid:                                Reading Persona.
--* getgrent:                              Scanning All Groups.
--* getgrent_r:                            Scanning All Groups.
--* getgrgid:                              Lookup Group.
--* getgrgid_r:                            Lookup Group.
--* getgrnam:                              Lookup Group.
--* getgrnam_r:                            Lookup Group.
--* getgroups:                             Reading Persona.
--* gethostbyaddr:                         Host Names.
--* gethostbyname:                         Host Names.
--* gethostent:                            Host Names.
--* gethostid:                             Host Identification.
--* gethostname:                           Host Identification.
--* getitimer:                             Setting an Alarm.
--* getline:                               Line Input.
--* getlogin:                              Who Logged In.
--* getnetbyaddr:                          Networks Database.
--* getnetbyname:                          Networks Database.
--* getnetent:                             Networks Database.
--* getnetgrent:                           Lookup Netgroup.
--* getnetgrent_r:                         Lookup Netgroup.
--* getopt:                                Parsing Options.
--* getopt_long:                           Long Options.
--* getpeername:                           Who is Connected.
--* getpgrp:                               Process Group Functions.
--* getpid:                                Process Identification.
--* getppid:                               Process Identification.
--* getpriority:                           Priority.
--* getprotobyname:                        Protocols Database.
--* getprotobynumber:                      Protocols Database.
--* getprotoent:                           Protocols Database.
--* getpwent:                              Scanning All Users.
--* getpwent_r:                            Scanning All Users.
--* getpwnam:                              Lookup User.
--* getpwnam_r:                            Lookup User.
--* getpwuid:                              Lookup User.
--* getpwuid_r:                            Lookup User.
--* getrlimit:                             Limits on Resources.
--* getrusage:                             Resource Usage.
--* gets:                                  Line Input.
--* getservbyname:                         Services Database.
--* getservbyport:                         Services Database.
--* getservent:                            Services Database.
--* getsockname:                           Reading Address.
--* getsockopt:                            Socket Option Functions.
--* getsubopt:                             Suboptions.
--* gettimeofday:                          High-Resolution Calendar.
--* getuid:                                Reading Persona.
--* getumask:                              Setting Permissions.
--* getw:                                  Character Input.
--* getwd:                                 Working Directory.
--* glob:                                  Calling Glob.
--* gmtime:                                Broken-down Time.
--* gsignal:                               Signaling Yourself.
--* htonl:                                 Byte Order.
--* htons:                                 Byte Order.
--* hypot:                                 Exponents and Logarithms.
--* IFTODT:                                Directory Entries.
--* index:                                 Search Functions.
--* inet_addr:                             Host Address Functions.
--* inet_aton:                             Host Address Functions.
--* inet_lnaof:                            Host Address Functions.
--* inet_makeaddr:                         Host Address Functions.
--* inet_netof:                            Host Address Functions.
--* inet_network:                          Host Address Functions.
--* inet_ntoa:                             Host Address Functions.
--* infnan:                                Predicates on Floats.
--* initgroups:                            Setting Groups.
--* initstate:                             BSD Random.
--* innetgr:                               Netgroup Membership.
--* isalnum:                               Classification of Characters.
--* isalpha:                               Classification of Characters.
--* isascii:                               Classification of Characters.
--* isatty:                                Is It a Terminal.
--* isblank:                               Classification of Characters.
--* iscntrl:                               Classification of Characters.
--* isdigit:                               Classification of Characters.
--* isgraph:                               Classification of Characters.
--* isinf:                                 Predicates on Floats.
--* islower:                               Classification of Characters.
--* isnan:                                 Predicates on Floats.
--* isprint:                               Classification of Characters.
--* ispunct:                               Classification of Characters.
--* isspace:                               Classification of Characters.
--* isupper:                               Classification of Characters.
--* isxdigit:                              Classification of Characters.
--* ITIMER_PROF:                           Setting an Alarm.
--* ITIMER_REAL:                           Setting an Alarm.
--* ITIMER_VIRTUAL:                        Setting an Alarm.
--* kill:                                  Signaling Another Process.
--* killpg:                                Signaling Another Process.
--* labs:                                  Absolute Value.
--* ldexp:                                 Normalization Functions.
--* ldiv:                                  Integer Division.
--* link:                                  Hard Links.
--* listen:                                Listening.
--* localeconv:                            Numeric Formatting.
--* localtime:                             Broken-down Time.
--* log:                                   Exponents and Logarithms.
--* log10:                                 Exponents and Logarithms.
--* log1p:                                 Exponents and Logarithms.
--* logb:                                  Normalization Functions.
--* longjmp:                               Non-Local Details.
--* lseek:                                 File Position Primitive.
--* lstat:                                 Reading Attributes.
--* main:                                  Program Arguments.
--* malloc:                                Basic Allocation.
--* mblen:                                 Length of Char.
--* mbstowcs:                              Wide String Conversion.
--* mbtowc:                                Converting One Char.
--* mcheck:                                Heap Consistency Checking.
--* memalign:                              Aligned Memory Blocks.
--* memccpy:                               Copying and Concatenation.
--* memchr:                                Search Functions.
--* memcmp:                                String/Array Comparison.
--* memcpy:                                Copying and Concatenation.
--* memmem:                                Search Functions.
--* memmove:                               Copying and Concatenation.
--* memory_warnings:                       Memory Warnings.
--* memset:                                Copying and Concatenation.
--* mkdir:                                 Creating Directories.
--* mkfifo:                                FIFO Special Files.
--* mknod:                                 Making Special Files.
--* mkstemp:                               Temporary Files.
--* mktemp:                                Temporary Files.
--* mktime:                                Broken-down Time.
--* modf:                                  Rounding and Remainders.
--* mprobe:                                Heap Consistency Checking.
--* mstats:                                Statistics of Malloc.
--* nice:                                  Priority.
--* notfound:                              Actions in the NSS configuration.
--* NSS_STATUS_NOTFOUND:                   NSS Modules Interface.
--* NSS_STATUS_SUCCESS:                    NSS Modules Interface.
--* NSS_STATUS_TRYAGAIN:                   NSS Modules Interface.
--* NSS_STATUS_UNAVAIL:                    NSS Modules Interface.
--* ntohl:                                 Byte Order.
--* ntohs:                                 Byte Order.
--* obstack_1grow:                         Growing Objects.
--* obstack_1grow_fast:                    Extra Fast Growing.
--* obstack_alignment_mask:                Obstacks Data Alignment.
--* obstack_alloc:                         Allocation in an Obstack.
--* obstack_base:                          Status of an Obstack.
--* obstack_blank:                         Growing Objects.
--* obstack_blank_fast:                    Extra Fast Growing.
--* obstack_chunk_alloc:                   Preparing for Obstacks.
--* obstack_chunk_free:                    Preparing for Obstacks.
--* obstack_chunk_size:                    Obstack Chunks.
--* obstack_copy:                          Allocation in an Obstack.
--* obstack_copy0:                         Allocation in an Obstack.
--* obstack_finish:                        Growing Objects.
--* obstack_free:                          Freeing Obstack Objects.
--* obstack_grow:                          Growing Objects.
--* obstack_grow0:                         Growing Objects.
--* obstack_init:                          Preparing for Obstacks.
--* obstack_int_grow:                      Growing Objects.
--* obstack_int_grow_fast:                 Extra Fast Growing.
--* obstack_next_free:                     Status of an Obstack.
--* obstack_object_size <1>:               Status of an Obstack.
--* obstack_object_size:                   Growing Objects.
--* obstack_printf:                        Dynamic Output.
--* obstack_ptr_grow:                      Growing Objects.
--* obstack_ptr_grow_fast:                 Extra Fast Growing.
--* obstack_room:                          Extra Fast Growing.
--* obstack_vprintf:                       Variable Arguments Output.
--* offsetof:                              Structure Measurement.
--* on_exit:                               Cleanups on Exit.
--* open:                                  Opening and Closing Files.
--* open_memstream:                        String Streams.
--* open_obstack_stream:                   Obstack Streams.
--* opendir:                               Opening a Directory.
--* parse_printf_format:                   Parsing a Template String.
--* pathconf:                              Pathconf.
--* pause:                                 Using Pause.
--* pclose:                                Pipe to a Subprocess.
--* perror:                                Error Messages.
--* pipe:                                  Creating a Pipe.
--* popen:                                 Pipe to a Subprocess.
--* pow:                                   Exponents and Logarithms.
--* printf:                                Formatted Output Functions.
--* psignal:                               Signal Messages.
--* putc:                                  Simple Output.
--* putchar:                               Simple Output.
--* putenv:                                Environment Access.
--* putpwent:                              Writing a User Entry.
--* puts:                                  Simple Output.
--* putw:                                  Simple Output.
--* qsort:                                 Array Sort Function.
--* r_alloc:                               Using Relocator.
--* r_alloc_free:                          Using Relocator.
--* r_re_alloc:                            Using Relocator.
--* raise:                                 Signaling Yourself.
--* rand:                                  ISO Random.
--* random:                                BSD Random.
--* read:                                  I/O Primitives.
--* readdir:                               Reading/Closing Directory.
--* readdir_r:                             Reading/Closing Directory.
--* readlink:                              Symbolic Links.
--* realloc:                               Changing Block Size.
--* recv:                                  Receiving Data.
--* recvfrom:                              Receiving Datagrams.
--* regcomp:                               POSIX Regexp Compilation.
--* regerror:                              Regexp Cleanup.
--* regexec:                               Matching POSIX Regexps.
--* regfree:                               Regexp Cleanup.
--* register_printf_function:              Registering New Conversions.
--* remove:                                Deleting Files.
--* rename:                                Renaming Files.
--* rewind:                                File Positioning.
--* rewinddir:                             Random Access Directory.
--* rindex:                                Search Functions.
--* rint:                                  Rounding and Remainders.
--* rmdir:                                 Deleting Files.
--* S_ISBLK:                               Testing File Type.
--* S_ISCHR:                               Testing File Type.
--* S_ISDIR:                               Testing File Type.
--* S_ISFIFO:                              Testing File Type.
--* S_ISLNK:                               Testing File Type.
--* S_ISREG:                               Testing File Type.
--* S_ISSOCK:                              Testing File Type.
--* scalb:                                 Normalization Functions.
--* scanf:                                 Formatted Input Functions.
--* seekdir:                               Random Access Directory.
--* select:                                Waiting for I/O.
--* send:                                  Sending Data.
--* sendto:                                Sending Datagrams.
--* setbuf:                                Controlling Buffering.
--* setbuffer:                             Controlling Buffering.
--* setgid:                                Setting Groups.
--* setgrent:                              Scanning All Groups.
--* setgroups:                             Setting Groups.
--* sethostent:                            Host Names.
--* sethostid:                             Host Identification.
--* sethostname:                           Host Identification.
--* setitimer:                             Setting an Alarm.
--* setjmp:                                Non-Local Details.
--* setlinebuf:                            Controlling Buffering.
--* setlocale:                             Setting the Locale.
--* setnetent:                             Networks Database.
--* setnetgrent:                           Lookup Netgroup.
--* setpgid:                               Process Group Functions.
--* setpgrp:                               Process Group Functions.
--* setpriority:                           Priority.
--* setprotoent:                           Protocols Database.
--* setpwent:                              Scanning All Users.
--* setregid:                              Setting Groups.
--* setreuid:                              Setting User ID.
--* setrlimit:                             Limits on Resources.
--* setservent:                            Services Database.
--* setsid:                                Process Group Functions.
--* setsockopt:                            Socket Option Functions.
--* setstate:                              BSD Random.
--* settimeofday:                          High-Resolution Calendar.
--* setuid:                                Setting User ID.
--* setvbuf:                               Controlling Buffering.
--* shutdown:                              Closing a Socket.
--* sigaction:                             Advanced Signal Handling.
--* sigaddset:                             Signal Sets.
--* sigaltstack:                           Signal Stack.
--* sigblock:                              Blocking in BSD.
--* sigdelset:                             Signal Sets.
--* sigemptyset:                           Signal Sets.
--* sigfillset:                            Signal Sets.
--* siginterrupt:                          BSD Handler.
--* sigismember:                           Signal Sets.
--* siglongjmp:                            Non-Local Exits and Signals.
--* sigmask:                               Blocking in BSD.
--* signal:                                Basic Signal Handling.
--* sigpause:                              Blocking in BSD.
--* sigpending:                            Checking for Pending Signals.
--* sigprocmask:                           Process Signal Mask.
--* sigsetjmp:                             Non-Local Exits and Signals.
--* sigsetmask:                            Blocking in BSD.
--* sigstack:                              Signal Stack.
--* sigsuspend:                            Sigsuspend.
--* sigvec:                                BSD Handler.
--* sin:                                   Trig Functions.
--* sinh:                                  Hyperbolic Functions.
--* sleep:                                 Sleeping.
--* snprintf:                              Formatted Output Functions.
--* socket:                                Creating a Socket.
--* socketpair:                            Socket Pairs.
--* sprintf:                               Formatted Output Functions.
--* sqrt:                                  Exponents and Logarithms.
--* srand:                                 ISO Random.
--* srandom:                               BSD Random.
--* sscanf:                                Formatted Input Functions.
--* ssignal:                               Basic Signal Handling.
--* stat:                                  Reading Attributes.
--* stpcpy:                                Copying and Concatenation.
--* stpncpy:                               Copying and Concatenation.
--* strcasecmp:                            String/Array Comparison.
--* strcat:                                Copying and Concatenation.
--* strchr:                                Search Functions.
--* strcmp:                                String/Array Comparison.
--* strcoll:                               Collation Functions.
--* strcpy:                                Copying and Concatenation.
--* strcspn:                               Search Functions.
--* strdup:                                Copying and Concatenation.
--* strdupa:                               Copying and Concatenation.
--* strerror:                              Error Messages.
--* strftime:                              Formatting Date and Time.
--* strlen:                                String Length.
--* strncasecmp:                           String/Array Comparison.
--* strncat:                               Copying and Concatenation.
--* strncmp:                               String/Array Comparison.
--* strncpy:                               Copying and Concatenation.
--* strndup:                               Copying and Concatenation.
--* strndupa:                              Copying and Concatenation.
--* strpbrk:                               Search Functions.
--* strrchr:                               Search Functions.
--* strsep:                                Finding Tokens in a String.
--* strsignal:                             Signal Messages.
--* strspn:                                Search Functions.
--* strstr:                                Search Functions.
--* strtod:                                Parsing of Floats.
--* strtof:                                Parsing of Floats.
--* strtok:                                Finding Tokens in a String.
--* strtok_r:                              Finding Tokens in a String.
--* strtol:                                Parsing of Integers.
--* strtold:                               Parsing of Floats.
--* strtoll:                               Parsing of Integers.
--* strtoq:                                Parsing of Integers.
--* strtoul:                               Parsing of Integers.
--* strtoull:                              Parsing of Integers.
--* strtouq:                               Parsing of Integers.
--* strxfrm:                               Collation Functions.
--* success:                               Actions in the NSS configuration.
--* symlink:                               Symbolic Links.
--* sysconf:                               Sysconf Definition.
--* system:                                Running a Command.
--* tan:                                   Trig Functions.
--* tanh:                                  Hyperbolic Functions.
--* tcdrain:                               Line Control.
--* tcflow:                                Line Control.
--* tcflush:                               Line Control.
--* tcgetattr:                             Mode Functions.
--* tcgetpgrp:                             Terminal Access Functions.
--* tcsendbreak:                           Line Control.
--* tcsetattr:                             Mode Functions.
--* tcsetpgrp:                             Terminal Access Functions.
--* telldir:                               Random Access Directory.
--* TEMP_FAILURE_RETRY:                    Interrupted Primitives.
--* tempnam:                               Temporary Files.
--* time:                                  Simple Calendar Time.
--* times:                                 Detailed CPU Time.
--* tmpfile:                               Temporary Files.
--* tmpnam:                                Temporary Files.
--* tmpnam_r:                              Temporary Files.
--* toascii:                               Case Conversion.
--* tolower:                               Case Conversion.
--* toupper:                               Case Conversion.
--* tryagain:                              Actions in the NSS configuration.
--* ttyname:                               Is It a Terminal.
--* tzset:                                 Time Zone Functions.
--* umask:                                 Setting Permissions.
--* uname:                                 Hardware/Software Type ID.
--* unavail:                               Actions in the NSS configuration.
--* ungetc:                                How Unread.
--* unlink:                                Deleting Files.
--* utime:                                 File Times.
--* utimes:                                File Times.
--* va_alist:                              Old Varargs.
--* va_arg:                                Argument Macros.
--* va_dcl:                                Old Varargs.
--* va_end:                                Argument Macros.
--* va_start <1>:                          Old Varargs.
--* va_start:                              Argument Macros.
--* valloc:                                Aligned Memory Blocks.
--* vasprintf:                             Variable Arguments Output.
--* vfork:                                 Creating a Process.
--* vfprintf:                              Variable Arguments Output.
--* vfscanf:                               Variable Arguments Input.
--* vprintf:                               Variable Arguments Output.
--* vscanf:                                Variable Arguments Input.
--* vsnprintf:                             Variable Arguments Output.
--* vsprintf:                              Variable Arguments Output.
--* vsscanf:                               Variable Arguments Input.
--* wait:                                  Process Completion.
--* wait3:                                 BSD Wait Functions.
--* wait4:                                 Process Completion.
--* waitpid:                               Process Completion.
--* WCOREDUMP:                             Process Completion Status.
--* wcstombs:                              Wide String Conversion.
--* wctomb:                                Converting One Char.
--* WEXITSTATUS:                           Process Completion Status.
--* WIFEXITED:                             Process Completion Status.
--* WIFSIGNALED:                           Process Completion Status.
--* WIFSTOPPED:                            Process Completion Status.
--* wordexp:                               Calling Wordexp.
--* wordfree:                              Calling Wordexp.
--* write:                                 I/O Primitives.
--* WSTOPSIG:                              Process Completion Status.
--* WTERMSIG:                              Process Completion Status.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-33 
glibc-2.0.1/manual/libc.info-33
---- ../glibc-2.0.1/manual/libc.info-33 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-33    1970-01-01 01:00:00.000000000 +0100
-@@ -1,816 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Variable Index,  Next: File Index,  Prev: Function 
Index,  Up: Top
--
--Variable and Constant Macro Index
--*********************************
--
--* Menu:
--
--* __free_hook:                           Hooks for Malloc.
--* __malloc_hook:                         Hooks for Malloc.
--* __realloc_hook:                        Hooks for Malloc.
--* _BSD_SOURCE:                           Feature Test Macros.
--* _GNU_SOURCE:                           Feature Test Macros.
--* _IOFBF:                                Controlling Buffering.
--* _IOLBF:                                Controlling Buffering.
--* _IONBF:                                Controlling Buffering.
--* _POSIX2_C_DEV:                         System Options.
--* _POSIX2_C_VERSION:                     Version Supported.
--* _POSIX2_FORT_DEV:                      System Options.
--* _POSIX2_FORT_RUN:                      System Options.
--* _POSIX2_LOCALEDEF:                     System Options.
--* _POSIX2_SW_DEV:                        System Options.
--* _POSIX_C_SOURCE:                       Feature Test Macros.
--* _POSIX_CHOWN_RESTRICTED:               Options for Files.
--* _POSIX_JOB_CONTROL:                    System Options.
--* _POSIX_NO_TRUNC:                       Options for Files.
--* _POSIX_SAVED_IDS:                      System Options.
--* _POSIX_SOURCE:                         Feature Test Macros.
--* _POSIX_VDISABLE <1>:                   Options for Files.
--* _POSIX_VDISABLE:                       Special Characters.
--* _POSIX_VERSION:                        Version Supported.
--* _REENTRANT:                            Feature Test Macros.
--* _SVID_SOURCE:                          Feature Test Macros.
--* _THREAD_SAFE:                          Feature Test Macros.
--* _XOPEN_SOURCE:                         Feature Test Macros.
--* AF_FILE:                               Address Formats.
--* AF_INET:                               Address Formats.
--* AF_UNIX:                               Address Formats.
--* AF_UNSPEC:                             Address Formats.
--* ALTWERASE:                             Local Modes.
--* ARG_MAX:                               General Limits.
--* B0:                                    Line Speed.
--* B110:                                  Line Speed.
--* B1200:                                 Line Speed.
--* B134:                                  Line Speed.
--* B150:                                  Line Speed.
--* B1800:                                 Line Speed.
--* B19200:                                Line Speed.
--* B200:                                  Line Speed.
--* B2400:                                 Line Speed.
--* B300:                                  Line Speed.
--* B38400:                                Line Speed.
--* B4800:                                 Line Speed.
--* B50:                                   Line Speed.
--* B600:                                  Line Speed.
--* B75:                                   Line Speed.
--* B9600:                                 Line Speed.
--* BC_BASE_MAX:                           Utility Limits.
--* BC_DIM_MAX:                            Utility Limits.
--* BC_SCALE_MAX:                          Utility Limits.
--* BC_STRING_MAX:                         Utility Limits.
--* BRKINT:                                Input Modes.
--* BUFSIZ:                                Controlling Buffering.
--* CCTS_OFLOW:                            Control Modes.
--* CHILD_MAX:                             General Limits.
--* CIGNORE:                               Control Modes.
--* CLK_TCK:                               Basic CPU Time.
--* CLOCAL:                                Control Modes.
--* CLOCKS_PER_SEC:                        Basic CPU Time.
--* COLL_WEIGHTS_MAX:                      Utility Limits.
--* COREFILE:                              Program Error Signals.
--* CREAD:                                 Control Modes.
--* CRTS_IFLOW:                            Control Modes.
--* CS5:                                   Control Modes.
--* CS6:                                   Control Modes.
--* CS7:                                   Control Modes.
--* CS8:                                   Control Modes.
--* CSIZE:                                 Control Modes.
--* CSTOPB:                                Control Modes.
--* daylight:                              Time Zone Functions.
--* E2BIG:                                 Error Codes.
--* EACCES:                                Error Codes.
--* EADDRINUSE:                            Error Codes.
--* EADDRNOTAVAIL:                         Error Codes.
--* EADV:                                  Error Codes.
--* EAFNOSUPPORT:                          Error Codes.
--* EAGAIN:                                Error Codes.
--* EALREADY:                              Error Codes.
--* EAUTH:                                 Error Codes.
--* EBACKGROUND:                           Error Codes.
--* EBADE:                                 Error Codes.
--* EBADF <1>:                             Line Control.
--* EBADF:                                 Error Codes.
--* EBADFD:                                Error Codes.
--* EBADMSG:                               Error Codes.
--* EBADR:                                 Error Codes.
--* EBADRPC:                               Error Codes.
--* EBADRQC:                               Error Codes.
--* EBADSLT:                               Error Codes.
--* EBFONT:                                Error Codes.
--* EBUSY:                                 Error Codes.
--* ECHILD:                                Error Codes.
--* ECHO:                                  Local Modes.
--* ECHOCTL:                               Local Modes.
--* ECHOE:                                 Local Modes.
--* ECHOK:                                 Local Modes.
--* ECHOKE:                                Local Modes.
--* ECHONL:                                Local Modes.
--* ECHOPRT:                               Local Modes.
--* ECHRNG:                                Error Codes.
--* ECOMM:                                 Error Codes.
--* ECONNABORTED:                          Error Codes.
--* ECONNREFUSED:                          Error Codes.
--* ECONNRESET:                            Error Codes.
--* ED:                                    Error Codes.
--* EDEADLK:                               Error Codes.
--* EDEADLOCK:                             Error Codes.
--* EDESTADDRREQ:                          Error Codes.
--* EDIED:                                 Error Codes.
--* EDOM:                                  Error Codes.
--* EDOTDOT:                               Error Codes.
--* EDQUOT:                                Error Codes.
--* EEXIST:                                Error Codes.
--* EFAULT:                                Error Codes.
--* EFBIG:                                 Error Codes.
--* EFTYPE:                                Error Codes.
--* EGRATUITOUS:                           Error Codes.
--* EGREGIOUS:                             Error Codes.
--* EHOSTDOWN:                             Error Codes.
--* EHOSTUNREACH:                          Error Codes.
--* EIDRM:                                 Error Codes.
--* EIEIO:                                 Error Codes.
--* EILSEQ:                                Error Codes.
--* EINPROGRESS:                           Error Codes.
--* EINTR:                                 Error Codes.
--* EINVAL <1>:                            Line Control.
--* EINVAL:                                Error Codes.
--* EIO:                                   Error Codes.
--* EISCONN:                               Error Codes.
--* EISDIR:                                Error Codes.
--* EISNAM:                                Error Codes.
--* EL2HLT:                                Error Codes.
--* EL2NSYNC:                              Error Codes.
--* EL3HLT:                                Error Codes.
--* EL3RST:                                Error Codes.
--* ELIBACC:                               Error Codes.
--* ELIBBAD:                               Error Codes.
--* ELIBEXEC:                              Error Codes.
--* ELIBMAX:                               Error Codes.
--* ELIBSCN:                               Error Codes.
--* ELNRNG:                                Error Codes.
--* ELOOP:                                 Error Codes.
--* EMFILE:                                Error Codes.
--* EMLINK:                                Error Codes.
--* EMSGSIZE:                              Error Codes.
--* EMULTIHOP:                             Error Codes.
--* ENAMETOOLONG:                          Error Codes.
--* ENAVAIL:                               Error Codes.
--* ENEEDAUTH:                             Error Codes.
--* ENETDOWN:                              Error Codes.
--* ENETRESET:                             Error Codes.
--* ENETUNREACH:                           Error Codes.
--* ENFILE:                                Error Codes.
--* ENOANO:                                Error Codes.
--* ENOBUFS:                               Error Codes.
--* ENOCSI:                                Error Codes.
--* ENODATA:                               Error Codes.
--* ENODEV:                                Error Codes.
--* ENOENT:                                Error Codes.
--* ENOEXEC:                               Error Codes.
--* ENOLCK:                                Error Codes.
--* ENOLINK:                               Error Codes.
--* ENOMEM:                                Error Codes.
--* ENOMSG:                                Error Codes.
--* ENONET:                                Error Codes.
--* ENOPKG:                                Error Codes.
--* ENOPROTOOPT:                           Error Codes.
--* ENOSPC:                                Error Codes.
--* ENOSR:                                 Error Codes.
--* ENOSTR:                                Error Codes.
--* ENOSYS:                                Error Codes.
--* ENOTBLK:                               Error Codes.
--* ENOTCONN:                              Error Codes.
--* ENOTDIR:                               Error Codes.
--* ENOTEMPTY:                             Error Codes.
--* ENOTNAM:                               Error Codes.
--* ENOTSOCK:                              Error Codes.
--* ENOTTY <1>:                            Line Control.
--* ENOTTY:                                Error Codes.
--* ENOTUNIQ:                              Error Codes.
--* environ:                               Environment Access.
--* ENXIO:                                 Error Codes.
--* EOF:                                   EOF and Errors.
--* EOPNOTSUPP:                            Error Codes.
--* EOVERFLOW:                             Error Codes.
--* EPERM:                                 Error Codes.
--* EPFNOSUPPORT:                          Error Codes.
--* EPIPE:                                 Error Codes.
--* EPROCLIM:                              Error Codes.
--* EPROCUNAVAIL:                          Error Codes.
--* EPROGMISMATCH:                         Error Codes.
--* EPROGUNAVAIL:                          Error Codes.
--* EPROTO:                                Error Codes.
--* EPROTONOSUPPORT:                       Error Codes.
--* EPROTOTYPE:                            Error Codes.
--* EQUIV_CLASS_MAX:                       Utility Limits.
--* ERANGE:                                Error Codes.
--* EREMCHG:                               Error Codes.
--* EREMOTE:                               Error Codes.
--* EREMOTEIO:                             Error Codes.
--* ERESTART:                              Error Codes.
--* EROFS:                                 Error Codes.
--* ERPCMISMATCH:                          Error Codes.
--* errno:                                 Checking for Errors.
--* ESHUTDOWN:                             Error Codes.
--* ESOCKTNOSUPPORT:                       Error Codes.
--* ESPIPE:                                Error Codes.
--* ESRCH:                                 Error Codes.
--* ESRMNT:                                Error Codes.
--* ESTALE:                                Error Codes.
--* ESTRPIPE:                              Error Codes.
--* ethers:                                NSS Basics.
--* ETIME:                                 Error Codes.
--* ETIMEDOUT:                             Error Codes.
--* ETOOMANYREFS:                          Error Codes.
--* ETXTBSY:                               Error Codes.
--* EUCLEAN:                               Error Codes.
--* EUNATCH:                               Error Codes.
--* EUSERS:                                Error Codes.
--* EWOULDBLOCK:                           Error Codes.
--* EXDEV:                                 Error Codes.
--* EXFULL:                                Error Codes.
--* EXIT_FAILURE:                          Exit Status.
--* EXIT_SUCCESS:                          Exit Status.
--* EXPR_NEST_MAX:                         Utility Limits.
--* EXTA:                                  Line Speed.
--* EXTB:                                  Line Speed.
--* F_DUPFD:                               Duplicating Descriptors.
--* F_GETFD:                               Descriptor Flags.
--* F_GETFL:                               Getting File Status Flags.
--* F_GETLK:                               File Locks.
--* F_GETOWN:                              Interrupt Input.
--* F_OK:                                  Testing File Access.
--* F_RDLCK:                               File Locks.
--* F_SETFD:                               Descriptor Flags.
--* F_SETFL:                               Getting File Status Flags.
--* F_SETLK:                               File Locks.
--* F_SETLKW:                              File Locks.
--* F_SETOWN:                              Interrupt Input.
--* F_UNLCK:                               File Locks.
--* F_WRLCK:                               File Locks.
--* FD_CLOEXEC:                            Descriptor Flags.
--* FD_SETSIZE:                            Waiting for I/O.
--* FILENAME_MAX:                          Limits for Files.
--* FLUSHO:                                Local Modes.
--* FOPEN_MAX:                             Opening Streams.
--* FPE_DECOVF_TRAP:                       Program Error Signals.
--* FPE_FLTDIV_TRAP:                       Program Error Signals.
--* FPE_FLTOVF_TRAP:                       Program Error Signals.
--* FPE_FLTUND_TRAP:                       Program Error Signals.
--* FPE_INTDIV_TRAP:                       Program Error Signals.
--* FPE_INTOVF_TRAP:                       Program Error Signals.
--* FPE_SUBRNG_TRAP:                       Program Error Signals.
--* group:                                 NSS Basics.
--* h_errno:                               Host Names.
--* HOST_NOT_FOUND:                        Host Names.
--* hosts:                                 NSS Basics.
--* HUGE_VAL:                              Domain and Range Errors.
--* HUGE_VALf:                             Domain and Range Errors.
--* HUGE_VALl:                             Domain and Range Errors.
--* HUPCL:                                 Control Modes.
--* ICANON:                                Local Modes.
--* ICRNL:                                 Input Modes.
--* IEXTEN:                                Local Modes.
--* IGNBRK:                                Input Modes.
--* IGNCR:                                 Input Modes.
--* IGNPAR:                                Input Modes.
--* IMAXBEL:                               Input Modes.
--* INADDR_ANY:                            Host Address Data Type.
--* INADDR_BROADCAST:                      Host Address Data Type.
--* INADDR_LOOPBACK:                       Host Address Data Type.
--* INADDR_NONE:                           Host Address Data Type.
--* INLCR:                                 Input Modes.
--* INPCK:                                 Input Modes.
--* int:                                   Limits on Resources.
--* IPPORT_RESERVED:                       Ports.
--* IPPORT_USERRESERVED:                   Ports.
--* ISIG:                                  Local Modes.
--* ISTRIP:                                Input Modes.
--* IXANY:                                 Input Modes.
--* IXOFF:                                 Input Modes.
--* IXON:                                  Input Modes.
--* L_ctermid:                             Identifying the Terminal.
--* L_cuserid:                             Who Logged In.
--* L_INCR:                                File Positioning.
--* L_SET:                                 File Positioning.
--* L_tmpnam:                              Temporary Files.
--* L_XTND:                                File Positioning.
--* LANG:                                  Locale Categories.
--* LC_ALL:                                Locale Categories.
--* LC_COLLATE:                            Locale Categories.
--* LC_CTYPE:                              Locale Categories.
--* LC_MESSAGES:                           Locale Categories.
--* LC_MONETARY:                           Locale Categories.
--* LC_NUMERIC:                            Locale Categories.
--* LC_TIME:                               Locale Categories.
--* LINE_MAX:                              Utility Limits.
--* LINK_MAX:                              Limits for Files.
--* MAX_CANON:                             Limits for Files.
--* MAX_INPUT:                             Limits for Files.
--* MAXNAMLEN:                             Limits for Files.
--* MB_CUR_MAX:                            Multibyte Char Intro.
--* MB_LEN_MAX:                            Multibyte Char Intro.
--* MDMBUF:                                Control Modes.
--* MINSIGSTKSZ:                           Signal Stack.
--* MSG_DONTROUTE:                         Socket Data Options.
--* MSG_OOB:                               Socket Data Options.
--* MSG_PEEK:                              Socket Data Options.
--* NAME_MAX:                              Limits for Files.
--* NAN:                                   Not a Number.
--* NCCS:                                  Mode Data Types.
--* NDEBUG:                                Consistency Checking.
--* netgroup:                              NSS Basics.
--* network:                               NSS Basics.
--* NGROUPS_MAX:                           General Limits.
--* NO_ADDRESS:                            Host Names.
--* NO_RECOVERY:                           Host Names.
--* NOFLSH:                                Local Modes.
--* NOKERNINFO:                            Local Modes.
--* NSIG:                                  Standard Signals.
--* NSS_STATUS_NOTFOUND:                   NSS Modules Interface.
--* NSS_STATUS_SUCCESS:                    NSS Modules Interface.
--* NSS_STATUS_TRYAGAIN:                   NSS Modules Interface.
--* NSS_STATUS_UNAVAIL:                    NSS Modules Interface.
--* NULL:                                  Null Pointer Constant.
--* O_ACCMODE:                             Access Modes.
--* O_APPEND:                              Operating Modes.
--* O_ASYNC:                               Operating Modes.
--* O_CREAT:                               Open-time Flags.
--* O_EXCL:                                Open-time Flags.
--* O_EXEC:                                Access Modes.
--* O_EXLOCK:                              Open-time Flags.
--* O_FSYNC:                               Operating Modes.
--* O_IGNORE_CTTY:                         Open-time Flags.
--* O_NDELAY:                              Operating Modes.
--* O_NOATIME:                             Operating Modes.
--* O_NOCTTY:                              Open-time Flags.
--* O_NOLINK:                              Open-time Flags.
--* O_NONBLOCK <1>:                        Operating Modes.
--* O_NONBLOCK:                            Open-time Flags.
--* O_NOTRANS:                             Open-time Flags.
--* O_RDONLY:                              Access Modes.
--* O_RDWR:                                Access Modes.
--* O_READ:                                Access Modes.
--* O_SHLOCK:                              Open-time Flags.
--* O_SYNC:                                Operating Modes.
--* O_TRUNC:                               Open-time Flags.
--* O_WRITE:                               Access Modes.
--* O_WRONLY:                              Access Modes.
--* ONLCR:                                 Output Modes.
--* ONOEOT:                                Output Modes.
--* OPEN_MAX:                              General Limits.
--* OPOST:                                 Output Modes.
--* optarg:                                Parsing Options.
--* opterr:                                Parsing Options.
--* optind:                                Parsing Options.
--* optopt:                                Parsing Options.
--* OXTABS:                                Output Modes.
--* P_tmpdir:                              Temporary Files.
--* PA_CHAR:                               Parsing a Template String.
--* PA_DOUBLE:                             Parsing a Template String.
--* PA_FLAG_LONG:                          Parsing a Template String.
--* PA_FLAG_LONG_DOUBLE:                   Parsing a Template String.
--* PA_FLAG_LONG_LONG:                     Parsing a Template String.
--* PA_FLAG_MASK:                          Parsing a Template String.
--* PA_FLAG_PTR:                           Parsing a Template String.
--* PA_FLAG_SHORT:                         Parsing a Template String.
--* PA_FLOAT:                              Parsing a Template String.
--* PA_INT:                                Parsing a Template String.
--* PA_LAST:                               Parsing a Template String.
--* PA_POINTER:                            Parsing a Template String.
--* PA_STRING:                             Parsing a Template String.
--* PARENB:                                Control Modes.
--* PARMRK:                                Input Modes.
--* PARODD:                                Control Modes.
--* passwd:                                NSS Basics.
--* PATH_MAX:                              Limits for Files.
--* PENDIN:                                Local Modes.
--* PF_CCITT:                              Misc Namespaces.
--* PF_FILE:                               File Namespace Details.
--* PF_IMPLINK:                            Misc Namespaces.
--* PF_INET:                               Internet Namespace.
--* PF_ISO:                                Misc Namespaces.
--* PF_NS:                                 Misc Namespaces.
--* PF_ROUTE:                              Misc Namespaces.
--* PF_UNIX:                               File Namespace Details.
--* PIPE_BUF:                              Limits for Files.
--* PRIO_MAX:                              Priority.
--* PRIO_MIN:                              Priority.
--* PRIO_PGRP:                             Priority.
--* PRIO_PROCESS:                          Priority.
--* PRIO_USER:                             Priority.
--* program_invocation_name:               Error Messages.
--* program_invocation_short_name:         Error Messages.
--* protocols:                             NSS Basics.
--* R_OK:                                  Testing File Access.
--* RAND_MAX:                              ISO Random.
--* RE_DUP_MAX:                            General Limits.
--* RLIM_NLIMITS:                          Limits on Resources.
--* RLIMIT_CORE:                           Limits on Resources.
--* RLIMIT_CPU:                            Limits on Resources.
--* RLIMIT_DATA:                           Limits on Resources.
--* RLIMIT_FSIZE:                          Limits on Resources.
--* RLIMIT_NOFILE:                         Limits on Resources.
--* RLIMIT_OFILE:                          Limits on Resources.
--* RLIMIT_RSS:                            Limits on Resources.
--* RLIMIT_STACK:                          Limits on Resources.
--* rpc:                                   NSS Basics.
--* S_IEXEC:                               Permission Bits.
--* S_IFBLK:                               Testing File Type.
--* S_IFCHR:                               Testing File Type.
--* S_IFDIR:                               Testing File Type.
--* S_IFIFO:                               Testing File Type.
--* S_IFLNK:                               Testing File Type.
--* S_IFMT:                                Testing File Type.
--* S_IFREG:                               Testing File Type.
--* S_IFSOCK:                              Testing File Type.
--* S_IREAD:                               Permission Bits.
--* S_IRGRP:                               Permission Bits.
--* S_IROTH:                               Permission Bits.
--* S_IRUSR:                               Permission Bits.
--* S_IRWXG:                               Permission Bits.
--* S_IRWXO:                               Permission Bits.
--* S_IRWXU:                               Permission Bits.
--* S_ISGID:                               Permission Bits.
--* S_ISUID:                               Permission Bits.
--* S_ISVTX:                               Permission Bits.
--* S_IWGRP:                               Permission Bits.
--* S_IWOTH:                               Permission Bits.
--* S_IWRITE:                              Permission Bits.
--* S_IWUSR:                               Permission Bits.
--* S_IXGRP:                               Permission Bits.
--* S_IXOTH:                               Permission Bits.
--* S_IXUSR:                               Permission Bits.
--* SA_DISABLE:                            Signal Stack.
--* SA_NOCLDSTOP:                          Flags for Sigaction.
--* SA_ONSTACK <1>:                        Signal Stack.
--* SA_ONSTACK:                            Flags for Sigaction.
--* SA_RESTART:                            Flags for Sigaction.
--* SEEK_CUR:                              File Positioning.
--* SEEK_END:                              File Positioning.
--* SEEK_SET:                              File Positioning.
--* services:                              NSS Basics.
--* shadow:                                NSS Basics.
--* SIG_BLOCK:                             Process Signal Mask.
--* SIG_DFL:                               Basic Signal Handling.
--* SIG_ERR:                               Basic Signal Handling.
--* SIG_IGN:                               Basic Signal Handling.
--* SIG_SETMASK:                           Process Signal Mask.
--* SIG_UNBLOCK:                           Process Signal Mask.
--* SIGABRT:                               Program Error Signals.
--* SIGALRM:                               Alarm Signals.
--* SIGBUS:                                Program Error Signals.
--* SIGCHLD:                               Job Control Signals.
--* SIGCLD:                                Job Control Signals.
--* SIGCONT:                               Job Control Signals.
--* SIGEMT:                                Program Error Signals.
--* SIGFPE:                                Program Error Signals.
--* SIGHUP:                                Termination Signals.
--* SIGILL:                                Program Error Signals.
--* SIGINFO:                               Miscellaneous Signals.
--* SIGINT:                                Termination Signals.
--* SIGIO:                                 Asynchronous I/O Signals.
--* SIGIOT:                                Program Error Signals.
--* SIGKILL:                               Termination Signals.
--* SIGLOST:                               Operation Error Signals.
--* SIGPIPE:                               Operation Error Signals.
--* SIGPOLL:                               Asynchronous I/O Signals.
--* SIGPROF:                               Alarm Signals.
--* SIGQUIT:                               Termination Signals.
--* SIGSEGV:                               Program Error Signals.
--* SIGSTKSZ:                              Signal Stack.
--* SIGSTOP:                               Job Control Signals.
--* SIGSYS:                                Program Error Signals.
--* SIGTERM:                               Termination Signals.
--* SIGTRAP:                               Program Error Signals.
--* SIGTSTP:                               Job Control Signals.
--* SIGTTIN:                               Job Control Signals.
--* SIGTTOU:                               Job Control Signals.
--* SIGURG:                                Asynchronous I/O Signals.
--* SIGUSR1:                               Miscellaneous Signals.
--* SIGUSR2:                               Miscellaneous Signals.
--* SIGVTALRM:                             Alarm Signals.
--* SIGWINCH:                              Miscellaneous Signals.
--* SIGXCPU:                               Operation Error Signals.
--* SIGXFSZ:                               Operation Error Signals.
--* SOCK_DGRAM:                            Communication Styles.
--* SOCK_RAW:                              Communication Styles.
--* SOCK_STREAM:                           Communication Styles.
--* SOL_SOCKET:                            Socket-Level Options.
--* SSIZE_MAX:                             General Limits.
--* stderr:                                Standard Streams.
--* STDERR_FILENO:                         Descriptors and Streams.
--* stdin:                                 Standard Streams.
--* STDIN_FILENO:                          Descriptors and Streams.
--* stdout:                                Standard Streams.
--* STDOUT_FILENO:                         Descriptors and Streams.
--* STREAM_MAX:                            General Limits.
--* SV_INTERRUPT:                          BSD Handler.
--* SV_ONSTACK:                            BSD Handler.
--* SV_RESETHAND:                          BSD Handler.
--* sys_siglist:                           Signal Messages.
--* TCIFLUSH:                              Line Control.
--* TCIOFF:                                Line Control.
--* TCIOFLUSH:                             Line Control.
--* TCION:                                 Line Control.
--* TCOFLUSH:                              Line Control.
--* TCOOFF:                                Line Control.
--* TCOON:                                 Line Control.
--* TCSADRAIN:                             Mode Functions.
--* TCSAFLUSH:                             Mode Functions.
--* TCSANOW:                               Mode Functions.
--* TCSASOFT:                              Mode Functions.
--* timezone:                              Time Zone Functions.
--* TMP_MAX:                               Temporary Files.
--* TOSTOP:                                Local Modes.
--* TRY_AGAIN:                             Host Names.
--* tzname:                                Time Zone Functions.
--* TZNAME_MAX:                            General Limits.
--* VDISCARD:                              Other Special.
--* VDSUSP:                                Signal Characters.
--* VEOF:                                  Editing Characters.
--* VEOL:                                  Editing Characters.
--* VEOL2:                                 Editing Characters.
--* VERASE:                                Editing Characters.
--* VINTR:                                 Signal Characters.
--* VKILL:                                 Editing Characters.
--* VLNEXT:                                Other Special.
--* VMIN:                                  Noncanonical Input.
--* VQUIT:                                 Signal Characters.
--* VREPRINT:                              Editing Characters.
--* VSTART:                                Start/Stop Characters.
--* VSTATUS:                               Other Special.
--* VSTOP:                                 Start/Stop Characters.
--* VSUSP:                                 Signal Characters.
--* VTIME:                                 Noncanonical Input.
--* VWERASE:                               Editing Characters.
--* W_OK:                                  Testing File Access.
--* X_OK:                                  Testing File Access.
--
--
--File: libc.info,  Node: File Index,  Prev: Variable Index,  Up: Top
--
--Program and File Index
--**********************
--
--* Menu:
--
--* -lbsd-compat <1>:                      Process Group Functions.
--* -lbsd-compat:                          Feature Test Macros.
--* /etc/group:                            Group Database.
--* /etc/hosts:                            Host Names.
--* /etc/localtime:                        TZ Variable.
--* /etc/networks:                         Networks Database.
--* /etc/passwd:                           User Database.
--* /etc/protocols:                        Protocols Database.
--* /etc/services:                         Services Database.
--* /share/lib/zoneinfo:                   TZ Variable.
--* arpa/inet.h:                           Host Address Functions.
--* assert.h:                              Consistency Checking.
--* bsd-compat <1>:                        Process Group Functions.
--* bsd-compat:                            Feature Test Macros.
--* cd:                                    Working Directory.
--* chgrp:                                 File Owner.
--* chown:                                 File Owner.
--* ctype.h <1>:                           Case Conversion.
--* ctype.h <2>:                           Classification of Characters.
--* ctype.h:                               Character Handling.
--* dirent.h <1>:                          Random Access Directory.
--* dirent.h <2>:                          Reading/Closing Directory.
--* dirent.h <3>:                          Opening a Directory.
--* dirent.h <4>:                          Directory Entries.
--* dirent.h:                              Reserved Names.
--* errno.h <1>:                           Error Codes.
--* errno.h <2>:                           Checking for Errors.
--* errno.h:                               Error Reporting.
--* fcntl.h <1>:                           Interrupt Input.
--* fcntl.h <2>:                           File Locks.
--* fcntl.h <3>:                           File Status Flags.
--* fcntl.h <4>:                           Descriptor Flags.
--* fcntl.h <5>:                           Duplicating Descriptors.
--* fcntl.h <6>:                           Control Operations.
--* fcntl.h <7>:                           Opening and Closing Files.
--* fcntl.h:                               Reserved Names.
--* float.h:                               Floating Point Parameters.
--* fnmatch.h:                             Wildcard Matching.
--* gcc:                                   ISO C.
--* grp.h <1>:                             Group Data Structure.
--* grp.h <2>:                             Setting Groups.
--* grp.h:                                 Reserved Names.
--* hostid:                                Host Identification.
--* hostname:                              Host Identification.
--* kill:                                  Termination Signals.
--* limits.h <1>:                          Width of Type.
--* limits.h <2>:                          Limits for Files.
--* limits.h <3>:                          General Limits.
--* limits.h <4>:                          Multibyte Char Intro.
--* limits.h:                              Reserved Names.
--* locale.h <1>:                          Numeric Formatting.
--* locale.h:                              Setting the Locale.
--* localtime:                             TZ Variable.
--* ls:                                    File Attributes.
--* malloc.c:                              Memory Warnings.
--* malloc.h <1>:                          Using Relocator.
--* malloc.h <2>:                          Statistics of Malloc.
--* malloc.h <3>:                          Hooks for Malloc.
--* malloc.h:                              Heap Consistency Checking.
--* math.h <1>:                            Rounding and Remainders.
--* math.h <2>:                            Normalization Functions.
--* math.h <3>:                            Absolute Value.
--* math.h <4>:                            Predicates on Floats.
--* math.h:                                Mathematics.
--* mkdir:                                 Creating Directories.
--* netdb.h <1>:                           Networks Database.
--* netdb.h <2>:                           Protocols Database.
--* netdb.h <3>:                           Services Database.
--* netdb.h:                               Host Names.
--* netinet/in.h <1>:                      Byte Order.
--* netinet/in.h <2>:                      Ports.
--* netinet/in.h <3>:                      Host Address Data Type.
--* netinet/in.h:                          Internet Address Format.
--* obstack.h:                             Creating Obstacks.
--* printf.h <1>:                          Conversion Specifier Options.
--* printf.h:                              Registering New Conversions.
--* pwd.h <1>:                             User Data Structure.
--* pwd.h:                                 Reserved Names.
--* setjmp.h <1>:                          Non-Local Exits and Signals.
--* setjmp.h:                              Non-Local Details.
--* sh:                                    Running a Command.
--* signal.h <1>:                          BSD Signal Handling.
--* signal.h <2>:                          Checking for Pending Signals.
--* signal.h <3>:                          Process Signal Mask.
--* signal.h <4>:                          Signal Sets.
--* signal.h <5>:                          Signaling Another Process.
--* signal.h <6>:                          Signaling Yourself.
--* signal.h <7>:                          Flags for Sigaction.
--* signal.h <8>:                          Advanced Signal Handling.
--* signal.h <9>:                          Basic Signal Handling.
--* signal.h <10>:                         Standard Signals.
--* signal.h:                              Reserved Names.
--* stdarg.h <1>:                          Argument Macros.
--* stdarg.h:                              Receiving Arguments.
--* stddef.h <1>:                          Important Data Types.
--* stddef.h:                              Wide Char Intro.
--* stdio.h <1>:                           Who Logged In.
--* stdio.h <2>:                           Identifying the Terminal.
--* stdio.h <3>:                           Signal Messages.
--* stdio.h <4>:                           Temporary Files.
--* stdio.h <5>:                           Deleting Files.
--* stdio.h <6>:                           Descriptors and Streams.
--* stdio.h <7>:                           Streams and Cookies.
--* stdio.h <8>:                           String Streams.
--* stdio.h <9>:                           Controlling Buffering.
--* stdio.h <10>:                          Flushing Buffers.
--* stdio.h <11>:                          Portable Positioning.
--* stdio.h <12>:                          File Positioning.
--* stdio.h <13>:                          EOF and Errors.
--* stdio.h <14>:                          Formatted Input Functions.
--* stdio.h <15>:                          Variable Arguments Output.
--* stdio.h <16>:                          Formatted Output Functions.
--* stdio.h <17>:                          Block Input/Output.
--* stdio.h <18>:                          Character Input.
--* stdio.h <19>:                          Simple Output.
--* stdio.h <20>:                          Opening Streams.
--* stdio.h <21>:                          Standard Streams.
--* stdio.h:                               Streams.
--* stdlib.h <1>:                          Running a Command.
--* stdlib.h <2>:                          Aborting a Program.
--* stdlib.h <3>:                          Exit Status.
--* stdlib.h <4>:                          Environment Access.
--* stdlib.h <5>:                          Converting One Char.
--* stdlib.h <6>:                          Length of Char.
--* stdlib.h <7>:                          Wide String Conversion.
--* stdlib.h <8>:                          Multibyte Char Intro.
--* stdlib.h <9>:                          Array Sort Function.
--* stdlib.h <10>:                         Array Search Function.
--* stdlib.h <11>:                         Parsing of Floats.
--* stdlib.h <12>:                         Parsing of Integers.
--* stdlib.h <13>:                         Integer Division.
--* stdlib.h <14>:                         Absolute Value.
--* stdlib.h <15>:                         BSD Random.
--* stdlib.h <16>:                         ISO Random.
--* stdlib.h <17>:                         Variable Size Automatic.
--* stdlib.h <18>:                         Aligned Memory Blocks.
--* stdlib.h <19>:                         Allocating Cleared Space.
--* stdlib.h <20>:                         Changing Block Size.
--* stdlib.h <21>:                         Freeing after Malloc.
--* stdlib.h:                              Basic Allocation.
--* string.h <1>:                          Signal Messages.
--* string.h <2>:                          Finding Tokens in a String.
--* string.h <3>:                          Search Functions.
--* string.h <4>:                          Collation Functions.
--* string.h <5>:                          String/Array Comparison.
--* string.h <6>:                          Copying and Concatenation.
--* string.h:                              String Length.
--* sys/param.h:                           Host Identification.
--* sys/resource.h <1>:                    Priority.
--* sys/resource.h <2>:                    Limits on Resources.
--* sys/resource.h:                        Resource Usage.
--* sys/socket.h <1>:                      Socket-Level Options.
--* sys/socket.h <2>:                      Socket Option Functions.
--* sys/socket.h <3>:                      Sending Datagrams.
--* sys/socket.h <4>:                      Socket Data Options.
--* sys/socket.h <5>:                      Receiving Data.
--* sys/socket.h <6>:                      Sending Data.
--* sys/socket.h <7>:                      Socket Pairs.
--* sys/socket.h <8>:                      Closing a Socket.
--* sys/socket.h <9>:                      Creating a Socket.
--* sys/socket.h <10>:                     Internet Namespace.
--* sys/socket.h <11>:                     File Namespace Details.
--* sys/socket.h <12>:                     Reading Address.
--* sys/socket.h <13>:                     Setting Address.
--* sys/socket.h <14>:                     Address Formats.
--* sys/socket.h:                          Communication Styles.
--* sys/stat.h <1>:                        FIFO Special Files.
--* sys/stat.h <2>:                        Making Special Files.
--* sys/stat.h <3>:                        Setting Permissions.
--* sys/stat.h <4>:                        Permission Bits.
--* sys/stat.h <5>:                        Testing File Type.
--* sys/stat.h <6>:                        Attribute Meanings.
--* sys/stat.h <7>:                        Creating Directories.
--* sys/stat.h:                            Reserved Names.
--* sys/time.h <1>:                        Setting an Alarm.
--* sys/time.h <2>:                        High-Resolution Calendar.
--* sys/time.h:                            File Times.
--* sys/times.h <1>:                       Detailed CPU Time.
--* sys/times.h:                           Reserved Names.
--* sys/types.h <1>:                       Setting Groups.
--* sys/types.h <2>:                       Setting User ID.
--* sys/types.h <3>:                       Reading Persona.
--* sys/types.h <4>:                       Terminal Access Functions.
--* sys/types.h <5>:                       Process Group Functions.
--* sys/types.h <6>:                       Process Identification.
--* sys/types.h:                           Waiting for I/O.
--* sys/un.h:                              File Namespace Details.
--* sys/utsname.h:                         Hardware/Software Type ID.
--* sys/wait.h <1>:                        BSD Wait Functions.
--* sys/wait.h <2>:                        Process Completion Status.
--* sys/wait.h:                            Process Completion.
--* termios.h <1>:                         Terminal Modes.
--* termios.h:                             Reserved Names.
--* time.h <1>:                            TZ Variable.
--* time.h <2>:                            Formatting Date and Time.
--* time.h <3>:                            Simple Calendar Time.
--* time.h <4>:                            Basic CPU Time.
--* time.h:                                File Times.
--* umask:                                 Setting Permissions.
--* unistd.h <1>:                          Options for Files.
--* unistd.h <2>:                          System Options.
--* unistd.h <3>:                          Host Identification.
--* unistd.h <4>:                          Who Logged In.
--* unistd.h <5>:                          Setting Groups.
--* unistd.h <6>:                          Setting User ID.
--* unistd.h <7>:                          Reading Persona.
--* unistd.h <8>:                          Terminal Access Functions.
--* unistd.h <9>:                          Process Group Functions.
--* unistd.h <10>:                         Executing a File.
--* unistd.h <11>:                         Creating a Process.
--* unistd.h <12>:                         Process Identification.
--* unistd.h <13>:                         Termination Internals.
--* unistd.h <14>:                         Parsing Options.
--* unistd.h <15>:                         Setting an Alarm.
--* unistd.h <16>:                         Is It a Terminal.
--* unistd.h <17>:                         Creating a Pipe.
--* unistd.h <18>:                         Testing File Access.
--* unistd.h <19>:                         File Owner.
--* unistd.h <20>:                         Deleting Files.
--* unistd.h <21>:                         Symbolic Links.
--* unistd.h <22>:                         Hard Links.
--* unistd.h <23>:                         Working Directory.
--* unistd.h <24>:                         Duplicating Descriptors.
--* unistd.h <25>:                         Descriptors and Streams.
--* unistd.h <26>:                         I/O Primitives.
--* unistd.h:                              Opening and Closing Files.
--* utime.h:                               File Times.
--* varargs.h:                             Old Varargs.
--* zoneinfo:                              TZ Variable.
--
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-4 
glibc-2.0.1/manual/libc.info-4
---- ../glibc-2.0.1/manual/libc.info-4  1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-4     1970-01-01 01:00:00.000000000 +0100
-@@ -1,1213 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Extra Fast Growing,  Next: Status of an Obstack,  
Prev: Growing Objects,  Up: Obstacks
--
--Extra Fast Growing Objects
----------------------------
--
--   The usual functions for growing objects incur overhead for checking
--whether there is room for the new growth in the current chunk.  If you
--are frequently constructing objects in small steps of growth, this
--overhead can be significant.
--
--   You can reduce the overhead by using special "fast growth" functions
--that grow the object without checking.  In order to have a robust
--program, you must do the checking yourself.  If you do this checking in
--the simplest way each time you are about to add data to the object, you
--have not saved anything, because that is what the ordinary growth
--functions do.  But if you can arrange to check less often, or check
--more efficiently, then you make the program faster.
--
--   The function `obstack_room' returns the amount of room available in
--the current chunk.  It is declared as follows:
--
-- - Function: int obstack_room (struct obstack *OBSTACK-PTR)
--     This returns the number of bytes that can be added safely to the
--     current growing object (or to an object about to be started) in
--     obstack OBSTACK using the fast growth functions.
--
--   While you know there is room, you can use these fast growth functions
--for adding data to a growing object:
--
-- - Function: void obstack_1grow_fast (struct obstack *OBSTACK-PTR, char
--          C)
--     The function `obstack_1grow_fast' adds one byte containing the
--     character C to the growing object in obstack OBSTACK-PTR.
--
-- - Function: void obstack_ptr_grow_fast (struct obstack *OBSTACK-PTR,
--          void *DATA)
--     The function `obstack_ptr_grow_fast' adds `sizeof (void *)' bytes
--     containing the value of DATA to the growing object in obstack
--     OBSTACK-PTR.
--
-- - Function: void obstack_int_grow_fast (struct obstack *OBSTACK-PTR,
--          int DATA)
--     The function `obstack_int_grow_fast' adds `sizeof (int)' bytes
--     containing the value of DATA to the growing object in obstack
--     OBSTACK-PTR.
--
-- - Function: void obstack_blank_fast (struct obstack *OBSTACK-PTR, int
--          SIZE)
--     The function `obstack_blank_fast' adds SIZE bytes to the growing
--     object in obstack OBSTACK-PTR without initializing them.
--
--   When you check for space using `obstack_room' and there is not
--enough room for what you want to add, the fast growth functions are not
--safe.  In this case, simply use the corresponding ordinary growth
--function instead.  Very soon this will copy the object to a new chunk;
--then there will be lots of room available again.
--
--   So, each time you use an ordinary growth function, check afterward
--for sufficient space using `obstack_room'.  Once the object is copied
--to a new chunk, there will be plenty of space again, so the program will
--start using the fast growth functions again.
--
--   Here is an example:
--
--     void
--     add_string (struct obstack *obstack, const char *ptr, int len)
--     {
--       while (len > 0)
--         {
--           int room = obstack_room (obstack);
--           if (room == 0)
--             {
--               /* Not enough room. Add one character slowly,
--                  which may copy to a new chunk and make room.  */
--               obstack_1grow (obstack, *ptr++);
--               len--;
--             }
--           else
--             {
--               if (room > len)
--                 room = len;
--               /* Add fast as much as we have room for. */
--               len -= room;
--               while (room-- > 0)
--                 obstack_1grow_fast (obstack, *ptr++);
--             }
--         }
--     }
--
--
--File: libc.info,  Node: Status of an Obstack,  Next: Obstacks Data Alignment, 
 Prev: Extra Fast Growing,  Up: Obstacks
--
--Status of an Obstack
----------------------
--
--   Here are functions that provide information on the current status of
--allocation in an obstack.  You can use them to learn about an object
--while still growing it.
--
-- - Function: void * obstack_base (struct obstack *OBSTACK-PTR)
--     This function returns the tentative address of the beginning of the
--     currently growing object in OBSTACK-PTR.  If you finish the object
--     immediately, it will have that address.  If you make it larger
--     first, it may outgrow the current chunk--then its address will
--     change!
--
--     If no object is growing, this value says where the next object you
--     allocate will start (once again assuming it fits in the current
--     chunk).
--
-- - Function: void * obstack_next_free (struct obstack *OBSTACK-PTR)
--     This function returns the address of the first free byte in the
--     current chunk of obstack OBSTACK-PTR.  This is the end of the
--     currently growing object.  If no object is growing,
--     `obstack_next_free' returns the same value as `obstack_base'.
--
-- - Function: int obstack_object_size (struct obstack *OBSTACK-PTR)
--     This function returns the size in bytes of the currently growing
--     object.  This is equivalent to
--
--          obstack_next_free (OBSTACK-PTR) - obstack_base (OBSTACK-PTR)
--
--
--File: libc.info,  Node: Obstacks Data Alignment,  Next: Obstack Chunks,  
Prev: Status of an Obstack,  Up: Obstacks
--
--Alignment of Data in Obstacks
-------------------------------
--
--   Each obstack has an "alignment boundary"; each object allocated in
--the obstack automatically starts on an address that is a multiple of the
--specified boundary.  By default, this boundary is 4 bytes.
--
--   To access an obstack's alignment boundary, use the macro
--`obstack_alignment_mask', whose function prototype looks like this:
--
-- - Macro: int obstack_alignment_mask (struct obstack *OBSTACK-PTR)
--     The value is a bit mask; a bit that is 1 indicates that the
--     corresponding bit in the address of an object should be 0.  The
--     mask value should be one less than a power of 2; the effect is
--     that all object addresses are multiples of that power of 2.  The
--     default value of the mask is 3, so that addresses are multiples of
--     4.  A mask value of 0 means an object can start on any multiple of
--     1 (that is, no alignment is required).
--
--     The expansion of the macro `obstack_alignment_mask' is an lvalue,
--     so you can alter the mask by assignment.  For example, this
--     statement:
--
--          obstack_alignment_mask (obstack_ptr) = 0;
--
--     has the effect of turning off alignment processing in the
--     specified obstack.
--
--   Note that a change in alignment mask does not take effect until
--*after* the next time an object is allocated or finished in the
--obstack.  If you are not growing an object, you can make the new
--alignment mask take effect immediately by calling `obstack_finish'.
--This will finish a zero-length object and then do proper alignment for
--the next object.
--
--
--File: libc.info,  Node: Obstack Chunks,  Next: Summary of Obstacks,  Prev: 
Obstacks Data Alignment,  Up: Obstacks
--
--Obstack Chunks
----------------
--
--   Obstacks work by allocating space for themselves in large chunks, and
--then parceling out space in the chunks to satisfy your requests.  Chunks
--are normally 4096 bytes long unless you specify a different chunk size.
--The chunk size includes 8 bytes of overhead that are not actually used
--for storing objects.  Regardless of the specified size, longer chunks
--will be allocated when necessary for long objects.
--
--   The obstack library allocates chunks by calling the function
--`obstack_chunk_alloc', which you must define.  When a chunk is no
--longer needed because you have freed all the objects in it, the obstack
--library frees the chunk by calling `obstack_chunk_free', which you must
--also define.
--
--   These two must be defined (as macros) or declared (as functions) in
--each source file that uses `obstack_init' (*note Creating Obstacks::.).
--Most often they are defined as macros like this:
--
--     #define obstack_chunk_alloc xmalloc
--     #define obstack_chunk_free free
--
--   Note that these are simple macros (no arguments).  Macro definitions
--with arguments will not work!  It is necessary that
--`obstack_chunk_alloc' or `obstack_chunk_free', alone, expand into a
--function name if it is not itself a function name.
--
--   If you allocate chunks with `malloc', the chunk size should be a
--power of 2.  The default chunk size, 4096, was chosen because it is long
--enough to satisfy many typical requests on the obstack yet short enough
--not to waste too much memory in the portion of the last chunk not yet
--used.
--
-- - Macro: int obstack_chunk_size (struct obstack *OBSTACK-PTR)
--     This returns the chunk size of the given obstack.
--
--   Since this macro expands to an lvalue, you can specify a new chunk
--size by assigning it a new value.  Doing so does not affect the chunks
--already allocated, but will change the size of chunks allocated for
--that particular obstack in the future.  It is unlikely to be useful to
--make the chunk size smaller, but making it larger might improve
--efficiency if you are allocating many objects whose size is comparable
--to the chunk size.  Here is how to do so cleanly:
--
--     if (obstack_chunk_size (obstack_ptr) < NEW-CHUNK-SIZE)
--       obstack_chunk_size (obstack_ptr) = NEW-CHUNK-SIZE;
--
--
--File: libc.info,  Node: Summary of Obstacks,  Prev: Obstack Chunks,  Up: 
Obstacks
--
--Summary of Obstack Functions
------------------------------
--
--   Here is a summary of all the functions associated with obstacks.
--Each takes the address of an obstack (`struct obstack *') as its first
--argument.
--
--`void obstack_init (struct obstack *OBSTACK-PTR)'
--     Initialize use of an obstack.  *Note Creating Obstacks::.
--
--`void *obstack_alloc (struct obstack *OBSTACK-PTR, int SIZE)'
--     Allocate an object of SIZE uninitialized bytes.  *Note Allocation
--     in an Obstack::.
--
--`void *obstack_copy (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
--     Allocate an object of SIZE bytes, with contents copied from
--     ADDRESS.  *Note Allocation in an Obstack::.
--
--`void *obstack_copy0 (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
--     Allocate an object of SIZE+1 bytes, with SIZE of them copied from
--     ADDRESS, followed by a null character at the end.  *Note
--     Allocation in an Obstack::.
--
--`void obstack_free (struct obstack *OBSTACK-PTR, void *OBJECT)'
--     Free OBJECT (and everything allocated in the specified obstack
--     more recently than OBJECT).  *Note Freeing Obstack Objects::.
--
--`void obstack_blank (struct obstack *OBSTACK-PTR, int SIZE)'
--     Add SIZE uninitialized bytes to a growing object.  *Note Growing
--     Objects::.
--
--`void obstack_grow (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
--     Add SIZE bytes, copied from ADDRESS, to a growing object.  *Note
--     Growing Objects::.
--
--`void obstack_grow0 (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
--     Add SIZE bytes, copied from ADDRESS, to a growing object, and then
--     add another byte containing a null character.  *Note Growing
--     Objects::.
--
--`void obstack_1grow (struct obstack *OBSTACK-PTR, char DATA-CHAR)'
--     Add one byte containing DATA-CHAR to a growing object.  *Note
--     Growing Objects::.
--
--`void *obstack_finish (struct obstack *OBSTACK-PTR)'
--     Finalize the object that is growing and return its permanent
--     address.  *Note Growing Objects::.
--
--`int obstack_object_size (struct obstack *OBSTACK-PTR)'
--     Get the current size of the currently growing object.  *Note
--     Growing Objects::.
--
--`void obstack_blank_fast (struct obstack *OBSTACK-PTR, int SIZE)'
--     Add SIZE uninitialized bytes to a growing object without checking
--     that there is enough room.  *Note Extra Fast Growing::.
--
--`void obstack_1grow_fast (struct obstack *OBSTACK-PTR, char DATA-CHAR)'
--     Add one byte containing DATA-CHAR to a growing object without
--     checking that there is enough room.  *Note Extra Fast Growing::.
--
--`int obstack_room (struct obstack *OBSTACK-PTR)'
--     Get the amount of room now available for growing the current
--     object.  *Note Extra Fast Growing::.
--
--`int obstack_alignment_mask (struct obstack *OBSTACK-PTR)'
--     The mask used for aligning the beginning of an object.  This is an
--     lvalue.  *Note Obstacks Data Alignment::.
--
--`int obstack_chunk_size (struct obstack *OBSTACK-PTR)'
--     The size for allocating chunks.  This is an lvalue.  *Note Obstack
--     Chunks::.
--
--`void *obstack_base (struct obstack *OBSTACK-PTR)'
--     Tentative starting address of the currently growing object.  *Note
--     Status of an Obstack::.
--
--`void *obstack_next_free (struct obstack *OBSTACK-PTR)'
--     Address just after the end of the currently growing object.  *Note
--     Status of an Obstack::.
--
--
--File: libc.info,  Node: Variable Size Automatic,  Next: Relocating Allocator, 
 Prev: Obstacks,  Up: Memory Allocation
--
--Automatic Storage with Variable Size
--====================================
--
--   The function `alloca' supports a kind of half-dynamic allocation in
--which blocks are allocated dynamically but freed automatically.
--
--   Allocating a block with `alloca' is an explicit action; you can
--allocate as many blocks as you wish, and compute the size at run time.
--But all the blocks are freed when you exit the function that `alloca'
--was called from, just as if they were automatic variables declared in
--that function.  There is no way to free the space explicitly.
--
--   The prototype for `alloca' is in `stdlib.h'.  This function is a BSD
--extension.
--
-- - Function: void * alloca (size_t SIZE);
--     The return value of `alloca' is the address of a block of SIZE
--     bytes of storage, allocated in the stack frame of the calling
--     function.
--
--   Do not use `alloca' inside the arguments of a function call--you
--will get unpredictable results, because the stack space for the
--`alloca' would appear on the stack in the middle of the space for the
--function arguments.  An example of what to avoid is `foo (x, alloca
--(4), y)'.
--
--* Menu:
--
--* Alloca Example::              Example of using `alloca'.
--* Advantages of Alloca::        Reasons to use `alloca'.
--* Disadvantages of Alloca::     Reasons to avoid `alloca'.
--* GNU C Variable-Size Arrays::  Only in GNU C, here is an alternative
--                               method of allocating dynamically and
--                               freeing automatically.
--
--
--File: libc.info,  Node: Alloca Example,  Next: Advantages of Alloca,  Up: 
Variable Size Automatic
--
--`alloca' Example
------------------
--
--   As an example of use of `alloca', here is a function that opens a
--file name made from concatenating two argument strings, and returns a
--file descriptor or minus one signifying failure:
--
--     int
--     open2 (char *str1, char *str2, int flags, int mode)
--     {
--       char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
--       stpcpy (stpcpy (name, str1), str2);
--       return open (name, flags, mode);
--     }
--
--Here is how you would get the same results with `malloc' and `free':
--
--     int
--     open2 (char *str1, char *str2, int flags, int mode)
--     {
--       char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
--       int desc;
--       if (name == 0)
--         fatal ("virtual memory exceeded");
--       stpcpy (stpcpy (name, str1), str2);
--       desc = open (name, flags, mode);
--       free (name);
--       return desc;
--     }
--
--   As you can see, it is simpler with `alloca'.  But `alloca' has
--other, more important advantages, and some disadvantages.
--
--
--File: libc.info,  Node: Advantages of Alloca,  Next: Disadvantages of Alloca, 
 Prev: Alloca Example,  Up: Variable Size Automatic
--
--Advantages of `alloca'
------------------------
--
--   Here are the reasons why `alloca' may be preferable to `malloc':
--
--   * Using `alloca' wastes very little space and is very fast.  (It is
--     open-coded by the GNU C compiler.)
--
--   * Since `alloca' does not have separate pools for different sizes of
--     block, space used for any size block can be reused for any other
--     size.  `alloca' does not cause storage fragmentation.
--
--   * Nonlocal exits done with `longjmp' (*note Non-Local Exits::.)
--     automatically free the space allocated with `alloca' when they exit
--     through the function that called `alloca'.  This is the most
--     important reason to use `alloca'.
--
--     To illustrate this, suppose you have a function
--     `open_or_report_error' which returns a descriptor, like `open', if
--     it succeeds, but does not return to its caller if it fails.  If
--     the file cannot be opened, it prints an error message and jumps
--     out to the command level of your program using `longjmp'.  Let's
--     change `open2' (*note Alloca Example::.) to use this subroutine:
--
--          int
--          open2 (char *str1, char *str2, int flags, int mode)
--          {
--            char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
--            stpcpy (stpcpy (name, str1), str2);
--            return open_or_report_error (name, flags, mode);
--          }
--
--     Because of the way `alloca' works, the storage it allocates is
--     freed even when an error occurs, with no special effort required.
--
--     By contrast, the previous definition of `open2' (which uses
--     `malloc' and `free') would develop a storage leak if it were
--     changed in this way.  Even if you are willing to make more changes
--     to fix it, there is no easy way to do so.
--
--
--File: libc.info,  Node: Disadvantages of Alloca,  Next: GNU C Variable-Size 
Arrays,  Prev: Advantages of Alloca,  Up: Variable Size Automatic
--
--Disadvantages of `alloca'
---------------------------
--
--   These are the disadvantages of `alloca' in comparison with `malloc':
--
--   * If you try to allocate more storage than the machine can provide,
--     you don't get a clean error message.  Instead you get a fatal
--     signal like the one you would get from an infinite recursion;
--     probably a segmentation violation (*note Program Error Signals::.).
--
--   * Some non-GNU systems fail to support `alloca', so it is less
--     portable.  However, a slower emulation of `alloca' written in C is
--     available for use on systems with this deficiency.
--
--
--File: libc.info,  Node: GNU C Variable-Size Arrays,  Prev: Disadvantages of 
Alloca,  Up: Variable Size Automatic
--
--GNU C Variable-Size Arrays
----------------------------
--
--   In GNU C, you can replace most uses of `alloca' with an array of
--variable size.  Here is how `open2' would look then:
--
--     int open2 (char *str1, char *str2, int flags, int mode)
--     {
--       char name[strlen (str1) + strlen (str2) + 1];
--       stpcpy (stpcpy (name, str1), str2);
--       return open (name, flags, mode);
--     }
--
--   But `alloca' is not always equivalent to a variable-sized array, for
--several reasons:
--
--   * A variable size array's space is freed at the end of the scope of
--     the name of the array.  The space allocated with `alloca' remains
--     until the end of the function.
--
--   * It is possible to use `alloca' within a loop, allocating an
--     additional block on each iteration.  This is impossible with
--     variable-sized arrays.
--
--   *Note:* If you mix use of `alloca' and variable-sized arrays within
--one function, exiting a scope in which a variable-sized array was
--declared frees all blocks allocated with `alloca' during the execution
--of that scope.
--
--
--File: libc.info,  Node: Relocating Allocator,  Next: Memory Warnings,  Prev: 
Variable Size Automatic,  Up: Memory Allocation
--
--Relocating Allocator
--====================
--
--   Any system of dynamic memory allocation has overhead: the amount of
--space it uses is more than the amount the program asks for.  The
--"relocating memory allocator" achieves very low overhead by moving
--blocks in memory as necessary, on its own initiative.
--
--* Menu:
--
--* Relocator Concepts::                How to understand relocating allocation.
--* Using Relocator::           Functions for relocating allocation.
--
--
--File: libc.info,  Node: Relocator Concepts,  Next: Using Relocator,  Up: 
Relocating Allocator
--
--Concepts of Relocating Allocation
-----------------------------------
--
--   The "relocating memory allocator" achieves very low overhead by
--moving blocks in memory as necessary, on its own initiative.
--
--   When you allocate a block with `malloc', the address of the block
--never changes unless you use `realloc' to change its size.  Thus, you
--can safely store the address in various places, temporarily or
--permanently, as you like.  This is not safe when you use the relocating
--memory allocator, because any and all relocatable blocks can move
--whenever you allocate memory in any fashion.  Even calling `malloc' or
--`realloc' can move the relocatable blocks.
--
--   For each relocatable block, you must make a "handle"--a pointer
--object in memory, designated to store the address of that block.  The
--relocating allocator knows where each block's handle is, and updates the
--address stored there whenever it moves the block, so that the handle
--always points to the block.  Each time you access the contents of the
--block, you should fetch its address anew from the handle.
--
--   To call any of the relocating allocator functions from a signal
--handler is almost certainly incorrect, because the signal could happen
--at any time and relocate all the blocks.  The only way to make this
--safe is to block the signal around any access to the contents of any
--relocatable block--not a convenient mode of operation.  *Note
--Nonreentrancy::.
--
--
--File: libc.info,  Node: Using Relocator,  Prev: Relocator Concepts,  Up: 
Relocating Allocator
--
--Allocating and Freeing Relocatable Blocks
-------------------------------------------
--
--   In the descriptions below, HANDLEPTR designates the address of the
--handle.  All the functions are declared in `malloc.h'; all are GNU
--extensions.
--
-- - Function: void * r_alloc (void **HANDLEPTR, size_t SIZE)
--     This function allocates a relocatable block of size SIZE.  It
--     stores the block's address in `*HANDLEPTR' and returns a non-null
--     pointer to indicate success.
--
--     If `r_alloc' can't get the space needed, it stores a null pointer
--     in `*HANDLEPTR', and returns a null pointer.
--
-- - Function: void r_alloc_free (void **HANDLEPTR)
--     This function is the way to free a relocatable block.  It frees the
--     block that `*HANDLEPTR' points to, and stores a null pointer in
--     `*HANDLEPTR' to show it doesn't point to an allocated block any
--     more.
--
-- - Function: void * r_re_alloc (void **HANDLEPTR, size_t SIZE)
--     The function `r_re_alloc' adjusts the size of the block that
--     `*HANDLEPTR' points to, making it SIZE bytes long.  It stores the
--     address of the resized block in `*HANDLEPTR' and returns a
--     non-null pointer to indicate success.
--
--     If enough memory is not available, this function returns a null
--     pointer and does not modify `*HANDLEPTR'.
--
--
--File: libc.info,  Node: Memory Warnings,  Prev: Relocating Allocator,  Up: 
Memory Allocation
--
--Memory Usage Warnings
--=====================
--
--   You can ask for warnings as the program approaches running out of
--memory space, by calling `memory_warnings'.  This tells `malloc' to
--check memory usage every time it asks for more memory from the operating
--system.  This is a GNU extension declared in `malloc.h'.
--
-- - Function: void memory_warnings (void *START, void (*WARN-FUNC)
--          (const char *))
--     Call this function to request warnings for nearing exhaustion of
--     virtual memory.
--
--     The argument START says where data space begins, in memory.  The
--     allocator compares this against the last address used and against
--     the limit of data space, to determine the fraction of available
--     memory in use.  If you supply zero for START, then a default value
--     is used which is right in most circumstances.
--
--     For WARN-FUNC, supply a function that `malloc' can call to warn
--     you.  It is called with a string (a warning message) as argument.
--     Normally it ought to display the string for the user to read.
--
--   The warnings come when memory becomes 75% full, when it becomes 85%
--full, and when it becomes 95% full.  Above 95% you get another warning
--each time memory usage increases.
--
--
--File: libc.info,  Node: Character Handling,  Next: String and Array 
Utilities,  Prev: Memory Allocation,  Up: Top
--
--Character Handling
--******************
--
--   Programs that work with characters and strings often need to
--classify a character--is it alphabetic, is it a digit, is it
--whitespace, and so on--and perform case conversion operations on
--characters.  The functions in the header file `ctype.h' are provided
--for this purpose.
--
--   Since the choice of locale and character set can alter the
--classifications of particular character codes, all of these functions
--are affected by the current locale.  (More precisely, they are affected
--by the locale currently selected for character classification--the
--`LC_CTYPE' category; see *Note Locale Categories::.)
--
--* Menu:
--
--* Classification of Characters::   Testing whether characters are
--                                  letters, digits, punctuation, etc.
--
--* Case Conversion::                Case mapping, and the like.
--
--
--File: libc.info,  Node: Classification of Characters,  Next: Case Conversion, 
 Up: Character Handling
--
--Classification of Characters
--============================
--
--   This section explains the library functions for classifying
--characters.  For example, `isalpha' is the function to test for an
--alphabetic character.  It takes one argument, the character to test,
--and returns a nonzero integer if the character is alphabetic, and zero
--otherwise.  You would use it like this:
--
--     if (isalpha (c))
--       printf ("The character `%c' is alphabetic.\n", c);
--
--   Each of the functions in this section tests for membership in a
--particular class of characters; each has a name starting with `is'.
--Each of them takes one argument, which is a character to test, and
--returns an `int' which is treated as a boolean value.  The character
--argument is passed as an `int', and it may be the constant value `EOF'
--instead of a real character.
--
--   The attributes of any given character can vary between locales.
--*Note Locales::, for more information on locales.
--
--   These functions are declared in the header file `ctype.h'.
--
-- - Function: int islower (int C)
--     Returns true if C is a lower-case letter.
--
-- - Function: int isupper (int C)
--     Returns true if C is an upper-case letter.
--
-- - Function: int isalpha (int C)
--     Returns true if C is an alphabetic character (a letter).  If
--     `islower' or `isupper' is true of a character, then `isalpha' is
--     also true.
--
--     In some locales, there may be additional characters for which
--     `isalpha' is true-letters which are neither upper case nor lower
--     case.  But in the standard `"C"' locale, there are no such
--     additional characters.
--
-- - Function: int isdigit (int C)
--     Returns true if C is a decimal digit (`0' through `9').
--
-- - Function: int isalnum (int C)
--     Returns true if C is an alphanumeric character (a letter or
--     number); in other words, if either `isalpha' or `isdigit' is true
--     of a character, then `isalnum' is also true.
--
-- - Function: int isxdigit (int C)
--     Returns true if C is a hexadecimal digit.  Hexadecimal digits
--     include the normal decimal digits `0' through `9' and the letters
--     `A' through `F' and `a' through `f'.
--
-- - Function: int ispunct (int C)
--     Returns true if C is a punctuation character.  This means any
--     printing character that is not alphanumeric or a space character.
--
-- - Function: int isspace (int C)
--     Returns true if C is a "whitespace" character.  In the standard
--     `"C"' locale, `isspace' returns true for only the standard
--     whitespace characters:
--
--    `' ''
--          space
--
--    `'\f''
--          formfeed
--
--    `'\n''
--          newline
--
--    `'\r''
--          carriage return
--
--    `'\t''
--          horizontal tab
--
--    `'\v''
--          vertical tab
--
-- - Function: int isblank (int C)
--     Returns true if C is a blank character; that is, a space or a tab.
--     This function is a GNU extension.
--
-- - Function: int isgraph (int C)
--     Returns true if C is a graphic character; that is, a character
--     that has a glyph associated with it.  The whitespace characters
--     are not considered graphic.
--
-- - Function: int isprint (int C)
--     Returns true if C is a printing character.  Printing characters
--     include all the graphic characters, plus the space (` ') character.
--
-- - Function: int iscntrl (int C)
--     Returns true if C is a control character (that is, a character that
--     is not a printing character).
--
-- - Function: int isascii (int C)
--     Returns true if C is a 7-bit `unsigned char' value that fits into
--     the US/UK ASCII character set.  This function is a BSD extension
--     and is also an SVID extension.
--
--
--File: libc.info,  Node: Case Conversion,  Prev: Classification of Characters, 
 Up: Character Handling
--
--Case Conversion
--===============
--
--   This section explains the library functions for performing
--conversions such as case mappings on characters.  For example, `toupper'
--converts any character to upper case if possible.  If the character
--can't be converted, `toupper' returns it unchanged.
--
--   These functions take one argument of type `int', which is the
--character to convert, and return the converted character as an `int'.
--If the conversion is not applicable to the argument given, the argument
--is returned unchanged.
--
--   *Compatibility Note:* In pre-ISO C dialects, instead of returning
--the argument unchanged, these functions may fail when the argument is
--not suitable for the conversion.  Thus for portability, you may need to
--write `islower(c) ? toupper(c) : c' rather than just `toupper(c)'.
--
--   These functions are declared in the header file `ctype.h'.
--
-- - Function: int tolower (int C)
--     If C is an upper-case letter, `tolower' returns the corresponding
--     lower-case letter.  If C is not an upper-case letter, C is
--     returned unchanged.
--
-- - Function: int toupper (int C)
--     If C is a lower-case letter, `tolower' returns the corresponding
--     upper-case letter.  Otherwise C is returned unchanged.
--
-- - Function: int toascii (int C)
--     This function converts C to a 7-bit `unsigned char' value that
--     fits into the US/UK ASCII character set, by clearing the high-order
--     bits.  This function is a BSD extension and is also an SVID
--     extension.
--
-- - Function: int _tolower (int C)
--     This is identical to `tolower', and is provided for compatibility
--     with the SVID.  *Note SVID::.
--
-- - Function: int _toupper (int C)
--     This is identical to `toupper', and is provided for compatibility
--     with the SVID.
--
--
--File: libc.info,  Node: String and Array Utilities,  Next: Extended 
Characters,  Prev: Character Handling,  Up: Top
--
--String and Array Utilities
--**************************
--
--   Operations on strings (or arrays of characters) are an important
--part of many programs.  The GNU C library provides an extensive set of
--string utility functions, including functions for copying,
--concatenating, comparing, and searching strings.  Many of these
--functions can also operate on arbitrary regions of storage; for
--example, the `memcpy' function can be used to copy the contents of any
--kind of array.
--
--   It's fairly common for beginning C programmers to "reinvent the
--wheel" by duplicating this functionality in their own code, but it pays
--to become familiar with the library functions and to make use of them,
--since this offers benefits in maintenance, efficiency, and portability.
--
--   For instance, you could easily compare one string to another in two
--lines of C code, but if you use the built-in `strcmp' function, you're
--less likely to make a mistake.  And, since these library functions are
--typically highly optimized, your program may run faster too.
--
--* Menu:
--
--* Representation of Strings::   Introduction to basic concepts.
--* String/Array Conventions::    Whether to use a string function or an
--                               arbitrary array function.
--* String Length::               Determining the length of a string.
--* Copying and Concatenation::   Functions to copy the contents of strings
--                               and arrays.
--* String/Array Comparison::     Functions for byte-wise and character-wise
--                               comparison.
--* Collation Functions::         Functions for collating strings.
--* Search Functions::            Searching for a specific element or substring.
--* Finding Tokens in a String::  Splitting a string into tokens by looking
--                               for delimiters.
--
--
--File: libc.info,  Node: Representation of Strings,  Next: String/Array 
Conventions,  Up: String and Array Utilities
--
--Representation of Strings
--=========================
--
--   This section is a quick summary of string concepts for beginning C
--programmers.  It describes how character strings are represented in C
--and some common pitfalls.  If you are already familiar with this
--material, you can skip this section.
--
--   A "string" is an array of `char' objects.  But string-valued
--variables are usually declared to be pointers of type `char *'.  Such
--variables do not include space for the text of a string; that has to be
--stored somewhere else--in an array variable, a string constant, or
--dynamically allocated memory (*note Memory Allocation::.).  It's up to
--you to store the address of the chosen memory space into the pointer
--variable.  Alternatively you can store a "null pointer" in the pointer
--variable.  The null pointer does not point anywhere, so attempting to
--reference the string it points to gets an error.
--
--   By convention, a "null character", `'\0'', marks the end of a
--string.  For example, in testing to see whether the `char *' variable P
--points to a null character marking the end of a string, you can write
--`!*P' or `*P == '\0''.
--
--   A null character is quite different conceptually from a null pointer,
--although both are represented by the integer `0'.
--
--   "String literals" appear in C program source as strings of
--characters between double-quote characters (`"').  In ISO C, string
--literals can also be formed by "string concatenation": `"a" "b"' is the
--same as `"ab"'.  Modification of string literals is not allowed by the
--GNU C compiler, because literals are placed in read-only storage.
--
--   Character arrays that are declared `const' cannot be modified
--either.  It's generally good style to declare non-modifiable string
--pointers to be of type `const char *', since this often allows the C
--compiler to detect accidental modifications as well as providing some
--amount of documentation about what your program intends to do with the
--string.
--
--   The amount of memory allocated for the character array may extend
--past the null character that normally marks the end of the string.  In
--this document, the term "allocation size" is always used to refer to the
--total amount of memory allocated for the string, while the term
--"length" refers to the number of characters up to (but not including)
--the terminating null character.
--
--   A notorious source of program bugs is trying to put more characters
--in a string than fit in its allocated size.  When writing code that
--extends strings or moves characters into a pre-allocated array, you
--should be very careful to keep track of the length of the text and make
--explicit checks for overflowing the array.  Many of the library
--functions *do not* do this for you!  Remember also that you need to
--allocate an extra byte to hold the null character that marks the end of
--the string.
--
--
--File: libc.info,  Node: String/Array Conventions,  Next: String Length,  
Prev: Representation of Strings,  Up: String and Array Utilities
--
--String and Array Conventions
--============================
--
--   This chapter describes both functions that work on arbitrary arrays
--or blocks of memory, and functions that are specific to null-terminated
--arrays of characters.
--
--   Functions that operate on arbitrary blocks of memory have names
--beginning with `mem' (such as `memcpy') and invariably take an argument
--which specifies the size (in bytes) of the block of memory to operate
--on.  The array arguments and return values for these functions have
--type `void *', and as a matter of style, the elements of these arrays
--are referred to as "bytes".  You can pass any kind of pointer to these
--functions, and the `sizeof' operator is useful in computing the value
--for the size argument.
--
--   In contrast, functions that operate specifically on strings have
--names beginning with `str' (such as `strcpy') and look for a null
--character to terminate the string instead of requiring an explicit size
--argument to be passed.  (Some of these functions accept a specified
--maximum length, but they also check for premature termination with a
--null character.)  The array arguments and return values for these
--functions have type `char *', and the array elements are referred to as
--"characters".
--
--   In many cases, there are both `mem' and `str' versions of a
--function.  The one that is more appropriate to use depends on the exact
--situation.  When your program is manipulating arbitrary arrays or
--blocks of storage, then you should always use the `mem' functions.  On
--the other hand, when you are manipulating null-terminated strings it is
--usually more convenient to use the `str' functions, unless you already
--know the length of the string in advance.
--
--
--File: libc.info,  Node: String Length,  Next: Copying and Concatenation,  
Prev: String/Array Conventions,  Up: String and Array Utilities
--
--String Length
--=============
--
--   You can get the length of a string using the `strlen' function.
--This function is declared in the header file `string.h'.
--
-- - Function: size_t strlen (const char *S)
--     The `strlen' function returns the length of the null-terminated
--     string S.  (In other words, it returns the offset of the
--     terminating null character within the array.)
--
--     For example,
--          strlen ("hello, world")
--              => 12
--
--     When applied to a character array, the `strlen' function returns
--     the length of the string stored there, not its allocation size.
--     You can get the allocation size of the character array that holds
--     a string using the `sizeof' operator:
--
--          char string[32] = "hello, world";
--          sizeof (string)
--              => 32
--          strlen (string)
--              => 12
--
--
--File: libc.info,  Node: Copying and Concatenation,  Next: String/Array 
Comparison,  Prev: String Length,  Up: String and Array Utilities
--
--Copying and Concatenation
--=========================
--
--   You can use the functions described in this section to copy the
--contents of strings and arrays, or to append the contents of one string
--to another.  These functions are declared in the header file `string.h'.
--
--   A helpful way to remember the ordering of the arguments to the
--functions in this section is that it corresponds to an assignment
--expression, with the destination array specified to the left of the
--source array.  All of these functions return the address of the
--destination array.
--
--   Most of these functions do not work properly if the source and
--destination arrays overlap.  For example, if the beginning of the
--destination array overlaps the end of the source array, the original
--contents of that part of the source array may get overwritten before it
--is copied.  Even worse, in the case of the string functions, the null
--character marking the end of the string may be lost, and the copy
--function might get stuck in a loop trashing all the memory allocated to
--your program.
--
--   All functions that have problems copying between overlapping arrays
--are explicitly identified in this manual.  In addition to functions in
--this section, there are a few others like `sprintf' (*note Formatted
--Output Functions::.) and `scanf' (*note Formatted Input Functions::.).
--
-- - Function: void * memcpy (void *TO, const void *FROM, size_t SIZE)
--     The `memcpy' function copies SIZE bytes from the object beginning
--     at FROM into the object beginning at TO.  The behavior of this
--     function is undefined if the two arrays TO and FROM overlap; use
--     `memmove' instead if overlapping is possible.
--
--     The value returned by `memcpy' is the value of TO.
--
--     Here is an example of how you might use `memcpy' to copy the
--     contents of an array:
--
--          struct foo *oldarray, *newarray;
--          int arraysize;
--          ...
--          memcpy (new, old, arraysize * sizeof (struct foo));
--
-- - Function: void * memmove (void *TO, const void *FROM, size_t SIZE)
--     `memmove' copies the SIZE bytes at FROM into the SIZE bytes at TO,
--     even if those two blocks of space overlap.  In the case of
--     overlap, `memmove' is careful to copy the original values of the
--     bytes in the block at FROM, including those bytes which also
--     belong to the block at TO.
--
-- - Function: void * memccpy (void *TO, const void *FROM, int C, size_t
--          SIZE)
--     This function copies no more than SIZE bytes from FROM to TO,
--     stopping if a byte matching C is found.  The return value is a
--     pointer into TO one byte past where C was copied, or a null
--     pointer if no byte matching C appeared in the first SIZE bytes of
--     FROM.
--
-- - Function: void * memset (void *BLOCK, int C, size_t SIZE)
--     This function copies the value of C (converted to an `unsigned
--     char') into each of the first SIZE bytes of the object beginning
--     at BLOCK.  It returns the value of BLOCK.
--
-- - Function: char * strcpy (char *TO, const char *FROM)
--     This copies characters from the string FROM (up to and including
--     the terminating null character) into the string TO.  Like
--     `memcpy', this function has undefined results if the strings
--     overlap.  The return value is the value of TO.
--
-- - Function: char * strncpy (char *TO, const char *FROM, size_t SIZE)
--     This function is similar to `strcpy' but always copies exactly
--     SIZE characters into TO.
--
--     If the length of FROM is more than SIZE, then `strncpy' copies
--     just the first SIZE characters.  Note that in this case there is
--     no null terminator written into TO.
--
--     If the length of FROM is less than SIZE, then `strncpy' copies all
--     of FROM, followed by enough null characters to add up to SIZE
--     characters in all.  This behavior is rarely useful, but it is
--     specified by the ISO C standard.
--
--     The behavior of `strncpy' is undefined if the strings overlap.
--
--     Using `strncpy' as opposed to `strcpy' is a way to avoid bugs
--     relating to writing past the end of the allocated space for TO.
--     However, it can also make your program much slower in one common
--     case: copying a string which is probably small into a potentially
--     large buffer.  In this case, SIZE may be large, and when it is,
--     `strncpy' will waste a considerable amount of time copying null
--     characters.
--
-- - Function: char * strdup (const char *S)
--     This function copies the null-terminated string S into a newly
--     allocated string.  The string is allocated using `malloc'; see
--     *Note Unconstrained Allocation::.  If `malloc' cannot allocate
--     space for the new string, `strdup' returns a null pointer.
--     Otherwise it returns a pointer to the new string.
--
-- - Function: char * strndup (const char *S, size_t SIZE)
--     This function is similar to `strdup' but always copies at most
--     SIZE characters into the newly allocated string.
--
--     If the length of S is more than SIZE, then `strndup' copies just
--     the first SIZE characters and adds a closing null terminator.
--     Otherwise all characters are copied and the string is terminated.
--
--     This function is different to `strncpy' in that it always
--     terminates the destination string.
--
-- - Function: char * stpcpy (char *TO, const char *FROM)
--     This function is like `strcpy', except that it returns a pointer to
--     the end of the string TO (that is, the address of the terminating
--     null character) rather than the beginning.
--
--     For example, this program uses `stpcpy' to concatenate `foo' and
--     `bar' to produce `foobar', which it then prints.
--
--          #include <string.h>
--          #include <stdio.h>
--          
--          int
--          main (void)
--          {
--            char buffer[10];
--            char *to = buffer;
--            to = stpcpy (to, "foo");
--            to = stpcpy (to, "bar");
--            puts (buffer);
--            return 0;
--          }
--
--     This function is not part of the ISO or POSIX standards, and is not
--     customary on Unix systems, but we did not invent it either.
--     Perhaps it comes from MS-DOG.
--
--     Its behavior is undefined if the strings overlap.
--
-- - Function: char * stpncpy (char *TO, const char *FROM, size_t SIZE)
--     This function is similar to `stpcpy' but copies always exactly
--     SIZE characters into TO.
--
--     If the length of FROM is more then SIZE, then `stpncpy' copies
--     just the first SIZE characters and returns a pointer to the
--     character directly following the one which was copied last.  Note
--     that in this case there is no null terminator written into TO.
--
--     If the length of FROM is less than SIZE, then `stpncpy' copies all
--     of FROM, followed by enough null characters to add up to SIZE
--     characters in all.  This behaviour is rarely useful, but it is
--     implemented to be useful in contexts where this behaviour of the
--     `strncpy' is used.  `stpncpy' returns a pointer to the *first*
--     written null character.
--
--     This function is not part of ISO or POSIX but was found useful
--     while developing GNU C Library itself.
--
--     Its behaviour is undefined if the strings overlap.
--
-- - Function: char * strdupa (const char *S)
--     This function is similar to `strdup' but allocates the new string
--     using `alloca' instead of `malloc' *note Variable Size
--     Automatic::..  This means of course the returned string has the
--     same limitations as any block of memory allocated using `alloca'.
--
--     For obvious reasons `strdupa' is implemented only as a macro.
--     I.e., you cannot get the address of this function.  Despite this
--     limitations it is a useful function.  The following code shows a
--     situation where using `malloc' would be a lot more expensive.
--
--          #include <paths.h>
--          #include <string.h>
--          #include <stdio.h>
--          
--          const char path[] = _PATH_STDPATH;
--          
--          int
--          main (void)
--          {
--            char *wr_path = strdupa (path);
--            char *cp = strtok (wr_path, ":");
--          
--            while (cp != NULL)
--              {
--                puts (cp);
--                cp = strtok (NULL, ":");
--              }
--            return 0;
--          }
--
--     Please note that calling `strtok' using PATH directly is illegal.
--
--     This function is only available if GNU CC is used.
--
-- - Function: char * strndupa (const char *S, size_t SIZE)
--     This function is similar to `strndup' but like `strdupa' it
--     allocates the new string using `alloca' *note Variable Size
--     Automatic::..  The same advantages and limitations of `strdupa'
--     are valid for `strndupa', too.
--
--     This function is implemented only as a macro which means one cannot
--     get the address of it.
--
--     `strndupa' is only available if GNU CC is used.
--
-- - Function: char * strcat (char *TO, const char *FROM)
--     The `strcat' function is similar to `strcpy', except that the
--     characters from FROM are concatenated or appended to the end of
--     TO, instead of overwriting it.  That is, the first character from
--     FROM overwrites the null character marking the end of TO.
--
--     An equivalent definition for `strcat' would be:
--
--          char *
--          strcat (char *to, const char *from)
--          {
--            strcpy (to + strlen (to), from);
--            return to;
--          }
--
--     This function has undefined results if the strings overlap.
--
-- - Function: char * strncat (char *TO, const char *FROM, size_t SIZE)
--     This function is like `strcat' except that not more than SIZE
--     characters from FROM are appended to the end of TO.  A single null
--     character is also always appended to TO, so the total allocated
--     size of TO must be at least `SIZE + 1' bytes longer than its
--     initial length.
--
--     The `strncat' function could be implemented like this:
--
--          char *
--          strncat (char *to, const char *from, size_t size)
--          {
--            strncpy (to + strlen (to), from, size);
--            return to;
--          }
--
--     The behavior of `strncat' is undefined if the strings overlap.
--
--   Here is an example showing the use of `strncpy' and `strncat'.
--Notice how, in the call to `strncat', the SIZE parameter is computed to
--avoid overflowing the character array `buffer'.
--
--     #include <string.h>
--     #include <stdio.h>
--     
--     #define SIZE 10
--     
--     static char buffer[SIZE];
--     
--     main ()
--     {
--       strncpy (buffer, "hello", SIZE);
--       puts (buffer);
--       strncat (buffer, ", world", SIZE - strlen (buffer) - 1);
--       puts (buffer);
--     }
--
--The output produced by this program looks like:
--
--     hello
--     hello, wo
--
-- - Function: void * bcopy (void *FROM, const void *TO, size_t SIZE)
--     This is a partially obsolete alternative for `memmove', derived
--     from BSD.  Note that it is not quite equivalent to `memmove',
--     because the arguments are not in the same order.
--
-- - Function: void * bzero (void *BLOCK, size_t SIZE)
--     This is a partially obsolete alternative for `memset', derived from
--     BSD.  Note that it is not as general as `memset', because the only
--     value it can store is zero.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-5 
glibc-2.0.1/manual/libc.info-5
---- ../glibc-2.0.1/manual/libc.info-5  1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-5     1970-01-01 01:00:00.000000000 +0100
-@@ -1,1049 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: String/Array Comparison,  Next: Collation Functions,  
Prev: Copying and Concatenation,  Up: String and Array Utilities
--
--String/Array Comparison
--=======================
--
--   You can use the functions in this section to perform comparisons on
--the contents of strings and arrays.  As well as checking for equality,
--these functions can also be used as the ordering functions for sorting
--operations.  *Note Searching and Sorting::, for an example of this.
--
--   Unlike most comparison operations in C, the string comparison
--functions return a nonzero value if the strings are *not* equivalent
--rather than if they are.  The sign of the value indicates the relative
--ordering of the first characters in the strings that are not
--equivalent:  a negative value indicates that the first string is "less"
--than the second, while a positive value indicates that the first string
--is "greater".
--
--   The most common use of these functions is to check only for equality.
--This is canonically done with an expression like `! strcmp (s1, s2)'.
--
--   All of these functions are declared in the header file `string.h'.
--
-- - Function: int memcmp (const void *A1, const void *A2, size_t SIZE)
--     The function `memcmp' compares the SIZE bytes of memory beginning
--     at A1 against the SIZE bytes of memory beginning at A2.  The value
--     returned has the same sign as the difference between the first
--     differing pair of bytes (interpreted as `unsigned char' objects,
--     then promoted to `int').
--
--     If the contents of the two blocks are equal, `memcmp' returns `0'.
--
--   On arbitrary arrays, the `memcmp' function is mostly useful for
--testing equality.  It usually isn't meaningful to do byte-wise ordering
--comparisons on arrays of things other than bytes.  For example, a
--byte-wise comparison on the bytes that make up floating-point numbers
--isn't likely to tell you anything about the relationship between the
--values of the floating-point numbers.
--
--   You should also be careful about using `memcmp' to compare objects
--that can contain "holes", such as the padding inserted into structure
--objects to enforce alignment requirements, extra space at the end of
--unions, and extra characters at the ends of strings whose length is less
--than their allocated size.  The contents of these "holes" are
--indeterminate and may cause strange behavior when performing byte-wise
--comparisons.  For more predictable results, perform an explicit
--component-wise comparison.
--
--   For example, given a structure type definition like:
--
--     struct foo
--       {
--         unsigned char tag;
--         union
--           {
--             double f;
--             long i;
--             char *p;
--           } value;
--       };
--
--you are better off writing a specialized comparison function to compare
--`struct foo' objects instead of comparing them with `memcmp'.
--
-- - Function: int strcmp (const char *S1, const char *S2)
--     The `strcmp' function compares the string S1 against S2, returning
--     a value that has the same sign as the difference between the first
--     differing pair of characters (interpreted as `unsigned char'
--     objects, then promoted to `int').
--
--     If the two strings are equal, `strcmp' returns `0'.
--
--     A consequence of the ordering used by `strcmp' is that if S1 is an
--     initial substring of S2, then S1 is considered to be "less than"
--     S2.
--
-- - Function: int strcasecmp (const char *S1, const char *S2)
--     This function is like `strcmp', except that differences in case
--     are ignored.
--
--     `strcasecmp' is derived from BSD.
--
-- - Function: int strncasecmp (const char *S1, const char *S2, size_t N)
--     This function is like `strncmp', except that differences in case
--     are ignored.
--
--     `strncasecmp' is a GNU extension.
--
-- - Function: int strncmp (const char *S1, const char *S2, size_t SIZE)
--     This function is the similar to `strcmp', except that no more than
--     SIZE characters are compared.  In other words, if the two strings
--     are the same in their first SIZE characters, the return value is
--     zero.
--
--   Here are some examples showing the use of `strcmp' and `strncmp'.
--These examples assume the use of the ASCII character set.  (If some
--other character set--say, EBCDIC--is used instead, then the glyphs are
--associated with different numeric codes, and the return values and
--ordering may differ.)
--
--     strcmp ("hello", "hello")
--         => 0    /* These two strings are the same. */
--     strcmp ("hello", "Hello")
--         => 32   /* Comparisons are case-sensitive. */
--     strcmp ("hello", "world")
--         => -15  /* The character `'h'' comes before `'w''. */
--     strcmp ("hello", "hello, world")
--         => -44  /* Comparing a null character against a comma. */
--     strncmp ("hello", "hello, world"", 5)
--         => 0    /* The initial 5 characters are the same. */
--     strncmp ("hello, world", "hello, stupid world!!!", 5)
--         => 0    /* The initial 5 characters are the same. */
--
-- - Function: int bcmp (const void *A1, const void *A2, size_t SIZE)
--     This is an obsolete alias for `memcmp', derived from BSD.
--
--
--File: libc.info,  Node: Collation Functions,  Next: Search Functions,  Prev: 
String/Array Comparison,  Up: String and Array Utilities
--
--Collation Functions
--===================
--
--   In some locales, the conventions for lexicographic ordering differ
--from the strict numeric ordering of character codes.  For example, in
--Spanish most glyphs with diacritical marks such as accents are not
--considered distinct letters for the purposes of collation.  On the
--other hand, the two-character sequence `ll' is treated as a single
--letter that is collated immediately after `l'.
--
--   You can use the functions `strcoll' and `strxfrm' (declared in the
--header file `string.h') to compare strings using a collation ordering
--appropriate for the current locale.  The locale used by these functions
--in particular can be specified by setting the locale for the
--`LC_COLLATE' category; see *Note Locales::.
--
--   In the standard C locale, the collation sequence for `strcoll' is
--the same as that for `strcmp'.
--
--   Effectively, the way these functions work is by applying a mapping to
--transform the characters in a string to a byte sequence that represents
--the string's position in the collating sequence of the current locale.
--Comparing two such byte sequences in a simple fashion is equivalent to
--comparing the strings with the locale's collating sequence.
--
--   The function `strcoll' performs this translation implicitly, in
--order to do one comparison.  By contrast, `strxfrm' performs the
--mapping explicitly.  If you are making multiple comparisons using the
--same string or set of strings, it is likely to be more efficient to use
--`strxfrm' to transform all the strings just once, and subsequently
--compare the transformed strings with `strcmp'.
--
-- - Function: int strcoll (const char *S1, const char *S2)
--     The `strcoll' function is similar to `strcmp' but uses the
--     collating sequence of the current locale for collation (the
--     `LC_COLLATE' locale).
--
--   Here is an example of sorting an array of strings, using `strcoll'
--to compare them.  The actual sort algorithm is not written here; it
--comes from `qsort' (*note Array Sort Function::.).  The job of the code
--shown here is to say how to compare the strings while sorting them.
--(Later on in this section, we will show a way to do this more
--efficiently using `strxfrm'.)
--
--     /* This is the comparison function used with `qsort'. */
--     
--     int
--     compare_elements (char **p1, char **p2)
--     {
--       return strcoll (*p1, *p2);
--     }
--     
--     /* This is the entry point--the function to sort
--        strings using the locale's collating sequence. */
--     
--     void
--     sort_strings (char **array, int nstrings)
--     {
--       /* Sort `temp_array' by comparing the strings. */
--       qsort (array, sizeof (char *),
--              nstrings, compare_elements);
--     }
--
-- - Function: size_t strxfrm (char *TO, const char *FROM, size_t SIZE)
--     The function `strxfrm' transforms STRING using the collation
--     transformation determined by the locale currently selected for
--     collation, and stores the transformed string in the array TO.  Up
--     to SIZE characters (including a terminating null character) are
--     stored.
--
--     The behavior is undefined if the strings TO and FROM overlap; see
--     *Note Copying and Concatenation::.
--
--     The return value is the length of the entire transformed string.
--     This value is not affected by the value of SIZE, but if it is
--     greater or equal than SIZE, it means that the transformed string
--     did not entirely fit in the array TO.  In this case, only as much
--     of the string as actually fits was stored.  To get the whole
--     transformed string, call `strxfrm' again with a bigger output
--     array.
--
--     The transformed string may be longer than the original string, and
--     it may also be shorter.
--
--     If SIZE is zero, no characters are stored in TO.  In this case,
--     `strxfrm' simply returns the number of characters that would be
--     the length of the transformed string.  This is useful for
--     determining what size string to allocate.  It does not matter what
--     TO is if SIZE is zero; TO may even be a null pointer.
--
--   Here is an example of how you can use `strxfrm' when you plan to do
--many comparisons.  It does the same thing as the previous example, but
--much faster, because it has to transform each string only once, no
--matter how many times it is compared with other strings.  Even the time
--needed to allocate and free storage is much less than the time we save,
--when there are many strings.
--
--     struct sorter { char *input; char *transformed; };
--     
--     /* This is the comparison function used with `qsort'
--        to sort an array of `struct sorter'. */
--     
--     int
--     compare_elements (struct sorter *p1, struct sorter *p2)
--     {
--       return strcmp (p1->transformed, p2->transformed);
--     }
--     
--     /* This is the entry point--the function to sort
--        strings using the locale's collating sequence. */
--     
--     void
--     sort_strings_fast (char **array, int nstrings)
--     {
--       struct sorter temp_array[nstrings];
--       int i;
--     
--       /* Set up `temp_array'.  Each element contains
--          one input string and its transformed string. */
--       for (i = 0; i < nstrings; i++)
--         {
--           size_t length = strlen (array[i]) * 2;
--           char *transformed;
--           size_t transformed_lenght;
--     
--           temp_array[i].input = array[i];
--     
--           /* First try a buffer perhaps big enough.  */
--           transformed = (char *) xmalloc (length);
--     
--           /* Transform `array[i]'.  */
--           transformed_length = strxfrm (transformed, array[i], length);
--     
--           /* If the buffer was not large enough, resize it
--              and try again.  */
--           if (transformed_length >= length)
--             {
--               /* Allocate the needed space. +1 for terminating
--                  `NUL' character.  */
--               transformed = (char *) xrealloc (transformed,
--                                                transformed_length + 1);
--     
--               /* The return value is not interesting because we know
--                  how long the transformed string is.  */
--               (void) strxfrm (transformed, array[i], transformed_length + 1);
--             }
--     
--           temp_array[i].transformed = transformed;
--         }
--     
--       /* Sort `temp_array' by comparing transformed strings. */
--       qsort (temp_array, sizeof (struct sorter),
--              nstrings, compare_elements);
--     
--       /* Put the elements back in the permanent array
--          in their sorted order. */
--       for (i = 0; i < nstrings; i++)
--         array[i] = temp_array[i].input;
--     
--       /* Free the strings we allocated. */
--       for (i = 0; i < nstrings; i++)
--         free (temp_array[i].transformed);
--     }
--
--   *Compatibility Note:*  The string collation functions are a new
--feature of ISO C.  Older C dialects have no equivalent feature.
--
--
--File: libc.info,  Node: Search Functions,  Next: Finding Tokens in a String,  
Prev: Collation Functions,  Up: String and Array Utilities
--
--Search Functions
--================
--
--   This section describes library functions which perform various kinds
--of searching operations on strings and arrays.  These functions are
--declared in the header file `string.h'.
--
-- - Function: void * memchr (const void *BLOCK, int C, size_t SIZE)
--     This function finds the first occurrence of the byte C (converted
--     to an `unsigned char') in the initial SIZE bytes of the object
--     beginning at BLOCK.  The return value is a pointer to the located
--     byte, or a null pointer if no match was found.
--
-- - Function: char * strchr (const char *STRING, int C)
--     The `strchr' function finds the first occurrence of the character
--     C (converted to a `char') in the null-terminated string beginning
--     at STRING.  The return value is a pointer to the located
--     character, or a null pointer if no match was found.
--
--     For example,
--          strchr ("hello, world", 'l')
--              => "llo, world"
--          strchr ("hello, world", '?')
--              => NULL
--
--     The terminating null character is considered to be part of the
--     string, so you can use this function get a pointer to the end of a
--     string by specifying a null character as the value of the C
--     argument.
--
-- - Function: char * index (const char *STRING, int C)
--     `index' is another name for `strchr'; they are exactly the same.
--
-- - Function: char * strrchr (const char *STRING, int C)
--     The function `strrchr' is like `strchr', except that it searches
--     backwards from the end of the string STRING (instead of forwards
--     from the front).
--
--     For example,
--          strrchr ("hello, world", 'l')
--              => "ld"
--
-- - Function: char * rindex (const char *STRING, int C)
--     `rindex' is another name for `strrchr'; they are exactly the same.
--
-- - Function: char * strstr (const char *HAYSTACK, const char *NEEDLE)
--     This is like `strchr', except that it searches HAYSTACK for a
--     substring NEEDLE rather than just a single character.  It returns
--     a pointer into the string HAYSTACK that is the first character of
--     the substring, or a null pointer if no match was found.  If NEEDLE
--     is an empty string, the function returns HAYSTACK.
--
--     For example,
--          strstr ("hello, world", "l")
--              => "llo, world"
--          strstr ("hello, world", "wo")
--              => "world"
--
-- - Function: void * memmem (const void *NEEDLE, size_t NEEDLE-LEN,
--          const void *HAYSTACK, size_t HAYSTACK-LEN)
--     This is like `strstr', but NEEDLE and HAYSTACK are byte arrays
--     rather than null-terminated strings.  NEEDLE-LEN is the length of
--     NEEDLE and HAYSTACK-LEN is the length of HAYSTACK.
--
--     This function is a GNU extension.
--
-- - Function: size_t strspn (const char *STRING, const char *SKIPSET)
--     The `strspn' ("string span") function returns the length of the
--     initial substring of STRING that consists entirely of characters
--     that are members of the set specified by the string SKIPSET.  The
--     order of the characters in SKIPSET is not important.
--
--     For example,
--          strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")
--              => 5
--
-- - Function: size_t strcspn (const char *STRING, const char *STOPSET)
--     The `strcspn' ("string complement span") function returns the
--     length of the initial substring of STRING that consists entirely
--     of characters that are *not* members of the set specified by the
--     string STOPSET.  (In other words, it returns the offset of the
--     first character in STRING that is a member of the set STOPSET.)
--
--     For example,
--          strcspn ("hello, world", " \t\n,.;!?")
--              => 5
--
-- - Function: char * strpbrk (const char *STRING, const char *STOPSET)
--     The `strpbrk' ("string pointer break") function is related to
--     `strcspn', except that it returns a pointer to the first character
--     in STRING that is a member of the set STOPSET instead of the
--     length of the initial substring.  It returns a null pointer if no
--     such character from STOPSET is found.
--
--     For example,
--
--          strpbrk ("hello, world", " \t\n,.;!?")
--              => ", world"
--
--
--File: libc.info,  Node: Finding Tokens in a String,  Prev: Search Functions,  
Up: String and Array Utilities
--
--Finding Tokens in a String
--==========================
--
--   It's fairly common for programs to have a need to do some simple
--kinds of lexical analysis and parsing, such as splitting a command
--string up into tokens.  You can do this with the `strtok' function,
--declared in the header file `string.h'.
--
-- - Function: char * strtok (char *NEWSTRING, const char *DELIMITERS)
--     A string can be split into tokens by making a series of calls to
--     the function `strtok'.
--
--     The string to be split up is passed as the NEWSTRING argument on
--     the first call only.  The `strtok' function uses this to set up
--     some internal state information.  Subsequent calls to get
--     additional tokens from the same string are indicated by passing a
--     null pointer as the NEWSTRING argument.  Calling `strtok' with
--     another non-null NEWSTRING argument reinitializes the state
--     information.  It is guaranteed that no other library function ever
--     calls `strtok' behind your back (which would mess up this internal
--     state information).
--
--     The DELIMITERS argument is a string that specifies a set of
--     delimiters that may surround the token being extracted.  All the
--     initial characters that are members of this set are discarded.
--     The first character that is *not* a member of this set of
--     delimiters marks the beginning of the next token.  The end of the
--     token is found by looking for the next character that is a member
--     of the delimiter set.  This character in the original string
--     NEWSTRING is overwritten by a null character, and the pointer to
--     the beginning of the token in NEWSTRING is returned.
--
--     On the next call to `strtok', the searching begins at the next
--     character beyond the one that marked the end of the previous token.
--     Note that the set of delimiters DELIMITERS do not have to be the
--     same on every call in a series of calls to `strtok'.
--
--     If the end of the string NEWSTRING is reached, or if the remainder
--     of string consists only of delimiter characters, `strtok' returns
--     a null pointer.
--
--   *Warning:* Since `strtok' alters the string it is parsing, you
--always copy the string to a temporary buffer before parsing it with
--`strtok'.  If you allow `strtok' to modify a string that came from
--another part of your program, you are asking for trouble; that string
--may be part of a data structure that could be used for other purposes
--during the parsing, when alteration by `strtok' makes the data
--structure temporarily inaccurate.
--
--   The string that you are operating on might even be a constant.  Then
--when `strtok' tries to modify it, your program will get a fatal signal
--for writing in read-only memory.  *Note Program Error Signals::.
--
--   This is a special case of a general principle: if a part of a program
--does not have as its purpose the modification of a certain data
--structure, then it is error-prone to modify the data structure
--temporarily.
--
--   The function `strtok' is not reentrant.  *Note Nonreentrancy::, for
--a discussion of where and why reentrancy is important.
--
--   Here is a simple example showing the use of `strtok'.
--
--     #include <string.h>
--     #include <stddef.h>
--     
--     ...
--     
--     char string[] = "words separated by spaces -- and, punctuation!";
--     const char delimiters[] = " .,;:!-";
--     char *token;
--     
--     ...
--     
--     token = strtok (string, delimiters);  /* token => "words" */
--     token = strtok (NULL, delimiters);    /* token => "separated" */
--     token = strtok (NULL, delimiters);    /* token => "by" */
--     token = strtok (NULL, delimiters);    /* token => "spaces" */
--     token = strtok (NULL, delimiters);    /* token => "and" */
--     token = strtok (NULL, delimiters);    /* token => "punctuation" */
--     token = strtok (NULL, delimiters);    /* token => NULL */
--
--   The GNU C library contains two more functions for tokenizing a string
--which overcome the limitation of non-reentrancy.
--
-- - Function: char * strtok_r (char *NEWSTRING, const char *DELIMITERS,
--          char **SAVE_PTR)
--     Just like `strtok' this function splits the string into several
--     tokens which can be accessed be successive calls to `strtok_r'.
--     The difference is that the information about the next token is not
--     set up in some internal state information.  Instead the caller has
--     to provide another argument SAVE_PTR which is a pointer to a string
--     pointer.  Calling `strtok_r' with a null pointer for NEWSTRING and
--     leaving SAVE_PTR between the calls unchanged does the job without
--     limiting reentrancy.
--
--     This function was proposed for POSIX.1b and can be found on many
--     systems which support multi-threading.
--
-- - Function: char * strsep (char **STRING_PTR, const char *DELIMITER)
--     A second reentrant approach is to avoid the additional first
--     argument.  The initialization of the moving pointer has to be done
--     by the user.  Successive calls of `strsep' move the pointer along
--     the tokens separated by DELIMITER, returning the address of the
--     next token and updating STRING_PTR to point to the beginning of
--     the next token.
--
--     This function was introduced in 4.3BSD and therefore is widely
--     available.
--
--   Here is how the above example looks like when `strsep' is used.
--
--     #include <string.h>
--     #include <stddef.h>
--     
--     ...
--     
--     char string[] = "words separated by spaces -- and, punctuation!";
--     const char delimiters[] = " .,;:!-";
--     char *running;
--     char *token;
--     
--     ...
--     
--     running = string;
--     token = strsep (&running, delimiters);    /* token => "words" */
--     token = strsep (&running, delimiters);    /* token => "separated" */
--     token = strsep (&running, delimiters);    /* token => "by" */
--     token = strsep (&running, delimiters);    /* token => "spaces" */
--     token = strsep (&running, delimiters);    /* token => "and" */
--     token = strsep (&running, delimiters);    /* token => "punctuation" */
--     token = strsep (&running, delimiters);    /* token => NULL */
--
--
--File: libc.info,  Node: I/O Overview,  Next: I/O on Streams,  Prev: Pattern 
Matching,  Up: Top
--
--Input/Output Overview
--*********************
--
--   Most programs need to do either input (reading data) or output
--(writing data), or most frequently both, in order to do anything
--useful.  The GNU C library provides such a large selection of input and
--output functions that the hardest part is often deciding which function
--is most appropriate!
--
--   This chapter introduces concepts and terminology relating to input
--and output.  Other chapters relating to the GNU I/O facilities are:
--
--   * *Note I/O on Streams::, which covers the high-level functions that
--     operate on streams, including formatted input and output.
--
--   * *Note Low-Level I/O::, which covers the basic I/O and control
--     functions on file descriptors.
--
--   * *Note File System Interface::, which covers functions for
--     operating on directories and for manipulating file attributes such
--     as access modes and ownership.
--
--   * *Note Pipes and FIFOs::, which includes information on the basic
--     interprocess communication facilities.
--
--   * *Note Sockets::, which covers a more complicated interprocess
--     communication facility with support for networking.
--
--   * *Note Low-Level Terminal Interface::, which covers functions for
--     changing how input and output to terminal or other serial devices
--     are processed.
--
--* Menu:
--
--* I/O Concepts::       Some basic information and terminology.
--* File Names::         How to refer to a file.
--
--
--File: libc.info,  Node: I/O Concepts,  Next: File Names,  Up: I/O Overview
--
--Input/Output Concepts
--=====================
--
--   Before you can read or write the contents of a file, you must
--establish a connection or communications channel to the file.  This
--process is called "opening" the file.  You can open a file for reading,
--writing, or both.
--
--   The connection to an open file is represented either as a stream or
--as a file descriptor.  You pass this as an argument to the functions
--that do the actual read or write operations, to tell them which file to
--operate on.  Certain functions expect streams, and others are designed
--to operate on file descriptors.
--
--   When you have finished reading to or writing from the file, you can
--terminate the connection by "closing" the file.  Once you have closed a
--stream or file descriptor, you cannot do any more input or output
--operations on it.
--
--* Menu:
--
--* Streams and File Descriptors::    The GNU Library provides two ways
--                                   to access the contents of files.
--* File Position::                   The number of bytes from the
--                                     beginning of the file.
--
--
--File: libc.info,  Node: Streams and File Descriptors,  Next: File Position,  
Up: I/O Concepts
--
--Streams and File Descriptors
------------------------------
--
--   When you want to do input or output to a file, you have a choice of
--two basic mechanisms for representing the connection between your
--program and the file: file descriptors and streams.  File descriptors
--are represented as objects of type `int', while streams are represented
--as `FILE *' objects.
--
--   File descriptors provide a primitive, low-level interface to input
--and output operations.  Both file descriptors and streams can represent
--a connection to a device (such as a terminal), or a pipe or socket for
--communicating with another process, as well as a normal file.  But, if
--you want to do control operations that are specific to a particular kind
--of device, you must use a file descriptor; there are no facilities to
--use streams in this way.  You must also use file descriptors if your
--program needs to do input or output in special modes, such as
--nonblocking (or polled) input (*note File Status Flags::.).
--
--   Streams provide a higher-level interface, layered on top of the
--primitive file descriptor facilities.  The stream interface treats all
--kinds of files pretty much alike--the sole exception being the three
--styles of buffering that you can choose (*note Stream Buffering::.).
--
--   The main advantage of using the stream interface is that the set of
--functions for performing actual input and output operations (as opposed
--to control operations) on streams is much richer and more powerful than
--the corresponding facilities for file descriptors.  The file descriptor
--interface provides only simple functions for transferring blocks of
--characters, but the stream interface also provides powerful formatted
--input and output functions (`printf' and `scanf') as well as functions
--for character- and line-oriented input and output.
--
--   Since streams are implemented in terms of file descriptors, you can
--extract the file descriptor from a stream and perform low-level
--operations directly on the file descriptor.  You can also initially open
--a connection as a file descriptor and then make a stream associated with
--that file descriptor.
--
--   In general, you should stick with using streams rather than file
--descriptors, unless there is some specific operation you want to do that
--can only be done on a file descriptor.  If you are a beginning
--programmer and aren't sure what functions to use, we suggest that you
--concentrate on the formatted input functions (*note Formatted Input::.)
--and formatted output functions (*note Formatted Output::.).
--
--   If you are concerned about portability of your programs to systems
--other than GNU, you should also be aware that file descriptors are not
--as portable as streams.  You can expect any system running ISO C to
--support streams, but non-GNU systems may not support file descriptors at
--all, or may only implement a subset of the GNU functions that operate on
--file descriptors.  Most of the file descriptor functions in the GNU
--library are included in the POSIX.1 standard, however.
--
--
--File: libc.info,  Node: File Position,  Prev: Streams and File Descriptors,  
Up: I/O Concepts
--
--File Position
---------------
--
--   One of the attributes of an open file is its "file position" that
--keeps track of where in the file the next character is to be read or
--written.  In the GNU system, and all POSIX.1 systems, the file position
--is simply an integer representing the number of bytes from the beginning
--of the file.
--
--   The file position is normally set to the beginning of the file when
--it is opened, and each time a character is read or written, the file
--position is incremented.  In other words, access to the file is normally
--"sequential".
--
--   Ordinary files permit read or write operations at any position within
--the file.  Some other kinds of files may also permit this.  Files which
--do permit this are sometimes referred to as "random-access" files.  You
--can change the file position using the `fseek' function on a stream
--(*note File Positioning::.) or the `lseek' function on a file
--descriptor (*note I/O Primitives::.).  If you try to change the file
--position on a file that doesn't support random access, you get the
--`ESPIPE' error.
--
--   Streams and descriptors that are opened for "append access" are
--treated specially for output: output to such files is *always* appended
--sequentially to the *end* of the file, regardless of the file position.
--However, the file position is still used to control where in the file
--reading is done.
--
--   If you think about it, you'll realize that several programs can read
--a given file at the same time.  In order for each program to be able to
--read the file at its own pace, each program must have its own file
--pointer, which is not affected by anything the other programs do.
--
--   In fact, each opening of a file creates a separate file position.
--Thus, if you open a file twice even in the same program, you get two
--streams or descriptors with independent file positions.
--
--   By contrast, if you open a descriptor and then duplicate it to get
--another descriptor, these two descriptors share the same file position:
--changing the file position of one descriptor will affect the other.
--
--
--File: libc.info,  Node: File Names,  Prev: I/O Concepts,  Up: I/O Overview
--
--File Names
--==========
--
--   In order to open a connection to a file, or to perform other
--operations such as deleting a file, you need some way to refer to the
--file.  Nearly all files have names that are strings--even files which
--are actually devices such as tape drives or terminals.  These strings
--are called "file names".  You specify the file name to say which file
--you want to open or operate on.
--
--   This section describes the conventions for file names and how the
--operating system works with them.
--
--* Menu:
--
--* Directories::                 Directories contain entries for files.
--* File Name Resolution::        A file name specifies how to look up a file.
--* File Name Errors::            Error conditions relating to file names.
--* File Name Portability::       File name portability and syntax issues.
--
--
--File: libc.info,  Node: Directories,  Next: File Name Resolution,  Up: File 
Names
--
--Directories
-------------
--
--   In order to understand the syntax of file names, you need to
--understand how the file system is organized into a hierarchy of
--directories.
--
--   A "directory" is a file that contains information to associate other
--files with names; these associations are called "links" or "directory
--entries".  Sometimes, people speak of "files in a directory", but in
--reality, a directory only contains pointers to files, not the files
--themselves.
--
--   The name of a file contained in a directory entry is called a "file
--name component".  In general, a file name consists of a sequence of one
--or more such components, separated by the slash character (`/').  A
--file name which is just one component names a file with respect to its
--directory.  A file name with multiple components names a directory, and
--then a file in that directory, and so on.
--
--   Some other documents, such as the POSIX standard, use the term
--"pathname" for what we call a file name, and either "filename" or
--"pathname component" for what this manual calls a file name component.
--We don't use this terminology because a "path" is something completely
--different (a list of directories to search), and we think that
--"pathname" used for something else will confuse users.  We always use
--"file name" and "file name component" (or sometimes just "component",
--where the context is obvious) in GNU documentation.  Some macros use
--the POSIX terminology in their names, such as `PATH_MAX'.  These macros
--are defined by the POSIX standard, so we cannot change their names.
--
--   You can find more detailed information about operations on
--directories in *Note File System Interface::.
--
--
--File: libc.info,  Node: File Name Resolution,  Next: File Name Errors,  Prev: 
Directories,  Up: File Names
--
--File Name Resolution
----------------------
--
--   A file name consists of file name components separated by slash
--(`/') characters.  On the systems that the GNU C library supports,
--multiple successive `/' characters are equivalent to a single `/'
--character.
--
--   The process of determining what file a file name refers to is called
--"file name resolution".  This is performed by examining the components
--that make up a file name in left-to-right order, and locating each
--successive component in the directory named by the previous component.
--Of course, each of the files that are referenced as directories must
--actually exist, be directories instead of regular files, and have the
--appropriate permissions to be accessible by the process; otherwise the
--file name resolution fails.
--
--   If a file name begins with a `/', the first component in the file
--name is located in the "root directory" of the process (usually all
--processes on the system have the same root directory).  Such a file name
--is called an "absolute file name".
--
--   Otherwise, the first component in the file name is located in the
--current working directory (*note Working Directory::.).  This kind of
--file name is called a "relative file name".
--
--   The file name components `.' ("dot") and `..' ("dot-dot") have
--special meanings.  Every directory has entries for these file name
--components.  The file name component `.' refers to the directory
--itself, while the file name component `..' refers to its "parent
--directory" (the directory that contains the link for the directory in
--question).  As a special case, `..' in the root directory refers to the
--root directory itself, since it has no parent; thus `/..' is the same
--as `/'.
--
--   Here are some examples of file names:
--
--`/a'
--     The file named `a', in the root directory.
--
--`/a/b'
--     The file named `b', in the directory named `a' in the root
--     directory.
--
--`a'
--     The file named `a', in the current working directory.
--
--`/a/./b'
--     This is the same as `/a/b'.
--
--`./a'
--     The file named `a', in the current working directory.
--
--`../a'
--     The file named `a', in the parent directory of the current working
--     directory.
--
--   A file name that names a directory may optionally end in a `/'.  You
--can specify a file name of `/' to refer to the root directory, but the
--empty string is not a meaningful file name.  If you want to refer to
--the current working directory, use a file name of `.' or `./'.
--
--   Unlike some other operating systems, the GNU system doesn't have any
--built-in support for file types (or extensions) or file versions as part
--of its file name syntax.  Many programs and utilities use conventions
--for file names--for example, files containing C source code usually
--have names suffixed with `.c'--but there is nothing in the file system
--itself that enforces this kind of convention.
--
--
--File: libc.info,  Node: File Name Errors,  Next: File Name Portability,  
Prev: File Name Resolution,  Up: File Names
--
--File Name Errors
------------------
--
--   Functions that accept file name arguments usually detect these
--`errno' error conditions relating to the file name syntax or trouble
--finding the named file.  These errors are referred to throughout this
--manual as the "usual file name errors".
--
--`EACCES'
--     The process does not have search permission for a directory
--     component of the file name.
--
--`ENAMETOOLONG'
--     This error is used when either the the total length of a file name
--     is greater than `PATH_MAX', or when an individual file name
--     component has a length greater than `NAME_MAX'.  *Note Limits for
--     Files::.
--
--     In the GNU system, there is no imposed limit on overall file name
--     length, but some file systems may place limits on the length of a
--     component.
--
--`ENOENT'
--     This error is reported when a file referenced as a directory
--     component in the file name doesn't exist, or when a component is a
--     symbolic link whose target file does not exist.  *Note Symbolic
--     Links::.
--
--`ENOTDIR'
--     A file that is referenced as a directory component in the file name
--     exists, but it isn't a directory.
--
--`ELOOP'
--     Too many symbolic links were resolved while trying to look up the
--     file name.  The system has an arbitrary limit on the number of
--     symbolic links that may be resolved in looking up a single file
--     name, as a primitive way to detect loops.  *Note Symbolic Links::.
--
--
--File: libc.info,  Node: File Name Portability,  Prev: File Name Errors,  Up: 
File Names
--
--Portability of File Names
---------------------------
--
--   The rules for the syntax of file names discussed in *Note File
--Names::, are the rules normally used by the GNU system and by other
--POSIX systems.  However, other operating systems may use other
--conventions.
--
--   There are two reasons why it can be important for you to be aware of
--file name portability issues:
--
--   * If your program makes assumptions about file name syntax, or
--     contains embedded literal file name strings, it is more difficult
--     to get it to run under other operating systems that use different
--     syntax conventions.
--
--   * Even if you are not concerned about running your program on
--     machines that run other operating systems, it may still be
--     possible to access files that use different naming conventions.
--     For example, you may be able to access file systems on another
--     computer running a different operating system over a network, or
--     read and write disks in formats used by other operating systems.
--
--   The ISO C standard says very little about file name syntax, only that
--file names are strings.  In addition to varying restrictions on the
--length of file names and what characters can validly appear in a file
--name, different operating systems use different conventions and syntax
--for concepts such as structured directories and file types or
--extensions.  Some concepts such as file versions might be supported in
--some operating systems and not by others.
--
--   The POSIX.1 standard allows implementations to put additional
--restrictions on file name syntax, concerning what characters are
--permitted in file names and on the length of file name and file name
--component strings.  However, in the GNU system, you do not need to worry
--about these restrictions; any character except the null character is
--permitted in a file name string, and there are no limits on the length
--of file name strings.
--
--
--File: libc.info,  Node: I/O on Streams,  Next: Low-Level I/O,  Prev: I/O 
Overview,  Up: Top
--
--Input/Output on Streams
--***********************
--
--   This chapter describes the functions for creating streams and
--performing input and output operations on them.  As discussed in *Note
--I/O Overview::, a stream is a fairly abstract, high-level concept
--representing a communications channel to a file, device, or process.
--
--* Menu:
--
--* Streams::                     About the data type representing a stream.
--* Standard Streams::            Streams to the standard input and output
--                                 devices are created for you.
--* Opening Streams::             How to create a stream to talk to a file.
--* Closing Streams::             Close a stream when you are finished with it.
--* Simple Output::               Unformatted output by characters and lines.
--* Character Input::             Unformatted input by characters and words.
--* Line Input::                  Reading a line or a record from a stream.
--* Unreading::                   Peeking ahead/pushing back input just read.
--* Block Input/Output::          Input and output operations on blocks of data.
--* Formatted Output::            `printf' and related functions.
--* Customizing Printf::          You can define new conversion specifiers for
--                                 `printf' and friends.
--* Formatted Input::             `scanf' and related functions.
--* EOF and Errors::              How you can tell if an I/O error happens.
--* Binary Streams::              Some systems distinguish between text files
--                                 and binary files.
--* File Positioning::            About random-access streams.
--* Portable Positioning::        Random access on peculiar ISO C systems.
--* Stream Buffering::            How to control buffering of streams.
--* Other Kinds of Streams::      Streams that do not necessarily correspond
--                                 to an open file.
--
--
--File: libc.info,  Node: Streams,  Next: Standard Streams,  Up: I/O on Streams
--
--Streams
--=======
--
--   For historical reasons, the type of the C data structure that
--represents a stream is called `FILE' rather than "stream".  Since most
--of the library functions deal with objects of type `FILE *', sometimes
--the term "file pointer" is also used to mean "stream".  This leads to
--unfortunate confusion over terminology in many books on C.  This
--manual, however, is careful to use the terms "file" and "stream" only
--in the technical sense.
--
--   The `FILE' type is declared in the header file `stdio.h'.
--
-- - Data Type: FILE
--     This is the data type used to represent stream objects.  A `FILE'
--     object holds all of the internal state information about the
--     connection to the associated file, including such things as the
--     file position indicator and buffering information.  Each stream
--     also has error and end-of-file status indicators that can be
--     tested with the `ferror' and `feof' functions; see *Note EOF and
--     Errors::.
--
--   `FILE' objects are allocated and managed internally by the
--input/output library functions.  Don't try to create your own objects of
--type `FILE'; let the library do it.  Your programs should deal only
--with pointers to these objects (that is, `FILE *' values) rather than
--the objects themselves.
--
--
--File: libc.info,  Node: Standard Streams,  Next: Opening Streams,  Prev: 
Streams,  Up: I/O on Streams
--
--Standard Streams
--================
--
--   When the `main' function of your program is invoked, it already has
--three predefined streams open and available for use.  These represent
--the "standard" input and output channels that have been established for
--the process.
--
--   These streams are declared in the header file `stdio.h'.
--
-- - Variable: FILE * stdin
--     The "standard input" stream, which is the normal source of input
--     for the program.
--
-- - Variable: FILE * stdout
--     The "standard output" stream, which is used for normal output from
--     the program.
--
-- - Variable: FILE * stderr
--     The "standard error" stream, which is used for error messages and
--     diagnostics issued by the program.
--
--   In the GNU system, you can specify what files or processes
--correspond to these streams using the pipe and redirection facilities
--provided by the shell.  (The primitives shells use to implement these
--facilities are described in *Note File System Interface::.)  Most other
--operating systems provide similar mechanisms, but the details of how to
--use them can vary.
--
--   In the GNU C library, `stdin', `stdout', and `stderr' are normal
--variables which you can set just like any others.  For example, to
--redirect the standard output to a file, you could do:
--
--     fclose (stdout);
--     stdout = fopen ("standard-output-file", "w");
--
--   Note however, that in other systems `stdin', `stdout', and `stderr'
--are macros that you cannot assign to in the normal way.  But you can
--use `freopen' to get the effect of closing one and reopening it.  *Note
--Opening Streams::.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-6 
glibc-2.0.1/manual/libc.info-6
---- ../glibc-2.0.1/manual/libc.info-6  1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-6     1970-01-01 01:00:00.000000000 +0100
-@@ -1,1156 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Opening Streams,  Next: Closing Streams,  Prev: 
Standard Streams,  Up: I/O on Streams
--
--Opening Streams
--===============
--
--   Opening a file with the `fopen' function creates a new stream and
--establishes a connection between the stream and a file.  This may
--involve creating a new file.
--
--   Everything described in this section is declared in the header file
--`stdio.h'.
--
-- - Function: FILE * fopen (const char *FILENAME, const char *OPENTYPE)
--     The `fopen' function opens a stream for I/O to the file FILENAME,
--     and returns a pointer to the stream.
--
--     The OPENTYPE argument is a string that controls how the file is
--     opened and specifies attributes of the resulting stream.  It must
--     begin with one of the following sequences of characters:
--
--    `r'
--          Open an existing file for reading only.
--
--    `w'
--          Open the file for writing only.  If the file already exists,
--          it is truncated to zero length.  Otherwise a new file is
--          created.
--
--    `a'
--          Open a file for append access; that is, writing at the end of
--          file only.  If the file already exists, its initial contents
--          are unchanged and output to the stream is appended to the end
--          of the file.  Otherwise, a new, empty file is created.
--
--    `r+'
--          Open an existing file for both reading and writing.  The
--          initial contents of the file are unchanged and the initial
--          file position is at the beginning of the file.
--
--    `w+'
--          Open a file for both reading and writing.  If the file
--          already exists, it is truncated to zero length.  Otherwise, a
--          new file is created.
--
--    `a+'
--          Open or create file for both reading and appending.  If the
--          file exists, its initial contents are unchanged.  Otherwise,
--          a new file is created.  The initial file position for reading
--          is at the beginning of the file, but output is always
--          appended to the end of the file.
--
--     As you can see, `+' requests a stream that can do both input and
--     output.  The ISO standard says that when using such a stream, you
--     must call `fflush' (*note Stream Buffering::.) or a file
--     positioning function such as `fseek' (*note File Positioning::.)
--     when switching from reading to writing or vice versa.  Otherwise,
--     internal buffers might not be emptied properly.  The GNU C library
--     does not have this limitation; you can do arbitrary reading and
--     writing operations on a stream in whatever order.
--
--     Additional characters may appear after these to specify flags for
--     the call.  Always put the mode (`r', `w+', etc.) first; that is
--     the only part you are guaranteed will be understood by all systems.
--
--     The GNU C library defines one additional character for use in
--     OPENTYPE: the character `x' insists on creating a new file--if a
--     file FILENAME already exists, `fopen' fails rather than opening
--     it.  If you use `x' you can are guaranteed that you will not
--     clobber an existing file.  This is equivalent to the `O_EXCL'
--     option to the `open' function (*note Opening and Closing Files::.).
--
--     The character `b' in OPENTYPE has a standard meaning; it requests
--     a binary stream rather than a text stream.  But this makes no
--     difference in POSIX systems (including the GNU system).  If both
--     `+' and `b' are specified, they can appear in either order.  *Note
--     Binary Streams::.
--
--     Any other characters in OPENTYPE are simply ignored.  They may be
--     meaningful in other systems.
--
--     If the open fails, `fopen' returns a null pointer.
--
--   You can have multiple streams (or file descriptors) pointing to the
--same file open at the same time.  If you do only input, this works
--straightforwardly, but you must be careful if any output streams are
--included.  *Note Stream/Descriptor Precautions::.  This is equally true
--whether the streams are in one program (not usual) or in several
--programs (which can easily happen).  It may be advantageous to use the
--file locking facilities to avoid simultaneous access.  *Note File
--Locks::.
--
-- - Macro: int FOPEN_MAX
--     The value of this macro is an integer constant expression that
--     represents the minimum number of streams that the implementation
--     guarantees can be open simultaneously.  You might be able to open
--     more than this many streams, but that is not guaranteed.  The
--     value of this constant is at least eight, which includes the three
--     standard streams `stdin', `stdout', and `stderr'.  In POSIX.1
--     systems this value is determined by the `OPEN_MAX' parameter;
--     *note General Limits::..  In BSD and GNU, it is controlled by the
--     `RLIMIT_NOFILE' resource limit; *note Limits on Resources::..
--
-- - Function: FILE * freopen (const char *FILENAME, const char
--          *OPENTYPE, FILE *STREAM)
--     This function is like a combination of `fclose' and `fopen'.  It
--     first closes the stream referred to by STREAM, ignoring any errors
--     that are detected in the process.  (Because errors are ignored,
--     you should not use `freopen' on an output stream if you have
--     actually done any output using the stream.)  Then the file named by
--     FILENAME is opened with mode OPENTYPE as for `fopen', and
--     associated with the same stream object STREAM.
--
--     If the operation fails, a null pointer is returned; otherwise,
--     `freopen' returns STREAM.
--
--     `freopen' has traditionally been used to connect a standard stream
--     such as `stdin' with a file of your own choice.  This is useful in
--     programs in which use of a standard stream for certain purposes is
--     hard-coded.  In the GNU C library, you can simply close the
--     standard streams and open new ones with `fopen'.  But other
--     systems lack this ability, so using `freopen' is more portable.
--
--
--File: libc.info,  Node: Closing Streams,  Next: Simple Output,  Prev: Opening 
Streams,  Up: I/O on Streams
--
--Closing Streams
--===============
--
--   When a stream is closed with `fclose', the connection between the
--stream and the file is cancelled.  After you have closed a stream, you
--cannot perform any additional operations on it.
--
-- - Function: int fclose (FILE *STREAM)
--     This function causes STREAM to be closed and the connection to the
--     corresponding file to be broken.  Any buffered output is written
--     and any buffered input is discarded.  The `fclose' function returns
--     a value of `0' if the file was closed successfully, and `EOF' if
--     an error was detected.
--
--     It is important to check for errors when you call `fclose' to close
--     an output stream, because real, everyday errors can be detected at
--     this time.  For example, when `fclose' writes the remaining
--     buffered output, it might get an error because the disk is full.
--     Even if you know the buffer is empty, errors can still occur when
--     closing a file if you are using NFS.
--
--     The function `fclose' is declared in `stdio.h'.
--
--   To close all streams currently available the GNU C Library provides
--another function.
--
-- - Function: int fcloseall (void)
--     This function causes all open streams of the process to be closed
--     and the connection to corresponding files to be broken.  All
--     buffered data is written and any buffered inputis discarded.  The
--     `fcloseall' function returns a value of `0' if all the files were
--     closed successfully, and `EOF' if an error was detected.
--
--     This function should be used in only in special situation, e.g.,
--     when an error occurred and the program must be aborted.  Normally
--     each single stream should be closed separately so that problems
--     with one stream can be identifier.  It is also problematic since
--     the standard streams (*note Standard Streams::.) will also be
--     closed.
--
--     The function `fcloseall' is declared in `stdio.h'.
--
--   If the `main' function to your program returns, or if you call the
--`exit' function (*note Normal Termination::.), all open streams are
--automatically closed properly.  If your program terminates in any other
--manner, such as by calling the `abort' function (*note Aborting a
--Program::.) or from a fatal signal (*note Signal Handling::.), open
--streams might not be closed properly.  Buffered output might not be
--flushed and files may be incomplete.  For more information on buffering
--of streams, see *Note Stream Buffering::.
--
--
--File: libc.info,  Node: Simple Output,  Next: Character Input,  Prev: Closing 
Streams,  Up: I/O on Streams
--
--Simple Output by Characters or Lines
--====================================
--
--   This section describes functions for performing character- and
--line-oriented output.
--
--   These functions are declared in the header file `stdio.h'.
--
-- - Function: int fputc (int C, FILE *STREAM)
--     The `fputc' function converts the character C to type `unsigned
--     char', and writes it to the stream STREAM.  `EOF' is returned if a
--     write error occurs; otherwise the character C is returned.
--
-- - Function: int putc (int C, FILE *STREAM)
--     This is just like `fputc', except that most systems implement it as
--     a macro, making it faster.  One consequence is that it may
--     evaluate the STREAM argument more than once, which is an exception
--     to the general rule for macros.  `putc' is usually the best
--     function to use for writing a single character.
--
-- - Function: int putchar (int C)
--     The `putchar' function is equivalent to `putc' with `stdout' as
--     the value of the STREAM argument.
--
-- - Function: int fputs (const char *S, FILE *STREAM)
--     The function `fputs' writes the string S to the stream STREAM.
--     The terminating null character is not written.  This function does
--     *not* add a newline character, either.  It outputs only the
--     characters in the string.
--
--     This function returns `EOF' if a write error occurs, and otherwise
--     a non-negative value.
--
--     For example:
--
--          fputs ("Are ", stdout);
--          fputs ("you ", stdout);
--          fputs ("hungry?\n", stdout);
--
--     outputs the text `Are you hungry?' followed by a newline.
--
-- - Function: int puts (const char *S)
--     The `puts' function writes the string S to the stream `stdout'
--     followed by a newline.  The terminating null character of the
--     string is not written.  (Note that `fputs' does *not* write a
--     newline as this function does.)
--
--     `puts' is the most convenient function for printing simple
--     messages.  For example:
--
--          puts ("This is a message.");
--
-- - Function: int putw (int W, FILE *STREAM)
--     This function writes the word W (that is, an `int') to STREAM.  It
--     is provided for compatibility with SVID, but we recommend you use
--     `fwrite' instead (*note Block Input/Output::.).
--
--
--File: libc.info,  Node: Character Input,  Next: Line Input,  Prev: Simple 
Output,  Up: I/O on Streams
--
--Character Input
--===============
--
--   This section describes functions for performing character-oriented
--input.  These functions are declared in the header file `stdio.h'.
--
--   These functions return an `int' value that is either a character of
--input, or the special value `EOF' (usually -1).  It is important to
--store the result of these functions in a variable of type `int' instead
--of `char', even when you plan to use it only as a character.  Storing
--`EOF' in a `char' variable truncates its value to the size of a
--character, so that it is no longer distinguishable from the valid
--character `(char) -1'.  So always use an `int' for the result of `getc'
--and friends, and check for `EOF' after the call; once you've verified
--that the result is not `EOF', you can be sure that it will fit in a
--`char' variable without loss of information.
--
-- - Function: int fgetc (FILE *STREAM)
--     This function reads the next character as an `unsigned char' from
--     the stream STREAM and returns its value, converted to an `int'.
--     If an end-of-file condition or read error occurs, `EOF' is
--     returned instead.
--
-- - Function: int getc (FILE *STREAM)
--     This is just like `fgetc', except that it is permissible (and
--     typical) for it to be implemented as a macro that evaluates the
--     STREAM argument more than once.  `getc' is often highly optimized,
--     so it is usually the best function to use to read a single
--     character.
--
-- - Function: int getchar (void)
--     The `getchar' function is equivalent to `getc' with `stdin' as the
--     value of the STREAM argument.
--
--   Here is an example of a function that does input using `fgetc'.  It
--would work just as well using `getc' instead, or using `getchar ()'
--instead of `fgetc (stdin)'.
--
--     int
--     y_or_n_p (const char *question)
--     {
--       fputs (question, stdout);
--       while (1)
--         {
--           int c, answer;
--           /* Write a space to separate answer from question. */
--           fputc (' ', stdout);
--           /* Read the first character of the line.
--              This should be the answer character, but might not be. */
--           c = tolower (fgetc (stdin));
--           answer = c;
--           /* Discard rest of input line. */
--           while (c != '\n' && c != EOF)
--             c = fgetc (stdin);
--           /* Obey the answer if it was valid. */
--           if (answer == 'y')
--             return 1;
--           if (answer == 'n')
--             return 0;
--           /* Answer was invalid: ask for valid answer. */
--           fputs ("Please answer y or n:", stdout);
--         }
--     }
--
-- - Function: int getw (FILE *STREAM)
--     This function reads a word (that is, an `int') from STREAM.  It's
--     provided for compatibility with SVID.  We recommend you use
--     `fread' instead (*note Block Input/Output::.).  Unlike `getc', any
--     `int' value could be a valid result.  `getw' returns `EOF' when it
--     encounters end-of-file or an error, but there is no way to
--     distinguish this from an input word with value -1.
--
--
--File: libc.info,  Node: Line Input,  Next: Unreading,  Prev: Character Input, 
 Up: I/O on Streams
--
--Line-Oriented Input
--===================
--
--   Since many programs interpret input on the basis of lines, it's
--convenient to have functions to read a line of text from a stream.
--
--   Standard C has functions to do this, but they aren't very safe: null
--characters and even (for `gets') long lines can confuse them.  So the
--GNU library provides the nonstandard `getline' function that makes it
--easy to read lines reliably.
--
--   Another GNU extension, `getdelim', generalizes `getline'.  It reads
--a delimited record, defined as everything through the next occurrence
--of a specified delimiter character.
--
--   All these functions are declared in `stdio.h'.
--
-- - Function: ssize_t getline (char **LINEPTR, size_t *N, FILE *STREAM)
--     This function reads an entire line from STREAM, storing the text
--     (including the newline and a terminating null character) in a
--     buffer and storing the buffer address in `*LINEPTR'.
--
--     Before calling `getline', you should place in `*LINEPTR' the
--     address of a buffer `*N' bytes long, allocated with `malloc'.  If
--     this buffer is long enough to hold the line, `getline' stores the
--     line in this buffer.  Otherwise, `getline' makes the buffer bigger
--     using `realloc', storing the new buffer address back in `*LINEPTR'
--     and the increased size back in `*N'.  *Note Unconstrained
--     Allocation::.
--
--     If you set `*LINEPTR' to a null pointer, and `*N' to zero, before
--     the call, then `getline' allocates the initial buffer for you by
--     calling `malloc'.
--
--     In either case, when `getline' returns,  `*LINEPTR' is a `char *'
--     which points to the text of the line.
--
--     When `getline' is successful, it returns the number of characters
--     read (including the newline, but not including the terminating
--     null).  This value enables you to distinguish null characters that
--     are part of the line from the null character inserted as a
--     terminator.
--
--     This function is a GNU extension, but it is the recommended way to
--     read lines from a stream.  The alternative standard functions are
--     unreliable.
--
--     If an error occurs or end of file is reached, `getline' returns
--     `-1'.
--
-- - Function: ssize_t getdelim (char **LINEPTR, size_t *N, int
--          DELIMITER, FILE *STREAM)
--     This function is like `getline' except that the character which
--     tells it to stop reading is not necessarily newline.  The argument
--     DELIMITER specifies the delimiter character; `getdelim' keeps
--     reading until it sees that character (or end of file).
--
--     The text is stored in LINEPTR, including the delimiter character
--     and a terminating null.  Like `getline', `getdelim' makes LINEPTR
--     bigger if it isn't big enough.
--
--     `getline' is in fact implemented in terms of `getdelim', just like
--     this:
--
--          ssize_t
--          getline (char **lineptr, size_t *n, FILE *stream)
--          {
--            return getdelim (lineptr, n, '\n', stream);
--          }
--
-- - Function: char * fgets (char *S, int COUNT, FILE *STREAM)
--     The `fgets' function reads characters from the stream STREAM up to
--     and including a newline character and stores them in the string S,
--     adding a null character to mark the end of the string.  You must
--     supply COUNT characters worth of space in S, but the number of
--     characters read is at most COUNT - 1.  The extra character space
--     is used to hold the null character at the end of the string.
--
--     If the system is already at end of file when you call `fgets', then
--     the contents of the array S are unchanged and a null pointer is
--     returned.  A null pointer is also returned if a read error occurs.
--     Otherwise, the return value is the pointer S.
--
--     *Warning:*  If the input data has a null character, you can't tell.
--     So don't use `fgets' unless you know the data cannot contain a
--     null.  Don't use it to read files edited by the user because, if
--     the user inserts a null character, you should either handle it
--     properly or print a clear error message.  We recommend using
--     `getline' instead of `fgets'.
--
-- - Deprecated function: char * gets (char *S)
--     The function `gets' reads characters from the stream `stdin' up to
--     the next newline character, and stores them in the string S.  The
--     newline character is discarded (note that this differs from the
--     behavior of `fgets', which copies the newline character into the
--     string).  If `gets' encounters a read error or end-of-file, it
--     returns a null pointer; otherwise it returns S.
--
--     *Warning:* The `gets' function is *very dangerous* because it
--     provides no protection against overflowing the string S.  The GNU
--     library includes it for compatibility only.  You should *always*
--     use `fgets' or `getline' instead.  To remind you of this, the
--     linker (if using GNU `ld') will issue a warning whenever you use
--     `gets'.
--
--
--File: libc.info,  Node: Unreading,  Next: Block Input/Output,  Prev: Line 
Input,  Up: I/O on Streams
--
--Unreading
--=========
--
--   In parser programs it is often useful to examine the next character
--in the input stream without removing it from the stream.  This is called
--"peeking ahead" at the input because your program gets a glimpse of the
--input it will read next.
--
--   Using stream I/O, you can peek ahead at input by first reading it and
--then "unreading" it (also called  "pushing it back" on the stream).
--Unreading a character makes it available to be input again from the
--stream, by  the next call to `fgetc' or other input function on that
--stream.
--
--* Menu:
--
--* Unreading Idea::              An explanation of unreading with pictures.
--* How Unread::                  How to call `ungetc' to do unreading.
--
--
--File: libc.info,  Node: Unreading Idea,  Next: How Unread,  Up: Unreading
--
--What Unreading Means
----------------------
--
--   Here is a pictorial explanation of unreading.  Suppose you have a
--stream reading a file that contains just six characters, the letters
--`foobar'.  Suppose you have read three characters so far.  The
--situation looks like this:
--
--     f  o  o  b  a  r
--              ^
--
--so the next input character will be `b'.
--
--   If instead of reading `b' you unread the letter `o', you get a
--situation like this:
--
--     f  o  o  b  a  r
--              |
--           o--
--           ^
--
--so that the next input characters will be `o' and `b'.
--
--   If you unread `9' instead of `o', you get this situation:
--
--     f  o  o  b  a  r
--              |
--           9--
--           ^
--
--so that the next input characters will be `9' and `b'.
--
--
--File: libc.info,  Node: How Unread,  Prev: Unreading Idea,  Up: Unreading
--
--Using `ungetc' To Do Unreading
--------------------------------
--
--   The function to unread a character is called `ungetc', because it
--reverses the action of `getc'.
--
-- - Function: int ungetc (int C, FILE *STREAM)
--     The `ungetc' function pushes back the character C onto the input
--     stream STREAM.  So the next input from STREAM will read C before
--     anything else.
--
--     If C is `EOF', `ungetc' does nothing and just returns `EOF'.  This
--     lets you call `ungetc' with the return value of `getc' without
--     needing to check for an error from `getc'.
--
--     The character that you push back doesn't have to be the same as
--     the last character that was actually read from the stream.  In
--     fact, it isn't necessary to actually read any characters from the
--     stream before unreading them with `ungetc'!  But that is a strange
--     way to write a program; usually `ungetc' is used only to unread a
--     character that was just read from the same stream.
--
--     The GNU C library only supports one character of pushback--in other
--     words, it does not work to call `ungetc' twice without doing input
--     in between.  Other systems might let you push back multiple
--     characters; then reading from the stream retrieves the characters
--     in the reverse order that they were pushed.
--
--     Pushing back characters doesn't alter the file; only the internal
--     buffering for the stream is affected.  If a file positioning
--     function (such as `fseek' or `rewind'; *note File Positioning::.)
--     is called, any pending pushed-back characters are discarded.
--
--     Unreading a character on a stream that is at end of file clears the
--     end-of-file indicator for the stream, because it makes the
--     character of input available.  After you read that character,
--     trying to read again will encounter end of file.
--
--   Here is an example showing the use of `getc' and `ungetc' to skip
--over whitespace characters.  When this function reaches a
--non-whitespace character, it unreads that character to be seen again on
--the next read operation on the stream.
--
--     #include <stdio.h>
--     #include <ctype.h>
--     
--     void
--     skip_whitespace (FILE *stream)
--     {
--       int c;
--       do
--         /* No need to check for `EOF' because it is not
--            `isspace', and `ungetc' ignores `EOF'.  */
--         c = getc (stream);
--       while (isspace (c));
--       ungetc (c, stream);
--     }
--
--
--File: libc.info,  Node: Block Input/Output,  Next: Formatted Output,  Prev: 
Unreading,  Up: I/O on Streams
--
--Block Input/Output
--==================
--
--   This section describes how to do input and output operations on
--blocks of data.  You can use these functions to read and write binary
--data, as well as to read and write text in fixed-size blocks instead of
--by characters or lines.
--
--   Binary files are typically used to read and write blocks of data in
--the same format as is used to represent the data in a running program.
--In other words, arbitrary blocks of memory--not just character or string
--objects--can be written to a binary file, and meaningfully read in
--again by the same program.
--
--   Storing data in binary form is often considerably more efficient than
--using the formatted I/O functions.  Also, for floating-point numbers,
--the binary form avoids possible loss of precision in the conversion
--process.  On the other hand, binary files can't be examined or modified
--easily using many standard file utilities (such as text editors), and
--are not portable between different implementations of the language, or
--different kinds of computers.
--
--   These functions are declared in `stdio.h'.
--
-- - Function: size_t fread (void *DATA, size_t SIZE, size_t COUNT, FILE
--          *STREAM)
--     This function reads up to COUNT objects of size SIZE into the
--     array DATA, from the stream STREAM.  It returns the number of
--     objects actually read, which might be less than COUNT if a read
--     error occurs or the end of the file is reached.  This function
--     returns a value of zero (and doesn't read anything) if either SIZE
--     or COUNT is zero.
--
--     If `fread' encounters end of file in the middle of an object, it
--     returns the number of complete objects read, and discards the
--     partial object.  Therefore, the stream remains at the actual end
--     of the file.
--
-- - Function: size_t fwrite (const void *DATA, size_t SIZE, size_t
--          COUNT, FILE *STREAM)
--     This function writes up to COUNT objects of size SIZE from the
--     array DATA, to the stream STREAM.  The return value is normally
--     COUNT, if the call succeeds.  Any other value indicates some sort
--     of error, such as running out of space.
--
--
--File: libc.info,  Node: Formatted Output,  Next: Customizing Printf,  Prev: 
Block Input/Output,  Up: I/O on Streams
--
--Formatted Output
--================
--
--   The functions described in this section (`printf' and related
--functions) provide a convenient way to perform formatted output.  You
--call `printf' with a "format string" or "template string" that
--specifies how to format the values of the remaining arguments.
--
--   Unless your program is a filter that specifically performs line- or
--character-oriented processing, using `printf' or one of the other
--related functions described in this section is usually the easiest and
--most concise way to perform output.  These functions are especially
--useful for printing error messages, tables of data, and the like.
--
--* Menu:
--
--* Formatted Output Basics::     Some examples to get you started.
--* Output Conversion Syntax::    General syntax of conversion
--                                 specifications.
--* Table of Output Conversions:: Summary of output conversions and
--                                 what they do.
--* Integer Conversions::         Details about formatting of integers.
--* Floating-Point Conversions::  Details about formatting of
--                                 floating-point numbers.
--* Other Output Conversions::    Details about formatting of strings,
--                                 characters, pointers, and the like.
--* Formatted Output Functions::  Descriptions of the actual functions.
--* Dynamic Output::            Functions that allocate memory for the output.
--* Variable Arguments Output::   `vprintf' and friends.
--* Parsing a Template String::   What kinds of args does a given template
--                                 call for?
--* Example of Parsing::          Sample program using `parse_printf_format'.
--
--
--File: libc.info,  Node: Formatted Output Basics,  Next: Output Conversion 
Syntax,  Up: Formatted Output
--
--Formatted Output Basics
-------------------------
--
--   The `printf' function can be used to print any number of arguments.
--The template string argument you supply in a call provides information
--not only about the number of additional arguments, but also about their
--types and what style should be used for printing them.
--
--   Ordinary characters in the template string are simply written to the
--output stream as-is, while "conversion specifications" introduced by a
--`%' character in the template cause subsequent arguments to be
--formatted and written to the output stream.  For example,
--
--     int pct = 37;
--     char filename[] = "foo.txt";
--     printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
--             filename, pct);
--
--produces output like
--
--     Processing of `foo.txt' is 37% finished.
--     Please be patient.
--
--   This example shows the use of the `%d' conversion to specify that an
--`int' argument should be printed in decimal notation, the `%s'
--conversion to specify printing of a string argument, and the `%%'
--conversion to print a literal `%' character.
--
--   There are also conversions for printing an integer argument as an
--unsigned value in octal, decimal, or hexadecimal radix (`%o', `%u', or
--`%x', respectively); or as a character value (`%c').
--
--   Floating-point numbers can be printed in normal, fixed-point notation
--using the `%f' conversion or in exponential notation using the `%e'
--conversion.  The `%g' conversion uses either `%e' or `%f' format,
--depending on what is more appropriate for the magnitude of the
--particular number.
--
--   You can control formatting more precisely by writing "modifiers"
--between the `%' and the character that indicates which conversion to
--apply.  These slightly alter the ordinary behavior of the conversion.
--For example, most conversion specifications permit you to specify a
--minimum field width and a flag indicating whether you want the result
--left- or right-justified within the field.
--
--   The specific flags and modifiers that are permitted and their
--interpretation vary depending on the particular conversion.  They're all
--described in more detail in the following sections.  Don't worry if this
--all seems excessively complicated at first; you can almost always get
--reasonable free-format output without using any of the modifiers at all.
--The modifiers are mostly used to make the output look "prettier" in
--tables.
--
--
--File: libc.info,  Node: Output Conversion Syntax,  Next: Table of Output 
Conversions,  Prev: Formatted Output Basics,  Up: Formatted Output
--
--Output Conversion Syntax
--------------------------
--
--   This section provides details about the precise syntax of conversion
--specifications that can appear in a `printf' template string.
--
--   Characters in the template string that are not part of a conversion
--specification are printed as-is to the output stream.  Multibyte
--character sequences (*note Extended Characters::.) are permitted in a
--template string.
--
--   The conversion specifications in a `printf' template string have the
--general form:
--
--     % FLAGS WIDTH [ . PRECISION ] TYPE CONVERSION
--
--   For example, in the conversion specifier `%-10.8ld', the `-' is a
--flag, `10' specifies the field width, the precision is `8', the letter
--`l' is a type modifier, and `d' specifies the conversion style.  (This
--particular type specifier says to print a `long int' argument in
--decimal notation, with a minimum of 8 digits left-justified in a field
--at least 10 characters wide.)
--
--   In more detail, output conversion specifications consist of an
--initial `%' character followed in sequence by:
--
--   * Zero or more "flag characters" that modify the normal behavior of
--     the conversion specification.
--
--   * An optional decimal integer specifying the "minimum field width".
--     If the normal conversion produces fewer characters than this, the
--     field is padded with spaces to the specified width.  This is a
--     *minimum* value; if the normal conversion produces more characters
--     than this, the field is *not* truncated.  Normally, the output is
--     right-justified within the field.
--
--     You can also specify a field width of `*'.  This means that the
--     next argument in the argument list (before the actual value to be
--     printed) is used as the field width.  The value must be an `int'.
--     If the value is negative, this means to set the `-' flag (see
--     below) and to use the absolute value as the field width.
--
--   * An optional "precision" to specify the number of digits to be
--     written for the numeric conversions.  If the precision is
--     specified, it consists of a period (`.') followed optionally by a
--     decimal integer (which defaults to zero if omitted).
--
--     You can also specify a precision of `*'.  This means that the next
--     argument in the argument list (before the actual value to be
--     printed) is used as the precision.  The value must be an `int',
--     and is ignored if it is negative.  If you specify `*' for both the
--     field width and precision, the field width argument precedes the
--     precision argument.  Other C library versions may not recognize
--     this syntax.
--
--   * An optional "type modifier character", which is used to specify the
--     data type of the corresponding argument if it differs from the
--     default type.  (For example, the integer conversions assume a type
--     of `int', but you can specify `h', `l', or `L' for other integer
--     types.)
--
--   * A character that specifies the conversion to be applied.
--
--   The exact options that are permitted and how they are interpreted
--vary between the different conversion specifiers.  See the descriptions
--of the individual conversions for information about the particular
--options that they use.
--
--   With the `-Wformat' option, the GNU C compiler checks calls to
--`printf' and related functions.  It examines the format string and
--verifies that the correct number and types of arguments are supplied.
--There is also a GNU C syntax to tell the compiler that a function you
--write uses a `printf'-style format string.  *Note Declaring Attributes
--of Functions: (gcc.info)Function Attributes, for more information.
--
--
--File: libc.info,  Node: Table of Output Conversions,  Next: Integer 
Conversions,  Prev: Output Conversion Syntax,  Up: Formatted Output
--
--Table of Output Conversions
-----------------------------
--
--   Here is a table summarizing what all the different conversions do:
--
--`%d', `%i'
--     Print an integer as a signed decimal number.  *Note Integer
--     Conversions::, for details.  `%d' and `%i' are synonymous for
--     output, but are different when used with `scanf' for input (*note
--     Table of Input Conversions::.).
--
--`%o'
--     Print an integer as an unsigned octal number.  *Note Integer
--     Conversions::, for details.
--
--`%u'
--     Print an integer as an unsigned decimal number.  *Note Integer
--     Conversions::, for details.
--
--`%x', `%X'
--     Print an integer as an unsigned hexadecimal number.  `%x' uses
--     lower-case letters and `%X' uses upper-case.  *Note Integer
--     Conversions::, for details.
--
--`%f'
--     Print a floating-point number in normal (fixed-point) notation.
--     *Note Floating-Point Conversions::, for details.
--
--`%e', `%E'
--     Print a floating-point number in exponential notation.  `%e' uses
--     lower-case letters and `%E' uses upper-case.  *Note Floating-Point
--     Conversions::, for details.
--
--`%g', `%G'
--     Print a floating-point number in either normal or exponential
--     notation, whichever is more appropriate for its magnitude.  `%g'
--     uses lower-case letters and `%G' uses upper-case.  *Note
--     Floating-Point Conversions::, for details.
--
--`%c'
--     Print a single character.  *Note Other Output Conversions::.
--
--`%s'
--     Print a string.  *Note Other Output Conversions::.
--
--`%p'
--     Print the value of a pointer.  *Note Other Output Conversions::.
--
--`%n'
--     Get the number of characters printed so far.  *Note Other Output
--     Conversions::.  Note that this conversion specification never
--     produces any output.
--
--`%m'
--     Print the string corresponding to the value of `errno'.  (This is
--     a GNU extension.) *Note Other Output Conversions::.
--
--`%%'
--     Print a literal `%' character.  *Note Other Output Conversions::.
--
--   If the syntax of a conversion specification is invalid, unpredictable
--things will happen, so don't do this.  If there aren't enough function
--arguments provided to supply values for all the conversion
--specifications in the template string, or if the arguments are not of
--the correct types, the results are unpredictable.  If you supply more
--arguments than conversion specifications, the extra argument values are
--simply ignored; this is sometimes useful.
--
--
--File: libc.info,  Node: Integer Conversions,  Next: Floating-Point 
Conversions,  Prev: Table of Output Conversions,  Up: Formatted Output
--
--Integer Conversions
---------------------
--
--   This section describes the options for the `%d', `%i', `%o', `%u',
--`%x', and `%X' conversion specifications.  These conversions print
--integers in various formats.
--
--   The `%d' and `%i' conversion specifications both print an `int'
--argument as a signed decimal number; while `%o', `%u', and `%x' print
--the argument as an unsigned octal, decimal, or hexadecimal number
--(respectively).  The `%X' conversion specification is just like `%x'
--except that it uses the characters `ABCDEF' as digits instead of
--`abcdef'.
--
--   The following flags are meaningful:
--
--`-'
--     Left-justify the result in the field (instead of the normal
--     right-justification).
--
--`+'
--     For the signed `%d' and `%i' conversions, print a plus sign if the
--     value is positive.
--
--` '
--     For the signed `%d' and `%i' conversions, if the result doesn't
--     start with a plus or minus sign, prefix it with a space character
--     instead.  Since the `+' flag ensures that the result includes a
--     sign, this flag is ignored if you supply both of them.
--
--`#'
--     For the `%o' conversion, this forces the leading digit to be `0',
--     as if by increasing the precision.  For `%x' or `%X', this
--     prefixes a leading `0x' or `0X' (respectively) to the result.
--     This doesn't do anything useful for the `%d', `%i', or `%u'
--     conversions.  Using this flag produces output which can be parsed
--     by the `strtoul' function (*note Parsing of Integers::.) and
--     `scanf' with the `%i' conversion (*note Numeric Input
--     Conversions::.).
--
--`''
--     Separate the digits into groups as specified by the locale
--     specified for the `LC_NUMERIC' category; *note General Numeric::..
--     This flag is a GNU extension.
--
--`0'
--     Pad the field with zeros instead of spaces.  The zeros are placed
--     after any indication of sign or base.  This flag is ignored if the
--     `-' flag is also specified, or if a precision is specified.
--
--   If a precision is supplied, it specifies the minimum number of
--digits to appear; leading zeros are produced if necessary.  If you
--don't specify a precision, the number is printed with as many digits as
--it needs.  If you convert a value of zero with an explicit precision of
--zero, then no characters at all are produced.
--
--   Without a type modifier, the corresponding argument is treated as an
--`int' (for the signed conversions `%i' and `%d') or `unsigned int' (for
--the unsigned conversions `%o', `%u', `%x', and `%X').  Recall that
--since `printf' and friends are variadic, any `char' and `short'
--arguments are automatically converted to `int' by the default argument
--promotions.  For arguments of other integer types, you can use these
--modifiers:
--
--`h'
--     Specifies that the argument is a `short int' or `unsigned short
--     int', as appropriate.  A `short' argument is converted to an `int'
--     or `unsigned int' by the default argument promotions anyway, but
--     the `h' modifier says to convert it back to a `short' again.
--
--`l'
--     Specifies that the argument is a `long int' or `unsigned long
--     int', as appropriate.  Two `l' characters is like the `L'
--     modifier, below.
--
--`L'
--`ll'
--`q'
--     Specifies that the argument is a `long long int'.  (This type is
--     an extension supported by the GNU C compiler.  On systems that
--     don't support extra-long integers, this is the same as `long int'.)
--
--     The `q' modifier is another name for the same thing, which comes
--     from 4.4 BSD; a `long long int' is sometimes called a "quad" `int'.
--
--`Z'
--     Specifies that the argument is a `size_t'.  This is a GNU
--     extension.
--
--   Here is an example.  Using the template string:
--
--     "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
--
--to print numbers using the different options for the `%d' conversion
--gives results like:
--
--     |    0|0    |   +0|+0   |    0|00000|     |   00|0|
--     |    1|1    |   +1|+1   |    1|00001|    1|   01|1|
--     |   -1|-1   |   -1|-1   |   -1|-0001|   -1|  -01|-1|
--     |100000|100000|+100000| 100000|100000|100000|100000|100000|
--
--   In particular, notice what happens in the last case where the number
--is too large to fit in the minimum field width specified.
--
--   Here are some more examples showing how unsigned integers print under
--various format options, using the template string:
--
--     "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
--
--     |    0|    0|    0|    0|    0|  0x0|  0X0|0x00000000|
--     |    1|    1|    1|    1|   01|  0x1|  0X1|0x00000001|
--     |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
--
--
--File: libc.info,  Node: Floating-Point Conversions,  Next: Other Output 
Conversions,  Prev: Integer Conversions,  Up: Formatted Output
--
--Floating-Point Conversions
----------------------------
--
--   This section discusses the conversion specifications for
--floating-point numbers: the `%f', `%e', `%E', `%g', and `%G'
--conversions.
--
--   The `%f' conversion prints its argument in fixed-point notation,
--producing output of the form [`-']DDD`.'DDD, where the number of digits
--following the decimal point is controlled by the precision you specify.
--
--   The `%e' conversion prints its argument in exponential notation,
--producing output of the form [`-']D`.'DDD`e'[`+'|`-']DD.  Again, the
--number of digits following the decimal point is controlled by the
--precision.  The exponent always contains at least two digits.  The `%E'
--conversion is similar but the exponent is marked with the letter `E'
--instead of `e'.
--
--   The `%g' and `%G' conversions print the argument in the style of
--`%e' or `%E' (respectively) if the exponent would be less than -4 or
--greater than or equal to the precision; otherwise they use the `%f'
--style.  Trailing zeros are removed from the fractional portion of the
--result and a decimal-point character appears only if it is followed by
--a digit.
--
--   The following flags can be used to modify the behavior:
--
--`-'
--     Left-justify the result in the field.  Normally the result is
--     right-justified.
--
--`+'
--     Always include a plus or minus sign in the result.
--
--` '
--     If the result doesn't start with a plus or minus sign, prefix it
--     with a space instead.  Since the `+' flag ensures that the result
--     includes a sign, this flag is ignored if you supply both of them.
--
--`#'
--     Specifies that the result should always include a decimal point,
--     even if no digits follow it.  For the `%g' and `%G' conversions,
--     this also forces trailing zeros after the decimal point to be left
--     in place where they would otherwise be removed.
--
--`''
--     Separate the digits of the integer part of the result into groups
--     as specified by the locale specified for the `LC_NUMERIC' category;
--     *note General Numeric::..  This flag is a GNU extension.
--
--`0'
--     Pad the field with zeros instead of spaces; the zeros are placed
--     after any sign.  This flag is ignored if the `-' flag is also
--     specified.
--
--   The precision specifies how many digits follow the decimal-point
--character for the `%f', `%e', and `%E' conversions.  For these
--conversions, the default precision is `6'.  If the precision is
--explicitly `0', this suppresses the decimal point character entirely.
--For the `%g' and `%G' conversions, the precision specifies how many
--significant digits to print.  Significant digits are the first digit
--before the decimal point, and all the digits after it.  If the
--precision `0' or not specified for `%g' or `%G', it is treated like a
--value of `1'.  If the value being printed cannot be expressed
--accurately in the specified number of digits, the value is rounded to
--the nearest number that fits.
--
--   Without a type modifier, the floating-point conversions use an
--argument of type `double'.  (By the default argument promotions, any
--`float' arguments are automatically converted to `double'.) The
--following type modifier is supported:
--
--`L'
--     An uppercase `L' specifies that the argument is a `long double'.
--
--   Here are some examples showing how numbers print using the various
--floating-point conversions.  All of the numbers were printed using this
--template string:
--
--     "|%12.4f|%12.4e|%12.4g|\n"
--
--   Here is the output:
--
--     |      0.0000|  0.0000e+00|           0|
--     |      1.0000|  1.0000e+00|           1|
--     |     -1.0000| -1.0000e+00|          -1|
--     |    100.0000|  1.0000e+02|         100|
--     |   1000.0000|  1.0000e+03|        1000|
--     |  10000.0000|  1.0000e+04|       1e+04|
--     |  12345.0000|  1.2345e+04|   1.234e+04|
--     | 100000.0000|  1.0000e+05|       1e+05|
--     | 123456.0000|  1.2346e+05|   1.234e+05|
--
--   Notice how the `%g' conversion drops trailing zeros.
--
--
--File: libc.info,  Node: Other Output Conversions,  Next: Formatted Output 
Functions,  Prev: Floating-Point Conversions,  Up: Formatted Output
--
--Other Output Conversions
--------------------------
--
--   This section describes miscellaneous conversions for `printf'.
--
--   The `%c' conversion prints a single character.  The `int' argument
--is first converted to an `unsigned char'.  The `-' flag can be used to
--specify left-justification in the field, but no other flags are
--defined, and no precision or type modifier can be given.  For example:
--
--     printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
--
--prints `hello'.
--
--   The `%s' conversion prints a string.  The corresponding argument
--must be of type `char *' (or `const char *').  A precision can be
--specified to indicate the maximum number of characters to write;
--otherwise characters in the string up to but not including the
--terminating null character are written to the output stream.  The `-'
--flag can be used to specify left-justification in the field, but no
--other flags or type modifiers are defined for this conversion.  For
--example:
--
--     printf ("%3s%-6s", "no", "where");
--
--prints ` nowhere '.
--
--   If you accidentally pass a null pointer as the argument for a `%s'
--conversion, the GNU library prints it as `(null)'.  We think this is
--more useful than crashing.  But it's not good practice to pass a null
--argument intentionally.
--
--   The `%m' conversion prints the string corresponding to the error
--code in `errno'.  *Note Error Messages::.  Thus:
--
--     fprintf (stderr, "can't open `%s': %m\n", filename);
--
--is equivalent to:
--
--     fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
--
--The `%m' conversion is a GNU C library extension.
--
--   The `%p' conversion prints a pointer value.  The corresponding
--argument must be of type `void *'.  In practice, you can use any type
--of pointer.
--
--   In the GNU system, non-null pointers are printed as unsigned
--integers, as if a `%#x' conversion were used.  Null pointers print as
--`(nil)'.  (Pointers might print differently in other systems.)
--
--   For example:
--
--     printf ("%p", "testing");
--
--prints `0x' followed by a hexadecimal number--the address of the string
--constant `"testing"'.  It does not print the word `testing'.
--
--   You can supply the `-' flag with the `%p' conversion to specify
--left-justification, but no other flags, precision, or type modifiers
--are defined.
--
--   The `%n' conversion is unlike any of the other output conversions.
--It uses an argument which must be a pointer to an `int', but instead of
--printing anything it stores the number of characters printed so far by
--this call at that location.  The `h' and `l' type modifiers are
--permitted to specify that the argument is of type `short int *' or
--`long int *' instead of `int *', but no flags, field width, or
--precision are permitted.
--
--   For example,
--
--     int nchar;
--     printf ("%d %s%n\n", 3, "bears", &nchar);
--
--prints:
--
--     3 bears
--
--and sets `nchar' to `7', because `3 bears' is seven characters.
--
--   The `%%' conversion prints a literal `%' character.  This conversion
--doesn't use an argument, and no flags, field width, precision, or type
--modifiers are permitted.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-7 
glibc-2.0.1/manual/libc.info-7
---- ../glibc-2.0.1/manual/libc.info-7  1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-7     1970-01-01 01:00:00.000000000 +0100
-@@ -1,1235 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Formatted Output Functions,  Next: Dynamic Output,  
Prev: Other Output Conversions,  Up: Formatted Output
--
--Formatted Output Functions
----------------------------
--
--   This section describes how to call `printf' and related functions.
--Prototypes for these functions are in the header file `stdio.h'.
--Because these functions take a variable number of arguments, you *must*
--declare prototypes for them before using them.  Of course, the easiest
--way to make sure you have all the right prototypes is to just include
--`stdio.h'.
--
-- - Function: int printf (const char *TEMPLATE, ...)
--     The `printf' function prints the optional arguments under the
--     control of the template string TEMPLATE to the stream `stdout'.
--     It returns the number of characters printed, or a negative value
--     if there was an output error.
--
-- - Function: int fprintf (FILE *STREAM, const char *TEMPLATE, ...)
--     This function is just like `printf', except that the output is
--     written to the stream STREAM instead of `stdout'.
--
-- - Function: int sprintf (char *S, const char *TEMPLATE, ...)
--     This is like `printf', except that the output is stored in the
--     character array S instead of written to a stream.  A null
--     character is written to mark the end of the string.
--
--     The `sprintf' function returns the number of characters stored in
--     the array S, not including the terminating null character.
--
--     The behavior of this function is undefined if copying takes place
--     between objects that overlap--for example, if S is also given as
--     an argument to be printed under control of the `%s' conversion.
--     *Note Copying and Concatenation::.
--
--     *Warning:* The `sprintf' function can be *dangerous* because it
--     can potentially output more characters than can fit in the
--     allocation size of the string S.  Remember that the field width
--     given in a conversion specification is only a *minimum* value.
--
--     To avoid this problem, you can use `snprintf' or `asprintf',
--     described below.
--
-- - Function: int snprintf (char *S, size_t SIZE, const char *TEMPLATE,
--          ...)
--     The `snprintf' function is similar to `sprintf', except that the
--     SIZE argument specifies the maximum number of characters to
--     produce.  The trailing null character is counted towards this
--     limit, so you should allocate at least SIZE characters for the
--     string S.
--
--     The return value is the number of characters stored, not including
--     the terminating null.  If this value equals `SIZE - 1', then there
--     was not enough space in S for all the output.  You should try
--     again with a bigger output string.  Here is an example of doing
--     this:
--
--          /* Construct a message describing the value of a variable
--             whose name is NAME and whose value is VALUE. */
--          char *
--          make_message (char *name, char *value)
--          {
--            /* Guess we need no more than 100 chars of space. */
--            int size = 100;
--            char *buffer = (char *) xmalloc (size);
--
--          while (1)
--              {
--                /* Try to print in the allocated space. */
--                int nchars = snprintf (buffer, size,
--                                       "value of %s is %s",
--                                       name, value);
--                /* If that worked, return the string. */
--                if (nchars < size)
--                  return buffer;
--                /* Else try again with twice as much space. */
--                size *= 2;
--                buffer = (char *) xrealloc (size, buffer);
--              }
--          }
--
--     In practice, it is often easier just to use `asprintf', below.
--
--
--File: libc.info,  Node: Dynamic Output,  Next: Variable Arguments Output,  
Prev: Formatted Output Functions,  Up: Formatted Output
--
--Dynamically Allocating Formatted Output
-----------------------------------------
--
--   The functions in this section do formatted output and place the
--results in dynamically allocated memory.
--
-- - Function: int asprintf (char **PTR, const char *TEMPLATE, ...)
--     This function is similar to `sprintf', except that it dynamically
--     allocates a string (as with `malloc'; *note Unconstrained
--     Allocation::.) to hold the output, instead of putting the output
--     in a buffer you allocate in advance.  The PTR argument should be
--     the address of a `char *' object, and `asprintf' stores a pointer
--     to the newly allocated string at that location.
--
--     Here is how to use `asprintf' to get the same result as the
--     `snprintf' example, but more easily:
--
--          /* Construct a message describing the value of a variable
--             whose name is NAME and whose value is VALUE. */
--          char *
--          make_message (char *name, char *value)
--          {
--            char *result;
--            asprintf (&result, "value of %s is %s", name, value);
--            return result;
--          }
--
-- - Function: int obstack_printf (struct obstack *OBSTACK, const char
--          *TEMPLATE, ...)
--     This function is similar to `asprintf', except that it uses the
--     obstack OBSTACK to allocate the space.  *Note Obstacks::.
--
--     The characters are written onto the end of the current object.  To
--     get at them, you must finish the object with `obstack_finish'
--     (*note Growing Objects::.).
--
--
--File: libc.info,  Node: Variable Arguments Output,  Next: Parsing a Template 
String,  Prev: Dynamic Output,  Up: Formatted Output
--
--Variable Arguments Output Functions
-------------------------------------
--
--   The functions `vprintf' and friends are provided so that you can
--define your own variadic `printf'-like functions that make use of the
--same internals as the built-in formatted output functions.
--
--   The most natural way to define such functions would be to use a
--language construct to say, "Call `printf' and pass this template plus
--all of my arguments after the first five."  But there is no way to do
--this in C, and it would be hard to provide a way, since at the C
--language level there is no way to tell how many arguments your function
--received.
--
--   Since that method is impossible, we provide alternative functions,
--the `vprintf' series, which lets you pass a `va_list' to describe "all
--of my arguments after the first five."
--
--   When it is sufficient to define a macro rather than a real function,
--the GNU C compiler provides a way to do this much more easily with
--macros.  For example:
--
--     #define myprintf(a, b, c, d, e, rest...) printf (mytemplate , ## rest...)
--
--*Note Macros with Variable Numbers of Arguments: (gcc.info)Macro
--Varargs, for details.  But this is limited to macros, and does not
--apply to real functions at all.
--
--   Before calling `vprintf' or the other functions listed in this
--section, you *must* call `va_start' (*note Variadic Functions::.) to
--initialize a pointer to the variable arguments.  Then you can call
--`va_arg' to fetch the arguments that you want to handle yourself.  This
--advances the pointer past those arguments.
--
--   Once your `va_list' pointer is pointing at the argument of your
--choice, you are ready to call `vprintf'.  That argument and all
--subsequent arguments that were passed to your function are used by
--`vprintf' along with the template that you specified separately.
--
--   In some other systems, the `va_list' pointer may become invalid
--after the call to `vprintf', so you must not use `va_arg' after you
--call `vprintf'.  Instead, you should call `va_end' to retire the
--pointer from service.  However, you can safely call `va_start' on
--another pointer variable and begin fetching the arguments again through
--that pointer.  Calling `vprintf' does not destroy the argument list of
--your function, merely the particular pointer that you passed to it.
--
--   GNU C does not have such restrictions.  You can safely continue to
--fetch arguments from a `va_list' pointer after passing it to `vprintf',
--and `va_end' is a no-op.  (Note, however, that subsequent `va_arg'
--calls will fetch the same arguments which `vprintf' previously used.)
--
--   Prototypes for these functions are declared in `stdio.h'.
--
-- - Function: int vprintf (const char *TEMPLATE, va_list AP)
--     This function is similar to `printf' except that, instead of taking
--     a variable number of arguments directly, it takes an argument list
--     pointer AP.
--
-- - Function: int vfprintf (FILE *STREAM, const char *TEMPLATE, va_list
--          AP)
--     This is the equivalent of `fprintf' with the variable argument list
--     specified directly as for `vprintf'.
--
-- - Function: int vsprintf (char *S, const char *TEMPLATE, va_list AP)
--     This is the equivalent of `sprintf' with the variable argument list
--     specified directly as for `vprintf'.
--
-- - Function: int vsnprintf (char *S, size_t SIZE, const char *TEMPLATE,
--          va_list AP)
--     This is the equivalent of `snprintf' with the variable argument
--     list specified directly as for `vprintf'.
--
-- - Function: int vasprintf (char **PTR, const char *TEMPLATE, va_list
--          AP)
--     The `vasprintf' function is the equivalent of `asprintf' with the
--     variable argument list specified directly as for `vprintf'.
--
-- - Function: int obstack_vprintf (struct obstack *OBSTACK, const char
--          *TEMPLATE, va_list AP)
--     The `obstack_vprintf' function is the equivalent of
--     `obstack_printf' with the variable argument list specified directly
--     as for `vprintf'.
--
--   Here's an example showing how you might use `vfprintf'.  This is a
--function that prints error messages to the stream `stderr', along with
--a prefix indicating the name of the program (*note Error Messages::.,
--for a description of `program_invocation_short_name').
--
--     #include <stdio.h>
--     #include <stdarg.h>
--     
--     void
--     eprintf (const char *template, ...)
--     {
--       va_list ap;
--       extern char *program_invocation_short_name;
--     
--       fprintf (stderr, "%s: ", program_invocation_short_name);
--       va_start (ap, count);
--       vfprintf (stderr, template, ap);
--       va_end (ap);
--     }
--
--You could call `eprintf' like this:
--
--     eprintf ("file `%s' does not exist\n", filename);
--
--   In GNU C, there is a special construct you can use to let the
--compiler know that a function uses a `printf'-style format string.
--Then it can check the number and types of arguments in each call to the
--function, and warn you when they do not match the format string.  For
--example, take this declaration of `eprintf':
--
--     void eprintf (const char *template, ...)
--             __attribute__ ((format (printf, 1, 2)));
--
--This tells the compiler that `eprintf' uses a format string like
--`printf' (as opposed to `scanf'; *note Formatted Input::.); the format
--string appears as the first argument; and the arguments to satisfy the
--format begin with the second.  *Note Declaring Attributes of Functions:
--(gcc.info)Function Attributes, for more information.
--
--
--File: libc.info,  Node: Parsing a Template String,  Next: Example of Parsing, 
 Prev: Variable Arguments Output,  Up: Formatted Output
--
--Parsing a Template String
---------------------------
--
--   You can use the function `parse_printf_format' to obtain information
--about the number and types of arguments that are expected by a given
--template string.  This function permits interpreters that provide
--interfaces to `printf' to avoid passing along invalid arguments from
--the user's program, which could cause a crash.
--
--   All the symbols described in this section are declared in the header
--file `printf.h'.
--
-- - Function: size_t parse_printf_format (const char *TEMPLATE, size_t
--          N, int *ARGTYPES)
--     This function returns information about the number and types of
--     arguments expected by the `printf' template string TEMPLATE.  The
--     information is stored in the array ARGTYPES; each element of this
--     array describes one argument.  This information is encoded using
--     the various `PA_' macros, listed below.
--
--     The N argument specifies the number of elements in the array
--     ARGTYPES.  This is the most elements that `parse_printf_format'
--     will try to write.
--
--     `parse_printf_format' returns the total number of arguments
--     required by TEMPLATE.  If this number is greater than N, then the
--     information returned describes only the first N arguments.  If you
--     want information about more than that many arguments, allocate a
--     bigger array and call `parse_printf_format' again.
--
--   The argument types are encoded as a combination of a basic type and
--modifier flag bits.
--
-- - Macro: int PA_FLAG_MASK
--     This macro is a bitmask for the type modifier flag bits.  You can
--     write the expression `(argtypes[i] & PA_FLAG_MASK)' to extract
--     just the flag bits for an argument, or `(argtypes[i] &
--     ~PA_FLAG_MASK)' to extract just the basic type code.
--
--   Here are symbolic constants that represent the basic types; they
--stand for integer values.
--
--`PA_INT'
--     This specifies that the base type is `int'.
--
--`PA_CHAR'
--     This specifies that the base type is `int', cast to `char'.
--
--`PA_STRING'
--     This specifies that the base type is `char *', a null-terminated
--     string.
--
--`PA_POINTER'
--     This specifies that the base type is `void *', an arbitrary
--     pointer.
--
--`PA_FLOAT'
--     This specifies that the base type is `float'.
--
--`PA_DOUBLE'
--     This specifies that the base type is `double'.
--
--`PA_LAST'
--     You can define additional base types for your own programs as
--     offsets from `PA_LAST'.  For example, if you have data types `foo'
--     and `bar' with their own specialized `printf' conversions, you
--     could define encodings for these types as:
--
--          #define PA_FOO  PA_LAST
--          #define PA_BAR  (PA_LAST + 1)
--
--   Here are the flag bits that modify a basic type.  They are combined
--with the code for the basic type using inclusive-or.
--
--`PA_FLAG_PTR'
--     If this bit is set, it indicates that the encoded type is a
--     pointer to the base type, rather than an immediate value.  For
--     example, `PA_INT|PA_FLAG_PTR' represents the type `int *'.
--
--`PA_FLAG_SHORT'
--     If this bit is set, it indicates that the base type is modified
--     with `short'.  (This corresponds to the `h' type modifier.)
--
--`PA_FLAG_LONG'
--     If this bit is set, it indicates that the base type is modified
--     with `long'.  (This corresponds to the `l' type modifier.)
--
--`PA_FLAG_LONG_LONG'
--     If this bit is set, it indicates that the base type is modified
--     with `long long'.  (This corresponds to the `L' type modifier.)
--
--`PA_FLAG_LONG_DOUBLE'
--     This is a synonym for `PA_FLAG_LONG_LONG', used by convention with
--     a base type of `PA_DOUBLE' to indicate a type of `long double'.
--
--   For an example of using these facilities, see *Note Example of
--Parsing::.
--
--
--File: libc.info,  Node: Example of Parsing,  Prev: Parsing a Template String, 
 Up: Formatted Output
--
--Example of Parsing a Template String
--------------------------------------
--
--   Here is an example of decoding argument types for a format string.
--We assume this is part of an interpreter which contains arguments of
--type `NUMBER', `CHAR', `STRING' and `STRUCTURE' (and perhaps others
--which are not valid here).
--
--     /* Test whether the NARGS specified objects
--        in the vector ARGS are valid
--        for the format string FORMAT:
--        if so, return 1.
--        If not, return 0 after printing an error message.  */
--     
--     int
--     validate_args (char *format, int nargs, OBJECT *args)
--     {
--       int *argtypes;
--       int nwanted;
--     
--       /* Get the information about the arguments.
--          Each conversion specification must be at least two characters
--          long, so there cannot be more specifications than half the
--          length of the string.  */
--     
--       argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
--       nwanted = parse_printf_format (string, nelts, argtypes);
--     
--       /* Check the number of arguments.  */
--       if (nwanted > nargs)
--         {
--           error ("too few arguments (at least %d required)", nwanted);
--           return 0;
--         }
--     
--       /* Check the C type wanted for each argument
--          and see if the object given is suitable.  */
--       for (i = 0; i < nwanted; i++)
--         {
--           int wanted;
--     
--           if (argtypes[i] & PA_FLAG_PTR)
--             wanted = STRUCTURE;
--           else
--             switch (argtypes[i] & ~PA_FLAG_MASK)
--               {
--               case PA_INT:
--               case PA_FLOAT:
--               case PA_DOUBLE:
--                 wanted = NUMBER;
--                 break;
--               case PA_CHAR:
--                 wanted = CHAR;
--                 break;
--               case PA_STRING:
--                 wanted = STRING;
--                 break;
--               case PA_POINTER:
--                 wanted = STRUCTURE;
--                 break;
--               }
--           if (TYPE (args[i]) != wanted)
--             {
--               error ("type mismatch for arg number %d", i);
--               return 0;
--             }
--         }
--       return 1;
--     }
--
--
--File: libc.info,  Node: Customizing Printf,  Next: Formatted Input,  Prev: 
Formatted Output,  Up: I/O on Streams
--
--Customizing `printf'
--====================
--
--   The GNU C library lets you define your own custom conversion
--specifiers for `printf' template strings, to teach `printf' clever ways
--to print the important data structures of your program.
--
--   The way you do this is by registering the conversion with the
--function `register_printf_function'; see *Note Registering New
--Conversions::.  One of the arguments you pass to this function is a
--pointer to a handler function that produces the actual output; see
--*Note Defining the Output Handler::, for information on how to write
--this function.
--
--   You can also install a function that just returns information about
--the number and type of arguments expected by the conversion specifier.
--*Note Parsing a Template String::, for information about this.
--
--   The facilities of this section are declared in the header file
--`printf.h'.
--
--* Menu:
--
--* Registering New Conversions::         Using `register_printf_function'
--                                         to register a new output conversion.
--* Conversion Specifier Options::        The handler must be able to get
--                                         the options specified in the
--                                         template when it is called.
--* Defining the Output Handler::         Defining the handler and arginfo
--                                         functions that are passed as 
arguments
--                                         to `register_printf_function'.
--* Printf Extension Example::            How to define a `printf'
--                                         handler function.
--
--   *Portability Note:* The ability to extend the syntax of `printf'
--template strings is a GNU extension.  ISO standard C has nothing
--similar.
--
--
--File: libc.info,  Node: Registering New Conversions,  Next: Conversion 
Specifier Options,  Up: Customizing Printf
--
--Registering New Conversions
-----------------------------
--
--   The function to register a new output conversion is
--`register_printf_function', declared in `printf.h'.
--
-- - Function: int register_printf_function (int SPEC, printf_function
--          HANDLER-FUNCTION, printf_arginfo_function ARGINFO-FUNCTION)
--     This function defines the conversion specifier character SPEC.
--     Thus, if SPEC is `'z'', it defines the conversion `%z'.  You can
--     redefine the built-in conversions like `%s', but flag characters
--     like `#' and type modifiers like `l' can never be used as
--     conversions; calling `register_printf_function' for those
--     characters has no effect.
--
--     The HANDLER-FUNCTION is the function called by `printf' and
--     friends when this conversion appears in a template string.  *Note
--     Defining the Output Handler::, for information about how to define
--     a function to pass as this argument.  If you specify a null
--     pointer, any existing handler function for SPEC is removed.
--
--     The ARGINFO-FUNCTION is the function called by
--     `parse_printf_format' when this conversion appears in a template
--     string.  *Note Parsing a Template String::, for information about
--     this.
--
--     *Attention:* In the GNU C library version before 2.0 the
--     ARGINFO-FUNCTION function did not need to be installed unless the
--     user uses the `parse_printf_format' function.  This changed.  Now
--     a call to any of the `printf' functions will call this function
--     when this format specifier appears in the format string.
--
--     The return value is `0' on success, and `-1' on failure (which
--     occurs if SPEC is out of range).
--
--     You can redefine the standard output conversions, but this is
--     probably not a good idea because of the potential for confusion.
--     Library routines written by other people could break if you do
--     this.
--
--
--File: libc.info,  Node: Conversion Specifier Options,  Next: Defining the 
Output Handler,  Prev: Registering New Conversions,  Up: Customizing Printf
--
--Conversion Specifier Options
------------------------------
--
--   If you define a meaning for `%A', what if the template contains
--`%+23A' or `%-#A'?  To implement a sensible meaning for these, the
--handler when called needs to be able to get the options specified in
--the template.
--
--   Both the HANDLER-FUNCTION and ARGINFO-FUNCTION arguments to
--`register_printf_function' accept an argument that points to a `struct
--printf_info', which contains information about the options appearing in
--an instance of the conversion specifier.  This data type is declared in
--the header file `printf.h'.
--
-- - Type: struct printf_info
--     This structure is used to pass information about the options
--     appearing in an instance of a conversion specifier in a `printf'
--     template string to the handler and arginfo functions for that
--     specifier.  It contains the following members:
--
--    `int prec'
--          This is the precision specified.  The value is `-1' if no
--          precision was specified.  If the precision was given as `*',
--          the `printf_info' structure passed to the handler function
--          contains the actual value retrieved from the argument list.
--          But the structure passed to the arginfo function contains a
--          value of `INT_MIN', since the actual value is not known.
--
--    `int width'
--          This is the minimum field width specified.  The value is `0'
--          if no width was specified.  If the field width was given as
--          `*', the `printf_info' structure passed to the handler
--          function contains the actual value retrieved from the
--          argument list.  But the structure passed to the arginfo
--          function contains a value of `INT_MIN', since the actual
--          value is not known.
--
--    `wchar_t spec'
--          This is the conversion specifier character specified.  It's
--          stored in the structure so that you can register the same
--          handler function for multiple characters, but still have a
--          way to tell them apart when the handler function is called.
--
--    `unsigned int is_long_double'
--          This is a boolean that is true if the `L', `ll', or `q' type
--          modifier was specified.  For integer conversions, this
--          indicates `long long int', as opposed to `long double' for
--          floating point conversions.
--
--    `unsigned int is_short'
--          This is a boolean that is true if the `h' type modifier was
--          specified.
--
--    `unsigned int is_long'
--          This is a boolean that is true if the `l' type modifier was
--          specified.
--
--    `unsigned int alt'
--          This is a boolean that is true if the `#' flag was specified.
--
--    `unsigned int space'
--          This is a boolean that is true if the ` ' flag was specified.
--
--    `unsigned int left'
--          This is a boolean that is true if the `-' flag was specified.
--
--    `unsigned int showsign'
--          This is a boolean that is true if the `+' flag was specified.
--
--    `unsigned int group'
--          This is a boolean that is true if the `'' flag was specified.
--
--    `unsigned int extra'
--          This flag has a special meaning depending on the context.  It
--          could be used freely by the user-defined handlers but when
--          called from the `printf' function this variable always
--          contains the value `0'.
--
--    `wchar_t pad'
--          This is the character to use for padding the output to the
--          minimum field width.  The value is `'0'' if the `0' flag was
--          specified, and `' '' otherwise.
--
--
--File: libc.info,  Node: Defining the Output Handler,  Next: Printf Extension 
Example,  Prev: Conversion Specifier Options,  Up: Customizing Printf
--
--Defining the Output Handler
-----------------------------
--
--   Now let's look at how to define the handler and arginfo functions
--which are passed as arguments to `register_printf_function'.
--
--   *Compatibility Note:* The interface change in the GNU libc version
--2.0.  Previously the third argument was of type `va_list *'.
--
--   You should define your handler functions with a prototype like:
--
--     int FUNCTION (FILE *stream, const struct printf_info *info,
--                         const void *const *args)
--
--   The STREAM argument passed to the handler function is the stream to
--which it should write output.
--
--   The INFO argument is a pointer to a structure that contains
--information about the various options that were included with the
--conversion in the template string.  You should not modify this structure
--inside your handler function.  *Note Conversion Specifier Options::, for
--a description of this data structure.
--
--   The ARGS is a vector of pointers to the arguments data.  The number
--of arguments were determined by calling the argument information
--function provided by the user.
--
--   Your handler function should return a value just like `printf' does:
--it should return the number of characters it has written, or a negative
--value to indicate an error.
--
-- - Data Type: printf_function
--     This is the data type that a handler function should have.
--
--   If you are going to use `parse_printf_format' in your application,
--you must also define a function to pass as the ARGINFO-FUNCTION
--argument for each new conversion you install with
--`register_printf_function'.
--
--   You have to define these functions with a prototype like:
--
--     int FUNCTION (const struct printf_info *info,
--                         size_t n, int *argtypes)
--
--   The return value from the function should be the number of arguments
--the conversion expects.  The function should also fill in no more than
--N elements of the ARGTYPES array with information about the types of
--each of these arguments.  This information is encoded using the various
--`PA_' macros.  (You will notice that this is the same calling
--convention `parse_printf_format' itself uses.)
--
-- - Data Type: printf_arginfo_function
--     This type is used to describe functions that return information
--     about the number and type of arguments used by a conversion
--     specifier.
--
--
--File: libc.info,  Node: Printf Extension Example,  Prev: Defining the Output 
Handler,  Up: Customizing Printf
--
--`printf' Extension Example
----------------------------
--
--   Here is an example showing how to define a `printf' handler function.
--This program defines a data structure called a `Widget' and defines the
--`%W' conversion to print information about `Widget *' arguments,
--including the pointer value and the name stored in the data structure.
--The `%W' conversion supports the minimum field width and
--left-justification options, but ignores everything else.
--
--     #include <stdio.h>
--     #include <printf.h>
--     #include <stdarg.h>
--     typedef struct
--       {
--         char *name;
--       } Widget;
--     
--     int
--     print_widget (FILE *stream, const struct printf_info *info, va_list *app)
--     {
--       Widget *w;
--       char *buffer;
--       int len;
--     
--       /* Format the output into a string. */
--       w = va_arg (*app, Widget *);
--       len = asprintf (&buffer, "<Widget %p: %s>", w, w->name);
--       if (len == -1)
--         return -1;
--     
--       /* Pad to the minimum field width and print to the stream. */
--       len = fprintf (stream, "%*s",
--                      (info->left ? - info->width : info->width),
--                      buffer);
--     
--       /* Clean up and return. */
--       free (buffer);
--       return len;
--     }
--     
--     
--     int
--     print_widget_arginfo (const struct printf_info *info, size_t n,
--                           int *argtypes)
--     {
--       /* We always take exactly one argument and this is a pointer to the
--          structure.. */
--       if (n > 0)
--         argtypes[0] = PA_POINTER;
--       return 1;
--     }
--     
--     
--     int
--     main (void)
--     {
--       /* Make a widget to print. */
--       Widget mywidget;
--       mywidget.name = "mywidget";
--     
--       /* Register the print function for widgets. */
--       register_printf_function ('W', print_widget, print_widget_arginfo);
--     
--       /* Now print the widget. */
--       printf ("|%W|\n", &mywidget);
--       printf ("|%35W|\n", &mywidget);
--       printf ("|%-35W|\n", &mywidget);
--     
--       return 0;
--     }
--
--   The output produced by this program looks like:
--
--     |<Widget 0xffeffb7c: mywidget>|
--     |      <Widget 0xffeffb7c: mywidget>|
--     |<Widget 0xffeffb7c: mywidget>      |
--
--
--File: libc.info,  Node: Formatted Input,  Next: EOF and Errors,  Prev: 
Customizing Printf,  Up: I/O on Streams
--
--Formatted Input
--===============
--
--   The functions described in this section (`scanf' and related
--functions) provide facilities for formatted input analogous to the
--formatted output facilities.  These functions provide a mechanism for
--reading arbitrary values under the control of a "format string" or
--"template string".
--
--* Menu:
--
--* Formatted Input Basics::      Some basics to get you started.
--* Input Conversion Syntax::     Syntax of conversion specifications.
--* Table of Input Conversions::  Summary of input conversions and what they do.
--* Numeric Input Conversions::   Details of conversions for reading numbers.
--* String Input Conversions::    Details of conversions for reading strings.
--* Dynamic String Input::      String conversions that `malloc' the buffer.
--* Other Input Conversions::     Details of miscellaneous other conversions.
--* Formatted Input Functions::   Descriptions of the actual functions.
--* Variable Arguments Input::    `vscanf' and friends.
--
--
--File: libc.info,  Node: Formatted Input Basics,  Next: Input Conversion 
Syntax,  Up: Formatted Input
--
--Formatted Input Basics
------------------------
--
--   Calls to `scanf' are superficially similar to calls to `printf' in
--that arbitrary arguments are read under the control of a template
--string.  While the syntax of the conversion specifications in the
--template is very similar to that for `printf', the interpretation of
--the template is oriented more towards free-format input and simple
--pattern matching, rather than fixed-field formatting.  For example,
--most `scanf' conversions skip over any amount of "white space"
--(including spaces, tabs, and newlines) in the input file, and there is
--no concept of precision for the numeric input conversions as there is
--for the corresponding output conversions.  Ordinarily, non-whitespace
--characters in the template are expected to match characters in the
--input stream exactly, but a matching failure is distinct from an input
--error on the stream.
--
--   Another area of difference between `scanf' and `printf' is that you
--must remember to supply pointers rather than immediate values as the
--optional arguments to `scanf'; the values that are read are stored in
--the objects that the pointers point to.  Even experienced programmers
--tend to forget this occasionally, so if your program is getting strange
--errors that seem to be related to `scanf', you might want to
--double-check this.
--
--   When a "matching failure" occurs, `scanf' returns immediately,
--leaving the first non-matching character as the next character to be
--read from the stream.  The normal return value from `scanf' is the
--number of values that were assigned, so you can use this to determine if
--a matching error happened before all the expected values were read.
--
--   The `scanf' function is typically used for things like reading in
--the contents of tables.  For example, here is a function that uses
--`scanf' to initialize an array of `double':
--
--     void
--     readarray (double *array, int n)
--     {
--       int i;
--       for (i=0; i<n; i++)
--         if (scanf (" %lf", &(array[i])) != 1)
--           invalid_input_error ();
--     }
--
--   The formatted input functions are not used as frequently as the
--formatted output functions.  Partly, this is because it takes some care
--to use them properly.  Another reason is that it is difficult to recover
--from a matching error.
--
--   If you are trying to read input that doesn't match a single, fixed
--pattern, you may be better off using a tool such as Flex to generate a
--lexical scanner, or Bison to generate a parser, rather than using
--`scanf'.  For more information about these tools, see *Note :
--(flex.info), and *Note : (bison.info).
--
--
--File: libc.info,  Node: Input Conversion Syntax,  Next: Table of Input 
Conversions,  Prev: Formatted Input Basics,  Up: Formatted Input
--
--Input Conversion Syntax
-------------------------
--
--   A `scanf' template string is a string that contains ordinary
--multibyte characters interspersed with conversion specifications that
--start with `%'.
--
--   Any whitespace character (as defined by the `isspace' function;
--*note Classification of Characters::.) in the template causes any number
--of whitespace characters in the input stream to be read and discarded.
--The whitespace characters that are matched need not be exactly the same
--whitespace characters that appear in the template string.  For example,
--write ` , ' in the template to recognize a comma with optional
--whitespace before and after.
--
--   Other characters in the template string that are not part of
--conversion specifications must match characters in the input stream
--exactly; if this is not the case, a matching failure occurs.
--
--   The conversion specifications in a `scanf' template string have the
--general form:
--
--     % FLAGS WIDTH TYPE CONVERSION
--
--   In more detail, an input conversion specification consists of an
--initial `%' character followed in sequence by:
--
--   * An optional "flag character" `*', which says to ignore the text
--     read for this specification.  When `scanf' finds a conversion
--     specification that uses this flag, it reads input as directed by
--     the rest of the conversion specification, but it discards this
--     input, does not use a pointer argument, and does not increment the
--     count of successful assignments.
--
--   * An optional flag character `a' (valid with string conversions only)
--     which requests allocation of a buffer long enough to store the
--     string in.  (This is a GNU extension.) *Note Dynamic String
--     Input::.
--
--   * An optional decimal integer that specifies the "maximum field
--     width".  Reading of characters from the input stream stops either
--     when this maximum is reached or when a non-matching character is
--     found, whichever happens first.  Most conversions discard initial
--     whitespace characters (those that don't are explicitly
--     documented), and these discarded characters don't count towards
--     the maximum field width.  String input conversions store a null
--     character to mark the end of the input; the maximum field width
--     does not include this terminator.
--
--   * An optional "type modifier character".  For example, you can
--     specify a type modifier of `l' with integer conversions such as
--     `%d' to specify that the argument is a pointer to a `long int'
--     rather than a pointer to an `int'.
--
--   * A character that specifies the conversion to be applied.
--
--   The exact options that are permitted and how they are interpreted
--vary between the different conversion specifiers.  See the descriptions
--of the individual conversions for information about the particular
--options that they allow.
--
--   With the `-Wformat' option, the GNU C compiler checks calls to
--`scanf' and related functions.  It examines the format string and
--verifies that the correct number and types of arguments are supplied.
--There is also a GNU C syntax to tell the compiler that a function you
--write uses a `scanf'-style format string.  *Note Declaring Attributes
--of Functions: (gcc.info)Function Attributes, for more information.
--
--
--File: libc.info,  Node: Table of Input Conversions,  Next: Numeric Input 
Conversions,  Prev: Input Conversion Syntax,  Up: Formatted Input
--
--Table of Input Conversions
----------------------------
--
--   Here is a table that summarizes the various conversion
--specifications:
--
--`%d'
--     Matches an optionally signed integer written in decimal.  *Note
--     Numeric Input Conversions::.
--
--`%i'
--     Matches an optionally signed integer in any of the formats that
--     the C language defines for specifying an integer constant.  *Note
--     Numeric Input Conversions::.
--
--`%o'
--     Matches an unsigned integer written in octal radix.  *Note Numeric
--     Input Conversions::.
--
--`%u'
--     Matches an unsigned integer written in decimal radix.  *Note
--     Numeric Input Conversions::.
--
--`%x', `%X'
--     Matches an unsigned integer written in hexadecimal radix.  *Note
--     Numeric Input Conversions::.
--
--`%e', `%f', `%g', `%E', `%G'
--     Matches an optionally signed floating-point number.  *Note Numeric
--     Input Conversions::.
--
--`%s'
--     Matches a string containing only non-whitespace characters.  *Note
--     String Input Conversions::.
--
--`%['
--     Matches a string of characters that belong to a specified set.
--     *Note String Input Conversions::.
--
--`%c'
--     Matches a string of one or more characters; the number of
--     characters read is controlled by the maximum field width given for
--     the conversion.  *Note String Input Conversions::.
--
--`%p'
--     Matches a pointer value in the same implementation-defined format
--     used by the `%p' output conversion for `printf'.  *Note Other
--     Input Conversions::.
--
--`%n'
--     This conversion doesn't read any characters; it records the number
--     of characters read so far by this call.  *Note Other Input
--     Conversions::.
--
--`%%'
--     This matches a literal `%' character in the input stream.  No
--     corresponding argument is used.  *Note Other Input Conversions::.
--
--   If the syntax of a conversion specification is invalid, the behavior
--is undefined.  If there aren't enough function arguments provided to
--supply addresses for all the conversion specifications in the template
--strings that perform assignments, or if the arguments are not of the
--correct types, the behavior is also undefined.  On the other hand, extra
--arguments are simply ignored.
--
--
--File: libc.info,  Node: Numeric Input Conversions,  Next: String Input 
Conversions,  Prev: Table of Input Conversions,  Up: Formatted Input
--
--Numeric Input Conversions
---------------------------
--
--   This section describes the `scanf' conversions for reading numeric
--values.
--
--   The `%d' conversion matches an optionally signed integer in decimal
--radix.  The syntax that is recognized is the same as that for the
--`strtol' function (*note Parsing of Integers::.) with the value `10'
--for the BASE argument.
--
--   The `%i' conversion matches an optionally signed integer in any of
--the formats that the C language defines for specifying an integer
--constant.  The syntax that is recognized is the same as that for the
--`strtol' function (*note Parsing of Integers::.) with the value `0' for
--the BASE argument.  (You can print integers in this syntax with
--`printf' by using the `#' flag character with the `%x', `%o', or `%d'
--conversion.  *Note Integer Conversions::.)
--
--   For example, any of the strings `10', `0xa', or `012' could be read
--in as integers under the `%i' conversion.  Each of these specifies a
--number with decimal value `10'.
--
--   The `%o', `%u', and `%x' conversions match unsigned integers in
--octal, decimal, and hexadecimal radices, respectively.  The syntax that
--is recognized is the same as that for the `strtoul' function (*note
--Parsing of Integers::.) with the appropriate value (`8', `10', or `16')
--for the BASE argument.
--
--   The `%X' conversion is identical to the `%x' conversion.  They both
--permit either uppercase or lowercase letters to be used as digits.
--
--   The default type of the corresponding argument for the `%d' and `%i'
--conversions is `int *', and `unsigned int *' for the other integer
--conversions.  You can use the following type modifiers to specify other
--sizes of integer:
--
--`h'
--     Specifies that the argument is a `short int *' or `unsigned short
--     int *'.
--
--`l'
--     Specifies that the argument is a `long int *' or `unsigned long
--     int *'.  Two `l' characters is like the `L' modifier, below.
--
--`ll'
--`L'
--`q'
--     Specifies that the argument is a `long long int *' or `unsigned
--     long long int *'.  (The `long long' type is an extension supported
--     by the GNU C compiler.  For systems that don't provide extra-long
--     integers, this is the same as `long int'.)
--
--     The `q' modifier is another name for the same thing, which comes
--     from 4.4 BSD; a `long long int' is sometimes called a "quad" `int'.
--
--   All of the `%e', `%f', `%g', `%E', and `%G' input conversions are
--interchangeable.  They all match an optionally signed floating point
--number, in the same syntax as for the `strtod' function (*note Parsing
--of Floats::.).
--
--   For the floating-point input conversions, the default argument type
--is `float *'.  (This is different from the corresponding output
--conversions, where the default type is `double'; remember that `float'
--arguments to `printf' are converted to `double' by the default argument
--promotions, but `float *' arguments are not promoted to `double *'.)
--You can specify other sizes of float using these type modifiers:
--
--`l'
--     Specifies that the argument is of type `double *'.
--
--`L'
--     Specifies that the argument is of type `long double *'.
--
--   For all the above number parsing formats there is an additional
--optional flag `''.  When this flag is given the `scanf' function
--expects the number represented in the input string to be formatted
--according to the grouping rules of the currently selected locale (*note
--General Numeric::.).
--
--   If the `"C"' or `"POSIX"' locale is selected there is no difference.
--But for a locale which specifies values for the appropriate fields in
--the locale the input must have the correct form in the input.
--Otherwise the longest prefix with a correct form is processed.
--
--
--File: libc.info,  Node: String Input Conversions,  Next: Dynamic String 
Input,  Prev: Numeric Input Conversions,  Up: Formatted Input
--
--String Input Conversions
--------------------------
--
--   This section describes the `scanf' input conversions for reading
--string and character values: `%s', `%[', and `%c'.
--
--   You have two options for how to receive the input from these
--conversions:
--
--   * Provide a buffer to store it in.  This is the default.  You should
--     provide an argument of type `char *'.
--
--     *Warning:* To make a robust program, you must make sure that the
--     input (plus its terminating null) cannot possibly exceed the size
--     of the buffer you provide.  In general, the only way to do this is
--     to specify a maximum field width one less than the buffer size.
--     *If you provide the buffer, always specify a maximum field width
--     to prevent overflow.*
--
--   * Ask `scanf' to allocate a big enough buffer, by specifying the `a'
--     flag character.  This is a GNU extension.  You should provide an
--     argument of type `char **' for the buffer address to be stored in.
--     *Note Dynamic String Input::.
--
--   The `%c' conversion is the simplest: it matches a fixed number of
--characters, always.  The maximum field with says how many characters to
--read; if you don't specify the maximum, the default is 1.  This
--conversion doesn't append a null character to the end of the text it
--reads.  It also does not skip over initial whitespace characters.  It
--reads precisely the next N characters, and fails if it cannot get that
--many.  Since there is always a maximum field width with `%c' (whether
--specified, or 1 by default), you can always prevent overflow by making
--the buffer long enough.
--
--   The `%s' conversion matches a string of non-whitespace characters.
--It skips and discards initial whitespace, but stops when it encounters
--more whitespace after having read something.  It stores a null character
--at the end of the text that it reads.
--
--   For example, reading the input:
--
--      hello, world
--
--with the conversion `%10c' produces `" hello, wo"', but reading the
--same input with the conversion `%10s' produces `"hello,"'.
--
--   *Warning:* If you do not specify a field width for `%s', then the
--number of characters read is limited only by where the next whitespace
--character appears.  This almost certainly means that invalid input can
--make your program crash--which is a bug.
--
--   To read in characters that belong to an arbitrary set of your choice,
--use the `%[' conversion.  You specify the set between the `[' character
--and a following `]' character, using the same syntax used in regular
--expressions.  As special cases:
--
--   * A literal `]' character can be specified as the first character of
--     the set.
--
--   * An embedded `-' character (that is, one that is not the first or
--     last character of the set) is used to specify a range of
--     characters.
--
--   * If a caret character `^' immediately follows the initial `[', then
--     the set of allowed input characters is the everything *except* the
--     characters listed.
--
--   The `%[' conversion does not skip over initial whitespace characters.
--
--   Here are some examples of `%[' conversions and what they mean:
--
--`%25[1234567890]'
--     Matches a string of up to 25 digits.
--
--`%25[][]'
--     Matches a string of up to 25 square brackets.
--
--`%25[^ \f\n\r\t\v]'
--     Matches a string up to 25 characters long that doesn't contain any
--     of the standard whitespace characters.  This is slightly different
--     from `%s', because if the input begins with a whitespace character,
--     `%[' reports a matching failure while `%s' simply discards the
--     initial whitespace.
--
--`%25[a-z]'
--     Matches up to 25 lowercase characters.
--
--   One more reminder: the `%s' and `%[' conversions are *dangerous* if
--you don't specify a maximum width or use the `a' flag, because input
--too long would overflow whatever buffer you have provided for it.  No
--matter how long your buffer is, a user could supply input that is
--longer.  A well-written program reports invalid input with a
--comprehensible error message, not with a crash.
--
--
--File: libc.info,  Node: Dynamic String Input,  Next: Other Input Conversions, 
 Prev: String Input Conversions,  Up: Formatted Input
--
--Dynamically Allocating String Conversions
-------------------------------------------
--
--   A GNU extension to formatted input lets you safely read a string
--with no maximum size.  Using this feature, you don't supply a buffer;
--instead, `scanf' allocates a buffer big enough to hold the data and
--gives you its address.  To use this feature, write `a' as a flag
--character, as in `%as' or `%a[0-9a-z]'.
--
--   The pointer argument you supply for where to store the input should
--have type `char **'.  The `scanf' function allocates a buffer and
--stores its address in the word that the argument points to.  You should
--free the buffer with `free' when you no longer need it.
--
--   Here is an example of using the `a' flag with the `%[...]'
--conversion specification to read a "variable assignment" of the form
--`VARIABLE = VALUE'.
--
--     {
--       char *variable, *value;
--     
--       if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
--                      &variable, &value))
--         {
--           invalid_input_error ();
--           return 0;
--         }
--     
--       ...
--     }
--
--
--File: libc.info,  Node: Other Input Conversions,  Next: Formatted Input 
Functions,  Prev: Dynamic String Input,  Up: Formatted Input
--
--Other Input Conversions
-------------------------
--
--   This section describes the miscellaneous input conversions.
--
--   The `%p' conversion is used to read a pointer value.  It recognizes
--the same syntax as is used by the `%p' output conversion for `printf'
--(*note Other Output Conversions::.); that is, a hexadecimal number just
--as the `%x' conversion accepts.  The corresponding argument should be
--of type `void **'; that is, the address of a place to store a pointer.
--
--   The resulting pointer value is not guaranteed to be valid if it was
--not originally written during the same program execution that reads it
--in.
--
--   The `%n' conversion produces the number of characters read so far by
--this call.  The corresponding argument should be of type `int *'.  This
--conversion works in the same way as the `%n' conversion for `printf';
--see *Note Other Output Conversions::, for an example.
--
--   The `%n' conversion is the only mechanism for determining the
--success of literal matches or conversions with suppressed assignments.
--If the `%n' follows the locus of a matching failure, then no value is
--stored for it since `scanf' returns before processing the `%n'.  If you
--store `-1' in that argument slot before calling `scanf', the presence
--of `-1' after `scanf' indicates an error occurred before the `%n' was
--reached.
--
--   Finally, the `%%' conversion matches a literal `%' character in the
--input stream, without using an argument.  This conversion does not
--permit any flags, field width, or type modifier to be specified.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-8 
glibc-2.0.1/manual/libc.info-8
---- ../glibc-2.0.1/manual/libc.info-8  1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-8     1970-01-01 01:00:00.000000000 +0100
-@@ -1,1094 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: Formatted Input Functions,  Next: Variable Arguments 
Input,  Prev: Other Input Conversions,  Up: Formatted Input
--
--Formatted Input Functions
---------------------------
--
--   Here are the descriptions of the functions for performing formatted
--input.  Prototypes for these functions are in the header file `stdio.h'.
--
-- - Function: int scanf (const char *TEMPLATE, ...)
--     The `scanf' function reads formatted input from the stream `stdin'
--     under the control of the template string TEMPLATE.  The optional
--     arguments are pointers to the places which receive the resulting
--     values.
--
--     The return value is normally the number of successful assignments.
--     If an end-of-file condition is detected before any matches are
--     performed (including matches against whitespace and literal
--     characters in the template), then `EOF' is returned.
--
-- - Function: int fscanf (FILE *STREAM, const char *TEMPLATE, ...)
--     This function is just like `scanf', except that the input is read
--     from the stream STREAM instead of `stdin'.
--
-- - Function: int sscanf (const char *S, const char *TEMPLATE, ...)
--     This is like `scanf', except that the characters are taken from the
--     null-terminated string S instead of from a stream.  Reaching the
--     end of the string is treated as an end-of-file condition.
--
--     The behavior of this function is undefined if copying takes place
--     between objects that overlap--for example, if S is also given as
--     an argument to receive a string read under control of the `%s'
--     conversion.
--
--
--File: libc.info,  Node: Variable Arguments Input,  Prev: Formatted Input 
Functions,  Up: Formatted Input
--
--Variable Arguments Input Functions
------------------------------------
--
--   The functions `vscanf' and friends are provided so that you can
--define your own variadic `scanf'-like functions that make use of the
--same internals as the built-in formatted output functions.  These
--functions are analogous to the `vprintf' series of output functions.
--*Note Variable Arguments Output::, for important information on how to
--use them.
--
--   *Portability Note:* The functions listed in this section are GNU
--extensions.
--
-- - Function: int vscanf (const char *TEMPLATE, va_list AP)
--     This function is similar to `scanf' except that, instead of taking
--     a variable number of arguments directly, it takes an argument list
--     pointer AP of type `va_list' (*note Variadic Functions::.).
--
-- - Function: int vfscanf (FILE *STREAM, const char *TEMPLATE, va_list
--          AP)
--     This is the equivalent of `fscanf' with the variable argument list
--     specified directly as for `vscanf'.
--
-- - Function: int vsscanf (const char *S, const char *TEMPLATE, va_list
--          AP)
--     This is the equivalent of `sscanf' with the variable argument list
--     specified directly as for `vscanf'.
--
--   In GNU C, there is a special construct you can use to let the
--compiler know that a function uses a `scanf'-style format string.  Then
--it can check the number and types of arguments in each call to the
--function, and warn you when they do not match the format string.  *Note
--Declaring Attributes of Functions: (gcc.info)Function Attributes, for
--details.
--
--
--File: libc.info,  Node: EOF and Errors,  Next: Binary Streams,  Prev: 
Formatted Input,  Up: I/O on Streams
--
--End-Of-File and Errors
--======================
--
--   Many of the functions described in this chapter return the value of
--the macro `EOF' to indicate unsuccessful completion of the operation.
--Since `EOF' is used to report both end of file and random errors, it's
--often better to use the `feof' function to check explicitly for end of
--file and `ferror' to check for errors.  These functions check
--indicators that are part of the internal state of the stream object,
--indicators set if the appropriate condition was detected by a previous
--I/O operation on that stream.
--
--   These symbols are declared in the header file `stdio.h'.
--
-- - Macro: int EOF
--     This macro is an integer value that is returned by a number of
--     functions to indicate an end-of-file condition, or some other
--     error situation.  With the GNU library, `EOF' is `-1'.  In other
--     libraries, its value may be some other negative number.
--
-- - Function: void clearerr (FILE *STREAM)
--     This function clears the end-of-file and error indicators for the
--     stream STREAM.
--
--     The file positioning functions (*note File Positioning::.) also
--     clear the end-of-file indicator for the stream.
--
-- - Function: int feof (FILE *STREAM)
--     The `feof' function returns nonzero if and only if the end-of-file
--     indicator for the stream STREAM is set.
--
-- - Function: int ferror (FILE *STREAM)
--     The `ferror' function returns nonzero if and only if the error
--     indicator for the stream STREAM is set, indicating that an error
--     has occurred on a previous operation on the stream.
--
--   In addition to setting the error indicator associated with the
--stream, the functions that operate on streams also set `errno' in the
--same way as the corresponding low-level functions that operate on file
--descriptors.  For example, all of the functions that perform output to a
--stream--such as `fputc', `printf', and `fflush'--are implemented in
--terms of `write', and all of the `errno' error conditions defined for
--`write' are meaningful for these functions.  For more information about
--the descriptor-level I/O functions, see *Note Low-Level I/O::.
--
--
--File: libc.info,  Node: Binary Streams,  Next: File Positioning,  Prev: EOF 
and Errors,  Up: I/O on Streams
--
--Text and Binary Streams
--=======================
--
--   The GNU system and other POSIX-compatible operating systems organize
--all files as uniform sequences of characters.  However, some other
--systems make a distinction between files containing text and files
--containing binary data, and the input and output facilities of ISO C
--provide for this distinction.  This section tells you how to write
--programs portable to such systems.
--
--   When you open a stream, you can specify either a "text stream" or a
--"binary stream".  You indicate that you want a binary stream by
--specifying the `b' modifier in the OPENTYPE argument to `fopen'; see
--*Note Opening Streams::.  Without this option, `fopen' opens the file
--as a text stream.
--
--   Text and binary streams differ in several ways:
--
--   * The data read from a text stream is divided into "lines" which are
--     terminated by newline (`'\n'') characters, while a binary stream is
--     simply a long series of characters.  A text stream might on some
--     systems fail to handle lines more than 254 characters long
--     (including the terminating newline character).
--
--   * On some systems, text files can contain only printing characters,
--     horizontal tab characters, and newlines, and so text streams may
--     not support other characters.  However, binary streams can handle
--     any character value.
--
--   * Space characters that are written immediately preceding a newline
--     character in a text stream may disappear when the file is read in
--     again.
--
--   * More generally, there need not be a one-to-one mapping between
--     characters that are read from or written to a text stream, and the
--     characters in the actual file.
--
--   Since a binary stream is always more capable and more predictable
--than a text stream, you might wonder what purpose text streams serve.
--Why not simply always use binary streams?  The answer is that on these
--operating systems, text and binary streams use different file formats,
--and the only way to read or write "an ordinary file of text" that can
--work with other text-oriented programs is through a text stream.
--
--   In the GNU library, and on all POSIX systems, there is no difference
--between text streams and binary streams.  When you open a stream, you
--get the same kind of stream regardless of whether you ask for binary.
--This stream can handle any file content, and has none of the
--restrictions that text streams sometimes have.
--
--
--File: libc.info,  Node: File Positioning,  Next: Portable Positioning,  Prev: 
Binary Streams,  Up: I/O on Streams
--
--File Positioning
--================
--
--   The "file position" of a stream describes where in the file the
--stream is currently reading or writing.  I/O on the stream advances the
--file position through the file.  In the GNU system, the file position is
--represented as an integer, which counts the number of bytes from the
--beginning of the file.  *Note File Position::.
--
--   During I/O to an ordinary disk file, you can change the file position
--whenever you wish, so as to read or write any portion of the file.  Some
--other kinds of files may also permit this.  Files which support changing
--the file position are sometimes referred to as "random-access" files.
--
--   You can use the functions in this section to examine or modify the
--file position indicator associated with a stream.  The symbols listed
--below are declared in the header file `stdio.h'.
--
-- - Function: long int ftell (FILE *STREAM)
--     This function returns the current file position of the stream
--     STREAM.
--
--     This function can fail if the stream doesn't support file
--     positioning, or if the file position can't be represented in a
--     `long int', and possibly for other reasons as well.  If a failure
--     occurs, a value of `-1' is returned.
--
-- - Function: int fseek (FILE *STREAM, long int OFFSET, int WHENCE)
--     The `fseek' function is used to change the file position of the
--     stream STREAM.  The value of WHENCE must be one of the constants
--     `SEEK_SET', `SEEK_CUR', or `SEEK_END', to indicate whether the
--     OFFSET is relative to the beginning of the file, the current file
--     position, or the end of the file, respectively.
--
--     This function returns a value of zero if the operation was
--     successful, and a nonzero value to indicate failure.  A successful
--     call also clears the end-of-file indicator of STREAM and discards
--     any characters that were "pushed back" by the use of `ungetc'.
--
--     `fseek' either flushes any buffered output before setting the file
--     position or else remembers it so it will be written later in its
--     proper place in the file.
--
--   *Portability Note:* In non-POSIX systems, `ftell' and `fseek' might
--work reliably only on binary streams.  *Note Binary Streams::.
--
--   The following symbolic constants are defined for use as the WHENCE
--argument to `fseek'.  They are also used with the `lseek' function
--(*note I/O Primitives::.) and to specify offsets for file locks (*note
--Control Operations::.).
--
-- - Macro: int SEEK_SET
--     This is an integer constant which, when used as the WHENCE
--     argument to the `fseek' function, specifies that the offset
--     provided is relative to the beginning of the file.
--
-- - Macro: int SEEK_CUR
--     This is an integer constant which, when used as the WHENCE
--     argument to the `fseek' function, specifies that the offset
--     provided is relative to the current file position.
--
-- - Macro: int SEEK_END
--     This is an integer constant which, when used as the WHENCE
--     argument to the `fseek' function, specifies that the offset
--     provided is relative to the end of the file.
--
-- - Function: void rewind (FILE *STREAM)
--     The `rewind' function positions the stream STREAM at the begining
--     of the file.  It is equivalent to calling `fseek' on the STREAM
--     with an OFFSET argument of `0L' and a WHENCE argument of
--     `SEEK_SET', except that the return value is discarded and the
--     error indicator for the stream is reset.
--
--   These three aliases for the `SEEK_...' constants exist for the sake
--of compatibility with older BSD systems.  They are defined in two
--different header files: `fcntl.h' and `sys/file.h'.
--
--`L_SET'
--     An alias for `SEEK_SET'.
--
--`L_INCR'
--     An alias for `SEEK_CUR'.
--
--`L_XTND'
--     An alias for `SEEK_END'.
--
--
--File: libc.info,  Node: Portable Positioning,  Next: Stream Buffering,  Prev: 
File Positioning,  Up: I/O on Streams
--
--Portable File-Position Functions
--================================
--
--   On the GNU system, the file position is truly a character count.  You
--can specify any character count value as an argument to `fseek' and get
--reliable results for any random access file.  However, some ISO C
--systems do not represent file positions in this way.
--
--   On some systems where text streams truly differ from binary streams,
--it is impossible to represent the file position of a text stream as a
--count of characters from the beginning of the file.  For example, the
--file position on some systems must encode both a record offset within
--the file, and a character offset within the record.
--
--   As a consequence, if you want your programs to be portable to these
--systems, you must observe certain rules:
--
--   * The value returned from `ftell' on a text stream has no predictable
--     relationship to the number of characters you have read so far.
--     The only thing you can rely on is that you can use it subsequently
--     as the OFFSET argument to `fseek' to move back to the same file
--     position.
--
--   * In a call to `fseek' on a text stream, either the OFFSET must
--     either be zero; or WHENCE must be `SEEK_SET' and the OFFSET must
--     be the result of an earlier call to `ftell' on the same stream.
--
--   * The value of the file position indicator of a text stream is
--     undefined while there are characters that have been pushed back
--     with `ungetc' that haven't been read or discarded.  *Note
--     Unreading::.
--
--   But even if you observe these rules, you may still have trouble for
--long files, because `ftell' and `fseek' use a `long int' value to
--represent the file position.  This type may not have room to encode all
--the file positions in a large file.
--
--   So if you do want to support systems with peculiar encodings for the
--file positions, it is better to use the functions `fgetpos' and
--`fsetpos' instead.  These functions represent the file position using
--the data type `fpos_t', whose internal representation varies from
--system to system.
--
--   These symbols are declared in the header file `stdio.h'.
--
-- - Data Type: fpos_t
--     This is the type of an object that can encode information about the
--     file position of a stream, for use by the functions `fgetpos' and
--     `fsetpos'.
--
--     In the GNU system, `fpos_t' is equivalent to `off_t' or `long
--     int'.  In other systems, it might have a different internal
--     representation.
--
-- - Function: int fgetpos (FILE *STREAM, fpos_t *POSITION)
--     This function stores the value of the file position indicator for
--     the stream STREAM in the `fpos_t' object pointed to by POSITION.
--     If successful, `fgetpos' returns zero; otherwise it returns a
--     nonzero value and stores an implementation-defined positive value
--     in `errno'.
--
-- - Function: int fsetpos (FILE *STREAM, const fpos_t POSITION)
--     This function sets the file position indicator for the stream
--     STREAM to the position POSITION, which must have been set by a
--     previous call to `fgetpos' on the same stream.  If successful,
--     `fsetpos' clears the end-of-file indicator on the stream, discards
--     any characters that were "pushed back" by the use of `ungetc', and
--     returns a value of zero.  Otherwise, `fsetpos' returns a nonzero
--     value and stores an implementation-defined positive value in
--     `errno'.
--
--
--File: libc.info,  Node: Stream Buffering,  Next: Other Kinds of Streams,  
Prev: Portable Positioning,  Up: I/O on Streams
--
--Stream Buffering
--================
--
--   Characters that are written to a stream are normally accumulated and
--transmitted asynchronously to the file in a block, instead of appearing
--as soon as they are output by the application program.  Similarly,
--streams often retrieve input from the host environment in blocks rather
--than on a character-by-character basis.  This is called "buffering".
--
--   If you are writing programs that do interactive input and output
--using streams, you need to understand how buffering works when you
--design the user interface to your program.  Otherwise, you might find
--that output (such as progress or prompt messages) doesn't appear when
--you intended it to, or other unexpected behavior.
--
--   This section deals only with controlling when characters are
--transmitted between the stream and the file or device, and *not* with
--how things like echoing, flow control, and the like are handled on
--specific classes of devices.  For information on common control
--operations on terminal devices, see *Note Low-Level Terminal
--Interface::.
--
--   You can bypass the stream buffering facilities altogether by using
--the low-level input and output functions that operate on file
--descriptors instead.  *Note Low-Level I/O::.
--
--* Menu:
--
--* Buffering Concepts::          Terminology is defined here.
--* Flushing Buffers::            How to ensure that output buffers are flushed.
--* Controlling Buffering::       How to specify what kind of buffering to use.
--
--
--File: libc.info,  Node: Buffering Concepts,  Next: Flushing Buffers,  Up: 
Stream Buffering
--
--Buffering Concepts
--------------------
--
--   There are three different kinds of buffering strategies:
--
--   * Characters written to or read from an "unbuffered" stream are
--     transmitted individually to or from the file as soon as possible.
--
--   * Characters written to a "line buffered" stream are transmitted to
--     the file in blocks when a newline character is encountered.
--
--   * Characters written to or read from a "fully buffered" stream are
--     transmitted to or from the file in blocks of arbitrary size.
--
--   Newly opened streams are normally fully buffered, with one
--exception: a stream connected to an interactive device such as a
--terminal is initially line buffered.  *Note Controlling Buffering::,
--for information on how to select a different kind of buffering.
--Usually the automatic selection gives you the most convenient kind of
--buffering for the file or device you open.
--
--   The use of line buffering for interactive devices implies that output
--messages ending in a newline will appear immediately--which is usually
--what you want.  Output that doesn't end in a newline might or might not
--show up immediately, so if you want them to appear immediately, you
--should flush buffered output explicitly with `fflush', as described in
--*Note Flushing Buffers::.
--
--
--File: libc.info,  Node: Flushing Buffers,  Next: Controlling Buffering,  
Prev: Buffering Concepts,  Up: Stream Buffering
--
--Flushing Buffers
------------------
--
--   "Flushing" output on a buffered stream means transmitting all
--accumulated characters to the file.  There are many circumstances when
--buffered output on a stream is flushed automatically:
--
--   * When you try to do output and the output buffer is full.
--
--   * When the stream is closed.  *Note Closing Streams::.
--
--   * When the program terminates by calling `exit'.  *Note Normal
--     Termination::.
--
--   * When a newline is written, if the stream is line buffered.
--
--   * Whenever an input operation on *any* stream actually reads data
--     from its file.
--
--   If you want to flush the buffered output at another time, call
--`fflush', which is declared in the header file `stdio.h'.
--
-- - Function: int fflush (FILE *STREAM)
--     This function causes any buffered output on STREAM to be delivered
--     to the file.  If STREAM is a null pointer, then `fflush' causes
--     buffered output on *all* open output streams to be flushed.
--
--     This function returns `EOF' if a write error occurs, or zero
--     otherwise.
--
--   *Compatibility Note:* Some brain-damaged operating systems have been
--known to be so thoroughly fixated on line-oriented input and output
--that flushing a line buffered stream causes a newline to be written!
--Fortunately, this "feature" seems to be becoming less common.  You do
--not need to worry about this in the GNU system.
--
--
--File: libc.info,  Node: Controlling Buffering,  Prev: Flushing Buffers,  Up: 
Stream Buffering
--
--Controlling Which Kind of Buffering
-------------------------------------
--
--   After opening a stream (but before any other operations have been
--performed on it), you can explicitly specify what kind of buffering you
--want it to have using the `setvbuf' function.
--
--   The facilities listed in this section are declared in the header
--file `stdio.h'.
--
-- - Function: int setvbuf (FILE *STREAM, char *BUF, int MODE, size_t
--          SIZE)
--     This function is used to specify that the stream STREAM should
--     have the buffering mode MODE, which can be either `_IOFBF' (for
--     full buffering), `_IOLBF' (for line buffering), or `_IONBF' (for
--     unbuffered input/output).
--
--     If you specify a null pointer as the BUF argument, then `setvbuf'
--     allocates a buffer itself using `malloc'.  This buffer will be
--     freed when you close the stream.
--
--     Otherwise, BUF should be a character array that can hold at least
--     SIZE characters.  You should not free the space for this array as
--     long as the stream remains open and this array remains its buffer.
--     You should usually either allocate it statically, or `malloc'
--     (*note Unconstrained Allocation::.) the buffer.  Using an
--     automatic array is not a good idea unless you close the file
--     before exiting the block that declares the array.
--
--     While the array remains a stream buffer, the stream I/O functions
--     will use the buffer for their internal purposes.  You shouldn't
--     try to access the values in the array directly while the stream is
--     using it for buffering.
--
--     The `setvbuf' function returns zero on success, or a nonzero value
--     if the value of MODE is not valid or if the request could not be
--     honored.
--
-- - Macro: int _IOFBF
--     The value of this macro is an integer constant expression that can
--     be used as the MODE argument to the `setvbuf' function to specify
--     that the stream should be fully buffered.
--
-- - Macro: int _IOLBF
--     The value of this macro is an integer constant expression that can
--     be used as the MODE argument to the `setvbuf' function to specify
--     that the stream should be line buffered.
--
-- - Macro: int _IONBF
--     The value of this macro is an integer constant expression that can
--     be used as the MODE argument to the `setvbuf' function to specify
--     that the stream should be unbuffered.
--
-- - Macro: int BUFSIZ
--     The value of this macro is an integer constant expression that is
--     good to use for the SIZE argument to `setvbuf'.  This value is
--     guaranteed to be at least `256'.
--
--     The value of `BUFSIZ' is chosen on each system so as to make stream
--     I/O efficient.  So it is a good idea to use `BUFSIZ' as the size
--     for the buffer when you call `setvbuf'.
--
--     Actually, you can get an even better value to use for the buffer
--     size by means of the `fstat' system call: it is found in the
--     `st_blksize' field of the file attributes.  *Note Attribute
--     Meanings::.
--
--     Sometimes people also use `BUFSIZ' as the allocation size of
--     buffers used for related purposes, such as strings used to receive
--     a line of input with `fgets' (*note Character Input::.).  There is
--     no particular reason to use `BUFSIZ' for this instead of any other
--     integer, except that it might lead to doing I/O in chunks of an
--     efficient size.
--
-- - Function: void setbuf (FILE *STREAM, char *BUF)
--     If BUF is a null pointer, the effect of this function is
--     equivalent to calling `setvbuf' with a MODE argument of `_IONBF'.
--     Otherwise, it is equivalent to calling `setvbuf' with BUF, and a
--     MODE of `_IOFBF' and a SIZE argument of `BUFSIZ'.
--
--     The `setbuf' function is provided for compatibility with old code;
--     use `setvbuf' in all new programs.
--
-- - Function: void setbuffer (FILE *STREAM, char *BUF, size_t SIZE)
--     If BUF is a null pointer, this function makes STREAM unbuffered.
--     Otherwise, it makes STREAM fully buffered using BUF as the buffer.
--     The SIZE argument specifies the length of BUF.
--
--     This function is provided for compatibility with old BSD code.  Use
--     `setvbuf' instead.
--
-- - Function: void setlinebuf (FILE *STREAM)
--     This function makes STREAM be line buffered, and allocates the
--     buffer for you.
--
--     This function is provided for compatibility with old BSD code.  Use
--     `setvbuf' instead.
--
--
--File: libc.info,  Node: Other Kinds of Streams,  Prev: Stream Buffering,  Up: 
I/O on Streams
--
--Other Kinds of Streams
--======================
--
--   The GNU library provides ways for you to define additional kinds of
--streams that do not necessarily correspond to an open file.
--
--   One such type of stream takes input from or writes output to a
--string.  These kinds of streams are used internally to implement the
--`sprintf' and `sscanf' functions.  You can also create such a stream
--explicitly, using the functions described in *Note String Streams::.
--
--   More generally, you can define streams that do input/output to
--arbitrary objects using functions supplied by your program.  This
--protocol is discussed in *Note Custom Streams::.
--
--   *Portability Note:* The facilities described in this section are
--specific to GNU.  Other systems or C implementations might or might not
--provide equivalent functionality.
--
--* Menu:
--
--* String Streams::              Streams that get data from or put data in
--                                 a string or memory buffer.
--* Obstack Streams::           Streams that store data in an obstack.
--* Custom Streams::              Defining your own streams with an arbitrary
--                                 input data source and/or output data sink.
--
--
--File: libc.info,  Node: String Streams,  Next: Obstack Streams,  Up: Other 
Kinds of Streams
--
--String Streams
----------------
--
--   The `fmemopen' and `open_memstream' functions allow you to do I/O to
--a string or memory buffer.  These facilities are declared in `stdio.h'.
--
-- - Function: FILE * fmemopen (void *BUF, size_t SIZE, const char
--          *OPENTYPE)
--     This function opens a stream that allows the access specified by
--     the OPENTYPE argument, that reads from or writes to the buffer
--     specified by the argument BUF.  This array must be at least SIZE
--     bytes long.
--
--     If you specify a null pointer as the BUF argument, `fmemopen'
--     dynamically allocates (as with `malloc'; *note Unconstrained
--     Allocation::.) an array SIZE bytes long.  This is really only
--     useful if you are going to write things to the buffer and then
--     read them back in again, because you have no way of actually
--     getting a pointer to the buffer (for this, try `open_memstream',
--     below).  The buffer is freed when the stream is open.
--
--     The argument OPENTYPE is the same as in `fopen' (*Note Opening
--     Streams::).  If the OPENTYPE specifies append mode, then the
--     initial file position is set to the first null character in the
--     buffer.  Otherwise the initial file position is at the beginning
--     of the buffer.
--
--     When a stream open for writing is flushed or closed, a null
--     character (zero byte) is written at the end of the buffer if it
--     fits.  You should add an extra byte to the SIZE argument to
--     account for this.  Attempts to write more than SIZE bytes to the
--     buffer result in an error.
--
--     For a stream open for reading, null characters (zero bytes) in the
--     buffer do not count as "end of file".  Read operations indicate
--     end of file only when the file position advances past SIZE bytes.
--     So, if you want to read characters from a null-terminated string,
--     you should supply the length of the string as the SIZE argument.
--
--   Here is an example of using `fmemopen' to create a stream for
--reading from a string:
--
--     #include <stdio.h>
--     
--     static char buffer[] = "foobar";
--     
--     int
--     main (void)
--     {
--       int ch;
--       FILE *stream;
--     
--       stream = fmemopen (buffer, strlen (buffer), "r");
--       while ((ch = fgetc (stream)) != EOF)
--         printf ("Got %c\n", ch);
--       fclose (stream);
--     
--       return 0;
--     }
--
--   This program produces the following output:
--
--     Got f
--     Got o
--     Got o
--     Got b
--     Got a
--     Got r
--
-- - Function: FILE * open_memstream (char **PTR, size_t *SIZELOC)
--     This function opens a stream for writing to a buffer.  The buffer
--     is allocated dynamically (as with `malloc'; *note Unconstrained
--     Allocation::.) and grown as necessary.
--
--     When the stream is closed with `fclose' or flushed with `fflush',
--     the locations PTR and SIZELOC are updated to contain the pointer
--     to the buffer and its size.  The values thus stored remain valid
--     only as long as no further output on the stream takes place.  If
--     you do more output, you must flush the stream again to store new
--     values before you use them again.
--
--     A null character is written at the end of the buffer.  This null
--     character is *not* included in the size value stored at SIZELOC.
--
--     You can move the stream's file position with `fseek' (*note File
--     Positioning::.).  Moving the file position past the end of the data
--     already written fills the intervening space with zeroes.
--
--   Here is an example of using `open_memstream':
--
--     #include <stdio.h>
--     
--     int
--     main (void)
--     {
--       char *bp;
--       size_t size;
--       FILE *stream;
--     
--       stream = open_memstream (&bp, &size);
--       fprintf (stream, "hello");
--       fflush (stream);
--       printf ("buf = `%s', size = %d\n", bp, size);
--       fprintf (stream, ", world");
--       fclose (stream);
--       printf ("buf = `%s', size = %d\n", bp, size);
--     
--       return 0;
--     }
--
--   This program produces the following output:
--
--     buf = `hello', size = 5
--     buf = `hello, world', size = 12
--
--
--File: libc.info,  Node: Obstack Streams,  Next: Custom Streams,  Prev: String 
Streams,  Up: Other Kinds of Streams
--
--Obstack Streams
-----------------
--
--   You can open an output stream that puts it data in an obstack.
--*Note Obstacks::.
--
-- - Function: FILE * open_obstack_stream (struct obstack *OBSTACK)
--     This function opens a stream for writing data into the obstack
--     OBSTACK.  This starts an object in the obstack and makes it grow
--     as data is written (*note Growing Objects::.).
--
--     Calling `fflush' on this stream updates the current size of the
--     object to match the amount of data that has been written.  After a
--     call to `fflush', you can examine the object temporarily.
--
--     You can move the file position of an obstack stream with `fseek'
--     (*note File Positioning::.).  Moving the file position past the
--     end of the data written fills the intervening space with zeros.
--
--     To make the object permanent, update the obstack with `fflush', and
--     then use `obstack_finish' to finalize the object and get its
--     address.  The following write to the stream starts a new object in
--     the obstack, and later writes add to that object until you do
--     another `fflush' and `obstack_finish'.
--
--     But how do you find out how long the object is?  You can get the
--     length in bytes by calling `obstack_object_size' (*note Status of
--     an Obstack::.), or you can null-terminate the object like this:
--
--          obstack_1grow (OBSTACK, 0);
--
--     Whichever one you do, you must do it *before* calling
--     `obstack_finish'.  (You can do both if you wish.)
--
--   Here is a sample function that uses `open_obstack_stream':
--
--     char *
--     make_message_string (const char *a, int b)
--     {
--       FILE *stream = open_obstack_stream (&message_obstack);
--       output_task (stream);
--       fprintf (stream, ": ");
--       fprintf (stream, a, b);
--       fprintf (stream, "\n");
--       fclose (stream);
--       obstack_1grow (&message_obstack, 0);
--       return obstack_finish (&message_obstack);
--     }
--
--
--File: libc.info,  Node: Custom Streams,  Prev: Obstack Streams,  Up: Other 
Kinds of Streams
--
--Programming Your Own Custom Streams
-------------------------------------
--
--   This section describes how you can make a stream that gets input
--from an arbitrary data source or writes output to an arbitrary data sink
--programmed by you.  We call these "custom streams".
--
--* Menu:
--
--* Streams and Cookies::         The "cookie" records where to fetch or
--                                 store data that is read or written.
--* Hook Functions::              How you should define the four "hook
--                                 functions" that a custom stream needs.
--
--
--File: libc.info,  Node: Streams and Cookies,  Next: Hook Functions,  Up: 
Custom Streams
--
--Custom Streams and Cookies
--..........................
--
--   Inside every custom stream is a special object called the "cookie".
--This is an object supplied by you which records where to fetch or store
--the data read or written.  It is up to you to define a data type to use
--for the cookie.  The stream functions in the library never refer
--directly to its contents, and they don't even know what the type is;
--they record its address with type `void *'.
--
--   To implement a custom stream, you must specify *how* to fetch or
--store the data in the specified place.  You do this by defining "hook
--functions" to read, write, change "file position", and close the
--stream.  All four of these functions will be passed the stream's cookie
--so they can tell where to fetch or store the data.  The library
--functions don't know what's inside the cookie, but your functions will
--know.
--
--   When you create a custom stream, you must specify the cookie pointer,
--and also the four hook functions stored in a structure of type
--`cookie_io_functions_t'.
--
--   These facilities are declared in `stdio.h'.
--
-- - Data Type: cookie_io_functions_t
--     This is a structure type that holds the functions that define the
--     communications protocol between the stream and its cookie.  It has
--     the following members:
--
--    `cookie_read_function_t *read'
--          This is the function that reads data from the cookie.  If the
--          value is a null pointer instead of a function, then read
--          operations on ths stream always return `EOF'.
--
--    `cookie_write_function_t *write'
--          This is the function that writes data to the cookie.  If the
--          value is a null pointer instead of a function, then data
--          written to the stream is discarded.
--
--    `cookie_seek_function_t *seek'
--          This is the function that performs the equivalent of file
--          positioning on the cookie.  If the value is a null pointer
--          instead of a function, calls to `fseek' on this stream can
--          only seek to locations within the buffer; any attempt to seek
--          outside the buffer will return an `ESPIPE' error.
--
--    `cookie_close_function_t *close'
--          This function performs any appropriate cleanup on the cookie
--          when closing the stream.  If the value is a null pointer
--          instead of a function, nothing special is done to close the
--          cookie when the stream is closed.
--
-- - Function: FILE * fopencookie (void *COOKIE, const char *OPENTYPE,
--          cookie_io_functions_t IO-FUNCTIONS)
--     This function actually creates the stream for communicating with
--     the COOKIE using the functions in the IO-FUNCTIONS argument.  The
--     OPENTYPE argument is interpreted as for `fopen'; see *Note Opening
--     Streams::.  (But note that the "truncate on open" option is
--     ignored.)  The new stream is fully buffered.
--
--     The `fopencookie' function returns the newly created stream, or a
--     null pointer in case of an error.
--
--
--File: libc.info,  Node: Hook Functions,  Prev: Streams and Cookies,  Up: 
Custom Streams
--
--Custom Stream Hook Functions
--............................
--
--   Here are more details on how you should define the four hook
--functions that a custom stream needs.
--
--   You should define the function to read data from the cookie as:
--
--     ssize_t READER (void *COOKIE, void *BUFFER, size_t SIZE)
--
--   This is very similar to the `read' function; see *Note I/O
--Primitives::.  Your function should transfer up to SIZE bytes into the
--BUFFER, and return the number of bytes read, or zero to indicate
--end-of-file.  You can return a value of `-1' to indicate an error.
--
--   You should define the function to write data to the cookie as:
--
--     ssize_t WRITER (void *COOKIE, const void *BUFFER, size_t SIZE)
--
--   This is very similar to the `write' function; see *Note I/O
--Primitives::.  Your function should transfer up to SIZE bytes from the
--buffer, and return the number of bytes written.  You can return a value
--of `-1' to indicate an error.
--
--   You should define the function to perform seek operations on the
--cookie as:
--
--     int SEEKER (void *COOKIE, fpos_t *POSITION, int WHENCE)
--
--   For this function, the POSITION and WHENCE arguments are interpreted
--as for `fgetpos'; see *Note Portable Positioning::.  In the GNU
--library, `fpos_t' is equivalent to `off_t' or `long int', and simply
--represents the number of bytes from the beginning of the file.
--
--   After doing the seek operation, your function should store the
--resulting file position relative to the beginning of the file in
--POSITION.  Your function should return a value of `0' on success and
--`-1' to indicate an error.
--
--   You should define the function to do cleanup operations on the cookie
--appropriate for closing the stream as:
--
--     int CLEANER (void *COOKIE)
--
--   Your function should return `-1' to indicate an error, and `0'
--otherwise.
--
-- - Data Type: cookie_read_function
--     This is the data type that the read function for a custom stream
--     should have.  If you declare the function as shown above, this is
--     the type it will have.
--
-- - Data Type: cookie_write_function
--     The data type of the write function for a custom stream.
--
-- - Data Type: cookie_seek_function
--     The data type of the seek function for a custom stream.
--
-- - Data Type: cookie_close_function
--     The data type of the close function for a custom stream.
--
--
--File: libc.info,  Node: Low-Level I/O,  Next: File System Interface,  Prev: 
I/O on Streams,  Up: Top
--
--Low-Level Input/Output
--**********************
--
--   This chapter describes functions for performing low-level
--input/output operations on file descriptors.  These functions include
--the primitives for the higher-level I/O functions described in *Note
--I/O on Streams::, as well as functions for performing low-level control
--operations for which there are no equivalents on streams.
--
--   Stream-level I/O is more flexible and usually more convenient;
--therefore, programmers generally use the descriptor-level functions only
--when necessary.  These are some of the usual reasons:
--
--   * For reading binary files in large chunks.
--
--   * For reading an entire file into core before parsing it.
--
--   * To perform operations other than data transfer, which can only be
--     done with a descriptor.  (You can use `fileno' to get the
--     descriptor corresponding to a stream.)
--
--   * To pass descriptors to a child process.  (The child can create its
--     own stream to use a descriptor that it inherits, but cannot
--     inherit a stream directly.)
--
--* Menu:
--
--* Opening and Closing Files::           How to open and close file
--                                         descriptors.
--* I/O Primitives::                      Reading and writing data.
--* File Position Primitive::             Setting a descriptor's file
--                                         position.
--* Descriptors and Streams::             Converting descriptor to stream
--                                         or vice-versa.
--* Stream/Descriptor Precautions::       Precautions needed if you use both
--                                         descriptors and streams.
--* Waiting for I/O::                     How to check for input or output
--                                       on multiple file descriptors.
--* Control Operations::                  Various other operations on file
--                                       descriptors.
--* Duplicating Descriptors::             Fcntl commands for duplicating
--                                         file descriptors.
--* Descriptor Flags::                    Fcntl commands for manipulating
--                                         flags associated with file
--                                         descriptors.
--* File Status Flags::                   Fcntl commands for manipulating
--                                         flags associated with open files.
--* File Locks::                          Fcntl commands for implementing
--                                         file locking.
--* Interrupt Input::                     Getting an asynchronous signal when
--                                         input arrives.
--
--
--File: libc.info,  Node: Opening and Closing Files,  Next: I/O Primitives,  
Up: Low-Level I/O
--
--Opening and Closing Files
--=========================
--
--   This section describes the primitives for opening and closing files
--using file descriptors.  The `open' and `creat' functions are declared
--in the header file `fcntl.h', while `close' is declared in `unistd.h'.
--
-- - Function: int open (const char *FILENAME, int FLAGS[, mode_t MODE])
--     The `open' function creates and returns a new file descriptor for
--     the file named by FILENAME.  Initially, the file position
--     indicator for the file is at the beginning of the file.  The
--     argument MODE is used only when a file is created, but it doesn't
--     hurt to supply the argument in any case.
--
--     The FLAGS argument controls how the file is to be opened.  This is
--     a bit mask; you create the value by the bitwise OR of the
--     appropriate parameters (using the `|' operator in C).  *Note File
--     Status Flags::, for the parameters available.
--
--     The normal return value from `open' is a non-negative integer file
--     descriptor.  In the case of an error, a value of `-1' is returned
--     instead.  In addition to the usual file name errors (*note File
--     Name Errors::.), the following `errno' error conditions are defined
--     for this function:
--
--    `EACCES'
--          The file exists but is not readable/writable as requested by
--          the FLAGS argument, the file does not exist and the directory
--          is unwritable so it cannot be created.
--
--    `EEXIST'
--          Both `O_CREAT' and `O_EXCL' are set, and the named file
--          already exists.
--
--    `EINTR'
--          The `open' operation was interrupted by a signal.  *Note
--          Interrupted Primitives::.
--
--    `EISDIR'
--          The FLAGS argument specified write access, and the file is a
--          directory.
--
--    `EMFILE'
--          The process has too many files open.  The maximum number of
--          file descriptors is controlled by the `RLIMIT_NOFILE'
--          resource limit; *note Limits on Resources::..
--
--    `ENFILE'
--          The entire system, or perhaps the file system which contains
--          the directory, cannot support any additional open files at
--          the moment.  (This problem cannot happen on the GNU system.)
--
--    `ENOENT'
--          The named file does not exist, and `O_CREAT' is not specified.
--
--    `ENOSPC'
--          The directory or file system that would contain the new file
--          cannot be extended, because there is no disk space left.
--
--    `ENXIO'
--          `O_NONBLOCK' and `O_WRONLY' are both set in the FLAGS
--          argument, the file named by FILENAME is a FIFO (*note Pipes
--          and FIFOs::.), and no process has the file open for reading.
--
--    `EROFS'
--          The file resides on a read-only file system and any of
--          `O_WRONLY', `O_RDWR', and `O_TRUNC' are set in the FLAGS
--          argument, or `O_CREAT' is set and the file does not already
--          exist.
--
--     The `open' function is the underlying primitive for the `fopen'
--     and `freopen' functions, that create streams.
--
-- - Obsolete function: int creat (const char *FILENAME, mode_t MODE)
--     This function is obsolete.  The call:
--
--          creat (FILENAME, MODE)
--
--     is equivalent to:
--
--          open (FILENAME, O_WRONLY | O_CREAT | O_TRUNC, MODE)
--
-- - Function: int close (int FILEDES)
--     The function `close' closes the file descriptor FILEDES.  Closing
--     a file has the following consequences:
--
--        * The file descriptor is deallocated.
--
--        * Any record locks owned by the process on the file are
--          unlocked.
--
--        * When all file descriptors associated with a pipe or FIFO have
--          been closed, any unread data is discarded.
--
--     The normal return value from `close' is `0'; a value of `-1' is
--     returned in case of failure.  The following `errno' error
--     conditions are defined for this function:
--
--    `EBADF'
--          The FILEDES argument is not a valid file descriptor.
--
--    `EINTR'
--          The `close' call was interrupted by a signal.  *Note
--          Interrupted Primitives::.  Here is an example of how to
--          handle `EINTR' properly:
--
--               TEMP_FAILURE_RETRY (close (desc));
--
--    `ENOSPC'
--    `EIO'
--    `EDQUOT'
--          When the file is accessed by NFS, these errors from `write'
--          can sometimes not be detected until `close'.  *Note I/O
--          Primitives::, for details on their meaning.
--
--   To close a stream, call `fclose' (*note Closing Streams::.) instead
--of trying to close its underlying file descriptor with `close'.  This
--flushes any buffered output and updates the stream object to indicate
--that it is closed.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-9 
glibc-2.0.1/manual/libc.info-9
---- ../glibc-2.0.1/manual/libc.info-9  1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-9     1970-01-01 01:00:00.000000000 +0100
-@@ -1,1169 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
--   This file documents the GNU C library.
--
--   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
--   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
--   Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
--   Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
--   Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info,  Node: I/O Primitives,  Next: File Position Primitive,  
Prev: Opening and Closing Files,  Up: Low-Level I/O
--
--Input and Output Primitives
--===========================
--
--   This section describes the functions for performing primitive input
--and output operations on file descriptors: `read', `write', and
--`lseek'.  These functions are declared in the header file `unistd.h'.
--
-- - Data Type: ssize_t
--     This data type is used to represent the sizes of blocks that can be
--     read or written in a single operation.  It is similar to `size_t',
--     but must be a signed type.
--
-- - Function: ssize_t read (int FILEDES, void *BUFFER, size_t SIZE)
--     The `read' function reads up to SIZE bytes from the file with
--     descriptor FILEDES, storing the results in the BUFFER.  (This is
--     not necessarily a character string and there is no terminating
--     null character added.)
--
--     The return value is the number of bytes actually read.  This might
--     be less than SIZE; for example, if there aren't that many bytes
--     left in the file or if there aren't that many bytes immediately
--     available.  The exact behavior depends on what kind of file it is.
--     Note that reading less than SIZE bytes is not an error.
--
--     A value of zero indicates end-of-file (except if the value of the
--     SIZE argument is also zero).  This is not considered an error.  If
--     you keep calling `read' while at end-of-file, it will keep
--     returning zero and doing nothing else.
--
--     If `read' returns at least one character, there is no way you can
--     tell whether end-of-file was reached.  But if you did reach the
--     end, the next read will return zero.
--
--     In case of an error, `read' returns `-1'.  The following `errno'
--     error conditions are defined for this function:
--
--    `EAGAIN'
--          Normally, when no input is immediately available, `read'
--          waits for some input.  But if the `O_NONBLOCK' flag is set
--          for the file (*note File Status Flags::.), `read' returns
--          immediately without reading any data, and reports this error.
--
--          *Compatibility Note:* Most versions of BSD Unix use a
--          different error code for this: `EWOULDBLOCK'.  In the GNU
--          library, `EWOULDBLOCK' is an alias for `EAGAIN', so it
--          doesn't matter which name you use.
--
--          On some systems, reading a large amount of data from a
--          character special file can also fail with `EAGAIN' if the
--          kernel cannot find enough physical memory to lock down the
--          user's pages.  This is limited to devices that transfer with
--          direct memory access into the user's memory, which means it
--          does not include terminals, since they always use separate
--          buffers inside the kernel.  This problem never happens in the
--          GNU system.
--
--          Any condition that could result in `EAGAIN' can instead
--          result in a successful `read' which returns fewer bytes than
--          requested.  Calling `read' again immediately would result in
--          `EAGAIN'.
--
--    `EBADF'
--          The FILEDES argument is not a valid file descriptor, or is
--          not open for reading.
--
--    `EINTR'
--          `read' was interrupted by a signal while it was waiting for
--          input.  *Note Interrupted Primitives::.  A signal will not
--          necessary cause `read' to return `EINTR'; it may instead
--          result in a successful `read' which returns fewer bytes than
--          requested.
--
--    `EIO'
--          For many devices, and for disk files, this error code
--          indicates a hardware error.
--
--          `EIO' also occurs when a background process tries to read
--          from the controlling terminal, and the normal action of
--          stopping the process by sending it a `SIGTTIN' signal isn't
--          working.  This might happen if signal is being blocked or
--          ignored, or because the process group is orphaned.  *Note Job
--          Control::, for more information about job control, and *Note
--          Signal Handling::, for information about signals.
--
--     The `read' function is the underlying primitive for all of the
--     functions that read from streams, such as `fgetc'.
--
-- - Function: ssize_t write (int FILEDES, const void *BUFFER, size_t
--          SIZE)
--     The `write' function writes up to SIZE bytes from BUFFER to the
--     file with descriptor FILEDES.  The data in BUFFER is not
--     necessarily a character string and a null character is output like
--     any other character.
--
--     The return value is the number of bytes actually written.  This
--     may be SIZE, but can always be smaller.  Your program should
--     always call `write' in a loop, iterating until all the data is
--     written.
--
--     Once `write' returns, the data is enqueued to be written and can be
--     read back right away, but it is not necessarily written out to
--     permanent storage immediately.  You can use `fsync' when you need
--     to be sure your data has been permanently stored before
--     continuing.  (It is more efficient for the system to batch up
--     consecutive writes and do them all at once when convenient.
--     Normally they will always be written to disk within a minute or
--     less.) You can use the `O_FSYNC' open mode to make `write' always
--     store the data to disk before returning; *note Operating Modes::..
--
--     In the case of an error, `write' returns `-1'.  The following
--     `errno' error conditions are defined for this function:
--
--    `EAGAIN'
--          Normally, `write' blocks until the write operation is
--          complete.  But if the `O_NONBLOCK' flag is set for the file
--          (*note Control Operations::.), it returns immediately without
--          writing any data, and reports this error.  An example of a
--          situation that might cause the process to block on output is
--          writing to a terminal device that supports flow control,
--          where output has been suspended by receipt of a STOP
--          character.
--
--          *Compatibility Note:* Most versions of BSD Unix use a
--          different error code for this: `EWOULDBLOCK'.  In the GNU
--          library, `EWOULDBLOCK' is an alias for `EAGAIN', so it
--          doesn't matter which name you use.
--
--          On some systems, writing a large amount of data from a
--          character special file can also fail with `EAGAIN' if the
--          kernel cannot find enough physical memory to lock down the
--          user's pages.  This is limited to devices that transfer with
--          direct memory access into the user's memory, which means it
--          does not include terminals, since they always use separate
--          buffers inside the kernel.  This problem does not arise in the
--          GNU system.
--
--    `EBADF'
--          The FILEDES argument is not a valid file descriptor, or is
--          not open for writing.
--
--    `EFBIG'
--          The size of the file would become larger than the
--          implementation can support.
--
--    `EINTR'
--          The `write' operation was interrupted by a signal while it was
--          blocked waiting for completion.  A signal will not necessary
--          cause `write' to return `EINTR'; it may instead result in a
--          successful `write' which writes fewer bytes than requested.
--          *Note Interrupted Primitives::.
--
--    `EIO'
--          For many devices, and for disk files, this error code
--          indicates a hardware error.
--
--    `ENOSPC'
--          The device containing the file is full.
--
--    `EPIPE'
--          This error is returned when you try to write to a pipe or
--          FIFO that isn't open for reading by any process.  When this
--          happens, a `SIGPIPE' signal is also sent to the process; see
--          *Note Signal Handling::.
--
--     Unless you have arranged to prevent `EINTR' failures, you should
--     check `errno' after each failing call to `write', and if the error
--     was `EINTR', you should simply repeat the call.  *Note Interrupted
--     Primitives::.  The easy way to do this is with the macro
--     `TEMP_FAILURE_RETRY', as follows:
--
--          nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
--
--     The `write' function is the underlying primitive for all of the
--     functions that write to streams, such as `fputc'.
--
--
--File: libc.info,  Node: File Position Primitive,  Next: Descriptors and 
Streams,  Prev: I/O Primitives,  Up: Low-Level I/O
--
--Setting the File Position of a Descriptor
--=========================================
--
--   Just as you can set the file position of a stream with `fseek', you
--can set the file position of a descriptor with `lseek'.  This specifies
--the position in the file for the next `read' or `write' operation.
--*Note File Positioning::, for more information on the file position and
--what it means.
--
--   To read the current file position value from a descriptor, use
--`lseek (DESC, 0, SEEK_CUR)'.
--
-- - Function: off_t lseek (int FILEDES, off_t OFFSET, int WHENCE)
--     The `lseek' function is used to change the file position of the
--     file with descriptor FILEDES.
--
--     The WHENCE argument specifies how the OFFSET should be interpreted
--     in the same way as for the `fseek' function, and must be one of
--     the symbolic constants `SEEK_SET', `SEEK_CUR', or `SEEK_END'.
--
--    `SEEK_SET'
--          Specifies that WHENCE is a count of characters from the
--          beginning of the file.
--
--    `SEEK_CUR'
--          Specifies that WHENCE is a count of characters from the
--          current file position.  This count may be positive or
--          negative.
--
--    `SEEK_END'
--          Specifies that WHENCE is a count of characters from the end of
--          the file.  A negative count specifies a position within the
--          current extent of the file; a positive count specifies a
--          position past the current end.  If you set the position past
--          the current end, and actually write data, you will extend the
--          file with zeros up to that position.  The return value from
--     `lseek' is normally the resulting file position, measured in bytes
--     from the beginning of the file.  You can use this feature together
--     with `SEEK_CUR' to read the current file position.
--
--     If you want to append to the file, setting the file position to the
--     current end of file with `SEEK_END' is not sufficient.  Another
--     process may write more data after you seek but before you write,
--     extending the file so the position you write onto clobbers their
--     data.  Instead, use the `O_APPEND' operating mode; *note Operating
--     Modes::..
--
--     You can set the file position past the current end of the file.
--     This does not by itself make the file longer; `lseek' never
--     changes the file.  But subsequent output at that position will
--     extend the file.  Characters between the previous end of file and
--     the new position are filled with zeros.  Extending the file in
--     this way can create a "hole": the blocks of zeros are not actually
--     allocated on disk, so the file takes up less space than it appears
--     so; it is then called a "sparse file".
--
--     If the file position cannot be changed, or the operation is in
--     some way invalid, `lseek' returns a value of `-1'.  The following
--     `errno' error conditions are defined for this function:
--
--    `EBADF'
--          The FILEDES is not a valid file descriptor.
--
--    `EINVAL'
--          The WHENCE argument value is not valid, or the resulting file
--          offset is not valid.  A file offset is invalid.
--
--    `ESPIPE'
--          The FILEDES corresponds to an object that cannot be
--          positioned, such as a pipe, FIFO or terminal device.
--          (POSIX.1 specifies this error only for pipes and FIFOs, but
--          in the GNU system, you always get `ESPIPE' if the object is
--          not seekable.)
--
--     The `lseek' function is the underlying primitive for the `fseek',
--     `ftell' and `rewind' functions, which operate on streams instead
--     of file descriptors.
--
--   You can have multiple descriptors for the same file if you open the
--file more than once, or if you duplicate a descriptor with `dup'.
--Descriptors that come from separate calls to `open' have independent
--file positions; using `lseek' on one descriptor has no effect on the
--other.  For example,
--
--     {
--       int d1, d2;
--       char buf[4];
--       d1 = open ("foo", O_RDONLY);
--       d2 = open ("foo", O_RDONLY);
--       lseek (d1, 1024, SEEK_SET);
--       read (d2, buf, 4);
--     }
--
--will read the first four characters of the file `foo'.  (The
--error-checking code necessary for a real program has been omitted here
--for brevity.)
--
--   By contrast, descriptors made by duplication share a common file
--position with the original descriptor that was duplicated.  Anything
--which alters the file position of one of the duplicates, including
--reading or writing data, affects all of them alike.  Thus, for example,
--
--     {
--       int d1, d2, d3;
--       char buf1[4], buf2[4];
--       d1 = open ("foo", O_RDONLY);
--       d2 = dup (d1);
--       d3 = dup (d2);
--       lseek (d3, 1024, SEEK_SET);
--       read (d1, buf1, 4);
--       read (d2, buf2, 4);
--     }
--
--will read four characters starting with the 1024'th character of `foo',
--and then four more characters starting with the 1028'th character.
--
-- - Data Type: off_t
--     This is an arithmetic data type used to represent file sizes.  In
--     the GNU system, this is equivalent to `fpos_t' or `long int'.
--
--   These aliases for the `SEEK_...' constants exist for the sake of
--compatibility with older BSD systems.  They are defined in two
--different header files: `fcntl.h' and `sys/file.h'.
--
--`L_SET'
--     An alias for `SEEK_SET'.
--
--`L_INCR'
--     An alias for `SEEK_CUR'.
--
--`L_XTND'
--     An alias for `SEEK_END'.
--
--
--File: libc.info,  Node: Descriptors and Streams,  Next: Stream/Descriptor 
Precautions,  Prev: File Position Primitive,  Up: Low-Level I/O
--
--Descriptors and Streams
--=======================
--
--   Given an open file descriptor, you can create a stream for it with
--the `fdopen' function.  You can get the underlying file descriptor for
--an existing stream with the `fileno' function.  These functions are
--declared in the header file `stdio.h'.
--
-- - Function: FILE * fdopen (int FILEDES, const char *OPENTYPE)
--     The `fdopen' function returns a new stream for the file descriptor
--     FILEDES.
--
--     The OPENTYPE argument is interpreted in the same way as for the
--     `fopen' function (*note Opening Streams::.), except that the `b'
--     option is not permitted; this is because GNU makes no distinction
--     between text and binary files.  Also, `"w"' and `"w+"' do not
--     cause truncation of the file; these have affect only when opening
--     a file, and in this case the file has already been opened.  You
--     must make sure that the OPENTYPE argument matches the actual mode
--     of the open file descriptor.
--
--     The return value is the new stream.  If the stream cannot be
--     created (for example, if the modes for the file indicated by the
--     file descriptor do not permit the access specified by the OPENTYPE
--     argument), a null pointer is returned instead.
--
--     In some other systems, `fdopen' may fail to detect that the modes
--     for file descriptor do not permit the access specified by
--     `opentype'.  The GNU C library always checks for this.
--
--   For an example showing the use of the `fdopen' function, see *Note
--Creating a Pipe::.
--
-- - Function: int fileno (FILE *STREAM)
--     This function returns the file descriptor associated with the
--     stream STREAM.  If an error is detected (for example, if the STREAM
--     is not valid) or if STREAM does not do I/O to a file, `fileno'
--     returns `-1'.
--
--   There are also symbolic constants defined in `unistd.h' for the file
--descriptors belonging to the standard streams `stdin', `stdout', and
--`stderr'; see *Note Standard Streams::.
--
--`STDIN_FILENO'
--     This macro has value `0', which is the file descriptor for
--     standard input.
--
--`STDOUT_FILENO'
--     This macro has value `1', which is the file descriptor for
--     standard output.
--
--`STDERR_FILENO'
--     This macro has value `2', which is the file descriptor for
--     standard error output.
--
--
--File: libc.info,  Node: Stream/Descriptor Precautions,  Next: Waiting for 
I/O,  Prev: Descriptors and Streams,  Up: Low-Level I/O
--
--Dangers of Mixing Streams and Descriptors
--=========================================
--
--   You can have multiple file descriptors and streams (let's call both
--streams and descriptors "channels" for short) connected to the same
--file, but you must take care to avoid confusion between channels.  There
--are two cases to consider: "linked" channels that share a single file
--position value, and "independent" channels that have their own file
--positions.
--
--   It's best to use just one channel in your program for actual data
--transfer to any given file, except when all the access is for input.
--For example, if you open a pipe (something you can only do at the file
--descriptor level), either do all I/O with the descriptor, or construct a
--stream from the descriptor with `fdopen' and then do all I/O with the
--stream.
--
--* Menu:
--
--* Linked Channels::      Dealing with channels sharing a file position.
--* Independent Channels::   Dealing with separately opened, unlinked channels.
--* Cleaning Streams::     Cleaning a stream makes it safe to use
--                            another channel.
--
--
--File: libc.info,  Node: Linked Channels,  Next: Independent Channels,  Up: 
Stream/Descriptor Precautions
--
--Linked Channels
-----------------
--
--   Channels that come from a single opening share the same file
--position; we call them "linked" channels.  Linked channels result when
--you make a stream from a descriptor using `fdopen', when you get a
--descriptor from a stream with `fileno', when you copy a descriptor with
--`dup' or `dup2', and when descriptors are inherited during `fork'.  For
--files that don't support random access, such as terminals and pipes,
--*all* channels are effectively linked.  On random-access files, all
--append-type output streams are effectively linked to each other.
--
--   If you have been using a stream for I/O, and you want to do I/O using
--another channel (either a stream or a descriptor) that is linked to it,
--you must first "clean up" the stream that you have been using.  *Note
--Cleaning Streams::.
--
--   Terminating a process, or executing a new program in the process,
--destroys all the streams in the process.  If descriptors linked to these
--streams persist in other processes, their file positions become
--undefined as a result.  To prevent this, you must clean up the streams
--before destroying them.
--
--
--File: libc.info,  Node: Independent Channels,  Next: Cleaning Streams,  Prev: 
Linked Channels,  Up: Stream/Descriptor Precautions
--
--Independent Channels
----------------------
--
--   When you open channels (streams or descriptors) separately on a
--seekable file, each channel has its own file position.  These are called
--"independent channels".
--
--   The system handles each channel independently.  Most of the time,
--this is quite predictable and natural (especially for input): each
--channel can read or write sequentially at its own place in the file.
--However, if some of the channels are streams, you must take these
--precautions:
--
--   * You should clean an output stream after use, before doing anything
--     else that might read or write from the same part of the file.
--
--   * You should clean an input stream before reading data that may have
--     been modified using an independent channel.  Otherwise, you might
--     read obsolete data that had been in the stream's buffer.
--
--   If you do output to one channel at the end of the file, this will
--certainly leave the other independent channels positioned somewhere
--before the new end.  You cannot reliably set their file positions to the
--new end of file before writing, because the file can always be extended
--by another process between when you set the file position and when you
--write the data.  Instead, use an append-type descriptor or stream; they
--always output at the current end of the file.  In order to make the
--end-of-file position accurate, you must clean the output channel you
--were using, if it is a stream.
--
--   It's impossible for two channels to have separate file pointers for a
--file that doesn't support random access.  Thus, channels for reading or
--writing such files are always linked, never independent.  Append-type
--channels are also always linked.  For these channels, follow the rules
--for linked channels; see *Note Linked Channels::.
--
--
--File: libc.info,  Node: Cleaning Streams,  Prev: Independent Channels,  Up: 
Stream/Descriptor Precautions
--
--Cleaning Streams
------------------
--
--   On the GNU system, you can clean up any stream with `fclean':
--
-- - Function: int fclean (FILE *STREAM)
--     Clean up the stream STREAM so that its buffer is empty.  If STREAM
--     is doing output, force it out.  If STREAM is doing input, give the
--     data in the buffer back to the system, arranging to reread it.
--
--   On other systems, you can use `fflush' to clean a stream in most
--cases.
--
--   You can skip the `fclean' or `fflush' if you know the stream is
--already clean.  A stream is clean whenever its buffer is empty.  For
--example, an unbuffered stream is always clean.  An input stream that is
--at end-of-file is clean.  A line-buffered stream is clean when the last
--character output was a newline.
--
--   There is one case in which cleaning a stream is impossible on most
--systems.  This is when the stream is doing input from a file that is not
--random-access.  Such streams typically read ahead, and when the file is
--not random access, there is no way to give back the excess data already
--read.  When an input stream reads from a random-access file, `fflush'
--does clean the stream, but leaves the file pointer at an unpredictable
--place; you must set the file pointer before doing any further I/O.  On
--the GNU system, using `fclean' avoids both of these problems.
--
--   Closing an output-only stream also does `fflush', so this is a valid
--way of cleaning an output stream.  On the GNU system, closing an input
--stream does `fclean'.
--
--   You need not clean a stream before using its descriptor for control
--operations such as setting terminal modes; these operations don't affect
--the file position and are not affected by it.  You can use any
--descriptor for these operations, and all channels are affected
--simultaneously.  However, text already "output" to a stream but still
--buffered by the stream will be subject to the new terminal modes when
--subsequently flushed.  To make sure "past" output is covered by the
--terminal settings that were in effect at the time, flush the output
--streams for that terminal before setting the modes.  *Note Terminal
--Modes::.
--
--
--File: libc.info,  Node: Waiting for I/O,  Next: Control Operations,  Prev: 
Stream/Descriptor Precautions,  Up: Low-Level I/O
--
--Waiting for Input or Output
--===========================
--
--   Sometimes a program needs to accept input on multiple input channels
--whenever input arrives.  For example, some workstations may have devices
--such as a digitizing tablet, function button box, or dial box that are
--connected via normal asynchronous serial interfaces; good user interface
--style requires responding immediately to input on any device.  Another
--example is a program that acts as a server to several other processes
--via pipes or sockets.
--
--   You cannot normally use `read' for this purpose, because this blocks
--the program until input is available on one particular file descriptor;
--input on other channels won't wake it up.  You could set nonblocking
--mode and poll each file descriptor in turn, but this is very
--inefficient.
--
--   A better solution is to use the `select' function.  This blocks the
--program until input or output is ready on a specified set of file
--descriptors, or until a timer expires, whichever comes first.  This
--facility is declared in the header file `sys/types.h'.
--
--   In the case of a server socket (*note Listening::.), we say that
--"input" is available when there are pending connections that could be
--accepted (*note Accepting Connections::.).  `accept' for server sockets
--blocks and interacts with `select' just as `read' does for normal input.
--
--   The file descriptor sets for the `select' function are specified as
--`fd_set' objects.  Here is the description of the data type and some
--macros for manipulating these objects.
--
-- - Data Type: fd_set
--     The `fd_set' data type represents file descriptor sets for the
--     `select' function.  It is actually a bit array.
--
-- - Macro: int FD_SETSIZE
--     The value of this macro is the maximum number of file descriptors
--     that a `fd_set' object can hold information about.  On systems
--     with a fixed maximum number, `FD_SETSIZE' is at least that number.
--     On some systems, including GNU, there is no absolute limit on the
--     number of descriptors open, but this macro still has a constant
--     value which controls the number of bits in an `fd_set'; if you get
--     a file descriptor with a value as high as `FD_SETSIZE', you cannot
--     put that descriptor into an `fd_set'.
--
-- - Macro: void FD_ZERO (fd_set *SET)
--     This macro initializes the file descriptor set SET to be the empty
--     set.
--
-- - Macro: void FD_SET (int FILEDES, fd_set *SET)
--     This macro adds FILEDES to the file descriptor set SET.
--
-- - Macro: void FD_CLR (int FILEDES, fd_set *SET)
--     This macro removes FILEDES from the file descriptor set SET.
--
-- - Macro: int FD_ISSET (int FILEDES, fd_set *SET)
--     This macro returns a nonzero value (true) if FILEDES is a member
--     of the the file descriptor set SET, and zero (false) otherwise.
--
--   Next, here is the description of the `select' function itself.
--
-- - Function: int select (int NFDS, fd_set *READ-FDS, fd_set *WRITE-FDS,
--          fd_set *EXCEPT-FDS, struct timeval *TIMEOUT)
--     The `select' function blocks the calling process until there is
--     activity on any of the specified sets of file descriptors, or
--     until the timeout period has expired.
--
--     The file descriptors specified by the READ-FDS argument are
--     checked to see if they are ready for reading; the WRITE-FDS file
--     descriptors are checked to see if they are ready for writing; and
--     the EXCEPT-FDS file descriptors are checked for exceptional
--     conditions.  You can pass a null pointer for any of these
--     arguments if you are not interested in checking for that kind of
--     condition.
--
--     A file descriptor is considered ready for reading if it is at end
--     of file.  A server socket is considered ready for reading if there
--     is a pending connection which can be accepted with `accept'; *note
--     Accepting Connections::..  A client socket is ready for writing
--     when its connection is fully established; *note Connecting::..
--
--     "Exceptional conditions" does not mean errors--errors are reported
--     immediately when an erroneous system call is executed, and do not
--     constitute a state of the descriptor.  Rather, they include
--     conditions such as the presence of an urgent message on a socket.
--     (*Note Sockets::, for information on urgent messages.)
--
--     The `select' function checks only the first NFDS file descriptors.
--     The usual thing is to pass `FD_SETSIZE' as the value of this
--     argument.
--
--     The TIMEOUT specifies the maximum time to wait.  If you pass a
--     null pointer for this argument, it means to block indefinitely
--     until one of the file descriptors is ready.  Otherwise, you should
--     provide the time in `struct timeval' format; see *Note
--     High-Resolution Calendar::.  Specify zero as the time (a `struct
--     timeval' containing all zeros) if you want to find out which
--     descriptors are ready without waiting if none are ready.
--
--     The normal return value from `select' is the total number of ready
--     file descriptors in all of the sets.  Each of the argument sets is
--     overwritten with information about the descriptors that are ready
--     for the corresponding operation.  Thus, to see if a particular
--     descriptor DESC has input, use `FD_ISSET (DESC, READ-FDS)' after
--     `select' returns.
--
--     If `select' returns because the timeout period expires, it returns
--     a value of zero.
--
--     Any signal will cause `select' to return immediately.  So if your
--     program uses signals, you can't rely on `select' to keep waiting
--     for the full time specified.  If you want to be sure of waiting
--     for a particular amount of time, you must check for `EINTR' and
--     repeat the `select' with a newly calculated timeout based on the
--     current time.  See the example below.  See also *Note Interrupted
--     Primitives::.
--
--     If an error occurs, `select' returns `-1' and does not modify the
--     argument file descriptor sets.  The following `errno' error
--     conditions are defined for this function:
--
--    `EBADF'
--          One of the file descriptor sets specified an invalid file
--          descriptor.
--
--    `EINTR'
--          The operation was interrupted by a signal.  *Note Interrupted
--          Primitives::.
--
--    `EINVAL'
--          The TIMEOUT argument is invalid; one of the components is
--          negative or too large.
--
--   *Portability Note:*  The `select' function is a BSD Unix feature.
--
--   Here is an example showing how you can use `select' to establish a
--timeout period for reading from a file descriptor.  The `input_timeout'
--function blocks the calling process until input is available on the
--file descriptor, or until the timeout period expires.
--
--     #include <stdio.h>
--     #include <unistd.h>
--     #include <sys/types.h>
--     #include <sys/time.h>
--
--     int
--     input_timeout (int filedes, unsigned int seconds)
--     {
--       fd_set set;
--       struct timeval timeout;
--     
--       /* Initialize the file descriptor set. */
--       FD_ZERO (&set);
--       FD_SET (filedes, &set);
--     
--       /* Initialize the timeout data structure. */
--       timeout.tv_sec = seconds;
--       timeout.tv_usec = 0;
--     /* `select' returns 0 if timeout, 1 if input available, -1 if error. */
--       return TEMP_FAILURE_RETRY (select (FD_SETSIZE,
--                                          &set, NULL, NULL,
--                                          &timeout));
--     }
--
--     int
--     main (void)
--     {
--       fprintf (stderr, "select returned %d.\n",
--                input_timeout (STDIN_FILENO, 5));
--       return 0;
--     }
--
--   There is another example showing the use of `select' to multiplex
--input from multiple sockets in *Note Server Example::.
--
--
--File: libc.info,  Node: Control Operations,  Next: Duplicating Descriptors,  
Prev: Waiting for I/O,  Up: Low-Level I/O
--
--Control Operations on Files
--===========================
--
--   This section describes how you can perform various other operations
--on file descriptors, such as inquiring about or setting flags describing
--the status of the file descriptor, manipulating record locks, and the
--like.  All of these operations are performed by the function `fcntl'.
--
--   The second argument to the `fcntl' function is a command that
--specifies which operation to perform.  The function and macros that name
--various flags that are used with it are declared in the header file
--`fcntl.h'.  Many of these flags are also used by the `open' function;
--see *Note Opening and Closing Files::.
--
-- - Function: int fcntl (int FILEDES, int COMMAND, ...)
--     The `fcntl' function performs the operation specified by COMMAND
--     on the file descriptor FILEDES.  Some commands require additional
--     arguments to be supplied.  These additional arguments and the
--     return value and error conditions are given in the detailed
--     descriptions of the individual commands.
--
--     Briefly, here is a list of what the various commands are.
--
--    `F_DUPFD'
--          Duplicate the file descriptor (return another file descriptor
--          pointing to the same open file).  *Note Duplicating
--          Descriptors::.
--
--    `F_GETFD'
--          Get flags associated with the file descriptor.  *Note
--          Descriptor Flags::.
--
--    `F_SETFD'
--          Set flags associated with the file descriptor.  *Note
--          Descriptor Flags::.
--
--    `F_GETFL'
--          Get flags associated with the open file.  *Note File Status
--          Flags::.
--
--    `F_SETFL'
--          Set flags associated with the open file.  *Note File Status
--          Flags::.
--
--    `F_GETLK'
--          Get a file lock.  *Note File Locks::.
--
--    `F_SETLK'
--          Set or clear a file lock.  *Note File Locks::.
--
--    `F_SETLKW'
--          Like `F_SETLK', but wait for completion.  *Note File Locks::.
--
--    `F_GETOWN'
--          Get process or process group ID to receive `SIGIO' signals.
--          *Note Interrupt Input::.
--
--    `F_SETOWN'
--          Set process or process group ID to receive `SIGIO' signals.
--          *Note Interrupt Input::.
--
--
--File: libc.info,  Node: Duplicating Descriptors,  Next: Descriptor Flags,  
Prev: Control Operations,  Up: Low-Level I/O
--
--Duplicating Descriptors
--=======================
--
--   You can "duplicate" a file descriptor, or allocate another file
--descriptor that refers to the same open file as the original.  Duplicate
--descriptors share one file position and one set of file status flags
--(*note File Status Flags::.), but each has its own set of file
--descriptor flags (*note Descriptor Flags::.).
--
--   The major use of duplicating a file descriptor is to implement
--"redirection" of input or output:  that is, to change the file or pipe
--that a particular file descriptor corresponds to.
--
--   You can perform this operation using the `fcntl' function with the
--`F_DUPFD' command, but there are also convenient functions `dup' and
--`dup2' for duplicating descriptors.
--
--   The `fcntl' function and flags are declared in `fcntl.h', while
--prototypes for `dup' and `dup2' are in the header file `unistd.h'.
--
-- - Function: int dup (int OLD)
--     This function copies descriptor OLD to the first available
--     descriptor number (the first number not currently open).  It is
--     equivalent to `fcntl (OLD, F_DUPFD, 0)'.
--
-- - Function: int dup2 (int OLD, int NEW)
--     This function copies the descriptor OLD to descriptor number NEW.
--
--     If OLD is an invalid descriptor, then `dup2' does nothing; it does
--     not close NEW.  Otherwise, the new duplicate of OLD replaces any
--     previous meaning of descriptor NEW, as if NEW were closed first.
--
--     If OLD and NEW are different numbers, and OLD is a valid
--     descriptor number, then `dup2' is equivalent to:
--
--          close (NEW);
--          fcntl (OLD, F_DUPFD, NEW)
--
--     However, `dup2' does this atomically; there is no instant in the
--     middle of calling `dup2' at which NEW is closed and not yet a
--     duplicate of OLD.
--
-- - Macro: int F_DUPFD
--     This macro is used as the COMMAND argument to `fcntl', to copy the
--     file descriptor given as the first argument.
--
--     The form of the call in this case is:
--
--          fcntl (OLD, F_DUPFD, NEXT-FILEDES)
--
--     The NEXT-FILEDES argument is of type `int' and specifies that the
--     file descriptor returned should be the next available one greater
--     than or equal to this value.
--
--     The return value from `fcntl' with this command is normally the
--     value of the new file descriptor.  A return value of `-1'
--     indicates an error.  The following `errno' error conditions are
--     defined for this command:
--
--    `EBADF'
--          The OLD argument is invalid.
--
--    `EINVAL'
--          The NEXT-FILEDES argument is invalid.
--
--    `EMFILE'
--          There are no more file descriptors available--your program is
--          already using the maximum.  In BSD and GNU, the maximum is
--          controlled by a resource limit that can be changed; *note
--          Limits on Resources::., for more information about the
--          `RLIMIT_NOFILE' limit.
--
--     `ENFILE' is not a possible error code for `dup2' because `dup2'
--     does not create a new opening of a file; duplicate descriptors do
--     not count toward the limit which `ENFILE' indicates.  `EMFILE' is
--     possible because it refers to the limit on distinct descriptor
--     numbers in use in one process.
--
--   Here is an example showing how to use `dup2' to do redirection.
--Typically, redirection of the standard streams (like `stdin') is done
--by a shell or shell-like program before calling one of the `exec'
--functions (*note Executing a File::.) to execute a new program in a
--child process.  When the new program is executed, it creates and
--initializes the standard streams to point to the corresponding file
--descriptors, before its `main' function is invoked.
--
--   So, to redirect standard input to a file, the shell could do
--something like:
--
--     pid = fork ();
--     if (pid == 0)
--       {
--         char *filename;
--         char *program;
--         int file;
--         ...
--         file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
--         dup2 (file, STDIN_FILENO);
--         TEMP_FAILURE_RETRY (close (file));
--         execv (program, NULL);
--       }
--
--   There is also a more detailed example showing how to implement
--redirection in the context of a pipeline of processes in *Note
--Launching Jobs::.
--
--
--File: libc.info,  Node: Descriptor Flags,  Next: File Status Flags,  Prev: 
Duplicating Descriptors,  Up: Low-Level I/O
--
--File Descriptor Flags
--=====================
--
--   "File descriptor flags" are miscellaneous attributes of a file
--descriptor.  These flags are associated with particular file
--descriptors, so that if you have created duplicate file descriptors
--from a single opening of a file, each descriptor has its own set of
--flags.
--
--   Currently there is just one file descriptor flag: `FD_CLOEXEC',
--which causes the descriptor to be closed if you use any of the
--`exec...' functions (*note Executing a File::.).
--
--   The symbols in this section are defined in the header file `fcntl.h'.
--
-- - Macro: int F_GETFD
--     This macro is used as the COMMAND argument to `fcntl', to specify
--     that it should return the file descriptor flags associated with
--     the FILEDES argument.
--
--     The normal return value from `fcntl' with this command is a
--     nonnegative number which can be interpreted as the bitwise OR of
--     the individual flags (except that currently there is only one flag
--     to use).
--
--     In case of an error, `fcntl' returns `-1'.  The following `errno'
--     error conditions are defined for this command:
--
--    `EBADF'
--          The FILEDES argument is invalid.
--
-- - Macro: int F_SETFD
--     This macro is used as the COMMAND argument to `fcntl', to specify
--     that it should set the file descriptor flags associated with the
--     FILEDES argument.  This requires a third `int' argument to specify
--     the new flags, so the form of the call is:
--
--          fcntl (FILEDES, F_SETFD, NEW-FLAGS)
--
--     The normal return value from `fcntl' with this command is an
--     unspecified value other than `-1', which indicates an error.  The
--     flags and error conditions are the same as for the `F_GETFD'
--     command.
--
--   The following macro is defined for use as a file descriptor flag with
--the `fcntl' function.  The value is an integer constant usable as a bit
--mask value.
--
-- - Macro: int FD_CLOEXEC
--     This flag specifies that the file descriptor should be closed when
--     an `exec' function is invoked; see *Note Executing a File::.  When
--     a file descriptor is allocated (as with `open' or `dup'), this bit
--     is initially cleared on the new file descriptor, meaning that
--     descriptor will survive into the new program after `exec'.
--
--   If you want to modify the file descriptor flags, you should get the
--current flags with `F_GETFD' and modify the value.  Don't assume that
--the flags listed here are the only ones that are implemented; your
--program may be run years from now and more flags may exist then.  For
--example, here is a function to set or clear the flag `FD_CLOEXEC'
--without altering any other flags:
--
--     /* Set the `FD_CLOEXEC' flag of DESC if VALUE is nonzero,
--        or clear the flag if VALUE is 0.
--        Return 0 on success, or -1 on error with `errno' set. */
--     
--     int
--     set_cloexec_flag (int desc, int value)
--     {
--       int oldflags = fcntl (desc, F_GETFD, 0);
--       /* If reading the flags failed, return error indication now.
--       if (oldflags < 0)
--         return oldflags;
--       /* Set just the flag we want to set. */
--       if (value != 0)
--         oldflags |= FD_CLOEXEC;
--       else
--         oldflags &= ~FD_CLOEXEC;
--       /* Store modified flag word in the descriptor. */
--       return fcntl (desc, F_SETFD, oldflags);
--     }
--
--
--File: libc.info,  Node: File Status Flags,  Next: File Locks,  Prev: 
Descriptor Flags,  Up: Low-Level I/O
--
--File Status Flags
--=================
--
--   "File status flags" are used to specify attributes of the opening of
--a file.  Unlike the file descriptor flags discussed in *Note Descriptor
--Flags::, the file status flags are shared by duplicated file descriptors
--resulting from a single opening of the file.  The file status flags are
--specified with the FLAGS argument to `open'; *note Opening and Closing
--Files::..
--
--   File status flags fall into three categories, which are described in
--the following sections.
--
--   * *Note Access Modes::, specify what type of access is allowed to the
--     file: reading, writing, or both.  They are set by `open' and are
--     returned by `fcntl', but cannot be changed.
--
--   * *Note Open-time Flags::, control details of what `open' will do.
--     These flags are not preserved after the `open' call.
--
--   * *Note Operating Modes::, affect how operations such as `read' and
--     `write' are done.  They are set by `open', and can be fetched or
--     changed with `fcntl'.
--
--   The symbols in this section are defined in the header file `fcntl.h'.
--
--* Menu:
--
--* Access Modes::                Whether the descriptor can read or write.
--* Open-time Flags::             Details of `open'.
--* Operating Modes::             Special modes to control I/O operations.
--* Getting File Status Flags::   Fetching and changing these flags.
--
--
--File: libc.info,  Node: Access Modes,  Next: Open-time Flags,  Up: File 
Status Flags
--
--File Access Modes
-------------------
--
--   The file access modes allow a file descriptor to be used for reading,
--writing, or both.  (In the GNU system, they can also allow none of
--these, and allow execution of the file as a program.)  The access modes
--are chosen when the file is opened, and never change.
--
-- - Macro: int O_RDONLY
--     Open the file for read access.
--
-- - Macro: int O_WRONLY
--     Open the file for write access.
--
-- - Macro: int O_RDWR
--     Open the file for both reading and writing.
--
--   In the GNU system (and not in other systems), `O_RDONLY' and
--`O_WRONLY' are independent bits that can be bitwise-ORed together, and
--it is valid for either bit to be set or clear.  This means that
--`O_RDWR' is the same as `O_RDONLY|O_WRONLY'.  A file access mode of
--zero is permissible; it allows no operations that do input or output to
--the file, but does allow other operations such as `fchmod'.  On the GNU
--system, since "read-only" or "write-only" is a misnomer, `fcntl.h'
--defines additional names for the file access modes.  These names are
--preferred when writing GNU-specific code.  But most programs will want
--to be portable to other POSIX.1 systems and should use the POSIX.1
--names above instead.
--
-- - Macro: int O_READ
--     Open the file for reading.  Same as `O_RDWR'; only defined on GNU.
--
-- - Macro: int O_WRITE
--     Open the file for reading.  Same as `O_WRONLY'; only defined on
--     GNU.
--
-- - Macro: int O_EXEC
--     Open the file for executing.  Only defined on GNU.
--
--   To determine the file access mode with `fcntl', you must extract the
--access mode bits from the retrieved file status flags.  In the GNU
--system, you can just test the `O_READ' and `O_WRITE' bits in the flags
--word.  But in other POSIX.1 systems, reading and writing access modes
--are not stored as distinct bit flags.  The portable way to extract the
--file access mode bits is with `O_ACCMODE'.
--
-- - Macro: int O_ACCMODE
--     This macro stands for a mask that can be bitwise-ANDed with the
--     file status flag value to produce a value representing the file
--     access mode.  The mode will be `O_RDONLY', `O_WRONLY', or `O_RDWR'.
--     (In the GNU system it could also be zero, and it never includes the
--     `O_EXEC' bit.)
--
--
--File: libc.info,  Node: Open-time Flags,  Next: Operating Modes,  Prev: 
Access Modes,  Up: File Status Flags
--
--Open-time Flags
-----------------
--
--   The open-time flags specify options affecting how `open' will behave.
--These options are not preserved once the file is open.  The exception to
--this is `O_NONBLOCK', which is also an I/O operating mode and so it
--*is* saved.  *Note Opening and Closing Files::, for how to call `open'.
--
--   There are two sorts of options specified by open-time flags.
--
--   * "File name translation flags" affect how `open' looks up the file
--     name to locate the file, and whether the file can be created.
--
--   * "Open-time action flags" specify extra operations that `open' will
--     perform on the file once it is open.
--
--   Here are the file name translation flags.
--
-- - Macro: int O_CREAT
--     If set, the file will be created if it doesn't already exist.
--
-- - Macro: int O_EXCL
--     If both `O_CREAT' and `O_EXCL' are set, then `open' fails if the
--     specified file already exists.  This is guaranteed to never
--     clobber an existing file.
--
-- - Macro: int O_NONBLOCK
--     This prevents `open' from blocking for a "long time" to open the
--     file.  This is only meaningful for some kinds of files, usually
--     devices such as serial ports; when it is not meaningful, it is
--     harmless and ignored.  Often opening a port to a modem blocks
--     until the modem reports carrier detection; if `O_NONBLOCK' is
--     specified, `open' will return immediately without a carrier.
--
--     Note that the `O_NONBLOCK' flag is overloaded as both an I/O
--     operating mode and a file name translation flag.  This means that
--     specifying `O_NONBLOCK' in `open' also sets nonblocking I/O mode;
--     *note Operating Modes::..  To open the file without blocking but
--     do normal I/O that blocks, you must call `open' with `O_NONBLOCK'
--     set and then call `fcntl' to turn the bit off.
--
-- - Macro: int O_NOCTTY
--     If the named file is a terminal device, don't make it the
--     controlling terminal for the process.  *Note Job Control::, for
--     information about what it means to be the controlling terminal.
--
--     In the GNU system and 4.4 BSD, opening a file never makes it the
--     controlling terminal and `O_NOCTTY' is zero.  However, other
--     systems may use a nonzero value for `O_NOCTTY' and set the
--     controlling terminal when you open a file that is a terminal
--     device; so to be portable, use `O_NOCTTY' when it is important to
--     avoid this.
--
--   The following three file name translation flags exist only in the
--GNU system.
--
-- - Macro: int O_IGNORE_CTTY
--     Do not recognize the named file as the controlling terminal, even
--     if it refers to the process's existing controlling terminal
--     device.  Operations on the new file descriptor will never induce
--     job control signals.  *Note Job Control::.
--
-- - Macro: int O_NOLINK
--     If the named file is a symbolic link, open the link itself instead
--     of the file it refers to.  (`fstat' on the new file descriptor will
--     return the information returned by `lstat' on the link's name.)
--
-- - Macro: int O_NOTRANS
--     If the named file is specially translated, do not invoke the
--     translator.  Open the bare file the translator itself sees.
--
--   The open-time action flags tell `open' to do additional operations
--which are not really related to opening the file.  The reason to do them
--as part of `open' instead of in separate calls is that `open' can do
--them atomically.
--
-- - Macro: int O_TRUNC
--     Truncate the file to zero length.  This option is only useful for
--     regular files, not special files such as directories or FIFOs.
--     POSIX.1 requires that you open the file for writing to use
--     `O_TRUNC'.  In BSD and GNU you must have permission to write the
--     file to truncate it, but you need not open for write access.
--
--     This is the only open-time action flag specified by POSIX.1.
--     There is no good reason for truncation to be done by `open',
--     instead of by calling `ftruncate' afterwards.  The `O_TRUNC' flag
--     existed in Unix before `ftruncate' was invented, and is retained
--     for backward compatibility.
--
-- - Macro: int O_SHLOCK
--     Acquire a shared lock on the file, as with `flock'.  *Note File
--     Locks::.
--
--     If `O_CREAT' is specified, the locking is done atomically when
--     creating the file.  You are guaranteed that no other process will
--     get the lock on the new file first.
--
-- - Macro: int O_EXLOCK
--     Acquire an exclusive lock on the file, as with `flock'.  *Note
--     File Locks::.  This is atomic like `O_SHLOCK'.
--
-diff -purN -x BOOT ../glibc-2.0.1/set-init.c glibc-2.0.1/set-init.c
---- ../glibc-2.0.1/set-init.c  1997-01-04 13:28:47.000000000 +0100
-+++ glibc-2.0.1/set-init.c     2018-06-05 20:48:52.485487171 +0200
-@@ -19,5 +19,7 @@
- #include <stdlib.h>
- #include "set-hooks.h"
- 
-+int __libc_subinit ();
-+
- DEFINE_HOOK_RUNNER (__libc_subinit, __libc_init,
-                   (int argc, char **argv, char **envp), (argc, argv, envp))
-diff -purN -x BOOT ../glibc-2.0.1/soversions.mk glibc-2.0.1/soversions.mk
---- ../glibc-2.0.1/soversions.mk       1970-01-01 01:00:00.000000000 +0100
-+++ glibc-2.0.1/soversions.mk  2018-06-05 22:08:58.655834070 +0200
-@@ -0,0 +1,30 @@
-+libm.so-version=.6
-+all-sonames+=libm.so$(libm.so-version)
-+libc.so-version=.6
-+all-sonames+=libc.so$(libc.so-version)
-+ld.so-version=ld-linux.so.2
-+all-sonames+=$(ld.so-version)
-+libdl.so-version=.2
-+all-sonames+=libdl.so$(libdl.so-version)
-+libutil.so-version=.1
-+all-sonames+=libutil.so$(libutil.so-version)
-+libresolv.so-version=.2
-+all-sonames+=libresolv.so$(libresolv.so-version)
-+libnss_files.so-version=.1
-+all-sonames+=libnss_files.so$(libnss_files.so-version)
-+libnss_dns.so-version=.1
-+all-sonames+=libnss_dns.so$(libnss_dns.so-version)
-+libnss_db.so-version=.1
-+all-sonames+=libnss_db.so$(libnss_db.so-version)
-+libnss_compat.so-version=.1
-+all-sonames+=libnss_compat.so$(libnss_compat.so-version)
-+libnss_nis.so-version=.1
-+all-sonames+=libnss_nis.so$(libnss_nis.so-version)
-+libnsl.so-version=.1
-+all-sonames+=libnsl.so$(libnsl.so-version)
-+libdb.so-version=.2
-+all-sonames+=libdb.so$(libdb.so-version)
-+libcrypt.so-version=.1
-+all-sonames+=libcrypt.so$(libcrypt.so-version)
-+libBrokenLocale.so-version=.1
-+all-sonames+=libBrokenLocale.so$(libBrokenLocale.so-version)
-diff -purN -x BOOT ../glibc-2.0.1/s-proto.d glibc-2.0.1/s-proto.d
---- ../glibc-2.0.1/s-proto.d   1970-01-01 01:00:00.000000000 +0100
-+++ glibc-2.0.1/s-proto.d      2018-06-05 20:53:03.945575790 +0200
-@@ -0,0 +1 @@
-+../s-proto.o ../s-proto.so ../s-proto.po ../s-proto.d: 
../sysdeps/unix/s-proto.S
-diff -purN -x BOOT ../glibc-2.0.1/sysdeps/unix/sysv/linux/i386/sysdep.S 
glibc-2.0.1/sysdeps/unix/sysv/linux/i386/sysdep.S
---- ../glibc-2.0.1/sysdeps/unix/sysv/linux/i386/sysdep.S       1996-11-28 
03:30:50.000000000 +0100
-+++ glibc-2.0.1/sysdeps/unix/sysv/linux/i386/sysdep.S  2018-06-05 
20:39:51.704574546 +0200
-@@ -45,7 +45,7 @@ _errno = errno       /* This name is expected
-    The code for Linux is almost identical to the canonical Unix/i386
-    code, except that the error number in %eax is negated.  */
- 
--ENTRY (__syscall_error)
-+__syscall_error:
-       negl %eax
- 
- #define __syscall_error __syscall_error_1
-diff -purN -x BOOT ../glibc-2.0.1/sysdeps/unix/sysv/linux/init-first.c 
glibc-2.0.1/sysdeps/unix/sysv/linux/init-first.c
---- ../glibc-2.0.1/sysdeps/unix/sysv/linux/init-first.c        1996-11-28 
03:10:38.000000000 +0100
-+++ glibc-2.0.1/sysdeps/unix/sysv/linux/init-first.c   2018-06-05 
20:59:51.108176593 +0200
-@@ -41,6 +41,7 @@ int __libc_multiple_libcs = 1;
- int __libc_argc;
- char **__libc_argv;
- 
-+extern char **environ;
- 
- static void
- init (int argc, char **argv, char **envp)
-@@ -57,14 +58,16 @@ init (int argc, char **argv, char **envp
-        the executable format.  */
-       __personality (PER_LINUX);
- 
-+#if 0
-       /* Set the FPU control word to the proper default value.  */
-       __setfpucw (__fpu_control);
-+#endif
-     }
- 
-   /* Save the command-line arguments.  */
-   __libc_argc = argc;
-   __libc_argv = argv;
--  __environ = envp;
-+  environ = envp;
- 
-   __libc_init (argc, argv, envp);
- 
-diff -purN -x BOOT ../glibc-2.0.1/sysd-syscalls glibc-2.0.1/sysd-syscalls
---- ../glibc-2.0.1/sysd-syscalls       1970-01-01 01:00:00.000000000 +0100
-+++ glibc-2.0.1/sysd-syscalls  2018-06-05 07:02:42.935962548 +0200
-@@ -0,0 +1,1376 @@
-+ifeq (,$(filter s_getgroups,$(unix-syscalls)))
-+unix-syscalls += s_getgroups
-+unix-extra-syscalls += s_getgroups
-+$(foreach o,$(object-suffixes),$(objpfx)s_getgroups$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__syscall_getgroups, getgroups, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__syscall_getgroups)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter s_llseek,$(unix-syscalls)))
-+unix-syscalls += s_llseek
-+unix-extra-syscalls += s_llseek
-+$(foreach o,$(object-suffixes),$(objpfx)s_llseek$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__sys_llseek, _llseek, 5)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__sys_llseek)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter s_setgroups,$(unix-syscalls)))
-+unix-syscalls += s_setgroups
-+unix-extra-syscalls += s_setgroups
-+$(foreach o,$(object-suffixes),$(objpfx)s_setgroups$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__syscall_setgroups, setgroups, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__syscall_setgroups)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter vm86,$(unix-syscalls)))
-+unix-syscalls += vm86
-+$(foreach o,$(object-suffixes),$(objpfx)vm86$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__vm86, vm86, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__vm86)'; \
-+       echo 'weak_alias (__vm86, vm86)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter adjtimex,$(unix-syscalls)))
-+unix-syscalls += adjtimex
-+unix-extra-syscalls += adjtimex
-+$(foreach o,$(object-suffixes),$(objpfx)adjtimex$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__adjtimex, adjtimex, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__adjtimex)'; \
-+       echo 'weak_alias (__adjtimex, adjtimex)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter bdflush,$(unix-syscalls)))
-+unix-syscalls += bdflush
-+unix-extra-syscalls += bdflush
-+$(foreach o,$(object-suffixes),$(objpfx)bdflush$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (bdflush, bdflush, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(bdflush)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter create_module,$(unix-syscalls)))
-+unix-syscalls += create_module
-+unix-extra-syscalls += create_module
-+$(foreach o,$(object-suffixes),$(objpfx)create_module$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (create_module, create_module, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(create_module)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter delete_module,$(unix-syscalls)))
-+unix-syscalls += delete_module
-+unix-extra-syscalls += delete_module
-+$(foreach o,$(object-suffixes),$(objpfx)delete_module$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (delete_module, delete_module, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(delete_module)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter fdatasync,$(unix-syscalls)))
-+unix-syscalls += fdatasync
-+$(foreach o,$(object-suffixes),$(objpfx)fdatasync$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (fdatasync, fdatasync, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(fdatasync)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter flock,$(unix-syscalls)))
-+unix-syscalls += flock
-+$(foreach o,$(object-suffixes),$(objpfx)flock$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__flock, flock, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__flock)'; \
-+       echo 'weak_alias (__flock, flock)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter fork,$(unix-syscalls)))
-+unix-syscalls += fork
-+$(foreach o,$(object-suffixes),$(objpfx)fork$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__fork, fork, 0)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__fork)'; \
-+       echo 'weak_alias (__fork, fork)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter get_kernel_syms,$(unix-syscalls)))
-+unix-syscalls += get_kernel_syms
-+unix-extra-syscalls += get_kernel_syms
-+$(foreach o,$(object-suffixes),$(objpfx)get_kernel_syms$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (get_kernel_syms, get_kernel_syms, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(get_kernel_syms)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getegid,$(unix-syscalls)))
-+unix-syscalls += getegid
-+$(foreach o,$(object-suffixes),$(objpfx)getegid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__getegid, getegid, 0)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__getegid)'; \
-+       echo 'weak_alias (__getegid, getegid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter geteuid,$(unix-syscalls)))
-+unix-syscalls += geteuid
-+$(foreach o,$(object-suffixes),$(objpfx)geteuid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__geteuid, geteuid, 0)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__geteuid)'; \
-+       echo 'weak_alias (__geteuid, geteuid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getpgid,$(unix-syscalls)))
-+unix-syscalls += getpgid
-+$(foreach o,$(object-suffixes),$(objpfx)getpgid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__getpgid, getpgid, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__getpgid)'; \
-+       echo 'weak_alias (__getpgid, getpgid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getpgrp,$(unix-syscalls)))
-+unix-syscalls += getpgrp
-+$(foreach o,$(object-suffixes),$(objpfx)getpgrp$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (getpgrp, getpgrp, 0)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(getpgrp)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getppid,$(unix-syscalls)))
-+unix-syscalls += getppid
-+$(foreach o,$(object-suffixes),$(objpfx)getppid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__getppid, getppid, 0)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__getppid)'; \
-+       echo 'weak_alias (__getppid, getppid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getresuid,$(unix-syscalls)))
-+unix-syscalls += getresuid
-+unix-extra-syscalls += getresuid
-+$(foreach o,$(object-suffixes),$(objpfx)getresuid$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (getresuid, getresuid, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(getresuid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getsid,$(unix-syscalls)))
-+unix-syscalls += getsid
-+$(foreach o,$(object-suffixes),$(objpfx)getsid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (getsid, getsid, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(getsid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter init_module,$(unix-syscalls)))
-+unix-syscalls += init_module
-+unix-extra-syscalls += init_module
-+$(foreach o,$(object-suffixes),$(objpfx)init_module$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (init_module, init_module, 5)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(init_module)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter ioperm,$(unix-syscalls)))
-+unix-syscalls += ioperm
-+$(foreach o,$(object-suffixes),$(objpfx)ioperm$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (ioperm, ioperm, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(ioperm)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter iopl,$(unix-syscalls)))
-+unix-syscalls += iopl
-+$(foreach o,$(object-suffixes),$(objpfx)iopl$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (iopl, iopl, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(iopl)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter ipc,$(unix-syscalls)))
-+unix-syscalls += ipc
-+unix-extra-syscalls += ipc
-+$(foreach o,$(object-suffixes),$(objpfx)ipc$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__ipc, ipc, 5)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__ipc)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter klogctl,$(unix-syscalls)))
-+unix-syscalls += klogctl
-+unix-extra-syscalls += klogctl
-+$(foreach o,$(object-suffixes),$(objpfx)klogctl$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (klogctl, syslog, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(klogctl)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter mlock,$(unix-syscalls)))
-+unix-syscalls += mlock
-+unix-extra-syscalls += mlock
-+$(foreach o,$(object-suffixes),$(objpfx)mlock$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__mlock, mlock, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__mlock)'; \
-+       echo 'weak_alias (__mlock, mlock)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter mlockall,$(unix-syscalls)))
-+unix-syscalls += mlockall
-+unix-extra-syscalls += mlockall
-+$(foreach o,$(object-suffixes),$(objpfx)mlockall$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__mlockall, mlockall, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__mlockall)'; \
-+       echo 'weak_alias (__mlockall, mlockall)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter mount,$(unix-syscalls)))
-+unix-syscalls += mount
-+unix-extra-syscalls += mount
-+$(foreach o,$(object-suffixes),$(objpfx)mount$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__mount, mount, 5)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__mount)'; \
-+       echo 'weak_alias (__mount, mount)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter mremap,$(unix-syscalls)))
-+unix-syscalls += mremap
-+unix-extra-syscalls += mremap
-+$(foreach o,$(object-suffixes),$(objpfx)mremap$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__mremap, mremap, 4)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__mremap)'; \
-+       echo 'weak_alias (__mremap, mremap)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter munlock,$(unix-syscalls)))
-+unix-syscalls += munlock
-+unix-extra-syscalls += munlock
-+$(foreach o,$(object-suffixes),$(objpfx)munlock$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__munlock, munlock, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__munlock)'; \
-+       echo 'weak_alias (__munlock, munlock)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter munlockall,$(unix-syscalls)))
-+unix-syscalls += munlockall
-+unix-extra-syscalls += munlockall
-+$(foreach o,$(object-suffixes),$(objpfx)munlockall$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__munlockall, munlockall, 0)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__munlockall)'; \
-+       echo 'weak_alias (__munlockall, munlockall)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter nanosleep,$(unix-syscalls)))
-+unix-syscalls += nanosleep
-+$(foreach o,$(object-suffixes),$(objpfx)nanosleep$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__libc_nanosleep, nanosleep, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__libc_nanosleep)'; \
-+       echo 'weak_alias (__libc_nanosleep, __nanosleep)'; \
-+       echo 'weak_alias (__libc_nanosleep, nanosleep)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter pause,$(unix-syscalls)))
-+unix-syscalls += pause
-+$(foreach o,$(object-suffixes),$(objpfx)pause$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__libc_pause, pause, 0)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__libc_pause)'; \
-+       echo 'weak_alias (__libc_pause, pause)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter personality,$(unix-syscalls)))
-+unix-syscalls += personality
-+unix-extra-syscalls += personality
-+$(foreach o,$(object-suffixes),$(objpfx)personality$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__personality, personality, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__personality)'; \
-+       echo 'weak_alias (__personality, personality)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter pipe,$(unix-syscalls)))
-+unix-syscalls += pipe
-+$(foreach o,$(object-suffixes),$(objpfx)pipe$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__pipe, pipe, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__pipe)'; \
-+       echo 'weak_alias (__pipe, pipe)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter query_module,$(unix-syscalls)))
-+unix-syscalls += query_module
-+unix-extra-syscalls += query_module
-+$(foreach o,$(object-suffixes),$(objpfx)query_module$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (query_module, query_module, 5)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(query_module)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter s_getdents,$(unix-syscalls)))
-+unix-syscalls += s_getdents
-+unix-extra-syscalls += s_getdents
-+$(foreach o,$(object-suffixes),$(objpfx)s_getdents$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__getdents, getdents, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__getdents)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter s_getpriority,$(unix-syscalls)))
-+unix-syscalls += s_getpriority
-+unix-extra-syscalls += s_getpriority
-+$(foreach o,$(object-suffixes),$(objpfx)s_getpriority$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__syscall_getpriority, getpriority, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__syscall_getpriority)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter s_ptrace,$(unix-syscalls)))
-+unix-syscalls += s_ptrace
-+unix-extra-syscalls += s_ptrace
-+$(foreach o,$(object-suffixes),$(objpfx)s_ptrace$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__syscall_ptrace, ptrace, 4)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__syscall_ptrace)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter s_reboot,$(unix-syscalls)))
-+unix-syscalls += s_reboot
-+unix-extra-syscalls += s_reboot
-+$(foreach o,$(object-suffixes),$(objpfx)s_reboot$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__syscall_reboot, reboot, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__syscall_reboot)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter s_sigsuspend,$(unix-syscalls)))
-+unix-syscalls += s_sigsuspend
-+unix-extra-syscalls += s_sigsuspend
-+$(foreach o,$(object-suffixes),$(objpfx)s_sigsuspend$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__syscall_sigsuspend, sigsuspend, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__syscall_sigsuspend)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter s_sysctl,$(unix-syscalls)))
-+unix-syscalls += s_sysctl
-+unix-extra-syscalls += s_sysctl
-+$(foreach o,$(object-suffixes),$(objpfx)s_sysctl$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__syscall__sysctl, _sysctl, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__syscall__sysctl)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter s_ustat,$(unix-syscalls)))
-+unix-syscalls += s_ustat
-+unix-extra-syscalls += s_ustat
-+$(foreach o,$(object-suffixes),$(objpfx)s_ustat$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__syscall_ustat, ustat, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__syscall_ustat)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sched_getp,$(unix-syscalls)))
-+unix-syscalls += sched_getp
-+$(foreach o,$(object-suffixes),$(objpfx)sched_getp$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__sched_getparam, sched_getparam, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__sched_getparam)'; \
-+       echo 'weak_alias (__sched_getparam, sched_getparam)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sched_gets,$(unix-syscalls)))
-+unix-syscalls += sched_gets
-+$(foreach o,$(object-suffixes),$(objpfx)sched_gets$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__sched_getscheduler, sched_getscheduler, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__sched_getscheduler)'; \
-+       echo 'weak_alias (__sched_getscheduler, sched_getscheduler)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sched_primax,$(unix-syscalls)))
-+unix-syscalls += sched_primax
-+$(foreach o,$(object-suffixes),$(objpfx)sched_primax$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__sched_get_priority_max, sched_get_priority_max, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__sched_get_priority_max)'; \
-+       echo 'weak_alias (__sched_get_priority_max, sched_get_priority_max)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sched_primin,$(unix-syscalls)))
-+unix-syscalls += sched_primin
-+$(foreach o,$(object-suffixes),$(objpfx)sched_primin$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__sched_get_priority_min, sched_get_priority_min, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__sched_get_priority_min)'; \
-+       echo 'weak_alias (__sched_get_priority_min, sched_get_priority_min)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sched_rr_gi,$(unix-syscalls)))
-+unix-syscalls += sched_rr_gi
-+$(foreach o,$(object-suffixes),$(objpfx)sched_rr_gi$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__sched_rr_get_interval, sched_rr_get_interval, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__sched_rr_get_interval)'; \
-+       echo 'weak_alias (__sched_rr_get_interval, sched_rr_get_interval)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sched_setp,$(unix-syscalls)))
-+unix-syscalls += sched_setp
-+$(foreach o,$(object-suffixes),$(objpfx)sched_setp$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__sched_setparam, sched_setparam, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__sched_setparam)'; \
-+       echo 'weak_alias (__sched_setparam, sched_setparam)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sched_sets,$(unix-syscalls)))
-+unix-syscalls += sched_sets
-+$(foreach o,$(object-suffixes),$(objpfx)sched_sets$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__sched_setscheduler, sched_setscheduler, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__sched_setscheduler)'; \
-+       echo 'weak_alias (__sched_setscheduler, sched_setscheduler)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sched_yield,$(unix-syscalls)))
-+unix-syscalls += sched_yield
-+$(foreach o,$(object-suffixes),$(objpfx)sched_yield$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__sched_yield, sched_yield, 0)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__sched_yield)'; \
-+       echo 'weak_alias (__sched_yield, sched_yield)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter select,$(unix-syscalls)))
-+unix-syscalls += select
-+$(foreach o,$(object-suffixes),$(objpfx)select$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__select, _newselect, 5)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__select)'; \
-+       echo 'weak_alias (__select, select)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setfsgid,$(unix-syscalls)))
-+unix-syscalls += setfsgid
-+unix-extra-syscalls += setfsgid
-+$(foreach o,$(object-suffixes),$(objpfx)setfsgid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (setfsgid, setfsgid, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(setfsgid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setfsuid,$(unix-syscalls)))
-+unix-syscalls += setfsuid
-+unix-extra-syscalls += setfsuid
-+$(foreach o,$(object-suffixes),$(objpfx)setfsuid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (setfsuid, setfsuid, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(setfsuid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setpgid,$(unix-syscalls)))
-+unix-syscalls += setpgid
-+$(foreach o,$(object-suffixes),$(objpfx)setpgid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__setpgid, setpgid, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__setpgid)'; \
-+       echo 'weak_alias (__setpgid, setpgid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setresuid,$(unix-syscalls)))
-+unix-syscalls += setresuid
-+unix-extra-syscalls += setresuid
-+$(foreach o,$(object-suffixes),$(objpfx)setresuid$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (setresuid, setresuid, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(setresuid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sigpending,$(unix-syscalls)))
-+unix-syscalls += sigpending
-+$(foreach o,$(object-suffixes),$(objpfx)sigpending$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (sigpending, sigpending, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(sigpending)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sigprocmask,$(unix-syscalls)))
-+unix-syscalls += sigprocmask
-+$(foreach o,$(object-suffixes),$(objpfx)sigprocmask$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__sigprocmask, sigprocmask, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__sigprocmask)'; \
-+       echo 'weak_alias (__sigprocmask, sigprocmask)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sigreturn,$(unix-syscalls)))
-+unix-syscalls += sigreturn
-+$(foreach o,$(object-suffixes),$(objpfx)sigreturn$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__sigreturn, sigreturn, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__sigreturn)'; \
-+       echo 'weak_alias (__sigreturn, sigreturn)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sys_mknod,$(unix-syscalls)))
-+unix-syscalls += sys_mknod
-+unix-extra-syscalls += sys_mknod
-+$(foreach o,$(object-suffixes),$(objpfx)sys_mknod$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__syscall_mknod, mknod, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__syscall_mknod)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sysinfo,$(unix-syscalls)))
-+unix-syscalls += sysinfo
-+unix-extra-syscalls += sysinfo
-+$(foreach o,$(object-suffixes),$(objpfx)sysinfo$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (sysinfo, sysinfo, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(sysinfo)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter swapon,$(unix-syscalls)))
-+unix-syscalls += swapon
-+$(foreach o,$(object-suffixes),$(objpfx)swapon$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (swapon, swapon, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(swapon)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter umount,$(unix-syscalls)))
-+unix-syscalls += umount
-+unix-extra-syscalls += umount
-+$(foreach o,$(object-suffixes),$(objpfx)umount$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__umount, umount, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__umount)'; \
-+       echo 'weak_alias (__umount, umount)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter uselib,$(unix-syscalls)))
-+unix-syscalls += uselib
-+unix-extra-syscalls += uselib
-+$(foreach o,$(object-suffixes),$(objpfx)uselib$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (uselib, uselib, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(uselib)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter wait4,$(unix-syscalls)))
-+unix-syscalls += wait4
-+$(foreach o,$(object-suffixes),$(objpfx)wait4$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__wait4, wait4, 4)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__wait4)'; \
-+       echo 'weak_alias (__wait4, wait4)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter fchmod,$(unix-syscalls)))
-+unix-syscalls += fchmod
-+$(foreach o,$(object-suffixes),$(objpfx)fchmod$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__fchmod, fchmod, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__fchmod)'; \
-+       echo 'weak_alias (__fchmod, fchmod)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter fchown,$(unix-syscalls)))
-+unix-syscalls += fchown
-+$(foreach o,$(object-suffixes),$(objpfx)fchown$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__fchown, fchown, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__fchown)'; \
-+       echo 'weak_alias (__fchown, fchown)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter ftruncate,$(unix-syscalls)))
-+unix-syscalls += ftruncate
-+$(foreach o,$(object-suffixes),$(objpfx)ftruncate$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (ftruncate, ftruncate, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(ftruncate)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getpgid,$(unix-syscalls)))
-+unix-syscalls += getpgid
-+$(foreach o,$(object-suffixes),$(objpfx)getpgid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__getpgid, getpgrp, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__getpgid)'; \
-+       echo 'weak_alias (__getpgid, getpgid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getrusage,$(unix-syscalls)))
-+unix-syscalls += getrusage
-+$(foreach o,$(object-suffixes),$(objpfx)getrusage$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__getrusage, getrusage, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__getrusage)'; \
-+       echo 'weak_alias (__getrusage, getrusage)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter gettimeofday,$(unix-syscalls)))
-+unix-syscalls += gettimeofday
-+$(foreach o,$(object-suffixes),$(objpfx)gettimeofday$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__gettimeofday, gettimeofday, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__gettimeofday)'; \
-+       echo 'weak_alias (__gettimeofday, gettimeofday)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter settimeofday,$(unix-syscalls)))
-+unix-syscalls += settimeofday
-+$(foreach o,$(object-suffixes),$(objpfx)settimeofday$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__settimeofday, settimeofday, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__settimeofday)'; \
-+       echo 'weak_alias (__settimeofday, settimeofday)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setpgid,$(unix-syscalls)))
-+unix-syscalls += setpgid
-+$(foreach o,$(object-suffixes),$(objpfx)setpgid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__setpgid, setpgrp, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__setpgid)'; \
-+       echo 'weak_alias (__setpgid, setpgid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setregid,$(unix-syscalls)))
-+unix-syscalls += setregid
-+$(foreach o,$(object-suffixes),$(objpfx)setregid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__setregid, setregid, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__setregid)'; \
-+       echo 'weak_alias (__setregid, setregid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setreuid,$(unix-syscalls)))
-+unix-syscalls += setreuid
-+$(foreach o,$(object-suffixes),$(objpfx)setreuid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__setreuid, setreuid, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__setreuid)'; \
-+       echo 'weak_alias (__setreuid, setreuid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sys_lstat,$(unix-syscalls)))
-+unix-syscalls += sys_lstat
-+unix-extra-syscalls += sys_lstat
-+$(foreach o,$(object-suffixes),$(objpfx)sys_lstat$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__syscall_lstat, lstat, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__syscall_lstat)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter truncate,$(unix-syscalls)))
-+unix-syscalls += truncate
-+$(foreach o,$(object-suffixes),$(objpfx)truncate$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (truncate, truncate, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(truncate)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter vhangup,$(unix-syscalls)))
-+unix-syscalls += vhangup
-+$(foreach o,$(object-suffixes),$(objpfx)vhangup$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (vhangup, vhangup, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(vhangup)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter mprotect,$(unix-syscalls)))
-+unix-syscalls += mprotect
-+$(foreach o,$(object-suffixes),$(objpfx)mprotect$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__mprotect, mprotect, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__mprotect)'; \
-+       echo 'weak_alias (__mprotect, mprotect)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter msync,$(unix-syscalls)))
-+unix-syscalls += msync
-+$(foreach o,$(object-suffixes),$(objpfx)msync$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__libc_msync, msync, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__libc_msync)'; \
-+       echo 'weak_alias (__libc_msync, msync)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter munmap,$(unix-syscalls)))
-+unix-syscalls += munmap
-+$(foreach o,$(object-suffixes),$(objpfx)munmap$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__munmap, munmap, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__munmap)'; \
-+       echo 'weak_alias (__munmap, munmap)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sethostname,$(unix-syscalls)))
-+unix-syscalls += sethostname
-+$(foreach o,$(object-suffixes),$(objpfx)sethostname$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (sethostname, sethostname, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(sethostname)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter alarm,$(unix-syscalls)))
-+unix-syscalls += alarm
-+$(foreach o,$(object-suffixes),$(objpfx)alarm$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (alarm, alarm, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(alarm)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter nice,$(unix-syscalls)))
-+unix-syscalls += nice
-+$(foreach o,$(object-suffixes),$(objpfx)nice$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (nice, nice, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(nice)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setrlimit,$(unix-syscalls)))
-+unix-syscalls += setrlimit
-+$(foreach o,$(object-suffixes),$(objpfx)setrlimit$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (setrlimit, setrlimit, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(setrlimit)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter settimeofday,$(unix-syscalls)))
-+unix-syscalls += settimeofday
-+$(foreach o,$(object-suffixes),$(objpfx)settimeofday$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__settimeofday, settimeofday, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__settimeofday)'; \
-+       echo 'weak_alias (__settimeofday, settimeofday)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter stime,$(unix-syscalls)))
-+unix-syscalls += stime
-+$(foreach o,$(object-suffixes),$(objpfx)stime$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (stime, stime, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(stime)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter times,$(unix-syscalls)))
-+unix-syscalls += times
-+$(foreach o,$(object-suffixes),$(objpfx)times$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__times, times, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__times)'; \
-+       echo 'weak_alias (__times, times)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter utime,$(unix-syscalls)))
-+unix-syscalls += utime
-+$(foreach o,$(object-suffixes),$(objpfx)utime$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (utime, utime, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(utime)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter access,$(unix-syscalls)))
-+unix-syscalls += access
-+$(foreach o,$(object-suffixes),$(objpfx)access$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__access, access, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__access)'; \
-+       echo 'weak_alias (__access, access)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter acct,$(unix-syscalls)))
-+unix-syscalls += acct
-+$(foreach o,$(object-suffixes),$(objpfx)acct$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (acct, acct, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(acct)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter chdir,$(unix-syscalls)))
-+unix-syscalls += chdir
-+$(foreach o,$(object-suffixes),$(objpfx)chdir$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__chdir, chdir, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__chdir)'; \
-+       echo 'weak_alias (__chdir, chdir)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter chmod,$(unix-syscalls)))
-+unix-syscalls += chmod
-+$(foreach o,$(object-suffixes),$(objpfx)chmod$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__chmod, chmod, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__chmod)'; \
-+       echo 'weak_alias (__chmod, chmod)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter chown,$(unix-syscalls)))
-+unix-syscalls += chown
-+$(foreach o,$(object-suffixes),$(objpfx)chown$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__chown, chown, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__chown)'; \
-+       echo 'weak_alias (__chown, chown)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter chroot,$(unix-syscalls)))
-+unix-syscalls += chroot
-+$(foreach o,$(object-suffixes),$(objpfx)chroot$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (chroot, chroot, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(chroot)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter close,$(unix-syscalls)))
-+unix-syscalls += close
-+$(foreach o,$(object-suffixes),$(objpfx)close$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__libc_close, close, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__libc_close)'; \
-+       echo 'weak_alias (__libc_close, __close)'; \
-+       echo 'weak_alias (__libc_close, close)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter dup,$(unix-syscalls)))
-+unix-syscalls += dup
-+$(foreach o,$(object-suffixes),$(objpfx)dup$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__dup, dup, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__dup)'; \
-+       echo 'weak_alias (__dup, dup)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter dup2,$(unix-syscalls)))
-+unix-syscalls += dup2
-+$(foreach o,$(object-suffixes),$(objpfx)dup2$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__dup2, dup2, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__dup2)'; \
-+       echo 'weak_alias (__dup2, dup2)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter fchdir,$(unix-syscalls)))
-+unix-syscalls += fchdir
-+$(foreach o,$(object-suffixes),$(objpfx)fchdir$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (fchdir, fchdir, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(fchdir)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter fcntl,$(unix-syscalls)))
-+unix-syscalls += fcntl
-+$(foreach o,$(object-suffixes),$(objpfx)fcntl$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__libc_fcntl, fcntl, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__libc_fcntl)'; \
-+       echo 'weak_alias (__libc_fcntl, __fcntl)'; \
-+       echo 'weak_alias (__libc_fcntl, fcntl)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter fstatfs,$(unix-syscalls)))
-+unix-syscalls += fstatfs
-+$(foreach o,$(object-suffixes),$(objpfx)fstatfs$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__fstatfs, fstatfs, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__fstatfs)'; \
-+       echo 'weak_alias (__fstatfs, fstatfs)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter fsync,$(unix-syscalls)))
-+unix-syscalls += fsync
-+$(foreach o,$(object-suffixes),$(objpfx)fsync$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__libc_fsync, fsync, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__libc_fsync)'; \
-+       echo 'weak_alias (__libc_fsync, fsync)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getdomain,$(unix-syscalls)))
-+unix-syscalls += getdomain
-+$(foreach o,$(object-suffixes),$(objpfx)getdomain$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (getdomainname, getdomainname, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(getdomainname)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getgid,$(unix-syscalls)))
-+unix-syscalls += getgid
-+$(foreach o,$(object-suffixes),$(objpfx)getgid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__getgid, getgid, 0)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__getgid)'; \
-+       echo 'weak_alias (__getgid, getgid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getitimer,$(unix-syscalls)))
-+unix-syscalls += getitimer
-+$(foreach o,$(object-suffixes),$(objpfx)getitimer$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__getitimer, getitimer, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__getitimer)'; \
-+       echo 'weak_alias (__getitimer, getitimer)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getpid,$(unix-syscalls)))
-+unix-syscalls += getpid
-+$(foreach o,$(object-suffixes),$(objpfx)getpid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__getpid, getpid, 0)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__getpid)'; \
-+       echo 'weak_alias (__getpid, getpid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getrlimit,$(unix-syscalls)))
-+unix-syscalls += getrlimit
-+$(foreach o,$(object-suffixes),$(objpfx)getrlimit$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__getrlimit, getrlimit, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__getrlimit)'; \
-+       echo 'weak_alias (__getrlimit, getrlimit)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter getuid,$(unix-syscalls)))
-+unix-syscalls += getuid
-+$(foreach o,$(object-suffixes),$(objpfx)getuid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__getuid, getuid, 0)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__getuid)'; \
-+       echo 'weak_alias (__getuid, getuid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter ioctl,$(unix-syscalls)))
-+unix-syscalls += ioctl
-+$(foreach o,$(object-suffixes),$(objpfx)ioctl$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__ioctl, ioctl, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__ioctl)'; \
-+       echo 'weak_alias (__ioctl, ioctl)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter kill,$(unix-syscalls)))
-+unix-syscalls += kill
-+$(foreach o,$(object-suffixes),$(objpfx)kill$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__kill, kill, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__kill)'; \
-+       echo 'weak_alias (__kill, kill)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter link,$(unix-syscalls)))
-+unix-syscalls += link
-+$(foreach o,$(object-suffixes),$(objpfx)link$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__link, link, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__link)'; \
-+       echo 'weak_alias (__link, link)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter lseek,$(unix-syscalls)))
-+unix-syscalls += lseek
-+$(foreach o,$(object-suffixes),$(objpfx)lseek$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__libc_lseek, lseek, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__libc_lseek)'; \
-+       echo 'weak_alias (__libc_lseek, __lseek)'; \
-+       echo 'weak_alias (__libc_lseek, lseek)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter mkdir,$(unix-syscalls)))
-+unix-syscalls += mkdir
-+$(foreach o,$(object-suffixes),$(objpfx)mkdir$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__mkdir, mkdir, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__mkdir)'; \
-+       echo 'weak_alias (__mkdir, mkdir)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter open,$(unix-syscalls)))
-+unix-syscalls += open
-+$(foreach o,$(object-suffixes),$(objpfx)open$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__libc_open, open, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__libc_open)'; \
-+       echo 'weak_alias (__libc_open, __open)'; \
-+       echo 'weak_alias (__libc_open, open)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter read,$(unix-syscalls)))
-+unix-syscalls += read
-+$(foreach o,$(object-suffixes),$(objpfx)read$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__libc_read, read, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__libc_read)'; \
-+       echo 'weak_alias (__libc_read, __read)'; \
-+       echo 'weak_alias (__libc_read, read)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter readlink,$(unix-syscalls)))
-+unix-syscalls += readlink
-+$(foreach o,$(object-suffixes),$(objpfx)readlink$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__readlink, readlink, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__readlink)'; \
-+       echo 'weak_alias (__readlink, readlink)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter readv,$(unix-syscalls)))
-+unix-syscalls += readv
-+$(foreach o,$(object-suffixes),$(objpfx)readv$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (readv, readv, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(readv)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter rename,$(unix-syscalls)))
-+unix-syscalls += rename
-+$(foreach o,$(object-suffixes),$(objpfx)rename$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (rename, rename, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(rename)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter rmdir,$(unix-syscalls)))
-+unix-syscalls += rmdir
-+$(foreach o,$(object-suffixes),$(objpfx)rmdir$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__rmdir, rmdir, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__rmdir)'; \
-+       echo 'weak_alias (__rmdir, rmdir)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter select,$(unix-syscalls)))
-+unix-syscalls += select
-+$(foreach o,$(object-suffixes),$(objpfx)select$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__select, select, 5)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__select)'; \
-+       echo 'weak_alias (__select, select)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setdomain,$(unix-syscalls)))
-+unix-syscalls += setdomain
-+$(foreach o,$(object-suffixes),$(objpfx)setdomain$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (setdomainname, setdomainname, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(setdomainname)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setgid,$(unix-syscalls)))
-+unix-syscalls += setgid
-+$(foreach o,$(object-suffixes),$(objpfx)setgid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__setgid, setgid, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__setgid)'; \
-+       echo 'weak_alias (__setgid, setgid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setitimer,$(unix-syscalls)))
-+unix-syscalls += setitimer
-+$(foreach o,$(object-suffixes),$(objpfx)setitimer$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__setitimer, setitimer, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__setitimer)'; \
-+       echo 'weak_alias (__setitimer, setitimer)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setpriority,$(unix-syscalls)))
-+unix-syscalls += setpriority
-+$(foreach o,$(object-suffixes),$(objpfx)setpriority$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (setpriority, setpriority, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(setpriority)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setsid,$(unix-syscalls)))
-+unix-syscalls += setsid
-+$(foreach o,$(object-suffixes),$(objpfx)setsid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__setsid, setsid, 0)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__setsid)'; \
-+       echo 'weak_alias (__setsid, setsid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter setuid,$(unix-syscalls)))
-+unix-syscalls += setuid
-+$(foreach o,$(object-suffixes),$(objpfx)setuid$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__setuid, setuid, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__setuid)'; \
-+       echo 'weak_alias (__setuid, setuid)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sstk,$(unix-syscalls)))
-+unix-syscalls += sstk
-+$(foreach o,$(object-suffixes),$(objpfx)sstk$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (sstk, sstk, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(sstk)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter statfs,$(unix-syscalls)))
-+unix-syscalls += statfs
-+$(foreach o,$(object-suffixes),$(objpfx)statfs$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__statfs, statfs, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__statfs)'; \
-+       echo 'weak_alias (__statfs, statfs)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter swapoff,$(unix-syscalls)))
-+unix-syscalls += swapoff
-+$(foreach o,$(object-suffixes),$(objpfx)swapoff$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (swapoff, swapoff, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(swapoff)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter swapon,$(unix-syscalls)))
-+unix-syscalls += swapon
-+$(foreach o,$(object-suffixes),$(objpfx)swapon$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (swapon, swapon, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(swapon)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter symlink,$(unix-syscalls)))
-+unix-syscalls += symlink
-+$(foreach o,$(object-suffixes),$(objpfx)symlink$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__symlink, symlink, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__symlink)'; \
-+       echo 'weak_alias (__symlink, symlink)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sync,$(unix-syscalls)))
-+unix-syscalls += sync
-+$(foreach o,$(object-suffixes),$(objpfx)sync$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (sync, sync, 0)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(sync)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sys_fstat,$(unix-syscalls)))
-+unix-syscalls += sys_fstat
-+unix-extra-syscalls += sys_fstat
-+$(foreach o,$(object-suffixes),$(objpfx)sys_fstat$o): 
$(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__syscall_fstat, fstat, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__syscall_fstat)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter sys_stat,$(unix-syscalls)))
-+unix-syscalls += sys_stat
-+unix-extra-syscalls += sys_stat
-+$(foreach o,$(object-suffixes),$(objpfx)sys_stat$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__syscall_stat, stat, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__syscall_stat)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter umask,$(unix-syscalls)))
-+unix-syscalls += umask
-+$(foreach o,$(object-suffixes),$(objpfx)umask$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__umask, umask, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__umask)'; \
-+       echo 'weak_alias (__umask, umask)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter uname,$(unix-syscalls)))
-+unix-syscalls += uname
-+$(foreach o,$(object-suffixes),$(objpfx)uname$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (uname, uname, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(uname)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter unlink,$(unix-syscalls)))
-+unix-syscalls += unlink
-+$(foreach o,$(object-suffixes),$(objpfx)unlink$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__unlink, unlink, 1)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__unlink)'; \
-+       echo 'weak_alias (__unlink, unlink)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter utimes,$(unix-syscalls)))
-+unix-syscalls += utimes
-+$(foreach o,$(object-suffixes),$(objpfx)utimes$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__utimes, utimes, 2)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__utimes)'; \
-+       echo 'weak_alias (__utimes, utimes)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter write,$(unix-syscalls)))
-+unix-syscalls += write
-+$(foreach o,$(object-suffixes),$(objpfx)write$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (__libc_write, write, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(__libc_write)'; \
-+       echo 'weak_alias (__libc_write, __write)'; \
-+       echo 'weak_alias (__libc_write, write)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-+ifeq (,$(filter writev,$(unix-syscalls)))
-+unix-syscalls += writev
-+$(foreach o,$(object-suffixes),$(objpfx)writev$o): $(common-objpfx)s-proto.d
-+      (echo '#include <sysdep.h>'; \
-+       echo 'PSEUDO (writev, writev, 3)'; \
-+       echo ' ret'; \
-+       echo 'PSEUDO_END(writev)'; \
-+      ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
-+endif
-diff -purN -x BOOT ../glibc-2.0.1/version.c glibc-2.0.1/version.c
---- ../glibc-2.0.1/version.c   1997-01-04 13:30:49.000000000 +0100
-+++ glibc-2.0.1/version.c      2018-06-05 20:52:12.844747867 +0200
-@@ -32,6 +32,10 @@ PARTICULAR PURPOSE.\n"
- 
- #include <unistd.h>
- 
-+#ifndef STDOUT_FILENO
-+#define STDOUT_FILENO 1
-+#endif
-+
- void
- __libc_print_version (void)
- {
-diff -purN -x BOOT ../glibc-2.0.1/version.mk glibc-2.0.1/version.mk
---- ../glibc-2.0.1/version.mk  1970-01-01 01:00:00.000000000 +0100
-+++ glibc-2.0.1/version.mk     2018-06-05 07:02:42.067948564 +0200
-@@ -0,0 +1,2 @@
-+release=experimental
-+version=2.0.1



reply via email to

[Prev in Thread] Current Thread [Next in Thread]