functions.texi revision 169695
1169695Skan@c Automatically generated from *.c and others (the comments before 2169695Skan@c each entry tell you which file and where in that file). DO NOT EDIT! 3169695Skan@c Edit the *.c files, configure with --enable-maintainer-mode, 4169695Skan@c and let gather-docs build you a new copy. 5169695Skan 6169695Skan@c safe-ctype.c:25 7169695Skan@defvr Extension HOST_CHARSET 8169695SkanThis macro indicates the basic character set and encoding used by the 9169695Skanhost: more precisely, the encoding used for character constants in 10169695Skanpreprocessor @samp{#if} statements (the C "execution character set"). 11169695SkanIt is defined by @file{safe-ctype.h}, and will be an integer constant 12169695Skanwith one of the following values: 13169695Skan 14169695Skan@ftable @code 15169695Skan@item HOST_CHARSET_UNKNOWN 16169695SkanThe host character set is unknown - that is, not one of the next two 17169695Skanpossibilities. 18169695Skan 19169695Skan@item HOST_CHARSET_ASCII 20169695SkanThe host character set is ASCII. 21169695Skan 22169695Skan@item HOST_CHARSET_EBCDIC 23169695SkanThe host character set is some variant of EBCDIC. (Only one of the 24169695Skannineteen EBCDIC varying characters is tested; exercise caution.) 25169695Skan@end ftable 26169695Skan@end defvr 27169695Skan 28169695Skan@c alloca.c:26 29169695Skan@deftypefn Replacement void* alloca (size_t @var{size}) 30169695Skan 31169695SkanThis function allocates memory which will be automatically reclaimed 32169695Skanafter the procedure exits. The @libib{} implementation does not free 33169695Skanthe memory immediately but will do so eventually during subsequent 34169695Skancalls to this function. Memory is allocated using @code{xmalloc} under 35169695Skannormal circumstances. 36169695Skan 37169695SkanThe header file @file{alloca-conf.h} can be used in conjunction with the 38169695SkanGNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make 39169695Skanavailable this function. The @code{AC_FUNC_ALLOCA} test requires that 40169695Skanclient code use a block of preprocessor code to be safe (see the Autoconf 41169695Skanmanual for more); this header incorporates that logic and more, including 42169695Skanthe possibility of a GCC built-in function. 43169695Skan 44169695Skan@end deftypefn 45169695Skan 46169695Skan@c asprintf.c:32 47169695Skan@deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...) 48169695Skan 49169695SkanLike @code{sprintf}, but instead of passing a pointer to a buffer, you 50169695Skanpass a pointer to a pointer. This function will compute the size of 51169695Skanthe buffer needed, allocate memory with @code{malloc}, and store a 52169695Skanpointer to the allocated memory in @code{*@var{resptr}}. The value 53169695Skanreturned is the same as @code{sprintf} would return. If memory could 54169695Skannot be allocated, minus one is returned and @code{NULL} is stored in 55169695Skan@code{*@var{resptr}}. 56169695Skan 57169695Skan@end deftypefn 58169695Skan 59169695Skan@c atexit.c:6 60169695Skan@deftypefn Supplemental int atexit (void (*@var{f})()) 61169695Skan 62169695SkanCauses function @var{f} to be called at exit. Returns 0. 63169695Skan 64169695Skan@end deftypefn 65169695Skan 66169695Skan@c basename.c:6 67169695Skan@deftypefn Supplemental char* basename (const char *@var{name}) 68169695Skan 69169695SkanReturns a pointer to the last component of pathname @var{name}. 70169695SkanBehavior is undefined if the pathname ends in a directory separator. 71169695Skan 72169695Skan@end deftypefn 73169695Skan 74169695Skan@c bcmp.c:6 75169695Skan@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count}) 76169695Skan 77169695SkanCompares the first @var{count} bytes of two areas of memory. Returns 78169695Skanzero if they are the same, nonzero otherwise. Returns zero if 79169695Skan@var{count} is zero. A nonzero result only indicates a difference, 80169695Skanit does not indicate any sorting order (say, by having a positive 81169695Skanresult mean @var{x} sorts before @var{y}). 82169695Skan 83169695Skan@end deftypefn 84169695Skan 85169695Skan@c bcopy.c:3 86169695Skan@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length}) 87169695Skan 88169695SkanCopies @var{length} bytes from memory region @var{in} to region 89169695Skan@var{out}. The use of @code{bcopy} is deprecated in new programs. 90169695Skan 91169695Skan@end deftypefn 92169695Skan 93169695Skan@c bsearch.c:33 94169695Skan@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 *)) 95169695Skan 96169695SkanPerforms a search over an array of @var{nmemb} elements pointed to by 97169695Skan@var{base} for a member that matches the object pointed to by @var{key}. 98169695SkanThe size of each member is specified by @var{size}. The array contents 99169695Skanshould be sorted in ascending order according to the @var{compar} 100169695Skancomparison function. This routine should take two arguments pointing to 101169695Skanthe @var{key} and to an array member, in that order, and should return an 102169695Skaninteger less than, equal to, or greater than zero if the @var{key} object 103169695Skanis respectively less than, matching, or greater than the array member. 104169695Skan 105169695Skan@end deftypefn 106169695Skan 107169695Skan@c argv.c:124 108169695Skan@deftypefn Extension char** buildargv (char *@var{sp}) 109169695Skan 110169695SkanGiven a pointer to a string, parse the string extracting fields 111169695Skanseparated by whitespace and optionally enclosed within either single 112169695Skanor double quotes (which are stripped off), and build a vector of 113169695Skanpointers to copies of the string for each field. The input string 114169695Skanremains unchanged. The last element of the vector is followed by a 115169695Skan@code{NULL} element. 116169695Skan 117169695SkanAll of the memory for the pointer array and copies of the string 118169695Skanis obtained from @code{malloc}. All of the memory can be returned to the 119169695Skansystem with the single function call @code{freeargv}, which takes the 120169695Skanreturned result of @code{buildargv}, as it's argument. 121169695Skan 122169695SkanReturns a pointer to the argument vector if successful. Returns 123169695Skan@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient 124169695Skanmemory to complete building the argument vector. 125169695Skan 126169695SkanIf the input is a null string (as opposed to a @code{NULL} pointer), 127169695Skanthen buildarg returns an argument vector that has one arg, a null 128169695Skanstring. 129169695Skan 130169695Skan@end deftypefn 131169695Skan 132169695Skan@c bzero.c:6 133169695Skan@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count}) 134169695Skan 135169695SkanZeros @var{count} bytes starting at @var{mem}. Use of this function 136169695Skanis deprecated in favor of @code{memset}. 137169695Skan 138169695Skan@end deftypefn 139169695Skan 140169695Skan@c calloc.c:6 141169695Skan@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize}) 142169695Skan 143169695SkanUses @code{malloc} to allocate storage for @var{nelem} objects of 144169695Skan@var{elsize} bytes each, then zeros the memory. 145169695Skan 146169695Skan@end deftypefn 147169695Skan 148169695Skan@c choose-temp.c:42 149169695Skan@deftypefn Extension char* choose_temp_base (void) 150169695Skan 151169695SkanReturn a prefix for temporary file names or @code{NULL} if unable to 152169695Skanfind one. The current directory is chosen if all else fails so the 153169695Skanprogram is exited if a temporary directory can't be found (@code{mktemp} 154169695Skanfails). The buffer for the result is obtained with @code{xmalloc}. 155169695Skan 156169695SkanThis function is provided for backwards compatability only. Its use is 157169695Skannot recommended. 158169695Skan 159169695Skan@end deftypefn 160169695Skan 161169695Skan@c make-temp-file.c:87 162169695Skan@deftypefn Replacement char* choose_tmpdir () 163169695Skan 164169695SkanReturns a pointer to a directory path suitable for creating temporary 165169695Skanfiles in. 166169695Skan 167169695Skan@end deftypefn 168169695Skan 169169695Skan@c clock.c:27 170169695Skan@deftypefn Supplemental long clock (void) 171169695Skan 172169695SkanReturns an approximation of the CPU time used by the process as a 173169695Skan@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the 174169695Skannumber of seconds used. 175169695Skan 176169695Skan@end deftypefn 177169695Skan 178169695Skan@c concat.c:24 179169695Skan@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL}) 180169695Skan 181169695SkanConcatenate zero or more of strings and return the result in freshly 182169695Skan@code{xmalloc}ed memory. Returns @code{NULL} if insufficient memory is 183169695Skanavailable. The argument list is terminated by the first @code{NULL} 184169695Skanpointer encountered. Pointers to empty strings are ignored. 185169695Skan 186169695Skan@end deftypefn 187169695Skan 188169695Skan@c argv.c:52 189169695Skan@deftypefn Extension char** dupargv (char **@var{vector}) 190169695Skan 191169695SkanDuplicate an argument vector. Simply scans through @var{vector}, 192169695Skanduplicating each argument until the terminating @code{NULL} is found. 193169695SkanReturns a pointer to the argument vector if successful. Returns 194169695Skan@code{NULL} if there is insufficient memory to complete building the 195169695Skanargument vector. 196169695Skan 197169695Skan@end deftypefn 198169695Skan 199169695Skan@c strerror.c:567 200169695Skan@deftypefn Extension int errno_max (void) 201169695Skan 202169695SkanReturns the maximum @code{errno} value for which a corresponding 203169695Skansymbolic name or message is available. Note that in the case where we 204169695Skanuse the @code{sys_errlist} supplied by the system, it is possible for 205169695Skanthere to be more symbolic names than messages, or vice versa. In 206169695Skanfact, the manual page for @code{perror(3C)} explicitly warns that one 207169695Skanshould check the size of the table (@code{sys_nerr}) before indexing 208169695Skanit, since new error codes may be added to the system before they are 209169695Skanadded to the table. Thus @code{sys_nerr} might be smaller than value 210169695Skanimplied by the largest @code{errno} value defined in @code{<errno.h>}. 211169695Skan 212169695SkanWe return the maximum value that can be used to obtain a meaningful 213169695Skansymbolic name or message. 214169695Skan 215169695Skan@end deftypefn 216169695Skan 217169695Skan@c argv.c:293 218169695Skan@deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp}) 219169695Skan 220169695SkanThe @var{argcp} and @code{argvp} arguments are pointers to the usual 221169695Skan@code{argc} and @code{argv} arguments to @code{main}. This function 222169695Skanlooks for arguments that begin with the character @samp{@@}. Any such 223169695Skanarguments are interpreted as ``response files''. The contents of the 224169695Skanresponse file are interpreted as additional command line options. In 225169695Skanparticular, the file is separated into whitespace-separated strings; 226169695Skaneach such string is taken as a command-line option. The new options 227169695Skanare inserted in place of the option naming the response file, and 228169695Skan@code{*argcp} and @code{*argvp} will be updated. If the value of 229169695Skan@code{*argvp} is modified by this function, then the new value has 230169695Skanbeen dynamically allocated and can be deallocated by the caller with 231169695Skan@code{freeargv}. However, most callers will simply call 232169695Skan@code{expandargv} near the beginning of @code{main} and allow the 233169695Skanoperating system to free the memory when the program exits. 234169695Skan 235169695Skan@end deftypefn 236169695Skan 237169695Skan@c fdmatch.c:23 238169695Skan@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2}) 239169695Skan 240169695SkanCheck to see if two open file descriptors refer to the same file. 241169695SkanThis is useful, for example, when we have an open file descriptor for 242169695Skanan unnamed file, and the name of a file that we believe to correspond 243169695Skanto that fd. This can happen when we are exec'd with an already open 244169695Skanfile (@code{stdout} for example) or from the SVR4 @file{/proc} calls 245169695Skanthat return open file descriptors for mapped address spaces. All we 246169695Skanhave to do is open the file by name and check the two file descriptors 247169695Skanfor a match, which is done by comparing major and minor device numbers 248169695Skanand inode numbers. 249169695Skan 250169695Skan@end deftypefn 251169695Skan 252169695Skan@c fopen_unlocked.c:48 253169695Skan@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, const char * @var{mode}) 254169695Skan 255169695SkanOpens and returns a @code{FILE} pointer via @code{fdopen}. If the 256169695Skanoperating system supports it, ensure that the stream is setup to avoid 257169695Skanany multi-threaded locking. Otherwise return the @code{FILE} pointer 258169695Skanunchanged. 259169695Skan 260169695Skan@end deftypefn 261169695Skan 262169695Skan@c ffs.c:3 263169695Skan@deftypefn Supplemental int ffs (int @var{valu}) 264169695Skan 265169695SkanFind the first (least significant) bit set in @var{valu}. Bits are 266169695Skannumbered from right to left, starting with bit 1 (corresponding to the 267169695Skanvalue 1). If @var{valu} is zero, zero is returned. 268169695Skan 269169695Skan@end deftypefn 270169695Skan 271169695Skan@c fnmatch.txh:1 272169695Skan@deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags}) 273169695Skan 274169695SkanMatches @var{string} against @var{pattern}, returning zero if it 275169695Skanmatches, @code{FNM_NOMATCH} if not. @var{pattern} may contain the 276169695Skanwildcards @code{?} to match any one character, @code{*} to match any 277169695Skanzero or more characters, or a set of alternate characters in square 278169695Skanbrackets, like @samp{[a-gt8]}, which match one character (@code{a} 279169695Skanthrough @code{g}, or @code{t}, or @code{8}, in this example) if that one 280169695Skancharacter is in the set. A set may be inverted (i.e., match anything 281169695Skanexcept what's in the set) by giving @code{^} or @code{!} as the first 282169695Skancharacter in the set. To include those characters in the set, list them 283169695Skanas anything other than the first character of the set. To include a 284169695Skandash in the set, list it last in the set. A backslash character makes 285169695Skanthe following character not special, so for example you could match 286169695Skanagainst a literal asterisk with @samp{\*}. To match a literal 287169695Skanbackslash, use @samp{\\}. 288169695Skan 289169695Skan@code{flags} controls various aspects of the matching process, and is a 290169695Skanboolean OR of zero or more of the following values (defined in 291169695Skan@code{<fnmatch.h>}): 292169695Skan 293169695Skan@table @code 294169695Skan 295169695Skan@item FNM_PATHNAME 296169695Skan@itemx FNM_FILE_NAME 297169695Skan@var{string} is assumed to be a path name. No wildcard will ever match 298169695Skan@code{/}. 299169695Skan 300169695Skan@item FNM_NOESCAPE 301169695SkanDo not interpret backslashes as quoting the following special character. 302169695Skan 303169695Skan@item FNM_PERIOD 304169695SkanA leading period (at the beginning of @var{string}, or if 305169695Skan@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or 306169695Skan@code{?} but must be matched explicitly. 307169695Skan 308169695Skan@item FNM_LEADING_DIR 309169695SkanMeans that @var{string} also matches @var{pattern} if some initial part 310169695Skanof @var{string} matches, and is followed by @code{/} and zero or more 311169695Skancharacters. For example, @samp{foo*} would match either @samp{foobar} 312169695Skanor @samp{foobar/grill}. 313169695Skan 314169695Skan@item FNM_CASEFOLD 315169695SkanIgnores case when performing the comparison. 316169695Skan 317169695Skan@end table 318169695Skan 319169695Skan@end deftypefn 320169695Skan 321169695Skan@c fopen_unlocked.c:39 322169695Skan@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, const char * @var{mode}) 323169695Skan 324169695SkanOpens and returns a @code{FILE} pointer via @code{fopen}. If the 325169695Skanoperating system supports it, ensure that the stream is setup to avoid 326169695Skanany multi-threaded locking. Otherwise return the @code{FILE} pointer 327169695Skanunchanged. 328169695Skan 329169695Skan@end deftypefn 330169695Skan 331169695Skan@c argv.c:97 332169695Skan@deftypefn Extension void freeargv (char **@var{vector}) 333169695Skan 334169695SkanFree an argument vector that was built using @code{buildargv}. Simply 335169695Skanscans through @var{vector}, freeing the memory for each argument until 336169695Skanthe terminating @code{NULL} is found, and then frees @var{vector} 337169695Skanitself. 338169695Skan 339169695Skan@end deftypefn 340169695Skan 341169695Skan@c fopen_unlocked.c:57 342169695Skan@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, const char * @var{mode}, FILE * @var{stream}) 343169695Skan 344169695SkanOpens and returns a @code{FILE} pointer via @code{freopen}. If the 345169695Skanoperating system supports it, ensure that the stream is setup to avoid 346169695Skanany multi-threaded locking. Otherwise return the @code{FILE} pointer 347169695Skanunchanged. 348169695Skan 349169695Skan@end deftypefn 350169695Skan 351169695Skan@c getruntime.c:82 352169695Skan@deftypefn Replacement long get_run_time (void) 353169695Skan 354169695SkanReturns the time used so far, in microseconds. If possible, this is 355169695Skanthe time used by this process, else it is the elapsed time since the 356169695Skanprocess started. 357169695Skan 358169695Skan@end deftypefn 359169695Skan 360169695Skan@c getcwd.c:6 361169695Skan@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len}) 362169695Skan 363169695SkanCopy the absolute pathname for the current working directory into 364169695Skan@var{pathname}, which is assumed to point to a buffer of at least 365169695Skan@var{len} bytes, and return a pointer to the buffer. If the current 366169695Skandirectory's path doesn't fit in @var{len} characters, the result is 367169695Skan@code{NULL} and @code{errno} is set. If @var{pathname} is a null pointer, 368169695Skan@code{getcwd} will obtain @var{len} bytes of space using 369169695Skan@code{malloc}. 370169695Skan 371169695Skan@end deftypefn 372169695Skan 373169695Skan@c getpagesize.c:5 374169695Skan@deftypefn Supplemental int getpagesize (void) 375169695Skan 376169695SkanReturns the number of bytes in a page of memory. This is the 377169695Skangranularity of many of the system memory management routines. No 378169695Skanguarantee is made as to whether or not it is the same as the basic 379169695Skanmemory management hardware page size. 380169695Skan 381169695Skan@end deftypefn 382169695Skan 383169695Skan@c getpwd.c:5 384169695Skan@deftypefn Supplemental char* getpwd (void) 385169695Skan 386169695SkanReturns the current working directory. This implementation caches the 387169695Skanresult on the assumption that the process will not call @code{chdir} 388169695Skanbetween calls to @code{getpwd}. 389169695Skan 390169695Skan@end deftypefn 391169695Skan 392169695Skan@c gettimeofday.c:12 393169695Skan@deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz}) 394169695Skan 395169695SkanWrites the current time to @var{tp}. This implementation requires 396169695Skanthat @var{tz} be NULL. Returns 0 on success, -1 on failure. 397169695Skan 398169695Skan@end deftypefn 399169695Skan 400169695Skan@c hex.c:33 401169695Skan@deftypefn Extension void hex_init (void) 402169695Skan 403169695SkanInitializes the array mapping the current character set to 404169695Skancorresponding hex values. This function must be called before any 405169695Skancall to @code{hex_p} or @code{hex_value}. If you fail to call it, a 406169695Skandefault ASCII-based table will normally be used on ASCII systems. 407169695Skan 408169695Skan@end deftypefn 409169695Skan 410169695Skan@c hex.c:42 411169695Skan@deftypefn Extension int hex_p (int @var{c}) 412169695Skan 413169695SkanEvaluates to non-zero if the given character is a valid hex character, 414169695Skanor zero if it is not. Note that the value you pass will be cast to 415169695Skan@code{unsigned char} within the macro. 416169695Skan 417169695Skan@end deftypefn 418169695Skan 419169695Skan@c hex.c:50 420169695Skan@deftypefn Extension {unsigned int} hex_value (int @var{c}) 421169695Skan 422169695SkanReturns the numeric equivalent of the given character when interpreted 423169695Skanas a hexidecimal digit. The result is undefined if you pass an 424169695Skaninvalid hex digit. Note that the value you pass will be cast to 425169695Skan@code{unsigned char} within the macro. 426169695Skan 427169695SkanThe @code{hex_value} macro returns @code{unsigned int}, rather than 428169695Skansigned @code{int}, to make it easier to use in parsing addresses from 429169695Skanhex dump files: a signed @code{int} would be sign-extended when 430169695Skanconverted to a wider unsigned type --- like @code{bfd_vma}, on some 431169695Skansystems. 432169695Skan 433169695Skan@end deftypefn 434169695Skan 435169695Skan@c index.c:5 436169695Skan@deftypefn Supplemental char* index (char *@var{s}, int @var{c}) 437169695Skan 438169695SkanReturns a pointer to the first occurrence of the character @var{c} in 439169695Skanthe string @var{s}, or @code{NULL} if not found. The use of @code{index} is 440169695Skandeprecated in new programs in favor of @code{strchr}. 441169695Skan 442169695Skan@end deftypefn 443169695Skan 444169695Skan@c insque.c:6 445169695Skan@deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred}) 446169695Skan@deftypefnx Supplemental void remque (struct qelem *@var{elem}) 447169695Skan 448169695SkanRoutines to manipulate queues built from doubly linked lists. The 449169695Skan@code{insque} routine inserts @var{elem} in the queue immediately 450169695Skanafter @var{pred}. The @code{remque} routine removes @var{elem} from 451169695Skanits containing queue. These routines expect to be passed pointers to 452169695Skanstructures which have as their first members a forward pointer and a 453169695Skanback pointer, like this prototype (although no prototype is provided): 454169695Skan 455169695Skan@example 456169695Skanstruct qelem @{ 457169695Skan struct qelem *q_forw; 458169695Skan struct qelem *q_back; 459169695Skan char q_data[]; 460169695Skan@}; 461169695Skan@end example 462169695Skan 463169695Skan@end deftypefn 464169695Skan 465169695Skan@c safe-ctype.c:46 466169695Skan@deffn Extension ISALPHA (@var{c}) 467169695Skan@deffnx Extension ISALNUM (@var{c}) 468169695Skan@deffnx Extension ISBLANK (@var{c}) 469169695Skan@deffnx Extension ISCNTRL (@var{c}) 470169695Skan@deffnx Extension ISDIGIT (@var{c}) 471169695Skan@deffnx Extension ISGRAPH (@var{c}) 472169695Skan@deffnx Extension ISLOWER (@var{c}) 473169695Skan@deffnx Extension ISPRINT (@var{c}) 474169695Skan@deffnx Extension ISPUNCT (@var{c}) 475169695Skan@deffnx Extension ISSPACE (@var{c}) 476169695Skan@deffnx Extension ISUPPER (@var{c}) 477169695Skan@deffnx Extension ISXDIGIT (@var{c}) 478169695Skan 479169695SkanThese twelve macros are defined by @file{safe-ctype.h}. Each has the 480169695Skansame meaning as the corresponding macro (with name in lowercase) 481169695Skandefined by the standard header @file{ctype.h}. For example, 482169695Skan@code{ISALPHA} returns true for alphabetic characters and false for 483169695Skanothers. However, there are two differences between these macros and 484169695Skanthose provided by @file{ctype.h}: 485169695Skan 486169695Skan@itemize @bullet 487169695Skan@item These macros are guaranteed to have well-defined behavior for all 488169695Skanvalues representable by @code{signed char} and @code{unsigned char}, and 489169695Skanfor @code{EOF}. 490169695Skan 491169695Skan@item These macros ignore the current locale; they are true for these 492169695Skanfixed sets of characters: 493169695Skan@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada} 494169695Skan@item @code{ALPHA} @tab @kbd{A-Za-z} 495169695Skan@item @code{ALNUM} @tab @kbd{A-Za-z0-9} 496169695Skan@item @code{BLANK} @tab @kbd{space tab} 497169695Skan@item @code{CNTRL} @tab @code{!PRINT} 498169695Skan@item @code{DIGIT} @tab @kbd{0-9} 499169695Skan@item @code{GRAPH} @tab @code{ALNUM || PUNCT} 500169695Skan@item @code{LOWER} @tab @kbd{a-z} 501169695Skan@item @code{PRINT} @tab @code{GRAPH ||} @kbd{space} 502169695Skan@item @code{PUNCT} @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?} 503169695Skan@item @code{SPACE} @tab @kbd{space tab \n \r \f \v} 504169695Skan@item @code{UPPER} @tab @kbd{A-Z} 505169695Skan@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f} 506169695Skan@end multitable 507169695Skan 508169695SkanNote that, if the host character set is ASCII or a superset thereof, 509169695Skanall these macros will return false for all values of @code{char} outside 510169695Skanthe range of 7-bit ASCII. In particular, both ISPRINT and ISCNTRL return 511169695Skanfalse for characters with numeric values from 128 to 255. 512169695Skan@end itemize 513169695Skan@end deffn 514169695Skan 515169695Skan@c safe-ctype.c:95 516169695Skan@deffn Extension ISIDNUM (@var{c}) 517169695Skan@deffnx Extension ISIDST (@var{c}) 518169695Skan@deffnx Extension IS_VSPACE (@var{c}) 519169695Skan@deffnx Extension IS_NVSPACE (@var{c}) 520169695Skan@deffnx Extension IS_SPACE_OR_NUL (@var{c}) 521169695Skan@deffnx Extension IS_ISOBASIC (@var{c}) 522169695SkanThese six macros are defined by @file{safe-ctype.h} and provide 523169695Skanadditional character classes which are useful when doing lexical 524169695Skananalysis of C or similar languages. They are true for the following 525169695Skansets of characters: 526169695Skan 527169695Skan@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada} 528169695Skan@item @code{IDNUM} @tab @kbd{A-Za-z0-9_} 529169695Skan@item @code{IDST} @tab @kbd{A-Za-z_} 530169695Skan@item @code{VSPACE} @tab @kbd{\r \n} 531169695Skan@item @code{NVSPACE} @tab @kbd{space tab \f \v \0} 532169695Skan@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE} 533169695Skan@item @code{ISOBASIC} @tab @code{VSPACE || NVSPACE || PRINT} 534169695Skan@end multitable 535169695Skan@end deffn 536169695Skan 537169695Skan@c lbasename.c:23 538169695Skan@deftypefn Replacement {const char*} lbasename (const char *@var{name}) 539169695Skan 540169695SkanGiven a pointer to a string containing a typical pathname 541169695Skan(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the 542169695Skanlast component of the pathname (@samp{ls.c} in this case). The 543169695Skanreturned pointer is guaranteed to lie within the original 544169695Skanstring. This latter fact is not true of many vendor C 545169695Skanlibraries, which return special strings or modify the passed 546169695Skanstrings for particular input. 547169695Skan 548169695SkanIn particular, the empty string returns the same empty string, 549169695Skanand a path ending in @code{/} returns the empty string after it. 550169695Skan 551169695Skan@end deftypefn 552169695Skan 553169695Skan@c lrealpath.c:25 554169695Skan@deftypefn Replacement {const char*} lrealpath (const char *@var{name}) 555169695Skan 556169695SkanGiven a pointer to a string containing a pathname, returns a canonical 557169695Skanversion of the filename. Symlinks will be resolved, and ``.'' and ``..'' 558169695Skancomponents will be simplified. The returned value will be allocated using 559169695Skan@code{malloc}, or @code{NULL} will be returned on a memory allocation error. 560169695Skan 561169695Skan@end deftypefn 562169695Skan 563169695Skan@c make-relative-prefix.c:24 564169695Skan@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, const char *@var{bin_prefix}, const char *@var{prefix}) 565169695Skan 566169695SkanGiven three paths @var{progname}, @var{bin_prefix}, @var{prefix}, 567169695Skanreturn the path that is in the same position relative to 568169695Skan@var{progname}'s directory as @var{prefix} is relative to 569169695Skan@var{bin_prefix}. That is, a string starting with the directory 570169695Skanportion of @var{progname}, followed by a relative pathname of the 571169695Skandifference between @var{bin_prefix} and @var{prefix}. 572169695Skan 573169695SkanIf @var{progname} does not contain any directory separators, 574169695Skan@code{make_relative_prefix} will search @env{PATH} to find a program 575169695Skannamed @var{progname}. Also, if @var{progname} is a symbolic link, 576169695Skanthe symbolic link will be resolved. 577169695Skan 578169695SkanFor example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta}, 579169695Skan@var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is 580169695Skan@code{/red/green/blue/gcc}, then this function will return 581169695Skan@code{/red/green/blue/../../omega/}. 582169695Skan 583169695SkanThe return value is normally allocated via @code{malloc}. If no 584169695Skanrelative prefix can be found, return @code{NULL}. 585169695Skan 586169695Skan@end deftypefn 587169695Skan 588169695Skan@c make-temp-file.c:137 589169695Skan@deftypefn Replacement char* make_temp_file (const char *@var{suffix}) 590169695Skan 591169695SkanReturn a temporary file name (as a string) or @code{NULL} if unable to 592169695Skancreate one. @var{suffix} is a suffix to append to the file name. The 593169695Skanstring is @code{malloc}ed, and the temporary file has been created. 594169695Skan 595169695Skan@end deftypefn 596169695Skan 597169695Skan@c memchr.c:3 598169695Skan@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n}) 599169695Skan 600169695SkanThis function searches memory starting at @code{*@var{s}} for the 601169695Skancharacter @var{c}. The search only ends with the first occurrence of 602169695Skan@var{c}, or after @var{length} characters; in particular, a null 603169695Skancharacter does not terminate the search. If the character @var{c} is 604169695Skanfound within @var{length} characters of @code{*@var{s}}, a pointer 605169695Skanto the character is returned. If @var{c} is not found, then @code{NULL} is 606169695Skanreturned. 607169695Skan 608169695Skan@end deftypefn 609169695Skan 610169695Skan@c memcmp.c:6 611169695Skan@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count}) 612169695Skan 613169695SkanCompares the first @var{count} bytes of two areas of memory. Returns 614169695Skanzero if they are the same, a value less than zero if @var{x} is 615169695Skanlexically less than @var{y}, or a value greater than zero if @var{x} 616169695Skanis lexically greater than @var{y}. Note that lexical order is determined 617169695Skanas if comparing unsigned char arrays. 618169695Skan 619169695Skan@end deftypefn 620169695Skan 621169695Skan@c memcpy.c:6 622169695Skan@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length}) 623169695Skan 624169695SkanCopies @var{length} bytes from memory region @var{in} to region 625169695Skan@var{out}. Returns a pointer to @var{out}. 626169695Skan 627169695Skan@end deftypefn 628169695Skan 629169695Skan@c memmove.c:6 630169695Skan@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count}) 631169695Skan 632169695SkanCopies @var{count} bytes from memory area @var{from} to memory area 633169695Skan@var{to}, returning a pointer to @var{to}. 634169695Skan 635169695Skan@end deftypefn 636169695Skan 637169695Skan@c mempcpy.c:23 638169695Skan@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, size_t @var{length}) 639169695Skan 640169695SkanCopies @var{length} bytes from memory region @var{in} to region 641169695Skan@var{out}. Returns a pointer to @var{out} + @var{length}. 642169695Skan 643169695Skan@end deftypefn 644169695Skan 645169695Skan@c memset.c:6 646169695Skan@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count}) 647169695Skan 648169695SkanSets the first @var{count} bytes of @var{s} to the constant byte 649169695Skan@var{c}, returning a pointer to @var{s}. 650169695Skan 651169695Skan@end deftypefn 652169695Skan 653169695Skan@c mkstemps.c:54 654169695Skan@deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len}) 655169695Skan 656169695SkanGenerate a unique temporary file name from @var{pattern}. 657169695Skan@var{pattern} has the form: 658169695Skan 659169695Skan@example 660169695Skan @var{path}/ccXXXXXX@var{suffix} 661169695Skan@end example 662169695Skan 663169695Skan@var{suffix_len} tells us how long @var{suffix} is (it can be zero 664169695Skanlength). The last six characters of @var{pattern} before @var{suffix} 665169695Skanmust be @samp{XXXXXX}; they are replaced with a string that makes the 666169695Skanfilename unique. Returns a file descriptor open on the file for 667169695Skanreading and writing. 668169695Skan 669169695Skan@end deftypefn 670169695Skan 671169695Skan@c pexecute.txh:244 672169695Skan@deftypefn Extension void pex_free (struct pex_obj @var{obj}) 673169695Skan 674169695SkanClean up and free all data associated with @var{obj}. 675169695Skan 676169695Skan@end deftypefn 677169695Skan 678169695Skan@c pexecute.txh:219 679169695Skan@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector}) 680169695Skan 681169695SkanReturns the exit status of all programs run using @var{obj}. 682169695Skan@var{count} is the number of results expected. The results will be 683169695Skanplaced into @var{vector}. The results are in the order of the calls 684169695Skanto @code{pex_run}. Returns 0 on error, 1 on success. 685169695Skan 686169695Skan@end deftypefn 687169695Skan 688169695Skan@c pexecute.txh:228 689169695Skan@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector}) 690169695Skan 691169695SkanReturns the process execution times of all programs run using 692169695Skan@var{obj}. @var{count} is the number of results expected. The 693169695Skanresults will be placed into @var{vector}. The results are in the 694169695Skanorder of the calls to @code{pex_run}. Returns 0 on error, 1 on 695169695Skansuccess. 696169695Skan 697169695Skan@code{struct pex_time} has the following fields of the type 698169695Skan@code{unsigned long}: @code{user_seconds}, 699169695Skan@code{user_microseconds}, @code{system_seconds}, 700169695Skan@code{system_microseconds}. On systems which do not support reporting 701169695Skanprocess times, all the fields will be set to @code{0}. 702169695Skan 703169695Skan@end deftypefn 704169695Skan 705169695Skan@c pexecute.txh:2 706169695Skan@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase}) 707169695Skan 708169695SkanPrepare to execute one or more programs, with standard output of each 709169695Skanprogram fed to standard input of the next. This is a system 710169695Skanindependent interface to execute a pipeline. 711169695Skan 712169695Skan@var{flags} is a bitwise combination of the following: 713169695Skan 714169695Skan@table @code 715169695Skan 716169695Skan@vindex PEX_RECORD_TIMES 717169695Skan@item PEX_RECORD_TIMES 718169695SkanRecord subprocess times if possible. 719169695Skan 720169695Skan@vindex PEX_USE_PIPES 721169695Skan@item PEX_USE_PIPES 722169695SkanUse pipes for communication between processes, if possible. 723169695Skan 724169695Skan@vindex PEX_SAVE_TEMPS 725169695Skan@item PEX_SAVE_TEMPS 726169695SkanDon't delete temporary files used for communication between 727169695Skanprocesses. 728169695Skan 729169695Skan@end table 730169695Skan 731169695Skan@var{pname} is the name of program to be executed, used in error 732169695Skanmessages. @var{tempbase} is a base name to use for any required 733169695Skantemporary files; it may be @code{NULL} to use a randomly chosen name. 734169695Skan 735169695Skan@end deftypefn 736169695Skan 737169695Skan@c pexecute.txh:146 738169695Skan@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{in_name}) 739169695Skan 740169695SkanReturn a stream for a temporary file to pass to the first program in 741169695Skanthe pipeline as input. 742169695Skan 743169695SkanThe name of the input file is chosen according to the same rules 744169695Skan@code{pex_run} uses to choose output file names, based on 745169695Skan@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}. 746169695Skan 747169695SkanDon't call @code{fclose} on the returned stream; the first call to 748169695Skan@code{pex_run} closes it automatically. 749169695Skan 750169695SkanIf @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in 751169695Skanbinary mode; otherwise, open it in the default mode. Including 752169695Skan@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix. 753169695Skan@end deftypefn 754169695Skan 755169695Skan@c pexecute.txh:163 756169695Skan@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, int @var{binary}) 757169695Skan 758169695SkanReturn a stream @var{fp} for a pipe connected to the standard input of 759169695Skanthe first program in the pipeline; @var{fp} is opened for writing. 760169695SkanYou must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call 761169695Skanthat returned @var{obj}. 762169695Skan 763169695SkanYou must close @var{fp} using @code{fclose} yourself when you have 764169695Skanfinished writing data to the pipeline. 765169695Skan 766169695SkanThe file descriptor underlying @var{fp} is marked not to be inherited 767169695Skanby child processes. 768169695Skan 769169695SkanOn systems that do not support pipes, this function returns 770169695Skan@code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would 771169695Skanlike to write code that is portable to all systems the @code{pex} 772169695Skanfunctions support, consider using @code{pex_input_file} instead. 773169695Skan 774169695SkanThere are two opportunities for deadlock using 775169695Skan@code{pex_input_pipe}: 776169695Skan 777169695Skan@itemize @bullet 778169695Skan@item 779169695SkanMost systems' pipes can buffer only a fixed amount of data; a process 780169695Skanthat writes to a full pipe blocks. Thus, if you write to @file{fp} 781169695Skanbefore starting the first process, you run the risk of blocking when 782169695Skanthere is no child process yet to read the data and allow you to 783169695Skancontinue. @code{pex_input_pipe} makes no promises about the 784169695Skansize of the pipe's buffer, so if you need to write any data at all 785169695Skanbefore starting the first process in the pipeline, consider using 786169695Skan@code{pex_input_file} instead. 787169695Skan 788169695Skan@item 789169695SkanUsing @code{pex_input_pipe} and @code{pex_read_output} together 790169695Skanmay also cause deadlock. If the output pipe fills up, so that each 791169695Skanprogram in the pipeline is waiting for the next to read more data, and 792169695Skanyou fill the input pipe by writing more data to @var{fp}, then there 793169695Skanis no way to make progress: the only process that could read data from 794169695Skanthe output pipe is you, but you are blocked on the input pipe. 795169695Skan 796169695Skan@end itemize 797169695Skan 798169695Skan@end deftypefn 799169695Skan 800169695Skan@c pexecute.txh:250 801169695Skan@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}) 802169695Skan 803169695SkanAn interface to permit the easy execution of a 804169695Skansingle program. The return value and most of the parameters are as 805169695Skanfor a call to @code{pex_run}. @var{flags} is restricted to a 806169695Skancombination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and 807169695Skan@code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if 808169695Skan@code{PEX_LAST} were set. On a successful return, @code{*@var{status}} will 809169695Skanbe set to the exit status of the program. 810169695Skan 811169695Skan@end deftypefn 812169695Skan 813169695Skan@c pexecute.txh:207 814169695Skan@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary}) 815169695Skan 816169695SkanReturns a @code{FILE} pointer which may be used to read the standard 817169695Skanoutput of the last program in the pipeline. When this is used, 818169695Skan@code{PEX_LAST} should not be used in a call to @code{pex_run}. After 819169695Skanthis is called, @code{pex_run} may no longer be called with the same 820169695Skan@var{obj}. @var{binary} should be non-zero if the file should be 821169695Skanopened in binary mode. Don't call @code{fclose} on the returned file; 822169695Skanit will be closed by @code{pex_free}. 823169695Skan 824169695Skan@end deftypefn 825169695Skan 826169695Skan@c pexecute.txh:33 827169695Skan@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}) 828169695Skan 829169695SkanExecute one program in a pipeline. On success this returns 830169695Skan@code{NULL}. On failure it returns an error message, a statically 831169695Skanallocated string. 832169695Skan 833169695Skan@var{obj} is returned by a previous call to @code{pex_init}. 834169695Skan 835169695Skan@var{flags} is a bitwise combination of the following: 836169695Skan 837169695Skan@table @code 838169695Skan 839169695Skan@vindex PEX_LAST 840169695Skan@item PEX_LAST 841169695SkanThis must be set on the last program in the pipeline. In particular, 842169695Skanit should be set when executing a single program. The standard output 843169695Skanof the program will be sent to @var{outname}, or, if @var{outname} is 844169695Skan@code{NULL}, to the standard output of the calling program. Do @emph{not} 845169695Skanset this bit if you want to call @code{pex_read_output} 846169695Skan(described below). After a call to @code{pex_run} with this bit set, 847169695Skan@var{pex_run} may no longer be called with the same @var{obj}. 848169695Skan 849169695Skan@vindex PEX_SEARCH 850169695Skan@item PEX_SEARCH 851169695SkanSearch for the program using the user's executable search path. 852169695Skan 853169695Skan@vindex PEX_SUFFIX 854169695Skan@item PEX_SUFFIX 855169695Skan@var{outname} is a suffix. See the description of @var{outname}, 856169695Skanbelow. 857169695Skan 858169695Skan@vindex PEX_STDERR_TO_STDOUT 859169695Skan@item PEX_STDERR_TO_STDOUT 860169695SkanSend the program's standard error to standard output, if possible. 861169695Skan 862169695Skan@vindex PEX_BINARY_INPUT 863169695Skan@vindex PEX_BINARY_OUTPUT 864169695Skan@item PEX_BINARY_INPUT 865169695Skan@itemx PEX_BINARY_OUTPUT 866169695SkanThe standard input (output) of the program should be read (written) in 867169695Skanbinary mode rather than text mode. These flags are ignored on systems 868169695Skanwhich do not distinguish binary mode and text mode, such as Unix. For 869169695Skanproper behavior these flags should match appropriately---a call to 870169695Skan@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a 871169695Skancall using @code{PEX_BINARY_INPUT}. 872169695Skan@end table 873169695Skan 874169695Skan@var{executable} is the program to execute. @var{argv} is the set of 875169695Skanarguments to pass to the program; normally @code{@var{argv}[0]} will 876169695Skanbe a copy of @var{executable}. 877169695Skan 878169695Skan@var{outname} is used to set the name of the file to use for standard 879169695Skanoutput. There are two cases in which no output file will be used: 880169695Skan 881169695Skan@enumerate 882169695Skan@item 883169695Skanif @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} 884169695Skanwas set in the call to @code{pex_init}, and the system supports pipes 885169695Skan 886169695Skan@item 887169695Skanif @code{PEX_LAST} is set in @var{flags}, and @var{outname} is 888169695Skan@code{NULL} 889169695Skan@end enumerate 890169695Skan 891169695Skan@noindent 892169695SkanOtherwise the code will use a file to hold standard 893169695Skanoutput. If @code{PEX_LAST} is not set, this file is considered to be 894169695Skana temporary file, and it will be removed when no longer needed, unless 895169695Skan@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. 896169695Skan 897169695SkanThere are two cases to consider when setting the name of the file to 898169695Skanhold standard output. 899169695Skan 900169695Skan@enumerate 901169695Skan@item 902169695Skan@code{PEX_SUFFIX} is set in @var{flags}. In this case 903169695Skan@var{outname} may not be @code{NULL}. If the @var{tempbase} parameter 904169695Skanto @code{pex_init} was not @code{NULL}, then the output file name is 905169695Skanthe concatenation of @var{tempbase} and @var{outname}. If 906169695Skan@var{tempbase} was @code{NULL}, then the output file name is a random 907169695Skanfile name ending in @var{outname}. 908169695Skan 909169695Skan@item 910169695Skan@code{PEX_SUFFIX} was not set in @var{flags}. In this 911169695Skancase, if @var{outname} is not @code{NULL}, it is used as the output 912169695Skanfile name. If @var{outname} is @code{NULL}, and @var{tempbase} was 913169695Skannot NULL, the output file name is randomly chosen using 914169695Skan@var{tempbase}. Otherwise the output file name is chosen completely 915169695Skanat random. 916169695Skan@end enumerate 917169695Skan 918169695Skan@var{errname} is the file name to use for standard error output. If 919169695Skanit is @code{NULL}, standard error is the same as the caller's. 920169695SkanOtherwise, standard error is written to the named file. 921169695Skan 922169695SkanOn an error return, the code sets @code{*@var{err}} to an @code{errno} 923169695Skanvalue, or to 0 if there is no relevant @code{errno}. 924169695Skan 925169695Skan@end deftypefn 926169695Skan 927169695Skan@c pexecute.txh:133 928169695Skan@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}) 929169695Skan 930169695SkanExecute one program in a pipeline, permitting the environment for the 931169695Skanprogram to be specified. Behaviour and parameters not listed below are 932169695Skanas for @code{pex_run}. 933169695Skan 934169695Skan@var{env} is the environment for the child process, specified as an array of 935169695Skancharacter pointers. Each element of the array should point to a string of the 936169695Skanform @code{VAR=VALUE}, with the exception of the last element that must be 937169695Skan@code{NULL}. 938169695Skan 939169695Skan@end deftypefn 940169695Skan 941169695Skan@c pexecute.txh:262 942169695Skan@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) 943169695Skan 944169695SkanThis is the old interface to execute one or more programs. It is 945169695Skanstill supported for compatibility purposes, but is no longer 946169695Skandocumented. 947169695Skan 948169695Skan@end deftypefn 949169695Skan 950169695Skan@c strsignal.c:539 951169695Skan@deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message}) 952169695Skan 953169695SkanPrint @var{message} to the standard error, followed by a colon, 954169695Skanfollowed by the description of the signal specified by @var{signo}, 955169695Skanfollowed by a newline. 956169695Skan 957169695Skan@end deftypefn 958169695Skan 959169695Skan@c putenv.c:21 960169695Skan@deftypefn Supplemental int putenv (const char *@var{string}) 961169695Skan 962169695SkanUses @code{setenv} or @code{unsetenv} to put @var{string} into 963169695Skanthe environment or remove it. If @var{string} is of the form 964169695Skan@samp{name=value} the string is added; if no @samp{=} is present the 965169695Skanname is unset/removed. 966169695Skan 967169695Skan@end deftypefn 968169695Skan 969169695Skan@c pexecute.txh:270 970169695Skan@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) 971169695Skan 972169695SkanAnother part of the old execution interface. 973169695Skan 974169695Skan@end deftypefn 975169695Skan 976169695Skan@c random.c:39 977169695Skan@deftypefn Supplement {long int} random (void) 978169695Skan@deftypefnx Supplement void srandom (unsigned int @var{seed}) 979169695Skan@deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n}) 980169695Skan@deftypefnx Supplement void* setstate (void *@var{arg_state}) 981169695Skan 982169695SkanRandom number functions. @code{random} returns a random number in the 983169695Skanrange 0 to @code{LONG_MAX}. @code{srandom} initializes the random 984169695Skannumber generator to some starting point determined by @var{seed} 985169695Skan(else, the values returned by @code{random} are always the same for each 986169695Skanrun of the program). @code{initstate} and @code{setstate} allow fine-grained 987169695Skancontrol over the state of the random number generator. 988169695Skan 989169695Skan@end deftypefn 990169695Skan 991169695Skan@c concat.c:173 992169695Skan@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL}) 993169695Skan 994169695SkanSame as @code{concat}, except that if @var{optr} is not @code{NULL} it 995169695Skanis freed after the string is created. This is intended to be useful 996169695Skanwhen you're extending an existing string or building up a string in a 997169695Skanloop: 998169695Skan 999169695Skan@example 1000169695Skan str = reconcat (str, "pre-", str, NULL); 1001169695Skan@end example 1002169695Skan 1003169695Skan@end deftypefn 1004169695Skan 1005169695Skan@c rename.c:6 1006169695Skan@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new}) 1007169695Skan 1008169695SkanRenames a file from @var{old} to @var{new}. If @var{new} already 1009169695Skanexists, it is removed. 1010169695Skan 1011169695Skan@end deftypefn 1012169695Skan 1013169695Skan@c rindex.c:5 1014169695Skan@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c}) 1015169695Skan 1016169695SkanReturns a pointer to the last occurrence of the character @var{c} in 1017169695Skanthe string @var{s}, or @code{NULL} if not found. The use of @code{rindex} is 1018169695Skandeprecated in new programs in favor of @code{strrchr}. 1019169695Skan 1020169695Skan@end deftypefn 1021169695Skan 1022169695Skan@c setenv.c:22 1023169695Skan@deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite}) 1024169695Skan@deftypefnx Supplemental void unsetenv (const char *@var{name}) 1025169695Skan 1026169695Skan@code{setenv} adds @var{name} to the environment with value 1027169695Skan@var{value}. If the name was already present in the environment, 1028169695Skanthe new value will be stored only if @var{overwrite} is nonzero. 1029169695SkanThe companion @code{unsetenv} function removes @var{name} from the 1030169695Skanenvironment. This implementation is not safe for multithreaded code. 1031169695Skan 1032169695Skan@end deftypefn 1033169695Skan 1034169695Skan@c strsignal.c:348 1035169695Skan@deftypefn Extension int signo_max (void) 1036169695Skan 1037169695SkanReturns the maximum signal value for which a corresponding symbolic 1038169695Skanname or message is available. Note that in the case where we use the 1039169695Skan@code{sys_siglist} supplied by the system, it is possible for there to 1040169695Skanbe more symbolic names than messages, or vice versa. In fact, the 1041169695Skanmanual page for @code{psignal(3b)} explicitly warns that one should 1042169695Skancheck the size of the table (@code{NSIG}) before indexing it, since 1043169695Skannew signal codes may be added to the system before they are added to 1044169695Skanthe table. Thus @code{NSIG} might be smaller than value implied by 1045169695Skanthe largest signo value defined in @code{<signal.h>}. 1046169695Skan 1047169695SkanWe return the maximum value that can be used to obtain a meaningful 1048169695Skansymbolic name or message. 1049169695Skan 1050169695Skan@end deftypefn 1051169695Skan 1052169695Skan@c sigsetmask.c:8 1053169695Skan@deftypefn Supplemental int sigsetmask (int @var{set}) 1054169695Skan 1055169695SkanSets the signal mask to the one provided in @var{set} and returns 1056169695Skanthe old mask (which, for libiberty's implementation, will always 1057169695Skanbe the value @code{1}). 1058169695Skan 1059169695Skan@end deftypefn 1060169695Skan 1061169695Skan@c snprintf.c:28 1062169695Skan@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...) 1063169695Skan 1064169695SkanThis function is similar to sprintf, but it will print at most @var{n} 1065169695Skancharacters. On error the return value is -1, otherwise it returns the 1066169695Skannumber of characters that would have been printed had @var{n} been 1067169695Skansufficiently large, regardless of the actual value of @var{n}. Note 1068169695Skansome pre-C99 system libraries do not implement this correctly so users 1069169695Skancannot generally rely on the return value if the system version of 1070169695Skanthis function is used. 1071169695Skan 1072169695Skan@end deftypefn 1073169695Skan 1074169695Skan@c spaces.c:22 1075169695Skan@deftypefn Extension char* spaces (int @var{count}) 1076169695Skan 1077169695SkanReturns a pointer to a memory region filled with the specified 1078169695Skannumber of spaces and null terminated. The returned pointer is 1079169695Skanvalid until at least the next call. 1080169695Skan 1081169695Skan@end deftypefn 1082169695Skan 1083169695Skan@c stpcpy.c:23 1084169695Skan@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src}) 1085169695Skan 1086169695SkanCopies the string @var{src} into @var{dst}. Returns a pointer to 1087169695Skan@var{dst} + strlen(@var{src}). 1088169695Skan 1089169695Skan@end deftypefn 1090169695Skan 1091169695Skan@c stpncpy.c:23 1092169695Skan@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, size_t @var{len}) 1093169695Skan 1094169695SkanCopies the string @var{src} into @var{dst}, copying exactly @var{len} 1095169695Skanand padding with zeros if necessary. If @var{len} < strlen(@var{src}) 1096169695Skanthen return @var{dst} + @var{len}, otherwise returns @var{dst} + 1097169695Skanstrlen(@var{src}). 1098169695Skan 1099169695Skan@end deftypefn 1100169695Skan 1101169695Skan@c strcasecmp.c:15 1102169695Skan@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2}) 1103169695Skan 1104169695SkanA case-insensitive @code{strcmp}. 1105169695Skan 1106169695Skan@end deftypefn 1107169695Skan 1108169695Skan@c strchr.c:6 1109169695Skan@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c}) 1110169695Skan 1111169695SkanReturns a pointer to the first occurrence of the character @var{c} in 1112169695Skanthe string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 1113169695Skannull character, the results are undefined. 1114169695Skan 1115169695Skan@end deftypefn 1116169695Skan 1117169695Skan@c strdup.c:3 1118169695Skan@deftypefn Supplemental char* strdup (const char *@var{s}) 1119169695Skan 1120169695SkanReturns a pointer to a copy of @var{s} in memory obtained from 1121169695Skan@code{malloc}, or @code{NULL} if insufficient memory was available. 1122169695Skan 1123169695Skan@end deftypefn 1124169695Skan 1125169695Skan@c strerror.c:670 1126169695Skan@deftypefn Replacement {const char*} strerrno (int @var{errnum}) 1127169695Skan 1128169695SkanGiven an error number returned from a system call (typically returned 1129169695Skanin @code{errno}), returns a pointer to a string containing the 1130169695Skansymbolic name of that error number, as found in @code{<errno.h>}. 1131169695Skan 1132169695SkanIf the supplied error number is within the valid range of indices for 1133169695Skansymbolic names, but no name is available for the particular error 1134169695Skannumber, then returns the string @samp{Error @var{num}}, where @var{num} 1135169695Skanis the error number. 1136169695Skan 1137169695SkanIf the supplied error number is not within the range of valid 1138169695Skanindices, then returns @code{NULL}. 1139169695Skan 1140169695SkanThe contents of the location pointed to are only guaranteed to be 1141169695Skanvalid until the next call to @code{strerrno}. 1142169695Skan 1143169695Skan@end deftypefn 1144169695Skan 1145169695Skan@c strerror.c:603 1146169695Skan@deftypefn Supplemental char* strerror (int @var{errnoval}) 1147169695Skan 1148169695SkanMaps an @code{errno} number to an error message string, the contents 1149169695Skanof which are implementation defined. On systems which have the 1150169695Skanexternal variables @code{sys_nerr} and @code{sys_errlist}, these 1151169695Skanstrings will be the same as the ones used by @code{perror}. 1152169695Skan 1153169695SkanIf the supplied error number is within the valid range of indices for 1154169695Skanthe @code{sys_errlist}, but no message is available for the particular 1155169695Skanerror number, then returns the string @samp{Error @var{num}}, where 1156169695Skan@var{num} is the error number. 1157169695Skan 1158169695SkanIf the supplied error number is not a valid index into 1159169695Skan@code{sys_errlist}, returns @code{NULL}. 1160169695Skan 1161169695SkanThe returned string is only guaranteed to be valid only until the 1162169695Skannext call to @code{strerror}. 1163169695Skan 1164169695Skan@end deftypefn 1165169695Skan 1166169695Skan@c strncasecmp.c:15 1167169695Skan@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2}) 1168169695Skan 1169169695SkanA case-insensitive @code{strncmp}. 1170169695Skan 1171169695Skan@end deftypefn 1172169695Skan 1173169695Skan@c strncmp.c:6 1174169695Skan@deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) 1175169695Skan 1176169695SkanCompares the first @var{n} bytes of two strings, returning a value as 1177169695Skan@code{strcmp}. 1178169695Skan 1179169695Skan@end deftypefn 1180169695Skan 1181169695Skan@c strndup.c:23 1182169695Skan@deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n}) 1183169695Skan 1184169695SkanReturns a pointer to a copy of @var{s} with at most @var{n} characters 1185169695Skanin memory obtained from @code{malloc}, or @code{NULL} if insufficient 1186169695Skanmemory was available. The result is always NUL terminated. 1187169695Skan 1188169695Skan@end deftypefn 1189169695Skan 1190169695Skan@c strrchr.c:6 1191169695Skan@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c}) 1192169695Skan 1193169695SkanReturns a pointer to the last occurrence of the character @var{c} in 1194169695Skanthe string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 1195169695Skannull character, the results are undefined. 1196169695Skan 1197169695Skan@end deftypefn 1198169695Skan 1199169695Skan@c strsignal.c:383 1200169695Skan@deftypefn Supplemental {const char *} strsignal (int @var{signo}) 1201169695Skan 1202169695SkanMaps an signal number to an signal message string, the contents of 1203169695Skanwhich are implementation defined. On systems which have the external 1204169695Skanvariable @code{sys_siglist}, these strings will be the same as the 1205169695Skanones used by @code{psignal()}. 1206169695Skan 1207169695SkanIf the supplied signal number is within the valid range of indices for 1208169695Skanthe @code{sys_siglist}, but no message is available for the particular 1209169695Skansignal number, then returns the string @samp{Signal @var{num}}, where 1210169695Skan@var{num} is the signal number. 1211169695Skan 1212169695SkanIf the supplied signal number is not a valid index into 1213169695Skan@code{sys_siglist}, returns @code{NULL}. 1214169695Skan 1215169695SkanThe returned string is only guaranteed to be valid only until the next 1216169695Skancall to @code{strsignal}. 1217169695Skan 1218169695Skan@end deftypefn 1219169695Skan 1220169695Skan@c strsignal.c:446 1221169695Skan@deftypefn Extension {const char*} strsigno (int @var{signo}) 1222169695Skan 1223169695SkanGiven an signal number, returns a pointer to a string containing the 1224169695Skansymbolic name of that signal number, as found in @code{<signal.h>}. 1225169695Skan 1226169695SkanIf the supplied signal number is within the valid range of indices for 1227169695Skansymbolic names, but no name is available for the particular signal 1228169695Skannumber, then returns the string @samp{Signal @var{num}}, where 1229169695Skan@var{num} is the signal number. 1230169695Skan 1231169695SkanIf the supplied signal number is not within the range of valid 1232169695Skanindices, then returns @code{NULL}. 1233169695Skan 1234169695SkanThe contents of the location pointed to are only guaranteed to be 1235169695Skanvalid until the next call to @code{strsigno}. 1236169695Skan 1237169695Skan@end deftypefn 1238169695Skan 1239169695Skan@c strstr.c:6 1240169695Skan@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub}) 1241169695Skan 1242169695SkanThis function searches for the substring @var{sub} in the string 1243169695Skan@var{string}, not including the terminating null characters. A pointer 1244169695Skanto the first occurrence of @var{sub} is returned, or @code{NULL} if the 1245169695Skansubstring is absent. If @var{sub} points to a string with zero 1246169695Skanlength, the function returns @var{string}. 1247169695Skan 1248169695Skan@end deftypefn 1249169695Skan 1250169695Skan@c strtod.c:27 1251169695Skan@deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr}) 1252169695Skan 1253169695SkanThis ISO C function converts the initial portion of @var{string} to a 1254169695Skan@code{double}. If @var{endptr} is not @code{NULL}, a pointer to the 1255169695Skancharacter after the last character used in the conversion is stored in 1256169695Skanthe location referenced by @var{endptr}. If no conversion is 1257169695Skanperformed, zero is returned and the value of @var{string} is stored in 1258169695Skanthe location referenced by @var{endptr}. 1259169695Skan 1260169695Skan@end deftypefn 1261169695Skan 1262169695Skan@c strerror.c:729 1263169695Skan@deftypefn Extension int strtoerrno (const char *@var{name}) 1264169695Skan 1265169695SkanGiven the symbolic name of a error number (e.g., @code{EACCES}), map it 1266169695Skanto an errno value. If no translation is found, returns 0. 1267169695Skan 1268169695Skan@end deftypefn 1269169695Skan 1270169695Skan@c strtol.c:33 1271169695Skan@deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base}) 1272169695Skan@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base}) 1273169695Skan 1274169695SkanThe @code{strtol} function converts the string in @var{string} to a 1275169695Skanlong integer value according to the given @var{base}, which must be 1276169695Skanbetween 2 and 36 inclusive, or be the special value 0. If @var{base} 1277169695Skanis 0, @code{strtol} will look for the prefixes @code{0} and @code{0x} 1278169695Skanto indicate bases 8 and 16, respectively, else default to base 10. 1279169695SkanWhen the base is 16 (either explicitly or implicitly), a prefix of 1280169695Skan@code{0x} is allowed. The handling of @var{endptr} is as that of 1281169695Skan@code{strtod} above. The @code{strtoul} function is the same, except 1282169695Skanthat the converted value is unsigned. 1283169695Skan 1284169695Skan@end deftypefn 1285169695Skan 1286169695Skan@c strsignal.c:500 1287169695Skan@deftypefn Extension int strtosigno (const char *@var{name}) 1288169695Skan 1289169695SkanGiven the symbolic name of a signal, map it to a signal number. If no 1290169695Skantranslation is found, returns 0. 1291169695Skan 1292169695Skan@end deftypefn 1293169695Skan 1294169695Skan@c strverscmp.c:25 1295169695Skan@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2}) 1296169695SkanThe @code{strverscmp} function compares the string @var{s1} against 1297169695Skan@var{s2}, considering them as holding indices/version numbers. Return 1298169695Skanvalue follows the same conventions as found in the @code{strverscmp} 1299169695Skanfunction. In fact, if @var{s1} and @var{s2} contain no digits, 1300169695Skan@code{strverscmp} behaves like @code{strcmp}. 1301169695Skan 1302169695SkanBasically, we compare strings normally (character by character), until 1303169695Skanwe find a digit in each string - then we enter a special comparison 1304169695Skanmode, where each sequence of digits is taken as a whole. If we reach the 1305169695Skanend of these two parts without noticing a difference, we return to the 1306169695Skanstandard comparison mode. There are two types of numeric parts: 1307169695Skan"integral" and "fractional" (those begin with a '0'). The types 1308169695Skanof the numeric parts affect the way we sort them: 1309169695Skan 1310169695Skan@itemize @bullet 1311169695Skan@item 1312169695Skanintegral/integral: we compare values as you would expect. 1313169695Skan 1314169695Skan@item 1315169695Skanfractional/integral: the fractional part is less than the integral one. 1316169695SkanAgain, no surprise. 1317169695Skan 1318169695Skan@item 1319169695Skanfractional/fractional: the things become a bit more complex. 1320169695SkanIf the common prefix contains only leading zeroes, the longest part is less 1321169695Skanthan the other one; else the comparison behaves normally. 1322169695Skan@end itemize 1323169695Skan 1324169695Skan@smallexample 1325169695Skanstrverscmp ("no digit", "no digit") 1326169695Skan @result{} 0 // @r{same behavior as strcmp.} 1327169695Skanstrverscmp ("item#99", "item#100") 1328169695Skan @result{} <0 // @r{same prefix, but 99 < 100.} 1329169695Skanstrverscmp ("alpha1", "alpha001") 1330169695Skan @result{} >0 // @r{fractional part inferior to integral one.} 1331169695Skanstrverscmp ("part1_f012", "part1_f01") 1332169695Skan @result{} >0 // @r{two fractional parts.} 1333169695Skanstrverscmp ("foo.009", "foo.0") 1334169695Skan @result{} <0 // @r{idem, but with leading zeroes only.} 1335169695Skan@end smallexample 1336169695Skan 1337169695SkanThis function is especially useful when dealing with filename sorting, 1338169695Skanbecause filenames frequently hold indices/version numbers. 1339169695Skan@end deftypefun 1340169695Skan 1341169695Skan@c tmpnam.c:3 1342169695Skan@deftypefn Supplemental char* tmpnam (char *@var{s}) 1343169695Skan 1344169695SkanThis function attempts to create a name for a temporary file, which 1345169695Skanwill be a valid file name yet not exist when @code{tmpnam} checks for 1346169695Skanit. @var{s} must point to a buffer of at least @code{L_tmpnam} bytes, 1347169695Skanor be @code{NULL}. Use of this function creates a security risk, and it must 1348169695Skannot be used in new projects. Use @code{mkstemp} instead. 1349169695Skan 1350169695Skan@end deftypefn 1351169695Skan 1352169695Skan@c unlink-if-ordinary.c:27 1353169695Skan@deftypefn Supplemental int unlink_if_ordinary (const char*) 1354169695Skan 1355169695SkanUnlinks the named file, unless it is special (e.g. a device file). 1356169695SkanReturns 0 when the file was unlinked, a negative value (and errno set) when 1357169695Skanthere was an error deleting the file, and a positive value if no attempt 1358169695Skanwas made to unlink the file because it is special. 1359169695Skan 1360169695Skan@end deftypefn 1361169695Skan 1362169695Skan@c fopen_unlocked.c:31 1363169695Skan@deftypefn Extension void unlock_std_streams (void) 1364169695Skan 1365169695SkanIf the OS supports it, ensure that the standard I/O streams, 1366169695Skan@code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any 1367169695Skanmulti-threaded locking. Otherwise do nothing. 1368169695Skan 1369169695Skan@end deftypefn 1370169695Skan 1371169695Skan@c fopen_unlocked.c:23 1372169695Skan@deftypefn Extension void unlock_stream (FILE * @var{stream}) 1373169695Skan 1374169695SkanIf the OS supports it, ensure that the supplied stream is setup to 1375169695Skanavoid any multi-threaded locking. Otherwise leave the @code{FILE} 1376169695Skanpointer unchanged. If the @var{stream} is @code{NULL} do nothing. 1377169695Skan 1378169695Skan@end deftypefn 1379169695Skan 1380169695Skan@c vasprintf.c:47 1381169695Skan@deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args}) 1382169695Skan 1383169695SkanLike @code{vsprintf}, but instead of passing a pointer to a buffer, 1384169695Skanyou pass a pointer to a pointer. This function will compute the size 1385169695Skanof the buffer needed, allocate memory with @code{malloc}, and store a 1386169695Skanpointer to the allocated memory in @code{*@var{resptr}}. The value 1387169695Skanreturned is the same as @code{vsprintf} would return. If memory could 1388169695Skannot be allocated, minus one is returned and @code{NULL} is stored in 1389169695Skan@code{*@var{resptr}}. 1390169695Skan 1391169695Skan@end deftypefn 1392169695Skan 1393169695Skan@c vfork.c:6 1394169695Skan@deftypefn Supplemental int vfork (void) 1395169695Skan 1396169695SkanEmulates @code{vfork} by calling @code{fork} and returning its value. 1397169695Skan 1398169695Skan@end deftypefn 1399169695Skan 1400169695Skan@c vprintf.c:3 1401169695Skan@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap}) 1402169695Skan@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap}) 1403169695Skan@deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap}) 1404169695Skan 1405169695SkanThese functions are the same as @code{printf}, @code{fprintf}, and 1406169695Skan@code{sprintf}, respectively, except that they are called with a 1407169695Skan@code{va_list} instead of a variable number of arguments. Note that 1408169695Skanthey do not call @code{va_end}; this is the application's 1409169695Skanresponsibility. In @libib{} they are implemented in terms of the 1410169695Skannonstandard but common function @code{_doprnt}. 1411169695Skan 1412169695Skan@end deftypefn 1413169695Skan 1414169695Skan@c vsnprintf.c:28 1415169695Skan@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap}) 1416169695Skan 1417169695SkanThis function is similar to vsprintf, but it will print at most 1418169695Skan@var{n} characters. On error the return value is -1, otherwise it 1419169695Skanreturns the number of characters that would have been printed had 1420169695Skan@var{n} been sufficiently large, regardless of the actual value of 1421169695Skan@var{n}. Note some pre-C99 system libraries do not implement this 1422169695Skancorrectly so users cannot generally rely on the return value if the 1423169695Skansystem version of this function is used. 1424169695Skan 1425169695Skan@end deftypefn 1426169695Skan 1427169695Skan@c waitpid.c:3 1428169695Skan@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int) 1429169695Skan 1430169695SkanThis is a wrapper around the @code{wait} function. Any ``special'' 1431169695Skanvalues of @var{pid} depend on your implementation of @code{wait}, as 1432169695Skandoes the return value. The third argument is unused in @libib{}. 1433169695Skan 1434169695Skan@end deftypefn 1435169695Skan 1436169695Skan@c xatexit.c:11 1437169695Skan@deftypefun int xatexit (void (*@var{fn}) (void)) 1438169695Skan 1439169695SkanBehaves as the standard @code{atexit} function, but with no limit on 1440169695Skanthe number of registered functions. Returns 0 on success, or @minus{}1 on 1441169695Skanfailure. If you use @code{xatexit} to register functions, you must use 1442169695Skan@code{xexit} to terminate your program. 1443169695Skan 1444169695Skan@end deftypefun 1445169695Skan 1446169695Skan@c xmalloc.c:38 1447169695Skan@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize}) 1448169695Skan 1449169695SkanAllocate memory without fail, and set it to zero. This routine functions 1450169695Skanlike @code{calloc}, but will behave the same as @code{xmalloc} if memory 1451169695Skancannot be found. 1452169695Skan 1453169695Skan@end deftypefn 1454169695Skan 1455169695Skan@c xexit.c:22 1456169695Skan@deftypefn Replacement void xexit (int @var{code}) 1457169695Skan 1458169695SkanTerminates the program. If any functions have been registered with 1459169695Skanthe @code{xatexit} replacement function, they will be called first. 1460169695SkanTermination is handled via the system's normal @code{exit} call. 1461169695Skan 1462169695Skan@end deftypefn 1463169695Skan 1464169695Skan@c xmalloc.c:22 1465169695Skan@deftypefn Replacement void* xmalloc (size_t) 1466169695Skan 1467169695SkanAllocate memory without fail. If @code{malloc} fails, this will print 1468169695Skana message to @code{stderr} (using the name set by 1469169695Skan@code{xmalloc_set_program_name}, 1470169695Skanif any) and then call @code{xexit}. Note that it is therefore safe for 1471169695Skana program to contain @code{#define malloc xmalloc} in its source. 1472169695Skan 1473169695Skan@end deftypefn 1474169695Skan 1475169695Skan@c xmalloc.c:53 1476169695Skan@deftypefn Replacement void xmalloc_failed (size_t) 1477169695Skan 1478169695SkanThis function is not meant to be called by client code, and is listed 1479169695Skanhere for completeness only. If any of the allocation routines fail, this 1480169695Skanfunction will be called to print an error message and terminate execution. 1481169695Skan 1482169695Skan@end deftypefn 1483169695Skan 1484169695Skan@c xmalloc.c:46 1485169695Skan@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name}) 1486169695Skan 1487169695SkanYou can use this to set the name of the program used by 1488169695Skan@code{xmalloc_failed} when printing a failure message. 1489169695Skan 1490169695Skan@end deftypefn 1491169695Skan 1492169695Skan@c xmemdup.c:7 1493169695Skan@deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size}) 1494169695Skan 1495169695SkanDuplicates a region of memory without fail. First, @var{alloc_size} bytes 1496169695Skanare allocated, then @var{copy_size} bytes from @var{input} are copied into 1497169695Skanit, and the new memory is returned. If fewer bytes are copied than were 1498169695Skanallocated, the remaining memory is zeroed. 1499169695Skan 1500169695Skan@end deftypefn 1501169695Skan 1502169695Skan@c xmalloc.c:32 1503169695Skan@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size}) 1504169695SkanReallocate memory without fail. This routine functions like @code{realloc}, 1505169695Skanbut will behave the same as @code{xmalloc} if memory cannot be found. 1506169695Skan 1507169695Skan@end deftypefn 1508169695Skan 1509169695Skan@c xstrdup.c:7 1510169695Skan@deftypefn Replacement char* xstrdup (const char *@var{s}) 1511169695Skan 1512169695SkanDuplicates a character string without fail, using @code{xmalloc} to 1513169695Skanobtain memory. 1514169695Skan 1515169695Skan@end deftypefn 1516169695Skan 1517169695Skan@c xstrerror.c:7 1518169695Skan@deftypefn Replacement char* xstrerror (int @var{errnum}) 1519169695Skan 1520169695SkanBehaves exactly like the standard @code{strerror} function, but 1521169695Skanwill never return a @code{NULL} pointer. 1522169695Skan 1523169695Skan@end deftypefn 1524169695Skan 1525169695Skan@c xstrndup.c:23 1526169695Skan@deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n}) 1527169695Skan 1528169695SkanReturns a pointer to a copy of @var{s} with at most @var{n} characters 1529169695Skanwithout fail, using @code{xmalloc} to obtain memory. The result is 1530169695Skanalways NUL terminated. 1531169695Skan 1532169695Skan@end deftypefn 1533169695Skan 1534169695Skan 1535