diff options
Diffstat (limited to 'contrib/binutils/libiberty/functions.texi')
| -rw-r--r-- | contrib/binutils/libiberty/functions.texi | 1156 |
1 files changed, 0 insertions, 1156 deletions
diff --git a/contrib/binutils/libiberty/functions.texi b/contrib/binutils/libiberty/functions.texi deleted file mode 100644 index aac4424fd8f27..0000000000000 --- a/contrib/binutils/libiberty/functions.texi +++ /dev/null @@ -1,1156 +0,0 @@ -@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:24 -@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:33 -@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:139 -@deftypefn Extension char** buildargv (char *@var{sp}) - -Given a pointer to a string, parse the string extracting fields -separated by whitespace and optionally enclosed within either single -or double quotes (which are stripped off), and build a vector of -pointers to copies of the string for each field. The input string -remains unchanged. The last element of the vector is followed by a -@code{NULL} element. - -All of the memory for the pointer array and copies of the string -is obtained from @code{malloc}. All of the memory can be returned to the -system with the single function call @code{freeargv}, which takes the -returned result of @code{buildargv}, as it's argument. - -Returns a pointer to the argument vector if successful. Returns -@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient -memory to complete building the argument vector. - -If the input is a null string (as opposed to a @code{NULL} pointer), -then buildarg returns an argument vector that has one arg, a null -string. - -@end deftypefn - -@c bzero.c:6 -@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count}) - -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 compatability only. Its use is -not recommended. - -@end deftypefn - -@c make-temp-file.c:88 -@deftypefn Replacement char* choose_tmpdir () - -Returns a pointer to a directory path suitable for creating temporary -files in. - -@end deftypefn - -@c clock.c:27 -@deftypefn Supplemental long clock (void) - -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:65 -@deftypefn Extension char** dupargv (char **@var{vector}) - -Duplicate an argument vector. Simply scans through @var{vector}, -duplicating each argument until the terminating @code{NULL} is found. -Returns a pointer to the argument vector if successful. Returns -@code{NULL} if there is insufficient memory to complete building the -argument vector. - -@end deftypefn - -@c strerror.c:566 -@deftypefn 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 fdmatch.c:23 -@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2}) - -Check to see if two open file descriptors refer to the same file. -This is useful, for example, when we have an open file descriptor for -an unnamed file, and the name of a file that we believe to correspond -to that fd. This can happen when we are exec'd with an already open -file (@code{stdout} for example) or from the SVR4 @file{/proc} calls -that return open file descriptors for mapped address spaces. All we -have to do is open the file by name and check the two file descriptors -for a match, which is done by comparing major and minor device numbers -and inode numbers. - -@end deftypefn - -@c ffs.c:3 -@deftypefn Supplemental int ffs (int @var{valu}) - -Find the first (least significant) bit set in @var{valu}. Bits are -numbered from right to left, starting with bit 1 (corresponding to the -value 1). If @var{valu} is zero, zero is returned. - -@end deftypefn - -@c fnmatch.txh:1 -@deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags}) - -Matches @var{string} against @var{pattern}, returning zero if it -matches, @code{FNM_NOMATCH} if not. @var{pattern} may contain the -wildcards @code{?} to match any one character, @code{*} to match any -zero or more characters, or a set of alternate characters in square -brackets, like @samp{[a-gt8]}, which match one character (@code{a} -through @code{g}, or @code{t}, or @code{8}, in this example) if that one -character is in the set. A set may be inverted (i.e., match anything -except what's in the set) by giving @code{^} or @code{!} as the first -character in the set. To include those characters in the set, list them -as anything other than the first character of the set. To include a -dash in the set, list it last in the set. A backslash character makes -the following character not special, so for example you could match -against a literal asterisk with @samp{\*}. To match a literal -backslash, use @samp{\\}. - -@code{flags} controls various aspects of the matching process, and is a -boolean OR of zero or more of the following values (defined in -@code{<fnmatch.h>}): - -@table @code - -@item FNM_PATHNAME -@itemx FNM_FILE_NAME -@var{string} is assumed to be a path name. No wildcard will ever match -@code{/}. - -@item FNM_NOESCAPE -Do not interpret backslashes as quoting the following special character. - -@item FNM_PERIOD -A leading period (at the beginning of @var{string}, or if -@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or -@code{?} but must be matched explicitly. - -@item FNM_LEADING_DIR -Means that @var{string} also matches @var{pattern} if some initial part -of @var{string} matches, and is followed by @code{/} and zero or more -characters. For example, @samp{foo*} would match either @samp{foobar} -or @samp{foobar/grill}. - -@item FNM_CASEFOLD -Ignores case when performing the comparison. - -@end table - -@end deftypefn - -@c argv.c:111 -@deftypefn Extension void freeargv (char **@var{vector}) - -Free an argument vector that was built using @code{buildargv}. Simply -scans through @var{vector}, freeing the memory for each argument until -the terminating @code{NULL} is found, and then frees @var{vector} -itself. - -@end deftypefn - -@c getruntime.c: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 hex.c:30 -@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:39 -@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:47 -@deftypefn Extension unsigned int hex_value (int @var{c}) - -Returns the numeric equivalent of the given character when interpreted -as a hexidecimal 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:45 -@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:94 -@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:138 -@deftypefn Replacement char* make_temp_file (const char *@var{suffix}) - -Return a temporary file name (as a string) or @code{NULL} if unable to -create one. @var{suffix} is a suffix to append to the file name. The -string is @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:54 -@deftypefn Replacement int mkstemps (char *@var{template}, int @var{suffix_len}) - -Generate a unique temporary file name from @var{template}. -@var{template} has the form: - -@example - @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{template} before @var{suffix} -must be @samp{XXXXXX}; they are replaced with a string that makes the -filename unique. Returns a file descriptor open on the file for -reading and writing. - -@end deftypefn - -@c pexecute.txh:1 -@deftypefn Extension int pexecute (const char *@var{program}, char * const *@var{argv}, const char *@var{this_pname}, const char *@var{temp_base}, char **@var{errmsg_fmt}, char **@var{errmsg_arg}, int flags) - -Executes a program. - -@var{program} and @var{argv} are the arguments to -@code{execv}/@code{execvp}. - -@var{this_pname} is name of the calling program (i.e., @code{argv[0]}). - -@var{temp_base} is the path name, sans suffix, of a temporary file to -use if needed. This is currently only needed for MS-DOS ports that -don't use @code{go32} (do any still exist?). Ports that don't need it -can pass @code{NULL}. - -(@code{@var{flags} & PEXECUTE_SEARCH}) is non-zero if @env{PATH} -should be searched (??? It's not clear that GCC passes this flag -correctly). (@code{@var{flags} & PEXECUTE_FIRST}) is nonzero for the -first process in chain. (@code{@var{flags} & PEXECUTE_FIRST}) is -nonzero for the last process in chain. The first/last flags could be -simplified to only mark the last of a chain of processes but that -requires the caller to always mark the last one (and not give up -early if some error occurs). It's more robust to require the caller -to mark both ends of the chain. - -The result is the pid on systems like Unix where we -@code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we -use @code{spawn}. It is up to the caller to wait for the child. - -The result is the @code{WEXITSTATUS} on systems like MS-DOS where we -@code{spawn} and wait for the child here. - -Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the -text of the error message with an optional argument (if not needed, -@var{errmsg_arg} is set to @code{NULL}), and @minus{}1 is returned. -@code{errno} is available to the caller to use. - -@end deftypefn - -@c strsignal.c:547 -@deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message}) - -Print @var{message} to the standard error, followed by a colon, -followed by the description of the signal specified by @var{signo}, -followed by a newline. - -@end deftypefn - -@c putenv.c:21 -@deftypefn Supplemental int putenv (const char *@var{string}) - -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:39 -@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) - -Waits for a program started by @code{pexecute} to finish. - -@var{pid} is the process id of the task to wait for. @var{status} is -the `status' argument to wait. @var{flags} is currently unused -(allows future enhancement without breaking upward compatibility). -Pass 0 for now. - -The result is the pid of the child reaped, or -1 for failure -(@code{errno} says why). - -On systems that don't support waiting for a particular child, -@var{pid} is ignored. On systems like MS-DOS that don't really -multitask @code{pwait} is just a mechanism to provide a consistent -interface for the caller. - -@end deftypefn - -@c random.c:39 -@deftypefn Supplement {long int} random (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:177 -@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:353 -@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:602 -@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 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:388 -@deftypefn Supplemental {const char *} strsignal (int @var{signo}) - -Maps an signal number to an signal message string, the contents of -which are implementation defined. On systems which have the external -variable @code{sys_siglist}, these strings will be the same as the -ones used by @code{psignal()}. - -If the supplied signal number is within the valid range of indices for -the @code{sys_siglist}, but no message is available for the particular -signal number, then returns the string @samp{Signal @var{num}}, where -@var{num} is the signal number. - -If the supplied signal number is not a valid index into -@code{sys_siglist}, returns @code{NULL}. - -The returned string is only guaranteed to be valid only until the next -call to @code{strsignal}. - -@end deftypefn - -@c strsignal.c:452 -@deftypefn Extension {const char*} strsigno (int @var{signo}) - -Given an signal number, returns a pointer to a string containing the -symbolic name of that signal number, as found in @code{<signal.h>}. - -If the supplied signal number is within the valid range of indices for -symbolic names, but no name is available for the particular signal -number, then returns the string @samp{Signal @var{num}}, where -@var{num} is the signal number. - -If the supplied signal number is not within the range of valid -indices, then returns @code{NULL}. - -The contents of the location pointed to are only guaranteed to be -valid until the next call to @code{strsigno}. - -@end deftypefn - -@c strstr.c:6 -@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub}) - -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:730 -@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:507 -@deftypefn Extension int strtosigno (const char *@var{name}) - -Given the symbolic name of a signal, map it to a signal number. If no -translation is found, returns 0. - -@end deftypefn - -@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 vasprintf.c:48 -@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 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 - - |