merge from gcc

libiberty/ChangeLog

@@ -1,3 +1,16 @@
+2001-10-15  DJ Delorie  <dj@redhat.com>
+
+	* Makefile.in (TEXIFILES): Add fnmatch.txh.
+	(maint-undoc): New.
+	maint-tool: Add "undoc" tool.
+	* alloca.c, argv.c, asprintf.c, choose-temp.c, concat.c,
+	fdmatch.c, ffs.c, getruntime.c, insque.c, lbasename.c,
+	make-temp-file.c, mkstemps.c, pexecute.c, random.c, spaces.c,
+	strerror.s, strsignal.c, strtol.c, vasprintf.c: Add or update
+	documentation.
+	* fnmatch.txh: New.
+	* functions.texi: Regenerate.
+
 2001-10-10  Joseph S. Myers  <jsm28@cam.ac.uk>
 
 	* bcmp.c, setenv.c: Use "nonzero" instead of "non-zero".

libiberty/Makefile.in

@@ -172,8 +172,9 @@ TEXISRC = \
 	$(srcdir)/functions.texi
 
 # Additional files that have texi snippets that need to be collected
-# and sorted.
-TEXIFILES = 
+# and sorted.  Some are here because the sources are imported from
+# elsewhere.  Others represent headers in ../include.
+TEXIFILES = fnmatch.txh
 
 libiberty.info : $(srcdir)/libiberty.texi $(TEXISRC)
 	$(MAKEINFO) -I$(srcdir) $(srcdir)/libiberty.texi
@@ -257,6 +258,9 @@ maint-missing :
 maint-buildall : $(REQUIRED_OFILES) $(CONFIGURED_OFILES)
 	@true
 
+maint-undoc : $(srcdir)/functions.texi
+	@$(PERL) $(srcdir)/maint-tool -s $(srcdir) undoc
+
 # Need to deal with profiled libraries, too.
 
 # Cleaning has to be done carefully to ensure that we don't clean our SUBDIRS

libiberty/alloca.c

@@ -150,6 +150,8 @@ static header *last_alloca_header = NULL;	/* -> last alloca header.  */
    caller, but that method cannot be made to work for some
    implementations of C, for example under Gould's UTX/32.  */
 
+/* @undocumented C_alloca */
+
 PTR
 C_alloca (size)
      size_t size;

libiberty/argv.c

@@ -62,26 +62,15 @@ extern char *strdup ();		/* Duplicate a string */
 
 /*
 
-NAME
+@deftypefn Extension char** dupargv (char **@var{vector})
 
-	dupargv -- duplicate an argument vector
+Duplicate an argument vector.  Simply scans through @var{vector},
+duplicating each argument until the terminating @code{NULL} is found.
+Returns a pointer to the argument vector if successful. Returns
+@code{NULL} if there is insufficient memory to complete building the
+argument vector.
 
-SYNOPSIS
-
-	char **dupargv (vector)
-	char **vector;
-
-DESCRIPTION
-
-	Duplicate an argument vector.  Simply scans through the
-	vector, duplicating each argument until the
-	terminating NULL is found.
-
-RETURNS
-
-	Returns a pointer to the argument vector if
-	successful. Returns NULL if there is insufficient memory to
-	complete building the argument vector.
+@end deftypefn
 
 */
 
@@ -119,24 +108,14 @@ dupargv (argv)
 
 /*
 
-NAME
-
-	freeargv -- free an argument vector
-
-SYNOPSIS
+@deftypefn Extension void freeargv (char **@var{vector})
 
-	void freeargv (vector)
-	char **vector;
+Free an argument vector that was built using @code{buildargv}.  Simply
+scans through @var{vector}, freeing the memory for each argument until
+the terminating @code{NULL} is found, and then frees @var{vector}
+itself.
 
-DESCRIPTION
-
-	Free an argument vector that was built using buildargv.  Simply scans
-	through the vector, freeing the memory for each argument until the
-	terminating NULL is found, and then frees the vector itself.
-
-RETURNS
-
-	No value.
+@end deftypefn
 
 */
 
@@ -157,49 +136,42 @@ char **vector;
 
 /*
 
-NAME
-
-	buildargv -- build an argument vector from a string
-
-SYNOPSIS
-
-	char **buildargv (sp)
-	char *sp;
-
-DESCRIPTION
+@deftypefn Extension char** buildargv (char *@var{sp})
 
-	Given a pointer to a string, parse the string extracting fields
-	separated by whitespace and optionally enclosed within either single
-	or double quotes (which are stripped off), and build a vector of
-	pointers to copies of the string for each field.  The input string
-	remains unchanged.
+Given a pointer to a string, parse the string extracting fields
+separated by whitespace and optionally enclosed within either single
+or double quotes (which are stripped off), and build a vector of
+pointers to copies of the string for each field.  The input string
+remains unchanged.  The last element of the vector is followed by a
+@code{NULL} element.
 
-	All of the memory for the pointer array and copies of the string
-	is obtained from malloc.  All of the memory can be returned to the
-	system with the single function call freeargv, which takes the
-	returned result of buildargv, as it's argument.
+All of the memory for the pointer array and copies of the string
+is obtained from @code{malloc}.  All of the memory can be returned to the
+system with the single function call @code{freeargv}, which takes the
+returned result of @code{buildargv}, as it's argument.
 
-	The memory for the argv array is dynamically expanded as necessary.
+Returns a pointer to the argument vector if successful. Returns
+@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient
+memory to complete building the argument vector.
 
-RETURNS
+If the input is a null string (as opposed to a @code{NULL} pointer),
+then buildarg returns an argument vector that has one arg, a null
+string.
 
-	Returns a pointer to the argument vector if successful. Returns NULL
-	if the input string pointer is NULL or if there is insufficient
-	memory to complete building the argument vector.
+@end deftypefn
 
-NOTES
+The memory for the argv array is dynamically expanded as necessary.
 
-	In order to provide a working buffer for extracting arguments into,
-	with appropriate stripping of quotes and translation of backslash
-	sequences, we allocate a working buffer at least as long as the input
-	string.  This ensures that we always have enough space in which to
-	work, since the extracted arg is never larger than the input string.
+In order to provide a working buffer for extracting arguments into,
+with appropriate stripping of quotes and translation of backslash
+sequences, we allocate a working buffer at least as long as the input
+string.  This ensures that we always have enough space in which to
+work, since the extracted arg is never larger than the input string.
 
-	If the input is a null string (as opposed to a NULL pointer), then
-	buildarg returns an argv that has one arg, a null string.
+The argument vector is always kept terminated with a @code{NULL} arg
+pointer, so it can be passed to @code{freeargv} at any time, or
+returned, as appropriate.
 
-	Argv is always kept terminated with a NULL arg pointer, so it can
-	be passed to freeargv at any time, or returned, as appropriate.
 */
 
 char **buildargv (input)

libiberty/asprintf.c

@@ -28,6 +28,22 @@ Boston, MA 02111-1307, USA.  */
 #include <varargs.h>
 #endif
 
