functions.texi revision 130562
1@c Automatically generated from *.c and others (the comments before 2@c each entry tell you which file and where in that file). DO NOT EDIT! 3@c Edit the *.c files, configure with --enable-maintainer-mode, 4@c and let gather-docs build you a new copy. 5 6@c safe-ctype.c:24 7@defvr Extension HOST_CHARSET 8This macro indicates the basic character set and encoding used by the 9host: more precisely, the encoding used for character constants in 10preprocessor @samp{#if} statements (the C "execution character set"). 11It is defined by @file{safe-ctype.h}, and will be an integer constant 12with one of the following values: 13 14@ftable @code 15@item HOST_CHARSET_UNKNOWN 16The host character set is unknown - that is, not one of the next two 17possibilities. 18 19@item HOST_CHARSET_ASCII 20The host character set is ASCII. 21 22@item HOST_CHARSET_EBCDIC 23The host character set is some variant of EBCDIC. (Only one of the 24nineteen EBCDIC varying characters is tested; exercise caution.) 25@end ftable 26@end defvr 27 28@c alloca.c:26 29@deftypefn Replacement void* alloca (size_t @var{size}) 30 31This function allocates memory which will be automatically reclaimed 32after the procedure exits. The @libib{} implementation does not free 33the memory immediately but will do so eventually during subsequent 34calls to this function. Memory is allocated using @code{xmalloc} under 35normal circumstances. 36 37The header file @file{alloca-conf.h} can be used in conjunction with the 38GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make 39available this function. The @code{AC_FUNC_ALLOCA} test requires that 40client code use a block of preprocessor code to be safe (see the Autoconf 41manual for more); this header incorporates that logic and more, including 42the possibility of a GCC built-in function. 43 44@end deftypefn 45 46@c asprintf.c:33 47@deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...) 48 49Like @code{sprintf}, but instead of passing a pointer to a buffer, you 50pass a pointer to a pointer. This function will compute the size of 51the buffer needed, allocate memory with @code{malloc}, and store a 52pointer to the allocated memory in @code{*@var{resptr}}. The value 53returned is the same as @code{sprintf} would return. If memory could 54not be allocated, minus one is returned and @code{NULL} is stored in 55@code{*@var{resptr}}. 56 57@end deftypefn 58 59@c atexit.c:6 60@deftypefn Supplemental int atexit (void (*@var{f})()) 61 62Causes function @var{f} to be called at exit. Returns 0. 63 64@end deftypefn 65 66@c basename.c:6 67@deftypefn Supplemental char* basename (const char *@var{name}) 68 69Returns a pointer to the last component of pathname @var{name}. 70Behavior is undefined if the pathname ends in a directory separator. 71 72@end deftypefn 73 74@c bcmp.c:6 75@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count}) 76 77Compares the first @var{count} bytes of two areas of memory. Returns 78zero if they are the same, nonzero otherwise. Returns zero if 79@var{count} is zero. A nonzero result only indicates a difference, 80it does not indicate any sorting order (say, by having a positive 81result mean @var{x} sorts before @var{y}). 82 83@end deftypefn 84 85@c bcopy.c:3 86@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length}) 87 88Copies @var{length} bytes from memory region @var{in} to region 89@var{out}. The use of @code{bcopy} is deprecated in new programs. 90 91@end deftypefn 92 93@c bsearch.c:33 94@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 *)) 95 96Performs a search over an array of @var{nmemb} elements pointed to by 97@var{base} for a member that matches the object pointed to by @var{key}. 98The size of each member is specified by @var{size}. The array contents 99should be sorted in ascending order according to the @var{compar} 100comparison function. This routine should take two arguments pointing to 101the @var{key} and to an array member, in that order, and should return an 102integer less than, equal to, or greater than zero if the @var{key} object 103is respectively less than, matching, or greater than the array member. 104 105@end deftypefn 106 107@c argv.c:139 108@deftypefn Extension char** buildargv (char *@var{sp}) 109 110Given a pointer to a string, parse the string extracting fields 111separated by whitespace and optionally enclosed within either single 112or double quotes (which are stripped off), and build a vector of 113pointers to copies of the string for each field. The input string 114remains unchanged. The last element of the vector is followed by a 115@code{NULL} element. 116 117All of the memory for the pointer array and copies of the string 118is obtained from @code{malloc}. All of the memory can be returned to the 119system with the single function call @code{freeargv}, which takes the 120returned result of @code{buildargv}, as it's argument. 121 122Returns a pointer to the argument vector if successful. Returns 123@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient 124memory to complete building the argument vector. 125 126If the input is a null string (as opposed to a @code{NULL} pointer), 127then buildarg returns an argument vector that has one arg, a null 128string. 129 130@end deftypefn 131 132@c bzero.c:6 133@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count}) 134 135Zeros @var{count} bytes starting at @var{mem}. Use of this function 136is deprecated in favor of @code{memset}. 137 138@end deftypefn 139 140@c calloc.c:6 141@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize}) 142 143Uses @code{malloc} to allocate storage for @var{nelem} objects of 144@var{elsize} bytes each, then zeros the memory. 145 146@end deftypefn 147 148@c choose-temp.c:42 149@deftypefn Extension char* choose_temp_base (void) 150 151Return a prefix for temporary file names or @code{NULL} if unable to 152find one. The current directory is chosen if all else fails so the 153program is exited if a temporary directory can't be found (@code{mktemp} 154fails). The buffer for the result is obtained with @code{xmalloc}. 155 156This function is provided for backwards compatability only. Its use is 157not recommended. 158 159@end deftypefn 160 161@c make-temp-file.c:88 162@deftypefn Replacement char* choose_tmpdir () 163 164Returns a pointer to a directory path suitable for creating temporary 165files in. 166 167@end deftypefn 168 169@c clock.c:27 170@deftypefn Supplemental long clock (void) 171 172Returns an approximation of the CPU time used by the process as a 173@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the 174number of seconds used. 175 176@end deftypefn 177 178@c concat.c:24 179@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL}) 180 181Concatenate zero or more of strings and return the result in freshly 182@code{xmalloc}ed memory. Returns @code{NULL} if insufficient memory is 183available. The argument list is terminated by the first @code{NULL} 184pointer encountered. Pointers to empty strings are ignored. 185 186@end deftypefn 187 188@c argv.c:65 189@deftypefn Extension char** dupargv (char **@var{vector}) 190 191Duplicate an argument vector. Simply scans through @var{vector}, 192duplicating each argument until the terminating @code{NULL} is found. 193Returns a pointer to the argument vector if successful. Returns 194@code{NULL} if there is insufficient memory to complete building the 195argument vector. 196 197@end deftypefn 198 199@c strerror.c:566 200@deftypefn Extension int errno_max (void) 201 202Returns the maximum @code{errno} value for which a corresponding 203symbolic name or message is available. Note that in the case where we 204use the @code{sys_errlist} supplied by the system, it is possible for 205there to be more symbolic names than messages, or vice versa. In 206fact, the manual page for @code{perror(3C)} explicitly warns that one 207should check the size of the table (@code{sys_nerr}) before indexing 208it, since new error codes may be added to the system before they are 209added to the table. Thus @code{sys_nerr} might be smaller than value 210implied by the largest @code{errno} value defined in @code{<errno.h>}. 211 212We return the maximum value that can be used to obtain a meaningful 213symbolic name or message. 214 215@end deftypefn 216 217@c fdmatch.c:23 218@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2}) 219 220Check to see if two open file descriptors refer to the same file. 221This is useful, for example, when we have an open file descriptor for 222an unnamed file, and the name of a file that we believe to correspond 223to that fd. This can happen when we are exec'd with an already open 224file (@code{stdout} for example) or from the SVR4 @file{/proc} calls 225that return open file descriptors for mapped address spaces. All we 226have to do is open the file by name and check the two file descriptors 227for a match, which is done by comparing major and minor device numbers 228and inode numbers. 229 230@end deftypefn 231 232@c ffs.c:3 233@deftypefn Supplemental int ffs (int @var{valu}) 234 235Find the first (least significant) bit set in @var{valu}. Bits are 236numbered from right to left, starting with bit 1 (corresponding to the 237value 1). If @var{valu} is zero, zero is returned. 238 239@end deftypefn 240 241@c fnmatch.txh:1 242@deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags}) 243 244Matches @var{string} against @var{pattern}, returning zero if it 245matches, @code{FNM_NOMATCH} if not. @var{pattern} may contain the 246wildcards @code{?} to match any one character, @code{*} to match any 247zero or more characters, or a set of alternate characters in square 248brackets, like @samp{[a-gt8]}, which match one character (@code{a} 249through @code{g}, or @code{t}, or @code{8}, in this example) if that one 250character is in the set. A set may be inverted (i.e., match anything 251except what's in the set) by giving @code{^} or @code{!} as the first 252character in the set. To include those characters in the set, list them 253as anything other than the first character of the set. To include a 254dash in the set, list it last in the set. A backslash character makes 255the following character not special, so for example you could match 256against a literal asterisk with @samp{\*}. To match a literal 257backslash, use @samp{\\}. 258 259@code{flags} controls various aspects of the matching process, and is a 260boolean OR of zero or more of the following values (defined in 261@code{<fnmatch.h>}): 262 263@table @code 264 265@item FNM_PATHNAME 266@itemx FNM_FILE_NAME 267@var{string} is assumed to be a path name. No wildcard will ever match 268@code{/}. 269 270@item FNM_NOESCAPE 271Do not interpret backslashes as quoting the following special character. 272 273@item FNM_PERIOD 274A leading period (at the beginning of @var{string}, or if 275@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or 276@code{?} but must be matched explicitly. 277 278@item FNM_LEADING_DIR 279Means that @var{string} also matches @var{pattern} if some initial part 280of @var{string} matches, and is followed by @code{/} and zero or more 281characters. For example, @samp{foo*} would match either @samp{foobar} 282or @samp{foobar/grill}. 283 284@item FNM_CASEFOLD 285Ignores case when performing the comparison. 286 287@end table 288 289@end deftypefn 290 291@c argv.c:111 292@deftypefn Extension void freeargv (char **@var{vector}) 293 294Free an argument vector that was built using @code{buildargv}. Simply 295scans through @var{vector}, freeing the memory for each argument until 296the terminating @code{NULL} is found, and then frees @var{vector} 297itself. 298 299@end deftypefn 300 301@c getruntime.c:82 302@deftypefn Replacement long get_run_time (void) 303 304Returns the time used so far, in microseconds. If possible, this is 305the time used by this process, else it is the elapsed time since the 306process started. 307 308@end deftypefn 309 310@c getcwd.c:6 311@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len}) 312 313Copy the absolute pathname for the current working directory into 314@var{pathname}, which is assumed to point to a buffer of at least 315@var{len} bytes, and return a pointer to the buffer. If the current 316directory's path doesn't fit in @var{len} characters, the result is 317@code{NULL} and @code{errno} is set. If @var{pathname} is a null pointer, 318@code{getcwd} will obtain @var{len} bytes of space using 319@code{malloc}. 320 321@end deftypefn 322 323@c getpagesize.c:5 324@deftypefn Supplemental int getpagesize (void) 325 326Returns the number of bytes in a page of memory. This is the 327granularity of many of the system memory management routines. No 328guarantee is made as to whether or not it is the same as the basic 329memory management hardware page size. 330 331@end deftypefn 332 333@c getpwd.c:5 334@deftypefn Supplemental char* getpwd (void) 335 336Returns the current working directory. This implementation caches the 337result on the assumption that the process will not call @code{chdir} 338between calls to @code{getpwd}. 339 340@end deftypefn 341 342@c hex.c:30 343@deftypefn Extension void hex_init (void) 344 345Initializes the array mapping the current character set to 346corresponding hex values. This function must be called before any 347call to @code{hex_p} or @code{hex_value}. If you fail to call it, a 348default ASCII-based table will normally be used on ASCII systems. 349 350@end deftypefn 351 352@c hex.c:39 353@deftypefn Extension int hex_p (int @var{c}) 354 355Evaluates to non-zero if the given character is a valid hex character, 356or zero if it is not. Note that the value you pass will be cast to 357@code{unsigned char} within the macro. 358 359@end deftypefn 360 361@c hex.c:47 362@deftypefn Extension unsigned int hex_value (int @var{c}) 363 364Returns the numeric equivalent of the given character when interpreted 365as a hexidecimal digit. The result is undefined if you pass an 366invalid hex digit. Note that the value you pass will be cast to 367@code{unsigned char} within the macro. 368 369The @code{hex_value} macro returns @code{unsigned int}, rather than 370signed @code{int}, to make it easier to use in parsing addresses from 371hex dump files: a signed @code{int} would be sign-extended when 372converted to a wider unsigned type --- like @code{bfd_vma}, on some 373systems. 374 375@end deftypefn 376 377@c index.c:5 378@deftypefn Supplemental char* index (char *@var{s}, int @var{c}) 379 380Returns a pointer to the first occurrence of the character @var{c} in 381the string @var{s}, or @code{NULL} if not found. The use of @code{index} is 382deprecated in new programs in favor of @code{strchr}. 383 384@end deftypefn 385 386@c insque.c:6 387@deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred}) 388@deftypefnx Supplemental void remque (struct qelem *@var{elem}) 389 390Routines to manipulate queues built from doubly linked lists. The 391@code{insque} routine inserts @var{elem} in the queue immediately 392after @var{pred}. The @code{remque} routine removes @var{elem} from 393its containing queue. These routines expect to be passed pointers to 394structures which have as their first members a forward pointer and a 395back pointer, like this prototype (although no prototype is provided): 396 397@example 398struct qelem @{ 399 struct qelem *q_forw; 400 struct qelem *q_back; 401 char q_data[]; 402@}; 403@end example 404 405@end deftypefn 406 407@c safe-ctype.c:45 408@deffn Extension ISALPHA (@var{c}) 409@deffnx Extension ISALNUM (@var{c}) 410@deffnx Extension ISBLANK (@var{c}) 411@deffnx Extension ISCNTRL (@var{c}) 412@deffnx Extension ISDIGIT (@var{c}) 413@deffnx Extension ISGRAPH (@var{c}) 414@deffnx Extension ISLOWER (@var{c}) 415@deffnx Extension ISPRINT (@var{c}) 416@deffnx Extension ISPUNCT (@var{c}) 417@deffnx Extension ISSPACE (@var{c}) 418@deffnx Extension ISUPPER (@var{c}) 419@deffnx Extension ISXDIGIT (@var{c}) 420 421These twelve macros are defined by @file{safe-ctype.h}. Each has the 422same meaning as the corresponding macro (with name in lowercase) 423defined by the standard header @file{ctype.h}. For example, 424@code{ISALPHA} returns true for alphabetic characters and false for 425others. However, there are two differences between these macros and 426those provided by @file{ctype.h}: 427 428@itemize @bullet 429@item These macros are guaranteed to have well-defined behavior for all 430values representable by @code{signed char} and @code{unsigned char}, and 431for @code{EOF}. 432 433@item These macros ignore the current locale; they are true for these 434fixed sets of characters: 435@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada} 436@item @code{ALPHA} @tab @kbd{A-Za-z} 437@item @code{ALNUM} @tab @kbd{A-Za-z0-9} 438@item @code{BLANK} @tab @kbd{space tab} 439@item @code{CNTRL} @tab @code{!PRINT} 440@item @code{DIGIT} @tab @kbd{0-9} 441@item @code{GRAPH} @tab @code{ALNUM || PUNCT} 442@item @code{LOWER} @tab @kbd{a-z} 443@item @code{PRINT} @tab @code{GRAPH ||} @kbd{space} 444@item @code{PUNCT} @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?} 445@item @code{SPACE} @tab @kbd{space tab \n \r \f \v} 446@item @code{UPPER} @tab @kbd{A-Z} 447@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f} 448@end multitable 449 450Note that, if the host character set is ASCII or a superset thereof, 451all these macros will return false for all values of @code{char} outside 452the range of 7-bit ASCII. In particular, both ISPRINT and ISCNTRL return 453false for characters with numeric values from 128 to 255. 454@end itemize 455@end deffn 456 457@c safe-ctype.c:94 458@deffn Extension ISIDNUM (@var{c}) 459@deffnx Extension ISIDST (@var{c}) 460@deffnx Extension IS_VSPACE (@var{c}) 461@deffnx Extension IS_NVSPACE (@var{c}) 462@deffnx Extension IS_SPACE_OR_NUL (@var{c}) 463@deffnx Extension IS_ISOBASIC (@var{c}) 464These six macros are defined by @file{safe-ctype.h} and provide 465additional character classes which are useful when doing lexical 466analysis of C or similar languages. They are true for the following 467sets of characters: 468 469@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada} 470@item @code{IDNUM} @tab @kbd{A-Za-z0-9_} 471@item @code{IDST} @tab @kbd{A-Za-z_} 472@item @code{VSPACE} @tab @kbd{\r \n} 473@item @code{NVSPACE} @tab @kbd{space tab \f \v \0} 474@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE} 475@item @code{ISOBASIC} @tab @code{VSPACE || NVSPACE || PRINT} 476@end multitable 477@end deffn 478 479@c lbasename.c:23 480@deftypefn Replacement {const char*} lbasename (const char *@var{name}) 481 482Given a pointer to a string containing a typical pathname 483(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the 484last component of the pathname (@samp{ls.c} in this case). The 485returned pointer is guaranteed to lie within the original 486string. This latter fact is not true of many vendor C 487libraries, which return special strings or modify the passed 488strings for particular input. 489 490In particular, the empty string returns the same empty string, 491and a path ending in @code{/} returns the empty string after it. 492 493@end deftypefn 494 495@c lrealpath.c:25 496@deftypefn Replacement {const char*} lrealpath (const char *@var{name}) 497 498Given a pointer to a string containing a pathname, returns a canonical 499version of the filename. Symlinks will be resolved, and ``.'' and ``..'' 500components will be simplified. The returned value will be allocated using 501@code{malloc}, or @code{NULL} will be returned on a memory allocation error. 502 503@end deftypefn 504 505@c make-relative-prefix.c:24 506@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, const char *@var{bin_prefix}, const char *@var{prefix}) 507 508Given three paths @var{progname}, @var{bin_prefix}, @var{prefix}, 509return the path that is in the same position relative to 510@var{progname}'s directory as @var{prefix} is relative to 511@var{bin_prefix}. That is, a string starting with the directory 512portion of @var{progname}, followed by a relative pathname of the 513difference between @var{bin_prefix} and @var{prefix}. 514 515If @var{progname} does not contain any directory separators, 516@code{make_relative_prefix} will search @env{PATH} to find a program 517named @var{progname}. Also, if @var{progname} is a symbolic link, 518the symbolic link will be resolved. 519 520For example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta}, 521@var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is 522@code{/red/green/blue/gcc}, then this function will return 523@code{/red/green/blue/../../omega/}. 524 525The return value is normally allocated via @code{malloc}. If no 526relative prefix can be found, return @code{NULL}. 527 528@end deftypefn 529 530@c make-temp-file.c:138 531@deftypefn Replacement char* make_temp_file (const char *@var{suffix}) 532 533Return a temporary file name (as a string) or @code{NULL} if unable to 534create one. @var{suffix} is a suffix to append to the file name. The 535string is @code{malloc}ed, and the temporary file has been created. 536 537@end deftypefn 538 539@c memchr.c:3 540@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n}) 541 542This function searches memory starting at @code{*@var{s}} for the 543character @var{c}. The search only ends with the first occurrence of 544@var{c}, or after @var{length} characters; in particular, a null 545character does not terminate the search. If the character @var{c} is 546found within @var{length} characters of @code{*@var{s}}, a pointer 547to the character is returned. If @var{c} is not found, then @code{NULL} is 548returned. 549 550@end deftypefn 551 552@c memcmp.c:6 553@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count}) 554 555Compares the first @var{count} bytes of two areas of memory. Returns 556zero if they are the same, a value less than zero if @var{x} is 557lexically less than @var{y}, or a value greater than zero if @var{x} 558is lexically greater than @var{y}. Note that lexical order is determined 559as if comparing unsigned char arrays. 560 561@end deftypefn 562 563@c memcpy.c:6 564@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length}) 565 566Copies @var{length} bytes from memory region @var{in} to region 567@var{out}. Returns a pointer to @var{out}. 568 569@end deftypefn 570 571@c memmove.c:6 572@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count}) 573 574Copies @var{count} bytes from memory area @var{from} to memory area 575@var{to}, returning a pointer to @var{to}. 576 577@end deftypefn 578 579@c mempcpy.c:23 580@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, size_t @var{length}) 581 582Copies @var{length} bytes from memory region @var{in} to region 583@var{out}. Returns a pointer to @var{out} + @var{length}. 584 585@end deftypefn 586 587@c memset.c:6 588@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count}) 589 590Sets the first @var{count} bytes of @var{s} to the constant byte 591@var{c}, returning a pointer to @var{s}. 592 593@end deftypefn 594 595@c mkstemps.c:54 596@deftypefn Replacement int mkstemps (char *@var{template}, int @var{suffix_len}) 597 598Generate a unique temporary file name from @var{template}. 599@var{template} has the form: 600 601@example 602 @var{path}/ccXXXXXX@var{suffix} 603@end example 604 605@var{suffix_len} tells us how long @var{suffix} is (it can be zero 606length). The last six characters of @var{template} before @var{suffix} 607must be @samp{XXXXXX}; they are replaced with a string that makes the 608filename unique. Returns a file descriptor open on the file for 609reading and writing. 610 611@end deftypefn 612 613@c pexecute.txh:1 614@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) 615 616Executes a program. 617 618@var{program} and @var{argv} are the arguments to 619@code{execv}/@code{execvp}. 620 621@var{this_pname} is name of the calling program (i.e., @code{argv[0]}). 622 623@var{temp_base} is the path name, sans suffix, of a temporary file to 624use if needed. This is currently only needed for MS-DOS ports that 625don't use @code{go32} (do any still exist?). Ports that don't need it 626can pass @code{NULL}. 627 628(@code{@var{flags} & PEXECUTE_SEARCH}) is non-zero if @env{PATH} 629should be searched (??? It's not clear that GCC passes this flag 630correctly). (@code{@var{flags} & PEXECUTE_FIRST}) is nonzero for the 631first process in chain. (@code{@var{flags} & PEXECUTE_FIRST}) is 632nonzero for the last process in chain. The first/last flags could be 633simplified to only mark the last of a chain of processes but that 634requires the caller to always mark the last one (and not give up 635early if some error occurs). It's more robust to require the caller 636to mark both ends of the chain. 637 638The result is the pid on systems like Unix where we 639@code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we 640use @code{spawn}. It is up to the caller to wait for the child. 641 642The result is the @code{WEXITSTATUS} on systems like MS-DOS where we 643@code{spawn} and wait for the child here. 644 645Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the 646text of the error message with an optional argument (if not needed, 647@var{errmsg_arg} is set to @code{NULL}), and @minus{}1 is returned. 648@code{errno} is available to the caller to use. 649 650@end deftypefn 651 652@c strsignal.c:547 653@deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message}) 654 655Print @var{message} to the standard error, followed by a colon, 656followed by the description of the signal specified by @var{signo}, 657followed by a newline. 658 659@end deftypefn 660 661@c putenv.c:21 662@deftypefn Supplemental int putenv (const char *@var{string}) 663 664Uses @code{setenv} or @code{unsetenv} to put @var{string} into 665the environment or remove it. If @var{string} is of the form 666@samp{name=value} the string is added; if no @samp{=} is present the 667name is unset/removed. 668 669@end deftypefn 670 671@c pexecute.txh:39 672@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) 673 674Waits for a program started by @code{pexecute} to finish. 675 676@var{pid} is the process id of the task to wait for. @var{status} is 677the `status' argument to wait. @var{flags} is currently unused 678(allows future enhancement without breaking upward compatibility). 679Pass 0 for now. 680 681The result is the pid of the child reaped, or -1 for failure 682(@code{errno} says why). 683 684On systems that don't support waiting for a particular child, 685@var{pid} is ignored. On systems like MS-DOS that don't really 686multitask @code{pwait} is just a mechanism to provide a consistent 687interface for the caller. 688 689@end deftypefn 690 691@c random.c:39 692@deftypefn Supplement {long int} random (void) 693@deftypefnx Supplement void srandom (unsigned int @var{seed}) 694@deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n}) 695@deftypefnx Supplement void* setstate (void *@var{arg_state}) 696 697Random number functions. @code{random} returns a random number in the 698range 0 to @code{LONG_MAX}. @code{srandom} initializes the random 699number generator to some starting point determined by @var{seed} 700(else, the values returned by @code{random} are always the same for each 701run of the program). @code{initstate} and @code{setstate} allow fine-grained 702control over the state of the random number generator. 703 704@end deftypefn 705 706@c concat.c:177 707@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL}) 708 709Same as @code{concat}, except that if @var{optr} is not @code{NULL} it 710is freed after the string is created. This is intended to be useful 711when you're extending an existing string or building up a string in a 712loop: 713 714@example 715 str = reconcat (str, "pre-", str, NULL); 716@end example 717 718@end deftypefn 719 720@c rename.c:6 721@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new}) 722 723Renames a file from @var{old} to @var{new}. If @var{new} already 724exists, it is removed. 725 726@end deftypefn 727 728@c rindex.c:5 729@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c}) 730 731Returns a pointer to the last occurrence of the character @var{c} in 732the string @var{s}, or @code{NULL} if not found. The use of @code{rindex} is 733deprecated in new programs in favor of @code{strrchr}. 734 735@end deftypefn 736 737@c setenv.c:22 738@deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite}) 739@deftypefnx Supplemental void unsetenv (const char *@var{name}) 740 741@code{setenv} adds @var{name} to the environment with value 742@var{value}. If the name was already present in the environment, 743the new value will be stored only if @var{overwrite} is nonzero. 744The companion @code{unsetenv} function removes @var{name} from the 745environment. This implementation is not safe for multithreaded code. 746 747@end deftypefn 748 749@c strsignal.c:353 750@deftypefn Extension int signo_max (void) 751 752Returns the maximum signal value for which a corresponding symbolic 753name or message is available. Note that in the case where we use the 754@code{sys_siglist} supplied by the system, it is possible for there to 755be more symbolic names than messages, or vice versa. In fact, the 756manual page for @code{psignal(3b)} explicitly warns that one should 757check the size of the table (@code{NSIG}) before indexing it, since 758new signal codes may be added to the system before they are added to 759the table. Thus @code{NSIG} might be smaller than value implied by 760the largest signo value defined in @code{<signal.h>}. 761 762We return the maximum value that can be used to obtain a meaningful 763symbolic name or message. 764 765@end deftypefn 766 767@c sigsetmask.c:8 768@deftypefn Supplemental int sigsetmask (int @var{set}) 769 770Sets the signal mask to the one provided in @var{set} and returns 771the old mask (which, for libiberty's implementation, will always 772be the value @code{1}). 773 774@end deftypefn 775 776@c snprintf.c:28 777@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...) 778 779This function is similar to sprintf, but it will print at most @var{n} 780characters. On error the return value is -1, otherwise it returns the 781number of characters that would have been printed had @var{n} been 782sufficiently large, regardless of the actual value of @var{n}. Note 783some pre-C99 system libraries do not implement this correctly so users 784cannot generally rely on the return value if the system version of 785this function is used. 786 787@end deftypefn 788 789@c spaces.c:22 790@deftypefn Extension char* spaces (int @var{count}) 791 792Returns a pointer to a memory region filled with the specified 793number of spaces and null terminated. The returned pointer is 794valid until at least the next call. 795 796@end deftypefn 797 798@c stpcpy.c:23 799@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src}) 800 801Copies the string @var{src} into @var{dst}. Returns a pointer to 802@var{dst} + strlen(@var{src}). 803 804@end deftypefn 805 806@c stpncpy.c:23 807@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, size_t @var{len}) 808 809Copies the string @var{src} into @var{dst}, copying exactly @var{len} 810and padding with zeros if necessary. If @var{len} < strlen(@var{src}) 811then return @var{dst} + @var{len}, otherwise returns @var{dst} + 812strlen(@var{src}). 813 814@end deftypefn 815 816@c strcasecmp.c:15 817@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2}) 818 819A case-insensitive @code{strcmp}. 820 821@end deftypefn 822 823@c strchr.c:6 824@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c}) 825 826Returns a pointer to the first occurrence of the character @var{c} in 827the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 828null character, the results are undefined. 829 830@end deftypefn 831 832@c strdup.c:3 833@deftypefn Supplemental char* strdup (const char *@var{s}) 834 835Returns a pointer to a copy of @var{s} in memory obtained from 836@code{malloc}, or @code{NULL} if insufficient memory was available. 837 838@end deftypefn 839 840@c strerror.c:670 841@deftypefn Replacement {const char*} strerrno (int @var{errnum}) 842 843Given an error number returned from a system call (typically returned 844in @code{errno}), returns a pointer to a string containing the 845symbolic name of that error number, as found in @code{<errno.h>}. 846 847If the supplied error number is within the valid range of indices for 848symbolic names, but no name is available for the particular error 849number, then returns the string @samp{Error @var{num}}, where @var{num} 850is the error number. 851 852If the supplied error number is not within the range of valid 853indices, then returns @code{NULL}. 854 855The contents of the location pointed to are only guaranteed to be 856valid until the next call to @code{strerrno}. 857 858@end deftypefn 859 860@c strerror.c:602 861@deftypefn Supplemental char* strerror (int @var{errnoval}) 862 863Maps an @code{errno} number to an error message string, the contents 864of which are implementation defined. On systems which have the 865external variables @code{sys_nerr} and @code{sys_errlist}, these 866strings will be the same as the ones used by @code{perror}. 867 868If the supplied error number is within the valid range of indices for 869the @code{sys_errlist}, but no message is available for the particular 870error number, then returns the string @samp{Error @var{num}}, where 871@var{num} is the error number. 872 873If the supplied error number is not a valid index into 874@code{sys_errlist}, returns @code{NULL}. 875 876The returned string is only guaranteed to be valid only until the 877next call to @code{strerror}. 878 879@end deftypefn 880 881@c strncasecmp.c:15 882@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2}) 883 884A case-insensitive @code{strncmp}. 885 886@end deftypefn 887 888@c strncmp.c:6 889@deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) 890 891Compares the first @var{n} bytes of two strings, returning a value as 892@code{strcmp}. 893 894@end deftypefn 895 896@c strrchr.c:6 897@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c}) 898 899Returns a pointer to the last occurrence of the character @var{c} in 900the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 901null character, the results are undefined. 902 903@end deftypefn 904 905@c strsignal.c:388 906@deftypefn Supplemental {const char *} strsignal (int @var{signo}) 907 908Maps an signal number to an signal message string, the contents of 909which are implementation defined. On systems which have the external 910variable @code{sys_siglist}, these strings will be the same as the 911ones used by @code{psignal()}. 912 913If the supplied signal number is within the valid range of indices for 914the @code{sys_siglist}, but no message is available for the particular 915signal number, then returns the string @samp{Signal @var{num}}, where 916@var{num} is the signal number. 917 918If the supplied signal number is not a valid index into 919@code{sys_siglist}, returns @code{NULL}. 920 921The returned string is only guaranteed to be valid only until the next 922call to @code{strsignal}. 923 924@end deftypefn 925 926@c strsignal.c:452 927@deftypefn Extension {const char*} strsigno (int @var{signo}) 928 929Given an signal number, returns a pointer to a string containing the 930symbolic name of that signal number, as found in @code{<signal.h>}. 931 932If the supplied signal number is within the valid range of indices for 933symbolic names, but no name is available for the particular signal 934number, then returns the string @samp{Signal @var{num}}, where 935@var{num} is the signal number. 936 937If the supplied signal number is not within the range of valid 938indices, then returns @code{NULL}. 939 940The contents of the location pointed to are only guaranteed to be 941valid until the next call to @code{strsigno}. 942 943@end deftypefn 944 945@c strstr.c:6 946@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub}) 947 948This function searches for the substring @var{sub} in the string 949@var{string}, not including the terminating null characters. A pointer 950to the first occurrence of @var{sub} is returned, or @code{NULL} if the 951substring is absent. If @var{sub} points to a string with zero 952length, the function returns @var{string}. 953 954@end deftypefn 955 956@c strtod.c:27 957@deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr}) 958 959This ISO C function converts the initial portion of @var{string} to a 960@code{double}. If @var{endptr} is not @code{NULL}, a pointer to the 961character after the last character used in the conversion is stored in 962the location referenced by @var{endptr}. If no conversion is 963performed, zero is returned and the value of @var{string} is stored in 964the location referenced by @var{endptr}. 965 966@end deftypefn 967 968@c strerror.c:730 969@deftypefn Extension int strtoerrno (const char *@var{name}) 970 971Given the symbolic name of a error number (e.g., @code{EACCES}), map it 972to an errno value. If no translation is found, returns 0. 973 974@end deftypefn 975 976@c strtol.c:33 977@deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base}) 978@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base}) 979 980The @code{strtol} function converts the string in @var{string} to a 981long integer value according to the given @var{base}, which must be 982between 2 and 36 inclusive, or be the special value 0. If @var{base} 983is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x} 984to indicate bases 8 and 16, respectively, else default to base 10. 985When the base is 16 (either explicitly or implicitly), a prefix of 986@code{0x} is allowed. The handling of @var{endptr} is as that of 987@code{strtod} above. The @code{strtoul} function is the same, except 988that the converted value is unsigned. 989 990@end deftypefn 991 992@c strsignal.c:507 993@deftypefn Extension int strtosigno (const char *@var{name}) 994 995Given the symbolic name of a signal, map it to a signal number. If no 996translation is found, returns 0. 997 998@end deftypefn 999 1000@c tmpnam.c:3 1001@deftypefn Supplemental char* tmpnam (char *@var{s}) 1002 1003This function attempts to create a name for a temporary file, which 1004will be a valid file name yet not exist when @code{tmpnam} checks for 1005it. @var{s} must point to a buffer of at least @code{L_tmpnam} bytes, 1006or be @code{NULL}. Use of this function creates a security risk, and it must 1007not be used in new projects. Use @code{mkstemp} instead. 1008 1009@end deftypefn 1010 1011@c vasprintf.c:48 1012@deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args}) 1013 1014Like @code{vsprintf}, but instead of passing a pointer to a buffer, 1015you pass a pointer to a pointer. This function will compute the size 1016of the buffer needed, allocate memory with @code{malloc}, and store a 1017pointer to the allocated memory in @code{*@var{resptr}}. The value 1018returned is the same as @code{vsprintf} would return. If memory could 1019not be allocated, minus one is returned and @code{NULL} is stored in 1020@code{*@var{resptr}}. 1021 1022@end deftypefn 1023 1024@c vfork.c:6 1025@deftypefn Supplemental int vfork (void) 1026 1027Emulates @code{vfork} by calling @code{fork} and returning its value. 1028 1029@end deftypefn 1030 1031@c vprintf.c:3 1032@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap}) 1033@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap}) 1034@deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap}) 1035 1036These functions are the same as @code{printf}, @code{fprintf}, and 1037@code{sprintf}, respectively, except that they are called with a 1038@code{va_list} instead of a variable number of arguments. Note that 1039they do not call @code{va_end}; this is the application's 1040responsibility. In @libib{} they are implemented in terms of the 1041nonstandard but common function @code{_doprnt}. 1042 1043@end deftypefn 1044 1045@c vsnprintf.c:28 1046@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap}) 1047 1048This function is similar to vsprintf, but it will print at most 1049@var{n} characters. On error the return value is -1, otherwise it 1050returns the number of characters that would have been printed had 1051@var{n} been sufficiently large, regardless of the actual value of 1052@var{n}. Note some pre-C99 system libraries do not implement this 1053correctly so users cannot generally rely on the return value if the 1054system version of this function is used. 1055 1056@end deftypefn 1057 1058@c waitpid.c:3 1059@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int) 1060 1061This is a wrapper around the @code{wait} function. Any ``special'' 1062values of @var{pid} depend on your implementation of @code{wait}, as 1063does the return value. The third argument is unused in @libib{}. 1064 1065@end deftypefn 1066 1067@c xatexit.c:11 1068@deftypefun int xatexit (void (*@var{fn}) (void)) 1069 1070Behaves as the standard @code{atexit} function, but with no limit on 1071the number of registered functions. Returns 0 on success, or @minus{}1 on 1072failure. If you use @code{xatexit} to register functions, you must use 1073@code{xexit} to terminate your program. 1074 1075@end deftypefun 1076 1077@c xmalloc.c:38 1078@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize}) 1079 1080Allocate memory without fail, and set it to zero. This routine functions 1081like @code{calloc}, but will behave the same as @code{xmalloc} if memory 1082cannot be found. 1083 1084@end deftypefn 1085 1086@c xexit.c:22 1087@deftypefn Replacement void xexit (int @var{code}) 1088 1089Terminates the program. If any functions have been registered with 1090the @code{xatexit} replacement function, they will be called first. 1091Termination is handled via the system's normal @code{exit} call. 1092 1093@end deftypefn 1094 1095@c xmalloc.c:22 1096@deftypefn Replacement void* xmalloc (size_t) 1097 1098Allocate memory without fail. If @code{malloc} fails, this will print 1099a message to @code{stderr} (using the name set by 1100@code{xmalloc_set_program_name}, 1101if any) and then call @code{xexit}. Note that it is therefore safe for 1102a program to contain @code{#define malloc xmalloc} in its source. 1103 1104@end deftypefn 1105 1106@c xmalloc.c:53 1107@deftypefn Replacement void xmalloc_failed (size_t) 1108 1109This function is not meant to be called by client code, and is listed 1110here for completeness only. If any of the allocation routines fail, this 1111function will be called to print an error message and terminate execution. 1112 1113@end deftypefn 1114 1115@c xmalloc.c:46 1116@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name}) 1117 1118You can use this to set the name of the program used by 1119@code{xmalloc_failed} when printing a failure message. 1120 1121@end deftypefn 1122 1123@c xmemdup.c:7 1124@deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size}) 1125 1126Duplicates a region of memory without fail. First, @var{alloc_size} bytes 1127are allocated, then @var{copy_size} bytes from @var{input} are copied into 1128it, and the new memory is returned. If fewer bytes are copied than were 1129allocated, the remaining memory is zeroed. 1130 1131@end deftypefn 1132 1133@c xmalloc.c:32 1134@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size}) 1135Reallocate memory without fail. This routine functions like @code{realloc}, 1136but will behave the same as @code{xmalloc} if memory cannot be found. 1137 1138@end deftypefn 1139 1140@c xstrdup.c:7 1141@deftypefn Replacement char* xstrdup (const char *@var{s}) 1142 1143Duplicates a character string without fail, using @code{xmalloc} to 1144obtain memory. 1145 1146@end deftypefn 1147 1148@c xstrerror.c:7 1149@deftypefn Replacement char* xstrerror (int @var{errnum}) 1150 1151Behaves exactly like the standard @code{strerror} function, but 1152will never return a @code{NULL} pointer. 1153 1154@end deftypefn 1155 1156 1157