+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".
$(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
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
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;
/*
-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
*/
/*
-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
*/
/*
-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)
#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, ...))
{
#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 ()
/*
-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
deal with low memory situations itself, it should supply an xmalloc
that just directly invokes malloc and blindly returns whatever
malloc returns.
+
*/
return dst;
}
+/* @undocumented concat_length */
+
unsigned long
concat_length VPARAMS ((const char *first, ...))
{
return length;
}
+/* @undocumented concat_copy */
+
char *
concat_copy VPARAMS ((char *dst, const char *first, ...))
{
char *libiberty_concat_ptr;
+/* @undocumented concat_copy2 */
+
char *
concat_copy2 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, ...))
{
/*
-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
/* 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
*/
--- /dev/null
+@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
@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})())
@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})
@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)
@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
@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})
@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})
@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})
@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})
@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})
@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})
@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
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
@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
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
@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})
@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.
@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
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
@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)
#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 ()
{
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.
*/
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"
}
&missing() if $mode eq "missing";
+&undoc() if $mode eq "undoc";
exit 0;
+format STDOUT =
+^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~
+$out
+ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
+$out
+.
+
######################################################################
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;
+ }
+}
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 ()
{
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)
#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;
/* 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__
/* 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;
{
* 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
/*
-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
*/
/*
-@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
/*
-@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
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
/*
-@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
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
/*
-@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.
/*
-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
*/
/*
-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
*/
/*
-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
*/
/*
-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
*/
/*
-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
/*
@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
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
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 *));
projects / binutils-gdb.git / commitdiff