+/*
+
+@deftypefn Extension int asprintf (char **@var{resptr}, char *@var{format}, ...)
+
+Like @code{sprintf}, but instead of passing a pointer to a buffer, you
+pass a pointer to a pointer.  This function will compute the size of
+the buffer needed, allocate memory with @code{malloc}, and store a
+pointer to the allocated memory in @code{*@var{resptr}}.  The value
+returned is the same as @code{sprintf} would return.  If memory could
+not be allocated, zero is returned and @code{NULL} is stored in
+@code{*@var{resptr}}.
+
+@end deftypefn
+
+*/
+
 int
 asprintf VPARAMS ((char **buf, const char *fmt, ...))
 {

libiberty/choose-temp.c

@@ -37,13 +37,21 @@ extern char *choose_tmpdir PARAMS ((void));
 #define TEMP_FILE "ccXXXXXX"
 #define TEMP_FILE_LEN (sizeof(TEMP_FILE) - 1)
 
-/* Return a prefix for temporary file names or NULL if unable to find one.
-   The current directory is chosen if all else fails so the program is
-   exited if a temporary directory can't be found (mktemp fails).
-   The buffer for the result is obtained with xmalloc. 
+/*
 
-   This function is provided for backwards compatability only.  It use
-   is not recommended.  */
+@deftypefn Extension char* choose_temp_base ()
+
+Return a prefix for temporary file names or @code{NULL} if unable to
+find one.  The current directory is chosen if all else fails so the
+program is exited if a temporary directory can't be found (@code{mktemp}
+fails).  The buffer for the result is obtained with @code{xmalloc}.
+
+This function is provided for backwards compatability only.  Its use is
+not recommended.
+
+@end deftypefn
+
+*/
 
 char *
 choose_temp_base ()

libiberty/concat.c

@@ -21,24 +21,14 @@ Boston, MA 02111-1307, USA.  */
 
 /*
 
-NAME
+@deftypefn Extension char* concat (char *@var{s1}, char *@var{s2}, ..., @code{NULL})
 
-	concat -- concatenate a variable number of strings
+Concatenate zero or more of strings and return the result in freshly
+xmalloc'd memory.  Returns @code{NULL} if insufficient memory is
+available.  The argument list is terminated by the first @code{NULL}
+pointer encountered.  Pointers to empty strings are ignored.
 
-SYNOPSIS
-
-	#include <varargs.h>
-
-	char *concat (s1, s2, s3, ..., NULL)
-
-DESCRIPTION
-
-	Concatenate a variable number of strings and return the result
-	in freshly malloc'd memory.
-
-	Returns NULL if insufficient memory is available.  The argument
-	list is terminated by the first NULL pointer encountered.  Pointers
-	to empty strings are ignored.
+@end deftypefn
 
 NOTES
 
@@ -50,6 +40,7 @@ NOTES
 	deal with low memory situations itself, it should supply an xmalloc
 	that just directly invokes malloc and blindly returns whatever
 	malloc returns.
+
 */
 
 
@@ -114,6 +105,8 @@ vconcat_copy (dst, first, args)
   return dst;
 }
 
+/* @undocumented concat_length */
+
 unsigned long
 concat_length VPARAMS ((const char *first, ...))
 {
@@ -127,6 +120,8 @@ concat_length VPARAMS ((const char *first, ...))
   return length;
 }
 
