Makefile.in (TEXIFILES): Add fnmatch.txh.

* 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.

From-SVN: r46274

1 files changed, 428 insertions, 7 deletions

diff --git a/libiberty/functions.texi b/libiberty/functions.texi
index 59df233..6668ce3 100644
--- a/libiberty/functions.texi
+++ b/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)