[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" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: Utility Minimums, Next: String Parameters, Prev:
Utility Limits, Up: System Configuration
+-
+-Minimum Values for Utility Limits
+-=================================
+-
+-`_POSIX2_BC_BASE_MAX'
+- The most restrictive limit permitted by POSIX.2 for the maximum
+- value of `obase' in the `bc' utility. Its value is `99'.
+-
+-`_POSIX2_BC_DIM_MAX'
+- The most restrictive limit permitted by POSIX.2 for the maximum
+- size of an array in the `bc' utility. Its value is `2048'.
+-
+-`_POSIX2_BC_SCALE_MAX'
+- The most restrictive limit permitted by POSIX.2 for the maximum
+- value of `scale' in the `bc' utility. Its value is `99'.
+-
+-`_POSIX2_BC_STRING_MAX'
+- The most restrictive limit permitted by POSIX.2 for the maximum
+- size of a string constant in the `bc' utility. Its value is
+- `1000'.
+-
+-`_POSIX2_COLL_WEIGHTS_MAX'
+- The most restrictive limit permitted by POSIX.2 for the maximum
+- number of weights that can necessarily be used in defining the
+- collating sequence for a locale. Its value is `2'.
+-
+-`_POSIX2_EXPR_NEST_MAX'
+- The most restrictive limit permitted by POSIX.2 for the maximum
+- number of expressions nested within parenthesis when using the
+- `expr' utility. Its value is `32'.
+-
+-`_POSIX2_LINE_MAX'
+- The most restrictive limit permitted by POSIX.2 for the maximum
+- size of a text line that the text utilities can handle. Its value
+- is `2048'.
+-
+-`_POSIX2_EQUIV_CLASS_MAX'
+- The most restrictive limit permitted by POSIX.2 for the maximum
+- number of weights that can be assigned to an entry of the
+- `LC_COLLATE' category `order' keyword in a locale definition. Its
+- value is `2'. The GNU C library does not presently support locale
+- definitions.
+-
+-
+-File: libc.info, Node: String Parameters, Prev: Utility Minimums, Up:
System Configuration
+-
+-String-Valued Parameters
+-========================
+-
+- POSIX.2 defines a way to get string-valued parameters from the
+-operating system with the function `confstr':
+-
+- - Function: size_t confstr (int PARAMETER, char *BUF, size_t LEN)
+- This function reads the value of a string-valued system parameter,
+- storing the string into LEN bytes of memory space starting at BUF.
+- The PARAMETER argument should be one of the `_CS_' symbols listed
+- below.
+-
+- The normal return value from `confstr' is the length of the string
+- value that you asked for. If you supply a null pointer for BUF,
+- then `confstr' does not try to store the string; it just returns
+- its length. A value of `0' indicates an error.
+-
+- If the string you asked for is too long for the buffer (that is,
+- longer than `LEN - 1'), then `confstr' stores just that much
+- (leaving room for the terminating null character). You can tell
+- that this has happened because `confstr' returns a value greater
+- than or equal to LEN.
+-
+- The following `errno' error conditions are defined for this
+- function:
+-
+- `EINVAL'
+- The value of the PARAMETER is invalid.
+-
+- Currently there is just one parameter you can read with `confstr':
+-
+-`_CS_PATH'
+- This parameter's value is the recommended default path for
+- searching for executable files. This is the path that a user has
+- by default just after logging in.
+-
+- The way to use `confstr' without any arbitrary limit on string size
+-is to call it twice: first call it to get the length, allocate the
+-buffer accordingly, and then call `confstr' again to fill the buffer,
+-like this:
+-
+- char *
+- get_default_path (void)
+- {
+- size_t len = confstr (_CS_PATH, NULL, 0);
+- char *buffer = (char *) xmalloc (len);
+-
+- if (confstr (_CS_PATH, buf, len + 1) == 0)
+- {
+- free (buffer);
+- return NULL;
+- }
+-
+- return buffer;
+- }
+-
+-
+-File: libc.info, Node: Language Features, Next: Library Summary, Prev:
System Configuration, Up: Top
+-
+-C Language Facilities in the Library
+-************************************
+-
+- Some of the facilities implemented by the C library really should be
+-thought of as parts of the C language itself. These facilities ought to
+-be documented in the C Language Manual, not in the library manual; but
+-since we don't have the language manual yet, and documentation for these
+-features has been written, we are publishing it here.
+-
+-* Menu:
+-
+-* Consistency Checking:: Using `assert' to abort if
+- something "impossible" happens.
+-* Variadic Functions:: Defining functions with varying numbers
+- of args.
+-* Null Pointer Constant:: The macro `NULL'.
+-* Important Data Types:: Data types for object sizes.
+-* Data Type Measurements:: Parameters of data type representations.
+-
+-
+-File: libc.info, Node: Consistency Checking, Next: Variadic Functions, Up:
Language Features
+-
+-Explicitly Checking Internal Consistency
+-========================================
+-
+- When you're writing a program, it's often a good idea to put in
+-checks at strategic places for "impossible" errors or violations of
+-basic assumptions. These kinds of checks are helpful in debugging
+-problems with the interfaces between different parts of the program,
+-for example.
+-
+- The `assert' macro, defined in the header file `assert.h', provides
+-a convenient way to abort the program while printing a message about
+-where in the program the error was detected.
+-
+- Once you think your program is debugged, you can disable the error
+-checks performed by the `assert' macro by recompiling with the macro
+-`NDEBUG' defined. This means you don't actually have to change the
+-program source code to disable these checks.
+-
+- But disabling these consistency checks is undesirable unless they
+-make the program significantly slower. All else being equal, more error
+-checking is good no matter who is running the program. A wise user
+-would rather have a program crash, visibly, than have it return nonsense
+-without indicating anything might be wrong.
+-
+- - Macro: void assert (int EXPRESSION)
+- Verify the programmer's belief that EXPRESSION should be nonzero
+- at this point in the program.
+-
+- If `NDEBUG' is not defined, `assert' tests the value of
+- EXPRESSION. If it is false (zero), `assert' aborts the program
+- (*note Aborting a Program::.) after printing a message of the form:
+-
+- `FILE':LINENUM: FUNCTION: Assertion `EXPRESSION' failed.
+-
+- on the standard error stream `stderr' (*note Standard Streams::.).
+- The filename and line number are taken from the C preprocessor
+- macros `__FILE__' and `__LINE__' and specify where the call to
+- `assert' was written. When using the GNU C compiler, the name of
+- the function which calls `assert' is taken from the built-in
+- variable `__PRETTY_FUNCTION__'; with older compilers, the function
+- name and following colon are omitted.
+-
+- If the preprocessor macro `NDEBUG' is defined before `assert.h' is
+- included, the `assert' macro is defined to do absolutely nothing.
+-
+- *Warning:* Even the argument expression EXPRESSION is not
+- evaluated if `NDEBUG' is in effect. So never use `assert' with
+- arguments that involve side effects. For example, `assert (++i >
+- 0);' is a bad idea, because `i' will not be incremented if
+- `NDEBUG' is defined.
+-
+- Sometimes the "impossible" condition you want to check for is an
+-error return from an operating system function. Then it is useful to
+-display not only where the program crashes, but also what error was
+-returned. The `assert_perror' macro makes this easy.
+-
+- - Macro: void assert_perror (int ERRNUM)
+- Similar to `assert', but verifies that ERRNUM is zero.
+-
+- If `NDEBUG' is defined, `assert_perror' tests the value of ERRNUM.
+- If it is nonzero, `assert_perror' aborts the program after a
+- printing a message of the form:
+-
+- `FILE':LINENUM: FUNCTION: ERROR TEXT
+-
+- on the standard error stream. The file name, line number, and
+- function name are as for `assert'. The error text is the result of
+- `strerror (ERRNUM)'. *Note Error Messages::.
+-
+- Like `assert', if `NDEBUG' is defined before `assert.h' is
+- included, the `assert_perror' macro does absolutely nothing. It
+- does not evaluate the argument, so ERRNUM should not have any side
+- effects. It is best for ERRNUM to be a just simple variable
+- reference; often it will be `errno'.
+-
+- This macro is a GNU extension.
+-
+- *Usage note:* The `assert' facility is designed for detecting
+-*internal inconsistency*; it is not suitable for reporting invalid
+-input or improper usage by *the user* of the program.
+-
+- The information in the diagnostic messages printed by the `assert'
+-macro is intended to help you, the programmer, track down the cause of a
+-bug, but is not really useful for telling a user of your program why his
+-or her input was invalid or why a command could not be carried out. So
+-you can't use `assert' or `assert_perror' to print the error messages
+-for these eventualities.
+-
+- What's more, your program should not abort when given invalid input,
+-as `assert' would do--it should exit with nonzero status (*note Exit
+-Status::.) after printing its error messages, or perhaps read another
+-command or move on to the next input file.
+-
+- *Note Error Messages::, for information on printing error messages
+-for problems that *do not* represent bugs in the program.
+-
+-
+-File: libc.info, Node: Variadic Functions, Next: Null Pointer Constant,
Prev: Consistency Checking, Up: Language Features
+-
+-Variadic Functions
+-==================
+-
+- ISO C defines a syntax for declaring a function to take a variable
+-number or type of arguments. (Such functions are referred to as
+-"varargs functions" or "variadic functions".) However, the language
+-itself provides no mechanism for such functions to access their
+-non-required arguments; instead, you use the variable arguments macros
+-defined in `stdarg.h'.
+-
+- This section describes how to declare variadic functions, how to
+-write them, and how to call them properly.
+-
+- *Compatibility Note:* Many older C dialects provide a similar, but
+-incompatible, mechanism for defining functions with variable numbers of
+-arguments, using `varargs.h'.
+-
+-* Menu:
+-
+-* Why Variadic:: Reasons for making functions take
+- variable arguments.
+-* How Variadic:: How to define and call variadic functions.
+-* Variadic Example:: A complete example.
+-
+-
+-File: libc.info, Node: Why Variadic, Next: How Variadic, Up: Variadic
Functions
+-
+-Why Variadic Functions are Used
+--------------------------------
+-
+- Ordinary C functions take a fixed number of arguments. When you
+-define a function, you specify the data type for each argument. Every
+-call to the function should supply the expected number of arguments,
+-with types that can be converted to the specified ones. Thus, if the
+-function `foo' is declared with `int foo (int, char *);' then you must
+-call it with two arguments, a number (any kind will do) and a string
+-pointer.
+-
+- But some functions perform operations that can meaningfully accept an
+-unlimited number of arguments.
+-
+- In some cases a function can handle any number of values by
+-operating on all of them as a block. For example, consider a function
+-that allocates a one-dimensional array with `malloc' to hold a
+-specified set of values. This operation makes sense for any number of
+-values, as long as the length of the array corresponds to that number.
+-Without facilities for variable arguments, you would have to define a
+-separate function for each possible array size.
+-
+- The library function `printf' (*note Formatted Output::.) is an
+-example of another class of function where variable arguments are
+-useful. This function prints its arguments (which can vary in type as
+-well as number) under the control of a format template string.
+-
+- These are good reasons to define a "variadic" function which can
+-handle as many arguments as the caller chooses to pass.
+-
+- Some functions such as `open' take a fixed set of arguments, but
+-occasionally ignore the last few. Strict adherence to ISO C requires
+-these functions to be defined as variadic; in practice, however, the GNU
+-C compiler and most other C compilers let you define such a function to
+-take a fixed set of arguments--the most it can ever use--and then only
+-*declare* the function as variadic (or not declare its arguments at
+-all!).
+-
+-
+-File: libc.info, Node: How Variadic, Next: Variadic Example, Prev: Why
Variadic, Up: Variadic Functions
+-
+-How Variadic Functions are Defined and Used
+--------------------------------------------
+-
+- Defining and using a variadic function involves three steps:
+-
+- * *Define* the function as variadic, using an ellipsis (`...') in
+- the argument list, and using special macros to access the variable
+- arguments. *Note Receiving Arguments::.
+-
+- * *Declare* the function as variadic, using a prototype with an
+- ellipsis (`...'), in all the files which call it. *Note Variadic
+- Prototypes::.
+-
+- * *Call* the function by writing the fixed arguments followed by the
+- additional variable arguments. *Note Calling Variadics::.
+-
+-* Menu:
+-
+-* Variadic Prototypes:: How to make a prototype for a function
+- with variable arguments.
+-* Receiving Arguments:: Steps you must follow to access the
+- optional argument values.
+-* How Many Arguments:: How to decide whether there are more arguments.
+-* Calling Variadics:: Things you need to know about calling
+- variable arguments functions.
+-* Argument Macros:: Detailed specification of the macros
+- for accessing variable arguments.
+-* Old Varargs:: The pre-ISO way of defining variadic functions.
+-
+-
+-File: libc.info, Node: Variadic Prototypes, Next: Receiving Arguments, Up:
How Variadic
+-
+-Syntax for Variable Arguments
+-.............................
+-
+- A function that accepts a variable number of arguments must be
+-declared with a prototype that says so. You write the fixed arguments
+-as usual, and then tack on `...' to indicate the possibility of
+-additional arguments. The syntax of ISO C requires at least one fixed
+-argument before the `...'. For example,
+-
+- int
+- func (const char *a, int b, ...)
+- {
+- ...
+- }
+-
+-outlines a definition of a function `func' which returns an `int' and
+-takes two required arguments, a `const char *' and an `int'. These are
+-followed by any number of anonymous arguments.
+-
+- *Portability note:* For some C compilers, the last required argument
+-must not be declared `register' in the function definition.
+-Furthermore, this argument's type must be "self-promoting": that is,
+-the default promotions must not change its type. This rules out array
+-and function types, as well as `float', `char' (whether signed or not)
+-and `short int' (whether signed or not). This is actually an ISO C
+-requirement.
+-
+-
+-File: libc.info, Node: Receiving Arguments, Next: How Many Arguments,
Prev: Variadic Prototypes, Up: How Variadic
+-
+-Receiving the Argument Values
+-.............................
+-
+- Ordinary fixed arguments have individual names, and you can use these
+-names to access their values. But optional arguments have no
+-names--nothing but `...'. How can you access them?
+-
+- The only way to access them is sequentially, in the order they were
+-written, and you must use special macros from `stdarg.h' in the
+-following three step process:
+-
+- 1. You initialize an argument pointer variable of type `va_list' using
+- `va_start'. The argument pointer when initialized points to the
+- first optional argument.
+-
+- 2. You access the optional arguments by successive calls to `va_arg'.
+- The first call to `va_arg' gives you the first optional argument,
+- the next call gives you the second, and so on.
+-
+- You can stop at any time if you wish to ignore any remaining
+- optional arguments. It is perfectly all right for a function to
+- access fewer arguments than were supplied in the call, but you
+- will get garbage values if you try to access too many arguments.
+-
+- 3. You indicate that you are finished with the argument pointer
+- variable by calling `va_end'.
+-
+- (In practice, with most C compilers, calling `va_end' does nothing
+- and you do not really need to call it. This is always true in the
+- GNU C compiler. But you might as well call `va_end' just in case
+- your program is someday compiled with a peculiar compiler.)
+-
+- *Note Argument Macros::, for the full definitions of `va_start',
+-`va_arg' and `va_end'.
+-
+- Steps 1 and 3 must be performed in the function that accepts the
+-optional arguments. However, you can pass the `va_list' variable as an
+-argument to another function and perform all or part of step 2 there.
+-
+- You can perform the entire sequence of the three steps multiple times
+-within a single function invocation. If you want to ignore the optional
+-arguments, you can do these steps zero times.
+-
+- You can have more than one argument pointer variable if you like.
+-You can initialize each variable with `va_start' when you wish, and
+-then you can fetch arguments with each argument pointer as you wish.
+-Each argument pointer variable will sequence through the same set of
+-argument values, but at its own pace.
+-
+- *Portability note:* With some compilers, once you pass an argument
+-pointer value to a subroutine, you must not keep using the same
+-argument pointer value after that subroutine returns. For full
+-portability, you should just pass it to `va_end'. This is actually an
+-ISO C requirement, but most ANSI C compilers work happily regardless.
+-
+-
+-File: libc.info, Node: How Many Arguments, Next: Calling Variadics, Prev:
Receiving Arguments, Up: How Variadic
+-
+-How Many Arguments Were Supplied
+-................................
+-
+- There is no general way for a function to determine the number and
+-type of the optional arguments it was called with. So whoever designs
+-the function typically designs a convention for the caller to tell it
+-how many arguments it has, and what kind. It is up to you to define an
+-appropriate calling convention for each variadic function, and write all
+-calls accordingly.
+-
+- One kind of calling convention is to pass the number of optional
+-arguments as one of the fixed arguments. This convention works provided
+-all of the optional arguments are of the same type.
+-
+- A similar alternative is to have one of the required arguments be a
+-bit mask, with a bit for each possible purpose for which an optional
+-argument might be supplied. You would test the bits in a predefined
+-sequence; if the bit is set, fetch the value of the next argument,
+-otherwise use a default value.
+-
+- A required argument can be used as a pattern to specify both the
+-number and types of the optional arguments. The format string argument
+-to `printf' is one example of this (*note Formatted Output
+-Functions::.).
+-
+- Another possibility is to pass an "end marker" value as the last
+-optional argument. For example, for a function that manipulates an
+-arbitrary number of pointer arguments, a null pointer might indicate the
+-end of the argument list. (This assumes that a null pointer isn't
+-otherwise meaningful to the function.) The `execl' function works in
+-just this way; see *Note Executing a File::.
+-
+-
+-File: libc.info, Node: Calling Variadics, Next: Argument Macros, Prev: How
Many Arguments, Up: How Variadic
+-
+-Calling Variadic Functions
+-..........................
+-
+- You don't have to write anything special when you call a variadic
+-function. Just write the arguments (required arguments, followed by
+-optional ones) inside parentheses, separated by commas, as usual. But
+-you should prepare by declaring the function with a prototype, and you
+-must know how the argument values are converted.
+-
+- In principle, functions that are *defined* to be variadic must also
+-be *declared* to be variadic using a function prototype whenever you
+-call them. (*Note Variadic Prototypes::, for how.) This is because
+-some C compilers use a different calling convention to pass the same set
+-of argument values to a function depending on whether that function
+-takes variable arguments or fixed arguments.
+-
+- In practice, the GNU C compiler always passes a given set of argument
+-types in the same way regardless of whether they are optional or
+-required. So, as long as the argument types are self-promoting, you can
+-safely omit declaring them. Usually it is a good idea to declare the
+-argument types for variadic functions, and indeed for all functions.
+-But there are a few functions which it is extremely convenient not to
+-have to declare as variadic--for example, `open' and `printf'.
+-
+- Since the prototype doesn't specify types for optional arguments, in
+-a call to a variadic function the "default argument promotions" are
+-performed on the optional argument values. This means the objects of
+-type `char' or `short int' (whether signed or not) are promoted to
+-either `int' or `unsigned int', as appropriate; and that objects of
+-type `float' are promoted to type `double'. So, if the caller passes a
+-`char' as an optional argument, it is promoted to an `int', and the
+-function should get it with `va_arg (AP, int)'.
+-
+- Conversion of the required arguments is controlled by the function
+-prototype in the usual way: the argument expression is converted to the
+-declared argument type as if it were being assigned to a variable of
+-that type.
+-
+-
+-File: libc.info, Node: Argument Macros, Next: Old Varargs, Prev: Calling
Variadics, Up: How Variadic
+-
+-Argument Access Macros
+-......................
+-
+- Here are descriptions of the macros used to retrieve variable
+-arguments. These macros are defined in the header file `stdarg.h'.
+-
+- - Data Type: va_list
+- The type `va_list' is used for argument pointer variables.
+-
+- - Macro: void va_start (va_list AP, LAST-REQUIRED)
+- This macro initializes the argument pointer variable AP to point
+- to the first of the optional arguments of the current function;
+- LAST-REQUIRED must be the last required argument to the function.
+-
+- *Note Old Varargs::, for an alternate definition of `va_start'
+- found in the header file `varargs.h'.
+-
+- - Macro: TYPE va_arg (va_list AP, TYPE)
+- The `va_arg' macro returns the value of the next optional argument,
+- and modifies the value of AP to point to the subsequent argument.
+- Thus, successive uses of `va_arg' return successive optional
+- arguments.
+-
+- The type of the value returned by `va_arg' is TYPE as specified in
+- the call. TYPE must be a self-promoting type (not `char' or
+- `short int' or `float') that matches the type of the actual
+- argument.
+-
+- - Macro: void va_end (va_list AP)
+- This ends the use of AP. After a `va_end' call, further `va_arg'
+- calls with the same AP may not work. You should invoke `va_end'
+- before returning from the function in which `va_start' was invoked
+- with the same AP argument.
+-
+- In the GNU C library, `va_end' does nothing, and you need not ever
+- use it except for reasons of portability.
+-
+-
+-
+-File: libc.info, Node: Variadic Example, Prev: How Variadic, Up: Variadic
Functions
+-
+-Example of a Variadic Function
+-------------------------------
+-
+- Here is a complete sample function that accepts a variable number of
+-arguments. The first argument to the function is the count of remaining
+-arguments, which are added up and the result returned. While trivial,
+-this function is sufficient to illustrate how to use the variable
+-arguments facility.
+-
+- #include <stdarg.h>
+- #include <stdio.h>
+-
+- int
+- add_em_up (int count,...)
+- {
+- va_list ap;
+- int i, sum;
+-
+- va_start (ap, count); /* Initialize the argument list. */
+-
+- sum = 0;
+- for (i = 0; i < count; i++)
+- sum += va_arg (ap, int); /* Get the next argument value. */
+-
+- va_end (ap); /* Clean up. */
+- return sum;
+- }
+-
+- int
+- main (void)
+- {
+- /* This call prints 16. */
+- printf ("%d\n", add_em_up (3, 5, 5, 6));
+-
+- /* This call prints 55. */
+- printf ("%d\n", add_em_up (10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10));
+-
+- return 0;
+- }
+-
+-
+-File: libc.info, Node: Old Varargs, Prev: Argument Macros, Up: How Variadic
+-
+-Old-Style Variadic Functions
+-............................
+-
+- Before ISO C, programmers used a slightly different facility for
+-writing variadic functions. The GNU C compiler still supports it;
+-currently, it is more portable than the ISO C facility, since support
+-for ISO C is still not universal. The header file which defines the
+-old-fashioned variadic facility is called `varargs.h'.
+-
+- Using `varargs.h' is almost the same as using `stdarg.h'. There is
+-no difference in how you call a variadic function; *Note Calling
+-Variadics::. The only difference is in how you define them. First of
+-all, you must use old-style non-prototype syntax, like this:
+-
+- tree
+- build (va_alist)
+- va_dcl
+- {
+-
+- Secondly, you must give `va_start' just one argument, like this:
+-
+- va_list p;
+- va_start (p);
+-
+- These are the special macros used for defining old-style variadic
+-functions:
+-
+- - Macro: va_alist
+- This macro stands for the argument name list required in a variadic
+- function.
+-
+- - Macro: va_dcl
+- This macro declares the implicit argument or arguments for a
+- variadic function.
+-
+- - Macro: void va_start (va_list AP)
+- This macro, as defined in `varargs.h', initializes the argument
+- pointer variable AP to point to the first argument of the current
+- function.
+-
+- The other argument macros, `va_arg' and `va_end', are the same in
+-`varargs.h' as in `stdarg.h'; see *Note Argument Macros:: for details.
+-
+- It does not work to include both `varargs.h' and `stdarg.h' in the
+-same compilation; they define `va_start' in conflicting ways.
+-
+-
+-File: libc.info, Node: Null Pointer Constant, Next: Important Data Types,
Prev: Variadic Functions, Up: Language Features
+-
+-Null Pointer Constant
+-=====================
+-
+- The null pointer constant is guaranteed not to point to any real
+-object. You can assign it to any pointer variable since it has type
+-`void *'. The preferred way to write a null pointer constant is with
+-`NULL'.
+-
+- - Macro: void * NULL
+- This is a null pointer constant.
+-
+- You can also use `0' or `(void *)0' as a null pointer constant, but
+-using `NULL' is cleaner because it makes the purpose of the constant
+-more evident.
+-
+- If you use the null pointer constant as a function argument, then for
+-complete portability you should make sure that the function has a
+-prototype declaration. Otherwise, if the target machine has two
+-different pointer representations, the compiler won't know which
+-representation to use for that argument. You can avoid the problem by
+-explicitly casting the constant to the proper pointer type, but we
+-recommend instead adding a prototype for the function you are calling.
+-
+-
+-File: libc.info, Node: Important Data Types, Next: Data Type Measurements,
Prev: Null Pointer Constant, Up: Language Features
+-
+-Important Data Types
+-====================
+-
+- The result of subtracting two pointers in C is always an integer,
+-but the precise data type varies from C compiler to C compiler.
+-Likewise, the data type of the result of `sizeof' also varies between
+-compilers. ISO defines standard aliases for these two types, so you
+-can refer to them in a portable fashion. They are defined in the
+-header file `stddef.h'.
+-
+- - Data Type: ptrdiff_t
+- This is the signed integer type of the result of subtracting two
+- pointers. For example, with the declaration `char *p1, *p2;', the
+- expression `p2 - p1' is of type `ptrdiff_t'. This will probably
+- be one of the standard signed integer types (`short int', `int' or
+- `long int'), but might be a nonstandard type that exists only for
+- this purpose.
+-
+- - Data Type: size_t
+- This is an unsigned integer type used to represent the sizes of
+- objects. The result of the `sizeof' operator is of this type, and
+- functions such as `malloc' (*note Unconstrained Allocation::.) and
+- `memcpy' (*note Copying and Concatenation::.) accept arguments of
+- this type to specify object sizes.
+-
+- *Usage Note:* `size_t' is the preferred way to declare any
+- arguments or variables that hold the size of an object.
+-
+- In the GNU system `size_t' is equivalent to either `unsigned int' or
+-`unsigned long int'. These types have identical properties on the GNU
+-system, and for most purposes, you can use them interchangeably.
+-However, they are distinct as data types, which makes a difference in
+-certain contexts.
+-
+- For example, when you specify the type of a function argument in a
+-function prototype, it makes a difference which one you use. If the
+-system header files declare `malloc' with an argument of type `size_t'
+-and you declare `malloc' with an argument of type `unsigned int', you
+-will get a compilation error if `size_t' happens to be `unsigned long
+-int' on your system. To avoid any possibility of error, when a
+-function argument or value is supposed to have type `size_t', never
+-declare its type in any other way.
+-
+- *Compatibility Note:* Implementations of C before the advent of
+-ISO C generally used `unsigned int' for representing object sizes and
+-`int' for pointer subtraction results. They did not necessarily define
+-either `size_t' or `ptrdiff_t'. Unix systems did define `size_t', in
+-`sys/types.h', but the definition was usually a signed type.
+-
+-
+-File: libc.info, Node: Data Type Measurements, Prev: Important Data Types,
Up: Language Features
+-
+-Data Type Measurements
+-======================
+-
+- Most of the time, if you choose the proper C data type for each
+-object in your program, you need not be concerned with just how it is
+-represented or how many bits it uses. When you do need such
+-information, the C language itself does not provide a way to get it.
+-The header files `limits.h' and `float.h' contain macros which give you
+-this information in full detail.
+-
+-* Menu:
+-
+-* Width of Type:: How many bits does an integer type hold?
+-* Range of Type:: What are the largest and smallest values
+- that an integer type can hold?
+-* Floating Type Macros:: Parameters that measure the floating point types.
+-* Structure Measurement:: Getting measurements on structure types.
+-
+-
+-File: libc.info, Node: Width of Type, Next: Range of Type, Up: Data Type
Measurements
+-
+-Computing the Width of an Integer Data Type
+--------------------------------------------
+-
+- The most common reason that a program needs to know how many bits
+-are in an integer type is for using an array of `long int' as a bit
+-vector. You can access the bit at index N with
+-
+- vector[N / LONGBITS] & (1 << (N % LONGBITS))
+-
+-provided you define `LONGBITS' as the number of bits in a `long int'.
+-
+- There is no operator in the C language that can give you the number
+-of bits in an integer data type. But you can compute it from the macro
+-`CHAR_BIT', defined in the header file `limits.h'.
+-
+-`CHAR_BIT'
+- This is the number of bits in a `char'--eight, on most systems.
+- The value has type `int'.
+-
+- You can compute the number of bits in any data type TYPE like this:
+-
+- sizeof (TYPE) * CHAR_BIT
+-
+-
+-File: libc.info, Node: Range of Type, Next: Floating Type Macros, Prev:
Width of Type, Up: Data Type Measurements
+-
+-Range of an Integer Type
+-------------------------
+-
+- Suppose you need to store an integer value which can range from zero
+-to one million. Which is the smallest type you can use? There is no
+-general rule; it depends on the C compiler and target machine. You can
+-use the `MIN' and `MAX' macros in `limits.h' to determine which type
+-will work.
+-
+- Each signed integer type has a pair of macros which give the smallest
+-and largest values that it can hold. Each unsigned integer type has one
+-such macro, for the maximum value; the minimum value is, of course,
+-zero.
+-
+- The values of these macros are all integer constant expressions. The
+-`MAX' and `MIN' macros for `char' and `short int' types have values of
+-type `int'. The `MAX' and `MIN' macros for the other types have values
+-of the same type described by the macro--thus, `ULONG_MAX' has type
+-`unsigned long int'.
+-
+-`SCHAR_MIN'
+- This is the minimum value that can be represented by a
+- `signed char'.
+-
+-`SCHAR_MAX'
+-`UCHAR_MAX'
+- These are the maximum values that can be represented by a
+- `signed char' and `unsigned char', respectively.
+-
+-`CHAR_MIN'
+- This is the minimum value that can be represented by a `char'.
+- It's equal to `SCHAR_MIN' if `char' is signed, or zero otherwise.
+-
+-`CHAR_MAX'
+- This is the maximum value that can be represented by a `char'.
+- It's equal to `SCHAR_MAX' if `char' is signed, or `UCHAR_MAX'
+- otherwise.
+-
+-`SHRT_MIN'
+- This is the minimum value that can be represented by a
+- `signed short int'. On most machines that the GNU C library runs
+- on, `short' integers are 16-bit quantities.
+-
+-`SHRT_MAX'
+-`USHRT_MAX'
+- These are the maximum values that can be represented by a
+- `signed short int' and `unsigned short int', respectively.
+-
+-`INT_MIN'
+- This is the minimum value that can be represented by a
+- `signed int'. On most machines that the GNU C system runs on, an
+- `int' is a 32-bit quantity.
+-
+-`INT_MAX'
+-`UINT_MAX'
+- These are the maximum values that can be represented by,
+- respectively, the type `signed int' and the type `unsigned int'.
+-
+-`LONG_MIN'
+- This is the minimum value that can be represented by a
+- `signed long int'. On most machines that the GNU C system runs
+- on, `long' integers are 32-bit quantities, the same size as `int'.
+-
+-`LONG_MAX'
+-`ULONG_MAX'
+- These are the maximum values that can be represented by a
+- `signed long int' and `unsigned long int', respectively.
+-
+-`LONG_LONG_MIN'
+- This is the minimum value that can be represented by a
+- `signed long long int'. On most machines that the GNU C system
+- runs on, `long long' integers are 64-bit quantities.
+-
+-`LONG_LONG_MAX'
+-`ULONG_LONG_MAX'
+- These are the maximum values that can be represented by a `signed
+- long long int' and `unsigned long long int', respectively.
+-
+-`WCHAR_MAX'
+- This is the maximum value that can be represented by a `wchar_t'.
+- *Note Wide Char Intro::.
+-
+- The header file `limits.h' also defines some additional constants
+-that parameterize various operating system and file system limits.
+-These constants are described in *Note System Configuration::.
+-
+-
+-File: libc.info, Node: Floating Type Macros, Next: Structure Measurement,
Prev: Range of Type, Up: Data Type Measurements
+-
+-Floating Type Macros
+---------------------
+-
+- The specific representation of floating point numbers varies from
+-machine to machine. Because floating point numbers are represented
+-internally as approximate quantities, algorithms for manipulating
+-floating point data often need to take account of the precise details of
+-the machine's floating point representation.
+-
+- Some of the functions in the C library itself need this information;
+-for example, the algorithms for printing and reading floating point
+-numbers (*note I/O on Streams::.) and for calculating trigonometric and
+-irrational functions (*note Mathematics::.) use it to avoid round-off
+-error and loss of accuracy. User programs that implement numerical
+-analysis techniques also often need this information in order to
+-minimize or compute error bounds.
+-
+- The header file `float.h' describes the format used by your machine.
+-
+-* Menu:
+-
+-* Floating Point Concepts:: Definitions of terminology.
+-* Floating Point Parameters:: Details of specific macros.
+-* IEEE Floating Point:: The measurements for one common
+- representation.
+-
+-
+-File: libc.info, Node: Floating Point Concepts, Next: Floating Point
Parameters, Up: Floating Type Macros
+-
+-Floating Point Representation Concepts
+-......................................
+-
+- This section introduces the terminology for describing floating point
+-representations.
+-
+- You are probably already familiar with most of these concepts in
+-terms of scientific or exponential notation for floating point numbers.
+-For example, the number `123456.0' could be expressed in exponential
+-notation as `1.23456e+05', a shorthand notation indicating that the
+-mantissa `1.23456' is multiplied by the base `10' raised to power `5'.
+-
+- More formally, the internal representation of a floating point number
+-can be characterized in terms of the following parameters:
+-
+- * The "sign" is either `-1' or `1'.
+-
+- * The "base" or "radix" for exponentiation, an integer greater than
+- `1'. This is a constant for a particular representation.
+-
+- * The "exponent" to which the base is raised. The upper and lower
+- bounds of the exponent value are constants for a particular
+- representation.
+-
+- Sometimes, in the actual bits representing the floating point
+- number, the exponent is "biased" by adding a constant to it, to
+- make it always be represented as an unsigned quantity. This is
+- only important if you have some reason to pick apart the bit
+- fields making up the floating point number by hand, which is
+- something for which the GNU library provides no support. So this
+- is ignored in the discussion that follows.
+-
+- * The "mantissa" or "significand", an unsigned integer which is a
+- part of each floating point number.
+-
+- * The "precision" of the mantissa. If the base of the representation
+- is B, then the precision is the number of base-B digits in the
+- mantissa. This is a constant for a particular representation.
+-
+- Many floating point representations have an implicit "hidden bit"
+- in the mantissa. This is a bit which is present virtually in the
+- mantissa, but not stored in memory because its value is always 1
+- in a normalized number. The precision figure (see above) includes
+- any hidden bits.
+-
+- Again, the GNU library provides no facilities for dealing with such
+- low-level aspects of the representation.
+-
+- The mantissa of a floating point number actually represents an
+-implicit fraction whose denominator is the base raised to the power of
+-the precision. Since the largest representable mantissa is one less
+-than this denominator, the value of the fraction is always strictly
+-less than `1'. The mathematical value of a floating point number is
+-then the product of this fraction, the sign, and the base raised to the
+-exponent.
+-
+- We say that the floating point number is "normalized" if the
+-fraction is at least `1/B', where B is the base. In other words, the
+-mantissa would be too large to fit if it were multiplied by the base.
+-Non-normalized numbers are sometimes called "denormal"; they contain
+-less precision than the representation normally can hold.
+-
+- If the number is not normalized, then you can subtract `1' from the
+-exponent while multiplying the mantissa by the base, and get another
+-floating point number with the same value. "Normalization" consists of
+-doing this repeatedly until the number is normalized. Two distinct
+-normalized floating point numbers cannot be equal in value.
+-
+- (There is an exception to this rule: if the mantissa is zero, it is
+-considered normalized. Another exception happens on certain machines
+-where the exponent is as small as the representation can hold. Then it
+-is impossible to subtract `1' from the exponent, so a number may be
+-normalized even if its fraction is less than `1/B'.)
+-
+-
+-File: libc.info, Node: Floating Point Parameters, Next: IEEE Floating
Point, Prev: Floating Point Concepts, Up: Floating Type Macros
+-
+-Floating Point Parameters
+-.........................
+-
+- These macro definitions can be accessed by including the header file
+-`float.h' in your program.
+-
+- Macro names starting with `FLT_' refer to the `float' type, while
+-names beginning with `DBL_' refer to the `double' type and names
+-beginning with `LDBL_' refer to the `long double' type. (Currently GCC
+-does not support `long double' as a distinct data type, so the values
+-for the `LDBL_' constants are equal to the corresponding constants for
+-the `double' type.)
+-
+- Of these macros, only `FLT_RADIX' is guaranteed to be a constant
+-expression. The other macros listed here cannot be reliably used in
+-places that require constant expressions, such as `#if' preprocessing
+-directives or in the dimensions of static arrays.
+-
+- Although the ISO C standard specifies minimum and maximum values for
+-most of these parameters, the GNU C implementation uses whatever values
+-describe the floating point representation of the target machine. So in
+-principle GNU C actually satisfies the ISO C requirements only if the
+-target machine is suitable. In practice, all the machines currently
+-supported are suitable.
+-
+-`FLT_ROUNDS'
+- This value characterizes the rounding mode for floating point
+- addition. The following values indicate standard rounding modes:
+-
+- `-1'
+- The mode is indeterminable.
+-
+- `0'
+- Rounding is towards zero.
+-
+- `1'
+- Rounding is to the nearest number.
+-
+- `2'
+- Rounding is towards positive infinity.
+-
+- `3'
+- Rounding is towards negative infinity.
+-
+- Any other value represents a machine-dependent nonstandard rounding
+- mode.
+-
+- On most machines, the value is `1', in accordance with the IEEE
+- standard for floating point.
+-
+- Here is a table showing how certain values round for each possible
+- value of `FLT_ROUNDS', if the other aspects of the representation
+- match the IEEE single-precision standard.
+-
+- 0 1 2 3
+- 1.00000003 1.0 1.0 1.00000012 1.0
+- 1.00000007 1.0 1.00000012 1.00000012 1.0
+- -1.00000003 -1.0 -1.0 -1.0 -1.00000012
+- -1.00000007 -1.0 -1.00000012 -1.0 -1.00000012
+-
+-`FLT_RADIX'
+- This is the value of the base, or radix, of exponent
+- representation. This is guaranteed to be a constant expression,
+- unlike the other macros described in this section. The value is 2
+- on all machines we know of except the IBM 360 and derivatives.
+-
+-`FLT_MANT_DIG'
+- This is the number of base-`FLT_RADIX' digits in the floating point
+- mantissa for the `float' data type. The following expression
+- yields `1.0' (even though mathematically it should not) due to the
+- limited number of mantissa digits:
+-
+- float radix = FLT_RADIX;
+-
+- 1.0f + 1.0f / radix / radix / ... / radix
+-
+- where `radix' appears `FLT_MANT_DIG' times.
+-
+-`DBL_MANT_DIG'
+-`LDBL_MANT_DIG'
+- This is the number of base-`FLT_RADIX' digits in the floating point
+- mantissa for the data types `double' and `long double',
+- respectively.
+-
+-`FLT_DIG'
+- This is the number of decimal digits of precision for the `float'
+- data type. Technically, if P and B are the precision and base
+- (respectively) for the representation, then the decimal precision
+- Q is the maximum number of decimal digits such that any floating
+- point number with Q base 10 digits can be rounded to a floating
+- point number with P base B digits and back again, without change
+- to the Q decimal digits.
+-
+- The value of this macro is supposed to be at least `6', to satisfy
+- ISO C.
+-
+-`DBL_DIG'
+-`LDBL_DIG'
+- These are similar to `FLT_DIG', but for the data types `double'
+- and `long double', respectively. The values of these macros are
+- supposed to be at least `10'.
+-
+-`FLT_MIN_EXP'
+- This is the smallest possible exponent value for type `float'.
+- More precisely, is the minimum negative integer such that the value
+- `FLT_RADIX' raised to this power minus 1 can be represented as a
+- normalized floating point number of type `float'.
+-
+-`DBL_MIN_EXP'
+-`LDBL_MIN_EXP'
+- These are similar to `FLT_MIN_EXP', but for the data types
+- `double' and `long double', respectively.
+-
+-`FLT_MIN_10_EXP'
+- This is the minimum negative integer such that `10' raised to this
+- power minus 1 can be represented as a normalized floating point
+- number of type `float'. This is supposed to be `-37' or even less.
+-
+-`DBL_MIN_10_EXP'
+-`LDBL_MIN_10_EXP'
+- These are similar to `FLT_MIN_10_EXP', but for the data types
+- `double' and `long double', respectively.
+-
+-`FLT_MAX_EXP'
+- This is the largest possible exponent value for type `float'. More
+- precisely, this is the maximum positive integer such that value
+- `FLT_RADIX' raised to this power minus 1 can be represented as a
+- floating point number of type `float'.
+-
+-`DBL_MAX_EXP'
+-`LDBL_MAX_EXP'
+- These are similar to `FLT_MAX_EXP', but for the data types
+- `double' and `long double', respectively.
+-
+-`FLT_MAX_10_EXP'
+- This is the maximum positive integer such that `10' raised to this
+- power minus 1 can be represented as a normalized floating point
+- number of type `float'. This is supposed to be at least `37'.
+-
+-`DBL_MAX_10_EXP'
+-`LDBL_MAX_10_EXP'
+- These are similar to `FLT_MAX_10_EXP', but for the data types
+- `double' and `long double', respectively.
+-
+-`FLT_MAX'
+- The value of this macro is the maximum number representable in type
+- `float'. It is supposed to be at least `1E+37'. The value has
+- type `float'.
+-
+- The smallest representable number is `- FLT_MAX'.
+-
+-`DBL_MAX'
+-`LDBL_MAX'
+- These are similar to `FLT_MAX', but for the data types `double'
+- and `long double', respectively. The type of the macro's value is
+- the same as the type it describes.
+-
+-`FLT_MIN'
+- The value of this macro is the minimum normalized positive floating
+- point number that is representable in type `float'. It is supposed
+- to be no more than `1E-37'.
+-
+-`DBL_MIN'
+-`LDBL_MIN'
+- These are similar to `FLT_MIN', but for the data types `double'
+- and `long double', respectively. The type of the macro's value is
+- the same as the type it describes.
+-
+-`FLT_EPSILON'
+- This is the minimum positive floating point number of type `float'
+- such that `1.0 + FLT_EPSILON != 1.0' is true. It's supposed to be
+- no greater than `1E-5'.
+-
+-`DBL_EPSILON'
+-`LDBL_EPSILON'
+- These are similar to `FLT_EPSILON', but for the data types
+- `double' and `long double', respectively. The type of the macro's
+- value is the same as the type it describes. The values are not
+- supposed to be greater than `1E-9'.
+-
+-
+-File: libc.info, Node: IEEE Floating Point, Prev: Floating Point
Parameters, Up: Floating Type Macros
+-
+-IEEE Floating Point
+-...................
+-
+- Here is an example showing how the floating type measurements come
+-out for the most common floating point representation, specified by the
+-`IEEE Standard for Binary Floating Point Arithmetic (ANSI/IEEE Std
+-754-1985)'. Nearly all computers designed since the 1980s use this
+-format.
+-
+- The IEEE single-precision float representation uses a base of 2.
+-There is a sign bit, a mantissa with 23 bits plus one hidden bit (so
+-the total precision is 24 base-2 digits), and an 8-bit exponent that
+-can represent values in the range -125 to 128, inclusive.
+-
+- So, for an implementation that uses this representation for the
+-`float' data type, appropriate values for the corresponding parameters
+-are:
+-
+- FLT_RADIX 2
+- FLT_MANT_DIG 24
+- FLT_DIG 6
+- FLT_MIN_EXP -125
+- FLT_MIN_10_EXP -37
+- FLT_MAX_EXP 128
+- FLT_MAX_10_EXP +38
+- FLT_MIN 1.17549435E-38F
+- FLT_MAX 3.40282347E+38F
+- FLT_EPSILON 1.19209290E-07F
+-
+- Here are the values for the `double' data type:
+-
+- DBL_MANT_DIG 53
+- DBL_DIG 15
+- DBL_MIN_EXP -1021
+- DBL_MIN_10_EXP -307
+- DBL_MAX_EXP 1024
+- DBL_MAX_10_EXP 308
+- DBL_MAX 1.7976931348623157E+308
+- DBL_MIN 2.2250738585072014E-308
+- DBL_EPSILON 2.2204460492503131E-016
+-
+-
+-File: libc.info, Node: Structure Measurement, Prev: Floating Type Macros,
Up: Data Type Measurements
+-
+-Structure Field Offset Measurement
+-----------------------------------
+-
+- You can use `offsetof' to measure the location within a structure
+-type of a particular structure member.
+-
+- - Macro: size_t offsetof (TYPE, MEMBER)
+- This expands to a integer constant expression that is the offset
+- of the structure member named MEMBER in a the structure type TYPE.
+- For example, `offsetof (struct s, elem)' is the offset, in bytes,
+- of the member `elem' in a `struct s'.
+-
+- This macro won't work if MEMBER is a bit field; you get an error
+- from the C compiler in that case.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-28
glibc-2.0.1/manual/libc.info-28
+--- ../glibc-2.0.1/manual/libc.info-28 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-28 1970-01-01 01:00:00.000000000 +0100
+@@ -1,3847 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+- This file documents the GNU C library.
+-
+- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+- Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+- Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+- Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: Library Summary, Next: Maintenance, Prev: Language
Features, Up: Top
+-
+-Summary of Library Facilities
+-*****************************
+-
+- This appendix is a complete list of the facilities declared within
+-the header files supplied with the GNU C library. Each entry also
+-lists the standard or other source from which each facility is derived,
+-and tells you where in the manual you can find more information about
+-how to use it.
+-
+-`void abort (void)'
+- `stdlib.h' (ISO): *Note Aborting a Program::.
+-
+-`int abs (int NUMBER)'
+- `stdlib.h' (ISO): *Note Absolute Value::.
+-
+-`int accept (int SOCKET, struct sockaddr *ADDR, size_t *LENGTH-PTR)'
+- `sys/socket.h' (BSD): *Note Accepting Connections::.
+-
+-`int access (const char *FILENAME, int HOW)'
+- `unistd.h' (POSIX.1): *Note Testing File Access::.
+-
+-`double acosh (double X)'
+- `math.h' (BSD): *Note Hyperbolic Functions::.
+-
+-`double acos (double X)'
+- `math.h' (ISO): *Note Inverse Trig Functions::.
+-
+-`int adjtime (const struct timeval *DELTA, struct timeval *OLDDELTA)'
+- `sys/time.h' (BSD): *Note High-Resolution Calendar::.
+-
+-`AF_FILE'
+- `sys/socket.h' (GNU): *Note Address Formats::.
+-
+-`AF_INET'
+- `sys/socket.h' (BSD): *Note Address Formats::.
+-
+-`AF_UNIX'
+- `sys/socket.h' (BSD): *Note Address Formats::.
+-
+-`AF_UNSPEC'
+- `sys/socket.h' (BSD): *Note Address Formats::.
+-
+-`unsigned int alarm (unsigned int SECONDS)'
+- `unistd.h' (POSIX.1): *Note Setting an Alarm::.
+-
+-`void * alloca (size_t SIZE);'
+- `stdlib.h' (GNU, BSD): *Note Variable Size Automatic::.
+-
+-`tcflag_t ALTWERASE'
+- `termios.h' (BSD): *Note Local Modes::.
+-
+-`int ARG_MAX'
+- `limits.h' (POSIX.1): *Note General Limits::.
+-
+-`char * asctime (const struct tm *BROKENTIME)'
+- `time.h' (ISO): *Note Formatting Date and Time::.
+-
+-`double asinh (double X)'
+- `math.h' (BSD): *Note Hyperbolic Functions::.
+-
+-`double asin (double X)'
+- `math.h' (ISO): *Note Inverse Trig Functions::.
+-
+-`int asprintf (char **PTR, const char *TEMPLATE, ...)'
+- `stdio.h' (GNU): *Note Dynamic Output::.
+-
+-`void assert (int EXPRESSION)'
+- `assert.h' (ISO): *Note Consistency Checking::.
+-
+-`void assert_perror (int ERRNUM)'
+- `assert.h' (GNU): *Note Consistency Checking::.
+-
+-`double atan2 (double Y, double X)'
+- `math.h' (ISO): *Note Inverse Trig Functions::.
+-
+-`double atanh (double X)'
+- `math.h' (BSD): *Note Hyperbolic Functions::.
+-
+-`double atan (double X)'
+- `math.h' (ISO): *Note Inverse Trig Functions::.
+-
+-`int atexit (void (*FUNCTION) (void))'
+- `stdlib.h' (ISO): *Note Cleanups on Exit::.
+-
+-`double atof (const char *STRING)'
+- `stdlib.h' (ISO): *Note Parsing of Floats::.
+-
+-`int atoi (const char *STRING)'
+- `stdlib.h' (ISO): *Note Parsing of Integers::.
+-
+-`long int atol (const char *STRING)'
+- `stdlib.h' (ISO): *Note Parsing of Integers::.
+-
+-`B0'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B110'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B1200'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B134'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B150'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B1800'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B19200'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B200'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B2400'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B300'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B38400'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B4800'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B50'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B600'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B75'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`B9600'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`int BC_BASE_MAX'
+- `limits.h' (POSIX.2): *Note Utility Limits::.
+-
+-`int BC_DIM_MAX'
+- `limits.h' (POSIX.2): *Note Utility Limits::.
+-
+-`int BC_DIM_MAX'
+- `limits.h' (POSIX.2): *Note Utility Limits::.
+-
+-`int bcmp (const void *A1, const void *A2, size_t SIZE)'
+- `string.h' (BSD): *Note String/Array Comparison::.
+-
+-`void * bcopy (void *FROM, const void *TO, size_t SIZE)'
+- `string.h' (BSD): *Note Copying and Concatenation::.
+-
+-`int BC_SCALE_MAX'
+- `limits.h' (POSIX.2): *Note Utility Limits::.
+-
+-`int BC_STRING_MAX'
+- `limits.h' (POSIX.2): *Note Utility Limits::.
+-
+-`int bind (int SOCKET, struct sockaddr *ADDR, size_t LENGTH)'
+- `sys/socket.h' (BSD): *Note Setting Address::.
+-
+-`tcflag_t BRKINT'
+- `termios.h' (POSIX.1): *Note Input Modes::.
+-
+-`_BSD_SOURCE'
+- (GNU): *Note Feature Test Macros::.
+-
+-`void * bsearch (const void *KEY, const void *ARRAY, size_t COUNT, size_t
SIZE, comparison_fn_t COMPARE)'
+- `stdlib.h' (ISO): *Note Array Search Function::.
+-
+-`int BUFSIZ'
+- `stdio.h' (ISO): *Note Controlling Buffering::.
+-
+-`void * bzero (void *BLOCK, size_t SIZE)'
+- `string.h' (BSD): *Note Copying and Concatenation::.
+-
+-`double cabs (struct { double real, imag; } Z)'
+- `math.h' (BSD): *Note Absolute Value::.
+-
+-`void * calloc (size_t COUNT, size_t ELTSIZE)'
+- `malloc.h', `stdlib.h' (ISO): *Note Allocating Cleared Space::.
+-
+-`double cbrt (double X)'
+- `math.h' (BSD): *Note Exponents and Logarithms::.
+-
+-`cc_t'
+- `termios.h' (POSIX.1): *Note Mode Data Types::.
+-
+-`tcflag_t CCTS_OFLOW'
+- `termios.h' (BSD): *Note Control Modes::.
+-
+-`double ceil (double X)'
+- `math.h' (ISO): *Note Rounding and Remainders::.
+-
+-`speed_t cfgetispeed (const struct termios *TERMIOS-P)'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`speed_t cfgetospeed (const struct termios *TERMIOS-P)'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`int cfmakeraw (struct termios *TERMIOS-P)'
+- `termios.h' (BSD): *Note Noncanonical Input::.
+-
+-`void cfree (void *PTR)'
+- `stdlib.h' (Sun): *Note Freeing after Malloc::.
+-
+-`int cfsetispeed (struct termios *TERMIOS-P, speed_t SPEED)'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`int cfsetospeed (struct termios *TERMIOS-P, speed_t SPEED)'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`int cfsetspeed (struct termios *TERMIOS-P, speed_t SPEED)'
+- `termios.h' (BSD): *Note Line Speed::.
+-
+-`CHAR_BIT'
+- `limits.h' (ISO): *Note Width of Type::.
+-
+-`CHAR_MAX'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`CHAR_MIN'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`int chdir (const char *FILENAME)'
+- `unistd.h' (POSIX.1): *Note Working Directory::.
+-
+-`int CHILD_MAX'
+- `limits.h' (POSIX.1): *Note General Limits::.
+-
+-`int chmod (const char *FILENAME, mode_t MODE)'
+- `sys/stat.h' (POSIX.1): *Note Setting Permissions::.
+-
+-`int chown (const char *FILENAME, uid_t OWNER, gid_t GROUP)'
+- `unistd.h' (POSIX.1): *Note File Owner::.
+-
+-`tcflag_t CIGNORE'
+- `termios.h' (BSD): *Note Control Modes::.
+-
+-`void clearerr (FILE *STREAM)'
+- `stdio.h' (ISO): *Note EOF and Errors::.
+-
+-`int CLK_TCK'
+- `time.h' (POSIX.1): *Note Basic CPU Time::.
+-
+-`tcflag_t CLOCAL'
+- `termios.h' (POSIX.1): *Note Control Modes::.
+-
+-`clock_t clock (void)'
+- `time.h' (ISO): *Note Basic CPU Time::.
+-
+-`int CLOCKS_PER_SEC'
+- `time.h' (ISO): *Note Basic CPU Time::.
+-
+-`clock_t'
+- `time.h' (ISO): *Note Basic CPU Time::.
+-
+-`int closedir (DIR *DIRSTREAM)'
+- `dirent.h' (POSIX.1): *Note Reading/Closing Directory::.
+-
+-`int close (int FILEDES)'
+- `unistd.h' (POSIX.1): *Note Opening and Closing Files::.
+-
+-`int COLL_WEIGHTS_MAX'
+- `limits.h' (POSIX.2): *Note Utility Limits::.
+-
+-`size_t confstr (int PARAMETER, char *BUF, size_t LEN)'
+- `unistd.h' (POSIX.2): *Note String Parameters::.
+-
+-`int connect (int SOCKET, struct sockaddr *ADDR, size_t LENGTH)'
+- `sys/socket.h' (BSD): *Note Connecting::.
+-
+-`cookie_close_function'
+- `stdio.h' (GNU): *Note Hook Functions::.
+-
+-`cookie_io_functions_t'
+- `stdio.h' (GNU): *Note Streams and Cookies::.
+-
+-`cookie_read_function'
+- `stdio.h' (GNU): *Note Hook Functions::.
+-
+-`cookie_seek_function'
+- `stdio.h' (GNU): *Note Hook Functions::.
+-
+-`cookie_write_function'
+- `stdio.h' (GNU): *Note Hook Functions::.
+-
+-`double copysign (double VALUE, double SIGN)'
+- `math.h' (BSD): *Note Normalization Functions::.
+-
+-`double cosh (double X)'
+- `math.h' (ISO): *Note Hyperbolic Functions::.
+-
+-`double cos (double X)'
+- `math.h' (ISO): *Note Trig Functions::.
+-
+-`tcflag_t CREAD'
+- `termios.h' (POSIX.1): *Note Control Modes::.
+-
+-`int creat (const char *FILENAME, mode_t MODE)'
+- `fcntl.h' (POSIX.1): *Note Opening and Closing Files::.
+-
+-`tcflag_t CRTS_IFLOW'
+- `termios.h' (BSD): *Note Control Modes::.
+-
+-`tcflag_t CS5'
+- `termios.h' (POSIX.1): *Note Control Modes::.
+-
+-`tcflag_t CS6'
+- `termios.h' (POSIX.1): *Note Control Modes::.
+-
+-`tcflag_t CS7'
+- `termios.h' (POSIX.1): *Note Control Modes::.
+-
+-`tcflag_t CS8'
+- `termios.h' (POSIX.1): *Note Control Modes::.
+-
+-`tcflag_t CSIZE'
+- `termios.h' (POSIX.1): *Note Control Modes::.
+-
+-`_CS_PATH'
+- `unistd.h' (POSIX.2): *Note String Parameters::.
+-
+-`tcflag_t CSTOPB'
+- `termios.h' (POSIX.1): *Note Control Modes::.
+-
+-`char * ctermid (char *STRING)'
+- `stdio.h' (POSIX.1): *Note Identifying the Terminal::.
+-
+-`char * ctime (const time_t *TIME)'
+- `time.h' (ISO): *Note Formatting Date and Time::.
+-
+-`char * cuserid (char *STRING)'
+- `stdio.h' (POSIX.1): *Note Who Logged In::.
+-
+-`int daylight'
+- `time.h' (SVID): *Note Time Zone Functions::.
+-
+-`DBL_DIG'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`DBL_EPSILON'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`DBL_MANT_DIG'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`DBL_MAX_10_EXP'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`DBL_MAX_EXP'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`DBL_MAX'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`DBL_MIN_10_EXP'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`DBL_MIN_EXP'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`DBL_MIN'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`dev_t'
+- `sys/types.h' (POSIX.1): *Note Attribute Meanings::.
+-
+-`double difftime (time_t TIME1, time_t TIME0)'
+- `time.h' (ISO): *Note Simple Calendar Time::.
+-
+-`DIR'
+- `dirent.h' (POSIX.1): *Note Opening a Directory::.
+-
+-`div_t div (int NUMERATOR, int DENOMINATOR)'
+- `stdlib.h' (ISO): *Note Integer Division::.
+-
+-`div_t'
+- `stdlib.h' (ISO): *Note Integer Division::.
+-
+-`double drem (double NUMERATOR, double DENOMINATOR)'
+- `math.h' (BSD): *Note Rounding and Remainders::.
+-
+-`int dup2 (int OLD, int NEW)'
+- `unistd.h' (POSIX.1): *Note Duplicating Descriptors::.
+-
+-`int dup (int OLD)'
+- `unistd.h' (POSIX.1): *Note Duplicating Descriptors::.
+-
+-`int E2BIG'
+- `errno.h' (POSIX.1: Argument list too long): *Note Error Codes::.
+-
+-`int EACCES'
+- `errno.h' (POSIX.1: Permission denied): *Note Error Codes::.
+-
+-`int EADDRINUSE'
+- `errno.h' (BSD: Address already in use): *Note Error Codes::.
+-
+-`int EADDRNOTAVAIL'
+- `errno.h' (BSD: Cannot assign requested address): *Note Error
+- Codes::.
+-
+-`int EADV'
+- `errno.h' (Linux???: Advertise error): *Note Error Codes::.
+-
+-`int EAFNOSUPPORT'
+- `errno.h' (BSD: Address family not supported by protocol): *Note
+- Error Codes::.
+-
+-`int EAGAIN'
+- `errno.h' (POSIX.1: Resource temporarily unavailable): *Note
+- Error Codes::.
+-
+-`int EALREADY'
+- `errno.h' (BSD: Operation already in progress): *Note Error
+- Codes::.
+-
+-`int EAUTH'
+- `errno.h' (BSD: Authentication error): *Note Error Codes::.
+-
+-`int EBACKGROUND'
+- `errno.h' (GNU: Inappropriate operation for background process):
+- *Note Error Codes::.
+-
+-`int EBADE'
+- `errno.h' (Linux???: Invalid exchange): *Note Error Codes::.
+-
+-`int EBADFD'
+- `errno.h' (Linux???: File descriptor in bad state): *Note Error
+- Codes::.
+-
+-`int EBADF'
+- `errno.h' (POSIX.1: Bad file descriptor): *Note Error Codes::.
+-
+-`int EBADMSG'
+- `errno.h' (XOPEN: Bad message): *Note Error Codes::.
+-
+-`int EBADR'
+- `errno.h' (Linux???: Invalid request descriptor): *Note Error
+- Codes::.
+-
+-`int EBADRPC'
+- `errno.h' (BSD: RPC struct is bad): *Note Error Codes::.
+-
+-`int EBADRQC'
+- `errno.h' (Linux???: Invalid request code): *Note Error Codes::.
+-
+-`int EBADSLT'
+- `errno.h' (Linux???: Invalid slot): *Note Error Codes::.
+-
+-`int EBFONT'
+- `errno.h' (Linux???: Bad font file format): *Note Error Codes::.
+-
+-`int EBUSY'
+- `errno.h' (POSIX.1: Device or resource busy): *Note Error Codes::.
+-
+-`int ECHILD'
+- `errno.h' (POSIX.1: No child processes): *Note Error Codes::.
+-
+-`tcflag_t ECHOCTL'
+- `termios.h' (BSD): *Note Local Modes::.
+-
+-`tcflag_t ECHOE'
+- `termios.h' (POSIX.1): *Note Local Modes::.
+-
+-`tcflag_t ECHO'
+- `termios.h' (POSIX.1): *Note Local Modes::.
+-
+-`tcflag_t ECHOKE'
+- `termios.h' (BSD): *Note Local Modes::.
+-
+-`tcflag_t ECHOK'
+- `termios.h' (POSIX.1): *Note Local Modes::.
+-
+-`tcflag_t ECHONL'
+- `termios.h' (POSIX.1): *Note Local Modes::.
+-
+-`tcflag_t ECHOPRT'
+- `termios.h' (BSD): *Note Local Modes::.
+-
+-`int ECHRNG'
+- `errno.h' (Linux???: Channel number out of range): *Note Error
+- Codes::.
+-
+-`int ECOMM'
+- `errno.h' (Linux???: Communication error on send): *Note Error
+- Codes::.
+-
+-`int ECONNABORTED'
+- `errno.h' (BSD: Software caused connection abort): *Note Error
+- Codes::.
+-
+-`int ECONNREFUSED'
+- `errno.h' (BSD: Connection refused): *Note Error Codes::.
+-
+-`int ECONNRESET'
+- `errno.h' (BSD: Connection reset by peer): *Note Error Codes::.
+-
+-`int EDEADLK'
+- `errno.h' (POSIX.1: Resource deadlock avoided): *Note Error
+- Codes::.
+-
+-`int EDEADLOCK'
+- `errno.h' (Linux???: File locking deadlock error): *Note Error
+- Codes::.
+-
+-`int EDESTADDRREQ'
+- `errno.h' (BSD: Destination address required): *Note Error
+- Codes::.
+-
+-`int EDIED'
+- `errno.h' (GNU: Translator died): *Note Error Codes::.
+-
+-`int ED'
+- `errno.h' (GNU: ?): *Note Error Codes::.
+-
+-`int EDOM'
+- `errno.h' (ISO: Numerical argument out of domain): *Note Error
+- Codes::.
+-
+-`int EDOTDOT'
+- `errno.h' (Linux???: RFS specific error): *Note Error Codes::.
+-
+-`int EDQUOT'
+- `errno.h' (BSD: Disc quota exceeded): *Note Error Codes::.
+-
+-`int EEXIST'
+- `errno.h' (POSIX.1: File exists): *Note Error Codes::.
+-
+-`int EFAULT'
+- `errno.h' (POSIX.1: Bad address): *Note Error Codes::.
+-
+-`int EFBIG'
+- `errno.h' (POSIX.1: File too large): *Note Error Codes::.
+-
+-`int EFTYPE'
+- `errno.h' (BSD: Inappropriate file type or format): *Note Error
+- Codes::.
+-
+-`int EGRATUITOUS'
+- `errno.h' (GNU: Gratuitous error): *Note Error Codes::.
+-
+-`int EGREGIOUS'
+- `errno.h' (GNU: You really blew it this time): *Note Error
+- Codes::.
+-
+-`int EHOSTDOWN'
+- `errno.h' (BSD: Host is down): *Note Error Codes::.
+-
+-`int EHOSTUNREACH'
+- `errno.h' (BSD: No route to host): *Note Error Codes::.
+-
+-`int EIDRM'
+- `errno.h' (XOPEN: Identifier removed): *Note Error Codes::.
+-
+-`int EIEIO'
+- `errno.h' (GNU: Computer bought the farm): *Note Error Codes::.
+-
+-`int EILSEQ'
+- `errno.h' (ISO: Invalid or incomplete multibyte or wide
+- character): *Note Error Codes::.
+-
+-`int EINPROGRESS'
+- `errno.h' (BSD: Operation now in progress): *Note Error Codes::.
+-
+-`int EINTR'
+- `errno.h' (POSIX.1: Interrupted system call): *Note Error Codes::.
+-
+-`int EINVAL'
+- `errno.h' (POSIX.1: Invalid argument): *Note Error Codes::.
+-
+-`int EIO'
+- `errno.h' (POSIX.1: Input/output error): *Note Error Codes::.
+-
+-`int EISCONN'
+- `errno.h' (BSD: Transport endpoint is already connected): *Note
+- Error Codes::.
+-
+-`int EISDIR'
+- `errno.h' (POSIX.1: Is a directory): *Note Error Codes::.
+-
+-`int EISNAM'
+- `errno.h' (Linux???: Is a named type file): *Note Error Codes::.
+-
+-`int EL2HLT'
+- `errno.h' (Linux???: Level 2 halted): *Note Error Codes::.
+-
+-`int EL2NSYNC'
+- `errno.h' (Linux???: Level 2 not synchronized): *Note Error
+- Codes::.
+-
+-`int EL3HLT'
+- `errno.h' (Linux???: Level 3 halted): *Note Error Codes::.
+-
+-`int EL3RST'
+- `errno.h' (Linux???: Level 3 reset): *Note Error Codes::.
+-
+-`int ELIBACC'
+- `errno.h' (Linux???: Can not access a needed shared library):
+- *Note Error Codes::.
+-
+-`int ELIBBAD'
+- `errno.h' (Linux???: Accessing a corrupted shared library): *Note
+- Error Codes::.
+-
+-`int ELIBEXEC'
+- `errno.h' (Linux???: Cannot exec a shared library directly):
+- *Note Error Codes::.
+-
+-`int ELIBMAX'
+- `errno.h' (Linux???: Attempting to link in too many shared
+- libraries): *Note Error Codes::.
+-
+-`int ELIBSCN'
+- `errno.h' (Linux???: .lib section in a.out corrupted): *Note
+- Error Codes::.
+-
+-`int ELNRNG'
+- `errno.h' (Linux???: Link number out of range): *Note Error
+- Codes::.
+-
+-`int ELOOP'
+- `errno.h' (BSD: Too many levels of symbolic links): *Note Error
+- Codes::.
+-
+-`int EMFILE'
+- `errno.h' (POSIX.1: Too many open files): *Note Error Codes::.
+-
+-`int EMLINK'
+- `errno.h' (POSIX.1: Too many links): *Note Error Codes::.
+-
+-`int EMSGSIZE'
+- `errno.h' (BSD: Message too long): *Note Error Codes::.
+-
+-`int EMULTIHOP'
+- `errno.h' (XOPEN: Multihop attempted): *Note Error Codes::.
+-
+-`int ENAMETOOLONG'
+- `errno.h' (POSIX.1: File name too long): *Note Error Codes::.
+-
+-`int ENAVAIL'
+- `errno.h' (Linux???: No XENIX semaphores available): *Note Error
+- Codes::.
+-
+-`void endgrent (void)'
+- `grp.h' (SVID, BSD): *Note Scanning All Groups::.
+-
+-`void endhostent ()'
+- `netdb.h' (BSD): *Note Host Names::.
+-
+-`void endnetent (void)'
+- `netdb.h' (BSD): *Note Networks Database::.
+-
+-`void endnetgrent (void)'
+- `netdb.h' (netdb.h): *Note Lookup Netgroup::.
+-
+-`void endprotoent (void)'
+- `netdb.h' (BSD): *Note Protocols Database::.
+-
+-`void endpwent (void)'
+- `pwd.h' (SVID, BSD): *Note Scanning All Users::.
+-
+-`void endservent (void)'
+- `netdb.h' (BSD): *Note Services Database::.
+-
+-`int ENEEDAUTH'
+- `errno.h' (BSD: Need authenticator): *Note Error Codes::.
+-
+-`int ENETDOWN'
+- `errno.h' (BSD: Network is down): *Note Error Codes::.
+-
+-`int ENETRESET'
+- `errno.h' (BSD: Network dropped connection on reset): *Note Error
+- Codes::.
+-
+-`int ENETUNREACH'
+- `errno.h' (BSD: Network is unreachable): *Note Error Codes::.
+-
+-`int ENFILE'
+- `errno.h' (POSIX.1: Too many open files in system): *Note Error
+- Codes::.
+-
+-`int ENOANO'
+- `errno.h' (Linux???: No anode): *Note Error Codes::.
+-
+-`int ENOBUFS'
+- `errno.h' (BSD: No buffer space available): *Note Error Codes::.
+-
+-`int ENOCSI'
+- `errno.h' (Linux???: No CSI structure available): *Note Error
+- Codes::.
+-
+-`int ENODATA'
+- `errno.h' (XOPEN: No data available): *Note Error Codes::.
+-
+-`int ENODEV'
+- `errno.h' (POSIX.1: Operation not supported by device): *Note
+- Error Codes::.
+-
+-`int ENOENT'
+- `errno.h' (POSIX.1: No such file or directory): *Note Error
+- Codes::.
+-
+-`int ENOEXEC'
+- `errno.h' (POSIX.1: Exec format error): *Note Error Codes::.
+-
+-`int ENOLCK'
+- `errno.h' (POSIX.1: No locks available): *Note Error Codes::.
+-
+-`int ENOLINK'
+- `errno.h' (XOPEN: Link has been severed): *Note Error Codes::.
+-
+-`int ENOMEM'
+- `errno.h' (POSIX.1: Cannot allocate memory): *Note Error Codes::.
+-
+-`int ENOMSG'
+- `errno.h' (XOPEN: No message of desired type): *Note Error
+- Codes::.
+-
+-`int ENONET'
+- `errno.h' (Linux???: Machine is not on the network): *Note Error
+- Codes::.
+-
+-`int ENOPKG'
+- `errno.h' (Linux???: Package not installed): *Note Error Codes::.
+-
+-`int ENOPROTOOPT'
+- `errno.h' (BSD: Protocol not available): *Note Error Codes::.
+-
+-`int ENOSPC'
+- `errno.h' (POSIX.1: No space left on device): *Note Error Codes::.
+-
+-`int ENOSR'
+- `errno.h' (XOPEN: Out of streams resources): *Note Error Codes::.
+-
+-`int ENOSTR'
+- `errno.h' (XOPEN: Device not a stream): *Note Error Codes::.
+-
+-`int ENOSYS'
+- `errno.h' (POSIX.1: Function not implemented): *Note Error
+- Codes::.
+-
+-`int ENOTBLK'
+- `errno.h' (BSD: Block device required): *Note Error Codes::.
+-
+-`int ENOTCONN'
+- `errno.h' (BSD: Transport endpoint is not connected): *Note Error
+- Codes::.
+-
+-`int ENOTDIR'
+- `errno.h' (POSIX.1: Not a directory): *Note Error Codes::.
+-
+-`int ENOTEMPTY'
+- `errno.h' (POSIX.1: Directory not empty): *Note Error Codes::.
+-
+-`int ENOTNAM'
+- `errno.h' (Linux???: Not a XENIX named type file): *Note Error
+- Codes::.
+-
+-`int ENOTSOCK'
+- `errno.h' (BSD: Socket operation on non-socket): *Note Error
+- Codes::.
+-
+-`int ENOTTY'
+- `errno.h' (POSIX.1: Inappropriate ioctl for device): *Note Error
+- Codes::.
+-
+-`int ENOTUNIQ'
+- `errno.h' (Linux???: Name not unique on network): *Note Error
+- Codes::.
+-
+-`char ** environ'
+- `unistd.h' (POSIX.1): *Note Environment Access::.
+-
+-`int ENXIO'
+- `errno.h' (POSIX.1: Device not configured): *Note Error Codes::.
+-
+-`int EOF'
+- `stdio.h' (ISO): *Note EOF and Errors::.
+-
+-`int EOPNOTSUPP'
+- `errno.h' (BSD: Operation not supported): *Note Error Codes::.
+-
+-`int EOVERFLOW'
+- `errno.h' (XOPEN: Value too large for defined data type): *Note
+- Error Codes::.
+-
+-`int EPERM'
+- `errno.h' (POSIX.1: Operation not permitted): *Note Error Codes::.
+-
+-`int EPFNOSUPPORT'
+- `errno.h' (BSD: Protocol family not supported): *Note Error
+- Codes::.
+-
+-`int EPIPE'
+- `errno.h' (POSIX.1: Broken pipe): *Note Error Codes::.
+-
+-`int EPROCLIM'
+- `errno.h' (BSD: Too many processes): *Note Error Codes::.
+-
+-`int EPROCUNAVAIL'
+- `errno.h' (BSD: RPC bad procedure for program): *Note Error
+- Codes::.
+-
+-`int EPROGMISMATCH'
+- `errno.h' (BSD: RPC program version wrong): *Note Error Codes::.
+-
+-`int EPROGUNAVAIL'
+- `errno.h' (BSD: RPC program not available): *Note Error Codes::.
+-
+-`int EPROTO'
+- `errno.h' (XOPEN: Protocol error): *Note Error Codes::.
+-
+-`int EPROTONOSUPPORT'
+- `errno.h' (BSD: Protocol not supported): *Note Error Codes::.
+-
+-`int EPROTOTYPE'
+- `errno.h' (BSD: Protocol wrong type for socket): *Note Error
+- Codes::.
+-
+-`int EQUIV_CLASS_MAX'
+- `limits.h' (POSIX.2): *Note Utility Limits::.
+-
+-`int ERANGE'
+- `errno.h' (ISO: Numerical result out of range): *Note Error
+- Codes::.
+-
+-`int EREMCHG'
+- `errno.h' (Linux???: Remote address changed): *Note Error Codes::.
+-
+-`int EREMOTEIO'
+- `errno.h' (Linux???: Remote I/O error): *Note Error Codes::.
+-
+-`int EREMOTE'
+- `errno.h' (BSD: Object is remote): *Note Error Codes::.
+-
+-`int ERESTART'
+- `errno.h' (Linux???: Interrupted system call should be restarted):
+- *Note Error Codes::.
+-
+-`int EROFS'
+- `errno.h' (POSIX.1: Read-only file system): *Note Error Codes::.
+-
+-`int ERPCMISMATCH'
+- `errno.h' (BSD: RPC version wrong): *Note Error Codes::.
+-
+-`volatile int errno'
+- `errno.h' (ISO): *Note Checking for Errors::.
+-
+-`int ESHUTDOWN'
+- `errno.h' (BSD: Cannot send after transport endpoint shutdown):
+- *Note Error Codes::.
+-
+-`int ESOCKTNOSUPPORT'
+- `errno.h' (BSD: Socket type not supported): *Note Error Codes::.
+-
+-`int ESPIPE'
+- `errno.h' (POSIX.1: Illegal seek): *Note Error Codes::.
+-
+-`int ESRCH'
+- `errno.h' (POSIX.1: No such process): *Note Error Codes::.
+-
+-`int ESRMNT'
+- `errno.h' (Linux???: Srmount error): *Note Error Codes::.
+-
+-`int ESTALE'
+- `errno.h' (BSD: Stale NFS file handle): *Note Error Codes::.
+-
+-`int ESTRPIPE'
+- `errno.h' (Linux???: Streams pipe error): *Note Error Codes::.
+-
+-`int ETIMEDOUT'
+- `errno.h' (BSD: Connection timed out): *Note Error Codes::.
+-
+-`int ETIME'
+- `errno.h' (XOPEN: Timer expired): *Note Error Codes::.
+-
+-`int ETOOMANYREFS'
+- `errno.h' (BSD: Too many references: cannot splice): *Note Error
+- Codes::.
+-
+-`int ETXTBSY'
+- `errno.h' (BSD: Text file busy): *Note Error Codes::.
+-
+-`int EUCLEAN'
+- `errno.h' (Linux???: Structure needs cleaning): *Note Error
+- Codes::.
+-
+-`int EUNATCH'
+- `errno.h' (Linux???: Protocol driver not attached): *Note Error
+- Codes::.
+-
+-`int EUSERS'
+- `errno.h' (BSD: Too many users): *Note Error Codes::.
+-
+-`int EWOULDBLOCK'
+- `errno.h' (BSD: Operation would block): *Note Error Codes::.
+-
+-`int EXDEV'
+- `errno.h' (POSIX.1: Invalid cross-device link): *Note Error
+- Codes::.
+-
+-`int execle (const char *FILENAME, const char *ARG0, char *const ENV[], ...)'
+- `unistd.h' (POSIX.1): *Note Executing a File::.
+-
+-`int execl (const char *FILENAME, const char *ARG0, ...)'
+- `unistd.h' (POSIX.1): *Note Executing a File::.
+-
+-`int execlp (const char *FILENAME, const char *ARG0, ...)'
+- `unistd.h' (POSIX.1): *Note Executing a File::.
+-
+-`int execve (const char *FILENAME, char *const ARGV[], char *const ENV[])'
+- `unistd.h' (POSIX.1): *Note Executing a File::.
+-
+-`int execv (const char *FILENAME, char *const ARGV[])'
+- `unistd.h' (POSIX.1): *Note Executing a File::.
+-
+-`int execvp (const char *FILENAME, char *const ARGV[])'
+- `unistd.h' (POSIX.1): *Note Executing a File::.
+-
+-`int EXFULL'
+- `errno.h' (Linux???: Exchange full): *Note Error Codes::.
+-
+-`int EXIT_FAILURE'
+- `stdlib.h' (ISO): *Note Exit Status::.
+-
+-`void _exit (int STATUS)'
+- `unistd.h' (POSIX.1): *Note Termination Internals::.
+-
+-`void exit (int STATUS)'
+- `stdlib.h' (ISO): *Note Normal Termination::.
+-
+-`int EXIT_SUCCESS'
+- `stdlib.h' (ISO): *Note Exit Status::.
+-
+-`double exp (double X)'
+- `math.h' (ISO): *Note Exponents and Logarithms::.
+-
+-`double expm1 (double X)'
+- `math.h' (BSD): *Note Exponents and Logarithms::.
+-
+-`int EXPR_NEST_MAX'
+- `limits.h' (POSIX.2): *Note Utility Limits::.
+-
+-`double fabs (double NUMBER)'
+- `math.h' (ISO): *Note Absolute Value::.
+-
+-`int fchmod (int FILEDES, int MODE)'
+- `sys/stat.h' (BSD): *Note Setting Permissions::.
+-
+-`int fchown (int FILEDES, int OWNER, int GROUP)'
+- `unistd.h' (BSD): *Note File Owner::.
+-
+-`int fclean (FILE *STREAM)'
+- `stdio.h' (GNU): *Note Cleaning Streams::.
+-
+-`int fcloseall (void)'
+- `stdio.h' (GNU): *Note Closing Streams::.
+-
+-`int fclose (FILE *STREAM)'
+- `stdio.h' (ISO): *Note Closing Streams::.
+-
+-`int fcntl (int FILEDES, int COMMAND, ...)'
+- `fcntl.h' (POSIX.1): *Note Control Operations::.
+-
+-`int FD_CLOEXEC'
+- `fcntl.h' (POSIX.1): *Note Descriptor Flags::.
+-
+-`void FD_CLR (int FILEDES, fd_set *SET)'
+- `sys/types.h' (BSD): *Note Waiting for I/O::.
+-
+-`int FD_ISSET (int FILEDES, fd_set *SET)'
+- `sys/types.h' (BSD): *Note Waiting for I/O::.
+-
+-`FILE * fdopen (int FILEDES, const char *OPENTYPE)'
+- `stdio.h' (POSIX.1): *Note Descriptors and Streams::.
+-
+-`void FD_SET (int FILEDES, fd_set *SET)'
+- `sys/types.h' (BSD): *Note Waiting for I/O::.
+-
+-`fd_set'
+- `sys/types.h' (BSD): *Note Waiting for I/O::.
+-
+-`int FD_SETSIZE'
+- `sys/types.h' (BSD): *Note Waiting for I/O::.
+-
+-`int F_DUPFD'
+- `fcntl.h' (POSIX.1): *Note Duplicating Descriptors::.
+-
+-`void FD_ZERO (fd_set *SET)'
+- `sys/types.h' (BSD): *Note Waiting for I/O::.
+-
+-`int feof (FILE *STREAM)'
+- `stdio.h' (ISO): *Note EOF and Errors::.
+-
+-`int ferror (FILE *STREAM)'
+- `stdio.h' (ISO): *Note EOF and Errors::.
+-
+-`int fflush (FILE *STREAM)'
+- `stdio.h' (ISO): *Note Flushing Buffers::.
+-
+-`int fgetc (FILE *STREAM)'
+- `stdio.h' (ISO): *Note Character Input::.
+-
+-`int F_GETFD'
+- `fcntl.h' (POSIX.1): *Note Descriptor Flags::.
+-
+-`int F_GETFL'
+- `fcntl.h' (POSIX.1): *Note Getting File Status Flags::.
+-
+-`struct group * fgetgrent (FILE *STREAM)'
+- `grp.h' (SVID): *Note Scanning All Groups::.
+-
+-`int fgetgrent_r (FILE *STREAM, struct group *RESULT_BUF, char *BUFFER,
size_t BUFLEN, struct group **RESULT)'
+- `grp.h' (GNU): *Note Scanning All Groups::.
+-
+-`int F_GETLK'
+- `fcntl.h' (POSIX.1): *Note File Locks::.
+-
+-`int F_GETOWN'
+- `fcntl.h' (BSD): *Note Interrupt Input::.
+-
+-`int fgetpos (FILE *STREAM, fpos_t *POSITION)'
+- `stdio.h' (ISO): *Note Portable Positioning::.
+-
+-`struct passwd * fgetpwent (FILE *STREAM)'
+- `pwd.h' (SVID): *Note Scanning All Users::.
+-
+-`int fgetpwent_r (FILE *STREAM, struct passwd *RESULT_BUF, char *BUFFER,
size_t BUFLEN, struct passwd **RESULT)'
+- `pwd.h' (GNU): *Note Scanning All Users::.
+-
+-`char * fgets (char *S, int COUNT, FILE *STREAM)'
+- `stdio.h' (ISO): *Note Line Input::.
+-
+-`FILE'
+- `stdio.h' (ISO): *Note Streams::.
+-
+-`int FILENAME_MAX'
+- `stdio.h' (ISO): *Note Limits for Files::.
+-
+-`int fileno (FILE *STREAM)'
+- `stdio.h' (POSIX.1): *Note Descriptors and Streams::.
+-
+-`int finite (double X)'
+- `math.h' (BSD): *Note Predicates on Floats::.
+-
+-`double floor (double X)'
+- `math.h' (ISO): *Note Rounding and Remainders::.
+-
+-`FLT_DIG'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`FLT_EPSILON'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`FLT_MANT_DIG'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`FLT_MAX_10_EXP'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`FLT_MAX_EXP'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`FLT_MAX'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`FLT_MIN_10_EXP'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`FLT_MIN_EXP'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`FLT_MIN'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`FLT_RADIX'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`FLT_ROUNDS'
+- `float.h' (ISO): *Note Floating Point Parameters::.
+-
+-`tcflag_t FLUSHO'
+- `termios.h' (BSD): *Note Local Modes::.
+-
+-`FILE * fmemopen (void *BUF, size_t SIZE, const char *OPENTYPE)'
+- `stdio.h' (GNU): *Note String Streams::.
+-
+-`double fmod (double NUMERATOR, double DENOMINATOR)'
+- `math.h' (ISO): *Note Rounding and Remainders::.
+-
+-`int fnmatch (const char *PATTERN, const char *STRING, int FLAGS)'
+- `fnmatch.h' (POSIX.2): *Note Wildcard Matching::.
+-
+-`FNM_CASEFOLD'
+- `fnmatch.h' (GNU): *Note Wildcard Matching::.
+-
+-`FNM_FILE_NAME'
+- `fnmatch.h' (GNU): *Note Wildcard Matching::.
+-
+-`FNM_LEADING_DIR'
+- `fnmatch.h' (GNU): *Note Wildcard Matching::.
+-
+-`FNM_NOESCAPE'
+- `fnmatch.h' (POSIX.2): *Note Wildcard Matching::.
+-
+-`FNM_PATHNAME'
+- `fnmatch.h' (POSIX.2): *Note Wildcard Matching::.
+-
+-`FNM_PERIOD'
+- `fnmatch.h' (POSIX.2): *Note Wildcard Matching::.
+-
+-`int F_OK'
+- `unistd.h' (POSIX.1): *Note Testing File Access::.
+-
+-`FILE * fopencookie (void *COOKIE, const char *OPENTYPE,
cookie_io_functions_t IO-FUNCTIONS)'
+- `stdio.h' (GNU): *Note Streams and Cookies::.
+-
+-`FILE * fopen (const char *FILENAME, const char *OPENTYPE)'
+- `stdio.h' (ISO): *Note Opening Streams::.
+-
+-`int FOPEN_MAX'
+- `stdio.h' (ISO): *Note Opening Streams::.
+-
+-`pid_t fork (void)'
+- `unistd.h' (POSIX.1): *Note Creating a Process::.
+-
+-`long int fpathconf (int FILEDES, int PARAMETER)'
+- `unistd.h' (POSIX.1): *Note Pathconf::.
+-
+-`FPE_DECOVF_TRAP'
+- `signal.h' (BSD): *Note Program Error Signals::.
+-
+-`FPE_FLTDIV_FAULT'
+- `signal.h' (BSD): *Note Program Error Signals::.
+-
+-`FPE_FLTDIV_TRAP'
+- `signal.h' (BSD): *Note Program Error Signals::.
+-
+-`FPE_FLTOVF_FAULT'
+- `signal.h' (BSD): *Note Program Error Signals::.
+-
+-`FPE_FLTOVF_TRAP'
+- `signal.h' (BSD): *Note Program Error Signals::.
+-
+-`FPE_FLTUND_FAULT'
+- `signal.h' (BSD): *Note Program Error Signals::.
+-
+-`FPE_FLTUND_TRAP'
+- `signal.h' (BSD): *Note Program Error Signals::.
+-
+-`FPE_INTDIV_TRAP'
+- `signal.h' (BSD): *Note Program Error Signals::.
+-
+-`FPE_INTOVF_TRAP'
+- `signal.h' (BSD): *Note Program Error Signals::.
+-
+-`FPE_SUBRNG_TRAP'
+- `signal.h' (BSD): *Note Program Error Signals::.
+-
+-`fpos_t'
+- `stdio.h' (ISO): *Note Portable Positioning::.
+-
+-`int fprintf (FILE *STREAM, const char *TEMPLATE, ...)'
+- `stdio.h' (ISO): *Note Formatted Output Functions::.
+-
+-`int fputc (int C, FILE *STREAM)'
+- `stdio.h' (ISO): *Note Simple Output::.
+-
+-`int fputs (const char *S, FILE *STREAM)'
+- `stdio.h' (ISO): *Note Simple Output::.
+-
+-`F_RDLCK'
+- `fcntl.h' (POSIX.1): *Note File Locks::.
+-
+-`size_t fread (void *DATA, size_t SIZE, size_t COUNT, FILE *STREAM)'
+- `stdio.h' (ISO): *Note Block Input/Output::.
+-
+-`__free_hook'
+- `malloc.h' (GNU): *Note Hooks for Malloc::.
+-
+-`void free (void *PTR)'
+- `malloc.h', `stdlib.h' (ISO): *Note Freeing after Malloc::.
+-
+-`FILE * freopen (const char *FILENAME, const char *OPENTYPE, FILE *STREAM)'
+- `stdio.h' (ISO): *Note Opening Streams::.
+-
+-`double frexp (double VALUE, int *EXPONENT)'
+- `math.h' (ISO): *Note Normalization Functions::.
+-
+-`int fscanf (FILE *STREAM, const char *TEMPLATE, ...)'
+- `stdio.h' (ISO): *Note Formatted Input Functions::.
+-
+-`int fseek (FILE *STREAM, long int OFFSET, int WHENCE)'
+- `stdio.h' (ISO): *Note File Positioning::.
+-
+-`int F_SETFD'
+- `fcntl.h' (POSIX.1): *Note Descriptor Flags::.
+-
+-`int F_SETFL'
+- `fcntl.h' (POSIX.1): *Note Getting File Status Flags::.
+-
+-`int F_SETLK'
+- `fcntl.h' (POSIX.1): *Note File Locks::.
+-
+-`int F_SETLKW'
+- `fcntl.h' (POSIX.1): *Note File Locks::.
+-
+-`int F_SETOWN'
+- `fcntl.h' (BSD): *Note Interrupt Input::.
+-
+-`int fsetpos (FILE *STREAM, const fpos_t POSITION)'
+- `stdio.h' (ISO): *Note Portable Positioning::.
+-
+-`int fstat (int FILEDES, struct stat *BUF)'
+- `sys/stat.h' (POSIX.1): *Note Reading Attributes::.
+-
+-`long int ftell (FILE *STREAM)'
+- `stdio.h' (ISO): *Note File Positioning::.
+-
+-`F_UNLCK'
+- `fcntl.h' (POSIX.1): *Note File Locks::.
+-
+-`size_t fwrite (const void *DATA, size_t SIZE, size_t COUNT, FILE *STREAM)'
+- `stdio.h' (ISO): *Note Block Input/Output::.
+-
+-`F_WRLCK'
+- `fcntl.h' (POSIX.1): *Note File Locks::.
+-
+-`int getchar (void)'
+- `stdio.h' (ISO): *Note Character Input::.
+-
+-`int getc (FILE *STREAM)'
+- `stdio.h' (ISO): *Note Character Input::.
+-
+-`char * getcwd (char *BUFFER, size_t SIZE)'
+- `unistd.h' (POSIX.1): *Note Working Directory::.
+-
+-`ssize_t getdelim (char **LINEPTR, size_t *N, int DELIMITER, FILE *STREAM)'
+- `stdio.h' (GNU): *Note Line Input::.
+-
+-`gid_t getegid (void)'
+- `unistd.h' (POSIX.1): *Note Reading Persona::.
+-
+-`char * getenv (const char *NAME)'
+- `stdlib.h' (ISO): *Note Environment Access::.
+-
+-`uid_t geteuid (void)'
+- `unistd.h' (POSIX.1): *Note Reading Persona::.
+-
+-`gid_t getgid (void)'
+- `unistd.h' (POSIX.1): *Note Reading Persona::.
+-
+-`struct group * getgrent (void)'
+- `grp.h' (SVID, BSD): *Note Scanning All Groups::.
+-
+-`int getgrent_r (struct group *RESULT_BUF, char *BUFFER, size_t BUFLEN,
struct group **RESULT)'
+- `grp.h' (GNU): *Note Scanning All Groups::.
+-
+-`struct group * getgrgid (gid_t GID)'
+- `grp.h' (POSIX.1): *Note Lookup Group::.
+-
+-`int getgrgid_r (gid_t GID, struct group *RESULT_BUF, char *BUFFER, size_t
BUFLEN, struct group **RESULT)'
+- `grp.h' (POSIX.1c): *Note Lookup Group::.
+-
+-`struct group * getgrnam (const char *NAME)'
+- `grp.h' (SVID, BSD): *Note Lookup Group::.
+-
+-`int getgrnam_r (const char *NAME, struct group *RESULT_BUF, char *BUFFER,
size_t BUFLEN, struct group **RESULT)'
+- `grp.h' (POSIX.1c): *Note Lookup Group::.
+-
+-`int getgroups (int COUNT, gid_t *GROUPS)'
+- `unistd.h' (POSIX.1): *Note Reading Persona::.
+-
+-`struct hostent * gethostbyaddr (const char *ADDR, int LENGTH, int FORMAT)'
+- `netdb.h' (BSD): *Note Host Names::.
+-
+-`struct hostent * gethostbyname (const char *NAME)'
+- `netdb.h' (BSD): *Note Host Names::.
+-
+-`struct hostent * gethostent ()'
+- `netdb.h' (BSD): *Note Host Names::.
+-
+-`long int gethostid (void)'
+- `unistd.h' (BSD): *Note Host Identification::.
+-
+-`int gethostname (char *NAME, size_t SIZE)'
+- `unistd.h' (BSD): *Note Host Identification::.
+-
+-`int getitimer (int WHICH, struct itimerval *OLD)'
+- `sys/time.h' (BSD): *Note Setting an Alarm::.
+-
+-`ssize_t getline (char **LINEPTR, size_t *N, FILE *STREAM)'
+- `stdio.h' (GNU): *Note Line Input::.
+-
+-`char * getlogin (void)'
+- `unistd.h' (POSIX.1): *Note Who Logged In::.
+-
+-`struct netent * getnetbyaddr (long NET, int TYPE)'
+- `netdb.h' (BSD): *Note Networks Database::.
+-
+-`struct netent * getnetbyname (const char *NAME)'
+- `netdb.h' (BSD): *Note Networks Database::.
+-
+-`struct netent * getnetent (void)'
+- `netdb.h' (BSD): *Note Networks Database::.
+-
+-`int getnetgrent (char **HOSTP, char **USERP, char **DOMAINP)'
+- `netdb.h' (netdb.h): *Note Lookup Netgroup::.
+-
+-`int getnetgrent_r (char **HOSTP, char **USERP, char **DOMAINP, char *BUFFER,
int BUFLEN)'
+- `netdb.h' (netdb.h): *Note Lookup Netgroup::.
+-
+-`int getopt (int ARGC, char **ARGV, const char *OPTIONS)'
+- `unistd.h' (POSIX.2): *Note Parsing Options::.
+-
+-`int getopt_long (int ARGC, char **ARGV, const char *SHORTOPTS, struct option
*LONGOPTS, int *INDEXPTR)'
+- `getopt.h' (GNU): *Note Long Options::.
+-
+-`int getpeername (int SOCKET, struct sockaddr *ADDR, size_t *LENGTH-PTR)'
+- `sys/socket.h' (BSD): *Note Who is Connected::.
+-
+-`pid_t getpgrp (pid_t PID)'
+- `unistd.h' (BSD): *Note Process Group Functions::.
+-
+-`pid_t getpgrp (void)'
+- `unistd.h' (POSIX.1): *Note Process Group Functions::.
+-
+-`pid_t getpid (void)'
+- `unistd.h' (POSIX.1): *Note Process Identification::.
+-
+-`pid_t getppid (void)'
+- `unistd.h' (POSIX.1): *Note Process Identification::.
+-
+-`int getpriority (int CLASS, int ID)'
+- `sys/resource.h' (BSD): *Note Priority::.
+-
+-`struct protoent * getprotobyname (const char *NAME)'
+- `netdb.h' (BSD): *Note Protocols Database::.
+-
+-`struct protoent * getprotobynumber (int PROTOCOL)'
+- `netdb.h' (BSD): *Note Protocols Database::.
+-
+-`struct protoent * getprotoent (void)'
+- `netdb.h' (BSD): *Note Protocols Database::.
+-
+-`struct passwd * getpwent (void)'
+- `pwd.h' (POSIX.1): *Note Scanning All Users::.
+-
+-`int getpwent_r (struct passwd *RESULT_BUF, char *BUFFER, int BUFLEN, struct
passwd **RESULT)'
+- `pwd.h' (GNU): *Note Scanning All Users::.
+-
+-`struct passwd * getpwnam (const char *NAME)'
+- `pwd.h' (POSIX.1): *Note Lookup User::.
+-
+-`int getpwnam_r (const char *NAME, struct passwd *RESULT_BUF, char *BUFFER,
size_t BUFLEN, struct passwd **RESULT)'
+- `pwd.h' (POSIX.1c): *Note Lookup User::.
+-
+-`struct passwd * getpwuid (uid_t UID)'
+- `pwd.h' (POSIX.1): *Note Lookup User::.
+-
+-`int getpwuid_r (uid_t UID, struct passwd *RESULT_BUF, char *BUFFER, size_t
BUFLEN, struct passwd **RESULT)'
+- `pwd.h' (POSIX.1c): *Note Lookup User::.
+-
+-`int getrlimit (int RESOURCE, struct rlimit *RLP)'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`int getrusage (int PROCESSES, struct rusage *RUSAGE)'
+- `sys/resource.h' (BSD): *Note Resource Usage::.
+-
+-`struct servent * getservbyname (const char *NAME, const char *PROTO)'
+- `netdb.h' (BSD): *Note Services Database::.
+-
+-`struct servent * getservbyport (int PORT, const char *PROTO)'
+- `netdb.h' (BSD): *Note Services Database::.
+-
+-`struct servent * getservent (void)'
+- `netdb.h' (BSD): *Note Services Database::.
+-
+-`char * gets (char *S)'
+- `stdio.h' (ISO): *Note Line Input::.
+-
+-`int getsockname (int SOCKET, struct sockaddr *ADDR, size_t *LENGTH-PTR)'
+- `sys/socket.h' (BSD): *Note Reading Address::.
+-
+-`int getsockopt (int SOCKET, int LEVEL, int OPTNAME, void *OPTVAL, size_t
*OPTLEN-PTR)'
+- `sys/socket.h' (BSD): *Note Socket Option Functions::.
+-
+-`int getsubopt (char **OPTIONP, const char* const *TOKENS, char **VALUEP)'
+- `stdlib.h' (stdlib.h): *Note Suboptions::.
+-
+-`int gettimeofday (struct timeval *TP, struct timezone *TZP)'
+- `sys/time.h' (BSD): *Note High-Resolution Calendar::.
+-
+-`uid_t getuid (void)'
+- `unistd.h' (POSIX.1): *Note Reading Persona::.
+-
+-`mode_t getumask (void)'
+- `sys/stat.h' (GNU): *Note Setting Permissions::.
+-
+-`char * getwd (char *BUFFER)'
+- `unistd.h' (BSD): *Note Working Directory::.
+-
+-`int getw (FILE *STREAM)'
+- `stdio.h' (SVID): *Note Character Input::.
+-
+-`gid_t'
+- `sys/types.h' (POSIX.1): *Note Reading Persona::.
+-
+-`GLOB_ABORTED'
+- `glob.h' (POSIX.2): *Note Calling Glob::.
+-
+-`GLOB_APPEND'
+- `glob.h' (POSIX.2): *Note Flags for Globbing::.
+-
+-`GLOB_DOOFFS'
+- `glob.h' (POSIX.2): *Note Flags for Globbing::.
+-
+-`GLOB_ERR'
+- `glob.h' (POSIX.2): *Note Flags for Globbing::.
+-
+-`int glob (const char *PATTERN, int FLAGS, int (*ERRFUNC) (const char
*FILENAME, int ERROR-CODE), glob_t *VECTOR-PTR)'
+- `glob.h' (POSIX.2): *Note Calling Glob::.
+-
+-`GLOB_MARK'
+- `glob.h' (POSIX.2): *Note Flags for Globbing::.
+-
+-`GLOB_NOCHECK'
+- `glob.h' (POSIX.2): *Note Flags for Globbing::.
+-
+-`GLOB_NOESCAPE'
+- `glob.h' (POSIX.2): *Note Flags for Globbing::.
+-
+-`GLOB_NOMATCH'
+- `glob.h' (POSIX.2): *Note Calling Glob::.
+-
+-`GLOB_NOSORT'
+- `glob.h' (POSIX.2): *Note Flags for Globbing::.
+-
+-`GLOB_NOSPACE'
+- `glob.h' (POSIX.2): *Note Calling Glob::.
+-
+-`glob_t'
+- `glob.h' (POSIX.2): *Note Calling Glob::.
+-
+-`struct tm * gmtime (const time_t *TIME)'
+- `time.h' (ISO): *Note Broken-down Time::.
+-
+-`_GNU_SOURCE'
+- (GNU): *Note Feature Test Macros::.
+-
+-`int gsignal (int SIGNUM)'
+- `signal.h' (SVID): *Note Signaling Yourself::.
+-
+-`HOST_NOT_FOUND'
+- `netdb.h' (BSD): *Note Host Names::.
+-
+-`unsigned long int htonl (unsigned long int HOSTLONG)'
+- `netinet/in.h' (BSD): *Note Byte Order::.
+-
+-`unsigned short int htons (unsigned short int HOSTSHORT)'
+- `netinet/in.h' (BSD): *Note Byte Order::.
+-
+-`float HUGE_VALf'
+- `math.h' (GNU): *Note Domain and Range Errors::.
+-
+-`double HUGE_VAL'
+- `math.h' (ISO): *Note Domain and Range Errors::.
+-
+-`long double HUGE_VALl'
+- `math.h' (GNU): *Note Domain and Range Errors::.
+-
+-`tcflag_t HUPCL'
+- `termios.h' (POSIX.1): *Note Control Modes::.
+-
+-`double hypot (double X, double Y)'
+- `math.h' (BSD): *Note Exponents and Logarithms::.
+-
+-`tcflag_t ICANON'
+- `termios.h' (POSIX.1): *Note Local Modes::.
+-
+-`tcflag_t ICRNL'
+- `termios.h' (POSIX.1): *Note Input Modes::.
+-
+-`tcflag_t IEXTEN'
+- `termios.h' (POSIX.1): *Note Local Modes::.
+-
+-`tcflag_t IGNBRK'
+- `termios.h' (POSIX.1): *Note Input Modes::.
+-
+-`tcflag_t IGNCR'
+- `termios.h' (POSIX.1): *Note Input Modes::.
+-
+-`tcflag_t IGNPAR'
+- `termios.h' (POSIX.1): *Note Input Modes::.
+-
+-`tcflag_t IMAXBEL'
+- `termios.h' (BSD): *Note Input Modes::.
+-
+-`unsigned long int INADDR_ANY'
+- `netinet/in.h' (BSD): *Note Host Address Data Type::.
+-
+-`unsigned long int INADDR_BROADCAST'
+- `netinet/in.h' (BSD): *Note Host Address Data Type::.
+-
+-`unsigned long int INADDR_LOOPBACK'
+- `netinet/in.h' (BSD): *Note Host Address Data Type::.
+-
+-`unsigned long int INADDR_NONE'
+- `netinet/in.h' (BSD): *Note Host Address Data Type::.
+-
+-`char * index (const char *STRING, int C)'
+- `string.h' (BSD): *Note Search Functions::.
+-
+-`unsigned long int inet_addr (const char *NAME)'
+- `arpa/inet.h' (BSD): *Note Host Address Functions::.
+-
+-`int inet_aton (const char *NAME, struct in_addr *ADDR)'
+- `arpa/inet.h' (BSD): *Note Host Address Functions::.
+-
+-`int inet_lnaof (struct in_addr ADDR)'
+- `arpa/inet.h' (BSD): *Note Host Address Functions::.
+-
+-`struct in_addr inet_makeaddr (int NET, int LOCAL)'
+- `arpa/inet.h' (BSD): *Note Host Address Functions::.
+-
+-`int inet_netof (struct in_addr ADDR)'
+- `arpa/inet.h' (BSD): *Note Host Address Functions::.
+-
+-`unsigned long int inet_network (const char *NAME)'
+- `arpa/inet.h' (BSD): *Note Host Address Functions::.
+-
+-`char * inet_ntoa (struct in_addr ADDR)'
+- `arpa/inet.h' (BSD): *Note Host Address Functions::.
+-
+-`double infnan (int ERROR)'
+- `math.h' (BSD): *Note Predicates on Floats::.
+-
+-`int initgroups (const char *USER, gid_t GID)'
+- `grp.h' (BSD): *Note Setting Groups::.
+-
+-`void * initstate (unsigned int SEED, void *STATE, size_t SIZE)'
+- `stdlib.h' (BSD): *Note BSD Random::.
+-
+-`tcflag_t INLCR'
+- `termios.h' (POSIX.1): *Note Input Modes::.
+-
+-`int innetgr (const char *NETGROUP, const char *HOST, const char *USER, const
char *DOMAIN)'
+- `netdb.h' (netdb.h): *Note Netgroup Membership::.
+-
+-`ino_t'
+- `sys/types.h' (POSIX.1): *Note Attribute Meanings::.
+-
+-`tcflag_t INPCK'
+- `termios.h' (POSIX.1): *Note Input Modes::.
+-
+-`int RLIM_INFINITY'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`INT_MAX'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`INT_MIN'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`int _IOFBF'
+- `stdio.h' (ISO): *Note Controlling Buffering::.
+-
+-`int _IOLBF'
+- `stdio.h' (ISO): *Note Controlling Buffering::.
+-
+-`int _IONBF'
+- `stdio.h' (ISO): *Note Controlling Buffering::.
+-
+-`int IPPORT_RESERVED'
+- `netinet/in.h' (BSD): *Note Ports::.
+-
+-`int IPPORT_USERRESERVED'
+- `netinet/in.h' (BSD): *Note Ports::.
+-
+-`int isalnum (int C)'
+- `ctype.h' (ISO): *Note Classification of Characters::.
+-
+-`int isalpha (int C)'
+- `ctype.h' (ISO): *Note Classification of Characters::.
+-
+-`int isascii (int C)'
+- `ctype.h' (SVID, BSD): *Note Classification of Characters::.
+-
+-`int isatty (int FILEDES)'
+- `unistd.h' (POSIX.1): *Note Is It a Terminal::.
+-
+-`int isblank (int C)'
+- `ctype.h' (GNU): *Note Classification of Characters::.
+-
+-`int iscntrl (int C)'
+- `ctype.h' (ISO): *Note Classification of Characters::.
+-
+-`int isdigit (int C)'
+- `ctype.h' (ISO): *Note Classification of Characters::.
+-
+-`int isgraph (int C)'
+- `ctype.h' (ISO): *Note Classification of Characters::.
+-
+-`tcflag_t ISIG'
+- `termios.h' (POSIX.1): *Note Local Modes::.
+-
+-`int isinf (double X)'
+- `math.h' (BSD): *Note Predicates on Floats::.
+-
+-`int islower (int C)'
+- `ctype.h' (ISO): *Note Classification of Characters::.
+-
+-`int isnan (double X)'
+- `math.h' (BSD): *Note Predicates on Floats::.
+-
+-`int isprint (int C)'
+- `ctype.h' (ISO): *Note Classification of Characters::.
+-
+-`int ispunct (int C)'
+- `ctype.h' (ISO): *Note Classification of Characters::.
+-
+-`int isspace (int C)'
+- `ctype.h' (ISO): *Note Classification of Characters::.
+-
+-`tcflag_t ISTRIP'
+- `termios.h' (POSIX.1): *Note Input Modes::.
+-
+-`int isupper (int C)'
+- `ctype.h' (ISO): *Note Classification of Characters::.
+-
+-`int isxdigit (int C)'
+- `ctype.h' (ISO): *Note Classification of Characters::.
+-
+-`ITIMER_PROF'
+- `sys/time.h' (BSD): *Note Setting an Alarm::.
+-
+-`ITIMER_REAL'
+- `sys/time.h' (BSD): *Note Setting an Alarm::.
+-
+-`ITIMER_VIRTUAL'
+- `sys/time.h' (BSD): *Note Setting an Alarm::.
+-
+-`tcflag_t IXANY'
+- `termios.h' (BSD): *Note Input Modes::.
+-
+-`tcflag_t IXOFF'
+- `termios.h' (POSIX.1): *Note Input Modes::.
+-
+-`tcflag_t IXON'
+- `termios.h' (POSIX.1): *Note Input Modes::.
+-
+-`jmp_buf'
+- `setjmp.h' (ISO): *Note Non-Local Details::.
+-
+-`int kill (pid_t PID, int SIGNUM)'
+- `signal.h' (POSIX.1): *Note Signaling Another Process::.
+-
+-`int killpg (int PGID, int SIGNUM)'
+- `signal.h' (BSD): *Note Signaling Another Process::.
+-
+-`long int labs (long int NUMBER)'
+- `stdlib.h' (ISO): *Note Absolute Value::.
+-
+-`LANG'
+- `locale.h' (ISO): *Note Locale Categories::.
+-
+-`LC_ALL'
+- `locale.h' (ISO): *Note Locale Categories::.
+-
+-`LC_COLLATE'
+- `locale.h' (ISO): *Note Locale Categories::.
+-
+-`LC_CTYPE'
+- `locale.h' (ISO): *Note Locale Categories::.
+-
+-`LC_MESSAGES'
+- `locale.h' (XOPEN): *Note Locale Categories::.
+-
+-`LC_MONETARY'
+- `locale.h' (ISO): *Note Locale Categories::.
+-
+-`LC_NUMERIC'
+- `locale.h' (ISO): *Note Locale Categories::.
+-
+-`int L_ctermid'
+- `stdio.h' (POSIX.1): *Note Identifying the Terminal::.
+-
+-`LC_TIME'
+- `locale.h' (ISO): *Note Locale Categories::.
+-
+-`int L_cuserid'
+- `stdio.h' (POSIX.1): *Note Who Logged In::.
+-
+-`double ldexp (double VALUE, int EXPONENT)'
+- `math.h' (ISO): *Note Normalization Functions::.
+-
+-`ldiv_t ldiv (long int NUMERATOR, long int DENOMINATOR)'
+- `stdlib.h' (ISO): *Note Integer Division::.
+-
+-`ldiv_t'
+- `stdlib.h' (ISO): *Note Integer Division::.
+-
+-`L_INCR'
+- `sys/file.h' (BSD): *Note File Positioning::.
+-
+-`int LINE_MAX'
+- `limits.h' (POSIX.2): *Note Utility Limits::.
+-
+-`int link (const char *OLDNAME, const char *NEWNAME)'
+- `unistd.h' (POSIX.1): *Note Hard Links::.
+-
+-`int LINK_MAX'
+- `limits.h' (POSIX.1): *Note Limits for Files::.
+-
+-`int listen (int SOCKET, unsigned int N)'
+- `sys/socket.h' (BSD): *Note Listening::.
+-
+-`struct lconv * localeconv (void)'
+- `locale.h' (ISO): *Note Numeric Formatting::.
+-
+-`struct tm * localtime (const time_t *TIME)'
+- `time.h' (ISO): *Note Broken-down Time::.
+-
+-`double log10 (double X)'
+- `math.h' (ISO): *Note Exponents and Logarithms::.
+-
+-`double log1p (double X)'
+- `math.h' (BSD): *Note Exponents and Logarithms::.
+-
+-`double logb (double X)'
+- `math.h' (BSD): *Note Normalization Functions::.
+-
+-`double log (double X)'
+- `math.h' (ISO): *Note Exponents and Logarithms::.
+-
+-`void longjmp (jmp_buf STATE, int VALUE)'
+- `setjmp.h' (ISO): *Note Non-Local Details::.
+-
+-`LONG_LONG_MAX'
+- `limits.h' (GNU): *Note Range of Type::.
+-
+-`LONG_LONG_MIN'
+- `limits.h' (GNU): *Note Range of Type::.
+-
+-`LONG_MAX'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`LONG_MIN'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`off_t lseek (int FILEDES, off_t OFFSET, int WHENCE)'
+- `unistd.h' (POSIX.1): *Note File Position Primitive::.
+-
+-`L_SET'
+- `sys/file.h' (BSD): *Note File Positioning::.
+-
+-`int lstat (const char *FILENAME, struct stat *BUF)'
+- `sys/stat.h' (BSD): *Note Reading Attributes::.
+-
+-`int L_tmpnam'
+- `stdio.h' (ISO): *Note Temporary Files::.
+-
+-`L_XTND'
+- `sys/file.h' (BSD): *Note File Positioning::.
+-
+-`__malloc_hook'
+- `malloc.h' (GNU): *Note Hooks for Malloc::.
+-
+-`void * malloc (size_t SIZE)'
+- `malloc.h', `stdlib.h' (ISO): *Note Basic Allocation::.
+-
+-`int MAX_CANON'
+- `limits.h' (POSIX.1): *Note Limits for Files::.
+-
+-`int MAX_INPUT'
+- `limits.h' (POSIX.1): *Note Limits for Files::.
+-
+-`int MAXNAMLEN'
+- `dirent.h' (BSD): *Note Limits for Files::.
+-
+-`int MB_CUR_MAX'
+- `stdlib.h' (ISO): *Note Multibyte Char Intro::.
+-
+-`int mblen (const char *STRING, size_t SIZE)'
+- `stdlib.h' (ISO): *Note Length of Char::.
+-
+-`int MB_LEN_MAX'
+- `limits.h' (ISO): *Note Multibyte Char Intro::.
+-
+-`size_t mbstowcs (wchar_t *WSTRING, const char *STRING, size_t SIZE)'
+- `stdlib.h' (ISO): *Note Wide String Conversion::.
+-
+-`int mbtowc (wchar_t *RESULT, const char *STRING, size_t SIZE)'
+- `stdlib.h' (ISO): *Note Converting One Char::.
+-
+-`int mcheck (void (*ABORTFN) (enum mcheck_status STATUS))'
+- `malloc.h' (GNU): *Note Heap Consistency Checking::.
+-
+-`tcflag_t MDMBUF'
+- `termios.h' (BSD): *Note Control Modes::.
+-
+-`void * memalign (size_t BOUNDARY, size_t SIZE)'
+- `malloc.h', `stdlib.h' (BSD): *Note Aligned Memory Blocks::.
+-
+-`void * memccpy (void *TO, const void *FROM, int C, size_t SIZE)'
+- `string.h' (SVID): *Note Copying and Concatenation::.
+-
+-`void * memchr (const void *BLOCK, int C, size_t SIZE)'
+- `string.h' (ISO): *Note Search Functions::.
+-
+-`int memcmp (const void *A1, const void *A2, size_t SIZE)'
+- `string.h' (ISO): *Note String/Array Comparison::.
+-
+-`void * memcpy (void *TO, const void *FROM, size_t SIZE)'
+- `string.h' (ISO): *Note Copying and Concatenation::.
+-
+-`void * memmem (const void *NEEDLE, size_t NEEDLE-LEN,
+- const void *HAYSTACK, size_t HAYSTACK-LEN)'
+- `string.h' (GNU): *Note Search Functions::.
+-
+-`void * memmove (void *TO, const void *FROM, size_t SIZE)'
+- `string.h' (ISO): *Note Copying and Concatenation::.
+-
+-`void memory_warnings (void *START, void (*WARN-FUNC) (const char *))'
+- `malloc.h' (GNU): *Note Memory Warnings::.
+-
+-`void * memset (void *BLOCK, int C, size_t SIZE)'
+- `string.h' (ISO): *Note Copying and Concatenation::.
+-
+-`int mkdir (const char *FILENAME, mode_t MODE)'
+- `sys/stat.h' (POSIX.1): *Note Creating Directories::.
+-
+-`int mkfifo (const char *FILENAME, mode_t MODE)'
+- `sys/stat.h' (POSIX.1): *Note FIFO Special Files::.
+-
+-`int mknod (const char *FILENAME, int MODE, int DEV)'
+- `sys/stat.h' (BSD): *Note Making Special Files::.
+-
+-`int mkstemp (char *TEMPLATE)'
+- `unistd.h' (BSD): *Note Temporary Files::.
+-
+-`char * mktemp (char *TEMPLATE)'
+- `unistd.h' (Unix): *Note Temporary Files::.
+-
+-`time_t mktime (struct tm *BROKENTIME)'
+- `time.h' (ISO): *Note Broken-down Time::.
+-
+-`mode_t'
+- `sys/types.h' (POSIX.1): *Note Attribute Meanings::.
+-
+-`double modf (double VALUE, double *INTEGER-PART)'
+- `math.h' (ISO): *Note Rounding and Remainders::.
+-
+-`int MSG_DONTROUTE'
+- `sys/socket.h' (BSD): *Note Socket Data Options::.
+-
+-`int MSG_OOB'
+- `sys/socket.h' (BSD): *Note Socket Data Options::.
+-
+-`int MSG_PEEK'
+- `sys/socket.h' (BSD): *Note Socket Data Options::.
+-
+-`struct mstats mstats (void)'
+- `malloc.h' (GNU): *Note Statistics of Malloc::.
+-
+-`int NAME_MAX'
+- `limits.h' (POSIX.1): *Note Limits for Files::.
+-
+-`double NAN'
+- `math.h' (GNU): *Note Not a Number::.
+-
+-`int NCCS'
+- `termios.h' (POSIX.1): *Note Mode Data Types::.
+-
+-`int NGROUPS_MAX'
+- `limits.h' (POSIX.1): *Note General Limits::.
+-
+-`int nice (int INCREMENT)'
+- `dunno.h' (dunno.h): *Note Priority::.
+-
+-`nlink_t'
+- `sys/types.h' (POSIX.1): *Note Attribute Meanings::.
+-
+-`NO_ADDRESS'
+- `netdb.h' (BSD): *Note Host Names::.
+-
+-`tcflag_t NOFLSH'
+- `termios.h' (POSIX.1): *Note Local Modes::.
+-
+-`tcflag_t NOKERNINFO'
+- `termios.h' (BSD): *Note Local Modes::.
+-
+-`NO_RECOVERY'
+- `netdb.h' (BSD): *Note Host Names::.
+-
+-`int NSIG'
+- `signal.h' (BSD): *Note Standard Signals::.
+-
+-`unsigned long int ntohl (unsigned long int NETLONG)'
+- `netinet/in.h' (BSD): *Note Byte Order::.
+-
+-`unsigned short int ntohs (unsigned short int NETSHORT)'
+- `netinet/in.h' (BSD): *Note Byte Order::.
+-
+-`void * NULL'
+- `stddef.h' (ISO): *Note Null Pointer Constant::.
+-
+-`int O_ACCMODE'
+- `fcntl.h' (POSIX.1): *Note Access Modes::.
+-
+-`int O_APPEND'
+- `fcntl.h' (POSIX.1): *Note Operating Modes::.
+-
+-`int O_ASYNC'
+- `fcntl.h' (BSD): *Note Operating Modes::.
+-
+-`void obstack_1grow_fast (struct obstack *OBSTACK-PTR, char C)'
+- `obstack.h' (GNU): *Note Extra Fast Growing::.
+-
+-`void obstack_1grow (struct obstack *OBSTACK-PTR, char C)'
+- `obstack.h' (GNU): *Note Growing Objects::.
+-
+-`int obstack_alignment_mask (struct obstack *OBSTACK-PTR)'
+- `obstack.h' (GNU): *Note Obstacks Data Alignment::.
+-
+-`void * obstack_alloc (struct obstack *OBSTACK-PTR, int SIZE)'
+- `obstack.h' (GNU): *Note Allocation in an Obstack::.
+-
+-`void * obstack_base (struct obstack *OBSTACK-PTR)'
+- `obstack.h' (GNU): *Note Status of an Obstack::.
+-
+-`void obstack_blank_fast (struct obstack *OBSTACK-PTR, int SIZE)'
+- `obstack.h' (GNU): *Note Extra Fast Growing::.
+-
+-`void obstack_blank (struct obstack *OBSTACK-PTR, int SIZE)'
+- `obstack.h' (GNU): *Note Growing Objects::.
+-
+-`int obstack_chunk_size (struct obstack *OBSTACK-PTR)'
+- `obstack.h' (GNU): *Note Obstack Chunks::.
+-
+-`void * obstack_copy0 (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
+- `obstack.h' (GNU): *Note Allocation in an Obstack::.
+-
+-`void * obstack_copy (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
+- `obstack.h' (GNU): *Note Allocation in an Obstack::.
+-
+-`void * obstack_finish (struct obstack *OBSTACK-PTR)'
+- `obstack.h' (GNU): *Note Growing Objects::.
+-
+-`void obstack_free (struct obstack *OBSTACK-PTR, void *OBJECT)'
+- `obstack.h' (GNU): *Note Freeing Obstack Objects::.
+-
+-`void obstack_grow0 (struct obstack *OBSTACK-PTR, void *DATA, int SIZE)'
+- `obstack.h' (GNU): *Note Growing Objects::.
+-
+-`void obstack_grow (struct obstack *OBSTACK-PTR, void *DATA, int SIZE)'
+- `obstack.h' (GNU): *Note Growing Objects::.
+-
+-`int obstack_init (struct obstack *OBSTACK-PTR)'
+- `obstack.h' (GNU): *Note Preparing for Obstacks::.
+-
+-`void obstack_int_grow_fast (struct obstack *OBSTACK-PTR, int DATA)'
+- `obstack.h' (GNU): *Note Extra Fast Growing::.
+-
+-`void obstack_int_grow (struct obstack *OBSTACK-PTR, int DATA)'
+- `obstack.h' (GNU): *Note Growing Objects::.
+-
+-`void * obstack_next_free (struct obstack *OBSTACK-PTR)'
+- `obstack.h' (GNU): *Note Status of an Obstack::.
+-
+-`int obstack_object_size (struct obstack *OBSTACK-PTR)'
+- `obstack.h' (GNU): *Note Growing Objects::.
+-
+-`int obstack_object_size (struct obstack *OBSTACK-PTR)'
+- `obstack.h' (GNU): *Note Status of an Obstack::.
+-
+-`int obstack_printf (struct obstack *OBSTACK, const char *TEMPLATE, ...)'
+- `stdio.h' (GNU): *Note Dynamic Output::.
+-
+-`void obstack_ptr_grow_fast (struct obstack *OBSTACK-PTR, void *DATA)'
+- `obstack.h' (GNU): *Note Extra Fast Growing::.
+-
+-`void obstack_ptr_grow (struct obstack *OBSTACK-PTR, void *DATA)'
+- `obstack.h' (GNU): *Note Growing Objects::.
+-
+-`int obstack_room (struct obstack *OBSTACK-PTR)'
+- `obstack.h' (GNU): *Note Extra Fast Growing::.
+-
+-`int obstack_vprintf (struct obstack *OBSTACK, const char *TEMPLATE, va_list
AP)'
+- `stdio.h' (GNU): *Note Variable Arguments Output::.
+-
+-`int O_CREAT'
+- `fcntl.h' (POSIX.1): *Note Open-time Flags::.
+-
+-`int O_EXCL'
+- `fcntl.h' (POSIX.1): *Note Open-time Flags::.
+-
+-`int O_EXEC'
+- `fcntl.h' (GNU): *Note Access Modes::.
+-
+-`int O_EXLOCK'
+- `fcntl.h' (BSD): *Note Open-time Flags::.
+-
+-`size_t offsetof (TYPE, MEMBER)'
+- `stddef.h' (ISO): *Note Structure Measurement::.
+-
+-`off_t'
+- `sys/types.h' (POSIX.1): *Note File Position Primitive::.
+-
+-`int O_FSYNC'
+- `fcntl.h' (BSD): *Note Operating Modes::.
+-
+-`int O_IGNORE_CTTY'
+- `fcntl.h' (GNU): *Note Open-time Flags::.
+-
+-`int O_NDELAY'
+- `fcntl.h' (BSD): *Note Operating Modes::.
+-
+-`int on_exit (void (*FUNCTION)(int STATUS, void *ARG), void *ARG)'
+- `stdlib.h' (SunOS): *Note Cleanups on Exit::.
+-
+-`tcflag_t ONLCR'
+- `termios.h' (BSD): *Note Output Modes::.
+-
+-`int O_NOATIME'
+- `fcntl.h' (GNU): *Note Operating Modes::.
+-
+-`int O_NOCTTY'
+- `fcntl.h' (POSIX.1): *Note Open-time Flags::.
+-
+-`tcflag_t ONOEOT'
+- `termios.h' (BSD): *Note Output Modes::.
+-
+-`int O_NOLINK'
+- `fcntl.h' (GNU): *Note Open-time Flags::.
+-
+-`int O_NONBLOCK'
+- `fcntl.h' (POSIX.1): *Note Open-time Flags::.
+-
+-`int O_NONBLOCK'
+- `fcntl.h' (POSIX.1): *Note Operating Modes::.
+-
+-`int O_NOTRANS'
+- `fcntl.h' (GNU): *Note Open-time Flags::.
+-
+-`DIR * opendir (const char *DIRNAME)'
+- `dirent.h' (POSIX.1): *Note Opening a Directory::.
+-
+-`int open (const char *FILENAME, int FLAGS[, mode_t MODE])'
+- `fcntl.h' (POSIX.1): *Note Opening and Closing Files::.
+-
+-`int OPEN_MAX'
+- `limits.h' (POSIX.1): *Note General Limits::.
+-
+-`FILE * open_memstream (char **PTR, size_t *SIZELOC)'
+- `stdio.h' (GNU): *Note String Streams::.
+-
+-`FILE * open_obstack_stream (struct obstack *OBSTACK)'
+- `stdio.h' (GNU): *Note Obstack Streams::.
+-
+-`tcflag_t OPOST'
+- `termios.h' (POSIX.1): *Note Output Modes::.
+-
+-`char * optarg'
+- `unistd.h' (POSIX.2): *Note Parsing Options::.
+-
+-`int opterr'
+- `unistd.h' (POSIX.2): *Note Parsing Options::.
+-
+-`int optind'
+- `unistd.h' (POSIX.2): *Note Parsing Options::.
+-
+-`int optopt'
+- `unistd.h' (POSIX.2): *Note Parsing Options::.
+-
+-`int O_RDONLY'
+- `fcntl.h' (POSIX.1): *Note Access Modes::.
+-
+-`int O_RDWR'
+- `fcntl.h' (POSIX.1): *Note Access Modes::.
+-
+-`int O_READ'
+- `fcntl.h' (GNU): *Note Access Modes::.
+-
+-`int O_SHLOCK'
+- `fcntl.h' (BSD): *Note Open-time Flags::.
+-
+-`int O_SYNC'
+- `fcntl.h' (BSD): *Note Operating Modes::.
+-
+-`int O_TRUNC'
+- `fcntl.h' (POSIX.1): *Note Open-time Flags::.
+-
+-`int O_WRITE'
+- `fcntl.h' (GNU): *Note Access Modes::.
+-
+-`int O_WRONLY'
+- `fcntl.h' (POSIX.1): *Note Access Modes::.
+-
+-`tcflag_t OXTABS'
+- `termios.h' (BSD): *Note Output Modes::.
+-
+-`PA_CHAR'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`PA_DOUBLE'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`PA_FLAG_LONG_DOUBLE'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`PA_FLAG_LONG'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`PA_FLAG_LONG_LONG'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`int PA_FLAG_MASK'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`PA_FLAG_PTR'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`PA_FLAG_SHORT'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`PA_FLOAT'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`PA_INT'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`PA_LAST'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`PA_POINTER'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`tcflag_t PARENB'
+- `termios.h' (POSIX.1): *Note Control Modes::.
+-
+-`tcflag_t PARMRK'
+- `termios.h' (POSIX.1): *Note Input Modes::.
+-
+-`tcflag_t PARODD'
+- `termios.h' (POSIX.1): *Note Control Modes::.
+-
+-`size_t parse_printf_format (const char *TEMPLATE, size_t N, int *ARGTYPES)'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`PA_STRING'
+- `printf.h' (GNU): *Note Parsing a Template String::.
+-
+-`long int pathconf (const char *FILENAME, int PARAMETER)'
+- `unistd.h' (POSIX.1): *Note Pathconf::.
+-
+-`int PATH_MAX'
+- `limits.h' (POSIX.1): *Note Limits for Files::.
+-
+-`int pause ()'
+- `unistd.h' (POSIX.1): *Note Using Pause::.
+-
+-`_PC_CHOWN_RESTRICTED'
+- `unistd.h' (POSIX.1): *Note Pathconf::.
+-
+-`_PC_LINK_MAX'
+- `unistd.h' (POSIX.1): *Note Pathconf::.
+-
+-`int pclose (FILE *STREAM)'
+- `stdio.h' (POSIX.2, SVID, BSD): *Note Pipe to a Subprocess::.
+-
+-`_PC_MAX_CANON'
+- `unistd.h' (POSIX.1): *Note Pathconf::.
+-
+-`_PC_MAX_INPUT'
+- `unistd.h' (POSIX.1): *Note Pathconf::.
+-
+-`_PC_NAME_MAX'
+- `unistd.h' (POSIX.1): *Note Pathconf::.
+-
+-`_PC_NO_TRUNC'
+- `unistd.h' (POSIX.1): *Note Pathconf::.
+-
+-`_PC_PATH_MAX'
+- `unistd.h' (POSIX.1): *Note Pathconf::.
+-
+-`_PC_PIPE_BUF'
+- `unistd.h' (POSIX.1): *Note Pathconf::.
+-
+-`_PC_VDISABLE'
+- `unistd.h' (POSIX.1): *Note Pathconf::.
+-
+-`tcflag_t PENDIN'
+- `termios.h' (BSD): *Note Local Modes::.
+-
+-`void perror (const char *MESSAGE)'
+- `stdio.h' (ISO): *Note Error Messages::.
+-
+-`int PF_FILE'
+- `sys/socket.h' (GNU): *Note File Namespace Details::.
+-
+-`int PF_INET'
+- `sys/socket.h' (BSD): *Note Internet Namespace::.
+-
+-`int PF_UNIX'
+- `sys/socket.h' (BSD): *Note File Namespace Details::.
+-
+-`pid_t'
+- `sys/types.h' (POSIX.1): *Note Process Identification::.
+-
+-`int PIPE_BUF'
+- `limits.h' (POSIX.1): *Note Limits for Files::.
+-
+-`int pipe (int FILEDES[2])'
+- `unistd.h' (POSIX.1): *Note Creating a Pipe::.
+-
+-`FILE * popen (const char *COMMAND, const char *MODE)'
+- `stdio.h' (POSIX.2, SVID, BSD): *Note Pipe to a Subprocess::.
+-
+-`_POSIX2_BC_BASE_MAX'
+- `limits.h' (POSIX.2): *Note Utility Minimums::.
+-
+-`_POSIX2_BC_DIM_MAX'
+- `limits.h' (POSIX.2): *Note Utility Minimums::.
+-
+-`_POSIX2_BC_SCALE_MAX'
+- `limits.h' (POSIX.2): *Note Utility Minimums::.
+-
+-`_POSIX2_BC_STRING_MAX'
+- `limits.h' (POSIX.2): *Note Utility Minimums::.
+-
+-`int _POSIX2_C_DEV'
+- `unistd.h' (POSIX.2): *Note System Options::.
+-
+-`_POSIX2_COLL_WEIGHTS_MAX'
+- `limits.h' (POSIX.2): *Note Utility Minimums::.
+-
+-`long int _POSIX2_C_VERSION'
+- `unistd.h' (POSIX.2): *Note Version Supported::.
+-
+-`_POSIX2_EQUIV_CLASS_MAX'
+- `limits.h' (POSIX.2): *Note Utility Minimums::.
+-
+-`_POSIX2_EXPR_NEST_MAX'
+- `limits.h' (POSIX.2): *Note Utility Minimums::.
+-
+-`int _POSIX2_FORT_DEV'
+- `unistd.h' (POSIX.2): *Note System Options::.
+-
+-`int _POSIX2_FORT_RUN'
+- `unistd.h' (POSIX.2): *Note System Options::.
+-
+-`_POSIX2_LINE_MAX'
+- `limits.h' (POSIX.2): *Note Utility Minimums::.
+-
+-`int _POSIX2_LOCALEDEF'
+- `unistd.h' (POSIX.2): *Note System Options::.
+-
+-`_POSIX2_RE_DUP_MAX'
+- `limits.h' (POSIX.2): *Note Minimums::.
+-
+-`int _POSIX2_SW_DEV'
+- `unistd.h' (POSIX.2): *Note System Options::.
+-
+-`_POSIX_ARG_MAX'
+- `limits.h' (POSIX.1): *Note Minimums::.
+-
+-`_POSIX_CHILD_MAX'
+- `limits.h' (POSIX.1): *Note Minimums::.
+-
+-`int _POSIX_CHOWN_RESTRICTED'
+- `unistd.h' (POSIX.1): *Note Options for Files::.
+-
+-`_POSIX_C_SOURCE'
+- (POSIX.2): *Note Feature Test Macros::.
+-
+-`int _POSIX_JOB_CONTROL'
+- `unistd.h' (POSIX.1): *Note System Options::.
+-
+-`_POSIX_LINK_MAX'
+- `limits.h' (POSIX.1): *Note File Minimums::.
+-
+-`_POSIX_MAX_CANON'
+- `limits.h' (POSIX.1): *Note File Minimums::.
+-
+-`_POSIX_MAX_INPUT'
+- `limits.h' (POSIX.1): *Note File Minimums::.
+-
+-`_POSIX_NAME_MAX'
+- `limits.h' (POSIX.1): *Note File Minimums::.
+-
+-`_POSIX_NGROUPS_MAX'
+- `limits.h' (POSIX.1): *Note Minimums::.
+-
+-`int _POSIX_NO_TRUNC'
+- `unistd.h' (POSIX.1): *Note Options for Files::.
+-
+-`_POSIX_OPEN_MAX'
+- `limits.h' (POSIX.1): *Note Minimums::.
+-
+-`_POSIX_PATH_MAX'
+- `limits.h' (POSIX.1): *Note File Minimums::.
+-
+-`_POSIX_PIPE_BUF'
+- `limits.h' (POSIX.1): *Note File Minimums::.
+-
+-`int _POSIX_SAVED_IDS'
+- `unistd.h' (POSIX.1): *Note System Options::.
+-
+-`_POSIX_SOURCE'
+- (POSIX.1): *Note Feature Test Macros::.
+-
+-`_POSIX_SSIZE_MAX'
+- `limits.h' (POSIX.1): *Note Minimums::.
+-
+-`_POSIX_STREAM_MAX'
+- `limits.h' (POSIX.1): *Note Minimums::.
+-
+-`_POSIX_TZNAME_MAX'
+- `limits.h' (POSIX.1): *Note Minimums::.
+-
+-`unsigned char _POSIX_VDISABLE'
+- `unistd.h' (POSIX.1): *Note Options for Files::.
+-
+-`long int _POSIX_VERSION'
+- `unistd.h' (POSIX.1): *Note Version Supported::.
+-
+-`double pow (double BASE, double POWER)'
+- `math.h' (ISO): *Note Exponents and Logarithms::.
+-
+-`printf_arginfo_function'
+- `printf.h' (GNU): *Note Defining the Output Handler::.
+-
+-`printf_function'
+- `printf.h' (GNU): *Note Defining the Output Handler::.
+-
+-`int printf (const char *TEMPLATE, ...)'
+- `stdio.h' (ISO): *Note Formatted Output Functions::.
+-
+-`PRIO_MAX'
+- `sys/resource.h' (BSD): *Note Priority::.
+-
+-`PRIO_MIN'
+- `sys/resource.h' (BSD): *Note Priority::.
+-
+-`PRIO_PGRP'
+- `sys/resource.h' (BSD): *Note Priority::.
+-
+-`PRIO_PROCESS'
+- `sys/resource.h' (BSD): *Note Priority::.
+-
+-`PRIO_USER'
+- `sys/resource.h' (BSD): *Note Priority::.
+-
+-`char * program_invocation_name'
+- `errno.h' (GNU): *Note Error Messages::.
+-
+-`char * program_invocation_short_name'
+- `errno.h' (GNU): *Note Error Messages::.
+-
+-`void psignal (int SIGNUM, const char *MESSAGE)'
+- `signal.h' (BSD): *Note Signal Messages::.
+-
+-`char * P_tmpdir'
+- `stdio.h' (SVID): *Note Temporary Files::.
+-
+-`ptrdiff_t'
+- `stddef.h' (ISO): *Note Important Data Types::.
+-
+-`int putchar (int C)'
+- `stdio.h' (ISO): *Note Simple Output::.
+-
+-`int putc (int C, FILE *STREAM)'
+- `stdio.h' (ISO): *Note Simple Output::.
+-
+-`int putenv (const char *STRING)'
+- `stdlib.h' (SVID): *Note Environment Access::.
+-
+-`int putpwent (const struct passwd *P, FILE *STREAM)'
+- `pwd.h' (SVID): *Note Writing a User Entry::.
+-
+-`int puts (const char *S)'
+- `stdio.h' (ISO): *Note Simple Output::.
+-
+-`int putw (int W, FILE *STREAM)'
+- `stdio.h' (SVID): *Note Simple Output::.
+-
+-`void qsort (void *ARRAY, size_t COUNT, size_t SIZE, comparison_fn_t COMPARE)'
+- `stdlib.h' (ISO): *Note Array Sort Function::.
+-
+-`int raise (int SIGNUM)'
+- `signal.h' (ISO): *Note Signaling Yourself::.
+-
+-`void r_alloc_free (void **HANDLEPTR)'
+- `malloc.h' (GNU): *Note Using Relocator::.
+-
+-`void * r_alloc (void **HANDLEPTR, size_t SIZE)'
+- `malloc.h' (GNU): *Note Using Relocator::.
+-
+-`int rand ()'
+- `stdlib.h' (ISO): *Note ISO Random::.
+-
+-`int RAND_MAX'
+- `stdlib.h' (ISO): *Note ISO Random::.
+-
+-`long int random ()'
+- `stdlib.h' (BSD): *Note BSD Random::.
+-
+-`struct dirent * readdir (DIR *DIRSTREAM)'
+- `dirent.h' (POSIX.1): *Note Reading/Closing Directory::.
+-
+-`int readdir_r (DIR *DIRSTREAM, struct *ENTRY, struct **RESULT)'
+- `dirent.h' (GNU): *Note Reading/Closing Directory::.
+-
+-`ssize_t read (int FILEDES, void *BUFFER, size_t SIZE)'
+- `unistd.h' (POSIX.1): *Note I/O Primitives::.
+-
+-`int readlink (const char *FILENAME, char *BUFFER, size_t SIZE)'
+- `unistd.h' (BSD): *Note Symbolic Links::.
+-
+-`__realloc_hook'
+- `malloc.h' (GNU): *Note Hooks for Malloc::.
+-
+-`void * realloc (void *PTR, size_t NEWSIZE)'
+- `malloc.h', `stdlib.h' (ISO): *Note Changing Block Size::.
+-
+-`int recvfrom (int SOCKET, void *BUFFER, size_t SIZE, int FLAGS, struct
sockaddr *ADDR, size_t *LENGTH-PTR)'
+- `sys/socket.h' (BSD): *Note Receiving Datagrams::.
+-
+-`int recv (int SOCKET, void *BUFFER, size_t SIZE, int FLAGS)'
+- `sys/socket.h' (BSD): *Note Receiving Data::.
+-
+-`int recvmsg (int SOCKET, struct msghdr *MESSAGE, int FLAGS)'
+- `sys/socket.h' (BSD): *Note Receiving Datagrams::.
+-
+-`int RE_DUP_MAX'
+- `limits.h' (POSIX.2): *Note General Limits::.
+-
+-`_REENTRANT'
+- (GNU): *Note Feature Test Macros::.
+-
+-`REG_BADBR'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`REG_BADPAT'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`REG_BADRPT'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`int regcomp (regex_t *COMPILED, const char *PATTERN, int CFLAGS)'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`REG_EBRACE'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`REG_EBRACK'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`REG_ECOLLATE'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`REG_ECTYPE'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`REG_EESCAPE'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`REG_EPAREN'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`REG_ERANGE'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`size_t regerror (int ERRCODE, regex_t *COMPILED, char *BUFFER, size_t
LENGTH)'
+- `regex.h' (POSIX.2): *Note Regexp Cleanup::.
+-
+-`REG_ESPACE'
+- `regex.h' (POSIX.2): *Note Matching POSIX Regexps::.
+-
+-`REG_ESPACE'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`REG_ESUBREG'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`int regexec (regex_t *COMPILED, char *STRING, size_t NMATCH, regmatch_t
MATCHPTR [], int EFLAGS)'
+- `regex.h' (POSIX.2): *Note Matching POSIX Regexps::.
+-
+-`REG_EXTENDED'
+- `regex.h' (POSIX.2): *Note Flags for POSIX Regexps::.
+-
+-`regex_t'
+- `regex.h' (POSIX.2): *Note POSIX Regexp Compilation::.
+-
+-`void regfree (regex_t *COMPILED)'
+- `regex.h' (POSIX.2): *Note Regexp Cleanup::.
+-
+-`REG_ICASE'
+- `regex.h' (POSIX.2): *Note Flags for POSIX Regexps::.
+-
+-`int register_printf_function (int SPEC, printf_function HANDLER-FUNCTION,
printf_arginfo_function ARGINFO-FUNCTION)'
+- `printf.h' (GNU): *Note Registering New Conversions::.
+-
+-`regmatch_t'
+- `regex.h' (POSIX.2): *Note Regexp Subexpressions::.
+-
+-`REG_NEWLINE'
+- `regex.h' (POSIX.2): *Note Flags for POSIX Regexps::.
+-
+-`REG_NOMATCH'
+- `regex.h' (POSIX.2): *Note Matching POSIX Regexps::.
+-
+-`REG_NOSUB'
+- `regex.h' (POSIX.2): *Note Flags for POSIX Regexps::.
+-
+-`REG_NOTBOL'
+- `regex.h' (POSIX.2): *Note Matching POSIX Regexps::.
+-
+-`REG_NOTEOL'
+- `regex.h' (POSIX.2): *Note Matching POSIX Regexps::.
+-
+-`regoff_t'
+- `regex.h' (POSIX.2): *Note Regexp Subexpressions::.
+-
+-`int remove (const char *FILENAME)'
+- `stdio.h' (ISO): *Note Deleting Files::.
+-
+-`int rename (const char *OLDNAME, const char *NEWNAME)'
+- `stdio.h' (ISO): *Note Renaming Files::.
+-
+-`void rewinddir (DIR *DIRSTREAM)'
+- `dirent.h' (POSIX.1): *Note Random Access Directory::.
+-
+-`void rewind (FILE *STREAM)'
+- `stdio.h' (ISO): *Note File Positioning::.
+-
+-`char * rindex (const char *STRING, int C)'
+- `string.h' (BSD): *Note Search Functions::.
+-
+-`double rint (double X)'
+- `math.h' (BSD): *Note Rounding and Remainders::.
+-
+-`RLIMIT_CORE'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`RLIMIT_CPU'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`RLIMIT_DATA'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`RLIMIT_FSIZE'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`RLIMIT_MEMLOCK'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`RLIMIT_NOFILE'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`RLIMIT_NPROC'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`RLIMIT_RSS'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`RLIMIT_STACK'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`RLIM_NLIMITS'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`int rmdir (const char *FILENAME)'
+- `unistd.h' (POSIX.1): *Note Deleting Files::.
+-
+-`int R_OK'
+- `unistd.h' (POSIX.1): *Note Testing File Access::.
+-
+-`void * r_re_alloc (void **HANDLEPTR, size_t SIZE)'
+- `malloc.h' (GNU): *Note Using Relocator::.
+-
+-`RUSAGE_CHILDREN'
+- `sys/resource.h' (BSD): *Note Resource Usage::.
+-
+-`RUSAGE_SELF'
+- `sys/resource.h' (BSD): *Note Resource Usage::.
+-
+-`int SA_NOCLDSTOP'
+- `signal.h' (POSIX.1): *Note Flags for Sigaction::.
+-
+-`int SA_ONSTACK'
+- `signal.h' (BSD): *Note Flags for Sigaction::.
+-
+-`int SA_RESTART'
+- `signal.h' (BSD): *Note Flags for Sigaction::.
+-
+-`_SC_2_C_DEV'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`_SC_2_FORT_DEV'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`_SC_2_FORT_RUN'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`_SC_2_LOCALEDEF'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`_SC_2_SW_DEV'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`_SC_2_VERSION'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`double scalb (double VALUE, int EXPONENT)'
+- `math.h' (BSD): *Note Normalization Functions::.
+-
+-`int scanf (const char *TEMPLATE, ...)'
+- `stdio.h' (ISO): *Note Formatted Input Functions::.
+-
+-`_SC_ARG_MAX'
+- `unistd.h' (POSIX.1): *Note Constants for Sysconf::.
+-
+-`_SC_BC_BASE_MAX'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`_SC_BC_DIM_MAX'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`_SC_BC_SCALE_MAX'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`_SC_BC_STRING_MAX'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`_SC_CHILD_MAX'
+- `unistd.h' (POSIX.1): *Note Constants for Sysconf::.
+-
+-`_SC_CLK_TCK'
+- `unistd.h' (POSIX.1): *Note Constants for Sysconf::.
+-
+-`_SC_COLL_WEIGHTS_MAX'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`_SC_EQUIV_CLASS_MAX'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`_SC_EXPR_NEST_MAX'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`SCHAR_MAX'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`SCHAR_MIN'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`_SC_JOB_CONTROL'
+- `unistd.h' (POSIX.1): *Note Constants for Sysconf::.
+-
+-`_SC_LINE_MAX'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`_SC_NGROUPS_MAX'
+- `unistd.h' (POSIX.1): *Note Constants for Sysconf::.
+-
+-`_SC_OPEN_MAX'
+- `unistd.h' (POSIX.1): *Note Constants for Sysconf::.
+-
+-`_SC_PAGESIZE'
+- `unistd.h' (GNU): *Note Constants for Sysconf::.
+-
+-`_SC_SAVED_IDS'
+- `unistd.h' (POSIX.1): *Note Constants for Sysconf::.
+-
+-`_SC_STREAM_MAX'
+- `unistd.h' (POSIX.1): *Note Constants for Sysconf::.
+-
+-`_SC_TZNAME_MAX'
+- `unistd.h' (POSIX.1): *Note Constants for Sysconf::.
+-
+-`_SC_VERSION'
+- `unistd.h' (POSIX.1): *Note Constants for Sysconf::.
+-
+-`_SC_VERSION'
+- `unistd.h' (POSIX.2): *Note Constants for Sysconf::.
+-
+-`int SEEK_CUR'
+- `stdio.h' (ISO): *Note File Positioning::.
+-
+-`void seekdir (DIR *DIRSTREAM, off_t POS)'
+- `dirent.h' (BSD): *Note Random Access Directory::.
+-
+-`int SEEK_END'
+- `stdio.h' (ISO): *Note File Positioning::.
+-
+-`int SEEK_SET'
+- `stdio.h' (ISO): *Note File Positioning::.
+-
+-`int select (int NFDS, fd_set *READ-FDS, fd_set *WRITE-FDS, fd_set
*EXCEPT-FDS, struct timeval *TIMEOUT)'
+- `sys/types.h' (BSD): *Note Waiting for I/O::.
+-
+-`int send (int SOCKET, void *BUFFER, size_t SIZE, int FLAGS)'
+- `sys/socket.h' (BSD): *Note Sending Data::.
+-
+-`int sendmsg (int SOCKET, const struct msghdr *MESSAGE, int FLAGS)'
+- `sys/socket.h' (BSD): *Note Receiving Datagrams::.
+-
+-`int sendto (int SOCKET, void *BUFFER. size_t SIZE, int FLAGS, struct
sockaddr *ADDR, size_t LENGTH)'
+- `sys/socket.h' (BSD): *Note Sending Datagrams::.
+-
+-`void setbuffer (FILE *STREAM, char *BUF, size_t SIZE)'
+- `stdio.h' (BSD): *Note Controlling Buffering::.
+-
+-`void setbuf (FILE *STREAM, char *BUF)'
+- `stdio.h' (ISO): *Note Controlling Buffering::.
+-
+-`int setgid (gid_t NEWGID)'
+- `unistd.h' (POSIX.1): *Note Setting Groups::.
+-
+-`void setgrent (void)'
+- `grp.h' (SVID, BSD): *Note Scanning All Groups::.
+-
+-`int setgroups (size_t COUNT, gid_t *GROUPS)'
+- `grp.h' (BSD): *Note Setting Groups::.
+-
+-`void sethostent (int STAYOPEN)'
+- `netdb.h' (BSD): *Note Host Names::.
+-
+-`int sethostid (long int ID)'
+- `unistd.h' (BSD): *Note Host Identification::.
+-
+-`int sethostname (const char *NAME, size_t LENGTH)'
+- `unistd.h' (BSD): *Note Host Identification::.
+-
+-`int setitimer (int WHICH, struct itimerval *NEW, struct itimerval *OLD)'
+- `sys/time.h' (BSD): *Note Setting an Alarm::.
+-
+-`int setjmp (jmp_buf STATE)'
+- `setjmp.h' (ISO): *Note Non-Local Details::.
+-
+-`void setlinebuf (FILE *STREAM)'
+- `stdio.h' (BSD): *Note Controlling Buffering::.
+-
+-`char * setlocale (int CATEGORY, const char *LOCALE)'
+- `locale.h' (ISO): *Note Setting the Locale::.
+-
+-`void setnetent (int STAYOPEN)'
+- `netdb.h' (BSD): *Note Networks Database::.
+-
+-`int setnetgrent (const char *NETGROUP)'
+- `netdb.h' (netdb.h): *Note Lookup Netgroup::.
+-
+-`int setpgid (pid_t PID, pid_t PGID)'
+- `unistd.h' (POSIX.1): *Note Process Group Functions::.
+-
+-`int setpgrp (pid_t PID, pid_t PGID)'
+- `unistd.h' (BSD): *Note Process Group Functions::.
+-
+-`int setpriority (int CLASS, int ID, int PRIORITY)'
+- `sys/resource.h' (BSD): *Note Priority::.
+-
+-`void setprotoent (int STAYOPEN)'
+- `netdb.h' (BSD): *Note Protocols Database::.
+-
+-`void setpwent (void)'
+- `pwd.h' (SVID, BSD): *Note Scanning All Users::.
+-
+-`int setregid (gid_t RGID, fid_t EGID)'
+- `unistd.h' (BSD): *Note Setting Groups::.
+-
+-`int setreuid (uid_t RUID, uid_t EUID)'
+- `unistd.h' (BSD): *Note Setting User ID::.
+-
+-`int setrlimit (int RESOURCE, struct rlimit *RLP)'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`void setservent (int STAYOPEN)'
+- `netdb.h' (BSD): *Note Services Database::.
+-
+-`pid_t setsid (void)'
+- `unistd.h' (POSIX.1): *Note Process Group Functions::.
+-
+-`int setsockopt (int SOCKET, int LEVEL, int OPTNAME, void *OPTVAL, size_t
OPTLEN)'
+- `sys/socket.h' (BSD): *Note Socket Option Functions::.
+-
+-`void * setstate (void *STATE)'
+- `stdlib.h' (BSD): *Note BSD Random::.
+-
+-`int settimeofday (const struct timeval *TP, const struct timezone *TZP)'
+- `sys/time.h' (BSD): *Note High-Resolution Calendar::.
+-
+-`int setuid (uid_t NEWUID)'
+- `unistd.h' (POSIX.1): *Note Setting User ID::.
+-
+-`int setvbuf (FILE *STREAM, char *BUF, int MODE, size_t SIZE)'
+- `stdio.h' (ISO): *Note Controlling Buffering::.
+-
+-`SHRT_MAX'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`SHRT_MIN'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`int shutdown (int SOCKET, int HOW)'
+- `sys/socket.h' (BSD): *Note Closing a Socket::.
+-
+-`S_IEXEC'
+- `sys/stat.h' (BSD): *Note Permission Bits::.
+-
+-`S_IFBLK'
+- `sys/stat.h' (BSD): *Note Testing File Type::.
+-
+-`S_IFCHR'
+- `sys/stat.h' (BSD): *Note Testing File Type::.
+-
+-`S_IFDIR'
+- `sys/stat.h' (BSD): *Note Testing File Type::.
+-
+-`S_IFIFO'
+- `sys/stat.h' (BSD): *Note Testing File Type::.
+-
+-`S_IFLNK'
+- `sys/stat.h' (BSD): *Note Testing File Type::.
+-
+-`int S_IFMT'
+- `sys/stat.h' (BSD): *Note Testing File Type::.
+-
+-`S_IFREG'
+- `sys/stat.h' (BSD): *Note Testing File Type::.
+-
+-`S_IFSOCK'
+- `sys/stat.h' (BSD): *Note Testing File Type::.
+-
+-`int SIGABRT'
+- `signal.h' (ISO): *Note Program Error Signals::.
+-
+-`int sigaction (int SIGNUM, const struct sigaction *ACTION, struct sigaction
*OLD-ACTION)'
+- `signal.h' (POSIX.1): *Note Advanced Signal Handling::.
+-
+-`int sigaddset (sigset_t *SET, int SIGNUM)'
+- `signal.h' (POSIX.1): *Note Signal Sets::.
+-
+-`int SIGALRM'
+- `signal.h' (POSIX.1): *Note Alarm Signals::.
+-
+-`int sigaltstack (const struct sigaltstack *STACK, struct sigaltstack
*OLDSTACK)'
+- `signal.h' (BSD): *Note Signal Stack::.
+-
+-`sig_atomic_t'
+- `signal.h' (ISO): *Note Atomic Types::.
+-
+-`SIG_BLOCK'
+- `signal.h' (POSIX.1): *Note Process Signal Mask::.
+-
+-`int sigblock (int MASK)'
+- `signal.h' (BSD): *Note Blocking in BSD::.
+-
+-`int SIGBUS'
+- `signal.h' (BSD): *Note Program Error Signals::.
+-
+-`int SIGCHLD'
+- `signal.h' (POSIX.1): *Note Job Control Signals::.
+-
+-`int SIGCLD'
+- `signal.h' (SVID): *Note Job Control Signals::.
+-
+-`int SIGCONT'
+- `signal.h' (POSIX.1): *Note Job Control Signals::.
+-
+-`int sigdelset (sigset_t *SET, int SIGNUM)'
+- `signal.h' (POSIX.1): *Note Signal Sets::.
+-
+-`int sigemptyset (sigset_t *SET)'
+- `signal.h' (POSIX.1): *Note Signal Sets::.
+-
+-`int SIGEMT'
+- `signal.h' (BSD): *Note Program Error Signals::.
+-
+-`sighandler_t SIG_ERR'
+- `signal.h' (ISO): *Note Basic Signal Handling::.
+-
+-`int sigfillset (sigset_t *SET)'
+- `signal.h' (POSIX.1): *Note Signal Sets::.
+-
+-`int SIGFPE'
+- `signal.h' (ISO): *Note Program Error Signals::.
+-
+-`sighandler_t'
+- `signal.h' (GNU): *Note Basic Signal Handling::.
+-
+-`int SIGHUP'
+- `signal.h' (POSIX.1): *Note Termination Signals::.
+-
+-`int SIGILL'
+- `signal.h' (ISO): *Note Program Error Signals::.
+-
+-`int SIGINFO'
+- `signal.h' (BSD): *Note Miscellaneous Signals::.
+-
+-`int siginterrupt (int SIGNUM, int FAILFLAG)'
+- `signal.h' (BSD): *Note BSD Handler::.
+-
+-`int SIGINT'
+- `signal.h' (ISO): *Note Termination Signals::.
+-
+-`int SIGIO'
+- `signal.h' (BSD): *Note Asynchronous I/O Signals::.
+-
+-`int SIGIOT'
+- `signal.h' (Unix): *Note Program Error Signals::.
+-
+-`int sigismember (const sigset_t *SET, int SIGNUM)'
+- `signal.h' (POSIX.1): *Note Signal Sets::.
+-
+-`sigjmp_buf'
+- `setjmp.h' (POSIX.1): *Note Non-Local Exits and Signals::.
+-
+-`int SIGKILL'
+- `signal.h' (POSIX.1): *Note Termination Signals::.
+-
+-`void siglongjmp (sigjmp_buf STATE, int VALUE)'
+- `setjmp.h' (POSIX.1): *Note Non-Local Exits and Signals::.
+-
+-`int SIGLOST'
+- `signal.h' (GNU): *Note Operation Error Signals::.
+-
+-`int sigmask (int SIGNUM)'
+- `signal.h' (BSD): *Note Blocking in BSD::.
+-
+-`sighandler_t signal (int SIGNUM, sighandler_t ACTION)'
+- `signal.h' (ISO): *Note Basic Signal Handling::.
+-
+-`int sigpause (int MASK)'
+- `signal.h' (BSD): *Note Blocking in BSD::.
+-
+-`int sigpending (sigset_t *SET)'
+- `signal.h' (POSIX.1): *Note Checking for Pending Signals::.
+-
+-`int SIGPIPE'
+- `signal.h' (POSIX.1): *Note Operation Error Signals::.
+-
+-`int SIGPOLL'
+- `signal.h' (SVID): *Note Asynchronous I/O Signals::.
+-
+-`int sigprocmask (int HOW, const sigset_t *SET, sigset_t *OLDSET)'
+- `signal.h' (POSIX.1): *Note Process Signal Mask::.
+-
+-`int SIGPROF'
+- `signal.h' (BSD): *Note Alarm Signals::.
+-
+-`int SIGQUIT'
+- `signal.h' (POSIX.1): *Note Termination Signals::.
+-
+-`int SIGSEGV'
+- `signal.h' (ISO): *Note Program Error Signals::.
+-
+-`int sigsetjmp (sigjmp_buf STATE, int SAVESIGS)'
+- `setjmp.h' (POSIX.1): *Note Non-Local Exits and Signals::.
+-
+-`SIG_SETMASK'
+- `signal.h' (POSIX.1): *Note Process Signal Mask::.
+-
+-`int sigsetmask (int MASK)'
+- `signal.h' (BSD): *Note Blocking in BSD::.
+-
+-`sigset_t'
+- `signal.h' (POSIX.1): *Note Signal Sets::.
+-
+-`int sigstack (const struct sigstack *STACK, struct sigstack *OLDSTACK)'
+- `signal.h' (BSD): *Note Signal Stack::.
+-
+-`int SIGSTOP'
+- `signal.h' (POSIX.1): *Note Job Control Signals::.
+-
+-`int sigsuspend (const sigset_t *SET)'
+- `signal.h' (POSIX.1): *Note Sigsuspend::.
+-
+-`int SIGSYS'
+- `signal.h' (Unix): *Note Program Error Signals::.
+-
+-`int SIGTERM'
+- `signal.h' (ISO): *Note Termination Signals::.
+-
+-`int SIGTRAP'
+- `signal.h' (BSD): *Note Program Error Signals::.
+-
+-`int SIGTSTP'
+- `signal.h' (POSIX.1): *Note Job Control Signals::.
+-
+-`int SIGTTIN'
+- `signal.h' (POSIX.1): *Note Job Control Signals::.
+-
+-`int SIGTTOU'
+- `signal.h' (POSIX.1): *Note Job Control Signals::.
+-
+-`SIG_UNBLOCK'
+- `signal.h' (POSIX.1): *Note Process Signal Mask::.
+-
+-`int SIGURG'
+- `signal.h' (BSD): *Note Asynchronous I/O Signals::.
+-
+-`int SIGUSR1'
+- `signal.h' (POSIX.1): *Note Miscellaneous Signals::.
+-
+-`int SIGUSR2'
+- `signal.h' (POSIX.1): *Note Miscellaneous Signals::.
+-
+-`int sigvec (int SIGNUM, const struct sigvec *ACTION,struct sigvec
*OLD-ACTION)'
+- `signal.h' (BSD): *Note BSD Handler::.
+-
+-`int SIGVTALRM'
+- `signal.h' (BSD): *Note Alarm Signals::.
+-
+-`int SIGWINCH'
+- `signal.h' (BSD): *Note Miscellaneous Signals::.
+-
+-`int SIGXCPU'
+- `signal.h' (BSD): *Note Operation Error Signals::.
+-
+-`int SIGXFSZ'
+- `signal.h' (BSD): *Note Operation Error Signals::.
+-
+-`double sinh (double X)'
+- `math.h' (ISO): *Note Hyperbolic Functions::.
+-
+-`double sin (double X)'
+- `math.h' (ISO): *Note Trig Functions::.
+-
+-`S_IREAD'
+- `sys/stat.h' (BSD): *Note Permission Bits::.
+-
+-`S_IRGRP'
+- `sys/stat.h' (POSIX.1): *Note Permission Bits::.
+-
+-`S_IROTH'
+- `sys/stat.h' (POSIX.1): *Note Permission Bits::.
+-
+-`S_IRUSR'
+- `sys/stat.h' (POSIX.1): *Note Permission Bits::.
+-
+-`S_IRWXG'
+- `sys/stat.h' (POSIX.1): *Note Permission Bits::.
+-
+-`S_IRWXO'
+- `sys/stat.h' (POSIX.1): *Note Permission Bits::.
+-
+-`S_IRWXU'
+- `sys/stat.h' (POSIX.1): *Note Permission Bits::.
+-
+-`int S_ISBLK (mode_t M)'
+- `sys/stat.h' (POSIX): *Note Testing File Type::.
+-
+-`int S_ISCHR (mode_t M)'
+- `sys/stat.h' (POSIX): *Note Testing File Type::.
+-
+-`int S_ISDIR (mode_t M)'
+- `sys/stat.h' (POSIX): *Note Testing File Type::.
+-
+-`int S_ISFIFO (mode_t M)'
+- `sys/stat.h' (POSIX): *Note Testing File Type::.
+-
+-`S_ISGID'
+- `sys/stat.h' (POSIX): *Note Permission Bits::.
+-
+-`int S_ISLNK (mode_t M)'
+- `sys/stat.h' (GNU): *Note Testing File Type::.
+-
+-`int S_ISREG (mode_t M)'
+- `sys/stat.h' (POSIX): *Note Testing File Type::.
+-
+-`int S_ISSOCK (mode_t M)'
+- `sys/stat.h' (GNU): *Note Testing File Type::.
+-
+-`S_ISUID'
+- `sys/stat.h' (POSIX): *Note Permission Bits::.
+-
+-`S_ISVTX'
+- `sys/stat.h' (BSD): *Note Permission Bits::.
+-
+-`S_IWGRP'
+- `sys/stat.h' (POSIX.1): *Note Permission Bits::.
+-
+-`S_IWOTH'
+- `sys/stat.h' (POSIX.1): *Note Permission Bits::.
+-
+-`S_IWRITE'
+- `sys/stat.h' (BSD): *Note Permission Bits::.
+-
+-`S_IWUSR'
+- `sys/stat.h' (POSIX.1): *Note Permission Bits::.
+-
+-`S_IXGRP'
+- `sys/stat.h' (POSIX.1): *Note Permission Bits::.
+-
+-`S_IXOTH'
+- `sys/stat.h' (POSIX.1): *Note Permission Bits::.
+-
+-`S_IXUSR'
+- `sys/stat.h' (POSIX.1): *Note Permission Bits::.
+-
+-`size_t'
+- `stddef.h' (ISO): *Note Important Data Types::.
+-
+-`unsigned int sleep (unsigned int SECONDS)'
+- `unistd.h' (POSIX.1): *Note Sleeping::.
+-
+-`int snprintf (char *S, size_t SIZE, const char *TEMPLATE, ...)'
+- `stdio.h' (GNU): *Note Formatted Output Functions::.
+-
+-`SO_BROADCAST'
+- `sys/socket.h' (BSD): *Note Socket-Level Options::.
+-
+-`int SOCK_DGRAM'
+- `sys/socket.h' (BSD): *Note Communication Styles::.
+-
+-`int socket (int NAMESPACE, int STYLE, int PROTOCOL)'
+- `sys/socket.h' (BSD): *Note Creating a Socket::.
+-
+-`int socketpair (int NAMESPACE, int STYLE, int PROTOCOL, int FILEDES[2])'
+- `sys/socket.h' (BSD): *Note Socket Pairs::.
+-
+-`int SOCK_RAW'
+- `sys/socket.h' (BSD): *Note Communication Styles::.
+-
+-`int SOCK_RDM'
+- `sys/socket.h' (BSD): *Note Communication Styles::.
+-
+-`int SOCK_SEQPACKET'
+- `sys/socket.h' (BSD): *Note Communication Styles::.
+-
+-`int SOCK_STREAM'
+- `sys/socket.h' (BSD): *Note Communication Styles::.
+-
+-`SO_DEBUG'
+- `sys/socket.h' (BSD): *Note Socket-Level Options::.
+-
+-`SO_DONTROUTE'
+- `sys/socket.h' (BSD): *Note Socket-Level Options::.
+-
+-`SO_ERROR'
+- `sys/socket.h' (BSD): *Note Socket-Level Options::.
+-
+-`SO_KEEPALIVE'
+- `sys/socket.h' (BSD): *Note Socket-Level Options::.
+-
+-`SO_LINGER'
+- `sys/socket.h' (BSD): *Note Socket-Level Options::.
+-
+-`int SOL_SOCKET'
+- `sys/socket.h' (BSD): *Note Socket-Level Options::.
+-
+-`SO_OOBINLINE'
+- `sys/socket.h' (BSD): *Note Socket-Level Options::.
+-
+-`SO_RCVBUF'
+- `sys/socket.h' (BSD): *Note Socket-Level Options::.
+-
+-`SO_REUSEADDR'
+- `sys/socket.h' (BSD): *Note Socket-Level Options::.
+-
+-`SO_SNDBUF'
+- `sys/socket.h' (BSD): *Note Socket-Level Options::.
+-
+-`SO_STYLE'
+- `sys/socket.h' (GNU): *Note Socket-Level Options::.
+-
+-`SO_TYPE'
+- `sys/socket.h' (BSD): *Note Socket-Level Options::.
+-
+-`speed_t'
+- `termios.h' (POSIX.1): *Note Line Speed::.
+-
+-`int sprintf (char *S, const char *TEMPLATE, ...)'
+- `stdio.h' (ISO): *Note Formatted Output Functions::.
+-
+-`double sqrt (double X)'
+- `math.h' (ISO): *Note Exponents and Logarithms::.
+-
+-`void srand (unsigned int SEED)'
+- `stdlib.h' (ISO): *Note ISO Random::.
+-
+-`void srandom (unsigned int SEED)'
+- `stdlib.h' (BSD): *Note BSD Random::.
+-
+-`int sscanf (const char *S, const char *TEMPLATE, ...)'
+- `stdio.h' (ISO): *Note Formatted Input Functions::.
+-
+-`sighandler_t ssignal (int SIGNUM, sighandler_t ACTION)'
+- `signal.h' (SVID): *Note Basic Signal Handling::.
+-
+-`int SSIZE_MAX'
+- `limits.h' (POSIX.1): *Note General Limits::.
+-
+-`ssize_t'
+- `unistd.h' (POSIX.1): *Note I/O Primitives::.
+-
+-`int stat (const char *FILENAME, struct stat *BUF)'
+- `sys/stat.h' (POSIX.1): *Note Reading Attributes::.
+-
+-`STDERR_FILENO'
+- `unistd.h' (POSIX.1): *Note Descriptors and Streams::.
+-
+-`FILE * stderr'
+- `stdio.h' (ISO): *Note Standard Streams::.
+-
+-`STDIN_FILENO'
+- `unistd.h' (POSIX.1): *Note Descriptors and Streams::.
+-
+-`FILE * stdin'
+- `stdio.h' (ISO): *Note Standard Streams::.
+-
+-`STDOUT_FILENO'
+- `unistd.h' (POSIX.1): *Note Descriptors and Streams::.
+-
+-`FILE * stdout'
+- `stdio.h' (ISO): *Note Standard Streams::.
+-
+-`char * stpcpy (char *TO, const char *FROM)'
+- `string.h' (Unknown origin): *Note Copying and Concatenation::.
+-
+-`char * stpncpy (char *TO, const char *FROM, size_t SIZE)'
+- `string.h' (GNU): *Note Copying and Concatenation::.
+-
+-`int strcasecmp (const char *S1, const char *S2)'
+- `string.h' (BSD): *Note String/Array Comparison::.
+-
+-`char * strcat (char *TO, const char *FROM)'
+- `string.h' (ISO): *Note Copying and Concatenation::.
+-
+-`char * strchr (const char *STRING, int C)'
+- `string.h' (ISO): *Note Search Functions::.
+-
+-`int strcmp (const char *S1, const char *S2)'
+- `string.h' (ISO): *Note String/Array Comparison::.
+-
+-`int strcoll (const char *S1, const char *S2)'
+- `string.h' (ISO): *Note Collation Functions::.
+-
+-`char * strcpy (char *TO, const char *FROM)'
+- `string.h' (ISO): *Note Copying and Concatenation::.
+-
+-`size_t strcspn (const char *STRING, const char *STOPSET)'
+- `string.h' (ISO): *Note Search Functions::.
+-
+-`char * strdupa (const char *S)'
+- `string.h' (GNU): *Note Copying and Concatenation::.
+-
+-`char * strdup (const char *S)'
+- `string.h' (SVID): *Note Copying and Concatenation::.
+-
+-`int STREAM_MAX'
+- `limits.h' (POSIX.1): *Note General Limits::.
+-
+-`char * strerror (int ERRNUM)'
+- `string.h' (ISO): *Note Error Messages::.
+-
+-`size_t strftime (char *S, size_t SIZE, const char *TEMPLATE, const struct tm
*BROKENTIME)'
+- `time.h' (POSIX.2): *Note Formatting Date and Time::.
+-
+-`size_t strlen (const char *S)'
+- `string.h' (ISO): *Note String Length::.
+-
+-`int strncasecmp (const char *S1, const char *S2, size_t N)'
+- `string.h' (BSD): *Note String/Array Comparison::.
+-
+-`char * strncat (char *TO, const char *FROM, size_t SIZE)'
+- `string.h' (ISO): *Note Copying and Concatenation::.
+-
+-`int strncmp (const char *S1, const char *S2, size_t SIZE)'
+- `string.h' (ISO): *Note String/Array Comparison::.
+-
+-`char * strncpy (char *TO, const char *FROM, size_t SIZE)'
+- `string.h' (ISO): *Note Copying and Concatenation::.
+-
+-`char * strndupa (const char *S, size_t SIZE)'
+- `string.h' (GNU): *Note Copying and Concatenation::.
+-
+-`char * strndup (const char *S, size_t SIZE)'
+- `string.h' (GNU): *Note Copying and Concatenation::.
+-
+-`char * strpbrk (const char *STRING, const char *STOPSET)'
+- `string.h' (ISO): *Note Search Functions::.
+-
+-`char * strrchr (const char *STRING, int C)'
+- `string.h' (ISO): *Note Search Functions::.
+-
+-`char * strsep (char **STRING_PTR, const char *DELIMITER)'
+- `string.h' (BSD): *Note Finding Tokens in a String::.
+-
+-`char * strsignal (int SIGNUM)'
+- `string.h' (GNU): *Note Signal Messages::.
+-
+-`size_t strspn (const char *STRING, const char *SKIPSET)'
+- `string.h' (ISO): *Note Search Functions::.
+-
+-`char * strstr (const char *HAYSTACK, const char *NEEDLE)'
+- `string.h' (ISO): *Note Search Functions::.
+-
+-`double strtod (const char *STRING, char **TAILPTR)'
+- `stdlib.h' (ISO): *Note Parsing of Floats::.
+-
+-`float strtof (const char *STRING, char **TAILPTR)'
+- `stdlib.h' (GNU): *Note Parsing of Floats::.
+-
+-`char * strtok (char *NEWSTRING, const char *DELIMITERS)'
+- `string.h' (ISO): *Note Finding Tokens in a String::.
+-
+-`char * strtok_r (char *NEWSTRING, const char *DELIMITERS, char **SAVE_PTR)'
+- `string.h' (POSIX): *Note Finding Tokens in a String::.
+-
+-`long double strtold (const char *STRING, char **TAILPTR)'
+- `stdlib.h' (GNU): *Note Parsing of Floats::.
+-
+-`long int strtol (const char *STRING, char **TAILPTR, int BASE)'
+- `stdlib.h' (ISO): *Note Parsing of Integers::.
+-
+-`long long int strtoll (const char *STRING, char **TAILPTR, int BASE)'
+- `stdlib.h' (GNU): *Note Parsing of Integers::.
+-
+-`long long int strtoq (const char *STRING, char **TAILPTR, int BASE)'
+- `stdlib.h' (BSD): *Note Parsing of Integers::.
+-
+-`unsigned long int strtoul (const char *STRING, char **TAILPTR, int BASE)'
+- `stdlib.h' (ISO): *Note Parsing of Integers::.
+-
+-`unsigned long long int strtoull (const char *STRING, char **TAILPTR, int
BASE)'
+- `stdlib.h' (GNU): *Note Parsing of Integers::.
+-
+-`unsigned long long int strtouq (const char *STRING, char **TAILPTR, int
BASE)'
+- `stdlib.h' (BSD): *Note Parsing of Integers::.
+-
+-`struct dirent'
+- `dirent.h' (POSIX.1): *Note Directory Entries::.
+-
+-`struct flock'
+- `fcntl.h' (POSIX.1): *Note File Locks::.
+-
+-`struct group'
+- `grp.h' (POSIX.1): *Note Group Data Structure::.
+-
+-`struct hostent'
+- `netdb.h' (BSD): *Note Host Names::.
+-
+-`struct in_addr'
+- `netinet/in.h' (BSD): *Note Host Address Data Type::.
+-
+-`struct itimerval'
+- `sys/time.h' (BSD): *Note Setting an Alarm::.
+-
+-`struct lconv'
+- `locale.h' (ISO): *Note Numeric Formatting::.
+-
+-`struct linger'
+- `sys/socket.h' (BSD): *Note Socket-Level Options::.
+-
+-`struct msghdr'
+- `sys/socket.h' (BSD): *Note Receiving Datagrams::.
+-
+-`struct mstats'
+- `malloc.h' (GNU): *Note Statistics of Malloc::.
+-
+-`struct netent'
+- `netdb.h' (BSD): *Note Networks Database::.
+-
+-`struct obstack'
+- `obstack.h' (GNU): *Note Creating Obstacks::.
+-
+-`struct option'
+- `getopt.h' (GNU): *Note Long Options::.
+-
+-`struct passwd'
+- `pwd.h' (POSIX.1): *Note User Data Structure::.
+-
+-`struct printf_info'
+- `printf.h' (GNU): *Note Conversion Specifier Options::.
+-
+-`struct protoent'
+- `netdb.h' (BSD): *Note Protocols Database::.
+-
+-`struct rlimit'
+- `sys/resource.h' (BSD): *Note Limits on Resources::.
+-
+-`struct rusage'
+- `sys/resource.h' (BSD): *Note Resource Usage::.
+-
+-`struct servent'
+- `netdb.h' (BSD): *Note Services Database::.
+-
+-`struct sigaction'
+- `signal.h' (POSIX.1): *Note Advanced Signal Handling::.
+-
+-`struct sigaltstack'
+- `signal.h' (BSD): *Note Signal Stack::.
+-
+-`struct sigstack'
+- `signal.h' (BSD): *Note Signal Stack::.
+-
+-`struct sigvec'
+- `signal.h' (BSD): *Note BSD Handler::.
+-
+-`struct sockaddr'
+- `sys/socket.h' (BSD): *Note Address Formats::.
+-
+-`struct sockaddr_in'
+- `netinet/in.h' (BSD): *Note Internet Address Format::.
+-
+-`struct sockaddr_un'
+- `sys/un.h' (BSD): *Note File Namespace Details::.
+-
+-`struct stat'
+- `sys/stat.h' (POSIX.1): *Note Attribute Meanings::.
+-
+-`struct termios'
+- `termios.h' (POSIX.1): *Note Mode Data Types::.
+-
+-`struct timeval'
+- `sys/time.h' (BSD): *Note High-Resolution Calendar::.
+-
+-`struct timezone'
+- `sys/time.h' (BSD): *Note High-Resolution Calendar::.
+-
+-`struct tm'
+- `time.h' (ISO): *Note Broken-down Time::.
+-
+-`struct tms'
+- `sys/times.h' (POSIX.1): *Note Detailed CPU Time::.
+-
+-`struct utimbuf'
+- `time.h' (POSIX.1): *Note File Times::.
+-
+-`struct utsname'
+- `sys/utsname.h' (POSIX.1): *Note Hardware/Software Type ID::.
+-
+-`size_t strxfrm (char *TO, const char *FROM, size_t SIZE)'
+- `string.h' (ISO): *Note Collation Functions::.
+-
+-`_SVID_SOURCE'
+- (GNU): *Note Feature Test Macros::.
+-
+-`int SV_INTERRUPT'
+- `signal.h' (BSD): *Note BSD Handler::.
+-
+-`int SV_ONSTACK'
+- `signal.h' (BSD): *Note BSD Handler::.
+-
+-`int SV_RESETHAND'
+- `signal.h' (Sun): *Note BSD Handler::.
+-
+-`int symlink (const char *OLDNAME, const char *NEWNAME)'
+- `unistd.h' (BSD): *Note Symbolic Links::.
+-
+-`long int sysconf (int PARAMETER)'
+- `unistd.h' (POSIX.1): *Note Sysconf Definition::.
+-
+-`int system (const char *COMMAND)'
+- `stdlib.h' (ISO): *Note Running a Command::.
+-
+-`double tanh (double X)'
+- `math.h' (ISO): *Note Hyperbolic Functions::.
+-
+-`double tan (double X)'
+- `math.h' (ISO): *Note Trig Functions::.
+-
+-`int tcdrain (int FILEDES)'
+- `termios.h' (POSIX.1): *Note Line Control::.
+-
+-`tcflag_t'
+- `termios.h' (POSIX.1): *Note Mode Data Types::.
+-
+-`int tcflow (int FILEDES, int ACTION)'
+- `termios.h' (POSIX.1): *Note Line Control::.
+-
+-`int tcflush (int FILEDES, int QUEUE)'
+- `termios.h' (POSIX.1): *Note Line Control::.
+-
+-`int tcgetattr (int FILEDES, struct termios *TERMIOS-P)'
+- `termios.h' (POSIX.1): *Note Mode Functions::.
+-
+-`pid_t tcgetpgrp (int FILEDES)'
+- `unistd.h' (POSIX.1): *Note Terminal Access Functions::.
+-
+-`TCSADRAIN'
+- `termios.h' (POSIX.1): *Note Mode Functions::.
+-
+-`TCSAFLUSH'
+- `termios.h' (POSIX.1): *Note Mode Functions::.
+-
+-`TCSANOW'
+- `termios.h' (POSIX.1): *Note Mode Functions::.
+-
+-`TCSASOFT'
+- `termios.h' (BSD): *Note Mode Functions::.
+-
+-`int tcsendbreak (int FILEDES, int DURATION)'
+- `termios.h' (POSIX.1): *Note Line Control::.
+-
+-`int tcsetattr (int FILEDES, int WHEN, const struct termios *TERMIOS-P)'
+- `termios.h' (POSIX.1): *Note Mode Functions::.
+-
+-`int tcsetpgrp (int FILEDES, pid_t PGID)'
+- `unistd.h' (POSIX.1): *Note Terminal Access Functions::.
+-
+-`off_t telldir (DIR *DIRSTREAM)'
+- `dirent.h' (BSD): *Note Random Access Directory::.
+-
+-`TEMP_FAILURE_RETRY (EXPRESSION)'
+- `unistd.h' (GNU): *Note Interrupted Primitives::.
+-
+-`char * tempnam (const char *DIR, const char *PREFIX)'
+- `stdio.h' (SVID): *Note Temporary Files::.
+-
+-`time_t time (time_t *RESULT)'
+- `time.h' (ISO): *Note Simple Calendar Time::.
+-
+-`clock_t times (struct tms *BUFFER)'
+- `sys/times.h' (POSIX.1): *Note Detailed CPU Time::.
+-
+-`time_t'
+- `time.h' (ISO): *Note Simple Calendar Time::.
+-
+-`long int timezone'
+- `time.h' (SVID): *Note Time Zone Functions::.
+-
+-`FILE * tmpfile (void)'
+- `stdio.h' (ISO): *Note Temporary Files::.
+-
+-`int TMP_MAX'
+- `stdio.h' (ISO): *Note Temporary Files::.
+-
+-`char * tmpnam (char *RESULT)'
+- `stdio.h' (ISO): *Note Temporary Files::.
+-
+-`char * tmpnam_r (char *RESULT)'
+- `stdio.h' (GNU): *Note Temporary Files::.
+-
+-`int toascii (int C)'
+- `ctype.h' (SVID, BSD): *Note Case Conversion::.
+-
+-`int _tolower (int C)'
+- `ctype.h' (SVID): *Note Case Conversion::.
+-
+-`int tolower (int C)'
+- `ctype.h' (ISO): *Note Case Conversion::.
+-
+-`tcflag_t TOSTOP'
+- `termios.h' (POSIX.1): *Note Local Modes::.
+-
+-`int _toupper (int C)'
+- `ctype.h' (SVID): *Note Case Conversion::.
+-
+-`int toupper (int C)'
+- `ctype.h' (ISO): *Note Case Conversion::.
+-
+-`TRY_AGAIN'
+- `netdb.h' (BSD): *Note Host Names::.
+-
+-`char * ttyname (int FILEDES)'
+- `unistd.h' (POSIX.1): *Note Is It a Terminal::.
+-
+-`char * tzname [2]'
+- `time.h' (POSIX.1): *Note Time Zone Functions::.
+-
+-`int TZNAME_MAX'
+- `limits.h' (POSIX.1): *Note General Limits::.
+-
+-`void tzset (void)'
+- `time.h' (POSIX.1): *Note Time Zone Functions::.
+-
+-`UCHAR_MAX'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`uid_t'
+- `sys/types.h' (POSIX.1): *Note Reading Persona::.
+-
+-`UINT_MAX'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`ULONG_LONG_MAX'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`ULONG_MAX'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`mode_t umask (mode_t MASK)'
+- `sys/stat.h' (POSIX.1): *Note Setting Permissions::.
+-
+-`int uname (struct utsname *INFO)'
+- `sys/utsname.h' (POSIX.1): *Note Hardware/Software Type ID::.
+-
+-`int ungetc (int C, FILE *STREAM)'
+- `stdio.h' (ISO): *Note How Unread::.
+-
+-`union wait'
+- `sys/wait.h' (BSD): *Note BSD Wait Functions::.
+-
+-`int unlink (const char *FILENAME)'
+- `unistd.h' (POSIX.1): *Note Deleting Files::.
+-
+-`USHRT_MAX'
+- `limits.h' (ISO): *Note Range of Type::.
+-
+-`int utime (const char *FILENAME, const struct utimbuf *TIMES)'
+- `time.h' (POSIX.1): *Note File Times::.
+-
+-`int utimes (const char *FILENAME, struct timeval TVP[2])'
+- `sys/time.h' (BSD): *Note File Times::.
+-
+-`va_alist'
+- `varargs.h' (Unix): *Note Old Varargs::.
+-
+-`TYPE va_arg (va_list AP, TYPE)'
+- `stdarg.h' (ISO): *Note Argument Macros::.
+-
+-`va_dcl'
+- `varargs.h' (Unix): *Note Old Varargs::.
+-
+-`void va_end (va_list AP)'
+- `stdarg.h' (ISO): *Note Argument Macros::.
+-
+-`va_list'
+- `stdarg.h' (ISO): *Note Argument Macros::.
+-
+-`void * valloc (size_t SIZE)'
+- `malloc.h', `stdlib.h' (BSD): *Note Aligned Memory Blocks::.
+-
+-`int vasprintf (char **PTR, const char *TEMPLATE, va_list AP)'
+- `stdio.h' (GNU): *Note Variable Arguments Output::.
+-
+-`void va_start (va_list AP)'
+- `varargs.h' (Unix): *Note Old Varargs::.
+-
+-`void va_start (va_list AP, LAST-REQUIRED)'
+- `stdarg.h' (ISO): *Note Argument Macros::.
+-
+-`int VDISCARD'
+- `termios.h' (BSD): *Note Other Special::.
+-
+-`int VDSUSP'
+- `termios.h' (BSD): *Note Signal Characters::.
+-
+-`int VEOF'
+- `termios.h' (POSIX.1): *Note Editing Characters::.
+-
+-`int VEOL2'
+- `termios.h' (BSD): *Note Editing Characters::.
+-
+-`int VEOL'
+- `termios.h' (POSIX.1): *Note Editing Characters::.
+-
+-`int VERASE'
+- `termios.h' (POSIX.1): *Note Editing Characters::.
+-
+-`pid_t vfork (void)'
+- `unistd.h' (BSD): *Note Creating a Process::.
+-
+-`int vfprintf (FILE *STREAM, const char *TEMPLATE, va_list AP)'
+- `stdio.h' (ISO): *Note Variable Arguments Output::.
+-
+-`int vfscanf (FILE *STREAM, const char *TEMPLATE, va_list AP)'
+- `stdio.h' (GNU): *Note Variable Arguments Input::.
+-
+-`int VINTR'
+- `termios.h' (POSIX.1): *Note Signal Characters::.
+-
+-`int VKILL'
+- `termios.h' (POSIX.1): *Note Editing Characters::.
+-
+-`int VLNEXT'
+- `termios.h' (BSD): *Note Other Special::.
+-
+-`int VMIN'
+- `termios.h' (POSIX.1): *Note Noncanonical Input::.
+-
+-`int vprintf (const char *TEMPLATE, va_list AP)'
+- `stdio.h' (ISO): *Note Variable Arguments Output::.
+-
+-`int VQUIT'
+- `termios.h' (POSIX.1): *Note Signal Characters::.
+-
+-`int VREPRINT'
+- `termios.h' (BSD): *Note Editing Characters::.
+-
+-`int vscanf (const char *TEMPLATE, va_list AP)'
+- `stdio.h' (GNU): *Note Variable Arguments Input::.
+-
+-`int vsnprintf (char *S, size_t SIZE, const char *TEMPLATE, va_list AP)'
+- `stdio.h' (GNU): *Note Variable Arguments Output::.
+-
+-`int vsprintf (char *S, const char *TEMPLATE, va_list AP)'
+- `stdio.h' (ISO): *Note Variable Arguments Output::.
+-
+-`int vsscanf (const char *S, const char *TEMPLATE, va_list AP)'
+- `stdio.h' (GNU): *Note Variable Arguments Input::.
+-
+-`int VSTART'
+- `termios.h' (POSIX.1): *Note Start/Stop Characters::.
+-
+-`int VSTATUS'
+- `termios.h' (BSD): *Note Other Special::.
+-
+-`int VSTOP'
+- `termios.h' (POSIX.1): *Note Start/Stop Characters::.
+-
+-`int VSUSP'
+- `termios.h' (POSIX.1): *Note Signal Characters::.
+-
+-`int VTIME'
+- `termios.h' (POSIX.1): *Note Noncanonical Input::.
+-
+-`int VWERASE'
+- `termios.h' (BSD): *Note Editing Characters::.
+-
+-`pid_t wait3 (union wait *STATUS-PTR, int OPTIONS, struct rusage *USAGE)'
+- `sys/wait.h' (BSD): *Note BSD Wait Functions::.
+-
+-`pid_t wait4 (pid_t PID, int *STATUS-PTR, int OPTIONS, struct rusage *USAGE)'
+- `sys/wait.h' (BSD): *Note Process Completion::.
+-
+-`pid_t wait (int *STATUS-PTR)'
+- `sys/wait.h' (POSIX.1): *Note Process Completion::.
+-
+-`pid_t waitpid (pid_t PID, int *STATUS-PTR, int OPTIONS)'
+- `sys/wait.h' (POSIX.1): *Note Process Completion::.
+-
+-`WCHAR_MAX'
+- `limits.h' (GNU): *Note Range of Type::.
+-
+-`wchar_t'
+- `stddef.h' (ISO): *Note Wide Char Intro::.
+-
+-`int WCOREDUMP (int STATUS)'
+- `sys/wait.h' (BSD): *Note Process Completion Status::.
+-
+-`size_t wcstombs (char *STRING, const wchar_t WSTRING, size_t SIZE)'
+- `stdlib.h' (ISO): *Note Wide String Conversion::.
+-
+-`int wctomb (char *STRING, wchar_t WCHAR)'
+- `stdlib.h' (ISO): *Note Converting One Char::.
+-
+-`int WEXITSTATUS (int STATUS)'
+- `sys/wait.h' (POSIX.1): *Note Process Completion Status::.
+-
+-`int WIFEXITED (int STATUS)'
+- `sys/wait.h' (POSIX.1): *Note Process Completion Status::.
+-
+-`int WIFSIGNALED (int STATUS)'
+- `sys/wait.h' (POSIX.1): *Note Process Completion Status::.
+-
+-`int WIFSTOPPED (int STATUS)'
+- `sys/wait.h' (POSIX.1): *Note Process Completion Status::.
+-
+-`int W_OK'
+- `unistd.h' (POSIX.1): *Note Testing File Access::.
+-
+-`int wordexp (const char *WORDS, wordexp_t *WORD-VECTOR-PTR, int FLAGS)'
+- `wordexp.h' (POSIX.2): *Note Calling Wordexp::.
+-
+-`wordexp_t'
+- `wordexp.h' (POSIX.2): *Note Calling Wordexp::.
+-
+-`void wordfree (wordexp_t *WORD-VECTOR-PTR)'
+- `wordexp.h' (POSIX.2): *Note Calling Wordexp::.
+-
+-`WRDE_APPEND'
+- `wordexp.h' (POSIX.2): *Note Flags for Wordexp::.
+-
+-`WRDE_BADCHAR'
+- `wordexp.h' (POSIX.2): *Note Calling Wordexp::.
+-
+-`WRDE_BADVAL'
+- `wordexp.h' (POSIX.2): *Note Calling Wordexp::.
+-
+-`WRDE_CMDSUB'
+- `wordexp.h' (POSIX.2): *Note Calling Wordexp::.
+-
+-`WRDE_DOOFFS'
+- `wordexp.h' (POSIX.2): *Note Flags for Wordexp::.
+-
+-`WRDE_NOCMD'
+- `wordexp.h' (POSIX.2): *Note Flags for Wordexp::.
+-
+-`WRDE_NOSPACE'
+- `wordexp.h' (POSIX.2): *Note Calling Wordexp::.
+-
+-`WRDE_REUSE'
+- `wordexp.h' (POSIX.2): *Note Flags for Wordexp::.
+-
+-`WRDE_SHOWERR'
+- `wordexp.h' (POSIX.2): *Note Flags for Wordexp::.
+-
+-`WRDE_SYNTAX'
+- `wordexp.h' (POSIX.2): *Note Calling Wordexp::.
+-
+-`WRDE_UNDEF'
+- `wordexp.h' (POSIX.2): *Note Flags for Wordexp::.
+-
+-`ssize_t write (int FILEDES, const void *BUFFER, size_t SIZE)'
+- `unistd.h' (POSIX.1): *Note I/O Primitives::.
+-
+-`int WSTOPSIG (int STATUS)'
+- `sys/wait.h' (POSIX.1): *Note Process Completion Status::.
+-
+-`int WTERMSIG (int STATUS)'
+- `sys/wait.h' (POSIX.1): *Note Process Completion Status::.
+-
+-`int X_OK'
+- `unistd.h' (POSIX.1): *Note Testing File Access::.
+-
+-`_XOPEN_SOURCE'
+- (XOPEN): *Note Feature Test Macros::.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-29
glibc-2.0.1/manual/libc.info-29
+--- ../glibc-2.0.1/manual/libc.info-29 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-29 1970-01-01 01:00:00.000000000 +0100
+@@ -1,995 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+- This file documents the GNU C library.
+-
+- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+- Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+- Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+- Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: Maintenance, Next: Copying, Prev: Library Summary,
Up: Top
+-
+-Library Maintenance
+-*******************
+-
+-* Menu:
+-
+-* Installation:: How to configure, compile and
+- install the GNU C library.
+-* Reporting Bugs:: How to report bugs (if you want to
+- get them fixed) and other troubles
+- you may have with the GNU C library.
+-* Source Layout:: How to add new functions or header files
+- to the GNU C library.
+-* Porting:: How to port the GNU C library to
+- a new machine or operating system.
+-* Contributors:: Contributors to the GNU C Library.
+-
+-
+-File: libc.info, Node: Installation, Next: Reporting Bugs, Up: Maintenance
+-
+-How to Install the GNU C Library
+-================================
+-
+- Installation of the GNU C library is relatively simple, but usually
+-requires several GNU tools to be installed already.
+-
+-* Menu:
+-
+-* Tools for Installation:: We recommend using these tools to build.
+-* Supported Configurations:: What systems the GNU C library runs on.
+-
+- To configure the GNU C library for your system, run the shell script
+-`configure' with `sh'. Use an argument which is the conventional GNU
+-name for your system configuration--for example, `sparc-sun-sunos4.1',
+-for a Sun 4 running SunOS 4.1. *Note Installation:
+-(gcc.info)Installation, for a full description of standard GNU
+-configuration names. If you omit the configuration name, `configure'
+-will try to guess one for you by inspecting the system it is running
+-on. It may or may not be able to come up with a guess, and the its
+-guess might be wrong. `configure' will tell you the canonical name of
+-the chosen configuration before proceeding.
+-
+- Here are some options that you should specify (if appropriate) when
+-you run `configure':
+-
+-`--with-gnu-ld'
+- Use this option if you plan to use GNU `ld' to link programs with
+- the GNU C Library. (We strongly recommend that you do.) This
+- option enables use of features that exist only in GNU `ld'; so if
+- you configure for GNU `ld' you must use GNU `ld' *every time* you
+- link with the GNU C Library, and when building it.
+-
+-`--with-gnu-as'
+- Use this option if you plan to use the GNU assembler, `gas', when
+- building the GNU C Library. On some systems, the library may not
+- build properly if you do *not* use `gas'.
+-
+-`--with-gnu-binutils'
+- This option implies both `--with-gnu-ld' and `--with-gnu-as'. On
+- systems where GNU tools are the system tools, there is no need to
+- specify this option. These include GNU, GNU/Linux, and free BSD
+- systems.
+-
+-`--without-fp'
+-`--nfp'
+- Use this option if your computer lacks hardware floating-point
+- support.
+-
+-`--prefix=DIRECTORY'
+- Install machine-independent data files in subdirectories of
+- `DIRECTORY'. (You can also set this in `configparms'; see below.)
+-
+-`--exec-prefix=DIRECTORY'
+- Install the library and other machine-dependent files in
+- subdirectories of `DIRECTORY'. (You can also set this in
+- `configparms'; see below.)
+-
+-`--enable-shared'
+-`--disable-shared'
+- Enable or disable building of an ELF shared library on systems that
+- support it. The default is to build the shared library on systems
+- using ELF when the GNU `binutils' are available.
+-
+-`--enable-profile'
+-`--disable-profile'
+- Enable or disable building of the profiled C library, `-lc_p'. The
+- default is to build the profiled library. You may wish to disable
+- it if you don't plan to do profiling, because it doubles the build
+- time of compiling just the unprofiled static library.
+-
+-`--enable-omitfp'
+- Enable building a highly-optimized but possibly undebuggable
+- static C library. This causes the normal static and shared (if
+- enabled) C libraries to be compiled with maximal optimization,
+- including the `-fomit-frame-pointer' switch that makes debugging
+- impossible on many machines, and without debugging information
+- (which makes the binaries substantially smaller). An additional
+- static library is compiled with no optimization and full debugging
+- information, and installed as `-lc_g'.
+-
+- The simplest way to run `configure' is to do it in the directory
+-that contains the library sources. This prepares to build the library
+-in that very directory.
+-
+- You can prepare to build the library in some other directory by going
+-to that other directory to run `configure'. In order to run configure,
+-you will have to specify a directory for it, like this:
+-
+- mkdir sun4
+- cd sun4
+- ../configure sparc-sun-sunos4.1
+-
+-`configure' looks for the sources in whatever directory you specified
+-for finding `configure' itself. It does not matter where in the file
+-system the source and build directories are--as long as you specify the
+-source directory when you run `configure', you will get the proper
+-results.
+-
+- This feature lets you keep sources and binaries in different
+-directories, and that makes it easy to build the library for several
+-different machines from the same set of sources. Simply create a build
+-directory for each target machine, and run `configure' in that
+-directory specifying the target machine's configuration name.
+-
+- The library has a number of special-purpose configuration parameters.
+-These are defined in the file `Makeconfig'; see the comments in that
+-file for the details.
+-
+- But don't edit the file `Makeconfig' yourself--instead, create a
+-file `configparms' in the directory where you are building the library,
+-and define in that file the parameters you want to specify.
+-`configparms' should *not* be an edited copy of `Makeconfig'; specify
+-only the parameters that you want to override. To see how to set these
+-parameters, find the section of `Makeconfig' that says "These are the
+-configuration variables." Then for each parameter that you want to
+-change, copy the definition from `Makeconfig' to your new `configparms'
+-file, and change the value as appropriate for your system.
+-
+- It is easy to configure the GNU C library for cross-compilation by
+-setting a few variables in `configparms'. Set `CC' to the
+-cross-compiler for the target you configured the library for; it is
+-important to use this same `CC' value when running `configure', like
+-this: `CC=TARGET-gcc configure TARGET'. Set `BUILD_CC' to the compiler
+-to use for for programs run on the build system as part of compiling
+-the library. You may need to set `AR' and `RANLIB' to cross-compiling
+-versions of `ar' and `ranlib' if the native tools are not configured to
+-work with object files for the target you configured for.
+-
+- Some of the machine-dependent code for some machines uses extensions
+-in the GNU C compiler, so you may need to compile the library with GCC.
+-(In fact, all of the existing complete ports require GCC.)
+-
+- To build the library and related programs, type `make'. This will
+-produce a lot of output, some of which may look like errors from `make'
+-(but isn't). Look for error messages from `make' containing `***'.
+-Those indicate that something is really wrong.
+-
+- To build and run some test programs which exercise some of the
+-library facilities, type `make check'. This will produce several files
+-with names like `PROGRAM.out'.
+-
+- To format the `GNU C Library Reference Manual' for printing, type
+-`make dvi'.
+-
+- To install the library and its header files, and the Info files of
+-the manual, type `make install'. This will build things if necessary,
+-before installing them.
+-
+-
+-File: libc.info, Node: Tools for Installation, Next: Supported
Configurations, Up: Installation
+-
+-Recommended Tools to Install the GNU C Library
+-----------------------------------------------
+-
+- We recommend installing the following GNU tools before attempting to
+-build the GNU C library:
+-
+- * `make' 3.75
+-
+- You need the latest version of GNU `make'. Modifying the GNU C
+- Library to work with other `make' programs would be so hard that we
+- recommend you port GNU `make' instead. *Really.* We recommend
+- version GNU `make' version 3.75 or later.
+-
+- * GCC 2.7.2
+-
+- On most platforms, the GNU C library can only be compiled with the
+- GNU C compiler. We recommend GCC version 2.7.2 or later; earlier
+- versions may have problems.
+-
+- * `binutils' 2.7
+-
+- Using the GNU `binutils' (assembler, linker, and related tools) is
+- preferable when possible, and they are required to build an ELF
+- shared C library. We recommend `binutils' version 2.7 or later;
+- earlier versions are known to have problems or to not support all
+- architectures.
+-
+-
+-File: libc.info, Node: Supported Configurations, Prev: Tools for
Installation, Up: Installation
+-
+-Supported Configurations
+-------------------------
+-
+- The GNU C Library currently supports configurations that match the
+-following patterns:
+-
+- alpha-dec-osf1
+- alpha-ANYTHING-linux
+- alpha-ANYTHING-linuxecoff
+- iX86-ANYTHING-bsd4.3
+- iX86-ANYTHING-gnu
+- iX86-ANYTHING-isc2.2
+- iX86-ANYTHING-isc3.N
+- iX86-ANYTHING-linux
+- iX86-ANYTHING-sco3.2
+- iX86-ANYTHING-sco3.2v4
+- iX86-ANYTHING-sysv
+- iX86-ANYTHING-sysv4
+- iX86-force_cpu386-none
+- iX86-sequent-bsd
+- i960-nindy960-none
+- m68k-hp-bsd4.3
+- m68k-mvme135-none
+- m68k-mvme136-none
+- m68k-sony-newsos3
+- m68k-sony-newsos4
+- m68k-sun-sunos4.N
+- mips-dec-ultrix4.N
+- mips-sgi-irix4.N
+- sparc-sun-solaris2.N
+- sparc-sun-sunos4.N
+-
+- Each case of `iX86' can be `i386', `i486', `i586', or `i686'.. All
+-of those configurations produce a library that can run on any of these
+-processors. The library will be optimized for the specified processor,
+-but will not use instructions not available on all of them.
+-
+- While no other configurations are supported, there are handy aliases
+-for these few. (These aliases work in other GNU software as well.)
+-
+- decstation
+- hp320-bsd4.3 hp300bsd
+- i486-gnu
+- i586-linux
+- i386-sco
+- i386-sco3.2v4
+- i386-sequent-dynix
+- i386-svr4
+- news
+- sun3-sunos4.N sun3
+- sun4-solaris2.N sun4-sunos5.N
+- sun4-sunos4.N sun4
+-
+-
+-File: libc.info, Node: Reporting Bugs, Next: Source Layout, Prev:
Installation, Up: Maintenance
+-
+-Reporting Bugs
+-==============
+-
+- There are probably bugs in the GNU C library. There are certainly
+-errors and omissions in this manual. If you report them, they will get
+-fixed. If you don't, no one will ever know about them and they will
+-remain unfixed for all eternity, if not longer.
+-
+- To report a bug, first you must find it. Hopefully, this will be the
+-hard part. Once you've found a bug, make sure it's really a bug. A
+-good way to do this is to see if the GNU C library behaves the same way
+-some other C library does. If so, probably you are wrong and the
+-libraries are right (but not necessarily). If not, one of the libraries
+-is probably wrong.
+-
+- Once you're sure you've found a bug, try to narrow it down to the
+-smallest test case that reproduces the problem. In the case of a C
+-library, you really only need to narrow it down to one library function
+-call, if possible. This should not be too difficult.
+-
+- The final step when you have a simple test case is to report the bug.
+-When reporting a bug, send your test case, the results you got, the
+-results you expected, what you think the problem might be (if you've
+-thought of anything), your system type, and the version of the GNU C
+-library which you are using. Also include the files `config.status'
+-and `config.make' which are created by running `configure'; they will
+-be in whatever directory was current when you ran `configure'.
+-
+- If you think you have found some way in which the GNU C library does
+-not conform to the ISO and POSIX standards (*note Standards and
+-Portability::.), that is definitely a bug. Report it!
+-
+- Send bug reports to the Internet address address@hidden'
+-or the UUCP path `mit-eddie!prep.ai.mit.edu!bug-glibc'. If you have
+-other problems with installation or use, please report those as well.
+-
+- If you are not sure how a function should behave, and this manual
+-doesn't tell you, that's a bug in the manual. Report that too! If the
+-function's behavior disagrees with the manual, then either the library
+-or the manual has a bug, so report the disagreement. If you find any
+-errors or omissions in this manual, please report them to the Internet
+-address address@hidden' or the UUCP path
+-`mit-eddie!prep.ai.mit.edu!bug-glibc-manual'.
+-
+-
+-File: libc.info, Node: Source Layout, Next: Porting, Prev: Reporting Bugs,
Up: Maintenance
+-
+-Adding New Functions
+-====================
+-
+- The process of building the library is driven by the makefiles, which
+-make heavy use of special features of GNU `make'. The makefiles are
+-very complex, and you probably don't want to try to understand them.
+-But what they do is fairly straightforward, and only requires that you
+-define a few variables in the right places.
+-
+- The library sources are divided into subdirectories, grouped by
+-topic.
+-
+- The `string' subdirectory has all the string-manipulation functions,
+-`math' has all the mathematical functions, etc.
+-
+- Each subdirectory contains a simple makefile, called `Makefile',
+-which defines a few `make' variables and then includes the global
+-makefile `Rules' with a line like:
+-
+- include ../Rules
+-
+-The basic variables that a subdirectory makefile defines are:
+-
+-`subdir'
+- The name of the subdirectory, for example `stdio'. This variable
+- *must* be defined.
+-
+-`headers'
+- The names of the header files in this section of the library, such
+- as `stdio.h'.
+-
+-`routines'
+-`aux'
+- The names of the modules (source files) in this section of the
+- library. These should be simple names, such as `strlen' (rather
+- than complete file names, such as `strlen.c'). Use `routines' for
+- modules that define functions in the library, and `aux' for
+- auxiliary modules containing things like data definitions. But the
+- values of `routines' and `aux' are just concatenated, so there
+- really is no practical difference.
+-
+-`tests'
+- The names of test programs for this section of the library. These
+- should be simple names, such as `tester' (rather than complete file
+- names, such as `tester.c'). `make tests' will build and run all
+- the test programs. If a test program needs input, put the test
+- data in a file called `TEST-PROGRAM.input'; it will be given to
+- the test program on its standard input. If a test program wants
+- to be run with arguments, put the arguments (all on a single line)
+- in a file called `TEST-PROGRAM.args'. Test programs should exit
+- with zero status when the test passes, and nonzero status when the
+- test indicates a bug in the library or error in building.
+-
+-`others'
+- The names of "other" programs associated with this section of the
+- library. These are programs which are not tests per se, but are
+- other small programs included with the library. They are built by
+- `make others'.
+-
+-`install-lib'
+-`install-data'
+-`install'
+- Files to be installed by `make install'. Files listed in
+- `install-lib' are installed in the directory specified by `libdir'
+- in `configparms' or `Makeconfig' (*note Installation::.). Files
+- listed in `install-data' are installed in the directory specified
+- by `datadir' in `configparms' or `Makeconfig'. Files listed in
+- `install' are installed in the directory specified by `bindir' in
+- `configparms' or `Makeconfig'.
+-
+-`distribute'
+- Other files from this subdirectory which should be put into a
+- distribution tar file. You need not list here the makefile itself
+- or the source and header files listed in the other standard
+- variables. Only define `distribute' if there are files used in an
+- unusual way that should go into the distribution.
+-
+-`generated'
+- Files which are generated by `Makefile' in this subdirectory.
+- These files will be removed by `make clean', and they will never
+- go into a distribution.
+-
+-`extra-objs'
+- Extra object files which are built by `Makefile' in this
+- subdirectory. This should be a list of file names like `foo.o';
+- the files will actually be found in whatever directory object
+- files are being built in. These files will be removed by
+- `make clean'. This variable is used for secondary object files
+- needed to build `others' or `tests'.
+-
+-
+-File: libc.info, Node: Porting, Next: Contributors, Prev: Source Layout,
Up: Maintenance
+-
+-Porting the GNU C Library
+-=========================
+-
+- The GNU C library is written to be easily portable to a variety of
+-machines and operating systems. Machine- and operating system-dependent
+-functions are well separated to make it easy to add implementations for
+-new machines or operating systems. This section describes the layout of
+-the library source tree and explains the mechanisms used to select
+-machine-dependent code to use.
+-
+- All the machine-dependent and operating system-dependent files in the
+-library are in the subdirectory `sysdeps' under the top-level library
+-source directory. This directory contains a hierarchy of
+-subdirectories (*note Hierarchy Conventions::.).
+-
+- Each subdirectory of `sysdeps' contains source files for a
+-particular machine or operating system, or for a class of machine or
+-operating system (for example, systems by a particular vendor, or all
+-machines that use IEEE 754 floating-point format). A configuration
+-specifies an ordered list of these subdirectories. Each subdirectory
+-implicitly appends its parent directory to the list. For example,
+-specifying the list `unix/bsd/vax' is equivalent to specifying the list
+-`unix/bsd/vax unix/bsd unix'. A subdirectory can also specify that it
+-implies other subdirectories which are not directly above it in the
+-directory hierarchy. If the file `Implies' exists in a subdirectory,
+-it lists other subdirectories of `sysdeps' which are appended to the
+-list, appearing after the subdirectory containing the `Implies' file.
+-Lines in an `Implies' file that begin with a `#' character are ignored
+-as comments. For example, `unix/bsd/Implies' contains:
+- # BSD has Internet-related things.
+- unix/inet
+-
+-and `unix/Implies' contains:
+- posix
+-
+-So the final list is `unix/bsd/vax unix/bsd unix/inet unix posix'.
+-
+- `sysdeps' has two "special" subdirectories, called `generic' and
+-`stub'. These two are always implicitly appended to the list of
+-subdirectories (in that order), so you needn't put them in an `Implies'
+-file, and you should not create any subdirectories under them intended
+-to be new specific categories. `generic' is for things that can be
+-implemented in machine-independent C, using only other
+-machine-independent functions in the C library. `stub' is for "stub"
+-versions of functions which cannot be implemented on a particular
+-machine or operating system. The stub functions always return an
+-error, and set `errno' to `ENOSYS' (Function not implemented). *Note
+-Error Reporting::.
+-
+- A source file is known to be system-dependent by its having a
+-version in `generic' or `stub'; every generally-available function whose
+-implementation is system-dependent in should have either a generic or
+-stub implementation (there is no point in having both). Some rare
+-functions are only useful on specific systems and aren't defined at all
+-on others; these do not appear anywhere in the system-independent
+-source code or makefiles (including the `generic' and `stub'
+-directories), only in the system-dependent `Makefile' in the specific
+-system's subdirectory.
+-
+- If you come across a file that is in one of the main source
+-directories (`string', `stdio', etc.), and you want to write a machine-
+-or operating system-dependent version of it, move the file into
+-`sysdeps/generic' and write your new implementation in the appropriate
+-system-specific subdirectory. Note that if a file is to be
+-system-dependent, it *must not* appear in one of the main source
+-directories.
+-
+- There are a few special files that may exist in each subdirectory of
+-`sysdeps':
+-
+-`Makefile'
+- A makefile for this machine or operating system, or class of
+- machine or operating system. This file is included by the library
+- makefile `Makerules', which is used by the top-level makefile and
+- the subdirectory makefiles. It can change the variables set in the
+- including makefile or add new rules. It can use GNU `make'
+- conditional directives based on the variable `subdir' (see above)
+- to select different sets of variables and rules for different
+- sections of the library. It can also set the `make' variable
+- `sysdep-routines', to specify extra modules to be included in the
+- library. You should use `sysdep-routines' rather than adding
+- modules to `routines' because the latter is used in determining
+- what to distribute for each subdirectory of the main source tree.
+-
+- Each makefile in a subdirectory in the ordered list of
+- subdirectories to be searched is included in order. Since several
+- system-dependent makefiles may be included, each should append to
+- `sysdep-routines' rather than simply setting it:
+-
+- sysdep-routines := $(sysdep-routines) foo bar
+-
+-`Subdirs'
+- This file contains the names of new whole subdirectories under the
+- top-level library source tree that should be included for this
+- system. These subdirectories are treated just like the
+- system-independent subdirectories in the library source tree, such
+- as `stdio' and `math'.
+-
+- Use this when there are completely new sets of functions and header
+- files that should go into the library for the system this
+- subdirectory of `sysdeps' implements. For example,
+- `sysdeps/unix/inet/Subdirs' contains `inet'; the `inet' directory
+- contains various network-oriented operations which only make sense
+- to put in the library on systems that support the Internet.
+-
+-`Dist'
+- This file contains the names of files (relative to the
+- subdirectory of `sysdeps' in which it appears) which should be
+- included in the distribution. List any new files used by rules in
+- the `Makefile' in the same directory, or header files used by the
+- source files in that directory. You don't need to list files that
+- are implementations (either C or assembly source) of routines
+- whose names are given in the machine-independent makefiles in the
+- main source tree.
+-
+-`configure'
+- This file is a shell script fragment to be run at configuration
+- time. The top-level `configure' script uses the shell `.' command
+- to read the `configure' file in each system-dependent directory
+- chosen, in order. The `configure' files are often generated from
+- `configure.in' files using Autoconf.
+-
+- A system-dependent `configure' script will usually add things to
+- the shell variables `DEFS' and `config_vars'; see the top-level
+- `configure' script for details. The script can check for
+- `--with-PACKAGE' options that were passed to the top-level
+- `configure'. For an option `--with-PACKAGE=VALUE' `configure'
+- sets the shell variable `with_PACKAGE' (with any dashes in PACKAGE
+- converted to underscores) to VALUE; if the option is just
+- `--with-PACKAGE' (no argument), then it sets `with_PACKAGE' to
+- `yes'.
+-
+-`configure.in'
+- This file is an Autoconf input fragment to be processed into the
+- file `configure' in this subdirectory. *Note Introduction:
+- (autoconf.info)Introduction, for a description of Autoconf. You
+- should write either `configure' or `configure.in', but not both.
+- The first line of `configure.in' should invoke the `m4' macro
+- `GLIBC_PROVIDES'. This macro does several `AC_PROVIDE' calls for
+- Autoconf macros which are used by the top-level `configure'
+- script; without this, those macros might be invoked again
+- unnecessarily by Autoconf.
+-
+- That is the general system for how system-dependencies are isolated.
+-
+-* Menu:
+-
+-* Hierarchy Conventions:: The layout of the `sysdeps' hierarchy.
+-* Porting to Unix:: Porting the library to an average
+- Unix-like system.
+-
+-
+-File: libc.info, Node: Hierarchy Conventions, Next: Porting to Unix, Up:
Porting
+-
+-Layout of the `sysdeps' Directory Hierarchy
+--------------------------------------------
+-
+- A GNU configuration name has three parts: the CPU type, the
+-manufacturer's name, and the operating system. `configure' uses these
+-to pick the list of system-dependent directories to look for. If the
+-`--nfp' option is *not* passed to `configure', the directory
+-`MACHINE/fpu' is also used. The operating system often has a "base
+-operating system"; for example, if the operating system is `sunos4.1',
+-the base operating system is `unix/bsd'. The algorithm used to pick
+-the list of directories is simple: `configure' makes a list of the base
+-operating system, manufacturer, CPU type, and operating system, in that
+-order. It then concatenates all these together with slashes in
+-between, to produce a directory name; for example, the configuration
+-`sparc-sun-sunos4.1' results in `unix/bsd/sun/sparc/sunos4.1'.
+-`configure' then tries removing each element of the list in turn, so
+-`unix/bsd/sparc' and `sun/sparc' are also tried, among others. Since
+-the precise version number of the operating system is often not
+-important, and it would be very inconvenient, for example, to have
+-identical `sunos4.1.1' and `sunos4.1.2' directories, `configure' tries
+-successively less specific operating system names by removing trailing
+-suffixes starting with a period.
+-
+- As an example, here is the complete list of directories that would be
+-tried for the configuration `sparc-sun-sunos4.1' (without the `--nfp'
+-option):
+-
+- sparc/fpu
+- unix/bsd/sun/sunos4.1/sparc
+- unix/bsd/sun/sunos4.1
+- unix/bsd/sun/sunos4/sparc
+- unix/bsd/sun/sunos4
+- unix/bsd/sun/sunos/sparc
+- unix/bsd/sun/sunos
+- unix/bsd/sun/sparc
+- unix/bsd/sun
+- unix/bsd/sunos4.1/sparc
+- unix/bsd/sunos4.1
+- unix/bsd/sunos4/sparc
+- unix/bsd/sunos4
+- unix/bsd/sunos/sparc
+- unix/bsd/sunos
+- unix/bsd/sparc
+- unix/bsd
+- unix/sun/sunos4.1/sparc
+- unix/sun/sunos4.1
+- unix/sun/sunos4/sparc
+- unix/sun/sunos4
+- unix/sun/sunos/sparc
+- unix/sun/sunos
+- unix/sun/sparc
+- unix/sun
+- unix/sunos4.1/sparc
+- unix/sunos4.1
+- unix/sunos4/sparc
+- unix/sunos4
+- unix/sunos/sparc
+- unix/sunos
+- unix/sparc
+- unix
+- sun/sunos4.1/sparc
+- sun/sunos4.1
+- sun/sunos4/sparc
+- sun/sunos4
+- sun/sunos/sparc
+- sun/sunos
+- sun/sparc
+- sun
+- sunos4.1/sparc
+- sunos4.1
+- sunos4/sparc
+- sunos4
+- sunos/sparc
+- sunos
+- sparc
+-
+- Different machine architectures are conventionally subdirectories at
+-the top level of the `sysdeps' directory tree. For example,
+-`sysdeps/sparc' and `sysdeps/m68k'. These contain files specific to
+-those machine architectures, but not specific to any particular
+-operating system. There might be subdirectories for specializations of
+-those architectures, such as `sysdeps/m68k/68020'. Code which is
+-specific to the floating-point coprocessor used with a particular
+-machine should go in `sysdeps/MACHINE/fpu'.
+-
+- There are a few directories at the top level of the `sysdeps'
+-hierarchy that are not for particular machine architectures.
+-
+-`generic'
+-`stub'
+- As described above (*note Porting::.), these are the two
+- subdirectories that every configuration implicitly uses after all
+- others.
+-
+-`ieee754'
+- This directory is for code using the IEEE 754 floating-point
+- format, where the C type `float' is IEEE 754 single-precision
+- format, and `double' is IEEE 754 double-precision format. Usually
+- this directory is referred to in the `Implies' file in a machine
+- architecture-specific directory, such as `m68k/Implies'.
+-
+-`posix'
+- This directory contains implementations of things in the library in
+- terms of POSIX.1 functions. This includes some of the POSIX.1
+- functions themselves. Of course, POSIX.1 cannot be completely
+- implemented in terms of itself, so a configuration using just
+- `posix' cannot be complete.
+-
+-`unix'
+- This is the directory for Unix-like things. *Note Porting to
+- Unix::. `unix' implies `posix'. There are some special-purpose
+- subdirectories of `unix':
+-
+- `unix/common'
+- This directory is for things common to both BSD and System V
+- release 4. Both `unix/bsd' and `unix/sysv/sysv4' imply
+- `unix/common'.
+-
+- `unix/inet'
+- This directory is for `socket' and related functions on Unix
+- systems. The `inet' top-level subdirectory is enabled by
+- `unix/inet/Subdirs'. `unix/common' implies `unix/inet'.
+-
+-`mach'
+- This is the directory for things based on the Mach microkernel
+- from CMU (including the GNU operating system). Other basic
+- operating systems (VMS, for example) would have their own
+- directories at the top level of the `sysdeps' hierarchy, parallel
+- to `unix' and `mach'.
+-
+-
+-File: libc.info, Node: Porting to Unix, Prev: Hierarchy Conventions, Up:
Porting
+-
+-Porting the GNU C Library to Unix Systems
+------------------------------------------
+-
+- Most Unix systems are fundamentally very similar. There are
+-variations between different machines, and variations in what
+-facilities are provided by the kernel. But the interface to the
+-operating system facilities is, for the most part, pretty uniform and
+-simple.
+-
+- The code for Unix systems is in the directory `unix', at the top
+-level of the `sysdeps' hierarchy. This directory contains
+-subdirectories (and subdirectory trees) for various Unix variants.
+-
+- The functions which are system calls in most Unix systems are
+-implemented in assembly code in files in `sysdeps/unix'. These files
+-are named with a suffix of `.S'; for example, `__open.S'. Files ending
+-in `.S' are run through the C preprocessor before being fed to the
+-assembler.
+-
+- These files all use a set of macros that should be defined in
+-`sysdep.h'. The `sysdep.h' file in `sysdeps/unix' partially defines
+-them; a `sysdep.h' file in another directory must finish defining them
+-for the particular machine and operating system variant. See
+-`sysdeps/unix/sysdep.h' and the machine-specific `sysdep.h'
+-implementations to see what these macros are and what they should do.
+-
+- The system-specific makefile for the `unix' directory (that is, the
+-file `sysdeps/unix/Makefile') gives rules to generate several files
+-from the Unix system you are building the library on (which is assumed
+-to be the target system you are building the library *for*). All the
+-generated files are put in the directory where the object files are
+-kept; they should not affect the source tree itself. The files
+-generated are `ioctls.h', `errnos.h', `sys/param.h', and `errlist.c'
+-(for the `stdio' section of the library).
+-
+-
+-File: libc.info, Node: Contributors, Prev: Porting, Up: Maintenance
+-
+-Contributors to the GNU C Library
+-=================================
+-
+- The GNU C library was written originally by Roland McGrath. Some
+-parts of the library were contributed or worked on by other people.
+-
+- * The `getopt' function and related code were written by Richard
+- Stallman, David J. MacKenzie, and Roland McGrath.
+-
+- * The merge sort function `qsort' was written by Michael J. Haertel.
+-
+- * The quick sort function used as a fallback by `qsort' was written
+- by Douglas C. Schmidt.
+-
+- * The memory allocation functions `malloc', `realloc' and `free' and
+- related code were written by Michael J. Haertel.
+-
+- * Fast implementations of many of the string functions (`memcpy',
+- `strlen', etc.) were written by Torbjorn Granlund.
+-
+- * The `tar.h' header file was written by David J. MacKenzie.
+-
+- * The port to the MIPS DECStation running Ultrix 4
+- (`mips-dec-ultrix4') was contributed by Brendan Kehoe and Ian
+- Lance Taylor.
+-
+- * The DES encryption function `crypt' and related functions were
+- contributed by Michael Glad.
+-
+- * The `ftw' function was contributed by Ian Lance Taylor.
+-
+- * The startup code to support SunOS shared libraries was contributed
+- by Tom Quinn.
+-
+- * The `mktime' function was contributed by Paul Eggert.
+-
+- * The port to the Sequent Symmetry running Dynix version 3
+- (`i386-sequent-bsd') was contributed by Jason Merrill.
+-
+- * The timezone support code is derived from the public-domain
+- timezone package by Arthur David Olson and his many contributors.
+-
+- * The port to the DEC Alpha running OSF/1 (`alpha-dec-osf1') was
+- contributed by Brendan Kehoe, using some code written by Roland
+- McGrath.
+-
+- * The port to SGI machines running Irix 4 (`mips-sgi-irix4') was
+- contributed by Tom Quinn.
+-
+- * The port of the Mach and Hurd code to the MIPS architecture
+- (`mips-ANYTHING-gnu') was contributed by Kazumoto Kojima.
+-
+- * The floating-point printing function used by `printf' and friends
+- and the floating-point reading function used by `scanf', `strtod'
+- and friends were written by Ulrich Drepper. The multi-precision
+- integer functions used in those functions are taken from GNU MP,
+- which was contributed by Torbjorn Granlund.
+-
+- * The internationalization support in the library, and the support
+- programs `locale' and `localedef', were written by Ulrich Drepper.
+- Ulrich Drepper adapted the support code for message catalogs
+- (`libintl.h', etc.) from the GNU `gettext' package, which he also
+- wrote. He also contributed the `catgets' support and the entire
+- suite of multi-byte and wide-character support functions
+- (`wctype.h', `wchar.h', etc.).
+-
+- * The implementations of the `nsswitch.conf' mechanism and the files
+- and DNS backends for it were designed and written by Ulrich
+- Drepper and Roland McGrath, based on a backend interface defined
+- by Peter Eriksson.
+-
+- * The port to Linux i386/ELF (`i386-ANYTHING-linux') was contributed
+- by Ulrich Drepper, based in large part on work done in Hongjiu
+- Lu's Linux version of the GNU C Library.
+-
+- * The port to Linux/m68k (`m68k-ANYTHING-linux') was contributed by
+- Andreas Schwab.
+-
+- * Richard Henderson contributed the ELF dynamic linking code and
+- other support for the Alpha processor.
+-
+- * David Mosberger-Tang contributed the port to Linux/Alpha
+- (`alpha-ANYTHING-linux').
+-
+- * Stephen R. van den Berg contributed a highly-optimized `strstr'
+- function.
+-
+- * Ulrich Drepper contributed the `hsearch' and `drand48' families of
+- functions; reentrant `...`_r'' versions of the `random' family;
+- System V shared memory and IPC support code; and several
+- highly-optimized string functions for iX86 processors.
+-
+- * The math functions are taken from `fdlibm-5.1' by Sun
+- Microsystems, as modified by J.T. Conklin, Ian Lance Taylor,
+- Ulrich Drepper, Andreas Schwab, and Roland McGrath.
+-
+- * The `libio' library used to implement `stdio' functions on some
+- platforms was written by Per Bothner and modified by Ulrich
+- Drepper.
+-
+- * The Internet-related code (most of the `inet' subdirectory) and
+- several other miscellaneous functions and header files have been
+- included from 4.4 BSD with little or no modification.
+-
+- All code incorporated from 4.4 BSD is under the following
+- copyright:
+-
+- Copyright (C) 1991 Regents of the University of California.
+- All rights reserved.
+-
+- Redistribution and use in source and binary forms, with or
+- without modification, are permitted provided that the
+- following conditions are met:
+-
+- 1. Redistributions of source code must retain the above
+- copyright notice, this list of conditions and the
+- following disclaimer.
+-
+- 2. Redistributions in binary form must reproduce the above
+- copyright notice, this list of conditions and the
+- following disclaimer in the documentation and/or other
+- materials provided with the distribution.
+-
+- 3. All advertising materials mentioning features or use of
+- this software must display the following acknowledgement:
+- This product includes software developed by the
+- University of California, Berkeley and its
+- contributors.
+-
+- 4. Neither the name of the University nor the names of its
+- contributors may be used to endorse or promote products
+- derived from this software without specific prior
+- written permission.
+-
+- THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS
+- IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+- FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
+- SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+- INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+- DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+- SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+- LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
+- THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
+- OF SUCH DAMAGE.
+-
+- * The random number generation functions `random', `srandom',
+- `setstate' and `initstate', which are also the basis for the
+- `rand' and `srand' functions, were written by Earl T. Cohen for
+- the University of California at Berkeley and are copyrighted by the
+- Regents of the University of California. They have undergone minor
+- changes to fit into the GNU C library and to fit the ISO C
+- standard, but the functional code is Berkeley's.
+-
+- * The Internet resolver code is taken directly from BIND 4.9.5,
+- which is under both the Berkeley copyright above and also:
+-
+- Portions Copyright (C) 1993 by Digital Equipment Corporation.
+-
+- Permission to use, copy, modify, and distribute this software
+- for any purpose with or without fee is hereby granted,
+- provided that the above copyright notice and this permission
+- notice appear in all copies, and that the name of Digital
+- Equipment Corporation not be used in advertising or publicity
+- pertaining to distribution of the document or software
+- without specific, written prior permission.
+-
+- THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP.
+- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+- INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+- FITNESS. IN NO EVENT SHALL DIGITAL EQUIPMENT CORPORATION BE
+- LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
+- DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+- DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
+- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
+- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+-
+- * The code to support Sun RPC is taken verbatim from Sun's
+- RPCSRC-4.0 distribution, and is covered by this copyright:
+-
+- Copyright (C) 1984, Sun Microsystems, Inc.
+-
+- Sun RPC is a product of Sun Microsystems, Inc. and is
+- provided for unrestricted use provided that this legend is
+- included on all tape media and as a part of the software
+- program in whole or part. Users may copy or modify Sun RPC
+- without charge, but are not authorized to license or
+- distribute it to anyone else except as part of a product or
+- program developed by the user.
+-
+- SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND
+- INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND
+- FITNESS FOR A PARTICULAR PURPOSE, OR ARISING FROM A COURSE OF
+- DEALING, USAGE OR TRADE PRACTICE.
+-
+- Sun RPC is provided with no support and without any
+- obligation on the part of Sun Microsystems, Inc. to assist in
+- its use, correction, modification or enhancement.
+-
+- SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT
+- TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY
+- PATENTS BY SUN RPC OR ANY PART THEREOF.
+-
+- In no event will Sun Microsystems, Inc. be liable for any
+- lost revenue or profits or other special, indirect and
+- consequential damages, even if Sun has been advised of the
+- possibility of such damages.
+-
+- Sun Microsystems, Inc.
+- 2550 Garcia Avenue
+- Mountain View, California 94043
+-
+- * Some of the support code for Mach is taken from Mach 3.0 by CMU,
+- and is under the following copyright terms:
+-
+- Mach Operating System
+- Copyright (C) 1991,1990,1989 Carnegie Mellon University
+- All Rights Reserved.
+-
+- Permission to use, copy, modify and distribute this software
+- and its documentation is hereby granted, provided that both
+- the copyright notice and this permission notice appear in all
+- copies of the software, derivative works or modified
+- versions, and any portions thereof, and that both notices
+- appear in supporting documentation.
+-
+- CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS
+- IS" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF
+- ANY KIND FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF
+- THIS SOFTWARE.
+-
+- Carnegie Mellon requests users of this software to return to
+-
+- Software Distribution Coordinator
+- School of Computer Science
+- Carnegie Mellon University
+- Pittsburgh PA 15213-3890
+-
+- or address@hidden' any improvements or
+- extensions that they make and grant Carnegie Mellon the
+- rights to redistribute these changes.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-3
glibc-2.0.1/manual/libc.info-3
+--- ../glibc-2.0.1/manual/libc.info-3 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-3 1970-01-01 01:00:00.000000000 +0100
+@@ -1,1163 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+- This file documents the GNU C library.
+-
+- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+- Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+- Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+- Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: Error Messages, Prev: Error Codes, Up: Error
Reporting
+-
+-Error Messages
+-==============
+-
+- The library has functions and variables designed to make it easy for
+-your program to report informative error messages in the customary
+-format about the failure of a library call. The functions `strerror'
+-and `perror' give you the standard error message for a given error
+-code; the variable `program_invocation_short_name' gives you convenient
+-access to the name of the program that encountered the error.
+-
+- - Function: char * strerror (int ERRNUM)
+- The `strerror' function maps the error code (*note Checking for
+- Errors::.) specified by the ERRNUM argument to a descriptive error
+- message string. The return value is a pointer to this string.
+-
+- The value ERRNUM normally comes from the variable `errno'.
+-
+- You should not modify the string returned by `strerror'. Also, if
+- you make subsequent calls to `strerror', the string might be
+- overwritten. (But it's guaranteed that no library function ever
+- calls `strerror' behind your back.)
+-
+- The function `strerror' is declared in `string.h'.
+-
+- - Function: void perror (const char *MESSAGE)
+- This function prints an error message to the stream `stderr'; see
+- *Note Standard Streams::.
+-
+- If you call `perror' with a MESSAGE that is either a null pointer
+- or an empty string, `perror' just prints the error message
+- corresponding to `errno', adding a trailing newline.
+-
+- If you supply a non-null MESSAGE argument, then `perror' prefixes
+- its output with this string. It adds a colon and a space
+- character to separate the MESSAGE from the error string
+- corresponding to `errno'.
+-
+- The function `perror' is declared in `stdio.h'.
+-
+- `strerror' and `perror' produce the exact same message for any given
+-error code; the precise text varies from system to system. On the GNU
+-system, the messages are fairly short; there are no multi-line messages
+-or embedded newlines. Each error message begins with a capital letter
+-and does not include any terminating punctuation.
+-
+- *Compatibility Note:* The `strerror' function is a new feature of
+-ISO C. Many older C systems do not support this function yet.
+-
+- Many programs that don't read input from the terminal are designed to
+-exit if any system call fails. By convention, the error message from
+-such a program should start with the program's name, sans directories.
+-You can find that name in the variable `program_invocation_short_name';
+-the full file name is stored the variable `program_invocation_name':
+-
+- - Variable: char * program_invocation_name
+- This variable's value is the name that was used to invoke the
+- program running in the current process. It is the same as
+- `argv[0]'. Note that this is not necessarily a useful file name;
+- often it contains no directory names. *Note Program Arguments::.
+-
+- - Variable: char * program_invocation_short_name
+- This variable's value is the name that was used to invoke the
+- program running in the current process, with directory names
+- removed. (That is to say, it is the same as
+- `program_invocation_name' minus everything up to the last slash,
+- if any.)
+-
+- The library initialization code sets up both of these variables
+-before calling `main'.
+-
+- *Portability Note:* These two variables are GNU extensions. If you
+-want your program to work with non-GNU libraries, you must save the
+-value of `argv[0]' in `main', and then strip off the directory names
+-yourself. We added these extensions to make it possible to write
+-self-contained error-reporting subroutines that require no explicit
+-cooperation from `main'.
+-
+- Here is an example showing how to handle failure to open a file
+-correctly. The function `open_sesame' tries to open the named file for
+-reading and returns a stream if successful. The `fopen' library
+-function returns a null pointer if it couldn't open the file for some
+-reason. In that situation, `open_sesame' constructs an appropriate
+-error message using the `strerror' function, and terminates the
+-program. If we were going to make some other library calls before
+-passing the error code to `strerror', we'd have to save it in a local
+-variable instead, because those other library functions might overwrite
+-`errno' in the meantime.
+-
+- #include <errno.h>
+- #include <stdio.h>
+- #include <stdlib.h>
+- #include <string.h>
+-
+- FILE *
+- open_sesame (char *name)
+- {
+- FILE *stream;
+-
+- errno = 0;
+- stream = fopen (name, "r");
+- if (stream == NULL)
+- {
+- fprintf (stderr, "%s: Couldn't open file %s; %s\n",
+- program_invocation_short_name, name, strerror (errno));
+- exit (EXIT_FAILURE);
+- }
+- else
+- return stream;
+- }
+-
+-
+-File: libc.info, Node: Memory Allocation, Next: Character Handling, Prev:
Error Reporting, Up: Top
+-
+-Memory Allocation
+-*****************
+-
+- The GNU system provides several methods for allocating memory space
+-under explicit program control. They vary in generality and in
+-efficiency.
+-
+-* Menu:
+-
+-* Memory Concepts:: An introduction to concepts and terminology.
+-* Dynamic Allocation and C:: How to get different kinds of allocation in C.
+-* Unconstrained Allocation:: The `malloc' facility allows fully general
+- dynamic allocation.
+-* Obstacks:: Obstacks are less general than malloc
+- but more efficient and convenient.
+-* Variable Size Automatic:: Allocation of variable-sized blocks
+- of automatic storage that are freed when the
+- calling function returns.
+-* Relocating Allocator:: Waste less memory, if you can tolerate
+- automatic relocation of the blocks you get.
+-* Memory Warnings:: Getting warnings when memory is nearly full.
+-
+-
+-File: libc.info, Node: Memory Concepts, Next: Dynamic Allocation and C,
Up: Memory Allocation
+-
+-Dynamic Memory Allocation Concepts
+-==================================
+-
+- "Dynamic memory allocation" is a technique in which programs
+-determine as they are running where to store some information. You need
+-dynamic allocation when the number of memory blocks you need, or how
+-long you continue to need them, depends on the data you are working on.
+-
+- For example, you may need a block to store a line read from an input
+-file; since there is no limit to how long a line can be, you must
+-allocate the storage dynamically and make it dynamically larger as you
+-read more of the line.
+-
+- Or, you may need a block for each record or each definition in the
+-input data; since you can't know in advance how many there will be, you
+-must allocate a new block for each record or definition as you read it.
+-
+- When you use dynamic allocation, the allocation of a block of memory
+-is an action that the program requests explicitly. You call a function
+-or macro when you want to allocate space, and specify the size with an
+-argument. If you want to free the space, you do so by calling another
+-function or macro. You can do these things whenever you want, as often
+-as you want.
+-
+-
+-File: libc.info, Node: Dynamic Allocation and C, Next: Unconstrained
Allocation, Prev: Memory Concepts, Up: Memory Allocation
+-
+-Dynamic Allocation and C
+-========================
+-
+- The C language supports two kinds of memory allocation through the
+-variables in C programs:
+-
+- * "Static allocation" is what happens when you declare a static or
+- global variable. Each static or global variable defines one block
+- of space, of a fixed size. The space is allocated once, when your
+- program is started, and is never freed.
+-
+- * "Automatic allocation" happens when you declare an automatic
+- variable, such as a function argument or a local variable. The
+- space for an automatic variable is allocated when the compound
+- statement containing the declaration is entered, and is freed when
+- that compound statement is exited.
+-
+- In GNU C, the length of the automatic storage can be an expression
+- that varies. In other C implementations, it must be a constant.
+-
+- Dynamic allocation is not supported by C variables; there is no
+-storage class "dynamic", and there can never be a C variable whose
+-value is stored in dynamically allocated space. The only way to refer
+-to dynamically allocated space is through a pointer. Because it is less
+-convenient, and because the actual process of dynamic allocation
+-requires more computation time, programmers generally use dynamic
+-allocation only when neither static nor automatic allocation will serve.
+-
+- For example, if you want to allocate dynamically some space to hold a
+-`struct foobar', you cannot declare a variable of type `struct foobar'
+-whose contents are the dynamically allocated space. But you can
+-declare a variable of pointer type `struct foobar *' and assign it the
+-address of the space. Then you can use the operators `*' and `->' on
+-this pointer variable to refer to the contents of the space:
+-
+- {
+- struct foobar *ptr
+- = (struct foobar *) malloc (sizeof (struct foobar));
+- ptr->name = x;
+- ptr->next = current_foobar;
+- current_foobar = ptr;
+- }
+-
+-
+-File: libc.info, Node: Unconstrained Allocation, Next: Obstacks, Prev:
Dynamic Allocation and C, Up: Memory Allocation
+-
+-Unconstrained Allocation
+-========================
+-
+- The most general dynamic allocation facility is `malloc'. It allows
+-you to allocate blocks of memory of any size at any time, make them
+-bigger or smaller at any time, and free the blocks individually at any
+-time (or never).
+-
+-* Menu:
+-
+-* Basic Allocation:: Simple use of `malloc'.
+-* Malloc Examples:: Examples of `malloc'. `xmalloc'.
+-* Freeing after Malloc:: Use `free' to free a block you
+- got with `malloc'.
+-* Changing Block Size:: Use `realloc' to make a block
+- bigger or smaller.
+-* Allocating Cleared Space:: Use `calloc' to allocate a
+- block and clear it.
+-* Efficiency and Malloc:: Efficiency considerations in use of
+- these functions.
+-* Aligned Memory Blocks:: Allocating specially aligned memory:
+- `memalign' and `valloc'.
+-* Heap Consistency Checking:: Automatic checking for errors.
+-* Hooks for Malloc:: You can use these hooks for debugging
+- programs that use `malloc'.
+-* Statistics of Malloc:: Getting information about how much
+- memory your program is using.
+-* Summary of Malloc:: Summary of `malloc' and related functions.
+-
+-
+-File: libc.info, Node: Basic Allocation, Next: Malloc Examples, Up:
Unconstrained Allocation
+-
+-Basic Storage Allocation
+-------------------------
+-
+- To allocate a block of memory, call `malloc'. The prototype for
+-this function is in `stdlib.h'.
+-
+- - Function: void * malloc (size_t SIZE)
+- This function returns a pointer to a newly allocated block SIZE
+- bytes long, or a null pointer if the block could not be allocated.
+-
+- The contents of the block are undefined; you must initialize it
+-yourself (or use `calloc' instead; *note Allocating Cleared Space::.).
+-Normally you would cast the value as a pointer to the kind of object
+-that you want to store in the block. Here we show an example of doing
+-so, and of initializing the space with zeros using the library function
+-`memset' (*note Copying and Concatenation::.):
+-
+- struct foo *ptr;
+- ...
+- ptr = (struct foo *) malloc (sizeof (struct foo));
+- if (ptr == 0) abort ();
+- memset (ptr, 0, sizeof (struct foo));
+-
+- You can store the result of `malloc' into any pointer variable
+-without a cast, because ISO C automatically converts the type `void *'
+-to another type of pointer when necessary. But the cast is necessary
+-in contexts other than assignment operators or if you might want your
+-code to run in traditional C.
+-
+- Remember that when allocating space for a string, the argument to
+-`malloc' must be one plus the length of the string. This is because a
+-string is terminated with a null character that doesn't count in the
+-"length" of the string but does need space. For example:
+-
+- char *ptr;
+- ...
+- ptr = (char *) malloc (length + 1);
+-
+-*Note Representation of Strings::, for more information about this.
+-
+-
+-File: libc.info, Node: Malloc Examples, Next: Freeing after Malloc, Prev:
Basic Allocation, Up: Unconstrained Allocation
+-
+-Examples of `malloc'
+---------------------
+-
+- If no more space is available, `malloc' returns a null pointer. You
+-should check the value of *every* call to `malloc'. It is useful to
+-write a subroutine that calls `malloc' and reports an error if the
+-value is a null pointer, returning only if the value is nonzero. This
+-function is conventionally called `xmalloc'. Here it is:
+-
+- void *
+- xmalloc (size_t size)
+- {
+- register void *value = malloc (size);
+- if (value == 0)
+- fatal ("virtual memory exhausted");
+- return value;
+- }
+-
+- Here is a real example of using `malloc' (by way of `xmalloc'). The
+-function `savestring' will copy a sequence of characters into a newly
+-allocated null-terminated string:
+-
+- char *
+- savestring (const char *ptr, size_t len)
+- {
+- register char *value = (char *) xmalloc (len + 1);
+- memcpy (value, ptr, len);
+- value[len] = '\0';
+- return value;
+- }
+-
+- The block that `malloc' gives you is guaranteed to be aligned so
+-that it can hold any type of data. In the GNU system, the address is
+-always a multiple of eight; if the size of block is 16 or more, then the
+-address is always a multiple of 16. Only rarely is any higher boundary
+-(such as a page boundary) necessary; for those cases, use `memalign' or
+-`valloc' (*note Aligned Memory Blocks::.).
+-
+- Note that the memory located after the end of the block is likely to
+-be in use for something else; perhaps a block already allocated by
+-another call to `malloc'. If you attempt to treat the block as longer
+-than you asked for it to be, you are liable to destroy the data that
+-`malloc' uses to keep track of its blocks, or you may destroy the
+-contents of another block. If you have already allocated a block and
+-discover you want it to be bigger, use `realloc' (*note Changing Block
+-Size::.).
+-
+-
+-File: libc.info, Node: Freeing after Malloc, Next: Changing Block Size,
Prev: Malloc Examples, Up: Unconstrained Allocation
+-
+-Freeing Memory Allocated with `malloc'
+---------------------------------------
+-
+- When you no longer need a block that you got with `malloc', use the
+-function `free' to make the block available to be allocated again. The
+-prototype for this function is in `stdlib.h'.
+-
+- - Function: void free (void *PTR)
+- The `free' function deallocates the block of storage pointed at by
+- PTR.
+-
+- - Function: void cfree (void *PTR)
+- This function does the same thing as `free'. It's provided for
+- backward compatibility with SunOS; you should use `free' instead.
+-
+- Freeing a block alters the contents of the block. *Do not expect to
+-find any data (such as a pointer to the next block in a chain of
+-blocks) in the block after freeing it.* Copy whatever you need out of
+-the block before freeing it! Here is an example of the proper way to
+-free all the blocks in a chain, and the strings that they point to:
+-
+- struct chain
+- {
+- struct chain *next;
+- char *name;
+- }
+-
+- void
+- free_chain (struct chain *chain)
+- {
+- while (chain != 0)
+- {
+- struct chain *next = chain->next;
+- free (chain->name);
+- free (chain);
+- chain = next;
+- }
+- }
+-
+- Occasionally, `free' can actually return memory to the operating
+-system and make the process smaller. Usually, all it can do is allow a
+-later call to `malloc' to reuse the space. In the meantime, the space
+-remains in your program as part of a free-list used internally by
+-`malloc'.
+-
+- There is no point in freeing blocks at the end of a program, because
+-all of the program's space is given back to the system when the process
+-terminates.
+-
+-
+-File: libc.info, Node: Changing Block Size, Next: Allocating Cleared Space,
Prev: Freeing after Malloc, Up: Unconstrained Allocation
+-
+-Changing the Size of a Block
+-----------------------------
+-
+- Often you do not know for certain how big a block you will
+-ultimately need at the time you must begin to use the block. For
+-example, the block might be a buffer that you use to hold a line being
+-read from a file; no matter how long you make the buffer initially, you
+-may encounter a line that is longer.
+-
+- You can make the block longer by calling `realloc'. This function
+-is declared in `stdlib.h'.
+-
+- - Function: void * realloc (void *PTR, size_t NEWSIZE)
+- The `realloc' function changes the size of the block whose address
+- is PTR to be NEWSIZE.
+-
+- Since the space after the end of the block may be in use, `realloc'
+- may find it necessary to copy the block to a new address where
+- more free space is available. The value of `realloc' is the new
+- address of the block. If the block needs to be moved, `realloc'
+- copies the old contents.
+-
+- If you pass a null pointer for PTR, `realloc' behaves just like
+- `malloc (NEWSIZE)'. This can be convenient, but beware that older
+- implementations (before ISO C) may not support this behavior, and
+- will probably crash when `realloc' is passed a null pointer.
+-
+- Like `malloc', `realloc' may return a null pointer if no memory
+-space is available to make the block bigger. When this happens, the
+-original block is untouched; it has not been modified or relocated.
+-
+- In most cases it makes no difference what happens to the original
+-block when `realloc' fails, because the application program cannot
+-continue when it is out of memory, and the only thing to do is to give
+-a fatal error message. Often it is convenient to write and use a
+-subroutine, conventionally called `xrealloc', that takes care of the
+-error message as `xmalloc' does for `malloc':
+-
+- void *
+- xrealloc (void *ptr, size_t size)
+- {
+- register void *value = realloc (ptr, size);
+- if (value == 0)
+- fatal ("Virtual memory exhausted");
+- return value;
+- }
+-
+- You can also use `realloc' to make a block smaller. The reason you
+-would do this is to avoid tying up a lot of memory space when only a
+-little is needed. Making a block smaller sometimes necessitates
+-copying it, so it can fail if no other space is available.
+-
+- If the new size you specify is the same as the old size, `realloc'
+-is guaranteed to change nothing and return the same address that you
+-gave.
+-
+-
+-File: libc.info, Node: Allocating Cleared Space, Next: Efficiency and
Malloc, Prev: Changing Block Size, Up: Unconstrained Allocation
+-
+-Allocating Cleared Space
+-------------------------
+-
+- The function `calloc' allocates memory and clears it to zero. It is
+-declared in `stdlib.h'.
+-
+- - Function: void * calloc (size_t COUNT, size_t ELTSIZE)
+- This function allocates a block long enough to contain a vector of
+- COUNT elements, each of size ELTSIZE. Its contents are cleared to
+- zero before `calloc' returns.
+-
+- You could define `calloc' as follows:
+-
+- void *
+- calloc (size_t count, size_t eltsize)
+- {
+- size_t size = count * eltsize;
+- void *value = malloc (size);
+- if (value != 0)
+- memset (value, 0, size);
+- return value;
+- }
+-
+-
+-File: libc.info, Node: Efficiency and Malloc, Next: Aligned Memory Blocks,
Prev: Allocating Cleared Space, Up: Unconstrained Allocation
+-
+-Efficiency Considerations for `malloc'
+---------------------------------------
+-
+- To make the best use of `malloc', it helps to know that the GNU
+-version of `malloc' always dispenses small amounts of memory in blocks
+-whose sizes are powers of two. It keeps separate pools for each power
+-of two. This holds for sizes up to a page size. Therefore, if you are
+-free to choose the size of a small block in order to make `malloc' more
+-efficient, make it a power of two.
+-
+- Once a page is split up for a particular block size, it can't be
+-reused for another size unless all the blocks in it are freed. In many
+-programs, this is unlikely to happen. Thus, you can sometimes make a
+-program use memory more efficiently by using blocks of the same size for
+-many different purposes.
+-
+- When you ask for memory blocks of a page or larger, `malloc' uses a
+-different strategy; it rounds the size up to a multiple of a page, and
+-it can coalesce and split blocks as needed.
+-
+- The reason for the two strategies is that it is important to allocate
+-and free small blocks as fast as possible, but speed is less important
+-for a large block since the program normally spends a fair amount of
+-time using it. Also, large blocks are normally fewer in number.
+-Therefore, for large blocks, it makes sense to use a method which takes
+-more time to minimize the wasted space.
+-
+-
+-File: libc.info, Node: Aligned Memory Blocks, Next: Heap Consistency
Checking, Prev: Efficiency and Malloc, Up: Unconstrained Allocation
+-
+-Allocating Aligned Memory Blocks
+---------------------------------
+-
+- The address of a block returned by `malloc' or `realloc' in the GNU
+-system is always a multiple of eight. If you need a block whose
+-address is a multiple of a higher power of two than that, use
+-`memalign' or `valloc'. These functions are declared in `stdlib.h'.
+-
+- With the GNU library, you can use `free' to free the blocks that
+-`memalign' and `valloc' return. That does not work in BSD,
+-however--BSD does not provide any way to free such blocks.
+-
+- - Function: void * memalign (size_t BOUNDARY, size_t SIZE)
+- The `memalign' function allocates a block of SIZE bytes whose
+- address is a multiple of BOUNDARY. The BOUNDARY must be a power
+- of two! The function `memalign' works by calling `malloc' to
+- allocate a somewhat larger block, and then returning an address
+- within the block that is on the specified boundary.
+-
+- - Function: void * valloc (size_t SIZE)
+- Using `valloc' is like using `memalign' and passing the page size
+- as the value of the second argument. It is implemented like this:
+-
+- void *
+- valloc (size_t size)
+- {
+- return memalign (getpagesize (), size);
+- }
+-
+-
+-File: libc.info, Node: Heap Consistency Checking, Next: Hooks for Malloc,
Prev: Aligned Memory Blocks, Up: Unconstrained Allocation
+-
+-Heap Consistency Checking
+--------------------------
+-
+- You can ask `malloc' to check the consistency of dynamic storage by
+-using the `mcheck' function. This function is a GNU extension,
+-declared in `malloc.h'.
+-
+- - Function: int mcheck (void (*ABORTFN) (enum mcheck_status STATUS))
+- Calling `mcheck' tells `malloc' to perform occasional consistency
+- checks. These will catch things such as writing past the end of a
+- block that was allocated with `malloc'.
+-
+- The ABORTFN argument is the function to call when an inconsistency
+- is found. If you supply a null pointer, then `mcheck' uses a
+- default function which prints a message and calls `abort' (*note
+- Aborting a Program::.). The function you supply is called with
+- one argument, which says what sort of inconsistency was detected;
+- its type is described below.
+-
+- It is too late to begin allocation checking once you have allocated
+- anything with `malloc'. So `mcheck' does nothing in that case.
+- The function returns `-1' if you call it too late, and `0'
+- otherwise (when it is successful).
+-
+- The easiest way to arrange to call `mcheck' early enough is to use
+- the option `-lmcheck' when you link your program; then you don't
+- need to modify your program source at all.
+-
+- - Function: enum mcheck_status mprobe (void *POINTER)
+- The `mprobe' function lets you explicitly check for inconsistencies
+- in a particular allocated block. You must have already called
+- `mcheck' at the beginning of the program, to do its occasional
+- checks; calling `mprobe' requests an additional consistency check
+- to be done at the time of the call.
+-
+- The argument POINTER must be a pointer returned by `malloc' or
+- `realloc'. `mprobe' returns a value that says what inconsistency,
+- if any, was found. The values are described below.
+-
+- - Data Type: enum mcheck_status
+- This enumerated type describes what kind of inconsistency was
+- detected in an allocated block, if any. Here are the possible
+- values:
+-
+- `MCHECK_DISABLED'
+- `mcheck' was not called before the first allocation. No
+- consistency checking can be done.
+-
+- `MCHECK_OK'
+- No inconsistency detected.
+-
+- `MCHECK_HEAD'
+- The data immediately before the block was modified. This
+- commonly happens when an array index or pointer is
+- decremented too far.
+-
+- `MCHECK_TAIL'
+- The data immediately after the block was modified. This
+- commonly happens when an array index or pointer is
+- incremented too far.
+-
+- `MCHECK_FREE'
+- The block was already freed.
+-
+-
+-File: libc.info, Node: Hooks for Malloc, Next: Statistics of Malloc, Prev:
Heap Consistency Checking, Up: Unconstrained Allocation
+-
+-Storage Allocation Hooks
+-------------------------
+-
+- The GNU C library lets you modify the behavior of `malloc',
+-`realloc', and `free' by specifying appropriate hook functions. You
+-can use these hooks to help you debug programs that use dynamic storage
+-allocation, for example.
+-
+- The hook variables are declared in `malloc.h'.
+-
+- - Variable: __malloc_hook
+- The value of this variable is a pointer to function that `malloc'
+- uses whenever it is called. You should define this function to
+- look like `malloc'; that is, like:
+-
+- void *FUNCTION (size_t SIZE)
+-
+- - Variable: __realloc_hook
+- The value of this variable is a pointer to function that `realloc'
+- uses whenever it is called. You should define this function to
+- look like `realloc'; that is, like:
+-
+- void *FUNCTION (void *PTR, size_t SIZE)
+-
+- - Variable: __free_hook
+- The value of this variable is a pointer to function that `free'
+- uses whenever it is called. You should define this function to
+- look like `free'; that is, like:
+-
+- void FUNCTION (void *PTR)
+-
+- You must make sure that the function you install as a hook for one of
+-these functions does not call that function recursively without
+-restoring the old value of the hook first! Otherwise, your program
+-will get stuck in an infinite recursion.
+-
+- Here is an example showing how to use `__malloc_hook' properly. It
+-installs a function that prints out information every time `malloc' is
+-called.
+-
+- static void *(*old_malloc_hook) (size_t);
+- static void *
+- my_malloc_hook (size_t size)
+- {
+- void *result;
+- __malloc_hook = old_malloc_hook;
+- result = malloc (size);
+- /* `printf' might call `malloc', so protect it too. */
+- printf ("malloc (%u) returns %p\n", (unsigned int) size, result);
+- __malloc_hook = my_malloc_hook;
+- return result;
+- }
+-
+- main ()
+- {
+- ...
+- old_malloc_hook = __malloc_hook;
+- __malloc_hook = my_malloc_hook;
+- ...
+- }
+-
+- The `mcheck' function (*note Heap Consistency Checking::.) works by
+-installing such hooks.
+-
+-
+-File: libc.info, Node: Statistics of Malloc, Next: Summary of Malloc,
Prev: Hooks for Malloc, Up: Unconstrained Allocation
+-
+-Statistics for Storage Allocation with `malloc'
+------------------------------------------------
+-
+- You can get information about dynamic storage allocation by calling
+-the `mstats' function. This function and its associated data type are
+-declared in `malloc.h'; they are a GNU extension.
+-
+- - Data Type: struct mstats
+- This structure type is used to return information about the dynamic
+- storage allocator. It contains the following members:
+-
+- `size_t bytes_total'
+- This is the total size of memory managed by `malloc', in
+- bytes.
+-
+- `size_t chunks_used'
+- This is the number of chunks in use. (The storage allocator
+- internally gets chunks of memory from the operating system,
+- and then carves them up to satisfy individual `malloc'
+- requests; see *Note Efficiency and Malloc::.)
+-
+- `size_t bytes_used'
+- This is the number of bytes in use.
+-
+- `size_t chunks_free'
+- This is the number of chunks which are free - that is, that
+- have been allocated by the operating system to your program,
+- but which are not now being used.
+-
+- `size_t bytes_free'
+- This is the number of bytes which are free.
+-
+- - Function: struct mstats mstats (void)
+- This function returns information about the current dynamic memory
+- usage in a structure of type `struct mstats'.
+-
+-
+-File: libc.info, Node: Summary of Malloc, Prev: Statistics of Malloc, Up:
Unconstrained Allocation
+-
+-Summary of `malloc'-Related Functions
+--------------------------------------
+-
+- Here is a summary of the functions that work with `malloc':
+-
+-`void *malloc (size_t SIZE)'
+- Allocate a block of SIZE bytes. *Note Basic Allocation::.
+-
+-`void free (void *ADDR)'
+- Free a block previously allocated by `malloc'. *Note Freeing
+- after Malloc::.
+-
+-`void *realloc (void *ADDR, size_t SIZE)'
+- Make a block previously allocated by `malloc' larger or smaller,
+- possibly by copying it to a new location. *Note Changing Block
+- Size::.
+-
+-`void *calloc (size_t COUNT, size_t ELTSIZE)'
+- Allocate a block of COUNT * ELTSIZE bytes using `malloc', and set
+- its contents to zero. *Note Allocating Cleared Space::.
+-
+-`void *valloc (size_t SIZE)'
+- Allocate a block of SIZE bytes, starting on a page boundary.
+- *Note Aligned Memory Blocks::.
+-
+-`void *memalign (size_t SIZE, size_t BOUNDARY)'
+- Allocate a block of SIZE bytes, starting on an address that is a
+- multiple of BOUNDARY. *Note Aligned Memory Blocks::.
+-
+-`int mcheck (void (*ABORTFN) (void))'
+- Tell `malloc' to perform occasional consistency checks on
+- dynamically allocated memory, and to call ABORTFN when an
+- inconsistency is found. *Note Heap Consistency Checking::.
+-
+-`void *(*__malloc_hook) (size_t SIZE)'
+- A pointer to a function that `malloc' uses whenever it is called.
+-
+-`void *(*__realloc_hook) (void *PTR, size_t SIZE)'
+- A pointer to a function that `realloc' uses whenever it is called.
+-
+-`void (*__free_hook) (void *PTR)'
+- A pointer to a function that `free' uses whenever it is called.
+-
+-`struct mstats mstats (void)'
+- Return information about the current dynamic memory usage. *Note
+- Statistics of Malloc::.
+-
+-
+-File: libc.info, Node: Obstacks, Next: Variable Size Automatic, Prev:
Unconstrained Allocation, Up: Memory Allocation
+-
+-Obstacks
+-========
+-
+- An "obstack" is a pool of memory containing a stack of objects. You
+-can create any number of separate obstacks, and then allocate objects in
+-specified obstacks. Within each obstack, the last object allocated must
+-always be the first one freed, but distinct obstacks are independent of
+-each other.
+-
+- Aside from this one constraint of order of freeing, obstacks are
+-totally general: an obstack can contain any number of objects of any
+-size. They are implemented with macros, so allocation is usually very
+-fast as long as the objects are usually small. And the only space
+-overhead per object is the padding needed to start each object on a
+-suitable boundary.
+-
+-* Menu:
+-
+-* Creating Obstacks:: How to declare an obstack in your program.
+-* Preparing for Obstacks:: Preparations needed before you can
+- use obstacks.
+-* Allocation in an Obstack:: Allocating objects in an obstack.
+-* Freeing Obstack Objects:: Freeing objects in an obstack.
+-* Obstack Functions:: The obstack functions are both
+- functions and macros.
+-* Growing Objects:: Making an object bigger by stages.
+-* Extra Fast Growing:: Extra-high-efficiency (though more
+- complicated) growing objects.
+-* Status of an Obstack:: Inquiries about the status of an obstack.
+-* Obstacks Data Alignment:: Controlling alignment of objects in obstacks.
+-* Obstack Chunks:: How obstacks obtain and release chunks;
+- efficiency considerations.
+-* Summary of Obstacks::
+-
+-
+-File: libc.info, Node: Creating Obstacks, Next: Preparing for Obstacks,
Up: Obstacks
+-
+-Creating Obstacks
+------------------
+-
+- The utilities for manipulating obstacks are declared in the header
+-file `obstack.h'.
+-
+- - Data Type: struct obstack
+- An obstack is represented by a data structure of type `struct
+- obstack'. This structure has a small fixed size; it records the
+- status of the obstack and how to find the space in which objects
+- are allocated. It does not contain any of the objects themselves.
+- You should not try to access the contents of the structure
+- directly; use only the functions described in this chapter.
+-
+- You can declare variables of type `struct obstack' and use them as
+-obstacks, or you can allocate obstacks dynamically like any other kind
+-of object. Dynamic allocation of obstacks allows your program to have a
+-variable number of different stacks. (You can even allocate an obstack
+-structure in another obstack, but this is rarely useful.)
+-
+- All the functions that work with obstacks require you to specify
+-which obstack to use. You do this with a pointer of type `struct
+-obstack *'. In the following, we often say "an obstack" when strictly
+-speaking the object at hand is such a pointer.
+-
+- The objects in the obstack are packed into large blocks called
+-"chunks". The `struct obstack' structure points to a chain of the
+-chunks currently in use.
+-
+- The obstack library obtains a new chunk whenever you allocate an
+-object that won't fit in the previous chunk. Since the obstack library
+-manages chunks automatically, you don't need to pay much attention to
+-them, but you do need to supply a function which the obstack library
+-should use to get a chunk. Usually you supply a function which uses
+-`malloc' directly or indirectly. You must also supply a function to
+-free a chunk. These matters are described in the following section.
+-
+-
+-File: libc.info, Node: Preparing for Obstacks, Next: Allocation in an
Obstack, Prev: Creating Obstacks, Up: Obstacks
+-
+-Preparing for Using Obstacks
+-----------------------------
+-
+- Each source file in which you plan to use the obstack functions must
+-include the header file `obstack.h', like this:
+-
+- #include <obstack.h>
+-
+- Also, if the source file uses the macro `obstack_init', it must
+-declare or define two functions or macros that will be called by the
+-obstack library. One, `obstack_chunk_alloc', is used to allocate the
+-chunks of memory into which objects are packed. The other,
+-`obstack_chunk_free', is used to return chunks when the objects in them
+-are freed. These macros should appear before any use of obstacks in
+-the source file.
+-
+- Usually these are defined to use `malloc' via the intermediary
+-`xmalloc' (*note Unconstrained Allocation::.). This is done with the
+-following pair of macro definitions:
+-
+- #define obstack_chunk_alloc xmalloc
+- #define obstack_chunk_free free
+-
+-Though the storage you get using obstacks really comes from `malloc',
+-using obstacks is faster because `malloc' is called less often, for
+-larger blocks of memory. *Note Obstack Chunks::, for full details.
+-
+- At run time, before the program can use a `struct obstack' object as
+-an obstack, it must initialize the obstack by calling `obstack_init'.
+-
+- - Function: int obstack_init (struct obstack *OBSTACK-PTR)
+- Initialize obstack OBSTACK-PTR for allocation of objects. This
+- function calls the obstack's `obstack_chunk_alloc' function. It
+- returns 0 if `obstack_chunk_alloc' returns a null pointer, meaning
+- that it is out of memory. Otherwise, it returns 1. If you supply
+- an `obstack_chunk_alloc' function that calls `exit' (*note Program
+- Termination::.) or `longjmp' (*note Non-Local Exits::.) when out
+- of memory, you can safely ignore the value that `obstack_init'
+- returns.
+-
+- Here are two examples of how to allocate the space for an obstack and
+-initialize it. First, an obstack that is a static variable:
+-
+- static struct obstack myobstack;
+- ...
+- obstack_init (&myobstack);
+-
+-Second, an obstack that is itself dynamically allocated:
+-
+- struct obstack *myobstack_ptr
+- = (struct obstack *) xmalloc (sizeof (struct obstack));
+-
+- obstack_init (myobstack_ptr);
+-
+-
+-File: libc.info, Node: Allocation in an Obstack, Next: Freeing Obstack
Objects, Prev: Preparing for Obstacks, Up: Obstacks
+-
+-Allocation in an Obstack
+-------------------------
+-
+- The most direct way to allocate an object in an obstack is with
+-`obstack_alloc', which is invoked almost like `malloc'.
+-
+- - Function: void * obstack_alloc (struct obstack *OBSTACK-PTR, int
+- SIZE)
+- This allocates an uninitialized block of SIZE bytes in an obstack
+- and returns its address. Here OBSTACK-PTR specifies which obstack
+- to allocate the block in; it is the address of the `struct obstack'
+- object which represents the obstack. Each obstack function or
+- macro requires you to specify an OBSTACK-PTR as the first argument.
+-
+- This function calls the obstack's `obstack_chunk_alloc' function if
+- it needs to allocate a new chunk of memory; it returns a null
+- pointer if `obstack_chunk_alloc' returns one. In that case, it
+- has not changed the amount of memory allocated in the obstack. If
+- you supply an `obstack_chunk_alloc' function that calls `exit'
+- (*note Program Termination::.) or `longjmp' (*note Non-Local
+- Exits::.) when out of memory, then `obstack_alloc' will never
+- return a null pointer.
+-
+- For example, here is a function that allocates a copy of a string STR
+-in a specific obstack, which is in the variable `string_obstack':
+-
+- struct obstack string_obstack;
+-
+- char *
+- copystring (char *string)
+- {
+- char *s = (char *) obstack_alloc (&string_obstack,
+- strlen (string) + 1);
+- memcpy (s, string, strlen (string));
+- return s;
+- }
+-
+- To allocate a block with specified contents, use the function
+-`obstack_copy', declared like this:
+-
+- - Function: void * obstack_copy (struct obstack *OBSTACK-PTR, void
+- *ADDRESS, int SIZE)
+- This allocates a block and initializes it by copying SIZE bytes of
+- data starting at ADDRESS. It can return a null pointer under the
+- same conditions as `obstack_alloc'.
+-
+- - Function: void * obstack_copy0 (struct obstack *OBSTACK-PTR, void
+- *ADDRESS, int SIZE)
+- Like `obstack_copy', but appends an extra byte containing a null
+- character. This extra byte is not counted in the argument SIZE.
+-
+- The `obstack_copy0' function is convenient for copying a sequence of
+-characters into an obstack as a null-terminated string. Here is an
+-example of its use:
+-
+- char *
+- obstack_savestring (char *addr, int size)
+- {
+- return obstack_copy0 (&myobstack, addr, size);
+- }
+-
+-Contrast this with the previous example of `savestring' using `malloc'
+-(*note Basic Allocation::.).
+-
+-
+-File: libc.info, Node: Freeing Obstack Objects, Next: Obstack Functions,
Prev: Allocation in an Obstack, Up: Obstacks
+-
+-Freeing Objects in an Obstack
+------------------------------
+-
+- To free an object allocated in an obstack, use the function
+-`obstack_free'. Since the obstack is a stack of objects, freeing one
+-object automatically frees all other objects allocated more recently in
+-the same obstack.
+-
+- - Function: void obstack_free (struct obstack *OBSTACK-PTR, void
+- *OBJECT)
+- If OBJECT is a null pointer, everything allocated in the obstack
+- is freed. Otherwise, OBJECT must be the address of an object
+- allocated in the obstack. Then OBJECT is freed, along with
+- everything allocated in OBSTACK since OBJECT.
+-
+- Note that if OBJECT is a null pointer, the result is an
+-uninitialized obstack. To free all storage in an obstack but leave it
+-valid for further allocation, call `obstack_free' with the address of
+-the first object allocated on the obstack:
+-
+- obstack_free (obstack_ptr, first_object_allocated_ptr);
+-
+- Recall that the objects in an obstack are grouped into chunks. When
+-all the objects in a chunk become free, the obstack library
+-automatically frees the chunk (*note Preparing for Obstacks::.). Then
+-other obstacks, or non-obstack allocation, can reuse the space of the
+-chunk.
+-
+-
+-File: libc.info, Node: Obstack Functions, Next: Growing Objects, Prev:
Freeing Obstack Objects, Up: Obstacks
+-
+-Obstack Functions and Macros
+-----------------------------
+-
+- The interfaces for using obstacks may be defined either as functions
+-or as macros, depending on the compiler. The obstack facility works
+-with all C compilers, including both ISO C and traditional C, but there
+-are precautions you must take if you plan to use compilers other than
+-GNU C.
+-
+- If you are using an old-fashioned non-ISO C compiler, all the obstack
+-"functions" are actually defined only as macros. You can call these
+-macros like functions, but you cannot use them in any other way (for
+-example, you cannot take their address).
+-
+- Calling the macros requires a special precaution: namely, the first
+-operand (the obstack pointer) may not contain any side effects, because
+-it may be computed more than once. For example, if you write this:
+-
+- obstack_alloc (get_obstack (), 4);
+-
+-you will find that `get_obstack' may be called several times. If you
+-use `*obstack_list_ptr++' as the obstack pointer argument, you will get
+-very strange results since the incrementation may occur several times.
+-
+- In ISO C, each function has both a macro definition and a function
+-definition. The function definition is used if you take the address of
+-the function without calling it. An ordinary call uses the macro
+-definition by default, but you can request the function definition
+-instead by writing the function name in parentheses, as shown here:
+-
+- char *x;
+- void *(*funcp) ();
+- /* Use the macro. */
+- x = (char *) obstack_alloc (obptr, size);
+- /* Call the function. */
+- x = (char *) (obstack_alloc) (obptr, size);
+- /* Take the address of the function. */
+- funcp = obstack_alloc;
+-
+-This is the same situation that exists in ISO C for the standard library
+-functions. *Note Macro Definitions::.
+-
+- *Warning:* When you do use the macros, you must observe the
+-precaution of avoiding side effects in the first operand, even in ISO C.
+-
+- If you use the GNU C compiler, this precaution is not necessary,
+-because various language extensions in GNU C permit defining the macros
+-so as to compute each argument only once.
+-
+-
+-File: libc.info, Node: Growing Objects, Next: Extra Fast Growing, Prev:
Obstack Functions, Up: Obstacks
+-
+-Growing Objects
+----------------
+-
+- Because storage in obstack chunks is used sequentially, it is
+-possible to build up an object step by step, adding one or more bytes
+-at a time to the end of the object. With this technique, you do not
+-need to know how much data you will put in the object until you come to
+-the end of it. We call this the technique of "growing objects". The
+-special functions for adding data to the growing object are described
+-in this section.
+-
+- You don't need to do anything special when you start to grow an
+-object. Using one of the functions to add data to the object
+-automatically starts it. However, it is necessary to say explicitly
+-when the object is finished. This is done with the function
+-`obstack_finish'.
+-
+- The actual address of the object thus built up is not known until the
+-object is finished. Until then, it always remains possible that you
+-will add so much data that the object must be copied into a new chunk.
+-
+- While the obstack is in use for a growing object, you cannot use it
+-for ordinary allocation of another object. If you try to do so, the
+-space already added to the growing object will become part of the other
+-object.
+-
+- - Function: void obstack_blank (struct obstack *OBSTACK-PTR, int SIZE)
+- The most basic function for adding to a growing object is
+- `obstack_blank', which adds space without initializing it.
+-
+- - Function: void obstack_grow (struct obstack *OBSTACK-PTR, void
+- *DATA, int SIZE)
+- To add a block of initialized space, use `obstack_grow', which is
+- the growing-object analogue of `obstack_copy'. It adds SIZE bytes
+- of data to the growing object, copying the contents from DATA.
+-
+- - Function: void obstack_grow0 (struct obstack *OBSTACK-PTR, void
+- *DATA, int SIZE)
+- This is the growing-object analogue of `obstack_copy0'. It adds
+- SIZE bytes copied from DATA, followed by an additional null
+- character.
+-
+- - Function: void obstack_1grow (struct obstack *OBSTACK-PTR, char C)
+- To add one character at a time, use the function `obstack_1grow'.
+- It adds a single byte containing C to the growing object.
+-
+- - Function: void obstack_ptr_grow (struct obstack *OBSTACK-PTR, void
+- *DATA)
+- Adding the value of a pointer one can use the function
+- `obstack_ptr_grow'. It adds `sizeof (void *)' bytes containing
+- the value of DATA.
+-
+- - Function: void obstack_int_grow (struct obstack *OBSTACK-PTR, int
+- DATA)
+- A single value of type `int' can be added by using the
+- `obstack_int_grow' function. It adds `sizeof (int)' bytes to the
+- growing object and initializes them with the value of DATA.
+-
+- - Function: void * obstack_finish (struct obstack *OBSTACK-PTR)
+- When you are finished growing the object, use the function
+- `obstack_finish' to close it off and return its final address.
+-
+- Once you have finished the object, the obstack is available for
+- ordinary allocation or for growing another object.
+-
+- This function can return a null pointer under the same conditions
+- as `obstack_alloc' (*note Allocation in an Obstack::.).
+-
+- When you build an object by growing it, you will probably need to
+-know afterward how long it became. You need not keep track of this as
+-you grow the object, because you can find out the length from the
+-obstack just before finishing the object with the function
+-`obstack_object_size', declared as follows:
+-
+- - Function: int obstack_object_size (struct obstack *OBSTACK-PTR)
+- This function returns the current size of the growing object, in
+- bytes. Remember to call this function *before* finishing the
+- object. After it is finished, `obstack_object_size' will return
+- zero.
+-
+- If you have started growing an object and wish to cancel it, you
+-should finish it and then free it, like this:
+-
+- obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
+-
+-This has no effect if no object was growing.
+-
+- You can use `obstack_blank' with a negative size argument to make
+-the current object smaller. Just don't try to shrink it beyond zero
+-length--there's no telling what will happen if you do that.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-30
glibc-2.0.1/manual/libc.info-30
+--- ../glibc-2.0.1/manual/libc.info-30 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-30 1970-01-01 01:00:00.000000000 +0100
+@@ -1,530 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+- This file documents the GNU C library.
+-
+- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+- Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+- Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+- Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: Copying, Next: Concept Index, Prev: Maintenance,
Up: Top
+-
+-GNU LIBRARY GENERAL PUBLIC LICENSE
+-**********************************
+-
+- Version 2, June 1991
+-
+- Copyright (C) 1991 Free Software Foundation, Inc.
+- 675 Mass Ave, Cambridge, MA 02139, USA
+- Everyone is permitted to copy and distribute verbatim copies
+- of this license document, but changing it is not allowed.
+-
+- [This is the first released version of the library GPL. It is
+- numbered 2 because it goes with version 2 of the ordinary GPL.]
+-
+-Preamble
+-========
+-
+- The licenses for most software are designed to take away your
+-freedom to share and change it. By contrast, the GNU General Public
+-Licenses are intended to guarantee your freedom to share and change
+-free software--to make sure the software is free for all its users.
+-
+- This license, the Library General Public License, applies to some
+-specially designated Free Software Foundation software, and to any
+-other libraries whose authors decide to use it. You can use it for
+-your libraries, too.
+-
+- When we speak of free software, we are referring to freedom, not
+-price. Our General Public Licenses are designed to make sure that you
+-have the freedom to distribute copies of free software (and charge for
+-this service if you wish), that you receive source code or can get it
+-if you want it, that you can change the software or use pieces of it in
+-new free programs; and that you know you can do these things.
+-
+- To protect your rights, we need to make restrictions that forbid
+-anyone to deny you these rights or to ask you to surrender the rights.
+-These restrictions translate to certain responsibilities for you if you
+-distribute copies of the library, or if you modify it.
+-
+- For example, if you distribute copies of the library, whether gratis
+-or for a fee, you must give the recipients all the rights that we gave
+-you. You must make sure that they, too, receive or can get the source
+-code. If you link a program with the library, you must provide
+-complete object files to the recipients so that they can relink them
+-with the library, after making changes to the library and recompiling
+-it. And you must show them these terms so they know their rights.
+-
+- Our method of protecting your rights has two steps: (1) copyright
+-the library, and (2) offer you this license which gives you legal
+-permission to copy, distribute and/or modify the library.
+-
+- Also, for each distributor's protection, we want to make certain
+-that everyone understands that there is no warranty for this free
+-library. If the library is modified by someone else and passed on, we
+-want its recipients to know that what they have is not the original
+-version, so that any problems introduced by others will not reflect on
+-the original authors' reputations.
+-
+- Finally, any free program is threatened constantly by software
+-patents. We wish to avoid the danger that companies distributing free
+-software will individually obtain patent licenses, thus in effect
+-transforming the program into proprietary software. To prevent this,
+-we have made it clear that any patent must be licensed for everyone's
+-free use or not licensed at all.
+-
+- Most GNU software, including some libraries, is covered by the
+-ordinary GNU General Public License, which was designed for utility
+-programs. This license, the GNU Library General Public License,
+-applies to certain designated libraries. This license is quite
+-different from the ordinary one; be sure to read it in full, and don't
+-assume that anything in it is the same as in the ordinary license.
+-
+- The reason we have a separate public license for some libraries is
+-that they blur the distinction we usually make between modifying or
+-adding to a program and simply using it. Linking a program with a
+-library, without changing the library, is in some sense simply using
+-the library, and is analogous to running a utility program or
+-application program. However, in a textual and legal sense, the linked
+-executable is a combined work, a derivative of the original library,
+-and the ordinary General Public License treats it as such.
+-
+- Because of this blurred distinction, using the ordinary General
+-Public License for libraries did not effectively promote software
+-sharing, because most developers did not use the libraries. We
+-concluded that weaker conditions might promote sharing better.
+-
+- However, unrestricted linking of non-free programs would deprive the
+-users of those programs of all benefit from the free status of the
+-libraries themselves. This Library General Public License is intended
+-to permit developers of non-free programs to use free libraries, while
+-preserving your freedom as a user of such programs to change the free
+-libraries that are incorporated in them. (We have not seen how to
+-achieve this as regards changes in header files, but we have achieved
+-it as regards changes in the actual functions of the Library.) The
+-hope is that this will lead to faster development of free libraries.
+-
+- The precise terms and conditions for copying, distribution and
+-modification follow. Pay close attention to the difference between a
+-"work based on the library" and a "work that uses the library". The
+-former contains code derived from the library, while the latter only
+-works together with the library.
+-
+- Note that it is possible for a library to be covered by the ordinary
+-General Public License rather than by this special one.
+-
+- TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+-
+- 0. This License Agreement applies to any software library which
+- contains a notice placed by the copyright holder or other
+- authorized party saying it may be distributed under the terms of
+- this Library General Public License (also called "this License").
+- Each licensee is addressed as "you".
+-
+- A "library" means a collection of software functions and/or data
+- prepared so as to be conveniently linked with application programs
+- (which use some of those functions and data) to form executables.
+-
+- The "Library", below, refers to any such software library or work
+- which has been distributed under these terms. A "work based on the
+- Library" means either the Library or any derivative work under
+- copyright law: that is to say, a work containing the Library or a
+- portion of it, either verbatim or with modifications and/or
+- translated straightforwardly into another language. (Hereinafter,
+- translation is included without limitation in the term
+- "modification".)
+-
+- "Source code" for a work means the preferred form of the work for
+- making modifications to it. For a library, complete source code
+- means all the source code for all modules it contains, plus any
+- associated interface definition files, plus the scripts used to
+- control compilation and installation of the library.
+-
+- Activities other than copying, distribution and modification are
+- not covered by this License; they are outside its scope. The act
+- of running a program using the Library is not restricted, and
+- output from such a program is covered only if its contents
+- constitute a work based on the Library (independent of the use of
+- the Library in a tool for writing it). Whether that is true
+- depends on what the Library does and what the program that uses
+- the Library does.
+-
+- 1. You may copy and distribute verbatim copies of the Library's
+- complete source code as you receive it, in any medium, provided
+- that you conspicuously and appropriately publish on each copy an
+- appropriate copyright notice and disclaimer of warranty; keep
+- intact all the notices that refer to this License and to the
+- absence of any warranty; and distribute a copy of this License
+- along with the Library.
+-
+- You may charge a fee for the physical act of transferring a copy,
+- and you may at your option offer warranty protection in exchange
+- for a fee.
+-
+- 2. You may modify your copy or copies of the Library or any portion
+- of it, thus forming a work based on the Library, and copy and
+- distribute such modifications or work under the terms of Section 1
+- above, provided that you also meet all of these conditions:
+-
+- a. The modified work must itself be a software library.
+-
+- b. You must cause the files modified to carry prominent notices
+- stating that you changed the files and the date of any change.
+-
+- c. You must cause the whole of the work to be licensed at no
+- charge to all third parties under the terms of this License.
+-
+- d. If a facility in the modified Library refers to a function or
+- a table of data to be supplied by an application program that
+- uses the facility, other than as an argument passed when the
+- facility is invoked, then you must make a good faith effort
+- to ensure that, in the event an application does not supply
+- such function or table, the facility still operates, and
+- performs whatever part of its purpose remains meaningful.
+-
+- (For example, a function in a library to compute square roots
+- has a purpose that is entirely well-defined independent of the
+- application. Therefore, Subsection 2d requires that any
+- application-supplied function or table used by this function
+- must be optional: if the application does not supply it, the
+- square root function must still compute square roots.)
+-
+- These requirements apply to the modified work as a whole. If
+- identifiable sections of that work are not derived from the
+- Library, and can be reasonably considered independent and separate
+- works in themselves, then this License, and its terms, do not
+- apply to those sections when you distribute them as separate
+- works. But when you distribute the same sections as part of a
+- whole which is a work based on the Library, the distribution of
+- the whole must be on the terms of this License, whose permissions
+- for other licensees extend to the entire whole, and thus to each
+- and every part regardless of who wrote it.
+-
+- Thus, it is not the intent of this section to claim rights or
+- contest your rights to work written entirely by you; rather, the
+- intent is to exercise the right to control the distribution of
+- derivative or collective works based on the Library.
+-
+- In addition, mere aggregation of another work not based on the
+- Library with the Library (or with a work based on the Library) on
+- a volume of a storage or distribution medium does not bring the
+- other work under the scope of this License.
+-
+- 3. You may opt to apply the terms of the ordinary GNU General Public
+- License instead of this License to a given copy of the Library.
+- To do this, you must alter all the notices that refer to this
+- License, so that they refer to the ordinary GNU General Public
+- License, version 2, instead of to this License. (If a newer
+- version than version 2 of the ordinary GNU General Public License
+- has appeared, then you can specify that version instead if you
+- wish.) Do not make any other change in these notices.
+-
+- Once this change is made in a given copy, it is irreversible for
+- that copy, so the ordinary GNU General Public License applies to
+- all subsequent copies and derivative works made from that copy.
+-
+- This option is useful when you wish to copy part of the code of
+- the Library into a program that is not a library.
+-
+- 4. You may copy and distribute the Library (or a portion or
+- derivative of it, under Section 2) in object code or executable
+- form under the terms of Sections 1 and 2 above provided that you
+- accompany it with the complete corresponding machine-readable
+- source code, which must be distributed under the terms of Sections
+- 1 and 2 above on a medium customarily used for software
+- interchange.
+-
+- If distribution of object code is made by offering access to copy
+- from a designated place, then offering equivalent access to copy
+- the source code from the same place satisfies the requirement to
+- distribute the source code, even though third parties are not
+- compelled to copy the source along with the object code.
+-
+- 5. A program that contains no derivative of any portion of the
+- Library, but is designed to work with the Library by being
+- compiled or linked with it, is called a "work that uses the
+- Library". Such a work, in isolation, is not a derivative work of
+- the Library, and therefore falls outside the scope of this License.
+-
+- However, linking a "work that uses the Library" with the Library
+- creates an executable that is a derivative of the Library (because
+- it contains portions of the Library), rather than a "work that
+- uses the library". The executable is therefore covered by this
+- License. Section 6 states terms for distribution of such
+- executables.
+-
+- When a "work that uses the Library" uses material from a header
+- file that is part of the Library, the object code for the work may
+- be a derivative work of the Library even though the source code is
+- not. Whether this is true is especially significant if the work
+- can be linked without the Library, or if the work is itself a
+- library. The threshold for this to be true is not precisely
+- defined by law.
+-
+- If such an object file uses only numerical parameters, data
+- structure layouts and accessors, and small macros and small inline
+- functions (ten lines or less in length), then the use of the object
+- file is unrestricted, regardless of whether it is legally a
+- derivative work. (Executables containing this object code plus
+- portions of the Library will still fall under Section 6.)
+-
+- Otherwise, if the work is a derivative of the Library, you may
+- distribute the object code for the work under the terms of Section
+- 6. Any executables containing that work also fall under Section 6,
+- whether or not they are linked directly with the Library itself.
+-
+- 6. As an exception to the Sections above, you may also compile or
+- link a "work that uses the Library" with the Library to produce a
+- work containing portions of the Library, and distribute that work
+- under terms of your choice, provided that the terms permit
+- modification of the work for the customer's own use and reverse
+- engineering for debugging such modifications.
+-
+- You must give prominent notice with each copy of the work that the
+- Library is used in it and that the Library and its use are covered
+- by this License. You must supply a copy of this License. If the
+- work during execution displays copyright notices, you must include
+- the copyright notice for the Library among them, as well as a
+- reference directing the user to the copy of this License. Also,
+- you must do one of these things:
+-
+- a. Accompany the work with the complete corresponding
+- machine-readable source code for the Library including
+- whatever changes were used in the work (which must be
+- distributed under Sections 1 and 2 above); and, if the work
+- is an executable linked with the Library, with the complete
+- machine-readable "work that uses the Library", as object code
+- and/or source code, so that the user can modify the Library
+- and then relink to produce a modified executable containing
+- the modified Library. (It is understood that the user who
+- changes the contents of definitions files in the Library will
+- not necessarily be able to recompile the application to use
+- the modified definitions.)
+-
+- b. Accompany the work with a written offer, valid for at least
+- three years, to give the same user the materials specified in
+- Subsection 6a, above, for a charge no more than the cost of
+- performing this distribution.
+-
+- c. If distribution of the work is made by offering access to copy
+- from a designated place, offer equivalent access to copy the
+- above specified materials from the same place.
+-
+- d. Verify that the user has already received a copy of these
+- materials or that you have already sent this user a copy.
+-
+- For an executable, the required form of the "work that uses the
+- Library" must include any data and utility programs needed for
+- reproducing the executable from it. However, as a special
+- exception, the source code distributed need not include anything
+- that is normally distributed (in either source or binary form)
+- with the major components (compiler, kernel, and so on) of the
+- operating system on which the executable runs, unless that
+- component itself accompanies the executable.
+-
+- It may happen that this requirement contradicts the license
+- restrictions of other proprietary libraries that do not normally
+- accompany the operating system. Such a contradiction means you
+- cannot use both them and the Library together in an executable
+- that you distribute.
+-
+- 7. You may place library facilities that are a work based on the
+- Library side-by-side in a single library together with other
+- library facilities not covered by this License, and distribute
+- such a combined library, provided that the separate distribution
+- of the work based on the Library and of the other library
+- facilities is otherwise permitted, and provided that you do these
+- two things:
+-
+- a. Accompany the combined library with a copy of the same work
+- based on the Library, uncombined with any other library
+- facilities. This must be distributed under the terms of the
+- Sections above.
+-
+- b. Give prominent notice with the combined library of the fact
+- that part of it is a work based on the Library, and explaining
+- where to find the accompanying uncombined form of the same
+- work.
+-
+- 8. You may not copy, modify, sublicense, link with, or distribute the
+- Library except as expressly provided under this License. Any
+- attempt otherwise to copy, modify, sublicense, link with, or
+- distribute the Library is void, and will automatically terminate
+- your rights under this License. However, parties who have
+- received copies, or rights, from you under this License will not
+- have their licenses terminated so long as such parties remain in
+- full compliance.
+-
+- 9. You are not required to accept this License, since you have not
+- signed it. However, nothing else grants you permission to modify
+- or distribute the Library or its derivative works. These actions
+- are prohibited by law if you do not accept this License.
+- Therefore, by modifying or distributing the Library (or any work
+- based on the Library), you indicate your acceptance of this
+- License to do so, and all its terms and conditions for copying,
+- distributing or modifying the Library or works based on it.
+-
+- 10. Each time you redistribute the Library (or any work based on the
+- Library), the recipient automatically receives a license from the
+- original licensor to copy, distribute, link with or modify the
+- Library subject to these terms and conditions. You may not impose
+- any further restrictions on the recipients' exercise of the rights
+- granted herein. You are not responsible for enforcing compliance
+- by third parties to this License.
+-
+- 11. If, as a consequence of a court judgment or allegation of patent
+- infringement or for any other reason (not limited to patent
+- issues), conditions are imposed on you (whether by court order,
+- agreement or otherwise) that contradict the conditions of this
+- License, they do not excuse you from the conditions of this
+- License. If you cannot distribute so as to satisfy simultaneously
+- your obligations under this License and any other pertinent
+- obligations, then as a consequence you may not distribute the
+- Library at all. For example, if a patent license would not permit
+- royalty-free redistribution of the Library by all those who
+- receive copies directly or indirectly through you, then the only
+- way you could satisfy both it and this License would be to refrain
+- entirely from distribution of the Library.
+-
+- If any portion of this section is held invalid or unenforceable
+- under any particular circumstance, the balance of the section is
+- intended to apply, and the section as a whole is intended to apply
+- in other circumstances.
+-
+- It is not the purpose of this section to induce you to infringe any
+- patents or other property right claims or to contest validity of
+- any such claims; this section has the sole purpose of protecting
+- the integrity of the free software distribution system which is
+- implemented by public license practices. Many people have made
+- generous contributions to the wide range of software distributed
+- through that system in reliance on consistent application of that
+- system; it is up to the author/donor to decide if he or she is
+- willing to distribute software through any other system and a
+- licensee cannot impose that choice.
+-
+- This section is intended to make thoroughly clear what is believed
+- to be a consequence of the rest of this License.
+-
+- 12. If the distribution and/or use of the Library is restricted in
+- certain countries either by patents or by copyrighted interfaces,
+- the original copyright holder who places the Library under this
+- License may add an explicit geographical distribution limitation
+- excluding those countries, so that distribution is permitted only
+- in or among countries not thus excluded. In such case, this
+- License incorporates the limitation as if written in the body of
+- this License.
+-
+- 13. The Free Software Foundation may publish revised and/or new
+- versions of the Library General Public License from time to time.
+- Such new versions will be similar in spirit to the present version,
+- but may differ in detail to address new problems or concerns.
+-
+- Each version is given a distinguishing version number. If the
+- Library specifies a version number of this License which applies
+- to it and "any later version", you have the option of following
+- the terms and conditions either of that version or of any later
+- version published by the Free Software Foundation. If the Library
+- does not specify a license version number, you may choose any
+- version ever published by the Free Software Foundation.
+-
+- 14. If you wish to incorporate parts of the Library into other free
+- programs whose distribution conditions are incompatible with these,
+- write to the author to ask for permission. For software which is
+- copyrighted by the Free Software Foundation, write to the Free
+- Software Foundation; we sometimes make exceptions for this. Our
+- decision will be guided by the two goals of preserving the free
+- status of all derivatives of our free software and of promoting
+- the sharing and reuse of software generally.
+-
+- NO WARRANTY
+-
+- 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+- WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE
+- LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+- HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT
+- WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
+- NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+- FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
+- QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE
+- LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
+- SERVICING, REPAIR OR CORRECTION.
+-
+- 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+- WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
+- MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
+- LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
+- INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
+- INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF
+- DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
+- OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY
+- OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
+- ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+-
+- END OF TERMS AND CONDITIONS
+-
+-How to Apply These Terms to Your New Libraries
+-==============================================
+-
+- If you develop a new library, and you want it to be of the greatest
+-possible use to the public, we recommend making it free software that
+-everyone can redistribute and change. You can do so by permitting
+-redistribution under these terms (or, alternatively, under the terms of
+-the ordinary General Public License).
+-
+- To apply these terms, attach the following notices to the library.
+-It is safest to attach them to the start of each source file to most
+-effectively convey the exclusion of warranty; and each file should have
+-at least the "copyright" line and a pointer to where the full notice is
+-found.
+-
+- ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES.
+- Copyright (C) YEAR NAME OF AUTHOR
+-
+- This library is free software; you can redistribute it and/or modify it
+- under the terms of the GNU Library General Public License as published
+- by the Free Software Foundation; either version 2 of the License, or (at
+- your option) any later version.
+-
+- This library is distributed in the hope that it will be useful, but
+- WITHOUT ANY WARRANTY; without even the implied warranty of
+- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+- Library General Public License for more details.
+-
+- You should have received a copy of the GNU Library General Public
+- License along with this library; if not, write to the Free Software
+- Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+-
+- Also add information on how to contact you by electronic and paper
+-mail.
+-
+- You should also get your employer (if you work as a programmer) or
+-your school, if any, to sign a "copyright disclaimer" for the library,
+-if necessary. Here is a sample; alter the names:
+-
+- Yoyodyne, Inc., hereby disclaims all copyright interest in the library
+- `Frob' (a library for tweaking knobs) written by James Random Hacker.
+-
+- SIGNATURE OF TY COON, 1 April 1990
+- Ty Coon, President of Vice
+-
+- That's all there is to it!
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-31
glibc-2.0.1/manual/libc.info-31
+--- ../glibc-2.0.1/manual/libc.info-31 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-31 1970-01-01 01:00:00.000000000 +0100
+@@ -1,863 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+- This file documents the GNU C library.
+-
+- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+- Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+- Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+- Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: Concept Index, Next: Type Index, Prev: Copying,
Up: Top
+-
+-Concept Index
+-*************
+-
+-* Menu:
+-
+-* /etc/nsswitch.conf: NSS Configuration File.
+-* 4.N BSD Unix: Berkeley Unix.
+-* _POSIX_OPTION_ORDER environment variable.: Standard Environment.
+-* abort signal: Program Error Signals.
+-* aborting a program: Aborting a Program.
+-* absolute file name: File Name Resolution.
+-* absolute value functions: Absolute Value.
+-* accepting connections: Accepting Connections.
+-* access permission for a file: Access Permission.
+-* access, testing for: Testing File Access.
+-* accessing directories: Accessing Directories.
+-* address of socket: Socket Addresses.
+-* alarm signal: Alarm Signals.
+-* alarms, setting: Setting an Alarm.
+-* alignment (in obstacks): Obstacks Data Alignment.
+-* alignment (with malloc): Aligned Memory Blocks.
+-* alloca disadvantages: Disadvantages of Alloca.
+-* alloca function: Variable Size Automatic.
+-* allocation (obstacks): Allocation in an Obstack.
+-* allocation hooks, for malloc: Hooks for Malloc.
+-* allocation of memory with malloc: Basic Allocation.
+-* allocation size of string: Representation of Strings.
+-* allocation statistics: Statistics of Malloc.
+-* alphabetic character: Classification of Characters.
+-* alphanumeric character: Classification of Characters.
+-* append-access files: File Position.
+-* argc (program argument count): Program Arguments.
+-* argument promotion: Calling Variadics.
+-* arguments (variadic functions): Receiving Arguments.
+-* arguments, how many: How Many Arguments.
+-* arguments, to program: Program Arguments.
+-* argv (program argument vector): Program Arguments.
+-* arithmetic expansion: Expansion Stages.
+-* array comparison functions: String/Array Comparison.
+-* array copy functions: Copying and Concatenation.
+-* array search function: Array Search Function.
+-* array sort function: Array Sort Function.
+-* ASCII character: Classification of Characters.
+-* assertions: Consistency Checking.
+-* attributes of a file: Attribute Meanings.
+-* automatic allocation: Memory Concepts.
+-* automatic freeing: Variable Size Automatic.
+-* automatic storage with variable size: Variable Size Automatic.
+-* background job: Concepts of Job Control.
+-* background job, launching: Foreground and Background.
+-* base (of floating point number): Floating Point Concepts.
+-* basic byte sequence: Multibyte Char Intro.
+-* baud rate: Line Speed.
+-* Berkeley Unix: Berkeley Unix.
+-* bias (of floating point number exponent): Floating Point Concepts.
+-* big-endian: Byte Order.
+-* binary I/O to a stream: Block Input/Output.
+-* binary search function (for arrays): Array Search Function.
+-* binary stream: Binary Streams.
+-* binding a socket address: Socket Addresses.
+-* blank character: Classification of Characters.
+-* block I/O to a stream: Block Input/Output.
+-* blocked signals: Delivery of Signal.
+-* blocked signals, checking for: Checking for Pending Signals.
+-* blocking signals: Blocking Signals.
+-* blocking signals, in a handler: Blocking for Handler.
+-* bootstrapping, and services: Actions in the NSS configuration.
+-* break condition, detecting: Input Modes.
+-* break condition, generating: Line Control.
+-* breaking a string into tokens: Finding Tokens in a String.
+-* broken pipe signal: Operation Error Signals.
+-* broken-down time <1>: Broken-down Time.
+-* broken-down time: Calendar Time.
+-* BSD compatibility library: Process Group Functions.
+-* BSD compatibility library.: Feature Test Macros.
+-* BSD Unix: Berkeley Unix.
+-* buffering of streams: Stream Buffering.
+-* buffering, controlling: Controlling Buffering.
+-* bugs, reporting: Reporting Bugs.
+-* bus error: Program Error Signals.
+-* byte order conversion, for socket: Byte Order.
+-* byte stream: Socket Concepts.
+-* calendar time: Calendar Time.
+-* calendar time and broken-down time: Broken-down Time.
+-* calling variadic functions: Calling Variadics.
+-* canonical input processing: Canonical or Not.
+-* capacity limits, POSIX: General Limits.
+-* carrier detect: Control Modes.
+-* case conversion of characters: Case Conversion.
+-* catching signals: Delivery of Signal.
+-* categories for locales: Locale Categories.
+-* change working directory: Working Directory.
+-* changing the locale: Setting the Locale.
+-* changing the size of a block (malloc): Changing Block Size.
+-* changing the size of a block (obstacks): Growing Objects.
+-* channels: Stream/Descriptor Precautions.
+-* character case conversion: Case Conversion.
+-* character code: Wide Char Intro.
+-* character predicates: Classification of Characters.
+-* character testing: Classification of Characters.
+-* checking for pending signals: Checking for Pending Signals.
+-* child process <1>: Process Creation Concepts.
+-* child process: Processes.
+-* child process signal: Job Control Signals.
+-* chunks: Obstack Chunks.
+-* classification of characters: Classification of Characters.
+-* cleaning up a stream: Linked Channels.
+-* clearing terminal input queue: Line Control.
+-* client: Connections.
+-* clock ticks: Processor Time.
+-* close-on-exec (file descriptor flag): Descriptor Flags.
+-* closing a file descriptor: Opening and Closing Files.
+-* closing a socket: Closing a Socket.
+-* closing a stream: Closing Streams.
+-* code, character: Wide Char Intro.
+-* collating strings: Collation Functions.
+-* combining locales: Choosing Locale.
+-* command argument syntax: Argument Syntax.
+-* command arguments, parsing: Parsing Options.
+-* command line arguments: Program Arguments.
+-* command substitution: Expansion Stages.
+-* communication style (of a socket): Socket Concepts.
+-* comparing strings and arrays: String/Array Comparison.
+-* Comparison Function: Comparison Functions.
+-* concatenating strings: Copying and Concatenation.
+-* configurations, all supported: Supported Configurations.
+-* connecting a socket: Connecting.
+-* connection: Connections.
+-* consistency checking: Consistency Checking.
+-* consistency checking, of heap: Heap Consistency Checking.
+-* continue signal: Job Control Signals.
+-* control character: Classification of Characters.
+-* control operations on files: Control Operations.
+-* controlling process: Controlling Terminal.
+-* controlling terminal: Concepts of Job Control.
+-* controlling terminal, access to: Access to the Terminal.
+-* controlling terminal, determining: Identifying the Terminal.
+-* controlling terminal, setting: Open-time Flags.
+-* conversion specifications (printf): Formatted Output Basics.
+-* conversion specifications (scanf): Formatted Input Basics.
+-* converting byte order: Byte Order.
+-* converting case of characters: Case Conversion.
+-* converting extended characters: Converting One Char.
+-* converting extended strings: Wide String Conversion.
+-* converting file descriptor to stream: Descriptors and Streams.
+-* converting floats to integers: Rounding and Remainders.
+-* converting group ID to group name: Lookup Group.
+-* converting group name to group ID: Lookup Group.
+-* converting host address to name: Host Names.
+-* converting host name to address: Host Names.
+-* converting network name to network number: Networks Database.
+-* converting network number to network name: Networks Database.
+-* converting port number to service name: Services Database.
+-* converting service name to port number: Services Database.
+-* converting string to collation order: Collation Functions.
+-* converting strings to numbers: Parsing of Numbers.
+-* converting user ID to user name: Lookup User.
+-* converting user name to user ID: Lookup User.
+-* cookie, for custom stream: Streams and Cookies.
+-* copying strings and arrays: Copying and Concatenation.
+-* CPU time: Processor Time.
+-* create on open (file status flag): Open-time Flags.
+-* creating a directory: Creating Directories.
+-* creating a FIFO special file: FIFO Special Files.
+-* creating a pipe: Creating a Pipe.
+-* creating a pipe to a subprocess: Pipe to a Subprocess.
+-* creating a process: Process Creation Concepts.
+-* creating a socket: Creating a Socket.
+-* creating a socket pair: Socket Pairs.
+-* creating special files: Making Special Files.
+-* cube root function: Exponents and Logarithms.
+-* currency symbols: Currency Symbol.
+-* current working directory: Working Directory.
+-* custom streams: Custom Streams.
+-* customizing printf: Customizing Printf.
+-* data loss on sockets: Socket Concepts.
+-* databases: Name Service Switch.
+-* datagram socket: Datagrams.
+-* datagrams, transmitting: Sending Datagrams.
+-* date and time: Calendar Time.
+-* Daylight Saving Time: Broken-down Time.
+-* decimal digit character: Classification of Characters.
+-* decimal-point separator: General Numeric.
+-* declaration (compared to definition): Header Files.
+-* declaring variadic functions: Calling Variadics.
+-* default action (for a signal): Delivery of Signal.
+-* default action for a signal: Basic Signal Handling.
+-* default argument promotions: Calling Variadics.
+-* default value, and NSS: Notes on NSS Configuration File.
+-* defining new printf conversions: Customizing Printf.
+-* definition (compared to declaration): Header Files.
+-* delayed suspend character: Signal Characters.
+-* deleting a directory: Deleting Files.
+-* deleting a file: Deleting Files.
+-* delivery of signals: Delivery of Signal.
+-* descriptors and streams: Stream/Descriptor Precautions.
+-* digit character: Classification of Characters.
+-* directories, accessing: Accessing Directories.
+-* directories, creating: Creating Directories.
+-* directories, deleting: Deleting Files.
+-* directory: Directories.
+-* directory entry: Directories.
+-* directory stream: Accessing Directories.
+-* disadvantages of alloca: Disadvantages of Alloca.
+-* DISCARD character: Other Special.
+-* DNS server unavailable: Actions in the NSS configuration.
+-* domain (of socket): Socket Concepts.
+-* domain error: Domain and Range Errors.
+-* dot notation, for Internet addresses: Abstract Host Addresses.
+-* DSUSP character: Signal Characters.
+-* duplicating file descriptors: Duplicating Descriptors.
+-* dynamic allocation: Memory Concepts.
+-* echo of terminal input: Local Modes.
+-* effective group ID: Process Persona.
+-* effective user ID: Process Persona.
+-* efficiency and malloc: Efficiency and Malloc.
+-* efficiency and obstacks: Extra Fast Growing.
+-* efficiency of chunks: Obstack Chunks.
+-* EINTR, and restarting interrupted primitives: Interrupted Primitives.
+-* end of file, on a stream: EOF and Errors.
+-* end-of-file, on a file descriptor: I/O Primitives.
+-* environment: Environment Variables.
+-* environment access: Environment Access.
+-* environment representation: Environment Access.
+-* environment variable: Environment Variables.
+-* EOF character: Editing Characters.
+-* EOL character: Editing Characters.
+-* EOL2 character: Editing Characters.
+-* epoch: Simple Calendar Time.
+-* ERASE character: Editing Characters.
+-* error codes: Error Reporting.
+-* error reporting: Error Reporting.
+-* establishing a handler: Signal Actions.
+-* ethers: NSS Basics.
+-* exception: Program Error Signals.
+-* exclusive lock: File Locks.
+-* exec functions: Executing a File.
+-* executing a file: Executing a File.
+-* exit status: Exit Status.
+-* exit status value: Program Termination.
+-* expansion of shell words: Word Expansion.
+-* exponent (of floating point number): Floating Point Concepts.
+-* exponentiation functions: Exponents and Logarithms.
+-* extended character sets: Extended Characters.
+-* extended characters, converting: Converting One Char.
+-* extended strings, converting representations: Wide String Conversion.
+-* extending printf: Customizing Printf.
+-* extracting file descriptor from stream: Descriptors and Streams.
+-* fcntl function: Control Operations.
+-* feature test macros: Feature Test Macros.
+-* field splitting: Expansion Stages.
+-* FIFO special file: Pipes and FIFOs.
+-* file access permission: Access Permission.
+-* file access time: File Times.
+-* file attribute modification time: File Times.
+-* file attributes: Attribute Meanings.
+-* file creation mask: Setting Permissions.
+-* file descriptor flags: Descriptor Flags.
+-* file descriptor sets, for select: Waiting for I/O.
+-* file descriptors, standard: Descriptors and Streams.
+-* file locks: File Locks.
+-* file modification time: File Times.
+-* file name: File Names.
+-* file name component: Directories.
+-* file name errors: File Name Errors.
+-* file name resolution: File Name Resolution.
+-* file name translation flags: Open-time Flags.
+-* file names, multiple: Hard Links.
+-* file namespace, for sockets: File Namespace.
+-* file owner: File Owner.
+-* file permission bits: Permission Bits.
+-* file pointer: Streams.
+-* file position: File Position.
+-* file positioning on a file descriptor: File Position Primitive.
+-* file positioning on a stream: File Positioning.
+-* file status flags: File Status Flags.
+-* filtering i/o through subprocess: Pipe to a Subprocess.
+-* flag character (printf): Output Conversion Syntax.
+-* flag character (scanf): Input Conversion Syntax.
+-* flags for sigaction: Flags for Sigaction.
+-* flags, file name translation: Open-time Flags.
+-* flags, open-time action: Open-time Flags.
+-* floating point, IEEE: IEEE Floating Point.
+-* floating type measurements: Floating Type Macros.
+-* floating-point exception: Program Error Signals.
+-* flow control, terminal: Line Control.
+-* flushing a stream: Flushing Buffers.
+-* flushing terminal output queue: Line Control.
+-* foreground job: Concepts of Job Control.
+-* foreground job, launching: Foreground and Background.
+-* forking a process: Process Creation Concepts.
+-* format string, for printf: Formatted Output.
+-* format string, for scanf: Formatted Input.
+-* formatted input from a stream: Formatted Input.
+-* formatted output to a stream: Formatted Output.
+-* freeing (obstacks): Freeing Obstack Objects.
+-* freeing memory allocated with malloc: Freeing after Malloc.
+-* fully buffered stream: Buffering Concepts.
+-* function prototypes (variadic): Variadic Prototypes.
+-* generation of signals: Signal Generation.
+-* globbing: Globbing.
+-* graphic character: Classification of Characters.
+-* Gregorian calendar: Calendar Time.
+-* group: NSS Basics.
+-* group database: Group Database.
+-* group ID: User and Group IDs.
+-* group name: User and Group IDs.
+-* group owner of a file: File Owner.
+-* grouping of digits: General Numeric.
+-* growing objects (in obstacks): Growing Objects.
+-* handle: Relocator Concepts.
+-* handling multiple signals: Merged Signals.
+-* hangup signal: Termination Signals.
+-* hard limit: Limits on Resources.
+-* hard link: Hard Links.
+-* header files: Header Files.
+-* heap consistency checking: Heap Consistency Checking.
+-* heap, dynamic allocation from: Unconstrained Allocation.
+-* heap, freeing memory from: Freeing after Malloc.
+-* hexadecimal digit character: Classification of Characters.
+-* hidden bit (of floating point number mantissa): Floating Point Concepts.
+-* high-priority data: Out-of-Band Data.
+-* high-resolution time: Calendar Time.
+-* holes in files: File Position Primitive.
+-* home directory: Standard Environment.
+-* HOME environment variable: Standard Environment.
+-* hook functions (of custom streams): Hook Functions.
+-* host address, Internet: Abstract Host Addresses.
+-* hosts: NSS Basics.
+-* hosts database: Host Names.
+-* how many arguments: How Many Arguments.
+-* hyperbolic functions: Hyperbolic Functions.
+-* identifying terminals: Is It a Terminal.
+-* IEEE floating point: Not a Number.
+-* IEEE floating point representation: IEEE Floating Point.
+-* IEEE Std 1003.1: POSIX.
+-* IEEE Std 1003.2: POSIX.
+-* ignore action for a signal: Basic Signal Handling.
+-* illegal instruction: Program Error Signals.
+-* impossible events: Consistency Checking.
+-* independent channels: Independent Channels.
+-* initial signal actions: Initial Signal Actions.
+-* inode number: Attribute Meanings.
+-* input available signal: Asynchronous I/O Signals.
+-* input conversions, for scanf: Table of Input Conversions.
+-* input from multiple files: Waiting for I/O.
+-* installation tools: Tools for Installation.
+-* installing the library: Installation.
+-* integer division functions: Integer Division.
+-* integer type range: Range of Type.
+-* integer type width: Width of Type.
+-* interactive signals, from terminal: Local Modes.
+-* interactive stop signal: Job Control Signals.
+-* internationalization: Locales.
+-* Internet host address: Abstract Host Addresses.
+-* Internet namespace, for sockets: Internet Namespace.
+-* interprocess communication, with FIFO: FIFO Special Files.
+-* interprocess communication, with pipes: Creating a Pipe.
+-* interprocess communication, with signals: Kill Example.
+-* interprocess communication, with sockets: Sockets.
+-* interrupt character: Signal Characters.
+-* interrupt signal: Termination Signals.
+-* interrupt-driven input: Interrupt Input.
+-* interrupting primitives: Interrupted Primitives.
+-* interval timer, setting: Setting an Alarm.
+-* INTR character: Signal Characters.
+-* inverse hyperbolic functions: Hyperbolic Functions.
+-* inverse trigonometric functions: Inverse Trig Functions.
+-* invocation of program: Program Arguments.
+-* ISO C: ISO C.
+-* job: Job Control.
+-* job control: Job Control.
+-* job control functions: Functions for Job Control.
+-* job control is optional: Job Control is Optional.
+-* job control signals: Job Control Signals.
+-* job control, enabling: Initializing the Shell.
+-* Kermit the frog: Search/Sort Example.
+-* KILL character: Editing Characters.
+-* kill signal: Termination Signals.
+-* killing a process: Signaling Another Process.
+-* LANG environment variable: Standard Environment.
+-* launching jobs: Launching Jobs.
+-* LC_COLLATE environment variable: Standard Environment.
+-* LC_CTYPE environment variable: Standard Environment.
+-* LC_MONETARY environment variable: Standard Environment.
+-* LC_NUMERIC environment variable: Standard Environment.
+-* LC_TIME environment variable: Standard Environment.
+-* leap second: Broken-down Time.
+-* length of multibyte character: Length of Char.
+-* length of string: Representation of Strings.
+-* level, for socket options: Socket Options.
+-* library: Introduction.
+-* limits on resource usage: Limits on Resources.
+-* limits, file name length: Limits for Files.
+-* limits, floating types: Floating Type Macros.
+-* limits, integer types: Range of Type.
+-* limits, link count of files: Limits for Files.
+-* limits, number of open files: General Limits.
+-* limits, number of processes: General Limits.
+-* limits, number of supplementary group IDs: General Limits.
+-* limits, pipe buffer size: Limits for Files.
+-* limits, POSIX: General Limits.
+-* limits, program argument size: General Limits.
+-* limits, terminal input queue: Limits for Files.
+-* limits, time zone name length: General Limits.
+-* line buffered stream: Buffering Concepts.
+-* line speed: Line Speed.
+-* lines (in a text file): Binary Streams.
+-* link: Directories.
+-* link, hard: Hard Links.
+-* link, soft: Symbolic Links.
+-* link, symbolic: Symbolic Links.
+-* linked channels: Linked Channels.
+-* listening (sockets): Listening.
+-* little-endian: Byte Order.
+-* LNEXT character: Other Special.
+-* local network address number: Abstract Host Addresses.
+-* local time: Calendar Time.
+-* locale categories: Locale Categories.
+-* locale, changing: Setting the Locale.
+-* locales: Locales.
+-* logarithm functions: Exponents and Logarithms.
+-* login name: User and Group IDs.
+-* login name, determining: Who Logged In.
+-* LOGNAME environment variable: Standard Environment.
+-* long jumps: Non-Local Exits.
+-* long-named options: Argument Syntax.
+-* longjmp: Advantages of Alloca.
+-* loss of data on sockets: Socket Concepts.
+-* lost resource signal: Operation Error Signals.
+-* lower-case character: Classification of Characters.
+-* macros: Obstack Functions.
+-* main function: Program Arguments.
+-* malloc function: Unconstrained Allocation.
+-* mantissa (of floating point number): Floating Point Concepts.
+-* matching failure, in scanf: Formatted Input Basics.
+-* maximum field width (scanf): Input Conversion Syntax.
+-* measurements of floating types: Floating Type Macros.
+-* memory allocation: Memory Allocation.
+-* memory usage warnings: Memory Warnings.
+-* merging of signals: Merged Signals.
+-* MIN termios slot: Noncanonical Input.
+-* minimum field width (printf): Output Conversion Syntax.
+-* mixing descriptors and streams: Stream/Descriptor Precautions.
+-* modem disconnect: Control Modes.
+-* modem status lines: Control Modes.
+-* monetary value formatting: Numeric Formatting.
+-* multibyte character, length of: Length of Char.
+-* multibyte characters: Multibyte Char Intro.
+-* multiple names for one file: Hard Links.
+-* multiplexing input: Waiting for I/O.
+-* name of running program: Error Messages.
+-* name of socket: Socket Addresses.
+-* Name Service Switch: Name Service Switch.
+-* name space: Reserved Names.
+-* names of signals: Standard Signals.
+-* namespace (of socket): Socket Concepts.
+-* NaN: Not a Number.
+-* Netgroup: Netgroup Data.
+-* netgroup: NSS Basics.
+-* network: NSS Basics.
+-* network byte order: Byte Order.
+-* network number: Abstract Host Addresses.
+-* network protocol: Socket Concepts.
+-* networks database: Networks Database.
+-* nisplus, and booting: Actions in the NSS configuration.
+-* nisplus, and completeness: Actions in the NSS configuration.
+-* non-blocking open: Open-time Flags.
+-* non-local exit, from signal handler: Longjmp in Handler.
+-* non-local exits: Non-Local Exits.
+-* noncanonical input processing: Canonical or Not.
+-* normalization functions (floating-point): Normalization Functions.
+-* normalized floating point number: Floating Point Concepts.
+-* not a number: Not a Number.
+-* NSS: Name Service Switch.
+-* nsswitch.conf: NSS Configuration File.
+-* null character: Representation of Strings.
+-* null pointer constant: Null Pointer Constant.
+-* number of arguments passed: How Many Arguments.
+-* number syntax, parsing: Parsing of Numbers.
+-* numeric value formatting: Numeric Formatting.
+-* obstack status: Status of an Obstack.
+-* obstacks: Obstacks.
+-* open-time action flags: Open-time Flags.
+-* opening a file: I/O Concepts.
+-* opening a file descriptor: Opening and Closing Files.
+-* opening a pipe: Creating a Pipe.
+-* opening a socket: Creating a Socket.
+-* opening a socket pair: Socket Pairs.
+-* opening a stream: Opening Streams.
+-* optimizing NSS: Notes on NSS Configuration File.
+-* optional arguments: Variadic Functions.
+-* optional POSIX features: System Options.
+-* orphaned process group: Orphaned Process Groups.
+-* out-of-band data: Out-of-Band Data.
+-* output conversions, for printf: Table of Output Conversions.
+-* output possible signal: Asynchronous I/O Signals.
+-* owner of a file: File Owner.
+-* packet: Socket Concepts.
+-* page boundary: Aligned Memory Blocks.
+-* parent directory: File Name Resolution.
+-* parent process <1>: Process Creation Concepts.
+-* parent process: Processes.
+-* parity checking: Input Modes.
+-* parsing a template string: Parsing a Template String.
+-* parsing numbers (in formatted input): Parsing of Numbers.
+-* parsing program arguments: Parsing Options.
+-* parsing tokens from a string: Finding Tokens in a String.
+-* passwd: NSS Basics.
+-* password database: User Database.
+-* PATH environment variable: Standard Environment.
+-* pause function: Waiting for a Signal.
+-* peeking at input: Unreading.
+-* pending signals: Delivery of Signal.
+-* pending signals, checking for: Checking for Pending Signals.
+-* permission to access a file: Access Permission.
+-* persona: Process Persona.
+-* pi (trigonometric constant): Trig Functions.
+-* pipe: Pipes and FIFOs.
+-* pipe signal: Operation Error Signals.
+-* pipe to a subprocess: Pipe to a Subprocess.
+-* port number: Ports.
+-* positioning a file descriptor: File Position Primitive.
+-* positioning a stream: File Positioning.
+-* POSIX: POSIX.
+-* POSIX capacity limits: General Limits.
+-* POSIX optional features: System Options.
+-* POSIX.1: POSIX.
+-* POSIX.2: POSIX.
+-* power functions: Exponents and Logarithms.
+-* precision (of floating point number): Floating Point Concepts.
+-* precision (printf): Output Conversion Syntax.
+-* predicates on arrays: String/Array Comparison.
+-* predicates on characters: Classification of Characters.
+-* predicates on strings: String/Array Comparison.
+-* primitives, interrupting: Interrupted Primitives.
+-* printing character: Classification of Characters.
+-* priority of a process: Priority.
+-* process <1>: Processes.
+-* process: Process Startup.
+-* process completion: Process Completion.
+-* process group functions: Functions for Job Control.
+-* process group ID: Launching Jobs.
+-* process group leader: Launching Jobs.
+-* process groups: Job Control.
+-* process ID: Process Creation Concepts.
+-* process image: Process Creation Concepts.
+-* process lifetime: Process Creation Concepts.
+-* process priority: Priority.
+-* process signal mask: Process Signal Mask.
+-* process termination: Program Termination.
+-* processor time: Processor Time.
+-* profiling alarm signal: Alarm Signals.
+-* profiling timer: Setting an Alarm.
+-* program argument syntax: Argument Syntax.
+-* program arguments: Program Arguments.
+-* program arguments, parsing: Parsing Options.
+-* program error signals: Program Error Signals.
+-* program name: Error Messages.
+-* program startup: Program Arguments.
+-* program termination: Program Termination.
+-* program termination signals: Termination Signals.
+-* programming your own streams: Custom Streams.
+-* protocol (of socket): Socket Concepts.
+-* protocol family: Socket Concepts.
+-* protocols: NSS Basics.
+-* protocols database: Protocols Database.
+-* prototypes for variadic functions: Variadic Prototypes.
+-* pseudo-random numbers: Pseudo-Random Numbers.
+-* punctuation character: Classification of Characters.
+-* pushing input back: Unreading.
+-* quick sort function (for arrays): Array Sort Function.
+-* QUIT character: Signal Characters.
+-* quit signal: Termination Signals.
+-* quote removal: Expansion Stages.
+-* race conditions, relating to job control: Launching Jobs.
+-* race conditions, relating to signals: Signals in Handler.
+-* radix (of floating point number): Floating Point Concepts.
+-* raising signals: Generating Signals.
+-* random numbers: Pseudo-Random Numbers.
+-* random-access files: File Position.
+-* range error: Domain and Range Errors.
+-* range of integer type: Range of Type.
+-* read lock: File Locks.
+-* reading from a directory: Accessing Directories.
+-* reading from a file descriptor: I/O Primitives.
+-* reading from a socket: Transferring Data.
+-* reading from a stream, by blocks: Block Input/Output.
+-* reading from a stream, by characters: Character Input.
+-* reading from a stream, formatted: Formatted Input.
+-* real group ID: Process Persona.
+-* real user ID: Process Persona.
+-* real-time timer: Setting an Alarm.
+-* receiving datagrams: Receiving Datagrams.
+-* record locking: File Locks.
+-* redirecting input and output: Duplicating Descriptors.
+-* reentrant functions: Nonreentrancy.
+-* reentrant NSS functions: NSS Module Names.
+-* relative file name: File Name Resolution.
+-* relocating memory allocator: Relocating Allocator.
+-* remainder functions: Rounding and Remainders.
+-* removal of quotes: Expansion Stages.
+-* removing a file: Deleting Files.
+-* removing macros that shadow functions: Macro Definitions.
+-* renaming a file: Renaming Files.
+-* reporting bugs: Reporting Bugs.
+-* reporting errors: Error Reporting.
+-* REPRINT character: Editing Characters.
+-* reserved names: Reserved Names.
+-* resource limits: Limits on Resources.
+-* restarting interrupted primitives: Interrupted Primitives.
+-* restrictions on signal handler functions: Nonreentrancy.
+-* root directory: File Name Resolution.
+-* rounding functions: Rounding and Remainders.
+-* rpc: NSS Basics.
+-* running a command: Running a Command.
+-* scanning the group list: Scanning All Groups.
+-* scanning the user list: Scanning All Users.
+-* search function (for arrays): Array Search Function.
+-* search functions (for strings): Search Functions.
+-* seed (for random numbers): Pseudo-Random Numbers.
+-* seeking on a file descriptor: File Position Primitive.
+-* seeking on a stream: File Positioning.
+-* segmentation violation: Program Error Signals.
+-* sending a datagram: Sending Datagrams.
+-* sending signals: Generating Signals.
+-* sequential-access files: File Position.
+-* server: Connections.
+-* services: NSS Basics.
+-* services database: Services Database.
+-* session <1>: Concepts of Job Control.
+-* session: Job Control.
+-* session leader: Concepts of Job Control.
+-* setting an alarm: Setting an Alarm.
+-* setuid programs: How Change Persona.
+-* setuid programs and file access: Testing File Access.
+-* shadow: NSS Basics.
+-* shadowing functions with macros: Macro Definitions.
+-* shared lock: File Locks.
+-* shell: Concepts of Job Control.
+-* shrinking objects: Growing Objects.
+-* shutting down a socket: Closing a Socket.
+-* sigaction flags: Flags for Sigaction.
+-* sigaction function: Advanced Signal Handling.
+-* SIGCHLD, handling of: Stopped and Terminated Jobs.
+-* sign (of floating point number): Floating Point Concepts.
+-* signal: Signal Handling.
+-* signal action: Delivery of Signal.
+-* signal actions: Signal Actions.
+-* signal flags: Flags for Sigaction.
+-* signal function: Basic Signal Handling.
+-* signal handler function: Defining Handlers.
+-* signal mask: Process Signal Mask.
+-* signal messages: Signal Messages.
+-* signal names: Standard Signals.
+-* signal number: Standard Signals.
+-* signal set: Signal Sets.
+-* signals, generating: Generating Signals.
+-* significand (of floating point number): Floating Point Concepts.
+-* SIGTTIN, from background job: Access to the Terminal.
+-* SIGTTOU, from background job: Access to the Terminal.
+-* size of string: Representation of Strings.
+-* socket: Sockets.
+-* socket address (name) binding: Socket Addresses.
+-* socket domain: Socket Concepts.
+-* socket namespace: Socket Concepts.
+-* socket option level: Socket Options.
+-* socket options: Socket Options.
+-* socket pair: Socket Pairs.
+-* socket protocol: Socket Concepts.
+-* socket shutdown: Closing a Socket.
+-* socket, client actions: Connecting.
+-* socket, closing: Closing a Socket.
+-* socket, connecting: Connecting.
+-* socket, creating: Creating a Socket.
+-* socket, initiating a connection: Connecting.
+-* sockets, accepting connections: Accepting Connections.
+-* sockets, listening: Listening.
+-* sockets, server actions: Listening.
+-* soft limit: Limits on Resources.
+-* soft link: Symbolic Links.
+-* sort function (for arrays): Array Sort Function.
+-* sparse files: File Position Primitive.
+-* special files: Making Special Files.
+-* specified action (for a signal): Delivery of Signal.
+-* square root function: Exponents and Logarithms.
+-* stable sorting: Array Sort Function.
+-* standard dot notation, for Internet addresses: Abstract Host Addresses.
+-* standard environment variables: Standard Environment.
+-* standard error file descriptor: Descriptors and Streams.
+-* standard error stream: Standard Streams.
+-* standard file descriptors: Descriptors and Streams.
+-* standard input file descriptor: Descriptors and Streams.
+-* standard input stream: Standard Streams.
+-* standard output file descriptor: Descriptors and Streams.
+-* standard output stream: Standard Streams.
+-* standard streams: Standard Streams.
+-* standards: Standards and Portability.
+-* START character: Start/Stop Characters.
+-* startup of program: Program Arguments.
+-* static allocation: Memory Concepts.
+-* STATUS character: Other Special.
+-* status codes: Error Reporting.
+-* status of a file: Attribute Meanings.
+-* status of obstack: Status of an Obstack.
+-* sticky bit: Permission Bits.
+-* STOP character: Start/Stop Characters.
+-* stop signal: Job Control Signals.
+-* stopped job: Concepts of Job Control.
+-* stopped jobs, continuing: Continuing Stopped Jobs.
+-* stopped jobs, detecting: Stopped and Terminated Jobs.
+-* storage allocation: Memory Allocation.
+-* stream (sockets): Socket Concepts.
+-* stream, for I/O to a string: String Streams.
+-* streams and descriptors: Stream/Descriptor Precautions.
+-* streams, and file descriptors: Descriptors and Streams.
+-* streams, standard: Standard Streams.
+-* string: Representation of Strings.
+-* string allocation: Representation of Strings.
+-* string collation functions: Collation Functions.
+-* string comparison functions: String/Array Comparison.
+-* string concatenation functions: Copying and Concatenation.
+-* string copy functions: Copying and Concatenation.
+-* string length: Representation of Strings.
+-* string literal: Representation of Strings.
+-* string search functions: Search Functions.
+-* string stream: String Streams.
+-* string, representation of: Representation of Strings.
+-* style of communication (of a socket): Socket Concepts.
+-* subshell: Initializing the Shell.
+-* substitution of variables and commands: Expansion Stages.
+-* successive signals: Merged Signals.
+-* summer time: Broken-down Time.
+-* SunOS: Berkeley Unix.
+-* supplementary group IDs: Process Persona.
+-* SUSP character: Signal Characters.
+-* suspend character: Signal Characters.
+-* SVID: SVID.
+-* symbolic link: Symbolic Links.
+-* symbolic link, opening: Open-time Flags.
+-* syntax, for program arguments: Argument Syntax.
+-* syntax, for reading numbers: Parsing of Numbers.
+-* System V Unix: SVID.
+-* TCP (Internet protocol): Protocols Database.
+-* template, for printf: Formatted Output.
+-* template, for scanf: Formatted Input.
+-* TERM environment variable: Standard Environment.
+-* terminal flow control: Line Control.
+-* terminal identification: Is It a Terminal.
+-* terminal input queue: I/O Queues.
+-* terminal input queue, clearing: Line Control.
+-* terminal input signal: Job Control Signals.
+-* terminal line control functions: Line Control.
+-* terminal line speed: Line Speed.
+-* terminal mode data types: Mode Data Types.
+-* terminal mode functions: Mode Functions.
+-* terminal output queue: I/O Queues.
+-* terminal output queue, flushing: Line Control.
+-* terminal output signal: Job Control Signals.
+-* terminated jobs, detecting: Stopped and Terminated Jobs.
+-* termination signal: Termination Signals.
+-* testing access permission: Testing File Access.
+-* testing exit status of child process: Process Completion.
+-* text stream: Binary Streams.
+-* ticks, clock: Processor Time.
+-* tilde expansion: Expansion Stages.
+-* TIME termios slot: Noncanonical Input.
+-* time zone: TZ Variable.
+-* time zone database: TZ Variable.
+-* time, calendar: Calendar Time.
+-* time, elapsed CPU: Processor Time.
+-* timer, profiling: Setting an Alarm.
+-* timer, real-time: Setting an Alarm.
+-* timer, virtual: Setting an Alarm.
+-* timers, setting: Setting an Alarm.
+-* timing error in signal handling: Remembering a Signal.
+-* TMPDIR environment variable: Temporary Files.
+-* tokenizing strings: Finding Tokens in a String.
+-* tools, for installing library: Tools for Installation.
+-* transmitting datagrams: Sending Datagrams.
+-* trigonometric functions: Trig Functions.
+-* type measurements, floating: Floating Type Macros.
+-* type measurements, integer: Width of Type.
+-* type modifier character (printf): Output Conversion Syntax.
+-* type modifier character (scanf): Input Conversion Syntax.
+-* typeahead buffer: I/O Queues.
+-* TZ environment variable: Standard Environment.
+-* umask: Setting Permissions.
+-* unbuffered stream: Buffering Concepts.
+-* unconstrained storage allocation: Unconstrained Allocation.
+-* undefining macros that shadow functions: Macro Definitions.
+-* Unix, Berkeley: Berkeley Unix.
+-* Unix, System V: SVID.
+-* unlinking a file: Deleting Files.
+-* unreading characters: Unreading.
+-* upper-case character: Classification of Characters.
+-* urgent data signal: Asynchronous I/O Signals.
+-* urgent socket condition: Out-of-Band Data.
+-* usage limits: Limits on Resources.
+-* user database: User Database.
+-* user ID: User and Group IDs.
+-* user ID, determining: Who Logged In.
+-* user name: User and Group IDs.
+-* user signals: Miscellaneous Signals.
+-* usual file name errors: File Name Errors.
+-* variable number of arguments: Variadic Functions.
+-* variable substitution: Expansion Stages.
+-* variable-sized arrays: GNU C Variable-Size Arrays.
+-* variadic function argument access: Receiving Arguments.
+-* variadic function prototypes: Variadic Prototypes.
+-* variadic functions: Variadic Functions.
+-* variadic functions, calling: Calling Variadics.
+-* virtual time alarm signal: Alarm Signals.
+-* virtual timer: Setting an Alarm.
+-* volatile declarations: Nonreentrancy.
+-* waiting for a signal: Waiting for a Signal.
+-* waiting for completion of child process: Process Completion.
+-* waiting for input or output: Waiting for I/O.
+-* warnings of memory almost full: Memory Warnings.
+-* WERASE character: Editing Characters.
+-* whitespace character: Classification of Characters.
+-* wide characters: Extended Char Intro.
+-* width of integer type: Width of Type.
+-* wildcard expansion: Expansion Stages.
+-* word expansion: Word Expansion.
+-* working directory: Working Directory.
+-* write lock: File Locks.
+-* writing to a file descriptor: I/O Primitives.
+-* writing to a socket: Transferring Data.
+-* writing to a stream, by blocks: Block Input/Output.
+-* writing to a stream, by characters: Simple Output.
+-* writing to a stream, formatted: Formatted Output.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-32
glibc-2.0.1/manual/libc.info-32
+--- ../glibc-2.0.1/manual/libc.info-32 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-32 1970-01-01 01:00:00.000000000 +0100
+@@ -1,646 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+- This file documents the GNU C library.
+-
+- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+- Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+- Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+- Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: Type Index, Next: Function Index, Prev: Concept
Index, Up: Top
+-
+-Type Index
+-**********
+-
+-* Menu:
+-
+-* cc_t: Mode Data Types.
+-* clock_t: Basic CPU Time.
+-* comparison_fn_t: Comparison Functions.
+-* cookie_close_function: Hook Functions.
+-* cookie_io_functions_t: Streams and Cookies.
+-* cookie_read_function: Hook Functions.
+-* cookie_seek_function: Hook Functions.
+-* cookie_write_function: Hook Functions.
+-* dev_t: Attribute Meanings.
+-* DIR: Opening a Directory.
+-* div_t: Integer Division.
+-* enum mcheck_status: Heap Consistency Checking.
+-* fd_set: Waiting for I/O.
+-* FILE: Streams.
+-* fpos_t: Portable Positioning.
+-* gid_t: Reading Persona.
+-* glob_t: Calling Glob.
+-* ino_t: Attribute Meanings.
+-* jmp_buf: Non-Local Details.
+-* ldiv_t: Integer Division.
+-* mode_t: Attribute Meanings.
+-* nlink_t: Attribute Meanings.
+-* off_t: File Position Primitive.
+-* pid_t: Process Identification.
+-* printf_arginfo_function: Defining the Output Handler.
+-* printf_function: Defining the Output Handler.
+-* ptrdiff_t: Important Data Types.
+-* regex_t: POSIX Regexp Compilation.
+-* regmatch_t: Regexp Subexpressions.
+-* regoff_t: Regexp Subexpressions.
+-* sig_atomic_t: Atomic Types.
+-* sighandler_t: Basic Signal Handling.
+-* sigjmp_buf: Non-Local Exits and Signals.
+-* sigset_t: Signal Sets.
+-* size_t: Important Data Types.
+-* speed_t: Line Speed.
+-* ssize_t: I/O Primitives.
+-* struct dirent: Directory Entries.
+-* struct flock: File Locks.
+-* struct group: Group Data Structure.
+-* struct hostent: Host Names.
+-* struct in_addr: Host Address Data Type.
+-* struct itimerval: Setting an Alarm.
+-* struct lconv: Numeric Formatting.
+-* struct linger: Socket-Level Options.
+-* struct mstats: Statistics of Malloc.
+-* struct netent: Networks Database.
+-* struct obstack: Creating Obstacks.
+-* struct option: Long Options.
+-* struct passwd: User Data Structure.
+-* struct printf_info: Conversion Specifier Options.
+-* struct protoent: Protocols Database.
+-* struct rlimit: Limits on Resources.
+-* struct rusage: Resource Usage.
+-* struct servent: Services Database.
+-* struct sigaction: Advanced Signal Handling.
+-* struct sigaltstack: Signal Stack.
+-* struct sigstack: Signal Stack.
+-* struct sigvec: BSD Handler.
+-* struct sockaddr: Address Formats.
+-* struct sockaddr_in: Internet Address Format.
+-* struct sockaddr_un: File Namespace Details.
+-* struct stat: Attribute Meanings.
+-* struct termios: Mode Data Types.
+-* struct timeval: High-Resolution Calendar.
+-* struct timezone: High-Resolution Calendar.
+-* struct tm: Broken-down Time.
+-* struct tms: Detailed CPU Time.
+-* struct utimbuf: File Times.
+-* struct utsname: Hardware/Software Type ID.
+-* tcflag_t: Mode Data Types.
+-* time_t: Simple Calendar Time.
+-* uid_t: Reading Persona.
+-* union wait: BSD Wait Functions.
+-* va_list: Argument Macros.
+-* wchar_t: Wide Char Intro.
+-* wordexp_t: Calling Wordexp.
+-
+-
+-File: libc.info, Node: Function Index, Next: Variable Index, Prev: Type
Index, Up: Top
+-
+-Function and Macro Index
+-************************
+-
+-* Menu:
+-
+-* _exit: Termination Internals.
+-* _tolower: Case Conversion.
+-* _toupper: Case Conversion.
+-* abort: Aborting a Program.
+-* abs: Absolute Value.
+-* accept: Accepting Connections.
+-* access: Testing File Access.
+-* acos: Inverse Trig Functions.
+-* acosh: Hyperbolic Functions.
+-* adjtime: High-Resolution Calendar.
+-* alarm: Setting an Alarm.
+-* alloca: Variable Size Automatic.
+-* asctime: Formatting Date and Time.
+-* asin: Inverse Trig Functions.
+-* asinh: Hyperbolic Functions.
+-* asprintf: Dynamic Output.
+-* assert: Consistency Checking.
+-* assert_perror: Consistency Checking.
+-* atan: Inverse Trig Functions.
+-* atan2: Inverse Trig Functions.
+-* atanh: Hyperbolic Functions.
+-* atexit: Cleanups on Exit.
+-* atof: Parsing of Floats.
+-* atoi: Parsing of Integers.
+-* atol: Parsing of Integers.
+-* bcmp: String/Array Comparison.
+-* bcopy: Copying and Concatenation.
+-* bind: Setting Address.
+-* bsearch: Array Search Function.
+-* bzero: Copying and Concatenation.
+-* cabs: Absolute Value.
+-* calloc: Allocating Cleared Space.
+-* cbrt: Exponents and Logarithms.
+-* ceil: Rounding and Remainders.
+-* cfgetispeed: Line Speed.
+-* cfgetospeed: Line Speed.
+-* cfmakeraw: Noncanonical Input.
+-* cfree: Freeing after Malloc.
+-* cfsetispeed: Line Speed.
+-* cfsetospeed: Line Speed.
+-* cfsetspeed: Line Speed.
+-* chdir: Working Directory.
+-* chmod: Setting Permissions.
+-* chown: File Owner.
+-* clearerr: EOF and Errors.
+-* clock: Basic CPU Time.
+-* close: Opening and Closing Files.
+-* closedir: Reading/Closing Directory.
+-* confstr: String Parameters.
+-* connect: Connecting.
+-* copysign: Normalization Functions.
+-* cos: Trig Functions.
+-* cosh: Hyperbolic Functions.
+-* creat: Opening and Closing Files.
+-* ctermid: Identifying the Terminal.
+-* ctime: Formatting Date and Time.
+-* cuserid: Who Logged In.
+-* difftime: Simple Calendar Time.
+-* div: Integer Division.
+-* drem: Rounding and Remainders.
+-* DTTOIF: Directory Entries.
+-* dup: Duplicating Descriptors.
+-* dup2: Duplicating Descriptors.
+-* endgrent: Scanning All Groups.
+-* endhostent: Host Names.
+-* endnetent: Networks Database.
+-* endnetgrent: Lookup Netgroup.
+-* endprotoent: Protocols Database.
+-* endpwent: Scanning All Users.
+-* endservent: Services Database.
+-* execl: Executing a File.
+-* execle: Executing a File.
+-* execlp: Executing a File.
+-* execv: Executing a File.
+-* execve: Executing a File.
+-* execvp: Executing a File.
+-* exit: Normal Termination.
+-* exp: Exponents and Logarithms.
+-* expm1: Exponents and Logarithms.
+-* fabs: Absolute Value.
+-* fchmod: Setting Permissions.
+-* fchown: File Owner.
+-* fclean: Cleaning Streams.
+-* fclose: Closing Streams.
+-* fcloseall: Closing Streams.
+-* fcntl: Control Operations.
+-* FD_CLR: Waiting for I/O.
+-* FD_ISSET: Waiting for I/O.
+-* FD_SET: Waiting for I/O.
+-* FD_ZERO: Waiting for I/O.
+-* fdopen: Descriptors and Streams.
+-* feof: EOF and Errors.
+-* ferror: EOF and Errors.
+-* fflush: Flushing Buffers.
+-* fgetc: Character Input.
+-* fgetgrent: Scanning All Groups.
+-* fgetgrent_r: Scanning All Groups.
+-* fgetpos: Portable Positioning.
+-* fgetpwent: Scanning All Users.
+-* fgetpwent_r: Scanning All Users.
+-* fgets: Line Input.
+-* fileno: Descriptors and Streams.
+-* finite: Predicates on Floats.
+-* floor: Rounding and Remainders.
+-* fmemopen: String Streams.
+-* fmod: Rounding and Remainders.
+-* fnmatch: Wildcard Matching.
+-* fopen: Opening Streams.
+-* fopencookie: Streams and Cookies.
+-* fork: Creating a Process.
+-* fpathconf: Pathconf.
+-* fprintf: Formatted Output Functions.
+-* fputc: Simple Output.
+-* fputs: Simple Output.
+-* fread: Block Input/Output.
+-* free: Freeing after Malloc.
+-* freopen: Opening Streams.
+-* frexp: Normalization Functions.
+-* fscanf: Formatted Input Functions.
+-* fseek: File Positioning.
+-* fsetpos: Portable Positioning.
+-* fstat: Reading Attributes.
+-* ftell: File Positioning.
+-* fwrite: Block Input/Output.
+-* getc: Character Input.
+-* getchar: Character Input.
+-* getcwd: Working Directory.
+-* getdelim: Line Input.
+-* getegid: Reading Persona.
+-* getenv: Environment Access.
+-* geteuid: Reading Persona.
+-* getgid: Reading Persona.
+-* getgrent: Scanning All Groups.
+-* getgrent_r: Scanning All Groups.
+-* getgrgid: Lookup Group.
+-* getgrgid_r: Lookup Group.
+-* getgrnam: Lookup Group.
+-* getgrnam_r: Lookup Group.
+-* getgroups: Reading Persona.
+-* gethostbyaddr: Host Names.
+-* gethostbyname: Host Names.
+-* gethostent: Host Names.
+-* gethostid: Host Identification.
+-* gethostname: Host Identification.
+-* getitimer: Setting an Alarm.
+-* getline: Line Input.
+-* getlogin: Who Logged In.
+-* getnetbyaddr: Networks Database.
+-* getnetbyname: Networks Database.
+-* getnetent: Networks Database.
+-* getnetgrent: Lookup Netgroup.
+-* getnetgrent_r: Lookup Netgroup.
+-* getopt: Parsing Options.
+-* getopt_long: Long Options.
+-* getpeername: Who is Connected.
+-* getpgrp: Process Group Functions.
+-* getpid: Process Identification.
+-* getppid: Process Identification.
+-* getpriority: Priority.
+-* getprotobyname: Protocols Database.
+-* getprotobynumber: Protocols Database.
+-* getprotoent: Protocols Database.
+-* getpwent: Scanning All Users.
+-* getpwent_r: Scanning All Users.
+-* getpwnam: Lookup User.
+-* getpwnam_r: Lookup User.
+-* getpwuid: Lookup User.
+-* getpwuid_r: Lookup User.
+-* getrlimit: Limits on Resources.
+-* getrusage: Resource Usage.
+-* gets: Line Input.
+-* getservbyname: Services Database.
+-* getservbyport: Services Database.
+-* getservent: Services Database.
+-* getsockname: Reading Address.
+-* getsockopt: Socket Option Functions.
+-* getsubopt: Suboptions.
+-* gettimeofday: High-Resolution Calendar.
+-* getuid: Reading Persona.
+-* getumask: Setting Permissions.
+-* getw: Character Input.
+-* getwd: Working Directory.
+-* glob: Calling Glob.
+-* gmtime: Broken-down Time.
+-* gsignal: Signaling Yourself.
+-* htonl: Byte Order.
+-* htons: Byte Order.
+-* hypot: Exponents and Logarithms.
+-* IFTODT: Directory Entries.
+-* index: Search Functions.
+-* inet_addr: Host Address Functions.
+-* inet_aton: Host Address Functions.
+-* inet_lnaof: Host Address Functions.
+-* inet_makeaddr: Host Address Functions.
+-* inet_netof: Host Address Functions.
+-* inet_network: Host Address Functions.
+-* inet_ntoa: Host Address Functions.
+-* infnan: Predicates on Floats.
+-* initgroups: Setting Groups.
+-* initstate: BSD Random.
+-* innetgr: Netgroup Membership.
+-* isalnum: Classification of Characters.
+-* isalpha: Classification of Characters.
+-* isascii: Classification of Characters.
+-* isatty: Is It a Terminal.
+-* isblank: Classification of Characters.
+-* iscntrl: Classification of Characters.
+-* isdigit: Classification of Characters.
+-* isgraph: Classification of Characters.
+-* isinf: Predicates on Floats.
+-* islower: Classification of Characters.
+-* isnan: Predicates on Floats.
+-* isprint: Classification of Characters.
+-* ispunct: Classification of Characters.
+-* isspace: Classification of Characters.
+-* isupper: Classification of Characters.
+-* isxdigit: Classification of Characters.
+-* ITIMER_PROF: Setting an Alarm.
+-* ITIMER_REAL: Setting an Alarm.
+-* ITIMER_VIRTUAL: Setting an Alarm.
+-* kill: Signaling Another Process.
+-* killpg: Signaling Another Process.
+-* labs: Absolute Value.
+-* ldexp: Normalization Functions.
+-* ldiv: Integer Division.
+-* link: Hard Links.
+-* listen: Listening.
+-* localeconv: Numeric Formatting.
+-* localtime: Broken-down Time.
+-* log: Exponents and Logarithms.
+-* log10: Exponents and Logarithms.
+-* log1p: Exponents and Logarithms.
+-* logb: Normalization Functions.
+-* longjmp: Non-Local Details.
+-* lseek: File Position Primitive.
+-* lstat: Reading Attributes.
+-* main: Program Arguments.
+-* malloc: Basic Allocation.
+-* mblen: Length of Char.
+-* mbstowcs: Wide String Conversion.
+-* mbtowc: Converting One Char.
+-* mcheck: Heap Consistency Checking.
+-* memalign: Aligned Memory Blocks.
+-* memccpy: Copying and Concatenation.
+-* memchr: Search Functions.
+-* memcmp: String/Array Comparison.
+-* memcpy: Copying and Concatenation.
+-* memmem: Search Functions.
+-* memmove: Copying and Concatenation.
+-* memory_warnings: Memory Warnings.
+-* memset: Copying and Concatenation.
+-* mkdir: Creating Directories.
+-* mkfifo: FIFO Special Files.
+-* mknod: Making Special Files.
+-* mkstemp: Temporary Files.
+-* mktemp: Temporary Files.
+-* mktime: Broken-down Time.
+-* modf: Rounding and Remainders.
+-* mprobe: Heap Consistency Checking.
+-* mstats: Statistics of Malloc.
+-* nice: Priority.
+-* notfound: Actions in the NSS configuration.
+-* NSS_STATUS_NOTFOUND: NSS Modules Interface.
+-* NSS_STATUS_SUCCESS: NSS Modules Interface.
+-* NSS_STATUS_TRYAGAIN: NSS Modules Interface.
+-* NSS_STATUS_UNAVAIL: NSS Modules Interface.
+-* ntohl: Byte Order.
+-* ntohs: Byte Order.
+-* obstack_1grow: Growing Objects.
+-* obstack_1grow_fast: Extra Fast Growing.
+-* obstack_alignment_mask: Obstacks Data Alignment.
+-* obstack_alloc: Allocation in an Obstack.
+-* obstack_base: Status of an Obstack.
+-* obstack_blank: Growing Objects.
+-* obstack_blank_fast: Extra Fast Growing.
+-* obstack_chunk_alloc: Preparing for Obstacks.
+-* obstack_chunk_free: Preparing for Obstacks.
+-* obstack_chunk_size: Obstack Chunks.
+-* obstack_copy: Allocation in an Obstack.
+-* obstack_copy0: Allocation in an Obstack.
+-* obstack_finish: Growing Objects.
+-* obstack_free: Freeing Obstack Objects.
+-* obstack_grow: Growing Objects.
+-* obstack_grow0: Growing Objects.
+-* obstack_init: Preparing for Obstacks.
+-* obstack_int_grow: Growing Objects.
+-* obstack_int_grow_fast: Extra Fast Growing.
+-* obstack_next_free: Status of an Obstack.
+-* obstack_object_size <1>: Status of an Obstack.
+-* obstack_object_size: Growing Objects.
+-* obstack_printf: Dynamic Output.
+-* obstack_ptr_grow: Growing Objects.
+-* obstack_ptr_grow_fast: Extra Fast Growing.
+-* obstack_room: Extra Fast Growing.
+-* obstack_vprintf: Variable Arguments Output.
+-* offsetof: Structure Measurement.
+-* on_exit: Cleanups on Exit.
+-* open: Opening and Closing Files.
+-* open_memstream: String Streams.
+-* open_obstack_stream: Obstack Streams.
+-* opendir: Opening a Directory.
+-* parse_printf_format: Parsing a Template String.
+-* pathconf: Pathconf.
+-* pause: Using Pause.
+-* pclose: Pipe to a Subprocess.
+-* perror: Error Messages.
+-* pipe: Creating a Pipe.
+-* popen: Pipe to a Subprocess.
+-* pow: Exponents and Logarithms.
+-* printf: Formatted Output Functions.
+-* psignal: Signal Messages.
+-* putc: Simple Output.
+-* putchar: Simple Output.
+-* putenv: Environment Access.
+-* putpwent: Writing a User Entry.
+-* puts: Simple Output.
+-* putw: Simple Output.
+-* qsort: Array Sort Function.
+-* r_alloc: Using Relocator.
+-* r_alloc_free: Using Relocator.
+-* r_re_alloc: Using Relocator.
+-* raise: Signaling Yourself.
+-* rand: ISO Random.
+-* random: BSD Random.
+-* read: I/O Primitives.
+-* readdir: Reading/Closing Directory.
+-* readdir_r: Reading/Closing Directory.
+-* readlink: Symbolic Links.
+-* realloc: Changing Block Size.
+-* recv: Receiving Data.
+-* recvfrom: Receiving Datagrams.
+-* regcomp: POSIX Regexp Compilation.
+-* regerror: Regexp Cleanup.
+-* regexec: Matching POSIX Regexps.
+-* regfree: Regexp Cleanup.
+-* register_printf_function: Registering New Conversions.
+-* remove: Deleting Files.
+-* rename: Renaming Files.
+-* rewind: File Positioning.
+-* rewinddir: Random Access Directory.
+-* rindex: Search Functions.
+-* rint: Rounding and Remainders.
+-* rmdir: Deleting Files.
+-* S_ISBLK: Testing File Type.
+-* S_ISCHR: Testing File Type.
+-* S_ISDIR: Testing File Type.
+-* S_ISFIFO: Testing File Type.
+-* S_ISLNK: Testing File Type.
+-* S_ISREG: Testing File Type.
+-* S_ISSOCK: Testing File Type.
+-* scalb: Normalization Functions.
+-* scanf: Formatted Input Functions.
+-* seekdir: Random Access Directory.
+-* select: Waiting for I/O.
+-* send: Sending Data.
+-* sendto: Sending Datagrams.
+-* setbuf: Controlling Buffering.
+-* setbuffer: Controlling Buffering.
+-* setgid: Setting Groups.
+-* setgrent: Scanning All Groups.
+-* setgroups: Setting Groups.
+-* sethostent: Host Names.
+-* sethostid: Host Identification.
+-* sethostname: Host Identification.
+-* setitimer: Setting an Alarm.
+-* setjmp: Non-Local Details.
+-* setlinebuf: Controlling Buffering.
+-* setlocale: Setting the Locale.
+-* setnetent: Networks Database.
+-* setnetgrent: Lookup Netgroup.
+-* setpgid: Process Group Functions.
+-* setpgrp: Process Group Functions.
+-* setpriority: Priority.
+-* setprotoent: Protocols Database.
+-* setpwent: Scanning All Users.
+-* setregid: Setting Groups.
+-* setreuid: Setting User ID.
+-* setrlimit: Limits on Resources.
+-* setservent: Services Database.
+-* setsid: Process Group Functions.
+-* setsockopt: Socket Option Functions.
+-* setstate: BSD Random.
+-* settimeofday: High-Resolution Calendar.
+-* setuid: Setting User ID.
+-* setvbuf: Controlling Buffering.
+-* shutdown: Closing a Socket.
+-* sigaction: Advanced Signal Handling.
+-* sigaddset: Signal Sets.
+-* sigaltstack: Signal Stack.
+-* sigblock: Blocking in BSD.
+-* sigdelset: Signal Sets.
+-* sigemptyset: Signal Sets.
+-* sigfillset: Signal Sets.
+-* siginterrupt: BSD Handler.
+-* sigismember: Signal Sets.
+-* siglongjmp: Non-Local Exits and Signals.
+-* sigmask: Blocking in BSD.
+-* signal: Basic Signal Handling.
+-* sigpause: Blocking in BSD.
+-* sigpending: Checking for Pending Signals.
+-* sigprocmask: Process Signal Mask.
+-* sigsetjmp: Non-Local Exits and Signals.
+-* sigsetmask: Blocking in BSD.
+-* sigstack: Signal Stack.
+-* sigsuspend: Sigsuspend.
+-* sigvec: BSD Handler.
+-* sin: Trig Functions.
+-* sinh: Hyperbolic Functions.
+-* sleep: Sleeping.
+-* snprintf: Formatted Output Functions.
+-* socket: Creating a Socket.
+-* socketpair: Socket Pairs.
+-* sprintf: Formatted Output Functions.
+-* sqrt: Exponents and Logarithms.
+-* srand: ISO Random.
+-* srandom: BSD Random.
+-* sscanf: Formatted Input Functions.
+-* ssignal: Basic Signal Handling.
+-* stat: Reading Attributes.
+-* stpcpy: Copying and Concatenation.
+-* stpncpy: Copying and Concatenation.
+-* strcasecmp: String/Array Comparison.
+-* strcat: Copying and Concatenation.
+-* strchr: Search Functions.
+-* strcmp: String/Array Comparison.
+-* strcoll: Collation Functions.
+-* strcpy: Copying and Concatenation.
+-* strcspn: Search Functions.
+-* strdup: Copying and Concatenation.
+-* strdupa: Copying and Concatenation.
+-* strerror: Error Messages.
+-* strftime: Formatting Date and Time.
+-* strlen: String Length.
+-* strncasecmp: String/Array Comparison.
+-* strncat: Copying and Concatenation.
+-* strncmp: String/Array Comparison.
+-* strncpy: Copying and Concatenation.
+-* strndup: Copying and Concatenation.
+-* strndupa: Copying and Concatenation.
+-* strpbrk: Search Functions.
+-* strrchr: Search Functions.
+-* strsep: Finding Tokens in a String.
+-* strsignal: Signal Messages.
+-* strspn: Search Functions.
+-* strstr: Search Functions.
+-* strtod: Parsing of Floats.
+-* strtof: Parsing of Floats.
+-* strtok: Finding Tokens in a String.
+-* strtok_r: Finding Tokens in a String.
+-* strtol: Parsing of Integers.
+-* strtold: Parsing of Floats.
+-* strtoll: Parsing of Integers.
+-* strtoq: Parsing of Integers.
+-* strtoul: Parsing of Integers.
+-* strtoull: Parsing of Integers.
+-* strtouq: Parsing of Integers.
+-* strxfrm: Collation Functions.
+-* success: Actions in the NSS configuration.
+-* symlink: Symbolic Links.
+-* sysconf: Sysconf Definition.
+-* system: Running a Command.
+-* tan: Trig Functions.
+-* tanh: Hyperbolic Functions.
+-* tcdrain: Line Control.
+-* tcflow: Line Control.
+-* tcflush: Line Control.
+-* tcgetattr: Mode Functions.
+-* tcgetpgrp: Terminal Access Functions.
+-* tcsendbreak: Line Control.
+-* tcsetattr: Mode Functions.
+-* tcsetpgrp: Terminal Access Functions.
+-* telldir: Random Access Directory.
+-* TEMP_FAILURE_RETRY: Interrupted Primitives.
+-* tempnam: Temporary Files.
+-* time: Simple Calendar Time.
+-* times: Detailed CPU Time.
+-* tmpfile: Temporary Files.
+-* tmpnam: Temporary Files.
+-* tmpnam_r: Temporary Files.
+-* toascii: Case Conversion.
+-* tolower: Case Conversion.
+-* toupper: Case Conversion.
+-* tryagain: Actions in the NSS configuration.
+-* ttyname: Is It a Terminal.
+-* tzset: Time Zone Functions.
+-* umask: Setting Permissions.
+-* uname: Hardware/Software Type ID.
+-* unavail: Actions in the NSS configuration.
+-* ungetc: How Unread.
+-* unlink: Deleting Files.
+-* utime: File Times.
+-* utimes: File Times.
+-* va_alist: Old Varargs.
+-* va_arg: Argument Macros.
+-* va_dcl: Old Varargs.
+-* va_end: Argument Macros.
+-* va_start <1>: Old Varargs.
+-* va_start: Argument Macros.
+-* valloc: Aligned Memory Blocks.
+-* vasprintf: Variable Arguments Output.
+-* vfork: Creating a Process.
+-* vfprintf: Variable Arguments Output.
+-* vfscanf: Variable Arguments Input.
+-* vprintf: Variable Arguments Output.
+-* vscanf: Variable Arguments Input.
+-* vsnprintf: Variable Arguments Output.
+-* vsprintf: Variable Arguments Output.
+-* vsscanf: Variable Arguments Input.
+-* wait: Process Completion.
+-* wait3: BSD Wait Functions.
+-* wait4: Process Completion.
+-* waitpid: Process Completion.
+-* WCOREDUMP: Process Completion Status.
+-* wcstombs: Wide String Conversion.
+-* wctomb: Converting One Char.
+-* WEXITSTATUS: Process Completion Status.
+-* WIFEXITED: Process Completion Status.
+-* WIFSIGNALED: Process Completion Status.
+-* WIFSTOPPED: Process Completion Status.
+-* wordexp: Calling Wordexp.
+-* wordfree: Calling Wordexp.
+-* write: I/O Primitives.
+-* WSTOPSIG: Process Completion Status.
+-* WTERMSIG: Process Completion Status.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-33
glibc-2.0.1/manual/libc.info-33
+--- ../glibc-2.0.1/manual/libc.info-33 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-33 1970-01-01 01:00:00.000000000 +0100
+@@ -1,816 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+- This file documents the GNU C library.
+-
+- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+- Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+- Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+- Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: Variable Index, Next: File Index, Prev: Function
Index, Up: Top
+-
+-Variable and Constant Macro Index
+-*********************************
+-
+-* Menu:
+-
+-* __free_hook: Hooks for Malloc.
+-* __malloc_hook: Hooks for Malloc.
+-* __realloc_hook: Hooks for Malloc.
+-* _BSD_SOURCE: Feature Test Macros.
+-* _GNU_SOURCE: Feature Test Macros.
+-* _IOFBF: Controlling Buffering.
+-* _IOLBF: Controlling Buffering.
+-* _IONBF: Controlling Buffering.
+-* _POSIX2_C_DEV: System Options.
+-* _POSIX2_C_VERSION: Version Supported.
+-* _POSIX2_FORT_DEV: System Options.
+-* _POSIX2_FORT_RUN: System Options.
+-* _POSIX2_LOCALEDEF: System Options.
+-* _POSIX2_SW_DEV: System Options.
+-* _POSIX_C_SOURCE: Feature Test Macros.
+-* _POSIX_CHOWN_RESTRICTED: Options for Files.
+-* _POSIX_JOB_CONTROL: System Options.
+-* _POSIX_NO_TRUNC: Options for Files.
+-* _POSIX_SAVED_IDS: System Options.
+-* _POSIX_SOURCE: Feature Test Macros.
+-* _POSIX_VDISABLE <1>: Options for Files.
+-* _POSIX_VDISABLE: Special Characters.
+-* _POSIX_VERSION: Version Supported.
+-* _REENTRANT: Feature Test Macros.
+-* _SVID_SOURCE: Feature Test Macros.
+-* _THREAD_SAFE: Feature Test Macros.
+-* _XOPEN_SOURCE: Feature Test Macros.
+-* AF_FILE: Address Formats.
+-* AF_INET: Address Formats.
+-* AF_UNIX: Address Formats.
+-* AF_UNSPEC: Address Formats.
+-* ALTWERASE: Local Modes.
+-* ARG_MAX: General Limits.
+-* B0: Line Speed.
+-* B110: Line Speed.
+-* B1200: Line Speed.
+-* B134: Line Speed.
+-* B150: Line Speed.
+-* B1800: Line Speed.
+-* B19200: Line Speed.
+-* B200: Line Speed.
+-* B2400: Line Speed.
+-* B300: Line Speed.
+-* B38400: Line Speed.
+-* B4800: Line Speed.
+-* B50: Line Speed.
+-* B600: Line Speed.
+-* B75: Line Speed.
+-* B9600: Line Speed.
+-* BC_BASE_MAX: Utility Limits.
+-* BC_DIM_MAX: Utility Limits.
+-* BC_SCALE_MAX: Utility Limits.
+-* BC_STRING_MAX: Utility Limits.
+-* BRKINT: Input Modes.
+-* BUFSIZ: Controlling Buffering.
+-* CCTS_OFLOW: Control Modes.
+-* CHILD_MAX: General Limits.
+-* CIGNORE: Control Modes.
+-* CLK_TCK: Basic CPU Time.
+-* CLOCAL: Control Modes.
+-* CLOCKS_PER_SEC: Basic CPU Time.
+-* COLL_WEIGHTS_MAX: Utility Limits.
+-* COREFILE: Program Error Signals.
+-* CREAD: Control Modes.
+-* CRTS_IFLOW: Control Modes.
+-* CS5: Control Modes.
+-* CS6: Control Modes.
+-* CS7: Control Modes.
+-* CS8: Control Modes.
+-* CSIZE: Control Modes.
+-* CSTOPB: Control Modes.
+-* daylight: Time Zone Functions.
+-* E2BIG: Error Codes.
+-* EACCES: Error Codes.
+-* EADDRINUSE: Error Codes.
+-* EADDRNOTAVAIL: Error Codes.
+-* EADV: Error Codes.
+-* EAFNOSUPPORT: Error Codes.
+-* EAGAIN: Error Codes.
+-* EALREADY: Error Codes.
+-* EAUTH: Error Codes.
+-* EBACKGROUND: Error Codes.
+-* EBADE: Error Codes.
+-* EBADF <1>: Line Control.
+-* EBADF: Error Codes.
+-* EBADFD: Error Codes.
+-* EBADMSG: Error Codes.
+-* EBADR: Error Codes.
+-* EBADRPC: Error Codes.
+-* EBADRQC: Error Codes.
+-* EBADSLT: Error Codes.
+-* EBFONT: Error Codes.
+-* EBUSY: Error Codes.
+-* ECHILD: Error Codes.
+-* ECHO: Local Modes.
+-* ECHOCTL: Local Modes.
+-* ECHOE: Local Modes.
+-* ECHOK: Local Modes.
+-* ECHOKE: Local Modes.
+-* ECHONL: Local Modes.
+-* ECHOPRT: Local Modes.
+-* ECHRNG: Error Codes.
+-* ECOMM: Error Codes.
+-* ECONNABORTED: Error Codes.
+-* ECONNREFUSED: Error Codes.
+-* ECONNRESET: Error Codes.
+-* ED: Error Codes.
+-* EDEADLK: Error Codes.
+-* EDEADLOCK: Error Codes.
+-* EDESTADDRREQ: Error Codes.
+-* EDIED: Error Codes.
+-* EDOM: Error Codes.
+-* EDOTDOT: Error Codes.
+-* EDQUOT: Error Codes.
+-* EEXIST: Error Codes.
+-* EFAULT: Error Codes.
+-* EFBIG: Error Codes.
+-* EFTYPE: Error Codes.
+-* EGRATUITOUS: Error Codes.
+-* EGREGIOUS: Error Codes.
+-* EHOSTDOWN: Error Codes.
+-* EHOSTUNREACH: Error Codes.
+-* EIDRM: Error Codes.
+-* EIEIO: Error Codes.
+-* EILSEQ: Error Codes.
+-* EINPROGRESS: Error Codes.
+-* EINTR: Error Codes.
+-* EINVAL <1>: Line Control.
+-* EINVAL: Error Codes.
+-* EIO: Error Codes.
+-* EISCONN: Error Codes.
+-* EISDIR: Error Codes.
+-* EISNAM: Error Codes.
+-* EL2HLT: Error Codes.
+-* EL2NSYNC: Error Codes.
+-* EL3HLT: Error Codes.
+-* EL3RST: Error Codes.
+-* ELIBACC: Error Codes.
+-* ELIBBAD: Error Codes.
+-* ELIBEXEC: Error Codes.
+-* ELIBMAX: Error Codes.
+-* ELIBSCN: Error Codes.
+-* ELNRNG: Error Codes.
+-* ELOOP: Error Codes.
+-* EMFILE: Error Codes.
+-* EMLINK: Error Codes.
+-* EMSGSIZE: Error Codes.
+-* EMULTIHOP: Error Codes.
+-* ENAMETOOLONG: Error Codes.
+-* ENAVAIL: Error Codes.
+-* ENEEDAUTH: Error Codes.
+-* ENETDOWN: Error Codes.
+-* ENETRESET: Error Codes.
+-* ENETUNREACH: Error Codes.
+-* ENFILE: Error Codes.
+-* ENOANO: Error Codes.
+-* ENOBUFS: Error Codes.
+-* ENOCSI: Error Codes.
+-* ENODATA: Error Codes.
+-* ENODEV: Error Codes.
+-* ENOENT: Error Codes.
+-* ENOEXEC: Error Codes.
+-* ENOLCK: Error Codes.
+-* ENOLINK: Error Codes.
+-* ENOMEM: Error Codes.
+-* ENOMSG: Error Codes.
+-* ENONET: Error Codes.
+-* ENOPKG: Error Codes.
+-* ENOPROTOOPT: Error Codes.
+-* ENOSPC: Error Codes.
+-* ENOSR: Error Codes.
+-* ENOSTR: Error Codes.
+-* ENOSYS: Error Codes.
+-* ENOTBLK: Error Codes.
+-* ENOTCONN: Error Codes.
+-* ENOTDIR: Error Codes.
+-* ENOTEMPTY: Error Codes.
+-* ENOTNAM: Error Codes.
+-* ENOTSOCK: Error Codes.
+-* ENOTTY <1>: Line Control.
+-* ENOTTY: Error Codes.
+-* ENOTUNIQ: Error Codes.
+-* environ: Environment Access.
+-* ENXIO: Error Codes.
+-* EOF: EOF and Errors.
+-* EOPNOTSUPP: Error Codes.
+-* EOVERFLOW: Error Codes.
+-* EPERM: Error Codes.
+-* EPFNOSUPPORT: Error Codes.
+-* EPIPE: Error Codes.
+-* EPROCLIM: Error Codes.
+-* EPROCUNAVAIL: Error Codes.
+-* EPROGMISMATCH: Error Codes.
+-* EPROGUNAVAIL: Error Codes.
+-* EPROTO: Error Codes.
+-* EPROTONOSUPPORT: Error Codes.
+-* EPROTOTYPE: Error Codes.
+-* EQUIV_CLASS_MAX: Utility Limits.
+-* ERANGE: Error Codes.
+-* EREMCHG: Error Codes.
+-* EREMOTE: Error Codes.
+-* EREMOTEIO: Error Codes.
+-* ERESTART: Error Codes.
+-* EROFS: Error Codes.
+-* ERPCMISMATCH: Error Codes.
+-* errno: Checking for Errors.
+-* ESHUTDOWN: Error Codes.
+-* ESOCKTNOSUPPORT: Error Codes.
+-* ESPIPE: Error Codes.
+-* ESRCH: Error Codes.
+-* ESRMNT: Error Codes.
+-* ESTALE: Error Codes.
+-* ESTRPIPE: Error Codes.
+-* ethers: NSS Basics.
+-* ETIME: Error Codes.
+-* ETIMEDOUT: Error Codes.
+-* ETOOMANYREFS: Error Codes.
+-* ETXTBSY: Error Codes.
+-* EUCLEAN: Error Codes.
+-* EUNATCH: Error Codes.
+-* EUSERS: Error Codes.
+-* EWOULDBLOCK: Error Codes.
+-* EXDEV: Error Codes.
+-* EXFULL: Error Codes.
+-* EXIT_FAILURE: Exit Status.
+-* EXIT_SUCCESS: Exit Status.
+-* EXPR_NEST_MAX: Utility Limits.
+-* EXTA: Line Speed.
+-* EXTB: Line Speed.
+-* F_DUPFD: Duplicating Descriptors.
+-* F_GETFD: Descriptor Flags.
+-* F_GETFL: Getting File Status Flags.
+-* F_GETLK: File Locks.
+-* F_GETOWN: Interrupt Input.
+-* F_OK: Testing File Access.
+-* F_RDLCK: File Locks.
+-* F_SETFD: Descriptor Flags.
+-* F_SETFL: Getting File Status Flags.
+-* F_SETLK: File Locks.
+-* F_SETLKW: File Locks.
+-* F_SETOWN: Interrupt Input.
+-* F_UNLCK: File Locks.
+-* F_WRLCK: File Locks.
+-* FD_CLOEXEC: Descriptor Flags.
+-* FD_SETSIZE: Waiting for I/O.
+-* FILENAME_MAX: Limits for Files.
+-* FLUSHO: Local Modes.
+-* FOPEN_MAX: Opening Streams.
+-* FPE_DECOVF_TRAP: Program Error Signals.
+-* FPE_FLTDIV_TRAP: Program Error Signals.
+-* FPE_FLTOVF_TRAP: Program Error Signals.
+-* FPE_FLTUND_TRAP: Program Error Signals.
+-* FPE_INTDIV_TRAP: Program Error Signals.
+-* FPE_INTOVF_TRAP: Program Error Signals.
+-* FPE_SUBRNG_TRAP: Program Error Signals.
+-* group: NSS Basics.
+-* h_errno: Host Names.
+-* HOST_NOT_FOUND: Host Names.
+-* hosts: NSS Basics.
+-* HUGE_VAL: Domain and Range Errors.
+-* HUGE_VALf: Domain and Range Errors.
+-* HUGE_VALl: Domain and Range Errors.
+-* HUPCL: Control Modes.
+-* ICANON: Local Modes.
+-* ICRNL: Input Modes.
+-* IEXTEN: Local Modes.
+-* IGNBRK: Input Modes.
+-* IGNCR: Input Modes.
+-* IGNPAR: Input Modes.
+-* IMAXBEL: Input Modes.
+-* INADDR_ANY: Host Address Data Type.
+-* INADDR_BROADCAST: Host Address Data Type.
+-* INADDR_LOOPBACK: Host Address Data Type.
+-* INADDR_NONE: Host Address Data Type.
+-* INLCR: Input Modes.
+-* INPCK: Input Modes.
+-* int: Limits on Resources.
+-* IPPORT_RESERVED: Ports.
+-* IPPORT_USERRESERVED: Ports.
+-* ISIG: Local Modes.
+-* ISTRIP: Input Modes.
+-* IXANY: Input Modes.
+-* IXOFF: Input Modes.
+-* IXON: Input Modes.
+-* L_ctermid: Identifying the Terminal.
+-* L_cuserid: Who Logged In.
+-* L_INCR: File Positioning.
+-* L_SET: File Positioning.
+-* L_tmpnam: Temporary Files.
+-* L_XTND: File Positioning.
+-* LANG: Locale Categories.
+-* LC_ALL: Locale Categories.
+-* LC_COLLATE: Locale Categories.
+-* LC_CTYPE: Locale Categories.
+-* LC_MESSAGES: Locale Categories.
+-* LC_MONETARY: Locale Categories.
+-* LC_NUMERIC: Locale Categories.
+-* LC_TIME: Locale Categories.
+-* LINE_MAX: Utility Limits.
+-* LINK_MAX: Limits for Files.
+-* MAX_CANON: Limits for Files.
+-* MAX_INPUT: Limits for Files.
+-* MAXNAMLEN: Limits for Files.
+-* MB_CUR_MAX: Multibyte Char Intro.
+-* MB_LEN_MAX: Multibyte Char Intro.
+-* MDMBUF: Control Modes.
+-* MINSIGSTKSZ: Signal Stack.
+-* MSG_DONTROUTE: Socket Data Options.
+-* MSG_OOB: Socket Data Options.
+-* MSG_PEEK: Socket Data Options.
+-* NAME_MAX: Limits for Files.
+-* NAN: Not a Number.
+-* NCCS: Mode Data Types.
+-* NDEBUG: Consistency Checking.
+-* netgroup: NSS Basics.
+-* network: NSS Basics.
+-* NGROUPS_MAX: General Limits.
+-* NO_ADDRESS: Host Names.
+-* NO_RECOVERY: Host Names.
+-* NOFLSH: Local Modes.
+-* NOKERNINFO: Local Modes.
+-* NSIG: Standard Signals.
+-* NSS_STATUS_NOTFOUND: NSS Modules Interface.
+-* NSS_STATUS_SUCCESS: NSS Modules Interface.
+-* NSS_STATUS_TRYAGAIN: NSS Modules Interface.
+-* NSS_STATUS_UNAVAIL: NSS Modules Interface.
+-* NULL: Null Pointer Constant.
+-* O_ACCMODE: Access Modes.
+-* O_APPEND: Operating Modes.
+-* O_ASYNC: Operating Modes.
+-* O_CREAT: Open-time Flags.
+-* O_EXCL: Open-time Flags.
+-* O_EXEC: Access Modes.
+-* O_EXLOCK: Open-time Flags.
+-* O_FSYNC: Operating Modes.
+-* O_IGNORE_CTTY: Open-time Flags.
+-* O_NDELAY: Operating Modes.
+-* O_NOATIME: Operating Modes.
+-* O_NOCTTY: Open-time Flags.
+-* O_NOLINK: Open-time Flags.
+-* O_NONBLOCK <1>: Operating Modes.
+-* O_NONBLOCK: Open-time Flags.
+-* O_NOTRANS: Open-time Flags.
+-* O_RDONLY: Access Modes.
+-* O_RDWR: Access Modes.
+-* O_READ: Access Modes.
+-* O_SHLOCK: Open-time Flags.
+-* O_SYNC: Operating Modes.
+-* O_TRUNC: Open-time Flags.
+-* O_WRITE: Access Modes.
+-* O_WRONLY: Access Modes.
+-* ONLCR: Output Modes.
+-* ONOEOT: Output Modes.
+-* OPEN_MAX: General Limits.
+-* OPOST: Output Modes.
+-* optarg: Parsing Options.
+-* opterr: Parsing Options.
+-* optind: Parsing Options.
+-* optopt: Parsing Options.
+-* OXTABS: Output Modes.
+-* P_tmpdir: Temporary Files.
+-* PA_CHAR: Parsing a Template String.
+-* PA_DOUBLE: Parsing a Template String.
+-* PA_FLAG_LONG: Parsing a Template String.
+-* PA_FLAG_LONG_DOUBLE: Parsing a Template String.
+-* PA_FLAG_LONG_LONG: Parsing a Template String.
+-* PA_FLAG_MASK: Parsing a Template String.
+-* PA_FLAG_PTR: Parsing a Template String.
+-* PA_FLAG_SHORT: Parsing a Template String.
+-* PA_FLOAT: Parsing a Template String.
+-* PA_INT: Parsing a Template String.
+-* PA_LAST: Parsing a Template String.
+-* PA_POINTER: Parsing a Template String.
+-* PA_STRING: Parsing a Template String.
+-* PARENB: Control Modes.
+-* PARMRK: Input Modes.
+-* PARODD: Control Modes.
+-* passwd: NSS Basics.
+-* PATH_MAX: Limits for Files.
+-* PENDIN: Local Modes.
+-* PF_CCITT: Misc Namespaces.
+-* PF_FILE: File Namespace Details.
+-* PF_IMPLINK: Misc Namespaces.
+-* PF_INET: Internet Namespace.
+-* PF_ISO: Misc Namespaces.
+-* PF_NS: Misc Namespaces.
+-* PF_ROUTE: Misc Namespaces.
+-* PF_UNIX: File Namespace Details.
+-* PIPE_BUF: Limits for Files.
+-* PRIO_MAX: Priority.
+-* PRIO_MIN: Priority.
+-* PRIO_PGRP: Priority.
+-* PRIO_PROCESS: Priority.
+-* PRIO_USER: Priority.
+-* program_invocation_name: Error Messages.
+-* program_invocation_short_name: Error Messages.
+-* protocols: NSS Basics.
+-* R_OK: Testing File Access.
+-* RAND_MAX: ISO Random.
+-* RE_DUP_MAX: General Limits.
+-* RLIM_NLIMITS: Limits on Resources.
+-* RLIMIT_CORE: Limits on Resources.
+-* RLIMIT_CPU: Limits on Resources.
+-* RLIMIT_DATA: Limits on Resources.
+-* RLIMIT_FSIZE: Limits on Resources.
+-* RLIMIT_NOFILE: Limits on Resources.
+-* RLIMIT_OFILE: Limits on Resources.
+-* RLIMIT_RSS: Limits on Resources.
+-* RLIMIT_STACK: Limits on Resources.
+-* rpc: NSS Basics.
+-* S_IEXEC: Permission Bits.
+-* S_IFBLK: Testing File Type.
+-* S_IFCHR: Testing File Type.
+-* S_IFDIR: Testing File Type.
+-* S_IFIFO: Testing File Type.
+-* S_IFLNK: Testing File Type.
+-* S_IFMT: Testing File Type.
+-* S_IFREG: Testing File Type.
+-* S_IFSOCK: Testing File Type.
+-* S_IREAD: Permission Bits.
+-* S_IRGRP: Permission Bits.
+-* S_IROTH: Permission Bits.
+-* S_IRUSR: Permission Bits.
+-* S_IRWXG: Permission Bits.
+-* S_IRWXO: Permission Bits.
+-* S_IRWXU: Permission Bits.
+-* S_ISGID: Permission Bits.
+-* S_ISUID: Permission Bits.
+-* S_ISVTX: Permission Bits.
+-* S_IWGRP: Permission Bits.
+-* S_IWOTH: Permission Bits.
+-* S_IWRITE: Permission Bits.
+-* S_IWUSR: Permission Bits.
+-* S_IXGRP: Permission Bits.
+-* S_IXOTH: Permission Bits.
+-* S_IXUSR: Permission Bits.
+-* SA_DISABLE: Signal Stack.
+-* SA_NOCLDSTOP: Flags for Sigaction.
+-* SA_ONSTACK <1>: Signal Stack.
+-* SA_ONSTACK: Flags for Sigaction.
+-* SA_RESTART: Flags for Sigaction.
+-* SEEK_CUR: File Positioning.
+-* SEEK_END: File Positioning.
+-* SEEK_SET: File Positioning.
+-* services: NSS Basics.
+-* shadow: NSS Basics.
+-* SIG_BLOCK: Process Signal Mask.
+-* SIG_DFL: Basic Signal Handling.
+-* SIG_ERR: Basic Signal Handling.
+-* SIG_IGN: Basic Signal Handling.
+-* SIG_SETMASK: Process Signal Mask.
+-* SIG_UNBLOCK: Process Signal Mask.
+-* SIGABRT: Program Error Signals.
+-* SIGALRM: Alarm Signals.
+-* SIGBUS: Program Error Signals.
+-* SIGCHLD: Job Control Signals.
+-* SIGCLD: Job Control Signals.
+-* SIGCONT: Job Control Signals.
+-* SIGEMT: Program Error Signals.
+-* SIGFPE: Program Error Signals.
+-* SIGHUP: Termination Signals.
+-* SIGILL: Program Error Signals.
+-* SIGINFO: Miscellaneous Signals.
+-* SIGINT: Termination Signals.
+-* SIGIO: Asynchronous I/O Signals.
+-* SIGIOT: Program Error Signals.
+-* SIGKILL: Termination Signals.
+-* SIGLOST: Operation Error Signals.
+-* SIGPIPE: Operation Error Signals.
+-* SIGPOLL: Asynchronous I/O Signals.
+-* SIGPROF: Alarm Signals.
+-* SIGQUIT: Termination Signals.
+-* SIGSEGV: Program Error Signals.
+-* SIGSTKSZ: Signal Stack.
+-* SIGSTOP: Job Control Signals.
+-* SIGSYS: Program Error Signals.
+-* SIGTERM: Termination Signals.
+-* SIGTRAP: Program Error Signals.
+-* SIGTSTP: Job Control Signals.
+-* SIGTTIN: Job Control Signals.
+-* SIGTTOU: Job Control Signals.
+-* SIGURG: Asynchronous I/O Signals.
+-* SIGUSR1: Miscellaneous Signals.
+-* SIGUSR2: Miscellaneous Signals.
+-* SIGVTALRM: Alarm Signals.
+-* SIGWINCH: Miscellaneous Signals.
+-* SIGXCPU: Operation Error Signals.
+-* SIGXFSZ: Operation Error Signals.
+-* SOCK_DGRAM: Communication Styles.
+-* SOCK_RAW: Communication Styles.
+-* SOCK_STREAM: Communication Styles.
+-* SOL_SOCKET: Socket-Level Options.
+-* SSIZE_MAX: General Limits.
+-* stderr: Standard Streams.
+-* STDERR_FILENO: Descriptors and Streams.
+-* stdin: Standard Streams.
+-* STDIN_FILENO: Descriptors and Streams.
+-* stdout: Standard Streams.
+-* STDOUT_FILENO: Descriptors and Streams.
+-* STREAM_MAX: General Limits.
+-* SV_INTERRUPT: BSD Handler.
+-* SV_ONSTACK: BSD Handler.
+-* SV_RESETHAND: BSD Handler.
+-* sys_siglist: Signal Messages.
+-* TCIFLUSH: Line Control.
+-* TCIOFF: Line Control.
+-* TCIOFLUSH: Line Control.
+-* TCION: Line Control.
+-* TCOFLUSH: Line Control.
+-* TCOOFF: Line Control.
+-* TCOON: Line Control.
+-* TCSADRAIN: Mode Functions.
+-* TCSAFLUSH: Mode Functions.
+-* TCSANOW: Mode Functions.
+-* TCSASOFT: Mode Functions.
+-* timezone: Time Zone Functions.
+-* TMP_MAX: Temporary Files.
+-* TOSTOP: Local Modes.
+-* TRY_AGAIN: Host Names.
+-* tzname: Time Zone Functions.
+-* TZNAME_MAX: General Limits.
+-* VDISCARD: Other Special.
+-* VDSUSP: Signal Characters.
+-* VEOF: Editing Characters.
+-* VEOL: Editing Characters.
+-* VEOL2: Editing Characters.
+-* VERASE: Editing Characters.
+-* VINTR: Signal Characters.
+-* VKILL: Editing Characters.
+-* VLNEXT: Other Special.
+-* VMIN: Noncanonical Input.
+-* VQUIT: Signal Characters.
+-* VREPRINT: Editing Characters.
+-* VSTART: Start/Stop Characters.
+-* VSTATUS: Other Special.
+-* VSTOP: Start/Stop Characters.
+-* VSUSP: Signal Characters.
+-* VTIME: Noncanonical Input.
+-* VWERASE: Editing Characters.
+-* W_OK: Testing File Access.
+-* X_OK: Testing File Access.
+-
+-
+-File: libc.info, Node: File Index, Prev: Variable Index, Up: Top
+-
+-Program and File Index
+-**********************
+-
+-* Menu:
+-
+-* -lbsd-compat <1>: Process Group Functions.
+-* -lbsd-compat: Feature Test Macros.
+-* /etc/group: Group Database.
+-* /etc/hosts: Host Names.
+-* /etc/localtime: TZ Variable.
+-* /etc/networks: Networks Database.
+-* /etc/passwd: User Database.
+-* /etc/protocols: Protocols Database.
+-* /etc/services: Services Database.
+-* /share/lib/zoneinfo: TZ Variable.
+-* arpa/inet.h: Host Address Functions.
+-* assert.h: Consistency Checking.
+-* bsd-compat <1>: Process Group Functions.
+-* bsd-compat: Feature Test Macros.
+-* cd: Working Directory.
+-* chgrp: File Owner.
+-* chown: File Owner.
+-* ctype.h <1>: Case Conversion.
+-* ctype.h <2>: Classification of Characters.
+-* ctype.h: Character Handling.
+-* dirent.h <1>: Random Access Directory.
+-* dirent.h <2>: Reading/Closing Directory.
+-* dirent.h <3>: Opening a Directory.
+-* dirent.h <4>: Directory Entries.
+-* dirent.h: Reserved Names.
+-* errno.h <1>: Error Codes.
+-* errno.h <2>: Checking for Errors.
+-* errno.h: Error Reporting.
+-* fcntl.h <1>: Interrupt Input.
+-* fcntl.h <2>: File Locks.
+-* fcntl.h <3>: File Status Flags.
+-* fcntl.h <4>: Descriptor Flags.
+-* fcntl.h <5>: Duplicating Descriptors.
+-* fcntl.h <6>: Control Operations.
+-* fcntl.h <7>: Opening and Closing Files.
+-* fcntl.h: Reserved Names.
+-* float.h: Floating Point Parameters.
+-* fnmatch.h: Wildcard Matching.
+-* gcc: ISO C.
+-* grp.h <1>: Group Data Structure.
+-* grp.h <2>: Setting Groups.
+-* grp.h: Reserved Names.
+-* hostid: Host Identification.
+-* hostname: Host Identification.
+-* kill: Termination Signals.
+-* limits.h <1>: Width of Type.
+-* limits.h <2>: Limits for Files.
+-* limits.h <3>: General Limits.
+-* limits.h <4>: Multibyte Char Intro.
+-* limits.h: Reserved Names.
+-* locale.h <1>: Numeric Formatting.
+-* locale.h: Setting the Locale.
+-* localtime: TZ Variable.
+-* ls: File Attributes.
+-* malloc.c: Memory Warnings.
+-* malloc.h <1>: Using Relocator.
+-* malloc.h <2>: Statistics of Malloc.
+-* malloc.h <3>: Hooks for Malloc.
+-* malloc.h: Heap Consistency Checking.
+-* math.h <1>: Rounding and Remainders.
+-* math.h <2>: Normalization Functions.
+-* math.h <3>: Absolute Value.
+-* math.h <4>: Predicates on Floats.
+-* math.h: Mathematics.
+-* mkdir: Creating Directories.
+-* netdb.h <1>: Networks Database.
+-* netdb.h <2>: Protocols Database.
+-* netdb.h <3>: Services Database.
+-* netdb.h: Host Names.
+-* netinet/in.h <1>: Byte Order.
+-* netinet/in.h <2>: Ports.
+-* netinet/in.h <3>: Host Address Data Type.
+-* netinet/in.h: Internet Address Format.
+-* obstack.h: Creating Obstacks.
+-* printf.h <1>: Conversion Specifier Options.
+-* printf.h: Registering New Conversions.
+-* pwd.h <1>: User Data Structure.
+-* pwd.h: Reserved Names.
+-* setjmp.h <1>: Non-Local Exits and Signals.
+-* setjmp.h: Non-Local Details.
+-* sh: Running a Command.
+-* signal.h <1>: BSD Signal Handling.
+-* signal.h <2>: Checking for Pending Signals.
+-* signal.h <3>: Process Signal Mask.
+-* signal.h <4>: Signal Sets.
+-* signal.h <5>: Signaling Another Process.
+-* signal.h <6>: Signaling Yourself.
+-* signal.h <7>: Flags for Sigaction.
+-* signal.h <8>: Advanced Signal Handling.
+-* signal.h <9>: Basic Signal Handling.
+-* signal.h <10>: Standard Signals.
+-* signal.h: Reserved Names.
+-* stdarg.h <1>: Argument Macros.
+-* stdarg.h: Receiving Arguments.
+-* stddef.h <1>: Important Data Types.
+-* stddef.h: Wide Char Intro.
+-* stdio.h <1>: Who Logged In.
+-* stdio.h <2>: Identifying the Terminal.
+-* stdio.h <3>: Signal Messages.
+-* stdio.h <4>: Temporary Files.
+-* stdio.h <5>: Deleting Files.
+-* stdio.h <6>: Descriptors and Streams.
+-* stdio.h <7>: Streams and Cookies.
+-* stdio.h <8>: String Streams.
+-* stdio.h <9>: Controlling Buffering.
+-* stdio.h <10>: Flushing Buffers.
+-* stdio.h <11>: Portable Positioning.
+-* stdio.h <12>: File Positioning.
+-* stdio.h <13>: EOF and Errors.
+-* stdio.h <14>: Formatted Input Functions.
+-* stdio.h <15>: Variable Arguments Output.
+-* stdio.h <16>: Formatted Output Functions.
+-* stdio.h <17>: Block Input/Output.
+-* stdio.h <18>: Character Input.
+-* stdio.h <19>: Simple Output.
+-* stdio.h <20>: Opening Streams.
+-* stdio.h <21>: Standard Streams.
+-* stdio.h: Streams.
+-* stdlib.h <1>: Running a Command.
+-* stdlib.h <2>: Aborting a Program.
+-* stdlib.h <3>: Exit Status.
+-* stdlib.h <4>: Environment Access.
+-* stdlib.h <5>: Converting One Char.
+-* stdlib.h <6>: Length of Char.
+-* stdlib.h <7>: Wide String Conversion.
+-* stdlib.h <8>: Multibyte Char Intro.
+-* stdlib.h <9>: Array Sort Function.
+-* stdlib.h <10>: Array Search Function.
+-* stdlib.h <11>: Parsing of Floats.
+-* stdlib.h <12>: Parsing of Integers.
+-* stdlib.h <13>: Integer Division.
+-* stdlib.h <14>: Absolute Value.
+-* stdlib.h <15>: BSD Random.
+-* stdlib.h <16>: ISO Random.
+-* stdlib.h <17>: Variable Size Automatic.
+-* stdlib.h <18>: Aligned Memory Blocks.
+-* stdlib.h <19>: Allocating Cleared Space.
+-* stdlib.h <20>: Changing Block Size.
+-* stdlib.h <21>: Freeing after Malloc.
+-* stdlib.h: Basic Allocation.
+-* string.h <1>: Signal Messages.
+-* string.h <2>: Finding Tokens in a String.
+-* string.h <3>: Search Functions.
+-* string.h <4>: Collation Functions.
+-* string.h <5>: String/Array Comparison.
+-* string.h <6>: Copying and Concatenation.
+-* string.h: String Length.
+-* sys/param.h: Host Identification.
+-* sys/resource.h <1>: Priority.
+-* sys/resource.h <2>: Limits on Resources.
+-* sys/resource.h: Resource Usage.
+-* sys/socket.h <1>: Socket-Level Options.
+-* sys/socket.h <2>: Socket Option Functions.
+-* sys/socket.h <3>: Sending Datagrams.
+-* sys/socket.h <4>: Socket Data Options.
+-* sys/socket.h <5>: Receiving Data.
+-* sys/socket.h <6>: Sending Data.
+-* sys/socket.h <7>: Socket Pairs.
+-* sys/socket.h <8>: Closing a Socket.
+-* sys/socket.h <9>: Creating a Socket.
+-* sys/socket.h <10>: Internet Namespace.
+-* sys/socket.h <11>: File Namespace Details.
+-* sys/socket.h <12>: Reading Address.
+-* sys/socket.h <13>: Setting Address.
+-* sys/socket.h <14>: Address Formats.
+-* sys/socket.h: Communication Styles.
+-* sys/stat.h <1>: FIFO Special Files.
+-* sys/stat.h <2>: Making Special Files.
+-* sys/stat.h <3>: Setting Permissions.
+-* sys/stat.h <4>: Permission Bits.
+-* sys/stat.h <5>: Testing File Type.
+-* sys/stat.h <6>: Attribute Meanings.
+-* sys/stat.h <7>: Creating Directories.
+-* sys/stat.h: Reserved Names.
+-* sys/time.h <1>: Setting an Alarm.
+-* sys/time.h <2>: High-Resolution Calendar.
+-* sys/time.h: File Times.
+-* sys/times.h <1>: Detailed CPU Time.
+-* sys/times.h: Reserved Names.
+-* sys/types.h <1>: Setting Groups.
+-* sys/types.h <2>: Setting User ID.
+-* sys/types.h <3>: Reading Persona.
+-* sys/types.h <4>: Terminal Access Functions.
+-* sys/types.h <5>: Process Group Functions.
+-* sys/types.h <6>: Process Identification.
+-* sys/types.h: Waiting for I/O.
+-* sys/un.h: File Namespace Details.
+-* sys/utsname.h: Hardware/Software Type ID.
+-* sys/wait.h <1>: BSD Wait Functions.
+-* sys/wait.h <2>: Process Completion Status.
+-* sys/wait.h: Process Completion.
+-* termios.h <1>: Terminal Modes.
+-* termios.h: Reserved Names.
+-* time.h <1>: TZ Variable.
+-* time.h <2>: Formatting Date and Time.
+-* time.h <3>: Simple Calendar Time.
+-* time.h <4>: Basic CPU Time.
+-* time.h: File Times.
+-* umask: Setting Permissions.
+-* unistd.h <1>: Options for Files.
+-* unistd.h <2>: System Options.
+-* unistd.h <3>: Host Identification.
+-* unistd.h <4>: Who Logged In.
+-* unistd.h <5>: Setting Groups.
+-* unistd.h <6>: Setting User ID.
+-* unistd.h <7>: Reading Persona.
+-* unistd.h <8>: Terminal Access Functions.
+-* unistd.h <9>: Process Group Functions.
+-* unistd.h <10>: Executing a File.
+-* unistd.h <11>: Creating a Process.
+-* unistd.h <12>: Process Identification.
+-* unistd.h <13>: Termination Internals.
+-* unistd.h <14>: Parsing Options.
+-* unistd.h <15>: Setting an Alarm.
+-* unistd.h <16>: Is It a Terminal.
+-* unistd.h <17>: Creating a Pipe.
+-* unistd.h <18>: Testing File Access.
+-* unistd.h <19>: File Owner.
+-* unistd.h <20>: Deleting Files.
+-* unistd.h <21>: Symbolic Links.
+-* unistd.h <22>: Hard Links.
+-* unistd.h <23>: Working Directory.
+-* unistd.h <24>: Duplicating Descriptors.
+-* unistd.h <25>: Descriptors and Streams.
+-* unistd.h <26>: I/O Primitives.
+-* unistd.h: Opening and Closing Files.
+-* utime.h: File Times.
+-* varargs.h: Old Varargs.
+-* zoneinfo: TZ Variable.
+-
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-4
glibc-2.0.1/manual/libc.info-4
+--- ../glibc-2.0.1/manual/libc.info-4 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-4 1970-01-01 01:00:00.000000000 +0100
+@@ -1,1213 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+- This file documents the GNU C library.
+-
+- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+- Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+- Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+- Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: Extra Fast Growing, Next: Status of an Obstack,
Prev: Growing Objects, Up: Obstacks
+-
+-Extra Fast Growing Objects
+---------------------------
+-
+- The usual functions for growing objects incur overhead for checking
+-whether there is room for the new growth in the current chunk. If you
+-are frequently constructing objects in small steps of growth, this
+-overhead can be significant.
+-
+- You can reduce the overhead by using special "fast growth" functions
+-that grow the object without checking. In order to have a robust
+-program, you must do the checking yourself. If you do this checking in
+-the simplest way each time you are about to add data to the object, you
+-have not saved anything, because that is what the ordinary growth
+-functions do. But if you can arrange to check less often, or check
+-more efficiently, then you make the program faster.
+-
+- The function `obstack_room' returns the amount of room available in
+-the current chunk. It is declared as follows:
+-
+- - Function: int obstack_room (struct obstack *OBSTACK-PTR)
+- This returns the number of bytes that can be added safely to the
+- current growing object (or to an object about to be started) in
+- obstack OBSTACK using the fast growth functions.
+-
+- While you know there is room, you can use these fast growth functions
+-for adding data to a growing object:
+-
+- - Function: void obstack_1grow_fast (struct obstack *OBSTACK-PTR, char
+- C)
+- The function `obstack_1grow_fast' adds one byte containing the
+- character C to the growing object in obstack OBSTACK-PTR.
+-
+- - Function: void obstack_ptr_grow_fast (struct obstack *OBSTACK-PTR,
+- void *DATA)
+- The function `obstack_ptr_grow_fast' adds `sizeof (void *)' bytes
+- containing the value of DATA to the growing object in obstack
+- OBSTACK-PTR.
+-
+- - Function: void obstack_int_grow_fast (struct obstack *OBSTACK-PTR,
+- int DATA)
+- The function `obstack_int_grow_fast' adds `sizeof (int)' bytes
+- containing the value of DATA to the growing object in obstack
+- OBSTACK-PTR.
+-
+- - Function: void obstack_blank_fast (struct obstack *OBSTACK-PTR, int
+- SIZE)
+- The function `obstack_blank_fast' adds SIZE bytes to the growing
+- object in obstack OBSTACK-PTR without initializing them.
+-
+- When you check for space using `obstack_room' and there is not
+-enough room for what you want to add, the fast growth functions are not
+-safe. In this case, simply use the corresponding ordinary growth
+-function instead. Very soon this will copy the object to a new chunk;
+-then there will be lots of room available again.
+-
+- So, each time you use an ordinary growth function, check afterward
+-for sufficient space using `obstack_room'. Once the object is copied
+-to a new chunk, there will be plenty of space again, so the program will
+-start using the fast growth functions again.
+-
+- Here is an example:
+-
+- void
+- add_string (struct obstack *obstack, const char *ptr, int len)
+- {
+- while (len > 0)
+- {
+- int room = obstack_room (obstack);
+- if (room == 0)
+- {
+- /* Not enough room. Add one character slowly,
+- which may copy to a new chunk and make room. */
+- obstack_1grow (obstack, *ptr++);
+- len--;
+- }
+- else
+- {
+- if (room > len)
+- room = len;
+- /* Add fast as much as we have room for. */
+- len -= room;
+- while (room-- > 0)
+- obstack_1grow_fast (obstack, *ptr++);
+- }
+- }
+- }
+-
+-
+-File: libc.info, Node: Status of an Obstack, Next: Obstacks Data Alignment,
Prev: Extra Fast Growing, Up: Obstacks
+-
+-Status of an Obstack
+---------------------
+-
+- Here are functions that provide information on the current status of
+-allocation in an obstack. You can use them to learn about an object
+-while still growing it.
+-
+- - Function: void * obstack_base (struct obstack *OBSTACK-PTR)
+- This function returns the tentative address of the beginning of the
+- currently growing object in OBSTACK-PTR. If you finish the object
+- immediately, it will have that address. If you make it larger
+- first, it may outgrow the current chunk--then its address will
+- change!
+-
+- If no object is growing, this value says where the next object you
+- allocate will start (once again assuming it fits in the current
+- chunk).
+-
+- - Function: void * obstack_next_free (struct obstack *OBSTACK-PTR)
+- This function returns the address of the first free byte in the
+- current chunk of obstack OBSTACK-PTR. This is the end of the
+- currently growing object. If no object is growing,
+- `obstack_next_free' returns the same value as `obstack_base'.
+-
+- - Function: int obstack_object_size (struct obstack *OBSTACK-PTR)
+- This function returns the size in bytes of the currently growing
+- object. This is equivalent to
+-
+- obstack_next_free (OBSTACK-PTR) - obstack_base (OBSTACK-PTR)
+-
+-
+-File: libc.info, Node: Obstacks Data Alignment, Next: Obstack Chunks,
Prev: Status of an Obstack, Up: Obstacks
+-
+-Alignment of Data in Obstacks
+------------------------------
+-
+- Each obstack has an "alignment boundary"; each object allocated in
+-the obstack automatically starts on an address that is a multiple of the
+-specified boundary. By default, this boundary is 4 bytes.
+-
+- To access an obstack's alignment boundary, use the macro
+-`obstack_alignment_mask', whose function prototype looks like this:
+-
+- - Macro: int obstack_alignment_mask (struct obstack *OBSTACK-PTR)
+- The value is a bit mask; a bit that is 1 indicates that the
+- corresponding bit in the address of an object should be 0. The
+- mask value should be one less than a power of 2; the effect is
+- that all object addresses are multiples of that power of 2. The
+- default value of the mask is 3, so that addresses are multiples of
+- 4. A mask value of 0 means an object can start on any multiple of
+- 1 (that is, no alignment is required).
+-
+- The expansion of the macro `obstack_alignment_mask' is an lvalue,
+- so you can alter the mask by assignment. For example, this
+- statement:
+-
+- obstack_alignment_mask (obstack_ptr) = 0;
+-
+- has the effect of turning off alignment processing in the
+- specified obstack.
+-
+- Note that a change in alignment mask does not take effect until
+-*after* the next time an object is allocated or finished in the
+-obstack. If you are not growing an object, you can make the new
+-alignment mask take effect immediately by calling `obstack_finish'.
+-This will finish a zero-length object and then do proper alignment for
+-the next object.
+-
+-
+-File: libc.info, Node: Obstack Chunks, Next: Summary of Obstacks, Prev:
Obstacks Data Alignment, Up: Obstacks
+-
+-Obstack Chunks
+---------------
+-
+- Obstacks work by allocating space for themselves in large chunks, and
+-then parceling out space in the chunks to satisfy your requests. Chunks
+-are normally 4096 bytes long unless you specify a different chunk size.
+-The chunk size includes 8 bytes of overhead that are not actually used
+-for storing objects. Regardless of the specified size, longer chunks
+-will be allocated when necessary for long objects.
+-
+- The obstack library allocates chunks by calling the function
+-`obstack_chunk_alloc', which you must define. When a chunk is no
+-longer needed because you have freed all the objects in it, the obstack
+-library frees the chunk by calling `obstack_chunk_free', which you must
+-also define.
+-
+- These two must be defined (as macros) or declared (as functions) in
+-each source file that uses `obstack_init' (*note Creating Obstacks::.).
+-Most often they are defined as macros like this:
+-
+- #define obstack_chunk_alloc xmalloc
+- #define obstack_chunk_free free
+-
+- Note that these are simple macros (no arguments). Macro definitions
+-with arguments will not work! It is necessary that
+-`obstack_chunk_alloc' or `obstack_chunk_free', alone, expand into a
+-function name if it is not itself a function name.
+-
+- If you allocate chunks with `malloc', the chunk size should be a
+-power of 2. The default chunk size, 4096, was chosen because it is long
+-enough to satisfy many typical requests on the obstack yet short enough
+-not to waste too much memory in the portion of the last chunk not yet
+-used.
+-
+- - Macro: int obstack_chunk_size (struct obstack *OBSTACK-PTR)
+- This returns the chunk size of the given obstack.
+-
+- Since this macro expands to an lvalue, you can specify a new chunk
+-size by assigning it a new value. Doing so does not affect the chunks
+-already allocated, but will change the size of chunks allocated for
+-that particular obstack in the future. It is unlikely to be useful to
+-make the chunk size smaller, but making it larger might improve
+-efficiency if you are allocating many objects whose size is comparable
+-to the chunk size. Here is how to do so cleanly:
+-
+- if (obstack_chunk_size (obstack_ptr) < NEW-CHUNK-SIZE)
+- obstack_chunk_size (obstack_ptr) = NEW-CHUNK-SIZE;
+-
+-
+-File: libc.info, Node: Summary of Obstacks, Prev: Obstack Chunks, Up:
Obstacks
+-
+-Summary of Obstack Functions
+-----------------------------
+-
+- Here is a summary of all the functions associated with obstacks.
+-Each takes the address of an obstack (`struct obstack *') as its first
+-argument.
+-
+-`void obstack_init (struct obstack *OBSTACK-PTR)'
+- Initialize use of an obstack. *Note Creating Obstacks::.
+-
+-`void *obstack_alloc (struct obstack *OBSTACK-PTR, int SIZE)'
+- Allocate an object of SIZE uninitialized bytes. *Note Allocation
+- in an Obstack::.
+-
+-`void *obstack_copy (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
+- Allocate an object of SIZE bytes, with contents copied from
+- ADDRESS. *Note Allocation in an Obstack::.
+-
+-`void *obstack_copy0 (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
+- Allocate an object of SIZE+1 bytes, with SIZE of them copied from
+- ADDRESS, followed by a null character at the end. *Note
+- Allocation in an Obstack::.
+-
+-`void obstack_free (struct obstack *OBSTACK-PTR, void *OBJECT)'
+- Free OBJECT (and everything allocated in the specified obstack
+- more recently than OBJECT). *Note Freeing Obstack Objects::.
+-
+-`void obstack_blank (struct obstack *OBSTACK-PTR, int SIZE)'
+- Add SIZE uninitialized bytes to a growing object. *Note Growing
+- Objects::.
+-
+-`void obstack_grow (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
+- Add SIZE bytes, copied from ADDRESS, to a growing object. *Note
+- Growing Objects::.
+-
+-`void obstack_grow0 (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
+- Add SIZE bytes, copied from ADDRESS, to a growing object, and then
+- add another byte containing a null character. *Note Growing
+- Objects::.
+-
+-`void obstack_1grow (struct obstack *OBSTACK-PTR, char DATA-CHAR)'
+- Add one byte containing DATA-CHAR to a growing object. *Note
+- Growing Objects::.
+-
+-`void *obstack_finish (struct obstack *OBSTACK-PTR)'
+- Finalize the object that is growing and return its permanent
+- address. *Note Growing Objects::.
+-
+-`int obstack_object_size (struct obstack *OBSTACK-PTR)'
+- Get the current size of the currently growing object. *Note
+- Growing Objects::.
+-
+-`void obstack_blank_fast (struct obstack *OBSTACK-PTR, int SIZE)'
+- Add SIZE uninitialized bytes to a growing object without checking
+- that there is enough room. *Note Extra Fast Growing::.
+-
+-`void obstack_1grow_fast (struct obstack *OBSTACK-PTR, char DATA-CHAR)'
+- Add one byte containing DATA-CHAR to a growing object without
+- checking that there is enough room. *Note Extra Fast Growing::.
+-
+-`int obstack_room (struct obstack *OBSTACK-PTR)'
+- Get the amount of room now available for growing the current
+- object. *Note Extra Fast Growing::.
+-
+-`int obstack_alignment_mask (struct obstack *OBSTACK-PTR)'
+- The mask used for aligning the beginning of an object. This is an
+- lvalue. *Note Obstacks Data Alignment::.
+-
+-`int obstack_chunk_size (struct obstack *OBSTACK-PTR)'
+- The size for allocating chunks. This is an lvalue. *Note Obstack
+- Chunks::.
+-
+-`void *obstack_base (struct obstack *OBSTACK-PTR)'
+- Tentative starting address of the currently growing object. *Note
+- Status of an Obstack::.
+-
+-`void *obstack_next_free (struct obstack *OBSTACK-PTR)'
+- Address just after the end of the currently growing object. *Note
+- Status of an Obstack::.
+-
+-
+-File: libc.info, Node: Variable Size Automatic, Next: Relocating Allocator,
Prev: Obstacks, Up: Memory Allocation
+-
+-Automatic Storage with Variable Size
+-====================================
+-
+- The function `alloca' supports a kind of half-dynamic allocation in
+-which blocks are allocated dynamically but freed automatically.
+-
+- Allocating a block with `alloca' is an explicit action; you can
+-allocate as many blocks as you wish, and compute the size at run time.
+-But all the blocks are freed when you exit the function that `alloca'
+-was called from, just as if they were automatic variables declared in
+-that function. There is no way to free the space explicitly.
+-
+- The prototype for `alloca' is in `stdlib.h'. This function is a BSD
+-extension.
+-
+- - Function: void * alloca (size_t SIZE);
+- The return value of `alloca' is the address of a block of SIZE
+- bytes of storage, allocated in the stack frame of the calling
+- function.
+-
+- Do not use `alloca' inside the arguments of a function call--you
+-will get unpredictable results, because the stack space for the
+-`alloca' would appear on the stack in the middle of the space for the
+-function arguments. An example of what to avoid is `foo (x, alloca
+-(4), y)'.
+-
+-* Menu:
+-
+-* Alloca Example:: Example of using `alloca'.
+-* Advantages of Alloca:: Reasons to use `alloca'.
+-* Disadvantages of Alloca:: Reasons to avoid `alloca'.
+-* GNU C Variable-Size Arrays:: Only in GNU C, here is an alternative
+- method of allocating dynamically and
+- freeing automatically.
+-
+-
+-File: libc.info, Node: Alloca Example, Next: Advantages of Alloca, Up:
Variable Size Automatic
+-
+-`alloca' Example
+-----------------
+-
+- As an example of use of `alloca', here is a function that opens a
+-file name made from concatenating two argument strings, and returns a
+-file descriptor or minus one signifying failure:
+-
+- int
+- open2 (char *str1, char *str2, int flags, int mode)
+- {
+- char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
+- stpcpy (stpcpy (name, str1), str2);
+- return open (name, flags, mode);
+- }
+-
+-Here is how you would get the same results with `malloc' and `free':
+-
+- int
+- open2 (char *str1, char *str2, int flags, int mode)
+- {
+- char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
+- int desc;
+- if (name == 0)
+- fatal ("virtual memory exceeded");
+- stpcpy (stpcpy (name, str1), str2);
+- desc = open (name, flags, mode);
+- free (name);
+- return desc;
+- }
+-
+- As you can see, it is simpler with `alloca'. But `alloca' has
+-other, more important advantages, and some disadvantages.
+-
+-
+-File: libc.info, Node: Advantages of Alloca, Next: Disadvantages of Alloca,
Prev: Alloca Example, Up: Variable Size Automatic
+-
+-Advantages of `alloca'
+-----------------------
+-
+- Here are the reasons why `alloca' may be preferable to `malloc':
+-
+- * Using `alloca' wastes very little space and is very fast. (It is
+- open-coded by the GNU C compiler.)
+-
+- * Since `alloca' does not have separate pools for different sizes of
+- block, space used for any size block can be reused for any other
+- size. `alloca' does not cause storage fragmentation.
+-
+- * Nonlocal exits done with `longjmp' (*note Non-Local Exits::.)
+- automatically free the space allocated with `alloca' when they exit
+- through the function that called `alloca'. This is the most
+- important reason to use `alloca'.
+-
+- To illustrate this, suppose you have a function
+- `open_or_report_error' which returns a descriptor, like `open', if
+- it succeeds, but does not return to its caller if it fails. If
+- the file cannot be opened, it prints an error message and jumps
+- out to the command level of your program using `longjmp'. Let's
+- change `open2' (*note Alloca Example::.) to use this subroutine:
+-
+- int
+- open2 (char *str1, char *str2, int flags, int mode)
+- {
+- char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
+- stpcpy (stpcpy (name, str1), str2);
+- return open_or_report_error (name, flags, mode);
+- }
+-
+- Because of the way `alloca' works, the storage it allocates is
+- freed even when an error occurs, with no special effort required.
+-
+- By contrast, the previous definition of `open2' (which uses
+- `malloc' and `free') would develop a storage leak if it were
+- changed in this way. Even if you are willing to make more changes
+- to fix it, there is no easy way to do so.
+-
+-
+-File: libc.info, Node: Disadvantages of Alloca, Next: GNU C Variable-Size
Arrays, Prev: Advantages of Alloca, Up: Variable Size Automatic
+-
+-Disadvantages of `alloca'
+--------------------------
+-
+- These are the disadvantages of `alloca' in comparison with `malloc':
+-
+- * If you try to allocate more storage than the machine can provide,
+- you don't get a clean error message. Instead you get a fatal
+- signal like the one you would get from an infinite recursion;
+- probably a segmentation violation (*note Program Error Signals::.).
+-
+- * Some non-GNU systems fail to support `alloca', so it is less
+- portable. However, a slower emulation of `alloca' written in C is
+- available for use on systems with this deficiency.
+-
+-
+-File: libc.info, Node: GNU C Variable-Size Arrays, Prev: Disadvantages of
Alloca, Up: Variable Size Automatic
+-
+-GNU C Variable-Size Arrays
+---------------------------
+-
+- In GNU C, you can replace most uses of `alloca' with an array of
+-variable size. Here is how `open2' would look then:
+-
+- int open2 (char *str1, char *str2, int flags, int mode)
+- {
+- char name[strlen (str1) + strlen (str2) + 1];
+- stpcpy (stpcpy (name, str1), str2);
+- return open (name, flags, mode);
+- }
+-
+- But `alloca' is not always equivalent to a variable-sized array, for
+-several reasons:
+-
+- * A variable size array's space is freed at the end of the scope of
+- the name of the array. The space allocated with `alloca' remains
+- until the end of the function.
+-
+- * It is possible to use `alloca' within a loop, allocating an
+- additional block on each iteration. This is impossible with
+- variable-sized arrays.
+-
+- *Note:* If you mix use of `alloca' and variable-sized arrays within
+-one function, exiting a scope in which a variable-sized array was
+-declared frees all blocks allocated with `alloca' during the execution
+-of that scope.
+-
+-
+-File: libc.info, Node: Relocating Allocator, Next: Memory Warnings, Prev:
Variable Size Automatic, Up: Memory Allocation
+-
+-Relocating Allocator
+-====================
+-
+- Any system of dynamic memory allocation has overhead: the amount of
+-space it uses is more than the amount the program asks for. The
+-"relocating memory allocator" achieves very low overhead by moving
+-blocks in memory as necessary, on its own initiative.
+-
+-* Menu:
+-
+-* Relocator Concepts:: How to understand relocating allocation.
+-* Using Relocator:: Functions for relocating allocation.
+-
+-
+-File: libc.info, Node: Relocator Concepts, Next: Using Relocator, Up:
Relocating Allocator
+-
+-Concepts of Relocating Allocation
+----------------------------------
+-
+- The "relocating memory allocator" achieves very low overhead by
+-moving blocks in memory as necessary, on its own initiative.
+-
+- When you allocate a block with `malloc', the address of the block
+-never changes unless you use `realloc' to change its size. Thus, you
+-can safely store the address in various places, temporarily or
+-permanently, as you like. This is not safe when you use the relocating
+-memory allocator, because any and all relocatable blocks can move
+-whenever you allocate memory in any fashion. Even calling `malloc' or
+-`realloc' can move the relocatable blocks.
+-
+- For each relocatable block, you must make a "handle"--a pointer
+-object in memory, designated to store the address of that block. The
+-relocating allocator knows where each block's handle is, and updates the
+-address stored there whenever it moves the block, so that the handle
+-always points to the block. Each time you access the contents of the
+-block, you should fetch its address anew from the handle.
+-
+- To call any of the relocating allocator functions from a signal
+-handler is almost certainly incorrect, because the signal could happen
+-at any time and relocate all the blocks. The only way to make this
+-safe is to block the signal around any access to the contents of any
+-relocatable block--not a convenient mode of operation. *Note
+-Nonreentrancy::.
+-
+-
+-File: libc.info, Node: Using Relocator, Prev: Relocator Concepts, Up:
Relocating Allocator
+-
+-Allocating and Freeing Relocatable Blocks
+------------------------------------------
+-
+- In the descriptions below, HANDLEPTR designates the address of the
+-handle. All the functions are declared in `malloc.h'; all are GNU
+-extensions.
+-
+- - Function: void * r_alloc (void **HANDLEPTR, size_t SIZE)
+- This function allocates a relocatable block of size SIZE. It
+- stores the block's address in `*HANDLEPTR' and returns a non-null
+- pointer to indicate success.
+-
+- If `r_alloc' can't get the space needed, it stores a null pointer
+- in `*HANDLEPTR', and returns a null pointer.
+-
+- - Function: void r_alloc_free (void **HANDLEPTR)
+- This function is the way to free a relocatable block. It frees the
+- block that `*HANDLEPTR' points to, and stores a null pointer in
+- `*HANDLEPTR' to show it doesn't point to an allocated block any
+- more.
+-
+- - Function: void * r_re_alloc (void **HANDLEPTR, size_t SIZE)
+- The function `r_re_alloc' adjusts the size of the block that
+- `*HANDLEPTR' points to, making it SIZE bytes long. It stores the
+- address of the resized block in `*HANDLEPTR' and returns a
+- non-null pointer to indicate success.
+-
+- If enough memory is not available, this function returns a null
+- pointer and does not modify `*HANDLEPTR'.
+-
+-
+-File: libc.info, Node: Memory Warnings, Prev: Relocating Allocator, Up:
Memory Allocation
+-
+-Memory Usage Warnings
+-=====================
+-
+- You can ask for warnings as the program approaches running out of
+-memory space, by calling `memory_warnings'. This tells `malloc' to
+-check memory usage every time it asks for more memory from the operating
+-system. This is a GNU extension declared in `malloc.h'.
+-
+- - Function: void memory_warnings (void *START, void (*WARN-FUNC)
+- (const char *))
+- Call this function to request warnings for nearing exhaustion of
+- virtual memory.
+-
+- The argument START says where data space begins, in memory. The
+- allocator compares this against the last address used and against
+- the limit of data space, to determine the fraction of available
+- memory in use. If you supply zero for START, then a default value
+- is used which is right in most circumstances.
+-
+- For WARN-FUNC, supply a function that `malloc' can call to warn
+- you. It is called with a string (a warning message) as argument.
+- Normally it ought to display the string for the user to read.
+-
+- The warnings come when memory becomes 75% full, when it becomes 85%
+-full, and when it becomes 95% full. Above 95% you get another warning
+-each time memory usage increases.
+-
+-
+-File: libc.info, Node: Character Handling, Next: String and Array
Utilities, Prev: Memory Allocation, Up: Top
+-
+-Character Handling
+-******************
+-
+- Programs that work with characters and strings often need to
+-classify a character--is it alphabetic, is it a digit, is it
+-whitespace, and so on--and perform case conversion operations on
+-characters. The functions in the header file `ctype.h' are provided
+-for this purpose.
+-
+- Since the choice of locale and character set can alter the
+-classifications of particular character codes, all of these functions
+-are affected by the current locale. (More precisely, they are affected
+-by the locale currently selected for character classification--the
+-`LC_CTYPE' category; see *Note Locale Categories::.)
+-
+-* Menu:
+-
+-* Classification of Characters:: Testing whether characters are
+- letters, digits, punctuation, etc.
+-
+-* Case Conversion:: Case mapping, and the like.
+-
+-
+-File: libc.info, Node: Classification of Characters, Next: Case Conversion,
Up: Character Handling
+-
+-Classification of Characters
+-============================
+-
+- This section explains the library functions for classifying
+-characters. For example, `isalpha' is the function to test for an
+-alphabetic character. It takes one argument, the character to test,
+-and returns a nonzero integer if the character is alphabetic, and zero
+-otherwise. You would use it like this:
+-
+- if (isalpha (c))
+- printf ("The character `%c' is alphabetic.\n", c);
+-
+- Each of the functions in this section tests for membership in a
+-particular class of characters; each has a name starting with `is'.
+-Each of them takes one argument, which is a character to test, and
+-returns an `int' which is treated as a boolean value. The character
+-argument is passed as an `int', and it may be the constant value `EOF'
+-instead of a real character.
+-
+- The attributes of any given character can vary between locales.
+-*Note Locales::, for more information on locales.
+-
+- These functions are declared in the header file `ctype.h'.
+-
+- - Function: int islower (int C)
+- Returns true if C is a lower-case letter.
+-
+- - Function: int isupper (int C)
+- Returns true if C is an upper-case letter.
+-
+- - Function: int isalpha (int C)
+- Returns true if C is an alphabetic character (a letter). If
+- `islower' or `isupper' is true of a character, then `isalpha' is
+- also true.
+-
+- In some locales, there may be additional characters for which
+- `isalpha' is true-letters which are neither upper case nor lower
+- case. But in the standard `"C"' locale, there are no such
+- additional characters.
+-
+- - Function: int isdigit (int C)
+- Returns true if C is a decimal digit (`0' through `9').
+-
+- - Function: int isalnum (int C)
+- Returns true if C is an alphanumeric character (a letter or
+- number); in other words, if either `isalpha' or `isdigit' is true
+- of a character, then `isalnum' is also true.
+-
+- - Function: int isxdigit (int C)
+- Returns true if C is a hexadecimal digit. Hexadecimal digits
+- include the normal decimal digits `0' through `9' and the letters
+- `A' through `F' and `a' through `f'.
+-
+- - Function: int ispunct (int C)
+- Returns true if C is a punctuation character. This means any
+- printing character that is not alphanumeric or a space character.
+-
+- - Function: int isspace (int C)
+- Returns true if C is a "whitespace" character. In the standard
+- `"C"' locale, `isspace' returns true for only the standard
+- whitespace characters:
+-
+- `' ''
+- space
+-
+- `'\f''
+- formfeed
+-
+- `'\n''
+- newline
+-
+- `'\r''
+- carriage return
+-
+- `'\t''
+- horizontal tab
+-
+- `'\v''
+- vertical tab
+-
+- - Function: int isblank (int C)
+- Returns true if C is a blank character; that is, a space or a tab.
+- This function is a GNU extension.
+-
+- - Function: int isgraph (int C)
+- Returns true if C is a graphic character; that is, a character
+- that has a glyph associated with it. The whitespace characters
+- are not considered graphic.
+-
+- - Function: int isprint (int C)
+- Returns true if C is a printing character. Printing characters
+- include all the graphic characters, plus the space (` ') character.
+-
+- - Function: int iscntrl (int C)
+- Returns true if C is a control character (that is, a character that
+- is not a printing character).
+-
+- - Function: int isascii (int C)
+- Returns true if C is a 7-bit `unsigned char' value that fits into
+- the US/UK ASCII character set. This function is a BSD extension
+- and is also an SVID extension.
+-
+-
+-File: libc.info, Node: Case Conversion, Prev: Classification of Characters,
Up: Character Handling
+-
+-Case Conversion
+-===============
+-
+- This section explains the library functions for performing
+-conversions such as case mappings on characters. For example, `toupper'
+-converts any character to upper case if possible. If the character
+-can't be converted, `toupper' returns it unchanged.
+-
+- These functions take one argument of type `int', which is the
+-character to convert, and return the converted character as an `int'.
+-If the conversion is not applicable to the argument given, the argument
+-is returned unchanged.
+-
+- *Compatibility Note:* In pre-ISO C dialects, instead of returning
+-the argument unchanged, these functions may fail when the argument is
+-not suitable for the conversion. Thus for portability, you may need to
+-write `islower(c) ? toupper(c) : c' rather than just `toupper(c)'.
+-
+- These functions are declared in the header file `ctype.h'.
+-
+- - Function: int tolower (int C)
+- If C is an upper-case letter, `tolower' returns the corresponding
+- lower-case letter. If C is not an upper-case letter, C is
+- returned unchanged.
+-
+- - Function: int toupper (int C)
+- If C is a lower-case letter, `tolower' returns the corresponding
+- upper-case letter. Otherwise C is returned unchanged.
+-
+- - Function: int toascii (int C)
+- This function converts C to a 7-bit `unsigned char' value that
+- fits into the US/UK ASCII character set, by clearing the high-order
+- bits. This function is a BSD extension and is also an SVID
+- extension.
+-
+- - Function: int _tolower (int C)
+- This is identical to `tolower', and is provided for compatibility
+- with the SVID. *Note SVID::.
+-
+- - Function: int _toupper (int C)
+- This is identical to `toupper', and is provided for compatibility
+- with the SVID.
+-
+-
+-File: libc.info, Node: String and Array Utilities, Next: Extended
Characters, Prev: Character Handling, Up: Top
+-
+-String and Array Utilities
+-**************************
+-
+- Operations on strings (or arrays of characters) are an important
+-part of many programs. The GNU C library provides an extensive set of
+-string utility functions, including functions for copying,
+-concatenating, comparing, and searching strings. Many of these
+-functions can also operate on arbitrary regions of storage; for
+-example, the `memcpy' function can be used to copy the contents of any
+-kind of array.
+-
+- It's fairly common for beginning C programmers to "reinvent the
+-wheel" by duplicating this functionality in their own code, but it pays
+-to become familiar with the library functions and to make use of them,
+-since this offers benefits in maintenance, efficiency, and portability.
+-
+- For instance, you could easily compare one string to another in two
+-lines of C code, but if you use the built-in `strcmp' function, you're
+-less likely to make a mistake. And, since these library functions are
+-typically highly optimized, your program may run faster too.
+-
+-* Menu:
+-
+-* Representation of Strings:: Introduction to basic concepts.
+-* String/Array Conventions:: Whether to use a string function or an
+- arbitrary array function.
+-* String Length:: Determining the length of a string.
+-* Copying and Concatenation:: Functions to copy the contents of strings
+- and arrays.
+-* String/Array Comparison:: Functions for byte-wise and character-wise
+- comparison.
+-* Collation Functions:: Functions for collating strings.
+-* Search Functions:: Searching for a specific element or substring.
+-* Finding Tokens in a String:: Splitting a string into tokens by looking
+- for delimiters.
+-
+-
+-File: libc.info, Node: Representation of Strings, Next: String/Array
Conventions, Up: String and Array Utilities
+-
+-Representation of Strings
+-=========================
+-
+- This section is a quick summary of string concepts for beginning C
+-programmers. It describes how character strings are represented in C
+-and some common pitfalls. If you are already familiar with this
+-material, you can skip this section.
+-
+- A "string" is an array of `char' objects. But string-valued
+-variables are usually declared to be pointers of type `char *'. Such
+-variables do not include space for the text of a string; that has to be
+-stored somewhere else--in an array variable, a string constant, or
+-dynamically allocated memory (*note Memory Allocation::.). It's up to
+-you to store the address of the chosen memory space into the pointer
+-variable. Alternatively you can store a "null pointer" in the pointer
+-variable. The null pointer does not point anywhere, so attempting to
+-reference the string it points to gets an error.
+-
+- By convention, a "null character", `'\0'', marks the end of a
+-string. For example, in testing to see whether the `char *' variable P
+-points to a null character marking the end of a string, you can write
+-`!*P' or `*P == '\0''.
+-
+- A null character is quite different conceptually from a null pointer,
+-although both are represented by the integer `0'.
+-
+- "String literals" appear in C program source as strings of
+-characters between double-quote characters (`"'). In ISO C, string
+-literals can also be formed by "string concatenation": `"a" "b"' is the
+-same as `"ab"'. Modification of string literals is not allowed by the
+-GNU C compiler, because literals are placed in read-only storage.
+-
+- Character arrays that are declared `const' cannot be modified
+-either. It's generally good style to declare non-modifiable string
+-pointers to be of type `const char *', since this often allows the C
+-compiler to detect accidental modifications as well as providing some
+-amount of documentation about what your program intends to do with the
+-string.
+-
+- The amount of memory allocated for the character array may extend
+-past the null character that normally marks the end of the string. In
+-this document, the term "allocation size" is always used to refer to the
+-total amount of memory allocated for the string, while the term
+-"length" refers to the number of characters up to (but not including)
+-the terminating null character.
+-
+- A notorious source of program bugs is trying to put more characters
+-in a string than fit in its allocated size. When writing code that
+-extends strings or moves characters into a pre-allocated array, you
+-should be very careful to keep track of the length of the text and make
+-explicit checks for overflowing the array. Many of the library
+-functions *do not* do this for you! Remember also that you need to
+-allocate an extra byte to hold the null character that marks the end of
+-the string.
+-
+-
+-File: libc.info, Node: String/Array Conventions, Next: String Length,
Prev: Representation of Strings, Up: String and Array Utilities
+-
+-String and Array Conventions
+-============================
+-
+- This chapter describes both functions that work on arbitrary arrays
+-or blocks of memory, and functions that are specific to null-terminated
+-arrays of characters.
+-
+- Functions that operate on arbitrary blocks of memory have names
+-beginning with `mem' (such as `memcpy') and invariably take an argument
+-which specifies the size (in bytes) of the block of memory to operate
+-on. The array arguments and return values for these functions have
+-type `void *', and as a matter of style, the elements of these arrays
+-are referred to as "bytes". You can pass any kind of pointer to these
+-functions, and the `sizeof' operator is useful in computing the value
+-for the size argument.
+-
+- In contrast, functions that operate specifically on strings have
+-names beginning with `str' (such as `strcpy') and look for a null
+-character to terminate the string instead of requiring an explicit size
+-argument to be passed. (Some of these functions accept a specified
+-maximum length, but they also check for premature termination with a
+-null character.) The array arguments and return values for these
+-functions have type `char *', and the array elements are referred to as
+-"characters".
+-
+- In many cases, there are both `mem' and `str' versions of a
+-function. The one that is more appropriate to use depends on the exact
+-situation. When your program is manipulating arbitrary arrays or
+-blocks of storage, then you should always use the `mem' functions. On
+-the other hand, when you are manipulating null-terminated strings it is
+-usually more convenient to use the `str' functions, unless you already
+-know the length of the string in advance.
+-
+-
+-File: libc.info, Node: String Length, Next: Copying and Concatenation,
Prev: String/Array Conventions, Up: String and Array Utilities
+-
+-String Length
+-=============
+-
+- You can get the length of a string using the `strlen' function.
+-This function is declared in the header file `string.h'.
+-
+- - Function: size_t strlen (const char *S)
+- The `strlen' function returns the length of the null-terminated
+- string S. (In other words, it returns the offset of the
+- terminating null character within the array.)
+-
+- For example,
+- strlen ("hello, world")
+- => 12
+-
+- When applied to a character array, the `strlen' function returns
+- the length of the string stored there, not its allocation size.
+- You can get the allocation size of the character array that holds
+- a string using the `sizeof' operator:
+-
+- char string[32] = "hello, world";
+- sizeof (string)
+- => 32
+- strlen (string)
+- => 12
+-
+-
+-File: libc.info, Node: Copying and Concatenation, Next: String/Array
Comparison, Prev: String Length, Up: String and Array Utilities
+-
+-Copying and Concatenation
+-=========================
+-
+- You can use the functions described in this section to copy the
+-contents of strings and arrays, or to append the contents of one string
+-to another. These functions are declared in the header file `string.h'.
+-
+- A helpful way to remember the ordering of the arguments to the
+-functions in this section is that it corresponds to an assignment
+-expression, with the destination array specified to the left of the
+-source array. All of these functions return the address of the
+-destination array.
+-
+- Most of these functions do not work properly if the source and
+-destination arrays overlap. For example, if the beginning of the
+-destination array overlaps the end of the source array, the original
+-contents of that part of the source array may get overwritten before it
+-is copied. Even worse, in the case of the string functions, the null
+-character marking the end of the string may be lost, and the copy
+-function might get stuck in a loop trashing all the memory allocated to
+-your program.
+-
+- All functions that have problems copying between overlapping arrays
+-are explicitly identified in this manual. In addition to functions in
+-this section, there are a few others like `sprintf' (*note Formatted
+-Output Functions::.) and `scanf' (*note Formatted Input Functions::.).
+-
+- - Function: void * memcpy (void *TO, const void *FROM, size_t SIZE)
+- The `memcpy' function copies SIZE bytes from the object beginning
+- at FROM into the object beginning at TO. The behavior of this
+- function is undefined if the two arrays TO and FROM overlap; use
+- `memmove' instead if overlapping is possible.
+-
+- The value returned by `memcpy' is the value of TO.
+-
+- Here is an example of how you might use `memcpy' to copy the
+- contents of an array:
+-
+- struct foo *oldarray, *newarray;
+- int arraysize;
+- ...
+- memcpy (new, old, arraysize * sizeof (struct foo));
+-
+- - Function: void * memmove (void *TO, const void *FROM, size_t SIZE)
+- `memmove' copies the SIZE bytes at FROM into the SIZE bytes at TO,
+- even if those two blocks of space overlap. In the case of
+- overlap, `memmove' is careful to copy the original values of the
+- bytes in the block at FROM, including those bytes which also
+- belong to the block at TO.
+-
+- - Function: void * memccpy (void *TO, const void *FROM, int C, size_t
+- SIZE)
+- This function copies no more than SIZE bytes from FROM to TO,
+- stopping if a byte matching C is found. The return value is a
+- pointer into TO one byte past where C was copied, or a null
+- pointer if no byte matching C appeared in the first SIZE bytes of
+- FROM.
+-
+- - Function: void * memset (void *BLOCK, int C, size_t SIZE)
+- This function copies the value of C (converted to an `unsigned
+- char') into each of the first SIZE bytes of the object beginning
+- at BLOCK. It returns the value of BLOCK.
+-
+- - Function: char * strcpy (char *TO, const char *FROM)
+- This copies characters from the string FROM (up to and including
+- the terminating null character) into the string TO. Like
+- `memcpy', this function has undefined results if the strings
+- overlap. The return value is the value of TO.
+-
+- - Function: char * strncpy (char *TO, const char *FROM, size_t SIZE)
+- This function is similar to `strcpy' but always copies exactly
+- SIZE characters into TO.
+-
+- If the length of FROM is more than SIZE, then `strncpy' copies
+- just the first SIZE characters. Note that in this case there is
+- no null terminator written into TO.
+-
+- If the length of FROM is less than SIZE, then `strncpy' copies all
+- of FROM, followed by enough null characters to add up to SIZE
+- characters in all. This behavior is rarely useful, but it is
+- specified by the ISO C standard.
+-
+- The behavior of `strncpy' is undefined if the strings overlap.
+-
+- Using `strncpy' as opposed to `strcpy' is a way to avoid bugs
+- relating to writing past the end of the allocated space for TO.
+- However, it can also make your program much slower in one common
+- case: copying a string which is probably small into a potentially
+- large buffer. In this case, SIZE may be large, and when it is,
+- `strncpy' will waste a considerable amount of time copying null
+- characters.
+-
+- - Function: char * strdup (const char *S)
+- This function copies the null-terminated string S into a newly
+- allocated string. The string is allocated using `malloc'; see
+- *Note Unconstrained Allocation::. If `malloc' cannot allocate
+- space for the new string, `strdup' returns a null pointer.
+- Otherwise it returns a pointer to the new string.
+-
+- - Function: char * strndup (const char *S, size_t SIZE)
+- This function is similar to `strdup' but always copies at most
+- SIZE characters into the newly allocated string.
+-
+- If the length of S is more than SIZE, then `strndup' copies just
+- the first SIZE characters and adds a closing null terminator.
+- Otherwise all characters are copied and the string is terminated.
+-
+- This function is different to `strncpy' in that it always
+- terminates the destination string.
+-
+- - Function: char * stpcpy (char *TO, const char *FROM)
+- This function is like `strcpy', except that it returns a pointer to
+- the end of the string TO (that is, the address of the terminating
+- null character) rather than the beginning.
+-
+- For example, this program uses `stpcpy' to concatenate `foo' and
+- `bar' to produce `foobar', which it then prints.
+-
+- #include <string.h>
+- #include <stdio.h>
+-
+- int
+- main (void)
+- {
+- char buffer[10];
+- char *to = buffer;
+- to = stpcpy (to, "foo");
+- to = stpcpy (to, "bar");
+- puts (buffer);
+- return 0;
+- }
+-
+- This function is not part of the ISO or POSIX standards, and is not
+- customary on Unix systems, but we did not invent it either.
+- Perhaps it comes from MS-DOG.
+-
+- Its behavior is undefined if the strings overlap.
+-
+- - Function: char * stpncpy (char *TO, const char *FROM, size_t SIZE)
+- This function is similar to `stpcpy' but copies always exactly
+- SIZE characters into TO.
+-
+- If the length of FROM is more then SIZE, then `stpncpy' copies
+- just the first SIZE characters and returns a pointer to the
+- character directly following the one which was copied last. Note
+- that in this case there is no null terminator written into TO.
+-
+- If the length of FROM is less than SIZE, then `stpncpy' copies all
+- of FROM, followed by enough null characters to add up to SIZE
+- characters in all. This behaviour is rarely useful, but it is
+- implemented to be useful in contexts where this behaviour of the
+- `strncpy' is used. `stpncpy' returns a pointer to the *first*
+- written null character.
+-
+- This function is not part of ISO or POSIX but was found useful
+- while developing GNU C Library itself.
+-
+- Its behaviour is undefined if the strings overlap.
+-
+- - Function: char * strdupa (const char *S)
+- This function is similar to `strdup' but allocates the new string
+- using `alloca' instead of `malloc' *note Variable Size
+- Automatic::.. This means of course the returned string has the
+- same limitations as any block of memory allocated using `alloca'.
+-
+- For obvious reasons `strdupa' is implemented only as a macro.
+- I.e., you cannot get the address of this function. Despite this
+- limitations it is a useful function. The following code shows a
+- situation where using `malloc' would be a lot more expensive.
+-
+- #include <paths.h>
+- #include <string.h>
+- #include <stdio.h>
+-
+- const char path[] = _PATH_STDPATH;
+-
+- int
+- main (void)
+- {
+- char *wr_path = strdupa (path);
+- char *cp = strtok (wr_path, ":");
+-
+- while (cp != NULL)
+- {
+- puts (cp);
+- cp = strtok (NULL, ":");
+- }
+- return 0;
+- }
+-
+- Please note that calling `strtok' using PATH directly is illegal.
+-
+- This function is only available if GNU CC is used.
+-
+- - Function: char * strndupa (const char *S, size_t SIZE)
+- This function is similar to `strndup' but like `strdupa' it
+- allocates the new string using `alloca' *note Variable Size
+- Automatic::.. The same advantages and limitations of `strdupa'
+- are valid for `strndupa', too.
+-
+- This function is implemented only as a macro which means one cannot
+- get the address of it.
+-
+- `strndupa' is only available if GNU CC is used.
+-
+- - Function: char * strcat (char *TO, const char *FROM)
+- The `strcat' function is similar to `strcpy', except that the
+- characters from FROM are concatenated or appended to the end of
+- TO, instead of overwriting it. That is, the first character from
+- FROM overwrites the null character marking the end of TO.
+-
+- An equivalent definition for `strcat' would be:
+-
+- char *
+- strcat (char *to, const char *from)
+- {
+- strcpy (to + strlen (to), from);
+- return to;
+- }
+-
+- This function has undefined results if the strings overlap.
+-
+- - Function: char * strncat (char *TO, const char *FROM, size_t SIZE)
+- This function is like `strcat' except that not more than SIZE
+- characters from FROM are appended to the end of TO. A single null
+- character is also always appended to TO, so the total allocated
+- size of TO must be at least `SIZE + 1' bytes longer than its
+- initial length.
+-
+- The `strncat' function could be implemented like this:
+-
+- char *
+- strncat (char *to, const char *from, size_t size)
+- {
+- strncpy (to + strlen (to), from, size);
+- return to;
+- }
+-
+- The behavior of `strncat' is undefined if the strings overlap.
+-
+- Here is an example showing the use of `strncpy' and `strncat'.
+-Notice how, in the call to `strncat', the SIZE parameter is computed to
+-avoid overflowing the character array `buffer'.
+-
+- #include <string.h>
+- #include <stdio.h>
+-
+- #define SIZE 10
+-
+- static char buffer[SIZE];
+-
+- main ()
+- {
+- strncpy (buffer, "hello", SIZE);
+- puts (buffer);
+- strncat (buffer, ", world", SIZE - strlen (buffer) - 1);
+- puts (buffer);
+- }
+-
+-The output produced by this program looks like:
+-
+- hello
+- hello, wo
+-
+- - Function: void * bcopy (void *FROM, const void *TO, size_t SIZE)
+- This is a partially obsolete alternative for `memmove', derived
+- from BSD. Note that it is not quite equivalent to `memmove',
+- because the arguments are not in the same order.
+-
+- - Function: void * bzero (void *BLOCK, size_t SIZE)
+- This is a partially obsolete alternative for `memset', derived from
+- BSD. Note that it is not as general as `memset', because the only
+- value it can store is zero.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-5
glibc-2.0.1/manual/libc.info-5
+--- ../glibc-2.0.1/manual/libc.info-5 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-5 1970-01-01 01:00:00.000000000 +0100
+@@ -1,1049 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+- This file documents the GNU C library.
+-
+- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+- Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+- Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+- Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: String/Array Comparison, Next: Collation Functions,
Prev: Copying and Concatenation, Up: String and Array Utilities
+-
+-String/Array Comparison
+-=======================
+-
+- You can use the functions in this section to perform comparisons on
+-the contents of strings and arrays. As well as checking for equality,
+-these functions can also be used as the ordering functions for sorting
+-operations. *Note Searching and Sorting::, for an example of this.
+-
+- Unlike most comparison operations in C, the string comparison
+-functions return a nonzero value if the strings are *not* equivalent
+-rather than if they are. The sign of the value indicates the relative
+-ordering of the first characters in the strings that are not
+-equivalent: a negative value indicates that the first string is "less"
+-than the second, while a positive value indicates that the first string
+-is "greater".
+-
+- The most common use of these functions is to check only for equality.
+-This is canonically done with an expression like `! strcmp (s1, s2)'.
+-
+- All of these functions are declared in the header file `string.h'.
+-
+- - Function: int memcmp (const void *A1, const void *A2, size_t SIZE)
+- The function `memcmp' compares the SIZE bytes of memory beginning
+- at A1 against the SIZE bytes of memory beginning at A2. The value
+- returned has the same sign as the difference between the first
+- differing pair of bytes (interpreted as `unsigned char' objects,
+- then promoted to `int').
+-
+- If the contents of the two blocks are equal, `memcmp' returns `0'.
+-
+- On arbitrary arrays, the `memcmp' function is mostly useful for
+-testing equality. It usually isn't meaningful to do byte-wise ordering
+-comparisons on arrays of things other than bytes. For example, a
+-byte-wise comparison on the bytes that make up floating-point numbers
+-isn't likely to tell you anything about the relationship between the
+-values of the floating-point numbers.
+-
+- You should also be careful about using `memcmp' to compare objects
+-that can contain "holes", such as the padding inserted into structure
+-objects to enforce alignment requirements, extra space at the end of
+-unions, and extra characters at the ends of strings whose length is less
+-than their allocated size. The contents of these "holes" are
+-indeterminate and may cause strange behavior when performing byte-wise
+-comparisons. For more predictable results, perform an explicit
+-component-wise comparison.
+-
+- For example, given a structure type definition like:
+-
+- struct foo
+- {
+- unsigned char tag;
+- union
+- {
+- double f;
+- long i;
+- char *p;
+- } value;
+- };
+-
+-you are better off writing a specialized comparison function to compare
+-`struct foo' objects instead of comparing them with `memcmp'.
+-
+- - Function: int strcmp (const char *S1, const char *S2)
+- The `strcmp' function compares the string S1 against S2, returning
+- a value that has the same sign as the difference between the first
+- differing pair of characters (interpreted as `unsigned char'
+- objects, then promoted to `int').
+-
+- If the two strings are equal, `strcmp' returns `0'.
+-
+- A consequence of the ordering used by `strcmp' is that if S1 is an
+- initial substring of S2, then S1 is considered to be "less than"
+- S2.
+-
+- - Function: int strcasecmp (const char *S1, const char *S2)
+- This function is like `strcmp', except that differences in case
+- are ignored.
+-
+- `strcasecmp' is derived from BSD.
+-
+- - Function: int strncasecmp (const char *S1, const char *S2, size_t N)
+- This function is like `strncmp', except that differences in case
+- are ignored.
+-
+- `strncasecmp' is a GNU extension.
+-
+- - Function: int strncmp (const char *S1, const char *S2, size_t SIZE)
+- This function is the similar to `strcmp', except that no more than
+- SIZE characters are compared. In other words, if the two strings
+- are the same in their first SIZE characters, the return value is
+- zero.
+-
+- Here are some examples showing the use of `strcmp' and `strncmp'.
+-These examples assume the use of the ASCII character set. (If some
+-other character set--say, EBCDIC--is used instead, then the glyphs are
+-associated with different numeric codes, and the return values and
+-ordering may differ.)
+-
+- strcmp ("hello", "hello")
+- => 0 /* These two strings are the same. */
+- strcmp ("hello", "Hello")
+- => 32 /* Comparisons are case-sensitive. */
+- strcmp ("hello", "world")
+- => -15 /* The character `'h'' comes before `'w''. */
+- strcmp ("hello", "hello, world")
+- => -44 /* Comparing a null character against a comma. */
+- strncmp ("hello", "hello, world"", 5)
+- => 0 /* The initial 5 characters are the same. */
+- strncmp ("hello, world", "hello, stupid world!!!", 5)
+- => 0 /* The initial 5 characters are the same. */
+-
+- - Function: int bcmp (const void *A1, const void *A2, size_t SIZE)
+- This is an obsolete alias for `memcmp', derived from BSD.
+-
+-
+-File: libc.info, Node: Collation Functions, Next: Search Functions, Prev:
String/Array Comparison, Up: String and Array Utilities
+-
+-Collation Functions
+-===================
+-
+- In some locales, the conventions for lexicographic ordering differ
+-from the strict numeric ordering of character codes. For example, in
+-Spanish most glyphs with diacritical marks such as accents are not
+-considered distinct letters for the purposes of collation. On the
+-other hand, the two-character sequence `ll' is treated as a single
+-letter that is collated immediately after `l'.
+-
+- You can use the functions `strcoll' and `strxfrm' (declared in the
+-header file `string.h') to compare strings using a collation ordering
+-appropriate for the current locale. The locale used by these functions
+-in particular can be specified by setting the locale for the
+-`LC_COLLATE' category; see *Note Locales::.
+-
+- In the standard C locale, the collation sequence for `strcoll' is
+-the same as that for `strcmp'.
+-
+- Effectively, the way these functions work is by applying a mapping to
+-transform the characters in a string to a byte sequence that represents
+-the string's position in the collating sequence of the current locale.
+-Comparing two such byte sequences in a simple fashion is equivalent to
+-comparing the strings with the locale's collating sequence.
+-
+- The function `strcoll' performs this translation implicitly, in
+-order to do one comparison. By contrast, `strxfrm' performs the
+-mapping explicitly. If you are making multiple comparisons using the
+-same string or set of strings, it is likely to be more efficient to use
+-`strxfrm' to transform all the strings just once, and subsequently
+-compare the transformed strings with `strcmp'.
+-
+- - Function: int strcoll (const char *S1, const char *S2)
+- The `strcoll' function is similar to `strcmp' but uses the
+- collating sequence of the current locale for collation (the
+- `LC_COLLATE' locale).
+-
+- Here is an example of sorting an array of strings, using `strcoll'
+-to compare them. The actual sort algorithm is not written here; it
+-comes from `qsort' (*note Array Sort Function::.). The job of the code
+-shown here is to say how to compare the strings while sorting them.
+-(Later on in this section, we will show a way to do this more
+-efficiently using `strxfrm'.)
+-
+- /* This is the comparison function used with `qsort'. */
+-
+- int
+- compare_elements (char **p1, char **p2)
+- {
+- return strcoll (*p1, *p2);
+- }
+-
+- /* This is the entry point--the function to sort
+- strings using the locale's collating sequence. */
+-
+- void
+- sort_strings (char **array, int nstrings)
+- {
+- /* Sort `temp_array' by comparing the strings. */
+- qsort (array, sizeof (char *),
+- nstrings, compare_elements);
+- }
+-
+- - Function: size_t strxfrm (char *TO, const char *FROM, size_t SIZE)
+- The function `strxfrm' transforms STRING using the collation
+- transformation determined by the locale currently selected for
+- collation, and stores the transformed string in the array TO. Up
+- to SIZE characters (including a terminating null character) are
+- stored.
+-
+- The behavior is undefined if the strings TO and FROM overlap; see
+- *Note Copying and Concatenation::.
+-
+- The return value is the length of the entire transformed string.
+- This value is not affected by the value of SIZE, but if it is
+- greater or equal than SIZE, it means that the transformed string
+- did not entirely fit in the array TO. In this case, only as much
+- of the string as actually fits was stored. To get the whole
+- transformed string, call `strxfrm' again with a bigger output
+- array.
+-
+- The transformed string may be longer than the original string, and
+- it may also be shorter.
+-
+- If SIZE is zero, no characters are stored in TO. In this case,
+- `strxfrm' simply returns the number of characters that would be
+- the length of the transformed string. This is useful for
+- determining what size string to allocate. It does not matter what
+- TO is if SIZE is zero; TO may even be a null pointer.
+-
+- Here is an example of how you can use `strxfrm' when you plan to do
+-many comparisons. It does the same thing as the previous example, but
+-much faster, because it has to transform each string only once, no
+-matter how many times it is compared with other strings. Even the time
+-needed to allocate and free storage is much less than the time we save,
+-when there are many strings.
+-
+- struct sorter { char *input; char *transformed; };
+-
+- /* This is the comparison function used with `qsort'
+- to sort an array of `struct sorter'. */
+-
+- int
+- compare_elements (struct sorter *p1, struct sorter *p2)
+- {
+- return strcmp (p1->transformed, p2->transformed);
+- }
+-
+- /* This is the entry point--the function to sort
+- strings using the locale's collating sequence. */
+-
+- void
+- sort_strings_fast (char **array, int nstrings)
+- {
+- struct sorter temp_array[nstrings];
+- int i;
+-
+- /* Set up `temp_array'. Each element contains
+- one input string and its transformed string. */
+- for (i = 0; i < nstrings; i++)
+- {
+- size_t length = strlen (array[i]) * 2;
+- char *transformed;
+- size_t transformed_lenght;
+-
+- temp_array[i].input = array[i];
+-
+- /* First try a buffer perhaps big enough. */
+- transformed = (char *) xmalloc (length);
+-
+- /* Transform `array[i]'. */
+- transformed_length = strxfrm (transformed, array[i], length);
+-
+- /* If the buffer was not large enough, resize it
+- and try again. */
+- if (transformed_length >= length)
+- {
+- /* Allocate the needed space. +1 for terminating
+- `NUL' character. */
+- transformed = (char *) xrealloc (transformed,
+- transformed_length + 1);
+-
+- /* The return value is not interesting because we know
+- how long the transformed string is. */
+- (void) strxfrm (transformed, array[i], transformed_length + 1);
+- }
+-
+- temp_array[i].transformed = transformed;
+- }
+-
+- /* Sort `temp_array' by comparing transformed strings. */
+- qsort (temp_array, sizeof (struct sorter),
+- nstrings, compare_elements);
+-
+- /* Put the elements back in the permanent array
+- in their sorted order. */
+- for (i = 0; i < nstrings; i++)
+- array[i] = temp_array[i].input;
+-
+- /* Free the strings we allocated. */
+- for (i = 0; i < nstrings; i++)
+- free (temp_array[i].transformed);
+- }
+-
+- *Compatibility Note:* The string collation functions are a new
+-feature of ISO C. Older C dialects have no equivalent feature.
+-
+-
+-File: libc.info, Node: Search Functions, Next: Finding Tokens in a String,
Prev: Collation Functions, Up: String and Array Utilities
+-
+-Search Functions
+-================
+-
+- This section describes library functions which perform various kinds
+-of searching operations on strings and arrays. These functions are
+-declared in the header file `string.h'.
+-
+- - Function: void * memchr (const void *BLOCK, int C, size_t SIZE)
+- This function finds the first occurrence of the byte C (converted
+- to an `unsigned char') in the initial SIZE bytes of the object
+- beginning at BLOCK. The return value is a pointer to the located
+- byte, or a null pointer if no match was found.
+-
+- - Function: char * strchr (const char *STRING, int C)
+- The `strchr' function finds the first occurrence of the character
+- C (converted to a `char') in the null-terminated string beginning
+- at STRING. The return value is a pointer to the located
+- character, or a null pointer if no match was found.
+-
+- For example,
+- strchr ("hello, world", 'l')
+- => "llo, world"
+- strchr ("hello, world", '?')
+- => NULL
+-
+- The terminating null character is considered to be part of the
+- string, so you can use this function get a pointer to the end of a
+- string by specifying a null character as the value of the C
+- argument.
+-
+- - Function: char * index (const char *STRING, int C)
+- `index' is another name for `strchr'; they are exactly the same.
+-
+- - Function: char * strrchr (const char *STRING, int C)
+- The function `strrchr' is like `strchr', except that it searches
+- backwards from the end of the string STRING (instead of forwards
+- from the front).
+-
+- For example,
+- strrchr ("hello, world", 'l')
+- => "ld"
+-
+- - Function: char * rindex (const char *STRING, int C)
+- `rindex' is another name for `strrchr'; they are exactly the same.
+-
+- - Function: char * strstr (const char *HAYSTACK, const char *NEEDLE)
+- This is like `strchr', except that it searches HAYSTACK for a
+- substring NEEDLE rather than just a single character. It returns
+- a pointer into the string HAYSTACK that is the first character of
+- the substring, or a null pointer if no match was found. If NEEDLE
+- is an empty string, the function returns HAYSTACK.
+-
+- For example,
+- strstr ("hello, world", "l")
+- => "llo, world"
+- strstr ("hello, world", "wo")
+- => "world"
+-
+- - Function: void * memmem (const void *NEEDLE, size_t NEEDLE-LEN,
+- const void *HAYSTACK, size_t HAYSTACK-LEN)
+- This is like `strstr', but NEEDLE and HAYSTACK are byte arrays
+- rather than null-terminated strings. NEEDLE-LEN is the length of
+- NEEDLE and HAYSTACK-LEN is the length of HAYSTACK.
+-
+- This function is a GNU extension.
+-
+- - Function: size_t strspn (const char *STRING, const char *SKIPSET)
+- The `strspn' ("string span") function returns the length of the
+- initial substring of STRING that consists entirely of characters
+- that are members of the set specified by the string SKIPSET. The
+- order of the characters in SKIPSET is not important.
+-
+- For example,
+- strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")
+- => 5
+-
+- - Function: size_t strcspn (const char *STRING, const char *STOPSET)
+- The `strcspn' ("string complement span") function returns the
+- length of the initial substring of STRING that consists entirely
+- of characters that are *not* members of the set specified by the
+- string STOPSET. (In other words, it returns the offset of the
+- first character in STRING that is a member of the set STOPSET.)
+-
+- For example,
+- strcspn ("hello, world", " \t\n,.;!?")
+- => 5
+-
+- - Function: char * strpbrk (const char *STRING, const char *STOPSET)
+- The `strpbrk' ("string pointer break") function is related to
+- `strcspn', except that it returns a pointer to the first character
+- in STRING that is a member of the set STOPSET instead of the
+- length of the initial substring. It returns a null pointer if no
+- such character from STOPSET is found.
+-
+- For example,
+-
+- strpbrk ("hello, world", " \t\n,.;!?")
+- => ", world"
+-
+-
+-File: libc.info, Node: Finding Tokens in a String, Prev: Search Functions,
Up: String and Array Utilities
+-
+-Finding Tokens in a String
+-==========================
+-
+- It's fairly common for programs to have a need to do some simple
+-kinds of lexical analysis and parsing, such as splitting a command
+-string up into tokens. You can do this with the `strtok' function,
+-declared in the header file `string.h'.
+-
+- - Function: char * strtok (char *NEWSTRING, const char *DELIMITERS)
+- A string can be split into tokens by making a series of calls to
+- the function `strtok'.
+-
+- The string to be split up is passed as the NEWSTRING argument on
+- the first call only. The `strtok' function uses this to set up
+- some internal state information. Subsequent calls to get
+- additional tokens from the same string are indicated by passing a
+- null pointer as the NEWSTRING argument. Calling `strtok' with
+- another non-null NEWSTRING argument reinitializes the state
+- information. It is guaranteed that no other library function ever
+- calls `strtok' behind your back (which would mess up this internal
+- state information).
+-
+- The DELIMITERS argument is a string that specifies a set of
+- delimiters that may surround the token being extracted. All the
+- initial characters that are members of this set are discarded.
+- The first character that is *not* a member of this set of
+- delimiters marks the beginning of the next token. The end of the
+- token is found by looking for the next character that is a member
+- of the delimiter set. This character in the original string
+- NEWSTRING is overwritten by a null character, and the pointer to
+- the beginning of the token in NEWSTRING is returned.
+-
+- On the next call to `strtok', the searching begins at the next
+- character beyond the one that marked the end of the previous token.
+- Note that the set of delimiters DELIMITERS do not have to be the
+- same on every call in a series of calls to `strtok'.
+-
+- If the end of the string NEWSTRING is reached, or if the remainder
+- of string consists only of delimiter characters, `strtok' returns
+- a null pointer.
+-
+- *Warning:* Since `strtok' alters the string it is parsing, you
+-always copy the string to a temporary buffer before parsing it with
+-`strtok'. If you allow `strtok' to modify a string that came from
+-another part of your program, you are asking for trouble; that string
+-may be part of a data structure that could be used for other purposes
+-during the parsing, when alteration by `strtok' makes the data
+-structure temporarily inaccurate.
+-
+- The string that you are operating on might even be a constant. Then
+-when `strtok' tries to modify it, your program will get a fatal signal
+-for writing in read-only memory. *Note Program Error Signals::.
+-
+- This is a special case of a general principle: if a part of a program
+-does not have as its purpose the modification of a certain data
+-structure, then it is error-prone to modify the data structure
+-temporarily.
+-
+- The function `strtok' is not reentrant. *Note Nonreentrancy::, for
+-a discussion of where and why reentrancy is important.
+-
+- Here is a simple example showing the use of `strtok'.
+-
+- #include <string.h>
+- #include <stddef.h>
+-
+- ...
+-
+- char string[] = "words separated by spaces -- and, punctuation!";
+- const char delimiters[] = " .,;:!-";
+- char *token;
+-
+- ...
+-
+- token = strtok (string, delimiters); /* token => "words" */
+- token = strtok (NULL, delimiters); /* token => "separated" */
+- token = strtok (NULL, delimiters); /* token => "by" */
+- token = strtok (NULL, delimiters); /* token => "spaces" */
+- token = strtok (NULL, delimiters); /* token => "and" */
+- token = strtok (NULL, delimiters); /* token => "punctuation" */
+- token = strtok (NULL, delimiters); /* token => NULL */
+-
+- The GNU C library contains two more functions for tokenizing a string
+-which overcome the limitation of non-reentrancy.
+-
+- - Function: char * strtok_r (char *NEWSTRING, const char *DELIMITERS,
+- char **SAVE_PTR)
+- Just like `strtok' this function splits the string into several
+- tokens which can be accessed be successive calls to `strtok_r'.
+- The difference is that the information about the next token is not
+- set up in some internal state information. Instead the caller has
+- to provide another argument SAVE_PTR which is a pointer to a string
+- pointer. Calling `strtok_r' with a null pointer for NEWSTRING and
+- leaving SAVE_PTR between the calls unchanged does the job without
+- limiting reentrancy.
+-
+- This function was proposed for POSIX.1b and can be found on many
+- systems which support multi-threading.
+-
+- - Function: char * strsep (char **STRING_PTR, const char *DELIMITER)
+- A second reentrant approach is to avoid the additional first
+- argument. The initialization of the moving pointer has to be done
+- by the user. Successive calls of `strsep' move the pointer along
+- the tokens separated by DELIMITER, returning the address of the
+- next token and updating STRING_PTR to point to the beginning of
+- the next token.
+-
+- This function was introduced in 4.3BSD and therefore is widely
+- available.
+-
+- Here is how the above example looks like when `strsep' is used.
+-
+- #include <string.h>
+- #include <stddef.h>
+-
+- ...
+-
+- char string[] = "words separated by spaces -- and, punctuation!";
+- const char delimiters[] = " .,;:!-";
+- char *running;
+- char *token;
+-
+- ...
+-
+- running = string;
+- token = strsep (&running, delimiters); /* token => "words" */
+- token = strsep (&running, delimiters); /* token => "separated" */
+- token = strsep (&running, delimiters); /* token => "by" */
+- token = strsep (&running, delimiters); /* token => "spaces" */
+- token = strsep (&running, delimiters); /* token => "and" */
+- token = strsep (&running, delimiters); /* token => "punctuation" */
+- token = strsep (&running, delimiters); /* token => NULL */
+-
+-
+-File: libc.info, Node: I/O Overview, Next: I/O on Streams, Prev: Pattern
Matching, Up: Top
+-
+-Input/Output Overview
+-*********************
+-
+- Most programs need to do either input (reading data) or output
+-(writing data), or most frequently both, in order to do anything
+-useful. The GNU C library provides such a large selection of input and
+-output functions that the hardest part is often deciding which function
+-is most appropriate!
+-
+- This chapter introduces concepts and terminology relating to input
+-and output. Other chapters relating to the GNU I/O facilities are:
+-
+- * *Note I/O on Streams::, which covers the high-level functions that
+- operate on streams, including formatted input and output.
+-
+- * *Note Low-Level I/O::, which covers the basic I/O and control
+- functions on file descriptors.
+-
+- * *Note File System Interface::, which covers functions for
+- operating on directories and for manipulating file attributes such
+- as access modes and ownership.
+-
+- * *Note Pipes and FIFOs::, which includes information on the basic
+- interprocess communication facilities.
+-
+- * *Note Sockets::, which covers a more complicated interprocess
+- communication facility with support for networking.
+-
+- * *Note Low-Level Terminal Interface::, which covers functions for
+- changing how input and output to terminal or other serial devices
+- are processed.
+-
+-* Menu:
+-
+-* I/O Concepts:: Some basic information and terminology.
+-* File Names:: How to refer to a file.
+-
+-
+-File: libc.info, Node: I/O Concepts, Next: File Names, Up: I/O Overview
+-
+-Input/Output Concepts
+-=====================
+-
+- Before you can read or write the contents of a file, you must
+-establish a connection or communications channel to the file. This
+-process is called "opening" the file. You can open a file for reading,
+-writing, or both.
+-
+- The connection to an open file is represented either as a stream or
+-as a file descriptor. You pass this as an argument to the functions
+-that do the actual read or write operations, to tell them which file to
+-operate on. Certain functions expect streams, and others are designed
+-to operate on file descriptors.
+-
+- When you have finished reading to or writing from the file, you can
+-terminate the connection by "closing" the file. Once you have closed a
+-stream or file descriptor, you cannot do any more input or output
+-operations on it.
+-
+-* Menu:
+-
+-* Streams and File Descriptors:: The GNU Library provides two ways
+- to access the contents of files.
+-* File Position:: The number of bytes from the
+- beginning of the file.
+-
+-
+-File: libc.info, Node: Streams and File Descriptors, Next: File Position,
Up: I/O Concepts
+-
+-Streams and File Descriptors
+-----------------------------
+-
+- When you want to do input or output to a file, you have a choice of
+-two basic mechanisms for representing the connection between your
+-program and the file: file descriptors and streams. File descriptors
+-are represented as objects of type `int', while streams are represented
+-as `FILE *' objects.
+-
+- File descriptors provide a primitive, low-level interface to input
+-and output operations. Both file descriptors and streams can represent
+-a connection to a device (such as a terminal), or a pipe or socket for
+-communicating with another process, as well as a normal file. But, if
+-you want to do control operations that are specific to a particular kind
+-of device, you must use a file descriptor; there are no facilities to
+-use streams in this way. You must also use file descriptors if your
+-program needs to do input or output in special modes, such as
+-nonblocking (or polled) input (*note File Status Flags::.).
+-
+- Streams provide a higher-level interface, layered on top of the
+-primitive file descriptor facilities. The stream interface treats all
+-kinds of files pretty much alike--the sole exception being the three
+-styles of buffering that you can choose (*note Stream Buffering::.).
+-
+- The main advantage of using the stream interface is that the set of
+-functions for performing actual input and output operations (as opposed
+-to control operations) on streams is much richer and more powerful than
+-the corresponding facilities for file descriptors. The file descriptor
+-interface provides only simple functions for transferring blocks of
+-characters, but the stream interface also provides powerful formatted
+-input and output functions (`printf' and `scanf') as well as functions
+-for character- and line-oriented input and output.
+-
+- Since streams are implemented in terms of file descriptors, you can
+-extract the file descriptor from a stream and perform low-level
+-operations directly on the file descriptor. You can also initially open
+-a connection as a file descriptor and then make a stream associated with
+-that file descriptor.
+-
+- In general, you should stick with using streams rather than file
+-descriptors, unless there is some specific operation you want to do that
+-can only be done on a file descriptor. If you are a beginning
+-programmer and aren't sure what functions to use, we suggest that you
+-concentrate on the formatted input functions (*note Formatted Input::.)
+-and formatted output functions (*note Formatted Output::.).
+-
+- If you are concerned about portability of your programs to systems
+-other than GNU, you should also be aware that file descriptors are not
+-as portable as streams. You can expect any system running ISO C to
+-support streams, but non-GNU systems may not support file descriptors at
+-all, or may only implement a subset of the GNU functions that operate on
+-file descriptors. Most of the file descriptor functions in the GNU
+-library are included in the POSIX.1 standard, however.
+-
+-
+-File: libc.info, Node: File Position, Prev: Streams and File Descriptors,
Up: I/O Concepts
+-
+-File Position
+--------------
+-
+- One of the attributes of an open file is its "file position" that
+-keeps track of where in the file the next character is to be read or
+-written. In the GNU system, and all POSIX.1 systems, the file position
+-is simply an integer representing the number of bytes from the beginning
+-of the file.
+-
+- The file position is normally set to the beginning of the file when
+-it is opened, and each time a character is read or written, the file
+-position is incremented. In other words, access to the file is normally
+-"sequential".
+-
+- Ordinary files permit read or write operations at any position within
+-the file. Some other kinds of files may also permit this. Files which
+-do permit this are sometimes referred to as "random-access" files. You
+-can change the file position using the `fseek' function on a stream
+-(*note File Positioning::.) or the `lseek' function on a file
+-descriptor (*note I/O Primitives::.). If you try to change the file
+-position on a file that doesn't support random access, you get the
+-`ESPIPE' error.
+-
+- Streams and descriptors that are opened for "append access" are
+-treated specially for output: output to such files is *always* appended
+-sequentially to the *end* of the file, regardless of the file position.
+-However, the file position is still used to control where in the file
+-reading is done.
+-
+- If you think about it, you'll realize that several programs can read
+-a given file at the same time. In order for each program to be able to
+-read the file at its own pace, each program must have its own file
+-pointer, which is not affected by anything the other programs do.
+-
+- In fact, each opening of a file creates a separate file position.
+-Thus, if you open a file twice even in the same program, you get two
+-streams or descriptors with independent file positions.
+-
+- By contrast, if you open a descriptor and then duplicate it to get
+-another descriptor, these two descriptors share the same file position:
+-changing the file position of one descriptor will affect the other.
+-
+-
+-File: libc.info, Node: File Names, Prev: I/O Concepts, Up: I/O Overview
+-
+-File Names
+-==========
+-
+- In order to open a connection to a file, or to perform other
+-operations such as deleting a file, you need some way to refer to the
+-file. Nearly all files have names that are strings--even files which
+-are actually devices such as tape drives or terminals. These strings
+-are called "file names". You specify the file name to say which file
+-you want to open or operate on.
+-
+- This section describes the conventions for file names and how the
+-operating system works with them.
+-
+-* Menu:
+-
+-* Directories:: Directories contain entries for files.
+-* File Name Resolution:: A file name specifies how to look up a file.
+-* File Name Errors:: Error conditions relating to file names.
+-* File Name Portability:: File name portability and syntax issues.
+-
+-
+-File: libc.info, Node: Directories, Next: File Name Resolution, Up: File
Names
+-
+-Directories
+------------
+-
+- In order to understand the syntax of file names, you need to
+-understand how the file system is organized into a hierarchy of
+-directories.
+-
+- A "directory" is a file that contains information to associate other
+-files with names; these associations are called "links" or "directory
+-entries". Sometimes, people speak of "files in a directory", but in
+-reality, a directory only contains pointers to files, not the files
+-themselves.
+-
+- The name of a file contained in a directory entry is called a "file
+-name component". In general, a file name consists of a sequence of one
+-or more such components, separated by the slash character (`/'). A
+-file name which is just one component names a file with respect to its
+-directory. A file name with multiple components names a directory, and
+-then a file in that directory, and so on.
+-
+- Some other documents, such as the POSIX standard, use the term
+-"pathname" for what we call a file name, and either "filename" or
+-"pathname component" for what this manual calls a file name component.
+-We don't use this terminology because a "path" is something completely
+-different (a list of directories to search), and we think that
+-"pathname" used for something else will confuse users. We always use
+-"file name" and "file name component" (or sometimes just "component",
+-where the context is obvious) in GNU documentation. Some macros use
+-the POSIX terminology in their names, such as `PATH_MAX'. These macros
+-are defined by the POSIX standard, so we cannot change their names.
+-
+- You can find more detailed information about operations on
+-directories in *Note File System Interface::.
+-
+-
+-File: libc.info, Node: File Name Resolution, Next: File Name Errors, Prev:
Directories, Up: File Names
+-
+-File Name Resolution
+---------------------
+-
+- A file name consists of file name components separated by slash
+-(`/') characters. On the systems that the GNU C library supports,
+-multiple successive `/' characters are equivalent to a single `/'
+-character.
+-
+- The process of determining what file a file name refers to is called
+-"file name resolution". This is performed by examining the components
+-that make up a file name in left-to-right order, and locating each
+-successive component in the directory named by the previous component.
+-Of course, each of the files that are referenced as directories must
+-actually exist, be directories instead of regular files, and have the
+-appropriate permissions to be accessible by the process; otherwise the
+-file name resolution fails.
+-
+- If a file name begins with a `/', the first component in the file
+-name is located in the "root directory" of the process (usually all
+-processes on the system have the same root directory). Such a file name
+-is called an "absolute file name".
+-
+- Otherwise, the first component in the file name is located in the
+-current working directory (*note Working Directory::.). This kind of
+-file name is called a "relative file name".
+-
+- The file name components `.' ("dot") and `..' ("dot-dot") have
+-special meanings. Every directory has entries for these file name
+-components. The file name component `.' refers to the directory
+-itself, while the file name component `..' refers to its "parent
+-directory" (the directory that contains the link for the directory in
+-question). As a special case, `..' in the root directory refers to the
+-root directory itself, since it has no parent; thus `/..' is the same
+-as `/'.
+-
+- Here are some examples of file names:
+-
+-`/a'
+- The file named `a', in the root directory.
+-
+-`/a/b'
+- The file named `b', in the directory named `a' in the root
+- directory.
+-
+-`a'
+- The file named `a', in the current working directory.
+-
+-`/a/./b'
+- This is the same as `/a/b'.
+-
+-`./a'
+- The file named `a', in the current working directory.
+-
+-`../a'
+- The file named `a', in the parent directory of the current working
+- directory.
+-
+- A file name that names a directory may optionally end in a `/'. You
+-can specify a file name of `/' to refer to the root directory, but the
+-empty string is not a meaningful file name. If you want to refer to
+-the current working directory, use a file name of `.' or `./'.
+-
+- Unlike some other operating systems, the GNU system doesn't have any
+-built-in support for file types (or extensions) or file versions as part
+-of its file name syntax. Many programs and utilities use conventions
+-for file names--for example, files containing C source code usually
+-have names suffixed with `.c'--but there is nothing in the file system
+-itself that enforces this kind of convention.
+-
+-
+-File: libc.info, Node: File Name Errors, Next: File Name Portability,
Prev: File Name Resolution, Up: File Names
+-
+-File Name Errors
+-----------------
+-
+- Functions that accept file name arguments usually detect these
+-`errno' error conditions relating to the file name syntax or trouble
+-finding the named file. These errors are referred to throughout this
+-manual as the "usual file name errors".
+-
+-`EACCES'
+- The process does not have search permission for a directory
+- component of the file name.
+-
+-`ENAMETOOLONG'
+- This error is used when either the the total length of a file name
+- is greater than `PATH_MAX', or when an individual file name
+- component has a length greater than `NAME_MAX'. *Note Limits for
+- Files::.
+-
+- In the GNU system, there is no imposed limit on overall file name
+- length, but some file systems may place limits on the length of a
+- component.
+-
+-`ENOENT'
+- This error is reported when a file referenced as a directory
+- component in the file name doesn't exist, or when a component is a
+- symbolic link whose target file does not exist. *Note Symbolic
+- Links::.
+-
+-`ENOTDIR'
+- A file that is referenced as a directory component in the file name
+- exists, but it isn't a directory.
+-
+-`ELOOP'
+- Too many symbolic links were resolved while trying to look up the
+- file name. The system has an arbitrary limit on the number of
+- symbolic links that may be resolved in looking up a single file
+- name, as a primitive way to detect loops. *Note Symbolic Links::.
+-
+-
+-File: libc.info, Node: File Name Portability, Prev: File Name Errors, Up:
File Names
+-
+-Portability of File Names
+--------------------------
+-
+- The rules for the syntax of file names discussed in *Note File
+-Names::, are the rules normally used by the GNU system and by other
+-POSIX systems. However, other operating systems may use other
+-conventions.
+-
+- There are two reasons why it can be important for you to be aware of
+-file name portability issues:
+-
+- * If your program makes assumptions about file name syntax, or
+- contains embedded literal file name strings, it is more difficult
+- to get it to run under other operating systems that use different
+- syntax conventions.
+-
+- * Even if you are not concerned about running your program on
+- machines that run other operating systems, it may still be
+- possible to access files that use different naming conventions.
+- For example, you may be able to access file systems on another
+- computer running a different operating system over a network, or
+- read and write disks in formats used by other operating systems.
+-
+- The ISO C standard says very little about file name syntax, only that
+-file names are strings. In addition to varying restrictions on the
+-length of file names and what characters can validly appear in a file
+-name, different operating systems use different conventions and syntax
+-for concepts such as structured directories and file types or
+-extensions. Some concepts such as file versions might be supported in
+-some operating systems and not by others.
+-
+- The POSIX.1 standard allows implementations to put additional
+-restrictions on file name syntax, concerning what characters are
+-permitted in file names and on the length of file name and file name
+-component strings. However, in the GNU system, you do not need to worry
+-about these restrictions; any character except the null character is
+-permitted in a file name string, and there are no limits on the length
+-of file name strings.
+-
+-
+-File: libc.info, Node: I/O on Streams, Next: Low-Level I/O, Prev: I/O
Overview, Up: Top
+-
+-Input/Output on Streams
+-***********************
+-
+- This chapter describes the functions for creating streams and
+-performing input and output operations on them. As discussed in *Note
+-I/O Overview::, a stream is a fairly abstract, high-level concept
+-representing a communications channel to a file, device, or process.
+-
+-* Menu:
+-
+-* Streams:: About the data type representing a stream.
+-* Standard Streams:: Streams to the standard input and output
+- devices are created for you.
+-* Opening Streams:: How to create a stream to talk to a file.
+-* Closing Streams:: Close a stream when you are finished with it.
+-* Simple Output:: Unformatted output by characters and lines.
+-* Character Input:: Unformatted input by characters and words.
+-* Line Input:: Reading a line or a record from a stream.
+-* Unreading:: Peeking ahead/pushing back input just read.
+-* Block Input/Output:: Input and output operations on blocks of data.
+-* Formatted Output:: `printf' and related functions.
+-* Customizing Printf:: You can define new conversion specifiers for
+- `printf' and friends.
+-* Formatted Input:: `scanf' and related functions.
+-* EOF and Errors:: How you can tell if an I/O error happens.
+-* Binary Streams:: Some systems distinguish between text files
+- and binary files.
+-* File Positioning:: About random-access streams.
+-* Portable Positioning:: Random access on peculiar ISO C systems.
+-* Stream Buffering:: How to control buffering of streams.
+-* Other Kinds of Streams:: Streams that do not necessarily correspond
+- to an open file.
+-
+-
+-File: libc.info, Node: Streams, Next: Standard Streams, Up: I/O on Streams
+-
+-Streams
+-=======
+-
+- For historical reasons, the type of the C data structure that
+-represents a stream is called `FILE' rather than "stream". Since most
+-of the library functions deal with objects of type `FILE *', sometimes
+-the term "file pointer" is also used to mean "stream". This leads to
+-unfortunate confusion over terminology in many books on C. This
+-manual, however, is careful to use the terms "file" and "stream" only
+-in the technical sense.
+-
+- The `FILE' type is declared in the header file `stdio.h'.
+-
+- - Data Type: FILE
+- This is the data type used to represent stream objects. A `FILE'
+- object holds all of the internal state information about the
+- connection to the associated file, including such things as the
+- file position indicator and buffering information. Each stream
+- also has error and end-of-file status indicators that can be
+- tested with the `ferror' and `feof' functions; see *Note EOF and
+- Errors::.
+-
+- `FILE' objects are allocated and managed internally by the
+-input/output library functions. Don't try to create your own objects of
+-type `FILE'; let the library do it. Your programs should deal only
+-with pointers to these objects (that is, `FILE *' values) rather than
+-the objects themselves.
+-
+-
+-File: libc.info, Node: Standard Streams, Next: Opening Streams, Prev:
Streams, Up: I/O on Streams
+-
+-Standard Streams
+-================
+-
+- When the `main' function of your program is invoked, it already has
+-three predefined streams open and available for use. These represent
+-the "standard" input and output channels that have been established for
+-the process.
+-
+- These streams are declared in the header file `stdio.h'.
+-
+- - Variable: FILE * stdin
+- The "standard input" stream, which is the normal source of input
+- for the program.
+-
+- - Variable: FILE * stdout
+- The "standard output" stream, which is used for normal output from
+- the program.
+-
+- - Variable: FILE * stderr
+- The "standard error" stream, which is used for error messages and
+- diagnostics issued by the program.
+-
+- In the GNU system, you can specify what files or processes
+-correspond to these streams using the pipe and redirection facilities
+-provided by the shell. (The primitives shells use to implement these
+-facilities are described in *Note File System Interface::.) Most other
+-operating systems provide similar mechanisms, but the details of how to
+-use them can vary.
+-
+- In the GNU C library, `stdin', `stdout', and `stderr' are normal
+-variables which you can set just like any others. For example, to
+-redirect the standard output to a file, you could do:
+-
+- fclose (stdout);
+- stdout = fopen ("standard-output-file", "w");
+-
+- Note however, that in other systems `stdin', `stdout', and `stderr'
+-are macros that you cannot assign to in the normal way. But you can
+-use `freopen' to get the effect of closing one and reopening it. *Note
+-Opening Streams::.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-6
glibc-2.0.1/manual/libc.info-6
+--- ../glibc-2.0.1/manual/libc.info-6 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-6 1970-01-01 01:00:00.000000000 +0100
+@@ -1,1156 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+- This file documents the GNU C library.
+-
+- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+- Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+- Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+- Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: Opening Streams, Next: Closing Streams, Prev:
Standard Streams, Up: I/O on Streams
+-
+-Opening Streams
+-===============
+-
+- Opening a file with the `fopen' function creates a new stream and
+-establishes a connection between the stream and a file. This may
+-involve creating a new file.
+-
+- Everything described in this section is declared in the header file
+-`stdio.h'.
+-
+- - Function: FILE * fopen (const char *FILENAME, const char *OPENTYPE)
+- The `fopen' function opens a stream for I/O to the file FILENAME,
+- and returns a pointer to the stream.
+-
+- The OPENTYPE argument is a string that controls how the file is
+- opened and specifies attributes of the resulting stream. It must
+- begin with one of the following sequences of characters:
+-
+- `r'
+- Open an existing file for reading only.
+-
+- `w'
+- Open the file for writing only. If the file already exists,
+- it is truncated to zero length. Otherwise a new file is
+- created.
+-
+- `a'
+- Open a file for append access; that is, writing at the end of
+- file only. If the file already exists, its initial contents
+- are unchanged and output to the stream is appended to the end
+- of the file. Otherwise, a new, empty file is created.
+-
+- `r+'
+- Open an existing file for both reading and writing. The
+- initial contents of the file are unchanged and the initial
+- file position is at the beginning of the file.
+-
+- `w+'
+- Open a file for both reading and writing. If the file
+- already exists, it is truncated to zero length. Otherwise, a
+- new file is created.
+-
+- `a+'
+- Open or create file for both reading and appending. If the
+- file exists, its initial contents are unchanged. Otherwise,
+- a new file is created. The initial file position for reading
+- is at the beginning of the file, but output is always
+- appended to the end of the file.
+-
+- As you can see, `+' requests a stream that can do both input and
+- output. The ISO standard says that when using such a stream, you
+- must call `fflush' (*note Stream Buffering::.) or a file
+- positioning function such as `fseek' (*note File Positioning::.)
+- when switching from reading to writing or vice versa. Otherwise,
+- internal buffers might not be emptied properly. The GNU C library
+- does not have this limitation; you can do arbitrary reading and
+- writing operations on a stream in whatever order.
+-
+- Additional characters may appear after these to specify flags for
+- the call. Always put the mode (`r', `w+', etc.) first; that is
+- the only part you are guaranteed will be understood by all systems.
+-
+- The GNU C library defines one additional character for use in
+- OPENTYPE: the character `x' insists on creating a new file--if a
+- file FILENAME already exists, `fopen' fails rather than opening
+- it. If you use `x' you can are guaranteed that you will not
+- clobber an existing file. This is equivalent to the `O_EXCL'
+- option to the `open' function (*note Opening and Closing Files::.).
+-
+- The character `b' in OPENTYPE has a standard meaning; it requests
+- a binary stream rather than a text stream. But this makes no
+- difference in POSIX systems (including the GNU system). If both
+- `+' and `b' are specified, they can appear in either order. *Note
+- Binary Streams::.
+-
+- Any other characters in OPENTYPE are simply ignored. They may be
+- meaningful in other systems.
+-
+- If the open fails, `fopen' returns a null pointer.
+-
+- You can have multiple streams (or file descriptors) pointing to the
+-same file open at the same time. If you do only input, this works
+-straightforwardly, but you must be careful if any output streams are
+-included. *Note Stream/Descriptor Precautions::. This is equally true
+-whether the streams are in one program (not usual) or in several
+-programs (which can easily happen). It may be advantageous to use the
+-file locking facilities to avoid simultaneous access. *Note File
+-Locks::.
+-
+- - Macro: int FOPEN_MAX
+- The value of this macro is an integer constant expression that
+- represents the minimum number of streams that the implementation
+- guarantees can be open simultaneously. You might be able to open
+- more than this many streams, but that is not guaranteed. The
+- value of this constant is at least eight, which includes the three
+- standard streams `stdin', `stdout', and `stderr'. In POSIX.1
+- systems this value is determined by the `OPEN_MAX' parameter;
+- *note General Limits::.. In BSD and GNU, it is controlled by the
+- `RLIMIT_NOFILE' resource limit; *note Limits on Resources::..
+-
+- - Function: FILE * freopen (const char *FILENAME, const char
+- *OPENTYPE, FILE *STREAM)
+- This function is like a combination of `fclose' and `fopen'. It
+- first closes the stream referred to by STREAM, ignoring any errors
+- that are detected in the process. (Because errors are ignored,
+- you should not use `freopen' on an output stream if you have
+- actually done any output using the stream.) Then the file named by
+- FILENAME is opened with mode OPENTYPE as for `fopen', and
+- associated with the same stream object STREAM.
+-
+- If the operation fails, a null pointer is returned; otherwise,
+- `freopen' returns STREAM.
+-
+- `freopen' has traditionally been used to connect a standard stream
+- such as `stdin' with a file of your own choice. This is useful in
+- programs in which use of a standard stream for certain purposes is
+- hard-coded. In the GNU C library, you can simply close the
+- standard streams and open new ones with `fopen'. But other
+- systems lack this ability, so using `freopen' is more portable.
+-
+-
+-File: libc.info, Node: Closing Streams, Next: Simple Output, Prev: Opening
Streams, Up: I/O on Streams
+-
+-Closing Streams
+-===============
+-
+- When a stream is closed with `fclose', the connection between the
+-stream and the file is cancelled. After you have closed a stream, you
+-cannot perform any additional operations on it.
+-
+- - Function: int fclose (FILE *STREAM)
+- This function causes STREAM to be closed and the connection to the
+- corresponding file to be broken. Any buffered output is written
+- and any buffered input is discarded. The `fclose' function returns
+- a value of `0' if the file was closed successfully, and `EOF' if
+- an error was detected.
+-
+- It is important to check for errors when you call `fclose' to close
+- an output stream, because real, everyday errors can be detected at
+- this time. For example, when `fclose' writes the remaining
+- buffered output, it might get an error because the disk is full.
+- Even if you know the buffer is empty, errors can still occur when
+- closing a file if you are using NFS.
+-
+- The function `fclose' is declared in `stdio.h'.
+-
+- To close all streams currently available the GNU C Library provides
+-another function.
+-
+- - Function: int fcloseall (void)
+- This function causes all open streams of the process to be closed
+- and the connection to corresponding files to be broken. All
+- buffered data is written and any buffered inputis discarded. The
+- `fcloseall' function returns a value of `0' if all the files were
+- closed successfully, and `EOF' if an error was detected.
+-
+- This function should be used in only in special situation, e.g.,
+- when an error occurred and the program must be aborted. Normally
+- each single stream should be closed separately so that problems
+- with one stream can be identifier. It is also problematic since
+- the standard streams (*note Standard Streams::.) will also be
+- closed.
+-
+- The function `fcloseall' is declared in `stdio.h'.
+-
+- If the `main' function to your program returns, or if you call the
+-`exit' function (*note Normal Termination::.), all open streams are
+-automatically closed properly. If your program terminates in any other
+-manner, such as by calling the `abort' function (*note Aborting a
+-Program::.) or from a fatal signal (*note Signal Handling::.), open
+-streams might not be closed properly. Buffered output might not be
+-flushed and files may be incomplete. For more information on buffering
+-of streams, see *Note Stream Buffering::.
+-
+-
+-File: libc.info, Node: Simple Output, Next: Character Input, Prev: Closing
Streams, Up: I/O on Streams
+-
+-Simple Output by Characters or Lines
+-====================================
+-
+- This section describes functions for performing character- and
+-line-oriented output.
+-
+- These functions are declared in the header file `stdio.h'.
+-
+- - Function: int fputc (int C, FILE *STREAM)
+- The `fputc' function converts the character C to type `unsigned
+- char', and writes it to the stream STREAM. `EOF' is returned if a
+- write error occurs; otherwise the character C is returned.
+-
+- - Function: int putc (int C, FILE *STREAM)
+- This is just like `fputc', except that most systems implement it as
+- a macro, making it faster. One consequence is that it may
+- evaluate the STREAM argument more than once, which is an exception
+- to the general rule for macros. `putc' is usually the best
+- function to use for writing a single character.
+-
+- - Function: int putchar (int C)
+- The `putchar' function is equivalent to `putc' with `stdout' as
+- the value of the STREAM argument.
+-
+- - Function: int fputs (const char *S, FILE *STREAM)
+- The function `fputs' writes the string S to the stream STREAM.
+- The terminating null character is not written. This function does
+- *not* add a newline character, either. It outputs only the
+- characters in the string.
+-
+- This function returns `EOF' if a write error occurs, and otherwise
+- a non-negative value.
+-
+- For example:
+-
+- fputs ("Are ", stdout);
+- fputs ("you ", stdout);
+- fputs ("hungry?\n", stdout);
+-
+- outputs the text `Are you hungry?' followed by a newline.
+-
+- - Function: int puts (const char *S)
+- The `puts' function writes the string S to the stream `stdout'
+- followed by a newline. The terminating null character of the
+- string is not written. (Note that `fputs' does *not* write a
+- newline as this function does.)
+-
+- `puts' is the most convenient function for printing simple
+- messages. For example:
+-
+- puts ("This is a message.");
+-
+- - Function: int putw (int W, FILE *STREAM)
+- This function writes the word W (that is, an `int') to STREAM. It
+- is provided for compatibility with SVID, but we recommend you use
+- `fwrite' instead (*note Block Input/Output::.).
+-
+-
+-File: libc.info, Node: Character Input, Next: Line Input, Prev: Simple
Output, Up: I/O on Streams
+-
+-Character Input
+-===============
+-
+- This section describes functions for performing character-oriented
+-input. These functions are declared in the header file `stdio.h'.
+-
+- These functions return an `int' value that is either a character of
+-input, or the special value `EOF' (usually -1). It is important to
+-store the result of these functions in a variable of type `int' instead
+-of `char', even when you plan to use it only as a character. Storing
+-`EOF' in a `char' variable truncates its value to the size of a
+-character, so that it is no longer distinguishable from the valid
+-character `(char) -1'. So always use an `int' for the result of `getc'
+-and friends, and check for `EOF' after the call; once you've verified
+-that the result is not `EOF', you can be sure that it will fit in a
+-`char' variable without loss of information.
+-
+- - Function: int fgetc (FILE *STREAM)
+- This function reads the next character as an `unsigned char' from
+- the stream STREAM and returns its value, converted to an `int'.
+- If an end-of-file condition or read error occurs, `EOF' is
+- returned instead.
+-
+- - Function: int getc (FILE *STREAM)
+- This is just like `fgetc', except that it is permissible (and
+- typical) for it to be implemented as a macro that evaluates the
+- STREAM argument more than once. `getc' is often highly optimized,
+- so it is usually the best function to use to read a single
+- character.
+-
+- - Function: int getchar (void)
+- The `getchar' function is equivalent to `getc' with `stdin' as the
+- value of the STREAM argument.
+-
+- Here is an example of a function that does input using `fgetc'. It
+-would work just as well using `getc' instead, or using `getchar ()'
+-instead of `fgetc (stdin)'.
+-
+- int
+- y_or_n_p (const char *question)
+- {
+- fputs (question, stdout);
+- while (1)
+- {
+- int c, answer;
+- /* Write a space to separate answer from question. */
+- fputc (' ', stdout);
+- /* Read the first character of the line.
+- This should be the answer character, but might not be. */
+- c = tolower (fgetc (stdin));
+- answer = c;
+- /* Discard rest of input line. */
+- while (c != '\n' && c != EOF)
+- c = fgetc (stdin);
+- /* Obey the answer if it was valid. */
+- if (answer == 'y')
+- return 1;
+- if (answer == 'n')
+- return 0;
+- /* Answer was invalid: ask for valid answer. */
+- fputs ("Please answer y or n:", stdout);
+- }
+- }
+-
+- - Function: int getw (FILE *STREAM)
+- This function reads a word (that is, an `int') from STREAM. It's
+- provided for compatibility with SVID. We recommend you use
+- `fread' instead (*note Block Input/Output::.). Unlike `getc', any
+- `int' value could be a valid result. `getw' returns `EOF' when it
+- encounters end-of-file or an error, but there is no way to
+- distinguish this from an input word with value -1.
+-
+-
+-File: libc.info, Node: Line Input, Next: Unreading, Prev: Character Input,
Up: I/O on Streams
+-
+-Line-Oriented Input
+-===================
+-
+- Since many programs interpret input on the basis of lines, it's
+-convenient to have functions to read a line of text from a stream.
+-
+- Standard C has functions to do this, but they aren't very safe: null
+-characters and even (for `gets') long lines can confuse them. So the
+-GNU library provides the nonstandard `getline' function that makes it
+-easy to read lines reliably.
+-
+- Another GNU extension, `getdelim', generalizes `getline'. It reads
+-a delimited record, defined as everything through the next occurrence
+-of a specified delimiter character.
+-
+- All these functions are declared in `stdio.h'.
+-
+- - Function: ssize_t getline (char **LINEPTR, size_t *N, FILE *STREAM)
+- This function reads an entire line from STREAM, storing the text
+- (including the newline and a terminating null character) in a
+- buffer and storing the buffer address in `*LINEPTR'.
+-
+- Before calling `getline', you should place in `*LINEPTR' the
+- address of a buffer `*N' bytes long, allocated with `malloc'. If
+- this buffer is long enough to hold the line, `getline' stores the
+- line in this buffer. Otherwise, `getline' makes the buffer bigger
+- using `realloc', storing the new buffer address back in `*LINEPTR'
+- and the increased size back in `*N'. *Note Unconstrained
+- Allocation::.
+-
+- If you set `*LINEPTR' to a null pointer, and `*N' to zero, before
+- the call, then `getline' allocates the initial buffer for you by
+- calling `malloc'.
+-
+- In either case, when `getline' returns, `*LINEPTR' is a `char *'
+- which points to the text of the line.
+-
+- When `getline' is successful, it returns the number of characters
+- read (including the newline, but not including the terminating
+- null). This value enables you to distinguish null characters that
+- are part of the line from the null character inserted as a
+- terminator.
+-
+- This function is a GNU extension, but it is the recommended way to
+- read lines from a stream. The alternative standard functions are
+- unreliable.
+-
+- If an error occurs or end of file is reached, `getline' returns
+- `-1'.
+-
+- - Function: ssize_t getdelim (char **LINEPTR, size_t *N, int
+- DELIMITER, FILE *STREAM)
+- This function is like `getline' except that the character which
+- tells it to stop reading is not necessarily newline. The argument
+- DELIMITER specifies the delimiter character; `getdelim' keeps
+- reading until it sees that character (or end of file).
+-
+- The text is stored in LINEPTR, including the delimiter character
+- and a terminating null. Like `getline', `getdelim' makes LINEPTR
+- bigger if it isn't big enough.
+-
+- `getline' is in fact implemented in terms of `getdelim', just like
+- this:
+-
+- ssize_t
+- getline (char **lineptr, size_t *n, FILE *stream)
+- {
+- return getdelim (lineptr, n, '\n', stream);
+- }
+-
+- - Function: char * fgets (char *S, int COUNT, FILE *STREAM)
+- The `fgets' function reads characters from the stream STREAM up to
+- and including a newline character and stores them in the string S,
+- adding a null character to mark the end of the string. You must
+- supply COUNT characters worth of space in S, but the number of
+- characters read is at most COUNT - 1. The extra character space
+- is used to hold the null character at the end of the string.
+-
+- If the system is already at end of file when you call `fgets', then
+- the contents of the array S are unchanged and a null pointer is
+- returned. A null pointer is also returned if a read error occurs.
+- Otherwise, the return value is the pointer S.
+-
+- *Warning:* If the input data has a null character, you can't tell.
+- So don't use `fgets' unless you know the data cannot contain a
+- null. Don't use it to read files edited by the user because, if
+- the user inserts a null character, you should either handle it
+- properly or print a clear error message. We recommend using
+- `getline' instead of `fgets'.
+-
+- - Deprecated function: char * gets (char *S)
+- The function `gets' reads characters from the stream `stdin' up to
+- the next newline character, and stores them in the string S. The
+- newline character is discarded (note that this differs from the
+- behavior of `fgets', which copies the newline character into the
+- string). If `gets' encounters a read error or end-of-file, it
+- returns a null pointer; otherwise it returns S.
+-
+- *Warning:* The `gets' function is *very dangerous* because it
+- provides no protection against overflowing the string S. The GNU
+- library includes it for compatibility only. You should *always*
+- use `fgets' or `getline' instead. To remind you of this, the
+- linker (if using GNU `ld') will issue a warning whenever you use
+- `gets'.
+-
+-
+-File: libc.info, Node: Unreading, Next: Block Input/Output, Prev: Line
Input, Up: I/O on Streams
+-
+-Unreading
+-=========
+-
+- In parser programs it is often useful to examine the next character
+-in the input stream without removing it from the stream. This is called
+-"peeking ahead" at the input because your program gets a glimpse of the
+-input it will read next.
+-
+- Using stream I/O, you can peek ahead at input by first reading it and
+-then "unreading" it (also called "pushing it back" on the stream).
+-Unreading a character makes it available to be input again from the
+-stream, by the next call to `fgetc' or other input function on that
+-stream.
+-
+-* Menu:
+-
+-* Unreading Idea:: An explanation of unreading with pictures.
+-* How Unread:: How to call `ungetc' to do unreading.
+-
+-
+-File: libc.info, Node: Unreading Idea, Next: How Unread, Up: Unreading
+-
+-What Unreading Means
+---------------------
+-
+- Here is a pictorial explanation of unreading. Suppose you have a
+-stream reading a file that contains just six characters, the letters
+-`foobar'. Suppose you have read three characters so far. The
+-situation looks like this:
+-
+- f o o b a r
+- ^
+-
+-so the next input character will be `b'.
+-
+- If instead of reading `b' you unread the letter `o', you get a
+-situation like this:
+-
+- f o o b a r
+- |
+- o--
+- ^
+-
+-so that the next input characters will be `o' and `b'.
+-
+- If you unread `9' instead of `o', you get this situation:
+-
+- f o o b a r
+- |
+- 9--
+- ^
+-
+-so that the next input characters will be `9' and `b'.
+-
+-
+-File: libc.info, Node: How Unread, Prev: Unreading Idea, Up: Unreading
+-
+-Using `ungetc' To Do Unreading
+-------------------------------
+-
+- The function to unread a character is called `ungetc', because it
+-reverses the action of `getc'.
+-
+- - Function: int ungetc (int C, FILE *STREAM)
+- The `ungetc' function pushes back the character C onto the input
+- stream STREAM. So the next input from STREAM will read C before
+- anything else.
+-
+- If C is `EOF', `ungetc' does nothing and just returns `EOF'. This
+- lets you call `ungetc' with the return value of `getc' without
+- needing to check for an error from `getc'.
+-
+- The character that you push back doesn't have to be the same as
+- the last character that was actually read from the stream. In
+- fact, it isn't necessary to actually read any characters from the
+- stream before unreading them with `ungetc'! But that is a strange
+- way to write a program; usually `ungetc' is used only to unread a
+- character that was just read from the same stream.
+-
+- The GNU C library only supports one character of pushback--in other
+- words, it does not work to call `ungetc' twice without doing input
+- in between. Other systems might let you push back multiple
+- characters; then reading from the stream retrieves the characters
+- in the reverse order that they were pushed.
+-
+- Pushing back characters doesn't alter the file; only the internal
+- buffering for the stream is affected. If a file positioning
+- function (such as `fseek' or `rewind'; *note File Positioning::.)
+- is called, any pending pushed-back characters are discarded.
+-
+- Unreading a character on a stream that is at end of file clears the
+- end-of-file indicator for the stream, because it makes the
+- character of input available. After you read that character,
+- trying to read again will encounter end of file.
+-
+- Here is an example showing the use of `getc' and `ungetc' to skip
+-over whitespace characters. When this function reaches a
+-non-whitespace character, it unreads that character to be seen again on
+-the next read operation on the stream.
+-
+- #include <stdio.h>
+- #include <ctype.h>
+-
+- void
+- skip_whitespace (FILE *stream)
+- {
+- int c;
+- do
+- /* No need to check for `EOF' because it is not
+- `isspace', and `ungetc' ignores `EOF'. */
+- c = getc (stream);
+- while (isspace (c));
+- ungetc (c, stream);
+- }
+-
+-
+-File: libc.info, Node: Block Input/Output, Next: Formatted Output, Prev:
Unreading, Up: I/O on Streams
+-
+-Block Input/Output
+-==================
+-
+- This section describes how to do input and output operations on
+-blocks of data. You can use these functions to read and write binary
+-data, as well as to read and write text in fixed-size blocks instead of
+-by characters or lines.
+-
+- Binary files are typically used to read and write blocks of data in
+-the same format as is used to represent the data in a running program.
+-In other words, arbitrary blocks of memory--not just character or string
+-objects--can be written to a binary file, and meaningfully read in
+-again by the same program.
+-
+- Storing data in binary form is often considerably more efficient than
+-using the formatted I/O functions. Also, for floating-point numbers,
+-the binary form avoids possible loss of precision in the conversion
+-process. On the other hand, binary files can't be examined or modified
+-easily using many standard file utilities (such as text editors), and
+-are not portable between different implementations of the language, or
+-different kinds of computers.
+-
+- These functions are declared in `stdio.h'.
+-
+- - Function: size_t fread (void *DATA, size_t SIZE, size_t COUNT, FILE
+- *STREAM)
+- This function reads up to COUNT objects of size SIZE into the
+- array DATA, from the stream STREAM. It returns the number of
+- objects actually read, which might be less than COUNT if a read
+- error occurs or the end of the file is reached. This function
+- returns a value of zero (and doesn't read anything) if either SIZE
+- or COUNT is zero.
+-
+- If `fread' encounters end of file in the middle of an object, it
+- returns the number of complete objects read, and discards the
+- partial object. Therefore, the stream remains at the actual end
+- of the file.
+-
+- - Function: size_t fwrite (const void *DATA, size_t SIZE, size_t
+- COUNT, FILE *STREAM)
+- This function writes up to COUNT objects of size SIZE from the
+- array DATA, to the stream STREAM. The return value is normally
+- COUNT, if the call succeeds. Any other value indicates some sort
+- of error, such as running out of space.
+-
+-
+-File: libc.info, Node: Formatted Output, Next: Customizing Printf, Prev:
Block Input/Output, Up: I/O on Streams
+-
+-Formatted Output
+-================
+-
+- The functions described in this section (`printf' and related
+-functions) provide a convenient way to perform formatted output. You
+-call `printf' with a "format string" or "template string" that
+-specifies how to format the values of the remaining arguments.
+-
+- Unless your program is a filter that specifically performs line- or
+-character-oriented processing, using `printf' or one of the other
+-related functions described in this section is usually the easiest and
+-most concise way to perform output. These functions are especially
+-useful for printing error messages, tables of data, and the like.
+-
+-* Menu:
+-
+-* Formatted Output Basics:: Some examples to get you started.
+-* Output Conversion Syntax:: General syntax of conversion
+- specifications.
+-* Table of Output Conversions:: Summary of output conversions and
+- what they do.
+-* Integer Conversions:: Details about formatting of integers.
+-* Floating-Point Conversions:: Details about formatting of
+- floating-point numbers.
+-* Other Output Conversions:: Details about formatting of strings,
+- characters, pointers, and the like.
+-* Formatted Output Functions:: Descriptions of the actual functions.
+-* Dynamic Output:: Functions that allocate memory for the output.
+-* Variable Arguments Output:: `vprintf' and friends.
+-* Parsing a Template String:: What kinds of args does a given template
+- call for?
+-* Example of Parsing:: Sample program using `parse_printf_format'.
+-
+-
+-File: libc.info, Node: Formatted Output Basics, Next: Output Conversion
Syntax, Up: Formatted Output
+-
+-Formatted Output Basics
+------------------------
+-
+- The `printf' function can be used to print any number of arguments.
+-The template string argument you supply in a call provides information
+-not only about the number of additional arguments, but also about their
+-types and what style should be used for printing them.
+-
+- Ordinary characters in the template string are simply written to the
+-output stream as-is, while "conversion specifications" introduced by a
+-`%' character in the template cause subsequent arguments to be
+-formatted and written to the output stream. For example,
+-
+- int pct = 37;
+- char filename[] = "foo.txt";
+- printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
+- filename, pct);
+-
+-produces output like
+-
+- Processing of `foo.txt' is 37% finished.
+- Please be patient.
+-
+- This example shows the use of the `%d' conversion to specify that an
+-`int' argument should be printed in decimal notation, the `%s'
+-conversion to specify printing of a string argument, and the `%%'
+-conversion to print a literal `%' character.
+-
+- There are also conversions for printing an integer argument as an
+-unsigned value in octal, decimal, or hexadecimal radix (`%o', `%u', or
+-`%x', respectively); or as a character value (`%c').
+-
+- Floating-point numbers can be printed in normal, fixed-point notation
+-using the `%f' conversion or in exponential notation using the `%e'
+-conversion. The `%g' conversion uses either `%e' or `%f' format,
+-depending on what is more appropriate for the magnitude of the
+-particular number.
+-
+- You can control formatting more precisely by writing "modifiers"
+-between the `%' and the character that indicates which conversion to
+-apply. These slightly alter the ordinary behavior of the conversion.
+-For example, most conversion specifications permit you to specify a
+-minimum field width and a flag indicating whether you want the result
+-left- or right-justified within the field.
+-
+- The specific flags and modifiers that are permitted and their
+-interpretation vary depending on the particular conversion. They're all
+-described in more detail in the following sections. Don't worry if this
+-all seems excessively complicated at first; you can almost always get
+-reasonable free-format output without using any of the modifiers at all.
+-The modifiers are mostly used to make the output look "prettier" in
+-tables.
+-
+-
+-File: libc.info, Node: Output Conversion Syntax, Next: Table of Output
Conversions, Prev: Formatted Output Basics, Up: Formatted Output
+-
+-Output Conversion Syntax
+-------------------------
+-
+- This section provides details about the precise syntax of conversion
+-specifications that can appear in a `printf' template string.
+-
+- Characters in the template string that are not part of a conversion
+-specification are printed as-is to the output stream. Multibyte
+-character sequences (*note Extended Characters::.) are permitted in a
+-template string.
+-
+- The conversion specifications in a `printf' template string have the
+-general form:
+-
+- % FLAGS WIDTH [ . PRECISION ] TYPE CONVERSION
+-
+- For example, in the conversion specifier `%-10.8ld', the `-' is a
+-flag, `10' specifies the field width, the precision is `8', the letter
+-`l' is a type modifier, and `d' specifies the conversion style. (This
+-particular type specifier says to print a `long int' argument in
+-decimal notation, with a minimum of 8 digits left-justified in a field
+-at least 10 characters wide.)
+-
+- In more detail, output conversion specifications consist of an
+-initial `%' character followed in sequence by:
+-
+- * Zero or more "flag characters" that modify the normal behavior of
+- the conversion specification.
+-
+- * An optional decimal integer specifying the "minimum field width".
+- If the normal conversion produces fewer characters than this, the
+- field is padded with spaces to the specified width. This is a
+- *minimum* value; if the normal conversion produces more characters
+- than this, the field is *not* truncated. Normally, the output is
+- right-justified within the field.
+-
+- You can also specify a field width of `*'. This means that the
+- next argument in the argument list (before the actual value to be
+- printed) is used as the field width. The value must be an `int'.
+- If the value is negative, this means to set the `-' flag (see
+- below) and to use the absolute value as the field width.
+-
+- * An optional "precision" to specify the number of digits to be
+- written for the numeric conversions. If the precision is
+- specified, it consists of a period (`.') followed optionally by a
+- decimal integer (which defaults to zero if omitted).
+-
+- You can also specify a precision of `*'. This means that the next
+- argument in the argument list (before the actual value to be
+- printed) is used as the precision. The value must be an `int',
+- and is ignored if it is negative. If you specify `*' for both the
+- field width and precision, the field width argument precedes the
+- precision argument. Other C library versions may not recognize
+- this syntax.
+-
+- * An optional "type modifier character", which is used to specify the
+- data type of the corresponding argument if it differs from the
+- default type. (For example, the integer conversions assume a type
+- of `int', but you can specify `h', `l', or `L' for other integer
+- types.)
+-
+- * A character that specifies the conversion to be applied.
+-
+- The exact options that are permitted and how they are interpreted
+-vary between the different conversion specifiers. See the descriptions
+-of the individual conversions for information about the particular
+-options that they use.
+-
+- With the `-Wformat' option, the GNU C compiler checks calls to
+-`printf' and related functions. It examines the format string and
+-verifies that the correct number and types of arguments are supplied.
+-There is also a GNU C syntax to tell the compiler that a function you
+-write uses a `printf'-style format string. *Note Declaring Attributes
+-of Functions: (gcc.info)Function Attributes, for more information.
+-
+-
+-File: libc.info, Node: Table of Output Conversions, Next: Integer
Conversions, Prev: Output Conversion Syntax, Up: Formatted Output
+-
+-Table of Output Conversions
+----------------------------
+-
+- Here is a table summarizing what all the different conversions do:
+-
+-`%d', `%i'
+- Print an integer as a signed decimal number. *Note Integer
+- Conversions::, for details. `%d' and `%i' are synonymous for
+- output, but are different when used with `scanf' for input (*note
+- Table of Input Conversions::.).
+-
+-`%o'
+- Print an integer as an unsigned octal number. *Note Integer
+- Conversions::, for details.
+-
+-`%u'
+- Print an integer as an unsigned decimal number. *Note Integer
+- Conversions::, for details.
+-
+-`%x', `%X'
+- Print an integer as an unsigned hexadecimal number. `%x' uses
+- lower-case letters and `%X' uses upper-case. *Note Integer
+- Conversions::, for details.
+-
+-`%f'
+- Print a floating-point number in normal (fixed-point) notation.
+- *Note Floating-Point Conversions::, for details.
+-
+-`%e', `%E'
+- Print a floating-point number in exponential notation. `%e' uses
+- lower-case letters and `%E' uses upper-case. *Note Floating-Point
+- Conversions::, for details.
+-
+-`%g', `%G'
+- Print a floating-point number in either normal or exponential
+- notation, whichever is more appropriate for its magnitude. `%g'
+- uses lower-case letters and `%G' uses upper-case. *Note
+- Floating-Point Conversions::, for details.
+-
+-`%c'
+- Print a single character. *Note Other Output Conversions::.
+-
+-`%s'
+- Print a string. *Note Other Output Conversions::.
+-
+-`%p'
+- Print the value of a pointer. *Note Other Output Conversions::.
+-
+-`%n'
+- Get the number of characters printed so far. *Note Other Output
+- Conversions::. Note that this conversion specification never
+- produces any output.
+-
+-`%m'
+- Print the string corresponding to the value of `errno'. (This is
+- a GNU extension.) *Note Other Output Conversions::.
+-
+-`%%'
+- Print a literal `%' character. *Note Other Output Conversions::.
+-
+- If the syntax of a conversion specification is invalid, unpredictable
+-things will happen, so don't do this. If there aren't enough function
+-arguments provided to supply values for all the conversion
+-specifications in the template string, or if the arguments are not of
+-the correct types, the results are unpredictable. If you supply more
+-arguments than conversion specifications, the extra argument values are
+-simply ignored; this is sometimes useful.
+-
+-
+-File: libc.info, Node: Integer Conversions, Next: Floating-Point
Conversions, Prev: Table of Output Conversions, Up: Formatted Output
+-
+-Integer Conversions
+--------------------
+-
+- This section describes the options for the `%d', `%i', `%o', `%u',
+-`%x', and `%X' conversion specifications. These conversions print
+-integers in various formats.
+-
+- The `%d' and `%i' conversion specifications both print an `int'
+-argument as a signed decimal number; while `%o', `%u', and `%x' print
+-the argument as an unsigned octal, decimal, or hexadecimal number
+-(respectively). The `%X' conversion specification is just like `%x'
+-except that it uses the characters `ABCDEF' as digits instead of
+-`abcdef'.
+-
+- The following flags are meaningful:
+-
+-`-'
+- Left-justify the result in the field (instead of the normal
+- right-justification).
+-
+-`+'
+- For the signed `%d' and `%i' conversions, print a plus sign if the
+- value is positive.
+-
+-` '
+- For the signed `%d' and `%i' conversions, if the result doesn't
+- start with a plus or minus sign, prefix it with a space character
+- instead. Since the `+' flag ensures that the result includes a
+- sign, this flag is ignored if you supply both of them.
+-
+-`#'
+- For the `%o' conversion, this forces the leading digit to be `0',
+- as if by increasing the precision. For `%x' or `%X', this
+- prefixes a leading `0x' or `0X' (respectively) to the result.
+- This doesn't do anything useful for the `%d', `%i', or `%u'
+- conversions. Using this flag produces output which can be parsed
+- by the `strtoul' function (*note Parsing of Integers::.) and
+- `scanf' with the `%i' conversion (*note Numeric Input
+- Conversions::.).
+-
+-`''
+- Separate the digits into groups as specified by the locale
+- specified for the `LC_NUMERIC' category; *note General Numeric::..
+- This flag is a GNU extension.
+-
+-`0'
+- Pad the field with zeros instead of spaces. The zeros are placed
+- after any indication of sign or base. This flag is ignored if the
+- `-' flag is also specified, or if a precision is specified.
+-
+- If a precision is supplied, it specifies the minimum number of
+-digits to appear; leading zeros are produced if necessary. If you
+-don't specify a precision, the number is printed with as many digits as
+-it needs. If you convert a value of zero with an explicit precision of
+-zero, then no characters at all are produced.
+-
+- Without a type modifier, the corresponding argument is treated as an
+-`int' (for the signed conversions `%i' and `%d') or `unsigned int' (for
+-the unsigned conversions `%o', `%u', `%x', and `%X'). Recall that
+-since `printf' and friends are variadic, any `char' and `short'
+-arguments are automatically converted to `int' by the default argument
+-promotions. For arguments of other integer types, you can use these
+-modifiers:
+-
+-`h'
+- Specifies that the argument is a `short int' or `unsigned short
+- int', as appropriate. A `short' argument is converted to an `int'
+- or `unsigned int' by the default argument promotions anyway, but
+- the `h' modifier says to convert it back to a `short' again.
+-
+-`l'
+- Specifies that the argument is a `long int' or `unsigned long
+- int', as appropriate. Two `l' characters is like the `L'
+- modifier, below.
+-
+-`L'
+-`ll'
+-`q'
+- Specifies that the argument is a `long long int'. (This type is
+- an extension supported by the GNU C compiler. On systems that
+- don't support extra-long integers, this is the same as `long int'.)
+-
+- The `q' modifier is another name for the same thing, which comes
+- from 4.4 BSD; a `long long int' is sometimes called a "quad" `int'.
+-
+-`Z'
+- Specifies that the argument is a `size_t'. This is a GNU
+- extension.
+-
+- Here is an example. Using the template string:
+-
+- "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
+-
+-to print numbers using the different options for the `%d' conversion
+-gives results like:
+-
+- | 0|0 | +0|+0 | 0|00000| | 00|0|
+- | 1|1 | +1|+1 | 1|00001| 1| 01|1|
+- | -1|-1 | -1|-1 | -1|-0001| -1| -01|-1|
+- |100000|100000|+100000| 100000|100000|100000|100000|100000|
+-
+- In particular, notice what happens in the last case where the number
+-is too large to fit in the minimum field width specified.
+-
+- Here are some more examples showing how unsigned integers print under
+-various format options, using the template string:
+-
+- "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
+-
+- | 0| 0| 0| 0| 0| 0x0| 0X0|0x00000000|
+- | 1| 1| 1| 1| 01| 0x1| 0X1|0x00000001|
+- |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
+-
+-
+-File: libc.info, Node: Floating-Point Conversions, Next: Other Output
Conversions, Prev: Integer Conversions, Up: Formatted Output
+-
+-Floating-Point Conversions
+---------------------------
+-
+- This section discusses the conversion specifications for
+-floating-point numbers: the `%f', `%e', `%E', `%g', and `%G'
+-conversions.
+-
+- The `%f' conversion prints its argument in fixed-point notation,
+-producing output of the form [`-']DDD`.'DDD, where the number of digits
+-following the decimal point is controlled by the precision you specify.
+-
+- The `%e' conversion prints its argument in exponential notation,
+-producing output of the form [`-']D`.'DDD`e'[`+'|`-']DD. Again, the
+-number of digits following the decimal point is controlled by the
+-precision. The exponent always contains at least two digits. The `%E'
+-conversion is similar but the exponent is marked with the letter `E'
+-instead of `e'.
+-
+- The `%g' and `%G' conversions print the argument in the style of
+-`%e' or `%E' (respectively) if the exponent would be less than -4 or
+-greater than or equal to the precision; otherwise they use the `%f'
+-style. Trailing zeros are removed from the fractional portion of the
+-result and a decimal-point character appears only if it is followed by
+-a digit.
+-
+- The following flags can be used to modify the behavior:
+-
+-`-'
+- Left-justify the result in the field. Normally the result is
+- right-justified.
+-
+-`+'
+- Always include a plus or minus sign in the result.
+-
+-` '
+- If the result doesn't start with a plus or minus sign, prefix it
+- with a space instead. Since the `+' flag ensures that the result
+- includes a sign, this flag is ignored if you supply both of them.
+-
+-`#'
+- Specifies that the result should always include a decimal point,
+- even if no digits follow it. For the `%g' and `%G' conversions,
+- this also forces trailing zeros after the decimal point to be left
+- in place where they would otherwise be removed.
+-
+-`''
+- Separate the digits of the integer part of the result into groups
+- as specified by the locale specified for the `LC_NUMERIC' category;
+- *note General Numeric::.. This flag is a GNU extension.
+-
+-`0'
+- Pad the field with zeros instead of spaces; the zeros are placed
+- after any sign. This flag is ignored if the `-' flag is also
+- specified.
+-
+- The precision specifies how many digits follow the decimal-point
+-character for the `%f', `%e', and `%E' conversions. For these
+-conversions, the default precision is `6'. If the precision is
+-explicitly `0', this suppresses the decimal point character entirely.
+-For the `%g' and `%G' conversions, the precision specifies how many
+-significant digits to print. Significant digits are the first digit
+-before the decimal point, and all the digits after it. If the
+-precision `0' or not specified for `%g' or `%G', it is treated like a
+-value of `1'. If the value being printed cannot be expressed
+-accurately in the specified number of digits, the value is rounded to
+-the nearest number that fits.
+-
+- Without a type modifier, the floating-point conversions use an
+-argument of type `double'. (By the default argument promotions, any
+-`float' arguments are automatically converted to `double'.) The
+-following type modifier is supported:
+-
+-`L'
+- An uppercase `L' specifies that the argument is a `long double'.
+-
+- Here are some examples showing how numbers print using the various
+-floating-point conversions. All of the numbers were printed using this
+-template string:
+-
+- "|%12.4f|%12.4e|%12.4g|\n"
+-
+- Here is the output:
+-
+- | 0.0000| 0.0000e+00| 0|
+- | 1.0000| 1.0000e+00| 1|
+- | -1.0000| -1.0000e+00| -1|
+- | 100.0000| 1.0000e+02| 100|
+- | 1000.0000| 1.0000e+03| 1000|
+- | 10000.0000| 1.0000e+04| 1e+04|
+- | 12345.0000| 1.2345e+04| 1.234e+04|
+- | 100000.0000| 1.0000e+05| 1e+05|
+- | 123456.0000| 1.2346e+05| 1.234e+05|
+-
+- Notice how the `%g' conversion drops trailing zeros.
+-
+-
+-File: libc.info, Node: Other Output Conversions, Next: Formatted Output
Functions, Prev: Floating-Point Conversions, Up: Formatted Output
+-
+-Other Output Conversions
+-------------------------
+-
+- This section describes miscellaneous conversions for `printf'.
+-
+- The `%c' conversion prints a single character. The `int' argument
+-is first converted to an `unsigned char'. The `-' flag can be used to
+-specify left-justification in the field, but no other flags are
+-defined, and no precision or type modifier can be given. For example:
+-
+- printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
+-
+-prints `hello'.
+-
+- The `%s' conversion prints a string. The corresponding argument
+-must be of type `char *' (or `const char *'). A precision can be
+-specified to indicate the maximum number of characters to write;
+-otherwise characters in the string up to but not including the
+-terminating null character are written to the output stream. The `-'
+-flag can be used to specify left-justification in the field, but no
+-other flags or type modifiers are defined for this conversion. For
+-example:
+-
+- printf ("%3s%-6s", "no", "where");
+-
+-prints ` nowhere '.
+-
+- If you accidentally pass a null pointer as the argument for a `%s'
+-conversion, the GNU library prints it as `(null)'. We think this is
+-more useful than crashing. But it's not good practice to pass a null
+-argument intentionally.
+-
+- The `%m' conversion prints the string corresponding to the error
+-code in `errno'. *Note Error Messages::. Thus:
+-
+- fprintf (stderr, "can't open `%s': %m\n", filename);
+-
+-is equivalent to:
+-
+- fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
+-
+-The `%m' conversion is a GNU C library extension.
+-
+- The `%p' conversion prints a pointer value. The corresponding
+-argument must be of type `void *'. In practice, you can use any type
+-of pointer.
+-
+- In the GNU system, non-null pointers are printed as unsigned
+-integers, as if a `%#x' conversion were used. Null pointers print as
+-`(nil)'. (Pointers might print differently in other systems.)
+-
+- For example:
+-
+- printf ("%p", "testing");
+-
+-prints `0x' followed by a hexadecimal number--the address of the string
+-constant `"testing"'. It does not print the word `testing'.
+-
+- You can supply the `-' flag with the `%p' conversion to specify
+-left-justification, but no other flags, precision, or type modifiers
+-are defined.
+-
+- The `%n' conversion is unlike any of the other output conversions.
+-It uses an argument which must be a pointer to an `int', but instead of
+-printing anything it stores the number of characters printed so far by
+-this call at that location. The `h' and `l' type modifiers are
+-permitted to specify that the argument is of type `short int *' or
+-`long int *' instead of `int *', but no flags, field width, or
+-precision are permitted.
+-
+- For example,
+-
+- int nchar;
+- printf ("%d %s%n\n", 3, "bears", &nchar);
+-
+-prints:
+-
+- 3 bears
+-
+-and sets `nchar' to `7', because `3 bears' is seven characters.
+-
+- The `%%' conversion prints a literal `%' character. This conversion
+-doesn't use an argument, and no flags, field width, precision, or type
+-modifiers are permitted.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-7
glibc-2.0.1/manual/libc.info-7
+--- ../glibc-2.0.1/manual/libc.info-7 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-7 1970-01-01 01:00:00.000000000 +0100
+@@ -1,1235 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+- This file documents the GNU C library.
+-
+- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+- Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+- Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+- Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: Formatted Output Functions, Next: Dynamic Output,
Prev: Other Output Conversions, Up: Formatted Output
+-
+-Formatted Output Functions
+---------------------------
+-
+- This section describes how to call `printf' and related functions.
+-Prototypes for these functions are in the header file `stdio.h'.
+-Because these functions take a variable number of arguments, you *must*
+-declare prototypes for them before using them. Of course, the easiest
+-way to make sure you have all the right prototypes is to just include
+-`stdio.h'.
+-
+- - Function: int printf (const char *TEMPLATE, ...)
+- The `printf' function prints the optional arguments under the
+- control of the template string TEMPLATE to the stream `stdout'.
+- It returns the number of characters printed, or a negative value
+- if there was an output error.
+-
+- - Function: int fprintf (FILE *STREAM, const char *TEMPLATE, ...)
+- This function is just like `printf', except that the output is
+- written to the stream STREAM instead of `stdout'.
+-
+- - Function: int sprintf (char *S, const char *TEMPLATE, ...)
+- This is like `printf', except that the output is stored in the
+- character array S instead of written to a stream. A null
+- character is written to mark the end of the string.
+-
+- The `sprintf' function returns the number of characters stored in
+- the array S, not including the terminating null character.
+-
+- The behavior of this function is undefined if copying takes place
+- between objects that overlap--for example, if S is also given as
+- an argument to be printed under control of the `%s' conversion.
+- *Note Copying and Concatenation::.
+-
+- *Warning:* The `sprintf' function can be *dangerous* because it
+- can potentially output more characters than can fit in the
+- allocation size of the string S. Remember that the field width
+- given in a conversion specification is only a *minimum* value.
+-
+- To avoid this problem, you can use `snprintf' or `asprintf',
+- described below.
+-
+- - Function: int snprintf (char *S, size_t SIZE, const char *TEMPLATE,
+- ...)
+- The `snprintf' function is similar to `sprintf', except that the
+- SIZE argument specifies the maximum number of characters to
+- produce. The trailing null character is counted towards this
+- limit, so you should allocate at least SIZE characters for the
+- string S.
+-
+- The return value is the number of characters stored, not including
+- the terminating null. If this value equals `SIZE - 1', then there
+- was not enough space in S for all the output. You should try
+- again with a bigger output string. Here is an example of doing
+- this:
+-
+- /* Construct a message describing the value of a variable
+- whose name is NAME and whose value is VALUE. */
+- char *
+- make_message (char *name, char *value)
+- {
+- /* Guess we need no more than 100 chars of space. */
+- int size = 100;
+- char *buffer = (char *) xmalloc (size);
+-
+- while (1)
+- {
+- /* Try to print in the allocated space. */
+- int nchars = snprintf (buffer, size,
+- "value of %s is %s",
+- name, value);
+- /* If that worked, return the string. */
+- if (nchars < size)
+- return buffer;
+- /* Else try again with twice as much space. */
+- size *= 2;
+- buffer = (char *) xrealloc (size, buffer);
+- }
+- }
+-
+- In practice, it is often easier just to use `asprintf', below.
+-
+-
+-File: libc.info, Node: Dynamic Output, Next: Variable Arguments Output,
Prev: Formatted Output Functions, Up: Formatted Output
+-
+-Dynamically Allocating Formatted Output
+----------------------------------------
+-
+- The functions in this section do formatted output and place the
+-results in dynamically allocated memory.
+-
+- - Function: int asprintf (char **PTR, const char *TEMPLATE, ...)
+- This function is similar to `sprintf', except that it dynamically
+- allocates a string (as with `malloc'; *note Unconstrained
+- Allocation::.) to hold the output, instead of putting the output
+- in a buffer you allocate in advance. The PTR argument should be
+- the address of a `char *' object, and `asprintf' stores a pointer
+- to the newly allocated string at that location.
+-
+- Here is how to use `asprintf' to get the same result as the
+- `snprintf' example, but more easily:
+-
+- /* Construct a message describing the value of a variable
+- whose name is NAME and whose value is VALUE. */
+- char *
+- make_message (char *name, char *value)
+- {
+- char *result;
+- asprintf (&result, "value of %s is %s", name, value);
+- return result;
+- }
+-
+- - Function: int obstack_printf (struct obstack *OBSTACK, const char
+- *TEMPLATE, ...)
+- This function is similar to `asprintf', except that it uses the
+- obstack OBSTACK to allocate the space. *Note Obstacks::.
+-
+- The characters are written onto the end of the current object. To
+- get at them, you must finish the object with `obstack_finish'
+- (*note Growing Objects::.).
+-
+-
+-File: libc.info, Node: Variable Arguments Output, Next: Parsing a Template
String, Prev: Dynamic Output, Up: Formatted Output
+-
+-Variable Arguments Output Functions
+------------------------------------
+-
+- The functions `vprintf' and friends are provided so that you can
+-define your own variadic `printf'-like functions that make use of the
+-same internals as the built-in formatted output functions.
+-
+- The most natural way to define such functions would be to use a
+-language construct to say, "Call `printf' and pass this template plus
+-all of my arguments after the first five." But there is no way to do
+-this in C, and it would be hard to provide a way, since at the C
+-language level there is no way to tell how many arguments your function
+-received.
+-
+- Since that method is impossible, we provide alternative functions,
+-the `vprintf' series, which lets you pass a `va_list' to describe "all
+-of my arguments after the first five."
+-
+- When it is sufficient to define a macro rather than a real function,
+-the GNU C compiler provides a way to do this much more easily with
+-macros. For example:
+-
+- #define myprintf(a, b, c, d, e, rest...) printf (mytemplate , ## rest...)
+-
+-*Note Macros with Variable Numbers of Arguments: (gcc.info)Macro
+-Varargs, for details. But this is limited to macros, and does not
+-apply to real functions at all.
+-
+- Before calling `vprintf' or the other functions listed in this
+-section, you *must* call `va_start' (*note Variadic Functions::.) to
+-initialize a pointer to the variable arguments. Then you can call
+-`va_arg' to fetch the arguments that you want to handle yourself. This
+-advances the pointer past those arguments.
+-
+- Once your `va_list' pointer is pointing at the argument of your
+-choice, you are ready to call `vprintf'. That argument and all
+-subsequent arguments that were passed to your function are used by
+-`vprintf' along with the template that you specified separately.
+-
+- In some other systems, the `va_list' pointer may become invalid
+-after the call to `vprintf', so you must not use `va_arg' after you
+-call `vprintf'. Instead, you should call `va_end' to retire the
+-pointer from service. However, you can safely call `va_start' on
+-another pointer variable and begin fetching the arguments again through
+-that pointer. Calling `vprintf' does not destroy the argument list of
+-your function, merely the particular pointer that you passed to it.
+-
+- GNU C does not have such restrictions. You can safely continue to
+-fetch arguments from a `va_list' pointer after passing it to `vprintf',
+-and `va_end' is a no-op. (Note, however, that subsequent `va_arg'
+-calls will fetch the same arguments which `vprintf' previously used.)
+-
+- Prototypes for these functions are declared in `stdio.h'.
+-
+- - Function: int vprintf (const char *TEMPLATE, va_list AP)
+- This function is similar to `printf' except that, instead of taking
+- a variable number of arguments directly, it takes an argument list
+- pointer AP.
+-
+- - Function: int vfprintf (FILE *STREAM, const char *TEMPLATE, va_list
+- AP)
+- This is the equivalent of `fprintf' with the variable argument list
+- specified directly as for `vprintf'.
+-
+- - Function: int vsprintf (char *S, const char *TEMPLATE, va_list AP)
+- This is the equivalent of `sprintf' with the variable argument list
+- specified directly as for `vprintf'.
+-
+- - Function: int vsnprintf (char *S, size_t SIZE, const char *TEMPLATE,
+- va_list AP)
+- This is the equivalent of `snprintf' with the variable argument
+- list specified directly as for `vprintf'.
+-
+- - Function: int vasprintf (char **PTR, const char *TEMPLATE, va_list
+- AP)
+- The `vasprintf' function is the equivalent of `asprintf' with the
+- variable argument list specified directly as for `vprintf'.
+-
+- - Function: int obstack_vprintf (struct obstack *OBSTACK, const char
+- *TEMPLATE, va_list AP)
+- The `obstack_vprintf' function is the equivalent of
+- `obstack_printf' with the variable argument list specified directly
+- as for `vprintf'.
+-
+- Here's an example showing how you might use `vfprintf'. This is a
+-function that prints error messages to the stream `stderr', along with
+-a prefix indicating the name of the program (*note Error Messages::.,
+-for a description of `program_invocation_short_name').
+-
+- #include <stdio.h>
+- #include <stdarg.h>
+-
+- void
+- eprintf (const char *template, ...)
+- {
+- va_list ap;
+- extern char *program_invocation_short_name;
+-
+- fprintf (stderr, "%s: ", program_invocation_short_name);
+- va_start (ap, count);
+- vfprintf (stderr, template, ap);
+- va_end (ap);
+- }
+-
+-You could call `eprintf' like this:
+-
+- eprintf ("file `%s' does not exist\n", filename);
+-
+- In GNU C, there is a special construct you can use to let the
+-compiler know that a function uses a `printf'-style format string.
+-Then it can check the number and types of arguments in each call to the
+-function, and warn you when they do not match the format string. For
+-example, take this declaration of `eprintf':
+-
+- void eprintf (const char *template, ...)
+- __attribute__ ((format (printf, 1, 2)));
+-
+-This tells the compiler that `eprintf' uses a format string like
+-`printf' (as opposed to `scanf'; *note Formatted Input::.); the format
+-string appears as the first argument; and the arguments to satisfy the
+-format begin with the second. *Note Declaring Attributes of Functions:
+-(gcc.info)Function Attributes, for more information.
+-
+-
+-File: libc.info, Node: Parsing a Template String, Next: Example of Parsing,
Prev: Variable Arguments Output, Up: Formatted Output
+-
+-Parsing a Template String
+--------------------------
+-
+- You can use the function `parse_printf_format' to obtain information
+-about the number and types of arguments that are expected by a given
+-template string. This function permits interpreters that provide
+-interfaces to `printf' to avoid passing along invalid arguments from
+-the user's program, which could cause a crash.
+-
+- All the symbols described in this section are declared in the header
+-file `printf.h'.
+-
+- - Function: size_t parse_printf_format (const char *TEMPLATE, size_t
+- N, int *ARGTYPES)
+- This function returns information about the number and types of
+- arguments expected by the `printf' template string TEMPLATE. The
+- information is stored in the array ARGTYPES; each element of this
+- array describes one argument. This information is encoded using
+- the various `PA_' macros, listed below.
+-
+- The N argument specifies the number of elements in the array
+- ARGTYPES. This is the most elements that `parse_printf_format'
+- will try to write.
+-
+- `parse_printf_format' returns the total number of arguments
+- required by TEMPLATE. If this number is greater than N, then the
+- information returned describes only the first N arguments. If you
+- want information about more than that many arguments, allocate a
+- bigger array and call `parse_printf_format' again.
+-
+- The argument types are encoded as a combination of a basic type and
+-modifier flag bits.
+-
+- - Macro: int PA_FLAG_MASK
+- This macro is a bitmask for the type modifier flag bits. You can
+- write the expression `(argtypes[i] & PA_FLAG_MASK)' to extract
+- just the flag bits for an argument, or `(argtypes[i] &
+- ~PA_FLAG_MASK)' to extract just the basic type code.
+-
+- Here are symbolic constants that represent the basic types; they
+-stand for integer values.
+-
+-`PA_INT'
+- This specifies that the base type is `int'.
+-
+-`PA_CHAR'
+- This specifies that the base type is `int', cast to `char'.
+-
+-`PA_STRING'
+- This specifies that the base type is `char *', a null-terminated
+- string.
+-
+-`PA_POINTER'
+- This specifies that the base type is `void *', an arbitrary
+- pointer.
+-
+-`PA_FLOAT'
+- This specifies that the base type is `float'.
+-
+-`PA_DOUBLE'
+- This specifies that the base type is `double'.
+-
+-`PA_LAST'
+- You can define additional base types for your own programs as
+- offsets from `PA_LAST'. For example, if you have data types `foo'
+- and `bar' with their own specialized `printf' conversions, you
+- could define encodings for these types as:
+-
+- #define PA_FOO PA_LAST
+- #define PA_BAR (PA_LAST + 1)
+-
+- Here are the flag bits that modify a basic type. They are combined
+-with the code for the basic type using inclusive-or.
+-
+-`PA_FLAG_PTR'
+- If this bit is set, it indicates that the encoded type is a
+- pointer to the base type, rather than an immediate value. For
+- example, `PA_INT|PA_FLAG_PTR' represents the type `int *'.
+-
+-`PA_FLAG_SHORT'
+- If this bit is set, it indicates that the base type is modified
+- with `short'. (This corresponds to the `h' type modifier.)
+-
+-`PA_FLAG_LONG'
+- If this bit is set, it indicates that the base type is modified
+- with `long'. (This corresponds to the `l' type modifier.)
+-
+-`PA_FLAG_LONG_LONG'
+- If this bit is set, it indicates that the base type is modified
+- with `long long'. (This corresponds to the `L' type modifier.)
+-
+-`PA_FLAG_LONG_DOUBLE'
+- This is a synonym for `PA_FLAG_LONG_LONG', used by convention with
+- a base type of `PA_DOUBLE' to indicate a type of `long double'.
+-
+- For an example of using these facilities, see *Note Example of
+-Parsing::.
+-
+-
+-File: libc.info, Node: Example of Parsing, Prev: Parsing a Template String,
Up: Formatted Output
+-
+-Example of Parsing a Template String
+-------------------------------------
+-
+- Here is an example of decoding argument types for a format string.
+-We assume this is part of an interpreter which contains arguments of
+-type `NUMBER', `CHAR', `STRING' and `STRUCTURE' (and perhaps others
+-which are not valid here).
+-
+- /* Test whether the NARGS specified objects
+- in the vector ARGS are valid
+- for the format string FORMAT:
+- if so, return 1.
+- If not, return 0 after printing an error message. */
+-
+- int
+- validate_args (char *format, int nargs, OBJECT *args)
+- {
+- int *argtypes;
+- int nwanted;
+-
+- /* Get the information about the arguments.
+- Each conversion specification must be at least two characters
+- long, so there cannot be more specifications than half the
+- length of the string. */
+-
+- argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
+- nwanted = parse_printf_format (string, nelts, argtypes);
+-
+- /* Check the number of arguments. */
+- if (nwanted > nargs)
+- {
+- error ("too few arguments (at least %d required)", nwanted);
+- return 0;
+- }
+-
+- /* Check the C type wanted for each argument
+- and see if the object given is suitable. */
+- for (i = 0; i < nwanted; i++)
+- {
+- int wanted;
+-
+- if (argtypes[i] & PA_FLAG_PTR)
+- wanted = STRUCTURE;
+- else
+- switch (argtypes[i] & ~PA_FLAG_MASK)
+- {
+- case PA_INT:
+- case PA_FLOAT:
+- case PA_DOUBLE:
+- wanted = NUMBER;
+- break;
+- case PA_CHAR:
+- wanted = CHAR;
+- break;
+- case PA_STRING:
+- wanted = STRING;
+- break;
+- case PA_POINTER:
+- wanted = STRUCTURE;
+- break;
+- }
+- if (TYPE (args[i]) != wanted)
+- {
+- error ("type mismatch for arg number %d", i);
+- return 0;
+- }
+- }
+- return 1;
+- }
+-
+-
+-File: libc.info, Node: Customizing Printf, Next: Formatted Input, Prev:
Formatted Output, Up: I/O on Streams
+-
+-Customizing `printf'
+-====================
+-
+- The GNU C library lets you define your own custom conversion
+-specifiers for `printf' template strings, to teach `printf' clever ways
+-to print the important data structures of your program.
+-
+- The way you do this is by registering the conversion with the
+-function `register_printf_function'; see *Note Registering New
+-Conversions::. One of the arguments you pass to this function is a
+-pointer to a handler function that produces the actual output; see
+-*Note Defining the Output Handler::, for information on how to write
+-this function.
+-
+- You can also install a function that just returns information about
+-the number and type of arguments expected by the conversion specifier.
+-*Note Parsing a Template String::, for information about this.
+-
+- The facilities of this section are declared in the header file
+-`printf.h'.
+-
+-* Menu:
+-
+-* Registering New Conversions:: Using `register_printf_function'
+- to register a new output conversion.
+-* Conversion Specifier Options:: The handler must be able to get
+- the options specified in the
+- template when it is called.
+-* Defining the Output Handler:: Defining the handler and arginfo
+- functions that are passed as
arguments
+- to `register_printf_function'.
+-* Printf Extension Example:: How to define a `printf'
+- handler function.
+-
+- *Portability Note:* The ability to extend the syntax of `printf'
+-template strings is a GNU extension. ISO standard C has nothing
+-similar.
+-
+-
+-File: libc.info, Node: Registering New Conversions, Next: Conversion
Specifier Options, Up: Customizing Printf
+-
+-Registering New Conversions
+----------------------------
+-
+- The function to register a new output conversion is
+-`register_printf_function', declared in `printf.h'.
+-
+- - Function: int register_printf_function (int SPEC, printf_function
+- HANDLER-FUNCTION, printf_arginfo_function ARGINFO-FUNCTION)
+- This function defines the conversion specifier character SPEC.
+- Thus, if SPEC is `'z'', it defines the conversion `%z'. You can
+- redefine the built-in conversions like `%s', but flag characters
+- like `#' and type modifiers like `l' can never be used as
+- conversions; calling `register_printf_function' for those
+- characters has no effect.
+-
+- The HANDLER-FUNCTION is the function called by `printf' and
+- friends when this conversion appears in a template string. *Note
+- Defining the Output Handler::, for information about how to define
+- a function to pass as this argument. If you specify a null
+- pointer, any existing handler function for SPEC is removed.
+-
+- The ARGINFO-FUNCTION is the function called by
+- `parse_printf_format' when this conversion appears in a template
+- string. *Note Parsing a Template String::, for information about
+- this.
+-
+- *Attention:* In the GNU C library version before 2.0 the
+- ARGINFO-FUNCTION function did not need to be installed unless the
+- user uses the `parse_printf_format' function. This changed. Now
+- a call to any of the `printf' functions will call this function
+- when this format specifier appears in the format string.
+-
+- The return value is `0' on success, and `-1' on failure (which
+- occurs if SPEC is out of range).
+-
+- You can redefine the standard output conversions, but this is
+- probably not a good idea because of the potential for confusion.
+- Library routines written by other people could break if you do
+- this.
+-
+-
+-File: libc.info, Node: Conversion Specifier Options, Next: Defining the
Output Handler, Prev: Registering New Conversions, Up: Customizing Printf
+-
+-Conversion Specifier Options
+-----------------------------
+-
+- If you define a meaning for `%A', what if the template contains
+-`%+23A' or `%-#A'? To implement a sensible meaning for these, the
+-handler when called needs to be able to get the options specified in
+-the template.
+-
+- Both the HANDLER-FUNCTION and ARGINFO-FUNCTION arguments to
+-`register_printf_function' accept an argument that points to a `struct
+-printf_info', which contains information about the options appearing in
+-an instance of the conversion specifier. This data type is declared in
+-the header file `printf.h'.
+-
+- - Type: struct printf_info
+- This structure is used to pass information about the options
+- appearing in an instance of a conversion specifier in a `printf'
+- template string to the handler and arginfo functions for that
+- specifier. It contains the following members:
+-
+- `int prec'
+- This is the precision specified. The value is `-1' if no
+- precision was specified. If the precision was given as `*',
+- the `printf_info' structure passed to the handler function
+- contains the actual value retrieved from the argument list.
+- But the structure passed to the arginfo function contains a
+- value of `INT_MIN', since the actual value is not known.
+-
+- `int width'
+- This is the minimum field width specified. The value is `0'
+- if no width was specified. If the field width was given as
+- `*', the `printf_info' structure passed to the handler
+- function contains the actual value retrieved from the
+- argument list. But the structure passed to the arginfo
+- function contains a value of `INT_MIN', since the actual
+- value is not known.
+-
+- `wchar_t spec'
+- This is the conversion specifier character specified. It's
+- stored in the structure so that you can register the same
+- handler function for multiple characters, but still have a
+- way to tell them apart when the handler function is called.
+-
+- `unsigned int is_long_double'
+- This is a boolean that is true if the `L', `ll', or `q' type
+- modifier was specified. For integer conversions, this
+- indicates `long long int', as opposed to `long double' for
+- floating point conversions.
+-
+- `unsigned int is_short'
+- This is a boolean that is true if the `h' type modifier was
+- specified.
+-
+- `unsigned int is_long'
+- This is a boolean that is true if the `l' type modifier was
+- specified.
+-
+- `unsigned int alt'
+- This is a boolean that is true if the `#' flag was specified.
+-
+- `unsigned int space'
+- This is a boolean that is true if the ` ' flag was specified.
+-
+- `unsigned int left'
+- This is a boolean that is true if the `-' flag was specified.
+-
+- `unsigned int showsign'
+- This is a boolean that is true if the `+' flag was specified.
+-
+- `unsigned int group'
+- This is a boolean that is true if the `'' flag was specified.
+-
+- `unsigned int extra'
+- This flag has a special meaning depending on the context. It
+- could be used freely by the user-defined handlers but when
+- called from the `printf' function this variable always
+- contains the value `0'.
+-
+- `wchar_t pad'
+- This is the character to use for padding the output to the
+- minimum field width. The value is `'0'' if the `0' flag was
+- specified, and `' '' otherwise.
+-
+-
+-File: libc.info, Node: Defining the Output Handler, Next: Printf Extension
Example, Prev: Conversion Specifier Options, Up: Customizing Printf
+-
+-Defining the Output Handler
+----------------------------
+-
+- Now let's look at how to define the handler and arginfo functions
+-which are passed as arguments to `register_printf_function'.
+-
+- *Compatibility Note:* The interface change in the GNU libc version
+-2.0. Previously the third argument was of type `va_list *'.
+-
+- You should define your handler functions with a prototype like:
+-
+- int FUNCTION (FILE *stream, const struct printf_info *info,
+- const void *const *args)
+-
+- The STREAM argument passed to the handler function is the stream to
+-which it should write output.
+-
+- The INFO argument is a pointer to a structure that contains
+-information about the various options that were included with the
+-conversion in the template string. You should not modify this structure
+-inside your handler function. *Note Conversion Specifier Options::, for
+-a description of this data structure.
+-
+- The ARGS is a vector of pointers to the arguments data. The number
+-of arguments were determined by calling the argument information
+-function provided by the user.
+-
+- Your handler function should return a value just like `printf' does:
+-it should return the number of characters it has written, or a negative
+-value to indicate an error.
+-
+- - Data Type: printf_function
+- This is the data type that a handler function should have.
+-
+- If you are going to use `parse_printf_format' in your application,
+-you must also define a function to pass as the ARGINFO-FUNCTION
+-argument for each new conversion you install with
+-`register_printf_function'.
+-
+- You have to define these functions with a prototype like:
+-
+- int FUNCTION (const struct printf_info *info,
+- size_t n, int *argtypes)
+-
+- The return value from the function should be the number of arguments
+-the conversion expects. The function should also fill in no more than
+-N elements of the ARGTYPES array with information about the types of
+-each of these arguments. This information is encoded using the various
+-`PA_' macros. (You will notice that this is the same calling
+-convention `parse_printf_format' itself uses.)
+-
+- - Data Type: printf_arginfo_function
+- This type is used to describe functions that return information
+- about the number and type of arguments used by a conversion
+- specifier.
+-
+-
+-File: libc.info, Node: Printf Extension Example, Prev: Defining the Output
Handler, Up: Customizing Printf
+-
+-`printf' Extension Example
+---------------------------
+-
+- Here is an example showing how to define a `printf' handler function.
+-This program defines a data structure called a `Widget' and defines the
+-`%W' conversion to print information about `Widget *' arguments,
+-including the pointer value and the name stored in the data structure.
+-The `%W' conversion supports the minimum field width and
+-left-justification options, but ignores everything else.
+-
+- #include <stdio.h>
+- #include <printf.h>
+- #include <stdarg.h>
+- typedef struct
+- {
+- char *name;
+- } Widget;
+-
+- int
+- print_widget (FILE *stream, const struct printf_info *info, va_list *app)
+- {
+- Widget *w;
+- char *buffer;
+- int len;
+-
+- /* Format the output into a string. */
+- w = va_arg (*app, Widget *);
+- len = asprintf (&buffer, "<Widget %p: %s>", w, w->name);
+- if (len == -1)
+- return -1;
+-
+- /* Pad to the minimum field width and print to the stream. */
+- len = fprintf (stream, "%*s",
+- (info->left ? - info->width : info->width),
+- buffer);
+-
+- /* Clean up and return. */
+- free (buffer);
+- return len;
+- }
+-
+-
+- int
+- print_widget_arginfo (const struct printf_info *info, size_t n,
+- int *argtypes)
+- {
+- /* We always take exactly one argument and this is a pointer to the
+- structure.. */
+- if (n > 0)
+- argtypes[0] = PA_POINTER;
+- return 1;
+- }
+-
+-
+- int
+- main (void)
+- {
+- /* Make a widget to print. */
+- Widget mywidget;
+- mywidget.name = "mywidget";
+-
+- /* Register the print function for widgets. */
+- register_printf_function ('W', print_widget, print_widget_arginfo);
+-
+- /* Now print the widget. */
+- printf ("|%W|\n", &mywidget);
+- printf ("|%35W|\n", &mywidget);
+- printf ("|%-35W|\n", &mywidget);
+-
+- return 0;
+- }
+-
+- The output produced by this program looks like:
+-
+- |<Widget 0xffeffb7c: mywidget>|
+- | <Widget 0xffeffb7c: mywidget>|
+- |<Widget 0xffeffb7c: mywidget> |
+-
+-
+-File: libc.info, Node: Formatted Input, Next: EOF and Errors, Prev:
Customizing Printf, Up: I/O on Streams
+-
+-Formatted Input
+-===============
+-
+- The functions described in this section (`scanf' and related
+-functions) provide facilities for formatted input analogous to the
+-formatted output facilities. These functions provide a mechanism for
+-reading arbitrary values under the control of a "format string" or
+-"template string".
+-
+-* Menu:
+-
+-* Formatted Input Basics:: Some basics to get you started.
+-* Input Conversion Syntax:: Syntax of conversion specifications.
+-* Table of Input Conversions:: Summary of input conversions and what they do.
+-* Numeric Input Conversions:: Details of conversions for reading numbers.
+-* String Input Conversions:: Details of conversions for reading strings.
+-* Dynamic String Input:: String conversions that `malloc' the buffer.
+-* Other Input Conversions:: Details of miscellaneous other conversions.
+-* Formatted Input Functions:: Descriptions of the actual functions.
+-* Variable Arguments Input:: `vscanf' and friends.
+-
+-
+-File: libc.info, Node: Formatted Input Basics, Next: Input Conversion
Syntax, Up: Formatted Input
+-
+-Formatted Input Basics
+-----------------------
+-
+- Calls to `scanf' are superficially similar to calls to `printf' in
+-that arbitrary arguments are read under the control of a template
+-string. While the syntax of the conversion specifications in the
+-template is very similar to that for `printf', the interpretation of
+-the template is oriented more towards free-format input and simple
+-pattern matching, rather than fixed-field formatting. For example,
+-most `scanf' conversions skip over any amount of "white space"
+-(including spaces, tabs, and newlines) in the input file, and there is
+-no concept of precision for the numeric input conversions as there is
+-for the corresponding output conversions. Ordinarily, non-whitespace
+-characters in the template are expected to match characters in the
+-input stream exactly, but a matching failure is distinct from an input
+-error on the stream.
+-
+- Another area of difference between `scanf' and `printf' is that you
+-must remember to supply pointers rather than immediate values as the
+-optional arguments to `scanf'; the values that are read are stored in
+-the objects that the pointers point to. Even experienced programmers
+-tend to forget this occasionally, so if your program is getting strange
+-errors that seem to be related to `scanf', you might want to
+-double-check this.
+-
+- When a "matching failure" occurs, `scanf' returns immediately,
+-leaving the first non-matching character as the next character to be
+-read from the stream. The normal return value from `scanf' is the
+-number of values that were assigned, so you can use this to determine if
+-a matching error happened before all the expected values were read.
+-
+- The `scanf' function is typically used for things like reading in
+-the contents of tables. For example, here is a function that uses
+-`scanf' to initialize an array of `double':
+-
+- void
+- readarray (double *array, int n)
+- {
+- int i;
+- for (i=0; i<n; i++)
+- if (scanf (" %lf", &(array[i])) != 1)
+- invalid_input_error ();
+- }
+-
+- The formatted input functions are not used as frequently as the
+-formatted output functions. Partly, this is because it takes some care
+-to use them properly. Another reason is that it is difficult to recover
+-from a matching error.
+-
+- If you are trying to read input that doesn't match a single, fixed
+-pattern, you may be better off using a tool such as Flex to generate a
+-lexical scanner, or Bison to generate a parser, rather than using
+-`scanf'. For more information about these tools, see *Note :
+-(flex.info), and *Note : (bison.info).
+-
+-
+-File: libc.info, Node: Input Conversion Syntax, Next: Table of Input
Conversions, Prev: Formatted Input Basics, Up: Formatted Input
+-
+-Input Conversion Syntax
+------------------------
+-
+- A `scanf' template string is a string that contains ordinary
+-multibyte characters interspersed with conversion specifications that
+-start with `%'.
+-
+- Any whitespace character (as defined by the `isspace' function;
+-*note Classification of Characters::.) in the template causes any number
+-of whitespace characters in the input stream to be read and discarded.
+-The whitespace characters that are matched need not be exactly the same
+-whitespace characters that appear in the template string. For example,
+-write ` , ' in the template to recognize a comma with optional
+-whitespace before and after.
+-
+- Other characters in the template string that are not part of
+-conversion specifications must match characters in the input stream
+-exactly; if this is not the case, a matching failure occurs.
+-
+- The conversion specifications in a `scanf' template string have the
+-general form:
+-
+- % FLAGS WIDTH TYPE CONVERSION
+-
+- In more detail, an input conversion specification consists of an
+-initial `%' character followed in sequence by:
+-
+- * An optional "flag character" `*', which says to ignore the text
+- read for this specification. When `scanf' finds a conversion
+- specification that uses this flag, it reads input as directed by
+- the rest of the conversion specification, but it discards this
+- input, does not use a pointer argument, and does not increment the
+- count of successful assignments.
+-
+- * An optional flag character `a' (valid with string conversions only)
+- which requests allocation of a buffer long enough to store the
+- string in. (This is a GNU extension.) *Note Dynamic String
+- Input::.
+-
+- * An optional decimal integer that specifies the "maximum field
+- width". Reading of characters from the input stream stops either
+- when this maximum is reached or when a non-matching character is
+- found, whichever happens first. Most conversions discard initial
+- whitespace characters (those that don't are explicitly
+- documented), and these discarded characters don't count towards
+- the maximum field width. String input conversions store a null
+- character to mark the end of the input; the maximum field width
+- does not include this terminator.
+-
+- * An optional "type modifier character". For example, you can
+- specify a type modifier of `l' with integer conversions such as
+- `%d' to specify that the argument is a pointer to a `long int'
+- rather than a pointer to an `int'.
+-
+- * A character that specifies the conversion to be applied.
+-
+- The exact options that are permitted and how they are interpreted
+-vary between the different conversion specifiers. See the descriptions
+-of the individual conversions for information about the particular
+-options that they allow.
+-
+- With the `-Wformat' option, the GNU C compiler checks calls to
+-`scanf' and related functions. It examines the format string and
+-verifies that the correct number and types of arguments are supplied.
+-There is also a GNU C syntax to tell the compiler that a function you
+-write uses a `scanf'-style format string. *Note Declaring Attributes
+-of Functions: (gcc.info)Function Attributes, for more information.
+-
+-
+-File: libc.info, Node: Table of Input Conversions, Next: Numeric Input
Conversions, Prev: Input Conversion Syntax, Up: Formatted Input
+-
+-Table of Input Conversions
+---------------------------
+-
+- Here is a table that summarizes the various conversion
+-specifications:
+-
+-`%d'
+- Matches an optionally signed integer written in decimal. *Note
+- Numeric Input Conversions::.
+-
+-`%i'
+- Matches an optionally signed integer in any of the formats that
+- the C language defines for specifying an integer constant. *Note
+- Numeric Input Conversions::.
+-
+-`%o'
+- Matches an unsigned integer written in octal radix. *Note Numeric
+- Input Conversions::.
+-
+-`%u'
+- Matches an unsigned integer written in decimal radix. *Note
+- Numeric Input Conversions::.
+-
+-`%x', `%X'
+- Matches an unsigned integer written in hexadecimal radix. *Note
+- Numeric Input Conversions::.
+-
+-`%e', `%f', `%g', `%E', `%G'
+- Matches an optionally signed floating-point number. *Note Numeric
+- Input Conversions::.
+-
+-`%s'
+- Matches a string containing only non-whitespace characters. *Note
+- String Input Conversions::.
+-
+-`%['
+- Matches a string of characters that belong to a specified set.
+- *Note String Input Conversions::.
+-
+-`%c'
+- Matches a string of one or more characters; the number of
+- characters read is controlled by the maximum field width given for
+- the conversion. *Note String Input Conversions::.
+-
+-`%p'
+- Matches a pointer value in the same implementation-defined format
+- used by the `%p' output conversion for `printf'. *Note Other
+- Input Conversions::.
+-
+-`%n'
+- This conversion doesn't read any characters; it records the number
+- of characters read so far by this call. *Note Other Input
+- Conversions::.
+-
+-`%%'
+- This matches a literal `%' character in the input stream. No
+- corresponding argument is used. *Note Other Input Conversions::.
+-
+- If the syntax of a conversion specification is invalid, the behavior
+-is undefined. If there aren't enough function arguments provided to
+-supply addresses for all the conversion specifications in the template
+-strings that perform assignments, or if the arguments are not of the
+-correct types, the behavior is also undefined. On the other hand, extra
+-arguments are simply ignored.
+-
+-
+-File: libc.info, Node: Numeric Input Conversions, Next: String Input
Conversions, Prev: Table of Input Conversions, Up: Formatted Input
+-
+-Numeric Input Conversions
+--------------------------
+-
+- This section describes the `scanf' conversions for reading numeric
+-values.
+-
+- The `%d' conversion matches an optionally signed integer in decimal
+-radix. The syntax that is recognized is the same as that for the
+-`strtol' function (*note Parsing of Integers::.) with the value `10'
+-for the BASE argument.
+-
+- The `%i' conversion matches an optionally signed integer in any of
+-the formats that the C language defines for specifying an integer
+-constant. The syntax that is recognized is the same as that for the
+-`strtol' function (*note Parsing of Integers::.) with the value `0' for
+-the BASE argument. (You can print integers in this syntax with
+-`printf' by using the `#' flag character with the `%x', `%o', or `%d'
+-conversion. *Note Integer Conversions::.)
+-
+- For example, any of the strings `10', `0xa', or `012' could be read
+-in as integers under the `%i' conversion. Each of these specifies a
+-number with decimal value `10'.
+-
+- The `%o', `%u', and `%x' conversions match unsigned integers in
+-octal, decimal, and hexadecimal radices, respectively. The syntax that
+-is recognized is the same as that for the `strtoul' function (*note
+-Parsing of Integers::.) with the appropriate value (`8', `10', or `16')
+-for the BASE argument.
+-
+- The `%X' conversion is identical to the `%x' conversion. They both
+-permit either uppercase or lowercase letters to be used as digits.
+-
+- The default type of the corresponding argument for the `%d' and `%i'
+-conversions is `int *', and `unsigned int *' for the other integer
+-conversions. You can use the following type modifiers to specify other
+-sizes of integer:
+-
+-`h'
+- Specifies that the argument is a `short int *' or `unsigned short
+- int *'.
+-
+-`l'
+- Specifies that the argument is a `long int *' or `unsigned long
+- int *'. Two `l' characters is like the `L' modifier, below.
+-
+-`ll'
+-`L'
+-`q'
+- Specifies that the argument is a `long long int *' or `unsigned
+- long long int *'. (The `long long' type is an extension supported
+- by the GNU C compiler. For systems that don't provide extra-long
+- integers, this is the same as `long int'.)
+-
+- The `q' modifier is another name for the same thing, which comes
+- from 4.4 BSD; a `long long int' is sometimes called a "quad" `int'.
+-
+- All of the `%e', `%f', `%g', `%E', and `%G' input conversions are
+-interchangeable. They all match an optionally signed floating point
+-number, in the same syntax as for the `strtod' function (*note Parsing
+-of Floats::.).
+-
+- For the floating-point input conversions, the default argument type
+-is `float *'. (This is different from the corresponding output
+-conversions, where the default type is `double'; remember that `float'
+-arguments to `printf' are converted to `double' by the default argument
+-promotions, but `float *' arguments are not promoted to `double *'.)
+-You can specify other sizes of float using these type modifiers:
+-
+-`l'
+- Specifies that the argument is of type `double *'.
+-
+-`L'
+- Specifies that the argument is of type `long double *'.
+-
+- For all the above number parsing formats there is an additional
+-optional flag `''. When this flag is given the `scanf' function
+-expects the number represented in the input string to be formatted
+-according to the grouping rules of the currently selected locale (*note
+-General Numeric::.).
+-
+- If the `"C"' or `"POSIX"' locale is selected there is no difference.
+-But for a locale which specifies values for the appropriate fields in
+-the locale the input must have the correct form in the input.
+-Otherwise the longest prefix with a correct form is processed.
+-
+-
+-File: libc.info, Node: String Input Conversions, Next: Dynamic String
Input, Prev: Numeric Input Conversions, Up: Formatted Input
+-
+-String Input Conversions
+-------------------------
+-
+- This section describes the `scanf' input conversions for reading
+-string and character values: `%s', `%[', and `%c'.
+-
+- You have two options for how to receive the input from these
+-conversions:
+-
+- * Provide a buffer to store it in. This is the default. You should
+- provide an argument of type `char *'.
+-
+- *Warning:* To make a robust program, you must make sure that the
+- input (plus its terminating null) cannot possibly exceed the size
+- of the buffer you provide. In general, the only way to do this is
+- to specify a maximum field width one less than the buffer size.
+- *If you provide the buffer, always specify a maximum field width
+- to prevent overflow.*
+-
+- * Ask `scanf' to allocate a big enough buffer, by specifying the `a'
+- flag character. This is a GNU extension. You should provide an
+- argument of type `char **' for the buffer address to be stored in.
+- *Note Dynamic String Input::.
+-
+- The `%c' conversion is the simplest: it matches a fixed number of
+-characters, always. The maximum field with says how many characters to
+-read; if you don't specify the maximum, the default is 1. This
+-conversion doesn't append a null character to the end of the text it
+-reads. It also does not skip over initial whitespace characters. It
+-reads precisely the next N characters, and fails if it cannot get that
+-many. Since there is always a maximum field width with `%c' (whether
+-specified, or 1 by default), you can always prevent overflow by making
+-the buffer long enough.
+-
+- The `%s' conversion matches a string of non-whitespace characters.
+-It skips and discards initial whitespace, but stops when it encounters
+-more whitespace after having read something. It stores a null character
+-at the end of the text that it reads.
+-
+- For example, reading the input:
+-
+- hello, world
+-
+-with the conversion `%10c' produces `" hello, wo"', but reading the
+-same input with the conversion `%10s' produces `"hello,"'.
+-
+- *Warning:* If you do not specify a field width for `%s', then the
+-number of characters read is limited only by where the next whitespace
+-character appears. This almost certainly means that invalid input can
+-make your program crash--which is a bug.
+-
+- To read in characters that belong to an arbitrary set of your choice,
+-use the `%[' conversion. You specify the set between the `[' character
+-and a following `]' character, using the same syntax used in regular
+-expressions. As special cases:
+-
+- * A literal `]' character can be specified as the first character of
+- the set.
+-
+- * An embedded `-' character (that is, one that is not the first or
+- last character of the set) is used to specify a range of
+- characters.
+-
+- * If a caret character `^' immediately follows the initial `[', then
+- the set of allowed input characters is the everything *except* the
+- characters listed.
+-
+- The `%[' conversion does not skip over initial whitespace characters.
+-
+- Here are some examples of `%[' conversions and what they mean:
+-
+-`%25[1234567890]'
+- Matches a string of up to 25 digits.
+-
+-`%25[][]'
+- Matches a string of up to 25 square brackets.
+-
+-`%25[^ \f\n\r\t\v]'
+- Matches a string up to 25 characters long that doesn't contain any
+- of the standard whitespace characters. This is slightly different
+- from `%s', because if the input begins with a whitespace character,
+- `%[' reports a matching failure while `%s' simply discards the
+- initial whitespace.
+-
+-`%25[a-z]'
+- Matches up to 25 lowercase characters.
+-
+- One more reminder: the `%s' and `%[' conversions are *dangerous* if
+-you don't specify a maximum width or use the `a' flag, because input
+-too long would overflow whatever buffer you have provided for it. No
+-matter how long your buffer is, a user could supply input that is
+-longer. A well-written program reports invalid input with a
+-comprehensible error message, not with a crash.
+-
+-
+-File: libc.info, Node: Dynamic String Input, Next: Other Input Conversions,
Prev: String Input Conversions, Up: Formatted Input
+-
+-Dynamically Allocating String Conversions
+------------------------------------------
+-
+- A GNU extension to formatted input lets you safely read a string
+-with no maximum size. Using this feature, you don't supply a buffer;
+-instead, `scanf' allocates a buffer big enough to hold the data and
+-gives you its address. To use this feature, write `a' as a flag
+-character, as in `%as' or `%a[0-9a-z]'.
+-
+- The pointer argument you supply for where to store the input should
+-have type `char **'. The `scanf' function allocates a buffer and
+-stores its address in the word that the argument points to. You should
+-free the buffer with `free' when you no longer need it.
+-
+- Here is an example of using the `a' flag with the `%[...]'
+-conversion specification to read a "variable assignment" of the form
+-`VARIABLE = VALUE'.
+-
+- {
+- char *variable, *value;
+-
+- if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
+- &variable, &value))
+- {
+- invalid_input_error ();
+- return 0;
+- }
+-
+- ...
+- }
+-
+-
+-File: libc.info, Node: Other Input Conversions, Next: Formatted Input
Functions, Prev: Dynamic String Input, Up: Formatted Input
+-
+-Other Input Conversions
+------------------------
+-
+- This section describes the miscellaneous input conversions.
+-
+- The `%p' conversion is used to read a pointer value. It recognizes
+-the same syntax as is used by the `%p' output conversion for `printf'
+-(*note Other Output Conversions::.); that is, a hexadecimal number just
+-as the `%x' conversion accepts. The corresponding argument should be
+-of type `void **'; that is, the address of a place to store a pointer.
+-
+- The resulting pointer value is not guaranteed to be valid if it was
+-not originally written during the same program execution that reads it
+-in.
+-
+- The `%n' conversion produces the number of characters read so far by
+-this call. The corresponding argument should be of type `int *'. This
+-conversion works in the same way as the `%n' conversion for `printf';
+-see *Note Other Output Conversions::, for an example.
+-
+- The `%n' conversion is the only mechanism for determining the
+-success of literal matches or conversions with suppressed assignments.
+-If the `%n' follows the locus of a matching failure, then no value is
+-stored for it since `scanf' returns before processing the `%n'. If you
+-store `-1' in that argument slot before calling `scanf', the presence
+-of `-1' after `scanf' indicates an error occurred before the `%n' was
+-reached.
+-
+- Finally, the `%%' conversion matches a literal `%' character in the
+-input stream, without using an argument. This conversion does not
+-permit any flags, field width, or type modifier to be specified.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-8
glibc-2.0.1/manual/libc.info-8
+--- ../glibc-2.0.1/manual/libc.info-8 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-8 1970-01-01 01:00:00.000000000 +0100
+@@ -1,1094 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+- This file documents the GNU C library.
+-
+- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+- Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+- Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+- Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: Formatted Input Functions, Next: Variable Arguments
Input, Prev: Other Input Conversions, Up: Formatted Input
+-
+-Formatted Input Functions
+--------------------------
+-
+- Here are the descriptions of the functions for performing formatted
+-input. Prototypes for these functions are in the header file `stdio.h'.
+-
+- - Function: int scanf (const char *TEMPLATE, ...)
+- The `scanf' function reads formatted input from the stream `stdin'
+- under the control of the template string TEMPLATE. The optional
+- arguments are pointers to the places which receive the resulting
+- values.
+-
+- The return value is normally the number of successful assignments.
+- If an end-of-file condition is detected before any matches are
+- performed (including matches against whitespace and literal
+- characters in the template), then `EOF' is returned.
+-
+- - Function: int fscanf (FILE *STREAM, const char *TEMPLATE, ...)
+- This function is just like `scanf', except that the input is read
+- from the stream STREAM instead of `stdin'.
+-
+- - Function: int sscanf (const char *S, const char *TEMPLATE, ...)
+- This is like `scanf', except that the characters are taken from the
+- null-terminated string S instead of from a stream. Reaching the
+- end of the string is treated as an end-of-file condition.
+-
+- The behavior of this function is undefined if copying takes place
+- between objects that overlap--for example, if S is also given as
+- an argument to receive a string read under control of the `%s'
+- conversion.
+-
+-
+-File: libc.info, Node: Variable Arguments Input, Prev: Formatted Input
Functions, Up: Formatted Input
+-
+-Variable Arguments Input Functions
+-----------------------------------
+-
+- The functions `vscanf' and friends are provided so that you can
+-define your own variadic `scanf'-like functions that make use of the
+-same internals as the built-in formatted output functions. These
+-functions are analogous to the `vprintf' series of output functions.
+-*Note Variable Arguments Output::, for important information on how to
+-use them.
+-
+- *Portability Note:* The functions listed in this section are GNU
+-extensions.
+-
+- - Function: int vscanf (const char *TEMPLATE, va_list AP)
+- This function is similar to `scanf' except that, instead of taking
+- a variable number of arguments directly, it takes an argument list
+- pointer AP of type `va_list' (*note Variadic Functions::.).
+-
+- - Function: int vfscanf (FILE *STREAM, const char *TEMPLATE, va_list
+- AP)
+- This is the equivalent of `fscanf' with the variable argument list
+- specified directly as for `vscanf'.
+-
+- - Function: int vsscanf (const char *S, const char *TEMPLATE, va_list
+- AP)
+- This is the equivalent of `sscanf' with the variable argument list
+- specified directly as for `vscanf'.
+-
+- In GNU C, there is a special construct you can use to let the
+-compiler know that a function uses a `scanf'-style format string. Then
+-it can check the number and types of arguments in each call to the
+-function, and warn you when they do not match the format string. *Note
+-Declaring Attributes of Functions: (gcc.info)Function Attributes, for
+-details.
+-
+-
+-File: libc.info, Node: EOF and Errors, Next: Binary Streams, Prev:
Formatted Input, Up: I/O on Streams
+-
+-End-Of-File and Errors
+-======================
+-
+- Many of the functions described in this chapter return the value of
+-the macro `EOF' to indicate unsuccessful completion of the operation.
+-Since `EOF' is used to report both end of file and random errors, it's
+-often better to use the `feof' function to check explicitly for end of
+-file and `ferror' to check for errors. These functions check
+-indicators that are part of the internal state of the stream object,
+-indicators set if the appropriate condition was detected by a previous
+-I/O operation on that stream.
+-
+- These symbols are declared in the header file `stdio.h'.
+-
+- - Macro: int EOF
+- This macro is an integer value that is returned by a number of
+- functions to indicate an end-of-file condition, or some other
+- error situation. With the GNU library, `EOF' is `-1'. In other
+- libraries, its value may be some other negative number.
+-
+- - Function: void clearerr (FILE *STREAM)
+- This function clears the end-of-file and error indicators for the
+- stream STREAM.
+-
+- The file positioning functions (*note File Positioning::.) also
+- clear the end-of-file indicator for the stream.
+-
+- - Function: int feof (FILE *STREAM)
+- The `feof' function returns nonzero if and only if the end-of-file
+- indicator for the stream STREAM is set.
+-
+- - Function: int ferror (FILE *STREAM)
+- The `ferror' function returns nonzero if and only if the error
+- indicator for the stream STREAM is set, indicating that an error
+- has occurred on a previous operation on the stream.
+-
+- In addition to setting the error indicator associated with the
+-stream, the functions that operate on streams also set `errno' in the
+-same way as the corresponding low-level functions that operate on file
+-descriptors. For example, all of the functions that perform output to a
+-stream--such as `fputc', `printf', and `fflush'--are implemented in
+-terms of `write', and all of the `errno' error conditions defined for
+-`write' are meaningful for these functions. For more information about
+-the descriptor-level I/O functions, see *Note Low-Level I/O::.
+-
+-
+-File: libc.info, Node: Binary Streams, Next: File Positioning, Prev: EOF
and Errors, Up: I/O on Streams
+-
+-Text and Binary Streams
+-=======================
+-
+- The GNU system and other POSIX-compatible operating systems organize
+-all files as uniform sequences of characters. However, some other
+-systems make a distinction between files containing text and files
+-containing binary data, and the input and output facilities of ISO C
+-provide for this distinction. This section tells you how to write
+-programs portable to such systems.
+-
+- When you open a stream, you can specify either a "text stream" or a
+-"binary stream". You indicate that you want a binary stream by
+-specifying the `b' modifier in the OPENTYPE argument to `fopen'; see
+-*Note Opening Streams::. Without this option, `fopen' opens the file
+-as a text stream.
+-
+- Text and binary streams differ in several ways:
+-
+- * The data read from a text stream is divided into "lines" which are
+- terminated by newline (`'\n'') characters, while a binary stream is
+- simply a long series of characters. A text stream might on some
+- systems fail to handle lines more than 254 characters long
+- (including the terminating newline character).
+-
+- * On some systems, text files can contain only printing characters,
+- horizontal tab characters, and newlines, and so text streams may
+- not support other characters. However, binary streams can handle
+- any character value.
+-
+- * Space characters that are written immediately preceding a newline
+- character in a text stream may disappear when the file is read in
+- again.
+-
+- * More generally, there need not be a one-to-one mapping between
+- characters that are read from or written to a text stream, and the
+- characters in the actual file.
+-
+- Since a binary stream is always more capable and more predictable
+-than a text stream, you might wonder what purpose text streams serve.
+-Why not simply always use binary streams? The answer is that on these
+-operating systems, text and binary streams use different file formats,
+-and the only way to read or write "an ordinary file of text" that can
+-work with other text-oriented programs is through a text stream.
+-
+- In the GNU library, and on all POSIX systems, there is no difference
+-between text streams and binary streams. When you open a stream, you
+-get the same kind of stream regardless of whether you ask for binary.
+-This stream can handle any file content, and has none of the
+-restrictions that text streams sometimes have.
+-
+-
+-File: libc.info, Node: File Positioning, Next: Portable Positioning, Prev:
Binary Streams, Up: I/O on Streams
+-
+-File Positioning
+-================
+-
+- The "file position" of a stream describes where in the file the
+-stream is currently reading or writing. I/O on the stream advances the
+-file position through the file. In the GNU system, the file position is
+-represented as an integer, which counts the number of bytes from the
+-beginning of the file. *Note File Position::.
+-
+- During I/O to an ordinary disk file, you can change the file position
+-whenever you wish, so as to read or write any portion of the file. Some
+-other kinds of files may also permit this. Files which support changing
+-the file position are sometimes referred to as "random-access" files.
+-
+- You can use the functions in this section to examine or modify the
+-file position indicator associated with a stream. The symbols listed
+-below are declared in the header file `stdio.h'.
+-
+- - Function: long int ftell (FILE *STREAM)
+- This function returns the current file position of the stream
+- STREAM.
+-
+- This function can fail if the stream doesn't support file
+- positioning, or if the file position can't be represented in a
+- `long int', and possibly for other reasons as well. If a failure
+- occurs, a value of `-1' is returned.
+-
+- - Function: int fseek (FILE *STREAM, long int OFFSET, int WHENCE)
+- The `fseek' function is used to change the file position of the
+- stream STREAM. The value of WHENCE must be one of the constants
+- `SEEK_SET', `SEEK_CUR', or `SEEK_END', to indicate whether the
+- OFFSET is relative to the beginning of the file, the current file
+- position, or the end of the file, respectively.
+-
+- This function returns a value of zero if the operation was
+- successful, and a nonzero value to indicate failure. A successful
+- call also clears the end-of-file indicator of STREAM and discards
+- any characters that were "pushed back" by the use of `ungetc'.
+-
+- `fseek' either flushes any buffered output before setting the file
+- position or else remembers it so it will be written later in its
+- proper place in the file.
+-
+- *Portability Note:* In non-POSIX systems, `ftell' and `fseek' might
+-work reliably only on binary streams. *Note Binary Streams::.
+-
+- The following symbolic constants are defined for use as the WHENCE
+-argument to `fseek'. They are also used with the `lseek' function
+-(*note I/O Primitives::.) and to specify offsets for file locks (*note
+-Control Operations::.).
+-
+- - Macro: int SEEK_SET
+- This is an integer constant which, when used as the WHENCE
+- argument to the `fseek' function, specifies that the offset
+- provided is relative to the beginning of the file.
+-
+- - Macro: int SEEK_CUR
+- This is an integer constant which, when used as the WHENCE
+- argument to the `fseek' function, specifies that the offset
+- provided is relative to the current file position.
+-
+- - Macro: int SEEK_END
+- This is an integer constant which, when used as the WHENCE
+- argument to the `fseek' function, specifies that the offset
+- provided is relative to the end of the file.
+-
+- - Function: void rewind (FILE *STREAM)
+- The `rewind' function positions the stream STREAM at the begining
+- of the file. It is equivalent to calling `fseek' on the STREAM
+- with an OFFSET argument of `0L' and a WHENCE argument of
+- `SEEK_SET', except that the return value is discarded and the
+- error indicator for the stream is reset.
+-
+- These three aliases for the `SEEK_...' constants exist for the sake
+-of compatibility with older BSD systems. They are defined in two
+-different header files: `fcntl.h' and `sys/file.h'.
+-
+-`L_SET'
+- An alias for `SEEK_SET'.
+-
+-`L_INCR'
+- An alias for `SEEK_CUR'.
+-
+-`L_XTND'
+- An alias for `SEEK_END'.
+-
+-
+-File: libc.info, Node: Portable Positioning, Next: Stream Buffering, Prev:
File Positioning, Up: I/O on Streams
+-
+-Portable File-Position Functions
+-================================
+-
+- On the GNU system, the file position is truly a character count. You
+-can specify any character count value as an argument to `fseek' and get
+-reliable results for any random access file. However, some ISO C
+-systems do not represent file positions in this way.
+-
+- On some systems where text streams truly differ from binary streams,
+-it is impossible to represent the file position of a text stream as a
+-count of characters from the beginning of the file. For example, the
+-file position on some systems must encode both a record offset within
+-the file, and a character offset within the record.
+-
+- As a consequence, if you want your programs to be portable to these
+-systems, you must observe certain rules:
+-
+- * The value returned from `ftell' on a text stream has no predictable
+- relationship to the number of characters you have read so far.
+- The only thing you can rely on is that you can use it subsequently
+- as the OFFSET argument to `fseek' to move back to the same file
+- position.
+-
+- * In a call to `fseek' on a text stream, either the OFFSET must
+- either be zero; or WHENCE must be `SEEK_SET' and the OFFSET must
+- be the result of an earlier call to `ftell' on the same stream.
+-
+- * The value of the file position indicator of a text stream is
+- undefined while there are characters that have been pushed back
+- with `ungetc' that haven't been read or discarded. *Note
+- Unreading::.
+-
+- But even if you observe these rules, you may still have trouble for
+-long files, because `ftell' and `fseek' use a `long int' value to
+-represent the file position. This type may not have room to encode all
+-the file positions in a large file.
+-
+- So if you do want to support systems with peculiar encodings for the
+-file positions, it is better to use the functions `fgetpos' and
+-`fsetpos' instead. These functions represent the file position using
+-the data type `fpos_t', whose internal representation varies from
+-system to system.
+-
+- These symbols are declared in the header file `stdio.h'.
+-
+- - Data Type: fpos_t
+- This is the type of an object that can encode information about the
+- file position of a stream, for use by the functions `fgetpos' and
+- `fsetpos'.
+-
+- In the GNU system, `fpos_t' is equivalent to `off_t' or `long
+- int'. In other systems, it might have a different internal
+- representation.
+-
+- - Function: int fgetpos (FILE *STREAM, fpos_t *POSITION)
+- This function stores the value of the file position indicator for
+- the stream STREAM in the `fpos_t' object pointed to by POSITION.
+- If successful, `fgetpos' returns zero; otherwise it returns a
+- nonzero value and stores an implementation-defined positive value
+- in `errno'.
+-
+- - Function: int fsetpos (FILE *STREAM, const fpos_t POSITION)
+- This function sets the file position indicator for the stream
+- STREAM to the position POSITION, which must have been set by a
+- previous call to `fgetpos' on the same stream. If successful,
+- `fsetpos' clears the end-of-file indicator on the stream, discards
+- any characters that were "pushed back" by the use of `ungetc', and
+- returns a value of zero. Otherwise, `fsetpos' returns a nonzero
+- value and stores an implementation-defined positive value in
+- `errno'.
+-
+-
+-File: libc.info, Node: Stream Buffering, Next: Other Kinds of Streams,
Prev: Portable Positioning, Up: I/O on Streams
+-
+-Stream Buffering
+-================
+-
+- Characters that are written to a stream are normally accumulated and
+-transmitted asynchronously to the file in a block, instead of appearing
+-as soon as they are output by the application program. Similarly,
+-streams often retrieve input from the host environment in blocks rather
+-than on a character-by-character basis. This is called "buffering".
+-
+- If you are writing programs that do interactive input and output
+-using streams, you need to understand how buffering works when you
+-design the user interface to your program. Otherwise, you might find
+-that output (such as progress or prompt messages) doesn't appear when
+-you intended it to, or other unexpected behavior.
+-
+- This section deals only with controlling when characters are
+-transmitted between the stream and the file or device, and *not* with
+-how things like echoing, flow control, and the like are handled on
+-specific classes of devices. For information on common control
+-operations on terminal devices, see *Note Low-Level Terminal
+-Interface::.
+-
+- You can bypass the stream buffering facilities altogether by using
+-the low-level input and output functions that operate on file
+-descriptors instead. *Note Low-Level I/O::.
+-
+-* Menu:
+-
+-* Buffering Concepts:: Terminology is defined here.
+-* Flushing Buffers:: How to ensure that output buffers are flushed.
+-* Controlling Buffering:: How to specify what kind of buffering to use.
+-
+-
+-File: libc.info, Node: Buffering Concepts, Next: Flushing Buffers, Up:
Stream Buffering
+-
+-Buffering Concepts
+-------------------
+-
+- There are three different kinds of buffering strategies:
+-
+- * Characters written to or read from an "unbuffered" stream are
+- transmitted individually to or from the file as soon as possible.
+-
+- * Characters written to a "line buffered" stream are transmitted to
+- the file in blocks when a newline character is encountered.
+-
+- * Characters written to or read from a "fully buffered" stream are
+- transmitted to or from the file in blocks of arbitrary size.
+-
+- Newly opened streams are normally fully buffered, with one
+-exception: a stream connected to an interactive device such as a
+-terminal is initially line buffered. *Note Controlling Buffering::,
+-for information on how to select a different kind of buffering.
+-Usually the automatic selection gives you the most convenient kind of
+-buffering for the file or device you open.
+-
+- The use of line buffering for interactive devices implies that output
+-messages ending in a newline will appear immediately--which is usually
+-what you want. Output that doesn't end in a newline might or might not
+-show up immediately, so if you want them to appear immediately, you
+-should flush buffered output explicitly with `fflush', as described in
+-*Note Flushing Buffers::.
+-
+-
+-File: libc.info, Node: Flushing Buffers, Next: Controlling Buffering,
Prev: Buffering Concepts, Up: Stream Buffering
+-
+-Flushing Buffers
+-----------------
+-
+- "Flushing" output on a buffered stream means transmitting all
+-accumulated characters to the file. There are many circumstances when
+-buffered output on a stream is flushed automatically:
+-
+- * When you try to do output and the output buffer is full.
+-
+- * When the stream is closed. *Note Closing Streams::.
+-
+- * When the program terminates by calling `exit'. *Note Normal
+- Termination::.
+-
+- * When a newline is written, if the stream is line buffered.
+-
+- * Whenever an input operation on *any* stream actually reads data
+- from its file.
+-
+- If you want to flush the buffered output at another time, call
+-`fflush', which is declared in the header file `stdio.h'.
+-
+- - Function: int fflush (FILE *STREAM)
+- This function causes any buffered output on STREAM to be delivered
+- to the file. If STREAM is a null pointer, then `fflush' causes
+- buffered output on *all* open output streams to be flushed.
+-
+- This function returns `EOF' if a write error occurs, or zero
+- otherwise.
+-
+- *Compatibility Note:* Some brain-damaged operating systems have been
+-known to be so thoroughly fixated on line-oriented input and output
+-that flushing a line buffered stream causes a newline to be written!
+-Fortunately, this "feature" seems to be becoming less common. You do
+-not need to worry about this in the GNU system.
+-
+-
+-File: libc.info, Node: Controlling Buffering, Prev: Flushing Buffers, Up:
Stream Buffering
+-
+-Controlling Which Kind of Buffering
+------------------------------------
+-
+- After opening a stream (but before any other operations have been
+-performed on it), you can explicitly specify what kind of buffering you
+-want it to have using the `setvbuf' function.
+-
+- The facilities listed in this section are declared in the header
+-file `stdio.h'.
+-
+- - Function: int setvbuf (FILE *STREAM, char *BUF, int MODE, size_t
+- SIZE)
+- This function is used to specify that the stream STREAM should
+- have the buffering mode MODE, which can be either `_IOFBF' (for
+- full buffering), `_IOLBF' (for line buffering), or `_IONBF' (for
+- unbuffered input/output).
+-
+- If you specify a null pointer as the BUF argument, then `setvbuf'
+- allocates a buffer itself using `malloc'. This buffer will be
+- freed when you close the stream.
+-
+- Otherwise, BUF should be a character array that can hold at least
+- SIZE characters. You should not free the space for this array as
+- long as the stream remains open and this array remains its buffer.
+- You should usually either allocate it statically, or `malloc'
+- (*note Unconstrained Allocation::.) the buffer. Using an
+- automatic array is not a good idea unless you close the file
+- before exiting the block that declares the array.
+-
+- While the array remains a stream buffer, the stream I/O functions
+- will use the buffer for their internal purposes. You shouldn't
+- try to access the values in the array directly while the stream is
+- using it for buffering.
+-
+- The `setvbuf' function returns zero on success, or a nonzero value
+- if the value of MODE is not valid or if the request could not be
+- honored.
+-
+- - Macro: int _IOFBF
+- The value of this macro is an integer constant expression that can
+- be used as the MODE argument to the `setvbuf' function to specify
+- that the stream should be fully buffered.
+-
+- - Macro: int _IOLBF
+- The value of this macro is an integer constant expression that can
+- be used as the MODE argument to the `setvbuf' function to specify
+- that the stream should be line buffered.
+-
+- - Macro: int _IONBF
+- The value of this macro is an integer constant expression that can
+- be used as the MODE argument to the `setvbuf' function to specify
+- that the stream should be unbuffered.
+-
+- - Macro: int BUFSIZ
+- The value of this macro is an integer constant expression that is
+- good to use for the SIZE argument to `setvbuf'. This value is
+- guaranteed to be at least `256'.
+-
+- The value of `BUFSIZ' is chosen on each system so as to make stream
+- I/O efficient. So it is a good idea to use `BUFSIZ' as the size
+- for the buffer when you call `setvbuf'.
+-
+- Actually, you can get an even better value to use for the buffer
+- size by means of the `fstat' system call: it is found in the
+- `st_blksize' field of the file attributes. *Note Attribute
+- Meanings::.
+-
+- Sometimes people also use `BUFSIZ' as the allocation size of
+- buffers used for related purposes, such as strings used to receive
+- a line of input with `fgets' (*note Character Input::.). There is
+- no particular reason to use `BUFSIZ' for this instead of any other
+- integer, except that it might lead to doing I/O in chunks of an
+- efficient size.
+-
+- - Function: void setbuf (FILE *STREAM, char *BUF)
+- If BUF is a null pointer, the effect of this function is
+- equivalent to calling `setvbuf' with a MODE argument of `_IONBF'.
+- Otherwise, it is equivalent to calling `setvbuf' with BUF, and a
+- MODE of `_IOFBF' and a SIZE argument of `BUFSIZ'.
+-
+- The `setbuf' function is provided for compatibility with old code;
+- use `setvbuf' in all new programs.
+-
+- - Function: void setbuffer (FILE *STREAM, char *BUF, size_t SIZE)
+- If BUF is a null pointer, this function makes STREAM unbuffered.
+- Otherwise, it makes STREAM fully buffered using BUF as the buffer.
+- The SIZE argument specifies the length of BUF.
+-
+- This function is provided for compatibility with old BSD code. Use
+- `setvbuf' instead.
+-
+- - Function: void setlinebuf (FILE *STREAM)
+- This function makes STREAM be line buffered, and allocates the
+- buffer for you.
+-
+- This function is provided for compatibility with old BSD code. Use
+- `setvbuf' instead.
+-
+-
+-File: libc.info, Node: Other Kinds of Streams, Prev: Stream Buffering, Up:
I/O on Streams
+-
+-Other Kinds of Streams
+-======================
+-
+- The GNU library provides ways for you to define additional kinds of
+-streams that do not necessarily correspond to an open file.
+-
+- One such type of stream takes input from or writes output to a
+-string. These kinds of streams are used internally to implement the
+-`sprintf' and `sscanf' functions. You can also create such a stream
+-explicitly, using the functions described in *Note String Streams::.
+-
+- More generally, you can define streams that do input/output to
+-arbitrary objects using functions supplied by your program. This
+-protocol is discussed in *Note Custom Streams::.
+-
+- *Portability Note:* The facilities described in this section are
+-specific to GNU. Other systems or C implementations might or might not
+-provide equivalent functionality.
+-
+-* Menu:
+-
+-* String Streams:: Streams that get data from or put data in
+- a string or memory buffer.
+-* Obstack Streams:: Streams that store data in an obstack.
+-* Custom Streams:: Defining your own streams with an arbitrary
+- input data source and/or output data sink.
+-
+-
+-File: libc.info, Node: String Streams, Next: Obstack Streams, Up: Other
Kinds of Streams
+-
+-String Streams
+---------------
+-
+- The `fmemopen' and `open_memstream' functions allow you to do I/O to
+-a string or memory buffer. These facilities are declared in `stdio.h'.
+-
+- - Function: FILE * fmemopen (void *BUF, size_t SIZE, const char
+- *OPENTYPE)
+- This function opens a stream that allows the access specified by
+- the OPENTYPE argument, that reads from or writes to the buffer
+- specified by the argument BUF. This array must be at least SIZE
+- bytes long.
+-
+- If you specify a null pointer as the BUF argument, `fmemopen'
+- dynamically allocates (as with `malloc'; *note Unconstrained
+- Allocation::.) an array SIZE bytes long. This is really only
+- useful if you are going to write things to the buffer and then
+- read them back in again, because you have no way of actually
+- getting a pointer to the buffer (for this, try `open_memstream',
+- below). The buffer is freed when the stream is open.
+-
+- The argument OPENTYPE is the same as in `fopen' (*Note Opening
+- Streams::). If the OPENTYPE specifies append mode, then the
+- initial file position is set to the first null character in the
+- buffer. Otherwise the initial file position is at the beginning
+- of the buffer.
+-
+- When a stream open for writing is flushed or closed, a null
+- character (zero byte) is written at the end of the buffer if it
+- fits. You should add an extra byte to the SIZE argument to
+- account for this. Attempts to write more than SIZE bytes to the
+- buffer result in an error.
+-
+- For a stream open for reading, null characters (zero bytes) in the
+- buffer do not count as "end of file". Read operations indicate
+- end of file only when the file position advances past SIZE bytes.
+- So, if you want to read characters from a null-terminated string,
+- you should supply the length of the string as the SIZE argument.
+-
+- Here is an example of using `fmemopen' to create a stream for
+-reading from a string:
+-
+- #include <stdio.h>
+-
+- static char buffer[] = "foobar";
+-
+- int
+- main (void)
+- {
+- int ch;
+- FILE *stream;
+-
+- stream = fmemopen (buffer, strlen (buffer), "r");
+- while ((ch = fgetc (stream)) != EOF)
+- printf ("Got %c\n", ch);
+- fclose (stream);
+-
+- return 0;
+- }
+-
+- This program produces the following output:
+-
+- Got f
+- Got o
+- Got o
+- Got b
+- Got a
+- Got r
+-
+- - Function: FILE * open_memstream (char **PTR, size_t *SIZELOC)
+- This function opens a stream for writing to a buffer. The buffer
+- is allocated dynamically (as with `malloc'; *note Unconstrained
+- Allocation::.) and grown as necessary.
+-
+- When the stream is closed with `fclose' or flushed with `fflush',
+- the locations PTR and SIZELOC are updated to contain the pointer
+- to the buffer and its size. The values thus stored remain valid
+- only as long as no further output on the stream takes place. If
+- you do more output, you must flush the stream again to store new
+- values before you use them again.
+-
+- A null character is written at the end of the buffer. This null
+- character is *not* included in the size value stored at SIZELOC.
+-
+- You can move the stream's file position with `fseek' (*note File
+- Positioning::.). Moving the file position past the end of the data
+- already written fills the intervening space with zeroes.
+-
+- Here is an example of using `open_memstream':
+-
+- #include <stdio.h>
+-
+- int
+- main (void)
+- {
+- char *bp;
+- size_t size;
+- FILE *stream;
+-
+- stream = open_memstream (&bp, &size);
+- fprintf (stream, "hello");
+- fflush (stream);
+- printf ("buf = `%s', size = %d\n", bp, size);
+- fprintf (stream, ", world");
+- fclose (stream);
+- printf ("buf = `%s', size = %d\n", bp, size);
+-
+- return 0;
+- }
+-
+- This program produces the following output:
+-
+- buf = `hello', size = 5
+- buf = `hello, world', size = 12
+-
+-
+-File: libc.info, Node: Obstack Streams, Next: Custom Streams, Prev: String
Streams, Up: Other Kinds of Streams
+-
+-Obstack Streams
+----------------
+-
+- You can open an output stream that puts it data in an obstack.
+-*Note Obstacks::.
+-
+- - Function: FILE * open_obstack_stream (struct obstack *OBSTACK)
+- This function opens a stream for writing data into the obstack
+- OBSTACK. This starts an object in the obstack and makes it grow
+- as data is written (*note Growing Objects::.).
+-
+- Calling `fflush' on this stream updates the current size of the
+- object to match the amount of data that has been written. After a
+- call to `fflush', you can examine the object temporarily.
+-
+- You can move the file position of an obstack stream with `fseek'
+- (*note File Positioning::.). Moving the file position past the
+- end of the data written fills the intervening space with zeros.
+-
+- To make the object permanent, update the obstack with `fflush', and
+- then use `obstack_finish' to finalize the object and get its
+- address. The following write to the stream starts a new object in
+- the obstack, and later writes add to that object until you do
+- another `fflush' and `obstack_finish'.
+-
+- But how do you find out how long the object is? You can get the
+- length in bytes by calling `obstack_object_size' (*note Status of
+- an Obstack::.), or you can null-terminate the object like this:
+-
+- obstack_1grow (OBSTACK, 0);
+-
+- Whichever one you do, you must do it *before* calling
+- `obstack_finish'. (You can do both if you wish.)
+-
+- Here is a sample function that uses `open_obstack_stream':
+-
+- char *
+- make_message_string (const char *a, int b)
+- {
+- FILE *stream = open_obstack_stream (&message_obstack);
+- output_task (stream);
+- fprintf (stream, ": ");
+- fprintf (stream, a, b);
+- fprintf (stream, "\n");
+- fclose (stream);
+- obstack_1grow (&message_obstack, 0);
+- return obstack_finish (&message_obstack);
+- }
+-
+-
+-File: libc.info, Node: Custom Streams, Prev: Obstack Streams, Up: Other
Kinds of Streams
+-
+-Programming Your Own Custom Streams
+------------------------------------
+-
+- This section describes how you can make a stream that gets input
+-from an arbitrary data source or writes output to an arbitrary data sink
+-programmed by you. We call these "custom streams".
+-
+-* Menu:
+-
+-* Streams and Cookies:: The "cookie" records where to fetch or
+- store data that is read or written.
+-* Hook Functions:: How you should define the four "hook
+- functions" that a custom stream needs.
+-
+-
+-File: libc.info, Node: Streams and Cookies, Next: Hook Functions, Up:
Custom Streams
+-
+-Custom Streams and Cookies
+-..........................
+-
+- Inside every custom stream is a special object called the "cookie".
+-This is an object supplied by you which records where to fetch or store
+-the data read or written. It is up to you to define a data type to use
+-for the cookie. The stream functions in the library never refer
+-directly to its contents, and they don't even know what the type is;
+-they record its address with type `void *'.
+-
+- To implement a custom stream, you must specify *how* to fetch or
+-store the data in the specified place. You do this by defining "hook
+-functions" to read, write, change "file position", and close the
+-stream. All four of these functions will be passed the stream's cookie
+-so they can tell where to fetch or store the data. The library
+-functions don't know what's inside the cookie, but your functions will
+-know.
+-
+- When you create a custom stream, you must specify the cookie pointer,
+-and also the four hook functions stored in a structure of type
+-`cookie_io_functions_t'.
+-
+- These facilities are declared in `stdio.h'.
+-
+- - Data Type: cookie_io_functions_t
+- This is a structure type that holds the functions that define the
+- communications protocol between the stream and its cookie. It has
+- the following members:
+-
+- `cookie_read_function_t *read'
+- This is the function that reads data from the cookie. If the
+- value is a null pointer instead of a function, then read
+- operations on ths stream always return `EOF'.
+-
+- `cookie_write_function_t *write'
+- This is the function that writes data to the cookie. If the
+- value is a null pointer instead of a function, then data
+- written to the stream is discarded.
+-
+- `cookie_seek_function_t *seek'
+- This is the function that performs the equivalent of file
+- positioning on the cookie. If the value is a null pointer
+- instead of a function, calls to `fseek' on this stream can
+- only seek to locations within the buffer; any attempt to seek
+- outside the buffer will return an `ESPIPE' error.
+-
+- `cookie_close_function_t *close'
+- This function performs any appropriate cleanup on the cookie
+- when closing the stream. If the value is a null pointer
+- instead of a function, nothing special is done to close the
+- cookie when the stream is closed.
+-
+- - Function: FILE * fopencookie (void *COOKIE, const char *OPENTYPE,
+- cookie_io_functions_t IO-FUNCTIONS)
+- This function actually creates the stream for communicating with
+- the COOKIE using the functions in the IO-FUNCTIONS argument. The
+- OPENTYPE argument is interpreted as for `fopen'; see *Note Opening
+- Streams::. (But note that the "truncate on open" option is
+- ignored.) The new stream is fully buffered.
+-
+- The `fopencookie' function returns the newly created stream, or a
+- null pointer in case of an error.
+-
+-
+-File: libc.info, Node: Hook Functions, Prev: Streams and Cookies, Up:
Custom Streams
+-
+-Custom Stream Hook Functions
+-............................
+-
+- Here are more details on how you should define the four hook
+-functions that a custom stream needs.
+-
+- You should define the function to read data from the cookie as:
+-
+- ssize_t READER (void *COOKIE, void *BUFFER, size_t SIZE)
+-
+- This is very similar to the `read' function; see *Note I/O
+-Primitives::. Your function should transfer up to SIZE bytes into the
+-BUFFER, and return the number of bytes read, or zero to indicate
+-end-of-file. You can return a value of `-1' to indicate an error.
+-
+- You should define the function to write data to the cookie as:
+-
+- ssize_t WRITER (void *COOKIE, const void *BUFFER, size_t SIZE)
+-
+- This is very similar to the `write' function; see *Note I/O
+-Primitives::. Your function should transfer up to SIZE bytes from the
+-buffer, and return the number of bytes written. You can return a value
+-of `-1' to indicate an error.
+-
+- You should define the function to perform seek operations on the
+-cookie as:
+-
+- int SEEKER (void *COOKIE, fpos_t *POSITION, int WHENCE)
+-
+- For this function, the POSITION and WHENCE arguments are interpreted
+-as for `fgetpos'; see *Note Portable Positioning::. In the GNU
+-library, `fpos_t' is equivalent to `off_t' or `long int', and simply
+-represents the number of bytes from the beginning of the file.
+-
+- After doing the seek operation, your function should store the
+-resulting file position relative to the beginning of the file in
+-POSITION. Your function should return a value of `0' on success and
+-`-1' to indicate an error.
+-
+- You should define the function to do cleanup operations on the cookie
+-appropriate for closing the stream as:
+-
+- int CLEANER (void *COOKIE)
+-
+- Your function should return `-1' to indicate an error, and `0'
+-otherwise.
+-
+- - Data Type: cookie_read_function
+- This is the data type that the read function for a custom stream
+- should have. If you declare the function as shown above, this is
+- the type it will have.
+-
+- - Data Type: cookie_write_function
+- The data type of the write function for a custom stream.
+-
+- - Data Type: cookie_seek_function
+- The data type of the seek function for a custom stream.
+-
+- - Data Type: cookie_close_function
+- The data type of the close function for a custom stream.
+-
+-
+-File: libc.info, Node: Low-Level I/O, Next: File System Interface, Prev:
I/O on Streams, Up: Top
+-
+-Low-Level Input/Output
+-**********************
+-
+- This chapter describes functions for performing low-level
+-input/output operations on file descriptors. These functions include
+-the primitives for the higher-level I/O functions described in *Note
+-I/O on Streams::, as well as functions for performing low-level control
+-operations for which there are no equivalents on streams.
+-
+- Stream-level I/O is more flexible and usually more convenient;
+-therefore, programmers generally use the descriptor-level functions only
+-when necessary. These are some of the usual reasons:
+-
+- * For reading binary files in large chunks.
+-
+- * For reading an entire file into core before parsing it.
+-
+- * To perform operations other than data transfer, which can only be
+- done with a descriptor. (You can use `fileno' to get the
+- descriptor corresponding to a stream.)
+-
+- * To pass descriptors to a child process. (The child can create its
+- own stream to use a descriptor that it inherits, but cannot
+- inherit a stream directly.)
+-
+-* Menu:
+-
+-* Opening and Closing Files:: How to open and close file
+- descriptors.
+-* I/O Primitives:: Reading and writing data.
+-* File Position Primitive:: Setting a descriptor's file
+- position.
+-* Descriptors and Streams:: Converting descriptor to stream
+- or vice-versa.
+-* Stream/Descriptor Precautions:: Precautions needed if you use both
+- descriptors and streams.
+-* Waiting for I/O:: How to check for input or output
+- on multiple file descriptors.
+-* Control Operations:: Various other operations on file
+- descriptors.
+-* Duplicating Descriptors:: Fcntl commands for duplicating
+- file descriptors.
+-* Descriptor Flags:: Fcntl commands for manipulating
+- flags associated with file
+- descriptors.
+-* File Status Flags:: Fcntl commands for manipulating
+- flags associated with open files.
+-* File Locks:: Fcntl commands for implementing
+- file locking.
+-* Interrupt Input:: Getting an asynchronous signal when
+- input arrives.
+-
+-
+-File: libc.info, Node: Opening and Closing Files, Next: I/O Primitives,
Up: Low-Level I/O
+-
+-Opening and Closing Files
+-=========================
+-
+- This section describes the primitives for opening and closing files
+-using file descriptors. The `open' and `creat' functions are declared
+-in the header file `fcntl.h', while `close' is declared in `unistd.h'.
+-
+- - Function: int open (const char *FILENAME, int FLAGS[, mode_t MODE])
+- The `open' function creates and returns a new file descriptor for
+- the file named by FILENAME. Initially, the file position
+- indicator for the file is at the beginning of the file. The
+- argument MODE is used only when a file is created, but it doesn't
+- hurt to supply the argument in any case.
+-
+- The FLAGS argument controls how the file is to be opened. This is
+- a bit mask; you create the value by the bitwise OR of the
+- appropriate parameters (using the `|' operator in C). *Note File
+- Status Flags::, for the parameters available.
+-
+- The normal return value from `open' is a non-negative integer file
+- descriptor. In the case of an error, a value of `-1' is returned
+- instead. In addition to the usual file name errors (*note File
+- Name Errors::.), the following `errno' error conditions are defined
+- for this function:
+-
+- `EACCES'
+- The file exists but is not readable/writable as requested by
+- the FLAGS argument, the file does not exist and the directory
+- is unwritable so it cannot be created.
+-
+- `EEXIST'
+- Both `O_CREAT' and `O_EXCL' are set, and the named file
+- already exists.
+-
+- `EINTR'
+- The `open' operation was interrupted by a signal. *Note
+- Interrupted Primitives::.
+-
+- `EISDIR'
+- The FLAGS argument specified write access, and the file is a
+- directory.
+-
+- `EMFILE'
+- The process has too many files open. The maximum number of
+- file descriptors is controlled by the `RLIMIT_NOFILE'
+- resource limit; *note Limits on Resources::..
+-
+- `ENFILE'
+- The entire system, or perhaps the file system which contains
+- the directory, cannot support any additional open files at
+- the moment. (This problem cannot happen on the GNU system.)
+-
+- `ENOENT'
+- The named file does not exist, and `O_CREAT' is not specified.
+-
+- `ENOSPC'
+- The directory or file system that would contain the new file
+- cannot be extended, because there is no disk space left.
+-
+- `ENXIO'
+- `O_NONBLOCK' and `O_WRONLY' are both set in the FLAGS
+- argument, the file named by FILENAME is a FIFO (*note Pipes
+- and FIFOs::.), and no process has the file open for reading.
+-
+- `EROFS'
+- The file resides on a read-only file system and any of
+- `O_WRONLY', `O_RDWR', and `O_TRUNC' are set in the FLAGS
+- argument, or `O_CREAT' is set and the file does not already
+- exist.
+-
+- The `open' function is the underlying primitive for the `fopen'
+- and `freopen' functions, that create streams.
+-
+- - Obsolete function: int creat (const char *FILENAME, mode_t MODE)
+- This function is obsolete. The call:
+-
+- creat (FILENAME, MODE)
+-
+- is equivalent to:
+-
+- open (FILENAME, O_WRONLY | O_CREAT | O_TRUNC, MODE)
+-
+- - Function: int close (int FILEDES)
+- The function `close' closes the file descriptor FILEDES. Closing
+- a file has the following consequences:
+-
+- * The file descriptor is deallocated.
+-
+- * Any record locks owned by the process on the file are
+- unlocked.
+-
+- * When all file descriptors associated with a pipe or FIFO have
+- been closed, any unread data is discarded.
+-
+- The normal return value from `close' is `0'; a value of `-1' is
+- returned in case of failure. The following `errno' error
+- conditions are defined for this function:
+-
+- `EBADF'
+- The FILEDES argument is not a valid file descriptor.
+-
+- `EINTR'
+- The `close' call was interrupted by a signal. *Note
+- Interrupted Primitives::. Here is an example of how to
+- handle `EINTR' properly:
+-
+- TEMP_FAILURE_RETRY (close (desc));
+-
+- `ENOSPC'
+- `EIO'
+- `EDQUOT'
+- When the file is accessed by NFS, these errors from `write'
+- can sometimes not be detected until `close'. *Note I/O
+- Primitives::, for details on their meaning.
+-
+- To close a stream, call `fclose' (*note Closing Streams::.) instead
+-of trying to close its underlying file descriptor with `close'. This
+-flushes any buffered output and updates the stream object to indicate
+-that it is closed.
+-
+diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-9
glibc-2.0.1/manual/libc.info-9
+--- ../glibc-2.0.1/manual/libc.info-9 1997-01-25 14:16:44.000000000 +0100
++++ glibc-2.0.1/manual/libc.info-9 1970-01-01 01:00:00.000000000 +0100
+@@ -1,1169 +0,0 @@
+-This is Info file libc.info, produced by Makeinfo version 1.67 from the
+-input file libc.texinfo.
+-
+- This file documents the GNU C library.
+-
+- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
+-Library Reference Manual', for Version 2.00 Beta.
+-
+- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
+-
+- Permission is granted to make and distribute verbatim copies of this
+-manual provided the copyright notice and this permission notice are
+-preserved on all copies.
+-
+- Permission is granted to copy and distribute modified versions of
+-this manual under the conditions for verbatim copying, provided also
+-that the section entitled "GNU Library General Public License" is
+-included exactly as in the original, and provided that the entire
+-resulting derived work is distributed under the terms of a permission
+-notice identical to this one.
+-
+- Permission is granted to copy and distribute translations of this
+-manual into another language, under the above conditions for modified
+-versions, except that the text of the translation of the section
+-entitled "GNU Library General Public License" must be approved for
+-accuracy by the Foundation.
+-
+-
+-File: libc.info, Node: I/O Primitives, Next: File Position Primitive,
Prev: Opening and Closing Files, Up: Low-Level I/O
+-
+-Input and Output Primitives
+-===========================
+-
+- This section describes the functions for performing primitive input
+-and output operations on file descriptors: `read', `write', and
+-`lseek'. These functions are declared in the header file `unistd.h'.
+-
+- - Data Type: ssize_t
+- This data type is used to represent the sizes of blocks that can be
+- read or written in a single operation. It is similar to `size_t',
+- but must be a signed type.
+-
+- - Function: ssize_t read (int FILEDES, void *BUFFER, size_t SIZE)
+- The `read' function reads up to SIZE bytes from the file with
+- descriptor FILEDES, storing the results in the BUFFER. (This is
+- not necessarily a character string and there is no terminating
+- null character added.)
+-
+- The return value is the number of bytes actually read. This might
+- be less than SIZE; for example, if there aren't that many bytes
+- left in the file or if there aren't that many bytes immediately
+- available. The exact behavior depends on what kind of file it is.
+- Note that reading less than SIZE bytes is not an error.
+-
+- A value of zero indicates end-of-file (except if the value of the
+- SIZE argument is also zero). This is not considered an error. If
+- you keep calling `read' while at end-of-file, it will keep
+- returning zero and doing nothing else.
+-
+- If `read' returns at least one character, there is no way you can
+- tell whether end-of-file was reached. But if you did reach the
+- end, the next read will return zero.
+-
+- In case of an error, `read' returns `-1'. The following `errno'
+- error conditions are defined for this function:
+-
+- `EAGAIN'
+- Normally, when no input is immediately available, `read'
+- waits for some input. But if the `O_NONBLOCK' flag is set
+- for the file (*note File Status Flags::.), `read' returns
+- immediately without reading any data, and reports this error.
+-
+- *Compatibility Note:* Most versions of BSD Unix use a
+- different error code for this: `EWOULDBLOCK'. In the GNU
+- library, `EWOULDBLOCK' is an alias for `EAGAIN', so it
+- doesn't matter which name you use.
+-
+- On some systems, reading a large amount of data from a
+- character special file can also fail with `EAGAIN' if the
+- kernel cannot find enough physical memory to lock down the
+- user's pages. This is limited to devices that transfer with
+- direct memory access into the user's memory, which means it
+- does not include terminals, since they always use separate
+- buffers inside the kernel. This problem never happens in the
+- GNU system.
+-
+- Any condition that could result in `EAGAIN' can instead
+- result in a successful `read' which returns fewer bytes than
+- requested. Calling `read' again immediately would result in
+- `EAGAIN'.
+-
+- `EBADF'
+- The FILEDES argument is not a valid file descriptor, or is
+- not open for reading.
+-
+- `EINTR'
+- `read' was interrupted by a signal while it was waiting for
+- input. *Note Interrupted Primitives::. A signal will not
+- necessary cause `read' to return `EINTR'; it may instead
+- result in a successful `read' which returns fewer bytes than
+- requested.
+-
+- `EIO'
+- For many devices, and for disk files, this error code
+- indicates a hardware error.
+-
+- `EIO' also occurs when a background process tries to read
+- from the controlling terminal, and the normal action of
+- stopping the process by sending it a `SIGTTIN' signal isn't
+- working. This might happen if signal is being blocked or
+- ignored, or because the process group is orphaned. *Note Job
+- Control::, for more information about job control, and *Note
+- Signal Handling::, for information about signals.
+-
+- The `read' function is the underlying primitive for all of the
+- functions that read from streams, such as `fgetc'.
+-
+- - Function: ssize_t write (int FILEDES, const void *BUFFER, size_t
+- SIZE)
+- The `write' function writes up to SIZE bytes from BUFFER to the
+- file with descriptor FILEDES. The data in BUFFER is not
+- necessarily a character string and a null character is output like
+- any other character.
+-
+- The return value is the number of bytes actually written. This
+- may be SIZE, but can always be smaller. Your program should
+- always call `write' in a loop, iterating until all the data is
+- written.
+-
+- Once `write' returns, the data is enqueued to be written and can be
+- read back right away, but it is not necessarily written out to
+- permanent storage immediately. You can use `fsync' when you need
+- to be sure your data has been permanently stored before
+- continuing. (It is more efficient for the system to batch up
+- consecutive writes and do them all at once when convenient.
+- Normally they will always be written to disk within a minute or
+- less.) You can use the `O_FSYNC' open mode to make `write' always
+- store the data to disk before returning; *note Operating Modes::..
+-
+- In the case of an error, `write' returns `-1'. The following
+- `errno' error conditions are defined for this function:
+-
+- `EAGAIN'
+- Normally, `write' blocks until the write operation is
+- complete. But if the `O_NONBLOCK' flag is set for the file
+- (*note Control Operations::.), it returns immediately without
+- writing any data, and reports this error. An example of a
+- situation that might cause the process to block on output is
+- writing to a terminal device that supports flow control,
+- where output has been suspended by receipt of a STOP
+- character.
+-
+- *Compatibility Note:* Most versions of BSD Unix use a
+- different error code for this: `EWOULDBLOCK'. In the GNU
+- library, `EWOULDBLOCK' is an alias for `EAGAIN', so it
+- doesn't matter which name you use.
+-
+- On some systems, writing a large amount of data from a
+- character special file can also fail with `EAGAIN' if the
+- kernel cannot find enough physical memory to lock down the
+- user's pages. This is limited to devices that transfer with
+- direct memory access into the user's memory, which means it
+- does not include terminals, since they always use separate
+- buffers inside the kernel. This problem does not arise in the
+- GNU system.
+-
+- `EBADF'
+- The FILEDES argument is not a valid file descriptor, or is
+- not open for writing.
+-
+- `EFBIG'
+- The size of the file would become larger than the
+- implementation can support.
+-
+- `EINTR'
+- The `write' operation was interrupted by a signal while it was
+- blocked waiting for completion. A signal will not necessary
+- cause `write' to return `EINTR'; it may instead result in a
+- successful `write' which writes fewer bytes than requested.
+- *Note Interrupted Primitives::.
+-
+- `EIO'
+- For many devices, and for disk files, this error code
+- indicates a hardware error.
+-
+- `ENOSPC'
+- The device containing the file is full.
+-
+- `EPIPE'
+- This error is returned when you try to write to a pipe or
+- FIFO that isn't open for reading by any process. When this
+- happens, a `SIGPIPE' signal is also sent to the process; see
+- *Note Signal Handling::.
+-
+- Unless you have arranged to prevent `EINTR' failures, you should
+- check `errno' after each failing call to `write', and if the error
+- was `EINTR', you should simply repeat the call. *Note Interrupted
+- Primitives::. The easy way to do this is with the macro
+- `TEMP_FAILURE_RETRY', as follows:
+-
+- nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
+-
+- The `write' function is the underlying primitive for all of the
+- functions that write to streams, such as `fputc'.
+-
+-
+-File: libc.info, Node: File Position Primitive, Next: Descriptors and
Streams, Prev: I/O Primitives, Up: Low-Level I/O
+-
+-Setting the File Position of a Descriptor
+-=========================================
+-
+- Just as you can set the file position of a stream with `fseek', you
+-can set the file position of a descriptor with `lseek'. This specifies
+-the position in the file for the next `read' or `write' operation.
+-*Note File Positioning::, for more information on the file position and
+-what it means.
+-
+- To read the current file position value from a descriptor, use
+-`lseek (DESC, 0, SEEK_CUR)'.
+-
+- - Function: off_t lseek (int FILEDES, off_t OFFSET, int WHENCE)
+- The `lseek' function is used to change the file position of the
+- file with descriptor FILEDES.
+-
+- The WHENCE argument specifies how the OFFSET should be interpreted
+- in the same way as for the `fseek' function, and must be one of
+- the symbolic constants `SEEK_SET', `SEEK_CUR', or `SEEK_END'.
+-
+- `SEEK_SET'
+- Specifies that WHENCE is a count of characters from the
+- beginning of the file.
+-
+- `SEEK_CUR'
+- Specifies that WHENCE is a count of characters from the
+- current file position. This count may be positive or
+- negative.
+-
+- `SEEK_END'
+- Specifies that WHENCE is a count of characters from the end of
+- the file. A negative count specifies a position within the
+- current extent of the file; a positive count specifies a
+- position past the current end. If you set the position past
+- the current end, and actually write data, you will extend the
+- file with zeros up to that position. The return value from
+- `lseek' is normally the resulting file position, measured in bytes
+- from the beginning of the file. You can use this feature together
+- with `SEEK_CUR' to read the current file position.
+-
+- If you want to append to the file, setting the file position to the
+- current end of file with `SEEK_END' is not sufficient. Another
+- process may write more data after you seek but before you write,
+- extending the file so the position you write onto clobbers their
+- data. Instead, use the `O_APPEND' operating mode; *note Operating
+- Modes::..
+-
+- You can set the file position past the current end of the file.
+- This does not by itself make the file longer; `lseek' never
+- changes the file. But subsequent output at that position will
+- extend the file. Characters between the previous end of file and
+- the new position are filled with zeros. Extending the file in
+- this way can create a "hole": the blocks of zeros are not actually
+- allocated on disk, so the file takes up less space than it appears
+- so; it is then called a "sparse file".
+-
+- If the file position cannot be changed, or the operation is in
+- some way invalid, `lseek' returns a value of `-1'. The following
+- `errno' error conditions are defined for this function:
+-
+- `EBADF'
+- The FILEDES is not a valid file descriptor.
+-
+- `EINVAL'
+- The WHENCE argument value is not valid, or the resulting file
+- offset is not valid. A file offset is invalid.
+-
+- `ESPIPE'
+- The FILEDES corresponds to an object that cannot be
+- positioned, such as a pipe, FIFO or terminal device.
+- (POSIX.1 specifies this error only for pipes and FIFOs, but
+- in the GNU system, you always get `ESPIPE' if the object is
+- not seekable.)
+-
+- The `lseek' function is the underlying primitive for the `fseek',
+- `ftell' and `rewind' functions, which operate on streams instead
+- of file descriptors.
+-
+- You can have multiple descriptors for the same file if you open the
+-file more than once, or if you duplicate a descriptor with `dup'.
+-Descriptors that come from separate calls to `open' have independent
+-file positions; using `lseek' on one descriptor has no effect on the
+-other. For example,
+-
+- {
+- int d1, d2;
+- char buf[4];
+- d1 = open ("foo", O_RDONLY);
+- d2 = open ("foo", O_RDONLY);
+- lseek (d1, 1024, SEEK_SET);
+- read (d2, buf, 4);
+- }
+-
+-will read the first four characters of the file `foo'. (The
+-error-checking code necessary for a real program has been omitted here
+-for brevity.)
+-
+- By contrast, descriptors made by duplication share a common file
+-position with the original descriptor that was duplicated. Anything
+-which alters the file position of one of the duplicates, including
+-reading or writing data, affects all of them alike. Thus, for example,
+-
+- {
+- int d1, d2, d3;
+- char buf1[4], buf2[4];
+- d1 = open ("foo", O_RDONLY);
+- d2 = dup (d1);
+- d3 = dup (d2);
+- lseek (d3, 1024, SEEK_SET);
+- read (d1, buf1, 4);
+- read (d2, buf2, 4);
+- }
+-
+-will read four characters starting with the 1024'th character of `foo',
+-and then four more characters starting with the 1028'th character.
+-
+- - Data Type: off_t
+- This is an arithmetic data type used to represent file sizes. In
+- the GNU system, this is equivalent to `fpos_t' or `long int'.
+-
+- These aliases for the `SEEK_...' constants exist for the sake of
+-compatibility with older BSD systems. They are defined in two
+-different header files: `fcntl.h' and `sys/file.h'.
+-
+-`L_SET'
+- An alias for `SEEK_SET'.
+-
+-`L_INCR'
+- An alias for `SEEK_CUR'.
+-
+-`L_XTND'
+- An alias for `SEEK_END'.
+-
+-
+-File: libc.info, Node: Descriptors and Streams, Next: Stream/Descriptor
Precautions, Prev: File Position Primitive, Up: Low-Level I/O
+-
+-Descriptors and Streams
+-=======================
+-
+- Given an open file descriptor, you can create a stream for it with
+-the `fdopen' function. You can get the underlying file descriptor for
+-an existing stream with the `fileno' function. These functions are
+-declared in the header file `stdio.h'.
+-
+- - Function: FILE * fdopen (int FILEDES, const char *OPENTYPE)
+- The `fdopen' function returns a new stream for the file descriptor
+- FILEDES.
+-
+- The OPENTYPE argument is interpreted in the same way as for the
+- `fopen' function (*note Opening Streams::.), except that the `b'
+- option is not permitted; this is because GNU makes no distinction
+- between text and binary files. Also, `"w"' and `"w+"' do not
+- cause truncation of the file; these have affect only when opening
+- a file, and in this case the file has already been opened. You
+- must make sure that the OPENTYPE argument matches the actual mode
+- of the open file descriptor.
+-
+- The return value is the new stream. If the stream cannot be
+- created (for example, if the modes for the file indicated by the
+- file descriptor do not permit the access specified by the OPENTYPE
+- argument), a null pointer is returned instead.
+-
+- In some other systems, `fdopen' may fail to detect that the modes
+- for file descriptor do not permit the access specified by
+- `opentype'. The GNU C library always checks for this.
+-
+- For an example showing the use of the `fdopen' function, see *Note
+-Creating a Pipe::.
+-
+- - Function: int fileno (FILE *STREAM)
+- This function returns the file descriptor associated with the
+- stream STREAM. If an error is detected (for example, if the STREAM
+- is not valid) or if STREAM does not do I/O to a file, `fileno'
+- returns `-1'.
+-
+- There are also symbolic constants defined in `unistd.h' for the file
+-descriptors belonging to the standard streams `stdin', `stdout', and
+-`stderr'; see *Note Standard Streams::.
+-
+-`STDIN_FILENO'
+- This macro has value `0', which is the file descriptor for
+- standard input.
+-
+-`STDOUT_FILENO'
+- This macro has value `1', which is the file descriptor for
+- standard output.
+-
+-`STDERR_FILENO'
+- This macro has value `2', which is the file descriptor for
+- standard error output.
+-
+-
+-File: libc.info, Node: Stream/Descriptor Precautions, Next: Waiting for
I/O, Prev: Descriptors and Streams, Up: Low-Level I/O
+-
+-Dangers of Mixing Streams and Descriptors
+-=========================================
+-
+- You can have multiple file descriptors and streams (let's call both
+-streams and descriptors "channels" for short) connected to the same
+-file, but you must take care to avoid confusion between channels. There
+-are two cases to consider: "linked" channels that share a single file
+-position value, and "independent" channels that have their own file
+-positions.
+-
+- It's best to use just one channel in your program for actual data
+-transfer to any given file, except when all the access is for input.
+-For example, if you open a pipe (something you can only do at the file
+-descriptor level), either do all I/O with the descriptor, or construct a
+-stream from the descriptor with `fdopen' and then do all I/O with the
+-stream.
+-
+-* Menu:
+-
+-* Linked Channels:: Dealing with channels sharing a file position.
+-* Independent Channels:: Dealing with separately opened, unlinked channels.
+-* Cleaning Streams:: Cleaning a stream makes it safe to use
+- another channel.
+-
+-
+-File: libc.info, Node: Linked Channels, Next: Independent Channels, Up:
Stream/Descriptor Precautions
+-
+-Linked Channels
+----------------
+-
+- Channels that come from a single opening share the same file
+-position; we call them "linked" channels. Linked channels result when
+-you make a stream from a descriptor using `fdopen', when you get a
+-descriptor from a stream with `fileno', when you copy a descriptor with
+-`dup' or `dup2', and when descriptors are inherited during `fork'. For
+-files that don't support random access, such as terminals and pipes,
+-*all* channels are effectively linked. On random-access files, all
+-append-type output streams are effectively linked to each other.
+-
+- If you have been using a stream for I/O, and you want to do I/O using
+-another channel (either a stream or a descriptor) that is linked to it,
+-you must first "clean up" the stream that you have been using. *Note
+-Cleaning Streams::.
+-
+- Terminating a process, or executing a new program in the process,
+-destroys all the streams in the process. If descriptors linked to these
+-streams persist in other processes, their file positions become
+-undefined as a result. To prevent this, you must clean up the streams
+-before destroying them.
+-
+-
+-File: libc.info, Node: Independent Channels, Next: Cleaning Streams, Prev:
Linked Channels, Up: Stream/Descriptor Precautions
+-
+-Independent Channels
+---------------------
+-
+- When you open channels (streams or descriptors) separately on a
+-seekable file, each channel has its own file position. These are called
+-"independent channels".
+-
+- The system handles each channel independently. Most of the time,
+-this is quite predictable and natural (especially for input): each
+-channel can read or write sequentially at its own place in the file.
+-However, if some of the channels are streams, you must take these
+-precautions:
+-
+- * You should clean an output stream after use, before doing anything
+- else that might read or write from the same part of the file.
+-
+- * You should clean an input stream before reading data that may have
+- been modified using an independent channel. Otherwise, you might
+- read obsolete data that had been in the stream's buffer.
+-
+- If you do output to one channel at the end of the file, this will
+-certainly leave the other independent channels positioned somewhere
+-before the new end. You cannot reliably set their file positions to the
+-new end of file before writing, because the file can always be extended
+-by another process between when you set the file position and when you
+-write the data. Instead, use an append-type descriptor or stream; they
+-always output at the current end of the file. In order to make the
+-end-of-file position accurate, you must clean the output channel you
+-were using, if it is a stream.
+-
+- It's impossible for two channels to have separate file pointers for a
+-file that doesn't support random access. Thus, channels for reading or
+-writing such files are always linked, never independent. Append-type
+-channels are also always linked. For these channels, follow the rules
+-for linked channels; see *Note Linked Channels::.
+-
+-
+-File: libc.info, Node: Cleaning Streams, Prev: Independent Channels, Up:
Stream/Descriptor Precautions
+-
+-Cleaning Streams
+-----------------
+-
+- On the GNU system, you can clean up any stream with `fclean':
+-
+- - Function: int fclean (FILE *STREAM)
+- Clean up the stream STREAM so that its buffer is empty. If STREAM
+- is doing output, force it out. If STREAM is doing input, give the
+- data in the buffer back to the system, arranging to reread it.
+-
+- On other systems, you can use `fflush' to clean a stream in most
+-cases.
+-
+- You can skip the `fclean' or `fflush' if you know the stream is
+-already clean. A stream is clean whenever its buffer is empty. For
+-example, an unbuffered stream is always clean. An input stream that is
+-at end-of-file is clean. A line-buffered stream is clean when the last
+-character output was a newline.
+-
+- There is one case in which cleaning a stream is impossible on most
+-systems. This is when the stream is doing input from a file that is not
+-random-access. Such streams typically read ahead, and when the file is
+-not random access, there is no way to give back the excess data already
+-read. When an input stream reads from a random-access file, `fflush'
+-does clean the stream, but leaves the file pointer at an unpredictable
+-place; you must set the file pointer before doing any further I/O. On
+-the GNU system, using `fclean' avoids both of these problems.
+-
+- Closing an output-only stream also does `fflush', so this is a valid
+-way of cleaning an output stream. On the GNU system, closing an input
+-stream does `fclean'.
+-
+- You need not clean a stream before using its descriptor for control
+-operations such as setting terminal modes; these operations don't affect
+-the file position and are not affected by it. You can use any
+-descriptor for these operations, and all channels are affected
+-simultaneously. However, text already "output" to a stream but still
+-buffered by the stream will be subject to the new terminal modes when
+-subsequently flushed. To make sure "past" output is covered by the
+-terminal settings that were in effect at the time, flush the output
+-streams for that terminal before setting the modes. *Note Terminal
+-Modes::.
+-
+-
+-File: libc.info, Node: Waiting for I/O, Next: Control Operations, Prev:
Stream/Descriptor Precautions, Up: Low-Level I/O
+-
+-Waiting for Input or Output
+-===========================
+-
+- Sometimes a program needs to accept input on multiple input channels
+-whenever input arrives. For example, some workstations may have devices
+-such as a digitizing tablet, function button box, or dial box that are
+-connected via normal asynchronous serial interfaces; good user interface
+-style requires responding immediately to input on any device. Another
+-example is a program that acts as a server to several other processes
+-via pipes or sockets.
+-
+- You cannot normally use `read' for this purpose, because this blocks
+-the program until input is available on one particular file descriptor;
+-input on other channels won't wake it up. You could set nonblocking
+-mode and poll each file descriptor in turn, but this is very
+-inefficient.
+-
+- A better solution is to use the `select' function. This blocks the
+-program until input or output is ready on a specified set of file
+-descriptors, or until a timer expires, whichever comes first. This
+-facility is declared in the header file `sys/types.h'.
+-
+- In the case of a server socket (*note Listening::.), we say that
+-"input" is available when there are pending connections that could be
+-accepted (*note Accepting Connections::.). `accept' for server sockets
+-blocks and interacts with `select' just as `read' does for normal input.
+-
+- The file descriptor sets for the `select' function are specified as
+-`fd_set' objects. Here is the description of the data type and some
+-macros for manipulating these objects.
+-
+- - Data Type: fd_set
+- The `fd_set' data type represents file descriptor sets for the
+- `select' function. It is actually a bit array.
+-
+- - Macro: int FD_SETSIZE
+- The value of this macro is the maximum number of file descriptors
+- that a `fd_set' object can hold information about. On systems
+- with a fixed maximum number, `FD_SETSIZE' is at least that number.
+- On some systems, including GNU, there is no absolute limit on the
+- number of descriptors open, but this macro still has a constant
+- value which controls the number of bits in an `fd_set'; if you get
+- a file descriptor with a value as high as `FD_SETSIZE', you cannot
+- put that descriptor into an `fd_set'.
+-
+- - Macro: void FD_ZERO (fd_set *SET)
+- This macro initializes the file descriptor set SET to be the empty
+- set.
+-
+- - Macro: void FD_SET (int FILEDES, fd_set *SET)
+- This macro adds FILEDES to the file descriptor set SET.
+-
+- - Macro: void FD_CLR (int FILEDES, fd_set *SET)
+- This macro removes FILEDES from the file descriptor set SET.
+-
+- - Macro: int FD_ISSET (int FILEDES, fd_set *SET)
+- This macro returns a nonzero value (true) if FILEDES is a member
+- of the the file descriptor set SET, and zero (false) otherwise.
+-
+- Next, here is the description of the `select' function itself.
+-
+- - Function: int select (int NFDS, fd_set *READ-FDS, fd_set *WRITE-FDS,
+- fd_set *EXCEPT-FDS, struct timeval *TIMEOUT)
+- The `select' function blocks the calling process until there is
+- activity on any of the specified sets of file descriptors, or
+- until the timeout period has expired.
+-
+- The file descriptors specified by the READ-FDS argument are
+- checked to see if they are ready for reading; the WRITE-FDS file
+- descriptors are checked to see if they are ready for writing; and
+- the EXCEPT-FDS file descriptors are checked for exceptional
+- conditions. You can pass a null pointer for any of these
+- arguments if you are not interested in checking for that kind of
+- condition.
+-
+- A file descriptor is considered ready for reading if it is at end
+- of file. A server socket is considered ready for reading if there
+- is a pending connection which can be accepted with `accept'; *note
+- Accepting Connections::.. A client socket is ready for writing
+- when its connection is fully established; *note Connecting::..
+-
+- "Exceptional conditions" does not mean errors--errors are reported
+- immediately when an erroneous system call is executed, and do not
+- constitute a state of the descriptor. Rather, they include
+- conditions such as the presence of an urgent message on a socket.
+- (*Note Sockets::, for information on urgent messages.)
+-
+- The `select' function checks only the first NFDS file descriptors.
+- The usual thing is to pass `FD_SETSIZE' as the value of this
+- argument.
+-
+- The TIMEOUT specifies the maximum time to wait. If you pass a
+- null pointer for this argument, it means to block indefinitely
+- until one of the file descriptors is ready. Otherwise, you should
+- provide the time in `struct timeval' format; see *Note
+- High-Resolution Calendar::. Specify zero as the time (a `struct
+- timeval' containing all zeros) if you want to find out which
+- descriptors are ready without waiting if none are ready.
+-
+- The normal return value from `select' is the total number of ready
+- file descriptors in all of the sets. Each of the argument sets is
+- overwritten with information about the descriptors that are ready
+- for the corresponding operation. Thus, to see if a particular
+- descriptor DESC has input, use `FD_ISSET (DESC, READ-FDS)' after
+- `select' returns.
+-
+- If `select' returns because the timeout period expires, it returns
+- a value of zero.
+-
+- Any signal will cause `select' to return immediately. So if your
+- program uses signals, you can't rely on `select' to keep waiting
+- for the full time specified. If you want to be sure of waiting
+- for a particular amount of time, you must check for `EINTR' and
+- repeat the `select' with a newly calculated timeout based on the
+- current time. See the example below. See also *Note Interrupted
+- Primitives::.
+-
+- If an error occurs, `select' returns `-1' and does not modify the
+- argument file descriptor sets. The following `errno' error
+- conditions are defined for this function:
+-
+- `EBADF'
+- One of the file descriptor sets specified an invalid file
+- descriptor.
+-
+- `EINTR'
+- The operation was interrupted by a signal. *Note Interrupted
+- Primitives::.
+-
+- `EINVAL'
+- The TIMEOUT argument is invalid; one of the components is
+- negative or too large.
+-
+- *Portability Note:* The `select' function is a BSD Unix feature.
+-
+- Here is an example showing how you can use `select' to establish a
+-timeout period for reading from a file descriptor. The `input_timeout'
+-function blocks the calling process until input is available on the
+-file descriptor, or until the timeout period expires.
+-
+- #include <stdio.h>
+- #include <unistd.h>
+- #include <sys/types.h>
+- #include <sys/time.h>
+-
+- int
+- input_timeout (int filedes, unsigned int seconds)
+- {
+- fd_set set;
+- struct timeval timeout;
+-
+- /* Initialize the file descriptor set. */
+- FD_ZERO (&set);
+- FD_SET (filedes, &set);
+-
+- /* Initialize the timeout data structure. */
+- timeout.tv_sec = seconds;
+- timeout.tv_usec = 0;
+- /* `select' returns 0 if timeout, 1 if input available, -1 if error. */
+- return TEMP_FAILURE_RETRY (select (FD_SETSIZE,
+- &set, NULL, NULL,
+- &timeout));
+- }
+-
+- int
+- main (void)
+- {
+- fprintf (stderr, "select returned %d.\n",
+- input_timeout (STDIN_FILENO, 5));
+- return 0;
+- }
+-
+- There is another example showing the use of `select' to multiplex
+-input from multiple sockets in *Note Server Example::.
+-
+-
+-File: libc.info, Node: Control Operations, Next: Duplicating Descriptors,
Prev: Waiting for I/O, Up: Low-Level I/O
+-
+-Control Operations on Files
+-===========================
+-
+- This section describes how you can perform various other operations
+-on file descriptors, such as inquiring about or setting flags describing
+-the status of the file descriptor, manipulating record locks, and the
+-like. All of these operations are performed by the function `fcntl'.
+-
+- The second argument to the `fcntl' function is a command that
+-specifies which operation to perform. The function and macros that name
+-various flags that are used with it are declared in the header file
+-`fcntl.h'. Many of these flags are also used by the `open' function;
+-see *Note Opening and Closing Files::.
+-
+- - Function: int fcntl (int FILEDES, int COMMAND, ...)
+- The `fcntl' function performs the operation specified by COMMAND
+- on the file descriptor FILEDES. Some commands require additional
+- arguments to be supplied. These additional arguments and the
+- return value and error conditions are given in the detailed
+- descriptions of the individual commands.
+-
+- Briefly, here is a list of what the various commands are.
+-
+- `F_DUPFD'
+- Duplicate the file descriptor (return another file descriptor
+- pointing to the same open file). *Note Duplicating
+- Descriptors::.
+-
+- `F_GETFD'
+- Get flags associated with the file descriptor. *Note
+- Descriptor Flags::.
+-
+- `F_SETFD'
+- Set flags associated with the file descriptor. *Note
+- Descriptor Flags::.
+-
+- `F_GETFL'
+- Get flags associated with the open file. *Note File Status
+- Flags::.
+-
+- `F_SETFL'
+- Set flags associated with the open file. *Note File Status
+- Flags::.
+-
+- `F_GETLK'
+- Get a file lock. *Note File Locks::.
+-
+- `F_SETLK'
+- Set or clear a file lock. *Note File Locks::.
+-
+- `F_SETLKW'
+- Like `F_SETLK', but wait for completion. *Note File Locks::.
+-
+- `F_GETOWN'
+- Get process or process group ID to receive `SIGIO' signals.
+- *Note Interrupt Input::.
+-
+- `F_SETOWN'
+- Set process or process group ID to receive `SIGIO' signals.
+- *Note Interrupt Input::.
+-
+-
+-File: libc.info, Node: Duplicating Descriptors, Next: Descriptor Flags,
Prev: Control Operations, Up: Low-Level I/O
+-
+-Duplicating Descriptors
+-=======================
+-
+- You can "duplicate" a file descriptor, or allocate another file
+-descriptor that refers to the same open file as the original. Duplicate
+-descriptors share one file position and one set of file status flags
+-(*note File Status Flags::.), but each has its own set of file
+-descriptor flags (*note Descriptor Flags::.).
+-
+- The major use of duplicating a file descriptor is to implement
+-"redirection" of input or output: that is, to change the file or pipe
+-that a particular file descriptor corresponds to.
+-
+- You can perform this operation using the `fcntl' function with the
+-`F_DUPFD' command, but there are also convenient functions `dup' and
+-`dup2' for duplicating descriptors.
+-
+- The `fcntl' function and flags are declared in `fcntl.h', while
+-prototypes for `dup' and `dup2' are in the header file `unistd.h'.
+-
+- - Function: int dup (int OLD)
+- This function copies descriptor OLD to the first available
+- descriptor number (the first number not currently open). It is
+- equivalent to `fcntl (OLD, F_DUPFD, 0)'.
+-
+- - Function: int dup2 (int OLD, int NEW)
+- This function copies the descriptor OLD to descriptor number NEW.
+-
+- If OLD is an invalid descriptor, then `dup2' does nothing; it does
+- not close NEW. Otherwise, the new duplicate of OLD replaces any
+- previous meaning of descriptor NEW, as if NEW were closed first.
+-
+- If OLD and NEW are different numbers, and OLD is a valid
+- descriptor number, then `dup2' is equivalent to:
+-
+- close (NEW);
+- fcntl (OLD, F_DUPFD, NEW)
+-
+- However, `dup2' does this atomically; there is no instant in the
+- middle of calling `dup2' at which NEW is closed and not yet a
+- duplicate of OLD.
+-
+- - Macro: int F_DUPFD
+- This macro is used as the COMMAND argument to `fcntl', to copy the
+- file descriptor given as the first argument.
+-
+- The form of the call in this case is:
+-
+- fcntl (OLD, F_DUPFD, NEXT-FILEDES)
+-
+- The NEXT-FILEDES argument is of type `int' and specifies that the
+- file descriptor returned should be the next available one greater
+- than or equal to this value.
+-
+- The return value from `fcntl' with this command is normally the
+- value of the new file descriptor. A return value of `-1'
+- indicates an error. The following `errno' error conditions are
+- defined for this command:
+-
+- `EBADF'
+- The OLD argument is invalid.
+-
+- `EINVAL'
+- The NEXT-FILEDES argument is invalid.
+-
+- `EMFILE'
+- There are no more file descriptors available--your program is
+- already using the maximum. In BSD and GNU, the maximum is
+- controlled by a resource limit that can be changed; *note
+- Limits on Resources::., for more information about the
+- `RLIMIT_NOFILE' limit.
+-
+- `ENFILE' is not a possible error code for `dup2' because `dup2'
+- does not create a new opening of a file; duplicate descriptors do
+- not count toward the limit which `ENFILE' indicates. `EMFILE' is
+- possible because it refers to the limit on distinct descriptor
+- numbers in use in one process.
+-
+- Here is an example showing how to use `dup2' to do redirection.
+-Typically, redirection of the standard streams (like `stdin') is done
+-by a shell or shell-like program before calling one of the `exec'
+-functions (*note Executing a File::.) to execute a new program in a
+-child process. When the new program is executed, it creates and
+-initializes the standard streams to point to the corresponding file
+-descriptors, before its `main' function is invoked.
+-
+- So, to redirect standard input to a file, the shell could do
+-something like:
+-
+- pid = fork ();
+- if (pid == 0)
+- {
+- char *filename;
+- char *program;
+- int file;
+- ...
+- file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
+- dup2 (file, STDIN_FILENO);
+- TEMP_FAILURE_RETRY (close (file));
+- execv (program, NULL);
+- }
+-
+- There is also a more detailed example showing how to implement
+-redirection in the context of a pipeline of processes in *Note
+-Launching Jobs::.
+-
+-
+-File: libc.info, Node: Descriptor Flags, Next: File Status Flags, Prev:
Duplicating Descriptors, Up: Low-Level I/O
+-
+-File Descriptor Flags
+-=====================
+-
+- "File descriptor flags" are miscellaneous attributes of a file
+-descriptor. These flags are associated with particular file
+-descriptors, so that if you have created duplicate file descriptors
+-from a single opening of a file, each descriptor has its own set of
+-flags.
+-
+- Currently there is just one file descriptor flag: `FD_CLOEXEC',
+-which causes the descriptor to be closed if you use any of the
+-`exec...' functions (*note Executing a File::.).
+-
+- The symbols in this section are defined in the header file `fcntl.h'.
+-
+- - Macro: int F_GETFD
+- This macro is used as the COMMAND argument to `fcntl', to specify
+- that it should return the file descriptor flags associated with
+- the FILEDES argument.
+-
+- The normal return value from `fcntl' with this command is a
+- nonnegative number which can be interpreted as the bitwise OR of
+- the individual flags (except that currently there is only one flag
+- to use).
+-
+- In case of an error, `fcntl' returns `-1'. The following `errno'
+- error conditions are defined for this command:
+-
+- `EBADF'
+- The FILEDES argument is invalid.
+-
+- - Macro: int F_SETFD
+- This macro is used as the COMMAND argument to `fcntl', to specify
+- that it should set the file descriptor flags associated with the
+- FILEDES argument. This requires a third `int' argument to specify
+- the new flags, so the form of the call is:
+-
+- fcntl (FILEDES, F_SETFD, NEW-FLAGS)
+-
+- The normal return value from `fcntl' with this command is an
+- unspecified value other than `-1', which indicates an error. The
+- flags and error conditions are the same as for the `F_GETFD'
+- command.
+-
+- The following macro is defined for use as a file descriptor flag with
+-the `fcntl' function. The value is an integer constant usable as a bit
+-mask value.
+-
+- - Macro: int FD_CLOEXEC
+- This flag specifies that the file descriptor should be closed when
+- an `exec' function is invoked; see *Note Executing a File::. When
+- a file descriptor is allocated (as with `open' or `dup'), this bit
+- is initially cleared on the new file descriptor, meaning that
+- descriptor will survive into the new program after `exec'.
+-
+- If you want to modify the file descriptor flags, you should get the
+-current flags with `F_GETFD' and modify the value. Don't assume that
+-the flags listed here are the only ones that are implemented; your
+-program may be run years from now and more flags may exist then. For
+-example, here is a function to set or clear the flag `FD_CLOEXEC'
+-without altering any other flags:
+-
+- /* Set the `FD_CLOEXEC' flag of DESC if VALUE is nonzero,
+- or clear the flag if VALUE is 0.
+- Return 0 on success, or -1 on error with `errno' set. */
+-
+- int
+- set_cloexec_flag (int desc, int value)
+- {
+- int oldflags = fcntl (desc, F_GETFD, 0);
+- /* If reading the flags failed, return error indication now.
+- if (oldflags < 0)
+- return oldflags;
+- /* Set just the flag we want to set. */
+- if (value != 0)
+- oldflags |= FD_CLOEXEC;
+- else
+- oldflags &= ~FD_CLOEXEC;
+- /* Store modified flag word in the descriptor. */
+- return fcntl (desc, F_SETFD, oldflags);
+- }
+-
+-
+-File: libc.info, Node: File Status Flags, Next: File Locks, Prev:
Descriptor Flags, Up: Low-Level I/O
+-
+-File Status Flags
+-=================
+-
+- "File status flags" are used to specify attributes of the opening of
+-a file. Unlike the file descriptor flags discussed in *Note Descriptor
+-Flags::, the file status flags are shared by duplicated file descriptors
+-resulting from a single opening of the file. The file status flags are
+-specified with the FLAGS argument to `open'; *note Opening and Closing
+-Files::..
+-
+- File status flags fall into three categories, which are described in
+-the following sections.
+-
+- * *Note Access Modes::, specify what type of access is allowed to the
+- file: reading, writing, or both. They are set by `open' and are
+- returned by `fcntl', but cannot be changed.
+-
+- * *Note Open-time Flags::, control details of what `open' will do.
+- These flags are not preserved after the `open' call.
+-
+- * *Note Operating Modes::, affect how operations such as `read' and
+- `write' are done. They are set by `open', and can be fetched or
+- changed with `fcntl'.
+-
+- The symbols in this section are defined in the header file `fcntl.h'.
+-
+-* Menu:
+-
+-* Access Modes:: Whether the descriptor can read or write.
+-* Open-time Flags:: Details of `open'.
+-* Operating Modes:: Special modes to control I/O operations.
+-* Getting File Status Flags:: Fetching and changing these flags.
+-
+-
+-File: libc.info, Node: Access Modes, Next: Open-time Flags, Up: File
Status Flags
+-
+-File Access Modes
+------------------
+-
+- The file access modes allow a file descriptor to be used for reading,
+-writing, or both. (In the GNU system, they can also allow none of
+-these, and allow execution of the file as a program.) The access modes
+-are chosen when the file is opened, and never change.
+-
+- - Macro: int O_RDONLY
+- Open the file for read access.
+-
+- - Macro: int O_WRONLY
+- Open the file for write access.
+-
+- - Macro: int O_RDWR
+- Open the file for both reading and writing.
+-
+- In the GNU system (and not in other systems), `O_RDONLY' and
+-`O_WRONLY' are independent bits that can be bitwise-ORed together, and
+-it is valid for either bit to be set or clear. This means that
+-`O_RDWR' is the same as `O_RDONLY|O_WRONLY'. A file access mode of
+-zero is permissible; it allows no operations that do input or output to
+-the file, but does allow other operations such as `fchmod'. On the GNU
+-system, since "read-only" or "write-only" is a misnomer, `fcntl.h'
+-defines additional names for the file access modes. These names are
+-preferred when writing GNU-specific code. But most programs will want
+-to be portable to other POSIX.1 systems and should use the POSIX.1
+-names above instead.
+-
+- - Macro: int O_READ
+- Open the file for reading. Same as `O_RDWR'; only defined on GNU.
+-
+- - Macro: int O_WRITE
+- Open the file for reading. Same as `O_WRONLY'; only defined on
+- GNU.
+-
+- - Macro: int O_EXEC
+- Open the file for executing. Only defined on GNU.
+-
+- To determine the file access mode with `fcntl', you must extract the
+-access mode bits from the retrieved file status flags. In the GNU
+-system, you can just test the `O_READ' and `O_WRITE' bits in the flags
+-word. But in other POSIX.1 systems, reading and writing access modes
+-are not stored as distinct bit flags. The portable way to extract the
+-file access mode bits is with `O_ACCMODE'.
+-
+- - Macro: int O_ACCMODE
+- This macro stands for a mask that can be bitwise-ANDed with the
+- file status flag value to produce a value representing the file
+- access mode. The mode will be `O_RDONLY', `O_WRONLY', or `O_RDWR'.
+- (In the GNU system it could also be zero, and it never includes the
+- `O_EXEC' bit.)
+-
+-
+-File: libc.info, Node: Open-time Flags, Next: Operating Modes, Prev:
Access Modes, Up: File Status Flags
+-
+-Open-time Flags
+----------------
+-
+- The open-time flags specify options affecting how `open' will behave.
+-These options are not preserved once the file is open. The exception to
+-this is `O_NONBLOCK', which is also an I/O operating mode and so it
+-*is* saved. *Note Opening and Closing Files::, for how to call `open'.
+-
+- There are two sorts of options specified by open-time flags.
+-
+- * "File name translation flags" affect how `open' looks up the file
+- name to locate the file, and whether the file can be created.
+-
+- * "Open-time action flags" specify extra operations that `open' will
+- perform on the file once it is open.
+-
+- Here are the file name translation flags.
+-
+- - Macro: int O_CREAT
+- If set, the file will be created if it doesn't already exist.
+-
+- - Macro: int O_EXCL
+- If both `O_CREAT' and `O_EXCL' are set, then `open' fails if the
+- specified file already exists. This is guaranteed to never
+- clobber an existing file.
+-
+- - Macro: int O_NONBLOCK
+- This prevents `open' from blocking for a "long time" to open the
+- file. This is only meaningful for some kinds of files, usually
+- devices such as serial ports; when it is not meaningful, it is
+- harmless and ignored. Often opening a port to a modem blocks
+- until the modem reports carrier detection; if `O_NONBLOCK' is
+- specified, `open' will return immediately without a carrier.
+-
+- Note that the `O_NONBLOCK' flag is overloaded as both an I/O
+- operating mode and a file name translation flag. This means that
+- specifying `O_NONBLOCK' in `open' also sets nonblocking I/O mode;
+- *note Operating Modes::.. To open the file without blocking but
+- do normal I/O that blocks, you must call `open' with `O_NONBLOCK'
+- set and then call `fcntl' to turn the bit off.
+-
+- - Macro: int O_NOCTTY
+- If the named file is a terminal device, don't make it the
+- controlling terminal for the process. *Note Job Control::, for
+- information about what it means to be the controlling terminal.
+-
+- In the GNU system and 4.4 BSD, opening a file never makes it the
+- controlling terminal and `O_NOCTTY' is zero. However, other
+- systems may use a nonzero value for `O_NOCTTY' and set the
+- controlling terminal when you open a file that is a terminal
+- device; so to be portable, use `O_NOCTTY' when it is important to
+- avoid this.
+-
+- The following three file name translation flags exist only in the
+-GNU system.
+-
+- - Macro: int O_IGNORE_CTTY
+- Do not recognize the named file as the controlling terminal, even
+- if it refers to the process's existing controlling terminal
+- device. Operations on the new file descriptor will never induce
+- job control signals. *Note Job Control::.
+-
+- - Macro: int O_NOLINK
+- If the named file is a symbolic link, open the link itself instead
+- of the file it refers to. (`fstat' on the new file descriptor will
+- return the information returned by `lstat' on the link's name.)
+-
+- - Macro: int O_NOTRANS
+- If the named file is specially translated, do not invoke the
+- translator. Open the bare file the translator itself sees.
+-
+- The open-time action flags tell `open' to do additional operations
+-which are not really related to opening the file. The reason to do them
+-as part of `open' instead of in separate calls is that `open' can do
+-them atomically.
+-
+- - Macro: int O_TRUNC
+- Truncate the file to zero length. This option is only useful for
+- regular files, not special files such as directories or FIFOs.
+- POSIX.1 requires that you open the file for writing to use
+- `O_TRUNC'. In BSD and GNU you must have permission to write the
+- file to truncate it, but you need not open for write access.
+-
+- This is the only open-time action flag specified by POSIX.1.
+- There is no good reason for truncation to be done by `open',
+- instead of by calling `ftruncate' afterwards. The `O_TRUNC' flag
+- existed in Unix before `ftruncate' was invented, and is retained
+- for backward compatibility.
+-
+- - Macro: int O_SHLOCK
+- Acquire a shared lock on the file, as with `flock'. *Note File
+- Locks::.
+-
+- If `O_CREAT' is specified, the locking is done atomically when
+- creating the file. You are guaranteed that no other process will
+- get the lock on the new file first.
+-
+- - Macro: int O_EXLOCK
+- Acquire an exclusive lock on the file, as with `flock'. *Note
+- File Locks::. This is atomic like `O_SHLOCK'.
+-
+diff -purN -x BOOT ../glibc-2.0.1/set-init.c glibc-2.0.1/set-init.c
+--- ../glibc-2.0.1/set-init.c 1997-01-04 13:28:47.000000000 +0100
++++ glibc-2.0.1/set-init.c 2018-06-05 20:48:52.485487171 +0200
+@@ -19,5 +19,7 @@
+ #include <stdlib.h>
+ #include "set-hooks.h"
+
++int __libc_subinit ();
++
+ DEFINE_HOOK_RUNNER (__libc_subinit, __libc_init,
+ (int argc, char **argv, char **envp), (argc, argv, envp))
+diff -purN -x BOOT ../glibc-2.0.1/soversions.mk glibc-2.0.1/soversions.mk
+--- ../glibc-2.0.1/soversions.mk 1970-01-01 01:00:00.000000000 +0100
++++ glibc-2.0.1/soversions.mk 2018-06-05 22:08:58.655834070 +0200
+@@ -0,0 +1,30 @@
++libm.so-version=.6
++all-sonames+=libm.so$(libm.so-version)
++libc.so-version=.6
++all-sonames+=libc.so$(libc.so-version)
++ld.so-version=ld-linux.so.2
++all-sonames+=$(ld.so-version)
++libdl.so-version=.2
++all-sonames+=libdl.so$(libdl.so-version)
++libutil.so-version=.1
++all-sonames+=libutil.so$(libutil.so-version)
++libresolv.so-version=.2
++all-sonames+=libresolv.so$(libresolv.so-version)
++libnss_files.so-version=.1
++all-sonames+=libnss_files.so$(libnss_files.so-version)
++libnss_dns.so-version=.1
++all-sonames+=libnss_dns.so$(libnss_dns.so-version)
++libnss_db.so-version=.1
++all-sonames+=libnss_db.so$(libnss_db.so-version)
++libnss_compat.so-version=.1
++all-sonames+=libnss_compat.so$(libnss_compat.so-version)
++libnss_nis.so-version=.1
++all-sonames+=libnss_nis.so$(libnss_nis.so-version)
++libnsl.so-version=.1
++all-sonames+=libnsl.so$(libnsl.so-version)
++libdb.so-version=.2
++all-sonames+=libdb.so$(libdb.so-version)
++libcrypt.so-version=.1
++all-sonames+=libcrypt.so$(libcrypt.so-version)
++libBrokenLocale.so-version=.1
++all-sonames+=libBrokenLocale.so$(libBrokenLocale.so-version)
+diff -purN -x BOOT ../glibc-2.0.1/s-proto.d glibc-2.0.1/s-proto.d
+--- ../glibc-2.0.1/s-proto.d 1970-01-01 01:00:00.000000000 +0100
++++ glibc-2.0.1/s-proto.d 2018-06-05 20:53:03.945575790 +0200
+@@ -0,0 +1 @@
++../s-proto.o ../s-proto.so ../s-proto.po ../s-proto.d:
../sysdeps/unix/s-proto.S
+diff -purN -x BOOT ../glibc-2.0.1/sysdeps/unix/sysv/linux/i386/sysdep.S
glibc-2.0.1/sysdeps/unix/sysv/linux/i386/sysdep.S
+--- ../glibc-2.0.1/sysdeps/unix/sysv/linux/i386/sysdep.S 1996-11-28
03:30:50.000000000 +0100
++++ glibc-2.0.1/sysdeps/unix/sysv/linux/i386/sysdep.S 2018-06-05
20:39:51.704574546 +0200
+@@ -45,7 +45,7 @@ _errno = errno /* This name is expected
+ The code for Linux is almost identical to the canonical Unix/i386
+ code, except that the error number in %eax is negated. */
+
+-ENTRY (__syscall_error)
++__syscall_error:
+ negl %eax
+
+ #define __syscall_error __syscall_error_1
+diff -purN -x BOOT ../glibc-2.0.1/sysdeps/unix/sysv/linux/init-first.c
glibc-2.0.1/sysdeps/unix/sysv/linux/init-first.c
+--- ../glibc-2.0.1/sysdeps/unix/sysv/linux/init-first.c 1996-11-28
03:10:38.000000000 +0100
++++ glibc-2.0.1/sysdeps/unix/sysv/linux/init-first.c 2018-06-05
20:59:51.108176593 +0200
+@@ -41,6 +41,7 @@ int __libc_multiple_libcs = 1;
+ int __libc_argc;
+ char **__libc_argv;
+
++extern char **environ;
+
+ static void
+ init (int argc, char **argv, char **envp)
+@@ -57,14 +58,16 @@ init (int argc, char **argv, char **envp
+ the executable format. */
+ __personality (PER_LINUX);
+
++#if 0
+ /* Set the FPU control word to the proper default value. */
+ __setfpucw (__fpu_control);
++#endif
+ }
+
+ /* Save the command-line arguments. */
+ __libc_argc = argc;
+ __libc_argv = argv;
+- __environ = envp;
++ environ = envp;
+
+ __libc_init (argc, argv, envp);
+
+diff -purN -x BOOT ../glibc-2.0.1/sysd-syscalls glibc-2.0.1/sysd-syscalls
+--- ../glibc-2.0.1/sysd-syscalls 1970-01-01 01:00:00.000000000 +0100
++++ glibc-2.0.1/sysd-syscalls 2018-06-05 07:02:42.935962548 +0200
+@@ -0,0 +1,1376 @@
++ifeq (,$(filter s_getgroups,$(unix-syscalls)))
++unix-syscalls += s_getgroups
++unix-extra-syscalls += s_getgroups
++$(foreach o,$(object-suffixes),$(objpfx)s_getgroups$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__syscall_getgroups, getgroups, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__syscall_getgroups)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter s_llseek,$(unix-syscalls)))
++unix-syscalls += s_llseek
++unix-extra-syscalls += s_llseek
++$(foreach o,$(object-suffixes),$(objpfx)s_llseek$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__sys_llseek, _llseek, 5)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__sys_llseek)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter s_setgroups,$(unix-syscalls)))
++unix-syscalls += s_setgroups
++unix-extra-syscalls += s_setgroups
++$(foreach o,$(object-suffixes),$(objpfx)s_setgroups$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__syscall_setgroups, setgroups, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__syscall_setgroups)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter vm86,$(unix-syscalls)))
++unix-syscalls += vm86
++$(foreach o,$(object-suffixes),$(objpfx)vm86$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__vm86, vm86, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__vm86)'; \
++ echo 'weak_alias (__vm86, vm86)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter adjtimex,$(unix-syscalls)))
++unix-syscalls += adjtimex
++unix-extra-syscalls += adjtimex
++$(foreach o,$(object-suffixes),$(objpfx)adjtimex$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__adjtimex, adjtimex, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__adjtimex)'; \
++ echo 'weak_alias (__adjtimex, adjtimex)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter bdflush,$(unix-syscalls)))
++unix-syscalls += bdflush
++unix-extra-syscalls += bdflush
++$(foreach o,$(object-suffixes),$(objpfx)bdflush$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (bdflush, bdflush, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(bdflush)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter create_module,$(unix-syscalls)))
++unix-syscalls += create_module
++unix-extra-syscalls += create_module
++$(foreach o,$(object-suffixes),$(objpfx)create_module$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (create_module, create_module, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(create_module)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter delete_module,$(unix-syscalls)))
++unix-syscalls += delete_module
++unix-extra-syscalls += delete_module
++$(foreach o,$(object-suffixes),$(objpfx)delete_module$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (delete_module, delete_module, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(delete_module)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter fdatasync,$(unix-syscalls)))
++unix-syscalls += fdatasync
++$(foreach o,$(object-suffixes),$(objpfx)fdatasync$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (fdatasync, fdatasync, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(fdatasync)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter flock,$(unix-syscalls)))
++unix-syscalls += flock
++$(foreach o,$(object-suffixes),$(objpfx)flock$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__flock, flock, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__flock)'; \
++ echo 'weak_alias (__flock, flock)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter fork,$(unix-syscalls)))
++unix-syscalls += fork
++$(foreach o,$(object-suffixes),$(objpfx)fork$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__fork, fork, 0)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__fork)'; \
++ echo 'weak_alias (__fork, fork)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter get_kernel_syms,$(unix-syscalls)))
++unix-syscalls += get_kernel_syms
++unix-extra-syscalls += get_kernel_syms
++$(foreach o,$(object-suffixes),$(objpfx)get_kernel_syms$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (get_kernel_syms, get_kernel_syms, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(get_kernel_syms)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getegid,$(unix-syscalls)))
++unix-syscalls += getegid
++$(foreach o,$(object-suffixes),$(objpfx)getegid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__getegid, getegid, 0)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__getegid)'; \
++ echo 'weak_alias (__getegid, getegid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter geteuid,$(unix-syscalls)))
++unix-syscalls += geteuid
++$(foreach o,$(object-suffixes),$(objpfx)geteuid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__geteuid, geteuid, 0)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__geteuid)'; \
++ echo 'weak_alias (__geteuid, geteuid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getpgid,$(unix-syscalls)))
++unix-syscalls += getpgid
++$(foreach o,$(object-suffixes),$(objpfx)getpgid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__getpgid, getpgid, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__getpgid)'; \
++ echo 'weak_alias (__getpgid, getpgid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getpgrp,$(unix-syscalls)))
++unix-syscalls += getpgrp
++$(foreach o,$(object-suffixes),$(objpfx)getpgrp$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (getpgrp, getpgrp, 0)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(getpgrp)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getppid,$(unix-syscalls)))
++unix-syscalls += getppid
++$(foreach o,$(object-suffixes),$(objpfx)getppid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__getppid, getppid, 0)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__getppid)'; \
++ echo 'weak_alias (__getppid, getppid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getresuid,$(unix-syscalls)))
++unix-syscalls += getresuid
++unix-extra-syscalls += getresuid
++$(foreach o,$(object-suffixes),$(objpfx)getresuid$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (getresuid, getresuid, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(getresuid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getsid,$(unix-syscalls)))
++unix-syscalls += getsid
++$(foreach o,$(object-suffixes),$(objpfx)getsid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (getsid, getsid, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(getsid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter init_module,$(unix-syscalls)))
++unix-syscalls += init_module
++unix-extra-syscalls += init_module
++$(foreach o,$(object-suffixes),$(objpfx)init_module$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (init_module, init_module, 5)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(init_module)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter ioperm,$(unix-syscalls)))
++unix-syscalls += ioperm
++$(foreach o,$(object-suffixes),$(objpfx)ioperm$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (ioperm, ioperm, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(ioperm)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter iopl,$(unix-syscalls)))
++unix-syscalls += iopl
++$(foreach o,$(object-suffixes),$(objpfx)iopl$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (iopl, iopl, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(iopl)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter ipc,$(unix-syscalls)))
++unix-syscalls += ipc
++unix-extra-syscalls += ipc
++$(foreach o,$(object-suffixes),$(objpfx)ipc$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__ipc, ipc, 5)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__ipc)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter klogctl,$(unix-syscalls)))
++unix-syscalls += klogctl
++unix-extra-syscalls += klogctl
++$(foreach o,$(object-suffixes),$(objpfx)klogctl$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (klogctl, syslog, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(klogctl)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter mlock,$(unix-syscalls)))
++unix-syscalls += mlock
++unix-extra-syscalls += mlock
++$(foreach o,$(object-suffixes),$(objpfx)mlock$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__mlock, mlock, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__mlock)'; \
++ echo 'weak_alias (__mlock, mlock)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter mlockall,$(unix-syscalls)))
++unix-syscalls += mlockall
++unix-extra-syscalls += mlockall
++$(foreach o,$(object-suffixes),$(objpfx)mlockall$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__mlockall, mlockall, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__mlockall)'; \
++ echo 'weak_alias (__mlockall, mlockall)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter mount,$(unix-syscalls)))
++unix-syscalls += mount
++unix-extra-syscalls += mount
++$(foreach o,$(object-suffixes),$(objpfx)mount$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__mount, mount, 5)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__mount)'; \
++ echo 'weak_alias (__mount, mount)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter mremap,$(unix-syscalls)))
++unix-syscalls += mremap
++unix-extra-syscalls += mremap
++$(foreach o,$(object-suffixes),$(objpfx)mremap$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__mremap, mremap, 4)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__mremap)'; \
++ echo 'weak_alias (__mremap, mremap)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter munlock,$(unix-syscalls)))
++unix-syscalls += munlock
++unix-extra-syscalls += munlock
++$(foreach o,$(object-suffixes),$(objpfx)munlock$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__munlock, munlock, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__munlock)'; \
++ echo 'weak_alias (__munlock, munlock)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter munlockall,$(unix-syscalls)))
++unix-syscalls += munlockall
++unix-extra-syscalls += munlockall
++$(foreach o,$(object-suffixes),$(objpfx)munlockall$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__munlockall, munlockall, 0)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__munlockall)'; \
++ echo 'weak_alias (__munlockall, munlockall)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter nanosleep,$(unix-syscalls)))
++unix-syscalls += nanosleep
++$(foreach o,$(object-suffixes),$(objpfx)nanosleep$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__libc_nanosleep, nanosleep, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__libc_nanosleep)'; \
++ echo 'weak_alias (__libc_nanosleep, __nanosleep)'; \
++ echo 'weak_alias (__libc_nanosleep, nanosleep)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter pause,$(unix-syscalls)))
++unix-syscalls += pause
++$(foreach o,$(object-suffixes),$(objpfx)pause$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__libc_pause, pause, 0)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__libc_pause)'; \
++ echo 'weak_alias (__libc_pause, pause)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter personality,$(unix-syscalls)))
++unix-syscalls += personality
++unix-extra-syscalls += personality
++$(foreach o,$(object-suffixes),$(objpfx)personality$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__personality, personality, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__personality)'; \
++ echo 'weak_alias (__personality, personality)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter pipe,$(unix-syscalls)))
++unix-syscalls += pipe
++$(foreach o,$(object-suffixes),$(objpfx)pipe$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__pipe, pipe, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__pipe)'; \
++ echo 'weak_alias (__pipe, pipe)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter query_module,$(unix-syscalls)))
++unix-syscalls += query_module
++unix-extra-syscalls += query_module
++$(foreach o,$(object-suffixes),$(objpfx)query_module$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (query_module, query_module, 5)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(query_module)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter s_getdents,$(unix-syscalls)))
++unix-syscalls += s_getdents
++unix-extra-syscalls += s_getdents
++$(foreach o,$(object-suffixes),$(objpfx)s_getdents$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__getdents, getdents, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__getdents)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter s_getpriority,$(unix-syscalls)))
++unix-syscalls += s_getpriority
++unix-extra-syscalls += s_getpriority
++$(foreach o,$(object-suffixes),$(objpfx)s_getpriority$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__syscall_getpriority, getpriority, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__syscall_getpriority)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter s_ptrace,$(unix-syscalls)))
++unix-syscalls += s_ptrace
++unix-extra-syscalls += s_ptrace
++$(foreach o,$(object-suffixes),$(objpfx)s_ptrace$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__syscall_ptrace, ptrace, 4)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__syscall_ptrace)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter s_reboot,$(unix-syscalls)))
++unix-syscalls += s_reboot
++unix-extra-syscalls += s_reboot
++$(foreach o,$(object-suffixes),$(objpfx)s_reboot$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__syscall_reboot, reboot, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__syscall_reboot)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter s_sigsuspend,$(unix-syscalls)))
++unix-syscalls += s_sigsuspend
++unix-extra-syscalls += s_sigsuspend
++$(foreach o,$(object-suffixes),$(objpfx)s_sigsuspend$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__syscall_sigsuspend, sigsuspend, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__syscall_sigsuspend)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter s_sysctl,$(unix-syscalls)))
++unix-syscalls += s_sysctl
++unix-extra-syscalls += s_sysctl
++$(foreach o,$(object-suffixes),$(objpfx)s_sysctl$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__syscall__sysctl, _sysctl, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__syscall__sysctl)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter s_ustat,$(unix-syscalls)))
++unix-syscalls += s_ustat
++unix-extra-syscalls += s_ustat
++$(foreach o,$(object-suffixes),$(objpfx)s_ustat$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__syscall_ustat, ustat, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__syscall_ustat)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sched_getp,$(unix-syscalls)))
++unix-syscalls += sched_getp
++$(foreach o,$(object-suffixes),$(objpfx)sched_getp$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__sched_getparam, sched_getparam, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__sched_getparam)'; \
++ echo 'weak_alias (__sched_getparam, sched_getparam)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sched_gets,$(unix-syscalls)))
++unix-syscalls += sched_gets
++$(foreach o,$(object-suffixes),$(objpfx)sched_gets$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__sched_getscheduler, sched_getscheduler, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__sched_getscheduler)'; \
++ echo 'weak_alias (__sched_getscheduler, sched_getscheduler)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sched_primax,$(unix-syscalls)))
++unix-syscalls += sched_primax
++$(foreach o,$(object-suffixes),$(objpfx)sched_primax$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__sched_get_priority_max, sched_get_priority_max, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__sched_get_priority_max)'; \
++ echo 'weak_alias (__sched_get_priority_max, sched_get_priority_max)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sched_primin,$(unix-syscalls)))
++unix-syscalls += sched_primin
++$(foreach o,$(object-suffixes),$(objpfx)sched_primin$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__sched_get_priority_min, sched_get_priority_min, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__sched_get_priority_min)'; \
++ echo 'weak_alias (__sched_get_priority_min, sched_get_priority_min)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sched_rr_gi,$(unix-syscalls)))
++unix-syscalls += sched_rr_gi
++$(foreach o,$(object-suffixes),$(objpfx)sched_rr_gi$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__sched_rr_get_interval, sched_rr_get_interval, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__sched_rr_get_interval)'; \
++ echo 'weak_alias (__sched_rr_get_interval, sched_rr_get_interval)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sched_setp,$(unix-syscalls)))
++unix-syscalls += sched_setp
++$(foreach o,$(object-suffixes),$(objpfx)sched_setp$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__sched_setparam, sched_setparam, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__sched_setparam)'; \
++ echo 'weak_alias (__sched_setparam, sched_setparam)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sched_sets,$(unix-syscalls)))
++unix-syscalls += sched_sets
++$(foreach o,$(object-suffixes),$(objpfx)sched_sets$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__sched_setscheduler, sched_setscheduler, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__sched_setscheduler)'; \
++ echo 'weak_alias (__sched_setscheduler, sched_setscheduler)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sched_yield,$(unix-syscalls)))
++unix-syscalls += sched_yield
++$(foreach o,$(object-suffixes),$(objpfx)sched_yield$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__sched_yield, sched_yield, 0)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__sched_yield)'; \
++ echo 'weak_alias (__sched_yield, sched_yield)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter select,$(unix-syscalls)))
++unix-syscalls += select
++$(foreach o,$(object-suffixes),$(objpfx)select$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__select, _newselect, 5)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__select)'; \
++ echo 'weak_alias (__select, select)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setfsgid,$(unix-syscalls)))
++unix-syscalls += setfsgid
++unix-extra-syscalls += setfsgid
++$(foreach o,$(object-suffixes),$(objpfx)setfsgid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (setfsgid, setfsgid, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(setfsgid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setfsuid,$(unix-syscalls)))
++unix-syscalls += setfsuid
++unix-extra-syscalls += setfsuid
++$(foreach o,$(object-suffixes),$(objpfx)setfsuid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (setfsuid, setfsuid, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(setfsuid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setpgid,$(unix-syscalls)))
++unix-syscalls += setpgid
++$(foreach o,$(object-suffixes),$(objpfx)setpgid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__setpgid, setpgid, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__setpgid)'; \
++ echo 'weak_alias (__setpgid, setpgid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setresuid,$(unix-syscalls)))
++unix-syscalls += setresuid
++unix-extra-syscalls += setresuid
++$(foreach o,$(object-suffixes),$(objpfx)setresuid$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (setresuid, setresuid, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(setresuid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sigpending,$(unix-syscalls)))
++unix-syscalls += sigpending
++$(foreach o,$(object-suffixes),$(objpfx)sigpending$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (sigpending, sigpending, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(sigpending)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sigprocmask,$(unix-syscalls)))
++unix-syscalls += sigprocmask
++$(foreach o,$(object-suffixes),$(objpfx)sigprocmask$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__sigprocmask, sigprocmask, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__sigprocmask)'; \
++ echo 'weak_alias (__sigprocmask, sigprocmask)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sigreturn,$(unix-syscalls)))
++unix-syscalls += sigreturn
++$(foreach o,$(object-suffixes),$(objpfx)sigreturn$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__sigreturn, sigreturn, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__sigreturn)'; \
++ echo 'weak_alias (__sigreturn, sigreturn)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sys_mknod,$(unix-syscalls)))
++unix-syscalls += sys_mknod
++unix-extra-syscalls += sys_mknod
++$(foreach o,$(object-suffixes),$(objpfx)sys_mknod$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__syscall_mknod, mknod, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__syscall_mknod)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sysinfo,$(unix-syscalls)))
++unix-syscalls += sysinfo
++unix-extra-syscalls += sysinfo
++$(foreach o,$(object-suffixes),$(objpfx)sysinfo$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (sysinfo, sysinfo, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(sysinfo)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter swapon,$(unix-syscalls)))
++unix-syscalls += swapon
++$(foreach o,$(object-suffixes),$(objpfx)swapon$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (swapon, swapon, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(swapon)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter umount,$(unix-syscalls)))
++unix-syscalls += umount
++unix-extra-syscalls += umount
++$(foreach o,$(object-suffixes),$(objpfx)umount$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__umount, umount, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__umount)'; \
++ echo 'weak_alias (__umount, umount)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter uselib,$(unix-syscalls)))
++unix-syscalls += uselib
++unix-extra-syscalls += uselib
++$(foreach o,$(object-suffixes),$(objpfx)uselib$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (uselib, uselib, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(uselib)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter wait4,$(unix-syscalls)))
++unix-syscalls += wait4
++$(foreach o,$(object-suffixes),$(objpfx)wait4$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__wait4, wait4, 4)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__wait4)'; \
++ echo 'weak_alias (__wait4, wait4)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter fchmod,$(unix-syscalls)))
++unix-syscalls += fchmod
++$(foreach o,$(object-suffixes),$(objpfx)fchmod$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__fchmod, fchmod, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__fchmod)'; \
++ echo 'weak_alias (__fchmod, fchmod)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter fchown,$(unix-syscalls)))
++unix-syscalls += fchown
++$(foreach o,$(object-suffixes),$(objpfx)fchown$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__fchown, fchown, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__fchown)'; \
++ echo 'weak_alias (__fchown, fchown)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter ftruncate,$(unix-syscalls)))
++unix-syscalls += ftruncate
++$(foreach o,$(object-suffixes),$(objpfx)ftruncate$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (ftruncate, ftruncate, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(ftruncate)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getpgid,$(unix-syscalls)))
++unix-syscalls += getpgid
++$(foreach o,$(object-suffixes),$(objpfx)getpgid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__getpgid, getpgrp, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__getpgid)'; \
++ echo 'weak_alias (__getpgid, getpgid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getrusage,$(unix-syscalls)))
++unix-syscalls += getrusage
++$(foreach o,$(object-suffixes),$(objpfx)getrusage$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__getrusage, getrusage, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__getrusage)'; \
++ echo 'weak_alias (__getrusage, getrusage)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter gettimeofday,$(unix-syscalls)))
++unix-syscalls += gettimeofday
++$(foreach o,$(object-suffixes),$(objpfx)gettimeofday$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__gettimeofday, gettimeofday, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__gettimeofday)'; \
++ echo 'weak_alias (__gettimeofday, gettimeofday)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter settimeofday,$(unix-syscalls)))
++unix-syscalls += settimeofday
++$(foreach o,$(object-suffixes),$(objpfx)settimeofday$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__settimeofday, settimeofday, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__settimeofday)'; \
++ echo 'weak_alias (__settimeofday, settimeofday)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setpgid,$(unix-syscalls)))
++unix-syscalls += setpgid
++$(foreach o,$(object-suffixes),$(objpfx)setpgid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__setpgid, setpgrp, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__setpgid)'; \
++ echo 'weak_alias (__setpgid, setpgid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setregid,$(unix-syscalls)))
++unix-syscalls += setregid
++$(foreach o,$(object-suffixes),$(objpfx)setregid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__setregid, setregid, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__setregid)'; \
++ echo 'weak_alias (__setregid, setregid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setreuid,$(unix-syscalls)))
++unix-syscalls += setreuid
++$(foreach o,$(object-suffixes),$(objpfx)setreuid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__setreuid, setreuid, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__setreuid)'; \
++ echo 'weak_alias (__setreuid, setreuid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sys_lstat,$(unix-syscalls)))
++unix-syscalls += sys_lstat
++unix-extra-syscalls += sys_lstat
++$(foreach o,$(object-suffixes),$(objpfx)sys_lstat$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__syscall_lstat, lstat, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__syscall_lstat)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter truncate,$(unix-syscalls)))
++unix-syscalls += truncate
++$(foreach o,$(object-suffixes),$(objpfx)truncate$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (truncate, truncate, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(truncate)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter vhangup,$(unix-syscalls)))
++unix-syscalls += vhangup
++$(foreach o,$(object-suffixes),$(objpfx)vhangup$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (vhangup, vhangup, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(vhangup)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter mprotect,$(unix-syscalls)))
++unix-syscalls += mprotect
++$(foreach o,$(object-suffixes),$(objpfx)mprotect$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__mprotect, mprotect, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__mprotect)'; \
++ echo 'weak_alias (__mprotect, mprotect)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter msync,$(unix-syscalls)))
++unix-syscalls += msync
++$(foreach o,$(object-suffixes),$(objpfx)msync$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__libc_msync, msync, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__libc_msync)'; \
++ echo 'weak_alias (__libc_msync, msync)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter munmap,$(unix-syscalls)))
++unix-syscalls += munmap
++$(foreach o,$(object-suffixes),$(objpfx)munmap$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__munmap, munmap, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__munmap)'; \
++ echo 'weak_alias (__munmap, munmap)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sethostname,$(unix-syscalls)))
++unix-syscalls += sethostname
++$(foreach o,$(object-suffixes),$(objpfx)sethostname$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (sethostname, sethostname, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(sethostname)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter alarm,$(unix-syscalls)))
++unix-syscalls += alarm
++$(foreach o,$(object-suffixes),$(objpfx)alarm$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (alarm, alarm, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(alarm)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter nice,$(unix-syscalls)))
++unix-syscalls += nice
++$(foreach o,$(object-suffixes),$(objpfx)nice$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (nice, nice, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(nice)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setrlimit,$(unix-syscalls)))
++unix-syscalls += setrlimit
++$(foreach o,$(object-suffixes),$(objpfx)setrlimit$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (setrlimit, setrlimit, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(setrlimit)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter settimeofday,$(unix-syscalls)))
++unix-syscalls += settimeofday
++$(foreach o,$(object-suffixes),$(objpfx)settimeofday$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__settimeofday, settimeofday, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__settimeofday)'; \
++ echo 'weak_alias (__settimeofday, settimeofday)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter stime,$(unix-syscalls)))
++unix-syscalls += stime
++$(foreach o,$(object-suffixes),$(objpfx)stime$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (stime, stime, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(stime)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter times,$(unix-syscalls)))
++unix-syscalls += times
++$(foreach o,$(object-suffixes),$(objpfx)times$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__times, times, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__times)'; \
++ echo 'weak_alias (__times, times)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter utime,$(unix-syscalls)))
++unix-syscalls += utime
++$(foreach o,$(object-suffixes),$(objpfx)utime$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (utime, utime, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(utime)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter access,$(unix-syscalls)))
++unix-syscalls += access
++$(foreach o,$(object-suffixes),$(objpfx)access$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__access, access, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__access)'; \
++ echo 'weak_alias (__access, access)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter acct,$(unix-syscalls)))
++unix-syscalls += acct
++$(foreach o,$(object-suffixes),$(objpfx)acct$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (acct, acct, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(acct)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter chdir,$(unix-syscalls)))
++unix-syscalls += chdir
++$(foreach o,$(object-suffixes),$(objpfx)chdir$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__chdir, chdir, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__chdir)'; \
++ echo 'weak_alias (__chdir, chdir)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter chmod,$(unix-syscalls)))
++unix-syscalls += chmod
++$(foreach o,$(object-suffixes),$(objpfx)chmod$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__chmod, chmod, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__chmod)'; \
++ echo 'weak_alias (__chmod, chmod)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter chown,$(unix-syscalls)))
++unix-syscalls += chown
++$(foreach o,$(object-suffixes),$(objpfx)chown$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__chown, chown, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__chown)'; \
++ echo 'weak_alias (__chown, chown)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter chroot,$(unix-syscalls)))
++unix-syscalls += chroot
++$(foreach o,$(object-suffixes),$(objpfx)chroot$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (chroot, chroot, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(chroot)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter close,$(unix-syscalls)))
++unix-syscalls += close
++$(foreach o,$(object-suffixes),$(objpfx)close$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__libc_close, close, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__libc_close)'; \
++ echo 'weak_alias (__libc_close, __close)'; \
++ echo 'weak_alias (__libc_close, close)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter dup,$(unix-syscalls)))
++unix-syscalls += dup
++$(foreach o,$(object-suffixes),$(objpfx)dup$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__dup, dup, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__dup)'; \
++ echo 'weak_alias (__dup, dup)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter dup2,$(unix-syscalls)))
++unix-syscalls += dup2
++$(foreach o,$(object-suffixes),$(objpfx)dup2$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__dup2, dup2, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__dup2)'; \
++ echo 'weak_alias (__dup2, dup2)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter fchdir,$(unix-syscalls)))
++unix-syscalls += fchdir
++$(foreach o,$(object-suffixes),$(objpfx)fchdir$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (fchdir, fchdir, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(fchdir)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter fcntl,$(unix-syscalls)))
++unix-syscalls += fcntl
++$(foreach o,$(object-suffixes),$(objpfx)fcntl$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__libc_fcntl, fcntl, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__libc_fcntl)'; \
++ echo 'weak_alias (__libc_fcntl, __fcntl)'; \
++ echo 'weak_alias (__libc_fcntl, fcntl)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter fstatfs,$(unix-syscalls)))
++unix-syscalls += fstatfs
++$(foreach o,$(object-suffixes),$(objpfx)fstatfs$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__fstatfs, fstatfs, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__fstatfs)'; \
++ echo 'weak_alias (__fstatfs, fstatfs)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter fsync,$(unix-syscalls)))
++unix-syscalls += fsync
++$(foreach o,$(object-suffixes),$(objpfx)fsync$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__libc_fsync, fsync, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__libc_fsync)'; \
++ echo 'weak_alias (__libc_fsync, fsync)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getdomain,$(unix-syscalls)))
++unix-syscalls += getdomain
++$(foreach o,$(object-suffixes),$(objpfx)getdomain$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (getdomainname, getdomainname, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(getdomainname)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getgid,$(unix-syscalls)))
++unix-syscalls += getgid
++$(foreach o,$(object-suffixes),$(objpfx)getgid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__getgid, getgid, 0)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__getgid)'; \
++ echo 'weak_alias (__getgid, getgid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getitimer,$(unix-syscalls)))
++unix-syscalls += getitimer
++$(foreach o,$(object-suffixes),$(objpfx)getitimer$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__getitimer, getitimer, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__getitimer)'; \
++ echo 'weak_alias (__getitimer, getitimer)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getpid,$(unix-syscalls)))
++unix-syscalls += getpid
++$(foreach o,$(object-suffixes),$(objpfx)getpid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__getpid, getpid, 0)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__getpid)'; \
++ echo 'weak_alias (__getpid, getpid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getrlimit,$(unix-syscalls)))
++unix-syscalls += getrlimit
++$(foreach o,$(object-suffixes),$(objpfx)getrlimit$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__getrlimit, getrlimit, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__getrlimit)'; \
++ echo 'weak_alias (__getrlimit, getrlimit)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter getuid,$(unix-syscalls)))
++unix-syscalls += getuid
++$(foreach o,$(object-suffixes),$(objpfx)getuid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__getuid, getuid, 0)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__getuid)'; \
++ echo 'weak_alias (__getuid, getuid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter ioctl,$(unix-syscalls)))
++unix-syscalls += ioctl
++$(foreach o,$(object-suffixes),$(objpfx)ioctl$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__ioctl, ioctl, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__ioctl)'; \
++ echo 'weak_alias (__ioctl, ioctl)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter kill,$(unix-syscalls)))
++unix-syscalls += kill
++$(foreach o,$(object-suffixes),$(objpfx)kill$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__kill, kill, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__kill)'; \
++ echo 'weak_alias (__kill, kill)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter link,$(unix-syscalls)))
++unix-syscalls += link
++$(foreach o,$(object-suffixes),$(objpfx)link$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__link, link, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__link)'; \
++ echo 'weak_alias (__link, link)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter lseek,$(unix-syscalls)))
++unix-syscalls += lseek
++$(foreach o,$(object-suffixes),$(objpfx)lseek$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__libc_lseek, lseek, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__libc_lseek)'; \
++ echo 'weak_alias (__libc_lseek, __lseek)'; \
++ echo 'weak_alias (__libc_lseek, lseek)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter mkdir,$(unix-syscalls)))
++unix-syscalls += mkdir
++$(foreach o,$(object-suffixes),$(objpfx)mkdir$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__mkdir, mkdir, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__mkdir)'; \
++ echo 'weak_alias (__mkdir, mkdir)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter open,$(unix-syscalls)))
++unix-syscalls += open
++$(foreach o,$(object-suffixes),$(objpfx)open$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__libc_open, open, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__libc_open)'; \
++ echo 'weak_alias (__libc_open, __open)'; \
++ echo 'weak_alias (__libc_open, open)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter read,$(unix-syscalls)))
++unix-syscalls += read
++$(foreach o,$(object-suffixes),$(objpfx)read$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__libc_read, read, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__libc_read)'; \
++ echo 'weak_alias (__libc_read, __read)'; \
++ echo 'weak_alias (__libc_read, read)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter readlink,$(unix-syscalls)))
++unix-syscalls += readlink
++$(foreach o,$(object-suffixes),$(objpfx)readlink$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__readlink, readlink, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__readlink)'; \
++ echo 'weak_alias (__readlink, readlink)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter readv,$(unix-syscalls)))
++unix-syscalls += readv
++$(foreach o,$(object-suffixes),$(objpfx)readv$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (readv, readv, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(readv)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter rename,$(unix-syscalls)))
++unix-syscalls += rename
++$(foreach o,$(object-suffixes),$(objpfx)rename$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (rename, rename, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(rename)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter rmdir,$(unix-syscalls)))
++unix-syscalls += rmdir
++$(foreach o,$(object-suffixes),$(objpfx)rmdir$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__rmdir, rmdir, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__rmdir)'; \
++ echo 'weak_alias (__rmdir, rmdir)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter select,$(unix-syscalls)))
++unix-syscalls += select
++$(foreach o,$(object-suffixes),$(objpfx)select$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__select, select, 5)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__select)'; \
++ echo 'weak_alias (__select, select)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setdomain,$(unix-syscalls)))
++unix-syscalls += setdomain
++$(foreach o,$(object-suffixes),$(objpfx)setdomain$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (setdomainname, setdomainname, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(setdomainname)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setgid,$(unix-syscalls)))
++unix-syscalls += setgid
++$(foreach o,$(object-suffixes),$(objpfx)setgid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__setgid, setgid, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__setgid)'; \
++ echo 'weak_alias (__setgid, setgid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setitimer,$(unix-syscalls)))
++unix-syscalls += setitimer
++$(foreach o,$(object-suffixes),$(objpfx)setitimer$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__setitimer, setitimer, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__setitimer)'; \
++ echo 'weak_alias (__setitimer, setitimer)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setpriority,$(unix-syscalls)))
++unix-syscalls += setpriority
++$(foreach o,$(object-suffixes),$(objpfx)setpriority$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (setpriority, setpriority, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(setpriority)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setsid,$(unix-syscalls)))
++unix-syscalls += setsid
++$(foreach o,$(object-suffixes),$(objpfx)setsid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__setsid, setsid, 0)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__setsid)'; \
++ echo 'weak_alias (__setsid, setsid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter setuid,$(unix-syscalls)))
++unix-syscalls += setuid
++$(foreach o,$(object-suffixes),$(objpfx)setuid$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__setuid, setuid, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__setuid)'; \
++ echo 'weak_alias (__setuid, setuid)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sstk,$(unix-syscalls)))
++unix-syscalls += sstk
++$(foreach o,$(object-suffixes),$(objpfx)sstk$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (sstk, sstk, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(sstk)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter statfs,$(unix-syscalls)))
++unix-syscalls += statfs
++$(foreach o,$(object-suffixes),$(objpfx)statfs$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__statfs, statfs, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__statfs)'; \
++ echo 'weak_alias (__statfs, statfs)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter swapoff,$(unix-syscalls)))
++unix-syscalls += swapoff
++$(foreach o,$(object-suffixes),$(objpfx)swapoff$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (swapoff, swapoff, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(swapoff)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter swapon,$(unix-syscalls)))
++unix-syscalls += swapon
++$(foreach o,$(object-suffixes),$(objpfx)swapon$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (swapon, swapon, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(swapon)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter symlink,$(unix-syscalls)))
++unix-syscalls += symlink
++$(foreach o,$(object-suffixes),$(objpfx)symlink$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__symlink, symlink, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__symlink)'; \
++ echo 'weak_alias (__symlink, symlink)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sync,$(unix-syscalls)))
++unix-syscalls += sync
++$(foreach o,$(object-suffixes),$(objpfx)sync$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (sync, sync, 0)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(sync)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sys_fstat,$(unix-syscalls)))
++unix-syscalls += sys_fstat
++unix-extra-syscalls += sys_fstat
++$(foreach o,$(object-suffixes),$(objpfx)sys_fstat$o):
$(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__syscall_fstat, fstat, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__syscall_fstat)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter sys_stat,$(unix-syscalls)))
++unix-syscalls += sys_stat
++unix-extra-syscalls += sys_stat
++$(foreach o,$(object-suffixes),$(objpfx)sys_stat$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__syscall_stat, stat, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__syscall_stat)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter umask,$(unix-syscalls)))
++unix-syscalls += umask
++$(foreach o,$(object-suffixes),$(objpfx)umask$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__umask, umask, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__umask)'; \
++ echo 'weak_alias (__umask, umask)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter uname,$(unix-syscalls)))
++unix-syscalls += uname
++$(foreach o,$(object-suffixes),$(objpfx)uname$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (uname, uname, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(uname)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter unlink,$(unix-syscalls)))
++unix-syscalls += unlink
++$(foreach o,$(object-suffixes),$(objpfx)unlink$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__unlink, unlink, 1)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__unlink)'; \
++ echo 'weak_alias (__unlink, unlink)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter utimes,$(unix-syscalls)))
++unix-syscalls += utimes
++$(foreach o,$(object-suffixes),$(objpfx)utimes$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__utimes, utimes, 2)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__utimes)'; \
++ echo 'weak_alias (__utimes, utimes)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter write,$(unix-syscalls)))
++unix-syscalls += write
++$(foreach o,$(object-suffixes),$(objpfx)write$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (__libc_write, write, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(__libc_write)'; \
++ echo 'weak_alias (__libc_write, __write)'; \
++ echo 'weak_alias (__libc_write, write)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
++ifeq (,$(filter writev,$(unix-syscalls)))
++unix-syscalls += writev
++$(foreach o,$(object-suffixes),$(objpfx)writev$o): $(common-objpfx)s-proto.d
++ (echo '#include <sysdep.h>'; \
++ echo 'PSEUDO (writev, writev, 3)'; \
++ echo ' ret'; \
++ echo 'PSEUDO_END(writev)'; \
++ ) | $(COMPILE.S) -x assembler-with-cpp -o $@ -
++endif
+diff -purN -x BOOT ../glibc-2.0.1/version.c glibc-2.0.1/version.c
+--- ../glibc-2.0.1/version.c 1997-01-04 13:30:49.000000000 +0100
++++ glibc-2.0.1/version.c 2018-06-05 20:52:12.844747867 +0200
+@@ -32,6 +32,10 @@ PARTICULAR PURPOSE.\n"
+
+ #include <unistd.h>
+
++#ifndef STDOUT_FILENO
++#define STDOUT_FILENO 1
++#endif
++
+ void
+ __libc_print_version (void)
+ {
+diff -purN -x BOOT ../glibc-2.0.1/version.mk glibc-2.0.1/version.mk
+--- ../glibc-2.0.1/version.mk 1970-01-01 01:00:00.000000000 +0100
++++ glibc-2.0.1/version.mk 2018-06-05 07:02:42.067948564 +0200
+@@ -0,0 +1,2 @@
++release=experimental
++version=2.0.1
- 28/30: gnu: Add gcc-core-boot 2.95.3., (continued)
- 28/30: gnu: Add gcc-core-boot 2.95.3., Jan Nieuwenhuizen, 2018/06/12
- 24/30: Revert "gnu: gcc-boot: Update to 3.2.", Jan Nieuwenhuizen, 2018/06/12
- 20/30: gnu: gcc-boot: Update to 3.0., Jan Nieuwenhuizen, 2018/06/12
- 15/30: Revert "gnu: binutils-boot: Update to 2.30.", Jan Nieuwenhuizen, 2018/06/12
- 17/30: gnu: gcc-boot: Update to 2.6.3., Jan Nieuwenhuizen, 2018/06/12
- 27/30: gnu: glibc-boot: Update to 2.2.5., Jan Nieuwenhuizen, 2018/06/12
- 25/30: Revert "gnu: gcc-boot: Update to 3.0.", Jan Nieuwenhuizen, 2018/06/12
- 19/30: gnu: gcc-boot: Update to 2.95.3., Jan Nieuwenhuizen, 2018/06/12
- 13/30: gnu: binutils-boot: Update to 2.25., Jan Nieuwenhuizen, 2018/06/12
- 16/30: Revert "gnu: binutils-boot: Update to 2.25.", Jan Nieuwenhuizen, 2018/06/12
- 26/30: gnu: Add glibc-boot 2.0.1.,
Jan Nieuwenhuizen <=