+/* @undocumented concat_copy */
+
 char *
 concat_copy VPARAMS ((char *dst, const char *first, ...))
 {
@@ -144,6 +139,8 @@ concat_copy VPARAMS ((char *dst, const char *first, ...))
 
 char *libiberty_concat_ptr;
 
+/* @undocumented concat_copy2 */
+
 char *
 concat_copy2 VPARAMS ((const char *first, ...))
 {
@@ -175,6 +172,23 @@ concat VPARAMS ((const char *first, ...))
   return newstr;
 }
 
+/*
+
+@deftypefn Extension char* reconcat (char *@var{optr}, char *@var{s1}, ..., @code{NULL})
+
+Same as @code{concat}, except that if @var{optr} is not @code{NULL} it
+is freed after the string is created.  This is intended to be useful
+when you're extending an existing string or building up a string in a
+loop:
+
+@example
+  str = reconcat (str, "pre-", str, NULL);
+@end example
+
+@end deftypefn
+
+*/
+
 char *
 reconcat VPARAMS ((char *optr, const char *first, ...))
 {

libiberty/fdmatch.c

@@ -20,25 +20,19 @@ Boston, MA 02111-1307, USA.  */
 
 /*
 
-NAME
-
-	fdmatch -- see if two file descriptors refer to same file
-
-SYNOPSIS
-
-	int fdmatch (int fd1, int fd2)
-
-DESCRIPTION
-
-	Check to see if two open file descriptors refer to the same file.
-	This is useful, for example, when we have an open file descriptor
-	for an unnamed file, and the name of a file that we believe to 
-	correspond to that fd.  This can happen when we are exec'd with
-	an already open file (stdout for example) or from the SVR4 /proc
-	calls that return open file descriptors for mapped address spaces.
-	All we have to do is open the file by name and check the two file
-	descriptors for a match, which is done by comparing major&minor
-	device numbers and inode numbers.
+@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2})
+
+Check to see if two open file descriptors refer to the same file.
+This is useful, for example, when we have an open file descriptor for
+an unnamed file, and the name of a file that we believe to correspond
+to that fd.  This can happen when we are exec'd with an already open
+file (@code{stdout} for example) or from the SVR4 @file{/proc} calls
+that return open file descriptors for mapped address spaces.  All we
+have to do is open the file by name and check the two file descriptors
+for a match, which is done by comparing major and minor device numbers
+and inode numbers.
+
+@end deftypefn
 
 BUGS
 

libiberty/ffs.c

@@ -1,14 +1,12 @@
 /* ffs -- Find the first bit set in the parameter
 
-NAME
-	ffs -- Find the first bit set in the parameter
+@deftypefn Supplemental int ffs (int @var{valu})
 
-SYNOPSIS
-	int ffs (int valu)
+Find the first (least significant) bit set in @var{valu}. Bits are
+numbered from right to left, starting with bit 1 (corresponding to the
+value 1).  If @var{valu} is zero, zero is returned.
 
-DESCRIPTION
-	Find the first bit set in the parameter. Bits are numbered from
-	right to left, starting with bit 1.
+@end deftypefn
 
 */
 

libiberty/fnmatch.txh

@@ -0,0 +1,48 @@
+@deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags})
+
+Matches @var{string} against @var{pattern}, returning zero if it
+matches, @code{FNM_NOMATCH} if not.  @var{pattern} may contain the
+wildcards @code{?} to match any one character, @code{*} to match any
+zero or more characters, or a set of alternate characters in square
+brackets, like @samp{[a-gt8]}, which match one character (@code{a}
+through @code{g}, or @code{t}, or @code{8}, in this example) if that one
+character is in the set.  A set may be inverted (i.e. match anything
+except what's in the set) by giving @code{^} or @code{!} as the first
+character in the set.  To include those characters in the set, list them
+as anything other than the first character of the set.  To include a
+dash in the set, list it last in the set.  A backslash character makes
+the following character not special, so for example you could match
+against a literal asterisk with @samp{\*}.  To match a literal
+backslash, use @samp{\\}.
+
+@code{flags} controls various aspects of the matching process, and is a
+boolean OR of zero or more of the following values (defined in
+@code{<fnmatch.h>}:
+
+@table @code
+
+@item FNM_PATHNAME
+@itemx FNM_FILE_NAME
+@var{string} is assumed to be a path name.  No wildcard will ever match
+@code{/}.
+
+@item FNM_NOESCAPE
+Do not interpret backslashes as quoting the following special character.
+
+@item FNM_PERIOD
+A leading period (at the beginning of @var{string}, or if
+@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or
+@code{?} but must be matched explicitly.
+
+@item FNM_LEADING_DIR
+Means that @var{string} also matches @var{pattern} if some initial part
+of @var{string} matches, and is followed by @code{/} and zero or more
+characters.  For example, @samp{foo*} would match either @samp{foobar}
+or @samp{foobar/grill}.
+
+@item FNM_CASEFOLD
+Ignores case when performing the comparison.
+
+@end table
+
+@end deftypefn

libiberty/functions.texi

@@ -21,6 +21,19 @@ the possibility of a GCC built-in function.
 
 @end deftypefn
 
+@c asprintf.c:33
+@deftypefn Extension int asprintf (char **@var{resptr}, char *@var{format}, ...)
+
+Like @code{sprintf}, but instead of passing a pointer to a buffer, you
+pass a pointer to a pointer.  This function will compute the size of
+the buffer needed, allocate memory with @code{malloc}, and store a
+pointer to the allocated memory in @code{*@var{resptr}}.  The value
+returned is the same as @code{sprintf} would return.  If memory could
+not be allocated, zero is returned and @code{NULL} is stored in
+@code{*@var{resptr}}.
+
+@end deftypefn
+
 @c atexit.c:6
 @deftypefn Supplemental int atexit (void (*@var{f})())
 
@@ -69,6 +82,31 @@ is respectively less than, matching, or greater than the array member.
 
 @end deftypefn
 
+@c argv.c:139
+@deftypefn Extension char** buildargv (char *@var{sp})
+
+Given a pointer to a string, parse the string extracting fields
+separated by whitespace and optionally enclosed within either single
+or double quotes (which are stripped off), and build a vector of
+pointers to copies of the string for each field.  The input string
+remains unchanged.  The last element of the vector is followed by a
+@code{NULL} element.
+
+All of the memory for the pointer array and copies of the string
+is obtained from @code{malloc}.  All of the memory can be returned to the
+system with the single function call @code{freeargv}, which takes the
+returned result of @code{buildargv}, as it's argument.
+
+Returns a pointer to the argument vector if successful. Returns
+@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient
+memory to complete building the argument vector.
+
+If the input is a null string (as opposed to a @code{NULL} pointer),
+then buildarg returns an argument vector that has one arg, a null
+string.
+
+@end deftypefn
+
 @c bzero.c:6
 @deftypefn Supplemental void bzero (char *@var{mem}, int @var{count})
 
@@ -85,6 +123,27 @@ Uses @code{malloc} to allocate storage for @var{nelem} objects of
 
 @end deftypefn
 
+@c choose-temp.c:42
+@deftypefn Extension char* choose_temp_base ()
+
+Return a prefix for temporary file names or @code{NULL} if unable to
+find one.  The current directory is chosen if all else fails so the
+program is exited if a temporary directory can't be found (@code{mktemp}
+fails).  The buffer for the result is obtained with @code{xmalloc}.
+
+This function is provided for backwards compatability only.  Its use is
+not recommended.
+
+@end deftypefn
+
+@c make-temp-file.c:88
+@deftypefn Replacement char* choose_tmpdir ()
+
+Returns a pointer to a directory path suitable for creating temporary
+files in.
+
+@end deftypefn
+
 @c clock.c:27
 @deftypefn Supplemental long clock (void)
 
@@ -94,8 +153,29 @@ number of seconds used.
 
 @end deftypefn
 
+@c concat.c:24
+@deftypefn Extension char* concat (char *@var{s1}, char *@var{s2}, ..., @code{NULL})
+
+Concatenate zero or more of strings and return the result in freshly
+xmalloc'd memory.  Returns @code{NULL} if insufficient memory is
+available.  The argument list is terminated by the first @code{NULL}
+pointer encountered.  Pointers to empty strings are ignored.
+
+@end deftypefn
+
+@c argv.c:65
+@deftypefn Extension char** dupargv (char **@var{vector})
+
+Duplicate an argument vector.  Simply scans through @var{vector},
+duplicating each argument until the terminating @code{NULL} is found.
+Returns a pointer to the argument vector if successful. Returns
+@code{NULL} if there is insufficient memory to complete building the
+argument vector.
+
+@end deftypefn
+
 @c strerror.c:566
-@deftypefn Replacement int errno_max (void)
+@deftypefn Extension int errno_max (void)
 
 Returns the maximum @code{errno} value for which a corresponding
 symbolic name or message is available.  Note that in the case where we
@@ -112,6 +192,99 @@ symbolic name or message.
 
 @end deftypefn
 
+@c fdmatch.c:23
+@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2})
+
+Check to see if two open file descriptors refer to the same file.
+This is useful, for example, when we have an open file descriptor for
+an unnamed file, and the name of a file that we believe to correspond
+to that fd.  This can happen when we are exec'd with an already open
+file (@code{stdout} for example) or from the SVR4 @file{/proc} calls
+that return open file descriptors for mapped address spaces.  All we
+have to do is open the file by name and check the two file descriptors
+for a match, which is done by comparing major and minor device numbers
+and inode numbers.
+
+@end deftypefn
+
+@c ffs.c:3
+@deftypefn Supplemental int ffs (int @var{valu})
+
+Find the first (least significant) bit set in @var{valu}. Bits are
+numbered from right to left, starting with bit 1 (corresponding to the
+value 1).  If @var{valu} is zero, zero is returned.
+
+@end deftypefn
+
+@c fnmatch.txh:1
+@deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags})
+
+Matches @var{string} against @var{pattern}, returning zero if it
+matches, @code{FNM_NOMATCH} if not.  @var{pattern} may contain the
+wildcards @code{?} to match any one character, @code{*} to match any
+zero or more characters, or a set of alternate characters in square
+brackets, like @samp{[a-gt8]}, which match one character (@code{a}
+through @code{g}, or @code{t}, or @code{8}, in this example) if that one
+character is in the set.  A set may be inverted (i.e. match anything
+except what's in the set) by giving @code{^} or @code{!} as the first
+character in the set.  To include those characters in the set, list them
+as anything other than the first character of the set.  To include a
+dash in the set, list it last in the set.  A backslash character makes
+the following character not special, so for example you could match
+against a literal asterisk with @samp{\*}.  To match a literal
+backslash, use @samp{\\}.
+
+@code{flags} controls various aspects of the matching process, and is a
+boolean OR of zero or more of the following values (defined in
+@code{<fnmatch.h>}:
+
+@table @code
+
+@item FNM_PATHNAME
+@itemx FNM_FILE_NAME
+@var{string} is assumed to be a path name.  No wildcard will ever match
+@code{/}.
+
+@item FNM_NOESCAPE
+Do not interpret backslashes as quoting the following special character.
+
+@item FNM_PERIOD
+A leading period (at the beginning of @var{string}, or if
+@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or
+@code{?} but must be matched explicitly.
+
+@item FNM_LEADING_DIR
+Means that @var{string} also matches @var{pattern} if some initial part
+of @var{string} matches, and is followed by @code{/} and zero or more
+characters.  For example, @samp{foo*} would match either @samp{foobar}
+or @samp{foobar/grill}.
+
+@item FNM_CASEFOLD
+Ignores case when performing the comparison.
+
+@end table
+
+@end deftypefn
+
+@c argv.c:111
+@deftypefn Extension void freeargv (char **@var{vector})
+
+Free an argument vector that was built using @code{buildargv}.  Simply
+scans through @var{vector}, freeing the memory for each argument until
+the terminating @code{NULL} is found, and then frees @var{vector}
+itself.
+
+@end deftypefn
+
+@c getruntime.c:78
+@deftypefn Replacement long get_run_time ()
+
+Returns the time used so far, in microseconds.  If possible, this is
+the time used by this process, else it is the elapsed time since the
+process started.
+
+@end deftypefn
+
 @c getcwd.c:6
 @deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len})
 
@@ -153,6 +326,52 @@ deprecated in new programs in favor of @code{strchr}.
 
 @end deftypefn
 
+@c insque.c:6
+@deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred})
+@deftypefnx Supplemental void remque (struct qelem *@var{elem})
+
+Routines to manipulate queues built from doubly linked lists.  The
+@code{insque} routine inserts @var{elem} in the queue immediately
+after @var{pred}.  The @code{remque} routine removes @var{elem} from
+its containing queue.  These routines expect to be passed pointers to
+structures which have as their first members a forward pointer and a
+back pointer, like this prototype (although no prototype is provided):
+
+@example
+struct qelem @{
+  struct qelem *q_forw;
+  struct qelem *q_back;
+  char q_data[];
+@};
+@end example
+
+@end deftypefn
+
+@c lbasename.c:23
+@deftypefn Replacement {const char*} lbasename (const char *@var{name})
+
+Given a pointer to a string containing a typical pathname
+(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the
+last component of the pathname (@samp{ls.c} in this case).  The
+returned pointer is guaranteed to lie within the original
+string.  This latter fact is not true of many vendor C
+libraries, which return special strings or modify the passed
+strings for particular input.
+
+In particular, the empty string returns the same empty string,
+and a path ending in @code{/} returns the empty string after it.
+
+@end deftypefn
+
+@c make-temp-file.c:138
+@deftypefn Replacement char* make_temp_file (const char *@var{suffix})
+
+Return a temporary file name (as a string) or @code{NULL} if unable to
+create one.  @var{suffix} is a suffix to append to the file name.  The
+string is malloced, and the temporary file has been created.
+
+@end deftypefn
+
 @c memchr.c:3
 @deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n})
 
