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