diff options
Diffstat (limited to 'gcc-4.7/libiberty/functions.texi')
| -rw-r--r-- | gcc-4.7/libiberty/functions.texi | 1940 |
1 files changed, 1940 insertions, 0 deletions
diff --git a/gcc-4.7/libiberty/functions.texi b/gcc-4.7/libiberty/functions.texi new file mode 100644 index 000000000..c9df186be --- /dev/null +++ b/gcc-4.7/libiberty/functions.texi @@ -0,0 +1,1940 @@ +@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 run 'make stamp-functions' and gather-docs will build a new copy. + +@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:142 +@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:46 +@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:96 +@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 crc32.c:141 +@deftypefn Extension {unsigned int} crc32 (const unsigned char *@var{buf}, @ + int @var{len}, unsigned int @var{init}) + +Compute the 32-bit CRC of @var{buf} which has length @var{len}. The +starting value is @var{init}; this may be used to compute the CRC of +data split across multiple buffers by passing the return value of each +call as the @var{init} parameter of the next. + +This is intended to match the CRC used by the @command{gdb} remote +protocol for the @samp{qCRC} command. In order to get the same +results as gdb for a block of data, you must pass the first CRC +parameter as @code{0xffffffff}. + +This CRC can be specified as: + + Width : 32 + Poly : 0x04c11db7 + Init : parameter, typically 0xffffffff + RefIn : false + RefOut : false + XorOut : 0 + +This differs from the "standard" CRC-32 algorithm in that the values +are not reflected, and there is no final XOR value. These differences +make it easy to compose the values of multiple blocks. + +@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:361 +@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:49 +@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 filename_cmp.c:81 +@deftypefn Extension int filename_ncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) + +Return zero if the two file names @var{s1} and @var{s2} are equivalent +in range @var{n}. +If not equivalent, the returned value is similar to what @code{strncmp} +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:59 +@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 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 hashtab.c:336 +@deftypefn Supplemental htab_t htab_create_typed_alloc (size_t @var{size}, @ +htab_hash @var{hash_f}, htab_eq @var{eq_f}, htab_del @var{del_f}, @ +htab_alloc @var{alloc_tab_f}, htab_alloc @var{alloc_f}, @ +htab_free @var{free_f}) + +This function creates a hash table that uses two different allocators +@var{alloc_tab_f} and @var{alloc_f} to use for allocating the table itself +and its entries respectively. This is useful when variables of different +types need to be allocated with different allocators. + +The created hash table is slightly larger than @var{size} and it is +initially empty (all the hash table entries are @code{HTAB_EMPTY_ENTRY}). +The function returns the created hash table, or @code{NULL} if memory +allocation fails. + +@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:174 +@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 memmem.c:20 +@deftypefn Supplemental void* memmem (const void *@var{haystack}, @ + size_t @var{haystack_len} const void *@var{needle}, size_t @var{needle_len}) + +Returns a pointer to the first occurrence of @var{needle} (length +@var{needle_len}) in @var{haystack} (length @var{haystack_len}). +Returns @code{NULL} if not found. + +@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:278 +@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:251 +@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:261 +@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:161 +@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:179 +@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:286 +@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:237 +@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:224 +@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:34 +@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:145 +@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:301 +@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:312 +@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:174 +@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:23 +@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 setproctitle.c:31 +@deftypefn Supplemental void setproctitle (const char *@var{fmt}, ...) + +Set the title of a process to @var{fmt}. va args not supported for now, +but defined for compatibility with BSD. + +@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 simple-object.txh:96 +@deftypefn Extension {const char *} simple_object_attributes_compare @ + (simple_object_attributes *@var{attrs1}, simple_object_attributes *@var{attrs2}, @ + int *@var{err}) + +Compare @var{attrs1} and @var{attrs2}. If they could be linked +together without error, return @code{NULL}. Otherwise, return an +error message and set @code{*@var{err}} to an errno value or @code{0} +if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:81 +@deftypefn Extension {simple_object_attributes *} simple_object_fetch_attributes @ + (simple_object_read *@var{simple_object}, const char **@var{errmsg}, int *@var{err}) + +Fetch the attributes of @var{simple_object}. The attributes are +internal information such as the format of the object file, or the +architecture it was compiled for. This information will persist until +@code{simple_object_attributes_release} is called, even if +@var{simple_object} itself is released. + +On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an +error message, and sets @code{*@var{err}} to an errno value or +@code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:49 +@deftypefn Extension {int} simple_object_find_section @ + (simple_object_read *@var{simple_object} off_t *@var{offset}, @ + off_t *@var{length}, const char **@var{errmsg}, int *@var{err}) + +Look for the section @var{name} in @var{simple_object}. This returns +information for the first section with that name. + +If found, return 1 and set @code{*@var{offset}} to the offset in the +file of the section contents and set @code{*@var{length}} to the +length of the section contents. The value in @code{*@var{offset}} +will be relative to the offset passed to +@code{simple_object_open_read}. + +If the section is not found, and no error occurs, +@code{simple_object_find_section} returns @code{0} and set +@code{*@var{errmsg}} to @code{NULL}. + +If an error occurs, @code{simple_object_find_section} returns +@code{0}, sets @code{*@var{errmsg}} to an error message, and sets +@code{*@var{err}} to an errno value or @code{0} if there is no +relevant errno. + +@end deftypefn + +@c simple-object.txh:27 +@deftypefn Extension {const char *} simple_object_find_sections @ + (simple_object_read *@var{simple_object}, int (*@var{pfn}) (void *@var{data}, @ + const char *@var{name}, off_t @var{offset}, off_t @var{length}), @ + void *@var{data}, int *@var{err}) + +This function calls @var{pfn} for each section in @var{simple_object}. +It calls @var{pfn} with the section name, the offset within the file +of the section contents, and the length of the section contents. The +offset within the file is relative to the offset passed to +@code{simple_object_open_read}. The @var{data} argument to this +function is passed along to @var{pfn}. + +If @var{pfn} returns @code{0}, the loop over the sections stops and +@code{simple_object_find_sections} returns. If @var{pfn} returns some +other value, the loop continues. + +On success @code{simple_object_find_sections} returns. On error it +returns an error string, and sets @code{*@var{err}} to an errno value +or @code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:2 +@deftypefn Extension {simple_object_read *} simple_object_open_read @ + (int @var{descriptor}, off_t @var{offset}, const char *{segment_name}, @ + const char **@var{errmsg}, int *@var{err}) + +Opens an object file for reading. Creates and returns an +@code{simple_object_read} pointer which may be passed to other +functions to extract data from the object file. + +@var{descriptor} holds a file descriptor which permits reading. + +@var{offset} is the offset into the file; this will be @code{0} in the +normal case, but may be a different value when reading an object file +in an archive file. + +@var{segment_name} is only used with the Mach-O file format used on +Darwin aka Mac OS X. It is required on that platform, and means to +only look at sections within the segment with that name. The +parameter is ignored on other systems. + +If an error occurs, this functions returns @code{NULL} and sets +@code{*@var{errmsg}} to an error string and sets @code{*@var{err}} to +an errno value or @code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:107 +@deftypefn Extension {void} simple_object_release_attributes @ + (simple_object_attributes *@var{attrs}) + +Release all resources associated with @var{attrs}. + +@end deftypefn + +@c simple-object.txh:73 +@deftypefn Extension {void} simple_object_release_read @ + (simple_object_read *@var{simple_object}) + +Release all resources associated with @var{simple_object}. This does +not close the file descriptor. + +@end deftypefn + +@c simple-object.txh:184 +@deftypefn Extension {void} simple_object_release_write @ + (simple_object_write *@var{simple_object}) + +Release all resources associated with @var{simple_object}. + +@end deftypefn + +@c simple-object.txh:114 +@deftypefn Extension {simple_object_write *} simple_object_start_write @ + (simple_object_attributes @var{attrs}, const char *@var{segment_name}, @ + const char **@var{errmsg}, int *@var{err}) + +Start creating a new object file using the object file format +described in @var{attrs}. You must fetch attribute information from +an existing object file before you can create a new one. There is +currently no support for creating an object file de novo. + +@var{segment_name} is only used with Mach-O as found on Darwin aka Mac +OS X. The parameter is required on that target. It means that all +sections are created within the named segment. It is ignored for +other object file formats. + +On error @code{simple_object_start_write} returns @code{NULL}, sets +@code{*@var{ERRMSG}} to an error message, and sets @code{*@var{err}} +to an errno value or @code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:153 +@deftypefn Extension {const char *} simple_object_write_add_data @ + (simple_object_write *@var{simple_object}, @ + simple_object_write_section *@var{section}, const void *@var{buffer}, @ + size_t @var{size}, int @var{copy}, int *@var{err}) + +Add data @var{buffer}/@var{size} to @var{section} in +@var{simple_object}. If @var{copy} is non-zero, the data will be +copied into memory if necessary. If @var{copy} is zero, @var{buffer} +must persist until @code{simple_object_write_to_file} is called. is +released. + +On success this returns @code{NULL}. On error this returns an error +message, and sets @code{*@var{err}} to an errno value or 0 if there is +no relevant erro. + +@end deftypefn + +@c simple-object.txh:134 +@deftypefn Extension {simple_object_write_section *} simple_object_write_create_section @ + (simple_object_write *@var{simple_object}, const char *@var{name}, @ + unsigned int @var{align}, const char **@var{errmsg}, int *@var{err}) + +Add a section to @var{simple_object}. @var{name} is the name of the +new section. @var{align} is the required alignment expressed as the +number of required low-order 0 bits (e.g., 2 for alignment to a 32-bit +boundary). + +The section is created as containing data, readable, not writable, not +executable, not loaded at runtime. The section is not written to the +file until @code{simple_object_write_to_file} is called. + +On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an +error message, and sets @code{*@var{err}} to an errno value or +@code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:170 +@deftypefn Extension {const char *} simple_object_write_to_file @ + (simple_object_write *@var{simple_object}, int @var{descriptor}, int *@var{err}) + +Write the complete object file to @var{descriptor}, an open file +descriptor. This writes out all the data accumulated by calls to +@code{simple_object_write_create_section} and +@var{simple_object_write_add_data}. + +This returns @code{NULL} on success. On error this returns an error +message and sets @code{*@var{err}} to an errno value or @code{0} if +there is no relevant errno. + +@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 @code{sprintf}, but it will write to +@var{buf} at most @code{@var{n}-1} bytes of text, followed by a +terminating null byte, for a total of @var{n} bytes. +On error the return value is -1, otherwise it returns the number of +bytes, not including the terminating null byte, that would have been +written 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 splay-tree.c:303 +@deftypefn Supplemental splay_tree splay_tree_new_with_typed_alloc @ +(splay_tree_compare_fn @var{compare_fn}, @ +splay_tree_delete_key_fn @var{delete_key_fn}, @ +splay_tree_delete_value_fn @var{delete_value_fn}, @ +splay_tree_allocate_fn @var{tree_allocate_fn}, @ +splay_tree_allocate_fn @var{node_allocate_fn}, @ +splay_tree_deallocate_fn @var{deallocate_fn}, @ +void * @var{allocate_data}) + +This function creates a splay tree that uses two different allocators +@var{tree_allocate_fn} and @var{node_allocate_fn} to use for allocating the +tree itself and its nodes respectively. This is useful when variables of +different types need to be allocated with different allocators. + +The splay tree will use @var{compare_fn} to compare nodes, +@var{delete_key_fn} to deallocate keys, and @var{delete_value_fn} to +deallocate values. + +@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 @code{vsprintf}, but it will write to +@var{buf} at most @code{@var{n}-1} bytes of text, followed by a +terminating null byte, for a total of @var{n} bytes. 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:306 +@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 + + |