Libiberty manual cleanup patch

["Joseph S. Myers" <jsm28 at cam dot ac dot uk>]

This patch cleans up the libiberty manual.  (Diffs to functions.texi
omitted below.)  It passes "make info" and "make dvi".  Applied to
mainline.

2001-10-07  Joseph S. Myers  <jsm28@cam.ac.uk>

	* alloca.c, clock.c, getcwd.c, getpagesize.c, getpwd.c, index.c,
	libiberty.texi, memchr.c, putenv.c, rindex.c, strchr.c, strdup.c,
	strerror.c, strrchr.c, strstr.c, strtod.c, tmpnam.c, vfork.c,
	xatexit.c, xmalloc.c, xstrerror.c: Improve manual formatting.  Fix
	spelling.  Give names to function arguments in documentation.  Use
	(void) prototypes in documentation.
	* functions.texi: Regenerate.

diff -ruN libiberty.orig/alloca.c libiberty/alloca.c
--- libiberty.orig/alloca.c	Thu Sep 27 08:59:47 2001
+++ libiberty/alloca.c	Sun Oct  7 21:23:30 2001
@@ -23,7 +23,7 @@
 
 /*
 
-@deftypefn Replacement void* alloca (size_t)
+@deftypefn Replacement void* alloca (size_t @var{size})
 
 This function allocates memory which will be automatically reclaimed
 after the procedure exits.  The @libib{} implementation does not free
@@ -36,7 +36,7 @@
 available this function.  The @code{AC_FUNC_ALLOCA} test requires that
 client code use a block of preprocessor code to be safe (see the Autoconf
 manual for more); this header incorporates that logic and more, including
-the possibility of a GCC builtin function.
+the possibility of a GCC built-in function.
 
 @end deftypefn
 
diff -ruN libiberty.orig/clock.c libiberty/clock.c
--- libiberty.orig/clock.c	Thu Sep 27 08:59:47 2001
+++ libiberty/clock.c	Sun Oct  7 21:23:42 2001
@@ -24,7 +24,7 @@
 
 /*
 
-@deftypefn Supplemental long clock ()
+@deftypefn Supplemental long clock (void)
 
 Returns an approximation of the CPU time used by the process as a
 @code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the
diff -ruN libiberty.orig/getcwd.c libiberty/getcwd.c
--- libiberty.orig/getcwd.c	Thu Sep 27 08:59:47 2001
+++ libiberty/getcwd.c	Sun Oct  7 21:24:52 2001
@@ -3,13 +3,13 @@
 
 /*
 
-@deftypefn Supplemental char* getcwd (char *@var{pathname}, @var{len})
+@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len})
 
 Copy the absolute pathname for the current working directory into
 @var{pathname}, which is assumed to point to a buffer of at least
 @var{len} bytes, and return a pointer to the buffer.  If the current
 directory's path doesn't fit in @var{len} characters, the result is
-NULL and @var{errno} is set.  If @var{pathname} is a null pointer,
+@code{NULL} and @code{errno} is set.  If @var{pathname} is a null pointer,
 @code{getcwd} will obtain @var{len} bytes of space using
 @code{malloc}.
 
diff -ruN libiberty.orig/getpagesize.c libiberty/getpagesize.c
--- libiberty.orig/getpagesize.c	Thu Sep 27 08:59:47 2001
+++ libiberty/getpagesize.c	Sun Oct  7 21:25:07 2001
@@ -2,7 +2,7 @@
 
 /*
 
-@deftypefn Supplemental int getpagesize ()
+@deftypefn Supplemental int getpagesize (void)
 
 Returns the number of bytes in a page of memory.  This is the
 granularity of many of the system memory management routines.  No
diff -ruN libiberty.orig/getpwd.c libiberty/getpwd.c
--- libiberty.orig/getpwd.c	Thu Sep 27 08:59:47 2001
+++ libiberty/getpwd.c	Sun Oct  7 21:25:22 2001
@@ -2,7 +2,7 @@
 
 /*
 
-@deftypefn Supplemental char* getpwd ()
+@deftypefn Supplemental char* getpwd (void)
 
 Returns the current working directory.  This implementation caches the
 result on the assumption that the process will not call @code{chdir}
diff -ruN libiberty.orig/index.c libiberty/index.c
--- libiberty.orig/index.c	Sat Sep 29 09:13:01 2001
+++ libiberty/index.c	Sun Oct  7 21:11:52 2001
@@ -5,7 +5,7 @@
 @deftypefn Supplemental char* index (char *@var{s}, int @var{c})
 
 Returns a pointer to the first occurrence of the character @var{c} in
-the string @var{s}, or NULL if not found.  The use of @code{index} is
+the string @var{s}, or @code{NULL} if not found.  The use of @code{index} is
 deprecated in new programs in favor of @code{strchr}.
 
 @end deftypefn
diff -ruN libiberty.orig/libiberty.texi libiberty/libiberty.texi
--- libiberty.orig/libiberty.texi	Sat Sep 29 09:13:01 2001
+++ libiberty/libiberty.texi	Sun Oct  7 21:30:37 2001
@@ -65,7 +65,8 @@
       section entitled ``GNU Free Documentation License''.
 
 @end titlepage
-
+@contents
+@page
 
 @ifnottex
 @node    Top,Using,,
@@ -319,6 +320,5 @@
 
 @printindex cp
 
-@contents
 @bye
 
diff -ruN libiberty.orig/memchr.c libiberty/memchr.c
--- libiberty.orig/memchr.c	Thu Sep 27 08:59:47 2001
+++ libiberty/memchr.c	Sun Oct  7 21:33:42 2001
@@ -2,12 +2,12 @@
 
 @deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n})
 
-This function searches memory starting at @code{*}@var{src} for the
+This function searches memory starting at @code{*@var{s}} for the
 character @var{c}.  The search only ends with the first occurrence of
 @var{c}, or after @var{length} characters; in particular, a null
 character does not terminate the search.  If the character @var{c} is
-found within @var{length} characters of @code{*}@var{src}, a pointer
-to the character is returned. If @var{c} is not found, then NULL is
+found within @var{length} characters of @code{*@var{s}}, a pointer
+to the character is returned.  If @var{c} is not found, then @code{NULL} is
 returned.
 
 @end deftypefn
diff -ruN libiberty.orig/putenv.c libiberty/putenv.c
--- libiberty.orig/putenv.c	Thu Sep 27 08:59:47 2001
+++ libiberty/putenv.c	Sun Oct  7 21:21:12 2001
@@ -22,7 +22,7 @@
 
 Uses @code{setenv} or @code{unsetenv} to put @var{string} into
 the environment or remove it.  If @var{string} is of the form
-@samp{name=value} the string is added; if no `=' is present the
+@samp{name=value} the string is added; if no @samp{=} is present the
 name is unset/removed.
 
 @end deftypefn
diff -ruN libiberty.orig/rindex.c libiberty/rindex.c
--- libiberty.orig/rindex.c	Sat Sep 29 09:13:01 2001
+++ libiberty/rindex.c	Sun Oct  7 21:12:45 2001
@@ -5,7 +5,7 @@
 @deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
 
 Returns a pointer to the last occurrence of the character @var{c} in
-the string @var{s}, or NULL if not found.  The use of @code{rindex} is
+the string @var{s}, or @code{NULL} if not found.  The use of @code{rindex} is
 deprecated in new programs in favor of @code{strrchr}.
 
 @end deftypefn
diff -ruN libiberty.orig/strchr.c libiberty/strchr.c
--- libiberty.orig/strchr.c	Sat Sep 29 09:13:01 2001
+++ libiberty/strchr.c	Sun Oct  7 21:12:57 2001
@@ -6,7 +6,7 @@
 @deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
 
 Returns a pointer to the first occurrence of the character @var{c} in
-the string @var{s}, or NULL if not found.  If @var{c} is itself the
+the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
 null character, the results are undefined.
 
 @end deftypefn
diff -ruN libiberty.orig/strdup.c libiberty/strdup.c
--- libiberty.orig/strdup.c	Thu Sep 27 08:59:47 2001
+++ libiberty/strdup.c	Sun Oct  7 21:13:09 2001
@@ -3,7 +3,7 @@
 @deftypefn Supplemental char* strdup (const char *@var{s})
 
 Returns a pointer to a copy of @var{s} in memory obtained from
-@code{malloc}, or NULL if insufficient memory was available.
+@code{malloc}, or @code{NULL} if insufficient memory was available.
 
 @end deftypefn
 
diff -ruN libiberty.orig/strerror.c libiberty/strerror.c
--- libiberty.orig/strerror.c	Sun Oct  7 17:14:33 2001
+++ libiberty/strerror.c	Sun Oct  7 21:26:36 2001
@@ -573,7 +573,7 @@
 should check the size of the table (@code{sys_nerr}) before indexing
 it, since new error codes may be added to the system before they are
 added to the table.  Thus @code{sys_nerr} might be smaller than value
-implied by the largest @code{errno} value defined in @file{errno.h}.
+implied by the largest @code{errno} value defined in @code{<errno.h>}.
 
 We return the maximum value that can be used to obtain a meaningful
 symbolic name or message.
@@ -612,7 +612,7 @@
 @var{num} is the error number.
 
 If the supplied error number is not a valid index into
-@code{sys_errlist}, returns NULL.
+@code{sys_errlist}, returns @code{NULL}.
 
 The returned string is only guaranteed to be valid only until the
 next call to @code{strerror}.
@@ -671,7 +671,7 @@
 
 Given an error number returned from a system call (typically returned
 in @code{errno}), returns a pointer to a string containing the
-symbolic name of that error number, as found in @file{errno.h}.
+symbolic name of that error number, as found in @code{<errno.h>}.
 
 If the supplied error number is within the valid range of indices for
 symbolic names, but no name is available for the particular error
@@ -679,7 +679,7 @@
 is the error number.
 
 If the supplied error number is not within the range of valid
-indices, then returns NULL.
+indices, then returns @code{NULL}.
 
 The contents of the location pointed to are only guaranteed to be
 valid until the next call to @code{strerrno}.
@@ -729,7 +729,7 @@
 
 @deftypefn Replacement int strtoerrno (const char *@var{name})
 
-Given the symbolic name of a error number (e.g., @code{EACCESS}), map it
+Given the symbolic name of a error number (e.g., @code{EACCES}), map it
 to an errno value.  If no translation is found, returns 0.
 
 @end deftypefn
diff -ruN libiberty.orig/strrchr.c libiberty/strrchr.c
--- libiberty.orig/strrchr.c	Sat Sep 29 09:13:01 2001
+++ libiberty/strrchr.c	Sun Oct  7 21:13:41 2001
@@ -6,7 +6,7 @@
 @deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
 
 Returns a pointer to the last occurrence of the character @var{c} in
-the string @var{s}, or NULL if not found.  If @var{c} is itself the
+the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
 null character, the results are undefined.
 
 @end deftypefn
diff -ruN libiberty.orig/strstr.c libiberty/strstr.c
--- libiberty.orig/strstr.c	Sat Sep 29 09:13:01 2001
+++ libiberty/strstr.c	Sun Oct  7 21:13:51 2001
@@ -7,7 +7,7 @@
 
 This function searches for the substring @var{sub} in the string
 @var{string}, not including the terminating null characters.  A pointer
-to the first occurrence of @var{sub} is returned, or NULL if the
+to the first occurrence of @var{sub} is returned, or @code{NULL} if the
 substring is absent.  If @var{sub} points to a string with zero
 length, the function returns @var{string}.
 
diff -ruN libiberty.orig/strtod.c libiberty/strtod.c
--- libiberty.orig/strtod.c	Thu Sep 27 08:59:48 2001
+++ libiberty/strtod.c	Sun Oct  7 21:14:09 2001
@@ -27,7 +27,7 @@
 @deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})
 
 This ANSI C function converts the initial portion of @var{string} to a
-@code{double}.  If @var{endptr} is not NULL, a pointer to the
+@code{double}.  If @var{endptr} is not @code{NULL}, a pointer to the
 character after the last character used in the conversion is stored in
 the location referenced by @var{endptr}.  If no conversion is
 performed, zero is returned and the value of @var{string} is stored in
diff -ruN libiberty.orig/tmpnam.c libiberty/tmpnam.c
--- libiberty.orig/tmpnam.c	Thu Sep 27 08:59:48 2001
+++ libiberty/tmpnam.c	Sun Oct  7 21:14:22 2001
@@ -5,7 +5,7 @@
 This function attempts to create a name for a temporary file, which
 will be a valid file name yet not exist when @code{tmpnam} checks for
 it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
-or be NULL.  Use of this function creates a security risk, and it must
+or be @code{NULL}.  Use of this function creates a security risk, and it must
 not be used in new projects.  Use @code{mkstemp} instead.
 
 @end deftypefn
diff -ruN libiberty.orig/vfork.c libiberty/vfork.c
--- libiberty.orig/vfork.c	Thu Sep 27 08:59:48 2001
+++ libiberty/vfork.c	Sun Oct  7 21:27:44 2001
@@ -3,7 +3,7 @@
 
 /*
 
-@deftypefn Supplemental int vfork ()
+@deftypefn Supplemental int vfork (void)
 
 Emulates @code{vfork} by calling @code{fork} and returning its value.
 
diff -ruN libiberty.orig/xatexit.c libiberty/xatexit.c
--- libiberty.orig/xatexit.c	Sat Sep 29 09:13:01 2001
+++ libiberty/xatexit.c	Sun Oct  7 21:18:05 2001
@@ -11,7 +11,7 @@
 @deftypefun int xatexit (void (*@var{fn}) (void))
 
 Behaves as the standard @code{atexit} function, but with no limit on
-the number of registered functions.  Returns 0 on success, or -1 on
+the number of registered functions.  Returns 0 on success, or @minus{}1 on
 failure.  If you use @code{xatexit} to register functions, you must use
 @code{xexit} to terminate your program.
 
diff -ruN libiberty.orig/xmalloc.c libiberty/xmalloc.c
--- libiberty.orig/xmalloc.c	Sat Sep 29 09:13:01 2001
+++ libiberty/xmalloc.c	Sun Oct  7 21:29:42 2001
@@ -29,13 +29,13 @@
 
 @end deftypefn
 
-@deftypefn Replacement void* xrealloc (void*, size_t)
+@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size})
 Reallocate memory without fail.  This routine functions like @code{realloc},
 but will behave the same as @code{xmalloc} if memory cannot be found.
 
 @end deftypefn
 
-@deftypefn Replacement void* xcalloc (size_t, size_t)
+@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize})
 
 Allocate memory without fail, and set it to zero.  This routine functions
 like @code{calloc}, but will behave the same as @code{xmalloc} if memory
diff -ruN libiberty.orig/xstrerror.c libiberty/xstrerror.c
--- libiberty.orig/xstrerror.c	Thu Sep 27 08:59:48 2001
+++ libiberty/xstrerror.c	Sun Oct  7 21:14:33 2001
@@ -7,7 +7,7 @@
 @deftypefn Replacement char* xstrerror (int @var{errnum})
 
 Behaves exactly like the standard @code{strerror} function, but
-will never return a NULL pointer.
+will never return a @code{NULL} pointer.
 
 @end deftypefn
 

-- 
Joseph S. Myers
jsm28@cam.ac.uk