guix-commits
[Top][All Lists]
Advanced

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

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


From: Jan Nieuwenhuizen
Subject: 79/207: gnu: glibc-boot: Update to 2.2.5.
Date: Sat, 8 Sep 2018 13:26:08 -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 l