guix-commits
[Top][All Lists]
Advanced

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

26/30: gnu: Add glibc-boot 2.0.1.


From: Jan Nieuwenhuizen
Subject: 26/30: gnu: Add glibc-boot 2.0.1.
Date: Tue, 12 Jun 2018 13:20:54 -0400 (EDT)

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

commit 8f10e60c73d15ab14e13bb1043f35246328f3ec3
Author: Jan Nieuwenhuizen <address@hidden>
Date:   Wed Jun 6 14:48:21 2018 +0200

    gnu: Add glibc-boot 2.0.1.
    
    * gnu/packages/mes.scm (glibc-boot): New variable.
    * gnu/packages/patches/glibc-boot.patch: New file.
    * gnu/local.mk (dist_patch_DATA): Add it.
---
 gnu/local.mk                          |     1 +
 gnu/packages/mes.scm                  |    60 +
 gnu/packages/patches/glibc-boot.patch | 43015 ++++++++++++++++++++++++++++++++
 3 files changed, 43076 insertions(+)

diff --git a/gnu/local.mk b/gnu/local.mk
index d8005d4..e1984b0 100644
--- a/gnu/local.mk
+++ b/gnu/local.mk
@@ -683,6 +683,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-CVE-2017-15670-15671.patch                \
+  %D%/packages/patches/glibc-boot.patch                                \
   %D%/packages/patches/glibc-bootstrap-system.patch            \
   %D%/packages/patches/glibc-ldd-x86_64.patch                  \
   %D%/packages/patches/glibc-locales.patch                     \
diff --git a/gnu/packages/mes.scm b/gnu/packages/mes.scm
index a29532b..20f1c20 100644
--- a/gnu/packages/mes.scm
+++ b/gnu/packages/mes.scm
@@ -673,6 +673,66 @@ ac_cv_c_float_format='IEEE (little-endian)'
                (copy-recursively (string-append tcc "/include")
                                  (string-append out "/include"))))))))))
 
+(define-public glibc-boot
+  (package
+    (inherit glibc)
+    (name "glibc-boot")
+    (version "2.0.1")
+    (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"))
+              (sha256
+               (base32
+                "1cckm2242wcc0i0zbs7djjp2z215fdca0j3ay6ydxhchvw4vir2v"))))
+    (supported-systems '("i686-linux"))
+    (native-inputs `(("binutils" ,binutils-boot)
+                     ("gcc" ,gcc-boot)
+                     ("tcc" ,tcc-boot)))
+    (propagated-inputs `(("kernel-headers" ,(linux-libre-headers-boot0))))
+    (arguments
+     `(#:tests? #f                      ; runtest: command not found
+       #: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))
+       #:phases
+       (modify-phases %standard-phases
+         (replace 'configure
+           (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")))
+               (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))))))))))))
+
 ;;;
 
 (define-public nyacc
diff --git a/gnu/packages/patches/glibc-boot.patch 
b/gnu/packages/patches/glibc-boot.patch
new file mode 100644
index 0000000..e702fcd
--- /dev/null
+++ b/gnu/packages/patches/glibc-boot.patch
@@ -0,0 +1,43015 @@
+diff -purN -x BOOT ../glibc-2.0.1/assert/assert.c glibc-2.0.1/assert/assert.c
+--- ../glibc-2.0.1/assert/assert.c     1996-12-02 16:40:23.000000000 +0100
++++ glibc-2.0.1/assert/assert.c        2018-06-05 21:00:54.777209397 +0200
+@@ -21,6 +21,9 @@
+ #include <stdlib.h>
+ #include <sysdep.h>
+ 
++#ifndef stderr
++#define stderr 2
++#endif
+ 
+ const char *__assert_program_name;
+ 
+diff -purN -x BOOT ../glibc-2.0.1/csu/errno-loc.d glibc-2.0.1/csu/errno-loc.d
+--- ../glibc-2.0.1/csu/errno-loc.d     1970-01-01 01:00:00.000000000 +0100
++++ glibc-2.0.1/csu/errno-loc.d        2018-06-05 20:53:03.897575013 +0200
+@@ -0,0 +1 @@
++errno-loc.o errno-loc.so errno-loc.po errno-loc.d: 
../sysdeps/generic/errno-loc.c
+Binary files ../glibc-2.0.1/csu/errno-loc.o and glibc-2.0.1/csu/errno-loc.o 
differ
+Binary files ../glibc-2.0.1/csu/errno-loc.po and glibc-2.0.1/csu/errno-loc.po 
differ
+Binary files ../glibc-2.0.1/csu/errno-loc.so and glibc-2.0.1/csu/errno-loc.so 
differ
+diff -purN -x BOOT ../glibc-2.0.1/ctype/ctype.c glibc-2.0.1/ctype/ctype.c
+--- ../glibc-2.0.1/ctype/ctype.c       1992-10-07 23:22:36.000000000 +0100
++++ glibc-2.0.1/ctype/ctype.c  2018-06-05 22:08:32.547406861 +0200
+@@ -21,8 +21,6 @@ Cambridge, MA 02139, USA.  */
+ #define       __NO_CTYPE
+ #include <ctype.h>
+ 
+-/* Provide real-function versions of all the ctype macros.  */
+-
+ #define       func(name, type) \
+   int DEFUN(name, (c), int c) { return __isctype(c, type); }
+ 
+diff -purN -x BOOT ../glibc-2.0.1/ctype/ctype.E glibc-2.0.1/ctype/ctype.E
+--- ../glibc-2.0.1/ctype/ctype.E       1970-01-01 01:00:00.000000000 +0100
++++ glibc-2.0.1/ctype/ctype.E  2018-06-05 21:55:56.987061510 +0200
+@@ -0,0 +1,222 @@
++# 1 "ctype.c"
++# 1 "../libc-symbols.h" 1
++ 
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++ 
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++ 
++
++
++
++
++
++
++
++
++ 
++
++ 
++
++
++
++ 
++
++
++
++
++
++ 
++
++
++
++
++
++extern const char _libc_intl_domainname[];
++
++
++
++
++
++ 
++
++
++
++
++
++
++ 
++
++
++ 
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++ 
++# 119 "../libc-symbols.h"
++
++
++
++
++
++
++
++
++
++
++
++
++
++ 
++
++
++
++
++# 184 "../libc-symbols.h"
++
++
++
++
++
++
++# 210 "../libc-symbols.h"
++
++
++
++
++ 
++
++
++
++
++
++
++
++
++ 
++
++# 248 "../libc-symbols.h"
++
++ 
++
++
++
++ 
++
++
++
++
++ 
++
++
++
++# 320 "../libc-symbols.h"
++
++
++
++# 1 "ctype.c" 2
++ 
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++ 
++
++
++
++
++int DEFUN( isalnum , (c), int c) { return __isctype(c,   _ISalnum ); } 
++int DEFUN( isalpha , (c), int c) { return __isctype(c,   _ISalpha ); } 
++int DEFUN( iscntrl , (c), int c) { return __isctype(c,   _IScntrl ); } 
++int DEFUN( isdigit , (c), int c) { return __isctype(c,   _ISdigit ); } 
++int DEFUN( islower , (c), int c) { return __isctype(c,   _ISlower ); } 
++int DEFUN( isgraph , (c), int c) { return __isctype(c,   _ISgraph ); } 
++int DEFUN( isprint , (c), int c) { return __isctype(c,   _ISprint ); } 
++int DEFUN( ispunct , (c), int c) { return __isctype(c,   _ISpunct ); } 
++int DEFUN( isspace , (c), int c) { return __isctype(c,   _ISspace ); } 
++int DEFUN( isupper , (c), int c) { return __isctype(c,   _ISupper ); } 
++int DEFUN( isxdigit , (c), int c) { return __isctype(c,   _ISxdigit ); } 
++
++int
++DEFUN(tolower, (c), int c)
++{
++  return __tolower (c);
++}
++
++int
++DEFUN(toupper, (c), int c)
++{
++  return __toupper (c);
++}
+diff -purN -x BOOT ../glibc-2.0.1/ctype/ctype.h glibc-2.0.1/ctype/ctype.h
+--- ../glibc-2.0.1/ctype/ctype.h       1996-11-08 13:22:43.000000000 +0100
++++ glibc-2.0.1/ctype/ctype.h  2018-06-05 22:05:26.852368283 +0200
+@@ -25,7 +25,7 @@
+ #define       _CTYPE_H        1
+ #include <features.h>
+ 
+-__BEGIN_DECLS
++/*__BEGIN_DECLS*/
+ 
+ #ifndef _ISbit
+ /* These are all the characteristics of characters.
+diff -purN -x BOOT ../glibc-2.0.1/glibcbug glibc-2.0.1/glibcbug
+--- ../glibc-2.0.1/glibcbug    1970-01-01 01:00:00.000000000 +0100
++++ glibc-2.0.1/glibcbug       2018-06-05 22:08:58.423830274 +0200
+@@ -0,0 +1,244 @@
++#! /bin/sh
++#
++# glibcbug - create a bug report and mail it to the bug address.
++#
++# configuration section:
++#       these variables are filled in by configure
++#
++VERSION="2.0.1"
++BUGGLIBC="address@hidden"
++ADDONS=""
++
++PATH=/bin:/usr/bin:/usr/local/bin:$PATH
++export PATH
++
++TEMP=/tmp/glibcbug.$$
++
++BUGADDR=${1-$BUGGLIBC}
++ENVIRONMENT=`uname -a`
++
++: ${EDITOR=emacs}
++
++: ${USER=${LOGNAME-`whoami`}}
++
++trap 'rm -f $TEMP $TEMP.x; exit 1' 1 2 3 13 15
++trap 'rm -f $TEMP $TEMP.x' 0
++
++
++# How to read the passwd database.
++PASSWD="cat /etc/passwd"
++
++if [ -f /usr/lib/sendmail ] ; then
++        MAIL_AGENT="/usr/lib/sendmail -oi -t"
++elif [ -f /usr/sbin/sendmail ] ; then
++        MAIL_AGENT="/usr/sbin/sendmail -oi -t"
++else
++        MAIL_AGENT=rmail
++fi
++
++# Figure out how to echo a string without a trailing newline
++N=`echo 'hi there\c'`
++case "$N" in
++*c)   ECHON1='echo -n' ECHON2= ;;
++*)    ECHON1=echo ECHON2='\c' ;;
++esac
++
++# Find out the name of the originator of this PR.
++if [ -n "$NAME" ]; then
++  ORIGINATOR="$NAME"
++elif [ -f $HOME/.fullname ]; then
++  ORIGINATOR="`sed -e '1q' $HOME/.fullname`"
++else
++  # Must use temp file due to incompatibilities in quoting behavior
++  # and to protect shell metacharacters in the expansion of $LOGNAME
++  $PASSWD | grep "^$LOGNAME:" | awk -F: '{print $5}' | sed -e 's/,.*//' > 
$TEMP
++  ORIGINATOR="`cat $TEMP`"
++  rm -f $TEMP
++fi
++
++if [ -n "$ORGANIZATION" ]; then
++  if [ -f "$ORGANIZATION" ]; then
++    ORGANIZATION="`cat $ORGANIZATION`"
++  fi
++else
++  if [ -f $HOME/.organization ]; then
++    ORGANIZATION="`cat $HOME/.organization`"
++  elif [ -f $HOME/.signature ]; then
++    ORGANIZATION=`sed -e "s/^/  /" $HOME/.signature; echo ">"`
++  fi
++fi
++
++# If they don't have a preferred editor set, then use
++if [ -z "$VISUAL" ]; then
++  if [ -z "$EDITOR" ]; then
++    EDIT=vi
++  else
++    EDIT="$EDITOR"
++  fi
++else
++  EDIT="$VISUAL"
++fi
++
++# Find out some information.
++SYSTEM=`( [ -f /bin/uname ] && /bin/uname -a ) || \
++        ( [ -f /usr/bin/uname ] && /usr/bin/uname -a ) || echo ""`
++ARCH=`[ -f /bin/arch ] && /bin/arch`
++MACHINE=`[ -f /bin/machine ] && /bin/machine`
++
++ORGANIZATION_C='<organization of PR author (multiple lines)>'
++SYNOPSIS_C='<synopsis of the problem (one line)>'
++SEVERITY_C='<[ non-critical | serious | critical ] (one line)>'
++PRIORITY_C='<[ low | medium | high ] (one line)>'
++CLASS_C='<[ sw-bug | doc-bug | change-request | support ] (one line)>'
++RELEASE_C='<release number or tag (one line)>'
++ENVIRONMENT_C='<machine, os, target, libraries (multiple lines)>'
++DESCRIPTION_C='<precise description of the problem (multiple lines)>'
++HOW_TO_REPEAT_C='<code/input/activities to reproduce the problem (multiple 
lines)>'
++FIX_C='<how to correct or work around the problem, if known (multiple lines)>'
++
++
++cat > $TEMP <<EOF
++SEND-PR: -*- send-pr -*-
++SEND-PR: Lines starting with \`SEND-PR' will be removed automatically, as
++SEND-PR: will all comments (text enclosed in \`<' and \`>').
++SEND-PR:
++From: ${USER}
++To: ${BUGADDR}
++Subject: [50 character or so descriptive subject here (for reference)]
++
++>Submitter-Id:        net
++>Originator:  ${ORIGINATOR}
++>Organization:
++${ORGANIZATION- $ORGANIZATION_C}
++>Confidential:        no
++>Synopsis:    $SYNOPSIS_C
++>Severity:    $SEVERITY_C
++>Priority:    $PRIORITY_C
++>Category:    libc
++>Class:               $CLASS_C
++>Release:     libc-${VERSION}
++>Environment:
++      $ENVIRONMENT_C
++`[ -n "$SYSTEM" ] && echo System: $SYSTEM`
++`[ -n "$ARCH" ] && echo Architecture: $ARCH`
++`[ -n "$MACHINE" ] && echo Machine: $MACHINE`
++`[ -n "$ADDONS" ] && echo Addons: $ADDONS`
++
++>Description:
++      $DESCRIPTION_C
++>How-To-Repeat:
++      $HOW_TO_REPEAT_C
++>Fix:
++      $FIX_C
++EOF
++
++chmod u+w $TEMP
++cp $TEMP $TEMP.x
++
++eval $EDIT $TEMP
++
++if cmp -s $TEMP $TEMP.x; then
++      echo "File not changed, no bug report submitted."
++      exit 1
++fi
++
++#
++#       Check the enumeration fields
++
++# This is a "sed-subroutine" with one keyword parameter
++# (with workaround for Sun sed bug)
++#
++SED_CMD='
++/$PATTERN/{
++s|||
++s|<.*>||
++s|^[  ]*||
++s|[   ]*$||
++p
++q
++}'
++
++
++while :; do
++  CNT=0
++
++  #
++  # 1) Severity
++  #
++  PATTERN=">Severity:"
++  SEVERITY=`eval sed -n -e "\"$SED_CMD\"" $TEMP`
++  case "$SEVERITY" in
++    ""|non-critical|serious|critical) CNT=`expr $CNT + 1` ;;
++    *)  echo "$COMMAND: \`$SEVERITY' is not a valid value for \`Severity'."
++  esac
++  #
++  # 2) Priority
++  #
++  PATTERN=">Priority:"
++  PRIORITY=`eval sed -n -e "\"$SED_CMD\"" $TEMP`
++  case "$PRIORITY" in
++    ""|low|medium|high) CNT=`expr $CNT + 1` ;;
++    *)  echo "$COMMAND: \`$PRIORITY' is not a valid value for \`Priority'."
++  esac
++  #
++  # 3) Class
++  #
++  PATTERN=">Class:"
++  CLASS=`eval sed -n -e "\"$SED_CMD\"" $TEMP`
++  case "$CLASS" in
++    ""|sw-bug|doc-bug|change-request|support) CNT=`expr $CNT + 1` ;;
++    *)  echo "$COMMAND: \`$CLASS' is not a valid value for \`Class'."
++  esac
++
++  [ $CNT -lt 3 ] &&
++    echo "Errors were found with the problem report."
++
++  while :; do
++    $ECHON1 "a)bort, e)dit or s)end? $ECHON2"
++    read input
++    case "$input" in
++      a*)
++      echo "$COMMAND: problem report saved in $HOME/dead.glibcbug."
++      cat $TEMP >> $HOME/dead.glibcbug
++        xs=1; exit
++        ;;
++      e*)
++        eval $EDIT $TEMP
++        continue 2
++        ;;
++      s*)
++        break 2
++        ;;
++    esac
++  done
++done
++#
++#       Remove comments and send the problem report
++#       (we have to use patterns, where the comment contains regex chars)
++#
++# /^>Originator:/s;$ORIGINATOR;;
++sed  -e "
++/^SEND-PR:/d
++/^>Organization:/,/^>[A-Za-z-]*:/s;$ORGANIZATION_C;;
++/^>Confidential:/s;<.*>;;
++/^>Synopsis:/s;$SYNOPSIS_C;;
++/^>Severity:/s;<.*>;;
++/^>Priority:/s;<.*>;;
++/^>Class:/s;<.*>;;
++/^>Release:/,/^>[A-Za-z-]*:/s;$RELEASE_C;;
++/^>Environment:/,/^>[A-Za-z-]*:/s;$ENVIRONMENT_C;;
++/^>Description:/,/^>[A-Za-z-]*:/s;$DESCRIPTION_C;;
++/^>How-To-Repeat:/,/^>[A-Za-z-]*:/s;$HOW_TO_REPEAT_C;;
++/^>Fix:/,/^>[A-Za-z-]*:/s;$FIX_C;;
++" $TEMP > $TEMP.x
++
++if $MAIL_AGENT $BUGGLIBC < $TEMP.x; then
++  echo "$COMMAND: problem report sent"
++  xs=0; exit
++else
++  echo "$COMMAND: mysterious mail failure, report not sent."
++  echo "$COMMAND: problem report saved in $HOME/dead.glibcbug."
++  cat $TEMP >> $HOME/dead.glibcbug
++fi
++
++exit 0
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info glibc-2.0.1/manual/libc.info
+--- ../glibc-2.0.1/manual/libc.info    1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info       1970-01-01 01:00:00.000000000 +0100
+@@ -1,596 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-Indirect:
+-libc.info-1: 1168
+-libc.info-2: 50130
+-libc.info-3: 97453
+-libc.info-4: 144446
+-libc.info-5: 193430
+-libc.info-6: 237807
+-libc.info-7: 285360
+-libc.info-8: 334723
+-libc.info-9: 379684
+-libc.info-10: 428359
+-libc.info-11: 477650
+-libc.info-12: 526627
+-libc.info-13: 576207
+-libc.info-14: 625641
+-libc.info-15: 673159
+-libc.info-16: 720930
+-libc.info-17: 769559
+-libc.info-18: 816715
+-libc.info-19: 864190
+-libc.info-20: 914097
+-libc.info-21: 963959
+-libc.info-22: 1011044
+-libc.info-23: 1058556
+-libc.info-24: 1108289
+-libc.info-25: 1158030
+-libc.info-26: 1207860
+-libc.info-27: 1256153
+-libc.info-28: 1305051
+-libc.info-29: 1410972
+-libc.info-30: 1453346
+-libc.info-31: 1480210
+-libc.info-32: 1530394
+-libc.info-33: 1567426
+-
+-Tag Table:
+-(Indirect)
+-Node: Top1168
+-Node: Introduction40477
+-Node: Getting Started41825
+-Node: Standards and Portability43285
+-Node: ISO C44670
+-Node: POSIX46187
+-Node: Berkeley Unix47867
+-Node: SVID48635
+-Node: Using the Library49407
+-Node: Header Files50130
+-Node: Macro Definitions54082
+-Node: Reserved Names56432
+-Node: Feature Test Macros61114
+-Node: Roadmap to the Manual66998
+-Node: Error Reporting74211
+-Node: Checking for Errors75139
+-Node: Error Codes79354
+-Node: Error Messages97453
+-Node: Memory Allocation102288
+-Node: Memory Concepts103291
+-Node: Dynamic Allocation and C104561
+-Node: Unconstrained Allocation106645
+-Node: Basic Allocation107972
+-Node: Malloc Examples109676
+-Node: Freeing after Malloc111657
+-Node: Changing Block Size113473
+-Node: Allocating Cleared Space116037
+-Node: Efficiency and Malloc116828
+-Node: Aligned Memory Blocks118326
+-Node: Heap Consistency Checking119694
+-Node: Hooks for Malloc122487
+-Node: Statistics of Malloc124736
+-Node: Summary of Malloc126242
+-Node: Obstacks128081
+-Node: Creating Obstacks129699
+-Node: Preparing for Obstacks131598
+-Node: Allocation in an Obstack133938
+-Node: Freeing Obstack Objects136633
+-Node: Obstack Functions137969
+-Node: Growing Objects140199
+-Node: Extra Fast Growing144446
+-Node: Status of an Obstack148065
+-Node: Obstacks Data Alignment149484
+-Node: Obstack Chunks151170
+-Node: Summary of Obstacks153527
+-Node: Variable Size Automatic156941
+-Node: Alloca Example158497
+-Node: Advantages of Alloca159614
+-Node: Disadvantages of Alloca161506
+-Node: GNU C Variable-Size Arrays162251
+-Node: Relocating Allocator163409
+-Node: Relocator Concepts163971
+-Node: Using Relocator165484
+-Node: Memory Warnings166869
+-Node: Character Handling168181
+-Node: Classification of Characters169130
+-Node: Case Conversion172791
+-Node: String and Array Utilities174639
+-Node: Representation of Strings176450
+-Node: String/Array Conventions179392
+-Node: String Length181224
+-Node: Copying and Concatenation182209
+-Node: String/Array Comparison193430
+-Node: Collation Functions198493
+-Node: Search Functions205455
+-Node: Finding Tokens in a String209726
+-Node: I/O Overview215868
+-Node: I/O Concepts217381
+-Node: Streams and File Descriptors218526
+-Node: File Position221617
+-Node: File Names223751
+-Node: Directories224637
+-Node: File Name Resolution226374
+-Node: File Name Errors229303
+-Node: File Name Portability230852
+-Node: I/O on Streams232844
+-Node: Streams234800
+-Node: Standard Streams236141
+-Node: Opening Streams237807
+-Node: Closing Streams243664
+-Node: Simple Output246208
+-Node: Character Input248544
+-Node: Line Input251653
+-Node: Unreading256641
+-Node: Unreading Idea257450
+-Node: How Unread258276
+-Node: Block Input/Output260759
+-Node: Formatted Output262988
+-Node: Formatted Output Basics264755
+-Node: Output Conversion Syntax267248
+-Node: Table of Output Conversions270974
+-Node: Integer Conversions273507
+-Node: Floating-Point Conversions278171
+-Node: Other Output Conversions282200
+-Node: Formatted Output Functions285360
+-Node: Dynamic Output289041
+-Node: Variable Arguments Output290678
+-Node: Parsing a Template String296190
+-Node: Example of Parsing300017
+-Node: Customizing Printf302305
+-Node: Registering New Conversions304154
+-Node: Conversion Specifier Options306145
+-Node: Defining the Output Handler309818
+-Node: Printf Extension Example312284
+-Node: Formatted Input314592
+-Node: Formatted Input Basics315671
+-Node: Input Conversion Syntax318351
+-Node: Table of Input Conversions321713
+-Node: Numeric Input Conversions324010
+-Node: String Input Conversions327788
+-Node: Dynamic String Input331881
+-Node: Other Input Conversions333071
+-Node: Formatted Input Functions334723
+-Node: Variable Arguments Input336289
+-Node: EOF and Errors337924
+-Node: Binary Streams340144
+-Node: File Positioning342668
+-Node: Portable Positioning346501
+-Node: Stream Buffering349972
+-Node: Buffering Concepts351557
+-Node: Flushing Buffers352920
+-Node: Controlling Buffering354416
+-Node: Other Kinds of Streams358851
+-Node: String Streams360113
+-Node: Obstack Streams364233
+-Node: Custom Streams366267
+-Node: Streams and Cookies366920
+-Node: Hook Functions369967
+-Node: Low-Level I/O372353
+-Node: Opening and Closing Files375005
+-Node: I/O Primitives379684
+-Node: File Position Primitive387937
+-Node: Descriptors and Streams393372
+-Node: Stream/Descriptor Precautions395792
+-Node: Linked Channels396999
+-Node: Independent Channels398227
+-Node: Cleaning Streams400130
+-Node: Waiting for I/O402333
+-Node: Control Operations410084
+-Node: Duplicating Descriptors412368
+-Node: Descriptor Flags416630
+-Node: File Status Flags420036
+-Node: Access Modes421490
+-Node: Open-time Flags423779
+-Node: Operating Modes428359
+-Node: Getting File Status Flags431125
+-Node: File Locks433736
+-Node: Interrupt Input442639
+-Node: File System Interface445058
+-Node: Working Directory446458
+-Node: Accessing Directories450212
+-Node: Directory Entries451418
+-Node: Opening a Directory454218
+-Node: Reading/Closing Directory455910
+-Node: Simple Directory Lister458844
+-Node: Random Access Directory459823
+-Node: Hard Links461290
+-Node: Symbolic Links464083
+-Node: Deleting Files467849
+-Node: Renaming Files470779
+-Node: Creating Directories474406
+-Node: File Attributes476154
+-Node: Attribute Meanings477650
+-Node: Reading Attributes482733
+-Node: Testing File Type484635
+-Node: File Owner487851
+-Node: Permission Bits491544
+-Node: Access Permission496651
+-Node: Setting Permissions497801
+-Node: Testing File Access503016
+-Node: File Times506659
+-Node: Making Special Files511167
+-Node: Temporary Files512844
+-Node: Pipes and FIFOs519051
+-Node: Creating a Pipe520634
+-Node: Pipe to a Subprocess523787
+-Node: FIFO Special Files526627
+-Node: Pipe Atomicity528200
+-Node: Sockets529084
+-Node: Socket Concepts530959
+-Node: Communication Styles534173
+-Node: Socket Addresses536025
+-Node: Address Formats538066
+-Node: Setting Address540749
+-Node: Reading Address542453
+-Node: File Namespace544211
+-Node: File Namespace Concepts544701
+-Node: File Namespace Details546296
+-Node: File Socket Example547910
+-Node: Internet Namespace549234
+-Node: Internet Address Format550961
+-Node: Host Addresses552330
+-Node: Abstract Host Addresses553390
+-Node: Host Address Data Type556183
+-Node: Host Address Functions558074
+-Node: Host Names560501
+-Node: Ports565513
+-Node: Services Database567551
+-Node: Byte Order570378
+-Node: Protocols Database572666
+-Node: Inet Example576207
+-Node: Misc Namespaces578237
+-Node: Open/Close Sockets578987
+-Node: Creating a Socket579485
+-Node: Closing a Socket581153
+-Node: Socket Pairs582683
+-Node: Connections584693
+-Node: Connecting585787
+-Node: Listening588343
+-Node: Accepting Connections590428
+-Node: Who is Connected593284
+-Node: Transferring Data594380
+-Node: Sending Data595490
+-Node: Receiving Data597738
+-Node: Socket Data Options599202
+-Node: Byte Stream Example600065
+-Node: Server Example602043
+-Node: Out-of-Band Data606090
+-Node: Datagrams611944
+-Node: Sending Datagrams612973
+-Node: Receiving Datagrams614630
+-Node: Datagram Example616431
+-Node: Example Receiver618349
+-Node: Inetd620916
+-Node: Inetd Servers621724
+-Node: Configuring Inetd622967
+-Node: Socket Options625641
+-Node: Socket Option Functions626349
+-Node: Socket-Level Options627907
+-Node: Networks Database631541
+-Node: Low-Level Terminal Interface634403
+-Node: Is It a Terminal635738
+-Node: I/O Queues636954
+-Node: Canonical or Not638924
+-Node: Terminal Modes640771
+-Node: Mode Data Types642047
+-Node: Mode Functions643875
+-Node: Setting Modes647815
+-Node: Input Modes649803
+-Node: Output Modes655070
+-Node: Control Modes656683
+-Node: Local Modes660773
+-Node: Line Speed667087
+-Node: Special Characters671247
+-Node: Editing Characters673159
+-Node: Signal Characters677500
+-Node: Start/Stop Characters680369
+-Node: Other Special682240
+-Node: Noncanonical Input684054
+-Node: Line Control688867
+-Node: Noncanon Example693179
+-Node: Mathematics695374
+-Node: Domain and Range Errors696578
+-Node: Trig Functions699801
+-Node: Inverse Trig Functions701171
+-Node: Exponents and Logarithms703609
+-Node: Hyperbolic Functions706510
+-Node: Pseudo-Random Numbers708089
+-Node: ISO Random709675
+-Node: BSD Random710848
+-Node: Arithmetic712765
+-Node: Not a Number713674
+-Node: Predicates on Floats715016
+-Node: Absolute Value716590
+-Node: Normalization Functions718088
+-Node: Rounding and Remainders720930
+-Node: Integer Division724298
+-Node: Parsing of Numbers726448
+-Node: Parsing of Integers727100
+-Node: Parsing of Floats734575
+-Node: Searching and Sorting739039
+-Node: Comparison Functions739830
+-Node: Array Search Function740944
+-Node: Array Sort Function742367
+-Node: Search/Sort Example744339
+-Node: Pattern Matching747789
+-Node: Wildcard Matching748591
+-Node: Globbing751469
+-Node: Calling Glob752259
+-Node: Flags for Globbing755840
+-Node: Regular Expressions759338
+-Node: POSIX Regexp Compilation760322
+-Node: Flags for POSIX Regexps764437
+-Node: Matching POSIX Regexps765344
+-Node: Regexp Subexpressions767505
+-Node: Subexpression Complications769559
+-Node: Regexp Cleanup771918
+-Node: Word Expansion774244
+-Node: Expansion Stages775412
+-Node: Calling Wordexp776905
+-Node: Flags for Wordexp780868
+-Node: Wordexp Example782821
+-Node: Date and Time784796
+-Node: Processor Time785920
+-Node: Basic CPU Time786678
+-Node: Detailed CPU Time788697
+-Node: Calendar Time791162
+-Node: Simple Calendar Time792740
+-Node: High-Resolution Calendar794497
+-Node: Broken-down Time800217
+-Node: Formatting Date and Time805433
+-Node: TZ Variable816715
+-Node: Time Zone Functions822776
+-Node: Time Functions Example825441
+-Node: Setting an Alarm826556
+-Node: Sleeping831783
+-Node: Resource Usage834439
+-Node: Limits on Resources837950
+-Node: Priority842324
+-Node: Extended Characters845586
+-Node: Extended Char Intro847194
+-Node: Locales and Extended Chars849131
+-Node: Multibyte Char Intro850181
+-Node: Wide Char Intro857475
+-Node: Wide String Conversion859242
+-Node: Length of Char862479
+-Node: Converting One Char864190
+-Node: Example of Conversion867587
+-Node: Shift State870477
+-Node: Locales873130
+-Node: Effects of Locale874698
+-Node: Choosing Locale876634
+-Node: Locale Categories877958
+-Node: Setting the Locale879605
+-Node: Standard Locales883499
+-Node: Numeric Formatting884739
+-Node: General Numeric886249
+-Node: Currency Symbol889171
+-Node: Sign of Money Amount893781
+-Node: Non-Local Exits896085
+-Node: Non-Local Intro896704
+-Node: Non-Local Details900431
+-Node: Non-Local Exits and Signals903507
+-Node: Signal Handling904977
+-Node: Concepts of Signals907012
+-Node: Kinds of Signals907576
+-Node: Signal Generation908973
+-Node: Delivery of Signal911240
+-Node: Standard Signals914097
+-Node: Program Error Signals915690
+-Node: Termination Signals923148
+-Node: Alarm Signals926986
+-Node: Asynchronous I/O Signals928226
+-Node: Job Control Signals929417
+-Node: Operation Error Signals934029
+-Node: Miscellaneous Signals935968
+-Node: Signal Messages937664
+-Node: Signal Actions939550
+-Node: Basic Signal Handling940495
+-Node: Advanced Signal Handling945428
+-Node: Signal and Sigaction948384
+-Node: Sigaction Function Example950136
+-Node: Flags for Sigaction952452
+-Node: Initial Signal Actions954830
+-Node: Defining Handlers956213
+-Node: Handler Returns958398
+-Node: Termination in Handler960448
+-Node: Longjmp in Handler961864
+-Node: Signals in Handler963959
+-Node: Merged Signals966079
+-Node: Nonreentrancy971789
+-Node: Atomic Data Access977337
+-Node: Non-atomic Example978373
+-Node: Atomic Types980144
+-Node: Atomic Usage981152
+-Node: Interrupted Primitives982622
+-Node: Generating Signals985922
+-Node: Signaling Yourself986515
+-Node: Signaling Another Process988497
+-Node: Permission for kill991880
+-Node: Kill Example993676
+-Node: Blocking Signals996020
+-Node: Why Block997792
+-Node: Signal Sets999329
+-Node: Process Signal Mask1002355
+-Node: Testing for Delivery1005363
+-Node: Blocking for Handler1006613
+-Node: Checking for Pending Signals1009032
+-Node: Remembering a Signal1011044
+-Node: Waiting for a Signal1014593
+-Node: Using Pause1015138
+-Node: Pause Problems1016358
+-Node: Sigsuspend1018082
+-Node: Signal Stack1020792
+-Node: BSD Signal Handling1026136
+-Node: BSD Handler1027410
+-Node: Blocking in BSD1029844
+-Node: Process Startup1031298
+-Node: Program Arguments1032333
+-Node: Argument Syntax1035062
+-Node: Parsing Options1037692
+-Node: Example of Getopt1040983
+-Node: Long Options1043699
+-Node: Long Option Example1047760
+-Node: Suboptions1050609
+-Node: Suboptions Example1052558
+-Node: Environment Variables1054653
+-Node: Environment Access1056514
+-Node: Standard Environment1058556
+-Node: Program Termination1062239
+-Node: Normal Termination1063458
+-Node: Exit Status1064684
+-Node: Cleanups on Exit1067703
+-Node: Aborting a Program1069520
+-Node: Termination Internals1070419
+-Node: Processes1072195
+-Node: Running a Command1074218
+-Node: Process Creation Concepts1075711
+-Node: Process Identification1077721
+-Node: Creating a Process1078645
+-Node: Executing a File1082261
+-Node: Process Completion1089296
+-Node: Process Completion Status1094305
+-Node: BSD Wait Functions1095949
+-Node: Process Creation Example1097841
+-Node: Job Control1100091
+-Node: Concepts of Job Control1101371
+-Node: Job Control is Optional1104728
+-Node: Controlling Terminal1105778
+-Node: Access to the Terminal1106685
+-Node: Orphaned Process Groups1108289
+-Node: Implementing a Shell1109281
+-Node: Data Structures1110164
+-Node: Initializing the Shell1112807
+-Node: Launching Jobs1116543
+-Node: Foreground and Background1123996
+-Node: Stopped and Terminated Jobs1127105
+-Node: Continuing Stopped Jobs1132287
+-Node: Missing Pieces1133914
+-Node: Functions for Job Control1135538
+-Node: Identifying the Terminal1136018
+-Node: Process Group Functions1137592
+-Node: Terminal Access Functions1141144
+-Node: Name Service Switch1144045
+-Node: NSS Basics1145379
+-Node: NSS Configuration File1146956
+-Node: Services in the NSS configuration1148654
+-Node: Actions in the NSS configuration1149935
+-Node: Notes on NSS Configuration File1153094
+-Node: NSS Module Internals1154970
+-Node: NSS Module Names1155666
+-Node: NSS Modules Interface1158030
+-Node: Extending NSS1161514
+-Node: Adding another Service to NSS1162445
+-Node: NSS Module Function Internals1164664
+-Node: Users and Groups1169065
+-Node: User and Group IDs1171541
+-Node: Process Persona1172448
+-Node: Why Change Persona1173959
+-Node: How Change Persona1175840
+-Node: Reading Persona1177322
+-Node: Setting User ID1179592
+-Node: Setting Groups1181802
+-Node: Enable/Disable Setuid1184359
+-Node: Setuid Program Example1186398
+-Node: Tips for Setuid1189867
+-Node: Who Logged In1191955
+-Node: User Database1194123
+-Node: User Data Structure1194784
+-Node: Lookup User1196063
+-Node: Scanning All Users1199153
+-Node: Writing a User Entry1202532
+-Node: Group Database1203431
+-Node: Group Data Structure1204018
+-Node: Lookup Group1204804
+-Node: Scanning All Groups1207860
+-Node: Netgroup Database1211141
+-Node: Netgroup Data1211575
+-Node: Lookup Netgroup1213139
+-Node: Netgroup Membership1216551
+-Node: Database Example1217881
+-Node: System Information1220055
+-Node: Host Identification1220652
+-Node: Hardware/Software Type ID1223871
+-Node: System Configuration1226570
+-Node: General Limits1228137
+-Node: System Options1231776
+-Node: Version Supported1235108
+-Node: Sysconf1236945
+-Node: Sysconf Definition1237581
+-Node: Constants for Sysconf1238253
+-Node: Examples of Sysconf1241386
+-Node: Minimums1242379
+-Node: Limits for Files1244455
+-Node: Options for Files1247457
+-Node: File Minimums1249746
+-Node: Pathconf1251408
+-Node: Utility Limits1254095
+-Node: Utility Minimums1256153
+-Node: String Parameters1257905
+-Node: Language Features1259959
+-Node: Consistency Checking1260890
+-Node: Variadic Functions1265528
+-Node: Why Variadic1266600
+-Node: How Variadic1268565
+-Node: Variadic Prototypes1269854
+-Node: Receiving Arguments1271012
+-Node: How Many Arguments1273726
+-Node: Calling Variadics1275397
+-Node: Argument Macros1277534
+-Node: Variadic Example1279174
+-Node: Old Varargs1280326
+-Node: Null Pointer Constant1281996
+-Node: Important Data Types1283081
+-Node: Data Type Measurements1285647
+-Node: Width of Type1286504
+-Node: Range of Type1287410
+-Node: Floating Type Macros1290674
+-Node: Floating Point Concepts1291934
+-Node: Floating Point Parameters1295669
+-Node: IEEE Floating Point1302603
+-Node: Structure Measurement1304356
+-Node: Library Summary1305051
+-Node: Maintenance1410972
+-Node: Installation1411717
+-Node: Tools for Installation1418563
+-Node: Supported Configurations1419651
+-Node: Reporting Bugs1421162
+-Node: Source Layout1423539
+-Node: Porting1427495
+-Node: Hierarchy Conventions1435283
+-Node: Porting to Unix1440203
+-Node: Contributors1442048
+-Node: Copying1453346
+-Node: Concept Index1480210
+-Node: Type Index1530394
+-Node: Function Index1535184
+-Node: Variable Index1567426
+-Node: File Index1598743
+-
+-End Tag Table
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-1 
glibc-2.0.1/manual/libc.info-1
+--- ../glibc-2.0.1/manual/libc.info-1  1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-1     1970-01-01 01:00:00.000000000 +0100
+@@ -1,1089 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
+-
+-Main Menu
+-*********
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta of the GNU C Library.
+-
+-* Menu:
+-
+-* Introduction::                Purpose of the GNU C Library.
+-* Error Reporting::             How the GNU Library functions report
+-                                 error conditions.
+-* Memory Allocation::           Your program can allocate memory dynamically
+-                                 and manipulate it via pointers.
+-* Character Handling::          Character testing and conversion functions.
+-* String and Array Utilities::  Utilities for copying and comparing
+-                                 strings and arrays.
+-* Extended Characters::         Support for extended character sets.
+-* Locales::                     The country and language can affect
+-                                 the behavior of library functions.
+-* Searching and Sorting::       General searching and sorting functions.
+-* Pattern Matching::            Matching wildcards and regular expressions,
+-                                 and shell-style "word expansion".
+-* I/O Overview::                Introduction to the I/O facilities.
+-* Streams: I/O on Streams.      High-level, portable I/O facilities.
+-* Low-Level I/O::               Low-level, less portable I/O.
+-* File System Interface::       Functions for manipulating files.
+-* Pipes and FIFOs::             A simple interprocess communication mechanism.
+-* Sockets::                     A more complicated interprocess communication
+-                                 mechanism, with support for networking.
+-* Low-Level Terminal Interface::How to change the characteristics
+-                                 of a terminal device.
+-* Mathematics::                 Math functions (transcendental functions,
+-                                 random numbers, absolute value, etc.).
+-* Arithmetic::                  Low-level arithmetic functions.
+-* Date and Time::               Functions for getting the date and time,
+-                                 and for conversion between formats.
+-* Non-Local Exits::             The `setjmp' and `longjmp' facilities.
+-* Signal Handling::             All about signals; how to send them,
+-                                 block them, and handle them.
+-* Process Startup::             Writing the beginning and end of your program.
+-* Processes::                   How to create processes and run other 
programs.
+-* Job Control::                 All about process groups and sessions.
+-* Name Service Switch::         Accessing the various system databases.
+-* Users and Groups::            How users are identified and classified.
+-* System Information::          Getting information about the
+-                                 hardware and software configuration
+-                                 of the machine a program runs on.
+-* System Configuration::        Parameters describing operating system limits.
+-
+-Appendices
+-
+-* Language Features::           C language features provided by the library.
+-
+-* Library Summary::             A summary showing the syntax, header file,
+-                                 and derivation of each library feature.
+-* Maintenance::                 How to install and maintain the GNU C Library.
+-* Copying::                     The GNU Library General Public License says
+-                                 how you can copy and share the GNU C Library.
+-
+-Indices
+-
+-* Concept Index::               Index of concepts and names.
+-* Type Index::                  Index of types and type qualifiers.
+-* Function Index::              Index of functions and function-like macros.
+-* Variable Index::              Index of variables and variable-like macros.
+-* File Index::                  Index of programs and files.
+-
+- -- The Detailed Node Listing --
+-
+-Introduction
+-
+-* Getting Started::             Getting Started
+-* Standards and Portability::   Standards and Portability
+-* Using the Library::           Using the Library
+-* Roadmap to the Manual::       Roadmap to the Manual
+-
+-Standards and Portability
+-
+-* ISO C::                       The American National Standard for the
+-                                 C programming language.
+-* POSIX::                       The ISO/IEC 9945 (aka IEEE 1003) standards
+-                                 for operating systems.
+-* Berkeley Unix::               BSD and SunOS.
+-* SVID::                        The System V Interface Description.
+-
+-Using the Library
+-
+-* Header Files::                How to use the header files in your programs.
+-* Macro Definitions::           Some functions in the library may really
+-                                 be implemented as macros.
+-* Reserved Names::              The C standard reserves some names for
+-                                 the library, and some for users.
+-* Feature Test Macros::         How to control what names are defined.
+-
+-Error Reporting
+-
+-* Checking for Errors::         How errors are reported by library functions.
+-* Error Codes::                 What all the error codes are.
+-* Error Messages::              Mapping error codes onto error messages.
+-
+-Memory Allocation
+-
+-* Memory Concepts::             An introduction to concepts and terminology.
+-* Dynamic Allocation and C::    How to get different kinds of allocation in C.
+-* Unconstrained Allocation::    The `malloc' facility allows fully general
+-                                 dynamic allocation.
+-* Obstacks::                    Obstacks are less general than malloc
+-                                 but more efficient and convenient.
+-* Variable Size Automatic::     Allocation of variable-sized blocks
+-                                 of automatic storage that are freed when the
+-                                 calling function returns.
+-* Relocating Allocator::        Waste less memory, if you can tolerate
+-                                 automatic relocation of the blocks you get.
+-* Memory Warnings::             Getting warnings when memory is nearly full.
+-
+-Unconstrained Allocation
+-
+-* Basic Allocation::            Simple use of `malloc'.
+-* Malloc Examples::             Examples of `malloc'.  `xmalloc'.
+-* Freeing after Malloc::        Use `free' to free a block you
+-                                 got with `malloc'.
+-* Changing Block Size::         Use `realloc' to make a block
+-                                 bigger or smaller.
+-* Allocating Cleared Space::    Use `calloc' to allocate a
+-                                 block and clear it.
+-* Efficiency and Malloc::       Efficiency considerations in use of
+-                                 these functions.
+-* Aligned Memory Blocks::       Allocating specially aligned memory:
+-                                 `memalign' and `valloc'.
+-* Heap Consistency Checking::   Automatic checking for errors.
+-* Hooks for Malloc::            You can use these hooks for debugging
+-                               programs that use `malloc'.
+-* Statistics of Malloc::        Getting information about how much
+-                               memory your program is using.
+-* Summary of Malloc::           Summary of `malloc' and related functions.
+-
+-Obstacks
+-
+-* Creating Obstacks::         How to declare an obstack in your program.
+-* Preparing for Obstacks::    Preparations needed before you can
+-                               use obstacks.
+-* Allocation in an Obstack::    Allocating objects in an obstack.
+-* Freeing Obstack Objects::     Freeing objects in an obstack.
+-* Obstack Functions::         The obstack functions are both
+-                               functions and macros.
+-* Growing Objects::             Making an object bigger by stages.
+-* Extra Fast Growing::                Extra-high-efficiency (though more
+-                               complicated) growing objects.
+-* Status of an Obstack::        Inquiries about the status of an obstack.
+-* Obstacks Data Alignment::     Controlling alignment of objects in obstacks.
+-* Obstack Chunks::              How obstacks obtain and release chunks.
+-                              Efficiency considerations.
+-* Summary of Obstacks::
+-
+-Automatic Storage with Variable Size
+-
+-* Alloca Example::              Example of using `alloca'.
+-* Advantages of Alloca::        Reasons to use `alloca'.
+-* Disadvantages of Alloca::     Reasons to avoid `alloca'.
+-* GNU C Variable-Size Arrays::  Only in GNU C, here is an alternative
+-                               method of allocating dynamically and
+-                               freeing automatically.
+-Relocating Allocator
+-
+-* Relocator Concepts::                How to understand relocating allocation.
+-* Using Relocator::           Functions for relocating allocation.
+-
+-Character Handling
+-
+-* Classification of Characters::Testing whether characters are
+-                                 letters, digits, punctuation, etc.
+-* Case Conversion::             Case mapping, and the like.
+-
+-String and Array Utilities
+-
+-* Representation of Strings::   Introduction to basic concepts.
+-* String/Array Conventions::    Whether to use a string function or an
+-                               arbitrary array function.
+-* String Length::               Determining the length of a string.
+-* Copying and Concatenation::   Functions to copy the contents of strings
+-                               and arrays.
+-* String/Array Comparison::     Functions for byte-wise and character-wise
+-                               comparison.
+-* Collation Functions::         Functions for collating strings.
+-* Search Functions::            Searching for a specific element or substring.
+-* Finding Tokens in a String::  Splitting a string into tokens by looking
+-                               for delimiters.
+-
+-Extended Characters
+-
+-* Extended Char Intro::         Multibyte codes versus wide characters.
+-* Locales and Extended Chars::  The locale selects the character codes.
+-* Multibyte Char Intro::        How multibyte codes are represented.
+-* Wide Char Intro::             How wide characters are represented.
+-* Wide String Conversion::      Converting wide strings to multibyte code
+-                                   and vice versa.
+-* Length of Char::              how many bytes make up one multibyte char.
+-* Converting One Char::         Converting a string character by character.
+-* Example of Conversion::       Example showing why converting
+-                                 one character at a time may be useful.
+-* Shift State::                 Multibyte codes with "shift characters".
+-
+-Locales and Internationalization
+-
+-* Effects of Locale::           Actions affected by the choice of locale.
+-* Choosing Locale::             How the user specifies a locale.
+-* Locale Categories::           Different purposes for which
+-                                 you can select a locale.
+-* Setting the Locale::          How a program specifies the locale.
+-* Standard Locales::            Locale names available on all systems.
+-* Numeric Formatting::          How to format numbers for the chosen locale.
+-
+-Searching and Sorting
+-
+-* Comparison Functions::        Defining how to compare two objects.
+-                              Since the sort and search facilities are
+-                              general, you have to specify the ordering.
+-* Array Search Function::       The `bsearch' function.
+-* Array Sort Function::         The `qsort' function.
+-* Search/Sort Example::         An example program.
+-
+-Pattern Matching
+-
+-* Wildcard Matching::    Matching a wildcard pattern against a single string.
+-* Globbing::             Finding the files that match a wildcard pattern.
+-* Regular Expressions::  Matching regular expressions against strings.
+-* Word Expansion::       Expanding shell variables, nested commands,
+-                          arithmetic, and wildcards.
+-                        This is what the shell does with shell commands.
+-
+-I/O Overview
+-
+-* I/O Concepts::                Some basic information and terminology.
+-* File Names::                  How to refer to a file.
+-
+-I/O Concepts
+-
+-* Streams and File Descriptors:: The GNU Library provides two ways
+-                                  to access the contents of files.
+-* File Position::               The number of bytes from the
+-                                 beginning of the file.
+-
+-File Names
+-
+-* Directories::                 Directories contain entries for files.
+-* File Name Resolution::        A file name specifies how to look up a file.
+-* File Name Errors::            Error conditions relating to file names.
+-* File Name Portability::       File name portability and syntax issues.
+-
+-I/O on Streams
+-
+-* Streams::                     About the data type representing a stream.
+-* Standard Streams::            Streams to the standard input and output
+-                                 devices are created for you.
+-* Opening Streams::             How to create a stream to talk to a file.
+-* Closing Streams::             Close a stream when you are finished with it.
+-* Simple Output::               Unformatted output by characters and lines.
+-* Character Input::             Unformatted input by characters and words.
+-* Line Input::                  Reading a line or a record from a stream.
+-* Unreading::                   Peeking ahead/pushing back input just read.
+-* Formatted Output::            `printf' and related functions.
+-* Customizing Printf::          You can define new conversion specifiers for
+-                                 `printf' and friends.
+-* Formatted Input::             `scanf' and related functions.
+-* Block Input/Output::          Input and output operations on blocks of data.
+-* EOF and Errors::              How you can tell if an I/O error happens.
+-* Binary Streams::              Some systems distinguish between text files
+-                                 and binary files.
+-* File Positioning::            About random-access streams.
+-* Portable Positioning::        Random access on peculiar ISO C systems.
+-* Stream Buffering::            How to control buffering of streams.
+-* Temporary Files::             How to open a temporary file.
+-* Other Kinds of Streams::      Other Kinds of Streams
+-
+-Unreading
+-
+-* Unreading Idea::              An explanation of unreading with pictures.
+-* How Unread::                  How to call `ungetc' to do unreading.
+-
+-Formatted Output
+-
+-* Formatted Output Basics::     Some examples to get you started.
+-* Output Conversion Syntax::    General syntax of conversion specifications.
+-* Table of Output Conversions:: Summary of output conversions, what they do.
+-* Integer Conversions::         Details of formatting integers.
+-* Floating-Point Conversions::  Details of formatting floating-point numbers.
+-* Other Output Conversions::    Details about formatting of strings,
+-                                 characters, pointers, and the like.
+-* Formatted Output Functions::  Descriptions of the actual functions.
+-* Variable Arguments Output::   `vprintf' and friends.
+-* Parsing a Template String::   What kinds of arguments does
+-                                 a given template call for?
+-
+-Customizing Printf
+-
+-* Registering New Conversions::
+-* Conversion Specifier Options::
+-* Defining the Output Handler::
+-* Printf Extension Example::
+-
+-Formatted Input
+-
+-* Formatted Input Basics::      Some basics to get you started.
+-* Input Conversion Syntax::     Syntax of conversion specifications.
+-* Table of Input Conversions::  Summary of input conversions and what they do.
+-* Numeric Input Conversions::   Details of conversions for reading numbers.
+-* String Input Conversions::    Details of conversions for reading strings.
+-* Other Input Conversions::     Details of miscellaneous other conversions.
+-* Formatted Input Functions::   Descriptions of the actual functions.
+-* Variable Arguments Input::    `vscanf' and friends.
+-
+-Stream Buffering
+-
+-* Buffering Concepts::          Terminology is defined here.
+-* Flushing Buffers::            How to ensure that output buffers are flushed.
+-* Controlling Buffering::       How to specify what kind of buffering to use.
+-
+-Other Kinds of Streams
+-
+-* String Streams::
+-* Custom Streams::
+-
+-Programming Your Own Custom Streams
+-
+-* Streams and Cookies::
+-* Hook Functions::
+-
+-Low-Level I/O
+-
+-* Opening and Closing Files::   How to open and close file descriptors.
+-* I/O Primitives::              Reading and writing data.
+-* File Position Primitive::     Setting a descriptor's file position.
+-* Descriptors and Streams::     Converting descriptor to stream or vice-versa.
+-* Stream/Descriptor Precautions::  Precautions needed if you use both
+-                                    descriptors and streams.
+-* Waiting for I/O::             How to check for input or output
+-                                 on multiple file descriptors.
+-* Control Operations::          Various other operations on file descriptors.
+-* Duplicating Descriptors::     Fcntl commands for duplicating descriptors.
+-* Descriptor Flags::            Fcntl commands for manipulating flags
+-                                 associated with file descriptors.
+-* File Status Flags::           Fcntl commands for manipulating flags
+-                                 associated with open files.
+-* File Locks::                  Fcntl commands for implementing file locking.
+-* Interrupt Input::             Getting a signal when input arrives.
+-
+-File System Interface
+-
+-* Working Directory::           This is used to resolve relative file names.
+-* Accessing Directories::       Finding out what files a directory contains.
+-* Hard Links::                  Adding alternate names to a file.
+-* Symbolic Links::              A file that "points to" a file name.
+-* Deleting Files::              How to delete a file, and what that means.
+-* Renaming Files::              Changing a file's name.
+-* Creating Directories::        A system call just for creating a directory.
+-* File Attributes::             Attributes of individual files.
+-* Making Special Files::        How to create special files.
+-
+-Accessing Directories
+-
+-* Directory Entries::           Format of one directory entry.
+-* Opening a Directory::         How to open a directory stream.
+-* Reading/Closing Directory::   How to read directory entries from the stream.
+-* Simple Directory Lister::     A very simple directory listing program.
+-* Random Access Directory::     Rereading part of the directory
+-                                  already read with the same stream.
+-
+-File Attributes
+-
+-* Attribute Meanings::          The names of the file attributes,
+-                                 and what their values mean.
+-* Reading Attributes::          How to read the attributes of a file.
+-* Testing File Type::           Distinguishing ordinary files,
+-                                 directories, links...
+-* File Owner::                  How ownership for new files is determined,
+-                                 and how to change it.
+-* Permission Bits::             How information about a file's access mode
+-                                 is stored.
+-* Access Permission::           How the system decides who can access a file.
+-* Setting Permissions::         How permissions for new files are assigned,
+-                                 and how to change them.
+-* Testing File Access::         How to find out if your process can
+-                                 access a file.
+-* File Times::                  About the time attributes of a file.
+-
+-Pipes and FIFOs
+-
+-* Creating a Pipe::             Making a pipe with the `pipe' function.
+-* Pipe to a Subprocess::        Using a pipe to communicate with a child.
+-* FIFO Special Files::          Making a FIFO special file.
+-
+-Sockets
+-
+-* Socket Concepts::             Basic concepts you need to know about.
+-* Communication Styles::        Stream communication, datagrams, and others.
+-* Socket Addresses::            How socket names ("addresses") work.
+-* File Namespace::              Details about the file namespace.
+-* Internet Namespace::          Details about the Internet namespace.
+-* Open/Close Sockets::          Creating sockets and destroying them.
+-* Connections::                 Operations on sockets with connection state.
+-* Datagrams::                   Operations on datagram sockets.
+-* Socket Options::              Miscellaneous low-level socket options.
+-* Networks Database::           Accessing the database of network names.
+-
+-Socket Addresses
+-
+-* Address Formats::             About `struct sockaddr'.
+-* Setting Address::             Binding an address to a socket.
+-* Reading Address::             Reading the address of a socket.
+-
+-Internet Domain
+-
+-* Internet Address Format::     How socket addresses are specified in the
+-                                 Internet namespace.
+-* Host Addresses::              All about host addresses of Internet hosts.
+-* Protocols Database::          Referring to protocols by name.
+-* Services Database::           Ports may have symbolic names.
+-* Byte Order::                  Different hosts may use different byte
+-                                 ordering conventions; you need to
+-                                 canonicalize host address and port number.
+-* Inet Example::                Putting it all together.
+-
+-Host Addresses
+-
+-* Abstract Host Addresses::             What a host number consists of.
+-* Data type: Host Address Data Type.    Data type for a host number.
+-* Functions: Host Address Functions.    Functions to operate on them.
+-* Names: Host Names.                    Translating host names to host 
numbers.
+-
+-Open/Close Sockets
+-
+-* Creating a Socket::           How to open a socket.
+-* Closing a Socket::            How to close a socket.
+-* Socket Pairs::                These are created like pipes.
+-
+-Connections
+-
+-* Connecting::                  What the client program must do.
+-* Listening::                   How a server program waits for requests.
+-* Accepting Connections::       What the server does when it gets a request.
+-* Who is Connected::            Getting the address of the
+-                                 other side of a connection.
+-* Transferring Data::           How to send and receive data.
+-* Byte Stream Example::         An example client for communicating over a
+-                                 byte stream socket in the Internet namespace.
+-* Server Example::              A corresponding server program.
+-* Out-of-Band Data::            This is an advanced feature.
+-
+-Transferring Data
+-
+-* Sending Data::                Sending data with `write'.
+-* Receiving Data::              Reading data with `read'.
+-* Socket Data Options::         Using `send' and `recv'.
+-
+-Datagrams
+-
+-* Sending Datagrams::           Sending packets on a datagram socket.
+-* Receiving Datagrams::         Receiving packets on a datagram socket.
+-* Datagram Example::            An example program: packets sent over a
+-                                 datagram stream in the file namespace.
+-* Example Receiver::            Another program, that receives those packets.
+-
+-Socket Options
+-
+-* Socket Option Functions::     The basic functions for setting and getting
+-                                 socket options.
+-* Socket-Level Options::        Details of the options at the socket level.
+-
+-Low-Level Terminal Interface
+-
+-* Is It a Terminal::            How to determine if a file is a terminal
+-                                 device, and what its name is.
+-* I/O Queues::                  About flow control and typeahead.
+-* Canonical or Not::            Two basic styles of input processing.
+-* Terminal Modes::              How to examine and modify flags controlling
+-                                 terminal I/O: echoing, signals, editing.
+-* Line Control::                Sending break sequences, clearing  buffers...
+-* Noncanon Example::            How to read single characters without echo.
+-
+-Terminal Modes
+-
+-* Mode Data Types::             The data type `struct termios' and related 
types.
+-* Mode Functions::              Functions to read and set terminal attributes.
+-* Setting Modes::               The right way to set attributes reliably.
+-* Input Modes::                 Flags controlling low-level input handling.
+-* Output Modes::                Flags controlling low-level output handling.
+-* Control Modes::               Flags controlling serial port behavior.
+-* Local Modes::                 Flags controlling high-level input handling.
+-* Line Speed::                  How to read and set the terminal line speed.
+-* Special Characters::          Characters that have special effects,
+-                                 and how to change them.
+-* Noncanonical Input::          Controlling how long to wait for input.
+-
+-Special Characters
+-
+-* Editing Characters::
+-* Signal Characters::
+-* Start/Stop Characters::
+-
+-Mathematics
+-
+-* Domain and Range Errors::     How overflow conditions and the
+-                                 like are reported.
+-* Not a Number::                Making NANs and testing for NANs.
+-* Trig Functions::              Sine, cosine, and tangent.
+-* Inverse Trig Functions::      Arc sine, arc cosine, and arc tangent.
+-* Exponents and Logarithms::    Also includes square root.
+-* Hyperbolic Functions::        Hyperbolic sine and friends.
+-* Pseudo-Random Numbers::       Functions for generating pseudo-random 
numbers.
+-* Absolute Value::              Absolute value functions.
+-
+-Pseudo-Random Numbers
+-
+-* ISO Random::                  `rand' and friends.
+-* BSD Random::                  `random' and friends.
+-
+-Low-Level Arithmetic Functions
+-
+-* Normalization Functions::     Hacks for radix-2 representations.
+-* Rounding and Remainders::     Determining the integer and
+-                                 fractional parts of a float.
+-* Integer Division::            Functions for performing integer division.
+-* Parsing of Numbers::          Functions for "reading" numbers from strings.
+-* Predicates on Floats::        Some miscellaneous test functions.
+-
+-Parsing of Numbers
+-
+-* Parsing of Integers::         Functions for conversion of integer values.
+-* Parsing of Floats::           Functions for conversion of floating-point.
+-
+-Date and Time
+-
+-* Processor Time::              Measures processor time used by a program.
+-* Calendar Time::               Manipulation of "real" dates and times.
+-* Setting an Alarm::            Sending a signal after a specified time.
+-* Sleeping::                    Waiting for a period of time.
+-
+-Processor Time
+-
+-* Basic CPU Time::              The `clock' function.
+-* Detailed CPU Time::           The `times' function.
+-
+-Calendar Time
+-
+-* Simple Calendar Time::        Facilities for manipulating calendar time.
+-* High-Resolution Calendar::    A time representation with greater precision.
+-* Broken-down Time::            Facilities for manipulating local time.
+-* Formatting Date and Time::    Converting times to strings.
+-* TZ Variable::                 How users specify the time zone.
+-* Time Zone Functions::         Functions to examine or specify the time zone.
+-* Time Functions Example::      An example program showing use of some of
+-                                 the time functions.
+-
+-Signal Handling
+-
+-* Concepts of Signals::         Introduction to the signal facilities.
+-* Standard Signals::            Particular kinds of signals with standard
+-                                 names and meanings.
+-* Signal Actions::              Specifying what happens when a particular
+-                                 signal is delivered.
+-* Defining Handlers::           How to write a signal handler function.
+-* Generating Signals::          How to send a signal to a process.
+-* Blocking Signals::            Making the system hold signals temporarily.
+-* Waiting for a Signal::        Suspending your program until a signal 
arrives.
+-* Signal Stack::                Using a Separate Signal Stack
+-* BSD Signal Handling::         Additional functions for backward
+-                                 compatibility with BSD.
+-
+-Basic Concepts of Signals
+-
+-* Kinds of Signals::            Some examples of what can cause a signal.
+-* Signal Generation::           Concepts of why and how signals occur.
+-* Delivery of Signal::          Concepts of what a signal does to the process.
+-
+-Standard Signals
+-
+-* Program Error Signals::       Used to report serious program errors.
+-* Termination Signals::         Used to interrupt and/or terminate the 
program.
+-* Alarm Signals::               Used to indicate expiration of timers.
+-* Asynchronous I/O Signals::    Used to indicate input is available.
+-* Job Control Signals::         Signals used to support job control.
+-* Operation Error Signals::     Used to report operational system errors.
+-* Miscellaneous Signals::       Miscellaneous Signals.
+-* Signal Messages::             Printing a message describing a signal.
+-
+-Specifying Signal Actions
+-
+-* Basic Signal Handling::       The simple `signal' function.
+-* Advanced Signal Handling::    The more powerful `sigaction' function.
+-* Signal and Sigaction::        How those two functions interact.
+-* Sigaction Function Example::  An example of using the sigaction function.
+-* Flags for Sigaction::         Specifying options for signal handling.
+-* Initial Signal Actions::      How programs inherit signal actions.
+-
+-Defining Signal Handlers
+-
+-* Handler Returns::
+-* Termination in Handler::
+-* Longjmp in Handler::
+-* Signals in Handler::
+-* Nonreentrancy::
+-* Atomic Data Access::
+-
+-Generating Signals
+-
+-* Signaling Yourself::          Signaling Yourself
+-* Signaling Another Process::   Send a signal to another process.
+-* Permission for kill::         Permission for using `kill'
+-* Kill Example::                Using `kill' for Communication
+-
+-Blocking Signals
+-
+-* Why Block::                   The purpose of blocking signals.
+-* Signal Sets::                 How to specify which signals to block.
+-* Process Signal Mask::         Blocking delivery of signals to your
+-                                 process during normal execution.
+-* Testing for Delivery::        Blocking to Test for Delivery of a Signal
+-* Blocking for Handler::        Blocking additional signals while a
+-                                 handler is being run.
+-* Checking for Pending Signals::Checking for Pending Signals
+-* Remembering a Signal::        How you can get almost the same effect
+-                                 as blocking a signal, by handling it
+-                                 and setting a flag to be tested later.
+-
+-Waiting for a Signal
+-
+-* Using Pause::                 The simple way, using `pause'.
+-* Pause Problems::              Why the simple way is often not very good.
+-* Sigsuspend::                  Reliably waiting for a specific signal.
+-
+-BSD Signal Handling
+-
+-* BSD Handler::                 BSD Function to Establish a Handler.
+-* Blocking in BSD::             BSD Functions for Blocking Signals
+-
+-Process Startup and Termination
+-
+-* Program Arguments::           Parsing your program's command-line arguments.
+-* Environment Variables::       How to access parameters inherited from
+-                                 a parent process.
+-* Program Termination::         How to cause a process to terminate and
+-                                 return status information to its parent.
+-
+-Program Arguments
+-
+-* Argument Syntax::             By convention, options start with a hyphen.
+-* Parsing Options::             The `getopt' function.
+-* Example of Getopt::           An example of parsing options with `getopt'.
+-* Long Options::                GNU utilities should accept long-named 
options.
+-                                 Here is how to do that.
+-* Long Option Example::         An example of using `getopt_long'.
+-
+-Environment Variables
+-
+-* Environment Access::          How to get and set the values of
+-                                 environment variables.
+-* Standard Environment::        These environment variables have
+-                                 standard interpretations.
+-
+-Program Termination
+-
+-* Normal Termination::          If a program calls `exit', a
+-                                 process terminates normally.
+-* Exit Status::                 The `exit status' provides information
+-                                 about why the process terminated.
+-* Cleanups on Exit::            A process can run its own cleanup
+-                                 functions upon normal termination.
+-* Aborting a Program::          The `abort' function causes
+-                                 abnormal program termination.
+-* Termination Internals::       What happens when a process terminates.
+-
+-
+-Child Processes
+-
+-* Running a Command::           The easy way to run another program.
+-* Process Creation Concepts::   An overview of the hard way to do it.
+-* Process Identification::      How to get the process ID of a process.
+-* Creating a Process::          How to fork a child process.
+-* Executing a File::            How to make a child execute another program.
+-* Process Completion::          How to tell when a child process has 
completed.
+-* Process Completion Status::   How to interpret the status value
+-                                 returned from a child process.
+-* BSD Wait Functions::          More functions, for backward compatibility.
+-* Process Creation Example::    A complete example program.
+-
+-Job Control
+-
+-* Concepts of Job Control ::    Concepts of Job Control
+-* Job Control is Optional::     Not all POSIX systems support job control.
+-* Controlling Terminal::        How a process gets its controlling terminal.
+-* Access to the Terminal::      How processes share the controlling terminal.
+-* Orphaned Process Groups::     Jobs left after the user logs out.
+-* Implementing a Shell::        What a shell must do to implement job control.
+-* Functions for Job Control::   Functions to control process groups.
+-
+-Implementing a Job Control Shell
+-
+-* Data Structures::             Introduction to the sample shell.
+-* Initializing the Shell::      What the shell must do to take
+-                                 responsibility for job control.
+-* Launching Jobs::              Creating jobs to execute commands.
+-* Foreground and Background::   Putting a job in foreground of background.
+-* Stopped and Terminated Jobs:: Reporting job status.
+-* Continuing Stopped Jobs::     How to continue a stopped job in
+-                                 the foreground or background.
+-* Missing Pieces::              Other parts of the shell.
+-
+-Functions for Job Control
+-
+-* Identifying the Terminal::    Determining the controlling terminal's name.
+-* Process Group Functions::     Functions for manipulating process groups.
+-* Terminal Access Functions::   Functions for controlling terminal access.
+-
+-Name Service Switch
+-
+-* NSS Basics::                  What is this NSS good for.
+-* NSS Configuration File::      Configuring NSS.
+-* NSS Module Internals::        How does it work internally.
+-* Extending NSS::               What to do to add services or databases.
+-
+-Users and Groups
+-
+-* User and Group IDs::          Each user and group has a unique numeric ID.
+-* Process Persona::             The user IDs and group IDs of a process.
+-* Why Change Persona::          Why a program might need to change
+-                                 its user and/or group IDs.
+-* How Change Persona::          Restrictions on changing user and group IDs.
+-* Reading Persona::             Examining the process's user and group IDs.
+-* Setting User ID::
+-* Setting Groups::
+-* Enable/Disable Setuid::
+-* Setuid Program Example::      Setuid Program Example
+-* Tips for Setuid::
+-* Who Logged In::               Getting the name of the user who logged in,
+-                                 or of the real user ID of the current 
process.
+-
+-* User Database::               Functions and data structures for
+-                                 accessing the user database.
+-* Group Database::              Functions and data structures for
+-                                 accessing the group database.
+-* Database Example::            Example program showing use of database
+-                                 inquiry functions.
+-
+-User Database
+-
+-* User Data Structure::
+-* Lookup User::
+-* Scanning All Users::          Scanning the List of All Users
+-* Writing a User Entry::
+-
+-Group Database
+-
+-* Group Data Structure::
+-* Lookup Group::
+-* Scanning All Groups::         Scanning the List of All Groups
+-
+-System Information
+-
+-* Host Identification::         Determining the name of the machine.
+-* Hardware/Software Type ID::   Determining the hardware type and
+-                                 operating system type.
+-
+-System Configuration Limits
+-
+-* General Limits::            Constants and functions that describe
+-                               various process-related limits that have
+-                               one uniform value for any given machine.
+-* System Options::            Optional POSIX features.
+-* Version Supported::         Version numbers of POSIX.1 and POSIX.2.
+-* Sysconf::                   Getting specific configuration values
+-                               of general limits and system options.
+-* Minimums::                  Minimum values for general limits.
+-
+-* Limits for Files::          Size limitations on individual files.
+-                               These can vary between file systems
+-                                or even from file to file.
+-* Options for Files::         Optional features that some files may support.
+-* File Minimums::             Minimum values for file limits.
+-* Pathconf::                  Getting the limit values for a particular file.
+-
+-* Utility Limits::            Capacity limits of POSIX.2 utility programs.
+-* Utility Minimums::          Minimum allowable values of those limits.
+-
+-* String Parameters::         Getting the default search path.
+-
+-Library Facilities that are Part of the C Language
+-
+-* Consistency Checking::        Using `assert' to abort
+-                               if something "impossible" happens.
+-* Variadic Functions::          Defining functions with varying
+-                                 numbers of arguments.
+-* Null Pointer Constant::       The macro `NULL'.
+-* Important Data Types::        Data types for object sizes.
+-* Data Type Measurements::      Parameters of data type representations.
+-
+-Variadic Functions
+-
+-* Why Variadic::                Reasons for making functions take
+-                                 variable arguments.
+-* How Variadic::                How to define and call variadic functions.
+-* Argument Macros::             Detailed specification of the macros
+-                               for accessing variable arguments.
+-* Variadic Example::            A complete example.
+-
+-How Variadic Functions are Defined and Used
+-
+-* Variadic Prototypes::         How to make a prototype for a function
+-                               with variable arguments.
+-* Receiving Arguments::               Steps you must follow to access the
+-                               optional argument values.
+-* How Many Arguments::          How to decide whether there are more 
arguments.
+-* Calling Variadics::         Things you need to know about calling
+-                               variable arguments functions.
+-
+-Data Type Measurements
+-
+-* Width of Type::             How many bits does an integer type hold?
+-* Range of Type::             What are the largest and smallest values
+-                               that an integer type can hold?
+-* Floating Type Macros::        Parameters that measure floating-point types.
+-* Structure Measurement::       Getting measurements on structure types.
+-
+-Floating Type Macros
+-
+-* Floating Point Concepts::     Definitions of terminology.
+-* Floating Point Parameters::   Dimensions, limits of floating point types.
+-* IEEE Floating Point::         How one common representation is described.
+-
+-Library Maintenance
+-
+-* Installation::                How to configure, compile and install
+-                                 the GNU C library.
+-* Reporting Bugs::              How to report bugs (if you want to
+-                                 get them fixed) and other troubles
+-                                 you may have with the GNU C library.
+-* Porting::                     How to port the GNU C library to
+-                                 a new machine or operating system.
+-* Contributors::              Who wrote what parts of the GNU C Library.
+-
+-Porting the GNU C Library
+-
+-* Hierarchy Conventions::       How the `sysdeps' hierarchy is
+-                                 layed out.
+-* Porting to Unix::             Porting the library to an average
+-                                 Unix-like system.
+-
+-
+-File: libc.info,  Node: Introduction,  Next: Error Reporting,  Prev: Top,  
Up: Top
+-
+-Introduction
+-************
+-
+-   The C language provides no built-in facilities for performing such
+-common operations as input/output, memory management, string
+-manipulation, and the like.  Instead, these facilities are defined in a
+-standard "library", which you compile and link with your programs.
+-
+-   The GNU C library, described in this document, defines all of the
+-library functions that are specified by the ISO C standard, as well as
+-additional features specific to POSIX and other derivatives of the Unix
+-operating system, and extensions specific to the GNU system.
+-
+-   The purpose of this manual is to tell you how to use the facilities
+-of the GNU library.  We have mentioned which features belong to which
+-standards to help you identify things that are potentially nonportable
+-to other systems.  But the emphasis in this manual is not on strict
+-portability.
+-
+-* Menu:
+-
+-* Getting Started::             What this manual is for and how to use it.
+-* Standards and Portability::   Standards and sources upon which the GNU
+-                                 C library is based.
+-* Using the Library::           Some practical uses for the library.
+-* Roadmap to the Manual::       Overview of the remaining chapters in
+-                                 this manual.
+-
+-
+-File: libc.info,  Node: Getting Started,  Next: Standards and Portability,  
Up: Introduction
+-
+-Getting Started
+-===============
+-
+-   This manual is written with the assumption that you are at least
+-somewhat familiar with the C programming language and basic programming
+-concepts.  Specifically, familiarity with ISO standard C (*note ISO
+-C::.), rather than "traditional" pre-ISO C dialects, is assumed.
+-
+-   The GNU C library includes several "header files", each of which
+-provides definitions and declarations for a group of related facilities;
+-this information is used by the C compiler when processing your program.
+-For example, the header file `stdio.h' declares facilities for
+-performing input and output, and the header file `string.h' declares
+-string processing utilities.  The organization of this manual generally
+-follows the same division as the header files.
+-
+-   If you are reading this manual for the first time, you should read
+-all of the introductory material and skim the remaining chapters.
+-There are a *lot* of functions in the GNU C library and it's not
+-realistic to expect that you will be able to remember exactly *how* to
+-use each and every one of them.  It's more important to become
+-generally familiar with the kinds of facilities that the library
+-provides, so that when you are writing your programs you can recognize
+-*when* to make use of library functions, and *where* in this manual you
+-can find more specific information about them.
+-
+-
+-File: libc.info,  Node: Standards and Portability,  Next: Using the Library,  
Prev: Getting Started,  Up: Introduction
+-
+-Standards and Portability
+-=========================
+-
+-   This section discusses the various standards and other sources that
+-the GNU C library is based upon.  These sources include the ISO C and
+-POSIX standards, and the System V and Berkeley Unix implementations.
+-
+-   The primary focus of this manual is to tell you how to make effective
+-use of the GNU library facilities.  But if you are concerned about
+-making your programs compatible with these standards, or portable to
+-operating systems other than GNU, this can affect how you use the
+-library.  This section gives you an overview of these standards, so that
+-you will know what they are when they are mentioned in other parts of
+-the manual.
+-
+-   *Note Library Summary::, for an alphabetical list of the functions
+-and other symbols provided by the library.  This list also states which
+-standards each function or symbol comes from.
+-
+-* Menu:
+-
+-* ISO C::                      The international standard for the C
+-                                 programming language.
+-* POSIX::                       The ISO/IEC 9945 (aka IEEE 1003) standards
+-                                 for operating systems.
+-* Berkeley Unix::               BSD and SunOS.
+-* SVID::                        The System V Interface Description.
+-
+-
+-File: libc.info,  Node: ISO C,  Next: POSIX,  Up: Standards and Portability
+-
+-ISO C
+------
+-
+-   The GNU C library is compatible with the C standard adopted by the
+-American National Standards Institute (ANSI): `American National
+-Standard X3.159-1989--"ANSI C"' and later by the International
+-Standardization Organization (ISO): `ISO/IEC 9899:1990, "Programming
+-languages--C"'.  We here refer to the standard as ISO C since this is
+-the more general standard in respect of ratification.  The header files
+-and library facilities that make up the GNU library are a superset of
+-those specified by the ISO C standard.
+-
+-   If you are concerned about strict adherence to the ISO C standard,
+-you should use the `-ansi' option when you compile your programs with
+-the GNU C compiler.  This tells the compiler to define *only* ISO
+-standard features from the library header files, unless you explicitly
+-ask for additional features.  *Note Feature Test Macros::, for
+-information on how to do this.
+-
+-   Being able to restrict the library to include only ISO C features is
+-important because ISO C puts limitations on what names can be defined
+-by the library implementation, and the GNU extensions don't fit these
+-limitations.  *Note Reserved Names::, for more information about these
+-restrictions.
+-
+-   This manual does not attempt to give you complete details on the
+-differences between ISO C and older dialects.  It gives advice on how
+-to write programs to work portably under multiple C dialects, but does
+-not aim for completeness.
+-
+-
+-File: libc.info,  Node: POSIX,  Next: Berkeley Unix,  Prev: ISO C,  Up: 
Standards and Portability
+-
+-POSIX (The Portable Operating System Interface)
+------------------------------------------------
+-
+-   The GNU library is also compatible with the IEEE "POSIX" family of
+-standards, known more formally as the "Portable Operating System
+-Interface for Computer Environments".  POSIX is derived mostly from
+-various versions of the Unix operating system.
+-
+-   The library facilities specified by the POSIX standards are a
+-superset of those required by ISO C; POSIX specifies additional
+-features for ISO C functions, as well as specifying new additional
+-functions.  In general, the additional requirements and functionality
+-defined by the POSIX standards are aimed at providing lower-level
+-support for a particular kind of operating system environment, rather
+-than general programming language support which can run in many diverse
+-operating system environments.
+-
+-   The GNU C library implements all of the functions specified in `IEEE
+-Std 1003.1-1990, the POSIX System Application Program Interface',
+-commonly referred to as POSIX.1.  The primary extensions to the ISO C
+-facilities specified by this standard include file system interface
+-primitives (*note File System Interface::.), device-specific terminal
+-control functions (*note Low-Level Terminal Interface::.), and process
+-control functions (*note Processes::.).
+-
+-   Some facilities from `IEEE Std 1003.2-1992, the POSIX Shell and
+-Utilities standard' (POSIX.2) are also implemented in the GNU library.
+-These include utilities for dealing with regular expressions and other
+-pattern matching facilities (*note Pattern Matching::.).
+-
+-
+-File: libc.info,  Node: Berkeley Unix,  Next: SVID,  Prev: POSIX,  Up: 
Standards and Portability
+-
+-Berkeley Unix
+--------------
+-
+-   The GNU C library defines facilities from some versions of Unix which
+-are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD,
+-and 4.4 BSD Unix systems (also known as "Berkeley Unix") and from
+-"SunOS" (a popular 4.2 BSD derivative that includes some Unix System V
+-functionality).  These systems support most of the ISO C and POSIX
+-facilities, and 4.4 BSD and newer releases of SunOS in fact support
+-them all.
+-
+-   The BSD facilities include symbolic links (*note Symbolic Links::.),
+-the `select' function (*note Waiting for I/O::.), the BSD signal
+-functions (*note BSD Signal Handling::.), and sockets (*note
+-Sockets::.).
+-
+-
+-File: libc.info,  Node: SVID,  Prev: Berkeley Unix,  Up: Standards and 
Portability
+-
+-SVID (The System V Interface Description)
+------------------------------------------
+-
+-   The "System V Interface Description" (SVID) is a document describing
+-the AT&T Unix System V operating system.  It is to some extent a
+-superset of the POSIX standard (*note POSIX::.).
+-
+-   The GNU C library defines some of the facilities required by the SVID
+-that are not also required by the ISO C or POSIX standards, for
+-compatibility with  System V Unix and other Unix systems (such as
+-SunOS) which include these facilities.  However, many of the more
+-obscure and less generally useful facilities required by the SVID are
+-not included.  (In fact, Unix System V itself does not provide them
+-all.)
+-
+-
+-File: libc.info,  Node: Using the Library,  Next: Roadmap to the Manual,  
Prev: Standards and Portability,  Up: Introduction
+-
+-Using the Library
+-=================
+-
+-   This section describes some of the practical issues involved in using
+-the GNU C library.
+-
+-* Menu:
+-
+-* Header Files::                How to include the header files in your
+-                                 programs.
+-* Macro Definitions::           Some functions in the library may really
+-                                 be implemented as macros.
+-* Reserved Names::              The C standard reserves some names for
+-                                 the library, and some for users.
+-* Feature Test Macros::         How to control what names are defined.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-10 
glibc-2.0.1/manual/libc.info-10
+--- ../glibc-2.0.1/manual/libc.info-10 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-10    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1251 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Operating Modes,  Next: Getting File Status Flags,  
Prev: Open-time Flags,  Up: File Status Flags
+-
+-I/O Operating Modes
+--------------------
+-
+-   The operating modes affect how input and output operations using a
+-file descriptor work.  These flags are set by `open' and can be fetched
+-and changed with `fcntl'.
+-
+- - Macro: int O_APPEND
+-     The bit that enables append mode for the file.  If set, then all
+-     `write' operations write the data at the end of the file, extending
+-     it, regardless of the current file position.  This is the only
+-     reliable way to append to a file.  In append mode, you are
+-     guaranteed that the data you write will always go to the current
+-     end of the file, regardless of other processes writing to the
+-     file.  Conversely, if you simply set the file position to the end
+-     of file and write, then another process can extend the file after
+-     you set the file position but before you write, resulting in your
+-     data appearing someplace before the real end of file.
+-
+- - Macro: int O_NONBLOCK
+-     The bit that enables nonblocking mode for the file.  If this bit
+-     is set, `read' requests on the file can return immediately with a
+-     failure status if there is no input immediately available, instead
+-     of blocking.  Likewise, `write' requests can also return
+-     immediately with a failure status if the output can't be written
+-     immediately.
+-
+-     Note that the `O_NONBLOCK' flag is overloaded as both an I/O
+-     operating mode and a file name translation flag; *note Open-time
+-     Flags::..
+-
+- - Macro: int O_NDELAY
+-     This is an obsolete name for `O_NONBLOCK', provided for
+-     compatibility with BSD.  It is not defined by the POSIX.1 standard.
+-
+-   The remaining operating modes are BSD and GNU extensions.  They
+-exist only on some systems.  On other systems, these macros are not
+-defined.
+-
+- - Macro: int O_ASYNC
+-     The bit that enables asynchronous input mode.  If set, then `SIGIO'
+-     signals will be generated when input is available.  *Note
+-     Interrupt Input::.
+-
+-     Asynchronous input mode is a BSD feature.
+-
+- - Macro: int O_FSYNC
+-     The bit that enables synchronous writing for the file.  If set,
+-     each `write' call will make sure the data is reliably stored on
+-     disk before returning.  Synchronous writing is a BSD feature.
+-
+- - Macro: int O_SYNC
+-     This is another name for `O_FSYNC'.  They have the same value.
+-
+- - Macro: int O_NOATIME
+-     If this bit is set, `read' will not update the access time of the
+-     file.  *Note File Times::.  This is used by programs that do
+-     backups, so that backing a file up does not count as reading it.
+-     Only the owner of the file or the superuser may use this bit.
+-
+-     This is a GNU extension.
+-
+-
+-File: libc.info,  Node: Getting File Status Flags,  Prev: Operating Modes,  
Up: File Status Flags
+-
+-Getting and Setting File Status Flags
+--------------------------------------
+-
+-   The `fcntl' function can fetch or change file status flags.
+-
+- - Macro: int F_GETFL
+-     This macro is used as the COMMAND argument to `fcntl', to read the
+-     file status flags for the open file with descriptor FILEDES.
+-
+-     The normal return value from `fcntl' with this command is a
+-     nonnegative number which can be interpreted as the bitwise OR of
+-     the individual flags.  Since the file access modes are not
+-     single-bit values, you can mask off other bits in the returned
+-     flags with `O_ACCMODE' to compare them.
+-
+-     In case of an error, `fcntl' returns `-1'.  The following `errno'
+-     error conditions are defined for this command:
+-
+-    `EBADF'
+-          The FILEDES argument is invalid.
+-
+- - Macro: int F_SETFL
+-     This macro is used as the COMMAND argument to `fcntl', to set the
+-     file status flags for the open file corresponding to the FILEDES
+-     argument.  This command requires a third `int' argument to specify
+-     the new flags, so the call looks like this:
+-
+-          fcntl (FILEDES, F_SETFL, NEW-FLAGS)
+-
+-     You can't change the access mode for the file in this way; that is,
+-     whether the file descriptor was opened for reading or writing.
+-
+-     The normal return value from `fcntl' with this command is an
+-     unspecified value other than `-1', which indicates an error.  The
+-     error conditions are the same as for the `F_GETFL' command.
+-
+-   If you want to modify the file status flags, you should get the
+-current flags with `F_GETFL' and modify the value.  Don't assume that
+-the flags listed here are the only ones that are implemented; your
+-program may be run years from now and more flags may exist then.  For
+-example, here is a function to set or clear the flag `O_NONBLOCK'
+-without altering any other flags:
+-
+-     /* Set the `O_NONBLOCK' flag of DESC if VALUE is nonzero,
+-        or clear the flag if VALUE is 0.
+-        Return 0 on success, or -1 on error with `errno' set. */
+-     
+-     int
+-     set_nonblock_flag (int desc, int value)
+-     {
+-       int oldflags = fcntl (desc, F_GETFL, 0);
+-       /* If reading the flags failed, return error indication now. */
+-       if (oldflags == -1)
+-         return -1;
+-       /* Set just the flag we want to set. */
+-       if (value != 0)
+-         oldflags |= O_NONBLOCK;
+-       else
+-         oldflags &= ~O_NONBLOCK;
+-       /* Store modified flag word in the descriptor. */
+-       return fcntl (desc, F_SETFL, oldflags);
+-     }
+-
+-
+-File: libc.info,  Node: File Locks,  Next: Interrupt Input,  Prev: File 
Status Flags,  Up: Low-Level I/O
+-
+-File Locks
+-==========
+-
+-   The remaining `fcntl' commands are used to support "record locking",
+-which permits multiple cooperating programs to prevent each other from
+-simultaneously accessing parts of a file in error-prone ways.
+-
+-   An "exclusive" or "write" lock gives a process exclusive access for
+-writing to the specified part of the file.  While a write lock is in
+-place, no other process can lock that part of the file.
+-
+-   A "shared" or "read" lock prohibits any other process from
+-requesting a write lock on the specified part of the file.  However,
+-other processes can request read locks.
+-
+-   The `read' and `write' functions do not actually check to see
+-whether there are any locks in place.  If you want to implement a
+-locking protocol for a file shared by multiple processes, your
+-application must do explicit `fcntl' calls to request and clear locks
+-at the appropriate points.
+-
+-   Locks are associated with processes.  A process can only have one
+-kind of lock set for each byte of a given file.  When any file
+-descriptor for that file is closed by the process, all of the locks
+-that process holds on that file are released, even if the locks were
+-made using other descriptors that remain open.  Likewise, locks are
+-released when a process exits, and are not inherited by child processes
+-created using `fork' (*note Creating a Process::.).
+-
+-   When making a lock, use a `struct flock' to specify what kind of
+-lock and where.  This data type and the associated macros for the
+-`fcntl' function are declared in the header file `fcntl.h'.
+-
+- - Data Type: struct flock
+-     This structure is used with the `fcntl' function to describe a file
+-     lock.  It has these members:
+-
+-    `short int l_type'
+-          Specifies the type of the lock; one of `F_RDLCK', `F_WRLCK',
+-          or `F_UNLCK'.
+-
+-    `short int l_whence'
+-          This corresponds to the WHENCE argument to `fseek' or
+-          `lseek', and specifies what the offset is relative to.  Its
+-          value can be one of `SEEK_SET', `SEEK_CUR', or `SEEK_END'.
+-
+-    `off_t l_start'
+-          This specifies the offset of the start of the region to which
+-          the lock applies, and is given in bytes relative to the point
+-          specified by `l_whence' member.
+-
+-    `off_t l_len'
+-          This specifies the length of the region to be locked.  A
+-          value of `0' is treated specially; it means the region
+-          extends to the end of the file.
+-
+-    `pid_t l_pid'
+-          This field is the process ID (*note Process Creation
+-          Concepts::.) of the process holding the lock.  It is filled
+-          in by calling `fcntl' with the `F_GETLK' command, but is
+-          ignored when making a lock.
+-
+- - Macro: int F_GETLK
+-     This macro is used as the COMMAND argument to `fcntl', to specify
+-     that it should get information about a lock.  This command
+-     requires a third argument of type `struct flock *' to be passed to
+-     `fcntl', so that the form of the call is:
+-
+-          fcntl (FILEDES, F_GETLK, LOCKP)
+-
+-     If there is a lock already in place that would block the lock
+-     described by the LOCKP argument, information about that lock
+-     overwrites `*LOCKP'.  Existing locks are not reported if they are
+-     compatible with making a new lock as specified.  Thus, you should
+-     specify a lock type of `F_WRLCK' if you want to find out about both
+-     read and write locks, or `F_RDLCK' if you want to find out about
+-     write locks only.
+-
+-     There might be more than one lock affecting the region specified
+-     by the LOCKP argument, but `fcntl' only returns information about
+-     one of them.  The `l_whence' member of the LOCKP structure is set
+-     to `SEEK_SET' and the `l_start' and `l_len' fields set to identify
+-     the locked region.
+-
+-     If no lock applies, the only change to the LOCKP structure is to
+-     update the `l_type' to a value of `F_UNLCK'.
+-
+-     The normal return value from `fcntl' with this command is an
+-     unspecified value other than `-1', which is reserved to indicate an
+-     error.  The following `errno' error conditions are defined for
+-     this command:
+-
+-    `EBADF'
+-          The FILEDES argument is invalid.
+-
+-    `EINVAL'
+-          Either the LOCKP argument doesn't specify valid lock
+-          information, or the file associated with FILEDES doesn't
+-          support locks.
+-
+- - Macro: int F_SETLK
+-     This macro is used as the COMMAND argument to `fcntl', to specify
+-     that it should set or clear a lock.  This command requires a third
+-     argument of type `struct flock *' to be passed to `fcntl', so that
+-     the form of the call is:
+-
+-          fcntl (FILEDES, F_SETLK, LOCKP)
+-
+-     If the process already has a lock on any part of the region, the
+-     old lock on that part is replaced with the new lock.  You can
+-     remove a lock by specifying a lock type of `F_UNLCK'.
+-
+-     If the lock cannot be set, `fcntl' returns immediately with a value
+-     of `-1'.  This function does not block waiting for other processes
+-     to release locks.  If `fcntl' succeeds, it return a value other
+-     than `-1'.
+-
+-     The following `errno' error conditions are defined for this
+-     function:
+-
+-    `EAGAIN'
+-    `EACCES'
+-          The lock cannot be set because it is blocked by an existing
+-          lock on the file.  Some systems use `EAGAIN' in this case,
+-          and other systems use `EACCES'; your program should treat
+-          them alike, after `F_SETLK'.  (The GNU system always uses
+-          `EAGAIN'.)
+-
+-    `EBADF'
+-          Either: the FILEDES argument is invalid; you requested a read
+-          lock but the FILEDES is not open for read access; or, you
+-          requested a write lock but the FILEDES is not open for write
+-          access.
+-
+-    `EINVAL'
+-          Either the LOCKP argument doesn't specify valid lock
+-          information, or the file associated with FILEDES doesn't
+-          support locks.
+-
+-    `ENOLCK'
+-          The system has run out of file lock resources; there are
+-          already too many file locks in place.
+-
+-          Well-designed file systems never report this error, because
+-          they have no limitation on the number of locks.  However, you
+-          must still take account of the possibility of this error, as
+-          it could result from network access to a file system on
+-          another machine.
+-
+- - Macro: int F_SETLKW
+-     This macro is used as the COMMAND argument to `fcntl', to specify
+-     that it should set or clear a lock.  It is just like the `F_SETLK'
+-     command, but causes the process to block (or wait) until the
+-     request can be specified.
+-
+-     This command requires a third argument of type `struct flock *', as
+-     for the `F_SETLK' command.
+-
+-     The `fcntl' return values and errors are the same as for the
+-     `F_SETLK' command, but these additional `errno' error conditions
+-     are defined for this command:
+-
+-    `EINTR'
+-          The function was interrupted by a signal while it was waiting.
+-          *Note Interrupted Primitives::.
+-
+-    `EDEADLK'
+-          The specified region is being locked by another process.  But
+-          that process is waiting to lock a region which the current
+-          process has locked, so waiting for the lock would result in
+-          deadlock.  The system does not guarantee that it will detect
+-          all such conditions, but it lets you know if it notices one.
+-
+-   The following macros are defined for use as values for the `l_type'
+-member of the `flock' structure.  The values are integer constants.
+-
+-`F_RDLCK'
+-     This macro is used to specify a read (or shared) lock.
+-
+-`F_WRLCK'
+-     This macro is used to specify a write (or exclusive) lock.
+-
+-`F_UNLCK'
+-     This macro is used to specify that the region is unlocked.
+-
+-   As an example of a situation where file locking is useful, consider a
+-program that can be run simultaneously by several different users, that
+-logs status information to a common file.  One example of such a program
+-might be a game that uses a file to keep track of high scores.  Another
+-example might be a program that records usage or accounting information
+-for billing purposes.
+-
+-   Having multiple copies of the program simultaneously writing to the
+-file could cause the contents of the file to become mixed up.  But you
+-can prevent this kind of problem by setting a write lock on the file
+-before actually writing to the file.
+-
+-   If the program also needs to read the file and wants to make sure
+-that the contents of the file are in a consistent state, then it can
+-also use a read lock.  While the read lock is set, no other process can
+-lock that part of the file for writing.
+-
+-   Remember that file locks are only a *voluntary* protocol for
+-controlling access to a file.  There is still potential for access to
+-the file by programs that don't use the lock protocol.
+-
+-
+-File: libc.info,  Node: Interrupt Input,  Prev: File Locks,  Up: Low-Level I/O
+-
+-Interrupt-Driven Input
+-======================
+-
+-   If you set the `O_ASYNC' status flag on a file descriptor (*note
+-File Status Flags::.), a `SIGIO' signal is sent whenever input or
+-output becomes possible on that file descriptor.  The process or
+-process group to receive the signal can be selected by using the
+-`F_SETOWN' command to the `fcntl' function.  If the file descriptor is
+-a socket, this also selects the recipient of `SIGURG' signals that are
+-delivered when out-of-band data arrives on that socket; see *Note
+-Out-of-Band Data::.  (`SIGURG' is sent in any situation where `select'
+-would report the socket as having an "exceptional condition".  *Note
+-Waiting for I/O::.)
+-
+-   If the file descriptor corresponds to a terminal device, then `SIGIO'
+-signals are sent to the foreground process group of the terminal.
+-*Note Job Control::.
+-
+-   The symbols in this section are defined in the header file `fcntl.h'.
+-
+- - Macro: int F_GETOWN
+-     This macro is used as the COMMAND argument to `fcntl', to specify
+-     that it should get information about the process or process group
+-     to which `SIGIO' signals are sent.  (For a terminal, this is
+-     actually the foreground process group ID, which you can get using
+-     `tcgetpgrp'; see *Note Terminal Access Functions::.)
+-
+-     The return value is interpreted as a process ID; if negative, its
+-     absolute value is the process group ID.
+-
+-     The following `errno' error condition is defined for this command:
+-
+-    `EBADF'
+-          The FILEDES argument is invalid.
+-
+- - Macro: int F_SETOWN
+-     This macro is used as the COMMAND argument to `fcntl', to specify
+-     that it should set the process or process group to which `SIGIO'
+-     signals are sent.  This command requires a third argument of type
+-     `pid_t' to be passed to `fcntl', so that the form of the call is:
+-
+-          fcntl (FILEDES, F_SETOWN, PID)
+-
+-     The PID argument should be a process ID.  You can also pass a
+-     negative number whose absolute value is a process group ID.
+-
+-     The return value from `fcntl' with this command is `-1' in case of
+-     error and some other value if successful.  The following `errno'
+-     error conditions are defined for this command:
+-
+-    `EBADF'
+-          The FILEDES argument is invalid.
+-
+-    `ESRCH'
+-          There is no process or process group corresponding to PID.
+-
+-
+-File: libc.info,  Node: File System Interface,  Next: Pipes and FIFOs,  Prev: 
Low-Level I/O,  Up: Top
+-
+-File System Interface
+-*********************
+-
+-   This chapter describes the GNU C library's functions for manipulating
+-files.  Unlike the input and output functions described in *Note I/O on
+-Streams:: and *Note Low-Level I/O::, these functions are concerned with
+-operating on the files themselves, rather than on their contents.
+-
+-   Among the facilities described in this chapter are functions for
+-examining or modifying directories, functions for renaming and deleting
+-files, and functions for examining and setting file attributes such as
+-access permissions and modification times.
+-
+-* Menu:
+-
+-* Working Directory::           This is used to resolve relative
+-                               file names.
+-* Accessing Directories::       Finding out what files a directory
+-                               contains.
+-* Hard Links::                  Adding alternate names to a file.
+-* Symbolic Links::              A file that "points to" a file name.
+-* Deleting Files::              How to delete a file, and what that means.
+-* Renaming Files::              Changing a file's name.
+-* Creating Directories::        A system call just for creating a directory.
+-* File Attributes::             Attributes of individual files.
+-* Making Special Files::        How to create special files.
+-* Temporary Files::             Naming and creating temporary files.
+-
+-
+-File: libc.info,  Node: Working Directory,  Next: Accessing Directories,  Up: 
File System Interface
+-
+-Working Directory
+-=================
+-
+-   Each process has associated with it a directory, called its "current
+-working directory" or simply "working directory", that is used in the
+-resolution of relative file names (*note File Name Resolution::.).
+-
+-   When you log in and begin a new session, your working directory is
+-initially set to the home directory associated with your login account
+-in the system user database.  You can find any user's home directory
+-using the `getpwuid' or `getpwnam' functions; see *Note User Database::.
+-
+-   Users can change the working directory using shell commands like
+-`cd'.  The functions described in this section are the primitives used
+-by those commands and by other programs for examining and changing the
+-working directory.
+-
+-   Prototypes for these functions are declared in the header file
+-`unistd.h'.
+-
+- - Function: char * getcwd (char *BUFFER, size_t SIZE)
+-     The `getcwd' function returns an absolute file name representing
+-     the current working directory, storing it in the character array
+-     BUFFER that you provide.  The SIZE argument is how you tell the
+-     system the allocation size of BUFFER.
+-
+-     The GNU library version of this function also permits you to
+-     specify a null pointer for the BUFFER argument.  Then `getcwd'
+-     allocates a buffer automatically, as with `malloc' (*note
+-     Unconstrained Allocation::.).  If the SIZE is greater than zero,
+-     then the buffer is that large; otherwise, the buffer is as large
+-     as necessary to hold the result.
+-
+-     The return value is BUFFER on success and a null pointer on
+-     failure.  The following `errno' error conditions are defined for
+-     this function:
+-
+-    `EINVAL'
+-          The SIZE argument is zero and BUFFER is not a null pointer.
+-
+-    `ERANGE'
+-          The SIZE argument is less than the length of the working
+-          directory name.  You need to allocate a bigger array and try
+-          again.
+-
+-    `EACCES'
+-          Permission to read or search a component of the file name was
+-          denied.
+-
+-   Here is an example showing how you could implement the behavior of
+-GNU's `getcwd (NULL, 0)' using only the standard behavior of `getcwd':
+-
+-     char *
+-     gnu_getcwd ()
+-     {
+-       int size = 100;
+-       char *buffer = (char *) xmalloc (size);
+-     
+-       while (1)
+-         {
+-           char *value = getcwd (buffer, size);
+-           if (value != 0)
+-             return buffer;
+-           size *= 2;
+-           free (buffer);
+-           buffer = (char *) xmalloc (size);
+-         }
+-     }
+-
+-*Note Malloc Examples::, for information about `xmalloc', which is not
+-a library function but is a customary name used in most GNU software.
+-
+- - Function: char * getwd (char *BUFFER)
+-     This is similar to `getcwd', but has no way to specify the size of
+-     the buffer.  The GNU library provides `getwd' only for backwards
+-     compatibility with BSD.
+-
+-     The BUFFER argument should be a pointer to an array at least
+-     `PATH_MAX' bytes long (*note Limits for Files::.).  In the GNU
+-     system there is no limit to the size of a file name, so this is not
+-     necessarily enough space to contain the directory name.  That is
+-     why this function is deprecated.
+-
+- - Function: int chdir (const char *FILENAME)
+-     This function is used to set the process's working directory to
+-     FILENAME.
+-
+-     The normal, successful return value from `chdir' is `0'.  A value
+-     of `-1' is returned to indicate an error.  The `errno' error
+-     conditions defined for this function are the usual file name
+-     syntax errors (*note File Name Errors::.), plus `ENOTDIR' if the
+-     file FILENAME is not a directory.
+-
+-
+-File: libc.info,  Node: Accessing Directories,  Next: Hard Links,  Prev: 
Working Directory,  Up: File System Interface
+-
+-Accessing Directories
+-=====================
+-
+-   The facilities described in this section let you read the contents
+-of a directory file.  This is useful if you want your program to list
+-all the files in a directory, perhaps as part of a menu.
+-
+-   The `opendir' function opens a "directory stream" whose elements are
+-directory entries.  You use the `readdir' function on the directory
+-stream to retrieve these entries, represented as `struct dirent'
+-objects.  The name of the file for each entry is stored in the `d_name'
+-member of this structure.  There are obvious parallels here to the
+-stream facilities for ordinary files, described in *Note I/O on
+-Streams::.
+-
+-* Menu:
+-
+-* Directory Entries::           Format of one directory entry.
+-* Opening a Directory::         How to open a directory stream.
+-* Reading/Closing Directory::   How to read directory entries from the stream.
+-* Simple Directory Lister::     A very simple directory listing program.
+-* Random Access Directory::     Rereading part of the directory
+-                                 already read with the same stream.
+-
+-
+-File: libc.info,  Node: Directory Entries,  Next: Opening a Directory,  Up: 
Accessing Directories
+-
+-Format of a Directory Entry
+----------------------------
+-
+-   This section describes what you find in a single directory entry, as
+-you might obtain it from a directory stream.  All the symbols are
+-declared in the header file `dirent.h'.
+-
+- - Data Type: struct dirent
+-     This is a structure type used to return information about directory
+-     entries.  It contains the following fields:
+-
+-    `char d_name[]'
+-          This is the null-terminated file name component.  This is the
+-          only field you can count on in all POSIX systems.
+-
+-    `ino_t d_fileno'
+-          This is the file serial number.  For BSD compatibility, you
+-          can also refer to this member as `d_ino'.  In the GNU system
+-          and most POSIX systems, for most files this the same as the
+-          `st_ino' member that `stat' will return for the file.  *Note
+-          File Attributes::.
+-
+-    `unsigned char d_namlen'
+-          This is the length of the file name, not including the
+-          terminating null character.  Its type is `unsigned char'
+-          because that is the integer type of the appropriate size
+-
+-    `unsigned char d_type'
+-          This is the type of the file, possibly unknown.  The
+-          following constants are defined for its value:
+-
+-         `DT_UNKNOWN'
+-               The type is unknown.  On some systems this is the only
+-               value returned.
+-
+-         `DT_REG'
+-               A regular file.
+-
+-         `DT_DIR'
+-               A directory.
+-
+-         `DT_FIFO'
+-               A named pipe, or FIFO.  *Note FIFO Special Files::.
+-
+-         `DT_SOCK'
+-               A local-domain socket.
+-
+-         `DT_CHR'
+-               A character device.
+-
+-         `DT_BLK'
+-               A block device.
+-
+-          This member is a BSD extension.  Each value except DT_UNKNOWN
+-          corresponds to the file type bits in the `st_mode' member of
+-          `struct statbuf'.  These two macros convert between `d_type'
+-          values and `st_mode' values:
+-
+-           - Function: int IFTODT (mode_t MODE)
+-               This returns the `d_type' value corresponding to MODE.
+-
+-           - Function: mode_t DTTOIF (int DIRTYPE)
+-               This returns the `st_mode' value corresponding to
+-               DIRTYPE.
+-
+-     This structure may contain additional members in the future.
+-
+-     When a file has multiple names, each name has its own directory
+-     entry.  The only way you can tell that the directory entries
+-     belong to a single file is that they have the same value for the
+-     `d_fileno' field.
+-
+-     File attributes such as size, modification times, and the like are
+-     part of the file itself, not any particular directory entry.
+-     *Note File Attributes::.
+-
+-
+-File: libc.info,  Node: Opening a Directory,  Next: Reading/Closing 
Directory,  Prev: Directory Entries,  Up: Accessing Directories
+-
+-Opening a Directory Stream
+---------------------------
+-
+-   This section describes how to open a directory stream.  All the
+-symbols are declared in the header file `dirent.h'.
+-
+- - Data Type: DIR
+-     The `DIR' data type represents a directory stream.
+-
+-   You shouldn't ever allocate objects of the `struct dirent' or `DIR'
+-data types, since the directory access functions do that for you.
+-Instead, you refer to these objects using the pointers returned by the
+-following functions.
+-
+- - Function: DIR * opendir (const char *DIRNAME)
+-     The `opendir' function opens and returns a directory stream for
+-     reading the directory whose file name is DIRNAME.  The stream has
+-     type `DIR *'.
+-
+-     If unsuccessful, `opendir' returns a null pointer.  In addition to
+-     the usual file name errors (*note File Name Errors::.), the
+-     following `errno' error conditions are defined for this function:
+-
+-    `EACCES'
+-          Read permission is denied for the directory named by
+-          `dirname'.
+-
+-    `EMFILE'
+-          The process has too many files open.
+-
+-    `ENFILE'
+-          The entire system, or perhaps the file system which contains
+-          the directory, cannot support any additional open files at
+-          the moment.  (This problem cannot happen on the GNU system.)
+-
+-     The `DIR' type is typically implemented using a file descriptor,
+-     and the `opendir' function in terms of the `open' function.  *Note
+-     Low-Level I/O::.  Directory streams and the underlying file
+-     descriptors are closed on `exec' (*note Executing a File::.).
+-
+-
+-File: libc.info,  Node: Reading/Closing Directory,  Next: Simple Directory 
Lister,  Prev: Opening a Directory,  Up: Accessing Directories
+-
+-Reading and Closing a Directory Stream
+---------------------------------------
+-
+-   This section describes how to read directory entries from a directory
+-stream, and how to close the stream when you are done with it.  All the
+-symbols are declared in the header file `dirent.h'.
+-
+- - Function: struct dirent * readdir (DIR *DIRSTREAM)
+-     This function reads the next entry from the directory.  It normally
+-     returns a pointer to a structure containing information about the
+-     file.  This structure is statically allocated and can be rewritten
+-     by a subsequent call.
+-
+-     *Portability Note:* On some systems, `readdir' may not return
+-     entries for `.' and `..', even though these are always valid file
+-     names in any directory.  *Note File Name Resolution::.
+-
+-     If there are no more entries in the directory or an error is
+-     detected, `readdir' returns a null pointer.  The following `errno'
+-     error conditions are defined for this function:
+-
+-    `EBADF'
+-          The DIRSTREAM argument is not valid.
+-
+-     `readdir' is not thread safe.  Multiple threads using `readdir' on
+-     the same DIRSTREAM may overwrite the return value.  Use
+-     `readdir_r' when this is critical.
+-
+- - Function: int readdir_r (DIR *DIRSTREAM, struct *ENTRY, struct
+-          **RESULT)
+-     This function is the reentrant version of `readdir'.  Like
+-     `readdir' it returns the next entry from the directory.  But to
+-     prevent conflicts for simultaneously running threads the result is
+-     not stored in some internal memory.  Instead the argument ENTRY
+-     has to point to a place where the result is stored.
+-
+-     The return value is `0' in case the next entry was read
+-     successfully.  In this case a pointer to the result is returned in
+-     *RESULT.  It is not required that *RESULT is the same as ENTRY.
+-     If something goes wrong while executing `readdir_r' the function
+-     returns `-1'.  The `errno' variable is set like described for
+-     `readdir'.
+-
+-     *Portability Note:* On some systems, `readdir_r' may not return a
+-     terminated string as the file name even if no `d_reclen' element
+-     is available in `struct dirent' and the file name as the maximal
+-     allowed size.  Modern systems all have the `d_reclen' field and on
+-     old systems multi threading is not critical.  In any case, there
+-     is no such problem with the `readdir' function so that even on
+-     systems without `d_reclen' field one could use multiple threads by
+-     using external locking.
+-
+- - Function: int closedir (DIR *DIRSTREAM)
+-     This function closes the directory stream DIRSTREAM.  It returns
+-     `0' on success and `-1' on failure.
+-
+-     The following `errno' error conditions are defined for this
+-     function:
+-
+-    `EBADF'
+-          The DIRSTREAM argument is not valid.
+-
+-
+-File: libc.info,  Node: Simple Directory Lister,  Next: Random Access 
Directory,  Prev: Reading/Closing Directory,  Up: Accessing Directories
+-
+-Simple Program to List a Directory
+-----------------------------------
+-
+-   Here's a simple program that prints the names of the files in the
+-current working directory:
+-
+-     #include <stddef.h>
+-     #include <stdio.h>
+-     #include <sys/types.h>
+-     #include <dirent.h>
+-     
+-     int
+-     main (void)
+-     {
+-       DIR *dp;
+-       struct dirent *ep;
+-     
+-       dp = opendir ("./");
+-       if (dp != NULL)
+-         {
+-           while (ep = readdir (dp))
+-             puts (ep->d_name);
+-           (void) closedir (dp);
+-         }
+-       else
+-         puts ("Couldn't open the directory.");
+-     
+-       return 0;
+-     }
+-
+-   The order in which files appear in a directory tends to be fairly
+-random.  A more useful program would sort the entries (perhaps by
+-alphabetizing them) before printing them; see *Note Array Sort
+-Function::.
+-
+-
+-File: libc.info,  Node: Random Access Directory,  Prev: Simple Directory 
Lister,  Up: Accessing Directories
+-
+-Random Access in a Directory Stream
+------------------------------------
+-
+-   This section describes how to reread parts of a directory that you
+-have already read from an open directory stream.  All the symbols are
+-declared in the header file `dirent.h'.
+-
+- - Function: void rewinddir (DIR *DIRSTREAM)
+-     The `rewinddir' function is used to reinitialize the directory
+-     stream DIRSTREAM, so that if you call `readdir' it returns
+-     information about the first entry in the directory again.  This
+-     function also notices if files have been added or removed to the
+-     directory since it was opened with `opendir'.  (Entries for these
+-     files might or might not be returned by `readdir' if they were
+-     added or removed since you last called `opendir' or `rewinddir'.)
+-
+- - Function: off_t telldir (DIR *DIRSTREAM)
+-     The `telldir' function returns the file position of the directory
+-     stream DIRSTREAM.  You can use this value with `seekdir' to
+-     restore the directory stream to that position.
+-
+- - Function: void seekdir (DIR *DIRSTREAM, off_t POS)
+-     The `seekdir' function sets the file position of the directory
+-     stream DIRSTREAM to POS.  The value POS must be the result of a
+-     previous call to `telldir' on this particular stream; closing and
+-     reopening the directory can invalidate values returned by
+-     `telldir'.
+-
+-
+-File: libc.info,  Node: Hard Links,  Next: Symbolic Links,  Prev: Accessing 
Directories,  Up: File System Interface
+-
+-Hard Links
+-==========
+-
+-   In POSIX systems, one file can have many names at the same time.
+-All of the names are equally real, and no one of them is preferred to
+-the others.
+-
+-   To add a name to a file, use the `link' function.  (The new name is
+-also called a "hard link" to the file.)  Creating a new link to a file
+-does not copy the contents of the file; it simply makes a new name by
+-which the file can be known, in addition to the file's existing name or
+-names.
+-
+-   One file can have names in several directories, so the the
+-organization of the file system is not a strict hierarchy or tree.
+-
+-   In most implementations, it is not possible to have hard links to the
+-same file in multiple file systems.  `link' reports an error if you try
+-to make a hard link to the file from another file system when this
+-cannot be done.
+-
+-   The prototype for the `link' function is declared in the header file
+-`unistd.h'.
+-
+- - Function: int link (const char *OLDNAME, const char *NEWNAME)
+-     The `link' function makes a new link to the existing file named by
+-     OLDNAME, under the new name NEWNAME.
+-
+-     This function returns a value of `0' if it is successful and `-1'
+-     on failure.  In addition to the usual file name errors (*note File
+-     Name Errors::.) for both OLDNAME and NEWNAME, the following
+-     `errno' error conditions are defined for this function:
+-
+-    `EACCES'
+-          You are not allowed to write the directory in which the new
+-          link is to be written.
+-
+-    `EEXIST'
+-          There is already a file named NEWNAME.  If you want to replace
+-          this link with a new link, you must remove the old link
+-          explicitly first.
+-
+-    `EMLINK'
+-          There are already too many links to the file named by OLDNAME.
+-          (The maximum number of links to a file is `LINK_MAX'; see
+-          *Note Limits for Files::.)
+-
+-    `ENOENT'
+-          The file named by OLDNAME doesn't exist.  You can't make a
+-          link to a file that doesn't exist.
+-
+-    `ENOSPC'
+-          The directory or file system that would contain the new link
+-          is full and cannot be extended.
+-
+-    `EPERM'
+-          In the GNU system and some others, you cannot make links to
+-          directories.  Many systems allow only privileged users to do
+-          so.  This error is used to report the problem.
+-
+-    `EROFS'
+-          The directory containing the new link can't be modified
+-          because it's on a read-only file system.
+-
+-    `EXDEV'
+-          The directory specified in NEWNAME is on a different file
+-          system than the existing file.
+-
+-    `EIO'
+-          A hardware error occurred while trying to read or write the
+-          to filesystem.
+-
+-
+-File: libc.info,  Node: Symbolic Links,  Next: Deleting Files,  Prev: Hard 
Links,  Up: File System Interface
+-
+-Symbolic Links
+-==============
+-
+-   The GNU system supports "soft links" or "symbolic links".  This is a
+-kind of "file" that is essentially a pointer to another file name.
+-Unlike hard links, symbolic links can be made to directories or across
+-file systems with no restrictions.  You can also make a symbolic link
+-to a name which is not the name of any file.  (Opening this link will
+-fail until a file by that name is created.)  Likewise, if the symbolic
+-link points to an existing file which is later deleted, the symbolic
+-link continues to point to the same file name even though the name no
+-longer names any file.
+-
+-   The reason symbolic links work the way they do is that special things
+-happen when you try to open the link.  The `open' function realizes you
+-have specified the name of a link, reads the file name contained in the
+-link, and opens that file name instead.  The `stat' function likewise
+-operates on the file that the symbolic link points to, instead of on
+-the link itself.
+-
+-   By contrast, other operations such as deleting or renaming the file
+-operate on the link itself.  The functions `readlink' and `lstat' also
+-refrain from following symbolic links, because their purpose is to
+-obtain information about the link.  So does `link', the function that
+-makes a hard link--it makes a hard link to the symbolic link, which one
+-rarely wants.
+-
+-   Prototypes for the functions listed in this section are in
+-`unistd.h'.
+-
+- - Function: int symlink (const char *OLDNAME, const char *NEWNAME)
+-     The `symlink' function makes a symbolic link to OLDNAME named
+-     NEWNAME.
+-
+-     The normal return value from `symlink' is `0'.  A return value of
+-     `-1' indicates an error.  In addition to the usual file name
+-     syntax errors (*note File Name Errors::.), the following `errno'
+-     error conditions are defined for this function:
+-
+-    `EEXIST'
+-          There is already an existing file named NEWNAME.
+-
+-    `EROFS'
+-          The file NEWNAME would exist on a read-only file system.
+-
+-    `ENOSPC'
+-          The directory or file system cannot be extended to make the
+-          new link.
+-
+-    `EIO'
+-          A hardware error occurred while reading or writing data on
+-          the disk.
+-
+-
+- - Function: int readlink (const char *FILENAME, char *BUFFER, size_t
+-          SIZE)
+-     The `readlink' function gets the value of the symbolic link
+-     FILENAME.  The file name that the link points to is copied into
+-     BUFFER.  This file name string is *not* null-terminated;
+-     `readlink' normally returns the number of characters copied.  The
+-     SIZE argument specifies the maximum number of characters to copy,
+-     usually the allocation size of BUFFER.
+-
+-     If the return value equals SIZE, you cannot tell whether or not
+-     there was room to return the entire name.  So make a bigger buffer
+-     and call `readlink' again.  Here is an example:
+-
+-          char *
+-          readlink_malloc (char *filename)
+-          {
+-            int size = 100;
+-          
+-            while (1)
+-              {
+-                char *buffer = (char *) xmalloc (size);
+-                int nchars = readlink (filename, buffer, size);
+-                if (nchars < size)
+-                  return buffer;
+-                free (buffer);
+-                size *= 2;
+-              }
+-          }
+-
+-     A value of `-1' is returned in case of error.  In addition to the
+-     usual file name errors (*note File Name Errors::.), the following
+-     `errno' error conditions are defined for this function:
+-
+-    `EINVAL'
+-          The named file is not a symbolic link.
+-
+-    `EIO'
+-          A hardware error occurred while reading or writing data on
+-          the disk.
+-
+-
+-File: libc.info,  Node: Deleting Files,  Next: Renaming Files,  Prev: 
Symbolic Links,  Up: File System Interface
+-
+-Deleting Files
+-==============
+-
+-   You can delete a file with the functions `unlink' or `remove'.
+-
+-   Deletion actually deletes a file name.  If this is the file's only
+-name, then the file is deleted as well.  If the file has other names as
+-well (*note Hard Links::.), it remains accessible under its other names.
+-
+- - Function: int unlink (const char *FILENAME)
+-     The `unlink' function deletes the file name FILENAME.  If this is
+-     a file's sole name, the file itself is also deleted.  (Actually,
+-     if any process has the file open when this happens, deletion is
+-     postponed until all processes have closed the file.)
+-
+-     The function `unlink' is declared in the header file `unistd.h'.
+-
+-     This function returns `0' on successful completion, and `-1' on
+-     error.  In addition to the usual file name errors (*note File Name
+-     Errors::.), the following `errno' error conditions are defined for
+-     this function:
+-
+-    `EACCES'
+-          Write permission is denied for the directory from which the
+-          file is to be removed, or the directory has the sticky bit
+-          set and you do not own the file.
+-
+-    `EBUSY'
+-          This error indicates that the file is being used by the
+-          system in such a way that it can't be unlinked.  For example,
+-          you might see this error if the file name specifies the root
+-          directory or a mount point for a file system.
+-
+-    `ENOENT'
+-          The file name to be deleted doesn't exist.
+-
+-    `EPERM'
+-          On some systems, `unlink' cannot be used to delete the name
+-          of a directory, or can only be used this way by a privileged
+-          user.  To avoid such problems, use `rmdir' to delete
+-          directories.  (In the GNU system `unlink' can never delete
+-          the name of a directory.)
+-
+-    `EROFS'
+-          The directory in which the file name is to be deleted is on a
+-          read-only file system, and can't be modified.
+-
+- - Function: int rmdir (const char *FILENAME)
+-     The `rmdir' function deletes a directory.  The directory must be
+-     empty before it can be removed; in other words, it can only contain
+-     entries for `.' and `..'.
+-
+-     In most other respects, `rmdir' behaves like `unlink'.  There are
+-     two additional `errno' error conditions defined for `rmdir':
+-
+-    `ENOTEMPTY'
+-    `EEXIST'
+-          The directory to be deleted is not empty.
+-
+-     These two error codes are synonymous; some systems use one, and
+-     some use the other.  The GNU system always uses `ENOTEMPTY'.
+-
+-     The prototype for this function is declared in the header file
+-     `unistd.h'.
+-
+- - Function: int remove (const char *FILENAME)
+-     This is the ISO C function to remove a file.  It works like
+-     `unlink' for files and like `rmdir' for directories.  `remove' is
+-     declared in `stdio.h'.
+-
+-
+-File: libc.info,  Node: Renaming Files,  Next: Creating Directories,  Prev: 
Deleting Files,  Up: File System Interface
+-
+-Renaming Files
+-==============
+-
+-   The `rename' function is used to change a file's name.
+-
+- - Function: int rename (const char *OLDNAME, const char *NEWNAME)
+-     The `rename' function renames the file name OLDNAME with NEWNAME.
+-     The file formerly accessible under the name OLDNAME is afterward
+-     accessible as NEWNAME instead.  (If the file had any other names
+-     aside from OLDNAME, it continues to have those names.)
+-
+-     The directory containing the name NEWNAME must be on the same file
+-     system as the file (as indicated by the name OLDNAME).
+-
+-     One special case for `rename' is when OLDNAME and NEWNAME are two
+-     names for the same file.  The consistent way to handle this case
+-     is to delete OLDNAME.  However, POSIX requires that in this case
+-     `rename' do nothing and report success--which is inconsistent.  We
+-     don't know what your operating system will do.
+-
+-     If the OLDNAME is not a directory, then any existing file named
+-     NEWNAME is removed during the renaming operation.  However, if
+-     NEWNAME is the name of a directory, `rename' fails in this case.
+-
+-     If the OLDNAME is a directory, then either NEWNAME must not exist
+-     or it must name a directory that is empty.  In the latter case,
+-     the existing directory named NEWNAME is deleted first.  The name
+-     NEWNAME must not specify a subdirectory of the directory `oldname'
+-     which is being renamed.
+-
+-     One useful feature of `rename' is that the meaning of the name
+-     NEWNAME changes "atomically" from any previously existing file by
+-     that name to its new meaning (the file that was called OLDNAME).
+-     There is no instant at which NEWNAME is nonexistent "in between"
+-     the old meaning and the new meaning.  If there is a system crash
+-     during the operation, it is possible for both names to still
+-     exist; but NEWNAME will always be intact if it exists at all.
+-
+-     If `rename' fails, it returns `-1'.  In addition to the usual file
+-     name errors (*note File Name Errors::.), the following `errno'
+-     error conditions are defined for this function:
+-
+-    `EACCES'
+-          One of the directories containing NEWNAME or OLDNAME refuses
+-          write permission; or NEWNAME and OLDNAME are directories and
+-          write permission is refused for one of them.
+-
+-    `EBUSY'
+-          A directory named by OLDNAME or NEWNAME is being used by the
+-          system in a way that prevents the renaming from working.
+-          This includes directories that are mount points for
+-          filesystems, and directories that are the current working
+-          directories of processes.
+-
+-    `ENOTEMPTY'
+-    `EEXIST'
+-          The directory NEWNAME isn't empty.  The GNU system always
+-          returns `ENOTEMPTY' for this, but some other systems return
+-          `EEXIST'.
+-
+-    `EINVAL'
+-          The OLDNAME is a directory that contains NEWNAME.
+-
+-    `EISDIR'
+-          The NEWNAME names a directory, but the OLDNAME doesn't.
+-
+-    `EMLINK'
+-          The parent directory of NEWNAME would have too many links.
+-
+-    `ENOENT'
+-          The file named by OLDNAME doesn't exist.
+-
+-    `ENOSPC'
+-          The directory that would contain NEWNAME has no room for
+-          another entry, and there is no space left in the file system
+-          to expand it.
+-
+-    `EROFS'
+-          The operation would involve writing to a directory on a
+-          read-only file system.
+-
+-    `EXDEV'
+-          The two file names NEWNAME and OLDNAMES are on different file
+-          systems.
+-
+-
+-File: libc.info,  Node: Creating Directories,  Next: File Attributes,  Prev: 
Renaming Files,  Up: File System Interface
+-
+-Creating Directories
+-====================
+-
+-   Directories are created with the `mkdir' function.  (There is also a
+-shell command `mkdir' which does the same thing.)
+-
+- - Function: int mkdir (const char *FILENAME, mode_t MODE)
+-     The `mkdir' function creates a new, empty directory whose name is
+-     FILENAME.
+-
+-     The argument MODE specifies the file permissions for the new
+-     directory file.  *Note Permission Bits::, for more information
+-     about this.
+-
+-     A return value of `0' indicates successful completion, and `-1'
+-     indicates failure.  In addition to the usual file name syntax
+-     errors (*note File Name Errors::.), the following `errno' error
+-     conditions are defined for this function:
+-
+-    `EACCES'
+-          Write permission is denied for the parent directory in which
+-          the new directory is to be added.
+-
+-    `EEXIST'
+-          A file named FILENAME already exists.
+-
+-    `EMLINK'
+-          The parent directory has too many links.
+-
+-          Well-designed file systems never report this error, because
+-          they permit more links than your disk could possibly hold.
+-          However, you must still take account of the possibility of
+-          this error, as it could result from network access to a file
+-          system on another machine.
+-
+-    `ENOSPC'
+-          The file system doesn't have enough room to create the new
+-          directory.
+-
+-    `EROFS'
+-          The parent directory of the directory being created is on a
+-          read-only file system, and cannot be modified.
+-
+-     To use this function, your program should include the header file
+-     `sys/stat.h'.
+-
+-
+-File: libc.info,  Node: File Attributes,  Next: Making Special Files,  Prev: 
Creating Directories,  Up: File System Interface
+-
+-File Attributes
+-===============
+-
+-   When you issue an `ls -l' shell command on a file, it gives you
+-information about the size of the file, who owns it, when it was last
+-modified, and the like.  This kind of information is called the "file
+-attributes"; it is associated with the file itself and not a particular
+-one of its names.
+-
+-   This section contains information about how you can inquire about and
+-modify these attributes of files.
+-
+-* Menu:
+-
+-* Attribute Meanings::          The names of the file attributes,
+-                                 and what their values mean.
+-* Reading Attributes::          How to read the attributes of a file.
+-* Testing File Type::           Distinguishing ordinary files,
+-                                 directories, links...
+-* File Owner::                  How ownership for new files is determined,
+-                               and how to change it.
+-* Permission Bits::             How information about a file's access
+-                                 mode is stored.
+-* Access Permission::           How the system decides who can access a file.
+-* Setting Permissions::         How permissions for new files are assigned,
+-                               and how to change them.
+-* Testing File Access::         How to find out if your process can
+-                                 access a file.
+-* File Times::                  About the time attributes of a file.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-11 
glibc-2.0.1/manual/libc.info-11
+--- ../glibc-2.0.1/manual/libc.info-11 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-11    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1248 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Attribute Meanings,  Next: Reading Attributes,  Up: 
File Attributes
+-
+-What the File Attribute Values Mean
+------------------------------------
+-
+-   When you read the attributes of a file, they come back in a structure
+-called `struct stat'.  This section describes the names of the
+-attributes, their data types, and what they mean.  For the functions to
+-read the attributes of a file, see *Note Reading Attributes::.
+-
+-   The header file `sys/stat.h' declares all the symbols defined in
+-this section.
+-
+- - Data Type: struct stat
+-     The `stat' structure type is used to return information about the
+-     attributes of a file.  It contains at least the following members:
+-
+-    `mode_t st_mode'
+-          Specifies the mode of the file.  This includes file type
+-          information (*note Testing File Type::.) and the file
+-          permission bits (*note Permission Bits::.).
+-
+-    `ino_t st_ino'
+-          The file serial number, which distinguishes this file from
+-          all other files on the same device.
+-
+-    `dev_t st_dev'
+-          Identifies the device containing the file.  The `st_ino' and
+-          `st_dev', taken together, uniquely identify the file.  The
+-          `st_dev' value is not necessarily consistent across reboots or
+-          system crashes, however.
+-
+-    `nlink_t st_nlink'
+-          The number of hard links to the file.  This count keeps track
+-          of how many directories have entries for this file.  If the
+-          count is ever decremented to zero, then the file itself is
+-          discarded as soon as no process still holds it open.
+-          Symbolic links are not counted in the total.
+-
+-    `uid_t st_uid'
+-          The user ID of the file's owner.  *Note File Owner::.
+-
+-    `gid_t st_gid'
+-          The group ID of the file.  *Note File Owner::.
+-
+-    `off_t st_size'
+-          This specifies the size of a regular file in bytes.  For
+-          files that are really devices and the like, this field isn't
+-          usually meaningful.  For symbolic links, this specifies the
+-          length of the file name the link refers to.
+-
+-    `time_t st_atime'
+-          This is the last access time for the file.  *Note File
+-          Times::.
+-
+-    `unsigned long int st_atime_usec'
+-          This is the fractional part of the last access time for the
+-          file.  *Note File Times::.
+-
+-    `time_t st_mtime'
+-          This is the time of the last modification to the contents of
+-          the file.  *Note File Times::.
+-
+-    `unsigned long int st_mtime_usec'
+-          This is the fractional part of the time of last modification
+-          to the contents of the file.  *Note File Times::.
+-
+-    `time_t st_ctime'
+-          This is the time of the last modification to the attributes
+-          of the file.  *Note File Times::.
+-
+-    `unsigned long int st_ctime_usec'
+-          This is the fractional part of the time of last modification
+-          to the attributes of the file.  *Note File Times::.
+-
+-    `unsigned int st_blocks'
+-          This is the amount of disk space that the file occupies,
+-          measured in units of 512-byte blocks.
+-
+-          The number of disk blocks is not strictly proportional to the
+-          size of the file, for two reasons: the file system may use
+-          some blocks for internal record keeping; and the file may be
+-          sparse--it may have "holes" which contain zeros but do not
+-          actually take up space on the disk.
+-
+-          You can tell (approximately) whether a file is sparse by
+-          comparing this value with `st_size', like this:
+-
+-               (st.st_blocks * 512 < st.st_size)
+-
+-          This test is not perfect because a file that is just slightly
+-          sparse might not be detected as sparse at all.  For practical
+-          applications, this is not a problem.
+-
+-    `unsigned int st_blksize'
+-          The optimal block size for reading of writing this file, in
+-          bytes.  You might use this size for allocating the buffer
+-          space for reading of writing the file.  (This is unrelated to
+-          `st_blocks'.)
+-
+-   Some of the file attributes have special data type names which exist
+-specifically for those attributes.  (They are all aliases for well-known
+-integer types that you know and love.)  These typedef names are defined
+-in the header file `sys/types.h' as well as in `sys/stat.h'.  Here is a
+-list of them.
+-
+- - Data Type: mode_t
+-     This is an integer data type used to represent file modes.  In the
+-     GNU system, this is equivalent to `unsigned int'.
+-
+- - Data Type: ino_t
+-     This is an arithmetic data type used to represent file serial
+-     numbers.  (In Unix jargon, these are sometimes called "inode
+-     numbers".) In the GNU system, this type is equivalent to `unsigned
+-     long int'.
+-
+- - Data Type: dev_t
+-     This is an arithmetic data type used to represent file device
+-     numbers.  In the GNU system, this is equivalent to `int'.
+-
+- - Data Type: nlink_t
+-     This is an arithmetic data type used to represent file link counts.
+-     In the GNU system, this is equivalent to `unsigned short int'.
+-
+-
+-File: libc.info,  Node: Reading Attributes,  Next: Testing File Type,  Prev: 
Attribute Meanings,  Up: File Attributes
+-
+-Reading the Attributes of a File
+---------------------------------
+-
+-   To examine the attributes of files, use the functions `stat',
+-`fstat' and `lstat'.  They return the attribute information in a
+-`struct stat' object.  All three functions are declared in the header
+-file `sys/stat.h'.
+-
+- - Function: int stat (const char *FILENAME, struct stat *BUF)
+-     The `stat' function returns information about the attributes of the
+-     file named by FILENAME in the structure pointed at by BUF.
+-
+-     If FILENAME is the name of a symbolic link, the attributes you get
+-     describe the file that the link points to.  If the link points to a
+-     nonexistent file name, then `stat' fails, reporting a nonexistent
+-     file.
+-
+-     The return value is `0' if the operation is successful, and `-1'
+-     on failure.  In addition to the usual file name errors (*note File
+-     Name Errors::., the following `errno' error conditions are defined
+-     for this function:
+-
+-    `ENOENT'
+-          The file named by FILENAME doesn't exist.
+-
+- - Function: int fstat (int FILEDES, struct stat *BUF)
+-     The `fstat' function is like `stat', except that it takes an open
+-     file descriptor as an argument instead of a file name.  *Note
+-     Low-Level I/O::.
+-
+-     Like `stat', `fstat' returns `0' on success and `-1' on failure.
+-     The following `errno' error conditions are defined for `fstat':
+-
+-    `EBADF'
+-          The FILEDES argument is not a valid file descriptor.
+-
+- - Function: int lstat (const char *FILENAME, struct stat *BUF)
+-     The `lstat' function is like `stat', except that it does not
+-     follow symbolic links.  If FILENAME is the name of a symbolic
+-     link, `lstat' returns information about the link itself; otherwise,
+-     `lstat' works like `stat'.  *Note Symbolic Links::.
+-
+-
+-File: libc.info,  Node: Testing File Type,  Next: File Owner,  Prev: Reading 
Attributes,  Up: File Attributes
+-
+-Testing the Type of a File
+---------------------------
+-
+-   The "file mode", stored in the `st_mode' field of the file
+-attributes, contains two kinds of information: the file type code, and
+-the access permission bits.  This section discusses only the type code,
+-which you can use to tell whether the file is a directory, whether it is
+-a socket, and so on.  For information about the access permission,
+-*Note Permission Bits::.
+-
+-   There are two predefined ways you can access the file type portion of
+-the file mode.  First of all, for each type of file, there is a
+-"predicate macro" which examines a file mode value and returns true or
+-false--is the file of that type, or not.  Secondly, you can mask out
+-the rest of the file mode to get just a file type code.  You can
+-compare this against various constants for the supported file types.
+-
+-   All of the symbols listed in this section are defined in the header
+-file `sys/stat.h'.
+-
+-   The following predicate macros test the type of a file, given the
+-value M which is the `st_mode' field returned by `stat' on that file:
+-
+- - Macro: int S_ISDIR (mode_t M)
+-     This macro returns nonzero if the file is a directory.
+-
+- - Macro: int S_ISCHR (mode_t M)
+-     This macro returns nonzero if the file is a character special file
+-     (a device like a terminal).
+-
+- - Macro: int S_ISBLK (mode_t M)
+-     This macro returns nonzero if the file is a block special file (a
+-     device like a disk).
+-
+- - Macro: int S_ISREG (mode_t M)
+-     This macro returns nonzero if the file is a regular file.
+-
+- - Macro: int S_ISFIFO (mode_t M)
+-     This macro returns nonzero if the file is a FIFO special file, or a
+-     pipe.  *Note Pipes and FIFOs::.
+-
+- - Macro: int S_ISLNK (mode_t M)
+-     This macro returns nonzero if the file is a symbolic link.  *Note
+-     Symbolic Links::.
+-
+- - Macro: int S_ISSOCK (mode_t M)
+-     This macro returns nonzero if the file is a socket.  *Note
+-     Sockets::.
+-
+-   An alterate non-POSIX method of testing the file type is supported
+-for compatibility with BSD.  The mode can be bitwise ANDed with
+-`S_IFMT' to extract the file type code, and compared to the appropriate
+-type code constant.  For example,
+-
+-     S_ISCHR (MODE)
+-
+-is equivalent to:
+-
+-     ((MODE & S_IFMT) == S_IFCHR)
+-
+- - Macro: int S_IFMT
+-     This is a bit mask used to extract the file type code portion of a
+-     mode value.
+-
+-   These are the symbolic names for the different file type codes:
+-
+-`S_IFDIR'
+-     This macro represents the value of the file type code for a
+-     directory file.
+-
+-`S_IFCHR'
+-     This macro represents the value of the file type code for a
+-     character-oriented device file.
+-
+-`S_IFBLK'
+-     This macro represents the value of the file type code for a
+-     block-oriented device file.
+-
+-`S_IFREG'
+-     This macro represents the value of the file type code for a
+-     regular file.
+-
+-`S_IFLNK'
+-     This macro represents the value of the file type code for a
+-     symbolic link.
+-
+-`S_IFSOCK'
+-     This macro represents the value of the file type code for a socket.
+-
+-`S_IFIFO'
+-     This macro represents the value of the file type code for a FIFO
+-     or pipe.
+-
+-
+-File: libc.info,  Node: File Owner,  Next: Permission Bits,  Prev: Testing 
File Type,  Up: File Attributes
+-
+-File Owner
+-----------
+-
+-   Every file has an "owner" which is one of the registered user names
+-defined on the system.  Each file also has a "group", which is one of
+-the defined groups.  The file owner can often be useful for showing you
+-who edited the file (especially when you edit with GNU Emacs), but its
+-main purpose is for access control.
+-
+-   The file owner and group play a role in determining access because
+-the file has one set of access permission bits for the user that is the
+-owner, another set that apply to users who belong to the file's group,
+-and a third set of bits that apply to everyone else.  *Note Access
+-Permission::, for the details of how access is decided based on this
+-data.
+-
+-   When a file is created, its owner is set from the effective user ID
+-of the process that creates it (*note Process Persona::.).  The file's
+-group ID may be set from either effective group ID of the process, or
+-the group ID of the directory that contains the file, depending on the
+-system where the file is stored.  When you access a remote file system,
+-it behaves according to its own rule, not according to the system your
+-program is running on.  Thus, your program must be prepared to encounter
+-either kind of behavior, no matter what kind of system you run it on.
+-
+-   You can change the owner and/or group owner of an existing file using
+-the `chown' function.  This is the primitive for the `chown' and
+-`chgrp' shell commands.
+-
+-   The prototype for this function is declared in `unistd.h'.
+-
+- - Function: int chown (const char *FILENAME, uid_t OWNER, gid_t GROUP)
+-     The `chown' function changes the owner of the file FILENAME to
+-     OWNER, and its group owner to GROUP.
+-
+-     Changing the owner of the file on certain systems clears the
+-     set-user-ID and set-group-ID bits of the file's permissions.
+-     (This is because those bits may not be appropriate for the new
+-     owner.)  The other file permission bits are not changed.
+-
+-     The return value is `0' on success and `-1' on failure.  In
+-     addition to the usual file name errors (*note File Name Errors::.),
+-     the following `errno' error conditions are defined for this
+-     function:
+-
+-    `EPERM'
+-          This process lacks permission to make the requested change.
+-
+-          Only privileged users or the file's owner can change the
+-          file's group.  On most file systems, only privileged users
+-          can change the file owner; some file systems allow you to
+-          change the owner if you are currently the owner.  When you
+-          access a remote file system, the behavior you encounter is
+-          determined by the system that actually holds the file, not by
+-          the system your program is running on.
+-
+-          *Note Options for Files::, for information about the
+-          `_POSIX_CHOWN_RESTRICTED' macro.
+-
+-    `EROFS'
+-          The file is on a read-only file system.
+-
+- - Function: int fchown (int FILEDES, int OWNER, int GROUP)
+-     This is like `chown', except that it changes the owner of the file
+-     with open file descriptor FILEDES.
+-
+-     The return value from `fchown' is `0' on success and `-1' on
+-     failure.  The following `errno' error codes are defined for this
+-     function:
+-
+-    `EBADF'
+-          The FILEDES argument is not a valid file descriptor.
+-
+-    `EINVAL'
+-          The FILEDES argument corresponds to a pipe or socket, not an
+-          ordinary file.
+-
+-    `EPERM'
+-          This process lacks permission to make the requested change.
+-          For details, see `chmod', above.
+-
+-    `EROFS'
+-          The file resides on a read-only file system.
+-
+-
+-File: libc.info,  Node: Permission Bits,  Next: Access Permission,  Prev: 
File Owner,  Up: File Attributes
+-
+-The Mode Bits for Access Permission
+------------------------------------
+-
+-   The "file mode", stored in the `st_mode' field of the file
+-attributes, contains two kinds of information: the file type code, and
+-the access permission bits.  This section discusses only the access
+-permission bits, which control who can read or write the file.  *Note
+-Testing File Type::, for information about the file type code.
+-
+-   All of the symbols listed in this section are defined in the header
+-file `sys/stat.h'.
+-
+-   These symbolic constants are defined for the file mode bits that
+-control access permission for the file:
+-
+-`S_IRUSR'
+-`S_IREAD'
+-     Read permission bit for the owner of the file.  On many systems,
+-     this bit is 0400.  `S_IREAD' is an obsolete synonym provided for
+-     BSD compatibility.
+-
+-`S_IWUSR'
+-`S_IWRITE'
+-     Write permission bit for the owner of the file.  Usually 0200.
+-     `S_IWRITE' is an obsolete synonym provided for BSD compatibility.
+-
+-`S_IXUSR'
+-`S_IEXEC'
+-     Execute (for ordinary files) or search (for directories)
+-     permission bit for the owner of the file.  Usually 0100.
+-     `S_IEXEC' is an obsolete synonym provided for BSD compatibility.
+-
+-`S_IRWXU'
+-     This is equivalent to `(S_IRUSR | S_IWUSR | S_IXUSR)'.
+-
+-`S_IRGRP'
+-     Read permission bit for the group owner of the file.  Usually 040.
+-
+-`S_IWGRP'
+-     Write permission bit for the group owner of the file.  Usually 020.
+-
+-`S_IXGRP'
+-     Execute or search permission bit for the group owner of the file.
+-     Usually 010.
+-
+-`S_IRWXG'
+-     This is equivalent to `(S_IRGRP | S_IWGRP | S_IXGRP)'.
+-
+-`S_IROTH'
+-     Read permission bit for other users.  Usually 04.
+-
+-`S_IWOTH'
+-     Write permission bit for other users.  Usually 02.
+-
+-`S_IXOTH'
+-     Execute or search permission bit for other users.  Usually 01.
+-
+-`S_IRWXO'
+-     This is equivalent to `(S_IROTH | S_IWOTH | S_IXOTH)'.
+-
+-`S_ISUID'
+-     This is the set-user-ID on execute bit, usually 04000.  *Note How
+-     Change Persona::.
+-
+-`S_ISGID'
+-     This is the set-group-ID on execute bit, usually 02000.  *Note How
+-     Change Persona::.
+-
+-`S_ISVTX'
+-     This is the "sticky" bit, usually 01000.
+-
+-     On a directory, it gives permission to delete a file in the
+-     directory only if you own that file.  Ordinarily, a user either
+-     can delete all the files in the directory or cannot delete any of
+-     them (based on whether the user has write permission for the
+-     directory).  The same restriction applies--you must both have
+-     write permission for the directory and own the file you want to
+-     delete.  The one exception is that the owner of the directory can
+-     delete any file in the directory, no matter who owns it (provided
+-     the owner has given himself write permission for the directory).
+-     This is commonly used for the `/tmp' directory, where anyone may
+-     create files, but not delete files created by other users.
+-
+-     Originally the sticky bit on an executable file modified the
+-     swapping policies of the system.  Normally, when a program
+-     terminated, its pages in core were immediately freed and reused.
+-     If the sticky bit was set on the executable file, the system kept
+-     the pages in core for a while as if the program were still
+-     running.  This was advantageous for a program likely to be run
+-     many times in succession.  This usage is obsolete in modern
+-     systems.  When a program terminates, its pages always remain in
+-     core as long as there is no shortage of memory in the system.
+-     When the program is next run, its pages will still be in core if
+-     no shortage arose since the last run.
+-
+-     On some modern systems where the sticky bit has no useful meaning
+-     for an executable file, you cannot set the bit at all for a
+-     non-directory.  If you try, `chmod' fails with `EFTYPE'; *note
+-     Setting Permissions::..
+-
+-     Some systems (particularly SunOS) have yet another use for the
+-     sticky bit.  If the sticky bit is set on a file that is *not*
+-     executable, it means the opposite: never cache the pages of this
+-     file at all.  The main use of this is for the files on an NFS
+-     server machine which are used as the swap area of diskless client
+-     machines.  The idea is that the pages of the file will be cached
+-     in the client's memory, so it is a waste of the server's memory to
+-     cache them a second time.  In this use the sticky bit also says
+-     that the filesystem may fail to record the file's modification
+-     time onto disk reliably (the idea being that noone cares for a
+-     swap file).
+-
+-   The actual bit values of the symbols are listed in the table above
+-so you can decode file mode values when debugging your programs.  These
+-bit values are correct for most systems, but they are not guaranteed.
+-
+-   *Warning:* Writing explicit numbers for file permissions is bad
+-practice.  It is not only nonportable, it also requires everyone who
+-reads your program to remember what the bits mean.  To make your
+-program clean, use the symbolic names.
+-
+-
+-File: libc.info,  Node: Access Permission,  Next: Setting Permissions,  Prev: 
Permission Bits,  Up: File Attributes
+-
+-How Your Access to a File is Decided
+-------------------------------------
+-
+-   Recall that the operating system normally decides access permission
+-for a file based on the effective user and group IDs of the process,
+-and its supplementary group IDs, together with the file's owner, group
+-and permission bits.  These concepts are discussed in detail in *Note
+-Process Persona::.
+-
+-   If the effective user ID of the process matches the owner user ID of
+-the file, then permissions for read, write, and execute/search are
+-controlled by the corresponding "user" (or "owner") bits.  Likewise, if
+-any of the effective group ID or supplementary group IDs of the process
+-matches the group owner ID of the file, then permissions are controlled
+-by the "group" bits.  Otherwise, permissions are controlled by the
+-"other" bits.
+-
+-   Privileged users, like `root', can access any file, regardless of
+-its file permission bits.  As a special case, for a file to be
+-executable even for a privileged user, at least one of its execute bits
+-must be set.
+-
+-
+-File: libc.info,  Node: Setting Permissions,  Next: Testing File Access,  
Prev: Access Permission,  Up: File Attributes
+-
+-Assigning File Permissions
+---------------------------
+-
+-   The primitive functions for creating files (for example, `open' or
+-`mkdir') take a MODE argument, which specifies the file permissions for
+-the newly created file.  But the specified mode is modified by the
+-process's "file creation mask", or "umask", before it is used.
+-
+-   The bits that are set in the file creation mask identify permissions
+-that are always to be disabled for newly created files.  For example, if
+-you set all the "other" access bits in the mask, then newly created
+-files are not accessible at all to processes in the "other" category,
+-even if the MODE argument specified to the creation function would
+-permit such access.  In other words, the file creation mask is the
+-complement of the ordinary access permissions you want to grant.
+-
+-   Programs that create files typically specify a MODE argument that
+-includes all the permissions that make sense for the particular file.
+-For an ordinary file, this is typically read and write permission for
+-all classes of users.  These permissions are then restricted as
+-specified by the individual user's own file creation mask.
+-
+-   To change the permission of an existing file given its name, call
+-`chmod'.  This function ignores the file creation mask; it uses exactly
+-the specified permission bits.
+-
+-   In normal use, the file creation mask is initialized in the user's
+-login shell (using the `umask' shell command), and inherited by all
+-subprocesses.  Application programs normally don't need to worry about
+-the file creation mask.  It will do automatically what it is supposed to
+-do.
+-
+-   When your program should create a file and bypass the umask for its
+-access permissions, the easiest way to do this is to use `fchmod' after
+-opening the file, rather than changing the umask.
+-
+-   In fact, changing the umask is usually done only by shells.  They use
+-the `umask' function.
+-
+-   The functions in this section are declared in `sys/stat.h'.
+-
+- - Function: mode_t umask (mode_t MASK)
+-     The `umask' function sets the file creation mask of the current
+-     process to MASK, and returns the previous value of the file
+-     creation mask.
+-
+-     Here is an example showing how to read the mask with `umask'
+-     without changing it permanently:
+-
+-          mode_t
+-          read_umask (void)
+-          {
+-            mask = umask (0);
+-            umask (mask);
+-          }
+-
+-     However, it is better to use `getumask' if you just want to read
+-     the mask value, because that is reentrant (at least if you use the
+-     GNU operating system).
+-
+- - Function: mode_t getumask (void)
+-     Return the current value of the file creation mask for the current
+-     process.  This function is a GNU extension.
+-
+- - Function: int chmod (const char *FILENAME, mode_t MODE)
+-     The `chmod' function sets the access permission bits for the file
+-     named by FILENAME to MODE.
+-
+-     If the FILENAME names a symbolic link, `chmod' changes the
+-     permission of the file pointed to by the link, not those of the
+-     link itself.
+-
+-     This function returns `0' if successful and `-1' if not.  In
+-     addition to the usual file name errors (*note File Name
+-     Errors::.), the following `errno' error conditions are defined for
+-     this function:
+-
+-    `ENOENT'
+-          The named file doesn't exist.
+-
+-    `EPERM'
+-          This process does not have permission to change the access
+-          permission of this file.  Only the file's owner (as judged by
+-          the effective user ID of the process) or a privileged user
+-          can change them.
+-
+-    `EROFS'
+-          The file resides on a read-only file system.
+-
+-    `EFTYPE'
+-          MODE has the `S_ISVTX' bit (the "sticky bit") set, and the
+-          named file is not a directory.  Some systems do not allow
+-          setting the sticky bit on non-directory files, and some do
+-          (and only some of those assign a useful meaning to the bit
+-          for non-directory files).
+-
+-          You only get `EFTYPE' on systems where the sticky bit has no
+-          useful meaning for non-directory files, so it is always safe
+-          to just clear the bit in MODE and call `chmod' again.  *Note
+-          Permission Bits::, for full details on the sticky bit.
+-
+- - Function: int fchmod (int FILEDES, int MODE)
+-     This is like `chmod', except that it changes the permissions of
+-     the file currently open via descriptor FILEDES.
+-
+-     The return value from `fchmod' is `0' on success and `-1' on
+-     failure.  The following `errno' error codes are defined for this
+-     function:
+-
+-    `EBADF'
+-          The FILEDES argument is not a valid file descriptor.
+-
+-    `EINVAL'
+-          The FILEDES argument corresponds to a pipe or socket, or
+-          something else that doesn't really have access permissions.
+-
+-    `EPERM'
+-          This process does not have permission to change the access
+-          permission of this file.  Only the file's owner (as judged by
+-          the effective user ID of the process) or a privileged user
+-          can change them.
+-
+-    `EROFS'
+-          The file resides on a read-only file system.
+-
+-
+-File: libc.info,  Node: Testing File Access,  Next: File Times,  Prev: 
Setting Permissions,  Up: File Attributes
+-
+-Testing Permission to Access a File
+------------------------------------
+-
+-   When a program runs as a privileged user, this permits it to access
+-files off-limits to ordinary users--for example, to modify
+-`/etc/passwd'.  Programs designed to be run by ordinary users but
+-access such files use the setuid bit feature so that they always run
+-with `root' as the effective user ID.
+-
+-   Such a program may also access files specified by the user, files
+-which conceptually are being accessed explicitly by the user.  Since the
+-program runs as `root', it has permission to access whatever file the
+-user specifies--but usually the desired behavior is to permit only
+-those files which the user could ordinarily access.
+-
+-   The program therefore must explicitly check whether *the user* would
+-have the necessary access to a file, before it reads or writes the file.
+-
+-   To do this, use the function `access', which checks for access
+-permission based on the process's *real* user ID rather than the
+-effective user ID.  (The setuid feature does not alter the real user ID,
+-so it reflects the user who actually ran the program.)
+-
+-   There is another way you could check this access, which is easy to
+-describe, but very hard to use.  This is to examine the file mode bits
+-and mimic the system's own access computation.  This method is
+-undesirable because many systems have additional access control
+-features; your program cannot portably mimic them, and you would not
+-want to try to keep track of the diverse features that different systems
+-have.  Using `access' is simple and automatically does whatever is
+-appropriate for the system you are using.
+-
+-   `access' is *only* only appropriate to use in setuid programs.  A
+-non-setuid program will always use the effective ID rather than the
+-real ID.
+-
+-   The symbols in this section are declared in `unistd.h'.
+-
+- - Function: int access (const char *FILENAME, int HOW)
+-     The `access' function checks to see whether the file named by
+-     FILENAME can be accessed in the way specified by the HOW argument.
+-     The HOW argument either can be the bitwise OR of the flags
+-     `R_OK', `W_OK', `X_OK', or the existence test `F_OK'.
+-
+-     This function uses the *real* user and group ID's of the calling
+-     process, rather than the *effective* ID's, to check for access
+-     permission.  As a result, if you use the function from a `setuid'
+-     or `setgid' program (*note How Change Persona::.), it gives
+-     information relative to the user who actually ran the program.
+-
+-     The return value is `0' if the access is permitted, and `-1'
+-     otherwise.  (In other words, treated as a predicate function,
+-     `access' returns true if the requested access is *denied*.)
+-
+-     In addition to the usual file name errors (*note File Name
+-     Errors::.), the following `errno' error conditions are defined for
+-     this function:
+-
+-    `EACCES'
+-          The access specified by HOW is denied.
+-
+-    `ENOENT'
+-          The file doesn't exist.
+-
+-    `EROFS'
+-          Write permission was requested for a file on a read-only file
+-          system.
+-
+-   These macros are defined in the header file `unistd.h' for use as
+-the HOW argument to the `access' function.  The values are integer
+-constants.
+-
+- - Macro: int R_OK
+-     Argument that means, test for read permission.
+-
+- - Macro: int W_OK
+-     Argument that means, test for write permission.
+-
+- - Macro: int X_OK
+-     Argument that means, test for execute/search permission.
+-
+- - Macro: int F_OK
+-     Argument that means, test for existence of the file.
+-
+-
+-File: libc.info,  Node: File Times,  Prev: Testing File Access,  Up: File 
Attributes
+-
+-File Times
+-----------
+-
+-   Each file has three timestamps associated with it:  its access time,
+-its modification time, and its attribute modification time.  These
+-correspond to the `st_atime', `st_mtime', and `st_ctime' members of the
+-`stat' structure; see *Note File Attributes::.
+-
+-   All of these times are represented in calendar time format, as
+-`time_t' objects.  This data type is defined in `time.h'.  For more
+-information about representation and manipulation of time values, see
+-*Note Calendar Time::.
+-
+-   Reading from a file updates its access time attribute, and writing
+-updates its modification time.  When a file is created, all three
+-timestamps for that file are set to the current time.  In addition, the
+-attribute change time and modification time fields of the directory that
+-contains the new entry are updated.
+-
+-   Adding a new name for a file with the `link' function updates the
+-attribute change time field of the file being linked, and both the
+-attribute change time and modification time fields of the directory
+-containing the new name.  These same fields are affected if a file name
+-is deleted with `unlink', `remove', or `rmdir'.  Renaming a file with
+-`rename' affects only the attribute change time and modification time
+-fields of the two parent directories involved, and not the times for
+-the file being renamed.
+-
+-   Changing attributes of a file (for example, with `chmod') updates
+-its attribute change time field.
+-
+-   You can also change some of the timestamps of a file explicitly using
+-the `utime' function--all except the attribute change time.  You need
+-to include the header file `utime.h' to use this facility.
+-
+- - Data Type: struct utimbuf
+-     The `utimbuf' structure is used with the `utime' function to
+-     specify new access and modification times for a file.  It contains
+-     the following members:
+-
+-    `time_t actime'
+-          This is the access time for the file.
+-
+-    `time_t modtime'
+-          This is the modification time for the file.
+-
+- - Function: int utime (const char *FILENAME, const struct utimbuf
+-          *TIMES)
+-     This function is used to modify the file times associated with the
+-     file named FILENAME.
+-
+-     If TIMES is a null pointer, then the access and modification times
+-     of the file are set to the current time.  Otherwise, they are set
+-     to the values from the `actime' and `modtime' members
+-     (respectively) of the `utimbuf' structure pointed at by TIMES.
+-
+-     The attribute modification time for the file is set to the current
+-     time in either case (since changing the timestamps is itself a
+-     modification of the file attributes).
+-
+-     The `utime' function returns `0' if successful and `-1' on
+-     failure.  In addition to the usual file name errors (*note File
+-     Name Errors::.), the following `errno' error conditions are
+-     defined for this function:
+-
+-    `EACCES'
+-          There is a permission problem in the case where a null
+-          pointer was passed as the TIMES argument.  In order to update
+-          the timestamp on the file, you must either be the owner of
+-          the file, have write permission on the file, or be a
+-          privileged user.
+-
+-    `ENOENT'
+-          The file doesn't exist.
+-
+-    `EPERM'
+-          If the TIMES argument is not a null pointer, you must either
+-          be the owner of the file or be a privileged user.  This error
+-          is used to report the problem.
+-
+-    `EROFS'
+-          The file lives on a read-only file system.
+-
+-   Each of the three time stamps has a corresponding microsecond part,
+-which extends its resolution.  These fields are called `st_atime_usec',
+-`st_mtime_usec', and `st_ctime_usec'; each has a value between 0 and
+-999,999, which indicates the time in microseconds.  They correspond to
+-the `tv_usec' field of a `timeval' structure; see *Note High-Resolution
+-Calendar::.
+-
+-   The `utimes' function is like `utime', but also lets you specify the
+-fractional part of the file times.  The prototype for this function is
+-in the header file `sys/time.h'.
+-
+- - Function: int utimes (const char *FILENAME, struct timeval TVP[2])
+-     This function sets the file access and modification times for the
+-     file named by FILENAME.  The new file access time is specified by
+-     `TVP[0]', and the new modification time by `TVP[1]'.  This
+-     function comes from BSD.
+-
+-     The return values and error conditions are the same as for the
+-     `utime' function.
+-
+-
+-File: libc.info,  Node: Making Special Files,  Next: Temporary Files,  Prev: 
File Attributes,  Up: File System Interface
+-
+-Making Special Files
+-====================
+-
+-   The `mknod' function is the primitive for making special files, such
+-as files that correspond to devices.  The GNU library includes this
+-function for compatibility with BSD.
+-
+-   The prototype for `mknod' is declared in `sys/stat.h'.
+-
+- - Function: int mknod (const char *FILENAME, int MODE, int DEV)
+-     The `mknod' function makes a special file with name FILENAME.  The
+-     MODE specifies the mode of the file, and may include the various
+-     special file bits, such as `S_IFCHR' (for a character special file)
+-     or `S_IFBLK' (for a block special file).  *Note Testing File
+-     Type::.
+-
+-     The DEV argument specifies which device the special file refers to.
+-     Its exact interpretation depends on the kind of special file being
+-     created.
+-
+-     The return value is `0' on success and `-1' on error.  In addition
+-     to the usual file name errors (*note File Name Errors::.), the
+-     following `errno' error conditions are defined for this function:
+-
+-    `EPERM'
+-          The calling process is not privileged.  Only the superuser
+-          can create special files.
+-
+-    `ENOSPC'
+-          The directory or file system that would contain the new file
+-          is full and cannot be extended.
+-
+-    `EROFS'
+-          The directory containing the new file can't be modified
+-          because it's on a read-only file system.
+-
+-    `EEXIST'
+-          There is already a file named FILENAME.  If you want to
+-          replace this file, you must remove the old file explicitly
+-          first.
+-
+-
+-File: libc.info,  Node: Temporary Files,  Prev: Making Special Files,  Up: 
File System Interface
+-
+-Temporary Files
+-===============
+-
+-   If you need to use a temporary file in your program, you can use the
+-`tmpfile' function to open it.  Or you can use the `tmpnam' (better:
+-`tmpnam_r') function make a name for a temporary file and then open it
+-in the usual way with `fopen'.
+-
+-   The `tempnam' function is like `tmpnam' but lets you choose what
+-directory temporary files will go in, and something about what their
+-file names will look like.  Important for multi threaded programs is
+-that `tempnam' is reentrant while `tmpnam' is not since it returns a
+-pointer to a static buffer.
+-
+-   These facilities are declared in the header file `stdio.h'.
+-
+- - Function: FILE * tmpfile (void)
+-     This function creates a temporary binary file for update mode, as
+-     if by calling `fopen' with mode `"wb+"'.  The file is deleted
+-     automatically when it is closed or when the program terminates.
+-     (On some other ISO C systems the file may fail to be deleted if
+-     the program terminates abnormally).
+-
+-     This function is reentrant.
+-
+- - Function: char * tmpnam (char *RESULT)
+-     This function constructs and returns a file name that is a valid
+-     file name and that does not name any existing file.  If the RESULT
+-     argument is a null pointer, the return value is a pointer to an
+-     internal static string, which might be modified by subsequent
+-     calls and therefore makes this function non-reentrant.  Otherwise,
+-     the RESULT argument should be a pointer to an array of at least
+-     `L_tmpnam' characters, and the result is written into that array.
+-
+-     It is possible for `tmpnam' to fail if you call it too many times
+-     without removing previously created files.  This is because the
+-     fixed length of a temporary file name gives room for only a finite
+-     number of different names.  If `tmpnam' fails, it returns a null
+-     pointer.
+-
+- - Function: char * tmpnam_r (char *RESULT)
+-     This function is nearly identical to the `tmpnam' function.  But it
+-     does not allow RESULT to be a null pointer.  In the later case a
+-     null pointer is returned.
+-
+-     This function is reentrant because the non-reentrant situation of
+-     `tmpnam' cannot happen here.
+-
+- - Macro: int L_tmpnam
+-     The value of this macro is an integer constant expression that
+-     represents the minimum allocation size of a string large enough to
+-     hold the file name generated by the `tmpnam' function.
+-
+- - Macro: int TMP_MAX
+-     The macro `TMP_MAX' is a lower bound for how many temporary names
+-     you can create with `tmpnam'.  You can rely on being able to call
+-     `tmpnam' at least this many times before it might fail saying you
+-     have made too many temporary file names.
+-
+-     With the GNU library, you can create a very large number of
+-     temporary file names--if you actually create the files, you will
+-     probably run out of disk space before you run out of names.  Some
+-     other systems have a fixed, small limit on the number of temporary
+-     files.  The limit is never less than `25'.
+-
+- - Function: char * tempnam (const char *DIR, const char *PREFIX)
+-     This function generates a unique temporary filename.  If PREFIX is
+-     not a null pointer, up to five characters of this string are used
+-     as a prefix for the file name.  The return value is a string newly
+-     allocated with `malloc'; you should release its storage with
+-     `free' when it is no longer needed.
+-
+-     Because the string is dynamically allocated this function is
+-     reentrant.
+-
+-     The directory prefix for the temporary file name is determined by
+-     testing each of the following, in sequence.  The directory must
+-     exist and be writable.
+-
+-        * The environment variable `TMPDIR', if it is defined.  For
+-          security reasons this only happens if the program is not SUID
+-          or SGID enabled.
+-
+-        * The DIR argument, if it is not a null pointer.
+-
+-        * The value of the `P_tmpdir' macro.
+-
+-        * The directory `/tmp'.
+-
+-     This function is defined for SVID compatibility.
+-
+- - SVID Macro: char * P_tmpdir
+-     This macro is the name of the default directory for temporary
+-     files.
+-
+-   Older Unix systems did not have the functions just described.
+-Instead they used `mktemp' and `mkstemp'.  Both of these functions work
+-by modifying a file name template string you pass.  The last six
+-characters of this string must be `XXXXXX'.  These six `X's are
+-replaced with six characters which make the whole string a unique file
+-name.  Usually the template string is something like
+-`/tmp/PREFIXXXXXXX', and each program uses a unique PREFIX.
+-
+-   *Note:* Because `mktemp' and `mkstemp' modify the template string,
+-you *must not* pass string constants to them.  String constants are
+-normally in read-only storage, so your program would crash when
+-`mktemp' or `mkstemp' tried to modify the string.
+-
+- - Function: char * mktemp (char *TEMPLATE)
+-     The `mktemp' function generates a unique file name by modifying
+-     TEMPLATE as described above.  If successful, it returns TEMPLATE
+-     as modified.  If `mktemp' cannot find a unique file name, it makes
+-     TEMPLATE an empty string and returns that.  If TEMPLATE does not
+-     end with `XXXXXX', `mktemp' returns a null pointer.
+-
+- - Function: int mkstemp (char *TEMPLATE)
+-     The `mkstemp' function generates a unique file name just as
+-     `mktemp' does, but it also opens the file for you with `open'
+-     (*note Opening and Closing Files::.).  If successful, it modifies
+-     TEMPLATE in place and returns a file descriptor open on that file
+-     for reading and writing.  If `mkstemp' cannot create a
+-     uniquely-named file, it makes TEMPLATE an empty string and returns
+-     `-1'.  If TEMPLATE does not end with `XXXXXX', `mkstemp' returns
+-     `-1' and does not modify TEMPLATE.
+-
+-   Unlike `mktemp', `mkstemp' is actually guaranteed to create a unique
+-file that cannot possibly clash with any other program trying to create
+-a temporary file.  This is because it works by calling `open' with the
+-`O_EXCL' flag bit, which says you want to always create a new file, and
+-get an error if the file already exists.
+-
+-
+-File: libc.info,  Node: Pipes and FIFOs,  Next: Sockets,  Prev: File System 
Interface,  Up: Top
+-
+-Pipes and FIFOs
+-***************
+-
+-   A "pipe" is a mechanism for interprocess communication; data written
+-to the pipe by one process can be read by another process.  The data is
+-handled in a first-in, first-out (FIFO) order.  The pipe has no name; it
+-is created for one use and both ends must be inherited from the single
+-process which created the pipe.
+-
+-   A "FIFO special file" is similar to a pipe, but instead of being an
+-anonymous, temporary connection, a FIFO has a name or names like any
+-other file.  Processes open the FIFO by name in order to communicate
+-through it.
+-
+-   A pipe or FIFO has to be open at both ends simultaneously.  If you
+-read from a pipe or FIFO file that doesn't have any processes writing
+-to it (perhaps because they have all closed the file, or exited), the
+-read returns end-of-file.  Writing to a pipe or FIFO that doesn't have a
+-reading process is treated as an error condition; it generates a
+-`SIGPIPE' signal, and fails with error code `EPIPE' if the signal is
+-handled or blocked.
+-
+-   Neither pipes nor FIFO special files allow file positioning.  Both
+-reading and writing operations happen sequentially; reading from the
+-beginning of the file and writing at the end.
+-
+-* Menu:
+-
+-* Creating a Pipe::             Making a pipe with the `pipe' function.
+-* Pipe to a Subprocess::        Using a pipe to communicate with a
+-                               child process.
+-* FIFO Special Files::          Making a FIFO special file.
+-* Pipe Atomicity::            When pipe (or FIFO) I/O is atomic.
+-
+-
+-File: libc.info,  Node: Creating a Pipe,  Next: Pipe to a Subprocess,  Up: 
Pipes and FIFOs
+-
+-Creating a Pipe
+-===============
+-
+-   The primitive for creating a pipe is the `pipe' function.  This
+-creates both the reading and writing ends of the pipe.  It is not very
+-useful for a single process to use a pipe to talk to itself.  In typical
+-use, a process creates a pipe just before it forks one or more child
+-processes (*note Creating a Process::.).  The pipe is then used for
+-communication either between the parent or child processes, or between
+-two sibling processes.
+-
+-   The `pipe' function is declared in the header file `unistd.h'.
+-
+- - Function: int pipe (int FILEDES[2])
+-     The `pipe' function creates a pipe and puts the file descriptors
+-     for the reading and writing ends of the pipe (respectively) into
+-     `FILEDES[0]' and `FILEDES[1]'.
+-
+-     An easy way to remember that the input end comes first is that file
+-     descriptor `0' is standard input, and file descriptor `1' is
+-     standard output.
+-
+-     If successful, `pipe' returns a value of `0'.  On failure, `-1' is
+-     returned.  The following `errno' error conditions are defined for
+-     this function:
+-
+-    `EMFILE'
+-          The process has too many files open.
+-
+-    `ENFILE'
+-          There are too many open files in the entire system.  *Note
+-          Error Codes::, for more information about `ENFILE'.  This
+-          error never occurs in the GNU system.
+-
+-   Here is an example of a simple program that creates a pipe.  This
+-program uses the `fork' function (*note Creating a Process::.) to create
+-a child process.  The parent process writes data to the pipe, which is
+-read by the child process.
+-
+-     #include <sys/types.h>
+-     #include <unistd.h>
+-     #include <stdio.h>
+-     #include <stdlib.h>
+-     
+-     /* Read characters from the pipe and echo them to `stdout'. */
+-     
+-     void
+-     read_from_pipe (int file)
+-     {
+-       FILE *stream;
+-       int c;
+-       stream = fdopen (file, "r");
+-       while ((c = fgetc (stream)) != EOF)
+-         putchar (c);
+-       fclose (stream);
+-     }
+-     
+-     /* Write some random text to the pipe. */
+-     
+-     void
+-     write_to_pipe (int file)
+-     {
+-       FILE *stream;
+-       stream = fdopen (file, "w");
+-       fprintf (stream, "hello, world!\n");
+-       fprintf (stream, "goodbye, world!\n");
+-       fclose (stream);
+-     }
+-     
+-     int
+-     main (void)
+-     {
+-       pid_t pid;
+-       int mypipe[2];
+-     /* Create the pipe. */
+-       if (pipe (mypipe))
+-         {
+-           fprintf (stderr, "Pipe failed.\n");
+-           return EXIT_FAILURE;
+-         }
+-     
+-       /* Create the child process. */
+-       pid = fork ();
+-       if (pid == (pid_t) 0)
+-         {
+-           /* This is the child process. */
+-           read_from_pipe (mypipe[0]);
+-           return EXIT_SUCCESS;
+-         }
+-       else if (pid < (pid_t) 0)
+-         {
+-           /* The fork failed. */
+-           fprintf (stderr, "Fork failed.\n");
+-           return EXIT_FAILURE;
+-         }
+-       else
+-         {
+-           /* This is the parent process. */
+-           write_to_pipe (mypipe[1]);
+-           return EXIT_SUCCESS;
+-         }
+-     }
+-
+-
+-File: libc.info,  Node: Pipe to a Subprocess,  Next: FIFO Special Files,  
Prev: Creating a Pipe,  Up: Pipes and FIFOs
+-
+-Pipe to a Subprocess
+-====================
+-
+-   A common use of pipes is to send data to or receive data from a
+-program being run as subprocess.  One way of doing this is by using a
+-combination of `pipe' (to create the pipe), `fork' (to create the
+-subprocess), `dup2' (to force the subprocess to use the pipe as its
+-standard input or output channel), and `exec' (to execute the new
+-program).  Or, you can use `popen' and `pclose'.
+-
+-   The advantage of using `popen' and `pclose' is that the interface is
+-much simpler and easier to use.  But it doesn't offer as much
+-flexibility as using the low-level functions directly.
+-
+- - Function: FILE * popen (const char *COMMAND, const char *MODE)
+-     The `popen' function is closely related to the `system' function;
+-     see *Note Running a Command::.  It executes the shell command
+-     COMMAND as a subprocess.  However, instead of waiting for the
+-     command to complete, it creates a pipe to the subprocess and
+-     returns a stream that corresponds to that pipe.
+-
+-     If you specify a MODE argument of `"r"', you can read from the
+-     stream to retrieve data from the standard output channel of the
+-     subprocess.  The subprocess inherits its standard input channel
+-     from the parent process.
+-
+-     Similarly, if you specify a MODE argument of `"w"', you can write
+-     to the stream to send data to the standard input channel of the
+-     subprocess.  The subprocess inherits its standard output channel
+-     from the parent process.
+-
+-     In the event of an error, `popen' returns a null pointer.  This
+-     might happen if the pipe or stream cannot be created, if the
+-     subprocess cannot be forked, or if the program cannot be executed.
+-
+- - Function: int pclose (FILE *STREAM)
+-     The `pclose' function is used to close a stream created by `popen'.
+-     It waits for the child process to terminate and returns its status
+-     value, as for the `system' function.
+-
+-   Here is an example showing how to use `popen' and `pclose' to filter
+-output through another program, in this case the paging program `more'.
+-
+-     #include <stdio.h>
+-     #include <stdlib.h>
+-     
+-     void
+-     write_data (FILE * stream)
+-     {
+-       int i;
+-       for (i = 0; i < 100; i++)
+-         fprintf (stream, "%d\n", i);
+-       if (ferror (stream))
+-         {
+-           fprintf (stderr, "Output to stream failed.\n");
+-           exit (EXIT_FAILURE);
+-         }
+-     }
+-     int
+-     main (void)
+-     {
+-       FILE *output;
+-     
+-       output = popen ("more", "w");
+-       if (!output)
+-         {
+-           fprintf (stderr, "Could not run more.\n");
+-           return EXIT_FAILURE;
+-         }
+-       write_data (output);
+-       pclose (output);
+-       return EXIT_SUCCESS;
+-     }
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-12 
glibc-2.0.1/manual/libc.info-12
+--- ../glibc-2.0.1/manual/libc.info-12 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-12    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1219 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: FIFO Special Files,  Next: Pipe Atomicity,  Prev: 
Pipe to a Subprocess,  Up: Pipes and FIFOs
+-
+-FIFO Special Files
+-==================
+-
+-   A FIFO special file is similar to a pipe, except that it is created
+-in a different way.  Instead of being an anonymous communications
+-channel, a FIFO special file is entered into the file system by calling
+-`mkfifo'.
+-
+-   Once you have created a FIFO special file in this way, any process
+-can open it for reading or writing, in the same way as an ordinary file.
+-However, it has to be open at both ends simultaneously before you can
+-proceed to do any input or output operations on it.  Opening a FIFO for
+-reading normally blocks until some other process opens the same FIFO for
+-writing, and vice versa.
+-
+-   The `mkfifo' function is declared in the header file `sys/stat.h'.
+-
+- - Function: int mkfifo (const char *FILENAME, mode_t MODE)
+-     The `mkfifo' function makes a FIFO special file with name
+-     FILENAME.  The MODE argument is used to set the file's
+-     permissions; see *Note Setting Permissions::.
+-
+-     The normal, successful return value from `mkfifo' is `0'.  In the
+-     case of an error, `-1' is returned.  In addition to the usual file
+-     name errors (*note File Name Errors::.), the following `errno'
+-     error conditions are defined for this function:
+-
+-    `EEXIST'
+-          The named file already exists.
+-
+-    `ENOSPC'
+-          The directory or file system cannot be extended.
+-
+-    `EROFS'
+-          The directory that would contain the file resides on a
+-          read-only file system.
+-
+-
+-File: libc.info,  Node: Pipe Atomicity,  Prev: FIFO Special Files,  Up: Pipes 
and FIFOs
+-
+-Atomicity of Pipe I/O
+-=====================
+-
+-   Reading or writing pipe data is "atomic" if the size of data written
+-is not greater than `PIPE_BUF'.  This means that the data transfer
+-seems to be an instantaneous unit, in that nothing else in the system
+-can observe a state in which it is partially complete.  Atomic I/O may
+-not begin right away (it may need to wait for buffer space or for data),
+-but once it does begin, it finishes immediately.
+-
+-   Reading or writing a larger amount of data may not be atomic; for
+-example, output data from other processes sharing the descriptor may be
+-interspersed.  Also, once `PIPE_BUF' characters have been written,
+-further writes will block until some characters are read.
+-
+-   *Note Limits for Files::, for information about the `PIPE_BUF'
+-parameter.
+-
+-
+-File: libc.info,  Node: Sockets,  Next: Low-Level Terminal Interface,  Prev: 
Pipes and FIFOs,  Up: Top
+-
+-Sockets
+-*******
+-
+-   This chapter describes the GNU facilities for interprocess
+-communication using sockets.
+-
+-   A "socket" is a generalized interprocess communication channel.
+-Like a pipe, a socket is represented as a file descriptor.  But, unlike
+-pipes, sockets support communication between unrelated processes, and
+-even between processes running on different machines that communicate
+-over a network.  Sockets are the primary means of communicating with
+-other machines; `telnet', `rlogin', `ftp', `talk', and the other
+-familiar network programs use sockets.
+-
+-   Not all operating systems support sockets.  In the GNU library, the
+-header file `sys/socket.h' exists regardless of the operating system,
+-and the socket functions always exist, but if the system does not
+-really support sockets, these functions always fail.
+-
+-   *Incomplete:* We do not currently document the facilities for
+-broadcast messages or for configuring Internet interfaces.
+-
+-* Menu:
+-
+-* Socket Concepts::   Basic concepts you need to know about.
+-* Communication Styles::Stream communication, datagrams, and other styles.
+-* Socket Addresses::  How socket names ("addresses") work.
+-* File Namespace::    Details about the file namespace.
+-* Internet Namespace::        Details about the Internet namespace.
+-* Misc Namespaces::   Other namespaces not documented fully here.
+-* Open/Close Sockets::  Creating sockets and destroying them.
+-* Connections::               Operations on sockets with connection state.
+-* Datagrams::         Operations on datagram sockets.
+-* Inetd::             Inetd is a daemon that starts servers on request.
+-                         The most convenient way to write a server
+-                         is to make it work with Inetd.
+-* Socket Options::    Miscellaneous low-level socket options.
+-* Networks Database::   Accessing the database of network names.
+-
+-
+-File: libc.info,  Node: Socket Concepts,  Next: Communication Styles,  Up: 
Sockets
+-
+-Socket Concepts
+-===============
+-
+-   When you create a socket, you must specify the style of communication
+-you want to use and the type of protocol that should implement it.  The
+-"communication style" of a socket defines the user-level semantics of
+-sending and receiving data on the socket.  Choosing a communication
+-style specifies the answers to questions such as these:
+-
+-   * *What are the units of data transmission?*  Some communication
+-     styles regard the data as a sequence of bytes, with no larger
+-     structure; others group the bytes into records (which are known in
+-     this context as "packets").
+-
+-   * *Can data be lost during normal operation?*  Some communication
+-     styles guarantee that all the data sent arrives in the order it was
+-     sent (barring system or network crashes); other styles occasionally
+-     lose data as a normal part of operation, and may sometimes deliver
+-     packets more than once or in the wrong order.
+-
+-     Designing a program to use unreliable communication styles usually
+-     involves taking precautions to detect lost or misordered packets
+-     and to retransmit data as needed.
+-
+-   * *Is communication entirely with one partner?*  Some communication
+-     styles are like a telephone call--you make a "connection" with one
+-     remote socket, and then exchange data freely.  Other styles are
+-     like mailing letters--you specify a destination address for each
+-     message you send.
+-
+-   You must also choose a "namespace" for naming the socket.  A socket
+-name ("address") is meaningful only in the context of a particular
+-namespace.  In fact, even the data type to use for a socket name may
+-depend on the namespace.  Namespaces are also called "domains", but we
+-avoid that word as it can be confused with other usage of the same
+-term.  Each namespace has a symbolic name that starts with `PF_'.  A
+-corresponding symbolic name starting with `AF_' designates the address
+-format for that namespace.
+-
+-   Finally you must choose the "protocol" to carry out the
+-communication.  The protocol determines what low-level mechanism is used
+-to transmit and receive data.  Each protocol is valid for a particular
+-namespace and communication style; a namespace is sometimes called a
+-"protocol family" because of this, which is why the namespace names
+-start with `PF_'.
+-
+-   The rules of a protocol apply to the data passing between two
+-programs, perhaps on different computers; most of these rules are
+-handled by the operating system, and you need not know about them.
+-What you do need to know about protocols is this:
+-
+-   * In order to have communication between two sockets, they must
+-     specify the *same* protocol.
+-
+-   * Each protocol is meaningful with particular style/namespace
+-     combinations and cannot be used with inappropriate combinations.
+-     For example, the TCP protocol fits only the byte stream style of
+-     communication and the Internet namespace.
+-
+-   * For each combination of style and namespace, there is a "default
+-     protocol" which you can request by specifying 0 as the protocol
+-     number.  And that's what you should normally do--use the default.
+-
+-
+-File: libc.info,  Node: Communication Styles,  Next: Socket Addresses,  Prev: 
Socket Concepts,  Up: Sockets
+-
+-Communication Styles
+-====================
+-
+-   The GNU library includes support for several different kinds of
+-sockets, each with different characteristics.  This section describes
+-the supported socket types.  The symbolic constants listed here are
+-defined in `sys/socket.h'.
+-
+- - Macro: int SOCK_STREAM
+-     The `SOCK_STREAM' style is like a pipe (*note Pipes and FIFOs::.);
+-     it operates over a connection with a particular remote socket, and
+-     transmits data reliably as a stream of bytes.
+-
+-     Use of this style is covered in detail in *Note Connections::.
+-
+- - Macro: int SOCK_DGRAM
+-     The `SOCK_DGRAM' style is used for sending individually-addressed
+-     packets, unreliably.  It is the diametrical opposite of
+-     `SOCK_STREAM'.
+-
+-     Each time you write data to a socket of this kind, that data
+-     becomes one packet.  Since `SOCK_DGRAM' sockets do not have
+-     connections, you must specify the recipient address with each
+-     packet.
+-
+-     The only guarantee that the system makes about your requests to
+-     transmit data is that it will try its best to deliver each packet
+-     you send.  It may succeed with the sixth packet after failing with
+-     the fourth and fifth packets; the seventh packet may arrive before
+-     the sixth, and may arrive a second time after the sixth.
+-
+-     The typical use for `SOCK_DGRAM' is in situations where it is
+-     acceptable to simply resend a packet if no response is seen in a
+-     reasonable amount of time.
+-
+-     *Note Datagrams::, for detailed information about how to use
+-     datagram sockets.
+-
+- - Macro: int SOCK_RAW
+-     This style provides access to low-level network protocols and
+-     interfaces.  Ordinary user programs usually have no need to use
+-     this style.
+-
+-
+-File: libc.info,  Node: Socket Addresses,  Next: File Namespace,  Prev: 
Communication Styles,  Up: Sockets
+-
+-Socket Addresses
+-================
+-
+-   The name of a socket is normally called an "address".  The functions
+-and symbols for dealing with socket addresses were named
+-inconsistently, sometimes using the term "name" and sometimes using
+-"address".  You can regard these terms as synonymous where sockets are
+-concerned.
+-
+-   A socket newly created with the `socket' function has no address.
+-Other processes can find it for communication only if you give it an
+-address.  We call this "binding" the address to the socket, and the way
+-to do it is with the `bind' function.
+-
+-   You need be concerned with the address of a socket if other processes
+-are to find it and start communicating with it.  You can specify an
+-address for other sockets, but this is usually pointless; the first time
+-you send data from a socket, or use it to initiate a connection, the
+-system assigns an address automatically if you have not specified one.
+-
+-   Occasionally a client needs to specify an address because the server
+-discriminates based on addresses; for example, the rsh and rlogin
+-protocols look at the client's socket address and don't bypass password
+-checking unless it is less than `IPPORT_RESERVED' (*note Ports::.).
+-
+-   The details of socket addresses vary depending on what namespace you
+-are using.  *Note File Namespace::, or *Note Internet Namespace::, for
+-specific information.
+-
+-   Regardless of the namespace, you use the same functions `bind' and
+-`getsockname' to set and examine a socket's address.  These functions
+-use a phony data type, `struct sockaddr *', to accept the address.  In
+-practice, the address lives in a structure of some other data type
+-appropriate to the address format you are using, but you cast its
+-address to `struct sockaddr *' when you pass it to `bind'.
+-
+-* Menu:
+-
+-* Address Formats::           About `struct sockaddr'.
+-* Setting Address::           Binding an address to a socket.
+-* Reading Address::           Reading the address of a socket.
+-
+-
+-File: libc.info,  Node: Address Formats,  Next: Setting Address,  Up: Socket 
Addresses
+-
+-Address Formats
+----------------
+-
+-   The functions `bind' and `getsockname' use the generic data type
+-`struct sockaddr *' to represent a pointer to a socket address.  You
+-can't use this data type effectively to interpret an address or
+-construct one; for that, you must use the proper data type for the
+-socket's namespace.
+-
+-   Thus, the usual practice is to construct an address in the proper
+-namespace-specific type, then cast a pointer to `struct sockaddr *'
+-when you call `bind' or `getsockname'.
+-
+-   The one piece of information that you can get from the `struct
+-sockaddr' data type is the "address format" designator which tells you
+-which data type to use to understand the address fully.
+-
+-   The symbols in this section are defined in the header file
+-`sys/socket.h'.
+-
+- - Date Type: struct sockaddr
+-     The `struct sockaddr' type itself has the following members:
+-
+-    `short int sa_family'
+-          This is the code for the address format of this address.  It
+-          identifies the format of the data which follows.
+-
+-    `char sa_data[14]'
+-          This is the actual socket address data, which is
+-          format-dependent.  Its length also depends on the format, and
+-          may well be more than 14.  The length 14 of `sa_data' is
+-          essentially arbitrary.
+-
+-   Each address format has a symbolic name which starts with `AF_'.
+-Each of them corresponds to a `PF_' symbol which designates the
+-corresponding namespace.  Here is a list of address format names:
+-
+-`AF_FILE'
+-     This designates the address format that goes with the file
+-     namespace.  (`PF_FILE' is the name of that namespace.)  *Note File
+-     Namespace Details::, for information about this address format.
+-
+-`AF_UNIX'
+-     This is a synonym for `AF_FILE', for compatibility.  (`PF_UNIX' is
+-     likewise a synonym for `PF_FILE'.)
+-
+-`AF_INET'
+-     This designates the address format that goes with the Internet
+-     namespace.  (`PF_INET' is the name of that namespace.) *Note
+-     Internet Address Format::.
+-
+-`AF_UNSPEC'
+-     This designates no particular address format.  It is used only in
+-     rare cases, such as to clear out the default destination address
+-     of a "connected" datagram socket.  *Note Sending Datagrams::.
+-
+-     The corresponding namespace designator symbol `PF_UNSPEC' exists
+-     for completeness, but there is no reason to use it in a program.
+-
+-   `sys/socket.h' defines symbols starting with `AF_' for many
+-different kinds of networks, all or most of which are not actually
+-implemented.  We will document those that really work, as we receive
+-information about how to use them.
+-
+-
+-File: libc.info,  Node: Setting Address,  Next: Reading Address,  Prev: 
Address Formats,  Up: Socket Addresses
+-
+-Setting the Address of a Socket
+--------------------------------
+-
+-   Use the `bind' function to assign an address to a socket.  The
+-prototype for `bind' is in the header file `sys/socket.h'.  For
+-examples of use, see *Note File Namespace::, or see *Note Inet
+-Example::.
+-
+- - Function: int bind (int SOCKET, struct sockaddr *ADDR, size_t LENGTH)
+-     The `bind' function assigns an address to the socket SOCKET.  The
+-     ADDR and LENGTH arguments specify the address; the detailed format
+-     of the address depends on the namespace.  The first part of the
+-     address is always the format designator, which specifies a
+-     namespace, and says that the address is in the format for that
+-     namespace.
+-
+-     The return value is `0' on success and `-1' on failure.  The
+-     following `errno' error conditions are defined for this function:
+-
+-    `EBADF'
+-          The SOCKET argument is not a valid file descriptor.
+-
+-    `ENOTSOCK'
+-          The descriptor SOCKET is not a socket.
+-
+-    `EADDRNOTAVAIL'
+-          The specified address is not available on this machine.
+-
+-    `EADDRINUSE'
+-          Some other socket is already using the specified address.
+-
+-    `EINVAL'
+-          The socket SOCKET already has an address.
+-
+-    `EACCES'
+-          You do not have permission to access the requested address.
+-          (In the Internet domain, only the super-user is allowed to
+-          specify a port number in the range 0 through
+-          `IPPORT_RESERVED' minus one; see *Note Ports::.)
+-
+-     Additional conditions may be possible depending on the particular
+-     namespace of the socket.
+-
+-
+-File: libc.info,  Node: Reading Address,  Prev: Setting Address,  Up: Socket 
Addresses
+-
+-Reading the Address of a Socket
+--------------------------------
+-
+-   Use the function `getsockname' to examine the address of an Internet
+-socket.  The prototype for this function is in the header file
+-`sys/socket.h'.
+-
+- - Function: int getsockname (int SOCKET, struct sockaddr *ADDR, size_t
+-          *LENGTH-PTR)
+-     The `getsockname' function returns information about the address
+-     of the socket SOCKET in the locations specified by the ADDR and
+-     LENGTH-PTR arguments.  Note that the LENGTH-PTR is a pointer; you
+-     should initialize it to be the allocation size of ADDR, and on
+-     return it contains the actual size of the address data.
+-
+-     The format of the address data depends on the socket namespace.
+-     The length of the information is usually fixed for a given
+-     namespace, so normally you can know exactly how much space is
+-     needed and can provide that much.  The usual practice is to
+-     allocate a place for the value using the proper data type for the
+-     socket's namespace, then cast its address to `struct sockaddr *'
+-     to pass it to `getsockname'.
+-
+-     The return value is `0' on success and `-1' on error.  The
+-     following `errno' error conditions are defined for this function:
+-
+-    `EBADF'
+-          The SOCKET argument is not a valid file descriptor.
+-
+-    `ENOTSOCK'
+-          The descriptor SOCKET is not a socket.
+-
+-    `ENOBUFS'
+-          There are not enough internal buffers available for the
+-          operation.
+-
+-   You can't read the address of a socket in the file namespace.  This
+-is consistent with the rest of the system; in general, there's no way to
+-find a file's name from a descriptor for that file.
+-
+-
+-File: libc.info,  Node: File Namespace,  Next: Internet Namespace,  Prev: 
Socket Addresses,  Up: Sockets
+-
+-The File Namespace
+-==================
+-
+-   This section describes the details of the file namespace, whose
+-symbolic name (required when you create a socket) is `PF_FILE'.
+-
+-* Menu:
+-
+-* Concepts: File Namespace Concepts.  What you need to understand.
+-* Details: File Namespace Details.    Address format, symbolic names, etc.
+-* Example: File Socket Example.               Example of creating a socket.
+-
+-
+-File: libc.info,  Node: File Namespace Concepts,  Next: File Namespace 
Details,  Up: File Namespace
+-
+-File Namespace Concepts
+------------------------
+-
+-   In the file namespace, socket addresses are file names.  You can
+-specify any file name you want as the address of the socket, but you
+-must have write permission on the directory containing it.  In order to
+-connect to a socket, you must have read permission for it.  It's common
+-to put these files in the `/tmp' directory.
+-
+-   One peculiarity of the file namespace is that the name is only used
+-when opening the connection; once that is over with, the address is not
+-meaningful and may not exist.
+-
+-   Another peculiarity is that you cannot connect to such a socket from
+-another machine-not even if the other machine shares the file system
+-which contains the name of the socket.  You can see the socket in a
+-directory listing, but connecting to it never succeeds.  Some programs
+-take advantage of this, such as by asking the client to send its own
+-process ID, and using the process IDs to distinguish between clients.
+-However, we recommend you not use this method in protocols you design,
+-as we might someday permit connections from other machines that mount
+-the same file systems.  Instead, send each new client an identifying
+-number if you want it to have one.
+-
+-   After you close a socket in the file namespace, you should delete the
+-file name from the file system.  Use `unlink' or `remove' to do this;
+-see *Note Deleting Files::.
+-
+-   The file namespace supports just one protocol for any communication
+-style; it is protocol number `0'.
+-
+-
+-File: libc.info,  Node: File Namespace Details,  Next: File Socket Example,  
Prev: File Namespace Concepts,  Up: File Namespace
+-
+-Details of File Namespace
+--------------------------
+-
+-   To create a socket in the file namespace, use the constant `PF_FILE'
+-as the NAMESPACE argument to `socket' or `socketpair'.  This constant
+-is defined in `sys/socket.h'.
+-
+- - Macro: int PF_FILE
+-     This designates the file namespace, in which socket addresses are
+-     file names, and its associated family of protocols.
+-
+- - Macro: int PF_UNIX
+-     This is a synonym for `PF_FILE', for compatibility's sake.
+-
+-   The structure for specifying socket names in the file namespace is
+-defined in the header file `sys/un.h':
+-
+- - Data Type: struct sockaddr_un
+-     This structure is used to specify file namespace socket addresses.
+-     It has the following members:
+-
+-    `short int sun_family'
+-          This identifies the address family or format of the socket
+-          address.  You should store the value `AF_FILE' to designate
+-          the file namespace.  *Note Socket Addresses::.
+-
+-    `char sun_path[108]'
+-          This is the file name to use.
+-
+-          *Incomplete:*  Why is 108 a magic number?  RMS suggests making
+-          this a zero-length array and tweaking the example following
+-          to use `alloca' to allocate an appropriate amount of storage
+-          based on the length of the filename.
+-
+-   You should compute the LENGTH parameter for a socket address in the
+-file namespace as the sum of the size of the `sun_family' component and
+-the string length (*not* the allocation size!) of the file name string.
+-
+-
+-File: libc.info,  Node: File Socket Example,  Prev: File Namespace Details,  
Up: File Namespace
+-
+-Example of File-Namespace Sockets
+----------------------------------
+-
+-   Here is an example showing how to create and name a socket in the
+-file namespace.
+-
+-     #include <stddef.h>
+-     #include <stdio.h>
+-     #include <errno.h>
+-     #include <stdlib.h>
+-     #include <sys/socket.h>
+-     #include <sys/un.h>
+-     
+-     int
+-     make_named_socket (const char *filename)
+-     {
+-       struct sockaddr_un name;
+-       int sock;
+-       size_t size;
+-     
+-       /* Create the socket. */
+-     
+-       sock = socket (PF_UNIX, SOCK_DGRAM, 0);
+-       if (sock < 0)
+-         {
+-           perror ("socket");
+-           exit (EXIT_FAILURE);
+-         }
+-     
+-       /* Bind a name to the socket. */
+-     
+-       name.sun_family = AF_FILE;
+-       strcpy (name.sun_path, filename);
+-     
+-       /* The size of the address is
+-          the offset of the start of the filename,
+-          plus its length,
+-          plus one for the terminating null byte. */
+-       size = (offsetof (struct sockaddr_un, sun_path)
+-               + strlen (name.sun_path) + 1);
+-     
+-       if (bind (sock, (struct sockaddr *) &name, size) < 0)
+-         {
+-           perror ("bind");
+-           exit (EXIT_FAILURE);
+-         }
+-     
+-       return sock;
+-     }
+-
+-
+-File: libc.info,  Node: Internet Namespace,  Next: Misc Namespaces,  Prev: 
File Namespace,  Up: Sockets
+-
+-The Internet Namespace
+-======================
+-
+-   This section describes the details the protocols and socket naming
+-conventions used in the Internet namespace.
+-
+-   To create a socket in the Internet namespace, use the symbolic name
+-`PF_INET' of this namespace as the NAMESPACE argument to `socket' or
+-`socketpair'.  This macro is defined in `sys/socket.h'.
+-
+- - Macro: int PF_INET
+-     This designates the Internet namespace and associated family of
+-     protocols.
+-
+-   A socket address for the Internet namespace includes the following
+-components:
+-
+-   * The address of the machine you want to connect to.  Internet
+-     addresses can be specified in several ways; these are discussed in
+-     *Note Internet Address Format::, *Note Host Addresses::, and *Note
+-     Host Names::.
+-
+-   * A port number for that machine.  *Note Ports::.
+-
+-   You must ensure that the address and port number are represented in a
+-canonical format called "network byte order".  *Note Byte Order::, for
+-information about this.
+-
+-* Menu:
+-
+-* Internet Address Format::     How socket addresses are specified in the
+-                                 Internet namespace.
+-* Host Addresses::            All about host addresses of internet host.
+-* Protocols Database::                Referring to protocols by name.
+-* Ports::                     Internet port numbers.
+-* Services Database::           Ports may have symbolic names.
+-* Byte Order::                        Different hosts may use different byte
+-                                 ordering conventions; you need to
+-                                 canonicalize host address and port number.
+-* Inet Example::              Putting it all together.
+-
+-
+-File: libc.info,  Node: Internet Address Format,  Next: Host Addresses,  Up: 
Internet Namespace
+-
+-Internet Socket Address Format
+-------------------------------
+-
+-   In the Internet namespace, a socket address consists of a host
+-address and a port on that host.  In addition, the protocol you choose
+-serves effectively as a part of the address because local port numbers
+-are meaningful only within a particular protocol.
+-
+-   The data type for representing socket addresses in the Internet
+-namespace is defined in the header file `netinet/in.h'.
+-
+- - Data Type: struct sockaddr_in
+-     This is the data type used to represent socket addresses in the
+-     Internet namespace.  It has the following members:
+-
+-    `short int sin_family'
+-          This identifies the address family or format of the socket
+-          address.  You should store the value of `AF_INET' in this
+-          member.  *Note Socket Addresses::.
+-
+-    `struct in_addr sin_addr'
+-          This is the Internet address of the host machine.  *Note Host
+-          Addresses::, and *Note Host Names::, for how to get a value
+-          to store here.
+-
+-    `unsigned short int sin_port'
+-          This is the port number.  *Note Ports::.
+-
+-   When you call `bind' or `getsockname', you should specify `sizeof
+-(struct sockaddr_in)' as the LENGTH parameter if you are using an
+-Internet namespace socket address.
+-
+-
+-File: libc.info,  Node: Host Addresses,  Next: Protocols Database,  Prev: 
Internet Address Format,  Up: Internet Namespace
+-
+-Host Addresses
+---------------
+-
+-   Each computer on the Internet has one or more "Internet addresses",
+-numbers which identify that computer among all those on the Internet.
+-Users typically write numeric host addresses as sequences of four
+-numbers, separated by periods, as in `128.52.46.32'.
+-
+-   Each computer also has one or more "host names", which are strings
+-of words separated by periods, as in `churchy.gnu.ai.mit.edu'.
+-
+-   Programs that let the user specify a host typically accept both
+-numeric addresses and host names.  But the program needs a numeric
+-address to open a connection; to use a host name, you must convert it
+-to the numeric address it stands for.
+-
+-* Menu:
+-
+-* Abstract Host Addresses::   What a host number consists of.
+-* Data type: Host Address Data Type.  Data type for a host number.
+-* Functions: Host Address Functions.  Functions to operate on them.
+-* Names: Host Names.          Translating host names to host numbers.
+-
+-
+-File: libc.info,  Node: Abstract Host Addresses,  Next: Host Address Data 
Type,  Up: Host Addresses
+-
+-Internet Host Addresses
+-.......................
+-
+-   Each computer on the Internet has one or more Internet addresses,
+-numbers which identify that computer among all those on the Internet.
+-
+-   An Internet host address is a number containing four bytes of data.
+-These are divided into two parts, a "network number" and a "local
+-network address number" within that network.  The network number
+-consists of the first one, two or three bytes; the rest of the bytes
+-are the local address.
+-
+-   Network numbers are registered with the Network Information Center
+-(NIC), and are divided into three classes--A, B, and C.  The local
+-network address numbers of individual machines are registered with the
+-administrator of the particular network.
+-
+-   Class A networks have single-byte numbers in the range 0 to 127.
+-There are only a small number of Class A networks, but they can each
+-support a very large number of hosts.  Medium-sized Class B networks
+-have two-byte network numbers, with the first byte in the range 128 to
+-191.  Class C networks are the smallest; they have three-byte network
+-numbers, with the first byte in the range 192-255.  Thus, the first 1,
+-2, or 3 bytes of an Internet address specifies a network.  The
+-remaining bytes of the Internet address specify the address within that
+-network.
+-
+-   The Class A network 0 is reserved for broadcast to all networks.  In
+-addition, the host number 0 within each network is reserved for
+-broadcast to all hosts in that network.
+-
+-   The Class A network 127 is reserved for loopback; you can always use
+-the Internet address `127.0.0.1' to refer to the host machine.
+-
+-   Since a single machine can be a member of multiple networks, it can
+-have multiple Internet host addresses.  However, there is never
+-supposed to be more than one machine with the same host address.
+-
+-   There are four forms of the "standard numbers-and-dots notation" for
+-Internet addresses:
+-
+-`A.B.C.D'
+-     This specifies all four bytes of the address individually.
+-
+-`A.B.C'
+-     The last part of the address, C, is interpreted as a 2-byte
+-     quantity.  This is useful for specifying host addresses in a Class
+-     B network with network address number `A.B'.
+-
+-`A.B'
+-     The last part of the address, C, is interpreted as a 3-byte
+-     quantity.  This is useful for specifying host addresses in a Class
+-     A network with network address number A.
+-
+-`A'
+-     If only one part is given, this corresponds directly to the host
+-     address number.
+-
+-   Within each part of the address, the usual C conventions for
+-specifying the radix apply.  In other words, a leading `0x' or `0X'
+-implies hexadecimal radix; a leading `0' implies octal; and otherwise
+-decimal radix is assumed.
+-
+-
+-File: libc.info,  Node: Host Address Data Type,  Next: Host Address 
Functions,  Prev: Abstract Host Addresses,  Up: Host Addresses
+-
+-Host Address Data Type
+-......................
+-
+-   Internet host addresses are represented in some contexts as integers
+-(type `unsigned long int').  In other contexts, the integer is packaged
+-inside a structure of type `struct in_addr'.  It would be better if the
+-usage were made consistent, but it is not hard to extract the integer
+-from the structure or put the integer into a structure.
+-
+-   The following basic definitions for Internet addresses appear in the
+-header file `netinet/in.h':
+-
+- - Data Type: struct in_addr
+-     This data type is used in certain contexts to contain an Internet
+-     host address.  It has just one field, named `s_addr', which
+-     records the host address number as an `unsigned long int'.
+-
+- - Macro: unsigned long int INADDR_LOOPBACK
+-     You can use this constant to stand for "the address of this
+-     machine," instead of finding its actual address.  It is the
+-     Internet address `127.0.0.1', which is usually called `localhost'.
+-     This special constant saves you the trouble of looking up the
+-     address of your own machine.  Also, the system usually implements
+-     `INADDR_LOOPBACK' specially, avoiding any network traffic for the
+-     case of one machine talking to itself.
+-
+- - Macro: unsigned long int INADDR_ANY
+-     You can use this constant to stand for "any incoming address," when
+-     binding to an address.  *Note Setting Address::.  This is the usual
+-     address to give in the `sin_addr' member of `struct sockaddr_in'
+-     when you want to accept Internet connections.
+-
+- - Macro: unsigned long int INADDR_BROADCAST
+-     This constant is the address you use to send a broadcast message.
+-
+- - Macro: unsigned long int INADDR_NONE
+-     This constant is returned by some functions to indicate an error.
+-
+-
+-File: libc.info,  Node: Host Address Functions,  Next: Host Names,  Prev: 
Host Address Data Type,  Up: Host Addresses
+-
+-Host Address Functions
+-......................
+-
+-   These additional functions for manipulating Internet addresses are
+-declared in `arpa/inet.h'.  They represent Internet addresses in
+-network byte order; they represent network numbers and
+-local-address-within-network numbers in host byte order.  *Note Byte
+-Order::, for an explanation of network and host byte order.
+-
+- - Function: int inet_aton (const char *NAME, struct in_addr *ADDR)
+-     This function converts the Internet host address NAME from the
+-     standard numbers-and-dots notation into binary data and stores it
+-     in the `struct in_addr' that ADDR points to.  `inet_aton' returns
+-     nonzero if the address is valid, zero if not.
+-
+- - Function: unsigned long int inet_addr (const char *NAME)
+-     This function converts the Internet host address NAME from the
+-     standard numbers-and-dots notation into binary data.  If the input
+-     is not valid, `inet_addr' returns `INADDR_NONE'.  This is an
+-     obsolete interface to `inet_aton', described immediately above; it
+-     is obsolete because `INADDR_NONE' is a valid address
+-     (255.255.255.255), and `inet_aton' provides a cleaner way to
+-     indicate error return.
+-
+- - Function: unsigned long int inet_network (const char *NAME)
+-     This function extracts the network number from the address NAME,
+-     given in the standard numbers-and-dots notation.  If the input is
+-     not valid, `inet_network' returns `-1'.
+-
+- - Function: char * inet_ntoa (struct in_addr ADDR)
+-     This function converts the Internet host address ADDR to a string
+-     in the standard numbers-and-dots notation.  The return value is a
+-     pointer into a statically-allocated buffer.  Subsequent calls will
+-     overwrite the same buffer, so you should copy the string if you
+-     need to save it.
+-
+- - Function: struct in_addr inet_makeaddr (int NET, int LOCAL)
+-     This function makes an Internet host address by combining the
+-     network number NET with the local-address-within-network number
+-     LOCAL.
+-
+- - Function: int inet_lnaof (struct in_addr ADDR)
+-     This function returns the local-address-within-network part of the
+-     Internet host address ADDR.
+-
+- - Function: int inet_netof (struct in_addr ADDR)
+-     This function returns the network number part of the Internet host
+-     address ADDR.
+-
+-
+-File: libc.info,  Node: Host Names,  Prev: Host Address Functions,  Up: Host 
Addresses
+-
+-Host Names
+-..........
+-
+-   Besides the standard numbers-and-dots notation for Internet
+-addresses, you can also refer to a host by a symbolic name.  The
+-advantage of a symbolic name is that it is usually easier to remember.
+-For example, the machine with Internet address `128.52.46.32' is also
+-known as `churchy.gnu.ai.mit.edu'; and other machines in the
+-`gnu.ai.mit.edu' domain can refer to it simply as `churchy'.
+-
+-   Internally, the system uses a database to keep track of the mapping
+-between host names and host numbers.  This database is usually either
+-the file `/etc/hosts' or an equivalent provided by a name server.  The
+-functions and other symbols for accessing this database are declared in
+-`netdb.h'.  They are BSD features, defined unconditionally if you
+-include `netdb.h'.
+-
+- - Data Type: struct hostent
+-     This data type is used to represent an entry in the hosts
+-     database.  It has the following members:
+-
+-    `char *h_name'
+-          This is the "official" name of the host.
+-
+-    `char **h_aliases'
+-          These are alternative names for the host, represented as a
+-          null-terminated vector of strings.
+-
+-    `int h_addrtype'
+-          This is the host address type; in practice, its value is
+-          always `AF_INET'.  In principle other kinds of addresses
+-          could be represented in the data base as well as Internet
+-          addresses; if this were done, you might find a value in this
+-          field other than `AF_INET'.  *Note Socket Addresses::.
+-
+-    `int h_length'
+-          This is the length, in bytes, of each address.
+-
+-    `char **h_addr_list'
+-          This is the vector of addresses for the host.  (Recall that
+-          the host might be connected to multiple networks and have
+-          different addresses on each one.)  The vector is terminated
+-          by a null pointer.
+-
+-    `char *h_addr'
+-          This is a synonym for `h_addr_list[0]'; in other words, it is
+-          the first host address.
+-
+-   As far as the host database is concerned, each address is just a
+-block of memory `h_length' bytes long.  But in other contexts there is
+-an implicit assumption that you can convert this to a `struct in_addr'
+-or an `unsigned long int'.  Host addresses in a `struct hostent'
+-structure are always given in network byte order; see *Note Byte
+-Order::.
+-
+-   You can use `gethostbyname' or `gethostbyaddr' to search the hosts
+-database for information about a particular host.  The information is
+-returned in a statically-allocated structure; you must copy the
+-information if you need to save it across calls.
+-
+- - Function: struct hostent * gethostbyname (const char *NAME)
+-     The `gethostbyname' function returns information about the host
+-     named NAME.  If the lookup fails, it returns a null pointer.
+-
+- - Function: struct hostent * gethostbyaddr (const char *ADDR, int
+-          LENGTH, int FORMAT)
+-     The `gethostbyaddr' function returns information about the host
+-     with Internet address ADDR.  The LENGTH argument is the size (in
+-     bytes) of the address at ADDR.  FORMAT specifies the address
+-     format; for an Internet address, specify a value of `AF_INET'.
+-
+-     If the lookup fails, `gethostbyaddr' returns a null pointer.
+-
+-   If the name lookup by `gethostbyname' or `gethostbyaddr' fails, you
+-can find out the reason by looking at the value of the variable
+-`h_errno'.  (It would be cleaner design for these functions to set
+-`errno', but use of `h_errno' is compatible with other systems.)
+-Before using `h_errno', you must declare it like this:
+-
+-     extern int h_errno;
+-
+-   Here are the error codes that you may find in `h_errno':
+-
+-`HOST_NOT_FOUND'
+-     No such host is known in the data base.
+-
+-`TRY_AGAIN'
+-     This condition happens when the name server could not be
+-     contacted.  If you try again later, you may succeed then.
+-
+-`NO_RECOVERY'
+-     A non-recoverable error occurred.
+-
+-`NO_ADDRESS'
+-     The host database contains an entry for the name, but it doesn't
+-     have an associated Internet address.
+-
+-   You can also scan the entire hosts database one entry at a time using
+-`sethostent', `gethostent', and `endhostent'.  Be careful in using
+-these functions, because they are not reentrant.
+-
+- - Function: void sethostent (int STAYOPEN)
+-     This function opens the hosts database to begin scanning it.  You
+-     can then call `gethostent' to read the entries.
+-
+-     If the STAYOPEN argument is nonzero, this sets a flag so that
+-     subsequent calls to `gethostbyname' or `gethostbyaddr' will not
+-     close the database (as they usually would).  This makes for more
+-     efficiency if you call those functions several times, by avoiding
+-     reopening the database for each call.
+-
+- - Function: struct hostent * gethostent ()
+-     This function returns the next entry in the hosts database.  It
+-     returns a null pointer if there are no more entries.
+-
+- - Function: void endhostent ()
+-     This function closes the hosts database.
+-
+-
+-File: libc.info,  Node: Ports,  Next: Services Database,  Prev: Protocols 
Database,  Up: Internet Namespace
+-
+-Internet Ports
+---------------
+-
+-   A socket address in the Internet namespace consists of a machine's
+-Internet address plus a "port number" which distinguishes the sockets
+-on a given machine (for a given protocol).  Port numbers range from 0
+-to 65,535.
+-
+-   Port numbers less than `IPPORT_RESERVED' are reserved for standard
+-servers, such as `finger' and `telnet'.  There is a database that keeps
+-track of these, and you can use the `getservbyname' function to map a
+-service name onto a port number; see *Note Services Database::.
+-
+-   If you write a server that is not one of the standard ones defined in
+-the database, you must choose a port number for it.  Use a number
+-greater than `IPPORT_USERRESERVED'; such numbers are reserved for
+-servers and won't ever be generated automatically by the system.
+-Avoiding conflicts with servers being run by other users is up to you.
+-
+-   When you use a socket without specifying its address, the system
+-generates a port number for it.  This number is between
+-`IPPORT_RESERVED' and `IPPORT_USERRESERVED'.
+-
+-   On the Internet, it is actually legitimate to have two different
+-sockets with the same port number, as long as they never both try to
+-communicate with the same socket address (host address plus port
+-number).  You shouldn't duplicate a port number except in special
+-circumstances where a higher-level protocol requires it.  Normally, the
+-system won't let you do it; `bind' normally insists on distinct port
+-numbers.  To reuse a port number, you must set the socket option
+-`SO_REUSEADDR'.  *Note Socket-Level Options::.
+-
+-   These macros are defined in the header file `netinet/in.h'.
+-
+- - Macro: int IPPORT_RESERVED
+-     Port numbers less than `IPPORT_RESERVED' are reserved for
+-     superuser use.
+-
+- - Macro: int IPPORT_USERRESERVED
+-     Port numbers greater than or equal to `IPPORT_USERRESERVED' are
+-     reserved for explicit use; they will never be allocated
+-     automatically.
+-
+-
+-File: libc.info,  Node: Services Database,  Next: Byte Order,  Prev: Ports,  
Up: Internet Namespace
+-
+-The Services Database
+----------------------
+-
+-   The database that keeps track of "well-known" services is usually
+-either the file `/etc/services' or an equivalent from a name server.
+-You can use these utilities, declared in `netdb.h', to access the
+-services database.
+-
+- - Data Type: struct servent
+-     This data type holds information about entries from the services
+-     database.  It has the following members:
+-
+-    `char *s_name'
+-          This is the "official" name of the service.
+-
+-    `char **s_aliases'
+-          These are alternate names for the service, represented as an
+-          array of strings.  A null pointer terminates the array.
+-
+-    `int s_port'
+-          This is the port number for the service.  Port numbers are
+-          given in network byte order; see *Note Byte Order::.
+-
+-    `char *s_proto'
+-          This is the name of the protocol to use with this service.
+-          *Note Protocols Database::.
+-
+-   To get information about a particular service, use the
+-`getservbyname' or `getservbyport' functions.  The information is
+-returned in a statically-allocated structure; you must copy the
+-information if you need to save it across calls.
+-
+- - Function: struct servent * getservbyname (const char *NAME, const
+-          char *PROTO)
+-     The `getservbyname' function returns information about the service
+-     named NAME using protocol PROTO.  If it can't find such a service,
+-     it returns a null pointer.
+-
+-     This function is useful for servers as well as for clients; servers
+-     use it to determine which port they should listen on (*note
+-     Listening::.).
+-
+- - Function: struct servent * getservbyport (int PORT, const char
+-          *PROTO)
+-     The `getservbyport' function returns information about the service
+-     at port PORT using protocol PROTO.  If it can't find such a
+-     service, it returns a null pointer.
+-
+-   You can also scan the services database using `setservent',
+-`getservent', and `endservent'.  Be careful in using these functions,
+-because they are not reentrant.
+-
+- - Function: void setservent (int STAYOPEN)
+-     This function opens the services database to begin scanning it.
+-
+-     If the STAYOPEN argument is nonzero, this sets a flag so that
+-     subsequent calls to `getservbyname' or `getservbyport' will not
+-     close the database (as they usually would).  This makes for more
+-     efficiency if you call those functions several times, by avoiding
+-     reopening the database for each call.
+-
+- - Function: struct servent * getservent (void)
+-     This function returns the next entry in the services database.  If
+-     there are no more entries, it returns a null pointer.
+-
+- - Function: void endservent (void)
+-     This function closes the services database.
+-
+-
+-File: libc.info,  Node: Byte Order,  Next: Inet Example,  Prev: Services 
Database,  Up: Internet Namespace
+-
+-Byte Order Conversion
+----------------------
+-
+-   Different kinds of computers use different conventions for the
+-ordering of bytes within a word.  Some computers put the most
+-significant byte within a word first (this is called "big-endian"
+-order), and others put it last ("little-endian" order).
+-
+-   So that machines with different byte order conventions can
+-communicate, the Internet protocols specify a canonical byte order
+-convention for data transmitted over the network.  This is known as the
+-"network byte order".
+-
+-   When establishing an Internet socket connection, you must make sure
+-that the data in the `sin_port' and `sin_addr' members of the
+-`sockaddr_in' structure are represented in the network byte order.  If
+-you are encoding integer data in the messages sent through the socket,
+-you should convert this to network byte order too.  If you don't do
+-this, your program may fail when running on or talking to other kinds
+-of machines.
+-
+-   If you use `getservbyname' and `gethostbyname' or `inet_addr' to get
+-the port number and host address, the values are already in the network
+-byte order, and you can copy them directly into the `sockaddr_in'
+-structure.
+-
+-   Otherwise, you have to convert the values explicitly.  Use `htons'
+-and `ntohs' to convert values for the `sin_port' member.  Use `htonl'
+-and `ntohl' to convert values for the `sin_addr' member.  (Remember,
+-`struct in_addr' is equivalent to `unsigned long int'.)  These
+-functions are declared in `netinet/in.h'.
+-
+- - Function: unsigned short int htons (unsigned short int HOSTSHORT)
+-     This function converts the `short' integer HOSTSHORT from host
+-     byte order to network byte order.
+-
+- - Function: unsigned short int ntohs (unsigned short int NETSHORT)
+-     This function converts the `short' integer NETSHORT from network
+-     byte order to host byte order.
+-
+- - Function: unsigned long int htonl (unsigned long int HOSTLONG)
+-     This function converts the `long' integer HOSTLONG from host byte
+-     order to network byte order.
+-
+- - Function: unsigned long int ntohl (unsigned long int NETLONG)
+-     This function converts the `long' integer NETLONG from network
+-     byte order to host byte order.
+-
+-
+-File: libc.info,  Node: Protocols Database,  Next: Ports,  Prev: Host 
Addresses,  Up: Internet Namespace
+-
+-Protocols Database
+-------------------
+-
+-   The communications protocol used with a socket controls low-level
+-details of how data is exchanged.  For example, the protocol implements
+-things like checksums to detect errors in transmissions, and routing
+-instructions for messages.  Normal user programs have little reason to
+-mess with these details directly.
+-
+-   The default communications protocol for the Internet namespace
+-depends on the communication style.  For stream communication, the
+-default is TCP ("transmission control protocol").  For datagram
+-communication, the default is UDP ("user datagram protocol").  For
+-reliable datagram communication, the default is RDP ("reliable datagram
+-protocol").  You should nearly always use the default.
+-
+-   Internet protocols are generally specified by a name instead of a
+-number.  The network protocols that a host knows about are stored in a
+-database.  This is usually either derived from the file
+-`/etc/protocols', or it may be an equivalent provided by a name server.
+-You look up the protocol number associated with a named protocol in
+-the database using the `getprotobyname' function.
+-
+-   Here are detailed descriptions of the utilities for accessing the
+-protocols database.  These are declared in `netdb.h'.
+-
+- - Data Type: struct protoent
+-     This data type is used to represent entries in the network
+-     protocols database.  It has the following members:
+-
+-    `char *p_name'
+-          This is the official name of the protocol.
+-
+-    `char **p_aliases'
+-          These are alternate names for the protocol, specified as an
+-          array of strings.  The last element of the array is a null
+-          pointer.
+-
+-    `int p_proto'
+-          This is the protocol number (in host byte order); use this
+-          member as the PROTOCOL argument to `socket'.
+-
+-   You can use `getprotobyname' and `getprotobynumber' to search the
+-protocols database for a specific protocol.  The information is
+-returned in a statically-allocated structure; you must copy the
+-information if you need to save it across calls.
+-
+- - Function: struct protoent * getprotobyname (const char *NAME)
+-     The `getprotobyname' function returns information about the
+-     network protocol named NAME.  If there is no such protocol, it
+-     returns a null pointer.
+-
+- - Function: struct protoent * getprotobynumber (int PROTOCOL)
+-     The `getprotobynumber' function returns information about the
+-     network protocol with number PROTOCOL.  If there is no such
+-     protocol, it returns a null pointer.
+-
+-   You can also scan the whole protocols database one protocol at a
+-time by using `setprotoent', `getprotoent', and `endprotoent'.  Be
+-careful in using these functions, because they are not reentrant.
+-
+- - Function: void setprotoent (int STAYOPEN)
+-     This function opens the protocols database to begin scanning it.
+-
+-     If the STAYOPEN argument is nonzero, this sets a flag so that
+-     subsequent calls to `getprotobyname' or `getprotobynumber' will
+-     not close the database (as they usually would).  This makes for
+-     more efficiency if you call those functions several times, by
+-     avoiding reopening the database for each call.
+-
+- - Function: struct protoent * getprotoent (void)
+-     This function returns the next entry in the protocols database.  It
+-     returns a null pointer if there are no more entries.
+-
+- - Function: void endprotoent (void)
+-     This function closes the protocols database.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-13 
glibc-2.0.1/manual/libc.info-13
+--- ../glibc-2.0.1/manual/libc.info-13 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-13    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1376 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Inet Example,  Prev: Byte Order,  Up: Internet 
Namespace
+-
+-Internet Socket Example
+------------------------
+-
+-   Here is an example showing how to create and name a socket in the
+-Internet namespace.  The newly created socket exists on the machine that
+-the program is running on.  Rather than finding and using the machine's
+-Internet address, this example specifies `INADDR_ANY' as the host
+-address; the system replaces that with the machine's actual address.
+-
+-     #include <stdio.h>
+-     #include <stdlib.h>
+-     #include <sys/socket.h>
+-     #include <netinet/in.h>
+-     
+-     int
+-     make_socket (unsigned short int port)
+-     {
+-       int sock;
+-       struct sockaddr_in name;
+-     
+-       /* Create the socket. */
+-       sock = socket (PF_INET, SOCK_STREAM, 0);
+-       if (sock < 0)
+-         {
+-           perror ("socket");
+-           exit (EXIT_FAILURE);
+-         }
+-     
+-       /* Give the socket a name. */
+-       name.sin_family = AF_INET;
+-       name.sin_port = htons (port);
+-       name.sin_addr.s_addr = htonl (INADDR_ANY);
+-       if (bind (sock, (struct sockaddr *) &name, sizeof (name)) < 0)
+-         {
+-           perror ("bind");
+-           exit (EXIT_FAILURE);
+-         }
+-     
+-       return sock;
+-     }
+-
+-   Here is another example, showing how you can fill in a `sockaddr_in'
+-structure, given a host name string and a port number:
+-
+-     #include <stdio.h>
+-     #include <stdlib.h>
+-     #include <sys/socket.h>
+-     #include <netinet/in.h>
+-     #include <netdb.h>
+-     
+-     void
+-     init_sockaddr (struct sockaddr_in *name,
+-                    const char *hostname,
+-                    unsigned short int port)
+-     {
+-       struct hostent *hostinfo;
+-     
+-       name->sin_family = AF_INET;
+-       name->sin_port = htons (port);
+-       hostinfo = gethostbyname (hostname);
+-       if (hostinfo == NULL)
+-         {
+-           fprintf (stderr, "Unknown host %s.\n", hostname);
+-           exit (EXIT_FAILURE);
+-         }
+-       name->sin_addr = *(struct in_addr *) hostinfo->h_addr;
+-     }
+-
+-
+-File: libc.info,  Node: Misc Namespaces,  Next: Open/Close Sockets,  Prev: 
Internet Namespace,  Up: Sockets
+-
+-Other Namespaces
+-================
+-
+-   Certain other namespaces and associated protocol families are
+-supported but not documented yet because they are not often used.
+-`PF_NS' refers to the Xerox Network Software protocols.  `PF_ISO' stands
+-for Open Systems Interconnect.  `PF_CCITT' refers to protocols from
+-CCITT.  `socket.h' defines these symbols and others naming protocols
+-not actually implemented.
+-
+-   `PF_IMPLINK' is used for communicating between hosts and Internet
+-Message Processors.  For information on this, and on `PF_ROUTE', an
+-occasionally-used local area routing protocol, see the GNU Hurd Manual
+-(to appear in the future).
+-
+-
+-File: libc.info,  Node: Open/Close Sockets,  Next: Connections,  Prev: Misc 
Namespaces,  Up: Sockets
+-
+-Opening and Closing Sockets
+-===========================
+-
+-   This section describes the actual library functions for opening and
+-closing sockets.  The same functions work for all namespaces and
+-connection styles.
+-
+-* Menu:
+-
+-* Creating a Socket::           How to open a socket.
+-* Closing a Socket::            How to close a socket.
+-* Socket Pairs::                These are created like pipes.
+-
+-
+-File: libc.info,  Node: Creating a Socket,  Next: Closing a Socket,  Up: 
Open/Close Sockets
+-
+-Creating a Socket
+------------------
+-
+-   The primitive for creating a socket is the `socket' function,
+-declared in `sys/socket.h'.
+-
+- - Function: int socket (int NAMESPACE, int STYLE, int PROTOCOL)
+-     This function creates a socket and specifies communication style
+-     STYLE, which should be one of the socket styles listed in *Note
+-     Communication Styles::.  The NAMESPACE argument specifies the
+-     namespace; it must be `PF_FILE' (*note File Namespace::.) or
+-     `PF_INET' (*note Internet Namespace::.).  PROTOCOL designates the
+-     specific protocol (*note Socket Concepts::.); zero is usually
+-     right for PROTOCOL.
+-
+-     The return value from `socket' is the file descriptor for the new
+-     socket, or `-1' in case of error.  The following `errno' error
+-     conditions are defined for this function:
+-
+-    `EPROTONOSUPPORT'
+-          The PROTOCOL or STYLE is not supported by the NAMESPACE
+-          specified.
+-
+-    `EMFILE'
+-          The process already has too many file descriptors open.
+-
+-    `ENFILE'
+-          The system already has too many file descriptors open.
+-
+-    `EACCESS'
+-          The process does not have privilege to create a socket of the
+-          specified STYLE or PROTOCOL.
+-
+-    `ENOBUFS'
+-          The system ran out of internal buffer space.
+-
+-     The file descriptor returned by the `socket' function supports both
+-     read and write operations.  But, like pipes, sockets do not
+-     support file positioning operations.
+-
+-   For examples of how to call the `socket' function, see *Note File
+-Namespace::, or *Note Inet Example::.
+-
+-
+-File: libc.info,  Node: Closing a Socket,  Next: Socket Pairs,  Prev: 
Creating a Socket,  Up: Open/Close Sockets
+-
+-Closing a Socket
+-----------------
+-
+-   When you are finished using a socket, you can simply close its file
+-descriptor with `close'; see *Note Opening and Closing Files::.  If
+-there is still data waiting to be transmitted over the connection,
+-normally `close' tries to complete this transmission.  You can control
+-this behavior using the `SO_LINGER' socket option to specify a timeout
+-period; see *Note Socket Options::.
+-
+-   You can also shut down only reception or only transmission on a
+-connection by calling `shutdown', which is declared in `sys/socket.h'.
+-
+- - Function: int shutdown (int SOCKET, int HOW)
+-     The `shutdown' function shuts down the connection of socket
+-     SOCKET.  The argument HOW specifies what action to perform:
+-
+-    `0'
+-          Stop receiving data for this socket.  If further data arrives,
+-          reject it.
+-
+-    `1'
+-          Stop trying to transmit data from this socket.  Discard any
+-          data waiting to be sent.  Stop looking for acknowledgement of
+-          data already sent; don't retransmit it if it is lost.
+-
+-    `2'
+-          Stop both reception and transmission.
+-
+-     The return value is `0' on success and `-1' on failure.  The
+-     following `errno' error conditions are defined for this function:
+-
+-    `EBADF'
+-          SOCKET is not a valid file descriptor.
+-
+-    `ENOTSOCK'
+-          SOCKET is not a socket.
+-
+-    `ENOTCONN'
+-          SOCKET is not connected.
+-
+-
+-File: libc.info,  Node: Socket Pairs,  Prev: Closing a Socket,  Up: 
Open/Close Sockets
+-
+-Socket Pairs
+-------------
+-
+-   A "socket pair" consists of a pair of connected (but unnamed)
+-sockets.  It is very similar to a pipe and is used in much the same
+-way.  Socket pairs are created with the `socketpair' function, declared
+-in `sys/socket.h'.  A socket pair is much like a pipe; the main
+-difference is that the socket pair is bidirectional, whereas the pipe
+-has one input-only end and one output-only end (*note Pipes and
+-FIFOs::.).
+-
+- - Function: int socketpair (int NAMESPACE, int STYLE, int PROTOCOL,
+-          int FILEDES[2])
+-     This function creates a socket pair, returning the file
+-     descriptors in `FILEDES[0]' and `FILEDES[1]'.  The socket pair is
+-     a full-duplex communications channel, so that both reading and
+-     writing may be performed at either end.
+-
+-     The NAMESPACE, STYLE, and PROTOCOL arguments are interpreted as
+-     for the `socket' function.  STYLE should be one of the
+-     communication styles listed in *Note Communication Styles::.  The
+-     NAMESPACE argument specifies the namespace, which must be
+-     `AF_FILE' (*note File Namespace::.); PROTOCOL specifies the
+-     communications protocol, but zero is the only meaningful value.
+-
+-     If STYLE specifies a connectionless communication style, then the
+-     two sockets you get are not *connected*, strictly speaking, but
+-     each of them knows the other as the default destination address,
+-     so they can send packets to each other.
+-
+-     The `socketpair' function returns `0' on success and `-1' on
+-     failure.  The following `errno' error conditions are defined for
+-     this function:
+-
+-    `EMFILE'
+-          The process has too many file descriptors open.
+-
+-    `EAFNOSUPPORT'
+-          The specified namespace is not supported.
+-
+-    `EPROTONOSUPPORT'
+-          The specified protocol is not supported.
+-
+-    `EOPNOTSUPP'
+-          The specified protocol does not support the creation of
+-          socket pairs.
+-
+-
+-File: libc.info,  Node: Connections,  Next: Datagrams,  Prev: Open/Close 
Sockets,  Up: Sockets
+-
+-Using Sockets with Connections
+-==============================
+-
+-   The most common communication styles involve making a connection to a
+-particular other socket, and then exchanging data with that socket over
+-and over.  Making a connection is asymmetric; one side (the "client")
+-acts to request a connection, while the other side (the "server") makes
+-a socket and waits for the connection request.
+-
+-* Menu:
+-
+-* Connecting::             What the client program must do.
+-* Listening::              How a server program waits for requests.
+-* Accepting Connections::    What the server does when it gets a request.
+-* Who is Connected::       Getting the address of the
+-                              other side of a connection.
+-* Transferring Data::        How to send and receive data.
+-* Byte Stream Example::            An example program: a client for 
communicating
+-                            over a byte stream socket in the Internet 
namespace.
+-* Server Example::         A corresponding server program.
+-* Out-of-Band Data::         This is an advanced feature.
+-
+-
+-File: libc.info,  Node: Connecting,  Next: Listening,  Up: Connections
+-
+-Making a Connection
+--------------------
+-
+-   In making a connection, the client makes a connection while the
+-server waits for and accepts the connection.  Here we discuss what the
+-client program must do, using the `connect' function, which is declared
+-in `sys/socket.h'.
+-
+- - Function: int connect (int SOCKET, struct sockaddr *ADDR, size_t
+-          LENGTH)
+-     The `connect' function initiates a connection from the socket with
+-     file descriptor SOCKET to the socket whose address is specified by
+-     the ADDR and LENGTH arguments.  (This socket is typically on
+-     another machine, and it must be already set up as a server.)
+-     *Note Socket Addresses::, for information about how these
+-     arguments are interpreted.
+-
+-     Normally, `connect' waits until the server responds to the request
+-     before it returns.  You can set nonblocking mode on the socket
+-     SOCKET to make `connect' return immediately without waiting for
+-     the response.  *Note File Status Flags::, for information about
+-     nonblocking mode.
+-
+-     The normal return value from `connect' is `0'.  If an error
+-     occurs, `connect' returns `-1'.  The following `errno' error
+-     conditions are defined for this function:
+-
+-    `EBADF'
+-          The socket SOCKET is not a valid file descriptor.
+-
+-    `ENOTSOCK'
+-          File descriptor SOCKET is not a socket.
+-
+-    `EADDRNOTAVAIL'
+-          The specified address is not available on the remote machine.
+-
+-    `EAFNOSUPPORT'
+-          The namespace of the ADDR is not supported by this socket.
+-
+-    `EISCONN'
+-          The socket SOCKET is already connected.
+-
+-    `ETIMEDOUT'
+-          The attempt to establish the connection timed out.
+-
+-    `ECONNREFUSED'
+-          The server has actively refused to establish the connection.
+-
+-    `ENETUNREACH'
+-          The network of the given ADDR isn't reachable from this host.
+-
+-    `EADDRINUSE'
+-          The socket address of the given ADDR is already in use.
+-
+-    `EINPROGRESS'
+-          The socket SOCKET is non-blocking and the connection could
+-          not be established immediately.  You can determine when the
+-          connection is completely established with `select'; *note
+-          Waiting for I/O::..  Another `connect' call on the same
+-          socket, before the connection is completely established, will
+-          fail with `EALREADY'.
+-
+-    `EALREADY'
+-          The socket SOCKET is non-blocking and already has a pending
+-          connection in progress (see `EINPROGRESS' above).
+-
+-
+-File: libc.info,  Node: Listening,  Next: Accepting Connections,  Prev: 
Connecting,  Up: Connections
+-
+-Listening for Connections
+--------------------------
+-
+-   Now let us consider what the server process must do to accept
+-connections on a socket.  First it must use the `listen' function to
+-enable connection requests on the socket, and then accept each incoming
+-connection with a call to `accept' (*note Accepting Connections::.).
+-Once connection requests are enabled on a server socket, the `select'
+-function reports when the socket has a connection ready to be accepted
+-(*note Waiting for I/O::.).
+-
+-   The `listen' function is not allowed for sockets using
+-connectionless communication styles.
+-
+-   You can write a network server that does not even start running
+-until a connection to it is requested.  *Note Inetd Servers::.
+-
+-   In the Internet namespace, there are no special protection mechanisms
+-for controlling access to connect to a port; any process on any machine
+-can make a connection to your server.  If you want to restrict access to
+-your server, make it examine the addresses associated with connection
+-requests or implement some other handshaking or identification protocol.
+-
+-   In the File namespace, the ordinary file protection bits control who
+-has access to connect to the socket.
+-
+- - Function: int listen (int SOCKET, unsigned int N)
+-     The `listen' function enables the socket SOCKET to accept
+-     connections, thus making it a server socket.
+-
+-     The argument N specifies the length of the queue for pending
+-     connections.  When the queue fills, new clients attempting to
+-     connect fail with `ECONNREFUSED' until the server calls `accept' to
+-     accept a connection from the queue.
+-
+-     The `listen' function returns `0' on success and `-1' on failure.
+-     The following `errno' error conditions are defined for this
+-     function:
+-
+-    `EBADF'
+-          The argument SOCKET is not a valid file descriptor.
+-
+-    `ENOTSOCK'
+-          The argument SOCKET is not a socket.
+-
+-    `EOPNOTSUPP'
+-          The socket SOCKET does not support this operation.
+-
+-
+-File: libc.info,  Node: Accepting Connections,  Next: Who is Connected,  
Prev: Listening,  Up: Connections
+-
+-Accepting Connections
+----------------------
+-
+-   When a server receives a connection request, it can complete the
+-connection by accepting the request.  Use the function `accept' to do
+-this.
+-
+-   A socket that has been established as a server can accept connection
+-requests from multiple clients.  The server's original socket *does not
+-become part* of the connection; instead, `accept' makes a new socket
+-which participates in the connection.  `accept' returns the descriptor
+-for this socket.  The server's original socket remains available for
+-listening for further connection requests.
+-
+-   The number of pending connection requests on a server socket is
+-finite.  If connection requests arrive from clients faster than the
+-server can act upon them, the queue can fill up and additional requests
+-are refused with a `ECONNREFUSED' error.  You can specify the maximum
+-length of this queue as an argument to the `listen' function, although
+-the system may also impose its own internal limit on the length of this
+-queue.
+-
+- - Function: int accept (int SOCKET, struct sockaddr *ADDR, size_t
+-          *LENGTH-PTR)
+-     This function is used to accept a connection request on the server
+-     socket SOCKET.
+-
+-     The `accept' function waits if there are no connections pending,
+-     unless the socket SOCKET has nonblocking mode set.  (You can use
+-     `select' to wait for a pending connection, with a nonblocking
+-     socket.)  *Note File Status Flags::, for information about
+-     nonblocking mode.
+-
+-     The ADDR and LENGTH-PTR arguments are used to return information
+-     about the name of the client socket that initiated the connection.
+-     *Note Socket Addresses::, for information about the format of the
+-     information.
+-
+-     Accepting a connection does not make SOCKET part of the
+-     connection.  Instead, it creates a new socket which becomes
+-     connected.  The normal return value of `accept' is the file
+-     descriptor for the new socket.
+-
+-     After `accept', the original socket SOCKET remains open and
+-     unconnected, and continues listening until you close it.  You can
+-     accept further connections with SOCKET by calling `accept' again.
+-
+-     If an error occurs, `accept' returns `-1'.  The following `errno'
+-     error conditions are defined for this function:
+-
+-    `EBADF'
+-          The SOCKET argument is not a valid file descriptor.
+-
+-    `ENOTSOCK'
+-          The descriptor SOCKET argument is not a socket.
+-
+-    `EOPNOTSUPP'
+-          The descriptor SOCKET does not support this operation.
+-
+-    `EWOULDBLOCK'
+-          SOCKET has nonblocking mode set, and there are no pending
+-          connections immediately available.
+-
+-   The `accept' function is not allowed for sockets using
+-connectionless communication styles.
+-
+-
+-File: libc.info,  Node: Who is Connected,  Next: Transferring Data,  Prev: 
Accepting Connections,  Up: Connections
+-
+-Who is Connected to Me?
+------------------------
+-
+- - Function: int getpeername (int SOCKET, struct sockaddr *ADDR, size_t
+-          *LENGTH-PTR)
+-     The `getpeername' function returns the address of the socket that
+-     SOCKET is connected to; it stores the address in the memory space
+-     specified by ADDR and LENGTH-PTR.  It stores the length of the
+-     address in `*LENGTH-PTR'.
+-
+-     *Note Socket Addresses::, for information about the format of the
+-     address.  In some operating systems, `getpeername' works only for
+-     sockets in the Internet domain.
+-
+-     The return value is `0' on success and `-1' on error.  The
+-     following `errno' error conditions are defined for this function:
+-
+-    `EBADF'
+-          The argument SOCKET is not a valid file descriptor.
+-
+-    `ENOTSOCK'
+-          The descriptor SOCKET is not a socket.
+-
+-    `ENOTCONN'
+-          The socket SOCKET is not connected.
+-
+-    `ENOBUFS'
+-          There are not enough internal buffers available.
+-
+-
+-File: libc.info,  Node: Transferring Data,  Next: Byte Stream Example,  Prev: 
Who is Connected,  Up: Connections
+-
+-Transferring Data
+------------------
+-
+-   Once a socket has been connected to a peer, you can use the ordinary
+-`read' and `write' operations (*note I/O Primitives::.) to transfer
+-data.  A socket is a two-way communications channel, so read and write
+-operations can be performed at either end.
+-
+-   There are also some I/O modes that are specific to socket operations.
+-In order to specify these modes, you must use the `recv' and `send'
+-functions instead of the more generic `read' and `write' functions.
+-The `recv' and `send' functions take an additional argument which you
+-can use to specify various flags to control the special I/O modes.  For
+-example, you can specify the `MSG_OOB' flag to read or write
+-out-of-band data, the `MSG_PEEK' flag to peek at input, or the
+-`MSG_DONTROUTE' flag to control inclusion of routing information on
+-output.
+-
+-* Menu:
+-
+-* Sending Data::              Sending data with `send'.
+-* Receiving Data::            Reading data with `recv'.
+-* Socket Data Options::               Using `send' and `recv'.
+-
+-
+-File: libc.info,  Node: Sending Data,  Next: Receiving Data,  Up: 
Transferring Data
+-
+-Sending Data
+-............
+-
+-   The `send' function is declared in the header file `sys/socket.h'.
+-If your FLAGS argument is zero, you can just as well use `write'
+-instead of `send'; see *Note I/O Primitives::.  If the socket was
+-connected but the connection has broken, you get a `SIGPIPE' signal for
+-any use of `send' or `write' (*note Miscellaneous Signals::.).
+-
+- - Function: int send (int SOCKET, void *BUFFER, size_t SIZE, int FLAGS)
+-     The `send' function is like `write', but with the additional flags
+-     FLAGS.  The possible values of FLAGS are described in *Note Socket
+-     Data Options::.
+-
+-     This function returns the number of bytes transmitted, or `-1' on
+-     failure.  If the socket is nonblocking, then `send' (like `write')
+-     can return after sending just part of the data.  *Note File Status
+-     Flags::, for information about nonblocking mode.
+-
+-     Note, however, that a successful return value merely indicates that
+-     the message has been sent without error, not necessarily that it
+-     has been received without error.
+-
+-     The following `errno' error conditions are defined for this
+-     function:
+-
+-    `EBADF'
+-          The SOCKET argument is not a valid file descriptor.
+-
+-    `EINTR'
+-          The operation was interrupted by a signal before any data was
+-          sent.  *Note Interrupted Primitives::.
+-
+-    `ENOTSOCK'
+-          The descriptor SOCKET is not a socket.
+-
+-    `EMSGSIZE'
+-          The socket type requires that the message be sent atomically,
+-          but the message is too large for this to be possible.
+-
+-    `EWOULDBLOCK'
+-          Nonblocking mode has been set on the socket, and the write
+-          operation would block.  (Normally `send' blocks until the
+-          operation can be completed.)
+-
+-    `ENOBUFS'
+-          There is not enough internal buffer space available.
+-
+-    `ENOTCONN'
+-          You never connected this socket.
+-
+-    `EPIPE'
+-          This socket was connected but the connection is now broken.
+-          In this case, `send' generates a `SIGPIPE' signal first; if
+-          that signal is ignored or blocked, or if its handler returns,
+-          then `send' fails with `EPIPE'.
+-
+-
+-File: libc.info,  Node: Receiving Data,  Next: Socket Data Options,  Prev: 
Sending Data,  Up: Transferring Data
+-
+-Receiving Data
+-..............
+-
+-   The `recv' function is declared in the header file `sys/socket.h'.
+-If your FLAGS argument is zero, you can just as well use `read' instead
+-of `recv'; see *Note I/O Primitives::.
+-
+- - Function: int recv (int SOCKET, void *BUFFER, size_t SIZE, int FLAGS)
+-     The `recv' function is like `read', but with the additional flags
+-     FLAGS.  The possible values of FLAGS are described In *Note Socket
+-     Data Options::.
+-
+-     If nonblocking mode is set for SOCKET, and no data is available to
+-     be read, `recv' fails immediately rather than waiting.  *Note File
+-     Status Flags::, for information about nonblocking mode.
+-
+-     This function returns the number of bytes received, or `-1' on
+-     failure.  The following `errno' error conditions are defined for
+-     this function:
+-
+-    `EBADF'
+-          The SOCKET argument is not a valid file descriptor.
+-
+-    `ENOTSOCK'
+-          The descriptor SOCKET is not a socket.
+-
+-    `EWOULDBLOCK'
+-          Nonblocking mode has been set on the socket, and the read
+-          operation would block.  (Normally, `recv' blocks until there
+-          is input available to be read.)
+-
+-    `EINTR'
+-          The operation was interrupted by a signal before any data was
+-          read.  *Note Interrupted Primitives::.
+-
+-    `ENOTCONN'
+-          You never connected this socket.
+-
+-
+-File: libc.info,  Node: Socket Data Options,  Prev: Receiving Data,  Up: 
Transferring Data
+-
+-Socket Data Options
+-...................
+-
+-   The FLAGS argument to `send' and `recv' is a bit mask.  You can
+-bitwise-OR the values of the following macros together to obtain a
+-value for this argument.  All are defined in the header file
+-`sys/socket.h'.
+-
+- - Macro: int MSG_OOB
+-     Send or receive out-of-band data.  *Note Out-of-Band Data::.
+-
+- - Macro: int MSG_PEEK
+-     Look at the data but don't remove it from the input queue.  This is
+-     only meaningful with input functions such as `recv', not with
+-     `send'.
+-
+- - Macro: int MSG_DONTROUTE
+-     Don't include routing information in the message.  This is only
+-     meaningful with output operations, and is usually only of interest
+-     for diagnostic or routing programs.  We don't try to explain it
+-     here.
+-
+-
+-File: libc.info,  Node: Byte Stream Example,  Next: Server Example,  Prev: 
Transferring Data,  Up: Connections
+-
+-Byte Stream Socket Example
+---------------------------
+-
+-   Here is an example client program that makes a connection for a byte
+-stream socket in the Internet namespace.  It doesn't do anything
+-particularly interesting once it has connected to the server; it just
+-sends a text string to the server and exits.
+-
+-     #include <stdio.h>
+-     #include <errno.h>
+-     #include <stdlib.h>
+-     #include <unistd.h>
+-     #include <sys/types.h>
+-     #include <sys/socket.h>
+-     #include <netinet/in.h>
+-     #include <netdb.h>
+-     
+-     #define PORT            5555
+-     #define MESSAGE         "Yow!!! Are we having fun yet?!?"
+-     #define SERVERHOST      "churchy.gnu.ai.mit.edu"
+-     
+-     void
+-     write_to_server (int filedes)
+-     {
+-       int nbytes;
+-     
+-       nbytes = write (filedes, MESSAGE, strlen (MESSAGE) + 1);
+-       if (nbytes < 0)
+-         {
+-           perror ("write");
+-           exit (EXIT_FAILURE);
+-         }
+-     }
+-     
+-     
+-     int
+-     main (void)
+-     {
+-       extern void init_sockaddr (struct sockaddr_in *name,
+-                                  const char *hostname,
+-                                  unsigned short int port);
+-       int sock;
+-       struct sockaddr_in servername;
+-     
+-       /* Create the socket. */
+-       sock = socket (PF_INET, SOCK_STREAM, 0);
+-       if (sock < 0)
+-         {
+-           perror ("socket (client)");
+-           exit (EXIT_FAILURE);
+-         }
+-     
+-       /* Connect to the server. */
+-       init_sockaddr (&servername, SERVERHOST, PORT);
+-       if (0 > connect (sock,
+-                        (struct sockaddr *) &servername,
+-                        sizeof (servername)))
+-         {
+-           perror ("connect (client)");
+-           exit (EXIT_FAILURE);
+-         }
+-     
+-       /* Send data to the server. */
+-       write_to_server (sock);
+-       close (sock);
+-       exit (EXIT_SUCCESS);
+-     }
+-
+-
+-File: libc.info,  Node: Server Example,  Next: Out-of-Band Data,  Prev: Byte 
Stream Example,  Up: Connections
+-
+-Byte Stream Connection Server Example
+--------------------------------------
+-
+-   The server end is much more complicated.  Since we want to allow
+-multiple clients to be connected to the server at the same time, it
+-would be incorrect to wait for input from a single client by simply
+-calling `read' or `recv'.  Instead, the right thing to do is to use
+-`select' (*note Waiting for I/O::.) to wait for input on all of the
+-open sockets.  This also allows the server to deal with additional
+-connection requests.
+-
+-   This particular server doesn't do anything interesting once it has
+-gotten a message from a client.  It does close the socket for that
+-client when it detects an end-of-file condition (resulting from the
+-client shutting down its end of the connection).
+-
+-   This program uses `make_socket' and `init_sockaddr' to set up the
+-socket address; see *Note Inet Example::.
+-
+-     #include <stdio.h>
+-     #include <errno.h>
+-     #include <stdlib.h>
+-     #include <unistd.h>
+-     #include <sys/types.h>
+-     #include <sys/socket.h>
+-     #include <netinet/in.h>
+-     #include <netdb.h>
+-     
+-     #define PORT    5555
+-     #define MAXMSG  512
+-     
+-     int
+-     read_from_client (int filedes)
+-     {
+-       char buffer[MAXMSG];
+-       int nbytes;
+-     
+-       nbytes = read (filedes, buffer, MAXMSG);
+-       if (nbytes < 0)
+-         {
+-           /* Read error. */
+-           perror ("read");
+-           exit (EXIT_FAILURE);
+-         }
+-       else if (nbytes == 0)
+-         /* End-of-file. */
+-         return -1;
+-       else
+-         {
+-           /* Data read. */
+-           fprintf (stderr, "Server: got message: `%s'\n", buffer);
+-           return 0;
+-         }
+-     }
+-     
+-     int
+-     main (void)
+-     {
+-       extern int make_socket (unsigned short int port);
+-       int sock;
+-       fd_set active_fd_set, read_fd_set;
+-       int i;
+-       struct sockaddr_in clientname;
+-       size_t size;
+-     
+-       /* Create the socket and set it up to accept connections. */
+-       sock = make_socket (PORT);
+-       if (listen (sock, 1) < 0)
+-         {
+-           perror ("listen");
+-           exit (EXIT_FAILURE);
+-         }
+-     
+-       /* Initialize the set of active sockets. */
+-       FD_ZERO (&active_fd_set);
+-       FD_SET (sock, &active_fd_set);
+-     
+-       while (1)
+-         {
+-           /* Block until input arrives on one or more active sockets. */
+-           read_fd_set = active_fd_set;
+-           if (select (FD_SETSIZE, &read_fd_set, NULL, NULL, NULL) < 0)
+-             {
+-               perror ("select");
+-               exit (EXIT_FAILURE);
+-             }
+-     
+-           /* Service all the sockets with input pending. */
+-           for (i = 0; i < FD_SETSIZE; ++i)
+-             if (FD_ISSET (i, &read_fd_set))
+-               {
+-                 if (i == sock)
+-                   {
+-                     /* Connection request on original socket. */
+-                     int new;
+-                     size = sizeof (clientname);
+-                     new = accept (sock,
+-                                   (struct sockaddr *) &clientname,
+-                                   &size);
+-                     if (new < 0)
+-                       {
+-                         perror ("accept");
+-                         exit (EXIT_FAILURE);
+-                       }
+-                     fprintf (stderr,
+-                              "Server: connect from host %s, port %hd.\n",
+-                              inet_ntoa (clientname.sin_addr),
+-                              ntohs (clientname.sin_port));
+-                     FD_SET (new, &active_fd_set);
+-                   }
+-                 else
+-                   {
+-                     /* Data arriving on an already-connected socket. */
+-                     if (read_from_client (i) < 0)
+-                       {
+-                         close (i);
+-                         FD_CLR (i, &active_fd_set);
+-                       }
+-                   }
+-               }
+-         }
+-     }
+-
+-
+-File: libc.info,  Node: Out-of-Band Data,  Prev: Server Example,  Up: 
Connections
+-
+-Out-of-Band Data
+-----------------
+-
+-   Streams with connections permit "out-of-band" data that is delivered
+-with higher priority than ordinary data.  Typically the reason for
+-sending out-of-band data is to send notice of an exceptional condition.
+-The way to send out-of-band data is using `send', specifying the flag
+-`MSG_OOB' (*note Sending Data::.).
+-
+-   Out-of-band data is received with higher priority because the
+-receiving process need not read it in sequence; to read the next
+-available out-of-band data, use `recv' with the `MSG_OOB' flag (*note
+-Receiving Data::.).  Ordinary read operations do not read out-of-band
+-data; they read only the ordinary data.
+-
+-   When a socket finds that out-of-band data is on its way, it sends a
+-`SIGURG' signal to the owner process or process group of the socket.
+-You can specify the owner using the `F_SETOWN' command to the `fcntl'
+-function; see *Note Interrupt Input::.  You must also establish a
+-handler for this signal, as described in *Note Signal Handling::, in
+-order to take appropriate action such as reading the out-of-band data.
+-
+-   Alternatively, you can test for pending out-of-band data, or wait
+-until there is out-of-band data, using the `select' function; it can
+-wait for an exceptional condition on the socket.  *Note Waiting for
+-I/O::, for more information about `select'.
+-
+-   Notification of out-of-band data (whether with `SIGURG' or with
+-`select') indicates that out-of-band data is on the way; the data may
+-not actually arrive until later.  If you try to read the out-of-band
+-data before it arrives, `recv' fails with an `EWOULDBLOCK' error.
+-
+-   Sending out-of-band data automatically places a "mark" in the stream
+-of ordinary data, showing where in the sequence the out-of-band data
+-"would have been".  This is useful when the meaning of out-of-band data
+-is "cancel everything sent so far".  Here is how you can test, in the
+-receiving process, whether any ordinary data was sent before the mark:
+-
+-     success = ioctl (socket, SIOCATMARK, &result);
+-
+-   Here's a function to discard any ordinary data preceding the
+-out-of-band mark:
+-
+-     int
+-     discard_until_mark (int socket)
+-     {
+-       while (1)
+-         {
+-           /* This is not an arbitrary limit; any size will do.  */
+-           char buffer[1024];
+-           int result, success;
+-     
+-           /* If we have reached the mark, return.  */
+-           success = ioctl (socket, SIOCATMARK, &result);
+-           if (success < 0)
+-             perror ("ioctl");
+-           if (result)
+-             return;
+-     
+-           /* Otherwise, read a bunch of ordinary data and discard it.
+-              This is guaranteed not to read past the mark
+-              if it starts before the mark.  */
+-           success = read (socket, buffer, sizeof buffer);
+-           if (success < 0)
+-             perror ("read");
+-         }
+-     }
+-
+-   If you don't want to discard the ordinary data preceding the mark,
+-you may need to read some of it anyway, to make room in internal system
+-buffers for the out-of-band data.  If you try to read out-of-band data
+-and get an `EWOULDBLOCK' error, try reading some ordinary data (saving
+-it so that you can use it when you want it) and see if that makes room.
+-Here is an example:
+-
+-     struct buffer
+-     {
+-       char *buffer;
+-       int size;
+-       struct buffer *next;
+-     };
+-     
+-     /* Read the out-of-band data from SOCKET and return it
+-        as a `struct buffer', which records the address of the data
+-        and its size.
+-     
+-        It may be necessary to read some ordinary data
+-        in order to make room for the out-of-band data.
+-        If so, the ordinary data is saved as a chain of buffers
+-        found in the `next' field of the value.  */
+-     
+-     struct buffer *
+-     read_oob (int socket)
+-     {
+-       struct buffer *tail = 0;
+-       struct buffer *list = 0;
+-     
+-       while (1)
+-         {
+-           /* This is an arbitrary limit.
+-              Does anyone know how to do this without a limit?  */
+-           char *buffer = (char *) xmalloc (1024);
+-           struct buffer *link;
+-           int success;
+-           int result;
+-     
+-           /* Try again to read the out-of-band data.  */
+-           success = recv (socket, buffer, sizeof buffer, MSG_OOB);
+-           if (success >= 0)
+-             {
+-               /* We got it, so return it.  */
+-               struct buffer *link
+-                 = (struct buffer *) xmalloc (sizeof (struct buffer));
+-               link->buffer = buffer;
+-               link->size = success;
+-               link->next = list;
+-               return link;
+-             }
+-     
+-           /* If we fail, see if we are at the mark.  */
+-           success = ioctl (socket, SIOCATMARK, &result);
+-           if (success < 0)
+-             perror ("ioctl");
+-           if (result)
+-             {
+-               /* At the mark; skipping past more ordinary data cannot help.
+-                  So just wait a while.  */
+-               sleep (1);
+-               continue;
+-             }
+-     
+-           /* Otherwise, read a bunch of ordinary data and save it.
+-              This is guaranteed not to read past the mark
+-              if it starts before the mark.  */
+-           success = read (socket, buffer, sizeof buffer);
+-           if (success < 0)
+-             perror ("read");
+-     
+-           /* Save this data in the buffer list.  */
+-           {
+-             struct buffer *link
+-               = (struct buffer *) xmalloc (sizeof (struct buffer));
+-             link->buffer = buffer;
+-             link->size = success;
+-     
+-             /* Add the new link to the end of the list.  */
+-             if (tail)
+-               tail->next = link;
+-             else
+-               list = link;
+-             tail = link;
+-           }
+-         }
+-     }
+-
+-
+-File: libc.info,  Node: Datagrams,  Next: Inetd,  Prev: Connections,  Up: 
Sockets
+-
+-Datagram Socket Operations
+-==========================
+-
+-   This section describes how to use communication styles that don't use
+-connections (styles `SOCK_DGRAM' and `SOCK_RDM').  Using these styles,
+-you group data into packets and each packet is an independent
+-communication.  You specify the destination for each packet
+-individually.
+-
+-   Datagram packets are like letters: you send each one independently,
+-with its own destination address, and they may arrive in the wrong
+-order or not at all.
+-
+-   The `listen' and `accept' functions are not allowed for sockets
+-using connectionless communication styles.
+-
+-* Menu:
+-
+-* Sending Datagrams::    Sending packets on a datagram socket.
+-* Receiving Datagrams::  Receiving packets on a datagram socket.
+-* Datagram Example::     An example program: packets sent over a
+-                           datagram socket in the file namespace.
+-* Example Receiver::   Another program, that receives those packets.
+-
+-
+-File: libc.info,  Node: Sending Datagrams,  Next: Receiving Datagrams,  Up: 
Datagrams
+-
+-Sending Datagrams
+------------------
+-
+-   The normal way of sending data on a datagram socket is by using the
+-`sendto' function, declared in `sys/socket.h'.
+-
+-   You can call `connect' on a datagram socket, but this only specifies
+-a default destination for further data transmission on the socket.
+-When a socket has a default destination, then you can use `send' (*note
+-Sending Data::.) or even `write' (*note I/O Primitives::.) to send a
+-packet there.  You can cancel the default destination by calling
+-`connect' using an address format of `AF_UNSPEC' in the ADDR argument.
+-*Note Connecting::, for more information about the `connect' function.
+-
+- - Function: int sendto (int SOCKET, void *BUFFER. size_t SIZE, int
+-          FLAGS, struct sockaddr *ADDR, size_t LENGTH)
+-     The `sendto' function transmits the data in the BUFFER through the
+-     socket SOCKET to the destination address specified by the ADDR and
+-     LENGTH arguments.  The SIZE argument specifies the number of bytes
+-     to be transmitted.
+-
+-     The FLAGS are interpreted the same way as for `send'; see *Note
+-     Socket Data Options::.
+-
+-     The return value and error conditions are also the same as for
+-     `send', but you cannot rely on the system to detect errors and
+-     report them; the most common error is that the packet is lost or
+-     there is no one at the specified address to receive it, and the
+-     operating system on your machine usually does not know this.
+-
+-     It is also possible for one call to `sendto' to report an error
+-     due to a problem related to a previous call.
+-
+-
+-File: libc.info,  Node: Receiving Datagrams,  Next: Datagram Example,  Prev: 
Sending Datagrams,  Up: Datagrams
+-
+-Receiving Datagrams
+--------------------
+-
+-   The `recvfrom' function reads a packet from a datagram socket and
+-also tells you where it was sent from.  This function is declared in
+-`sys/socket.h'.
+-
+- - Function: int recvfrom (int SOCKET, void *BUFFER, size_t SIZE, int
+-          FLAGS, struct sockaddr *ADDR, size_t *LENGTH-PTR)
+-     The `recvfrom' function reads one packet from the socket SOCKET
+-     into the buffer BUFFER.  The SIZE argument specifies the maximum
+-     number of bytes to be read.
+-
+-     If the packet is longer than SIZE bytes, then you get the first
+-     SIZE bytes of the packet, and the rest of the packet is lost.
+-     There's no way to read the rest of the packet.  Thus, when you use
+-     a packet protocol, you must always know how long a packet to
+-     expect.
+-
+-     The ADDR and LENGTH-PTR arguments are used to return the address
+-     where the packet came from.  *Note Socket Addresses::.  For a
+-     socket in the file domain, the address information won't be
+-     meaningful, since you can't read the address of such a socket
+-     (*note File Namespace::.).  You can specify a null pointer as the
+-     ADDR argument if you are not interested in this information.
+-
+-     The FLAGS are interpreted the same way as for `recv' (*note Socket
+-     Data Options::.).  The return value and error conditions are also
+-     the same as for `recv'.
+-
+-   You can use plain `recv' (*note Receiving Data::.) instead of
+-`recvfrom' if you know don't need to find out who sent the packet
+-(either because you know where it should come from or because you treat
+-all possible senders alike).  Even `read' can be used if you don't want
+-to specify FLAGS (*note I/O Primitives::.).
+-
+-
+-File: libc.info,  Node: Datagram Example,  Next: Example Receiver,  Prev: 
Receiving Datagrams,  Up: Datagrams
+-
+-Datagram Socket Example
+------------------------
+-
+-   Here is a set of example programs that send messages over a datagram
+-stream in the file namespace.  Both the client and server programs use
+-the `make_named_socket' function that was presented in *Note File
+-Namespace::, to create and name their sockets.
+-
+-   First, here is the server program.  It sits in a loop waiting for
+-messages to arrive, bouncing each message back to the sender.
+-Obviously, this isn't a particularly useful program, but it does show
+-the general ideas involved.
+-
+-     #include <stdio.h>
+-     #include <errno.h>
+-     #include <stdlib.h>
+-     #include <sys/socket.h>
+-     #include <sys/un.h>
+-     
+-     #define SERVER  "/tmp/serversocket"
+-     #define MAXMSG  512
+-     
+-     int
+-     main (void)
+-     {
+-       int sock;
+-       char message[MAXMSG];
+-       struct sockaddr_un name;
+-       size_t size;
+-       int nbytes;
+-     
+-       /* Make the socket, then loop endlessly. */
+-     
+-       sock = make_named_socket (SERVER);
+-       while (1)
+-         {
+-           /* Wait for a datagram. */
+-           size = sizeof (name);
+-           nbytes = recvfrom (sock, message, MAXMSG, 0,
+-                              (struct sockaddr *) & name, &size);
+-           if (nbytes < 0)
+-             {
+-               perror ("recfrom (server)");
+-               exit (EXIT_FAILURE);
+-             }
+-     
+-           /* Give a diagnostic message. */
+-           fprintf (stderr, "Server: got message: %s\n", message);
+-     
+-           /* Bounce the message back to the sender. */
+-           nbytes = sendto (sock, message, nbytes, 0,
+-                            (struct sockaddr *) & name, size);
+-           if (nbytes < 0)
+-             {
+-               perror ("sendto (server)");
+-               exit (EXIT_FAILURE);
+-             }
+-         }
+-     }
+-
+-
+-File: libc.info,  Node: Example Receiver,  Prev: Datagram Example,  Up: 
Datagrams
+-
+-Example of Reading Datagrams
+-----------------------------
+-
+-   Here is the client program corresponding to the server above.
+-
+-   It sends a datagram to the server and then waits for a reply.  Notice
+-that the socket for the client (as well as for the server) in this
+-example has to be given a name.  This is so that the server can direct
+-a message back to the client.  Since the socket has no associated
+-connection state, the only way the server can do this is by referencing
+-the name of the client.
+-
+-     #include <stdio.h>
+-     #include <errno.h>
+-     #include <unistd.h>
+-     #include <stdlib.h>
+-     #include <sys/socket.h>
+-     #include <sys/un.h>
+-     
+-     #define SERVER  "/tmp/serversocket"
+-     #define CLIENT  "/tmp/mysocket"
+-     #define MAXMSG  512
+-     #define MESSAGE "Yow!!! Are we having fun yet?!?"
+-     
+-     int
+-     main (void)
+-     {
+-       extern int make_named_socket (const char *name);
+-       int sock;
+-       char message[MAXMSG];
+-       struct sockaddr_un name;
+-       size_t size;
+-       int nbytes;
+-     
+-       /* Make the socket. */
+-       sock = make_named_socket (CLIENT);
+-     
+-       /* Initialize the server socket address. */
+-       name.sun_family = AF_UNIX;
+-       strcpy (name.sun_path, SERVER);
+-       size = strlen (name.sun_path) + sizeof (name.sun_family);
+-     
+-       /* Send the datagram. */
+-       nbytes = sendto (sock, MESSAGE, strlen (MESSAGE) + 1, 0,
+-                        (struct sockaddr *) & name, size);
+-       if (nbytes < 0)
+-         {
+-           perror ("sendto (client)");
+-           exit (EXIT_FAILURE);
+-         }
+-     
+-       /* Wait for a reply. */
+-       nbytes = recvfrom (sock, message, MAXMSG, 0, NULL, 0);
+-       if (nbytes < 0)
+-         {
+-           perror ("recfrom (client)");
+-           exit (EXIT_FAILURE);
+-         }
+-     
+-       /* Print a diagnostic message. */
+-       fprintf (stderr, "Client: got message: %s\n", message);
+-     
+-       /* Clean up. */
+-       remove (CLIENT);
+-       close (sock);
+-     }
+-
+-   Keep in mind that datagram socket communications are unreliable.  In
+-this example, the client program waits indefinitely if the message
+-never reaches the server or if the server's response never comes back.
+-It's up to the user running the program to kill it and restart it, if
+-desired.  A more automatic solution could be to use `select' (*note
+-Waiting for I/O::.) to establish a timeout period for the reply, and in
+-case of timeout either resend the message or shut down the socket and
+-exit.
+-
+-
+-File: libc.info,  Node: Inetd,  Next: Socket Options,  Prev: Datagrams,  Up: 
Sockets
+-
+-The `inetd' Daemon
+-==================
+-
+-   We've explained above how to write a server program that does its own
+-listening.  Such a server must already be running in order for anyone
+-to connect to it.
+-
+-   Another way to provide service for an Internet port is to let the
+-daemon program `inetd' do the listening.  `inetd' is a program that
+-runs all the time and waits (using `select') for messages on a
+-specified set of ports.  When it receives a message, it accepts the
+-connection (if the socket style calls for connections) and then forks a
+-child process to run the corresponding server program.  You specify the
+-ports and their programs in the file `/etc/inetd.conf'.
+-
+-* Menu:
+-
+-* Inetd Servers::
+-* Configuring Inetd::
+-
+-
+-File: libc.info,  Node: Inetd Servers,  Next: Configuring Inetd,  Up: Inetd
+-
+-`inetd' Servers
+----------------
+-
+-   Writing a server program to be run by `inetd' is very simple.  Each
+-time someone requests a connection to the appropriate port, a new server
+-process starts.  The connection already exists at this time; the socket
+-is available as the standard input descriptor and as the standard
+-output descriptor (descriptors 0 and 1) in the server process.  So the
+-server program can begin reading and writing data right away.  Often
+-the program needs only the ordinary I/O facilities; in fact, a
+-general-purpose filter program that knows nothing about sockets can
+-work as a byte stream server run by `inetd'.
+-
+-   You can also use `inetd' for servers that use connectionless
+-communication styles.  For these servers, `inetd' does not try to accept
+-a connection, since no connection is possible.  It just starts the
+-server program, which can read the incoming datagram packet from
+-descriptor 0.  The server program can handle one request and then exit,
+-or you can choose to write it to keep reading more requests until no
+-more arrive, and then exit.  You must specify which of these two
+-techniques the server uses, when you configure `inetd'.
+-
+-
+-File: libc.info,  Node: Configuring Inetd,  Prev: Inetd Servers,  Up: Inetd
+-
+-Configuring `inetd'
+--------------------
+-
+-   The file `/etc/inetd.conf' tells `inetd' which ports to listen to
+-and what server programs to run for them.  Normally each entry in the
+-file is one line, but you can split it onto multiple lines provided all
+-but the first line of the entry start with whitespace.  Lines that
+-start with `#' are comments.
+-
+-   Here are two standard entries in `/etc/inetd.conf':
+-
+-     ftp      stream  tcp     nowait  root    /libexec/ftpd   ftpd
+-     talk     dgram   udp     wait    root    /libexec/talkd  talkd
+-
+-   An entry has this format:
+-
+-     SERVICE STYLE PROTOCOL WAIT USERNAME PROGRAM ARGUMENTS
+-
+-   The SERVICE field says which service this program provides.  It
+-should be the name of a service defined in `/etc/services'.  `inetd'
+-uses SERVICE to decide which port to listen on for this entry.
+-
+-   The fields STYLE and PROTOCOL specify the communication style and
+-the protocol to use for the listening socket.  The style should be the
+-name of a communication style, converted to lower case and with `SOCK_'
+-deleted--for example, `stream' or `dgram'.  PROTOCOL should be one of
+-the protocols listed in `/etc/protocols'.  The typical protocol names
+-are `tcp' for byte stream connections and `udp' for unreliable
+-datagrams.
+-
+-   The WAIT field should be either `wait' or `nowait'.  Use `wait' if
+-STYLE is a connectionless style and the server, once started, handles
+-multiple requests, as many as come in.  Use `nowait' if `inetd' should
+-start a new process for each message or request that comes in.  If
+-STYLE uses connections, then WAIT *must* be `nowait'.
+-
+-   USER is the user name that the server should run as.  `inetd' runs
+-as root, so it can set the user ID of its children arbitrarily.  It's
+-best to avoid using `root' for USER if you can; but some servers, such
+-as Telnet and FTP, read a username and password themselves.  These
+-servers need to be root initially so they can log in as commanded by
+-the data coming over the network.
+-
+-   PROGRAM together with ARGUMENTS specifies the command to run to
+-start the server.  PROGRAM should be an absolute file name specifying
+-the executable file to run.  ARGUMENTS consists of any number of
+-whitespace-separated words, which become the command-line arguments of
+-PROGRAM.  The first word in ARGUMENTS is argument zero, which should by
+-convention be the program name itself (sans directories).
+-
+-   If you edit `/etc/inetd.conf', you can tell `inetd' to reread the
+-file and obey its new contents by sending the `inetd' process the
+-`SIGHUP' signal.  You'll have to use `ps' to determine the process ID
+-of the `inetd' process, as it is not fixed.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-14 
glibc-2.0.1/manual/libc.info-14
+--- ../glibc-2.0.1/manual/libc.info-14 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-14    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1159 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Socket Options,  Next: Networks Database,  Prev: 
Inetd,  Up: Sockets
+-
+-Socket Options
+-==============
+-
+-   This section describes how to read or set various options that modify
+-the behavior of sockets and their underlying communications protocols.
+-
+-   When you are manipulating a socket option, you must specify which
+-"level" the option pertains to.  This describes whether the option
+-applies to the socket interface, or to a lower-level communications
+-protocol interface.
+-
+-* Menu:
+-
+-* Socket Option Functions::     The basic functions for setting and getting
+-                                 socket options.
+-* Socket-Level Options::        Details of the options at the socket level.
+-
+-
+-File: libc.info,  Node: Socket Option Functions,  Next: Socket-Level Options, 
 Up: Socket Options
+-
+-Socket Option Functions
+------------------------
+-
+-   Here are the functions for examining and modifying socket options.
+-They are declared in `sys/socket.h'.
+-
+- - Function: int getsockopt (int SOCKET, int LEVEL, int OPTNAME, void
+-          *OPTVAL, size_t *OPTLEN-PTR)
+-     The `getsockopt' function gets information about the value of
+-     option OPTNAME at level LEVEL for socket SOCKET.
+-
+-     The option value is stored in a buffer that OPTVAL points to.
+-     Before the call, you should supply in `*OPTLEN-PTR' the size of
+-     this buffer; on return, it contains the number of bytes of
+-     information actually stored in the buffer.
+-
+-     Most options interpret the OPTVAL buffer as a single `int' value.
+-
+-     The actual return value of `getsockopt' is `0' on success and `-1'
+-     on failure.  The following `errno' error conditions are defined:
+-
+-    `EBADF'
+-          The SOCKET argument is not a valid file descriptor.
+-
+-    `ENOTSOCK'
+-          The descriptor SOCKET is not a socket.
+-
+-    `ENOPROTOOPT'
+-          The OPTNAME doesn't make sense for the given LEVEL.
+-
+- - Function: int setsockopt (int SOCKET, int LEVEL, int OPTNAME, void
+-          *OPTVAL, size_t OPTLEN)
+-     This function is used to set the socket option OPTNAME at level
+-     LEVEL for socket SOCKET.  The value of the option is passed in the
+-     buffer OPTVAL, which has size OPTLEN.
+-
+-     The return value and error codes for `setsockopt' are the same as
+-     for `getsockopt'.
+-
+-
+-File: libc.info,  Node: Socket-Level Options,  Prev: Socket Option Functions, 
 Up: Socket Options
+-
+-Socket-Level Options
+---------------------
+-
+- - Constant: int SOL_SOCKET
+-     Use this constant as the LEVEL argument to `getsockopt' or
+-     `setsockopt' to manipulate the socket-level options described in
+-     this section.
+-
+-   Here is a table of socket-level option names; all are defined in the
+-header file `sys/socket.h'.
+-
+-`SO_DEBUG'
+-     This option toggles recording of debugging information in the
+-     underlying protocol modules.  The value has type `int'; a nonzero
+-     value means "yes".
+-
+-`SO_REUSEADDR'
+-     This option controls whether `bind' (*note Setting Address::.)
+-     should permit reuse of local addresses for this socket.  If you
+-     enable this option, you can actually have two sockets with the
+-     same Internet port number; but the system won't allow you to use
+-     the two identically-named sockets in a way that would confuse the
+-     Internet.  The reason for this option is that some higher-level
+-     Internet protocols, including FTP, require you to keep reusing the
+-     same socket number.
+-
+-     The value has type `int'; a nonzero value means "yes".
+-
+-`SO_KEEPALIVE'
+-     This option controls whether the underlying protocol should
+-     periodically transmit messages on a connected socket.  If the peer
+-     fails to respond to these messages, the connection is considered
+-     broken.  The value has type `int'; a nonzero value means "yes".
+-
+-`SO_DONTROUTE'
+-     This option controls whether outgoing messages bypass the normal
+-     message routing facilities.  If set, messages are sent directly to
+-     the network interface instead.  The value has type `int'; a nonzero
+-     value means "yes".
+-
+-`SO_LINGER'
+-     This option specifies what should happen when the socket of a type
+-     that promises reliable delivery still has untransmitted messages
+-     when it is closed; see *Note Closing a Socket::.  The value has
+-     type `struct linger'.
+-
+-      - Data Type: struct linger
+-          This structure type has the following members:
+-
+-         `int l_onoff'
+-               This field is interpreted as a boolean.  If nonzero,
+-               `close' blocks until the data is transmitted or the
+-               timeout period has expired.
+-
+-         `int l_linger'
+-               This specifies the timeout period, in seconds.
+-
+-`SO_BROADCAST'
+-     This option controls whether datagrams may be broadcast from the
+-     socket.  The value has type `int'; a nonzero value means "yes".
+-
+-`SO_OOBINLINE'
+-     If this option is set, out-of-band data received on the socket is
+-     placed in the normal input queue.  This permits it to be read using
+-     `read' or `recv' without specifying the `MSG_OOB' flag.  *Note
+-     Out-of-Band Data::.  The value has type `int'; a nonzero value
+-     means "yes".
+-
+-`SO_SNDBUF'
+-     This option gets or sets the size of the output buffer.  The value
+-     is a `size_t', which is the size in bytes.
+-
+-`SO_RCVBUF'
+-     This option gets or sets the size of the input buffer.  The value
+-     is a `size_t', which is the size in bytes.
+-
+-`SO_STYLE'
+-`SO_TYPE'
+-     This option can be used with `getsockopt' only.  It is used to get
+-     the socket's communication style.  `SO_TYPE' is the historical
+-     name, and `SO_STYLE' is the preferred name in GNU.  The value has
+-     type `int' and its value designates a communication style; see
+-     *Note Communication Styles::.
+-
+-`SO_ERROR'
+-     This option can be used with `getsockopt' only.  It is used to
+-     reset the error status of the socket.  The value is an `int',
+-     which represents the previous error status.
+-
+-
+-File: libc.info,  Node: Networks Database,  Prev: Socket Options,  Up: Sockets
+-
+-Networks Database
+-=================
+-
+-   Many systems come with a database that records a list of networks
+-known to the system developer.  This is usually kept either in the file
+-`/etc/networks' or in an equivalent from a name server.  This data base
+-is useful for routing programs such as `route', but it is not useful
+-for programs that simply communicate over the network.  We provide
+-functions to access this data base, which are declared in `netdb.h'.
+-
+- - Data Type: struct netent
+-     This data type is used to represent information about entries in
+-     the networks database.  It has the following members:
+-
+-    `char *n_name'
+-          This is the "official" name of the network.
+-
+-    `char **n_aliases'
+-          These are alternative names for the network, represented as a
+-          vector of strings.  A null pointer terminates the array.
+-
+-    `int n_addrtype'
+-          This is the type of the network number; this is always equal
+-          to `AF_INET' for Internet networks.
+-
+-    `unsigned long int n_net'
+-          This is the network number.  Network numbers are returned in
+-          host byte order; see *Note Byte Order::.
+-
+-   Use the `getnetbyname' or `getnetbyaddr' functions to search the
+-networks database for information about a specific network.  The
+-information is returned in a statically-allocated structure; you must
+-copy the information if you need to save it.
+-
+- - Function: struct netent * getnetbyname (const char *NAME)
+-     The `getnetbyname' function returns information about the network
+-     named NAME.  It returns a null pointer if there is no such network.
+-
+- - Function: struct netent * getnetbyaddr (long NET, int TYPE)
+-     The `getnetbyaddr' function returns information about the network
+-     of type TYPE with number NET.  You should specify a value of
+-     `AF_INET' for the TYPE argument for Internet networks.
+-
+-     `getnetbyaddr' returns a null pointer if there is no such network.
+-
+-   You can also scan the networks database using `setnetent',
+-`getnetent', and `endnetent'.  Be careful in using these functions,
+-because they are not reentrant.
+-
+- - Function: void setnetent (int STAYOPEN)
+-     This function opens and rewinds the networks database.
+-
+-     If the STAYOPEN argument is nonzero, this sets a flag so that
+-     subsequent calls to `getnetbyname' or `getnetbyaddr' will not
+-     close the database (as they usually would).  This makes for more
+-     efficiency if you call those functions several times, by avoiding
+-     reopening the database for each call.
+-
+- - Function: struct netent * getnetent (void)
+-     This function returns the next entry in the networks database.  It
+-     returns a null pointer if there are no more entries.
+-
+- - Function: void endnetent (void)
+-     This function closes the networks database.
+-
+-
+-File: libc.info,  Node: Low-Level Terminal Interface,  Next: Mathematics,  
Prev: Sockets,  Up: Top
+-
+-Low-Level Terminal Interface
+-****************************
+-
+-   This chapter describes functions that are specific to terminal
+-devices.  You can use these functions to do things like turn off input
+-echoing; set serial line characteristics such as line speed and flow
+-control; and change which characters are used for end-of-file,
+-command-line editing, sending signals, and similar control functions.
+-
+-   Most of the functions in this chapter operate on file descriptors.
+-*Note Low-Level I/O::, for more information about what a file
+-descriptor is and how to open a file descriptor for a terminal device.
+-
+-* Menu:
+-
+-* Is It a Terminal::            How to determine if a file is a terminal
+-                               device, and what its name is.
+-* I/O Queues::                  About flow control and typeahead.
+-* Canonical or Not::            Two basic styles of input processing.
+-* Terminal Modes::              How to examine and modify flags controlling
+-                               details of terminal I/O: echoing,
+-                                 signals, editing.
+-* Line Control::                Sending break sequences, clearing
+-                                 terminal buffers ...
+-* Noncanon Example::            How to read single characters without echo.
+-
+-
+-File: libc.info,  Node: Is It a Terminal,  Next: I/O Queues,  Up: Low-Level 
Terminal Interface
+-
+-Identifying Terminals
+-=====================
+-
+-   The functions described in this chapter only work on files that
+-correspond to terminal devices.  You can find out whether a file
+-descriptor is associated with a terminal by using the `isatty' function.
+-
+-   Prototypes for both `isatty' and `ttyname' are declared in the
+-header file `unistd.h'.
+-
+- - Function: int isatty (int FILEDES)
+-     This function returns `1' if FILEDES is a file descriptor
+-     associated with an open terminal device, and `0' otherwise.
+-
+-   If a file descriptor is associated with a terminal, you can get its
+-associated file name using the `ttyname' function.  See also the
+-`ctermid' function, described in *Note Identifying the Terminal::.
+-
+- - Function: char * ttyname (int FILEDES)
+-     If the file descriptor FILEDES is associated with a terminal
+-     device, the `ttyname' function returns a pointer to a
+-     statically-allocated, null-terminated string containing the file
+-     name of the terminal file.  The value is a null pointer if the
+-     file descriptor isn't associated with a terminal, or the file name
+-     cannot be determined.
+-
+-
+-File: libc.info,  Node: I/O Queues,  Next: Canonical or Not,  Prev: Is It a 
Terminal,  Up: Low-Level Terminal Interface
+-
+-I/O Queues
+-==========
+-
+-   Many of the remaining functions in this section refer to the input
+-and output queues of a terminal device.  These queues implement a form
+-of buffering *within the kernel* independent of the buffering
+-implemented by I/O streams (*note I/O on Streams::.).
+-
+-   The "terminal input queue" is also sometimes referred to as its
+-"typeahead buffer".  It holds the characters that have been received
+-from the terminal but not yet read by any process.
+-
+-   The size of the terminal's input queue is described by the
+-`MAX_INPUT' and `_POSIX_MAX_INPUT' parameters; see *Note Limits for
+-Files::.  You are guaranteed a queue size of at least `MAX_INPUT', but
+-the queue might be larger, and might even dynamically change size.  If
+-input flow control is enabled by setting the `IXOFF' input mode bit
+-(*note Input Modes::.), the terminal driver transmits STOP and START
+-characters to the terminal when necessary to prevent the queue from
+-overflowing.  Otherwise, input may be lost if it comes in too fast from
+-the terminal.  In canonical mode, all input stays in the queue until a
+-newline character is received, so the terminal input queue can fill up
+-when you type a very long line.  *Note Canonical or Not::.
+-
+-   The "terminal output queue" is like the input queue, but for output;
+-it contains characters that have been written by processes, but not yet
+-transmitted to the terminal.  If output flow control is enabled by
+-setting the `IXON' input mode bit (*note Input Modes::.), the terminal
+-driver obeys STOP and STOP characters sent by the terminal to stop and
+-restart transmission of output.
+-
+-   "Clearing" the terminal input queue means discarding any characters
+-that have been received but not yet read.  Similarly, clearing the
+-terminal output queue means discarding any characters that have been
+-written but not yet transmitted.
+-
+-
+-File: libc.info,  Node: Canonical or Not,  Next: Terminal Modes,  Prev: I/O 
Queues,  Up: Low-Level Terminal Interface
+-
+-Two Styles of Input: Canonical or Not
+-=====================================
+-
+-   POSIX systems support two basic modes of input: canonical and
+-noncanonical.
+-
+-   In "canonical input processing" mode, terminal input is processed in
+-lines terminated by newline (`'\n''), EOF, or EOL characters.  No input
+-can be read until an entire line has been typed by the user, and the
+-`read' function (*note I/O Primitives::.) returns at most a single line
+-of input, no matter how many bytes are requested.
+-
+-   In canonical input mode, the operating system provides input editing
+-facilities: some characters are interpreted specially to perform editing
+-operations within the current line of text, such as ERASE and KILL.
+-*Note Editing Characters::.
+-
+-   The constants `_POSIX_MAX_CANON' and `MAX_CANON' parameterize the
+-maximum number of bytes which may appear in a single line of canonical
+-input.  *Note Limits for Files::.  You are guaranteed a maximum line
+-length of at least `MAX_CANON' bytes, but the maximum might be larger,
+-and might even dynamically change size.
+-
+-   In "noncanonical input processing" mode, characters are not grouped
+-into lines, and ERASE and KILL processing is not performed.  The
+-granularity with which bytes are read in noncanonical input mode is
+-controlled by the MIN and TIME settings.  *Note Noncanonical Input::.
+-
+-   Most programs use canonical input mode, because this gives the user a
+-way to edit input line by line.  The usual reason to use noncanonical
+-mode is when the program accepts single-character commands or provides
+-its own editing facilities.
+-
+-   The choice of canonical or noncanonical input is controlled by the
+-`ICANON' flag in the `c_lflag' member of `struct termios'.  *Note Local
+-Modes::.
+-
+-
+-File: libc.info,  Node: Terminal Modes,  Next: Line Control,  Prev: Canonical 
or Not,  Up: Low-Level Terminal Interface
+-
+-Terminal Modes
+-==============
+-
+-   This section describes the various terminal attributes that control
+-how input and output are done.  The functions, data structures, and
+-symbolic constants are all declared in the header file `termios.h'.
+-
+-* Menu:
+-
+-* Mode Data Types::             The data type `struct termios' and
+-                                 related types.
+-* Mode Functions::              Functions to read and set the terminal
+-                                 attributes.
+-* Setting Modes::               The right way to set terminal attributes
+-                                 reliably.
+-* Input Modes::                 Flags controlling low-level input handling.
+-* Output Modes::                Flags controlling low-level output handling.
+-* Control Modes::               Flags controlling serial port behavior.
+-* Local Modes::                 Flags controlling high-level input handling.
+-* Line Speed::                  How to read and set the terminal line speed.
+-* Special Characters::          Characters that have special effects,
+-                               and how to change them.
+-* Noncanonical Input::          Controlling how long to wait for input.
+-
+-
+-File: libc.info,  Node: Mode Data Types,  Next: Mode Functions,  Up: Terminal 
Modes
+-
+-Terminal Mode Data Types
+-------------------------
+-
+-   The entire collection of attributes of a terminal is stored in a
+-structure of type `struct termios'.  This structure is used with the
+-functions `tcgetattr' and `tcsetattr' to read and set the attributes.
+-
+- - Data Type: struct termios
+-     Structure that records all the I/O attributes of a terminal.  The
+-     structure includes at least the following members:
+-
+-    `tcflag_t c_iflag'
+-          A bit mask specifying flags for input modes; see *Note Input
+-          Modes::.
+-
+-    `tcflag_t c_oflag'
+-          A bit mask specifying flags for output modes; see *Note
+-          Output Modes::.
+-
+-    `tcflag_t c_cflag'
+-          A bit mask specifying flags for control modes; see *Note
+-          Control Modes::.
+-
+-    `tcflag_t c_lflag'
+-          A bit mask specifying flags for local modes; see *Note Local
+-          Modes::.
+-
+-    `cc_t c_cc[NCCS]'
+-          An array specifying which characters are associated with
+-          various control functions; see *Note Special Characters::.
+-
+-     The `struct termios' structure also contains members which encode
+-     input and output transmission speeds, but the representation is
+-     not specified.  *Note Line Speed::, for how to examine and store
+-     the speed values.
+-
+-   The following sections describe the details of the members of the
+-`struct termios' structure.
+-
+- - Data Type: tcflag_t
+-     This is an unsigned integer type used to represent the various bit
+-     masks for terminal flags.
+-
+- - Data Type: cc_t
+-     This is an unsigned integer type used to represent characters
+-     associated with various terminal control functions.
+-
+- - Macro: int NCCS
+-     The value of this macro is the number of elements in the `c_cc'
+-     array.
+-
+-
+-File: libc.info,  Node: Mode Functions,  Next: Setting Modes,  Prev: Mode 
Data Types,  Up: Terminal Modes
+-
+-Terminal Mode Functions
+------------------------
+-
+- - Function: int tcgetattr (int FILEDES, struct termios *TERMIOS-P)
+-     This function is used to examine the attributes of the terminal
+-     device with file descriptor FILEDES.  The attributes are returned
+-     in the structure that TERMIOS-P points to.
+-
+-     If successful, `tcgetattr' returns `0'.  A return value of `-1'
+-     indicates an error.  The following `errno' error conditions are
+-     defined for this function:
+-
+-    `EBADF'
+-          The FILEDES argument is not a valid file descriptor.
+-
+-    `ENOTTY'
+-          The FILEDES is not associated with a terminal.
+-
+- - Function: int tcsetattr (int FILEDES, int WHEN, const struct termios
+-          *TERMIOS-P)
+-     This function sets the attributes of the terminal device with file
+-     descriptor FILEDES.  The new attributes are taken from the
+-     structure that TERMIOS-P points to.
+-
+-     The WHEN argument specifies how to deal with input and output
+-     already queued.  It can be one of the following values:
+-
+-    `TCSANOW'
+-          Make the change immediately.
+-
+-    `TCSADRAIN'
+-          Make the change after waiting until all queued output has
+-          been written.  You should usually use this option when
+-          changing parameters that affect output.
+-
+-    `TCSAFLUSH'
+-          This is like `TCSADRAIN', but also discards any queued input.
+-
+-    `TCSASOFT'
+-          This is a flag bit that you can add to any of the above
+-          alternatives.  Its meaning is to inhibit alteration of the
+-          state of the terminal hardware.  It is a BSD extension; it is
+-          only supported on BSD systems and the GNU system.
+-
+-          Using `TCSASOFT' is exactly the same as setting the `CIGNORE'
+-          bit in the `c_cflag' member of the structure TERMIOS-P points
+-          to.  *Note Control Modes::, for a description of `CIGNORE'.
+-
+-     If this function is called from a background process on its
+-     controlling terminal, normally all processes in the process group
+-     are sent a `SIGTTOU' signal, in the same way as if the process
+-     were trying to write to the terminal.  The exception is if the
+-     calling process itself is ignoring or blocking `SIGTTOU' signals,
+-     in which case the operation is performed and no signal is sent.
+-     *Note Job Control::.
+-
+-     If successful, `tcsetattr' returns `0'.  A return value of `-1'
+-     indicates an error.  The following `errno' error conditions are
+-     defined for this function:
+-
+-    `EBADF'
+-          The FILEDES argument is not a valid file descriptor.
+-
+-    `ENOTTY'
+-          The FILEDES is not associated with a terminal.
+-
+-    `EINVAL'
+-          Either the value of the `when' argument is not valid, or
+-          there is something wrong with the data in the TERMIOS-P
+-          argument.
+-
+-   Although `tcgetattr' and `tcsetattr' specify the terminal device
+-with a file descriptor, the attributes are those of the terminal device
+-itself and not of the file descriptor.  This means that the effects of
+-changing terminal attributes are persistent; if another process opens
+-the terminal file later on, it will see the changed attributes even
+-though it doesn't have anything to do with the open file descriptor you
+-originally specified in changing the attributes.
+-
+-   Similarly, if a single process has multiple or duplicated file
+-descriptors for the same terminal device, changing the terminal
+-attributes affects input and output to all of these file descriptors.
+-This means, for example, that you can't open one file descriptor or
+-stream to read from a terminal in the normal line-buffered, echoed
+-mode; and simultaneously have another file descriptor for the same
+-terminal that you use to read from it in single-character, non-echoed
+-mode.  Instead, you have to explicitly switch the terminal back and
+-forth between the two modes.
+-
+-
+-File: libc.info,  Node: Setting Modes,  Next: Input Modes,  Prev: Mode 
Functions,  Up: Terminal Modes
+-
+-Setting Terminal Modes Properly
+--------------------------------
+-
+-   When you set terminal modes, you should call `tcgetattr' first to
+-get the current modes of the particular terminal device, modify only
+-those modes that you are really interested in, and store the result with
+-`tcsetattr'.
+-
+-   It's a bad idea to simply initialize a `struct termios' structure to
+-a chosen set of attributes and pass it directly to `tcsetattr'.  Your
+-program may be run years from now, on systems that support members not
+-documented in this manual.  The way to avoid setting these members to
+-unreasonable values is to avoid changing them.
+-
+-   What's more, different terminal devices may require different mode
+-settings in order to function properly.  So you should avoid blindly
+-copying attributes from one terminal device to another.
+-
+-   When a member contains a collection of independent flags, as the
+-`c_iflag', `c_oflag' and `c_cflag' members do, even setting the entire
+-member is a bad idea, because particular operating systems have their
+-own flags.  Instead, you should start with the current value of the
+-member and alter only the flags whose values matter in your program,
+-leaving any other flags unchanged.
+-
+-   Here is an example of how to set one flag (`ISTRIP') in the `struct
+-termios' structure while properly preserving all the other data in the
+-structure:
+-
+-     int
+-     set_istrip (int desc, int value)
+-     {
+-       struct termios settings;
+-       int result;
+-
+-     result = tcgetattr (desc, &settings);
+-       if (result < 0)
+-         {
+-           perror ("error in tcgetattr");
+-           return 0;
+-         }
+-
+-     settings.c_iflag &= ~ISTRIP;
+-       if (value)
+-         settings.c_iflag |= ISTRIP;
+-
+-     result = tcsetattr (desc, TCSANOW, &settings);
+-       if (result < 0)
+-         {
+-           perror ("error in tcgetattr");
+-           return;
+-        }
+-       return 1;
+-     }
+-
+-
+-File: libc.info,  Node: Input Modes,  Next: Output Modes,  Prev: Setting 
Modes,  Up: Terminal Modes
+-
+-Input Modes
+------------
+-
+-   This section describes the terminal attribute flags that control
+-fairly low-level aspects of input processing: handling of parity errors,
+-break signals, flow control, and <RET> and <LFD> characters.
+-
+-   All of these flags are bits in the `c_iflag' member of the `struct
+-termios' structure.  The member is an integer, and you change flags
+-using the operators `&', `|' and `^'.  Don't try to specify the entire
+-value for `c_iflag'--instead, change only specific flags and leave the
+-rest untouched (*note Setting Modes::.).
+-
+- - Macro: tcflag_t INPCK
+-     If this bit is set, input parity checking is enabled.  If it is
+-     not set, no checking at all is done for parity errors on input; the
+-     characters are simply passed through to the application.
+-
+-     Parity checking on input processing is independent of whether
+-     parity detection and generation on the underlying terminal
+-     hardware is enabled; see *Note Control Modes::.  For example, you
+-     could clear the `INPCK' input mode flag and set the `PARENB'
+-     control mode flag to ignore parity errors on input, but still
+-     generate parity on output.
+-
+-     If this bit is set, what happens when a parity error is detected
+-     depends on whether the `IGNPAR' or `PARMRK' bits are set.  If
+-     neither of these bits are set, a byte with a parity error is
+-     passed to the application as a `'\0'' character.
+-
+- - Macro: tcflag_t IGNPAR
+-     If this bit is set, any byte with a framing or parity error is
+-     ignored.  This is only useful if `INPCK' is also set.
+-
+- - Macro: tcflag_t PARMRK
+-     If this bit is set, input bytes with parity or framing errors are
+-     marked when passed to the program.  This bit is meaningful only
+-     when `INPCK' is set and `IGNPAR' is not set.
+-
+-     The way erroneous bytes are marked is with two preceding bytes,
+-     `377' and `0'.  Thus, the program actually reads three bytes for
+-     one erroneous byte received from the terminal.
+-
+-     If a valid byte has the value `0377', and `ISTRIP' (see below) is
+-     not set, the program might confuse it with the prefix that marks a
+-     parity error.  So a valid byte `0377' is passed to the program as
+-     two bytes, `0377' `0377', in this case.
+-
+- - Macro: tcflag_t ISTRIP
+-     If this bit is set, valid input bytes are stripped to seven bits;
+-     otherwise, all eight bits are available for programs to read.
+-
+- - Macro: tcflag_t IGNBRK
+-     If this bit is set, break conditions are ignored.
+-
+-     A "break condition" is defined in the context of asynchronous
+-     serial data transmission as a series of zero-value bits longer
+-     than a single byte.
+-
+- - Macro: tcflag_t BRKINT
+-     If this bit is set and `IGNBRK' is not set, a break condition
+-     clears the terminal input and output queues and raises a `SIGINT'
+-     signal for the foreground process group associated with the
+-     terminal.
+-
+-     If neither `BRKINT' nor `IGNBRK' are set, a break condition is
+-     passed to the application as a single `'\0'' character if `PARMRK'
+-     is not set, or otherwise as a three-character sequence `'\377'',
+-     `'\0'', `'\0''.
+-
+- - Macro: tcflag_t IGNCR
+-     If this bit is set, carriage return characters (`'\r'') are
+-     discarded on input.  Discarding carriage return may be useful on
+-     terminals that send both carriage return and linefeed when you
+-     type the <RET> key.
+-
+- - Macro: tcflag_t ICRNL
+-     If this bit is set and `IGNCR' is not set, carriage return
+-     characters (`'\r'') received as input are passed to the
+-     application as newline characters (`'\n'').
+-
+- - Macro: tcflag_t INLCR
+-     If this bit is set, newline characters (`'\n'') received as input
+-     are passed to the application as carriage return characters
+-     (`'\r'').
+-
+- - Macro: tcflag_t IXOFF
+-     If this bit is set, start/stop control on input is enabled.  In
+-     other words, the computer sends STOP and START characters as
+-     necessary to prevent input from coming in faster than programs are
+-     reading it.  The idea is that the actual terminal hardware that is
+-     generating the input data responds to a STOP character by
+-     suspending transmission, and to a START character by resuming
+-     transmission.  *Note Start/Stop Characters::.
+-
+- - Macro: tcflag_t IXON
+-     If this bit is set, start/stop control on output is enabled.  In
+-     other words, if the computer receives a STOP character, it
+-     suspends output until a START character is received.  In this
+-     case, the STOP and START characters are never passed to the
+-     application program.  If this bit is not set, then START and STOP
+-     can be read as ordinary characters.  *Note Start/Stop Characters::.
+-
+- - Macro: tcflag_t IXANY
+-     If this bit is set, any input character restarts output when
+-     output has been suspended with the STOP character.  Otherwise,
+-     only the START character restarts output.
+-
+-     This is a BSD extension; it exists only on BSD systems and the GNU
+-     system.
+-
+- - Macro: tcflag_t IMAXBEL
+-     If this bit is set, then filling up the terminal input buffer
+-     sends a BEL character (code `007') to the terminal to ring the
+-     bell.
+-
+-     This is a BSD extension.
+-
+-
+-File: libc.info,  Node: Output Modes,  Next: Control Modes,  Prev: Input 
Modes,  Up: Terminal Modes
+-
+-Output Modes
+-------------
+-
+-   This section describes the terminal flags and fields that control how
+-output characters are translated and padded for display.  All of these
+-are contained in the `c_oflag' member of the `struct termios' structure.
+-
+-   The `c_oflag' member itself is an integer, and you change the flags
+-and fields using the operators `&', `|', and `^'.  Don't try to specify
+-the entire value for `c_oflag'--instead, change only specific flags and
+-leave the rest untouched (*note Setting Modes::.).
+-
+- - Macro: tcflag_t OPOST
+-     If this bit is set, output data is processed in some unspecified
+-     way so that it is displayed appropriately on the terminal device.
+-     This typically includes mapping newline characters (`'\n'') onto
+-     carriage return and linefeed pairs.
+-
+-     If this bit isn't set, the characters are transmitted as-is.
+-
+-   The following three bits are BSD features, and they exist only BSD
+-systems and the GNU system.  They are effective only if `OPOST' is set.
+-
+- - Macro: tcflag_t ONLCR
+-     If this bit is set, convert the newline character on output into a
+-     pair of characters, carriage return followed by linefeed.
+-
+- - Macro: tcflag_t OXTABS
+-     If this bit is set, convert tab characters on output into the
+-     appropriate number of spaces to emulate a tab stop every eight
+-     columns.
+-
+- - Macro: tcflag_t ONOEOT
+-     If this bit is set, discard `C-d' characters (code `004') on
+-     output.  These characters cause many dial-up terminals to
+-     disconnect.
+-
+-
+-File: libc.info,  Node: Control Modes,  Next: Local Modes,  Prev: Output 
Modes,  Up: Terminal Modes
+-
+-Control Modes
+--------------
+-
+-   This section describes the terminal flags and fields that control
+-parameters usually associated with asynchronous serial data
+-transmission.  These flags may not make sense for other kinds of
+-terminal ports (such as a network connection pseudo-terminal).  All of
+-these are contained in the `c_cflag' member of the `struct termios'
+-structure.
+-
+-   The `c_cflag' member itself is an integer, and you change the flags
+-and fields using the operators `&', `|', and `^'.  Don't try to specify
+-the entire value for `c_cflag'--instead, change only specific flags and
+-leave the rest untouched (*note Setting Modes::.).
+-
+- - Macro: tcflag_t CLOCAL
+-     If this bit is set, it indicates that the terminal is connected
+-     "locally" and that the modem status lines (such as carrier detect)
+-     should be ignored.
+-
+-     On many systems if this bit is not set and you call `open' without
+-     the `O_NONBLOCK' flag set, `open' blocks until a modem connection
+-     is established.
+-
+-     If this bit is not set and a modem disconnect is detected, a
+-     `SIGHUP' signal is sent to the controlling process group for the
+-     terminal (if it has one).  Normally, this causes the process to
+-     exit; see *Note Signal Handling::.  Reading from the terminal
+-     after a disconnect causes an end-of-file condition, and writing
+-     causes an `EIO' error to be returned.  The terminal device must be
+-     closed and reopened to clear the condition.
+-
+- - Macro: tcflag_t HUPCL
+-     If this bit is set, a modem disconnect is generated when all
+-     processes that have the terminal device open have either closed
+-     the file or exited.
+-
+- - Macro: tcflag_t CREAD
+-     If this bit is set, input can be read from the terminal.
+-     Otherwise, input is discarded when it arrives.
+-
+- - Macro: tcflag_t CSTOPB
+-     If this bit is set, two stop bits are used.  Otherwise, only one
+-     stop bit is used.
+-
+- - Macro: tcflag_t PARENB
+-     If this bit is set, generation and detection of a parity bit are
+-     enabled.  *Note Input Modes::, for information on how input parity
+-     errors are handled.
+-
+-     If this bit is not set, no parity bit is added to output
+-     characters, and input characters are not checked for correct
+-     parity.
+-
+- - Macro: tcflag_t PARODD
+-     This bit is only useful if `PARENB' is set.  If `PARODD' is set,
+-     odd parity is used, otherwise even parity is used.
+-
+-   The control mode flags also includes a field for the number of bits
+-per character.  You can use the `CSIZE' macro as a mask to extract the
+-value, like this: `settings.c_cflag & CSIZE'.
+-
+- - Macro: tcflag_t CSIZE
+-     This is a mask for the number of bits per character.
+-
+- - Macro: tcflag_t CS5
+-     This specifies five bits per byte.
+-
+- - Macro: tcflag_t CS6
+-     This specifies six bits per byte.
+-
+- - Macro: tcflag_t CS7
+-     This specifies seven bits per byte.
+-
+- - Macro: tcflag_t CS8
+-     This specifies eight bits per byte.
+-
+-   The following four bits are BSD extensions; this exist only on BSD
+-systems and the GNU system.
+-
+- - Macro: tcflag_t CCTS_OFLOW
+-     If this bit is set, enable flow control of output based on the CTS
+-     wire (RS232 protocol).
+-
+- - Macro: tcflag_t CRTS_IFLOW
+-     If this bit is set, enable flow control of input based on the RTS
+-     wire (RS232 protocol).
+-
+- - Macro: tcflag_t MDMBUF
+-     If this bit is set, enable carrier-based flow control of output.
+-
+- - Macro: tcflag_t CIGNORE
+-     If this bit is set, it says to ignore the control modes and line
+-     speed values entirely.  This is only meaningful in a call to
+-     `tcsetattr'.
+-
+-     The `c_cflag' member and the line speed values returned by
+-     `cfgetispeed' and `cfgetospeed' will be unaffected by the call.
+-     `CIGNORE' is useful if you want to set all the software modes in
+-     the other members, but leave the hardware details in `c_cflag'
+-     unchanged.  (This is how the `TCSASOFT' flag to `tcsettattr'
+-     works.)
+-
+-     This bit is never set in the structure filled in by `tcgetattr'.
+-
+-
+-File: libc.info,  Node: Local Modes,  Next: Line Speed,  Prev: Control Modes, 
 Up: Terminal Modes
+-
+-Local Modes
+------------
+-
+-   This section describes the flags for the `c_lflag' member of the
+-`struct termios' structure.  These flags generally control higher-level
+-aspects of input processing than the input modes flags described in
+-*Note Input Modes::, such as echoing, signals, and the choice of
+-canonical or noncanonical input.
+-
+-   The `c_lflag' member itself is an integer, and you change the flags
+-and fields using the operators `&', `|', and `^'.  Don't try to specify
+-the entire value for `c_lflag'--instead, change only specific flags and
+-leave the rest untouched (*note Setting Modes::.).
+-
+- - Macro: tcflag_t ICANON
+-     This bit, if set, enables canonical input processing mode.
+-     Otherwise, input is processed in noncanonical mode.  *Note
+-     Canonical or Not::.
+-
+- - Macro: tcflag_t ECHO
+-     If this bit is set, echoing of input characters back to the
+-     terminal is enabled.
+-
+- - Macro: tcflag_t ECHOE
+-     If this bit is set, echoing indicates erasure of input with the
+-     ERASE character by erasing the last character in the current line
+-     from the screen.  Otherwise, the character erased is re-echoed to
+-     show what has happened (suitable for a printing terminal).
+-
+-     This bit only controls the display behavior; the `ICANON' bit by
+-     itself controls actual recognition of the ERASE character and
+-     erasure of input, without which `ECHOE' is simply irrelevant.
+-
+- - Macro: tcflag_t ECHOPRT
+-     This bit is like `ECHOE', enables display of the ERASE character in
+-     a way that is geared to a hardcopy terminal.  When you type the
+-     ERASE character, a `\' character is printed followed by the first
+-     character erased.  Typing the ERASE character again just prints
+-     the next character erased.  Then, the next time you type a normal
+-     character, a `/' character is printed before the character echoes.
+-
+-     This is a BSD extension, and exists only in BSD systems and the
+-     GNU system.
+-
+- - Macro: tcflag_t ECHOK
+-     This bit enables special display of the KILL character by moving
+-     to a new line after echoing the KILL character normally.  The
+-     behavior of `ECHOKE' (below) is nicer to look at.
+-
+-     If this bit is not set, the KILL character echoes just as it would
+-     if it were not the KILL character.  Then it is up to the user to
+-     remember that the KILL character has erased the preceding input;
+-     there is no indication of this on the screen.
+-
+-     This bit only controls the display behavior; the `ICANON' bit by
+-     itself controls actual recognition of the KILL character and
+-     erasure of input, without which `ECHOK' is simply irrelevant.
+-
+- - Macro: tcflag_t ECHOKE
+-     This bit is similar to `ECHOK'.  It enables special display of the
+-     KILL character by erasing on the screen the entire line that has
+-     been killed.  This is a BSD extension, and exists only in BSD
+-     systems and the GNU system.
+-
+- - Macro: tcflag_t ECHONL
+-     If this bit is set and the `ICANON' bit is also set, then the
+-     newline (`'\n'') character is echoed even if the `ECHO' bit is not
+-     set.
+-
+- - Macro: tcflag_t ECHOCTL
+-     If this bit is set and the `ECHO' bit is also set, echo control
+-     characters with `^' followed by the corresponding text character.
+-     Thus, control-A echoes as `^A'.  This is usually the preferred mode
+-     for interactive input, because echoing a control character back to
+-     the terminal could have some undesired effect on the terminal.
+-
+-     This is a BSD extension, and exists only in BSD systems and the
+-     GNU system.
+-
+- - Macro: tcflag_t ISIG
+-     This bit controls whether the INTR, QUIT, and SUSP characters are
+-     recognized.  The functions associated with these characters are
+-     performed if and only if this bit is set.  Being in canonical or
+-     noncanonical input mode has no affect on the interpretation of
+-     these characters.
+-
+-     You should use caution when disabling recognition of these
+-     characters.  Programs that cannot be interrupted interactively are
+-     very user-unfriendly.  If you clear this bit, your program should
+-     provide some alternate interface that allows the user to
+-     interactively send the signals associated with these characters,
+-     or to escape from the program.
+-
+-     *Note Signal Characters::.
+-
+- - Macro: tcflag_t IEXTEN
+-     POSIX.1 gives `IEXTEN' implementation-defined meaning, so you
+-     cannot rely on this interpretation on all systems.
+-
+-     On BSD systems and the GNU system, it enables the LNEXT and
+-     DISCARD characters.  *Note Other Special::.
+-
+- - Macro: tcflag_t NOFLSH
+-     Normally, the INTR, QUIT, and SUSP characters cause input and
+-     output queues for the terminal to be cleared.  If this bit is set,
+-     the queues are not cleared.
+-
+- - Macro: tcflag_t TOSTOP
+-     If this bit is set and the system supports job control, then
+-     `SIGTTOU' signals are generated by background processes that
+-     attempt to write to the terminal.  *Note Access to the Terminal::.
+-
+-   The following bits are BSD extensions; they exist only in BSD systems
+-and the GNU system.
+-
+- - Macro: tcflag_t ALTWERASE
+-     This bit determines how far the WERASE character should erase.  The
+-     WERASE character erases back to the beginning of a word; the
+-     question is, where do words begin?
+-
+-     If this bit is clear, then the beginning of a word is a
+-     nonwhitespace character following a whitespace character.  If the
+-     bit is set, then the beginning of a word is an alphanumeric
+-     character or underscore following a character which is none of
+-     those.
+-
+-     *Note Editing Characters::, for more information about the WERASE
+-     character.
+-
+- - Macro: tcflag_t FLUSHO
+-     This is the bit that toggles when the user types the DISCARD
+-     character.  While this bit is set, all output is discarded.  *Note
+-     Other Special::.
+-
+- - Macro: tcflag_t NOKERNINFO
+-     Setting this bit disables handling of the STATUS character.  *Note
+-     Other Special::.
+-
+- - Macro: tcflag_t PENDIN
+-     If this bit is set, it indicates that there is a line of input that
+-     needs to be reprinted.  Typing the REPRINT character sets this
+-     bit; the bit remains set until reprinting is finished.  *Note
+-     Editing Characters::.
+-
+-
+-File: libc.info,  Node: Line Speed,  Next: Special Characters,  Prev: Local 
Modes,  Up: Terminal Modes
+-
+-Line Speed
+-----------
+-
+-   The terminal line speed tells the computer how fast to read and write
+-data on the terminal.
+-
+-   If the terminal is connected to a real serial line, the terminal
+-speed you specify actually controls the line--if it doesn't match the
+-terminal's own idea of the speed, communication does not work.  Real
+-serial ports accept only certain standard speeds.  Also, particular
+-hardware may not support even all the standard speeds.  Specifying a
+-speed of zero hangs up a dialup connection and turns off modem control
+-signals.
+-
+-   If the terminal is not a real serial line (for example, if it is a
+-network connection), then the line speed won't really affect data
+-transmission speed, but some programs will use it to determine the
+-amount of padding needed.  It's best to specify a line speed value that
+-matches the actual speed of the actual terminal, but you can safely
+-experiment with different values to vary the amount of padding.
+-
+-   There are actually two line speeds for each terminal, one for input
+-and one for output.  You can set them independently, but most often
+-terminals use the same speed for both directions.
+-
+-   The speed values are stored in the `struct termios' structure, but
+-don't try to access them in the `struct termios' structure directly.
+-Instead, you should use the following functions to read and store them:
+-
+- - Function: speed_t cfgetospeed (const struct termios *TERMIOS-P)
+-     This function returns the output line speed stored in the structure
+-     `*TERMIOS-P'.
+-
+- - Function: speed_t cfgetispeed (const struct termios *TERMIOS-P)
+-     This function returns the input line speed stored in the structure
+-     `*TERMIOS-P'.
+-
+- - Function: int cfsetospeed (struct termios *TERMIOS-P, speed_t SPEED)
+-     This function stores SPEED in `*TERMIOS-P' as the output speed.
+-     The normal return value is `0'; a value of `-1' indicates an
+-     error.  If SPEED is not a speed, `cfsetospeed' returns `-1'.
+-
+- - Function: int cfsetispeed (struct termios *TERMIOS-P, speed_t SPEED)
+-     This function stores SPEED in `*TERMIOS-P' as the input speed.
+-     The normal return value is `0'; a value of `-1' indicates an
+-     error.  If SPEED is not a speed, `cfsetospeed' returns `-1'.
+-
+- - Function: int cfsetspeed (struct termios *TERMIOS-P, speed_t SPEED)
+-     This function stores SPEED in `*TERMIOS-P' as both the input and
+-     output speeds.  The normal return value is `0'; a value of `-1'
+-     indicates an error.  If SPEED is not a speed, `cfsetspeed' returns
+-     `-1'.  This function is an extension in 4.4 BSD.
+-
+- - Data Type: speed_t
+-     The `speed_t' type is an unsigned integer data type used to
+-     represent line speeds.
+-
+-   The functions `cfsetospeed' and `cfsetispeed' report errors only for
+-speed values that the system simply cannot handle.  If you specify a
+-speed value that is basically acceptable, then those functions will
+-succeed.  But they do not check that a particular hardware device can
+-actually support the specified speeds--in fact, they don't know which
+-device you plan to set the speed for.  If you use `tcsetattr' to set
+-the speed of a particular device to a value that it cannot handle,
+-`tcsetattr' returns `-1'.
+-
+-   *Portability note:* In the GNU library, the functions above accept
+-speeds measured in bits per second as input, and return speed values
+-measured in bits per second.  Other libraries require speeds to be
+-indicated by special codes.  For POSIX.1 portability, you must use one
+-of the following symbols to represent the speed; their precise numeric
+-values are system-dependent, but each name has a fixed meaning: `B110'
+-stands for 110 bps, `B300' for 300 bps, and so on.  There is no
+-portable way to represent any speed but these, but these are the only
+-speeds that typical serial lines can support.
+-
+-     B0  B50  B75  B110  B134  B150  B200
+-     B300  B600  B1200  B1800  B2400  B4800
+-     B9600  B19200  B38400
+-
+-   BSD defines two additional speed symbols as aliases: `EXTA' is an
+-alias for `B19200' and `EXTB' is an alias for `B38400'.  These aliases
+-are obsolete.
+-
+-
+-File: libc.info,  Node: Special Characters,  Next: Noncanonical Input,  Prev: 
Line Speed,  Up: Terminal Modes
+-
+-Special Characters
+-------------------
+-
+-   In canonical input, the terminal driver recognizes a number of
+-special characters which perform various control functions.  These
+-include the ERASE character (usually <DEL>) for editing input, and
+-other editing characters.  The INTR character (normally `C-c') for
+-sending a `SIGINT' signal, and other signal-raising characters, may be
+-available in either canonical or noncanonical input mode.  All these
+-characters are described in this section.
+-
+-   The particular characters used are specified in the `c_cc' member of
+-the `struct termios' structure.  This member is an array; each element
+-specifies the character for a particular role.  Each element has a
+-symbolic constant that stands for the index of that element--for
+-example, `INTR' is the index of the element that specifies the INTR
+-character, so storing `'='' in `TERMIOS.c_cc[INTR]' specifies `=' as
+-the INTR character.
+-
+-   On some systems, you can disable a particular special character
+-function by specifying the value `_POSIX_VDISABLE' for that role.  This
+-value is unequal to any possible character code.  *Note Options for
+-Files::, for more information about how to tell whether the operating
+-system you are using supports `_POSIX_VDISABLE'.
+-
+-* Menu:
+-
+-* Editing Characters::          Special characters that terminate lines and
+-                                  delete text, and other editing functions.
+-* Signal Characters::           Special characters that send or raise signals
+-                                  to or for certain classes of processes.
+-* Start/Stop Characters::       Special characters that suspend or resume
+-                                  suspended output.
+-* Other Special::             Other special characters for BSD systems:
+-                                they can discard output, and print status.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-15 
glibc-2.0.1/manual/libc.info-15
+--- ../glibc-2.0.1/manual/libc.info-15 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-15    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1220 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Editing Characters,  Next: Signal Characters,  Up: 
Special Characters
+-
+-Characters for Input Editing
+-............................
+-
+-   These special characters are active only in canonical input mode.
+-*Note Canonical or Not::.
+-
+- - Macro: int VEOF
+-     This is the subscript for the EOF character in the special control
+-     character array.  `TERMIOS.c_cc[VEOF]' holds the character itself.
+-
+-     The EOF character is recognized only in canonical input mode.  It
+-     acts as a line terminator in the same way as a newline character,
+-     but if the EOF character is typed at the beginning of a line it
+-     causes `read' to return a byte count of zero, indicating
+-     end-of-file.  The EOF character itself is discarded.
+-
+-     Usually, the EOF character is `C-d'.
+-
+- - Macro: int VEOL
+-     This is the subscript for the EOL character in the special control
+-     character array.  `TERMIOS.c_cc[VEOL]' holds the character itself.
+-
+-     The EOL character is recognized only in canonical input mode.  It
+-     acts as a line terminator, just like a newline character.  The EOL
+-     character is not discarded; it is read as the last character in
+-     the input line.
+-
+-     You don't need to use the EOL character to make <RET> end a line.
+-     Just set the ICRNL flag.  In fact, this is the default state of
+-     affairs.
+-
+- - Macro: int VEOL2
+-     This is the subscript for the EOL2 character in the special control
+-     character array.  `TERMIOS.c_cc[VEOL2]' holds the character itself.
+-
+-     The EOL2 character works just like the EOL character (see above),
+-     but it can be a different character.  Thus, you can specify two
+-     characters to terminate an input line, by setting EOL to one of
+-     them and EOL2 to the other.
+-
+-     The EOL2 character is a BSD extension; it exists only on BSD
+-     systems and the GNU system.
+-
+- - Macro: int VERASE
+-     This is the subscript for the ERASE character in the special
+-     control character array.  `TERMIOS.c_cc[VERASE]' holds the
+-     character itself.
+-
+-     The ERASE character is recognized only in canonical input mode.
+-     When the user types the erase character, the previous character
+-     typed is discarded.  (If the terminal generates multibyte
+-     character sequences, this may cause more than one byte of input to
+-     be discarded.)  This cannot be used to erase past the beginning of
+-     the current line of text.  The ERASE character itself is discarded.
+-
+-     Usually, the ERASE character is <DEL>.
+-
+- - Macro: int VWERASE
+-     This is the subscript for the WERASE character in the special
+-     control character array.  `TERMIOS.c_cc[VWERASE]' holds the
+-     character itself.
+-
+-     The WERASE character is recognized only in canonical mode.  It
+-     erases an entire word of prior input, and any whitespace after it;
+-     whitespace characters before the word are not erased.
+-
+-     The definition of a "word" depends on the setting of the
+-     `ALTWERASE' mode; *note Local Modes::..
+-
+-     If the `ALTWERASE' mode is not set, a word is defined as a sequence
+-     of any characters except space or tab.
+-
+-     If the `ALTWERASE' mode is set, a word is defined as a sequence of
+-     characters containing only letters, numbers, and underscores,
+-     optionally followed by one character that is not a letter, number,
+-     or underscore.
+-
+-     The WERASE character is usually `C-w'.
+-
+-     This is a BSD extension.
+-
+- - Macro: int VKILL
+-     This is the subscript for the KILL character in the special control
+-     character array.  `TERMIOS.c_cc[VKILL]' holds the character itself.
+-
+-     The KILL character is recognized only in canonical input mode.
+-     When the user types the kill character, the entire contents of the
+-     current line of input are discarded.  The kill character itself is
+-     discarded too.
+-
+-     The KILL character is usually `C-u'.
+-
+- - Macro: int VREPRINT
+-     This is the subscript for the REPRINT character in the special
+-     control character array.  `TERMIOS.c_cc[VREPRINT]' holds the
+-     character itself.
+-
+-     The REPRINT character is recognized only in canonical mode.  It
+-     reprints the current input line.  If some asynchronous output has
+-     come while you are typing, this lets you see the line you are
+-     typing clearly again.
+-
+-     The REPRINT character is usually `C-r'.
+-
+-     This is a BSD extension.
+-
+-
+-File: libc.info,  Node: Signal Characters,  Next: Start/Stop Characters,  
Prev: Editing Characters,  Up: Special Characters
+-
+-Characters that Cause Signals
+-.............................
+-
+-   These special characters may be active in either canonical or
+-noncanonical input mode, but only when the `ISIG' flag is set (*note
+-Local Modes::.).
+-
+- - Macro: int VINTR
+-     This is the subscript for the INTR character in the special control
+-     character array.  `TERMIOS.c_cc[VINTR]' holds the character itself.
+-
+-     The INTR (interrupt) character raises a `SIGINT' signal for all
+-     processes in the foreground job associated with the terminal.  The
+-     INTR character itself is then discarded.  *Note Signal Handling::,
+-     for more information about signals.
+-
+-     Typically, the INTR character is `C-c'.
+-
+- - Macro: int VQUIT
+-     This is the subscript for the QUIT character in the special control
+-     character array.  `TERMIOS.c_cc[VQUIT]' holds the character itself.
+-
+-     The QUIT character raises a `SIGQUIT' signal for all processes in
+-     the foreground job associated with the terminal.  The QUIT
+-     character itself is then discarded.  *Note Signal Handling::, for
+-     more information about signals.
+-
+-     Typically, the QUIT character is `C-\'.
+-
+- - Macro: int VSUSP
+-     This is the subscript for the SUSP character in the special control
+-     character array.  `TERMIOS.c_cc[VSUSP]' holds the character itself.
+-
+-     The SUSP (suspend) character is recognized only if the
+-     implementation supports job control (*note Job Control::.).  It
+-     causes a `SIGTSTP' signal to be sent to all processes in the
+-     foreground job associated with the terminal.  The SUSP character
+-     itself is then discarded.  *Note Signal Handling::, for more
+-     information about signals.
+-
+-     Typically, the SUSP character is `C-z'.
+-
+-   Few applications disable the normal interpretation of the SUSP
+-character.  If your program does this, it should provide some other
+-mechanism for the user to stop the job.  When the user invokes this
+-mechanism, the program should send a `SIGTSTP' signal to the process
+-group of the process, not just to the process itself.  *Note Signaling
+-Another Process::.
+-
+- - Macro: int VDSUSP
+-     This is the subscript for the DSUSP character in the special
+-     control character array.  `TERMIOS.c_cc[VDSUSP]' holds the
+-     character itself.
+-
+-     The DSUSP (suspend) character is recognized only if the
+-     implementation supports job control (*note Job Control::.).  It
+-     sends a `SIGTSTP' signal, like the SUSP character, but not right
+-     away--only when the program tries to read it as input.  Not all
+-     systems with job control support DSUSP; only BSD-compatible
+-     systems (including the GNU system).
+-
+-     *Note Signal Handling::, for more information about signals.
+-
+-     Typically, the DSUSP character is `C-y'.
+-
+-
+-File: libc.info,  Node: Start/Stop Characters,  Next: Other Special,  Prev: 
Signal Characters,  Up: Special Characters
+-
+-Special Characters for Flow Control
+-...................................
+-
+-   These special characters may be active in either canonical or
+-noncanonical input mode, but their use is controlled by the flags
+-`IXON' and `IXOFF' (*note Input Modes::.).
+-
+- - Macro: int VSTART
+-     This is the subscript for the START character in the special
+-     control character array.  `TERMIOS.c_cc[VSTART]' holds the
+-     character itself.
+-
+-     The START character is used to support the `IXON' and `IXOFF'
+-     input modes.  If `IXON' is set, receiving a START character resumes
+-     suspended output; the START character itself is discarded.  If
+-     `IXANY' is set, receiving any character at all resumes suspended
+-     output; the resuming character is not discarded unless it is the
+-     START character.  `IXOFF' is set, the system may also transmit
+-     START characters to the terminal.
+-
+-     The usual value for the START character is `C-q'.  You may not be
+-     able to change this value--the hardware may insist on using `C-q'
+-     regardless of what you specify.
+-
+- - Macro: int VSTOP
+-     This is the subscript for the STOP character in the special control
+-     character array.  `TERMIOS.c_cc[VSTOP]' holds the character itself.
+-
+-     The STOP character is used to support the `IXON' and `IXOFF' input
+-     modes.  If `IXON' is set, receiving a STOP character causes output
+-     to be suspended; the STOP character itself is discarded.  If
+-     `IXOFF' is set, the system may also transmit STOP characters to the
+-     terminal, to prevent the input queue from overflowing.
+-
+-     The usual value for the STOP character is `C-s'.  You may not be
+-     able to change this value--the hardware may insist on using `C-s'
+-     regardless of what you specify.
+-
+-
+-File: libc.info,  Node: Other Special,  Prev: Start/Stop Characters,  Up: 
Special Characters
+-
+-Other Special Characters
+-........................
+-
+-   These special characters exist only in BSD systems and the GNU
+-system.
+-
+- - Macro: int VLNEXT
+-     This is the subscript for the LNEXT character in the special
+-     control character array.  `TERMIOS.c_cc[VLNEXT]' holds the
+-     character itself.
+-
+-     The LNEXT character is recognized only when `IEXTEN' is set, but in
+-     both canonical and noncanonical mode.  It disables any special
+-     significance of the next character the user types.  Even if the
+-     character would normally perform some editing function or generate
+-     a signal, it is read as a plain character.  This is the analogue
+-     of the `C-q' command in Emacs.  "LNEXT" stands for "literal next."
+-
+-     The LNEXT character is usually `C-v'.
+-
+- - Macro: int VDISCARD
+-     This is the subscript for the DISCARD character in the special
+-     control character array.  `TERMIOS.c_cc[VDISCARD]' holds the
+-     character itself.
+-
+-     The DISCARD character is recognized only when `IEXTEN' is set, but
+-     in both canonical and noncanonical mode.  Its effect is to toggle
+-     the discard-output flag.  When this flag is set, all program
+-     output is discarded.  Setting the flag also discards all output
+-     currently in the output buffer.  Typing any other character resets
+-     the flag.
+-
+- - Macro: int VSTATUS
+-     This is the subscript for the STATUS character in the special
+-     control character array.  `TERMIOS.c_cc[VSTATUS]' holds the
+-     character itself.
+-
+-     The STATUS character's effect is to print out a status message
+-     about how the current process is running.
+-
+-     The STATUS character is recognized only in canonical mode, and
+-     only if `NOKERNINFO' is not set.
+-
+-
+-File: libc.info,  Node: Noncanonical Input,  Prev: Special Characters,  Up: 
Terminal Modes
+-
+-Noncanonical Input
+-------------------
+-
+-   In noncanonical input mode, the special editing characters such as
+-ERASE and KILL are ignored.  The system facilities for the user to edit
+-input are disabled in noncanonical mode, so that all input characters
+-(unless they are special for signal or flow-control purposes) are passed
+-to the application program exactly as typed.  It is up to the
+-application program to give the user ways to edit the input, if
+-appropriate.
+-
+-   Noncanonical mode offers special parameters called MIN and TIME for
+-controlling whether and how long to wait for input to be available.  You
+-can even use them to avoid ever waiting--to return immediately with
+-whatever input is available, or with no input.
+-
+-   The MIN and TIME are stored in elements of the `c_cc' array, which
+-is a member of the `struct termios' structure.  Each element of this
+-array has a particular role, and each element has a symbolic constant
+-that stands for the index of that element.  `VMIN' and `VMAX' are the
+-names for the indices in the array of the MIN and TIME slots.
+-
+- - Macro: int VMIN
+-     This is the subscript for the MIN slot in the `c_cc' array.  Thus,
+-     `TERMIOS.c_cc[VMIN]' is the value itself.
+-
+-     The MIN slot is only meaningful in noncanonical input mode; it
+-     specifies the minimum number of bytes that must be available in the
+-     input queue in order for `read' to return.
+-
+- - Macro: int VTIME
+-     This is the subscript for the TIME slot in the `c_cc' array.  Thus,
+-     `TERMIOS.c_cc[VTIME]' is the value itself.
+-
+-     The TIME slot is only meaningful in noncanonical input mode; it
+-     specifies how long to wait for input before returning, in units of
+-     0.1 seconds.
+-
+-   The MIN and TIME values interact to determine the criterion for when
+-`read' should return; their precise meanings depend on which of them
+-are nonzero.  There are four possible cases:
+-
+-   * Both TIME and MIN are nonzero.
+-
+-     In this case, TIME specifies how long to wait after each input
+-     character to see if more input arrives.  After the first character
+-     received, `read' keeps waiting until either MIN bytes have arrived
+-     in all, or TIME elapses with no further input.
+-
+-     `read' always blocks until the first character arrives, even if
+-     TIME elapses first.  `read' can return more than MIN characters if
+-     more than MIN happen to be in the queue.
+-
+-   * Both MIN and TIME are zero.
+-
+-     In this case, `read' always returns immediately with as many
+-     characters as are available in the queue, up to the number
+-     requested.  If no input is immediately available, `read' returns a
+-     value of zero.
+-
+-   * MIN is zero but TIME has a nonzero value.
+-
+-     In this case, `read' waits for time TIME for input to become
+-     available; the availability of a single byte is enough to satisfy
+-     the read request and cause `read' to return.  When it returns, it
+-     returns as many characters as are available, up to the number
+-     requested.  If no input is available before the timer expires,
+-     `read' returns a value of zero.
+-
+-   * TIME is zero but MIN has a nonzero value.
+-
+-     In this case, `read' waits until at least MIN bytes are available
+-     in the queue.  At that time, `read' returns as many characters as
+-     are available, up to the number requested.  `read' can return more
+-     than MIN characters if more than MIN happen to be in the queue.
+-
+-   What happens if MIN is 50 and you ask to read just 10 bytes?
+-Normally, `read' waits until there are 50 bytes in the buffer (or, more
+-generally, the wait condition described above is satisfied), and then
+-reads 10 of them, leaving the other 40 buffered in the operating system
+-for a subsequent call to `read'.
+-
+-   *Portability note:* On some systems, the MIN and TIME slots are
+-actually the same as the EOF and EOL slots.  This causes no serious
+-problem because the MIN and TIME slots are used only in noncanonical
+-input and the EOF and EOL slots are used only in canonical input, but it
+-isn't very clean.  The GNU library allocates separate slots for these
+-uses.
+-
+- - Function: int cfmakeraw (struct termios *TERMIOS-P)
+-     This function provides an easy way to set up `*TERMIOS-P' for what
+-     has traditionally been called "raw mode" in BSD.  This uses
+-     noncanonical input, and turns off most processing to give an
+-     unmodified channel to the terminal.
+-
+-     It does exactly this:
+-            TERMIOS-P->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
+-                                          |INLCR|IGNCR|ICRNL|IXON);
+-            TERMIOS-P->c_oflag &= ~OPOST;
+-            TERMIOS-P->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
+-            TERMIOS-P->c_cflag &= ~(CSIZE|PARENB);
+-            TERMIOS-P->c_cflag |= CS8;
+-
+-
+-File: libc.info,  Node: Line Control,  Next: Noncanon Example,  Prev: 
Terminal Modes,  Up: Low-Level Terminal Interface
+-
+-Line Control Functions
+-======================
+-
+-   These functions perform miscellaneous control actions on terminal
+-devices.  As regards terminal access, they are treated like doing
+-output: if any of these functions is used by a background process on its
+-controlling terminal, normally all processes in the process group are
+-sent a `SIGTTOU' signal.  The exception is if the calling process
+-itself is ignoring or blocking `SIGTTOU' signals, in which case the
+-operation is performed and no signal is sent.  *Note Job Control::.
+-
+- - Function: int tcsendbreak (int FILEDES, int DURATION)
+-     This function generates a break condition by transmitting a stream
+-     of zero bits on the terminal associated with the file descriptor
+-     FILEDES.  The duration of the break is controlled by the DURATION
+-     argument.  If zero, the duration is between 0.25 and 0.5 seconds.
+-     The meaning of a nonzero value depends on the operating system.
+-
+-     This function does nothing if the terminal is not an asynchronous
+-     serial data port.
+-
+-     The return value is normally zero.  In the event of an error, a
+-     value of `-1' is returned.  The following `errno' error conditions
+-     are defined for this function:
+-
+-    `EBADF'
+-          The FILEDES is not a valid file descriptor.
+-
+-    `ENOTTY'
+-          The FILEDES is not associated with a terminal device.
+-
+- - Function: int tcdrain (int FILEDES)
+-     The `tcdrain' function waits until all queued output to the
+-     terminal FILEDES has been transmitted.
+-
+-     The return value is normally zero.  In the event of an error, a
+-     value of `-1' is returned.  The following `errno' error conditions
+-     are defined for this function:
+-
+-    `EBADF'
+-          The FILEDES is not a valid file descriptor.
+-
+-    `ENOTTY'
+-          The FILEDES is not associated with a terminal device.
+-
+-    `EINTR'
+-          The operation was interrupted by delivery of a signal.  *Note
+-          Interrupted Primitives::.
+-
+- - Function: int tcflush (int FILEDES, int QUEUE)
+-     The `tcflush' function is used to clear the input and/or output
+-     queues associated with the terminal file FILEDES.  The QUEUE
+-     argument specifies which queue(s) to clear, and can be one of the
+-     following values:
+-
+-    `TCIFLUSH'
+-          Clear any input data received, but not yet read.
+-
+-    `TCOFLUSH'
+-          Clear any output data written, but not yet transmitted.
+-
+-    `TCIOFLUSH'
+-          Clear both queued input and output.
+-
+-     The return value is normally zero.  In the event of an error, a
+-     value of `-1' is returned.  The following `errno' error conditions
+-     are defined for this function:
+-
+-    `EBADF'
+-          The FILEDES is not a valid file descriptor.
+-
+-    `ENOTTY'
+-          The FILEDES is not associated with a terminal device.
+-
+-    `EINVAL'
+-          A bad value was supplied as the QUEUE argument.
+-
+-     It is unfortunate that this function is named `tcflush', because
+-     the term "flush" is normally used for quite another
+-     operation--waiting until all output is transmitted--and using it
+-     for discarding input or output would be confusing.  Unfortunately,
+-     the name `tcflush' comes from POSIX and we cannot change it.
+-
+- - Function: int tcflow (int FILEDES, int ACTION)
+-     The `tcflow' function is used to perform operations relating to
+-     XON/XOFF flow control on the terminal file specified by FILEDES.
+-
+-     The ACTION argument specifies what operation to perform, and can
+-     be one of the following values:
+-
+-    `TCOOFF'
+-          Suspend transmission of output.
+-
+-    `TCOON'
+-          Restart transmission of output.
+-
+-    `TCIOFF'
+-          Transmit a STOP character.
+-
+-    `TCION'
+-          Transmit a START character.
+-
+-     For more information about the STOP and START characters, see
+-     *Note Special Characters::.
+-
+-     The return value is normally zero.  In the event of an error, a
+-     value of `-1' is returned.  The following `errno' error conditions
+-     are defined for this function:
+-
+-    `EBADF'
+-          The FILEDES is not a valid file descriptor.
+-
+-    `ENOTTY'
+-          The FILEDES is not associated with a terminal device.
+-
+-    `EINVAL'
+-          A bad value was supplied as the ACTION argument.
+-
+-
+-File: libc.info,  Node: Noncanon Example,  Prev: Line Control,  Up: Low-Level 
Terminal Interface
+-
+-Noncanonical Mode Example
+-=========================
+-
+-   Here is an example program that shows how you can set up a terminal
+-device to read single characters in noncanonical input mode, without
+-echo.
+-
+-     #include <unistd.h>
+-     #include <stdio.h>
+-     #include <stdlib.h>
+-     #include <termios.h>
+-     
+-     /* Use this variable to remember original terminal attributes. */
+-     
+-     struct termios saved_attributes;
+-     
+-     void
+-     reset_input_mode (void)
+-     {
+-       tcsetattr (STDIN_FILENO, TCSANOW, &saved_attributes);
+-     }
+-     
+-     void
+-     set_input_mode (void)
+-     {
+-       struct termios tattr;
+-       char *name;
+-     
+-       /* Make sure stdin is a terminal. */
+-       if (!isatty (STDIN_FILENO))
+-         {
+-           fprintf (stderr, "Not a terminal.\n");
+-           exit (EXIT_FAILURE);
+-         }
+-     
+-       /* Save the terminal attributes so we can restore them later. */
+-       tcgetattr (STDIN_FILENO, &saved_attributes);
+-       atexit (reset_input_mode);
+-     /* Set the funny terminal modes. */
+-       tcgetattr (STDIN_FILENO, &tattr);
+-       tattr.c_lflag &= ~(ICANON|ECHO); /* Clear ICANON and ECHO. */
+-       tattr.c_cc[VMIN] = 1;
+-       tattr.c_cc[VTIME] = 0;
+-       tcsetattr (STDIN_FILENO, TCSAFLUSH, &tattr);
+-     }
+-     
+-     int
+-     main (void)
+-     {
+-       char c;
+-     
+-       set_input_mode ();
+-     
+-       while (1)
+-         {
+-           read (STDIN_FILENO, &c, 1);
+-           if (c == '\004')          /* `C-d' */
+-             break;
+-           else
+-             putchar (c);
+-         }
+-     
+-       return EXIT_SUCCESS;
+-     }
+-
+-   This program is careful to restore the original terminal modes before
+-exiting or terminating with a signal.  It uses the `atexit' function
+-(*note Cleanups on Exit::.) to make sure this is done by `exit'.
+-
+-   The shell is supposed to take care of resetting the terminal modes
+-when a process is stopped or continued; see *Note Job Control::.  But
+-some existing shells do not actually do this, so you may wish to
+-establish handlers for job control signals that reset terminal modes.
+-The above example does so.
+-
+-
+-File: libc.info,  Node: Mathematics,  Next: Arithmetic,  Prev: Low-Level 
Terminal Interface,  Up: Top
+-
+-Mathematics
+-***********
+-
+-   This chapter contains information about functions for performing
+-mathematical computations, such as trigonometric functions.  Most of
+-these functions have prototypes declared in the header file `math.h'.
+-
+-   All of the functions that operate on floating-point numbers accept
+-arguments and return results of type `double'.  In the future, there
+-may be additional functions that operate on `float' and `long double'
+-values.  For example, `cosf' and `cosl' would be versions of the `cos'
+-function that operate on `float' and `long double' arguments,
+-respectively.  In the meantime, you should avoid using these names
+-yourself.  *Note Reserved Names::.
+-
+-* Menu:
+-
+-* Domain and Range Errors::     Detecting overflow conditions and the like.
+-* Trig Functions::              Sine, cosine, and tangent.
+-* Inverse Trig Functions::      Arc sine, arc cosine, and arc tangent.
+-* Exponents and Logarithms::    Also includes square root.
+-* Hyperbolic Functions::        Hyperbolic sine and friends.
+-* Pseudo-Random Numbers::       Functions for generating pseudo-random
+-                               numbers.
+-
+-
+-File: libc.info,  Node: Domain and Range Errors,  Next: Trig Functions,  Up: 
Mathematics
+-
+-Domain and Range Errors
+-=======================
+-
+-   Many of the functions listed in this chapter are defined
+-mathematically over a domain that is only a subset of real numbers.
+-For example, the `acos' function is defined over the domain between
+-`-1' and `1'.  If you pass an argument to one of these functions that is
+-outside the domain over which it is defined, the function sets `errno'
+-to `EDOM' to indicate a "domain error".  On machines that support
+-IEEE 754 floating point, functions reporting error `EDOM' also return a
+-NaN.
+-
+-   Some of these functions are defined mathematically to result in a
+-complex value over parts of their domains.  The most familiar example of
+-this is taking the square root of a negative number.  The functions in
+-this chapter take only real arguments and return only real values;
+-therefore, if the value ought to be nonreal, this is treated as a domain
+-error.
+-
+-   A related problem is that the mathematical result of a function may
+-not be representable as a floating point number.  If magnitude of the
+-correct result is too large to be represented, the function sets
+-`errno' to `ERANGE' to indicate a "range error", and returns a
+-particular very large value (named by the macro `HUGE_VAL') or its
+-negation (`- HUGE_VAL').
+-
+-   If the magnitude of the result is too small, a value of zero is
+-returned instead.  In this case, `errno' might or might not be set to
+-`ERANGE'.
+-
+-   The only completely reliable way to check for domain and range
+-errors is to set `errno' to `0' before you call the mathematical
+-function and test `errno' afterward.  As a consequence of this use of
+-`errno', use of the mathematical functions is not reentrant if you
+-check for errors.
+-
+-   None of the mathematical functions ever generates signals as a
+-result of domain or range errors.  In particular, this means that you
+-won't see `SIGFPE' signals generated within these functions.  (*Note
+-Signal Handling::, for more information about signals.)
+-
+- - Macro: double HUGE_VAL
+-     An expression representing a particular very large number.  On
+-     machines that use IEEE 754/IEEE 854 floating point format, the
+-     value is "infinity".  On other machines, it's typically the
+-     largest positive number that can be represented.
+-
+-     The value of this macro is used as the return value from various
+-     mathematical `double' returning functions in overflow situations.
+-
+- - Macro: float HUGE_VALf
+-     This macro is similar to the `HUGE_VAL' macro except that it is
+-     used by functions returning `float' values.
+-
+-     This macro is a GNU extension.
+-
+- - Macro: long double HUGE_VALl
+-     This macro is similar to the `HUGE_VAL' macro except that it is
+-     used by functions returning `long double' values.  The value is
+-     only different from `HUGE_VAL' if the architecture really supports
+-     `long double' values.
+-
+-     This macro is a GNU extension.
+-
+-   For more information about floating-point representations and limits,
+-see *Note Floating Point Parameters::.  In particular, the macro
+-`DBL_MAX' might be more appropriate than `HUGE_VAL' for many uses other
+-than testing for an error in a mathematical function.
+-
+-
+-File: libc.info,  Node: Trig Functions,  Next: Inverse Trig Functions,  Prev: 
Domain and Range Errors,  Up: Mathematics
+-
+-Trigonometric Functions
+-=======================
+-
+-   These are the familiar `sin', `cos', and `tan' functions.  The
+-arguments to all of these functions are in units of radians; recall
+-that pi radians equals 180 degrees.
+-
+-   The math library doesn't define a symbolic constant for pi, but you
+-can define your own if you need one:
+-
+-     #define PI 3.14159265358979323846264338327
+-
+-You can also compute the value of pi with the expression `acos (-1.0)'.
+-
+- - Function: double sin (double X)
+-     This function returns the sine of X, where X is given in radians.
+-     The return value is in the range `-1' to `1'.
+-
+- - Function: double cos (double X)
+-     This function returns the cosine of X, where X is given in
+-     radians.  The return value is in the range `-1' to `1'.
+-
+- - Function: double tan (double X)
+-     This function returns the tangent of X, where X is given in
+-     radians.
+-
+-     The following `errno' error conditions are defined for this
+-     function:
+-
+-    `ERANGE'
+-          Mathematically, the tangent function has singularities at odd
+-          multiples of pi/2.  If the argument X is too close to one of
+-          these singularities, `tan' sets `errno' to `ERANGE' and
+-          returns either positive or negative `HUGE_VAL'.
+-
+-
+-File: libc.info,  Node: Inverse Trig Functions,  Next: Exponents and 
Logarithms,  Prev: Trig Functions,  Up: Mathematics
+-
+-Inverse Trigonometric Functions
+-===============================
+-
+-   These are the usual arc sine, arc cosine and arc tangent functions,
+-which are the inverses of the sine, cosine and tangent functions,
+-respectively.
+-
+- - Function: double asin (double X)
+-     This function computes the arc sine of X--that is, the value whose
+-     sine is X.  The value is in units of radians.  Mathematically,
+-     there are infinitely many such values; the one actually returned
+-     is the one between `-pi/2' and `pi/2' (inclusive).
+-
+-     `asin' fails, and sets `errno' to `EDOM', if X is out of range.
+-     The arc sine function is defined mathematically only over the
+-     domain `-1' to `1'.
+-
+- - Function: double acos (double X)
+-     This function computes the arc cosine of X--that is, the value
+-     whose cosine is X.  The value is in units of radians.
+-     Mathematically, there are infinitely many such values; the one
+-     actually returned is the one between `0' and `pi' (inclusive).
+-
+-     `acos' fails, and sets `errno' to `EDOM', if X is out of range.
+-     The arc cosine function is defined mathematically only over the
+-     domain `-1' to `1'.
+-
+- - Function: double atan (double X)
+-     This function computes the arc tangent of X--that is, the value
+-     whose tangent is X.  The value is in units of radians.
+-     Mathematically, there are infinitely many such values; the one
+-     actually returned is the one between `-pi/2' and `pi/2'
+-     (inclusive).
+-
+- - Function: double atan2 (double Y, double X)
+-     This is the two argument arc tangent function.  It is similar to
+-     computing the arc tangent of Y/X, except that the signs of both
+-     arguments are used to determine the quadrant of the result, and X
+-     is permitted to be zero.  The return value is given in radians and
+-     is in the range `-pi' to `pi', inclusive.
+-
+-     If X and Y are coordinates of a point in the plane, `atan2'
+-     returns the signed angle between the line from the origin to that
+-     point and the x-axis.  Thus, `atan2' is useful for converting
+-     Cartesian coordinates to polar coordinates.  (To compute the
+-     radial coordinate, use `hypot'; see *Note Exponents and
+-     Logarithms::.)
+-
+-     The function `atan2' sets `errno' to `EDOM' if both X and Y are
+-     zero; the return value is not defined in this case.
+-
+-
+-File: libc.info,  Node: Exponents and Logarithms,  Next: Hyperbolic 
Functions,  Prev: Inverse Trig Functions,  Up: Mathematics
+-
+-Exponentiation and Logarithms
+-=============================
+-
+- - Function: double exp (double X)
+-     The `exp' function returns the value of e (the base of natural
+-     logarithms) raised to power X.
+-
+-     The function fails, and sets `errno' to `ERANGE', if the magnitude
+-     of the result is too large to be representable.
+-
+- - Function: double log (double X)
+-     This function returns the natural logarithm of X.  `exp (log (X))'
+-     equals X, exactly in mathematics and approximately in C.
+-
+-     The following `errno' error conditions are defined for this
+-     function:
+-
+-    `EDOM'
+-          The argument X is negative.  The log function is defined
+-          mathematically to return a real result only on positive
+-          arguments.
+-
+-    `ERANGE'
+-          The argument is zero.  The log of zero is not defined.
+-
+- - Function: double log10 (double X)
+-     This function returns the base-10 logarithm of X.  Except for the
+-     different base, it is similar to the `log' function.  In fact,
+-     `log10 (X)' equals `log (X) / log (10)'.
+-
+- - Function: double pow (double BASE, double POWER)
+-     This is a general exponentiation function, returning BASE raised
+-     to POWER.
+-
+-     The following `errno' error conditions are defined for this
+-     function:
+-
+-    `EDOM'
+-          The argument BASE is negative and POWER is not an integral
+-          value.  Mathematically, the result would be a complex number
+-          in this case.
+-
+-    `ERANGE'
+-          An underflow or overflow condition was detected in the result.
+-
+- - Function: double sqrt (double X)
+-     This function returns the nonnegative square root of X.
+-
+-     The `sqrt' function fails, and sets `errno' to `EDOM', if X is
+-     negative.  Mathematically, the square root would be a complex
+-     number.
+-
+- - Function: double cbrt (double X)
+-     This function returns the cube root of X.  This function cannot
+-     fail; every representable real value has a representable real cube
+-     root.
+-
+- - Function: double hypot (double X, double Y)
+-     The `hypot' function returns `sqrt (X*X + Y*Y)'.  (This is the
+-     length of the hypotenuse of a right triangle with sides of length
+-     X and Y, or the distance of the point (X, Y) from the origin.)
+-     See also the function `cabs' in *Note Absolute Value::.
+-
+- - Function: double expm1 (double X)
+-     This function returns a value equivalent to `exp (X) - 1'.  It is
+-     computed in a way that is accurate even if the value of X is near
+-     zero--a case where `exp (X) - 1' would be inaccurate due to
+-     subtraction of two numbers that are nearly equal.
+-
+- - Function: double log1p (double X)
+-     This function returns a value equivalent to `log (1 + X)'.  It is
+-     computed in a way that is accurate even if the value of X is near
+-     zero.
+-
+-
+-File: libc.info,  Node: Hyperbolic Functions,  Next: Pseudo-Random Numbers,  
Prev: Exponents and Logarithms,  Up: Mathematics
+-
+-Hyperbolic Functions
+-====================
+-
+-   The functions in this section are related to the exponential
+-functions; see *Note Exponents and Logarithms::.
+-
+- - Function: double sinh (double X)
+-     The `sinh' function returns the hyperbolic sine of X, defined
+-     mathematically as `exp (X) - exp (-X) / 2'.  The function fails,
+-     and sets `errno' to `ERANGE', if the value of X is too large; that
+-     is, if overflow occurs.
+-
+- - Function: double cosh (double X)
+-     The `cosh' function returns the hyperbolic cosine of X, defined
+-     mathematically as `exp (X) + exp (-X) / 2'.  The function fails,
+-     and sets `errno' to `ERANGE', if the value of X is too large; that
+-     is, if overflow occurs.
+-
+- - Function: double tanh (double X)
+-     This function returns the hyperbolic tangent of X, whose
+-     mathematical definition is `sinh (X) / cosh (X)'.
+-
+- - Function: double asinh (double X)
+-     This function returns the inverse hyperbolic sine of X--the value
+-     whose hyperbolic sine is X.
+-
+- - Function: double acosh (double X)
+-     This function returns the inverse hyperbolic cosine of X--the
+-     value whose hyperbolic cosine is X.  If X is less than `1',
+-     `acosh' returns `HUGE_VAL'.
+-
+- - Function: double atanh (double X)
+-     This function returns the inverse hyperbolic tangent of X--the
+-     value whose hyperbolic tangent is X.  If the absolute value of X
+-     is greater than or equal to `1', `atanh' returns `HUGE_VAL'.
+-
+-
+-File: libc.info,  Node: Pseudo-Random Numbers,  Prev: Hyperbolic Functions,  
Up: Mathematics
+-
+-Pseudo-Random Numbers
+-=====================
+-
+-   This section describes the GNU facilities for generating a series of
+-pseudo-random numbers.  The numbers generated are not truly random;
+-typically, they form a sequence that repeats periodically, with a
+-period so large that you can ignore it for ordinary purposes.  The
+-random number generator works by remembering at all times a "seed"
+-value which it uses to compute the next random number and also to
+-compute a new seed.
+-
+-   Although the generated numbers look unpredictable within one run of a
+-program, the sequence of numbers is *exactly the same* from one run to
+-the next.  This is because the initial seed is always the same.  This
+-is convenient when you are debugging a program, but it is unhelpful if
+-you want the program to behave unpredictably.  If you want truly random
+-numbers, not just pseudo-random, specify a seed based on the current
+-time.
+-
+-   You can get repeatable sequences of numbers on a particular machine
+-type by specifying the same initial seed value for the random number
+-generator.  There is no standard meaning for a particular seed value;
+-the same seed, used in different C libraries or on different CPU types,
+-will give you different random numbers.
+-
+-   The GNU library supports the standard ISO C random number functions
+-plus another set derived from BSD.  We recommend you use the standard
+-ones, `rand' and `srand'.
+-
+-* Menu:
+-
+-* ISO Random::       `rand' and friends.
+-* BSD Random::       `random' and friends.
+-
+-
+-File: libc.info,  Node: ISO Random,  Next: BSD Random,  Up: Pseudo-Random 
Numbers
+-
+-ISO C Random Number Functions
+------------------------------
+-
+-   This section describes the random number functions that are part of
+-the ISO C standard.
+-
+-   To use these facilities, you should include the header file
+-`stdlib.h' in your program.
+-
+- - Macro: int RAND_MAX
+-     The value of this macro is an integer constant expression that
+-     represents the maximum possible value returned by the `rand'
+-     function.  In the GNU library, it is `037777777', which is the
+-     largest signed integer representable in 32 bits.  In other
+-     libraries, it may be as low as `32767'.
+-
+- - Function: int rand ()
+-     The `rand' function returns the next pseudo-random number in the
+-     series.  The value is in the range from `0' to `RAND_MAX'.
+-
+- - Function: void srand (unsigned int SEED)
+-     This function establishes SEED as the seed for a new series of
+-     pseudo-random numbers.  If you call `rand' before a seed has been
+-     established with `srand', it uses the value `1' as a default seed.
+-
+-     To produce truly random numbers (not just pseudo-random), do `srand
+-     (time (0))'.
+-
+-
+-File: libc.info,  Node: BSD Random,  Prev: ISO Random,  Up: Pseudo-Random 
Numbers
+-
+-BSD Random Number Functions
+----------------------------
+-
+-   This section describes a set of random number generation functions
+-that are derived from BSD.  There is no advantage to using these
+-functions with the GNU C library; we support them for BSD compatibility
+-only.
+-
+-   The prototypes for these functions are in `stdlib.h'.
+-
+- - Function: long int random ()
+-     This function returns the next pseudo-random number in the
+-     sequence.  The range of values returned is from `0' to `RAND_MAX'.
+-
+- - Function: void srandom (unsigned int SEED)
+-     The `srandom' function sets the seed for the current random number
+-     state based on the integer SEED.  If you supply a SEED value of
+-     `1', this will cause `random' to reproduce the default set of
+-     random numbers.
+-
+-     To produce truly random numbers (not just pseudo-random), do
+-     `srandom (time (0))'.
+-
+- - Function: void * initstate (unsigned int SEED, void *STATE, size_t
+-          SIZE)
+-     The `initstate' function is used to initialize the random number
+-     generator state.  The argument STATE is an array of SIZE bytes,
+-     used to hold the state information.  The size must be at least 8
+-     bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The
+-     bigger the STATE array, the better.
+-
+-     The return value is the previous value of the state information
+-     array.  You can use this value later as an argument to `setstate'
+-     to restore that state.
+-
+- - Function: void * setstate (void *STATE)
+-     The `setstate' function restores the random number state
+-     information STATE.  The argument must have been the result of a
+-     previous call to INITSTATE or SETSTATE.
+-
+-     The return value is the previous value of the state information
+-     array.  You can use thise value later as an argument to `setstate'
+-     to restore that state.
+-
+-
+-File: libc.info,  Node: Arithmetic,  Next: Date and Time,  Prev: Mathematics, 
 Up: Top
+-
+-Low-Level Arithmetic Functions
+-******************************
+-
+-   This chapter contains information about functions for doing basic
+-arithmetic operations, such as splitting a float into its integer and
+-fractional parts.  These functions are declared in the header file
+-`math.h'.
+-
+-* Menu:
+-
+-* Not a Number::                Making NaNs and testing for NaNs.
+-* Predicates on Floats::        Testing for infinity and for NaNs.
+-* Absolute Value::              Absolute value functions.
+-* Normalization Functions::     Hacks for radix-2 representations.
+-* Rounding and Remainders::     Determining the integer and
+-                               fractional parts of a float.
+-* Integer Division::            Functions for performing integer
+-                               division.
+-* Parsing of Numbers::          Functions for "reading" numbers
+-                               from strings.
+-
+-
+-File: libc.info,  Node: Not a Number,  Next: Predicates on Floats,  Up: 
Arithmetic
+-
+-"Not a Number" Values
+-=====================
+-
+-   The IEEE floating point format used by most modern computers supports
+-values that are "not a number".  These values are called "NaNs".  "Not
+-a number" values result from certain operations which have no
+-meaningful numeric result, such as zero divided by zero or infinity
+-divided by infinity.
+-
+-   One noteworthy property of NaNs is that they are not equal to
+-themselves.  Thus, `x == x' can be 0 if the value of `x' is a NaN.  You
+-can use this to test whether a value is a NaN or not: if it is not
+-equal to itself, then it is a NaN.  But the recommended way to test for
+-a NaN is with the `isnan' function (*note Predicates on Floats::.).
+-
+-   Almost any arithmetic operation in which one argument is a NaN
+-returns a NaN.
+-
+- - Macro: double NAN
+-     An expression representing a value which is "not a number".  This
+-     macro is a GNU extension, available only on machines that support
+-     "not a number" values--that is to say, on all machines that
+-     support IEEE floating point.
+-
+-     You can use `#ifdef NAN' to test whether the machine supports
+-     NaNs.  (Of course, you must arrange for GNU extensions to be
+-     visible, such as by defining `_GNU_SOURCE', and then you must
+-     include `math.h'.)
+-
+-
+-File: libc.info,  Node: Predicates on Floats,  Next: Absolute Value,  Prev: 
Not a Number,  Up: Arithmetic
+-
+-Predicates on Floats
+-====================
+-
+-   This section describes some miscellaneous test functions on doubles.
+-Prototypes for these functions appear in `math.h'.  These are BSD
+-functions, and thus are available if you define `_BSD_SOURCE' or
+-`_GNU_SOURCE'.
+-
+- - Function: int isinf (double X)
+-     This function returns `-1' if X represents negative infinity, `1'
+-     if X represents positive infinity, and `0' otherwise.
+-
+- - Function: int isnan (double X)
+-     This function returns a nonzero value if X is a "not a number"
+-     value, and zero otherwise.  (You can just as well use `X != X' to
+-     get the same result).
+-
+- - Function: int finite (double X)
+-     This function returns a nonzero value if X is finite or a "not a
+-     number" value, and zero otherwise.
+-
+- - Function: double infnan (int ERROR)
+-     This function is provided for compatibility with BSD.  The other
+-     mathematical functions use `infnan' to decide what to return on
+-     occasion of an error.  Its argument is an error code, `EDOM' or
+-     `ERANGE'; `infnan' returns a suitable value to indicate this with.
+-     `-ERANGE' is also acceptable as an argument, and corresponds to
+-     `-HUGE_VAL' as a value.
+-
+-     In the BSD library, on certain machines, `infnan' raises a fatal
+-     signal in all cases.  The GNU library does not do likewise,
+-     because that does not fit the ISO C specification.
+-
+-   *Portability Note:* The functions listed in this section are BSD
+-extensions.
+-
+-
+-File: libc.info,  Node: Absolute Value,  Next: Normalization Functions,  
Prev: Predicates on Floats,  Up: Arithmetic
+-
+-Absolute Value
+-==============
+-
+-   These functions are provided for obtaining the "absolute value" (or
+-"magnitude") of a number.  The absolute value of a real number X is X
+-is X is positive, -X if X is negative.  For a complex number Z, whose
+-real part is X and whose imaginary part is Y, the absolute value is
+-`sqrt (X*X + Y*Y)'.
+-
+-   Prototypes for `abs' and `labs' are in `stdlib.h'; `fabs' and `cabs'
+-are declared in `math.h'.
+-
+- - Function: int abs (int NUMBER)
+-     This function returns the absolute value of NUMBER.
+-
+-     Most computers use a two's complement integer representation, in
+-     which the absolute value of `INT_MIN' (the smallest possible `int')
+-     cannot be represented; thus, `abs (INT_MIN)' is not defined.
+-
+- - Function: long int labs (long int NUMBER)
+-     This is similar to `abs', except that both the argument and result
+-     are of type `long int' rather than `int'.
+-
+- - Function: double fabs (double NUMBER)
+-     This function returns the absolute value of the floating-point
+-     number NUMBER.
+-
+- - Function: double cabs (struct { double real, imag; } Z)
+-     The `cabs' function returns the absolute value of the complex
+-     number Z, whose real part is `Z.real' and whose imaginary part is
+-     `Z.imag'.  (See also the function `hypot' in *Note Exponents and
+-     Logarithms::.)  The value is:
+-
+-          sqrt (Z.real*Z.real + Z.imag*Z.imag)
+-
+-
+-File: libc.info,  Node: Normalization Functions,  Next: Rounding and 
Remainders,  Prev: Absolute Value,  Up: Arithmetic
+-
+-Normalization Functions
+-=======================
+-
+-   The functions described in this section are primarily provided as a
+-way to efficiently perform certain low-level manipulations on floating
+-point numbers that are represented internally using a binary radix; see
+-*Note Floating Point Concepts::.  These functions are required to have
+-equivalent behavior even if the representation does not use a radix of
+-2, but of course they are unlikely to be particularly efficient in
+-those cases.
+-
+-   All these functions are declared in `math.h'.
+-
+- - Function: double frexp (double VALUE, int *EXPONENT)
+-     The `frexp' function is used to split the number VALUE into a
+-     normalized fraction and an exponent.
+-
+-     If the argument VALUE is not zero, the return value is VALUE times
+-     a power of two, and is always in the range 1/2 (inclusive) to 1
+-     (exclusive).  The corresponding exponent is stored in `*EXPONENT';
+-     the return value multiplied by 2 raised to this exponent equals
+-     the original number VALUE.
+-
+-     For example, `frexp (12.8, &exponent)' returns `0.8' and stores
+-     `4' in `exponent'.
+-
+-     If VALUE is zero, then the return value is zero and zero is stored
+-     in `*EXPONENT'.
+-
+- - Function: double ldexp (double VALUE, int EXPONENT)
+-     This function returns the result of multiplying the floating-point
+-     number VALUE by 2 raised to the power EXPONENT.  (It can be used
+-     to reassemble floating-point numbers that were taken apart by
+-     `frexp'.)
+-
+-     For example, `ldexp (0.8, 4)' returns `12.8'.
+-
+-   The following functions which come from BSD provide facilities
+-equivalent to those of `ldexp' and `frexp':
+-
+- - Function: double scalb (double VALUE, int EXPONENT)
+-     The `scalb' function is the BSD name for `ldexp'.
+-
+- - Function: double logb (double X)
+-     This BSD function returns the integer part of the base-2 logarithm
+-     of X, an integer value represented in type `double'.  This is the
+-     highest integer power of `2' contained in X.  The sign of X is
+-     ignored.  For example, `logb (3.5)' is `1.0' and `logb (4.0)' is
+-     `2.0'.
+-
+-     When `2' raised to this power is divided into X, it gives a
+-     quotient between `1' (inclusive) and `2' (exclusive).
+-
+-     If X is zero, the value is minus infinity (if the machine supports
+-     such a value), or else a very small number.  If X is infinity, the
+-     value is infinity.
+-
+-     The value returned by `logb' is one less than the value that
+-     `frexp' would store into `*EXPONENT'.
+-
+- - Function: double copysign (double VALUE, double SIGN)
+-     The `copysign' function returns a value whose absolute value is the
+-     same as that of VALUE, and whose sign matches that of SIGN.  This
+-     is a BSD function.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-16 
glibc-2.0.1/manual/libc.info-16
+--- ../glibc-2.0.1/manual/libc.info-16 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-16    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1257 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Rounding and Remainders,  Next: Integer Division,  
Prev: Normalization Functions,  Up: Arithmetic
+-
+-Rounding and Remainder Functions
+-================================
+-
+-   The functions listed here perform operations such as rounding,
+-truncation, and remainder in division of floating point numbers.  Some
+-of these functions convert floating point numbers to integer values.
+-They are all declared in `math.h'.
+-
+-   You can also convert floating-point numbers to integers simply by
+-casting them to `int'.  This discards the fractional part, effectively
+-rounding towards zero.  However, this only works if the result can
+-actually be represented as an `int'--for very large numbers, this is
+-impossible.  The functions listed here return the result as a `double'
+-instead to get around this problem.
+-
+- - Function: double ceil (double X)
+-     The `ceil' function rounds X upwards to the nearest integer,
+-     returning that value as a `double'.  Thus, `ceil (1.5)' is `2.0'.
+-
+- - Function: double floor (double X)
+-     The `ceil' function rounds X downwards to the nearest integer,
+-     returning that value as a `double'.  Thus, `floor (1.5)' is `1.0'
+-     and `floor (-1.5)' is `-2.0'.
+-
+- - Function: double rint (double X)
+-     This function rounds X to an integer value according to the
+-     current rounding mode.  *Note Floating Point Parameters::, for
+-     information about the various rounding modes.  The default
+-     rounding mode is to round to the nearest integer; some machines
+-     support other modes, but round-to-nearest is always used unless
+-     you explicit select another.
+-
+- - Function: double modf (double VALUE, double *INTEGER-PART)
+-     This function breaks the argument VALUE into an integer part and a
+-     fractional part (between `-1' and `1', exclusive).  Their sum
+-     equals VALUE.  Each of the parts has the same sign as VALUE, so
+-     the rounding of the integer part is towards zero.
+-
+-     `modf' stores the integer part in `*INTEGER-PART', and returns the
+-     fractional part.  For example, `modf (2.5, &intpart)' returns
+-     `0.5' and stores `2.0' into `intpart'.
+-
+- - Function: double fmod (double NUMERATOR, double DENOMINATOR)
+-     This function computes the remainder from the division of
+-     NUMERATOR by DENOMINATOR.  Specifically, the return value is
+-     `NUMERATOR - N * DENOMINATOR', where N is the quotient of
+-     NUMERATOR divided by DENOMINATOR, rounded towards zero to an
+-     integer.  Thus, `fmod (6.5, 2.3)' returns `1.9', which is `6.5'
+-     minus `4.6'.
+-
+-     The result has the same sign as the NUMERATOR and has magnitude
+-     less than the magnitude of the DENOMINATOR.
+-
+-     If DENOMINATOR is zero, `fmod' fails and sets `errno' to `EDOM'.
+-
+- - Function: double drem (double NUMERATOR, double DENOMINATOR)
+-     The function `drem' is like `fmod' except that it rounds the
+-     internal quotient N to the nearest integer instead of towards zero
+-     to an integer.  For example, `drem (6.5, 2.3)' returns `-0.4',
+-     which is `6.5' minus `6.9'.
+-
+-     The absolute value of the result is less than or equal to half the
+-     absolute value of the DENOMINATOR.  The difference between `fmod
+-     (NUMERATOR, DENOMINATOR)' and `drem (NUMERATOR, DENOMINATOR)' is
+-     always either DENOMINATOR, minus DENOMINATOR, or zero.
+-
+-     If DENOMINATOR is zero, `drem' fails and sets `errno' to `EDOM'.
+-
+-
+-File: libc.info,  Node: Integer Division,  Next: Parsing of Numbers,  Prev: 
Rounding and Remainders,  Up: Arithmetic
+-
+-Integer Division
+-================
+-
+-   This section describes functions for performing integer division.
+-These functions are redundant in the GNU C library, since in GNU C the
+-`/' operator always rounds towards zero.  But in other C
+-implementations, `/' may round differently with negative arguments.
+-`div' and `ldiv' are useful because they specify how to round the
+-quotient: towards zero.  The remainder has the same sign as the
+-numerator.
+-
+-   These functions are specified to return a result R such that the
+-value `R.quot*DENOMINATOR + R.rem' equals NUMERATOR.
+-
+-   To use these facilities, you should include the header file
+-`stdlib.h' in your program.
+-
+- - Data Type: div_t
+-     This is a structure type used to hold the result returned by the
+-     `div' function.  It has the following members:
+-
+-    `int quot'
+-          The quotient from the division.
+-
+-    `int rem'
+-          The remainder from the division.
+-
+- - Function: div_t div (int NUMERATOR, int DENOMINATOR)
+-     This function `div' computes the quotient and remainder from the
+-     division of NUMERATOR by DENOMINATOR, returning the result in a
+-     structure of type `div_t'.
+-
+-     If the result cannot be represented (as in a division by zero), the
+-     behavior is undefined.
+-
+-     Here is an example, albeit not a very useful one.
+-
+-          div_t result;
+-          result = div (20, -6);
+-
+-     Now `result.quot' is `-3' and `result.rem' is `2'.
+-
+- - Data Type: ldiv_t
+-     This is a structure type used to hold the result returned by the
+-     `ldiv' function.  It has the following members:
+-
+-    `long int quot'
+-          The quotient from the division.
+-
+-    `long int rem'
+-          The remainder from the division.
+-
+-     (This is identical to `div_t' except that the components are of
+-     type `long int' rather than `int'.)
+-
+- - Function: ldiv_t ldiv (long int NUMERATOR, long int DENOMINATOR)
+-     The `ldiv' function is similar to `div', except that the arguments
+-     are of type `long int' and the result is returned as a structure
+-     of type `ldiv'.
+-
+-
+-File: libc.info,  Node: Parsing of Numbers,  Prev: Integer Division,  Up: 
Arithmetic
+-
+-Parsing of Numbers
+-==================
+-
+-   This section describes functions for "reading" integer and
+-floating-point numbers from a string.  It may be more convenient in some
+-cases to use `sscanf' or one of the related functions; see *Note
+-Formatted Input::.  But often you can make a program more robust by
+-finding the tokens in the string by hand, then converting the numbers
+-one by one.
+-
+-* Menu:
+-
+-* Parsing of Integers::         Functions for conversion of integer values.
+-* Parsing of Floats::           Functions for conversion of floating-point
+-                               values.
+-
+-
+-File: libc.info,  Node: Parsing of Integers,  Next: Parsing of Floats,  Up: 
Parsing of Numbers
+-
+-Parsing of Integers
+--------------------
+-
+-   These functions are declared in `stdlib.h'.
+-
+- - Function: long int strtol (const char *STRING, char **TAILPTR, int
+-          BASE)
+-     The `strtol' ("string-to-long") function converts the initial part
+-     of STRING to a signed integer, which is returned as a value of
+-     type `long int'.
+-
+-     This function attempts to decompose STRING as follows:
+-
+-        * A (possibly empty) sequence of whitespace characters.  Which
+-          characters are whitespace is determined by the `isspace'
+-          function (*note Classification of Characters::.).  These are
+-          discarded.
+-
+-        * An optional plus or minus sign (`+' or `-').
+-
+-        * A nonempty sequence of digits in the radix specified by BASE.
+-
+-          If BASE is zero, decimal radix is assumed unless the series of
+-          digits begins with `0' (specifying octal radix), or `0x' or
+-          `0X' (specifying hexadecimal radix); in other words, the same
+-          syntax used for integer constants in C.
+-
+-          Otherwise BASE must have a value between `2' and `35'.  If
+-          BASE is `16', the digits may optionally be preceded by `0x'
+-          or `0X'.  If base has no legal value the value returned is
+-          `0l' and the global variable `errno' is set to `EINVAL'.
+-
+-        * Any remaining characters in the string.  If TAILPTR is not a
+-          null pointer, `strtol' stores a pointer to this tail in
+-          `*TAILPTR'.
+-
+-     If the string is empty, contains only whitespace, or does not
+-     contain an initial substring that has the expected syntax for an
+-     integer in the specified BASE, no conversion is performed.  In
+-     this case, `strtol' returns a value of zero and the value stored in
+-     `*TAILPTR' is the value of STRING.
+-
+-     In a locale other than the standard `"C"' locale, this function
+-     may recognize additional implementation-dependent syntax.
+-
+-     If the string has valid syntax for an integer but the value is not
+-     representable because of overflow, `strtol' returns either
+-     `LONG_MAX' or `LONG_MIN' (*note Range of Type::.), as appropriate
+-     for the sign of the value.  It also sets `errno' to `ERANGE' to
+-     indicate there was overflow.
+-
+-     Because the value `0l' is a correct result for `strtol' the user
+-     who is interested in handling errors should set the global variable
+-     `errno' to `0' before calling this function, so that the program
+-     can later test whether an error occurred.
+-
+-     There is an example at the end of this section.
+-
+- - Function: unsigned long int strtoul (const char *STRING, char
+-          **TAILPTR, int BASE)
+-     The `strtoul' ("string-to-unsigned-long") function is like
+-     `strtol' except it deals with unsigned numbers, and returns its
+-     value with type `unsigned long int'.  No `+' or `-' sign may
+-     appear before the number, but the syntax is otherwise the same as
+-     described above for `strtol'.  The value returned in case of
+-     overflow is `ULONG_MAX' (*note Range of Type::.).
+-
+-     Like `strtol' this function sets `errno' and returns the value
+-     `0ul' in case the value for BASE is not in the legal range.  For
+-     `strtoul' this can happen in another situation.  In case the
+-     number to be converted is negative `strtoul' also sets `errno' to
+-     `EINVAL' and returns `0ul'.
+-
+- - Function: long long int strtoq (const char *STRING, char **TAILPTR,
+-          int BASE)
+-     The `strtoq' ("string-to-quad-word") function is like `strtol'
+-     except that is deals with extra long numbers and it returns its
+-     value with type `long long int'.
+-
+-     If the string has valid syntax for an integer but the value is not
+-     representable because of overflow, `strtoq' returns either
+-     `LONG_LONG_MAX' or `LONG_LONG_MIN' (*note Range of Type::.), as
+-     appropriate for the sign of the value.  It also sets `errno' to
+-     `ERANGE' to indicate there was overflow.
+-
+- - Function: long long int strtoll (const char *STRING, char **TAILPTR,
+-          int BASE)
+-     `strtoll' is only an commonly used other name for the `strtoq'
+-     function.  Everything said for `strtoq' applies to `strtoll' as
+-     well.
+-
+- - Function: unsigned long long int strtouq (const char *STRING, char
+-          **TAILPTR, int BASE)
+-     The `strtouq' ("string-to-unsigned-quad-word") function is like
+-     `strtoul' except that is deals with extra long numbers and it
+-     returns its value with type `unsigned long long int'.  The value
+-     returned in case of overflow is `ULONG_LONG_MAX' (*note Range of
+-     Type::.).
+-
+- - Function: unsigned long long int strtoull (const char *STRING, char
+-          **TAILPTR, int BASE)
+-     `strtoull' is only an commonly used other name for the `strtouq'
+-     function.  Everything said for `strtouq' applies to `strtoull' as
+-     well.
+-
+- - Function: long int atol (const char *STRING)
+-     This function is similar to the `strtol' function with a BASE
+-     argument of `10', except that it need not detect overflow errors.
+-     The `atol' function is provided mostly for compatibility with
+-     existing code; using `strtol' is more robust.
+-
+- - Function: int atoi (const char *STRING)
+-     This function is like `atol', except that it returns an `int'
+-     value rather than `long int'.  The `atoi' function is also
+-     considered obsolete; use `strtol' instead.
+-
+-   The POSIX locales contain some information about how to format
+-numbers (*note General Numeric::.).  This mainly deals with
+-representing numbers for better readability for humans.  The functions
+-present so far in this section cannot handle numbers in this form.
+-
+-   If this functionality is needed in a program one can use the
+-functions from the `scanf' family which know about the flag `'' for
+-parsing numeric input (*note Numeric Input Conversions::.).  Sometimes
+-it is more desirable to have finer control.
+-
+-   In these situation one could use the function `__strtoXXX_internal'.
+-XXX here stands for any of the above forms.  All numeric conversion
+-functions (including the functions to process floating-point numbers)
+-have such a counterpart.  The difference to the normal form is the
+-extra argument at the end of the parameter list.  If this value has an
+-non-zero value the handling of number grouping is enabled.  The
+-advantage of using these functions is that the TAILPTR parameters allow
+-to determine which part of the input is processed.  The `scanf'
+-functions don't provide this information.  The drawback of using these
+-functions is that they are not portable.  They only exist in the GNU C
+-library.
+-
+-   Here is a function which parses a string as a sequence of integers
+-and returns the sum of them:
+-
+-     int
+-     sum_ints_from_string (char *string)
+-     {
+-       int sum = 0;
+-     
+-       while (1) {
+-         char *tail;
+-         int next;
+-     
+-         /* Skip whitespace by hand, to detect the end.  */
+-         while (isspace (*string)) string++;
+-         if (*string == 0)
+-           break;
+-     
+-         /* There is more nonwhitespace,  */
+-         /* so it ought to be another number.  */
+-         errno = 0;
+-         /* Parse it.  */
+-         next = strtol (string, &tail, 0);
+-         /* Add it in, if not overflow.  */
+-         if (errno)
+-           printf ("Overflow\n");
+-         else
+-           sum += next;
+-         /* Advance past it.  */
+-         string = tail;
+-       }
+-     
+-       return sum;
+-     }
+-
+-
+-File: libc.info,  Node: Parsing of Floats,  Prev: Parsing of Integers,  Up: 
Parsing of Numbers
+-
+-Parsing of Floats
+------------------
+-
+-   These functions are declared in `stdlib.h'.
+-
+- - Function: double strtod (const char *STRING, char **TAILPTR)
+-     The `strtod' ("string-to-double") function converts the initial
+-     part of STRING to a floating-point number, which is returned as a
+-     value of type `double'.
+-
+-     This function attempts to decompose STRING as follows:
+-
+-        * A (possibly empty) sequence of whitespace characters.  Which
+-          characters are whitespace is determined by the `isspace'
+-          function (*note Classification of Characters::.).  These are
+-          discarded.
+-
+-        * An optional plus or minus sign (`+' or `-').
+-
+-        * A nonempty sequence of digits optionally containing a
+-          decimal-point character--normally `.', but it depends on the
+-          locale (*note Numeric Formatting::.).
+-
+-        * An optional exponent part, consisting of a character `e' or
+-          `E', an optional sign, and a sequence of digits.
+-
+-        * Any remaining characters in the string.  If TAILPTR is not a
+-          null pointer, a pointer to this tail of the string is stored
+-          in `*TAILPTR'.
+-
+-     If the string is empty, contains only whitespace, or does not
+-     contain an initial substring that has the expected syntax for a
+-     floating-point number, no conversion is performed.  In this case,
+-     `strtod' returns a value of zero and the value returned in
+-     `*TAILPTR' is the value of STRING.
+-
+-     In a locale other than the standard `"C"' or `"POSIX"' locales,
+-     this function may recognize additional locale-dependent syntax.
+-
+-     If the string has valid syntax for a floating-point number but the
+-     value is not representable because of overflow, `strtod' returns
+-     either positive or negative `HUGE_VAL' (*note Mathematics::.),
+-     depending on the sign of the value.  Similarly, if the value is
+-     not representable because of underflow, `strtod' returns zero.  It
+-     also sets `errno' to `ERANGE' if there was overflow or underflow.
+-
+-     Since the value zero which is returned in the error case is also a
+-     valid result the user should set the global variable `errno' to
+-     zero before calling this function.  So one can test for failures
+-     after the call since all failures set `errno' to a non-zero value.
+-
+- - Function: float strtof (const char *STRING, char **TAILPTR)
+-     This function is similar to the `strtod' function but it returns a
+-     `float' value instead of a `double' value.  If the precision of a
+-     `float' value is sufficient this function should be used since it
+-     is much faster than `strtod' on some architectures.  The reasons
+-     are obvious: IEEE 754 defines `float' to have a mantissa of 23
+-     bits while `double' has 53 bits and every additional bit of
+-     precision can require additional computation.
+-
+-     If the string has valid syntax for a floating-point number but the
+-     value is not representable because of overflow, `strtof' returns
+-     either positive or negative `HUGE_VALf' (*note Mathematics::.),
+-     depending on the sign of the value.
+-
+-     This function is a GNU extension.
+-
+- - Function: long double strtold (const char *STRING, char **TAILPTR)
+-     This function is similar to the `strtod' function but it returns a
+-     `long double' value instead of a `double' value.  It should be
+-     used when high precision is needed.  On systems which define a
+-     `long double' type (i.e., on which it is not the same as `double')
+-     running this function might take significantly more time since
+-     more bits of precision are required.
+-
+-     If the string has valid syntax for a floating-point number but the
+-     value is not representable because of overflow, `strtold' returns
+-     either positive or negative `HUGE_VALl' (*note Mathematics::.),
+-     depending on the sign of the value.
+-
+-     This function is a GNU extension.
+-
+-   As for the integer parsing functions there are additional functions
+-which will handle numbers represented using the grouping scheme of the
+-current locale (*note Parsing of Integers::.).
+-
+- - Function: double atof (const char *STRING)
+-     This function is similar to the `strtod' function, except that it
+-     need not detect overflow and underflow errors.  The `atof' function
+-     is provided mostly for compatibility with existing code; using
+-     `strtod' is more robust.
+-
+-
+-File: libc.info,  Node: Searching and Sorting,  Next: Pattern Matching,  
Prev: Locales,  Up: Top
+-
+-Searching and Sorting
+-*********************
+-
+-   This chapter describes functions for searching and sorting arrays of
+-arbitrary objects.  You pass the appropriate comparison function to be
+-applied as an argument, along with the size of the objects in the array
+-and the total number of elements.
+-
+-* Menu:
+-
+-* Comparison Functions::        Defining how to compare two objects.
+-                               Since the sort and search facilities
+-                                 are general, you have to specify the
+-                                 ordering.
+-* Array Search Function::       The `bsearch' function.
+-* Array Sort Function::         The `qsort' function.
+-* Search/Sort Example::         An example program.
+-
+-
+-File: libc.info,  Node: Comparison Functions,  Next: Array Search Function,  
Up: Searching and Sorting
+-
+-Defining the Comparison Function
+-================================
+-
+-   In order to use the sorted array library functions, you have to
+-describe how to compare the elements of the array.
+-
+-   To do this, you supply a comparison function to compare two elements
+-of the array.  The library will call this function, passing as arguments
+-pointers to two array elements to be compared.  Your comparison function
+-should return a value the way `strcmp' (*note String/Array
+-Comparison::.) does: negative if the first argument is "less" than the
+-second, zero if they are "equal", and positive if the first argument is
+-"greater".
+-
+-   Here is an example of a comparison function which works with an
+-array of numbers of type `double':
+-
+-     int
+-     compare_doubles (const double *a, const double *b)
+-     {
+-       return (int) (*a - *b);
+-     }
+-
+-   The header file `stdlib.h' defines a name for the data type of
+-comparison functions.  This type is a GNU extension.
+-
+-     int comparison_fn_t (const void *, const void *);
+-
+-
+-File: libc.info,  Node: Array Search Function,  Next: Array Sort Function,  
Prev: Comparison Functions,  Up: Searching and Sorting
+-
+-Array Search Function
+-=====================
+-
+-   To search a sorted array for an element matching the key, use the
+-`bsearch' function.  The prototype for this function is in the header
+-file `stdlib.h'.
+-
+- - Function: void * bsearch (const void *KEY, const void *ARRAY, size_t
+-          COUNT, size_t SIZE, comparison_fn_t COMPARE)
+-     The `bsearch' function searches the sorted array ARRAY for an
+-     object that is equivalent to KEY.  The array contains COUNT
+-     elements, each of which is of size SIZE bytes.
+-
+-     The COMPARE function is used to perform the comparison.  This
+-     function is called with two pointer arguments and should return an
+-     integer less than, equal to, or greater than zero corresponding to
+-     whether its first argument is considered less than, equal to, or
+-     greater than its second argument.  The elements of the ARRAY must
+-     already be sorted in ascending order according to this comparison
+-     function.
+-
+-     The return value is a pointer to the matching array element, or a
+-     null pointer if no match is found.  If the array contains more
+-     than one element that matches, the one that is returned is
+-     unspecified.
+-
+-     This function derives its name from the fact that it is implemented
+-     using the binary search algorithm.
+-
+-
+-File: libc.info,  Node: Array Sort Function,  Next: Search/Sort Example,  
Prev: Array Search Function,  Up: Searching and Sorting
+-
+-Array Sort Function
+-===================
+-
+-   To sort an array using an arbitrary comparison function, use the
+-`qsort' function.  The prototype for this function is in `stdlib.h'.
+-
+- - Function: void qsort (void *ARRAY, size_t COUNT, size_t SIZE,
+-          comparison_fn_t COMPARE)
+-     The QSORT function sorts the array ARRAY.  The array contains
+-     COUNT elements, each of which is of size SIZE.
+-
+-     The COMPARE function is used to perform the comparison on the
+-     array elements.  This function is called with two pointer
+-     arguments and should return an integer less than, equal to, or
+-     greater than zero corresponding to whether its first argument is
+-     considered less than, equal to, or greater than its second
+-     argument.
+-
+-     *Warning:* If two objects compare as equal, their order after
+-     sorting is unpredictable.  That is to say, the sorting is not
+-     stable.  This can make a difference when the comparison considers
+-     only part of the elements.  Two elements with the same sort key
+-     may differ in other respects.
+-
+-     If you want the effect of a stable sort, you can get this result by
+-     writing the comparison function so that, lacking other reason
+-     distinguish between two elements, it compares them by their
+-     addresses.  Note that doing this may make the sorting algorithm
+-     less efficient, so do it only if necessary.
+-
+-     Here is a simple example of sorting an array of doubles in
+-     numerical order, using the comparison function defined above
+-     (*note Comparison Functions::.):
+-
+-          {
+-            double *array;
+-            int size;
+-            ...
+-            qsort (array, size, sizeof (double), compare_doubles);
+-          }
+-
+-     The `qsort' function derives its name from the fact that it was
+-     originally implemented using the "quick sort" algorithm.
+-
+-
+-File: libc.info,  Node: Search/Sort Example,  Prev: Array Sort Function,  Up: 
Searching and Sorting
+-
+-Searching and Sorting Example
+-=============================
+-
+-   Here is an example showing the use of `qsort' and `bsearch' with an
+-array of structures.  The objects in the array are sorted by comparing
+-their `name' fields with the `strcmp' function.  Then, we can look up
+-individual objects based on their names.
+-
+-     #include <stdlib.h>
+-     #include <stdio.h>
+-     #include <string.h>
+-     
+-     /* Define an array of critters to sort. */
+-     
+-     struct critter
+-       {
+-         const char *name;
+-         const char *species;
+-       };
+-     
+-     struct critter muppets[] =
+-       {
+-         {"Kermit", "frog"},
+-         {"Piggy", "pig"},
+-         {"Gonzo", "whatever"},
+-         {"Fozzie", "bear"},
+-         {"Sam", "eagle"},
+-         {"Robin", "frog"},
+-         {"Animal", "animal"},
+-         {"Camilla", "chicken"},
+-         {"Sweetums", "monster"},
+-         {"Dr. Strangepork", "pig"},
+-         {"Link Hogthrob", "pig"},
+-         {"Zoot", "human"},
+-         {"Dr. Bunsen Honeydew", "human"},
+-         {"Beaker", "human"},
+-         {"Swedish Chef", "human"}
+-       };
+-     
+-     int count = sizeof (muppets) / sizeof (struct critter);
+-     
+-     
+-     
+-     /* This is the comparison function used for sorting and searching. */
+-     
+-     int
+-     critter_cmp (const struct critter *c1, const struct critter *c2)
+-     {
+-       return strcmp (c1->name, c2->name);
+-     }
+-     
+-     
+-     /* Print information about a critter. */
+-     
+-     void
+-     print_critter (const struct critter *c)
+-     {
+-       printf ("%s, the %s\n", c->name, c->species);
+-     }
+-     /* Do the lookup into the sorted array. */
+-     
+-     void
+-     find_critter (const char *name)
+-     {
+-       struct critter target, *result;
+-       target.name = name;
+-       result = bsearch (&target, muppets, count, sizeof (struct critter),
+-                         critter_cmp);
+-       if (result)
+-         print_critter (result);
+-       else
+-         printf ("Couldn't find %s.\n", name);
+-     }
+-     
+-     /* Main program. */
+-     
+-     int
+-     main (void)
+-     {
+-       int i;
+-     
+-       for (i = 0; i < count; i++)
+-         print_critter (&muppets[i]);
+-       printf ("\n");
+-     
+-       qsort (muppets, count, sizeof (struct critter), critter_cmp);
+-     
+-       for (i = 0; i < count; i++)
+-         print_critter (&muppets[i]);
+-       printf ("\n");
+-     
+-       find_critter ("Kermit");
+-       find_critter ("Gonzo");
+-       find_critter ("Janice");
+-     
+-       return 0;
+-     }
+-
+-   The output from this program looks like:
+-
+-     Kermit, the frog
+-     Piggy, the pig
+-     Gonzo, the whatever
+-     Fozzie, the bear
+-     Sam, the eagle
+-     Robin, the frog
+-     Animal, the animal
+-     Camilla, the chicken
+-     Sweetums, the monster
+-     Dr. Strangepork, the pig
+-     Link Hogthrob, the pig
+-     Zoot, the human
+-     Dr. Bunsen Honeydew, the human
+-     Beaker, the human
+-     Swedish Chef, the human
+-     
+-     Animal, the animal
+-     Beaker, the human
+-     Camilla, the chicken
+-     Dr. Bunsen Honeydew, the human
+-     Dr. Strangepork, the pig
+-     Fozzie, the bear
+-     Gonzo, the whatever
+-     Kermit, the frog
+-     Link Hogthrob, the pig
+-     Piggy, the pig
+-     Robin, the frog
+-     Sam, the eagle
+-     Swedish Chef, the human
+-     Sweetums, the monster
+-     Zoot, the human
+-     
+-     Kermit, the frog
+-     Gonzo, the whatever
+-     Couldn't find Janice.
+-
+-
+-File: libc.info,  Node: Pattern Matching,  Next: I/O Overview,  Prev: 
Searching and Sorting,  Up: Top
+-
+-Pattern Matching
+-****************
+-
+-   The GNU C Library provides pattern matching facilities for two kinds
+-of patterns: regular expressions and file-name wildcards.  The library
+-also provides a facility for expanding variable and command references
+-and parsing text into words in the way the shell does.
+-
+-* Menu:
+-
+-* Wildcard Matching::    Matching a wildcard pattern against a single string.
+-* Globbing::             Finding the files that match a wildcard pattern.
+-* Regular Expressions::  Matching regular expressions against strings.
+-* Word Expansion::       Expanding shell variables, nested commands,
+-                          arithmetic, and wildcards.
+-                          This is what the shell does with shell commands.
+-
+-
+-File: libc.info,  Node: Wildcard Matching,  Next: Globbing,  Up: Pattern 
Matching
+-
+-Wildcard Matching
+-=================
+-
+-   This section describes how to match a wildcard pattern against a
+-particular string.  The result is a yes or no answer: does the string
+-fit the pattern or not.  The symbols described here are all declared in
+-`fnmatch.h'.
+-
+- - Function: int fnmatch (const char *PATTERN, const char *STRING, int
+-          FLAGS)
+-     This function tests whether the string STRING matches the pattern
+-     PATTERN.  It returns `0' if they do match; otherwise, it returns
+-     the nonzero value `FNM_NOMATCH'.  The arguments PATTERN and STRING
+-     are both strings.
+-
+-     The argument FLAGS is a combination of flag bits that alter the
+-     details of matching.  See below for a list of the defined flags.
+-
+-     In the GNU C Library, `fnmatch' cannot experience an "error"--it
+-     always returns an answer for whether the match succeeds.  However,
+-     other implementations of `fnmatch' might sometimes report "errors".
+-     They would do so by returning nonzero values that are not equal to
+-     `FNM_NOMATCH'.
+-
+-   These are the available flags for the FLAGS argument:
+-
+-`FNM_FILE_NAME'
+-     Treat the `/' character specially, for matching file names.  If
+-     this flag is set, wildcard constructs in PATTERN cannot match `/'
+-     in STRING.  Thus, the only way to match `/' is with an explicit
+-     `/' in PATTERN.
+-
+-`FNM_PATHNAME'
+-     This is an alias for `FNM_FILE_NAME'; it comes from POSIX.2.  We
+-     don't recommend this name because we don't use the term "pathname"
+-     for file names.
+-
+-`FNM_PERIOD'
+-     Treat the `.' character specially if it appears at the beginning of
+-     STRING.  If this flag is set, wildcard constructs in PATTERN
+-     cannot match `.' as the first character of STRING.
+-
+-     If you set both `FNM_PERIOD' and `FNM_FILE_NAME', then the special
+-     treatment applies to `.' following `/' as well as to `.' at the
+-     beginning of STRING.  (The shell uses the `FNM_PERIOD' and
+-     `FNM_FILE_NAME' falgs together for matching file names.)
+-
+-`FNM_NOESCAPE'
+-     Don't treat the `\' character specially in patterns.  Normally,
+-     `\' quotes the following character, turning off its special meaning
+-     (if any) so that it matches only itself.  When quoting is enabled,
+-     the pattern `\?' matches only the string `?', because the question
+-     mark in the pattern acts like an ordinary character.
+-
+-     If you use `FNM_NOESCAPE', then `\' is an ordinary character.
+-
+-`FNM_LEADING_DIR'
+-     Ignore a trailing sequence of characters starting with a `/' in
+-     STRING; that is to say, test whether STRING starts with a
+-     directory name that PATTERN matches.
+-
+-     If this flag is set, either `foo*' or `foobar' as a pattern would
+-     match the string `foobar/frobozz'.
+-
+-`FNM_CASEFOLD'
+-     Ignore case in comparing STRING to PATTERN.
+-
+-
+-File: libc.info,  Node: Globbing,  Next: Regular Expressions,  Prev: Wildcard 
Matching,  Up: Pattern Matching
+-
+-Globbing
+-========
+-
+-   The archetypal use of wildcards is for matching against the files in
+-a directory, and making a list of all the matches.  This is called
+-"globbing".
+-
+-   You could do this using `fnmatch', by reading the directory entries
+-one by one and testing each one with `fnmatch'.  But that would be slow
+-(and complex, since you would have to handle subdirectories by hand).
+-
+-   The library provides a function `glob' to make this particular use
+-of wildcards convenient.  `glob' and the other symbols in this section
+-are declared in `glob.h'.
+-
+-* Menu:
+-
+-* Calling Glob::        Basic use of `glob'.
+-* Flags for Globbing::  Flags that enable various options in `glob'.
+-
+-
+-File: libc.info,  Node: Calling Glob,  Next: Flags for Globbing,  Up: Globbing
+-
+-Calling `glob'
+---------------
+-
+-   The result of globbing is a vector of file names (strings).  To
+-return this vector, `glob' uses a special data type, `glob_t', which is
+-a structure.  You pass `glob' the address of the structure, and it
+-fills in the structure's fields to tell you about the results.
+-
+- - Data Type: glob_t
+-     This data type holds a pointer to a word vector.  More precisely,
+-     it records both the address of the word vector and its size.
+-
+-    `gl_pathc'
+-          The number of elements in the vector.
+-
+-    `gl_pathv'
+-          The address of the vector.  This field has type `char **'.
+-
+-    `gl_offs'
+-          The offset of the first real element of the vector, from its
+-          nominal address in the `gl_pathv' field.  Unlike the other
+-          fields, this is always an input to `glob', rather than an
+-          output from it.
+-
+-          If you use a nonzero offset, then that many elements at the
+-          beginning of the vector are left empty.  (The `glob' function
+-          fills them with null pointers.)
+-
+-          The `gl_offs' field is meaningful only if you use the
+-          `GLOB_DOOFFS' flag.  Otherwise, the offset is always zero
+-          regardless of what is in this field, and the first real
+-          element comes at the beginning of the vector.
+-
+- - Function: int glob (const char *PATTERN, int FLAGS, int (*ERRFUNC)
+-          (const char *FILENAME, int ERROR-CODE), glob_t *VECTOR-PTR)
+-     The function `glob' does globbing using the pattern PATTERN in the
+-     current directory.  It puts the result in a newly allocated
+-     vector, and stores the size and address of this vector into
+-     `*VECTOR-PTR'.  The argument FLAGS is a combination of bit flags;
+-     see *Note Flags for Globbing::, for details of the flags.
+-
+-     The result of globbing is a sequence of file names.  The function
+-     `glob' allocates a string for each resulting word, then allocates
+-     a vector of type `char **' to store the addresses of these
+-     strings.  The last element of the vector is a null pointer.  This
+-     vector is called the "word vector".
+-
+-     To return this vector, `glob' stores both its address and its
+-     length (number of elements, not counting the terminating null
+-     pointer) into `*VECTOR-PTR'.
+-
+-     Normally, `glob' sorts the file names alphabetically before
+-     returning them.  You can turn this off with the flag `GLOB_NOSORT'
+-     if you want to get the information as fast as possible.  Usually
+-     it's a good idea to let `glob' sort them--if you process the files
+-     in alphabetical order, the users will have a feel for the rate of
+-     progress that your application is making.
+-
+-     If `glob' succeeds, it returns 0.  Otherwise, it returns one of
+-     these error codes:
+-
+-    `GLOB_ABORTED'
+-          There was an error opening a directory, and you used the flag
+-          `GLOB_ERR' or your specified ERRFUNC returned a nonzero value.
+-          *Note Flags for Globbing::, for an explanation of the
+-          `GLOB_ERR' flag and ERRFUNC.
+-
+-    `GLOB_NOMATCH'
+-          The pattern didn't match any existing files.  If you use the
+-          `GLOB_NOCHECK' flag, then you never get this error code,
+-          because that flag tells `glob' to *pretend* that the pattern
+-          matched at least one file.
+-
+-    `GLOB_NOSPACE'
+-          It was impossible to allocate memory to hold the result.
+-
+-     In the event of an error, `glob' stores information in
+-     `*VECTOR-PTR' about all the matches it has found so far.
+-
+-
+-File: libc.info,  Node: Flags for Globbing,  Prev: Calling Glob,  Up: Globbing
+-
+-Flags for Globbing
+-------------------
+-
+-   This section describes the flags that you can specify in the FLAGS
+-argument to `glob'.  Choose the flags you want, and combine them with
+-the C bitwise OR operator `|'.
+-
+-`GLOB_APPEND'
+-     Append the words from this expansion to the vector of words
+-     produced by previous calls to `glob'.  This way you can
+-     effectively expand several words as if they were concatenated with
+-     spaces between them.
+-
+-     In order for appending to work, you must not modify the contents
+-     of the word vector structure between calls to `glob'.  And, if you
+-     set `GLOB_DOOFFS' in the first call to `glob', you must also set
+-     it when you append to the results.
+-
+-     Note that the pointer stored in `gl_pathv' may no longer be valid
+-     after you call `glob' the second time, because `glob' might have
+-     relocated the vector.  So always fetch `gl_pathv' from the
+-     `glob_t' structure after each `glob' call; *never* save the
+-     pointer across calls.
+-
+-`GLOB_DOOFFS'
+-     Leave blank slots at the beginning of the vector of words.  The
+-     `gl_offs' field says how many slots to leave.  The blank slots
+-     contain null pointers.
+-
+-`GLOB_ERR'
+-     Give up right away and report an error if there is any difficulty
+-     reading the directories that must be read in order to expand
+-     PATTERN fully.  Such difficulties might include a directory in
+-     which you don't have the requisite access.  Normally, `glob' tries
+-     its best to keep on going despite any errors, reading whatever
+-     directories it can.
+-
+-     You can exercise even more control than this by specifying an
+-     error-handler function ERRFUNC when you call `glob'.  If ERRFUNC
+-     is not a null pointer, then `glob' doesn't give up right away when
+-     it can't read a directory; instead, it calls ERRFUNC with two
+-     arguments, like this:
+-
+-          (*ERRFUNC) (FILENAME, ERROR-CODE)
+-
+-     The argument FILENAME is the name of the directory that `glob'
+-     couldn't open or couldn't read, and ERROR-CODE is the `errno'
+-     value that was reported to `glob'.
+-
+-     If the error handler function returns nonzero, then `glob' gives up
+-     right away.  Otherwise, it continues.
+-
+-`GLOB_MARK'
+-     If the pattern matches the name of a directory, append `/' to the
+-     directory's name when returning it.
+-
+-`GLOB_NOCHECK'
+-     If the pattern doesn't match any file names, return the pattern
+-     itself as if it were a file name that had been matched.
+-     (Normally, when the pattern doesn't match anything, `glob' returns
+-     that there were no matches.)
+-
+-`GLOB_NOSORT'
+-     Don't sort the file names; return them in no particular order.
+-     (In practice, the order will depend on the order of the entries in
+-     the directory.)  The only reason *not* to sort is to save time.
+-
+-`GLOB_NOESCAPE'
+-     Don't treat the `\' character specially in patterns.  Normally,
+-     `\' quotes the following character, turning off its special meaning
+-     (if any) so that it matches only itself.  When quoting is enabled,
+-     the pattern `\?' matches only the string `?', because the question
+-     mark in the pattern acts like an ordinary character.
+-
+-     If you use `GLOB_NOESCAPE', then `\' is an ordinary character.
+-
+-     `glob' does its work by calling the function `fnmatch' repeatedly.
+-     It handles the flag `GLOB_NOESCAPE' by turning on the
+-     `FNM_NOESCAPE' flag in calls to `fnmatch'.
+-
+-
+-File: libc.info,  Node: Regular Expressions,  Next: Word Expansion,  Prev: 
Globbing,  Up: Pattern Matching
+-
+-Regular Expression Matching
+-===========================
+-
+-   The GNU C library supports two interfaces for matching regular
+-expressions.  One is the standard POSIX.2 interface, and the other is
+-what the GNU system has had for many years.
+-
+-   Both interfaces are declared in the header file `regex.h'.  If you
+-define `_POSIX_C_SOURCE', then only the POSIX.2 functions, structures,
+-and constants are declared.
+-
+-* Menu:
+-
+-* POSIX Regexp Compilation::    Using `regcomp' to prepare to match.
+-* Flags for POSIX Regexps::     Syntax variations for `regcomp'.
+-* Matching POSIX Regexps::      Using `regexec' to match the compiled
+-                                 pattern that you get from `regcomp'.
+-* Regexp Subexpressions::       Finding which parts of the string were 
matched.
+-* Subexpression Complications:: Find points of which parts were matched.
+-* Regexp Cleanup::            Freeing storage; reporting errors.
+-
+-
+-File: libc.info,  Node: POSIX Regexp Compilation,  Next: Flags for POSIX 
Regexps,  Up: Regular Expressions
+-
+-POSIX Regular Expression Compilation
+-------------------------------------
+-
+-   Before you can actually match a regular expression, you must
+-"compile" it.  This is not true compilation--it produces a special data
+-structure, not machine instructions.  But it is like ordinary
+-compilation in that its purpose is to enable you to "execute" the
+-pattern fast.  (*Note Matching POSIX Regexps::, for how to use the
+-compiled regular expression for matching.)
+-
+-   There is a special data type for compiled regular expressions:
+-
+- - Data Type: regex_t
+-     This type of object holds a compiled regular expression.  It is
+-     actually a structure.  It has just one field that your programs
+-     should look at:
+-
+-    `re_nsub'
+-          This field holds the number of parenthetical subexpressions
+-          in the regular expression that was compiled.
+-
+-     There are several other fields, but we don't describe them here,
+-     because only the functions in the library should use them.
+-
+-   After you create a `regex_t' object, you can compile a regular
+-expression into it by calling `regcomp'.
+-
+- - Function: int regcomp (regex_t *COMPILED, const char *PATTERN, int
+-          CFLAGS)
+-     The function `regcomp' "compiles" a regular expression into a data
+-     structure that you can use with `regexec' to match against a
+-     string.  The compiled regular expression format is designed for
+-     efficient matching.  `regcomp' stores it into `*COMPILED'.
+-
+-     It's up to you to allocate an object of type `regex_t' and pass its
+-     address to `regcomp'.
+-
+-     The argument CFLAGS lets you specify various options that control
+-     the syntax and semantics of regular expressions.  *Note Flags for
+-     POSIX Regexps::.
+-
+-     If you use the flag `REG_NOSUB', then `regcomp' omits from the
+-     compiled regular expression the information necessary to record
+-     how subexpressions actually match.  In this case, you might as well
+-     pass `0' for the MATCHPTR and NMATCH arguments when you call
+-     `regexec'.
+-
+-     If you don't use `REG_NOSUB', then the compiled regular expression
+-     does have the capacity to record how subexpressions match.  Also,
+-     `regcomp' tells you how many subexpressions PATTERN has, by
+-     storing the number in `COMPILED->re_nsub'.  You can use that value
+-     to decide how long an array to allocate to hold information about
+-     subexpression matches.
+-
+-     `regcomp' returns `0' if it succeeds in compiling the regular
+-     expression; otherwise, it returns a nonzero error code (see the
+-     table below).  You can use `regerror' to produce an error message
+-     string describing the reason for a nonzero value; see *Note Regexp
+-     Cleanup::.
+-
+-
+-   Here are the possible nonzero values that `regcomp' can return:
+-
+-`REG_BADBR'
+-     There was an invalid `\{...\}' construct in the regular
+-     expression.  A valid `\{...\}' construct must contain either a
+-     single number, or two numbers in increasing order separated by a
+-     comma.
+-
+-`REG_BADPAT'
+-     There was a syntax error in the regular expression.
+-
+-`REG_BADRPT'
+-     A repetition operator such as `?' or `*' appeared in a bad
+-     position (with no preceding subexpression to act on).
+-
+-`REG_ECOLLATE'
+-     The regular expression referred to an invalid collating element
+-     (one not defined in the current locale for string collation).
+-     *Note Locale Categories::.
+-
+-`REG_ECTYPE'
+-     The regular expression referred to an invalid character class name.
+-
+-`REG_EESCAPE'
+-     The regular expression ended with `\'.
+-
+-`REG_ESUBREG'
+-     There was an invalid number in the `\DIGIT' construct.
+-
+-`REG_EBRACK'
+-     There were unbalanced square brackets in the regular expression.
+-
+-`REG_EPAREN'
+-     An extended regular expression had unbalanced parentheses, or a
+-     basic regular expression had unbalanced `\(' and `\)'.
+-
+-`REG_EBRACE'
+-     The regular expression had unbalanced `\{' and `\}'.
+-
+-`REG_ERANGE'
+-     One of the endpoints in a range expression was invalid.
+-
+-`REG_ESPACE'
+-     `regcomp' ran out of memory.
+-
+-
+-File: libc.info,  Node: Flags for POSIX Regexps,  Next: Matching POSIX 
Regexps,  Prev: POSIX Regexp Compilation,  Up: Regular Expressions
+-
+-Flags for POSIX Regular Expressions
+------------------------------------
+-
+-   These are the bit flags that you can use in the CFLAGS operand when
+-compiling a regular expression with `regcomp'.
+-
+-`REG_EXTENDED'
+-     Treat the pattern as an extended regular expression, rather than
+-     as a basic regular expression.
+-
+-`REG_ICASE'
+-     Ignore case when matching letters.
+-
+-`REG_NOSUB'
+-     Don't bother storing the contents of the MATCHES-PTR array.
+-
+-`REG_NEWLINE'
+-     Treat a newline in STRING as dividing STRING into multiple lines,
+-     so that `$' can match before the newline and `^' can match after.
+-     Also, don't permit `.' to match a newline, and don't permit
+-     `[^...]' to match a newline.
+-
+-     Otherwise, newline acts like any other ordinary character.
+-
+-
+-File: libc.info,  Node: Matching POSIX Regexps,  Next: Regexp Subexpressions, 
 Prev: Flags for POSIX Regexps,  Up: Regular Expressions
+-
+-Matching a Compiled POSIX Regular Expression
+---------------------------------------------
+-
+-   Once you have compiled a regular expression, as described in *Note
+-POSIX Regexp Compilation::, you can match it against strings using
+-`regexec'.  A match anywhere inside the string counts as success,
+-unless the regular expression contains anchor characters (`^' or `$').
+-
+- - Function: int regexec (regex_t *COMPILED, char *STRING, size_t
+-          NMATCH, regmatch_t MATCHPTR [], int EFLAGS)
+-     This function tries to match the compiled regular expression
+-     `*COMPILED' against STRING.
+-
+-     `regexec' returns `0' if the regular expression matches;
+-     otherwise, it returns a nonzero value.  See the table below for
+-     what nonzero values mean.  You can use `regerror' to produce an
+-     error message string describing the reason for a nonzero value;
+-     see *Note Regexp Cleanup::.
+-
+-     The argument EFLAGS is a word of bit flags that enable various
+-     options.
+-
+-     If you want to get information about what part of STRING actually
+-     matched the regular expression or its subexpressions, use the
+-     arguments MATCHPTR and NMATCH.  Otherwise, pass `0' for NMATCH,
+-     and `NULL' for MATCHPTR.  *Note Regexp Subexpressions::.
+-
+-   You must match the regular expression with the same set of current
+-locales that were in effect when you compiled the regular expression.
+-
+-   The function `regexec' accepts the following flags in the EFLAGS
+-argument:
+-
+-`REG_NOTBOL'
+-     Do not regard the beginning of the specified string as the
+-     beginning of a line; more generally, don't make any assumptions
+-     about what text might precede it.
+-
+-`REG_NOTEOL'
+-     Do not regard the end of the specified string as the end of a
+-     line; more generally, don't make any assumptions about what text
+-     might follow it.
+-
+-   Here are the possible nonzero values that `regexec' can return:
+-
+-`REG_NOMATCH'
+-     The pattern didn't match the string.  This isn't really an error.
+-
+-`REG_ESPACE'
+-     `regexec' ran out of memory.
+-
+-
+-File: libc.info,  Node: Regexp Subexpressions,  Next: Subexpression 
Complications,  Prev: Matching POSIX Regexps,  Up: Regular Expressions
+-
+-Match Results with Subexpressions
+----------------------------------
+-
+-   When `regexec' matches parenthetical subexpressions of PATTERN, it
+-records which parts of STRING they match.  It returns that information
+-by storing the offsets into an array whose elements are structures of
+-type `regmatch_t'.  The first element of the array (index `0') records
+-the part of the string that matched the entire regular expression.
+-Each other element of the array records the beginning and end of the
+-part that matched a single parenthetical subexpression.
+-
+- - Data Type: regmatch_t
+-     This is the data type of the MATCHARRAY array that you pass to
+-     `regexec'.  It contains two structure fields, as follows:
+-
+-    `rm_so'
+-          The offset in STRING of the beginning of a substring.  Add
+-          this value to STRING to get the address of that part.
+-
+-    `rm_eo'
+-          The offset in STRING of the end of the substring.
+-
+- - Data Type: regoff_t
+-     `regoff_t' is an alias for another signed integer type.  The
+-     fields of `regmatch_t' have type `regoff_t'.
+-
+-   The `regmatch_t' elements correspond to subexpressions positionally;
+-the first element (index `1') records where the first subexpression
+-matched, the second element records the second subexpression, and so
+-on.  The order of the subexpressions is the order in which they begin.
+-
+-   When you call `regexec', you specify how long the MATCHPTR array is,
+-with the NMATCH argument.  This tells `regexec' how many elements to
+-store.  If the actual regular expression has more than NMATCH
+-subexpressions, then you won't get offset information about the rest of
+-them.  But this doesn't alter whether the pattern matches a particular
+-string or not.
+-
+-   If you don't want `regexec' to return any information about where
+-the subexpressions matched, you can either supply `0' for NMATCH, or
+-use the flag `REG_NOSUB' when you compile the pattern with `regcomp'.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-17 
glibc-2.0.1/manual/libc.info-17
+--- ../glibc-2.0.1/manual/libc.info-17 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-17    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1227 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Subexpression Complications,  Next: Regexp Cleanup,  
Prev: Regexp Subexpressions,  Up: Regular Expressions
+-
+-Complications in Subexpression Matching
+----------------------------------------
+-
+-   Sometimes a subexpression matches a substring of no characters.  This
+-happens when `f\(o*\)' matches the string `fum'.  (It really matches
+-just the `f'.)  In this case, both of the offsets identify the point in
+-the string where the null substring was found.  In this example, the
+-offsets are both `1'.
+-
+-   Sometimes the entire regular expression can match without using some
+-of its subexpressions at all--for example, when `ba\(na\)*' matches the
+-string `ba', the parenthetical subexpression is not used.  When this
+-happens, `regexec' stores `-1' in both fields of the element for that
+-subexpression.
+-
+-   Sometimes matching the entire regular expression can match a
+-particular subexpression more than once--for example, when `ba\(na\)*'
+-matches the string `bananana', the parenthetical subexpression matches
+-three times.  When this happens, `regexec' usually stores the offsets
+-of the last part of the string that matched the subexpression.  In the
+-case of `bananana', these offsets are `6' and `8'.
+-
+-   But the last match is not always the one that is chosen.  It's more
+-accurate to say that the last *opportunity* to match is the one that
+-takes precedence.  What this means is that when one subexpression
+-appears within another, then the results reported for the inner
+-subexpression reflect whatever happened on the last match of the outer
+-subexpression.  For an example, consider `\(ba\(na\)*s \)*' matching
+-the string `bananas bas '.  The last time the inner expression actually
+-matches is near the end of the first word.  But it is *considered*
+-again in the second word, and fails to match there.  `regexec' reports
+-nonuse of the "na" subexpression.
+-
+-   Another place where this rule applies is when the regular expression
+-`\(ba\(na\)*s \|nefer\(ti\)* \)*' matches `bananas nefertiti'.  The
+-"na" subexpression does match in the first word, but it doesn't match
+-in the second word because the other alternative is used there.  Once
+-again, the second repetition of the outer subexpression overrides the
+-first, and within that second repetition, the "na" subexpression is not
+-used.  So `regexec' reports nonuse of the "na" subexpression.
+-
+-
+-File: libc.info,  Node: Regexp Cleanup,  Prev: Subexpression Complications,  
Up: Regular Expressions
+-
+-POSIX Regexp Matching Cleanup
+------------------------------
+-
+-   When you are finished using a compiled regular expression, you can
+-free the storage it uses by calling `regfree'.
+-
+- - Function: void regfree (regex_t *COMPILED)
+-     Calling `regfree' frees all the storage that `*COMPILED' points
+-     to.  This includes various internal fields of the `regex_t'
+-     structure that aren't documented in this manual.
+-
+-     `regfree' does not free the object `*COMPILED' itself.
+-
+-   You should always free the space in a `regex_t' structure with
+-`regfree' before using the structure to compile another regular
+-expression.
+-
+-   When `regcomp' or `regexec' reports an error, you can use the
+-function `regerror' to turn it into an error message string.
+-
+- - Function: size_t regerror (int ERRCODE, regex_t *COMPILED, char
+-          *BUFFER, size_t LENGTH)
+-     This function produces an error message string for the error code
+-     ERRCODE, and stores the string in LENGTH bytes of memory starting
+-     at BUFFER.  For the COMPILED argument, supply the same compiled
+-     regular expression structure that `regcomp' or `regexec' was
+-     working with when it got the error.  Alternatively, you can supply
+-     `NULL' for COMPILED; you will still get a meaningful error
+-     message, but it might not be as detailed.
+-
+-     If the error message can't fit in LENGTH bytes (including a
+-     terminating null character), then `regerror' truncates it.  The
+-     string that `regerror' stores is always null-terminated even if it
+-     has been truncated.
+-
+-     The return value of `regerror' is the minimum length needed to
+-     store the entire error message.  If this is less than LENGTH, then
+-     the error message was not truncated, and you can use it.
+-     Otherwise, you should call `regerror' again with a larger buffer.
+-
+-     Here is a function which uses `regerror', but always dynamically
+-     allocates a buffer for the error message:
+-
+-          char *get_regerror (int errcode, regex_t *compiled)
+-          {
+-            size_t length = regerror (errcode, compiled, NULL, 0);
+-            char *buffer = xmalloc (length);
+-            (void) regerror (errcode, compiled, buffer, length);
+-            return buffer;
+-          }
+-
+-
+-File: libc.info,  Node: Word Expansion,  Prev: Regular Expressions,  Up: 
Pattern Matching
+-
+-Shell-Style Word Expansion
+-==========================
+-
+-   "Word expansion" means the process of splitting a string into
+-"words" and substituting for variables, commands, and wildcards just as
+-the shell does.
+-
+-   For example, when you write `ls -l foo.c', this string is split into
+-three separate words--`ls', `-l' and `foo.c'.  This is the most basic
+-function of word expansion.
+-
+-   When you write `ls *.c', this can become many words, because the
+-word `*.c' can be replaced with any number of file names.  This is
+-called "wildcard expansion", and it is also a part of word expansion.
+-
+-   When you use `echo $PATH' to print your path, you are taking
+-advantage of "variable substitution", which is also part of word
+-expansion.
+-
+-   Ordinary programs can perform word expansion just like the shell by
+-calling the library function `wordexp'.
+-
+-* Menu:
+-
+-* Expansion Stages::  What word expansion does to a string.
+-* Calling Wordexp::   How to call `wordexp'.
+-* Flags for Wordexp::   Options you can enable in `wordexp'.
+-* Wordexp Example::   A sample program that does word expansion.
+-
+-
+-File: libc.info,  Node: Expansion Stages,  Next: Calling Wordexp,  Up: Word 
Expansion
+-
+-The Stages of Word Expansion
+-----------------------------
+-
+-   When word expansion is applied to a sequence of words, it performs
+-the following transformations in the order shown here:
+-
+-  1. "Tilde expansion": Replacement of `~foo' with the name of the home
+-     directory of `foo'.
+-
+-  2. Next, three different transformations are applied in the same step,
+-     from left to right:
+-
+-        * "Variable substitution": Environment variables are
+-          substituted for references such as `$foo'.
+-
+-        * "Command substitution": Constructs such as ``cat foo`' and
+-          the equivalent `$(cat foo)' are replaced with the output from
+-          the inner command.
+-
+-        * "Arithmetic expansion": Constructs such as `$(($x-1))' are
+-          replaced with the result of the arithmetic computation.
+-
+-  3. "Field splitting": subdivision of the text into "words".
+-
+-  4. "Wildcard expansion": The replacement of a construct such as `*.c'
+-     with a list of `.c' file names.  Wildcard expansion applies to an
+-     entire word at a time, and replaces that word with 0 or more file
+-     names that are themselves words.
+-
+-  5. "Quote removal": The deletion of string-quotes, now that they have
+-     done their job by inhibiting the above transformations when
+-     appropriate.
+-
+-   For the details of these transformations, and how to write the
+-constructs that use them, see `The BASH Manual' (to appear).
+-
+-
+-File: libc.info,  Node: Calling Wordexp,  Next: Flags for Wordexp,  Prev: 
Expansion Stages,  Up: Word Expansion
+-
+-Calling `wordexp'
+------------------
+-
+-   All the functions, constants and data types for word expansion are
+-declared in the header file `wordexp.h'.
+-
+-   Word expansion produces a vector of words (strings).  To return this
+-vector, `wordexp' uses a special data type, `wordexp_t', which is a
+-structure.  You pass `wordexp' the address of the structure, and it
+-fills in the structure's fields to tell you about the results.
+-
+- - Data Type: wordexp_t
+-     This data type holds a pointer to a word vector.  More precisely,
+-     it records both the address of the word vector and its size.
+-
+-    `we_wordc'
+-          The number of elements in the vector.
+-
+-    `we_wordv'
+-          The address of the vector.  This field has type `char **'.
+-
+-    `we_offs'
+-          The offset of the first real element of the vector, from its
+-          nominal address in the `we_wordv' field.  Unlike the other
+-          fields, this is always an input to `wordexp', rather than an
+-          output from it.
+-
+-          If you use a nonzero offset, then that many elements at the
+-          beginning of the vector are left empty.  (The `wordexp'
+-          function fills them with null pointers.)
+-
+-          The `we_offs' field is meaningful only if you use the
+-          `WRDE_DOOFFS' flag.  Otherwise, the offset is always zero
+-          regardless of what is in this field, and the first real
+-          element comes at the beginning of the vector.
+-
+- - Function: int wordexp (const char *WORDS, wordexp_t
+-          *WORD-VECTOR-PTR, int FLAGS)
+-     Perform word expansion on the string WORDS, putting the result in
+-     a newly allocated vector, and store the size and address of this
+-     vector into `*WORD-VECTOR-PTR'.  The argument FLAGS is a
+-     combination of bit flags; see *Note Flags for Wordexp::, for
+-     details of the flags.
+-
+-     You shouldn't use any of the characters `|&;<>' in the string
+-     WORDS unless they are quoted; likewise for newline.  If you use
+-     these characters unquoted, you will get the `WRDE_BADCHAR' error
+-     code.  Don't use parentheses or braces unless they are quoted or
+-     part of a word expansion construct.  If you use quotation
+-     characters `'"`', they should come in pairs that balance.
+-
+-     The results of word expansion are a sequence of words.  The
+-     function `wordexp' allocates a string for each resulting word, then
+-     allocates a vector of type `char **' to store the addresses of
+-     these strings.  The last element of the vector is a null pointer.
+-     This vector is called the "word vector".
+-
+-     To return this vector, `wordexp' stores both its address and its
+-     length (number of elements, not counting the terminating null
+-     pointer) into `*WORD-VECTOR-PTR'.
+-
+-     If `wordexp' succeeds, it returns 0.  Otherwise, it returns one of
+-     these error codes:
+-
+-    `WRDE_BADCHAR'
+-          The input string WORDS contains an unquoted invalid character
+-          such as `|'.
+-
+-    `WRDE_BADVAL'
+-          The input string refers to an undefined shell variable, and
+-          you used the flag `WRDE_UNDEF' to forbid such references.
+-
+-    `WRDE_CMDSUB'
+-          The input string uses command substitution, and you used the
+-          flag `WRDE_NOCMD' to forbid command substitution.
+-
+-    `WRDE_NOSPACE'
+-          It was impossible to allocate memory to hold the result.  In
+-          this case, `wordexp' can store part of the results--as much
+-          as it could allocate room for.
+-
+-    `WRDE_SYNTAX'
+-          There was a syntax error in the input string.  For example,
+-          an unmatched quoting character is a syntax error.
+-
+- - Function: void wordfree (wordexp_t *WORD-VECTOR-PTR)
+-     Free the storage used for the word-strings and vector that
+-     `*WORD-VECTOR-PTR' points to.  This does not free the structure
+-     `*WORD-VECTOR-PTR' itself--only the other data it points to.
+-
+-
+-File: libc.info,  Node: Flags for Wordexp,  Next: Wordexp Example,  Prev: 
Calling Wordexp,  Up: Word Expansion
+-
+-Flags for Word Expansion
+-------------------------
+-
+-   This section describes the flags that you can specify in the FLAGS
+-argument to `wordexp'.  Choose the flags you want, and combine them
+-with the C operator `|'.
+-
+-`WRDE_APPEND'
+-     Append the words from this expansion to the vector of words
+-     produced by previous calls to `wordexp'.  This way you can
+-     effectively expand several words as if they were concatenated with
+-     spaces between them.
+-
+-     In order for appending to work, you must not modify the contents
+-     of the word vector structure between calls to `wordexp'.  And, if
+-     you set `WRDE_DOOFFS' in the first call to `wordexp', you must also
+-     set it when you append to the results.
+-
+-`WRDE_DOOFFS'
+-     Leave blank slots at the beginning of the vector of words.  The
+-     `we_offs' field says how many slots to leave.  The blank slots
+-     contain null pointers.
+-
+-`WRDE_NOCMD'
+-     Don't do command substitution; if the input requests command
+-     substitution, report an error.
+-
+-`WRDE_REUSE'
+-     Reuse a word vector made by a previous call to `wordexp'.  Instead
+-     of allocating a new vector of words, this call to `wordexp' will
+-     use the vector that already exists (making it larger if necessary).
+-
+-     Note that the vector may move, so it is not safe to save an old
+-     pointer and use it again after calling `wordexp'.  You must fetch
+-     `we_pathv' anew after each call.
+-
+-`WRDE_SHOWERR'
+-     Do show any error messages printed by commands run by command
+-     substitution.  More precisely, allow these commands to inherit the
+-     standard error output stream of the current process.  By default,
+-     `wordexp' gives these commands a standard error stream that
+-     discards all output.
+-
+-`WRDE_UNDEF'
+-     If the input refers to a shell variable that is not defined,
+-     report an error.
+-
+-
+-File: libc.info,  Node: Wordexp Example,  Prev: Flags for Wordexp,  Up: Word 
Expansion
+-
+-`wordexp' Example
+------------------
+-
+-   Here is an example of using `wordexp' to expand several strings and
+-use the results to run a shell command.  It also shows the use of
+-`WRDE_APPEND' to concatenate the expansions and of `wordfree' to free
+-the space allocated by `wordexp'.
+-
+-     int
+-     expand_and_execute (const char *program, const char *options)
+-     {
+-       wordexp_t result;
+-       pid_t pid
+-       int status, i;
+-     
+-       /* Expand the string for the program to run.  */
+-       switch (wordexp (program, &result, 0))
+-         {
+-         case 0:                      /* Successful.  */
+-           break;
+-         case WRDE_NOSPACE:
+-           /* If the error was `WRDE_NOSPACE',
+-              then perhaps part of the result was allocated.  */
+-           wordfree (&result);
+-         default:                    /* Some other error.  */
+-           return -1;
+-         }
+-     
+-       /* Expand the strings specified for the arguments.  */
+-       for (i = 0; args[i]; i++)
+-         {
+-           if (wordexp (options, &result, WRDE_APPEND))
+-             {
+-               wordfree (&result);
+-               return -1;
+-             }
+-         }
+-     
+-       pid = fork ();
+-       if (pid == 0)
+-         {
+-           /* This is the child process.  Execute the command. */
+-           execv (result.we_wordv[0], result.we_wordv);
+-           exit (EXIT_FAILURE);
+-         }
+-       else if (pid < 0)
+-         /* The fork failed.  Report failure.  */
+-         status = -1;
+-       else
+-         /* This is the parent process.  Wait for the child to complete.  */
+-         if (waitpid (pid, &status, 0) != pid)
+-           status = -1;
+-     
+-       wordfree (&result);
+-       return status;
+-     }
+-
+-   In practice, since `wordexp' is executed by running a subshell, it
+-would be faster to do this by concatenating the strings with spaces
+-between them and running that as a shell command using `sh -c'.
+-
+-
+-File: libc.info,  Node: Date and Time,  Next: Non-Local Exits,  Prev: 
Arithmetic,  Up: Top
+-
+-Date and Time
+-*************
+-
+-   This chapter describes functions for manipulating dates and times,
+-including functions for determining what the current time is and
+-conversion between different time representations.
+-
+-   The time functions fall into three main categories:
+-
+-   * Functions for measuring elapsed CPU time are discussed in *Note
+-     Processor Time::.
+-
+-   * Functions for measuring absolute clock or calendar time are
+-     discussed in *Note Calendar Time::.
+-
+-   * Functions for setting alarms and timers are discussed in *Note
+-     Setting an Alarm::.
+-
+-* Menu:
+-
+-* Processor Time::              Measures processor time used by a program.
+-* Calendar Time::               Manipulation of "real" dates and times.
+-* Setting an Alarm::            Sending a signal after a specified time.
+-* Sleeping::                    Waiting for a period of time.
+-* Resource Usage::            Measuring various resources used.
+-* Limits on Resources::               Specifying limits on resource usage.
+-* Priority::                  Reading or setting process run priority.
+-
+-
+-File: libc.info,  Node: Processor Time,  Next: Calendar Time,  Up: Date and 
Time
+-
+-Processor Time
+-==============
+-
+-   If you're trying to optimize your program or measure its efficiency,
+-it's very useful to be able to know how much "processor time" or "CPU
+-time" it has used at any given point.  Processor time is different from
+-actual wall clock time because it doesn't include any time spent waiting
+-for I/O or when some other process is running.  Processor time is
+-represented by the data type `clock_t', and is given as a number of
+-"clock ticks" relative to an arbitrary base time marking the beginning
+-of a single program invocation.
+-
+-* Menu:
+-
+-* Basic CPU Time::              The `clock' function.
+-* Detailed CPU Time::           The `times' function.
+-
+-
+-File: libc.info,  Node: Basic CPU Time,  Next: Detailed CPU Time,  Up: 
Processor Time
+-
+-Basic CPU Time Inquiry
+-----------------------
+-
+-   To get the elapsed CPU time used by a process, you can use the
+-`clock' function.  This facility is declared in the header file
+-`time.h'.
+-
+-   In typical usage, you call the `clock' function at the beginning and
+-end of the interval you want to time, subtract the values, and then
+-divide by `CLOCKS_PER_SEC' (the number of clock ticks per second), like
+-this:
+-
+-     #include <time.h>
+-     
+-     clock_t start, end;
+-     double elapsed;
+-     
+-     start = clock();
+-     ... /* Do the work. */
+-     end = clock();
+-     elapsed = ((double) (end - start)) / CLOCKS_PER_SEC;
+-
+-   Different computers and operating systems vary wildly in how they
+-keep track of processor time.  It's common for the internal processor
+-clock to have a resolution somewhere between hundredths and millionths
+-of a second.
+-
+-   In the GNU system, `clock_t' is equivalent to `long int' and
+-`CLOCKS_PER_SEC' is an integer value.  But in other systems, both
+-`clock_t' and the type of the macro `CLOCKS_PER_SEC' can be either
+-integer or floating-point types.  Casting processor time values to
+-`double', as in the example above, makes sure that operations such as
+-arithmetic and printing work properly and consistently no matter what
+-the underlying representation is.
+-
+- - Macro: int CLOCKS_PER_SEC
+-     The value of this macro is the number of clock ticks per second
+-     measured by the `clock' function.
+-
+- - Macro: int CLK_TCK
+-     This is an obsolete name for `CLOCKS_PER_SEC'.
+-
+- - Data Type: clock_t
+-     This is the type of the value returned by the `clock' function.
+-     Values of type `clock_t' are in units of clock ticks.
+-
+- - Function: clock_t clock (void)
+-     This function returns the elapsed processor time.  The base time is
+-     arbitrary but doesn't change within a single process.  If the
+-     processor time is not available or cannot be represented, `clock'
+-     returns the value `(clock_t)(-1)'.
+-
+-
+-File: libc.info,  Node: Detailed CPU Time,  Prev: Basic CPU Time,  Up: 
Processor Time
+-
+-Detailed Elapsed CPU Time Inquiry
+----------------------------------
+-
+-   The `times' function returns more detailed information about elapsed
+-processor time in a `struct tms' object.  You should include the header
+-file `sys/times.h' to use this facility.
+-
+- - Data Type: struct tms
+-     The `tms' structure is used to return information about process
+-     times.  It contains at least the following members:
+-
+-    `clock_t tms_utime'
+-          This is the CPU time used in executing the instructions of
+-          the calling process.
+-
+-    `clock_t tms_stime'
+-          This is the CPU time used by the system on behalf of the
+-          calling process.
+-
+-    `clock_t tms_cutime'
+-          This is the sum of the `tms_utime' values and the `tms_cutime'
+-          values of all terminated child processes of the calling
+-          process, whose status has been reported to the parent process
+-          by `wait' or `waitpid'; see *Note Process Completion::.  In
+-          other words, it represents the total CPU time used in
+-          executing the instructions of all the terminated child
+-          processes of the calling process, excluding child processes
+-          which have not yet been reported by `wait' or `waitpid'.
+-
+-    `clock_t tms_cstime'
+-          This is similar to `tms_cutime', but represents the total CPU
+-          time used by the system on behalf of all the terminated child
+-          processes of the calling process.
+-
+-     All of the times are given in clock ticks.  These are absolute
+-     values; in a newly created process, they are all zero.  *Note
+-     Creating a Process::.
+-
+- - Function: clock_t times (struct tms *BUFFER)
+-     The `times' function stores the processor time information for the
+-     calling process in BUFFER.
+-
+-     The return value is the same as the value of `clock()': the elapsed
+-     real time relative to an arbitrary base.  The base is a constant
+-     within a particular process, and typically represents the time
+-     since system start-up.  A value of `(clock_t)(-1)' is returned to
+-     indicate failure.
+-
+-   *Portability Note:* The `clock' function described in *Note Basic
+-CPU Time::, is specified by the ISO C standard.  The `times' function
+-is a feature of POSIX.1.  In the GNU system, the value returned by the
+-`clock' function is equivalent to the sum of the `tms_utime' and
+-`tms_stime' fields returned by `times'.
+-
+-
+-File: libc.info,  Node: Calendar Time,  Next: Setting an Alarm,  Prev: 
Processor Time,  Up: Date and Time
+-
+-Calendar Time
+-=============
+-
+-   This section describes facilities for keeping track of dates and
+-times according to the Gregorian calendar.
+-
+-   There are three representations for date and time information:
+-
+-   * "Calendar time" (the `time_t' data type) is a compact
+-     representation, typically giving the number of seconds elapsed
+-     since some implementation-specific base time.
+-
+-   * There is also a "high-resolution time" representation (the `struct
+-     timeval' data type) that includes fractions of a second.  Use this
+-     time representation instead of ordinary calendar time when you
+-     need greater precision.
+-
+-   * "Local time" or "broken-down time" (the `struct tm' data type)
+-     represents the date and time as a set of components specifying the
+-     year, month, and so on, for a specific time zone.  This time
+-     representation is usually used in conjunction with formatting date
+-     and time values.
+-
+-* Menu:
+-
+-* Simple Calendar Time::        Facilities for manipulating calendar time.
+-* High-Resolution Calendar::    A time representation with greater precision.
+-* Broken-down Time::            Facilities for manipulating local time.
+-* Formatting Date and Time::    Converting times to strings.
+-* TZ Variable::                 How users specify the time zone.
+-* Time Zone Functions::         Functions to examine or specify the time zone.
+-* Time Functions Example::      An example program showing use of some of
+-                               the time functions.
+-
+-
+-File: libc.info,  Node: Simple Calendar Time,  Next: High-Resolution 
Calendar,  Up: Calendar Time
+-
+-Simple Calendar Time
+---------------------
+-
+-   This section describes the `time_t' data type for representing
+-calendar time, and the functions which operate on calendar time objects.
+-These facilities are declared in the header file `time.h'.
+-
+- - Data Type: time_t
+-     This is the data type used to represent calendar time.  When
+-     interpreted as an absolute time value, it represents the number of
+-     seconds elapsed since 00:00:00 on January 1, 1970, Coordinated
+-     Universal Time.  (This date is sometimes referred to as the
+-     "epoch".)  POSIX requires that this count ignore leap seconds, but
+-     on some hosts this count includes leap seconds if you set `TZ' to
+-     certain values (*note TZ Variable::.).
+-
+-     In the GNU C library, `time_t' is equivalent to `long int'.  In
+-     other systems, `time_t' might be either an integer or
+-     floating-point type.
+-
+- - Function: double difftime (time_t TIME1, time_t TIME0)
+-     The `difftime' function returns the number of seconds elapsed
+-     between time TIME1 and time TIME0, as a value of type `double'.
+-     The difference ignores leap seconds unless leap second support is
+-     enabled.
+-
+-     In the GNU system, you can simply subtract `time_t' values.  But on
+-     other systems, the `time_t' data type might use some other encoding
+-     where subtraction doesn't work directly.
+-
+- - Function: time_t time (time_t *RESULT)
+-     The `time' function returns the current time as a value of type
+-     `time_t'.  If the argument RESULT is not a null pointer, the time
+-     value is also stored in `*RESULT'.  If the calendar time is not
+-     available, the value `(time_t)(-1)' is returned.
+-
+-
+-File: libc.info,  Node: High-Resolution Calendar,  Next: Broken-down Time,  
Prev: Simple Calendar Time,  Up: Calendar Time
+-
+-High-Resolution Calendar
+-------------------------
+-
+-   The `time_t' data type used to represent calendar times has a
+-resolution of only one second.  Some applications need more precision.
+-
+-   So, the GNU C library also contains functions which are capable of
+-representing calendar times to a higher resolution than one second.  The
+-functions and the associated data types described in this section are
+-declared in `sys/time.h'.
+-
+- - Data Type: struct timeval
+-     The `struct timeval' structure represents a calendar time.  It has
+-     the following members:
+-
+-    `long int tv_sec'
+-          This represents the number of seconds since the epoch.  It is
+-          equivalent to a normal `time_t' value.
+-
+-    `long int tv_usec'
+-          This is the fractional second value, represented as the
+-          number of microseconds.
+-
+-          Some times struct timeval values are used for time intervals.
+-          Then the `tv_sec' member is the number of seconds in the
+-          interval, and `tv_usec' is the number of additional
+-          microseconds.
+-
+- - Data Type: struct timezone
+-     The `struct timezone' structure is used to hold minimal information
+-     about the local time zone.  It has the following members:
+-
+-    `int tz_minuteswest'
+-          This is the number of minutes west of UTC.
+-
+-    `int tz_dsttime'
+-          If nonzero, daylight saving time applies during some part of
+-          the year.
+-
+-     The `struct timezone' type is obsolete and should never be used.
+-     Instead, use the facilities described in *Note Time Zone
+-     Functions::.
+-
+-   It is often necessary to subtract two values of type
+-`struct timeval'.  Here is the best way to do this.  It works even on
+-some peculiar operating systems where the `tv_sec' member has an
+-unsigned type.
+-
+-     /* Subtract the `struct timeval' values X and Y,
+-        storing the result in RESULT.
+-        Return 1 if the difference is negative, otherwise 0.  */
+-     
+-     int
+-     timeval_subtract (result, x, y)
+-          struct timeval *result, *x, *y;
+-     {
+-       /* Perform the carry for the later subtraction by updating Y. */
+-       if (x->tv_usec < y->tv_usec) {
+-         int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
+-         y->tv_usec -= 1000000 * nsec;
+-         y->tv_sec += nsec;
+-       }
+-       if (x->tv_usec - y->tv_usec > 1000000) {
+-         int nsec = (y->tv_usec - x->tv_usec) / 1000000;
+-         y->tv_usec += 1000000 * nsec;
+-         y->tv_sec -= nsec;
+-       }
+-     
+-       /* Compute the time remaining to wait.
+-          `tv_usec' is certainly positive. */
+-       result->tv_sec = x->tv_sec - y->tv_sec;
+-       result->tv_usec = x->tv_usec - y->tv_usec;
+-     
+-       /* Return 1 if result is negative. */
+-       return x->tv_sec < y->tv_sec;
+-     }
+-
+- - Function: int gettimeofday (struct timeval *TP, struct timezone *TZP)
+-     The `gettimeofday' function returns the current date and time in
+-     the `struct timeval' structure indicated by TP.  Information about
+-     the time zone is returned in the structure pointed at TZP.  If the
+-     TZP argument is a null pointer, time zone information is ignored.
+-
+-     The return value is `0' on success and `-1' on failure.  The
+-     following `errno' error condition is defined for this function:
+-
+-    `ENOSYS'
+-          The operating system does not support getting time zone
+-          information, and TZP is not a null pointer.  The GNU
+-          operating system does not support using `struct timezone' to
+-          represent time zone information; that is an obsolete feature
+-          of 4.3 BSD.  Instead, use the facilities described in *Note
+-          Time Zone Functions::.
+-
+- - Function: int settimeofday (const struct timeval *TP, const struct
+-          timezone *TZP)
+-     The `settimeofday' function sets the current date and time
+-     according to the arguments.  As for `gettimeofday', time zone
+-     information is ignored if TZP is a null pointer.
+-
+-     You must be a privileged user in order to use `settimeofday'.
+-
+-     The return value is `0' on success and `-1' on failure.  The
+-     following `errno' error conditions are defined for this function:
+-
+-    `EPERM'
+-          This process cannot set the time because it is not privileged.
+-
+-    `ENOSYS'
+-          The operating system does not support setting time zone
+-          information, and TZP is not a null pointer.
+-
+- - Function: int adjtime (const struct timeval *DELTA, struct timeval
+-          *OLDDELTA)
+-     This function speeds up or slows down the system clock in order to
+-     make gradual adjustments in the current time.  This ensures that
+-     the time reported by the system clock is always monotonically
+-     increasing, which might not happen if you simply set the current
+-     time.
+-
+-     The DELTA argument specifies a relative adjustment to be made to
+-     the current time.  If negative, the system clock is slowed down
+-     for a while until it has lost this much time.  If positive, the
+-     system clock is speeded up for a while.
+-
+-     If the OLDDELTA argument is not a null pointer, the `adjtime'
+-     function returns information about any previous time adjustment
+-     that has not yet completed.
+-
+-     This function is typically used to synchronize the clocks of
+-     computers in a local network.  You must be a privileged user to
+-     use it.  The return value is `0' on success and `-1' on failure.
+-     The following `errno' error condition is defined for this function:
+-
+-    `EPERM'
+-          You do not have privilege to set the time.
+-
+-   *Portability Note:*  The `gettimeofday', `settimeofday', and
+-`adjtime' functions are derived from BSD.
+-
+-
+-File: libc.info,  Node: Broken-down Time,  Next: Formatting Date and Time,  
Prev: High-Resolution Calendar,  Up: Calendar Time
+-
+-Broken-down Time
+-----------------
+-
+-   Calendar time is represented as a number of seconds.  This is
+-convenient for calculation, but has no resemblance to the way people
+-normally represent dates and times.  By contrast, "broken-down time" is
+-a binary representation separated into year, month, day, and so on.
+-Broken down time values are not useful for calculations, but they are
+-useful for printing human readable time.
+-
+-   A broken-down time value is always relative to a choice of local time
+-zone, and it also indicates which time zone was used.
+-
+-   The symbols in this section are declared in the header file `time.h'.
+-
+- - Data Type: struct tm
+-     This is the data type used to represent a broken-down time.  The
+-     structure contains at least the following members, which can
+-     appear in any order:
+-
+-    `int tm_sec'
+-          This is the number of seconds after the minute, normally in
+-          the range `0' through `59'.  (The actual upper limit is `60',
+-          to allow for leap seconds if leap second support is
+-          available.)
+-
+-    `int tm_min'
+-          This is the number of minutes after the hour, in the range
+-          `0' through `59'.
+-
+-    `int tm_hour'
+-          This is the number of hours past midnight, in the range `0'
+-          through `23'.
+-
+-    `int tm_mday'
+-          This is the day of the month, in the range `1' through `31'.
+-
+-    `int tm_mon'
+-          This is the number of months since January, in the range `0'
+-          through `11'.
+-
+-    `int tm_year'
+-          This is the number of years since `1900'.
+-
+-    `int tm_wday'
+-          This is the number of days since Sunday, in the range `0'
+-          through `6'.
+-
+-    `int tm_yday'
+-          This is the number of days since January 1, in the range `0'
+-          through `365'.
+-
+-    `int tm_isdst'
+-          This is a flag that indicates whether Daylight Saving Time is
+-          (or was, or will be) in effect at the time described.  The
+-          value is positive if Daylight Saving Time is in effect, zero
+-          if it is not, and negative if the information is not
+-          available.
+-
+-    `long int tm_gmtoff'
+-          This field describes the time zone that was used to compute
+-          this broken-down time value, including any adjustment for
+-          daylight saving; it is the number of seconds that you must
+-          add to UTC to get local time.  You can also think of this as
+-          the number of seconds east of UTC.  For example, for U.S.
+-          Eastern Standard Time, the value is `-5*60*60'.  The
+-          `tm_gmtoff' field is derived from BSD and is a GNU library
+-          extension; it is not visible in a strict ISO C environment.
+-
+-    `const char *tm_zone'
+-          This field is the name for the time zone that was used to
+-          compute this broken-down time value.  Like `tm_gmtoff', this
+-          field is a BSD and GNU extension, and is not visible in a
+-          strict ISO C environment.
+-
+- - Function: struct tm * localtime (const time_t *TIME)
+-     The `localtime' function converts the calendar time pointed to by
+-     TIME to broken-down time representation, expressed relative to the
+-     user's specified time zone.
+-
+-     The return value is a pointer to a static broken-down time
+-     structure, which might be overwritten by subsequent calls to
+-     `ctime', `gmtime', or `localtime'.  (But no other library function
+-     overwrites the contents of this object.)
+-
+-     Calling `localtime' has one other effect: it sets the variable
+-     `tzname' with information about the current time zone.  *Note Time
+-     Zone Functions::.
+-
+- - Function: struct tm * gmtime (const time_t *TIME)
+-     This function is similar to `localtime', except that the
+-     broken-down time is expressed as Coordinated Universal Time
+-     (UTC)--that is, as Greenwich Mean Time (GMT)--rather than relative
+-     to the local time zone.
+-
+-     Recall that calendar times are *always* expressed in coordinated
+-     universal time.
+-
+- - Function: time_t mktime (struct tm *BROKENTIME)
+-     The `mktime' function is used to convert a broken-down time
+-     structure to a calendar time representation.  It also "normalizes"
+-     the contents of the broken-down time structure, by filling in the
+-     day of week and day of year based on the other date and time
+-     components.
+-
+-     The `mktime' function ignores the specified contents of the
+-     `tm_wday' and `tm_yday' members of the broken-down time structure.
+-     It uses the values of the other components to compute the
+-     calendar time; it's permissible for these components to have
+-     unnormalized values outside of their normal ranges.  The last
+-     thing that `mktime' does is adjust the components of the BROKENTIME
+-     structure (including the `tm_wday' and `tm_yday').
+-
+-     If the specified broken-down time cannot be represented as a
+-     calendar time, `mktime' returns a value of `(time_t)(-1)' and does
+-     not modify the contents of BROKENTIME.
+-
+-     Calling `mktime' also sets the variable `tzname' with information
+-     about the current time zone.  *Note Time Zone Functions::.
+-
+-
+-File: libc.info,  Node: Formatting Date and Time,  Next: TZ Variable,  Prev: 
Broken-down Time,  Up: Calendar Time
+-
+-Formatting Date and Time
+-------------------------
+-
+-   The functions described in this section format time values as
+-strings.  These functions are declared in the header file `time.h'.
+-
+- - Function: char * asctime (const struct tm *BROKENTIME)
+-     The `asctime' function converts the broken-down time value that
+-     BROKENTIME points to into a string in a standard format:
+-
+-          "Tue May 21 13:46:22 1991\n"
+-
+-     The abbreviations for the days of week are: `Sun', `Mon', `Tue',
+-     `Wed', `Thu', `Fri', and `Sat'.
+-
+-     The abbreviations for the months are: `Jan', `Feb', `Mar', `Apr',
+-     `May', `Jun', `Jul', `Aug', `Sep', `Oct', `Nov', and `Dec'.
+-
+-     The return value points to a statically allocated string, which
+-     might be overwritten by subsequent calls to `asctime' or `ctime'.
+-     (But no other library function overwrites the contents of this
+-     string.)
+-
+- - Function: char * ctime (const time_t *TIME)
+-     The `ctime' function is similar to `asctime', except that the time
+-     value is specified as a `time_t' calendar time value rather than
+-     in broken-down local time format.  It is equivalent to
+-
+-          asctime (localtime (TIME))
+-
+-     `ctime' sets the variable `tzname', because `localtime' does so.
+-     *Note Time Zone Functions::.
+-
+- - Function: size_t strftime (char *S, size_t SIZE, const char
+-          *TEMPLATE, const struct tm *BROKENTIME)
+-     This function is similar to the `sprintf' function (*note
+-     Formatted Input::.), but the conversion specifications that can
+-     appear in the format template TEMPLATE are specialized for
+-     printing components of the date and time BROKENTIME according to
+-     the locale currently specified for time conversion (*note
+-     Locales::.).
+-
+-     Ordinary characters appearing in the TEMPLATE are copied to the
+-     output string S; this can include multibyte character sequences.
+-     Conversion specifiers are introduced by a `%' character, followed
+-     by an optional flag which can be one of the following.  These
+-     flags, which are GNU extensions, affect only the output of numbers:
+-
+-    `_'
+-          The number is padded with spaces.
+-
+-    `-'
+-          The number is not padded at all.
+-
+-    `0'
+-          The number is padded with zeros even if the format specifies
+-          padding with spaces.
+-
+-    `^'
+-          The output uses uppercase characters, but only if this is
+-          possible (*note Case Conversion::.).
+-
+-     The default action is to pad the number with zeros to keep it a
+-     constant width.  Numbers that do not have a range indicated below
+-     are never padded, since there is no natural width for them.
+-
+-     Following the flag an optional specification of the width is
+-     possible.  This is specified in decimal notation.  If the natural
+-     size of the output is of the field has less than the specified
+-     number of characters, the result is written right adjusted and
+-     space padded to the given size.
+-
+-     An optional modifier can follow the optional flag and width
+-     specification.  The modifiers, which are POSIX.2 extensions, are:
+-
+-    `E'
+-          Use the locale's alternate representation for date and time.
+-          This modifier applies to the `%c', `%C', `%x', `%X', `%y' and
+-          `%Y' format specifiers.  In a Japanese locale, for example,
+-          `%Ex' might yield a date format based on the Japanese
+-          Emperors' reigns.
+-
+-    `O'
+-          Use the locale's alternate numeric symbols for numbers.  This
+-          modifier applies only to numeric format specifiers.
+-
+-     If the format supports the modifier but no alternate representation
+-     is available, it is ignored.
+-
+-     The conversion specifier ends with a format specifier taken from
+-     the following list.  The whole `%' sequence is replaced in the
+-     output string as follows:
+-
+-    `%a'
+-          The abbreviated weekday name according to the current locale.
+-
+-    `%A'
+-          The full weekday name according to the current locale.
+-
+-    `%b'
+-          The abbreviated month name according to the current locale.
+-
+-    `%B'
+-          The full month name according to the current locale.
+-
+-    `%c'
+-          The preferred date and time representation for the current
+-          locale.
+-
+-    `%C'
+-          The century of the year.  This is equivalent to the greatest
+-          integer not greater than the year divided by 100.
+-
+-          This format is a POSIX.2 extension.
+-
+-    `%d'
+-          The day of the month as a decimal number (range `01' through
+-          `31').
+-
+-    `%D'
+-          The date using the format `%m/%d/%y'.
+-
+-          This format is a POSIX.2 extension.
+-
+-    `%e'
+-          The day of the month like with `%d', but padded with blank
+-          (range ` 1' through `31').
+-
+-          This format is a POSIX.2 extension.
+-
+-    `%g'
+-          The year corresponding to the ISO week number, but without
+-          the century (range `00' through `99').  This has the same
+-          format and value as `%y', except that if the ISO week number
+-          (see `%V') belongs to the previous or next year, that year is
+-          used instead.
+-
+-          This format is a GNU extension.
+-
+-    `%G'
+-          The year corresponding to the ISO week number.  This has the
+-          same format and value as `%Y', except that if the ISO week
+-          number (see `%V') belongs to the previous or next year, that
+-          year is used instead.
+-
+-          This format is a GNU extension.
+-
+-    `%h'
+-          The abbreviated month name according to the current locale.
+-          The action is the same as for `%b'.
+-
+-          This format is a POSIX.2 extension.
+-
+-    `%H'
+-          The hour as a decimal number, using a 24-hour clock (range
+-          `00' through `23').
+-
+-    `%I'
+-          The hour as a decimal number, using a 12-hour clock (range
+-          `01' through `12').
+-
+-    `%j'
+-          The day of the year as a decimal number (range `001' through
+-          `366').
+-
+-    `%k'
+-          The hour as a decimal number, using a 24-hour clock like
+-          `%H', but padded with blank (range ` 0' through `23').
+-
+-          This format is a GNU extension.
+-
+-    `%l'
+-          The hour as a decimal number, using a 12-hour clock like
+-          `%I', but padded with blank (range ` 1' through `12').
+-
+-          This format is a GNU extension.
+-
+-    `%m'
+-          The month as a decimal number (range `01' through `12').
+-
+-    `%M'
+-          The minute as a decimal number (range `00' through `59').
+-
+-    `%n'
+-          A single `\n' (newline) character.
+-
+-          This format is a POSIX.2 extension.
+-
+-    `%p'
+-          Either `AM' or `PM', according to the given time value; or the
+-          corresponding strings for the current locale.  Noon is
+-          treated as `PM' and midnight as `AM'.
+-
+-    `%P'
+-          Either `am' or `pm', according to the given time value; or the
+-          corresponding strings for the current locale, printed in
+-          lowercase characters.  Noon is treated as `pm' and midnight
+-          as `am'.
+-
+-          This format is a GNU extension.
+-
+-    `%r'
+-          The complete time using the AM/PM format of the current
+-          locale.
+-
+-          This format is a POSIX.2 extension.
+-
+-    `%R'
+-          The hour and minute in decimal numbers using the format
+-          `%H:%M'.
+-
+-          This format is a GNU extension.
+-
+-    `%s'
+-          The number of seconds since the epoch, i.e., since 1970-01-01
+-          00:00:00 UTC.  Leap seconds are not counted unless leap
+-          second support is available.
+-
+-          This format is a GNU extension.
+-
+-    `%S'
+-          The second as a decimal number (range `00' through `60').
+-
+-    `%t'
+-          A single `\t' (tabulator) character.
+-
+-          This format is a POSIX.2 extension.
+-
+-    `%T'
+-          The time using decimal numbers using the format `%H:%M:%S'.
+-
+-          This format is a POSIX.2 extension.
+-
+-    `%u'
+-          The day of the week as a decimal number (range `1' through
+-          `7'), Monday being `1'.
+-
+-          This format is a POSIX.2 extension.
+-
+-    `%U'
+-          The week number of the current year as a decimal number
+-          (range `00' through `53'), starting with the first Sunday as
+-          the first day of the first week.  Days preceding the first
+-          Sunday in the year are considered to be in week `00'.
+-
+-    `%V'
+-          The ISO 8601:1988 week number as a decimal number (range `01'
+-          through `53').  ISO weeks start with Monday and end with
+-          Sunday.  Week `01' of a year is the first week which has the
+-          majority of its days in that year; this is equivalent to the
+-          week containing the year's first Thursday, and it is also
+-          equivalent to the week containing January 4.  Week `01' of a
+-          year can contain days from the previous year.  The week
+-          before week `01' of a year is the last week (`52' or `53') of
+-          the previous year even if it contains days from the new year.
+-
+-          This format is a POSIX.2 extension.
+-
+-    `%w'
+-          The day of the week as a decimal number (range `0' through
+-          `6'), Sunday being `0'.
+-
+-    `%W'
+-          The week number of the current year as a decimal number
+-          (range `00' through `53'), starting with the first Monday as
+-          the first day of the first week.  All days preceding the
+-          first Monday in the year are considered to be in week `00'.
+-
+-    `%x'
+-          The preferred date representation for the current locale, but
+-          without the time.
+-
+-    `%X'
+-          The preferred time representation for the current locale, but
+-          with no date.
+-
+-    `%y'
+-          The year without a century as a decimal number (range `00'
+-          through `99').  This is equivalent to the year modulo 100.
+-
+-    `%Y'
+-          The year as a decimal number, using the Gregorian calendar.
+-          Years before the year `1' are numbered `0', `-1', and so on.
+-
+-    `%z'
+-          RFC 822/ISO 8601:1988 style numeric time zone (e.g., `-0600'
+-          or `+0100'), or nothing if no time zone is determinable.
+-
+-          This format is a GNU extension.
+-
+-    `%Z'
+-          The time zone abbreviation (empty if the time zone can't be
+-          determined).
+-
+-    `%%'
+-          A literal `%' character.
+-
+-     The SIZE parameter can be used to specify the maximum number of
+-     characters to be stored in the array S, including the terminating
+-     null character.  If the formatted time requires more than SIZE
+-     characters, the excess characters are discarded.  The return value
+-     from `strftime' is the number of characters placed in the array S,
+-     not including the terminating null character.  If the value equals
+-     SIZE, it means that the array S was too small; you should repeat
+-     the call, providing a bigger array.
+-
+-     If S is a null pointer, `strftime' does not actually write
+-     anything, but instead returns the number of characters it would
+-     have written.
+-
+-     According to POSIX.1 every call to `strftime' implies a call to
+-     `tzset'.  So the contents of the environment variable `TZ' is
+-     examined before any output is produced.
+-
+-     For an example of `strftime', see *Note Time Functions Example::.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-18 
glibc-2.0.1/manual/libc.info-18
+--- ../glibc-2.0.1/manual/libc.info-18 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-18    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1165 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: TZ Variable,  Next: Time Zone Functions,  Prev: 
Formatting Date and Time,  Up: Calendar Time
+-
+-Specifying the Time Zone with `TZ'
+-----------------------------------
+-
+-   In POSIX systems, a user can specify the time zone by means of the
+-`TZ' environment variable.  For information about how to set
+-environment variables, see *Note Environment Variables::.  The functions
+-for accessing the time zone are declared in `time.h'.
+-
+-   You should not normally need to set `TZ'.  If the system is
+-configured properly, the default time zone will be correct.  You might
+-set `TZ' if you are using a computer over the network from a different
+-time zone, and would like times reported to you in the time zone that
+-local for you, rather than what is local for the computer.
+-
+-   In POSIX.1 systems the value of the `TZ' variable can be of one of
+-three formats.  With the GNU C library, the most common format is the
+-last one, which can specify a selection from a large database of time
+-zone information for many regions of the world.  The first two formats
+-are used to describe the time zone information directly, which is both
+-more cumbersome and less precise.  But the POSIX.1 standard only
+-specifies the details of the first two formats, so it is good to be
+-familiar with them in case you come across a POSIX.1 system that doesn't
+-support a time zone information database.
+-
+-   The first format is used when there is no Daylight Saving Time (or
+-summer time) in the local time zone:
+-
+-     STD OFFSET
+-
+-   The STD string specifies the name of the time zone.  It must be
+-three or more characters long and must not contain a leading colon or
+-embedded digits, commas, or plus or minus signs.  There is no space
+-character separating the time zone name from the OFFSET, so these
+-restrictions are necessary to parse the specification correctly.
+-
+-   The OFFSET specifies the time value one must add to the local time
+-to get a Coordinated Universal Time value.  It has syntax like
+-[`+'|`-']HH[`:'MM[`:'SS]].  This is positive if the local time zone is
+-west of the Prime Meridian and negative if it is east.  The hour must
+-be between `0' and `23', and the minute and seconds between `0' and
+-`59'.
+-
+-   For example, here is how we would specify Eastern Standard Time, but
+-without any daylight saving time alternative:
+-
+-     EST+5
+-
+-   The second format is used when there is Daylight Saving Time:
+-
+-     STD OFFSET DST [OFFSET]`,'START[`/'TIME]`,'END[`/'TIME]
+-
+-   The initial STD and OFFSET specify the standard time zone, as
+-described above.  The DST string and OFFSET specify the name and offset
+-for the corresponding daylight saving time time zone; if the OFFSET is
+-omitted, it defaults to one hour ahead of standard time.
+-
+-   The remainder of the specification describes when daylight saving
+-time is in effect.  The START field is when daylight saving time goes
+-into effect and the END field is when the change is made back to
+-standard time.  The following formats are recognized for these fields:
+-
+-`JN'
+-     This specifies the Julian day, with N between `1' and `365'.
+-     February 29 is never counted, even in leap years.
+-
+-`N'
+-     This specifies the Julian day, with N between `0' and `365'.
+-     February 29 is counted in leap years.
+-
+-`MM.W.D'
+-     This specifies day D of week W of month M.  The day D must be
+-     between `0' (Sunday) and `6'.  The week W must be between `1' and
+-     `5'; week `1' is the first week in which day D occurs, and week
+-     `5' specifies the *last* D day in the month.  The month M should be
+-     between `1' and `12'.
+-
+-   The TIME fields specify when, in the local time currently in effect,
+-the change to the other time occurs.  If omitted, the default is
+-`02:00:00'.
+-
+-   For example, here is how one would specify the Eastern time zone in
+-the United States, including the appropriate daylight saving time and
+-its dates of applicability.  The normal offset from UTC is 5 hours;
+-since this is west of the prime meridian, the sign is positive.  Summer
+-time begins on the first Sunday in April at 2:00am, and ends on the
+-last Sunday in October at 2:00am.
+-
+-     EST+5EDT,M4.1.0/2,M10.5.0/2
+-
+-   The schedule of daylight saving time in any particular jurisdiction
+-has changed over the years.  To be strictly correct, the conversion of
+-dates and times in the past should be based on the schedule that was in
+-effect then.  However, this format has no facilities to let you specify
+-how the schedule has changed from year to year.  The most you can do is
+-specify one particular schedule--usually the present day schedule--and
+-this is used to convert any date, no matter when.  For precise time zone
+-specifications, it is best to use the time zone information database
+-(see below).
+-
+-   The third format looks like this:
+-
+-     :CHARACTERS
+-
+-   Each operating system interprets this format differently; in the GNU
+-C library, CHARACTERS is the name of a file which describes the time
+-zone.
+-
+-   If the `TZ' environment variable does not have a value, the
+-operation chooses a time zone by default.  In the GNU C library, the
+-default time zone is like the specification `TZ=:/etc/localtime' (or
+-`TZ=:/usr/local/etc/localtime', depending on how GNU C library was
+-configured; *note Installation::.).  Other C libraries use their own
+-rule for choosing the default time zone, so there is little we can say
+-about them.
+-
+-   If CHARACTERS begins with a slash, it is an absolute file name;
+-otherwise the library looks for the file
+-`/share/lib/zoneinfo/CHARACTERS'.  The `zoneinfo' directory contains
+-data files describing local time zones in many different parts of the
+-world.  The names represent major cities, with subdirectories for
+-geographical areas; for example, `America/New_York', `Europe/London',
+-`Asia/Hong_Kong'.  These data files are installed by the system
+-administrator, who also sets `/etc/localtime' to point to the data file
+-for the local time zone.  The GNU C library comes with a large database
+-of time zone information for most regions of the world, which is
+-maintained by a community of volunteers and put in the public domain.
+-
+-
+-File: libc.info,  Node: Time Zone Functions,  Next: Time Functions Example,  
Prev: TZ Variable,  Up: Calendar Time
+-
+-Functions and Variables for Time Zones
+---------------------------------------
+-
+- - Variable: char * tzname
+-     The array `tzname' contains two strings, which are the standard
+-     names of the pair of time zones (standard and daylight saving)
+-     that the user has selected.  `tzname[0]' is the name of the
+-     standard time zone (for example, `"EST"'), and `tzname[1]' is the
+-     name for the time zone when daylight saving time is in use (for
+-     example, `"EDT"').  These correspond to the STD and DST strings
+-     (respectively) from the `TZ' environment variable.  If daylight
+-     saving time is never used, `tzname[1]' is the empty string.
+-
+-     The `tzname' array is initialized from the `TZ' environment
+-     variable whenever `tzset', `ctime', `strftime', `mktime', or
+-     `localtime' is called.  If multiple abbreviations have been used
+-     (e.g. `"EWT"' and `"EDT"' for U.S. Eastern War Time and Eastern
+-     Daylight Time), the array contains the most recent abbreviation.
+-
+-     The `tzname' array is required for POSIX.1 compatibility, but in
+-     GNU programs it is better to use the `tm_zone' member of the
+-     broken-down time structure, since `tm_zone' reports the correct
+-     abbreviation even when it is not the latest one.
+-
+-
+- - Function: void tzset (void)
+-     The `tzset' function initializes the `tzname' variable from the
+-     value of the `TZ' environment variable.  It is not usually
+-     necessary for your program to call this function, because it is
+-     called automatically when you use the other time conversion
+-     functions that depend on the time zone.
+-
+-   The following variables are defined for compatibility with System V
+-Unix.  Like `tzname', these variables are set by calling `tzset' or the
+-other time conversion functions.
+-
+- - Variable: long int timezone
+-     This contains the difference between UTC and the latest local
+-     standard time, in seconds west of UTC.  For example, in the U.S.
+-     Eastern time zone, the value is `5*60*60'.  Unlike the `tm_gmtoff'
+-     member of the broken-down time structure, this value is not
+-     adjusted for daylight saving, and its sign is reversed.  In GNU
+-     programs it is better to use `tm_gmtoff', since it contains the
+-     correct offset even when it is not the latest one.
+-
+- - Variable: int daylight
+-     This variable has a nonzero value if daylight savings time rules
+-     apply.  A nonzero value does not necessarily mean that daylight
+-     savings time is now in effect; it means only that daylight savings
+-     time is sometimes in effect.
+-
+-
+-File: libc.info,  Node: Time Functions Example,  Prev: Time Zone Functions,  
Up: Calendar Time
+-
+-Time Functions Example
+-----------------------
+-
+-   Here is an example program showing the use of some of the local time
+-and calendar time functions.
+-
+-     #include <time.h>
+-     #include <stdio.h>
+-     
+-     #define SIZE 256
+-     
+-     int
+-     main (void)
+-     {
+-       char buffer[SIZE];
+-       time_t curtime;
+-       struct tm *loctime;
+-     
+-       /* Get the current time. */
+-       curtime = time (NULL);
+-     
+-       /* Convert it to local time representation. */
+-       loctime = localtime (&curtime);
+-     
+-       /* Print out the date and time in the standard format. */
+-       fputs (asctime (loctime), stdout);
+-     /* Print it out in a nice format. */
+-       strftime (buffer, SIZE, "Today is %A, %B %d.\n", loctime);
+-       fputs (buffer, stdout);
+-       strftime (buffer, SIZE, "The time is %I:%M %p.\n", loctime);
+-       fputs (buffer, stdout);
+-     
+-       return 0;
+-     }
+-
+-   It produces output like this:
+-
+-     Wed Jul 31 13:02:36 1991
+-     Today is Wednesday, July 31.
+-     The time is 01:02 PM.
+-
+-
+-File: libc.info,  Node: Setting an Alarm,  Next: Sleeping,  Prev: Calendar 
Time,  Up: Date and Time
+-
+-Setting an Alarm
+-================
+-
+-   The `alarm' and `setitimer' functions provide a mechanism for a
+-process to interrupt itself at some future time.  They do this by
+-setting a timer; when the timer expires, the process receives a signal.
+-
+-   Each process has three independent interval timers available:
+-
+-   * A real-time timer that counts clock time.  This timer sends a
+-     `SIGALRM' signal to the process when it expires.
+-
+-   * A virtual timer that counts CPU time used by the process.  This
+-     timer sends a `SIGVTALRM' signal to the process when it expires.
+-
+-   * A profiling timer that counts both CPU time used by the process,
+-     and CPU time spent in system calls on behalf of the process.  This
+-     timer sends a `SIGPROF' signal to the process when it expires.
+-
+-     This timer is useful for profiling in interpreters.  The interval
+-     timer mechanism does not have the fine granularity necessary for
+-     profiling native code.
+-
+-   You can only have one timer of each kind set at any given time.  If
+-you set a timer that has not yet expired, that timer is simply reset to
+-the new value.
+-
+-   You should establish a handler for the appropriate alarm signal using
+-`signal' or `sigaction' before issuing a call to `setitimer' or
+-`alarm'.  Otherwise, an unusual chain of events could cause the timer
+-to expire before your program establishes the handler, and in that case
+-it would be terminated, since that is the default action for the alarm
+-signals.  *Note Signal Handling::.
+-
+-   The `setitimer' function is the primary means for setting an alarm.
+-This facility is declared in the header file `sys/time.h'.  The `alarm'
+-function, declared in `unistd.h', provides a somewhat simpler interface
+-for setting the real-time timer.
+-
+- - Data Type: struct itimerval
+-     This structure is used to specify when a timer should expire.  It
+-     contains the following members:
+-    `struct timeval it_interval'
+-          This is the interval between successive timer interrupts.  If
+-          zero, the alarm will only be sent once.
+-
+-    `struct timeval it_value'
+-          This is the interval to the first timer interrupt.  If zero,
+-          the alarm is disabled.
+-
+-     The `struct timeval' data type is described in *Note
+-     High-Resolution Calendar::.
+-
+- - Function: int setitimer (int WHICH, struct itimerval *NEW, struct
+-          itimerval *OLD)
+-     The `setitimer' function sets the timer specified by WHICH
+-     according to NEW.  The WHICH argument can have a value of
+-     `ITIMER_REAL', `ITIMER_VIRTUAL', or `ITIMER_PROF'.
+-
+-     If OLD is not a null pointer, `setitimer' returns information
+-     about any previous unexpired timer of the same kind in the
+-     structure it points to.
+-
+-     The return value is `0' on success and `-1' on failure.  The
+-     following `errno' error conditions are defined for this function:
+-
+-    `EINVAL'
+-          The timer interval was too large.
+-
+- - Function: int getitimer (int WHICH, struct itimerval *OLD)
+-     The `getitimer' function stores information about the timer
+-     specified by WHICH in the structure pointed at by OLD.
+-
+-     The return value and error conditions are the same as for
+-     `setitimer'.
+-
+-`ITIMER_REAL'
+-     This constant can be used as the WHICH argument to the `setitimer'
+-     and `getitimer' functions to specify the real-time timer.
+-
+-`ITIMER_VIRTUAL'
+-     This constant can be used as the WHICH argument to the `setitimer'
+-     and `getitimer' functions to specify the virtual timer.
+-
+-`ITIMER_PROF'
+-     This constant can be used as the WHICH argument to the `setitimer'
+-     and `getitimer' functions to specify the profiling timer.
+-
+- - Function: unsigned int alarm (unsigned int SECONDS)
+-     The `alarm' function sets the real-time timer to expire in SECONDS
+-     seconds.  If you want to cancel any existing alarm, you can do
+-     this by calling `alarm' with a SECONDS argument of zero.
+-
+-     The return value indicates how many seconds remain before the
+-     previous alarm would have been sent.  If there is no previous
+-     alarm, `alarm' returns zero.
+-
+-   The `alarm' function could be defined in terms of `setitimer' like
+-this:
+-
+-     unsigned int
+-     alarm (unsigned int seconds)
+-     {
+-       struct itimerval old, new;
+-       new.it_interval.tv_usec = 0;
+-       new.it_interval.tv_sec = 0;
+-       new.it_value.tv_usec = 0;
+-       new.it_value.tv_sec = (long int) seconds;
+-       if (setitimer (ITIMER_REAL, &new, &old) < 0)
+-         return 0;
+-       else
+-         return old.it_value.tv_sec;
+-     }
+-
+-   There is an example showing the use of the `alarm' function in *Note
+-Handler Returns::.
+-
+-   If you simply want your process to wait for a given number of
+-seconds, you should use the `sleep' function.  *Note Sleeping::.
+-
+-   You shouldn't count on the signal arriving precisely when the timer
+-expires.  In a multiprocessing environment there is typically some
+-amount of delay involved.
+-
+-   *Portability Note:* The `setitimer' and `getitimer' functions are
+-derived from BSD Unix, while the `alarm' function is specified by the
+-POSIX.1 standard.  `setitimer' is more powerful than `alarm', but
+-`alarm' is more widely used.
+-
+-
+-File: libc.info,  Node: Sleeping,  Next: Resource Usage,  Prev: Setting an 
Alarm,  Up: Date and Time
+-
+-Sleeping
+-========
+-
+-   The function `sleep' gives a simple way to make the program wait for
+-short periods of time.  If your program doesn't use signals (except to
+-terminate), then you can expect `sleep' to wait reliably for the
+-specified amount of time.  Otherwise, `sleep' can return sooner if a
+-signal arrives; if you want to wait for a given period regardless of
+-signals, use `select' (*note Waiting for I/O::.) and don't specify any
+-descriptors to wait for.
+-
+- - Function: unsigned int sleep (unsigned int SECONDS)
+-     The `sleep' function waits for SECONDS or until a signal is
+-     delivered, whichever happens first.
+-
+-     If `sleep' function returns because the requested time has
+-     elapsed, it returns a value of zero.  If it returns because of
+-     delivery of a signal, its return value is the remaining time in
+-     the sleep period.
+-
+-     The `sleep' function is declared in `unistd.h'.
+-
+-   Resist the temptation to implement a sleep for a fixed amount of
+-time by using the return value of `sleep', when nonzero, to call
+-`sleep' again.  This will work with a certain amount of accuracy as
+-long as signals arrive infrequently.  But each signal can cause the
+-eventual wakeup time to be off by an additional second or so.  Suppose a
+-few signals happen to arrive in rapid succession by bad luck--there is
+-no limit on how much this could shorten or lengthen the wait.
+-
+-   Instead, compute the time at which the program should stop waiting,
+-and keep trying to wait until that time.  This won't be off by more
+-than a second.  With just a little more work, you can use `select' and
+-make the waiting period quite accurate.  (Of course, heavy system load
+-can cause unavoidable additional delays--unless the machine is
+-dedicated to one application, there is no way you can avoid this.)
+-
+-   On some systems, `sleep' can do strange things if your program uses
+-`SIGALRM' explicitly.  Even if `SIGALRM' signals are being ignored or
+-blocked when `sleep' is called, `sleep' might return prematurely on
+-delivery of a `SIGALRM' signal.  If you have established a handler for
+-`SIGALRM' signals and a `SIGALRM' signal is delivered while the process
+-is sleeping, the action taken might be just to cause `sleep' to return
+-instead of invoking your handler.  And, if `sleep' is interrupted by
+-delivery of a signal whose handler requests an alarm or alters the
+-handling of `SIGALRM', this handler and `sleep' will interfere.
+-
+-   On the GNU system, it is safe to use `sleep' and `SIGALRM' in the
+-same program, because `sleep' does not work by means of `SIGALRM'.
+-
+-
+-File: libc.info,  Node: Resource Usage,  Next: Limits on Resources,  Prev: 
Sleeping,  Up: Date and Time
+-
+-Resource Usage
+-==============
+-
+-   The function `getrusage' and the data type `struct rusage' are used
+-for examining the usage figures of a process.  They are declared in
+-`sys/resource.h'.
+-
+- - Function: int getrusage (int PROCESSES, struct rusage *RUSAGE)
+-     This function reports the usage totals for processes specified by
+-     PROCESSES, storing the information in `*RUSAGE'.
+-
+-     In most systems, PROCESSES has only two valid values:
+-
+-    `RUSAGE_SELF'
+-          Just the current process.
+-
+-    `RUSAGE_CHILDREN'
+-          All child processes (direct and indirect) that have
+-          terminated already.
+-
+-     In the GNU system, you can also inquire about a particular child
+-     process by specifying its process ID.
+-
+-     The return value of `getrusage' is zero for success, and `-1' for
+-     failure.
+-
+-    `EINVAL'
+-          The argument PROCESSES is not valid.
+-
+-   One way of getting usage figures for a particular child process is
+-with the function `wait4', which returns totals for a child when it
+-terminates.  *Note BSD Wait Functions::.
+-
+- - Data Type: struct rusage
+-     This data type records a collection usage amounts for various
+-     sorts of resources.  It has the following members, and possibly
+-     others:
+-
+-    `struct timeval ru_utime'
+-          Time spent executing user instructions.
+-
+-    `struct timeval ru_stime'
+-          Time spent in operating system code on behalf of PROCESSES.
+-
+-    `long int ru_maxrss'
+-          The maximum resident set size used, in kilobytes.  That is,
+-          the maximum number of kilobytes that PROCESSES used in real
+-          memory simultaneously.
+-
+-    `long int ru_ixrss'
+-          An integral value expressed in kilobytes times ticks of
+-          execution, which indicates the amount of memory used by text
+-          that was shared with other processes.
+-
+-    `long int ru_idrss'
+-          An integral value expressed the same way, which is the amount
+-          of unshared memory used in data.
+-
+-    `long int ru_isrss'
+-          An integral value expressed the same way, which is the amount
+-          of unshared memory used in stack space.
+-
+-    `long int ru_minflt'
+-          The number of page faults which were serviced without
+-          requiring any I/O.
+-
+-    `long int ru_majflt'
+-          The number of page faults which were serviced by doing I/O.
+-
+-    `long int ru_nswap'
+-          The number of times PROCESSES was swapped entirely out of
+-          main memory.
+-
+-    `long int ru_inblock'
+-          The number of times the file system had to read from the disk
+-          on behalf of PROCESSES.
+-
+-    `long int ru_oublock'
+-          The number of times the file system had to write to the disk
+-          on behalf of PROCESSES.
+-
+-    `long int ru_msgsnd'
+-          Number of IPC messages sent.
+-
+-    `long ru_msgrcv'
+-          Number of IPC messages received.
+-
+-    `long int ru_nsignals'
+-          Number of signals received.
+-
+-    `long int ru_nvcsw'
+-          The number of times PROCESSES voluntarily invoked a context
+-          switch (usually to wait for some service).
+-
+-    `long int ru_nivcsw'
+-          The number of times an involuntary context switch took place
+-          (because the time slice expired, or another process of higher
+-          priority became runnable).
+-
+-   An additional historical function for examining usage figures,
+-`vtimes', is supported but not documented here.  It is declared in
+-`sys/vtimes.h'.
+-
+-
+-File: libc.info,  Node: Limits on Resources,  Next: Priority,  Prev: Resource 
Usage,  Up: Date and Time
+-
+-Limiting Resource Usage
+-=======================
+-
+-   You can specify limits for the resource usage of a process.  When the
+-process tries to exceed a limit, it may get a signal, or the system call
+-by which it tried to do so may fail, depending on the limit.  Each
+-process initially inherits its limit values from its parent, but it can
+-subsequently change them.
+-
+-   The symbols in this section are defined in `sys/resource.h'.
+-
+- - Function: int getrlimit (int RESOURCE, struct rlimit *RLP)
+-     Read the current value and the maximum value of resource RESOURCE
+-     and store them in `*RLP'.
+-
+-     The return value is `0' on success and `-1' on failure.  The only
+-     possible `errno' error condition is `EFAULT'.
+-
+- - Function: int setrlimit (int RESOURCE, struct rlimit *RLP)
+-     Store the current value and the maximum value of resource RESOURCE
+-     in `*RLP'.
+-
+-     The return value is `0' on success and `-1' on failure.  The
+-     following `errno' error condition is possible:
+-
+-    `EPERM'
+-          You tried to change the maximum permissible limit value, but
+-          you don't have privileges to do so.
+-
+- - Data Type: struct rlimit
+-     This structure is used with `getrlimit' to receive limit values,
+-     and with `setrlimit' to specify limit values.  It has two fields:
+-
+-    `rlim_cur'
+-          The current value of the limit in question.  This is also
+-          called the "soft limit".
+-
+-    `rlim_max'
+-          The maximum permissible value of the limit in question.  You
+-          cannot set the current value of the limit to a larger number
+-          than this maximum.  Only the super user can change the
+-          maximum permissible value.  This is also called the "hard
+-          limit".
+-
+-     In `getrlimit', the structure is an output; it receives the current
+-     values.  In `setrlimit', it specifies the new values.
+-
+-   Here is a list of resources that you can specify a limit for.  Those
+-that are sizes are measured in bytes.
+-
+-`RLIMIT_CPU'
+-     The maximum amount of cpu time the process can use.  If it runs for
+-     longer than this, it gets a signal: `SIGXCPU'.  The value is
+-     measured in seconds.  *Note Operation Error Signals::.
+-
+-`RLIMIT_FSIZE'
+-     The maximum size of file the process can create.  Trying to write a
+-     larger file causes a signal: `SIGXFSZ'.  *Note Operation Error
+-     Signals::.
+-
+-`RLIMIT_DATA'
+-     The maximum size of data memory for the process.  If the process
+-     tries to allocate data memory beyond this amount, the allocation
+-     function fails.
+-
+-`RLIMIT_STACK'
+-     The maximum stack size for the process.  If the process tries to
+-     extend its stack past this size, it gets a `SIGSEGV' signal.
+-     *Note Program Error Signals::.
+-
+-`RLIMIT_CORE'
+-     The maximum size core file that this process can create.  If the
+-     process terminates and would dump a core file larger than this
+-     maximum size, then no core file is created.  So setting this limit
+-     to zero prevents core files from ever being created.
+-
+-`RLIMIT_RSS'
+-     The maximum amount of physical memory that this process should get.
+-     This parameter is a guide for the system's scheduler and memory
+-     allocator; the system may give the process more memory when there
+-     is a surplus.
+-
+-`RLIMIT_MEMLOCK'
+-     The maximum amount of memory that can be locked into physical
+-     memory (so it will never be paged out).
+-
+-`RLIMIT_NPROC'
+-     The maximum number of processes that can be created with the same
+-     user ID.  If you have reached the limit for your user ID, `fork'
+-     will fail with `EAGAIN'.  *Note Creating a Process::.
+-
+-`RLIMIT_NOFILE'
+-`RLIMIT_OFILE'
+-     The maximum number of files that the process can open.  If it
+-     tries to open more files than this, it gets error code `EMFILE'.
+-     *Note Error Codes::.  Not all systems support this limit; GNU
+-     does, and 4.4 BSD does.
+-
+-`RLIM_NLIMITS'
+-     The number of different resource limits.  Any valid RESOURCE
+-     operand must be less than `RLIM_NLIMITS'.
+-
+- - Constant: int
+-     This constant stands for a value of "infinity" when supplied as
+-     the limit value in `setrlimit'.
+-
+-   Two historical functions for setting resource limits, `ulimit' and
+-`vlimit', are not documented here.  The latter is declared in
+-`sys/vlimit.h' and comes from BSD.
+-
+-
+-File: libc.info,  Node: Priority,  Prev: Limits on Resources,  Up: Date and 
Time
+-
+-Process Priority
+-================
+-
+-   When several processes try to run, their respective priorities
+-determine what share of the CPU each process gets.  This section
+-describes how you can read and set the priority of a process.  All
+-these functions and macros are declared in `sys/resource.h'.
+-
+-   The range of valid priority values depends on the operating system,
+-but typically it runs from `-20' to `20'.  A lower priority value means
+-the process runs more often.  These constants describe the range of
+-priority values:
+-
+-`PRIO_MIN'
+-     The smallest valid priority value.
+-
+-`PRIO_MAX'
+-     The smallest valid priority value.
+-
+- - Function: int getpriority (int CLASS, int ID)
+-     Read the priority of a class of processes; CLASS and ID specify
+-     which ones (see below).  If the processes specified do not all
+-     have the same priority, this returns the smallest value that any
+-     of them has.
+-
+-     The return value is the priority value on success, and `-1' on
+-     failure.  The following `errno' error condition are possible for
+-     this function:
+-
+-    `ESRCH'
+-          The combination of CLASS and ID does not match any existing
+-          process.
+-
+-    `EINVAL'
+-          The value of CLASS is not valid.
+-
+-     When the return value is `-1', it could indicate failure, or it
+-     could be the priority value.  The only way to make certain is to
+-     set `errno = 0' before calling `getpriority', then use `errno !=
+-     0' afterward as the criterion for failure.
+-
+- - Function: int setpriority (int CLASS, int ID, int PRIORITY)
+-     Set the priority of a class of processes to PRIORITY; CLASS and ID
+-     specify which ones (see below).
+-
+-     The return value is `0' on success and `-1' on failure.  The
+-     following `errno' error condition are defined for this function:
+-
+-    `ESRCH'
+-          The combination of CLASS and ID does not match any existing
+-          process.
+-
+-    `EINVAL'
+-          The value of CLASS is not valid.
+-
+-    `EPERM'
+-          You tried to set the priority of some other user's process,
+-          and you don't have privileges for that.
+-
+-    `EACCES'
+-          You tried to lower the priority of a process, and you don't
+-          have privileges for that.
+-
+-   The arguments CLASS and ID together specify a set of processes you
+-are interested in.  These are the possible values for CLASS:
+-
+-`PRIO_PROCESS'
+-     Read or set the priority of one process.  The argument ID is a
+-     process ID.
+-
+-`PRIO_PGRP'
+-     Read or set the priority of one process group.  The argument ID is
+-     a process group ID.
+-
+-`PRIO_USER'
+-     Read or set the priority of one user's processes.  The argument ID
+-     is a user ID.
+-
+-   If the argument ID is 0, it stands for the current process, current
+-process group, or the current user, according to CLASS.
+-
+- - Function: int nice (int INCREMENT)
+-     Increment the priority of the current process by INCREMENT.  The
+-     return value is the same as for `setpriority'.
+-
+-     Here is an equivalent definition for `nice':
+-
+-          int
+-          nice (int increment)
+-          {
+-            int old = getpriority (PRIO_PROCESS, 0);
+-            return setpriority (PRIO_PROCESS, 0, old + increment);
+-          }
+-
+-
+-File: libc.info,  Node: Extended Characters,  Next: Locales,  Prev: String 
and Array Utilities,  Up: Top
+-
+-Extended Characters
+-*******************
+-
+-   A number of languages use character sets that are larger than the
+-range of values of type `char'.  Japanese and Chinese are probably the
+-most familiar examples.
+-
+-   The GNU C library includes support for two mechanisms for dealing
+-with extended character sets: multibyte characters and wide characters.
+-This chapter describes how to use these mechanisms, and the functions
+-for converting between them.
+-
+-   The behavior of the functions in this chapter is affected by the
+-current locale for character classification--the `LC_CTYPE' category;
+-see *Note Locale Categories::.  This choice of locale selects which
+-multibyte code is used, and also controls the meanings and
+-characteristics of wide character codes.
+-
+-* Menu:
+-
+-* Extended Char Intro::         Multibyte codes versus wide characters.
+-* Locales and Extended Chars::  The locale selects the character codes.
+-* Multibyte Char Intro::        How multibyte codes are represented.
+-* Wide Char Intro::             How wide characters are represented.
+-* Wide String Conversion::      Converting wide strings to multibyte code
+-                                 and vice versa.
+-* Length of Char::              how many bytes make up one multibyte char.
+-* Converting One Char::         Converting a string character by character.
+-* Example of Conversion::       Example showing why converting
+-                               one character at a time may be useful.
+-* Shift State::                 Multibyte codes with "shift characters".
+-
+-
+-File: libc.info,  Node: Extended Char Intro,  Next: Locales and Extended 
Chars,  Up: Extended Characters
+-
+-Introduction to Extended Characters
+-===================================
+-
+-   You can represent extended characters in either of two ways:
+-
+-   * As "multibyte characters" which can be embedded in an ordinary
+-     string, an array of `char' objects.  Their advantage is that many
+-     programs and operating systems can handle occasional multibyte
+-     characters scattered among ordinary ASCII characters, without any
+-     change.
+-
+-   * As "wide characters", which are like ordinary characters except
+-     that they occupy more bits.  The wide character data type,
+-     `wchar_t', has a range large enough to hold extended character
+-     codes as well as old-fashioned ASCII codes.
+-
+-     An advantage of wide characters is that each character is a single
+-     data object, just like ordinary ASCII characters.  There are a few
+-     disadvantages:
+-
+-        * Each existing program must be modified and recompiled to make
+-          it use wide characters.
+-
+-        * Files of wide characters cannot be read by programs that
+-          expect ordinary characters.
+-
+-   Typically, you use the multibyte character representation as part of
+-the external program interface, such as reading or writing text to
+-files.  However, it's usually easier to perform internal manipulations
+-on strings containing extended characters on arrays of `wchar_t'
+-objects, since the uniform representation makes most editing operations
+-easier.  If you do use multibyte characters for files and wide
+-characters for internal operations, you need to convert between them
+-when you read and write data.
+-
+-   If your system supports extended characters, then it supports them
+-both as multibyte characters and as wide characters.  The library
+-includes functions you can use to convert between the two
+-representations.  These functions are described in this chapter.
+-
+-
+-File: libc.info,  Node: Locales and Extended Chars,  Next: Multibyte Char 
Intro,  Prev: Extended Char Intro,  Up: Extended Characters
+-
+-Locales and Extended Characters
+-===============================
+-
+-   A computer system can support more than one multibyte character code,
+-and more than one wide character code.  The user controls the choice of
+-codes through the current locale for character classification (*note
+-Locales::.).  Each locale specifies a particular multibyte character
+-code and a particular wide character code.  The choice of locale
+-influences the behavior of the conversion functions in the library.
+-
+-   Some locales support neither wide characters nor nontrivial multibyte
+-characters.  In these locales, the library conversion functions still
+-work, even though what they do is basically trivial.
+-
+-   If you select a new locale for character classification, the internal
+-shift state maintained by these functions can become confused, so it's
+-not a good idea to change the locale while you are in the middle of
+-processing a string.
+-
+-
+-File: libc.info,  Node: Multibyte Char Intro,  Next: Wide Char Intro,  Prev: 
Locales and Extended Chars,  Up: Extended Characters
+-
+-Multibyte Characters
+-====================
+-
+-   In the ordinary ASCII code, a sequence of characters is a sequence of
+-bytes, and each character is one byte.  This is very simple, but allows
+-for only 256 distinct characters.
+-
+-   In a "multibyte character code", a sequence of characters is a
+-sequence of bytes, but each character may occupy one or more consecutive
+-bytes of the sequence.
+-
+-   There are many different ways of designing a multibyte character
+-code; different systems use different codes.  To specify a particular
+-code means designating the "basic" byte sequences--those which represent
+-a single character--and what characters they stand for.  A code that a
+-computer can actually use must have a finite number of these basic
+-sequences, and typically none of them is more than a few characters
+-long.
+-
+-   These sequences need not all have the same length.  In fact, many of
+-them are just one byte long.  Because the basic ASCII characters in the
+-range from `0' to `0177' are so important, they stand for themselves in
+-all multibyte character codes.  That is to say, a byte whose value is
+-`0' through `0177' is always a character in itself.  The characters
+-which are more than one byte must always start with a byte in the range
+-from `0200' through `0377'.
+-
+-   The byte value `0' can be used to terminate a string, just as it is
+-often used in a string of ASCII characters.
+-
+-   Specifying the basic byte sequences that represent single characters
+-automatically gives meanings to many longer byte sequences, as more than
+-one character.  For example, if the two byte sequence `0205 049' stands
+-for the Greek letter alpha, then `0205 049 065' must stand for an alpha
+-followed by an `A' (ASCII code 065), and `0205 049 0205 049' must stand
+-for two alphas in a row.
+-
+-   If any byte sequence can have more than one meaning as a sequence of
+-characters, then the multibyte code is ambiguous--and no good.  The
+-codes that systems actually use are all unambiguous.
+-
+-   In most codes, there are certain sequences of bytes that have no
+-meaning as a character or characters.  These are called "invalid".
+-
+-   The simplest possible multibyte code is a trivial one:
+-
+-     The basic sequences consist of single bytes.
+-
+-   This particular code is equivalent to not using multibyte characters
+-at all.  It has no invalid sequences.  But it can handle only 256
+-different characters.
+-
+-   Here is another possible code which can handle 9376 different
+-characters:
+-
+-     The basic sequences consist of
+-
+-        * single bytes with values in the range `0' through `0237'.
+-
+-        * two-byte sequences, in which both of the bytes have values in
+-          the range from `0240' through `0377'.
+-
+-This code or a similar one is used on some systems to represent Japanese
+-characters.  The invalid sequences are those which consist of an odd
+-number of consecutive bytes in the range from `0240' through `0377'.
+-
+-   Here is another multibyte code which can handle more distinct
+-extended characters--in fact, almost thirty million:
+-
+-     The basic sequences consist of
+-
+-        * single bytes with values in the range `0' through `0177'.
+-
+-        * sequences of up to four bytes in which the first byte is in
+-          the range from `0200' through `0237', and the remaining bytes
+-          are in the range from `0240' through `0377'.
+-
+-In this code, any sequence that starts with a byte in the range from
+-`0240' through `0377' is invalid.
+-
+-   And here is another variant which has the advantage that removing the
+-last byte or bytes from a valid character can never produce another
+-valid character.  (This property is convenient when you want to search
+-strings for particular characters.)
+-
+-     The basic sequences consist of
+-
+-        * single bytes with values in the range `0' through `0177'.
+-
+-        * two-byte sequences in which the first byte is in the range
+-          from `0200' through `0207', and the second byte is in the
+-          range from `0240' through `0377'.
+-
+-        * three-byte sequences in which the first byte is in the range
+-          from `0210' through `0217', and the other bytes are in the
+-          range from `0240' through `0377'.
+-
+-        * four-byte sequences in which the first byte is in the range
+-          from `0220' through `0227', and the other bytes are in the
+-          range from `0240' through `0377'.
+-
+-The list of invalid sequences for this code is long and not worth
+-stating in full; examples of invalid sequences include `0240' and `0220
+-0300 065'.
+-
+-   The number of *possible* multibyte codes is astronomical.  But a
+-given computer system will support at most a few different codes.  (One
+-of these codes may allow for thousands of different characters.)
+-Another computer system may support a completely different code.  The
+-library facilities described in this chapter are helpful because they
+-package up the knowledge of the details of a particular computer
+-system's multibyte code, so your programs need not know them.
+-
+-   You can use special standard macros to find out the maximum possible
+-number of bytes in a character in the currently selected multibyte code
+-with `MB_CUR_MAX', and the maximum for *any* multibyte code supported
+-on your computer with `MB_LEN_MAX'.
+-
+- - Macro: int MB_LEN_MAX
+-     This is the maximum length of a multibyte character for any
+-     supported locale.  It is defined in `limits.h'.
+-
+- - Macro: int MB_CUR_MAX
+-     This macro expands into a (possibly non-constant) positive integer
+-     expression that is the maximum number of bytes in a multibyte
+-     character in the current locale.  The value is never greater than
+-     `MB_LEN_MAX'.
+-
+-     `MB_CUR_MAX' is defined in `stdlib.h'.
+-
+-   Normally, each basic sequence in a particular character code stands
+-for one character, the same character regardless of context.  Some
+-multibyte character codes have a concept of "shift state"; certain
+-codes, called "shift sequences", change to a different shift state, and
+-the meaning of some or all basic sequences varies according to the
+-current shift state.  In fact, the set of basic sequences might even be
+-different depending on the current shift state.  *Note Shift State::,
+-for more information on handling this sort of code.
+-
+-   What happens if you try to pass a string containing multibyte
+-characters to a function that doesn't know about them?  Normally, such
+-a function treats a string as a sequence of bytes, and interprets
+-certain byte values specially; all other byte values are "ordinary".
+-As long as a multibyte character doesn't contain any of the special
+-byte values, the function should pass it through as if it were several
+-ordinary characters.
+-
+-   For example, let's figure out what happens if you use multibyte
+-characters in a file name.  The functions such as `open' and `unlink'
+-that operate on file names treat the name as a sequence of byte values,
+-with `/' as the only special value.  Any other byte values are copied,
+-or compared, in sequence, and all byte values are treated alike.  Thus,
+-you may think of the file name as a sequence of bytes or as a string
+-containing multibyte characters; the same behavior makes sense equally
+-either way, provided no multibyte character contains a `/'.
+-
+-
+-File: libc.info,  Node: Wide Char Intro,  Next: Wide String Conversion,  
Prev: Multibyte Char Intro,  Up: Extended Characters
+-
+-Wide Character Introduction
+-===========================
+-
+-   "Wide characters" are much simpler than multibyte characters.  They
+-are simply characters with more than eight bits, so that they have room
+-for more than 256 distinct codes.  The wide character data type,
+-`wchar_t', has a range large enough to hold extended character codes as
+-well as old-fashioned ASCII codes.
+-
+-   An advantage of wide characters is that each character is a single
+-data object, just like ordinary ASCII characters.  Wide characters also
+-have some disadvantages:
+-
+-   * A program must be modified and recompiled in order to use wide
+-     characters at all.
+-
+-   * Files of wide characters cannot be read by programs that expect
+-     ordinary characters.
+-
+-   Wide character values `0' through `0177' are always identical in
+-meaning to the ASCII character codes.  The wide character value zero is
+-often used to terminate a string of wide characters, just as a single
+-byte with value zero often terminates a string of ordinary characters.
+-
+- - Data Type: wchar_t
+-     This is the "wide character" type, an integer type whose range is
+-     large enough to represent all distinct values in any extended
+-     character set in the supported locales.  *Note Locales::, for more
+-     information about locales.  This type is defined in the header
+-     file `stddef.h'.
+-
+-   If your system supports extended characters, then each extended
+-character has both a wide character code and a corresponding multibyte
+-basic sequence.
+-
+-   In this chapter, the term "code" is used to refer to a single
+-extended character object to emphasize the distinction from the `char'
+-data type.
+-
+-
+-File: libc.info,  Node: Wide String Conversion,  Next: Length of Char,  Prev: 
Wide Char Intro,  Up: Extended Characters
+-
+-Conversion of Extended Strings
+-==============================
+-
+-   The `mbstowcs' function converts a string of multibyte characters to
+-a wide character array.  The `wcstombs' function does the reverse.
+-These functions are declared in the header file `stdlib.h'.
+-
+-   In most programs, these functions are the only ones you need for
+-conversion between wide strings and multibyte character strings.  But
+-they have limitations.  If your data is not null-terminated or is not
+-all in core at once, you probably need to use the low-level conversion
+-functions to convert one character at a time.  *Note Converting One
+-Char::.
+-
+- - Function: size_t mbstowcs (wchar_t *WSTRING, const char *STRING,
+-          size_t SIZE)
+-     The `mbstowcs' ("multibyte string to wide character string")
+-     function converts the null-terminated string of multibyte
+-     characters STRING to an array of wide character codes, storing not
+-     more than SIZE wide characters into the array beginning at WSTRING.
+-     The terminating null character counts towards the size, so if SIZE
+-     is less than the actual number of wide characters resulting from
+-     STRING, no terminating null character is stored.
+-
+-     The conversion of characters from STRING begins in the initial
+-     shift state.
+-
+-     If an invalid multibyte character sequence is found, this function
+-     returns a value of `-1'.  Otherwise, it returns the number of wide
+-     characters stored in the array WSTRING.  This number does not
+-     include the terminating null character, which is present if the
+-     number is less than SIZE.
+-
+-     Here is an example showing how to convert a string of multibyte
+-     characters, allocating enough space for the result.
+-
+-          wchar_t *
+-          mbstowcs_alloc (const char *string)
+-          {
+-            size_t size = strlen (string) + 1;
+-            wchar_t *buf = xmalloc (size * sizeof (wchar_t));
+-          
+-            size = mbstowcs (buf, string, size);
+-            if (size == (size_t) -1)
+-              return NULL;
+-            buf = xrealloc (buf, (size + 1) * sizeof (wchar_t));
+-            return buf;
+-          }
+-
+-
+- - Function: size_t wcstombs (char *STRING, const wchar_t WSTRING,
+-          size_t SIZE)
+-     The `wcstombs' ("wide character string to multibyte string")
+-     function converts the null-terminated wide character array WSTRING
+-     into a string containing multibyte characters, storing not more
+-     than SIZE bytes starting at STRING, followed by a terminating null
+-     character if there is room.  The conversion of characters begins in
+-     the initial shift state.
+-
+-     The terminating null character counts towards the size, so if SIZE
+-     is less than or equal to the number of bytes needed in WSTRING, no
+-     terminating null character is stored.
+-
+-     If a code that does not correspond to a valid multibyte character
+-     is found, this function returns a value of `-1'.  Otherwise, the
+-     return value is the number of bytes stored in the array STRING.
+-     This number does not include the terminating null character, which
+-     is present if the number is less than SIZE.
+-
+-
+-File: libc.info,  Node: Length of Char,  Next: Converting One Char,  Prev: 
Wide String Conversion,  Up: Extended Characters
+-
+-Multibyte Character Length
+-==========================
+-
+-   This section describes how to scan a string containing multibyte
+-characters, one character at a time.  The difficulty in doing this is
+-to know how many bytes each character contains.  Your program can use
+-`mblen' to find this out.
+-
+- - Function: int mblen (const char *STRING, size_t SIZE)
+-     The `mblen' function with a non-null STRING argument returns the
+-     number of bytes that make up the multibyte character beginning at
+-     STRING, never examining more than SIZE bytes.  (The idea is to
+-     supply for SIZE the number of bytes of data you have in hand.)
+-
+-     The return value of `mblen' distinguishes three possibilities: the
+-     first SIZE bytes at STRING start with valid multibyte character,
+-     they start with an invalid byte sequence or just part of a
+-     character, or STRING points to an empty string (a null character).
+-
+-     For a valid multibyte character, `mblen' returns the number of
+-     bytes in that character (always at least `1', and never more than
+-     SIZE).  For an invalid byte sequence, `mblen' returns `-1'.  For
+-     an empty string, it returns `0'.
+-
+-     If the multibyte character code uses shift characters, then `mblen'
+-     maintains and updates a shift state as it scans.  If you call
+-     `mblen' with a null pointer for STRING, that initializes the shift
+-     state to its standard initial value.  It also returns nonzero if
+-     the multibyte character code in use actually has a shift state.
+-     *Note Shift State::.
+-
+-     The function `mblen' is declared in `stdlib.h'.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-19 
glibc-2.0.1/manual/libc.info-19
+--- ../glibc-2.0.1/manual/libc.info-19 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-19    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1234 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Converting One Char,  Next: Example of Conversion,  
Prev: Length of Char,  Up: Extended Characters
+-
+-Conversion of Extended Characters One by One
+-============================================
+-
+-   You can convert multibyte characters one at a time to wide characters
+-with the `mbtowc' function.  The `wctomb' function does the reverse.
+-These functions are declared in `stdlib.h'.
+-
+- - Function: int mbtowc (wchar_t *RESULT, const char *STRING, size_t
+-          SIZE)
+-     The `mbtowc' ("multibyte to wide character") function when called
+-     with non-null STRING converts the first multibyte character
+-     beginning at STRING to its corresponding wide character code.  It
+-     stores the result in `*RESULT'.
+-
+-     `mbtowc' never examines more than SIZE bytes.  (The idea is to
+-     supply for SIZE the number of bytes of data you have in hand.)
+-
+-     `mbtowc' with non-null STRING distinguishes three possibilities:
+-     the first SIZE bytes at STRING start with valid multibyte
+-     character, they start with an invalid byte sequence or just part
+-     of a character, or STRING points to an empty string (a null
+-     character).
+-
+-     For a valid multibyte character, `mbtowc' converts it to a wide
+-     character and stores that in `*RESULT', and returns the number of
+-     bytes in that character (always at least `1', and never more than
+-     SIZE).
+-
+-     For an invalid byte sequence, `mbtowc' returns `-1'.  For an empty
+-     string, it returns `0', also storing `0' in `*RESULT'.
+-
+-     If the multibyte character code uses shift characters, then
+-     `mbtowc' maintains and updates a shift state as it scans.  If you
+-     call `mbtowc' with a null pointer for STRING, that initializes the
+-     shift state to its standard initial value.  It also returns
+-     nonzero if the multibyte character code in use actually has a
+-     shift state.  *Note Shift State::.
+-
+- - Function: int wctomb (char *STRING, wchar_t WCHAR)
+-     The `wctomb' ("wide character to multibyte") function converts the
+-     wide character code WCHAR to its corresponding multibyte character
+-     sequence, and stores the result in bytes starting at STRING.  At
+-     most `MB_CUR_MAX' characters are stored.
+-
+-     `wctomb' with non-null STRING distinguishes three possibilities
+-     for WCHAR: a valid wide character code (one that can be translated
+-     to a multibyte character), an invalid code, and `0'.
+-
+-     Given a valid code, `wctomb' converts it to a multibyte character,
+-     storing the bytes starting at STRING.  Then it returns the number
+-     of bytes in that character (always at least `1', and never more
+-     than `MB_CUR_MAX').
+-
+-     If WCHAR is an invalid wide character code, `wctomb' returns `-1'.
+-     If WCHAR is `0', it returns `0', also storing `0' in `*STRING'.
+-
+-     If the multibyte character code uses shift characters, then
+-     `wctomb' maintains and updates a shift state as it scans.  If you
+-     call `wctomb' with a null pointer for STRING, that initializes the
+-     shift state to its standard initial value.  It also returns
+-     nonzero if the multibyte character code in use actually has a
+-     shift state.  *Note Shift State::.
+-
+-     Calling this function with a WCHAR argument of zero when STRING is
+-     not null has the side-effect of reinitializing the stored shift
+-     state *as well as* storing the multibyte character `0' and
+-     returning `0'.
+-
+-
+-File: libc.info,  Node: Example of Conversion,  Next: Shift State,  Prev: 
Converting One Char,  Up: Extended Characters
+-
+-Character-by-Character Conversion Example
+-=========================================
+-
+-   Here is an example that reads multibyte character text from
+-descriptor `input' and writes the corresponding wide characters to
+-descriptor `output'.  We need to convert characters one by one for this
+-example because `mbstowcs' is unable to continue past a null character,
+-and cannot cope with an apparently invalid partial character by reading
+-more input.
+-
+-     int
+-     file_mbstowcs (int input, int output)
+-     {
+-       char buffer[BUFSIZ + MB_LEN_MAX];
+-       int filled = 0;
+-       int eof = 0;
+-     
+-       while (!eof)
+-         {
+-           int nread;
+-           int nwrite;
+-           char *inp = buffer;
+-           wchar_t outbuf[BUFSIZ];
+-           wchar_t *outp = outbuf;
+-     
+-           /* Fill up the buffer from the input file.  */
+-           nread = read (input, buffer + filled, BUFSIZ);
+-           if (nread < 0)
+-             {
+-               perror ("read");
+-               return 0;
+-             }
+-           /* If we reach end of file, make a note to read no more. */
+-           if (nread == 0)
+-             eof = 1;
+-     
+-           /* `filled' is now the number of bytes in `buffer'. */
+-           filled += nread;
+-     
+-           /* Convert those bytes to wide characters-as many as we can. */
+-           while (1)
+-             {
+-               int thislen = mbtowc (outp, inp, filled);
+-               /* Stop converting at invalid character;
+-                  this can mean we have read just the first part
+-                  of a valid character.  */
+-               if (thislen == -1)
+-                 break;
+-               /* Treat null character like any other,
+-                  but also reset shift state. */
+-               if (thislen == 0) {
+-                 thislen = 1;
+-                 mbtowc (NULL, NULL, 0);
+-               }
+-               /* Advance past this character. */
+-               inp += thislen;
+-               filled -= thislen;
+-               outp++;
+-             }
+-     
+-           /* Write the wide characters we just made.  */
+-           nwrite = write (output, outbuf,
+-                           (outp - outbuf) * sizeof (wchar_t));
+-           if (nwrite < 0)
+-             {
+-               perror ("write");
+-               return 0;
+-             }
+-     
+-           /* See if we have a *real* invalid character. */
+-           if ((eof && filled > 0) || filled >= MB_CUR_MAX)
+-             {
+-               error ("invalid multibyte character");
+-               return 0;
+-             }
+-     
+-           /* If any characters must be carried forward,
+-              put them at the beginning of `buffer'. */
+-           if (filled > 0)
+-             memcpy (inp, buffer, filled);
+-           }
+-         }
+-     
+-       return 1;
+-     }
+-
+-
+-File: libc.info,  Node: Shift State,  Prev: Example of Conversion,  Up: 
Extended Characters
+-
+-Multibyte Codes Using Shift Sequences
+-=====================================
+-
+-   In some multibyte character codes, the *meaning* of any particular
+-byte sequence is not fixed; it depends on what other sequences have come
+-earlier in the same string.  Typically there are just a few sequences
+-that can change the meaning of other sequences; these few are called
+-"shift sequences" and we say that they set the "shift state" for other
+-sequences that follow.
+-
+-   To illustrate shift state and shift sequences, suppose we decide that
+-the sequence `0200' (just one byte) enters Japanese mode, in which
+-pairs of bytes in the range from `0240' to `0377' are single
+-characters, while `0201' enters Latin-1 mode, in which single bytes in
+-the range from `0240' to `0377' are characters, and interpreted
+-according to the ISO Latin-1 character set.  This is a multibyte code
+-which has two alternative shift states ("Japanese mode" and "Latin-1
+-mode"), and two shift sequences that specify particular shift states.
+-
+-   When the multibyte character code in use has shift states, then
+-`mblen', `mbtowc' and `wctomb' must maintain and update the current
+-shift state as they scan the string.  To make this work properly, you
+-must follow these rules:
+-
+-   * Before starting to scan a string, call the function with a null
+-     pointer for the multibyte character address--for example, `mblen
+-     (NULL, 0)'.  This initializes the shift state to its standard
+-     initial value.
+-
+-   * Scan the string one character at a time, in order.  Do not "back
+-     up" and rescan characters already scanned, and do not intersperse
+-     the processing of different strings.
+-
+-   Here is an example of using `mblen' following these rules:
+-
+-     void
+-     scan_string (char *s)
+-     {
+-       int length = strlen (s);
+-     
+-       /* Initialize shift state. */
+-       mblen (NULL, 0);
+-     
+-       while (1)
+-         {
+-           int thischar = mblen (s, length);
+-           /* Deal with end of string and invalid characters. */
+-           if (thischar == 0)
+-             break;
+-           if (thischar == -1)
+-             {
+-               error ("invalid multibyte character");
+-               break;
+-             }
+-           /* Advance past this character. */
+-           s += thischar;
+-           length -= thischar;
+-         }
+-     }
+-
+-   The functions `mblen', `mbtowc' and `wctomb' are not reentrant when
+-using a multibyte code that uses a shift state.  However, no other
+-library functions call these functions, so you don't have to worry that
+-the shift state will be changed mysteriously.
+-
+-
+-File: libc.info,  Node: Locales,  Next: Searching and Sorting,  Prev: 
Extended Characters,  Up: Top
+-
+-Locales and Internationalization
+-********************************
+-
+-   Different countries and cultures have varying conventions for how to
+-communicate.  These conventions range from very simple ones, such as the
+-format for representing dates and times, to very complex ones, such as
+-the language spoken.
+-
+-   "Internationalization" of software means programming it to be able
+-to adapt to the user's favorite conventions.  In ISO C,
+-internationalization works by means of "locales".  Each locale
+-specifies a collection of conventions, one convention for each purpose.
+-The user chooses a set of conventions by specifying a locale (via
+-environment variables).
+-
+-   All programs inherit the chosen locale as part of their environment.
+-Provided the programs are written to obey the choice of locale, they
+-will follow the conventions preferred by the user.
+-
+-* Menu:
+-
+-* Effects of Locale::           Actions affected by the choice of
+-                                 locale.
+-* Choosing Locale::             How the user specifies a locale.
+-* Locale Categories::           Different purposes for which you can
+-                                 select a locale.
+-* Setting the Locale::          How a program specifies the locale
+-                                 with library functions.
+-* Standard Locales::            Locale names available on all systems.
+-* Numeric Formatting::          How to format numbers according to the
+-                                 chosen locale.
+-
+-
+-File: libc.info,  Node: Effects of Locale,  Next: Choosing Locale,  Up: 
Locales
+-
+-What Effects a Locale Has
+-=========================
+-
+-   Each locale specifies conventions for several purposes, including the
+-following:
+-
+-   * What multibyte character sequences are valid, and how they are
+-     interpreted (*note Extended Characters::.).
+-
+-   * Classification of which characters in the local character set are
+-     considered alphabetic, and upper- and lower-case conversion
+-     conventions (*note Character Handling::.).
+-
+-   * The collating sequence for the local language and character set
+-     (*note Collation Functions::.).
+-
+-   * Formatting of numbers and currency amounts (*note Numeric
+-     Formatting::.).
+-
+-   * Formatting of dates and times (*note Formatting Date and Time::.).
+-
+-   * What language to use for output, including error messages.  (The C
+-     library doesn't yet help you implement this.)
+-
+-   * What language to use for user answers to yes-or-no questions.
+-
+-   * What language to use for more complex user input.  (The C library
+-     doesn't yet help you implement this.)
+-
+-   Some aspects of adapting to the specified locale are handled
+-automatically by the library subroutines.  For example, all your program
+-needs to do in order to use the collating sequence of the chosen locale
+-is to use `strcoll' or `strxfrm' to compare strings.
+-
+-   Other aspects of locales are beyond the comprehension of the library.
+-For example, the library can't automatically translate your program's
+-output messages into other languages.  The only way you can support
+-output in the user's favorite language is to program this more or less
+-by hand.  (Eventually, we hope to provide facilities to make this
+-easier.)
+-
+-   This chapter discusses the mechanism by which you can modify the
+-current locale.  The effects of the current locale on specific library
+-functions are discussed in more detail in the descriptions of those
+-functions.
+-
+-
+-File: libc.info,  Node: Choosing Locale,  Next: Locale Categories,  Prev: 
Effects of Locale,  Up: Locales
+-
+-Choosing a Locale
+-=================
+-
+-   The simplest way for the user to choose a locale is to set the
+-environment variable `LANG'.  This specifies a single locale to use for
+-all purposes.  For example, a user could specify a hypothetical locale
+-named `espana-castellano' to use the standard conventions of most of
+-Spain.
+-
+-   The set of locales supported depends on the operating system you are
+-using, and so do their names.  We can't make any promises about what
+-locales will exist, except for one standard locale called `C' or
+-`POSIX'.
+-
+-   A user also has the option of specifying different locales for
+-different purposes--in effect, choosing a mixture of multiple locales.
+-
+-   For example, the user might specify the locale `espana-castellano'
+-for most purposes, but specify the locale `usa-english' for currency
+-formatting.  This might make sense if the user is a Spanish-speaking
+-American, working in Spanish, but representing monetary amounts in US
+-dollars.
+-
+-   Note that both locales `espana-castellano' and `usa-english', like
+-all locales, would include conventions for all of the purposes to which
+-locales apply.  However, the user can choose to use each locale for a
+-particular subset of those purposes.
+-
+-
+-File: libc.info,  Node: Locale Categories,  Next: Setting the Locale,  Prev: 
Choosing Locale,  Up: Locales
+-
+-Categories of Activities that Locales Affect
+-============================================
+-
+-   The purposes that locales serve are grouped into "categories", so
+-that a user or a program can choose the locale for each category
+-independently.  Here is a table of categories; each name is both an
+-environment variable that a user can set, and a macro name that you can
+-use as an argument to `setlocale'.
+-
+-`LC_COLLATE'
+-     This category applies to collation of strings (functions `strcoll'
+-     and `strxfrm'); see *Note Collation Functions::.
+-
+-`LC_CTYPE'
+-     This category applies to classification and conversion of
+-     characters, and to multibyte and wide characters; see *Note
+-     Character Handling:: and *Note Extended Characters::.
+-
+-`LC_MONETARY'
+-     This category applies to formatting monetary values; see *Note
+-     Numeric Formatting::.
+-
+-`LC_NUMERIC'
+-     This category applies to formatting numeric values that are not
+-     monetary; see *Note Numeric Formatting::.
+-
+-`LC_TIME'
+-     This category applies to formatting date and time values; see
+-     *Note Formatting Date and Time::.
+-
+-`LC_MESSAGES'
+-     This category applies to selecting the language used in the user
+-     interface for message translation.
+-
+-`LC_ALL'
+-     This is not an environment variable; it is only a macro that you
+-     can use with `setlocale' to set a single locale for all purposes.
+-
+-`LANG'
+-     If this environment variable is defined, its value specifies the
+-     locale to use for all purposes except as overridden by the
+-     variables above.
+-
+-
+-File: libc.info,  Node: Setting the Locale,  Next: Standard Locales,  Prev: 
Locale Categories,  Up: Locales
+-
+-How Programs Set the Locale
+-===========================
+-
+-   A C program inherits its locale environment variables when it starts
+-up.  This happens automatically.  However, these variables do not
+-automatically control the locale used by the library functions, because
+-ISO C says that all programs start by default in the standard `C'
+-locale.  To use the locales specified by the environment, you must call
+-`setlocale'.  Call it as follows:
+-
+-     setlocale (LC_ALL, "");
+-
+-to select a locale based on the appropriate environment variables.
+-
+-   You can also use `setlocale' to specify a particular locale, for
+-general use or for a specific category.
+-
+-   The symbols in this section are defined in the header file
+-`locale.h'.
+-
+- - Function: char * setlocale (int CATEGORY, const char *LOCALE)
+-     The function `setlocale' sets the current locale for category
+-     CATEGORY to LOCALE.
+-
+-     If CATEGORY is `LC_ALL', this specifies the locale for all
+-     purposes.  The other possible values of CATEGORY specify an
+-     individual purpose (*note Locale Categories::.).
+-
+-     You can also use this function to find out the current locale by
+-     passing a null pointer as the LOCALE argument.  In this case,
+-     `setlocale' returns a string that is the name of the locale
+-     currently selected for category CATEGORY.
+-
+-     The string returned by `setlocale' can be overwritten by subsequent
+-     calls, so you should make a copy of the string (*note Copying and
+-     Concatenation::.) if you want to save it past any further calls to
+-     `setlocale'.  (The standard library is guaranteed never to call
+-     `setlocale' itself.)
+-
+-     You should not modify the string returned by `setlocale'.  It
+-     might be the same string that was passed as an argument in a
+-     previous call to `setlocale'.
+-
+-     When you read the current locale for category `LC_ALL', the value
+-     encodes the entire combination of selected locales for all
+-     categories.  In this case, the value is not just a single locale
+-     name.  In fact, we don't make any promises about what it looks
+-     like.  But if you specify the same "locale name" with `LC_ALL' in
+-     a subsequent call to `setlocale', it restores the same combination
+-     of locale selections.
+-
+-     When the LOCALE argument is not a null pointer, the string returned
+-     by `setlocale' reflects the newly modified locale.
+-
+-     If you specify an empty string for LOCALE, this means to read the
+-     appropriate environment variable and use its value to select the
+-     locale for CATEGORY.
+-
+-     If you specify an invalid locale name, `setlocale' returns a null
+-     pointer and leaves the current locale unchanged.
+-
+-   Here is an example showing how you might use `setlocale' to
+-temporarily switch to a new locale.
+-
+-     #include <stddef.h>
+-     #include <locale.h>
+-     #include <stdlib.h>
+-     #include <string.h>
+-     
+-     void
+-     with_other_locale (char *new_locale,
+-                        void (*subroutine) (int),
+-                        int argument)
+-     {
+-       char *old_locale, *saved_locale;
+-     
+-       /* Get the name of the current locale.  */
+-       old_locale = setlocale (LC_ALL, NULL);
+-     
+-       /* Copy the name so it won't be clobbered by `setlocale'. */
+-       saved_locale = strdup (old_locale);
+-       if (old_locale == NULL)
+-         fatal ("Out of memory");
+-     
+-       /* Now change the locale and do some stuff with it. */
+-       setlocale (LC_ALL, new_locale);
+-       (*subroutine) (argument);
+-     
+-       /* Restore the original locale. */
+-       setlocale (LC_ALL, saved_locale);
+-       free (saved_locale);
+-     }
+-
+-   *Portability Note:* Some ISO C systems may define additional locale
+-categories.  For portability, assume that any symbol beginning with
+-`LC_' might be defined in `locale.h'.
+-
+-
+-File: libc.info,  Node: Standard Locales,  Next: Numeric Formatting,  Prev: 
Setting the Locale,  Up: Locales
+-
+-Standard Locales
+-================
+-
+-   The only locale names you can count on finding on all operating
+-systems are these three standard ones:
+-
+-`"C"'
+-     This is the standard C locale.  The attributes and behavior it
+-     provides are specified in the ISO C standard.  When your program
+-     starts up, it initially uses this locale by default.
+-
+-`"POSIX"'
+-     This is the standard POSIX locale.  Currently, it is an alias for
+-     the standard C locale.
+-
+-`""'
+-     The empty name says to select a locale based on environment
+-     variables.  *Note Locale Categories::.
+-
+-   Defining and installing named locales is normally a responsibility of
+-the system administrator at your site (or the person who installed the
+-GNU C library).  Some systems may allow users to create locales, but we
+-don't discuss that here.
+-
+-   If your program needs to use something other than the `C' locale, it
+-will be more portable if you use whatever locale the user specifies
+-with the environment, rather than trying to specify some non-standard
+-locale explicitly by name.  Remember, different machines might have
+-different sets of locales installed.
+-
+-
+-File: libc.info,  Node: Numeric Formatting,  Prev: Standard Locales,  Up: 
Locales
+-
+-Numeric Formatting
+-==================
+-
+-   When you want to format a number or a currency amount using the
+-conventions of the current locale, you can use the function
+-`localeconv' to get the data on how to do it.  The function
+-`localeconv' is declared in the header file `locale.h'.
+-
+- - Function: struct lconv * localeconv (void)
+-     The `localeconv' function returns a pointer to a structure whose
+-     components contain information about how numeric and monetary
+-     values should be formatted in the current locale.
+-
+-     You shouldn't modify the structure or its contents.  The structure
+-     might be overwritten by subsequent calls to `localeconv', or by
+-     calls to `setlocale', but no other function in the library
+-     overwrites this value.
+-
+- - Data Type: struct lconv
+-     This is the data type of the value returned by `localeconv'.
+-
+-   If a member of the structure `struct lconv' has type `char', and the
+-value is `CHAR_MAX', it means that the current locale has no value for
+-that parameter.
+-
+-* Menu:
+-
+-* General Numeric::             Parameters for formatting numbers and
+-                                 currency amounts.
+-* Currency Symbol::             How to print the symbol that identifies an
+-                                 amount of money (e.g. `$').
+-* Sign of Money Amount::        How to print the (positive or negative) sign
+-                                 for a monetary amount, if one exists.
+-
+-
+-File: libc.info,  Node: General Numeric,  Next: Currency Symbol,  Up: Numeric 
Formatting
+-
+-Generic Numeric Formatting Parameters
+--------------------------------------
+-
+-   These are the standard members of `struct lconv'; there may be
+-others.
+-
+-`char *decimal_point'
+-`char *mon_decimal_point'
+-     These are the decimal-point separators used in formatting
+-     non-monetary and monetary quantities, respectively.  In the `C'
+-     locale, the value of `decimal_point' is `"."', and the value of
+-     `mon_decimal_point' is `""'.
+-
+-`char *thousands_sep'
+-`char *mon_thousands_sep'
+-     These are the separators used to delimit groups of digits to the
+-     left of the decimal point in formatting non-monetary and monetary
+-     quantities, respectively.  In the `C' locale, both members have a
+-     value of `""' (the empty string).
+-
+-`char *grouping'
+-`char *mon_grouping'
+-     These are strings that specify how to group the digits to the left
+-     of the decimal point.  `grouping' applies to non-monetary
+-     quantities and `mon_grouping' applies to monetary quantities.  Use
+-     either `thousands_sep' or `mon_thousands_sep' to separate the digit
+-     groups.
+-
+-     Each string is made up of decimal numbers separated by semicolons.
+-     Successive numbers (from left to right) give the sizes of
+-     successive groups (from right to left, starting at the decimal
+-     point).  The last number in the string is used over and over for
+-     all the remaining groups.
+-
+-     If the last integer is `-1', it means that there is no more
+-     grouping--or, put another way, any remaining digits form one large
+-     group without separators.
+-
+-     For example, if `grouping' is `"4;3;2"', the correct grouping for
+-     the number `123456787654321' is `12', `34', `56', `78', `765',
+-     `4321'.  This uses a group of 4 digits at the end, preceded by a
+-     group of 3 digits, preceded by groups of 2 digits (as many as
+-     needed).  With a separator of `,', the number would be printed as
+-     `12,34,56,78,765,4321'.
+-
+-     A value of `"3"' indicates repeated groups of three digits, as
+-     normally used in the U.S.
+-
+-     In the standard `C' locale, both `grouping' and `mon_grouping'
+-     have a value of `""'.  This value specifies no grouping at all.
+-
+-`char int_frac_digits'
+-`char frac_digits'
+-     These are small integers indicating how many fractional digits (to
+-     the right of the decimal point) should be displayed in a monetary
+-     value in international and local formats, respectively.  (Most
+-     often, both members have the same value.)
+-
+-     In the standard `C' locale, both of these members have the value
+-     `CHAR_MAX', meaning "unspecified".  The ISO standard doesn't say
+-     what to do when you find this the value; we recommend printing no
+-     fractional digits.  (This locale also specifies the empty string
+-     for `mon_decimal_point', so printing any fractional digits would be
+-     confusing!)
+-
+-
+-File: libc.info,  Node: Currency Symbol,  Next: Sign of Money Amount,  Prev: 
General Numeric,  Up: Numeric Formatting
+-
+-Printing the Currency Symbol
+-----------------------------
+-
+-   These members of the `struct lconv' structure specify how to print
+-the symbol to identify a monetary value--the international analog of
+-`$' for US dollars.
+-
+-   Each country has two standard currency symbols.  The "local currency
+-symbol" is used commonly within the country, while the "international
+-currency symbol" is used internationally to refer to that country's
+-currency when it is necessary to indicate the country unambiguously.
+-
+-   For example, many countries use the dollar as their monetary unit,
+-and when dealing with international currencies it's important to specify
+-that one is dealing with (say) Canadian dollars instead of U.S. dollars
+-or Australian dollars.  But when the context is known to be Canada,
+-there is no need to make this explicit--dollar amounts are implicitly
+-assumed to be in Canadian dollars.
+-
+-`char *currency_symbol'
+-     The local currency symbol for the selected locale.
+-
+-     In the standard `C' locale, this member has a value of `""' (the
+-     empty string), meaning "unspecified".  The ISO standard doesn't
+-     say what to do when you find this value; we recommend you simply
+-     print the empty string as you would print any other string found
+-     in the appropriate member.
+-
+-`char *int_curr_symbol'
+-     The international currency symbol for the selected locale.
+-
+-     The value of `int_curr_symbol' should normally consist of a
+-     three-letter abbreviation determined by the international standard
+-     `ISO 4217 Codes for the Representation of Currency and Funds',
+-     followed by a one-character separator (often a space).
+-
+-     In the standard `C' locale, this member has a value of `""' (the
+-     empty string), meaning "unspecified".  We recommend you simply
+-     print the empty string as you would print any other string found
+-     in the appropriate member.
+-
+-`char p_cs_precedes'
+-`char n_cs_precedes'
+-     These members are `1' if the `currency_symbol' string should
+-     precede the value of a monetary amount, or `0' if the string should
+-     follow the value.  The `p_cs_precedes' member applies to positive
+-     amounts (or zero), and the `n_cs_precedes' member applies to
+-     negative amounts.
+-
+-     In the standard `C' locale, both of these members have a value of
+-     `CHAR_MAX', meaning "unspecified".  The ISO standard doesn't say
+-     what to do when you find this value, but we recommend printing the
+-     currency symbol before the amount.  That's right for most
+-     countries.  In other words, treat all nonzero values alike in
+-     these members.
+-
+-     The POSIX standard says that these two members apply to the
+-     `int_curr_symbol' as well as the `currency_symbol'.  The ISO C
+-     standard seems to imply that they should apply only to the
+-     `currency_symbol'--so the `int_curr_symbol' should always precede
+-     the amount.
+-
+-     We can only guess which of these (if either) matches the usual
+-     conventions for printing international currency symbols.  Our
+-     guess is that they should always precede the amount.  If we find
+-     out a reliable answer, we will put it here.
+-
+-`char p_sep_by_space'
+-`char n_sep_by_space'
+-     These members are `1' if a space should appear between the
+-     `currency_symbol' string and the amount, or `0' if no space should
+-     appear.  The `p_sep_by_space' member applies to positive amounts
+-     (or zero), and the `n_sep_by_space' member applies to negative
+-     amounts.
+-
+-     In the standard `C' locale, both of these members have a value of
+-     `CHAR_MAX', meaning "unspecified".  The ISO standard doesn't say
+-     what you should do when you find this value; we suggest you treat
+-     it as one (print a space).  In other words, treat all nonzero
+-     values alike in these members.
+-
+-     These members apply only to `currency_symbol'.  When you use
+-     `int_curr_symbol', you never print an additional space, because
+-     `int_curr_symbol' itself contains the appropriate separator.
+-
+-     The POSIX standard says that these two members apply to the
+-     `int_curr_symbol' as well as the `currency_symbol'.  But an
+-     example in the ISO C standard clearly implies that they should
+-     apply only to the `currency_symbol'--that the `int_curr_symbol'
+-     contains any appropriate separator, so you should never print an
+-     additional space.
+-
+-     Based on what we know now, we recommend you ignore these members
+-     when printing international currency symbols, and print no extra
+-     space.
+-
+-
+-File: libc.info,  Node: Sign of Money Amount,  Prev: Currency Symbol,  Up: 
Numeric Formatting
+-
+-Printing the Sign of an Amount of Money
+----------------------------------------
+-
+-   These members of the `struct lconv' structure specify how to print
+-the sign (if any) in a monetary value.
+-
+-`char *positive_sign'
+-`char *negative_sign'
+-     These are strings used to indicate positive (or zero) and negative
+-     (respectively) monetary quantities.
+-
+-     In the standard `C' locale, both of these members have a value of
+-     `""' (the empty string), meaning "unspecified".
+-
+-     The ISO standard doesn't say what to do when you find this value;
+-     we recommend printing `positive_sign' as you find it, even if it is
+-     empty.  For a negative value, print `negative_sign' as you find it
+-     unless both it and `positive_sign' are empty, in which case print
+-     `-' instead.  (Failing to indicate the sign at all seems rather
+-     unreasonable.)
+-
+-`char p_sign_posn'
+-`char n_sign_posn'
+-     These members have values that are small integers indicating how to
+-     position the sign for nonnegative and negative monetary quantities,
+-     respectively.  (The string used by the sign is what was specified
+-     with `positive_sign' or `negative_sign'.)  The possible values are
+-     as follows:
+-
+-    `0'
+-          The currency symbol and quantity should be surrounded by
+-          parentheses.
+-
+-    `1'
+-          Print the sign string before the quantity and currency symbol.
+-
+-    `2'
+-          Print the sign string after the quantity and currency symbol.
+-
+-    `3'
+-          Print the sign string right before the currency symbol.
+-
+-    `4'
+-          Print the sign string right after the currency symbol.
+-
+-    `CHAR_MAX'
+-          "Unspecified".  Both members have this value in the standard
+-          `C' locale.
+-
+-     The ISO standard doesn't say what you should do when the value is
+-     `CHAR_MAX'.  We recommend you print the sign after the currency
+-     symbol.
+-
+-   It is not clear whether you should let these members apply to the
+-international currency format or not.  POSIX says you should, but
+-intuition plus the examples in the ISO C standard suggest you should
+-not.  We hope that someone who knows well the conventions for formatting
+-monetary quantities will tell us what we should recommend.
+-
+-
+-File: libc.info,  Node: Non-Local Exits,  Next: Signal Handling,  Prev: Date 
and Time,  Up: Top
+-
+-Non-Local Exits
+-***************
+-
+-   Sometimes when your program detects an unusual situation inside a
+-deeply nested set of function calls, you would like to be able to
+-immediately return to an outer level of control.  This section
+-describes how you can do such "non-local exits" using the `setjmp' and
+-`longjmp' functions.
+-
+-* Menu:
+-
+-* Intro: Non-Local Intro.        When and how to use these facilities.
+-* Details: Non-Local Details.   Functions for nonlocal exits.
+-* Non-Local Exits and Signals::  Portability issues.
+-
+-
+-File: libc.info,  Node: Non-Local Intro,  Next: Non-Local Details,  Up: 
Non-Local Exits
+-
+-Introduction to Non-Local Exits
+-===============================
+-
+-   As an example of a situation where a non-local exit can be useful,
+-suppose you have an interactive program that has a "main loop" that
+-prompts for and executes commands.  Suppose the "read" command reads
+-input from a file, doing some lexical analysis and parsing of the input
+-while processing it.  If a low-level input error is detected, it would
+-be useful to be able to return immediately to the "main loop" instead
+-of having to make each of the lexical analysis, parsing, and processing
+-phases all have to explicitly deal with error situations initially
+-detected by nested calls.
+-
+-   (On the other hand, if each of these phases has to do a substantial
+-amount of cleanup when it exits--such as closing files, deallocating
+-buffers or other data structures, and the like--then it can be more
+-appropriate to do a normal return and have each phase do its own
+-cleanup, because a non-local exit would bypass the intervening phases
+-and their associated cleanup code entirely.  Alternatively, you could
+-use a non-local exit but do the cleanup explicitly either before or
+-after returning to the "main loop".)
+-
+-   In some ways, a non-local exit is similar to using the `return'
+-statement to return from a function.  But while `return' abandons only
+-a single function call, transferring control back to the point at which
+-it was called, a non-local exit can potentially abandon many levels of
+-nested function calls.
+-
+-   You identify return points for non-local exits calling the function
+-`setjmp'.  This function saves information about the execution
+-environment in which the call to `setjmp' appears in an object of type
+-`jmp_buf'.  Execution of the program continues normally after the call
+-to `setjmp', but if a exit is later made to this return point by
+-calling `longjmp' with the corresponding `jmp_buf' object, control is
+-transferred back to the point where `setjmp' was called.  The return
+-value from `setjmp' is used to distinguish between an ordinary return
+-and a return made by a call to `longjmp', so calls to `setjmp' usually
+-appear in an `if' statement.
+-
+-   Here is how the example program described above might be set up:
+-
+-     #include <setjmp.h>
+-     #include <stdlib.h>
+-     #include <stdio.h>
+-     
+-     jmp_buf main_loop;
+-     
+-     void
+-     abort_to_main_loop (int status)
+-     {
+-       longjmp (main_loop, status);
+-     }
+-     
+-     int
+-     main (void)
+-     {
+-       while (1)
+-         if (setjmp (main_loop))
+-           puts ("Back at main loop....");
+-         else
+-           do_command ();
+-     }
+-     
+-     
+-     void
+-     do_command (void)
+-     {
+-       char buffer[128];
+-       if (fgets (buffer, 128, stdin) == NULL)
+-         abort_to_main_loop (-1);
+-       else
+-         exit (EXIT_SUCCESS);
+-     }
+-
+-   The function `abort_to_main_loop' causes an immediate transfer of
+-control back to the main loop of the program, no matter where it is
+-called from.
+-
+-   The flow of control inside the `main' function may appear a little
+-mysterious at first, but it is actually a common idiom with `setjmp'.
+-A normal call to `setjmp' returns zero, so the "else" clause of the
+-conditional is executed.  If `abort_to_main_loop' is called somewhere
+-within the execution of `do_command', then it actually appears as if
+-the *same* call to `setjmp' in `main' were returning a second time with
+-a value of `-1'.
+-
+-   So, the general pattern for using `setjmp' looks something like:
+-
+-     if (setjmp (BUFFER))
+-       /* Code to clean up after premature return. */
+-       ...
+-     else
+-       /* Code to be executed normally after setting up the return point. */
+-       ...
+-
+-
+-File: libc.info,  Node: Non-Local Details,  Next: Non-Local Exits and 
Signals,  Prev: Non-Local Intro,  Up: Non-Local Exits
+-
+-Details of Non-Local Exits
+-==========================
+-
+-   Here are the details on the functions and data structures used for
+-performing non-local exits.  These facilities are declared in
+-`setjmp.h'.
+-
+- - Data Type: jmp_buf
+-     Objects of type `jmp_buf' hold the state information to be
+-     restored by a non-local exit.  The contents of a `jmp_buf'
+-     identify a specific place to return to.
+-
+- - Macro: int setjmp (jmp_buf STATE)
+-     When called normally, `setjmp' stores information about the
+-     execution state of the program in STATE and returns zero.  If
+-     `longjmp' is later used to perform a non-local exit to this STATE,
+-     `setjmp' returns a nonzero value.
+-
+- - Function: void longjmp (jmp_buf STATE, int VALUE)
+-     This function restores current execution to the state saved in
+-     STATE, and continues execution from the call to `setjmp' that
+-     established that return point.  Returning from `setjmp' by means of
+-     `longjmp' returns the VALUE argument that was passed to `longjmp',
+-     rather than `0'.  (But if VALUE is given as `0', `setjmp' returns
+-     `1').
+-
+-   There are a lot of obscure but important restrictions on the use of
+-`setjmp' and `longjmp'.  Most of these restrictions are present because
+-non-local exits require a fair amount of magic on the part of the C
+-compiler and can interact with other parts of the language in strange
+-ways.
+-
+-   The `setjmp' function is actually a macro without an actual function
+-definition, so you shouldn't try to `#undef' it or take its address.
+-In addition, calls to `setjmp' are safe in only the following contexts:
+-
+-   * As the test expression of a selection or iteration statement (such
+-     as `if', `switch', or `while').
+-
+-   * As one operand of a equality or comparison operator that appears
+-     as the test expression of a selection or iteration statement.  The
+-     other operand must be an integer constant expression.
+-
+-   * As the operand of a unary `!' operator, that appears as the test
+-     expression of a selection or iteration statement.
+-
+-   * By itself as an expression statement.
+-
+-   Return points are valid only during the dynamic extent of the
+-function that called `setjmp' to establish them.  If you `longjmp' to a
+-return point that was established in a function that has already
+-returned, unpredictable and disastrous things are likely to happen.
+-
+-   You should use a nonzero VALUE argument to `longjmp'.  While
+-`longjmp' refuses to pass back a zero argument as the return value from
+-`setjmp', this is intended as a safety net against accidental misuse
+-and is not really good programming style.
+-
+-   When you perform a non-local exit, accessible objects generally
+-retain whatever values they had at the time `longjmp' was called.  The
+-exception is that the values of automatic variables local to the
+-function containing the `setjmp' call that have been changed since the
+-call to `setjmp' are indeterminate, unless you have declared them
+-`volatile'.
+-
+-
+-File: libc.info,  Node: Non-Local Exits and Signals,  Prev: Non-Local 
Details,  Up: Non-Local Exits
+-
+-Non-Local Exits and Signals
+-===========================
+-
+-   In BSD Unix systems, `setjmp' and `longjmp' also save and restore
+-the set of blocked signals; see *Note Blocking Signals::.  However, the
+-POSIX.1 standard requires `setjmp' and `longjmp' not to change the set
+-of blocked signals, and provides an additional pair of functions
+-(`sigsetjmp' and `sigsetjmp') to get the BSD behavior.
+-
+-   The behavior of `setjmp' and `longjmp' in the GNU library is
+-controlled by feature test macros; see *Note Feature Test Macros::.  The
+-default in the GNU system is the POSIX.1 behavior rather than the BSD
+-behavior.
+-
+-   The facilities in this section are declared in the header file
+-`setjmp.h'.
+-
+- - Data Type: sigjmp_buf
+-     This is similar to `jmp_buf', except that it can also store state
+-     information about the set of blocked signals.
+-
+- - Function: int sigsetjmp (sigjmp_buf STATE, int SAVESIGS)
+-     This is similar to `setjmp'.  If SAVESIGS is nonzero, the set of
+-     blocked signals is saved in STATE and will be restored if a
+-     `siglongjmp' is later performed with this STATE.
+-
+- - Function: void siglongjmp (sigjmp_buf STATE, int VALUE)
+-     This is similar to `longjmp' except for the type of its STATE
+-     argument.  If the `sigsetjmp' call that set this STATE used a
+-     nonzero SAVESIGS flag, `siglongjmp' also restores the set of
+-     blocked signals.
+-
+-
+-File: libc.info,  Node: Signal Handling,  Next: Process Startup,  Prev: 
Non-Local Exits,  Up: Top
+-
+-Signal Handling
+-***************
+-
+-   A "signal" is a software interrupt delivered to a process.  The
+-operating system uses signals to report exceptional situations to an
+-executing program.  Some signals report errors such as references to
+-invalid memory addresses; others report asynchronous events, such as
+-disconnection of a phone line.
+-
+-   The GNU C library defines a variety of signal types, each for a
+-particular kind of event.  Some kinds of events make it inadvisable or
+-impossible for the program to proceed as usual, and the corresponding
+-signals normally abort the program.  Other kinds of signals that report
+-harmless events are ignored by default.
+-
+-   If you anticipate an event that causes signals, you can define a
+-handler function and tell the operating system to run it when that
+-particular type of signal arrives.
+-
+-   Finally, one process can send a signal to another process; this
+-allows a parent process to abort a child, or two related processes to
+-communicate and synchronize.
+-
+-* Menu:
+-
+-* Concepts of Signals::         Introduction to the signal facilities.
+-* Standard Signals::            Particular kinds of signals with
+-                                 standard names and meanings.
+-* Signal Actions::              Specifying what happens when a
+-                                 particular signal is delivered.
+-* Defining Handlers::           How to write a signal handler function.
+-* Interrupted Primitives::    Signal handlers affect use of `open',
+-                               `read', `write' and other functions.
+-* Generating Signals::          How to send a signal to a process.
+-* Blocking Signals::            Making the system hold signals temporarily.
+-* Waiting for a Signal::        Suspending your program until a signal
+-                                 arrives.
+-* Signal Stack::                Using a Separate Signal Stack.
+-* BSD Signal Handling::         Additional functions for backward
+-                               compatibility with BSD.
+-
+-
+-File: libc.info,  Node: Concepts of Signals,  Next: Standard Signals,  Up: 
Signal Handling
+-
+-Basic Concepts of Signals
+-=========================
+-
+-   This section explains basic concepts of how signals are generated,
+-what happens after a signal is delivered, and how programs can handle
+-signals.
+-
+-* Menu:
+-
+-* Kinds of Signals::            Some examples of what can cause a signal.
+-* Signal Generation::           Concepts of why and how signals occur.
+-* Delivery of Signal::          Concepts of what a signal does to the
+-                                 process.
+-
+-
+-File: libc.info,  Node: Kinds of Signals,  Next: Signal Generation,  Up: 
Concepts of Signals
+-
+-Some Kinds of Signals
+----------------------
+-
+-   A signal reports the occurrence of an exceptional event.  These are
+-some of the events that can cause (or "generate", or "raise") a signal:
+-
+-   * A program error such as dividing by zero or issuing an address
+-     outside the valid range.
+-
+-   * A user request to interrupt or terminate the program.  Most
+-     environments are set up to let a user suspend the program by
+-     typing `C-z', or terminate it with `C-c'.  Whatever key sequence
+-     is used, the operating system sends the proper signal to interrupt
+-     the process.
+-
+-   * The termination of a child process.
+-
+-   * Expiration of a timer or alarm.
+-
+-   * A call to `kill' or `raise' by the same process.
+-
+-   * A call to `kill' from another process.  Signals are a limited but
+-     useful form of interprocess communication.
+-
+-   * An attempt to perform an I/O operation that cannot be done.
+-     Examples are reading from a pipe that has no writer (*note Pipes
+-     and FIFOs::.), and reading or writing to a terminal in certain
+-     situations (*note Job Control::.).
+-
+-   Each of these kinds of events (excepting explicit calls to `kill'
+-and `raise') generates its own particular kind of signal.  The various
+-kinds of signals are listed and described in detail in *Note Standard
+-Signals::.
+-
+-
+-File: libc.info,  Node: Signal Generation,  Next: Delivery of Signal,  Prev: 
Kinds of Signals,  Up: Concepts of Signals
+-
+-Concepts of Signal Generation
+------------------------------
+-
+-   In general, the events that generate signals fall into three major
+-categories: errors, external events, and explicit requests.
+-
+-   An error means that a program has done something invalid and cannot
+-continue execution.  But not all kinds of errors generate signals--in
+-fact, most do not.  For example, opening a nonexistent file is an error,
+-but it does not raise a signal; instead, `open' returns `-1'.  In
+-general, errors that are necessarily associated with certain library
+-functions are reported by returning a value that indicates an error.
+-The errors which raise signals are those which can happen anywhere in
+-the program, not just in library calls.  These include division by zero
+-and invalid memory addresses.
+-
+-   An external event generally has to do with I/O or other processes.
+-These include the arrival of input, the expiration of a timer, and the
+-termination of a child process.
+-
+-   An explicit request means the use of a library function such as
+-`kill' whose purpose is specifically to generate a signal.
+-
+-   Signals may be generated "synchronously" or "asynchronously".  A
+-synchronous signal pertains to a specific action in the program, and is
+-delivered (unless blocked) during that action.  Most errors generate
+-signals synchronously, and so do explicit requests by a process to
+-generate a signal for that same process.  On some machines, certain
+-kinds of hardware errors (usually floating-point exceptions) are not
+-reported completely synchronously, but may arrive a few instructions
+-later.
+-
+-   Asynchronous signals are generated by events outside the control of
+-the process that receives them.  These signals arrive at unpredictable
+-times during execution.  External events generate signals
+-asynchronously, and so do explicit requests that apply to some other
+-process.
+-
+-   A given type of signal is either typically synchronous or typically
+-asynchronous.  For example, signals for errors are typically synchronous
+-because errors generate signals synchronously.  But any type of signal
+-can be generated synchronously or asynchronously with an explicit
+-request.
+-
+-
+-File: libc.info,  Node: Delivery of Signal,  Prev: Signal Generation,  Up: 
Concepts of Signals
+-
+-How Signals Are Delivered
+--------------------------
+-
+-   When a signal is generated, it becomes "pending".  Normally it
+-remains pending for just a short period of time and then is "delivered"
+-to the process that was signaled.  However, if that kind of signal is
+-currently "blocked", it may remain pending indefinitely--until signals
+-of that kind are "unblocked".  Once unblocked, it will be delivered
+-immediately.  *Note Blocking Signals::.
+-
+-   When the signal is delivered, whether right away or after a long
+-delay, the "specified action" for that signal is taken.  For certain
+-signals, such as `SIGKILL' and `SIGSTOP', the action is fixed, but for
+-most signals, the program has a choice: ignore the signal, specify a
+-"handler function", or accept the "default action" for that kind of
+-signal.  The program specifies its choice using functions such as
+-`signal' or `sigaction' (*note Signal Actions::.).  We sometimes say
+-that a handler "catches" the signal.  While the handler is running,
+-that particular signal is normally blocked.
+-
+-   If the specified action for a kind of signal is to ignore it, then
+-any such signal which is generated is discarded immediately.  This
+-happens even if the signal is also blocked at the time.  A signal
+-discarded in this way will never be delivered, not even if the program
+-subsequently specifies a different action for that kind of signal and
+-then unblocks it.
+-
+-   If a signal arrives which the program has neither handled nor
+-ignored, its "default action" takes place.  Each kind of signal has its
+-own default action, documented below (*note Standard Signals::.).  For
+-most kinds of signals, the default action is to terminate the process.
+-For certain kinds of signals that represent "harmless" events, the
+-default action is to do nothing.
+-
+-   When a signal terminates a process, its parent process can determine
+-the cause of termination by examining the termination status code
+-reported by the `wait' or `waitpid' functions.  (This is discussed in
+-more detail in *Note Process Completion::.)  The information it can get
+-includes the fact that termination was due to a signal, and the kind of
+-signal involved.  If a program you run from a shell is terminated by a
+-signal, the shell typically prints some kind of error message.
+-
+-   The signals that normally represent program errors have a special
+-property: when one of these signals terminates the process, it also
+-writes a "core dump file" which records the state of the process at the
+-time of termination.  You can examine the core dump with a debugger to
+-investigate what caused the error.
+-
+-   If you raise a "program error" signal by explicit request, and this
+-terminates the process, it makes a core dump file just as if the signal
+-had been due directly to an error.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-2 
glibc-2.0.1/manual/libc.info-2
+--- ../glibc-2.0.1/manual/libc.info-2  1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-2     1970-01-01 01:00:00.000000000 +0100
+@@ -1,1202 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Header Files,  Next: Macro Definitions,  Up: Using 
the Library
+-
+-Header Files
+-------------
+-
+-   Libraries for use by C programs really consist of two parts: "header
+-files" that define types and macros and declare variables and
+-functions; and the actual library or "archive" that contains the
+-definitions of the variables and functions.
+-
+-   (Recall that in C, a "declaration" merely provides information that
+-a function or variable exists and gives its type.  For a function
+-declaration, information about the types of its arguments might be
+-provided as well.  The purpose of declarations is to allow the compiler
+-to correctly process references to the declared variables and functions.
+-A "definition", on the other hand, actually allocates storage for a
+-variable or says what a function does.)
+-
+-   In order to use the facilities in the GNU C library, you should be
+-sure that your program source files include the appropriate header
+-files.  This is so that the compiler has declarations of these
+-facilities available and can correctly process references to them.
+-Once your program has been compiled, the linker resolves these
+-references to the actual definitions provided in the archive file.
+-
+-   Header files are included into a program source file by the
+-`#include' preprocessor directive.  The C language supports two forms
+-of this directive; the first,
+-
+-     #include "HEADER"
+-
+-is typically used to include a header file HEADER that you write
+-yourself; this would contain definitions and declarations describing the
+-interfaces between the different parts of your particular application.
+-By contrast,
+-
+-     #include <file.h>
+-
+-is typically used to include a header file `file.h' that contains
+-definitions and declarations for a standard library.  This file would
+-normally be installed in a standard place by your system administrator.
+-You should use this second form for the C library header files.
+-
+-   Typically, `#include' directives are placed at the top of the C
+-source file, before any other code.  If you begin your source files with
+-some comments explaining what the code in the file does (a good idea),
+-put the `#include' directives immediately afterwards, following the
+-feature test macro definition (*note Feature Test Macros::.).
+-
+-   For more information about the use of header files and `#include'
+-directives, *note Header Files: (cpp.info)Header Files..
+-
+-   The GNU C library provides several header files, each of which
+-contains the type and macro definitions and variable and function
+-declarations for a group of related facilities.  This means that your
+-programs may need to include several header files, depending on exactly
+-which facilities you are using.
+-
+-   Some library header files include other library header files
+-automatically.  However, as a matter of programming style, you should
+-not rely on this; it is better to explicitly include all the header
+-files required for the library facilities you are using.  The GNU C
+-library header files have been written in such a way that it doesn't
+-matter if a header file is accidentally included more than once;
+-including a header file a second time has no effect.  Likewise, if your
+-program needs to include multiple header files, the order in which they
+-are included doesn't matter.
+-
+-   *Compatibility Note:* Inclusion of standard header files in any
+-order and any number of times works in any ISO C implementation.
+-However, this has traditionally not been the case in many older C
+-implementations.
+-
+-   Strictly speaking, you don't *have to* include a header file to use
+-a function it declares; you could declare the function explicitly
+-yourself, according to the specifications in this manual.  But it is
+-usually better to include the header file because it may define types
+-and macros that are not otherwise available and because it may define
+-more efficient macro replacements for some functions.  It is also a sure
+-way to have the correct declaration.
+-
+-
+-File: libc.info,  Node: Macro Definitions,  Next: Reserved Names,  Prev: 
Header Files,  Up: Using the Library
+-
+-Macro Definitions of Functions
+-------------------------------
+-
+-   If we describe something as a function in this manual, it may have a
+-macro definition as well.  This normally has no effect on how your
+-program runs--the macro definition does the same thing as the function
+-would.  In particular, macro equivalents for library functions evaluate
+-arguments exactly once, in the same way that a function call would.  The
+-main reason for these macro definitions is that sometimes they can
+-produce an inline expansion that is considerably faster than an actual
+-function call.
+-
+-   Taking the address of a library function works even if it is also
+-defined as a macro.  This is because, in this context, the name of the
+-function isn't followed by the left parenthesis that is syntactically
+-necessary to recognize a macro call.
+-
+-   You might occasionally want to avoid using the macro definition of a
+-function--perhaps to make your program easier to debug.  There are two
+-ways you can do this:
+-
+-   * You can avoid a macro definition in a specific use by enclosing
+-     the name of the function in parentheses.  This works because the
+-     name of the function doesn't appear in a syntactic context where
+-     it is recognizable as a macro call.
+-
+-   * You can suppress any macro definition for a whole source file by
+-     using the `#undef' preprocessor directive, unless otherwise stated
+-     explicitly in the description of that facility.
+-
+-   For example, suppose the header file `stdlib.h' declares a function
+-named `abs' with
+-
+-     extern int abs (int);
+-
+-and also provides a macro definition for `abs'.  Then, in:
+-
+-     #include <stdlib.h>
+-     int f (int *i) { return (abs (++*i)); }
+-
+-the reference to `abs' might refer to either a macro or a function.  On
+-the other hand, in each of the following examples the reference is to a
+-function and not a macro.
+-
+-     #include <stdlib.h>
+-     int g (int *i) { return ((abs)(++*i)); }
+-     
+-     #undef abs
+-     int h (int *i) { return (abs (++*i)); }
+-
+-   Since macro definitions that double for a function behave in exactly
+-the same way as the actual function version, there is usually no need
+-for any of these methods.  In fact, removing macro definitions usually
+-just makes your program slower.
+-
+-
+-File: libc.info,  Node: Reserved Names,  Next: Feature Test Macros,  Prev: 
Macro Definitions,  Up: Using the Library
+-
+-Reserved Names
+---------------
+-
+-   The names of all library types, macros, variables and functions that
+-come from the ISO C standard are reserved unconditionally; your program
+-*may not* redefine these names.  All other library names are reserved
+-if your program explicitly includes the header file that defines or
+-declares them.  There are several reasons for these restrictions:
+-
+-   * Other people reading your code could get very confused if you were
+-     using a function named `exit' to do something completely different
+-     from what the standard `exit' function does, for example.
+-     Preventing this situation helps to make your programs easier to
+-     understand and contributes to modularity and maintainability.
+-
+-   * It avoids the possibility of a user accidentally redefining a
+-     library function that is called by other library functions.  If
+-     redefinition were allowed, those other functions would not work
+-     properly.
+-
+-   * It allows the compiler to do whatever special optimizations it
+-     pleases on calls to these functions, without the possibility that
+-     they may have been redefined by the user.  Some library
+-     facilities, such as those for dealing with variadic arguments
+-     (*note Variadic Functions::.) and non-local exits (*note Non-Local
+-     Exits::.), actually require a considerable amount of cooperation
+-     on the part of the C compiler, and implementationally it might be
+-     easier for the compiler to treat these as built-in parts of the
+-     language.
+-
+-   In addition to the names documented in this manual, reserved names
+-include all external identifiers (global functions and variables) that
+-begin with an underscore (`_') and all identifiers regardless of use
+-that begin with either two underscores or an underscore followed by a
+-capital letter are reserved names.  This is so that the library and
+-header files can define functions, variables, and macros for internal
+-purposes without risk of conflict with names in user programs.
+-
+-   Some additional classes of identifier names are reserved for future
+-extensions to the C language or the POSIX.1 environment.  While using
+-these names for your own purposes right now might not cause a problem,
+-they do raise the possibility of conflict with future versions of the C
+-or POSIX standards, so you should avoid these names.
+-
+-   * Names beginning with a capital `E' followed a digit or uppercase
+-     letter may be used for additional error code names.  *Note Error
+-     Reporting::.
+-
+-   * Names that begin with either `is' or `to' followed by a lowercase
+-     letter may be used for additional character testing and conversion
+-     functions.  *Note Character Handling::.
+-
+-   * Names that begin with `LC_' followed by an uppercase letter may be
+-     used for additional macros specifying locale attributes.  *Note
+-     Locales::.
+-
+-   * Names of all existing mathematics functions (*note Mathematics::.)
+-     suffixed with `f' or `l' are reserved for corresponding functions
+-     that operate on `float' and `long double' arguments, respectively.
+-
+-   * Names that begin with `SIG' followed by an uppercase letter are
+-     reserved for additional signal names.  *Note Standard Signals::.
+-
+-   * Names that begin with `SIG_' followed by an uppercase letter are
+-     reserved for additional signal actions.  *Note Basic Signal
+-     Handling::.
+-
+-   * Names beginning with `str', `mem', or `wcs' followed by a
+-     lowercase letter are reserved for additional string and array
+-     functions.  *Note String and Array Utilities::.
+-
+-   * Names that end with `_t' are reserved for additional type names.
+-
+-   In addition, some individual header files reserve names beyond those
+-that they actually define.  You only need to worry about these
+-restrictions if your program includes that particular header file.
+-
+-   * The header file `dirent.h' reserves names prefixed with `d_'.
+-
+-   * The header file `fcntl.h' reserves names prefixed with `l_', `F_',
+-     `O_', and `S_'.
+-
+-   * The header file `grp.h' reserves names prefixed with `gr_'.
+-
+-   * The header file `limits.h' reserves names suffixed with `_MAX'.
+-
+-   * The header file `pwd.h' reserves names prefixed with `pw_'.
+-
+-   * The header file `signal.h' reserves names prefixed with `sa_' and
+-     `SA_'.
+-
+-   * The header file `sys/stat.h' reserves names prefixed with `st_'
+-     and `S_'.
+-
+-   * The header file `sys/times.h' reserves names prefixed with `tms_'.
+-
+-   * The header file `termios.h' reserves names prefixed with `c_',
+-     `V', `I', `O', and `TC'; and names prefixed with `B' followed by a
+-     digit.
+-
+-
+-File: libc.info,  Node: Feature Test Macros,  Prev: Reserved Names,  Up: 
Using the Library
+-
+-Feature Test Macros
+--------------------
+-
+-   The exact set of features available when you compile a source file
+-is controlled by which "feature test macros" you define.
+-
+-   If you compile your programs using `gcc -ansi', you get only the
+-ISO C library features, unless you explicitly request additional
+-features by defining one or more of the feature macros.  *Note GNU CC
+-Command Options: (gcc.info)Invoking GCC, for more information about GCC
+-options.
+-
+-   You should define these macros by using `#define' preprocessor
+-directives at the top of your source code files.  These directives
+-*must* come before any `#include' of a system header file.  It is best
+-to make them the very first thing in the file, preceded only by
+-comments.  You could also use the `-D' option to GCC, but it's better
+-if you make the source files indicate their own meaning in a
+-self-contained way.
+-
+- - Macro: _POSIX_SOURCE
+-     If you define this macro, then the functionality from the POSIX.1
+-     standard (IEEE Standard 1003.1) is available, as well as all of the
+-     ISO C facilities.
+-
+- - Macro: _POSIX_C_SOURCE
+-     If you define this macro with a value of `1', then the
+-     functionality from the POSIX.1 standard (IEEE Standard 1003.1) is
+-     made available.  If you define this macro with a value of `2',
+-     then both the functionality from the POSIX.1 standard and the
+-     functionality from the POSIX.2 standard (IEEE Standard 1003.2) are
+-     made available.  This is in addition to the ISO C facilities.
+-
+- - Macro: _BSD_SOURCE
+-     If you define this macro, functionality derived from 4.3 BSD Unix
+-     is included as well as the ISO C, POSIX.1, and POSIX.2 material.
+-
+-     Some of the features derived from 4.3 BSD Unix conflict with the
+-     corresponding features specified by the POSIX.1 standard.  If this
+-     macro is defined, the 4.3 BSD definitions take precedence over the
+-     POSIX definitions.
+-
+-     Due to the nature of some of the conflicts between 4.3 BSD and
+-     POSIX.1, you need to use a special "BSD compatibility library"
+-     when linking programs compiled for BSD compatibility.  This is
+-     because some functions must be defined in two different ways, one
+-     of them in the normal C library, and one of them in the
+-     compatibility library.  If your program defines `_BSD_SOURCE', you
+-     must give the option `-lbsd-compat' to the compiler or linker when
+-     linking the program, to tell it to find functions in this special
+-     compatibility library before looking for them in the normal C
+-     library.
+-
+- - Macro: _SVID_SOURCE
+-     If you define this macro, functionality derived from SVID is
+-     included as well as the ISO C, POSIX.1, POSIX.2, and X/Open
+-     material.
+-
+- - Macro: _XOPEN_SOURCE
+-     If you define this macro, functionality described in the X/Open
+-     Portability Guide is included.  This is a superset of the POSIX.1
+-     and POSIX.2 functionality and in fact `_POSIX_SOURCE' and
+-     `_POSIX_C_SOURCE' are automatically defined.
+-
+-     As the unification of all Unices, functionality only available in
+-     BSD and SVID is also included.
+-
+-     If the macro `_XOPEN_SOURCE_EXTENDED' is also defined, even more
+-     functionality is available.  The extra functions will make all
+-     functions available which are necessary for the X/Open Unix brand.
+-
+- - Macro: _GNU_SOURCE
+-     If you define this macro, everything is included: ISO C, POSIX.1,
+-     POSIX.2, BSD, SVID, X/Open, and GNU extensions.  In the cases where
+-     POSIX.1 conflicts with BSD, the POSIX definitions take precedence.
+-
+-     If you want to get the full effect of `_GNU_SOURCE' but make the
+-     BSD definitions take precedence over the POSIX definitions, use
+-     this sequence of definitions:
+-
+-          #define _GNU_SOURCE
+-          #define _BSD_SOURCE
+-          #define _SVID_SOURCE
+-
+-     Note that if you do this, you must link your program with the BSD
+-     compatibility library by passing the `-lbsd-compat' option to the
+-     compiler or linker.  *Note:* If you forget to do this, you may get
+-     very strange errors at run time.
+-
+- - Macro: _REENTRANT
+- - Macro: _THREAD_SAFE
+-     If you define one of these macros, reentrant versions of several
+-     functions get declared.  Some of the functions are specified in
+-     POSIX.1c but many others are only available on a few other systems
+-     or are unique to GNU libc.  The problem is that the
+-     standardization of the thread safe C library interface still is
+-     behind.
+-
+-     Unlike on some other systems no special version of the C library
+-     must be used for linking.  There is only one version but while
+-     compiling this it must have been specified to compile as thread
+-     safe.
+-
+-   We recommend you use `_GNU_SOURCE' in new programs.  If you don't
+-specify the `-ansi' option to GCC and don't define any of these macros
+-explicitly, the effect is the same as defining `_POSIX_C_SOURCE' to 2
+-and `_POSIX_SOURCE', `_SVID_SOURCE', and `_BSD_SOURCE' to 1.
+-
+-   When you define a feature test macro to request a larger class of
+-features, it is harmless to define in addition a feature test macro for
+-a subset of those features.  For example, if you define
+-`_POSIX_C_SOURCE', then defining `_POSIX_SOURCE' as well has no effect.
+-Likewise, if you define `_GNU_SOURCE', then defining either
+-`_POSIX_SOURCE' or `_POSIX_C_SOURCE' or `_SVID_SOURCE' as well has no
+-effect.
+-
+-   Note, however, that the features of `_BSD_SOURCE' are not a subset of
+-any of the other feature test macros supported.  This is because it
+-defines BSD features that take precedence over the POSIX features that
+-are requested by the other macros.  For this reason, defining
+-`_BSD_SOURCE' in addition to the other feature test macros does have an
+-effect: it causes the BSD features to take priority over the conflicting
+-POSIX features.
+-
+-
+-File: libc.info,  Node: Roadmap to the Manual,  Prev: Using the Library,  Up: 
Introduction
+-
+-Roadmap to the Manual
+-=====================
+-
+-   Here is an overview of the contents of the remaining chapters of
+-this manual.
+-
+-   * *Note Error Reporting::, describes how errors detected by the
+-     library are reported.
+-
+-   * *Note Language Features::, contains information about library
+-     support for standard parts of the C language, including things
+-     like the `sizeof' operator and the symbolic constant `NULL', how
+-     to write functions accepting variable numbers of arguments, and
+-     constants describing the ranges and other properties of the
+-     numerical types.  There is also a simple debugging mechanism which
+-     allows you to put assertions in your code, and have diagnostic
+-     messages printed if the tests fail.
+-
+-   * *Note Memory Allocation::, describes the GNU library's facilities
+-     for dynamic allocation of storage.  If you do not know in advance
+-     how much storage your program needs, you can allocate it
+-     dynamically instead, and manipulate it via pointers.
+-
+-   * *Note Character Handling::, contains information about character
+-     classification functions (such as `isspace') and functions for
+-     performing case conversion.
+-
+-   * *Note String and Array Utilities::, has descriptions of functions
+-     for manipulating strings (null-terminated character arrays) and
+-     general byte arrays, including operations such as copying and
+-     comparison.
+-
+-   * *Note I/O Overview::, gives an overall look at the input and output
+-     facilities in the library, and contains information about basic
+-     concepts such as file names.
+-
+-   * *Note I/O on Streams::, describes I/O operations involving streams
+-     (or `FILE *' objects).  These are the normal C library functions
+-     from `stdio.h'.
+-
+-   * *Note Low-Level I/O::, contains information about I/O operations
+-     on file descriptors.  File descriptors are a lower-level mechanism
+-     specific to the Unix family of operating systems.
+-
+-   * *Note File System Interface::, has descriptions of operations on
+-     entire files, such as functions for deleting and renaming them and
+-     for creating new directories.  This chapter also contains
+-     information about how you can access the attributes of a file,
+-     such as its owner and file protection modes.
+-
+-   * *Note Pipes and FIFOs::, contains information about simple
+-     interprocess communication mechanisms.  Pipes allow communication
+-     between two related processes (such as between a parent and
+-     child), while FIFOs allow communication between processes sharing
+-     a common file system on the same machine.
+-
+-   * *Note Sockets::, describes a more complicated interprocess
+-     communication mechanism that allows processes running on different
+-     machines to communicate over a network.  This chapter also
+-     contains information about Internet host addressing and how to use
+-     the system network databases.
+-
+-   * *Note Low-Level Terminal Interface::, describes how you can change
+-     the attributes of a terminal device.  If you want to disable echo
+-     of characters typed by the user, for example, read this chapter.
+-
+-   * *Note Mathematics::, contains information about the math library
+-     functions.  These include things like random-number generators and
+-     remainder functions on integers as well as the usual trigonometric
+-     and exponential functions on floating-point numbers.
+-
+-   * *Note Low-Level Arithmetic Functions: Arithmetic, describes
+-     functions for simple arithmetic, analysis of floating-point
+-     values, and reading numbers from strings.
+-
+-   * *Note Searching and Sorting::, contains information about functions
+-     for searching and sorting arrays.  You can use these functions on
+-     any kind of array by providing an appropriate comparison function.
+-
+-   * *Note Pattern Matching::, presents functions for matching regular
+-     expressions and shell file name patterns, and for expanding words
+-     as the shell does.
+-
+-   * *Note Date and Time::, describes functions for measuring both
+-     calendar time and CPU time, as well as functions for setting
+-     alarms and timers.
+-
+-   * *Note Extended Characters::, contains information about
+-     manipulating characters and strings using character sets larger
+-     than will fit in the usual `char' data type.
+-
+-   * *Note Locales::, describes how selecting a particular country or
+-     language affects the behavior of the library.  For example, the
+-     locale affects collation sequences for strings and how monetary
+-     values are formatted.
+-
+-   * *Note Non-Local Exits::, contains descriptions of the `setjmp' and
+-     `longjmp' functions.  These functions provide a facility for
+-     `goto'-like jumps which can jump from one function to another.
+-
+-   * *Note Signal Handling::, tells you all about signals--what they
+-     are, how to establish a handler that is called when a particular
+-     kind of signal is delivered, and how to prevent signals from
+-     arriving during critical sections of your program.
+-
+-   * *Note Process Startup::, tells how your programs can access their
+-     command-line arguments and environment variables.
+-
+-   * *Note Processes::, contains information about how to start new
+-     processes and run programs.
+-
+-   * *Note Job Control::, describes functions for manipulating process
+-     groups and the controlling terminal.  This material is probably
+-     only of interest if you are writing a shell or other program which
+-     handles job control specially.
+-
+-   * *Note Name Service Switch::, describes the services which are
+-     available for looking up names in the system databases, how to
+-     determine which service is used for which database, and how these
+-     services are implemented so that contributors can design their own
+-     services.
+-
+-   * *Note User Database::, and *Note Group Database::, tell you how to
+-     access the system user and group databases.
+-
+-   * *Note System Information::, describes functions for getting
+-     information about the hardware and software configuration your
+-     program is executing under.
+-
+-   * *Note System Configuration::, tells you how you can get
+-     information about various operating system limits.  Most of these
+-     parameters are provided for compatibility with POSIX.
+-
+-   * *Note Library Summary::, gives a summary of all the functions,
+-     variables, and macros in the library, with complete data types and
+-     function prototypes, and says what standard or system each is
+-     derived from.
+-
+-   * *Note Maintenance::, explains how to build and install the GNU C
+-     library on your system, how to report any bugs you might find, and
+-     how to add new functions or port the library to a new system.
+-
+-   If you already know the name of the facility you are interested in,
+-you can look it up in *Note Library Summary::.  This gives you a
+-summary of its syntax and a pointer to where you can find a more
+-detailed description.  This appendix is particularly useful if you just
+-want to verify the order and type of arguments to a function, for
+-example.  It also tells you what standard or system each function,
+-variable, or macro is derived from.
+-
+-
+-File: libc.info,  Node: Error Reporting,  Next: Memory Allocation,  Prev: 
Introduction,  Up: Top
+-
+-Error Reporting
+-***************
+-
+-   Many functions in the GNU C library detect and report error
+-conditions, and sometimes your programs need to check for these error
+-conditions.  For example, when you open an input file, you should
+-verify that the file was actually opened correctly, and print an error
+-message or take other appropriate action if the call to the library
+-function failed.
+-
+-   This chapter describes how the error reporting facility works.  Your
+-program should include the header file `errno.h' to use this facility.
+-
+-* Menu:
+-
+-* Checking for Errors::         How errors are reported by library functions.
+-* Error Codes::                 Error code macros; all of these expand
+-                                 into integer constant values.
+-* Error Messages::              Mapping error codes onto error messages.
+-
+-
+-File: libc.info,  Node: Checking for Errors,  Next: Error Codes,  Up: Error 
Reporting
+-
+-Checking for Errors
+-===================
+-
+-   Most library functions return a special value to indicate that they
+-have failed.  The special value is typically `-1', a null pointer, or a
+-constant such as `EOF' that is defined for that purpose.  But this
+-return value tells you only that an error has occurred.  To find out
+-what kind of error it was, you need to look at the error code stored in
+-the variable `errno'.  This variable is declared in the header file
+-`errno.h'.
+-
+- - Variable: volatile int errno
+-     The variable `errno' contains the system error number.  You can
+-     change the value of `errno'.
+-
+-     Since `errno' is declared `volatile', it might be changed
+-     asynchronously by a signal handler; see *Note Defining Handlers::.
+-     However, a properly written signal handler saves and restores the
+-     value of `errno', so you generally do not need to worry about this
+-     possibility except when writing signal handlers.
+-
+-     The initial value of `errno' at program startup is zero.  Many
+-     library functions are guaranteed to set it to certain nonzero
+-     values when they encounter certain kinds of errors.  These error
+-     conditions are listed for each function.  These functions do not
+-     change `errno' when they succeed; thus, the value of `errno' after
+-     a successful call is not necessarily zero, and you should not use
+-     `errno' to determine *whether* a call failed.  The proper way to
+-     do that is documented for each function.  *If* the call the
+-     failed, you can examine `errno'.
+-
+-     Many library functions can set `errno' to a nonzero value as a
+-     result of calling other library functions which might fail.  You
+-     should assume that any library function might alter `errno' when
+-     the function returns an error.
+-
+-     *Portability Note:* ISO C specifies `errno' as a "modifiable
+-     lvalue" rather than as a variable, permitting it to be implemented
+-     as a macro.  For example, its expansion might involve a function
+-     call, like `*_errno ()'.  In fact, that is what it is on the GNU
+-     system itself.  The GNU library, on non-GNU systems, does whatever
+-     is right for the particular system.
+-
+-     There are a few library functions, like `sqrt' and `atan', that
+-     return a perfectly legitimate value in case of an error, but also
+-     set `errno'.  For these functions, if you want to check to see
+-     whether an error occurred, the recommended method is to set `errno'
+-     to zero before calling the function, and then check its value
+-     afterward.
+-
+-   All the error codes have symbolic names; they are macros defined in
+-`errno.h'.  The names start with `E' and an upper-case letter or digit;
+-you should consider names of this form to be reserved names.  *Note
+-Reserved Names::.
+-
+-   The error code values are all positive integers and are all distinct,
+-with one exception: `EWOULDBLOCK' and `EAGAIN' are the same.  Since the
+-values are distinct, you can use them as labels in a `switch'
+-statement; just don't use both `EWOULDBLOCK' and `EAGAIN'.  Your
+-program should not make any other assumptions about the specific values
+-of these symbolic constants.
+-
+-   The value of `errno' doesn't necessarily have to correspond to any
+-of these macros, since some library functions might return other error
+-codes of their own for other situations.  The only values that are
+-guaranteed to be meaningful for a particular library function are the
+-ones that this manual lists for that function.
+-
+-   On non-GNU systems, almost any system call can return `EFAULT' if it
+-is given an invalid pointer as an argument.  Since this could only
+-happen as a result of a bug in your program, and since it will not
+-happen on the GNU system, we have saved space by not mentioning
+-`EFAULT' in the descriptions of individual functions.
+-
+-   In some Unix systems, many system calls can also return `EFAULT' if
+-given as an argument a pointer into the stack, and the kernel for some
+-obscure reason fails in its attempt to extend the stack.  If this ever
+-happens, you should probably try using statically or dynamically
+-allocated memory instead of stack memory on that system.
+-
+-
+-File: libc.info,  Node: Error Codes,  Next: Error Messages,  Prev: Checking 
for Errors,  Up: Error Reporting
+-
+-Error Codes
+-===========
+-
+-   The error code macros are defined in the header file `errno.h'.  All
+-of them expand into integer constant values.  Some of these error codes
+-can't occur on the GNU system, but they can occur using the GNU library
+-on other systems.
+-
+- - Macro: int EPERM
+-     Operation not permitted; only the owner of the file (or other
+-     resource) or processes with special privileges can perform the
+-     operation.
+-
+- - Macro: int ENOENT
+-     No such file or directory.  This is a "file doesn't exist" error
+-     for ordinary files that are referenced in contexts where they are
+-     expected to already exist.
+-
+- - Macro: int ESRCH
+-     No process matches the specified process ID.
+-
+- - Macro: int EINTR
+-     Interrupted function call; an asynchronous signal occurred and
+-     prevented completion of the call.  When this happens, you should
+-     try the call again.
+-
+-     You can choose to have functions resume after a signal that is
+-     handled, rather than failing with `EINTR'; see *Note Interrupted
+-     Primitives::.
+-
+- - Macro: int EIO
+-     Input/output error; usually used for physical read or write errors.
+-
+- - Macro: int ENXIO
+-     No such device or address.  The system tried to use the device
+-     represented by a file you specified, and it couldn't find the
+-     device.  This can mean that the device file was installed
+-     incorrectly, or that the physical device is missing or not
+-     correctly attached to the computer.
+-
+- - Macro: int E2BIG
+-     Argument list too long; used when the arguments passed to a new
+-     program being executed with one of the `exec' functions (*note
+-     Executing a File::.) occupy too much memory space.  This condition
+-     never arises in the GNU system.
+-
+- - Macro: int ENOEXEC
+-     Invalid executable file format.  This condition is detected by the
+-     `exec' functions; see *Note Executing a File::.
+-
+- - Macro: int EBADF
+-     Bad file descriptor; for example, I/O on a descriptor that has been
+-     closed or reading from a descriptor open only for writing (or vice
+-     versa).
+-
+- - Macro: int ECHILD
+-     There are no child processes.  This error happens on operations
+-     that are supposed to manipulate child processes, when there aren't
+-     any processes to manipulate.
+-
+- - Macro: int EDEADLK
+-     Deadlock avoided; allocating a system resource would have resulted
+-     in a deadlock situation.  The system does not guarantee that it
+-     will notice all such situations.  This error means you got lucky
+-     and the system noticed; it might just hang.  *Note File Locks::,
+-     for an example.
+-
+- - Macro: int ENOMEM
+-     No memory available.  The system cannot allocate more virtual
+-     memory because its capacity is full.
+-
+- - Macro: int EACCES
+-     Permission denied; the file permissions do not allow the attempted
+-     operation.
+-
+- - Macro: int EFAULT
+-     Bad address; an invalid pointer was detected.  In the GNU system,
+-     this error never happens; you get a signal instead.
+-
+- - Macro: int ENOTBLK
+-     A file that isn't a block special file was given in a situation
+-     that requires one.  For example, trying to mount an ordinary file
+-     as a file system in Unix gives this error.
+-
+- - Macro: int EBUSY
+-     Resource busy; a system resource that can't be shared is already
+-     in use.  For example, if you try to delete a file that is the root
+-     of a currently mounted filesystem, you get this error.
+-
+- - Macro: int EEXIST
+-     File exists; an existing file was specified in a context where it
+-     only makes sense to specify a new file.
+-
+- - Macro: int EXDEV
+-     An attempt to make an improper link across file systems was
+-     detected.  This happens not only when you use `link' (*note Hard
+-     Links::.) but also when you rename a file with `rename' (*note
+-     Renaming Files::.).
+-
+- - Macro: int ENODEV
+-     The wrong type of device was given to a function that expects a
+-     particular sort of device.
+-
+- - Macro: int ENOTDIR
+-     A file that isn't a directory was specified when a directory is
+-     required.
+-
+- - Macro: int EISDIR
+-     File is a directory; you cannot open a directory for writing, or
+-     create or remove hard links to it.
+-
+- - Macro: int EINVAL
+-     Invalid argument.  This is used to indicate various kinds of
+-     problems with passing the wrong argument to a library function.
+-
+- - Macro: int EMFILE
+-     The current process has too many files open and can't open any
+-     more.  Duplicate descriptors do count toward this limit.
+-
+-     In BSD and GNU, the number of open files is controlled by a
+-     resource limit that can usually be increased.  If you get this
+-     error, you might want to increase the `RLIMIT_NOFILE' limit or
+-     make it unlimited; *note Limits on Resources::..
+-
+- - Macro: int ENFILE
+-     There are too many distinct file openings in the entire system.
+-     Note that any number of linked channels count as just one file
+-     opening; see *Note Linked Channels::.  This error never occurs in
+-     the GNU system.
+-
+- - Macro: int ENOTTY
+-     Inappropriate I/O control operation, such as trying to set terminal
+-     modes on an ordinary file.
+-
+- - Macro: int ETXTBSY
+-     An attempt to execute a file that is currently open for writing, or
+-     write to a file that is currently being executed.  Often using a
+-     debugger to run a program is considered having it open for writing
+-     and will cause this error.  (The name stands for "text file
+-     busy".)  This is not an error in the GNU system; the text is
+-     copied as necessary.
+-
+- - Macro: int EFBIG
+-     File too big; the size of a file would be larger than allowed by
+-     the system.
+-
+- - Macro: int ENOSPC
+-     No space left on device; write operation on a file failed because
+-     the disk is full.
+-
+- - Macro: int ESPIPE
+-     Invalid seek operation (such as on a pipe).
+-
+- - Macro: int EROFS
+-     An attempt was made to modify something on a read-only file system.
+-
+- - Macro: int EMLINK
+-     Too many links; the link count of a single file would become too
+-     large.  `rename' can cause this error if the file being renamed
+-     already has as many links as it can take (*note Renaming Files::.).
+-
+- - Macro: int EPIPE
+-     Broken pipe; there is no process reading from the other end of a
+-     pipe.  Every library function that returns this error code also
+-     generates a `SIGPIPE' signal; this signal terminates the program
+-     if not handled or blocked.  Thus, your program will never actually
+-     see `EPIPE' unless it has handled or blocked `SIGPIPE'.
+-
+- - Macro: int EDOM
+-     Domain error; used by mathematical functions when an argument
+-     value does not fall into the domain over which the function is
+-     defined.
+-
+- - Macro: int ERANGE
+-     Range error; used by mathematical functions when the result value
+-     is not representable because of overflow or underflow.
+-
+- - Macro: int EAGAIN
+-     Resource temporarily unavailable; the call might work if you try
+-     again later.  The macro `EWOULDBLOCK' is another name for `EAGAIN';
+-     they are always the same in the GNU C library.
+-
+-     This error can happen in a few different situations:
+-
+-        * An operation that would block was attempted on an object that
+-          has non-blocking mode selected.  Trying the same operation
+-          again will block until some external condition makes it
+-          possible to read, write, or connect (whatever the operation).
+-          You can use `select' to find out when the operation will be
+-          possible; *note Waiting for I/O::..
+-
+-          *Portability Note:* In older Unix many systems, this condition
+-          was indicated by `EWOULDBLOCK', which was a distinct error
+-          code different from `EAGAIN'.  To make your program portable,
+-          you should check for both codes and treat them the same.
+-
+-        * A temporary resource shortage made an operation impossible.
+-          `fork' can return this error.  It indicates that the shortage
+-          is expected to pass, so your program can try the call again
+-          later and it may succeed.  It is probably a good idea to
+-          delay for a few seconds before trying it again, to allow time
+-          for other processes to release scarce resources.  Such
+-          shortages are usually fairly serious and affect the whole
+-          system, so usually an interactive program should report the
+-          error to the user and return to its command loop.
+-
+- - Macro: int EWOULDBLOCK
+-     In the GNU C library, this is another name for `EAGAIN' (above).
+-     The values are always the same, on every operating system.
+-
+-     C libraries in many older Unix systems have `EWOULDBLOCK' as a
+-     separate error code.
+-
+- - Macro: int EINPROGRESS
+-     An operation that cannot complete immediately was initiated on an
+-     object that has non-blocking mode selected.  Some functions that
+-     must always block (such as `connect'; *note Connecting::.) never
+-     return `EAGAIN'.  Instead, they return `EINPROGRESS' to indicate
+-     that the operation has begun and will take some time.  Attempts to
+-     manipulate the object before the call completes return `EALREADY'.
+-     You can use the `select' function to find out when the pending
+-     operation has completed; *note Waiting for I/O::..
+-
+- - Macro: int EALREADY
+-     An operation is already in progress on an object that has
+-     non-blocking mode selected.
+-
+- - Macro: int ENOTSOCK
+-     A file that isn't a socket was specified when a socket is required.
+-
+- - Macro: int EMSGSIZE
+-     The size of a message sent on a socket was larger than the
+-     supported maximum size.
+-
+- - Macro: int EPROTOTYPE
+-     The socket type does not support the requested communications
+-     protocol.
+-
+- - Macro: int ENOPROTOOPT
+-     You specified a socket option that doesn't make sense for the
+-     particular protocol being used by the socket.  *Note Socket
+-     Options::.
+-
+- - Macro: int EPROTONOSUPPORT
+-     The socket domain does not support the requested communications
+-     protocol (perhaps because the requested protocol is completely
+-     invalid.) *Note Creating a Socket::.
+-
+- - Macro: int ESOCKTNOSUPPORT
+-     The socket type is not supported.
+-
+- - Macro: int EOPNOTSUPP
+-     The operation you requested is not supported.  Some socket
+-     functions don't make sense for all types of sockets, and others
+-     may not be implemented for all communications protocols.  In the
+-     GNU system, this error can happen for many calls when the object
+-     does not support the particular operation; it is a generic
+-     indication that the server knows nothing to do for that call.
+-
+- - Macro: int EPFNOSUPPORT
+-     The socket communications protocol family you requested is not
+-     supported.
+-
+- - Macro: int EAFNOSUPPORT
+-     The address family specified for a socket is not supported; it is
+-     inconsistent with the protocol being used on the socket.  *Note
+-     Sockets::.
+-
+- - Macro: int EADDRINUSE
+-     The requested socket address is already in use.  *Note Socket
+-     Addresses::.
+-
+- - Macro: int EADDRNOTAVAIL
+-     The requested socket address is not available; for example, you
+-     tried to give a socket a name that doesn't match the local host
+-     name.  *Note Socket Addresses::.
+-
+- - Macro: int ENETDOWN
+-     A socket operation failed because the network was down.
+-
+- - Macro: int ENETUNREACH
+-     A socket operation failed because the subnet containing the remote
+-     host was unreachable.
+-
+- - Macro: int ENETRESET
+-     A network connection was reset because the remote host crashed.
+-
+- - Macro: int ECONNABORTED
+-     A network connection was aborted locally.
+-
+- - Macro: int ECONNRESET
+-     A network connection was closed for reasons outside the control of
+-     the local host, such as by the remote machine rebooting or an
+-     unrecoverable protocol violation.
+-
+- - Macro: int ENOBUFS
+-     The kernel's buffers for I/O operations are all in use.  In GNU,
+-     this error is always synonymous with `ENOMEM'; you may get one or
+-     the other from network operations.
+-
+- - Macro: int EISCONN
+-     You tried to connect a socket that is already connected.  *Note
+-     Connecting::.
+-
+- - Macro: int ENOTCONN
+-     The socket is not connected to anything.  You get this error when
+-     you try to transmit data over a socket, without first specifying a
+-     destination for the data.  For a connectionless socket (for
+-     datagram protocols, such as UDP), you get `EDESTADDRREQ' instead.
+-
+- - Macro: int EDESTADDRREQ
+-     No default destination address was set for the socket.  You get
+-     this error when you try to transmit data over a connectionless
+-     socket, without first specifying a destination for the data with
+-     `connect'.
+-
+- - Macro: int ESHUTDOWN
+-     The socket has already been shut down.
+-
+- - Macro: int ETOOMANYREFS
+-     ???
+-
+- - Macro: int ETIMEDOUT
+-     A socket operation with a specified timeout received no response
+-     during the timeout period.
+-
+- - Macro: int ECONNREFUSED
+-     A remote host refused to allow the network connection (typically
+-     because it is not running the requested service).
+-
+- - Macro: int ELOOP
+-     Too many levels of symbolic links were encountered in looking up a
+-     file name.  This often indicates a cycle of symbolic links.
+-
+- - Macro: int ENAMETOOLONG
+-     Filename too long (longer than `PATH_MAX'; *note Limits for
+-     Files::.) or host name too long (in `gethostname' or
+-     `sethostname'; *note Host Identification::.).
+-
+- - Macro: int EHOSTDOWN
+-     The remote host for a requested network connection is down.
+-
+- - Macro: int EHOSTUNREACH
+-     The remote host for a requested network connection is not
+-     reachable.
+-
+- - Macro: int ENOTEMPTY
+-     Directory not empty, where an empty directory was expected.
+-     Typically, this error occurs when you are trying to delete a
+-     directory.
+-
+- - Macro: int EPROCLIM
+-     This means that the per-user limit on new process would be
+-     exceeded by an attempted `fork'.  *Note Limits on Resources::, for
+-     details on the `RLIMIT_NPROC' limit.
+-
+- - Macro: int EUSERS
+-     The file quota system is confused because there are too many users.
+-
+- - Macro: int EDQUOT
+-     The user's disk quota was exceeded.
+-
+- - Macro: int ESTALE
+-     Stale NFS file handle.  This indicates an internal confusion in
+-     the NFS system which is due to file system rearrangements on the
+-     server host.  Repairing this condition usually requires unmounting
+-     and remounting the NFS file system on the local host.
+-
+- - Macro: int EREMOTE
+-     An attempt was made to NFS-mount a remote file system with a file
+-     name that already specifies an NFS-mounted file.  (This is an
+-     error on some operating systems, but we expect it to work properly
+-     on the GNU system, making this error code impossible.)
+-
+- - Macro: int EBADRPC
+-     ???
+-
+- - Macro: int ERPCMISMATCH
+-     ???
+-
+- - Macro: int EPROGUNAVAIL
+-     ???
+-
+- - Macro: int EPROGMISMATCH
+-     ???
+-
+- - Macro: int EPROCUNAVAIL
+-     ???
+-
+- - Macro: int ENOLCK
+-     No locks available.  This is used by the file locking facilities;
+-     see *Note File Locks::.  This error is never generated by the GNU
+-     system, but it can result from an operation to an NFS server
+-     running another operating system.
+-
+- - Macro: int EFTYPE
+-     Inappropriate file type or format.  The file was the wrong type
+-     for the operation, or a data file had the wrong format.
+-
+-     On some systems `chmod' returns this error if you try to set the
+-     sticky bit on a non-directory file; *note Setting Permissions::..
+-
+- - Macro: int EAUTH
+-     ???
+-
+- - Macro: int ENEEDAUTH
+-     ???
+-
+- - Macro: int ENOSYS
+-     Function not implemented.  Some functions have commands or options
+-     defined that might not be supported in all implementations, and
+-     this is the kind of error you get if you request them and they are
+-     not supported.
+-
+- - Macro: int EILSEQ
+-     While decoding a multibyte character the function came along an
+-     invalid or an incomplete sequence of bytes or the given wide
+-     character is invalid.
+-
+- - Macro: int EBACKGROUND
+-     In the GNU system, servers supporting the `term' protocol return
+-     this error for certain operations when the caller is not in the
+-     foreground process group of the terminal.  Users do not usually
+-     see this error because functions such as `read' and `write'
+-     translate it into a `SIGTTIN' or `SIGTTOU' signal.  *Note Job
+-     Control::, for information on process groups and these signals.
+-
+- - Macro: int EDIED
+-     In the GNU system, opening a file returns this error when the file
+-     is translated by a program and the translator program dies while
+-     starting up, before it has connected to the file.
+-
+- - Macro: int ED
+-     The experienced user will know what is wrong.
+-
+- - Macro: int EGREGIOUS
+-     You did *what*?
+-
+- - Macro: int EIEIO
+-     Go home and have a glass of warm, dairy-fresh milk.
+-
+- - Macro: int EGRATUITOUS
+-     This error code has no purpose.
+-
+- - Macro: int EBADMSG
+-
+- - Macro: int EIDRM
+-
+- - Macro: int EMULTIHOP
+-
+- - Macro: int ENODATA
+-
+- - Macro: int ENOLINK
+-
+- - Macro: int ENOMSG
+-
+- - Macro: int ENOSR
+-
+- - Macro: int ENOSTR
+-
+- - Macro: int EOVERFLOW
+-
+- - Macro: int EPROTO
+-
+- - Macro: int ETIME
+-
+-   *The following error codes are defined by the Linux/i386 kernel.
+-They are not yet documented.*
+-
+- - Macro: int ERESTART
+-
+- - Macro: int ECHRNG
+-
+- - Macro: int EL2NSYNC
+-
+- - Macro: int EL3HLT
+-
+- - Macro: int EL3RST
+-
+- - Macro: int ELNRNG
+-
+- - Macro: int EUNATCH
+-
+- - Macro: int ENOCSI
+-
+- - Macro: int EL2HLT
+-
+- - Macro: int EBADE
+-
+- - Macro: int EBADR
+-
+- - Macro: int EXFULL
+-
+- - Macro: int ENOANO
+-
+- - Macro: int EBADRQC
+-
+- - Macro: int EBADSLT
+-
+- - Macro: int EDEADLOCK
+-
+- - Macro: int EBFONT
+-
+- - Macro: int ENONET
+-
+- - Macro: int ENOPKG
+-
+- - Macro: int EADV
+-
+- - Macro: int ESRMNT
+-
+- - Macro: int ECOMM
+-
+- - Macro: int EDOTDOT
+-
+- - Macro: int ENOTUNIQ
+-
+- - Macro: int EBADFD
+-
+- - Macro: int EREMCHG
+-
+- - Macro: int ELIBACC
+-
+- - Macro: int ELIBBAD
+-
+- - Macro: int ELIBSCN
+-
+- - Macro: int ELIBMAX
+-
+- - Macro: int ELIBEXEC
+-
+- - Macro: int ESTRPIPE
+-
+- - Macro: int EUCLEAN
+-
+- - Macro: int ENOTNAM
+-
+- - Macro: int ENAVAIL
+-
+- - Macro: int EISNAM
+-
+- - Macro: int EREMOTEIO
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-20 
glibc-2.0.1/manual/libc.info-20
+--- ../glibc-2.0.1/manual/libc.info-20 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-20    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1220 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Standard Signals,  Next: Signal Actions,  Prev: 
Concepts of Signals,  Up: Signal Handling
+-
+-Standard Signals
+-================
+-
+-   This section lists the names for various standard kinds of signals
+-and describes what kind of event they mean.  Each signal name is a macro
+-which stands for a positive integer--the "signal number" for that kind
+-of signal.  Your programs should never make assumptions about the
+-numeric code for a particular kind of signal, but rather refer to them
+-always by the names defined here.  This is because the number for a
+-given kind of signal can vary from system to system, but the meanings of
+-the names are standardized and fairly uniform.
+-
+-   The signal names are defined in the header file `signal.h'.
+-
+- - Macro: int NSIG
+-     The value of this symbolic constant is the total number of signals
+-     defined.  Since the signal numbers are allocated consecutively,
+-     `NSIG' is also one greater than the largest defined signal number.
+-
+-* Menu:
+-
+-* Program Error Signals::       Used to report serious program errors.
+-* Termination Signals::         Used to interrupt and/or terminate the
+-                                 program.
+-* Alarm Signals::               Used to indicate expiration of timers.
+-* Asynchronous I/O Signals::    Used to indicate input is available.
+-* Job Control Signals::         Signals used to support job control.
+-* Operation Error Signals::     Used to report operational system errors.
+-* Miscellaneous Signals::       Miscellaneous Signals.
+-* Signal Messages::             Printing a message describing a signal.
+-
+-
+-File: libc.info,  Node: Program Error Signals,  Next: Termination Signals,  
Up: Standard Signals
+-
+-Program Error Signals
+----------------------
+-
+-   The following signals are generated when a serious program error is
+-detected by the operating system or the computer itself.  In general,
+-all of these signals are indications that your program is seriously
+-broken in some way, and there's usually no way to continue the
+-computation which encountered the error.
+-
+-   Some programs handle program error signals in order to tidy up before
+-terminating; for example, programs that turn off echoing of terminal
+-input should handle program error signals in order to turn echoing back
+-on.  The handler should end by specifying the default action for the
+-signal that happened and then reraising it; this will cause the program
+-to terminate with that signal, as if it had not had a handler.  (*Note
+-Termination in Handler::.)
+-
+-   Termination is the sensible ultimate outcome from a program error in
+-most programs.  However, programming systems such as Lisp that can load
+-compiled user programs might need to keep executing even if a user
+-program incurs an error.  These programs have handlers which use
+-`longjmp' to return control to the command level.
+-
+-   The default action for all of these signals is to cause the process
+-to terminate.  If you block or ignore these signals or establish
+-handlers for them that return normally, your program will probably
+-break horribly when such signals happen, unless they are generated by
+-`raise' or `kill' instead of a real error.
+-
+-   When one of these program error signals terminates a process, it also
+-writes a "core dump file" which records the state of the process at the
+-time of termination.  The core dump file is named `core' and is written
+-in whichever directory is current in the process at the time.  (On the
+-GNU system, you can specify the file name for core dumps with the
+-environment variable `COREFILE'.)  The purpose of core dump files is so
+-that you can examine them with a debugger to investigate what caused
+-the error.
+-
+- - Macro: int SIGFPE
+-     The `SIGFPE' signal reports a fatal arithmetic error.  Although the
+-     name is derived from "floating-point exception", this signal
+-     actually covers all arithmetic errors, including division by zero
+-     and overflow.  If a program stores integer data in a location
+-     which is then used in a floating-point operation, this often
+-     causes an "invalid operation" exception, because the processor
+-     cannot recognize the data as a floating-point number.
+-
+-     Actual floating-point exceptions are a complicated subject because
+-     there are many types of exceptions with subtly different meanings,
+-     and the `SIGFPE' signal doesn't distinguish between them.  The
+-     `IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std
+-     754-1985 and ANSI/IEEE Std 854-1987)' defines various
+-     floating-point exceptions and requires conforming computer systems
+-     to report their occurrences.  However, this standard does not
+-     specify how the exceptions are reported, or what kinds of handling
+-     and control the operating system can offer to the programmer.
+-
+-   BSD systems provide the `SIGFPE' handler with an extra argument that
+-distinguishes various causes of the exception.  In order to access this
+-argument, you must define the handler to accept two arguments, which
+-means you must cast it to a one-argument function type in order to
+-establish the handler.  The GNU library does provide this extra
+-argument, but the value is meaningful only on operating systems that
+-provide the information (BSD systems and GNU systems).
+-
+-`FPE_INTOVF_TRAP'
+-     Integer overflow (impossible in a C program unless you enable
+-     overflow trapping in a hardware-specific fashion).
+-
+-`FPE_INTDIV_TRAP'
+-     Integer division by zero.
+-
+-`FPE_SUBRNG_TRAP'
+-     Subscript-range (something that C programs never check for).
+-
+-`FPE_FLTOVF_TRAP'
+-     Floating overflow trap.
+-
+-`FPE_FLTDIV_TRAP'
+-     Floating/decimal division by zero.
+-
+-`FPE_FLTUND_TRAP'
+-     Floating underflow trap.  (Trapping on floating underflow is not
+-     normally enabled.)
+-
+-`FPE_DECOVF_TRAP'
+-     Decimal overflow trap.  (Only a few machines have decimal
+-     arithmetic and C never uses it.)
+-
+- - Macro: int SIGILL
+-     The name of this signal is derived from "illegal instruction"; it
+-     usually means your program is trying to execute garbage or a
+-     privileged instruction.  Since the C compiler generates only valid
+-     instructions, `SIGILL' typically indicates that the executable
+-     file is corrupted, or that you are trying to execute data.  Some
+-     common ways of getting into the latter situation are by passing an
+-     invalid object where a pointer to a function was expected, or by
+-     writing past the end of an automatic array (or similar problems
+-     with pointers to automatic variables) and corrupting other data on
+-     the stack such as the return address of a stack frame.
+-
+-     `SIGILL' can also be generated when the stack overflows, or when
+-     the system has trouble running the handler for a signal.
+-
+- - Macro: int SIGSEGV
+-     This signal is generated when a program tries to read or write
+-     outside the memory that is allocated for it, or to write memory
+-     that can only be read.  (Actually, the signals only occur when the
+-     program goes far enough outside to be detected by the system's
+-     memory protection mechanism.)  The name is an abbreviation for
+-     "segmentation violation".
+-
+-     Common ways of getting a `SIGSEGV' condition include dereferencing
+-     a null or uninitialized pointer, or when you use a pointer to step
+-     through an array, but fail to check for the end of the array.  It
+-     varies among systems whether dereferencing a null pointer generates
+-     `SIGSEGV' or `SIGBUS'.
+-
+- - Macro: int SIGBUS
+-     This signal is generated when an invalid pointer is dereferenced.
+-     Like `SIGSEGV', this signal is typically the result of
+-     dereferencing an uninitialized pointer.  The difference between
+-     the two is that `SIGSEGV' indicates an invalid access to valid
+-     memory, while `SIGBUS' indicates an access to an invalid address.
+-     In particular, `SIGBUS' signals often result from dereferencing a
+-     misaligned pointer, such as referring to a four-word integer at an
+-     address not divisible by four.  (Each kind of computer has its own
+-     requirements for address alignment.)
+-
+-     The name of this signal is an abbreviation for "bus error".
+-
+- - Macro: int SIGABRT
+-     This signal indicates an error detected by the program itself and
+-     reported by calling `abort'.  *Note Aborting a Program::.
+-
+- - Macro: int SIGIOT
+-     Generated by the PDP-11 "iot" instruction.  On most machines, this
+-     is just another name for `SIGABRT'.
+-
+- - Macro: int SIGTRAP
+-     Generated by the machine's breakpoint instruction, and possibly
+-     other trap instructions.  This signal is used by debuggers.  Your
+-     program will probably only see `SIGTRAP' if it is somehow
+-     executing bad instructions.
+-
+- - Macro: int SIGEMT
+-     Emulator trap; this results from certain unimplemented instructions
+-     which might be emulated in software, or the operating system's
+-     failure to properly emulate them.
+-
+- - Macro: int SIGSYS
+-     Bad system call; that is to say, the instruction to trap to the
+-     operating system was executed, but the code number for the system
+-     call to perform was invalid.
+-
+-
+-File: libc.info,  Node: Termination Signals,  Next: Alarm Signals,  Prev: 
Program Error Signals,  Up: Standard Signals
+-
+-Termination Signals
+--------------------
+-
+-   These signals are all used to tell a process to terminate, in one way
+-or another.  They have different names because they're used for slightly
+-different purposes, and programs might want to handle them differently.
+-
+-   The reason for handling these signals is usually so your program can
+-tidy up as appropriate before actually terminating.  For example, you
+-might want to save state information, delete temporary files, or restore
+-the previous terminal modes.  Such a handler should end by specifying
+-the default action for the signal that happened and then reraising it;
+-this will cause the program to terminate with that signal, as if it had
+-not had a handler.  (*Note Termination in Handler::.)
+-
+-   The (obvious) default action for all of these signals is to cause the
+-process to terminate.
+-
+- - Macro: int SIGTERM
+-     The `SIGTERM' signal is a generic signal used to cause program
+-     termination.  Unlike `SIGKILL', this signal can be blocked,
+-     handled, and ignored.  It is the normal way to politely ask a
+-     program to terminate.
+-
+-     The shell command `kill' generates `SIGTERM' by default.
+-
+- - Macro: int SIGINT
+-     The `SIGINT' ("program interrupt") signal is sent when the user
+-     types the INTR character (normally `C-c').  *Note Special
+-     Characters::, for information about terminal driver support for
+-     `C-c'.
+-
+- - Macro: int SIGQUIT
+-     The `SIGQUIT' signal is similar to `SIGINT', except that it's
+-     controlled by a different key--the QUIT character, usually
+-     `C-\'--and produces a core dump when it terminates the process,
+-     just like a program error signal.  You can think of this as a
+-     program error condition "detected" by the user.
+-
+-     *Note Program Error Signals::, for information about core dumps.
+-     *Note Special Characters::, for information about terminal driver
+-     support.
+-
+-     Certain kinds of cleanups are best omitted in handling `SIGQUIT'.
+-     For example, if the program creates temporary files, it should
+-     handle the other termination requests by deleting the temporary
+-     files.  But it is better for `SIGQUIT' not to delete them, so that
+-     the user can examine them in conjunction with the core dump.
+-
+- - Macro: int SIGKILL
+-     The `SIGKILL' signal is used to cause immediate program
+-     termination.  It cannot be handled or ignored, and is therefore
+-     always fatal.  It is also not possible to block this signal.
+-
+-     This signal is usually generated only by explicit request.  Since
+-     it cannot be handled, you should generate it only as a last
+-     resort, after first trying a less drastic method such as `C-c' or
+-     `SIGTERM'.  If a process does not respond to any other termination
+-     signals, sending it a `SIGKILL' signal will almost always cause it
+-     to go away.
+-
+-     In fact, if `SIGKILL' fails to terminate a process, that by itself
+-     constitutes an operating system bug which you should report.
+-
+-     The system will generate `SIGKILL' for a process itself under some
+-     unusual conditions where the program cannot possible continue to
+-     run (even to run a signal handler).
+-
+- - Macro: int SIGHUP
+-     The `SIGHUP' ("hang-up") signal is used to report that the user's
+-     terminal is disconnected, perhaps because a network or telephone
+-     connection was broken.  For more information about this, see *Note
+-     Control Modes::.
+-
+-     This signal is also used to report the termination of the
+-     controlling process on a terminal to jobs associated with that
+-     session; this termination effectively disconnects all processes in
+-     the session from the controlling terminal.  For more information,
+-     see *Note Termination Internals::.
+-
+-
+-File: libc.info,  Node: Alarm Signals,  Next: Asynchronous I/O Signals,  
Prev: Termination Signals,  Up: Standard Signals
+-
+-Alarm Signals
+--------------
+-
+-   These signals are used to indicate the expiration of timers.  *Note
+-Setting an Alarm::, for information about functions that cause these
+-signals to be sent.
+-
+-   The default behavior for these signals is to cause program
+-termination.  This default is rarely useful, but no other default would
+-be useful; most of the ways of using these signals would require
+-handler functions in any case.
+-
+- - Macro: int SIGALRM
+-     This signal typically indicates expiration of a timer that
+-     measures real or clock time.  It is used by the `alarm' function,
+-     for example.
+-
+- - Macro: int SIGVTALRM
+-     This signal typically indicates expiration of a timer that
+-     measures CPU time used by the current process.  The name is an
+-     abbreviation for "virtual time alarm".
+-
+- - Macro: int SIGPROF
+-     This signal is typically indicates expiration of a timer that
+-     measures both CPU time used by the current process, and CPU time
+-     expended on behalf of the process by the system.  Such a timer is
+-     used to implement code profiling facilities, hence the name of
+-     this signal.
+-
+-
+-File: libc.info,  Node: Asynchronous I/O Signals,  Next: Job Control Signals, 
 Prev: Alarm Signals,  Up: Standard Signals
+-
+-Asynchronous I/O Signals
+-------------------------
+-
+-   The signals listed in this section are used in conjunction with
+-asynchronous I/O facilities.  You have to take explicit action by
+-calling `fcntl' to enable a particular file descriptor to generate
+-these signals (*note Interrupt Input::.).  The default action for these
+-signals is to ignore them.
+-
+- - Macro: int SIGIO
+-     This signal is sent when a file descriptor is ready to perform
+-     input or output.
+-
+-     On most operating systems, terminals and sockets are the only
+-     kinds of files that can generate `SIGIO'; other kinds, including
+-     ordinary files, never generate `SIGIO' even if you ask them to.
+-
+-     In the GNU system `SIGIO' will always be generated properly if you
+-     successfully set asynchronous mode with `fcntl'.
+-
+- - Macro: int SIGURG
+-     This signal is sent when "urgent" or out-of-band data arrives on a
+-     socket.  *Note Out-of-Band Data::.
+-
+- - Macro: int SIGPOLL
+-     This is a System V signal name, more or less similar to `SIGIO'.
+-     It is defined only for compatibility.
+-
+-
+-File: libc.info,  Node: Job Control Signals,  Next: Operation Error Signals,  
Prev: Asynchronous I/O Signals,  Up: Standard Signals
+-
+-Job Control Signals
+--------------------
+-
+-   These signals are used to support job control.  If your system
+-doesn't support job control, then these macros are defined but the
+-signals themselves can't be raised or handled.
+-
+-   You should generally leave these signals alone unless you really
+-understand how job control works.  *Note Job Control::.
+-
+- - Macro: int SIGCHLD
+-     This signal is sent to a parent process whenever one of its child
+-     processes terminates or stops.
+-
+-     The default action for this signal is to ignore it.  If you
+-     establish a handler for this signal while there are child
+-     processes that have terminated but not reported their status via
+-     `wait' or `waitpid' (*note Process Completion::.), whether your
+-     new handler applies to those processes or not depends on the
+-     particular operating system.
+-
+- - Macro: int SIGCLD
+-     This is an obsolete name for `SIGCHLD'.
+-
+- - Macro: int SIGCONT
+-     You can send a `SIGCONT' signal to a process to make it continue.
+-     This signal is special--it always makes the process continue if it
+-     is stopped, before the signal is delivered.  The default behavior
+-     is to do nothing else.  You cannot block this signal.  You can set
+-     a handler, but `SIGCONT' always makes the process continue
+-     regardless.
+-
+-     Most programs have no reason to handle `SIGCONT'; they simply
+-     resume execution without realizing they were ever stopped.  You
+-     can use a handler for `SIGCONT' to make a program do something
+-     special when it is stopped and continued--for example, to reprint
+-     a prompt when it is suspended while waiting for input.
+-
+- - Macro: int SIGSTOP
+-     The `SIGSTOP' signal stops the process.  It cannot be handled,
+-     ignored, or blocked.
+-
+- - Macro: int SIGTSTP
+-     The `SIGTSTP' signal is an interactive stop signal.  Unlike
+-     `SIGSTOP', this signal can be handled and ignored.
+-
+-     Your program should handle this signal if you have a special need
+-     to leave files or system tables in a secure state when a process is
+-     stopped.  For example, programs that turn off echoing should handle
+-     `SIGTSTP' so they can turn echoing back on before stopping.
+-
+-     This signal is generated when the user types the SUSP character
+-     (normally `C-z').  For more information about terminal driver
+-     support, see *Note Special Characters::.
+-
+- - Macro: int SIGTTIN
+-     A process cannot read from the the user's terminal while it is
+-     running as a background job.  When any process in a background job
+-     tries to read from the terminal, all of the processes in the job
+-     are sent a `SIGTTIN' signal.  The default action for this signal
+-     is to stop the process.  For more information about how this
+-     interacts with the terminal driver, see *Note Access to the
+-     Terminal::.
+-
+- - Macro: int SIGTTOU
+-     This is similar to `SIGTTIN', but is generated when a process in a
+-     background job attempts to write to the terminal or set its modes.
+-     Again, the default action is to stop the process.  `SIGTTOU' is
+-     only generated for an attempt to write to the terminal if the
+-     `TOSTOP' output mode is set; *note Output Modes::..
+-
+-   While a process is stopped, no more signals can be delivered to it
+-until it is continued, except `SIGKILL' signals and (obviously)
+-`SIGCONT' signals.  The signals are marked as pending, but not
+-delivered until the process is continued.  The `SIGKILL' signal always
+-causes termination of the process and can't be blocked, handled or
+-ignored.  You can ignore `SIGCONT', but it always causes the process to
+-be continued anyway if it is stopped.  Sending a `SIGCONT' signal to a
+-process causes any pending stop signals for that process to be
+-discarded.  Likewise, any pending `SIGCONT' signals for a process are
+-discarded when it receives a stop signal.
+-
+-   When a process in an orphaned process group (*note Orphaned Process
+-Groups::.) receives a `SIGTSTP', `SIGTTIN', or `SIGTTOU' signal and
+-does not handle it, the process does not stop.  Stopping the process
+-would probably not be very useful, since there is no shell program that
+-will notice it stop and allow the user to continue it.  What happens
+-instead depends on the operating system you are using.  Some systems
+-may do nothing; others may deliver another signal instead, such as
+-`SIGKILL' or `SIGHUP'.  In the GNU system, the process dies with
+-`SIGKILL'; this avoids the problem of many stopped, orphaned processes
+-lying around the system.
+-
+-
+-File: libc.info,  Node: Operation Error Signals,  Next: Miscellaneous 
Signals,  Prev: Job Control Signals,  Up: Standard Signals
+-
+-Operation Error Signals
+------------------------
+-
+-   These signals are used to report various errors generated by an
+-operation done by the program.  They do not necessarily indicate a
+-programming error in the program, but an error that prevents an
+-operating system call from completing.  The default action for all of
+-them is to cause the process to terminate.
+-
+- - Macro: int SIGPIPE
+-     Broken pipe.  If you use pipes or FIFOs, you have to design your
+-     application so that one process opens the pipe for reading before
+-     another starts writing.  If the reading process never starts, or
+-     terminates unexpectedly, writing to the pipe or FIFO raises a
+-     `SIGPIPE' signal.  If `SIGPIPE' is blocked, handled or ignored,
+-     the offending call fails with `EPIPE' instead.
+-
+-     Pipes and FIFO special files are discussed in more detail in *Note
+-     Pipes and FIFOs::.
+-
+-     Another cause of `SIGPIPE' is when you try to output to a socket
+-     that isn't connected.  *Note Sending Data::.
+-
+- - Macro: int SIGLOST
+-     Resource lost.  This signal is generated when you have an advisory
+-     lock on an NFS file, and the NFS server reboots and forgets about
+-     your lock.
+-
+-     In the GNU system, `SIGLOST' is generated when any server program
+-     dies unexpectedly.  It is usually fine to ignore the signal;
+-     whatever call was made to the server that died just returns an
+-     error.
+-
+- - Macro: int SIGXCPU
+-     CPU time limit exceeded.  This signal is generated when the process
+-     exceeds its soft resource limit on CPU time.  *Note Limits on
+-     Resources::.
+-
+- - Macro: int SIGXFSZ
+-     File size limit exceeded.  This signal is generated when the
+-     process attempts to extend a file so it exceeds the process's soft
+-     resource limit on file size.  *Note Limits on Resources::.
+-
+-
+-File: libc.info,  Node: Miscellaneous Signals,  Next: Signal Messages,  Prev: 
Operation Error Signals,  Up: Standard Signals
+-
+-Miscellaneous Signals
+----------------------
+-
+-   These signals are used for various other purposes.  In general, they
+-will not affect your program unless it explicitly uses them for
+-something.
+-
+- - Macro: int SIGUSR1
+-
+- - Macro: int SIGUSR2
+-     The `SIGUSR1' and `SIGUSR2' signals are set aside for you to use
+-     any way you want.  They're useful for simple interprocess
+-     communication, if you write a signal handler for them in the
+-     program that receives the signal.
+-
+-     There is an example showing the use of `SIGUSR1' and `SIGUSR2' in
+-     *Note Signaling Another Process::.
+-
+-     The default action is to terminate the process.
+-
+- - Macro: int SIGWINCH
+-     Window size change.  This is generated on some systems (including
+-     GNU) when the terminal driver's record of the number of rows and
+-     columns on the screen is changed.  The default action is to ignore
+-     it.
+-
+-     If a program does full-screen display, it should handle `SIGWINCH'.
+-     When the signal arrives, it should fetch the new screen size and
+-     reformat its display accordingly.
+-
+- - Macro: int SIGINFO
+-     Information request.  In 4.4 BSD and the GNU system, this signal
+-     is sent to all the processes in the foreground process group of
+-     the controlling terminal when the user types the STATUS character
+-     in canonical mode; *note Signal Characters::..
+-
+-     If the process is the leader of the process group, the default
+-     action is to print some status information about the system and
+-     what the process is doing.  Otherwise the default is to do nothing.
+-
+-
+-File: libc.info,  Node: Signal Messages,  Prev: Miscellaneous Signals,  Up: 
Standard Signals
+-
+-Signal Messages
+----------------
+-
+-   We mentioned above that the shell prints a message describing the
+-signal that terminated a child process.  The clean way to print a
+-message describing a signal is to use the functions `strsignal' and
+-`psignal'.  These functions use a signal number to specify which kind
+-of signal to describe.  The signal number may come from the termination
+-status of a child process (*note Process Completion::.) or it may come
+-from a signal handler in the same process.
+-
+- - Function: char * strsignal (int SIGNUM)
+-     This function returns a pointer to a statically-allocated string
+-     containing a message describing the signal SIGNUM.  You should not
+-     modify the contents of this string; and, since it can be rewritten
+-     on subsequent calls, you should save a copy of it if you need to
+-     reference it later.
+-
+-     This function is a GNU extension, declared in the header file
+-     `string.h'.
+-
+- - Function: void psignal (int SIGNUM, const char *MESSAGE)
+-     This function prints a message describing the signal SIGNUM to the
+-     standard error output stream `stderr'; see *Note Standard
+-     Streams::.
+-
+-     If you call `psignal' with a MESSAGE that is either a null pointer
+-     or an empty string, `psignal' just prints the message
+-     corresponding to SIGNUM, adding a trailing newline.
+-
+-     If you supply a non-null MESSAGE argument, then `psignal' prefixes
+-     its output with this string.  It adds a colon and a space
+-     character to separate the MESSAGE from the string corresponding to
+-     SIGNUM.
+-
+-     This function is a BSD feature, declared in the header file
+-     `signal.h'.
+-
+-   There is also an array `sys_siglist' which contains the messages for
+-the various signal codes.  This array exists on BSD systems, unlike
+-`strsignal'.
+-
+-
+-File: libc.info,  Node: Signal Actions,  Next: Defining Handlers,  Prev: 
Standard Signals,  Up: Signal Handling
+-
+-Specifying Signal Actions
+-=========================
+-
+-   The simplest way to change the action for a signal is to use the
+-`signal' function.  You can specify a built-in action (such as to
+-ignore the signal), or you can "establish a handler".
+-
+-   The GNU library also implements the more versatile `sigaction'
+-facility.  This section describes both facilities and gives suggestions
+-on which to use when.
+-
+-* Menu:
+-
+-* Basic Signal Handling::       The simple `signal' function.
+-* Advanced Signal Handling::    The more powerful `sigaction' function.
+-* Signal and Sigaction::        How those two functions interact.
+-* Sigaction Function Example::  An example of using the sigaction function.
+-* Flags for Sigaction::         Specifying options for signal handling.
+-* Initial Signal Actions::      How programs inherit signal actions.
+-
+-
+-File: libc.info,  Node: Basic Signal Handling,  Next: Advanced Signal 
Handling,  Up: Signal Actions
+-
+-Basic Signal Handling
+----------------------
+-
+-   The `signal' function provides a simple interface for establishing
+-an action for a particular signal.  The function and associated macros
+-are declared in the header file `signal.h'.
+-
+- - Data Type: sighandler_t
+-     This is the type of signal handler functions.  Signal handlers
+-     take one integer argument specifying the signal number, and have
+-     return type `void'.  So, you should define handler functions like
+-     this:
+-
+-          void HANDLER (int `signum') { ... }
+-
+-     The name `sighandler_t' for this data type is a GNU extension.
+-
+- - Function: sighandler_t signal (int SIGNUM, sighandler_t ACTION)
+-     The `signal' function establishes ACTION as the action for the
+-     signal SIGNUM.
+-
+-     The first argument, SIGNUM, identifies the signal whose behavior
+-     you want to control, and should be a signal number.  The proper
+-     way to specify a signal number is with one of the symbolic signal
+-     names described in *Note Standard Signals::--don't use an explicit
+-     number, because the numerical code for a given kind of signal may
+-     vary from operating system to operating system.
+-
+-     The second argument, ACTION, specifies the action to use for the
+-     signal SIGNUM.  This can be one of the following:
+-
+-    `SIG_DFL'
+-          `SIG_DFL' specifies the default action for the particular
+-          signal.  The default actions for various kinds of signals are
+-          stated in *Note Standard Signals::.
+-
+-    `SIG_IGN'
+-          `SIG_IGN' specifies that the signal should be ignored.
+-
+-          Your program generally should not ignore signals that
+-          represent serious events or that are normally used to request
+-          termination.  You cannot ignore the `SIGKILL' or `SIGSTOP'
+-          signals at all.  You can ignore program error signals like
+-          `SIGSEGV', but ignoring the error won't enable the program to
+-          continue executing meaningfully.  Ignoring user requests such
+-          as `SIGINT', `SIGQUIT', and `SIGTSTP' is unfriendly.
+-
+-          When you do not wish signals to be delivered during a certain
+-          part of the program, the thing to do is to block them, not
+-          ignore them.  *Note Blocking Signals::.
+-
+-    `HANDLER'
+-          Supply the address of a handler function in your program, to
+-          specify running this handler as the way to deliver the signal.
+-
+-          For more information about defining signal handler functions,
+-          see *Note Defining Handlers::.
+-
+-     If you set the action for a signal to `SIG_IGN', or if you set it
+-     to `SIG_DFL' and the default action is to ignore that signal, then
+-     any pending signals of that type are discarded (even if they are
+-     blocked).  Discarding the pending signals means that they will
+-     never be delivered, not even if you subsequently specify another
+-     action and unblock this kind of signal.
+-
+-     The `signal' function returns the action that was previously in
+-     effect for the specified SIGNUM.  You can save this value and
+-     restore it later by calling `signal' again.
+-
+-     If `signal' can't honor the request, it returns `SIG_ERR' instead.
+-     The following `errno' error conditions are defined for this
+-     function:
+-
+-    `EINVAL'
+-          You specified an invalid SIGNUM; or you tried to ignore or
+-          provide a handler for `SIGKILL' or `SIGSTOP'.
+-
+-   Here is a simple example of setting up a handler to delete temporary
+-files when certain fatal signals happen:
+-
+-     #include <signal.h>
+-     
+-     void
+-     termination_handler (int signum)
+-     {
+-       struct temp_file *p;
+-     
+-       for (p = temp_file_list; p; p = p->next)
+-         unlink (p->name);
+-     }
+-     
+-     int
+-     main (void)
+-     {
+-       ...
+-       if (signal (SIGINT, termination_handler) == SIG_IGN)
+-         signal (SIGINT, SIG_IGN);
+-       if (signal (SIGHUP, termination_handler) == SIG_IGN)
+-         signal (SIGHUP, SIG_IGN);
+-       if (signal (SIGTERM, termination_handler) == SIG_IGN)
+-         signal (SIGTERM, SIG_IGN);
+-       ...
+-     }
+-
+-Note how if a given signal was previously set to be ignored, this code
+-avoids altering that setting.  This is because non-job-control shells
+-often ignore certain signals when starting children, and it is important
+-for the children to respect this.
+-
+-   We do not handle `SIGQUIT' or the program error signals in this
+-example because these are designed to provide information for debugging
+-(a core dump), and the temporary files may give useful information.
+-
+- - Function: sighandler_t ssignal (int SIGNUM, sighandler_t ACTION)
+-     The `ssignal' function does the same thing as `signal'; it is
+-     provided only for compatibility with SVID.
+-
+- - Macro: sighandler_t SIG_ERR
+-     The value of this macro is used as the return value from `signal'
+-     to indicate an error.
+-
+-
+-File: libc.info,  Node: Advanced Signal Handling,  Next: Signal and 
Sigaction,  Prev: Basic Signal Handling,  Up: Signal Actions
+-
+-Advanced Signal Handling
+-------------------------
+-
+-   The `sigaction' function has the same basic effect as `signal': to
+-specify how a signal should be handled by the process.  However,
+-`sigaction' offers more control, at the expense of more complexity.  In
+-particular, `sigaction' allows you to specify additional flags to
+-control when the signal is generated and how the handler is invoked.
+-
+-   The `sigaction' function is declared in `signal.h'.
+-
+- - Data Type: struct sigaction
+-     Structures of type `struct sigaction' are used in the `sigaction'
+-     function to specify all the information about how to handle a
+-     particular signal.  This structure contains at least the following
+-     members:
+-
+-    `sighandler_t sa_handler'
+-          This is used in the same way as the ACTION argument to the
+-          `signal' function.  The value can be `SIG_DFL', `SIG_IGN', or
+-          a function pointer.  *Note Basic Signal Handling::.
+-
+-    `sigset_t sa_mask'
+-          This specifies a set of signals to be blocked while the
+-          handler runs.  Blocking is explained in *Note Blocking for
+-          Handler::.  Note that the signal that was delivered is
+-          automatically blocked by default before its handler is
+-          started; this is true regardless of the value in `sa_mask'.
+-          If you want that signal not to be blocked within its handler,
+-          you must write code in the handler to unblock it.
+-
+-    `int sa_flags'
+-          This specifies various flags which can affect the behavior of
+-          the signal.  These are described in more detail in *Note
+-          Flags for Sigaction::.
+-
+- - Function: int sigaction (int SIGNUM, const struct sigaction *ACTION,
+-          struct sigaction *OLD-ACTION)
+-     The ACTION argument is used to set up a new action for the signal
+-     SIGNUM, while the OLD-ACTION argument is used to return
+-     information about the action previously associated with this
+-     symbol.  (In other words, OLD-ACTION has the same purpose as the
+-     `signal' function's return value--you can check to see what the
+-     old action in effect for the signal was, and restore it later if
+-     you want.)
+-
+-     Either ACTION or OLD-ACTION can be a null pointer.  If OLD-ACTION
+-     is a null pointer, this simply suppresses the return of
+-     information about the old action.  If ACTION is a null pointer,
+-     the action associated with the signal SIGNUM is unchanged; this
+-     allows you to inquire about how a signal is being handled without
+-     changing that handling.
+-
+-     The return value from `sigaction' is zero if it succeeds, and `-1'
+-     on failure.  The following `errno' error conditions are defined
+-     for this function:
+-
+-    `EINVAL'
+-          The SIGNUM argument is not valid, or you are trying to trap
+-          or ignore `SIGKILL' or `SIGSTOP'.
+-
+-
+-File: libc.info,  Node: Signal and Sigaction,  Next: Sigaction Function 
Example,  Prev: Advanced Signal Handling,  Up: Signal Actions
+-
+-Interaction of `signal' and `sigaction'
+----------------------------------------
+-
+-   It's possible to use both the `signal' and `sigaction' functions
+-within a single program, but you have to be careful because they can
+-interact in slightly strange ways.
+-
+-   The `sigaction' function specifies more information than the
+-`signal' function, so the return value from `signal' cannot express the
+-full range of `sigaction' possibilities.  Therefore, if you use
+-`signal' to save and later reestablish an action, it may not be able to
+-reestablish properly a handler that was established with `sigaction'.
+-
+-   To avoid having problems as a result, always use `sigaction' to save
+-and restore a handler if your program uses `sigaction' at all.  Since
+-`sigaction' is more general, it can properly save and reestablish any
+-action, regardless of whether it was established originally with
+-`signal' or `sigaction'.
+-
+-   On some systems if you establish an action with `signal' and then
+-examine it with `sigaction', the handler address that you get may not
+-be the same as what you specified with `signal'.  It may not even be
+-suitable for use as an action argument with `signal'.  But you can rely
+-on using it as an argument to `sigaction'.  This problem never happens
+-on the GNU system.
+-
+-   So, you're better off using one or the other of the mechanisms
+-consistently within a single program.
+-
+-   *Portability Note:* The basic `signal' function is a feature of
+-ISO C, while `sigaction' is part of the POSIX.1 standard.  If you are
+-concerned about portability to non-POSIX systems, then you should use
+-the `signal' function instead.
+-
+-
+-File: libc.info,  Node: Sigaction Function Example,  Next: Flags for 
Sigaction,  Prev: Signal and Sigaction,  Up: Signal Actions
+-
+-`sigaction' Function Example
+-----------------------------
+-
+-   In *Note Basic Signal Handling::, we gave an example of establishing
+-a simple handler for termination signals using `signal'.  Here is an
+-equivalent example using `sigaction':
+-
+-     #include <signal.h>
+-     
+-     void
+-     termination_handler (int signum)
+-     {
+-       struct temp_file *p;
+-     
+-       for (p = temp_file_list; p; p = p->next)
+-         unlink (p->name);
+-     }
+-     
+-     int
+-     main (void)
+-     {
+-       ...
+-       struct sigaction new_action, old_action;
+-     
+-       /* Set up the structure to specify the new action. */
+-       new_action.sa_handler = termination_handler;
+-       sigemptyset (&new_action.sa_mask);
+-       new_action.sa_flags = 0;
+-     
+-       sigaction (SIGINT, NULL, &old_action);
+-       if (old_action.sa_handler != SIG_IGN)
+-         sigaction (SIGINT, &new_action, NULL);
+-       sigaction (SIGHUP, NULL, &old_action);
+-       if (old_action.sa_handler != SIG_IGN)
+-         sigaction (SIGHUP, &new_action, NULL);
+-       sigaction (SIGTERM, NULL, &old_action);
+-       if (old_action.sa_handler != SIG_IGN)
+-         sigaction (SIGTERM, &new_action, NULL);
+-       ...
+-     }
+-
+-   The program just loads the `new_action' structure with the desired
+-parameters and passes it in the `sigaction' call.  The usage of
+-`sigemptyset' is described later; see *Note Blocking Signals::.
+-
+-   As in the example using `signal', we avoid handling signals
+-previously set to be ignored.  Here we can avoid altering the signal
+-handler even momentarily, by using the feature of `sigaction' that lets
+-us examine the current action without specifying a new one.
+-
+-   Here is another example.  It retrieves information about the current
+-action for `SIGINT' without changing that action.
+-
+-     struct sigaction query_action;
+-     
+-     if (sigaction (SIGINT, NULL, &query_action) < 0)
+-       /* `sigaction' returns -1 in case of error. */
+-     else if (query_action.sa_handler == SIG_DFL)
+-       /* `SIGINT' is handled in the default, fatal manner. */
+-     else if (query_action.sa_handler == SIG_IGN)
+-       /* `SIGINT' is ignored. */
+-     else
+-       /* A programmer-defined signal handler is in effect. */
+-
+-
+-File: libc.info,  Node: Flags for Sigaction,  Next: Initial Signal Actions,  
Prev: Sigaction Function Example,  Up: Signal Actions
+-
+-Flags for `sigaction'
+----------------------
+-
+-   The `sa_flags' member of the `sigaction' structure is a catch-all
+-for special features.  Most of the time, `SA_RESTART' is a good value
+-to use for this field.
+-
+-   The value of `sa_flags' is interpreted as a bit mask.  Thus, you
+-should choose the flags you want to set, OR those flags together, and
+-store the result in the `sa_flags' member of your `sigaction' structure.
+-
+-   Each signal number has its own set of flags.  Each call to
+-`sigaction' affects one particular signal number, and the flags that
+-you specify apply only to that particular signal.
+-
+-   In the GNU C library, establishing a handler with `signal' sets all
+-the flags to zero except for `SA_RESTART', whose value depends on the
+-settings you have made with `siginterrupt'.  *Note Interrupted
+-Primitives::, to see what this is about.
+-
+-   These macros are defined in the header file `signal.h'.
+-
+- - Macro: int SA_NOCLDSTOP
+-     This flag is meaningful only for the `SIGCHLD' signal.  When the
+-     flag is set, the system delivers the signal for a terminated child
+-     process but not for one that is stopped.  By default, `SIGCHLD' is
+-     delivered for both terminated children and stopped children.
+-
+-     Setting this flag for a signal other than `SIGCHLD' has no effect.
+-
+- - Macro: int SA_ONSTACK
+-     If this flag is set for a particular signal number, the system
+-     uses the signal stack when delivering that kind of signal.  *Note
+-     Signal Stack::.  If a signal with this flag arrives and you have
+-     not set a signal stack, the system terminates the program with
+-     `SIGILL'.
+-
+- - Macro: int SA_RESTART
+-     This flag controls what happens when a signal is delivered during
+-     certain primitives (such as `open', `read' or `write'), and the
+-     signal handler returns normally.  There are two alternatives: the
+-     library function can resume, or it can return failure with error
+-     code `EINTR'.
+-
+-     The choice is controlled by the `SA_RESTART' flag for the
+-     particular kind of signal that was delivered.  If the flag is set,
+-     returning from a handler resumes the library function.  If the
+-     flag is clear, returning from a handler makes the function fail.
+-     *Note Interrupted Primitives::.
+-
+-
+-File: libc.info,  Node: Initial Signal Actions,  Prev: Flags for Sigaction,  
Up: Signal Actions
+-
+-Initial Signal Actions
+-----------------------
+-
+-   When a new process is created (*note Creating a Process::.), it
+-inherits handling of signals from its parent process.  However, when
+-you load a new process image using the `exec' function (*note Executing
+-a File::.), any signals that you've defined your own handlers for
+-revert to their `SIG_DFL' handling.  (If you think about it a little,
+-this makes sense; the handler functions from the old program are
+-specific to that program, and aren't even present in the address space
+-of the new program image.)  Of course, the new program can establish
+-its own handlers.
+-
+-   When a program is run by a shell, the shell normally sets the initial
+-actions for the child process to `SIG_DFL' or `SIG_IGN', as
+-appropriate.  It's a good idea to check to make sure that the shell has
+-not set up an initial action of `SIG_IGN' before you establish your own
+-signal handlers.
+-
+-   Here is an example of how to establish a handler for `SIGHUP', but
+-not if `SIGHUP' is currently ignored:
+-
+-     ...
+-     struct sigaction temp;
+-     
+-     sigaction (SIGHUP, NULL, &temp);
+-     
+-     if (temp.sa_handler != SIG_IGN)
+-       {
+-         temp.sa_handler = handle_sighup;
+-         sigemptyset (&temp.sa_mask);
+-         sigaction (SIGHUP, &temp, NULL);
+-       }
+-
+-
+-File: libc.info,  Node: Defining Handlers,  Next: Interrupted Primitives,  
Prev: Signal Actions,  Up: Signal Handling
+-
+-Defining Signal Handlers
+-========================
+-
+-   This section describes how to write a signal handler function that
+-can be established with the `signal' or `sigaction' functions.
+-
+-   A signal handler is just a function that you compile together with
+-the rest of the program.  Instead of directly invoking the function,
+-you use `signal' or `sigaction' to tell the operating system to call it
+-when a signal arrives.  This is known as "establishing" the handler.
+-*Note Signal Actions::.
+-
+-   There are two basic strategies you can use in signal handler
+-functions:
+-
+-   * You can have the handler function note that the signal arrived by
+-     tweaking some global data structures, and then return normally.
+-
+-   * You can have the handler function terminate the program or transfer
+-     control to a point where it can recover from the situation that
+-     caused the signal.
+-
+-   You need to take special care in writing handler functions because
+-they can be called asynchronously.  That is, a handler might be called
+-at any point in the program, unpredictably.  If two signals arrive
+-during a very short interval, one handler can run within another.  This
+-section describes what your handler should do, and what you should
+-avoid.
+-
+-* Menu:
+-
+-* Handler Returns::             Handlers that return normally, and what
+-                                 this means.
+-* Termination in Handler::      How handler functions terminate a program.
+-* Longjmp in Handler::          Nonlocal transfer of control out of a
+-                                 signal handler.
+-* Signals in Handler::          What happens when signals arrive while
+-                                 the handler is already occupied.
+-* Merged Signals::            When a second signal arrives before the
+-                               first is handled.
+-* Nonreentrancy::               Do not call any functions unless you know they
+-                                 are reentrant with respect to signals.
+-* Atomic Data Access::          A single handler can run in the middle of
+-                                 reading or writing a single object.
+-
+-
+-File: libc.info,  Node: Handler Returns,  Next: Termination in Handler,  Up: 
Defining Handlers
+-
+-Signal Handlers that Return
+----------------------------
+-
+-   Handlers which return normally are usually used for signals such as
+-`SIGALRM' and the I/O and interprocess communication signals.  But a
+-handler for `SIGINT' might also return normally after setting a flag
+-that tells the program to exit at a convenient time.
+-
+-   It is not safe to return normally from the handler for a program
+-error signal, because the behavior of the program when the handler
+-function returns is not defined after a program error.  *Note Program
+-Error Signals::.
+-
+-   Handlers that return normally must modify some global variable in
+-order to have any effect.  Typically, the variable is one that is
+-examined periodically by the program during normal operation.  Its data
+-type should be `sig_atomic_t' for reasons described in *Note Atomic
+-Data Access::.
+-
+-   Here is a simple example of such a program.  It executes the body of
+-the loop until it has noticed that a `SIGALRM' signal has arrived.
+-This technique is useful because it allows the iteration in progress
+-when the signal arrives to complete before the loop exits.
+-
+-     #include <signal.h>
+-     #include <stdio.h>
+-     #include <stdlib.h>
+-     
+-     /* This flag controls termination of the main loop. */
+-     volatile sig_atomic_t keep_going = 1;
+-     
+-     /* The signal handler just clears the flag and re-enables itself. */
+-     void
+-     catch_alarm (int sig)
+-     {
+-       keep_going = 0;
+-       signal (sig, catch_alarm);
+-     }
+-     
+-     void
+-     do_stuff (void)
+-     {
+-       puts ("Doing stuff while waiting for alarm....");
+-     }
+-     
+-     int
+-     main (void)
+-     {
+-       /* Establish a handler for SIGALRM signals. */
+-       signal (SIGALRM, catch_alarm);
+-     
+-       /* Set an alarm to go off in a little while. */
+-       alarm (2);
+-     
+-       /* Check the flag once in a while to see when to quit. */
+-       while (keep_going)
+-         do_stuff ();
+-     
+-       return EXIT_SUCCESS;
+-     }
+-
+-
+-File: libc.info,  Node: Termination in Handler,  Next: Longjmp in Handler,  
Prev: Handler Returns,  Up: Defining Handlers
+-
+-Handlers That Terminate the Process
+------------------------------------
+-
+-   Handler functions that terminate the program are typically used to
+-cause orderly cleanup or recovery from program error signals and
+-interactive interrupts.
+-
+-   The cleanest way for a handler to terminate the process is to raise
+-the same signal that ran the handler in the first place.  Here is how
+-to do this:
+-
+-     volatile sig_atomic_t fatal_error_in_progress = 0;
+-     
+-     void
+-     fatal_error_signal (int sig)
+-     {
+-     /* Since this handler is established for more than one kind of signal, 
+-          it might still get invoked recursively by delivery of some other 
kind
+-          of signal.  Use a static variable to keep track of that. */
+-       if (fatal_error_in_progress)
+-         raise (sig);
+-       fatal_error_in_progress = 1;
+-
+-     /* Now do the clean up actions:
+-          - reset terminal modes
+-          - kill child processes
+-          - remove lock files */
+-       ...
+-
+-     /* Now reraise the signal.  Since the signal is blocked,
+-          it will receive its default handling, which is
+-          to terminate the process.  We could just call
+-          `exit' or `abort', but reraising the signal
+-          sets the return status from the process correctly. */
+-       raise (sig);
+-     }
+-
+-
+-File: libc.info,  Node: Longjmp in Handler,  Next: Signals in Handler,  Prev: 
Termination in Handler,  Up: Defining Handlers
+-
+-Nonlocal Control Transfer in Handlers
+--------------------------------------
+-
+-   You can do a nonlocal transfer of control out of a signal handler
+-using the `setjmp' and `longjmp' facilities (*note Non-Local Exits::.).
+-
+-   When the handler does a nonlocal control transfer, the part of the
+-program that was running will not continue.  If this part of the program
+-was in the middle of updating an important data structure, the data
+-structure will remain inconsistent.  Since the program does not
+-terminate, the inconsistency is likely to be noticed later on.
+-
+-   There are two ways to avoid this problem.  One is to block the signal
+-for the parts of the program that update important data structures.
+-Blocking the signal delays its delivery until it is unblocked, once the
+-critical updating is finished.  *Note Blocking Signals::.
+-
+-   The other way to re-initialize the crucial data structures in the
+-signal handler, or make their values consistent.
+-
+-   Here is a rather schematic example showing the reinitialization of
+-one global variable.
+-
+-     #include <signal.h>
+-     #include <setjmp.h>
+-     
+-     jmp_buf return_to_top_level;
+-     
+-     volatile sig_atomic_t waiting_for_input;
+-     
+-     void
+-     handle_sigint (int signum)
+-     {
+-       /* We may have been waiting for input when the signal arrived,
+-          but we are no longer waiting once we transfer control. */
+-       waiting_for_input = 0;
+-       longjmp (return_to_top_level, 1);
+-     }
+-
+-     int
+-     main (void)
+-     {
+-       ...
+-       signal (SIGINT, sigint_handler);
+-       ...
+-       while (1) {
+-         prepare_for_command ();
+-         if (setjmp (return_to_top_level) == 0)
+-           read_and_execute_command ();
+-       }
+-     }
+-
+-     /* Imagine this is a subroutine used by various commands. */
+-     char *
+-     read_data ()
+-     {
+-       if (input_from_terminal) {
+-         waiting_for_input = 1;
+-         ...
+-         waiting_for_input = 0;
+-       } else {
+-         ...
+-       }
+-     }
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-21 
glibc-2.0.1/manual/libc.info-21
+--- ../glibc-2.0.1/manual/libc.info-21 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-21    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1178 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Signals in Handler,  Next: Merged Signals,  Prev: 
Longjmp in Handler,  Up: Defining Handlers
+-
+-Signals Arriving While a Handler Runs
+--------------------------------------
+-
+-   What happens if another signal arrives while your signal handler
+-function is running?
+-
+-   When the handler for a particular signal is invoked, that signal is
+-automatically blocked until the handler returns.  That means that if two
+-signals of the same kind arrive close together, the second one will be
+-held until the first has been handled.  (The handler can explicitly
+-unblock the signal using `sigprocmask', if you want to allow more
+-signals of this type to arrive; see *Note Process Signal Mask::.)
+-
+-   However, your handler can still be interrupted by delivery of another
+-kind of signal.  To avoid this, you can use the `sa_mask' member of the
+-action structure passed to `sigaction' to explicitly specify which
+-signals should be blocked while the signal handler runs.  These signals
+-are in addition to the signal for which the handler was invoked, and
+-any other signals that are normally blocked by the process.  *Note
+-Blocking for Handler::.
+-
+-   When the handler returns, the set of blocked signals is restored to
+-the value it had before the handler ran.  So using `sigprocmask' inside
+-the handler only affects what signals can arrive during the execution of
+-the handler itself, not what signals can arrive once the handler
+-returns.
+-
+-   *Portability Note:* Always use `sigaction' to establish a handler
+-for a signal that you expect to receive asynchronously, if you want
+-your program to work properly on System V Unix.  On this system, the
+-handling of a signal whose handler was established with `signal'
+-automatically sets the signal's action back to `SIG_DFL', and the
+-handler must re-establish itself each time it runs.  This practice,
+-while inconvenient, does work when signals cannot arrive in succession.
+-However, if another signal can arrive right away, it may arrive before
+-the handler can re-establish itself.  Then the second signal would
+-receive the default handling, which could terminate the process.
+-
+-
+-File: libc.info,  Node: Merged Signals,  Next: Nonreentrancy,  Prev: Signals 
in Handler,  Up: Defining Handlers
+-
+-Signals Close Together Merge into One
+--------------------------------------
+-
+-   If multiple signals of the same type are delivered to your process
+-before your signal handler has a chance to be invoked at all, the
+-handler may only be invoked once, as if only a single signal had
+-arrived.  In effect, the signals merge into one.  This situation can
+-arise when the signal is blocked, or in a multiprocessing environment
+-where the system is busy running some other processes while the signals
+-are delivered.  This means, for example, that you cannot reliably use a
+-signal handler to count signals.  The only distinction you can reliably
+-make is whether at least one signal has arrived since a given time in
+-the past.
+-
+-   Here is an example of a handler for `SIGCHLD' that compensates for
+-the fact that the number of signals recieved may not equal the number of
+-child processes generate them.  It assumes that the program keeps track
+-of all the child processes with a chain of structures as follows:
+-
+-     struct process
+-     {
+-       struct process *next;
+-       /* The process ID of this child.  */
+-       int pid;
+-       /* The descriptor of the pipe or pseudo terminal
+-          on which output comes from this child.  */
+-       int input_descriptor;
+-       /* Nonzero if this process has stopped or terminated.  */
+-       sig_atomic_t have_status;
+-       /* The status of this child; 0 if running,
+-          otherwise a status value from `waitpid'.  */
+-       int status;
+-     };
+-     
+-     struct process *process_list;
+-
+-   This example also uses a flag to indicate whether signals have
+-arrived since some time in the past--whenever the program last cleared
+-it to zero.
+-
+-     /* Nonzero means some child's status has changed
+-        so look at `process_list' for the details.  */
+-     int process_status_change;
+-
+-   Here is the handler itself:
+-
+-     void
+-     sigchld_handler (int signo)
+-     {
+-       int old_errno = errno;
+-     
+-       while (1) {
+-         register int pid;
+-         int w;
+-         struct process *p;
+-     
+-         /* Keep asking for a status until we get a definitive result.  */
+-         do
+-           {
+-             errno = 0;
+-             pid = waitpid (WAIT_ANY, &w, WNOHANG | WUNTRACED);
+-           }
+-         while (pid <= 0 && errno == EINTR);
+-     
+-         if (pid <= 0) {
+-           /* A real failure means there are no more
+-              stopped or terminated child processes, so return.  */
+-           errno = old_errno;
+-           return;
+-         }
+-     
+-         /* Find the process that signaled us, and record its status.  */
+-     
+-         for (p = process_list; p; p = p->next)
+-           if (p->pid == pid) {
+-             p->status = w;
+-             /* Indicate that the `status' field
+-                has data to look at.  We do this only after storing it.  */
+-             p->have_status = 1;
+-     
+-             /* If process has terminated, stop waiting for its output.  */
+-             if (WIFSIGNALED (w) || WIFEXITED (w))
+-               if (p->input_descriptor)
+-                 FD_CLR (p->input_descriptor, &input_wait_mask);
+-     
+-             /* The program should check this flag from time to time
+-                to see if there is any news in `process_list'.  */
+-             ++process_status_change;
+-           }
+-     
+-         /* Loop around to handle all the processes
+-            that have something to tell us.  */
+-       }
+-     }
+-
+-   Here is the proper way to check the flag `process_status_change':
+-
+-     if (process_status_change) {
+-       struct process *p;
+-       process_status_change = 0;
+-       for (p = process_list; p; p = p->next)
+-         if (p->have_status) {
+-           ... Examine `p->status' ...
+-         }
+-     }
+-
+-It is vital to clear the flag before examining the list; otherwise, if a
+-signal were delivered just before the clearing of the flag, and after
+-the appropriate element of the process list had been checked, the status
+-change would go unnoticed until the next signal arrived to set the flag
+-again.  You could, of course, avoid this problem by blocking the signal
+-while scanning the list, but it is much more elegant to guarantee
+-correctness by doing things in the right order.
+-
+-   The loop which checks process status avoids examining `p->status'
+-until it sees that status has been validly stored.  This is to make sure
+-that the status cannot change in the middle of accessing it.  Once
+-`p->have_status' is set, it means that the child process is stopped or
+-terminated, and in either case, it cannot stop or terminate again until
+-the program has taken notice.  *Note Atomic Usage::, for more
+-information about coping with interruptions during accessings of a
+-variable.
+-
+-   Here is another way you can test whether the handler has run since
+-the last time you checked.  This technique uses a counter which is never
+-changed outside the handler.  Instead of clearing the count, the program
+-remembers the previous value and sees whether it has changed since the
+-previous check.  The advantage of this method is that different parts of
+-the program can check independently, each part checking whether there
+-has been a signal since that part last checked.
+-
+-     sig_atomic_t process_status_change;
+-     
+-     sig_atomic_t last_process_status_change;
+-     
+-     ...
+-     {
+-       sig_atomic_t prev = last_process_status_change;
+-       last_process_status_change = process_status_change;
+-       if (last_process_status_change != prev) {
+-         struct process *p;
+-         for (p = process_list; p; p = p->next)
+-           if (p->have_status) {
+-             ... Examine `p->status' ...
+-           }
+-       }
+-     }
+-
+-
+-File: libc.info,  Node: Nonreentrancy,  Next: Atomic Data Access,  Prev: 
Merged Signals,  Up: Defining Handlers
+-
+-Signal Handling and Nonreentrant Functions
+-------------------------------------------
+-
+-   Handler functions usually don't do very much.  The best practice is
+-to write a handler that does nothing but set an external variable that
+-the program checks regularly, and leave all serious work to the program.
+-This is best because the handler can be called at asynchronously, at
+-unpredictable times--perhaps in the middle of a primitive function, or
+-even between the beginning and the end of a C operator that requires
+-multiple instructions.  The data structures being manipulated might
+-therefore be in an inconsistent state when the handler function is
+-invoked.  Even copying one `int' variable into another can take two
+-instructions on most machines.
+-
+-   This means you have to be very careful about what you do in a signal
+-handler.
+-
+-   * If your handler needs to access any global variables from your
+-     program, declare those variables `volatile'.  This tells the
+-     compiler that the value of the variable might change
+-     asynchronously, and inhibits certain optimizations that would be
+-     invalidated by such modifications.
+-
+-   * If you call a function in the handler, make sure it is "reentrant"
+-     with respect to signals, or else make sure that the signal cannot
+-     interrupt a call to a related function.
+-
+-   A function can be non-reentrant if it uses memory that is not on the
+-stack.
+-
+-   * If a function uses a static variable or a global variable, or a
+-     dynamically-allocated object that it finds for itself, then it is
+-     non-reentrant and any two calls to the function can interfere.
+-
+-     For example, suppose that the signal handler uses `gethostbyname'.
+-     This function returns its value in a static object, reusing the
+-     same object each time.  If the signal happens to arrive during a
+-     call to `gethostbyname', or even after one (while the program is
+-     still using the value), it will clobber the value that the program
+-     asked for.
+-
+-     However, if the program does not use `gethostbyname' or any other
+-     function that returns information in the same object, or if it
+-     always blocks signals around each use, then you are safe.
+-
+-     There are a large number of library functions that return values
+-     in a fixed object, always reusing the same object in this fashion,
+-     and all of them cause the same problem.  The description of a
+-     function in this manual always mentions this behavior.
+-
+-   * If a function uses and modifies an object that you supply, then it
+-     is potentially non-reentrant; two calls can interfere if they use
+-     the same object.
+-
+-     This case arises when you do I/O using streams.  Suppose that the
+-     signal handler prints a message with `fprintf'.  Suppose that the
+-     program was in the middle of an `fprintf' call using the same
+-     stream when the signal was delivered.  Both the signal handler's
+-     message and the program's data could be corrupted, because both
+-     calls operate on the same data structure--the stream itself.
+-
+-     However, if you know that the stream that the handler uses cannot
+-     possibly be used by the program at a time when signals can arrive,
+-     then you are safe.  It is no problem if the program uses some
+-     other stream.
+-
+-   * On most systems, `malloc' and `free' are not reentrant, because
+-     they use a static data structure which records what memory blocks
+-     are free.  As a result, no library functions that allocate or free
+-     memory are reentrant.  This includes functions that allocate space
+-     to store a result.
+-
+-     The best way to avoid the need to allocate memory in a handler is
+-     to allocate in advance space for signal handlers to use.
+-
+-     The best way to avoid freeing memory in a handler is to flag or
+-     record the objects to be freed, and have the program check from
+-     time to time whether anything is waiting to be freed.  But this
+-     must be done with care, because placing an object on a chain is
+-     not atomic, and if it is interrupted by another signal handler
+-     that does the same thing, you could "lose" one of the objects.
+-
+-     The relocating allocation functions (*note Relocating Allocator::.)
+-     are certainly not safe to use in a signal handler.
+-
+-   * Any function that modifies `errno' is non-reentrant, but you can
+-     correct for this: in the handler, save the original value of
+-     `errno' and restore it before returning normally.  This prevents
+-     errors that occur within the signal handler from being confused
+-     with errors from system calls at the point the program is
+-     interrupted to run the handler.
+-
+-     This technique is generally applicable; if you want to call in a
+-     handler a function that modifies a particular object in memory,
+-     you can make this safe by saving and restoring that object.
+-
+-   * Merely reading from a memory object is safe provided that you can
+-     deal with any of the values that might appear in the object at a
+-     time when the signal can be delivered.  Keep in mind that
+-     assignment to some data types requires more than one instruction,
+-     which means that the handler could run "in the middle of" an
+-     assignment to the variable if its type is not atomic.  *Note
+-     Atomic Data Access::.
+-
+-   * Merely writing into a memory object is safe as long as a sudden
+-     change in the value, at any time when the handler might run, will
+-     not disturb anything.
+-
+-
+-File: libc.info,  Node: Atomic Data Access,  Prev: Nonreentrancy,  Up: 
Defining Handlers
+-
+-Atomic Data Access and Signal Handling
+---------------------------------------
+-
+-   Whether the data in your application concerns atoms, or mere text,
+-you have to be careful about the fact that access to a single datum is
+-not necessarily "atomic".  This means that it can take more than one
+-instruction to read or write a single object.  In such cases, a signal
+-handler might in the middle of reading or writing the object.
+-
+-   There are three ways you can cope with this problem.  You can use
+-data types that are always accessed atomically; you can carefully
+-arrange that nothing untoward happens if an access is interrupted, or
+-you can block all signals around any access that had better not be
+-interrupted (*note Blocking Signals::.).
+-
+-* Menu:
+-
+-* Non-atomic Example::                A program illustrating interrupted 
access.
+-* Types: Atomic Types.                Data types that guarantee no 
interruption.
+-* Usage: Atomic Usage.                Proving that interruption is harmless.
+-
+-
+-File: libc.info,  Node: Non-atomic Example,  Next: Atomic Types,  Up: Atomic 
Data Access
+-
+-Problems with Non-Atomic Access
+-...............................
+-
+-   Here is an example which shows what can happen if a signal handler
+-runs in the middle of modifying a variable.  (Interrupting the reading
+-of a variable can also lead to paradoxical results, but here we only
+-show writing.)
+-
+-     #include <signal.h>
+-     #include <stdio.h>
+-     
+-     struct two_words { int a, b; } memory;
+-     
+-     void
+-     handler(int signum)
+-     {
+-        printf ("%d,%d\n", memory.a, memory.b);
+-        alarm (1);
+-     }
+-     int
+-     main (void)
+-     {
+-        static struct two_words zeros = { 0, 0 }, ones = { 1, 1 };
+-        signal (SIGALRM, handler);
+-        memory = zeros;
+-        alarm (1);
+-        while (1)
+-          {
+-            memory = zeros;
+-            memory = ones;
+-          }
+-     }
+-
+-   This program fills `memory' with zeros, ones, zeros, ones,
+-alternating forever; meanwhile, once per second, the alarm signal
+-handler prints the current contents.  (Calling `printf' in the handler
+-is safe in this program because it is certainly not being called outside
+-the handler when the signal happens.)
+-
+-   Clearly, this program can print a pair of zeros or a pair of ones.
+-But that's not all it can do!  On most machines, it takes several
+-instructions to store a new value in `memory', and the value is stored
+-one word at a time.  If the signal is delivered in between these
+-instructions, the handler might find that `memory.a' is zero and
+-`memory.b' is one (or vice versa).
+-
+-   On some machines it may be possible to store a new value in `memory'
+-with just one instruction that cannot be interrupted.  On these
+-machines, the handler will always print two zeros or two ones.
+-
+-
+-File: libc.info,  Node: Atomic Types,  Next: Atomic Usage,  Prev: Non-atomic 
Example,  Up: Atomic Data Access
+-
+-Atomic Types
+-............
+-
+-   To avoid uncertainty about interrupting access to a variable, you can
+-use a particular data type for which access is always atomic:
+-`sig_atomic_t'.  Reading and writing this data type is guaranteed to
+-happen in a single instruction, so there's no way for a handler to run
+-"in the middle" of an access.
+-
+-   The type `sig_atomic_t' is always an integer data type, but which
+-one it is, and how many bits it contains, may vary from machine to
+-machine.
+-
+- - Data Type: sig_atomic_t
+-     This is an integer data type.  Objects of this type are always
+-     accessed atomically.
+-
+-   In practice, you can assume that `int' and other integer types no
+-longer than `int' are atomic.  You can also assume that pointer types
+-are atomic; that is very convenient.  Both of these are true on all of
+-the machines that the GNU C library supports, and on all POSIX systems
+-we know of.
+-
+-
+-File: libc.info,  Node: Atomic Usage,  Prev: Atomic Types,  Up: Atomic Data 
Access
+-
+-Atomic Usage Patterns
+-.....................
+-
+-   Certain patterns of access avoid any problem even if an access is
+-interrupted.  For example, a flag which is set by the handler, and
+-tested and cleared by the main program from time to time, is always safe
+-even if access actually requires two instructions.  To show that this is
+-so, we must consider each access that could be interrupted, and show
+-that there is no problem if it is interrupted.
+-
+-   An interrupt in the middle of testing the flag is safe because
+-either it's recognized to be nonzero, in which case the precise value
+-doesn't matter, or it will be seen to be nonzero the next time it's
+-tested.
+-
+-   An interrupt in the middle of clearing the flag is no problem because
+-either the value ends up zero, which is what happens if a signal comes
+-in just before the flag is cleared, or the value ends up nonzero, and
+-subsequent events occur as if the signal had come in just after the flag
+-was cleared.  As long as the code handles both of these cases properly,
+-it can also handle a signal in the middle of clearing the flag.  (This
+-is an example of the sort of reasoning you need to do to figure out
+-whether non-atomic usage is safe.)
+-
+-   Sometimes you can insure uninterrupted access to one object by
+-protecting its use with another object, perhaps one whose type
+-guarantees atomicity.  *Note Merged Signals::, for an example.
+-
+-
+-File: libc.info,  Node: Interrupted Primitives,  Next: Generating Signals,  
Prev: Defining Handlers,  Up: Signal Handling
+-
+-Primitives Interrupted by Signals
+-=================================
+-
+-   A signal can arrive and be handled while an I/O primitive such as
+-`open' or `read' is waiting for an I/O device.  If the signal handler
+-returns, the system faces the question: what should happen next?
+-
+-   POSIX specifies one approach: make the primitive fail right away.
+-The error code for this kind of failure is `EINTR'.  This is flexible,
+-but usually inconvenient.  Typically, POSIX applications that use signal
+-handlers must check for `EINTR' after each library function that can
+-return it, in order to try the call again.  Often programmers forget to
+-check, which is a common source of error.
+-
+-   The GNU library provides a convenient way to retry a call after a
+-temporary failure, with the macro `TEMP_FAILURE_RETRY':
+-
+- - Macro: TEMP_FAILURE_RETRY (EXPRESSION)
+-     This macro evaluates EXPRESSION once.  If it fails and reports
+-     error code `EINTR', `TEMP_FAILURE_RETRY' evaluates it again, and
+-     over and over until the result is not a temporary failure.
+-
+-     The value returned by `TEMP_FAILURE_RETRY' is whatever value
+-     EXPRESSION produced.
+-
+-   BSD avoids `EINTR' entirely and provides a more convenient approach:
+-to restart the interrupted primitive, instead of making it fail.  If
+-you choose this approach, you need not be concerned with `EINTR'.
+-
+-   You can choose either approach with the GNU library.  If you use
+-`sigaction' to establish a signal handler, you can specify how that
+-handler should behave.  If you specify the `SA_RESTART' flag, return
+-from that handler will resume a primitive; otherwise, return from that
+-handler will cause `EINTR'.  *Note Flags for Sigaction::.
+-
+-   Another way to specify the choice is with the `siginterrupt'
+-function.  *Note BSD Handler::.
+-
+-   When you don't specify with `sigaction' or `siginterrupt' what a
+-particular handler should do, it uses a default choice.  The default
+-choice in the GNU library depends on the feature test macros you have
+-defined.  If you define `_BSD_SOURCE' or `_GNU_SOURCE' before calling
+-`signal', the default is to resume primitives; otherwise, the default
+-is to make them fail with `EINTR'.  (The library contains alternate
+-versions of the `signal' function, and the feature test macros
+-determine which one you really call.)  *Note Feature Test Macros::.
+-
+-   The description of each primitive affected by this issue lists
+-`EINTR' among the error codes it can return.
+-
+-   There is one situation where resumption never happens no matter which
+-choice you make: when a data-transfer function such as `read' or
+-`write' is interrupted by a signal after transferring part of the data.
+-In this case, the function returns the number of bytes already
+-transferred, indicating partial success.
+-
+-   This might at first appear to cause unreliable behavior on
+-record-oriented devices (including datagram sockets; *note
+-Datagrams::.), where splitting one `read' or `write' into two would
+-read or write two records.  Actually, there is no problem, because
+-interruption after a partial transfer cannot happen on such devices;
+-they always transfer an entire record in one burst, with no waiting
+-once data transfer has started.
+-
+-
+-File: libc.info,  Node: Generating Signals,  Next: Blocking Signals,  Prev: 
Interrupted Primitives,  Up: Signal Handling
+-
+-Generating Signals
+-==================
+-
+-   Besides signals that are generated as a result of a hardware trap or
+-interrupt, your program can explicitly send signals to itself or to
+-another process.
+-
+-* Menu:
+-
+-* Signaling Yourself::          A process can send a signal to itself.
+-* Signaling Another Process::   Send a signal to another process.
+-* Permission for kill::         Permission for using `kill'.
+-* Kill Example::                Using `kill' for Communication.
+-
+-
+-File: libc.info,  Node: Signaling Yourself,  Next: Signaling Another Process, 
 Up: Generating Signals
+-
+-Signaling Yourself
+-------------------
+-
+-   A process can send itself a signal with the `raise' function.  This
+-function is declared in `signal.h'.
+-
+- - Function: int raise (int SIGNUM)
+-     The `raise' function sends the signal SIGNUM to the calling
+-     process.  It returns zero if successful and a nonzero value if it
+-     fails.  About the only reason for failure would be if the value of
+-     SIGNUM is invalid.
+-
+- - Function: int gsignal (int SIGNUM)
+-     The `gsignal' function does the same thing as `raise'; it is
+-     provided only for compatibility with SVID.
+-
+-   One convenient use for `raise' is to reproduce the default behavior
+-of a signal that you have trapped.  For instance, suppose a user of your
+-program types the SUSP character (usually `C-z'; *note Special
+-Characters::.) to send it an interactive stop stop signal (`SIGTSTP'),
+-and you want to clean up some internal data buffers before stopping.
+-You might set this up like this:
+-
+-     #include <signal.h>
+-     
+-     /* When a stop signal arrives, set the action back to the default
+-        and then resend the signal after doing cleanup actions. */
+-     
+-     void
+-     tstp_handler (int sig)
+-     {
+-       signal (SIGTSTP, SIG_DFL);
+-       /* Do cleanup actions here. */
+-       ...
+-       raise (SIGTSTP);
+-     }
+-     
+-     /* When the process is continued again, restore the signal handler. */
+-     
+-     void
+-     cont_handler (int sig)
+-     {
+-       signal (SIGCONT, cont_handler);
+-       signal (SIGTSTP, tstp_handler);
+-     }
+-     /* Enable both handlers during program initialization. */
+-     
+-     int
+-     main (void)
+-     {
+-       signal (SIGCONT, cont_handler);
+-       signal (SIGTSTP, tstp_handler);
+-       ...
+-     }
+-
+-   *Portability note:* `raise' was invented by the ISO C committee.
+-Older systems may not support it, so using `kill' may be more portable.
+-*Note Signaling Another Process::.
+-
+-
+-File: libc.info,  Node: Signaling Another Process,  Next: Permission for 
kill,  Prev: Signaling Yourself,  Up: Generating Signals
+-
+-Signaling Another Process
+--------------------------
+-
+-   The `kill' function can be used to send a signal to another process.
+-In spite of its name, it can be used for a lot of things other than
+-causing a process to terminate.  Some examples of situations where you
+-might want to send signals between processes are:
+-
+-   * A parent process starts a child to perform a task--perhaps having
+-     the child running an infinite loop--and then terminates the child
+-     when the task is no longer needed.
+-
+-   * A process executes as part of a group, and needs to terminate or
+-     notify the other processes in the group when an error or other
+-     event occurs.
+-
+-   * Two processes need to synchronize while working together.
+-
+-   This section assumes that you know a little bit about how processes
+-work.  For more information on this subject, see *Note Processes::.
+-
+-   The `kill' function is declared in `signal.h'.
+-
+- - Function: int kill (pid_t PID, int SIGNUM)
+-     The `kill' function sends the signal SIGNUM to the process or
+-     process group specified by PID.  Besides the signals listed in
+-     *Note Standard Signals::, SIGNUM can also have a value of zero to
+-     check the validity of the PID.
+-
+-     The PID specifies the process or process group to receive the
+-     signal:
+-
+-    `PID > 0'
+-          The process whose identifier is PID.
+-
+-    `PID == 0'
+-          All processes in the same process group as the sender.
+-
+-    `PID < -1'
+-          The process group whose identifier is -PID.
+-
+-    `PID == -1'
+-          If the process is privileged, send the signal to all
+-          processes except for some special system processes.
+-          Otherwise, send the signal to all processes with the same
+-          effective user ID.
+-
+-     A process can send a signal SIGNUM to itself with a call like
+-     `kill (getpid(), SIGNUM)'.  If `kill' is used by a process to send
+-     a signal to itself, and the signal is not blocked, then `kill'
+-     delivers at least one signal (which might be some other pending
+-     unblocked signal instead of the signal SIGNUM) to that process
+-     before it returns.
+-
+-     The return value from `kill' is zero if the signal can be sent
+-     successfully.  Otherwise, no signal is sent, and a value of `-1' is
+-     returned.  If PID specifies sending a signal to several processes,
+-     `kill' succeeds if it can send the signal to at least one of them.
+-     There's no way you can tell which of the processes got the signal
+-     or whether all of them did.
+-
+-     The following `errno' error conditions are defined for this
+-     function:
+-
+-    `EINVAL'
+-          The SIGNUM argument is an invalid or unsupported number.
+-
+-    `EPERM'
+-          You do not have the privilege to send a signal to the process
+-          or any of the processes in the process group named by PID.
+-
+-    `ESCRH'
+-          The PID argument does not refer to an existing process or
+-          group.
+-
+- - Function: int killpg (int PGID, int SIGNUM)
+-     This is similar to `kill', but sends signal SIGNUM to the process
+-     group PGID.  This function is provided for compatibility with BSD;
+-     using `kill' to do this is more portable.
+-
+-   As a simple example of `kill', the call `kill (getpid (), SIG)' has
+-the same effect as `raise (SIG)'.
+-
+-
+-File: libc.info,  Node: Permission for kill,  Next: Kill Example,  Prev: 
Signaling Another Process,  Up: Generating Signals
+-
+-Permission for using `kill'
+----------------------------
+-
+-   There are restrictions that prevent you from using `kill' to send
+-signals to any random process.  These are intended to prevent antisocial
+-behavior such as arbitrarily killing off processes belonging to another
+-user.  In typical use, `kill' is used to pass signals between parent,
+-child, and sibling processes, and in these situations you normally do
+-have permission to send signals.  The only common exception is when you
+-run a setuid program in a child process; if the program changes its
+-real UID as well as its effective UID, you may not have permission to
+-send a signal.  The `su' program does this.
+-
+-   Whether a process has permission to send a signal to another process
+-is determined by the user IDs of the two processes.  This concept is
+-discussed in detail in *Note Process Persona::.
+-
+-   Generally, for a process to be able to send a signal to another
+-process, either the sending process must belong to a privileged user
+-(like `root'), or the real or effective user ID of the sending process
+-must match the real or effective user ID of the receiving process.  If
+-the receiving process has changed its effective user ID from the
+-set-user-ID mode bit on its process image file, then the owner of the
+-process image file is used in place of its current effective user ID.
+-In some implementations, a parent process might be able to send signals
+-to a child process even if the user ID's don't match, and other
+-implementations might enforce other restrictions.
+-
+-   The `SIGCONT' signal is a special case.  It can be sent if the
+-sender is part of the same session as the receiver, regardless of user
+-IDs.
+-
+-
+-File: libc.info,  Node: Kill Example,  Prev: Permission for kill,  Up: 
Generating Signals
+-
+-Using `kill' for Communication
+-------------------------------
+-
+-   Here is a longer example showing how signals can be used for
+-interprocess communication.  This is what the `SIGUSR1' and `SIGUSR2'
+-signals are provided for.  Since these signals are fatal by default,
+-the process that is supposed to receive them must trap them through
+-`signal' or `sigaction'.
+-
+-   In this example, a parent process forks a child process and then
+-waits for the child to complete its initialization.  The child process
+-tells the parent when it is ready by sending it a `SIGUSR1' signal,
+-using the `kill' function.
+-
+-     #include <signal.h>
+-     #include <stdio.h>
+-     #include <sys/types.h>
+-     #include <unistd.h>
+-     
+-     /* When a `SIGUSR1' signal arrives, set this variable. */
+-     volatile sig_atomic_t usr_interrupt = 0;
+-     
+-     void
+-     synch_signal (int sig)
+-     {
+-       usr_interrupt = 1;
+-     }
+-     
+-     /* The child process executes this function. */
+-     void
+-     child_function (void)
+-     {
+-       /* Perform initialization. */
+-       printf ("I'm here!!!  My pid is %d.\n", (int) getpid ());
+-     
+-       /* Let parent know you're done. */
+-       kill (getppid (), SIGUSR1);
+-     
+-       /* Continue with execution. */
+-       puts ("Bye, now....");
+-       exit (0);
+-     }
+-     
+-     int
+-     main (void)
+-     {
+-       struct sigaction usr_action;
+-       sigset_t block_mask;
+-       pid_t child_id;
+-     
+-       /* Establish the signal handler. */
+-       sigfillset (&block_mask);
+-       usr_action.sa_handler = synch_signal;
+-       usr_action.sa_mask = block_mask;
+-       usr_action.sa_flags = 0;
+-       sigaction (SIGUSR1, &usr_action, NULL);
+-     
+-       /* Create the child process. */
+-       child_id = fork ();
+-       if (child_id == 0)
+-         child_function ();          /* Does not return. */
+-     /* Busy wait for the child to send a signal. */
+-       while (!usr_interrupt)
+-         ;
+-     
+-       /* Now continue execution. */
+-       puts ("That's all, folks!");
+-     
+-       return 0;
+-     }
+-
+-   This example uses a busy wait, which is bad, because it wastes CPU
+-cycles that other programs could otherwise use.  It is better to ask the
+-system to wait until the signal arrives.  See the example in *Note
+-Waiting for a Signal::.
+-
+-
+-File: libc.info,  Node: Blocking Signals,  Next: Waiting for a Signal,  Prev: 
Generating Signals,  Up: Signal Handling
+-
+-Blocking Signals
+-================
+-
+-   Blocking a signal means telling the operating system to hold it and
+-deliver it later.  Generally, a program does not block signals
+-indefinitely--it might as well ignore them by setting their actions to
+-`SIG_IGN'.  But it is useful to block signals briefly, to prevent them
+-from interrupting sensitive operations.  For instance:
+-
+-   * You can use the `sigprocmask' function to block signals while you
+-     modify global variables that are also modified by the handlers for
+-     these signals.
+-
+-   * You can set `sa_mask' in your `sigaction' call to block certain
+-     signals while a particular signal handler runs.  This way, the
+-     signal handler can run without being interrupted itself by signals.
+-
+-* Menu:
+-
+-* Why Block::                           The purpose of blocking signals.
+-* Signal Sets::                         How to specify which signals to
+-                                         block.
+-* Process Signal Mask::                 Blocking delivery of signals to your
+-                                       process during normal execution.
+-* Testing for Delivery::                Blocking to Test for Delivery of
+-                                         a Signal.
+-* Blocking for Handler::                Blocking additional signals while a
+-                                       handler is being run.
+-* Checking for Pending Signals::        Checking for Pending Signals
+-* Remembering a Signal::                How you can get almost the same
+-                                         effect as blocking a signal, by
+-                                         handling it and setting a flag
+-                                         to be tested later.
+-
+-
+-File: libc.info,  Node: Why Block,  Next: Signal Sets,  Up: Blocking Signals
+-
+-Why Blocking Signals is Useful
+-------------------------------
+-
+-   Temporary blocking of signals with `sigprocmask' gives you a way to
+-prevent interrupts during critical parts of your code.  If signals
+-arrive in that part of the program, they are delivered later, after you
+-unblock them.
+-
+-   One example where this is useful is for sharing data between a signal
+-handler and the rest of the program.  If the type of the data is not
+-`sig_atomic_t' (*note Atomic Data Access::.), then the signal handler
+-could run when the rest of the program has only half finished reading
+-or writing the data.  This would lead to confusing consequences.
+-
+-   To make the program reliable, you can prevent the signal handler from
+-running while the rest of the program is examining or modifying that
+-data--by blocking the appropriate signal around the parts of the
+-program that touch the data.
+-
+-   Blocking signals is also necessary when you want to perform a certain
+-action only if a signal has not arrived.  Suppose that the handler for
+-the signal sets a flag of type `sig_atomic_t'; you would like to test
+-the flag and perform the action if the flag is not set.  This is
+-unreliable.  Suppose the signal is delivered immediately after you test
+-the flag, but before the consequent action: then the program will
+-perform the action even though the signal has arrived.
+-
+-   The only way to test reliably for whether a signal has yet arrived
+-is to test while the signal is blocked.
+-
+-
+-File: libc.info,  Node: Signal Sets,  Next: Process Signal Mask,  Prev: Why 
Block,  Up: Blocking Signals
+-
+-Signal Sets
+------------
+-
+-   All of the signal blocking functions use a data structure called a
+-"signal set" to specify what signals are affected.  Thus, every
+-activity involves two stages: creating the signal set, and then passing
+-it as an argument to a library function.
+-
+-   These facilities are declared in the header file `signal.h'.
+-
+- - Data Type: sigset_t
+-     The `sigset_t' data type is used to represent a signal set.
+-     Internally, it may be implemented as either an integer or structure
+-     type.
+-
+-     For portability, use only the functions described in this section
+-     to initialize, change, and retrieve information from `sigset_t'
+-     objects--don't try to manipulate them directly.
+-
+-   There are two ways to initialize a signal set.  You can initially
+-specify it to be empty with `sigemptyset' and then add specified
+-signals individually.  Or you can specify it to be full with
+-`sigfillset' and then delete specified signals individually.
+-
+-   You must always initialize the signal set with one of these two
+-functions before using it in any other way.  Don't try to set all the
+-signals explicitly because the `sigset_t' object might include some
+-other information (like a version field) that needs to be initialized as
+-well.  (In addition, it's not wise to put into your program an
+-assumption that the system has no signals aside from the ones you know
+-about.)
+-
+- - Function: int sigemptyset (sigset_t *SET)
+-     This function initializes the signal set SET to exclude all of the
+-     defined signals.  It always returns `0'.
+-
+- - Function: int sigfillset (sigset_t *SET)
+-     This function initializes the signal set SET to include all of the
+-     defined signals.  Again, the return value is `0'.
+-
+- - Function: int sigaddset (sigset_t *SET, int SIGNUM)
+-     This function adds the signal SIGNUM to the signal set SET.  All
+-     `sigaddset' does is modify SET; it does not block or unblock any
+-     signals.
+-
+-     The return value is `0' on success and `-1' on failure.  The
+-     following `errno' error condition is defined for this function:
+-
+-    `EINVAL'
+-          The SIGNUM argument doesn't specify a valid signal.
+-
+- - Function: int sigdelset (sigset_t *SET, int SIGNUM)
+-     This function removes the signal SIGNUM from the signal set SET.
+-     All `sigdelset' does is modify SET; it does not block or unblock
+-     any signals.  The return value and error conditions are the same
+-     as for `sigaddset'.
+-
+-   Finally, there is a function to test what signals are in a signal
+-set:
+-
+- - Function: int sigismember (const sigset_t *SET, int SIGNUM)
+-     The `sigismember' function tests whether the signal SIGNUM is a
+-     member of the signal set SET.  It returns `1' if the signal is in
+-     the set, `0' if not, and `-1' if there is an error.
+-
+-     The following `errno' error condition is defined for this function:
+-
+-    `EINVAL'
+-          The SIGNUM argument doesn't specify a valid signal.
+-
+-
+-File: libc.info,  Node: Process Signal Mask,  Next: Testing for Delivery,  
Prev: Signal Sets,  Up: Blocking Signals
+-
+-Process Signal Mask
+--------------------
+-
+-   The collection of signals that are currently blocked is called the
+-"signal mask".  Each process has its own signal mask.  When you create
+-a new process (*note Creating a Process::.), it inherits its parent's
+-mask.  You can block or unblock signals with total flexibility by
+-modifying the signal mask.
+-
+-   The prototype for the `sigprocmask' function is in `signal.h'.
+-
+- - Function: int sigprocmask (int HOW, const sigset_t *SET, sigset_t
+-          *OLDSET)
+-     The `sigprocmask' function is used to examine or change the calling
+-     process's signal mask.  The HOW argument determines how the signal
+-     mask is changed, and must be one of the following values:
+-
+-    `SIG_BLOCK'
+-          Block the signals in `set'--add them to the existing mask.  In
+-          other words, the new mask is the union of the existing mask
+-          and SET.
+-
+-    `SIG_UNBLOCK'
+-          Unblock the signals in SET--remove them from the existing
+-          mask.
+-
+-    `SIG_SETMASK'
+-          Use SET for the mask; ignore the previous value of the mask.
+-
+-     The last argument, OLDSET, is used to return information about the
+-     old process signal mask.  If you just want to change the mask
+-     without looking at it, pass a null pointer as the OLDSET argument.
+-     Similarly, if you want to know what's in the mask without changing
+-     it, pass a null pointer for SET (in this case the HOW argument is
+-     not significant).  The OLDSET argument is often used to remember
+-     the previous signal mask in order to restore it later.  (Since the
+-     signal mask is inherited over `fork' and `exec' calls, you can't
+-     predict what its contents are when your program starts running.)
+-
+-     If invoking `sigprocmask' causes any pending signals to be
+-     unblocked, at least one of those signals is delivered to the
+-     process before `sigprocmask' returns.  The order in which pending
+-     signals are delivered is not specified, but you can control the
+-     order explicitly by making multiple `sigprocmask' calls to unblock
+-     various signals one at a time.
+-
+-     The `sigprocmask' function returns `0' if successful, and `-1' to
+-     indicate an error.  The following `errno' error conditions are
+-     defined for this function:
+-
+-    `EINVAL'
+-          The HOW argument is invalid.
+-
+-     You can't block the `SIGKILL' and `SIGSTOP' signals, but if the
+-     signal set includes these, `sigprocmask' just ignores them instead
+-     of returning an error status.
+-
+-     Remember, too, that blocking program error signals such as `SIGFPE'
+-     leads to undesirable results for signals generated by an actual
+-     program error (as opposed to signals sent with `raise' or `kill').
+-     This is because your program may be too broken to be able to
+-     continue executing to a point where the signal is unblocked again.
+-     *Note Program Error Signals::.
+-
+-
+-File: libc.info,  Node: Testing for Delivery,  Next: Blocking for Handler,  
Prev: Process Signal Mask,  Up: Blocking Signals
+-
+-Blocking to Test for Delivery of a Signal
+------------------------------------------
+-
+-   Now for a simple example.  Suppose you establish a handler for
+-`SIGALRM' signals that sets a flag whenever a signal arrives, and your
+-main program checks this flag from time to time and then resets it.
+-You can prevent additional `SIGALRM' signals from arriving in the
+-meantime by wrapping the critical part of the code with calls to
+-`sigprocmask', like this:
+-
+-     /* This variable is set by the SIGALRM signal handler. */
+-     volatile sig_atomic_t flag = 0;
+-     
+-     int
+-     main (void)
+-     {
+-       sigset_t block_alarm;
+-     
+-       ...
+-     
+-       /* Initialize the signal mask. */
+-       sigemptyset (&block_alarm);
+-       sigaddset (&block_alarm, SIGALRM);
+-     while (1)
+-         {
+-           /* Check if a signal has arrived; if so, reset the flag. */
+-           sigprocmask (SIG_BLOCK, &block_alarm, NULL);
+-           if (flag)
+-             {
+-               ACTIONS-IF-NOT-ARRIVED
+-               flag = 0;
+-             }
+-           sigprocmask (SIG_UNBLOCK, &block_alarm, NULL);
+-     
+-           ...
+-         }
+-     }
+-
+-
+-File: libc.info,  Node: Blocking for Handler,  Next: Checking for Pending 
Signals,  Prev: Testing for Delivery,  Up: Blocking Signals
+-
+-Blocking Signals for a Handler
+-------------------------------
+-
+-   When a signal handler is invoked, you usually want it to be able to
+-finish without being interrupted by another signal.  From the moment the
+-handler starts until the moment it finishes, you must block signals that
+-might confuse it or corrupt its data.
+-
+-   When a handler function is invoked on a signal, that signal is
+-automatically blocked (in addition to any other signals that are already
+-in the process's signal mask) during the time the handler is running.
+-If you set up a handler for `SIGTSTP', for instance, then the arrival
+-of that signal forces further `SIGTSTP' signals to wait during the
+-execution of the handler.
+-
+-   However, by default, other kinds of signals are not blocked; they can
+-arrive during handler execution.
+-
+-   The reliable way to block other kinds of signals during the
+-execution of the handler is to use the `sa_mask' member of the
+-`sigaction' structure.
+-
+-   Here is an example:
+-
+-     #include <signal.h>
+-     #include <stddef.h>
+-     
+-     void catch_stop ();
+-     
+-     void
+-     install_handler (void)
+-     {
+-       struct sigaction setup_action;
+-       sigset_t block_mask;
+-     
+-       sigemptyset (&block_mask);
+-       /* Block other terminal-generated signals while handler runs. */
+-       sigaddset (&block_mask, SIGINT);
+-       sigaddset (&block_mask, SIGQUIT);
+-       setup_action.sa_handler = catch_stop;
+-       setup_action.sa_mask = block_mask;
+-       setup_action.sa_flags = 0;
+-       sigaction (SIGTSTP, &setup_action, NULL);
+-     }
+-
+-   This is more reliable than blocking the other signals explicitly in
+-the code for the handler.  If you block signals explicitly in the
+-handler, you can't avoid at least a short interval at the beginning of
+-the handler where they are not yet blocked.
+-
+-   You cannot remove signals from the process's current mask using this
+-mechanism.  However, you can make calls to `sigprocmask' within your
+-handler to block or unblock signals as you wish.
+-
+-   In any case, when the handler returns, the system restores the mask
+-that was in place before the handler was entered.  If any signals that
+-become unblocked by this restoration are pending, the process will
+-receive those signals immediately, before returning to the code that was
+-interrupted.
+-
+-
+-File: libc.info,  Node: Checking for Pending Signals,  Next: Remembering a 
Signal,  Prev: Blocking for Handler,  Up: Blocking Signals
+-
+-Checking for Pending Signals
+-----------------------------
+-
+-   You can find out which signals are pending at any time by calling
+-`sigpending'.  This function is declared in `signal.h'.
+-
+- - Function: int sigpending (sigset_t *SET)
+-     The `sigpending' function stores information about pending signals
+-     in SET.  If there is a pending signal that is blocked from
+-     delivery, then that signal is a member of the returned set.  (You
+-     can test whether a particular signal is a member of this set using
+-     `sigismember'; see *Note Signal Sets::.)
+-
+-     The return value is `0' if successful, and `-1' on failure.
+-
+-   Testing whether a signal is pending is not often useful.  Testing
+-when that signal is not blocked is almost certainly bad design.
+-
+-   Here is an example.
+-
+-     #include <signal.h>
+-     #include <stddef.h>
+-     
+-     sigset_t base_mask, waiting_mask;
+-     
+-     sigemptyset (&base_mask);
+-     sigaddset (&base_mask, SIGINT);
+-     sigaddset (&base_mask, SIGTSTP);
+-     
+-     /* Block user interrupts while doing other processing. */
+-     sigprocmask (SIG_SETMASK, &base_mask, NULL);
+-     ...
+-     
+-     /* After a while, check to see whether any signals are pending. */
+-     sigpending (&waiting_mask);
+-     if (sigismember (&waiting_mask, SIGINT)) {
+-       /* User has tried to kill the process. */
+-     }
+-     else if (sigismember (&waiting_mask, SIGTSTP)) {
+-       /* User has tried to stop the process. */
+-     }
+-
+-   Remember that if there is a particular signal pending for your
+-process, additional signals of that same type that arrive in the
+-meantime might be discarded.  For example, if a `SIGINT' signal is
+-pending when another `SIGINT' signal arrives, your program will
+-probably only see one of them when you unblock this signal.
+-
+-   *Portability Note:* The `sigpending' function is new in POSIX.1.
+-Older systems have no equivalent facility.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-22 
glibc-2.0.1/manual/libc.info-22
+--- ../glibc-2.0.1/manual/libc.info-22 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-22    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1247 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Remembering a Signal,  Prev: Checking for Pending 
Signals,  Up: Blocking Signals
+-
+-Remembering a Signal to Act On Later
+-------------------------------------
+-
+-   Instead of blocking a signal using the library facilities, you can
+-get almost the same results by making the handler set a flag to be
+-tested later, when you "unblock".  Here is an example:
+-
+-     /* If this flag is nonzero, don't handle the signal right away. */
+-     volatile sig_atomic_t signal_pending;
+-     
+-     /* This is nonzero if a signal arrived and was not handled. */
+-     volatile sig_atomic_t defer_signal;
+-     
+-     void
+-     handler (int signum)
+-     {
+-       if (defer_signal)
+-         signal_pending = signum;
+-       else
+-         ... /* "Really" handle the signal. */
+-     }
+-     
+-     ...
+-     
+-     void
+-     update_mumble (int frob)
+-     {
+-       /* Prevent signals from having immediate effect. */
+-       defer_signal++;
+-       /* Now update `mumble', without worrying about interruption. */
+-       mumble.a = 1;
+-       mumble.b = hack ();
+-       mumble.c = frob;
+-       /* We have updated `mumble'.  Handle any signal that came in. */
+-       defer_signal--;
+-       if (defer_signal == 0 && signal_pending != 0)
+-         raise (signal_pending);
+-     }
+-
+-   Note how the particular signal that arrives is stored in
+-`signal_pending'.  That way, we can handle several types of
+-inconvenient signals with the same mechanism.
+-
+-   We increment and decrement `defer_signal' so that nested critical
+-sections will work properly; thus, if `update_mumble' were called with
+-`signal_pending' already nonzero, signals would be deferred not only
+-within `update_mumble', but also within the caller.  This is also why
+-we do not check `signal_pending' if `defer_signal' is still nonzero.
+-
+-   The incrementing and decrementing of `defer_signal' require more
+-than one instruction; it is possible for a signal to happen in the
+-middle.  But that does not cause any problem.  If the signal happens
+-early enough to see the value from before the increment or decrement,
+-that is equivalent to a signal which came before the beginning of the
+-increment or decrement, which is a case that works properly.
+-
+-   It is absolutely vital to decrement `defer_signal' before testing
+-`signal_pending', because this avoids a subtle bug.  If we did these
+-things in the other order, like this,
+-
+-       if (defer_signal == 1 && signal_pending != 0)
+-         raise (signal_pending);
+-       defer_signal--;
+-
+-then a signal arriving in between the `if' statement and the decrement
+-would be effectively "lost" for an indefinite amount of time.  The
+-handler would merely set `defer_signal', but the program having already
+-tested this variable, it would not test the variable again.
+-
+-   Bugs like these are called "timing errors".  They are especially bad
+-because they happen only rarely and are nearly impossible to reproduce.
+-You can't expect to find them with a debugger as you would find a
+-reproducible bug.  So it is worth being especially careful to avoid
+-them.
+-
+-   (You would not be tempted to write the code in this order, given the
+-use of `defer_signal' as a counter which must be tested along with
+-`signal_pending'.  After all, testing for zero is cleaner than testing
+-for one.  But if you did not use `defer_signal' as a counter, and gave
+-it values of zero and one only, then either order might seem equally
+-simple.  This is a further advantage of using a counter for
+-`defer_signal': it will reduce the chance you will write the code in
+-the wrong order and create a subtle bug.)
+-
+-
+-File: libc.info,  Node: Waiting for a Signal,  Next: Signal Stack,  Prev: 
Blocking Signals,  Up: Signal Handling
+-
+-Waiting for a Signal
+-====================
+-
+-   If your program is driven by external events, or uses signals for
+-synchronization, then when it has nothing to do it should probably wait
+-until a signal arrives.
+-
+-* Menu:
+-
+-* Using Pause::                 The simple way, using `pause'.
+-* Pause Problems::              Why the simple way is often not very good.
+-* Sigsuspend::                  Reliably waiting for a specific signal.
+-
+-
+-File: libc.info,  Node: Using Pause,  Next: Pause Problems,  Up: Waiting for 
a Signal
+-
+-Using `pause'
+--------------
+-
+-   The simple way to wait until a signal arrives is to call `pause'.
+-Please read about its disadvantages, in the following section, before
+-you use it.
+-
+- - Function: int pause ()
+-     The `pause' function suspends program execution until a signal
+-     arrives whose action is either to execute a handler function, or to
+-     terminate the process.
+-
+-     If the signal causes a handler function to be executed, then
+-     `pause' returns.  This is considered an unsuccessful return (since
+-     "successful" behavior would be to suspend the program forever), so
+-     the return value is `-1'.  Even if you specify that other
+-     primitives should resume when a system handler returns (*note
+-     Interrupted Primitives::.), this has no effect on `pause'; it
+-     always fails when a signal is handled.
+-
+-     The following `errno' error conditions are defined for this
+-     function:
+-
+-    `EINTR'
+-          The function was interrupted by delivery of a signal.
+-
+-     If the signal causes program termination, `pause' doesn't return
+-     (obviously).
+-
+-     The `pause' function is declared in  `unistd.h'.
+-
+-
+-File: libc.info,  Node: Pause Problems,  Next: Sigsuspend,  Prev: Using 
Pause,  Up: Waiting for a Signal
+-
+-Problems with `pause'
+----------------------
+-
+-   The simplicity of `pause' can conceal serious timing errors that can
+-make a program hang mysteriously.
+-
+-   It is safe to use `pause' if the real work of your program is done
+-by the signal handlers themselves, and the "main program" does nothing
+-but call `pause'.  Each time a signal is delivered, the handler will do
+-the next batch of work that is to be done, and then return, so that the
+-main loop of the program can call `pause' again.
+-
+-   You can't safely use `pause' to wait until one more signal arrives,
+-and then resume real work.  Even if you arrange for the signal handler
+-to cooperate by setting a flag, you still can't use `pause' reliably.
+-Here is an example of this problem:
+-
+-     /* `usr_interrupt' is set by the signal handler.  */
+-     if (!usr_interrupt)
+-       pause ();
+-     
+-     /* Do work once the signal arrives.  */
+-     ...
+-
+-This has a bug: the signal could arrive after the variable
+-`usr_interrupt' is checked, but before the call to `pause'.  If no
+-further signals arrive, the process would never wake up again.
+-
+-   You can put an upper limit on the excess waiting by using `sleep' in
+-a loop, instead of using `pause'.  (*Note Sleeping::, for more about
+-`sleep'.)  Here is what this looks like:
+-
+-     /* `usr_interrupt' is set by the signal handler.
+-     while (!usr_interrupt)
+-       sleep (1);
+-     
+-     /* Do work once the signal arrives.  */
+-     ...
+-
+-   For some purposes, that is good enough.  But with a little more
+-complexity, you can wait reliably until a particular signal handler is
+-run, using `sigsuspend'.  *Note Sigsuspend::.
+-
+-
+-File: libc.info,  Node: Sigsuspend,  Prev: Pause Problems,  Up: Waiting for a 
Signal
+-
+-Using `sigsuspend'
+-------------------
+-
+-   The clean and reliable way to wait for a signal to arrive is to
+-block it and then use `sigsuspend'.  By using `sigsuspend' in a loop,
+-you can wait for certain kinds of signals, while letting other kinds of
+-signals be handled by their handlers.
+-
+- - Function: int sigsuspend (const sigset_t *SET)
+-     This function replaces the process's signal mask with SET and then
+-     suspends the process until a signal is delivered whose action is
+-     either to terminate the process or invoke a signal handling
+-     function.  In other words, the program is effectively suspended
+-     until one of the signals that is not a member of SET arrives.
+-
+-     If the process is woken up by deliver of a signal that invokes a
+-     handler function, and the handler function returns, then
+-     `sigsuspend' also returns.
+-
+-     The mask remains SET only as long as `sigsuspend' is waiting.  The
+-     function `sigsuspend' always restores the previous signal mask
+-     when it returns.
+-
+-     The return value and error conditions are the same as for `pause'.
+-
+-   With `sigsuspend', you can replace the `pause' or `sleep' loop in
+-the previous section with something completely reliable:
+-
+-     sigset_t mask, oldmask;
+-     
+-     ...
+-     
+-     /* Set up the mask of signals to temporarily block. */
+-     sigemptyset (&mask);
+-     sigaddset (&mask, SIGUSR1);
+-     
+-     ...
+-     
+-     /* Wait for a signal to arrive. */
+-     sigprocmask (SIG_BLOCK, &mask, &oldmask);
+-     while (!usr_interrupt)
+-       sigsuspend (&oldmask);
+-     sigprocmask (SIG_UNBLOCK, &mask, NULL);
+-
+-   This last piece of code is a little tricky.  The key point to
+-remember here is that when `sigsuspend' returns, it resets the process's
+-signal mask to the original value, the value from before the call to
+-`sigsuspend'--in this case, the `SIGUSR1' signal is once again blocked.
+-The second call to `sigprocmask' is necessary to explicitly unblock
+-this signal.
+-
+-   One other point: you may be wondering why the `while' loop is
+-necessary at all, since the program is apparently only waiting for one
+-`SIGUSR1' signal.  The answer is that the mask passed to `sigsuspend'
+-permits the process to be woken up by the delivery of other kinds of
+-signals, as well--for example, job control signals.  If the process is
+-woken up by a signal that doesn't set `usr_interrupt', it just suspends
+-itself again until the "right" kind of signal eventually arrives.
+-
+-   This technique takes a few more lines of preparation, but that is
+-needed just once for each kind of wait criterion you want to use.  The
+-code that actually waits is just four lines.
+-
+-
+-File: libc.info,  Node: Signal Stack,  Next: BSD Signal Handling,  Prev: 
Waiting for a Signal,  Up: Signal Handling
+-
+-Using a Separate Signal Stack
+-=============================
+-
+-   A signal stack is a special area of memory to be used as the
+-execution stack during signal handlers.  It should be fairly large, to
+-avoid any danger that it will overflow in turn; the macro `SIGSTKSZ' is
+-defined to a canonical size for signal stacks.  You can use `malloc' to
+-allocate the space for the stack.  Then call `sigaltstack' or
+-`sigstack' to tell the system to use that space for the signal stack.
+-
+-   You don't need to write signal handlers differently in order to use a
+-signal stack.  Switching from one stack to the other happens
+-automatically.  (Some non-GNU debuggers on some machines may get
+-confused if you examine a stack trace while a handler that uses the
+-signal stack is running.)
+-
+-   There are two interfaces for telling the system to use a separate
+-signal stack.  `sigstack' is the older interface, which comes from 4.2
+-BSD.  `sigaltstack' is the newer interface, and comes from 4.4 BSD.
+-The `sigaltstack' interface has the advantage that it does not require
+-your program to know which direction the stack grows, which depends on
+-the specific machine and operating system.
+-
+- - Data Type: struct sigaltstack
+-     This structure describes a signal stack.  It contains the
+-     following members:
+-
+-    `void *ss_sp'
+-          This points to the base of the signal stack.
+-
+-    `size_t ss_size'
+-          This is the size (in bytes) of the signal stack which `ss_sp'
+-          points to.  You should set this to however much space you
+-          allocated for the stack.
+-
+-          There are two macros defined in `signal.h' that you should
+-          use in calculating this size:
+-
+-         `SIGSTKSZ'
+-               This is the canonical size for a signal stack.  It is
+-               judged to be sufficient for normal uses.
+-
+-         `MINSIGSTKSZ'
+-               This is the amount of signal stack space the operating
+-               system needs just to implement signal delivery.  The
+-               size of a signal stack *must* be greater than this.
+-
+-               For most cases, just using `SIGSTKSZ' for `ss_size' is
+-               sufficient.  But if you know how much stack space your
+-               program's signal handlers will need, you may want to use
+-               a different size.  In this case, you should allocate
+-               `MINSIGSTKSZ' additional bytes for the signal stack and
+-               increase `ss_size' accordingly.
+-
+-    `int ss_flags'
+-          This field contains the bitwise OR of these flags:
+-
+-         `SA_DISABLE'
+-               This tells the system that it should not use the signal
+-               stack.
+-
+-         `SA_ONSTACK'
+-               This is set by the system, and indicates that the signal
+-               stack is currently in use.  If this bit is not set, then
+-               signals will be delivered on the normal user stack.
+-
+- - Function: int sigaltstack (const struct sigaltstack *STACK, struct
+-          sigaltstack *OLDSTACK)
+-     The `sigaltstack' function specifies an alternate stack for use
+-     during signal handling.  When a signal is received by the process
+-     and its action indicates that the signal stack is used, the system
+-     arranges a switch to the currently installed signal stack while
+-     the handler for that signal is executed.
+-
+-     If OLDSTACK is not a null pointer, information about the currently
+-     installed signal stack is returned in the location it points to.
+-     If STACK is not a null pointer, then this is installed as the new
+-     stack for use by signal handlers.
+-
+-     The return value is `0' on success and `-1' on failure.  If
+-     `sigaltstack' fails, it sets `errno' to one of these values:
+-
+-    `'
+-    `EINVAL'
+-          You tried to disable a stack that was in fact currently in
+-          use.
+-
+-    `ENOMEM'
+-          The size of the alternate stack was too small.  It must be
+-          greater than `MINSIGSTKSZ'.
+-
+-   Here is the older `sigstack' interface.  You should use
+-`sigaltstack' instead on systems that have it.
+-
+- - Data Type: struct sigstack
+-     This structure describes a signal stack.  It contains the
+-     following members:
+-
+-    `void *ss_sp'
+-          This is the stack pointer.  If the stack grows downwards on
+-          your machine, this should point to the top of the area you
+-          allocated.  If the stack grows upwards, it should point to
+-          the bottom.
+-
+-    `int ss_onstack'
+-          This field is true if the process is currently using this
+-          stack.
+-
+- - Function: int sigstack (const struct sigstack *STACK, struct
+-          sigstack *OLDSTACK)
+-     The `sigstack' function specifies an alternate stack for use during
+-     signal handling.  When a signal is received by the process and its
+-     action indicates that the signal stack is used, the system
+-     arranges a switch to the currently installed signal stack while
+-     the handler for that signal is executed.
+-
+-     If OLDSTACK is not a null pointer, information about the currently
+-     installed signal stack is returned in the location it points to.
+-     If STACK is not a null pointer, then this is installed as the new
+-     stack for use by signal handlers.
+-
+-     The return value is `0' on success and `-1' on failure.
+-
+-
+-File: libc.info,  Node: BSD Signal Handling,  Prev: Signal Stack,  Up: Signal 
Handling
+-
+-BSD Signal Handling
+-===================
+-
+-   This section describes alternative signal handling functions derived
+-from BSD Unix.  These facilities were an advance, in their time; today,
+-they are mostly obsolete, and supported mainly for compatibility with
+-BSD Unix.
+-
+-   There are many similarities between the BSD and POSIX signal handling
+-facilities, because the POSIX facilities were inspired by the BSD
+-facilities.  Besides having different names for all the functions to
+-avoid conflicts, the main differences between the two are:
+-
+-   * BSD Unix represents signal masks as an `int' bit mask, rather than
+-     as a `sigset_t' object.
+-
+-   * The BSD facilities use a different default for whether an
+-     interrupted primitive should fail or resume.  The POSIX facilities
+-     make system calls fail unless you specify that they should resume.
+-     With the BSD facility, the default is to make system calls resume
+-     unless you say they should fail.  *Note Interrupted Primitives::.
+-
+-   The BSD facilities are declared in `signal.h'.
+-
+-* Menu:
+-
+-* BSD Handler::                 BSD Function to Establish a Handler.
+-* Blocking in BSD::             BSD Functions for Blocking Signals.
+-
+-
+-File: libc.info,  Node: BSD Handler,  Next: Blocking in BSD,  Up: BSD Signal 
Handling
+-
+-BSD Function to Establish a Handler
+------------------------------------
+-
+- - Data Type: struct sigvec
+-     This data type is the BSD equivalent of `struct sigaction' (*note
+-     Advanced Signal Handling::.); it is used to specify signal actions
+-     to the `sigvec' function.  It contains the following members:
+-
+-    `sighandler_t sv_handler'
+-          This is the handler function.
+-
+-    `int sv_mask'
+-          This is the mask of additional signals to be blocked while
+-          the handler function is being called.
+-
+-    `int sv_flags'
+-          This is a bit mask used to specify various flags which affect
+-          the behavior of the signal.  You can also refer to this field
+-          as `sv_onstack'.
+-
+-   These symbolic constants can be used to provide values for the
+-`sv_flags' field of a `sigvec' structure.  This field is a bit mask
+-value, so you bitwise-OR the flags of interest to you together.
+-
+- - Macro: int SV_ONSTACK
+-     If this bit is set in the `sv_flags' field of a `sigvec'
+-     structure, it means to use the signal stack when delivering the
+-     signal.
+-
+- - Macro: int SV_INTERRUPT
+-     If this bit is set in the `sv_flags' field of a `sigvec'
+-     structure, it means that system calls interrupted by this kind of
+-     signal should not be restarted if the handler returns; instead,
+-     the system calls should return with a `EINTR' error status.  *Note
+-     Interrupted Primitives::.
+-
+- - Macro: int SV_RESETHAND
+-     If this bit is set in the `sv_flags' field of a `sigvec'
+-     structure, it means to reset the action for the signal back to
+-     `SIG_DFL' when the signal is received.
+-
+- - Function: int sigvec (int SIGNUM, const struct sigvec *ACTION,struct
+-          sigvec *OLD-ACTION)
+-     This function is the equivalent of `sigaction' (*note Advanced
+-     Signal Handling::.); it installs the action ACTION for the signal
+-     SIGNUM, returning information about the previous action in effect
+-     for that signal in OLD-ACTION.
+-
+- - Function: int siginterrupt (int SIGNUM, int FAILFLAG)
+-     This function specifies which approach to use when certain
+-     primitives are interrupted by handling signal SIGNUM.  If FAILFLAG
+-     is false, signal SIGNUM restarts primitives.  If FAILFLAG is true,
+-     handling SIGNUM causes these primitives to fail with error code
+-     `EINTR'.  *Note Interrupted Primitives::.
+-
+-
+-File: libc.info,  Node: Blocking in BSD,  Prev: BSD Handler,  Up: BSD Signal 
Handling
+-
+-BSD Functions for Blocking Signals
+-----------------------------------
+-
+- - Macro: int sigmask (int SIGNUM)
+-     This macro returns a signal mask that has the bit for signal SIGNUM
+-     set.  You can bitwise-OR the results of several calls to `sigmask'
+-     together to specify more than one signal.  For example,
+-
+-          (sigmask (SIGTSTP) | sigmask (SIGSTOP)
+-           | sigmask (SIGTTIN) | sigmask (SIGTTOU))
+-
+-     specifies a mask that includes all the job-control stop signals.
+-
+- - Function: int sigblock (int MASK)
+-     This function is equivalent to `sigprocmask' (*note Process Signal
+-     Mask::.) with a HOW argument of `SIG_BLOCK': it adds the signals
+-     specified by MASK to the calling process's set of blocked signals.
+-     The return value is the previous set of blocked signals.
+-
+- - Function: int sigsetmask (int MASK)
+-     This function equivalent to `sigprocmask' (*note Process Signal
+-     Mask::.) with a HOW argument of `SIG_SETMASK': it sets the calling
+-     process's signal mask to MASK.  The return value is the previous
+-     set of blocked signals.
+-
+- - Function: int sigpause (int MASK)
+-     This function is the equivalent of `sigsuspend' (*note Waiting for
+-     a Signal::.):  it sets the calling process's signal mask to MASK,
+-     and waits for a signal to arrive.  On return the previous set of
+-     blocked signals is restored.
+-
+-
+-File: libc.info,  Node: Process Startup,  Next: Processes,  Prev: Signal 
Handling,  Up: Top
+-
+-Process Startup and Termination
+-*******************************
+-
+-   "Processes" are the primitive units for allocation of system
+-resources.  Each process has its own address space and (usually) one
+-thread of control.  A process executes a program; you can have multiple
+-processes executing the same program, but each process has its own copy
+-of the program within its own address space and executes it
+-independently of the other copies.
+-
+-   This chapter explains what your program should do to handle the
+-startup of a process, to terminate its process, and to receive
+-information (arguments and the environment) from the parent process.
+-
+-* Menu:
+-
+-* Program Arguments::           Parsing your program's command-line arguments.
+-* Environment Variables::       How to access parameters inherited from
+-                               a parent process.
+-* Program Termination::         How to cause a process to terminate and
+-                               return status information to its parent.
+-
+-
+-File: libc.info,  Node: Program Arguments,  Next: Environment Variables,  Up: 
Process Startup
+-
+-Program Arguments
+-=================
+-
+-   The system starts a C program by calling the function `main'.  It is
+-up to you to write a function named `main'--otherwise, you won't even
+-be able to link your program without errors.
+-
+-   In ISO C you can define `main' either to take no arguments, or to
+-take two arguments that represent the command line arguments to the
+-program, like this:
+-
+-     int main (int ARGC, char *ARGV[])
+-
+-   The command line arguments are the whitespace-separated tokens given
+-in the shell command used to invoke the program; thus, in `cat foo
+-bar', the arguments are `foo' and `bar'.  The only way a program can
+-look at its command line arguments is via the arguments of `main'.  If
+-`main' doesn't take arguments, then you cannot get at the command line.
+-
+-   The value of the ARGC argument is the number of command line
+-arguments.  The ARGV argument is a vector of C strings; its elements
+-are the individual command line argument strings.  The file name of the
+-program being run is also included in the vector as the first element;
+-the value of ARGC counts this element.  A null pointer always follows
+-the last element: `ARGV[ARGC]' is this null pointer.
+-
+-   For the command `cat foo bar', ARGC is 3 and ARGV has three
+-elements, `"cat"', `"foo"' and `"bar"'.
+-
+-   If the syntax for the command line arguments to your program is
+-simple enough, you can simply pick the arguments off from ARGV by hand.
+-But unless your program takes a fixed number of arguments, or all of the
+-arguments are interpreted in the same way (as file names, for example),
+-you are usually better off using `getopt' to do the parsing.
+-
+-   In Unix systems you can define `main' a third way, using three
+-arguments:
+-
+-     int main (int ARGC, char *ARGV[], char *ENVP)
+-
+-   The first two arguments are just the same.  The third argument ENVP
+-gives the process's environment; it is the same as the value of
+-`environ'.  *Note Environment Variables::.  POSIX.1 does not allow this
+-three-argument form, so to be portable it is best to write `main' to
+-take two arguments, and use the value of `environ'.
+-
+-* Menu:
+-
+-* Argument Syntax::             By convention, options start with a hyphen.
+-* Parsing Options::             The `getopt' function.
+-* Example of Getopt::           An example of parsing options with `getopt'.
+-* Long Options::                GNU suggests utilities accept long-named 
options.
+-                         Here is how to do that.
+-* Long Option Example::         An example of using `getopt_long'.
+-* Suboptions::                  Some programs need more detailed options.
+-* Suboptions Example::          This shows how it could be done for `mount'.
+-
+-
+-File: libc.info,  Node: Argument Syntax,  Next: Parsing Options,  Up: Program 
Arguments
+-
+-Program Argument Syntax Conventions
+------------------------------------
+-
+-   POSIX recommends these conventions for command line arguments.
+-`getopt' (*note Parsing Options::.) makes it easy to implement them.
+-
+-   * Arguments are options if they begin with a hyphen delimiter (`-').
+-
+-   * Multiple options may follow a hyphen delimiter in a single token if
+-     the options do not take arguments.  Thus, `-abc' is equivalent to
+-     `-a -b -c'.
+-
+-   * Option names are single alphanumeric characters (as for `isalnum';
+-     see *Note Classification of Characters::).
+-
+-   * Certain options require an argument.  For example, the `-o' command
+-     of the `ld' command requires an argument--an output file name.
+-
+-   * An option and its argument may or may not appear as separate
+-     tokens.  (In other words, the whitespace separating them is
+-     optional.)  Thus, `-o foo' and `-ofoo' are equivalent.
+-
+-   * Options typically precede other non-option arguments.
+-
+-     The implementation of `getopt' in the GNU C library normally makes
+-     it appear as if all the option arguments were specified before all
+-     the non-option arguments for the purposes of parsing, even if the
+-     user of your program intermixed option and non-option arguments.
+-     It does this by reordering the elements of the ARGV array.  This
+-     behavior is nonstandard; if you want to suppress it, define the
+-     `_POSIX_OPTION_ORDER' environment variable.  *Note Standard
+-     Environment::.
+-
+-   * The argument `--' terminates all options; any following arguments
+-     are treated as non-option arguments, even if they begin with a
+-     hyphen.
+-
+-   * A token consisting of a single hyphen character is interpreted as
+-     an ordinary non-option argument.  By convention, it is used to
+-     specify input from or output to the standard input and output
+-     streams.
+-
+-   * Options may be supplied in any order, or appear multiple times.
+-     The interpretation is left up to the particular application
+-     program.
+-
+-   GNU adds "long options" to these conventions.  Long options consist
+-of `--' followed by a name made of alphanumeric characters and dashes.
+-Option names are typically one to three words long, with hyphens to
+-separate words.  Users can abbreviate the option names as long as the
+-abbreviations are unique.
+-
+-   To specify an argument for a long option, write `--NAME=VALUE'.
+-This syntax enables a long option to accept an argument that is itself
+-optional.
+-
+-   Eventually, the GNU system will provide completion for long option
+-names in the shell.
+-
+-
+-File: libc.info,  Node: Parsing Options,  Next: Example of Getopt,  Prev: 
Argument Syntax,  Up: Program Arguments
+-
+-Parsing Program Options
+------------------------
+-
+-   Here are the details about how to call the `getopt' function.  To
+-use this facility, your program must include the header file `unistd.h'.
+-
+- - Variable: int opterr
+-     If the value of this variable is nonzero, then `getopt' prints an
+-     error message to the standard error stream if it encounters an
+-     unknown option character or an option with a missing required
+-     argument.  This is the default behavior.  If you set this variable
+-     to zero, `getopt' does not print any messages, but it still
+-     returns the character `?' to indicate an error.
+-
+- - Variable: int optopt
+-     When `getopt' encounters an unknown option character or an option
+-     with a missing required argument, it stores that option character
+-     in this variable.  You can use this for providing your own
+-     diagnostic messages.
+-
+- - Variable: int optind
+-     This variable is set by `getopt' to the index of the next element
+-     of the ARGV array to be processed.  Once `getopt' has found all of
+-     the option arguments, you can use this variable to determine where
+-     the remaining non-option arguments begin.  The initial value of
+-     this variable is `1'.
+-
+- - Variable: char * optarg
+-     This variable is set by `getopt' to point at the value of the
+-     option argument, for those options that accept arguments.
+-
+- - Function: int getopt (int ARGC, char **ARGV, const char *OPTIONS)
+-     The `getopt' function gets the next option argument from the
+-     argument list specified by the ARGV and ARGC arguments.  Normally
+-     these values come directly from the arguments received by `main'.
+-
+-     The OPTIONS argument is a string that specifies the option
+-     characters that are valid for this program.  An option character
+-     in this string can be followed by a colon (`:') to indicate that
+-     it takes a required argument.
+-
+-     If the OPTIONS argument string begins with a hyphen (`-'), this is
+-     treated specially.  It permits arguments that are not options to be
+-     returned as if they were associated with option character `\0'.
+-
+-     The `getopt' function returns the option character for the next
+-     command line option.  When no more option arguments are available,
+-     it returns `-1'.  There may still be more non-option arguments; you
+-     must compare the external variable `optind' against the ARGC
+-     parameter to check this.
+-
+-     If the option has an argument, `getopt' returns the argument by
+-     storing it in the variable OPTARG.  You don't ordinarily need to
+-     copy the `optarg' string, since it is a pointer into the original
+-     ARGV array, not into a static area that might be overwritten.
+-
+-     If `getopt' finds an option character in ARGV that was not
+-     included in OPTIONS, or a missing option argument, it returns `?'
+-     and sets the external variable `optopt' to the actual option
+-     character.  If the first character of OPTIONS is a colon (`:'),
+-     then `getopt' returns `:' instead of `?' to indicate a missing
+-     option argument.  In addition, if the external variable `opterr'
+-     is nonzero (which is the default), `getopt' prints an error
+-     message.
+-
+-
+-File: libc.info,  Node: Example of Getopt,  Next: Long Options,  Prev: 
Parsing Options,  Up: Program Arguments
+-
+-Example of Parsing Arguments with `getopt'
+-------------------------------------------
+-
+-   Here is an example showing how `getopt' is typically used.  The key
+-points to notice are:
+-
+-   * Normally, `getopt' is called in a loop.  When `getopt' returns
+-     `-1', indicating no more options are present, the loop terminates.
+-
+-   * A `switch' statement is used to dispatch on the return value from
+-     `getopt'.  In typical use, each case just sets a variable that is
+-     used later in the program.
+-
+-   * A second loop is used to process the remaining non-option
+-     arguments.
+-
+-     #include <unistd.h>
+-     #include <stdio.h>
+-     
+-     int
+-     main (int argc, char **argv)
+-     {
+-       int aflag = 0;
+-       int bflag = 0;
+-       char *cvalue = NULL;
+-       int index;
+-       int c;
+-     
+-       opterr = 0;
+-
+-     while ((c = getopt (argc, argv, "abc:")) != -1)
+-         switch (c)
+-           {
+-           case 'a':
+-             aflag = 1;
+-             break;
+-           case 'b':
+-             bflag = 1;
+-             break;
+-           case 'c':
+-             cvalue = optarg;
+-             break;
+-           case '?':
+-             if (isprint (optopt))
+-               fprintf (stderr, "Unknown option `-%c'.\n", optopt);
+-             else
+-               fprintf (stderr,
+-                        "Unknown option character `\\x%x'.\n",
+-                        optopt);
+-             return 1;
+-           default:
+-             abort ();
+-           }
+-
+-     printf ("aflag = %d, bflag = %d, cvalue = %s\n", aflag, bflag, cvalue);
+-     
+-       for (index = optind; index < argc; index++)
+-         printf ("Non-option argument %s\n", argv[index]);
+-       return 0;
+-     }
+-
+-   Here are some examples showing what this program prints with
+-different combinations of arguments:
+-
+-     % testopt
+-     aflag = 0, bflag = 0, cvalue = (null)
+-     
+-     % testopt -a -b
+-     aflag = 1, bflag = 1, cvalue = (null)
+-     
+-     % testopt -ab
+-     aflag = 1, bflag = 1, cvalue = (null)
+-     
+-     % testopt -c foo
+-     aflag = 0, bflag = 0, cvalue = foo
+-     
+-     % testopt -cfoo
+-     aflag = 0, bflag = 0, cvalue = foo
+-     
+-     % testopt arg1
+-     aflag = 0, bflag = 0, cvalue = (null)
+-     Non-option argument arg1
+-     
+-     % testopt -a arg1
+-     aflag = 1, bflag = 0, cvalue = (null)
+-     Non-option argument arg1
+-     
+-     % testopt -c foo arg1
+-     aflag = 0, bflag = 0, cvalue = foo
+-     Non-option argument arg1
+-     
+-     % testopt -a -- -b
+-     aflag = 1, bflag = 0, cvalue = (null)
+-     Non-option argument -b
+-     
+-     % testopt -a -
+-     aflag = 1, bflag = 0, cvalue = (null)
+-     Non-option argument -
+-
+-
+-File: libc.info,  Node: Long Options,  Next: Long Option Example,  Prev: 
Example of Getopt,  Up: Program Arguments
+-
+-Parsing Long Options
+---------------------
+-
+-   To accept GNU-style long options as well as single-character options,
+-use `getopt_long' instead of `getopt'.  This function is declared in
+-`getopt.h', not `unistd.h'.  You should make every program accept long
+-options if it uses any options, for this takes little extra work and
+-helps beginners remember how to use the program.
+-
+- - Data Type: struct option
+-     This structure describes a single long option name for the sake of
+-     `getopt_long'.  The argument LONGOPTS must be an array of these
+-     structures, one for each long option.  Terminate the array with an
+-     element containing all zeros.
+-
+-     The `struct option' structure has these fields:
+-
+-    `const char *name'
+-          This field is the name of the option.  It is a string.
+-
+-    `int has_arg'
+-          This field says whether the option takes an argument.  It is
+-          an integer, and there are three legitimate values:
+-          `no_argument', `required_argument' and `optional_argument'.
+-
+-    `int *flag'
+-    `int val'
+-          These fields control how to report or act on the option when
+-          it occurs.
+-
+-          If `flag' is a null pointer, then the `val' is a value which
+-          identifies this option.  Often these values are chosen to
+-          uniquely identify particular long options.
+-
+-          If `flag' is not a null pointer, it should be the address of
+-          an `int' variable which is the flag for this option.  The
+-          value in `val' is the value to store in the flag to indicate
+-          that the option was seen.
+-
+- - Function: int getopt_long (int ARGC, char **ARGV, const char
+-          *SHORTOPTS, struct option *LONGOPTS, int *INDEXPTR)
+-     Decode options from the vector ARGV (whose length is ARGC).  The
+-     argument SHORTOPTS describes the short options to accept, just as
+-     it does in `getopt'.  The argument LONGOPTS describes the long
+-     options to accept (see above).
+-
+-     When `getopt_long' encounters a short option, it does the same
+-     thing that `getopt' would do: it returns the character code for the
+-     option, and stores the options argument (if it has one) in
+-     `optarg'.
+-
+-     When `getopt_long' encounters a long option, it takes actions based
+-     on the `flag' and `val' fields of the definition of that option.
+-
+-     If `flag' is a null pointer, then `getopt_long' returns the
+-     contents of `val' to indicate which option it found.  You should
+-     arrange distinct values in the `val' field for options with
+-     different meanings, so you can decode these values after
+-     `getopt_long' returns.  If the long option is equivalent to a short
+-     option, you can use the short option's character code in `val'.
+-
+-     If `flag' is not a null pointer, that means this option should just
+-     set a flag in the program.  The flag is a variable of type `int'
+-     that you define.  Put the address of the flag in the `flag' field.
+-     Put in the `val' field the value you would like this option to
+-     store in the flag.  In this case, `getopt_long' returns `0'.
+-
+-     For any long option, `getopt_long' tells you the index in the array
+-     LONGOPTS of the options definition, by storing it into
+-     `*INDEXPTR'.  You can get the name of the option with
+-     `LONGOPTS[*INDEXPTR].name'.  So you can distinguish among long
+-     options either by the values in their `val' fields or by their
+-     indices.  You can also distinguish in this way among long options
+-     that set flags.
+-
+-     When a long option has an argument, `getopt_long' puts the argument
+-     value in the variable `optarg' before returning.  When the option
+-     has no argument, the value in `optarg' is a null pointer.  This is
+-     how you can tell whether an optional argument was supplied.
+-
+-     When `getopt_long' has no more options to handle, it returns `-1',
+-     and leaves in the variable `optind' the index in ARGV of the next
+-     remaining argument.
+-
+-
+-File: libc.info,  Node: Long Option Example,  Next: Suboptions,  Prev: Long 
Options,  Up: Program Arguments
+-
+-Example of Parsing Long Options
+--------------------------------
+-
+-     #include <stdio.h>
+-     #include <stdlib.h>
+-     #include <getopt.h>
+-     
+-     /* Flag set by `--verbose'. */
+-     static int verbose_flag;
+-     
+-     int
+-     main (argc, argv)
+-          int argc;
+-          char **argv;
+-     {
+-       int c;
+-     
+-       while (1)
+-         {
+-           static struct option long_options[] =
+-             {
+-               /* These options set a flag. */
+-               {"verbose", 0, &verbose_flag, 1},
+-               {"brief", 0, &verbose_flag, 0},
+-               /* These options don't set a flag.
+-                  We distinguish them by their indices. */
+-               {"add", 1, 0, 0},
+-               {"append", 0, 0, 0},
+-               {"delete", 1, 0, 0},
+-               {"create", 0, 0, 0},
+-               {"file", 1, 0, 0},
+-               {0, 0, 0, 0}
+-             };
+-           /* `getopt_long' stores the option index here. */
+-           int option_index = 0;
+-     
+-           c = getopt_long (argc, argv, "abc:d:",
+-                            long_options, &option_index);
+-     
+-           /* Detect the end of the options. */
+-           if (c == -1)
+-             break;
+-     
+-           switch (c)
+-             {
+-             case 0:
+-               /* If this option set a flag, do nothing else now. */
+-               if (long_options[option_index].flag != 0)
+-                 break;
+-               printf ("option %s", long_options[option_index].name);
+-               if (optarg)
+-                 printf (" with arg %s", optarg);
+-               printf ("\n");
+-               break;
+-     
+-             case 'a':
+-               puts ("option -a\n");
+-               break;
+-     
+-             case 'b':
+-               puts ("option -b\n");
+-               break;
+-     
+-             case 'c':
+-               printf ("option -c with value `%s'\n", optarg);
+-               break;
+-     
+-             case 'd':
+-               printf ("option -d with value `%s'\n", optarg);
+-               break;
+-     
+-             case '?':
+-               /* `getopt_long' already printed an error message. */
+-               break;
+-     
+-             default:
+-               abort ();
+-             }
+-         }
+-     
+-       /* Instead of reporting `--verbose'
+-          and `--brief' as they are encountered,
+-          we report the final status resulting from them. */
+-       if (verbose_flag)
+-         puts ("verbose flag is set");
+-     
+-       /* Print any remaining command line arguments (not options). */
+-       if (optind < argc)
+-         {
+-           printf ("non-option ARGV-elements: ");
+-           while (optind < argc)
+-             printf ("%s ", argv[optind++]);
+-           putchar ('\n');
+-         }
+-     
+-       exit (0);
+-     }
+-
+-
+-File: libc.info,  Node: Suboptions,  Next: Suboptions Example,  Prev: Long 
Option Example,  Up: Program Arguments
+-
+-Parsing of Suboptions
+----------------------
+-
+-   Having a single level of options is sometimes not enough.  There
+-might be too many options which have to be available or a set of
+-options is closely related.
+-
+-   For this case some programs use suboptions.  One of the most
+-prominent programs is certainly `mount'(8).  The `-o' option take one
+-argument which itself is a comma separated list of options.  To ease the
+-programming of code like this the function `getsubopt' is available.
+-
+- - Function: int getsubopt (char **OPTIONP, const char* const *TOKENS,
+-          char **VALUEP)
+-     The OPTIONP parameter must be a pointer to a variable containing
+-     the address of the string to process.  When the function returns
+-     the reference is updated to point to the next suboption or to the
+-     terminating `\0' character if there is no more suboption available.
+-
+-     The TOKENS parameter references an array of strings containing the
+-     known suboptions.  All strings must be `\0' terminated and to mark
+-     the end a null pointer must be stored.  When `getsubopt' finds a
+-     possible legal suboption it compares it with all strings available
+-     in the TOKENS array and returns the index in the string as the
+-     indicator.
+-
+-     In case the suboption has an associated value introduced by a `='
+-     character, a pointer to the value is returned in VALUEP.  The
+-     string is `\0' terminated.  If no argument is available VALUEP is
+-     set to the null pointer.  By doing this the caller can check
+-     whether a necessary value is given or whether no unexpected value
+-     is present.
+-
+-     In case the next suboption in the string is not mentioned in the
+-     TOKENS array the starting address of the suboption including a
+-     possible value is returned in VALUEP and the return value of the
+-     function is `-1'.
+-
+-
+-File: libc.info,  Node: Suboptions Example,  Prev: Suboptions,  Up: Program 
Arguments
+-
+-Parsing of Suboptions Example
+------------------------------
+-
+-   The code which might appear in the `mount'(8) program is a perfect
+-example of the use of `getsubopt':
+-
+-     #include <stdio.h>
+-     #include <stdlib.h>
+-     
+-     int do_all;
+-     const char *type;
+-     int read_size;
+-     int write_size;
+-     int read_only;
+-     
+-     enum
+-     {
+-       RO_OPTION = 0,
+-       RW_OPTION,
+-       READ_SIZE_OPTION,
+-       WRITE_SIZE_OPTION
+-     };
+-     
+-     const char *mount_opts[] =
+-     {
+-       [RO_OPTION] = "ro",
+-       [RW_OPTION] = "rw",
+-       [READ_SIZE_OPTION] = "rsize",
+-       [WRITE_SIZE_OPTION] = "wsize"
+-     };
+-     
+-     int
+-     main (int argc, char *argv[])
+-     {
+-       char *subopts, *value;
+-       int opt;
+-     
+-       while ((opt = getopt (argc, argv, "at:o:")) != -1)
+-         switch (opt)
+-           {
+-           case 'a':
+-             do_all = 1;
+-             break;
+-           case 't':
+-             type = optarg;
+-             break;
+-           case 'o':
+-             subopts = optarg;
+-             while (*subopts != '\0')
+-               switch (getsubopt (&subopts, mount_opts, &value))
+-                 {
+-                 case RO_OPTION:
+-                   read_only = 1;
+-                   break;
+-                 case RW_OPTION:
+-                   read_only = 0;
+-                   break;
+-                 case READ_SIZE_OPTION:
+-                   if (value == NULL)
+-                     abort ();
+-                   read_size = atoi (value);
+-                   break;
+-                 case WRITE_SIZE_OPTION:
+-                   if (value == NULL)
+-                     abort ();
+-                   write_size = atoi (value);
+-                   break;
+-                 default:
+-                   /* Unknown suboption. */
+-                   printf ("Unknown suboption `%s'\n", value);
+-                   break;
+-                 }
+-             break;
+-           default:
+-             abort ();
+-           }
+-     
+-       /* Do the real work. */
+-     
+-       return 0;
+-     }
+-
+-
+-File: libc.info,  Node: Environment Variables,  Next: Program Termination,  
Prev: Program Arguments,  Up: Process Startup
+-
+-Environment Variables
+-=====================
+-
+-   When a program is executed, it receives information about the
+-context in which it was invoked in two ways.  The first mechanism uses
+-the ARGV and ARGC arguments to its `main' function, and is discussed in
+-*Note Program Arguments::.  The second mechanism uses "environment
+-variables" and is discussed in this section.
+-
+-   The ARGV mechanism is typically used to pass command-line arguments
+-specific to the particular program being invoked.  The environment, on
+-the other hand, keeps track of information that is shared by many
+-programs, changes infrequently, and that is less frequently used.
+-
+-   The environment variables discussed in this section are the same
+-environment variables that you set using assignments and the `export'
+-command in the shell.  Programs executed from the shell inherit all of
+-the environment variables from the shell.
+-
+-   Standard environment variables are used for information about the
+-user's home directory, terminal type, current locale, and so on; you
+-can define additional variables for other purposes.  The set of all
+-environment variables that have values is collectively known as the
+-"environment".
+-
+-   Names of environment variables are case-sensitive and must not
+-contain the character `='.  System-defined environment variables are
+-invariably uppercase.
+-
+-   The values of environment variables can be anything that can be
+-represented as a string.  A value must not contain an embedded null
+-character, since this is assumed to terminate the string.
+-
+-* Menu:
+-
+-* Environment Access::          How to get and set the values of
+-                         environment variables.
+-* Standard Environment::        These environment variables have
+-                         standard interpretations.
+-
+-
+-File: libc.info,  Node: Environment Access,  Next: Standard Environment,  Up: 
Environment Variables
+-
+-Environment Access
+-------------------
+-
+-   The value of an environment variable can be accessed with the
+-`getenv' function.  This is declared in the header file `stdlib.h'.
+-
+- - Function: char * getenv (const char *NAME)
+-     This function returns a string that is the value of the environment
+-     variable NAME.  You must not modify this string.  In some non-Unix
+-     systems not using the GNU library, it might be overwritten by
+-     subsequent calls to `getenv' (but not by any other library
+-     function).  If the environment variable NAME is not defined, the
+-     value is a null pointer.
+-
+- - Function: int putenv (const char *STRING)
+-     The `putenv' function adds or removes definitions from the
+-     environment.  If the STRING is of the form `NAME=VALUE', the
+-     definition is added to the environment.  Otherwise, the STRING is
+-     interpreted as the name of an environment variable, and any
+-     definition for this variable in the environment is removed.
+-
+-     The GNU library provides this function for compatibility with
+-     SVID; it may not be available in other systems.
+-
+-   You can deal directly with the underlying representation of
+-environment objects to add more variables to the environment (for
+-example, to communicate with another program you are about to execute;
+-see *Note Executing a File::).
+-
+- - Variable: char ** environ
+-     The environment is represented as an array of strings.  Each
+-     string is of the format `NAME=VALUE'.  The order in which strings
+-     appear in the environment is not significant, but the same NAME
+-     must not appear more than once.  The last element of the array is
+-     a null pointer.
+-
+-     This variable is declared in the header file `unistd.h'.
+-
+-     If you just want to get the value of an environment variable, use
+-     `getenv'.
+-
+-   Unix systems, and the GNU system, pass the initial value of
+-`environ' as the third argument to `main'.  *Note Program Arguments::.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-23 
glibc-2.0.1/manual/libc.info-23
+--- ../glibc-2.0.1/manual/libc.info-23 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-23    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1202 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Standard Environment,  Prev: Environment Access,  Up: 
Environment Variables
+-
+-Standard Environment Variables
+-------------------------------
+-
+-   These environment variables have standard meanings.  This doesn't
+-mean that they are always present in the environment; but if these
+-variables *are* present, they have these meanings.  You shouldn't try
+-to use these environment variable names for some other purpose.
+-
+-`HOME'
+-     This is a string representing the user's "home directory", or
+-     initial default working directory.
+-
+-     The user can set `HOME' to any value.  If you need to make sure to
+-     obtain the proper home directory for a particular user, you should
+-     not use `HOME'; instead, look up the user's name in the user
+-     database (*note User Database::.).
+-
+-     For most purposes, it is better to use `HOME', precisely because
+-     this lets the user specify the value.
+-
+-`LOGNAME'
+-     This is the name that the user used to log in.  Since the value in
+-     the environment can be tweaked arbitrarily, this is not a reliable
+-     way to identify the user who is running a process; a function like
+-     `getlogin' (*note Who Logged In::.) is better for that purpose.
+-
+-     For most purposes, it is better to use `LOGNAME', precisely because
+-     this lets the user specify the value.
+-
+-`PATH'
+-     A "path" is a sequence of directory names which is used for
+-     searching for a file.  The variable `PATH' holds a path used for
+-     searching for programs to be run.
+-
+-     The `execlp' and `execvp' functions (*note Executing a File::.)
+-     use this environment variable, as do many shells and other
+-     utilities which are implemented in terms of those functions.
+-
+-     The syntax of a path is a sequence of directory names separated by
+-     colons.  An empty string instead of a directory name stands for the
+-     current directory (*note Working Directory::.).
+-
+-     A typical value for this environment variable might be a string
+-     like:
+-
+-          :/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local/bin
+-
+-     This means that if the user tries to execute a program named `foo',
+-     the system will look for files named `foo', `/bin/foo',
+-     `/etc/foo', and so on.  The first of these files that exists is
+-     the one that is executed.
+-
+-`TERM'
+-     This specifies the kind of terminal that is receiving program
+-     output.  Some programs can make use of this information to take
+-     advantage of special escape sequences or terminal modes supported
+-     by particular kinds of terminals.  Many programs which use the
+-     termcap library (*note Find: (termcap)Finding a Terminal
+-     Description.) use the `TERM' environment variable, for example.
+-
+-`TZ'
+-     This specifies the time zone.  *Note TZ Variable::, for
+-     information about the format of this string and how it is used.
+-
+-`LANG'
+-     This specifies the default locale to use for attribute categories
+-     where neither `LC_ALL' nor the specific environment variable for
+-     that category is set.  *Note Locales::, for more information about
+-     locales.
+-
+-`LC_COLLATE'
+-     This specifies what locale to use for string sorting.
+-
+-`LC_CTYPE'
+-     This specifies what locale to use for character sets and character
+-     classification.
+-
+-`LC_MONETARY'
+-     This specifies what locale to use for formatting monetary values.
+-
+-`LC_NUMERIC'
+-     This specifies what locale to use for formatting numbers.
+-
+-`LC_TIME'
+-     This specifies what locale to use for formatting date/time values.
+-
+-`_POSIX_OPTION_ORDER'
+-     If this environment variable is defined, it suppresses the usual
+-     reordering of command line arguments by `getopt'.  *Note Argument
+-     Syntax::.
+-
+-
+-File: libc.info,  Node: Program Termination,  Prev: Environment Variables,  
Up: Process Startup
+-
+-Program Termination
+-===================
+-
+-   The usual way for a program to terminate is simply for its `main'
+-function to return.  The "exit status value" returned from the `main'
+-function is used to report information back to the process's parent
+-process or shell.
+-
+-   A program can also terminate normally by calling the `exit' function.
+-
+-   In addition, programs can be terminated by signals; this is
+-discussed in more detail in *Note Signal Handling::.  The `abort'
+-function causes a signal that kills the program.
+-
+-* Menu:
+-
+-* Normal Termination::          If a program calls `exit', a
+-                                 process terminates normally.
+-* Exit Status::                 The `exit status' provides information
+-                                 about why the process terminated.
+-* Cleanups on Exit::            A process can run its own cleanup
+-                                 functions upon normal termination.
+-* Aborting a Program::          The `abort' function causes
+-                                 abnormal program termination.
+-* Termination Internals::       What happens when a process terminates.
+-
+-
+-File: libc.info,  Node: Normal Termination,  Next: Exit Status,  Up: Program 
Termination
+-
+-Normal Termination
+-------------------
+-
+-   A process terminates normally when the program calls `exit'.
+-Returning from `main' is equivalent to calling `exit', and the value
+-that `main' returns is used as the argument to `exit'.
+-
+- - Function: void exit (int STATUS)
+-     The `exit' function terminates the process with status STATUS.
+-     This function does not return.
+-
+-   Normal termination causes the following actions:
+-
+-  1. Functions that were registered with the `atexit' or `on_exit'
+-     functions are called in the reverse order of their registration.
+-     This mechanism allows your application to specify its own
+-     "cleanup" actions to be performed at program termination.
+-     Typically, this is used to do things like saving program state
+-     information in a file, or unlocking locks in shared data bases.
+-
+-  2. All open streams are closed, writing out any buffered output data.
+-     See *Note Closing Streams::.  In addition, temporary files opened
+-     with the `tmpfile' function are removed; see *Note Temporary
+-     Files::.
+-
+-  3. `_exit' is called, terminating the program.  *Note Termination
+-     Internals::.
+-
+-
+-File: libc.info,  Node: Exit Status,  Next: Cleanups on Exit,  Prev: Normal 
Termination,  Up: Program Termination
+-
+-Exit Status
+------------
+-
+-   When a program exits, it can return to the parent process a small
+-amount of information about the cause of termination, using the "exit
+-status".  This is a value between 0 and 255 that the exiting process
+-passes as an argument to `exit'.
+-
+-   Normally you should use the exit status to report very broad
+-information about success or failure.  You can't provide a lot of
+-detail about the reasons for the failure, and most parent processes
+-would not want much detail anyway.
+-
+-   There are conventions for what sorts of status values certain
+-programs should return.  The most common convention is simply 0 for
+-success and 1 for failure.  Programs that perform comparison use a
+-different convention: they use status 1 to indicate a mismatch, and
+-status 2 to indicate an inability to compare.  Your program should
+-follow an existing convention if an existing convention makes sense for
+-it.
+-
+-   A general convention reserves status values 128 and up for special
+-purposes.  In particular, the value 128 is used to indicate failure to
+-execute another program in a subprocess.  This convention is not
+-universally obeyed, but it is a good idea to follow it in your programs.
+-
+-   *Warning:* Don't try to use the number of errors as the exit status.
+-This is actually not very useful; a parent process would generally not
+-care how many errors occurred.  Worse than that, it does not work,
+-because the status value is truncated to eight bits.  Thus, if the
+-program tried to report 256 errors, the parent would receive a report
+-of 0 errors--that is, success.
+-
+-   For the same reason, it does not work to use the value of `errno' as
+-the exit status--these can exceed 255.
+-
+-   *Portability note:* Some non-POSIX systems use different conventions
+-for exit status values.  For greater portability, you can use the
+-macros `EXIT_SUCCESS' and `EXIT_FAILURE' for the conventional status
+-value for success and failure, respectively.  They are declared in the
+-file `stdlib.h'.
+-
+- - Macro: int EXIT_SUCCESS
+-     This macro can be used with the `exit' function to indicate
+-     successful program completion.
+-
+-     On POSIX systems, the value of this macro is `0'.  On other
+-     systems, the value might be some other (possibly non-constant)
+-     integer expression.
+-
+- - Macro: int EXIT_FAILURE
+-     This macro can be used with the `exit' function to indicate
+-     unsuccessful program completion in a general sense.
+-
+-     On POSIX systems, the value of this macro is `1'.  On other
+-     systems, the value might be some other (possibly non-constant)
+-     integer expression.  Other nonzero status values also indicate
+-     future.  Certain programs use different nonzero status values to
+-     indicate particular kinds of "non-success".  For example, `diff'
+-     uses status value `1' to mean that the files are different, and
+-     `2' or more to mean that there was difficulty in opening the files.
+-
+-
+-File: libc.info,  Node: Cleanups on Exit,  Next: Aborting a Program,  Prev: 
Exit Status,  Up: Program Termination
+-
+-Cleanups on Exit
+-----------------
+-
+-   Your program can arrange to run its own cleanup functions if normal
+-termination happens.  If you are writing a library for use in various
+-application programs, then it is unreliable to insist that all
+-applications call the library's cleanup functions explicitly before
+-exiting.  It is much more robust to make the cleanup invisible to the
+-application, by setting up a cleanup function in the library itself
+-using `atexit' or `on_exit'.
+-
+- - Function: int atexit (void (*FUNCTION) (void))
+-     The `atexit' function registers the function FUNCTION to be called
+-     at normal program termination.  The FUNCTION is called with no
+-     arguments.
+-
+-     The return value from `atexit' is zero on success and nonzero if
+-     the function cannot be registered.
+-
+- - Function: int on_exit (void (*FUNCTION)(int STATUS, void *ARG), void
+-          *ARG)
+-     This function is a somewhat more powerful variant of `atexit'.  It
+-     accepts two arguments, a function FUNCTION and an arbitrary
+-     pointer ARG.  At normal program termination, the FUNCTION is
+-     called with two arguments:  the STATUS value passed to `exit', and
+-     the ARG.
+-
+-     This function is included in the GNU C library only for
+-     compatibility for SunOS, and may not be supported by other
+-     implementations.
+-
+-   Here's a trivial program that illustrates the use of `exit' and
+-`atexit':
+-
+-     #include <stdio.h>
+-     #include <stdlib.h>
+-     
+-     void
+-     bye (void)
+-     {
+-       puts ("Goodbye, cruel world....");
+-     }
+-     
+-     int
+-     main (void)
+-     {
+-       atexit (bye);
+-       exit (EXIT_SUCCESS);
+-     }
+-
+-When this program is executed, it just prints the message and exits.
+-
+-
+-File: libc.info,  Node: Aborting a Program,  Next: Termination Internals,  
Prev: Cleanups on Exit,  Up: Program Termination
+-
+-Aborting a Program
+-------------------
+-
+-   You can abort your program using the `abort' function.  The prototype
+-for this function is in `stdlib.h'.
+-
+- - Function: void abort (void)
+-     The `abort' function causes abnormal program termination.  This
+-     does not execute cleanup functions registered with `atexit' or
+-     `on_exit'.
+-
+-     This function actually terminates the process by raising a
+-     `SIGABRT' signal, and your program can include a handler to
+-     intercept this signal; see *Note Signal Handling::.
+-
+-   *Future Change Warning:* Proposed Federal censorship regulations may
+-prohibit us from giving you information about the possibility of
+-calling this function.  We would be required to say that this is not an
+-acceptable way of terminating a program.
+-
+-
+-File: libc.info,  Node: Termination Internals,  Prev: Aborting a Program,  
Up: Program Termination
+-
+-Termination Internals
+----------------------
+-
+-   The `_exit' function is the primitive used for process termination
+-by `exit'.  It is declared in the header file `unistd.h'.
+-
+- - Function: void _exit (int STATUS)
+-     The `_exit' function is the primitive for causing a process to
+-     terminate with status STATUS.  Calling this function does not
+-     execute cleanup functions registered with `atexit' or `on_exit'.
+-
+-   When a process terminates for any reason--either by an explicit
+-termination call, or termination as a result of a signal--the following
+-things happen:
+-
+-   * All open file descriptors in the process are closed.  *Note
+-     Low-Level I/O::.  Note that streams are not flushed automatically
+-     when the process terminates; *Note I/O on Streams::.
+-
+-   * The low-order 8 bits of the return status code are saved to be
+-     reported back to the parent process via `wait' or `waitpid'; see
+-     *Note Process Completion::.
+-
+-   * Any child processes of the process being terminated are assigned a
+-     new parent process.  (On most systems, including GNU, this is the
+-     `init' process, with process ID 1.)
+-
+-   * A `SIGCHLD' signal is sent to the parent process.
+-
+-   * If the process is a session leader that has a controlling
+-     terminal, then a `SIGHUP' signal is sent to each process in the
+-     foreground job, and the controlling terminal is disassociated from
+-     that session.  *Note Job Control::.
+-
+-   * If termination of a process causes a process group to become
+-     orphaned, and any member of that process group is stopped, then a
+-     `SIGHUP' signal and a `SIGCONT' signal are sent to each process in
+-     the group.  *Note Job Control::.
+-
+-
+-File: libc.info,  Node: Processes,  Next: Job Control,  Prev: Process 
Startup,  Up: Top
+-
+-Processes
+-*********
+-
+-   "Processes" are the primitive units for allocation of system
+-resources.  Each process has its own address space and (usually) one
+-thread of control.  A process executes a program; you can have multiple
+-processes executing the same program, but each process has its own copy
+-of the program within its own address space and executes it
+-independently of the other copies.
+-
+-   Processes are organized hierarchically.  Each process has a "parent
+-process" which explicitly arranged to create it.  The processes created
+-by a given parent are called its "child processes".  A child inherits
+-many of its attributes from the parent process.
+-
+-   This chapter describes how a program can create, terminate, and
+-control child processes.  Actually, there are three distinct operations
+-involved: creating a new child process, causing the new process to
+-execute a program, and coordinating the completion of the child process
+-with the original program.
+-
+-   The `system' function provides a simple, portable mechanism for
+-running another program; it does all three steps automatically.  If you
+-need more control over the details of how this is done, you can use the
+-primitive functions to do each step individually instead.
+-
+-* Menu:
+-
+-* Running a Command::           The easy way to run another program.
+-* Process Creation Concepts::   An overview of the hard way to do it.
+-* Process Identification::      How to get the process ID of a process.
+-* Creating a Process::          How to fork a child process.
+-* Executing a File::            How to make a process execute another program.
+-* Process Completion::          How to tell when a child process has 
completed.
+-* Process Completion Status::   How to interpret the status value
+-                                 returned from a child process.
+-* BSD Wait Functions::        More functions, for backward compatibility.
+-* Process Creation Example::    A complete example program.
+-
+-
+-File: libc.info,  Node: Running a Command,  Next: Process Creation Concepts,  
Up: Processes
+-
+-Running a Command
+-=================
+-
+-   The easy way to run another program is to use the `system' function.
+-This function does all the work of running a subprogram, but it
+-doesn't give you much control over the details: you have to wait until
+-the subprogram terminates before you can do anything else.
+-
+- - Function: int system (const char *COMMAND)
+-     This function executes COMMAND as a shell command.  In the GNU C
+-     library, it always uses the default shell `sh' to run the command.
+-     In particular, it searches the directories in `PATH' to find
+-     programs to execute.  The return value is `-1' if it wasn't
+-     possible to create the shell process, and otherwise is the status
+-     of the shell process.  *Note Process Completion::, for details on
+-     how this status code can be interpreted.
+-
+-     The `system' function is declared in the header file `stdlib.h'.
+-
+-   *Portability Note:* Some C implementations may not have any notion
+-of a command processor that can execute other programs.  You can
+-determine whether a command processor exists by executing
+-`system (NULL)'; if the return value is nonzero, a command processor is
+-available.
+-
+-   The `popen' and `pclose' functions (*note Pipe to a Subprocess::.)
+-are closely related to the `system' function.  They allow the parent
+-process to communicate with the standard input and output channels of
+-the command being executed.
+-
+-
+-File: libc.info,  Node: Process Creation Concepts,  Next: Process 
Identification,  Prev: Running a Command,  Up: Processes
+-
+-Process Creation Concepts
+-=========================
+-
+-   This section gives an overview of processes and of the steps
+-involved in creating a process and making it run another program.
+-
+-   Each process is named by a "process ID" number.  A unique process ID
+-is allocated to each process when it is created.  The "lifetime" of a
+-process ends when its termination is reported to its parent process; at
+-that time, all of the process resources, including its process ID, are
+-freed.
+-
+-   Processes are created with the `fork' system call (so the operation
+-of creating a new process is sometimes called "forking" a process).
+-The "child process" created by `fork' is a copy of the original "parent
+-process", except that it has its own process ID.
+-
+-   After forking a child process, both the parent and child processes
+-continue to execute normally.  If you want your program to wait for a
+-child process to finish executing before continuing, you must do this
+-explicitly after the fork operation, by calling `wait' or `waitpid'
+-(*note Process Completion::.).  These functions give you limited
+-information about why the child terminated--for example, its exit
+-status code.
+-
+-   A newly forked child process continues to execute the same program as
+-its parent process, at the point where the `fork' call returns.  You
+-can use the return value from `fork' to tell whether the program is
+-running in the parent process or the child.
+-
+-   Having several processes run the same program is only occasionally
+-useful.  But the child can execute another program using one of the
+-`exec' functions; see *Note Executing a File::.  The program that the
+-process is executing is called its "process image".  Starting execution
+-of a new program causes the process to forget all about its previous
+-process image; when the new program exits, the process exits too,
+-instead of returning to the previous process image.
+-
+-
+-File: libc.info,  Node: Process Identification,  Next: Creating a Process,  
Prev: Process Creation Concepts,  Up: Processes
+-
+-Process Identification
+-======================
+-
+-   The `pid_t' data type represents process IDs.  You can get the
+-process ID of a process by calling `getpid'.  The function `getppid'
+-returns the process ID of the parent of the current process (this is
+-also known as the "parent process ID").  Your program should include
+-the header files `unistd.h' and `sys/types.h' to use these functions.
+-
+- - Data Type: pid_t
+-     The `pid_t' data type is a signed integer type which is capable of
+-     representing a process ID.  In the GNU library, this is an `int'.
+-
+- - Function: pid_t getpid (void)
+-     The `getpid' function returns the process ID of the current
+-     process.
+-
+- - Function: pid_t getppid (void)
+-     The `getppid' function returns the process ID of the parent of the
+-     current process.
+-
+-
+-File: libc.info,  Node: Creating a Process,  Next: Executing a File,  Prev: 
Process Identification,  Up: Processes
+-
+-Creating a Process
+-==================
+-
+-   The `fork' function is the primitive for creating a process.  It is
+-declared in the header file `unistd.h'.
+-
+- - Function: pid_t fork (void)
+-     The `fork' function creates a new process.
+-
+-     If the operation is successful, there are then both parent and
+-     child processes and both see `fork' return, but with different
+-     values: it returns a value of `0' in the child process and returns
+-     the child's process ID in the parent process.
+-
+-     If process creation failed, `fork' returns a value of `-1' in the
+-     parent process.  The following `errno' error conditions are
+-     defined for `fork':
+-
+-    `EAGAIN'
+-          There aren't enough system resources to create another
+-          process, or the user already has too many processes running.
+-          This means exceeding the `RLIMIT_NPROC' resource limit, which
+-          can usually be increased; *note Limits on Resources::..
+-
+-    `ENOMEM'
+-          The process requires more space than the system can supply.
+-
+-   The specific attributes of the child process that differ from the
+-parent process are:
+-
+-   * The child process has its own unique process ID.
+-
+-   * The parent process ID of the child process is the process ID of its
+-     parent process.
+-
+-   * The child process gets its own copies of the parent process's open
+-     file descriptors.  Subsequently changing attributes of the file
+-     descriptors in the parent process won't affect the file
+-     descriptors in the child, and vice versa.  *Note Control
+-     Operations::.  However, the file position associated with each
+-     descriptor is shared by both processes; *note File Position::..
+-
+-   * The elapsed processor times for the child process are set to zero;
+-     see *Note Processor Time::.
+-
+-   * The child doesn't inherit file locks set by the parent process.
+-     *Note Control Operations::.
+-
+-   * The child doesn't inherit alarms set by the parent process.  *Note
+-     Setting an Alarm::.
+-
+-   * The set of pending signals (*note Delivery of Signal::.) for the
+-     child process is cleared.  (The child process inherits its mask of
+-     blocked signals and signal actions from the parent process.)
+-
+- - Function: pid_t vfork (void)
+-     The `vfork' function is similar to `fork' but on systems it is
+-     more efficient; however, there are restrictions you must follow to
+-     use it safely.
+-
+-     While `fork' makes a complete copy of the calling process's
+-     address space and allows both the parent and child to execute
+-     independently, `vfork' does not make this copy.  Instead, the
+-     child process created with `vfork' shares its parent's address
+-     space until it calls exits or one of the `exec' functions.  In the
+-     meantime, the parent process suspends execution.
+-
+-     You must be very careful not to allow the child process created
+-     with `vfork' to modify any global data or even local variables
+-     shared with the parent.  Furthermore, the child process cannot
+-     return from (or do a long jump out of) the function that called
+-     `vfork'!  This would leave the parent process's control
+-     information very confused.  If in doubt, use `fork' instead.
+-
+-     Some operating systems don't really implement `vfork'.  The GNU C
+-     library permits you to use `vfork' on all systems, but actually
+-     executes `fork' if `vfork' isn't available.  If you follow the
+-     proper precautions for using `vfork', your program will still work
+-     even if the system uses `fork' instead.
+-
+-
+-File: libc.info,  Node: Executing a File,  Next: Process Completion,  Prev: 
Creating a Process,  Up: Processes
+-
+-Executing a File
+-================
+-
+-   This section describes the `exec' family of functions, for executing
+-a file as a process image.  You can use these functions to make a child
+-process execute a new program after it has been forked.
+-
+-   The functions in this family differ in how you specify the arguments,
+-but otherwise they all do the same thing.  They are declared in the
+-header file `unistd.h'.
+-
+- - Function: int execv (const char *FILENAME, char *const ARGV[])
+-     The `execv' function executes the file named by FILENAME as a new
+-     process image.
+-
+-     The ARGV argument is an array of null-terminated strings that is
+-     used to provide a value for the `argv' argument to the `main'
+-     function of the program to be executed.  The last element of this
+-     array must be a null pointer.  By convention, the first element of
+-     this array is the file name of the program sans directory names.
+-     *Note Program Arguments::, for full details on how programs can
+-     access these arguments.
+-
+-     The environment for the new process image is taken from the
+-     `environ' variable of the current process image; see *Note
+-     Environment Variables::, for information about environments.
+-
+- - Function: int execl (const char *FILENAME, const char *ARG0, ...)
+-     This is similar to `execv', but the ARGV strings are specified
+-     individually instead of as an array.  A null pointer must be
+-     passed as the last such argument.
+-
+- - Function: int execve (const char *FILENAME, char *const ARGV[], char
+-          *const ENV[])
+-     This is similar to `execv', but permits you to specify the
+-     environment for the new program explicitly as the ENV argument.
+-     This should be an array of strings in the same format as for the
+-     `environ' variable; see *Note Environment Access::.
+-
+- - Function: int execle (const char *FILENAME, const char *ARG0, char
+-          *const ENV[], ...)
+-     This is similar to `execl', but permits you to specify the
+-     environment for the new program explicitly.  The environment
+-     argument is passed following the null pointer that marks the last
+-     ARGV argument, and should be an array of strings in the same
+-     format as for the `environ' variable.
+-
+- - Function: int execvp (const char *FILENAME, char *const ARGV[])
+-     The `execvp' function is similar to `execv', except that it
+-     searches the directories listed in the `PATH' environment variable
+-     (*note Standard Environment::.) to find the full file name of a
+-     file from FILENAME if FILENAME does not contain a slash.
+-
+-     This function is useful for executing system utility programs,
+-     because it looks for them in the places that the user has chosen.
+-     Shells use it to run the commands that users type.
+-
+- - Function: int execlp (const char *FILENAME, const char *ARG0, ...)
+-     This function is like `execl', except that it performs the same
+-     file name searching as the `execvp' function.
+-
+-   The size of the argument list and environment list taken together
+-must not be greater than `ARG_MAX' bytes.  *Note General Limits::.  In
+-the GNU system, the size (which compares against `ARG_MAX') includes,
+-for each string, the number of characters in the string, plus the size
+-of a `char *', plus one, rounded up to a multiple of the size of a
+-`char *'.  Other systems may have somewhat different rules for counting.
+-
+-   These functions normally don't return, since execution of a new
+-program causes the currently executing program to go away completely.
+-A value of `-1' is returned in the event of a failure.  In addition to
+-the usual file name errors (*note File Name Errors::.), the following
+-`errno' error conditions are defined for these functions:
+-
+-`E2BIG'
+-     The combined size of the new program's argument list and
+-     environment list is larger than `ARG_MAX' bytes.  The GNU system
+-     has no specific limit on the argument list size, so this error
+-     code cannot result, but you may get `ENOMEM' instead if the
+-     arguments are too big for available memory.
+-
+-`ENOEXEC'
+-     The specified file can't be executed because it isn't in the right
+-     format.
+-
+-`ENOMEM'
+-     Executing the specified file requires more storage than is
+-     available.
+-
+-   If execution of the new file succeeds, it updates the access time
+-field of the file as if the file had been read.  *Note File Times::,
+-for more details about access times of files.
+-
+-   The point at which the file is closed again is not specified, but is
+-at some point before the process exits or before another process image
+-is executed.
+-
+-   Executing a new process image completely changes the contents of
+-memory, copying only the argument and environment strings to new
+-locations.  But many other attributes of the process are unchanged:
+-
+-   * The process ID and the parent process ID.  *Note Process Creation
+-     Concepts::.
+-
+-   * Session and process group membership.  *Note Concepts of Job
+-     Control::.
+-
+-   * Real user ID and group ID, and supplementary group IDs.  *Note
+-     Process Persona::.
+-
+-   * Pending alarms.  *Note Setting an Alarm::.
+-
+-   * Current working directory and root directory.  *Note Working
+-     Directory::.  In the GNU system, the root directory is not copied
+-     when executing a setuid program; instead the system default root
+-     directory is used for the new program.
+-
+-   * File mode creation mask.  *Note Setting Permissions::.
+-
+-   * Process signal mask; see *Note Process Signal Mask::.
+-
+-   * Pending signals; see *Note Blocking Signals::.
+-
+-   * Elapsed processor time associated with the process; see *Note
+-     Processor Time::.
+-
+-   If the set-user-ID and set-group-ID mode bits of the process image
+-file are set, this affects the effective user ID and effective group ID
+-(respectively) of the process.  These concepts are discussed in detail
+-in *Note Process Persona::.
+-
+-   Signals that are set to be ignored in the existing process image are
+-also set to be ignored in the new process image.  All other signals are
+-set to the default action in the new process image.  For more
+-information about signals, see *Note Signal Handling::.
+-
+-   File descriptors open in the existing process image remain open in
+-the new process image, unless they have the `FD_CLOEXEC'
+-(close-on-exec) flag set.  The files that remain open inherit all
+-attributes of the open file description from the existing process image,
+-including file locks.  File descriptors are discussed in *Note
+-Low-Level I/O::.
+-
+-   Streams, by contrast, cannot survive through `exec' functions,
+-because they are located in the memory of the process itself.  The new
+-process image has no streams except those it creates afresh.  Each of
+-the streams in the pre-`exec' process image has a descriptor inside it,
+-and these descriptors do survive through `exec' (provided that they do
+-not have `FD_CLOEXEC' set).  The new process image can reconnect these
+-to new streams using `fdopen' (*note Descriptors and Streams::.).
+-
+-
+-File: libc.info,  Node: Process Completion,  Next: Process Completion Status, 
 Prev: Executing a File,  Up: Processes
+-
+-Process Completion
+-==================
+-
+-   The functions described in this section are used to wait for a child
+-process to terminate or stop, and determine its status.  These functions
+-are declared in the header file `sys/wait.h'.
+-
+- - Function: pid_t waitpid (pid_t PID, int *STATUS-PTR, int OPTIONS)
+-     The `waitpid' function is used to request status information from a
+-     child process whose process ID is PID.  Normally, the calling
+-     process is suspended until the child process makes status
+-     information available by terminating.
+-
+-     Other values for the PID argument have special interpretations.  A
+-     value of `-1' or `WAIT_ANY' requests status information for any
+-     child process; a value of `0' or `WAIT_MYPGRP' requests
+-     information for any child process in the same process group as the
+-     calling process; and any other negative value - PGID requests
+-     information for any child process whose process group ID is PGID.
+-
+-     If status information for a child process is available
+-     immediately, this function returns immediately without waiting.
+-     If more than one eligible child process has status information
+-     available, one of them is chosen randomly, and its status is
+-     returned immediately.  To get the status from the other eligible
+-     child processes, you need to call `waitpid' again.
+-
+-     The OPTIONS argument is a bit mask.  Its value should be the
+-     bitwise OR (that is, the `|' operator) of zero or more of the
+-     `WNOHANG' and `WUNTRACED' flags.  You can use the `WNOHANG' flag
+-     to indicate that the parent process shouldn't wait; and the
+-     `WUNTRACED' flag to request status information from stopped
+-     processes as well as processes that have terminated.
+-
+-     The status information from the child process is stored in the
+-     object that STATUS-PTR points to, unless STATUS-PTR is a null
+-     pointer.
+-
+-     The return value is normally the process ID of the child process
+-     whose status is reported.  If the `WNOHANG' option was specified
+-     and no child process is waiting to be noticed, the value is zero.
+-     A value of `-1' is returned in case of error.  The following
+-     `errno' error conditions are defined for this function:
+-
+-    `EINTR'
+-          The function was interrupted by delivery of a signal to the
+-          calling process.  *Note Interrupted Primitives::.
+-
+-    `ECHILD'
+-          There are no child processes to wait for, or the specified PID
+-          is not a child of the calling process.
+-
+-    `EINVAL'
+-          An invalid value was provided for the OPTIONS argument.
+-
+-   These symbolic constants are defined as values for the PID argument
+-to the `waitpid' function.
+-
+-`WAIT_ANY'
+-     This constant macro (whose value is `-1') specifies that `waitpid'
+-     should return status information about any child process.
+-
+-`WAIT_MYPGRP'
+-     This constant (with value `0') specifies that `waitpid' should
+-     return status information about any child process in the same
+-     process group as the calling process.
+-
+-   These symbolic constants are defined as flags for the OPTIONS
+-argument to the `waitpid' function.  You can bitwise-OR the flags
+-together to obtain a value to use as the argument.
+-
+-`WNOHANG'
+-     This flag specifies that `waitpid' should return immediately
+-     instead of waiting, if there is no child process ready to be
+-     noticed.
+-
+-`WUNTRACED'
+-     This flag specifies that `waitpid' should report the status of any
+-     child processes that have been stopped as well as those that have
+-     terminated.
+-
+- - Function: pid_t wait (int *STATUS-PTR)
+-     This is a simplified version of `waitpid', and is used to wait
+-     until any one child process terminates.  The call:
+-
+-          wait (&status)
+-
+-     is exactly equivalent to:
+-
+-          waitpid (-1, &status, 0)
+-
+- - Function: pid_t wait4 (pid_t PID, int *STATUS-PTR, int OPTIONS,
+-          struct rusage *USAGE)
+-     If USAGE is a null pointer, `wait4' is equivalent to `waitpid
+-     (PID, STATUS-PTR, OPTIONS)'.
+-
+-     If USAGE is not null, `wait4' stores usage figures for the child
+-     process in `*RUSAGE' (but only if the child has terminated, not if
+-     it has stopped).  *Note Resource Usage::.
+-
+-     This function is a BSD extension.
+-
+-   Here's an example of how to use `waitpid' to get the status from all
+-child processes that have terminated, without ever waiting.  This
+-function is designed to be a handler for `SIGCHLD', the signal that
+-indicates that at least one child process has terminated.
+-
+-     void
+-     sigchld_handler (int signum)
+-     {
+-       int pid;
+-       int status;
+-       while (1)
+-         {
+-           pid = waitpid (WAIT_ANY, &status, WNOHANG);
+-           if (pid < 0)
+-             {
+-               perror ("waitpid");
+-               break;
+-             }
+-           if (pid == 0)
+-             break;
+-           notice_termination (pid, status);
+-         }
+-     }
+-
+-
+-File: libc.info,  Node: Process Completion Status,  Next: BSD Wait Functions, 
 Prev: Process Completion,  Up: Processes
+-
+-Process Completion Status
+-=========================
+-
+-   If the exit status value (*note Program Termination::.) of the child
+-process is zero, then the status value reported by `waitpid' or `wait'
+-is also zero.  You can test for other kinds of information encoded in
+-the returned status value using the following macros.  These macros are
+-defined in the header file `sys/wait.h'.
+-
+- - Macro: int WIFEXITED (int STATUS)
+-     This macro returns a nonzero value if the child process terminated
+-     normally with `exit' or `_exit'.
+-
+- - Macro: int WEXITSTATUS (int STATUS)
+-     If `WIFEXITED' is true of STATUS, this macro returns the low-order
+-     8 bits of the exit status value from the child process.  *Note
+-     Exit Status::.
+-
+- - Macro: int WIFSIGNALED (int STATUS)
+-     This macro returns a nonzero value if the child process terminated
+-     because it received a signal that was not handled.  *Note Signal
+-     Handling::.
+-
+- - Macro: int WTERMSIG (int STATUS)
+-     If `WIFSIGNALED' is true of STATUS, this macro returns the signal
+-     number of the signal that terminated the child process.
+-
+- - Macro: int WCOREDUMP (int STATUS)
+-     This macro returns a nonzero value if the child process terminated
+-     and produced a core dump.
+-
+- - Macro: int WIFSTOPPED (int STATUS)
+-     This macro returns a nonzero value if the child process is stopped.
+-
+- - Macro: int WSTOPSIG (int STATUS)
+-     If `WIFSTOPPED' is true of STATUS, this macro returns the signal
+-     number of the signal that caused the child process to stop.
+-
+-
+-File: libc.info,  Node: BSD Wait Functions,  Next: Process Creation Example,  
Prev: Process Completion Status,  Up: Processes
+-
+-BSD Process Wait Functions
+-==========================
+-
+-   The GNU library also provides these related facilities for
+-compatibility with BSD Unix.  BSD uses the `union wait' data type to
+-represent status values rather than an `int'.  The two representations
+-are actually interchangeable; they describe the same bit patterns.  The
+-GNU C Library defines macros such as `WEXITSTATUS' so that they will
+-work on either kind of object, and the `wait' function is defined to
+-accept either type of pointer as its STATUS-PTR argument.
+-
+-   These functions are declared in `sys/wait.h'.
+-
+- - Data Type: union wait
+-     This data type represents program termination status values.  It
+-     has the following members:
+-
+-    `int w_termsig'
+-          The value of this member is the same as the result of the
+-          `WTERMSIG' macro.
+-
+-    `int w_coredump'
+-          The value of this member is the same as the result of the
+-          `WCOREDUMP' macro.
+-
+-    `int w_retcode'
+-          The value of this member is the same as the result of the
+-          `WEXITSTATUS' macro.
+-
+-    `int w_stopsig'
+-          The value of this member is the same as the result of the
+-          `WSTOPSIG' macro.
+-
+-     Instead of accessing these members directly, you should use the
+-     equivalent macros.
+-
+-   The `wait3' function is the predecessor to `wait4', which is more
+-flexible.  `wait3' is now obsolete.
+-
+- - Function: pid_t wait3 (union wait *STATUS-PTR, int OPTIONS, struct
+-          rusage *USAGE)
+-     If USAGE is a null pointer, `wait3' is equivalent to `waitpid (-1,
+-     STATUS-PTR, OPTIONS)'.
+-
+-     If USAGE is not null, `wait3' stores usage figures for the child
+-     process in `*RUSAGE' (but only if the child has terminated, not if
+-     it has stopped).  *Note Resource Usage::.
+-
+-
+-File: libc.info,  Node: Process Creation Example,  Prev: BSD Wait Functions,  
Up: Processes
+-
+-Process Creation Example
+-========================
+-
+-   Here is an example program showing how you might write a function
+-similar to the built-in `system'.  It executes its COMMAND argument
+-using the equivalent of `sh -c COMMAND'.
+-
+-     #include <stddef.h>
+-     #include <stdlib.h>
+-     #include <unistd.h>
+-     #include <sys/types.h>
+-     #include <sys/wait.h>
+-     
+-     /* Execute the command using this shell program.  */
+-     #define SHELL "/bin/sh"
+-     int
+-     my_system (const char *command)
+-     {
+-       int status;
+-       pid_t pid;
+-     
+-       pid = fork ();
+-       if (pid == 0)
+-         {
+-           /* This is the child process.  Execute the shell command. */
+-           execl (SHELL, SHELL, "-c", command, NULL);
+-           _exit (EXIT_FAILURE);
+-         }
+-       else if (pid < 0)
+-         /* The fork failed.  Report failure.  */
+-         status = -1;
+-       else
+-         /* This is the parent process.  Wait for the child to complete.  */
+-         if (waitpid (pid, &status, 0) != pid)
+-           status = -1;
+-       return status;
+-     }
+-
+-   There are a couple of things you should pay attention to in this
+-example.
+-
+-   Remember that the first `argv' argument supplied to the program
+-represents the name of the program being executed.  That is why, in the
+-call to `execl', `SHELL' is supplied once to name the program to
+-execute and a second time to supply a value for `argv[0]'.
+-
+-   The `execl' call in the child process doesn't return if it is
+-successful.  If it fails, you must do something to make the child
+-process terminate.  Just returning a bad status code with `return'
+-would leave two processes running the original program.  Instead, the
+-right behavior is for the child process to report failure to its parent
+-process.
+-
+-   Call `_exit' to accomplish this.  The reason for using `_exit'
+-instead of `exit' is to avoid flushing fully buffered streams such as
+-`stdout'.  The buffers of these streams probably contain data that was
+-copied from the parent process by the `fork', data that will be output
+-eventually by the parent process.  Calling `exit' in the child would
+-output the data twice.  *Note Termination Internals::.
+-
+-
+-File: libc.info,  Node: Job Control,  Next: Name Service Switch,  Prev: 
Processes,  Up: Top
+-
+-Job Control
+-***********
+-
+-   "Job control" refers to the protocol for allowing a user to move
+-between multiple "process groups" (or "jobs") within a single "login
+-session".  The job control facilities are set up so that appropriate
+-behavior for most programs happens automatically and they need not do
+-anything special about job control.  So you can probably ignore the
+-material in this chapter unless you are writing a shell or login
+-program.
+-
+-   You need to be familiar with concepts relating to process creation
+-(*note Process Creation Concepts::.) and signal handling (*note Signal
+-Handling::.) in order to understand this material presented in this
+-chapter.
+-
+-* Menu:
+-
+-* Concepts of Job Control::     Jobs can be controlled by a shell.
+-* Job Control is Optional::     Not all POSIX systems support job control.
+-* Controlling Terminal::        How a process gets its controlling terminal.
+-* Access to the Terminal::      How processes share the controlling terminal.
+-* Orphaned Process Groups::     Jobs left after the user logs out.
+-* Implementing a Shell::        What a shell must do to implement job control.
+-* Functions for Job Control::   Functions to control process groups.
+-
+-
+-File: libc.info,  Node: Concepts of Job Control,  Next: Job Control is 
Optional,  Up: Job Control
+-
+-Concepts of Job Control
+-=======================
+-
+-   The fundamental purpose of an interactive shell is to read commands
+-from the user's terminal and create processes to execute the programs
+-specified by those commands.  It can do this using the `fork' (*note
+-Creating a Process::.) and `exec' (*note Executing a File::.) functions.
+-
+-   A single command may run just one process--but often one command uses
+-several processes.  If you use the `|' operator in a shell command, you
+-explicitly request several programs in their own processes.  But even
+-if you run just one program, it can use multiple processes internally.
+-For example, a single compilation command such as `cc -c foo.c'
+-typically uses four processes (though normally only two at any given
+-time).  If you run `make', its job is to run other programs in separate
+-processes.
+-
+-   The processes belonging to a single command are called a "process
+-group" or "job".  This is so that you can operate on all of them at
+-once.  For example, typing `C-c' sends the signal `SIGINT' to terminate
+-all the processes in the foreground process group.
+-
+-   A "session" is a larger group of processes.  Normally all the
+-processes that stem from a single login belong to the same session.
+-
+-   Every process belongs to a process group.  When a process is
+-created, it becomes a member of the same process group and session as
+-its parent process.  You can put it in another process group using the
+-`setpgid' function, provided the process group belongs to the same
+-session.
+-
+-   The only way to put a process in a different session is to make it
+-the initial process of a new session, or a "session leader", using the
+-`setsid' function.  This also puts the session leader into a new
+-process group, and you can't move it out of that process group again.
+-
+-   Usually, new sessions are created by the system login program, and
+-the session leader is the process running the user's login shell.
+-
+-   A shell that supports job control must arrange to control which job
+-can use the terminal at any time.  Otherwise there might be multiple
+-jobs trying to read from the terminal at once, and confusion about which
+-process should receive the input typed by the user.  To prevent this,
+-the shell must cooperate with the terminal driver using the protocol
+-described in this chapter.
+-
+-   The shell can give unlimited access to the controlling terminal to
+-only one process group at a time.  This is called the "foreground job"
+-on that controlling terminal.  Other process groups managed by the shell
+-that are executing without such access to the terminal are called
+-"background jobs".
+-
+-   If a background job needs to read from its controlling terminal, it
+-is "stopped" by the terminal driver; if the `TOSTOP' mode is set,
+-likewise for writing.  The user can stop a foreground job by typing the
+-SUSP character (*note Special Characters::.) and a program can stop any
+-job by sending it a `SIGSTOP' signal.  It's the responsibility of the
+-shell to notice when jobs stop, to notify the user about them, and to
+-provide mechanisms for allowing the user to interactively continue
+-stopped jobs and switch jobs between foreground and background.
+-
+-   *Note Access to the Terminal::, for more information about I/O to the
+-controlling terminal,
+-
+-
+-File: libc.info,  Node: Job Control is Optional,  Next: Controlling Terminal, 
 Prev: Concepts of Job Control,  Up: Job Control
+-
+-Job Control is Optional
+-=======================
+-
+-   Not all operating systems support job control.  The GNU system does
+-support job control, but if you are using the GNU library on some other
+-system, that system may not support job control itself.
+-
+-   You can use the `_POSIX_JOB_CONTROL' macro to test at compile-time
+-whether the system supports job control.  *Note System Options::.
+-
+-   If job control is not supported, then there can be only one process
+-group per session, which behaves as if it were always in the foreground.
+-The functions for creating additional process groups simply fail with
+-the error code `ENOSYS'.
+-
+-   The macros naming the various job control signals (*note Job Control
+-Signals::.) are defined even if job control is not supported.  However,
+-the system never generates these signals, and attempts to send a job
+-control signal or examine or specify their actions report errors or do
+-nothing.
+-
+-
+-File: libc.info,  Node: Controlling Terminal,  Next: Access to the Terminal,  
Prev: Job Control is Optional,  Up: Job Control
+-
+-Controlling Terminal of a Process
+-=================================
+-
+-   One of the attributes of a process is its controlling terminal.
+-Child processes created with `fork' inherit the controlling terminal
+-from their parent process.  In this way, all the processes in a session
+-inherit the controlling terminal from the session leader.  A session
+-leader that has control of a terminal is called the "controlling
+-process" of that terminal.
+-
+-   You generally do not need to worry about the exact mechanism used to
+-allocate a controlling terminal to a session, since it is done for you
+-by the system when you log in.
+-
+-   An individual process disconnects from its controlling terminal when
+-it calls `setsid' to become the leader of a new session.  *Note Process
+-Group Functions::.
+-
+-
+-File: libc.info,  Node: Access to the Terminal,  Next: Orphaned Process 
Groups,  Prev: Controlling Terminal,  Up: Job Control
+-
+-Access to the Controlling Terminal
+-==================================
+-
+-   Processes in the foreground job of a controlling terminal have
+-unrestricted access to that terminal; background processes do not.  This
+-section describes in more detail what happens when a process in a
+-background job tries to access its controlling terminal.
+-
+-   When a process in a background job tries to read from its controlling
+-terminal, the process group is usually sent a `SIGTTIN' signal.  This
+-normally causes all of the processes in that group to stop (unless they
+-handle the signal and don't stop themselves).  However, if the reading
+-process is ignoring or blocking this signal, then `read' fails with an
+-`EIO' error instead.
+-
+-   Similarly, when a process in a background job tries to write to its
+-controlling terminal, the default behavior is to send a `SIGTTOU'
+-signal to the process group.  However, the behavior is modified by the
+-`TOSTOP' bit of the local modes flags (*note Local Modes::.).  If this
+-bit is not set (which is the default), then writing to the controlling
+-terminal is always permitted without sending a signal.  Writing is also
+-permitted if the `SIGTTOU' signal is being ignored or blocked by the
+-writing process.
+-
+-   Most other terminal operations that a program can do are treated as
+-reading or as writing.  (The description of each operation should say
+-which.)
+-
+-   For more information about the primitive `read' and `write'
+-functions, see *Note I/O Primitives::.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-24 
glibc-2.0.1/manual/libc.info-24
+--- ../glibc-2.0.1/manual/libc.info-24 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-24    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1332 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Orphaned Process Groups,  Next: Implementing a Shell, 
 Prev: Access to the Terminal,  Up: Job Control
+-
+-Orphaned Process Groups
+-=======================
+-
+-   When a controlling process terminates, its terminal becomes free and
+-a new session can be established on it.  (In fact, another user could
+-log in on the terminal.)  This could cause a problem if any processes
+-from the old session are still trying to use that terminal.
+-
+-   To prevent problems, process groups that continue running even after
+-the session leader has terminated are marked as "orphaned process
+-groups".
+-
+-   When a process group becomes an orphan, its processes are sent a
+-`SIGHUP' signal.  Ordinarily, this causes the processes to terminate.
+-However, if a program ignores this signal or establishes a handler for
+-it (*note Signal Handling::.), it can continue running as in the orphan
+-process group even after its controlling process terminates; but it
+-still cannot access the terminal any more.
+-
+-
+-File: libc.info,  Node: Implementing a Shell,  Next: Functions for Job 
Control,  Prev: Orphaned Process Groups,  Up: Job Control
+-
+-Implementing a Job Control Shell
+-================================
+-
+-   This section describes what a shell must do to implement job
+-control, by presenting an extensive sample program to illustrate the
+-concepts involved.
+-
+-* Menu:
+-
+-* Data Structures::             Introduction to the sample shell.
+-* Initializing the Shell::      What the shell must do to take
+-                               responsibility for job control.
+-* Launching Jobs::              Creating jobs to execute commands.
+-* Foreground and Background::   Putting a job in foreground of background.
+-* Stopped and Terminated Jobs::  Reporting job status.
+-* Continuing Stopped Jobs::     How to continue a stopped job in
+-                               the foreground or background.
+-* Missing Pieces::              Other parts of the shell.
+-
+-
+-File: libc.info,  Node: Data Structures,  Next: Initializing the Shell,  Up: 
Implementing a Shell
+-
+-Data Structures for the Shell
+------------------------------
+-
+-   All of the program examples included in this chapter are part of a
+-simple shell program.  This section presents data structures and
+-utility functions which are used throughout the example.
+-
+-   The sample shell deals mainly with two data structures.  The `job'
+-type contains information about a job, which is a set of subprocesses
+-linked together with pipes.  The `process' type holds information about
+-a single subprocess.  Here are the relevant data structure declarations:
+-
+-     /* A process is a single process.  */
+-     typedef struct process
+-     {
+-       struct process *next;       /* next process in pipeline */
+-       char **argv;                /* for exec */
+-       pid_t pid;                  /* process ID */
+-       char completed;             /* true if process has completed */
+-       char stopped;               /* true if process has stopped */
+-       int status;                 /* reported status value */
+-     } process;
+-
+-     /* A job is a pipeline of processes.  */
+-     typedef struct job
+-     {
+-       struct job *next;           /* next active job */
+-       char *command;              /* command line, used for messages */
+-       process *first_process;     /* list of processes in this job */
+-       pid_t pgid;                 /* process group ID */
+-       char notified;              /* true if user told about stopped job */
+-       struct termios tmodes;      /* saved terminal modes */
+-       int stdin, stdout, stderr;  /* standard i/o channels */
+-     } job;
+-     
+-     /* The active jobs are linked into a list.  This is its head.   */
+-     job *first_job = NULL;
+-
+-   Here are some utility functions that are used for operating on `job'
+-objects.
+-
+-     /* Find the active job with the indicated PGID.  */
+-     job *
+-     find_job (pid_t pgid)
+-     {
+-       job *j;
+-     
+-       for (j = first_job; j; j = j->next)
+-         if (j->pgid == pgid)
+-           return j;
+-       return NULL;
+-     }
+-
+-     /* Return true if all processes in the job have stopped or completed.  */
+-     int
+-     job_is_stopped (job *j)
+-     {
+-       process *p;
+-     
+-       for (p = j->first_process; p; p = p->next)
+-         if (!p->completed && !p->stopped)
+-           return 0;
+-       return 1;
+-     }
+-
+-     /* Return true if all processes in the job have completed.  */
+-     int
+-     job_is_completed (job *j)
+-     {
+-       process *p;
+-     
+-       for (p = j->first_process; p; p = p->next)
+-         if (!p->completed)
+-           return 0;
+-       return 1;
+-     }
+-
+-
+-File: libc.info,  Node: Initializing the Shell,  Next: Launching Jobs,  Prev: 
Data Structures,  Up: Implementing a Shell
+-
+-Initializing the Shell
+-----------------------
+-
+-   When a shell program that normally performs job control is started,
+-it has to be careful in case it has been invoked from another shell
+-that is already doing its own job control.
+-
+-   A subshell that runs interactively has to ensure that it has been
+-placed in the foreground by its parent shell before it can enable job
+-control itself.  It does this by getting its initial process group ID
+-with the `getpgrp' function, and comparing it to the process group ID
+-of the current foreground job associated with its controlling terminal
+-(which can be retrieved using the `tcgetpgrp' function).
+-
+-   If the subshell is not running as a foreground job, it must stop
+-itself by sending a `SIGTTIN' signal to its own process group.  It may
+-not arbitrarily put itself into the foreground; it must wait for the
+-user to tell the parent shell to do this.  If the subshell is continued
+-again, it should repeat the check and stop itself again if it is still
+-not in the foreground.
+-
+-   Once the subshell has been placed into the foreground by its parent
+-shell, it can enable its own job control.  It does this by calling
+-`setpgid' to put itself into its own process group, and then calling
+-`tcsetpgrp' to place this process group into the foreground.
+-
+-   When a shell enables job control, it should set itself to ignore all
+-the job control stop signals so that it doesn't accidentally stop
+-itself.  You can do this by setting the action for all the stop signals
+-to `SIG_IGN'.
+-
+-   A subshell that runs non-interactively cannot and should not support
+-job control.  It must leave all processes it creates in the same process
+-group as the shell itself; this allows the non-interactive shell and its
+-child processes to be treated as a single job by the parent shell.  This
+-is easy to do--just don't use any of the job control primitives--but
+-you must remember to make the shell do it.
+-
+-   Here is the initialization code for the sample shell that shows how
+-to do all of this.
+-
+-     /* Keep track of attributes of the shell.  */
+-     
+-     #include <sys/types.h>
+-     #include <termios.h>
+-     #include <unistd.h>
+-     
+-     pid_t shell_pgid;
+-     struct termios shell_tmodes;
+-     int shell_terminal;
+-     int shell_is_interactive;
+-     
+-     
+-     /* Make sure the shell is running interactively as the foreground job
+-        before proceeding. */
+-     
+-     void
+-     init_shell ()
+-     {
+-     
+-       /* See if we are running interactively.  */
+-       shell_terminal = STDIN_FILENO;
+-       shell_is_interactive = isatty (shell_terminal);
+-     
+-       if (shell_is_interactive)
+-         {
+-           /* Loop until we are in the foreground.  */
+-           while (tcgetpgrp (shell_terminal) != (shell_pgid = getpgrp ()))
+-             kill (- shell_pgid, SIGTTIN);
+-     
+-           /* Ignore interactive and job-control signals.  */
+-           signal (SIGINT, SIG_IGN);
+-           signal (SIGQUIT, SIG_IGN);
+-           signal (SIGTSTP, SIG_IGN);
+-           signal (SIGTTIN, SIG_IGN);
+-           signal (SIGTTOU, SIG_IGN);
+-           signal (SIGCHLD, SIG_IGN);
+-     
+-           /* Put ourselves in our own process group.  */
+-           shell_pgid = getpid ();
+-           if (setpgid (shell_pgid, shell_pgid) < 0)
+-             {
+-               perror ("Couldn't put the shell in its own process group");
+-               exit (1);
+-             }
+-     
+-           /* Grab control of the terminal.  */
+-           tcsetpgrp (shell_terminal, shell_pgid);
+-     
+-           /* Save default terminal attributes for shell.  */
+-           tcgetattr (shell_terminal, &shell_tmodes);
+-         }
+-     }
+-
+-
+-File: libc.info,  Node: Launching Jobs,  Next: Foreground and Background,  
Prev: Initializing the Shell,  Up: Implementing a Shell
+-
+-Launching Jobs
+---------------
+-
+-   Once the shell has taken responsibility for performing job control on
+-its controlling terminal, it can launch jobs in response to commands
+-typed by the user.
+-
+-   To create the processes in a process group, you use the same `fork'
+-and `exec' functions described in *Note Process Creation Concepts::.
+-Since there are multiple child processes involved, though, things are a
+-little more complicated and you must be careful to do things in the
+-right order.  Otherwise, nasty race conditions can result.
+-
+-   You have two choices for how to structure the tree of parent-child
+-relationships among the processes.  You can either make all the
+-processes in the process group be children of the shell process, or you
+-can make one process in group be the ancestor of all the other processes
+-in that group.  The sample shell program presented in this chapter uses
+-the first approach because it makes bookkeeping somewhat simpler.
+-
+-   As each process is forked, it should put itself in the new process
+-group by calling `setpgid'; see *Note Process Group Functions::.  The
+-first process in the new group becomes its "process group leader", and
+-its process ID becomes the "process group ID" for the group.
+-
+-   The shell should also call `setpgid' to put each of its child
+-processes into the new process group.  This is because there is a
+-potential timing problem: each child process must be put in the process
+-group before it begins executing a new program, and the shell depends on
+-having all the child processes in the group before it continues
+-executing.  If both the child processes and the shell call `setpgid',
+-this ensures that the right things happen no matter which process gets
+-to it first.
+-
+-   If the job is being launched as a foreground job, the new process
+-group also needs to be put into the foreground on the controlling
+-terminal using `tcsetpgrp'.  Again, this should be done by the shell as
+-well as by each of its child processes, to avoid race conditions.
+-
+-   The next thing each child process should do is to reset its signal
+-actions.
+-
+-   During initialization, the shell process set itself to ignore job
+-control signals; see *Note Initializing the Shell::.  As a result, any
+-child processes it creates also ignore these signals by inheritance.
+-This is definitely undesirable, so each child process should explicitly
+-set the actions for these signals back to `SIG_DFL' just after it is
+-forked.
+-
+-   Since shells follow this convention, applications can assume that
+-they inherit the correct handling of these signals from the parent
+-process.  But every application has a responsibility not to mess up the
+-handling of stop signals.  Applications that disable the normal
+-interpretation of the SUSP character should provide some other
+-mechanism for the user to stop the job.  When the user invokes this
+-mechanism, the program should send a `SIGTSTP' signal to the process
+-group of the process, not just to the process itself.  *Note Signaling
+-Another Process::.
+-
+-   Finally, each child process should call `exec' in the normal way.
+-This is also the point at which redirection of the standard input and
+-output channels should be handled.  *Note Duplicating Descriptors::,
+-for an explanation of how to do this.
+-
+-   Here is the function from the sample shell program that is
+-responsible for launching a program.  The function is executed by each
+-child process immediately after it has been forked by the shell, and
+-never returns.
+-
+-     void
+-     launch_process (process *p, pid_t pgid,
+-                     int infile, int outfile, int errfile,
+-                     int foreground)
+-     {
+-       pid_t pid;
+-     
+-       if (shell_is_interactive)
+-         {
+-           /* Put the process into the process group and give the process 
group
+-              the terminal, if appropriate.
+-              This has to be done both by the shell and in the individual
+-              child processes because of potential race conditions.  */
+-           pid = getpid ();
+-           if (pgid == 0) pgid = pid;
+-           setpgid (pid, pgid);
+-           if (foreground)
+-             tcsetpgrp (shell_terminal, pgid);
+-     
+-           /* Set the handling for job control signals back to the default.  
*/
+-           signal (SIGINT, SIG_DFL);
+-           signal (SIGQUIT, SIG_DFL);
+-           signal (SIGTSTP, SIG_DFL);
+-           signal (SIGTTIN, SIG_DFL);
+-           signal (SIGTTOU, SIG_DFL);
+-           signal (SIGCHLD, SIG_DFL);
+-         }
+-     
+-       /* Set the standard input/output channels of the new process.  */
+-       if (infile != STDIN_FILENO)
+-         {
+-           dup2 (infile, STDIN_FILENO);
+-           close (infile);
+-         }
+-       if (outfile != STDOUT_FILENO)
+-         {
+-           dup2 (outfile, STDOUT_FILENO);
+-           close (outfile);
+-         }
+-       if (errfile != STDERR_FILENO)
+-         {
+-           dup2 (errfile, STDERR_FILENO);
+-           close (errfile);
+-         }
+-     
+-       /* Exec the new process.  Make sure we exit.  */
+-       execvp (p->argv[0], p->argv);
+-       perror ("execvp");
+-       exit (1);
+-     }
+-
+-   If the shell is not running interactively, this function does not do
+-anything with process groups or signals.  Remember that a shell not
+-performing job control must keep all of its subprocesses in the same
+-process group as the shell itself.
+-
+-   Next, here is the function that actually launches a complete job.
+-After creating the child processes, this function calls some other
+-functions to put the newly created job into the foreground or
+-background; these are discussed in *Note Foreground and Background::.
+-
+-     void
+-     launch_job (job *j, int foreground)
+-     {
+-       process *p;
+-       pid_t pid;
+-       int mypipe[2], infile, outfile;
+-     
+-       infile = j->stdin;
+-       for (p = j->first_process; p; p = p->next)
+-         {
+-           /* Set up pipes, if necessary.  */
+-           if (p->next)
+-             {
+-               if (pipe (mypipe) < 0)
+-                 {
+-                   perror ("pipe");
+-                   exit (1);
+-                 }
+-               outfile = mypipe[1];
+-             }
+-           else
+-             outfile = j->stdout;
+-     
+-           /* Fork the child processes.  */
+-           pid = fork ();
+-           if (pid == 0)
+-             /* This is the child process.  */
+-             launch_process (p, j->pgid, infile,
+-                             outfile, j->stderr, foreground);
+-           else if (pid < 0)
+-             {
+-               /* The fork failed.  */
+-               perror ("fork");
+-               exit (1);
+-             }
+-           else
+-             {
+-               /* This is the parent process.  */
+-               p->pid = pid;
+-               if (shell_is_interactive)
+-                 {
+-                   if (!j->pgid)
+-                     j->pgid = pid;
+-                   setpgid (pid, j->pgid);
+-                 }
+-             }
+-     
+-           /* Clean up after pipes.  */
+-           if (infile != j->stdin)
+-             close (infile);
+-           if (outfile != j->stdout)
+-             close (outfile);
+-           infile = mypipe[0];
+-         }
+-     
+-       format_job_info (j, "launched");
+-     
+-       if (!shell_is_interactive)
+-         wait_for_job (j);
+-       else if (foreground)
+-         put_job_in_foreground (j, 0);
+-       else
+-         put_job_in_background (j, 0);
+-     }
+-
+-
+-File: libc.info,  Node: Foreground and Background,  Next: Stopped and 
Terminated Jobs,  Prev: Launching Jobs,  Up: Implementing a Shell
+-
+-Foreground and Background
+--------------------------
+-
+-   Now let's consider what actions must be taken by the shell when it
+-launches a job into the foreground, and how this differs from what must
+-be done when a background job is launched.
+-
+-   When a foreground job is launched, the shell must first give it
+-access to the controlling terminal by calling `tcsetpgrp'.  Then, the
+-shell should wait for processes in that process group to terminate or
+-stop.  This is discussed in more detail in *Note Stopped and Terminated
+-Jobs::.
+-
+-   When all of the processes in the group have either completed or
+-stopped, the shell should regain control of the terminal for its own
+-process group by calling `tcsetpgrp' again.  Since stop signals caused
+-by I/O from a background process or a SUSP character typed by the user
+-are sent to the process group, normally all the processes in the job
+-stop together.
+-
+-   The foreground job may have left the terminal in a strange state, so
+-the shell should restore its own saved terminal modes before
+-continuing.  In case the job is merely been stopped, the shell should
+-first save the current terminal modes so that it can restore them later
+-if the job is continued.  The functions for dealing with terminal modes
+-are `tcgetattr' and `tcsetattr'; these are described in *Note Terminal
+-Modes::.
+-
+-   Here is the sample shell's function for doing all of this.
+-
+-     /* Put job J in the foreground.  If CONT is nonzero,
+-        restore the saved terminal modes and send the process group a
+-        `SIGCONT' signal to wake it up before we block.  */
+-     
+-     void
+-     put_job_in_foreground (job *j, int cont)
+-     {
+-       /* Put the job into the foreground.  */
+-       tcsetpgrp (shell_terminal, j->pgid);
+-
+-     /* Send the job a continue signal, if necessary.  */
+-       if (cont)
+-         {
+-           tcsetattr (shell_terminal, TCSADRAIN, &j->tmodes);
+-           if (kill (- j->pgid, SIGCONT) < 0)
+-             perror ("kill (SIGCONT)");
+-         }
+-     
+-       /* Wait for it to report.  */
+-       wait_for_job (j);
+-     
+-       /* Put the shell back in the foreground.  */
+-       tcsetpgrp (shell_terminal, shell_pgid);
+-     /* Restore the shell's terminal modes.  */
+-       tcgetattr (shell_terminal, &j->tmodes);
+-       tcsetattr (shell_terminal, TCSADRAIN, &shell_tmodes);
+-     }
+-
+-   If the process group is launched as a background job, the shell
+-should remain in the foreground itself and continue to read commands
+-from the terminal.
+-
+-   In the sample shell, there is not much that needs to be done to put
+-a job into the background.  Here is the function it uses:
+-
+-     /* Put a job in the background.  If the cont argument is true, send
+-        the process group a `SIGCONT' signal to wake it up.  */
+-     
+-     void
+-     put_job_in_background (job *j, int cont)
+-     {
+-       /* Send the job a continue signal, if necessary.  */
+-       if (cont)
+-         if (kill (-j->pgid, SIGCONT) < 0)
+-           perror ("kill (SIGCONT)");
+-     }
+-
+-
+-File: libc.info,  Node: Stopped and Terminated Jobs,  Next: Continuing 
Stopped Jobs,  Prev: Foreground and Background,  Up: Implementing a Shell
+-
+-Stopped and Terminated Jobs
+----------------------------
+-
+-   When a foreground process is launched, the shell must block until
+-all of the processes in that job have either terminated or stopped.  It
+-can do this by calling the `waitpid' function; see *Note Process
+-Completion::.  Use the `WUNTRACED' option so that status is reported
+-for processes that stop as well as processes that terminate.
+-
+-   The shell must also check on the status of background jobs so that it
+-can report terminated and stopped jobs to the user; this can be done by
+-calling `waitpid' with the `WNOHANG' option.  A good place to put a
+-such a check for terminated and stopped jobs is just before prompting
+-for a new command.
+-
+-   The shell can also receive asynchronous notification that there is
+-status information available for a child process by establishing a
+-handler for `SIGCHLD' signals.  *Note Signal Handling::.
+-
+-   In the sample shell program, the `SIGCHLD' signal is normally
+-ignored.  This is to avoid reentrancy problems involving the global data
+-structures the shell manipulates.  But at specific times when the shell
+-is not using these data structures--such as when it is waiting for
+-input on the terminal--it makes sense to enable a handler for
+-`SIGCHLD'.  The same function that is used to do the synchronous status
+-checks (`do_job_notification', in this case) can also be called from
+-within this handler.
+-
+-   Here are the parts of the sample shell program that deal with
+-checking the status of jobs and reporting the information to the user.
+-
+-     /* Store the status of the process PID that was returned by waitpid.
+-        Return 0 if all went well, nonzero otherwise.  */
+-     
+-     int
+-     mark_process_status (pid_t pid, int status)
+-     {
+-       job *j;
+-       process *p;
+-
+-     if (pid > 0)
+-         {
+-           /* Update the record for the process.  */
+-           for (j = first_job; j; j = j->next)
+-             for (p = j->first_process; p; p = p->next)
+-               if (p->pid == pid)
+-                 {
+-                   p->status = status;
+-                   if (WIFSTOPPED (status))
+-                     p->stopped = 1;
+-                   else
+-                     {
+-                       p->completed = 1;
+-                       if (WIFSIGNALED (status))
+-                         fprintf (stderr, "%d: Terminated by signal %d.\n",
+-                                  (int) pid, WTERMSIG (p->status));
+-                     }
+-                   return 0;
+-                  }
+-           fprintf (stderr, "No child process %d.\n", pid);
+-           return -1;
+-         }
+-
+-     else if (pid == 0 || errno == ECHILD)
+-         /* No processes ready to report.  */
+-         return -1;
+-       else {
+-         /* Other weird errors.  */
+-         perror ("waitpid");
+-         return -1;
+-       }
+-     }
+-
+-     /* Check for processes that have status information available,
+-        without blocking.  */
+-     
+-     void
+-     update_status (void)
+-     {
+-       int status;
+-       pid_t pid;
+-     
+-       do
+-         pid = waitpid (WAIT_ANY, &status, WUNTRACED|WNOHANG);
+-       while (!mark_process_status (pid, status));
+-     }
+-
+-     /* Check for processes that have status information available,
+-        blocking until all processes in the given job have reported.  */
+-     
+-     void
+-     wait_for_job (job *j)
+-     {
+-       int status;
+-       pid_t pid;
+-     
+-       do
+-         pid = waitpid (WAIT_ANY, &status, WUNTRACED);
+-       while (!mark_process_status (pid, status)
+-              && !job_is_stopped (j)
+-              && !job_is_completed (j));
+-     }
+-
+-     /* Format information about job status for the user to look at.  */
+-     
+-     void
+-     format_job_info (job *j, const char *status)
+-     {
+-       fprintf (stderr, "%ld (%s): %s\n", (long)j->pgid, status, j->command);
+-     }
+-
+-     /* Notify the user about stopped or terminated jobs.
+-        Delete terminated jobs from the active job list.  */
+-     
+-     void
+-     do_job_notification (void)
+-     {
+-       job *j, *jlast, *jnext;
+-       process *p;
+-     
+-       /* Update status information for child processes.  */
+-       update_status ();
+-     
+-       jlast = NULL;
+-       for (j = first_job; j; j = jnext)
+-         {
+-           jnext = j->next;
+-     
+-           /* If all processes have completed, tell the user the job has
+-              completed and delete it from the list of active jobs.  */
+-           if (job_is_completed (j)) {
+-             format_job_info (j, "completed");
+-             if (jlast)
+-               jlast->next = jnext;
+-             else
+-               first_job = jnext;
+-             free_job (j);
+-           }
+-     
+-           /* Notify the user about stopped jobs,
+-              marking them so that we won't do this more than once.  */
+-           else if (job_is_stopped (j) && !j->notified) {
+-             format_job_info (j, "stopped");
+-             j->notified = 1;
+-             jlast = j;
+-           }
+-     
+-           /* Don't say anything about jobs that are still running.  */
+-           else
+-             jlast = j;
+-         }
+-     }
+-
+-
+-File: libc.info,  Node: Continuing Stopped Jobs,  Next: Missing Pieces,  
Prev: Stopped and Terminated Jobs,  Up: Implementing a Shell
+-
+-Continuing Stopped Jobs
+------------------------
+-
+-   The shell can continue a stopped job by sending a `SIGCONT' signal
+-to its process group.  If the job is being continued in the foreground,
+-the shell should first invoke `tcsetpgrp' to give the job access to the
+-terminal, and restore the saved terminal settings.  After continuing a
+-job in the foreground, the shell should wait for the job to stop or
+-complete, as if the job had just been launched in the foreground.
+-
+-   The sample shell program handles both newly created and continued
+-jobs with the same pair of functions, `put_job_in_foreground' and
+-`put_job_in_background'.  The definitions of these functions were given
+-in *Note Foreground and Background::.  When continuing a stopped job, a
+-nonzero value is passed as the CONT argument to ensure that the
+-`SIGCONT' signal is sent and the terminal modes reset, as appropriate.
+-
+-   This leaves only a function for updating the shell's internal
+-bookkeeping about the job being continued:
+-
+-     /* Mark a stopped job J as being running again.  */
+-     
+-     void
+-     mark_job_as_running (job *j)
+-     {
+-       Process *p;
+-     
+-       for (p = j->first_process; p; p = p->next)
+-         p->stopped = 0;
+-       j->notified = 0;
+-     }
+-
+-     /* Continue the job J.  */
+-     
+-     void
+-     continue_job (job *j, int foreground)
+-     {
+-       mark_job_as_running (j);
+-       if (foreground)
+-         put_job_in_foreground (j, 1);
+-       else
+-         put_job_in_background (j, 1);
+-     }
+-
+-
+-File: libc.info,  Node: Missing Pieces,  Prev: Continuing Stopped Jobs,  Up: 
Implementing a Shell
+-
+-The Missing Pieces
+-------------------
+-
+-   The code extracts for the sample shell included in this chapter are
+-only a part of the entire shell program.  In particular, nothing at all
+-has been said about how `job' and `program' data structures are
+-allocated and initialized.
+-
+-   Most real shells provide a complex user interface that has support
+-for a command language; variables; abbreviations, substitutions, and
+-pattern matching on file names; and the like.  All of this is far too
+-complicated to explain here!  Instead, we have concentrated on showing
+-how to implement the core process creation and job control functions
+-that can be called from such a shell.
+-
+-   Here is a table summarizing the major entry points we have presented:
+-
+-`void init_shell (void)'
+-     Initialize the shell's internal state.  *Note Initializing the
+-     Shell::.
+-
+-`void launch_job (job *J, int FOREGROUND)'
+-     Launch the job J as either a foreground or background job.  *Note
+-     Launching Jobs::.
+-
+-`void do_job_notification (void)'
+-     Check for and report any jobs that have terminated or stopped.
+-     Can be called synchronously or within a handler for `SIGCHLD'
+-     signals.  *Note Stopped and Terminated Jobs::.
+-
+-`void continue_job (job *J, int FOREGROUND)'
+-     Continue the job J.  *Note Continuing Stopped Jobs::.
+-
+-   Of course, a real shell would also want to provide other functions
+-for managing jobs.  For example, it would be useful to have commands to
+-list all active jobs or to send a signal (such as `SIGKILL') to a job.
+-
+-
+-File: libc.info,  Node: Functions for Job Control,  Prev: Implementing a 
Shell,  Up: Job Control
+-
+-Functions for Job Control
+-=========================
+-
+-   This section contains detailed descriptions of the functions relating
+-to job control.
+-
+-* Menu:
+-
+-* Identifying the Terminal::    Determining the controlling terminal's name.
+-* Process Group Functions::     Functions for manipulating process groups.
+-* Terminal Access Functions::   Functions for controlling terminal access.
+-
+-
+-File: libc.info,  Node: Identifying the Terminal,  Next: Process Group 
Functions,  Up: Functions for Job Control
+-
+-Identifying the Controlling Terminal
+-------------------------------------
+-
+-   You can use the `ctermid' function to get a file name that you can
+-use to open the controlling terminal.  In the GNU library, it returns
+-the same string all the time: `"/dev/tty"'.  That is a special "magic"
+-file name that refers to the controlling terminal of the current
+-process (if it has one).  To find the name of the specific terminal
+-device, use `ttyname'; *note Is It a Terminal::..
+-
+-   The function `ctermid' is declared in the header file `stdio.h'.
+-
+- - Function: char * ctermid (char *STRING)
+-     The `ctermid' function returns a string containing the file name of
+-     the controlling terminal for the current process.  If STRING is
+-     not a null pointer, it should be an array that can hold at least
+-     `L_ctermid' characters; the string is returned in this array.
+-     Otherwise, a pointer to a string in a static area is returned,
+-     which might get overwritten on subsequent calls to this function.
+-
+-     An empty string is returned if the file name cannot be determined
+-     for any reason.  Even if a file name is returned, access to the
+-     file it represents is not guaranteed.
+-
+- - Macro: int L_ctermid
+-     The value of this macro is an integer constant expression that
+-     represents the size of a string large enough to hold the file name
+-     returned by `ctermid'.
+-
+-   See also the `isatty' and `ttyname' functions, in *Note Is It a
+-Terminal::.
+-
+-
+-File: libc.info,  Node: Process Group Functions,  Next: Terminal Access 
Functions,  Prev: Identifying the Terminal,  Up: Functions for Job Control
+-
+-Process Group Functions
+------------------------
+-
+-   Here are descriptions of the functions for manipulating process
+-groups.  Your program should include the header files `sys/types.h' and
+-`unistd.h' to use these functions.
+-
+- - Function: pid_t setsid (void)
+-     The `setsid' function creates a new session.  The calling process
+-     becomes the session leader, and is put in a new process group whose
+-     process group ID is the same as the process ID of that process.
+-     There are initially no other processes in the new process group,
+-     and no other process groups in the new session.
+-
+-     This function also makes the calling process have no controlling
+-     terminal.
+-
+-     The `setsid' function returns the new process group ID of the
+-     calling process if successful.  A return value of `-1' indicates an
+-     error.  The following `errno' error conditions are defined for this
+-     function:
+-
+-    `EPERM'
+-          The calling process is already a process group leader, or
+-          there is already another process group around that has the
+-          same process group ID.
+-
+-   The `getpgrp' function has two definitions: one derived from BSD
+-Unix, and one from the POSIX.1 standard.  The feature test macros you
+-have selected (*note Feature Test Macros::.) determine which definition
+-you get.  Specifically, you get the BSD version if you define
+-`_BSD_SOURCE'; otherwise, you get the POSIX version if you define
+-`_POSIX_SOURCE' or `_GNU_SOURCE'.  Programs written for old BSD systems
+-will not include `unistd.h', which defines `getpgrp' specially under
+-`_BSD_SOURCE'.  You must link such programs with the `-lbsd-compat'
+-option to get the BSD definition.
+-
+- - POSIX.1 Function: pid_t getpgrp (void)
+-     The POSIX.1 definition of `getpgrp' returns the process group ID of
+-     the calling process.
+-
+- - BSD Function: pid_t getpgrp (pid_t PID)
+-     The BSD definition of `getpgrp' returns the process group ID of the
+-     process PID.  You can supply a value of `0' for the PID argument
+-     to get information about the calling process.
+-
+- - Function: int setpgid (pid_t PID, pid_t PGID)
+-     The `setpgid' function puts the process PID into the process group
+-     PGID.  As a special case, either PID or PGID can be zero to
+-     indicate the process ID of the calling process.
+-
+-     This function fails on a system that does not support job control.
+-     *Note Job Control is Optional::, for more information.
+-
+-     If the operation is successful, `setpgid' returns zero.  Otherwise
+-     it returns `-1'.  The following `errno' error conditions are
+-     defined for this function:
+-
+-    `EACCES'
+-          The child process named by PID has executed an `exec'
+-          function since it was forked.
+-
+-    `EINVAL'
+-          The value of the PGID is not valid.
+-
+-    `ENOSYS'
+-          The system doesn't support job control.
+-
+-    `EPERM'
+-          The process indicated by the PID argument is a session leader,
+-          or is not in the same session as the calling process, or the
+-          value of the PGID argument doesn't match a process group ID
+-          in the same session as the calling process.
+-
+-    `ESRCH'
+-          The process indicated by the PID argument is not the calling
+-          process or a child of the calling process.
+-
+- - Function: int setpgrp (pid_t PID, pid_t PGID)
+-     This is the BSD Unix name for `setpgid'.  Both functions do exactly
+-     the same thing.
+-
+-
+-File: libc.info,  Node: Terminal Access Functions,  Prev: Process Group 
Functions,  Up: Functions for Job Control
+-
+-Functions for Controlling Terminal Access
+------------------------------------------
+-
+-   These are the functions for reading or setting the foreground
+-process group of a terminal.  You should include the header files
+-`sys/types.h' and `unistd.h' in your application to use these functions.
+-
+-   Although these functions take a file descriptor argument to specify
+-the terminal device, the foreground job is associated with the terminal
+-file itself and not a particular open file descriptor.
+-
+- - Function: pid_t tcgetpgrp (int FILEDES)
+-     This function returns the process group ID of the foreground
+-     process group associated with the terminal open on descriptor
+-     FILEDES.
+-
+-     If there is no foreground process group, the return value is a
+-     number greater than `1' that does not match the process group ID
+-     of any existing process group.  This can happen if all of the
+-     processes in the job that was formerly the foreground job have
+-     terminated, and no other job has yet been moved into the
+-     foreground.
+-
+-     In case of an error, a value of `-1' is returned.  The following
+-     `errno' error conditions are defined for this function:
+-
+-    `EBADF'
+-          The FILEDES argument is not a valid file descriptor.
+-
+-    `ENOSYS'
+-          The system doesn't support job control.
+-
+-    `ENOTTY'
+-          The terminal file associated with the FILEDES argument isn't
+-          the controlling terminal of the calling process.
+-
+- - Function: int tcsetpgrp (int FILEDES, pid_t PGID)
+-     This function is used to set a terminal's foreground process group
+-     ID.  The argument FILEDES is a descriptor which specifies the
+-     terminal; PGID specifies the process group.  The calling process
+-     must be a member of the same session as PGID and must have the same
+-     controlling terminal.
+-
+-     For terminal access purposes, this function is treated as output.
+-     If it is called from a background process on its controlling
+-     terminal, normally all processes in the process group are sent a
+-     `SIGTTOU' signal.  The exception is if the calling process itself
+-     is ignoring or blocking `SIGTTOU' signals, in which case the
+-     operation is performed and no signal is sent.
+-
+-     If successful, `tcsetpgrp' returns `0'.  A return value of `-1'
+-     indicates an error.  The following `errno' error conditions are
+-     defined for this function:
+-
+-    `EBADF'
+-          The FILEDES argument is not a valid file descriptor.
+-
+-    `EINVAL'
+-          The PGID argument is not valid.
+-
+-    `ENOSYS'
+-          The system doesn't support job control.
+-
+-    `ENOTTY'
+-          The FILEDES isn't the controlling terminal of the calling
+-          process.
+-
+-    `EPERM'
+-          The PGID isn't a process group in the same session as the
+-          calling process.
+-
+-
+-File: libc.info,  Node: Name Service Switch,  Next: Users and Groups,  Prev: 
Job Control,  Up: Top
+-
+-System Databases and Name Service Switch
+-****************************************
+-
+-   Various functions in the C Library need to be configured to work
+-correctly in the local environment.  Traditionally, this was done by
+-using files (e.g., `/etc/passwd'), but other nameservices (line the
+-Network Information Service (NIS) and the Domain Name Service (DNS))
+-became popular, and were hacked into the C library, usually with a fixed
+-search order (*note frobnicate: (jargon)frobnicate.).
+-
+-   The GNU C Library contains a cleaner solution of this problem.  It is
+-designed after a method used by Sun Microsystems in the C library of
+-Solaris 2.  GNU C Library follows their name and calls this scheme
+-"Name Service Switch" (NSS).
+-
+-   Though the interface might be similar to Sun's version there is no
+-common code.  We never saw any source code of Sun's implementation and
+-so the internal interface is incompatible.  This is also manifests in
+-the file names we use as we will see later.
+-
+-* Menu:
+-
+-* NSS Basics::                  What is this NSS good for.
+-* NSS Configuration File::      Configuring NSS.
+-* NSS Module Internals::        How does it work internally.
+-* Extending NSS::               What to do to add services or databases.
+-
+-
+-File: libc.info,  Node: NSS Basics,  Next: NSS Configuration File,  Prev: 
Name Service Switch,  Up: Name Service Switch
+-
+-NSS Basics
+-==========
+-
+-   The basic idea is to put the implementation of the different services
+-offered to access the databases in separate modules.  This has some
+-advantages:
+-
+-  1. Contributors can add new services without adding them to GNU C
+-     Library.
+-
+-  2. The modules can be updated separately.
+-
+-  3. The C library image is smaller.
+-
+-   To fulfill the first goal above the ABI of the modules will be
+-described below.  For getting the implementation of a new service right
+-it is important to understand how the functions in the modules get
+-called.  They are in no way designed to be used by the programmer
+-directly.  Instead the programmer should only use the documented and
+-standardized functions to access the databases.
+-
+-The databases available in the NSS are
+-
+-`ethers'
+-     Ethernet numbers,
+-
+-`group'
+-     Groups of users, *note Group Database::..
+-
+-`hosts'
+-     Host names and numbers, *note Host Names::..
+-
+-`netgroup'
+-     Network wide list of host and users, *note Netgroup Database::..
+-
+-`network'
+-     Network names and numbers, *note Networks Database::..
+-
+-`protocols'
+-     Network protocols, *note Protocols Database::..
+-
+-`passwd'
+-     User passwords, *note User Database::..
+-
+-`rpc'
+-     Remote procedure call names and numbers,
+-
+-`services'
+-     Network services, *note Services Database::..
+-
+-`shadow'
+-     Shadow user passwords,
+-
+-There will be some more added later (`aliases', `automount',
+-`bootparams', `netmasks', and `publickey').
+-
+-
+-File: libc.info,  Node: NSS Configuration File,  Next: NSS Module Internals,  
Prev: NSS Basics,  Up: Name Service Switch
+-
+-The NSS Configuration File
+-==========================
+-
+-   Somehow the NSS code must be told about the wishes of the user.  For
+-this reason there is the file `/etc/nsswitch.conf'.  For each database
+-this file contain a specification how the lookup process should work.
+-The file could look like this:
+-
+-     # /etc/nsswitch.conf
+-     #
+-     # Name Service Switch configuration file.
+-     #
+-     
+-     passwd:     db files nis
+-     shadow:     files
+-     group:      db files nis
+-     
+-     hosts:      files nisplus nis dns
+-     networks:   nisplus [NOTFOUND=return] files
+-     
+-     ethers:     nisplus [NOTFOUND=return] db files
+-     protocols:  nisplus [NOTFOUND=return] db files
+-     rpc:        nisplus [NOTFOUND=return] db files
+-     services:   nisplus [NOTFOUND=return] db files
+-
+-   The first column is the database as you can guess from the table
+-above.  The rest of the line specifies how the lookup process works.
+-Please note that you specify the way it works for each database
+-individually.  This cannot be done with the old way of a monolithic
+-implementation.
+-
+-   The configuration specification for each database can contain two
+-different items:
+-
+-   * the service specification like `files', `db', or `nis'.
+-
+-   * the reaction on lookup result line `[NOTFOUND=return]'.
+-
+-* Menu:
+-
+-* Services in the NSS configuration::  Service names in the NSS configuration.
+-* Actions in the NSS configuration::  React appropriately to the lookup 
result.
+-* Notes on NSS Configuration File::  Things to take care about while
+-                                     configuring NSS.
+-
+-
+-File: libc.info,  Node: Services in the NSS configuration,  Next: Actions in 
the NSS configuration,  Prev: NSS Configuration File,  Up: NSS Configuration 
File
+-
+-Services in the NSS configuration File
+---------------------------------------
+-
+-   The above example file mentions four different services: `files',
+-`db', `nis', and `nisplus'.  This does not mean these services are
+-available on all sites and it does also not mean these are all the
+-services which will ever be available.
+-
+-   In fact, these names are simply strings which the NSS code uses to
+-find the implicitly addressed functions.  The internal interface will be
+-described later.  Visible to the user are the modules which implement an
+-individual service.
+-
+-   Assume the service NAME shall be used for a lookup.  The code for
+-this service is implemented in a module called `libnss_NAME'.  On a
+-system supporting shared libraries this is in fact a shared library
+-with the name (for example) `libnss_NAME.so.1'.  The number at the end
+-is the currently used version of the interface which will not change
+-frequently.  Normally the user should not have to be cognizant of these
+-files since they should be placed in a directory where they are found
+-automatically.  Only the names of all available services are important.
+-
+-
+-File: libc.info,  Node: Actions in the NSS configuration,  Next: Notes on NSS 
Configuration File,  Prev: Services in the NSS configuration,  Up: NSS 
Configuration File
+-
+-Actions in the NSS configuration
+---------------------------------
+-
+-   The second item in the specification gives the user much finer
+-control on the lookup process.  Action items are placed between two
+-service names and are written within brackets.  The general form is
+-
+-     `[' ( `!'? STATUS `=' ACTION )+ `]'
+-
+-where
+-
+-     STATUS => success | notfound | unavail | tryagain
+-     ACTION => return | continue
+-
+-   The case of the keywords is insignificant.  The STATUS values are
+-the results of a call to a lookup function of a specific service.  They
+-mean
+-
+-`success'
+-     No error occurred and the wanted entry is returned.  The default
+-     action for this is `return'.
+-
+-`notfound'
+-     The lookup process works ok but the needed value was not found.
+-     The default action is `continue'.
+-
+-`unavail'
+-     The service is permanently unavailable.  This can either mean the
+-     needed file is not available, or, for DNS, the server is not
+-     available or does not allow queries.  The default action is
+-     `continue'.
+-
+-`tryagain'
+-     The service is temporarily unavailable.  This could mean a file is
+-     locked or a server currently cannot accept more connections.  The
+-     default action is `continue'.
+-
+-If we have a line like
+-
+-     ethers: nisplus [NOTFOUND=return] db files
+-
+-this is equivalent to
+-
+-     ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue
+-                      TRYAGAIN=continue]
+-             db      [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
+-                      TRYAGAIN=continue]
+-             files
+-
+-(except that it would have to be written on one line).  The default
+-value for the actions are normally what you want, and only need to be
+-changed in exceptional cases.
+-
+-   If the optional `!' is placed before the STATUS this means the
+-following action is used for all statii but STATUS itself.  I.e., `!'
+-is negation as in the C language (and others).
+-
+-   Before we explain the exception which makes this action item
+-necessary one more remark: obviously it makes no sense to add another
+-action item after the `files' service.  Since there is no other service
+-following the action *always* is `return'.
+-
+-   Now, why is this `[NOTFOUND=return]' action useful?  To understand
+-this we should know that the `nisplus' service is often complete; i.e.,
+-if an entry is not available in the NIS+ tables it is not available
+-anywhere else.  This is what is expressed by this action item: it is
+-useless to examine further services since they will not give us a
+-result.
+-
+-   The situation would be different if the NIS+ service is not available
+-because the machine is booting.  In this case the return value of the
+-lookup function is not `notfound' but instead `unavail'.  And as you
+-can see in the complete form above: in this situation the `db' and
+-`files' services are used.  Neat, isn't it?  The system administrator
+-need not pay special care for the time the system is not completely
+-ready to work (while booting or shutdown or network problems).
+-
+-
+-File: libc.info,  Node: Notes on NSS Configuration File,  Prev: Actions in 
the NSS configuration,  Up: NSS Configuration File
+-
+-Notes on the NSS Configuration File
+------------------------------------
+-
+-   Finally a few more hints.  The NSS implementation is not completely
+-helpless if `/etc/nsswitch.conf' does not exist.  For all supported
+-databases there is a default value so it should normally be possible to
+-get the system running even if the file is corrupted or missing.
+-
+-   For the `hosts' and `network' databases the default value is `dns
+-[!UNAVAIL=return] files'.  I.e., the system is prepared for the DNS
+-service not to be available but if it is available the answer it
+-returns is ultimative.
+-
+-   The `passwd', `group', and `shadow' databases are traditionally
+-handled in a special way.  The appropriate files in the `/etc'
+-directory are read but if an entry with a name starting with a `+'
+-character is found NIS is used.  This kind of lookup remains possible
+-by using the special lookup service `compat' and the default value for
+-the three databases above is `compat [NOTFOUND=return] files'.
+-
+-   For all other databases the default value is `nis [NOTFOUND=return]
+-files'.  This solution give the best chance to be correct since NIS and
+-file based lookup is used.
+-
+-   A second point is that the user should try to optimize the lookup
+-process.  The different service have different response times.  A
+-simple file look up on a local file could be fast, but if the file is
+-long and the needed entry is near the end of the file this may take
+-quite some time.  In this case it might be better to use the `db'
+-service which allows fast local access to large data sets.
+-
+-   Often the situation is that some global information like NIS must be
+-used.  So it is unavoidable to use service entries like `nis' etc.  But
+-one should avoid slow services like this if possible.
+-
+-
+-File: libc.info,  Node: NSS Module Internals,  Next: Extending NSS,  Prev: 
NSS Configuration File,  Up: Name Service Switch
+-
+-NSS Module Internals
+-====================
+-
+-   Now it is time to described how the modules look like.  The functions
+-contained in a module are identified by their names.  I.e., there is no
+-jump table or the like.  How this is done is of no interest here; those
+-interested in this topic should read about Dynamic Linking.
+-
+-* Menu:
+-
+-* NSS Module Names::            Construction of the interface function of
+-                                the NSS modules.
+-* NSS Modules Interface::       Programming interface in the NSS module
+-                                functions.
+-
+-
+-File: libc.info,  Node: NSS Module Names,  Next: NSS Modules Interface,  
Prev: NSS Module Internals,  Up: NSS Module Internals
+-
+-The Naming Scheme of the NSS Modules
+-------------------------------------
+-
+-The name of each function consist of various parts:
+-
+-            _nss_SERVICE_FUNCTION
+-
+-   SERVICE of course corresponds to the name of the module this
+-function is found in.(1)  The FUNCTION part is derived from the
+-interface function in the C library itself.  If the user calls the
+-function `gethostbyname' and the service used is `files' the function
+-
+-            _nss_files_gethostbyname_r
+-
+-in the module
+-
+-            libnss_files.so.1
+-
+-is used.  You see, what is explained above in not the whole truth.  In
+-fact the NSS modules only contain reentrant versions of the lookup
+-functions.  I.e., if the user would call the `gethostbyname_r' function
+-this also would end in the above function.  For all user interface
+-functions the C library maps this call to a call to the reentrant
+-function.  For reentrant functions this is trivial since the interface
+-is (nearly) the same.  For the non-reentrant version pointers to static
+-buffers are used to replace the user supplied buffers.
+-
+-   I.e., the reentrant functions *can* have counterparts.  No service
+-module is forced to have functions for all databases and all kinds to
+-access them.  If a function is not available it is simply treated as if
+-the function would return `unavail' (*note Actions in the NSS
+-configuration::.).
+-
+-   The file name `libnss_files.so.1' would be on a Solaris 2 system
+-`nss_files.so.1'.  This is the difference mentioned above.  Sun's NSS
+-modules are usable as modules which get indirectly loaded only.
+-
+-   The NSS modules in the GNU C Library are prepared to be used as
+-normal libraries itself.  This is *not* true in the moment, though.
+-But the different organization of the name space in the modules does
+-not make it impossible like it is for Solaris.  Now you can see why the
+-modules are still libraries.(2)
+-
+-   ---------- Footnotes ----------
+-
+-   (1)  Now you might ask why to duplicate this information.  The
+-answer is that we want to keep the possibility to link directly with
+-these shared objects.
+-
+-   (2)  There is a second explanation: we were too lazy to change the
+-Makefiles to allow the generation of shared objects not starting with
+-`lib' but do not tell this anybody.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-25 
glibc-2.0.1/manual/libc.info-25
+--- ../glibc-2.0.1/manual/libc.info-25 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-25    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1217 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: NSS Modules Interface,  Prev: NSS Module Names,  Up: 
NSS Module Internals
+-
+-The Interface of the Function in NSS Modules
+---------------------------------------------
+-
+-   Now we know about the functions contained in the modules.  It is now
+-time to describe the types.  When we mentioned the reentrant versions of
+-the functions above, this means there are some additional arguments
+-(compared with the standard, non-reentrant version).  The prototypes for
+-the non-reentrant and reentrant versions of our function above are:
+-
+-     struct hostent *gethostbyname (const char *name)
+-     
+-     int gethostbyname_r (const char *name, struct hostent *result_buf,
+-                          char *buf, size_t buflen, struct hostent **result,
+-                          int *h_errnop)
+-
+-The actual prototype of the function in the NSS modules in this case is
+-
+-     enum nss_status _nss_files_gethostbyname_r (const char *name,
+-                                                 struct hostent *result_buf,
+-                                                 char *buf, size_t buflen,
+-                                                 int *h_errnop)
+-
+-   I.e., the interface function is in fact the reentrant function with
+-the change of the return value.  While the user-level function returns a
+-pointer to the result the reentrant function return an `enum
+-nss_status' value:
+-
+-`NSS_STATUS_TRYAGAIN'
+-     numeric value `-2'
+-
+-`NSS_STATUS_UNAVAIL'
+-     numeric value `-1'
+-
+-`NSS_STATUS_NOTFOUND'
+-     numeric value `0'
+-
+-`NSS_STATUS_SUCCESS'
+-     numeric value `1'
+-
+-Now you see where the action items of the `/etc/nsswitch.conf' file are
+-used.
+-
+-   If you study the source code you will find there is a fifth value:
+-`NSS_STATUS_RETURN'.  This is an internal use only value, used by a few
+-functions in places where none of the above value can be used.  If
+-necessary the source code should be examined to learn about the details.
+-
+-   The above function has something special which is missing for almost
+-all the other module functions.  There is an argument H_ERRNOP.  This
+-points to a variable which will be filled with the error code in case
+-the execution of the function fails for some reason.  The reentrant
+-function cannot use the global variable H_ERRNO; `gethostbyname' calls
+-`gethostbyname_r' with the last argument set to `&h_errno'.
+-
+-   The `getXXXbyYYY' functions are the most important functions in the
+-NSS modules.  But there are others which implement the other ways to
+-access system databases (say for the password database, there are
+-`setpwent', `getpwent', and `endpwent').  These will be described in
+-more detail later.  Here we give a general way to determine the
+-signature of the module function:
+-
+-   * the return value is `int';
+-
+-   * the name is as explain in *note NSS Module Names::.;
+-
+-   * the first arguments are identical to the arguments of the
+-     non-reentrant function;
+-
+-   * the next three arguments are:
+-
+-    `STRUCT_TYPE result_buf'
+-          pointer to buffer where the result is stored.  `STRUCT_TYPE'
+-          is normally a struct which corresponds to the database.
+-
+-    `char *buffer'
+-          pointer to a buffer where the function can store additional
+-          adata for the result etc.
+-
+-    `int buflen'
+-          length of the buffer pointed to by BUFFER.
+-
+-   * possibly a last argument H_ERRNOP, for the host name and network
+-     name lookup functions.
+-
+-This table is correct for all functions but the `set...ent' and
+-`end...ent' functions.
+-
+-
+-File: libc.info,  Node: Extending NSS,  Prev: NSS Module Internals,  Up: Name 
Service Switch
+-
+-Extending NSS
+-=============
+-
+-   One of the advantages of NSS mentioned above is that it can be
+-extended quite easily.  There are two ways in which the extension can
+-happen: adding another database or adding another service.  The former
+-is normally done only by the C library developers.  It is here only
+-important to remember that adding another database is independent from
+-adding another service because a service need not support all databases
+-or lookup functions.
+-
+-   A designer/implementor of a new service is therefore free to choose
+-the databases s/he is interested in and leave the rest for later (or
+-completely aside).
+-
+-* Menu:
+-
+-* Adding another Service to NSS::  What is to do to add a new service.
+-* NSS Module Function Internals::  Guidelines for writing new NSS
+-                                        service functions.
+-
+-
+-File: libc.info,  Node: Adding another Service to NSS,  Next: NSS Module 
Function Internals,  Prev: Extending NSS,  Up: Extending NSS
+-
+-Adding another Service to NSS
+------------------------------
+-
+-   The sources for a new service need not (and should not) be part of
+-the GNU C Library itself.  The developer retains complete control over
+-the sources and its development.  The links between the C library and
+-the new service module consists solely of the interface functions.
+-
+-   Each module is designed following a specific interface specification.
+-For now the version is 1 and this manifests in the version number of the
+-shared library object of the NSS modules: they have the extension `.1'.
+-If the interface ever changes in an incompatible way, this number will
+-be increased--hopefully this will never be necessary.  Modules using
+-the old interface will still be usable.
+-
+-   Developers of a new service will have to make sure that their module
+-is created using the correct interface number.  This means the file
+-itself must have the correct name and on ElF systems the "soname"
+-(Shared Object Name) must also have this number.  Building a module
+-from a bunch of object files on an ELF system using GNU CC could be
+-done like this:
+-
+-     gcc -shared -o libnss_NAME.so.1 -Wl,-soname,libnss_NAME.so.1 OBJECTS
+-
+-*Note Options for Linking: (gcc)Link Options, to learn more about this
+-command line.
+-
+-   To use the new module the library must be able to find it.  This can
+-be achieved by using options for the dynamic linker so that it will
+-search directory where the binary is placed.  For an ELF system this
+-could be done by adding the wanted directory to the value of
+-`LD_LIBRARY_PATH'.
+-
+-   But this is not always possible since some program (those which run
+-under IDs which do not belong to the user) ignore this variable.
+-Therefore the stable version of the module should be placed into a
+-directory which is searched by the dynamic linker.  Normally this should
+-be the directory `$prefix/lib', where `$prefix' corresponds to the
+-value given to configure using the `--prefix' option.  But be careful:
+-this should only be done if it is clear the module does not cause any
+-harm.  System administrators should be careful.
+-
+-
+-File: libc.info,  Node: NSS Module Function Internals,  Prev: Adding another 
Service to NSS,  Up: Extending NSS
+-
+-Internals of the NSS Module Functions
+--------------------------------------
+-
+-   Until now we only provided the syntactic interface for the functions
+-in the NSS module.  In fact there is not more much we can tell since the
+-implementation obviously is different for each function.  But a few
+-general rules must be followed by all functions.
+-
+-   In fact there are four kinds of different functions which may appear
+-in the interface.  All derive from the traditional ones for system
+-databases.  DB in the following table is normally an abbreviation for
+-the database (e.g., it is `pw' for the password database).
+-
+-`enum nss_status _nss_DATABASE_setDBent (void)'
+-     This function prepares the service for following operations.  For a
+-     simple file based lookup this means files could be opened, for
+-     other services this function simply is a noop.
+-
+-     One special case for this function is that it takes an additional
+-     argument for some DATABASEs (i.e., the interface is `int setDBent
+-     (int)').  *Note Host Names::, which describes the `sethostent'
+-     function.
+-
+-     The return value should be NSS_STATUS_SUCCESS or according to the
+-     table above in case of an error (*note NSS Modules Interface::.).
+-
+-`enum nss_status _nss_DATABASE_endDBent (void)'
+-     This function simply closes all files which are still open or
+-     removes buffer caches.  If there are no files or buffers to remove
+-     this is again a simple noop.
+-
+-     There normally is no return value different to NSS_STATUS_SUCCESS.
+-
+-`enum nss_status _nss_DATABASE_getDBent_r (STRUCTURE *result, char *buffer, 
size_t buflen)'
+-     Since this function will be called several times in a row to
+-     retrieve one entry after the other it must keep some kind of
+-     state.  But this also means the functions are not really
+-     reentrant.  They are reentrant only in that simultaneous calls to
+-     this function will not try to write the retrieved data in the same
+-     place (as it would be the case for the non-reentrant functions);
+-     instead, it writes to the structure pointed to by the RESULT
+-     parameter.  But the calls share a common state and in the case of
+-     a file access this means they return neighboring entries in the
+-     file.
+-
+-     The buffer of length BUFLEN pointed to by BUFFER can be used for
+-     storing some additional data for the result.  It is *not*
+-     guaranteed that the same buffer will be passed for the next call
+-     of this function.  Therefore one must not misuse this buffer to
+-     save some state information from one call to another.
+-
+-     As explained above this function could also have an additional last
+-     argument.  This depends on the database used; it happens only for
+-     `host' and `network'.
+-
+-     The function shall return `NSS_STATUS_SUCCESS' as long as their are
+-     more entries.  When the last entry was read it should return
+-     `NSS_STATUS_NOTFOUND'.  When the buffer given as an argument is too
+-     small for the data to be returned `NSS_STATUS_TRYAGAIN' should be
+-     returned.  When the service was not formerly initialized by a call
+-     to `_nss_DATABASE_setDBent' all return value allowed for this
+-     function can also be returned here.
+-
+-`enum nss_status _nss_DATABASE_getDBbyXX_r (PARAMS, STRUCTURE *result, char 
*buffer, size_t buflen)'
+-     This function shall return the entry from the database which is
+-     addressed by the PARAMS.  The type and number of these arguments
+-     vary.  It must be individually determined by looking to the
+-     user-level interface functions.  All arguments given to the
+-     non-reentrant version are here described by PARAMS.
+-
+-     The result must be stored in the structure pointed to by RESULT.
+-     If there is additional data to return (say strings, where the
+-     RESULT structure only contains pointers) the function must use the
+-     BUFFER or length BUFLEN.  There must not be any references to
+-     non-constant global data.
+-
+-     The implementation of this function should honour the STAYOPEN
+-     flag set by the `setDBent' function whenever this makes sense.
+-
+-     Again, this function takes an additional last argument for the
+-     `host' and `network' database.
+-
+-     The return value should as always follow the rules given above
+-     (*note NSS Modules Interface::.).
+-
+-
+-File: libc.info,  Node: Users and Groups,  Next: System Information,  Prev: 
Name Service Switch,  Up: Top
+-
+-Users and Groups
+-****************
+-
+-   Every user who can log in on the system is identified by a unique
+-number called the "user ID".  Each process has an effective user ID
+-which says which user's access permissions it has.
+-
+-   Users are classified into "groups" for access control purposes.  Each
+-process has one or more "group ID values" which say which groups the
+-process can use for access to files.
+-
+-   The effective user and group IDs of a process collectively form its
+-"persona".  This determines which files the process can access.
+-Normally, a process inherits its persona from the parent process, but
+-under special circumstances a process can change its persona and thus
+-change its access permissions.
+-
+-   Each file in the system also has a user ID and a group ID.  Access
+-control works by comparing the user and group IDs of the file with those
+-of the running process.
+-
+-   The system keeps a database of all the registered users, and another
+-database of all the defined groups.  There are library functions you
+-can use to examine these databases.
+-
+-* Menu:
+-
+-* User and Group IDs::          Each user has a unique numeric ID;
+-                               likewise for groups.
+-* Process Persona::             The user IDs and group IDs of a process.
+-* Why Change Persona::          Why a program might need to change
+-                               its user and/or group IDs.
+-* How Change Persona::          Changing the user and group IDs.
+-* Reading Persona::             How to examine the user and group IDs.
+-
+-* Setting User ID::             Functions for setting the user ID.
+-* Setting Groups::              Functions for setting the group IDs.
+-
+-* Enable/Disable Setuid::       Turning setuid access on and off.
+-* Setuid Program Example::      The pertinent parts of one sample program.
+-* Tips for Setuid::             How to avoid granting unlimited access.
+-
+-* Who Logged In::               Getting the name of the user who logged in,
+-                               or of the real user ID of the current process.
+-
+-* User Database::               Functions and data structures for
+-                               accessing the user database.
+-* Group Database::              Functions and data structures for
+-                               accessing the group database.
+-* Netgroup Database::           Functions for accessing the netgroup database.
+-* Database Example::            Example program showing use of database
+-                               inquiry functions.
+-
+-
+-File: libc.info,  Node: User and Group IDs,  Next: Process Persona,  Prev: 
Users and Groups,  Up: Users and Groups
+-
+-User and Group IDs
+-==================
+-
+-   Each user account on a computer system is identified by a "user
+-name" (or "login name") and "user ID".  Normally, each user name has a
+-unique user ID, but it is possible for several login names to have the
+-same user ID.  The user names and corresponding user IDs are stored in
+-a data base which you can access as described in *Note User Database::.
+-
+-   Users are classified in "groups".  Each user name also belongs to
+-one or more groups, and has one "default group".  Users who are members
+-of the same group can share resources (such as files) that are not
+-accessible to users who are not a member of that group.  Each group has
+-a "group name" and "group ID".  *Note Group Database::, for how to find
+-information about a group ID or group name.
+-
+-
+-File: libc.info,  Node: Process Persona,  Next: Why Change Persona,  Prev: 
User and Group IDs,  Up: Users and Groups
+-
+-The Persona of a Process
+-========================
+-
+-   At any time, each process has a single user ID and a group ID which
+-determine the privileges of the process.  These are collectively called
+-the "persona" of the process, because they determine "who it is" for
+-purposes of access control.  These IDs are also called the "effective
+-user ID" and "effective group ID" of the process.
+-
+-   Your login shell starts out with a persona which consists of your
+-user ID and your default group ID.  In normal circumstances, all your
+-other processes inherit these values.
+-
+-   A process also has a "real user ID" which identifies the user who
+-created the process, and a "real group ID" which identifies that user's
+-default group.  These values do not play a role in access control, so
+-we do not consider them part of the persona.  But they are also
+-important.
+-
+-   Both the real and effective user ID can be changed during the
+-lifetime of a process.  *Note Why Change Persona::.
+-
+-   In addition, a user can belong to multiple groups, so the persona
+-includes "supplementary group IDs" that also contribute to access
+-permission.
+-
+-   For details on how a process's effective user IDs and group IDs
+-affect its permission to access files, see *Note Access Permission::.
+-
+-   The user ID of a process also controls permissions for sending
+-signals using the `kill' function.  *Note Signaling Another Process::.
+-
+-
+-File: libc.info,  Node: Why Change Persona,  Next: How Change Persona,  Prev: 
Process Persona,  Up: Users and Groups
+-
+-Why Change the Persona of a Process?
+-====================================
+-
+-   The most obvious situation where it is necessary for a process to
+-change its user and/or group IDs is the `login' program.  When `login'
+-starts running, its user ID is `root'.  Its job is to start a shell
+-whose user and group IDs are those of the user who is logging in.  (To
+-accomplish this fully, `login' must set the real user and group IDs as
+-well as its persona.  But this is a special case.)
+-
+-   The more common case of changing persona is when an ordinary user
+-program needs access to a resource that wouldn't ordinarily be
+-accessible to the user actually running it.
+-
+-   For example, you may have a file that is controlled by your program
+-but that shouldn't be read or modified directly by other users, either
+-because it implements some kind of locking protocol, or because you want
+-to preserve the integrity or privacy of the information it contains.
+-This kind of restricted access can be implemented by having the program
+-change its effective user or group ID to match that of the resource.
+-
+-   Thus, imagine a game program that saves scores in a file.  The game
+-program itself needs to be able to update this file no matter who is
+-running it, but if users can write the file without going through the
+-game, they can give themselves any scores they like.  Some people
+-consider this undesirable, or even reprehensible.  It can be prevented
+-by creating a new user ID and login name (say, `games') to own the
+-scores file, and make the file writable only by this user.  Then, when
+-the game program wants to update this file, it can change its effective
+-user ID to be that for `games'.  In effect, the program must adopt the
+-persona of `games' so it can write the scores file.
+-
+-
+-File: libc.info,  Node: How Change Persona,  Next: Reading Persona,  Prev: 
Why Change Persona,  Up: Users and Groups
+-
+-How an Application Can Change Persona
+-=====================================
+-
+-   The ability to change the persona of a process can be a source of
+-unintentional privacy violations, or even intentional abuse.  Because of
+-the potential for problems, changing persona is restricted to special
+-circumstances.
+-
+-   You can't arbitrarily set your user ID or group ID to anything you
+-want; only privileged processes can do that.  Instead, the normal way
+-for a program to change its persona is that it has been set up in
+-advance to change to a particular user or group.  This is the function
+-of the setuid and setgid bits of a file's access mode.  *Note
+-Permission Bits::.
+-
+-   When the setuid bit of an executable file is set, executing that file
+-automatically changes the effective user ID to the user that owns the
+-file.  Likewise, executing a file whose setgid bit is set changes the
+-effective group ID to the group of the file.  *Note Executing a File::.
+-Creating a file that changes to a particular user or group ID thus
+-requires full access to that user or group ID.
+-
+-   *Note File Attributes::, for a more general discussion of file modes
+-and accessibility.
+-
+-   A process can always change its effective user (or group) ID back to
+-its real ID.  Programs do this so as to turn off their special
+-privileges when they are not needed, which makes for more robustness.
+-
+-
+-File: libc.info,  Node: Reading Persona,  Next: Setting User ID,  Prev: How 
Change Persona,  Up: Users and Groups
+-
+-Reading the Persona of a Process
+-================================
+-
+-   Here are detailed descriptions of the functions for reading the user
+-and group IDs of a process, both real and effective.  To use these
+-facilities, you must include the header files `sys/types.h' and
+-`unistd.h'.
+-
+- - Data Type: uid_t
+-     This is an integer data type used to represent user IDs.  In the
+-     GNU library, this is an alias for `unsigned int'.
+-
+- - Data Type: gid_t
+-     This is an integer data type used to represent group IDs.  In the
+-     GNU library, this is an alias for `unsigned int'.
+-
+- - Function: uid_t getuid (void)
+-     The `getuid' function returns the real user ID of the process.
+-
+- - Function: gid_t getgid (void)
+-     The `getgid' function returns the real group ID of the process.
+-
+- - Function: uid_t geteuid (void)
+-     The `geteuid' function returns the effective user ID of the
+-     process.
+-
+- - Function: gid_t getegid (void)
+-     The `getegid' function returns the effective group ID of the
+-     process.
+-
+- - Function: int getgroups (int COUNT, gid_t *GROUPS)
+-     The `getgroups' function is used to inquire about the supplementary
+-     group IDs of the process.  Up to COUNT of these group IDs are
+-     stored in the array GROUPS; the return value from the function is
+-     the number of group IDs actually stored.  If COUNT is smaller than
+-     the total number of supplementary group IDs, then `getgroups'
+-     returns a value of `-1' and `errno' is set to `EINVAL'.
+-
+-     If COUNT is zero, then `getgroups' just returns the total number
+-     of supplementary group IDs.  On systems that do not support
+-     supplementary groups, this will always be zero.
+-
+-     Here's how to use `getgroups' to read all the supplementary group
+-     IDs:
+-
+-          gid_t *
+-          read_all_groups (void)
+-          {
+-            int ngroups = getgroups (0, NULL);
+-            gid_t *groups
+-              = (gid_t *) xmalloc (ngroups * sizeof (gid_t));
+-            int val = getgroups (ngroups, groups);
+-            if (val < 0)
+-              {
+-                free (groups);
+-                return NULL;
+-              }
+-            return groups;
+-          }
+-
+-
+-File: libc.info,  Node: Setting User ID,  Next: Setting Groups,  Prev: 
Reading Persona,  Up: Users and Groups
+-
+-Setting the User ID
+-===================
+-
+-   This section describes the functions for altering the user ID (real
+-and/or effective) of a process.  To use these facilities, you must
+-include the header files `sys/types.h' and `unistd.h'.
+-
+- - Function: int setuid (uid_t NEWUID)
+-     This function sets both the real and effective user ID of the
+-     process to NEWUID, provided that the process has appropriate
+-     privileges.
+-
+-     If the process is not privileged, then NEWUID must either be equal
+-     to the real user ID or the saved user ID (if the system supports
+-     the `_POSIX_SAVED_IDS' feature).  In this case, `setuid' sets only
+-     the effective user ID and not the real user ID.
+-
+-     The `setuid' function returns a value of `0' to indicate
+-     successful completion, and a value of `-1' to indicate an error.
+-     The following `errno' error conditions are defined for this
+-     function:
+-
+-    `EINVAL'
+-          The value of the NEWUID argument is invalid.
+-
+-    `EPERM'
+-          The process does not have the appropriate privileges; you do
+-          not have permission to change to the specified ID.
+-
+- - Function: int setreuid (uid_t RUID, uid_t EUID)
+-     This function sets the real user ID of the process to RUID and the
+-     effective user ID to EUID.  If RUID is `-1', it means not to
+-     change the real user ID; likewise if EUID is `-1', it means not to
+-     change the effective user ID.
+-
+-     The `setreuid' function exists for compatibility with 4.3 BSD Unix,
+-     which does not support saved IDs.  You can use this function to
+-     swap the effective and real user IDs of the process.  (Privileged
+-     processes are not limited to this particular usage.)  If saved IDs
+-     are supported, you should use that feature instead of this
+-     function.  *Note Enable/Disable Setuid::.
+-
+-     The return value is `0' on success and `-1' on failure.  The
+-     following `errno' error conditions are defined for this function:
+-
+-    `EPERM'
+-          The process does not have the appropriate privileges; you do
+-          not have permission to change to the specified ID.
+-
+-
+-File: libc.info,  Node: Setting Groups,  Next: Enable/Disable Setuid,  Prev: 
Setting User ID,  Up: Users and Groups
+-
+-Setting the Group IDs
+-=====================
+-
+-   This section describes the functions for altering the group IDs (real
+-and effective) of a process.  To use these facilities, you must include
+-the header files `sys/types.h' and `unistd.h'.
+-
+- - Function: int setgid (gid_t NEWGID)
+-     This function sets both the real and effective group ID of the
+-     process to NEWGID, provided that the process has appropriate
+-     privileges.
+-
+-     If the process is not privileged, then NEWGID must either be equal
+-     to the real group ID or the saved group ID.  In this case, `setgid'
+-     sets only the effective group ID and not the real group ID.
+-
+-     The return values and error conditions for `setgid' are the same
+-     as those for `setuid'.
+-
+- - Function: int setregid (gid_t RGID, fid_t EGID)
+-     This function sets the real group ID of the process to RGID and
+-     the effective group ID to EGID.  If RGID is `-1', it means not to
+-     change the real group ID; likewise if EGID is `-1', it means not
+-     to change the effective group ID.
+-
+-     The `setregid' function is provided for compatibility with 4.3 BSD
+-     Unix, which does not support saved IDs.  You can use this function
+-     to swap the effective and real group IDs of the process.
+-     (Privileged processes are not limited to this usage.)  If saved
+-     IDs are supported, you should use that feature instead of using
+-     this function.  *Note Enable/Disable Setuid::.
+-
+-     The return values and error conditions for `setregid' are the same
+-     as those for `setreuid'.
+-
+-   The GNU system also lets privileged processes change their
+-supplementary group IDs.  To use `setgroups' or `initgroups', your
+-programs should include the header file `grp.h'.
+-
+- - Function: int setgroups (size_t COUNT, gid_t *GROUPS)
+-     This function sets the process's supplementary group IDs.  It can
+-     only be called from privileged processes.  The COUNT argument
+-     specifies the number of group IDs in the array GROUPS.
+-
+-     This function returns `0' if successful and `-1' on error.  The
+-     following `errno' error conditions are defined for this function:
+-
+-    `EPERM'
+-          The calling process is not privileged.
+-
+- - Function: int initgroups (const char *USER, gid_t GID)
+-     The `initgroups' function effectively calls `setgroups' to set the
+-     process's supplementary group IDs to be the normal default for the
+-     user name USER.  The group ID GID is also included.
+-
+-
+-File: libc.info,  Node: Enable/Disable Setuid,  Next: Setuid Program Example, 
 Prev: Setting Groups,  Up: Users and Groups
+-
+-Enabling and Disabling Setuid Access
+-====================================
+-
+-   A typical setuid program does not need its special access all of the
+-time.  It's a good idea to turn off this access when it isn't needed,
+-so it can't possibly give unintended access.
+-
+-   If the system supports the saved user ID feature, you can accomplish
+-this with `setuid'.  When the game program starts, its real user ID is
+-`jdoe', its effective user ID is `games', and its saved user ID is also
+-`games'.  The program should record both user ID values once at the
+-beginning, like this:
+-
+-     user_user_id = getuid ();
+-     game_user_id = geteuid ();
+-
+-   Then it can turn off game file access with
+-
+-     setuid (user_user_id);
+-
+-and turn it on with
+-
+-     setuid (game_user_id);
+-
+-Throughout this process, the real user ID remains `jdoe' and the saved
+-user ID remains `games', so the program can always set its effective
+-user ID to either one.
+-
+-   On other systems that don't support the saved user ID feature, you
+-can turn setuid access on and off by using `setreuid' to swap the real
+-and effective user IDs of the process, as follows:
+-
+-     setreuid (geteuid (), getuid ());
+-
+-This special case is always allowed--it cannot fail.
+-
+-   Why does this have the effect of toggling the setuid access?
+-Suppose a game program has just started, and its real user ID is `jdoe'
+-while its effective user ID is `games'.  In this state, the game can
+-write the scores file.  If it swaps the two uids, the real becomes
+-`games' and the effective becomes `jdoe'; now the program has only
+-`jdoe' access.  Another swap brings `games' back to the effective user
+-ID and restores access to the scores file.
+-
+-   In order to handle both kinds of systems, test for the saved user ID
+-feature with a preprocessor conditional, like this:
+-
+-     #ifdef _POSIX_SAVED_IDS
+-       setuid (user_user_id);
+-     #else
+-       setreuid (geteuid (), getuid ());
+-     #endif
+-
+-
+-File: libc.info,  Node: Setuid Program Example,  Next: Tips for Setuid,  
Prev: Enable/Disable Setuid,  Up: Users and Groups
+-
+-Setuid Program Example
+-======================
+-
+-   Here's an example showing how to set up a program that changes its
+-effective user ID.
+-
+-   This is part of a game program called `caber-toss' that manipulates
+-a file `scores' that should be writable only by the game program
+-itself.  The program assumes that its executable file will be installed
+-with the set-user-ID bit set and owned by the same user as the `scores'
+-file.  Typically, a system administrator will set up an account like
+-`games' for this purpose.
+-
+-   The executable file is given mode `4755', so that doing an `ls -l'
+-on it produces output like:
+-
+-     -rwsr-xr-x   1 games    184422 Jul 30 15:17 caber-toss
+-
+-The set-user-ID bit shows up in the file modes as the `s'.
+-
+-   The scores file is given mode `644', and doing an `ls -l' on it
+-shows:
+-
+-     -rw-r--r--  1 games           0 Jul 31 15:33 scores
+-
+-   Here are the parts of the program that show how to set up the changed
+-user ID.  This program is conditionalized so that it makes use of the
+-saved IDs feature if it is supported, and otherwise uses `setreuid' to
+-swap the effective and real user IDs.
+-
+-     #include <stdio.h>
+-     #include <sys/types.h>
+-     #include <unistd.h>
+-     #include <stdlib.h>
+-     
+-     
+-     /* Save the effective and real UIDs. */
+-     
+-     static uid_t euid, ruid;
+-     
+-     
+-     /* Restore the effective UID to its original value. */
+-     
+-     void
+-     do_setuid (void)
+-     {
+-       int status;
+-     
+-     #ifdef _POSIX_SAVED_IDS
+-       status = setuid (euid);
+-     #else
+-       status = setreuid (ruid, euid);
+-     #endif
+-       if (status < 0) {
+-         fprintf (stderr, "Couldn't set uid.\n");
+-         exit (status);
+-         }
+-     }
+-     /* Set the effective UID to the real UID. */
+-     
+-     void
+-     undo_setuid (void)
+-     {
+-       int status;
+-     
+-     #ifdef _POSIX_SAVED_IDS
+-       status = setuid (ruid);
+-     #else
+-       status = setreuid (euid, ruid);
+-     #endif
+-       if (status < 0) {
+-         fprintf (stderr, "Couldn't set uid.\n");
+-         exit (status);
+-         }
+-     }
+-     
+-     /* Main program. */
+-     
+-     int
+-     main (void)
+-     {
+-       /* Save the real and effective user IDs.  */
+-       ruid = getuid ();
+-       euid = geteuid ();
+-       undo_setuid ();
+-     
+-       /* Do the game and record the score.  */
+-       ...
+-     }
+-
+-   Notice how the first thing the `main' function does is to set the
+-effective user ID back to the real user ID.  This is so that any other
+-file accesses that are performed while the user is playing the game use
+-the real user ID for determining permissions.  Only when the program
+-needs to open the scores file does it switch back to the original
+-effective user ID, like this:
+-
+-     /* Record the score. */
+-     
+-     int
+-     record_score (int score)
+-     {
+-       FILE *stream;
+-       char *myname;
+-     
+-       /* Open the scores file. */
+-       do_setuid ();
+-       stream = fopen (SCORES_FILE, "a");
+-       undo_setuid ();
+-     /* Write the score to the file. */
+-       if (stream)
+-         {
+-           myname = cuserid (NULL);
+-           if (score < 0)
+-             fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
+-           else
+-             fprintf (stream, "%10s: %d feet.\n", myname, score);
+-           fclose (stream);
+-           return 0;
+-         }
+-       else
+-         return -1;
+-     }
+-
+-
+-File: libc.info,  Node: Tips for Setuid,  Next: Who Logged In,  Prev: Setuid 
Program Example,  Up: Users and Groups
+-
+-Tips for Writing Setuid Programs
+-================================
+-
+-   It is easy for setuid programs to give the user access that isn't
+-intended--in fact, if you want to avoid this, you need to be careful.
+-Here are some guidelines for preventing unintended access and
+-minimizing its consequences when it does occur:
+-
+-   * Don't have `setuid' programs with privileged user IDs such as
+-     `root' unless it is absolutely necessary.  If the resource is
+-     specific to your particular program, it's better to define a new,
+-     nonprivileged user ID or group ID just to manage that resource.
+-
+-   * Be cautious about using the `system' and `exec' functions in
+-     combination with changing the effective user ID.  Don't let users
+-     of your program execute arbitrary programs under a changed user ID.
+-     Executing a shell is especially bad news.  Less obviously, the
+-     `execlp' and `execvp' functions are a potential risk (since the
+-     program they execute depends on the user's `PATH' environment
+-     variable).
+-
+-     If you must `exec' another program under a changed ID, specify an
+-     absolute file name (*note File Name Resolution::.) for the
+-     executable, and make sure that the protections on that executable
+-     and *all* containing directories are such that ordinary users
+-     cannot replace it with some other program.
+-
+-   * Only use the user ID controlling the resource in the part of the
+-     program that actually uses that resource.  When you're finished
+-     with it, restore the effective user ID back to the actual user's
+-     user ID.  *Note Enable/Disable Setuid::.
+-
+-   * If the `setuid' part of your program needs to access other files
+-     besides the controlled resource, it should verify that the real
+-     user would ordinarily have permission to access those files.  You
+-     can use the `access' function (*note Access Permission::.) to
+-     check this; it uses the real user and group IDs, rather than the
+-     effective IDs.
+-
+-
+-File: libc.info,  Node: Who Logged In,  Next: User Database,  Prev: Tips for 
Setuid,  Up: Users and Groups
+-
+-Identifying Who Logged In
+-=========================
+-
+-   You can use the functions listed in this section to determine the
+-login name of the user who is running a process, and the name of the
+-user who logged in the current session.  See also the function `getuid'
+-and friends (*note Reading Persona::.).
+-
+-   The `getlogin' function is declared in `unistd.h', while `cuserid'
+-and `L_cuserid' are declared in `stdio.h'.
+-
+- - Function: char * getlogin (void)
+-     The `getlogin' function returns a pointer to a string containing
+-     the name of the user logged in on the controlling terminal of the
+-     process, or a null pointer if this information cannot be
+-     determined.  The string is statically allocated and might be
+-     overwritten on subsequent calls to this function or to `cuserid'.
+-
+- - Function: char * cuserid (char *STRING)
+-     The `cuserid' function returns a pointer to a string containing a
+-     user name associated with the effective ID of the process.  If
+-     STRING is not a null pointer, it should be an array that can hold
+-     at least `L_cuserid' characters; the string is returned in this
+-     array.  Otherwise, a pointer to a string in a static area is
+-     returned.  This string is statically allocated and might be
+-     overwritten on subsequent calls to this function or to `getlogin'.
+-
+-     The use of this function is deprecated since it is marked to be
+-     withdrawn in XPG4.2 and it is already removed in POSIX.1.
+-
+- - Macro: int L_cuserid
+-     An integer constant that indicates how long an array you might
+-     need to store a user name.
+-
+-   These functions let your program identify positively the user who is
+-running or the user who logged in this session.  (These can differ when
+-setuid programs are involved; *Note Process Persona::.)  The user cannot
+-do anything to fool these functions.
+-
+-   For most purposes, it is more useful to use the environment variable
+-`LOGNAME' to find out who the user is.  This is more flexible precisely
+-because the user can set `LOGNAME' arbitrarily.  *Note Standard
+-Environment::.
+-
+-
+-File: libc.info,  Node: User Database,  Next: Group Database,  Prev: Who 
Logged In,  Up: Users and Groups
+-
+-User Database
+-=============
+-
+-   This section describes all about how to search and scan the database
+-of registered users.  The database itself is kept in the file
+-`/etc/passwd' on most systems, but on some systems a special network
+-server gives access to it.
+-
+-* Menu:
+-
+-* User Data Structure::         What each user record contains.
+-* Lookup User::                 How to look for a particular user.
+-* Scanning All Users::          Scanning the list of all users, one by one.
+-* Writing a User Entry::        How a program can rewrite a user's record.
+-
+-
+-File: libc.info,  Node: User Data Structure,  Next: Lookup User,  Prev: User 
Database,  Up: User Database
+-
+-The Data Structure that Describes a User
+-----------------------------------------
+-
+-   The functions and data structures for accessing the system user
+-database are declared in the header file `pwd.h'.
+-
+- - Data Type: struct passwd
+-     The `passwd' data structure is used to hold information about
+-     entries in the system user data base.  It has at least the
+-     following members:
+-
+-    `char *pw_name'
+-          The user's login name.
+-
+-    `char *pw_passwd.'
+-          The encrypted password string.
+-
+-    `uid_t pw_uid'
+-          The user ID number.
+-
+-    `gid_t pw_gid'
+-          The user's default group ID number.
+-
+-    `char *pw_gecos'
+-          A string typically containing the user's real name, and
+-          possibly other information such as a phone number.
+-
+-    `char *pw_dir'
+-          The user's home directory, or initial working directory.
+-          This might be a null pointer, in which case the
+-          interpretation is system-dependent.
+-
+-    `char *pw_shell'
+-          The user's default shell, or the initial program run when the
+-          user logs in.  This might be a null pointer, indicating that
+-          the system default should be used.
+-
+-
+-File: libc.info,  Node: Lookup User,  Next: Scanning All Users,  Prev: User 
Data Structure,  Up: User Database
+-
+-Looking Up One User
+--------------------
+-
+-   You can search the system user database for information about a
+-specific user using `getpwuid' or `getpwnam'.  These functions are
+-declared in `pwd.h'.
+-
+- - Function: struct passwd * getpwuid (uid_t UID)
+-     This function returns a pointer to a statically-allocated structure
+-     containing information about the user whose user ID is UID.  This
+-     structure may be overwritten on subsequent calls to `getpwuid'.
+-
+-     A null pointer value indicates there is no user in the data base
+-     with user ID UID.
+-
+- - Function: int getpwuid_r (uid_t UID, struct passwd *RESULT_BUF, char
+-          *BUFFER, size_t BUFLEN, struct passwd **RESULT)
+-     This function is similar to `getpwuid' in that is returns
+-     information about the user whose user ID is UID.  But the result
+-     is not placed in a static buffer.  Instead the user supplied
+-     structure pointed to by RESULT_BUF is filled with the information.
+-     The first BUFLEN bytes of the additional buffer pointed to by
+-     BUFFER are used to contain additional information, normally
+-     strings which are pointed to by the elements of the result
+-     structure.
+-
+-     If the return value is `0' the pointer returned in RESULT points
+-     to the record which contains the wanted data (i.e., RESULT
+-     contains the value RESULT_BUF).  In case the return value is non
+-     null there is no user in the data base with user ID UID or the
+-     buffer BUFFER is too small to contain all the needed information.
+-     In the later case the global ERRNO variable is set to `ERANGE'.
+-
+- - Function: struct passwd * getpwnam (const char *NAME)
+-     This function returns a pointer to a statically-allocated structure
+-     containing information about the user whose user name is NAME.
+-     This structure may be overwritten on subsequent calls to
+-     `getpwnam'.
+-
+-     A null pointer value indicates there is no user named NAME.
+-
+- - Function: int getpwnam_r (const char *NAME, struct passwd
+-          *RESULT_BUF, char *BUFFER, size_t BUFLEN, struct passwd
+-          **RESULT)
+-     This function is similar to `getpwnam' in that is returns
+-     information about the user whose user name is NAME.  But the result
+-     is not placed in a static buffer.  Instead the user supplied
+-     structure pointed to by RESULT_BUF is filled with the information.
+-     The first BUFLEN bytes of the additional buffer pointed to by
+-     BUFFER are used to contain additional information, normally
+-     strings which are pointed to by the elements of the result
+-     structure.
+-
+-     If the return value is `0' the pointer returned in RESULT points
+-     to the record which contains the wanted data (i.e., RESULT
+-     contains the value RESULT_BUF).  In case the return value is non
+-     null there is no user in the data base with user name NAME or the
+-     buffer BUFFER is too small to contain all the needed information.
+-     In the later case the global ERRNO variable is set to `ERANGE'.
+-
+-
+-File: libc.info,  Node: Scanning All Users,  Next: Writing a User Entry,  
Prev: Lookup User,  Up: User Database
+-
+-Scanning the List of All Users
+-------------------------------
+-
+-   This section explains how a program can read the list of all users in
+-the system, one user at a time.  The functions described here are
+-declared in `pwd.h'.
+-
+-   You can use the `fgetpwent' function to read user entries from a
+-particular file.
+-
+- - Function: struct passwd * fgetpwent (FILE *STREAM)
+-     This function reads the next user entry from STREAM and returns a
+-     pointer to the entry.  The structure is statically allocated and is
+-     rewritten on subsequent calls to `fgetpwent'.  You must copy the
+-     contents of the structure if you wish to save the information.
+-
+-     This stream must correspond to a file in the same format as the
+-     standard password database file.  This function comes from System
+-     V.
+-
+- - Function: int fgetpwent_r (FILE *STREAM, struct passwd *RESULT_BUF,
+-          char *BUFFER, size_t BUFLEN, struct passwd **RESULT)
+-     This function is similar to `fgetpwent' in that it reads the next
+-     user entry from STREAM.  But the result is returned in the
+-     structure pointed to by RESULT_BUF.  The first BUFLEN bytes of the
+-     additional buffer pointed to by BUFFER are used to contain
+-     additional information, normally strings which are pointed to by
+-     the elements of the result structure.
+-
+-     This stream must correspond to a file in the same format as the
+-     standard password database file.
+-
+-     If the function returns null RESULT points to the structure with
+-     the wanted data (normally this is in RESULT_BUF).  If errors
+-     occurred the return value is non-null and RESULT contains a null
+-     pointer.
+-
+-   The way to scan all the entries in the user database is with
+-`setpwent', `getpwent', and `endpwent'.
+-
+- - Function: void setpwent (void)
+-     This function initializes a stream which `getpwent' and
+-     `getpwent_r' use to read the user database.
+-
+- - Function: struct passwd * getpwent (void)
+-     The `getpwent' function reads the next entry from the stream
+-     initialized by `setpwent'.  It returns a pointer to the entry.  The
+-     structure is statically allocated and is rewritten on subsequent
+-     calls to `getpwent'.  You must copy the contents of the structure
+-     if you wish to save the information.
+-
+-     A null pointer is returned in case no further entry is available.
+-
+- - Function: int getpwent_r (struct passwd *RESULT_BUF, char *BUFFER,
+-          int BUFLEN, struct passwd **RESULT)
+-     This function is similar to `getpwent' in that it returns the next
+-     entry from the stream initialized by `setpwent'.  But in contrast
+-     to the `getpwent' function this function is reentrant since the
+-     result is placed in the user supplied structure pointed to by
+-     RESULT_BUF.  Additional data, normally the strings pointed to by
+-     the elements of the result structure, are placed in the additional
+-     buffer or length BUFLEN starting at BUFFER.
+-
+-     If the function returns zero RESULT points to the structure with
+-     the wanted data (normally this is in RESULT_BUF).  If errors
+-     occurred the return value is non-zero and RESULT contains a null
+-     pointer.
+-
+- - Function: void endpwent (void)
+-     This function closes the internal stream used by `getpwent' or
+-     `getpwent_r'.
+-
+-
+-File: libc.info,  Node: Writing a User Entry,  Prev: Scanning All Users,  Up: 
User Database
+-
+-Writing a User Entry
+---------------------
+-
+- - Function: int putpwent (const struct passwd *P, FILE *STREAM)
+-     This function writes the user entry `*P' to the stream STREAM, in
+-     the format used for the standard user database file.  The return
+-     value is zero on success and nonzero on failure.
+-
+-     This function exists for compatibility with SVID.  We recommend
+-     that you avoid using it, because it makes sense only on the
+-     assumption that the `struct passwd' structure has no members
+-     except the standard ones; on a system which merges the traditional
+-     Unix data base with other extended information about users, adding
+-     an entry using this function would inevitably leave out much of
+-     the important information.
+-
+-     The function `putpwent' is declared in `pwd.h'.
+-
+-
+-File: libc.info,  Node: Group Database,  Next: Netgroup Database,  Prev: User 
Database,  Up: Users and Groups
+-
+-Group Database
+-==============
+-
+-   This section describes all about how to search and scan the database
+-of registered groups.  The database itself is kept in the file
+-`/etc/group' on most systems, but on some systems a special network
+-service provides access to it.
+-
+-* Menu:
+-
+-* Group Data Structure::        What each group record contains.
+-* Lookup Group::                How to look for a particular group.
+-* Scanning All Groups::         Scanning the list of all groups.
+-
+-
+-File: libc.info,  Node: Group Data Structure,  Next: Lookup Group,  Prev: 
Group Database,  Up: Group Database
+-
+-The Data Structure for a Group
+-------------------------------
+-
+-   The functions and data structures for accessing the system group
+-database are declared in the header file `grp.h'.
+-
+- - Data Type: struct group
+-     The `group' structure is used to hold information about an entry in
+-     the system group database.  It has at least the following members:
+-
+-    `char *gr_name'
+-          The name of the group.
+-
+-    `gid_t gr_gid'
+-          The group ID of the group.
+-
+-    `char **gr_mem'
+-          A vector of pointers to the names of users in the group.
+-          Each user name is a null-terminated string, and the vector
+-          itself is terminated by a null pointer.
+-
+-
+-File: libc.info,  Node: Lookup Group,  Next: Scanning All Groups,  Prev: 
Group Data Structure,  Up: Group Database
+-
+-Looking Up One Group
+---------------------
+-
+-   You can search the group database for information about a specific
+-group using `getgrgid' or `getgrnam'.  These functions are declared in
+-`grp.h'.
+-
+- - Function: struct group * getgrgid (gid_t GID)
+-     This function returns a pointer to a statically-allocated structure
+-     containing information about the group whose group ID is GID.
+-     This structure may be overwritten by subsequent calls to
+-     `getgrgid'.
+-
+-     A null pointer indicates there is no group with ID GID.
+-
+- - Function: int getgrgid_r (gid_t GID, struct group *RESULT_BUF, char
+-          *BUFFER, size_t BUFLEN, struct group **RESULT)
+-     This function is similar to `getgrgid' in that is returns
+-     information about the group whose group ID is GID.  But the result
+-     is not placed in a static buffer.  Instead the user supplied
+-     structure pointed to by RESULT_BUF is filled with the information.
+-     The first BUFLEN bytes of the additional buffer pointed to by
+-     BUFFER are used to contain additional information, normally
+-     strings which are pointed to by the elements of the result
+-     structure.
+-
+-     If the return value is `0' the pointer returned in RESULT points
+-     to the record which contains the wanted data (i.e., RESULT
+-     contains the value RESULT_BUF).  If the return value is non-zero
+-     there is no group in the data base with group ID GID or the buffer
+-     BUFFER is too small to contain all the needed information.  In the
+-     later case the global ERRNO variable is set to `ERANGE'.
+-
+- - Function: struct group * getgrnam (const char *NAME)
+-     This function returns a pointer to a statically-allocated structure
+-     containing information about the group whose group name is NAME.
+-     This structure may be overwritten by subsequent calls to
+-     `getgrnam'.
+-
+-     A null pointer indicates there is no group named NAME.
+-
+- - Function: int getgrnam_r (const char *NAME, struct group
+-          *RESULT_BUF, char *BUFFER, size_t BUFLEN, struct group
+-          **RESULT)
+-     This function is similar to `getgrnam' in that is returns
+-     information about the group whose group name is NAME.  But the
+-     result is not placed in a static buffer.  Instead the user
+-     supplied structure pointed to by RESULT_BUF is filled with the
+-     information.  The first BUFLEN bytes of the additional buffer
+-     pointed to by BUFFER are used to contain additional information,
+-     normally strings which are pointed to by the elements of the
+-     result structure.
+-
+-     If the return value is `0' the pointer returned in RESULT points
+-     to the record which contains the wanted data (i.e., RESULT
+-     contains the value RESULT_BUF).  If the return value is non-zero
+-     there is no group in the data base with group name NAME or the
+-     buffer BUFFER is too small to contain all the needed information.
+-     In the later case the global ERRNO variable is set to `ERANGE'.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-26 
glibc-2.0.1/manual/libc.info-26
+--- ../glibc-2.0.1/manual/libc.info-26 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-26    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1240 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info,  Node: Scanning All Groups,  Prev: Lookup Group,  Up: Group 
Database
+-
+-Scanning the List of All Groups
+--------------------------------
+-
+-   This section explains how a program can read the list of all groups
+-in the system, one group at a time.  The functions described here are
+-declared in `grp.h'.
+-
+-   You can use the `fgetgrent' function to read group entries from a
+-particular file.
+-
+- - Function: struct group * fgetgrent (FILE *STREAM)
+-     The `fgetgrent' function reads the next entry from STREAM.  It
+-     returns a pointer to the entry.  The structure is statically
+-     allocated and is rewritten on subsequent calls to `fgetgrent'.  You
+-     must copy the contents of the structure if you wish to save the
+-     information.
+-
+-     The stream must correspond to a file in the same format as the
+-     standard group database file.
+-
+- - Function: int fgetgrent_r (FILE *STREAM, struct group *RESULT_BUF,
+-          char *BUFFER, size_t BUFLEN, struct group **RESULT)
+-     This function is similar to `fgetgrent' in that it reads the next
+-     user entry from STREAM.  But the result is returned in the
+-     structure pointed to by RESULT_BUF.  The first BUFLEN bytes of the
+-     additional buffer pointed to by BUFFER are used to contain
+-     additional information, normally strings which are pointed to by
+-     the elements of the result structure.
+-
+-     This stream must correspond to a file in the same format as the
+-     standard group database file.
+-
+-     If the function returns zero RESULT points to the structure with
+-     the wanted data (normally this is in RESULT_BUF).  If errors
+-     occurred the return value is non-zero and RESULT contains a null
+-     pointer.
+-
+-   The way to scan all the entries in the group database is with
+-`setgrent', `getgrent', and `endgrent'.
+-
+- - Function: void setgrent (void)
+-     This function initializes a stream for reading from the group data
+-     base.  You use this stream by calling `getgrent' or `getgrent_r'.
+-
+- - Function: struct group * getgrent (void)
+-     The `getgrent' function reads the next entry from the stream
+-     initialized by `setgrent'.  It returns a pointer to the entry.  The
+-     structure is statically allocated and is rewritten on subsequent
+-     calls to `getgrent'.  You must copy the contents of the structure
+-     if you wish to save the information.
+-
+- - Function: int getgrent_r (struct group *RESULT_BUF, char *BUFFER,
+-          size_t BUFLEN, struct group **RESULT)
+-     This function is similar to `getgrent' in that it returns the next
+-     entry from the stream initialized by `setgrent'.  But in contrast
+-     to the `getgrent' function this function is reentrant since the
+-     result is placed in the user supplied structure pointed to by
+-     RESULT_BUF.  Additional data, normally the strings pointed to by
+-     the elements of the result structure, are placed in the additional
+-     buffer or length BUFLEN starting at BUFFER.
+-
+-     If the function returns zero RESULT points to the structure with
+-     the wanted data (normally this is in RESULT_BUF).  If errors
+-     occurred the return value is non-zero and RESULT contains a null
+-     pointer.
+-
+- - Function: void endgrent (void)
+-     This function closes the internal stream used by `getgrent' or
+-     `getgrent_r'.
+-
+-
+-File: libc.info,  Node: Netgroup Database,  Next: Database Example,  Prev: 
Group Database,  Up: Users and Groups
+-
+-Netgroup Database
+-=================
+-
+-* Menu:
+-
+-* Netgroup Data::                  Data in the Netgroup database and where
+-                                   it comes from.
+-* Lookup Netgroup::                How to look for a particular netgroup.
+-* Netgroup Membership::            How to test for netgroup membership.
+-
+-
+-File: libc.info,  Node: Netgroup Data,  Next: Lookup Netgroup,  Prev: 
Netgroup Database,  Up: Netgroup Database
+-
+-Netgroup Data
+--------------
+-
+-   Sometimes it is useful group users according to other criterias like
+-the ones used in the *Note Group Database::.  E.g., it is useful to
+-associate a certain group of users with a certain machine.  On the
+-other hand grouping of host names is not supported so far.
+-
+-   In Sun Microsystems SunOS appeared a new kind of database, the
+-netgroup database.  It allows to group hosts, users, and domain freely,
+-giving them individual names.  More concrete: a netgroup is a list of
+-triples consisting of a host name, a user name, and a domain name,
+-where any of the entries can be a wildcard entry, matching all inputs.
+-A last possibility is that names of other netgroups can also be given
+-in the list specifying a netgroup.  So one can construct arbitrary
+-hierarchies without loops.
+-
+-   Sun's implementation allows netgroups only for the `nis' or
+-`nisplus' service *note Services in the NSS configuration::..  The
+-implementation in the GNU C library has no such restriction.  An entry
+-in either of the input services must have the following form:
+-
+-     GROUPNAME ( GROUPNAME | `('HOSTNAME`,'USERNAME`,'`domainname'`)' )+
+-
+-   Any of the fields in the triple can be empty which means anything
+-matches.  While describing the functions we will see that the opposite
+-case is useful as well.  I.e., there may be entries which will not
+-match any input.  For entries like a name consisting of the single
+-character `-' shall be used.
+-
+-
+-File: libc.info,  Node: Lookup Netgroup,  Next: Netgroup Membership,  Prev: 
Netgroup Data,  Up: Netgroup Database
+-
+-Looking up one Netgroup
+------------------------
+-
+-   The lookup functions for netgroups are a bit different to all other
+-system database handling functions.  Since a single netgroup can contain
+-many entries a two-step process is needed.  First a single netgroup is
+-selected and then one can iterate over all entries in this netgroup.
+-These functions are declared in `netdb.h'.
+-
+- - Function: int setnetgrent (const char *NETGROUP)
+-     A call to this function initializes the internal state of the
+-     library to allow following calls of the `getnetgrent' iterate over
+-     all entries in the netgroup with name NETGROUP.
+-
+-     When the call is successful (i.e., when a netgroup with this name
+-     exist) the return value is `1'.  When the return value is `0' no
+-     netgroup of this name is known or some other error occurred.
+-
+-   It is important to remember that there is only one single state for
+-iterating the netgroups.  Even if the programmer uses the
+-`getnetgrent_r' function the result is not really reentrant since
+-always only one single netgroup at a time can be processed.  If the
+-program needs to process more than one netgroup simultaneously she must
+-protect this by using external locking.  This problem was introduced in
+-the original netgroups implementation in SunOS and since we must stay
+-compatible it is not possible to change this.
+-
+-   Some other functions also use the netgroups state.  Currently these
+-are the `innetgr' function and parts of the implementation of the
+-`compat' service part of the NSS implementation.
+-
+- - Function: int getnetgrent (char **HOSTP, char **USERP, char
+-          **DOMAINP)
+-     This function returns the next unprocessed entry of the currently
+-     selected netgroup.  The string pointers, which addresses are
+-     passed in the arguments HOSTP, USERP, and DOMAINP, will contain
+-     after a successful call pointers to appropriate strings.  If the
+-     string in the next entry is empty the pointer has the value `NULL'.
+-     The returned string pointers are only valid unless no of the
+-     netgroup related functions are called.
+-
+-     The return value is `1' if the next entry was successfully read.  A
+-     value of `0' means no further entries exist or internal errors
+-     occurred.
+-
+- - Function: int getnetgrent_r (char **HOSTP, char **USERP, char
+-          **DOMAINP, char *BUFFER, int BUFLEN)
+-     This function is similar to `getnetgrent' with only one exception:
+-     the strings the three string pointers HOSTP, USERP, and DOMAINP
+-     point to, are placed in the buffer of BUFLEN bytes starting at
+-     BUFFER.  This means the returned values are valid even after other
+-     netgroup related functions are called.
+-
+-     The return value is `1' if the next entry was successfully read and
+-     the buffer contains enough room to place the strings in it.  `0' is
+-     returned in case no more entries are found, the buffer is too
+-     small, or internal errors occurred.
+-
+-     This function is a GNU extension.  The original implementation in
+-     the SunOS libc does not provide this function.
+-
+- - Function: void endnetgrent (void)
+-     This function free all buffers which were allocated to process the
+-     last selected netgroup.  As a result all string pointers returned
+-     by calls to `getnetgrent' are invalid afterwards.
+-
+-
+-File: libc.info,  Node: Netgroup Membership,  Prev: Lookup Netgroup,  Up: 
Netgroup Database
+-
+-Testing for Netgroup Membership
+--------------------------------
+-
+-   It is often not necessary to scan the whole netgroup since often the
+-only interesting question is whether a given entry is part of the
+-selected netgroup.
+-
+- - Function: int innetgr (const char *NETGROUP, const char *HOST, const
+-          char *USER, const char *DOMAIN)
+-     This function tests whether the triple specified by the parameters
+-     HOSTP, USERP, and DOMAINP is part of the netgroup NETGROUP.  Using
+-     this function has the advantage that
+-
+-       1. no other netgroup function can use the global netgroup state
+-          since internal locking is used and
+-
+-       2. the function is implemented more efficiently than successive
+-          calls to the other `set'/`get'/`endnetgrent' functions.
+-
+-     Any of the pointers HOSTP, USERP, and DOMAINP can be `NULL' which
+-     means any value is excepted in this position.  This is also true
+-     for the name `-' which should not match any other string otherwise.
+-
+-     The return value is `1' if an entry matching the given triple is
+-     found in the netgroup.  The return value is `0' if the netgroup
+-     itself is not found, the netgroup does not contain the triple or
+-     internal errors occurred.
+-
+-
+-File: libc.info,  Node: Database Example,  Prev: Netgroup Database,  Up: 
Users and Groups
+-
+-User and Group Database Example
+-===============================
+-
+-   Here is an example program showing the use of the system database
+-inquiry functions.  The program prints some information about the user
+-running the program.
+-
+-     #include <grp.h>
+-     #include <pwd.h>
+-     #include <sys/types.h>
+-     #include <unistd.h>
+-     #include <stdlib.h>
+-     
+-     int
+-     main (void)
+-     {
+-       uid_t me;
+-       struct passwd *my_passwd;
+-       struct group *my_group;
+-       char **members;
+-     
+-       /* Get information about the user ID. */
+-       me = getuid ();
+-       my_passwd = getpwuid (me);
+-       if (!my_passwd)
+-         {
+-           printf ("Couldn't find out about user %d.\n", (int) me);
+-           exit (EXIT_FAILURE);
+-         }
+-     
+-       /* Print the information. */
+-       printf ("I am %s.\n", my_passwd->pw_gecos);
+-       printf ("My login name is %s.\n", my_passwd->pw_name);
+-       printf ("My uid is %d.\n", (int) (my_passwd->pw_uid));
+-       printf ("My home directory is %s.\n", my_passwd->pw_dir);
+-       printf ("My default shell is %s.\n", my_passwd->pw_shell);
+-     
+-       /* Get information about the default group ID. */
+-       my_group = getgrgid (my_passwd->pw_gid);
+-       if (!my_group)
+-         {
+-           printf ("Couldn't find out about group %d.\n",
+-                   (int) my_passwd->pw_gid);
+-           exit (EXIT_FAILURE);
+-         }
+-     
+-       /* Print the information. */
+-       printf ("My default group is %s (%d).\n",
+-               my_group->gr_name, (int) (my_passwd->pw_gid));
+-       printf ("The members of this group are:\n");
+-       members = my_group->gr_mem;
+-       while (*members)
+-         {
+-           printf ("  %s\n", *(members));
+-           members++;
+-         }
+-     
+-       return EXIT_SUCCESS;
+-     }
+-
+-   Here is some output from this program:
+-
+-     I am Throckmorton Snurd.
+-     My login name is snurd.
+-     My uid is 31093.
+-     My home directory is /home/fsg/snurd.
+-     My default shell is /bin/sh.
+-     My default group is guest (12).
+-     The members of this group are:
+-       friedman
+-       tami
+-
+-
+-File: libc.info,  Node: System Information,  Next: System Configuration,  
Prev: Users and Groups,  Up: Top
+-
+-System Information
+-******************
+-
+-   This chapter describes functions that return information about the
+-particular machine that is in use--the type of hardware, the type of
+-software, and the individual machine's name.
+-
+-* Menu:
+-
+-* Host Identification::         Determining the name of the machine.
+-* Hardware/Software Type ID::   Determining the hardware type of the
+-                                 machine and what operating system it is
+-                                 running.
+-
+-
+-File: libc.info,  Node: Host Identification,  Next: Hardware/Software Type 
ID,  Up: System Information
+-
+-Host Identification
+-===================
+-
+-   This section explains how to identify the particular machine that
+-your program is running on.  The identification of a machine consists
+-of its Internet host name and Internet address; see *Note Internet
+-Namespace::.  The host name should always be a fully qualified domain
+-name, like `crispy-wheats-n-chicken.ai.mit.edu', not a simple name like
+-just `crispy-wheats-n-chicken'.
+-
+-   Prototypes for these functions appear in `unistd.h'.  The shell
+-commands `hostname' and `hostid' work by calling them.
+-
+- - Function: int gethostname (char *NAME, size_t SIZE)
+-     This function returns the name of the host machine in the array
+-     NAME.  The SIZE argument specifies the size of this array, in
+-     bytes.
+-
+-     The return value is `0' on success and `-1' on failure.  In the
+-     GNU C library, `gethostname' fails if SIZE is not large enough;
+-     then you can try again with a larger array.  The following `errno'
+-     error condition is defined for this function:
+-
+-    `ENAMETOOLONG'
+-          The SIZE argument is less than the size of the host name plus
+-          one.
+-
+-     On some systems, there is a symbol for the maximum possible host
+-     name length: `MAXHOSTNAMELEN'.  It is defined in `sys/param.h'.
+-     But you can't count on this to exist, so it is cleaner to handle
+-     failure and try again.
+-
+-     `gethostname' stores the beginning of the host name in NAME even
+-     if the host name won't entirely fit.  For some purposes, a
+-     truncated host name is good enough.  If it is, you can ignore the
+-     error code.
+-
+- - Function: int sethostname (const char *NAME, size_t LENGTH)
+-     The `sethostname' function sets the name of the host machine to
+-     NAME, a string with length LENGTH.  Only privileged processes are
+-     allowed to do this.  Usually it happens just once, at system boot
+-     time.
+-
+-     The return value is `0' on success and `-1' on failure.  The
+-     following `errno' error condition is defined for this function:
+-
+-    `EPERM'
+-          This process cannot set the host name because it is not
+-          privileged.
+-
+- - Function: long int gethostid (void)
+-     This function returns the "host ID" of the machine the program is
+-     running on.  By convention, this is usually the primary Internet
+-     address of that machine, converted to a `long int'.  However, some
+-     systems it is a meaningless but unique number which is hard-coded
+-     for each machine.
+-
+- - Function: int sethostid (long int ID)
+-     The `sethostid' function sets the "host ID" of the host machine to
+-     ID.  Only privileged processes are allowed to do this.  Usually it
+-     happens just once, at system boot time.
+-
+-     The return value is `0' on success and `-1' on failure.  The
+-     following `errno' error condition is defined for this function:
+-
+-    `EPERM'
+-          This process cannot set the host name because it is not
+-          privileged.
+-
+-    `ENOSYS'
+-          The operating system does not support setting the host ID.
+-          On some systems, the host ID is a meaningless but unique
+-          number hard-coded for each machine.
+-
+-
+-File: libc.info,  Node: Hardware/Software Type ID,  Prev: Host 
Identification,  Up: System Information
+-
+-Hardware/Software Type Identification
+-=====================================
+-
+-   You can use the `uname' function to find out some information about
+-the type of computer your program is running on.  This function and the
+-associated data type are declared in the header file `sys/utsname.h'.
+-
+- - Data Type: struct utsname
+-     The `utsname' structure is used to hold information returned by
+-     the `uname' function.  It has the following members:
+-
+-    `char sysname[]'
+-          This is the name of the operating system in use.
+-
+-    `char nodename[]'
+-          This is the network name of this particular computer.  In the
+-          GNU library, the value is the same as that returned by
+-          `gethostname'; see *Note Host Identification::.
+-
+-    `char release[]'
+-          This is the current release level of the operating system
+-          implementation.
+-
+-    `char version[]'
+-          This is the current version level within the release of the
+-          operating system.
+-
+-    `char machine[]'
+-          This is a description of the type of hardware that is in use.
+-
+-          Some systems provide a mechanism to interrogate the kernel
+-          directly for this information.  On systems without such a
+-          mechanism, the GNU C library fills in this field based on the
+-          configuration name that was specified when building and
+-          installing the library.
+-
+-          GNU uses a three-part name to describe a system
+-          configuration; the three parts are CPU, MANUFACTURER and
+-          SYSTEM-TYPE, and they are separated with dashes.  Any
+-          possible combination of three names is potentially
+-          meaningful, but most such combinations are meaningless in
+-          practice and even the meaningful ones are not necessarily
+-          supported by any particular GNU program.
+-
+-          Since the value in `machine' is supposed to describe just the
+-          hardware, it consists of the first two parts of the
+-          configuration name: `CPU-MANUFACTURER'.  For example, it
+-          might be one of these:
+-
+-               `"sparc-sun"', `"i386-ANYTHING"', `"m68k-hp"',
+-               `"m68k-sony"', `"m68k-sun"', `"mips-dec"'
+-
+- - Function: int uname (struct utsname *INFO)
+-     The `uname' function fills in the structure pointed to by INFO
+-     with information about the operating system and host machine.  A
+-     non-negative value indicates that the data was successfully stored.
+-
+-     `-1' as the value indicates an error.  The only error possible is
+-     `EFAULT', which we normally don't mention as it is always a
+-     possibility.
+-
+-
+-File: libc.info,  Node: System Configuration,  Next: Language Features,  
Prev: System Information,  Up: Top
+-
+-System Configuration Parameters
+-*******************************
+-
+-   The functions and macros listed in this chapter give information
+-about configuration parameters of the operating system--for example,
+-capacity limits, presence of optional POSIX features, and the default
+-path for executable files (*note String Parameters::.).
+-
+-* Menu:
+-
+-* General Limits::           Constants and functions that describe
+-                              various process-related limits that have
+-                              one uniform value for any given machine.
+-* System Options::           Optional POSIX features.
+-* Version Supported::        Version numbers of POSIX.1 and POSIX.2.
+-* Sysconf::                  Getting specific configuration values
+-                                of general limits and system options.
+-* Minimums::                 Minimum values for general limits.
+-
+-* Limits for Files::         Size limitations that pertain to individual 
files.
+-                                These can vary between file systems
+-                                or even from file to file.
+-* Options for Files::        Optional features that some files may support.
+-* File Minimums::            Minimum values for file limits.
+-* Pathconf::                 Getting the limit values for a particular file.
+-
+-* Utility Limits::           Capacity limits of some POSIX.2 utility programs.
+-* Utility Minimums::         Minimum allowable values of those limits.
+-
+-* String Parameters::        Getting the default search path.
+-
+-
+-File: libc.info,  Node: General Limits,  Next: System Options,  Up: System 
Configuration
+-
+-General Capacity Limits
+-=======================
+-
+-   The POSIX.1 and POSIX.2 standards specify a number of parameters that
+-describe capacity limitations of the system.  These limits can be fixed
+-constants for a given operating system, or they can vary from machine to
+-machine.  For example, some limit values may be configurable by the
+-system administrator, either at run time or by rebuilding the kernel,
+-and this should not require recompiling application programs.
+-
+-   Each of the following limit parameters has a macro that is defined in
+-`limits.h' only if the system has a fixed, uniform limit for the
+-parameter in question.  If the system allows different file systems or
+-files to have different limits, then the macro is undefined; use
+-`sysconf' to find out the limit that applies at a particular time on a
+-particular machine.  *Note Sysconf::.
+-
+-   Each of these parameters also has another macro, with a name starting
+-with `_POSIX', which gives the lowest value that the limit is allowed
+-to have on *any* POSIX system.  *Note Minimums::.
+-
+- - Macro: int ARG_MAX
+-     If defined, the unvarying maximum combined length of the ARGV and
+-     ENVIRON arguments that can be passed to the `exec' functions.
+-
+- - Macro: int CHILD_MAX
+-     If defined, the unvarying maximum number of processes that can
+-     exist with the same real user ID at any one time.  In BSD and GNU,
+-     this is controlled by the `RLIMIT_NPROC' resource limit; *note
+-     Limits on Resources::..
+-
+- - Macro: int OPEN_MAX
+-     If defined, the unvarying maximum number of files that a single
+-     process can have open simultaneously.  In BSD and GNU, this is
+-     controlled by the `RLIMIT_NOFILE' resource limit; *note Limits on
+-     Resources::..
+-
+- - Macro: int STREAM_MAX
+-     If defined, the unvarying maximum number of streams that a single
+-     process can have open simultaneously.  *Note Opening Streams::.
+-
+- - Macro: int TZNAME_MAX
+-     If defined, the unvarying maximum length of a time zone name.
+-     *Note Time Zone Functions::.
+-
+-   These limit macros are always defined in `limits.h'.
+-
+- - Macro: int NGROUPS_MAX
+-     The maximum number of supplementary group IDs that one process can
+-     have.
+-
+-     The value of this macro is actually a lower bound for the maximum.
+-     That is, you can count on being able to have that many
+-     supplementary group IDs, but a particular machine might let you
+-     have even more.  You can use `sysconf' to see whether a particular
+-     machine will let you have more (*note Sysconf::.).
+-
+- - Macro: int SSIZE_MAX
+-     The largest value that can fit in an object of type `ssize_t'.
+-     Effectively, this is the limit on the number of bytes that can be
+-     read or written in a single operation.
+-
+-     This macro is defined in all POSIX systems because this limit is
+-     never configurable.
+-
+- - Macro: int RE_DUP_MAX
+-     The largest number of repetitions you are guaranteed is allowed in
+-     the construct `\{MIN,MAX\}' in a regular expression.
+-
+-     The value of this macro is actually a lower bound for the maximum.
+-     That is, you can count on being able to have that many
+-     repetitions, but a particular machine might let you have even
+-     more.  You can use `sysconf' to see whether a particular machine
+-     will let you have more (*note Sysconf::.).  And even the value
+-     that `sysconf' tells you is just a lower bound--larger values
+-     might work.
+-
+-     This macro is defined in all POSIX.2 systems, because POSIX.2 says
+-     it should always be defined even if there is no specific imposed
+-     limit.
+-
+-
+-File: libc.info,  Node: System Options,  Next: Version Supported,  Prev: 
General Limits,  Up: System Configuration
+-
+-Overall System Options
+-======================
+-
+-   POSIX defines certain system-specific options that not all POSIX
+-systems support.  Since these options are provided in the kernel, not
+-in the library, simply using the GNU C library does not guarantee any
+-of these features is supported; it depends on the system you are using.
+-
+-   You can test for the availability of a given option using the macros
+-in this section, together with the function `sysconf'.  The macros are
+-defined only if you include `unistd.h'.
+-
+-   For the following macros, if the macro is defined in `unistd.h',
+-then the option is supported.  Otherwise, the option may or may not be
+-supported; use `sysconf' to find out.  *Note Sysconf::.
+-
+- - Macro: int _POSIX_JOB_CONTROL
+-     If this symbol is defined, it indicates that the system supports
+-     job control.  Otherwise, the implementation behaves as if all
+-     processes within a session belong to a single process group.
+-     *Note Job Control::.
+-
+- - Macro: int _POSIX_SAVED_IDS
+-     If this symbol is defined, it indicates that the system remembers
+-     the effective user and group IDs of a process before it executes an
+-     executable file with the set-user-ID or set-group-ID bits set, and
+-     that explicitly changing the effective user or group IDs back to
+-     these values is permitted.  If this option is not defined, then if
+-     a nonprivileged process changes its effective user or group ID to
+-     the real user or group ID of the process, it can't change it back
+-     again.  *Note Enable/Disable Setuid::.
+-
+-   For the following macros, if the macro is defined in `unistd.h',
+-then its value indicates whether the option is supported.  A value of
+-`-1' means no, and any other value means yes.  If the macro is not
+-defined, then the option may or may not be supported; use `sysconf' to
+-find out.  *Note Sysconf::.
+-
+- - Macro: int _POSIX2_C_DEV
+-     If this symbol is defined, it indicates that the system has the
+-     POSIX.2 C compiler command, `c89'.  The GNU C library always
+-     defines this as `1', on the assumption that you would not have
+-     installed it if you didn't have a C compiler.
+-
+- - Macro: int _POSIX2_FORT_DEV
+-     If this symbol is defined, it indicates that the system has the
+-     POSIX.2 Fortran compiler command, `fort77'.  The GNU C library
+-     never defines this, because we don't know what the system has.
+-
+- - Macro: int _POSIX2_FORT_RUN
+-     If this symbol is defined, it indicates that the system has the
+-     POSIX.2 `asa' command to interpret Fortran carriage control.  The
+-     GNU C library never defines this, because we don't know what the
+-     system has.
+-
+- - Macro: int _POSIX2_LOCALEDEF
+-     If this symbol is defined, it indicates that the system has the
+-     POSIX.2 `localedef' command.  The GNU C library never defines
+-     this, because we don't know what the system has.
+-
+- - Macro: int _POSIX2_SW_DEV
+-     If this symbol is defined, it indicates that the system has the
+-     POSIX.2 commands `ar', `make', and `strip'.  The GNU C library
+-     always defines this as `1', on the assumption that you had to have
+-     `ar' and `make' to install the library, and it's unlikely that
+-     `strip' would be absent when those are present.
+-
+-
+-File: libc.info,  Node: Version Supported,  Next: Sysconf,  Prev: System 
Options,  Up: System Configuration
+-
+-Which Version of POSIX is Supported
+-===================================
+-
+- - Macro: long int _POSIX_VERSION
+-     This constant represents the version of the POSIX.1 standard to
+-     which the implementation conforms.  For an implementation
+-     conforming to the 1990 POSIX.1 standard, the value is the integer
+-     `199009L'.
+-
+-     `_POSIX_VERSION' is always defined (in `unistd.h') in any POSIX
+-     system.
+-
+-     *Usage Note:* Don't try to test whether the system supports POSIX
+-     by including `unistd.h' and then checking whether `_POSIX_VERSION'
+-     is defined.  On a non-POSIX system, this will probably fail
+-     because there is no `unistd.h'.  We do not know of *any* way you
+-     can reliably test at compilation time whether your target system
+-     supports POSIX or whether `unistd.h' exists.
+-
+-     The GNU C compiler predefines the symbol `__POSIX__' if the target
+-     system is a POSIX system.  Provided you do not use any other
+-     compilers on POSIX systems, testing `defined (__POSIX__)' will
+-     reliably detect such systems.
+-
+- - Macro: long int _POSIX2_C_VERSION
+-     This constant represents the version of the POSIX.2 standard which
+-     the library and system kernel support.  We don't know what value
+-     this will be for the first version of the POSIX.2 standard,
+-     because the value is based on the year and month in which the
+-     standard is officially adopted.
+-
+-     The value of this symbol says nothing about the utilities
+-     installed on the system.
+-
+-     *Usage Note:* You can use this macro to tell whether a POSIX.1
+-     system library supports POSIX.2 as well.  Any POSIX.1 system
+-     contains `unistd.h', so include that file and then test `defined
+-     (_POSIX2_C_VERSION)'.
+-
+-
+-File: libc.info,  Node: Sysconf,  Next: Minimums,  Prev: Version Supported,  
Up: System Configuration
+-
+-Using `sysconf'
+-===============
+-
+-   When your system has configurable system limits, you can use the
+-`sysconf' function to find out the value that applies to any particular
+-machine.  The function and the associated PARAMETER constants are
+-declared in the header file `unistd.h'.
+-
+-* Menu:
+-
+-* Sysconf Definition::        Detailed specifications of `sysconf'.
+-* Constants for Sysconf::     The list of parameters `sysconf' can read.
+-* Examples of Sysconf::       How to use `sysconf' and the parameter
+-                               macros properly together.
+-
+-
+-File: libc.info,  Node: Sysconf Definition,  Next: Constants for Sysconf,  
Up: Sysconf
+-
+-Definition of `sysconf'
+------------------------
+-
+- - Function: long int sysconf (int PARAMETER)
+-     This function is used to inquire about runtime system parameters.
+-     The PARAMETER argument should be one of the `_SC_' symbols listed
+-     below.
+-
+-     The normal return value from `sysconf' is the value you requested.
+-     A value of `-1' is returned both if the implementation does not
+-     impose a limit, and in case of an error.
+-
+-     The following `errno' error conditions are defined for this
+-     function:
+-
+-    `EINVAL'
+-          The value of the PARAMETER is invalid.
+-
+-
+-File: libc.info,  Node: Constants for Sysconf,  Next: Examples of Sysconf,  
Prev: Sysconf Definition,  Up: Sysconf
+-
+-Constants for `sysconf' Parameters
+-----------------------------------
+-
+-   Here are the symbolic constants for use as the PARAMETER argument to
+-`sysconf'.  The values are all integer constants (more specifically,
+-enumeration type values).
+-
+-`_SC_ARG_MAX'
+-     Inquire about the parameter corresponding to `ARG_MAX'.
+-
+-`_SC_CHILD_MAX'
+-     Inquire about the parameter corresponding to `CHILD_MAX'.
+-
+-`_SC_OPEN_MAX'
+-     Inquire about the parameter corresponding to `OPEN_MAX'.
+-
+-`_SC_STREAM_MAX'
+-     Inquire about the parameter corresponding to `STREAM_MAX'.
+-
+-`_SC_TZNAME_MAX'
+-     Inquire about the parameter corresponding to `TZNAME_MAX'.
+-
+-`_SC_NGROUPS_MAX'
+-     Inquire about the parameter corresponding to `NGROUPS_MAX'.
+-
+-`_SC_JOB_CONTROL'
+-     Inquire about the parameter corresponding to `_POSIX_JOB_CONTROL'.
+-
+-`_SC_SAVED_IDS'
+-     Inquire about the parameter corresponding to `_POSIX_SAVED_IDS'.
+-
+-`_SC_VERSION'
+-     Inquire about the parameter corresponding to `_POSIX_VERSION'.
+-
+-`_SC_CLK_TCK'
+-     Inquire about the parameter corresponding to `CLOCKS_PER_SEC';
+-     *note Basic CPU Time::..
+-
+-`_SC_2_C_DEV'
+-     Inquire about whether the system has the POSIX.2 C compiler
+-     command, `c89'.
+-
+-`_SC_2_FORT_DEV'
+-     Inquire about whether the system has the POSIX.2 Fortran compiler
+-     command, `fort77'.
+-
+-`_SC_2_FORT_RUN'
+-     Inquire about whether the system has the POSIX.2 `asa' command to
+-     interpret Fortran carriage control.
+-
+-`_SC_2_LOCALEDEF'
+-     Inquire about whether the system has the POSIX.2 `localedef'
+-     command.
+-
+-`_SC_2_SW_DEV'
+-     Inquire about whether the system has the POSIX.2 commands `ar',
+-     `make', and `strip'.
+-
+-`_SC_BC_BASE_MAX'
+-     Inquire about the maximum value of `obase' in the `bc' utility.
+-
+-`_SC_BC_DIM_MAX'
+-     Inquire about the maximum size of an array in the `bc' utility.
+-
+-`_SC_BC_SCALE_MAX'
+-     Inquire about the maximum value of `scale' in the `bc' utility.
+-
+-`_SC_BC_STRING_MAX'
+-     Inquire about the maximum size of a string constant in the `bc'
+-     utility.
+-
+-`_SC_COLL_WEIGHTS_MAX'
+-     Inquire about the maximum number of weights that can necessarily
+-     be used in defining the collating sequence for a locale.
+-
+-`_SC_EXPR_NEST_MAX'
+-     Inquire about the maximum number of expressions nested within
+-     parentheses when using the `expr' utility.
+-
+-`_SC_LINE_MAX'
+-     Inquire about the maximum size of a text line that the POSIX.2 text
+-     utilities can handle.
+-
+-`_SC_EQUIV_CLASS_MAX'
+-     Inquire about the maximum number of weights that can be assigned
+-     to an entry of the `LC_COLLATE' category `order' keyword in a
+-     locale definition.  The GNU C library does not presently support
+-     locale definitions.
+-
+-`_SC_VERSION'
+-     Inquire about the version number of POSIX.1 that the library and
+-     kernel support.
+-
+-`_SC_2_VERSION'
+-     Inquire about the version number of POSIX.2 that the system
+-     utilities support.
+-
+-`_SC_PAGESIZE'
+-     Inquire about the virtual memory page size of the machine.
+-     `getpagesize' returns the same value.
+-
+-
+-File: libc.info,  Node: Examples of Sysconf,  Prev: Constants for Sysconf,  
Up: Sysconf
+-
+-Examples of `sysconf'
+----------------------
+-
+-   We recommend that you first test for a macro definition for the
+-parameter you are interested in, and call `sysconf' only if the macro
+-is not defined.  For example, here is how to test whether job control
+-is supported:
+-
+-     int
+-     have_job_control (void)
+-     {
+-     #ifdef _POSIX_JOB_CONTROL
+-       return 1;
+-     #else
+-       int value = sysconf (_SC_JOB_CONTROL);
+-       if (value < 0)
+-         /* If the system is that badly wedged,
+-            there's no use trying to go on.  */
+-         fatal (strerror (errno));
+-       return value;
+-     #endif
+-     }
+-
+-   Here is how to get the value of a numeric limit:
+-
+-     int
+-     get_child_max ()
+-     {
+-     #ifdef CHILD_MAX
+-       return CHILD_MAX;
+-     #else
+-       int value = sysconf (_SC_CHILD_MAX);
+-       if (value < 0)
+-         fatal (strerror (errno));
+-       return value;
+-     #endif
+-     }
+-
+-
+-File: libc.info,  Node: Minimums,  Next: Limits for Files,  Prev: Sysconf,  
Up: System Configuration
+-
+-Minimum Values for General Capacity Limits
+-==========================================
+-
+-   Here are the names for the POSIX minimum upper bounds for the system
+-limit parameters.  The significance of these values is that you can
+-safely push to these limits without checking whether the particular
+-system you are using can go that far.
+-
+-`_POSIX_ARG_MAX'
+-     The value of this macro is the most restrictive limit permitted by
+-     POSIX for the maximum combined length of the ARGV and ENVIRON
+-     arguments that can be passed to the `exec' functions.  Its value
+-     is `4096'.
+-
+-`_POSIX_CHILD_MAX'
+-     The value of this macro is the most restrictive limit permitted by
+-     POSIX for the maximum number of simultaneous processes per real
+-     user ID.  Its value is `6'.
+-
+-`_POSIX_NGROUPS_MAX'
+-     The value of this macro is the most restrictive limit permitted by
+-     POSIX for the maximum number of supplementary group IDs per
+-     process.  Its value is `0'.
+-
+-`_POSIX_OPEN_MAX'
+-     The value of this macro is the most restrictive limit permitted by
+-     POSIX for the maximum number of files that a single process can
+-     have open simultaneously.  Its value is `16'.
+-
+-`_POSIX_SSIZE_MAX'
+-     The value of this macro is the most restrictive limit permitted by
+-     POSIX for the maximum value that can be stored in an object of type
+-     `ssize_t'.  Its value is `32767'.
+-
+-`_POSIX_STREAM_MAX'
+-     The value of this macro is the most restrictive limit permitted by
+-     POSIX for the maximum number of streams that a single process can
+-     have open simultaneously.  Its value is `8'.
+-
+-`_POSIX_TZNAME_MAX'
+-     The value of this macro is the most restrictive limit permitted by
+-     POSIX for the maximum length of a time zone name.  Its value is
+-     `3'.
+-
+-`_POSIX2_RE_DUP_MAX'
+-     The value of this macro is the most restrictive limit permitted by
+-     POSIX for the numbers used in the `\{MIN,MAX\}' construct in a
+-     regular expression.  Its value is `255'.
+-
+-
+-File: libc.info,  Node: Limits for Files,  Next: Options for Files,  Prev: 
Minimums,  Up: System Configuration
+-
+-Limits on File System Capacity
+-==============================
+-
+-   The POSIX.1 standard specifies a number of parameters that describe
+-the limitations of the file system.  It's possible for the system to
+-have a fixed, uniform limit for a parameter, but this isn't the usual
+-case.  On most systems, it's possible for different file systems (and,
+-for some parameters, even different files) to have different maximum
+-limits.  For example, this is very likely if you use NFS to mount some
+-of the file systems from other machines.
+-
+-   Each of the following macros is defined in `limits.h' only if the
+-system has a fixed, uniform limit for the parameter in question.  If the
+-system allows different file systems or files to have different limits,
+-then the macro is undefined; use `pathconf' or `fpathconf' to find out
+-the limit that applies to a particular file.  *Note Pathconf::.
+-
+-   Each parameter also has another macro, with a name starting with
+-`_POSIX', which gives the lowest value that the limit is allowed to
+-have on *any* POSIX system.  *Note File Minimums::.
+-
+- - Macro: int LINK_MAX
+-     The uniform system limit (if any) for the number of names for a
+-     given file.  *Note Hard Links::.
+-
+- - Macro: int MAX_CANON
+-     The uniform system limit (if any) for the amount of text in a line
+-     of input when input editing is enabled.  *Note Canonical or Not::.
+-
+- - Macro: int MAX_INPUT
+-     The uniform system limit (if any) for the total number of
+-     characters typed ahead as input.  *Note I/O Queues::.
+-
+- - Macro: int NAME_MAX
+-     The uniform system limit (if any) for the length of a file name
+-     component.
+-
+- - Macro: int PATH_MAX
+-     The uniform system limit (if any) for the length of an entire file
+-     name (that is, the argument given to system calls such as `open').
+-
+- - Macro: int PIPE_BUF
+-     The uniform system limit (if any) for the number of bytes that can
+-     be written atomically to a pipe.  If multiple processes are
+-     writing to the same pipe simultaneously, output from different
+-     processes might be interleaved in chunks of this size.  *Note
+-     Pipes and FIFOs::.
+-
+-   These are alternative macro names for some of the same information.
+-
+- - Macro: int MAXNAMLEN
+-     This is the BSD name for `NAME_MAX'.  It is defined in `dirent.h'.
+-
+- - Macro: int FILENAME_MAX
+-     The value of this macro is an integer constant expression that
+-     represents the maximum length of a file name string.  It is
+-     defined in `stdio.h'.
+-
+-     Unlike `PATH_MAX', this macro is defined even if there is no actual
+-     limit imposed.  In such a case, its value is typically a very large
+-     number.  *This is always the case on the GNU system.*
+-
+-     *Usage Note:* Don't use `FILENAME_MAX' as the size of an array in
+-     which to store a file name!  You can't possibly make an array that
+-     big!  Use dynamic allocation (*note Memory Allocation::.) instead.
+-
+-
+-File: libc.info,  Node: Options for Files,  Next: File Minimums,  Prev: 
Limits for Files,  Up: System Configuration
+-
+-Optional Features in File Support
+-=================================
+-
+-   POSIX defines certain system-specific options in the system calls for
+-operating on files.  Some systems support these options and others do
+-not.  Since these options are provided in the kernel, not in the
+-library, simply using the GNU C library does not guarantee any of these
+-features is supported; it depends on the system you are using.  They can
+-also vary between file systems on a single machine.
+-
+-   This section describes the macros you can test to determine whether a
+-particular option is supported on your machine.  If a given macro is
+-defined in `unistd.h', then its value says whether the corresponding
+-feature is supported.  (A value of `-1' indicates no; any other value
+-indicates yes.)  If the macro is undefined, it means particular files
+-may or may not support the feature.
+-
+-   Since all the machines that support the GNU C library also support
+-NFS, one can never make a general statement about whether all file
+-systems support the `_POSIX_CHOWN_RESTRICTED' and `_POSIX_NO_TRUNC'
+-features.  So these names are never defined as macros in the GNU C
+-library.
+-
+- - Macro: int _POSIX_CHOWN_RESTRICTED
+-     If this option is in effect, the `chown' function is restricted so
+-     that the only changes permitted to nonprivileged processes is to
+-     change the group owner of a file to either be the effective group
+-     ID of the process, or one of its supplementary group IDs.  *Note
+-     File Owner::.
+-
+- - Macro: int _POSIX_NO_TRUNC
+-     If this option is in effect, file name components longer than
+-     `NAME_MAX' generate an `ENAMETOOLONG' error.  Otherwise, file name
+-     components that are too long are silently truncated.
+-
+- - Macro: unsigned char _POSIX_VDISABLE
+-     This option is only meaningful for files that are terminal devices.
+-     If it is enabled, then handling for special control characters can
+-     be disabled individually.  *Note Special Characters::.
+-
+-   If one of these macros is undefined, that means that the option
+-might be in effect for some files and not for others.  To inquire about
+-a particular file, call `pathconf' or `fpathconf'.  *Note Pathconf::.
+-
+-
+-File: libc.info,  Node: File Minimums,  Next: Pathconf,  Prev: Options for 
Files,  Up: System Configuration
+-
+-Minimum Values for File System Limits
+-=====================================
+-
+-   Here are the names for the POSIX minimum upper bounds for some of the
+-above parameters.  The significance of these values is that you can
+-safely push to these limits without checking whether the particular
+-system you are using can go that far.
+-
+-`_POSIX_LINK_MAX'
+-     The most restrictive limit permitted by POSIX for the maximum
+-     value of a file's link count.  The value of this constant is `8';
+-     thus, you can always make up to eight names for a file without
+-     running into a system limit.
+-
+-`_POSIX_MAX_CANON'
+-     The most restrictive limit permitted by POSIX for the maximum
+-     number of bytes in a canonical input line from a terminal device.
+-     The value of this constant is `255'.
+-
+-`_POSIX_MAX_INPUT'
+-     The most restrictive limit permitted by POSIX for the maximum
+-     number of bytes in a terminal device input queue (or typeahead
+-     buffer).  *Note Input Modes::.  The value of this constant is
+-     `255'.
+-
+-`_POSIX_NAME_MAX'
+-     The most restrictive limit permitted by POSIX for the maximum
+-     number of bytes in a file name component.  The value of this
+-     constant is `14'.
+-
+-`_POSIX_PATH_MAX'
+-     The most restrictive limit permitted by POSIX for the maximum
+-     number of bytes in a file name.  The value of this constant is
+-     `255'.
+-
+-`_POSIX_PIPE_BUF'
+-     The most restrictive limit permitted by POSIX for the maximum
+-     number of bytes that can be written atomically to a pipe.  The
+-     value of this constant is `512'.
+-
+-
+-File: libc.info,  Node: Pathconf,  Next: Utility Limits,  Prev: File 
Minimums,  Up: System Configuration
+-
+-Using `pathconf'
+-================
+-
+-   When your machine allows different files to have different values
+-for a file system parameter, you can use the functions in this section
+-to find out the value that applies to any particular file.
+-
+-   These functions and the associated constants for the PARAMETER
+-argument are declared in the header file `unistd.h'.
+-
+- - Function: long int pathconf (const char *FILENAME, int PARAMETER)
+-     This function is used to inquire about the limits that apply to
+-     the file named FILENAME.
+-
+-     The PARAMETER argument should be one of the `_PC_' constants
+-     listed below.
+-
+-     The normal return value from `pathconf' is the value you requested.
+-     A value of `-1' is returned both if the implementation does not
+-     impose a limit, and in case of an error.  In the former case,
+-     `errno' is not set, while in the latter case, `errno' is set to
+-     indicate the cause of the problem.  So the only way to use this
+-     function robustly is to store `0' into `errno' just before calling
+-     it.
+-
+-     Besides the usual file name errors (*note File Name Errors::.),
+-     the following error condition is defined for this function:
+-
+-    `EINVAL'
+-          The value of PARAMETER is invalid, or the implementation
+-          doesn't support the PARAMETER for the specific file.
+-
+- - Function: long int fpathconf (int FILEDES, int PARAMETER)
+-     This is just like `pathconf' except that an open file descriptor
+-     is used to specify the file for which information is requested,
+-     instead of a file name.
+-
+-     The following `errno' error conditions are defined for this
+-     function:
+-
+-    `EBADF'
+-          The FILEDES argument is not a valid file descriptor.
+-
+-    `EINVAL'
+-          The value of PARAMETER is invalid, or the implementation
+-          doesn't support the PARAMETER for the specific file.
+-
+-   Here are the symbolic constants that you can use as the PARAMETER
+-argument to `pathconf' and `fpathconf'.  The values are all integer
+-constants.
+-
+-`_PC_LINK_MAX'
+-     Inquire about the value of `LINK_MAX'.
+-
+-`_PC_MAX_CANON'
+-     Inquire about the value of `MAX_CANON'.
+-
+-`_PC_MAX_INPUT'
+-     Inquire about the value of `MAX_INPUT'.
+-
+-`_PC_NAME_MAX'
+-     Inquire about the value of `NAME_MAX'.
+-
+-`_PC_PATH_MAX'
+-     Inquire about the value of `PATH_MAX'.
+-
+-`_PC_PIPE_BUF'
+-     Inquire about the value of `PIPE_BUF'.
+-
+-`_PC_CHOWN_RESTRICTED'
+-     Inquire about the value of `_POSIX_CHOWN_RESTRICTED'.
+-
+-`_PC_NO_TRUNC'
+-     Inquire about the value of `_POSIX_NO_TRUNC'.
+-
+-`_PC_VDISABLE'
+-     Inquire about the value of `_POSIX_VDISABLE'.
+-
+-
+-File: libc.info,  Node: Utility Limits,  Next: Utility Minimums,  Prev: 
Pathconf,  Up: System Configuration
+-
+-Utility Program Capacity Limits
+-===============================
+-
+-   The POSIX.2 standard specifies certain system limits that you can
+-access through `sysconf' that apply to utility behavior rather than the
+-behavior of the library or the operating system.
+-
+-   The GNU C library defines macros for these limits, and `sysconf'
+-returns values for them if you ask; but these values convey no
+-meaningful information.  They are simply the smallest values that
+-POSIX.2 permits.
+-
+- - Macro: int BC_BASE_MAX
+-     The largest value of `obase' that the `bc' utility is guaranteed
+-     to support.
+-
+- - Macro: int BC_SCALE_MAX
+-     The largest value of `scale' that the `bc' utility is guaranteed
+-     to support.
+-
+- - Macro: int BC_DIM_MAX
+-     The largest number of elements in one array that the `bc' utility
+-     is guaranteed to support.
+-
+- - Macro: int BC_STRING_MAX
+-     The largest number of characters in one string constant that the
+-     `bc' utility is guaranteed to support.
+-
+- - Macro: int BC_DIM_MAX
+-     The largest number of elements in one array that the `bc' utility
+-     is guaranteed to support.
+-
+- - Macro: int COLL_WEIGHTS_MAX
+-     The largest number of weights that can necessarily be used in
+-     defining the collating sequence for a locale.
+-
+- - Macro: int EXPR_NEST_MAX
+-     The maximum number of expressions that can be nested within
+-     parenthesis by the `expr' utility.
+-
+- - Macro: int LINE_MAX
+-     The largest text line that the text-oriented POSIX.2 utilities can
+-     support.  (If you are using the GNU versions of these utilities,
+-     then there is no actual limit except that imposed by the available
+-     virtual memory, but there is no way that the library can tell you
+-     this.)
+-
+- - Macro: int EQUIV_CLASS_MAX
+-     The maximum number of weights that can be assigned to an entry of
+-     the `LC_COLLATE' category `order' keyword in a locale definition.
+-     The GNU C library does not presently support locale definitions.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-27 
glibc-2.0.1/manual/libc.info-27
+--- ../glibc-2.0.1/manual/libc.info-27 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-27    1970-01-01 01:00:00.000000000 +0100
+@@ -1,1214 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+-   This file documents the GNU C library.
+-
+-   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+-   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+-   Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+-   Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+-   Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License"