functions.texi revision 104834
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 alloca.c:26 7@deftypefn Replacement void* alloca (size_t @var{size}) 8 9This function allocates memory which will be automatically reclaimed 10after the procedure exits. The @libib{} implementation does not free 11the memory immediately but will do so eventually during subsequent 12calls to this function. Memory is allocated using @code{xmalloc} under 13normal circumstances. 14 15The header file @file{alloca-conf.h} can be used in conjunction with the 16GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make 17available this function. The @code{AC_FUNC_ALLOCA} test requires that 18client code use a block of preprocessor code to be safe (see the Autoconf 19manual for more); this header incorporates that logic and more, including 20the possibility of a GCC built-in function. 21 22@end deftypefn 23 24@c asprintf.c:33 25@deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...) 26 27Like @code{sprintf}, but instead of passing a pointer to a buffer, you 28pass a pointer to a pointer. This function will compute the size of 29the buffer needed, allocate memory with @code{malloc}, and store a 30pointer to the allocated memory in @code{*@var{resptr}}. The value 31returned is the same as @code{sprintf} would return. If memory could 32not be allocated, zero is returned and @code{NULL} is stored in 33@code{*@var{resptr}}. 34 35@end deftypefn 36 37@c atexit.c:6 38@deftypefn Supplemental int atexit (void (*@var{f})()) 39 40Causes function @var{f} to be called at exit. Returns 0. 41 42@end deftypefn 43 44@c basename.c:6 45@deftypefn Supplemental char* basename (const char *@var{name}) 46 47Returns a pointer to the last component of pathname @var{name}. 48Behavior is undefined if the pathname ends in a directory separator. 49 50@end deftypefn 51 52@c bcmp.c:6 53@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count}) 54 55Compares the first @var{count} bytes of two areas of memory. Returns 56zero if they are the same, nonzero otherwise. Returns zero if 57@var{count} is zero. A nonzero result only indicates a difference, 58it does not indicate any sorting order (say, by having a positive 59result mean @var{x} sorts before @var{y}). 60 61@end deftypefn 62 63@c bcopy.c:3 64@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length}) 65 66Copies @var{length} bytes from memory region @var{in} to region 67@var{out}. The use of @code{bcopy} is deprecated in new programs. 68 69@end deftypefn 70 71@c bsearch.c:33 72@deftypefn Supplemental void* bsearch (const void *@var{key}, const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, int (*@var{compar})(const void *, const void *)) 73 74Performs a search over an array of @var{nmemb} elements pointed to by 75@var{base} for a member that matches the object pointed to by @var{key}. 76The size of each member is specified by @var{size}. The array contents 77should be sorted in ascending order according to the @var{compar} 78comparison function. This routine should take two arguments pointing to 79the @var{key} and to an array member, in that order, and should return an 80integer less than, equal to, or greater than zero if the @var{key} object 81is respectively less than, matching, or greater than the array member. 82 83@end deftypefn 84 85@c argv.c:139 86@deftypefn Extension char** buildargv (char *@var{sp}) 87 88Given a pointer to a string, parse the string extracting fields 89separated by whitespace and optionally enclosed within either single 90or double quotes (which are stripped off), and build a vector of 91pointers to copies of the string for each field. The input string 92remains unchanged. The last element of the vector is followed by a 93@code{NULL} element. 94 95All of the memory for the pointer array and copies of the string 96is obtained from @code{malloc}. All of the memory can be returned to the 97system with the single function call @code{freeargv}, which takes the 98returned result of @code{buildargv}, as it's argument. 99 100Returns a pointer to the argument vector if successful. Returns 101@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient 102memory to complete building the argument vector. 103 104If the input is a null string (as opposed to a @code{NULL} pointer), 105then buildarg returns an argument vector that has one arg, a null 106string. 107 108@end deftypefn 109 110@c bzero.c:6 111@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count}) 112 113Zeros @var{count} bytes starting at @var{mem}. Use of this function 114is deprecated in favor of @code{memset}. 115 116@end deftypefn 117 118@c calloc.c:6 119@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize}) 120 121Uses @code{malloc} to allocate storage for @var{nelem} objects of 122@var{elsize} bytes each, then zeros the memory. 123 124@end deftypefn 125 126@c choose-temp.c:42 127@deftypefn Extension char* choose_temp_base (void) 128 129Return a prefix for temporary file names or @code{NULL} if unable to 130find one. The current directory is chosen if all else fails so the 131program is exited if a temporary directory can't be found (@code{mktemp} 132fails). The buffer for the result is obtained with @code{xmalloc}. 133 134This function is provided for backwards compatability only. Its use is 135not recommended. 136 137@end deftypefn 138 139@c make-temp-file.c:88 140@deftypefn Replacement char* choose_tmpdir () 141 142Returns a pointer to a directory path suitable for creating temporary 143files in. 144 145@end deftypefn 146 147@c clock.c:27 148@deftypefn Supplemental long clock (void) 149 150Returns an approximation of the CPU time used by the process as a 151@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the 152number of seconds used. 153 154@end deftypefn 155 156@c concat.c:24 157@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL}) 158 159Concatenate zero or more of strings and return the result in freshly 160@code{xmalloc}ed memory. Returns @code{NULL} if insufficient memory is 161available. The argument list is terminated by the first @code{NULL} 162pointer encountered. Pointers to empty strings are ignored. 163 164@end deftypefn 165 166@c argv.c:65 167@deftypefn Extension char** dupargv (char **@var{vector}) 168 169Duplicate an argument vector. Simply scans through @var{vector}, 170duplicating each argument until the terminating @code{NULL} is found. 171Returns a pointer to the argument vector if successful. Returns 172@code{NULL} if there is insufficient memory to complete building the 173argument vector. 174 175@end deftypefn 176 177@c strerror.c:566 178@deftypefn Extension int errno_max (void) 179 180Returns the maximum @code{errno} value for which a corresponding 181symbolic name or message is available. Note that in the case where we 182use the @code{sys_errlist} supplied by the system, it is possible for 183there to be more symbolic names than messages, or vice versa. In 184fact, the manual page for @code{perror(3C)} explicitly warns that one 185should check the size of the table (@code{sys_nerr}) before indexing 186it, since new error codes may be added to the system before they are 187added to the table. Thus @code{sys_nerr} might be smaller than value 188implied by the largest @code{errno} value defined in @code{<errno.h>}. 189 190We return the maximum value that can be used to obtain a meaningful 191symbolic name or message. 192 193@end deftypefn 194 195@c fdmatch.c:23 196@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2}) 197 198Check to see if two open file descriptors refer to the same file. 199This is useful, for example, when we have an open file descriptor for 200an unnamed file, and the name of a file that we believe to correspond 201to that fd. This can happen when we are exec'd with an already open 202file (@code{stdout} for example) or from the SVR4 @file{/proc} calls 203that return open file descriptors for mapped address spaces. All we 204have to do is open the file by name and check the two file descriptors 205for a match, which is done by comparing major and minor device numbers 206and inode numbers. 207 208@end deftypefn 209 210@c ffs.c:3 211@deftypefn Supplemental int ffs (int @var{valu}) 212 213Find the first (least significant) bit set in @var{valu}. Bits are 214numbered from right to left, starting with bit 1 (corresponding to the 215value 1). If @var{valu} is zero, zero is returned. 216 217@end deftypefn 218 219@c fnmatch.txh:1 220@deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags}) 221 222Matches @var{string} against @var{pattern}, returning zero if it 223matches, @code{FNM_NOMATCH} if not. @var{pattern} may contain the 224wildcards @code{?} to match any one character, @code{*} to match any 225zero or more characters, or a set of alternate characters in square 226brackets, like @samp{[a-gt8]}, which match one character (@code{a} 227through @code{g}, or @code{t}, or @code{8}, in this example) if that one 228character is in the set. A set may be inverted (i.e., match anything 229except what's in the set) by giving @code{^} or @code{!} as the first 230character in the set. To include those characters in the set, list them 231as anything other than the first character of the set. To include a 232dash in the set, list it last in the set. A backslash character makes 233the following character not special, so for example you could match 234against a literal asterisk with @samp{\*}. To match a literal 235backslash, use @samp{\\}. 236 237@code{flags} controls various aspects of the matching process, and is a 238boolean OR of zero or more of the following values (defined in 239@code{<fnmatch.h>}): 240 241@table @code 242 243@item FNM_PATHNAME 244@itemx FNM_FILE_NAME 245@var{string} is assumed to be a path name. No wildcard will ever match 246@code{/}. 247 248@item FNM_NOESCAPE 249Do not interpret backslashes as quoting the following special character. 250 251@item FNM_PERIOD 252A leading period (at the beginning of @var{string}, or if 253@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or 254@code{?} but must be matched explicitly. 255 256@item FNM_LEADING_DIR 257Means that @var{string} also matches @var{pattern} if some initial part 258of @var{string} matches, and is followed by @code{/} and zero or more 259characters. For example, @samp{foo*} would match either @samp{foobar} 260or @samp{foobar/grill}. 261 262@item FNM_CASEFOLD 263Ignores case when performing the comparison. 264 265@end table 266 267@end deftypefn 268 269@c argv.c:111 270@deftypefn Extension void freeargv (char **@var{vector}) 271 272Free an argument vector that was built using @code{buildargv}. Simply 273scans through @var{vector}, freeing the memory for each argument until 274the terminating @code{NULL} is found, and then frees @var{vector} 275itself. 276 277@end deftypefn 278 279@c getruntime.c:78 280@deftypefn Replacement long get_run_time (void) 281 282Returns the time used so far, in microseconds. If possible, this is 283the time used by this process, else it is the elapsed time since the 284process started. 285 286@end deftypefn 287 288@c getcwd.c:6 289@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len}) 290 291Copy the absolute pathname for the current working directory into 292@var{pathname}, which is assumed to point to a buffer of at least 293@var{len} bytes, and return a pointer to the buffer. If the current 294directory's path doesn't fit in @var{len} characters, the result is 295@code{NULL} and @code{errno} is set. If @var{pathname} is a null pointer, 296@code{getcwd} will obtain @var{len} bytes of space using 297@code{malloc}. 298 299@end deftypefn 300 301@c getpagesize.c:5 302@deftypefn Supplemental int getpagesize (void) 303 304Returns the number of bytes in a page of memory. This is the 305granularity of many of the system memory management routines. No 306guarantee is made as to whether or not it is the same as the basic 307memory management hardware page size. 308 309@end deftypefn 310 311@c getpwd.c:5 312@deftypefn Supplemental char* getpwd (void) 313 314Returns the current working directory. This implementation caches the 315result on the assumption that the process will not call @code{chdir} 316between calls to @code{getpwd}. 317 318@end deftypefn 319 320@c hex.c:25 321@deftypefn Extension void hex_init (void) 322 323Initializes the array mapping the current character set to 324corresponding hex values. This function must be called before any 325call to @code{hex_p} or @code{hex_value}. 326 327@end deftypefn 328 329@c hex.c:33 330@deftypefn Extension int hex_p (int @var{c}) 331 332Evaluates to non-zero if the given character is a valid hex character, 333or zero if it is not. Note that the value you pass will be cast to 334@code{unsigned char} within the macro. 335 336@end deftypefn 337 338@c hex.c:41 339@deftypefn Extension int hex_value (int @var{c}) 340 341Returns the numeric equivalent of the given character when interpreted 342as a hexidecimal digit. The result is undefined if you pass an 343invalid hex digit. Note that the value you pass will be cast to 344@code{unsigned char} within the macro. 345 346@end deftypefn 347 348@c index.c:5 349@deftypefn Supplemental char* index (char *@var{s}, int @var{c}) 350 351Returns a pointer to the first occurrence of the character @var{c} in 352the string @var{s}, or @code{NULL} if not found. The use of @code{index} is 353deprecated in new programs in favor of @code{strchr}. 354 355@end deftypefn 356 357@c insque.c:6 358@deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred}) 359@deftypefnx Supplemental void remque (struct qelem *@var{elem}) 360 361Routines to manipulate queues built from doubly linked lists. The 362@code{insque} routine inserts @var{elem} in the queue immediately 363after @var{pred}. The @code{remque} routine removes @var{elem} from 364its containing queue. These routines expect to be passed pointers to 365structures which have as their first members a forward pointer and a 366back pointer, like this prototype (although no prototype is provided): 367 368@example 369struct qelem @{ 370 struct qelem *q_forw; 371 struct qelem *q_back; 372 char q_data[]; 373@}; 374@end example 375 376@end deftypefn 377 378@c lbasename.c:23 379@deftypefn Replacement {const char*} lbasename (const char *@var{name}) 380 381Given a pointer to a string containing a typical pathname 382(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the 383last component of the pathname (@samp{ls.c} in this case). The 384returned pointer is guaranteed to lie within the original 385string. This latter fact is not true of many vendor C 386libraries, which return special strings or modify the passed 387strings for particular input. 388 389In particular, the empty string returns the same empty string, 390and a path ending in @code{/} returns the empty string after it. 391 392@end deftypefn 393 394@c make-temp-file.c:138 395@deftypefn Replacement char* make_temp_file (const char *@var{suffix}) 396 397Return a temporary file name (as a string) or @code{NULL} if unable to 398create one. @var{suffix} is a suffix to append to the file name. The 399string is @code{malloc}ed, and the temporary file has been created. 400 401@end deftypefn 402 403@c memchr.c:3 404@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n}) 405 406This function searches memory starting at @code{*@var{s}} for the 407character @var{c}. The search only ends with the first occurrence of 408@var{c}, or after @var{length} characters; in particular, a null 409character does not terminate the search. If the character @var{c} is 410found within @var{length} characters of @code{*@var{s}}, a pointer 411to the character is returned. If @var{c} is not found, then @code{NULL} is 412returned. 413 414@end deftypefn 415 416@c memcmp.c:6 417@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count}) 418 419Compares the first @var{count} bytes of two areas of memory. Returns 420zero if they are the same, a value less than zero if @var{x} is 421lexically less than @var{y}, or a value greater than zero if @var{x} 422is lexically greater than @var{y}. Note that lexical order is determined 423as if comparing unsigned char arrays. 424 425@end deftypefn 426 427@c memcpy.c:6 428@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length}) 429 430Copies @var{length} bytes from memory region @var{in} to region 431@var{out}. Returns a pointer to @var{out}. 432 433@end deftypefn 434 435@c memmove.c:6 436@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count}) 437 438Copies @var{count} bytes from memory area @var{from} to memory area 439@var{to}, returning a pointer to @var{to}. 440 441@end deftypefn 442 443@c memset.c:6 444@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count}) 445 446Sets the first @var{count} bytes of @var{s} to the constant byte 447@var{c}, returning a pointer to @var{s}. 448 449@end deftypefn 450 451@c mkstemps.c:54 452@deftypefn Replacement int mkstemps (char *@var{template}, int @var{suffix_len}) 453 454Generate a unique temporary file name from @var{template}. 455@var{template} has the form: 456 457@example 458 @var{path}/ccXXXXXX@var{suffix} 459@end example 460 461@var{suffix_len} tells us how long @var{suffix} is (it can be zero 462length). The last six characters of @var{template} before @var{suffix} 463must be @samp{XXXXXX}; they are replaced with a string that makes the 464filename unique. Returns a file descriptor open on the file for 465reading and writing. 466 467@end deftypefn 468 469@c pexecute.c:67 470@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 flags) 471 472Executes a program. 473 474@var{program} and @var{argv} are the arguments to 475@code{execv}/@code{execvp}. 476 477@var{this_pname} is name of the calling program (i.e., @code{argv[0]}). 478 479@var{temp_base} is the path name, sans suffix, of a temporary file to 480use if needed. This is currently only needed for MS-DOS ports that 481don't use @code{go32} (do any still exist?). Ports that don't need it 482can pass @code{NULL}. 483 484(@code{@var{flags} & PEXECUTE_SEARCH}) is non-zero if @env{PATH} should be searched 485(??? It's not clear that GCC passes this flag correctly). (@code{@var{flags} & 486PEXECUTE_FIRST}) is nonzero for the first process in chain. 487(@code{@var{flags} & PEXECUTE_FIRST}) is nonzero for the last process 488in chain. The first/last flags could be simplified to only mark the 489last of a chain of processes but that requires the caller to always 490mark the last one (and not give up early if some error occurs). 491It's more robust to require the caller to mark both ends of the chain. 492 493The result is the pid on systems like Unix where we 494@code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we 495use @code{spawn}. It is up to the caller to wait for the child. 496 497The result is the @code{WEXITSTATUS} on systems like MS-DOS where we 498@code{spawn} and wait for the child here. 499 500Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the 501text of the error message with an optional argument (if not needed, 502@var{errmsg_arg} is set to @code{NULL}), and @minus{}1 is returned. 503@code{errno} is available to the caller to use. 504 505@end deftypefn 506 507@c strsignal.c:547 508@deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message}) 509 510Print @var{message} to the standard error, followed by a colon, 511followed by the description of the signal specified by @var{signo}, 512followed by a newline. 513 514@end deftypefn 515 516@c putenv.c:21 517@deftypefn Supplemental int putenv (const char *@var{string}) 518 519Uses @code{setenv} or @code{unsetenv} to put @var{string} into 520the environment or remove it. If @var{string} is of the form 521@samp{name=value} the string is added; if no @samp{=} is present the 522name is unset/removed. 523 524@end deftypefn 525 526@c pexecute.c:104 527@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) 528 529Waits for a program started by @code{pexecute} to finish. 530 531@var{pid} is the process id of the task to wait for. @var{status} is 532the `status' argument to wait. @var{flags} is currently unused (allows 533future enhancement without breaking upward compatibility). Pass 0 for now. 534 535The result is the pid of the child reaped, or -1 for failure 536(@code{errno} says why). 537 538On systems that don't support waiting for a particular child, @var{pid} is 539ignored. On systems like MS-DOS that don't really multitask @code{pwait} 540is just a mechanism to provide a consistent interface for the caller. 541 542@end deftypefn 543 544@c random.c:39 545@deftypefn Supplement {long int} random (void) 546@deftypefnx Supplement void srandom (unsigned int @var{seed}) 547@deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n}) 548@deftypefnx Supplement void* setstate (void *@var{arg_state}) 549 550Random number functions. @code{random} returns a random number in the 551range 0 to @code{LONG_MAX}. @code{srandom} initializes the random 552number generator to some starting point determined by @var{seed} 553(else, the values returned by @code{random} are always the same for each 554run of the program). @code{initstate} and @code{setstate} allow fine-grained 555control over the state of the random number generator. 556 557@end deftypefn 558 559@c concat.c:177 560@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL}) 561 562Same as @code{concat}, except that if @var{optr} is not @code{NULL} it 563is freed after the string is created. This is intended to be useful 564when you're extending an existing string or building up a string in a 565loop: 566 567@example 568 str = reconcat (str, "pre-", str, NULL); 569@end example 570 571@end deftypefn 572 573@c rename.c:6 574@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new}) 575 576Renames a file from @var{old} to @var{new}. If @var{new} already 577exists, it is removed. 578 579@end deftypefn 580 581@c rindex.c:5 582@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c}) 583 584Returns a pointer to the last occurrence of the character @var{c} in 585the string @var{s}, or @code{NULL} if not found. The use of @code{rindex} is 586deprecated in new programs in favor of @code{strrchr}. 587 588@end deftypefn 589 590@c setenv.c:22 591@deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite}) 592@deftypefnx Supplemental void unsetenv (const char *@var{name}) 593 594@code{setenv} adds @var{name} to the environment with value 595@var{value}. If the name was already present in the environment, 596the new value will be stored only if @var{overwrite} is nonzero. 597The companion @code{unsetenv} function removes @var{name} from the 598environment. This implementation is not safe for multithreaded code. 599 600@end deftypefn 601 602@c strsignal.c:353 603@deftypefn Extension int signo_max (void) 604 605Returns the maximum signal value for which a corresponding symbolic 606name or message is available. Note that in the case where we use the 607@code{sys_siglist} supplied by the system, it is possible for there to 608be more symbolic names than messages, or vice versa. In fact, the 609manual page for @code{psignal(3b)} explicitly warns that one should 610check the size of the table (@code{NSIG}) before indexing it, since 611new signal codes may be added to the system before they are added to 612the table. Thus @code{NSIG} might be smaller than value implied by 613the largest signo value defined in @code{<signal.h>}. 614 615We return the maximum value that can be used to obtain a meaningful 616symbolic name or message. 617 618@end deftypefn 619 620@c sigsetmask.c:8 621@deftypefn Supplemental int sigsetmask (int @var{set}) 622 623Sets the signal mask to the one provided in @var{set} and returns 624the old mask (which, for libiberty's implementation, will always 625be the value @code{1}). 626 627@end deftypefn 628 629@c spaces.c:22 630@deftypefn Extension char* spaces (int @var{count}) 631 632Returns a pointer to a memory region filled with the specified 633number of spaces and null terminated. The returned pointer is 634valid until at least the next call. 635 636@end deftypefn 637 638@c strcasecmp.c:15 639@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2}) 640 641A case-insensitive @code{strcmp}. 642 643@end deftypefn 644 645@c strchr.c:6 646@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c}) 647 648Returns a pointer to the first occurrence of the character @var{c} in 649the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 650null character, the results are undefined. 651 652@end deftypefn 653 654@c strdup.c:3 655@deftypefn Supplemental char* strdup (const char *@var{s}) 656 657Returns a pointer to a copy of @var{s} in memory obtained from 658@code{malloc}, or @code{NULL} if insufficient memory was available. 659 660@end deftypefn 661 662@c strerror.c:670 663@deftypefn Replacement {const char*} strerrno (int @var{errnum}) 664 665Given an error number returned from a system call (typically returned 666in @code{errno}), returns a pointer to a string containing the 667symbolic name of that error number, as found in @code{<errno.h>}. 668 669If the supplied error number is within the valid range of indices for 670symbolic names, but no name is available for the particular error 671number, then returns the string @samp{Error @var{num}}, where @var{num} 672is the error number. 673 674If the supplied error number is not within the range of valid 675indices, then returns @code{NULL}. 676 677The contents of the location pointed to are only guaranteed to be 678valid until the next call to @code{strerrno}. 679 680@end deftypefn 681 682@c strerror.c:602 683@deftypefn Supplemental char* strerror (int @var{errnoval}) 684 685Maps an @code{errno} number to an error message string, the contents 686of which are implementation defined. On systems which have the 687external variables @code{sys_nerr} and @code{sys_errlist}, these 688strings will be the same as the ones used by @code{perror}. 689 690If the supplied error number is within the valid range of indices for 691the @code{sys_errlist}, but no message is available for the particular 692error number, then returns the string @samp{Error @var{num}}, where 693@var{num} is the error number. 694 695If the supplied error number is not a valid index into 696@code{sys_errlist}, returns @code{NULL}. 697 698The returned string is only guaranteed to be valid only until the 699next call to @code{strerror}. 700 701@end deftypefn 702 703@c strncasecmp.c:15 704@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2}) 705 706A case-insensitive @code{strncmp}. 707 708@end deftypefn 709 710@c strncmp.c:6 711@deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) 712 713Compares the first @var{n} bytes of two strings, returning a value as 714@code{strcmp}. 715 716@end deftypefn 717 718@c strrchr.c:6 719@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c}) 720 721Returns a pointer to the last occurrence of the character @var{c} in 722the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 723null character, the results are undefined. 724 725@end deftypefn 726 727@c strsignal.c:388 728@deftypefn Supplemental {const char *} strsignal (int @var{signo}) 729 730Maps an signal number to an signal message string, the contents of 731which are implementation defined. On systems which have the external 732variable @code{sys_siglist}, these strings will be the same as the 733ones used by @code{psignal()}. 734 735If the supplied signal number is within the valid range of indices for 736the @code{sys_siglist}, but no message is available for the particular 737signal number, then returns the string @samp{Signal @var{num}}, where 738@var{num} is the signal number. 739 740If the supplied signal number is not a valid index into 741@code{sys_siglist}, returns @code{NULL}. 742 743The returned string is only guaranteed to be valid only until the next 744call to @code{strsignal}. 745 746@end deftypefn 747 748@c strsignal.c:452 749@deftypefn Extension {const char*} strsigno (int @var{signo}) 750 751Given an signal number, returns a pointer to a string containing the 752symbolic name of that signal number, as found in @code{<signal.h>}. 753 754If the supplied signal number is within the valid range of indices for 755symbolic names, but no name is available for the particular signal 756number, then returns the string @samp{Signal @var{num}}, where 757@var{num} is the signal number. 758 759If the supplied signal number is not within the range of valid 760indices, then returns @code{NULL}. 761 762The contents of the location pointed to are only guaranteed to be 763valid until the next call to @code{strsigno}. 764 765@end deftypefn 766 767@c strstr.c:6 768@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub}) 769 770This function searches for the substring @var{sub} in the string 771@var{string}, not including the terminating null characters. A pointer 772to the first occurrence of @var{sub} is returned, or @code{NULL} if the 773substring is absent. If @var{sub} points to a string with zero 774length, the function returns @var{string}. 775 776@end deftypefn 777 778@c strtod.c:27 779@deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr}) 780 781This ISO C function converts the initial portion of @var{string} to a 782@code{double}. If @var{endptr} is not @code{NULL}, a pointer to the 783character after the last character used in the conversion is stored in 784the location referenced by @var{endptr}. If no conversion is 785performed, zero is returned and the value of @var{string} is stored in 786the location referenced by @var{endptr}. 787 788@end deftypefn 789 790@c strerror.c:730 791@deftypefn Extension int strtoerrno (const char *@var{name}) 792 793Given the symbolic name of a error number (e.g., @code{EACCES}), map it 794to an errno value. If no translation is found, returns 0. 795 796@end deftypefn 797 798@c strtol.c:33 799@deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base}) 800@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base}) 801 802The @code{strtol} function converts the string in @var{string} to a 803long integer value according to the given @var{base}, which must be 804between 2 and 36 inclusive, or be the special value 0. If @var{base} 805is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x} 806to indicate bases 8 and 16, respectively, else default to base 10. 807When the base is 16 (either explicitly or implicitly), a prefix of 808@code{0x} is allowed. The handling of @var{endptr} is as that of 809@code{strtod} above. The @code{strtoul} function is the same, except 810that the converted value is unsigned. 811 812@end deftypefn 813 814@c strsignal.c:507 815@deftypefn Extension int strtosigno (const char *@var{name}) 816 817Given the symbolic name of a signal, map it to a signal number. If no 818translation is found, returns 0. 819 820@end deftypefn 821 822@c tmpnam.c:3 823@deftypefn Supplemental char* tmpnam (char *@var{s}) 824 825This function attempts to create a name for a temporary file, which 826will be a valid file name yet not exist when @code{tmpnam} checks for 827it. @var{s} must point to a buffer of at least @code{L_tmpnam} bytes, 828or be @code{NULL}. Use of this function creates a security risk, and it must 829not be used in new projects. Use @code{mkstemp} instead. 830 831@end deftypefn 832 833@c vasprintf.c:48 834@deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args}) 835 836Like @code{vsprintf}, but instead of passing a pointer to a buffer, 837you pass a pointer to a pointer. This function will compute the size 838of the buffer needed, allocate memory with @code{malloc}, and store a 839pointer to the allocated memory in @code{*@var{resptr}}. The value 840returned is the same as @code{vsprintf} would return. If memory could 841not be allocated, zero is returned and @code{NULL} is stored in 842@code{*@var{resptr}}. 843 844@end deftypefn 845 846@c vfork.c:6 847@deftypefn Supplemental int vfork (void) 848 849Emulates @code{vfork} by calling @code{fork} and returning its value. 850 851@end deftypefn 852 853@c vprintf.c:3 854@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap}) 855@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap}) 856@deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap}) 857 858These functions are the same as @code{printf}, @code{fprintf}, and 859@code{sprintf}, respectively, except that they are called with a 860@code{va_list} instead of a variable number of arguments. Note that 861they do not call @code{va_end}; this is the application's 862responsibility. In @libib{} they are implemented in terms of the 863nonstandard but common function @code{_doprnt}. 864 865@end deftypefn 866 867@c waitpid.c:3 868@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int) 869 870This is a wrapper around the @code{wait} function. Any ``special'' 871values of @var{pid} depend on your implementation of @code{wait}, as 872does the return value. The third argument is unused in @libib{}. 873 874@end deftypefn 875 876@c xatexit.c:11 877@deftypefun int xatexit (void (*@var{fn}) (void)) 878 879Behaves as the standard @code{atexit} function, but with no limit on 880the number of registered functions. Returns 0 on success, or @minus{}1 on 881failure. If you use @code{xatexit} to register functions, you must use 882@code{xexit} to terminate your program. 883 884@end deftypefun 885 886@c xmalloc.c:38 887@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize}) 888 889Allocate memory without fail, and set it to zero. This routine functions 890like @code{calloc}, but will behave the same as @code{xmalloc} if memory 891cannot be found. 892 893@end deftypefn 894 895@c xexit.c:22 896@deftypefn Replacement void xexit (int @var{code}) 897 898Terminates the program. If any functions have been registered with 899the @code{xatexit} replacement function, they will be called first. 900Termination is handled via the system's normal @code{exit} call. 901 902@end deftypefn 903 904@c xmalloc.c:22 905@deftypefn Replacement void* xmalloc (size_t) 906 907Allocate memory without fail. If @code{malloc} fails, this will print 908a message to @code{stderr} (using the name set by 909@code{xmalloc_set_program_name}, 910if any) and then call @code{xexit}. Note that it is therefore safe for 911a program to contain @code{#define malloc xmalloc} in its source. 912 913@end deftypefn 914 915@c xmalloc.c:53 916@deftypefn Replacement void xmalloc_failed (size_t) 917 918This function is not meant to be called by client code, and is listed 919here for completeness only. If any of the allocation routines fail, this 920function will be called to print an error message and terminate execution. 921 922@end deftypefn 923 924@c xmalloc.c:46 925@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name}) 926 927You can use this to set the name of the program used by 928@code{xmalloc_failed} when printing a failure message. 929 930@end deftypefn 931 932@c xmemdup.c:7 933@deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size}) 934 935Duplicates a region of memory without fail. First, @var{alloc_size} bytes 936are allocated, then @var{copy_size} bytes from @var{input} are copied into 937it, and the new memory is returned. If fewer bytes are copied than were 938allocated, the remaining memory is zeroed. 939 940@end deftypefn 941 942@c xmalloc.c:32 943@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size}) 944Reallocate memory without fail. This routine functions like @code{realloc}, 945but will behave the same as @code{xmalloc} if memory cannot be found. 946 947@end deftypefn 948 949@c xstrdup.c:7 950@deftypefn Replacement char* xstrdup (const char *@var{s}) 951 952Duplicates a character string without fail, using @code{xmalloc} to 953obtain memory. 954 955@end deftypefn 956 957@c xstrerror.c:7 958@deftypefn Replacement char* xstrerror (int @var{errnum}) 959 960Behaves exactly like the standard @code{strerror} function, but 961will never return a @code{NULL} pointer. 962 963@end deftypefn 964 965 966