[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
79/207: gnu: glibc-boot: Update to 2.2.5.
|
From: |
Jan Nieuwenhuizen |
|
Subject: |
79/207: gnu: glibc-boot: Update to 2.2.5. |
|
Date: |
Sat, 8 Sep 2018 13:26:08 -0400 (EDT) |
janneke pushed a commit to branch wip-bootstrap
in repository guix.
commit 8812901d29c6624b8ed2926ea08befcc8f9e650c
Author: Jan Nieuwenhuizen <address@hidden>
Date: Sun Jun 10 11:15:05 2018 +0200
gnu: glibc-boot: Update to 2.2.5.
* gnu/packages/mes.scm (glibc-boot): Update to 2.2.5.
* gnu/packages/patches/glibc-boot-2.2.5.patch: New file.
* gnu/packages/patches/glibc-boot.patch: Remove.
* gnu/local.mk (dist_patch_DATA): Rename it.
---
gnu/local.mk | 2 +-
gnu/packages/mes.scm | 90 +-
gnu/packages/patches/glibc-boot-2.2.5.patch | 204 +
gnu/packages/patches/glibc-boot.patch | 43015 --------------------------
4 files changed, 255 insertions(+), 43056 deletions(-)
diff --git a/gnu/local.mk b/gnu/local.mk
index fbc42ef..262c300 100644
--- a/gnu/local.mk
+++ b/gnu/local.mk
@@ -742,7 +742,7 @@ dist_patch_DATA =
\
%D%/packages/patches/glibc-CVE-2017-1000366-pt2.patch \
%D%/packages/patches/glibc-CVE-2017-1000366-pt3.patch \
%D%/packages/patches/glibc-allow-kernel-2.6.32.patch \
- %D%/packages/patches/glibc-boot.patch \
+ %D%/packages/patches/glibc-boot-2.2.5.patch \
%D%/packages/patches/glibc-bootstrap-system.patch \
%D%/packages/patches/glibc-hidden-visibility-ldconfig.patch \
%D%/packages/patches/glibc-ldd-x86_64.patch \
diff --git a/gnu/packages/mes.scm b/gnu/packages/mes.scm
index cc44c59..9667579 100644
--- a/gnu/packages/mes.scm
+++ b/gnu/packages/mes.scm
@@ -682,61 +682,71 @@ ac_cv_c_float_format='IEEE (little-endian)'
(package
(inherit glibc)
(name "glibc-boot")
- (version "2.0.1")
+ (version "2.2.5")
(source (origin
(method url-fetch)
- (uri (string-append
"https://gcc.gnu.org/pub/glibc/old-releases/glibc-";
- version ".tar.bz2"))
- (patches (search-patches "glibc-boot.patch"))
+ (uri (string-append "mirror://gnu/glibc/glibc-"
+ version
+ ".tar.gz"))
+ (patches (search-patches "glibc-boot-2.2.5.patch"))
(sha256
(base32
- "1cckm2242wcc0i0zbs7djjp2z215fdca0j3ay6ydxhchvw4vir2v"))))
+ "1vl48i16gx6h68whjyhgnn1s57vqq32f9ygfa2fls7pdkbsqvp2q"))))
(supported-systems '("i686-linux"))
(native-inputs `(("binutils" ,binutils-boot)
- ("gcc" ,gcc-boot)
- ("tcc" ,tcc-boot)))
+ ("gcc" ,gcc-boot)))
(propagated-inputs `(("kernel-headers" ,(linux-libre-headers-boot0))))
+ (outputs '("out"))
(arguments
- `(#:tests? #f ; runtest: command not found
+ `(#:tests? #f
#:strip-binaries? #f
- #:parallel-build? #f
- #:make-flags `(,(string-append "sysincludedir=" (assoc-ref
%build-inputs "tcc") "/include"))
- #:modules ((guix build gnu-build-system)
- (guix build utils)
- (srfi srfi-1))
+ #:parallel-build? #f ; gcc-2.95.3 ICEs on massively parallel builds
+ #:configure-flags
+ (let ((out (assoc-ref %outputs "out"))
+ (headers (assoc-ref %build-inputs "kernel-headers")))
+ #:configure-flags
+ (list
+ "--disable-shared"
+ "--enable-static"
+ "--disable-sanity-checks"
+ "--host=i386-unknown-linux"
+ "--target=i386-unknown-linux"
+ (string-append "--with-headers=" headers "/include")
+ "--enable-static-nss"
+ "--without-__thread"
+ "--without-cvs"
+ "--without-gd"
+ "--without-tls"
+ (string-append "--prefix=" out)))
+ #:make-flags '("lib")
#:phases
(modify-phases %standard-phases
- (replace 'configure
+ (add-before 'configure 'setenv
(lambda* (#:key outputs #:allow-other-keys)
- (let ((out (assoc-ref outputs "out"))
- (headers (assoc-ref %build-inputs "kernel-headers"))
- (binutils (assoc-ref %build-inputs "binutils"))
- (tcc (assoc-ref %build-inputs "tcc")))
- (setenv "PATH" (string-append
- binutils "/i686-unknown-linux-gnu/bin"
- ":" (getenv "PATH")))
+ (let* ((out (assoc-ref outputs "out"))
+ (headers (assoc-ref %build-inputs "kernel-headers"))
+ (gcc (assoc-ref %build-inputs "gcc"))
+ (cppflags (string-append
+ " -D __STDC__=1"
+ " -D MES_BOOTSTRAP=1"))
+ (cflags (string-append " -L " (getcwd))))
(setenv "CONFIG_SHELL" (string-append
(assoc-ref %build-inputs "bash")
"/bin/sh"))
- (setenv "CPPLAGS" (string-append "-I" headers "/include"))
- (setenv "CC" (string-append
- "gcc"
- " -I " headers "/include "
- " -D _POSIX_OPEN_MAX=16" ;; how to move to mes?
- " -DSTDOUT_FILENO=1"
- " -Dstderr=2"
- " -L " (getcwd)))
- (setenv "CPP" "gcc -E")
- (system* "ar" "r" "libc.a"
- (string-append tcc "/lib/libg.o"))
- (system* "ls" "-ltrF")
- (and
- (zero?
- (system* "./configure"
- "--host=i386-unknown-linux"
- "--target=i386-unknown-linux"
- "--disable-sanity-checks"
- (string-append "--prefix=" out))))))))))))
+ (setenv "CPP" (string-append gcc "/bin/gcc -E " cppflags))
+ (setenv "CC" (string-append gcc "/bin/gcc " cppflags cflags))
+ (unsetenv "C_INCLUDE_PATH")
+ (unsetenv "LIBRARY_PATH"))))
+ ;; glibc-2.2.5 needs a slightly more classical invocation of configure
+ ;; configure: warning:
CONFIG_SHELL=/gnu/store/kpxi8h3669afr9r1bgvaf9ij3y4wdyyn-bash-minimal-4.4.12/bin/bash:
invalid host type
+ (replace 'configure
+ (lambda* (#:key configure-flags #:allow-other-keys)
+ (zero?
+ (apply system* "./configure" configure-flags))))
+ (replace 'install
+ (lambda* (#:key make-flags #:allow-other-keys)
+ (zero?
+ (apply system* "make" "install-lib-all" "install-headers"
make-flags)))))))))
;;;
diff --git a/gnu/packages/patches/glibc-boot-2.2.5.patch
b/gnu/packages/patches/glibc-boot-2.2.5.patch
new file mode 100644
index 0000000..e8b9c52
--- /dev/null
+++ b/gnu/packages/patches/glibc-boot-2.2.5.patch
@@ -0,0 +1,204 @@
+odiff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/adiff glibc-2.2.5/adiff
+--- ../glibc-2.2.5/adiff 1970-01-01 01:00:00.000000000 +0100
++++ glibc-2.2.5/adiff 2018-06-09 10:43:27.954899327 +0200
+@@ -0,0 +1,26 @@
++make 4.x should be fine
++
++sed: unterminated `s' command
++
++ fopen_max=16
++ 16
++
++timex.h:
++
++gcc: Internal compiler error: program cc1 got fatal signal 11
++
++syslog.c:
++syslog.c:219: `cancel_handler' undeclared (first use in this function)
++
++Makefile:250: *** mixed implicit and normal rules: deprecated syntax
++make[1]: *** No rule to make target 'stamp.o', needed by 'lib'. Stop.
++make[1]: Leaving directory
'/tmp/guix-build-glibc-boot-2.2.5.drv-0/glibc-2.2.5/manual'
++
++math/ftestexcept.c:
++/tmp/guix-build-glibc-boot-2.2.5.drv-0/cce9CKia.s: Assembler messages:
++/tmp/guix-build-glibc-boot-2.2.5.drv-0/cce9CKia.s:61: Error: operand type
mismatch for `fnstsw'
++make[1]: *** [../sysd-rules:256: ftestexcept.o] Error 1
++make[1]: Leaving directory
'/tmp/guix-build-glibc-boot-2.2.5.drv-0/glibc-2.2.5/math'
++
++
++glibc-2.2.5/stdio-common/perror.c:68: undefined reference to `fileno_unlocked'
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/configure glibc-2.2.5/configure
+--- ../glibc-2.2.5/configure 2002-01-08 23:16:44.000000000 +0100
++++ glibc-2.2.5/configure 2018-06-07 20:47:26.608895319 +0200
+@@ -1530,7 +1530,7 @@ echo "configure:1530: checking version o
+ ac_prog_version=`$MAKE --version 2>&1 | sed -n 's/^.*GNU
Make[^0-9]*\([0-9][0-9.]*\).*$/\1/p'`
+ case $ac_prog_version in
+ '') ac_prog_version="v. ?.??, bad"; ac_verc_fail=yes;;
+- 3.79* | 3.[89]*)
++ 3.79* | 3.[89]* | 4.*)
+ ac_prog_version="$ac_prog_version, ok"; ac_verc_fail=no;;
+ *) ac_prog_version="$ac_prog_version, bad"; ac_verc_fail=yes;;
+
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/Makerules glibc-2.2.5/Makerules
+--- ../glibc-2.2.5/Makerules 2001-11-16 02:02:19.000000000 +0100
++++ glibc-2.2.5/Makerules 2018-06-10 14:54:18.152989789 +0200
+@@ -748,6 +748,18 @@ endef
+ installed-libcs := $(foreach o,$(filter-out .os,$(object-suffixes-for-libc)),\
+ $(inst_libdir)/$(patsubst %,$(libtype$o),\
+ $(libprefix)$(libc-name)))
++
++ifeq (yes,$(build-shared))
++install-lib-all: $(inst_libdir)/libc.a \
++ $(inst_slibdir)/libc.so$(libc.so-version) \
++ $(inst_slibdir)/libc-$(version).so \
++ $(inst_libdir)/libc.so \
++ install-lib
++else
++install-lib-all: $(inst_libdir)/libc.a \
++ install-lib
++endif
++
+ install: $(installed-libcs)
+ $(installed-libcs): $(inst_libdir)/lib$(libprefix)%: lib $(+force)
+ $(make-target-directory)
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/misc/syslog.c
glibc-2.2.5/misc/syslog.c
+--- ../glibc-2.2.5/misc/syslog.c 2001-08-31 01:13:49.000000000 +0200
++++ glibc-2.2.5/misc/syslog.c 2018-06-09 09:01:20.008918690 +0200
+@@ -216,9 +216,11 @@ vsyslog(pri, fmt, ap)
+
+ /* Prepare for multiple users. We have to take care: open and
+ write are cancellation points. */
++#if _LIBC_REENTRANT
+ __libc_cleanup_region_start (1, (void (*) (void *)) cancel_handler,
+ &oldaction_ptr);
+ __libc_lock_lock (syslog_lock);
++#endif
+
+ /* Prepare for a broken connection. */
+ memset (&action, 0, sizeof (action));
+@@ -268,9 +270,11 @@ vsyslog(pri, fmt, ap)
+ if (sigpipe == 0)
+ __sigaction (SIGPIPE, &oldaction, (struct sigaction *) NULL);
+
++#if _LIBC_REENTRANT
+ /* End of critical section. */
+ __libc_cleanup_region_end (0);
+ __libc_lock_unlock (syslog_lock);
++#endif
+
+ free (buf);
+ }
+@@ -326,16 +330,20 @@ openlog_internal(const char *ident, int
+ void
+ openlog (const char *ident, int logstat, int logfac)
+ {
++#if _LIBC_REENTRANT
+ /* Protect against multiple users. */
+ __libc_cleanup_region_start (1,
+ (void (*) __P ((void *))) __libc_mutex_unlock,
+ &syslog_lock);
+ __libc_lock_lock (syslog_lock);
++#endif
+
+ openlog_internal (ident, logstat, logfac);
+
++#if _LIBC_REENTRANT
+ /* Free the lock. */
+ __libc_cleanup_region_end (1);
++#endif
+ }
+
+ static void
+@@ -358,18 +366,22 @@ closelog_internal()
+ void
+ closelog ()
+ {
++#if _LIBC_REENTRANT
+ /* Protect against multiple users. */
+ __libc_cleanup_region_start (1,
+ (void (*) __P ((void *))) __libc_mutex_unlock,
+ &syslog_lock);
+ __libc_lock_lock (syslog_lock);
++#endif
+
+ closelog_internal ();
+ LogTag = NULL;
+ LogType = SOCK_DGRAM; /* this is the default */
+
++#if _LIBC_REENTRANT
+ /* Free the lock. */
+ __libc_cleanup_region_end (1);
++#endif
+ }
+
+ #ifdef _LIBC_REENTRANT
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/Rules glibc-2.2.5/Rules
+--- ../glibc-2.2.5/Rules 2001-08-30 00:44:35.000000000 +0200
++++ glibc-2.2.5/Rules 2018-06-09 08:15:54.880683675 +0200
+@@ -218,7 +218,7 @@ endif
+ fopen_max=`sed -n 's/^#define OPEN_MAX //1p' $(@:st=hT)`; \
+ filename_max=`sed -n 's/^#define PATH_MAX //1p' $(@:st=hT)`; \
+ iov_max=`sed -n 's/^#define UIO_MAXIOV //p' $(@:st=hT)`; \
+- fopen_max=$${fopen_max:-16}; \
++ fopen_max=$${fu_fopen_max:-16}; \
+ filename_max=$${filename_max:-1024}; \
+ if [ -z $$iov_max ]; then \
+ define_iov_max="# undef IOV_MAX"; \
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/stdio-common/perror.c
glibc-2.2.5/stdio-common/perror.c
+--- ../glibc-2.2.5/stdio-common/perror.c 2001-09-01 07:33:01.000000000
+0200
++++ glibc-2.2.5/stdio-common/perror.c 2018-06-09 10:42:25.909899529 +0200
+@@ -48,6 +48,8 @@ perror_internal (FILE *fp, const char *s
+ }
+
+
++#define fileno_unlocked(x) 1
++
+ /* Print a line on stderr consisting of the text in S, a colon, a space,
+ a message describing the meaning of the contents of `errno' and a newline.
+ If S is NULL or "", the colon and space are omitted. */
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x
BOOT-GCC -x texis -x '*.info*' ../glibc-2.2.5/sysdeps/i386/fpu/ftestexcept.c
glibc-2.2.5/sysdeps/i386/fpu/ftestexcept.c
+--- ../glibc-2.2.5/sysdeps/i386/fpu/ftestexcept.c 2001-07-06
06:55:53.000000000 +0200
++++ glibc-2.2.5/sysdeps/i386/fpu/ftestexcept.c 2018-06-09 09:45:13.363031424
+0200
+@@ -25,8 +25,10 @@ fetestexcept (int excepts)
+ {
+ int temp;
+
++#if 0
+ /* Get current exceptions. */
+ __asm__ ("fnstsw %0" : "=a" (temp));
++#endif
+
+ return temp & excepts & FE_ALL_EXCEPT;
+ }
+diff -purN -x .git -x Makefile -x config.status -x config.h -x BOOT -x
BOOT-GCC -x texis -x '*.info*'
../glibc-2.2.5/sysdeps/unix/sysv/linux/sys/timex.h
glibc-2.2.5/sysdeps/unix/sysv/linux/sys/timex.h
+--- ../glibc-2.2.5/sysdeps/unix/sysv/linux/sys/timex.h 2001-07-06
06:56:21.000000000 +0200
++++ glibc-2.2.5/sysdeps/unix/sysv/linux/sys/timex.h 2018-06-09
20:09:07.713806647 +0200
+@@ -54,10 +54,12 @@ struct timex
+ long int errcnt; /* calibration errors (ro) */
+ long int stbcnt; /* stability limit exceeded (ro) */
+
++#if !MES_BOOTSTRAP
+ /* ??? */
+ int :32; int :32; int :32; int :32;
+ int :32; int :32; int :32; int :32;
+ int :32; int :32; int :32; int :32;
++#endif
+ };
+
+ /* Mode codes (timex.mode) */
+--- ../glibc-2.2.5/manual/Makefile 2001-08-28 10:05:40.000000000 +0200
++++ glibc-2.2.5/manual/Makefile 2018-06-09 10:13:03.093633660 +0200
+@@ -247,7 +247,11 @@
+ .PHONY: stubs
+ stubs: $(objpfx)stubs
+ endif
+-$(objpfx)stubs ../po/manual.pot $(objpfx)stamp%:
++po/manual.pot $(objpfx)stubs:
++ $(make-target-directory)
++ touch $@
++
++$(objpfx)stamp%:
+ $(make-target-directory)
+ touch $@
+
diff --git a/gnu/packages/patches/glibc-boot.patch
b/gnu/packages/patches/glibc-boot.patch
deleted file mode 100644
index e702fcd..0000000
--- a/gnu/packages/patches/glibc-boot.patch
+++ /dev/null
@@ -1,43015 +0,0 @@
-diff -purN -x BOOT ../glibc-2.0.1/assert/assert.c glibc-2.0.1/assert/assert.c
---- ../glibc-2.0.1/assert/assert.c 1996-12-02 16:40:23.000000000 +0100
-+++ glibc-2.0.1/assert/assert.c 2018-06-05 21:00:54.777209397 +0200
-@@ -21,6 +21,9 @@
- #include <stdlib.h>
- #include <sysdep.h>
-
-+#ifndef stderr
-+#define stderr 2
-+#endif
-
- const char *__assert_program_name;
-
-diff -purN -x BOOT ../glibc-2.0.1/csu/errno-loc.d glibc-2.0.1/csu/errno-loc.d
---- ../glibc-2.0.1/csu/errno-loc.d 1970-01-01 01:00:00.000000000 +0100
-+++ glibc-2.0.1/csu/errno-loc.d 2018-06-05 20:53:03.897575013 +0200
-@@ -0,0 +1 @@
-+errno-loc.o errno-loc.so errno-loc.po errno-loc.d:
../sysdeps/generic/errno-loc.c
-Binary files ../glibc-2.0.1/csu/errno-loc.o and glibc-2.0.1/csu/errno-loc.o
differ
-Binary files ../glibc-2.0.1/csu/errno-loc.po and glibc-2.0.1/csu/errno-loc.po
differ
-Binary files ../glibc-2.0.1/csu/errno-loc.so and glibc-2.0.1/csu/errno-loc.so
differ
-diff -purN -x BOOT ../glibc-2.0.1/ctype/ctype.c glibc-2.0.1/ctype/ctype.c
---- ../glibc-2.0.1/ctype/ctype.c 1992-10-07 23:22:36.000000000 +0100
-+++ glibc-2.0.1/ctype/ctype.c 2018-06-05 22:08:32.547406861 +0200
-@@ -21,8 +21,6 @@ Cambridge, MA 02139, USA. */
- #define __NO_CTYPE
- #include <ctype.h>
-
--/* Provide real-function versions of all the ctype macros. */
--
- #define func(name, type) \
- int DEFUN(name, (c), int c) { return __isctype(c, type); }
-
-diff -purN -x BOOT ../glibc-2.0.1/ctype/ctype.E glibc-2.0.1/ctype/ctype.E
---- ../glibc-2.0.1/ctype/ctype.E 1970-01-01 01:00:00.000000000 +0100
-+++ glibc-2.0.1/ctype/ctype.E 2018-06-05 21:55:56.987061510 +0200
-@@ -0,0 +1,222 @@
-+# 1 "ctype.c"
-+# 1 "../libc-symbols.h" 1
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+extern const char _libc_intl_domainname[];
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+# 119 "../libc-symbols.h"
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+# 184 "../libc-symbols.h"
-+
-+
-+
-+
-+
-+
-+# 210 "../libc-symbols.h"
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+# 248 "../libc-symbols.h"
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+# 320 "../libc-symbols.h"
-+
-+
-+
-+# 1 "ctype.c" 2
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+
-+int DEFUN( isalnum , (c), int c) { return __isctype(c, _ISalnum ); }
-+int DEFUN( isalpha , (c), int c) { return __isctype(c, _ISalpha ); }
-+int DEFUN( iscntrl , (c), int c) { return __isctype(c, _IScntrl ); }
-+int DEFUN( isdigit , (c), int c) { return __isctype(c, _ISdigit ); }
-+int DEFUN( islower , (c), int c) { return __isctype(c, _ISlower ); }
-+int DEFUN( isgraph , (c), int c) { return __isctype(c, _ISgraph ); }
-+int DEFUN( isprint , (c), int c) { return __isctype(c, _ISprint ); }
-+int DEFUN( ispunct , (c), int c) { return __isctype(c, _ISpunct ); }
-+int DEFUN( isspace , (c), int c) { return __isctype(c, _ISspace ); }
-+int DEFUN( isupper , (c), int c) { return __isctype(c, _ISupper ); }
-+int DEFUN( isxdigit , (c), int c) { return __isctype(c, _ISxdigit ); }
-+
-+int
-+DEFUN(tolower, (c), int c)
-+{
-+ return __tolower (c);
-+}
-+
-+int
-+DEFUN(toupper, (c), int c)
-+{
-+ return __toupper (c);
-+}
-diff -purN -x BOOT ../glibc-2.0.1/ctype/ctype.h glibc-2.0.1/ctype/ctype.h
---- ../glibc-2.0.1/ctype/ctype.h 1996-11-08 13:22:43.000000000 +0100
-+++ glibc-2.0.1/ctype/ctype.h 2018-06-05 22:05:26.852368283 +0200
-@@ -25,7 +25,7 @@
- #define _CTYPE_H 1
- #include <features.h>
-
--__BEGIN_DECLS
-+/*__BEGIN_DECLS*/
-
- #ifndef _ISbit
- /* These are all the characteristics of characters.
-diff -purN -x BOOT ../glibc-2.0.1/glibcbug glibc-2.0.1/glibcbug
---- ../glibc-2.0.1/glibcbug 1970-01-01 01:00:00.000000000 +0100
-+++ glibc-2.0.1/glibcbug 2018-06-05 22:08:58.423830274 +0200
-@@ -0,0 +1,244 @@
-+#! /bin/sh
-+#
-+# glibcbug - create a bug report and mail it to the bug address.
-+#
-+# configuration section:
-+# these variables are filled in by configure
-+#
-+VERSION="2.0.1"
-+BUGGLIBC="address@hidden"
-+ADDONS=""
-+
-+PATH=/bin:/usr/bin:/usr/local/bin:$PATH
-+export PATH
-+
-+TEMP=/tmp/glibcbug.$$
-+
-+BUGADDR=${1-$BUGGLIBC}
-+ENVIRONMENT=`uname -a`
-+
-+: ${EDITOR=emacs}
-+
-+: ${USER=${LOGNAME-`whoami`}}
-+
-+trap 'rm -f $TEMP $TEMP.x; exit 1' 1 2 3 13 15
-+trap 'rm -f $TEMP $TEMP.x' 0
-+
-+
-+# How to read the passwd database.
-+PASSWD="cat /etc/passwd"
-+
-+if [ -f /usr/lib/sendmail ] ; then
-+ MAIL_AGENT="/usr/lib/sendmail -oi -t"
-+elif [ -f /usr/sbin/sendmail ] ; then
-+ MAIL_AGENT="/usr/sbin/sendmail -oi -t"
-+else
-+ MAIL_AGENT=rmail
-+fi
-+
-+# Figure out how to echo a string without a trailing newline
-+N=`echo 'hi there\c'`
-+case "$N" in
-+*c) ECHON1='echo -n' ECHON2= ;;
-+*) ECHON1=echo ECHON2='\c' ;;
-+esac
-+
-+# Find out the name of the originator of this PR.
-+if [ -n "$NAME" ]; then
-+ ORIGINATOR="$NAME"
-+elif [ -f $HOME/.fullname ]; then
-+ ORIGINATOR="`sed -e '1q' $HOME/.fullname`"
-+else
-+ # Must use temp file due to incompatibilities in quoting behavior
-+ # and to protect shell metacharacters in the expansion of $LOGNAME
-+ $PASSWD | grep "^$LOGNAME:" | awk -F: '{print $5}' | sed -e 's/,.*//' >
$TEMP
-+ ORIGINATOR="`cat $TEMP`"
-+ rm -f $TEMP
-+fi
-+
-+if [ -n "$ORGANIZATION" ]; then
-+ if [ -f "$ORGANIZATION" ]; then
-+ ORGANIZATION="`cat $ORGANIZATION`"
-+ fi
-+else
-+ if [ -f $HOME/.organization ]; then
-+ ORGANIZATION="`cat $HOME/.organization`"
-+ elif [ -f $HOME/.signature ]; then
-+ ORGANIZATION=`sed -e "s/^/ /" $HOME/.signature; echo ">"`
-+ fi
-+fi
-+
-+# If they don't have a preferred editor set, then use
-+if [ -z "$VISUAL" ]; then
-+ if [ -z "$EDITOR" ]; then
-+ EDIT=vi
-+ else
-+ EDIT="$EDITOR"
-+ fi
-+else
-+ EDIT="$VISUAL"
-+fi
-+
-+# Find out some information.
-+SYSTEM=`( [ -f /bin/uname ] && /bin/uname -a ) || \
-+ ( [ -f /usr/bin/uname ] && /usr/bin/uname -a ) || echo ""`
-+ARCH=`[ -f /bin/arch ] && /bin/arch`
-+MACHINE=`[ -f /bin/machine ] && /bin/machine`
-+
-+ORGANIZATION_C='<organization of PR author (multiple lines)>'
-+SYNOPSIS_C='<synopsis of the problem (one line)>'
-+SEVERITY_C='<[ non-critical | serious | critical ] (one line)>'
-+PRIORITY_C='<[ low | medium | high ] (one line)>'
-+CLASS_C='<[ sw-bug | doc-bug | change-request | support ] (one line)>'
-+RELEASE_C='<release number or tag (one line)>'
-+ENVIRONMENT_C='<machine, os, target, libraries (multiple lines)>'
-+DESCRIPTION_C='<precise description of the problem (multiple lines)>'
-+HOW_TO_REPEAT_C='<code/input/activities to reproduce the problem (multiple
lines)>'
-+FIX_C='<how to correct or work around the problem, if known (multiple lines)>'
-+
-+
-+cat > $TEMP <<EOF
-+SEND-PR: -*- send-pr -*-
-+SEND-PR: Lines starting with \`SEND-PR' will be removed automatically, as
-+SEND-PR: will all comments (text enclosed in \`<' and \`>').
-+SEND-PR:
-+From: ${USER}
-+To: ${BUGADDR}
-+Subject: [50 character or so descriptive subject here (for reference)]
-+
-+>Submitter-Id: net
-+>Originator: ${ORIGINATOR}
-+>Organization:
-+${ORGANIZATION- $ORGANIZATION_C}
-+>Confidential: no
-+>Synopsis: $SYNOPSIS_C
-+>Severity: $SEVERITY_C
-+>Priority: $PRIORITY_C
-+>Category: libc
-+>Class: $CLASS_C
-+>Release: libc-${VERSION}
-+>Environment:
-+ $ENVIRONMENT_C
-+`[ -n "$SYSTEM" ] && echo System: $SYSTEM`
-+`[ -n "$ARCH" ] && echo Architecture: $ARCH`
-+`[ -n "$MACHINE" ] && echo Machine: $MACHINE`
-+`[ -n "$ADDONS" ] && echo Addons: $ADDONS`
-+
-+>Description:
-+ $DESCRIPTION_C
-+>How-To-Repeat:
-+ $HOW_TO_REPEAT_C
-+>Fix:
-+ $FIX_C
-+EOF
-+
-+chmod u+w $TEMP
-+cp $TEMP $TEMP.x
-+
-+eval $EDIT $TEMP
-+
-+if cmp -s $TEMP $TEMP.x; then
-+ echo "File not changed, no bug report submitted."
-+ exit 1
-+fi
-+
-+#
-+# Check the enumeration fields
-+
-+# This is a "sed-subroutine" with one keyword parameter
-+# (with workaround for Sun sed bug)
-+#
-+SED_CMD='
-+/$PATTERN/{
-+s|||
-+s|<.*>||
-+s|^[ ]*||
-+s|[ ]*$||
-+p
-+q
-+}'
-+
-+
-+while :; do
-+ CNT=0
-+
-+ #
-+ # 1) Severity
-+ #
-+ PATTERN=">Severity:"
-+ SEVERITY=`eval sed -n -e "\"$SED_CMD\"" $TEMP`
-+ case "$SEVERITY" in
-+ ""|non-critical|serious|critical) CNT=`expr $CNT + 1` ;;
-+ *) echo "$COMMAND: \`$SEVERITY' is not a valid value for \`Severity'."
-+ esac
-+ #
-+ # 2) Priority
-+ #
-+ PATTERN=">Priority:"
-+ PRIORITY=`eval sed -n -e "\"$SED_CMD\"" $TEMP`
-+ case "$PRIORITY" in
-+ ""|low|medium|high) CNT=`expr $CNT + 1` ;;
-+ *) echo "$COMMAND: \`$PRIORITY' is not a valid value for \`Priority'."
-+ esac
-+ #
-+ # 3) Class
-+ #
-+ PATTERN=">Class:"
-+ CLASS=`eval sed -n -e "\"$SED_CMD\"" $TEMP`
-+ case "$CLASS" in
-+ ""|sw-bug|doc-bug|change-request|support) CNT=`expr $CNT + 1` ;;
-+ *) echo "$COMMAND: \`$CLASS' is not a valid value for \`Class'."
-+ esac
-+
-+ [ $CNT -lt 3 ] &&
-+ echo "Errors were found with the problem report."
-+
-+ while :; do
-+ $ECHON1 "a)bort, e)dit or s)end? $ECHON2"
-+ read input
-+ case "$input" in
-+ a*)
-+ echo "$COMMAND: problem report saved in $HOME/dead.glibcbug."
-+ cat $TEMP >> $HOME/dead.glibcbug
-+ xs=1; exit
-+ ;;
-+ e*)
-+ eval $EDIT $TEMP
-+ continue 2
-+ ;;
-+ s*)
-+ break 2
-+ ;;
-+ esac
-+ done
-+done
-+#
-+# Remove comments and send the problem report
-+# (we have to use patterns, where the comment contains regex chars)
-+#
-+# /^>Originator:/s;$ORIGINATOR;;
-+sed -e "
-+/^SEND-PR:/d
-+/^>Organization:/,/^>[A-Za-z-]*:/s;$ORGANIZATION_C;;
-+/^>Confidential:/s;<.*>;;
-+/^>Synopsis:/s;$SYNOPSIS_C;;
-+/^>Severity:/s;<.*>;;
-+/^>Priority:/s;<.*>;;
-+/^>Class:/s;<.*>;;
-+/^>Release:/,/^>[A-Za-z-]*:/s;$RELEASE_C;;
-+/^>Environment:/,/^>[A-Za-z-]*:/s;$ENVIRONMENT_C;;
-+/^>Description:/,/^>[A-Za-z-]*:/s;$DESCRIPTION_C;;
-+/^>How-To-Repeat:/,/^>[A-Za-z-]*:/s;$HOW_TO_REPEAT_C;;
-+/^>Fix:/,/^>[A-Za-z-]*:/s;$FIX_C;;
-+" $TEMP > $TEMP.x
-+
-+if $MAIL_AGENT $BUGGLIBC < $TEMP.x; then
-+ echo "$COMMAND: problem report sent"
-+ xs=0; exit
-+else
-+ echo "$COMMAND: mysterious mail failure, report not sent."
-+ echo "$COMMAND: problem report saved in $HOME/dead.glibcbug."
-+ cat $TEMP >> $HOME/dead.glibcbug
-+fi
-+
-+exit 0
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info glibc-2.0.1/manual/libc.info
---- ../glibc-2.0.1/manual/libc.info 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info 1970-01-01 01:00:00.000000000 +0100
-@@ -1,596 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--Indirect:
--libc.info-1: 1168
--libc.info-2: 50130
--libc.info-3: 97453
--libc.info-4: 144446
--libc.info-5: 193430
--libc.info-6: 237807
--libc.info-7: 285360
--libc.info-8: 334723
--libc.info-9: 379684
--libc.info-10: 428359
--libc.info-11: 477650
--libc.info-12: 526627
--libc.info-13: 576207
--libc.info-14: 625641
--libc.info-15: 673159
--libc.info-16: 720930
--libc.info-17: 769559
--libc.info-18: 816715
--libc.info-19: 864190
--libc.info-20: 914097
--libc.info-21: 963959
--libc.info-22: 1011044
--libc.info-23: 1058556
--libc.info-24: 1108289
--libc.info-25: 1158030
--libc.info-26: 1207860
--libc.info-27: 1256153
--libc.info-28: 1305051
--libc.info-29: 1410972
--libc.info-30: 1453346
--libc.info-31: 1480210
--libc.info-32: 1530394
--libc.info-33: 1567426
--
--Tag Table:
--(Indirect)
--Node: Top1168
--Node: Introduction40477
--Node: Getting Started41825
--Node: Standards and Portability43285
--Node: ISO C44670
--Node: POSIX46187
--Node: Berkeley Unix47867
--Node: SVID48635
--Node: Using the Library49407
--Node: Header Files50130
--Node: Macro Definitions54082
--Node: Reserved Names56432
--Node: Feature Test Macros61114
--Node: Roadmap to the Manual66998
--Node: Error Reporting74211
--Node: Checking for Errors75139
--Node: Error Codes79354
--Node: Error Messages97453
--Node: Memory Allocation102288
--Node: Memory Concepts103291
--Node: Dynamic Allocation and C104561
--Node: Unconstrained Allocation106645
--Node: Basic Allocation107972
--Node: Malloc Examples109676
--Node: Freeing after Malloc111657
--Node: Changing Block Size113473
--Node: Allocating Cleared Space116037
--Node: Efficiency and Malloc116828
--Node: Aligned Memory Blocks118326
--Node: Heap Consistency Checking119694
--Node: Hooks for Malloc122487
--Node: Statistics of Malloc124736
--Node: Summary of Malloc126242
--Node: Obstacks128081
--Node: Creating Obstacks129699
--Node: Preparing for Obstacks131598
--Node: Allocation in an Obstack133938
--Node: Freeing Obstack Objects136633
--Node: Obstack Functions137969
--Node: Growing Objects140199
--Node: Extra Fast Growing144446
--Node: Status of an Obstack148065
--Node: Obstacks Data Alignment149484
--Node: Obstack Chunks151170
--Node: Summary of Obstacks153527
--Node: Variable Size Automatic156941
--Node: Alloca Example158497
--Node: Advantages of Alloca159614
--Node: Disadvantages of Alloca161506
--Node: GNU C Variable-Size Arrays162251
--Node: Relocating Allocator163409
--Node: Relocator Concepts163971
--Node: Using Relocator165484
--Node: Memory Warnings166869
--Node: Character Handling168181
--Node: Classification of Characters169130
--Node: Case Conversion172791
--Node: String and Array Utilities174639
--Node: Representation of Strings176450
--Node: String/Array Conventions179392
--Node: String Length181224
--Node: Copying and Concatenation182209
--Node: String/Array Comparison193430
--Node: Collation Functions198493
--Node: Search Functions205455
--Node: Finding Tokens in a String209726
--Node: I/O Overview215868
--Node: I/O Concepts217381
--Node: Streams and File Descriptors218526
--Node: File Position221617
--Node: File Names223751
--Node: Directories224637
--Node: File Name Resolution226374
--Node: File Name Errors229303
--Node: File Name Portability230852
--Node: I/O on Streams232844
--Node: Streams234800
--Node: Standard Streams236141
--Node: Opening Streams237807
--Node: Closing Streams243664
--Node: Simple Output246208
--Node: Character Input248544
--Node: Line Input251653
--Node: Unreading256641
--Node: Unreading Idea257450
--Node: How Unread258276
--Node: Block Input/Output260759
--Node: Formatted Output262988
--Node: Formatted Output Basics264755
--Node: Output Conversion Syntax267248
--Node: Table of Output Conversions270974
--Node: Integer Conversions273507
--Node: Floating-Point Conversions278171
--Node: Other Output Conversions282200
--Node: Formatted Output Functions285360
--Node: Dynamic Output289041
--Node: Variable Arguments Output290678
--Node: Parsing a Template String296190
--Node: Example of Parsing300017
--Node: Customizing Printf302305
--Node: Registering New Conversions304154
--Node: Conversion Specifier Options306145
--Node: Defining the Output Handler309818
--Node: Printf Extension Example312284
--Node: Formatted Input314592
--Node: Formatted Input Basics315671
--Node: Input Conversion Syntax318351
--Node: Table of Input Conversions321713
--Node: Numeric Input Conversions324010
--Node: String Input Conversions327788
--Node: Dynamic String Input331881
--Node: Other Input Conversions333071
--Node: Formatted Input Functions334723
--Node: Variable Arguments Input336289
--Node: EOF and Errors337924
--Node: Binary Streams340144
--Node: File Positioning342668
--Node: Portable Positioning346501
--Node: Stream Buffering349972
--Node: Buffering Concepts351557
--Node: Flushing Buffers352920
--Node: Controlling Buffering354416
--Node: Other Kinds of Streams358851
--Node: String Streams360113
--Node: Obstack Streams364233
--Node: Custom Streams366267
--Node: Streams and Cookies366920
--Node: Hook Functions369967
--Node: Low-Level I/O372353
--Node: Opening and Closing Files375005
--Node: I/O Primitives379684
--Node: File Position Primitive387937
--Node: Descriptors and Streams393372
--Node: Stream/Descriptor Precautions395792
--Node: Linked Channels396999
--Node: Independent Channels398227
--Node: Cleaning Streams400130
--Node: Waiting for I/O402333
--Node: Control Operations410084
--Node: Duplicating Descriptors412368
--Node: Descriptor Flags416630
--Node: File Status Flags420036
--Node: Access Modes421490
--Node: Open-time Flags423779
--Node: Operating Modes428359
--Node: Getting File Status Flags431125
--Node: File Locks433736
--Node: Interrupt Input442639
--Node: File System Interface445058
--Node: Working Directory446458
--Node: Accessing Directories450212
--Node: Directory Entries451418
--Node: Opening a Directory454218
--Node: Reading/Closing Directory455910
--Node: Simple Directory Lister458844
--Node: Random Access Directory459823
--Node: Hard Links461290
--Node: Symbolic Links464083
--Node: Deleting Files467849
--Node: Renaming Files470779
--Node: Creating Directories474406
--Node: File Attributes476154
--Node: Attribute Meanings477650
--Node: Reading Attributes482733
--Node: Testing File Type484635
--Node: File Owner487851
--Node: Permission Bits491544
--Node: Access Permission496651
--Node: Setting Permissions497801
--Node: Testing File Access503016
--Node: File Times506659
--Node: Making Special Files511167
--Node: Temporary Files512844
--Node: Pipes and FIFOs519051
--Node: Creating a Pipe520634
--Node: Pipe to a Subprocess523787
--Node: FIFO Special Files526627
--Node: Pipe Atomicity528200
--Node: Sockets529084
--Node: Socket Concepts530959
--Node: Communication Styles534173
--Node: Socket Addresses536025
--Node: Address Formats538066
--Node: Setting Address540749
--Node: Reading Address542453
--Node: File Namespace544211
--Node: File Namespace Concepts544701
--Node: File Namespace Details546296
--Node: File Socket Example547910
--Node: Internet Namespace549234
--Node: Internet Address Format550961
--Node: Host Addresses552330
--Node: Abstract Host Addresses553390
--Node: Host Address Data Type556183
--Node: Host Address Functions558074
--Node: Host Names560501
--Node: Ports565513
--Node: Services Database567551
--Node: Byte Order570378
--Node: Protocols Database572666
--Node: Inet Example576207
--Node: Misc Namespaces578237
--Node: Open/Close Sockets578987
--Node: Creating a Socket579485
--Node: Closing a Socket581153
--Node: Socket Pairs582683
--Node: Connections584693
--Node: Connecting585787
--Node: Listening588343
--Node: Accepting Connections590428
--Node: Who is Connected593284
--Node: Transferring Data594380
--Node: Sending Data595490
--Node: Receiving Data597738
--Node: Socket Data Options599202
--Node: Byte Stream Example600065
--Node: Server Example602043
--Node: Out-of-Band Data606090
--Node: Datagrams611944
--Node: Sending Datagrams612973
--Node: Receiving Datagrams614630
--Node: Datagram Example616431
--Node: Example Receiver618349
--Node: Inetd620916
--Node: Inetd Servers621724
--Node: Configuring Inetd622967
--Node: Socket Options625641
--Node: Socket Option Functions626349
--Node: Socket-Level Options627907
--Node: Networks Database631541
--Node: Low-Level Terminal Interface634403
--Node: Is It a Terminal635738
--Node: I/O Queues636954
--Node: Canonical or Not638924
--Node: Terminal Modes640771
--Node: Mode Data Types642047
--Node: Mode Functions643875
--Node: Setting Modes647815
--Node: Input Modes649803
--Node: Output Modes655070
--Node: Control Modes656683
--Node: Local Modes660773
--Node: Line Speed667087
--Node: Special Characters671247
--Node: Editing Characters673159
--Node: Signal Characters677500
--Node: Start/Stop Characters680369
--Node: Other Special682240
--Node: Noncanonical Input684054
--Node: Line Control688867
--Node: Noncanon Example693179
--Node: Mathematics695374
--Node: Domain and Range Errors696578
--Node: Trig Functions699801
--Node: Inverse Trig Functions701171
--Node: Exponents and Logarithms703609
--Node: Hyperbolic Functions706510
--Node: Pseudo-Random Numbers708089
--Node: ISO Random709675
--Node: BSD Random710848
--Node: Arithmetic712765
--Node: Not a Number713674
--Node: Predicates on Floats715016
--Node: Absolute Value716590
--Node: Normalization Functions718088
--Node: Rounding and Remainders720930
--Node: Integer Division724298
--Node: Parsing of Numbers726448
--Node: Parsing of Integers727100
--Node: Parsing of Floats734575
--Node: Searching and Sorting739039
--Node: Comparison Functions739830
--Node: Array Search Function740944
--Node: Array Sort Function742367
--Node: Search/Sort Example744339
--Node: Pattern Matching747789
--Node: Wildcard Matching748591
--Node: Globbing751469
--Node: Calling Glob752259
--Node: Flags for Globbing755840
--Node: Regular Expressions759338
--Node: POSIX Regexp Compilation760322
--Node: Flags for POSIX Regexps764437
--Node: Matching POSIX Regexps765344
--Node: Regexp Subexpressions767505
--Node: Subexpression Complications769559
--Node: Regexp Cleanup771918
--Node: Word Expansion774244
--Node: Expansion Stages775412
--Node: Calling Wordexp776905
--Node: Flags for Wordexp780868
--Node: Wordexp Example782821
--Node: Date and Time784796
--Node: Processor Time785920
--Node: Basic CPU Time786678
--Node: Detailed CPU Time788697
--Node: Calendar Time791162
--Node: Simple Calendar Time792740
--Node: High-Resolution Calendar794497
--Node: Broken-down Time800217
--Node: Formatting Date and Time805433
--Node: TZ Variable816715
--Node: Time Zone Functions822776
--Node: Time Functions Example825441
--Node: Setting an Alarm826556
--Node: Sleeping831783
--Node: Resource Usage834439
--Node: Limits on Resources837950
--Node: Priority842324
--Node: Extended Characters845586
--Node: Extended Char Intro847194
--Node: Locales and Extended Chars849131
--Node: Multibyte Char Intro850181
--Node: Wide Char Intro857475
--Node: Wide String Conversion859242
--Node: Length of Char862479
--Node: Converting One Char864190
--Node: Example of Conversion867587
--Node: Shift State870477
--Node: Locales873130
--Node: Effects of Locale874698
--Node: Choosing Locale876634
--Node: Locale Categories877958
--Node: Setting the Locale879605
--Node: Standard Locales883499
--Node: Numeric Formatting884739
--Node: General Numeric886249
--Node: Currency Symbol889171
--Node: Sign of Money Amount893781
--Node: Non-Local Exits896085
--Node: Non-Local Intro896704
--Node: Non-Local Details900431
--Node: Non-Local Exits and Signals903507
--Node: Signal Handling904977
--Node: Concepts of Signals907012
--Node: Kinds of Signals907576
--Node: Signal Generation908973
--Node: Delivery of Signal911240
--Node: Standard Signals914097
--Node: Program Error Signals915690
--Node: Termination Signals923148
--Node: Alarm Signals926986
--Node: Asynchronous I/O Signals928226
--Node: Job Control Signals929417
--Node: Operation Error Signals934029
--Node: Miscellaneous Signals935968
--Node: Signal Messages937664
--Node: Signal Actions939550
--Node: Basic Signal Handling940495
--Node: Advanced Signal Handling945428
--Node: Signal and Sigaction948384
--Node: Sigaction Function Example950136
--Node: Flags for Sigaction952452
--Node: Initial Signal Actions954830
--Node: Defining Handlers956213
--Node: Handler Returns958398
--Node: Termination in Handler960448
--Node: Longjmp in Handler961864
--Node: Signals in Handler963959
--Node: Merged Signals966079
--Node: Nonreentrancy971789
--Node: Atomic Data Access977337
--Node: Non-atomic Example978373
--Node: Atomic Types980144
--Node: Atomic Usage981152
--Node: Interrupted Primitives982622
--Node: Generating Signals985922
--Node: Signaling Yourself986515
--Node: Signaling Another Process988497
--Node: Permission for kill991880
--Node: Kill Example993676
--Node: Blocking Signals996020
--Node: Why Block997792
--Node: Signal Sets999329
--Node: Process Signal Mask1002355
--Node: Testing for Delivery1005363
--Node: Blocking for Handler1006613
--Node: Checking for Pending Signals1009032
--Node: Remembering a Signal1011044
--Node: Waiting for a Signal1014593
--Node: Using Pause1015138
--Node: Pause Problems1016358
--Node: Sigsuspend1018082
--Node: Signal Stack1020792
--Node: BSD Signal Handling1026136
--Node: BSD Handler1027410
--Node: Blocking in BSD1029844
--Node: Process Startup1031298
--Node: Program Arguments1032333
--Node: Argument Syntax1035062
--Node: Parsing Options1037692
--Node: Example of Getopt1040983
--Node: Long Options1043699
--Node: Long Option Example1047760
--Node: Suboptions1050609
--Node: Suboptions Example1052558
--Node: Environment Variables1054653
--Node: Environment Access1056514
--Node: Standard Environment1058556
--Node: Program Termination1062239
--Node: Normal Termination1063458
--Node: Exit Status1064684
--Node: Cleanups on Exit1067703
--Node: Aborting a Program1069520
--Node: Termination Internals1070419
--Node: Processes1072195
--Node: Running a Command1074218
--Node: Process Creation Concepts1075711
--Node: Process Identification1077721
--Node: Creating a Process1078645
--Node: Executing a File1082261
--Node: Process Completion1089296
--Node: Process Completion Status1094305
--Node: BSD Wait Functions1095949
--Node: Process Creation Example1097841
--Node: Job Control1100091
--Node: Concepts of Job Control1101371
--Node: Job Control is Optional1104728
--Node: Controlling Terminal1105778
--Node: Access to the Terminal1106685
--Node: Orphaned Process Groups1108289
--Node: Implementing a Shell1109281
--Node: Data Structures1110164
--Node: Initializing the Shell1112807
--Node: Launching Jobs1116543
--Node: Foreground and Background1123996
--Node: Stopped and Terminated Jobs1127105
--Node: Continuing Stopped Jobs1132287
--Node: Missing Pieces1133914
--Node: Functions for Job Control1135538
--Node: Identifying the Terminal1136018
--Node: Process Group Functions1137592
--Node: Terminal Access Functions1141144
--Node: Name Service Switch1144045
--Node: NSS Basics1145379
--Node: NSS Configuration File1146956
--Node: Services in the NSS configuration1148654
--Node: Actions in the NSS configuration1149935
--Node: Notes on NSS Configuration File1153094
--Node: NSS Module Internals1154970
--Node: NSS Module Names1155666
--Node: NSS Modules Interface1158030
--Node: Extending NSS1161514
--Node: Adding another Service to NSS1162445
--Node: NSS Module Function Internals1164664
--Node: Users and Groups1169065
--Node: User and Group IDs1171541
--Node: Process Persona1172448
--Node: Why Change Persona1173959
--Node: How Change Persona1175840
--Node: Reading Persona1177322
--Node: Setting User ID1179592
--Node: Setting Groups1181802
--Node: Enable/Disable Setuid1184359
--Node: Setuid Program Example1186398
--Node: Tips for Setuid1189867
--Node: Who Logged In1191955
--Node: User Database1194123
--Node: User Data Structure1194784
--Node: Lookup User1196063
--Node: Scanning All Users1199153
--Node: Writing a User Entry1202532
--Node: Group Database1203431
--Node: Group Data Structure1204018
--Node: Lookup Group1204804
--Node: Scanning All Groups1207860
--Node: Netgroup Database1211141
--Node: Netgroup Data1211575
--Node: Lookup Netgroup1213139
--Node: Netgroup Membership1216551
--Node: Database Example1217881
--Node: System Information1220055
--Node: Host Identification1220652
--Node: Hardware/Software Type ID1223871
--Node: System Configuration1226570
--Node: General Limits1228137
--Node: System Options1231776
--Node: Version Supported1235108
--Node: Sysconf1236945
--Node: Sysconf Definition1237581
--Node: Constants for Sysconf1238253
--Node: Examples of Sysconf1241386
--Node: Minimums1242379
--Node: Limits for Files1244455
--Node: Options for Files1247457
--Node: File Minimums1249746
--Node: Pathconf1251408
--Node: Utility Limits1254095
--Node: Utility Minimums1256153
--Node: String Parameters1257905
--Node: Language Features1259959
--Node: Consistency Checking1260890
--Node: Variadic Functions1265528
--Node: Why Variadic1266600
--Node: How Variadic1268565
--Node: Variadic Prototypes1269854
--Node: Receiving Arguments1271012
--Node: How Many Arguments1273726
--Node: Calling Variadics1275397
--Node: Argument Macros1277534
--Node: Variadic Example1279174
--Node: Old Varargs1280326
--Node: Null Pointer Constant1281996
--Node: Important Data Types1283081
--Node: Data Type Measurements1285647
--Node: Width of Type1286504
--Node: Range of Type1287410
--Node: Floating Type Macros1290674
--Node: Floating Point Concepts1291934
--Node: Floating Point Parameters1295669
--Node: IEEE Floating Point1302603
--Node: Structure Measurement1304356
--Node: Library Summary1305051
--Node: Maintenance1410972
--Node: Installation1411717
--Node: Tools for Installation1418563
--Node: Supported Configurations1419651
--Node: Reporting Bugs1421162
--Node: Source Layout1423539
--Node: Porting1427495
--Node: Hierarchy Conventions1435283
--Node: Porting to Unix1440203
--Node: Contributors1442048
--Node: Copying1453346
--Node: Concept Index1480210
--Node: Type Index1530394
--Node: Function Index1535184
--Node: Variable Index1567426
--Node: File Index1598743
--
--End Tag Table
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-1
glibc-2.0.1/manual/libc.info-1
---- ../glibc-2.0.1/manual/libc.info-1 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-1 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1089 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
--
--Main Menu
--*********
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta of the GNU C Library.
--
--* Menu:
--
--* Introduction:: Purpose of the GNU C Library.
--* Error Reporting:: How the GNU Library functions report
-- error conditions.
--* Memory Allocation:: Your program can allocate memory dynamically
-- and manipulate it via pointers.
--* Character Handling:: Character testing and conversion functions.
--* String and Array Utilities:: Utilities for copying and comparing
-- strings and arrays.
--* Extended Characters:: Support for extended character sets.
--* Locales:: The country and language can affect
-- the behavior of library functions.
--* Searching and Sorting:: General searching and sorting functions.
--* Pattern Matching:: Matching wildcards and regular expressions,
-- and shell-style "word expansion".
--* I/O Overview:: Introduction to the I/O facilities.
--* Streams: I/O on Streams. High-level, portable I/O facilities.
--* Low-Level I/O:: Low-level, less portable I/O.
--* File System Interface:: Functions for manipulating files.
--* Pipes and FIFOs:: A simple interprocess communication mechanism.
--* Sockets:: A more complicated interprocess communication
-- mechanism, with support for networking.
--* Low-Level Terminal Interface::How to change the characteristics
-- of a terminal device.
--* Mathematics:: Math functions (transcendental functions,
-- random numbers, absolute value, etc.).
--* Arithmetic:: Low-level arithmetic functions.
--* Date and Time:: Functions for getting the date and time,
-- and for conversion between formats.
--* Non-Local Exits:: The `setjmp' and `longjmp' facilities.
--* Signal Handling:: All about signals; how to send them,
-- block them, and handle them.
--* Process Startup:: Writing the beginning and end of your program.
--* Processes:: How to create processes and run other
programs.
--* Job Control:: All about process groups and sessions.
--* Name Service Switch:: Accessing the various system databases.
--* Users and Groups:: How users are identified and classified.
--* System Information:: Getting information about the
-- hardware and software configuration
-- of the machine a program runs on.
--* System Configuration:: Parameters describing operating system limits.
--
--Appendices
--
--* Language Features:: C language features provided by the library.
--
--* Library Summary:: A summary showing the syntax, header file,
-- and derivation of each library feature.
--* Maintenance:: How to install and maintain the GNU C Library.
--* Copying:: The GNU Library General Public License says
-- how you can copy and share the GNU C Library.
--
--Indices
--
--* Concept Index:: Index of concepts and names.
--* Type Index:: Index of types and type qualifiers.
--* Function Index:: Index of functions and function-like macros.
--* Variable Index:: Index of variables and variable-like macros.
--* File Index:: Index of programs and files.
--
-- -- The Detailed Node Listing --
--
--Introduction
--
--* Getting Started:: Getting Started
--* Standards and Portability:: Standards and Portability
--* Using the Library:: Using the Library
--* Roadmap to the Manual:: Roadmap to the Manual
--
--Standards and Portability
--
--* ISO C:: The American National Standard for the
-- C programming language.
--* POSIX:: The ISO/IEC 9945 (aka IEEE 1003) standards
-- for operating systems.
--* Berkeley Unix:: BSD and SunOS.
--* SVID:: The System V Interface Description.
--
--Using the Library
--
--* Header Files:: How to use the header files in your programs.
--* Macro Definitions:: Some functions in the library may really
-- be implemented as macros.
--* Reserved Names:: The C standard reserves some names for
-- the library, and some for users.
--* Feature Test Macros:: How to control what names are defined.
--
--Error Reporting
--
--* Checking for Errors:: How errors are reported by library functions.
--* Error Codes:: What all the error codes are.
--* Error Messages:: Mapping error codes onto error messages.
--
--Memory Allocation
--
--* Memory Concepts:: An introduction to concepts and terminology.
--* Dynamic Allocation and C:: How to get different kinds of allocation in C.
--* Unconstrained Allocation:: The `malloc' facility allows fully general
-- dynamic allocation.
--* Obstacks:: Obstacks are less general than malloc
-- but more efficient and convenient.
--* Variable Size Automatic:: Allocation of variable-sized blocks
-- of automatic storage that are freed when the
-- calling function returns.
--* Relocating Allocator:: Waste less memory, if you can tolerate
-- automatic relocation of the blocks you get.
--* Memory Warnings:: Getting warnings when memory is nearly full.
--
--Unconstrained Allocation
--
--* Basic Allocation:: Simple use of `malloc'.
--* Malloc Examples:: Examples of `malloc'. `xmalloc'.
--* Freeing after Malloc:: Use `free' to free a block you
-- got with `malloc'.
--* Changing Block Size:: Use `realloc' to make a block
-- bigger or smaller.
--* Allocating Cleared Space:: Use `calloc' to allocate a
-- block and clear it.
--* Efficiency and Malloc:: Efficiency considerations in use of
-- these functions.
--* Aligned Memory Blocks:: Allocating specially aligned memory:
-- `memalign' and `valloc'.
--* Heap Consistency Checking:: Automatic checking for errors.
--* Hooks for Malloc:: You can use these hooks for debugging
-- programs that use `malloc'.
--* Statistics of Malloc:: Getting information about how much
-- memory your program is using.
--* Summary of Malloc:: Summary of `malloc' and related functions.
--
--Obstacks
--
--* Creating Obstacks:: How to declare an obstack in your program.
--* Preparing for Obstacks:: Preparations needed before you can
-- use obstacks.
--* Allocation in an Obstack:: Allocating objects in an obstack.
--* Freeing Obstack Objects:: Freeing objects in an obstack.
--* Obstack Functions:: The obstack functions are both
-- functions and macros.
--* Growing Objects:: Making an object bigger by stages.
--* Extra Fast Growing:: Extra-high-efficiency (though more
-- complicated) growing objects.
--* Status of an Obstack:: Inquiries about the status of an obstack.
--* Obstacks Data Alignment:: Controlling alignment of objects in obstacks.
--* Obstack Chunks:: How obstacks obtain and release chunks.
-- Efficiency considerations.
--* Summary of Obstacks::
--
--Automatic Storage with Variable Size
--
--* Alloca Example:: Example of using `alloca'.
--* Advantages of Alloca:: Reasons to use `alloca'.
--* Disadvantages of Alloca:: Reasons to avoid `alloca'.
--* GNU C Variable-Size Arrays:: Only in GNU C, here is an alternative
-- method of allocating dynamically and
-- freeing automatically.
--Relocating Allocator
--
--* Relocator Concepts:: How to understand relocating allocation.
--* Using Relocator:: Functions for relocating allocation.
--
--Character Handling
--
--* Classification of Characters::Testing whether characters are
-- letters, digits, punctuation, etc.
--* Case Conversion:: Case mapping, and the like.
--
--String and Array Utilities
--
--* Representation of Strings:: Introduction to basic concepts.
--* String/Array Conventions:: Whether to use a string function or an
-- arbitrary array function.
--* String Length:: Determining the length of a string.
--* Copying and Concatenation:: Functions to copy the contents of strings
-- and arrays.
--* String/Array Comparison:: Functions for byte-wise and character-wise
-- comparison.
--* Collation Functions:: Functions for collating strings.
--* Search Functions:: Searching for a specific element or substring.
--* Finding Tokens in a String:: Splitting a string into tokens by looking
-- for delimiters.
--
--Extended Characters
--
--* Extended Char Intro:: Multibyte codes versus wide characters.
--* Locales and Extended Chars:: The locale selects the character codes.
--* Multibyte Char Intro:: How multibyte codes are represented.
--* Wide Char Intro:: How wide characters are represented.
--* Wide String Conversion:: Converting wide strings to multibyte code
-- and vice versa.
--* Length of Char:: how many bytes make up one multibyte char.
--* Converting One Char:: Converting a string character by character.
--* Example of Conversion:: Example showing why converting
-- one character at a time may be useful.
--* Shift State:: Multibyte codes with "shift characters".
--
--Locales and Internationalization
--
--* Effects of Locale:: Actions affected by the choice of locale.
--* Choosing Locale:: How the user specifies a locale.
--* Locale Categories:: Different purposes for which
-- you can select a locale.
--* Setting the Locale:: How a program specifies the locale.
--* Standard Locales:: Locale names available on all systems.
--* Numeric Formatting:: How to format numbers for the chosen locale.
--
--Searching and Sorting
--
--* Comparison Functions:: Defining how to compare two objects.
-- Since the sort and search facilities are
-- general, you have to specify the ordering.
--* Array Search Function:: The `bsearch' function.
--* Array Sort Function:: The `qsort' function.
--* Search/Sort Example:: An example program.
--
--Pattern Matching
--
--* Wildcard Matching:: Matching a wildcard pattern against a single string.
--* Globbing:: Finding the files that match a wildcard pattern.
--* Regular Expressions:: Matching regular expressions against strings.
--* Word Expansion:: Expanding shell variables, nested commands,
-- arithmetic, and wildcards.
-- This is what the shell does with shell commands.
--
--I/O Overview
--
--* I/O Concepts:: Some basic information and terminology.
--* File Names:: How to refer to a file.
--
--I/O Concepts
--
--* Streams and File Descriptors:: The GNU Library provides two ways
-- to access the contents of files.
--* File Position:: The number of bytes from the
-- beginning of the file.
--
--File Names
--
--* Directories:: Directories contain entries for files.
--* File Name Resolution:: A file name specifies how to look up a file.
--* File Name Errors:: Error conditions relating to file names.
--* File Name Portability:: File name portability and syntax issues.
--
--I/O on Streams
--
--* Streams:: About the data type representing a stream.
--* Standard Streams:: Streams to the standard input and output
-- devices are created for you.
--* Opening Streams:: How to create a stream to talk to a file.
--* Closing Streams:: Close a stream when you are finished with it.
--* Simple Output:: Unformatted output by characters and lines.
--* Character Input:: Unformatted input by characters and words.
--* Line Input:: Reading a line or a record from a stream.
--* Unreading:: Peeking ahead/pushing back input just read.
--* Formatted Output:: `printf' and related functions.
--* Customizing Printf:: You can define new conversion specifiers for
-- `printf' and friends.
--* Formatted Input:: `scanf' and related functions.
--* Block Input/Output:: Input and output operations on blocks of data.
--* EOF and Errors:: How you can tell if an I/O error happens.
--* Binary Streams:: Some systems distinguish between text files
-- and binary files.
--* File Positioning:: About random-access streams.
--* Portable Positioning:: Random access on peculiar ISO C systems.
--* Stream Buffering:: How to control buffering of streams.
--* Temporary Files:: How to open a temporary file.
--* Other Kinds of Streams:: Other Kinds of Streams
--
--Unreading
--
--* Unreading Idea:: An explanation of unreading with pictures.
--* How Unread:: How to call `ungetc' to do unreading.
--
--Formatted Output
--
--* Formatted Output Basics:: Some examples to get you started.
--* Output Conversion Syntax:: General syntax of conversion specifications.
--* Table of Output Conversions:: Summary of output conversions, what they do.
--* Integer Conversions:: Details of formatting integers.
--* Floating-Point Conversions:: Details of formatting floating-point numbers.
--* Other Output Conversions:: Details about formatting of strings,
-- characters, pointers, and the like.
--* Formatted Output Functions:: Descriptions of the actual functions.
--* Variable Arguments Output:: `vprintf' and friends.
--* Parsing a Template String:: What kinds of arguments does
-- a given template call for?
--
--Customizing Printf
--
--* Registering New Conversions::
--* Conversion Specifier Options::
--* Defining the Output Handler::
--* Printf Extension Example::
--
--Formatted Input
--
--* Formatted Input Basics:: Some basics to get you started.
--* Input Conversion Syntax:: Syntax of conversion specifications.
--* Table of Input Conversions:: Summary of input conversions and what they do.
--* Numeric Input Conversions:: Details of conversions for reading numbers.
--* String Input Conversions:: Details of conversions for reading strings.
--* Other Input Conversions:: Details of miscellaneous other conversions.
--* Formatted Input Functions:: Descriptions of the actual functions.
--* Variable Arguments Input:: `vscanf' and friends.
--
--Stream Buffering
--
--* Buffering Concepts:: Terminology is defined here.
--* Flushing Buffers:: How to ensure that output buffers are flushed.
--* Controlling Buffering:: How to specify what kind of buffering to use.
--
--Other Kinds of Streams
--
--* String Streams::
--* Custom Streams::
--
--Programming Your Own Custom Streams
--
--* Streams and Cookies::
--* Hook Functions::
--
--Low-Level I/O
--
--* Opening and Closing Files:: How to open and close file descriptors.
--* I/O Primitives:: Reading and writing data.
--* File Position Primitive:: Setting a descriptor's file position.
--* Descriptors and Streams:: Converting descriptor to stream or vice-versa.
--* Stream/Descriptor Precautions:: Precautions needed if you use both
-- descriptors and streams.
--* Waiting for I/O:: How to check for input or output
-- on multiple file descriptors.
--* Control Operations:: Various other operations on file descriptors.
--* Duplicating Descriptors:: Fcntl commands for duplicating descriptors.
--* Descriptor Flags:: Fcntl commands for manipulating flags
-- associated with file descriptors.
--* File Status Flags:: Fcntl commands for manipulating flags
-- associated with open files.
--* File Locks:: Fcntl commands for implementing file locking.
--* Interrupt Input:: Getting a signal when input arrives.
--
--File System Interface
--
--* Working Directory:: This is used to resolve relative file names.
--* Accessing Directories:: Finding out what files a directory contains.
--* Hard Links:: Adding alternate names to a file.
--* Symbolic Links:: A file that "points to" a file name.
--* Deleting Files:: How to delete a file, and what that means.
--* Renaming Files:: Changing a file's name.
--* Creating Directories:: A system call just for creating a directory.
--* File Attributes:: Attributes of individual files.
--* Making Special Files:: How to create special files.
--
--Accessing Directories
--
--* Directory Entries:: Format of one directory entry.
--* Opening a Directory:: How to open a directory stream.
--* Reading/Closing Directory:: How to read directory entries from the stream.
--* Simple Directory Lister:: A very simple directory listing program.
--* Random Access Directory:: Rereading part of the directory
-- already read with the same stream.
--
--File Attributes
--
--* Attribute Meanings:: The names of the file attributes,
-- and what their values mean.
--* Reading Attributes:: How to read the attributes of a file.
--* Testing File Type:: Distinguishing ordinary files,
-- directories, links...
--* File Owner:: How ownership for new files is determined,
-- and how to change it.
--* Permission Bits:: How information about a file's access mode
-- is stored.
--* Access Permission:: How the system decides who can access a file.
--* Setting Permissions:: How permissions for new files are assigned,
-- and how to change them.
--* Testing File Access:: How to find out if your process can
-- access a file.
--* File Times:: About the time attributes of a file.
--
--Pipes and FIFOs
--
--* Creating a Pipe:: Making a pipe with the `pipe' function.
--* Pipe to a Subprocess:: Using a pipe to communicate with a child.
--* FIFO Special Files:: Making a FIFO special file.
--
--Sockets
--
--* Socket Concepts:: Basic concepts you need to know about.
--* Communication Styles:: Stream communication, datagrams, and others.
--* Socket Addresses:: How socket names ("addresses") work.
--* File Namespace:: Details about the file namespace.
--* Internet Namespace:: Details about the Internet namespace.
--* Open/Close Sockets:: Creating sockets and destroying them.
--* Connections:: Operations on sockets with connection state.
--* Datagrams:: Operations on datagram sockets.
--* Socket Options:: Miscellaneous low-level socket options.
--* Networks Database:: Accessing the database of network names.
--
--Socket Addresses
--
--* Address Formats:: About `struct sockaddr'.
--* Setting Address:: Binding an address to a socket.
--* Reading Address:: Reading the address of a socket.
--
--Internet Domain
--
--* Internet Address Format:: How socket addresses are specified in the
-- Internet namespace.
--* Host Addresses:: All about host addresses of Internet hosts.
--* Protocols Database:: Referring to protocols by name.
--* Services Database:: Ports may have symbolic names.
--* Byte Order:: Different hosts may use different byte
-- ordering conventions; you need to
-- canonicalize host address and port number.
--* Inet Example:: Putting it all together.
--
--Host Addresses
--
--* Abstract Host Addresses:: What a host number consists of.
--* Data type: Host Address Data Type. Data type for a host number.
--* Functions: Host Address Functions. Functions to operate on them.
--* Names: Host Names. Translating host names to host
numbers.
--
--Open/Close Sockets
--
--* Creating a Socket:: How to open a socket.
--* Closing a Socket:: How to close a socket.
--* Socket Pairs:: These are created like pipes.
--
--Connections
--
--* Connecting:: What the client program must do.
--* Listening:: How a server program waits for requests.
--* Accepting Connections:: What the server does when it gets a request.
--* Who is Connected:: Getting the address of the
-- other side of a connection.
--* Transferring Data:: How to send and receive data.
--* Byte Stream Example:: An example client for communicating over a
-- byte stream socket in the Internet namespace.
--* Server Example:: A corresponding server program.
--* Out-of-Band Data:: This is an advanced feature.
--
--Transferring Data
--
--* Sending Data:: Sending data with `write'.
--* Receiving Data:: Reading data with `read'.
--* Socket Data Options:: Using `send' and `recv'.
--
--Datagrams
--
--* Sending Datagrams:: Sending packets on a datagram socket.
--* Receiving Datagrams:: Receiving packets on a datagram socket.
--* Datagram Example:: An example program: packets sent over a
-- datagram stream in the file namespace.
--* Example Receiver:: Another program, that receives those packets.
--
--Socket Options
--
--* Socket Option Functions:: The basic functions for setting and getting
-- socket options.
--* Socket-Level Options:: Details of the options at the socket level.
--
--Low-Level Terminal Interface
--
--* Is It a Terminal:: How to determine if a file is a terminal
-- device, and what its name is.
--* I/O Queues:: About flow control and typeahead.
--* Canonical or Not:: Two basic styles of input processing.
--* Terminal Modes:: How to examine and modify flags controlling
-- terminal I/O: echoing, signals, editing.
--* Line Control:: Sending break sequences, clearing buffers...
--* Noncanon Example:: How to read single characters without echo.
--
--Terminal Modes
--
--* Mode Data Types:: The data type `struct termios' and related
types.
--* Mode Functions:: Functions to read and set terminal attributes.
--* Setting Modes:: The right way to set attributes reliably.
--* Input Modes:: Flags controlling low-level input handling.
--* Output Modes:: Flags controlling low-level output handling.
--* Control Modes:: Flags controlling serial port behavior.
--* Local Modes:: Flags controlling high-level input handling.
--* Line Speed:: How to read and set the terminal line speed.
--* Special Characters:: Characters that have special effects,
-- and how to change them.
--* Noncanonical Input:: Controlling how long to wait for input.
--
--Special Characters
--
--* Editing Characters::
--* Signal Characters::
--* Start/Stop Characters::
--
--Mathematics
--
--* Domain and Range Errors:: How overflow conditions and the
-- like are reported.
--* Not a Number:: Making NANs and testing for NANs.
--* Trig Functions:: Sine, cosine, and tangent.
--* Inverse Trig Functions:: Arc sine, arc cosine, and arc tangent.
--* Exponents and Logarithms:: Also includes square root.
--* Hyperbolic Functions:: Hyperbolic sine and friends.
--* Pseudo-Random Numbers:: Functions for generating pseudo-random
numbers.
--* Absolute Value:: Absolute value functions.
--
--Pseudo-Random Numbers
--
--* ISO Random:: `rand' and friends.
--* BSD Random:: `random' and friends.
--
--Low-Level Arithmetic Functions
--
--* Normalization Functions:: Hacks for radix-2 representations.
--* Rounding and Remainders:: Determining the integer and
-- fractional parts of a float.
--* Integer Division:: Functions for performing integer division.
--* Parsing of Numbers:: Functions for "reading" numbers from strings.
--* Predicates on Floats:: Some miscellaneous test functions.
--
--Parsing of Numbers
--
--* Parsing of Integers:: Functions for conversion of integer values.
--* Parsing of Floats:: Functions for conversion of floating-point.
--
--Date and Time
--
--* Processor Time:: Measures processor time used by a program.
--* Calendar Time:: Manipulation of "real" dates and times.
--* Setting an Alarm:: Sending a signal after a specified time.
--* Sleeping:: Waiting for a period of time.
--
--Processor Time
--
--* Basic CPU Time:: The `clock' function.
--* Detailed CPU Time:: The `times' function.
--
--Calendar Time
--
--* Simple Calendar Time:: Facilities for manipulating calendar time.
--* High-Resolution Calendar:: A time representation with greater precision.
--* Broken-down Time:: Facilities for manipulating local time.
--* Formatting Date and Time:: Converting times to strings.
--* TZ Variable:: How users specify the time zone.
--* Time Zone Functions:: Functions to examine or specify the time zone.
--* Time Functions Example:: An example program showing use of some of
-- the time functions.
--
--Signal Handling
--
--* Concepts of Signals:: Introduction to the signal facilities.
--* Standard Signals:: Particular kinds of signals with standard
-- names and meanings.
--* Signal Actions:: Specifying what happens when a particular
-- signal is delivered.
--* Defining Handlers:: How to write a signal handler function.
--* Generating Signals:: How to send a signal to a process.
--* Blocking Signals:: Making the system hold signals temporarily.
--* Waiting for a Signal:: Suspending your program until a signal
arrives.
--* Signal Stack:: Using a Separate Signal Stack
--* BSD Signal Handling:: Additional functions for backward
-- compatibility with BSD.
--
--Basic Concepts of Signals
--
--* Kinds of Signals:: Some examples of what can cause a signal.
--* Signal Generation:: Concepts of why and how signals occur.
--* Delivery of Signal:: Concepts of what a signal does to the process.
--
--Standard Signals
--
--* Program Error Signals:: Used to report serious program errors.
--* Termination Signals:: Used to interrupt and/or terminate the
program.
--* Alarm Signals:: Used to indicate expiration of timers.
--* Asynchronous I/O Signals:: Used to indicate input is available.
--* Job Control Signals:: Signals used to support job control.
--* Operation Error Signals:: Used to report operational system errors.
--* Miscellaneous Signals:: Miscellaneous Signals.
--* Signal Messages:: Printing a message describing a signal.
--
--Specifying Signal Actions
--
--* Basic Signal Handling:: The simple `signal' function.
--* Advanced Signal Handling:: The more powerful `sigaction' function.
--* Signal and Sigaction:: How those two functions interact.
--* Sigaction Function Example:: An example of using the sigaction function.
--* Flags for Sigaction:: Specifying options for signal handling.
--* Initial Signal Actions:: How programs inherit signal actions.
--
--Defining Signal Handlers
--
--* Handler Returns::
--* Termination in Handler::
--* Longjmp in Handler::
--* Signals in Handler::
--* Nonreentrancy::
--* Atomic Data Access::
--
--Generating Signals
--
--* Signaling Yourself:: Signaling Yourself
--* Signaling Another Process:: Send a signal to another process.
--* Permission for kill:: Permission for using `kill'
--* Kill Example:: Using `kill' for Communication
--
--Blocking Signals
--
--* Why Block:: The purpose of blocking signals.
--* Signal Sets:: How to specify which signals to block.
--* Process Signal Mask:: Blocking delivery of signals to your
-- process during normal execution.
--* Testing for Delivery:: Blocking to Test for Delivery of a Signal
--* Blocking for Handler:: Blocking additional signals while a
-- handler is being run.
--* Checking for Pending Signals::Checking for Pending Signals
--* Remembering a Signal:: How you can get almost the same effect
-- as blocking a signal, by handling it
-- and setting a flag to be tested later.
--
--Waiting for a Signal
--
--* Using Pause:: The simple way, using `pause'.
--* Pause Problems:: Why the simple way is often not very good.
--* Sigsuspend:: Reliably waiting for a specific signal.
--
--BSD Signal Handling
--
--* BSD Handler:: BSD Function to Establish a Handler.
--* Blocking in BSD:: BSD Functions for Blocking Signals
--
--Process Startup and Termination
--
--* Program Arguments:: Parsing your program's command-line arguments.
--* Environment Variables:: How to access parameters inherited from
-- a parent process.
--* Program Termination:: How to cause a process to terminate and
-- return status information to its parent.
--
--Program Arguments
--
--* Argument Syntax:: By convention, options start with a hyphen.
--* Parsing Options:: The `getopt' function.
--* Example of Getopt:: An example of parsing options with `getopt'.
--* Long Options:: GNU utilities should accept long-named
options.
-- Here is how to do that.
--* Long Option Example:: An example of using `getopt_long'.
--
--Environment Variables
--
--* Environment Access:: How to get and set the values of
-- environment variables.
--* Standard Environment:: These environment variables have
-- standard interpretations.
--
--Program Termination
--
--* Normal Termination:: If a program calls `exit', a
-- process terminates normally.
--* Exit Status:: The `exit status' provides information
-- about why the process terminated.
--* Cleanups on Exit:: A process can run its own cleanup
-- functions upon normal termination.
--* Aborting a Program:: The `abort' function causes
-- abnormal program termination.
--* Termination Internals:: What happens when a process terminates.
--
--
--Child Processes
--
--* Running a Command:: The easy way to run another program.
--* Process Creation Concepts:: An overview of the hard way to do it.
--* Process Identification:: How to get the process ID of a process.
--* Creating a Process:: How to fork a child process.
--* Executing a File:: How to make a child execute another program.
--* Process Completion:: How to tell when a child process has
completed.
--* Process Completion Status:: How to interpret the status value
-- returned from a child process.
--* BSD Wait Functions:: More functions, for backward compatibility.
--* Process Creation Example:: A complete example program.
--
--Job Control
--
--* Concepts of Job Control :: Concepts of Job Control
--* Job Control is Optional:: Not all POSIX systems support job control.
--* Controlling Terminal:: How a process gets its controlling terminal.
--* Access to the Terminal:: How processes share the controlling terminal.
--* Orphaned Process Groups:: Jobs left after the user logs out.
--* Implementing a Shell:: What a shell must do to implement job control.
--* Functions for Job Control:: Functions to control process groups.
--
--Implementing a Job Control Shell
--
--* Data Structures:: Introduction to the sample shell.
--* Initializing the Shell:: What the shell must do to take
-- responsibility for job control.
--* Launching Jobs:: Creating jobs to execute commands.
--* Foreground and Background:: Putting a job in foreground of background.
--* Stopped and Terminated Jobs:: Reporting job status.
--* Continuing Stopped Jobs:: How to continue a stopped job in
-- the foreground or background.
--* Missing Pieces:: Other parts of the shell.
--
--Functions for Job Control
--
--* Identifying the Terminal:: Determining the controlling terminal's name.
--* Process Group Functions:: Functions for manipulating process groups.
--* Terminal Access Functions:: Functions for controlling terminal access.
--
--Name Service Switch
--
--* NSS Basics:: What is this NSS good for.
--* NSS Configuration File:: Configuring NSS.
--* NSS Module Internals:: How does it work internally.
--* Extending NSS:: What to do to add services or databases.
--
--Users and Groups
--
--* User and Group IDs:: Each user and group has a unique numeric ID.
--* Process Persona:: The user IDs and group IDs of a process.
--* Why Change Persona:: Why a program might need to change
-- its user and/or group IDs.
--* How Change Persona:: Restrictions on changing user and group IDs.
--* Reading Persona:: Examining the process's user and group IDs.
--* Setting User ID::
--* Setting Groups::
--* Enable/Disable Setuid::
--* Setuid Program Example:: Setuid Program Example
--* Tips for Setuid::
--* Who Logged In:: Getting the name of the user who logged in,
-- or of the real user ID of the current
process.
--
--* User Database:: Functions and data structures for
-- accessing the user database.
--* Group Database:: Functions and data structures for
-- accessing the group database.
--* Database Example:: Example program showing use of database
-- inquiry functions.
--
--User Database
--
--* User Data Structure::
--* Lookup User::
--* Scanning All Users:: Scanning the List of All Users
--* Writing a User Entry::
--
--Group Database
--
--* Group Data Structure::
--* Lookup Group::
--* Scanning All Groups:: Scanning the List of All Groups
--
--System Information
--
--* Host Identification:: Determining the name of the machine.
--* Hardware/Software Type ID:: Determining the hardware type and
-- operating system type.
--
--System Configuration Limits
--
--* General Limits:: Constants and functions that describe
-- various process-related limits that have
-- one uniform value for any given machine.
--* System Options:: Optional POSIX features.
--* Version Supported:: Version numbers of POSIX.1 and POSIX.2.
--* Sysconf:: Getting specific configuration values
-- of general limits and system options.
--* Minimums:: Minimum values for general limits.
--
--* Limits for Files:: Size limitations on individual files.
-- These can vary between file systems
-- or even from file to file.
--* Options for Files:: Optional features that some files may support.
--* File Minimums:: Minimum values for file limits.
--* Pathconf:: Getting the limit values for a particular file.
--
--* Utility Limits:: Capacity limits of POSIX.2 utility programs.
--* Utility Minimums:: Minimum allowable values of those limits.
--
--* String Parameters:: Getting the default search path.
--
--Library Facilities that are Part of the C Language
--
--* Consistency Checking:: Using `assert' to abort
-- if something "impossible" happens.
--* Variadic Functions:: Defining functions with varying
-- numbers of arguments.
--* Null Pointer Constant:: The macro `NULL'.
--* Important Data Types:: Data types for object sizes.
--* Data Type Measurements:: Parameters of data type representations.
--
--Variadic Functions
--
--* Why Variadic:: Reasons for making functions take
-- variable arguments.
--* How Variadic:: How to define and call variadic functions.
--* Argument Macros:: Detailed specification of the macros
-- for accessing variable arguments.
--* Variadic Example:: A complete example.
--
--How Variadic Functions are Defined and Used
--
--* Variadic Prototypes:: How to make a prototype for a function
-- with variable arguments.
--* Receiving Arguments:: Steps you must follow to access the
-- optional argument values.
--* How Many Arguments:: How to decide whether there are more
arguments.
--* Calling Variadics:: Things you need to know about calling
-- variable arguments functions.
--
--Data Type Measurements
--
--* Width of Type:: How many bits does an integer type hold?
--* Range of Type:: What are the largest and smallest values
-- that an integer type can hold?
--* Floating Type Macros:: Parameters that measure floating-point types.
--* Structure Measurement:: Getting measurements on structure types.
--
--Floating Type Macros
--
--* Floating Point Concepts:: Definitions of terminology.
--* Floating Point Parameters:: Dimensions, limits of floating point types.
--* IEEE Floating Point:: How one common representation is described.
--
--Library Maintenance
--
--* Installation:: How to configure, compile and install
-- the GNU C library.
--* Reporting Bugs:: How to report bugs (if you want to
-- get them fixed) and other troubles
-- you may have with the GNU C library.
--* Porting:: How to port the GNU C library to
-- a new machine or operating system.
--* Contributors:: Who wrote what parts of the GNU C Library.
--
--Porting the GNU C Library
--
--* Hierarchy Conventions:: How the `sysdeps' hierarchy is
-- layed out.
--* Porting to Unix:: Porting the library to an average
-- Unix-like system.
--
--
--File: libc.info, Node: Introduction, Next: Error Reporting, Prev: Top,
Up: Top
--
--Introduction
--************
--
-- The C language provides no built-in facilities for performing such
--common operations as input/output, memory management, string
--manipulation, and the like. Instead, these facilities are defined in a
--standard "library", which you compile and link with your programs.
--
-- The GNU C library, described in this document, defines all of the
--library functions that are specified by the ISO C standard, as well as
--additional features specific to POSIX and other derivatives of the Unix
--operating system, and extensions specific to the GNU system.
--
-- The purpose of this manual is to tell you how to use the facilities
--of the GNU library. We have mentioned which features belong to which
--standards to help you identify things that are potentially nonportable
--to other systems. But the emphasis in this manual is not on strict
--portability.
--
--* Menu:
--
--* Getting Started:: What this manual is for and how to use it.
--* Standards and Portability:: Standards and sources upon which the GNU
-- C library is based.
--* Using the Library:: Some practical uses for the library.
--* Roadmap to the Manual:: Overview of the remaining chapters in
-- this manual.
--
--
--File: libc.info, Node: Getting Started, Next: Standards and Portability,
Up: Introduction
--
--Getting Started
--===============
--
-- This manual is written with the assumption that you are at least
--somewhat familiar with the C programming language and basic programming
--concepts. Specifically, familiarity with ISO standard C (*note ISO
--C::.), rather than "traditional" pre-ISO C dialects, is assumed.
--
-- The GNU C library includes several "header files", each of which
--provides definitions and declarations for a group of related facilities;
--this information is used by the C compiler when processing your program.
--For example, the header file `stdio.h' declares facilities for
--performing input and output, and the header file `string.h' declares
--string processing utilities. The organization of this manual generally
--follows the same division as the header files.
--
-- If you are reading this manual for the first time, you should read
--all of the introductory material and skim the remaining chapters.
--There are a *lot* of functions in the GNU C library and it's not
--realistic to expect that you will be able to remember exactly *how* to
--use each and every one of them. It's more important to become
--generally familiar with the kinds of facilities that the library
--provides, so that when you are writing your programs you can recognize
--*when* to make use of library functions, and *where* in this manual you
--can find more specific information about them.
--
--
--File: libc.info, Node: Standards and Portability, Next: Using the Library,
Prev: Getting Started, Up: Introduction
--
--Standards and Portability
--=========================
--
-- This section discusses the various standards and other sources that
--the GNU C library is based upon. These sources include the ISO C and
--POSIX standards, and the System V and Berkeley Unix implementations.
--
-- The primary focus of this manual is to tell you how to make effective
--use of the GNU library facilities. But if you are concerned about
--making your programs compatible with these standards, or portable to
--operating systems other than GNU, this can affect how you use the
--library. This section gives you an overview of these standards, so that
--you will know what they are when they are mentioned in other parts of
--the manual.
--
-- *Note Library Summary::, for an alphabetical list of the functions
--and other symbols provided by the library. This list also states which
--standards each function or symbol comes from.
--
--* Menu:
--
--* ISO C:: The international standard for the C
-- programming language.
--* POSIX:: The ISO/IEC 9945 (aka IEEE 1003) standards
-- for operating systems.
--* Berkeley Unix:: BSD and SunOS.
--* SVID:: The System V Interface Description.
--
--
--File: libc.info, Node: ISO C, Next: POSIX, Up: Standards and Portability
--
--ISO C
-------
--
-- The GNU C library is compatible with the C standard adopted by the
--American National Standards Institute (ANSI): `American National
--Standard X3.159-1989--"ANSI C"' and later by the International
--Standardization Organization (ISO): `ISO/IEC 9899:1990, "Programming
--languages--C"'. We here refer to the standard as ISO C since this is
--the more general standard in respect of ratification. The header files
--and library facilities that make up the GNU library are a superset of
--those specified by the ISO C standard.
--
-- If you are concerned about strict adherence to the ISO C standard,
--you should use the `-ansi' option when you compile your programs with
--the GNU C compiler. This tells the compiler to define *only* ISO
--standard features from the library header files, unless you explicitly
--ask for additional features. *Note Feature Test Macros::, for
--information on how to do this.
--
-- Being able to restrict the library to include only ISO C features is
--important because ISO C puts limitations on what names can be defined
--by the library implementation, and the GNU extensions don't fit these
--limitations. *Note Reserved Names::, for more information about these
--restrictions.
--
-- This manual does not attempt to give you complete details on the
--differences between ISO C and older dialects. It gives advice on how
--to write programs to work portably under multiple C dialects, but does
--not aim for completeness.
--
--
--File: libc.info, Node: POSIX, Next: Berkeley Unix, Prev: ISO C, Up:
Standards and Portability
--
--POSIX (The Portable Operating System Interface)
-------------------------------------------------
--
-- The GNU library is also compatible with the IEEE "POSIX" family of
--standards, known more formally as the "Portable Operating System
--Interface for Computer Environments". POSIX is derived mostly from
--various versions of the Unix operating system.
--
-- The library facilities specified by the POSIX standards are a
--superset of those required by ISO C; POSIX specifies additional
--features for ISO C functions, as well as specifying new additional
--functions. In general, the additional requirements and functionality
--defined by the POSIX standards are aimed at providing lower-level
--support for a particular kind of operating system environment, rather
--than general programming language support which can run in many diverse
--operating system environments.
--
-- The GNU C library implements all of the functions specified in `IEEE
--Std 1003.1-1990, the POSIX System Application Program Interface',
--commonly referred to as POSIX.1. The primary extensions to the ISO C
--facilities specified by this standard include file system interface
--primitives (*note File System Interface::.), device-specific terminal
--control functions (*note Low-Level Terminal Interface::.), and process
--control functions (*note Processes::.).
--
-- Some facilities from `IEEE Std 1003.2-1992, the POSIX Shell and
--Utilities standard' (POSIX.2) are also implemented in the GNU library.
--These include utilities for dealing with regular expressions and other
--pattern matching facilities (*note Pattern Matching::.).
--
--
--File: libc.info, Node: Berkeley Unix, Next: SVID, Prev: POSIX, Up:
Standards and Portability
--
--Berkeley Unix
---------------
--
-- The GNU C library defines facilities from some versions of Unix which
--are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD,
--and 4.4 BSD Unix systems (also known as "Berkeley Unix") and from
--"SunOS" (a popular 4.2 BSD derivative that includes some Unix System V
--functionality). These systems support most of the ISO C and POSIX
--facilities, and 4.4 BSD and newer releases of SunOS in fact support
--them all.
--
-- The BSD facilities include symbolic links (*note Symbolic Links::.),
--the `select' function (*note Waiting for I/O::.), the BSD signal
--functions (*note BSD Signal Handling::.), and sockets (*note
--Sockets::.).
--
--
--File: libc.info, Node: SVID, Prev: Berkeley Unix, Up: Standards and
Portability
--
--SVID (The System V Interface Description)
-------------------------------------------
--
-- The "System V Interface Description" (SVID) is a document describing
--the AT&T Unix System V operating system. It is to some extent a
--superset of the POSIX standard (*note POSIX::.).
--
-- The GNU C library defines some of the facilities required by the SVID
--that are not also required by the ISO C or POSIX standards, for
--compatibility with System V Unix and other Unix systems (such as
--SunOS) which include these facilities. However, many of the more
--obscure and less generally useful facilities required by the SVID are
--not included. (In fact, Unix System V itself does not provide them
--all.)
--
--
--File: libc.info, Node: Using the Library, Next: Roadmap to the Manual,
Prev: Standards and Portability, Up: Introduction
--
--Using the Library
--=================
--
-- This section describes some of the practical issues involved in using
--the GNU C library.
--
--* Menu:
--
--* Header Files:: How to include the header files in your
-- programs.
--* Macro Definitions:: Some functions in the library may really
-- be implemented as macros.
--* Reserved Names:: The C standard reserves some names for
-- the library, and some for users.
--* Feature Test Macros:: How to control what names are defined.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-10
glibc-2.0.1/manual/libc.info-10
---- ../glibc-2.0.1/manual/libc.info-10 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-10 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1251 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Operating Modes, Next: Getting File Status Flags,
Prev: Open-time Flags, Up: File Status Flags
--
--I/O Operating Modes
---------------------
--
-- The operating modes affect how input and output operations using a
--file descriptor work. These flags are set by `open' and can be fetched
--and changed with `fcntl'.
--
-- - Macro: int O_APPEND
-- The bit that enables append mode for the file. If set, then all
-- `write' operations write the data at the end of the file, extending
-- it, regardless of the current file position. This is the only
-- reliable way to append to a file. In append mode, you are
-- guaranteed that the data you write will always go to the current
-- end of the file, regardless of other processes writing to the
-- file. Conversely, if you simply set the file position to the end
-- of file and write, then another process can extend the file after
-- you set the file position but before you write, resulting in your
-- data appearing someplace before the real end of file.
--
-- - Macro: int O_NONBLOCK
-- The bit that enables nonblocking mode for the file. If this bit
-- is set, `read' requests on the file can return immediately with a
-- failure status if there is no input immediately available, instead
-- of blocking. Likewise, `write' requests can also return
-- immediately with a failure status if the output can't be written
-- immediately.
--
-- Note that the `O_NONBLOCK' flag is overloaded as both an I/O
-- operating mode and a file name translation flag; *note Open-time
-- Flags::..
--
-- - Macro: int O_NDELAY
-- This is an obsolete name for `O_NONBLOCK', provided for
-- compatibility with BSD. It is not defined by the POSIX.1 standard.
--
-- The remaining operating modes are BSD and GNU extensions. They
--exist only on some systems. On other systems, these macros are not
--defined.
--
-- - Macro: int O_ASYNC
-- The bit that enables asynchronous input mode. If set, then `SIGIO'
-- signals will be generated when input is available. *Note
-- Interrupt Input::.
--
-- Asynchronous input mode is a BSD feature.
--
-- - Macro: int O_FSYNC
-- The bit that enables synchronous writing for the file. If set,
-- each `write' call will make sure the data is reliably stored on
-- disk before returning. Synchronous writing is a BSD feature.
--
-- - Macro: int O_SYNC
-- This is another name for `O_FSYNC'. They have the same value.
--
-- - Macro: int O_NOATIME
-- If this bit is set, `read' will not update the access time of the
-- file. *Note File Times::. This is used by programs that do
-- backups, so that backing a file up does not count as reading it.
-- Only the owner of the file or the superuser may use this bit.
--
-- This is a GNU extension.
--
--
--File: libc.info, Node: Getting File Status Flags, Prev: Operating Modes,
Up: File Status Flags
--
--Getting and Setting File Status Flags
---------------------------------------
--
-- The `fcntl' function can fetch or change file status flags.
--
-- - Macro: int F_GETFL
-- This macro is used as the COMMAND argument to `fcntl', to read the
-- file status flags for the open file with descriptor FILEDES.
--
-- The normal return value from `fcntl' with this command is a
-- nonnegative number which can be interpreted as the bitwise OR of
-- the individual flags. Since the file access modes are not
-- single-bit values, you can mask off other bits in the returned
-- flags with `O_ACCMODE' to compare them.
--
-- In case of an error, `fcntl' returns `-1'. The following `errno'
-- error conditions are defined for this command:
--
-- `EBADF'
-- The FILEDES argument is invalid.
--
-- - Macro: int F_SETFL
-- This macro is used as the COMMAND argument to `fcntl', to set the
-- file status flags for the open file corresponding to the FILEDES
-- argument. This command requires a third `int' argument to specify
-- the new flags, so the call looks like this:
--
-- fcntl (FILEDES, F_SETFL, NEW-FLAGS)
--
-- You can't change the access mode for the file in this way; that is,
-- whether the file descriptor was opened for reading or writing.
--
-- The normal return value from `fcntl' with this command is an
-- unspecified value other than `-1', which indicates an error. The
-- error conditions are the same as for the `F_GETFL' command.
--
-- If you want to modify the file status flags, you should get the
--current flags with `F_GETFL' and modify the value. Don't assume that
--the flags listed here are the only ones that are implemented; your
--program may be run years from now and more flags may exist then. For
--example, here is a function to set or clear the flag `O_NONBLOCK'
--without altering any other flags:
--
-- /* Set the `O_NONBLOCK' flag of DESC if VALUE is nonzero,
-- or clear the flag if VALUE is 0.
-- Return 0 on success, or -1 on error with `errno' set. */
--
-- int
-- set_nonblock_flag (int desc, int value)
-- {
-- int oldflags = fcntl (desc, F_GETFL, 0);
-- /* If reading the flags failed, return error indication now. */
-- if (oldflags == -1)
-- return -1;
-- /* Set just the flag we want to set. */
-- if (value != 0)
-- oldflags |= O_NONBLOCK;
-- else
-- oldflags &= ~O_NONBLOCK;
-- /* Store modified flag word in the descriptor. */
-- return fcntl (desc, F_SETFL, oldflags);
-- }
--
--
--File: libc.info, Node: File Locks, Next: Interrupt Input, Prev: File
Status Flags, Up: Low-Level I/O
--
--File Locks
--==========
--
-- The remaining `fcntl' commands are used to support "record locking",
--which permits multiple cooperating programs to prevent each other from
--simultaneously accessing parts of a file in error-prone ways.
--
-- An "exclusive" or "write" lock gives a process exclusive access for
--writing to the specified part of the file. While a write lock is in
--place, no other process can lock that part of the file.
--
-- A "shared" or "read" lock prohibits any other process from
--requesting a write lock on the specified part of the file. However,
--other processes can request read locks.
--
-- The `read' and `write' functions do not actually check to see
--whether there are any locks in place. If you want to implement a
--locking protocol for a file shared by multiple processes, your
--application must do explicit `fcntl' calls to request and clear locks
--at the appropriate points.
--
-- Locks are associated with processes. A process can only have one
--kind of lock set for each byte of a given file. When any file
--descriptor for that file is closed by the process, all of the locks
--that process holds on that file are released, even if the locks were
--made using other descriptors that remain open. Likewise, locks are
--released when a process exits, and are not inherited by child processes
--created using `fork' (*note Creating a Process::.).
--
-- When making a lock, use a `struct flock' to specify what kind of
--lock and where. This data type and the associated macros for the
--`fcntl' function are declared in the header file `fcntl.h'.
--
-- - Data Type: struct flock
-- This structure is used with the `fcntl' function to describe a file
-- lock. It has these members:
--
-- `short int l_type'
-- Specifies the type of the lock; one of `F_RDLCK', `F_WRLCK',
-- or `F_UNLCK'.
--
-- `short int l_whence'
-- This corresponds to the WHENCE argument to `fseek' or
-- `lseek', and specifies what the offset is relative to. Its
-- value can be one of `SEEK_SET', `SEEK_CUR', or `SEEK_END'.
--
-- `off_t l_start'
-- This specifies the offset of the start of the region to which
-- the lock applies, and is given in bytes relative to the point
-- specified by `l_whence' member.
--
-- `off_t l_len'
-- This specifies the length of the region to be locked. A
-- value of `0' is treated specially; it means the region
-- extends to the end of the file.
--
-- `pid_t l_pid'
-- This field is the process ID (*note Process Creation
-- Concepts::.) of the process holding the lock. It is filled
-- in by calling `fcntl' with the `F_GETLK' command, but is
-- ignored when making a lock.
--
-- - Macro: int F_GETLK
-- This macro is used as the COMMAND argument to `fcntl', to specify
-- that it should get information about a lock. This command
-- requires a third argument of type `struct flock *' to be passed to
-- `fcntl', so that the form of the call is:
--
-- fcntl (FILEDES, F_GETLK, LOCKP)
--
-- If there is a lock already in place that would block the lock
-- described by the LOCKP argument, information about that lock
-- overwrites `*LOCKP'. Existing locks are not reported if they are
-- compatible with making a new lock as specified. Thus, you should
-- specify a lock type of `F_WRLCK' if you want to find out about both
-- read and write locks, or `F_RDLCK' if you want to find out about
-- write locks only.
--
-- There might be more than one lock affecting the region specified
-- by the LOCKP argument, but `fcntl' only returns information about
-- one of them. The `l_whence' member of the LOCKP structure is set
-- to `SEEK_SET' and the `l_start' and `l_len' fields set to identify
-- the locked region.
--
-- If no lock applies, the only change to the LOCKP structure is to
-- update the `l_type' to a value of `F_UNLCK'.
--
-- The normal return value from `fcntl' with this command is an
-- unspecified value other than `-1', which is reserved to indicate an
-- error. The following `errno' error conditions are defined for
-- this command:
--
-- `EBADF'
-- The FILEDES argument is invalid.
--
-- `EINVAL'
-- Either the LOCKP argument doesn't specify valid lock
-- information, or the file associated with FILEDES doesn't
-- support locks.
--
-- - Macro: int F_SETLK
-- This macro is used as the COMMAND argument to `fcntl', to specify
-- that it should set or clear a lock. This command requires a third
-- argument of type `struct flock *' to be passed to `fcntl', so that
-- the form of the call is:
--
-- fcntl (FILEDES, F_SETLK, LOCKP)
--
-- If the process already has a lock on any part of the region, the
-- old lock on that part is replaced with the new lock. You can
-- remove a lock by specifying a lock type of `F_UNLCK'.
--
-- If the lock cannot be set, `fcntl' returns immediately with a value
-- of `-1'. This function does not block waiting for other processes
-- to release locks. If `fcntl' succeeds, it return a value other
-- than `-1'.
--
-- The following `errno' error conditions are defined for this
-- function:
--
-- `EAGAIN'
-- `EACCES'
-- The lock cannot be set because it is blocked by an existing
-- lock on the file. Some systems use `EAGAIN' in this case,
-- and other systems use `EACCES'; your program should treat
-- them alike, after `F_SETLK'. (The GNU system always uses
-- `EAGAIN'.)
--
-- `EBADF'
-- Either: the FILEDES argument is invalid; you requested a read
-- lock but the FILEDES is not open for read access; or, you
-- requested a write lock but the FILEDES is not open for write
-- access.
--
-- `EINVAL'
-- Either the LOCKP argument doesn't specify valid lock
-- information, or the file associated with FILEDES doesn't
-- support locks.
--
-- `ENOLCK'
-- The system has run out of file lock resources; there are
-- already too many file locks in place.
--
-- Well-designed file systems never report this error, because
-- they have no limitation on the number of locks. However, you
-- must still take account of the possibility of this error, as
-- it could result from network access to a file system on
-- another machine.
--
-- - Macro: int F_SETLKW
-- This macro is used as the COMMAND argument to `fcntl', to specify
-- that it should set or clear a lock. It is just like the `F_SETLK'
-- command, but causes the process to block (or wait) until the
-- request can be specified.
--
-- This command requires a third argument of type `struct flock *', as
-- for the `F_SETLK' command.
--
-- The `fcntl' return values and errors are the same as for the
-- `F_SETLK' command, but these additional `errno' error conditions
-- are defined for this command:
--
-- `EINTR'
-- The function was interrupted by a signal while it was waiting.
-- *Note Interrupted Primitives::.
--
-- `EDEADLK'
-- The specified region is being locked by another process. But
-- that process is waiting to lock a region which the current
-- process has locked, so waiting for the lock would result in
-- deadlock. The system does not guarantee that it will detect
-- all such conditions, but it lets you know if it notices one.
--
-- The following macros are defined for use as values for the `l_type'
--member of the `flock' structure. The values are integer constants.
--
--`F_RDLCK'
-- This macro is used to specify a read (or shared) lock.
--
--`F_WRLCK'
-- This macro is used to specify a write (or exclusive) lock.
--
--`F_UNLCK'
-- This macro is used to specify that the region is unlocked.
--
-- As an example of a situation where file locking is useful, consider a
--program that can be run simultaneously by several different users, that
--logs status information to a common file. One example of such a program
--might be a game that uses a file to keep track of high scores. Another
--example might be a program that records usage or accounting information
--for billing purposes.
--
-- Having multiple copies of the program simultaneously writing to the
--file could cause the contents of the file to become mixed up. But you
--can prevent this kind of problem by setting a write lock on the file
--before actually writing to the file.
--
-- If the program also needs to read the file and wants to make sure
--that the contents of the file are in a consistent state, then it can
--also use a read lock. While the read lock is set, no other process can
--lock that part of the file for writing.
--
-- Remember that file locks are only a *voluntary* protocol for
--controlling access to a file. There is still potential for access to
--the file by programs that don't use the lock protocol.
--
--
--File: libc.info, Node: Interrupt Input, Prev: File Locks, Up: Low-Level I/O
--
--Interrupt-Driven Input
--======================
--
-- If you set the `O_ASYNC' status flag on a file descriptor (*note
--File Status Flags::.), a `SIGIO' signal is sent whenever input or
--output becomes possible on that file descriptor. The process or
--process group to receive the signal can be selected by using the
--`F_SETOWN' command to the `fcntl' function. If the file descriptor is
--a socket, this also selects the recipient of `SIGURG' signals that are
--delivered when out-of-band data arrives on that socket; see *Note
--Out-of-Band Data::. (`SIGURG' is sent in any situation where `select'
--would report the socket as having an "exceptional condition". *Note
--Waiting for I/O::.)
--
-- If the file descriptor corresponds to a terminal device, then `SIGIO'
--signals are sent to the foreground process group of the terminal.
--*Note Job Control::.
--
-- The symbols in this section are defined in the header file `fcntl.h'.
--
-- - Macro: int F_GETOWN
-- This macro is used as the COMMAND argument to `fcntl', to specify
-- that it should get information about the process or process group
-- to which `SIGIO' signals are sent. (For a terminal, this is
-- actually the foreground process group ID, which you can get using
-- `tcgetpgrp'; see *Note Terminal Access Functions::.)
--
-- The return value is interpreted as a process ID; if negative, its
-- absolute value is the process group ID.
--
-- The following `errno' error condition is defined for this command:
--
-- `EBADF'
-- The FILEDES argument is invalid.
--
-- - Macro: int F_SETOWN
-- This macro is used as the COMMAND argument to `fcntl', to specify
-- that it should set the process or process group to which `SIGIO'
-- signals are sent. This command requires a third argument of type
-- `pid_t' to be passed to `fcntl', so that the form of the call is:
--
-- fcntl (FILEDES, F_SETOWN, PID)
--
-- The PID argument should be a process ID. You can also pass a
-- negative number whose absolute value is a process group ID.
--
-- The return value from `fcntl' with this command is `-1' in case of
-- error and some other value if successful. The following `errno'
-- error conditions are defined for this command:
--
-- `EBADF'
-- The FILEDES argument is invalid.
--
-- `ESRCH'
-- There is no process or process group corresponding to PID.
--
--
--File: libc.info, Node: File System Interface, Next: Pipes and FIFOs, Prev:
Low-Level I/O, Up: Top
--
--File System Interface
--*********************
--
-- This chapter describes the GNU C library's functions for manipulating
--files. Unlike the input and output functions described in *Note I/O on
--Streams:: and *Note Low-Level I/O::, these functions are concerned with
--operating on the files themselves, rather than on their contents.
--
-- Among the facilities described in this chapter are functions for
--examining or modifying directories, functions for renaming and deleting
--files, and functions for examining and setting file attributes such as
--access permissions and modification times.
--
--* Menu:
--
--* Working Directory:: This is used to resolve relative
-- file names.
--* Accessing Directories:: Finding out what files a directory
-- contains.
--* Hard Links:: Adding alternate names to a file.
--* Symbolic Links:: A file that "points to" a file name.
--* Deleting Files:: How to delete a file, and what that means.
--* Renaming Files:: Changing a file's name.
--* Creating Directories:: A system call just for creating a directory.
--* File Attributes:: Attributes of individual files.
--* Making Special Files:: How to create special files.
--* Temporary Files:: Naming and creating temporary files.
--
--
--File: libc.info, Node: Working Directory, Next: Accessing Directories, Up:
File System Interface
--
--Working Directory
--=================
--
-- Each process has associated with it a directory, called its "current
--working directory" or simply "working directory", that is used in the
--resolution of relative file names (*note File Name Resolution::.).
--
-- When you log in and begin a new session, your working directory is
--initially set to the home directory associated with your login account
--in the system user database. You can find any user's home directory
--using the `getpwuid' or `getpwnam' functions; see *Note User Database::.
--
-- Users can change the working directory using shell commands like
--`cd'. The functions described in this section are the primitives used
--by those commands and by other programs for examining and changing the
--working directory.
--
-- Prototypes for these functions are declared in the header file
--`unistd.h'.
--
-- - Function: char * getcwd (char *BUFFER, size_t SIZE)
-- The `getcwd' function returns an absolute file name representing
-- the current working directory, storing it in the character array
-- BUFFER that you provide. The SIZE argument is how you tell the
-- system the allocation size of BUFFER.
--
-- The GNU library version of this function also permits you to
-- specify a null pointer for the BUFFER argument. Then `getcwd'
-- allocates a buffer automatically, as with `malloc' (*note
-- Unconstrained Allocation::.). If the SIZE is greater than zero,
-- then the buffer is that large; otherwise, the buffer is as large
-- as necessary to hold the result.
--
-- The return value is BUFFER on success and a null pointer on
-- failure. The following `errno' error conditions are defined for
-- this function:
--
-- `EINVAL'
-- The SIZE argument is zero and BUFFER is not a null pointer.
--
-- `ERANGE'
-- The SIZE argument is less than the length of the working
-- directory name. You need to allocate a bigger array and try
-- again.
--
-- `EACCES'
-- Permission to read or search a component of the file name was
-- denied.
--
-- Here is an example showing how you could implement the behavior of
--GNU's `getcwd (NULL, 0)' using only the standard behavior of `getcwd':
--
-- char *
-- gnu_getcwd ()
-- {
-- int size = 100;
-- char *buffer = (char *) xmalloc (size);
--
-- while (1)
-- {
-- char *value = getcwd (buffer, size);
-- if (value != 0)
-- return buffer;
-- size *= 2;
-- free (buffer);
-- buffer = (char *) xmalloc (size);
-- }
-- }
--
--*Note Malloc Examples::, for information about `xmalloc', which is not
--a library function but is a customary name used in most GNU software.
--
-- - Function: char * getwd (char *BUFFER)
-- This is similar to `getcwd', but has no way to specify the size of
-- the buffer. The GNU library provides `getwd' only for backwards
-- compatibility with BSD.
--
-- The BUFFER argument should be a pointer to an array at least
-- `PATH_MAX' bytes long (*note Limits for Files::.). In the GNU
-- system there is no limit to the size of a file name, so this is not
-- necessarily enough space to contain the directory name. That is
-- why this function is deprecated.
--
-- - Function: int chdir (const char *FILENAME)
-- This function is used to set the process's working directory to
-- FILENAME.
--
-- The normal, successful return value from `chdir' is `0'. A value
-- of `-1' is returned to indicate an error. The `errno' error
-- conditions defined for this function are the usual file name
-- syntax errors (*note File Name Errors::.), plus `ENOTDIR' if the
-- file FILENAME is not a directory.
--
--
--File: libc.info, Node: Accessing Directories, Next: Hard Links, Prev:
Working Directory, Up: File System Interface
--
--Accessing Directories
--=====================
--
-- The facilities described in this section let you read the contents
--of a directory file. This is useful if you want your program to list
--all the files in a directory, perhaps as part of a menu.
--
-- The `opendir' function opens a "directory stream" whose elements are
--directory entries. You use the `readdir' function on the directory
--stream to retrieve these entries, represented as `struct dirent'
--objects. The name of the file for each entry is stored in the `d_name'
--member of this structure. There are obvious parallels here to the
--stream facilities for ordinary files, described in *Note I/O on
--Streams::.
--
--* Menu:
--
--* Directory Entries:: Format of one directory entry.
--* Opening a Directory:: How to open a directory stream.
--* Reading/Closing Directory:: How to read directory entries from the stream.
--* Simple Directory Lister:: A very simple directory listing program.
--* Random Access Directory:: Rereading part of the directory
-- already read with the same stream.
--
--
--File: libc.info, Node: Directory Entries, Next: Opening a Directory, Up:
Accessing Directories
--
--Format of a Directory Entry
-----------------------------
--
-- This section describes what you find in a single directory entry, as
--you might obtain it from a directory stream. All the symbols are
--declared in the header file `dirent.h'.
--
-- - Data Type: struct dirent
-- This is a structure type used to return information about directory
-- entries. It contains the following fields:
--
-- `char d_name[]'
-- This is the null-terminated file name component. This is the
-- only field you can count on in all POSIX systems.
--
-- `ino_t d_fileno'
-- This is the file serial number. For BSD compatibility, you
-- can also refer to this member as `d_ino'. In the GNU system
-- and most POSIX systems, for most files this the same as the
-- `st_ino' member that `stat' will return for the file. *Note
-- File Attributes::.
--
-- `unsigned char d_namlen'
-- This is the length of the file name, not including the
-- terminating null character. Its type is `unsigned char'
-- because that is the integer type of the appropriate size
--
-- `unsigned char d_type'
-- This is the type of the file, possibly unknown. The
-- following constants are defined for its value:
--
-- `DT_UNKNOWN'
-- The type is unknown. On some systems this is the only
-- value returned.
--
-- `DT_REG'
-- A regular file.
--
-- `DT_DIR'
-- A directory.
--
-- `DT_FIFO'
-- A named pipe, or FIFO. *Note FIFO Special Files::.
--
-- `DT_SOCK'
-- A local-domain socket.
--
-- `DT_CHR'
-- A character device.
--
-- `DT_BLK'
-- A block device.
--
-- This member is a BSD extension. Each value except DT_UNKNOWN
-- corresponds to the file type bits in the `st_mode' member of
-- `struct statbuf'. These two macros convert between `d_type'
-- values and `st_mode' values:
--
-- - Function: int IFTODT (mode_t MODE)
-- This returns the `d_type' value corresponding to MODE.
--
-- - Function: mode_t DTTOIF (int DIRTYPE)
-- This returns the `st_mode' value corresponding to
-- DIRTYPE.
--
-- This structure may contain additional members in the future.
--
-- When a file has multiple names, each name has its own directory
-- entry. The only way you can tell that the directory entries
-- belong to a single file is that they have the same value for the
-- `d_fileno' field.
--
-- File attributes such as size, modification times, and the like are
-- part of the file itself, not any particular directory entry.
-- *Note File Attributes::.
--
--
--File: libc.info, Node: Opening a Directory, Next: Reading/Closing
Directory, Prev: Directory Entries, Up: Accessing Directories
--
--Opening a Directory Stream
----------------------------
--
-- This section describes how to open a directory stream. All the
--symbols are declared in the header file `dirent.h'.
--
-- - Data Type: DIR
-- The `DIR' data type represents a directory stream.
--
-- You shouldn't ever allocate objects of the `struct dirent' or `DIR'
--data types, since the directory access functions do that for you.
--Instead, you refer to these objects using the pointers returned by the
--following functions.
--
-- - Function: DIR * opendir (const char *DIRNAME)
-- The `opendir' function opens and returns a directory stream for
-- reading the directory whose file name is DIRNAME. The stream has
-- type `DIR *'.
--
-- If unsuccessful, `opendir' returns a null pointer. In addition to
-- the usual file name errors (*note File Name Errors::.), the
-- following `errno' error conditions are defined for this function:
--
-- `EACCES'
-- Read permission is denied for the directory named by
-- `dirname'.
--
-- `EMFILE'
-- The process has too many files open.
--
-- `ENFILE'
-- The entire system, or perhaps the file system which contains
-- the directory, cannot support any additional open files at
-- the moment. (This problem cannot happen on the GNU system.)
--
-- The `DIR' type is typically implemented using a file descriptor,
-- and the `opendir' function in terms of the `open' function. *Note
-- Low-Level I/O::. Directory streams and the underlying file
-- descriptors are closed on `exec' (*note Executing a File::.).
--
--
--File: libc.info, Node: Reading/Closing Directory, Next: Simple Directory
Lister, Prev: Opening a Directory, Up: Accessing Directories
--
--Reading and Closing a Directory Stream
----------------------------------------
--
-- This section describes how to read directory entries from a directory
--stream, and how to close the stream when you are done with it. All the
--symbols are declared in the header file `dirent.h'.
--
-- - Function: struct dirent * readdir (DIR *DIRSTREAM)
-- This function reads the next entry from the directory. It normally
-- returns a pointer to a structure containing information about the
-- file. This structure is statically allocated and can be rewritten
-- by a subsequent call.
--
-- *Portability Note:* On some systems, `readdir' may not return
-- entries for `.' and `..', even though these are always valid file
-- names in any directory. *Note File Name Resolution::.
--
-- If there are no more entries in the directory or an error is
-- detected, `readdir' returns a null pointer. The following `errno'
-- error conditions are defined for this function:
--
-- `EBADF'
-- The DIRSTREAM argument is not valid.
--
-- `readdir' is not thread safe. Multiple threads using `readdir' on
-- the same DIRSTREAM may overwrite the return value. Use
-- `readdir_r' when this is critical.
--
-- - Function: int readdir_r (DIR *DIRSTREAM, struct *ENTRY, struct
-- **RESULT)
-- This function is the reentrant version of `readdir'. Like
-- `readdir' it returns the next entry from the directory. But to
-- prevent conflicts for simultaneously running threads the result is
-- not stored in some internal memory. Instead the argument ENTRY
-- has to point to a place where the result is stored.
--
-- The return value is `0' in case the next entry was read
-- successfully. In this case a pointer to the result is returned in
-- *RESULT. It is not required that *RESULT is the same as ENTRY.
-- If something goes wrong while executing `readdir_r' the function
-- returns `-1'. The `errno' variable is set like described for
-- `readdir'.
--
-- *Portability Note:* On some systems, `readdir_r' may not return a
-- terminated string as the file name even if no `d_reclen' element
-- is available in `struct dirent' and the file name as the maximal
-- allowed size. Modern systems all have the `d_reclen' field and on
-- old systems multi threading is not critical. In any case, there
-- is no such problem with the `readdir' function so that even on
-- systems without `d_reclen' field one could use multiple threads by
-- using external locking.
--
-- - Function: int closedir (DIR *DIRSTREAM)
-- This function closes the directory stream DIRSTREAM. It returns
-- `0' on success and `-1' on failure.
--
-- The following `errno' error conditions are defined for this
-- function:
--
-- `EBADF'
-- The DIRSTREAM argument is not valid.
--
--
--File: libc.info, Node: Simple Directory Lister, Next: Random Access
Directory, Prev: Reading/Closing Directory, Up: Accessing Directories
--
--Simple Program to List a Directory
------------------------------------
--
-- Here's a simple program that prints the names of the files in the
--current working directory:
--
-- #include <stddef.h>
-- #include <stdio.h>
-- #include <sys/types.h>
-- #include <dirent.h>
--
-- int
-- main (void)
-- {
-- DIR *dp;
-- struct dirent *ep;
--
-- dp = opendir ("./");
-- if (dp != NULL)
-- {
-- while (ep = readdir (dp))
-- puts (ep->d_name);
-- (void) closedir (dp);
-- }
-- else
-- puts ("Couldn't open the directory.");
--
-- return 0;
-- }
--
-- The order in which files appear in a directory tends to be fairly
--random. A more useful program would sort the entries (perhaps by
--alphabetizing them) before printing them; see *Note Array Sort
--Function::.
--
--
--File: libc.info, Node: Random Access Directory, Prev: Simple Directory
Lister, Up: Accessing Directories
--
--Random Access in a Directory Stream
-------------------------------------
--
-- This section describes how to reread parts of a directory that you
--have already read from an open directory stream. All the symbols are
--declared in the header file `dirent.h'.
--
-- - Function: void rewinddir (DIR *DIRSTREAM)
-- The `rewinddir' function is used to reinitialize the directory
-- stream DIRSTREAM, so that if you call `readdir' it returns
-- information about the first entry in the directory again. This
-- function also notices if files have been added or removed to the
-- directory since it was opened with `opendir'. (Entries for these
-- files might or might not be returned by `readdir' if they were
-- added or removed since you last called `opendir' or `rewinddir'.)
--
-- - Function: off_t telldir (DIR *DIRSTREAM)
-- The `telldir' function returns the file position of the directory
-- stream DIRSTREAM. You can use this value with `seekdir' to
-- restore the directory stream to that position.
--
-- - Function: void seekdir (DIR *DIRSTREAM, off_t POS)
-- The `seekdir' function sets the file position of the directory
-- stream DIRSTREAM to POS. The value POS must be the result of a
-- previous call to `telldir' on this particular stream; closing and
-- reopening the directory can invalidate values returned by
-- `telldir'.
--
--
--File: libc.info, Node: Hard Links, Next: Symbolic Links, Prev: Accessing
Directories, Up: File System Interface
--
--Hard Links
--==========
--
-- In POSIX systems, one file can have many names at the same time.
--All of the names are equally real, and no one of them is preferred to
--the others.
--
-- To add a name to a file, use the `link' function. (The new name is
--also called a "hard link" to the file.) Creating a new link to a file
--does not copy the contents of the file; it simply makes a new name by
--which the file can be known, in addition to the file's existing name or
--names.
--
-- One file can have names in several directories, so the the
--organization of the file system is not a strict hierarchy or tree.
--
-- In most implementations, it is not possible to have hard links to the
--same file in multiple file systems. `link' reports an error if you try
--to make a hard link to the file from another file system when this
--cannot be done.
--
-- The prototype for the `link' function is declared in the header file
--`unistd.h'.
--
-- - Function: int link (const char *OLDNAME, const char *NEWNAME)
-- The `link' function makes a new link to the existing file named by
-- OLDNAME, under the new name NEWNAME.
--
-- This function returns a value of `0' if it is successful and `-1'
-- on failure. In addition to the usual file name errors (*note File
-- Name Errors::.) for both OLDNAME and NEWNAME, the following
-- `errno' error conditions are defined for this function:
--
-- `EACCES'
-- You are not allowed to write the directory in which the new
-- link is to be written.
--
-- `EEXIST'
-- There is already a file named NEWNAME. If you want to replace
-- this link with a new link, you must remove the old link
-- explicitly first.
--
-- `EMLINK'
-- There are already too many links to the file named by OLDNAME.
-- (The maximum number of links to a file is `LINK_MAX'; see
-- *Note Limits for Files::.)
--
-- `ENOENT'
-- The file named by OLDNAME doesn't exist. You can't make a
-- link to a file that doesn't exist.
--
-- `ENOSPC'
-- The directory or file system that would contain the new link
-- is full and cannot be extended.
--
-- `EPERM'
-- In the GNU system and some others, you cannot make links to
-- directories. Many systems allow only privileged users to do
-- so. This error is used to report the problem.
--
-- `EROFS'
-- The directory containing the new link can't be modified
-- because it's on a read-only file system.
--
-- `EXDEV'
-- The directory specified in NEWNAME is on a different file
-- system than the existing file.
--
-- `EIO'
-- A hardware error occurred while trying to read or write the
-- to filesystem.
--
--
--File: libc.info, Node: Symbolic Links, Next: Deleting Files, Prev: Hard
Links, Up: File System Interface
--
--Symbolic Links
--==============
--
-- The GNU system supports "soft links" or "symbolic links". This is a
--kind of "file" that is essentially a pointer to another file name.
--Unlike hard links, symbolic links can be made to directories or across
--file systems with no restrictions. You can also make a symbolic link
--to a name which is not the name of any file. (Opening this link will
--fail until a file by that name is created.) Likewise, if the symbolic
--link points to an existing file which is later deleted, the symbolic
--link continues to point to the same file name even though the name no
--longer names any file.
--
-- The reason symbolic links work the way they do is that special things
--happen when you try to open the link. The `open' function realizes you
--have specified the name of a link, reads the file name contained in the
--link, and opens that file name instead. The `stat' function likewise
--operates on the file that the symbolic link points to, instead of on
--the link itself.
--
-- By contrast, other operations such as deleting or renaming the file
--operate on the link itself. The functions `readlink' and `lstat' also
--refrain from following symbolic links, because their purpose is to
--obtain information about the link. So does `link', the function that
--makes a hard link--it makes a hard link to the symbolic link, which one
--rarely wants.
--
-- Prototypes for the functions listed in this section are in
--`unistd.h'.
--
-- - Function: int symlink (const char *OLDNAME, const char *NEWNAME)
-- The `symlink' function makes a symbolic link to OLDNAME named
-- NEWNAME.
--
-- The normal return value from `symlink' is `0'. A return value of
-- `-1' indicates an error. In addition to the usual file name
-- syntax errors (*note File Name Errors::.), the following `errno'
-- error conditions are defined for this function:
--
-- `EEXIST'
-- There is already an existing file named NEWNAME.
--
-- `EROFS'
-- The file NEWNAME would exist on a read-only file system.
--
-- `ENOSPC'
-- The directory or file system cannot be extended to make the
-- new link.
--
-- `EIO'
-- A hardware error occurred while reading or writing data on
-- the disk.
--
--
-- - Function: int readlink (const char *FILENAME, char *BUFFER, size_t
-- SIZE)
-- The `readlink' function gets the value of the symbolic link
-- FILENAME. The file name that the link points to is copied into
-- BUFFER. This file name string is *not* null-terminated;
-- `readlink' normally returns the number of characters copied. The
-- SIZE argument specifies the maximum number of characters to copy,
-- usually the allocation size of BUFFER.
--
-- If the return value equals SIZE, you cannot tell whether or not
-- there was room to return the entire name. So make a bigger buffer
-- and call `readlink' again. Here is an example:
--
-- char *
-- readlink_malloc (char *filename)
-- {
-- int size = 100;
--
-- while (1)
-- {
-- char *buffer = (char *) xmalloc (size);
-- int nchars = readlink (filename, buffer, size);
-- if (nchars < size)
-- return buffer;
-- free (buffer);
-- size *= 2;
-- }
-- }
--
-- A value of `-1' is returned in case of error. In addition to the
-- usual file name errors (*note File Name Errors::.), the following
-- `errno' error conditions are defined for this function:
--
-- `EINVAL'
-- The named file is not a symbolic link.
--
-- `EIO'
-- A hardware error occurred while reading or writing data on
-- the disk.
--
--
--File: libc.info, Node: Deleting Files, Next: Renaming Files, Prev:
Symbolic Links, Up: File System Interface
--
--Deleting Files
--==============
--
-- You can delete a file with the functions `unlink' or `remove'.
--
-- Deletion actually deletes a file name. If this is the file's only
--name, then the file is deleted as well. If the file has other names as
--well (*note Hard Links::.), it remains accessible under its other names.
--
-- - Function: int unlink (const char *FILENAME)
-- The `unlink' function deletes the file name FILENAME. If this is
-- a file's sole name, the file itself is also deleted. (Actually,
-- if any process has the file open when this happens, deletion is
-- postponed until all processes have closed the file.)
--
-- The function `unlink' is declared in the header file `unistd.h'.
--
-- This function returns `0' on successful completion, and `-1' on
-- error. In addition to the usual file name errors (*note File Name
-- Errors::.), the following `errno' error conditions are defined for
-- this function:
--
-- `EACCES'
-- Write permission is denied for the directory from which the
-- file is to be removed, or the directory has the sticky bit
-- set and you do not own the file.
--
-- `EBUSY'
-- This error indicates that the file is being used by the
-- system in such a way that it can't be unlinked. For example,
-- you might see this error if the file name specifies the root
-- directory or a mount point for a file system.
--
-- `ENOENT'
-- The file name to be deleted doesn't exist.
--
-- `EPERM'
-- On some systems, `unlink' cannot be used to delete the name
-- of a directory, or can only be used this way by a privileged
-- user. To avoid such problems, use `rmdir' to delete
-- directories. (In the GNU system `unlink' can never delete
-- the name of a directory.)
--
-- `EROFS'
-- The directory in which the file name is to be deleted is on a
-- read-only file system, and can't be modified.
--
-- - Function: int rmdir (const char *FILENAME)
-- The `rmdir' function deletes a directory. The directory must be
-- empty before it can be removed; in other words, it can only contain
-- entries for `.' and `..'.
--
-- In most other respects, `rmdir' behaves like `unlink'. There are
-- two additional `errno' error conditions defined for `rmdir':
--
-- `ENOTEMPTY'
-- `EEXIST'
-- The directory to be deleted is not empty.
--
-- These two error codes are synonymous; some systems use one, and
-- some use the other. The GNU system always uses `ENOTEMPTY'.
--
-- The prototype for this function is declared in the header file
-- `unistd.h'.
--
-- - Function: int remove (const char *FILENAME)
-- This is the ISO C function to remove a file. It works like
-- `unlink' for files and like `rmdir' for directories. `remove' is
-- declared in `stdio.h'.
--
--
--File: libc.info, Node: Renaming Files, Next: Creating Directories, Prev:
Deleting Files, Up: File System Interface
--
--Renaming Files
--==============
--
-- The `rename' function is used to change a file's name.
--
-- - Function: int rename (const char *OLDNAME, const char *NEWNAME)
-- The `rename' function renames the file name OLDNAME with NEWNAME.
-- The file formerly accessible under the name OLDNAME is afterward
-- accessible as NEWNAME instead. (If the file had any other names
-- aside from OLDNAME, it continues to have those names.)
--
-- The directory containing the name NEWNAME must be on the same file
-- system as the file (as indicated by the name OLDNAME).
--
-- One special case for `rename' is when OLDNAME and NEWNAME are two
-- names for the same file. The consistent way to handle this case
-- is to delete OLDNAME. However, POSIX requires that in this case
-- `rename' do nothing and report success--which is inconsistent. We
-- don't know what your operating system will do.
--
-- If the OLDNAME is not a directory, then any existing file named
-- NEWNAME is removed during the renaming operation. However, if
-- NEWNAME is the name of a directory, `rename' fails in this case.
--
-- If the OLDNAME is a directory, then either NEWNAME must not exist
-- or it must name a directory that is empty. In the latter case,
-- the existing directory named NEWNAME is deleted first. The name
-- NEWNAME must not specify a subdirectory of the directory `oldname'
-- which is being renamed.
--
-- One useful feature of `rename' is that the meaning of the name
-- NEWNAME changes "atomically" from any previously existing file by
-- that name to its new meaning (the file that was called OLDNAME).
-- There is no instant at which NEWNAME is nonexistent "in between"
-- the old meaning and the new meaning. If there is a system crash
-- during the operation, it is possible for both names to still
-- exist; but NEWNAME will always be intact if it exists at all.
--
-- If `rename' fails, it returns `-1'. In addition to the usual file
-- name errors (*note File Name Errors::.), the following `errno'
-- error conditions are defined for this function:
--
-- `EACCES'
-- One of the directories containing NEWNAME or OLDNAME refuses
-- write permission; or NEWNAME and OLDNAME are directories and
-- write permission is refused for one of them.
--
-- `EBUSY'
-- A directory named by OLDNAME or NEWNAME is being used by the
-- system in a way that prevents the renaming from working.
-- This includes directories that are mount points for
-- filesystems, and directories that are the current working
-- directories of processes.
--
-- `ENOTEMPTY'
-- `EEXIST'
-- The directory NEWNAME isn't empty. The GNU system always
-- returns `ENOTEMPTY' for this, but some other systems return
-- `EEXIST'.
--
-- `EINVAL'
-- The OLDNAME is a directory that contains NEWNAME.
--
-- `EISDIR'
-- The NEWNAME names a directory, but the OLDNAME doesn't.
--
-- `EMLINK'
-- The parent directory of NEWNAME would have too many links.
--
-- `ENOENT'
-- The file named by OLDNAME doesn't exist.
--
-- `ENOSPC'
-- The directory that would contain NEWNAME has no room for
-- another entry, and there is no space left in the file system
-- to expand it.
--
-- `EROFS'
-- The operation would involve writing to a directory on a
-- read-only file system.
--
-- `EXDEV'
-- The two file names NEWNAME and OLDNAMES are on different file
-- systems.
--
--
--File: libc.info, Node: Creating Directories, Next: File Attributes, Prev:
Renaming Files, Up: File System Interface
--
--Creating Directories
--====================
--
-- Directories are created with the `mkdir' function. (There is also a
--shell command `mkdir' which does the same thing.)
--
-- - Function: int mkdir (const char *FILENAME, mode_t MODE)
-- The `mkdir' function creates a new, empty directory whose name is
-- FILENAME.
--
-- The argument MODE specifies the file permissions for the new
-- directory file. *Note Permission Bits::, for more information
-- about this.
--
-- A return value of `0' indicates successful completion, and `-1'
-- indicates failure. In addition to the usual file name syntax
-- errors (*note File Name Errors::.), the following `errno' error
-- conditions are defined for this function:
--
-- `EACCES'
-- Write permission is denied for the parent directory in which
-- the new directory is to be added.
--
-- `EEXIST'
-- A file named FILENAME already exists.
--
-- `EMLINK'
-- The parent directory has too many links.
--
-- Well-designed file systems never report this error, because
-- they permit more links than your disk could possibly hold.
-- However, you must still take account of the possibility of
-- this error, as it could result from network access to a file
-- system on another machine.
--
-- `ENOSPC'
-- The file system doesn't have enough room to create the new
-- directory.
--
-- `EROFS'
-- The parent directory of the directory being created is on a
-- read-only file system, and cannot be modified.
--
-- To use this function, your program should include the header file
-- `sys/stat.h'.
--
--
--File: libc.info, Node: File Attributes, Next: Making Special Files, Prev:
Creating Directories, Up: File System Interface
--
--File Attributes
--===============
--
-- When you issue an `ls -l' shell command on a file, it gives you
--information about the size of the file, who owns it, when it was last
--modified, and the like. This kind of information is called the "file
--attributes"; it is associated with the file itself and not a particular
--one of its names.
--
-- This section contains information about how you can inquire about and
--modify these attributes of files.
--
--* Menu:
--
--* Attribute Meanings:: The names of the file attributes,
-- and what their values mean.
--* Reading Attributes:: How to read the attributes of a file.
--* Testing File Type:: Distinguishing ordinary files,
-- directories, links...
--* File Owner:: How ownership for new files is determined,
-- and how to change it.
--* Permission Bits:: How information about a file's access
-- mode is stored.
--* Access Permission:: How the system decides who can access a file.
--* Setting Permissions:: How permissions for new files are assigned,
-- and how to change them.
--* Testing File Access:: How to find out if your process can
-- access a file.
--* File Times:: About the time attributes of a file.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-11
glibc-2.0.1/manual/libc.info-11
---- ../glibc-2.0.1/manual/libc.info-11 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-11 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1248 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Attribute Meanings, Next: Reading Attributes, Up:
File Attributes
--
--What the File Attribute Values Mean
-------------------------------------
--
-- When you read the attributes of a file, they come back in a structure
--called `struct stat'. This section describes the names of the
--attributes, their data types, and what they mean. For the functions to
--read the attributes of a file, see *Note Reading Attributes::.
--
-- The header file `sys/stat.h' declares all the symbols defined in
--this section.
--
-- - Data Type: struct stat
-- The `stat' structure type is used to return information about the
-- attributes of a file. It contains at least the following members:
--
-- `mode_t st_mode'
-- Specifies the mode of the file. This includes file type
-- information (*note Testing File Type::.) and the file
-- permission bits (*note Permission Bits::.).
--
-- `ino_t st_ino'
-- The file serial number, which distinguishes this file from
-- all other files on the same device.
--
-- `dev_t st_dev'
-- Identifies the device containing the file. The `st_ino' and
-- `st_dev', taken together, uniquely identify the file. The
-- `st_dev' value is not necessarily consistent across reboots or
-- system crashes, however.
--
-- `nlink_t st_nlink'
-- The number of hard links to the file. This count keeps track
-- of how many directories have entries for this file. If the
-- count is ever decremented to zero, then the file itself is
-- discarded as soon as no process still holds it open.
-- Symbolic links are not counted in the total.
--
-- `uid_t st_uid'
-- The user ID of the file's owner. *Note File Owner::.
--
-- `gid_t st_gid'
-- The group ID of the file. *Note File Owner::.
--
-- `off_t st_size'
-- This specifies the size of a regular file in bytes. For
-- files that are really devices and the like, this field isn't
-- usually meaningful. For symbolic links, this specifies the
-- length of the file name the link refers to.
--
-- `time_t st_atime'
-- This is the last access time for the file. *Note File
-- Times::.
--
-- `unsigned long int st_atime_usec'
-- This is the fractional part of the last access time for the
-- file. *Note File Times::.
--
-- `time_t st_mtime'
-- This is the time of the last modification to the contents of
-- the file. *Note File Times::.
--
-- `unsigned long int st_mtime_usec'
-- This is the fractional part of the time of last modification
-- to the contents of the file. *Note File Times::.
--
-- `time_t st_ctime'
-- This is the time of the last modification to the attributes
-- of the file. *Note File Times::.
--
-- `unsigned long int st_ctime_usec'
-- This is the fractional part of the time of last modification
-- to the attributes of the file. *Note File Times::.
--
-- `unsigned int st_blocks'
-- This is the amount of disk space that the file occupies,
-- measured in units of 512-byte blocks.
--
-- The number of disk blocks is not strictly proportional to the
-- size of the file, for two reasons: the file system may use
-- some blocks for internal record keeping; and the file may be
-- sparse--it may have "holes" which contain zeros but do not
-- actually take up space on the disk.
--
-- You can tell (approximately) whether a file is sparse by
-- comparing this value with `st_size', like this:
--
-- (st.st_blocks * 512 < st.st_size)
--
-- This test is not perfect because a file that is just slightly
-- sparse might not be detected as sparse at all. For practical
-- applications, this is not a problem.
--
-- `unsigned int st_blksize'
-- The optimal block size for reading of writing this file, in
-- bytes. You might use this size for allocating the buffer
-- space for reading of writing the file. (This is unrelated to
-- `st_blocks'.)
--
-- Some of the file attributes have special data type names which exist
--specifically for those attributes. (They are all aliases for well-known
--integer types that you know and love.) These typedef names are defined
--in the header file `sys/types.h' as well as in `sys/stat.h'. Here is a
--list of them.
--
-- - Data Type: mode_t
-- This is an integer data type used to represent file modes. In the
-- GNU system, this is equivalent to `unsigned int'.
--
-- - Data Type: ino_t
-- This is an arithmetic data type used to represent file serial
-- numbers. (In Unix jargon, these are sometimes called "inode
-- numbers".) In the GNU system, this type is equivalent to `unsigned
-- long int'.
--
-- - Data Type: dev_t
-- This is an arithmetic data type used to represent file device
-- numbers. In the GNU system, this is equivalent to `int'.
--
-- - Data Type: nlink_t
-- This is an arithmetic data type used to represent file link counts.
-- In the GNU system, this is equivalent to `unsigned short int'.
--
--
--File: libc.info, Node: Reading Attributes, Next: Testing File Type, Prev:
Attribute Meanings, Up: File Attributes
--
--Reading the Attributes of a File
----------------------------------
--
-- To examine the attributes of files, use the functions `stat',
--`fstat' and `lstat'. They return the attribute information in a
--`struct stat' object. All three functions are declared in the header
--file `sys/stat.h'.
--
-- - Function: int stat (const char *FILENAME, struct stat *BUF)
-- The `stat' function returns information about the attributes of the
-- file named by FILENAME in the structure pointed at by BUF.
--
-- If FILENAME is the name of a symbolic link, the attributes you get
-- describe the file that the link points to. If the link points to a
-- nonexistent file name, then `stat' fails, reporting a nonexistent
-- file.
--
-- The return value is `0' if the operation is successful, and `-1'
-- on failure. In addition to the usual file name errors (*note File
-- Name Errors::., the following `errno' error conditions are defined
-- for this function:
--
-- `ENOENT'
-- The file named by FILENAME doesn't exist.
--
-- - Function: int fstat (int FILEDES, struct stat *BUF)
-- The `fstat' function is like `stat', except that it takes an open
-- file descriptor as an argument instead of a file name. *Note
-- Low-Level I/O::.
--
-- Like `stat', `fstat' returns `0' on success and `-1' on failure.
-- The following `errno' error conditions are defined for `fstat':
--
-- `EBADF'
-- The FILEDES argument is not a valid file descriptor.
--
-- - Function: int lstat (const char *FILENAME, struct stat *BUF)
-- The `lstat' function is like `stat', except that it does not
-- follow symbolic links. If FILENAME is the name of a symbolic
-- link, `lstat' returns information about the link itself; otherwise,
-- `lstat' works like `stat'. *Note Symbolic Links::.
--
--
--File: libc.info, Node: Testing File Type, Next: File Owner, Prev: Reading
Attributes, Up: File Attributes
--
--Testing the Type of a File
----------------------------
--
-- The "file mode", stored in the `st_mode' field of the file
--attributes, contains two kinds of information: the file type code, and
--the access permission bits. This section discusses only the type code,
--which you can use to tell whether the file is a directory, whether it is
--a socket, and so on. For information about the access permission,
--*Note Permission Bits::.
--
-- There are two predefined ways you can access the file type portion of
--the file mode. First of all, for each type of file, there is a
--"predicate macro" which examines a file mode value and returns true or
--false--is the file of that type, or not. Secondly, you can mask out
--the rest of the file mode to get just a file type code. You can
--compare this against various constants for the supported file types.
--
-- All of the symbols listed in this section are defined in the header
--file `sys/stat.h'.
--
-- The following predicate macros test the type of a file, given the
--value M which is the `st_mode' field returned by `stat' on that file:
--
-- - Macro: int S_ISDIR (mode_t M)
-- This macro returns nonzero if the file is a directory.
--
-- - Macro: int S_ISCHR (mode_t M)
-- This macro returns nonzero if the file is a character special file
-- (a device like a terminal).
--
-- - Macro: int S_ISBLK (mode_t M)
-- This macro returns nonzero if the file is a block special file (a
-- device like a disk).
--
-- - Macro: int S_ISREG (mode_t M)
-- This macro returns nonzero if the file is a regular file.
--
-- - Macro: int S_ISFIFO (mode_t M)
-- This macro returns nonzero if the file is a FIFO special file, or a
-- pipe. *Note Pipes and FIFOs::.
--
-- - Macro: int S_ISLNK (mode_t M)
-- This macro returns nonzero if the file is a symbolic link. *Note
-- Symbolic Links::.
--
-- - Macro: int S_ISSOCK (mode_t M)
-- This macro returns nonzero if the file is a socket. *Note
-- Sockets::.
--
-- An alterate non-POSIX method of testing the file type is supported
--for compatibility with BSD. The mode can be bitwise ANDed with
--`S_IFMT' to extract the file type code, and compared to the appropriate
--type code constant. For example,
--
-- S_ISCHR (MODE)
--
--is equivalent to:
--
-- ((MODE & S_IFMT) == S_IFCHR)
--
-- - Macro: int S_IFMT
-- This is a bit mask used to extract the file type code portion of a
-- mode value.
--
-- These are the symbolic names for the different file type codes:
--
--`S_IFDIR'
-- This macro represents the value of the file type code for a
-- directory file.
--
--`S_IFCHR'
-- This macro represents the value of the file type code for a
-- character-oriented device file.
--
--`S_IFBLK'
-- This macro represents the value of the file type code for a
-- block-oriented device file.
--
--`S_IFREG'
-- This macro represents the value of the file type code for a
-- regular file.
--
--`S_IFLNK'
-- This macro represents the value of the file type code for a
-- symbolic link.
--
--`S_IFSOCK'
-- This macro represents the value of the file type code for a socket.
--
--`S_IFIFO'
-- This macro represents the value of the file type code for a FIFO
-- or pipe.
--
--
--File: libc.info, Node: File Owner, Next: Permission Bits, Prev: Testing
File Type, Up: File Attributes
--
--File Owner
------------
--
-- Every file has an "owner" which is one of the registered user names
--defined on the system. Each file also has a "group", which is one of
--the defined groups. The file owner can often be useful for showing you
--who edited the file (especially when you edit with GNU Emacs), but its
--main purpose is for access control.
--
-- The file owner and group play a role in determining access because
--the file has one set of access permission bits for the user that is the
--owner, another set that apply to users who belong to the file's group,
--and a third set of bits that apply to everyone else. *Note Access
--Permission::, for the details of how access is decided based on this
--data.
--
-- When a file is created, its owner is set from the effective user ID
--of the process that creates it (*note Process Persona::.). The file's
--group ID may be set from either effective group ID of the process, or
--the group ID of the directory that contains the file, depending on the
--system where the file is stored. When you access a remote file system,
--it behaves according to its own rule, not according to the system your
--program is running on. Thus, your program must be prepared to encounter
--either kind of behavior, no matter what kind of system you run it on.
--
-- You can change the owner and/or group owner of an existing file using
--the `chown' function. This is the primitive for the `chown' and
--`chgrp' shell commands.
--
-- The prototype for this function is declared in `unistd.h'.
--
-- - Function: int chown (const char *FILENAME, uid_t OWNER, gid_t GROUP)
-- The `chown' function changes the owner of the file FILENAME to
-- OWNER, and its group owner to GROUP.
--
-- Changing the owner of the file on certain systems clears the
-- set-user-ID and set-group-ID bits of the file's permissions.
-- (This is because those bits may not be appropriate for the new
-- owner.) The other file permission bits are not changed.
--
-- The return value is `0' on success and `-1' on failure. In
-- addition to the usual file name errors (*note File Name Errors::.),
-- the following `errno' error conditions are defined for this
-- function:
--
-- `EPERM'
-- This process lacks permission to make the requested change.
--
-- Only privileged users or the file's owner can change the
-- file's group. On most file systems, only privileged users
-- can change the file owner; some file systems allow you to
-- change the owner if you are currently the owner. When you
-- access a remote file system, the behavior you encounter is
-- determined by the system that actually holds the file, not by
-- the system your program is running on.
--
-- *Note Options for Files::, for information about the
-- `_POSIX_CHOWN_RESTRICTED' macro.
--
-- `EROFS'
-- The file is on a read-only file system.
--
-- - Function: int fchown (int FILEDES, int OWNER, int GROUP)
-- This is like `chown', except that it changes the owner of the file
-- with open file descriptor FILEDES.
--
-- The return value from `fchown' is `0' on success and `-1' on
-- failure. The following `errno' error codes are defined for this
-- function:
--
-- `EBADF'
-- The FILEDES argument is not a valid file descriptor.
--
-- `EINVAL'
-- The FILEDES argument corresponds to a pipe or socket, not an
-- ordinary file.
--
-- `EPERM'
-- This process lacks permission to make the requested change.
-- For details, see `chmod', above.
--
-- `EROFS'
-- The file resides on a read-only file system.
--
--
--File: libc.info, Node: Permission Bits, Next: Access Permission, Prev:
File Owner, Up: File Attributes
--
--The Mode Bits for Access Permission
-------------------------------------
--
-- The "file mode", stored in the `st_mode' field of the file
--attributes, contains two kinds of information: the file type code, and
--the access permission bits. This section discusses only the access
--permission bits, which control who can read or write the file. *Note
--Testing File Type::, for information about the file type code.
--
-- All of the symbols listed in this section are defined in the header
--file `sys/stat.h'.
--
-- These symbolic constants are defined for the file mode bits that
--control access permission for the file:
--
--`S_IRUSR'
--`S_IREAD'
-- Read permission bit for the owner of the file. On many systems,
-- this bit is 0400. `S_IREAD' is an obsolete synonym provided for
-- BSD compatibility.
--
--`S_IWUSR'
--`S_IWRITE'
-- Write permission bit for the owner of the file. Usually 0200.
-- `S_IWRITE' is an obsolete synonym provided for BSD compatibility.
--
--`S_IXUSR'
--`S_IEXEC'
-- Execute (for ordinary files) or search (for directories)
-- permission bit for the owner of the file. Usually 0100.
-- `S_IEXEC' is an obsolete synonym provided for BSD compatibility.
--
--`S_IRWXU'
-- This is equivalent to `(S_IRUSR | S_IWUSR | S_IXUSR)'.
--
--`S_IRGRP'
-- Read permission bit for the group owner of the file. Usually 040.
--
--`S_IWGRP'
-- Write permission bit for the group owner of the file. Usually 020.
--
--`S_IXGRP'
-- Execute or search permission bit for the group owner of the file.
-- Usually 010.
--
--`S_IRWXG'
-- This is equivalent to `(S_IRGRP | S_IWGRP | S_IXGRP)'.
--
--`S_IROTH'
-- Read permission bit for other users. Usually 04.
--
--`S_IWOTH'
-- Write permission bit for other users. Usually 02.
--
--`S_IXOTH'
-- Execute or search permission bit for other users. Usually 01.
--
--`S_IRWXO'
-- This is equivalent to `(S_IROTH | S_IWOTH | S_IXOTH)'.
--
--`S_ISUID'
-- This is the set-user-ID on execute bit, usually 04000. *Note How
-- Change Persona::.
--
--`S_ISGID'
-- This is the set-group-ID on execute bit, usually 02000. *Note How
-- Change Persona::.
--
--`S_ISVTX'
-- This is the "sticky" bit, usually 01000.
--
-- On a directory, it gives permission to delete a file in the
-- directory only if you own that file. Ordinarily, a user either
-- can delete all the files in the directory or cannot delete any of
-- them (based on whether the user has write permission for the
-- directory). The same restriction applies--you must both have
-- write permission for the directory and own the file you want to
-- delete. The one exception is that the owner of the directory can
-- delete any file in the directory, no matter who owns it (provided
-- the owner has given himself write permission for the directory).
-- This is commonly used for the `/tmp' directory, where anyone may
-- create files, but not delete files created by other users.
--
-- Originally the sticky bit on an executable file modified the
-- swapping policies of the system. Normally, when a program
-- terminated, its pages in core were immediately freed and reused.
-- If the sticky bit was set on the executable file, the system kept
-- the pages in core for a while as if the program were still
-- running. This was advantageous for a program likely to be run
-- many times in succession. This usage is obsolete in modern
-- systems. When a program terminates, its pages always remain in
-- core as long as there is no shortage of memory in the system.
-- When the program is next run, its pages will still be in core if
-- no shortage arose since the last run.
--
-- On some modern systems where the sticky bit has no useful meaning
-- for an executable file, you cannot set the bit at all for a
-- non-directory. If you try, `chmod' fails with `EFTYPE'; *note
-- Setting Permissions::..
--
-- Some systems (particularly SunOS) have yet another use for the
-- sticky bit. If the sticky bit is set on a file that is *not*
-- executable, it means the opposite: never cache the pages of this
-- file at all. The main use of this is for the files on an NFS
-- server machine which are used as the swap area of diskless client
-- machines. The idea is that the pages of the file will be cached
-- in the client's memory, so it is a waste of the server's memory to
-- cache them a second time. In this use the sticky bit also says
-- that the filesystem may fail to record the file's modification
-- time onto disk reliably (the idea being that noone cares for a
-- swap file).
--
-- The actual bit values of the symbols are listed in the table above
--so you can decode file mode values when debugging your programs. These
--bit values are correct for most systems, but they are not guaranteed.
--
-- *Warning:* Writing explicit numbers for file permissions is bad
--practice. It is not only nonportable, it also requires everyone who
--reads your program to remember what the bits mean. To make your
--program clean, use the symbolic names.
--
--
--File: libc.info, Node: Access Permission, Next: Setting Permissions, Prev:
Permission Bits, Up: File Attributes
--
--How Your Access to a File is Decided
--------------------------------------
--
-- Recall that the operating system normally decides access permission
--for a file based on the effective user and group IDs of the process,
--and its supplementary group IDs, together with the file's owner, group
--and permission bits. These concepts are discussed in detail in *Note
--Process Persona::.
--
-- If the effective user ID of the process matches the owner user ID of
--the file, then permissions for read, write, and execute/search are
--controlled by the corresponding "user" (or "owner") bits. Likewise, if
--any of the effective group ID or supplementary group IDs of the process
--matches the group owner ID of the file, then permissions are controlled
--by the "group" bits. Otherwise, permissions are controlled by the
--"other" bits.
--
-- Privileged users, like `root', can access any file, regardless of
--its file permission bits. As a special case, for a file to be
--executable even for a privileged user, at least one of its execute bits
--must be set.
--
--
--File: libc.info, Node: Setting Permissions, Next: Testing File Access,
Prev: Access Permission, Up: File Attributes
--
--Assigning File Permissions
----------------------------
--
-- The primitive functions for creating files (for example, `open' or
--`mkdir') take a MODE argument, which specifies the file permissions for
--the newly created file. But the specified mode is modified by the
--process's "file creation mask", or "umask", before it is used.
--
-- The bits that are set in the file creation mask identify permissions
--that are always to be disabled for newly created files. For example, if
--you set all the "other" access bits in the mask, then newly created
--files are not accessible at all to processes in the "other" category,
--even if the MODE argument specified to the creation function would
--permit such access. In other words, the file creation mask is the
--complement of the ordinary access permissions you want to grant.
--
-- Programs that create files typically specify a MODE argument that
--includes all the permissions that make sense for the particular file.
--For an ordinary file, this is typically read and write permission for
--all classes of users. These permissions are then restricted as
--specified by the individual user's own file creation mask.
--
-- To change the permission of an existing file given its name, call
--`chmod'. This function ignores the file creation mask; it uses exactly
--the specified permission bits.
--
-- In normal use, the file creation mask is initialized in the user's
--login shell (using the `umask' shell command), and inherited by all
--subprocesses. Application programs normally don't need to worry about
--the file creation mask. It will do automatically what it is supposed to
--do.
--
-- When your program should create a file and bypass the umask for its
--access permissions, the easiest way to do this is to use `fchmod' after
--opening the file, rather than changing the umask.
--
-- In fact, changing the umask is usually done only by shells. They use
--the `umask' function.
--
-- The functions in this section are declared in `sys/stat.h'.
--
-- - Function: mode_t umask (mode_t MASK)
-- The `umask' function sets the file creation mask of the current
-- process to MASK, and returns the previous value of the file
-- creation mask.
--
-- Here is an example showing how to read the mask with `umask'
-- without changing it permanently:
--
-- mode_t
-- read_umask (void)
-- {
-- mask = umask (0);
-- umask (mask);
-- }
--
-- However, it is better to use `getumask' if you just want to read
-- the mask value, because that is reentrant (at least if you use the
-- GNU operating system).
--
-- - Function: mode_t getumask (void)
-- Return the current value of the file creation mask for the current
-- process. This function is a GNU extension.
--
-- - Function: int chmod (const char *FILENAME, mode_t MODE)
-- The `chmod' function sets the access permission bits for the file
-- named by FILENAME to MODE.
--
-- If the FILENAME names a symbolic link, `chmod' changes the
-- permission of the file pointed to by the link, not those of the
-- link itself.
--
-- This function returns `0' if successful and `-1' if not. In
-- addition to the usual file name errors (*note File Name
-- Errors::.), the following `errno' error conditions are defined for
-- this function:
--
-- `ENOENT'
-- The named file doesn't exist.
--
-- `EPERM'
-- This process does not have permission to change the access
-- permission of this file. Only the file's owner (as judged by
-- the effective user ID of the process) or a privileged user
-- can change them.
--
-- `EROFS'
-- The file resides on a read-only file system.
--
-- `EFTYPE'
-- MODE has the `S_ISVTX' bit (the "sticky bit") set, and the
-- named file is not a directory. Some systems do not allow
-- setting the sticky bit on non-directory files, and some do
-- (and only some of those assign a useful meaning to the bit
-- for non-directory files).
--
-- You only get `EFTYPE' on systems where the sticky bit has no
-- useful meaning for non-directory files, so it is always safe
-- to just clear the bit in MODE and call `chmod' again. *Note
-- Permission Bits::, for full details on the sticky bit.
--
-- - Function: int fchmod (int FILEDES, int MODE)
-- This is like `chmod', except that it changes the permissions of
-- the file currently open via descriptor FILEDES.
--
-- The return value from `fchmod' is `0' on success and `-1' on
-- failure. The following `errno' error codes are defined for this
-- function:
--
-- `EBADF'
-- The FILEDES argument is not a valid file descriptor.
--
-- `EINVAL'
-- The FILEDES argument corresponds to a pipe or socket, or
-- something else that doesn't really have access permissions.
--
-- `EPERM'
-- This process does not have permission to change the access
-- permission of this file. Only the file's owner (as judged by
-- the effective user ID of the process) or a privileged user
-- can change them.
--
-- `EROFS'
-- The file resides on a read-only file system.
--
--
--File: libc.info, Node: Testing File Access, Next: File Times, Prev:
Setting Permissions, Up: File Attributes
--
--Testing Permission to Access a File
-------------------------------------
--
-- When a program runs as a privileged user, this permits it to access
--files off-limits to ordinary users--for example, to modify
--`/etc/passwd'. Programs designed to be run by ordinary users but
--access such files use the setuid bit feature so that they always run
--with `root' as the effective user ID.
--
-- Such a program may also access files specified by the user, files
--which conceptually are being accessed explicitly by the user. Since the
--program runs as `root', it has permission to access whatever file the
--user specifies--but usually the desired behavior is to permit only
--those files which the user could ordinarily access.
--
-- The program therefore must explicitly check whether *the user* would
--have the necessary access to a file, before it reads or writes the file.
--
-- To do this, use the function `access', which checks for access
--permission based on the process's *real* user ID rather than the
--effective user ID. (The setuid feature does not alter the real user ID,
--so it reflects the user who actually ran the program.)
--
-- There is another way you could check this access, which is easy to
--describe, but very hard to use. This is to examine the file mode bits
--and mimic the system's own access computation. This method is
--undesirable because many systems have additional access control
--features; your program cannot portably mimic them, and you would not
--want to try to keep track of the diverse features that different systems
--have. Using `access' is simple and automatically does whatever is
--appropriate for the system you are using.
--
-- `access' is *only* only appropriate to use in setuid programs. A
--non-setuid program will always use the effective ID rather than the
--real ID.
--
-- The symbols in this section are declared in `unistd.h'.
--
-- - Function: int access (const char *FILENAME, int HOW)
-- The `access' function checks to see whether the file named by
-- FILENAME can be accessed in the way specified by the HOW argument.
-- The HOW argument either can be the bitwise OR of the flags
-- `R_OK', `W_OK', `X_OK', or the existence test `F_OK'.
--
-- This function uses the *real* user and group ID's of the calling
-- process, rather than the *effective* ID's, to check for access
-- permission. As a result, if you use the function from a `setuid'
-- or `setgid' program (*note How Change Persona::.), it gives
-- information relative to the user who actually ran the program.
--
-- The return value is `0' if the access is permitted, and `-1'
-- otherwise. (In other words, treated as a predicate function,
-- `access' returns true if the requested access is *denied*.)
--
-- In addition to the usual file name errors (*note File Name
-- Errors::.), the following `errno' error conditions are defined for
-- this function:
--
-- `EACCES'
-- The access specified by HOW is denied.
--
-- `ENOENT'
-- The file doesn't exist.
--
-- `EROFS'
-- Write permission was requested for a file on a read-only file
-- system.
--
-- These macros are defined in the header file `unistd.h' for use as
--the HOW argument to the `access' function. The values are integer
--constants.
--
-- - Macro: int R_OK
-- Argument that means, test for read permission.
--
-- - Macro: int W_OK
-- Argument that means, test for write permission.
--
-- - Macro: int X_OK
-- Argument that means, test for execute/search permission.
--
-- - Macro: int F_OK
-- Argument that means, test for existence of the file.
--
--
--File: libc.info, Node: File Times, Prev: Testing File Access, Up: File
Attributes
--
--File Times
------------
--
-- Each file has three timestamps associated with it: its access time,
--its modification time, and its attribute modification time. These
--correspond to the `st_atime', `st_mtime', and `st_ctime' members of the
--`stat' structure; see *Note File Attributes::.
--
-- All of these times are represented in calendar time format, as
--`time_t' objects. This data type is defined in `time.h'. For more
--information about representation and manipulation of time values, see
--*Note Calendar Time::.
--
-- Reading from a file updates its access time attribute, and writing
--updates its modification time. When a file is created, all three
--timestamps for that file are set to the current time. In addition, the
--attribute change time and modification time fields of the directory that
--contains the new entry are updated.
--
-- Adding a new name for a file with the `link' function updates the
--attribute change time field of the file being linked, and both the
--attribute change time and modification time fields of the directory
--containing the new name. These same fields are affected if a file name
--is deleted with `unlink', `remove', or `rmdir'. Renaming a file with
--`rename' affects only the attribute change time and modification time
--fields of the two parent directories involved, and not the times for
--the file being renamed.
--
-- Changing attributes of a file (for example, with `chmod') updates
--its attribute change time field.
--
-- You can also change some of the timestamps of a file explicitly using
--the `utime' function--all except the attribute change time. You need
--to include the header file `utime.h' to use this facility.
--
-- - Data Type: struct utimbuf
-- The `utimbuf' structure is used with the `utime' function to
-- specify new access and modification times for a file. It contains
-- the following members:
--
-- `time_t actime'
-- This is the access time for the file.
--
-- `time_t modtime'
-- This is the modification time for the file.
--
-- - Function: int utime (const char *FILENAME, const struct utimbuf
-- *TIMES)
-- This function is used to modify the file times associated with the
-- file named FILENAME.
--
-- If TIMES is a null pointer, then the access and modification times
-- of the file are set to the current time. Otherwise, they are set
-- to the values from the `actime' and `modtime' members
-- (respectively) of the `utimbuf' structure pointed at by TIMES.
--
-- The attribute modification time for the file is set to the current
-- time in either case (since changing the timestamps is itself a
-- modification of the file attributes).
--
-- The `utime' function returns `0' if successful and `-1' on
-- failure. In addition to the usual file name errors (*note File
-- Name Errors::.), the following `errno' error conditions are
-- defined for this function:
--
-- `EACCES'
-- There is a permission problem in the case where a null
-- pointer was passed as the TIMES argument. In order to update
-- the timestamp on the file, you must either be the owner of
-- the file, have write permission on the file, or be a
-- privileged user.
--
-- `ENOENT'
-- The file doesn't exist.
--
-- `EPERM'
-- If the TIMES argument is not a null pointer, you must either
-- be the owner of the file or be a privileged user. This error
-- is used to report the problem.
--
-- `EROFS'
-- The file lives on a read-only file system.
--
-- Each of the three time stamps has a corresponding microsecond part,
--which extends its resolution. These fields are called `st_atime_usec',
--`st_mtime_usec', and `st_ctime_usec'; each has a value between 0 and
--999,999, which indicates the time in microseconds. They correspond to
--the `tv_usec' field of a `timeval' structure; see *Note High-Resolution
--Calendar::.
--
-- The `utimes' function is like `utime', but also lets you specify the
--fractional part of the file times. The prototype for this function is
--in the header file `sys/time.h'.
--
-- - Function: int utimes (const char *FILENAME, struct timeval TVP[2])
-- This function sets the file access and modification times for the
-- file named by FILENAME. The new file access time is specified by
-- `TVP[0]', and the new modification time by `TVP[1]'. This
-- function comes from BSD.
--
-- The return values and error conditions are the same as for the
-- `utime' function.
--
--
--File: libc.info, Node: Making Special Files, Next: Temporary Files, Prev:
File Attributes, Up: File System Interface
--
--Making Special Files
--====================
--
-- The `mknod' function is the primitive for making special files, such
--as files that correspond to devices. The GNU library includes this
--function for compatibility with BSD.
--
-- The prototype for `mknod' is declared in `sys/stat.h'.
--
-- - Function: int mknod (const char *FILENAME, int MODE, int DEV)
-- The `mknod' function makes a special file with name FILENAME. The
-- MODE specifies the mode of the file, and may include the various
-- special file bits, such as `S_IFCHR' (for a character special file)
-- or `S_IFBLK' (for a block special file). *Note Testing File
-- Type::.
--
-- The DEV argument specifies which device the special file refers to.
-- Its exact interpretation depends on the kind of special file being
-- created.
--
-- The return value is `0' on success and `-1' on error. In addition
-- to the usual file name errors (*note File Name Errors::.), the
-- following `errno' error conditions are defined for this function:
--
-- `EPERM'
-- The calling process is not privileged. Only the superuser
-- can create special files.
--
-- `ENOSPC'
-- The directory or file system that would contain the new file
-- is full and cannot be extended.
--
-- `EROFS'
-- The directory containing the new file can't be modified
-- because it's on a read-only file system.
--
-- `EEXIST'
-- There is already a file named FILENAME. If you want to
-- replace this file, you must remove the old file explicitly
-- first.
--
--
--File: libc.info, Node: Temporary Files, Prev: Making Special Files, Up:
File System Interface
--
--Temporary Files
--===============
--
-- If you need to use a temporary file in your program, you can use the
--`tmpfile' function to open it. Or you can use the `tmpnam' (better:
--`tmpnam_r') function make a name for a temporary file and then open it
--in the usual way with `fopen'.
--
-- The `tempnam' function is like `tmpnam' but lets you choose what
--directory temporary files will go in, and something about what their
--file names will look like. Important for multi threaded programs is
--that `tempnam' is reentrant while `tmpnam' is not since it returns a
--pointer to a static buffer.
--
-- These facilities are declared in the header file `stdio.h'.
--
-- - Function: FILE * tmpfile (void)
-- This function creates a temporary binary file for update mode, as
-- if by calling `fopen' with mode `"wb+"'. The file is deleted
-- automatically when it is closed or when the program terminates.
-- (On some other ISO C systems the file may fail to be deleted if
-- the program terminates abnormally).
--
-- This function is reentrant.
--
-- - Function: char * tmpnam (char *RESULT)
-- This function constructs and returns a file name that is a valid
-- file name and that does not name any existing file. If the RESULT
-- argument is a null pointer, the return value is a pointer to an
-- internal static string, which might be modified by subsequent
-- calls and therefore makes this function non-reentrant. Otherwise,
-- the RESULT argument should be a pointer to an array of at least
-- `L_tmpnam' characters, and the result is written into that array.
--
-- It is possible for `tmpnam' to fail if you call it too many times
-- without removing previously created files. This is because the
-- fixed length of a temporary file name gives room for only a finite
-- number of different names. If `tmpnam' fails, it returns a null
-- pointer.
--
-- - Function: char * tmpnam_r (char *RESULT)
-- This function is nearly identical to the `tmpnam' function. But it
-- does not allow RESULT to be a null pointer. In the later case a
-- null pointer is returned.
--
-- This function is reentrant because the non-reentrant situation of
-- `tmpnam' cannot happen here.
--
-- - Macro: int L_tmpnam
-- The value of this macro is an integer constant expression that
-- represents the minimum allocation size of a string large enough to
-- hold the file name generated by the `tmpnam' function.
--
-- - Macro: int TMP_MAX
-- The macro `TMP_MAX' is a lower bound for how many temporary names
-- you can create with `tmpnam'. You can rely on being able to call
-- `tmpnam' at least this many times before it might fail saying you
-- have made too many temporary file names.
--
-- With the GNU library, you can create a very large number of
-- temporary file names--if you actually create the files, you will
-- probably run out of disk space before you run out of names. Some
-- other systems have a fixed, small limit on the number of temporary
-- files. The limit is never less than `25'.
--
-- - Function: char * tempnam (const char *DIR, const char *PREFIX)
-- This function generates a unique temporary filename. If PREFIX is
-- not a null pointer, up to five characters of this string are used
-- as a prefix for the file name. The return value is a string newly
-- allocated with `malloc'; you should release its storage with
-- `free' when it is no longer needed.
--
-- Because the string is dynamically allocated this function is
-- reentrant.
--
-- The directory prefix for the temporary file name is determined by
-- testing each of the following, in sequence. The directory must
-- exist and be writable.
--
-- * The environment variable `TMPDIR', if it is defined. For
-- security reasons this only happens if the program is not SUID
-- or SGID enabled.
--
-- * The DIR argument, if it is not a null pointer.
--
-- * The value of the `P_tmpdir' macro.
--
-- * The directory `/tmp'.
--
-- This function is defined for SVID compatibility.
--
-- - SVID Macro: char * P_tmpdir
-- This macro is the name of the default directory for temporary
-- files.
--
-- Older Unix systems did not have the functions just described.
--Instead they used `mktemp' and `mkstemp'. Both of these functions work
--by modifying a file name template string you pass. The last six
--characters of this string must be `XXXXXX'. These six `X's are
--replaced with six characters which make the whole string a unique file
--name. Usually the template string is something like
--`/tmp/PREFIXXXXXXX', and each program uses a unique PREFIX.
--
-- *Note:* Because `mktemp' and `mkstemp' modify the template string,
--you *must not* pass string constants to them. String constants are
--normally in read-only storage, so your program would crash when
--`mktemp' or `mkstemp' tried to modify the string.
--
-- - Function: char * mktemp (char *TEMPLATE)
-- The `mktemp' function generates a unique file name by modifying
-- TEMPLATE as described above. If successful, it returns TEMPLATE
-- as modified. If `mktemp' cannot find a unique file name, it makes
-- TEMPLATE an empty string and returns that. If TEMPLATE does not
-- end with `XXXXXX', `mktemp' returns a null pointer.
--
-- - Function: int mkstemp (char *TEMPLATE)
-- The `mkstemp' function generates a unique file name just as
-- `mktemp' does, but it also opens the file for you with `open'
-- (*note Opening and Closing Files::.). If successful, it modifies
-- TEMPLATE in place and returns a file descriptor open on that file
-- for reading and writing. If `mkstemp' cannot create a
-- uniquely-named file, it makes TEMPLATE an empty string and returns
-- `-1'. If TEMPLATE does not end with `XXXXXX', `mkstemp' returns
-- `-1' and does not modify TEMPLATE.
--
-- Unlike `mktemp', `mkstemp' is actually guaranteed to create a unique
--file that cannot possibly clash with any other program trying to create
--a temporary file. This is because it works by calling `open' with the
--`O_EXCL' flag bit, which says you want to always create a new file, and
--get an error if the file already exists.
--
--
--File: libc.info, Node: Pipes and FIFOs, Next: Sockets, Prev: File System
Interface, Up: Top
--
--Pipes and FIFOs
--***************
--
-- A "pipe" is a mechanism for interprocess communication; data written
--to the pipe by one process can be read by another process. The data is
--handled in a first-in, first-out (FIFO) order. The pipe has no name; it
--is created for one use and both ends must be inherited from the single
--process which created the pipe.
--
-- A "FIFO special file" is similar to a pipe, but instead of being an
--anonymous, temporary connection, a FIFO has a name or names like any
--other file. Processes open the FIFO by name in order to communicate
--through it.
--
-- A pipe or FIFO has to be open at both ends simultaneously. If you
--read from a pipe or FIFO file that doesn't have any processes writing
--to it (perhaps because they have all closed the file, or exited), the
--read returns end-of-file. Writing to a pipe or FIFO that doesn't have a
--reading process is treated as an error condition; it generates a
--`SIGPIPE' signal, and fails with error code `EPIPE' if the signal is
--handled or blocked.
--
-- Neither pipes nor FIFO special files allow file positioning. Both
--reading and writing operations happen sequentially; reading from the
--beginning of the file and writing at the end.
--
--* Menu:
--
--* Creating a Pipe:: Making a pipe with the `pipe' function.
--* Pipe to a Subprocess:: Using a pipe to communicate with a
-- child process.
--* FIFO Special Files:: Making a FIFO special file.
--* Pipe Atomicity:: When pipe (or FIFO) I/O is atomic.
--
--
--File: libc.info, Node: Creating a Pipe, Next: Pipe to a Subprocess, Up:
Pipes and FIFOs
--
--Creating a Pipe
--===============
--
-- The primitive for creating a pipe is the `pipe' function. This
--creates both the reading and writing ends of the pipe. It is not very
--useful for a single process to use a pipe to talk to itself. In typical
--use, a process creates a pipe just before it forks one or more child
--processes (*note Creating a Process::.). The pipe is then used for
--communication either between the parent or child processes, or between
--two sibling processes.
--
-- The `pipe' function is declared in the header file `unistd.h'.
--
-- - Function: int pipe (int FILEDES[2])
-- The `pipe' function creates a pipe and puts the file descriptors
-- for the reading and writing ends of the pipe (respectively) into
-- `FILEDES[0]' and `FILEDES[1]'.
--
-- An easy way to remember that the input end comes first is that file
-- descriptor `0' is standard input, and file descriptor `1' is
-- standard output.
--
-- If successful, `pipe' returns a value of `0'. On failure, `-1' is
-- returned. The following `errno' error conditions are defined for
-- this function:
--
-- `EMFILE'
-- The process has too many files open.
--
-- `ENFILE'
-- There are too many open files in the entire system. *Note
-- Error Codes::, for more information about `ENFILE'. This
-- error never occurs in the GNU system.
--
-- Here is an example of a simple program that creates a pipe. This
--program uses the `fork' function (*note Creating a Process::.) to create
--a child process. The parent process writes data to the pipe, which is
--read by the child process.
--
-- #include <sys/types.h>
-- #include <unistd.h>
-- #include <stdio.h>
-- #include <stdlib.h>
--
-- /* Read characters from the pipe and echo them to `stdout'. */
--
-- void
-- read_from_pipe (int file)
-- {
-- FILE *stream;
-- int c;
-- stream = fdopen (file, "r");
-- while ((c = fgetc (stream)) != EOF)
-- putchar (c);
-- fclose (stream);
-- }
--
-- /* Write some random text to the pipe. */
--
-- void
-- write_to_pipe (int file)
-- {
-- FILE *stream;
-- stream = fdopen (file, "w");
-- fprintf (stream, "hello, world!\n");
-- fprintf (stream, "goodbye, world!\n");
-- fclose (stream);
-- }
--
-- int
-- main (void)
-- {
-- pid_t pid;
-- int mypipe[2];
-- /* Create the pipe. */
-- if (pipe (mypipe))
-- {
-- fprintf (stderr, "Pipe failed.\n");
-- return EXIT_FAILURE;
-- }
--
-- /* Create the child process. */
-- pid = fork ();
-- if (pid == (pid_t) 0)
-- {
-- /* This is the child process. */
-- read_from_pipe (mypipe[0]);
-- return EXIT_SUCCESS;
-- }
-- else if (pid < (pid_t) 0)
-- {
-- /* The fork failed. */
-- fprintf (stderr, "Fork failed.\n");
-- return EXIT_FAILURE;
-- }
-- else
-- {
-- /* This is the parent process. */
-- write_to_pipe (mypipe[1]);
-- return EXIT_SUCCESS;
-- }
-- }
--
--
--File: libc.info, Node: Pipe to a Subprocess, Next: FIFO Special Files,
Prev: Creating a Pipe, Up: Pipes and FIFOs
--
--Pipe to a Subprocess
--====================
--
-- A common use of pipes is to send data to or receive data from a
--program being run as subprocess. One way of doing this is by using a
--combination of `pipe' (to create the pipe), `fork' (to create the
--subprocess), `dup2' (to force the subprocess to use the pipe as its
--standard input or output channel), and `exec' (to execute the new
--program). Or, you can use `popen' and `pclose'.
--
-- The advantage of using `popen' and `pclose' is that the interface is
--much simpler and easier to use. But it doesn't offer as much
--flexibility as using the low-level functions directly.
--
-- - Function: FILE * popen (const char *COMMAND, const char *MODE)
-- The `popen' function is closely related to the `system' function;
-- see *Note Running a Command::. It executes the shell command
-- COMMAND as a subprocess. However, instead of waiting for the
-- command to complete, it creates a pipe to the subprocess and
-- returns a stream that corresponds to that pipe.
--
-- If you specify a MODE argument of `"r"', you can read from the
-- stream to retrieve data from the standard output channel of the
-- subprocess. The subprocess inherits its standard input channel
-- from the parent process.
--
-- Similarly, if you specify a MODE argument of `"w"', you can write
-- to the stream to send data to the standard input channel of the
-- subprocess. The subprocess inherits its standard output channel
-- from the parent process.
--
-- In the event of an error, `popen' returns a null pointer. This
-- might happen if the pipe or stream cannot be created, if the
-- subprocess cannot be forked, or if the program cannot be executed.
--
-- - Function: int pclose (FILE *STREAM)
-- The `pclose' function is used to close a stream created by `popen'.
-- It waits for the child process to terminate and returns its status
-- value, as for the `system' function.
--
-- Here is an example showing how to use `popen' and `pclose' to filter
--output through another program, in this case the paging program `more'.
--
-- #include <stdio.h>
-- #include <stdlib.h>
--
-- void
-- write_data (FILE * stream)
-- {
-- int i;
-- for (i = 0; i < 100; i++)
-- fprintf (stream, "%d\n", i);
-- if (ferror (stream))
-- {
-- fprintf (stderr, "Output to stream failed.\n");
-- exit (EXIT_FAILURE);
-- }
-- }
-- int
-- main (void)
-- {
-- FILE *output;
--
-- output = popen ("more", "w");
-- if (!output)
-- {
-- fprintf (stderr, "Could not run more.\n");
-- return EXIT_FAILURE;
-- }
-- write_data (output);
-- pclose (output);
-- return EXIT_SUCCESS;
-- }
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-12
glibc-2.0.1/manual/libc.info-12
---- ../glibc-2.0.1/manual/libc.info-12 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-12 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1219 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: FIFO Special Files, Next: Pipe Atomicity, Prev:
Pipe to a Subprocess, Up: Pipes and FIFOs
--
--FIFO Special Files
--==================
--
-- A FIFO special file is similar to a pipe, except that it is created
--in a different way. Instead of being an anonymous communications
--channel, a FIFO special file is entered into the file system by calling
--`mkfifo'.
--
-- Once you have created a FIFO special file in this way, any process
--can open it for reading or writing, in the same way as an ordinary file.
--However, it has to be open at both ends simultaneously before you can
--proceed to do any input or output operations on it. Opening a FIFO for
--reading normally blocks until some other process opens the same FIFO for
--writing, and vice versa.
--
-- The `mkfifo' function is declared in the header file `sys/stat.h'.
--
-- - Function: int mkfifo (const char *FILENAME, mode_t MODE)
-- The `mkfifo' function makes a FIFO special file with name
-- FILENAME. The MODE argument is used to set the file's
-- permissions; see *Note Setting Permissions::.
--
-- The normal, successful return value from `mkfifo' is `0'. In the
-- case of an error, `-1' is returned. In addition to the usual file
-- name errors (*note File Name Errors::.), the following `errno'
-- error conditions are defined for this function:
--
-- `EEXIST'
-- The named file already exists.
--
-- `ENOSPC'
-- The directory or file system cannot be extended.
--
-- `EROFS'
-- The directory that would contain the file resides on a
-- read-only file system.
--
--
--File: libc.info, Node: Pipe Atomicity, Prev: FIFO Special Files, Up: Pipes
and FIFOs
--
--Atomicity of Pipe I/O
--=====================
--
-- Reading or writing pipe data is "atomic" if the size of data written
--is not greater than `PIPE_BUF'. This means that the data transfer
--seems to be an instantaneous unit, in that nothing else in the system
--can observe a state in which it is partially complete. Atomic I/O may
--not begin right away (it may need to wait for buffer space or for data),
--but once it does begin, it finishes immediately.
--
-- Reading or writing a larger amount of data may not be atomic; for
--example, output data from other processes sharing the descriptor may be
--interspersed. Also, once `PIPE_BUF' characters have been written,
--further writes will block until some characters are read.
--
-- *Note Limits for Files::, for information about the `PIPE_BUF'
--parameter.
--
--
--File: libc.info, Node: Sockets, Next: Low-Level Terminal Interface, Prev:
Pipes and FIFOs, Up: Top
--
--Sockets
--*******
--
-- This chapter describes the GNU facilities for interprocess
--communication using sockets.
--
-- A "socket" is a generalized interprocess communication channel.
--Like a pipe, a socket is represented as a file descriptor. But, unlike
--pipes, sockets support communication between unrelated processes, and
--even between processes running on different machines that communicate
--over a network. Sockets are the primary means of communicating with
--other machines; `telnet', `rlogin', `ftp', `talk', and the other
--familiar network programs use sockets.
--
-- Not all operating systems support sockets. In the GNU library, the
--header file `sys/socket.h' exists regardless of the operating system,
--and the socket functions always exist, but if the system does not
--really support sockets, these functions always fail.
--
-- *Incomplete:* We do not currently document the facilities for
--broadcast messages or for configuring Internet interfaces.
--
--* Menu:
--
--* Socket Concepts:: Basic concepts you need to know about.
--* Communication Styles::Stream communication, datagrams, and other styles.
--* Socket Addresses:: How socket names ("addresses") work.
--* File Namespace:: Details about the file namespace.
--* Internet Namespace:: Details about the Internet namespace.
--* Misc Namespaces:: Other namespaces not documented fully here.
--* Open/Close Sockets:: Creating sockets and destroying them.
--* Connections:: Operations on sockets with connection state.
--* Datagrams:: Operations on datagram sockets.
--* Inetd:: Inetd is a daemon that starts servers on request.
-- The most convenient way to write a server
-- is to make it work with Inetd.
--* Socket Options:: Miscellaneous low-level socket options.
--* Networks Database:: Accessing the database of network names.
--
--
--File: libc.info, Node: Socket Concepts, Next: Communication Styles, Up:
Sockets
--
--Socket Concepts
--===============
--
-- When you create a socket, you must specify the style of communication
--you want to use and the type of protocol that should implement it. The
--"communication style" of a socket defines the user-level semantics of
--sending and receiving data on the socket. Choosing a communication
--style specifies the answers to questions such as these:
--
-- * *What are the units of data transmission?* Some communication
-- styles regard the data as a sequence of bytes, with no larger
-- structure; others group the bytes into records (which are known in
-- this context as "packets").
--
-- * *Can data be lost during normal operation?* Some communication
-- styles guarantee that all the data sent arrives in the order it was
-- sent (barring system or network crashes); other styles occasionally
-- lose data as a normal part of operation, and may sometimes deliver
-- packets more than once or in the wrong order.
--
-- Designing a program to use unreliable communication styles usually
-- involves taking precautions to detect lost or misordered packets
-- and to retransmit data as needed.
--
-- * *Is communication entirely with one partner?* Some communication
-- styles are like a telephone call--you make a "connection" with one
-- remote socket, and then exchange data freely. Other styles are
-- like mailing letters--you specify a destination address for each
-- message you send.
--
-- You must also choose a "namespace" for naming the socket. A socket
--name ("address") is meaningful only in the context of a particular
--namespace. In fact, even the data type to use for a socket name may
--depend on the namespace. Namespaces are also called "domains", but we
--avoid that word as it can be confused with other usage of the same
--term. Each namespace has a symbolic name that starts with `PF_'. A
--corresponding symbolic name starting with `AF_' designates the address
--format for that namespace.
--
-- Finally you must choose the "protocol" to carry out the
--communication. The protocol determines what low-level mechanism is used
--to transmit and receive data. Each protocol is valid for a particular
--namespace and communication style; a namespace is sometimes called a
--"protocol family" because of this, which is why the namespace names
--start with `PF_'.
--
-- The rules of a protocol apply to the data passing between two
--programs, perhaps on different computers; most of these rules are
--handled by the operating system, and you need not know about them.
--What you do need to know about protocols is this:
--
-- * In order to have communication between two sockets, they must
-- specify the *same* protocol.
--
-- * Each protocol is meaningful with particular style/namespace
-- combinations and cannot be used with inappropriate combinations.
-- For example, the TCP protocol fits only the byte stream style of
-- communication and the Internet namespace.
--
-- * For each combination of style and namespace, there is a "default
-- protocol" which you can request by specifying 0 as the protocol
-- number. And that's what you should normally do--use the default.
--
--
--File: libc.info, Node: Communication Styles, Next: Socket Addresses, Prev:
Socket Concepts, Up: Sockets
--
--Communication Styles
--====================
--
-- The GNU library includes support for several different kinds of
--sockets, each with different characteristics. This section describes
--the supported socket types. The symbolic constants listed here are
--defined in `sys/socket.h'.
--
-- - Macro: int SOCK_STREAM
-- The `SOCK_STREAM' style is like a pipe (*note Pipes and FIFOs::.);
-- it operates over a connection with a particular remote socket, and
-- transmits data reliably as a stream of bytes.
--
-- Use of this style is covered in detail in *Note Connections::.
--
-- - Macro: int SOCK_DGRAM
-- The `SOCK_DGRAM' style is used for sending individually-addressed
-- packets, unreliably. It is the diametrical opposite of
-- `SOCK_STREAM'.
--
-- Each time you write data to a socket of this kind, that data
-- becomes one packet. Since `SOCK_DGRAM' sockets do not have
-- connections, you must specify the recipient address with each
-- packet.
--
-- The only guarantee that the system makes about your requests to
-- transmit data is that it will try its best to deliver each packet
-- you send. It may succeed with the sixth packet after failing with
-- the fourth and fifth packets; the seventh packet may arrive before
-- the sixth, and may arrive a second time after the sixth.
--
-- The typical use for `SOCK_DGRAM' is in situations where it is
-- acceptable to simply resend a packet if no response is seen in a
-- reasonable amount of time.
--
-- *Note Datagrams::, for detailed information about how to use
-- datagram sockets.
--
-- - Macro: int SOCK_RAW
-- This style provides access to low-level network protocols and
-- interfaces. Ordinary user programs usually have no need to use
-- this style.
--
--
--File: libc.info, Node: Socket Addresses, Next: File Namespace, Prev:
Communication Styles, Up: Sockets
--
--Socket Addresses
--================
--
-- The name of a socket is normally called an "address". The functions
--and symbols for dealing with socket addresses were named
--inconsistently, sometimes using the term "name" and sometimes using
--"address". You can regard these terms as synonymous where sockets are
--concerned.
--
-- A socket newly created with the `socket' function has no address.
--Other processes can find it for communication only if you give it an
--address. We call this "binding" the address to the socket, and the way
--to do it is with the `bind' function.
--
-- You need be concerned with the address of a socket if other processes
--are to find it and start communicating with it. You can specify an
--address for other sockets, but this is usually pointless; the first time
--you send data from a socket, or use it to initiate a connection, the
--system assigns an address automatically if you have not specified one.
--
-- Occasionally a client needs to specify an address because the server
--discriminates based on addresses; for example, the rsh and rlogin
--protocols look at the client's socket address and don't bypass password
--checking unless it is less than `IPPORT_RESERVED' (*note Ports::.).
--
-- The details of socket addresses vary depending on what namespace you
--are using. *Note File Namespace::, or *Note Internet Namespace::, for
--specific information.
--
-- Regardless of the namespace, you use the same functions `bind' and
--`getsockname' to set and examine a socket's address. These functions
--use a phony data type, `struct sockaddr *', to accept the address. In
--practice, the address lives in a structure of some other data type
--appropriate to the address format you are using, but you cast its
--address to `struct sockaddr *' when you pass it to `bind'.
--
--* Menu:
--
--* Address Formats:: About `struct sockaddr'.
--* Setting Address:: Binding an address to a socket.
--* Reading Address:: Reading the address of a socket.
--
--
--File: libc.info, Node: Address Formats, Next: Setting Address, Up: Socket
Addresses
--
--Address Formats
-----------------
--
-- The functions `bind' and `getsockname' use the generic data type
--`struct sockaddr *' to represent a pointer to a socket address. You
--can't use this data type effectively to interpret an address or
--construct one; for that, you must use the proper data type for the
--socket's namespace.
--
-- Thus, the usual practice is to construct an address in the proper
--namespace-specific type, then cast a pointer to `struct sockaddr *'
--when you call `bind' or `getsockname'.
--
-- The one piece of information that you can get from the `struct
--sockaddr' data type is the "address format" designator which tells you
--which data type to use to understand the address fully.
--
-- The symbols in this section are defined in the header file
--`sys/socket.h'.
--
-- - Date Type: struct sockaddr
-- The `struct sockaddr' type itself has the following members:
--
-- `short int sa_family'
-- This is the code for the address format of this address. It
-- identifies the format of the data which follows.
--
-- `char sa_data[14]'
-- This is the actual socket address data, which is
-- format-dependent. Its length also depends on the format, and
-- may well be more than 14. The length 14 of `sa_data' is
-- essentially arbitrary.
--
-- Each address format has a symbolic name which starts with `AF_'.
--Each of them corresponds to a `PF_' symbol which designates the
--corresponding namespace. Here is a list of address format names:
--
--`AF_FILE'
-- This designates the address format that goes with the file
-- namespace. (`PF_FILE' is the name of that namespace.) *Note File
-- Namespace Details::, for information about this address format.
--
--`AF_UNIX'
-- This is a synonym for `AF_FILE', for compatibility. (`PF_UNIX' is
-- likewise a synonym for `PF_FILE'.)
--
--`AF_INET'
-- This designates the address format that goes with the Internet
-- namespace. (`PF_INET' is the name of that namespace.) *Note
-- Internet Address Format::.
--
--`AF_UNSPEC'
-- This designates no particular address format. It is used only in
-- rare cases, such as to clear out the default destination address
-- of a "connected" datagram socket. *Note Sending Datagrams::.
--
-- The corresponding namespace designator symbol `PF_UNSPEC' exists
-- for completeness, but there is no reason to use it in a program.
--
-- `sys/socket.h' defines symbols starting with `AF_' for many
--different kinds of networks, all or most of which are not actually
--implemented. We will document those that really work, as we receive
--information about how to use them.
--
--
--File: libc.info, Node: Setting Address, Next: Reading Address, Prev:
Address Formats, Up: Socket Addresses
--
--Setting the Address of a Socket
---------------------------------
--
-- Use the `bind' function to assign an address to a socket. The
--prototype for `bind' is in the header file `sys/socket.h'. For
--examples of use, see *Note File Namespace::, or see *Note Inet
--Example::.
--
-- - Function: int bind (int SOCKET, struct sockaddr *ADDR, size_t LENGTH)
-- The `bind' function assigns an address to the socket SOCKET. The
-- ADDR and LENGTH arguments specify the address; the detailed format
-- of the address depends on the namespace. The first part of the
-- address is always the format designator, which specifies a
-- namespace, and says that the address is in the format for that
-- namespace.
--
-- The return value is `0' on success and `-1' on failure. The
-- following `errno' error conditions are defined for this function:
--
-- `EBADF'
-- The SOCKET argument is not a valid file descriptor.
--
-- `ENOTSOCK'
-- The descriptor SOCKET is not a socket.
--
-- `EADDRNOTAVAIL'
-- The specified address is not available on this machine.
--
-- `EADDRINUSE'
-- Some other socket is already using the specified address.
--
-- `EINVAL'
-- The socket SOCKET already has an address.
--
-- `EACCES'
-- You do not have permission to access the requested address.
-- (In the Internet domain, only the super-user is allowed to
-- specify a port number in the range 0 through
-- `IPPORT_RESERVED' minus one; see *Note Ports::.)
--
-- Additional conditions may be possible depending on the particular
-- namespace of the socket.
--
--
--File: libc.info, Node: Reading Address, Prev: Setting Address, Up: Socket
Addresses
--
--Reading the Address of a Socket
---------------------------------
--
-- Use the function `getsockname' to examine the address of an Internet
--socket. The prototype for this function is in the header file
--`sys/socket.h'.
--
-- - Function: int getsockname (int SOCKET, struct sockaddr *ADDR, size_t
-- *LENGTH-PTR)
-- The `getsockname' function returns information about the address
-- of the socket SOCKET in the locations specified by the ADDR and
-- LENGTH-PTR arguments. Note that the LENGTH-PTR is a pointer; you
-- should initialize it to be the allocation size of ADDR, and on
-- return it contains the actual size of the address data.
--
-- The format of the address data depends on the socket namespace.
-- The length of the information is usually fixed for a given
-- namespace, so normally you can know exactly how much space is
-- needed and can provide that much. The usual practice is to
-- allocate a place for the value using the proper data type for the
-- socket's namespace, then cast its address to `struct sockaddr *'
-- to pass it to `getsockname'.
--
-- The return value is `0' on success and `-1' on error. The
-- following `errno' error conditions are defined for this function:
--
-- `EBADF'
-- The SOCKET argument is not a valid file descriptor.
--
-- `ENOTSOCK'
-- The descriptor SOCKET is not a socket.
--
-- `ENOBUFS'
-- There are not enough internal buffers available for the
-- operation.
--
-- You can't read the address of a socket in the file namespace. This
--is consistent with the rest of the system; in general, there's no way to
--find a file's name from a descriptor for that file.
--
--
--File: libc.info, Node: File Namespace, Next: Internet Namespace, Prev:
Socket Addresses, Up: Sockets
--
--The File Namespace
--==================
--
-- This section describes the details of the file namespace, whose
--symbolic name (required when you create a socket) is `PF_FILE'.
--
--* Menu:
--
--* Concepts: File Namespace Concepts. What you need to understand.
--* Details: File Namespace Details. Address format, symbolic names, etc.
--* Example: File Socket Example. Example of creating a socket.
--
--
--File: libc.info, Node: File Namespace Concepts, Next: File Namespace
Details, Up: File Namespace
--
--File Namespace Concepts
-------------------------
--
-- In the file namespace, socket addresses are file names. You can
--specify any file name you want as the address of the socket, but you
--must have write permission on the directory containing it. In order to
--connect to a socket, you must have read permission for it. It's common
--to put these files in the `/tmp' directory.
--
-- One peculiarity of the file namespace is that the name is only used
--when opening the connection; once that is over with, the address is not
--meaningful and may not exist.
--
-- Another peculiarity is that you cannot connect to such a socket from
--another machine-not even if the other machine shares the file system
--which contains the name of the socket. You can see the socket in a
--directory listing, but connecting to it never succeeds. Some programs
--take advantage of this, such as by asking the client to send its own
--process ID, and using the process IDs to distinguish between clients.
--However, we recommend you not use this method in protocols you design,
--as we might someday permit connections from other machines that mount
--the same file systems. Instead, send each new client an identifying
--number if you want it to have one.
--
-- After you close a socket in the file namespace, you should delete the
--file name from the file system. Use `unlink' or `remove' to do this;
--see *Note Deleting Files::.
--
-- The file namespace supports just one protocol for any communication
--style; it is protocol number `0'.
--
--
--File: libc.info, Node: File Namespace Details, Next: File Socket Example,
Prev: File Namespace Concepts, Up: File Namespace
--
--Details of File Namespace
---------------------------
--
-- To create a socket in the file namespace, use the constant `PF_FILE'
--as the NAMESPACE argument to `socket' or `socketpair'. This constant
--is defined in `sys/socket.h'.
--
-- - Macro: int PF_FILE
-- This designates the file namespace, in which socket addresses are
-- file names, and its associated family of protocols.
--
-- - Macro: int PF_UNIX
-- This is a synonym for `PF_FILE', for compatibility's sake.
--
-- The structure for specifying socket names in the file namespace is
--defined in the header file `sys/un.h':
--
-- - Data Type: struct sockaddr_un
-- This structure is used to specify file namespace socket addresses.
-- It has the following members:
--
-- `short int sun_family'
-- This identifies the address family or format of the socket
-- address. You should store the value `AF_FILE' to designate
-- the file namespace. *Note Socket Addresses::.
--
-- `char sun_path[108]'
-- This is the file name to use.
--
-- *Incomplete:* Why is 108 a magic number? RMS suggests making
-- this a zero-length array and tweaking the example following
-- to use `alloca' to allocate an appropriate amount of storage
-- based on the length of the filename.
--
-- You should compute the LENGTH parameter for a socket address in the
--file namespace as the sum of the size of the `sun_family' component and
--the string length (*not* the allocation size!) of the file name string.
--
--
--File: libc.info, Node: File Socket Example, Prev: File Namespace Details,
Up: File Namespace
--
--Example of File-Namespace Sockets
-----------------------------------
--
-- Here is an example showing how to create and name a socket in the
--file namespace.
--
-- #include <stddef.h>
-- #include <stdio.h>
-- #include <errno.h>
-- #include <stdlib.h>
-- #include <sys/socket.h>
-- #include <sys/un.h>
--
-- int
-- make_named_socket (const char *filename)
-- {
-- struct sockaddr_un name;
-- int sock;
-- size_t size;
--
-- /* Create the socket. */
--
-- sock = socket (PF_UNIX, SOCK_DGRAM, 0);
-- if (sock < 0)
-- {
-- perror ("socket");
-- exit (EXIT_FAILURE);
-- }
--
-- /* Bind a name to the socket. */
--
-- name.sun_family = AF_FILE;
-- strcpy (name.sun_path, filename);
--
-- /* The size of the address is
-- the offset of the start of the filename,
-- plus its length,
-- plus one for the terminating null byte. */
-- size = (offsetof (struct sockaddr_un, sun_path)
-- + strlen (name.sun_path) + 1);
--
-- if (bind (sock, (struct sockaddr *) &name, size) < 0)
-- {
-- perror ("bind");
-- exit (EXIT_FAILURE);
-- }
--
-- return sock;
-- }
--
--
--File: libc.info, Node: Internet Namespace, Next: Misc Namespaces, Prev:
File Namespace, Up: Sockets
--
--The Internet Namespace
--======================
--
-- This section describes the details the protocols and socket naming
--conventions used in the Internet namespace.
--
-- To create a socket in the Internet namespace, use the symbolic name
--`PF_INET' of this namespace as the NAMESPACE argument to `socket' or
--`socketpair'. This macro is defined in `sys/socket.h'.
--
-- - Macro: int PF_INET
-- This designates the Internet namespace and associated family of
-- protocols.
--
-- A socket address for the Internet namespace includes the following
--components:
--
-- * The address of the machine you want to connect to. Internet
-- addresses can be specified in several ways; these are discussed in
-- *Note Internet Address Format::, *Note Host Addresses::, and *Note
-- Host Names::.
--
-- * A port number for that machine. *Note Ports::.
--
-- You must ensure that the address and port number are represented in a
--canonical format called "network byte order". *Note Byte Order::, for
--information about this.
--
--* Menu:
--
--* Internet Address Format:: How socket addresses are specified in the
-- Internet namespace.
--* Host Addresses:: All about host addresses of internet host.
--* Protocols Database:: Referring to protocols by name.
--* Ports:: Internet port numbers.
--* Services Database:: Ports may have symbolic names.
--* Byte Order:: Different hosts may use different byte
-- ordering conventions; you need to
-- canonicalize host address and port number.
--* Inet Example:: Putting it all together.
--
--
--File: libc.info, Node: Internet Address Format, Next: Host Addresses, Up:
Internet Namespace
--
--Internet Socket Address Format
--------------------------------
--
-- In the Internet namespace, a socket address consists of a host
--address and a port on that host. In addition, the protocol you choose
--serves effectively as a part of the address because local port numbers
--are meaningful only within a particular protocol.
--
-- The data type for representing socket addresses in the Internet
--namespace is defined in the header file `netinet/in.h'.
--
-- - Data Type: struct sockaddr_in
-- This is the data type used to represent socket addresses in the
-- Internet namespace. It has the following members:
--
-- `short int sin_family'
-- This identifies the address family or format of the socket
-- address. You should store the value of `AF_INET' in this
-- member. *Note Socket Addresses::.
--
-- `struct in_addr sin_addr'
-- This is the Internet address of the host machine. *Note Host
-- Addresses::, and *Note Host Names::, for how to get a value
-- to store here.
--
-- `unsigned short int sin_port'
-- This is the port number. *Note Ports::.
--
-- When you call `bind' or `getsockname', you should specify `sizeof
--(struct sockaddr_in)' as the LENGTH parameter if you are using an
--Internet namespace socket address.
--
--
--File: libc.info, Node: Host Addresses, Next: Protocols Database, Prev:
Internet Address Format, Up: Internet Namespace
--
--Host Addresses
----------------
--
-- Each computer on the Internet has one or more "Internet addresses",
--numbers which identify that computer among all those on the Internet.
--Users typically write numeric host addresses as sequences of four
--numbers, separated by periods, as in `128.52.46.32'.
--
-- Each computer also has one or more "host names", which are strings
--of words separated by periods, as in `churchy.gnu.ai.mit.edu'.
--
-- Programs that let the user specify a host typically accept both
--numeric addresses and host names. But the program needs a numeric
--address to open a connection; to use a host name, you must convert it
--to the numeric address it stands for.
--
--* Menu:
--
--* Abstract Host Addresses:: What a host number consists of.
--* Data type: Host Address Data Type. Data type for a host number.
--* Functions: Host Address Functions. Functions to operate on them.
--* Names: Host Names. Translating host names to host numbers.
--
--
--File: libc.info, Node: Abstract Host Addresses, Next: Host Address Data
Type, Up: Host Addresses
--
--Internet Host Addresses
--.......................
--
-- Each computer on the Internet has one or more Internet addresses,
--numbers which identify that computer among all those on the Internet.
--
-- An Internet host address is a number containing four bytes of data.
--These are divided into two parts, a "network number" and a "local
--network address number" within that network. The network number
--consists of the first one, two or three bytes; the rest of the bytes
--are the local address.
--
-- Network numbers are registered with the Network Information Center
--(NIC), and are divided into three classes--A, B, and C. The local
--network address numbers of individual machines are registered with the
--administrator of the particular network.
--
-- Class A networks have single-byte numbers in the range 0 to 127.
--There are only a small number of Class A networks, but they can each
--support a very large number of hosts. Medium-sized Class B networks
--have two-byte network numbers, with the first byte in the range 128 to
--191. Class C networks are the smallest; they have three-byte network
--numbers, with the first byte in the range 192-255. Thus, the first 1,
--2, or 3 bytes of an Internet address specifies a network. The
--remaining bytes of the Internet address specify the address within that
--network.
--
-- The Class A network 0 is reserved for broadcast to all networks. In
--addition, the host number 0 within each network is reserved for
--broadcast to all hosts in that network.
--
-- The Class A network 127 is reserved for loopback; you can always use
--the Internet address `127.0.0.1' to refer to the host machine.
--
-- Since a single machine can be a member of multiple networks, it can
--have multiple Internet host addresses. However, there is never
--supposed to be more than one machine with the same host address.
--
-- There are four forms of the "standard numbers-and-dots notation" for
--Internet addresses:
--
--`A.B.C.D'
-- This specifies all four bytes of the address individually.
--
--`A.B.C'
-- The last part of the address, C, is interpreted as a 2-byte
-- quantity. This is useful for specifying host addresses in a Class
-- B network with network address number `A.B'.
--
--`A.B'
-- The last part of the address, C, is interpreted as a 3-byte
-- quantity. This is useful for specifying host addresses in a Class
-- A network with network address number A.
--
--`A'
-- If only one part is given, this corresponds directly to the host
-- address number.
--
-- Within each part of the address, the usual C conventions for
--specifying the radix apply. In other words, a leading `0x' or `0X'
--implies hexadecimal radix; a leading `0' implies octal; and otherwise
--decimal radix is assumed.
--
--
--File: libc.info, Node: Host Address Data Type, Next: Host Address
Functions, Prev: Abstract Host Addresses, Up: Host Addresses
--
--Host Address Data Type
--......................
--
-- Internet host addresses are represented in some contexts as integers
--(type `unsigned long int'). In other contexts, the integer is packaged
--inside a structure of type `struct in_addr'. It would be better if the
--usage were made consistent, but it is not hard to extract the integer
--from the structure or put the integer into a structure.
--
-- The following basic definitions for Internet addresses appear in the
--header file `netinet/in.h':
--
-- - Data Type: struct in_addr
-- This data type is used in certain contexts to contain an Internet
-- host address. It has just one field, named `s_addr', which
-- records the host address number as an `unsigned long int'.
--
-- - Macro: unsigned long int INADDR_LOOPBACK
-- You can use this constant to stand for "the address of this
-- machine," instead of finding its actual address. It is the
-- Internet address `127.0.0.1', which is usually called `localhost'.
-- This special constant saves you the trouble of looking up the
-- address of your own machine. Also, the system usually implements
-- `INADDR_LOOPBACK' specially, avoiding any network traffic for the
-- case of one machine talking to itself.
--
-- - Macro: unsigned long int INADDR_ANY
-- You can use this constant to stand for "any incoming address," when
-- binding to an address. *Note Setting Address::. This is the usual
-- address to give in the `sin_addr' member of `struct sockaddr_in'
-- when you want to accept Internet connections.
--
-- - Macro: unsigned long int INADDR_BROADCAST
-- This constant is the address you use to send a broadcast message.
--
-- - Macro: unsigned long int INADDR_NONE
-- This constant is returned by some functions to indicate an error.
--
--
--File: libc.info, Node: Host Address Functions, Next: Host Names, Prev:
Host Address Data Type, Up: Host Addresses
--
--Host Address Functions
--......................
--
-- These additional functions for manipulating Internet addresses are
--declared in `arpa/inet.h'. They represent Internet addresses in
--network byte order; they represent network numbers and
--local-address-within-network numbers in host byte order. *Note Byte
--Order::, for an explanation of network and host byte order.
--
-- - Function: int inet_aton (const char *NAME, struct in_addr *ADDR)
-- This function converts the Internet host address NAME from the
-- standard numbers-and-dots notation into binary data and stores it
-- in the `struct in_addr' that ADDR points to. `inet_aton' returns
-- nonzero if the address is valid, zero if not.
--
-- - Function: unsigned long int inet_addr (const char *NAME)
-- This function converts the Internet host address NAME from the
-- standard numbers-and-dots notation into binary data. If the input
-- is not valid, `inet_addr' returns `INADDR_NONE'. This is an
-- obsolete interface to `inet_aton', described immediately above; it
-- is obsolete because `INADDR_NONE' is a valid address
-- (255.255.255.255), and `inet_aton' provides a cleaner way to
-- indicate error return.
--
-- - Function: unsigned long int inet_network (const char *NAME)
-- This function extracts the network number from the address NAME,
-- given in the standard numbers-and-dots notation. If the input is
-- not valid, `inet_network' returns `-1'.
--
-- - Function: char * inet_ntoa (struct in_addr ADDR)
-- This function converts the Internet host address ADDR to a string
-- in the standard numbers-and-dots notation. The return value is a
-- pointer into a statically-allocated buffer. Subsequent calls will
-- overwrite the same buffer, so you should copy the string if you
-- need to save it.
--
-- - Function: struct in_addr inet_makeaddr (int NET, int LOCAL)
-- This function makes an Internet host address by combining the
-- network number NET with the local-address-within-network number
-- LOCAL.
--
-- - Function: int inet_lnaof (struct in_addr ADDR)
-- This function returns the local-address-within-network part of the
-- Internet host address ADDR.
--
-- - Function: int inet_netof (struct in_addr ADDR)
-- This function returns the network number part of the Internet host
-- address ADDR.
--
--
--File: libc.info, Node: Host Names, Prev: Host Address Functions, Up: Host
Addresses
--
--Host Names
--..........
--
-- Besides the standard numbers-and-dots notation for Internet
--addresses, you can also refer to a host by a symbolic name. The
--advantage of a symbolic name is that it is usually easier to remember.
--For example, the machine with Internet address `128.52.46.32' is also
--known as `churchy.gnu.ai.mit.edu'; and other machines in the
--`gnu.ai.mit.edu' domain can refer to it simply as `churchy'.
--
-- Internally, the system uses a database to keep track of the mapping
--between host names and host numbers. This database is usually either
--the file `/etc/hosts' or an equivalent provided by a name server. The
--functions and other symbols for accessing this database are declared in
--`netdb.h'. They are BSD features, defined unconditionally if you
--include `netdb.h'.
--
-- - Data Type: struct hostent
-- This data type is used to represent an entry in the hosts
-- database. It has the following members:
--
-- `char *h_name'
-- This is the "official" name of the host.
--
-- `char **h_aliases'
-- These are alternative names for the host, represented as a
-- null-terminated vector of strings.
--
-- `int h_addrtype'
-- This is the host address type; in practice, its value is
-- always `AF_INET'. In principle other kinds of addresses
-- could be represented in the data base as well as Internet
-- addresses; if this were done, you might find a value in this
-- field other than `AF_INET'. *Note Socket Addresses::.
--
-- `int h_length'
-- This is the length, in bytes, of each address.
--
-- `char **h_addr_list'
-- This is the vector of addresses for the host. (Recall that
-- the host might be connected to multiple networks and have
-- different addresses on each one.) The vector is terminated
-- by a null pointer.
--
-- `char *h_addr'
-- This is a synonym for `h_addr_list[0]'; in other words, it is
-- the first host address.
--
-- As far as the host database is concerned, each address is just a
--block of memory `h_length' bytes long. But in other contexts there is
--an implicit assumption that you can convert this to a `struct in_addr'
--or an `unsigned long int'. Host addresses in a `struct hostent'
--structure are always given in network byte order; see *Note Byte
--Order::.
--
-- You can use `gethostbyname' or `gethostbyaddr' to search the hosts
--database for information about a particular host. The information is
--returned in a statically-allocated structure; you must copy the
--information if you need to save it across calls.
--
-- - Function: struct hostent * gethostbyname (const char *NAME)
-- The `gethostbyname' function returns information about the host
-- named NAME. If the lookup fails, it returns a null pointer.
--
-- - Function: struct hostent * gethostbyaddr (const char *ADDR, int
-- LENGTH, int FORMAT)
-- The `gethostbyaddr' function returns information about the host
-- with Internet address ADDR. The LENGTH argument is the size (in
-- bytes) of the address at ADDR. FORMAT specifies the address
-- format; for an Internet address, specify a value of `AF_INET'.
--
-- If the lookup fails, `gethostbyaddr' returns a null pointer.
--
-- If the name lookup by `gethostbyname' or `gethostbyaddr' fails, you
--can find out the reason by looking at the value of the variable
--`h_errno'. (It would be cleaner design for these functions to set
--`errno', but use of `h_errno' is compatible with other systems.)
--Before using `h_errno', you must declare it like this:
--
-- extern int h_errno;
--
-- Here are the error codes that you may find in `h_errno':
--
--`HOST_NOT_FOUND'
-- No such host is known in the data base.
--
--`TRY_AGAIN'
-- This condition happens when the name server could not be
-- contacted. If you try again later, you may succeed then.
--
--`NO_RECOVERY'
-- A non-recoverable error occurred.
--
--`NO_ADDRESS'
-- The host database contains an entry for the name, but it doesn't
-- have an associated Internet address.
--
-- You can also scan the entire hosts database one entry at a time using
--`sethostent', `gethostent', and `endhostent'. Be careful in using
--these functions, because they are not reentrant.
--
-- - Function: void sethostent (int STAYOPEN)
-- This function opens the hosts database to begin scanning it. You
-- can then call `gethostent' to read the entries.
--
-- If the STAYOPEN argument is nonzero, this sets a flag so that
-- subsequent calls to `gethostbyname' or `gethostbyaddr' will not
-- close the database (as they usually would). This makes for more
-- efficiency if you call those functions several times, by avoiding
-- reopening the database for each call.
--
-- - Function: struct hostent * gethostent ()
-- This function returns the next entry in the hosts database. It
-- returns a null pointer if there are no more entries.
--
-- - Function: void endhostent ()
-- This function closes the hosts database.
--
--
--File: libc.info, Node: Ports, Next: Services Database, Prev: Protocols
Database, Up: Internet Namespace
--
--Internet Ports
----------------
--
-- A socket address in the Internet namespace consists of a machine's
--Internet address plus a "port number" which distinguishes the sockets
--on a given machine (for a given protocol). Port numbers range from 0
--to 65,535.
--
-- Port numbers less than `IPPORT_RESERVED' are reserved for standard
--servers, such as `finger' and `telnet'. There is a database that keeps
--track of these, and you can use the `getservbyname' function to map a
--service name onto a port number; see *Note Services Database::.
--
-- If you write a server that is not one of the standard ones defined in
--the database, you must choose a port number for it. Use a number
--greater than `IPPORT_USERRESERVED'; such numbers are reserved for
--servers and won't ever be generated automatically by the system.
--Avoiding conflicts with servers being run by other users is up to you.
--
-- When you use a socket without specifying its address, the system
--generates a port number for it. This number is between
--`IPPORT_RESERVED' and `IPPORT_USERRESERVED'.
--
-- On the Internet, it is actually legitimate to have two different
--sockets with the same port number, as long as they never both try to
--communicate with the same socket address (host address plus port
--number). You shouldn't duplicate a port number except in special
--circumstances where a higher-level protocol requires it. Normally, the
--system won't let you do it; `bind' normally insists on distinct port
--numbers. To reuse a port number, you must set the socket option
--`SO_REUSEADDR'. *Note Socket-Level Options::.
--
-- These macros are defined in the header file `netinet/in.h'.
--
-- - Macro: int IPPORT_RESERVED
-- Port numbers less than `IPPORT_RESERVED' are reserved for
-- superuser use.
--
-- - Macro: int IPPORT_USERRESERVED
-- Port numbers greater than or equal to `IPPORT_USERRESERVED' are
-- reserved for explicit use; they will never be allocated
-- automatically.
--
--
--File: libc.info, Node: Services Database, Next: Byte Order, Prev: Ports,
Up: Internet Namespace
--
--The Services Database
-----------------------
--
-- The database that keeps track of "well-known" services is usually
--either the file `/etc/services' or an equivalent from a name server.
--You can use these utilities, declared in `netdb.h', to access the
--services database.
--
-- - Data Type: struct servent
-- This data type holds information about entries from the services
-- database. It has the following members:
--
-- `char *s_name'
-- This is the "official" name of the service.
--
-- `char **s_aliases'
-- These are alternate names for the service, represented as an
-- array of strings. A null pointer terminates the array.
--
-- `int s_port'
-- This is the port number for the service. Port numbers are
-- given in network byte order; see *Note Byte Order::.
--
-- `char *s_proto'
-- This is the name of the protocol to use with this service.
-- *Note Protocols Database::.
--
-- To get information about a particular service, use the
--`getservbyname' or `getservbyport' functions. The information is
--returned in a statically-allocated structure; you must copy the
--information if you need to save it across calls.
--
-- - Function: struct servent * getservbyname (const char *NAME, const
-- char *PROTO)
-- The `getservbyname' function returns information about the service
-- named NAME using protocol PROTO. If it can't find such a service,
-- it returns a null pointer.
--
-- This function is useful for servers as well as for clients; servers
-- use it to determine which port they should listen on (*note
-- Listening::.).
--
-- - Function: struct servent * getservbyport (int PORT, const char
-- *PROTO)
-- The `getservbyport' function returns information about the service
-- at port PORT using protocol PROTO. If it can't find such a
-- service, it returns a null pointer.
--
-- You can also scan the services database using `setservent',
--`getservent', and `endservent'. Be careful in using these functions,
--because they are not reentrant.
--
-- - Function: void setservent (int STAYOPEN)
-- This function opens the services database to begin scanning it.
--
-- If the STAYOPEN argument is nonzero, this sets a flag so that
-- subsequent calls to `getservbyname' or `getservbyport' will not
-- close the database (as they usually would). This makes for more
-- efficiency if you call those functions several times, by avoiding
-- reopening the database for each call.
--
-- - Function: struct servent * getservent (void)
-- This function returns the next entry in the services database. If
-- there are no more entries, it returns a null pointer.
--
-- - Function: void endservent (void)
-- This function closes the services database.
--
--
--File: libc.info, Node: Byte Order, Next: Inet Example, Prev: Services
Database, Up: Internet Namespace
--
--Byte Order Conversion
-----------------------
--
-- Different kinds of computers use different conventions for the
--ordering of bytes within a word. Some computers put the most
--significant byte within a word first (this is called "big-endian"
--order), and others put it last ("little-endian" order).
--
-- So that machines with different byte order conventions can
--communicate, the Internet protocols specify a canonical byte order
--convention for data transmitted over the network. This is known as the
--"network byte order".
--
-- When establishing an Internet socket connection, you must make sure
--that the data in the `sin_port' and `sin_addr' members of the
--`sockaddr_in' structure are represented in the network byte order. If
--you are encoding integer data in the messages sent through the socket,
--you should convert this to network byte order too. If you don't do
--this, your program may fail when running on or talking to other kinds
--of machines.
--
-- If you use `getservbyname' and `gethostbyname' or `inet_addr' to get
--the port number and host address, the values are already in the network
--byte order, and you can copy them directly into the `sockaddr_in'
--structure.
--
-- Otherwise, you have to convert the values explicitly. Use `htons'
--and `ntohs' to convert values for the `sin_port' member. Use `htonl'
--and `ntohl' to convert values for the `sin_addr' member. (Remember,
--`struct in_addr' is equivalent to `unsigned long int'.) These
--functions are declared in `netinet/in.h'.
--
-- - Function: unsigned short int htons (unsigned short int HOSTSHORT)
-- This function converts the `short' integer HOSTSHORT from host
-- byte order to network byte order.
--
-- - Function: unsigned short int ntohs (unsigned short int NETSHORT)
-- This function converts the `short' integer NETSHORT from network
-- byte order to host byte order.
--
-- - Function: unsigned long int htonl (unsigned long int HOSTLONG)
-- This function converts the `long' integer HOSTLONG from host byte
-- order to network byte order.
--
-- - Function: unsigned long int ntohl (unsigned long int NETLONG)
-- This function converts the `long' integer NETLONG from network
-- byte order to host byte order.
--
--
--File: libc.info, Node: Protocols Database, Next: Ports, Prev: Host
Addresses, Up: Internet Namespace
--
--Protocols Database
--------------------
--
-- The communications protocol used with a socket controls low-level
--details of how data is exchanged. For example, the protocol implements
--things like checksums to detect errors in transmissions, and routing
--instructions for messages. Normal user programs have little reason to
--mess with these details directly.
--
-- The default communications protocol for the Internet namespace
--depends on the communication style. For stream communication, the
--default is TCP ("transmission control protocol"). For datagram
--communication, the default is UDP ("user datagram protocol"). For
--reliable datagram communication, the default is RDP ("reliable datagram
--protocol"). You should nearly always use the default.
--
-- Internet protocols are generally specified by a name instead of a
--number. The network protocols that a host knows about are stored in a
--database. This is usually either derived from the file
--`/etc/protocols', or it may be an equivalent provided by a name server.
--You look up the protocol number associated with a named protocol in
--the database using the `getprotobyname' function.
--
-- Here are detailed descriptions of the utilities for accessing the
--protocols database. These are declared in `netdb.h'.
--
-- - Data Type: struct protoent
-- This data type is used to represent entries in the network
-- protocols database. It has the following members:
--
-- `char *p_name'
-- This is the official name of the protocol.
--
-- `char **p_aliases'
-- These are alternate names for the protocol, specified as an
-- array of strings. The last element of the array is a null
-- pointer.
--
-- `int p_proto'
-- This is the protocol number (in host byte order); use this
-- member as the PROTOCOL argument to `socket'.
--
-- You can use `getprotobyname' and `getprotobynumber' to search the
--protocols database for a specific protocol. The information is
--returned in a statically-allocated structure; you must copy the
--information if you need to save it across calls.
--
-- - Function: struct protoent * getprotobyname (const char *NAME)
-- The `getprotobyname' function returns information about the
-- network protocol named NAME. If there is no such protocol, it
-- returns a null pointer.
--
-- - Function: struct protoent * getprotobynumber (int PROTOCOL)
-- The `getprotobynumber' function returns information about the
-- network protocol with number PROTOCOL. If there is no such
-- protocol, it returns a null pointer.
--
-- You can also scan the whole protocols database one protocol at a
--time by using `setprotoent', `getprotoent', and `endprotoent'. Be
--careful in using these functions, because they are not reentrant.
--
-- - Function: void setprotoent (int STAYOPEN)
-- This function opens the protocols database to begin scanning it.
--
-- If the STAYOPEN argument is nonzero, this sets a flag so that
-- subsequent calls to `getprotobyname' or `getprotobynumber' will
-- not close the database (as they usually would). This makes for
-- more efficiency if you call those functions several times, by
-- avoiding reopening the database for each call.
--
-- - Function: struct protoent * getprotoent (void)
-- This function returns the next entry in the protocols database. It
-- returns a null pointer if there are no more entries.
--
-- - Function: void endprotoent (void)
-- This function closes the protocols database.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-13
glibc-2.0.1/manual/libc.info-13
---- ../glibc-2.0.1/manual/libc.info-13 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-13 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1376 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Inet Example, Prev: Byte Order, Up: Internet
Namespace
--
--Internet Socket Example
-------------------------
--
-- Here is an example showing how to create and name a socket in the
--Internet namespace. The newly created socket exists on the machine that
--the program is running on. Rather than finding and using the machine's
--Internet address, this example specifies `INADDR_ANY' as the host
--address; the system replaces that with the machine's actual address.
--
-- #include <stdio.h>
-- #include <stdlib.h>
-- #include <sys/socket.h>
-- #include <netinet/in.h>
--
-- int
-- make_socket (unsigned short int port)
-- {
-- int sock;
-- struct sockaddr_in name;
--
-- /* Create the socket. */
-- sock = socket (PF_INET, SOCK_STREAM, 0);
-- if (sock < 0)
-- {
-- perror ("socket");
-- exit (EXIT_FAILURE);
-- }
--
-- /* Give the socket a name. */
-- name.sin_family = AF_INET;
-- name.sin_port = htons (port);
-- name.sin_addr.s_addr = htonl (INADDR_ANY);
-- if (bind (sock, (struct sockaddr *) &name, sizeof (name)) < 0)
-- {
-- perror ("bind");
-- exit (EXIT_FAILURE);
-- }
--
-- return sock;
-- }
--
-- Here is another example, showing how you can fill in a `sockaddr_in'
--structure, given a host name string and a port number:
--
-- #include <stdio.h>
-- #include <stdlib.h>
-- #include <sys/socket.h>
-- #include <netinet/in.h>
-- #include <netdb.h>
--
-- void
-- init_sockaddr (struct sockaddr_in *name,
-- const char *hostname,
-- unsigned short int port)
-- {
-- struct hostent *hostinfo;
--
-- name->sin_family = AF_INET;
-- name->sin_port = htons (port);
-- hostinfo = gethostbyname (hostname);
-- if (hostinfo == NULL)
-- {
-- fprintf (stderr, "Unknown host %s.\n", hostname);
-- exit (EXIT_FAILURE);
-- }
-- name->sin_addr = *(struct in_addr *) hostinfo->h_addr;
-- }
--
--
--File: libc.info, Node: Misc Namespaces, Next: Open/Close Sockets, Prev:
Internet Namespace, Up: Sockets
--
--Other Namespaces
--================
--
-- Certain other namespaces and associated protocol families are
--supported but not documented yet because they are not often used.
--`PF_NS' refers to the Xerox Network Software protocols. `PF_ISO' stands
--for Open Systems Interconnect. `PF_CCITT' refers to protocols from
--CCITT. `socket.h' defines these symbols and others naming protocols
--not actually implemented.
--
-- `PF_IMPLINK' is used for communicating between hosts and Internet
--Message Processors. For information on this, and on `PF_ROUTE', an
--occasionally-used local area routing protocol, see the GNU Hurd Manual
--(to appear in the future).
--
--
--File: libc.info, Node: Open/Close Sockets, Next: Connections, Prev: Misc
Namespaces, Up: Sockets
--
--Opening and Closing Sockets
--===========================
--
-- This section describes the actual library functions for opening and
--closing sockets. The same functions work for all namespaces and
--connection styles.
--
--* Menu:
--
--* Creating a Socket:: How to open a socket.
--* Closing a Socket:: How to close a socket.
--* Socket Pairs:: These are created like pipes.
--
--
--File: libc.info, Node: Creating a Socket, Next: Closing a Socket, Up:
Open/Close Sockets
--
--Creating a Socket
-------------------
--
-- The primitive for creating a socket is the `socket' function,
--declared in `sys/socket.h'.
--
-- - Function: int socket (int NAMESPACE, int STYLE, int PROTOCOL)
-- This function creates a socket and specifies communication style
-- STYLE, which should be one of the socket styles listed in *Note
-- Communication Styles::. The NAMESPACE argument specifies the
-- namespace; it must be `PF_FILE' (*note File Namespace::.) or
-- `PF_INET' (*note Internet Namespace::.). PROTOCOL designates the
-- specific protocol (*note Socket Concepts::.); zero is usually
-- right for PROTOCOL.
--
-- The return value from `socket' is the file descriptor for the new
-- socket, or `-1' in case of error. The following `errno' error
-- conditions are defined for this function:
--
-- `EPROTONOSUPPORT'
-- The PROTOCOL or STYLE is not supported by the NAMESPACE
-- specified.
--
-- `EMFILE'
-- The process already has too many file descriptors open.
--
-- `ENFILE'
-- The system already has too many file descriptors open.
--
-- `EACCESS'
-- The process does not have privilege to create a socket of the
-- specified STYLE or PROTOCOL.
--
-- `ENOBUFS'
-- The system ran out of internal buffer space.
--
-- The file descriptor returned by the `socket' function supports both
-- read and write operations. But, like pipes, sockets do not
-- support file positioning operations.
--
-- For examples of how to call the `socket' function, see *Note File
--Namespace::, or *Note Inet Example::.
--
--
--File: libc.info, Node: Closing a Socket, Next: Socket Pairs, Prev:
Creating a Socket, Up: Open/Close Sockets
--
--Closing a Socket
------------------
--
-- When you are finished using a socket, you can simply close its file
--descriptor with `close'; see *Note Opening and Closing Files::. If
--there is still data waiting to be transmitted over the connection,
--normally `close' tries to complete this transmission. You can control
--this behavior using the `SO_LINGER' socket option to specify a timeout
--period; see *Note Socket Options::.
--
-- You can also shut down only reception or only transmission on a
--connection by calling `shutdown', which is declared in `sys/socket.h'.
--
-- - Function: int shutdown (int SOCKET, int HOW)
-- The `shutdown' function shuts down the connection of socket
-- SOCKET. The argument HOW specifies what action to perform:
--
-- `0'
-- Stop receiving data for this socket. If further data arrives,
-- reject it.
--
-- `1'
-- Stop trying to transmit data from this socket. Discard any
-- data waiting to be sent. Stop looking for acknowledgement of
-- data already sent; don't retransmit it if it is lost.
--
-- `2'
-- Stop both reception and transmission.
--
-- The return value is `0' on success and `-1' on failure. The
-- following `errno' error conditions are defined for this function:
--
-- `EBADF'
-- SOCKET is not a valid file descriptor.
--
-- `ENOTSOCK'
-- SOCKET is not a socket.
--
-- `ENOTCONN'
-- SOCKET is not connected.
--
--
--File: libc.info, Node: Socket Pairs, Prev: Closing a Socket, Up:
Open/Close Sockets
--
--Socket Pairs
--------------
--
-- A "socket pair" consists of a pair of connected (but unnamed)
--sockets. It is very similar to a pipe and is used in much the same
--way. Socket pairs are created with the `socketpair' function, declared
--in `sys/socket.h'. A socket pair is much like a pipe; the main
--difference is that the socket pair is bidirectional, whereas the pipe
--has one input-only end and one output-only end (*note Pipes and
--FIFOs::.).
--
-- - Function: int socketpair (int NAMESPACE, int STYLE, int PROTOCOL,
-- int FILEDES[2])
-- This function creates a socket pair, returning the file
-- descriptors in `FILEDES[0]' and `FILEDES[1]'. The socket pair is
-- a full-duplex communications channel, so that both reading and
-- writing may be performed at either end.
--
-- The NAMESPACE, STYLE, and PROTOCOL arguments are interpreted as
-- for the `socket' function. STYLE should be one of the
-- communication styles listed in *Note Communication Styles::. The
-- NAMESPACE argument specifies the namespace, which must be
-- `AF_FILE' (*note File Namespace::.); PROTOCOL specifies the
-- communications protocol, but zero is the only meaningful value.
--
-- If STYLE specifies a connectionless communication style, then the
-- two sockets you get are not *connected*, strictly speaking, but
-- each of them knows the other as the default destination address,
-- so they can send packets to each other.
--
-- The `socketpair' function returns `0' on success and `-1' on
-- failure. The following `errno' error conditions are defined for
-- this function:
--
-- `EMFILE'
-- The process has too many file descriptors open.
--
-- `EAFNOSUPPORT'
-- The specified namespace is not supported.
--
-- `EPROTONOSUPPORT'
-- The specified protocol is not supported.
--
-- `EOPNOTSUPP'
-- The specified protocol does not support the creation of
-- socket pairs.
--
--
--File: libc.info, Node: Connections, Next: Datagrams, Prev: Open/Close
Sockets, Up: Sockets
--
--Using Sockets with Connections
--==============================
--
-- The most common communication styles involve making a connection to a
--particular other socket, and then exchanging data with that socket over
--and over. Making a connection is asymmetric; one side (the "client")
--acts to request a connection, while the other side (the "server") makes
--a socket and waits for the connection request.
--
--* Menu:
--
--* Connecting:: What the client program must do.
--* Listening:: How a server program waits for requests.
--* Accepting Connections:: What the server does when it gets a request.
--* Who is Connected:: Getting the address of the
-- other side of a connection.
--* Transferring Data:: How to send and receive data.
--* Byte Stream Example:: An example program: a client for
communicating
-- over a byte stream socket in the Internet
namespace.
--* Server Example:: A corresponding server program.
--* Out-of-Band Data:: This is an advanced feature.
--
--
--File: libc.info, Node: Connecting, Next: Listening, Up: Connections
--
--Making a Connection
---------------------
--
-- In making a connection, the client makes a connection while the
--server waits for and accepts the connection. Here we discuss what the
--client program must do, using the `connect' function, which is declared
--in `sys/socket.h'.
--
-- - Function: int connect (int SOCKET, struct sockaddr *ADDR, size_t
-- LENGTH)
-- The `connect' function initiates a connection from the socket with
-- file descriptor SOCKET to the socket whose address is specified by
-- the ADDR and LENGTH arguments. (This socket is typically on
-- another machine, and it must be already set up as a server.)
-- *Note Socket Addresses::, for information about how these
-- arguments are interpreted.
--
-- Normally, `connect' waits until the server responds to the request
-- before it returns. You can set nonblocking mode on the socket
-- SOCKET to make `connect' return immediately without waiting for
-- the response. *Note File Status Flags::, for information about
-- nonblocking mode.
--
-- The normal return value from `connect' is `0'. If an error
-- occurs, `connect' returns `-1'. The following `errno' error
-- conditions are defined for this function:
--
-- `EBADF'
-- The socket SOCKET is not a valid file descriptor.
--
-- `ENOTSOCK'
-- File descriptor SOCKET is not a socket.
--
-- `EADDRNOTAVAIL'
-- The specified address is not available on the remote machine.
--
-- `EAFNOSUPPORT'
-- The namespace of the ADDR is not supported by this socket.
--
-- `EISCONN'
-- The socket SOCKET is already connected.
--
-- `ETIMEDOUT'
-- The attempt to establish the connection timed out.
--
-- `ECONNREFUSED'
-- The server has actively refused to establish the connection.
--
-- `ENETUNREACH'
-- The network of the given ADDR isn't reachable from this host.
--
-- `EADDRINUSE'
-- The socket address of the given ADDR is already in use.
--
-- `EINPROGRESS'
-- The socket SOCKET is non-blocking and the connection could
-- not be established immediately. You can determine when the
-- connection is completely established with `select'; *note
-- Waiting for I/O::.. Another `connect' call on the same
-- socket, before the connection is completely established, will
-- fail with `EALREADY'.
--
-- `EALREADY'
-- The socket SOCKET is non-blocking and already has a pending
-- connection in progress (see `EINPROGRESS' above).
--
--
--File: libc.info, Node: Listening, Next: Accepting Connections, Prev:
Connecting, Up: Connections
--
--Listening for Connections
---------------------------
--
-- Now let us consider what the server process must do to accept
--connections on a socket. First it must use the `listen' function to
--enable connection requests on the socket, and then accept each incoming
--connection with a call to `accept' (*note Accepting Connections::.).
--Once connection requests are enabled on a server socket, the `select'
--function reports when the socket has a connection ready to be accepted
--(*note Waiting for I/O::.).
--
-- The `listen' function is not allowed for sockets using
--connectionless communication styles.
--
-- You can write a network server that does not even start running
--until a connection to it is requested. *Note Inetd Servers::.
--
-- In the Internet namespace, there are no special protection mechanisms
--for controlling access to connect to a port; any process on any machine
--can make a connection to your server. If you want to restrict access to
--your server, make it examine the addresses associated with connection
--requests or implement some other handshaking or identification protocol.
--
-- In the File namespace, the ordinary file protection bits control who
--has access to connect to the socket.
--
-- - Function: int listen (int SOCKET, unsigned int N)
-- The `listen' function enables the socket SOCKET to accept
-- connections, thus making it a server socket.
--
-- The argument N specifies the length of the queue for pending
-- connections. When the queue fills, new clients attempting to
-- connect fail with `ECONNREFUSED' until the server calls `accept' to
-- accept a connection from the queue.
--
-- The `listen' function returns `0' on success and `-1' on failure.
-- The following `errno' error conditions are defined for this
-- function:
--
-- `EBADF'
-- The argument SOCKET is not a valid file descriptor.
--
-- `ENOTSOCK'
-- The argument SOCKET is not a socket.
--
-- `EOPNOTSUPP'
-- The socket SOCKET does not support this operation.
--
--
--File: libc.info, Node: Accepting Connections, Next: Who is Connected,
Prev: Listening, Up: Connections
--
--Accepting Connections
-----------------------
--
-- When a server receives a connection request, it can complete the
--connection by accepting the request. Use the function `accept' to do
--this.
--
-- A socket that has been established as a server can accept connection
--requests from multiple clients. The server's original socket *does not
--become part* of the connection; instead, `accept' makes a new socket
--which participates in the connection. `accept' returns the descriptor
--for this socket. The server's original socket remains available for
--listening for further connection requests.
--
-- The number of pending connection requests on a server socket is
--finite. If connection requests arrive from clients faster than the
--server can act upon them, the queue can fill up and additional requests
--are refused with a `ECONNREFUSED' error. You can specify the maximum
--length of this queue as an argument to the `listen' function, although
--the system may also impose its own internal limit on the length of this
--queue.
--
-- - Function: int accept (int SOCKET, struct sockaddr *ADDR, size_t
-- *LENGTH-PTR)
-- This function is used to accept a connection request on the server
-- socket SOCKET.
--
-- The `accept' function waits if there are no connections pending,
-- unless the socket SOCKET has nonblocking mode set. (You can use
-- `select' to wait for a pending connection, with a nonblocking
-- socket.) *Note File Status Flags::, for information about
-- nonblocking mode.
--
-- The ADDR and LENGTH-PTR arguments are used to return information
-- about the name of the client socket that initiated the connection.
-- *Note Socket Addresses::, for information about the format of the
-- information.
--
-- Accepting a connection does not make SOCKET part of the
-- connection. Instead, it creates a new socket which becomes
-- connected. The normal return value of `accept' is the file
-- descriptor for the new socket.
--
-- After `accept', the original socket SOCKET remains open and
-- unconnected, and continues listening until you close it. You can
-- accept further connections with SOCKET by calling `accept' again.
--
-- If an error occurs, `accept' returns `-1'. The following `errno'
-- error conditions are defined for this function:
--
-- `EBADF'
-- The SOCKET argument is not a valid file descriptor.
--
-- `ENOTSOCK'
-- The descriptor SOCKET argument is not a socket.
--
-- `EOPNOTSUPP'
-- The descriptor SOCKET does not support this operation.
--
-- `EWOULDBLOCK'
-- SOCKET has nonblocking mode set, and there are no pending
-- connections immediately available.
--
-- The `accept' function is not allowed for sockets using
--connectionless communication styles.
--
--
--File: libc.info, Node: Who is Connected, Next: Transferring Data, Prev:
Accepting Connections, Up: Connections
--
--Who is Connected to Me?
-------------------------
--
-- - Function: int getpeername (int SOCKET, struct sockaddr *ADDR, size_t
-- *LENGTH-PTR)
-- The `getpeername' function returns the address of the socket that
-- SOCKET is connected to; it stores the address in the memory space
-- specified by ADDR and LENGTH-PTR. It stores the length of the
-- address in `*LENGTH-PTR'.
--
-- *Note Socket Addresses::, for information about the format of the
-- address. In some operating systems, `getpeername' works only for
-- sockets in the Internet domain.
--
-- The return value is `0' on success and `-1' on error. The
-- following `errno' error conditions are defined for this function:
--
-- `EBADF'
-- The argument SOCKET is not a valid file descriptor.
--
-- `ENOTSOCK'
-- The descriptor SOCKET is not a socket.
--
-- `ENOTCONN'
-- The socket SOCKET is not connected.
--
-- `ENOBUFS'
-- There are not enough internal buffers available.
--
--
--File: libc.info, Node: Transferring Data, Next: Byte Stream Example, Prev:
Who is Connected, Up: Connections
--
--Transferring Data
-------------------
--
-- Once a socket has been connected to a peer, you can use the ordinary
--`read' and `write' operations (*note I/O Primitives::.) to transfer
--data. A socket is a two-way communications channel, so read and write
--operations can be performed at either end.
--
-- There are also some I/O modes that are specific to socket operations.
--In order to specify these modes, you must use the `recv' and `send'
--functions instead of the more generic `read' and `write' functions.
--The `recv' and `send' functions take an additional argument which you
--can use to specify various flags to control the special I/O modes. For
--example, you can specify the `MSG_OOB' flag to read or write
--out-of-band data, the `MSG_PEEK' flag to peek at input, or the
--`MSG_DONTROUTE' flag to control inclusion of routing information on
--output.
--
--* Menu:
--
--* Sending Data:: Sending data with `send'.
--* Receiving Data:: Reading data with `recv'.
--* Socket Data Options:: Using `send' and `recv'.
--
--
--File: libc.info, Node: Sending Data, Next: Receiving Data, Up:
Transferring Data
--
--Sending Data
--............
--
-- The `send' function is declared in the header file `sys/socket.h'.
--If your FLAGS argument is zero, you can just as well use `write'
--instead of `send'; see *Note I/O Primitives::. If the socket was
--connected but the connection has broken, you get a `SIGPIPE' signal for
--any use of `send' or `write' (*note Miscellaneous Signals::.).
--
-- - Function: int send (int SOCKET, void *BUFFER, size_t SIZE, int FLAGS)
-- The `send' function is like `write', but with the additional flags
-- FLAGS. The possible values of FLAGS are described in *Note Socket
-- Data Options::.
--
-- This function returns the number of bytes transmitted, or `-1' on
-- failure. If the socket is nonblocking, then `send' (like `write')
-- can return after sending just part of the data. *Note File Status
-- Flags::, for information about nonblocking mode.
--
-- Note, however, that a successful return value merely indicates that
-- the message has been sent without error, not necessarily that it
-- has been received without error.
--
-- The following `errno' error conditions are defined for this
-- function:
--
-- `EBADF'
-- The SOCKET argument is not a valid file descriptor.
--
-- `EINTR'
-- The operation was interrupted by a signal before any data was
-- sent. *Note Interrupted Primitives::.
--
-- `ENOTSOCK'
-- The descriptor SOCKET is not a socket.
--
-- `EMSGSIZE'
-- The socket type requires that the message be sent atomically,
-- but the message is too large for this to be possible.
--
-- `EWOULDBLOCK'
-- Nonblocking mode has been set on the socket, and the write
-- operation would block. (Normally `send' blocks until the
-- operation can be completed.)
--
-- `ENOBUFS'
-- There is not enough internal buffer space available.
--
-- `ENOTCONN'
-- You never connected this socket.
--
-- `EPIPE'
-- This socket was connected but the connection is now broken.
-- In this case, `send' generates a `SIGPIPE' signal first; if
-- that signal is ignored or blocked, or if its handler returns,
-- then `send' fails with `EPIPE'.
--
--
--File: libc.info, Node: Receiving Data, Next: Socket Data Options, Prev:
Sending Data, Up: Transferring Data
--
--Receiving Data
--..............
--
-- The `recv' function is declared in the header file `sys/socket.h'.
--If your FLAGS argument is zero, you can just as well use `read' instead
--of `recv'; see *Note I/O Primitives::.
--
-- - Function: int recv (int SOCKET, void *BUFFER, size_t SIZE, int FLAGS)
-- The `recv' function is like `read', but with the additional flags
-- FLAGS. The possible values of FLAGS are described In *Note Socket
-- Data Options::.
--
-- If nonblocking mode is set for SOCKET, and no data is available to
-- be read, `recv' fails immediately rather than waiting. *Note File
-- Status Flags::, for information about nonblocking mode.
--
-- This function returns the number of bytes received, or `-1' on
-- failure. The following `errno' error conditions are defined for
-- this function:
--
-- `EBADF'
-- The SOCKET argument is not a valid file descriptor.
--
-- `ENOTSOCK'
-- The descriptor SOCKET is not a socket.
--
-- `EWOULDBLOCK'
-- Nonblocking mode has been set on the socket, and the read
-- operation would block. (Normally, `recv' blocks until there
-- is input available to be read.)
--
-- `EINTR'
-- The operation was interrupted by a signal before any data was
-- read. *Note Interrupted Primitives::.
--
-- `ENOTCONN'
-- You never connected this socket.
--
--
--File: libc.info, Node: Socket Data Options, Prev: Receiving Data, Up:
Transferring Data
--
--Socket Data Options
--...................
--
-- The FLAGS argument to `send' and `recv' is a bit mask. You can
--bitwise-OR the values of the following macros together to obtain a
--value for this argument. All are defined in the header file
--`sys/socket.h'.
--
-- - Macro: int MSG_OOB
-- Send or receive out-of-band data. *Note Out-of-Band Data::.
--
-- - Macro: int MSG_PEEK
-- Look at the data but don't remove it from the input queue. This is
-- only meaningful with input functions such as `recv', not with
-- `send'.
--
-- - Macro: int MSG_DONTROUTE
-- Don't include routing information in the message. This is only
-- meaningful with output operations, and is usually only of interest
-- for diagnostic or routing programs. We don't try to explain it
-- here.
--
--
--File: libc.info, Node: Byte Stream Example, Next: Server Example, Prev:
Transferring Data, Up: Connections
--
--Byte Stream Socket Example
----------------------------
--
-- Here is an example client program that makes a connection for a byte
--stream socket in the Internet namespace. It doesn't do anything
--particularly interesting once it has connected to the server; it just
--sends a text string to the server and exits.
--
-- #include <stdio.h>
-- #include <errno.h>
-- #include <stdlib.h>
-- #include <unistd.h>
-- #include <sys/types.h>
-- #include <sys/socket.h>
-- #include <netinet/in.h>
-- #include <netdb.h>
--
-- #define PORT 5555
-- #define MESSAGE "Yow!!! Are we having fun yet?!?"
-- #define SERVERHOST "churchy.gnu.ai.mit.edu"
--
-- void
-- write_to_server (int filedes)
-- {
-- int nbytes;
--
-- nbytes = write (filedes, MESSAGE, strlen (MESSAGE) + 1);
-- if (nbytes < 0)
-- {
-- perror ("write");
-- exit (EXIT_FAILURE);
-- }
-- }
--
--
-- int
-- main (void)
-- {
-- extern void init_sockaddr (struct sockaddr_in *name,
-- const char *hostname,
-- unsigned short int port);
-- int sock;
-- struct sockaddr_in servername;
--
-- /* Create the socket. */
-- sock = socket (PF_INET, SOCK_STREAM, 0);
-- if (sock < 0)
-- {
-- perror ("socket (client)");
-- exit (EXIT_FAILURE);
-- }
--
-- /* Connect to the server. */
-- init_sockaddr (&servername, SERVERHOST, PORT);
-- if (0 > connect (sock,
-- (struct sockaddr *) &servername,
-- sizeof (servername)))
-- {
-- perror ("connect (client)");
-- exit (EXIT_FAILURE);
-- }
--
-- /* Send data to the server. */
-- write_to_server (sock);
-- close (sock);
-- exit (EXIT_SUCCESS);
-- }
--
--
--File: libc.info, Node: Server Example, Next: Out-of-Band Data, Prev: Byte
Stream Example, Up: Connections
--
--Byte Stream Connection Server Example
---------------------------------------
--
-- The server end is much more complicated. Since we want to allow
--multiple clients to be connected to the server at the same time, it
--would be incorrect to wait for input from a single client by simply
--calling `read' or `recv'. Instead, the right thing to do is to use
--`select' (*note Waiting for I/O::.) to wait for input on all of the
--open sockets. This also allows the server to deal with additional
--connection requests.
--
-- This particular server doesn't do anything interesting once it has
--gotten a message from a client. It does close the socket for that
--client when it detects an end-of-file condition (resulting from the
--client shutting down its end of the connection).
--
-- This program uses `make_socket' and `init_sockaddr' to set up the
--socket address; see *Note Inet Example::.
--
-- #include <stdio.h>
-- #include <errno.h>
-- #include <stdlib.h>
-- #include <unistd.h>
-- #include <sys/types.h>
-- #include <sys/socket.h>
-- #include <netinet/in.h>
-- #include <netdb.h>
--
-- #define PORT 5555
-- #define MAXMSG 512
--
-- int
-- read_from_client (int filedes)
-- {
-- char buffer[MAXMSG];
-- int nbytes;
--
-- nbytes = read (filedes, buffer, MAXMSG);
-- if (nbytes < 0)
-- {
-- /* Read error. */
-- perror ("read");
-- exit (EXIT_FAILURE);
-- }
-- else if (nbytes == 0)
-- /* End-of-file. */
-- return -1;
-- else
-- {
-- /* Data read. */
-- fprintf (stderr, "Server: got message: `%s'\n", buffer);
-- return 0;
-- }
-- }
--
-- int
-- main (void)
-- {
-- extern int make_socket (unsigned short int port);
-- int sock;
-- fd_set active_fd_set, read_fd_set;
-- int i;
-- struct sockaddr_in clientname;
-- size_t size;
--
-- /* Create the socket and set it up to accept connections. */
-- sock = make_socket (PORT);
-- if (listen (sock, 1) < 0)
-- {
-- perror ("listen");
-- exit (EXIT_FAILURE);
-- }
--
-- /* Initialize the set of active sockets. */
-- FD_ZERO (&active_fd_set);
-- FD_SET (sock, &active_fd_set);
--
-- while (1)
-- {
-- /* Block until input arrives on one or more active sockets. */
-- read_fd_set = active_fd_set;
-- if (select (FD_SETSIZE, &read_fd_set, NULL, NULL, NULL) < 0)
-- {
-- perror ("select");
-- exit (EXIT_FAILURE);
-- }
--
-- /* Service all the sockets with input pending. */
-- for (i = 0; i < FD_SETSIZE; ++i)
-- if (FD_ISSET (i, &read_fd_set))
-- {
-- if (i == sock)
-- {
-- /* Connection request on original socket. */
-- int new;
-- size = sizeof (clientname);
-- new = accept (sock,
-- (struct sockaddr *) &clientname,
-- &size);
-- if (new < 0)
-- {
-- perror ("accept");
-- exit (EXIT_FAILURE);
-- }
-- fprintf (stderr,
-- "Server: connect from host %s, port %hd.\n",
-- inet_ntoa (clientname.sin_addr),
-- ntohs (clientname.sin_port));
-- FD_SET (new, &active_fd_set);
-- }
-- else
-- {
-- /* Data arriving on an already-connected socket. */
-- if (read_from_client (i) < 0)
-- {
-- close (i);
-- FD_CLR (i, &active_fd_set);
-- }
-- }
-- }
-- }
-- }
--
--
--File: libc.info, Node: Out-of-Band Data, Prev: Server Example, Up:
Connections
--
--Out-of-Band Data
------------------
--
-- Streams with connections permit "out-of-band" data that is delivered
--with higher priority than ordinary data. Typically the reason for
--sending out-of-band data is to send notice of an exceptional condition.
--The way to send out-of-band data is using `send', specifying the flag
--`MSG_OOB' (*note Sending Data::.).
--
-- Out-of-band data is received with higher priority because the
--receiving process need not read it in sequence; to read the next
--available out-of-band data, use `recv' with the `MSG_OOB' flag (*note
--Receiving Data::.). Ordinary read operations do not read out-of-band
--data; they read only the ordinary data.
--
-- When a socket finds that out-of-band data is on its way, it sends a
--`SIGURG' signal to the owner process or process group of the socket.
--You can specify the owner using the `F_SETOWN' command to the `fcntl'
--function; see *Note Interrupt Input::. You must also establish a
--handler for this signal, as described in *Note Signal Handling::, in
--order to take appropriate action such as reading the out-of-band data.
--
-- Alternatively, you can test for pending out-of-band data, or wait
--until there is out-of-band data, using the `select' function; it can
--wait for an exceptional condition on the socket. *Note Waiting for
--I/O::, for more information about `select'.
--
-- Notification of out-of-band data (whether with `SIGURG' or with
--`select') indicates that out-of-band data is on the way; the data may
--not actually arrive until later. If you try to read the out-of-band
--data before it arrives, `recv' fails with an `EWOULDBLOCK' error.
--
-- Sending out-of-band data automatically places a "mark" in the stream
--of ordinary data, showing where in the sequence the out-of-band data
--"would have been". This is useful when the meaning of out-of-band data
--is "cancel everything sent so far". Here is how you can test, in the
--receiving process, whether any ordinary data was sent before the mark:
--
-- success = ioctl (socket, SIOCATMARK, &result);
--
-- Here's a function to discard any ordinary data preceding the
--out-of-band mark:
--
-- int
-- discard_until_mark (int socket)
-- {
-- while (1)
-- {
-- /* This is not an arbitrary limit; any size will do. */
-- char buffer[1024];
-- int result, success;
--
-- /* If we have reached the mark, return. */
-- success = ioctl (socket, SIOCATMARK, &result);
-- if (success < 0)
-- perror ("ioctl");
-- if (result)
-- return;
--
-- /* Otherwise, read a bunch of ordinary data and discard it.
-- This is guaranteed not to read past the mark
-- if it starts before the mark. */
-- success = read (socket, buffer, sizeof buffer);
-- if (success < 0)
-- perror ("read");
-- }
-- }
--
-- If you don't want to discard the ordinary data preceding the mark,
--you may need to read some of it anyway, to make room in internal system
--buffers for the out-of-band data. If you try to read out-of-band data
--and get an `EWOULDBLOCK' error, try reading some ordinary data (saving
--it so that you can use it when you want it) and see if that makes room.
--Here is an example:
--
-- struct buffer
-- {
-- char *buffer;
-- int size;
-- struct buffer *next;
-- };
--
-- /* Read the out-of-band data from SOCKET and return it
-- as a `struct buffer', which records the address of the data
-- and its size.
--
-- It may be necessary to read some ordinary data
-- in order to make room for the out-of-band data.
-- If so, the ordinary data is saved as a chain of buffers
-- found in the `next' field of the value. */
--
-- struct buffer *
-- read_oob (int socket)
-- {
-- struct buffer *tail = 0;
-- struct buffer *list = 0;
--
-- while (1)
-- {
-- /* This is an arbitrary limit.
-- Does anyone know how to do this without a limit? */
-- char *buffer = (char *) xmalloc (1024);
-- struct buffer *link;
-- int success;
-- int result;
--
-- /* Try again to read the out-of-band data. */
-- success = recv (socket, buffer, sizeof buffer, MSG_OOB);
-- if (success >= 0)
-- {
-- /* We got it, so return it. */
-- struct buffer *link
-- = (struct buffer *) xmalloc (sizeof (struct buffer));
-- link->buffer = buffer;
-- link->size = success;
-- link->next = list;
-- return link;
-- }
--
-- /* If we fail, see if we are at the mark. */
-- success = ioctl (socket, SIOCATMARK, &result);
-- if (success < 0)
-- perror ("ioctl");
-- if (result)
-- {
-- /* At the mark; skipping past more ordinary data cannot help.
-- So just wait a while. */
-- sleep (1);
-- continue;
-- }
--
-- /* Otherwise, read a bunch of ordinary data and save it.
-- This is guaranteed not to read past the mark
-- if it starts before the mark. */
-- success = read (socket, buffer, sizeof buffer);
-- if (success < 0)
-- perror ("read");
--
-- /* Save this data in the buffer list. */
-- {
-- struct buffer *link
-- = (struct buffer *) xmalloc (sizeof (struct buffer));
-- link->buffer = buffer;
-- link->size = success;
--
-- /* Add the new link to the end of the list. */
-- if (tail)
-- tail->next = link;
-- else
-- list = link;
-- tail = link;
-- }
-- }
-- }
--
--
--File: libc.info, Node: Datagrams, Next: Inetd, Prev: Connections, Up:
Sockets
--
--Datagram Socket Operations
--==========================
--
-- This section describes how to use communication styles that don't use
--connections (styles `SOCK_DGRAM' and `SOCK_RDM'). Using these styles,
--you group data into packets and each packet is an independent
--communication. You specify the destination for each packet
--individually.
--
-- Datagram packets are like letters: you send each one independently,
--with its own destination address, and they may arrive in the wrong
--order or not at all.
--
-- The `listen' and `accept' functions are not allowed for sockets
--using connectionless communication styles.
--
--* Menu:
--
--* Sending Datagrams:: Sending packets on a datagram socket.
--* Receiving Datagrams:: Receiving packets on a datagram socket.
--* Datagram Example:: An example program: packets sent over a
-- datagram socket in the file namespace.
--* Example Receiver:: Another program, that receives those packets.
--
--
--File: libc.info, Node: Sending Datagrams, Next: Receiving Datagrams, Up:
Datagrams
--
--Sending Datagrams
-------------------
--
-- The normal way of sending data on a datagram socket is by using the
--`sendto' function, declared in `sys/socket.h'.
--
-- You can call `connect' on a datagram socket, but this only specifies
--a default destination for further data transmission on the socket.
--When a socket has a default destination, then you can use `send' (*note
--Sending Data::.) or even `write' (*note I/O Primitives::.) to send a
--packet there. You can cancel the default destination by calling
--`connect' using an address format of `AF_UNSPEC' in the ADDR argument.
--*Note Connecting::, for more information about the `connect' function.
--
-- - Function: int sendto (int SOCKET, void *BUFFER. size_t SIZE, int
-- FLAGS, struct sockaddr *ADDR, size_t LENGTH)
-- The `sendto' function transmits the data in the BUFFER through the
-- socket SOCKET to the destination address specified by the ADDR and
-- LENGTH arguments. The SIZE argument specifies the number of bytes
-- to be transmitted.
--
-- The FLAGS are interpreted the same way as for `send'; see *Note
-- Socket Data Options::.
--
-- The return value and error conditions are also the same as for
-- `send', but you cannot rely on the system to detect errors and
-- report them; the most common error is that the packet is lost or
-- there is no one at the specified address to receive it, and the
-- operating system on your machine usually does not know this.
--
-- It is also possible for one call to `sendto' to report an error
-- due to a problem related to a previous call.
--
--
--File: libc.info, Node: Receiving Datagrams, Next: Datagram Example, Prev:
Sending Datagrams, Up: Datagrams
--
--Receiving Datagrams
---------------------
--
-- The `recvfrom' function reads a packet from a datagram socket and
--also tells you where it was sent from. This function is declared in
--`sys/socket.h'.
--
-- - Function: int recvfrom (int SOCKET, void *BUFFER, size_t SIZE, int
-- FLAGS, struct sockaddr *ADDR, size_t *LENGTH-PTR)
-- The `recvfrom' function reads one packet from the socket SOCKET
-- into the buffer BUFFER. The SIZE argument specifies the maximum
-- number of bytes to be read.
--
-- If the packet is longer than SIZE bytes, then you get the first
-- SIZE bytes of the packet, and the rest of the packet is lost.
-- There's no way to read the rest of the packet. Thus, when you use
-- a packet protocol, you must always know how long a packet to
-- expect.
--
-- The ADDR and LENGTH-PTR arguments are used to return the address
-- where the packet came from. *Note Socket Addresses::. For a
-- socket in the file domain, the address information won't be
-- meaningful, since you can't read the address of such a socket
-- (*note File Namespace::.). You can specify a null pointer as the
-- ADDR argument if you are not interested in this information.
--
-- The FLAGS are interpreted the same way as for `recv' (*note Socket
-- Data Options::.). The return value and error conditions are also
-- the same as for `recv'.
--
-- You can use plain `recv' (*note Receiving Data::.) instead of
--`recvfrom' if you know don't need to find out who sent the packet
--(either because you know where it should come from or because you treat
--all possible senders alike). Even `read' can be used if you don't want
--to specify FLAGS (*note I/O Primitives::.).
--
--
--File: libc.info, Node: Datagram Example, Next: Example Receiver, Prev:
Receiving Datagrams, Up: Datagrams
--
--Datagram Socket Example
-------------------------
--
-- Here is a set of example programs that send messages over a datagram
--stream in the file namespace. Both the client and server programs use
--the `make_named_socket' function that was presented in *Note File
--Namespace::, to create and name their sockets.
--
-- First, here is the server program. It sits in a loop waiting for
--messages to arrive, bouncing each message back to the sender.
--Obviously, this isn't a particularly useful program, but it does show
--the general ideas involved.
--
-- #include <stdio.h>
-- #include <errno.h>
-- #include <stdlib.h>
-- #include <sys/socket.h>
-- #include <sys/un.h>
--
-- #define SERVER "/tmp/serversocket"
-- #define MAXMSG 512
--
-- int
-- main (void)
-- {
-- int sock;
-- char message[MAXMSG];
-- struct sockaddr_un name;
-- size_t size;
-- int nbytes;
--
-- /* Make the socket, then loop endlessly. */
--
-- sock = make_named_socket (SERVER);
-- while (1)
-- {
-- /* Wait for a datagram. */
-- size = sizeof (name);
-- nbytes = recvfrom (sock, message, MAXMSG, 0,
-- (struct sockaddr *) & name, &size);
-- if (nbytes < 0)
-- {
-- perror ("recfrom (server)");
-- exit (EXIT_FAILURE);
-- }
--
-- /* Give a diagnostic message. */
-- fprintf (stderr, "Server: got message: %s\n", message);
--
-- /* Bounce the message back to the sender. */
-- nbytes = sendto (sock, message, nbytes, 0,
-- (struct sockaddr *) & name, size);
-- if (nbytes < 0)
-- {
-- perror ("sendto (server)");
-- exit (EXIT_FAILURE);
-- }
-- }
-- }
--
--
--File: libc.info, Node: Example Receiver, Prev: Datagram Example, Up:
Datagrams
--
--Example of Reading Datagrams
------------------------------
--
-- Here is the client program corresponding to the server above.
--
-- It sends a datagram to the server and then waits for a reply. Notice
--that the socket for the client (as well as for the server) in this
--example has to be given a name. This is so that the server can direct
--a message back to the client. Since the socket has no associated
--connection state, the only way the server can do this is by referencing
--the name of the client.
--
-- #include <stdio.h>
-- #include <errno.h>
-- #include <unistd.h>
-- #include <stdlib.h>
-- #include <sys/socket.h>
-- #include <sys/un.h>
--
-- #define SERVER "/tmp/serversocket"
-- #define CLIENT "/tmp/mysocket"
-- #define MAXMSG 512
-- #define MESSAGE "Yow!!! Are we having fun yet?!?"
--
-- int
-- main (void)
-- {
-- extern int make_named_socket (const char *name);
-- int sock;
-- char message[MAXMSG];
-- struct sockaddr_un name;
-- size_t size;
-- int nbytes;
--
-- /* Make the socket. */
-- sock = make_named_socket (CLIENT);
--
-- /* Initialize the server socket address. */
-- name.sun_family = AF_UNIX;
-- strcpy (name.sun_path, SERVER);
-- size = strlen (name.sun_path) + sizeof (name.sun_family);
--
-- /* Send the datagram. */
-- nbytes = sendto (sock, MESSAGE, strlen (MESSAGE) + 1, 0,
-- (struct sockaddr *) & name, size);
-- if (nbytes < 0)
-- {
-- perror ("sendto (client)");
-- exit (EXIT_FAILURE);
-- }
--
-- /* Wait for a reply. */
-- nbytes = recvfrom (sock, message, MAXMSG, 0, NULL, 0);
-- if (nbytes < 0)
-- {
-- perror ("recfrom (client)");
-- exit (EXIT_FAILURE);
-- }
--
-- /* Print a diagnostic message. */
-- fprintf (stderr, "Client: got message: %s\n", message);
--
-- /* Clean up. */
-- remove (CLIENT);
-- close (sock);
-- }
--
-- Keep in mind that datagram socket communications are unreliable. In
--this example, the client program waits indefinitely if the message
--never reaches the server or if the server's response never comes back.
--It's up to the user running the program to kill it and restart it, if
--desired. A more automatic solution could be to use `select' (*note
--Waiting for I/O::.) to establish a timeout period for the reply, and in
--case of timeout either resend the message or shut down the socket and
--exit.
--
--
--File: libc.info, Node: Inetd, Next: Socket Options, Prev: Datagrams, Up:
Sockets
--
--The `inetd' Daemon
--==================
--
-- We've explained above how to write a server program that does its own
--listening. Such a server must already be running in order for anyone
--to connect to it.
--
-- Another way to provide service for an Internet port is to let the
--daemon program `inetd' do the listening. `inetd' is a program that
--runs all the time and waits (using `select') for messages on a
--specified set of ports. When it receives a message, it accepts the
--connection (if the socket style calls for connections) and then forks a
--child process to run the corresponding server program. You specify the
--ports and their programs in the file `/etc/inetd.conf'.
--
--* Menu:
--
--* Inetd Servers::
--* Configuring Inetd::
--
--
--File: libc.info, Node: Inetd Servers, Next: Configuring Inetd, Up: Inetd
--
--`inetd' Servers
-----------------
--
-- Writing a server program to be run by `inetd' is very simple. Each
--time someone requests a connection to the appropriate port, a new server
--process starts. The connection already exists at this time; the socket
--is available as the standard input descriptor and as the standard
--output descriptor (descriptors 0 and 1) in the server process. So the
--server program can begin reading and writing data right away. Often
--the program needs only the ordinary I/O facilities; in fact, a
--general-purpose filter program that knows nothing about sockets can
--work as a byte stream server run by `inetd'.
--
-- You can also use `inetd' for servers that use connectionless
--communication styles. For these servers, `inetd' does not try to accept
--a connection, since no connection is possible. It just starts the
--server program, which can read the incoming datagram packet from
--descriptor 0. The server program can handle one request and then exit,
--or you can choose to write it to keep reading more requests until no
--more arrive, and then exit. You must specify which of these two
--techniques the server uses, when you configure `inetd'.
--
--
--File: libc.info, Node: Configuring Inetd, Prev: Inetd Servers, Up: Inetd
--
--Configuring `inetd'
---------------------
--
-- The file `/etc/inetd.conf' tells `inetd' which ports to listen to
--and what server programs to run for them. Normally each entry in the
--file is one line, but you can split it onto multiple lines provided all
--but the first line of the entry start with whitespace. Lines that
--start with `#' are comments.
--
-- Here are two standard entries in `/etc/inetd.conf':
--
-- ftp stream tcp nowait root /libexec/ftpd ftpd
-- talk dgram udp wait root /libexec/talkd talkd
--
-- An entry has this format:
--
-- SERVICE STYLE PROTOCOL WAIT USERNAME PROGRAM ARGUMENTS
--
-- The SERVICE field says which service this program provides. It
--should be the name of a service defined in `/etc/services'. `inetd'
--uses SERVICE to decide which port to listen on for this entry.
--
-- The fields STYLE and PROTOCOL specify the communication style and
--the protocol to use for the listening socket. The style should be the
--name of a communication style, converted to lower case and with `SOCK_'
--deleted--for example, `stream' or `dgram'. PROTOCOL should be one of
--the protocols listed in `/etc/protocols'. The typical protocol names
--are `tcp' for byte stream connections and `udp' for unreliable
--datagrams.
--
-- The WAIT field should be either `wait' or `nowait'. Use `wait' if
--STYLE is a connectionless style and the server, once started, handles
--multiple requests, as many as come in. Use `nowait' if `inetd' should
--start a new process for each message or request that comes in. If
--STYLE uses connections, then WAIT *must* be `nowait'.
--
-- USER is the user name that the server should run as. `inetd' runs
--as root, so it can set the user ID of its children arbitrarily. It's
--best to avoid using `root' for USER if you can; but some servers, such
--as Telnet and FTP, read a username and password themselves. These
--servers need to be root initially so they can log in as commanded by
--the data coming over the network.
--
-- PROGRAM together with ARGUMENTS specifies the command to run to
--start the server. PROGRAM should be an absolute file name specifying
--the executable file to run. ARGUMENTS consists of any number of
--whitespace-separated words, which become the command-line arguments of
--PROGRAM. The first word in ARGUMENTS is argument zero, which should by
--convention be the program name itself (sans directories).
--
-- If you edit `/etc/inetd.conf', you can tell `inetd' to reread the
--file and obey its new contents by sending the `inetd' process the
--`SIGHUP' signal. You'll have to use `ps' to determine the process ID
--of the `inetd' process, as it is not fixed.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-14
glibc-2.0.1/manual/libc.info-14
---- ../glibc-2.0.1/manual/libc.info-14 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-14 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1159 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Socket Options, Next: Networks Database, Prev:
Inetd, Up: Sockets
--
--Socket Options
--==============
--
-- This section describes how to read or set various options that modify
--the behavior of sockets and their underlying communications protocols.
--
-- When you are manipulating a socket option, you must specify which
--"level" the option pertains to. This describes whether the option
--applies to the socket interface, or to a lower-level communications
--protocol interface.
--
--* Menu:
--
--* Socket Option Functions:: The basic functions for setting and getting
-- socket options.
--* Socket-Level Options:: Details of the options at the socket level.
--
--
--File: libc.info, Node: Socket Option Functions, Next: Socket-Level Options,
Up: Socket Options
--
--Socket Option Functions
-------------------------
--
-- Here are the functions for examining and modifying socket options.
--They are declared in `sys/socket.h'.
--
-- - Function: int getsockopt (int SOCKET, int LEVEL, int OPTNAME, void
-- *OPTVAL, size_t *OPTLEN-PTR)
-- The `getsockopt' function gets information about the value of
-- option OPTNAME at level LEVEL for socket SOCKET.
--
-- The option value is stored in a buffer that OPTVAL points to.
-- Before the call, you should supply in `*OPTLEN-PTR' the size of
-- this buffer; on return, it contains the number of bytes of
-- information actually stored in the buffer.
--
-- Most options interpret the OPTVAL buffer as a single `int' value.
--
-- The actual return value of `getsockopt' is `0' on success and `-1'
-- on failure. The following `errno' error conditions are defined:
--
-- `EBADF'
-- The SOCKET argument is not a valid file descriptor.
--
-- `ENOTSOCK'
-- The descriptor SOCKET is not a socket.
--
-- `ENOPROTOOPT'
-- The OPTNAME doesn't make sense for the given LEVEL.
--
-- - Function: int setsockopt (int SOCKET, int LEVEL, int OPTNAME, void
-- *OPTVAL, size_t OPTLEN)
-- This function is used to set the socket option OPTNAME at level
-- LEVEL for socket SOCKET. The value of the option is passed in the
-- buffer OPTVAL, which has size OPTLEN.
--
-- The return value and error codes for `setsockopt' are the same as
-- for `getsockopt'.
--
--
--File: libc.info, Node: Socket-Level Options, Prev: Socket Option Functions,
Up: Socket Options
--
--Socket-Level Options
----------------------
--
-- - Constant: int SOL_SOCKET
-- Use this constant as the LEVEL argument to `getsockopt' or
-- `setsockopt' to manipulate the socket-level options described in
-- this section.
--
-- Here is a table of socket-level option names; all are defined in the
--header file `sys/socket.h'.
--
--`SO_DEBUG'
-- This option toggles recording of debugging information in the
-- underlying protocol modules. The value has type `int'; a nonzero
-- value means "yes".
--
--`SO_REUSEADDR'
-- This option controls whether `bind' (*note Setting Address::.)
-- should permit reuse of local addresses for this socket. If you
-- enable this option, you can actually have two sockets with the
-- same Internet port number; but the system won't allow you to use
-- the two identically-named sockets in a way that would confuse the
-- Internet. The reason for this option is that some higher-level
-- Internet protocols, including FTP, require you to keep reusing the
-- same socket number.
--
-- The value has type `int'; a nonzero value means "yes".
--
--`SO_KEEPALIVE'
-- This option controls whether the underlying protocol should
-- periodically transmit messages on a connected socket. If the peer
-- fails to respond to these messages, the connection is considered
-- broken. The value has type `int'; a nonzero value means "yes".
--
--`SO_DONTROUTE'
-- This option controls whether outgoing messages bypass the normal
-- message routing facilities. If set, messages are sent directly to
-- the network interface instead. The value has type `int'; a nonzero
-- value means "yes".
--
--`SO_LINGER'
-- This option specifies what should happen when the socket of a type
-- that promises reliable delivery still has untransmitted messages
-- when it is closed; see *Note Closing a Socket::. The value has
-- type `struct linger'.
--
-- - Data Type: struct linger
-- This structure type has the following members:
--
-- `int l_onoff'
-- This field is interpreted as a boolean. If nonzero,
-- `close' blocks until the data is transmitted or the
-- timeout period has expired.
--
-- `int l_linger'
-- This specifies the timeout period, in seconds.
--
--`SO_BROADCAST'
-- This option controls whether datagrams may be broadcast from the
-- socket. The value has type `int'; a nonzero value means "yes".
--
--`SO_OOBINLINE'
-- If this option is set, out-of-band data received on the socket is
-- placed in the normal input queue. This permits it to be read using
-- `read' or `recv' without specifying the `MSG_OOB' flag. *Note
-- Out-of-Band Data::. The value has type `int'; a nonzero value
-- means "yes".
--
--`SO_SNDBUF'
-- This option gets or sets the size of the output buffer. The value
-- is a `size_t', which is the size in bytes.
--
--`SO_RCVBUF'
-- This option gets or sets the size of the input buffer. The value
-- is a `size_t', which is the size in bytes.
--
--`SO_STYLE'
--`SO_TYPE'
-- This option can be used with `getsockopt' only. It is used to get
-- the socket's communication style. `SO_TYPE' is the historical
-- name, and `SO_STYLE' is the preferred name in GNU. The value has
-- type `int' and its value designates a communication style; see
-- *Note Communication Styles::.
--
--`SO_ERROR'
-- This option can be used with `getsockopt' only. It is used to
-- reset the error status of the socket. The value is an `int',
-- which represents the previous error status.
--
--
--File: libc.info, Node: Networks Database, Prev: Socket Options, Up: Sockets
--
--Networks Database
--=================
--
-- Many systems come with a database that records a list of networks
--known to the system developer. This is usually kept either in the file
--`/etc/networks' or in an equivalent from a name server. This data base
--is useful for routing programs such as `route', but it is not useful
--for programs that simply communicate over the network. We provide
--functions to access this data base, which are declared in `netdb.h'.
--
-- - Data Type: struct netent
-- This data type is used to represent information about entries in
-- the networks database. It has the following members:
--
-- `char *n_name'
-- This is the "official" name of the network.
--
-- `char **n_aliases'
-- These are alternative names for the network, represented as a
-- vector of strings. A null pointer terminates the array.
--
-- `int n_addrtype'
-- This is the type of the network number; this is always equal
-- to `AF_INET' for Internet networks.
--
-- `unsigned long int n_net'
-- This is the network number. Network numbers are returned in
-- host byte order; see *Note Byte Order::.
--
-- Use the `getnetbyname' or `getnetbyaddr' functions to search the
--networks database for information about a specific network. The
--information is returned in a statically-allocated structure; you must
--copy the information if you need to save it.
--
-- - Function: struct netent * getnetbyname (const char *NAME)
-- The `getnetbyname' function returns information about the network
-- named NAME. It returns a null pointer if there is no such network.
--
-- - Function: struct netent * getnetbyaddr (long NET, int TYPE)
-- The `getnetbyaddr' function returns information about the network
-- of type TYPE with number NET. You should specify a value of
-- `AF_INET' for the TYPE argument for Internet networks.
--
-- `getnetbyaddr' returns a null pointer if there is no such network.
--
-- You can also scan the networks database using `setnetent',
--`getnetent', and `endnetent'. Be careful in using these functions,
--because they are not reentrant.
--
-- - Function: void setnetent (int STAYOPEN)
-- This function opens and rewinds the networks database.
--
-- If the STAYOPEN argument is nonzero, this sets a flag so that
-- subsequent calls to `getnetbyname' or `getnetbyaddr' will not
-- close the database (as they usually would). This makes for more
-- efficiency if you call those functions several times, by avoiding
-- reopening the database for each call.
--
-- - Function: struct netent * getnetent (void)
-- This function returns the next entry in the networks database. It
-- returns a null pointer if there are no more entries.
--
-- - Function: void endnetent (void)
-- This function closes the networks database.
--
--
--File: libc.info, Node: Low-Level Terminal Interface, Next: Mathematics,
Prev: Sockets, Up: Top
--
--Low-Level Terminal Interface
--****************************
--
-- This chapter describes functions that are specific to terminal
--devices. You can use these functions to do things like turn off input
--echoing; set serial line characteristics such as line speed and flow
--control; and change which characters are used for end-of-file,
--command-line editing, sending signals, and similar control functions.
--
-- Most of the functions in this chapter operate on file descriptors.
--*Note Low-Level I/O::, for more information about what a file
--descriptor is and how to open a file descriptor for a terminal device.
--
--* Menu:
--
--* Is It a Terminal:: How to determine if a file is a terminal
-- device, and what its name is.
--* I/O Queues:: About flow control and typeahead.
--* Canonical or Not:: Two basic styles of input processing.
--* Terminal Modes:: How to examine and modify flags controlling
-- details of terminal I/O: echoing,
-- signals, editing.
--* Line Control:: Sending break sequences, clearing
-- terminal buffers ...
--* Noncanon Example:: How to read single characters without echo.
--
--
--File: libc.info, Node: Is It a Terminal, Next: I/O Queues, Up: Low-Level
Terminal Interface
--
--Identifying Terminals
--=====================
--
-- The functions described in this chapter only work on files that
--correspond to terminal devices. You can find out whether a file
--descriptor is associated with a terminal by using the `isatty' function.
--
-- Prototypes for both `isatty' and `ttyname' are declared in the
--header file `unistd.h'.
--
-- - Function: int isatty (int FILEDES)
-- This function returns `1' if FILEDES is a file descriptor
-- associated with an open terminal device, and `0' otherwise.
--
-- If a file descriptor is associated with a terminal, you can get its
--associated file name using the `ttyname' function. See also the
--`ctermid' function, described in *Note Identifying the Terminal::.
--
-- - Function: char * ttyname (int FILEDES)
-- If the file descriptor FILEDES is associated with a terminal
-- device, the `ttyname' function returns a pointer to a
-- statically-allocated, null-terminated string containing the file
-- name of the terminal file. The value is a null pointer if the
-- file descriptor isn't associated with a terminal, or the file name
-- cannot be determined.
--
--
--File: libc.info, Node: I/O Queues, Next: Canonical or Not, Prev: Is It a
Terminal, Up: Low-Level Terminal Interface
--
--I/O Queues
--==========
--
-- Many of the remaining functions in this section refer to the input
--and output queues of a terminal device. These queues implement a form
--of buffering *within the kernel* independent of the buffering
--implemented by I/O streams (*note I/O on Streams::.).
--
-- The "terminal input queue" is also sometimes referred to as its
--"typeahead buffer". It holds the characters that have been received
--from the terminal but not yet read by any process.
--
-- The size of the terminal's input queue is described by the
--`MAX_INPUT' and `_POSIX_MAX_INPUT' parameters; see *Note Limits for
--Files::. You are guaranteed a queue size of at least `MAX_INPUT', but
--the queue might be larger, and might even dynamically change size. If
--input flow control is enabled by setting the `IXOFF' input mode bit
--(*note Input Modes::.), the terminal driver transmits STOP and START
--characters to the terminal when necessary to prevent the queue from
--overflowing. Otherwise, input may be lost if it comes in too fast from
--the terminal. In canonical mode, all input stays in the queue until a
--newline character is received, so the terminal input queue can fill up
--when you type a very long line. *Note Canonical or Not::.
--
-- The "terminal output queue" is like the input queue, but for output;
--it contains characters that have been written by processes, but not yet
--transmitted to the terminal. If output flow control is enabled by
--setting the `IXON' input mode bit (*note Input Modes::.), the terminal
--driver obeys STOP and STOP characters sent by the terminal to stop and
--restart transmission of output.
--
-- "Clearing" the terminal input queue means discarding any characters
--that have been received but not yet read. Similarly, clearing the
--terminal output queue means discarding any characters that have been
--written but not yet transmitted.
--
--
--File: libc.info, Node: Canonical or Not, Next: Terminal Modes, Prev: I/O
Queues, Up: Low-Level Terminal Interface
--
--Two Styles of Input: Canonical or Not
--=====================================
--
-- POSIX systems support two basic modes of input: canonical and
--noncanonical.
--
-- In "canonical input processing" mode, terminal input is processed in
--lines terminated by newline (`'\n''), EOF, or EOL characters. No input
--can be read until an entire line has been typed by the user, and the
--`read' function (*note I/O Primitives::.) returns at most a single line
--of input, no matter how many bytes are requested.
--
-- In canonical input mode, the operating system provides input editing
--facilities: some characters are interpreted specially to perform editing
--operations within the current line of text, such as ERASE and KILL.
--*Note Editing Characters::.
--
-- The constants `_POSIX_MAX_CANON' and `MAX_CANON' parameterize the
--maximum number of bytes which may appear in a single line of canonical
--input. *Note Limits for Files::. You are guaranteed a maximum line
--length of at least `MAX_CANON' bytes, but the maximum might be larger,
--and might even dynamically change size.
--
-- In "noncanonical input processing" mode, characters are not grouped
--into lines, and ERASE and KILL processing is not performed. The
--granularity with which bytes are read in noncanonical input mode is
--controlled by the MIN and TIME settings. *Note Noncanonical Input::.
--
-- Most programs use canonical input mode, because this gives the user a
--way to edit input line by line. The usual reason to use noncanonical
--mode is when the program accepts single-character commands or provides
--its own editing facilities.
--
-- The choice of canonical or noncanonical input is controlled by the
--`ICANON' flag in the `c_lflag' member of `struct termios'. *Note Local
--Modes::.
--
--
--File: libc.info, Node: Terminal Modes, Next: Line Control, Prev: Canonical
or Not, Up: Low-Level Terminal Interface
--
--Terminal Modes
--==============
--
-- This section describes the various terminal attributes that control
--how input and output are done. The functions, data structures, and
--symbolic constants are all declared in the header file `termios.h'.
--
--* Menu:
--
--* Mode Data Types:: The data type `struct termios' and
-- related types.
--* Mode Functions:: Functions to read and set the terminal
-- attributes.
--* Setting Modes:: The right way to set terminal attributes
-- reliably.
--* Input Modes:: Flags controlling low-level input handling.
--* Output Modes:: Flags controlling low-level output handling.
--* Control Modes:: Flags controlling serial port behavior.
--* Local Modes:: Flags controlling high-level input handling.
--* Line Speed:: How to read and set the terminal line speed.
--* Special Characters:: Characters that have special effects,
-- and how to change them.
--* Noncanonical Input:: Controlling how long to wait for input.
--
--
--File: libc.info, Node: Mode Data Types, Next: Mode Functions, Up: Terminal
Modes
--
--Terminal Mode Data Types
--------------------------
--
-- The entire collection of attributes of a terminal is stored in a
--structure of type `struct termios'. This structure is used with the
--functions `tcgetattr' and `tcsetattr' to read and set the attributes.
--
-- - Data Type: struct termios
-- Structure that records all the I/O attributes of a terminal. The
-- structure includes at least the following members:
--
-- `tcflag_t c_iflag'
-- A bit mask specifying flags for input modes; see *Note Input
-- Modes::.
--
-- `tcflag_t c_oflag'
-- A bit mask specifying flags for output modes; see *Note
-- Output Modes::.
--
-- `tcflag_t c_cflag'
-- A bit mask specifying flags for control modes; see *Note
-- Control Modes::.
--
-- `tcflag_t c_lflag'
-- A bit mask specifying flags for local modes; see *Note Local
-- Modes::.
--
-- `cc_t c_cc[NCCS]'
-- An array specifying which characters are associated with
-- various control functions; see *Note Special Characters::.
--
-- The `struct termios' structure also contains members which encode
-- input and output transmission speeds, but the representation is
-- not specified. *Note Line Speed::, for how to examine and store
-- the speed values.
--
-- The following sections describe the details of the members of the
--`struct termios' structure.
--
-- - Data Type: tcflag_t
-- This is an unsigned integer type used to represent the various bit
-- masks for terminal flags.
--
-- - Data Type: cc_t
-- This is an unsigned integer type used to represent characters
-- associated with various terminal control functions.
--
-- - Macro: int NCCS
-- The value of this macro is the number of elements in the `c_cc'
-- array.
--
--
--File: libc.info, Node: Mode Functions, Next: Setting Modes, Prev: Mode
Data Types, Up: Terminal Modes
--
--Terminal Mode Functions
-------------------------
--
-- - Function: int tcgetattr (int FILEDES, struct termios *TERMIOS-P)
-- This function is used to examine the attributes of the terminal
-- device with file descriptor FILEDES. The attributes are returned
-- in the structure that TERMIOS-P points to.
--
-- If successful, `tcgetattr' returns `0'. A return value of `-1'
-- indicates an error. The following `errno' error conditions are
-- defined for this function:
--
-- `EBADF'
-- The FILEDES argument is not a valid file descriptor.
--
-- `ENOTTY'
-- The FILEDES is not associated with a terminal.
--
-- - Function: int tcsetattr (int FILEDES, int WHEN, const struct termios
-- *TERMIOS-P)
-- This function sets the attributes of the terminal device with file
-- descriptor FILEDES. The new attributes are taken from the
-- structure that TERMIOS-P points to.
--
-- The WHEN argument specifies how to deal with input and output
-- already queued. It can be one of the following values:
--
-- `TCSANOW'
-- Make the change immediately.
--
-- `TCSADRAIN'
-- Make the change after waiting until all queued output has
-- been written. You should usually use this option when
-- changing parameters that affect output.
--
-- `TCSAFLUSH'
-- This is like `TCSADRAIN', but also discards any queued input.
--
-- `TCSASOFT'
-- This is a flag bit that you can add to any of the above
-- alternatives. Its meaning is to inhibit alteration of the
-- state of the terminal hardware. It is a BSD extension; it is
-- only supported on BSD systems and the GNU system.
--
-- Using `TCSASOFT' is exactly the same as setting the `CIGNORE'
-- bit in the `c_cflag' member of the structure TERMIOS-P points
-- to. *Note Control Modes::, for a description of `CIGNORE'.
--
-- If this function is called from a background process on its
-- controlling terminal, normally all processes in the process group
-- are sent a `SIGTTOU' signal, in the same way as if the process
-- were trying to write to the terminal. The exception is if the
-- calling process itself is ignoring or blocking `SIGTTOU' signals,
-- in which case the operation is performed and no signal is sent.
-- *Note Job Control::.
--
-- If successful, `tcsetattr' returns `0'. A return value of `-1'
-- indicates an error. The following `errno' error conditions are
-- defined for this function:
--
-- `EBADF'
-- The FILEDES argument is not a valid file descriptor.
--
-- `ENOTTY'
-- The FILEDES is not associated with a terminal.
--
-- `EINVAL'
-- Either the value of the `when' argument is not valid, or
-- there is something wrong with the data in the TERMIOS-P
-- argument.
--
-- Although `tcgetattr' and `tcsetattr' specify the terminal device
--with a file descriptor, the attributes are those of the terminal device
--itself and not of the file descriptor. This means that the effects of
--changing terminal attributes are persistent; if another process opens
--the terminal file later on, it will see the changed attributes even
--though it doesn't have anything to do with the open file descriptor you
--originally specified in changing the attributes.
--
-- Similarly, if a single process has multiple or duplicated file
--descriptors for the same terminal device, changing the terminal
--attributes affects input and output to all of these file descriptors.
--This means, for example, that you can't open one file descriptor or
--stream to read from a terminal in the normal line-buffered, echoed
--mode; and simultaneously have another file descriptor for the same
--terminal that you use to read from it in single-character, non-echoed
--mode. Instead, you have to explicitly switch the terminal back and
--forth between the two modes.
--
--
--File: libc.info, Node: Setting Modes, Next: Input Modes, Prev: Mode
Functions, Up: Terminal Modes
--
--Setting Terminal Modes Properly
---------------------------------
--
-- When you set terminal modes, you should call `tcgetattr' first to
--get the current modes of the particular terminal device, modify only
--those modes that you are really interested in, and store the result with
--`tcsetattr'.
--
-- It's a bad idea to simply initialize a `struct termios' structure to
--a chosen set of attributes and pass it directly to `tcsetattr'. Your
--program may be run years from now, on systems that support members not
--documented in this manual. The way to avoid setting these members to
--unreasonable values is to avoid changing them.
--
-- What's more, different terminal devices may require different mode
--settings in order to function properly. So you should avoid blindly
--copying attributes from one terminal device to another.
--
-- When a member contains a collection of independent flags, as the
--`c_iflag', `c_oflag' and `c_cflag' members do, even setting the entire
--member is a bad idea, because particular operating systems have their
--own flags. Instead, you should start with the current value of the
--member and alter only the flags whose values matter in your program,
--leaving any other flags unchanged.
--
-- Here is an example of how to set one flag (`ISTRIP') in the `struct
--termios' structure while properly preserving all the other data in the
--structure:
--
-- int
-- set_istrip (int desc, int value)
-- {
-- struct termios settings;
-- int result;
--
-- result = tcgetattr (desc, &settings);
-- if (result < 0)
-- {
-- perror ("error in tcgetattr");
-- return 0;
-- }
--
-- settings.c_iflag &= ~ISTRIP;
-- if (value)
-- settings.c_iflag |= ISTRIP;
--
-- result = tcsetattr (desc, TCSANOW, &settings);
-- if (result < 0)
-- {
-- perror ("error in tcgetattr");
-- return;
-- }
-- return 1;
-- }
--
--
--File: libc.info, Node: Input Modes, Next: Output Modes, Prev: Setting
Modes, Up: Terminal Modes
--
--Input Modes
-------------
--
-- This section describes the terminal attribute flags that control
--fairly low-level aspects of input processing: handling of parity errors,
--break signals, flow control, and <RET> and <LFD> characters.
--
-- All of these flags are bits in the `c_iflag' member of the `struct
--termios' structure. The member is an integer, and you change flags
--using the operators `&', `|' and `^'. Don't try to specify the entire
--value for `c_iflag'--instead, change only specific flags and leave the
--rest untouched (*note Setting Modes::.).
--
-- - Macro: tcflag_t INPCK
-- If this bit is set, input parity checking is enabled. If it is
-- not set, no checking at all is done for parity errors on input; the
-- characters are simply passed through to the application.
--
-- Parity checking on input processing is independent of whether
-- parity detection and generation on the underlying terminal
-- hardware is enabled; see *Note Control Modes::. For example, you
-- could clear the `INPCK' input mode flag and set the `PARENB'
-- control mode flag to ignore parity errors on input, but still
-- generate parity on output.
--
-- If this bit is set, what happens when a parity error is detected
-- depends on whether the `IGNPAR' or `PARMRK' bits are set. If
-- neither of these bits are set, a byte with a parity error is
-- passed to the application as a `'\0'' character.
--
-- - Macro: tcflag_t IGNPAR
-- If this bit is set, any byte with a framing or parity error is
-- ignored. This is only useful if `INPCK' is also set.
--
-- - Macro: tcflag_t PARMRK
-- If this bit is set, input bytes with parity or framing errors are
-- marked when passed to the program. This bit is meaningful only
-- when `INPCK' is set and `IGNPAR' is not set.
--
-- The way erroneous bytes are marked is with two preceding bytes,
-- `377' and `0'. Thus, the program actually reads three bytes for
-- one erroneous byte received from the terminal.
--
-- If a valid byte has the value `0377', and `ISTRIP' (see below) is
-- not set, the program might confuse it with the prefix that marks a
-- parity error. So a valid byte `0377' is passed to the program as
-- two bytes, `0377' `0377', in this case.
--
-- - Macro: tcflag_t ISTRIP
-- If this bit is set, valid input bytes are stripped to seven bits;
-- otherwise, all eight bits are available for programs to read.
--
-- - Macro: tcflag_t IGNBRK
-- If this bit is set, break conditions are ignored.
--
-- A "break condition" is defined in the context of asynchronous
-- serial data transmission as a series of zero-value bits longer
-- than a single byte.
--
-- - Macro: tcflag_t BRKINT
-- If this bit is set and `IGNBRK' is not set, a break condition
-- clears the terminal input and output queues and raises a `SIGINT'
-- signal for the foreground process group associated with the
-- terminal.
--
-- If neither `BRKINT' nor `IGNBRK' are set, a break condition is
-- passed to the application as a single `'\0'' character if `PARMRK'
-- is not set, or otherwise as a three-character sequence `'\377'',
-- `'\0'', `'\0''.
--
-- - Macro: tcflag_t IGNCR
-- If this bit is set, carriage return characters (`'\r'') are
-- discarded on input. Discarding carriage return may be useful on
-- terminals that send both carriage return and linefeed when you
-- type the <RET> key.
--
-- - Macro: tcflag_t ICRNL
-- If this bit is set and `IGNCR' is not set, carriage return
-- characters (`'\r'') received as input are passed to the
-- application as newline characters (`'\n'').
--
-- - Macro: tcflag_t INLCR
-- If this bit is set, newline characters (`'\n'') received as input
-- are passed to the application as carriage return characters
-- (`'\r'').
--
-- - Macro: tcflag_t IXOFF
-- If this bit is set, start/stop control on input is enabled. In
-- other words, the computer sends STOP and START characters as
-- necessary to prevent input from coming in faster than programs are
-- reading it. The idea is that the actual terminal hardware that is
-- generating the input data responds to a STOP character by
-- suspending transmission, and to a START character by resuming
-- transmission. *Note Start/Stop Characters::.
--
-- - Macro: tcflag_t IXON
-- If this bit is set, start/stop control on output is enabled. In
-- other words, if the computer receives a STOP character, it
-- suspends output until a START character is received. In this
-- case, the STOP and START characters are never passed to the
-- application program. If this bit is not set, then START and STOP
-- can be read as ordinary characters. *Note Start/Stop Characters::.
--
-- - Macro: tcflag_t IXANY
-- If this bit is set, any input character restarts output when
-- output has been suspended with the STOP character. Otherwise,
-- only the START character restarts output.
--
-- This is a BSD extension; it exists only on BSD systems and the GNU
-- system.
--
-- - Macro: tcflag_t IMAXBEL
-- If this bit is set, then filling up the terminal input buffer
-- sends a BEL character (code `007') to the terminal to ring the
-- bell.
--
-- This is a BSD extension.
--
--
--File: libc.info, Node: Output Modes, Next: Control Modes, Prev: Input
Modes, Up: Terminal Modes
--
--Output Modes
--------------
--
-- This section describes the terminal flags and fields that control how
--output characters are translated and padded for display. All of these
--are contained in the `c_oflag' member of the `struct termios' structure.
--
-- The `c_oflag' member itself is an integer, and you change the flags
--and fields using the operators `&', `|', and `^'. Don't try to specify
--the entire value for `c_oflag'--instead, change only specific flags and
--leave the rest untouched (*note Setting Modes::.).
--
-- - Macro: tcflag_t OPOST
-- If this bit is set, output data is processed in some unspecified
-- way so that it is displayed appropriately on the terminal device.
-- This typically includes mapping newline characters (`'\n'') onto
-- carriage return and linefeed pairs.
--
-- If this bit isn't set, the characters are transmitted as-is.
--
-- The following three bits are BSD features, and they exist only BSD
--systems and the GNU system. They are effective only if `OPOST' is set.
--
-- - Macro: tcflag_t ONLCR
-- If this bit is set, convert the newline character on output into a
-- pair of characters, carriage return followed by linefeed.
--
-- - Macro: tcflag_t OXTABS
-- If this bit is set, convert tab characters on output into the
-- appropriate number of spaces to emulate a tab stop every eight
-- columns.
--
-- - Macro: tcflag_t ONOEOT
-- If this bit is set, discard `C-d' characters (code `004') on
-- output. These characters cause many dial-up terminals to
-- disconnect.
--
--
--File: libc.info, Node: Control Modes, Next: Local Modes, Prev: Output
Modes, Up: Terminal Modes
--
--Control Modes
---------------
--
-- This section describes the terminal flags and fields that control
--parameters usually associated with asynchronous serial data
--transmission. These flags may not make sense for other kinds of
--terminal ports (such as a network connection pseudo-terminal). All of
--these are contained in the `c_cflag' member of the `struct termios'
--structure.
--
-- The `c_cflag' member itself is an integer, and you change the flags
--and fields using the operators `&', `|', and `^'. Don't try to specify
--the entire value for `c_cflag'--instead, change only specific flags and
--leave the rest untouched (*note Setting Modes::.).
--
-- - Macro: tcflag_t CLOCAL
-- If this bit is set, it indicates that the terminal is connected
-- "locally" and that the modem status lines (such as carrier detect)
-- should be ignored.
--
-- On many systems if this bit is not set and you call `open' without
-- the `O_NONBLOCK' flag set, `open' blocks until a modem connection
-- is established.
--
-- If this bit is not set and a modem disconnect is detected, a
-- `SIGHUP' signal is sent to the controlling process group for the
-- terminal (if it has one). Normally, this causes the process to
-- exit; see *Note Signal Handling::. Reading from the terminal
-- after a disconnect causes an end-of-file condition, and writing
-- causes an `EIO' error to be returned. The terminal device must be
-- closed and reopened to clear the condition.
--
-- - Macro: tcflag_t HUPCL
-- If this bit is set, a modem disconnect is generated when all
-- processes that have the terminal device open have either closed
-- the file or exited.
--
-- - Macro: tcflag_t CREAD
-- If this bit is set, input can be read from the terminal.
-- Otherwise, input is discarded when it arrives.
--
-- - Macro: tcflag_t CSTOPB
-- If this bit is set, two stop bits are used. Otherwise, only one
-- stop bit is used.
--
-- - Macro: tcflag_t PARENB
-- If this bit is set, generation and detection of a parity bit are
-- enabled. *Note Input Modes::, for information on how input parity
-- errors are handled.
--
-- If this bit is not set, no parity bit is added to output
-- characters, and input characters are not checked for correct
-- parity.
--
-- - Macro: tcflag_t PARODD
-- This bit is only useful if `PARENB' is set. If `PARODD' is set,
-- odd parity is used, otherwise even parity is used.
--
-- The control mode flags also includes a field for the number of bits
--per character. You can use the `CSIZE' macro as a mask to extract the
--value, like this: `settings.c_cflag & CSIZE'.
--
-- - Macro: tcflag_t CSIZE
-- This is a mask for the number of bits per character.
--
-- - Macro: tcflag_t CS5
-- This specifies five bits per byte.
--
-- - Macro: tcflag_t CS6
-- This specifies six bits per byte.
--
-- - Macro: tcflag_t CS7
-- This specifies seven bits per byte.
--
-- - Macro: tcflag_t CS8
-- This specifies eight bits per byte.
--
-- The following four bits are BSD extensions; this exist only on BSD
--systems and the GNU system.
--
-- - Macro: tcflag_t CCTS_OFLOW
-- If this bit is set, enable flow control of output based on the CTS
-- wire (RS232 protocol).
--
-- - Macro: tcflag_t CRTS_IFLOW
-- If this bit is set, enable flow control of input based on the RTS
-- wire (RS232 protocol).
--
-- - Macro: tcflag_t MDMBUF
-- If this bit is set, enable carrier-based flow control of output.
--
-- - Macro: tcflag_t CIGNORE
-- If this bit is set, it says to ignore the control modes and line
-- speed values entirely. This is only meaningful in a call to
-- `tcsetattr'.
--
-- The `c_cflag' member and the line speed values returned by
-- `cfgetispeed' and `cfgetospeed' will be unaffected by the call.
-- `CIGNORE' is useful if you want to set all the software modes in
-- the other members, but leave the hardware details in `c_cflag'
-- unchanged. (This is how the `TCSASOFT' flag to `tcsettattr'
-- works.)
--
-- This bit is never set in the structure filled in by `tcgetattr'.
--
--
--File: libc.info, Node: Local Modes, Next: Line Speed, Prev: Control Modes,
Up: Terminal Modes
--
--Local Modes
-------------
--
-- This section describes the flags for the `c_lflag' member of the
--`struct termios' structure. These flags generally control higher-level
--aspects of input processing than the input modes flags described in
--*Note Input Modes::, such as echoing, signals, and the choice of
--canonical or noncanonical input.
--
-- The `c_lflag' member itself is an integer, and you change the flags
--and fields using the operators `&', `|', and `^'. Don't try to specify
--the entire value for `c_lflag'--instead, change only specific flags and
--leave the rest untouched (*note Setting Modes::.).
--
-- - Macro: tcflag_t ICANON
-- This bit, if set, enables canonical input processing mode.
-- Otherwise, input is processed in noncanonical mode. *Note
-- Canonical or Not::.
--
-- - Macro: tcflag_t ECHO
-- If this bit is set, echoing of input characters back to the
-- terminal is enabled.
--
-- - Macro: tcflag_t ECHOE
-- If this bit is set, echoing indicates erasure of input with the
-- ERASE character by erasing the last character in the current line
-- from the screen. Otherwise, the character erased is re-echoed to
-- show what has happened (suitable for a printing terminal).
--
-- This bit only controls the display behavior; the `ICANON' bit by
-- itself controls actual recognition of the ERASE character and
-- erasure of input, without which `ECHOE' is simply irrelevant.
--
-- - Macro: tcflag_t ECHOPRT
-- This bit is like `ECHOE', enables display of the ERASE character in
-- a way that is geared to a hardcopy terminal. When you type the
-- ERASE character, a `\' character is printed followed by the first
-- character erased. Typing the ERASE character again just prints
-- the next character erased. Then, the next time you type a normal
-- character, a `/' character is printed before the character echoes.
--
-- This is a BSD extension, and exists only in BSD systems and the
-- GNU system.
--
-- - Macro: tcflag_t ECHOK
-- This bit enables special display of the KILL character by moving
-- to a new line after echoing the KILL character normally. The
-- behavior of `ECHOKE' (below) is nicer to look at.
--
-- If this bit is not set, the KILL character echoes just as it would
-- if it were not the KILL character. Then it is up to the user to
-- remember that the KILL character has erased the preceding input;
-- there is no indication of this on the screen.
--
-- This bit only controls the display behavior; the `ICANON' bit by
-- itself controls actual recognition of the KILL character and
-- erasure of input, without which `ECHOK' is simply irrelevant.
--
-- - Macro: tcflag_t ECHOKE
-- This bit is similar to `ECHOK'. It enables special display of the
-- KILL character by erasing on the screen the entire line that has
-- been killed. This is a BSD extension, and exists only in BSD
-- systems and the GNU system.
--
-- - Macro: tcflag_t ECHONL
-- If this bit is set and the `ICANON' bit is also set, then the
-- newline (`'\n'') character is echoed even if the `ECHO' bit is not
-- set.
--
-- - Macro: tcflag_t ECHOCTL
-- If this bit is set and the `ECHO' bit is also set, echo control
-- characters with `^' followed by the corresponding text character.
-- Thus, control-A echoes as `^A'. This is usually the preferred mode
-- for interactive input, because echoing a control character back to
-- the terminal could have some undesired effect on the terminal.
--
-- This is a BSD extension, and exists only in BSD systems and the
-- GNU system.
--
-- - Macro: tcflag_t ISIG
-- This bit controls whether the INTR, QUIT, and SUSP characters are
-- recognized. The functions associated with these characters are
-- performed if and only if this bit is set. Being in canonical or
-- noncanonical input mode has no affect on the interpretation of
-- these characters.
--
-- You should use caution when disabling recognition of these
-- characters. Programs that cannot be interrupted interactively are
-- very user-unfriendly. If you clear this bit, your program should
-- provide some alternate interface that allows the user to
-- interactively send the signals associated with these characters,
-- or to escape from the program.
--
-- *Note Signal Characters::.
--
-- - Macro: tcflag_t IEXTEN
-- POSIX.1 gives `IEXTEN' implementation-defined meaning, so you
-- cannot rely on this interpretation on all systems.
--
-- On BSD systems and the GNU system, it enables the LNEXT and
-- DISCARD characters. *Note Other Special::.
--
-- - Macro: tcflag_t NOFLSH
-- Normally, the INTR, QUIT, and SUSP characters cause input and
-- output queues for the terminal to be cleared. If this bit is set,
-- the queues are not cleared.
--
-- - Macro: tcflag_t TOSTOP
-- If this bit is set and the system supports job control, then
-- `SIGTTOU' signals are generated by background processes that
-- attempt to write to the terminal. *Note Access to the Terminal::.
--
-- The following bits are BSD extensions; they exist only in BSD systems
--and the GNU system.
--
-- - Macro: tcflag_t ALTWERASE
-- This bit determines how far the WERASE character should erase. The
-- WERASE character erases back to the beginning of a word; the
-- question is, where do words begin?
--
-- If this bit is clear, then the beginning of a word is a
-- nonwhitespace character following a whitespace character. If the
-- bit is set, then the beginning of a word is an alphanumeric
-- character or underscore following a character which is none of
-- those.
--
-- *Note Editing Characters::, for more information about the WERASE
-- character.
--
-- - Macro: tcflag_t FLUSHO
-- This is the bit that toggles when the user types the DISCARD
-- character. While this bit is set, all output is discarded. *Note
-- Other Special::.
--
-- - Macro: tcflag_t NOKERNINFO
-- Setting this bit disables handling of the STATUS character. *Note
-- Other Special::.
--
-- - Macro: tcflag_t PENDIN
-- If this bit is set, it indicates that there is a line of input that
-- needs to be reprinted. Typing the REPRINT character sets this
-- bit; the bit remains set until reprinting is finished. *Note
-- Editing Characters::.
--
--
--File: libc.info, Node: Line Speed, Next: Special Characters, Prev: Local
Modes, Up: Terminal Modes
--
--Line Speed
------------
--
-- The terminal line speed tells the computer how fast to read and write
--data on the terminal.
--
-- If the terminal is connected to a real serial line, the terminal
--speed you specify actually controls the line--if it doesn't match the
--terminal's own idea of the speed, communication does not work. Real
--serial ports accept only certain standard speeds. Also, particular
--hardware may not support even all the standard speeds. Specifying a
--speed of zero hangs up a dialup connection and turns off modem control
--signals.
--
-- If the terminal is not a real serial line (for example, if it is a
--network connection), then the line speed won't really affect data
--transmission speed, but some programs will use it to determine the
--amount of padding needed. It's best to specify a line speed value that
--matches the actual speed of the actual terminal, but you can safely
--experiment with different values to vary the amount of padding.
--
-- There are actually two line speeds for each terminal, one for input
--and one for output. You can set them independently, but most often
--terminals use the same speed for both directions.
--
-- The speed values are stored in the `struct termios' structure, but
--don't try to access them in the `struct termios' structure directly.
--Instead, you should use the following functions to read and store them:
--
-- - Function: speed_t cfgetospeed (const struct termios *TERMIOS-P)
-- This function returns the output line speed stored in the structure
-- `*TERMIOS-P'.
--
-- - Function: speed_t cfgetispeed (const struct termios *TERMIOS-P)
-- This function returns the input line speed stored in the structure
-- `*TERMIOS-P'.
--
-- - Function: int cfsetospeed (struct termios *TERMIOS-P, speed_t SPEED)
-- This function stores SPEED in `*TERMIOS-P' as the output speed.
-- The normal return value is `0'; a value of `-1' indicates an
-- error. If SPEED is not a speed, `cfsetospeed' returns `-1'.
--
-- - Function: int cfsetispeed (struct termios *TERMIOS-P, speed_t SPEED)
-- This function stores SPEED in `*TERMIOS-P' as the input speed.
-- The normal return value is `0'; a value of `-1' indicates an
-- error. If SPEED is not a speed, `cfsetospeed' returns `-1'.
--
-- - Function: int cfsetspeed (struct termios *TERMIOS-P, speed_t SPEED)
-- This function stores SPEED in `*TERMIOS-P' as both the input and
-- output speeds. The normal return value is `0'; a value of `-1'
-- indicates an error. If SPEED is not a speed, `cfsetspeed' returns
-- `-1'. This function is an extension in 4.4 BSD.
--
-- - Data Type: speed_t
-- The `speed_t' type is an unsigned integer data type used to
-- represent line speeds.
--
-- The functions `cfsetospeed' and `cfsetispeed' report errors only for
--speed values that the system simply cannot handle. If you specify a
--speed value that is basically acceptable, then those functions will
--succeed. But they do not check that a particular hardware device can
--actually support the specified speeds--in fact, they don't know which
--device you plan to set the speed for. If you use `tcsetattr' to set
--the speed of a particular device to a value that it cannot handle,
--`tcsetattr' returns `-1'.
--
-- *Portability note:* In the GNU library, the functions above accept
--speeds measured in bits per second as input, and return speed values
--measured in bits per second. Other libraries require speeds to be
--indicated by special codes. For POSIX.1 portability, you must use one
--of the following symbols to represent the speed; their precise numeric
--values are system-dependent, but each name has a fixed meaning: `B110'
--stands for 110 bps, `B300' for 300 bps, and so on. There is no
--portable way to represent any speed but these, but these are the only
--speeds that typical serial lines can support.
--
-- B0 B50 B75 B110 B134 B150 B200
-- B300 B600 B1200 B1800 B2400 B4800
-- B9600 B19200 B38400
--
-- BSD defines two additional speed symbols as aliases: `EXTA' is an
--alias for `B19200' and `EXTB' is an alias for `B38400'. These aliases
--are obsolete.
--
--
--File: libc.info, Node: Special Characters, Next: Noncanonical Input, Prev:
Line Speed, Up: Terminal Modes
--
--Special Characters
--------------------
--
-- In canonical input, the terminal driver recognizes a number of
--special characters which perform various control functions. These
--include the ERASE character (usually <DEL>) for editing input, and
--other editing characters. The INTR character (normally `C-c') for
--sending a `SIGINT' signal, and other signal-raising characters, may be
--available in either canonical or noncanonical input mode. All these
--characters are described in this section.
--
-- The particular characters used are specified in the `c_cc' member of
--the `struct termios' structure. This member is an array; each element
--specifies the character for a particular role. Each element has a
--symbolic constant that stands for the index of that element--for
--example, `INTR' is the index of the element that specifies the INTR
--character, so storing `'='' in `TERMIOS.c_cc[INTR]' specifies `=' as
--the INTR character.
--
-- On some systems, you can disable a particular special character
--function by specifying the value `_POSIX_VDISABLE' for that role. This
--value is unequal to any possible character code. *Note Options for
--Files::, for more information about how to tell whether the operating
--system you are using supports `_POSIX_VDISABLE'.
--
--* Menu:
--
--* Editing Characters:: Special characters that terminate lines and
-- delete text, and other editing functions.
--* Signal Characters:: Special characters that send or raise signals
-- to or for certain classes of processes.
--* Start/Stop Characters:: Special characters that suspend or resume
-- suspended output.
--* Other Special:: Other special characters for BSD systems:
-- they can discard output, and print status.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-15
glibc-2.0.1/manual/libc.info-15
---- ../glibc-2.0.1/manual/libc.info-15 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-15 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1220 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Editing Characters, Next: Signal Characters, Up:
Special Characters
--
--Characters for Input Editing
--............................
--
-- These special characters are active only in canonical input mode.
--*Note Canonical or Not::.
--
-- - Macro: int VEOF
-- This is the subscript for the EOF character in the special control
-- character array. `TERMIOS.c_cc[VEOF]' holds the character itself.
--
-- The EOF character is recognized only in canonical input mode. It
-- acts as a line terminator in the same way as a newline character,
-- but if the EOF character is typed at the beginning of a line it
-- causes `read' to return a byte count of zero, indicating
-- end-of-file. The EOF character itself is discarded.
--
-- Usually, the EOF character is `C-d'.
--
-- - Macro: int VEOL
-- This is the subscript for the EOL character in the special control
-- character array. `TERMIOS.c_cc[VEOL]' holds the character itself.
--
-- The EOL character is recognized only in canonical input mode. It
-- acts as a line terminator, just like a newline character. The EOL
-- character is not discarded; it is read as the last character in
-- the input line.
--
-- You don't need to use the EOL character to make <RET> end a line.
-- Just set the ICRNL flag. In fact, this is the default state of
-- affairs.
--
-- - Macro: int VEOL2
-- This is the subscript for the EOL2 character in the special control
-- character array. `TERMIOS.c_cc[VEOL2]' holds the character itself.
--
-- The EOL2 character works just like the EOL character (see above),
-- but it can be a different character. Thus, you can specify two
-- characters to terminate an input line, by setting EOL to one of
-- them and EOL2 to the other.
--
-- The EOL2 character is a BSD extension; it exists only on BSD
-- systems and the GNU system.
--
-- - Macro: int VERASE
-- This is the subscript for the ERASE character in the special
-- control character array. `TERMIOS.c_cc[VERASE]' holds the
-- character itself.
--
-- The ERASE character is recognized only in canonical input mode.
-- When the user types the erase character, the previous character
-- typed is discarded. (If the terminal generates multibyte
-- character sequences, this may cause more than one byte of input to
-- be discarded.) This cannot be used to erase past the beginning of
-- the current line of text. The ERASE character itself is discarded.
--
-- Usually, the ERASE character is <DEL>.
--
-- - Macro: int VWERASE
-- This is the subscript for the WERASE character in the special
-- control character array. `TERMIOS.c_cc[VWERASE]' holds the
-- character itself.
--
-- The WERASE character is recognized only in canonical mode. It
-- erases an entire word of prior input, and any whitespace after it;
-- whitespace characters before the word are not erased.
--
-- The definition of a "word" depends on the setting of the
-- `ALTWERASE' mode; *note Local Modes::..
--
-- If the `ALTWERASE' mode is not set, a word is defined as a sequence
-- of any characters except space or tab.
--
-- If the `ALTWERASE' mode is set, a word is defined as a sequence of
-- characters containing only letters, numbers, and underscores,
-- optionally followed by one character that is not a letter, number,
-- or underscore.
--
-- The WERASE character is usually `C-w'.
--
-- This is a BSD extension.
--
-- - Macro: int VKILL
-- This is the subscript for the KILL character in the special control
-- character array. `TERMIOS.c_cc[VKILL]' holds the character itself.
--
-- The KILL character is recognized only in canonical input mode.
-- When the user types the kill character, the entire contents of the
-- current line of input are discarded. The kill character itself is
-- discarded too.
--
-- The KILL character is usually `C-u'.
--
-- - Macro: int VREPRINT
-- This is the subscript for the REPRINT character in the special
-- control character array. `TERMIOS.c_cc[VREPRINT]' holds the
-- character itself.
--
-- The REPRINT character is recognized only in canonical mode. It
-- reprints the current input line. If some asynchronous output has
-- come while you are typing, this lets you see the line you are
-- typing clearly again.
--
-- The REPRINT character is usually `C-r'.
--
-- This is a BSD extension.
--
--
--File: libc.info, Node: Signal Characters, Next: Start/Stop Characters,
Prev: Editing Characters, Up: Special Characters
--
--Characters that Cause Signals
--.............................
--
-- These special characters may be active in either canonical or
--noncanonical input mode, but only when the `ISIG' flag is set (*note
--Local Modes::.).
--
-- - Macro: int VINTR
-- This is the subscript for the INTR character in the special control
-- character array. `TERMIOS.c_cc[VINTR]' holds the character itself.
--
-- The INTR (interrupt) character raises a `SIGINT' signal for all
-- processes in the foreground job associated with the terminal. The
-- INTR character itself is then discarded. *Note Signal Handling::,
-- for more information about signals.
--
-- Typically, the INTR character is `C-c'.
--
-- - Macro: int VQUIT
-- This is the subscript for the QUIT character in the special control
-- character array. `TERMIOS.c_cc[VQUIT]' holds the character itself.
--
-- The QUIT character raises a `SIGQUIT' signal for all processes in
-- the foreground job associated with the terminal. The QUIT
-- character itself is then discarded. *Note Signal Handling::, for
-- more information about signals.
--
-- Typically, the QUIT character is `C-\'.
--
-- - Macro: int VSUSP
-- This is the subscript for the SUSP character in the special control
-- character array. `TERMIOS.c_cc[VSUSP]' holds the character itself.
--
-- The SUSP (suspend) character is recognized only if the
-- implementation supports job control (*note Job Control::.). It
-- causes a `SIGTSTP' signal to be sent to all processes in the
-- foreground job associated with the terminal. The SUSP character
-- itself is then discarded. *Note Signal Handling::, for more
-- information about signals.
--
-- Typically, the SUSP character is `C-z'.
--
-- Few applications disable the normal interpretation of the SUSP
--character. If your program does this, it should provide some other
--mechanism for the user to stop the job. When the user invokes this
--mechanism, the program should send a `SIGTSTP' signal to the process
--group of the process, not just to the process itself. *Note Signaling
--Another Process::.
--
-- - Macro: int VDSUSP
-- This is the subscript for the DSUSP character in the special
-- control character array. `TERMIOS.c_cc[VDSUSP]' holds the
-- character itself.
--
-- The DSUSP (suspend) character is recognized only if the
-- implementation supports job control (*note Job Control::.). It
-- sends a `SIGTSTP' signal, like the SUSP character, but not right
-- away--only when the program tries to read it as input. Not all
-- systems with job control support DSUSP; only BSD-compatible
-- systems (including the GNU system).
--
-- *Note Signal Handling::, for more information about signals.
--
-- Typically, the DSUSP character is `C-y'.
--
--
--File: libc.info, Node: Start/Stop Characters, Next: Other Special, Prev:
Signal Characters, Up: Special Characters
--
--Special Characters for Flow Control
--...................................
--
-- These special characters may be active in either canonical or
--noncanonical input mode, but their use is controlled by the flags
--`IXON' and `IXOFF' (*note Input Modes::.).
--
-- - Macro: int VSTART
-- This is the subscript for the START character in the special
-- control character array. `TERMIOS.c_cc[VSTART]' holds the
-- character itself.
--
-- The START character is used to support the `IXON' and `IXOFF'
-- input modes. If `IXON' is set, receiving a START character resumes
-- suspended output; the START character itself is discarded. If
-- `IXANY' is set, receiving any character at all resumes suspended
-- output; the resuming character is not discarded unless it is the
-- START character. `IXOFF' is set, the system may also transmit
-- START characters to the terminal.
--
-- The usual value for the START character is `C-q'. You may not be
-- able to change this value--the hardware may insist on using `C-q'
-- regardless of what you specify.
--
-- - Macro: int VSTOP
-- This is the subscript for the STOP character in the special control
-- character array. `TERMIOS.c_cc[VSTOP]' holds the character itself.
--
-- The STOP character is used to support the `IXON' and `IXOFF' input
-- modes. If `IXON' is set, receiving a STOP character causes output
-- to be suspended; the STOP character itself is discarded. If
-- `IXOFF' is set, the system may also transmit STOP characters to the
-- terminal, to prevent the input queue from overflowing.
--
-- The usual value for the STOP character is `C-s'. You may not be
-- able to change this value--the hardware may insist on using `C-s'
-- regardless of what you specify.
--
--
--File: libc.info, Node: Other Special, Prev: Start/Stop Characters, Up:
Special Characters
--
--Other Special Characters
--........................
--
-- These special characters exist only in BSD systems and the GNU
--system.
--
-- - Macro: int VLNEXT
-- This is the subscript for the LNEXT character in the special
-- control character array. `TERMIOS.c_cc[VLNEXT]' holds the
-- character itself.
--
-- The LNEXT character is recognized only when `IEXTEN' is set, but in
-- both canonical and noncanonical mode. It disables any special
-- significance of the next character the user types. Even if the
-- character would normally perform some editing function or generate
-- a signal, it is read as a plain character. This is the analogue
-- of the `C-q' command in Emacs. "LNEXT" stands for "literal next."
--
-- The LNEXT character is usually `C-v'.
--
-- - Macro: int VDISCARD
-- This is the subscript for the DISCARD character in the special
-- control character array. `TERMIOS.c_cc[VDISCARD]' holds the
-- character itself.
--
-- The DISCARD character is recognized only when `IEXTEN' is set, but
-- in both canonical and noncanonical mode. Its effect is to toggle
-- the discard-output flag. When this flag is set, all program
-- output is discarded. Setting the flag also discards all output
-- currently in the output buffer. Typing any other character resets
-- the flag.
--
-- - Macro: int VSTATUS
-- This is the subscript for the STATUS character in the special
-- control character array. `TERMIOS.c_cc[VSTATUS]' holds the
-- character itself.
--
-- The STATUS character's effect is to print out a status message
-- about how the current process is running.
--
-- The STATUS character is recognized only in canonical mode, and
-- only if `NOKERNINFO' is not set.
--
--
--File: libc.info, Node: Noncanonical Input, Prev: Special Characters, Up:
Terminal Modes
--
--Noncanonical Input
--------------------
--
-- In noncanonical input mode, the special editing characters such as
--ERASE and KILL are ignored. The system facilities for the user to edit
--input are disabled in noncanonical mode, so that all input characters
--(unless they are special for signal or flow-control purposes) are passed
--to the application program exactly as typed. It is up to the
--application program to give the user ways to edit the input, if
--appropriate.
--
-- Noncanonical mode offers special parameters called MIN and TIME for
--controlling whether and how long to wait for input to be available. You
--can even use them to avoid ever waiting--to return immediately with
--whatever input is available, or with no input.
--
-- The MIN and TIME are stored in elements of the `c_cc' array, which
--is a member of the `struct termios' structure. Each element of this
--array has a particular role, and each element has a symbolic constant
--that stands for the index of that element. `VMIN' and `VMAX' are the
--names for the indices in the array of the MIN and TIME slots.
--
-- - Macro: int VMIN
-- This is the subscript for the MIN slot in the `c_cc' array. Thus,
-- `TERMIOS.c_cc[VMIN]' is the value itself.
--
-- The MIN slot is only meaningful in noncanonical input mode; it
-- specifies the minimum number of bytes that must be available in the
-- input queue in order for `read' to return.
--
-- - Macro: int VTIME
-- This is the subscript for the TIME slot in the `c_cc' array. Thus,
-- `TERMIOS.c_cc[VTIME]' is the value itself.
--
-- The TIME slot is only meaningful in noncanonical input mode; it
-- specifies how long to wait for input before returning, in units of
-- 0.1 seconds.
--
-- The MIN and TIME values interact to determine the criterion for when
--`read' should return; their precise meanings depend on which of them
--are nonzero. There are four possible cases:
--
-- * Both TIME and MIN are nonzero.
--
-- In this case, TIME specifies how long to wait after each input
-- character to see if more input arrives. After the first character
-- received, `read' keeps waiting until either MIN bytes have arrived
-- in all, or TIME elapses with no further input.
--
-- `read' always blocks until the first character arrives, even if
-- TIME elapses first. `read' can return more than MIN characters if
-- more than MIN happen to be in the queue.
--
-- * Both MIN and TIME are zero.
--
-- In this case, `read' always returns immediately with as many
-- characters as are available in the queue, up to the number
-- requested. If no input is immediately available, `read' returns a
-- value of zero.
--
-- * MIN is zero but TIME has a nonzero value.
--
-- In this case, `read' waits for time TIME for input to become
-- available; the availability of a single byte is enough to satisfy
-- the read request and cause `read' to return. When it returns, it
-- returns as many characters as are available, up to the number
-- requested. If no input is available before the timer expires,
-- `read' returns a value of zero.
--
-- * TIME is zero but MIN has a nonzero value.
--
-- In this case, `read' waits until at least MIN bytes are available
-- in the queue. At that time, `read' returns as many characters as
-- are available, up to the number requested. `read' can return more
-- than MIN characters if more than MIN happen to be in the queue.
--
-- What happens if MIN is 50 and you ask to read just 10 bytes?
--Normally, `read' waits until there are 50 bytes in the buffer (or, more
--generally, the wait condition described above is satisfied), and then
--reads 10 of them, leaving the other 40 buffered in the operating system
--for a subsequent call to `read'.
--
-- *Portability note:* On some systems, the MIN and TIME slots are
--actually the same as the EOF and EOL slots. This causes no serious
--problem because the MIN and TIME slots are used only in noncanonical
--input and the EOF and EOL slots are used only in canonical input, but it
--isn't very clean. The GNU library allocates separate slots for these
--uses.
--
-- - Function: int cfmakeraw (struct termios *TERMIOS-P)
-- This function provides an easy way to set up `*TERMIOS-P' for what
-- has traditionally been called "raw mode" in BSD. This uses
-- noncanonical input, and turns off most processing to give an
-- unmodified channel to the terminal.
--
-- It does exactly this:
-- TERMIOS-P->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
-- |INLCR|IGNCR|ICRNL|IXON);
-- TERMIOS-P->c_oflag &= ~OPOST;
-- TERMIOS-P->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
-- TERMIOS-P->c_cflag &= ~(CSIZE|PARENB);
-- TERMIOS-P->c_cflag |= CS8;
--
--
--File: libc.info, Node: Line Control, Next: Noncanon Example, Prev:
Terminal Modes, Up: Low-Level Terminal Interface
--
--Line Control Functions
--======================
--
-- These functions perform miscellaneous control actions on terminal
--devices. As regards terminal access, they are treated like doing
--output: if any of these functions is used by a background process on its
--controlling terminal, normally all processes in the process group are
--sent a `SIGTTOU' signal. The exception is if the calling process
--itself is ignoring or blocking `SIGTTOU' signals, in which case the
--operation is performed and no signal is sent. *Note Job Control::.
--
-- - Function: int tcsendbreak (int FILEDES, int DURATION)
-- This function generates a break condition by transmitting a stream
-- of zero bits on the terminal associated with the file descriptor
-- FILEDES. The duration of the break is controlled by the DURATION
-- argument. If zero, the duration is between 0.25 and 0.5 seconds.
-- The meaning of a nonzero value depends on the operating system.
--
-- This function does nothing if the terminal is not an asynchronous
-- serial data port.
--
-- The return value is normally zero. In the event of an error, a
-- value of `-1' is returned. The following `errno' error conditions
-- are defined for this function:
--
-- `EBADF'
-- The FILEDES is not a valid file descriptor.
--
-- `ENOTTY'
-- The FILEDES is not associated with a terminal device.
--
-- - Function: int tcdrain (int FILEDES)
-- The `tcdrain' function waits until all queued output to the
-- terminal FILEDES has been transmitted.
--
-- The return value is normally zero. In the event of an error, a
-- value of `-1' is returned. The following `errno' error conditions
-- are defined for this function:
--
-- `EBADF'
-- The FILEDES is not a valid file descriptor.
--
-- `ENOTTY'
-- The FILEDES is not associated with a terminal device.
--
-- `EINTR'
-- The operation was interrupted by delivery of a signal. *Note
-- Interrupted Primitives::.
--
-- - Function: int tcflush (int FILEDES, int QUEUE)
-- The `tcflush' function is used to clear the input and/or output
-- queues associated with the terminal file FILEDES. The QUEUE
-- argument specifies which queue(s) to clear, and can be one of the
-- following values:
--
-- `TCIFLUSH'
-- Clear any input data received, but not yet read.
--
-- `TCOFLUSH'
-- Clear any output data written, but not yet transmitted.
--
-- `TCIOFLUSH'
-- Clear both queued input and output.
--
-- The return value is normally zero. In the event of an error, a
-- value of `-1' is returned. The following `errno' error conditions
-- are defined for this function:
--
-- `EBADF'
-- The FILEDES is not a valid file descriptor.
--
-- `ENOTTY'
-- The FILEDES is not associated with a terminal device.
--
-- `EINVAL'
-- A bad value was supplied as the QUEUE argument.
--
-- It is unfortunate that this function is named `tcflush', because
-- the term "flush" is normally used for quite another
-- operation--waiting until all output is transmitted--and using it
-- for discarding input or output would be confusing. Unfortunately,
-- the name `tcflush' comes from POSIX and we cannot change it.
--
-- - Function: int tcflow (int FILEDES, int ACTION)
-- The `tcflow' function is used to perform operations relating to
-- XON/XOFF flow control on the terminal file specified by FILEDES.
--
-- The ACTION argument specifies what operation to perform, and can
-- be one of the following values:
--
-- `TCOOFF'
-- Suspend transmission of output.
--
-- `TCOON'
-- Restart transmission of output.
--
-- `TCIOFF'
-- Transmit a STOP character.
--
-- `TCION'
-- Transmit a START character.
--
-- For more information about the STOP and START characters, see
-- *Note Special Characters::.
--
-- The return value is normally zero. In the event of an error, a
-- value of `-1' is returned. The following `errno' error conditions
-- are defined for this function:
--
-- `EBADF'
-- The FILEDES is not a valid file descriptor.
--
-- `ENOTTY'
-- The FILEDES is not associated with a terminal device.
--
-- `EINVAL'
-- A bad value was supplied as the ACTION argument.
--
--
--File: libc.info, Node: Noncanon Example, Prev: Line Control, Up: Low-Level
Terminal Interface
--
--Noncanonical Mode Example
--=========================
--
-- Here is an example program that shows how you can set up a terminal
--device to read single characters in noncanonical input mode, without
--echo.
--
-- #include <unistd.h>
-- #include <stdio.h>
-- #include <stdlib.h>
-- #include <termios.h>
--
-- /* Use this variable to remember original terminal attributes. */
--
-- struct termios saved_attributes;
--
-- void
-- reset_input_mode (void)
-- {
-- tcsetattr (STDIN_FILENO, TCSANOW, &saved_attributes);
-- }
--
-- void
-- set_input_mode (void)
-- {
-- struct termios tattr;
-- char *name;
--
-- /* Make sure stdin is a terminal. */
-- if (!isatty (STDIN_FILENO))
-- {
-- fprintf (stderr, "Not a terminal.\n");
-- exit (EXIT_FAILURE);
-- }
--
-- /* Save the terminal attributes so we can restore them later. */
-- tcgetattr (STDIN_FILENO, &saved_attributes);
-- atexit (reset_input_mode);
-- /* Set the funny terminal modes. */
-- tcgetattr (STDIN_FILENO, &tattr);
-- tattr.c_lflag &= ~(ICANON|ECHO); /* Clear ICANON and ECHO. */
-- tattr.c_cc[VMIN] = 1;
-- tattr.c_cc[VTIME] = 0;
-- tcsetattr (STDIN_FILENO, TCSAFLUSH, &tattr);
-- }
--
-- int
-- main (void)
-- {
-- char c;
--
-- set_input_mode ();
--
-- while (1)
-- {
-- read (STDIN_FILENO, &c, 1);
-- if (c == '\004') /* `C-d' */
-- break;
-- else
-- putchar (c);
-- }
--
-- return EXIT_SUCCESS;
-- }
--
-- This program is careful to restore the original terminal modes before
--exiting or terminating with a signal. It uses the `atexit' function
--(*note Cleanups on Exit::.) to make sure this is done by `exit'.
--
-- The shell is supposed to take care of resetting the terminal modes
--when a process is stopped or continued; see *Note Job Control::. But
--some existing shells do not actually do this, so you may wish to
--establish handlers for job control signals that reset terminal modes.
--The above example does so.
--
--
--File: libc.info, Node: Mathematics, Next: Arithmetic, Prev: Low-Level
Terminal Interface, Up: Top
--
--Mathematics
--***********
--
-- This chapter contains information about functions for performing
--mathematical computations, such as trigonometric functions. Most of
--these functions have prototypes declared in the header file `math.h'.
--
-- All of the functions that operate on floating-point numbers accept
--arguments and return results of type `double'. In the future, there
--may be additional functions that operate on `float' and `long double'
--values. For example, `cosf' and `cosl' would be versions of the `cos'
--function that operate on `float' and `long double' arguments,
--respectively. In the meantime, you should avoid using these names
--yourself. *Note Reserved Names::.
--
--* Menu:
--
--* Domain and Range Errors:: Detecting overflow conditions and the like.
--* Trig Functions:: Sine, cosine, and tangent.
--* Inverse Trig Functions:: Arc sine, arc cosine, and arc tangent.
--* Exponents and Logarithms:: Also includes square root.
--* Hyperbolic Functions:: Hyperbolic sine and friends.
--* Pseudo-Random Numbers:: Functions for generating pseudo-random
-- numbers.
--
--
--File: libc.info, Node: Domain and Range Errors, Next: Trig Functions, Up:
Mathematics
--
--Domain and Range Errors
--=======================
--
-- Many of the functions listed in this chapter are defined
--mathematically over a domain that is only a subset of real numbers.
--For example, the `acos' function is defined over the domain between
--`-1' and `1'. If you pass an argument to one of these functions that is
--outside the domain over which it is defined, the function sets `errno'
--to `EDOM' to indicate a "domain error". On machines that support
--IEEE 754 floating point, functions reporting error `EDOM' also return a
--NaN.
--
-- Some of these functions are defined mathematically to result in a
--complex value over parts of their domains. The most familiar example of
--this is taking the square root of a negative number. The functions in
--this chapter take only real arguments and return only real values;
--therefore, if the value ought to be nonreal, this is treated as a domain
--error.
--
-- A related problem is that the mathematical result of a function may
--not be representable as a floating point number. If magnitude of the
--correct result is too large to be represented, the function sets
--`errno' to `ERANGE' to indicate a "range error", and returns a
--particular very large value (named by the macro `HUGE_VAL') or its
--negation (`- HUGE_VAL').
--
-- If the magnitude of the result is too small, a value of zero is
--returned instead. In this case, `errno' might or might not be set to
--`ERANGE'.
--
-- The only completely reliable way to check for domain and range
--errors is to set `errno' to `0' before you call the mathematical
--function and test `errno' afterward. As a consequence of this use of
--`errno', use of the mathematical functions is not reentrant if you
--check for errors.
--
-- None of the mathematical functions ever generates signals as a
--result of domain or range errors. In particular, this means that you
--won't see `SIGFPE' signals generated within these functions. (*Note
--Signal Handling::, for more information about signals.)
--
-- - Macro: double HUGE_VAL
-- An expression representing a particular very large number. On
-- machines that use IEEE 754/IEEE 854 floating point format, the
-- value is "infinity". On other machines, it's typically the
-- largest positive number that can be represented.
--
-- The value of this macro is used as the return value from various
-- mathematical `double' returning functions in overflow situations.
--
-- - Macro: float HUGE_VALf
-- This macro is similar to the `HUGE_VAL' macro except that it is
-- used by functions returning `float' values.
--
-- This macro is a GNU extension.
--
-- - Macro: long double HUGE_VALl
-- This macro is similar to the `HUGE_VAL' macro except that it is
-- used by functions returning `long double' values. The value is
-- only different from `HUGE_VAL' if the architecture really supports
-- `long double' values.
--
-- This macro is a GNU extension.
--
-- For more information about floating-point representations and limits,
--see *Note Floating Point Parameters::. In particular, the macro
--`DBL_MAX' might be more appropriate than `HUGE_VAL' for many uses other
--than testing for an error in a mathematical function.
--
--
--File: libc.info, Node: Trig Functions, Next: Inverse Trig Functions, Prev:
Domain and Range Errors, Up: Mathematics
--
--Trigonometric Functions
--=======================
--
-- These are the familiar `sin', `cos', and `tan' functions. The
--arguments to all of these functions are in units of radians; recall
--that pi radians equals 180 degrees.
--
-- The math library doesn't define a symbolic constant for pi, but you
--can define your own if you need one:
--
-- #define PI 3.14159265358979323846264338327
--
--You can also compute the value of pi with the expression `acos (-1.0)'.
--
-- - Function: double sin (double X)
-- This function returns the sine of X, where X is given in radians.
-- The return value is in the range `-1' to `1'.
--
-- - Function: double cos (double X)
-- This function returns the cosine of X, where X is given in
-- radians. The return value is in the range `-1' to `1'.
--
-- - Function: double tan (double X)
-- This function returns the tangent of X, where X is given in
-- radians.
--
-- The following `errno' error conditions are defined for this
-- function:
--
-- `ERANGE'
-- Mathematically, the tangent function has singularities at odd
-- multiples of pi/2. If the argument X is too close to one of
-- these singularities, `tan' sets `errno' to `ERANGE' and
-- returns either positive or negative `HUGE_VAL'.
--
--
--File: libc.info, Node: Inverse Trig Functions, Next: Exponents and
Logarithms, Prev: Trig Functions, Up: Mathematics
--
--Inverse Trigonometric Functions
--===============================
--
-- These are the usual arc sine, arc cosine and arc tangent functions,
--which are the inverses of the sine, cosine and tangent functions,
--respectively.
--
-- - Function: double asin (double X)
-- This function computes the arc sine of X--that is, the value whose
-- sine is X. The value is in units of radians. Mathematically,
-- there are infinitely many such values; the one actually returned
-- is the one between `-pi/2' and `pi/2' (inclusive).
--
-- `asin' fails, and sets `errno' to `EDOM', if X is out of range.
-- The arc sine function is defined mathematically only over the
-- domain `-1' to `1'.
--
-- - Function: double acos (double X)
-- This function computes the arc cosine of X--that is, the value
-- whose cosine is X. The value is in units of radians.
-- Mathematically, there are infinitely many such values; the one
-- actually returned is the one between `0' and `pi' (inclusive).
--
-- `acos' fails, and sets `errno' to `EDOM', if X is out of range.
-- The arc cosine function is defined mathematically only over the
-- domain `-1' to `1'.
--
-- - Function: double atan (double X)
-- This function computes the arc tangent of X--that is, the value
-- whose tangent is X. The value is in units of radians.
-- Mathematically, there are infinitely many such values; the one
-- actually returned is the one between `-pi/2' and `pi/2'
-- (inclusive).
--
-- - Function: double atan2 (double Y, double X)
-- This is the two argument arc tangent function. It is similar to
-- computing the arc tangent of Y/X, except that the signs of both
-- arguments are used to determine the quadrant of the result, and X
-- is permitted to be zero. The return value is given in radians and
-- is in the range `-pi' to `pi', inclusive.
--
-- If X and Y are coordinates of a point in the plane, `atan2'
-- returns the signed angle between the line from the origin to that
-- point and the x-axis. Thus, `atan2' is useful for converting
-- Cartesian coordinates to polar coordinates. (To compute the
-- radial coordinate, use `hypot'; see *Note Exponents and
-- Logarithms::.)
--
-- The function `atan2' sets `errno' to `EDOM' if both X and Y are
-- zero; the return value is not defined in this case.
--
--
--File: libc.info, Node: Exponents and Logarithms, Next: Hyperbolic
Functions, Prev: Inverse Trig Functions, Up: Mathematics
--
--Exponentiation and Logarithms
--=============================
--
-- - Function: double exp (double X)
-- The `exp' function returns the value of e (the base of natural
-- logarithms) raised to power X.
--
-- The function fails, and sets `errno' to `ERANGE', if the magnitude
-- of the result is too large to be representable.
--
-- - Function: double log (double X)
-- This function returns the natural logarithm of X. `exp (log (X))'
-- equals X, exactly in mathematics and approximately in C.
--
-- The following `errno' error conditions are defined for this
-- function:
--
-- `EDOM'
-- The argument X is negative. The log function is defined
-- mathematically to return a real result only on positive
-- arguments.
--
-- `ERANGE'
-- The argument is zero. The log of zero is not defined.
--
-- - Function: double log10 (double X)
-- This function returns the base-10 logarithm of X. Except for the
-- different base, it is similar to the `log' function. In fact,
-- `log10 (X)' equals `log (X) / log (10)'.
--
-- - Function: double pow (double BASE, double POWER)
-- This is a general exponentiation function, returning BASE raised
-- to POWER.
--
-- The following `errno' error conditions are defined for this
-- function:
--
-- `EDOM'
-- The argument BASE is negative and POWER is not an integral
-- value. Mathematically, the result would be a complex number
-- in this case.
--
-- `ERANGE'
-- An underflow or overflow condition was detected in the result.
--
-- - Function: double sqrt (double X)
-- This function returns the nonnegative square root of X.
--
-- The `sqrt' function fails, and sets `errno' to `EDOM', if X is
-- negative. Mathematically, the square root would be a complex
-- number.
--
-- - Function: double cbrt (double X)
-- This function returns the cube root of X. This function cannot
-- fail; every representable real value has a representable real cube
-- root.
--
-- - Function: double hypot (double X, double Y)
-- The `hypot' function returns `sqrt (X*X + Y*Y)'. (This is the
-- length of the hypotenuse of a right triangle with sides of length
-- X and Y, or the distance of the point (X, Y) from the origin.)
-- See also the function `cabs' in *Note Absolute Value::.
--
-- - Function: double expm1 (double X)
-- This function returns a value equivalent to `exp (X) - 1'. It is
-- computed in a way that is accurate even if the value of X is near
-- zero--a case where `exp (X) - 1' would be inaccurate due to
-- subtraction of two numbers that are nearly equal.
--
-- - Function: double log1p (double X)
-- This function returns a value equivalent to `log (1 + X)'. It is
-- computed in a way that is accurate even if the value of X is near
-- zero.
--
--
--File: libc.info, Node: Hyperbolic Functions, Next: Pseudo-Random Numbers,
Prev: Exponents and Logarithms, Up: Mathematics
--
--Hyperbolic Functions
--====================
--
-- The functions in this section are related to the exponential
--functions; see *Note Exponents and Logarithms::.
--
-- - Function: double sinh (double X)
-- The `sinh' function returns the hyperbolic sine of X, defined
-- mathematically as `exp (X) - exp (-X) / 2'. The function fails,
-- and sets `errno' to `ERANGE', if the value of X is too large; that
-- is, if overflow occurs.
--
-- - Function: double cosh (double X)
-- The `cosh' function returns the hyperbolic cosine of X, defined
-- mathematically as `exp (X) + exp (-X) / 2'. The function fails,
-- and sets `errno' to `ERANGE', if the value of X is too large; that
-- is, if overflow occurs.
--
-- - Function: double tanh (double X)
-- This function returns the hyperbolic tangent of X, whose
-- mathematical definition is `sinh (X) / cosh (X)'.
--
-- - Function: double asinh (double X)
-- This function returns the inverse hyperbolic sine of X--the value
-- whose hyperbolic sine is X.
--
-- - Function: double acosh (double X)
-- This function returns the inverse hyperbolic cosine of X--the
-- value whose hyperbolic cosine is X. If X is less than `1',
-- `acosh' returns `HUGE_VAL'.
--
-- - Function: double atanh (double X)
-- This function returns the inverse hyperbolic tangent of X--the
-- value whose hyperbolic tangent is X. If the absolute value of X
-- is greater than or equal to `1', `atanh' returns `HUGE_VAL'.
--
--
--File: libc.info, Node: Pseudo-Random Numbers, Prev: Hyperbolic Functions,
Up: Mathematics
--
--Pseudo-Random Numbers
--=====================
--
-- This section describes the GNU facilities for generating a series of
--pseudo-random numbers. The numbers generated are not truly random;
--typically, they form a sequence that repeats periodically, with a
--period so large that you can ignore it for ordinary purposes. The
--random number generator works by remembering at all times a "seed"
--value which it uses to compute the next random number and also to
--compute a new seed.
--
-- Although the generated numbers look unpredictable within one run of a
--program, the sequence of numbers is *exactly the same* from one run to
--the next. This is because the initial seed is always the same. This
--is convenient when you are debugging a program, but it is unhelpful if
--you want the program to behave unpredictably. If you want truly random
--numbers, not just pseudo-random, specify a seed based on the current
--time.
--
-- You can get repeatable sequences of numbers on a particular machine
--type by specifying the same initial seed value for the random number
--generator. There is no standard meaning for a particular seed value;
--the same seed, used in different C libraries or on different CPU types,
--will give you different random numbers.
--
-- The GNU library supports the standard ISO C random number functions
--plus another set derived from BSD. We recommend you use the standard
--ones, `rand' and `srand'.
--
--* Menu:
--
--* ISO Random:: `rand' and friends.
--* BSD Random:: `random' and friends.
--
--
--File: libc.info, Node: ISO Random, Next: BSD Random, Up: Pseudo-Random
Numbers
--
--ISO C Random Number Functions
-------------------------------
--
-- This section describes the random number functions that are part of
--the ISO C standard.
--
-- To use these facilities, you should include the header file
--`stdlib.h' in your program.
--
-- - Macro: int RAND_MAX
-- The value of this macro is an integer constant expression that
-- represents the maximum possible value returned by the `rand'
-- function. In the GNU library, it is `037777777', which is the
-- largest signed integer representable in 32 bits. In other
-- libraries, it may be as low as `32767'.
--
-- - Function: int rand ()
-- The `rand' function returns the next pseudo-random number in the
-- series. The value is in the range from `0' to `RAND_MAX'.
--
-- - Function: void srand (unsigned int SEED)
-- This function establishes SEED as the seed for a new series of
-- pseudo-random numbers. If you call `rand' before a seed has been
-- established with `srand', it uses the value `1' as a default seed.
--
-- To produce truly random numbers (not just pseudo-random), do `srand
-- (time (0))'.
--
--
--File: libc.info, Node: BSD Random, Prev: ISO Random, Up: Pseudo-Random
Numbers
--
--BSD Random Number Functions
-----------------------------
--
-- This section describes a set of random number generation functions
--that are derived from BSD. There is no advantage to using these
--functions with the GNU C library; we support them for BSD compatibility
--only.
--
-- The prototypes for these functions are in `stdlib.h'.
--
-- - Function: long int random ()
-- This function returns the next pseudo-random number in the
-- sequence. The range of values returned is from `0' to `RAND_MAX'.
--
-- - Function: void srandom (unsigned int SEED)
-- The `srandom' function sets the seed for the current random number
-- state based on the integer SEED. If you supply a SEED value of
-- `1', this will cause `random' to reproduce the default set of
-- random numbers.
--
-- To produce truly random numbers (not just pseudo-random), do
-- `srandom (time (0))'.
--
-- - Function: void * initstate (unsigned int SEED, void *STATE, size_t
-- SIZE)
-- The `initstate' function is used to initialize the random number
-- generator state. The argument STATE is an array of SIZE bytes,
-- used to hold the state information. The size must be at least 8
-- bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256. The
-- bigger the STATE array, the better.
--
-- The return value is the previous value of the state information
-- array. You can use this value later as an argument to `setstate'
-- to restore that state.
--
-- - Function: void * setstate (void *STATE)
-- The `setstate' function restores the random number state
-- information STATE. The argument must have been the result of a
-- previous call to INITSTATE or SETSTATE.
--
-- The return value is the previous value of the state information
-- array. You can use thise value later as an argument to `setstate'
-- to restore that state.
--
--
--File: libc.info, Node: Arithmetic, Next: Date and Time, Prev: Mathematics,
Up: Top
--
--Low-Level Arithmetic Functions
--******************************
--
-- This chapter contains information about functions for doing basic
--arithmetic operations, such as splitting a float into its integer and
--fractional parts. These functions are declared in the header file
--`math.h'.
--
--* Menu:
--
--* Not a Number:: Making NaNs and testing for NaNs.
--* Predicates on Floats:: Testing for infinity and for NaNs.
--* Absolute Value:: Absolute value functions.
--* Normalization Functions:: Hacks for radix-2 representations.
--* Rounding and Remainders:: Determining the integer and
-- fractional parts of a float.
--* Integer Division:: Functions for performing integer
-- division.
--* Parsing of Numbers:: Functions for "reading" numbers
-- from strings.
--
--
--File: libc.info, Node: Not a Number, Next: Predicates on Floats, Up:
Arithmetic
--
--"Not a Number" Values
--=====================
--
-- The IEEE floating point format used by most modern computers supports
--values that are "not a number". These values are called "NaNs". "Not
--a number" values result from certain operations which have no
--meaningful numeric result, such as zero divided by zero or infinity
--divided by infinity.
--
-- One noteworthy property of NaNs is that they are not equal to
--themselves. Thus, `x == x' can be 0 if the value of `x' is a NaN. You
--can use this to test whether a value is a NaN or not: if it is not
--equal to itself, then it is a NaN. But the recommended way to test for
--a NaN is with the `isnan' function (*note Predicates on Floats::.).
--
-- Almost any arithmetic operation in which one argument is a NaN
--returns a NaN.
--
-- - Macro: double NAN
-- An expression representing a value which is "not a number". This
-- macro is a GNU extension, available only on machines that support
-- "not a number" values--that is to say, on all machines that
-- support IEEE floating point.
--
-- You can use `#ifdef NAN' to test whether the machine supports
-- NaNs. (Of course, you must arrange for GNU extensions to be
-- visible, such as by defining `_GNU_SOURCE', and then you must
-- include `math.h'.)
--
--
--File: libc.info, Node: Predicates on Floats, Next: Absolute Value, Prev:
Not a Number, Up: Arithmetic
--
--Predicates on Floats
--====================
--
-- This section describes some miscellaneous test functions on doubles.
--Prototypes for these functions appear in `math.h'. These are BSD
--functions, and thus are available if you define `_BSD_SOURCE' or
--`_GNU_SOURCE'.
--
-- - Function: int isinf (double X)
-- This function returns `-1' if X represents negative infinity, `1'
-- if X represents positive infinity, and `0' otherwise.
--
-- - Function: int isnan (double X)
-- This function returns a nonzero value if X is a "not a number"
-- value, and zero otherwise. (You can just as well use `X != X' to
-- get the same result).
--
-- - Function: int finite (double X)
-- This function returns a nonzero value if X is finite or a "not a
-- number" value, and zero otherwise.
--
-- - Function: double infnan (int ERROR)
-- This function is provided for compatibility with BSD. The other
-- mathematical functions use `infnan' to decide what to return on
-- occasion of an error. Its argument is an error code, `EDOM' or
-- `ERANGE'; `infnan' returns a suitable value to indicate this with.
-- `-ERANGE' is also acceptable as an argument, and corresponds to
-- `-HUGE_VAL' as a value.
--
-- In the BSD library, on certain machines, `infnan' raises a fatal
-- signal in all cases. The GNU library does not do likewise,
-- because that does not fit the ISO C specification.
--
-- *Portability Note:* The functions listed in this section are BSD
--extensions.
--
--
--File: libc.info, Node: Absolute Value, Next: Normalization Functions,
Prev: Predicates on Floats, Up: Arithmetic
--
--Absolute Value
--==============
--
-- These functions are provided for obtaining the "absolute value" (or
--"magnitude") of a number. The absolute value of a real number X is X
--is X is positive, -X if X is negative. For a complex number Z, whose
--real part is X and whose imaginary part is Y, the absolute value is
--`sqrt (X*X + Y*Y)'.
--
-- Prototypes for `abs' and `labs' are in `stdlib.h'; `fabs' and `cabs'
--are declared in `math.h'.
--
-- - Function: int abs (int NUMBER)
-- This function returns the absolute value of NUMBER.
--
-- Most computers use a two's complement integer representation, in
-- which the absolute value of `INT_MIN' (the smallest possible `int')
-- cannot be represented; thus, `abs (INT_MIN)' is not defined.
--
-- - Function: long int labs (long int NUMBER)
-- This is similar to `abs', except that both the argument and result
-- are of type `long int' rather than `int'.
--
-- - Function: double fabs (double NUMBER)
-- This function returns the absolute value of the floating-point
-- number NUMBER.
--
-- - Function: double cabs (struct { double real, imag; } Z)
-- The `cabs' function returns the absolute value of the complex
-- number Z, whose real part is `Z.real' and whose imaginary part is
-- `Z.imag'. (See also the function `hypot' in *Note Exponents and
-- Logarithms::.) The value is:
--
-- sqrt (Z.real*Z.real + Z.imag*Z.imag)
--
--
--File: libc.info, Node: Normalization Functions, Next: Rounding and
Remainders, Prev: Absolute Value, Up: Arithmetic
--
--Normalization Functions
--=======================
--
-- The functions described in this section are primarily provided as a
--way to efficiently perform certain low-level manipulations on floating
--point numbers that are represented internally using a binary radix; see
--*Note Floating Point Concepts::. These functions are required to have
--equivalent behavior even if the representation does not use a radix of
--2, but of course they are unlikely to be particularly efficient in
--those cases.
--
-- All these functions are declared in `math.h'.
--
-- - Function: double frexp (double VALUE, int *EXPONENT)
-- The `frexp' function is used to split the number VALUE into a
-- normalized fraction and an exponent.
--
-- If the argument VALUE is not zero, the return value is VALUE times
-- a power of two, and is always in the range 1/2 (inclusive) to 1
-- (exclusive). The corresponding exponent is stored in `*EXPONENT';
-- the return value multiplied by 2 raised to this exponent equals
-- the original number VALUE.
--
-- For example, `frexp (12.8, &exponent)' returns `0.8' and stores
-- `4' in `exponent'.
--
-- If VALUE is zero, then the return value is zero and zero is stored
-- in `*EXPONENT'.
--
-- - Function: double ldexp (double VALUE, int EXPONENT)
-- This function returns the result of multiplying the floating-point
-- number VALUE by 2 raised to the power EXPONENT. (It can be used
-- to reassemble floating-point numbers that were taken apart by
-- `frexp'.)
--
-- For example, `ldexp (0.8, 4)' returns `12.8'.
--
-- The following functions which come from BSD provide facilities
--equivalent to those of `ldexp' and `frexp':
--
-- - Function: double scalb (double VALUE, int EXPONENT)
-- The `scalb' function is the BSD name for `ldexp'.
--
-- - Function: double logb (double X)
-- This BSD function returns the integer part of the base-2 logarithm
-- of X, an integer value represented in type `double'. This is the
-- highest integer power of `2' contained in X. The sign of X is
-- ignored. For example, `logb (3.5)' is `1.0' and `logb (4.0)' is
-- `2.0'.
--
-- When `2' raised to this power is divided into X, it gives a
-- quotient between `1' (inclusive) and `2' (exclusive).
--
-- If X is zero, the value is minus infinity (if the machine supports
-- such a value), or else a very small number. If X is infinity, the
-- value is infinity.
--
-- The value returned by `logb' is one less than the value that
-- `frexp' would store into `*EXPONENT'.
--
-- - Function: double copysign (double VALUE, double SIGN)
-- The `copysign' function returns a value whose absolute value is the
-- same as that of VALUE, and whose sign matches that of SIGN. This
-- is a BSD function.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-16
glibc-2.0.1/manual/libc.info-16
---- ../glibc-2.0.1/manual/libc.info-16 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-16 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1257 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Rounding and Remainders, Next: Integer Division,
Prev: Normalization Functions, Up: Arithmetic
--
--Rounding and Remainder Functions
--================================
--
-- The functions listed here perform operations such as rounding,
--truncation, and remainder in division of floating point numbers. Some
--of these functions convert floating point numbers to integer values.
--They are all declared in `math.h'.
--
-- You can also convert floating-point numbers to integers simply by
--casting them to `int'. This discards the fractional part, effectively
--rounding towards zero. However, this only works if the result can
--actually be represented as an `int'--for very large numbers, this is
--impossible. The functions listed here return the result as a `double'
--instead to get around this problem.
--
-- - Function: double ceil (double X)
-- The `ceil' function rounds X upwards to the nearest integer,
-- returning that value as a `double'. Thus, `ceil (1.5)' is `2.0'.
--
-- - Function: double floor (double X)
-- The `ceil' function rounds X downwards to the nearest integer,
-- returning that value as a `double'. Thus, `floor (1.5)' is `1.0'
-- and `floor (-1.5)' is `-2.0'.
--
-- - Function: double rint (double X)
-- This function rounds X to an integer value according to the
-- current rounding mode. *Note Floating Point Parameters::, for
-- information about the various rounding modes. The default
-- rounding mode is to round to the nearest integer; some machines
-- support other modes, but round-to-nearest is always used unless
-- you explicit select another.
--
-- - Function: double modf (double VALUE, double *INTEGER-PART)
-- This function breaks the argument VALUE into an integer part and a
-- fractional part (between `-1' and `1', exclusive). Their sum
-- equals VALUE. Each of the parts has the same sign as VALUE, so
-- the rounding of the integer part is towards zero.
--
-- `modf' stores the integer part in `*INTEGER-PART', and returns the
-- fractional part. For example, `modf (2.5, &intpart)' returns
-- `0.5' and stores `2.0' into `intpart'.
--
-- - Function: double fmod (double NUMERATOR, double DENOMINATOR)
-- This function computes the remainder from the division of
-- NUMERATOR by DENOMINATOR. Specifically, the return value is
-- `NUMERATOR - N * DENOMINATOR', where N is the quotient of
-- NUMERATOR divided by DENOMINATOR, rounded towards zero to an
-- integer. Thus, `fmod (6.5, 2.3)' returns `1.9', which is `6.5'
-- minus `4.6'.
--
-- The result has the same sign as the NUMERATOR and has magnitude
-- less than the magnitude of the DENOMINATOR.
--
-- If DENOMINATOR is zero, `fmod' fails and sets `errno' to `EDOM'.
--
-- - Function: double drem (double NUMERATOR, double DENOMINATOR)
-- The function `drem' is like `fmod' except that it rounds the
-- internal quotient N to the nearest integer instead of towards zero
-- to an integer. For example, `drem (6.5, 2.3)' returns `-0.4',
-- which is `6.5' minus `6.9'.
--
-- The absolute value of the result is less than or equal to half the
-- absolute value of the DENOMINATOR. The difference between `fmod
-- (NUMERATOR, DENOMINATOR)' and `drem (NUMERATOR, DENOMINATOR)' is
-- always either DENOMINATOR, minus DENOMINATOR, or zero.
--
-- If DENOMINATOR is zero, `drem' fails and sets `errno' to `EDOM'.
--
--
--File: libc.info, Node: Integer Division, Next: Parsing of Numbers, Prev:
Rounding and Remainders, Up: Arithmetic
--
--Integer Division
--================
--
-- This section describes functions for performing integer division.
--These functions are redundant in the GNU C library, since in GNU C the
--`/' operator always rounds towards zero. But in other C
--implementations, `/' may round differently with negative arguments.
--`div' and `ldiv' are useful because they specify how to round the
--quotient: towards zero. The remainder has the same sign as the
--numerator.
--
-- These functions are specified to return a result R such that the
--value `R.quot*DENOMINATOR + R.rem' equals NUMERATOR.
--
-- To use these facilities, you should include the header file
--`stdlib.h' in your program.
--
-- - Data Type: div_t
-- This is a structure type used to hold the result returned by the
-- `div' function. It has the following members:
--
-- `int quot'
-- The quotient from the division.
--
-- `int rem'
-- The remainder from the division.
--
-- - Function: div_t div (int NUMERATOR, int DENOMINATOR)
-- This function `div' computes the quotient and remainder from the
-- division of NUMERATOR by DENOMINATOR, returning the result in a
-- structure of type `div_t'.
--
-- If the result cannot be represented (as in a division by zero), the
-- behavior is undefined.
--
-- Here is an example, albeit not a very useful one.
--
-- div_t result;
-- result = div (20, -6);
--
-- Now `result.quot' is `-3' and `result.rem' is `2'.
--
-- - Data Type: ldiv_t
-- This is a structure type used to hold the result returned by the
-- `ldiv' function. It has the following members:
--
-- `long int quot'
-- The quotient from the division.
--
-- `long int rem'
-- The remainder from the division.
--
-- (This is identical to `div_t' except that the components are of
-- type `long int' rather than `int'.)
--
-- - Function: ldiv_t ldiv (long int NUMERATOR, long int DENOMINATOR)
-- The `ldiv' function is similar to `div', except that the arguments
-- are of type `long int' and the result is returned as a structure
-- of type `ldiv'.
--
--
--File: libc.info, Node: Parsing of Numbers, Prev: Integer Division, Up:
Arithmetic
--
--Parsing of Numbers
--==================
--
-- This section describes functions for "reading" integer and
--floating-point numbers from a string. It may be more convenient in some
--cases to use `sscanf' or one of the related functions; see *Note
--Formatted Input::. But often you can make a program more robust by
--finding the tokens in the string by hand, then converting the numbers
--one by one.
--
--* Menu:
--
--* Parsing of Integers:: Functions for conversion of integer values.
--* Parsing of Floats:: Functions for conversion of floating-point
-- values.
--
--
--File: libc.info, Node: Parsing of Integers, Next: Parsing of Floats, Up:
Parsing of Numbers
--
--Parsing of Integers
---------------------
--
-- These functions are declared in `stdlib.h'.
--
-- - Function: long int strtol (const char *STRING, char **TAILPTR, int
-- BASE)
-- The `strtol' ("string-to-long") function converts the initial part
-- of STRING to a signed integer, which is returned as a value of
-- type `long int'.
--
-- This function attempts to decompose STRING as follows:
--
-- * A (possibly empty) sequence of whitespace characters. Which
-- characters are whitespace is determined by the `isspace'
-- function (*note Classification of Characters::.). These are
-- discarded.
--
-- * An optional plus or minus sign (`+' or `-').
--
-- * A nonempty sequence of digits in the radix specified by BASE.
--
-- If BASE is zero, decimal radix is assumed unless the series of
-- digits begins with `0' (specifying octal radix), or `0x' or
-- `0X' (specifying hexadecimal radix); in other words, the same
-- syntax used for integer constants in C.
--
-- Otherwise BASE must have a value between `2' and `35'. If
-- BASE is `16', the digits may optionally be preceded by `0x'
-- or `0X'. If base has no legal value the value returned is
-- `0l' and the global variable `errno' is set to `EINVAL'.
--
-- * Any remaining characters in the string. If TAILPTR is not a
-- null pointer, `strtol' stores a pointer to this tail in
-- `*TAILPTR'.
--
-- If the string is empty, contains only whitespace, or does not
-- contain an initial substring that has the expected syntax for an
-- integer in the specified BASE, no conversion is performed. In
-- this case, `strtol' returns a value of zero and the value stored in
-- `*TAILPTR' is the value of STRING.
--
-- In a locale other than the standard `"C"' locale, this function
-- may recognize additional implementation-dependent syntax.
--
-- If the string has valid syntax for an integer but the value is not
-- representable because of overflow, `strtol' returns either
-- `LONG_MAX' or `LONG_MIN' (*note Range of Type::.), as appropriate
-- for the sign of the value. It also sets `errno' to `ERANGE' to
-- indicate there was overflow.
--
-- Because the value `0l' is a correct result for `strtol' the user
-- who is interested in handling errors should set the global variable
-- `errno' to `0' before calling this function, so that the program
-- can later test whether an error occurred.
--
-- There is an example at the end of this section.
--
-- - Function: unsigned long int strtoul (const char *STRING, char
-- **TAILPTR, int BASE)
-- The `strtoul' ("string-to-unsigned-long") function is like
-- `strtol' except it deals with unsigned numbers, and returns its
-- value with type `unsigned long int'. No `+' or `-' sign may
-- appear before the number, but the syntax is otherwise the same as
-- described above for `strtol'. The value returned in case of
-- overflow is `ULONG_MAX' (*note Range of Type::.).
--
-- Like `strtol' this function sets `errno' and returns the value
-- `0ul' in case the value for BASE is not in the legal range. For
-- `strtoul' this can happen in another situation. In case the
-- number to be converted is negative `strtoul' also sets `errno' to
-- `EINVAL' and returns `0ul'.
--
-- - Function: long long int strtoq (const char *STRING, char **TAILPTR,
-- int BASE)
-- The `strtoq' ("string-to-quad-word") function is like `strtol'
-- except that is deals with extra long numbers and it returns its
-- value with type `long long int'.
--
-- If the string has valid syntax for an integer but the value is not
-- representable because of overflow, `strtoq' returns either
-- `LONG_LONG_MAX' or `LONG_LONG_MIN' (*note Range of Type::.), as
-- appropriate for the sign of the value. It also sets `errno' to
-- `ERANGE' to indicate there was overflow.
--
-- - Function: long long int strtoll (const char *STRING, char **TAILPTR,
-- int BASE)
-- `strtoll' is only an commonly used other name for the `strtoq'
-- function. Everything said for `strtoq' applies to `strtoll' as
-- well.
--
-- - Function: unsigned long long int strtouq (const char *STRING, char
-- **TAILPTR, int BASE)
-- The `strtouq' ("string-to-unsigned-quad-word") function is like
-- `strtoul' except that is deals with extra long numbers and it
-- returns its value with type `unsigned long long int'. The value
-- returned in case of overflow is `ULONG_LONG_MAX' (*note Range of
-- Type::.).
--
-- - Function: unsigned long long int strtoull (const char *STRING, char
-- **TAILPTR, int BASE)
-- `strtoull' is only an commonly used other name for the `strtouq'
-- function. Everything said for `strtouq' applies to `strtoull' as
-- well.
--
-- - Function: long int atol (const char *STRING)
-- This function is similar to the `strtol' function with a BASE
-- argument of `10', except that it need not detect overflow errors.
-- The `atol' function is provided mostly for compatibility with
-- existing code; using `strtol' is more robust.
--
-- - Function: int atoi (const char *STRING)
-- This function is like `atol', except that it returns an `int'
-- value rather than `long int'. The `atoi' function is also
-- considered obsolete; use `strtol' instead.
--
-- The POSIX locales contain some information about how to format
--numbers (*note General Numeric::.). This mainly deals with
--representing numbers for better readability for humans. The functions
--present so far in this section cannot handle numbers in this form.
--
-- If this functionality is needed in a program one can use the
--functions from the `scanf' family which know about the flag `'' for
--parsing numeric input (*note Numeric Input Conversions::.). Sometimes
--it is more desirable to have finer control.
--
-- In these situation one could use the function `__strtoXXX_internal'.
--XXX here stands for any of the above forms. All numeric conversion
--functions (including the functions to process floating-point numbers)
--have such a counterpart. The difference to the normal form is the
--extra argument at the end of the parameter list. If this value has an
--non-zero value the handling of number grouping is enabled. The
--advantage of using these functions is that the TAILPTR parameters allow
--to determine which part of the input is processed. The `scanf'
--functions don't provide this information. The drawback of using these
--functions is that they are not portable. They only exist in the GNU C
--library.
--
-- Here is a function which parses a string as a sequence of integers
--and returns the sum of them:
--
-- int
-- sum_ints_from_string (char *string)
-- {
-- int sum = 0;
--
-- while (1) {
-- char *tail;
-- int next;
--
-- /* Skip whitespace by hand, to detect the end. */
-- while (isspace (*string)) string++;
-- if (*string == 0)
-- break;
--
-- /* There is more nonwhitespace, */
-- /* so it ought to be another number. */
-- errno = 0;
-- /* Parse it. */
-- next = strtol (string, &tail, 0);
-- /* Add it in, if not overflow. */
-- if (errno)
-- printf ("Overflow\n");
-- else
-- sum += next;
-- /* Advance past it. */
-- string = tail;
-- }
--
-- return sum;
-- }
--
--
--File: libc.info, Node: Parsing of Floats, Prev: Parsing of Integers, Up:
Parsing of Numbers
--
--Parsing of Floats
-------------------
--
-- These functions are declared in `stdlib.h'.
--
-- - Function: double strtod (const char *STRING, char **TAILPTR)
-- The `strtod' ("string-to-double") function converts the initial
-- part of STRING to a floating-point number, which is returned as a
-- value of type `double'.
--
-- This function attempts to decompose STRING as follows:
--
-- * A (possibly empty) sequence of whitespace characters. Which
-- characters are whitespace is determined by the `isspace'
-- function (*note Classification of Characters::.). These are
-- discarded.
--
-- * An optional plus or minus sign (`+' or `-').
--
-- * A nonempty sequence of digits optionally containing a
-- decimal-point character--normally `.', but it depends on the
-- locale (*note Numeric Formatting::.).
--
-- * An optional exponent part, consisting of a character `e' or
-- `E', an optional sign, and a sequence of digits.
--
-- * Any remaining characters in the string. If TAILPTR is not a
-- null pointer, a pointer to this tail of the string is stored
-- in `*TAILPTR'.
--
-- If the string is empty, contains only whitespace, or does not
-- contain an initial substring that has the expected syntax for a
-- floating-point number, no conversion is performed. In this case,
-- `strtod' returns a value of zero and the value returned in
-- `*TAILPTR' is the value of STRING.
--
-- In a locale other than the standard `"C"' or `"POSIX"' locales,
-- this function may recognize additional locale-dependent syntax.
--
-- If the string has valid syntax for a floating-point number but the
-- value is not representable because of overflow, `strtod' returns
-- either positive or negative `HUGE_VAL' (*note Mathematics::.),
-- depending on the sign of the value. Similarly, if the value is
-- not representable because of underflow, `strtod' returns zero. It
-- also sets `errno' to `ERANGE' if there was overflow or underflow.
--
-- Since the value zero which is returned in the error case is also a
-- valid result the user should set the global variable `errno' to
-- zero before calling this function. So one can test for failures
-- after the call since all failures set `errno' to a non-zero value.
--
-- - Function: float strtof (const char *STRING, char **TAILPTR)
-- This function is similar to the `strtod' function but it returns a
-- `float' value instead of a `double' value. If the precision of a
-- `float' value is sufficient this function should be used since it
-- is much faster than `strtod' on some architectures. The reasons
-- are obvious: IEEE 754 defines `float' to have a mantissa of 23
-- bits while `double' has 53 bits and every additional bit of
-- precision can require additional computation.
--
-- If the string has valid syntax for a floating-point number but the
-- value is not representable because of overflow, `strtof' returns
-- either positive or negative `HUGE_VALf' (*note Mathematics::.),
-- depending on the sign of the value.
--
-- This function is a GNU extension.
--
-- - Function: long double strtold (const char *STRING, char **TAILPTR)
-- This function is similar to the `strtod' function but it returns a
-- `long double' value instead of a `double' value. It should be
-- used when high precision is needed. On systems which define a
-- `long double' type (i.e., on which it is not the same as `double')
-- running this function might take significantly more time since
-- more bits of precision are required.
--
-- If the string has valid syntax for a floating-point number but the
-- value is not representable because of overflow, `strtold' returns
-- either positive or negative `HUGE_VALl' (*note Mathematics::.),
-- depending on the sign of the value.
--
-- This function is a GNU extension.
--
-- As for the integer parsing functions there are additional functions
--which will handle numbers represented using the grouping scheme of the
--current locale (*note Parsing of Integers::.).
--
-- - Function: double atof (const char *STRING)
-- This function is similar to the `strtod' function, except that it
-- need not detect overflow and underflow errors. The `atof' function
-- is provided mostly for compatibility with existing code; using
-- `strtod' is more robust.
--
--
--File: libc.info, Node: Searching and Sorting, Next: Pattern Matching,
Prev: Locales, Up: Top
--
--Searching and Sorting
--*********************
--
-- This chapter describes functions for searching and sorting arrays of
--arbitrary objects. You pass the appropriate comparison function to be
--applied as an argument, along with the size of the objects in the array
--and the total number of elements.
--
--* Menu:
--
--* Comparison Functions:: Defining how to compare two objects.
-- Since the sort and search facilities
-- are general, you have to specify the
-- ordering.
--* Array Search Function:: The `bsearch' function.
--* Array Sort Function:: The `qsort' function.
--* Search/Sort Example:: An example program.
--
--
--File: libc.info, Node: Comparison Functions, Next: Array Search Function,
Up: Searching and Sorting
--
--Defining the Comparison Function
--================================
--
-- In order to use the sorted array library functions, you have to
--describe how to compare the elements of the array.
--
-- To do this, you supply a comparison function to compare two elements
--of the array. The library will call this function, passing as arguments
--pointers to two array elements to be compared. Your comparison function
--should return a value the way `strcmp' (*note String/Array
--Comparison::.) does: negative if the first argument is "less" than the
--second, zero if they are "equal", and positive if the first argument is
--"greater".
--
-- Here is an example of a comparison function which works with an
--array of numbers of type `double':
--
-- int
-- compare_doubles (const double *a, const double *b)
-- {
-- return (int) (*a - *b);
-- }
--
-- The header file `stdlib.h' defines a name for the data type of
--comparison functions. This type is a GNU extension.
--
-- int comparison_fn_t (const void *, const void *);
--
--
--File: libc.info, Node: Array Search Function, Next: Array Sort Function,
Prev: Comparison Functions, Up: Searching and Sorting
--
--Array Search Function
--=====================
--
-- To search a sorted array for an element matching the key, use the
--`bsearch' function. The prototype for this function is in the header
--file `stdlib.h'.
--
-- - Function: void * bsearch (const void *KEY, const void *ARRAY, size_t
-- COUNT, size_t SIZE, comparison_fn_t COMPARE)
-- The `bsearch' function searches the sorted array ARRAY for an
-- object that is equivalent to KEY. The array contains COUNT
-- elements, each of which is of size SIZE bytes.
--
-- The COMPARE function is used to perform the comparison. This
-- function is called with two pointer arguments and should return an
-- integer less than, equal to, or greater than zero corresponding to
-- whether its first argument is considered less than, equal to, or
-- greater than its second argument. The elements of the ARRAY must
-- already be sorted in ascending order according to this comparison
-- function.
--
-- The return value is a pointer to the matching array element, or a
-- null pointer if no match is found. If the array contains more
-- than one element that matches, the one that is returned is
-- unspecified.
--
-- This function derives its name from the fact that it is implemented
-- using the binary search algorithm.
--
--
--File: libc.info, Node: Array Sort Function, Next: Search/Sort Example,
Prev: Array Search Function, Up: Searching and Sorting
--
--Array Sort Function
--===================
--
-- To sort an array using an arbitrary comparison function, use the
--`qsort' function. The prototype for this function is in `stdlib.h'.
--
-- - Function: void qsort (void *ARRAY, size_t COUNT, size_t SIZE,
-- comparison_fn_t COMPARE)
-- The QSORT function sorts the array ARRAY. The array contains
-- COUNT elements, each of which is of size SIZE.
--
-- The COMPARE function is used to perform the comparison on the
-- array elements. This function is called with two pointer
-- arguments and should return an integer less than, equal to, or
-- greater than zero corresponding to whether its first argument is
-- considered less than, equal to, or greater than its second
-- argument.
--
-- *Warning:* If two objects compare as equal, their order after
-- sorting is unpredictable. That is to say, the sorting is not
-- stable. This can make a difference when the comparison considers
-- only part of the elements. Two elements with the same sort key
-- may differ in other respects.
--
-- If you want the effect of a stable sort, you can get this result by
-- writing the comparison function so that, lacking other reason
-- distinguish between two elements, it compares them by their
-- addresses. Note that doing this may make the sorting algorithm
-- less efficient, so do it only if necessary.
--
-- Here is a simple example of sorting an array of doubles in
-- numerical order, using the comparison function defined above
-- (*note Comparison Functions::.):
--
-- {
-- double *array;
-- int size;
-- ...
-- qsort (array, size, sizeof (double), compare_doubles);
-- }
--
-- The `qsort' function derives its name from the fact that it was
-- originally implemented using the "quick sort" algorithm.
--
--
--File: libc.info, Node: Search/Sort Example, Prev: Array Sort Function, Up:
Searching and Sorting
--
--Searching and Sorting Example
--=============================
--
-- Here is an example showing the use of `qsort' and `bsearch' with an
--array of structures. The objects in the array are sorted by comparing
--their `name' fields with the `strcmp' function. Then, we can look up
--individual objects based on their names.
--
-- #include <stdlib.h>
-- #include <stdio.h>
-- #include <string.h>
--
-- /* Define an array of critters to sort. */
--
-- struct critter
-- {
-- const char *name;
-- const char *species;
-- };
--
-- struct critter muppets[] =
-- {
-- {"Kermit", "frog"},
-- {"Piggy", "pig"},
-- {"Gonzo", "whatever"},
-- {"Fozzie", "bear"},
-- {"Sam", "eagle"},
-- {"Robin", "frog"},
-- {"Animal", "animal"},
-- {"Camilla", "chicken"},
-- {"Sweetums", "monster"},
-- {"Dr. Strangepork", "pig"},
-- {"Link Hogthrob", "pig"},
-- {"Zoot", "human"},
-- {"Dr. Bunsen Honeydew", "human"},
-- {"Beaker", "human"},
-- {"Swedish Chef", "human"}
-- };
--
-- int count = sizeof (muppets) / sizeof (struct critter);
--
--
--
-- /* This is the comparison function used for sorting and searching. */
--
-- int
-- critter_cmp (const struct critter *c1, const struct critter *c2)
-- {
-- return strcmp (c1->name, c2->name);
-- }
--
--
-- /* Print information about a critter. */
--
-- void
-- print_critter (const struct critter *c)
-- {
-- printf ("%s, the %s\n", c->name, c->species);
-- }
-- /* Do the lookup into the sorted array. */
--
-- void
-- find_critter (const char *name)
-- {
-- struct critter target, *result;
-- target.name = name;
-- result = bsearch (&target, muppets, count, sizeof (struct critter),
-- critter_cmp);
-- if (result)
-- print_critter (result);
-- else
-- printf ("Couldn't find %s.\n", name);
-- }
--
-- /* Main program. */
--
-- int
-- main (void)
-- {
-- int i;
--
-- for (i = 0; i < count; i++)
-- print_critter (&muppets[i]);
-- printf ("\n");
--
-- qsort (muppets, count, sizeof (struct critter), critter_cmp);
--
-- for (i = 0; i < count; i++)
-- print_critter (&muppets[i]);
-- printf ("\n");
--
-- find_critter ("Kermit");
-- find_critter ("Gonzo");
-- find_critter ("Janice");
--
-- return 0;
-- }
--
-- The output from this program looks like:
--
-- Kermit, the frog
-- Piggy, the pig
-- Gonzo, the whatever
-- Fozzie, the bear
-- Sam, the eagle
-- Robin, the frog
-- Animal, the animal
-- Camilla, the chicken
-- Sweetums, the monster
-- Dr. Strangepork, the pig
-- Link Hogthrob, the pig
-- Zoot, the human
-- Dr. Bunsen Honeydew, the human
-- Beaker, the human
-- Swedish Chef, the human
--
-- Animal, the animal
-- Beaker, the human
-- Camilla, the chicken
-- Dr. Bunsen Honeydew, the human
-- Dr. Strangepork, the pig
-- Fozzie, the bear
-- Gonzo, the whatever
-- Kermit, the frog
-- Link Hogthrob, the pig
-- Piggy, the pig
-- Robin, the frog
-- Sam, the eagle
-- Swedish Chef, the human
-- Sweetums, the monster
-- Zoot, the human
--
-- Kermit, the frog
-- Gonzo, the whatever
-- Couldn't find Janice.
--
--
--File: libc.info, Node: Pattern Matching, Next: I/O Overview, Prev:
Searching and Sorting, Up: Top
--
--Pattern Matching
--****************
--
-- The GNU C Library provides pattern matching facilities for two kinds
--of patterns: regular expressions and file-name wildcards. The library
--also provides a facility for expanding variable and command references
--and parsing text into words in the way the shell does.
--
--* Menu:
--
--* Wildcard Matching:: Matching a wildcard pattern against a single string.
--* Globbing:: Finding the files that match a wildcard pattern.
--* Regular Expressions:: Matching regular expressions against strings.
--* Word Expansion:: Expanding shell variables, nested commands,
-- arithmetic, and wildcards.
-- This is what the shell does with shell commands.
--
--
--File: libc.info, Node: Wildcard Matching, Next: Globbing, Up: Pattern
Matching
--
--Wildcard Matching
--=================
--
-- This section describes how to match a wildcard pattern against a
--particular string. The result is a yes or no answer: does the string
--fit the pattern or not. The symbols described here are all declared in
--`fnmatch.h'.
--
-- - Function: int fnmatch (const char *PATTERN, const char *STRING, int
-- FLAGS)
-- This function tests whether the string STRING matches the pattern
-- PATTERN. It returns `0' if they do match; otherwise, it returns
-- the nonzero value `FNM_NOMATCH'. The arguments PATTERN and STRING
-- are both strings.
--
-- The argument FLAGS is a combination of flag bits that alter the
-- details of matching. See below for a list of the defined flags.
--
-- In the GNU C Library, `fnmatch' cannot experience an "error"--it
-- always returns an answer for whether the match succeeds. However,
-- other implementations of `fnmatch' might sometimes report "errors".
-- They would do so by returning nonzero values that are not equal to
-- `FNM_NOMATCH'.
--
-- These are the available flags for the FLAGS argument:
--
--`FNM_FILE_NAME'
-- Treat the `/' character specially, for matching file names. If
-- this flag is set, wildcard constructs in PATTERN cannot match `/'
-- in STRING. Thus, the only way to match `/' is with an explicit
-- `/' in PATTERN.
--
--`FNM_PATHNAME'
-- This is an alias for `FNM_FILE_NAME'; it comes from POSIX.2. We
-- don't recommend this name because we don't use the term "pathname"
-- for file names.
--
--`FNM_PERIOD'
-- Treat the `.' character specially if it appears at the beginning of
-- STRING. If this flag is set, wildcard constructs in PATTERN
-- cannot match `.' as the first character of STRING.
--
-- If you set both `FNM_PERIOD' and `FNM_FILE_NAME', then the special
-- treatment applies to `.' following `/' as well as to `.' at the
-- beginning of STRING. (The shell uses the `FNM_PERIOD' and
-- `FNM_FILE_NAME' falgs together for matching file names.)
--
--`FNM_NOESCAPE'
-- Don't treat the `\' character specially in patterns. Normally,
-- `\' quotes the following character, turning off its special meaning
-- (if any) so that it matches only itself. When quoting is enabled,
-- the pattern `\?' matches only the string `?', because the question
-- mark in the pattern acts like an ordinary character.
--
-- If you use `FNM_NOESCAPE', then `\' is an ordinary character.
--
--`FNM_LEADING_DIR'
-- Ignore a trailing sequence of characters starting with a `/' in
-- STRING; that is to say, test whether STRING starts with a
-- directory name that PATTERN matches.
--
-- If this flag is set, either `foo*' or `foobar' as a pattern would
-- match the string `foobar/frobozz'.
--
--`FNM_CASEFOLD'
-- Ignore case in comparing STRING to PATTERN.
--
--
--File: libc.info, Node: Globbing, Next: Regular Expressions, Prev: Wildcard
Matching, Up: Pattern Matching
--
--Globbing
--========
--
-- The archetypal use of wildcards is for matching against the files in
--a directory, and making a list of all the matches. This is called
--"globbing".
--
-- You could do this using `fnmatch', by reading the directory entries
--one by one and testing each one with `fnmatch'. But that would be slow
--(and complex, since you would have to handle subdirectories by hand).
--
-- The library provides a function `glob' to make this particular use
--of wildcards convenient. `glob' and the other symbols in this section
--are declared in `glob.h'.
--
--* Menu:
--
--* Calling Glob:: Basic use of `glob'.
--* Flags for Globbing:: Flags that enable various options in `glob'.
--
--
--File: libc.info, Node: Calling Glob, Next: Flags for Globbing, Up: Globbing
--
--Calling `glob'
----------------
--
-- The result of globbing is a vector of file names (strings). To
--return this vector, `glob' uses a special data type, `glob_t', which is
--a structure. You pass `glob' the address of the structure, and it
--fills in the structure's fields to tell you about the results.
--
-- - Data Type: glob_t
-- This data type holds a pointer to a word vector. More precisely,
-- it records both the address of the word vector and its size.
--
-- `gl_pathc'
-- The number of elements in the vector.
--
-- `gl_pathv'
-- The address of the vector. This field has type `char **'.
--
-- `gl_offs'
-- The offset of the first real element of the vector, from its
-- nominal address in the `gl_pathv' field. Unlike the other
-- fields, this is always an input to `glob', rather than an
-- output from it.
--
-- If you use a nonzero offset, then that many elements at the
-- beginning of the vector are left empty. (The `glob' function
-- fills them with null pointers.)
--
-- The `gl_offs' field is meaningful only if you use the
-- `GLOB_DOOFFS' flag. Otherwise, the offset is always zero
-- regardless of what is in this field, and the first real
-- element comes at the beginning of the vector.
--
-- - Function: int glob (const char *PATTERN, int FLAGS, int (*ERRFUNC)
-- (const char *FILENAME, int ERROR-CODE), glob_t *VECTOR-PTR)
-- The function `glob' does globbing using the pattern PATTERN in the
-- current directory. It puts the result in a newly allocated
-- vector, and stores the size and address of this vector into
-- `*VECTOR-PTR'. The argument FLAGS is a combination of bit flags;
-- see *Note Flags for Globbing::, for details of the flags.
--
-- The result of globbing is a sequence of file names. The function
-- `glob' allocates a string for each resulting word, then allocates
-- a vector of type `char **' to store the addresses of these
-- strings. The last element of the vector is a null pointer. This
-- vector is called the "word vector".
--
-- To return this vector, `glob' stores both its address and its
-- length (number of elements, not counting the terminating null
-- pointer) into `*VECTOR-PTR'.
--
-- Normally, `glob' sorts the file names alphabetically before
-- returning them. You can turn this off with the flag `GLOB_NOSORT'
-- if you want to get the information as fast as possible. Usually
-- it's a good idea to let `glob' sort them--if you process the files
-- in alphabetical order, the users will have a feel for the rate of
-- progress that your application is making.
--
-- If `glob' succeeds, it returns 0. Otherwise, it returns one of
-- these error codes:
--
-- `GLOB_ABORTED'
-- There was an error opening a directory, and you used the flag
-- `GLOB_ERR' or your specified ERRFUNC returned a nonzero value.
-- *Note Flags for Globbing::, for an explanation of the
-- `GLOB_ERR' flag and ERRFUNC.
--
-- `GLOB_NOMATCH'
-- The pattern didn't match any existing files. If you use the
-- `GLOB_NOCHECK' flag, then you never get this error code,
-- because that flag tells `glob' to *pretend* that the pattern
-- matched at least one file.
--
-- `GLOB_NOSPACE'
-- It was impossible to allocate memory to hold the result.
--
-- In the event of an error, `glob' stores information in
-- `*VECTOR-PTR' about all the matches it has found so far.
--
--
--File: libc.info, Node: Flags for Globbing, Prev: Calling Glob, Up: Globbing
--
--Flags for Globbing
--------------------
--
-- This section describes the flags that you can specify in the FLAGS
--argument to `glob'. Choose the flags you want, and combine them with
--the C bitwise OR operator `|'.
--
--`GLOB_APPEND'
-- Append the words from this expansion to the vector of words
-- produced by previous calls to `glob'. This way you can
-- effectively expand several words as if they were concatenated with
-- spaces between them.
--
-- In order for appending to work, you must not modify the contents
-- of the word vector structure between calls to `glob'. And, if you
-- set `GLOB_DOOFFS' in the first call to `glob', you must also set
-- it when you append to the results.
--
-- Note that the pointer stored in `gl_pathv' may no longer be valid
-- after you call `glob' the second time, because `glob' might have
-- relocated the vector. So always fetch `gl_pathv' from the
-- `glob_t' structure after each `glob' call; *never* save the
-- pointer across calls.
--
--`GLOB_DOOFFS'
-- Leave blank slots at the beginning of the vector of words. The
-- `gl_offs' field says how many slots to leave. The blank slots
-- contain null pointers.
--
--`GLOB_ERR'
-- Give up right away and report an error if there is any difficulty
-- reading the directories that must be read in order to expand
-- PATTERN fully. Such difficulties might include a directory in
-- which you don't have the requisite access. Normally, `glob' tries
-- its best to keep on going despite any errors, reading whatever
-- directories it can.
--
-- You can exercise even more control than this by specifying an
-- error-handler function ERRFUNC when you call `glob'. If ERRFUNC
-- is not a null pointer, then `glob' doesn't give up right away when
-- it can't read a directory; instead, it calls ERRFUNC with two
-- arguments, like this:
--
-- (*ERRFUNC) (FILENAME, ERROR-CODE)
--
-- The argument FILENAME is the name of the directory that `glob'
-- couldn't open or couldn't read, and ERROR-CODE is the `errno'
-- value that was reported to `glob'.
--
-- If the error handler function returns nonzero, then `glob' gives up
-- right away. Otherwise, it continues.
--
--`GLOB_MARK'
-- If the pattern matches the name of a directory, append `/' to the
-- directory's name when returning it.
--
--`GLOB_NOCHECK'
-- If the pattern doesn't match any file names, return the pattern
-- itself as if it were a file name that had been matched.
-- (Normally, when the pattern doesn't match anything, `glob' returns
-- that there were no matches.)
--
--`GLOB_NOSORT'
-- Don't sort the file names; return them in no particular order.
-- (In practice, the order will depend on the order of the entries in
-- the directory.) The only reason *not* to sort is to save time.
--
--`GLOB_NOESCAPE'
-- Don't treat the `\' character specially in patterns. Normally,
-- `\' quotes the following character, turning off its special meaning
-- (if any) so that it matches only itself. When quoting is enabled,
-- the pattern `\?' matches only the string `?', because the question
-- mark in the pattern acts like an ordinary character.
--
-- If you use `GLOB_NOESCAPE', then `\' is an ordinary character.
--
-- `glob' does its work by calling the function `fnmatch' repeatedly.
-- It handles the flag `GLOB_NOESCAPE' by turning on the
-- `FNM_NOESCAPE' flag in calls to `fnmatch'.
--
--
--File: libc.info, Node: Regular Expressions, Next: Word Expansion, Prev:
Globbing, Up: Pattern Matching
--
--Regular Expression Matching
--===========================
--
-- The GNU C library supports two interfaces for matching regular
--expressions. One is the standard POSIX.2 interface, and the other is
--what the GNU system has had for many years.
--
-- Both interfaces are declared in the header file `regex.h'. If you
--define `_POSIX_C_SOURCE', then only the POSIX.2 functions, structures,
--and constants are declared.
--
--* Menu:
--
--* POSIX Regexp Compilation:: Using `regcomp' to prepare to match.
--* Flags for POSIX Regexps:: Syntax variations for `regcomp'.
--* Matching POSIX Regexps:: Using `regexec' to match the compiled
-- pattern that you get from `regcomp'.
--* Regexp Subexpressions:: Finding which parts of the string were
matched.
--* Subexpression Complications:: Find points of which parts were matched.
--* Regexp Cleanup:: Freeing storage; reporting errors.
--
--
--File: libc.info, Node: POSIX Regexp Compilation, Next: Flags for POSIX
Regexps, Up: Regular Expressions
--
--POSIX Regular Expression Compilation
--------------------------------------
--
-- Before you can actually match a regular expression, you must
--"compile" it. This is not true compilation--it produces a special data
--structure, not machine instructions. But it is like ordinary
--compilation in that its purpose is to enable you to "execute" the
--pattern fast. (*Note Matching POSIX Regexps::, for how to use the
--compiled regular expression for matching.)
--
-- There is a special data type for compiled regular expressions:
--
-- - Data Type: regex_t
-- This type of object holds a compiled regular expression. It is
-- actually a structure. It has just one field that your programs
-- should look at:
--
-- `re_nsub'
-- This field holds the number of parenthetical subexpressions
-- in the regular expression that was compiled.
--
-- There are several other fields, but we don't describe them here,
-- because only the functions in the library should use them.
--
-- After you create a `regex_t' object, you can compile a regular
--expression into it by calling `regcomp'.
--
-- - Function: int regcomp (regex_t *COMPILED, const char *PATTERN, int
-- CFLAGS)
-- The function `regcomp' "compiles" a regular expression into a data
-- structure that you can use with `regexec' to match against a
-- string. The compiled regular expression format is designed for
-- efficient matching. `regcomp' stores it into `*COMPILED'.
--
-- It's up to you to allocate an object of type `regex_t' and pass its
-- address to `regcomp'.
--
-- The argument CFLAGS lets you specify various options that control
-- the syntax and semantics of regular expressions. *Note Flags for
-- POSIX Regexps::.
--
-- If you use the flag `REG_NOSUB', then `regcomp' omits from the
-- compiled regular expression the information necessary to record
-- how subexpressions actually match. In this case, you might as well
-- pass `0' for the MATCHPTR and NMATCH arguments when you call
-- `regexec'.
--
-- If you don't use `REG_NOSUB', then the compiled regular expression
-- does have the capacity to record how subexpressions match. Also,
-- `regcomp' tells you how many subexpressions PATTERN has, by
-- storing the number in `COMPILED->re_nsub'. You can use that value
-- to decide how long an array to allocate to hold information about
-- subexpression matches.
--
-- `regcomp' returns `0' if it succeeds in compiling the regular
-- expression; otherwise, it returns a nonzero error code (see the
-- table below). You can use `regerror' to produce an error message
-- string describing the reason for a nonzero value; see *Note Regexp
-- Cleanup::.
--
--
-- Here are the possible nonzero values that `regcomp' can return:
--
--`REG_BADBR'
-- There was an invalid `\{...\}' construct in the regular
-- expression. A valid `\{...\}' construct must contain either a
-- single number, or two numbers in increasing order separated by a
-- comma.
--
--`REG_BADPAT'
-- There was a syntax error in the regular expression.
--
--`REG_BADRPT'
-- A repetition operator such as `?' or `*' appeared in a bad
-- position (with no preceding subexpression to act on).
--
--`REG_ECOLLATE'
-- The regular expression referred to an invalid collating element
-- (one not defined in the current locale for string collation).
-- *Note Locale Categories::.
--
--`REG_ECTYPE'
-- The regular expression referred to an invalid character class name.
--
--`REG_EESCAPE'
-- The regular expression ended with `\'.
--
--`REG_ESUBREG'
-- There was an invalid number in the `\DIGIT' construct.
--
--`REG_EBRACK'
-- There were unbalanced square brackets in the regular expression.
--
--`REG_EPAREN'
-- An extended regular expression had unbalanced parentheses, or a
-- basic regular expression had unbalanced `\(' and `\)'.
--
--`REG_EBRACE'
-- The regular expression had unbalanced `\{' and `\}'.
--
--`REG_ERANGE'
-- One of the endpoints in a range expression was invalid.
--
--`REG_ESPACE'
-- `regcomp' ran out of memory.
--
--
--File: libc.info, Node: Flags for POSIX Regexps, Next: Matching POSIX
Regexps, Prev: POSIX Regexp Compilation, Up: Regular Expressions
--
--Flags for POSIX Regular Expressions
-------------------------------------
--
-- These are the bit flags that you can use in the CFLAGS operand when
--compiling a regular expression with `regcomp'.
--
--`REG_EXTENDED'
-- Treat the pattern as an extended regular expression, rather than
-- as a basic regular expression.
--
--`REG_ICASE'
-- Ignore case when matching letters.
--
--`REG_NOSUB'
-- Don't bother storing the contents of the MATCHES-PTR array.
--
--`REG_NEWLINE'
-- Treat a newline in STRING as dividing STRING into multiple lines,
-- so that `$' can match before the newline and `^' can match after.
-- Also, don't permit `.' to match a newline, and don't permit
-- `[^...]' to match a newline.
--
-- Otherwise, newline acts like any other ordinary character.
--
--
--File: libc.info, Node: Matching POSIX Regexps, Next: Regexp Subexpressions,
Prev: Flags for POSIX Regexps, Up: Regular Expressions
--
--Matching a Compiled POSIX Regular Expression
----------------------------------------------
--
-- Once you have compiled a regular expression, as described in *Note
--POSIX Regexp Compilation::, you can match it against strings using
--`regexec'. A match anywhere inside the string counts as success,
--unless the regular expression contains anchor characters (`^' or `$').
--
-- - Function: int regexec (regex_t *COMPILED, char *STRING, size_t
-- NMATCH, regmatch_t MATCHPTR [], int EFLAGS)
-- This function tries to match the compiled regular expression
-- `*COMPILED' against STRING.
--
-- `regexec' returns `0' if the regular expression matches;
-- otherwise, it returns a nonzero value. See the table below for
-- what nonzero values mean. You can use `regerror' to produce an
-- error message string describing the reason for a nonzero value;
-- see *Note Regexp Cleanup::.
--
-- The argument EFLAGS is a word of bit flags that enable various
-- options.
--
-- If you want to get information about what part of STRING actually
-- matched the regular expression or its subexpressions, use the
-- arguments MATCHPTR and NMATCH. Otherwise, pass `0' for NMATCH,
-- and `NULL' for MATCHPTR. *Note Regexp Subexpressions::.
--
-- You must match the regular expression with the same set of current
--locales that were in effect when you compiled the regular expression.
--
-- The function `regexec' accepts the following flags in the EFLAGS
--argument:
--
--`REG_NOTBOL'
-- Do not regard the beginning of the specified string as the
-- beginning of a line; more generally, don't make any assumptions
-- about what text might precede it.
--
--`REG_NOTEOL'
-- Do not regard the end of the specified string as the end of a
-- line; more generally, don't make any assumptions about what text
-- might follow it.
--
-- Here are the possible nonzero values that `regexec' can return:
--
--`REG_NOMATCH'
-- The pattern didn't match the string. This isn't really an error.
--
--`REG_ESPACE'
-- `regexec' ran out of memory.
--
--
--File: libc.info, Node: Regexp Subexpressions, Next: Subexpression
Complications, Prev: Matching POSIX Regexps, Up: Regular Expressions
--
--Match Results with Subexpressions
-----------------------------------
--
-- When `regexec' matches parenthetical subexpressions of PATTERN, it
--records which parts of STRING they match. It returns that information
--by storing the offsets into an array whose elements are structures of
--type `regmatch_t'. The first element of the array (index `0') records
--the part of the string that matched the entire regular expression.
--Each other element of the array records the beginning and end of the
--part that matched a single parenthetical subexpression.
--
-- - Data Type: regmatch_t
-- This is the data type of the MATCHARRAY array that you pass to
-- `regexec'. It contains two structure fields, as follows:
--
-- `rm_so'
-- The offset in STRING of the beginning of a substring. Add
-- this value to STRING to get the address of that part.
--
-- `rm_eo'
-- The offset in STRING of the end of the substring.
--
-- - Data Type: regoff_t
-- `regoff_t' is an alias for another signed integer type. The
-- fields of `regmatch_t' have type `regoff_t'.
--
-- The `regmatch_t' elements correspond to subexpressions positionally;
--the first element (index `1') records where the first subexpression
--matched, the second element records the second subexpression, and so
--on. The order of the subexpressions is the order in which they begin.
--
-- When you call `regexec', you specify how long the MATCHPTR array is,
--with the NMATCH argument. This tells `regexec' how many elements to
--store. If the actual regular expression has more than NMATCH
--subexpressions, then you won't get offset information about the rest of
--them. But this doesn't alter whether the pattern matches a particular
--string or not.
--
-- If you don't want `regexec' to return any information about where
--the subexpressions matched, you can either supply `0' for NMATCH, or
--use the flag `REG_NOSUB' when you compile the pattern with `regcomp'.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-17
glibc-2.0.1/manual/libc.info-17
---- ../glibc-2.0.1/manual/libc.info-17 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-17 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1227 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Subexpression Complications, Next: Regexp Cleanup,
Prev: Regexp Subexpressions, Up: Regular Expressions
--
--Complications in Subexpression Matching
-----------------------------------------
--
-- Sometimes a subexpression matches a substring of no characters. This
--happens when `f\(o*\)' matches the string `fum'. (It really matches
--just the `f'.) In this case, both of the offsets identify the point in
--the string where the null substring was found. In this example, the
--offsets are both `1'.
--
-- Sometimes the entire regular expression can match without using some
--of its subexpressions at all--for example, when `ba\(na\)*' matches the
--string `ba', the parenthetical subexpression is not used. When this
--happens, `regexec' stores `-1' in both fields of the element for that
--subexpression.
--
-- Sometimes matching the entire regular expression can match a
--particular subexpression more than once--for example, when `ba\(na\)*'
--matches the string `bananana', the parenthetical subexpression matches
--three times. When this happens, `regexec' usually stores the offsets
--of the last part of the string that matched the subexpression. In the
--case of `bananana', these offsets are `6' and `8'.
--
-- But the last match is not always the one that is chosen. It's more
--accurate to say that the last *opportunity* to match is the one that
--takes precedence. What this means is that when one subexpression
--appears within another, then the results reported for the inner
--subexpression reflect whatever happened on the last match of the outer
--subexpression. For an example, consider `\(ba\(na\)*s \)*' matching
--the string `bananas bas '. The last time the inner expression actually
--matches is near the end of the first word. But it is *considered*
--again in the second word, and fails to match there. `regexec' reports
--nonuse of the "na" subexpression.
--
-- Another place where this rule applies is when the regular expression
--`\(ba\(na\)*s \|nefer\(ti\)* \)*' matches `bananas nefertiti'. The
--"na" subexpression does match in the first word, but it doesn't match
--in the second word because the other alternative is used there. Once
--again, the second repetition of the outer subexpression overrides the
--first, and within that second repetition, the "na" subexpression is not
--used. So `regexec' reports nonuse of the "na" subexpression.
--
--
--File: libc.info, Node: Regexp Cleanup, Prev: Subexpression Complications,
Up: Regular Expressions
--
--POSIX Regexp Matching Cleanup
-------------------------------
--
-- When you are finished using a compiled regular expression, you can
--free the storage it uses by calling `regfree'.
--
-- - Function: void regfree (regex_t *COMPILED)
-- Calling `regfree' frees all the storage that `*COMPILED' points
-- to. This includes various internal fields of the `regex_t'
-- structure that aren't documented in this manual.
--
-- `regfree' does not free the object `*COMPILED' itself.
--
-- You should always free the space in a `regex_t' structure with
--`regfree' before using the structure to compile another regular
--expression.
--
-- When `regcomp' or `regexec' reports an error, you can use the
--function `regerror' to turn it into an error message string.
--
-- - Function: size_t regerror (int ERRCODE, regex_t *COMPILED, char
-- *BUFFER, size_t LENGTH)
-- This function produces an error message string for the error code
-- ERRCODE, and stores the string in LENGTH bytes of memory starting
-- at BUFFER. For the COMPILED argument, supply the same compiled
-- regular expression structure that `regcomp' or `regexec' was
-- working with when it got the error. Alternatively, you can supply
-- `NULL' for COMPILED; you will still get a meaningful error
-- message, but it might not be as detailed.
--
-- If the error message can't fit in LENGTH bytes (including a
-- terminating null character), then `regerror' truncates it. The
-- string that `regerror' stores is always null-terminated even if it
-- has been truncated.
--
-- The return value of `regerror' is the minimum length needed to
-- store the entire error message. If this is less than LENGTH, then
-- the error message was not truncated, and you can use it.
-- Otherwise, you should call `regerror' again with a larger buffer.
--
-- Here is a function which uses `regerror', but always dynamically
-- allocates a buffer for the error message:
--
-- char *get_regerror (int errcode, regex_t *compiled)
-- {
-- size_t length = regerror (errcode, compiled, NULL, 0);
-- char *buffer = xmalloc (length);
-- (void) regerror (errcode, compiled, buffer, length);
-- return buffer;
-- }
--
--
--File: libc.info, Node: Word Expansion, Prev: Regular Expressions, Up:
Pattern Matching
--
--Shell-Style Word Expansion
--==========================
--
-- "Word expansion" means the process of splitting a string into
--"words" and substituting for variables, commands, and wildcards just as
--the shell does.
--
-- For example, when you write `ls -l foo.c', this string is split into
--three separate words--`ls', `-l' and `foo.c'. This is the most basic
--function of word expansion.
--
-- When you write `ls *.c', this can become many words, because the
--word `*.c' can be replaced with any number of file names. This is
--called "wildcard expansion", and it is also a part of word expansion.
--
-- When you use `echo $PATH' to print your path, you are taking
--advantage of "variable substitution", which is also part of word
--expansion.
--
-- Ordinary programs can perform word expansion just like the shell by
--calling the library function `wordexp'.
--
--* Menu:
--
--* Expansion Stages:: What word expansion does to a string.
--* Calling Wordexp:: How to call `wordexp'.
--* Flags for Wordexp:: Options you can enable in `wordexp'.
--* Wordexp Example:: A sample program that does word expansion.
--
--
--File: libc.info, Node: Expansion Stages, Next: Calling Wordexp, Up: Word
Expansion
--
--The Stages of Word Expansion
------------------------------
--
-- When word expansion is applied to a sequence of words, it performs
--the following transformations in the order shown here:
--
-- 1. "Tilde expansion": Replacement of `~foo' with the name of the home
-- directory of `foo'.
--
-- 2. Next, three different transformations are applied in the same step,
-- from left to right:
--
-- * "Variable substitution": Environment variables are
-- substituted for references such as `$foo'.
--
-- * "Command substitution": Constructs such as ``cat foo`' and
-- the equivalent `$(cat foo)' are replaced with the output from
-- the inner command.
--
-- * "Arithmetic expansion": Constructs such as `$(($x-1))' are
-- replaced with the result of the arithmetic computation.
--
-- 3. "Field splitting": subdivision of the text into "words".
--
-- 4. "Wildcard expansion": The replacement of a construct such as `*.c'
-- with a list of `.c' file names. Wildcard expansion applies to an
-- entire word at a time, and replaces that word with 0 or more file
-- names that are themselves words.
--
-- 5. "Quote removal": The deletion of string-quotes, now that they have
-- done their job by inhibiting the above transformations when
-- appropriate.
--
-- For the details of these transformations, and how to write the
--constructs that use them, see `The BASH Manual' (to appear).
--
--
--File: libc.info, Node: Calling Wordexp, Next: Flags for Wordexp, Prev:
Expansion Stages, Up: Word Expansion
--
--Calling `wordexp'
-------------------
--
-- All the functions, constants and data types for word expansion are
--declared in the header file `wordexp.h'.
--
-- Word expansion produces a vector of words (strings). To return this
--vector, `wordexp' uses a special data type, `wordexp_t', which is a
--structure. You pass `wordexp' the address of the structure, and it
--fills in the structure's fields to tell you about the results.
--
-- - Data Type: wordexp_t
-- This data type holds a pointer to a word vector. More precisely,
-- it records both the address of the word vector and its size.
--
-- `we_wordc'
-- The number of elements in the vector.
--
-- `we_wordv'
-- The address of the vector. This field has type `char **'.
--
-- `we_offs'
-- The offset of the first real element of the vector, from its
-- nominal address in the `we_wordv' field. Unlike the other
-- fields, this is always an input to `wordexp', rather than an
-- output from it.
--
-- If you use a nonzero offset, then that many elements at the
-- beginning of the vector are left empty. (The `wordexp'
-- function fills them with null pointers.)
--
-- The `we_offs' field is meaningful only if you use the
-- `WRDE_DOOFFS' flag. Otherwise, the offset is always zero
-- regardless of what is in this field, and the first real
-- element comes at the beginning of the vector.
--
-- - Function: int wordexp (const char *WORDS, wordexp_t
-- *WORD-VECTOR-PTR, int FLAGS)
-- Perform word expansion on the string WORDS, putting the result in
-- a newly allocated vector, and store the size and address of this
-- vector into `*WORD-VECTOR-PTR'. The argument FLAGS is a
-- combination of bit flags; see *Note Flags for Wordexp::, for
-- details of the flags.
--
-- You shouldn't use any of the characters `|&;<>' in the string
-- WORDS unless they are quoted; likewise for newline. If you use
-- these characters unquoted, you will get the `WRDE_BADCHAR' error
-- code. Don't use parentheses or braces unless they are quoted or
-- part of a word expansion construct. If you use quotation
-- characters `'"`', they should come in pairs that balance.
--
-- The results of word expansion are a sequence of words. The
-- function `wordexp' allocates a string for each resulting word, then
-- allocates a vector of type `char **' to store the addresses of
-- these strings. The last element of the vector is a null pointer.
-- This vector is called the "word vector".
--
-- To return this vector, `wordexp' stores both its address and its
-- length (number of elements, not counting the terminating null
-- pointer) into `*WORD-VECTOR-PTR'.
--
-- If `wordexp' succeeds, it returns 0. Otherwise, it returns one of
-- these error codes:
--
-- `WRDE_BADCHAR'
-- The input string WORDS contains an unquoted invalid character
-- such as `|'.
--
-- `WRDE_BADVAL'
-- The input string refers to an undefined shell variable, and
-- you used the flag `WRDE_UNDEF' to forbid such references.
--
-- `WRDE_CMDSUB'
-- The input string uses command substitution, and you used the
-- flag `WRDE_NOCMD' to forbid command substitution.
--
-- `WRDE_NOSPACE'
-- It was impossible to allocate memory to hold the result. In
-- this case, `wordexp' can store part of the results--as much
-- as it could allocate room for.
--
-- `WRDE_SYNTAX'
-- There was a syntax error in the input string. For example,
-- an unmatched quoting character is a syntax error.
--
-- - Function: void wordfree (wordexp_t *WORD-VECTOR-PTR)
-- Free the storage used for the word-strings and vector that
-- `*WORD-VECTOR-PTR' points to. This does not free the structure
-- `*WORD-VECTOR-PTR' itself--only the other data it points to.
--
--
--File: libc.info, Node: Flags for Wordexp, Next: Wordexp Example, Prev:
Calling Wordexp, Up: Word Expansion
--
--Flags for Word Expansion
--------------------------
--
-- This section describes the flags that you can specify in the FLAGS
--argument to `wordexp'. Choose the flags you want, and combine them
--with the C operator `|'.
--
--`WRDE_APPEND'
-- Append the words from this expansion to the vector of words
-- produced by previous calls to `wordexp'. This way you can
-- effectively expand several words as if they were concatenated with
-- spaces between them.
--
-- In order for appending to work, you must not modify the contents
-- of the word vector structure between calls to `wordexp'. And, if
-- you set `WRDE_DOOFFS' in the first call to `wordexp', you must also
-- set it when you append to the results.
--
--`WRDE_DOOFFS'
-- Leave blank slots at the beginning of the vector of words. The
-- `we_offs' field says how many slots to leave. The blank slots
-- contain null pointers.
--
--`WRDE_NOCMD'
-- Don't do command substitution; if the input requests command
-- substitution, report an error.
--
--`WRDE_REUSE'
-- Reuse a word vector made by a previous call to `wordexp'. Instead
-- of allocating a new vector of words, this call to `wordexp' will
-- use the vector that already exists (making it larger if necessary).
--
-- Note that the vector may move, so it is not safe to save an old
-- pointer and use it again after calling `wordexp'. You must fetch
-- `we_pathv' anew after each call.
--
--`WRDE_SHOWERR'
-- Do show any error messages printed by commands run by command
-- substitution. More precisely, allow these commands to inherit the
-- standard error output stream of the current process. By default,
-- `wordexp' gives these commands a standard error stream that
-- discards all output.
--
--`WRDE_UNDEF'
-- If the input refers to a shell variable that is not defined,
-- report an error.
--
--
--File: libc.info, Node: Wordexp Example, Prev: Flags for Wordexp, Up: Word
Expansion
--
--`wordexp' Example
-------------------
--
-- Here is an example of using `wordexp' to expand several strings and
--use the results to run a shell command. It also shows the use of
--`WRDE_APPEND' to concatenate the expansions and of `wordfree' to free
--the space allocated by `wordexp'.
--
-- int
-- expand_and_execute (const char *program, const char *options)
-- {
-- wordexp_t result;
-- pid_t pid
-- int status, i;
--
-- /* Expand the string for the program to run. */
-- switch (wordexp (program, &result, 0))
-- {
-- case 0: /* Successful. */
-- break;
-- case WRDE_NOSPACE:
-- /* If the error was `WRDE_NOSPACE',
-- then perhaps part of the result was allocated. */
-- wordfree (&result);
-- default: /* Some other error. */
-- return -1;
-- }
--
-- /* Expand the strings specified for the arguments. */
-- for (i = 0; args[i]; i++)
-- {
-- if (wordexp (options, &result, WRDE_APPEND))
-- {
-- wordfree (&result);
-- return -1;
-- }
-- }
--
-- pid = fork ();
-- if (pid == 0)
-- {
-- /* This is the child process. Execute the command. */
-- execv (result.we_wordv[0], result.we_wordv);
-- exit (EXIT_FAILURE);
-- }
-- else if (pid < 0)
-- /* The fork failed. Report failure. */
-- status = -1;
-- else
-- /* This is the parent process. Wait for the child to complete. */
-- if (waitpid (pid, &status, 0) != pid)
-- status = -1;
--
-- wordfree (&result);
-- return status;
-- }
--
-- In practice, since `wordexp' is executed by running a subshell, it
--would be faster to do this by concatenating the strings with spaces
--between them and running that as a shell command using `sh -c'.
--
--
--File: libc.info, Node: Date and Time, Next: Non-Local Exits, Prev:
Arithmetic, Up: Top
--
--Date and Time
--*************
--
-- This chapter describes functions for manipulating dates and times,
--including functions for determining what the current time is and
--conversion between different time representations.
--
-- The time functions fall into three main categories:
--
-- * Functions for measuring elapsed CPU time are discussed in *Note
-- Processor Time::.
--
-- * Functions for measuring absolute clock or calendar time are
-- discussed in *Note Calendar Time::.
--
-- * Functions for setting alarms and timers are discussed in *Note
-- Setting an Alarm::.
--
--* Menu:
--
--* Processor Time:: Measures processor time used by a program.
--* Calendar Time:: Manipulation of "real" dates and times.
--* Setting an Alarm:: Sending a signal after a specified time.
--* Sleeping:: Waiting for a period of time.
--* Resource Usage:: Measuring various resources used.
--* Limits on Resources:: Specifying limits on resource usage.
--* Priority:: Reading or setting process run priority.
--
--
--File: libc.info, Node: Processor Time, Next: Calendar Time, Up: Date and
Time
--
--Processor Time
--==============
--
-- If you're trying to optimize your program or measure its efficiency,
--it's very useful to be able to know how much "processor time" or "CPU
--time" it has used at any given point. Processor time is different from
--actual wall clock time because it doesn't include any time spent waiting
--for I/O or when some other process is running. Processor time is
--represented by the data type `clock_t', and is given as a number of
--"clock ticks" relative to an arbitrary base time marking the beginning
--of a single program invocation.
--
--* Menu:
--
--* Basic CPU Time:: The `clock' function.
--* Detailed CPU Time:: The `times' function.
--
--
--File: libc.info, Node: Basic CPU Time, Next: Detailed CPU Time, Up:
Processor Time
--
--Basic CPU Time Inquiry
------------------------
--
-- To get the elapsed CPU time used by a process, you can use the
--`clock' function. This facility is declared in the header file
--`time.h'.
--
-- In typical usage, you call the `clock' function at the beginning and
--end of the interval you want to time, subtract the values, and then
--divide by `CLOCKS_PER_SEC' (the number of clock ticks per second), like
--this:
--
-- #include <time.h>
--
-- clock_t start, end;
-- double elapsed;
--
-- start = clock();
-- ... /* Do the work. */
-- end = clock();
-- elapsed = ((double) (end - start)) / CLOCKS_PER_SEC;
--
-- Different computers and operating systems vary wildly in how they
--keep track of processor time. It's common for the internal processor
--clock to have a resolution somewhere between hundredths and millionths
--of a second.
--
-- In the GNU system, `clock_t' is equivalent to `long int' and
--`CLOCKS_PER_SEC' is an integer value. But in other systems, both
--`clock_t' and the type of the macro `CLOCKS_PER_SEC' can be either
--integer or floating-point types. Casting processor time values to
--`double', as in the example above, makes sure that operations such as
--arithmetic and printing work properly and consistently no matter what
--the underlying representation is.
--
-- - Macro: int CLOCKS_PER_SEC
-- The value of this macro is the number of clock ticks per second
-- measured by the `clock' function.
--
-- - Macro: int CLK_TCK
-- This is an obsolete name for `CLOCKS_PER_SEC'.
--
-- - Data Type: clock_t
-- This is the type of the value returned by the `clock' function.
-- Values of type `clock_t' are in units of clock ticks.
--
-- - Function: clock_t clock (void)
-- This function returns the elapsed processor time. The base time is
-- arbitrary but doesn't change within a single process. If the
-- processor time is not available or cannot be represented, `clock'
-- returns the value `(clock_t)(-1)'.
--
--
--File: libc.info, Node: Detailed CPU Time, Prev: Basic CPU Time, Up:
Processor Time
--
--Detailed Elapsed CPU Time Inquiry
-----------------------------------
--
-- The `times' function returns more detailed information about elapsed
--processor time in a `struct tms' object. You should include the header
--file `sys/times.h' to use this facility.
--
-- - Data Type: struct tms
-- The `tms' structure is used to return information about process
-- times. It contains at least the following members:
--
-- `clock_t tms_utime'
-- This is the CPU time used in executing the instructions of
-- the calling process.
--
-- `clock_t tms_stime'
-- This is the CPU time used by the system on behalf of the
-- calling process.
--
-- `clock_t tms_cutime'
-- This is the sum of the `tms_utime' values and the `tms_cutime'
-- values of all terminated child processes of the calling
-- process, whose status has been reported to the parent process
-- by `wait' or `waitpid'; see *Note Process Completion::. In
-- other words, it represents the total CPU time used in
-- executing the instructions of all the terminated child
-- processes of the calling process, excluding child processes
-- which have not yet been reported by `wait' or `waitpid'.
--
-- `clock_t tms_cstime'
-- This is similar to `tms_cutime', but represents the total CPU
-- time used by the system on behalf of all the terminated child
-- processes of the calling process.
--
-- All of the times are given in clock ticks. These are absolute
-- values; in a newly created process, they are all zero. *Note
-- Creating a Process::.
--
-- - Function: clock_t times (struct tms *BUFFER)
-- The `times' function stores the processor time information for the
-- calling process in BUFFER.
--
-- The return value is the same as the value of `clock()': the elapsed
-- real time relative to an arbitrary base. The base is a constant
-- within a particular process, and typically represents the time
-- since system start-up. A value of `(clock_t)(-1)' is returned to
-- indicate failure.
--
-- *Portability Note:* The `clock' function described in *Note Basic
--CPU Time::, is specified by the ISO C standard. The `times' function
--is a feature of POSIX.1. In the GNU system, the value returned by the
--`clock' function is equivalent to the sum of the `tms_utime' and
--`tms_stime' fields returned by `times'.
--
--
--File: libc.info, Node: Calendar Time, Next: Setting an Alarm, Prev:
Processor Time, Up: Date and Time
--
--Calendar Time
--=============
--
-- This section describes facilities for keeping track of dates and
--times according to the Gregorian calendar.
--
-- There are three representations for date and time information:
--
-- * "Calendar time" (the `time_t' data type) is a compact
-- representation, typically giving the number of seconds elapsed
-- since some implementation-specific base time.
--
-- * There is also a "high-resolution time" representation (the `struct
-- timeval' data type) that includes fractions of a second. Use this
-- time representation instead of ordinary calendar time when you
-- need greater precision.
--
-- * "Local time" or "broken-down time" (the `struct tm' data type)
-- represents the date and time as a set of components specifying the
-- year, month, and so on, for a specific time zone. This time
-- representation is usually used in conjunction with formatting date
-- and time values.
--
--* Menu:
--
--* Simple Calendar Time:: Facilities for manipulating calendar time.
--* High-Resolution Calendar:: A time representation with greater precision.
--* Broken-down Time:: Facilities for manipulating local time.
--* Formatting Date and Time:: Converting times to strings.
--* TZ Variable:: How users specify the time zone.
--* Time Zone Functions:: Functions to examine or specify the time zone.
--* Time Functions Example:: An example program showing use of some of
-- the time functions.
--
--
--File: libc.info, Node: Simple Calendar Time, Next: High-Resolution
Calendar, Up: Calendar Time
--
--Simple Calendar Time
----------------------
--
-- This section describes the `time_t' data type for representing
--calendar time, and the functions which operate on calendar time objects.
--These facilities are declared in the header file `time.h'.
--
-- - Data Type: time_t
-- This is the data type used to represent calendar time. When
-- interpreted as an absolute time value, it represents the number of
-- seconds elapsed since 00:00:00 on January 1, 1970, Coordinated
-- Universal Time. (This date is sometimes referred to as the
-- "epoch".) POSIX requires that this count ignore leap seconds, but
-- on some hosts this count includes leap seconds if you set `TZ' to
-- certain values (*note TZ Variable::.).
--
-- In the GNU C library, `time_t' is equivalent to `long int'. In
-- other systems, `time_t' might be either an integer or
-- floating-point type.
--
-- - Function: double difftime (time_t TIME1, time_t TIME0)
-- The `difftime' function returns the number of seconds elapsed
-- between time TIME1 and time TIME0, as a value of type `double'.
-- The difference ignores leap seconds unless leap second support is
-- enabled.
--
-- In the GNU system, you can simply subtract `time_t' values. But on
-- other systems, the `time_t' data type might use some other encoding
-- where subtraction doesn't work directly.
--
-- - Function: time_t time (time_t *RESULT)
-- The `time' function returns the current time as a value of type
-- `time_t'. If the argument RESULT is not a null pointer, the time
-- value is also stored in `*RESULT'. If the calendar time is not
-- available, the value `(time_t)(-1)' is returned.
--
--
--File: libc.info, Node: High-Resolution Calendar, Next: Broken-down Time,
Prev: Simple Calendar Time, Up: Calendar Time
--
--High-Resolution Calendar
--------------------------
--
-- The `time_t' data type used to represent calendar times has a
--resolution of only one second. Some applications need more precision.
--
-- So, the GNU C library also contains functions which are capable of
--representing calendar times to a higher resolution than one second. The
--functions and the associated data types described in this section are
--declared in `sys/time.h'.
--
-- - Data Type: struct timeval
-- The `struct timeval' structure represents a calendar time. It has
-- the following members:
--
-- `long int tv_sec'
-- This represents the number of seconds since the epoch. It is
-- equivalent to a normal `time_t' value.
--
-- `long int tv_usec'
-- This is the fractional second value, represented as the
-- number of microseconds.
--
-- Some times struct timeval values are used for time intervals.
-- Then the `tv_sec' member is the number of seconds in the
-- interval, and `tv_usec' is the number of additional
-- microseconds.
--
-- - Data Type: struct timezone
-- The `struct timezone' structure is used to hold minimal information
-- about the local time zone. It has the following members:
--
-- `int tz_minuteswest'
-- This is the number of minutes west of UTC.
--
-- `int tz_dsttime'
-- If nonzero, daylight saving time applies during some part of
-- the year.
--
-- The `struct timezone' type is obsolete and should never be used.
-- Instead, use the facilities described in *Note Time Zone
-- Functions::.
--
-- It is often necessary to subtract two values of type
--`struct timeval'. Here is the best way to do this. It works even on
--some peculiar operating systems where the `tv_sec' member has an
--unsigned type.
--
-- /* Subtract the `struct timeval' values X and Y,
-- storing the result in RESULT.
-- Return 1 if the difference is negative, otherwise 0. */
--
-- int
-- timeval_subtract (result, x, y)
-- struct timeval *result, *x, *y;
-- {
-- /* Perform the carry for the later subtraction by updating Y. */
-- if (x->tv_usec < y->tv_usec) {
-- int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
-- y->tv_usec -= 1000000 * nsec;
-- y->tv_sec += nsec;
-- }
-- if (x->tv_usec - y->tv_usec > 1000000) {
-- int nsec = (y->tv_usec - x->tv_usec) / 1000000;
-- y->tv_usec += 1000000 * nsec;
-- y->tv_sec -= nsec;
-- }
--
-- /* Compute the time remaining to wait.
-- `tv_usec' is certainly positive. */
-- result->tv_sec = x->tv_sec - y->tv_sec;
-- result->tv_usec = x->tv_usec - y->tv_usec;
--
-- /* Return 1 if result is negative. */
-- return x->tv_sec < y->tv_sec;
-- }
--
-- - Function: int gettimeofday (struct timeval *TP, struct timezone *TZP)
-- The `gettimeofday' function returns the current date and time in
-- the `struct timeval' structure indicated by TP. Information about
-- the time zone is returned in the structure pointed at TZP. If the
-- TZP argument is a null pointer, time zone information is ignored.
--
-- The return value is `0' on success and `-1' on failure. The
-- following `errno' error condition is defined for this function:
--
-- `ENOSYS'
-- The operating system does not support getting time zone
-- information, and TZP is not a null pointer. The GNU
-- operating system does not support using `struct timezone' to
-- represent time zone information; that is an obsolete feature
-- of 4.3 BSD. Instead, use the facilities described in *Note
-- Time Zone Functions::.
--
-- - Function: int settimeofday (const struct timeval *TP, const struct
-- timezone *TZP)
-- The `settimeofday' function sets the current date and time
-- according to the arguments. As for `gettimeofday', time zone
-- information is ignored if TZP is a null pointer.
--
-- You must be a privileged user in order to use `settimeofday'.
--
-- The return value is `0' on success and `-1' on failure. The
-- following `errno' error conditions are defined for this function:
--
-- `EPERM'
-- This process cannot set the time because it is not privileged.
--
-- `ENOSYS'
-- The operating system does not support setting time zone
-- information, and TZP is not a null pointer.
--
-- - Function: int adjtime (const struct timeval *DELTA, struct timeval
-- *OLDDELTA)
-- This function speeds up or slows down the system clock in order to
-- make gradual adjustments in the current time. This ensures that
-- the time reported by the system clock is always monotonically
-- increasing, which might not happen if you simply set the current
-- time.
--
-- The DELTA argument specifies a relative adjustment to be made to
-- the current time. If negative, the system clock is slowed down
-- for a while until it has lost this much time. If positive, the
-- system clock is speeded up for a while.
--
-- If the OLDDELTA argument is not a null pointer, the `adjtime'
-- function returns information about any previous time adjustment
-- that has not yet completed.
--
-- This function is typically used to synchronize the clocks of
-- computers in a local network. You must be a privileged user to
-- use it. The return value is `0' on success and `-1' on failure.
-- The following `errno' error condition is defined for this function:
--
-- `EPERM'
-- You do not have privilege to set the time.
--
-- *Portability Note:* The `gettimeofday', `settimeofday', and
--`adjtime' functions are derived from BSD.
--
--
--File: libc.info, Node: Broken-down Time, Next: Formatting Date and Time,
Prev: High-Resolution Calendar, Up: Calendar Time
--
--Broken-down Time
------------------
--
-- Calendar time is represented as a number of seconds. This is
--convenient for calculation, but has no resemblance to the way people
--normally represent dates and times. By contrast, "broken-down time" is
--a binary representation separated into year, month, day, and so on.
--Broken down time values are not useful for calculations, but they are
--useful for printing human readable time.
--
-- A broken-down time value is always relative to a choice of local time
--zone, and it also indicates which time zone was used.
--
-- The symbols in this section are declared in the header file `time.h'.
--
-- - Data Type: struct tm
-- This is the data type used to represent a broken-down time. The
-- structure contains at least the following members, which can
-- appear in any order:
--
-- `int tm_sec'
-- This is the number of seconds after the minute, normally in
-- the range `0' through `59'. (The actual upper limit is `60',
-- to allow for leap seconds if leap second support is
-- available.)
--
-- `int tm_min'
-- This is the number of minutes after the hour, in the range
-- `0' through `59'.
--
-- `int tm_hour'
-- This is the number of hours past midnight, in the range `0'
-- through `23'.
--
-- `int tm_mday'
-- This is the day of the month, in the range `1' through `31'.
--
-- `int tm_mon'
-- This is the number of months since January, in the range `0'
-- through `11'.
--
-- `int tm_year'
-- This is the number of years since `1900'.
--
-- `int tm_wday'
-- This is the number of days since Sunday, in the range `0'
-- through `6'.
--
-- `int tm_yday'
-- This is the number of days since January 1, in the range `0'
-- through `365'.
--
-- `int tm_isdst'
-- This is a flag that indicates whether Daylight Saving Time is
-- (or was, or will be) in effect at the time described. The
-- value is positive if Daylight Saving Time is in effect, zero
-- if it is not, and negative if the information is not
-- available.
--
-- `long int tm_gmtoff'
-- This field describes the time zone that was used to compute
-- this broken-down time value, including any adjustment for
-- daylight saving; it is the number of seconds that you must
-- add to UTC to get local time. You can also think of this as
-- the number of seconds east of UTC. For example, for U.S.
-- Eastern Standard Time, the value is `-5*60*60'. The
-- `tm_gmtoff' field is derived from BSD and is a GNU library
-- extension; it is not visible in a strict ISO C environment.
--
-- `const char *tm_zone'
-- This field is the name for the time zone that was used to
-- compute this broken-down time value. Like `tm_gmtoff', this
-- field is a BSD and GNU extension, and is not visible in a
-- strict ISO C environment.
--
-- - Function: struct tm * localtime (const time_t *TIME)
-- The `localtime' function converts the calendar time pointed to by
-- TIME to broken-down time representation, expressed relative to the
-- user's specified time zone.
--
-- The return value is a pointer to a static broken-down time
-- structure, which might be overwritten by subsequent calls to
-- `ctime', `gmtime', or `localtime'. (But no other library function
-- overwrites the contents of this object.)
--
-- Calling `localtime' has one other effect: it sets the variable
-- `tzname' with information about the current time zone. *Note Time
-- Zone Functions::.
--
-- - Function: struct tm * gmtime (const time_t *TIME)
-- This function is similar to `localtime', except that the
-- broken-down time is expressed as Coordinated Universal Time
-- (UTC)--that is, as Greenwich Mean Time (GMT)--rather than relative
-- to the local time zone.
--
-- Recall that calendar times are *always* expressed in coordinated
-- universal time.
--
-- - Function: time_t mktime (struct tm *BROKENTIME)
-- The `mktime' function is used to convert a broken-down time
-- structure to a calendar time representation. It also "normalizes"
-- the contents of the broken-down time structure, by filling in the
-- day of week and day of year based on the other date and time
-- components.
--
-- The `mktime' function ignores the specified contents of the
-- `tm_wday' and `tm_yday' members of the broken-down time structure.
-- It uses the values of the other components to compute the
-- calendar time; it's permissible for these components to have
-- unnormalized values outside of their normal ranges. The last
-- thing that `mktime' does is adjust the components of the BROKENTIME
-- structure (including the `tm_wday' and `tm_yday').
--
-- If the specified broken-down time cannot be represented as a
-- calendar time, `mktime' returns a value of `(time_t)(-1)' and does
-- not modify the contents of BROKENTIME.
--
-- Calling `mktime' also sets the variable `tzname' with information
-- about the current time zone. *Note Time Zone Functions::.
--
--
--File: libc.info, Node: Formatting Date and Time, Next: TZ Variable, Prev:
Broken-down Time, Up: Calendar Time
--
--Formatting Date and Time
--------------------------
--
-- The functions described in this section format time values as
--strings. These functions are declared in the header file `time.h'.
--
-- - Function: char * asctime (const struct tm *BROKENTIME)
-- The `asctime' function converts the broken-down time value that
-- BROKENTIME points to into a string in a standard format:
--
-- "Tue May 21 13:46:22 1991\n"
--
-- The abbreviations for the days of week are: `Sun', `Mon', `Tue',
-- `Wed', `Thu', `Fri', and `Sat'.
--
-- The abbreviations for the months are: `Jan', `Feb', `Mar', `Apr',
-- `May', `Jun', `Jul', `Aug', `Sep', `Oct', `Nov', and `Dec'.
--
-- The return value points to a statically allocated string, which
-- might be overwritten by subsequent calls to `asctime' or `ctime'.
-- (But no other library function overwrites the contents of this
-- string.)
--
-- - Function: char * ctime (const time_t *TIME)
-- The `ctime' function is similar to `asctime', except that the time
-- value is specified as a `time_t' calendar time value rather than
-- in broken-down local time format. It is equivalent to
--
-- asctime (localtime (TIME))
--
-- `ctime' sets the variable `tzname', because `localtime' does so.
-- *Note Time Zone Functions::.
--
-- - Function: size_t strftime (char *S, size_t SIZE, const char
-- *TEMPLATE, const struct tm *BROKENTIME)
-- This function is similar to the `sprintf' function (*note
-- Formatted Input::.), but the conversion specifications that can
-- appear in the format template TEMPLATE are specialized for
-- printing components of the date and time BROKENTIME according to
-- the locale currently specified for time conversion (*note
-- Locales::.).
--
-- Ordinary characters appearing in the TEMPLATE are copied to the
-- output string S; this can include multibyte character sequences.
-- Conversion specifiers are introduced by a `%' character, followed
-- by an optional flag which can be one of the following. These
-- flags, which are GNU extensions, affect only the output of numbers:
--
-- `_'
-- The number is padded with spaces.
--
-- `-'
-- The number is not padded at all.
--
-- `0'
-- The number is padded with zeros even if the format specifies
-- padding with spaces.
--
-- `^'
-- The output uses uppercase characters, but only if this is
-- possible (*note Case Conversion::.).
--
-- The default action is to pad the number with zeros to keep it a
-- constant width. Numbers that do not have a range indicated below
-- are never padded, since there is no natural width for them.
--
-- Following the flag an optional specification of the width is
-- possible. This is specified in decimal notation. If the natural
-- size of the output is of the field has less than the specified
-- number of characters, the result is written right adjusted and
-- space padded to the given size.
--
-- An optional modifier can follow the optional flag and width
-- specification. The modifiers, which are POSIX.2 extensions, are:
--
-- `E'
-- Use the locale's alternate representation for date and time.
-- This modifier applies to the `%c', `%C', `%x', `%X', `%y' and
-- `%Y' format specifiers. In a Japanese locale, for example,
-- `%Ex' might yield a date format based on the Japanese
-- Emperors' reigns.
--
-- `O'
-- Use the locale's alternate numeric symbols for numbers. This
-- modifier applies only to numeric format specifiers.
--
-- If the format supports the modifier but no alternate representation
-- is available, it is ignored.
--
-- The conversion specifier ends with a format specifier taken from
-- the following list. The whole `%' sequence is replaced in the
-- output string as follows:
--
-- `%a'
-- The abbreviated weekday name according to the current locale.
--
-- `%A'
-- The full weekday name according to the current locale.
--
-- `%b'
-- The abbreviated month name according to the current locale.
--
-- `%B'
-- The full month name according to the current locale.
--
-- `%c'
-- The preferred date and time representation for the current
-- locale.
--
-- `%C'
-- The century of the year. This is equivalent to the greatest
-- integer not greater than the year divided by 100.
--
-- This format is a POSIX.2 extension.
--
-- `%d'
-- The day of the month as a decimal number (range `01' through
-- `31').
--
-- `%D'
-- The date using the format `%m/%d/%y'.
--
-- This format is a POSIX.2 extension.
--
-- `%e'
-- The day of the month like with `%d', but padded with blank
-- (range ` 1' through `31').
--
-- This format is a POSIX.2 extension.
--
-- `%g'
-- The year corresponding to the ISO week number, but without
-- the century (range `00' through `99'). This has the same
-- format and value as `%y', except that if the ISO week number
-- (see `%V') belongs to the previous or next year, that year is
-- used instead.
--
-- This format is a GNU extension.
--
-- `%G'
-- The year corresponding to the ISO week number. This has the
-- same format and value as `%Y', except that if the ISO week
-- number (see `%V') belongs to the previous or next year, that
-- year is used instead.
--
-- This format is a GNU extension.
--
-- `%h'
-- The abbreviated month name according to the current locale.
-- The action is the same as for `%b'.
--
-- This format is a POSIX.2 extension.
--
-- `%H'
-- The hour as a decimal number, using a 24-hour clock (range
-- `00' through `23').
--
-- `%I'
-- The hour as a decimal number, using a 12-hour clock (range
-- `01' through `12').
--
-- `%j'
-- The day of the year as a decimal number (range `001' through
-- `366').
--
-- `%k'
-- The hour as a decimal number, using a 24-hour clock like
-- `%H', but padded with blank (range ` 0' through `23').
--
-- This format is a GNU extension.
--
-- `%l'
-- The hour as a decimal number, using a 12-hour clock like
-- `%I', but padded with blank (range ` 1' through `12').
--
-- This format is a GNU extension.
--
-- `%m'
-- The month as a decimal number (range `01' through `12').
--
-- `%M'
-- The minute as a decimal number (range `00' through `59').
--
-- `%n'
-- A single `\n' (newline) character.
--
-- This format is a POSIX.2 extension.
--
-- `%p'
-- Either `AM' or `PM', according to the given time value; or the
-- corresponding strings for the current locale. Noon is
-- treated as `PM' and midnight as `AM'.
--
-- `%P'
-- Either `am' or `pm', according to the given time value; or the
-- corresponding strings for the current locale, printed in
-- lowercase characters. Noon is treated as `pm' and midnight
-- as `am'.
--
-- This format is a GNU extension.
--
-- `%r'
-- The complete time using the AM/PM format of the current
-- locale.
--
-- This format is a POSIX.2 extension.
--
-- `%R'
-- The hour and minute in decimal numbers using the format
-- `%H:%M'.
--
-- This format is a GNU extension.
--
-- `%s'
-- The number of seconds since the epoch, i.e., since 1970-01-01
-- 00:00:00 UTC. Leap seconds are not counted unless leap
-- second support is available.
--
-- This format is a GNU extension.
--
-- `%S'
-- The second as a decimal number (range `00' through `60').
--
-- `%t'
-- A single `\t' (tabulator) character.
--
-- This format is a POSIX.2 extension.
--
-- `%T'
-- The time using decimal numbers using the format `%H:%M:%S'.
--
-- This format is a POSIX.2 extension.
--
-- `%u'
-- The day of the week as a decimal number (range `1' through
-- `7'), Monday being `1'.
--
-- This format is a POSIX.2 extension.
--
-- `%U'
-- The week number of the current year as a decimal number
-- (range `00' through `53'), starting with the first Sunday as
-- the first day of the first week. Days preceding the first
-- Sunday in the year are considered to be in week `00'.
--
-- `%V'
-- The ISO 8601:1988 week number as a decimal number (range `01'
-- through `53'). ISO weeks start with Monday and end with
-- Sunday. Week `01' of a year is the first week which has the
-- majority of its days in that year; this is equivalent to the
-- week containing the year's first Thursday, and it is also
-- equivalent to the week containing January 4. Week `01' of a
-- year can contain days from the previous year. The week
-- before week `01' of a year is the last week (`52' or `53') of
-- the previous year even if it contains days from the new year.
--
-- This format is a POSIX.2 extension.
--
-- `%w'
-- The day of the week as a decimal number (range `0' through
-- `6'), Sunday being `0'.
--
-- `%W'
-- The week number of the current year as a decimal number
-- (range `00' through `53'), starting with the first Monday as
-- the first day of the first week. All days preceding the
-- first Monday in the year are considered to be in week `00'.
--
-- `%x'
-- The preferred date representation for the current locale, but
-- without the time.
--
-- `%X'
-- The preferred time representation for the current locale, but
-- with no date.
--
-- `%y'
-- The year without a century as a decimal number (range `00'
-- through `99'). This is equivalent to the year modulo 100.
--
-- `%Y'
-- The year as a decimal number, using the Gregorian calendar.
-- Years before the year `1' are numbered `0', `-1', and so on.
--
-- `%z'
-- RFC 822/ISO 8601:1988 style numeric time zone (e.g., `-0600'
-- or `+0100'), or nothing if no time zone is determinable.
--
-- This format is a GNU extension.
--
-- `%Z'
-- The time zone abbreviation (empty if the time zone can't be
-- determined).
--
-- `%%'
-- A literal `%' character.
--
-- The SIZE parameter can be used to specify the maximum number of
-- characters to be stored in the array S, including the terminating
-- null character. If the formatted time requires more than SIZE
-- characters, the excess characters are discarded. The return value
-- from `strftime' is the number of characters placed in the array S,
-- not including the terminating null character. If the value equals
-- SIZE, it means that the array S was too small; you should repeat
-- the call, providing a bigger array.
--
-- If S is a null pointer, `strftime' does not actually write
-- anything, but instead returns the number of characters it would
-- have written.
--
-- According to POSIX.1 every call to `strftime' implies a call to
-- `tzset'. So the contents of the environment variable `TZ' is
-- examined before any output is produced.
--
-- For an example of `strftime', see *Note Time Functions Example::.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-18
glibc-2.0.1/manual/libc.info-18
---- ../glibc-2.0.1/manual/libc.info-18 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-18 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1165 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: TZ Variable, Next: Time Zone Functions, Prev:
Formatting Date and Time, Up: Calendar Time
--
--Specifying the Time Zone with `TZ'
------------------------------------
--
-- In POSIX systems, a user can specify the time zone by means of the
--`TZ' environment variable. For information about how to set
--environment variables, see *Note Environment Variables::. The functions
--for accessing the time zone are declared in `time.h'.
--
-- You should not normally need to set `TZ'. If the system is
--configured properly, the default time zone will be correct. You might
--set `TZ' if you are using a computer over the network from a different
--time zone, and would like times reported to you in the time zone that
--local for you, rather than what is local for the computer.
--
-- In POSIX.1 systems the value of the `TZ' variable can be of one of
--three formats. With the GNU C library, the most common format is the
--last one, which can specify a selection from a large database of time
--zone information for many regions of the world. The first two formats
--are used to describe the time zone information directly, which is both
--more cumbersome and less precise. But the POSIX.1 standard only
--specifies the details of the first two formats, so it is good to be
--familiar with them in case you come across a POSIX.1 system that doesn't
--support a time zone information database.
--
-- The first format is used when there is no Daylight Saving Time (or
--summer time) in the local time zone:
--
-- STD OFFSET
--
-- The STD string specifies the name of the time zone. It must be
--three or more characters long and must not contain a leading colon or
--embedded digits, commas, or plus or minus signs. There is no space
--character separating the time zone name from the OFFSET, so these
--restrictions are necessary to parse the specification correctly.
--
-- The OFFSET specifies the time value one must add to the local time
--to get a Coordinated Universal Time value. It has syntax like
--[`+'|`-']HH[`:'MM[`:'SS]]. This is positive if the local time zone is
--west of the Prime Meridian and negative if it is east. The hour must
--be between `0' and `23', and the minute and seconds between `0' and
--`59'.
--
-- For example, here is how we would specify Eastern Standard Time, but
--without any daylight saving time alternative:
--
-- EST+5
--
-- The second format is used when there is Daylight Saving Time:
--
-- STD OFFSET DST [OFFSET]`,'START[`/'TIME]`,'END[`/'TIME]
--
-- The initial STD and OFFSET specify the standard time zone, as
--described above. The DST string and OFFSET specify the name and offset
--for the corresponding daylight saving time time zone; if the OFFSET is
--omitted, it defaults to one hour ahead of standard time.
--
-- The remainder of the specification describes when daylight saving
--time is in effect. The START field is when daylight saving time goes
--into effect and the END field is when the change is made back to
--standard time. The following formats are recognized for these fields:
--
--`JN'
-- This specifies the Julian day, with N between `1' and `365'.
-- February 29 is never counted, even in leap years.
--
--`N'
-- This specifies the Julian day, with N between `0' and `365'.
-- February 29 is counted in leap years.
--
--`MM.W.D'
-- This specifies day D of week W of month M. The day D must be
-- between `0' (Sunday) and `6'. The week W must be between `1' and
-- `5'; week `1' is the first week in which day D occurs, and week
-- `5' specifies the *last* D day in the month. The month M should be
-- between `1' and `12'.
--
-- The TIME fields specify when, in the local time currently in effect,
--the change to the other time occurs. If omitted, the default is
--`02:00:00'.
--
-- For example, here is how one would specify the Eastern time zone in
--the United States, including the appropriate daylight saving time and
--its dates of applicability. The normal offset from UTC is 5 hours;
--since this is west of the prime meridian, the sign is positive. Summer
--time begins on the first Sunday in April at 2:00am, and ends on the
--last Sunday in October at 2:00am.
--
-- EST+5EDT,M4.1.0/2,M10.5.0/2
--
-- The schedule of daylight saving time in any particular jurisdiction
--has changed over the years. To be strictly correct, the conversion of
--dates and times in the past should be based on the schedule that was in
--effect then. However, this format has no facilities to let you specify
--how the schedule has changed from year to year. The most you can do is
--specify one particular schedule--usually the present day schedule--and
--this is used to convert any date, no matter when. For precise time zone
--specifications, it is best to use the time zone information database
--(see below).
--
-- The third format looks like this:
--
-- :CHARACTERS
--
-- Each operating system interprets this format differently; in the GNU
--C library, CHARACTERS is the name of a file which describes the time
--zone.
--
-- If the `TZ' environment variable does not have a value, the
--operation chooses a time zone by default. In the GNU C library, the
--default time zone is like the specification `TZ=:/etc/localtime' (or
--`TZ=:/usr/local/etc/localtime', depending on how GNU C library was
--configured; *note Installation::.). Other C libraries use their own
--rule for choosing the default time zone, so there is little we can say
--about them.
--
-- If CHARACTERS begins with a slash, it is an absolute file name;
--otherwise the library looks for the file
--`/share/lib/zoneinfo/CHARACTERS'. The `zoneinfo' directory contains
--data files describing local time zones in many different parts of the
--world. The names represent major cities, with subdirectories for
--geographical areas; for example, `America/New_York', `Europe/London',
--`Asia/Hong_Kong'. These data files are installed by the system
--administrator, who also sets `/etc/localtime' to point to the data file
--for the local time zone. The GNU C library comes with a large database
--of time zone information for most regions of the world, which is
--maintained by a community of volunteers and put in the public domain.
--
--
--File: libc.info, Node: Time Zone Functions, Next: Time Functions Example,
Prev: TZ Variable, Up: Calendar Time
--
--Functions and Variables for Time Zones
----------------------------------------
--
-- - Variable: char * tzname
-- The array `tzname' contains two strings, which are the standard
-- names of the pair of time zones (standard and daylight saving)
-- that the user has selected. `tzname[0]' is the name of the
-- standard time zone (for example, `"EST"'), and `tzname[1]' is the
-- name for the time zone when daylight saving time is in use (for
-- example, `"EDT"'). These correspond to the STD and DST strings
-- (respectively) from the `TZ' environment variable. If daylight
-- saving time is never used, `tzname[1]' is the empty string.
--
-- The `tzname' array is initialized from the `TZ' environment
-- variable whenever `tzset', `ctime', `strftime', `mktime', or
-- `localtime' is called. If multiple abbreviations have been used
-- (e.g. `"EWT"' and `"EDT"' for U.S. Eastern War Time and Eastern
-- Daylight Time), the array contains the most recent abbreviation.
--
-- The `tzname' array is required for POSIX.1 compatibility, but in
-- GNU programs it is better to use the `tm_zone' member of the
-- broken-down time structure, since `tm_zone' reports the correct
-- abbreviation even when it is not the latest one.
--
--
-- - Function: void tzset (void)
-- The `tzset' function initializes the `tzname' variable from the
-- value of the `TZ' environment variable. It is not usually
-- necessary for your program to call this function, because it is
-- called automatically when you use the other time conversion
-- functions that depend on the time zone.
--
-- The following variables are defined for compatibility with System V
--Unix. Like `tzname', these variables are set by calling `tzset' or the
--other time conversion functions.
--
-- - Variable: long int timezone
-- This contains the difference between UTC and the latest local
-- standard time, in seconds west of UTC. For example, in the U.S.
-- Eastern time zone, the value is `5*60*60'. Unlike the `tm_gmtoff'
-- member of the broken-down time structure, this value is not
-- adjusted for daylight saving, and its sign is reversed. In GNU
-- programs it is better to use `tm_gmtoff', since it contains the
-- correct offset even when it is not the latest one.
--
-- - Variable: int daylight
-- This variable has a nonzero value if daylight savings time rules
-- apply. A nonzero value does not necessarily mean that daylight
-- savings time is now in effect; it means only that daylight savings
-- time is sometimes in effect.
--
--
--File: libc.info, Node: Time Functions Example, Prev: Time Zone Functions,
Up: Calendar Time
--
--Time Functions Example
------------------------
--
-- Here is an example program showing the use of some of the local time
--and calendar time functions.
--
-- #include <time.h>
-- #include <stdio.h>
--
-- #define SIZE 256
--
-- int
-- main (void)
-- {
-- char buffer[SIZE];
-- time_t curtime;
-- struct tm *loctime;
--
-- /* Get the current time. */
-- curtime = time (NULL);
--
-- /* Convert it to local time representation. */
-- loctime = localtime (&curtime);
--
-- /* Print out the date and time in the standard format. */
-- fputs (asctime (loctime), stdout);
-- /* Print it out in a nice format. */
-- strftime (buffer, SIZE, "Today is %A, %B %d.\n", loctime);
-- fputs (buffer, stdout);
-- strftime (buffer, SIZE, "The time is %I:%M %p.\n", loctime);
-- fputs (buffer, stdout);
--
-- return 0;
-- }
--
-- It produces output like this:
--
-- Wed Jul 31 13:02:36 1991
-- Today is Wednesday, July 31.
-- The time is 01:02 PM.
--
--
--File: libc.info, Node: Setting an Alarm, Next: Sleeping, Prev: Calendar
Time, Up: Date and Time
--
--Setting an Alarm
--================
--
-- The `alarm' and `setitimer' functions provide a mechanism for a
--process to interrupt itself at some future time. They do this by
--setting a timer; when the timer expires, the process receives a signal.
--
-- Each process has three independent interval timers available:
--
-- * A real-time timer that counts clock time. This timer sends a
-- `SIGALRM' signal to the process when it expires.
--
-- * A virtual timer that counts CPU time used by the process. This
-- timer sends a `SIGVTALRM' signal to the process when it expires.
--
-- * A profiling timer that counts both CPU time used by the process,
-- and CPU time spent in system calls on behalf of the process. This
-- timer sends a `SIGPROF' signal to the process when it expires.
--
-- This timer is useful for profiling in interpreters. The interval
-- timer mechanism does not have the fine granularity necessary for
-- profiling native code.
--
-- You can only have one timer of each kind set at any given time. If
--you set a timer that has not yet expired, that timer is simply reset to
--the new value.
--
-- You should establish a handler for the appropriate alarm signal using
--`signal' or `sigaction' before issuing a call to `setitimer' or
--`alarm'. Otherwise, an unusual chain of events could cause the timer
--to expire before your program establishes the handler, and in that case
--it would be terminated, since that is the default action for the alarm
--signals. *Note Signal Handling::.
--
-- The `setitimer' function is the primary means for setting an alarm.
--This facility is declared in the header file `sys/time.h'. The `alarm'
--function, declared in `unistd.h', provides a somewhat simpler interface
--for setting the real-time timer.
--
-- - Data Type: struct itimerval
-- This structure is used to specify when a timer should expire. It
-- contains the following members:
-- `struct timeval it_interval'
-- This is the interval between successive timer interrupts. If
-- zero, the alarm will only be sent once.
--
-- `struct timeval it_value'
-- This is the interval to the first timer interrupt. If zero,
-- the alarm is disabled.
--
-- The `struct timeval' data type is described in *Note
-- High-Resolution Calendar::.
--
-- - Function: int setitimer (int WHICH, struct itimerval *NEW, struct
-- itimerval *OLD)
-- The `setitimer' function sets the timer specified by WHICH
-- according to NEW. The WHICH argument can have a value of
-- `ITIMER_REAL', `ITIMER_VIRTUAL', or `ITIMER_PROF'.
--
-- If OLD is not a null pointer, `setitimer' returns information
-- about any previous unexpired timer of the same kind in the
-- structure it points to.
--
-- The return value is `0' on success and `-1' on failure. The
-- following `errno' error conditions are defined for this function:
--
-- `EINVAL'
-- The timer interval was too large.
--
-- - Function: int getitimer (int WHICH, struct itimerval *OLD)
-- The `getitimer' function stores information about the timer
-- specified by WHICH in the structure pointed at by OLD.
--
-- The return value and error conditions are the same as for
-- `setitimer'.
--
--`ITIMER_REAL'
-- This constant can be used as the WHICH argument to the `setitimer'
-- and `getitimer' functions to specify the real-time timer.
--
--`ITIMER_VIRTUAL'
-- This constant can be used as the WHICH argument to the `setitimer'
-- and `getitimer' functions to specify the virtual timer.
--
--`ITIMER_PROF'
-- This constant can be used as the WHICH argument to the `setitimer'
-- and `getitimer' functions to specify the profiling timer.
--
-- - Function: unsigned int alarm (unsigned int SECONDS)
-- The `alarm' function sets the real-time timer to expire in SECONDS
-- seconds. If you want to cancel any existing alarm, you can do
-- this by calling `alarm' with a SECONDS argument of zero.
--
-- The return value indicates how many seconds remain before the
-- previous alarm would have been sent. If there is no previous
-- alarm, `alarm' returns zero.
--
-- The `alarm' function could be defined in terms of `setitimer' like
--this:
--
-- unsigned int
-- alarm (unsigned int seconds)
-- {
-- struct itimerval old, new;
-- new.it_interval.tv_usec = 0;
-- new.it_interval.tv_sec = 0;
-- new.it_value.tv_usec = 0;
-- new.it_value.tv_sec = (long int) seconds;
-- if (setitimer (ITIMER_REAL, &new, &old) < 0)
-- return 0;
-- else
-- return old.it_value.tv_sec;
-- }
--
-- There is an example showing the use of the `alarm' function in *Note
--Handler Returns::.
--
-- If you simply want your process to wait for a given number of
--seconds, you should use the `sleep' function. *Note Sleeping::.
--
-- You shouldn't count on the signal arriving precisely when the timer
--expires. In a multiprocessing environment there is typically some
--amount of delay involved.
--
-- *Portability Note:* The `setitimer' and `getitimer' functions are
--derived from BSD Unix, while the `alarm' function is specified by the
--POSIX.1 standard. `setitimer' is more powerful than `alarm', but
--`alarm' is more widely used.
--
--
--File: libc.info, Node: Sleeping, Next: Resource Usage, Prev: Setting an
Alarm, Up: Date and Time
--
--Sleeping
--========
--
-- The function `sleep' gives a simple way to make the program wait for
--short periods of time. If your program doesn't use signals (except to
--terminate), then you can expect `sleep' to wait reliably for the
--specified amount of time. Otherwise, `sleep' can return sooner if a
--signal arrives; if you want to wait for a given period regardless of
--signals, use `select' (*note Waiting for I/O::.) and don't specify any
--descriptors to wait for.
--
-- - Function: unsigned int sleep (unsigned int SECONDS)
-- The `sleep' function waits for SECONDS or until a signal is
-- delivered, whichever happens first.
--
-- If `sleep' function returns because the requested time has
-- elapsed, it returns a value of zero. If it returns because of
-- delivery of a signal, its return value is the remaining time in
-- the sleep period.
--
-- The `sleep' function is declared in `unistd.h'.
--
-- Resist the temptation to implement a sleep for a fixed amount of
--time by using the return value of `sleep', when nonzero, to call
--`sleep' again. This will work with a certain amount of accuracy as
--long as signals arrive infrequently. But each signal can cause the
--eventual wakeup time to be off by an additional second or so. Suppose a
--few signals happen to arrive in rapid succession by bad luck--there is
--no limit on how much this could shorten or lengthen the wait.
--
-- Instead, compute the time at which the program should stop waiting,
--and keep trying to wait until that time. This won't be off by more
--than a second. With just a little more work, you can use `select' and
--make the waiting period quite accurate. (Of course, heavy system load
--can cause unavoidable additional delays--unless the machine is
--dedicated to one application, there is no way you can avoid this.)
--
-- On some systems, `sleep' can do strange things if your program uses
--`SIGALRM' explicitly. Even if `SIGALRM' signals are being ignored or
--blocked when `sleep' is called, `sleep' might return prematurely on
--delivery of a `SIGALRM' signal. If you have established a handler for
--`SIGALRM' signals and a `SIGALRM' signal is delivered while the process
--is sleeping, the action taken might be just to cause `sleep' to return
--instead of invoking your handler. And, if `sleep' is interrupted by
--delivery of a signal whose handler requests an alarm or alters the
--handling of `SIGALRM', this handler and `sleep' will interfere.
--
-- On the GNU system, it is safe to use `sleep' and `SIGALRM' in the
--same program, because `sleep' does not work by means of `SIGALRM'.
--
--
--File: libc.info, Node: Resource Usage, Next: Limits on Resources, Prev:
Sleeping, Up: Date and Time
--
--Resource Usage
--==============
--
-- The function `getrusage' and the data type `struct rusage' are used
--for examining the usage figures of a process. They are declared in
--`sys/resource.h'.
--
-- - Function: int getrusage (int PROCESSES, struct rusage *RUSAGE)
-- This function reports the usage totals for processes specified by
-- PROCESSES, storing the information in `*RUSAGE'.
--
-- In most systems, PROCESSES has only two valid values:
--
-- `RUSAGE_SELF'
-- Just the current process.
--
-- `RUSAGE_CHILDREN'
-- All child processes (direct and indirect) that have
-- terminated already.
--
-- In the GNU system, you can also inquire about a particular child
-- process by specifying its process ID.
--
-- The return value of `getrusage' is zero for success, and `-1' for
-- failure.
--
-- `EINVAL'
-- The argument PROCESSES is not valid.
--
-- One way of getting usage figures for a particular child process is
--with the function `wait4', which returns totals for a child when it
--terminates. *Note BSD Wait Functions::.
--
-- - Data Type: struct rusage
-- This data type records a collection usage amounts for various
-- sorts of resources. It has the following members, and possibly
-- others:
--
-- `struct timeval ru_utime'
-- Time spent executing user instructions.
--
-- `struct timeval ru_stime'
-- Time spent in operating system code on behalf of PROCESSES.
--
-- `long int ru_maxrss'
-- The maximum resident set size used, in kilobytes. That is,
-- the maximum number of kilobytes that PROCESSES used in real
-- memory simultaneously.
--
-- `long int ru_ixrss'
-- An integral value expressed in kilobytes times ticks of
-- execution, which indicates the amount of memory used by text
-- that was shared with other processes.
--
-- `long int ru_idrss'
-- An integral value expressed the same way, which is the amount
-- of unshared memory used in data.
--
-- `long int ru_isrss'
-- An integral value expressed the same way, which is the amount
-- of unshared memory used in stack space.
--
-- `long int ru_minflt'
-- The number of page faults which were serviced without
-- requiring any I/O.
--
-- `long int ru_majflt'
-- The number of page faults which were serviced by doing I/O.
--
-- `long int ru_nswap'
-- The number of times PROCESSES was swapped entirely out of
-- main memory.
--
-- `long int ru_inblock'
-- The number of times the file system had to read from the disk
-- on behalf of PROCESSES.
--
-- `long int ru_oublock'
-- The number of times the file system had to write to the disk
-- on behalf of PROCESSES.
--
-- `long int ru_msgsnd'
-- Number of IPC messages sent.
--
-- `long ru_msgrcv'
-- Number of IPC messages received.
--
-- `long int ru_nsignals'
-- Number of signals received.
--
-- `long int ru_nvcsw'
-- The number of times PROCESSES voluntarily invoked a context
-- switch (usually to wait for some service).
--
-- `long int ru_nivcsw'
-- The number of times an involuntary context switch took place
-- (because the time slice expired, or another process of higher
-- priority became runnable).
--
-- An additional historical function for examining usage figures,
--`vtimes', is supported but not documented here. It is declared in
--`sys/vtimes.h'.
--
--
--File: libc.info, Node: Limits on Resources, Next: Priority, Prev: Resource
Usage, Up: Date and Time
--
--Limiting Resource Usage
--=======================
--
-- You can specify limits for the resource usage of a process. When the
--process tries to exceed a limit, it may get a signal, or the system call
--by which it tried to do so may fail, depending on the limit. Each
--process initially inherits its limit values from its parent, but it can
--subsequently change them.
--
-- The symbols in this section are defined in `sys/resource.h'.
--
-- - Function: int getrlimit (int RESOURCE, struct rlimit *RLP)
-- Read the current value and the maximum value of resource RESOURCE
-- and store them in `*RLP'.
--
-- The return value is `0' on success and `-1' on failure. The only
-- possible `errno' error condition is `EFAULT'.
--
-- - Function: int setrlimit (int RESOURCE, struct rlimit *RLP)
-- Store the current value and the maximum value of resource RESOURCE
-- in `*RLP'.
--
-- The return value is `0' on success and `-1' on failure. The
-- following `errno' error condition is possible:
--
-- `EPERM'
-- You tried to change the maximum permissible limit value, but
-- you don't have privileges to do so.
--
-- - Data Type: struct rlimit
-- This structure is used with `getrlimit' to receive limit values,
-- and with `setrlimit' to specify limit values. It has two fields:
--
-- `rlim_cur'
-- The current value of the limit in question. This is also
-- called the "soft limit".
--
-- `rlim_max'
-- The maximum permissible value of the limit in question. You
-- cannot set the current value of the limit to a larger number
-- than this maximum. Only the super user can change the
-- maximum permissible value. This is also called the "hard
-- limit".
--
-- In `getrlimit', the structure is an output; it receives the current
-- values. In `setrlimit', it specifies the new values.
--
-- Here is a list of resources that you can specify a limit for. Those
--that are sizes are measured in bytes.
--
--`RLIMIT_CPU'
-- The maximum amount of cpu time the process can use. If it runs for
-- longer than this, it gets a signal: `SIGXCPU'. The value is
-- measured in seconds. *Note Operation Error Signals::.
--
--`RLIMIT_FSIZE'
-- The maximum size of file the process can create. Trying to write a
-- larger file causes a signal: `SIGXFSZ'. *Note Operation Error
-- Signals::.
--
--`RLIMIT_DATA'
-- The maximum size of data memory for the process. If the process
-- tries to allocate data memory beyond this amount, the allocation
-- function fails.
--
--`RLIMIT_STACK'
-- The maximum stack size for the process. If the process tries to
-- extend its stack past this size, it gets a `SIGSEGV' signal.
-- *Note Program Error Signals::.
--
--`RLIMIT_CORE'
-- The maximum size core file that this process can create. If the
-- process terminates and would dump a core file larger than this
-- maximum size, then no core file is created. So setting this limit
-- to zero prevents core files from ever being created.
--
--`RLIMIT_RSS'
-- The maximum amount of physical memory that this process should get.
-- This parameter is a guide for the system's scheduler and memory
-- allocator; the system may give the process more memory when there
-- is a surplus.
--
--`RLIMIT_MEMLOCK'
-- The maximum amount of memory that can be locked into physical
-- memory (so it will never be paged out).
--
--`RLIMIT_NPROC'
-- The maximum number of processes that can be created with the same
-- user ID. If you have reached the limit for your user ID, `fork'
-- will fail with `EAGAIN'. *Note Creating a Process::.
--
--`RLIMIT_NOFILE'
--`RLIMIT_OFILE'
-- The maximum number of files that the process can open. If it
-- tries to open more files than this, it gets error code `EMFILE'.
-- *Note Error Codes::. Not all systems support this limit; GNU
-- does, and 4.4 BSD does.
--
--`RLIM_NLIMITS'
-- The number of different resource limits. Any valid RESOURCE
-- operand must be less than `RLIM_NLIMITS'.
--
-- - Constant: int
-- This constant stands for a value of "infinity" when supplied as
-- the limit value in `setrlimit'.
--
-- Two historical functions for setting resource limits, `ulimit' and
--`vlimit', are not documented here. The latter is declared in
--`sys/vlimit.h' and comes from BSD.
--
--
--File: libc.info, Node: Priority, Prev: Limits on Resources, Up: Date and
Time
--
--Process Priority
--================
--
-- When several processes try to run, their respective priorities
--determine what share of the CPU each process gets. This section
--describes how you can read and set the priority of a process. All
--these functions and macros are declared in `sys/resource.h'.
--
-- The range of valid priority values depends on the operating system,
--but typically it runs from `-20' to `20'. A lower priority value means
--the process runs more often. These constants describe the range of
--priority values:
--
--`PRIO_MIN'
-- The smallest valid priority value.
--
--`PRIO_MAX'
-- The smallest valid priority value.
--
-- - Function: int getpriority (int CLASS, int ID)
-- Read the priority of a class of processes; CLASS and ID specify
-- which ones (see below). If the processes specified do not all
-- have the same priority, this returns the smallest value that any
-- of them has.
--
-- The return value is the priority value on success, and `-1' on
-- failure. The following `errno' error condition are possible for
-- this function:
--
-- `ESRCH'
-- The combination of CLASS and ID does not match any existing
-- process.
--
-- `EINVAL'
-- The value of CLASS is not valid.
--
-- When the return value is `-1', it could indicate failure, or it
-- could be the priority value. The only way to make certain is to
-- set `errno = 0' before calling `getpriority', then use `errno !=
-- 0' afterward as the criterion for failure.
--
-- - Function: int setpriority (int CLASS, int ID, int PRIORITY)
-- Set the priority of a class of processes to PRIORITY; CLASS and ID
-- specify which ones (see below).
--
-- The return value is `0' on success and `-1' on failure. The
-- following `errno' error condition are defined for this function:
--
-- `ESRCH'
-- The combination of CLASS and ID does not match any existing
-- process.
--
-- `EINVAL'
-- The value of CLASS is not valid.
--
-- `EPERM'
-- You tried to set the priority of some other user's process,
-- and you don't have privileges for that.
--
-- `EACCES'
-- You tried to lower the priority of a process, and you don't
-- have privileges for that.
--
-- The arguments CLASS and ID together specify a set of processes you
--are interested in. These are the possible values for CLASS:
--
--`PRIO_PROCESS'
-- Read or set the priority of one process. The argument ID is a
-- process ID.
--
--`PRIO_PGRP'
-- Read or set the priority of one process group. The argument ID is
-- a process group ID.
--
--`PRIO_USER'
-- Read or set the priority of one user's processes. The argument ID
-- is a user ID.
--
-- If the argument ID is 0, it stands for the current process, current
--process group, or the current user, according to CLASS.
--
-- - Function: int nice (int INCREMENT)
-- Increment the priority of the current process by INCREMENT. The
-- return value is the same as for `setpriority'.
--
-- Here is an equivalent definition for `nice':
--
-- int
-- nice (int increment)
-- {
-- int old = getpriority (PRIO_PROCESS, 0);
-- return setpriority (PRIO_PROCESS, 0, old + increment);
-- }
--
--
--File: libc.info, Node: Extended Characters, Next: Locales, Prev: String
and Array Utilities, Up: Top
--
--Extended Characters
--*******************
--
-- A number of languages use character sets that are larger than the
--range of values of type `char'. Japanese and Chinese are probably the
--most familiar examples.
--
-- The GNU C library includes support for two mechanisms for dealing
--with extended character sets: multibyte characters and wide characters.
--This chapter describes how to use these mechanisms, and the functions
--for converting between them.
--
-- The behavior of the functions in this chapter is affected by the
--current locale for character classification--the `LC_CTYPE' category;
--see *Note Locale Categories::. This choice of locale selects which
--multibyte code is used, and also controls the meanings and
--characteristics of wide character codes.
--
--* Menu:
--
--* Extended Char Intro:: Multibyte codes versus wide characters.
--* Locales and Extended Chars:: The locale selects the character codes.
--* Multibyte Char Intro:: How multibyte codes are represented.
--* Wide Char Intro:: How wide characters are represented.
--* Wide String Conversion:: Converting wide strings to multibyte code
-- and vice versa.
--* Length of Char:: how many bytes make up one multibyte char.
--* Converting One Char:: Converting a string character by character.
--* Example of Conversion:: Example showing why converting
-- one character at a time may be useful.
--* Shift State:: Multibyte codes with "shift characters".
--
--
--File: libc.info, Node: Extended Char Intro, Next: Locales and Extended
Chars, Up: Extended Characters
--
--Introduction to Extended Characters
--===================================
--
-- You can represent extended characters in either of two ways:
--
-- * As "multibyte characters" which can be embedded in an ordinary
-- string, an array of `char' objects. Their advantage is that many
-- programs and operating systems can handle occasional multibyte
-- characters scattered among ordinary ASCII characters, without any
-- change.
--
-- * As "wide characters", which are like ordinary characters except
-- that they occupy more bits. The wide character data type,
-- `wchar_t', has a range large enough to hold extended character
-- codes as well as old-fashioned ASCII codes.
--
-- An advantage of wide characters is that each character is a single
-- data object, just like ordinary ASCII characters. There are a few
-- disadvantages:
--
-- * Each existing program must be modified and recompiled to make
-- it use wide characters.
--
-- * Files of wide characters cannot be read by programs that
-- expect ordinary characters.
--
-- Typically, you use the multibyte character representation as part of
--the external program interface, such as reading or writing text to
--files. However, it's usually easier to perform internal manipulations
--on strings containing extended characters on arrays of `wchar_t'
--objects, since the uniform representation makes most editing operations
--easier. If you do use multibyte characters for files and wide
--characters for internal operations, you need to convert between them
--when you read and write data.
--
-- If your system supports extended characters, then it supports them
--both as multibyte characters and as wide characters. The library
--includes functions you can use to convert between the two
--representations. These functions are described in this chapter.
--
--
--File: libc.info, Node: Locales and Extended Chars, Next: Multibyte Char
Intro, Prev: Extended Char Intro, Up: Extended Characters
--
--Locales and Extended Characters
--===============================
--
-- A computer system can support more than one multibyte character code,
--and more than one wide character code. The user controls the choice of
--codes through the current locale for character classification (*note
--Locales::.). Each locale specifies a particular multibyte character
--code and a particular wide character code. The choice of locale
--influences the behavior of the conversion functions in the library.
--
-- Some locales support neither wide characters nor nontrivial multibyte
--characters. In these locales, the library conversion functions still
--work, even though what they do is basically trivial.
--
-- If you select a new locale for character classification, the internal
--shift state maintained by these functions can become confused, so it's
--not a good idea to change the locale while you are in the middle of
--processing a string.
--
--
--File: libc.info, Node: Multibyte Char Intro, Next: Wide Char Intro, Prev:
Locales and Extended Chars, Up: Extended Characters
--
--Multibyte Characters
--====================
--
-- In the ordinary ASCII code, a sequence of characters is a sequence of
--bytes, and each character is one byte. This is very simple, but allows
--for only 256 distinct characters.
--
-- In a "multibyte character code", a sequence of characters is a
--sequence of bytes, but each character may occupy one or more consecutive
--bytes of the sequence.
--
-- There are many different ways of designing a multibyte character
--code; different systems use different codes. To specify a particular
--code means designating the "basic" byte sequences--those which represent
--a single character--and what characters they stand for. A code that a
--computer can actually use must have a finite number of these basic
--sequences, and typically none of them is more than a few characters
--long.
--
-- These sequences need not all have the same length. In fact, many of
--them are just one byte long. Because the basic ASCII characters in the
--range from `0' to `0177' are so important, they stand for themselves in
--all multibyte character codes. That is to say, a byte whose value is
--`0' through `0177' is always a character in itself. The characters
--which are more than one byte must always start with a byte in the range
--from `0200' through `0377'.
--
-- The byte value `0' can be used to terminate a string, just as it is
--often used in a string of ASCII characters.
--
-- Specifying the basic byte sequences that represent single characters
--automatically gives meanings to many longer byte sequences, as more than
--one character. For example, if the two byte sequence `0205 049' stands
--for the Greek letter alpha, then `0205 049 065' must stand for an alpha
--followed by an `A' (ASCII code 065), and `0205 049 0205 049' must stand
--for two alphas in a row.
--
-- If any byte sequence can have more than one meaning as a sequence of
--characters, then the multibyte code is ambiguous--and no good. The
--codes that systems actually use are all unambiguous.
--
-- In most codes, there are certain sequences of bytes that have no
--meaning as a character or characters. These are called "invalid".
--
-- The simplest possible multibyte code is a trivial one:
--
-- The basic sequences consist of single bytes.
--
-- This particular code is equivalent to not using multibyte characters
--at all. It has no invalid sequences. But it can handle only 256
--different characters.
--
-- Here is another possible code which can handle 9376 different
--characters:
--
-- The basic sequences consist of
--
-- * single bytes with values in the range `0' through `0237'.
--
-- * two-byte sequences, in which both of the bytes have values in
-- the range from `0240' through `0377'.
--
--This code or a similar one is used on some systems to represent Japanese
--characters. The invalid sequences are those which consist of an odd
--number of consecutive bytes in the range from `0240' through `0377'.
--
-- Here is another multibyte code which can handle more distinct
--extended characters--in fact, almost thirty million:
--
-- The basic sequences consist of
--
-- * single bytes with values in the range `0' through `0177'.
--
-- * sequences of up to four bytes in which the first byte is in
-- the range from `0200' through `0237', and the remaining bytes
-- are in the range from `0240' through `0377'.
--
--In this code, any sequence that starts with a byte in the range from
--`0240' through `0377' is invalid.
--
-- And here is another variant which has the advantage that removing the
--last byte or bytes from a valid character can never produce another
--valid character. (This property is convenient when you want to search
--strings for particular characters.)
--
-- The basic sequences consist of
--
-- * single bytes with values in the range `0' through `0177'.
--
-- * two-byte sequences in which the first byte is in the range
-- from `0200' through `0207', and the second byte is in the
-- range from `0240' through `0377'.
--
-- * three-byte sequences in which the first byte is in the range
-- from `0210' through `0217', and the other bytes are in the
-- range from `0240' through `0377'.
--
-- * four-byte sequences in which the first byte is in the range
-- from `0220' through `0227', and the other bytes are in the
-- range from `0240' through `0377'.
--
--The list of invalid sequences for this code is long and not worth
--stating in full; examples of invalid sequences include `0240' and `0220
--0300 065'.
--
-- The number of *possible* multibyte codes is astronomical. But a
--given computer system will support at most a few different codes. (One
--of these codes may allow for thousands of different characters.)
--Another computer system may support a completely different code. The
--library facilities described in this chapter are helpful because they
--package up the knowledge of the details of a particular computer
--system's multibyte code, so your programs need not know them.
--
-- You can use special standard macros to find out the maximum possible
--number of bytes in a character in the currently selected multibyte code
--with `MB_CUR_MAX', and the maximum for *any* multibyte code supported
--on your computer with `MB_LEN_MAX'.
--
-- - Macro: int MB_LEN_MAX
-- This is the maximum length of a multibyte character for any
-- supported locale. It is defined in `limits.h'.
--
-- - Macro: int MB_CUR_MAX
-- This macro expands into a (possibly non-constant) positive integer
-- expression that is the maximum number of bytes in a multibyte
-- character in the current locale. The value is never greater than
-- `MB_LEN_MAX'.
--
-- `MB_CUR_MAX' is defined in `stdlib.h'.
--
-- Normally, each basic sequence in a particular character code stands
--for one character, the same character regardless of context. Some
--multibyte character codes have a concept of "shift state"; certain
--codes, called "shift sequences", change to a different shift state, and
--the meaning of some or all basic sequences varies according to the
--current shift state. In fact, the set of basic sequences might even be
--different depending on the current shift state. *Note Shift State::,
--for more information on handling this sort of code.
--
-- What happens if you try to pass a string containing multibyte
--characters to a function that doesn't know about them? Normally, such
--a function treats a string as a sequence of bytes, and interprets
--certain byte values specially; all other byte values are "ordinary".
--As long as a multibyte character doesn't contain any of the special
--byte values, the function should pass it through as if it were several
--ordinary characters.
--
-- For example, let's figure out what happens if you use multibyte
--characters in a file name. The functions such as `open' and `unlink'
--that operate on file names treat the name as a sequence of byte values,
--with `/' as the only special value. Any other byte values are copied,
--or compared, in sequence, and all byte values are treated alike. Thus,
--you may think of the file name as a sequence of bytes or as a string
--containing multibyte characters; the same behavior makes sense equally
--either way, provided no multibyte character contains a `/'.
--
--
--File: libc.info, Node: Wide Char Intro, Next: Wide String Conversion,
Prev: Multibyte Char Intro, Up: Extended Characters
--
--Wide Character Introduction
--===========================
--
-- "Wide characters" are much simpler than multibyte characters. They
--are simply characters with more than eight bits, so that they have room
--for more than 256 distinct codes. The wide character data type,
--`wchar_t', has a range large enough to hold extended character codes as
--well as old-fashioned ASCII codes.
--
-- An advantage of wide characters is that each character is a single
--data object, just like ordinary ASCII characters. Wide characters also
--have some disadvantages:
--
-- * A program must be modified and recompiled in order to use wide
-- characters at all.
--
-- * Files of wide characters cannot be read by programs that expect
-- ordinary characters.
--
-- Wide character values `0' through `0177' are always identical in
--meaning to the ASCII character codes. The wide character value zero is
--often used to terminate a string of wide characters, just as a single
--byte with value zero often terminates a string of ordinary characters.
--
-- - Data Type: wchar_t
-- This is the "wide character" type, an integer type whose range is
-- large enough to represent all distinct values in any extended
-- character set in the supported locales. *Note Locales::, for more
-- information about locales. This type is defined in the header
-- file `stddef.h'.
--
-- If your system supports extended characters, then each extended
--character has both a wide character code and a corresponding multibyte
--basic sequence.
--
-- In this chapter, the term "code" is used to refer to a single
--extended character object to emphasize the distinction from the `char'
--data type.
--
--
--File: libc.info, Node: Wide String Conversion, Next: Length of Char, Prev:
Wide Char Intro, Up: Extended Characters
--
--Conversion of Extended Strings
--==============================
--
-- The `mbstowcs' function converts a string of multibyte characters to
--a wide character array. The `wcstombs' function does the reverse.
--These functions are declared in the header file `stdlib.h'.
--
-- In most programs, these functions are the only ones you need for
--conversion between wide strings and multibyte character strings. But
--they have limitations. If your data is not null-terminated or is not
--all in core at once, you probably need to use the low-level conversion
--functions to convert one character at a time. *Note Converting One
--Char::.
--
-- - Function: size_t mbstowcs (wchar_t *WSTRING, const char *STRING,
-- size_t SIZE)
-- The `mbstowcs' ("multibyte string to wide character string")
-- function converts the null-terminated string of multibyte
-- characters STRING to an array of wide character codes, storing not
-- more than SIZE wide characters into the array beginning at WSTRING.
-- The terminating null character counts towards the size, so if SIZE
-- is less than the actual number of wide characters resulting from
-- STRING, no terminating null character is stored.
--
-- The conversion of characters from STRING begins in the initial
-- shift state.
--
-- If an invalid multibyte character sequence is found, this function
-- returns a value of `-1'. Otherwise, it returns the number of wide
-- characters stored in the array WSTRING. This number does not
-- include the terminating null character, which is present if the
-- number is less than SIZE.
--
-- Here is an example showing how to convert a string of multibyte
-- characters, allocating enough space for the result.
--
-- wchar_t *
-- mbstowcs_alloc (const char *string)
-- {
-- size_t size = strlen (string) + 1;
-- wchar_t *buf = xmalloc (size * sizeof (wchar_t));
--
-- size = mbstowcs (buf, string, size);
-- if (size == (size_t) -1)
-- return NULL;
-- buf = xrealloc (buf, (size + 1) * sizeof (wchar_t));
-- return buf;
-- }
--
--
-- - Function: size_t wcstombs (char *STRING, const wchar_t WSTRING,
-- size_t SIZE)
-- The `wcstombs' ("wide character string to multibyte string")
-- function converts the null-terminated wide character array WSTRING
-- into a string containing multibyte characters, storing not more
-- than SIZE bytes starting at STRING, followed by a terminating null
-- character if there is room. The conversion of characters begins in
-- the initial shift state.
--
-- The terminating null character counts towards the size, so if SIZE
-- is less than or equal to the number of bytes needed in WSTRING, no
-- terminating null character is stored.
--
-- If a code that does not correspond to a valid multibyte character
-- is found, this function returns a value of `-1'. Otherwise, the
-- return value is the number of bytes stored in the array STRING.
-- This number does not include the terminating null character, which
-- is present if the number is less than SIZE.
--
--
--File: libc.info, Node: Length of Char, Next: Converting One Char, Prev:
Wide String Conversion, Up: Extended Characters
--
--Multibyte Character Length
--==========================
--
-- This section describes how to scan a string containing multibyte
--characters, one character at a time. The difficulty in doing this is
--to know how many bytes each character contains. Your program can use
--`mblen' to find this out.
--
-- - Function: int mblen (const char *STRING, size_t SIZE)
-- The `mblen' function with a non-null STRING argument returns the
-- number of bytes that make up the multibyte character beginning at
-- STRING, never examining more than SIZE bytes. (The idea is to
-- supply for SIZE the number of bytes of data you have in hand.)
--
-- The return value of `mblen' distinguishes three possibilities: the
-- first SIZE bytes at STRING start with valid multibyte character,
-- they start with an invalid byte sequence or just part of a
-- character, or STRING points to an empty string (a null character).
--
-- For a valid multibyte character, `mblen' returns the number of
-- bytes in that character (always at least `1', and never more than
-- SIZE). For an invalid byte sequence, `mblen' returns `-1'. For
-- an empty string, it returns `0'.
--
-- If the multibyte character code uses shift characters, then `mblen'
-- maintains and updates a shift state as it scans. If you call
-- `mblen' with a null pointer for STRING, that initializes the shift
-- state to its standard initial value. It also returns nonzero if
-- the multibyte character code in use actually has a shift state.
-- *Note Shift State::.
--
-- The function `mblen' is declared in `stdlib.h'.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-19
glibc-2.0.1/manual/libc.info-19
---- ../glibc-2.0.1/manual/libc.info-19 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-19 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1234 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Converting One Char, Next: Example of Conversion,
Prev: Length of Char, Up: Extended Characters
--
--Conversion of Extended Characters One by One
--============================================
--
-- You can convert multibyte characters one at a time to wide characters
--with the `mbtowc' function. The `wctomb' function does the reverse.
--These functions are declared in `stdlib.h'.
--
-- - Function: int mbtowc (wchar_t *RESULT, const char *STRING, size_t
-- SIZE)
-- The `mbtowc' ("multibyte to wide character") function when called
-- with non-null STRING converts the first multibyte character
-- beginning at STRING to its corresponding wide character code. It
-- stores the result in `*RESULT'.
--
-- `mbtowc' never examines more than SIZE bytes. (The idea is to
-- supply for SIZE the number of bytes of data you have in hand.)
--
-- `mbtowc' with non-null STRING distinguishes three possibilities:
-- the first SIZE bytes at STRING start with valid multibyte
-- character, they start with an invalid byte sequence or just part
-- of a character, or STRING points to an empty string (a null
-- character).
--
-- For a valid multibyte character, `mbtowc' converts it to a wide
-- character and stores that in `*RESULT', and returns the number of
-- bytes in that character (always at least `1', and never more than
-- SIZE).
--
-- For an invalid byte sequence, `mbtowc' returns `-1'. For an empty
-- string, it returns `0', also storing `0' in `*RESULT'.
--
-- If the multibyte character code uses shift characters, then
-- `mbtowc' maintains and updates a shift state as it scans. If you
-- call `mbtowc' with a null pointer for STRING, that initializes the
-- shift state to its standard initial value. It also returns
-- nonzero if the multibyte character code in use actually has a
-- shift state. *Note Shift State::.
--
-- - Function: int wctomb (char *STRING, wchar_t WCHAR)
-- The `wctomb' ("wide character to multibyte") function converts the
-- wide character code WCHAR to its corresponding multibyte character
-- sequence, and stores the result in bytes starting at STRING. At
-- most `MB_CUR_MAX' characters are stored.
--
-- `wctomb' with non-null STRING distinguishes three possibilities
-- for WCHAR: a valid wide character code (one that can be translated
-- to a multibyte character), an invalid code, and `0'.
--
-- Given a valid code, `wctomb' converts it to a multibyte character,
-- storing the bytes starting at STRING. Then it returns the number
-- of bytes in that character (always at least `1', and never more
-- than `MB_CUR_MAX').
--
-- If WCHAR is an invalid wide character code, `wctomb' returns `-1'.
-- If WCHAR is `0', it returns `0', also storing `0' in `*STRING'.
--
-- If the multibyte character code uses shift characters, then
-- `wctomb' maintains and updates a shift state as it scans. If you
-- call `wctomb' with a null pointer for STRING, that initializes the
-- shift state to its standard initial value. It also returns
-- nonzero if the multibyte character code in use actually has a
-- shift state. *Note Shift State::.
--
-- Calling this function with a WCHAR argument of zero when STRING is
-- not null has the side-effect of reinitializing the stored shift
-- state *as well as* storing the multibyte character `0' and
-- returning `0'.
--
--
--File: libc.info, Node: Example of Conversion, Next: Shift State, Prev:
Converting One Char, Up: Extended Characters
--
--Character-by-Character Conversion Example
--=========================================
--
-- Here is an example that reads multibyte character text from
--descriptor `input' and writes the corresponding wide characters to
--descriptor `output'. We need to convert characters one by one for this
--example because `mbstowcs' is unable to continue past a null character,
--and cannot cope with an apparently invalid partial character by reading
--more input.
--
-- int
-- file_mbstowcs (int input, int output)
-- {
-- char buffer[BUFSIZ + MB_LEN_MAX];
-- int filled = 0;
-- int eof = 0;
--
-- while (!eof)
-- {
-- int nread;
-- int nwrite;
-- char *inp = buffer;
-- wchar_t outbuf[BUFSIZ];
-- wchar_t *outp = outbuf;
--
-- /* Fill up the buffer from the input file. */
-- nread = read (input, buffer + filled, BUFSIZ);
-- if (nread < 0)
-- {
-- perror ("read");
-- return 0;
-- }
-- /* If we reach end of file, make a note to read no more. */
-- if (nread == 0)
-- eof = 1;
--
-- /* `filled' is now the number of bytes in `buffer'. */
-- filled += nread;
--
-- /* Convert those bytes to wide characters-as many as we can. */
-- while (1)
-- {
-- int thislen = mbtowc (outp, inp, filled);
-- /* Stop converting at invalid character;
-- this can mean we have read just the first part
-- of a valid character. */
-- if (thislen == -1)
-- break;
-- /* Treat null character like any other,
-- but also reset shift state. */
-- if (thislen == 0) {
-- thislen = 1;
-- mbtowc (NULL, NULL, 0);
-- }
-- /* Advance past this character. */
-- inp += thislen;
-- filled -= thislen;
-- outp++;
-- }
--
-- /* Write the wide characters we just made. */
-- nwrite = write (output, outbuf,
-- (outp - outbuf) * sizeof (wchar_t));
-- if (nwrite < 0)
-- {
-- perror ("write");
-- return 0;
-- }
--
-- /* See if we have a *real* invalid character. */
-- if ((eof && filled > 0) || filled >= MB_CUR_MAX)
-- {
-- error ("invalid multibyte character");
-- return 0;
-- }
--
-- /* If any characters must be carried forward,
-- put them at the beginning of `buffer'. */
-- if (filled > 0)
-- memcpy (inp, buffer, filled);
-- }
-- }
--
-- return 1;
-- }
--
--
--File: libc.info, Node: Shift State, Prev: Example of Conversion, Up:
Extended Characters
--
--Multibyte Codes Using Shift Sequences
--=====================================
--
-- In some multibyte character codes, the *meaning* of any particular
--byte sequence is not fixed; it depends on what other sequences have come
--earlier in the same string. Typically there are just a few sequences
--that can change the meaning of other sequences; these few are called
--"shift sequences" and we say that they set the "shift state" for other
--sequences that follow.
--
-- To illustrate shift state and shift sequences, suppose we decide that
--the sequence `0200' (just one byte) enters Japanese mode, in which
--pairs of bytes in the range from `0240' to `0377' are single
--characters, while `0201' enters Latin-1 mode, in which single bytes in
--the range from `0240' to `0377' are characters, and interpreted
--according to the ISO Latin-1 character set. This is a multibyte code
--which has two alternative shift states ("Japanese mode" and "Latin-1
--mode"), and two shift sequences that specify particular shift states.
--
-- When the multibyte character code in use has shift states, then
--`mblen', `mbtowc' and `wctomb' must maintain and update the current
--shift state as they scan the string. To make this work properly, you
--must follow these rules:
--
-- * Before starting to scan a string, call the function with a null
-- pointer for the multibyte character address--for example, `mblen
-- (NULL, 0)'. This initializes the shift state to its standard
-- initial value.
--
-- * Scan the string one character at a time, in order. Do not "back
-- up" and rescan characters already scanned, and do not intersperse
-- the processing of different strings.
--
-- Here is an example of using `mblen' following these rules:
--
-- void
-- scan_string (char *s)
-- {
-- int length = strlen (s);
--
-- /* Initialize shift state. */
-- mblen (NULL, 0);
--
-- while (1)
-- {
-- int thischar = mblen (s, length);
-- /* Deal with end of string and invalid characters. */
-- if (thischar == 0)
-- break;
-- if (thischar == -1)
-- {
-- error ("invalid multibyte character");
-- break;
-- }
-- /* Advance past this character. */
-- s += thischar;
-- length -= thischar;
-- }
-- }
--
-- The functions `mblen', `mbtowc' and `wctomb' are not reentrant when
--using a multibyte code that uses a shift state. However, no other
--library functions call these functions, so you don't have to worry that
--the shift state will be changed mysteriously.
--
--
--File: libc.info, Node: Locales, Next: Searching and Sorting, Prev:
Extended Characters, Up: Top
--
--Locales and Internationalization
--********************************
--
-- Different countries and cultures have varying conventions for how to
--communicate. These conventions range from very simple ones, such as the
--format for representing dates and times, to very complex ones, such as
--the language spoken.
--
-- "Internationalization" of software means programming it to be able
--to adapt to the user's favorite conventions. In ISO C,
--internationalization works by means of "locales". Each locale
--specifies a collection of conventions, one convention for each purpose.
--The user chooses a set of conventions by specifying a locale (via
--environment variables).
--
-- All programs inherit the chosen locale as part of their environment.
--Provided the programs are written to obey the choice of locale, they
--will follow the conventions preferred by the user.
--
--* Menu:
--
--* Effects of Locale:: Actions affected by the choice of
-- locale.
--* Choosing Locale:: How the user specifies a locale.
--* Locale Categories:: Different purposes for which you can
-- select a locale.
--* Setting the Locale:: How a program specifies the locale
-- with library functions.
--* Standard Locales:: Locale names available on all systems.
--* Numeric Formatting:: How to format numbers according to the
-- chosen locale.
--
--
--File: libc.info, Node: Effects of Locale, Next: Choosing Locale, Up:
Locales
--
--What Effects a Locale Has
--=========================
--
-- Each locale specifies conventions for several purposes, including the
--following:
--
-- * What multibyte character sequences are valid, and how they are
-- interpreted (*note Extended Characters::.).
--
-- * Classification of which characters in the local character set are
-- considered alphabetic, and upper- and lower-case conversion
-- conventions (*note Character Handling::.).
--
-- * The collating sequence for the local language and character set
-- (*note Collation Functions::.).
--
-- * Formatting of numbers and currency amounts (*note Numeric
-- Formatting::.).
--
-- * Formatting of dates and times (*note Formatting Date and Time::.).
--
-- * What language to use for output, including error messages. (The C
-- library doesn't yet help you implement this.)
--
-- * What language to use for user answers to yes-or-no questions.
--
-- * What language to use for more complex user input. (The C library
-- doesn't yet help you implement this.)
--
-- Some aspects of adapting to the specified locale are handled
--automatically by the library subroutines. For example, all your program
--needs to do in order to use the collating sequence of the chosen locale
--is to use `strcoll' or `strxfrm' to compare strings.
--
-- Other aspects of locales are beyond the comprehension of the library.
--For example, the library can't automatically translate your program's
--output messages into other languages. The only way you can support
--output in the user's favorite language is to program this more or less
--by hand. (Eventually, we hope to provide facilities to make this
--easier.)
--
-- This chapter discusses the mechanism by which you can modify the
--current locale. The effects of the current locale on specific library
--functions are discussed in more detail in the descriptions of those
--functions.
--
--
--File: libc.info, Node: Choosing Locale, Next: Locale Categories, Prev:
Effects of Locale, Up: Locales
--
--Choosing a Locale
--=================
--
-- The simplest way for the user to choose a locale is to set the
--environment variable `LANG'. This specifies a single locale to use for
--all purposes. For example, a user could specify a hypothetical locale
--named `espana-castellano' to use the standard conventions of most of
--Spain.
--
-- The set of locales supported depends on the operating system you are
--using, and so do their names. We can't make any promises about what
--locales will exist, except for one standard locale called `C' or
--`POSIX'.
--
-- A user also has the option of specifying different locales for
--different purposes--in effect, choosing a mixture of multiple locales.
--
-- For example, the user might specify the locale `espana-castellano'
--for most purposes, but specify the locale `usa-english' for currency
--formatting. This might make sense if the user is a Spanish-speaking
--American, working in Spanish, but representing monetary amounts in US
--dollars.
--
-- Note that both locales `espana-castellano' and `usa-english', like
--all locales, would include conventions for all of the purposes to which
--locales apply. However, the user can choose to use each locale for a
--particular subset of those purposes.
--
--
--File: libc.info, Node: Locale Categories, Next: Setting the Locale, Prev:
Choosing Locale, Up: Locales
--
--Categories of Activities that Locales Affect
--============================================
--
-- The purposes that locales serve are grouped into "categories", so
--that a user or a program can choose the locale for each category
--independently. Here is a table of categories; each name is both an
--environment variable that a user can set, and a macro name that you can
--use as an argument to `setlocale'.
--
--`LC_COLLATE'
-- This category applies to collation of strings (functions `strcoll'
-- and `strxfrm'); see *Note Collation Functions::.
--
--`LC_CTYPE'
-- This category applies to classification and conversion of
-- characters, and to multibyte and wide characters; see *Note
-- Character Handling:: and *Note Extended Characters::.
--
--`LC_MONETARY'
-- This category applies to formatting monetary values; see *Note
-- Numeric Formatting::.
--
--`LC_NUMERIC'
-- This category applies to formatting numeric values that are not
-- monetary; see *Note Numeric Formatting::.
--
--`LC_TIME'
-- This category applies to formatting date and time values; see
-- *Note Formatting Date and Time::.
--
--`LC_MESSAGES'
-- This category applies to selecting the language used in the user
-- interface for message translation.
--
--`LC_ALL'
-- This is not an environment variable; it is only a macro that you
-- can use with `setlocale' to set a single locale for all purposes.
--
--`LANG'
-- If this environment variable is defined, its value specifies the
-- locale to use for all purposes except as overridden by the
-- variables above.
--
--
--File: libc.info, Node: Setting the Locale, Next: Standard Locales, Prev:
Locale Categories, Up: Locales
--
--How Programs Set the Locale
--===========================
--
-- A C program inherits its locale environment variables when it starts
--up. This happens automatically. However, these variables do not
--automatically control the locale used by the library functions, because
--ISO C says that all programs start by default in the standard `C'
--locale. To use the locales specified by the environment, you must call
--`setlocale'. Call it as follows:
--
-- setlocale (LC_ALL, "");
--
--to select a locale based on the appropriate environment variables.
--
-- You can also use `setlocale' to specify a particular locale, for
--general use or for a specific category.
--
-- The symbols in this section are defined in the header file
--`locale.h'.
--
-- - Function: char * setlocale (int CATEGORY, const char *LOCALE)
-- The function `setlocale' sets the current locale for category
-- CATEGORY to LOCALE.
--
-- If CATEGORY is `LC_ALL', this specifies the locale for all
-- purposes. The other possible values of CATEGORY specify an
-- individual purpose (*note Locale Categories::.).
--
-- You can also use this function to find out the current locale by
-- passing a null pointer as the LOCALE argument. In this case,
-- `setlocale' returns a string that is the name of the locale
-- currently selected for category CATEGORY.
--
-- The string returned by `setlocale' can be overwritten by subsequent
-- calls, so you should make a copy of the string (*note Copying and
-- Concatenation::.) if you want to save it past any further calls to
-- `setlocale'. (The standard library is guaranteed never to call
-- `setlocale' itself.)
--
-- You should not modify the string returned by `setlocale'. It
-- might be the same string that was passed as an argument in a
-- previous call to `setlocale'.
--
-- When you read the current locale for category `LC_ALL', the value
-- encodes the entire combination of selected locales for all
-- categories. In this case, the value is not just a single locale
-- name. In fact, we don't make any promises about what it looks
-- like. But if you specify the same "locale name" with `LC_ALL' in
-- a subsequent call to `setlocale', it restores the same combination
-- of locale selections.
--
-- When the LOCALE argument is not a null pointer, the string returned
-- by `setlocale' reflects the newly modified locale.
--
-- If you specify an empty string for LOCALE, this means to read the
-- appropriate environment variable and use its value to select the
-- locale for CATEGORY.
--
-- If you specify an invalid locale name, `setlocale' returns a null
-- pointer and leaves the current locale unchanged.
--
-- Here is an example showing how you might use `setlocale' to
--temporarily switch to a new locale.
--
-- #include <stddef.h>
-- #include <locale.h>
-- #include <stdlib.h>
-- #include <string.h>
--
-- void
-- with_other_locale (char *new_locale,
-- void (*subroutine) (int),
-- int argument)
-- {
-- char *old_locale, *saved_locale;
--
-- /* Get the name of the current locale. */
-- old_locale = setlocale (LC_ALL, NULL);
--
-- /* Copy the name so it won't be clobbered by `setlocale'. */
-- saved_locale = strdup (old_locale);
-- if (old_locale == NULL)
-- fatal ("Out of memory");
--
-- /* Now change the locale and do some stuff with it. */
-- setlocale (LC_ALL, new_locale);
-- (*subroutine) (argument);
--
-- /* Restore the original locale. */
-- setlocale (LC_ALL, saved_locale);
-- free (saved_locale);
-- }
--
-- *Portability Note:* Some ISO C systems may define additional locale
--categories. For portability, assume that any symbol beginning with
--`LC_' might be defined in `locale.h'.
--
--
--File: libc.info, Node: Standard Locales, Next: Numeric Formatting, Prev:
Setting the Locale, Up: Locales
--
--Standard Locales
--================
--
-- The only locale names you can count on finding on all operating
--systems are these three standard ones:
--
--`"C"'
-- This is the standard C locale. The attributes and behavior it
-- provides are specified in the ISO C standard. When your program
-- starts up, it initially uses this locale by default.
--
--`"POSIX"'
-- This is the standard POSIX locale. Currently, it is an alias for
-- the standard C locale.
--
--`""'
-- The empty name says to select a locale based on environment
-- variables. *Note Locale Categories::.
--
-- Defining and installing named locales is normally a responsibility of
--the system administrator at your site (or the person who installed the
--GNU C library). Some systems may allow users to create locales, but we
--don't discuss that here.
--
-- If your program needs to use something other than the `C' locale, it
--will be more portable if you use whatever locale the user specifies
--with the environment, rather than trying to specify some non-standard
--locale explicitly by name. Remember, different machines might have
--different sets of locales installed.
--
--
--File: libc.info, Node: Numeric Formatting, Prev: Standard Locales, Up:
Locales
--
--Numeric Formatting
--==================
--
-- When you want to format a number or a currency amount using the
--conventions of the current locale, you can use the function
--`localeconv' to get the data on how to do it. The function
--`localeconv' is declared in the header file `locale.h'.
--
-- - Function: struct lconv * localeconv (void)
-- The `localeconv' function returns a pointer to a structure whose
-- components contain information about how numeric and monetary
-- values should be formatted in the current locale.
--
-- You shouldn't modify the structure or its contents. The structure
-- might be overwritten by subsequent calls to `localeconv', or by
-- calls to `setlocale', but no other function in the library
-- overwrites this value.
--
-- - Data Type: struct lconv
-- This is the data type of the value returned by `localeconv'.
--
-- If a member of the structure `struct lconv' has type `char', and the
--value is `CHAR_MAX', it means that the current locale has no value for
--that parameter.
--
--* Menu:
--
--* General Numeric:: Parameters for formatting numbers and
-- currency amounts.
--* Currency Symbol:: How to print the symbol that identifies an
-- amount of money (e.g. `$').
--* Sign of Money Amount:: How to print the (positive or negative) sign
-- for a monetary amount, if one exists.
--
--
--File: libc.info, Node: General Numeric, Next: Currency Symbol, Up: Numeric
Formatting
--
--Generic Numeric Formatting Parameters
---------------------------------------
--
-- These are the standard members of `struct lconv'; there may be
--others.
--
--`char *decimal_point'
--`char *mon_decimal_point'
-- These are the decimal-point separators used in formatting
-- non-monetary and monetary quantities, respectively. In the `C'
-- locale, the value of `decimal_point' is `"."', and the value of
-- `mon_decimal_point' is `""'.
--
--`char *thousands_sep'
--`char *mon_thousands_sep'
-- These are the separators used to delimit groups of digits to the
-- left of the decimal point in formatting non-monetary and monetary
-- quantities, respectively. In the `C' locale, both members have a
-- value of `""' (the empty string).
--
--`char *grouping'
--`char *mon_grouping'
-- These are strings that specify how to group the digits to the left
-- of the decimal point. `grouping' applies to non-monetary
-- quantities and `mon_grouping' applies to monetary quantities. Use
-- either `thousands_sep' or `mon_thousands_sep' to separate the digit
-- groups.
--
-- Each string is made up of decimal numbers separated by semicolons.
-- Successive numbers (from left to right) give the sizes of
-- successive groups (from right to left, starting at the decimal
-- point). The last number in the string is used over and over for
-- all the remaining groups.
--
-- If the last integer is `-1', it means that there is no more
-- grouping--or, put another way, any remaining digits form one large
-- group without separators.
--
-- For example, if `grouping' is `"4;3;2"', the correct grouping for
-- the number `123456787654321' is `12', `34', `56', `78', `765',
-- `4321'. This uses a group of 4 digits at the end, preceded by a
-- group of 3 digits, preceded by groups of 2 digits (as many as
-- needed). With a separator of `,', the number would be printed as
-- `12,34,56,78,765,4321'.
--
-- A value of `"3"' indicates repeated groups of three digits, as
-- normally used in the U.S.
--
-- In the standard `C' locale, both `grouping' and `mon_grouping'
-- have a value of `""'. This value specifies no grouping at all.
--
--`char int_frac_digits'
--`char frac_digits'
-- These are small integers indicating how many fractional digits (to
-- the right of the decimal point) should be displayed in a monetary
-- value in international and local formats, respectively. (Most
-- often, both members have the same value.)
--
-- In the standard `C' locale, both of these members have the value
-- `CHAR_MAX', meaning "unspecified". The ISO standard doesn't say
-- what to do when you find this the value; we recommend printing no
-- fractional digits. (This locale also specifies the empty string
-- for `mon_decimal_point', so printing any fractional digits would be
-- confusing!)
--
--
--File: libc.info, Node: Currency Symbol, Next: Sign of Money Amount, Prev:
General Numeric, Up: Numeric Formatting
--
--Printing the Currency Symbol
------------------------------
--
-- These members of the `struct lconv' structure specify how to print
--the symbol to identify a monetary value--the international analog of
--`$' for US dollars.
--
-- Each country has two standard currency symbols. The "local currency
--symbol" is used commonly within the country, while the "international
--currency symbol" is used internationally to refer to that country's
--currency when it is necessary to indicate the country unambiguously.
--
-- For example, many countries use the dollar as their monetary unit,
--and when dealing with international currencies it's important to specify
--that one is dealing with (say) Canadian dollars instead of U.S. dollars
--or Australian dollars. But when the context is known to be Canada,
--there is no need to make this explicit--dollar amounts are implicitly
--assumed to be in Canadian dollars.
--
--`char *currency_symbol'
-- The local currency symbol for the selected locale.
--
-- In the standard `C' locale, this member has a value of `""' (the
-- empty string), meaning "unspecified". The ISO standard doesn't
-- say what to do when you find this value; we recommend you simply
-- print the empty string as you would print any other string found
-- in the appropriate member.
--
--`char *int_curr_symbol'
-- The international currency symbol for the selected locale.
--
-- The value of `int_curr_symbol' should normally consist of a
-- three-letter abbreviation determined by the international standard
-- `ISO 4217 Codes for the Representation of Currency and Funds',
-- followed by a one-character separator (often a space).
--
-- In the standard `C' locale, this member has a value of `""' (the
-- empty string), meaning "unspecified". We recommend you simply
-- print the empty string as you would print any other string found
-- in the appropriate member.
--
--`char p_cs_precedes'
--`char n_cs_precedes'
-- These members are `1' if the `currency_symbol' string should
-- precede the value of a monetary amount, or `0' if the string should
-- follow the value. The `p_cs_precedes' member applies to positive
-- amounts (or zero), and the `n_cs_precedes' member applies to
-- negative amounts.
--
-- In the standard `C' locale, both of these members have a value of
-- `CHAR_MAX', meaning "unspecified". The ISO standard doesn't say
-- what to do when you find this value, but we recommend printing the
-- currency symbol before the amount. That's right for most
-- countries. In other words, treat all nonzero values alike in
-- these members.
--
-- The POSIX standard says that these two members apply to the
-- `int_curr_symbol' as well as the `currency_symbol'. The ISO C
-- standard seems to imply that they should apply only to the
-- `currency_symbol'--so the `int_curr_symbol' should always precede
-- the amount.
--
-- We can only guess which of these (if either) matches the usual
-- conventions for printing international currency symbols. Our
-- guess is that they should always precede the amount. If we find
-- out a reliable answer, we will put it here.
--
--`char p_sep_by_space'
--`char n_sep_by_space'
-- These members are `1' if a space should appear between the
-- `currency_symbol' string and the amount, or `0' if no space should
-- appear. The `p_sep_by_space' member applies to positive amounts
-- (or zero), and the `n_sep_by_space' member applies to negative
-- amounts.
--
-- In the standard `C' locale, both of these members have a value of
-- `CHAR_MAX', meaning "unspecified". The ISO standard doesn't say
-- what you should do when you find this value; we suggest you treat
-- it as one (print a space). In other words, treat all nonzero
-- values alike in these members.
--
-- These members apply only to `currency_symbol'. When you use
-- `int_curr_symbol', you never print an additional space, because
-- `int_curr_symbol' itself contains the appropriate separator.
--
-- The POSIX standard says that these two members apply to the
-- `int_curr_symbol' as well as the `currency_symbol'. But an
-- example in the ISO C standard clearly implies that they should
-- apply only to the `currency_symbol'--that the `int_curr_symbol'
-- contains any appropriate separator, so you should never print an
-- additional space.
--
-- Based on what we know now, we recommend you ignore these members
-- when printing international currency symbols, and print no extra
-- space.
--
--
--File: libc.info, Node: Sign of Money Amount, Prev: Currency Symbol, Up:
Numeric Formatting
--
--Printing the Sign of an Amount of Money
-----------------------------------------
--
-- These members of the `struct lconv' structure specify how to print
--the sign (if any) in a monetary value.
--
--`char *positive_sign'
--`char *negative_sign'
-- These are strings used to indicate positive (or zero) and negative
-- (respectively) monetary quantities.
--
-- In the standard `C' locale, both of these members have a value of
-- `""' (the empty string), meaning "unspecified".
--
-- The ISO standard doesn't say what to do when you find this value;
-- we recommend printing `positive_sign' as you find it, even if it is
-- empty. For a negative value, print `negative_sign' as you find it
-- unless both it and `positive_sign' are empty, in which case print
-- `-' instead. (Failing to indicate the sign at all seems rather
-- unreasonable.)
--
--`char p_sign_posn'
--`char n_sign_posn'
-- These members have values that are small integers indicating how to
-- position the sign for nonnegative and negative monetary quantities,
-- respectively. (The string used by the sign is what was specified
-- with `positive_sign' or `negative_sign'.) The possible values are
-- as follows:
--
-- `0'
-- The currency symbol and quantity should be surrounded by
-- parentheses.
--
-- `1'
-- Print the sign string before the quantity and currency symbol.
--
-- `2'
-- Print the sign string after the quantity and currency symbol.
--
-- `3'
-- Print the sign string right before the currency symbol.
--
-- `4'
-- Print the sign string right after the currency symbol.
--
-- `CHAR_MAX'
-- "Unspecified". Both members have this value in the standard
-- `C' locale.
--
-- The ISO standard doesn't say what you should do when the value is
-- `CHAR_MAX'. We recommend you print the sign after the currency
-- symbol.
--
-- It is not clear whether you should let these members apply to the
--international currency format or not. POSIX says you should, but
--intuition plus the examples in the ISO C standard suggest you should
--not. We hope that someone who knows well the conventions for formatting
--monetary quantities will tell us what we should recommend.
--
--
--File: libc.info, Node: Non-Local Exits, Next: Signal Handling, Prev: Date
and Time, Up: Top
--
--Non-Local Exits
--***************
--
-- Sometimes when your program detects an unusual situation inside a
--deeply nested set of function calls, you would like to be able to
--immediately return to an outer level of control. This section
--describes how you can do such "non-local exits" using the `setjmp' and
--`longjmp' functions.
--
--* Menu:
--
--* Intro: Non-Local Intro. When and how to use these facilities.
--* Details: Non-Local Details. Functions for nonlocal exits.
--* Non-Local Exits and Signals:: Portability issues.
--
--
--File: libc.info, Node: Non-Local Intro, Next: Non-Local Details, Up:
Non-Local Exits
--
--Introduction to Non-Local Exits
--===============================
--
-- As an example of a situation where a non-local exit can be useful,
--suppose you have an interactive program that has a "main loop" that
--prompts for and executes commands. Suppose the "read" command reads
--input from a file, doing some lexical analysis and parsing of the input
--while processing it. If a low-level input error is detected, it would
--be useful to be able to return immediately to the "main loop" instead
--of having to make each of the lexical analysis, parsing, and processing
--phases all have to explicitly deal with error situations initially
--detected by nested calls.
--
-- (On the other hand, if each of these phases has to do a substantial
--amount of cleanup when it exits--such as closing files, deallocating
--buffers or other data structures, and the like--then it can be more
--appropriate to do a normal return and have each phase do its own
--cleanup, because a non-local exit would bypass the intervening phases
--and their associated cleanup code entirely. Alternatively, you could
--use a non-local exit but do the cleanup explicitly either before or
--after returning to the "main loop".)
--
-- In some ways, a non-local exit is similar to using the `return'
--statement to return from a function. But while `return' abandons only
--a single function call, transferring control back to the point at which
--it was called, a non-local exit can potentially abandon many levels of
--nested function calls.
--
-- You identify return points for non-local exits calling the function
--`setjmp'. This function saves information about the execution
--environment in which the call to `setjmp' appears in an object of type
--`jmp_buf'. Execution of the program continues normally after the call
--to `setjmp', but if a exit is later made to this return point by
--calling `longjmp' with the corresponding `jmp_buf' object, control is
--transferred back to the point where `setjmp' was called. The return
--value from `setjmp' is used to distinguish between an ordinary return
--and a return made by a call to `longjmp', so calls to `setjmp' usually
--appear in an `if' statement.
--
-- Here is how the example program described above might be set up:
--
-- #include <setjmp.h>
-- #include <stdlib.h>
-- #include <stdio.h>
--
-- jmp_buf main_loop;
--
-- void
-- abort_to_main_loop (int status)
-- {
-- longjmp (main_loop, status);
-- }
--
-- int
-- main (void)
-- {
-- while (1)
-- if (setjmp (main_loop))
-- puts ("Back at main loop....");
-- else
-- do_command ();
-- }
--
--
-- void
-- do_command (void)
-- {
-- char buffer[128];
-- if (fgets (buffer, 128, stdin) == NULL)
-- abort_to_main_loop (-1);
-- else
-- exit (EXIT_SUCCESS);
-- }
--
-- The function `abort_to_main_loop' causes an immediate transfer of
--control back to the main loop of the program, no matter where it is
--called from.
--
-- The flow of control inside the `main' function may appear a little
--mysterious at first, but it is actually a common idiom with `setjmp'.
--A normal call to `setjmp' returns zero, so the "else" clause of the
--conditional is executed. If `abort_to_main_loop' is called somewhere
--within the execution of `do_command', then it actually appears as if
--the *same* call to `setjmp' in `main' were returning a second time with
--a value of `-1'.
--
-- So, the general pattern for using `setjmp' looks something like:
--
-- if (setjmp (BUFFER))
-- /* Code to clean up after premature return. */
-- ...
-- else
-- /* Code to be executed normally after setting up the return point. */
-- ...
--
--
--File: libc.info, Node: Non-Local Details, Next: Non-Local Exits and
Signals, Prev: Non-Local Intro, Up: Non-Local Exits
--
--Details of Non-Local Exits
--==========================
--
-- Here are the details on the functions and data structures used for
--performing non-local exits. These facilities are declared in
--`setjmp.h'.
--
-- - Data Type: jmp_buf
-- Objects of type `jmp_buf' hold the state information to be
-- restored by a non-local exit. The contents of a `jmp_buf'
-- identify a specific place to return to.
--
-- - Macro: int setjmp (jmp_buf STATE)
-- When called normally, `setjmp' stores information about the
-- execution state of the program in STATE and returns zero. If
-- `longjmp' is later used to perform a non-local exit to this STATE,
-- `setjmp' returns a nonzero value.
--
-- - Function: void longjmp (jmp_buf STATE, int VALUE)
-- This function restores current execution to the state saved in
-- STATE, and continues execution from the call to `setjmp' that
-- established that return point. Returning from `setjmp' by means of
-- `longjmp' returns the VALUE argument that was passed to `longjmp',
-- rather than `0'. (But if VALUE is given as `0', `setjmp' returns
-- `1').
--
-- There are a lot of obscure but important restrictions on the use of
--`setjmp' and `longjmp'. Most of these restrictions are present because
--non-local exits require a fair amount of magic on the part of the C
--compiler and can interact with other parts of the language in strange
--ways.
--
-- The `setjmp' function is actually a macro without an actual function
--definition, so you shouldn't try to `#undef' it or take its address.
--In addition, calls to `setjmp' are safe in only the following contexts:
--
-- * As the test expression of a selection or iteration statement (such
-- as `if', `switch', or `while').
--
-- * As one operand of a equality or comparison operator that appears
-- as the test expression of a selection or iteration statement. The
-- other operand must be an integer constant expression.
--
-- * As the operand of a unary `!' operator, that appears as the test
-- expression of a selection or iteration statement.
--
-- * By itself as an expression statement.
--
-- Return points are valid only during the dynamic extent of the
--function that called `setjmp' to establish them. If you `longjmp' to a
--return point that was established in a function that has already
--returned, unpredictable and disastrous things are likely to happen.
--
-- You should use a nonzero VALUE argument to `longjmp'. While
--`longjmp' refuses to pass back a zero argument as the return value from
--`setjmp', this is intended as a safety net against accidental misuse
--and is not really good programming style.
--
-- When you perform a non-local exit, accessible objects generally
--retain whatever values they had at the time `longjmp' was called. The
--exception is that the values of automatic variables local to the
--function containing the `setjmp' call that have been changed since the
--call to `setjmp' are indeterminate, unless you have declared them
--`volatile'.
--
--
--File: libc.info, Node: Non-Local Exits and Signals, Prev: Non-Local
Details, Up: Non-Local Exits
--
--Non-Local Exits and Signals
--===========================
--
-- In BSD Unix systems, `setjmp' and `longjmp' also save and restore
--the set of blocked signals; see *Note Blocking Signals::. However, the
--POSIX.1 standard requires `setjmp' and `longjmp' not to change the set
--of blocked signals, and provides an additional pair of functions
--(`sigsetjmp' and `sigsetjmp') to get the BSD behavior.
--
-- The behavior of `setjmp' and `longjmp' in the GNU library is
--controlled by feature test macros; see *Note Feature Test Macros::. The
--default in the GNU system is the POSIX.1 behavior rather than the BSD
--behavior.
--
-- The facilities in this section are declared in the header file
--`setjmp.h'.
--
-- - Data Type: sigjmp_buf
-- This is similar to `jmp_buf', except that it can also store state
-- information about the set of blocked signals.
--
-- - Function: int sigsetjmp (sigjmp_buf STATE, int SAVESIGS)
-- This is similar to `setjmp'. If SAVESIGS is nonzero, the set of
-- blocked signals is saved in STATE and will be restored if a
-- `siglongjmp' is later performed with this STATE.
--
-- - Function: void siglongjmp (sigjmp_buf STATE, int VALUE)
-- This is similar to `longjmp' except for the type of its STATE
-- argument. If the `sigsetjmp' call that set this STATE used a
-- nonzero SAVESIGS flag, `siglongjmp' also restores the set of
-- blocked signals.
--
--
--File: libc.info, Node: Signal Handling, Next: Process Startup, Prev:
Non-Local Exits, Up: Top
--
--Signal Handling
--***************
--
-- A "signal" is a software interrupt delivered to a process. The
--operating system uses signals to report exceptional situations to an
--executing program. Some signals report errors such as references to
--invalid memory addresses; others report asynchronous events, such as
--disconnection of a phone line.
--
-- The GNU C library defines a variety of signal types, each for a
--particular kind of event. Some kinds of events make it inadvisable or
--impossible for the program to proceed as usual, and the corresponding
--signals normally abort the program. Other kinds of signals that report
--harmless events are ignored by default.
--
-- If you anticipate an event that causes signals, you can define a
--handler function and tell the operating system to run it when that
--particular type of signal arrives.
--
-- Finally, one process can send a signal to another process; this
--allows a parent process to abort a child, or two related processes to
--communicate and synchronize.
--
--* Menu:
--
--* Concepts of Signals:: Introduction to the signal facilities.
--* Standard Signals:: Particular kinds of signals with
-- standard names and meanings.
--* Signal Actions:: Specifying what happens when a
-- particular signal is delivered.
--* Defining Handlers:: How to write a signal handler function.
--* Interrupted Primitives:: Signal handlers affect use of `open',
-- `read', `write' and other functions.
--* Generating Signals:: How to send a signal to a process.
--* Blocking Signals:: Making the system hold signals temporarily.
--* Waiting for a Signal:: Suspending your program until a signal
-- arrives.
--* Signal Stack:: Using a Separate Signal Stack.
--* BSD Signal Handling:: Additional functions for backward
-- compatibility with BSD.
--
--
--File: libc.info, Node: Concepts of Signals, Next: Standard Signals, Up:
Signal Handling
--
--Basic Concepts of Signals
--=========================
--
-- This section explains basic concepts of how signals are generated,
--what happens after a signal is delivered, and how programs can handle
--signals.
--
--* Menu:
--
--* Kinds of Signals:: Some examples of what can cause a signal.
--* Signal Generation:: Concepts of why and how signals occur.
--* Delivery of Signal:: Concepts of what a signal does to the
-- process.
--
--
--File: libc.info, Node: Kinds of Signals, Next: Signal Generation, Up:
Concepts of Signals
--
--Some Kinds of Signals
-----------------------
--
-- A signal reports the occurrence of an exceptional event. These are
--some of the events that can cause (or "generate", or "raise") a signal:
--
-- * A program error such as dividing by zero or issuing an address
-- outside the valid range.
--
-- * A user request to interrupt or terminate the program. Most
-- environments are set up to let a user suspend the program by
-- typing `C-z', or terminate it with `C-c'. Whatever key sequence
-- is used, the operating system sends the proper signal to interrupt
-- the process.
--
-- * The termination of a child process.
--
-- * Expiration of a timer or alarm.
--
-- * A call to `kill' or `raise' by the same process.
--
-- * A call to `kill' from another process. Signals are a limited but
-- useful form of interprocess communication.
--
-- * An attempt to perform an I/O operation that cannot be done.
-- Examples are reading from a pipe that has no writer (*note Pipes
-- and FIFOs::.), and reading or writing to a terminal in certain
-- situations (*note Job Control::.).
--
-- Each of these kinds of events (excepting explicit calls to `kill'
--and `raise') generates its own particular kind of signal. The various
--kinds of signals are listed and described in detail in *Note Standard
--Signals::.
--
--
--File: libc.info, Node: Signal Generation, Next: Delivery of Signal, Prev:
Kinds of Signals, Up: Concepts of Signals
--
--Concepts of Signal Generation
-------------------------------
--
-- In general, the events that generate signals fall into three major
--categories: errors, external events, and explicit requests.
--
-- An error means that a program has done something invalid and cannot
--continue execution. But not all kinds of errors generate signals--in
--fact, most do not. For example, opening a nonexistent file is an error,
--but it does not raise a signal; instead, `open' returns `-1'. In
--general, errors that are necessarily associated with certain library
--functions are reported by returning a value that indicates an error.
--The errors which raise signals are those which can happen anywhere in
--the program, not just in library calls. These include division by zero
--and invalid memory addresses.
--
-- An external event generally has to do with I/O or other processes.
--These include the arrival of input, the expiration of a timer, and the
--termination of a child process.
--
-- An explicit request means the use of a library function such as
--`kill' whose purpose is specifically to generate a signal.
--
-- Signals may be generated "synchronously" or "asynchronously". A
--synchronous signal pertains to a specific action in the program, and is
--delivered (unless blocked) during that action. Most errors generate
--signals synchronously, and so do explicit requests by a process to
--generate a signal for that same process. On some machines, certain
--kinds of hardware errors (usually floating-point exceptions) are not
--reported completely synchronously, but may arrive a few instructions
--later.
--
-- Asynchronous signals are generated by events outside the control of
--the process that receives them. These signals arrive at unpredictable
--times during execution. External events generate signals
--asynchronously, and so do explicit requests that apply to some other
--process.
--
-- A given type of signal is either typically synchronous or typically
--asynchronous. For example, signals for errors are typically synchronous
--because errors generate signals synchronously. But any type of signal
--can be generated synchronously or asynchronously with an explicit
--request.
--
--
--File: libc.info, Node: Delivery of Signal, Prev: Signal Generation, Up:
Concepts of Signals
--
--How Signals Are Delivered
---------------------------
--
-- When a signal is generated, it becomes "pending". Normally it
--remains pending for just a short period of time and then is "delivered"
--to the process that was signaled. However, if that kind of signal is
--currently "blocked", it may remain pending indefinitely--until signals
--of that kind are "unblocked". Once unblocked, it will be delivered
--immediately. *Note Blocking Signals::.
--
-- When the signal is delivered, whether right away or after a long
--delay, the "specified action" for that signal is taken. For certain
--signals, such as `SIGKILL' and `SIGSTOP', the action is fixed, but for
--most signals, the program has a choice: ignore the signal, specify a
--"handler function", or accept the "default action" for that kind of
--signal. The program specifies its choice using functions such as
--`signal' or `sigaction' (*note Signal Actions::.). We sometimes say
--that a handler "catches" the signal. While the handler is running,
--that particular signal is normally blocked.
--
-- If the specified action for a kind of signal is to ignore it, then
--any such signal which is generated is discarded immediately. This
--happens even if the signal is also blocked at the time. A signal
--discarded in this way will never be delivered, not even if the program
--subsequently specifies a different action for that kind of signal and
--then unblocks it.
--
-- If a signal arrives which the program has neither handled nor
--ignored, its "default action" takes place. Each kind of signal has its
--own default action, documented below (*note Standard Signals::.). For
--most kinds of signals, the default action is to terminate the process.
--For certain kinds of signals that represent "harmless" events, the
--default action is to do nothing.
--
-- When a signal terminates a process, its parent process can determine
--the cause of termination by examining the termination status code
--reported by the `wait' or `waitpid' functions. (This is discussed in
--more detail in *Note Process Completion::.) The information it can get
--includes the fact that termination was due to a signal, and the kind of
--signal involved. If a program you run from a shell is terminated by a
--signal, the shell typically prints some kind of error message.
--
-- The signals that normally represent program errors have a special
--property: when one of these signals terminates the process, it also
--writes a "core dump file" which records the state of the process at the
--time of termination. You can examine the core dump with a debugger to
--investigate what caused the error.
--
-- If you raise a "program error" signal by explicit request, and this
--terminates the process, it makes a core dump file just as if the signal
--had been due directly to an error.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-2
glibc-2.0.1/manual/libc.info-2
---- ../glibc-2.0.1/manual/libc.info-2 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-2 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1202 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Header Files, Next: Macro Definitions, Up: Using
the Library
--
--Header Files
--------------
--
-- Libraries for use by C programs really consist of two parts: "header
--files" that define types and macros and declare variables and
--functions; and the actual library or "archive" that contains the
--definitions of the variables and functions.
--
-- (Recall that in C, a "declaration" merely provides information that
--a function or variable exists and gives its type. For a function
--declaration, information about the types of its arguments might be
--provided as well. The purpose of declarations is to allow the compiler
--to correctly process references to the declared variables and functions.
--A "definition", on the other hand, actually allocates storage for a
--variable or says what a function does.)
--
-- In order to use the facilities in the GNU C library, you should be
--sure that your program source files include the appropriate header
--files. This is so that the compiler has declarations of these
--facilities available and can correctly process references to them.
--Once your program has been compiled, the linker resolves these
--references to the actual definitions provided in the archive file.
--
-- Header files are included into a program source file by the
--`#include' preprocessor directive. The C language supports two forms
--of this directive; the first,
--
-- #include "HEADER"
--
--is typically used to include a header file HEADER that you write
--yourself; this would contain definitions and declarations describing the
--interfaces between the different parts of your particular application.
--By contrast,
--
-- #include <file.h>
--
--is typically used to include a header file `file.h' that contains
--definitions and declarations for a standard library. This file would
--normally be installed in a standard place by your system administrator.
--You should use this second form for the C library header files.
--
-- Typically, `#include' directives are placed at the top of the C
--source file, before any other code. If you begin your source files with
--some comments explaining what the code in the file does (a good idea),
--put the `#include' directives immediately afterwards, following the
--feature test macro definition (*note Feature Test Macros::.).
--
-- For more information about the use of header files and `#include'
--directives, *note Header Files: (cpp.info)Header Files..
--
-- The GNU C library provides several header files, each of which
--contains the type and macro definitions and variable and function
--declarations for a group of related facilities. This means that your
--programs may need to include several header files, depending on exactly
--which facilities you are using.
--
-- Some library header files include other library header files
--automatically. However, as a matter of programming style, you should
--not rely on this; it is better to explicitly include all the header
--files required for the library facilities you are using. The GNU C
--library header files have been written in such a way that it doesn't
--matter if a header file is accidentally included more than once;
--including a header file a second time has no effect. Likewise, if your
--program needs to include multiple header files, the order in which they
--are included doesn't matter.
--
-- *Compatibility Note:* Inclusion of standard header files in any
--order and any number of times works in any ISO C implementation.
--However, this has traditionally not been the case in many older C
--implementations.
--
-- Strictly speaking, you don't *have to* include a header file to use
--a function it declares; you could declare the function explicitly
--yourself, according to the specifications in this manual. But it is
--usually better to include the header file because it may define types
--and macros that are not otherwise available and because it may define
--more efficient macro replacements for some functions. It is also a sure
--way to have the correct declaration.
--
--
--File: libc.info, Node: Macro Definitions, Next: Reserved Names, Prev:
Header Files, Up: Using the Library
--
--Macro Definitions of Functions
--------------------------------
--
-- If we describe something as a function in this manual, it may have a
--macro definition as well. This normally has no effect on how your
--program runs--the macro definition does the same thing as the function
--would. In particular, macro equivalents for library functions evaluate
--arguments exactly once, in the same way that a function call would. The
--main reason for these macro definitions is that sometimes they can
--produce an inline expansion that is considerably faster than an actual
--function call.
--
-- Taking the address of a library function works even if it is also
--defined as a macro. This is because, in this context, the name of the
--function isn't followed by the left parenthesis that is syntactically
--necessary to recognize a macro call.
--
-- You might occasionally want to avoid using the macro definition of a
--function--perhaps to make your program easier to debug. There are two
--ways you can do this:
--
-- * You can avoid a macro definition in a specific use by enclosing
-- the name of the function in parentheses. This works because the
-- name of the function doesn't appear in a syntactic context where
-- it is recognizable as a macro call.
--
-- * You can suppress any macro definition for a whole source file by
-- using the `#undef' preprocessor directive, unless otherwise stated
-- explicitly in the description of that facility.
--
-- For example, suppose the header file `stdlib.h' declares a function
--named `abs' with
--
-- extern int abs (int);
--
--and also provides a macro definition for `abs'. Then, in:
--
-- #include <stdlib.h>
-- int f (int *i) { return (abs (++*i)); }
--
--the reference to `abs' might refer to either a macro or a function. On
--the other hand, in each of the following examples the reference is to a
--function and not a macro.
--
-- #include <stdlib.h>
-- int g (int *i) { return ((abs)(++*i)); }
--
-- #undef abs
-- int h (int *i) { return (abs (++*i)); }
--
-- Since macro definitions that double for a function behave in exactly
--the same way as the actual function version, there is usually no need
--for any of these methods. In fact, removing macro definitions usually
--just makes your program slower.
--
--
--File: libc.info, Node: Reserved Names, Next: Feature Test Macros, Prev:
Macro Definitions, Up: Using the Library
--
--Reserved Names
----------------
--
-- The names of all library types, macros, variables and functions that
--come from the ISO C standard are reserved unconditionally; your program
--*may not* redefine these names. All other library names are reserved
--if your program explicitly includes the header file that defines or
--declares them. There are several reasons for these restrictions:
--
-- * Other people reading your code could get very confused if you were
-- using a function named `exit' to do something completely different
-- from what the standard `exit' function does, for example.
-- Preventing this situation helps to make your programs easier to
-- understand and contributes to modularity and maintainability.
--
-- * It avoids the possibility of a user accidentally redefining a
-- library function that is called by other library functions. If
-- redefinition were allowed, those other functions would not work
-- properly.
--
-- * It allows the compiler to do whatever special optimizations it
-- pleases on calls to these functions, without the possibility that
-- they may have been redefined by the user. Some library
-- facilities, such as those for dealing with variadic arguments
-- (*note Variadic Functions::.) and non-local exits (*note Non-Local
-- Exits::.), actually require a considerable amount of cooperation
-- on the part of the C compiler, and implementationally it might be
-- easier for the compiler to treat these as built-in parts of the
-- language.
--
-- In addition to the names documented in this manual, reserved names
--include all external identifiers (global functions and variables) that
--begin with an underscore (`_') and all identifiers regardless of use
--that begin with either two underscores or an underscore followed by a
--capital letter are reserved names. This is so that the library and
--header files can define functions, variables, and macros for internal
--purposes without risk of conflict with names in user programs.
--
-- Some additional classes of identifier names are reserved for future
--extensions to the C language or the POSIX.1 environment. While using
--these names for your own purposes right now might not cause a problem,
--they do raise the possibility of conflict with future versions of the C
--or POSIX standards, so you should avoid these names.
--
-- * Names beginning with a capital `E' followed a digit or uppercase
-- letter may be used for additional error code names. *Note Error
-- Reporting::.
--
-- * Names that begin with either `is' or `to' followed by a lowercase
-- letter may be used for additional character testing and conversion
-- functions. *Note Character Handling::.
--
-- * Names that begin with `LC_' followed by an uppercase letter may be
-- used for additional macros specifying locale attributes. *Note
-- Locales::.
--
-- * Names of all existing mathematics functions (*note Mathematics::.)
-- suffixed with `f' or `l' are reserved for corresponding functions
-- that operate on `float' and `long double' arguments, respectively.
--
-- * Names that begin with `SIG' followed by an uppercase letter are
-- reserved for additional signal names. *Note Standard Signals::.
--
-- * Names that begin with `SIG_' followed by an uppercase letter are
-- reserved for additional signal actions. *Note Basic Signal
-- Handling::.
--
-- * Names beginning with `str', `mem', or `wcs' followed by a
-- lowercase letter are reserved for additional string and array
-- functions. *Note String and Array Utilities::.
--
-- * Names that end with `_t' are reserved for additional type names.
--
-- In addition, some individual header files reserve names beyond those
--that they actually define. You only need to worry about these
--restrictions if your program includes that particular header file.
--
-- * The header file `dirent.h' reserves names prefixed with `d_'.
--
-- * The header file `fcntl.h' reserves names prefixed with `l_', `F_',
-- `O_', and `S_'.
--
-- * The header file `grp.h' reserves names prefixed with `gr_'.
--
-- * The header file `limits.h' reserves names suffixed with `_MAX'.
--
-- * The header file `pwd.h' reserves names prefixed with `pw_'.
--
-- * The header file `signal.h' reserves names prefixed with `sa_' and
-- `SA_'.
--
-- * The header file `sys/stat.h' reserves names prefixed with `st_'
-- and `S_'.
--
-- * The header file `sys/times.h' reserves names prefixed with `tms_'.
--
-- * The header file `termios.h' reserves names prefixed with `c_',
-- `V', `I', `O', and `TC'; and names prefixed with `B' followed by a
-- digit.
--
--
--File: libc.info, Node: Feature Test Macros, Prev: Reserved Names, Up:
Using the Library
--
--Feature Test Macros
---------------------
--
-- The exact set of features available when you compile a source file
--is controlled by which "feature test macros" you define.
--
-- If you compile your programs using `gcc -ansi', you get only the
--ISO C library features, unless you explicitly request additional
--features by defining one or more of the feature macros. *Note GNU CC
--Command Options: (gcc.info)Invoking GCC, for more information about GCC
--options.
--
-- You should define these macros by using `#define' preprocessor
--directives at the top of your source code files. These directives
--*must* come before any `#include' of a system header file. It is best
--to make them the very first thing in the file, preceded only by
--comments. You could also use the `-D' option to GCC, but it's better
--if you make the source files indicate their own meaning in a
--self-contained way.
--
-- - Macro: _POSIX_SOURCE
-- If you define this macro, then the functionality from the POSIX.1
-- standard (IEEE Standard 1003.1) is available, as well as all of the
-- ISO C facilities.
--
-- - Macro: _POSIX_C_SOURCE
-- If you define this macro with a value of `1', then the
-- functionality from the POSIX.1 standard (IEEE Standard 1003.1) is
-- made available. If you define this macro with a value of `2',
-- then both the functionality from the POSIX.1 standard and the
-- functionality from the POSIX.2 standard (IEEE Standard 1003.2) are
-- made available. This is in addition to the ISO C facilities.
--
-- - Macro: _BSD_SOURCE
-- If you define this macro, functionality derived from 4.3 BSD Unix
-- is included as well as the ISO C, POSIX.1, and POSIX.2 material.
--
-- Some of the features derived from 4.3 BSD Unix conflict with the
-- corresponding features specified by the POSIX.1 standard. If this
-- macro is defined, the 4.3 BSD definitions take precedence over the
-- POSIX definitions.
--
-- Due to the nature of some of the conflicts between 4.3 BSD and
-- POSIX.1, you need to use a special "BSD compatibility library"
-- when linking programs compiled for BSD compatibility. This is
-- because some functions must be defined in two different ways, one
-- of them in the normal C library, and one of them in the
-- compatibility library. If your program defines `_BSD_SOURCE', you
-- must give the option `-lbsd-compat' to the compiler or linker when
-- linking the program, to tell it to find functions in this special
-- compatibility library before looking for them in the normal C
-- library.
--
-- - Macro: _SVID_SOURCE
-- If you define this macro, functionality derived from SVID is
-- included as well as the ISO C, POSIX.1, POSIX.2, and X/Open
-- material.
--
-- - Macro: _XOPEN_SOURCE
-- If you define this macro, functionality described in the X/Open
-- Portability Guide is included. This is a superset of the POSIX.1
-- and POSIX.2 functionality and in fact `_POSIX_SOURCE' and
-- `_POSIX_C_SOURCE' are automatically defined.
--
-- As the unification of all Unices, functionality only available in
-- BSD and SVID is also included.
--
-- If the macro `_XOPEN_SOURCE_EXTENDED' is also defined, even more
-- functionality is available. The extra functions will make all
-- functions available which are necessary for the X/Open Unix brand.
--
-- - Macro: _GNU_SOURCE
-- If you define this macro, everything is included: ISO C, POSIX.1,
-- POSIX.2, BSD, SVID, X/Open, and GNU extensions. In the cases where
-- POSIX.1 conflicts with BSD, the POSIX definitions take precedence.
--
-- If you want to get the full effect of `_GNU_SOURCE' but make the
-- BSD definitions take precedence over the POSIX definitions, use
-- this sequence of definitions:
--
-- #define _GNU_SOURCE
-- #define _BSD_SOURCE
-- #define _SVID_SOURCE
--
-- Note that if you do this, you must link your program with the BSD
-- compatibility library by passing the `-lbsd-compat' option to the
-- compiler or linker. *Note:* If you forget to do this, you may get
-- very strange errors at run time.
--
-- - Macro: _REENTRANT
-- - Macro: _THREAD_SAFE
-- If you define one of these macros, reentrant versions of several
-- functions get declared. Some of the functions are specified in
-- POSIX.1c but many others are only available on a few other systems
-- or are unique to GNU libc. The problem is that the
-- standardization of the thread safe C library interface still is
-- behind.
--
-- Unlike on some other systems no special version of the C library
-- must be used for linking. There is only one version but while
-- compiling this it must have been specified to compile as thread
-- safe.
--
-- We recommend you use `_GNU_SOURCE' in new programs. If you don't
--specify the `-ansi' option to GCC and don't define any of these macros
--explicitly, the effect is the same as defining `_POSIX_C_SOURCE' to 2
--and `_POSIX_SOURCE', `_SVID_SOURCE', and `_BSD_SOURCE' to 1.
--
-- When you define a feature test macro to request a larger class of
--features, it is harmless to define in addition a feature test macro for
--a subset of those features. For example, if you define
--`_POSIX_C_SOURCE', then defining `_POSIX_SOURCE' as well has no effect.
--Likewise, if you define `_GNU_SOURCE', then defining either
--`_POSIX_SOURCE' or `_POSIX_C_SOURCE' or `_SVID_SOURCE' as well has no
--effect.
--
-- Note, however, that the features of `_BSD_SOURCE' are not a subset of
--any of the other feature test macros supported. This is because it
--defines BSD features that take precedence over the POSIX features that
--are requested by the other macros. For this reason, defining
--`_BSD_SOURCE' in addition to the other feature test macros does have an
--effect: it causes the BSD features to take priority over the conflicting
--POSIX features.
--
--
--File: libc.info, Node: Roadmap to the Manual, Prev: Using the Library, Up:
Introduction
--
--Roadmap to the Manual
--=====================
--
-- Here is an overview of the contents of the remaining chapters of
--this manual.
--
-- * *Note Error Reporting::, describes how errors detected by the
-- library are reported.
--
-- * *Note Language Features::, contains information about library
-- support for standard parts of the C language, including things
-- like the `sizeof' operator and the symbolic constant `NULL', how
-- to write functions accepting variable numbers of arguments, and
-- constants describing the ranges and other properties of the
-- numerical types. There is also a simple debugging mechanism which
-- allows you to put assertions in your code, and have diagnostic
-- messages printed if the tests fail.
--
-- * *Note Memory Allocation::, describes the GNU library's facilities
-- for dynamic allocation of storage. If you do not know in advance
-- how much storage your program needs, you can allocate it
-- dynamically instead, and manipulate it via pointers.
--
-- * *Note Character Handling::, contains information about character
-- classification functions (such as `isspace') and functions for
-- performing case conversion.
--
-- * *Note String and Array Utilities::, has descriptions of functions
-- for manipulating strings (null-terminated character arrays) and
-- general byte arrays, including operations such as copying and
-- comparison.
--
-- * *Note I/O Overview::, gives an overall look at the input and output
-- facilities in the library, and contains information about basic
-- concepts such as file names.
--
-- * *Note I/O on Streams::, describes I/O operations involving streams
-- (or `FILE *' objects). These are the normal C library functions
-- from `stdio.h'.
--
-- * *Note Low-Level I/O::, contains information about I/O operations
-- on file descriptors. File descriptors are a lower-level mechanism
-- specific to the Unix family of operating systems.
--
-- * *Note File System Interface::, has descriptions of operations on
-- entire files, such as functions for deleting and renaming them and
-- for creating new directories. This chapter also contains
-- information about how you can access the attributes of a file,
-- such as its owner and file protection modes.
--
-- * *Note Pipes and FIFOs::, contains information about simple
-- interprocess communication mechanisms. Pipes allow communication
-- between two related processes (such as between a parent and
-- child), while FIFOs allow communication between processes sharing
-- a common file system on the same machine.
--
-- * *Note Sockets::, describes a more complicated interprocess
-- communication mechanism that allows processes running on different
-- machines to communicate over a network. This chapter also
-- contains information about Internet host addressing and how to use
-- the system network databases.
--
-- * *Note Low-Level Terminal Interface::, describes how you can change
-- the attributes of a terminal device. If you want to disable echo
-- of characters typed by the user, for example, read this chapter.
--
-- * *Note Mathematics::, contains information about the math library
-- functions. These include things like random-number generators and
-- remainder functions on integers as well as the usual trigonometric
-- and exponential functions on floating-point numbers.
--
-- * *Note Low-Level Arithmetic Functions: Arithmetic, describes
-- functions for simple arithmetic, analysis of floating-point
-- values, and reading numbers from strings.
--
-- * *Note Searching and Sorting::, contains information about functions
-- for searching and sorting arrays. You can use these functions on
-- any kind of array by providing an appropriate comparison function.
--
-- * *Note Pattern Matching::, presents functions for matching regular
-- expressions and shell file name patterns, and for expanding words
-- as the shell does.
--
-- * *Note Date and Time::, describes functions for measuring both
-- calendar time and CPU time, as well as functions for setting
-- alarms and timers.
--
-- * *Note Extended Characters::, contains information about
-- manipulating characters and strings using character sets larger
-- than will fit in the usual `char' data type.
--
-- * *Note Locales::, describes how selecting a particular country or
-- language affects the behavior of the library. For example, the
-- locale affects collation sequences for strings and how monetary
-- values are formatted.
--
-- * *Note Non-Local Exits::, contains descriptions of the `setjmp' and
-- `longjmp' functions. These functions provide a facility for
-- `goto'-like jumps which can jump from one function to another.
--
-- * *Note Signal Handling::, tells you all about signals--what they
-- are, how to establish a handler that is called when a particular
-- kind of signal is delivered, and how to prevent signals from
-- arriving during critical sections of your program.
--
-- * *Note Process Startup::, tells how your programs can access their
-- command-line arguments and environment variables.
--
-- * *Note Processes::, contains information about how to start new
-- processes and run programs.
--
-- * *Note Job Control::, describes functions for manipulating process
-- groups and the controlling terminal. This material is probably
-- only of interest if you are writing a shell or other program which
-- handles job control specially.
--
-- * *Note Name Service Switch::, describes the services which are
-- available for looking up names in the system databases, how to
-- determine which service is used for which database, and how these
-- services are implemented so that contributors can design their own
-- services.
--
-- * *Note User Database::, and *Note Group Database::, tell you how to
-- access the system user and group databases.
--
-- * *Note System Information::, describes functions for getting
-- information about the hardware and software configuration your
-- program is executing under.
--
-- * *Note System Configuration::, tells you how you can get
-- information about various operating system limits. Most of these
-- parameters are provided for compatibility with POSIX.
--
-- * *Note Library Summary::, gives a summary of all the functions,
-- variables, and macros in the library, with complete data types and
-- function prototypes, and says what standard or system each is
-- derived from.
--
-- * *Note Maintenance::, explains how to build and install the GNU C
-- library on your system, how to report any bugs you might find, and
-- how to add new functions or port the library to a new system.
--
-- If you already know the name of the facility you are interested in,
--you can look it up in *Note Library Summary::. This gives you a
--summary of its syntax and a pointer to where you can find a more
--detailed description. This appendix is particularly useful if you just
--want to verify the order and type of arguments to a function, for
--example. It also tells you what standard or system each function,
--variable, or macro is derived from.
--
--
--File: libc.info, Node: Error Reporting, Next: Memory Allocation, Prev:
Introduction, Up: Top
--
--Error Reporting
--***************
--
-- Many functions in the GNU C library detect and report error
--conditions, and sometimes your programs need to check for these error
--conditions. For example, when you open an input file, you should
--verify that the file was actually opened correctly, and print an error
--message or take other appropriate action if the call to the library
--function failed.
--
-- This chapter describes how the error reporting facility works. Your
--program should include the header file `errno.h' to use this facility.
--
--* Menu:
--
--* Checking for Errors:: How errors are reported by library functions.
--* Error Codes:: Error code macros; all of these expand
-- into integer constant values.
--* Error Messages:: Mapping error codes onto error messages.
--
--
--File: libc.info, Node: Checking for Errors, Next: Error Codes, Up: Error
Reporting
--
--Checking for Errors
--===================
--
-- Most library functions return a special value to indicate that they
--have failed. The special value is typically `-1', a null pointer, or a
--constant such as `EOF' that is defined for that purpose. But this
--return value tells you only that an error has occurred. To find out
--what kind of error it was, you need to look at the error code stored in
--the variable `errno'. This variable is declared in the header file
--`errno.h'.
--
-- - Variable: volatile int errno
-- The variable `errno' contains the system error number. You can
-- change the value of `errno'.
--
-- Since `errno' is declared `volatile', it might be changed
-- asynchronously by a signal handler; see *Note Defining Handlers::.
-- However, a properly written signal handler saves and restores the
-- value of `errno', so you generally do not need to worry about this
-- possibility except when writing signal handlers.
--
-- The initial value of `errno' at program startup is zero. Many
-- library functions are guaranteed to set it to certain nonzero
-- values when they encounter certain kinds of errors. These error
-- conditions are listed for each function. These functions do not
-- change `errno' when they succeed; thus, the value of `errno' after
-- a successful call is not necessarily zero, and you should not use
-- `errno' to determine *whether* a call failed. The proper way to
-- do that is documented for each function. *If* the call the
-- failed, you can examine `errno'.
--
-- Many library functions can set `errno' to a nonzero value as a
-- result of calling other library functions which might fail. You
-- should assume that any library function might alter `errno' when
-- the function returns an error.
--
-- *Portability Note:* ISO C specifies `errno' as a "modifiable
-- lvalue" rather than as a variable, permitting it to be implemented
-- as a macro. For example, its expansion might involve a function
-- call, like `*_errno ()'. In fact, that is what it is on the GNU
-- system itself. The GNU library, on non-GNU systems, does whatever
-- is right for the particular system.
--
-- There are a few library functions, like `sqrt' and `atan', that
-- return a perfectly legitimate value in case of an error, but also
-- set `errno'. For these functions, if you want to check to see
-- whether an error occurred, the recommended method is to set `errno'
-- to zero before calling the function, and then check its value
-- afterward.
--
-- All the error codes have symbolic names; they are macros defined in
--`errno.h'. The names start with `E' and an upper-case letter or digit;
--you should consider names of this form to be reserved names. *Note
--Reserved Names::.
--
-- The error code values are all positive integers and are all distinct,
--with one exception: `EWOULDBLOCK' and `EAGAIN' are the same. Since the
--values are distinct, you can use them as labels in a `switch'
--statement; just don't use both `EWOULDBLOCK' and `EAGAIN'. Your
--program should not make any other assumptions about the specific values
--of these symbolic constants.
--
-- The value of `errno' doesn't necessarily have to correspond to any
--of these macros, since some library functions might return other error
--codes of their own for other situations. The only values that are
--guaranteed to be meaningful for a particular library function are the
--ones that this manual lists for that function.
--
-- On non-GNU systems, almost any system call can return `EFAULT' if it
--is given an invalid pointer as an argument. Since this could only
--happen as a result of a bug in your program, and since it will not
--happen on the GNU system, we have saved space by not mentioning
--`EFAULT' in the descriptions of individual functions.
--
-- In some Unix systems, many system calls can also return `EFAULT' if
--given as an argument a pointer into the stack, and the kernel for some
--obscure reason fails in its attempt to extend the stack. If this ever
--happens, you should probably try using statically or dynamically
--allocated memory instead of stack memory on that system.
--
--
--File: libc.info, Node: Error Codes, Next: Error Messages, Prev: Checking
for Errors, Up: Error Reporting
--
--Error Codes
--===========
--
-- The error code macros are defined in the header file `errno.h'. All
--of them expand into integer constant values. Some of these error codes
--can't occur on the GNU system, but they can occur using the GNU library
--on other systems.
--
-- - Macro: int EPERM
-- Operation not permitted; only the owner of the file (or other
-- resource) or processes with special privileges can perform the
-- operation.
--
-- - Macro: int ENOENT
-- No such file or directory. This is a "file doesn't exist" error
-- for ordinary files that are referenced in contexts where they are
-- expected to already exist.
--
-- - Macro: int ESRCH
-- No process matches the specified process ID.
--
-- - Macro: int EINTR
-- Interrupted function call; an asynchronous signal occurred and
-- prevented completion of the call. When this happens, you should
-- try the call again.
--
-- You can choose to have functions resume after a signal that is
-- handled, rather than failing with `EINTR'; see *Note Interrupted
-- Primitives::.
--
-- - Macro: int EIO
-- Input/output error; usually used for physical read or write errors.
--
-- - Macro: int ENXIO
-- No such device or address. The system tried to use the device
-- represented by a file you specified, and it couldn't find the
-- device. This can mean that the device file was installed
-- incorrectly, or that the physical device is missing or not
-- correctly attached to the computer.
--
-- - Macro: int E2BIG
-- Argument list too long; used when the arguments passed to a new
-- program being executed with one of the `exec' functions (*note
-- Executing a File::.) occupy too much memory space. This condition
-- never arises in the GNU system.
--
-- - Macro: int ENOEXEC
-- Invalid executable file format. This condition is detected by the
-- `exec' functions; see *Note Executing a File::.
--
-- - Macro: int EBADF
-- Bad file descriptor; for example, I/O on a descriptor that has been
-- closed or reading from a descriptor open only for writing (or vice
-- versa).
--
-- - Macro: int ECHILD
-- There are no child processes. This error happens on operations
-- that are supposed to manipulate child processes, when there aren't
-- any processes to manipulate.
--
-- - Macro: int EDEADLK
-- Deadlock avoided; allocating a system resource would have resulted
-- in a deadlock situation. The system does not guarantee that it
-- will notice all such situations. This error means you got lucky
-- and the system noticed; it might just hang. *Note File Locks::,
-- for an example.
--
-- - Macro: int ENOMEM
-- No memory available. The system cannot allocate more virtual
-- memory because its capacity is full.
--
-- - Macro: int EACCES
-- Permission denied; the file permissions do not allow the attempted
-- operation.
--
-- - Macro: int EFAULT
-- Bad address; an invalid pointer was detected. In the GNU system,
-- this error never happens; you get a signal instead.
--
-- - Macro: int ENOTBLK
-- A file that isn't a block special file was given in a situation
-- that requires one. For example, trying to mount an ordinary file
-- as a file system in Unix gives this error.
--
-- - Macro: int EBUSY
-- Resource busy; a system resource that can't be shared is already
-- in use. For example, if you try to delete a file that is the root
-- of a currently mounted filesystem, you get this error.
--
-- - Macro: int EEXIST
-- File exists; an existing file was specified in a context where it
-- only makes sense to specify a new file.
--
-- - Macro: int EXDEV
-- An attempt to make an improper link across file systems was
-- detected. This happens not only when you use `link' (*note Hard
-- Links::.) but also when you rename a file with `rename' (*note
-- Renaming Files::.).
--
-- - Macro: int ENODEV
-- The wrong type of device was given to a function that expects a
-- particular sort of device.
--
-- - Macro: int ENOTDIR
-- A file that isn't a directory was specified when a directory is
-- required.
--
-- - Macro: int EISDIR
-- File is a directory; you cannot open a directory for writing, or
-- create or remove hard links to it.
--
-- - Macro: int EINVAL
-- Invalid argument. This is used to indicate various kinds of
-- problems with passing the wrong argument to a library function.
--
-- - Macro: int EMFILE
-- The current process has too many files open and can't open any
-- more. Duplicate descriptors do count toward this limit.
--
-- In BSD and GNU, the number of open files is controlled by a
-- resource limit that can usually be increased. If you get this
-- error, you might want to increase the `RLIMIT_NOFILE' limit or
-- make it unlimited; *note Limits on Resources::..
--
-- - Macro: int ENFILE
-- There are too many distinct file openings in the entire system.
-- Note that any number of linked channels count as just one file
-- opening; see *Note Linked Channels::. This error never occurs in
-- the GNU system.
--
-- - Macro: int ENOTTY
-- Inappropriate I/O control operation, such as trying to set terminal
-- modes on an ordinary file.
--
-- - Macro: int ETXTBSY
-- An attempt to execute a file that is currently open for writing, or
-- write to a file that is currently being executed. Often using a
-- debugger to run a program is considered having it open for writing
-- and will cause this error. (The name stands for "text file
-- busy".) This is not an error in the GNU system; the text is
-- copied as necessary.
--
-- - Macro: int EFBIG
-- File too big; the size of a file would be larger than allowed by
-- the system.
--
-- - Macro: int ENOSPC
-- No space left on device; write operation on a file failed because
-- the disk is full.
--
-- - Macro: int ESPIPE
-- Invalid seek operation (such as on a pipe).
--
-- - Macro: int EROFS
-- An attempt was made to modify something on a read-only file system.
--
-- - Macro: int EMLINK
-- Too many links; the link count of a single file would become too
-- large. `rename' can cause this error if the file being renamed
-- already has as many links as it can take (*note Renaming Files::.).
--
-- - Macro: int EPIPE
-- Broken pipe; there is no process reading from the other end of a
-- pipe. Every library function that returns this error code also
-- generates a `SIGPIPE' signal; this signal terminates the program
-- if not handled or blocked. Thus, your program will never actually
-- see `EPIPE' unless it has handled or blocked `SIGPIPE'.
--
-- - Macro: int EDOM
-- Domain error; used by mathematical functions when an argument
-- value does not fall into the domain over which the function is
-- defined.
--
-- - Macro: int ERANGE
-- Range error; used by mathematical functions when the result value
-- is not representable because of overflow or underflow.
--
-- - Macro: int EAGAIN
-- Resource temporarily unavailable; the call might work if you try
-- again later. The macro `EWOULDBLOCK' is another name for `EAGAIN';
-- they are always the same in the GNU C library.
--
-- This error can happen in a few different situations:
--
-- * An operation that would block was attempted on an object that
-- has non-blocking mode selected. Trying the same operation
-- again will block until some external condition makes it
-- possible to read, write, or connect (whatever the operation).
-- You can use `select' to find out when the operation will be
-- possible; *note Waiting for I/O::..
--
-- *Portability Note:* In older Unix many systems, this condition
-- was indicated by `EWOULDBLOCK', which was a distinct error
-- code different from `EAGAIN'. To make your program portable,
-- you should check for both codes and treat them the same.
--
-- * A temporary resource shortage made an operation impossible.
-- `fork' can return this error. It indicates that the shortage
-- is expected to pass, so your program can try the call again
-- later and it may succeed. It is probably a good idea to
-- delay for a few seconds before trying it again, to allow time
-- for other processes to release scarce resources. Such
-- shortages are usually fairly serious and affect the whole
-- system, so usually an interactive program should report the
-- error to the user and return to its command loop.
--
-- - Macro: int EWOULDBLOCK
-- In the GNU C library, this is another name for `EAGAIN' (above).
-- The values are always the same, on every operating system.
--
-- C libraries in many older Unix systems have `EWOULDBLOCK' as a
-- separate error code.
--
-- - Macro: int EINPROGRESS
-- An operation that cannot complete immediately was initiated on an
-- object that has non-blocking mode selected. Some functions that
-- must always block (such as `connect'; *note Connecting::.) never
-- return `EAGAIN'. Instead, they return `EINPROGRESS' to indicate
-- that the operation has begun and will take some time. Attempts to
-- manipulate the object before the call completes return `EALREADY'.
-- You can use the `select' function to find out when the pending
-- operation has completed; *note Waiting for I/O::..
--
-- - Macro: int EALREADY
-- An operation is already in progress on an object that has
-- non-blocking mode selected.
--
-- - Macro: int ENOTSOCK
-- A file that isn't a socket was specified when a socket is required.
--
-- - Macro: int EMSGSIZE
-- The size of a message sent on a socket was larger than the
-- supported maximum size.
--
-- - Macro: int EPROTOTYPE
-- The socket type does not support the requested communications
-- protocol.
--
-- - Macro: int ENOPROTOOPT
-- You specified a socket option that doesn't make sense for the
-- particular protocol being used by the socket. *Note Socket
-- Options::.
--
-- - Macro: int EPROTONOSUPPORT
-- The socket domain does not support the requested communications
-- protocol (perhaps because the requested protocol is completely
-- invalid.) *Note Creating a Socket::.
--
-- - Macro: int ESOCKTNOSUPPORT
-- The socket type is not supported.
--
-- - Macro: int EOPNOTSUPP
-- The operation you requested is not supported. Some socket
-- functions don't make sense for all types of sockets, and others
-- may not be implemented for all communications protocols. In the
-- GNU system, this error can happen for many calls when the object
-- does not support the particular operation; it is a generic
-- indication that the server knows nothing to do for that call.
--
-- - Macro: int EPFNOSUPPORT
-- The socket communications protocol family you requested is not
-- supported.
--
-- - Macro: int EAFNOSUPPORT
-- The address family specified for a socket is not supported; it is
-- inconsistent with the protocol being used on the socket. *Note
-- Sockets::.
--
-- - Macro: int EADDRINUSE
-- The requested socket address is already in use. *Note Socket
-- Addresses::.
--
-- - Macro: int EADDRNOTAVAIL
-- The requested socket address is not available; for example, you
-- tried to give a socket a name that doesn't match the local host
-- name. *Note Socket Addresses::.
--
-- - Macro: int ENETDOWN
-- A socket operation failed because the network was down.
--
-- - Macro: int ENETUNREACH
-- A socket operation failed because the subnet containing the remote
-- host was unreachable.
--
-- - Macro: int ENETRESET
-- A network connection was reset because the remote host crashed.
--
-- - Macro: int ECONNABORTED
-- A network connection was aborted locally.
--
-- - Macro: int ECONNRESET
-- A network connection was closed for reasons outside the control of
-- the local host, such as by the remote machine rebooting or an
-- unrecoverable protocol violation.
--
-- - Macro: int ENOBUFS
-- The kernel's buffers for I/O operations are all in use. In GNU,
-- this error is always synonymous with `ENOMEM'; you may get one or
-- the other from network operations.
--
-- - Macro: int EISCONN
-- You tried to connect a socket that is already connected. *Note
-- Connecting::.
--
-- - Macro: int ENOTCONN
-- The socket is not connected to anything. You get this error when
-- you try to transmit data over a socket, without first specifying a
-- destination for the data. For a connectionless socket (for
-- datagram protocols, such as UDP), you get `EDESTADDRREQ' instead.
--
-- - Macro: int EDESTADDRREQ
-- No default destination address was set for the socket. You get
-- this error when you try to transmit data over a connectionless
-- socket, without first specifying a destination for the data with
-- `connect'.
--
-- - Macro: int ESHUTDOWN
-- The socket has already been shut down.
--
-- - Macro: int ETOOMANYREFS
-- ???
--
-- - Macro: int ETIMEDOUT
-- A socket operation with a specified timeout received no response
-- during the timeout period.
--
-- - Macro: int ECONNREFUSED
-- A remote host refused to allow the network connection (typically
-- because it is not running the requested service).
--
-- - Macro: int ELOOP
-- Too many levels of symbolic links were encountered in looking up a
-- file name. This often indicates a cycle of symbolic links.
--
-- - Macro: int ENAMETOOLONG
-- Filename too long (longer than `PATH_MAX'; *note Limits for
-- Files::.) or host name too long (in `gethostname' or
-- `sethostname'; *note Host Identification::.).
--
-- - Macro: int EHOSTDOWN
-- The remote host for a requested network connection is down.
--
-- - Macro: int EHOSTUNREACH
-- The remote host for a requested network connection is not
-- reachable.
--
-- - Macro: int ENOTEMPTY
-- Directory not empty, where an empty directory was expected.
-- Typically, this error occurs when you are trying to delete a
-- directory.
--
-- - Macro: int EPROCLIM
-- This means that the per-user limit on new process would be
-- exceeded by an attempted `fork'. *Note Limits on Resources::, for
-- details on the `RLIMIT_NPROC' limit.
--
-- - Macro: int EUSERS
-- The file quota system is confused because there are too many users.
--
-- - Macro: int EDQUOT
-- The user's disk quota was exceeded.
--
-- - Macro: int ESTALE
-- Stale NFS file handle. This indicates an internal confusion in
-- the NFS system which is due to file system rearrangements on the
-- server host. Repairing this condition usually requires unmounting
-- and remounting the NFS file system on the local host.
--
-- - Macro: int EREMOTE
-- An attempt was made to NFS-mount a remote file system with a file
-- name that already specifies an NFS-mounted file. (This is an
-- error on some operating systems, but we expect it to work properly
-- on the GNU system, making this error code impossible.)
--
-- - Macro: int EBADRPC
-- ???
--
-- - Macro: int ERPCMISMATCH
-- ???
--
-- - Macro: int EPROGUNAVAIL
-- ???
--
-- - Macro: int EPROGMISMATCH
-- ???
--
-- - Macro: int EPROCUNAVAIL
-- ???
--
-- - Macro: int ENOLCK
-- No locks available. This is used by the file locking facilities;
-- see *Note File Locks::. This error is never generated by the GNU
-- system, but it can result from an operation to an NFS server
-- running another operating system.
--
-- - Macro: int EFTYPE
-- Inappropriate file type or format. The file was the wrong type
-- for the operation, or a data file had the wrong format.
--
-- On some systems `chmod' returns this error if you try to set the
-- sticky bit on a non-directory file; *note Setting Permissions::..
--
-- - Macro: int EAUTH
-- ???
--
-- - Macro: int ENEEDAUTH
-- ???
--
-- - Macro: int ENOSYS
-- Function not implemented. Some functions have commands or options
-- defined that might not be supported in all implementations, and
-- this is the kind of error you get if you request them and they are
-- not supported.
--
-- - Macro: int EILSEQ
-- While decoding a multibyte character the function came along an
-- invalid or an incomplete sequence of bytes or the given wide
-- character is invalid.
--
-- - Macro: int EBACKGROUND
-- In the GNU system, servers supporting the `term' protocol return
-- this error for certain operations when the caller is not in the
-- foreground process group of the terminal. Users do not usually
-- see this error because functions such as `read' and `write'
-- translate it into a `SIGTTIN' or `SIGTTOU' signal. *Note Job
-- Control::, for information on process groups and these signals.
--
-- - Macro: int EDIED
-- In the GNU system, opening a file returns this error when the file
-- is translated by a program and the translator program dies while
-- starting up, before it has connected to the file.
--
-- - Macro: int ED
-- The experienced user will know what is wrong.
--
-- - Macro: int EGREGIOUS
-- You did *what*?
--
-- - Macro: int EIEIO
-- Go home and have a glass of warm, dairy-fresh milk.
--
-- - Macro: int EGRATUITOUS
-- This error code has no purpose.
--
-- - Macro: int EBADMSG
--
-- - Macro: int EIDRM
--
-- - Macro: int EMULTIHOP
--
-- - Macro: int ENODATA
--
-- - Macro: int ENOLINK
--
-- - Macro: int ENOMSG
--
-- - Macro: int ENOSR
--
-- - Macro: int ENOSTR
--
-- - Macro: int EOVERFLOW
--
-- - Macro: int EPROTO
--
-- - Macro: int ETIME
--
-- *The following error codes are defined by the Linux/i386 kernel.
--They are not yet documented.*
--
-- - Macro: int ERESTART
--
-- - Macro: int ECHRNG
--
-- - Macro: int EL2NSYNC
--
-- - Macro: int EL3HLT
--
-- - Macro: int EL3RST
--
-- - Macro: int ELNRNG
--
-- - Macro: int EUNATCH
--
-- - Macro: int ENOCSI
--
-- - Macro: int EL2HLT
--
-- - Macro: int EBADE
--
-- - Macro: int EBADR
--
-- - Macro: int EXFULL
--
-- - Macro: int ENOANO
--
-- - Macro: int EBADRQC
--
-- - Macro: int EBADSLT
--
-- - Macro: int EDEADLOCK
--
-- - Macro: int EBFONT
--
-- - Macro: int ENONET
--
-- - Macro: int ENOPKG
--
-- - Macro: int EADV
--
-- - Macro: int ESRMNT
--
-- - Macro: int ECOMM
--
-- - Macro: int EDOTDOT
--
-- - Macro: int ENOTUNIQ
--
-- - Macro: int EBADFD
--
-- - Macro: int EREMCHG
--
-- - Macro: int ELIBACC
--
-- - Macro: int ELIBBAD
--
-- - Macro: int ELIBSCN
--
-- - Macro: int ELIBMAX
--
-- - Macro: int ELIBEXEC
--
-- - Macro: int ESTRPIPE
--
-- - Macro: int EUCLEAN
--
-- - Macro: int ENOTNAM
--
-- - Macro: int ENAVAIL
--
-- - Macro: int EISNAM
--
-- - Macro: int EREMOTEIO
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-20
glibc-2.0.1/manual/libc.info-20
---- ../glibc-2.0.1/manual/libc.info-20 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-20 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1220 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Standard Signals, Next: Signal Actions, Prev:
Concepts of Signals, Up: Signal Handling
--
--Standard Signals
--================
--
-- This section lists the names for various standard kinds of signals
--and describes what kind of event they mean. Each signal name is a macro
--which stands for a positive integer--the "signal number" for that kind
--of signal. Your programs should never make assumptions about the
--numeric code for a particular kind of signal, but rather refer to them
--always by the names defined here. This is because the number for a
--given kind of signal can vary from system to system, but the meanings of
--the names are standardized and fairly uniform.
--
-- The signal names are defined in the header file `signal.h'.
--
-- - Macro: int NSIG
-- The value of this symbolic constant is the total number of signals
-- defined. Since the signal numbers are allocated consecutively,
-- `NSIG' is also one greater than the largest defined signal number.
--
--* Menu:
--
--* Program Error Signals:: Used to report serious program errors.
--* Termination Signals:: Used to interrupt and/or terminate the
-- program.
--* Alarm Signals:: Used to indicate expiration of timers.
--* Asynchronous I/O Signals:: Used to indicate input is available.
--* Job Control Signals:: Signals used to support job control.
--* Operation Error Signals:: Used to report operational system errors.
--* Miscellaneous Signals:: Miscellaneous Signals.
--* Signal Messages:: Printing a message describing a signal.
--
--
--File: libc.info, Node: Program Error Signals, Next: Termination Signals,
Up: Standard Signals
--
--Program Error Signals
-----------------------
--
-- The following signals are generated when a serious program error is
--detected by the operating system or the computer itself. In general,
--all of these signals are indications that your program is seriously
--broken in some way, and there's usually no way to continue the
--computation which encountered the error.
--
-- Some programs handle program error signals in order to tidy up before
--terminating; for example, programs that turn off echoing of terminal
--input should handle program error signals in order to turn echoing back
--on. The handler should end by specifying the default action for the
--signal that happened and then reraising it; this will cause the program
--to terminate with that signal, as if it had not had a handler. (*Note
--Termination in Handler::.)
--
-- Termination is the sensible ultimate outcome from a program error in
--most programs. However, programming systems such as Lisp that can load
--compiled user programs might need to keep executing even if a user
--program incurs an error. These programs have handlers which use
--`longjmp' to return control to the command level.
--
-- The default action for all of these signals is to cause the process
--to terminate. If you block or ignore these signals or establish
--handlers for them that return normally, your program will probably
--break horribly when such signals happen, unless they are generated by
--`raise' or `kill' instead of a real error.
--
-- When one of these program error signals terminates a process, it also
--writes a "core dump file" which records the state of the process at the
--time of termination. The core dump file is named `core' and is written
--in whichever directory is current in the process at the time. (On the
--GNU system, you can specify the file name for core dumps with the
--environment variable `COREFILE'.) The purpose of core dump files is so
--that you can examine them with a debugger to investigate what caused
--the error.
--
-- - Macro: int SIGFPE
-- The `SIGFPE' signal reports a fatal arithmetic error. Although the
-- name is derived from "floating-point exception", this signal
-- actually covers all arithmetic errors, including division by zero
-- and overflow. If a program stores integer data in a location
-- which is then used in a floating-point operation, this often
-- causes an "invalid operation" exception, because the processor
-- cannot recognize the data as a floating-point number.
--
-- Actual floating-point exceptions are a complicated subject because
-- there are many types of exceptions with subtly different meanings,
-- and the `SIGFPE' signal doesn't distinguish between them. The
-- `IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std
-- 754-1985 and ANSI/IEEE Std 854-1987)' defines various
-- floating-point exceptions and requires conforming computer systems
-- to report their occurrences. However, this standard does not
-- specify how the exceptions are reported, or what kinds of handling
-- and control the operating system can offer to the programmer.
--
-- BSD systems provide the `SIGFPE' handler with an extra argument that
--distinguishes various causes of the exception. In order to access this
--argument, you must define the handler to accept two arguments, which
--means you must cast it to a one-argument function type in order to
--establish the handler. The GNU library does provide this extra
--argument, but the value is meaningful only on operating systems that
--provide the information (BSD systems and GNU systems).
--
--`FPE_INTOVF_TRAP'
-- Integer overflow (impossible in a C program unless you enable
-- overflow trapping in a hardware-specific fashion).
--
--`FPE_INTDIV_TRAP'
-- Integer division by zero.
--
--`FPE_SUBRNG_TRAP'
-- Subscript-range (something that C programs never check for).
--
--`FPE_FLTOVF_TRAP'
-- Floating overflow trap.
--
--`FPE_FLTDIV_TRAP'
-- Floating/decimal division by zero.
--
--`FPE_FLTUND_TRAP'
-- Floating underflow trap. (Trapping on floating underflow is not
-- normally enabled.)
--
--`FPE_DECOVF_TRAP'
-- Decimal overflow trap. (Only a few machines have decimal
-- arithmetic and C never uses it.)
--
-- - Macro: int SIGILL
-- The name of this signal is derived from "illegal instruction"; it
-- usually means your program is trying to execute garbage or a
-- privileged instruction. Since the C compiler generates only valid
-- instructions, `SIGILL' typically indicates that the executable
-- file is corrupted, or that you are trying to execute data. Some
-- common ways of getting into the latter situation are by passing an
-- invalid object where a pointer to a function was expected, or by
-- writing past the end of an automatic array (or similar problems
-- with pointers to automatic variables) and corrupting other data on
-- the stack such as the return address of a stack frame.
--
-- `SIGILL' can also be generated when the stack overflows, or when
-- the system has trouble running the handler for a signal.
--
-- - Macro: int SIGSEGV
-- This signal is generated when a program tries to read or write
-- outside the memory that is allocated for it, or to write memory
-- that can only be read. (Actually, the signals only occur when the
-- program goes far enough outside to be detected by the system's
-- memory protection mechanism.) The name is an abbreviation for
-- "segmentation violation".
--
-- Common ways of getting a `SIGSEGV' condition include dereferencing
-- a null or uninitialized pointer, or when you use a pointer to step
-- through an array, but fail to check for the end of the array. It
-- varies among systems whether dereferencing a null pointer generates
-- `SIGSEGV' or `SIGBUS'.
--
-- - Macro: int SIGBUS
-- This signal is generated when an invalid pointer is dereferenced.
-- Like `SIGSEGV', this signal is typically the result of
-- dereferencing an uninitialized pointer. The difference between
-- the two is that `SIGSEGV' indicates an invalid access to valid
-- memory, while `SIGBUS' indicates an access to an invalid address.
-- In particular, `SIGBUS' signals often result from dereferencing a
-- misaligned pointer, such as referring to a four-word integer at an
-- address not divisible by four. (Each kind of computer has its own
-- requirements for address alignment.)
--
-- The name of this signal is an abbreviation for "bus error".
--
-- - Macro: int SIGABRT
-- This signal indicates an error detected by the program itself and
-- reported by calling `abort'. *Note Aborting a Program::.
--
-- - Macro: int SIGIOT
-- Generated by the PDP-11 "iot" instruction. On most machines, this
-- is just another name for `SIGABRT'.
--
-- - Macro: int SIGTRAP
-- Generated by the machine's breakpoint instruction, and possibly
-- other trap instructions. This signal is used by debuggers. Your
-- program will probably only see `SIGTRAP' if it is somehow
-- executing bad instructions.
--
-- - Macro: int SIGEMT
-- Emulator trap; this results from certain unimplemented instructions
-- which might be emulated in software, or the operating system's
-- failure to properly emulate them.
--
-- - Macro: int SIGSYS
-- Bad system call; that is to say, the instruction to trap to the
-- operating system was executed, but the code number for the system
-- call to perform was invalid.
--
--
--File: libc.info, Node: Termination Signals, Next: Alarm Signals, Prev:
Program Error Signals, Up: Standard Signals
--
--Termination Signals
---------------------
--
-- These signals are all used to tell a process to terminate, in one way
--or another. They have different names because they're used for slightly
--different purposes, and programs might want to handle them differently.
--
-- The reason for handling these signals is usually so your program can
--tidy up as appropriate before actually terminating. For example, you
--might want to save state information, delete temporary files, or restore
--the previous terminal modes. Such a handler should end by specifying
--the default action for the signal that happened and then reraising it;
--this will cause the program to terminate with that signal, as if it had
--not had a handler. (*Note Termination in Handler::.)
--
-- The (obvious) default action for all of these signals is to cause the
--process to terminate.
--
-- - Macro: int SIGTERM
-- The `SIGTERM' signal is a generic signal used to cause program
-- termination. Unlike `SIGKILL', this signal can be blocked,
-- handled, and ignored. It is the normal way to politely ask a
-- program to terminate.
--
-- The shell command `kill' generates `SIGTERM' by default.
--
-- - Macro: int SIGINT
-- The `SIGINT' ("program interrupt") signal is sent when the user
-- types the INTR character (normally `C-c'). *Note Special
-- Characters::, for information about terminal driver support for
-- `C-c'.
--
-- - Macro: int SIGQUIT
-- The `SIGQUIT' signal is similar to `SIGINT', except that it's
-- controlled by a different key--the QUIT character, usually
-- `C-\'--and produces a core dump when it terminates the process,
-- just like a program error signal. You can think of this as a
-- program error condition "detected" by the user.
--
-- *Note Program Error Signals::, for information about core dumps.
-- *Note Special Characters::, for information about terminal driver
-- support.
--
-- Certain kinds of cleanups are best omitted in handling `SIGQUIT'.
-- For example, if the program creates temporary files, it should
-- handle the other termination requests by deleting the temporary
-- files. But it is better for `SIGQUIT' not to delete them, so that
-- the user can examine them in conjunction with the core dump.
--
-- - Macro: int SIGKILL
-- The `SIGKILL' signal is used to cause immediate program
-- termination. It cannot be handled or ignored, and is therefore
-- always fatal. It is also not possible to block this signal.
--
-- This signal is usually generated only by explicit request. Since
-- it cannot be handled, you should generate it only as a last
-- resort, after first trying a less drastic method such as `C-c' or
-- `SIGTERM'. If a process does not respond to any other termination
-- signals, sending it a `SIGKILL' signal will almost always cause it
-- to go away.
--
-- In fact, if `SIGKILL' fails to terminate a process, that by itself
-- constitutes an operating system bug which you should report.
--
-- The system will generate `SIGKILL' for a process itself under some
-- unusual conditions where the program cannot possible continue to
-- run (even to run a signal handler).
--
-- - Macro: int SIGHUP
-- The `SIGHUP' ("hang-up") signal is used to report that the user's
-- terminal is disconnected, perhaps because a network or telephone
-- connection was broken. For more information about this, see *Note
-- Control Modes::.
--
-- This signal is also used to report the termination of the
-- controlling process on a terminal to jobs associated with that
-- session; this termination effectively disconnects all processes in
-- the session from the controlling terminal. For more information,
-- see *Note Termination Internals::.
--
--
--File: libc.info, Node: Alarm Signals, Next: Asynchronous I/O Signals,
Prev: Termination Signals, Up: Standard Signals
--
--Alarm Signals
---------------
--
-- These signals are used to indicate the expiration of timers. *Note
--Setting an Alarm::, for information about functions that cause these
--signals to be sent.
--
-- The default behavior for these signals is to cause program
--termination. This default is rarely useful, but no other default would
--be useful; most of the ways of using these signals would require
--handler functions in any case.
--
-- - Macro: int SIGALRM
-- This signal typically indicates expiration of a timer that
-- measures real or clock time. It is used by the `alarm' function,
-- for example.
--
-- - Macro: int SIGVTALRM
-- This signal typically indicates expiration of a timer that
-- measures CPU time used by the current process. The name is an
-- abbreviation for "virtual time alarm".
--
-- - Macro: int SIGPROF
-- This signal is typically indicates expiration of a timer that
-- measures both CPU time used by the current process, and CPU time
-- expended on behalf of the process by the system. Such a timer is
-- used to implement code profiling facilities, hence the name of
-- this signal.
--
--
--File: libc.info, Node: Asynchronous I/O Signals, Next: Job Control Signals,
Prev: Alarm Signals, Up: Standard Signals
--
--Asynchronous I/O Signals
--------------------------
--
-- The signals listed in this section are used in conjunction with
--asynchronous I/O facilities. You have to take explicit action by
--calling `fcntl' to enable a particular file descriptor to generate
--these signals (*note Interrupt Input::.). The default action for these
--signals is to ignore them.
--
-- - Macro: int SIGIO
-- This signal is sent when a file descriptor is ready to perform
-- input or output.
--
-- On most operating systems, terminals and sockets are the only
-- kinds of files that can generate `SIGIO'; other kinds, including
-- ordinary files, never generate `SIGIO' even if you ask them to.
--
-- In the GNU system `SIGIO' will always be generated properly if you
-- successfully set asynchronous mode with `fcntl'.
--
-- - Macro: int SIGURG
-- This signal is sent when "urgent" or out-of-band data arrives on a
-- socket. *Note Out-of-Band Data::.
--
-- - Macro: int SIGPOLL
-- This is a System V signal name, more or less similar to `SIGIO'.
-- It is defined only for compatibility.
--
--
--File: libc.info, Node: Job Control Signals, Next: Operation Error Signals,
Prev: Asynchronous I/O Signals, Up: Standard Signals
--
--Job Control Signals
---------------------
--
-- These signals are used to support job control. If your system
--doesn't support job control, then these macros are defined but the
--signals themselves can't be raised or handled.
--
-- You should generally leave these signals alone unless you really
--understand how job control works. *Note Job Control::.
--
-- - Macro: int SIGCHLD
-- This signal is sent to a parent process whenever one of its child
-- processes terminates or stops.
--
-- The default action for this signal is to ignore it. If you
-- establish a handler for this signal while there are child
-- processes that have terminated but not reported their status via
-- `wait' or `waitpid' (*note Process Completion::.), whether your
-- new handler applies to those processes or not depends on the
-- particular operating system.
--
-- - Macro: int SIGCLD
-- This is an obsolete name for `SIGCHLD'.
--
-- - Macro: int SIGCONT
-- You can send a `SIGCONT' signal to a process to make it continue.
-- This signal is special--it always makes the process continue if it
-- is stopped, before the signal is delivered. The default behavior
-- is to do nothing else. You cannot block this signal. You can set
-- a handler, but `SIGCONT' always makes the process continue
-- regardless.
--
-- Most programs have no reason to handle `SIGCONT'; they simply
-- resume execution without realizing they were ever stopped. You
-- can use a handler for `SIGCONT' to make a program do something
-- special when it is stopped and continued--for example, to reprint
-- a prompt when it is suspended while waiting for input.
--
-- - Macro: int SIGSTOP
-- The `SIGSTOP' signal stops the process. It cannot be handled,
-- ignored, or blocked.
--
-- - Macro: int SIGTSTP
-- The `SIGTSTP' signal is an interactive stop signal. Unlike
-- `SIGSTOP', this signal can be handled and ignored.
--
-- Your program should handle this signal if you have a special need
-- to leave files or system tables in a secure state when a process is
-- stopped. For example, programs that turn off echoing should handle
-- `SIGTSTP' so they can turn echoing back on before stopping.
--
-- This signal is generated when the user types the SUSP character
-- (normally `C-z'). For more information about terminal driver
-- support, see *Note Special Characters::.
--
-- - Macro: int SIGTTIN
-- A process cannot read from the the user's terminal while it is
-- running as a background job. When any process in a background job
-- tries to read from the terminal, all of the processes in the job
-- are sent a `SIGTTIN' signal. The default action for this signal
-- is to stop the process. For more information about how this
-- interacts with the terminal driver, see *Note Access to the
-- Terminal::.
--
-- - Macro: int SIGTTOU
-- This is similar to `SIGTTIN', but is generated when a process in a
-- background job attempts to write to the terminal or set its modes.
-- Again, the default action is to stop the process. `SIGTTOU' is
-- only generated for an attempt to write to the terminal if the
-- `TOSTOP' output mode is set; *note Output Modes::..
--
-- While a process is stopped, no more signals can be delivered to it
--until it is continued, except `SIGKILL' signals and (obviously)
--`SIGCONT' signals. The signals are marked as pending, but not
--delivered until the process is continued. The `SIGKILL' signal always
--causes termination of the process and can't be blocked, handled or
--ignored. You can ignore `SIGCONT', but it always causes the process to
--be continued anyway if it is stopped. Sending a `SIGCONT' signal to a
--process causes any pending stop signals for that process to be
--discarded. Likewise, any pending `SIGCONT' signals for a process are
--discarded when it receives a stop signal.
--
-- When a process in an orphaned process group (*note Orphaned Process
--Groups::.) receives a `SIGTSTP', `SIGTTIN', or `SIGTTOU' signal and
--does not handle it, the process does not stop. Stopping the process
--would probably not be very useful, since there is no shell program that
--will notice it stop and allow the user to continue it. What happens
--instead depends on the operating system you are using. Some systems
--may do nothing; others may deliver another signal instead, such as
--`SIGKILL' or `SIGHUP'. In the GNU system, the process dies with
--`SIGKILL'; this avoids the problem of many stopped, orphaned processes
--lying around the system.
--
--
--File: libc.info, Node: Operation Error Signals, Next: Miscellaneous
Signals, Prev: Job Control Signals, Up: Standard Signals
--
--Operation Error Signals
-------------------------
--
-- These signals are used to report various errors generated by an
--operation done by the program. They do not necessarily indicate a
--programming error in the program, but an error that prevents an
--operating system call from completing. The default action for all of
--them is to cause the process to terminate.
--
-- - Macro: int SIGPIPE
-- Broken pipe. If you use pipes or FIFOs, you have to design your
-- application so that one process opens the pipe for reading before
-- another starts writing. If the reading process never starts, or
-- terminates unexpectedly, writing to the pipe or FIFO raises a
-- `SIGPIPE' signal. If `SIGPIPE' is blocked, handled or ignored,
-- the offending call fails with `EPIPE' instead.
--
-- Pipes and FIFO special files are discussed in more detail in *Note
-- Pipes and FIFOs::.
--
-- Another cause of `SIGPIPE' is when you try to output to a socket
-- that isn't connected. *Note Sending Data::.
--
-- - Macro: int SIGLOST
-- Resource lost. This signal is generated when you have an advisory
-- lock on an NFS file, and the NFS server reboots and forgets about
-- your lock.
--
-- In the GNU system, `SIGLOST' is generated when any server program
-- dies unexpectedly. It is usually fine to ignore the signal;
-- whatever call was made to the server that died just returns an
-- error.
--
-- - Macro: int SIGXCPU
-- CPU time limit exceeded. This signal is generated when the process
-- exceeds its soft resource limit on CPU time. *Note Limits on
-- Resources::.
--
-- - Macro: int SIGXFSZ
-- File size limit exceeded. This signal is generated when the
-- process attempts to extend a file so it exceeds the process's soft
-- resource limit on file size. *Note Limits on Resources::.
--
--
--File: libc.info, Node: Miscellaneous Signals, Next: Signal Messages, Prev:
Operation Error Signals, Up: Standard Signals
--
--Miscellaneous Signals
-----------------------
--
-- These signals are used for various other purposes. In general, they
--will not affect your program unless it explicitly uses them for
--something.
--
-- - Macro: int SIGUSR1
--
-- - Macro: int SIGUSR2
-- The `SIGUSR1' and `SIGUSR2' signals are set aside for you to use
-- any way you want. They're useful for simple interprocess
-- communication, if you write a signal handler for them in the
-- program that receives the signal.
--
-- There is an example showing the use of `SIGUSR1' and `SIGUSR2' in
-- *Note Signaling Another Process::.
--
-- The default action is to terminate the process.
--
-- - Macro: int SIGWINCH
-- Window size change. This is generated on some systems (including
-- GNU) when the terminal driver's record of the number of rows and
-- columns on the screen is changed. The default action is to ignore
-- it.
--
-- If a program does full-screen display, it should handle `SIGWINCH'.
-- When the signal arrives, it should fetch the new screen size and
-- reformat its display accordingly.
--
-- - Macro: int SIGINFO
-- Information request. In 4.4 BSD and the GNU system, this signal
-- is sent to all the processes in the foreground process group of
-- the controlling terminal when the user types the STATUS character
-- in canonical mode; *note Signal Characters::..
--
-- If the process is the leader of the process group, the default
-- action is to print some status information about the system and
-- what the process is doing. Otherwise the default is to do nothing.
--
--
--File: libc.info, Node: Signal Messages, Prev: Miscellaneous Signals, Up:
Standard Signals
--
--Signal Messages
-----------------
--
-- We mentioned above that the shell prints a message describing the
--signal that terminated a child process. The clean way to print a
--message describing a signal is to use the functions `strsignal' and
--`psignal'. These functions use a signal number to specify which kind
--of signal to describe. The signal number may come from the termination
--status of a child process (*note Process Completion::.) or it may come
--from a signal handler in the same process.
--
-- - Function: char * strsignal (int SIGNUM)
-- This function returns a pointer to a statically-allocated string
-- containing a message describing the signal SIGNUM. You should not
-- modify the contents of this string; and, since it can be rewritten
-- on subsequent calls, you should save a copy of it if you need to
-- reference it later.
--
-- This function is a GNU extension, declared in the header file
-- `string.h'.
--
-- - Function: void psignal (int SIGNUM, const char *MESSAGE)
-- This function prints a message describing the signal SIGNUM to the
-- standard error output stream `stderr'; see *Note Standard
-- Streams::.
--
-- If you call `psignal' with a MESSAGE that is either a null pointer
-- or an empty string, `psignal' just prints the message
-- corresponding to SIGNUM, adding a trailing newline.
--
-- If you supply a non-null MESSAGE argument, then `psignal' prefixes
-- its output with this string. It adds a colon and a space
-- character to separate the MESSAGE from the string corresponding to
-- SIGNUM.
--
-- This function is a BSD feature, declared in the header file
-- `signal.h'.
--
-- There is also an array `sys_siglist' which contains the messages for
--the various signal codes. This array exists on BSD systems, unlike
--`strsignal'.
--
--
--File: libc.info, Node: Signal Actions, Next: Defining Handlers, Prev:
Standard Signals, Up: Signal Handling
--
--Specifying Signal Actions
--=========================
--
-- The simplest way to change the action for a signal is to use the
--`signal' function. You can specify a built-in action (such as to
--ignore the signal), or you can "establish a handler".
--
-- The GNU library also implements the more versatile `sigaction'
--facility. This section describes both facilities and gives suggestions
--on which to use when.
--
--* Menu:
--
--* Basic Signal Handling:: The simple `signal' function.
--* Advanced Signal Handling:: The more powerful `sigaction' function.
--* Signal and Sigaction:: How those two functions interact.
--* Sigaction Function Example:: An example of using the sigaction function.
--* Flags for Sigaction:: Specifying options for signal handling.
--* Initial Signal Actions:: How programs inherit signal actions.
--
--
--File: libc.info, Node: Basic Signal Handling, Next: Advanced Signal
Handling, Up: Signal Actions
--
--Basic Signal Handling
-----------------------
--
-- The `signal' function provides a simple interface for establishing
--an action for a particular signal. The function and associated macros
--are declared in the header file `signal.h'.
--
-- - Data Type: sighandler_t
-- This is the type of signal handler functions. Signal handlers
-- take one integer argument specifying the signal number, and have
-- return type `void'. So, you should define handler functions like
-- this:
--
-- void HANDLER (int `signum') { ... }
--
-- The name `sighandler_t' for this data type is a GNU extension.
--
-- - Function: sighandler_t signal (int SIGNUM, sighandler_t ACTION)
-- The `signal' function establishes ACTION as the action for the
-- signal SIGNUM.
--
-- The first argument, SIGNUM, identifies the signal whose behavior
-- you want to control, and should be a signal number. The proper
-- way to specify a signal number is with one of the symbolic signal
-- names described in *Note Standard Signals::--don't use an explicit
-- number, because the numerical code for a given kind of signal may
-- vary from operating system to operating system.
--
-- The second argument, ACTION, specifies the action to use for the
-- signal SIGNUM. This can be one of the following:
--
-- `SIG_DFL'
-- `SIG_DFL' specifies the default action for the particular
-- signal. The default actions for various kinds of signals are
-- stated in *Note Standard Signals::.
--
-- `SIG_IGN'
-- `SIG_IGN' specifies that the signal should be ignored.
--
-- Your program generally should not ignore signals that
-- represent serious events or that are normally used to request
-- termination. You cannot ignore the `SIGKILL' or `SIGSTOP'
-- signals at all. You can ignore program error signals like
-- `SIGSEGV', but ignoring the error won't enable the program to
-- continue executing meaningfully. Ignoring user requests such
-- as `SIGINT', `SIGQUIT', and `SIGTSTP' is unfriendly.
--
-- When you do not wish signals to be delivered during a certain
-- part of the program, the thing to do is to block them, not
-- ignore them. *Note Blocking Signals::.
--
-- `HANDLER'
-- Supply the address of a handler function in your program, to
-- specify running this handler as the way to deliver the signal.
--
-- For more information about defining signal handler functions,
-- see *Note Defining Handlers::.
--
-- If you set the action for a signal to `SIG_IGN', or if you set it
-- to `SIG_DFL' and the default action is to ignore that signal, then
-- any pending signals of that type are discarded (even if they are
-- blocked). Discarding the pending signals means that they will
-- never be delivered, not even if you subsequently specify another
-- action and unblock this kind of signal.
--
-- The `signal' function returns the action that was previously in
-- effect for the specified SIGNUM. You can save this value and
-- restore it later by calling `signal' again.
--
-- If `signal' can't honor the request, it returns `SIG_ERR' instead.
-- The following `errno' error conditions are defined for this
-- function:
--
-- `EINVAL'
-- You specified an invalid SIGNUM; or you tried to ignore or
-- provide a handler for `SIGKILL' or `SIGSTOP'.
--
-- Here is a simple example of setting up a handler to delete temporary
--files when certain fatal signals happen:
--
-- #include <signal.h>
--
-- void
-- termination_handler (int signum)
-- {
-- struct temp_file *p;
--
-- for (p = temp_file_list; p; p = p->next)
-- unlink (p->name);
-- }
--
-- int
-- main (void)
-- {
-- ...
-- if (signal (SIGINT, termination_handler) == SIG_IGN)
-- signal (SIGINT, SIG_IGN);
-- if (signal (SIGHUP, termination_handler) == SIG_IGN)
-- signal (SIGHUP, SIG_IGN);
-- if (signal (SIGTERM, termination_handler) == SIG_IGN)
-- signal (SIGTERM, SIG_IGN);
-- ...
-- }
--
--Note how if a given signal was previously set to be ignored, this code
--avoids altering that setting. This is because non-job-control shells
--often ignore certain signals when starting children, and it is important
--for the children to respect this.
--
-- We do not handle `SIGQUIT' or the program error signals in this
--example because these are designed to provide information for debugging
--(a core dump), and the temporary files may give useful information.
--
-- - Function: sighandler_t ssignal (int SIGNUM, sighandler_t ACTION)
-- The `ssignal' function does the same thing as `signal'; it is
-- provided only for compatibility with SVID.
--
-- - Macro: sighandler_t SIG_ERR
-- The value of this macro is used as the return value from `signal'
-- to indicate an error.
--
--
--File: libc.info, Node: Advanced Signal Handling, Next: Signal and
Sigaction, Prev: Basic Signal Handling, Up: Signal Actions
--
--Advanced Signal Handling
--------------------------
--
-- The `sigaction' function has the same basic effect as `signal': to
--specify how a signal should be handled by the process. However,
--`sigaction' offers more control, at the expense of more complexity. In
--particular, `sigaction' allows you to specify additional flags to
--control when the signal is generated and how the handler is invoked.
--
-- The `sigaction' function is declared in `signal.h'.
--
-- - Data Type: struct sigaction
-- Structures of type `struct sigaction' are used in the `sigaction'
-- function to specify all the information about how to handle a
-- particular signal. This structure contains at least the following
-- members:
--
-- `sighandler_t sa_handler'
-- This is used in the same way as the ACTION argument to the
-- `signal' function. The value can be `SIG_DFL', `SIG_IGN', or
-- a function pointer. *Note Basic Signal Handling::.
--
-- `sigset_t sa_mask'
-- This specifies a set of signals to be blocked while the
-- handler runs. Blocking is explained in *Note Blocking for
-- Handler::. Note that the signal that was delivered is
-- automatically blocked by default before its handler is
-- started; this is true regardless of the value in `sa_mask'.
-- If you want that signal not to be blocked within its handler,
-- you must write code in the handler to unblock it.
--
-- `int sa_flags'
-- This specifies various flags which can affect the behavior of
-- the signal. These are described in more detail in *Note
-- Flags for Sigaction::.
--
-- - Function: int sigaction (int SIGNUM, const struct sigaction *ACTION,
-- struct sigaction *OLD-ACTION)
-- The ACTION argument is used to set up a new action for the signal
-- SIGNUM, while the OLD-ACTION argument is used to return
-- information about the action previously associated with this
-- symbol. (In other words, OLD-ACTION has the same purpose as the
-- `signal' function's return value--you can check to see what the
-- old action in effect for the signal was, and restore it later if
-- you want.)
--
-- Either ACTION or OLD-ACTION can be a null pointer. If OLD-ACTION
-- is a null pointer, this simply suppresses the return of
-- information about the old action. If ACTION is a null pointer,
-- the action associated with the signal SIGNUM is unchanged; this
-- allows you to inquire about how a signal is being handled without
-- changing that handling.
--
-- The return value from `sigaction' is zero if it succeeds, and `-1'
-- on failure. The following `errno' error conditions are defined
-- for this function:
--
-- `EINVAL'
-- The SIGNUM argument is not valid, or you are trying to trap
-- or ignore `SIGKILL' or `SIGSTOP'.
--
--
--File: libc.info, Node: Signal and Sigaction, Next: Sigaction Function
Example, Prev: Advanced Signal Handling, Up: Signal Actions
--
--Interaction of `signal' and `sigaction'
-----------------------------------------
--
-- It's possible to use both the `signal' and `sigaction' functions
--within a single program, but you have to be careful because they can
--interact in slightly strange ways.
--
-- The `sigaction' function specifies more information than the
--`signal' function, so the return value from `signal' cannot express the
--full range of `sigaction' possibilities. Therefore, if you use
--`signal' to save and later reestablish an action, it may not be able to
--reestablish properly a handler that was established with `sigaction'.
--
-- To avoid having problems as a result, always use `sigaction' to save
--and restore a handler if your program uses `sigaction' at all. Since
--`sigaction' is more general, it can properly save and reestablish any
--action, regardless of whether it was established originally with
--`signal' or `sigaction'.
--
-- On some systems if you establish an action with `signal' and then
--examine it with `sigaction', the handler address that you get may not
--be the same as what you specified with `signal'. It may not even be
--suitable for use as an action argument with `signal'. But you can rely
--on using it as an argument to `sigaction'. This problem never happens
--on the GNU system.
--
-- So, you're better off using one or the other of the mechanisms
--consistently within a single program.
--
-- *Portability Note:* The basic `signal' function is a feature of
--ISO C, while `sigaction' is part of the POSIX.1 standard. If you are
--concerned about portability to non-POSIX systems, then you should use
--the `signal' function instead.
--
--
--File: libc.info, Node: Sigaction Function Example, Next: Flags for
Sigaction, Prev: Signal and Sigaction, Up: Signal Actions
--
--`sigaction' Function Example
------------------------------
--
-- In *Note Basic Signal Handling::, we gave an example of establishing
--a simple handler for termination signals using `signal'. Here is an
--equivalent example using `sigaction':
--
-- #include <signal.h>
--
-- void
-- termination_handler (int signum)
-- {
-- struct temp_file *p;
--
-- for (p = temp_file_list; p; p = p->next)
-- unlink (p->name);
-- }
--
-- int
-- main (void)
-- {
-- ...
-- struct sigaction new_action, old_action;
--
-- /* Set up the structure to specify the new action. */
-- new_action.sa_handler = termination_handler;
-- sigemptyset (&new_action.sa_mask);
-- new_action.sa_flags = 0;
--
-- sigaction (SIGINT, NULL, &old_action);
-- if (old_action.sa_handler != SIG_IGN)
-- sigaction (SIGINT, &new_action, NULL);
-- sigaction (SIGHUP, NULL, &old_action);
-- if (old_action.sa_handler != SIG_IGN)
-- sigaction (SIGHUP, &new_action, NULL);
-- sigaction (SIGTERM, NULL, &old_action);
-- if (old_action.sa_handler != SIG_IGN)
-- sigaction (SIGTERM, &new_action, NULL);
-- ...
-- }
--
-- The program just loads the `new_action' structure with the desired
--parameters and passes it in the `sigaction' call. The usage of
--`sigemptyset' is described later; see *Note Blocking Signals::.
--
-- As in the example using `signal', we avoid handling signals
--previously set to be ignored. Here we can avoid altering the signal
--handler even momentarily, by using the feature of `sigaction' that lets
--us examine the current action without specifying a new one.
--
-- Here is another example. It retrieves information about the current
--action for `SIGINT' without changing that action.
--
-- struct sigaction query_action;
--
-- if (sigaction (SIGINT, NULL, &query_action) < 0)
-- /* `sigaction' returns -1 in case of error. */
-- else if (query_action.sa_handler == SIG_DFL)
-- /* `SIGINT' is handled in the default, fatal manner. */
-- else if (query_action.sa_handler == SIG_IGN)
-- /* `SIGINT' is ignored. */
-- else
-- /* A programmer-defined signal handler is in effect. */
--
--
--File: libc.info, Node: Flags for Sigaction, Next: Initial Signal Actions,
Prev: Sigaction Function Example, Up: Signal Actions
--
--Flags for `sigaction'
-----------------------
--
-- The `sa_flags' member of the `sigaction' structure is a catch-all
--for special features. Most of the time, `SA_RESTART' is a good value
--to use for this field.
--
-- The value of `sa_flags' is interpreted as a bit mask. Thus, you
--should choose the flags you want to set, OR those flags together, and
--store the result in the `sa_flags' member of your `sigaction' structure.
--
-- Each signal number has its own set of flags. Each call to
--`sigaction' affects one particular signal number, and the flags that
--you specify apply only to that particular signal.
--
-- In the GNU C library, establishing a handler with `signal' sets all
--the flags to zero except for `SA_RESTART', whose value depends on the
--settings you have made with `siginterrupt'. *Note Interrupted
--Primitives::, to see what this is about.
--
-- These macros are defined in the header file `signal.h'.
--
-- - Macro: int SA_NOCLDSTOP
-- This flag is meaningful only for the `SIGCHLD' signal. When the
-- flag is set, the system delivers the signal for a terminated child
-- process but not for one that is stopped. By default, `SIGCHLD' is
-- delivered for both terminated children and stopped children.
--
-- Setting this flag for a signal other than `SIGCHLD' has no effect.
--
-- - Macro: int SA_ONSTACK
-- If this flag is set for a particular signal number, the system
-- uses the signal stack when delivering that kind of signal. *Note
-- Signal Stack::. If a signal with this flag arrives and you have
-- not set a signal stack, the system terminates the program with
-- `SIGILL'.
--
-- - Macro: int SA_RESTART
-- This flag controls what happens when a signal is delivered during
-- certain primitives (such as `open', `read' or `write'), and the
-- signal handler returns normally. There are two alternatives: the
-- library function can resume, or it can return failure with error
-- code `EINTR'.
--
-- The choice is controlled by the `SA_RESTART' flag for the
-- particular kind of signal that was delivered. If the flag is set,
-- returning from a handler resumes the library function. If the
-- flag is clear, returning from a handler makes the function fail.
-- *Note Interrupted Primitives::.
--
--
--File: libc.info, Node: Initial Signal Actions, Prev: Flags for Sigaction,
Up: Signal Actions
--
--Initial Signal Actions
------------------------
--
-- When a new process is created (*note Creating a Process::.), it
--inherits handling of signals from its parent process. However, when
--you load a new process image using the `exec' function (*note Executing
--a File::.), any signals that you've defined your own handlers for
--revert to their `SIG_DFL' handling. (If you think about it a little,
--this makes sense; the handler functions from the old program are
--specific to that program, and aren't even present in the address space
--of the new program image.) Of course, the new program can establish
--its own handlers.
--
-- When a program is run by a shell, the shell normally sets the initial
--actions for the child process to `SIG_DFL' or `SIG_IGN', as
--appropriate. It's a good idea to check to make sure that the shell has
--not set up an initial action of `SIG_IGN' before you establish your own
--signal handlers.
--
-- Here is an example of how to establish a handler for `SIGHUP', but
--not if `SIGHUP' is currently ignored:
--
-- ...
-- struct sigaction temp;
--
-- sigaction (SIGHUP, NULL, &temp);
--
-- if (temp.sa_handler != SIG_IGN)
-- {
-- temp.sa_handler = handle_sighup;
-- sigemptyset (&temp.sa_mask);
-- sigaction (SIGHUP, &temp, NULL);
-- }
--
--
--File: libc.info, Node: Defining Handlers, Next: Interrupted Primitives,
Prev: Signal Actions, Up: Signal Handling
--
--Defining Signal Handlers
--========================
--
-- This section describes how to write a signal handler function that
--can be established with the `signal' or `sigaction' functions.
--
-- A signal handler is just a function that you compile together with
--the rest of the program. Instead of directly invoking the function,
--you use `signal' or `sigaction' to tell the operating system to call it
--when a signal arrives. This is known as "establishing" the handler.
--*Note Signal Actions::.
--
-- There are two basic strategies you can use in signal handler
--functions:
--
-- * You can have the handler function note that the signal arrived by
-- tweaking some global data structures, and then return normally.
--
-- * You can have the handler function terminate the program or transfer
-- control to a point where it can recover from the situation that
-- caused the signal.
--
-- You need to take special care in writing handler functions because
--they can be called asynchronously. That is, a handler might be called
--at any point in the program, unpredictably. If two signals arrive
--during a very short interval, one handler can run within another. This
--section describes what your handler should do, and what you should
--avoid.
--
--* Menu:
--
--* Handler Returns:: Handlers that return normally, and what
-- this means.
--* Termination in Handler:: How handler functions terminate a program.
--* Longjmp in Handler:: Nonlocal transfer of control out of a
-- signal handler.
--* Signals in Handler:: What happens when signals arrive while
-- the handler is already occupied.
--* Merged Signals:: When a second signal arrives before the
-- first is handled.
--* Nonreentrancy:: Do not call any functions unless you know they
-- are reentrant with respect to signals.
--* Atomic Data Access:: A single handler can run in the middle of
-- reading or writing a single object.
--
--
--File: libc.info, Node: Handler Returns, Next: Termination in Handler, Up:
Defining Handlers
--
--Signal Handlers that Return
-----------------------------
--
-- Handlers which return normally are usually used for signals such as
--`SIGALRM' and the I/O and interprocess communication signals. But a
--handler for `SIGINT' might also return normally after setting a flag
--that tells the program to exit at a convenient time.
--
-- It is not safe to return normally from the handler for a program
--error signal, because the behavior of the program when the handler
--function returns is not defined after a program error. *Note Program
--Error Signals::.
--
-- Handlers that return normally must modify some global variable in
--order to have any effect. Typically, the variable is one that is
--examined periodically by the program during normal operation. Its data
--type should be `sig_atomic_t' for reasons described in *Note Atomic
--Data Access::.
--
-- Here is a simple example of such a program. It executes the body of
--the loop until it has noticed that a `SIGALRM' signal has arrived.
--This technique is useful because it allows the iteration in progress
--when the signal arrives to complete before the loop exits.
--
-- #include <signal.h>
-- #include <stdio.h>
-- #include <stdlib.h>
--
-- /* This flag controls termination of the main loop. */
-- volatile sig_atomic_t keep_going = 1;
--
-- /* The signal handler just clears the flag and re-enables itself. */
-- void
-- catch_alarm (int sig)
-- {
-- keep_going = 0;
-- signal (sig, catch_alarm);
-- }
--
-- void
-- do_stuff (void)
-- {
-- puts ("Doing stuff while waiting for alarm....");
-- }
--
-- int
-- main (void)
-- {
-- /* Establish a handler for SIGALRM signals. */
-- signal (SIGALRM, catch_alarm);
--
-- /* Set an alarm to go off in a little while. */
-- alarm (2);
--
-- /* Check the flag once in a while to see when to quit. */
-- while (keep_going)
-- do_stuff ();
--
-- return EXIT_SUCCESS;
-- }
--
--
--File: libc.info, Node: Termination in Handler, Next: Longjmp in Handler,
Prev: Handler Returns, Up: Defining Handlers
--
--Handlers That Terminate the Process
-------------------------------------
--
-- Handler functions that terminate the program are typically used to
--cause orderly cleanup or recovery from program error signals and
--interactive interrupts.
--
-- The cleanest way for a handler to terminate the process is to raise
--the same signal that ran the handler in the first place. Here is how
--to do this:
--
-- volatile sig_atomic_t fatal_error_in_progress = 0;
--
-- void
-- fatal_error_signal (int sig)
-- {
-- /* Since this handler is established for more than one kind of signal,
-- it might still get invoked recursively by delivery of some other
kind
-- of signal. Use a static variable to keep track of that. */
-- if (fatal_error_in_progress)
-- raise (sig);
-- fatal_error_in_progress = 1;
--
-- /* Now do the clean up actions:
-- - reset terminal modes
-- - kill child processes
-- - remove lock files */
-- ...
--
-- /* Now reraise the signal. Since the signal is blocked,
-- it will receive its default handling, which is
-- to terminate the process. We could just call
-- `exit' or `abort', but reraising the signal
-- sets the return status from the process correctly. */
-- raise (sig);
-- }
--
--
--File: libc.info, Node: Longjmp in Handler, Next: Signals in Handler, Prev:
Termination in Handler, Up: Defining Handlers
--
--Nonlocal Control Transfer in Handlers
---------------------------------------
--
-- You can do a nonlocal transfer of control out of a signal handler
--using the `setjmp' and `longjmp' facilities (*note Non-Local Exits::.).
--
-- When the handler does a nonlocal control transfer, the part of the
--program that was running will not continue. If this part of the program
--was in the middle of updating an important data structure, the data
--structure will remain inconsistent. Since the program does not
--terminate, the inconsistency is likely to be noticed later on.
--
-- There are two ways to avoid this problem. One is to block the signal
--for the parts of the program that update important data structures.
--Blocking the signal delays its delivery until it is unblocked, once the
--critical updating is finished. *Note Blocking Signals::.
--
-- The other way to re-initialize the crucial data structures in the
--signal handler, or make their values consistent.
--
-- Here is a rather schematic example showing the reinitialization of
--one global variable.
--
-- #include <signal.h>
-- #include <setjmp.h>
--
-- jmp_buf return_to_top_level;
--
-- volatile sig_atomic_t waiting_for_input;
--
-- void
-- handle_sigint (int signum)
-- {
-- /* We may have been waiting for input when the signal arrived,
-- but we are no longer waiting once we transfer control. */
-- waiting_for_input = 0;
-- longjmp (return_to_top_level, 1);
-- }
--
-- int
-- main (void)
-- {
-- ...
-- signal (SIGINT, sigint_handler);
-- ...
-- while (1) {
-- prepare_for_command ();
-- if (setjmp (return_to_top_level) == 0)
-- read_and_execute_command ();
-- }
-- }
--
-- /* Imagine this is a subroutine used by various commands. */
-- char *
-- read_data ()
-- {
-- if (input_from_terminal) {
-- waiting_for_input = 1;
-- ...
-- waiting_for_input = 0;
-- } else {
-- ...
-- }
-- }
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-21
glibc-2.0.1/manual/libc.info-21
---- ../glibc-2.0.1/manual/libc.info-21 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-21 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1178 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Signals in Handler, Next: Merged Signals, Prev:
Longjmp in Handler, Up: Defining Handlers
--
--Signals Arriving While a Handler Runs
---------------------------------------
--
-- What happens if another signal arrives while your signal handler
--function is running?
--
-- When the handler for a particular signal is invoked, that signal is
--automatically blocked until the handler returns. That means that if two
--signals of the same kind arrive close together, the second one will be
--held until the first has been handled. (The handler can explicitly
--unblock the signal using `sigprocmask', if you want to allow more
--signals of this type to arrive; see *Note Process Signal Mask::.)
--
-- However, your handler can still be interrupted by delivery of another
--kind of signal. To avoid this, you can use the `sa_mask' member of the
--action structure passed to `sigaction' to explicitly specify which
--signals should be blocked while the signal handler runs. These signals
--are in addition to the signal for which the handler was invoked, and
--any other signals that are normally blocked by the process. *Note
--Blocking for Handler::.
--
-- When the handler returns, the set of blocked signals is restored to
--the value it had before the handler ran. So using `sigprocmask' inside
--the handler only affects what signals can arrive during the execution of
--the handler itself, not what signals can arrive once the handler
--returns.
--
-- *Portability Note:* Always use `sigaction' to establish a handler
--for a signal that you expect to receive asynchronously, if you want
--your program to work properly on System V Unix. On this system, the
--handling of a signal whose handler was established with `signal'
--automatically sets the signal's action back to `SIG_DFL', and the
--handler must re-establish itself each time it runs. This practice,
--while inconvenient, does work when signals cannot arrive in succession.
--However, if another signal can arrive right away, it may arrive before
--the handler can re-establish itself. Then the second signal would
--receive the default handling, which could terminate the process.
--
--
--File: libc.info, Node: Merged Signals, Next: Nonreentrancy, Prev: Signals
in Handler, Up: Defining Handlers
--
--Signals Close Together Merge into One
---------------------------------------
--
-- If multiple signals of the same type are delivered to your process
--before your signal handler has a chance to be invoked at all, the
--handler may only be invoked once, as if only a single signal had
--arrived. In effect, the signals merge into one. This situation can
--arise when the signal is blocked, or in a multiprocessing environment
--where the system is busy running some other processes while the signals
--are delivered. This means, for example, that you cannot reliably use a
--signal handler to count signals. The only distinction you can reliably
--make is whether at least one signal has arrived since a given time in
--the past.
--
-- Here is an example of a handler for `SIGCHLD' that compensates for
--the fact that the number of signals recieved may not equal the number of
--child processes generate them. It assumes that the program keeps track
--of all the child processes with a chain of structures as follows:
--
-- struct process
-- {
-- struct process *next;
-- /* The process ID of this child. */
-- int pid;
-- /* The descriptor of the pipe or pseudo terminal
-- on which output comes from this child. */
-- int input_descriptor;
-- /* Nonzero if this process has stopped or terminated. */
-- sig_atomic_t have_status;
-- /* The status of this child; 0 if running,
-- otherwise a status value from `waitpid'. */
-- int status;
-- };
--
-- struct process *process_list;
--
-- This example also uses a flag to indicate whether signals have
--arrived since some time in the past--whenever the program last cleared
--it to zero.
--
-- /* Nonzero means some child's status has changed
-- so look at `process_list' for the details. */
-- int process_status_change;
--
-- Here is the handler itself:
--
-- void
-- sigchld_handler (int signo)
-- {
-- int old_errno = errno;
--
-- while (1) {
-- register int pid;
-- int w;
-- struct process *p;
--
-- /* Keep asking for a status until we get a definitive result. */
-- do
-- {
-- errno = 0;
-- pid = waitpid (WAIT_ANY, &w, WNOHANG | WUNTRACED);
-- }
-- while (pid <= 0 && errno == EINTR);
--
-- if (pid <= 0) {
-- /* A real failure means there are no more
-- stopped or terminated child processes, so return. */
-- errno = old_errno;
-- return;
-- }
--
-- /* Find the process that signaled us, and record its status. */
--
-- for (p = process_list; p; p = p->next)
-- if (p->pid == pid) {
-- p->status = w;
-- /* Indicate that the `status' field
-- has data to look at. We do this only after storing it. */
-- p->have_status = 1;
--
-- /* If process has terminated, stop waiting for its output. */
-- if (WIFSIGNALED (w) || WIFEXITED (w))
-- if (p->input_descriptor)
-- FD_CLR (p->input_descriptor, &input_wait_mask);
--
-- /* The program should check this flag from time to time
-- to see if there is any news in `process_list'. */
-- ++process_status_change;
-- }
--
-- /* Loop around to handle all the processes
-- that have something to tell us. */
-- }
-- }
--
-- Here is the proper way to check the flag `process_status_change':
--
-- if (process_status_change) {
-- struct process *p;
-- process_status_change = 0;
-- for (p = process_list; p; p = p->next)
-- if (p->have_status) {
-- ... Examine `p->status' ...
-- }
-- }
--
--It is vital to clear the flag before examining the list; otherwise, if a
--signal were delivered just before the clearing of the flag, and after
--the appropriate element of the process list had been checked, the status
--change would go unnoticed until the next signal arrived to set the flag
--again. You could, of course, avoid this problem by blocking the signal
--while scanning the list, but it is much more elegant to guarantee
--correctness by doing things in the right order.
--
-- The loop which checks process status avoids examining `p->status'
--until it sees that status has been validly stored. This is to make sure
--that the status cannot change in the middle of accessing it. Once
--`p->have_status' is set, it means that the child process is stopped or
--terminated, and in either case, it cannot stop or terminate again until
--the program has taken notice. *Note Atomic Usage::, for more
--information about coping with interruptions during accessings of a
--variable.
--
-- Here is another way you can test whether the handler has run since
--the last time you checked. This technique uses a counter which is never
--changed outside the handler. Instead of clearing the count, the program
--remembers the previous value and sees whether it has changed since the
--previous check. The advantage of this method is that different parts of
--the program can check independently, each part checking whether there
--has been a signal since that part last checked.
--
-- sig_atomic_t process_status_change;
--
-- sig_atomic_t last_process_status_change;
--
-- ...
-- {
-- sig_atomic_t prev = last_process_status_change;
-- last_process_status_change = process_status_change;
-- if (last_process_status_change != prev) {
-- struct process *p;
-- for (p = process_list; p; p = p->next)
-- if (p->have_status) {
-- ... Examine `p->status' ...
-- }
-- }
-- }
--
--
--File: libc.info, Node: Nonreentrancy, Next: Atomic Data Access, Prev:
Merged Signals, Up: Defining Handlers
--
--Signal Handling and Nonreentrant Functions
--------------------------------------------
--
-- Handler functions usually don't do very much. The best practice is
--to write a handler that does nothing but set an external variable that
--the program checks regularly, and leave all serious work to the program.
--This is best because the handler can be called at asynchronously, at
--unpredictable times--perhaps in the middle of a primitive function, or
--even between the beginning and the end of a C operator that requires
--multiple instructions. The data structures being manipulated might
--therefore be in an inconsistent state when the handler function is
--invoked. Even copying one `int' variable into another can take two
--instructions on most machines.
--
-- This means you have to be very careful about what you do in a signal
--handler.
--
-- * If your handler needs to access any global variables from your
-- program, declare those variables `volatile'. This tells the
-- compiler that the value of the variable might change
-- asynchronously, and inhibits certain optimizations that would be
-- invalidated by such modifications.
--
-- * If you call a function in the handler, make sure it is "reentrant"
-- with respect to signals, or else make sure that the signal cannot
-- interrupt a call to a related function.
--
-- A function can be non-reentrant if it uses memory that is not on the
--stack.
--
-- * If a function uses a static variable or a global variable, or a
-- dynamically-allocated object that it finds for itself, then it is
-- non-reentrant and any two calls to the function can interfere.
--
-- For example, suppose that the signal handler uses `gethostbyname'.
-- This function returns its value in a static object, reusing the
-- same object each time. If the signal happens to arrive during a
-- call to `gethostbyname', or even after one (while the program is
-- still using the value), it will clobber the value that the program
-- asked for.
--
-- However, if the program does not use `gethostbyname' or any other
-- function that returns information in the same object, or if it
-- always blocks signals around each use, then you are safe.
--
-- There are a large number of library functions that return values
-- in a fixed object, always reusing the same object in this fashion,
-- and all of them cause the same problem. The description of a
-- function in this manual always mentions this behavior.
--
-- * If a function uses and modifies an object that you supply, then it
-- is potentially non-reentrant; two calls can interfere if they use
-- the same object.
--
-- This case arises when you do I/O using streams. Suppose that the
-- signal handler prints a message with `fprintf'. Suppose that the
-- program was in the middle of an `fprintf' call using the same
-- stream when the signal was delivered. Both the signal handler's
-- message and the program's data could be corrupted, because both
-- calls operate on the same data structure--the stream itself.
--
-- However, if you know that the stream that the handler uses cannot
-- possibly be used by the program at a time when signals can arrive,
-- then you are safe. It is no problem if the program uses some
-- other stream.
--
-- * On most systems, `malloc' and `free' are not reentrant, because
-- they use a static data structure which records what memory blocks
-- are free. As a result, no library functions that allocate or free
-- memory are reentrant. This includes functions that allocate space
-- to store a result.
--
-- The best way to avoid the need to allocate memory in a handler is
-- to allocate in advance space for signal handlers to use.
--
-- The best way to avoid freeing memory in a handler is to flag or
-- record the objects to be freed, and have the program check from
-- time to time whether anything is waiting to be freed. But this
-- must be done with care, because placing an object on a chain is
-- not atomic, and if it is interrupted by another signal handler
-- that does the same thing, you could "lose" one of the objects.
--
-- The relocating allocation functions (*note Relocating Allocator::.)
-- are certainly not safe to use in a signal handler.
--
-- * Any function that modifies `errno' is non-reentrant, but you can
-- correct for this: in the handler, save the original value of
-- `errno' and restore it before returning normally. This prevents
-- errors that occur within the signal handler from being confused
-- with errors from system calls at the point the program is
-- interrupted to run the handler.
--
-- This technique is generally applicable; if you want to call in a
-- handler a function that modifies a particular object in memory,
-- you can make this safe by saving and restoring that object.
--
-- * Merely reading from a memory object is safe provided that you can
-- deal with any of the values that might appear in the object at a
-- time when the signal can be delivered. Keep in mind that
-- assignment to some data types requires more than one instruction,
-- which means that the handler could run "in the middle of" an
-- assignment to the variable if its type is not atomic. *Note
-- Atomic Data Access::.
--
-- * Merely writing into a memory object is safe as long as a sudden
-- change in the value, at any time when the handler might run, will
-- not disturb anything.
--
--
--File: libc.info, Node: Atomic Data Access, Prev: Nonreentrancy, Up:
Defining Handlers
--
--Atomic Data Access and Signal Handling
----------------------------------------
--
-- Whether the data in your application concerns atoms, or mere text,
--you have to be careful about the fact that access to a single datum is
--not necessarily "atomic". This means that it can take more than one
--instruction to read or write a single object. In such cases, a signal
--handler might in the middle of reading or writing the object.
--
-- There are three ways you can cope with this problem. You can use
--data types that are always accessed atomically; you can carefully
--arrange that nothing untoward happens if an access is interrupted, or
--you can block all signals around any access that had better not be
--interrupted (*note Blocking Signals::.).
--
--* Menu:
--
--* Non-atomic Example:: A program illustrating interrupted
access.
--* Types: Atomic Types. Data types that guarantee no
interruption.
--* Usage: Atomic Usage. Proving that interruption is harmless.
--
--
--File: libc.info, Node: Non-atomic Example, Next: Atomic Types, Up: Atomic
Data Access
--
--Problems with Non-Atomic Access
--...............................
--
-- Here is an example which shows what can happen if a signal handler
--runs in the middle of modifying a variable. (Interrupting the reading
--of a variable can also lead to paradoxical results, but here we only
--show writing.)
--
-- #include <signal.h>
-- #include <stdio.h>
--
-- struct two_words { int a, b; } memory;
--
-- void
-- handler(int signum)
-- {
-- printf ("%d,%d\n", memory.a, memory.b);
-- alarm (1);
-- }
-- int
-- main (void)
-- {
-- static struct two_words zeros = { 0, 0 }, ones = { 1, 1 };
-- signal (SIGALRM, handler);
-- memory = zeros;
-- alarm (1);
-- while (1)
-- {
-- memory = zeros;
-- memory = ones;
-- }
-- }
--
-- This program fills `memory' with zeros, ones, zeros, ones,
--alternating forever; meanwhile, once per second, the alarm signal
--handler prints the current contents. (Calling `printf' in the handler
--is safe in this program because it is certainly not being called outside
--the handler when the signal happens.)
--
-- Clearly, this program can print a pair of zeros or a pair of ones.
--But that's not all it can do! On most machines, it takes several
--instructions to store a new value in `memory', and the value is stored
--one word at a time. If the signal is delivered in between these
--instructions, the handler might find that `memory.a' is zero and
--`memory.b' is one (or vice versa).
--
-- On some machines it may be possible to store a new value in `memory'
--with just one instruction that cannot be interrupted. On these
--machines, the handler will always print two zeros or two ones.
--
--
--File: libc.info, Node: Atomic Types, Next: Atomic Usage, Prev: Non-atomic
Example, Up: Atomic Data Access
--
--Atomic Types
--............
--
-- To avoid uncertainty about interrupting access to a variable, you can
--use a particular data type for which access is always atomic:
--`sig_atomic_t'. Reading and writing this data type is guaranteed to
--happen in a single instruction, so there's no way for a handler to run
--"in the middle" of an access.
--
-- The type `sig_atomic_t' is always an integer data type, but which
--one it is, and how many bits it contains, may vary from machine to
--machine.
--
-- - Data Type: sig_atomic_t
-- This is an integer data type. Objects of this type are always
-- accessed atomically.
--
-- In practice, you can assume that `int' and other integer types no
--longer than `int' are atomic. You can also assume that pointer types
--are atomic; that is very convenient. Both of these are true on all of
--the machines that the GNU C library supports, and on all POSIX systems
--we know of.
--
--
--File: libc.info, Node: Atomic Usage, Prev: Atomic Types, Up: Atomic Data
Access
--
--Atomic Usage Patterns
--.....................
--
-- Certain patterns of access avoid any problem even if an access is
--interrupted. For example, a flag which is set by the handler, and
--tested and cleared by the main program from time to time, is always safe
--even if access actually requires two instructions. To show that this is
--so, we must consider each access that could be interrupted, and show
--that there is no problem if it is interrupted.
--
-- An interrupt in the middle of testing the flag is safe because
--either it's recognized to be nonzero, in which case the precise value
--doesn't matter, or it will be seen to be nonzero the next time it's
--tested.
--
-- An interrupt in the middle of clearing the flag is no problem because
--either the value ends up zero, which is what happens if a signal comes
--in just before the flag is cleared, or the value ends up nonzero, and
--subsequent events occur as if the signal had come in just after the flag
--was cleared. As long as the code handles both of these cases properly,
--it can also handle a signal in the middle of clearing the flag. (This
--is an example of the sort of reasoning you need to do to figure out
--whether non-atomic usage is safe.)
--
-- Sometimes you can insure uninterrupted access to one object by
--protecting its use with another object, perhaps one whose type
--guarantees atomicity. *Note Merged Signals::, for an example.
--
--
--File: libc.info, Node: Interrupted Primitives, Next: Generating Signals,
Prev: Defining Handlers, Up: Signal Handling
--
--Primitives Interrupted by Signals
--=================================
--
-- A signal can arrive and be handled while an I/O primitive such as
--`open' or `read' is waiting for an I/O device. If the signal handler
--returns, the system faces the question: what should happen next?
--
-- POSIX specifies one approach: make the primitive fail right away.
--The error code for this kind of failure is `EINTR'. This is flexible,
--but usually inconvenient. Typically, POSIX applications that use signal
--handlers must check for `EINTR' after each library function that can
--return it, in order to try the call again. Often programmers forget to
--check, which is a common source of error.
--
-- The GNU library provides a convenient way to retry a call after a
--temporary failure, with the macro `TEMP_FAILURE_RETRY':
--
-- - Macro: TEMP_FAILURE_RETRY (EXPRESSION)
-- This macro evaluates EXPRESSION once. If it fails and reports
-- error code `EINTR', `TEMP_FAILURE_RETRY' evaluates it again, and
-- over and over until the result is not a temporary failure.
--
-- The value returned by `TEMP_FAILURE_RETRY' is whatever value
-- EXPRESSION produced.
--
-- BSD avoids `EINTR' entirely and provides a more convenient approach:
--to restart the interrupted primitive, instead of making it fail. If
--you choose this approach, you need not be concerned with `EINTR'.
--
-- You can choose either approach with the GNU library. If you use
--`sigaction' to establish a signal handler, you can specify how that
--handler should behave. If you specify the `SA_RESTART' flag, return
--from that handler will resume a primitive; otherwise, return from that
--handler will cause `EINTR'. *Note Flags for Sigaction::.
--
-- Another way to specify the choice is with the `siginterrupt'
--function. *Note BSD Handler::.
--
-- When you don't specify with `sigaction' or `siginterrupt' what a
--particular handler should do, it uses a default choice. The default
--choice in the GNU library depends on the feature test macros you have
--defined. If you define `_BSD_SOURCE' or `_GNU_SOURCE' before calling
--`signal', the default is to resume primitives; otherwise, the default
--is to make them fail with `EINTR'. (The library contains alternate
--versions of the `signal' function, and the feature test macros
--determine which one you really call.) *Note Feature Test Macros::.
--
-- The description of each primitive affected by this issue lists
--`EINTR' among the error codes it can return.
--
-- There is one situation where resumption never happens no matter which
--choice you make: when a data-transfer function such as `read' or
--`write' is interrupted by a signal after transferring part of the data.
--In this case, the function returns the number of bytes already
--transferred, indicating partial success.
--
-- This might at first appear to cause unreliable behavior on
--record-oriented devices (including datagram sockets; *note
--Datagrams::.), where splitting one `read' or `write' into two would
--read or write two records. Actually, there is no problem, because
--interruption after a partial transfer cannot happen on such devices;
--they always transfer an entire record in one burst, with no waiting
--once data transfer has started.
--
--
--File: libc.info, Node: Generating Signals, Next: Blocking Signals, Prev:
Interrupted Primitives, Up: Signal Handling
--
--Generating Signals
--==================
--
-- Besides signals that are generated as a result of a hardware trap or
--interrupt, your program can explicitly send signals to itself or to
--another process.
--
--* Menu:
--
--* Signaling Yourself:: A process can send a signal to itself.
--* Signaling Another Process:: Send a signal to another process.
--* Permission for kill:: Permission for using `kill'.
--* Kill Example:: Using `kill' for Communication.
--
--
--File: libc.info, Node: Signaling Yourself, Next: Signaling Another Process,
Up: Generating Signals
--
--Signaling Yourself
--------------------
--
-- A process can send itself a signal with the `raise' function. This
--function is declared in `signal.h'.
--
-- - Function: int raise (int SIGNUM)
-- The `raise' function sends the signal SIGNUM to the calling
-- process. It returns zero if successful and a nonzero value if it
-- fails. About the only reason for failure would be if the value of
-- SIGNUM is invalid.
--
-- - Function: int gsignal (int SIGNUM)
-- The `gsignal' function does the same thing as `raise'; it is
-- provided only for compatibility with SVID.
--
-- One convenient use for `raise' is to reproduce the default behavior
--of a signal that you have trapped. For instance, suppose a user of your
--program types the SUSP character (usually `C-z'; *note Special
--Characters::.) to send it an interactive stop stop signal (`SIGTSTP'),
--and you want to clean up some internal data buffers before stopping.
--You might set this up like this:
--
-- #include <signal.h>
--
-- /* When a stop signal arrives, set the action back to the default
-- and then resend the signal after doing cleanup actions. */
--
-- void
-- tstp_handler (int sig)
-- {
-- signal (SIGTSTP, SIG_DFL);
-- /* Do cleanup actions here. */
-- ...
-- raise (SIGTSTP);
-- }
--
-- /* When the process is continued again, restore the signal handler. */
--
-- void
-- cont_handler (int sig)
-- {
-- signal (SIGCONT, cont_handler);
-- signal (SIGTSTP, tstp_handler);
-- }
-- /* Enable both handlers during program initialization. */
--
-- int
-- main (void)
-- {
-- signal (SIGCONT, cont_handler);
-- signal (SIGTSTP, tstp_handler);
-- ...
-- }
--
-- *Portability note:* `raise' was invented by the ISO C committee.
--Older systems may not support it, so using `kill' may be more portable.
--*Note Signaling Another Process::.
--
--
--File: libc.info, Node: Signaling Another Process, Next: Permission for
kill, Prev: Signaling Yourself, Up: Generating Signals
--
--Signaling Another Process
---------------------------
--
-- The `kill' function can be used to send a signal to another process.
--In spite of its name, it can be used for a lot of things other than
--causing a process to terminate. Some examples of situations where you
--might want to send signals between processes are:
--
-- * A parent process starts a child to perform a task--perhaps having
-- the child running an infinite loop--and then terminates the child
-- when the task is no longer needed.
--
-- * A process executes as part of a group, and needs to terminate or
-- notify the other processes in the group when an error or other
-- event occurs.
--
-- * Two processes need to synchronize while working together.
--
-- This section assumes that you know a little bit about how processes
--work. For more information on this subject, see *Note Processes::.
--
-- The `kill' function is declared in `signal.h'.
--
-- - Function: int kill (pid_t PID, int SIGNUM)
-- The `kill' function sends the signal SIGNUM to the process or
-- process group specified by PID. Besides the signals listed in
-- *Note Standard Signals::, SIGNUM can also have a value of zero to
-- check the validity of the PID.
--
-- The PID specifies the process or process group to receive the
-- signal:
--
-- `PID > 0'
-- The process whose identifier is PID.
--
-- `PID == 0'
-- All processes in the same process group as the sender.
--
-- `PID < -1'
-- The process group whose identifier is -PID.
--
-- `PID == -1'
-- If the process is privileged, send the signal to all
-- processes except for some special system processes.
-- Otherwise, send the signal to all processes with the same
-- effective user ID.
--
-- A process can send a signal SIGNUM to itself with a call like
-- `kill (getpid(), SIGNUM)'. If `kill' is used by a process to send
-- a signal to itself, and the signal is not blocked, then `kill'
-- delivers at least one signal (which might be some other pending
-- unblocked signal instead of the signal SIGNUM) to that process
-- before it returns.
--
-- The return value from `kill' is zero if the signal can be sent
-- successfully. Otherwise, no signal is sent, and a value of `-1' is
-- returned. If PID specifies sending a signal to several processes,
-- `kill' succeeds if it can send the signal to at least one of them.
-- There's no way you can tell which of the processes got the signal
-- or whether all of them did.
--
-- The following `errno' error conditions are defined for this
-- function:
--
-- `EINVAL'
-- The SIGNUM argument is an invalid or unsupported number.
--
-- `EPERM'
-- You do not have the privilege to send a signal to the process
-- or any of the processes in the process group named by PID.
--
-- `ESCRH'
-- The PID argument does not refer to an existing process or
-- group.
--
-- - Function: int killpg (int PGID, int SIGNUM)
-- This is similar to `kill', but sends signal SIGNUM to the process
-- group PGID. This function is provided for compatibility with BSD;
-- using `kill' to do this is more portable.
--
-- As a simple example of `kill', the call `kill (getpid (), SIG)' has
--the same effect as `raise (SIG)'.
--
--
--File: libc.info, Node: Permission for kill, Next: Kill Example, Prev:
Signaling Another Process, Up: Generating Signals
--
--Permission for using `kill'
-----------------------------
--
-- There are restrictions that prevent you from using `kill' to send
--signals to any random process. These are intended to prevent antisocial
--behavior such as arbitrarily killing off processes belonging to another
--user. In typical use, `kill' is used to pass signals between parent,
--child, and sibling processes, and in these situations you normally do
--have permission to send signals. The only common exception is when you
--run a setuid program in a child process; if the program changes its
--real UID as well as its effective UID, you may not have permission to
--send a signal. The `su' program does this.
--
-- Whether a process has permission to send a signal to another process
--is determined by the user IDs of the two processes. This concept is
--discussed in detail in *Note Process Persona::.
--
-- Generally, for a process to be able to send a signal to another
--process, either the sending process must belong to a privileged user
--(like `root'), or the real or effective user ID of the sending process
--must match the real or effective user ID of the receiving process. If
--the receiving process has changed its effective user ID from the
--set-user-ID mode bit on its process image file, then the owner of the
--process image file is used in place of its current effective user ID.
--In some implementations, a parent process might be able to send signals
--to a child process even if the user ID's don't match, and other
--implementations might enforce other restrictions.
--
-- The `SIGCONT' signal is a special case. It can be sent if the
--sender is part of the same session as the receiver, regardless of user
--IDs.
--
--
--File: libc.info, Node: Kill Example, Prev: Permission for kill, Up:
Generating Signals
--
--Using `kill' for Communication
--------------------------------
--
-- Here is a longer example showing how signals can be used for
--interprocess communication. This is what the `SIGUSR1' and `SIGUSR2'
--signals are provided for. Since these signals are fatal by default,
--the process that is supposed to receive them must trap them through
--`signal' or `sigaction'.
--
-- In this example, a parent process forks a child process and then
--waits for the child to complete its initialization. The child process
--tells the parent when it is ready by sending it a `SIGUSR1' signal,
--using the `kill' function.
--
-- #include <signal.h>
-- #include <stdio.h>
-- #include <sys/types.h>
-- #include <unistd.h>
--
-- /* When a `SIGUSR1' signal arrives, set this variable. */
-- volatile sig_atomic_t usr_interrupt = 0;
--
-- void
-- synch_signal (int sig)
-- {
-- usr_interrupt = 1;
-- }
--
-- /* The child process executes this function. */
-- void
-- child_function (void)
-- {
-- /* Perform initialization. */
-- printf ("I'm here!!! My pid is %d.\n", (int) getpid ());
--
-- /* Let parent know you're done. */
-- kill (getppid (), SIGUSR1);
--
-- /* Continue with execution. */
-- puts ("Bye, now....");
-- exit (0);
-- }
--
-- int
-- main (void)
-- {
-- struct sigaction usr_action;
-- sigset_t block_mask;
-- pid_t child_id;
--
-- /* Establish the signal handler. */
-- sigfillset (&block_mask);
-- usr_action.sa_handler = synch_signal;
-- usr_action.sa_mask = block_mask;
-- usr_action.sa_flags = 0;
-- sigaction (SIGUSR1, &usr_action, NULL);
--
-- /* Create the child process. */
-- child_id = fork ();
-- if (child_id == 0)
-- child_function (); /* Does not return. */
-- /* Busy wait for the child to send a signal. */
-- while (!usr_interrupt)
-- ;
--
-- /* Now continue execution. */
-- puts ("That's all, folks!");
--
-- return 0;
-- }
--
-- This example uses a busy wait, which is bad, because it wastes CPU
--cycles that other programs could otherwise use. It is better to ask the
--system to wait until the signal arrives. See the example in *Note
--Waiting for a Signal::.
--
--
--File: libc.info, Node: Blocking Signals, Next: Waiting for a Signal, Prev:
Generating Signals, Up: Signal Handling
--
--Blocking Signals
--================
--
-- Blocking a signal means telling the operating system to hold it and
--deliver it later. Generally, a program does not block signals
--indefinitely--it might as well ignore them by setting their actions to
--`SIG_IGN'. But it is useful to block signals briefly, to prevent them
--from interrupting sensitive operations. For instance:
--
-- * You can use the `sigprocmask' function to block signals while you
-- modify global variables that are also modified by the handlers for
-- these signals.
--
-- * You can set `sa_mask' in your `sigaction' call to block certain
-- signals while a particular signal handler runs. This way, the
-- signal handler can run without being interrupted itself by signals.
--
--* Menu:
--
--* Why Block:: The purpose of blocking signals.
--* Signal Sets:: How to specify which signals to
-- block.
--* Process Signal Mask:: Blocking delivery of signals to your
-- process during normal execution.
--* Testing for Delivery:: Blocking to Test for Delivery of
-- a Signal.
--* Blocking for Handler:: Blocking additional signals while a
-- handler is being run.
--* Checking for Pending Signals:: Checking for Pending Signals
--* Remembering a Signal:: How you can get almost the same
-- effect as blocking a signal, by
-- handling it and setting a flag
-- to be tested later.
--
--
--File: libc.info, Node: Why Block, Next: Signal Sets, Up: Blocking Signals
--
--Why Blocking Signals is Useful
--------------------------------
--
-- Temporary blocking of signals with `sigprocmask' gives you a way to
--prevent interrupts during critical parts of your code. If signals
--arrive in that part of the program, they are delivered later, after you
--unblock them.
--
-- One example where this is useful is for sharing data between a signal
--handler and the rest of the program. If the type of the data is not
--`sig_atomic_t' (*note Atomic Data Access::.), then the signal handler
--could run when the rest of the program has only half finished reading
--or writing the data. This would lead to confusing consequences.
--
-- To make the program reliable, you can prevent the signal handler from
--running while the rest of the program is examining or modifying that
--data--by blocking the appropriate signal around the parts of the
--program that touch the data.
--
-- Blocking signals is also necessary when you want to perform a certain
--action only if a signal has not arrived. Suppose that the handler for
--the signal sets a flag of type `sig_atomic_t'; you would like to test
--the flag and perform the action if the flag is not set. This is
--unreliable. Suppose the signal is delivered immediately after you test
--the flag, but before the consequent action: then the program will
--perform the action even though the signal has arrived.
--
-- The only way to test reliably for whether a signal has yet arrived
--is to test while the signal is blocked.
--
--
--File: libc.info, Node: Signal Sets, Next: Process Signal Mask, Prev: Why
Block, Up: Blocking Signals
--
--Signal Sets
-------------
--
-- All of the signal blocking functions use a data structure called a
--"signal set" to specify what signals are affected. Thus, every
--activity involves two stages: creating the signal set, and then passing
--it as an argument to a library function.
--
-- These facilities are declared in the header file `signal.h'.
--
-- - Data Type: sigset_t
-- The `sigset_t' data type is used to represent a signal set.
-- Internally, it may be implemented as either an integer or structure
-- type.
--
-- For portability, use only the functions described in this section
-- to initialize, change, and retrieve information from `sigset_t'
-- objects--don't try to manipulate them directly.
--
-- There are two ways to initialize a signal set. You can initially
--specify it to be empty with `sigemptyset' and then add specified
--signals individually. Or you can specify it to be full with
--`sigfillset' and then delete specified signals individually.
--
-- You must always initialize the signal set with one of these two
--functions before using it in any other way. Don't try to set all the
--signals explicitly because the `sigset_t' object might include some
--other information (like a version field) that needs to be initialized as
--well. (In addition, it's not wise to put into your program an
--assumption that the system has no signals aside from the ones you know
--about.)
--
-- - Function: int sigemptyset (sigset_t *SET)
-- This function initializes the signal set SET to exclude all of the
-- defined signals. It always returns `0'.
--
-- - Function: int sigfillset (sigset_t *SET)
-- This function initializes the signal set SET to include all of the
-- defined signals. Again, the return value is `0'.
--
-- - Function: int sigaddset (sigset_t *SET, int SIGNUM)
-- This function adds the signal SIGNUM to the signal set SET. All
-- `sigaddset' does is modify SET; it does not block or unblock any
-- signals.
--
-- The return value is `0' on success and `-1' on failure. The
-- following `errno' error condition is defined for this function:
--
-- `EINVAL'
-- The SIGNUM argument doesn't specify a valid signal.
--
-- - Function: int sigdelset (sigset_t *SET, int SIGNUM)
-- This function removes the signal SIGNUM from the signal set SET.
-- All `sigdelset' does is modify SET; it does not block or unblock
-- any signals. The return value and error conditions are the same
-- as for `sigaddset'.
--
-- Finally, there is a function to test what signals are in a signal
--set:
--
-- - Function: int sigismember (const sigset_t *SET, int SIGNUM)
-- The `sigismember' function tests whether the signal SIGNUM is a
-- member of the signal set SET. It returns `1' if the signal is in
-- the set, `0' if not, and `-1' if there is an error.
--
-- The following `errno' error condition is defined for this function:
--
-- `EINVAL'
-- The SIGNUM argument doesn't specify a valid signal.
--
--
--File: libc.info, Node: Process Signal Mask, Next: Testing for Delivery,
Prev: Signal Sets, Up: Blocking Signals
--
--Process Signal Mask
---------------------
--
-- The collection of signals that are currently blocked is called the
--"signal mask". Each process has its own signal mask. When you create
--a new process (*note Creating a Process::.), it inherits its parent's
--mask. You can block or unblock signals with total flexibility by
--modifying the signal mask.
--
-- The prototype for the `sigprocmask' function is in `signal.h'.
--
-- - Function: int sigprocmask (int HOW, const sigset_t *SET, sigset_t
-- *OLDSET)
-- The `sigprocmask' function is used to examine or change the calling
-- process's signal mask. The HOW argument determines how the signal
-- mask is changed, and must be one of the following values:
--
-- `SIG_BLOCK'
-- Block the signals in `set'--add them to the existing mask. In
-- other words, the new mask is the union of the existing mask
-- and SET.
--
-- `SIG_UNBLOCK'
-- Unblock the signals in SET--remove them from the existing
-- mask.
--
-- `SIG_SETMASK'
-- Use SET for the mask; ignore the previous value of the mask.
--
-- The last argument, OLDSET, is used to return information about the
-- old process signal mask. If you just want to change the mask
-- without looking at it, pass a null pointer as the OLDSET argument.
-- Similarly, if you want to know what's in the mask without changing
-- it, pass a null pointer for SET (in this case the HOW argument is
-- not significant). The OLDSET argument is often used to remember
-- the previous signal mask in order to restore it later. (Since the
-- signal mask is inherited over `fork' and `exec' calls, you can't
-- predict what its contents are when your program starts running.)
--
-- If invoking `sigprocmask' causes any pending signals to be
-- unblocked, at least one of those signals is delivered to the
-- process before `sigprocmask' returns. The order in which pending
-- signals are delivered is not specified, but you can control the
-- order explicitly by making multiple `sigprocmask' calls to unblock
-- various signals one at a time.
--
-- The `sigprocmask' function returns `0' if successful, and `-1' to
-- indicate an error. The following `errno' error conditions are
-- defined for this function:
--
-- `EINVAL'
-- The HOW argument is invalid.
--
-- You can't block the `SIGKILL' and `SIGSTOP' signals, but if the
-- signal set includes these, `sigprocmask' just ignores them instead
-- of returning an error status.
--
-- Remember, too, that blocking program error signals such as `SIGFPE'
-- leads to undesirable results for signals generated by an actual
-- program error (as opposed to signals sent with `raise' or `kill').
-- This is because your program may be too broken to be able to
-- continue executing to a point where the signal is unblocked again.
-- *Note Program Error Signals::.
--
--
--File: libc.info, Node: Testing for Delivery, Next: Blocking for Handler,
Prev: Process Signal Mask, Up: Blocking Signals
--
--Blocking to Test for Delivery of a Signal
-------------------------------------------
--
-- Now for a simple example. Suppose you establish a handler for
--`SIGALRM' signals that sets a flag whenever a signal arrives, and your
--main program checks this flag from time to time and then resets it.
--You can prevent additional `SIGALRM' signals from arriving in the
--meantime by wrapping the critical part of the code with calls to
--`sigprocmask', like this:
--
-- /* This variable is set by the SIGALRM signal handler. */
-- volatile sig_atomic_t flag = 0;
--
-- int
-- main (void)
-- {
-- sigset_t block_alarm;
--
-- ...
--
-- /* Initialize the signal mask. */
-- sigemptyset (&block_alarm);
-- sigaddset (&block_alarm, SIGALRM);
-- while (1)
-- {
-- /* Check if a signal has arrived; if so, reset the flag. */
-- sigprocmask (SIG_BLOCK, &block_alarm, NULL);
-- if (flag)
-- {
-- ACTIONS-IF-NOT-ARRIVED
-- flag = 0;
-- }
-- sigprocmask (SIG_UNBLOCK, &block_alarm, NULL);
--
-- ...
-- }
-- }
--
--
--File: libc.info, Node: Blocking for Handler, Next: Checking for Pending
Signals, Prev: Testing for Delivery, Up: Blocking Signals
--
--Blocking Signals for a Handler
--------------------------------
--
-- When a signal handler is invoked, you usually want it to be able to
--finish without being interrupted by another signal. From the moment the
--handler starts until the moment it finishes, you must block signals that
--might confuse it or corrupt its data.
--
-- When a handler function is invoked on a signal, that signal is
--automatically blocked (in addition to any other signals that are already
--in the process's signal mask) during the time the handler is running.
--If you set up a handler for `SIGTSTP', for instance, then the arrival
--of that signal forces further `SIGTSTP' signals to wait during the
--execution of the handler.
--
-- However, by default, other kinds of signals are not blocked; they can
--arrive during handler execution.
--
-- The reliable way to block other kinds of signals during the
--execution of the handler is to use the `sa_mask' member of the
--`sigaction' structure.
--
-- Here is an example:
--
-- #include <signal.h>
-- #include <stddef.h>
--
-- void catch_stop ();
--
-- void
-- install_handler (void)
-- {
-- struct sigaction setup_action;
-- sigset_t block_mask;
--
-- sigemptyset (&block_mask);
-- /* Block other terminal-generated signals while handler runs. */
-- sigaddset (&block_mask, SIGINT);
-- sigaddset (&block_mask, SIGQUIT);
-- setup_action.sa_handler = catch_stop;
-- setup_action.sa_mask = block_mask;
-- setup_action.sa_flags = 0;
-- sigaction (SIGTSTP, &setup_action, NULL);
-- }
--
-- This is more reliable than blocking the other signals explicitly in
--the code for the handler. If you block signals explicitly in the
--handler, you can't avoid at least a short interval at the beginning of
--the handler where they are not yet blocked.
--
-- You cannot remove signals from the process's current mask using this
--mechanism. However, you can make calls to `sigprocmask' within your
--handler to block or unblock signals as you wish.
--
-- In any case, when the handler returns, the system restores the mask
--that was in place before the handler was entered. If any signals that
--become unblocked by this restoration are pending, the process will
--receive those signals immediately, before returning to the code that was
--interrupted.
--
--
--File: libc.info, Node: Checking for Pending Signals, Next: Remembering a
Signal, Prev: Blocking for Handler, Up: Blocking Signals
--
--Checking for Pending Signals
------------------------------
--
-- You can find out which signals are pending at any time by calling
--`sigpending'. This function is declared in `signal.h'.
--
-- - Function: int sigpending (sigset_t *SET)
-- The `sigpending' function stores information about pending signals
-- in SET. If there is a pending signal that is blocked from
-- delivery, then that signal is a member of the returned set. (You
-- can test whether a particular signal is a member of this set using
-- `sigismember'; see *Note Signal Sets::.)
--
-- The return value is `0' if successful, and `-1' on failure.
--
-- Testing whether a signal is pending is not often useful. Testing
--when that signal is not blocked is almost certainly bad design.
--
-- Here is an example.
--
-- #include <signal.h>
-- #include <stddef.h>
--
-- sigset_t base_mask, waiting_mask;
--
-- sigemptyset (&base_mask);
-- sigaddset (&base_mask, SIGINT);
-- sigaddset (&base_mask, SIGTSTP);
--
-- /* Block user interrupts while doing other processing. */
-- sigprocmask (SIG_SETMASK, &base_mask, NULL);
-- ...
--
-- /* After a while, check to see whether any signals are pending. */
-- sigpending (&waiting_mask);
-- if (sigismember (&waiting_mask, SIGINT)) {
-- /* User has tried to kill the process. */
-- }
-- else if (sigismember (&waiting_mask, SIGTSTP)) {
-- /* User has tried to stop the process. */
-- }
--
-- Remember that if there is a particular signal pending for your
--process, additional signals of that same type that arrive in the
--meantime might be discarded. For example, if a `SIGINT' signal is
--pending when another `SIGINT' signal arrives, your program will
--probably only see one of them when you unblock this signal.
--
-- *Portability Note:* The `sigpending' function is new in POSIX.1.
--Older systems have no equivalent facility.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-22
glibc-2.0.1/manual/libc.info-22
---- ../glibc-2.0.1/manual/libc.info-22 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-22 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1247 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Remembering a Signal, Prev: Checking for Pending
Signals, Up: Blocking Signals
--
--Remembering a Signal to Act On Later
--------------------------------------
--
-- Instead of blocking a signal using the library facilities, you can
--get almost the same results by making the handler set a flag to be
--tested later, when you "unblock". Here is an example:
--
-- /* If this flag is nonzero, don't handle the signal right away. */
-- volatile sig_atomic_t signal_pending;
--
-- /* This is nonzero if a signal arrived and was not handled. */
-- volatile sig_atomic_t defer_signal;
--
-- void
-- handler (int signum)
-- {
-- if (defer_signal)
-- signal_pending = signum;
-- else
-- ... /* "Really" handle the signal. */
-- }
--
-- ...
--
-- void
-- update_mumble (int frob)
-- {
-- /* Prevent signals from having immediate effect. */
-- defer_signal++;
-- /* Now update `mumble', without worrying about interruption. */
-- mumble.a = 1;
-- mumble.b = hack ();
-- mumble.c = frob;
-- /* We have updated `mumble'. Handle any signal that came in. */
-- defer_signal--;
-- if (defer_signal == 0 && signal_pending != 0)
-- raise (signal_pending);
-- }
--
-- Note how the particular signal that arrives is stored in
--`signal_pending'. That way, we can handle several types of
--inconvenient signals with the same mechanism.
--
-- We increment and decrement `defer_signal' so that nested critical
--sections will work properly; thus, if `update_mumble' were called with
--`signal_pending' already nonzero, signals would be deferred not only
--within `update_mumble', but also within the caller. This is also why
--we do not check `signal_pending' if `defer_signal' is still nonzero.
--
-- The incrementing and decrementing of `defer_signal' require more
--than one instruction; it is possible for a signal to happen in the
--middle. But that does not cause any problem. If the signal happens
--early enough to see the value from before the increment or decrement,
--that is equivalent to a signal which came before the beginning of the
--increment or decrement, which is a case that works properly.
--
-- It is absolutely vital to decrement `defer_signal' before testing
--`signal_pending', because this avoids a subtle bug. If we did these
--things in the other order, like this,
--
-- if (defer_signal == 1 && signal_pending != 0)
-- raise (signal_pending);
-- defer_signal--;
--
--then a signal arriving in between the `if' statement and the decrement
--would be effectively "lost" for an indefinite amount of time. The
--handler would merely set `defer_signal', but the program having already
--tested this variable, it would not test the variable again.
--
-- Bugs like these are called "timing errors". They are especially bad
--because they happen only rarely and are nearly impossible to reproduce.
--You can't expect to find them with a debugger as you would find a
--reproducible bug. So it is worth being especially careful to avoid
--them.
--
-- (You would not be tempted to write the code in this order, given the
--use of `defer_signal' as a counter which must be tested along with
--`signal_pending'. After all, testing for zero is cleaner than testing
--for one. But if you did not use `defer_signal' as a counter, and gave
--it values of zero and one only, then either order might seem equally
--simple. This is a further advantage of using a counter for
--`defer_signal': it will reduce the chance you will write the code in
--the wrong order and create a subtle bug.)
--
--
--File: libc.info, Node: Waiting for a Signal, Next: Signal Stack, Prev:
Blocking Signals, Up: Signal Handling
--
--Waiting for a Signal
--====================
--
-- If your program is driven by external events, or uses signals for
--synchronization, then when it has nothing to do it should probably wait
--until a signal arrives.
--
--* Menu:
--
--* Using Pause:: The simple way, using `pause'.
--* Pause Problems:: Why the simple way is often not very good.
--* Sigsuspend:: Reliably waiting for a specific signal.
--
--
--File: libc.info, Node: Using Pause, Next: Pause Problems, Up: Waiting for
a Signal
--
--Using `pause'
---------------
--
-- The simple way to wait until a signal arrives is to call `pause'.
--Please read about its disadvantages, in the following section, before
--you use it.
--
-- - Function: int pause ()
-- The `pause' function suspends program execution until a signal
-- arrives whose action is either to execute a handler function, or to
-- terminate the process.
--
-- If the signal causes a handler function to be executed, then
-- `pause' returns. This is considered an unsuccessful return (since
-- "successful" behavior would be to suspend the program forever), so
-- the return value is `-1'. Even if you specify that other
-- primitives should resume when a system handler returns (*note
-- Interrupted Primitives::.), this has no effect on `pause'; it
-- always fails when a signal is handled.
--
-- The following `errno' error conditions are defined for this
-- function:
--
-- `EINTR'
-- The function was interrupted by delivery of a signal.
--
-- If the signal causes program termination, `pause' doesn't return
-- (obviously).
--
-- The `pause' function is declared in `unistd.h'.
--
--
--File: libc.info, Node: Pause Problems, Next: Sigsuspend, Prev: Using
Pause, Up: Waiting for a Signal
--
--Problems with `pause'
-----------------------
--
-- The simplicity of `pause' can conceal serious timing errors that can
--make a program hang mysteriously.
--
-- It is safe to use `pause' if the real work of your program is done
--by the signal handlers themselves, and the "main program" does nothing
--but call `pause'. Each time a signal is delivered, the handler will do
--the next batch of work that is to be done, and then return, so that the
--main loop of the program can call `pause' again.
--
-- You can't safely use `pause' to wait until one more signal arrives,
--and then resume real work. Even if you arrange for the signal handler
--to cooperate by setting a flag, you still can't use `pause' reliably.
--Here is an example of this problem:
--
-- /* `usr_interrupt' is set by the signal handler. */
-- if (!usr_interrupt)
-- pause ();
--
-- /* Do work once the signal arrives. */
-- ...
--
--This has a bug: the signal could arrive after the variable
--`usr_interrupt' is checked, but before the call to `pause'. If no
--further signals arrive, the process would never wake up again.
--
-- You can put an upper limit on the excess waiting by using `sleep' in
--a loop, instead of using `pause'. (*Note Sleeping::, for more about
--`sleep'.) Here is what this looks like:
--
-- /* `usr_interrupt' is set by the signal handler.
-- while (!usr_interrupt)
-- sleep (1);
--
-- /* Do work once the signal arrives. */
-- ...
--
-- For some purposes, that is good enough. But with a little more
--complexity, you can wait reliably until a particular signal handler is
--run, using `sigsuspend'. *Note Sigsuspend::.
--
--
--File: libc.info, Node: Sigsuspend, Prev: Pause Problems, Up: Waiting for a
Signal
--
--Using `sigsuspend'
--------------------
--
-- The clean and reliable way to wait for a signal to arrive is to
--block it and then use `sigsuspend'. By using `sigsuspend' in a loop,
--you can wait for certain kinds of signals, while letting other kinds of
--signals be handled by their handlers.
--
-- - Function: int sigsuspend (const sigset_t *SET)
-- This function replaces the process's signal mask with SET and then
-- suspends the process until a signal is delivered whose action is
-- either to terminate the process or invoke a signal handling
-- function. In other words, the program is effectively suspended
-- until one of the signals that is not a member of SET arrives.
--
-- If the process is woken up by deliver of a signal that invokes a
-- handler function, and the handler function returns, then
-- `sigsuspend' also returns.
--
-- The mask remains SET only as long as `sigsuspend' is waiting. The
-- function `sigsuspend' always restores the previous signal mask
-- when it returns.
--
-- The return value and error conditions are the same as for `pause'.
--
-- With `sigsuspend', you can replace the `pause' or `sleep' loop in
--the previous section with something completely reliable:
--
-- sigset_t mask, oldmask;
--
-- ...
--
-- /* Set up the mask of signals to temporarily block. */
-- sigemptyset (&mask);
-- sigaddset (&mask, SIGUSR1);
--
-- ...
--
-- /* Wait for a signal to arrive. */
-- sigprocmask (SIG_BLOCK, &mask, &oldmask);
-- while (!usr_interrupt)
-- sigsuspend (&oldmask);
-- sigprocmask (SIG_UNBLOCK, &mask, NULL);
--
-- This last piece of code is a little tricky. The key point to
--remember here is that when `sigsuspend' returns, it resets the process's
--signal mask to the original value, the value from before the call to
--`sigsuspend'--in this case, the `SIGUSR1' signal is once again blocked.
--The second call to `sigprocmask' is necessary to explicitly unblock
--this signal.
--
-- One other point: you may be wondering why the `while' loop is
--necessary at all, since the program is apparently only waiting for one
--`SIGUSR1' signal. The answer is that the mask passed to `sigsuspend'
--permits the process to be woken up by the delivery of other kinds of
--signals, as well--for example, job control signals. If the process is
--woken up by a signal that doesn't set `usr_interrupt', it just suspends
--itself again until the "right" kind of signal eventually arrives.
--
-- This technique takes a few more lines of preparation, but that is
--needed just once for each kind of wait criterion you want to use. The
--code that actually waits is just four lines.
--
--
--File: libc.info, Node: Signal Stack, Next: BSD Signal Handling, Prev:
Waiting for a Signal, Up: Signal Handling
--
--Using a Separate Signal Stack
--=============================
--
-- A signal stack is a special area of memory to be used as the
--execution stack during signal handlers. It should be fairly large, to
--avoid any danger that it will overflow in turn; the macro `SIGSTKSZ' is
--defined to a canonical size for signal stacks. You can use `malloc' to
--allocate the space for the stack. Then call `sigaltstack' or
--`sigstack' to tell the system to use that space for the signal stack.
--
-- You don't need to write signal handlers differently in order to use a
--signal stack. Switching from one stack to the other happens
--automatically. (Some non-GNU debuggers on some machines may get
--confused if you examine a stack trace while a handler that uses the
--signal stack is running.)
--
-- There are two interfaces for telling the system to use a separate
--signal stack. `sigstack' is the older interface, which comes from 4.2
--BSD. `sigaltstack' is the newer interface, and comes from 4.4 BSD.
--The `sigaltstack' interface has the advantage that it does not require
--your program to know which direction the stack grows, which depends on
--the specific machine and operating system.
--
-- - Data Type: struct sigaltstack
-- This structure describes a signal stack. It contains the
-- following members:
--
-- `void *ss_sp'
-- This points to the base of the signal stack.
--
-- `size_t ss_size'
-- This is the size (in bytes) of the signal stack which `ss_sp'
-- points to. You should set this to however much space you
-- allocated for the stack.
--
-- There are two macros defined in `signal.h' that you should
-- use in calculating this size:
--
-- `SIGSTKSZ'
-- This is the canonical size for a signal stack. It is
-- judged to be sufficient for normal uses.
--
-- `MINSIGSTKSZ'
-- This is the amount of signal stack space the operating
-- system needs just to implement signal delivery. The
-- size of a signal stack *must* be greater than this.
--
-- For most cases, just using `SIGSTKSZ' for `ss_size' is
-- sufficient. But if you know how much stack space your
-- program's signal handlers will need, you may want to use
-- a different size. In this case, you should allocate
-- `MINSIGSTKSZ' additional bytes for the signal stack and
-- increase `ss_size' accordingly.
--
-- `int ss_flags'
-- This field contains the bitwise OR of these flags:
--
-- `SA_DISABLE'
-- This tells the system that it should not use the signal
-- stack.
--
-- `SA_ONSTACK'
-- This is set by the system, and indicates that the signal
-- stack is currently in use. If this bit is not set, then
-- signals will be delivered on the normal user stack.
--
-- - Function: int sigaltstack (const struct sigaltstack *STACK, struct
-- sigaltstack *OLDSTACK)
-- The `sigaltstack' function specifies an alternate stack for use
-- during signal handling. When a signal is received by the process
-- and its action indicates that the signal stack is used, the system
-- arranges a switch to the currently installed signal stack while
-- the handler for that signal is executed.
--
-- If OLDSTACK is not a null pointer, information about the currently
-- installed signal stack is returned in the location it points to.
-- If STACK is not a null pointer, then this is installed as the new
-- stack for use by signal handlers.
--
-- The return value is `0' on success and `-1' on failure. If
-- `sigaltstack' fails, it sets `errno' to one of these values:
--
-- `'
-- `EINVAL'
-- You tried to disable a stack that was in fact currently in
-- use.
--
-- `ENOMEM'
-- The size of the alternate stack was too small. It must be
-- greater than `MINSIGSTKSZ'.
--
-- Here is the older `sigstack' interface. You should use
--`sigaltstack' instead on systems that have it.
--
-- - Data Type: struct sigstack
-- This structure describes a signal stack. It contains the
-- following members:
--
-- `void *ss_sp'
-- This is the stack pointer. If the stack grows downwards on
-- your machine, this should point to the top of the area you
-- allocated. If the stack grows upwards, it should point to
-- the bottom.
--
-- `int ss_onstack'
-- This field is true if the process is currently using this
-- stack.
--
-- - Function: int sigstack (const struct sigstack *STACK, struct
-- sigstack *OLDSTACK)
-- The `sigstack' function specifies an alternate stack for use during
-- signal handling. When a signal is received by the process and its
-- action indicates that the signal stack is used, the system
-- arranges a switch to the currently installed signal stack while
-- the handler for that signal is executed.
--
-- If OLDSTACK is not a null pointer, information about the currently
-- installed signal stack is returned in the location it points to.
-- If STACK is not a null pointer, then this is installed as the new
-- stack for use by signal handlers.
--
-- The return value is `0' on success and `-1' on failure.
--
--
--File: libc.info, Node: BSD Signal Handling, Prev: Signal Stack, Up: Signal
Handling
--
--BSD Signal Handling
--===================
--
-- This section describes alternative signal handling functions derived
--from BSD Unix. These facilities were an advance, in their time; today,
--they are mostly obsolete, and supported mainly for compatibility with
--BSD Unix.
--
-- There are many similarities between the BSD and POSIX signal handling
--facilities, because the POSIX facilities were inspired by the BSD
--facilities. Besides having different names for all the functions to
--avoid conflicts, the main differences between the two are:
--
-- * BSD Unix represents signal masks as an `int' bit mask, rather than
-- as a `sigset_t' object.
--
-- * The BSD facilities use a different default for whether an
-- interrupted primitive should fail or resume. The POSIX facilities
-- make system calls fail unless you specify that they should resume.
-- With the BSD facility, the default is to make system calls resume
-- unless you say they should fail. *Note Interrupted Primitives::.
--
-- The BSD facilities are declared in `signal.h'.
--
--* Menu:
--
--* BSD Handler:: BSD Function to Establish a Handler.
--* Blocking in BSD:: BSD Functions for Blocking Signals.
--
--
--File: libc.info, Node: BSD Handler, Next: Blocking in BSD, Up: BSD Signal
Handling
--
--BSD Function to Establish a Handler
-------------------------------------
--
-- - Data Type: struct sigvec
-- This data type is the BSD equivalent of `struct sigaction' (*note
-- Advanced Signal Handling::.); it is used to specify signal actions
-- to the `sigvec' function. It contains the following members:
--
-- `sighandler_t sv_handler'
-- This is the handler function.
--
-- `int sv_mask'
-- This is the mask of additional signals to be blocked while
-- the handler function is being called.
--
-- `int sv_flags'
-- This is a bit mask used to specify various flags which affect
-- the behavior of the signal. You can also refer to this field
-- as `sv_onstack'.
--
-- These symbolic constants can be used to provide values for the
--`sv_flags' field of a `sigvec' structure. This field is a bit mask
--value, so you bitwise-OR the flags of interest to you together.
--
-- - Macro: int SV_ONSTACK
-- If this bit is set in the `sv_flags' field of a `sigvec'
-- structure, it means to use the signal stack when delivering the
-- signal.
--
-- - Macro: int SV_INTERRUPT
-- If this bit is set in the `sv_flags' field of a `sigvec'
-- structure, it means that system calls interrupted by this kind of
-- signal should not be restarted if the handler returns; instead,
-- the system calls should return with a `EINTR' error status. *Note
-- Interrupted Primitives::.
--
-- - Macro: int SV_RESETHAND
-- If this bit is set in the `sv_flags' field of a `sigvec'
-- structure, it means to reset the action for the signal back to
-- `SIG_DFL' when the signal is received.
--
-- - Function: int sigvec (int SIGNUM, const struct sigvec *ACTION,struct
-- sigvec *OLD-ACTION)
-- This function is the equivalent of `sigaction' (*note Advanced
-- Signal Handling::.); it installs the action ACTION for the signal
-- SIGNUM, returning information about the previous action in effect
-- for that signal in OLD-ACTION.
--
-- - Function: int siginterrupt (int SIGNUM, int FAILFLAG)
-- This function specifies which approach to use when certain
-- primitives are interrupted by handling signal SIGNUM. If FAILFLAG
-- is false, signal SIGNUM restarts primitives. If FAILFLAG is true,
-- handling SIGNUM causes these primitives to fail with error code
-- `EINTR'. *Note Interrupted Primitives::.
--
--
--File: libc.info, Node: Blocking in BSD, Prev: BSD Handler, Up: BSD Signal
Handling
--
--BSD Functions for Blocking Signals
------------------------------------
--
-- - Macro: int sigmask (int SIGNUM)
-- This macro returns a signal mask that has the bit for signal SIGNUM
-- set. You can bitwise-OR the results of several calls to `sigmask'
-- together to specify more than one signal. For example,
--
-- (sigmask (SIGTSTP) | sigmask (SIGSTOP)
-- | sigmask (SIGTTIN) | sigmask (SIGTTOU))
--
-- specifies a mask that includes all the job-control stop signals.
--
-- - Function: int sigblock (int MASK)
-- This function is equivalent to `sigprocmask' (*note Process Signal
-- Mask::.) with a HOW argument of `SIG_BLOCK': it adds the signals
-- specified by MASK to the calling process's set of blocked signals.
-- The return value is the previous set of blocked signals.
--
-- - Function: int sigsetmask (int MASK)
-- This function equivalent to `sigprocmask' (*note Process Signal
-- Mask::.) with a HOW argument of `SIG_SETMASK': it sets the calling
-- process's signal mask to MASK. The return value is the previous
-- set of blocked signals.
--
-- - Function: int sigpause (int MASK)
-- This function is the equivalent of `sigsuspend' (*note Waiting for
-- a Signal::.): it sets the calling process's signal mask to MASK,
-- and waits for a signal to arrive. On return the previous set of
-- blocked signals is restored.
--
--
--File: libc.info, Node: Process Startup, Next: Processes, Prev: Signal
Handling, Up: Top
--
--Process Startup and Termination
--*******************************
--
-- "Processes" are the primitive units for allocation of system
--resources. Each process has its own address space and (usually) one
--thread of control. A process executes a program; you can have multiple
--processes executing the same program, but each process has its own copy
--of the program within its own address space and executes it
--independently of the other copies.
--
-- This chapter explains what your program should do to handle the
--startup of a process, to terminate its process, and to receive
--information (arguments and the environment) from the parent process.
--
--* Menu:
--
--* Program Arguments:: Parsing your program's command-line arguments.
--* Environment Variables:: How to access parameters inherited from
-- a parent process.
--* Program Termination:: How to cause a process to terminate and
-- return status information to its parent.
--
--
--File: libc.info, Node: Program Arguments, Next: Environment Variables, Up:
Process Startup
--
--Program Arguments
--=================
--
-- The system starts a C program by calling the function `main'. It is
--up to you to write a function named `main'--otherwise, you won't even
--be able to link your program without errors.
--
-- In ISO C you can define `main' either to take no arguments, or to
--take two arguments that represent the command line arguments to the
--program, like this:
--
-- int main (int ARGC, char *ARGV[])
--
-- The command line arguments are the whitespace-separated tokens given
--in the shell command used to invoke the program; thus, in `cat foo
--bar', the arguments are `foo' and `bar'. The only way a program can
--look at its command line arguments is via the arguments of `main'. If
--`main' doesn't take arguments, then you cannot get at the command line.
--
-- The value of the ARGC argument is the number of command line
--arguments. The ARGV argument is a vector of C strings; its elements
--are the individual command line argument strings. The file name of the
--program being run is also included in the vector as the first element;
--the value of ARGC counts this element. A null pointer always follows
--the last element: `ARGV[ARGC]' is this null pointer.
--
-- For the command `cat foo bar', ARGC is 3 and ARGV has three
--elements, `"cat"', `"foo"' and `"bar"'.
--
-- If the syntax for the command line arguments to your program is
--simple enough, you can simply pick the arguments off from ARGV by hand.
--But unless your program takes a fixed number of arguments, or all of the
--arguments are interpreted in the same way (as file names, for example),
--you are usually better off using `getopt' to do the parsing.
--
-- In Unix systems you can define `main' a third way, using three
--arguments:
--
-- int main (int ARGC, char *ARGV[], char *ENVP)
--
-- The first two arguments are just the same. The third argument ENVP
--gives the process's environment; it is the same as the value of
--`environ'. *Note Environment Variables::. POSIX.1 does not allow this
--three-argument form, so to be portable it is best to write `main' to
--take two arguments, and use the value of `environ'.
--
--* Menu:
--
--* Argument Syntax:: By convention, options start with a hyphen.
--* Parsing Options:: The `getopt' function.
--* Example of Getopt:: An example of parsing options with `getopt'.
--* Long Options:: GNU suggests utilities accept long-named
options.
-- Here is how to do that.
--* Long Option Example:: An example of using `getopt_long'.
--* Suboptions:: Some programs need more detailed options.
--* Suboptions Example:: This shows how it could be done for `mount'.
--
--
--File: libc.info, Node: Argument Syntax, Next: Parsing Options, Up: Program
Arguments
--
--Program Argument Syntax Conventions
-------------------------------------
--
-- POSIX recommends these conventions for command line arguments.
--`getopt' (*note Parsing Options::.) makes it easy to implement them.
--
-- * Arguments are options if they begin with a hyphen delimiter (`-').
--
-- * Multiple options may follow a hyphen delimiter in a single token if
-- the options do not take arguments. Thus, `-abc' is equivalent to
-- `-a -b -c'.
--
-- * Option names are single alphanumeric characters (as for `isalnum';
-- see *Note Classification of Characters::).
--
-- * Certain options require an argument. For example, the `-o' command
-- of the `ld' command requires an argument--an output file name.
--
-- * An option and its argument may or may not appear as separate
-- tokens. (In other words, the whitespace separating them is
-- optional.) Thus, `-o foo' and `-ofoo' are equivalent.
--
-- * Options typically precede other non-option arguments.
--
-- The implementation of `getopt' in the GNU C library normally makes
-- it appear as if all the option arguments were specified before all
-- the non-option arguments for the purposes of parsing, even if the
-- user of your program intermixed option and non-option arguments.
-- It does this by reordering the elements of the ARGV array. This
-- behavior is nonstandard; if you want to suppress it, define the
-- `_POSIX_OPTION_ORDER' environment variable. *Note Standard
-- Environment::.
--
-- * The argument `--' terminates all options; any following arguments
-- are treated as non-option arguments, even if they begin with a
-- hyphen.
--
-- * A token consisting of a single hyphen character is interpreted as
-- an ordinary non-option argument. By convention, it is used to
-- specify input from or output to the standard input and output
-- streams.
--
-- * Options may be supplied in any order, or appear multiple times.
-- The interpretation is left up to the particular application
-- program.
--
-- GNU adds "long options" to these conventions. Long options consist
--of `--' followed by a name made of alphanumeric characters and dashes.
--Option names are typically one to three words long, with hyphens to
--separate words. Users can abbreviate the option names as long as the
--abbreviations are unique.
--
-- To specify an argument for a long option, write `--NAME=VALUE'.
--This syntax enables a long option to accept an argument that is itself
--optional.
--
-- Eventually, the GNU system will provide completion for long option
--names in the shell.
--
--
--File: libc.info, Node: Parsing Options, Next: Example of Getopt, Prev:
Argument Syntax, Up: Program Arguments
--
--Parsing Program Options
-------------------------
--
-- Here are the details about how to call the `getopt' function. To
--use this facility, your program must include the header file `unistd.h'.
--
-- - Variable: int opterr
-- If the value of this variable is nonzero, then `getopt' prints an
-- error message to the standard error stream if it encounters an
-- unknown option character or an option with a missing required
-- argument. This is the default behavior. If you set this variable
-- to zero, `getopt' does not print any messages, but it still
-- returns the character `?' to indicate an error.
--
-- - Variable: int optopt
-- When `getopt' encounters an unknown option character or an option
-- with a missing required argument, it stores that option character
-- in this variable. You can use this for providing your own
-- diagnostic messages.
--
-- - Variable: int optind
-- This variable is set by `getopt' to the index of the next element
-- of the ARGV array to be processed. Once `getopt' has found all of
-- the option arguments, you can use this variable to determine where
-- the remaining non-option arguments begin. The initial value of
-- this variable is `1'.
--
-- - Variable: char * optarg
-- This variable is set by `getopt' to point at the value of the
-- option argument, for those options that accept arguments.
--
-- - Function: int getopt (int ARGC, char **ARGV, const char *OPTIONS)
-- The `getopt' function gets the next option argument from the
-- argument list specified by the ARGV and ARGC arguments. Normally
-- these values come directly from the arguments received by `main'.
--
-- The OPTIONS argument is a string that specifies the option
-- characters that are valid for this program. An option character
-- in this string can be followed by a colon (`:') to indicate that
-- it takes a required argument.
--
-- If the OPTIONS argument string begins with a hyphen (`-'), this is
-- treated specially. It permits arguments that are not options to be
-- returned as if they were associated with option character `\0'.
--
-- The `getopt' function returns the option character for the next
-- command line option. When no more option arguments are available,
-- it returns `-1'. There may still be more non-option arguments; you
-- must compare the external variable `optind' against the ARGC
-- parameter to check this.
--
-- If the option has an argument, `getopt' returns the argument by
-- storing it in the variable OPTARG. You don't ordinarily need to
-- copy the `optarg' string, since it is a pointer into the original
-- ARGV array, not into a static area that might be overwritten.
--
-- If `getopt' finds an option character in ARGV that was not
-- included in OPTIONS, or a missing option argument, it returns `?'
-- and sets the external variable `optopt' to the actual option
-- character. If the first character of OPTIONS is a colon (`:'),
-- then `getopt' returns `:' instead of `?' to indicate a missing
-- option argument. In addition, if the external variable `opterr'
-- is nonzero (which is the default), `getopt' prints an error
-- message.
--
--
--File: libc.info, Node: Example of Getopt, Next: Long Options, Prev:
Parsing Options, Up: Program Arguments
--
--Example of Parsing Arguments with `getopt'
--------------------------------------------
--
-- Here is an example showing how `getopt' is typically used. The key
--points to notice are:
--
-- * Normally, `getopt' is called in a loop. When `getopt' returns
-- `-1', indicating no more options are present, the loop terminates.
--
-- * A `switch' statement is used to dispatch on the return value from
-- `getopt'. In typical use, each case just sets a variable that is
-- used later in the program.
--
-- * A second loop is used to process the remaining non-option
-- arguments.
--
-- #include <unistd.h>
-- #include <stdio.h>
--
-- int
-- main (int argc, char **argv)
-- {
-- int aflag = 0;
-- int bflag = 0;
-- char *cvalue = NULL;
-- int index;
-- int c;
--
-- opterr = 0;
--
-- while ((c = getopt (argc, argv, "abc:")) != -1)
-- switch (c)
-- {
-- case 'a':
-- aflag = 1;
-- break;
-- case 'b':
-- bflag = 1;
-- break;
-- case 'c':
-- cvalue = optarg;
-- break;
-- case '?':
-- if (isprint (optopt))
-- fprintf (stderr, "Unknown option `-%c'.\n", optopt);
-- else
-- fprintf (stderr,
-- "Unknown option character `\\x%x'.\n",
-- optopt);
-- return 1;
-- default:
-- abort ();
-- }
--
-- printf ("aflag = %d, bflag = %d, cvalue = %s\n", aflag, bflag, cvalue);
--
-- for (index = optind; index < argc; index++)
-- printf ("Non-option argument %s\n", argv[index]);
-- return 0;
-- }
--
-- Here are some examples showing what this program prints with
--different combinations of arguments:
--
-- % testopt
-- aflag = 0, bflag = 0, cvalue = (null)
--
-- % testopt -a -b
-- aflag = 1, bflag = 1, cvalue = (null)
--
-- % testopt -ab
-- aflag = 1, bflag = 1, cvalue = (null)
--
-- % testopt -c foo
-- aflag = 0, bflag = 0, cvalue = foo
--
-- % testopt -cfoo
-- aflag = 0, bflag = 0, cvalue = foo
--
-- % testopt arg1
-- aflag = 0, bflag = 0, cvalue = (null)
-- Non-option argument arg1
--
-- % testopt -a arg1
-- aflag = 1, bflag = 0, cvalue = (null)
-- Non-option argument arg1
--
-- % testopt -c foo arg1
-- aflag = 0, bflag = 0, cvalue = foo
-- Non-option argument arg1
--
-- % testopt -a -- -b
-- aflag = 1, bflag = 0, cvalue = (null)
-- Non-option argument -b
--
-- % testopt -a -
-- aflag = 1, bflag = 0, cvalue = (null)
-- Non-option argument -
--
--
--File: libc.info, Node: Long Options, Next: Long Option Example, Prev:
Example of Getopt, Up: Program Arguments
--
--Parsing Long Options
----------------------
--
-- To accept GNU-style long options as well as single-character options,
--use `getopt_long' instead of `getopt'. This function is declared in
--`getopt.h', not `unistd.h'. You should make every program accept long
--options if it uses any options, for this takes little extra work and
--helps beginners remember how to use the program.
--
-- - Data Type: struct option
-- This structure describes a single long option name for the sake of
-- `getopt_long'. The argument LONGOPTS must be an array of these
-- structures, one for each long option. Terminate the array with an
-- element containing all zeros.
--
-- The `struct option' structure has these fields:
--
-- `const char *name'
-- This field is the name of the option. It is a string.
--
-- `int has_arg'
-- This field says whether the option takes an argument. It is
-- an integer, and there are three legitimate values:
-- `no_argument', `required_argument' and `optional_argument'.
--
-- `int *flag'
-- `int val'
-- These fields control how to report or act on the option when
-- it occurs.
--
-- If `flag' is a null pointer, then the `val' is a value which
-- identifies this option. Often these values are chosen to
-- uniquely identify particular long options.
--
-- If `flag' is not a null pointer, it should be the address of
-- an `int' variable which is the flag for this option. The
-- value in `val' is the value to store in the flag to indicate
-- that the option was seen.
--
-- - Function: int getopt_long (int ARGC, char **ARGV, const char
-- *SHORTOPTS, struct option *LONGOPTS, int *INDEXPTR)
-- Decode options from the vector ARGV (whose length is ARGC). The
-- argument SHORTOPTS describes the short options to accept, just as
-- it does in `getopt'. The argument LONGOPTS describes the long
-- options to accept (see above).
--
-- When `getopt_long' encounters a short option, it does the same
-- thing that `getopt' would do: it returns the character code for the
-- option, and stores the options argument (if it has one) in
-- `optarg'.
--
-- When `getopt_long' encounters a long option, it takes actions based
-- on the `flag' and `val' fields of the definition of that option.
--
-- If `flag' is a null pointer, then `getopt_long' returns the
-- contents of `val' to indicate which option it found. You should
-- arrange distinct values in the `val' field for options with
-- different meanings, so you can decode these values after
-- `getopt_long' returns. If the long option is equivalent to a short
-- option, you can use the short option's character code in `val'.
--
-- If `flag' is not a null pointer, that means this option should just
-- set a flag in the program. The flag is a variable of type `int'
-- that you define. Put the address of the flag in the `flag' field.
-- Put in the `val' field the value you would like this option to
-- store in the flag. In this case, `getopt_long' returns `0'.
--
-- For any long option, `getopt_long' tells you the index in the array
-- LONGOPTS of the options definition, by storing it into
-- `*INDEXPTR'. You can get the name of the option with
-- `LONGOPTS[*INDEXPTR].name'. So you can distinguish among long
-- options either by the values in their `val' fields or by their
-- indices. You can also distinguish in this way among long options
-- that set flags.
--
-- When a long option has an argument, `getopt_long' puts the argument
-- value in the variable `optarg' before returning. When the option
-- has no argument, the value in `optarg' is a null pointer. This is
-- how you can tell whether an optional argument was supplied.
--
-- When `getopt_long' has no more options to handle, it returns `-1',
-- and leaves in the variable `optind' the index in ARGV of the next
-- remaining argument.
--
--
--File: libc.info, Node: Long Option Example, Next: Suboptions, Prev: Long
Options, Up: Program Arguments
--
--Example of Parsing Long Options
---------------------------------
--
-- #include <stdio.h>
-- #include <stdlib.h>
-- #include <getopt.h>
--
-- /* Flag set by `--verbose'. */
-- static int verbose_flag;
--
-- int
-- main (argc, argv)
-- int argc;
-- char **argv;
-- {
-- int c;
--
-- while (1)
-- {
-- static struct option long_options[] =
-- {
-- /* These options set a flag. */
-- {"verbose", 0, &verbose_flag, 1},
-- {"brief", 0, &verbose_flag, 0},
-- /* These options don't set a flag.
-- We distinguish them by their indices. */
-- {"add", 1, 0, 0},
-- {"append", 0, 0, 0},
-- {"delete", 1, 0, 0},
-- {"create", 0, 0, 0},
-- {"file", 1, 0, 0},
-- {0, 0, 0, 0}
-- };
-- /* `getopt_long' stores the option index here. */
-- int option_index = 0;
--
-- c = getopt_long (argc, argv, "abc:d:",
-- long_options, &option_index);
--
-- /* Detect the end of the options. */
-- if (c == -1)
-- break;
--
-- switch (c)
-- {
-- case 0:
-- /* If this option set a flag, do nothing else now. */
-- if (long_options[option_index].flag != 0)
-- break;
-- printf ("option %s", long_options[option_index].name);
-- if (optarg)
-- printf (" with arg %s", optarg);
-- printf ("\n");
-- break;
--
-- case 'a':
-- puts ("option -a\n");
-- break;
--
-- case 'b':
-- puts ("option -b\n");
-- break;
--
-- case 'c':
-- printf ("option -c with value `%s'\n", optarg);
-- break;
--
-- case 'd':
-- printf ("option -d with value `%s'\n", optarg);
-- break;
--
-- case '?':
-- /* `getopt_long' already printed an error message. */
-- break;
--
-- default:
-- abort ();
-- }
-- }
--
-- /* Instead of reporting `--verbose'
-- and `--brief' as they are encountered,
-- we report the final status resulting from them. */
-- if (verbose_flag)
-- puts ("verbose flag is set");
--
-- /* Print any remaining command line arguments (not options). */
-- if (optind < argc)
-- {
-- printf ("non-option ARGV-elements: ");
-- while (optind < argc)
-- printf ("%s ", argv[optind++]);
-- putchar ('\n');
-- }
--
-- exit (0);
-- }
--
--
--File: libc.info, Node: Suboptions, Next: Suboptions Example, Prev: Long
Option Example, Up: Program Arguments
--
--Parsing of Suboptions
-----------------------
--
-- Having a single level of options is sometimes not enough. There
--might be too many options which have to be available or a set of
--options is closely related.
--
-- For this case some programs use suboptions. One of the most
--prominent programs is certainly `mount'(8). The `-o' option take one
--argument which itself is a comma separated list of options. To ease the
--programming of code like this the function `getsubopt' is available.
--
-- - Function: int getsubopt (char **OPTIONP, const char* const *TOKENS,
-- char **VALUEP)
-- The OPTIONP parameter must be a pointer to a variable containing
-- the address of the string to process. When the function returns
-- the reference is updated to point to the next suboption or to the
-- terminating `\0' character if there is no more suboption available.
--
-- The TOKENS parameter references an array of strings containing the
-- known suboptions. All strings must be `\0' terminated and to mark
-- the end a null pointer must be stored. When `getsubopt' finds a
-- possible legal suboption it compares it with all strings available
-- in the TOKENS array and returns the index in the string as the
-- indicator.
--
-- In case the suboption has an associated value introduced by a `='
-- character, a pointer to the value is returned in VALUEP. The
-- string is `\0' terminated. If no argument is available VALUEP is
-- set to the null pointer. By doing this the caller can check
-- whether a necessary value is given or whether no unexpected value
-- is present.
--
-- In case the next suboption in the string is not mentioned in the
-- TOKENS array the starting address of the suboption including a
-- possible value is returned in VALUEP and the return value of the
-- function is `-1'.
--
--
--File: libc.info, Node: Suboptions Example, Prev: Suboptions, Up: Program
Arguments
--
--Parsing of Suboptions Example
-------------------------------
--
-- The code which might appear in the `mount'(8) program is a perfect
--example of the use of `getsubopt':
--
-- #include <stdio.h>
-- #include <stdlib.h>
--
-- int do_all;
-- const char *type;
-- int read_size;
-- int write_size;
-- int read_only;
--
-- enum
-- {
-- RO_OPTION = 0,
-- RW_OPTION,
-- READ_SIZE_OPTION,
-- WRITE_SIZE_OPTION
-- };
--
-- const char *mount_opts[] =
-- {
-- [RO_OPTION] = "ro",
-- [RW_OPTION] = "rw",
-- [READ_SIZE_OPTION] = "rsize",
-- [WRITE_SIZE_OPTION] = "wsize"
-- };
--
-- int
-- main (int argc, char *argv[])
-- {
-- char *subopts, *value;
-- int opt;
--
-- while ((opt = getopt (argc, argv, "at:o:")) != -1)
-- switch (opt)
-- {
-- case 'a':
-- do_all = 1;
-- break;
-- case 't':
-- type = optarg;
-- break;
-- case 'o':
-- subopts = optarg;
-- while (*subopts != '\0')
-- switch (getsubopt (&subopts, mount_opts, &value))
-- {
-- case RO_OPTION:
-- read_only = 1;
-- break;
-- case RW_OPTION:
-- read_only = 0;
-- break;
-- case READ_SIZE_OPTION:
-- if (value == NULL)
-- abort ();
-- read_size = atoi (value);
-- break;
-- case WRITE_SIZE_OPTION:
-- if (value == NULL)
-- abort ();
-- write_size = atoi (value);
-- break;
-- default:
-- /* Unknown suboption. */
-- printf ("Unknown suboption `%s'\n", value);
-- break;
-- }
-- break;
-- default:
-- abort ();
-- }
--
-- /* Do the real work. */
--
-- return 0;
-- }
--
--
--File: libc.info, Node: Environment Variables, Next: Program Termination,
Prev: Program Arguments, Up: Process Startup
--
--Environment Variables
--=====================
--
-- When a program is executed, it receives information about the
--context in which it was invoked in two ways. The first mechanism uses
--the ARGV and ARGC arguments to its `main' function, and is discussed in
--*Note Program Arguments::. The second mechanism uses "environment
--variables" and is discussed in this section.
--
-- The ARGV mechanism is typically used to pass command-line arguments
--specific to the particular program being invoked. The environment, on
--the other hand, keeps track of information that is shared by many
--programs, changes infrequently, and that is less frequently used.
--
-- The environment variables discussed in this section are the same
--environment variables that you set using assignments and the `export'
--command in the shell. Programs executed from the shell inherit all of
--the environment variables from the shell.
--
-- Standard environment variables are used for information about the
--user's home directory, terminal type, current locale, and so on; you
--can define additional variables for other purposes. The set of all
--environment variables that have values is collectively known as the
--"environment".
--
-- Names of environment variables are case-sensitive and must not
--contain the character `='. System-defined environment variables are
--invariably uppercase.
--
-- The values of environment variables can be anything that can be
--represented as a string. A value must not contain an embedded null
--character, since this is assumed to terminate the string.
--
--* Menu:
--
--* Environment Access:: How to get and set the values of
-- environment variables.
--* Standard Environment:: These environment variables have
-- standard interpretations.
--
--
--File: libc.info, Node: Environment Access, Next: Standard Environment, Up:
Environment Variables
--
--Environment Access
--------------------
--
-- The value of an environment variable can be accessed with the
--`getenv' function. This is declared in the header file `stdlib.h'.
--
-- - Function: char * getenv (const char *NAME)
-- This function returns a string that is the value of the environment
-- variable NAME. You must not modify this string. In some non-Unix
-- systems not using the GNU library, it might be overwritten by
-- subsequent calls to `getenv' (but not by any other library
-- function). If the environment variable NAME is not defined, the
-- value is a null pointer.
--
-- - Function: int putenv (const char *STRING)
-- The `putenv' function adds or removes definitions from the
-- environment. If the STRING is of the form `NAME=VALUE', the
-- definition is added to the environment. Otherwise, the STRING is
-- interpreted as the name of an environment variable, and any
-- definition for this variable in the environment is removed.
--
-- The GNU library provides this function for compatibility with
-- SVID; it may not be available in other systems.
--
-- You can deal directly with the underlying representation of
--environment objects to add more variables to the environment (for
--example, to communicate with another program you are about to execute;
--see *Note Executing a File::).
--
-- - Variable: char ** environ
-- The environment is represented as an array of strings. Each
-- string is of the format `NAME=VALUE'. The order in which strings
-- appear in the environment is not significant, but the same NAME
-- must not appear more than once. The last element of the array is
-- a null pointer.
--
-- This variable is declared in the header file `unistd.h'.
--
-- If you just want to get the value of an environment variable, use
-- `getenv'.
--
-- Unix systems, and the GNU system, pass the initial value of
--`environ' as the third argument to `main'. *Note Program Arguments::.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-23
glibc-2.0.1/manual/libc.info-23
---- ../glibc-2.0.1/manual/libc.info-23 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-23 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1202 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Standard Environment, Prev: Environment Access, Up:
Environment Variables
--
--Standard Environment Variables
--------------------------------
--
-- These environment variables have standard meanings. This doesn't
--mean that they are always present in the environment; but if these
--variables *are* present, they have these meanings. You shouldn't try
--to use these environment variable names for some other purpose.
--
--`HOME'
-- This is a string representing the user's "home directory", or
-- initial default working directory.
--
-- The user can set `HOME' to any value. If you need to make sure to
-- obtain the proper home directory for a particular user, you should
-- not use `HOME'; instead, look up the user's name in the user
-- database (*note User Database::.).
--
-- For most purposes, it is better to use `HOME', precisely because
-- this lets the user specify the value.
--
--`LOGNAME'
-- This is the name that the user used to log in. Since the value in
-- the environment can be tweaked arbitrarily, this is not a reliable
-- way to identify the user who is running a process; a function like
-- `getlogin' (*note Who Logged In::.) is better for that purpose.
--
-- For most purposes, it is better to use `LOGNAME', precisely because
-- this lets the user specify the value.
--
--`PATH'
-- A "path" is a sequence of directory names which is used for
-- searching for a file. The variable `PATH' holds a path used for
-- searching for programs to be run.
--
-- The `execlp' and `execvp' functions (*note Executing a File::.)
-- use this environment variable, as do many shells and other
-- utilities which are implemented in terms of those functions.
--
-- The syntax of a path is a sequence of directory names separated by
-- colons. An empty string instead of a directory name stands for the
-- current directory (*note Working Directory::.).
--
-- A typical value for this environment variable might be a string
-- like:
--
-- :/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local/bin
--
-- This means that if the user tries to execute a program named `foo',
-- the system will look for files named `foo', `/bin/foo',
-- `/etc/foo', and so on. The first of these files that exists is
-- the one that is executed.
--
--`TERM'
-- This specifies the kind of terminal that is receiving program
-- output. Some programs can make use of this information to take
-- advantage of special escape sequences or terminal modes supported
-- by particular kinds of terminals. Many programs which use the
-- termcap library (*note Find: (termcap)Finding a Terminal
-- Description.) use the `TERM' environment variable, for example.
--
--`TZ'
-- This specifies the time zone. *Note TZ Variable::, for
-- information about the format of this string and how it is used.
--
--`LANG'
-- This specifies the default locale to use for attribute categories
-- where neither `LC_ALL' nor the specific environment variable for
-- that category is set. *Note Locales::, for more information about
-- locales.
--
--`LC_COLLATE'
-- This specifies what locale to use for string sorting.
--
--`LC_CTYPE'
-- This specifies what locale to use for character sets and character
-- classification.
--
--`LC_MONETARY'
-- This specifies what locale to use for formatting monetary values.
--
--`LC_NUMERIC'
-- This specifies what locale to use for formatting numbers.
--
--`LC_TIME'
-- This specifies what locale to use for formatting date/time values.
--
--`_POSIX_OPTION_ORDER'
-- If this environment variable is defined, it suppresses the usual
-- reordering of command line arguments by `getopt'. *Note Argument
-- Syntax::.
--
--
--File: libc.info, Node: Program Termination, Prev: Environment Variables,
Up: Process Startup
--
--Program Termination
--===================
--
-- The usual way for a program to terminate is simply for its `main'
--function to return. The "exit status value" returned from the `main'
--function is used to report information back to the process's parent
--process or shell.
--
-- A program can also terminate normally by calling the `exit' function.
--
-- In addition, programs can be terminated by signals; this is
--discussed in more detail in *Note Signal Handling::. The `abort'
--function causes a signal that kills the program.
--
--* Menu:
--
--* Normal Termination:: If a program calls `exit', a
-- process terminates normally.
--* Exit Status:: The `exit status' provides information
-- about why the process terminated.
--* Cleanups on Exit:: A process can run its own cleanup
-- functions upon normal termination.
--* Aborting a Program:: The `abort' function causes
-- abnormal program termination.
--* Termination Internals:: What happens when a process terminates.
--
--
--File: libc.info, Node: Normal Termination, Next: Exit Status, Up: Program
Termination
--
--Normal Termination
--------------------
--
-- A process terminates normally when the program calls `exit'.
--Returning from `main' is equivalent to calling `exit', and the value
--that `main' returns is used as the argument to `exit'.
--
-- - Function: void exit (int STATUS)
-- The `exit' function terminates the process with status STATUS.
-- This function does not return.
--
-- Normal termination causes the following actions:
--
-- 1. Functions that were registered with the `atexit' or `on_exit'
-- functions are called in the reverse order of their registration.
-- This mechanism allows your application to specify its own
-- "cleanup" actions to be performed at program termination.
-- Typically, this is used to do things like saving program state
-- information in a file, or unlocking locks in shared data bases.
--
-- 2. All open streams are closed, writing out any buffered output data.
-- See *Note Closing Streams::. In addition, temporary files opened
-- with the `tmpfile' function are removed; see *Note Temporary
-- Files::.
--
-- 3. `_exit' is called, terminating the program. *Note Termination
-- Internals::.
--
--
--File: libc.info, Node: Exit Status, Next: Cleanups on Exit, Prev: Normal
Termination, Up: Program Termination
--
--Exit Status
-------------
--
-- When a program exits, it can return to the parent process a small
--amount of information about the cause of termination, using the "exit
--status". This is a value between 0 and 255 that the exiting process
--passes as an argument to `exit'.
--
-- Normally you should use the exit status to report very broad
--information about success or failure. You can't provide a lot of
--detail about the reasons for the failure, and most parent processes
--would not want much detail anyway.
--
-- There are conventions for what sorts of status values certain
--programs should return. The most common convention is simply 0 for
--success and 1 for failure. Programs that perform comparison use a
--different convention: they use status 1 to indicate a mismatch, and
--status 2 to indicate an inability to compare. Your program should
--follow an existing convention if an existing convention makes sense for
--it.
--
-- A general convention reserves status values 128 and up for special
--purposes. In particular, the value 128 is used to indicate failure to
--execute another program in a subprocess. This convention is not
--universally obeyed, but it is a good idea to follow it in your programs.
--
-- *Warning:* Don't try to use the number of errors as the exit status.
--This is actually not very useful; a parent process would generally not
--care how many errors occurred. Worse than that, it does not work,
--because the status value is truncated to eight bits. Thus, if the
--program tried to report 256 errors, the parent would receive a report
--of 0 errors--that is, success.
--
-- For the same reason, it does not work to use the value of `errno' as
--the exit status--these can exceed 255.
--
-- *Portability note:* Some non-POSIX systems use different conventions
--for exit status values. For greater portability, you can use the
--macros `EXIT_SUCCESS' and `EXIT_FAILURE' for the conventional status
--value for success and failure, respectively. They are declared in the
--file `stdlib.h'.
--
-- - Macro: int EXIT_SUCCESS
-- This macro can be used with the `exit' function to indicate
-- successful program completion.
--
-- On POSIX systems, the value of this macro is `0'. On other
-- systems, the value might be some other (possibly non-constant)
-- integer expression.
--
-- - Macro: int EXIT_FAILURE
-- This macro can be used with the `exit' function to indicate
-- unsuccessful program completion in a general sense.
--
-- On POSIX systems, the value of this macro is `1'. On other
-- systems, the value might be some other (possibly non-constant)
-- integer expression. Other nonzero status values also indicate
-- future. Certain programs use different nonzero status values to
-- indicate particular kinds of "non-success". For example, `diff'
-- uses status value `1' to mean that the files are different, and
-- `2' or more to mean that there was difficulty in opening the files.
--
--
--File: libc.info, Node: Cleanups on Exit, Next: Aborting a Program, Prev:
Exit Status, Up: Program Termination
--
--Cleanups on Exit
------------------
--
-- Your program can arrange to run its own cleanup functions if normal
--termination happens. If you are writing a library for use in various
--application programs, then it is unreliable to insist that all
--applications call the library's cleanup functions explicitly before
--exiting. It is much more robust to make the cleanup invisible to the
--application, by setting up a cleanup function in the library itself
--using `atexit' or `on_exit'.
--
-- - Function: int atexit (void (*FUNCTION) (void))
-- The `atexit' function registers the function FUNCTION to be called
-- at normal program termination. The FUNCTION is called with no
-- arguments.
--
-- The return value from `atexit' is zero on success and nonzero if
-- the function cannot be registered.
--
-- - Function: int on_exit (void (*FUNCTION)(int STATUS, void *ARG), void
-- *ARG)
-- This function is a somewhat more powerful variant of `atexit'. It
-- accepts two arguments, a function FUNCTION and an arbitrary
-- pointer ARG. At normal program termination, the FUNCTION is
-- called with two arguments: the STATUS value passed to `exit', and
-- the ARG.
--
-- This function is included in the GNU C library only for
-- compatibility for SunOS, and may not be supported by other
-- implementations.
--
-- Here's a trivial program that illustrates the use of `exit' and
--`atexit':
--
-- #include <stdio.h>
-- #include <stdlib.h>
--
-- void
-- bye (void)
-- {
-- puts ("Goodbye, cruel world....");
-- }
--
-- int
-- main (void)
-- {
-- atexit (bye);
-- exit (EXIT_SUCCESS);
-- }
--
--When this program is executed, it just prints the message and exits.
--
--
--File: libc.info, Node: Aborting a Program, Next: Termination Internals,
Prev: Cleanups on Exit, Up: Program Termination
--
--Aborting a Program
--------------------
--
-- You can abort your program using the `abort' function. The prototype
--for this function is in `stdlib.h'.
--
-- - Function: void abort (void)
-- The `abort' function causes abnormal program termination. This
-- does not execute cleanup functions registered with `atexit' or
-- `on_exit'.
--
-- This function actually terminates the process by raising a
-- `SIGABRT' signal, and your program can include a handler to
-- intercept this signal; see *Note Signal Handling::.
--
-- *Future Change Warning:* Proposed Federal censorship regulations may
--prohibit us from giving you information about the possibility of
--calling this function. We would be required to say that this is not an
--acceptable way of terminating a program.
--
--
--File: libc.info, Node: Termination Internals, Prev: Aborting a Program,
Up: Program Termination
--
--Termination Internals
-----------------------
--
-- The `_exit' function is the primitive used for process termination
--by `exit'. It is declared in the header file `unistd.h'.
--
-- - Function: void _exit (int STATUS)
-- The `_exit' function is the primitive for causing a process to
-- terminate with status STATUS. Calling this function does not
-- execute cleanup functions registered with `atexit' or `on_exit'.
--
-- When a process terminates for any reason--either by an explicit
--termination call, or termination as a result of a signal--the following
--things happen:
--
-- * All open file descriptors in the process are closed. *Note
-- Low-Level I/O::. Note that streams are not flushed automatically
-- when the process terminates; *Note I/O on Streams::.
--
-- * The low-order 8 bits of the return status code are saved to be
-- reported back to the parent process via `wait' or `waitpid'; see
-- *Note Process Completion::.
--
-- * Any child processes of the process being terminated are assigned a
-- new parent process. (On most systems, including GNU, this is the
-- `init' process, with process ID 1.)
--
-- * A `SIGCHLD' signal is sent to the parent process.
--
-- * If the process is a session leader that has a controlling
-- terminal, then a `SIGHUP' signal is sent to each process in the
-- foreground job, and the controlling terminal is disassociated from
-- that session. *Note Job Control::.
--
-- * If termination of a process causes a process group to become
-- orphaned, and any member of that process group is stopped, then a
-- `SIGHUP' signal and a `SIGCONT' signal are sent to each process in
-- the group. *Note Job Control::.
--
--
--File: libc.info, Node: Processes, Next: Job Control, Prev: Process
Startup, Up: Top
--
--Processes
--*********
--
-- "Processes" are the primitive units for allocation of system
--resources. Each process has its own address space and (usually) one
--thread of control. A process executes a program; you can have multiple
--processes executing the same program, but each process has its own copy
--of the program within its own address space and executes it
--independently of the other copies.
--
-- Processes are organized hierarchically. Each process has a "parent
--process" which explicitly arranged to create it. The processes created
--by a given parent are called its "child processes". A child inherits
--many of its attributes from the parent process.
--
-- This chapter describes how a program can create, terminate, and
--control child processes. Actually, there are three distinct operations
--involved: creating a new child process, causing the new process to
--execute a program, and coordinating the completion of the child process
--with the original program.
--
-- The `system' function provides a simple, portable mechanism for
--running another program; it does all three steps automatically. If you
--need more control over the details of how this is done, you can use the
--primitive functions to do each step individually instead.
--
--* Menu:
--
--* Running a Command:: The easy way to run another program.
--* Process Creation Concepts:: An overview of the hard way to do it.
--* Process Identification:: How to get the process ID of a process.
--* Creating a Process:: How to fork a child process.
--* Executing a File:: How to make a process execute another program.
--* Process Completion:: How to tell when a child process has
completed.
--* Process Completion Status:: How to interpret the status value
-- returned from a child process.
--* BSD Wait Functions:: More functions, for backward compatibility.
--* Process Creation Example:: A complete example program.
--
--
--File: libc.info, Node: Running a Command, Next: Process Creation Concepts,
Up: Processes
--
--Running a Command
--=================
--
-- The easy way to run another program is to use the `system' function.
--This function does all the work of running a subprogram, but it
--doesn't give you much control over the details: you have to wait until
--the subprogram terminates before you can do anything else.
--
-- - Function: int system (const char *COMMAND)
-- This function executes COMMAND as a shell command. In the GNU C
-- library, it always uses the default shell `sh' to run the command.
-- In particular, it searches the directories in `PATH' to find
-- programs to execute. The return value is `-1' if it wasn't
-- possible to create the shell process, and otherwise is the status
-- of the shell process. *Note Process Completion::, for details on
-- how this status code can be interpreted.
--
-- The `system' function is declared in the header file `stdlib.h'.
--
-- *Portability Note:* Some C implementations may not have any notion
--of a command processor that can execute other programs. You can
--determine whether a command processor exists by executing
--`system (NULL)'; if the return value is nonzero, a command processor is
--available.
--
-- The `popen' and `pclose' functions (*note Pipe to a Subprocess::.)
--are closely related to the `system' function. They allow the parent
--process to communicate with the standard input and output channels of
--the command being executed.
--
--
--File: libc.info, Node: Process Creation Concepts, Next: Process
Identification, Prev: Running a Command, Up: Processes
--
--Process Creation Concepts
--=========================
--
-- This section gives an overview of processes and of the steps
--involved in creating a process and making it run another program.
--
-- Each process is named by a "process ID" number. A unique process ID
--is allocated to each process when it is created. The "lifetime" of a
--process ends when its termination is reported to its parent process; at
--that time, all of the process resources, including its process ID, are
--freed.
--
-- Processes are created with the `fork' system call (so the operation
--of creating a new process is sometimes called "forking" a process).
--The "child process" created by `fork' is a copy of the original "parent
--process", except that it has its own process ID.
--
-- After forking a child process, both the parent and child processes
--continue to execute normally. If you want your program to wait for a
--child process to finish executing before continuing, you must do this
--explicitly after the fork operation, by calling `wait' or `waitpid'
--(*note Process Completion::.). These functions give you limited
--information about why the child terminated--for example, its exit
--status code.
--
-- A newly forked child process continues to execute the same program as
--its parent process, at the point where the `fork' call returns. You
--can use the return value from `fork' to tell whether the program is
--running in the parent process or the child.
--
-- Having several processes run the same program is only occasionally
--useful. But the child can execute another program using one of the
--`exec' functions; see *Note Executing a File::. The program that the
--process is executing is called its "process image". Starting execution
--of a new program causes the process to forget all about its previous
--process image; when the new program exits, the process exits too,
--instead of returning to the previous process image.
--
--
--File: libc.info, Node: Process Identification, Next: Creating a Process,
Prev: Process Creation Concepts, Up: Processes
--
--Process Identification
--======================
--
-- The `pid_t' data type represents process IDs. You can get the
--process ID of a process by calling `getpid'. The function `getppid'
--returns the process ID of the parent of the current process (this is
--also known as the "parent process ID"). Your program should include
--the header files `unistd.h' and `sys/types.h' to use these functions.
--
-- - Data Type: pid_t
-- The `pid_t' data type is a signed integer type which is capable of
-- representing a process ID. In the GNU library, this is an `int'.
--
-- - Function: pid_t getpid (void)
-- The `getpid' function returns the process ID of the current
-- process.
--
-- - Function: pid_t getppid (void)
-- The `getppid' function returns the process ID of the parent of the
-- current process.
--
--
--File: libc.info, Node: Creating a Process, Next: Executing a File, Prev:
Process Identification, Up: Processes
--
--Creating a Process
--==================
--
-- The `fork' function is the primitive for creating a process. It is
--declared in the header file `unistd.h'.
--
-- - Function: pid_t fork (void)
-- The `fork' function creates a new process.
--
-- If the operation is successful, there are then both parent and
-- child processes and both see `fork' return, but with different
-- values: it returns a value of `0' in the child process and returns
-- the child's process ID in the parent process.
--
-- If process creation failed, `fork' returns a value of `-1' in the
-- parent process. The following `errno' error conditions are
-- defined for `fork':
--
-- `EAGAIN'
-- There aren't enough system resources to create another
-- process, or the user already has too many processes running.
-- This means exceeding the `RLIMIT_NPROC' resource limit, which
-- can usually be increased; *note Limits on Resources::..
--
-- `ENOMEM'
-- The process requires more space than the system can supply.
--
-- The specific attributes of the child process that differ from the
--parent process are:
--
-- * The child process has its own unique process ID.
--
-- * The parent process ID of the child process is the process ID of its
-- parent process.
--
-- * The child process gets its own copies of the parent process's open
-- file descriptors. Subsequently changing attributes of the file
-- descriptors in the parent process won't affect the file
-- descriptors in the child, and vice versa. *Note Control
-- Operations::. However, the file position associated with each
-- descriptor is shared by both processes; *note File Position::..
--
-- * The elapsed processor times for the child process are set to zero;
-- see *Note Processor Time::.
--
-- * The child doesn't inherit file locks set by the parent process.
-- *Note Control Operations::.
--
-- * The child doesn't inherit alarms set by the parent process. *Note
-- Setting an Alarm::.
--
-- * The set of pending signals (*note Delivery of Signal::.) for the
-- child process is cleared. (The child process inherits its mask of
-- blocked signals and signal actions from the parent process.)
--
-- - Function: pid_t vfork (void)
-- The `vfork' function is similar to `fork' but on systems it is
-- more efficient; however, there are restrictions you must follow to
-- use it safely.
--
-- While `fork' makes a complete copy of the calling process's
-- address space and allows both the parent and child to execute
-- independently, `vfork' does not make this copy. Instead, the
-- child process created with `vfork' shares its parent's address
-- space until it calls exits or one of the `exec' functions. In the
-- meantime, the parent process suspends execution.
--
-- You must be very careful not to allow the child process created
-- with `vfork' to modify any global data or even local variables
-- shared with the parent. Furthermore, the child process cannot
-- return from (or do a long jump out of) the function that called
-- `vfork'! This would leave the parent process's control
-- information very confused. If in doubt, use `fork' instead.
--
-- Some operating systems don't really implement `vfork'. The GNU C
-- library permits you to use `vfork' on all systems, but actually
-- executes `fork' if `vfork' isn't available. If you follow the
-- proper precautions for using `vfork', your program will still work
-- even if the system uses `fork' instead.
--
--
--File: libc.info, Node: Executing a File, Next: Process Completion, Prev:
Creating a Process, Up: Processes
--
--Executing a File
--================
--
-- This section describes the `exec' family of functions, for executing
--a file as a process image. You can use these functions to make a child
--process execute a new program after it has been forked.
--
-- The functions in this family differ in how you specify the arguments,
--but otherwise they all do the same thing. They are declared in the
--header file `unistd.h'.
--
-- - Function: int execv (const char *FILENAME, char *const ARGV[])
-- The `execv' function executes the file named by FILENAME as a new
-- process image.
--
-- The ARGV argument is an array of null-terminated strings that is
-- used to provide a value for the `argv' argument to the `main'
-- function of the program to be executed. The last element of this
-- array must be a null pointer. By convention, the first element of
-- this array is the file name of the program sans directory names.
-- *Note Program Arguments::, for full details on how programs can
-- access these arguments.
--
-- The environment for the new process image is taken from the
-- `environ' variable of the current process image; see *Note
-- Environment Variables::, for information about environments.
--
-- - Function: int execl (const char *FILENAME, const char *ARG0, ...)
-- This is similar to `execv', but the ARGV strings are specified
-- individually instead of as an array. A null pointer must be
-- passed as the last such argument.
--
-- - Function: int execve (const char *FILENAME, char *const ARGV[], char
-- *const ENV[])
-- This is similar to `execv', but permits you to specify the
-- environment for the new program explicitly as the ENV argument.
-- This should be an array of strings in the same format as for the
-- `environ' variable; see *Note Environment Access::.
--
-- - Function: int execle (const char *FILENAME, const char *ARG0, char
-- *const ENV[], ...)
-- This is similar to `execl', but permits you to specify the
-- environment for the new program explicitly. The environment
-- argument is passed following the null pointer that marks the last
-- ARGV argument, and should be an array of strings in the same
-- format as for the `environ' variable.
--
-- - Function: int execvp (const char *FILENAME, char *const ARGV[])
-- The `execvp' function is similar to `execv', except that it
-- searches the directories listed in the `PATH' environment variable
-- (*note Standard Environment::.) to find the full file name of a
-- file from FILENAME if FILENAME does not contain a slash.
--
-- This function is useful for executing system utility programs,
-- because it looks for them in the places that the user has chosen.
-- Shells use it to run the commands that users type.
--
-- - Function: int execlp (const char *FILENAME, const char *ARG0, ...)
-- This function is like `execl', except that it performs the same
-- file name searching as the `execvp' function.
--
-- The size of the argument list and environment list taken together
--must not be greater than `ARG_MAX' bytes. *Note General Limits::. In
--the GNU system, the size (which compares against `ARG_MAX') includes,
--for each string, the number of characters in the string, plus the size
--of a `char *', plus one, rounded up to a multiple of the size of a
--`char *'. Other systems may have somewhat different rules for counting.
--
-- These functions normally don't return, since execution of a new
--program causes the currently executing program to go away completely.
--A value of `-1' is returned in the event of a failure. In addition to
--the usual file name errors (*note File Name Errors::.), the following
--`errno' error conditions are defined for these functions:
--
--`E2BIG'
-- The combined size of the new program's argument list and
-- environment list is larger than `ARG_MAX' bytes. The GNU system
-- has no specific limit on the argument list size, so this error
-- code cannot result, but you may get `ENOMEM' instead if the
-- arguments are too big for available memory.
--
--`ENOEXEC'
-- The specified file can't be executed because it isn't in the right
-- format.
--
--`ENOMEM'
-- Executing the specified file requires more storage than is
-- available.
--
-- If execution of the new file succeeds, it updates the access time
--field of the file as if the file had been read. *Note File Times::,
--for more details about access times of files.
--
-- The point at which the file is closed again is not specified, but is
--at some point before the process exits or before another process image
--is executed.
--
-- Executing a new process image completely changes the contents of
--memory, copying only the argument and environment strings to new
--locations. But many other attributes of the process are unchanged:
--
-- * The process ID and the parent process ID. *Note Process Creation
-- Concepts::.
--
-- * Session and process group membership. *Note Concepts of Job
-- Control::.
--
-- * Real user ID and group ID, and supplementary group IDs. *Note
-- Process Persona::.
--
-- * Pending alarms. *Note Setting an Alarm::.
--
-- * Current working directory and root directory. *Note Working
-- Directory::. In the GNU system, the root directory is not copied
-- when executing a setuid program; instead the system default root
-- directory is used for the new program.
--
-- * File mode creation mask. *Note Setting Permissions::.
--
-- * Process signal mask; see *Note Process Signal Mask::.
--
-- * Pending signals; see *Note Blocking Signals::.
--
-- * Elapsed processor time associated with the process; see *Note
-- Processor Time::.
--
-- If the set-user-ID and set-group-ID mode bits of the process image
--file are set, this affects the effective user ID and effective group ID
--(respectively) of the process. These concepts are discussed in detail
--in *Note Process Persona::.
--
-- Signals that are set to be ignored in the existing process image are
--also set to be ignored in the new process image. All other signals are
--set to the default action in the new process image. For more
--information about signals, see *Note Signal Handling::.
--
-- File descriptors open in the existing process image remain open in
--the new process image, unless they have the `FD_CLOEXEC'
--(close-on-exec) flag set. The files that remain open inherit all
--attributes of the open file description from the existing process image,
--including file locks. File descriptors are discussed in *Note
--Low-Level I/O::.
--
-- Streams, by contrast, cannot survive through `exec' functions,
--because they are located in the memory of the process itself. The new
--process image has no streams except those it creates afresh. Each of
--the streams in the pre-`exec' process image has a descriptor inside it,
--and these descriptors do survive through `exec' (provided that they do
--not have `FD_CLOEXEC' set). The new process image can reconnect these
--to new streams using `fdopen' (*note Descriptors and Streams::.).
--
--
--File: libc.info, Node: Process Completion, Next: Process Completion Status,
Prev: Executing a File, Up: Processes
--
--Process Completion
--==================
--
-- The functions described in this section are used to wait for a child
--process to terminate or stop, and determine its status. These functions
--are declared in the header file `sys/wait.h'.
--
-- - Function: pid_t waitpid (pid_t PID, int *STATUS-PTR, int OPTIONS)
-- The `waitpid' function is used to request status information from a
-- child process whose process ID is PID. Normally, the calling
-- process is suspended until the child process makes status
-- information available by terminating.
--
-- Other values for the PID argument have special interpretations. A
-- value of `-1' or `WAIT_ANY' requests status information for any
-- child process; a value of `0' or `WAIT_MYPGRP' requests
-- information for any child process in the same process group as the
-- calling process; and any other negative value - PGID requests
-- information for any child process whose process group ID is PGID.
--
-- If status information for a child process is available
-- immediately, this function returns immediately without waiting.
-- If more than one eligible child process has status information
-- available, one of them is chosen randomly, and its status is
-- returned immediately. To get the status from the other eligible
-- child processes, you need to call `waitpid' again.
--
-- The OPTIONS argument is a bit mask. Its value should be the
-- bitwise OR (that is, the `|' operator) of zero or more of the
-- `WNOHANG' and `WUNTRACED' flags. You can use the `WNOHANG' flag
-- to indicate that the parent process shouldn't wait; and the
-- `WUNTRACED' flag to request status information from stopped
-- processes as well as processes that have terminated.
--
-- The status information from the child process is stored in the
-- object that STATUS-PTR points to, unless STATUS-PTR is a null
-- pointer.
--
-- The return value is normally the process ID of the child process
-- whose status is reported. If the `WNOHANG' option was specified
-- and no child process is waiting to be noticed, the value is zero.
-- A value of `-1' is returned in case of error. The following
-- `errno' error conditions are defined for this function:
--
-- `EINTR'
-- The function was interrupted by delivery of a signal to the
-- calling process. *Note Interrupted Primitives::.
--
-- `ECHILD'
-- There are no child processes to wait for, or the specified PID
-- is not a child of the calling process.
--
-- `EINVAL'
-- An invalid value was provided for the OPTIONS argument.
--
-- These symbolic constants are defined as values for the PID argument
--to the `waitpid' function.
--
--`WAIT_ANY'
-- This constant macro (whose value is `-1') specifies that `waitpid'
-- should return status information about any child process.
--
--`WAIT_MYPGRP'
-- This constant (with value `0') specifies that `waitpid' should
-- return status information about any child process in the same
-- process group as the calling process.
--
-- These symbolic constants are defined as flags for the OPTIONS
--argument to the `waitpid' function. You can bitwise-OR the flags
--together to obtain a value to use as the argument.
--
--`WNOHANG'
-- This flag specifies that `waitpid' should return immediately
-- instead of waiting, if there is no child process ready to be
-- noticed.
--
--`WUNTRACED'
-- This flag specifies that `waitpid' should report the status of any
-- child processes that have been stopped as well as those that have
-- terminated.
--
-- - Function: pid_t wait (int *STATUS-PTR)
-- This is a simplified version of `waitpid', and is used to wait
-- until any one child process terminates. The call:
--
-- wait (&status)
--
-- is exactly equivalent to:
--
-- waitpid (-1, &status, 0)
--
-- - Function: pid_t wait4 (pid_t PID, int *STATUS-PTR, int OPTIONS,
-- struct rusage *USAGE)
-- If USAGE is a null pointer, `wait4' is equivalent to `waitpid
-- (PID, STATUS-PTR, OPTIONS)'.
--
-- If USAGE is not null, `wait4' stores usage figures for the child
-- process in `*RUSAGE' (but only if the child has terminated, not if
-- it has stopped). *Note Resource Usage::.
--
-- This function is a BSD extension.
--
-- Here's an example of how to use `waitpid' to get the status from all
--child processes that have terminated, without ever waiting. This
--function is designed to be a handler for `SIGCHLD', the signal that
--indicates that at least one child process has terminated.
--
-- void
-- sigchld_handler (int signum)
-- {
-- int pid;
-- int status;
-- while (1)
-- {
-- pid = waitpid (WAIT_ANY, &status, WNOHANG);
-- if (pid < 0)
-- {
-- perror ("waitpid");
-- break;
-- }
-- if (pid == 0)
-- break;
-- notice_termination (pid, status);
-- }
-- }
--
--
--File: libc.info, Node: Process Completion Status, Next: BSD Wait Functions,
Prev: Process Completion, Up: Processes
--
--Process Completion Status
--=========================
--
-- If the exit status value (*note Program Termination::.) of the child
--process is zero, then the status value reported by `waitpid' or `wait'
--is also zero. You can test for other kinds of information encoded in
--the returned status value using the following macros. These macros are
--defined in the header file `sys/wait.h'.
--
-- - Macro: int WIFEXITED (int STATUS)
-- This macro returns a nonzero value if the child process terminated
-- normally with `exit' or `_exit'.
--
-- - Macro: int WEXITSTATUS (int STATUS)
-- If `WIFEXITED' is true of STATUS, this macro returns the low-order
-- 8 bits of the exit status value from the child process. *Note
-- Exit Status::.
--
-- - Macro: int WIFSIGNALED (int STATUS)
-- This macro returns a nonzero value if the child process terminated
-- because it received a signal that was not handled. *Note Signal
-- Handling::.
--
-- - Macro: int WTERMSIG (int STATUS)
-- If `WIFSIGNALED' is true of STATUS, this macro returns the signal
-- number of the signal that terminated the child process.
--
-- - Macro: int WCOREDUMP (int STATUS)
-- This macro returns a nonzero value if the child process terminated
-- and produced a core dump.
--
-- - Macro: int WIFSTOPPED (int STATUS)
-- This macro returns a nonzero value if the child process is stopped.
--
-- - Macro: int WSTOPSIG (int STATUS)
-- If `WIFSTOPPED' is true of STATUS, this macro returns the signal
-- number of the signal that caused the child process to stop.
--
--
--File: libc.info, Node: BSD Wait Functions, Next: Process Creation Example,
Prev: Process Completion Status, Up: Processes
--
--BSD Process Wait Functions
--==========================
--
-- The GNU library also provides these related facilities for
--compatibility with BSD Unix. BSD uses the `union wait' data type to
--represent status values rather than an `int'. The two representations
--are actually interchangeable; they describe the same bit patterns. The
--GNU C Library defines macros such as `WEXITSTATUS' so that they will
--work on either kind of object, and the `wait' function is defined to
--accept either type of pointer as its STATUS-PTR argument.
--
-- These functions are declared in `sys/wait.h'.
--
-- - Data Type: union wait
-- This data type represents program termination status values. It
-- has the following members:
--
-- `int w_termsig'
-- The value of this member is the same as the result of the
-- `WTERMSIG' macro.
--
-- `int w_coredump'
-- The value of this member is the same as the result of the
-- `WCOREDUMP' macro.
--
-- `int w_retcode'
-- The value of this member is the same as the result of the
-- `WEXITSTATUS' macro.
--
-- `int w_stopsig'
-- The value of this member is the same as the result of the
-- `WSTOPSIG' macro.
--
-- Instead of accessing these members directly, you should use the
-- equivalent macros.
--
-- The `wait3' function is the predecessor to `wait4', which is more
--flexible. `wait3' is now obsolete.
--
-- - Function: pid_t wait3 (union wait *STATUS-PTR, int OPTIONS, struct
-- rusage *USAGE)
-- If USAGE is a null pointer, `wait3' is equivalent to `waitpid (-1,
-- STATUS-PTR, OPTIONS)'.
--
-- If USAGE is not null, `wait3' stores usage figures for the child
-- process in `*RUSAGE' (but only if the child has terminated, not if
-- it has stopped). *Note Resource Usage::.
--
--
--File: libc.info, Node: Process Creation Example, Prev: BSD Wait Functions,
Up: Processes
--
--Process Creation Example
--========================
--
-- Here is an example program showing how you might write a function
--similar to the built-in `system'. It executes its COMMAND argument
--using the equivalent of `sh -c COMMAND'.
--
-- #include <stddef.h>
-- #include <stdlib.h>
-- #include <unistd.h>
-- #include <sys/types.h>
-- #include <sys/wait.h>
--
-- /* Execute the command using this shell program. */
-- #define SHELL "/bin/sh"
-- int
-- my_system (const char *command)
-- {
-- int status;
-- pid_t pid;
--
-- pid = fork ();
-- if (pid == 0)
-- {
-- /* This is the child process. Execute the shell command. */
-- execl (SHELL, SHELL, "-c", command, NULL);
-- _exit (EXIT_FAILURE);
-- }
-- else if (pid < 0)
-- /* The fork failed. Report failure. */
-- status = -1;
-- else
-- /* This is the parent process. Wait for the child to complete. */
-- if (waitpid (pid, &status, 0) != pid)
-- status = -1;
-- return status;
-- }
--
-- There are a couple of things you should pay attention to in this
--example.
--
-- Remember that the first `argv' argument supplied to the program
--represents the name of the program being executed. That is why, in the
--call to `execl', `SHELL' is supplied once to name the program to
--execute and a second time to supply a value for `argv[0]'.
--
-- The `execl' call in the child process doesn't return if it is
--successful. If it fails, you must do something to make the child
--process terminate. Just returning a bad status code with `return'
--would leave two processes running the original program. Instead, the
--right behavior is for the child process to report failure to its parent
--process.
--
-- Call `_exit' to accomplish this. The reason for using `_exit'
--instead of `exit' is to avoid flushing fully buffered streams such as
--`stdout'. The buffers of these streams probably contain data that was
--copied from the parent process by the `fork', data that will be output
--eventually by the parent process. Calling `exit' in the child would
--output the data twice. *Note Termination Internals::.
--
--
--File: libc.info, Node: Job Control, Next: Name Service Switch, Prev:
Processes, Up: Top
--
--Job Control
--***********
--
-- "Job control" refers to the protocol for allowing a user to move
--between multiple "process groups" (or "jobs") within a single "login
--session". The job control facilities are set up so that appropriate
--behavior for most programs happens automatically and they need not do
--anything special about job control. So you can probably ignore the
--material in this chapter unless you are writing a shell or login
--program.
--
-- You need to be familiar with concepts relating to process creation
--(*note Process Creation Concepts::.) and signal handling (*note Signal
--Handling::.) in order to understand this material presented in this
--chapter.
--
--* Menu:
--
--* Concepts of Job Control:: Jobs can be controlled by a shell.
--* Job Control is Optional:: Not all POSIX systems support job control.
--* Controlling Terminal:: How a process gets its controlling terminal.
--* Access to the Terminal:: How processes share the controlling terminal.
--* Orphaned Process Groups:: Jobs left after the user logs out.
--* Implementing a Shell:: What a shell must do to implement job control.
--* Functions for Job Control:: Functions to control process groups.
--
--
--File: libc.info, Node: Concepts of Job Control, Next: Job Control is
Optional, Up: Job Control
--
--Concepts of Job Control
--=======================
--
-- The fundamental purpose of an interactive shell is to read commands
--from the user's terminal and create processes to execute the programs
--specified by those commands. It can do this using the `fork' (*note
--Creating a Process::.) and `exec' (*note Executing a File::.) functions.
--
-- A single command may run just one process--but often one command uses
--several processes. If you use the `|' operator in a shell command, you
--explicitly request several programs in their own processes. But even
--if you run just one program, it can use multiple processes internally.
--For example, a single compilation command such as `cc -c foo.c'
--typically uses four processes (though normally only two at any given
--time). If you run `make', its job is to run other programs in separate
--processes.
--
-- The processes belonging to a single command are called a "process
--group" or "job". This is so that you can operate on all of them at
--once. For example, typing `C-c' sends the signal `SIGINT' to terminate
--all the processes in the foreground process group.
--
-- A "session" is a larger group of processes. Normally all the
--processes that stem from a single login belong to the same session.
--
-- Every process belongs to a process group. When a process is
--created, it becomes a member of the same process group and session as
--its parent process. You can put it in another process group using the
--`setpgid' function, provided the process group belongs to the same
--session.
--
-- The only way to put a process in a different session is to make it
--the initial process of a new session, or a "session leader", using the
--`setsid' function. This also puts the session leader into a new
--process group, and you can't move it out of that process group again.
--
-- Usually, new sessions are created by the system login program, and
--the session leader is the process running the user's login shell.
--
-- A shell that supports job control must arrange to control which job
--can use the terminal at any time. Otherwise there might be multiple
--jobs trying to read from the terminal at once, and confusion about which
--process should receive the input typed by the user. To prevent this,
--the shell must cooperate with the terminal driver using the protocol
--described in this chapter.
--
-- The shell can give unlimited access to the controlling terminal to
--only one process group at a time. This is called the "foreground job"
--on that controlling terminal. Other process groups managed by the shell
--that are executing without such access to the terminal are called
--"background jobs".
--
-- If a background job needs to read from its controlling terminal, it
--is "stopped" by the terminal driver; if the `TOSTOP' mode is set,
--likewise for writing. The user can stop a foreground job by typing the
--SUSP character (*note Special Characters::.) and a program can stop any
--job by sending it a `SIGSTOP' signal. It's the responsibility of the
--shell to notice when jobs stop, to notify the user about them, and to
--provide mechanisms for allowing the user to interactively continue
--stopped jobs and switch jobs between foreground and background.
--
-- *Note Access to the Terminal::, for more information about I/O to the
--controlling terminal,
--
--
--File: libc.info, Node: Job Control is Optional, Next: Controlling Terminal,
Prev: Concepts of Job Control, Up: Job Control
--
--Job Control is Optional
--=======================
--
-- Not all operating systems support job control. The GNU system does
--support job control, but if you are using the GNU library on some other
--system, that system may not support job control itself.
--
-- You can use the `_POSIX_JOB_CONTROL' macro to test at compile-time
--whether the system supports job control. *Note System Options::.
--
-- If job control is not supported, then there can be only one process
--group per session, which behaves as if it were always in the foreground.
--The functions for creating additional process groups simply fail with
--the error code `ENOSYS'.
--
-- The macros naming the various job control signals (*note Job Control
--Signals::.) are defined even if job control is not supported. However,
--the system never generates these signals, and attempts to send a job
--control signal or examine or specify their actions report errors or do
--nothing.
--
--
--File: libc.info, Node: Controlling Terminal, Next: Access to the Terminal,
Prev: Job Control is Optional, Up: Job Control
--
--Controlling Terminal of a Process
--=================================
--
-- One of the attributes of a process is its controlling terminal.
--Child processes created with `fork' inherit the controlling terminal
--from their parent process. In this way, all the processes in a session
--inherit the controlling terminal from the session leader. A session
--leader that has control of a terminal is called the "controlling
--process" of that terminal.
--
-- You generally do not need to worry about the exact mechanism used to
--allocate a controlling terminal to a session, since it is done for you
--by the system when you log in.
--
-- An individual process disconnects from its controlling terminal when
--it calls `setsid' to become the leader of a new session. *Note Process
--Group Functions::.
--
--
--File: libc.info, Node: Access to the Terminal, Next: Orphaned Process
Groups, Prev: Controlling Terminal, Up: Job Control
--
--Access to the Controlling Terminal
--==================================
--
-- Processes in the foreground job of a controlling terminal have
--unrestricted access to that terminal; background processes do not. This
--section describes in more detail what happens when a process in a
--background job tries to access its controlling terminal.
--
-- When a process in a background job tries to read from its controlling
--terminal, the process group is usually sent a `SIGTTIN' signal. This
--normally causes all of the processes in that group to stop (unless they
--handle the signal and don't stop themselves). However, if the reading
--process is ignoring or blocking this signal, then `read' fails with an
--`EIO' error instead.
--
-- Similarly, when a process in a background job tries to write to its
--controlling terminal, the default behavior is to send a `SIGTTOU'
--signal to the process group. However, the behavior is modified by the
--`TOSTOP' bit of the local modes flags (*note Local Modes::.). If this
--bit is not set (which is the default), then writing to the controlling
--terminal is always permitted without sending a signal. Writing is also
--permitted if the `SIGTTOU' signal is being ignored or blocked by the
--writing process.
--
-- Most other terminal operations that a program can do are treated as
--reading or as writing. (The description of each operation should say
--which.)
--
-- For more information about the primitive `read' and `write'
--functions, see *Note I/O Primitives::.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-24
glibc-2.0.1/manual/libc.info-24
---- ../glibc-2.0.1/manual/libc.info-24 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-24 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1332 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Orphaned Process Groups, Next: Implementing a Shell,
Prev: Access to the Terminal, Up: Job Control
--
--Orphaned Process Groups
--=======================
--
-- When a controlling process terminates, its terminal becomes free and
--a new session can be established on it. (In fact, another user could
--log in on the terminal.) This could cause a problem if any processes
--from the old session are still trying to use that terminal.
--
-- To prevent problems, process groups that continue running even after
--the session leader has terminated are marked as "orphaned process
--groups".
--
-- When a process group becomes an orphan, its processes are sent a
--`SIGHUP' signal. Ordinarily, this causes the processes to terminate.
--However, if a program ignores this signal or establishes a handler for
--it (*note Signal Handling::.), it can continue running as in the orphan
--process group even after its controlling process terminates; but it
--still cannot access the terminal any more.
--
--
--File: libc.info, Node: Implementing a Shell, Next: Functions for Job
Control, Prev: Orphaned Process Groups, Up: Job Control
--
--Implementing a Job Control Shell
--================================
--
-- This section describes what a shell must do to implement job
--control, by presenting an extensive sample program to illustrate the
--concepts involved.
--
--* Menu:
--
--* Data Structures:: Introduction to the sample shell.
--* Initializing the Shell:: What the shell must do to take
-- responsibility for job control.
--* Launching Jobs:: Creating jobs to execute commands.
--* Foreground and Background:: Putting a job in foreground of background.
--* Stopped and Terminated Jobs:: Reporting job status.
--* Continuing Stopped Jobs:: How to continue a stopped job in
-- the foreground or background.
--* Missing Pieces:: Other parts of the shell.
--
--
--File: libc.info, Node: Data Structures, Next: Initializing the Shell, Up:
Implementing a Shell
--
--Data Structures for the Shell
-------------------------------
--
-- All of the program examples included in this chapter are part of a
--simple shell program. This section presents data structures and
--utility functions which are used throughout the example.
--
-- The sample shell deals mainly with two data structures. The `job'
--type contains information about a job, which is a set of subprocesses
--linked together with pipes. The `process' type holds information about
--a single subprocess. Here are the relevant data structure declarations:
--
-- /* A process is a single process. */
-- typedef struct process
-- {
-- struct process *next; /* next process in pipeline */
-- char **argv; /* for exec */
-- pid_t pid; /* process ID */
-- char completed; /* true if process has completed */
-- char stopped; /* true if process has stopped */
-- int status; /* reported status value */
-- } process;
--
-- /* A job is a pipeline of processes. */
-- typedef struct job
-- {
-- struct job *next; /* next active job */
-- char *command; /* command line, used for messages */
-- process *first_process; /* list of processes in this job */
-- pid_t pgid; /* process group ID */
-- char notified; /* true if user told about stopped job */
-- struct termios tmodes; /* saved terminal modes */
-- int stdin, stdout, stderr; /* standard i/o channels */
-- } job;
--
-- /* The active jobs are linked into a list. This is its head. */
-- job *first_job = NULL;
--
-- Here are some utility functions that are used for operating on `job'
--objects.
--
-- /* Find the active job with the indicated PGID. */
-- job *
-- find_job (pid_t pgid)
-- {
-- job *j;
--
-- for (j = first_job; j; j = j->next)
-- if (j->pgid == pgid)
-- return j;
-- return NULL;
-- }
--
-- /* Return true if all processes in the job have stopped or completed. */
-- int
-- job_is_stopped (job *j)
-- {
-- process *p;
--
-- for (p = j->first_process; p; p = p->next)
-- if (!p->completed && !p->stopped)
-- return 0;
-- return 1;
-- }
--
-- /* Return true if all processes in the job have completed. */
-- int
-- job_is_completed (job *j)
-- {
-- process *p;
--
-- for (p = j->first_process; p; p = p->next)
-- if (!p->completed)
-- return 0;
-- return 1;
-- }
--
--
--File: libc.info, Node: Initializing the Shell, Next: Launching Jobs, Prev:
Data Structures, Up: Implementing a Shell
--
--Initializing the Shell
------------------------
--
-- When a shell program that normally performs job control is started,
--it has to be careful in case it has been invoked from another shell
--that is already doing its own job control.
--
-- A subshell that runs interactively has to ensure that it has been
--placed in the foreground by its parent shell before it can enable job
--control itself. It does this by getting its initial process group ID
--with the `getpgrp' function, and comparing it to the process group ID
--of the current foreground job associated with its controlling terminal
--(which can be retrieved using the `tcgetpgrp' function).
--
-- If the subshell is not running as a foreground job, it must stop
--itself by sending a `SIGTTIN' signal to its own process group. It may
--not arbitrarily put itself into the foreground; it must wait for the
--user to tell the parent shell to do this. If the subshell is continued
--again, it should repeat the check and stop itself again if it is still
--not in the foreground.
--
-- Once the subshell has been placed into the foreground by its parent
--shell, it can enable its own job control. It does this by calling
--`setpgid' to put itself into its own process group, and then calling
--`tcsetpgrp' to place this process group into the foreground.
--
-- When a shell enables job control, it should set itself to ignore all
--the job control stop signals so that it doesn't accidentally stop
--itself. You can do this by setting the action for all the stop signals
--to `SIG_IGN'.
--
-- A subshell that runs non-interactively cannot and should not support
--job control. It must leave all processes it creates in the same process
--group as the shell itself; this allows the non-interactive shell and its
--child processes to be treated as a single job by the parent shell. This
--is easy to do--just don't use any of the job control primitives--but
--you must remember to make the shell do it.
--
-- Here is the initialization code for the sample shell that shows how
--to do all of this.
--
-- /* Keep track of attributes of the shell. */
--
-- #include <sys/types.h>
-- #include <termios.h>
-- #include <unistd.h>
--
-- pid_t shell_pgid;
-- struct termios shell_tmodes;
-- int shell_terminal;
-- int shell_is_interactive;
--
--
-- /* Make sure the shell is running interactively as the foreground job
-- before proceeding. */
--
-- void
-- init_shell ()
-- {
--
-- /* See if we are running interactively. */
-- shell_terminal = STDIN_FILENO;
-- shell_is_interactive = isatty (shell_terminal);
--
-- if (shell_is_interactive)
-- {
-- /* Loop until we are in the foreground. */
-- while (tcgetpgrp (shell_terminal) != (shell_pgid = getpgrp ()))
-- kill (- shell_pgid, SIGTTIN);
--
-- /* Ignore interactive and job-control signals. */
-- signal (SIGINT, SIG_IGN);
-- signal (SIGQUIT, SIG_IGN);
-- signal (SIGTSTP, SIG_IGN);
-- signal (SIGTTIN, SIG_IGN);
-- signal (SIGTTOU, SIG_IGN);
-- signal (SIGCHLD, SIG_IGN);
--
-- /* Put ourselves in our own process group. */
-- shell_pgid = getpid ();
-- if (setpgid (shell_pgid, shell_pgid) < 0)
-- {
-- perror ("Couldn't put the shell in its own process group");
-- exit (1);
-- }
--
-- /* Grab control of the terminal. */
-- tcsetpgrp (shell_terminal, shell_pgid);
--
-- /* Save default terminal attributes for shell. */
-- tcgetattr (shell_terminal, &shell_tmodes);
-- }
-- }
--
--
--File: libc.info, Node: Launching Jobs, Next: Foreground and Background,
Prev: Initializing the Shell, Up: Implementing a Shell
--
--Launching Jobs
----------------
--
-- Once the shell has taken responsibility for performing job control on
--its controlling terminal, it can launch jobs in response to commands
--typed by the user.
--
-- To create the processes in a process group, you use the same `fork'
--and `exec' functions described in *Note Process Creation Concepts::.
--Since there are multiple child processes involved, though, things are a
--little more complicated and you must be careful to do things in the
--right order. Otherwise, nasty race conditions can result.
--
-- You have two choices for how to structure the tree of parent-child
--relationships among the processes. You can either make all the
--processes in the process group be children of the shell process, or you
--can make one process in group be the ancestor of all the other processes
--in that group. The sample shell program presented in this chapter uses
--the first approach because it makes bookkeeping somewhat simpler.
--
-- As each process is forked, it should put itself in the new process
--group by calling `setpgid'; see *Note Process Group Functions::. The
--first process in the new group becomes its "process group leader", and
--its process ID becomes the "process group ID" for the group.
--
-- The shell should also call `setpgid' to put each of its child
--processes into the new process group. This is because there is a
--potential timing problem: each child process must be put in the process
--group before it begins executing a new program, and the shell depends on
--having all the child processes in the group before it continues
--executing. If both the child processes and the shell call `setpgid',
--this ensures that the right things happen no matter which process gets
--to it first.
--
-- If the job is being launched as a foreground job, the new process
--group also needs to be put into the foreground on the controlling
--terminal using `tcsetpgrp'. Again, this should be done by the shell as
--well as by each of its child processes, to avoid race conditions.
--
-- The next thing each child process should do is to reset its signal
--actions.
--
-- During initialization, the shell process set itself to ignore job
--control signals; see *Note Initializing the Shell::. As a result, any
--child processes it creates also ignore these signals by inheritance.
--This is definitely undesirable, so each child process should explicitly
--set the actions for these signals back to `SIG_DFL' just after it is
--forked.
--
-- Since shells follow this convention, applications can assume that
--they inherit the correct handling of these signals from the parent
--process. But every application has a responsibility not to mess up the
--handling of stop signals. Applications that disable the normal
--interpretation of the SUSP character should provide some other
--mechanism for the user to stop the job. When the user invokes this
--mechanism, the program should send a `SIGTSTP' signal to the process
--group of the process, not just to the process itself. *Note Signaling
--Another Process::.
--
-- Finally, each child process should call `exec' in the normal way.
--This is also the point at which redirection of the standard input and
--output channels should be handled. *Note Duplicating Descriptors::,
--for an explanation of how to do this.
--
-- Here is the function from the sample shell program that is
--responsible for launching a program. The function is executed by each
--child process immediately after it has been forked by the shell, and
--never returns.
--
-- void
-- launch_process (process *p, pid_t pgid,
-- int infile, int outfile, int errfile,
-- int foreground)
-- {
-- pid_t pid;
--
-- if (shell_is_interactive)
-- {
-- /* Put the process into the process group and give the process
group
-- the terminal, if appropriate.
-- This has to be done both by the shell and in the individual
-- child processes because of potential race conditions. */
-- pid = getpid ();
-- if (pgid == 0) pgid = pid;
-- setpgid (pid, pgid);
-- if (foreground)
-- tcsetpgrp (shell_terminal, pgid);
--
-- /* Set the handling for job control signals back to the default.
*/
-- signal (SIGINT, SIG_DFL);
-- signal (SIGQUIT, SIG_DFL);
-- signal (SIGTSTP, SIG_DFL);
-- signal (SIGTTIN, SIG_DFL);
-- signal (SIGTTOU, SIG_DFL);
-- signal (SIGCHLD, SIG_DFL);
-- }
--
-- /* Set the standard input/output channels of the new process. */
-- if (infile != STDIN_FILENO)
-- {
-- dup2 (infile, STDIN_FILENO);
-- close (infile);
-- }
-- if (outfile != STDOUT_FILENO)
-- {
-- dup2 (outfile, STDOUT_FILENO);
-- close (outfile);
-- }
-- if (errfile != STDERR_FILENO)
-- {
-- dup2 (errfile, STDERR_FILENO);
-- close (errfile);
-- }
--
-- /* Exec the new process. Make sure we exit. */
-- execvp (p->argv[0], p->argv);
-- perror ("execvp");
-- exit (1);
-- }
--
-- If the shell is not running interactively, this function does not do
--anything with process groups or signals. Remember that a shell not
--performing job control must keep all of its subprocesses in the same
--process group as the shell itself.
--
-- Next, here is the function that actually launches a complete job.
--After creating the child processes, this function calls some other
--functions to put the newly created job into the foreground or
--background; these are discussed in *Note Foreground and Background::.
--
-- void
-- launch_job (job *j, int foreground)
-- {
-- process *p;
-- pid_t pid;
-- int mypipe[2], infile, outfile;
--
-- infile = j->stdin;
-- for (p = j->first_process; p; p = p->next)
-- {
-- /* Set up pipes, if necessary. */
-- if (p->next)
-- {
-- if (pipe (mypipe) < 0)
-- {
-- perror ("pipe");
-- exit (1);
-- }
-- outfile = mypipe[1];
-- }
-- else
-- outfile = j->stdout;
--
-- /* Fork the child processes. */
-- pid = fork ();
-- if (pid == 0)
-- /* This is the child process. */
-- launch_process (p, j->pgid, infile,
-- outfile, j->stderr, foreground);
-- else if (pid < 0)
-- {
-- /* The fork failed. */
-- perror ("fork");
-- exit (1);
-- }
-- else
-- {
-- /* This is the parent process. */
-- p->pid = pid;
-- if (shell_is_interactive)
-- {
-- if (!j->pgid)
-- j->pgid = pid;
-- setpgid (pid, j->pgid);
-- }
-- }
--
-- /* Clean up after pipes. */
-- if (infile != j->stdin)
-- close (infile);
-- if (outfile != j->stdout)
-- close (outfile);
-- infile = mypipe[0];
-- }
--
-- format_job_info (j, "launched");
--
-- if (!shell_is_interactive)
-- wait_for_job (j);
-- else if (foreground)
-- put_job_in_foreground (j, 0);
-- else
-- put_job_in_background (j, 0);
-- }
--
--
--File: libc.info, Node: Foreground and Background, Next: Stopped and
Terminated Jobs, Prev: Launching Jobs, Up: Implementing a Shell
--
--Foreground and Background
---------------------------
--
-- Now let's consider what actions must be taken by the shell when it
--launches a job into the foreground, and how this differs from what must
--be done when a background job is launched.
--
-- When a foreground job is launched, the shell must first give it
--access to the controlling terminal by calling `tcsetpgrp'. Then, the
--shell should wait for processes in that process group to terminate or
--stop. This is discussed in more detail in *Note Stopped and Terminated
--Jobs::.
--
-- When all of the processes in the group have either completed or
--stopped, the shell should regain control of the terminal for its own
--process group by calling `tcsetpgrp' again. Since stop signals caused
--by I/O from a background process or a SUSP character typed by the user
--are sent to the process group, normally all the processes in the job
--stop together.
--
-- The foreground job may have left the terminal in a strange state, so
--the shell should restore its own saved terminal modes before
--continuing. In case the job is merely been stopped, the shell should
--first save the current terminal modes so that it can restore them later
--if the job is continued. The functions for dealing with terminal modes
--are `tcgetattr' and `tcsetattr'; these are described in *Note Terminal
--Modes::.
--
-- Here is the sample shell's function for doing all of this.
--
-- /* Put job J in the foreground. If CONT is nonzero,
-- restore the saved terminal modes and send the process group a
-- `SIGCONT' signal to wake it up before we block. */
--
-- void
-- put_job_in_foreground (job *j, int cont)
-- {
-- /* Put the job into the foreground. */
-- tcsetpgrp (shell_terminal, j->pgid);
--
-- /* Send the job a continue signal, if necessary. */
-- if (cont)
-- {
-- tcsetattr (shell_terminal, TCSADRAIN, &j->tmodes);
-- if (kill (- j->pgid, SIGCONT) < 0)
-- perror ("kill (SIGCONT)");
-- }
--
-- /* Wait for it to report. */
-- wait_for_job (j);
--
-- /* Put the shell back in the foreground. */
-- tcsetpgrp (shell_terminal, shell_pgid);
-- /* Restore the shell's terminal modes. */
-- tcgetattr (shell_terminal, &j->tmodes);
-- tcsetattr (shell_terminal, TCSADRAIN, &shell_tmodes);
-- }
--
-- If the process group is launched as a background job, the shell
--should remain in the foreground itself and continue to read commands
--from the terminal.
--
-- In the sample shell, there is not much that needs to be done to put
--a job into the background. Here is the function it uses:
--
-- /* Put a job in the background. If the cont argument is true, send
-- the process group a `SIGCONT' signal to wake it up. */
--
-- void
-- put_job_in_background (job *j, int cont)
-- {
-- /* Send the job a continue signal, if necessary. */
-- if (cont)
-- if (kill (-j->pgid, SIGCONT) < 0)
-- perror ("kill (SIGCONT)");
-- }
--
--
--File: libc.info, Node: Stopped and Terminated Jobs, Next: Continuing
Stopped Jobs, Prev: Foreground and Background, Up: Implementing a Shell
--
--Stopped and Terminated Jobs
-----------------------------
--
-- When a foreground process is launched, the shell must block until
--all of the processes in that job have either terminated or stopped. It
--can do this by calling the `waitpid' function; see *Note Process
--Completion::. Use the `WUNTRACED' option so that status is reported
--for processes that stop as well as processes that terminate.
--
-- The shell must also check on the status of background jobs so that it
--can report terminated and stopped jobs to the user; this can be done by
--calling `waitpid' with the `WNOHANG' option. A good place to put a
--such a check for terminated and stopped jobs is just before prompting
--for a new command.
--
-- The shell can also receive asynchronous notification that there is
--status information available for a child process by establishing a
--handler for `SIGCHLD' signals. *Note Signal Handling::.
--
-- In the sample shell program, the `SIGCHLD' signal is normally
--ignored. This is to avoid reentrancy problems involving the global data
--structures the shell manipulates. But at specific times when the shell
--is not using these data structures--such as when it is waiting for
--input on the terminal--it makes sense to enable a handler for
--`SIGCHLD'. The same function that is used to do the synchronous status
--checks (`do_job_notification', in this case) can also be called from
--within this handler.
--
-- Here are the parts of the sample shell program that deal with
--checking the status of jobs and reporting the information to the user.
--
-- /* Store the status of the process PID that was returned by waitpid.
-- Return 0 if all went well, nonzero otherwise. */
--
-- int
-- mark_process_status (pid_t pid, int status)
-- {
-- job *j;
-- process *p;
--
-- if (pid > 0)
-- {
-- /* Update the record for the process. */
-- for (j = first_job; j; j = j->next)
-- for (p = j->first_process; p; p = p->next)
-- if (p->pid == pid)
-- {
-- p->status = status;
-- if (WIFSTOPPED (status))
-- p->stopped = 1;
-- else
-- {
-- p->completed = 1;
-- if (WIFSIGNALED (status))
-- fprintf (stderr, "%d: Terminated by signal %d.\n",
-- (int) pid, WTERMSIG (p->status));
-- }
-- return 0;
-- }
-- fprintf (stderr, "No child process %d.\n", pid);
-- return -1;
-- }
--
-- else if (pid == 0 || errno == ECHILD)
-- /* No processes ready to report. */
-- return -1;
-- else {
-- /* Other weird errors. */
-- perror ("waitpid");
-- return -1;
-- }
-- }
--
-- /* Check for processes that have status information available,
-- without blocking. */
--
-- void
-- update_status (void)
-- {
-- int status;
-- pid_t pid;
--
-- do
-- pid = waitpid (WAIT_ANY, &status, WUNTRACED|WNOHANG);
-- while (!mark_process_status (pid, status));
-- }
--
-- /* Check for processes that have status information available,
-- blocking until all processes in the given job have reported. */
--
-- void
-- wait_for_job (job *j)
-- {
-- int status;
-- pid_t pid;
--
-- do
-- pid = waitpid (WAIT_ANY, &status, WUNTRACED);
-- while (!mark_process_status (pid, status)
-- && !job_is_stopped (j)
-- && !job_is_completed (j));
-- }
--
-- /* Format information about job status for the user to look at. */
--
-- void
-- format_job_info (job *j, const char *status)
-- {
-- fprintf (stderr, "%ld (%s): %s\n", (long)j->pgid, status, j->command);
-- }
--
-- /* Notify the user about stopped or terminated jobs.
-- Delete terminated jobs from the active job list. */
--
-- void
-- do_job_notification (void)
-- {
-- job *j, *jlast, *jnext;
-- process *p;
--
-- /* Update status information for child processes. */
-- update_status ();
--
-- jlast = NULL;
-- for (j = first_job; j; j = jnext)
-- {
-- jnext = j->next;
--
-- /* If all processes have completed, tell the user the job has
-- completed and delete it from the list of active jobs. */
-- if (job_is_completed (j)) {
-- format_job_info (j, "completed");
-- if (jlast)
-- jlast->next = jnext;
-- else
-- first_job = jnext;
-- free_job (j);
-- }
--
-- /* Notify the user about stopped jobs,
-- marking them so that we won't do this more than once. */
-- else if (job_is_stopped (j) && !j->notified) {
-- format_job_info (j, "stopped");
-- j->notified = 1;
-- jlast = j;
-- }
--
-- /* Don't say anything about jobs that are still running. */
-- else
-- jlast = j;
-- }
-- }
--
--
--File: libc.info, Node: Continuing Stopped Jobs, Next: Missing Pieces,
Prev: Stopped and Terminated Jobs, Up: Implementing a Shell
--
--Continuing Stopped Jobs
-------------------------
--
-- The shell can continue a stopped job by sending a `SIGCONT' signal
--to its process group. If the job is being continued in the foreground,
--the shell should first invoke `tcsetpgrp' to give the job access to the
--terminal, and restore the saved terminal settings. After continuing a
--job in the foreground, the shell should wait for the job to stop or
--complete, as if the job had just been launched in the foreground.
--
-- The sample shell program handles both newly created and continued
--jobs with the same pair of functions, `put_job_in_foreground' and
--`put_job_in_background'. The definitions of these functions were given
--in *Note Foreground and Background::. When continuing a stopped job, a
--nonzero value is passed as the CONT argument to ensure that the
--`SIGCONT' signal is sent and the terminal modes reset, as appropriate.
--
-- This leaves only a function for updating the shell's internal
--bookkeeping about the job being continued:
--
-- /* Mark a stopped job J as being running again. */
--
-- void
-- mark_job_as_running (job *j)
-- {
-- Process *p;
--
-- for (p = j->first_process; p; p = p->next)
-- p->stopped = 0;
-- j->notified = 0;
-- }
--
-- /* Continue the job J. */
--
-- void
-- continue_job (job *j, int foreground)
-- {
-- mark_job_as_running (j);
-- if (foreground)
-- put_job_in_foreground (j, 1);
-- else
-- put_job_in_background (j, 1);
-- }
--
--
--File: libc.info, Node: Missing Pieces, Prev: Continuing Stopped Jobs, Up:
Implementing a Shell
--
--The Missing Pieces
--------------------
--
-- The code extracts for the sample shell included in this chapter are
--only a part of the entire shell program. In particular, nothing at all
--has been said about how `job' and `program' data structures are
--allocated and initialized.
--
-- Most real shells provide a complex user interface that has support
--for a command language; variables; abbreviations, substitutions, and
--pattern matching on file names; and the like. All of this is far too
--complicated to explain here! Instead, we have concentrated on showing
--how to implement the core process creation and job control functions
--that can be called from such a shell.
--
-- Here is a table summarizing the major entry points we have presented:
--
--`void init_shell (void)'
-- Initialize the shell's internal state. *Note Initializing the
-- Shell::.
--
--`void launch_job (job *J, int FOREGROUND)'
-- Launch the job J as either a foreground or background job. *Note
-- Launching Jobs::.
--
--`void do_job_notification (void)'
-- Check for and report any jobs that have terminated or stopped.
-- Can be called synchronously or within a handler for `SIGCHLD'
-- signals. *Note Stopped and Terminated Jobs::.
--
--`void continue_job (job *J, int FOREGROUND)'
-- Continue the job J. *Note Continuing Stopped Jobs::.
--
-- Of course, a real shell would also want to provide other functions
--for managing jobs. For example, it would be useful to have commands to
--list all active jobs or to send a signal (such as `SIGKILL') to a job.
--
--
--File: libc.info, Node: Functions for Job Control, Prev: Implementing a
Shell, Up: Job Control
--
--Functions for Job Control
--=========================
--
-- This section contains detailed descriptions of the functions relating
--to job control.
--
--* Menu:
--
--* Identifying the Terminal:: Determining the controlling terminal's name.
--* Process Group Functions:: Functions for manipulating process groups.
--* Terminal Access Functions:: Functions for controlling terminal access.
--
--
--File: libc.info, Node: Identifying the Terminal, Next: Process Group
Functions, Up: Functions for Job Control
--
--Identifying the Controlling Terminal
--------------------------------------
--
-- You can use the `ctermid' function to get a file name that you can
--use to open the controlling terminal. In the GNU library, it returns
--the same string all the time: `"/dev/tty"'. That is a special "magic"
--file name that refers to the controlling terminal of the current
--process (if it has one). To find the name of the specific terminal
--device, use `ttyname'; *note Is It a Terminal::..
--
-- The function `ctermid' is declared in the header file `stdio.h'.
--
-- - Function: char * ctermid (char *STRING)
-- The `ctermid' function returns a string containing the file name of
-- the controlling terminal for the current process. If STRING is
-- not a null pointer, it should be an array that can hold at least
-- `L_ctermid' characters; the string is returned in this array.
-- Otherwise, a pointer to a string in a static area is returned,
-- which might get overwritten on subsequent calls to this function.
--
-- An empty string is returned if the file name cannot be determined
-- for any reason. Even if a file name is returned, access to the
-- file it represents is not guaranteed.
--
-- - Macro: int L_ctermid
-- The value of this macro is an integer constant expression that
-- represents the size of a string large enough to hold the file name
-- returned by `ctermid'.
--
-- See also the `isatty' and `ttyname' functions, in *Note Is It a
--Terminal::.
--
--
--File: libc.info, Node: Process Group Functions, Next: Terminal Access
Functions, Prev: Identifying the Terminal, Up: Functions for Job Control
--
--Process Group Functions
-------------------------
--
-- Here are descriptions of the functions for manipulating process
--groups. Your program should include the header files `sys/types.h' and
--`unistd.h' to use these functions.
--
-- - Function: pid_t setsid (void)
-- The `setsid' function creates a new session. The calling process
-- becomes the session leader, and is put in a new process group whose
-- process group ID is the same as the process ID of that process.
-- There are initially no other processes in the new process group,
-- and no other process groups in the new session.
--
-- This function also makes the calling process have no controlling
-- terminal.
--
-- The `setsid' function returns the new process group ID of the
-- calling process if successful. A return value of `-1' indicates an
-- error. The following `errno' error conditions are defined for this
-- function:
--
-- `EPERM'
-- The calling process is already a process group leader, or
-- there is already another process group around that has the
-- same process group ID.
--
-- The `getpgrp' function has two definitions: one derived from BSD
--Unix, and one from the POSIX.1 standard. The feature test macros you
--have selected (*note Feature Test Macros::.) determine which definition
--you get. Specifically, you get the BSD version if you define
--`_BSD_SOURCE'; otherwise, you get the POSIX version if you define
--`_POSIX_SOURCE' or `_GNU_SOURCE'. Programs written for old BSD systems
--will not include `unistd.h', which defines `getpgrp' specially under
--`_BSD_SOURCE'. You must link such programs with the `-lbsd-compat'
--option to get the BSD definition.
--
-- - POSIX.1 Function: pid_t getpgrp (void)
-- The POSIX.1 definition of `getpgrp' returns the process group ID of
-- the calling process.
--
-- - BSD Function: pid_t getpgrp (pid_t PID)
-- The BSD definition of `getpgrp' returns the process group ID of the
-- process PID. You can supply a value of `0' for the PID argument
-- to get information about the calling process.
--
-- - Function: int setpgid (pid_t PID, pid_t PGID)
-- The `setpgid' function puts the process PID into the process group
-- PGID. As a special case, either PID or PGID can be zero to
-- indicate the process ID of the calling process.
--
-- This function fails on a system that does not support job control.
-- *Note Job Control is Optional::, for more information.
--
-- If the operation is successful, `setpgid' returns zero. Otherwise
-- it returns `-1'. The following `errno' error conditions are
-- defined for this function:
--
-- `EACCES'
-- The child process named by PID has executed an `exec'
-- function since it was forked.
--
-- `EINVAL'
-- The value of the PGID is not valid.
--
-- `ENOSYS'
-- The system doesn't support job control.
--
-- `EPERM'
-- The process indicated by the PID argument is a session leader,
-- or is not in the same session as the calling process, or the
-- value of the PGID argument doesn't match a process group ID
-- in the same session as the calling process.
--
-- `ESRCH'
-- The process indicated by the PID argument is not the calling
-- process or a child of the calling process.
--
-- - Function: int setpgrp (pid_t PID, pid_t PGID)
-- This is the BSD Unix name for `setpgid'. Both functions do exactly
-- the same thing.
--
--
--File: libc.info, Node: Terminal Access Functions, Prev: Process Group
Functions, Up: Functions for Job Control
--
--Functions for Controlling Terminal Access
-------------------------------------------
--
-- These are the functions for reading or setting the foreground
--process group of a terminal. You should include the header files
--`sys/types.h' and `unistd.h' in your application to use these functions.
--
-- Although these functions take a file descriptor argument to specify
--the terminal device, the foreground job is associated with the terminal
--file itself and not a particular open file descriptor.
--
-- - Function: pid_t tcgetpgrp (int FILEDES)
-- This function returns the process group ID of the foreground
-- process group associated with the terminal open on descriptor
-- FILEDES.
--
-- If there is no foreground process group, the return value is a
-- number greater than `1' that does not match the process group ID
-- of any existing process group. This can happen if all of the
-- processes in the job that was formerly the foreground job have
-- terminated, and no other job has yet been moved into the
-- foreground.
--
-- In case of an error, a value of `-1' is returned. The following
-- `errno' error conditions are defined for this function:
--
-- `EBADF'
-- The FILEDES argument is not a valid file descriptor.
--
-- `ENOSYS'
-- The system doesn't support job control.
--
-- `ENOTTY'
-- The terminal file associated with the FILEDES argument isn't
-- the controlling terminal of the calling process.
--
-- - Function: int tcsetpgrp (int FILEDES, pid_t PGID)
-- This function is used to set a terminal's foreground process group
-- ID. The argument FILEDES is a descriptor which specifies the
-- terminal; PGID specifies the process group. The calling process
-- must be a member of the same session as PGID and must have the same
-- controlling terminal.
--
-- For terminal access purposes, this function is treated as output.
-- If it is called from a background process on its controlling
-- terminal, normally all processes in the process group are sent a
-- `SIGTTOU' signal. The exception is if the calling process itself
-- is ignoring or blocking `SIGTTOU' signals, in which case the
-- operation is performed and no signal is sent.
--
-- If successful, `tcsetpgrp' returns `0'. A return value of `-1'
-- indicates an error. The following `errno' error conditions are
-- defined for this function:
--
-- `EBADF'
-- The FILEDES argument is not a valid file descriptor.
--
-- `EINVAL'
-- The PGID argument is not valid.
--
-- `ENOSYS'
-- The system doesn't support job control.
--
-- `ENOTTY'
-- The FILEDES isn't the controlling terminal of the calling
-- process.
--
-- `EPERM'
-- The PGID isn't a process group in the same session as the
-- calling process.
--
--
--File: libc.info, Node: Name Service Switch, Next: Users and Groups, Prev:
Job Control, Up: Top
--
--System Databases and Name Service Switch
--****************************************
--
-- Various functions in the C Library need to be configured to work
--correctly in the local environment. Traditionally, this was done by
--using files (e.g., `/etc/passwd'), but other nameservices (line the
--Network Information Service (NIS) and the Domain Name Service (DNS))
--became popular, and were hacked into the C library, usually with a fixed
--search order (*note frobnicate: (jargon)frobnicate.).
--
-- The GNU C Library contains a cleaner solution of this problem. It is
--designed after a method used by Sun Microsystems in the C library of
--Solaris 2. GNU C Library follows their name and calls this scheme
--"Name Service Switch" (NSS).
--
-- Though the interface might be similar to Sun's version there is no
--common code. We never saw any source code of Sun's implementation and
--so the internal interface is incompatible. This is also manifests in
--the file names we use as we will see later.
--
--* Menu:
--
--* NSS Basics:: What is this NSS good for.
--* NSS Configuration File:: Configuring NSS.
--* NSS Module Internals:: How does it work internally.
--* Extending NSS:: What to do to add services or databases.
--
--
--File: libc.info, Node: NSS Basics, Next: NSS Configuration File, Prev:
Name Service Switch, Up: Name Service Switch
--
--NSS Basics
--==========
--
-- The basic idea is to put the implementation of the different services
--offered to access the databases in separate modules. This has some
--advantages:
--
-- 1. Contributors can add new services without adding them to GNU C
-- Library.
--
-- 2. The modules can be updated separately.
--
-- 3. The C library image is smaller.
--
-- To fulfill the first goal above the ABI of the modules will be
--described below. For getting the implementation of a new service right
--it is important to understand how the functions in the modules get
--called. They are in no way designed to be used by the programmer
--directly. Instead the programmer should only use the documented and
--standardized functions to access the databases.
--
--The databases available in the NSS are
--
--`ethers'
-- Ethernet numbers,
--
--`group'
-- Groups of users, *note Group Database::..
--
--`hosts'
-- Host names and numbers, *note Host Names::..
--
--`netgroup'
-- Network wide list of host and users, *note Netgroup Database::..
--
--`network'
-- Network names and numbers, *note Networks Database::..
--
--`protocols'
-- Network protocols, *note Protocols Database::..
--
--`passwd'
-- User passwords, *note User Database::..
--
--`rpc'
-- Remote procedure call names and numbers,
--
--`services'
-- Network services, *note Services Database::..
--
--`shadow'
-- Shadow user passwords,
--
--There will be some more added later (`aliases', `automount',
--`bootparams', `netmasks', and `publickey').
--
--
--File: libc.info, Node: NSS Configuration File, Next: NSS Module Internals,
Prev: NSS Basics, Up: Name Service Switch
--
--The NSS Configuration File
--==========================
--
-- Somehow the NSS code must be told about the wishes of the user. For
--this reason there is the file `/etc/nsswitch.conf'. For each database
--this file contain a specification how the lookup process should work.
--The file could look like this:
--
-- # /etc/nsswitch.conf
-- #
-- # Name Service Switch configuration file.
-- #
--
-- passwd: db files nis
-- shadow: files
-- group: db files nis
--
-- hosts: files nisplus nis dns
-- networks: nisplus [NOTFOUND=return] files
--
-- ethers: nisplus [NOTFOUND=return] db files
-- protocols: nisplus [NOTFOUND=return] db files
-- rpc: nisplus [NOTFOUND=return] db files
-- services: nisplus [NOTFOUND=return] db files
--
-- The first column is the database as you can guess from the table
--above. The rest of the line specifies how the lookup process works.
--Please note that you specify the way it works for each database
--individually. This cannot be done with the old way of a monolithic
--implementation.
--
-- The configuration specification for each database can contain two
--different items:
--
-- * the service specification like `files', `db', or `nis'.
--
-- * the reaction on lookup result line `[NOTFOUND=return]'.
--
--* Menu:
--
--* Services in the NSS configuration:: Service names in the NSS configuration.
--* Actions in the NSS configuration:: React appropriately to the lookup
result.
--* Notes on NSS Configuration File:: Things to take care about while
-- configuring NSS.
--
--
--File: libc.info, Node: Services in the NSS configuration, Next: Actions in
the NSS configuration, Prev: NSS Configuration File, Up: NSS Configuration
File
--
--Services in the NSS configuration File
----------------------------------------
--
-- The above example file mentions four different services: `files',
--`db', `nis', and `nisplus'. This does not mean these services are
--available on all sites and it does also not mean these are all the
--services which will ever be available.
--
-- In fact, these names are simply strings which the NSS code uses to
--find the implicitly addressed functions. The internal interface will be
--described later. Visible to the user are the modules which implement an
--individual service.
--
-- Assume the service NAME shall be used for a lookup. The code for
--this service is implemented in a module called `libnss_NAME'. On a
--system supporting shared libraries this is in fact a shared library
--with the name (for example) `libnss_NAME.so.1'. The number at the end
--is the currently used version of the interface which will not change
--frequently. Normally the user should not have to be cognizant of these
--files since they should be placed in a directory where they are found
--automatically. Only the names of all available services are important.
--
--
--File: libc.info, Node: Actions in the NSS configuration, Next: Notes on NSS
Configuration File, Prev: Services in the NSS configuration, Up: NSS
Configuration File
--
--Actions in the NSS configuration
----------------------------------
--
-- The second item in the specification gives the user much finer
--control on the lookup process. Action items are placed between two
--service names and are written within brackets. The general form is
--
-- `[' ( `!'? STATUS `=' ACTION )+ `]'
--
--where
--
-- STATUS => success | notfound | unavail | tryagain
-- ACTION => return | continue
--
-- The case of the keywords is insignificant. The STATUS values are
--the results of a call to a lookup function of a specific service. They
--mean
--
--`success'
-- No error occurred and the wanted entry is returned. The default
-- action for this is `return'.
--
--`notfound'
-- The lookup process works ok but the needed value was not found.
-- The default action is `continue'.
--
--`unavail'
-- The service is permanently unavailable. This can either mean the
-- needed file is not available, or, for DNS, the server is not
-- available or does not allow queries. The default action is
-- `continue'.
--
--`tryagain'
-- The service is temporarily unavailable. This could mean a file is
-- locked or a server currently cannot accept more connections. The
-- default action is `continue'.
--
--If we have a line like
--
-- ethers: nisplus [NOTFOUND=return] db files
--
--this is equivalent to
--
-- ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue
-- TRYAGAIN=continue]
-- db [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
-- TRYAGAIN=continue]
-- files
--
--(except that it would have to be written on one line). The default
--value for the actions are normally what you want, and only need to be
--changed in exceptional cases.
--
-- If the optional `!' is placed before the STATUS this means the
--following action is used for all statii but STATUS itself. I.e., `!'
--is negation as in the C language (and others).
--
-- Before we explain the exception which makes this action item
--necessary one more remark: obviously it makes no sense to add another
--action item after the `files' service. Since there is no other service
--following the action *always* is `return'.
--
-- Now, why is this `[NOTFOUND=return]' action useful? To understand
--this we should know that the `nisplus' service is often complete; i.e.,
--if an entry is not available in the NIS+ tables it is not available
--anywhere else. This is what is expressed by this action item: it is
--useless to examine further services since they will not give us a
--result.
--
-- The situation would be different if the NIS+ service is not available
--because the machine is booting. In this case the return value of the
--lookup function is not `notfound' but instead `unavail'. And as you
--can see in the complete form above: in this situation the `db' and
--`files' services are used. Neat, isn't it? The system administrator
--need not pay special care for the time the system is not completely
--ready to work (while booting or shutdown or network problems).
--
--
--File: libc.info, Node: Notes on NSS Configuration File, Prev: Actions in
the NSS configuration, Up: NSS Configuration File
--
--Notes on the NSS Configuration File
-------------------------------------
--
-- Finally a few more hints. The NSS implementation is not completely
--helpless if `/etc/nsswitch.conf' does not exist. For all supported
--databases there is a default value so it should normally be possible to
--get the system running even if the file is corrupted or missing.
--
-- For the `hosts' and `network' databases the default value is `dns
--[!UNAVAIL=return] files'. I.e., the system is prepared for the DNS
--service not to be available but if it is available the answer it
--returns is ultimative.
--
-- The `passwd', `group', and `shadow' databases are traditionally
--handled in a special way. The appropriate files in the `/etc'
--directory are read but if an entry with a name starting with a `+'
--character is found NIS is used. This kind of lookup remains possible
--by using the special lookup service `compat' and the default value for
--the three databases above is `compat [NOTFOUND=return] files'.
--
-- For all other databases the default value is `nis [NOTFOUND=return]
--files'. This solution give the best chance to be correct since NIS and
--file based lookup is used.
--
-- A second point is that the user should try to optimize the lookup
--process. The different service have different response times. A
--simple file look up on a local file could be fast, but if the file is
--long and the needed entry is near the end of the file this may take
--quite some time. In this case it might be better to use the `db'
--service which allows fast local access to large data sets.
--
-- Often the situation is that some global information like NIS must be
--used. So it is unavoidable to use service entries like `nis' etc. But
--one should avoid slow services like this if possible.
--
--
--File: libc.info, Node: NSS Module Internals, Next: Extending NSS, Prev:
NSS Configuration File, Up: Name Service Switch
--
--NSS Module Internals
--====================
--
-- Now it is time to described how the modules look like. The functions
--contained in a module are identified by their names. I.e., there is no
--jump table or the like. How this is done is of no interest here; those
--interested in this topic should read about Dynamic Linking.
--
--* Menu:
--
--* NSS Module Names:: Construction of the interface function of
-- the NSS modules.
--* NSS Modules Interface:: Programming interface in the NSS module
-- functions.
--
--
--File: libc.info, Node: NSS Module Names, Next: NSS Modules Interface,
Prev: NSS Module Internals, Up: NSS Module Internals
--
--The Naming Scheme of the NSS Modules
--------------------------------------
--
--The name of each function consist of various parts:
--
-- _nss_SERVICE_FUNCTION
--
-- SERVICE of course corresponds to the name of the module this
--function is found in.(1) The FUNCTION part is derived from the
--interface function in the C library itself. If the user calls the
--function `gethostbyname' and the service used is `files' the function
--
-- _nss_files_gethostbyname_r
--
--in the module
--
-- libnss_files.so.1
--
--is used. You see, what is explained above in not the whole truth. In
--fact the NSS modules only contain reentrant versions of the lookup
--functions. I.e., if the user would call the `gethostbyname_r' function
--this also would end in the above function. For all user interface
--functions the C library maps this call to a call to the reentrant
--function. For reentrant functions this is trivial since the interface
--is (nearly) the same. For the non-reentrant version pointers to static
--buffers are used to replace the user supplied buffers.
--
-- I.e., the reentrant functions *can* have counterparts. No service
--module is forced to have functions for all databases and all kinds to
--access them. If a function is not available it is simply treated as if
--the function would return `unavail' (*note Actions in the NSS
--configuration::.).
--
-- The file name `libnss_files.so.1' would be on a Solaris 2 system
--`nss_files.so.1'. This is the difference mentioned above. Sun's NSS
--modules are usable as modules which get indirectly loaded only.
--
-- The NSS modules in the GNU C Library are prepared to be used as
--normal libraries itself. This is *not* true in the moment, though.
--But the different organization of the name space in the modules does
--not make it impossible like it is for Solaris. Now you can see why the
--modules are still libraries.(2)
--
-- ---------- Footnotes ----------
--
-- (1) Now you might ask why to duplicate this information. The
--answer is that we want to keep the possibility to link directly with
--these shared objects.
--
-- (2) There is a second explanation: we were too lazy to change the
--Makefiles to allow the generation of shared objects not starting with
--`lib' but do not tell this anybody.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-25
glibc-2.0.1/manual/libc.info-25
---- ../glibc-2.0.1/manual/libc.info-25 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-25 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1217 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: NSS Modules Interface, Prev: NSS Module Names, Up:
NSS Module Internals
--
--The Interface of the Function in NSS Modules
----------------------------------------------
--
-- Now we know about the functions contained in the modules. It is now
--time to describe the types. When we mentioned the reentrant versions of
--the functions above, this means there are some additional arguments
--(compared with the standard, non-reentrant version). The prototypes for
--the non-reentrant and reentrant versions of our function above are:
--
-- struct hostent *gethostbyname (const char *name)
--
-- int gethostbyname_r (const char *name, struct hostent *result_buf,
-- char *buf, size_t buflen, struct hostent **result,
-- int *h_errnop)
--
--The actual prototype of the function in the NSS modules in this case is
--
-- enum nss_status _nss_files_gethostbyname_r (const char *name,
-- struct hostent *result_buf,
-- char *buf, size_t buflen,
-- int *h_errnop)
--
-- I.e., the interface function is in fact the reentrant function with
--the change of the return value. While the user-level function returns a
--pointer to the result the reentrant function return an `enum
--nss_status' value:
--
--`NSS_STATUS_TRYAGAIN'
-- numeric value `-2'
--
--`NSS_STATUS_UNAVAIL'
-- numeric value `-1'
--
--`NSS_STATUS_NOTFOUND'
-- numeric value `0'
--
--`NSS_STATUS_SUCCESS'
-- numeric value `1'
--
--Now you see where the action items of the `/etc/nsswitch.conf' file are
--used.
--
-- If you study the source code you will find there is a fifth value:
--`NSS_STATUS_RETURN'. This is an internal use only value, used by a few
--functions in places where none of the above value can be used. If
--necessary the source code should be examined to learn about the details.
--
-- The above function has something special which is missing for almost
--all the other module functions. There is an argument H_ERRNOP. This
--points to a variable which will be filled with the error code in case
--the execution of the function fails for some reason. The reentrant
--function cannot use the global variable H_ERRNO; `gethostbyname' calls
--`gethostbyname_r' with the last argument set to `&h_errno'.
--
-- The `getXXXbyYYY' functions are the most important functions in the
--NSS modules. But there are others which implement the other ways to
--access system databases (say for the password database, there are
--`setpwent', `getpwent', and `endpwent'). These will be described in
--more detail later. Here we give a general way to determine the
--signature of the module function:
--
-- * the return value is `int';
--
-- * the name is as explain in *note NSS Module Names::.;
--
-- * the first arguments are identical to the arguments of the
-- non-reentrant function;
--
-- * the next three arguments are:
--
-- `STRUCT_TYPE result_buf'
-- pointer to buffer where the result is stored. `STRUCT_TYPE'
-- is normally a struct which corresponds to the database.
--
-- `char *buffer'
-- pointer to a buffer where the function can store additional
-- adata for the result etc.
--
-- `int buflen'
-- length of the buffer pointed to by BUFFER.
--
-- * possibly a last argument H_ERRNOP, for the host name and network
-- name lookup functions.
--
--This table is correct for all functions but the `set...ent' and
--`end...ent' functions.
--
--
--File: libc.info, Node: Extending NSS, Prev: NSS Module Internals, Up: Name
Service Switch
--
--Extending NSS
--=============
--
-- One of the advantages of NSS mentioned above is that it can be
--extended quite easily. There are two ways in which the extension can
--happen: adding another database or adding another service. The former
--is normally done only by the C library developers. It is here only
--important to remember that adding another database is independent from
--adding another service because a service need not support all databases
--or lookup functions.
--
-- A designer/implementor of a new service is therefore free to choose
--the databases s/he is interested in and leave the rest for later (or
--completely aside).
--
--* Menu:
--
--* Adding another Service to NSS:: What is to do to add a new service.
--* NSS Module Function Internals:: Guidelines for writing new NSS
-- service functions.
--
--
--File: libc.info, Node: Adding another Service to NSS, Next: NSS Module
Function Internals, Prev: Extending NSS, Up: Extending NSS
--
--Adding another Service to NSS
-------------------------------
--
-- The sources for a new service need not (and should not) be part of
--the GNU C Library itself. The developer retains complete control over
--the sources and its development. The links between the C library and
--the new service module consists solely of the interface functions.
--
-- Each module is designed following a specific interface specification.
--For now the version is 1 and this manifests in the version number of the
--shared library object of the NSS modules: they have the extension `.1'.
--If the interface ever changes in an incompatible way, this number will
--be increased--hopefully this will never be necessary. Modules using
--the old interface will still be usable.
--
-- Developers of a new service will have to make sure that their module
--is created using the correct interface number. This means the file
--itself must have the correct name and on ElF systems the "soname"
--(Shared Object Name) must also have this number. Building a module
--from a bunch of object files on an ELF system using GNU CC could be
--done like this:
--
-- gcc -shared -o libnss_NAME.so.1 -Wl,-soname,libnss_NAME.so.1 OBJECTS
--
--*Note Options for Linking: (gcc)Link Options, to learn more about this
--command line.
--
-- To use the new module the library must be able to find it. This can
--be achieved by using options for the dynamic linker so that it will
--search directory where the binary is placed. For an ELF system this
--could be done by adding the wanted directory to the value of
--`LD_LIBRARY_PATH'.
--
-- But this is not always possible since some program (those which run
--under IDs which do not belong to the user) ignore this variable.
--Therefore the stable version of the module should be placed into a
--directory which is searched by the dynamic linker. Normally this should
--be the directory `$prefix/lib', where `$prefix' corresponds to the
--value given to configure using the `--prefix' option. But be careful:
--this should only be done if it is clear the module does not cause any
--harm. System administrators should be careful.
--
--
--File: libc.info, Node: NSS Module Function Internals, Prev: Adding another
Service to NSS, Up: Extending NSS
--
--Internals of the NSS Module Functions
---------------------------------------
--
-- Until now we only provided the syntactic interface for the functions
--in the NSS module. In fact there is not more much we can tell since the
--implementation obviously is different for each function. But a few
--general rules must be followed by all functions.
--
-- In fact there are four kinds of different functions which may appear
--in the interface. All derive from the traditional ones for system
--databases. DB in the following table is normally an abbreviation for
--the database (e.g., it is `pw' for the password database).
--
--`enum nss_status _nss_DATABASE_setDBent (void)'
-- This function prepares the service for following operations. For a
-- simple file based lookup this means files could be opened, for
-- other services this function simply is a noop.
--
-- One special case for this function is that it takes an additional
-- argument for some DATABASEs (i.e., the interface is `int setDBent
-- (int)'). *Note Host Names::, which describes the `sethostent'
-- function.
--
-- The return value should be NSS_STATUS_SUCCESS or according to the
-- table above in case of an error (*note NSS Modules Interface::.).
--
--`enum nss_status _nss_DATABASE_endDBent (void)'
-- This function simply closes all files which are still open or
-- removes buffer caches. If there are no files or buffers to remove
-- this is again a simple noop.
--
-- There normally is no return value different to NSS_STATUS_SUCCESS.
--
--`enum nss_status _nss_DATABASE_getDBent_r (STRUCTURE *result, char *buffer,
size_t buflen)'
-- Since this function will be called several times in a row to
-- retrieve one entry after the other it must keep some kind of
-- state. But this also means the functions are not really
-- reentrant. They are reentrant only in that simultaneous calls to
-- this function will not try to write the retrieved data in the same
-- place (as it would be the case for the non-reentrant functions);
-- instead, it writes to the structure pointed to by the RESULT
-- parameter. But the calls share a common state and in the case of
-- a file access this means they return neighboring entries in the
-- file.
--
-- The buffer of length BUFLEN pointed to by BUFFER can be used for
-- storing some additional data for the result. It is *not*
-- guaranteed that the same buffer will be passed for the next call
-- of this function. Therefore one must not misuse this buffer to
-- save some state information from one call to another.
--
-- As explained above this function could also have an additional last
-- argument. This depends on the database used; it happens only for
-- `host' and `network'.
--
-- The function shall return `NSS_STATUS_SUCCESS' as long as their are
-- more entries. When the last entry was read it should return
-- `NSS_STATUS_NOTFOUND'. When the buffer given as an argument is too
-- small for the data to be returned `NSS_STATUS_TRYAGAIN' should be
-- returned. When the service was not formerly initialized by a call
-- to `_nss_DATABASE_setDBent' all return value allowed for this
-- function can also be returned here.
--
--`enum nss_status _nss_DATABASE_getDBbyXX_r (PARAMS, STRUCTURE *result, char
*buffer, size_t buflen)'
-- This function shall return the entry from the database which is
-- addressed by the PARAMS. The type and number of these arguments
-- vary. It must be individually determined by looking to the
-- user-level interface functions. All arguments given to the
-- non-reentrant version are here described by PARAMS.
--
-- The result must be stored in the structure pointed to by RESULT.
-- If there is additional data to return (say strings, where the
-- RESULT structure only contains pointers) the function must use the
-- BUFFER or length BUFLEN. There must not be any references to
-- non-constant global data.
--
-- The implementation of this function should honour the STAYOPEN
-- flag set by the `setDBent' function whenever this makes sense.
--
-- Again, this function takes an additional last argument for the
-- `host' and `network' database.
--
-- The return value should as always follow the rules given above
-- (*note NSS Modules Interface::.).
--
--
--File: libc.info, Node: Users and Groups, Next: System Information, Prev:
Name Service Switch, Up: Top
--
--Users and Groups
--****************
--
-- Every user who can log in on the system is identified by a unique
--number called the "user ID". Each process has an effective user ID
--which says which user's access permissions it has.
--
-- Users are classified into "groups" for access control purposes. Each
--process has one or more "group ID values" which say which groups the
--process can use for access to files.
--
-- The effective user and group IDs of a process collectively form its
--"persona". This determines which files the process can access.
--Normally, a process inherits its persona from the parent process, but
--under special circumstances a process can change its persona and thus
--change its access permissions.
--
-- Each file in the system also has a user ID and a group ID. Access
--control works by comparing the user and group IDs of the file with those
--of the running process.
--
-- The system keeps a database of all the registered users, and another
--database of all the defined groups. There are library functions you
--can use to examine these databases.
--
--* Menu:
--
--* User and Group IDs:: Each user has a unique numeric ID;
-- likewise for groups.
--* Process Persona:: The user IDs and group IDs of a process.
--* Why Change Persona:: Why a program might need to change
-- its user and/or group IDs.
--* How Change Persona:: Changing the user and group IDs.
--* Reading Persona:: How to examine the user and group IDs.
--
--* Setting User ID:: Functions for setting the user ID.
--* Setting Groups:: Functions for setting the group IDs.
--
--* Enable/Disable Setuid:: Turning setuid access on and off.
--* Setuid Program Example:: The pertinent parts of one sample program.
--* Tips for Setuid:: How to avoid granting unlimited access.
--
--* Who Logged In:: Getting the name of the user who logged in,
-- or of the real user ID of the current process.
--
--* User Database:: Functions and data structures for
-- accessing the user database.
--* Group Database:: Functions and data structures for
-- accessing the group database.
--* Netgroup Database:: Functions for accessing the netgroup database.
--* Database Example:: Example program showing use of database
-- inquiry functions.
--
--
--File: libc.info, Node: User and Group IDs, Next: Process Persona, Prev:
Users and Groups, Up: Users and Groups
--
--User and Group IDs
--==================
--
-- Each user account on a computer system is identified by a "user
--name" (or "login name") and "user ID". Normally, each user name has a
--unique user ID, but it is possible for several login names to have the
--same user ID. The user names and corresponding user IDs are stored in
--a data base which you can access as described in *Note User Database::.
--
-- Users are classified in "groups". Each user name also belongs to
--one or more groups, and has one "default group". Users who are members
--of the same group can share resources (such as files) that are not
--accessible to users who are not a member of that group. Each group has
--a "group name" and "group ID". *Note Group Database::, for how to find
--information about a group ID or group name.
--
--
--File: libc.info, Node: Process Persona, Next: Why Change Persona, Prev:
User and Group IDs, Up: Users and Groups
--
--The Persona of a Process
--========================
--
-- At any time, each process has a single user ID and a group ID which
--determine the privileges of the process. These are collectively called
--the "persona" of the process, because they determine "who it is" for
--purposes of access control. These IDs are also called the "effective
--user ID" and "effective group ID" of the process.
--
-- Your login shell starts out with a persona which consists of your
--user ID and your default group ID. In normal circumstances, all your
--other processes inherit these values.
--
-- A process also has a "real user ID" which identifies the user who
--created the process, and a "real group ID" which identifies that user's
--default group. These values do not play a role in access control, so
--we do not consider them part of the persona. But they are also
--important.
--
-- Both the real and effective user ID can be changed during the
--lifetime of a process. *Note Why Change Persona::.
--
-- In addition, a user can belong to multiple groups, so the persona
--includes "supplementary group IDs" that also contribute to access
--permission.
--
-- For details on how a process's effective user IDs and group IDs
--affect its permission to access files, see *Note Access Permission::.
--
-- The user ID of a process also controls permissions for sending
--signals using the `kill' function. *Note Signaling Another Process::.
--
--
--File: libc.info, Node: Why Change Persona, Next: How Change Persona, Prev:
Process Persona, Up: Users and Groups
--
--Why Change the Persona of a Process?
--====================================
--
-- The most obvious situation where it is necessary for a process to
--change its user and/or group IDs is the `login' program. When `login'
--starts running, its user ID is `root'. Its job is to start a shell
--whose user and group IDs are those of the user who is logging in. (To
--accomplish this fully, `login' must set the real user and group IDs as
--well as its persona. But this is a special case.)
--
-- The more common case of changing persona is when an ordinary user
--program needs access to a resource that wouldn't ordinarily be
--accessible to the user actually running it.
--
-- For example, you may have a file that is controlled by your program
--but that shouldn't be read or modified directly by other users, either
--because it implements some kind of locking protocol, or because you want
--to preserve the integrity or privacy of the information it contains.
--This kind of restricted access can be implemented by having the program
--change its effective user or group ID to match that of the resource.
--
-- Thus, imagine a game program that saves scores in a file. The game
--program itself needs to be able to update this file no matter who is
--running it, but if users can write the file without going through the
--game, they can give themselves any scores they like. Some people
--consider this undesirable, or even reprehensible. It can be prevented
--by creating a new user ID and login name (say, `games') to own the
--scores file, and make the file writable only by this user. Then, when
--the game program wants to update this file, it can change its effective
--user ID to be that for `games'. In effect, the program must adopt the
--persona of `games' so it can write the scores file.
--
--
--File: libc.info, Node: How Change Persona, Next: Reading Persona, Prev:
Why Change Persona, Up: Users and Groups
--
--How an Application Can Change Persona
--=====================================
--
-- The ability to change the persona of a process can be a source of
--unintentional privacy violations, or even intentional abuse. Because of
--the potential for problems, changing persona is restricted to special
--circumstances.
--
-- You can't arbitrarily set your user ID or group ID to anything you
--want; only privileged processes can do that. Instead, the normal way
--for a program to change its persona is that it has been set up in
--advance to change to a particular user or group. This is the function
--of the setuid and setgid bits of a file's access mode. *Note
--Permission Bits::.
--
-- When the setuid bit of an executable file is set, executing that file
--automatically changes the effective user ID to the user that owns the
--file. Likewise, executing a file whose setgid bit is set changes the
--effective group ID to the group of the file. *Note Executing a File::.
--Creating a file that changes to a particular user or group ID thus
--requires full access to that user or group ID.
--
-- *Note File Attributes::, for a more general discussion of file modes
--and accessibility.
--
-- A process can always change its effective user (or group) ID back to
--its real ID. Programs do this so as to turn off their special
--privileges when they are not needed, which makes for more robustness.
--
--
--File: libc.info, Node: Reading Persona, Next: Setting User ID, Prev: How
Change Persona, Up: Users and Groups
--
--Reading the Persona of a Process
--================================
--
-- Here are detailed descriptions of the functions for reading the user
--and group IDs of a process, both real and effective. To use these
--facilities, you must include the header files `sys/types.h' and
--`unistd.h'.
--
-- - Data Type: uid_t
-- This is an integer data type used to represent user IDs. In the
-- GNU library, this is an alias for `unsigned int'.
--
-- - Data Type: gid_t
-- This is an integer data type used to represent group IDs. In the
-- GNU library, this is an alias for `unsigned int'.
--
-- - Function: uid_t getuid (void)
-- The `getuid' function returns the real user ID of the process.
--
-- - Function: gid_t getgid (void)
-- The `getgid' function returns the real group ID of the process.
--
-- - Function: uid_t geteuid (void)
-- The `geteuid' function returns the effective user ID of the
-- process.
--
-- - Function: gid_t getegid (void)
-- The `getegid' function returns the effective group ID of the
-- process.
--
-- - Function: int getgroups (int COUNT, gid_t *GROUPS)
-- The `getgroups' function is used to inquire about the supplementary
-- group IDs of the process. Up to COUNT of these group IDs are
-- stored in the array GROUPS; the return value from the function is
-- the number of group IDs actually stored. If COUNT is smaller than
-- the total number of supplementary group IDs, then `getgroups'
-- returns a value of `-1' and `errno' is set to `EINVAL'.
--
-- If COUNT is zero, then `getgroups' just returns the total number
-- of supplementary group IDs. On systems that do not support
-- supplementary groups, this will always be zero.
--
-- Here's how to use `getgroups' to read all the supplementary group
-- IDs:
--
-- gid_t *
-- read_all_groups (void)
-- {
-- int ngroups = getgroups (0, NULL);
-- gid_t *groups
-- = (gid_t *) xmalloc (ngroups * sizeof (gid_t));
-- int val = getgroups (ngroups, groups);
-- if (val < 0)
-- {
-- free (groups);
-- return NULL;
-- }
-- return groups;
-- }
--
--
--File: libc.info, Node: Setting User ID, Next: Setting Groups, Prev:
Reading Persona, Up: Users and Groups
--
--Setting the User ID
--===================
--
-- This section describes the functions for altering the user ID (real
--and/or effective) of a process. To use these facilities, you must
--include the header files `sys/types.h' and `unistd.h'.
--
-- - Function: int setuid (uid_t NEWUID)
-- This function sets both the real and effective user ID of the
-- process to NEWUID, provided that the process has appropriate
-- privileges.
--
-- If the process is not privileged, then NEWUID must either be equal
-- to the real user ID or the saved user ID (if the system supports
-- the `_POSIX_SAVED_IDS' feature). In this case, `setuid' sets only
-- the effective user ID and not the real user ID.
--
-- The `setuid' function returns a value of `0' to indicate
-- successful completion, and a value of `-1' to indicate an error.
-- The following `errno' error conditions are defined for this
-- function:
--
-- `EINVAL'
-- The value of the NEWUID argument is invalid.
--
-- `EPERM'
-- The process does not have the appropriate privileges; you do
-- not have permission to change to the specified ID.
--
-- - Function: int setreuid (uid_t RUID, uid_t EUID)
-- This function sets the real user ID of the process to RUID and the
-- effective user ID to EUID. If RUID is `-1', it means not to
-- change the real user ID; likewise if EUID is `-1', it means not to
-- change the effective user ID.
--
-- The `setreuid' function exists for compatibility with 4.3 BSD Unix,
-- which does not support saved IDs. You can use this function to
-- swap the effective and real user IDs of the process. (Privileged
-- processes are not limited to this particular usage.) If saved IDs
-- are supported, you should use that feature instead of this
-- function. *Note Enable/Disable Setuid::.
--
-- The return value is `0' on success and `-1' on failure. The
-- following `errno' error conditions are defined for this function:
--
-- `EPERM'
-- The process does not have the appropriate privileges; you do
-- not have permission to change to the specified ID.
--
--
--File: libc.info, Node: Setting Groups, Next: Enable/Disable Setuid, Prev:
Setting User ID, Up: Users and Groups
--
--Setting the Group IDs
--=====================
--
-- This section describes the functions for altering the group IDs (real
--and effective) of a process. To use these facilities, you must include
--the header files `sys/types.h' and `unistd.h'.
--
-- - Function: int setgid (gid_t NEWGID)
-- This function sets both the real and effective group ID of the
-- process to NEWGID, provided that the process has appropriate
-- privileges.
--
-- If the process is not privileged, then NEWGID must either be equal
-- to the real group ID or the saved group ID. In this case, `setgid'
-- sets only the effective group ID and not the real group ID.
--
-- The return values and error conditions for `setgid' are the same
-- as those for `setuid'.
--
-- - Function: int setregid (gid_t RGID, fid_t EGID)
-- This function sets the real group ID of the process to RGID and
-- the effective group ID to EGID. If RGID is `-1', it means not to
-- change the real group ID; likewise if EGID is `-1', it means not
-- to change the effective group ID.
--
-- The `setregid' function is provided for compatibility with 4.3 BSD
-- Unix, which does not support saved IDs. You can use this function
-- to swap the effective and real group IDs of the process.
-- (Privileged processes are not limited to this usage.) If saved
-- IDs are supported, you should use that feature instead of using
-- this function. *Note Enable/Disable Setuid::.
--
-- The return values and error conditions for `setregid' are the same
-- as those for `setreuid'.
--
-- The GNU system also lets privileged processes change their
--supplementary group IDs. To use `setgroups' or `initgroups', your
--programs should include the header file `grp.h'.
--
-- - Function: int setgroups (size_t COUNT, gid_t *GROUPS)
-- This function sets the process's supplementary group IDs. It can
-- only be called from privileged processes. The COUNT argument
-- specifies the number of group IDs in the array GROUPS.
--
-- This function returns `0' if successful and `-1' on error. The
-- following `errno' error conditions are defined for this function:
--
-- `EPERM'
-- The calling process is not privileged.
--
-- - Function: int initgroups (const char *USER, gid_t GID)
-- The `initgroups' function effectively calls `setgroups' to set the
-- process's supplementary group IDs to be the normal default for the
-- user name USER. The group ID GID is also included.
--
--
--File: libc.info, Node: Enable/Disable Setuid, Next: Setuid Program Example,
Prev: Setting Groups, Up: Users and Groups
--
--Enabling and Disabling Setuid Access
--====================================
--
-- A typical setuid program does not need its special access all of the
--time. It's a good idea to turn off this access when it isn't needed,
--so it can't possibly give unintended access.
--
-- If the system supports the saved user ID feature, you can accomplish
--this with `setuid'. When the game program starts, its real user ID is
--`jdoe', its effective user ID is `games', and its saved user ID is also
--`games'. The program should record both user ID values once at the
--beginning, like this:
--
-- user_user_id = getuid ();
-- game_user_id = geteuid ();
--
-- Then it can turn off game file access with
--
-- setuid (user_user_id);
--
--and turn it on with
--
-- setuid (game_user_id);
--
--Throughout this process, the real user ID remains `jdoe' and the saved
--user ID remains `games', so the program can always set its effective
--user ID to either one.
--
-- On other systems that don't support the saved user ID feature, you
--can turn setuid access on and off by using `setreuid' to swap the real
--and effective user IDs of the process, as follows:
--
-- setreuid (geteuid (), getuid ());
--
--This special case is always allowed--it cannot fail.
--
-- Why does this have the effect of toggling the setuid access?
--Suppose a game program has just started, and its real user ID is `jdoe'
--while its effective user ID is `games'. In this state, the game can
--write the scores file. If it swaps the two uids, the real becomes
--`games' and the effective becomes `jdoe'; now the program has only
--`jdoe' access. Another swap brings `games' back to the effective user
--ID and restores access to the scores file.
--
-- In order to handle both kinds of systems, test for the saved user ID
--feature with a preprocessor conditional, like this:
--
-- #ifdef _POSIX_SAVED_IDS
-- setuid (user_user_id);
-- #else
-- setreuid (geteuid (), getuid ());
-- #endif
--
--
--File: libc.info, Node: Setuid Program Example, Next: Tips for Setuid,
Prev: Enable/Disable Setuid, Up: Users and Groups
--
--Setuid Program Example
--======================
--
-- Here's an example showing how to set up a program that changes its
--effective user ID.
--
-- This is part of a game program called `caber-toss' that manipulates
--a file `scores' that should be writable only by the game program
--itself. The program assumes that its executable file will be installed
--with the set-user-ID bit set and owned by the same user as the `scores'
--file. Typically, a system administrator will set up an account like
--`games' for this purpose.
--
-- The executable file is given mode `4755', so that doing an `ls -l'
--on it produces output like:
--
-- -rwsr-xr-x 1 games 184422 Jul 30 15:17 caber-toss
--
--The set-user-ID bit shows up in the file modes as the `s'.
--
-- The scores file is given mode `644', and doing an `ls -l' on it
--shows:
--
-- -rw-r--r-- 1 games 0 Jul 31 15:33 scores
--
-- Here are the parts of the program that show how to set up the changed
--user ID. This program is conditionalized so that it makes use of the
--saved IDs feature if it is supported, and otherwise uses `setreuid' to
--swap the effective and real user IDs.
--
-- #include <stdio.h>
-- #include <sys/types.h>
-- #include <unistd.h>
-- #include <stdlib.h>
--
--
-- /* Save the effective and real UIDs. */
--
-- static uid_t euid, ruid;
--
--
-- /* Restore the effective UID to its original value. */
--
-- void
-- do_setuid (void)
-- {
-- int status;
--
-- #ifdef _POSIX_SAVED_IDS
-- status = setuid (euid);
-- #else
-- status = setreuid (ruid, euid);
-- #endif
-- if (status < 0) {
-- fprintf (stderr, "Couldn't set uid.\n");
-- exit (status);
-- }
-- }
-- /* Set the effective UID to the real UID. */
--
-- void
-- undo_setuid (void)
-- {
-- int status;
--
-- #ifdef _POSIX_SAVED_IDS
-- status = setuid (ruid);
-- #else
-- status = setreuid (euid, ruid);
-- #endif
-- if (status < 0) {
-- fprintf (stderr, "Couldn't set uid.\n");
-- exit (status);
-- }
-- }
--
-- /* Main program. */
--
-- int
-- main (void)
-- {
-- /* Save the real and effective user IDs. */
-- ruid = getuid ();
-- euid = geteuid ();
-- undo_setuid ();
--
-- /* Do the game and record the score. */
-- ...
-- }
--
-- Notice how the first thing the `main' function does is to set the
--effective user ID back to the real user ID. This is so that any other
--file accesses that are performed while the user is playing the game use
--the real user ID for determining permissions. Only when the program
--needs to open the scores file does it switch back to the original
--effective user ID, like this:
--
-- /* Record the score. */
--
-- int
-- record_score (int score)
-- {
-- FILE *stream;
-- char *myname;
--
-- /* Open the scores file. */
-- do_setuid ();
-- stream = fopen (SCORES_FILE, "a");
-- undo_setuid ();
-- /* Write the score to the file. */
-- if (stream)
-- {
-- myname = cuserid (NULL);
-- if (score < 0)
-- fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
-- else
-- fprintf (stream, "%10s: %d feet.\n", myname, score);
-- fclose (stream);
-- return 0;
-- }
-- else
-- return -1;
-- }
--
--
--File: libc.info, Node: Tips for Setuid, Next: Who Logged In, Prev: Setuid
Program Example, Up: Users and Groups
--
--Tips for Writing Setuid Programs
--================================
--
-- It is easy for setuid programs to give the user access that isn't
--intended--in fact, if you want to avoid this, you need to be careful.
--Here are some guidelines for preventing unintended access and
--minimizing its consequences when it does occur:
--
-- * Don't have `setuid' programs with privileged user IDs such as
-- `root' unless it is absolutely necessary. If the resource is
-- specific to your particular program, it's better to define a new,
-- nonprivileged user ID or group ID just to manage that resource.
--
-- * Be cautious about using the `system' and `exec' functions in
-- combination with changing the effective user ID. Don't let users
-- of your program execute arbitrary programs under a changed user ID.
-- Executing a shell is especially bad news. Less obviously, the
-- `execlp' and `execvp' functions are a potential risk (since the
-- program they execute depends on the user's `PATH' environment
-- variable).
--
-- If you must `exec' another program under a changed ID, specify an
-- absolute file name (*note File Name Resolution::.) for the
-- executable, and make sure that the protections on that executable
-- and *all* containing directories are such that ordinary users
-- cannot replace it with some other program.
--
-- * Only use the user ID controlling the resource in the part of the
-- program that actually uses that resource. When you're finished
-- with it, restore the effective user ID back to the actual user's
-- user ID. *Note Enable/Disable Setuid::.
--
-- * If the `setuid' part of your program needs to access other files
-- besides the controlled resource, it should verify that the real
-- user would ordinarily have permission to access those files. You
-- can use the `access' function (*note Access Permission::.) to
-- check this; it uses the real user and group IDs, rather than the
-- effective IDs.
--
--
--File: libc.info, Node: Who Logged In, Next: User Database, Prev: Tips for
Setuid, Up: Users and Groups
--
--Identifying Who Logged In
--=========================
--
-- You can use the functions listed in this section to determine the
--login name of the user who is running a process, and the name of the
--user who logged in the current session. See also the function `getuid'
--and friends (*note Reading Persona::.).
--
-- The `getlogin' function is declared in `unistd.h', while `cuserid'
--and `L_cuserid' are declared in `stdio.h'.
--
-- - Function: char * getlogin (void)
-- The `getlogin' function returns a pointer to a string containing
-- the name of the user logged in on the controlling terminal of the
-- process, or a null pointer if this information cannot be
-- determined. The string is statically allocated and might be
-- overwritten on subsequent calls to this function or to `cuserid'.
--
-- - Function: char * cuserid (char *STRING)
-- The `cuserid' function returns a pointer to a string containing a
-- user name associated with the effective ID of the process. If
-- STRING is not a null pointer, it should be an array that can hold
-- at least `L_cuserid' characters; the string is returned in this
-- array. Otherwise, a pointer to a string in a static area is
-- returned. This string is statically allocated and might be
-- overwritten on subsequent calls to this function or to `getlogin'.
--
-- The use of this function is deprecated since it is marked to be
-- withdrawn in XPG4.2 and it is already removed in POSIX.1.
--
-- - Macro: int L_cuserid
-- An integer constant that indicates how long an array you might
-- need to store a user name.
--
-- These functions let your program identify positively the user who is
--running or the user who logged in this session. (These can differ when
--setuid programs are involved; *Note Process Persona::.) The user cannot
--do anything to fool these functions.
--
-- For most purposes, it is more useful to use the environment variable
--`LOGNAME' to find out who the user is. This is more flexible precisely
--because the user can set `LOGNAME' arbitrarily. *Note Standard
--Environment::.
--
--
--File: libc.info, Node: User Database, Next: Group Database, Prev: Who
Logged In, Up: Users and Groups
--
--User Database
--=============
--
-- This section describes all about how to search and scan the database
--of registered users. The database itself is kept in the file
--`/etc/passwd' on most systems, but on some systems a special network
--server gives access to it.
--
--* Menu:
--
--* User Data Structure:: What each user record contains.
--* Lookup User:: How to look for a particular user.
--* Scanning All Users:: Scanning the list of all users, one by one.
--* Writing a User Entry:: How a program can rewrite a user's record.
--
--
--File: libc.info, Node: User Data Structure, Next: Lookup User, Prev: User
Database, Up: User Database
--
--The Data Structure that Describes a User
------------------------------------------
--
-- The functions and data structures for accessing the system user
--database are declared in the header file `pwd.h'.
--
-- - Data Type: struct passwd
-- The `passwd' data structure is used to hold information about
-- entries in the system user data base. It has at least the
-- following members:
--
-- `char *pw_name'
-- The user's login name.
--
-- `char *pw_passwd.'
-- The encrypted password string.
--
-- `uid_t pw_uid'
-- The user ID number.
--
-- `gid_t pw_gid'
-- The user's default group ID number.
--
-- `char *pw_gecos'
-- A string typically containing the user's real name, and
-- possibly other information such as a phone number.
--
-- `char *pw_dir'
-- The user's home directory, or initial working directory.
-- This might be a null pointer, in which case the
-- interpretation is system-dependent.
--
-- `char *pw_shell'
-- The user's default shell, or the initial program run when the
-- user logs in. This might be a null pointer, indicating that
-- the system default should be used.
--
--
--File: libc.info, Node: Lookup User, Next: Scanning All Users, Prev: User
Data Structure, Up: User Database
--
--Looking Up One User
---------------------
--
-- You can search the system user database for information about a
--specific user using `getpwuid' or `getpwnam'. These functions are
--declared in `pwd.h'.
--
-- - Function: struct passwd * getpwuid (uid_t UID)
-- This function returns a pointer to a statically-allocated structure
-- containing information about the user whose user ID is UID. This
-- structure may be overwritten on subsequent calls to `getpwuid'.
--
-- A null pointer value indicates there is no user in the data base
-- with user ID UID.
--
-- - Function: int getpwuid_r (uid_t UID, struct passwd *RESULT_BUF, char
-- *BUFFER, size_t BUFLEN, struct passwd **RESULT)
-- This function is similar to `getpwuid' in that is returns
-- information about the user whose user ID is UID. But the result
-- is not placed in a static buffer. Instead the user supplied
-- structure pointed to by RESULT_BUF is filled with the information.
-- The first BUFLEN bytes of the additional buffer pointed to by
-- BUFFER are used to contain additional information, normally
-- strings which are pointed to by the elements of the result
-- structure.
--
-- If the return value is `0' the pointer returned in RESULT points
-- to the record which contains the wanted data (i.e., RESULT
-- contains the value RESULT_BUF). In case the return value is non
-- null there is no user in the data base with user ID UID or the
-- buffer BUFFER is too small to contain all the needed information.
-- In the later case the global ERRNO variable is set to `ERANGE'.
--
-- - Function: struct passwd * getpwnam (const char *NAME)
-- This function returns a pointer to a statically-allocated structure
-- containing information about the user whose user name is NAME.
-- This structure may be overwritten on subsequent calls to
-- `getpwnam'.
--
-- A null pointer value indicates there is no user named NAME.
--
-- - Function: int getpwnam_r (const char *NAME, struct passwd
-- *RESULT_BUF, char *BUFFER, size_t BUFLEN, struct passwd
-- **RESULT)
-- This function is similar to `getpwnam' in that is returns
-- information about the user whose user name is NAME. But the result
-- is not placed in a static buffer. Instead the user supplied
-- structure pointed to by RESULT_BUF is filled with the information.
-- The first BUFLEN bytes of the additional buffer pointed to by
-- BUFFER are used to contain additional information, normally
-- strings which are pointed to by the elements of the result
-- structure.
--
-- If the return value is `0' the pointer returned in RESULT points
-- to the record which contains the wanted data (i.e., RESULT
-- contains the value RESULT_BUF). In case the return value is non
-- null there is no user in the data base with user name NAME or the
-- buffer BUFFER is too small to contain all the needed information.
-- In the later case the global ERRNO variable is set to `ERANGE'.
--
--
--File: libc.info, Node: Scanning All Users, Next: Writing a User Entry,
Prev: Lookup User, Up: User Database
--
--Scanning the List of All Users
--------------------------------
--
-- This section explains how a program can read the list of all users in
--the system, one user at a time. The functions described here are
--declared in `pwd.h'.
--
-- You can use the `fgetpwent' function to read user entries from a
--particular file.
--
-- - Function: struct passwd * fgetpwent (FILE *STREAM)
-- This function reads the next user entry from STREAM and returns a
-- pointer to the entry. The structure is statically allocated and is
-- rewritten on subsequent calls to `fgetpwent'. You must copy the
-- contents of the structure if you wish to save the information.
--
-- This stream must correspond to a file in the same format as the
-- standard password database file. This function comes from System
-- V.
--
-- - Function: int fgetpwent_r (FILE *STREAM, struct passwd *RESULT_BUF,
-- char *BUFFER, size_t BUFLEN, struct passwd **RESULT)
-- This function is similar to `fgetpwent' in that it reads the next
-- user entry from STREAM. But the result is returned in the
-- structure pointed to by RESULT_BUF. The first BUFLEN bytes of the
-- additional buffer pointed to by BUFFER are used to contain
-- additional information, normally strings which are pointed to by
-- the elements of the result structure.
--
-- This stream must correspond to a file in the same format as the
-- standard password database file.
--
-- If the function returns null RESULT points to the structure with
-- the wanted data (normally this is in RESULT_BUF). If errors
-- occurred the return value is non-null and RESULT contains a null
-- pointer.
--
-- The way to scan all the entries in the user database is with
--`setpwent', `getpwent', and `endpwent'.
--
-- - Function: void setpwent (void)
-- This function initializes a stream which `getpwent' and
-- `getpwent_r' use to read the user database.
--
-- - Function: struct passwd * getpwent (void)
-- The `getpwent' function reads the next entry from the stream
-- initialized by `setpwent'. It returns a pointer to the entry. The
-- structure is statically allocated and is rewritten on subsequent
-- calls to `getpwent'. You must copy the contents of the structure
-- if you wish to save the information.
--
-- A null pointer is returned in case no further entry is available.
--
-- - Function: int getpwent_r (struct passwd *RESULT_BUF, char *BUFFER,
-- int BUFLEN, struct passwd **RESULT)
-- This function is similar to `getpwent' in that it returns the next
-- entry from the stream initialized by `setpwent'. But in contrast
-- to the `getpwent' function this function is reentrant since the
-- result is placed in the user supplied structure pointed to by
-- RESULT_BUF. Additional data, normally the strings pointed to by
-- the elements of the result structure, are placed in the additional
-- buffer or length BUFLEN starting at BUFFER.
--
-- If the function returns zero RESULT points to the structure with
-- the wanted data (normally this is in RESULT_BUF). If errors
-- occurred the return value is non-zero and RESULT contains a null
-- pointer.
--
-- - Function: void endpwent (void)
-- This function closes the internal stream used by `getpwent' or
-- `getpwent_r'.
--
--
--File: libc.info, Node: Writing a User Entry, Prev: Scanning All Users, Up:
User Database
--
--Writing a User Entry
----------------------
--
-- - Function: int putpwent (const struct passwd *P, FILE *STREAM)
-- This function writes the user entry `*P' to the stream STREAM, in
-- the format used for the standard user database file. The return
-- value is zero on success and nonzero on failure.
--
-- This function exists for compatibility with SVID. We recommend
-- that you avoid using it, because it makes sense only on the
-- assumption that the `struct passwd' structure has no members
-- except the standard ones; on a system which merges the traditional
-- Unix data base with other extended information about users, adding
-- an entry using this function would inevitably leave out much of
-- the important information.
--
-- The function `putpwent' is declared in `pwd.h'.
--
--
--File: libc.info, Node: Group Database, Next: Netgroup Database, Prev: User
Database, Up: Users and Groups
--
--Group Database
--==============
--
-- This section describes all about how to search and scan the database
--of registered groups. The database itself is kept in the file
--`/etc/group' on most systems, but on some systems a special network
--service provides access to it.
--
--* Menu:
--
--* Group Data Structure:: What each group record contains.
--* Lookup Group:: How to look for a particular group.
--* Scanning All Groups:: Scanning the list of all groups.
--
--
--File: libc.info, Node: Group Data Structure, Next: Lookup Group, Prev:
Group Database, Up: Group Database
--
--The Data Structure for a Group
--------------------------------
--
-- The functions and data structures for accessing the system group
--database are declared in the header file `grp.h'.
--
-- - Data Type: struct group
-- The `group' structure is used to hold information about an entry in
-- the system group database. It has at least the following members:
--
-- `char *gr_name'
-- The name of the group.
--
-- `gid_t gr_gid'
-- The group ID of the group.
--
-- `char **gr_mem'
-- A vector of pointers to the names of users in the group.
-- Each user name is a null-terminated string, and the vector
-- itself is terminated by a null pointer.
--
--
--File: libc.info, Node: Lookup Group, Next: Scanning All Groups, Prev:
Group Data Structure, Up: Group Database
--
--Looking Up One Group
----------------------
--
-- You can search the group database for information about a specific
--group using `getgrgid' or `getgrnam'. These functions are declared in
--`grp.h'.
--
-- - Function: struct group * getgrgid (gid_t GID)
-- This function returns a pointer to a statically-allocated structure
-- containing information about the group whose group ID is GID.
-- This structure may be overwritten by subsequent calls to
-- `getgrgid'.
--
-- A null pointer indicates there is no group with ID GID.
--
-- - Function: int getgrgid_r (gid_t GID, struct group *RESULT_BUF, char
-- *BUFFER, size_t BUFLEN, struct group **RESULT)
-- This function is similar to `getgrgid' in that is returns
-- information about the group whose group ID is GID. But the result
-- is not placed in a static buffer. Instead the user supplied
-- structure pointed to by RESULT_BUF is filled with the information.
-- The first BUFLEN bytes of the additional buffer pointed to by
-- BUFFER are used to contain additional information, normally
-- strings which are pointed to by the elements of the result
-- structure.
--
-- If the return value is `0' the pointer returned in RESULT points
-- to the record which contains the wanted data (i.e., RESULT
-- contains the value RESULT_BUF). If the return value is non-zero
-- there is no group in the data base with group ID GID or the buffer
-- BUFFER is too small to contain all the needed information. In the
-- later case the global ERRNO variable is set to `ERANGE'.
--
-- - Function: struct group * getgrnam (const char *NAME)
-- This function returns a pointer to a statically-allocated structure
-- containing information about the group whose group name is NAME.
-- This structure may be overwritten by subsequent calls to
-- `getgrnam'.
--
-- A null pointer indicates there is no group named NAME.
--
-- - Function: int getgrnam_r (const char *NAME, struct group
-- *RESULT_BUF, char *BUFFER, size_t BUFLEN, struct group
-- **RESULT)
-- This function is similar to `getgrnam' in that is returns
-- information about the group whose group name is NAME. But the
-- result is not placed in a static buffer. Instead the user
-- supplied structure pointed to by RESULT_BUF is filled with the
-- information. The first BUFLEN bytes of the additional buffer
-- pointed to by BUFFER are used to contain additional information,
-- normally strings which are pointed to by the elements of the
-- result structure.
--
-- If the return value is `0' the pointer returned in RESULT points
-- to the record which contains the wanted data (i.e., RESULT
-- contains the value RESULT_BUF). If the return value is non-zero
-- there is no group in the data base with group name NAME or the
-- buffer BUFFER is too small to contain all the needed information.
-- In the later case the global ERRNO variable is set to `ERANGE'.
--
-diff -purN -x BOOT ../glibc-2.0.1/manual/libc.info-26
glibc-2.0.1/manual/libc.info-26
---- ../glibc-2.0.1/manual/libc.info-26 1997-01-25 14:16:44.000000000 +0100
-+++ glibc-2.0.1/manual/libc.info-26 1970-01-01 01:00:00.000000000 +0100
-@@ -1,1240 +0,0 @@
--This is Info file libc.info, produced by Makeinfo version 1.67 from the
--input file libc.texinfo.
--
-- This file documents the GNU C library.
--
-- This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
--Library Reference Manual', for Version 2.00 Beta.
--
-- Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.
--
-- Permission is granted to make and distribute verbatim copies of this
--manual provided the copyright notice and this permission notice are
--preserved on all copies.
--
-- Permission is granted to copy and distribute modified versions of
--this manual under the conditions for verbatim copying, provided also
--that the section entitled "GNU Library General Public License" is
--included exactly as in the original, and provided that the entire
--resulting derived work is distributed under the terms of a permission
--notice identical to this one.
--
-- Permission is granted to copy and distribute translations of this
--manual into another language, under the above conditions for modified
--versions, except that the text of the translation of the section
--entitled "GNU Library General Public License" must be approved for
--accuracy by the Foundation.
--
--
--File: libc.info, Node: Scanning All Groups, Prev: Lookup Group, Up: Group
Database
--
--Scanning the List of All Groups
---------------------------------
--
-- This section explains how a program can read the list of all groups
--in the system, one group at a time. The functions described here are
--declared in `grp.h'.
--
-- You can use the `fgetgrent' function to read group entries from a
--particular file.
--
-- - Function: struct group * fgetgrent (FILE *STREAM)
-- The `fgetgrent' function reads the next entry from STREAM. It
-- returns a pointer to the entry. The structure is statically
-- allocated and is rewritten on subsequent calls to `fgetgrent'. You
-- must copy the contents of the structure if you wish to save the
-- information.
--
-- The stream must correspond to a file in the same format as the
-- standard group database file.
--
-- - Function: int fgetgrent_r (FILE *STREAM, struct group *RESULT_BUF,
-- char *BUFFER, size_t BUFLEN, struct group **RESULT)
-- This function is similar to `fgetgrent' in that it reads the next
-- user entry from STREAM. But the result is returned in the
-- structure pointed to by RESULT_BUF. The first BUFLEN bytes of the
-- additional buffer pointed to by BUFFER are used to contain
-- additional information, normally strings which are pointed to by
-- the elements of the result structure.
--
-- This stream must correspond to a file in the same format as the
-- standard group database file.
--
-- If the function returns zero RESULT points to the structure with
-- the wanted data (normally this is in RESULT_BUF). If errors
-- occurred the return value is non-zero and RESULT contains a null
-- pointer.
--
-- The way to scan all the entries in the group database is with
--`setgrent', `getgrent', and `endgrent'.
--
-- - Function: void setgrent (void)
-- This function initializes a stream for reading from the group data
-- base. You use this stream by calling `getgrent' or `getgrent_r'.
--
-- - Function: struct group * getgrent (void)
-- The `getgrent' function reads the next entry from the stream
-- initialized by `setgrent'. It returns a pointer to the entry. The
-- structure is statically allocated and is rewritten on subsequent
-- calls to `getgrent'. You must copy the contents of the structure
-- if you wish to save the information.
--
-- - Function: int getgrent_r (struct group *RESULT_BUF, char *BUFFER,
-- size_t BUFLEN, struct group **RESULT)
-- This function is similar to `getgrent' in that it returns the next
-- entry from the stream initialized by `setgrent'. But in contrast
-- to the `getgrent' function this function is reentrant since the
-- result is placed in the user supplied structure pointed to by
-- RESULT_BUF. Additional data, normally the strings pointed to by
-- the elements of the result structure, are placed in the additional
-- buffer or length BUFLEN starting at BUFFER.
--
-- If the function returns zero RESULT points to the structure with
-- the wanted data (normally this is in RESULT_BUF). If errors
-- occurred the return value is non-zero and RESULT contains a null
-- pointer.
--
-- - Function: void endgrent (void)
-- This function closes the internal stream used by `getgrent' or
-- `getgrent_r'.
--
--
--File: libc.info, Node: Netgroup Database, Next: Database Example, Prev:
Group Database, Up: Users and Groups
--
--Netgroup Database
--=================
--
--* Menu:
--
--* Netgroup Data:: Data in the Netgroup database and where
-- it comes from.
--* Lookup Netgroup:: How to look for a particular netgroup.
--* Netgroup Membership:: How to test for netgroup membership.
--
--
--File: libc.info, Node: Netgroup Data, Next: Lookup Netgroup, Prev:
Netgroup Database, Up: Netgroup Database
--
--Netgroup Data
---------------
--
-- Sometimes it is useful group users according to other criterias like
--the ones used in the *Note Group Database::. E.g., it is useful to
--associate a certain group of users with a certain machine. On the
--other hand grouping of host names is not supported so far.
--
-- In Sun Microsystems SunOS appeared a new kind of database, the
--netgroup database. It allows to group hosts, users, and domain freely,
--giving them individual names. More concrete: a netgroup is a list of
--triples consisting of a host name, a user name, and a domain name,
--where any of the entries can be a wildcard entry, matching all inputs.
--A last possibility is that names of other netgroups can also be given
--in the list specifying a netgroup. So one can construct arbitrary
--hierarchies without loops.
--
-- Sun's implementation allows netgroups only for the `nis' or
--`nisplus' service *note Services in the NSS configuration::.. The
--implementation in the GNU C library has no such restriction. An entry
--in either of the input services must have the following form:
--
-- GROUPNAME ( GROUPNAME | `('HOSTNAME`,'USERNAME`,'`domainname'`)' )+
--
-- Any of the fields in the triple can be empty which means anything
--matches. While describing the functions we will see that the opposite
--case is useful as well. I.e., there may be entries which will not
--match any input. For entries like a name consisting of the single
--character `-' shall be used.
--
--
--File: libc.info, Node: Lookup Netgroup, Next: Netgroup Membership, Prev:
Netgroup Data, Up: Netgroup Database
--
--Looking up one Netgroup
-------------------------
--
-- The lookup functions for netgroups are a bit different to all other
--system database handling functions. Since a single netgroup can contain
--many entries a two-step process is needed. First a single netgroup is
--selected and then one can iterate over all entries in this netgroup.
--These functions are declared in `netdb.h'.
--
-- - Function: int setnetgrent (const char *NETGROUP)
-- A call to this function initializes the internal state of the
-- library to allow following calls of the `getnetgrent' iterate over
-- all entries in the netgroup with name NETGROUP.
--
-- When the call is successful (i.e., when a netgroup with this name
-- exist) the return value is `1'. When the return value is `0' no
-- netgroup of this name is known or some other error occurred.
--
-- It is important to remember that there is only one single state for
--iterating the netgroups. Even if the programmer uses the
--`getnetgrent_r' function the result is not really reentrant since
--always only one single netgroup at a time can be processed. If the
--program needs to process more than one netgroup simultaneously she must
--protect this by using external locking. This problem was introduced in
--the original netgroups implementation in SunOS and since we must stay
--compatible it is not possible to change this.
--
-- Some other functions also use the netgroups state. Currently these
--are the `innetgr' function and parts of the implementation of the
--`compat' service part of the NSS implementation.
--
-- - Function: int getnetgrent (char **HOSTP, char **USERP, char
-- **DOMAINP)
-- This function returns the next unprocessed entry of the currently
-- selected netgroup. The string pointers, which addresses are
-- passed in the arguments HOSTP, USERP, and DOMAINP, will contain
-- after a successful call pointers to appropriate strings. If the
-- string in the next entry is empty the pointer has the value `NULL'.
-- The returned string pointers are only valid unless no of the
-- netgroup related functions are called.
--
-- The return value is `1' if the next entry was successfully read. A
-- value of `0' means no further entries exist or internal errors
-- occurred.
--
-- - Function: int getnetgrent_r (char **HOSTP, char **USERP, char
-- **DOMAINP, char *BUFFER, int BUFLEN)
-- This function is similar to `getnetgrent' with only one exception:
-- the strings the three string pointers HOSTP, USERP, and DOMAINP
-- point to, are placed in the buffer of BUFLEN bytes starting at
-- BUFFER. This means the returned values are valid even after other
-- netgroup related functions are called.
--
-- The return value is `1' if the next entry was successfully read and
-- the buffer contains enough room to place the strings in it. `0' is
-- returned in case no more entries are found, the buffer is too
-- small, or internal errors occurred.
--
-- This function is a GNU extension. The original implementation in
-- the SunOS libc does not provide this function.
--
-- - Function: void endnetgrent (void)
-- This function free all buffers which were allocated to process the
-- last selected netgroup. As a result all string pointers returned
-- by calls to `getnetgrent' are invalid afterwards.
--
--
--File: libc.info, Node: Netgroup Membership, Prev: Lookup Netgroup, Up:
Netgroup Database
--
--Testing for Netgroup Membership
---------------------------------
--
-- It is often not necessary to scan the whole netgroup since often the
--only interesting question is whether a given entry is part of the
--selected netgroup.
--
-- - Function: int innetgr (const char *NETGROUP, const char *HOST, const
-- char *USER, const char *DOMAIN)
-- This function tests whether the triple specified by the parameters
-- HOSTP, USERP, and DOMAINP is part of the netgroup NETGROUP. Using
-- this function has the advantage that
--
-- 1. no other netgroup function can use the global netgroup state
-- since internal locking is used and
--
-- 2. the function is implemented more efficiently than successive
-- calls to the other `set'/`get'/`endnetgrent' functions.
--
-- Any of the pointers HOSTP, USERP, and DOMAINP can be `NULL' which
-- means any value is excepted in this position. This is also true
-- for the name `-' which should not match any other string otherwise.
--
-- The return value is `1' if an entry matching the given triple is
-- found in the netgroup. The return value is `0' if the netgroup
-- itself is not found, the netgroup does not contain the triple or
-- internal errors occurred.
--
--
--File: libc.info, Node: Database Example, Prev: Netgroup Database, Up:
Users and Groups
--
--User and Group Database Example
--===============================
--
-- Here is an example program showing the use of the system database
--inquiry functions. The program prints some information about the user
--running the program.
--
-- #include <grp.h>
-- #include <pwd.h>
-- #include <sys/types.h>
-- #include <unistd.h>
-- #include <stdlib.h>
--
-- int
-- main (void)
-- {
-- uid_t me;
-- struct passwd *my_passwd;
-- struct group *my_group;
-- char **members;
--
-- /* Get information about the user ID. */
-- me = getuid ();
-- my_passwd = getpwuid (me);
-- if (!my_passwd)
-- {
-- printf ("Couldn't find out about user %d.\n", (int) me);
-- exit (EXIT_FAILURE);
-- }
--
-- /* Print the information. */
-- printf ("I am %s.\n", my_passwd->pw_gecos);
-- printf ("My login name is %s.\n", my_passwd->pw_name);
-- printf ("My uid is %d.\n", (int) (my_passwd->pw_uid));
-- printf ("My home directory is %s.\n", my_passwd->pw_dir);
-- printf ("My default shell is %s.\n", my_passwd->pw_shell);
--
-- /* Get information about the default group ID. */
-- my_group = getgrgid (my_passwd->pw_gid);
-- if (!my_group)
-- {
-- printf ("Couldn't find out about group %d.\n",
-- (int) my_passwd->pw_gid);
-- exit (EXIT_FAILURE);
-- }
--
-- /* Print the information. */
-- printf ("My default group is %s (%d).\n",
-- my_group->gr_name, (int) (my_passwd->pw_gid));
-- printf ("The members of this group are:\n");
-- members = my_group->gr_mem;
-- while (*members)
-- {
-- printf (" %s\n", *(members));
-- members++;
-- }
--
-- return EXIT_SUCCESS;
-- }
--
-- Here is some output from this program:
--
-- I am Throckmorton Snurd.
-- My login name is snurd.
-- My uid is 31093.
-- My home directory is /home/fsg/snurd.
-- My default shell is /bin/sh.
-- My default group is guest (12).
-- The members of this group are:
-- friedman
-- tami
--
--
--File: libc.info, Node: System Information, Next: System Configuration,
Prev: Users and Groups, Up: Top
--
--System Information
--******************
--
-- This chapter describes functions that return information about the
--particular machine that is in use--the type of hardware, the type of
--software, and the individual machine's name.
--
--* Menu:
--
--* Host Identification:: Determining the name of the machine.
--* Hardware/Software Type ID:: Determining the hardware type of the
-- machine and what operating system it is
-- running.
--
--
--File: libc.info, Node: Host Identification, Next: Hardware/Software Type
ID, Up: System Information
--
--Host Identification
--===================
--
-- This section explains how to identify the particular machine that
--your program is running on. The identification of a machine consists
--of its Internet host name and Internet address; see *Note Internet
--Namespace::. The host name should always be a fully qualified domain
--name, like `crispy-wheats-n-chicken.ai.mit.edu', not a simple name like
--just `crispy-wheats-n-chicken'.
--
-- Prototypes for these functions appear in `unistd.h'. The shell
--commands `hostname' and `hostid' work by calling them.
--
-- - Function: int gethostname (char *NAME, size_t SIZE)
-- This function returns the name of the host machine in the array
-- NAME. The SIZE argument specifies the size of this array, in
-- bytes.
--
-- The return value is `0' on success and `-1' on failure. In the
-- GNU C library, `gethostname' fails if SIZE is not large enough;
-- then you can try again with a larger array. The following `errno'
-- error condition is defined for this function:
--
-- `ENAMETOOLONG'
-- The SIZE argument is less than the size of the host name plus
-- one.
--
-- On some systems, there is a symbol for the maximum possible host
-- name length: `MAXHOSTNAMELEN'. It is defined in `sys/param.h'.
-- But you can't count on this to exist, so it is cleaner to handle
-- failure and try again.
--
-- `gethostname' stores the beginning of the host name in NAME even
-- if the host name won't entirely fit. For some purposes, a
-- truncated host name is good enough. If it is, you can ignore the
-- error code.
--
-- - Function: int sethostname (const char *NAME, size_t LENGTH)
-- The `sethostname' function sets the name of the host machine to
-- NAME, a string with length LENGTH. Only privileged processes are
-- allowed to do this. Usually it happens just once, at system boot
-- time.
--
-- The return value is `0' on success and `-1' on failure. The
-- following `errno' error condition is defined for this function:
--
-- `EPERM'
-- This process cannot set the host name because it is not
-- privileged.
--
-- - Function: long int gethostid (void)
-- This function returns the "host ID" of the machine the program is
-- running on. By convention, this is usually the primary Internet
-- address of that machine, converted to a `long int'. However, some
-- systems it is a meaningless but unique number which is hard-coded
-- for each machine.
--
-- - Function: int sethostid (long int ID)
-- The `sethostid' function sets the "host ID" of the host machine to
-- ID. Only privileged processes are allowed to do this. Usually it
-- happens just once, at system boot time.
--
-- The return value is `0' on success and `-1' on failure. The
-- following `errno' error condition is defined for this function:
--
-- `EPERM'
-- This process cannot set the host name because it is not
-- privileged.
--
-- `ENOSYS'
-- The operating system does not support setting the host ID.
-- On some systems, the host ID is a meaningless but unique
-- number hard-coded for each machine.
--
--
--File: libc.info, Node: Hardware/Software Type ID, Prev: Host
Identification, Up: System Information
--
--Hardware/Software Type Identification
--=====================================
--
-- You can use the `uname' function to find out some information about
--the type of computer your program is running on. This function and the
--associated data type are declared in the header file `sys/utsname.h'.
--
-- - Data Type: struct utsname
-- The `utsname' structure is used to hold information returned by
-- the `uname' function. It has the following members:
--
-- `char sysname[]'
-- This is the name of the operating system in use.
--
-- `char nodename[]'
-- This is the network name of this particular computer. In the
-- GNU library, the value is the same as that returned by
-- `gethostname'; see *Note Host Identification::.
--
-- `char release[]'
-- This is the current release level of the operating system
-- implementation.
--
-- `char version[]'
-- This is the current version level within the release of the
-- operating system.
--
-- `char machine[]'
-- This is a description of the type of hardware that is in use.
--
-- Some systems provide a mechanism to interrogate the kernel
-- directly for this information. On systems without such a
-- mechanism, the GNU C library fills in this field based on the
-- configuration name that was specified when building and
-- installing the library.
--
-- GNU uses a three-part name to describe a system
-- configuration; the three parts are CPU, MANUFACTURER and
-- SYSTEM-TYPE, and they are separated with dashes. Any
-- possible combination of three names is potentially
-- meaningful, but most such combinations are meaningless in
-- practice and even the meaningful ones are not necessarily
-- supported by any particular GNU program.
--
-- Since the value in `machine' is supposed to describe just the
-- hardware, it consists of the first two parts of the
-- configuration name: `CPU-MANUFACTURER'. For example, it
-- might be one of these:
--
-- `"sparc-sun"', `"i386-ANYTHING"', `"m68k-hp"',
-- `"m68k-sony"', `"m68k-sun"', `"mips-dec"'
--
-- - Function: int uname (struct utsname *INFO)
-- The `uname' function fills in the structure pointed to by INFO
-- with information about the operating system and host machine. A
-- non-negative value indicates that the data was successfully stored.
--
-- `-1' as the value indicates an error. The only error possible is
-- `EFAULT', which we normally don't mention as it is always a
-- possibility.
--
--
--File: libc.info, Node: System Configuration, Next: Language Features,
Prev: System Information, Up: Top
--
--System Configuration Parameters
--*******************************
--
-- The functions and macros listed in this chapter give information
--about configuration parameters of the operating system--for example,
--capacity limits, presence of optional POSIX features, and the default
--path for executable files (*note String Parameters::.).
--
--* Menu:
--
--* General Limits:: Constants and functions that describe
-- various process-related limits that have
-- one uniform value for any given machine.
--* System Options:: Optional POSIX features.
--* Version Supported:: Version numbers of POSIX.1 and POSIX.2.
--* Sysconf:: Getting specific configuration values
-- of general limits and system options.
--* Minimums:: Minimum values for general limits.
--
--* Limits for Files:: Size limitations that pertain to individual
files.
-- These can vary between file systems
-- or even from file to file.
--* Options for Files:: Optional features that some files may support.
--* File Minimums:: Minimum values for file limits.
--* Pathconf:: Getting the limit values for a particular file.
--
--* Utility Limits:: Capacity limits of some POSIX.2 utility programs.
--* Utility Minimums:: Minimum allowable values of those limits.
--
--* String Parameters:: Getting the default search path.
--
--
--File: libc.info, Node: General Limits, Next: System Options, Up: System
Configuration
--
--General Capacity Limits
--=======================
--
-- The POSIX.1 and POSIX.2 standards specify a number of parameters that
--describe capacity limitations of the system. These limits can be fixed
--constants for a given operating system, or they can vary from machine to
--machine. For example, some limit values may be configurable by the
--system administrator, either at run time or by rebuilding the kernel,
--and this should not require recompiling application programs.
--
-- Each of the following limit parameters has a macro that is defined in
--`limits.h' only if the system has a fixed, uniform limit for the
--parameter in question. If the system allows different file systems or
--files to have different limits, then the macro is undefined; use
--`sysconf' to find out the limit that applies at a particular time on a
--particular machine. *Note Sysconf::.
--
-- Each of these parameters also has another macro, with a name starting
--with `_POSIX', which gives the lowest value that the limit is allowed
--to have on *any* POSIX system. *Note Minimums::.
--
-- - Macro: int ARG_MAX
-- If defined, the unvarying maximum combined length of the ARGV and
-- ENVIRON arguments that can be passed to the `exec' functions.
--
-- - Macro: int CHILD_MAX
-- If defined, the unvarying maximum number of processes that can
-- exist with the same real user ID at any one time. In BSD and GNU,
-- this is controlled by the `RLIMIT_NPROC' resource limit; *note
-- Limits on Resources::..
--
-- - Macro: int OPEN_MAX
-- If defined, the unvarying maximum number of files that a single
-- process can have open simultaneously. In BSD and GNU, this is
-- controlled by the `RLIMIT_NOFILE' resource limit; *note Limits on
-- Resources::..
--
-- - Macro: int STREAM_MAX
-- If defined, the unvarying maximum number of streams that a single
-- process can have open simultaneously. *Note Opening Streams::.
--
-- - Macro: int TZNAME_MAX
-- If defined, the unvarying maximum length of a time zone name.
-- *Note Time Zone Functions::.
--
-- These limit macros are always defined in `limits.h'.
--
-- - Macro: int NGROUPS_MAX
-- The maximum number of supplementary group IDs that one process can
-- have.
--
-- The value of this macro is actually a lower bound for the maximum.
-- That is, you can count on being able to have that many
-- supplementary group IDs, but a particular machine might let you
-- have even more. You can use `sysconf' to see whether a particular
-- machine will let you have more (*note Sysconf::.).
--
-- - Macro: int SSIZE_MAX
-- The largest value that can fit in an object of type `ssize_t'.
-- Effectively, this is the limit on the number of bytes that can be
-- read or written in a single operation.
--
-- This macro is defined in all POSIX systems because this limit is
-- never configurable.
--
-- - Macro: int RE_DUP_MAX
-- The largest number of repetitions you are guaranteed is allowed in
-- the construct `\{MIN,MAX\}' in a regular expression.
--
-- The value of this macro is actually a lower bound for the maximum.
-- That is, you can count on being able to have that many
-- repetitions, but a particular machine might let you have even
-- more. You can use `sysconf' to see whether a particular machine
-- will let you have more (*note Sysconf::.). And even the value
-- that `sysconf' tells you is just a lower bound--larger values
-- might work.
--
-- This macro is defined in all POSIX.2 systems, because POSIX.2 says
-- it should always be defined even if there is no specific imposed
-- limit.
--
--
--File: libc.info, Node: System Options, Next: Version Supported, Prev:
General Limits, Up: System Configuration
--
--Overall System Options
--======================
--
-- POSIX defines certain system-specific options that not all POSIX
--systems support. Since these options are provided in the kernel, not
--in the library, simply using the GNU C library does not guarantee any
--of these features is supported; it depends on the system you are using.
--
-- You can test for the availability of a given option using the macros
--in this section, together with the function `sysconf'. The macros are
--defined only if you include `unistd.h'.
--
-- For the following macros, if the macro is defined in `unistd.h',
--then the option is supported. Otherwise, the option may or may not be
--supported; use `sysconf' to find out. *Note Sysconf::.
--
-- - Macro: int _POSIX_JOB_CONTROL
-- If this symbol is defined, it indicates that the system supports
-- job control. Otherwise, the implementation behaves as if all
-- processes within a session belong to a single process group.
-- *Note Job Control::.
--
-- - Macro: int _POSIX_SAVED_IDS
-- If this symbol is defined, it indicates that the system remembers
-- the effective user and group IDs of a process before it executes an
-- executable file with the set-user-ID or set-group-ID bits set, and
-- that explicitly changing the effective user or group IDs back to
-- these values is permitted. If this option is not defined, then if
-- a nonprivileged process changes its effective user or group ID to
-- the real user or group ID of the process, it can't change it back
-- again. *Note Enable/Disable Setuid::.
--
-- For the following macros, if the macro is defined in `unistd.h',
--then its value indicates whether the option is supported. A value of
--`-1' means no, and any other value means yes. If the macro is not
--defined, then the option may or may not be supported; use `sysconf' to
--find out. *Note Sysconf::.
--
-- - Macro: int _POSIX2_C_DEV
-- If this symbol is defined, it indicates that the system has the
-- POSIX.2 C compiler command, `c89'. The GNU C library always
-- defines this as `1', on the assumption that you would not have
-- installed it if you didn't have a C compiler.
--
-- - Macro: int _POSIX2_FORT_DEV
-- If this symbol is defined, it indicates that the system has the
-- POSIX.2 Fortran compiler command, `fort77'. The GNU C library
-- never defines this, because we don't know what the system has.
--
-- - Macro: int _POSIX2_FORT_RUN
-- If this symbol is defined, it indicates that the system has the
-- POSIX.2 `asa' command to interpret Fortran carriage control. The
-- GNU C library never defines this, because we don't know what the
-- system has.
--
-- - Macro: int _POSIX2_LOCALEDEF
-- If this symbol is defined, it indicates that the system has the
-- POSIX.2 `localedef' command. The GNU C library never defines
-- this, because we don't know what the system has.
--
-- - Macro: int _POSIX2_SW_DEV
-- If this symbol is defined, it indicates that the system has the
-- POSIX.2 commands `ar', `make', and `strip'. The GNU C library
-- always defines this as `1', on the assumption that you had to have
-- `ar' and `make' to install the library, and it's unlikely that
-- `strip' would be absent when those are present.
--
--
--File: libc.info, Node: Version Supported, Next: Sysconf, Prev: System
Options, Up: System Configuration
--
--Which Version of POSIX is Supported
--===================================
--
-- - Macro: long int _POSIX_VERSION
-- This constant represents the version of the POSIX.1 standard to
-- which the implementation conforms. For an implementation
-- conforming to the 1990 POSIX.1 standard, the value is the integer
-- `199009L'.
--
-- `_POSIX_VERSION' is always defined (in `unistd.h') in any POSIX
-- system.
--
-- *Usage Note:* Don't try to test whether the system supports POSIX
-- by including `unistd.h' and then checking whether `_POSIX_VERSION'
-- is defined. On a non-POSIX system, this will probably fail
-- because there is no `unistd.h'. We do not know of *any* way you
-- can reliably test at compilation time whether your target system
-- supports POSIX or whether `unistd.h' exists.
--
-- The GNU C compiler predefines the symbol `__POSIX__' if the target
-- system is a POSIX system. Provided you do not use any other
-- compilers on POSIX systems, testing `defined (__POSIX__)' will
-- reliably detect such systems.
--
-- - Macro: long int _POSIX2_C_VERSION
-- This constant represents the version of the POSIX.2 standard which
-- the library and system kernel support. We don't know what value
-- this will be for the first version of the POSIX.2 standard,
-- because the value is based on the year and month in which the
-- standard is officially adopted.
--
-- The value of this symbol says nothing about the utilities
-- installed on the system.
--
-- *Usage Note:* You can use this macro to tell whether a POSIX.1
-- system library supports POSIX.2 as well. Any POSIX.1 system
-- contains `unistd.h', so include that file and then test `defined
-- (_POSIX2_C_VERSION)'.
--
--
--File: libc.info, Node: Sysconf, Next: Minimums, Prev: Version Supported,
Up: System Configuration
--
--Using `sysconf'
--===============
--
-- When your system has configurable system limits, you can use the
--`sysconf' function to find out the value that applies to any particular
--machine. The function and the associated PARAMETER constants are
--declared in the header file `unistd.h'.
--
--* Menu:
--
--* Sysconf Definition:: Detailed specifications of `sysconf'.
--* Constants for Sysconf:: The list of parameters `sysconf' can read.
--* Examples of Sysconf:: How to use `sysconf' and the parameter
-- macros properly together.
--
--
--File: libc.info, Node: Sysconf Definition, Next: Constants for Sysconf,
Up: Sysconf
--
--Definition of `sysconf'
-------------------------
--
-- - Function: long int sysconf (int PARAMETER)
-- This function is used to inquire about runtime system parameters.
-- The PARAMETER argument should be one of the `_SC_' symbols listed
-- below.
--
-- The normal return value from `sysconf' is the value you requested.
-- A value of `-1' is returned both if the implementation does not
-- impose a limit, and in case of an error.
--
-- The following `errno' error conditions are defined for this
-- function:
--
-- `EINVAL'
-- The value of the PARAMETER is invalid.
--
--
--File: libc.info, Node: Constants for Sysconf, Next: Examples of Sysconf,
Prev: Sysconf Definition, Up: Sysconf
--
--Constants for `sysconf' Parameters
------------------------------------
--
-- Here are the symbolic constants for use as the PARAMETER argument to
--`sysconf'. The values are all integer constants (more specifically,
--enumeration type values).
--
--`_SC_ARG_MAX'
-- Inquire about the parameter corresponding to `ARG_MAX'.
--
--`_SC_CHILD_MAX'
-- Inquire about the parameter corresponding to `CHILD_MAX'.
--
--`_SC_OPEN_MAX'
-- Inquire about the parameter corresponding to `OPEN_MAX'.
--
--`_SC_STREAM_MAX'
-- Inquire about the parameter corresponding to `STREAM_MAX'.
--
--`_SC_TZNAME_MAX'
-- Inquire about the parameter corresponding to `TZNAME_MAX'.
--
--`_SC_NGROUPS_MAX'
-- Inquire about the parameter corresponding to `NGROUPS_MAX'.
--
--`_SC_JOB_CONTROL'
-- Inquire about the parameter corresponding to `_POSIX_JOB_CONTROL'.
--
--`_SC_SAVED_IDS'
-- Inquire about the parameter corresponding to `_POSIX_SAVED_IDS'.
--
--`_SC_VERSION'
-- Inquire about the parameter corresponding to `_POSIX_VERSION'.
--
--`_SC_CLK_TCK'
-- Inquire about the parameter corresponding to `CLOCKS_PER_SEC';
-- *note Basic CPU Time::..
--
--`_SC_2_C_DEV'
-- Inquire about whether the system has the POSIX.2 C compiler
-- command, `c89'.
--
--`_SC_2_FORT_DEV'
-- Inquire about whether the system has the POSIX.2 Fortran compiler
-- command, `fort77'.
--
--`_SC_2_FORT_RUN'
-- Inquire about whether the system has the POSIX.2 `asa' command to
-- interpret Fortran carriage control.
--
--`_SC_2_LOCALEDEF'
-- Inquire about whether the system has the POSIX.2 `localedef'
-- command.
--
--`_SC_2_SW_DEV'
-- Inquire about whether the system has the POSIX.2 commands `ar',
-- `make', and `strip'.
--
--`_SC_BC_BASE_MAX'
-- Inquire about the maximum value of `obase' in the `bc' utility.
--
--`_SC_BC_DIM_MAX'
-- Inquire about the maximum size of an array in the `bc' utility.
--
--`_SC_BC_SCALE_MAX'
-- Inquire about the maximum value of `scale' in the `bc' utility.
--
--`_SC_BC_STRING_MAX'
-- Inquire about the maximum size of a string constant in the `bc'
-- utility.
--
--`_SC_COLL_WEIGHTS_MAX'
-- Inquire about the maximum number of weights that can necessarily
-- be used in defining the collating sequence for a locale.
--
--`_SC_EXPR_NEST_MAX'
-- Inquire about the maximum number of expressions nested within
-- parentheses when using the `expr' utility.
--
--`_SC_LINE_MAX'
-- Inquire about the maximum size of a text line that the POSIX.2 text
-- utilities can handle.
--
--`_SC_EQUIV_CLASS_MAX'
-- Inquire about the maximum number of weights that can be assigned
-- to an entry of the `LC_COLLATE' category `order' keyword in a
-- locale definition. The GNU C library does not presently support
-- locale definitions.
--
--`_SC_VERSION'
-- Inquire about the version number of POSIX.1 that the library and
-- kernel support.
--
--`_SC_2_VERSION'
-- Inquire about the version number of POSIX.2 that the system
-- utilities support.
--
--`_SC_PAGESIZE'
-- Inquire about the virtual memory page size of the machine.
-- `getpagesize' returns the same value.
--
--
--File: libc.info, Node: Examples of Sysconf, Prev: Constants for Sysconf,
Up: Sysconf
--
--Examples of `sysconf'
-----------------------
--
-- We recommend that you first test for a macro definition for the
--parameter you are interested in, and call `sysconf' only if the macro
--is not defined. For example, here is how to test whether job control
--is supported:
--
-- int
-- have_job_control (void)
-- {
-- #ifdef _POSIX_JOB_CONTROL
-- return 1;
-- #else
-- int value = sysconf (_SC_JOB_CONTROL);
-- if (value < 0)
-- /* If the system is that badly wedged,
-- there's no use trying to go on. */
-- fatal (strerror (errno));
-- return value;
-- #endif
-- }
--
-- Here is how to get the value of a numeric limit:
--
-- int
-- get_child_max ()
-- {
-- #ifdef CHILD_MAX
-- return CHILD_MAX;
-- #else
-- int value = sysconf (_SC_CHILD_MAX);
-- if (value < 0)
-- fatal (strerror (errno));
-- return value;
-- #endif
-- }
--
--
--File: libc.info, Node: Minimums, Next: Limits for Files, Prev: Sysconf,
Up: System Configuration
--
--Minimum Values for General Capacity Limits
--==========================================
--
-- Here are the names for the POSIX minimum upper bounds for the system
--limit parameters. The significance of these values is that you can
--safely push to these limits without checking whether the particular
--system you are using can go that far.
--
--`_POSIX_ARG_MAX'
-- The value of this macro is the most restrictive limit permitted by
-- POSIX for the maximum combined length of the ARGV and ENVIRON
-- arguments that can be passed to the `exec' functions. Its value
-- is `4096'.
--
--`_POSIX_CHILD_MAX'
-- The value of this macro is the most restrictive limit permitted by
-- POSIX for the maximum number of simultaneous processes per real
-- user ID. Its value is `6'.
--
--`_POSIX_NGROUPS_MAX'
-- The value of this macro is the most restrictive limit permitted by
-- POSIX for the maximum number of supplementary group IDs per
-- process. Its value is `0'.
--
--`_POSIX_OPEN_MAX'
-- The value of this macro is the most restrictive limit permitted by
-- POSIX for the maximum number of files that a single process can
-- have open simultaneously. Its value is `16'.
--
--`_POSIX_SSIZE_MAX'
-- The value of this macro is the most restrictive limit permitted by
-- POSIX for the maximum value that can be stored in an object of type
-- `ssize_t'. Its value is `32767'.
--
--`_POSIX_STREAM_MAX'
-- The value of this macro is the most restrictive limit permitted by
-- POSIX for the maximum number of streams that a single process can
-- have open simultaneously. Its value is `8'.
--
--`_POSIX_TZNAME_MAX'
-- The value of this macro is the most restrictive limit permitted by
-- POSIX for the maximum length of a time zone name. Its value is
-- `3'.
--
--`_POSIX2_RE_DUP_MAX'
-- The value of this macro is the most restrictive limit permitted by
-- POSIX for the numbers used in the `\{MIN,MAX\}' construct in a
-- regular expression. Its value is `255'.
--
--
--File: libc.info, Node: Limits for Files, Next: Options for Files, Prev:
Minimums, Up: System Configuration
--
--Limits on File System Capacity
--==============================
--
-- The POSIX.1 standard specifies a number of parameters that describe
--the limitations of the file system. It's possible for the system to
--have a fixed, uniform limit for a parameter, but this isn't the usual
--case. On most systems, it's possible for different file systems (and,
--for some parameters, even different files) to have different maximum
--limits. For example, this is very likely if you use NFS to mount some
--of the file systems from other machines.
--
-- Each of the following macros is defined in `limits.h' only if the
--system has a fixed, uniform limit for the parameter in question. If the
--system allows different file systems or files to have different limits,
--then the macro is undefined; use `pathconf' or `fpathconf' to find out
--the limit that applies to a particular file. *Note Pathconf::.
--
-- Each parameter also has another macro, with a name starting with
--`_POSIX', which gives the lowest value that the limit is allowed to
--have on *any* POSIX system. *Note File Minimums::.
--
-- - Macro: int LINK_MAX
-- The uniform system limit (if any) for the number of names for a
-- given file. *Note Hard Links::.
--
-- - Macro: int MAX_CANON
-- The uniform system limit (if any) for the amount of text in a line
-- of input when input editing is enabled. *Note Canonical or Not::.
--
-- - Macro: int MAX_INPUT
-- The uniform system limit (if any) for the total number of
-- characters typed ahead as input. *Note I/O Queues::.
--
-- - Macro: int NAME_MAX
-- The uniform system limit (if any) for the length of a file name
-- component.
--
-- - Macro: int PATH_MAX
-- The uniform system limit (if any) for the length of an entire file
-- name (that is, the argument given to system calls such as `open').
--
-- - Macro: int PIPE_BUF
-- The uniform system 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/207: gnu: Update mes-boot, tcc-boot: __udivdi3, __umoddi3., (continued)
- 28/207: gnu: Update mes-boot, tcc-boot: __udivdi3, __umoddi3., Jan Nieuwenhuizen, 2018/09/08
- 25/207: gnu: Update mescc-tools-boot: Binaries with function debug info., Jan Nieuwenhuizen, 2018/09/08
- 03/207: gnu: Add mes-boot., Jan Nieuwenhuizen, 2018/09/08
- 06/207: use %bootstrap-guile -- still guile-2.2 in bag-with-origins :-(, Jan Nieuwenhuizen, 2018/09/08
- 02/207: gnu: Add mescc-tools-boot., Jan Nieuwenhuizen, 2018/09/08
- 09/207: bump tcc-boot: add sysinclude path for [m4] configure., Jan Nieuwenhuizen, 2018/09/08
- 07/207: Revert "use %bootstrap-guile -- still guile-2.2 in bag-with-origins :-(", Jan Nieuwenhuizen, 2018/09/08
- 01/207: gnu: Add stage0-boot., Jan Nieuwenhuizen, 2018/09/08
- 08/207: gnu: Add gcc-boot. WIP, Jan Nieuwenhuizen, 2018/09/08
- 05/207: gnu: Add tcc-boot., Jan Nieuwenhuizen, 2018/09/08
- 79/207: gnu: glibc-boot: Update to 2.2.5.,
Jan Nieuwenhuizen <=
- 78/207: gnu: Add glibc-boot 2.0.1., Jan Nieuwenhuizen, 2018/09/11