@@ -201,6 +420,71 @@ Sets the first @var{count} bytes of @var{s} to the constant byte
 
 @end deftypefn
 
+@c mkstemps.c:54
+@deftypefn Replacement int mkstemps (char *@var{template}, int @var{suffix_len})
+
+Generate a unique temporary file name from @var{template}.
+@var{template} has the form:
+
+@example
+   <path>/ccXXXXXX<suffix>
+@end example
+
+@var{suffix_len} tells us how long <suffix> is (it can be zero
+length).  The last six characters of @var{template} before <suffix>
+must be @code{XXXXXX}; they are replaced with a string that makes the
+filename unique.  Returns a file descriptor open on the file for
+reading and writing.
+
+@end deftypefn
+
+@c pexecute.c:67
+@deftypefn Extension int pexecute (const char *@var{program}, char * const *@var{argv}, const char *@var{this_pname}, const char *@var{temp_base}, char **@var{errmsg_fmt}, char **@var{errmsg_arg}, int flags)
+
+Executes a program.
+
+@var{program} and @var{argv} are the arguments to
+@code{execv}/@code{execvp}.
+
+@var{this_pname} is name of the calling program (i.e. @code{argv[0]}).
+
+@var{temp_base} is the path name, sans suffix, of a temporary file to
+use if needed.  This is currently only needed for MS-DOS ports that
+don't use @code{go32} (do any still exist?).  Ports that don't need it
+can pass @code{NULL}.
+
+(@var{flags} & @code{PEXECUTE_SEARCH}) is non-zero if @code{$PATH} should be searched
+(??? It's not clear that GCC passes this flag correctly). (@var{flags} &
+@code{PEXECUTE_FIRST}) is nonzero for the first process in chain.
+(@var{flags} & @code{PEXECUTE_FIRST}) is nonzero for the last process
+in chain.  The first/last flags could be simplified to only mark the
+last of a chain of processes but that requires the caller to always
+mark the last one (and not give up early if some error occurs).
+It's more robust to require the caller to mark both ends of the chain.
+
+The result is the pid on systems like Unix where we
+@code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we
+use @code{spawn}.  It is up to the caller to wait for the child.
+
+The result is the WEXITSTATUS on systems like MS-DOS where we
+@code{spawn} and wait for the child here.
+
+Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the
+text of the error message with an optional argument (if not needed,
+@var{errmsg_arg} is set to @code{NULL}), and -1 is returned.
+@code{errno} is available to the caller to use.
+
+@end deftypefn
+
+@c strsignal.c:547
+@deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message})
+
+Print @var{message} to the standard error, followed by a colon,
+followed by the description of the signal specified by @var{signo},
+followed by a newline.
+
+@end deftypefn
+
 @c putenv.c:21
 @deftypefn Supplemental int putenv (const char *@var{string})
 
@@ -211,6 +495,53 @@ name is unset/removed.
 
 @end deftypefn
 
