functions.texi revision 89857
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 index.c:5 321@deftypefn Supplemental char* index (char *@var{s}, int @var{c}) 322 323Returns a pointer to the first occurrence of the character @var{c} in 324the string @var{s}, or @code{NULL} if not found. The use of @code{index} is 325deprecated in new programs in favor of @code{strchr}. 326 327@end deftypefn 328 329@c insque.c:6 330@deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred}) 331@deftypefnx Supplemental void remque (struct qelem *@var{elem}) 332 333Routines to manipulate queues built from doubly linked lists. The 334@code{insque} routine inserts @var{elem} in the queue immediately 335after @var{pred}. The @code{remque} routine removes @var{elem} from 336its containing queue. These routines expect to be passed pointers to 337structures which have as their first members a forward pointer and a 338back pointer, like this prototype (although no prototype is provided): 339 340@example 341struct qelem @{ 342 struct qelem *q_forw; 343 struct qelem *q_back; 344 char q_data[]; 345@}; 346@end example 347 348@end deftypefn 349 350@c lbasename.c:23 351@deftypefn Replacement {const char*} lbasename (const char *@var{name}) 352 353Given a pointer to a string containing a typical pathname 354(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the 355last component of the pathname (@samp{ls.c} in this case). The 356returned pointer is guaranteed to lie within the original 357string. This latter fact is not true of many vendor C 358libraries, which return special strings or modify the passed 359strings for particular input. 360 361In particular, the empty string returns the same empty string, 362and a path ending in @code{/} returns the empty string after it. 363 364@end deftypefn 365 366@c make-temp-file.c:138 367@deftypefn Replacement char* make_temp_file (const char *@var{suffix}) 368 369Return a temporary file name (as a string) or @code{NULL} if unable to 370create one. @var{suffix} is a suffix to append to the file name. The 371string is @code{malloc}ed, and the temporary file has been created. 372 373@end deftypefn 374 375@c memchr.c:3 376@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n}) 377 378This function searches memory starting at @code{*@var{s}} for the 379character @var{c}. The search only ends with the first occurrence of 380@var{c}, or after @var{length} characters; in particular, a null 381character does not terminate the search. If the character @var{c} is 382found within @var{length} characters of @code{*@var{s}}, a pointer 383to the character is returned. If @var{c} is not found, then @code{NULL} is 384returned. 385 386@end deftypefn 387 388@c memcmp.c:6 389@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count}) 390 391Compares the first @var{count} bytes of two areas of memory. Returns 392zero if they are the same, a value less than zero if @var{x} is 393lexically less than @var{y}, or a value greater than zero if @var{x} 394is lexically greater than @var{y}. Note that lexical order is determined 395as if comparing unsigned char arrays. 396 397@end deftypefn 398 399@c memcpy.c:6 400@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length}) 401 402Copies @var{length} bytes from memory region @var{in} to region 403@var{out}. Returns a pointer to @var{out}. 404 405@end deftypefn 406 407@c memmove.c:6 408@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count}) 409 410Copies @var{count} bytes from memory area @var{from} to memory area 411@var{to}, returning a pointer to @var{to}. 412 413@end deftypefn 414 415@c memset.c:6 416@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count}) 417 418Sets the first @var{count} bytes of @var{s} to the constant byte 419@var{c}, returning a pointer to @var{s}. 420 421@end deftypefn 422 423@c mkstemps.c:54 424@deftypefn Replacement int mkstemps (char *@var{template}, int @var{suffix_len}) 425 426Generate a unique temporary file name from @var{template}. 427@var{template} has the form: 428 429@example 430 @var{path}/ccXXXXXX@var{suffix} 431@end example 432 433@var{suffix_len} tells us how long @var{suffix} is (it can be zero 434length). The last six characters of @var{template} before @var{suffix} 435must be @samp{XXXXXX}; they are replaced with a string that makes the 436filename unique. Returns a file descriptor open on the file for 437reading and writing. 438 439@end deftypefn 440 441@c pexecute.c:67 442@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) 443 444Executes a program. 445 446@var{program} and @var{argv} are the arguments to 447@code{execv}/@code{execvp}. 448 449@var{this_pname} is name of the calling program (i.e., @code{argv[0]}). 450 451@var{temp_base} is the path name, sans suffix, of a temporary file to 452use if needed. This is currently only needed for MS-DOS ports that 453don't use @code{go32} (do any still exist?). Ports that don't need it 454can pass @code{NULL}. 455 456(@code{@var{flags} & PEXECUTE_SEARCH}) is non-zero if @env{PATH} should be searched 457(??? It's not clear that GCC passes this flag correctly). (@code{@var{flags} & 458PEXECUTE_FIRST}) is nonzero for the first process in chain. 459(@code{@var{flags} & PEXECUTE_FIRST}) is nonzero for the last process 460in chain. The first/last flags could be simplified to only mark the 461last of a chain of processes but that requires the caller to always 462mark the last one (and not give up early if some error occurs). 463It's more robust to require the caller to mark both ends of the chain. 464 465The result is the pid on systems like Unix where we 466@code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we 467use @code{spawn}. It is up to the caller to wait for the child. 468 469The result is the @code{WEXITSTATUS} on systems like MS-DOS where we 470@code{spawn} and wait for the child here. 471 472Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the 473text of the error message with an optional argument (if not needed, 474@var{errmsg_arg} is set to @code{NULL}), and @minus{}1 is returned. 475@code{errno} is available to the caller to use. 476 477@end deftypefn 478 479@c strsignal.c:547 480@deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message}) 481 482Print @var{message} to the standard error, followed by a colon, 483followed by the description of the signal specified by @var{signo}, 484followed by a newline. 485 486@end deftypefn 487 488@c putenv.c:21 489@deftypefn Supplemental int putenv (const char *@var{string}) 490 491Uses @code{setenv} or @code{unsetenv} to put @var{string} into 492the environment or remove it. If @var{string} is of the form 493@samp{name=value} the string is added; if no @samp{=} is present the 494name is unset/removed. 495 496@end deftypefn 497 498@c pexecute.c:104 499@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) 500 501Waits for a program started by @code{pexecute} to finish. 502 503@var{pid} is the process id of the task to wait for. @var{status} is 504the `status' argument to wait. @var{flags} is currently unused (allows 505future enhancement without breaking upward compatibility). Pass 0 for now. 506 507The result is the pid of the child reaped, or -1 for failure 508(@code{errno} says why). 509 510On systems that don't support waiting for a particular child, @var{pid} is 511ignored. On systems like MS-DOS that don't really multitask @code{pwait} 512is just a mechanism to provide a consistent interface for the caller. 513 514@end deftypefn 515 516@c random.c:39 517@deftypefn Supplement {long int} random (void) 518@deftypefnx Supplement void srandom (unsigned int @var{seed}) 519@deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n}) 520@deftypefnx Supplement void* setstate (void *@var{arg_state}) 521 522Random number functions. @code{random} returns a random number in the 523range 0 to @code{LONG_MAX}. @code{srandom} initializes the random 524number generator to some starting point determined by @var{seed} 525(else, the values returned by @code{random} are always the same for each 526run of the program). @code{initstate} and @code{setstate} allow fine-grained 527control over the state of the random number generator. 528 529@end deftypefn 530 531@c concat.c:177 532@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL}) 533 534Same as @code{concat}, except that if @var{optr} is not @code{NULL} it 535is freed after the string is created. This is intended to be useful 536when you're extending an existing string or building up a string in a 537loop: 538 539@example 540 str = reconcat (str, "pre-", str, NULL); 541@end example 542 543@end deftypefn 544 545@c rename.c:6 546@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new}) 547 548Renames a file from @var{old} to @var{new}. If @var{new} already 549exists, it is removed. 550 551@end deftypefn 552 553@c rindex.c:5 554@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c}) 555 556Returns a pointer to the last occurrence of the character @var{c} in 557the string @var{s}, or @code{NULL} if not found. The use of @code{rindex} is 558deprecated in new programs in favor of @code{strrchr}. 559 560@end deftypefn 561 562@c setenv.c:22 563@deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite}) 564@deftypefnx Supplemental void unsetenv (const char *@var{name}) 565 566@code{setenv} adds @var{name} to the environment with value 567@var{value}. If the name was already present in the environment, 568the new value will be stored only if @var{overwrite} is nonzero. 569The companion @code{unsetenv} function removes @var{name} from the 570environment. This implementation is not safe for multithreaded code. 571 572@end deftypefn 573 574@c strsignal.c:353 575@deftypefn Extension int signo_max (void) 576 577Returns the maximum signal value for which a corresponding symbolic 578name or message is available. Note that in the case where we use the 579@code{sys_siglist} supplied by the system, it is possible for there to 580be more symbolic names than messages, or vice versa. In fact, the 581manual page for @code{psignal(3b)} explicitly warns that one should 582check the size of the table (@code{NSIG}) before indexing it, since 583new signal codes may be added to the system before they are added to 584the table. Thus @code{NSIG} might be smaller than value implied by 585the largest signo value defined in @code{<signal.h>}. 586 587We return the maximum value that can be used to obtain a meaningful 588symbolic name or message. 589 590@end deftypefn 591 592@c sigsetmask.c:8 593@deftypefn Supplemental int sigsetmask (int @var{set}) 594 595Sets the signal mask to the one provided in @var{set} and returns 596the old mask (which, for libiberty's implementation, will always 597be the value @code{1}). 598 599@end deftypefn 600 601@c spaces.c:22 602@deftypefn Extension char* spaces (int @var{count}) 603 604Returns a pointer to a memory region filled with the specified 605number of spaces and null terminated. The returned pointer is 606valid until at least the next call. 607 608@end deftypefn 609 610@c strcasecmp.c:15 611@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2}) 612 613A case-insensitive @code{strcmp}. 614 615@end deftypefn 616 617@c strchr.c:6 618@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c}) 619 620Returns a pointer to the first occurrence of the character @var{c} in 621the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 622null character, the results are undefined. 623 624@end deftypefn 625 626@c strdup.c:3 627@deftypefn Supplemental char* strdup (const char *@var{s}) 628 629Returns a pointer to a copy of @var{s} in memory obtained from 630@code{malloc}, or @code{NULL} if insufficient memory was available. 631 632@end deftypefn 633 634@c strerror.c:670 635@deftypefn Replacement {const char*} strerrno (int @var{errnum}) 636 637Given an error number returned from a system call (typically returned 638in @code{errno}), returns a pointer to a string containing the 639symbolic name of that error number, as found in @code{<errno.h>}. 640 641If the supplied error number is within the valid range of indices for 642symbolic names, but no name is available for the particular error 643number, then returns the string @samp{Error @var{num}}, where @var{num} 644is the error number. 645 646If the supplied error number is not within the range of valid 647indices, then returns @code{NULL}. 648 649The contents of the location pointed to are only guaranteed to be 650valid until the next call to @code{strerrno}. 651 652@end deftypefn 653 654@c strerror.c:602 655@deftypefn Supplemental char* strerror (int @var{errnoval}) 656 657Maps an @code{errno} number to an error message string, the contents 658of which are implementation defined. On systems which have the 659external variables @code{sys_nerr} and @code{sys_errlist}, these 660strings will be the same as the ones used by @code{perror}. 661 662If the supplied error number is within the valid range of indices for 663the @code{sys_errlist}, but no message is available for the particular 664error number, then returns the string @samp{Error @var{num}}, where 665@var{num} is the error number. 666 667If the supplied error number is not a valid index into 668@code{sys_errlist}, returns @code{NULL}. 669 670The returned string is only guaranteed to be valid only until the 671next call to @code{strerror}. 672 673@end deftypefn 674 675@c strncasecmp.c:15 676@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2}) 677 678A case-insensitive @code{strncmp}. 679 680@end deftypefn 681 682@c strncmp.c:6 683@deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) 684 685Compares the first @var{n} bytes of two strings, returning a value as 686@code{strcmp}. 687 688@end deftypefn 689 690@c strrchr.c:6 691@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c}) 692 693Returns a pointer to the last occurrence of the character @var{c} in 694the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 695null character, the results are undefined. 696 697@end deftypefn 698 699@c strsignal.c:388 700@deftypefn Supplemental {const char *} strsignal (int @var{signo}) 701 702Maps an signal number to an signal message string, the contents of 703which are implementation defined. On systems which have the external 704variable @code{sys_siglist}, these strings will be the same as the 705ones used by @code{psignal()}. 706 707If the supplied signal number is within the valid range of indices for 708the @code{sys_siglist}, but no message is available for the particular 709signal number, then returns the string @samp{Signal @var{num}}, where 710@var{num} is the signal number. 711 712If the supplied signal number is not a valid index into 713@code{sys_siglist}, returns @code{NULL}. 714 715The returned string is only guaranteed to be valid only until the next 716call to @code{strsignal}. 717 718@end deftypefn 719 720@c strsignal.c:452 721@deftypefn Extension {const char*} strsigno (int @var{signo}) 722 723Given an signal number, returns a pointer to a string containing the 724symbolic name of that signal number, as found in @code{<signal.h>}. 725 726If the supplied signal number is within the valid range of indices for 727symbolic names, but no name is available for the particular signal 728number, then returns the string @samp{Signal @var{num}}, where 729@var{num} is the signal number. 730 731If the supplied signal number is not within the range of valid 732indices, then returns @code{NULL}. 733 734The contents of the location pointed to are only guaranteed to be 735valid until the next call to @code{strsigno}. 736 737@end deftypefn 738 739@c strstr.c:6 740@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub}) 741 742This function searches for the substring @var{sub} in the string 743@var{string}, not including the terminating null characters. A pointer 744to the first occurrence of @var{sub} is returned, or @code{NULL} if the 745substring is absent. If @var{sub} points to a string with zero 746length, the function returns @var{string}. 747 748@end deftypefn 749 750@c strtod.c:27 751@deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr}) 752 753This ISO C function converts the initial portion of @var{string} to a 754@code{double}. If @var{endptr} is not @code{NULL}, a pointer to the 755character after the last character used in the conversion is stored in 756the location referenced by @var{endptr}. If no conversion is 757performed, zero is returned and the value of @var{string} is stored in 758the location referenced by @var{endptr}. 759 760@end deftypefn 761 762@c strerror.c:730 763@deftypefn Extension int strtoerrno (const char *@var{name}) 764 765Given the symbolic name of a error number (e.g., @code{EACCES}), map it 766to an errno value. If no translation is found, returns 0. 767 768@end deftypefn 769 770@c strtol.c:33 771@deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base}) 772@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base}) 773 774The @code{strtol} function converts the string in @var{string} to a 775long integer value according to the given @var{base}, which must be 776between 2 and 36 inclusive, or be the special value 0. If @var{base} 777is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x} 778to indicate bases 8 and 16, respectively, else default to base 10. 779When the base is 16 (either explicitly or implicitly), a prefix of 780@code{0x} is allowed. The handling of @var{endptr} is as that of 781@code{strtod} above. The @code{strtoul} function is the same, except 782that the converted value is unsigned. 783 784@end deftypefn 785 786@c strsignal.c:507 787@deftypefn Extension int strtosigno (const char *@var{name}) 788 789Given the symbolic name of a signal, map it to a signal number. If no 790translation is found, returns 0. 791 792@end deftypefn 793 794@c tmpnam.c:3 795@deftypefn Supplemental char* tmpnam (char *@var{s}) 796 797This function attempts to create a name for a temporary file, which 798will be a valid file name yet not exist when @code{tmpnam} checks for 799it. @var{s} must point to a buffer of at least @code{L_tmpnam} bytes, 800or be @code{NULL}. Use of this function creates a security risk, and it must 801not be used in new projects. Use @code{mkstemp} instead. 802 803@end deftypefn 804 805@c vasprintf.c:48 806@deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args}) 807 808Like @code{vsprintf}, but instead of passing a pointer to a buffer, 809you pass a pointer to a pointer. This function will compute the size 810of the buffer needed, allocate memory with @code{malloc}, and store a 811pointer to the allocated memory in @code{*@var{resptr}}. The value 812returned is the same as @code{vsprintf} would return. If memory could 813not be allocated, zero is returned and @code{NULL} is stored in 814@code{*@var{resptr}}. 815 816@end deftypefn 817 818@c vfork.c:6 819@deftypefn Supplemental int vfork (void) 820 821Emulates @code{vfork} by calling @code{fork} and returning its value. 822 823@end deftypefn 824 825@c vprintf.c:3 826@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap}) 827@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap}) 828@deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap}) 829 830These functions are the same as @code{printf}, @code{fprintf}, and 831@code{sprintf}, respectively, except that they are called with a 832@code{va_list} instead of a variable number of arguments. Note that 833they do not call @code{va_end}; this is the application's 834responsibility. In @libib{} they are implemented in terms of the 835nonstandard but common function @code{_doprnt}. 836 837@end deftypefn 838 839@c waitpid.c:3 840@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int) 841 842This is a wrapper around the @code{wait} function. Any ``special'' 843values of @var{pid} depend on your implementation of @code{wait}, as 844does the return value. The third argument is unused in @libib{}. 845 846@end deftypefn 847 848@c xatexit.c:11 849@deftypefun int xatexit (void (*@var{fn}) (void)) 850 851Behaves as the standard @code{atexit} function, but with no limit on 852the number of registered functions. Returns 0 on success, or @minus{}1 on 853failure. If you use @code{xatexit} to register functions, you must use 854@code{xexit} to terminate your program. 855 856@end deftypefun 857 858@c xmalloc.c:38 859@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize}) 860 861Allocate memory without fail, and set it to zero. This routine functions 862like @code{calloc}, but will behave the same as @code{xmalloc} if memory 863cannot be found. 864 865@end deftypefn 866 867@c xexit.c:22 868@deftypefn Replacement void xexit (int @var{code}) 869 870Terminates the program. If any functions have been registered with 871the @code{xatexit} replacement function, they will be called first. 872Termination is handled via the system's normal @code{exit} call. 873 874@end deftypefn 875 876@c xmalloc.c:22 877@deftypefn Replacement void* xmalloc (size_t) 878 879Allocate memory without fail. If @code{malloc} fails, this will print 880a message to @code{stderr} (using the name set by 881@code{xmalloc_set_program_name}, 882if any) and then call @code{xexit}. Note that it is therefore safe for 883a program to contain @code{#define malloc xmalloc} in its source. 884 885@end deftypefn 886 887@c xmalloc.c:53 888@deftypefn Replacement void xmalloc_failed (size_t) 889 890This function is not meant to be called by client code, and is listed 891here for completeness only. If any of the allocation routines fail, this 892function will be called to print an error message and terminate execution. 893 894@end deftypefn 895 896@c xmalloc.c:46 897@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name}) 898 899You can use this to set the name of the program used by 900@code{xmalloc_failed} when printing a failure message. 901 902@end deftypefn 903 904@c xmemdup.c:7 905@deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size}) 906 907Duplicates a region of memory without fail. First, @var{alloc_size} bytes 908are allocated, then @var{copy_size} bytes from @var{input} are copied into 909it, and the new memory is returned. If fewer bytes are copied than were 910allocated, the remaining memory is zeroed. 911 912@end deftypefn 913 914@c xmalloc.c:32 915@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size}) 916Reallocate memory without fail. This routine functions like @code{realloc}, 917but will behave the same as @code{xmalloc} if memory cannot be found. 918 919@end deftypefn 920 921@c xstrdup.c:7 922@deftypefn Replacement char* xstrdup (const char *@var{s}) 923 924Duplicates a character string without fail, using @code{xmalloc} to 925obtain memory. 926 927@end deftypefn 928 929@c xstrerror.c:7 930@deftypefn Replacement char* xstrerror (int @var{errnum}) 931 932Behaves exactly like the standard @code{strerror} function, but 933will never return a @code{NULL} pointer. 934 935@end deftypefn 936 937 938