diff --git a/libiberty/ChangeLog b/libiberty/ChangeLog index 1a373dec05..52eb093bcc 100644 --- a/libiberty/ChangeLog +++ b/libiberty/ChangeLog @@ -1,3 +1,11 @@ +2001-10-17 DJ Delorie + + * argv.c, asprintf.c, choose-temp.c, concat.c, cplus-dem.c, + ffs.c, fnmatch.txh, getruntime.c, make-temp-file.c, + mkstemps.c, pexecute.c, random.c, strsitnal.c, vasprintf.c: + Improve manual formatting. + * functions.texi: Regenerate. + 2001-10-15 DJ Delorie * Makefile.in (TEXIFILES): Add fnmatch.txh. diff --git a/libiberty/argv.c b/libiberty/argv.c index ede61cb541..4205579a57 100644 --- a/libiberty/argv.c +++ b/libiberty/argv.c @@ -66,7 +66,7 @@ extern char *strdup (); /* Duplicate a string */ 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 +Returns a pointer to the argument vector if successful. Returns @code{NULL} if there is insufficient memory to complete building the argument vector. @@ -150,7 +150,7 @@ 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 +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. diff --git a/libiberty/asprintf.c b/libiberty/asprintf.c index 7693ac0181..5de775616d 100644 --- a/libiberty/asprintf.c +++ b/libiberty/asprintf.c @@ -30,7 +30,7 @@ Boston, MA 02111-1307, USA. */ /* -@deftypefn Extension int asprintf (char **@var{resptr}, char *@var{format}, ...) +@deftypefn Extension int asprintf (char **@var{resptr}, const 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 diff --git a/libiberty/choose-temp.c b/libiberty/choose-temp.c index de6fbed4b7..5c2c6140db 100644 --- a/libiberty/choose-temp.c +++ b/libiberty/choose-temp.c @@ -39,7 +39,7 @@ extern char *choose_tmpdir PARAMS ((void)); /* -@deftypefn Extension char* choose_temp_base () +@deftypefn Extension char* choose_temp_base (void) 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 diff --git a/libiberty/concat.c b/libiberty/concat.c index a7e642880f..98b20e16a1 100644 --- a/libiberty/concat.c +++ b/libiberty/concat.c @@ -21,10 +21,10 @@ Boston, MA 02111-1307, USA. */ /* -@deftypefn Extension char* concat (char *@var{s1}, char *@var{s2}, ..., @code{NULL}) +@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL}) Concatenate zero or more of strings and return the result in freshly -xmalloc'd memory. Returns @code{NULL} if insufficient memory is +@code{xmalloc}ed 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. @@ -174,7 +174,7 @@ concat VPARAMS ((const char *first, ...)) /* -@deftypefn Extension char* reconcat (char *@var{optr}, char *@var{s1}, ..., @code{NULL}) +@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @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 diff --git a/libiberty/cplus-dem.c b/libiberty/cplus-dem.c index a464f45e15..e19340c5ad 100644 --- a/libiberty/cplus-dem.c +++ b/libiberty/cplus-dem.c @@ -877,7 +877,7 @@ cplus_demangle_name_to_style (name) /* char *cplus_demangle (const char *mangled, int options) If MANGLED is a mangled function name produced by GNU C++, then - a pointer to a malloced string giving a C++ representation + a pointer to a @code{malloc}ed string giving a C++ representation of the name will be returned; otherwise NULL will be returned. It is the caller's responsibility to free the string which is returned. diff --git a/libiberty/ffs.c b/libiberty/ffs.c index 4a92c828a8..de047e217e 100644 --- a/libiberty/ffs.c +++ b/libiberty/ffs.c @@ -2,7 +2,7 @@ @deftypefn Supplemental int ffs (int @var{valu}) -Find the first (least significant) bit set in @var{valu}. Bits are +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. diff --git a/libiberty/fnmatch.txh b/libiberty/fnmatch.txh index dfdac2406a..92e11bcb38 100644 --- a/libiberty/fnmatch.txh +++ b/libiberty/fnmatch.txh @@ -6,7 +6,7 @@ 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 +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 @@ -17,7 +17,7 @@ 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{}: +@code{}): @table @code diff --git a/libiberty/functions.texi b/libiberty/functions.texi index 6668ce35e4..af7760d89b 100644 --- a/libiberty/functions.texi +++ b/libiberty/functions.texi @@ -22,7 +22,7 @@ the possibility of a GCC built-in function. @end deftypefn @c asprintf.c:33 -@deftypefn Extension int asprintf (char **@var{resptr}, char *@var{format}, ...) +@deftypefn Extension int asprintf (char **@var{resptr}, const 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 @@ -97,7 +97,7 @@ 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 +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. @@ -124,7 +124,7 @@ Uses @code{malloc} to allocate storage for @var{nelem} objects of @end deftypefn @c choose-temp.c:42 -@deftypefn Extension char* choose_temp_base () +@deftypefn Extension char* choose_temp_base (void) 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 @@ -154,10 +154,10 @@ number of seconds used. @end deftypefn @c concat.c:24 -@deftypefn Extension char* concat (char *@var{s1}, char *@var{s2}, ..., @code{NULL}) +@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL}) Concatenate zero or more of strings and return the result in freshly -xmalloc'd memory. Returns @code{NULL} if insufficient memory is +@code{xmalloc}ed 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. @@ -168,7 +168,7 @@ pointer encountered. Pointers to empty strings are ignored. 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 +Returns a pointer to the argument vector if successful. Returns @code{NULL} if there is insufficient memory to complete building the argument vector. @@ -210,7 +210,7 @@ and inode numbers. @c ffs.c:3 @deftypefn Supplemental int ffs (int @var{valu}) -Find the first (least significant) bit set in @var{valu}. Bits are +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. @@ -225,7 +225,7 @@ 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 +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 @@ -236,7 +236,7 @@ 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{}: +@code{}): @table @code @@ -277,7 +277,7 @@ itself. @end deftypefn @c getruntime.c:78 -@deftypefn Replacement long get_run_time () +@deftypefn Replacement long get_run_time (void) 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 @@ -368,7 +368,7 @@ and a path ending in @code{/} returns the empty string after it. 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. +string is @code{malloc}ed, and the temporary file has been created. @end deftypefn @@ -427,12 +427,12 @@ Generate a unique temporary file name from @var{template}. @var{template} has the form: @example - /ccXXXXXX + @var{path}/ccXXXXXX@var{suffix} @end example -@var{suffix_len} tells us how long is (it can be zero -length). The last six characters of @var{template} before -must be @code{XXXXXX}; they are replaced with a string that makes the +@var{suffix_len} tells us how long @var{suffix} is (it can be zero +length). The last six characters of @var{template} before @var{suffix} +must be @samp{XXXXXX}; they are replaced with a string that makes the filename unique. Returns a file descriptor open on the file for reading and writing. @@ -446,17 +446,17 @@ 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{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 +(@code{@var{flags} & PEXECUTE_SEARCH}) is non-zero if @env{PATH} should be searched +(??? It's not clear that GCC passes this flag correctly). (@code{@var{flags} & +PEXECUTE_FIRST}) is nonzero for the first process in chain. +(@code{@var{flags} & 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). @@ -466,12 +466,12 @@ 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 +The result is the @code{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. +@var{errmsg_arg} is set to @code{NULL}), and @minus{}1 is returned. @code{errno} is available to the caller to use. @end deftypefn @@ -514,22 +514,22 @@ is just a mechanism to provide a consistent interface for the caller. @end deftypefn @c random.c:39 -@deftypefn Supplement {long int} random () +@deftypefn Supplement {long int} random (void) @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 +range 0 to @code{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 +run of the program). @code{initstate} and @code{setstate} allow fine-grained 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}) +@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @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 @@ -572,7 +572,7 @@ environment. This implementation is not safe for multithreaded code. @end deftypefn @c strsignal.c:353 -@deftypefn Extension int signo_max () +@deftypefn Extension int signo_max (void) Returns the maximum signal value for which a corresponding symbolic name or message is available. Note that in the case where we use the @@ -803,7 +803,7 @@ 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}) +@deftypefn Extension int vasprintf (char **@var{resptr}, const 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 diff --git a/libiberty/getruntime.c b/libiberty/getruntime.c index f610c94024..9301deb773 100644 --- a/libiberty/getruntime.c +++ b/libiberty/getruntime.c @@ -75,7 +75,7 @@ Boston, MA 02111-1307, USA. */ /* -@deftypefn Replacement long get_run_time () +@deftypefn Replacement long get_run_time (void) 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 diff --git a/libiberty/make-temp-file.c b/libiberty/make-temp-file.c index db4bd9e5e4..883350479f 100644 --- a/libiberty/make-temp-file.c +++ b/libiberty/make-temp-file.c @@ -139,7 +139,7 @@ choose_tmpdir () 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. +string is @code{malloc}ed, and the temporary file has been created. @end deftypefn diff --git a/libiberty/mkstemps.c b/libiberty/mkstemps.c index 56b0baea77..8fe5784f18 100644 --- a/libiberty/mkstemps.c +++ b/libiberty/mkstemps.c @@ -57,12 +57,12 @@ Generate a unique temporary file name from @var{template}. @var{template} has the form: @example - /ccXXXXXX + @var{path}/ccXXXXXX@var{suffix} @end example -@var{suffix_len} tells us how long is (it can be zero -length). The last six characters of @var{template} before -must be @code{XXXXXX}; they are replaced with a string that makes the +@var{suffix_len} tells us how long @var{suffix} is (it can be zero +length). The last six characters of @var{template} before @var{suffix} +must be @samp{XXXXXX}; they are replaced with a string that makes the filename unique. Returns a file descriptor open on the file for reading and writing. diff --git a/libiberty/pexecute.c b/libiberty/pexecute.c index 4a3fbeda8b..347c4db109 100644 --- a/libiberty/pexecute.c +++ b/libiberty/pexecute.c @@ -71,17 +71,17 @@ 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{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 +(@code{@var{flags} & PEXECUTE_SEARCH}) is non-zero if @env{PATH} should be searched +(??? It's not clear that GCC passes this flag correctly). (@code{@var{flags} & +PEXECUTE_FIRST}) is nonzero for the first process in chain. +(@code{@var{flags} & 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). @@ -91,12 +91,12 @@ 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 +The result is the @code{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. +@var{errmsg_arg} is set to @code{NULL}), and @minus{}1 is returned. @code{errno} is available to the caller to use. @end deftypefn diff --git a/libiberty/random.c b/libiberty/random.c index 7c46bac644..48035f0821 100644 --- a/libiberty/random.c +++ b/libiberty/random.c @@ -36,16 +36,16 @@ /* -@deftypefn Supplement {long int} random () +@deftypefn Supplement {long int} random (void) @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 +range 0 to @code{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 +run of the program). @code{initstate} and @code{setstate} allow fine-grained control over the state of the random number generator. @end deftypefn diff --git a/libiberty/strsignal.c b/libiberty/strsignal.c index 521a2a83a6..86c8aca5b4 100644 --- a/libiberty/strsignal.c +++ b/libiberty/strsignal.c @@ -350,7 +350,7 @@ init_signal_tables () /* -@deftypefn Extension int signo_max () +@deftypefn Extension int signo_max (void) Returns the maximum signal value for which a corresponding symbolic name or message is available. Note that in the case where we use the diff --git a/libiberty/vasprintf.c b/libiberty/vasprintf.c index d69dc323b5..d438225fc1 100644 --- a/libiberty/vasprintf.c +++ b/libiberty/vasprintf.c @@ -45,7 +45,7 @@ int global_total_width; /* -@deftypefn Extension int vasprintf (char **@var{resptr}, char *@var{format}, va_list @var{args}) +@deftypefn Extension int vasprintf (char **@var{resptr}, const 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