+@c pexecute.c:104
+@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
+
+Waits for a program started by @code{pexecute} to finish.
+
+@var{pid} is the process id of the task to wait for. @var{status} is
+the `status' argument to wait. @var{flags} is currently unused (allows
+future enhancement without breaking upward compatibility).  Pass 0 for now.
+
+The result is the pid of the child reaped, or -1 for failure
+(@code{errno} says why).
+
+On systems that don't support waiting for a particular child, @var{pid} is
+ignored.  On systems like MS-DOS that don't really multitask @code{pwait}
+is just a mechanism to provide a consistent interface for the caller.
+
+@end deftypefn
+
+@c random.c:39
+@deftypefn Supplement {long int} random ()
+@deftypefnx Supplement void srandom (unsigned int @var{seed})
+@deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n})
+@deftypefnx Supplement void* setstate (void *@var{arg_state})
+
+Random number functions.  @code{random} returns a random number in the
+range @code{0..LONG_MAX}.  @code{srandom} initializes the random
+number generator to some starting point determined by @var{seed}
+(else, the values returned by @code{random} are always the same for each
+run of the program).  @code{initstate} and @code{setstate} allow fine-grain
+control over the state of the random number generator.
+
+@end deftypefn
+
+@c concat.c:177
+@deftypefn Extension char* reconcat (char *@var{optr}, char *@var{s1}, ..., @code{NULL})
+
+Same as @code{concat}, except that if @var{optr} is not @code{NULL} it
+is freed after the string is created.  This is intended to be useful
+when you're extending an existing string or building up a string in a
+loop:
+
+@example
+  str = reconcat (str, "pre-", str, NULL);
+@end example
+
+@end deftypefn
+
 @c rename.c:6
 @deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
 
@@ -240,6 +571,24 @@ environment.  This implementation is not safe for multithreaded code.
 
 @end deftypefn
 
+@c strsignal.c:353
+@deftypefn Extension int signo_max ()
+
+Returns the maximum signal value for which a corresponding symbolic
+name or message is available.  Note that in the case where we use the
+@code{sys_siglist} supplied by the system, it is possible for there to
+be more symbolic names than messages, or vice versa.  In fact, the
+manual page for @code{psignal(3b)} explicitly warns that one should
+check the size of the table (@code{NSIG}) before indexing it, since
+new signal codes may be added to the system before they are added to
+the table.  Thus @code{NSIG} might be smaller than value implied by
+the largest signo value defined in @code{<signal.h>}.
+
+We return the maximum value that can be used to obtain a meaningful
+symbolic name or message.
+
+@end deftypefn
+
 @c sigsetmask.c:8
 @deftypefn Supplemental int sigsetmask (int @var{set})
 
@@ -249,6 +598,15 @@ be the value @code{1}).
 
 @end deftypefn
 
+@c spaces.c:22
+@deftypefn Extension char* spaces (int @var{count})
+
+Returns a pointer to a memory region filled with the specified
+number of spaces and null terminated.  The returned pointer is
+valid until at least the next call.
+
+@end deftypefn
+
 @c strcasecmp.c:15
 @deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
 
@@ -274,7 +632,7 @@ Returns a pointer to a copy of @var{s} in memory obtained from
 @end deftypefn
 
 @c strerror.c:670
-@deftypefn Replacement const char* strerrno (int @var{errnum})
+@deftypefn Replacement {const char*} strerrno (int @var{errnum})
 
 Given an error number returned from a system call (typically returned
 in @code{errno}), returns a pointer to a string containing the
@@ -282,7 +640,7 @@ 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
-number, then returns the string @samp{"Error @var{num}"}, where @var{num}
+number, then returns the string @samp{Error @var{num}}, where @var{num}
 is the error number.
 
 If the supplied error number is not within the range of valid
@@ -294,7 +652,7 @@ valid until the next call to @code{strerrno}.
 @end deftypefn
 
 @c strerror.c:602
-@deftypefn Replacement char* strerror (int @var{errnoval})
+@deftypefn Supplemental char* strerror (int @var{errnoval})
 
 Maps an @code{errno} number to an error message string, the contents
 of which are implementation defined.  On systems which have the
@@ -303,7 +661,7 @@ strings will be the same as the ones used by @code{perror}.
 
 If the supplied error number is within the valid range of indices for
 the @code{sys_errlist}, but no message is available for the particular
-error number, then returns the string @samp{"Error @var{num}"}, where
+error number, then returns the string @samp{Error @var{num}}, where
 @var{num} is the error number.
 
 If the supplied error number is not a valid index into
@@ -338,6 +696,46 @@ null character, the results are undefined.
 
 @end deftypefn
 
+@c strsignal.c:388
+@deftypefn Supplemental {const char *} strsignal (int @var{signo})
+
+Maps an signal number to an signal message string, the contents of
+which are implementation defined.  On systems which have the external
+variable @code{sys_siglist}, these strings will be the same as the
+ones used by @code{psignal()}.
+
+If the supplied signal number is within the valid range of indices for
+the @code{sys_siglist}, but no message is available for the particular
+signal number, then returns the string @samp{Signal @var{num}}, where
+@var{num} is the signal number.
+
+If the supplied signal number is not a valid index into
+@code{sys_siglist}, returns @code{NULL}.
+
+The returned string is only guaranteed to be valid only until the next
+call to @code{strsignal}.
+
+@end deftypefn
+
+@c strsignal.c:452
+@deftypefn Extension {const char*} strsigno (int @var{signo})
+
+Given an signal number, returns a pointer to a string containing the
+symbolic name of that signal number, as found in @code{<signal.h>}.
+
+If the supplied signal number is within the valid range of indices for
+symbolic names, but no name is available for the particular signal
+number, then returns the string @samp{Signal @var{num}}, where
+@var{num} is the signal number.
+
+If the supplied signal number is not within the range of valid
+indices, then returns @code{NULL}.
+
+The contents of the location pointed to are only guaranteed to be
+valid until the next call to @code{strsigno}.
+
+@end deftypefn
+
 @c strstr.c:6
 @deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
 
@@ -362,7 +760,7 @@ the location referenced by @var{endptr}.
 @end deftypefn
 
 @c strerror.c:730
-@deftypefn Replacement int strtoerrno (const char *@var{name})
+@deftypefn Extension int strtoerrno (const char *@var{name})
 
 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.
@@ -371,6 +769,7 @@ to an errno value.  If no translation is found, returns 0.
 
 @c strtol.c:33
 @deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
+@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base})
 
 The @code{strtol} function converts the string in @var{string} to a
 long integer value according to the given @var{base}, which must be
@@ -379,7 +778,16 @@ is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
 to indicate bases 8 and 16, respectively, else default to base 10.
 When the base is 16 (either explicitly or implicitly), a prefix of
 @code{0x} is allowed.  The handling of @var{endptr} is as that of
-@code{strtod} above.
+@code{strtod} above.  The @code{strtoul} function is the same, except
+that the converted value is unsigned.
+
+@end deftypefn
+
+@c strsignal.c:507
+@deftypefn Extension int strtosigno (const char *@var{name})
+
+Given the symbolic name of a signal, map it to a signal number.  If no
+translation is found, returns 0.
 
 @end deftypefn
 
@@ -394,6 +802,19 @@ not be used in new projects.  Use @code{mkstemp} instead.
 
 @end deftypefn
 
+@c vasprintf.c:48
+@deftypefn Extension int vasprintf (char **@var{resptr}, char *@var{format}, va_list @var{args})
+
+Like @code{vsprintf}, but instead of passing a pointer to a buffer,
+you pass a pointer to a pointer.  This function will compute the size
+of the buffer needed, allocate memory with @code{malloc}, and store a
+pointer to the allocated memory in @code{*@var{resptr}}.  The value
+returned is the same as @code{vsprintf} would return.  If memory could
+not be allocated, zero is returned and @code{NULL} is stored in
+@code{*@var{resptr}}.
+
+@end deftypefn
+
 @c vfork.c:6
 @deftypefn Supplemental int vfork (void)
 

libiberty/getruntime.c

@@ -73,6 +73,18 @@ Boston, MA 02111-1307, USA.  */
 #endif
 #endif
 
+/*
+
+@deftypefn Replacement long get_run_time ()
+
+Returns the time used so far, in microseconds.  If possible, this is
+the time used by this process, else it is the elapsed time since the
+process started.
+
+@end deftypefn
+
+*/
+
 long
 get_run_time ()
 {

libiberty/insque.c

@@ -2,24 +2,27 @@
    This file is in the public domain.  */
 
 /*
-NAME
-	insque, remque -- insert, remove an element from a queue
 
-SYNOPSIS
-	struct qelem {
-	  struct qelem *q_forw;
-	  struct qelem *q_back;
-	  char q_data[];
-	};
+@deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred})
+@deftypefnx Supplemental void remque (struct qelem *@var{elem})
 
-	void insque (struct qelem *elem, struct qelem *pred)
+Routines to manipulate queues built from doubly linked lists.  The
+@code{insque} routine inserts @var{elem} in the queue immediately
+after @var{pred}.  The @code{remque} routine removes @var{elem} from
+its containing queue.  These routines expect to be passed pointers to
+structures which have as their first members a forward pointer and a
+back pointer, like this prototype (although no prototype is provided):
 
-	void remque (struct qelem *elem)
+@example
+struct qelem @{
+  struct qelem *q_forw;
+  struct qelem *q_back;
+  char q_data[];
+@};
+@end example
+
+@end deftypefn
 
-DESCRIPTION
-	Routines to manipulate queues built from doubly linked lists.
-	The insque routine inserts ELEM in the queue immediately after
-	PRED.  The remque routine removes ELEM from its containing queue.
 */
 
 

libiberty/lbasename.c

@@ -19,23 +19,22 @@ not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 Boston, MA 02111-1307, USA.  */
 
 /*
-NAME
-	lbasename -- return pointer to last component of a pathname
-
-SYNOPSIS
-	const char *lbasename (const char *name)
-
-DESCRIPTION
-	Given a pointer to a string containing a typical pathname
-	(/usr/src/cmd/ls/ls.c for example), returns a pointer to the
-	last component of the pathname ("ls.c" in this case).  The
-	returned pointer is guaranteed to lie within the original
-	string.  This latter fact is not true of many vendor C
-	libraries, which return special strings or modify the passed
-	strings for particular input.
-
-	In particular, the empty string returns the same empty string,
-	and a path ending in '/' returns the empty string after it.
+
+@deftypefn Replacement {const char*} lbasename (const char *@var{name})
+
+Given a pointer to a string containing a typical pathname
+(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the
+last component of the pathname (@samp{ls.c} in this case).  The
+returned pointer is guaranteed to lie within the original
+string.  This latter fact is not true of many vendor C
+libraries, which return special strings or modify the passed
+strings for particular input.
+
+In particular, the empty string returns the same empty string,
+and a path ending in @code{/} returns the empty string after it.
+
+@end deftypefn
+
 */
 
 #include "ansidecl.h"

libiberty/maint-tool

@@ -35,9 +35,17 @@ if ($mode eq "-s") {
 }
 
 &missing() if $mode eq "missing";
+&undoc() if $mode eq "undoc";
 
 exit 0;
 
+format STDOUT =
+^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~
+$out
+        ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
+$out
+.
+
 ######################################################################
 
 sub missing {
@@ -73,3 +81,100 @@ sub missing {
 	}
     }
 }
+
+######################################################################
+
+sub undoc {
+
+    opendir(S, $srcdir);
+    while ($file = readdir S) {
+	if ($file =~ /\.texi$/) {
+	    open(T, "$srcdir/$file");
+	    while (<T>) {
+		if (/^\@deftype[^\(]* ([^\s\(]+) *\(/) {
+		    $documented{$1} = 1;
+		}
+	    }
+	    close(T);
+	}
+	if ($file =~ /\.c$/) {
+	    open(C, "$srcdir/$file");
+	    while (<C>) {
+		if (/\@undocumented (\S+)/) {
+		    $documented{$1} = 1;
+		}
+		if (/^static /) {
+		    if (! /[\(;]/) {
+			s/[\r\n]+$/ /;
+			$_ .= <C>;
+		    }
+		    while ($_ =~ /\([^\)]*$/) {
+			s/[\r\n]+$/ /;
+			$_ .= <C>;
+		    }
+		}
+		s/ VPARAMS([ \(])/$1/;
+		s/PREFIX\(([^\)]*)\)/byte_$1/;
+		if (/^static [^\(]* ([^\s\(]+) *\(.*\)$/) {
+		    $documented{$1} = 1;
+		}
+	    }
+	}
+    }
+    closedir(D);
+
+    # $out = join(' ', sort keys %documented);
+    # write;
+    # print "\n";
+
+    system "etags $srcdir/*.c $srcdir/../include/*.h";
+    open(TAGS, "TAGS");
+    while (<TAGS>) {
+	s/[\r\n]+$//;
+	if (/^\014$/) {
+	    $filename = <TAGS>;
+	    $filename =~ s/[\r\n]+$//;
+	    $filename =~ s/,\d+$//;
+	    $filename =~ s@.*[/\\]@@;
+	    next;
+	}
+	if ($filename =~ /\.c$/ ) {
+	    next unless /^[_a-zA-Z]/;
+	} else {
+	    next unless /^\# *define/;
+	    s/\# *define *//;
+	}
+	next if $filename =~ /mpw\.c/;
+
+	s/ VPARAMS//;
+	s/ *\177.*//;
+	s/,$//;
+	s/DEFUN\(//;
+	s/\(//;
+
+	next if /^static /;
+	next if /\s/;
+	next if /^_/;
+	next if $documented{$_};
+	next if /_H_?$/;
+
+	if ($seen_in{$_} ne $filename) {
+	    $saw{$_} ++;
+	}
+	$seen_in{$_} = $filename;
+    }
+
+    for $k (keys %saw) {
+	delete $saw{$k} if $saw{$k} > 1;
+    }
+
+    for $k (sort keys %saw) {
+	$fromfile{$seen_in{$k}} .= " " if $fromfile{$seen_in{$k}};
+	$fromfile{$seen_in{$k}} .= $k;
+    }
+
+    for $f (sort keys %fromfile) {
+	$out = "$f: $fromfile{$f}";
+	write;
+    }
+}

libiberty/make-temp-file.c

@@ -83,6 +83,17 @@ static const char vartmp[] =
 
 static char *memoized_tmpdir;
 
+/*
+
+@deftypefn Replacement char* choose_tmpdir ()
+
+Returns a pointer to a directory path suitable for creating temporary
+files in.
+
+@end deftypefn
+
+*/
+
 char *
 choose_tmpdir ()
 {
@@ -122,9 +133,17 @@ choose_tmpdir ()
   return tmpdir;
 }
 
-/* Return a temporary file name (as a string) or NULL if unable to create
-   one.  SUFFIX is a suffix to append to the file name.  The string is
-   malloced, and the temporary file has been created.  */
+/*
+
+@deftypefn Replacement char* make_temp_file (const char *@var{suffix})
+
+Return a temporary file name (as a string) or @code{NULL} if unable to
+create one.  @var{suffix} is a suffix to append to the file name.  The
+string is malloced, and the temporary file has been created.
+
+@end deftypefn
+
+*/
 
 char *
 make_temp_file (suffix)

libiberty/mkstemps.c

@@ -49,18 +49,27 @@ typedef unsigned long gcc_uint64_t;
 #define TMP_MAX 16384
 #endif
 
-/* Generate a unique temporary file name from TEMPLATE.
+/*
 
-   TEMPLATE has the form:
+@deftypefn Replacement int mkstemps (char *@var{template}, int @var{suffix_len})
 
+Generate a unique temporary file name from @var{template}.
+@var{template} has the form:
+
+@example
    <path>/ccXXXXXX<suffix>
+@end example
+
+@var{suffix_len} tells us how long <suffix> is (it can be zero
+length).  The last six characters of @var{template} before <suffix>
+must be @code{XXXXXX}; they are replaced with a string that makes the
+filename unique.  Returns a file descriptor open on the file for
+reading and writing.
 
-   SUFFIX_LEN tells us how long <suffix> is (it can be zero length).
+@end deftypefn
 
-   The last six characters of TEMPLATE before <suffix> must be "XXXXXX";
-   they are replaced with a string that makes the filename unique.
+*/
 
-   Returns a file descriptor open on the file for reading and writing.  */
 int
 mkstemps (template, suffix_len)
      char *template;

libiberty/pexecute.c

@@ -64,53 +64,66 @@ static char *install_error_msg = "installation problem, cannot exec `%s'";
 
 /* pexecute: execute a program.
 
-   PROGRAM and ARGV are the arguments to execv/execvp.
+@deftypefn Extension int pexecute (const char *@var{program}, char * const *@var{argv}, const char *@var{this_pname}, const char *@var{temp_base}, char **@var{errmsg_fmt}, char **@var{errmsg_arg}, int flags)
 
-   THIS_PNAME is name of the calling program (i.e. argv[0]).
+Executes a program.
 
-   TEMP_BASE is the path name, sans suffix, of a temporary file to use
-   if needed.  This is currently only needed for MSDOS ports that don't use
-   GO32 (do any still exist?).  Ports that don't need it can pass NULL.
+@var{program} and @var{argv} are the arguments to
+@code{execv}/@code{execvp}.
 
-   (FLAGS & PEXECUTE_SEARCH) is non-zero if $PATH should be searched
-   (??? It's not clear that GCC passes this flag correctly).
-   (FLAGS & PEXECUTE_FIRST) is nonzero for the first process in chain.
-   (FLAGS & PEXECUTE_FIRST) is nonzero for the last process in chain.
-   FIRST_LAST could be simplified to only mark the last of a chain of processes
-   but that requires the caller to always mark the last one (and not give up
-   early if some error occurs).  It's more robust to require the caller to
-   mark both ends of the chain.
+@var{this_pname} is name of the calling program (i.e. @code{argv[0]}).
 
-   The result is the pid on systems like Unix where we fork/exec and on systems
-   like WIN32 and OS2 where we use spawn.  It is up to the caller to wait for
-   the child.
+@var{temp_base} is the path name, sans suffix, of a temporary file to
+use if needed.  This is currently only needed for MS-DOS ports that
+don't use @code{go32} (do any still exist?).  Ports that don't need it
+can pass @code{NULL}.
 
-   The result is the WEXITSTATUS on systems like MSDOS where we spawn and wait
-   for the child here.
+(@var{flags} & @code{PEXECUTE_SEARCH}) is non-zero if @code{$PATH} should be searched
+(??? It's not clear that GCC passes this flag correctly). (@var{flags} &
+@code{PEXECUTE_FIRST}) is nonzero for the first process in chain.
+(@var{flags} & @code{PEXECUTE_FIRST}) is nonzero for the last process
+in chain.  The first/last flags could be simplified to only mark the
+last of a chain of processes but that requires the caller to always
+mark the last one (and not give up early if some error occurs).
+It's more robust to require the caller to mark both ends of the chain.
 
-   Upon failure, ERRMSG_FMT and ERRMSG_ARG are set to the text of the error
-   message with an optional argument (if not needed, ERRMSG_ARG is set to
-   NULL), and -1 is returned.  `errno' is available to the caller to use.
+The result is the pid on systems like Unix where we
+@code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we
+use @code{spawn}.  It is up to the caller to wait for the child.
 
-   pwait: cover function for wait.
+The result is the WEXITSTATUS on systems like MS-DOS where we
+@code{spawn} and wait for the child here.
 
-   PID is the process id of the task to wait for.
-   STATUS is the `status' argument to wait.
-   FLAGS is currently unused (allows future enhancement without breaking
-   upward compatibility).  Pass 0 for now.
+Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the
+text of the error message with an optional argument (if not needed,
+@var{errmsg_arg} is set to @code{NULL}), and -1 is returned.
+@code{errno} is available to the caller to use.
 
-   The result is the pid of the child reaped,
-   or -1 for failure (errno says why).
+@end deftypefn
 
-   On systems that don't support waiting for a particular child, PID is
-   ignored.  On systems like MSDOS that don't really multitask pwait
-   is just a mechanism to provide a consistent interface for the caller.
+@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
+
+Waits for a program started by @code{pexecute} to finish.
+
+@var{pid} is the process id of the task to wait for. @var{status} is
+the `status' argument to wait. @var{flags} is currently unused (allows
+future enhancement without breaking upward compatibility).  Pass 0 for now.
+
+The result is the pid of the child reaped, or -1 for failure
+(@code{errno} says why).
+
+On systems that don't support waiting for a particular child, @var{pid} is
+ignored.  On systems like MS-DOS that don't really multitask @code{pwait}
+is just a mechanism to provide a consistent interface for the caller.
+
+@end deftypefn
+
+@undocumented pfinish
 
    pfinish: finish generation of script
 
    pfinish is necessary for systems like MPW where a script is generated that
-   runs the requested programs.
-*/
+   runs the requested programs.  */
 
 #ifdef __MSDOS__
 
