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 run 'make stamp-functions' and gather-docs will build a new copy. 5 6@c alloca.c:26 7@deftypefn Replacement void* alloca (size_t @var{size}) 8 9This function allocates memory which will be automatically reclaimed 10after the procedure exits. The @libib{} implementation does not free 11the memory immediately but will do so eventually during subsequent 12calls to this function. Memory is allocated using @code{xmalloc} under 13normal circumstances. 14 15The header file @file{alloca-conf.h} can be used in conjunction with the 16GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make 17available this function. The @code{AC_FUNC_ALLOCA} test requires that 18client code use a block of preprocessor code to be safe (see the Autoconf 19manual for more); this header incorporates that logic and more, including 20the possibility of a GCC built-in function. 21 22@end deftypefn 23 24@c asprintf.c:32 25@deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...) 26 27Like @code{sprintf}, but instead of passing a pointer to a buffer, you 28pass a pointer to a pointer. This function will compute the size of 29the buffer needed, allocate memory with @code{malloc}, and store a 30pointer to the allocated memory in @code{*@var{resptr}}. The value 31returned is the same as @code{sprintf} would return. If memory could 32not be allocated, minus one is returned and @code{NULL} is stored in 33@code{*@var{resptr}}. 34 35@end deftypefn 36 37@c atexit.c:6 38@deftypefn Supplemental int atexit (void (*@var{f})()) 39 40Causes function @var{f} to be called at exit. Returns 0. 41 42@end deftypefn 43 44@c basename.c:6 45@deftypefn Supplemental char* basename (const char *@var{name}) 46 47Returns a pointer to the last component of pathname @var{name}. 48Behavior is undefined if the pathname ends in a directory separator. 49 50@end deftypefn 51 52@c bcmp.c:6 53@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count}) 54 55Compares the first @var{count} bytes of two areas of memory. Returns 56zero if they are the same, nonzero otherwise. Returns zero if 57@var{count} is zero. A nonzero result only indicates a difference, 58it does not indicate any sorting order (say, by having a positive 59result mean @var{x} sorts before @var{y}). 60 61@end deftypefn 62 63@c bcopy.c:3 64@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length}) 65 66Copies @var{length} bytes from memory region @var{in} to region 67@var{out}. The use of @code{bcopy} is deprecated in new programs. 68 69@end deftypefn 70 71@c bsearch.c:33 72@deftypefn Supplemental void* bsearch (const void *@var{key}, @ 73 const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, @ 74 int (*@var{compar})(const void *, const void *)) 75 76Performs a search over an array of @var{nmemb} elements pointed to by 77@var{base} for a member that matches the object pointed to by @var{key}. 78The size of each member is specified by @var{size}. The array contents 79should be sorted in ascending order according to the @var{compar} 80comparison function. This routine should take two arguments pointing to 81the @var{key} and to an array member, in that order, and should return an 82integer less than, equal to, or greater than zero if the @var{key} object 83is respectively less than, matching, or greater than the array member. 84 85@end deftypefn 86 87@c argv.c:135 88@deftypefn Extension char** buildargv (char *@var{sp}) 89 90Given a pointer to a string, parse the string extracting fields 91separated by whitespace and optionally enclosed within either single 92or double quotes (which are stripped off), and build a vector of 93pointers to copies of the string for each field. The input string 94remains unchanged. The last element of the vector is followed by a 95@code{NULL} element. 96 97All of the memory for the pointer array and copies of the string 98is obtained from @code{xmalloc}. All of the memory can be returned to the 99system with the single function call @code{freeargv}, which takes the 100returned result of @code{buildargv}, as it's argument. 101 102Returns a pointer to the argument vector if successful. Returns 103@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient 104memory to complete building the argument vector. 105 106If the input is a null string (as opposed to a @code{NULL} pointer), 107then buildarg returns an argument vector that has one arg, a null 108string. 109 110@end deftypefn 111 112@c bzero.c:6 113@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count}) 114 115Zeros @var{count} bytes starting at @var{mem}. Use of this function 116is deprecated in favor of @code{memset}. 117 118@end deftypefn 119 120@c calloc.c:6 121@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize}) 122 123Uses @code{malloc} to allocate storage for @var{nelem} objects of 124@var{elsize} bytes each, then zeros the memory. 125 126@end deftypefn 127 128@c choose-temp.c:46 129@deftypefn Extension char* choose_temp_base (void) 130 131Return a prefix for temporary file names or @code{NULL} if unable to 132find one. The current directory is chosen if all else fails so the 133program is exited if a temporary directory can't be found (@code{mktemp} 134fails). The buffer for the result is obtained with @code{xmalloc}. 135 136This function is provided for backwards compatibility only. Its use is 137not recommended. 138 139@end deftypefn 140 141@c make-temp-file.c:96 142@deftypefn Replacement char* choose_tmpdir () 143 144Returns a pointer to a directory path suitable for creating temporary 145files in. 146 147@end deftypefn 148 149@c clock.c:27 150@deftypefn Supplemental long clock (void) 151 152Returns an approximation of the CPU time used by the process as a 153@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the 154number of seconds used. 155 156@end deftypefn 157 158@c concat.c:24 159@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @ 160 @dots{}, @code{NULL}) 161 162Concatenate zero or more of strings and return the result in freshly 163@code{xmalloc}ed memory. Returns @code{NULL} if insufficient memory is 164available. The argument list is terminated by the first @code{NULL} 165pointer encountered. Pointers to empty strings are ignored. 166 167@end deftypefn 168 169@c argv.c:470 170@deftypefn Extension int countargv (char **@var{argv}) 171 172Return the number of elements in @var{argv}. 173Returns zero if @var{argv} is NULL. 174 175@end deftypefn 176 177@c crc32.c:141 178@deftypefn Extension {unsigned int} crc32 (const unsigned char *@var{buf}, @ 179 int @var{len}, unsigned int @var{init}) 180 181Compute the 32-bit CRC of @var{buf} which has length @var{len}. The 182starting value is @var{init}; this may be used to compute the CRC of 183data split across multiple buffers by passing the return value of each 184call as the @var{init} parameter of the next. 185 186This is intended to match the CRC used by the @command{gdb} remote 187protocol for the @samp{qCRC} command. In order to get the same 188results as gdb for a block of data, you must pass the first CRC 189parameter as @code{0xffffffff}. 190 191This CRC can be specified as: 192 193 Width : 32 194 Poly : 0x04c11db7 195 Init : parameter, typically 0xffffffff 196 RefIn : false 197 RefOut : false 198 XorOut : 0 199 200This differs from the "standard" CRC-32 algorithm in that the values 201are not reflected, and there is no final XOR value. These differences 202make it easy to compose the values of multiple blocks. 203 204@end deftypefn 205 206@c argv.c:52 207@deftypefn Extension char** dupargv (char **@var{vector}) 208 209Duplicate an argument vector. Simply scans through @var{vector}, 210duplicating each argument until the terminating @code{NULL} is found. 211Returns a pointer to the argument vector if successful. Returns 212@code{NULL} if there is insufficient memory to complete building the 213argument vector. 214 215@end deftypefn 216 217@c strerror.c:567 218@deftypefn Extension int errno_max (void) 219 220Returns the maximum @code{errno} value for which a corresponding 221symbolic name or message is available. Note that in the case where we 222use the @code{sys_errlist} supplied by the system, it is possible for 223there to be more symbolic names than messages, or vice versa. In 224fact, the manual page for @code{perror(3C)} explicitly warns that one 225should check the size of the table (@code{sys_nerr}) before indexing 226it, since new error codes may be added to the system before they are 227added to the table. Thus @code{sys_nerr} might be smaller than value 228implied by the largest @code{errno} value defined in @code{<errno.h>}. 229 230We return the maximum value that can be used to obtain a meaningful 231symbolic name or message. 232 233@end deftypefn 234 235@c argv.c:341 236@deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp}) 237 238The @var{argcp} and @code{argvp} arguments are pointers to the usual 239@code{argc} and @code{argv} arguments to @code{main}. This function 240looks for arguments that begin with the character @samp{@@}. Any such 241arguments are interpreted as ``response files''. The contents of the 242response file are interpreted as additional command line options. In 243particular, the file is separated into whitespace-separated strings; 244each such string is taken as a command-line option. The new options 245are inserted in place of the option naming the response file, and 246@code{*argcp} and @code{*argvp} will be updated. If the value of 247@code{*argvp} is modified by this function, then the new value has 248been dynamically allocated and can be deallocated by the caller with 249@code{freeargv}. However, most callers will simply call 250@code{expandargv} near the beginning of @code{main} and allow the 251operating system to free the memory when the program exits. 252 253@end deftypefn 254 255@c fdmatch.c:23 256@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2}) 257 258Check to see if two open file descriptors refer to the same file. 259This is useful, for example, when we have an open file descriptor for 260an unnamed file, and the name of a file that we believe to correspond 261to that fd. This can happen when we are exec'd with an already open 262file (@code{stdout} for example) or from the SVR4 @file{/proc} calls 263that return open file descriptors for mapped address spaces. All we 264have to do is open the file by name and check the two file descriptors 265for a match, which is done by comparing major and minor device numbers 266and inode numbers. 267 268@end deftypefn 269 270@c fopen_unlocked.c:49 271@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, @ 272 const char * @var{mode}) 273 274Opens and returns a @code{FILE} pointer via @code{fdopen}. If the 275operating system supports it, ensure that the stream is setup to avoid 276any multi-threaded locking. Otherwise return the @code{FILE} pointer 277unchanged. 278 279@end deftypefn 280 281@c ffs.c:3 282@deftypefn Supplemental int ffs (int @var{valu}) 283 284Find the first (least significant) bit set in @var{valu}. Bits are 285numbered from right to left, starting with bit 1 (corresponding to the 286value 1). If @var{valu} is zero, zero is returned. 287 288@end deftypefn 289 290@c filename_cmp.c:32 291@deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2}) 292 293Return zero if the two file names @var{s1} and @var{s2} are equivalent. 294If not equivalent, the returned value is similar to what @code{strcmp} 295would return. In other words, it returns a negative value if @var{s1} 296is less than @var{s2}, or a positive value if @var{s2} is greater than 297@var{s2}. 298 299This function does not normalize file names. As a result, this function 300will treat filenames that are spelled differently as different even in 301the case when the two filenames point to the same underlying file. 302However, it does handle the fact that on DOS-like file systems, forward 303and backward slashes are equal. 304 305@end deftypefn 306 307@c filename_cmp.c:178 308@deftypefn Extension int filename_eq (const void *@var{s1}, const void *@var{s2}) 309 310Return non-zero if file names @var{s1} and @var{s2} are equivalent. 311This function is for use with hashtab.c hash tables. 312 313@end deftypefn 314 315@c filename_cmp.c:147 316@deftypefn Extension hashval_t filename_hash (const void *@var{s}) 317 318Return the hash value for file name @var{s} that will be compared 319using filename_cmp. 320This function is for use with hashtab.c hash tables. 321 322@end deftypefn 323 324@c filename_cmp.c:89 325@deftypefn Extension int filename_ncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) 326 327Return zero if the two file names @var{s1} and @var{s2} are equivalent 328in range @var{n}. 329If not equivalent, the returned value is similar to what @code{strncmp} 330would return. In other words, it returns a negative value if @var{s1} 331is less than @var{s2}, or a positive value if @var{s2} is greater than 332@var{s2}. 333 334This function does not normalize file names. As a result, this function 335will treat filenames that are spelled differently as different even in 336the case when the two filenames point to the same underlying file. 337However, it does handle the fact that on DOS-like file systems, forward 338and backward slashes are equal. 339 340@end deftypefn 341 342@c fnmatch.txh:1 343@deftypefn Replacement int fnmatch (const char *@var{pattern}, @ 344 const char *@var{string}, int @var{flags}) 345 346Matches @var{string} against @var{pattern}, returning zero if it 347matches, @code{FNM_NOMATCH} if not. @var{pattern} may contain the 348wildcards @code{?} to match any one character, @code{*} to match any 349zero or more characters, or a set of alternate characters in square 350brackets, like @samp{[a-gt8]}, which match one character (@code{a} 351through @code{g}, or @code{t}, or @code{8}, in this example) if that one 352character is in the set. A set may be inverted (i.e., match anything 353except what's in the set) by giving @code{^} or @code{!} as the first 354character in the set. To include those characters in the set, list them 355as anything other than the first character of the set. To include a 356dash in the set, list it last in the set. A backslash character makes 357the following character not special, so for example you could match 358against a literal asterisk with @samp{\*}. To match a literal 359backslash, use @samp{\\}. 360 361@code{flags} controls various aspects of the matching process, and is a 362boolean OR of zero or more of the following values (defined in 363@code{<fnmatch.h>}): 364 365@table @code 366 367@item FNM_PATHNAME 368@itemx FNM_FILE_NAME 369@var{string} is assumed to be a path name. No wildcard will ever match 370@code{/}. 371 372@item FNM_NOESCAPE 373Do not interpret backslashes as quoting the following special character. 374 375@item FNM_PERIOD 376A leading period (at the beginning of @var{string}, or if 377@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or 378@code{?} but must be matched explicitly. 379 380@item FNM_LEADING_DIR 381Means that @var{string} also matches @var{pattern} if some initial part 382of @var{string} matches, and is followed by @code{/} and zero or more 383characters. For example, @samp{foo*} would match either @samp{foobar} 384or @samp{foobar/grill}. 385 386@item FNM_CASEFOLD 387Ignores case when performing the comparison. 388 389@end table 390 391@end deftypefn 392 393@c fopen_unlocked.c:39 394@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, @ 395 const char * @var{mode}) 396 397Opens and returns a @code{FILE} pointer via @code{fopen}. If the 398operating system supports it, ensure that the stream is setup to avoid 399any multi-threaded locking. Otherwise return the @code{FILE} pointer 400unchanged. 401 402@end deftypefn 403 404@c argv.c:90 405@deftypefn Extension void freeargv (char **@var{vector}) 406 407Free an argument vector that was built using @code{buildargv}. Simply 408scans through @var{vector}, freeing the memory for each argument until 409the terminating @code{NULL} is found, and then frees @var{vector} 410itself. 411 412@end deftypefn 413 414@c fopen_unlocked.c:59 415@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, @ 416 const char * @var{mode}, FILE * @var{stream}) 417 418Opens and returns a @code{FILE} pointer via @code{freopen}. If the 419operating system supports it, ensure that the stream is setup to avoid 420any multi-threaded locking. Otherwise return the @code{FILE} pointer 421unchanged. 422 423@end deftypefn 424 425@c getruntime.c:82 426@deftypefn Replacement long get_run_time (void) 427 428Returns the time used so far, in microseconds. If possible, this is 429the time used by this process, else it is the elapsed time since the 430process started. 431 432@end deftypefn 433 434@c getcwd.c:6 435@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len}) 436 437Copy the absolute pathname for the current working directory into 438@var{pathname}, which is assumed to point to a buffer of at least 439@var{len} bytes, and return a pointer to the buffer. If the current 440directory's path doesn't fit in @var{len} characters, the result is 441@code{NULL} and @code{errno} is set. If @var{pathname} is a null pointer, 442@code{getcwd} will obtain @var{len} bytes of space using 443@code{malloc}. 444 445@end deftypefn 446 447@c getpagesize.c:5 448@deftypefn Supplemental int getpagesize (void) 449 450Returns the number of bytes in a page of memory. This is the 451granularity of many of the system memory management routines. No 452guarantee is made as to whether or not it is the same as the basic 453memory management hardware page size. 454 455@end deftypefn 456 457@c getpwd.c:5 458@deftypefn Supplemental char* getpwd (void) 459 460Returns the current working directory. This implementation caches the 461result on the assumption that the process will not call @code{chdir} 462between calls to @code{getpwd}. 463 464@end deftypefn 465 466@c gettimeofday.c:12 467@deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz}) 468 469Writes the current time to @var{tp}. This implementation requires 470that @var{tz} be NULL. Returns 0 on success, -1 on failure. 471 472@end deftypefn 473 474@c hex.c:33 475@deftypefn Extension void hex_init (void) 476 477Initializes the array mapping the current character set to 478corresponding hex values. This function must be called before any 479call to @code{hex_p} or @code{hex_value}. If you fail to call it, a 480default ASCII-based table will normally be used on ASCII systems. 481 482@end deftypefn 483 484@c hex.c:42 485@deftypefn Extension int hex_p (int @var{c}) 486 487Evaluates to non-zero if the given character is a valid hex character, 488or zero if it is not. Note that the value you pass will be cast to 489@code{unsigned char} within the macro. 490 491@end deftypefn 492 493@c hex.c:50 494@deftypefn Extension {unsigned int} hex_value (int @var{c}) 495 496Returns the numeric equivalent of the given character when interpreted 497as a hexadecimal digit. The result is undefined if you pass an 498invalid hex digit. Note that the value you pass will be cast to 499@code{unsigned char} within the macro. 500 501The @code{hex_value} macro returns @code{unsigned int}, rather than 502signed @code{int}, to make it easier to use in parsing addresses from 503hex dump files: a signed @code{int} would be sign-extended when 504converted to a wider unsigned type --- like @code{bfd_vma}, on some 505systems. 506 507@end deftypefn 508 509@c safe-ctype.c:25 510@defvr Extension HOST_CHARSET 511This macro indicates the basic character set and encoding used by the 512host: more precisely, the encoding used for character constants in 513preprocessor @samp{#if} statements (the C "execution character set"). 514It is defined by @file{safe-ctype.h}, and will be an integer constant 515with one of the following values: 516 517@ftable @code 518@item HOST_CHARSET_UNKNOWN 519The host character set is unknown - that is, not one of the next two 520possibilities. 521 522@item HOST_CHARSET_ASCII 523The host character set is ASCII. 524 525@item HOST_CHARSET_EBCDIC 526The host character set is some variant of EBCDIC. (Only one of the 527nineteen EBCDIC varying characters is tested; exercise caution.) 528@end ftable 529@end defvr 530 531@c hashtab.c:336 532@deftypefn Supplemental htab_t htab_create_typed_alloc (size_t @var{size}, @ 533htab_hash @var{hash_f}, htab_eq @var{eq_f}, htab_del @var{del_f}, @ 534htab_alloc @var{alloc_tab_f}, htab_alloc @var{alloc_f}, @ 535htab_free @var{free_f}) 536 537This function creates a hash table that uses two different allocators 538@var{alloc_tab_f} and @var{alloc_f} to use for allocating the table itself 539and its entries respectively. This is useful when variables of different 540types need to be allocated with different allocators. 541 542The created hash table is slightly larger than @var{size} and it is 543initially empty (all the hash table entries are @code{HTAB_EMPTY_ENTRY}). 544The function returns the created hash table, or @code{NULL} if memory 545allocation fails. 546 547@end deftypefn 548 549@c index.c:5 550@deftypefn Supplemental char* index (char *@var{s}, int @var{c}) 551 552Returns a pointer to the first occurrence of the character @var{c} in 553the string @var{s}, or @code{NULL} if not found. The use of @code{index} is 554deprecated in new programs in favor of @code{strchr}. 555 556@end deftypefn 557 558@c insque.c:6 559@deftypefn Supplemental void insque (struct qelem *@var{elem}, @ 560 struct qelem *@var{pred}) 561@deftypefnx Supplemental void remque (struct qelem *@var{elem}) 562 563Routines to manipulate queues built from doubly linked lists. The 564@code{insque} routine inserts @var{elem} in the queue immediately 565after @var{pred}. The @code{remque} routine removes @var{elem} from 566its containing queue. These routines expect to be passed pointers to 567structures which have as their first members a forward pointer and a 568back pointer, like this prototype (although no prototype is provided): 569 570@example 571struct qelem @{ 572 struct qelem *q_forw; 573 struct qelem *q_back; 574 char q_data[]; 575@}; 576@end example 577 578@end deftypefn 579 580@c safe-ctype.c:46 581@deffn Extension ISALPHA (@var{c}) 582@deffnx Extension ISALNUM (@var{c}) 583@deffnx Extension ISBLANK (@var{c}) 584@deffnx Extension ISCNTRL (@var{c}) 585@deffnx Extension ISDIGIT (@var{c}) 586@deffnx Extension ISGRAPH (@var{c}) 587@deffnx Extension ISLOWER (@var{c}) 588@deffnx Extension ISPRINT (@var{c}) 589@deffnx Extension ISPUNCT (@var{c}) 590@deffnx Extension ISSPACE (@var{c}) 591@deffnx Extension ISUPPER (@var{c}) 592@deffnx Extension ISXDIGIT (@var{c}) 593 594These twelve macros are defined by @file{safe-ctype.h}. Each has the 595same meaning as the corresponding macro (with name in lowercase) 596defined by the standard header @file{ctype.h}. For example, 597@code{ISALPHA} returns true for alphabetic characters and false for 598others. However, there are two differences between these macros and 599those provided by @file{ctype.h}: 600 601@itemize @bullet 602@item These macros are guaranteed to have well-defined behavior for all 603values representable by @code{signed char} and @code{unsigned char}, and 604for @code{EOF}. 605 606@item These macros ignore the current locale; they are true for these 607fixed sets of characters: 608@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada} 609@item @code{ALPHA} @tab @kbd{A-Za-z} 610@item @code{ALNUM} @tab @kbd{A-Za-z0-9} 611@item @code{BLANK} @tab @kbd{space tab} 612@item @code{CNTRL} @tab @code{!PRINT} 613@item @code{DIGIT} @tab @kbd{0-9} 614@item @code{GRAPH} @tab @code{ALNUM || PUNCT} 615@item @code{LOWER} @tab @kbd{a-z} 616@item @code{PRINT} @tab @code{GRAPH ||} @kbd{space} 617@item @code{PUNCT} @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?} 618@item @code{SPACE} @tab @kbd{space tab \n \r \f \v} 619@item @code{UPPER} @tab @kbd{A-Z} 620@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f} 621@end multitable 622 623Note that, if the host character set is ASCII or a superset thereof, 624all these macros will return false for all values of @code{char} outside 625the range of 7-bit ASCII. In particular, both ISPRINT and ISCNTRL return 626false for characters with numeric values from 128 to 255. 627@end itemize 628@end deffn 629 630@c safe-ctype.c:95 631@deffn Extension ISIDNUM (@var{c}) 632@deffnx Extension ISIDST (@var{c}) 633@deffnx Extension IS_VSPACE (@var{c}) 634@deffnx Extension IS_NVSPACE (@var{c}) 635@deffnx Extension IS_SPACE_OR_NUL (@var{c}) 636@deffnx Extension IS_ISOBASIC (@var{c}) 637These six macros are defined by @file{safe-ctype.h} and provide 638additional character classes which are useful when doing lexical 639analysis of C or similar languages. They are true for the following 640sets of characters: 641 642@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada} 643@item @code{IDNUM} @tab @kbd{A-Za-z0-9_} 644@item @code{IDST} @tab @kbd{A-Za-z_} 645@item @code{VSPACE} @tab @kbd{\r \n} 646@item @code{NVSPACE} @tab @kbd{space tab \f \v \0} 647@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE} 648@item @code{ISOBASIC} @tab @code{VSPACE || NVSPACE || PRINT} 649@end multitable 650@end deffn 651 652@c lbasename.c:23 653@deftypefn Replacement {const char*} lbasename (const char *@var{name}) 654 655Given a pointer to a string containing a typical pathname 656(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the 657last component of the pathname (@samp{ls.c} in this case). The 658returned pointer is guaranteed to lie within the original 659string. This latter fact is not true of many vendor C 660libraries, which return special strings or modify the passed 661strings for particular input. 662 663In particular, the empty string returns the same empty string, 664and a path ending in @code{/} returns the empty string after it. 665 666@end deftypefn 667 668@c lrealpath.c:25 669@deftypefn Replacement {const char*} lrealpath (const char *@var{name}) 670 671Given a pointer to a string containing a pathname, returns a canonical 672version of the filename. Symlinks will be resolved, and ``.'' and ``..'' 673components will be simplified. The returned value will be allocated using 674@code{malloc}, or @code{NULL} will be returned on a memory allocation error. 675 676@end deftypefn 677 678@c make-relative-prefix.c:24 679@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, @ 680 const char *@var{bin_prefix}, const char *@var{prefix}) 681 682Given three paths @var{progname}, @var{bin_prefix}, @var{prefix}, 683return the path that is in the same position relative to 684@var{progname}'s directory as @var{prefix} is relative to 685@var{bin_prefix}. That is, a string starting with the directory 686portion of @var{progname}, followed by a relative pathname of the 687difference between @var{bin_prefix} and @var{prefix}. 688 689If @var{progname} does not contain any directory separators, 690@code{make_relative_prefix} will search @env{PATH} to find a program 691named @var{progname}. Also, if @var{progname} is a symbolic link, 692the symbolic link will be resolved. 693 694For example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta}, 695@var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is 696@code{/red/green/blue/gcc}, then this function will return 697@code{/red/green/blue/../../omega/}. 698 699The return value is normally allocated via @code{malloc}. If no 700relative prefix can be found, return @code{NULL}. 701 702@end deftypefn 703 704@c make-temp-file.c:174 705@deftypefn Replacement char* make_temp_file (const char *@var{suffix}) 706 707Return a temporary file name (as a string) or @code{NULL} if unable to 708create one. @var{suffix} is a suffix to append to the file name. The 709string is @code{malloc}ed, and the temporary file has been created. 710 711@end deftypefn 712 713@c memchr.c:3 714@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, @ 715 size_t @var{n}) 716 717This function searches memory starting at @code{*@var{s}} for the 718character @var{c}. The search only ends with the first occurrence of 719@var{c}, or after @var{length} characters; in particular, a null 720character does not terminate the search. If the character @var{c} is 721found within @var{length} characters of @code{*@var{s}}, a pointer 722to the character is returned. If @var{c} is not found, then @code{NULL} is 723returned. 724 725@end deftypefn 726 727@c memcmp.c:6 728@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, @ 729 size_t @var{count}) 730 731Compares the first @var{count} bytes of two areas of memory. Returns 732zero if they are the same, a value less than zero if @var{x} is 733lexically less than @var{y}, or a value greater than zero if @var{x} 734is lexically greater than @var{y}. Note that lexical order is determined 735as if comparing unsigned char arrays. 736 737@end deftypefn 738 739@c memcpy.c:6 740@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, @ 741 size_t @var{length}) 742 743Copies @var{length} bytes from memory region @var{in} to region 744@var{out}. Returns a pointer to @var{out}. 745 746@end deftypefn 747 748@c memmem.c:20 749@deftypefn Supplemental void* memmem (const void *@var{haystack}, @ 750 size_t @var{haystack_len} const void *@var{needle}, size_t @var{needle_len}) 751 752Returns a pointer to the first occurrence of @var{needle} (length 753@var{needle_len}) in @var{haystack} (length @var{haystack_len}). 754Returns @code{NULL} if not found. 755 756@end deftypefn 757 758@c memmove.c:6 759@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, @ 760 size_t @var{count}) 761 762Copies @var{count} bytes from memory area @var{from} to memory area 763@var{to}, returning a pointer to @var{to}. 764 765@end deftypefn 766 767@c mempcpy.c:23 768@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, @ 769 size_t @var{length}) 770 771Copies @var{length} bytes from memory region @var{in} to region 772@var{out}. Returns a pointer to @var{out} + @var{length}. 773 774@end deftypefn 775 776@c memset.c:6 777@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, @ 778 size_t @var{count}) 779 780Sets the first @var{count} bytes of @var{s} to the constant byte 781@var{c}, returning a pointer to @var{s}. 782 783@end deftypefn 784 785@c mkstemps.c:58 786@deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len}) 787 788Generate a unique temporary file name from @var{pattern}. 789@var{pattern} has the form: 790 791@example 792 @var{path}/ccXXXXXX@var{suffix} 793@end example 794 795@var{suffix_len} tells us how long @var{suffix} is (it can be zero 796length). The last six characters of @var{pattern} before @var{suffix} 797must be @samp{XXXXXX}; they are replaced with a string that makes the 798filename unique. Returns a file descriptor open on the file for 799reading and writing. 800 801@end deftypefn 802 803@c pexecute.txh:278 804@deftypefn Extension void pex_free (struct pex_obj @var{obj}) 805 806Clean up and free all data associated with @var{obj}. If you have not 807yet called @code{pex_get_times} or @code{pex_get_status}, this will 808try to kill the subprocesses. 809 810@end deftypefn 811 812@c pexecute.txh:251 813@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, @ 814 int @var{count}, int *@var{vector}) 815 816Returns the exit status of all programs run using @var{obj}. 817@var{count} is the number of results expected. The results will be 818placed into @var{vector}. The results are in the order of the calls 819to @code{pex_run}. Returns 0 on error, 1 on success. 820 821@end deftypefn 822 823@c pexecute.txh:261 824@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, @ 825 int @var{count}, struct pex_time *@var{vector}) 826 827Returns the process execution times of all programs run using 828@var{obj}. @var{count} is the number of results expected. The 829results will be placed into @var{vector}. The results are in the 830order of the calls to @code{pex_run}. Returns 0 on error, 1 on 831success. 832 833@code{struct pex_time} has the following fields of the type 834@code{unsigned long}: @code{user_seconds}, 835@code{user_microseconds}, @code{system_seconds}, 836@code{system_microseconds}. On systems which do not support reporting 837process times, all the fields will be set to @code{0}. 838 839@end deftypefn 840 841@c pexecute.txh:2 842@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, @ 843 const char *@var{pname}, const char *@var{tempbase}) 844 845Prepare to execute one or more programs, with standard output of each 846program fed to standard input of the next. This is a system 847independent interface to execute a pipeline. 848 849@var{flags} is a bitwise combination of the following: 850 851@table @code 852 853@vindex PEX_RECORD_TIMES 854@item PEX_RECORD_TIMES 855Record subprocess times if possible. 856 857@vindex PEX_USE_PIPES 858@item PEX_USE_PIPES 859Use pipes for communication between processes, if possible. 860 861@vindex PEX_SAVE_TEMPS 862@item PEX_SAVE_TEMPS 863Don't delete temporary files used for communication between 864processes. 865 866@end table 867 868@var{pname} is the name of program to be executed, used in error 869messages. @var{tempbase} is a base name to use for any required 870temporary files; it may be @code{NULL} to use a randomly chosen name. 871 872@end deftypefn 873 874@c pexecute.txh:161 875@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, @ 876 int @var{flags}, const char *@var{in_name}) 877 878Return a stream for a temporary file to pass to the first program in 879the pipeline as input. 880 881The name of the input file is chosen according to the same rules 882@code{pex_run} uses to choose output file names, based on 883@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}. 884 885Don't call @code{fclose} on the returned stream; the first call to 886@code{pex_run} closes it automatically. 887 888If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in 889binary mode; otherwise, open it in the default mode. Including 890@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix. 891@end deftypefn 892 893@c pexecute.txh:179 894@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, @ 895 int @var{binary}) 896 897Return a stream @var{fp} for a pipe connected to the standard input of 898the first program in the pipeline; @var{fp} is opened for writing. 899You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call 900that returned @var{obj}. 901 902You must close @var{fp} using @code{fclose} yourself when you have 903finished writing data to the pipeline. 904 905The file descriptor underlying @var{fp} is marked not to be inherited 906by child processes. 907 908On systems that do not support pipes, this function returns 909@code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would 910like to write code that is portable to all systems the @code{pex} 911functions support, consider using @code{pex_input_file} instead. 912 913There are two opportunities for deadlock using 914@code{pex_input_pipe}: 915 916@itemize @bullet 917@item 918Most systems' pipes can buffer only a fixed amount of data; a process 919that writes to a full pipe blocks. Thus, if you write to @file{fp} 920before starting the first process, you run the risk of blocking when 921there is no child process yet to read the data and allow you to 922continue. @code{pex_input_pipe} makes no promises about the 923size of the pipe's buffer, so if you need to write any data at all 924before starting the first process in the pipeline, consider using 925@code{pex_input_file} instead. 926 927@item 928Using @code{pex_input_pipe} and @code{pex_read_output} together 929may also cause deadlock. If the output pipe fills up, so that each 930program in the pipeline is waiting for the next to read more data, and 931you fill the input pipe by writing more data to @var{fp}, then there 932is no way to make progress: the only process that could read data from 933the output pipe is you, but you are blocked on the input pipe. 934 935@end itemize 936 937@end deftypefn 938 939@c pexecute.txh:286 940@deftypefn Extension {const char *} pex_one (int @var{flags}, @ 941 const char *@var{executable}, char * const *@var{argv}, @ 942 const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, @ 943 int *@var{status}, int *@var{err}) 944 945An interface to permit the easy execution of a 946single program. The return value and most of the parameters are as 947for a call to @code{pex_run}. @var{flags} is restricted to a 948combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and 949@code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if 950@code{PEX_LAST} were set. On a successful return, @code{*@var{status}} will 951be set to the exit status of the program. 952 953@end deftypefn 954 955@c pexecute.txh:237 956@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, @ 957 int @var{binary}) 958 959Returns a @code{FILE} pointer which may be used to read the standard 960error of the last program in the pipeline. When this is used, 961@code{PEX_LAST} should not be used in a call to @code{pex_run}. After 962this is called, @code{pex_run} may no longer be called with the same 963@var{obj}. @var{binary} should be non-zero if the file should be 964opened in binary mode. Don't call @code{fclose} on the returned file; 965it will be closed by @code{pex_free}. 966 967@end deftypefn 968 969@c pexecute.txh:224 970@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, @ 971 int @var{binary}) 972 973Returns a @code{FILE} pointer which may be used to read the standard 974output of the last program in the pipeline. When this is used, 975@code{PEX_LAST} should not be used in a call to @code{pex_run}. After 976this is called, @code{pex_run} may no longer be called with the same 977@var{obj}. @var{binary} should be non-zero if the file should be 978opened in binary mode. Don't call @code{fclose} on the returned file; 979it will be closed by @code{pex_free}. 980 981@end deftypefn 982 983@c pexecute.txh:34 984@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, @ 985 int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ 986 const char *@var{outname}, const char *@var{errname}, int *@var{err}) 987 988Execute one program in a pipeline. On success this returns 989@code{NULL}. On failure it returns an error message, a statically 990allocated string. 991 992@var{obj} is returned by a previous call to @code{pex_init}. 993 994@var{flags} is a bitwise combination of the following: 995 996@table @code 997 998@vindex PEX_LAST 999@item PEX_LAST 1000This must be set on the last program in the pipeline. In particular, 1001it should be set when executing a single program. The standard output 1002of the program will be sent to @var{outname}, or, if @var{outname} is 1003@code{NULL}, to the standard output of the calling program. Do @emph{not} 1004set this bit if you want to call @code{pex_read_output} 1005(described below). After a call to @code{pex_run} with this bit set, 1006@var{pex_run} may no longer be called with the same @var{obj}. 1007 1008@vindex PEX_SEARCH 1009@item PEX_SEARCH 1010Search for the program using the user's executable search path. 1011 1012@vindex PEX_SUFFIX 1013@item PEX_SUFFIX 1014@var{outname} is a suffix. See the description of @var{outname}, 1015below. 1016 1017@vindex PEX_STDERR_TO_STDOUT 1018@item PEX_STDERR_TO_STDOUT 1019Send the program's standard error to standard output, if possible. 1020 1021@vindex PEX_BINARY_INPUT 1022@vindex PEX_BINARY_OUTPUT 1023@vindex PEX_BINARY_ERROR 1024@item PEX_BINARY_INPUT 1025@itemx PEX_BINARY_OUTPUT 1026@itemx PEX_BINARY_ERROR 1027The standard input (output or error) of the program should be read (written) in 1028binary mode rather than text mode. These flags are ignored on systems 1029which do not distinguish binary mode and text mode, such as Unix. For 1030proper behavior these flags should match appropriately---a call to 1031@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a 1032call using @code{PEX_BINARY_INPUT}. 1033 1034@vindex PEX_STDERR_TO_PIPE 1035@item PEX_STDERR_TO_PIPE 1036Send the program's standard error to a pipe, if possible. This flag 1037cannot be specified together with @code{PEX_STDERR_TO_STDOUT}. This 1038flag can be specified only on the last program in pipeline. 1039 1040@end table 1041 1042@var{executable} is the program to execute. @var{argv} is the set of 1043arguments to pass to the program; normally @code{@var{argv}[0]} will 1044be a copy of @var{executable}. 1045 1046@var{outname} is used to set the name of the file to use for standard 1047output. There are two cases in which no output file will be used: 1048 1049@enumerate 1050@item 1051if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} 1052was set in the call to @code{pex_init}, and the system supports pipes 1053 1054@item 1055if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is 1056@code{NULL} 1057@end enumerate 1058 1059@noindent 1060Otherwise the code will use a file to hold standard 1061output. If @code{PEX_LAST} is not set, this file is considered to be 1062a temporary file, and it will be removed when no longer needed, unless 1063@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. 1064 1065There are two cases to consider when setting the name of the file to 1066hold standard output. 1067 1068@enumerate 1069@item 1070@code{PEX_SUFFIX} is set in @var{flags}. In this case 1071@var{outname} may not be @code{NULL}. If the @var{tempbase} parameter 1072to @code{pex_init} was not @code{NULL}, then the output file name is 1073the concatenation of @var{tempbase} and @var{outname}. If 1074@var{tempbase} was @code{NULL}, then the output file name is a random 1075file name ending in @var{outname}. 1076 1077@item 1078@code{PEX_SUFFIX} was not set in @var{flags}. In this 1079case, if @var{outname} is not @code{NULL}, it is used as the output 1080file name. If @var{outname} is @code{NULL}, and @var{tempbase} was 1081not NULL, the output file name is randomly chosen using 1082@var{tempbase}. Otherwise the output file name is chosen completely 1083at random. 1084@end enumerate 1085 1086@var{errname} is the file name to use for standard error output. If 1087it is @code{NULL}, standard error is the same as the caller's. 1088Otherwise, standard error is written to the named file. 1089 1090On an error return, the code sets @code{*@var{err}} to an @code{errno} 1091value, or to 0 if there is no relevant @code{errno}. 1092 1093@end deftypefn 1094 1095@c pexecute.txh:145 1096@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, @ 1097 int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ 1098 char * const *@var{env}, int @var{env_size}, const char *@var{outname}, @ 1099 const char *@var{errname}, int *@var{err}) 1100 1101Execute one program in a pipeline, permitting the environment for the 1102program to be specified. Behaviour and parameters not listed below are 1103as for @code{pex_run}. 1104 1105@var{env} is the environment for the child process, specified as an array of 1106character pointers. Each element of the array should point to a string of the 1107form @code{VAR=VALUE}, with the exception of the last element that must be 1108@code{NULL}. 1109 1110@end deftypefn 1111 1112@c pexecute.txh:301 1113@deftypefn Extension int pexecute (const char *@var{program}, @ 1114 char * const *@var{argv}, const char *@var{this_pname}, @ 1115 const char *@var{temp_base}, char **@var{errmsg_fmt}, @ 1116 char **@var{errmsg_arg}, int @var{flags}) 1117 1118This is the old interface to execute one or more programs. It is 1119still supported for compatibility purposes, but is no longer 1120documented. 1121 1122@end deftypefn 1123 1124@c strsignal.c:541 1125@deftypefn Supplemental void psignal (int @var{signo}, char *@var{message}) 1126 1127Print @var{message} to the standard error, followed by a colon, 1128followed by the description of the signal specified by @var{signo}, 1129followed by a newline. 1130 1131@end deftypefn 1132 1133@c putenv.c:21 1134@deftypefn Supplemental int putenv (const char *@var{string}) 1135 1136Uses @code{setenv} or @code{unsetenv} to put @var{string} into 1137the environment or remove it. If @var{string} is of the form 1138@samp{name=value} the string is added; if no @samp{=} is present the 1139name is unset/removed. 1140 1141@end deftypefn 1142 1143@c pexecute.txh:312 1144@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) 1145 1146Another part of the old execution interface. 1147 1148@end deftypefn 1149 1150@c random.c:39 1151@deftypefn Supplement {long int} random (void) 1152@deftypefnx Supplement void srandom (unsigned int @var{seed}) 1153@deftypefnx Supplement void* initstate (unsigned int @var{seed}, @ 1154 void *@var{arg_state}, unsigned long @var{n}) 1155@deftypefnx Supplement void* setstate (void *@var{arg_state}) 1156 1157Random number functions. @code{random} returns a random number in the 1158range 0 to @code{LONG_MAX}. @code{srandom} initializes the random 1159number generator to some starting point determined by @var{seed} 1160(else, the values returned by @code{random} are always the same for each 1161run of the program). @code{initstate} and @code{setstate} allow fine-grained 1162control over the state of the random number generator. 1163 1164@end deftypefn 1165 1166@c concat.c:174 1167@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @ 1168 @dots{}, @code{NULL}) 1169 1170Same as @code{concat}, except that if @var{optr} is not @code{NULL} it 1171is freed after the string is created. This is intended to be useful 1172when you're extending an existing string or building up a string in a 1173loop: 1174 1175@example 1176 str = reconcat (str, "pre-", str, NULL); 1177@end example 1178 1179@end deftypefn 1180 1181@c rename.c:6 1182@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new}) 1183 1184Renames a file from @var{old} to @var{new}. If @var{new} already 1185exists, it is removed. 1186 1187@end deftypefn 1188 1189@c rindex.c:5 1190@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c}) 1191 1192Returns a pointer to the last occurrence of the character @var{c} in 1193the string @var{s}, or @code{NULL} if not found. The use of @code{rindex} is 1194deprecated in new programs in favor of @code{strrchr}. 1195 1196@end deftypefn 1197 1198@c setenv.c:23 1199@deftypefn Supplemental int setenv (const char *@var{name}, @ 1200 const char *@var{value}, int @var{overwrite}) 1201@deftypefnx Supplemental void unsetenv (const char *@var{name}) 1202 1203@code{setenv} adds @var{name} to the environment with value 1204@var{value}. If the name was already present in the environment, 1205the new value will be stored only if @var{overwrite} is nonzero. 1206The companion @code{unsetenv} function removes @var{name} from the 1207environment. This implementation is not safe for multithreaded code. 1208 1209@end deftypefn 1210 1211@c setproctitle.c:31 1212@deftypefn Supplemental void setproctitle (const char *@var{fmt}, ...) 1213 1214Set the title of a process to @var{fmt}. va args not supported for now, 1215but defined for compatibility with BSD. 1216 1217@end deftypefn 1218 1219@c strsignal.c:348 1220@deftypefn Extension int signo_max (void) 1221 1222Returns the maximum signal value for which a corresponding symbolic 1223name or message is available. Note that in the case where we use the 1224@code{sys_siglist} supplied by the system, it is possible for there to 1225be more symbolic names than messages, or vice versa. In fact, the 1226manual page for @code{psignal(3b)} explicitly warns that one should 1227check the size of the table (@code{NSIG}) before indexing it, since 1228new signal codes may be added to the system before they are added to 1229the table. Thus @code{NSIG} might be smaller than value implied by 1230the largest signo value defined in @code{<signal.h>}. 1231 1232We return the maximum value that can be used to obtain a meaningful 1233symbolic name or message. 1234 1235@end deftypefn 1236 1237@c sigsetmask.c:8 1238@deftypefn Supplemental int sigsetmask (int @var{set}) 1239 1240Sets the signal mask to the one provided in @var{set} and returns 1241the old mask (which, for libiberty's implementation, will always 1242be the value @code{1}). 1243 1244@end deftypefn 1245 1246@c simple-object.txh:96 1247@deftypefn Extension {const char *} simple_object_attributes_compare @ 1248 (simple_object_attributes *@var{attrs1}, simple_object_attributes *@var{attrs2}, @ 1249 int *@var{err}) 1250 1251Compare @var{attrs1} and @var{attrs2}. If they could be linked 1252together without error, return @code{NULL}. Otherwise, return an 1253error message and set @code{*@var{err}} to an errno value or @code{0} 1254if there is no relevant errno. 1255 1256@end deftypefn 1257 1258@c simple-object.txh:81 1259@deftypefn Extension {simple_object_attributes *} simple_object_fetch_attributes @ 1260 (simple_object_read *@var{simple_object}, const char **@var{errmsg}, int *@var{err}) 1261 1262Fetch the attributes of @var{simple_object}. The attributes are 1263internal information such as the format of the object file, or the 1264architecture it was compiled for. This information will persist until 1265@code{simple_object_attributes_release} is called, even if 1266@var{simple_object} itself is released. 1267 1268On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an 1269error message, and sets @code{*@var{err}} to an errno value or 1270@code{0} if there is no relevant errno. 1271 1272@end deftypefn 1273 1274@c simple-object.txh:49 1275@deftypefn Extension {int} simple_object_find_section @ 1276 (simple_object_read *@var{simple_object} off_t *@var{offset}, @ 1277 off_t *@var{length}, const char **@var{errmsg}, int *@var{err}) 1278 1279Look for the section @var{name} in @var{simple_object}. This returns 1280information for the first section with that name. 1281 1282If found, return 1 and set @code{*@var{offset}} to the offset in the 1283file of the section contents and set @code{*@var{length}} to the 1284length of the section contents. The value in @code{*@var{offset}} 1285will be relative to the offset passed to 1286@code{simple_object_open_read}. 1287 1288If the section is not found, and no error occurs, 1289@code{simple_object_find_section} returns @code{0} and set 1290@code{*@var{errmsg}} to @code{NULL}. 1291 1292If an error occurs, @code{simple_object_find_section} returns 1293@code{0}, sets @code{*@var{errmsg}} to an error message, and sets 1294@code{*@var{err}} to an errno value or @code{0} if there is no 1295relevant errno. 1296 1297@end deftypefn 1298 1299@c simple-object.txh:27 1300@deftypefn Extension {const char *} simple_object_find_sections @ 1301 (simple_object_read *@var{simple_object}, int (*@var{pfn}) (void *@var{data}, @ 1302 const char *@var{name}, off_t @var{offset}, off_t @var{length}), @ 1303 void *@var{data}, int *@var{err}) 1304 1305This function calls @var{pfn} for each section in @var{simple_object}. 1306It calls @var{pfn} with the section name, the offset within the file 1307of the section contents, and the length of the section contents. The 1308offset within the file is relative to the offset passed to 1309@code{simple_object_open_read}. The @var{data} argument to this 1310function is passed along to @var{pfn}. 1311 1312If @var{pfn} returns @code{0}, the loop over the sections stops and 1313@code{simple_object_find_sections} returns. If @var{pfn} returns some 1314other value, the loop continues. 1315 1316On success @code{simple_object_find_sections} returns. On error it 1317returns an error string, and sets @code{*@var{err}} to an errno value 1318or @code{0} if there is no relevant errno. 1319 1320@end deftypefn 1321 1322@c simple-object.txh:2 1323@deftypefn Extension {simple_object_read *} simple_object_open_read @ 1324 (int @var{descriptor}, off_t @var{offset}, const char *{segment_name}, @ 1325 const char **@var{errmsg}, int *@var{err}) 1326 1327Opens an object file for reading. Creates and returns an 1328@code{simple_object_read} pointer which may be passed to other 1329functions to extract data from the object file. 1330 1331@var{descriptor} holds a file descriptor which permits reading. 1332 1333@var{offset} is the offset into the file; this will be @code{0} in the 1334normal case, but may be a different value when reading an object file 1335in an archive file. 1336 1337@var{segment_name} is only used with the Mach-O file format used on 1338Darwin aka Mac OS X. It is required on that platform, and means to 1339only look at sections within the segment with that name. The 1340parameter is ignored on other systems. 1341 1342If an error occurs, this functions returns @code{NULL} and sets 1343@code{*@var{errmsg}} to an error string and sets @code{*@var{err}} to 1344an errno value or @code{0} if there is no relevant errno. 1345 1346@end deftypefn 1347 1348@c simple-object.txh:107 1349@deftypefn Extension {void} simple_object_release_attributes @ 1350 (simple_object_attributes *@var{attrs}) 1351 1352Release all resources associated with @var{attrs}. 1353 1354@end deftypefn 1355 1356@c simple-object.txh:73 1357@deftypefn Extension {void} simple_object_release_read @ 1358 (simple_object_read *@var{simple_object}) 1359 1360Release all resources associated with @var{simple_object}. This does 1361not close the file descriptor. 1362 1363@end deftypefn 1364 1365@c simple-object.txh:184 1366@deftypefn Extension {void} simple_object_release_write @ 1367 (simple_object_write *@var{simple_object}) 1368 1369Release all resources associated with @var{simple_object}. 1370 1371@end deftypefn 1372 1373@c simple-object.txh:114 1374@deftypefn Extension {simple_object_write *} simple_object_start_write @ 1375 (simple_object_attributes @var{attrs}, const char *@var{segment_name}, @ 1376 const char **@var{errmsg}, int *@var{err}) 1377 1378Start creating a new object file using the object file format 1379described in @var{attrs}. You must fetch attribute information from 1380an existing object file before you can create a new one. There is 1381currently no support for creating an object file de novo. 1382 1383@var{segment_name} is only used with Mach-O as found on Darwin aka Mac 1384OS X. The parameter is required on that target. It means that all 1385sections are created within the named segment. It is ignored for 1386other object file formats. 1387 1388On error @code{simple_object_start_write} returns @code{NULL}, sets 1389@code{*@var{ERRMSG}} to an error message, and sets @code{*@var{err}} 1390to an errno value or @code{0} if there is no relevant errno. 1391 1392@end deftypefn 1393 1394@c simple-object.txh:153 1395@deftypefn Extension {const char *} simple_object_write_add_data @ 1396 (simple_object_write *@var{simple_object}, @ 1397 simple_object_write_section *@var{section}, const void *@var{buffer}, @ 1398 size_t @var{size}, int @var{copy}, int *@var{err}) 1399 1400Add data @var{buffer}/@var{size} to @var{section} in 1401@var{simple_object}. If @var{copy} is non-zero, the data will be 1402copied into memory if necessary. If @var{copy} is zero, @var{buffer} 1403must persist until @code{simple_object_write_to_file} is called. is 1404released. 1405 1406On success this returns @code{NULL}. On error this returns an error 1407message, and sets @code{*@var{err}} to an errno value or 0 if there is 1408no relevant erro. 1409 1410@end deftypefn 1411 1412@c simple-object.txh:134 1413@deftypefn Extension {simple_object_write_section *} simple_object_write_create_section @ 1414 (simple_object_write *@var{simple_object}, const char *@var{name}, @ 1415 unsigned int @var{align}, const char **@var{errmsg}, int *@var{err}) 1416 1417Add a section to @var{simple_object}. @var{name} is the name of the 1418new section. @var{align} is the required alignment expressed as the 1419number of required low-order 0 bits (e.g., 2 for alignment to a 32-bit 1420boundary). 1421 1422The section is created as containing data, readable, not writable, not 1423executable, not loaded at runtime. The section is not written to the 1424file until @code{simple_object_write_to_file} is called. 1425 1426On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an 1427error message, and sets @code{*@var{err}} to an errno value or 1428@code{0} if there is no relevant errno. 1429 1430@end deftypefn 1431 1432@c simple-object.txh:170 1433@deftypefn Extension {const char *} simple_object_write_to_file @ 1434 (simple_object_write *@var{simple_object}, int @var{descriptor}, int *@var{err}) 1435 1436Write the complete object file to @var{descriptor}, an open file 1437descriptor. This writes out all the data accumulated by calls to 1438@code{simple_object_write_create_section} and 1439@var{simple_object_write_add_data}. 1440 1441This returns @code{NULL} on success. On error this returns an error 1442message and sets @code{*@var{err}} to an errno value or @code{0} if 1443there is no relevant errno. 1444 1445@end deftypefn 1446 1447@c snprintf.c:28 1448@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, @ 1449 const char *@var{format}, ...) 1450 1451This function is similar to @code{sprintf}, but it will write to 1452@var{buf} at most @code{@var{n}-1} bytes of text, followed by a 1453terminating null byte, for a total of @var{n} bytes. 1454On error the return value is -1, otherwise it returns the number of 1455bytes, not including the terminating null byte, that would have been 1456written had @var{n} been sufficiently large, regardless of the actual 1457value of @var{n}. Note some pre-C99 system libraries do not implement 1458this correctly so users cannot generally rely on the return value if 1459the system version of this function is used. 1460 1461@end deftypefn 1462 1463@c spaces.c:22 1464@deftypefn Extension char* spaces (int @var{count}) 1465 1466Returns a pointer to a memory region filled with the specified 1467number of spaces and null terminated. The returned pointer is 1468valid until at least the next call. 1469 1470@end deftypefn 1471 1472@c splay-tree.c:303 1473@deftypefn Supplemental splay_tree splay_tree_new_with_typed_alloc @ 1474(splay_tree_compare_fn @var{compare_fn}, @ 1475splay_tree_delete_key_fn @var{delete_key_fn}, @ 1476splay_tree_delete_value_fn @var{delete_value_fn}, @ 1477splay_tree_allocate_fn @var{tree_allocate_fn}, @ 1478splay_tree_allocate_fn @var{node_allocate_fn}, @ 1479splay_tree_deallocate_fn @var{deallocate_fn}, @ 1480void * @var{allocate_data}) 1481 1482This function creates a splay tree that uses two different allocators 1483@var{tree_allocate_fn} and @var{node_allocate_fn} to use for allocating the 1484tree itself and its nodes respectively. This is useful when variables of 1485different types need to be allocated with different allocators. 1486 1487The splay tree will use @var{compare_fn} to compare nodes, 1488@var{delete_key_fn} to deallocate keys, and @var{delete_value_fn} to 1489deallocate values. 1490 1491@end deftypefn 1492 1493@c stack-limit.c:28 1494@deftypefn Extension void stack_limit_increase (unsigned long @var{pref}) 1495 1496Attempt to increase stack size limit to @var{pref} bytes if possible. 1497 1498@end deftypefn 1499 1500@c stpcpy.c:23 1501@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src}) 1502 1503Copies the string @var{src} into @var{dst}. Returns a pointer to 1504@var{dst} + strlen(@var{src}). 1505 1506@end deftypefn 1507 1508@c stpncpy.c:23 1509@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, @ 1510 size_t @var{len}) 1511 1512Copies the string @var{src} into @var{dst}, copying exactly @var{len} 1513and padding with zeros if necessary. If @var{len} < strlen(@var{src}) 1514then return @var{dst} + @var{len}, otherwise returns @var{dst} + 1515strlen(@var{src}). 1516 1517@end deftypefn 1518 1519@c strcasecmp.c:15 1520@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2}) 1521 1522A case-insensitive @code{strcmp}. 1523 1524@end deftypefn 1525 1526@c strchr.c:6 1527@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c}) 1528 1529Returns a pointer to the first occurrence of the character @var{c} in 1530the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 1531null character, the results are undefined. 1532 1533@end deftypefn 1534 1535@c strdup.c:3 1536@deftypefn Supplemental char* strdup (const char *@var{s}) 1537 1538Returns a pointer to a copy of @var{s} in memory obtained from 1539@code{malloc}, or @code{NULL} if insufficient memory was available. 1540 1541@end deftypefn 1542 1543@c strerror.c:670 1544@deftypefn Replacement {const char*} strerrno (int @var{errnum}) 1545 1546Given an error number returned from a system call (typically returned 1547in @code{errno}), returns a pointer to a string containing the 1548symbolic name of that error number, as found in @code{<errno.h>}. 1549 1550If the supplied error number is within the valid range of indices for 1551symbolic names, but no name is available for the particular error 1552number, then returns the string @samp{Error @var{num}}, where @var{num} 1553is the error number. 1554 1555If the supplied error number is not within the range of valid 1556indices, then returns @code{NULL}. 1557 1558The contents of the location pointed to are only guaranteed to be 1559valid until the next call to @code{strerrno}. 1560 1561@end deftypefn 1562 1563@c strerror.c:603 1564@deftypefn Supplemental char* strerror (int @var{errnoval}) 1565 1566Maps an @code{errno} number to an error message string, the contents 1567of which are implementation defined. On systems which have the 1568external variables @code{sys_nerr} and @code{sys_errlist}, these 1569strings will be the same as the ones used by @code{perror}. 1570 1571If the supplied error number is within the valid range of indices for 1572the @code{sys_errlist}, but no message is available for the particular 1573error number, then returns the string @samp{Error @var{num}}, where 1574@var{num} is the error number. 1575 1576If the supplied error number is not a valid index into 1577@code{sys_errlist}, returns @code{NULL}. 1578 1579The returned string is only guaranteed to be valid only until the 1580next call to @code{strerror}. 1581 1582@end deftypefn 1583 1584@c strncasecmp.c:15 1585@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2}) 1586 1587A case-insensitive @code{strncmp}. 1588 1589@end deftypefn 1590 1591@c strncmp.c:6 1592@deftypefn Supplemental int strncmp (const char *@var{s1}, @ 1593 const char *@var{s2}, size_t @var{n}) 1594 1595Compares the first @var{n} bytes of two strings, returning a value as 1596@code{strcmp}. 1597 1598@end deftypefn 1599 1600@c strndup.c:23 1601@deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n}) 1602 1603Returns a pointer to a copy of @var{s} with at most @var{n} characters 1604in memory obtained from @code{malloc}, or @code{NULL} if insufficient 1605memory was available. The result is always NUL terminated. 1606 1607@end deftypefn 1608 1609@c strnlen.c:6 1610@deftypefn Supplemental size_t strnlen (const char *@var{s}, size_t @var{maxlen}) 1611 1612Returns the length of @var{s}, as with @code{strlen}, but never looks 1613past the first @var{maxlen} characters in the string. If there is no 1614'\0' character in the first @var{maxlen} characters, returns 1615@var{maxlen}. 1616 1617@end deftypefn 1618 1619@c strrchr.c:6 1620@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c}) 1621 1622Returns a pointer to the last occurrence of the character @var{c} in 1623the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 1624null character, the results are undefined. 1625 1626@end deftypefn 1627 1628@c strsignal.c:383 1629@deftypefn Supplemental {const char *} strsignal (int @var{signo}) 1630 1631Maps an signal number to an signal message string, the contents of 1632which are implementation defined. On systems which have the external 1633variable @code{sys_siglist}, these strings will be the same as the 1634ones used by @code{psignal()}. 1635 1636If the supplied signal number is within the valid range of indices for 1637the @code{sys_siglist}, but no message is available for the particular 1638signal number, then returns the string @samp{Signal @var{num}}, where 1639@var{num} is the signal number. 1640 1641If the supplied signal number is not a valid index into 1642@code{sys_siglist}, returns @code{NULL}. 1643 1644The returned string is only guaranteed to be valid only until the next 1645call to @code{strsignal}. 1646 1647@end deftypefn 1648 1649@c strsignal.c:448 1650@deftypefn Extension {const char*} strsigno (int @var{signo}) 1651 1652Given an signal number, returns a pointer to a string containing the 1653symbolic name of that signal number, as found in @code{<signal.h>}. 1654 1655If the supplied signal number is within the valid range of indices for 1656symbolic names, but no name is available for the particular signal 1657number, then returns the string @samp{Signal @var{num}}, where 1658@var{num} is the signal number. 1659 1660If the supplied signal number is not within the range of valid 1661indices, then returns @code{NULL}. 1662 1663The contents of the location pointed to are only guaranteed to be 1664valid until the next call to @code{strsigno}. 1665 1666@end deftypefn 1667 1668@c strstr.c:6 1669@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub}) 1670 1671This function searches for the substring @var{sub} in the string 1672@var{string}, not including the terminating null characters. A pointer 1673to the first occurrence of @var{sub} is returned, or @code{NULL} if the 1674substring is absent. If @var{sub} points to a string with zero 1675length, the function returns @var{string}. 1676 1677@end deftypefn 1678 1679@c strtod.c:27 1680@deftypefn Supplemental double strtod (const char *@var{string}, @ 1681 char **@var{endptr}) 1682 1683This ISO C function converts the initial portion of @var{string} to a 1684@code{double}. If @var{endptr} is not @code{NULL}, a pointer to the 1685character after the last character used in the conversion is stored in 1686the location referenced by @var{endptr}. If no conversion is 1687performed, zero is returned and the value of @var{string} is stored in 1688the location referenced by @var{endptr}. 1689 1690@end deftypefn 1691 1692@c strerror.c:729 1693@deftypefn Extension int strtoerrno (const char *@var{name}) 1694 1695Given the symbolic name of a error number (e.g., @code{EACCES}), map it 1696to an errno value. If no translation is found, returns 0. 1697 1698@end deftypefn 1699 1700@c strtol.c:33 1701@deftypefn Supplemental {long int} strtol (const char *@var{string}, @ 1702 char **@var{endptr}, int @var{base}) 1703@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, @ 1704 char **@var{endptr}, int @var{base}) 1705 1706The @code{strtol} function converts the string in @var{string} to a 1707long integer value according to the given @var{base}, which must be 1708between 2 and 36 inclusive, or be the special value 0. If @var{base} 1709is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x} 1710to indicate bases 8 and 16, respectively, else default to base 10. 1711When the base is 16 (either explicitly or implicitly), a prefix of 1712@code{0x} is allowed. The handling of @var{endptr} is as that of 1713@code{strtod} above. The @code{strtoul} function is the same, except 1714that the converted value is unsigned. 1715 1716@end deftypefn 1717 1718@c strsignal.c:502 1719@deftypefn Extension int strtosigno (const char *@var{name}) 1720 1721Given the symbolic name of a signal, map it to a signal number. If no 1722translation is found, returns 0. 1723 1724@end deftypefn 1725 1726@c strverscmp.c:25 1727@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2}) 1728The @code{strverscmp} function compares the string @var{s1} against 1729@var{s2}, considering them as holding indices/version numbers. Return 1730value follows the same conventions as found in the @code{strverscmp} 1731function. In fact, if @var{s1} and @var{s2} contain no digits, 1732@code{strverscmp} behaves like @code{strcmp}. 1733 1734Basically, we compare strings normally (character by character), until 1735we find a digit in each string - then we enter a special comparison 1736mode, where each sequence of digits is taken as a whole. If we reach the 1737end of these two parts without noticing a difference, we return to the 1738standard comparison mode. There are two types of numeric parts: 1739"integral" and "fractional" (those begin with a '0'). The types 1740of the numeric parts affect the way we sort them: 1741 1742@itemize @bullet 1743@item 1744integral/integral: we compare values as you would expect. 1745 1746@item 1747fractional/integral: the fractional part is less than the integral one. 1748Again, no surprise. 1749 1750@item 1751fractional/fractional: the things become a bit more complex. 1752If the common prefix contains only leading zeroes, the longest part is less 1753than the other one; else the comparison behaves normally. 1754@end itemize 1755 1756@smallexample 1757strverscmp ("no digit", "no digit") 1758 @result{} 0 // @r{same behavior as strcmp.} 1759strverscmp ("item#99", "item#100") 1760 @result{} <0 // @r{same prefix, but 99 < 100.} 1761strverscmp ("alpha1", "alpha001") 1762 @result{} >0 // @r{fractional part inferior to integral one.} 1763strverscmp ("part1_f012", "part1_f01") 1764 @result{} >0 // @r{two fractional parts.} 1765strverscmp ("foo.009", "foo.0") 1766 @result{} <0 // @r{idem, but with leading zeroes only.} 1767@end smallexample 1768 1769This function is especially useful when dealing with filename sorting, 1770because filenames frequently hold indices/version numbers. 1771@end deftypefun 1772 1773@c timeval-utils.c:43 1774@deftypefn Extension void timeval_add (struct timeval *@var{a}, @ 1775 struct timeval *@var{b}, struct timeval *@var{result}) 1776 1777Adds @var{a} to @var{b} and stores the result in @var{result}. 1778 1779@end deftypefn 1780 1781@c timeval-utils.c:67 1782@deftypefn Extension void timeval_sub (struct timeval *@var{a}, @ 1783 struct timeval *@var{b}, struct timeval *@var{result}) 1784 1785Subtracts @var{b} from @var{a} and stores the result in @var{result}. 1786 1787@end deftypefn 1788 1789@c tmpnam.c:3 1790@deftypefn Supplemental char* tmpnam (char *@var{s}) 1791 1792This function attempts to create a name for a temporary file, which 1793will be a valid file name yet not exist when @code{tmpnam} checks for 1794it. @var{s} must point to a buffer of at least @code{L_tmpnam} bytes, 1795or be @code{NULL}. Use of this function creates a security risk, and it must 1796not be used in new projects. Use @code{mkstemp} instead. 1797 1798@end deftypefn 1799 1800@c unlink-if-ordinary.c:27 1801@deftypefn Supplemental int unlink_if_ordinary (const char*) 1802 1803Unlinks the named file, unless it is special (e.g. a device file). 1804Returns 0 when the file was unlinked, a negative value (and errno set) when 1805there was an error deleting the file, and a positive value if no attempt 1806was made to unlink the file because it is special. 1807 1808@end deftypefn 1809 1810@c fopen_unlocked.c:31 1811@deftypefn Extension void unlock_std_streams (void) 1812 1813If the OS supports it, ensure that the standard I/O streams, 1814@code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any 1815multi-threaded locking. Otherwise do nothing. 1816 1817@end deftypefn 1818 1819@c fopen_unlocked.c:23 1820@deftypefn Extension void unlock_stream (FILE * @var{stream}) 1821 1822If the OS supports it, ensure that the supplied stream is setup to 1823avoid any multi-threaded locking. Otherwise leave the @code{FILE} 1824pointer unchanged. If the @var{stream} is @code{NULL} do nothing. 1825 1826@end deftypefn 1827 1828@c vasprintf.c:47 1829@deftypefn Extension int vasprintf (char **@var{resptr}, @ 1830 const char *@var{format}, va_list @var{args}) 1831 1832Like @code{vsprintf}, but instead of passing a pointer to a buffer, 1833you pass a pointer to a pointer. This function will compute the size 1834of the buffer needed, allocate memory with @code{malloc}, and store a 1835pointer to the allocated memory in @code{*@var{resptr}}. The value 1836returned is the same as @code{vsprintf} would return. If memory could 1837not be allocated, minus one is returned and @code{NULL} is stored in 1838@code{*@var{resptr}}. 1839 1840@end deftypefn 1841 1842@c vfork.c:6 1843@deftypefn Supplemental int vfork (void) 1844 1845Emulates @code{vfork} by calling @code{fork} and returning its value. 1846 1847@end deftypefn 1848 1849@c vprintf.c:3 1850@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap}) 1851@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, @ 1852 const char *@var{format}, va_list @var{ap}) 1853@deftypefnx Supplemental int vsprintf (char *@var{str}, @ 1854 const char *@var{format}, va_list @var{ap}) 1855 1856These functions are the same as @code{printf}, @code{fprintf}, and 1857@code{sprintf}, respectively, except that they are called with a 1858@code{va_list} instead of a variable number of arguments. Note that 1859they do not call @code{va_end}; this is the application's 1860responsibility. In @libib{} they are implemented in terms of the 1861nonstandard but common function @code{_doprnt}. 1862 1863@end deftypefn 1864 1865@c vsnprintf.c:28 1866@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, @ 1867 const char *@var{format}, va_list @var{ap}) 1868 1869This function is similar to @code{vsprintf}, but it will write to 1870@var{buf} at most @code{@var{n}-1} bytes of text, followed by a 1871terminating null byte, for a total of @var{n} bytes. On error the 1872return value is -1, otherwise it returns the number of characters that 1873would have been printed had @var{n} been sufficiently large, 1874regardless of the actual value of @var{n}. Note some pre-C99 system 1875libraries do not implement this correctly so users cannot generally 1876rely on the return value if the system version of this function is 1877used. 1878 1879@end deftypefn 1880 1881@c waitpid.c:3 1882@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int) 1883 1884This is a wrapper around the @code{wait} function. Any ``special'' 1885values of @var{pid} depend on your implementation of @code{wait}, as 1886does the return value. The third argument is unused in @libib{}. 1887 1888@end deftypefn 1889 1890@c argv.c:286 1891@deftypefn Extension int writeargv (const char **@var{argv}, FILE *@var{file}) 1892 1893Write each member of ARGV, handling all necessary quoting, to the file 1894named by FILE, separated by whitespace. Return 0 on success, non-zero 1895if an error occurred while writing to FILE. 1896 1897@end deftypefn 1898 1899@c xatexit.c:11 1900@deftypefun int xatexit (void (*@var{fn}) (void)) 1901 1902Behaves as the standard @code{atexit} function, but with no limit on 1903the number of registered functions. Returns 0 on success, or @minus{}1 on 1904failure. If you use @code{xatexit} to register functions, you must use 1905@code{xexit} to terminate your program. 1906 1907@end deftypefun 1908 1909@c xmalloc.c:38 1910@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize}) 1911 1912Allocate memory without fail, and set it to zero. This routine functions 1913like @code{calloc}, but will behave the same as @code{xmalloc} if memory 1914cannot be found. 1915 1916@end deftypefn 1917 1918@c xexit.c:22 1919@deftypefn Replacement void xexit (int @var{code}) 1920 1921Terminates the program. If any functions have been registered with 1922the @code{xatexit} replacement function, they will be called first. 1923Termination is handled via the system's normal @code{exit} call. 1924 1925@end deftypefn 1926 1927@c xmalloc.c:22 1928@deftypefn Replacement void* xmalloc (size_t) 1929 1930Allocate memory without fail. If @code{malloc} fails, this will print 1931a message to @code{stderr} (using the name set by 1932@code{xmalloc_set_program_name}, 1933if any) and then call @code{xexit}. Note that it is therefore safe for 1934a program to contain @code{#define malloc xmalloc} in its source. 1935 1936@end deftypefn 1937 1938@c xmalloc.c:53 1939@deftypefn Replacement void xmalloc_failed (size_t) 1940 1941This function is not meant to be called by client code, and is listed 1942here for completeness only. If any of the allocation routines fail, this 1943function will be called to print an error message and terminate execution. 1944 1945@end deftypefn 1946 1947@c xmalloc.c:46 1948@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name}) 1949 1950You can use this to set the name of the program used by 1951@code{xmalloc_failed} when printing a failure message. 1952 1953@end deftypefn 1954 1955@c xmemdup.c:7 1956@deftypefn Replacement void* xmemdup (void *@var{input}, @ 1957 size_t @var{copy_size}, size_t @var{alloc_size}) 1958 1959Duplicates a region of memory without fail. First, @var{alloc_size} bytes 1960are allocated, then @var{copy_size} bytes from @var{input} are copied into 1961it, and the new memory is returned. If fewer bytes are copied than were 1962allocated, the remaining memory is zeroed. 1963 1964@end deftypefn 1965 1966@c xmalloc.c:32 1967@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size}) 1968Reallocate memory without fail. This routine functions like @code{realloc}, 1969but will behave the same as @code{xmalloc} if memory cannot be found. 1970 1971@end deftypefn 1972 1973@c xstrdup.c:7 1974@deftypefn Replacement char* xstrdup (const char *@var{s}) 1975 1976Duplicates a character string without fail, using @code{xmalloc} to 1977obtain memory. 1978 1979@end deftypefn 1980 1981@c xstrerror.c:7 1982@deftypefn Replacement char* xstrerror (int @var{errnum}) 1983 1984Behaves exactly like the standard @code{strerror} function, but 1985will never return a @code{NULL} pointer. 1986 1987@end deftypefn 1988 1989@c xstrndup.c:23 1990@deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n}) 1991 1992Returns a pointer to a copy of @var{s} with at most @var{n} characters 1993without fail, using @code{xmalloc} to obtain memory. The result is 1994always NUL terminated. 1995 1996@end deftypefn 1997 1998 1999