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