@@ -254,7 +267,7 @@ extern int _spawnvp ();
 /* This is a kludge to get around the Microsoft C spawn functions' propensity
    to remove the outermost set of double quotes from all arguments.  */
 
-const char * const *
+static const char * const *
 fix_argv (argvec)
      char **argvec;
 {

libiberty/random.c

@@ -34,6 +34,24 @@
  * It was reworked for the GNU C Library by Roland McGrath.
  */
 
+/*
+
+@deftypefn Supplement {long int} random ()
+@deftypefnx Supplement void srandom (unsigned int @var{seed})
+@deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n})
+@deftypefnx Supplement void* setstate (void *@var{arg_state})
+
+Random number functions.  @code{random} returns a random number in the
+range @code{0..LONG_MAX}.  @code{srandom} initializes the random
+number generator to some starting point determined by @var{seed}
+(else, the values returned by @code{random} are always the same for each
+run of the program).  @code{initstate} and @code{setstate} allow fine-grain
+control over the state of the random number generator.
+
+@end deftypefn
+
+*/
+
 #include <errno.h>
 
 #if 0

libiberty/spaces.c

@@ -19,21 +19,13 @@ Boston, MA 02111-1307, USA.  */
 
 /*
 
-NAME
+@deftypefn Extension char* spaces (int @var{count})
 
-	spaces -- return a pointer to a buffer full of spaces
+Returns a pointer to a memory region filled with the specified
+number of spaces and null terminated.  The returned pointer is
+valid until at least the next call.
 
-SYNOPSIS
-
-	char *spaces (int count)
-
-DESCRIPTION
-
-	Returns a pointer to a memory region filled with the specified
-	number of spaces and null terminated.  The returned pointer is
-	valid until at least the next call.
-	
-BUGS
+@end deftypefn
 
 */
 

libiberty/strerror.c

@@ -563,7 +563,7 @@ init_error_tables ()
 /*
 
 
-@deftypefn Replacement int errno_max (void)
+@deftypefn Extension int errno_max (void)
 
 Returns the maximum @code{errno} value for which a corresponding
 symbolic name or message is available.  Note that in the case where we
@@ -599,7 +599,7 @@ errno_max ()
 
 /*
 
-@deftypefn Replacement char* strerror (int @var{errnoval})
+@deftypefn Supplemental char* strerror (int @var{errnoval})
 
 Maps an @code{errno} number to an error message string, the contents
 of which are implementation defined.  On systems which have the
@@ -608,7 +608,7 @@ strings will be the same as the ones used by @code{perror}.
 
 If the supplied error number is within the valid range of indices for
 the @code{sys_errlist}, but no message is available for the particular
-error number, then returns the string @samp{"Error @var{num}"}, where
+error number, then returns the string @samp{Error @var{num}}, where
 @var{num} is the error number.
 
 If the supplied error number is not a valid index into
@@ -667,7 +667,7 @@ strerror (errnoval)
 
 /*
 
-@deftypefn Replacement const char* strerrno (int @var{errnum})
+@deftypefn Replacement {const char*} strerrno (int @var{errnum})
 
 Given an error number returned from a system call (typically returned
 in @code{errno}), returns a pointer to a string containing the
@@ -675,7 +675,7 @@ 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
-number, then returns the string @samp{"Error @var{num}"}, where @var{num}
+number, then returns the string @samp{Error @var{num}}, where @var{num}
 is the error number.
 
 If the supplied error number is not within the range of valid
@@ -727,7 +727,7 @@ strerrno (errnoval)
 
 /*
 
-@deftypefn Replacement int strtoerrno (const char *@var{name})
+@deftypefn Extension int strtoerrno (const char *@var{name})
 
 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.

libiberty/strsignal.c

@@ -350,28 +350,22 @@ init_signal_tables ()
 
 /*
 
-NAME
-
-	signo_max -- return the max signo value
-
-SYNOPSIS
+@deftypefn Extension int signo_max ()
 
-	int signo_max ();
+Returns the maximum signal value for which a corresponding symbolic
+name or message is available.  Note that in the case where we use the
+@code{sys_siglist} supplied by the system, it is possible for there to
+be more symbolic names than messages, or vice versa.  In fact, the
+manual page for @code{psignal(3b)} explicitly warns that one should
+check the size of the table (@code{NSIG}) before indexing it, since
+new signal codes may be added to the system before they are added to
+the table.  Thus @code{NSIG} might be smaller than value implied by
+the largest signo value defined in @code{<signal.h>}.
 
-DESCRIPTION
-
-	Returns the maximum signo value for which a corresponding symbolic
-	name or message is available.  Note that in the case where
-	we use the sys_siglist supplied by the system, it is possible for
-	there to be more symbolic names than messages, or vice versa.
-	In fact, the manual page for psignal(3b) explicitly warns that one
-	should check the size of the table (NSIG) before indexing it,
-	since new signal codes may be added to the system before they are
-	added to the table.  Thus NSIG might be smaller than value
-	implied by the largest signo value defined in <signal.h>.
+We return the maximum value that can be used to obtain a meaningful
+symbolic name or message.
 
-	We return the maximum value that can be used to obtain a meaningful
-	symbolic name or message.
+@end deftypefn
 
 */
 
@@ -391,31 +385,25 @@ signo_max ()
 
 /*
 
-NAME
-
-	strsignal -- map a signal number to a signal message string
+@deftypefn Supplemental {const char *} strsignal (int @var{signo})
 
-SYNOPSIS
-
-	const char *strsignal (int signo)
-
-DESCRIPTION
+Maps an signal number to an signal message string, the contents of
+which are implementation defined.  On systems which have the external
+variable @code{sys_siglist}, these strings will be the same as the
+ones used by @code{psignal()}.
 
-	Maps an signal number to an signal message string, the contents of
-	which are implementation defined.  On systems which have the external
-	variable sys_siglist, these strings will be the same as the ones used
-	by psignal().
+If the supplied signal number is within the valid range of indices for
+the @code{sys_siglist}, but no message is available for the particular
+signal number, then returns the string @samp{Signal @var{num}}, where
+@var{num} is the signal number.
 
-	If the supplied signal number is within the valid range of indices
-	for the sys_siglist, but no message is available for the particular
-	signal number, then returns the string "Signal NUM", where NUM is the
-	signal number.
+If the supplied signal number is not a valid index into
+@code{sys_siglist}, returns @code{NULL}.
 
-	If the supplied signal number is not a valid index into sys_siglist,
-	returns NULL.
+The returned string is only guaranteed to be valid only until the next
+call to @code{strsignal}.
 
-	The returned string is only guaranteed to be valid only until the
-	next call to strsignal.
+@end deftypefn
 
 */
 
@@ -461,31 +449,23 @@ strsignal (signo)
 
 /*
 
-NAME
-
-	strsigno -- map an signal number to a symbolic name string
+@deftypefn Extension {const char*} strsigno (int @var{signo})
 
-SYNOPSIS
+Given an signal number, returns a pointer to a string containing the
+symbolic name of that signal number, as found in @code{<signal.h>}.
 
-	const char *strsigno (int signo)
+If the supplied signal number is within the valid range of indices for
+symbolic names, but no name is available for the particular signal
+number, then returns the string @samp{Signal @var{num}}, where
+@var{num} is the signal number.
 
-DESCRIPTION
+If the supplied signal number is not within the range of valid
+indices, then returns @code{NULL}.
 
-	Given an signal number, returns a pointer to a string containing
-	the symbolic name of that signal number, as found in <signal.h>.
+The contents of the location pointed to are only guaranteed to be
+valid until the next call to @code{strsigno}.
 
-	If the supplied signal number is within the valid range of indices
-	for symbolic names, but no name is available for the particular
-	signal number, then returns the string "Signal NUM", where NUM is
-	the signal number.
-
-	If the supplied signal number is not within the range of valid
-	indices, then returns NULL.
-
-BUGS
-
-	The contents of the location pointed to are only guaranteed to be
-	valid until the next call to strsigno.
+@end deftypefn
 
 */
 
@@ -524,18 +504,12 @@ strsigno (signo)
 
 /*
 
-NAME
-
-	strtosigno -- map a symbolic signal name to a numeric value
+@deftypefn Extension int strtosigno (const char *@var{name})
 
-SYNOPSIS
+Given the symbolic name of a signal, map it to a signal number.  If no
+translation is found, returns 0.
 
-	int strtosigno (char *name)
-
-DESCRIPTION
-
-	Given the symbolic name of a signal, map it to a signal number.
-	If no translation is found, returns 0.
+@end deftypefn
 
 */
 
@@ -570,19 +544,14 @@ strtosigno (name)
 
 /*
 
-NAME
+@deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message})
 
-	psignal -- print message about signal to stderr
+Print @var{message} to the standard error, followed by a colon,
+followed by the description of the signal specified by @var{signo},
+followed by a newline.
 
-SYNOPSIS
-
-	void psignal (unsigned signo, char *message);
-
-DESCRIPTION
+@end deftypefn
 
-	Print to the standard error the message, followed by a colon,
-	followed by the description of the signal specified by signo,
-	followed by a newline.
 */
 
 #ifndef HAVE_PSIGNAL

libiberty/strtol.c

@@ -31,6 +31,7 @@
 /*
 
 @deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
+@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base})
 
 The @code{strtol} function converts the string in @var{string} to a
 long integer value according to the given @var{base}, which must be
@@ -39,7 +40,8 @@ is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
 to indicate bases 8 and 16, respectively, else default to base 10.
 When the base is 16 (either explicitly or implicitly), a prefix of
 @code{0x} is allowed.  The handling of @var{endptr} is as that of
-@code{strtod} above.
+@code{strtod} above.  The @code{strtoul} function is the same, except
+that the converted value is unsigned.
 
 @end deftypefn
 

libiberty/vasprintf.c

@@ -43,6 +43,21 @@ extern PTR malloc ();
 int global_total_width;
 #endif
 
+/*
+
+@deftypefn Extension int vasprintf (char **@var{resptr}, char *@var{format}, va_list @var{args})
+
+Like @code{vsprintf}, but instead of passing a pointer to a buffer,
+you pass a pointer to a pointer.  This function will compute the size
+of the buffer needed, allocate memory with @code{malloc}, and store a
+pointer to the allocated memory in @code{*@var{resptr}}.  The value
+returned is the same as @code{vsprintf} would return.  If memory could
+not be allocated, zero is returned and @code{NULL} is stored in
+@code{*@var{resptr}}.
+
+@end deftypefn
+
+*/
 
 static int int_vasprintf PARAMS ((char **, const char *, va_list *));