aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--libiberty/ChangeLog13
-rw-r--r--libiberty/Makefile.in8
-rw-r--r--libiberty/alloca.c2
-rw-r--r--libiberty/argv.c108
-rw-r--r--libiberty/asprintf.c16
-rw-r--r--libiberty/choose-temp.c20
-rw-r--r--libiberty/concat.c46
-rw-r--r--libiberty/fdmatch.c32
-rw-r--r--libiberty/ffs.c12
-rw-r--r--libiberty/fnmatch.txh48
-rw-r--r--libiberty/functions.texi435
-rw-r--r--libiberty/getruntime.c12
-rw-r--r--libiberty/insque.c31
-rw-r--r--libiberty/lbasename.c33
-rw-r--r--libiberty/maint-tool105
-rw-r--r--libiberty/make-temp-file.c25
-rw-r--r--libiberty/mkstemps.c21
-rw-r--r--libiberty/pexecute.c81
-rw-r--r--libiberty/random.c18
-rw-r--r--libiberty/spaces.c18
-rw-r--r--libiberty/strerror.c12
-rw-r--r--libiberty/strsignal.c127
-rw-r--r--libiberty/strtol.c4
-rw-r--r--libiberty/vasprintf.c15
24 files changed, 944 insertions, 298 deletions
diff --git a/libiberty/ChangeLog b/libiberty/ChangeLog
index 90dcb1f..1a373de 100644
--- a/libiberty/ChangeLog
+++ b/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".
diff --git a/libiberty/Makefile.in b/libiberty/Makefile.in
index 393fa9f..f549902 100644
--- a/libiberty/Makefile.in
+++ b/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
diff --git a/libiberty/alloca.c b/libiberty/alloca.c
index e98a053..918235d 100644
--- a/libiberty/alloca.c
+++ b/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;
diff --git a/libiberty/argv.c b/libiberty/argv.c
index 5d848ad..ede61cb 100644
--- a/libiberty/argv.c
+++ b/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)
diff --git a/libiberty/asprintf.c b/libiberty/asprintf.c
index e09af23..7693ac0 100644
--- a/libiberty/asprintf.c
+++ b/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, ...))
{
diff --git a/libiberty/choose-temp.c b/libiberty/choose-temp.c
index c6df304..de6fbed 100644
--- a/libiberty/choose-temp.c
+++ b/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 ()
diff --git a/libiberty/concat.c b/libiberty/concat.c
index fbbf2ee..a7e6428 100644
--- a/libiberty/concat.c
+++ b/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, ...))
{
diff --git a/libiberty/fdmatch.c b/libiberty/fdmatch.c
index 7af039f..979c214 100644
--- a/libiberty/fdmatch.c
+++ b/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
diff --git a/libiberty/ffs.c b/libiberty/ffs.c
index 8ffb03e..4a92c82 100644
--- a/libiberty/ffs.c
+++ b/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
*/
diff --git a/libiberty/fnmatch.txh b/libiberty/fnmatch.txh
new file mode 100644
index 0000000..dfdac24
--- /dev/null
+++ b/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
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)
diff --git a/libiberty/getruntime.c b/libiberty/getruntime.c
index 4abfa83..f610c94 100644
--- a/libiberty/getruntime.c
+++ b/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 ()
{
diff --git a/libiberty/insque.c b/libiberty/insque.c
index 775019f..c0c1180 100644
--- a/libiberty/insque.c
+++ b/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.
*/
diff --git a/libiberty/lbasename.c b/libiberty/lbasename.c
index b373162..cea0253 100644
--- a/libiberty/lbasename.c
+++ b/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"
diff --git a/libiberty/maint-tool b/libiberty/maint-tool
index 9708800..75b0c50 100644
--- a/libiberty/maint-tool
+++ b/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;
+ }
+}
diff --git a/libiberty/make-temp-file.c b/libiberty/make-temp-file.c
index f3e1d10..db4bd9e 100644
--- a/libiberty/make-temp-file.c
+++ b/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)
diff --git a/libiberty/mkstemps.c b/libiberty/mkstemps.c
index 4b89162..56b0bae 100644
--- a/libiberty/mkstemps.c
+++ b/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;
diff --git a/libiberty/pexecute.c b/libiberty/pexecute.c
index 32943af..4a3fbed 100644
--- a/libiberty/pexecute.c
+++ b/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;
{
diff --git a/libiberty/random.c b/libiberty/random.c
index ef00da0..7c46bac 100644
--- a/libiberty/random.c
+++ b/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
diff --git a/libiberty/spaces.c b/libiberty/spaces.c
index ea92571..bfead7ed 100644
--- a/libiberty/spaces.c
+++ b/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
*/
diff --git a/libiberty/strerror.c b/libiberty/strerror.c
index 37fbf4d..18050c2 100644
--- a/libiberty/strerror.c
+++ b/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.
diff --git a/libiberty/strsignal.c b/libiberty/strsignal.c
index 85639f9..521a2a8 100644
--- a/libiberty/strsignal.c
+++ b/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
diff --git a/libiberty/strtol.c b/libiberty/strtol.c
index fa84a2e..d9f54cc 100644
--- a/libiberty/strtol.c
+++ b/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
diff --git a/libiberty/vasprintf.c b/libiberty/vasprintf.c
index 32faa84..d69dc32 100644
--- a/libiberty/vasprintf.c
+++ b/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 *));