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