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