diff options
| -rw-r--r-- | libiberty/ChangeLog | 13 | ||||
| -rw-r--r-- | libiberty/Makefile.in | 8 | ||||
| -rw-r--r-- | libiberty/alloca.c | 2 | ||||
| -rw-r--r-- | libiberty/argv.c | 108 | ||||
| -rw-r--r-- | libiberty/asprintf.c | 16 | ||||
| -rw-r--r-- | libiberty/choose-temp.c | 20 | ||||
| -rw-r--r-- | libiberty/concat.c | 46 | ||||
| -rw-r--r-- | libiberty/fdmatch.c | 32 | ||||
| -rw-r--r-- | libiberty/ffs.c | 12 | ||||
| -rw-r--r-- | libiberty/fnmatch.txh | 48 | ||||
| -rw-r--r-- | libiberty/functions.texi | 435 | ||||
| -rw-r--r-- | libiberty/getruntime.c | 12 | ||||
| -rw-r--r-- | libiberty/insque.c | 31 | ||||
| -rw-r--r-- | libiberty/lbasename.c | 33 | ||||
| -rw-r--r-- | libiberty/maint-tool | 105 | ||||
| -rw-r--r-- | libiberty/make-temp-file.c | 25 | ||||
| -rw-r--r-- | libiberty/mkstemps.c | 21 | ||||
| -rw-r--r-- | libiberty/pexecute.c | 81 | ||||
| -rw-r--r-- | libiberty/random.c | 18 | ||||
| -rw-r--r-- | libiberty/spaces.c | 18 | ||||
| -rw-r--r-- | libiberty/strerror.c | 12 | ||||
| -rw-r--r-- | libiberty/strsignal.c | 127 | ||||
| -rw-r--r-- | libiberty/strtol.c | 4 | ||||
| -rw-r--r-- | libiberty/vasprintf.c | 15 |
24 files changed, 944 insertions, 298 deletions
diff --git a/libiberty/ChangeLog b/libiberty/ChangeLog index 90dcb1f2601..1a373dec05a 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 393fa9fe3af..f5499029696 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 e98a053fbee..918235df465 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 5d848ad2a98..ede61cb541b 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 e09af239ae7..7693ac01818 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 c6df304b552..de6fbed4b7d 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 fbbf2ee41a9..a7e642880fa 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 7af039f5a2b..979c214d5d4 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 8ffb03e7c5e..4a92c828a81 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 00000000000..dfdac2406aa --- /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 59df233947b..6668ce35e48 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 4abfa83bf33..f610c940248 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 775019f8fff..c0c1180d421 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 b37316259d2..cea0253887b 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 97088009f8d..75b0c508cd9 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 f3e1d10e9a7..db4bd9e5e4a 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 4b89162751d..56b0baea77e 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 32943af59ef..4a3fbeda8be 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 ef00da0a5ae..7c46bac6448 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 ea925712e3f..bfead7ed7a4 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 37fbf4d0a8b..18050c2c15f 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 85639f98814..521a2a83a67 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 fa84a2e8d2d..d9f54cc8f7a 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 32faa84a4a2..d69dc323b5c 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 *)); |