CbC/CbC_gcc: libiberty/functions.texi comparison

comparison libiberty/functions.texi @ 0:a06113de4d67

first commit

author	kent <kent@cr.ie.u-ryukyu.ac.jp>
date	Fri, 17 Jul 2009 14:47:48 +0900
parents
children	77e2b8dfacca

comparison

equal deleted inserted replaced

--1:000000000000
+:a06113de4d67
+@c Automatically generated from *.c and others (the comments before
+@c each entry tell you which file and where in that file).  DO NOT EDIT!
+@c Edit the *.c files, configure with --enable-maintainer-mode,
+@c and let gather-docs build you a new copy.
+@c safe-ctype.c:25
+@defvr Extension HOST_CHARSET
+This macro indicates the basic character set and encoding used by the
+host: more precisely, the encoding used for character constants in
+preprocessor @samp{#if} statements (the C "execution character set").
+It is defined by @file{safe-ctype.h}, and will be an integer constant
+with one of the following values:
+@ftable @code
+@item HOST_CHARSET_UNKNOWN
+The host character set is unknown - that is, not one of the next two
+possibilities.
+@item HOST_CHARSET_ASCII
+The host character set is ASCII.
+@item HOST_CHARSET_EBCDIC
+The host character set is some variant of EBCDIC.  (Only one of the
+nineteen EBCDIC varying characters is tested; exercise caution.)
+@end ftable
+@end defvr
+@c alloca.c:26
+@deftypefn Replacement void* alloca (size_t @var{size})
+This function allocates memory which will be automatically reclaimed
+after the procedure exits.  The @libib{} implementation does not free
+the memory immediately but will do so eventually during subsequent
+calls to this function.  Memory is allocated using @code{xmalloc} under
+normal circumstances.
+The header file @file{alloca-conf.h} can be used in conjunction with the
+GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make
+available this function.  The @code{AC_FUNC_ALLOCA} test requires that
+client code use a block of preprocessor code to be safe (see the Autoconf
+manual for more); this header incorporates that logic and more, including
+the possibility of a GCC built-in function.
+@end deftypefn
+@c asprintf.c:32
+@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
+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, minus one is returned and @code{NULL} is stored in
+@code{*@var{resptr}}.
+@end deftypefn
+@c atexit.c:6
+@deftypefn Supplemental int atexit (void (*@var{f})())
+Causes function @var{f} to be called at exit.  Returns 0.
+@end deftypefn
+@c basename.c:6
+@deftypefn Supplemental char* basename (const char *@var{name})
+Returns a pointer to the last component of pathname @var{name}.
+Behavior is undefined if the pathname ends in a directory separator.
+@end deftypefn
+@c bcmp.c:6
+@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count})
+Compares the first @var{count} bytes of two areas of memory.  Returns
+zero if they are the same, nonzero otherwise.  Returns zero if
+@var{count} is zero.  A nonzero result only indicates a difference,
+it does not indicate any sorting order (say, by having a positive
+result mean @var{x} sorts before @var{y}).
+@end deftypefn
+@c bcopy.c:3
+@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length})
+Copies @var{length} bytes from memory region @var{in} to region
+@var{out}.  The use of @code{bcopy} is deprecated in new programs.
+@end deftypefn
+@c bsearch.c:33
+@deftypefn Supplemental void* bsearch (const void *@var{key}, const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, int (*@var{compar})(const void *, const void *))
+Performs a search over an array of @var{nmemb} elements pointed to by
+@var{base} for a member that matches the object pointed to by @var{key}.
+The size of each member is specified by @var{size}.  The array contents
+should be sorted in ascending order according to the @var{compar}
+comparison function.  This routine should take two arguments pointing to
+the @var{key} and to an array member, in that order, and should return an
+integer less than, equal to, or greater than zero if the @var{key} object
+is respectively less than, matching, or greater than the array member.
+@end deftypefn
+@c argv.c:124
+@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})
+Zeros @var{count} bytes starting at @var{mem}.  Use of this function
+is deprecated in favor of @code{memset}.
+@end deftypefn
+@c calloc.c:6
+@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize})
+Uses @code{malloc} to allocate storage for @var{nelem} objects of
+@var{elsize} bytes each, then zeros the memory.
+@end deftypefn
+@c choose-temp.c:42
+@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
+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 compatibility only.  Its use is
+not recommended.
+@end deftypefn
+@c make-temp-file.c:87
+@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)
+Returns an approximation of the CPU time used by the process as a
+@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the
+number of seconds used.
+@end deftypefn
+@c concat.c:24
+@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
+@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.
+@end deftypefn
+@c argv.c:52
+@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:567
+@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
+use the @code{sys_errlist} 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{perror(3C)} explicitly warns that one
+should check the size of the table (@code{sys_nerr}) before indexing
+it, since new error codes may be added to the system before they are
+added to the table.  Thus @code{sys_nerr} might be smaller than value
+implied by the largest @code{errno} value defined in @code{<errno.h>}.
+We return the maximum value that can be used to obtain a meaningful
+symbolic name or message.
+@end deftypefn
+@c argv.c:348
+@deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp})
+The @var{argcp} and @code{argvp} arguments are pointers to the usual
+@code{argc} and @code{argv} arguments to @code{main}.  This function
+looks for arguments that begin with the character @samp{@@}.  Any such
+arguments are interpreted as ``response files''.  The contents of the
+response file are interpreted as additional command line options.  In
+particular, the file is separated into whitespace-separated strings;
+each such string is taken as a command-line option.  The new options
+are inserted in place of the option naming the response file, and
+@code{*argcp} and @code{*argvp} will be updated.  If the value of
+@code{*argvp} is modified by this function, then the new value has
+been dynamically allocated and can be deallocated by the caller with
+@code{freeargv}.  However, most callers will simply call
+@code{expandargv} near the beginning of @code{main} and allow the
+operating system to free the memory when the program exits.
+@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 fopen_unlocked.c:48
+@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, const char * @var{mode})
+Opens and returns a @code{FILE} pointer via @code{fdopen}.  If the
+operating system supports it, ensure that the stream is setup to avoid
+any multi-threaded locking.  Otherwise return the @code{FILE} pointer
+unchanged.
+@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 filename_cmp.c:32
+@deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2})
+Return zero if the two file names @var{s1} and @var{s2} are equivalent.
+If not equivalent, the returned value is similar to what @code{strcmp}
+would return.  In other words, it returns a negative value if @var{s1}
+is less than @var{s2}, or a positive value if @var{s2} is greater than
+@var{s2}.
+This function does not normalize file names.  As a result, this function
+will treat filenames that are spelled differently as different even in
+the case when the two filenames point to the same underlying file.
+However, it does handle the fact that on DOS-like file systems, forward
+and backward slashes are equal.
+@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 fopen_unlocked.c:39
+@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, const char * @var{mode})
+Opens and returns a @code{FILE} pointer via @code{fopen}.  If the
+operating system supports it, ensure that the stream is setup to avoid
+any multi-threaded locking.  Otherwise return the @code{FILE} pointer
+unchanged.
+@end deftypefn
+@c argv.c:97
+@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 fopen_unlocked.c:57
+@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, const char * @var{mode}, FILE * @var{stream})
+Opens and returns a @code{FILE} pointer via @code{freopen}.  If the
+operating system supports it, ensure that the stream is setup to avoid
+any multi-threaded locking.  Otherwise return the @code{FILE} pointer
+unchanged.
+@end deftypefn
+@c getruntime.c:82
+@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
+process started.
+@end deftypefn
+@c getcwd.c:6
+@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len})
+Copy the absolute pathname for the current working directory into
+@var{pathname}, which is assumed to point to a buffer of at least
+@var{len} bytes, and return a pointer to the buffer.  If the current
+directory's path doesn't fit in @var{len} characters, the result is
+@code{NULL} and @code{errno} is set.  If @var{pathname} is a null pointer,
+@code{getcwd} will obtain @var{len} bytes of space using
+@code{malloc}.
+@end deftypefn
+@c getpagesize.c:5
+@deftypefn Supplemental int getpagesize (void)
+Returns the number of bytes in a page of memory.  This is the
+granularity of many of the system memory management routines.  No
+guarantee is made as to whether or not it is the same as the basic
+memory management hardware page size.
+@end deftypefn
+@c getpwd.c:5
+@deftypefn Supplemental char* getpwd (void)
+Returns the current working directory.  This implementation caches the
+result on the assumption that the process will not call @code{chdir}
+between calls to @code{getpwd}.
+@end deftypefn
+@c gettimeofday.c:12
+@deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz})
+Writes the current time to @var{tp}.  This implementation requires
+that @var{tz} be NULL.  Returns 0 on success, -1 on failure.
+@end deftypefn
+@c hex.c:33
+@deftypefn Extension void hex_init (void)
+Initializes the array mapping the current character set to
+corresponding hex values.  This function must be called before any
+call to @code{hex_p} or @code{hex_value}.  If you fail to call it, a
+default ASCII-based table will normally be used on ASCII systems.
+@end deftypefn
+@c hex.c:42
+@deftypefn Extension int hex_p (int @var{c})
+Evaluates to non-zero if the given character is a valid hex character,
+or zero if it is not.  Note that the value you pass will be cast to
+@code{unsigned char} within the macro.
+@end deftypefn
+@c hex.c:50
+@deftypefn Extension {unsigned int} hex_value (int @var{c})
+Returns the numeric equivalent of the given character when interpreted
+as a hexadecimal digit.  The result is undefined if you pass an
+invalid hex digit.  Note that the value you pass will be cast to
+@code{unsigned char} within the macro.
+The @code{hex_value} macro returns @code{unsigned int}, rather than
+signed @code{int}, to make it easier to use in parsing addresses from
+hex dump files: a signed @code{int} would be sign-extended when
+converted to a wider unsigned type --- like @code{bfd_vma}, on some
+systems.
+@end deftypefn
+@c index.c:5
+@deftypefn Supplemental char* index (char *@var{s}, int @var{c})
+Returns a pointer to the first occurrence of the character @var{c} in
+the string @var{s}, or @code{NULL} if not found.  The use of @code{index} is
+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 safe-ctype.c:46
+@deffn  Extension ISALPHA  (@var{c})
+@deffnx Extension ISALNUM  (@var{c})
+@deffnx Extension ISBLANK  (@var{c})
+@deffnx Extension ISCNTRL  (@var{c})
+@deffnx Extension ISDIGIT  (@var{c})
+@deffnx Extension ISGRAPH  (@var{c})
+@deffnx Extension ISLOWER  (@var{c})
+@deffnx Extension ISPRINT  (@var{c})
+@deffnx Extension ISPUNCT  (@var{c})
+@deffnx Extension ISSPACE  (@var{c})
+@deffnx Extension ISUPPER  (@var{c})
+@deffnx Extension ISXDIGIT (@var{c})
+These twelve macros are defined by @file{safe-ctype.h}.  Each has the
+same meaning as the corresponding macro (with name in lowercase)
+defined by the standard header @file{ctype.h}.  For example,
+@code{ISALPHA} returns true for alphabetic characters and false for
+others.  However, there are two differences between these macros and
+those provided by @file{ctype.h}:
+@itemize @bullet
+@item These macros are guaranteed to have well-defined behavior for all
+values representable by @code{signed char} and @code{unsigned char}, and
+for @code{EOF}.
+@item These macros ignore the current locale; they are true for these
+fixed sets of characters:
+@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada}
+@item @code{ALPHA}  @tab @kbd{A-Za-z}
+@item @code{ALNUM}  @tab @kbd{A-Za-z0-9}
+@item @code{BLANK}  @tab @kbd{space tab}
+@item @code{CNTRL}  @tab @code{!PRINT}
+@item @code{DIGIT}  @tab @kbd{0-9}
+@item @code{GRAPH}  @tab @code{ALNUM || PUNCT}
+@item @code{LOWER}  @tab @kbd{a-z}
+@item @code{PRINT}  @tab @code{GRAPH ||} @kbd{space}
+@item @code{PUNCT}  @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?}
+@item @code{SPACE}  @tab @kbd{space tab \n \r \f \v}
+@item @code{UPPER}  @tab @kbd{A-Z}
+@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f}
+@end multitable
+Note that, if the host character set is ASCII or a superset thereof,
+all these macros will return false for all values of @code{char} outside
+the range of 7-bit ASCII.  In particular, both ISPRINT and ISCNTRL return
+false for characters with numeric values from 128 to 255.
+@end itemize
+@end deffn
+@c safe-ctype.c:95
+@deffn  Extension ISIDNUM         (@var{c})
+@deffnx Extension ISIDST          (@var{c})
+@deffnx Extension IS_VSPACE       (@var{c})
+@deffnx Extension IS_NVSPACE      (@var{c})
+@deffnx Extension IS_SPACE_OR_NUL (@var{c})
+@deffnx Extension IS_ISOBASIC     (@var{c})
+These six macros are defined by @file{safe-ctype.h} and provide
+additional character classes which are useful when doing lexical
+analysis of C or similar languages.  They are true for the following
+sets of characters:
+@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada}
+@item @code{IDNUM}        @tab @kbd{A-Za-z0-9_}
+@item @code{IDST}         @tab @kbd{A-Za-z_}
+@item @code{VSPACE}       @tab @kbd{\r \n}
+@item @code{NVSPACE}      @tab @kbd{space tab \f \v \0}
+@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE}
+@item @code{ISOBASIC}     @tab @code{VSPACE || NVSPACE || PRINT}
+@end multitable
+@end deffn
+@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 lrealpath.c:25
+@deftypefn Replacement {const char*} lrealpath (const char *@var{name})
+Given a pointer to a string containing a pathname, returns a canonical
+version of the filename.  Symlinks will be resolved, and ``.'' and ``..''
+components will be simplified.  The returned value will be allocated using
+@code{malloc}, or @code{NULL} will be returned on a memory allocation error.
+@end deftypefn
+@c make-relative-prefix.c:24
+@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, const char *@var{bin_prefix}, const char *@var{prefix})
+Given three paths @var{progname}, @var{bin_prefix}, @var{prefix},
+return the path that is in the same position relative to
+@var{progname}'s directory as @var{prefix} is relative to
+@var{bin_prefix}.  That is, a string starting with the directory
+portion of @var{progname}, followed by a relative pathname of the
+difference between @var{bin_prefix} and @var{prefix}.
+If @var{progname} does not contain any directory separators,
+@code{make_relative_prefix} will search @env{PATH} to find a program
+named @var{progname}.  Also, if @var{progname} is a symbolic link,
+the symbolic link will be resolved.
+For example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta},
+@var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is
+@code{/red/green/blue/gcc}, then this function will return
+@code{/red/green/blue/../../omega/}.
+The return value is normally allocated via @code{malloc}.  If no
+relative prefix can be found, return @code{NULL}.
+@end deftypefn
+@c make-temp-file.c:137
+@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 @code{malloc}ed, 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})
+This function searches memory starting at @code{*@var{s}} for the
+character @var{c}.  The search only ends with the first occurrence of
+@var{c}, or after @var{length} characters; in particular, a null
+character does not terminate the search.  If the character @var{c} is
+found within @var{length} characters of @code{*@var{s}}, a pointer
+to the character is returned.  If @var{c} is not found, then @code{NULL} is
+returned.
+@end deftypefn
+@c memcmp.c:6
+@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count})
+Compares the first @var{count} bytes of two areas of memory.  Returns
+zero if they are the same, a value less than zero if @var{x} is
+lexically less than @var{y}, or a value greater than zero if @var{x}
+is lexically greater than @var{y}.  Note that lexical order is determined
+as if comparing unsigned char arrays.
+@end deftypefn
+@c memcpy.c:6
+@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
+Copies @var{length} bytes from memory region @var{in} to region
+@var{out}.  Returns a pointer to @var{out}.
+@end deftypefn
+@c memmove.c:6
+@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count})
+Copies @var{count} bytes from memory area @var{from} to memory area
+@var{to}, returning a pointer to @var{to}.
+@end deftypefn
+@c mempcpy.c:23
+@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
+Copies @var{length} bytes from memory region @var{in} to region
+@var{out}.  Returns a pointer to @var{out} + @var{length}.
+@end deftypefn
+@c memset.c:6
+@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count})
+Sets the first @var{count} bytes of @var{s} to the constant byte
+@var{c}, returning a pointer to @var{s}.
+@end deftypefn
+@c mkstemps.c:58
+@deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len})
+Generate a unique temporary file name from @var{pattern}.
+@var{pattern} has the form:
+@example
+@var{path}/ccXXXXXX@var{suffix}
+@end example
+@var{suffix_len} tells us how long @var{suffix} is (it can be zero
+length).  The last six characters of @var{pattern} 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.
+@end deftypefn
+@c pexecute.txh:266
+@deftypefn Extension void pex_free (struct pex_obj @var{obj})
+Clean up and free all data associated with @var{obj}.  If you have not
+yet called @code{pex_get_times} or @code{pex_get_status}, this will
+try to kill the subprocesses.
+@end deftypefn
+@c pexecute.txh:241
+@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector})
+Returns the exit status of all programs run using @var{obj}.
+@var{count} is the number of results expected.  The results will be
+placed into @var{vector}.  The results are in the order of the calls
+to @code{pex_run}.  Returns 0 on error, 1 on success.
+@end deftypefn
+@c pexecute.txh:250
+@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector})
+Returns the process execution times of all programs run using
+@var{obj}.  @var{count} is the number of results expected.  The
+results will be placed into @var{vector}.  The results are in the
+order of the calls to @code{pex_run}.  Returns 0 on error, 1 on
+success.
+@code{struct pex_time} has the following fields of the type
+@code{unsigned long}: @code{user_seconds},
+@code{user_microseconds}, @code{system_seconds},
+@code{system_microseconds}.  On systems which do not support reporting
+process times, all the fields will be set to @code{0}.
+@end deftypefn
+@c pexecute.txh:2
+@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase})
+Prepare to execute one or more programs, with standard output of each
+program fed to standard input of the next.  This is a system
+independent interface to execute a pipeline.
+@var{flags} is a bitwise combination of the following:
+@table @code
+@vindex PEX_RECORD_TIMES
+@item PEX_RECORD_TIMES
+Record subprocess times if possible.
+@vindex PEX_USE_PIPES
+@item PEX_USE_PIPES
+Use pipes for communication between processes, if possible.
+@vindex PEX_SAVE_TEMPS
+@item PEX_SAVE_TEMPS
+Don't delete temporary files used for communication between
+processes.
+@end table
+@var{pname} is the name of program to be executed, used in error
+messages.  @var{tempbase} is a base name to use for any required
+temporary files; it may be @code{NULL} to use a randomly chosen name.
+@end deftypefn
+@c pexecute.txh:155
+@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{in_name})
+Return a stream for a temporary file to pass to the first program in
+the pipeline as input.
+The name of the input file is chosen according to the same rules
+@code{pex_run} uses to choose output file names, based on
+@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}.
+Don't call @code{fclose} on the returned stream; the first call to
+@code{pex_run} closes it automatically.
+If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in
+binary mode; otherwise, open it in the default mode.  Including
+@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix.
+@end deftypefn
+@c pexecute.txh:172
+@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, int @var{binary})
+Return a stream @var{fp} for a pipe connected to the standard input of
+the first program in the pipeline; @var{fp} is opened for writing.
+You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call
+that returned @var{obj}.
+You must close @var{fp} using @code{fclose} yourself when you have
+finished writing data to the pipeline.
+The file descriptor underlying @var{fp} is marked not to be inherited
+by child processes.
+On systems that do not support pipes, this function returns
+@code{NULL}, and sets @code{errno} to @code{EINVAL}.  If you would
+like to write code that is portable to all systems the @code{pex}
+functions support, consider using @code{pex_input_file} instead.
+There are two opportunities for deadlock using
+@code{pex_input_pipe}:
+@itemize @bullet
+@item
+Most systems' pipes can buffer only a fixed amount of data; a process
+that writes to a full pipe blocks.  Thus, if you write to @file{fp}
+before starting the first process, you run the risk of blocking when
+there is no child process yet to read the data and allow you to
+continue.  @code{pex_input_pipe} makes no promises about the
+size of the pipe's buffer, so if you need to write any data at all
+before starting the first process in the pipeline, consider using
+@code{pex_input_file} instead.
+@item
+Using @code{pex_input_pipe} and @code{pex_read_output} together
+may also cause deadlock.  If the output pipe fills up, so that each
+program in the pipeline is waiting for the next to read more data, and
+you fill the input pipe by writing more data to @var{fp}, then there
+is no way to make progress: the only process that could read data from
+the output pipe is you, but you are blocked on the input pipe.
+@end itemize
+@end deftypefn
+@c pexecute.txh:274
+@deftypefn Extension {const char *} pex_one (int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, int *@var{status}, int *@var{err})
+An interface to permit the easy execution of a
+single program.  The return value and most of the parameters are as
+for a call to @code{pex_run}.  @var{flags} is restricted to a
+combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and
+@code{PEX_BINARY_OUTPUT}.  @var{outname} is interpreted as if
+@code{PEX_LAST} were set.  On a successful return, @code{*@var{status}} will
+be set to the exit status of the program.
+@end deftypefn
+@c pexecute.txh:228
+@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, int @var{binary})
+Returns a @code{FILE} pointer which may be used to read the standard
+error of the last program in the pipeline.  When this is used,
+@code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
+this is called, @code{pex_run} may no longer be called with the same
+@var{obj}.  @var{binary} should be non-zero if the file should be
+opened in binary mode.  Don't call @code{fclose} on the returned file;
+it will be closed by @code{pex_free}.
+@end deftypefn
+@c pexecute.txh:216
+@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary})
+Returns a @code{FILE} pointer which may be used to read the standard
+output of the last program in the pipeline.  When this is used,
+@code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
+this is called, @code{pex_run} may no longer be called with the same
+@var{obj}.  @var{binary} should be non-zero if the file should be
+opened in binary mode.  Don't call @code{fclose} on the returned file;
+it will be closed by @code{pex_free}.
+@end deftypefn
+@c pexecute.txh:33
+@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{outname}, const char *@var{errname}, int *@var{err})
+Execute one program in a pipeline.  On success this returns
+@code{NULL}.  On failure it returns an error message, a statically
+allocated string.
+@var{obj} is returned by a previous call to @code{pex_init}.
+@var{flags} is a bitwise combination of the following:
+@table @code
+@vindex PEX_LAST
+@item PEX_LAST
+This must be set on the last program in the pipeline.  In particular,
+it should be set when executing a single program.  The standard output
+of the program will be sent to @var{outname}, or, if @var{outname} is
+@code{NULL}, to the standard output of the calling program.  Do @emph{not}
+set this bit if you want to call @code{pex_read_output}
+(described below).  After a call to @code{pex_run} with this bit set,
+@var{pex_run} may no longer be called with the same @var{obj}.
+@vindex PEX_SEARCH
+@item PEX_SEARCH
+Search for the program using the user's executable search path.
+@vindex PEX_SUFFIX
+@item PEX_SUFFIX
+@var{outname} is a suffix.  See the description of @var{outname},
+below.
+@vindex PEX_STDERR_TO_STDOUT
+@item PEX_STDERR_TO_STDOUT
+Send the program's standard error to standard output, if possible.
+@vindex PEX_BINARY_INPUT
+@vindex PEX_BINARY_OUTPUT
+@vindex PEX_BINARY_ERROR
+@item PEX_BINARY_INPUT
+@itemx PEX_BINARY_OUTPUT
+@itemx PEX_BINARY_ERROR
+The standard input (output or error) of the program should be read (written) in
+binary mode rather than text mode.  These flags are ignored on systems
+which do not distinguish binary mode and text mode, such as Unix.  For
+proper behavior these flags should match appropriately---a call to
+@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
+call using @code{PEX_BINARY_INPUT}.
+@vindex PEX_STDERR_TO_PIPE
+@item PEX_STDERR_TO_PIPE
+Send the program's standard error to a pipe, if possible.  This flag
+cannot be specified together with @code{PEX_STDERR_TO_STDOUT}.  This
+flag can be specified only on the last program in pipeline.
+@end table
+@var{executable} is the program to execute.  @var{argv} is the set of
+arguments to pass to the program; normally @code{@var{argv}[0]} will
+be a copy of @var{executable}.
+@var{outname} is used to set the name of the file to use for standard
+output.  There are two cases in which no output file will be used:
+@enumerate
+@item
+if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES}
+was set in the call to @code{pex_init}, and the system supports pipes
+@item
+if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
+@code{NULL}
+@end enumerate
+@noindent
+Otherwise the code will use a file to hold standard
+output.  If @code{PEX_LAST} is not set, this file is considered to be
+a temporary file, and it will be removed when no longer needed, unless
+@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}.
+There are two cases to consider when setting the name of the file to
+hold standard output.
+@enumerate
+@item
+@code{PEX_SUFFIX} is set in @var{flags}.  In this case
+@var{outname} may not be @code{NULL}.  If the @var{tempbase} parameter
+to @code{pex_init} was not @code{NULL}, then the output file name is
+the concatenation of @var{tempbase} and @var{outname}.  If
+@var{tempbase} was @code{NULL}, then the output file name is a random
+file name ending in @var{outname}.
+@item
+@code{PEX_SUFFIX} was not set in @var{flags}.  In this
+case, if @var{outname} is not @code{NULL}, it is used as the output
+file name.  If @var{outname} is @code{NULL}, and @var{tempbase} was
+not NULL, the output file name is randomly chosen using
+@var{tempbase}.  Otherwise the output file name is chosen completely
+at random.
+@end enumerate
+@var{errname} is the file name to use for standard error output.  If
+it is @code{NULL}, standard error is the same as the caller's.
+Otherwise, standard error is written to the named file.
+On an error return, the code sets @code{*@var{err}} to an @code{errno}
+value, or to 0 if there is no relevant @code{errno}.
+@end deftypefn
+@c pexecute.txh:142
+@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, char * const *@var{env}, int @var{env_size}, const char *@var{outname}, const char *@var{errname}, int *@var{err})
+Execute one program in a pipeline, permitting the environment for the
+program to be specified.  Behaviour and parameters not listed below are
+as for @code{pex_run}.
+@var{env} is the environment for the child process, specified as an array of
+character pointers.  Each element of the array should point to a string of the
+form @code{VAR=VALUE}, with the exception of the last element that must be
+@code{NULL}.
+@end deftypefn
+@c pexecute.txh:286
+@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 @var{flags})
+This is the old interface to execute one or more programs.  It is
+still supported for compatibility purposes, but is no longer
+documented.
+@end deftypefn
+@c strsignal.c:541
+@deftypefn Supplemental void psignal (int @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})
+Uses @code{setenv} or @code{unsetenv} to put @var{string} into
+the environment or remove it.  If @var{string} is of the form
+@samp{name=value} the string is added; if no @samp{=} is present the
+name is unset/removed.
+@end deftypefn
+@c pexecute.txh:294
+@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
+Another part of the old execution interface.
+@end deftypefn
+@c random.c:39
+@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 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-grained
+control over the state of the random number generator.
+@end deftypefn
+@c concat.c:173
+@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
+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})
+Renames a file from @var{old} to @var{new}.  If @var{new} already
+exists, it is removed.
+@end deftypefn
+@c rindex.c:5
+@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
+Returns a pointer to the last occurrence of the character @var{c} in
+the string @var{s}, or @code{NULL} if not found.  The use of @code{rindex} is
+deprecated in new programs in favor of @code{strrchr}.
+@end deftypefn
+@c setenv.c:22
+@deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
+@deftypefnx Supplemental void unsetenv (const char *@var{name})
+@code{setenv} adds @var{name} to the environment with value
+@var{value}.  If the name was already present in the environment,
+the new value will be stored only if @var{overwrite} is nonzero.
+The companion @code{unsetenv} function removes @var{name} from the
+environment.  This implementation is not safe for multithreaded code.
+@end deftypefn
+@c strsignal.c:348
+@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
+@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})
+Sets the signal mask to the one provided in @var{set} and returns
+the old mask (which, for libiberty's implementation, will always
+be the value @code{1}).
+@end deftypefn
+@c snprintf.c:28
+@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...)
+This function is similar to sprintf, but it will print at most @var{n}
+characters.  On error the return value is -1, otherwise it returns the
+number of characters that would have been printed had @var{n} been
+sufficiently large, regardless of the actual value of @var{n}.  Note
+some pre-C99 system libraries do not implement this correctly so users
+cannot generally rely on the return value if the system version of
+this function is used.
+@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 stpcpy.c:23
+@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src})
+Copies the string @var{src} into @var{dst}.  Returns a pointer to
+@var{dst} + strlen(@var{src}).
+@end deftypefn
+@c stpncpy.c:23
+@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, size_t @var{len})
+Copies the string @var{src} into @var{dst}, copying exactly @var{len}
+and padding with zeros if necessary.  If @var{len} < strlen(@var{src})
+then return @var{dst} + @var{len}, otherwise returns @var{dst} +
+strlen(@var{src}).
+@end deftypefn
+@c strcasecmp.c:15
+@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
+A case-insensitive @code{strcmp}.
+@end deftypefn
+@c strchr.c:6
+@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
+Returns a pointer to the first occurrence of the character @var{c} in
+the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
+null character, the results are undefined.
+@end deftypefn
+@c strdup.c:3
+@deftypefn Supplemental char* strdup (const char *@var{s})
+Returns a pointer to a copy of @var{s} in memory obtained from
+@code{malloc}, or @code{NULL} if insufficient memory was available.
+@end deftypefn
+@c strerror.c:670
+@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
+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}
+is the error number.
+If the supplied error 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{strerrno}.
+@end deftypefn
+@c strerror.c:603
+@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
+external variables @code{sys_nerr} and @code{sys_errlist}, these
+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
+@var{num} is the error number.
+If the supplied error number is not a valid index into
+@code{sys_errlist}, returns @code{NULL}.
+The returned string is only guaranteed to be valid only until the
+next call to @code{strerror}.
+@end deftypefn
+@c strncasecmp.c:15
+@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
+A case-insensitive @code{strncmp}.
+@end deftypefn
+@c strncmp.c:6
+@deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
+Compares the first @var{n} bytes of two strings, returning a value as
+@code{strcmp}.
+@end deftypefn
+@c strndup.c:23
+@deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n})
+Returns a pointer to a copy of @var{s} with at most @var{n} characters
+in memory obtained from @code{malloc}, or @code{NULL} if insufficient
+memory was available.  The result is always NUL terminated.
+@end deftypefn
+@c strrchr.c:6
+@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
+Returns a pointer to the last occurrence of the character @var{c} in
+the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
+null character, the results are undefined.
+@end deftypefn
+@c strsignal.c:383
+@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:448
+@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})
+This function searches for the substring @var{sub} in the string
+@var{string}, not including the terminating null characters.  A pointer
+to the first occurrence of @var{sub} is returned, or @code{NULL} if the
+substring is absent.  If @var{sub} points to a string with zero
+length, the function returns @var{string}.
+@end deftypefn
+@c strtod.c:27
+@deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})
+This ISO C function converts the initial portion of @var{string} to a
+@code{double}.  If @var{endptr} is not @code{NULL}, a pointer to the
+character after the last character used in the conversion is stored in
+the location referenced by @var{endptr}.  If no conversion is
+performed, zero is returned and the value of @var{string} is stored in
+the location referenced by @var{endptr}.
+@end deftypefn
+@c strerror.c:729
+@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.
+@end deftypefn
+@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
+between 2 and 36 inclusive, or be the special value 0.  If @var{base}
+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.  The @code{strtoul} function is the same, except
+that the converted value is unsigned.
+@end deftypefn
+@c strsignal.c:502
+@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
+@c strverscmp.c:25
+@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2})
+The @code{strverscmp} function compares the string @var{s1} against
+@var{s2}, considering them as holding indices/version numbers.  Return
+value follows the same conventions as found in the @code{strverscmp}
+function.  In fact, if @var{s1} and @var{s2} contain no digits,
+@code{strverscmp} behaves like @code{strcmp}.
+Basically, we compare strings normally (character by character), until
+we find a digit in each string - then we enter a special comparison
+mode, where each sequence of digits is taken as a whole.  If we reach the
+end of these two parts without noticing a difference, we return to the
+standard comparison mode.  There are two types of numeric parts:
+"integral" and "fractional" (those  begin with a '0'). The types
+of the numeric parts affect the way we sort them:
+@itemize @bullet
+@item
+integral/integral: we compare values as you would expect.
+@item
+fractional/integral: the fractional part is less than the integral one.
+Again, no surprise.
+@item
+fractional/fractional: the things become a bit more complex.
+If the common prefix contains only leading zeroes, the longest part is less
+than the other one; else the comparison behaves normally.
+@end itemize
+@smallexample
+strverscmp ("no digit", "no digit")
+@result{} 0    // @r{same behavior as strcmp.}
+strverscmp ("item#99", "item#100")
+@result{} <0   // @r{same prefix, but 99 < 100.}
+strverscmp ("alpha1", "alpha001")
+@result{} >0   // @r{fractional part inferior to integral one.}
+strverscmp ("part1_f012", "part1_f01")
+@result{} >0   // @r{two fractional parts.}
+strverscmp ("foo.009", "foo.0")
+@result{} <0   // @r{idem, but with leading zeroes only.}
+@end smallexample
+This function is especially useful when dealing with filename sorting,
+because filenames frequently hold indices/version numbers.
+@end deftypefun
+@c tmpnam.c:3
+@deftypefn Supplemental char* tmpnam (char *@var{s})
+This function attempts to create a name for a temporary file, which
+will be a valid file name yet not exist when @code{tmpnam} checks for
+it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
+or be @code{NULL}.  Use of this function creates a security risk, and it must
+not be used in new projects.  Use @code{mkstemp} instead.
+@end deftypefn
+@c unlink-if-ordinary.c:27
+@deftypefn Supplemental int unlink_if_ordinary (const char*)
+Unlinks the named file, unless it is special (e.g. a device file).
+Returns 0 when the file was unlinked, a negative value (and errno set) when
+there was an error deleting the file, and a positive value if no attempt
+was made to unlink the file because it is special.
+@end deftypefn
+@c fopen_unlocked.c:31
+@deftypefn Extension void unlock_std_streams (void)
+If the OS supports it, ensure that the standard I/O streams,
+@code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any
+multi-threaded locking.  Otherwise do nothing.
+@end deftypefn
+@c fopen_unlocked.c:23
+@deftypefn Extension void unlock_stream (FILE * @var{stream})
+If the OS supports it, ensure that the supplied stream is setup to
+avoid any multi-threaded locking.  Otherwise leave the @code{FILE}
+pointer unchanged.  If the @var{stream} is @code{NULL} do nothing.
+@end deftypefn
+@c vasprintf.c:47
+@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
+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, minus one is returned and @code{NULL} is stored in
+@code{*@var{resptr}}.
+@end deftypefn
+@c vfork.c:6
+@deftypefn Supplemental int vfork (void)
+Emulates @code{vfork} by calling @code{fork} and returning its value.
+@end deftypefn
+@c vprintf.c:3
+@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
+@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
+@deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})
+These functions are the same as @code{printf}, @code{fprintf}, and
+@code{sprintf}, respectively, except that they are called with a
+@code{va_list} instead of a variable number of arguments.  Note that
+they do not call @code{va_end}; this is the application's
+responsibility.  In @libib{} they are implemented in terms of the
+nonstandard but common function @code{_doprnt}.
+@end deftypefn
+@c vsnprintf.c:28
+@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap})
+This function is similar to vsprintf, but it will print at most
+@var{n} characters.  On error the return value is -1, otherwise it
+returns the number of characters that would have been printed had
+@var{n} been sufficiently large, regardless of the actual value of
+@var{n}.  Note some pre-C99 system libraries do not implement this
+correctly so users cannot generally rely on the return value if the
+system version of this function is used.
+@end deftypefn
+@c waitpid.c:3
+@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
+This is a wrapper around the @code{wait} function.  Any ``special''
+values of @var{pid} depend on your implementation of @code{wait}, as
+does the return value.  The third argument is unused in @libib{}.
+@end deftypefn
+@c argv.c:293
+@deftypefn Extension int writeargv (const char **@var{argv}, FILE *@var{file})
+Write each member of ARGV, handling all necessary quoting, to the file
+named by FILE, separated by whitespace.  Return 0 on success, non-zero
+if an error occurred while writing to FILE.
+@end deftypefn
+@c xatexit.c:11
+@deftypefun int xatexit (void (*@var{fn}) (void))
+Behaves as the standard @code{atexit} function, but with no limit on
+the number of registered functions.  Returns 0 on success, or @minus{}1 on
+failure.  If you use @code{xatexit} to register functions, you must use
+@code{xexit} to terminate your program.
+@end deftypefun
+@c xmalloc.c:38
+@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize})
+Allocate memory without fail, and set it to zero.  This routine functions
+like @code{calloc}, but will behave the same as @code{xmalloc} if memory
+cannot be found.
+@end deftypefn
+@c xexit.c:22
+@deftypefn Replacement void xexit (int @var{code})
+Terminates the program.  If any functions have been registered with
+the @code{xatexit} replacement function, they will be called first.
+Termination is handled via the system's normal @code{exit} call.
+@end deftypefn
+@c xmalloc.c:22
+@deftypefn Replacement void* xmalloc (size_t)
+Allocate memory without fail.  If @code{malloc} fails, this will print
+a message to @code{stderr} (using the name set by
+@code{xmalloc_set_program_name},
+if any) and then call @code{xexit}.  Note that it is therefore safe for
+a program to contain @code{#define malloc xmalloc} in its source.
+@end deftypefn
+@c xmalloc.c:53
+@deftypefn Replacement void xmalloc_failed (size_t)
+This function is not meant to be called by client code, and is listed
+here for completeness only.  If any of the allocation routines fail, this
+function will be called to print an error message and terminate execution.
+@end deftypefn
+@c xmalloc.c:46
+@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
+You can use this to set the name of the program used by
+@code{xmalloc_failed} when printing a failure message.
+@end deftypefn
+@c xmemdup.c:7
+@deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})
+Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
+are allocated, then @var{copy_size} bytes from @var{input} are copied into
+it, and the new memory is returned.  If fewer bytes are copied than were
+allocated, the remaining memory is zeroed.
+@end deftypefn
+@c xmalloc.c:32
+@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size})
+Reallocate memory without fail.  This routine functions like @code{realloc},
+but will behave the same as @code{xmalloc} if memory cannot be found.
+@end deftypefn
+@c xstrdup.c:7
+@deftypefn Replacement char* xstrdup (const char *@var{s})
+Duplicates a character string without fail, using @code{xmalloc} to
+obtain memory.
+@end deftypefn
+@c xstrerror.c:7
+@deftypefn Replacement char* xstrerror (int @var{errnum})
+Behaves exactly like the standard @code{strerror} function, but
+will never return a @code{NULL} pointer.
+@end deftypefn
+@c xstrndup.c:23
+@deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n})
+Returns a pointer to a copy of @var{s} with at most @var{n} characters
+without fail, using @code{xmalloc} to obtain memory.  The result is
+always NUL terminated.
+@end deftypefn

Mercurial > hg > CbC > CbC_gcc

comparison libiberty/functions.texi @ 0:a06113de4d67