Many changes after first published edition and comments from mib; still not finished.
authorroland <roland>
Wed, 29 Dec 1993 23:32:21 +0000 (23:32 +0000)
committerroland <roland>
Wed, 29 Dec 1993 23:32:21 +0000 (23:32 +0000)
manual/intro.texi
manual/io.texi
manual/libc.texinfo
manual/locale.texi
manual/mbyte.texi
manual/memory.texi
manual/pattern.texi
manual/search.texi
manual/stdio.texi
manual/string.texi

index 6367bbe..75bc735 100644 (file)
@@ -16,7 +16,7 @@ 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 on this manual is not on strict
+to other systems.  But the emphasis in this manual is not on strict
 portability.
 
 @menu
@@ -115,7 +115,7 @@ to write programs to work portably under multiple C dialects, but does
 not aim for completeness.
 
 @node POSIX, Berkeley Unix, ANSI C, Standards and Portability
-@subsection @sc{posix} (The Portable Operating System Interface)
+@subsection POSIX (The Portable Operating System Interface)
 @cindex POSIX
 @cindex POSIX.1
 @cindex IEEE Std 1003.1
@@ -127,27 +127,27 @@ standards, known more formally as the @dfn{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 standard are a superset of
-those required by ANSI C; POSIX specifies additional features for ANSI C
-functions, as well as specifying new additional functions.  In general,
-the additional requirements and functionality defined by the POSIX
-standard 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.@refill
+The library facilities specified by the POSIX standards are a superset
+of those required by ANSI C; POSIX specifies additional features for
+ANSI 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.@refill
 
 The GNU C library implements all of the functions specified in
-@cite{IEEE Std 1003.1-1988, the POSIX System Application Program
+@cite{IEEE Std 1003.1-1990, the POSIX System Application Program
 Interface}, commonly referred to as POSIX.1.  The primary extensions to
 the ANSI C facilities specified by this standard include file system
 interface primitives (@pxref{File System Interface}), device-specific
 terminal control functions (@pxref{Low-Level Terminal Interface}), and
 process control functions (@pxref{Child Processes}).
 
-Some facilities from draft 11 of @cite{IEEE Std 1003.2, 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 (@pxref{Pattern Matching}).
+Some facilities from @cite{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 (@pxref{Pattern Matching}).
 
 @comment Roland sez:
 @comment The GNU C library as it stands conforms to 1003.2 draft 11, which
@@ -166,22 +166,24 @@ and other pattern matching facilities (@pxref{Pattern Matching}).
 @node Berkeley Unix, SVID, POSIX, Standards and Portability
 @subsection Berkeley Unix
 @cindex BSD Unix
-@cindex 4.x BSD Unix
+@cindex 4.@var{n} BSD Unix
 @cindex Berkeley Unix
 @cindex SunOS
 @cindex Unix, Berkeley
 
-The GNU C library defines facilities from some other versions of Unix,
-specifically from the 4.2 BSD and 4.3 BSD Unix systems (also known as
-@dfn{Berkeley Unix}) and from @dfn{SunOS} (a popular 4.2 BSD derivative
-that includes some Unix System V functionality).  
+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 @dfn{Berkeley Unix}) and from
+@dfn{SunOS} (a popular 4.2 BSD derivative that includes some Unix System
+V functionality).  These systems support most of the ANSI and POSIX
+facilities, and 4.4 BSD and newer releases of SunOS in fact support them all.
 
 The BSD facilities include symbolic links (@pxref{Symbolic Links}), the
 @code{select} function (@pxref{Waiting for I/O}), the BSD signal
 functions (@pxref{BSD Signal Handling}), and sockets (@pxref{Sockets}).
 
 @node SVID,  , Berkeley Unix, Standards and Portability
-@subsection @sc{svid} (The System V Interface Description)
+@subsection SVID (The System V Interface Description)
 @cindex SVID
 @cindex System V Unix
 @cindex Unix, System V
@@ -197,9 +199,7 @@ 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.)
 
-@strong{Incomplete:}  Are there any particular System V facilities that
-ought to be mentioned specifically here?
-
+@c !!! mention sysv ipc/shmem when it is there.
 
 
 @node Using the Library, Roadmap to the Manual, Standards and Portability, Introduction
@@ -325,9 +325,9 @@ 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 the  a macro call.
+necessary to recognize a macro call.
 
-You might occasionally want to avoid using the macro definition of a
+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:
 
@@ -386,7 +386,7 @@ just makes your program slower.
 The names of all library types, macros, variables and functions that
 come from the ANSI C standard are reserved unconditionally; your program
 @strong{may not} redefine these names.  All other library names are
-reserved if your programs explicitly includes the header file that
+reserved if your program explicitly includes the header file that
 defines or declares them.  There are several reasons for these
 restrictions:
 
@@ -447,7 +447,7 @@ used for additional macros specifying locale attributes.
 @item
 Names of all existing mathematics functions (@pxref{Mathematics})
 suffixed with @samp{f} or @samp{l} are reserved for corresponding
-functions that operate on @code{float} or @code{long double} arguments,
+functions that operate on @code{float} and @code{long double} arguments,
 respectively.
 
 @item
@@ -530,9 +530,12 @@ features by defining one or more of the feature macros.
 for more information about GCC options.@refill
 
 You should define these macros by using @samp{#define} preprocessor
-directives at the top of your source code files.  You could also use 
-the @samp{-D} option to GCC, but it's better if you make the source
-files indicate their own meaning in a self-contained way.
+directives at the top of your source code files.  These directives
+@emph{must} come before any @code{#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 @samp{-D} option to GCC, but it's
+better if you make the source files indicate their own meaning in a
+self-contained way.
 
 @comment (none)
 @comment POSIX.1
@@ -602,9 +605,10 @@ sequence of definitions:
 #define _SVID_SOURCE
 @end smallexample
 
-Note that if you do this, you may need to link your program with the BSD
+Note that if you do this, you must link your program with the BSD
 compatibility library by passing the @samp{-lbsd-compat} option to the
-compiler or linker.
+compiler or linker.  @strong{Note:} If you forget to do this, you may
+get very strange errors at run time.
 @end defvr
 
 We recommend you use @code{_GNU_SOURCE} in new programs.  If you don't
@@ -694,8 +698,7 @@ communication between processes sharing a common file system.
 @ref{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,
-such as @file{/etc/hosts}.
+Internet host addressing and how to use the system network databases.
 
 @item
 @ref{Low-Level Terminal Interface}, describes how you can change the
@@ -789,4 +792,6 @@ If you already know the name of the facility you are interested in, you
 can look it up in @ref{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.
+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.
index aa60d93..e2790b3 100644 (file)
@@ -29,7 +29,7 @@ and ownership.
 communication facilities.
 
 @item
-@ref{Sockets}, covering a more complicated interprocess communication
+@ref{Sockets}, which covers a more complicated interprocess communication
 facility with support for networking.
 
 @item
@@ -128,10 +128,11 @@ library are included in the POSIX.1 standard, however.
 @node File Position,  , Streams and File Descriptors, I/O Concepts
 @subsection File Position 
 
-One of the attributes of an open file is its @dfn{file position}
-that keeps track of where in the file the next character is to be read
-or written.  In the GNU system, the file position is simply an integer
-representing the number of bytes from the beginning of the file.
+One of the attributes of an open file is its @dfn{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
@@ -146,7 +147,8 @@ do permit this are sometimes referred to as @dfn{random-access} files.
 You can change the file position using the @code{fseek} function on a
 stream (@pxref{File Positioning}) or the @code{lseek} function on a file
 descriptor (@pxref{I/O Primitives}).  If you try to change the file
-position on a file that doesn't support random access, you get an error.
+position on a file that doesn't support random access, you get the
+@code{ESPIPE} error.
 @cindex random-access files
 
 Streams and descriptors that are opened for @dfn{append access} are
@@ -247,8 +249,9 @@ process; otherwise the file name resolution fails.
 @cindex root directory
 @cindex absolute file name
 If a file name begins with a @samp{/}, the first component in the file
-name is located in the @dfn{root directory} of the process.  Such a file
-name is called an @dfn{absolute file name}.
+name is located in the @dfn{root directory} of the process (usually all
+processes on the system have the same root directory).  Such a file name
+is called an @dfn{absolute file name}.
 @c !!! xref here to chroot, if we ever document chroot. -rm
 @c ??? I don't like the idea of encouraging smoking--rms.
 @c !!! What the hell is that bad pun supposed to mean?  I don't get it.  -rm
@@ -264,7 +267,9 @@ have special meanings.  Every directory has entries for these file name
 components.  The file name component @file{.} refers to the directory
 itself, while the file name component @file{..} refers to its
 @dfn{parent directory} (the directory that contains the link for the
-directory in question).
+directory in question).  As a special case, @file{..} in the root
+directory refers to the root directory itself, since it has no parent;
+thus @file{/..} is the same as @file{/}.
 
 Here are some examples of file names:
 
@@ -331,11 +336,18 @@ component.
 
 @item ENOENT
 This error is reported when a file referenced as a directory component
-in the file name doesn't exist.
+in the file name doesn't exist, or when a component is a symbolic link
+whose target file does not exist.  @xref{Symbolic Links}.
 
 @item ENOTDIR
 A file that is referenced as a directory component in the file name
 exists, but it isn't a directory.
+
+@item 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.  @xref{Symbolic Links}.
 @end table
 
 
index 8a0dc27..4bdba63 100644 (file)
@@ -5,11 +5,14 @@
 @setchapternewpage odd
 @comment %**end of header (This is for running Texinfo on a region.)
 
+@c This tells texinfo.tex to use the real section titles in xrefs in
+@c place of the node name, when no section title is explicitly given.
+@set xref-automatic-section-title
 @smallbook
 
-@set EDITION 0.04 (Preliminary)
+@set EDITION 0.05
 @set VERSION 1.07 Beta
-@set UPDATED 20 June 1993
+@set UPDATED 30 August 1993
 
 @ifinfo
 This file documents the GNU C library.
index 0c931a4..d2d7557 100644 (file)
@@ -53,7 +53,7 @@ The collating sequence for the local language and character set
 (@pxref{Collation Functions}).
 
 @item
-Formatting of numbers and currency amounts.
+Formatting of numbers and currency amounts (@pxref{Numeric Formatting}).
 
 @item
 Formatting of dates and times (@pxref{Formatting Date and Time}).
@@ -102,7 +102,7 @@ locales will exist, except for one standard locale called @samp{C} or
 
 @cindex combining locales
 A user also has the option of specifying different locales for different
-purposes---in effect, choosing a mixture of two locales.
+purposes---in effect, choosing a mixture of multiple locales.
 
 For example, the user might specify the locale @samp{espana-castellano}
 for most purposes, but specify the locale @samp{usa-english} for
@@ -138,8 +138,9 @@ and @code{strxfrm}); see @ref{Collation Functions}.
 @comment ANSI
 @item LC_CTYPE
 @vindex LC_CTYPE
-This category applies to classification and conversion of characters;
-see @ref{Character Handling}.
+This category applies to classification and conversion of characters,
+and to multibyte and wide characters;
+see @ref{Character Handling} and @ref{Extended Characters}.
 
 @comment locale.h
 @comment ANSI
@@ -313,8 +314,8 @@ This is the standard POSIX locale.  Currently, it is an alias for the
 standard C locale.
 
 @item ""
-The empty name stands for a site-specific default locale.  It's supposed
-to be a good default for the machine on which the program is running.
+The empty name says to select a locale based on environment variables.
+@xref{Locale Categories}.
 @end table
 
 Defining and installing named locales is normally a responsibility of
index 75cdc54..c058cbf 100644 (file)
@@ -38,7 +38,7 @@ You can represent extended characters in either of two ways:
 
 @itemize @bullet
 @item
-As @dfn{Multibyte characters} which can be embedded in an ordinary
+As @dfn{multibyte characters} which can be embedded in an ordinary
 string, an array of @code{char} objects.  Their advantage is that many
 programs and operating systems can handle occasional multibyte
 characters scattered among ordinary ASCII characters, without any
@@ -431,10 +431,10 @@ can use @code{mblen} to find this out.
 @comment stdlib.h
 @comment ANSI
 @deftypefun int mblen (const char *@var{string}, size_t @var{size})
-The @code{mblen} function with non-null @var{string} returns the number
-of bytes that make up the multibyte character beginning at @var{string},
-never examining more than @var{size} bytes.  (The idea is to supply
-for @var{size} the number of bytes of data you have in hand.)
+The @code{mblen} function with a non-null @var{string} argument returns
+the number of bytes that make up the multibyte character beginning at
+@var{string}, never examining more than @var{size} bytes.  (The idea is
+to supply for @var{size} the number of bytes of data you have in hand.)
 
 The return value of @code{mblen} distinguishes three possibilities: the
 first @var{size} bytes at @var{string} start with valid multibyte
@@ -563,10 +563,11 @@ file_mbstowcs (int input, int output)
 
       /* @r{Fill up the buffer from the input file.}  */
       nread = read (input, buffer + filled, BUFSIZ);
-      if (nread < 0) @{
-        perror ("read");
-        return 0;
-      @}
+      if (nread < 0)
+        @{
+          perror ("read");
+          return 0;
+        @}
       /* @r{If we reach end of file, make a note to read no more.} */
       if (nread == 0)
         eof = 1;
@@ -611,8 +612,8 @@ file_mbstowcs (int input, int output)
           return 0;
         @}
 
-      /* @r{If any characters must be carried forward,
-         put them at the beginning of @code{buffer}.} */
+      /* @r{If any characters must be carried forward,}
+         @r{put them at the beginning of @code{buffer}.} */
       if (filled > 0)
         memcpy (inp, buffer, filled);
       @}
index 2ea915e..8228741 100644 (file)
@@ -1,3 +1,6 @@
+@comment !!! describe mmap et al (here?)
+@c !!! doc brk/sbrk
+
 @node Memory Allocation, Character Handling, Error Reporting, Top
 @chapter Memory Allocation
 @cindex memory allocation
@@ -226,7 +229,7 @@ savestring (const char *ptr, size_t len)
 @{
   register char *value = (char *) xmalloc (len + 1);
   memcpy (value, ptr, len);
-  value[len] = 0;
+  value[len] = '\0';
   return value;
 @}
 @end smallexample
@@ -332,6 +335,12 @@ may find it necessary to copy the block to a new address where more free
 space is available.  The value of @code{realloc} is the new address of the
 block.  If the block needs to be moved, @code{realloc} copies the old
 contents.
+
+If you pass a null pointer for @var{ptr}, @code{realloc} behaves just
+like @samp{malloc (@var{newsize})}.  This can be convenient, but beware
+that older implementations (before ANSI C) may not support this
+behavior, and will probably crash when @code{realloc} is passed a null
+pointer.
 @end deftypefun
 
 Like @code{malloc}, @code{realloc} may return a null pointer if no
@@ -407,6 +416,7 @@ 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
 @code{malloc} more efficient, make it a power of two.
+@c !!! xref getpagesize
 
 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
@@ -443,7 +453,7 @@ however---BSD does not provide any way to free such blocks.
 
 @comment malloc.h stdlib.h
 @comment BSD
-@deftypefun {void *} memalign (size_t @var{size}, int @var{boundary})
+@deftypefun {void *} memalign (size_t @var{size}, size_t @var{boundary})
 The @code{memalign} function allocates a block of @var{size} bytes whose
 address is a multiple of @var{boundary}.  The @var{boundary} must be a
 power of two!  The function @code{memalign} works by calling
@@ -455,7 +465,16 @@ address within the block that is on the specified boundary.
 @comment BSD
 @deftypefun {void *} valloc (size_t @var{size})
 Using @code{valloc} is like using @code{memalign} and passing the page size
-as the value of the second argument.
+as the value of the second argument.  It is implemented like this:
+
+@smallexample
+void *
+valloc (size_t size)
+@{
+  return memalign (size, getpagesize ());
+@}
+@end smallexample
+@c !!! xref getpagesize
 @end deftypefun
 
 @node Heap Consistency Checking
@@ -471,7 +490,7 @@ declared in @file{malloc.h}.
 
 @comment malloc.h
 @comment GNU
-@deftypefun void mcheck (void (*@var{abortfn}) (void))
+@deftypefun int mcheck (void (*@var{abortfn}) (void))
 Calling @code{mcheck} tells @code{malloc} to perform occasional
 consistency checks.  These will catch things such as writing
 past the end of a block that was allocated with @code{malloc}.
@@ -486,7 +505,8 @@ case.  The function returns @code{-1} if you call it too late, and
 @code{0} otherwise (when it is successful).
 
 The easiest way to arrange to call @code{mcheck} early enough is to use
-the option @samp{-lmcheck} when you link your program.
+the option @samp{-lmcheck} when you link your program; then you don't
+need to modify your program source at all.
 @end deftypefun
 
 @node Hooks for Malloc
@@ -591,7 +611,7 @@ storage allocator.  It contains the following members:
 
 @table @code
 @item size_t bytes_total
-This is the total size of memory managed by malloc, in bytes.
+This is the total size of memory managed by @code{malloc}, in bytes.
 
 @item size_t chunks_used
 This is the number of chunks in use.  (The storage allocator internally
@@ -642,14 +662,14 @@ Allocate a block of @var{count} * @var{eltsize} bytes using
 Space}.
 
 @item void *valloc (size_t @var{size})
-Allocate a block @var{size} bytes, starting on a page boundary.
+Allocate a block of @var{size} bytes, starting on a page boundary.
 @xref{Aligned Memory Blocks}.
 
 @item void *memalign (size_t @var{size}, size_t @var{boundary})
-Allocate a block @var{size} bytes, starting on an address that is a
+Allocate a block of @var{size} bytes, starting on an address that is a
 multiple of @var{boundary}.  @xref{Aligned Memory Blocks}.
 
-@item void mcheck (void (*@var{abortfn}) (void))
+@item int mcheck (void (*@var{abortfn}) (void))
 Tell @code{malloc} to perform occasional consistency checks on
 dynamically allocated memory, and to call @var{abortfn} when an
 inconsistency is found.  @xref{Heap Consistency Checking}.
@@ -663,8 +683,8 @@ A pointer to a function that @code{realloc} uses whenever it is called.
 @item void (*__free_hook) (void *@var{ptr})
 A pointer to a function that @code{free} uses whenever it is called.
 
-@item void struct mstats mstats (void)
-Read information about the current dynamic memory usage.
+@item struct mstats mstats (void)
+Return information about the current dynamic memory usage.
 @xref{Statistics of Malloc}.
 @end table
 
@@ -823,7 +843,7 @@ requires you to specify an @var{obstack_ptr} as the first argument.
 @end deftypefun
 
 For example, here is a function that allocates a copy of a string @var{str}
-in a specific obstack, which is the variable @code{string_obstack}:
+in a specific obstack, which is in the variable @code{string_obstack}:
 
 @smallexample
 struct obstack string_obstack;
@@ -1543,14 +1563,13 @@ several reasons:
 @itemize @bullet
 @item
 A variable size array's space is freed at the end of the scope of the
-name of the array.  The space allocated with @code{alloca} usually
+name of the array.  The space allocated with @code{alloca}
 remains until the end of the function.
 
 @item
 It is possible to use @code{alloca} within a loop, allocating an
 additional block on each iteration.  This is impossible with
-variable-sized arrays.  On the other hand, this is also slightly
-unclean.
+variable-sized arrays.
 @end itemize
 
 @strong{Note:} If you mix use of @code{alloca} and variable-sized arrays
@@ -1650,12 +1669,13 @@ and does not modify @code{*@var{handleptr}}.
 
 @pindex malloc.c
 You can ask for warnings as the program approaches running out of memory
-space, by calling @code{memory_warnings}.  This is a GNU extension
-declared in @file{malloc.h}.
+space, by calling @code{memory_warnings}.  This tells @code{malloc} to
+check memory usage every time it asks for more memory from the operating
+system.  This is a GNU extension declared in @file{malloc.h}.
 
 @comment malloc.h
 @comment GNU
-@deftypefun void memory_warnings (void *@var{start}, void (*@var{warn_func}) (char *))
+@deftypefun void memory_warnings (void *@var{start}, void (*@var{warn_func}) (const char *))
 Call this function to request warnings for nearing exhaustion of virtual
 memory.
 
index 47d5c3e..3d004bc 100644 (file)
@@ -1,8 +1,10 @@
 @node Pattern Matching, I/O Overview, Searching and Sorting, Top
 @chapter Pattern Matching
 
-The GNU C Library provides pattern matching facilities for two kinds
-of patterns: regular expressions and file-name wildcards.
+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.
@@ -66,8 +68,10 @@ Treat the @samp{.} character specially if it appears at the beginning of
 cannot match @samp{.} as the first character of @var{string}.
 
 If you set both @code{FNM_PERIOD} and @code{FNM_FILE_NAME}, then the
-special treatment applies to @samp{.} following @samp{/} as well as
-to @samp{.} at the beginning of @var{string}.
+special treatment applies to @samp{.} following @samp{/} as well as to
+@samp{.} at the beginning of @var{string}.  (The shell uses the
+@code{FNM_PERIOD} and @code{FNM_FILE_NAME} falgs together for matching
+file names.)
 
 @comment fnmatch.h
 @comment POSIX.2
@@ -137,7 +141,7 @@ records both the address of the word vector and its size.
 The number of elements in the vector.
 
 @item gl_pathv
-The address of the vector.  This field has type @code{char **}.
+The address of the vector.  This field has type @w{@code{char **}}.
 
 @item gl_offs
 The offset of the first real element of the vector, from its nominal
@@ -161,7 +165,7 @@ the beginning of the vector.
 The function @code{glob} does globbing using the pattern @var{pattern}
 in the current directory.  It puts the result in a newly allocated
 vector, and stores the size and address of this vector into
-@code{*@var{vector-ptr}}.  The argument @var{flags} is a combination of
+@code{*@var{vector_ptr}}.  The argument @var{flags} is a combination of
 bit flags; see @ref{Flags for Globbing}, for details of the flags.
 
 The result of globbing is a sequence of file names.  The function
@@ -172,7 +176,7 @@ This vector is called the @dfn{word vector}.
 
 To return this vector, @code{glob} stores both its address and its
 length (number of elements, not counting the terminating null pointer)
-into @code{*@var{vector-ptr}}.
+into @code{*@var{vector_ptr}}.
 
 Normally, @code{glob} sorts the file names alphabetically before 
 returning them.  You can turn this off with the flag @code{GLOB_NOSORT}
@@ -191,6 +195,13 @@ of these error codes:
 There was an error opening a directory, and you used the flag
 @code{GLOB_ERR} or your specified @var{errfunc} returned a nonzero
 value.
+@iftex
+See below
+@end iftex
+@ifinfo
+@xref{Flags for Globbing},
+@end ifinfo
+for an explanation of the @code{GLOB_ERR} flag and @var{errfunc}.
 
 @comment glob.h
 @comment POSIX.2
@@ -207,7 +218,7 @@ It was impossible to allocate memory to hold the result.
 @end table
 
 In the event of an error, @code{glob} stores information in
-@code{*@var{vector-ptr}} about all the matches it has found so far.
+@code{*@var{vector_ptr}} about all the matches it has found so far.
 @end deftypefun
 
 @node Flags for Globbing
@@ -215,7 +226,7 @@ In the event of an error, @code{glob} stores information in
 
 This section describes the flags that you can specify in the 
 @var{flags} argument to @code{glob}.  Choose the flags you want,
-and combine them with the C operator @code{|}.
+and combine them with the C bitwise OR operator @code{|}.
 
 @table @code
 @comment glob.h
@@ -230,6 +241,12 @@ word vector structure between calls to @code{glob}.  And, if you set
 @code{GLOB_DOOFFS} in the first call to @code{glob}, you must also
 set it when you append to the results.
 
+Note that the pointer stored in @code{gl_pathv} may no longer be valid
+after you call @code{glob} the second time, because @code{glob} might
+have relocated the vector.  So always fetch @code{gl_pathv} from the
+@code{glob_t} structure after each @code{glob} call; @strong{never} save
+the pointer across calls.
+
 @comment glob.h
 @comment POSIX.2
 @item GLOB_DOOFFS
@@ -246,11 +263,11 @@ fully.  Such difficulties might include a directory in which you don't
 have the requisite access.  Normally, @code{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 @var{errfunc} when you call @code{glob}.  If @var{errfunc} is
-nonzero, then @code{glob} doesn't give up right away when it can't read
-a directory; instead, it calls @var{errfunc} with two arguments, like
-this:
+You can exercise even more control than this by specifying an
+error-handler function @var{errfunc} when you call @code{glob}.  If
+@var{errfunc} is not a null pointer, then @code{glob} doesn't give up
+right away when it can't read a directory; instead, it calls
+@var{errfunc} with two arguments, like this:
 
 @smallexample
 (*@var{errfunc}) (@var{filename}, @var{error-code})
@@ -309,10 +326,9 @@ 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 @file{regex.h}.
-If you define @code{_GNU_SOURCE}, then the GNU functions, structures
-and constants are declared.  Otherwise, only the POSIX names are
-declared.
-@c !!! wrong-- default is GNU
+If you define @w{@code{_POSIX_C_SOURCE}}, then only the POSIX.2
+functions, structures, and constants are declared.
+@c !!! we only document the POSIX.2 interface here!!
 
 @menu
 * POSIX Regexp Compilation::    Using @code{regcomp} to prepare to match.
@@ -459,7 +475,7 @@ One of the endpoints in a range expression was invalid.
 @comment regex.h
 @comment POSIX.2
 @item REG_ESPACE
-@code{regcomp} or @code{regexec} ran out of memory.
+@code{regcomp} ran out of memory.
 @end table
 
 @node Flags for POSIX Regexps
@@ -559,7 +575,7 @@ The pattern didn't match the string.  This isn't really an error.
 @comment regex.h
 @comment POSIX.2
 @item REG_ESPACE
-@code{regcomp} or @code{regexec} ran out of memory.
+@code{regexec} ran out of memory.
 @end table
 
 @node Regexp Subexpressions
@@ -569,10 +585,10 @@ When @code{regexec} matches parenthetical subexpressions of
 @var{pattern}, it records which parts of @var{string} they match.  It
 returns that information by storing the offsets into an array whose
 elements are structures of type @code{regmatch_t}.  The first element of
-the array 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.
-@c !!! in this paragraph, [0] is called "first"; see below
+the array (index @code{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.
 
 @comment regex.h
 @comment POSIX.2
@@ -598,10 +614,10 @@ The fields of @code{regmatch_t} have type @code{regoff_t}.
 @end deftp
 
 The @code{regmatch_t} elements correspond to subexpressions
-positionally; the first element 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.
-@c !!! here [1] is called "first"; see above
+positionally; the first element (index @code{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 @code{regexec}, you specify how long the @var{matchptr}
 array is, with the @var{nmatch} argument.  This tells @code{regexec} how
@@ -643,7 +659,7 @@ accurate to say that the last @emph{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 @samp{\(ba\(na\)*s \)} matching
+subexpression.  For an example, consider @samp{\(ba\(na\)*s \)*} matching
 the string @samp{bananas bas }.  The last time the inner expression
 actually matches is near the end of the first word.  But it is 
 @emph{considered} again in the second word, and fails to match there.
@@ -827,7 +843,7 @@ records both the address of the word vector and its size.
 The number of elements in the vector.
 
 @item we_wordv
-The address of the vector.  This field has type @code{char **}.
+The address of the vector.  This field has type @w{@code{char **}}.
 
 @item we_offs
 The offset of the first real element of the vector, from its nominal
@@ -957,6 +973,10 @@ Reuse a word vector made by a previous call to @code{wordexp}.
 Instead of allocating a new vector of words, this call to @code{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 @code{wordexp}.  You must fetch
+@code{we_pathv} anew after each call.
+
 @comment wordexp.h
 @comment POSIX.2
 @item WRDE_SHOWERR
index ed6e3fd..b328a39 100644 (file)
@@ -38,19 +38,12 @@ numbers of type @code{double}:
 int
 compare_doubles (const double *a, const double *b)
 @{
-  double temp = *a - *b;
-  if (temp > 0)
-    return 1;
-  else if (temp < 0)
-    return -1;
-  else
-    return 0;
+  return (int) (*a - *b);
 @}
 @end smallexample
 
 The header file @file{stdlib.h} defines a name for the data type of
-comparison functions.  This is a GNU extension and thus defined only if
-you request the GNU extensions.
+comparison functions.  This type is a GNU extension.
 
 @comment stdlib.h
 @comment GNU
@@ -75,7 +68,7 @@ the header file @file{stdlib.h}.
 @deftypefun {void *} bsearch (const void *@var{key}, const void *@var{array}, size_t @var{count}, size_t @var{size}, comparison_fn_t @var{compare})
 The @code{bsearch} function searches the sorted array @var{array} for an object
 that is equivalent to @var{key}.  The array contains @var{count} elements,
-each of which is of size @var{size}.
+each of which is of size @var{size} bytes.  
 
 The @var{compare} function is used to perform the comparison.  This
 function is called with two pointer arguments and should return an
@@ -140,7 +133,7 @@ Functions}):
 @end smallexample
 
 The @code{qsort} function derives its name from the fact that it was
-originally implemented using the algorithm ``quick sort''.
+originally implemented using the ``quick sort'' algorithm.
 @end deftypefun
 
 @node Search/Sort Example,  , Array Sort Function, Searching and Sorting
@@ -160,6 +153,22 @@ Then, we can look up individual objects based on their names.
 The output from this program looks like:
 
 @smallexample
+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
@@ -176,7 +185,6 @@ Swedish Chef, the human
 Sweetums, the monster
 Zoot, the human
 
-
 Kermit, the frog
 Gonzo, the whatever
 Couldn't find Janice.
index 3e7ab74..6927bf1 100644 (file)
@@ -49,12 +49,12 @@ The @code{FILE} type is declared in the header file @file{stdio.h}.
 @comment stdio.h
 @comment ANSI
 @deftp {Data Type} FILE
-This is the data type is used to represent stream objects.  A
-@code{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
-@code{ferror} and @code{feof} functions; see @ref{EOF and Errors}.
+This is the data type used to represent stream objects.  A @code{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 @code{ferror}
+and @code{feof} functions; see @ref{EOF and Errors}.
 @end deftp
 
 @code{FILE} objects are allocated and managed internally by the
@@ -74,34 +74,31 @@ three predefined streams open and available for use.  These represent
 the ``standard'' input and output channels that have been established
 for the process.
 
-@c !!! in glibc, these are variables that you can set.  i.e., freopen is
-@c obsolete because you can do "fclose(stdout);stdout=fopen(...);"
-
 These streams are declared in the header file @file{stdio.h}.
 @pindex stdio.h
 
 @comment stdio.h
 @comment ANSI
-@deftypevr Macro {FILE *} stdin
+@deftypevar {FILE *} stdin
 The @dfn{standard input} stream, which is the normal source of input for the
 program.
-@end deftypevr
+@end deftypevar
 @cindex standard input stream
 
 @comment stdio.h
 @comment ANSI
-@deftypevr Macro {FILE *} stdout
+@deftypevar {FILE *} stdout
 The @dfn{standard output} stream, which is used for normal output from
 the program.
-@end deftypevr
+@end deftypevar
 @cindex standard output stream
 
 @comment stdio.h
 @comment ANSI
-@deftypevr Macro {FILE *} stderr
+@deftypevar {FILE *} stderr
 The @dfn{standard error} stream, which is used for error messages and
 diagnostics issued by the program.
-@end deftypevr
+@end deftypevar
 @cindex standard error stream
 
 In the GNU system, you can specify what files or processes correspond to
@@ -110,8 +107,18 @@ shell.  (The primitives shells use to implement these facilities are
 described in @ref{File System Interface}.)  Most other operating systems
 provide similar mechanisms, but the details of how to use them can vary.
 
-It is probably not a good idea to close any of the standard streams.
-But you can use @code{freopen} to get te effect of closing one and
+In the GNU C library, @code{stdin}, @code{stdout}, and @code{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:
+
+@smallexample
+fclose (stdout);
+stdout = fopen ("standard-output-file", "w");
+@end smallexample
+
+Note however, that in other systems @code{stdin}, @code{stdout}, and
+@code{stderr} are macros that you cannot assign to in the normal way.
+But you can use @code{freopen} to get the effect of closing one and
 reopening it.  @xref{Opening Streams}.
 
 @node Opening Streams
@@ -145,35 +152,35 @@ Open the file for writing only.  If the file already exists, it is
 truncated to zero length.  Otherwise a new file is created.
 
 @item a
-Open file for append access; that is, writing at the end of file only.
+Open 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.
 
 @item r+
-Open existing file for both reading and writing.  The initial contents
+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.
 
 @item w+
-Open file for both reading and writing.  If the file already exists, it
+Open file for both reading and writing.  If the file already exists, it
 is truncated to zero length.  Otherwise, a new file is created.
 
 @item 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 might be at either
-the beginning or end of the file, but output is always appended
-to the end of the file.
+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.
 @end table
 
-@c !!! this paragraph is false in glibc; "getc(fp);putc('x',fp);" works fine.
 As you can see, @samp{+} requests a stream that can do both input and
-output.  When using such a stream, you must call @code{fflush}
-(@pxref{Stream Buffering}) or a file positioning function such as
-@code{fseek} (@pxref{File Positioning}) when switching from reading to
-writing or vice versa.  Otherwise, internal buffers might not be emptied
-properly.
+output.  The ANSI standard says that when using such a stream, you must
+call @code{fflush} (@pxref{Stream Buffering}) or a file positioning
+function such as @code{fseek} (@pxref{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.
 
 The GNU C library defines one additional character for use in
 @var{opentype}: the character @samp{x} insists on creating a new
@@ -226,10 +233,12 @@ and associated with the same stream object @var{stream}.
 If the operation fails, a null pointer is returned; otherwise,
 @code{freopen} returns @var{stream}.
 
-The main use of @code{freopen} is to connect a standard stream such as
-@code{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.
-@c !!! can do stdout=... in glibc
+@code{freopen} has traditionally been used to connect a standard stream
+such as @code{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 @code{fopen}.  But other systems lack
+this ability, so using @code{freopen} is more portable.
 @end deftypefun
 
 
@@ -239,7 +248,7 @@ in which use of a standard stream for certain purposes is hard-coded.
 @cindex closing a stream
 When a stream is closed with @code{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 any more.
+cannot perform any additional operations on it.
 
 @comment stdio.h
 @comment ANSI
@@ -333,6 +342,13 @@ outputs the text @samp{Are you hungry?} followed by a newline.
 The @code{puts} function writes the string @var{s} to the stream
 @code{stdout} followed by a newline.  The terminating null character of
 the string is not written.
+
+@code{puts} is the most convenient function for printing simple
+messages.  For example:
+
+@smallexample
+puts ("This is a message.");
+@end smallexample
 @end deftypefun
 
 @comment stdio.h
@@ -380,32 +396,33 @@ as the value of the @var{stream} argument.
 
 Here is an example of a function that does input using @code{fgetc}.  It
 would work just as well using @code{getc} instead, or using
-@code{getchar ()} instead of @code{fgetc (stdin)}.
+@code{getchar ()} instead of @w{@code{fgetc (stdin)}}.
 
 @smallexample
 int
 y_or_n_p (const char *question)
 @{
   fputs (question, stdout);
-  while (1) @{
-    int c, answer;
-    /* @r{Write a space to separate answer from question.} */
-    fputc (' ', stdout);
-    /* @r{Read the first character of the line.}
-       @r{This should be the answer character, but might not be.} */
-    c = tolower (fgetc (stdin));
-    answer = c;
-    /* @r{Discard rest of input line.} */
-    while (c != '\n')
-      c = fgetc (stdin);
-    /* @r{Obey the answer if it was valid.} */
-    if (answer == 'y')
-      return 1;
-    if (answer == 'n')
-      return 0;
-    /* @r{Answer was invalid: ask for valid answer.} */
-    fputs ("Please answer y or n:", stdout);
-  @}
+  while (1)
+    @{
+      int c, answer;
+      /* @r{Write a space to separate answer from question.} */
+      fputc (' ', stdout);
+      /* @r{Read the first character of the line.}
+         @r{This should be the answer character, but might not be.} */
+      c = tolower (fgetc (stdin));
+      answer = c;
+      /* @r{Discard rest of input line.} */
+      while (c != '\n')
+        c = fgetc (stdin);
+      /* @r{Obey the answer if it was valid.} */
+      if (answer == 'y')
+        return 1;
+      if (answer == 'n')
+        return 0;
+      /* @r{Answer was invalid: ask for valid answer.} */
+      fputs ("Please answer y or n:", stdout);
+    @}
 @}
 @end smallexample
 
@@ -442,15 +459,17 @@ This function reads an entire line from @var{stream}, storing the text
 and storing the buffer address in @code{*@var{lineptr}}.
 
 Before calling @code{getline}, you should place in @code{*@var{lineptr}}
-the address of a buffer @code{*@var{n}} bytes long.  If this buffer is
-long enough to hold the line, @code{getline} stores the line in this
-buffer.  Otherwise, @code{getline} makes the buffer bigger using
-@code{realloc}, storing the new buffer address back in
-@code{*@var{lineptr}} and the increased size back in @code{*@var{n}}.
+the address of a buffer @code{*@var{n}} bytes long, allocated with
+@code{malloc}.  If this buffer is long enough to hold the line,
+@code{getline} stores the line in this buffer.  Otherwise,
+@code{getline} makes the buffer bigger using @code{realloc}, storing the
+new buffer address back in @code{*@var{lineptr}} and the increased size
+back in @code{*@var{n}}.
+@xref{Unconstrained Allocation}.
 
 If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}}
 to zero, before the call, then @code{getline} allocates the initial
-buffer for you.
+buffer for you by calling @code{malloc}.
 
 In either case, when @code{getline} returns,  @code{*@var{lineptr}} is
 a @code{char *} which points to the text of the line.
@@ -478,6 +497,17 @@ reading until it sees that character (or end of file).
 The text is stored in @var{lineptr}, including the delimiter character
 and a terminating null.  Like @code{getline}, @code{getdelim} makes
 @var{lineptr} bigger if it isn't big enough.
+
+@code{getline} is in fact implemented in terms of @code{getdelim}, just
+like this:
+
+@smallexample
+ssize_t
+getline (char **lineptr, size_t *n, FILE *stream)
+@{
+  return getdelim (lineptr, n, '\n', stream);
+@}
+@end smallexample
 @end deftypefun
 
 @comment stdio.h
@@ -591,7 +621,7 @@ so that the next input characters will be @samp{9} and @samp{b}.
 @subsection Using @code{ungetc} To Do Unreading
  
 The function to unread a character is called @code{ungetc}, because it
-reverses the action of @code{fgetc}.
+reverses the action of @code{getc}.
 
 @comment stdio.h
 @comment ANSI
@@ -601,7 +631,7 @@ input stream @var{stream}.  So the next input from @var{stream} will
 read @var{c} before anything else.
 
 If @var{c} is @code{EOF}, @code{ungetc} does nothing and just returns
-@code{EOF}.  This lets call @code{ungetc} with the return value of
+@code{EOF}.  This lets you call @code{ungetc} with the return value of
 @code{getc} without needing to check for an error from @code{getc}.
 
 The character that you push back doesn't have to be the same as the last
@@ -635,14 +665,15 @@ the next read operation on the stream.
 
 @smallexample
 #include <stdio.h>
+#include <ctype.h>
 
 void
 skip_whitespace (FILE *stream)
 @{
   int c;
   do
-    /* @r{No need to check for @code{EOF} because it is not
-       @code{isspace}, and @code{ungetc} ignores @code{EOF}.}  */
+    /* @r{No need to check for @code{EOF} because it is not}
+       @r{@code{isspace}, and @code{ungetc} ignores @code{EOF}.}  */
     c = getc (stream);
   while (isspace (c));
   ungetc (c, stream);
@@ -761,9 +792,9 @@ a template string.
 The conversion specifications in a @code{printf} template string have
 the general form:
 
-@smallexample
+@example
 % @var{flags} @var{width} @r{[} . @var{precision} @r{]} @var{type} @var{conversion}
-@end smallexample
+@end example
 
 For example, in the conversion specifier @samp{%-10.8ld}, the @samp{-}
 is a flag, @samp{10} specifies the field width, the precision is
@@ -888,6 +919,7 @@ Note that this conversion specification never produces any output.
 
 @item @samp{%m}
 Print the string corresponding to the value of @code{errno}.
+(This is a GNU extension.)
 @xref{Other Output Conversions}.
 
 @item @samp{%%}
@@ -941,7 +973,7 @@ For the @samp{%o} conversion, this forces the leading digit to be
 to the result.  This doesn't do anything useful for the @samp{%d},
 @samp{%i}, or @samp{%u} conversions.  Using this flag produces output
 which can be parsed by the @code{strtoul} function (@pxref{Parsing of
-Integers}) and @code{scanf} with the @code{%i} conversion
+Integers}) and @code{scanf} with the @samp{%i} conversion
 (@pxref{Numeric Input Conversions}).
 
 @item @samp{0}
@@ -990,7 +1022,7 @@ the sole purpose of @samp{%Z} is to specify the data type
 Here is an example.  Using the template string:
 
 @smallexample
-|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
+"|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
 @end smallexample
 
 @noindent
@@ -1142,12 +1174,13 @@ printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
 prints @samp{hello}.
 
 The @samp{%s} conversion prints a string.  The corresponding argument
-must be of type @code{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 @samp{-} 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:
+must be of type @code{char *} (or @code{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
+@samp{-} 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:
 
 @smallexample
 printf ("%3s%-6s", "no", "where");
@@ -1293,9 +1326,10 @@ produce.  The trailing null character is counted towards this limit, so
 you should allocate at least @var{size} characters for the string @var{s}.
 
 The return value is the number of characters stored, not including the
-terminating null.  If this value equals @var{size}, then there was not
-enough space in @var{s} for all the output.  You should try again with a
-bigger output string.  Here is an example of doing this:
+terminating null.  If this value equals @code{@var{size} - 1}, then
+there was not enough space in @var{s} for all the output.  You should
+try again with a bigger output string.  Here is an example of doing
+this:
 
 @smallexample
 @group
@@ -1307,6 +1341,8 @@ make_message (char *name, char *value)
   /* @r{Guess we need no more than 100 chars of space.} */
   int size = 100;
   char *buffer = (char *) xmalloc (size);
+@end group
+@group
   while (1)
     @{
       /* @r{Try to print in the allocated space.} */
@@ -1343,7 +1379,7 @@ buffer you allocate in advance.  The @var{ptr} argument should be the
 address of a @code{char *} object, and @code{asprintf} stores a pointer
 to the newly allocated string at that location.
 
-Here is how to use @code{asprint} to get the same result as the
+Here is how to use @code{asprintf} to get the same result as the
 @code{snprintf} example, but more easily:
 
 @smallexample
@@ -1407,10 +1443,10 @@ arguments again through that pointer.  Calling @code{vprintf} does not
 destroy the argument list of your function, merely the particular
 pointer that you passed to it.
 
-The GNU library does not have such restrictions.  You can safely
-continue to fetch arguments from a @code{va_list} pointer after passing
-it to @code{vprintf}, and @code{va_end} is a no-op.  (Note, however,
-that subsequent @code{va_arg} calls will fetch the same arguments which
+GNU C does not have such restrictions.  You can safely continue to fetch
+arguments from a @code{va_list} pointer after passing it to
+@code{vprintf}, and @code{va_end} is a no-op.  (Note, however, that
+subsequent @code{va_arg} calls will fetch the same arguments which
 @code{vprintf} previously used.)
 
 Prototypes for these functions are declared in @file{stdio.h}.
@@ -1656,54 +1692,56 @@ perhaps others which are not valid here).
 int
 validate_args (char *format, int nargs, OBJECT *args)
 @{
-  int nelts = 20;
   int *argtypes;
   int nwanted;
 
-  /* @r{Get the information about the arguments.}  */
-  while (1) @{
-    argtypes = (int *) alloca (nelts * sizeof (int));
-    nwanted = parse_printf_format (string, nelts, argtypes);
-    if (nwanted <= nelts)
-      break;
-    nelts *= 2;
-  @}
+  /* @r{Get the information about the arguments.}
+     @r{Each conversion specification must be at least two characters}
+     @r{long, so there cannot be more specifications than half the}
+     @r{length of the string.}  */
+
+  argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
+  nwanted = parse_printf_format (string, nelts, argtypes);
 
   /* @r{Check the number of arguments.}  */
-  if (nwanted > nargs) @{
-    error ("too few arguments (at least %d required)", nwanted);
-    return 0;
-  @}
+  if (nwanted > nargs)
+    @{
+      error ("too few arguments (at least %d required)", nwanted);
+      return 0;
+    @}
     
   /* @r{Check the C type wanted for each argument}
      @r{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:
+  for (i = 0; i < nwanted; i++)
+    @{
+      int wanted;
+
+      if (argtypes[i] & PA_FLAG_PTR)
         wanted = STRUCTURE;
-        break;
-      @}
-    if (TYPE (args[i]) != wanted) @{
-      error ("type mismatch for arg number %d", i);
-      return 0;
+      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;
 @}
 @end smallexample
@@ -1788,7 +1826,7 @@ written by other people could break if you do this.
 @subsection Conversion Specifier Options
 
 If you define a meaning for @samp{%q}, what if the template contains
-@samp{%+Sq} or @samp{%-#q}?  To implement a sensible meaning for these,
+@samp{%+23q} or @samp{%-#q}?  To implement a sensible meaning for these,
 the handler when called needs to be able to get the options specified in
 the template.
 
@@ -1892,9 +1930,9 @@ means of @code{va_arg (@var{type}, *ap_pointer)}.
 function to update its own @code{va_list} variable to account for the
 arguments that your handler processes.  @xref{Variadic Functions}.)
 
-The return value from your handler function should be the number of
-argument values that it processes from the variable argument list.  You
-can also return a value of @code{-1} to indicate an error.
+Your handler function should return a value just like @code{printf}
+does: it should return the number of characters it has written, or a
+negative value to indicate an error.
 
 @comment printf.h
 @comment GNU
@@ -1915,9 +1953,9 @@ int @var{function} (const struct printf_info *info,
 @end smallexample
 
 The return value from the function should be the number of arguments the
-conversion expects, up to a maximum of @var{n}.  The function should
-also fill in the @var{argtypes} array with information about the types
-of each of these arguments.  This information is encoded using the
+conversion expects.  The function should also fill in no more than
+@var{n} elements of the @var{argtypes} array with information about the
+types of each of these arguments.  This information is encoded using the
 various @samp{PA_} macros.  (You will notice that this is the same
 calling convention @code{parse_printf_format} itself uses.)
 
@@ -2029,10 +2067,11 @@ 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 Bison to generate a
-parser, rather than using @code{scanf}.  For more information about
-this, see @ref{Top, Bison, Bison, bison.info, The Bison Reference
-Manual}.
+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
+@code{scanf}.  For more information about this, see @ref{Top, Flex,
+Flex, flex.info, Flex: The Lexical Scanner Generator} and @ref{Top,
+Bison, Bison, bison.info, The Bison Reference Manual}.
 
 @node Input Conversion Syntax
 @subsection Input Conversion Syntax
@@ -2076,6 +2115,7 @@ successful assignments.
 @item
 An optional flag character @samp{a} (valid with string conversions only)
 which requests allocation of a buffer long enough to store the string in.
+(This is a GNU extension.)
 @xref{Dynamic String Input}.
 
 @item
@@ -2085,7 +2125,7 @@ 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.
-Most input conversions store a null character to mark the end of the
+String input conversions store a null character to mark the end of the
 input; the maximum field width does not include this terminator.
 @cindex maximum field width (@code{scanf})
 
@@ -2393,8 +2433,10 @@ This section describes the miscellaneous input conversions.
 
 The @samp{%p} conversion is used to read a pointer value.  It recognizes
 the same syntax as is used by the @samp{%p} output conversion for
-@code{printf}.  The corresponding argument should be of type @code{void **};
-that is, the address of a place to store a pointer.
+@code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal
+number just as the @samp{%x} conversion accepts.  The corresponding
+argument should be of type @code{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.
index f63141d..e57917f 100644 (file)
@@ -211,12 +211,13 @@ behavior of this function is undefined if the two arrays @var{to} and
 The value returned by @code{memcpy} is the value of @var{to}.
 
 Here is an example of how you might use @code{memcpy} to copy the
-contents of a @code{struct}:
+contents of an array:
 
 @smallexample
-struct foo *old, *new;
+struct foo *oldarray, *newarray;
+int arraysize;
 @dots{}
-memcpy (new, old, sizeof(struct foo));
+memcpy (new, old, arraysize * sizeof (struct foo));
 @end smallexample
 @end deftypefun
 
@@ -388,7 +389,9 @@ arguments are not in the same order.
 @deftypefun {void *} bzero (void *@var{block}, size_t @var{size})
 This is a partially obsolete alternative for @code{memset}, derived from
 BSD.  Note that it is not as general as @code{memset}, because the only
-value it can store is zero.
+value it can store is zero.  Some machines have special instructions for
+zeroing memory, so @code{bzero} might be more efficient than
+@code{memset}.
 @end deftypefun
 
 @node String/Array Comparison, Collation Functions, Copying and Concatenation, String and Array Utilities
@@ -752,6 +755,12 @@ specifying a null character as the value of the @var{c} argument.
 @end deftypefun
 
 @comment string.h
+@comment BSD
+@deftypefun {char *} index (const char *@var{string}, int @var{c})
+@code{index} is another name for @code{strchr}; they are exactly the same.
+@end deftypefun
+
+@comment string.h
 @comment ANSI
 @deftypefun {char *} strrchr (const char *@var{string}, int @var{c})
 The function @code{strrchr} is like @code{strchr}, except that it searches
@@ -766,6 +775,12 @@ strrchr ("hello, world", 'l')
 @end deftypefun
 
 @comment string.h
+@comment BSD
+@deftypefun {char *} rindex (const char *@var{string}, int @var{c})
+@code{rindex} is another name for @code{strrchr}; they are exactly the same.
+@end deftypefun
+
+@comment string.h
 @comment ANSI
 @deftypefun {char *} strstr (const char *@var{haystack}, const char *@var{needle})
 This is like @code{strchr}, except that it searches @var{haystack} for a