12a6b7db3Sskrll@c Automatically generated from *.c and others (the comments before 22a6b7db3Sskrll@c each entry tell you which file and where in that file). DO NOT EDIT! 32a6b7db3Sskrll@c Edit the *.c files, configure with --enable-maintainer-mode, 4b3ac4aedSchristos@c run 'make stamp-functions' and gather-docs will build a new copy. 52a6b7db3Sskrll 62a6b7db3Sskrll@c alloca.c:26 72a6b7db3Sskrll@deftypefn Replacement void* alloca (size_t @var{size}) 82a6b7db3Sskrll 92a6b7db3SskrllThis function allocates memory which will be automatically reclaimed 102a6b7db3Sskrllafter the procedure exits. The @libib{} implementation does not free 112a6b7db3Sskrllthe memory immediately but will do so eventually during subsequent 122a6b7db3Sskrllcalls to this function. Memory is allocated using @code{xmalloc} under 132a6b7db3Sskrllnormal circumstances. 142a6b7db3Sskrll 152a6b7db3SskrllThe header file @file{alloca-conf.h} can be used in conjunction with the 162a6b7db3SskrllGNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make 172a6b7db3Sskrllavailable this function. The @code{AC_FUNC_ALLOCA} test requires that 182a6b7db3Sskrllclient code use a block of preprocessor code to be safe (see the Autoconf 192a6b7db3Sskrllmanual for more); this header incorporates that logic and more, including 202a6b7db3Sskrllthe possibility of a GCC built-in function. 212a6b7db3Sskrll 222a6b7db3Sskrll@end deftypefn 232a6b7db3Sskrll 242a6b7db3Sskrll@c asprintf.c:32 252a6b7db3Sskrll@deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...) 262a6b7db3Sskrll 272a6b7db3SskrllLike @code{sprintf}, but instead of passing a pointer to a buffer, you 282a6b7db3Sskrllpass a pointer to a pointer. This function will compute the size of 292a6b7db3Sskrllthe buffer needed, allocate memory with @code{malloc}, and store a 302a6b7db3Sskrllpointer to the allocated memory in @code{*@var{resptr}}. The value 312a6b7db3Sskrllreturned is the same as @code{sprintf} would return. If memory could 322a6b7db3Sskrllnot be allocated, minus one is returned and @code{NULL} is stored in 332a6b7db3Sskrll@code{*@var{resptr}}. 342a6b7db3Sskrll 352a6b7db3Sskrll@end deftypefn 362a6b7db3Sskrll 372a6b7db3Sskrll@c atexit.c:6 382a6b7db3Sskrll@deftypefn Supplemental int atexit (void (*@var{f})()) 392a6b7db3Sskrll 402a6b7db3SskrllCauses function @var{f} to be called at exit. Returns 0. 412a6b7db3Sskrll 422a6b7db3Sskrll@end deftypefn 432a6b7db3Sskrll 442a6b7db3Sskrll@c basename.c:6 452a6b7db3Sskrll@deftypefn Supplemental char* basename (const char *@var{name}) 462a6b7db3Sskrll 472a6b7db3SskrllReturns a pointer to the last component of pathname @var{name}. 482a6b7db3SskrllBehavior is undefined if the pathname ends in a directory separator. 492a6b7db3Sskrll 502a6b7db3Sskrll@end deftypefn 512a6b7db3Sskrll 522a6b7db3Sskrll@c bcmp.c:6 532a6b7db3Sskrll@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count}) 542a6b7db3Sskrll 552a6b7db3SskrllCompares the first @var{count} bytes of two areas of memory. Returns 562a6b7db3Sskrllzero if they are the same, nonzero otherwise. Returns zero if 572a6b7db3Sskrll@var{count} is zero. A nonzero result only indicates a difference, 582a6b7db3Sskrllit does not indicate any sorting order (say, by having a positive 592a6b7db3Sskrllresult mean @var{x} sorts before @var{y}). 602a6b7db3Sskrll 612a6b7db3Sskrll@end deftypefn 622a6b7db3Sskrll 632a6b7db3Sskrll@c bcopy.c:3 642a6b7db3Sskrll@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length}) 652a6b7db3Sskrll 662a6b7db3SskrllCopies @var{length} bytes from memory region @var{in} to region 672a6b7db3Sskrll@var{out}. The use of @code{bcopy} is deprecated in new programs. 682a6b7db3Sskrll 692a6b7db3Sskrll@end deftypefn 702a6b7db3Sskrll 712a6b7db3Sskrll@c bsearch.c:33 7205caefcfSchristos@deftypefn Supplemental void* bsearch (const void *@var{key}, @ 7305caefcfSchristos const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, @ 7405caefcfSchristos int (*@var{compar})(const void *, const void *)) 752a6b7db3Sskrll 762a6b7db3SskrllPerforms a search over an array of @var{nmemb} elements pointed to by 772a6b7db3Sskrll@var{base} for a member that matches the object pointed to by @var{key}. 782a6b7db3SskrllThe size of each member is specified by @var{size}. The array contents 792a6b7db3Sskrllshould be sorted in ascending order according to the @var{compar} 802a6b7db3Sskrllcomparison function. This routine should take two arguments pointing to 812a6b7db3Sskrllthe @var{key} and to an array member, in that order, and should return an 822a6b7db3Sskrllinteger less than, equal to, or greater than zero if the @var{key} object 832a6b7db3Sskrllis respectively less than, matching, or greater than the array member. 842a6b7db3Sskrll 852a6b7db3Sskrll@end deftypefn 862a6b7db3Sskrll 87*f22f0ef4Schristos@c bsearch_r.c:33 88*f22f0ef4Schristos@deftypefn Supplemental void* bsearch_r (const void *@var{key}, @ 89*f22f0ef4Schristos const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, @ 90*f22f0ef4Schristos int (*@var{compar})(const void *, const void *, void *), void *@var{arg}) 91*f22f0ef4Schristos 92*f22f0ef4SchristosPerforms a search over an array of @var{nmemb} elements pointed to by 93*f22f0ef4Schristos@var{base} for a member that matches the object pointed to by @var{key}. 94*f22f0ef4SchristosThe size of each member is specified by @var{size}. The array contents 95*f22f0ef4Schristosshould be sorted in ascending order according to the @var{compar} 96*f22f0ef4Schristoscomparison function. This routine should take three arguments: the first 97*f22f0ef4Schristostwo point to the @var{key} and to an array member, and the last is passed 98*f22f0ef4Schristosdown unchanged from @code{bsearch_r}'s last argument. It should return an 99*f22f0ef4Schristosinteger less than, equal to, or greater than zero if the @var{key} object 100*f22f0ef4Schristosis respectively less than, matching, or greater than the array member. 101*f22f0ef4Schristos 102*f22f0ef4Schristos@end deftypefn 103*f22f0ef4Schristos 104f7172901Schristos@c argv.c:138 1052a6b7db3Sskrll@deftypefn Extension char** buildargv (char *@var{sp}) 1062a6b7db3Sskrll 1072a6b7db3SskrllGiven a pointer to a string, parse the string extracting fields 1082a6b7db3Sskrllseparated by whitespace and optionally enclosed within either single 1092a6b7db3Sskrllor double quotes (which are stripped off), and build a vector of 1102a6b7db3Sskrllpointers to copies of the string for each field. The input string 1112a6b7db3Sskrllremains unchanged. The last element of the vector is followed by a 1122a6b7db3Sskrll@code{NULL} element. 1132a6b7db3Sskrll 1142a6b7db3SskrllAll of the memory for the pointer array and copies of the string 1155ba6b03cSchristosis obtained from @code{xmalloc}. All of the memory can be returned to the 1162a6b7db3Sskrllsystem with the single function call @code{freeargv}, which takes the 1172a6b7db3Sskrllreturned result of @code{buildargv}, as it's argument. 1182a6b7db3Sskrll 1192a6b7db3SskrllReturns a pointer to the argument vector if successful. Returns 1202a6b7db3Sskrll@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient 1212a6b7db3Sskrllmemory to complete building the argument vector. 1222a6b7db3Sskrll 1232a6b7db3SskrllIf the input is a null string (as opposed to a @code{NULL} pointer), 1242a6b7db3Sskrllthen buildarg returns an argument vector that has one arg, a null 1252a6b7db3Sskrllstring. 1262a6b7db3Sskrll 1272a6b7db3Sskrll@end deftypefn 1282a6b7db3Sskrll 1292a6b7db3Sskrll@c bzero.c:6 1302a6b7db3Sskrll@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count}) 1312a6b7db3Sskrll 1322a6b7db3SskrllZeros @var{count} bytes starting at @var{mem}. Use of this function 1332a6b7db3Sskrllis deprecated in favor of @code{memset}. 1342a6b7db3Sskrll 1352a6b7db3Sskrll@end deftypefn 1362a6b7db3Sskrll 1372a6b7db3Sskrll@c calloc.c:6 1382a6b7db3Sskrll@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize}) 1392a6b7db3Sskrll 1402a6b7db3SskrllUses @code{malloc} to allocate storage for @var{nelem} objects of 1412a6b7db3Sskrll@var{elsize} bytes each, then zeros the memory. 1422a6b7db3Sskrll 1432a6b7db3Sskrll@end deftypefn 1442a6b7db3Sskrll 1455ba6b03cSchristos@c filename_cmp.c:201 1465ba6b03cSchristos@deftypefn Extension int canonical_filename_eq (const char *@var{a}, const char *@var{b}) 1475ba6b03cSchristos 1485ba6b03cSchristosReturn non-zero if file names @var{a} and @var{b} are equivalent. 1495ba6b03cSchristosThis function compares the canonical versions of the filenames as returned by 1505ba6b03cSchristos@code{lrealpath()}, so that so that different file names pointing to the same 1515ba6b03cSchristosunderlying file are treated as being identical. 1525ba6b03cSchristos 1535ba6b03cSchristos@end deftypefn 1545ba6b03cSchristos 1555ba6b03cSchristos@c choose-temp.c:45 1562a6b7db3Sskrll@deftypefn Extension char* choose_temp_base (void) 1572a6b7db3Sskrll 1582a6b7db3SskrllReturn a prefix for temporary file names or @code{NULL} if unable to 1592a6b7db3Sskrllfind one. The current directory is chosen if all else fails so the 1602a6b7db3Sskrllprogram is exited if a temporary directory can't be found (@code{mktemp} 1612a6b7db3Sskrllfails). The buffer for the result is obtained with @code{xmalloc}. 1622a6b7db3Sskrll 1632a6b7db3SskrllThis function is provided for backwards compatibility only. Its use is 1642a6b7db3Sskrllnot recommended. 1652a6b7db3Sskrll 1662a6b7db3Sskrll@end deftypefn 1672a6b7db3Sskrll 168f7172901Schristos@c make-temp-file.c:95 1695ba6b03cSchristos@deftypefn Replacement const char* choose_tmpdir () 1702a6b7db3Sskrll 1712a6b7db3SskrllReturns a pointer to a directory path suitable for creating temporary 1722a6b7db3Sskrllfiles in. 1732a6b7db3Sskrll 1742a6b7db3Sskrll@end deftypefn 1752a6b7db3Sskrll 1762a6b7db3Sskrll@c clock.c:27 1772a6b7db3Sskrll@deftypefn Supplemental long clock (void) 1782a6b7db3Sskrll 1792a6b7db3SskrllReturns an approximation of the CPU time used by the process as a 1802a6b7db3Sskrll@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the 1812a6b7db3Sskrllnumber of seconds used. 1822a6b7db3Sskrll 1832a6b7db3Sskrll@end deftypefn 1842a6b7db3Sskrll 1852a6b7db3Sskrll@c concat.c:24 18605caefcfSchristos@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @ 18705caefcfSchristos @dots{}, @code{NULL}) 1882a6b7db3Sskrll 1892a6b7db3SskrllConcatenate zero or more of strings and return the result in freshly 1905ba6b03cSchristos@code{xmalloc}ed memory. The argument list is terminated by the first 1915ba6b03cSchristos@code{NULL} pointer encountered. Pointers to empty strings are ignored. 1925ba6b03cSchristos 1935ba6b03cSchristos@end deftypefn 1945ba6b03cSchristos 195*f22f0ef4Schristos@c argv.c:495 19675f9f1baSchristos@deftypefn Extension int countargv (char * const *@var{argv}) 1975ba6b03cSchristos 1985ba6b03cSchristosReturn the number of elements in @var{argv}. 1995ba6b03cSchristosReturns zero if @var{argv} is NULL. 2002a6b7db3Sskrll 2012a6b7db3Sskrll@end deftypefn 2022a6b7db3Sskrll 203f7172901Schristos@c crc32.c:140 20405caefcfSchristos@deftypefn Extension {unsigned int} crc32 (const unsigned char *@var{buf}, @ 20505caefcfSchristos int @var{len}, unsigned int @var{init}) 206b3ac4aedSchristos 207b3ac4aedSchristosCompute the 32-bit CRC of @var{buf} which has length @var{len}. The 208b3ac4aedSchristosstarting value is @var{init}; this may be used to compute the CRC of 209b3ac4aedSchristosdata split across multiple buffers by passing the return value of each 210b3ac4aedSchristoscall as the @var{init} parameter of the next. 211b3ac4aedSchristos 212f7172901SchristosThis is used by the @command{gdb} remote protocol for the @samp{qCRC} 213f7172901Schristoscommand. In order to get the same results as gdb for a block of data, 214f7172901Schristosyou must pass the first CRC parameter as @code{0xffffffff}. 215b3ac4aedSchristos 216b3ac4aedSchristosThis CRC can be specified as: 217b3ac4aedSchristos 218b3ac4aedSchristos Width : 32 219b3ac4aedSchristos Poly : 0x04c11db7 220b3ac4aedSchristos Init : parameter, typically 0xffffffff 221b3ac4aedSchristos RefIn : false 222b3ac4aedSchristos RefOut : false 223b3ac4aedSchristos XorOut : 0 224b3ac4aedSchristos 225b3ac4aedSchristosThis differs from the "standard" CRC-32 algorithm in that the values 226b3ac4aedSchristosare not reflected, and there is no final XOR value. These differences 227b3ac4aedSchristosmake it easy to compose the values of multiple blocks. 228b3ac4aedSchristos 229b3ac4aedSchristos@end deftypefn 230b3ac4aedSchristos 231f7172901Schristos@c argv.c:59 23275f9f1baSchristos@deftypefn Extension char** dupargv (char * const *@var{vector}) 2332a6b7db3Sskrll 2342a6b7db3SskrllDuplicate an argument vector. Simply scans through @var{vector}, 2352a6b7db3Sskrllduplicating each argument until the terminating @code{NULL} is found. 2362a6b7db3SskrllReturns a pointer to the argument vector if successful. Returns 2372a6b7db3Sskrll@code{NULL} if there is insufficient memory to complete building the 2382a6b7db3Sskrllargument vector. 2392a6b7db3Sskrll 2402a6b7db3Sskrll@end deftypefn 2412a6b7db3Sskrll 242f7172901Schristos@c strerror.c:572 2432a6b7db3Sskrll@deftypefn Extension int errno_max (void) 2442a6b7db3Sskrll 2452a6b7db3SskrllReturns the maximum @code{errno} value for which a corresponding 2462a6b7db3Sskrllsymbolic name or message is available. Note that in the case where we 2472a6b7db3Sskrlluse the @code{sys_errlist} supplied by the system, it is possible for 2482a6b7db3Sskrllthere to be more symbolic names than messages, or vice versa. In 2492a6b7db3Sskrllfact, the manual page for @code{perror(3C)} explicitly warns that one 2502a6b7db3Sskrllshould check the size of the table (@code{sys_nerr}) before indexing 2512a6b7db3Sskrllit, since new error codes may be added to the system before they are 2522a6b7db3Sskrlladded to the table. Thus @code{sys_nerr} might be smaller than value 2532a6b7db3Sskrllimplied by the largest @code{errno} value defined in @code{<errno.h>}. 2542a6b7db3Sskrll 2552a6b7db3SskrllWe return the maximum value that can be used to obtain a meaningful 2562a6b7db3Sskrllsymbolic name or message. 2572a6b7db3Sskrll 2582a6b7db3Sskrll@end deftypefn 2592a6b7db3Sskrll 260*f22f0ef4Schristos@c argv.c:352 2612a6b7db3Sskrll@deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp}) 2622a6b7db3Sskrll 2632a6b7db3SskrllThe @var{argcp} and @code{argvp} arguments are pointers to the usual 2642a6b7db3Sskrll@code{argc} and @code{argv} arguments to @code{main}. This function 2652a6b7db3Sskrlllooks for arguments that begin with the character @samp{@@}. Any such 2662a6b7db3Sskrllarguments are interpreted as ``response files''. The contents of the 2672a6b7db3Sskrllresponse file are interpreted as additional command line options. In 2682a6b7db3Sskrllparticular, the file is separated into whitespace-separated strings; 2692a6b7db3Sskrlleach such string is taken as a command-line option. The new options 2702a6b7db3Sskrllare inserted in place of the option naming the response file, and 2712a6b7db3Sskrll@code{*argcp} and @code{*argvp} will be updated. If the value of 2722a6b7db3Sskrll@code{*argvp} is modified by this function, then the new value has 2732a6b7db3Sskrllbeen dynamically allocated and can be deallocated by the caller with 2742a6b7db3Sskrll@code{freeargv}. However, most callers will simply call 2752a6b7db3Sskrll@code{expandargv} near the beginning of @code{main} and allow the 2762a6b7db3Sskrlloperating system to free the memory when the program exits. 2772a6b7db3Sskrll 2782a6b7db3Sskrll@end deftypefn 2792a6b7db3Sskrll 2802a6b7db3Sskrll@c fdmatch.c:23 2812a6b7db3Sskrll@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2}) 2822a6b7db3Sskrll 2832a6b7db3SskrllCheck to see if two open file descriptors refer to the same file. 2842a6b7db3SskrllThis is useful, for example, when we have an open file descriptor for 2852a6b7db3Sskrllan unnamed file, and the name of a file that we believe to correspond 2862a6b7db3Sskrllto that fd. This can happen when we are exec'd with an already open 2872a6b7db3Sskrllfile (@code{stdout} for example) or from the SVR4 @file{/proc} calls 2882a6b7db3Sskrllthat return open file descriptors for mapped address spaces. All we 2892a6b7db3Sskrllhave to do is open the file by name and check the two file descriptors 2902a6b7db3Sskrllfor a match, which is done by comparing major and minor device numbers 2912a6b7db3Sskrlland inode numbers. 2922a6b7db3Sskrll 2932a6b7db3Sskrll@end deftypefn 2942a6b7db3Sskrll 29505caefcfSchristos@c fopen_unlocked.c:49 29605caefcfSchristos@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, @ 29705caefcfSchristos const char * @var{mode}) 2982a6b7db3Sskrll 2992a6b7db3SskrllOpens and returns a @code{FILE} pointer via @code{fdopen}. If the 3002a6b7db3Sskrlloperating system supports it, ensure that the stream is setup to avoid 3012a6b7db3Sskrllany multi-threaded locking. Otherwise return the @code{FILE} pointer 3022a6b7db3Sskrllunchanged. 3032a6b7db3Sskrll 3042a6b7db3Sskrll@end deftypefn 3052a6b7db3Sskrll 3062a6b7db3Sskrll@c ffs.c:3 3072a6b7db3Sskrll@deftypefn Supplemental int ffs (int @var{valu}) 3082a6b7db3Sskrll 3092a6b7db3SskrllFind the first (least significant) bit set in @var{valu}. Bits are 3102a6b7db3Sskrllnumbered from right to left, starting with bit 1 (corresponding to the 3112a6b7db3Sskrllvalue 1). If @var{valu} is zero, zero is returned. 3122a6b7db3Sskrll 3132a6b7db3Sskrll@end deftypefn 3142a6b7db3Sskrll 3155ba6b03cSchristos@c filename_cmp.c:37 3162a6b7db3Sskrll@deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2}) 3172a6b7db3Sskrll 3182a6b7db3SskrllReturn zero if the two file names @var{s1} and @var{s2} are equivalent. 3192a6b7db3SskrllIf not equivalent, the returned value is similar to what @code{strcmp} 3202a6b7db3Sskrllwould return. In other words, it returns a negative value if @var{s1} 3212a6b7db3Sskrllis less than @var{s2}, or a positive value if @var{s2} is greater than 3222a6b7db3Sskrll@var{s2}. 3232a6b7db3Sskrll 3242a6b7db3SskrllThis function does not normalize file names. As a result, this function 3252a6b7db3Sskrllwill treat filenames that are spelled differently as different even in 3262a6b7db3Sskrllthe case when the two filenames point to the same underlying file. 3272a6b7db3SskrllHowever, it does handle the fact that on DOS-like file systems, forward 3282a6b7db3Sskrlland backward slashes are equal. 3292a6b7db3Sskrll 3302a6b7db3Sskrll@end deftypefn 3312a6b7db3Sskrll 3325ba6b03cSchristos@c filename_cmp.c:183 3335ba6b03cSchristos@deftypefn Extension int filename_eq (const void *@var{s1}, const void *@var{s2}) 3345ba6b03cSchristos 3355ba6b03cSchristosReturn non-zero if file names @var{s1} and @var{s2} are equivalent. 3365ba6b03cSchristosThis function is for use with hashtab.c hash tables. 3375ba6b03cSchristos 3385ba6b03cSchristos@end deftypefn 3395ba6b03cSchristos 3405ba6b03cSchristos@c filename_cmp.c:152 3415ba6b03cSchristos@deftypefn Extension hashval_t filename_hash (const void *@var{s}) 3425ba6b03cSchristos 3435ba6b03cSchristosReturn the hash value for file name @var{s} that will be compared 3445ba6b03cSchristosusing filename_cmp. 3455ba6b03cSchristosThis function is for use with hashtab.c hash tables. 3465ba6b03cSchristos 3475ba6b03cSchristos@end deftypefn 3485ba6b03cSchristos 3495ba6b03cSchristos@c filename_cmp.c:94 35005caefcfSchristos@deftypefn Extension int filename_ncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) 35105caefcfSchristos 35205caefcfSchristosReturn zero if the two file names @var{s1} and @var{s2} are equivalent 35305caefcfSchristosin range @var{n}. 35405caefcfSchristosIf not equivalent, the returned value is similar to what @code{strncmp} 35505caefcfSchristoswould return. In other words, it returns a negative value if @var{s1} 35605caefcfSchristosis less than @var{s2}, or a positive value if @var{s2} is greater than 35705caefcfSchristos@var{s2}. 35805caefcfSchristos 35905caefcfSchristosThis function does not normalize file names. As a result, this function 36005caefcfSchristoswill treat filenames that are spelled differently as different even in 36105caefcfSchristosthe case when the two filenames point to the same underlying file. 36205caefcfSchristosHowever, it does handle the fact that on DOS-like file systems, forward 36305caefcfSchristosand backward slashes are equal. 36405caefcfSchristos 36505caefcfSchristos@end deftypefn 36605caefcfSchristos 3672a6b7db3Sskrll@c fnmatch.txh:1 36805caefcfSchristos@deftypefn Replacement int fnmatch (const char *@var{pattern}, @ 36905caefcfSchristos const char *@var{string}, int @var{flags}) 3702a6b7db3Sskrll 3712a6b7db3SskrllMatches @var{string} against @var{pattern}, returning zero if it 3722a6b7db3Sskrllmatches, @code{FNM_NOMATCH} if not. @var{pattern} may contain the 3732a6b7db3Sskrllwildcards @code{?} to match any one character, @code{*} to match any 3742a6b7db3Sskrllzero or more characters, or a set of alternate characters in square 3752a6b7db3Sskrllbrackets, like @samp{[a-gt8]}, which match one character (@code{a} 3762a6b7db3Sskrllthrough @code{g}, or @code{t}, or @code{8}, in this example) if that one 3772a6b7db3Sskrllcharacter is in the set. A set may be inverted (i.e., match anything 3782a6b7db3Sskrllexcept what's in the set) by giving @code{^} or @code{!} as the first 3792a6b7db3Sskrllcharacter in the set. To include those characters in the set, list them 3802a6b7db3Sskrllas anything other than the first character of the set. To include a 3812a6b7db3Sskrlldash in the set, list it last in the set. A backslash character makes 3822a6b7db3Sskrllthe following character not special, so for example you could match 3832a6b7db3Sskrllagainst a literal asterisk with @samp{\*}. To match a literal 3842a6b7db3Sskrllbackslash, use @samp{\\}. 3852a6b7db3Sskrll 3862a6b7db3Sskrll@code{flags} controls various aspects of the matching process, and is a 3872a6b7db3Sskrllboolean OR of zero or more of the following values (defined in 3882a6b7db3Sskrll@code{<fnmatch.h>}): 3892a6b7db3Sskrll 3902a6b7db3Sskrll@table @code 3912a6b7db3Sskrll 3922a6b7db3Sskrll@item FNM_PATHNAME 3932a6b7db3Sskrll@itemx FNM_FILE_NAME 3942a6b7db3Sskrll@var{string} is assumed to be a path name. No wildcard will ever match 3952a6b7db3Sskrll@code{/}. 3962a6b7db3Sskrll 3972a6b7db3Sskrll@item FNM_NOESCAPE 3982a6b7db3SskrllDo not interpret backslashes as quoting the following special character. 3992a6b7db3Sskrll 4002a6b7db3Sskrll@item FNM_PERIOD 4012a6b7db3SskrllA leading period (at the beginning of @var{string}, or if 4022a6b7db3Sskrll@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or 4032a6b7db3Sskrll@code{?} but must be matched explicitly. 4042a6b7db3Sskrll 4052a6b7db3Sskrll@item FNM_LEADING_DIR 4062a6b7db3SskrllMeans that @var{string} also matches @var{pattern} if some initial part 4072a6b7db3Sskrllof @var{string} matches, and is followed by @code{/} and zero or more 4082a6b7db3Sskrllcharacters. For example, @samp{foo*} would match either @samp{foobar} 4092a6b7db3Sskrllor @samp{foobar/grill}. 4102a6b7db3Sskrll 4112a6b7db3Sskrll@item FNM_CASEFOLD 4122a6b7db3SskrllIgnores case when performing the comparison. 4132a6b7db3Sskrll 4142a6b7db3Sskrll@end table 4152a6b7db3Sskrll 4162a6b7db3Sskrll@end deftypefn 4172a6b7db3Sskrll 4182a6b7db3Sskrll@c fopen_unlocked.c:39 41905caefcfSchristos@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, @ 42005caefcfSchristos const char * @var{mode}) 4212a6b7db3Sskrll 4222a6b7db3SskrllOpens and returns a @code{FILE} pointer via @code{fopen}. If the 4232a6b7db3Sskrlloperating system supports it, ensure that the stream is setup to avoid 4242a6b7db3Sskrllany multi-threaded locking. Otherwise return the @code{FILE} pointer 4252a6b7db3Sskrllunchanged. 4262a6b7db3Sskrll 4272a6b7db3Sskrll@end deftypefn 4282a6b7db3Sskrll 429f7172901Schristos@c argv.c:93 4302a6b7db3Sskrll@deftypefn Extension void freeargv (char **@var{vector}) 4312a6b7db3Sskrll 4322a6b7db3SskrllFree an argument vector that was built using @code{buildargv}. Simply 4332a6b7db3Sskrllscans through @var{vector}, freeing the memory for each argument until 4342a6b7db3Sskrllthe terminating @code{NULL} is found, and then frees @var{vector} 4352a6b7db3Sskrllitself. 4362a6b7db3Sskrll 4372a6b7db3Sskrll@end deftypefn 4382a6b7db3Sskrll 43905caefcfSchristos@c fopen_unlocked.c:59 44005caefcfSchristos@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, @ 44105caefcfSchristos const char * @var{mode}, FILE * @var{stream}) 4422a6b7db3Sskrll 4432a6b7db3SskrllOpens and returns a @code{FILE} pointer via @code{freopen}. If the 4442a6b7db3Sskrlloperating system supports it, ensure that the stream is setup to avoid 4452a6b7db3Sskrllany multi-threaded locking. Otherwise return the @code{FILE} pointer 4462a6b7db3Sskrllunchanged. 4472a6b7db3Sskrll 4482a6b7db3Sskrll@end deftypefn 4492a6b7db3Sskrll 450f7172901Schristos@c getruntime.c:86 4512a6b7db3Sskrll@deftypefn Replacement long get_run_time (void) 4522a6b7db3Sskrll 4532a6b7db3SskrllReturns the time used so far, in microseconds. If possible, this is 4542a6b7db3Sskrllthe time used by this process, else it is the elapsed time since the 4552a6b7db3Sskrllprocess started. 4562a6b7db3Sskrll 4572a6b7db3Sskrll@end deftypefn 4582a6b7db3Sskrll 4592a6b7db3Sskrll@c getcwd.c:6 4602a6b7db3Sskrll@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len}) 4612a6b7db3Sskrll 4622a6b7db3SskrllCopy the absolute pathname for the current working directory into 4632a6b7db3Sskrll@var{pathname}, which is assumed to point to a buffer of at least 4642a6b7db3Sskrll@var{len} bytes, and return a pointer to the buffer. If the current 4652a6b7db3Sskrlldirectory's path doesn't fit in @var{len} characters, the result is 4662a6b7db3Sskrll@code{NULL} and @code{errno} is set. If @var{pathname} is a null pointer, 4672a6b7db3Sskrll@code{getcwd} will obtain @var{len} bytes of space using 4682a6b7db3Sskrll@code{malloc}. 4692a6b7db3Sskrll 4702a6b7db3Sskrll@end deftypefn 4712a6b7db3Sskrll 4722a6b7db3Sskrll@c getpagesize.c:5 4732a6b7db3Sskrll@deftypefn Supplemental int getpagesize (void) 4742a6b7db3Sskrll 4752a6b7db3SskrllReturns the number of bytes in a page of memory. This is the 4762a6b7db3Sskrllgranularity of many of the system memory management routines. No 4772a6b7db3Sskrllguarantee is made as to whether or not it is the same as the basic 4782a6b7db3Sskrllmemory management hardware page size. 4792a6b7db3Sskrll 4802a6b7db3Sskrll@end deftypefn 4812a6b7db3Sskrll 4822a6b7db3Sskrll@c getpwd.c:5 4832a6b7db3Sskrll@deftypefn Supplemental char* getpwd (void) 4842a6b7db3Sskrll 4852a6b7db3SskrllReturns the current working directory. This implementation caches the 4862a6b7db3Sskrllresult on the assumption that the process will not call @code{chdir} 4872a6b7db3Sskrllbetween calls to @code{getpwd}. 4882a6b7db3Sskrll 4892a6b7db3Sskrll@end deftypefn 4902a6b7db3Sskrll 4912a6b7db3Sskrll@c gettimeofday.c:12 4922a6b7db3Sskrll@deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz}) 4932a6b7db3Sskrll 4942a6b7db3SskrllWrites the current time to @var{tp}. This implementation requires 4952a6b7db3Sskrllthat @var{tz} be NULL. Returns 0 on success, -1 on failure. 4962a6b7db3Sskrll 4972a6b7db3Sskrll@end deftypefn 4982a6b7db3Sskrll 4992a6b7db3Sskrll@c hex.c:33 5002a6b7db3Sskrll@deftypefn Extension void hex_init (void) 5012a6b7db3Sskrll 5022a6b7db3SskrllInitializes the array mapping the current character set to 5032a6b7db3Sskrllcorresponding hex values. This function must be called before any 5042a6b7db3Sskrllcall to @code{hex_p} or @code{hex_value}. If you fail to call it, a 5052a6b7db3Sskrlldefault ASCII-based table will normally be used on ASCII systems. 5062a6b7db3Sskrll 5072a6b7db3Sskrll@end deftypefn 5082a6b7db3Sskrll 5092a6b7db3Sskrll@c hex.c:42 5102a6b7db3Sskrll@deftypefn Extension int hex_p (int @var{c}) 5112a6b7db3Sskrll 5122a6b7db3SskrllEvaluates to non-zero if the given character is a valid hex character, 5132a6b7db3Sskrllor zero if it is not. Note that the value you pass will be cast to 5142a6b7db3Sskrll@code{unsigned char} within the macro. 5152a6b7db3Sskrll 5162a6b7db3Sskrll@end deftypefn 5172a6b7db3Sskrll 5182a6b7db3Sskrll@c hex.c:50 5192a6b7db3Sskrll@deftypefn Extension {unsigned int} hex_value (int @var{c}) 5202a6b7db3Sskrll 5212a6b7db3SskrllReturns the numeric equivalent of the given character when interpreted 5222a6b7db3Sskrllas a hexadecimal digit. The result is undefined if you pass an 5232a6b7db3Sskrllinvalid hex digit. Note that the value you pass will be cast to 5242a6b7db3Sskrll@code{unsigned char} within the macro. 5252a6b7db3Sskrll 5262a6b7db3SskrllThe @code{hex_value} macro returns @code{unsigned int}, rather than 5272a6b7db3Sskrllsigned @code{int}, to make it easier to use in parsing addresses from 5282a6b7db3Sskrllhex dump files: a signed @code{int} would be sign-extended when 5292a6b7db3Sskrllconverted to a wider unsigned type --- like @code{bfd_vma}, on some 5302a6b7db3Sskrllsystems. 5312a6b7db3Sskrll 5322a6b7db3Sskrll@end deftypefn 5332a6b7db3Sskrll 534f7172901Schristos@c safe-ctype.c:24 53505caefcfSchristos@defvr Extension HOST_CHARSET 53605caefcfSchristosThis macro indicates the basic character set and encoding used by the 53705caefcfSchristoshost: more precisely, the encoding used for character constants in 53805caefcfSchristospreprocessor @samp{#if} statements (the C "execution character set"). 53905caefcfSchristosIt is defined by @file{safe-ctype.h}, and will be an integer constant 54005caefcfSchristoswith one of the following values: 54105caefcfSchristos 54205caefcfSchristos@ftable @code 54305caefcfSchristos@item HOST_CHARSET_UNKNOWN 54405caefcfSchristosThe host character set is unknown - that is, not one of the next two 54505caefcfSchristospossibilities. 54605caefcfSchristos 54705caefcfSchristos@item HOST_CHARSET_ASCII 54805caefcfSchristosThe host character set is ASCII. 54905caefcfSchristos 55005caefcfSchristos@item HOST_CHARSET_EBCDIC 55105caefcfSchristosThe host character set is some variant of EBCDIC. (Only one of the 55205caefcfSchristosnineteen EBCDIC varying characters is tested; exercise caution.) 55305caefcfSchristos@end ftable 55405caefcfSchristos@end defvr 55505caefcfSchristos 556f7172901Schristos@c hashtab.c:327 55705caefcfSchristos@deftypefn Supplemental htab_t htab_create_typed_alloc (size_t @var{size}, @ 55805caefcfSchristoshtab_hash @var{hash_f}, htab_eq @var{eq_f}, htab_del @var{del_f}, @ 55905caefcfSchristoshtab_alloc @var{alloc_tab_f}, htab_alloc @var{alloc_f}, @ 560b3ac4aedSchristoshtab_free @var{free_f}) 561b3ac4aedSchristos 562b3ac4aedSchristosThis function creates a hash table that uses two different allocators 563b3ac4aedSchristos@var{alloc_tab_f} and @var{alloc_f} to use for allocating the table itself 564b3ac4aedSchristosand its entries respectively. This is useful when variables of different 565b3ac4aedSchristostypes need to be allocated with different allocators. 566b3ac4aedSchristos 567b3ac4aedSchristosThe created hash table is slightly larger than @var{size} and it is 568b3ac4aedSchristosinitially empty (all the hash table entries are @code{HTAB_EMPTY_ENTRY}). 569b3ac4aedSchristosThe function returns the created hash table, or @code{NULL} if memory 570b3ac4aedSchristosallocation fails. 571b3ac4aedSchristos 572b3ac4aedSchristos@end deftypefn 573b3ac4aedSchristos 5742a6b7db3Sskrll@c index.c:5 5752a6b7db3Sskrll@deftypefn Supplemental char* index (char *@var{s}, int @var{c}) 5762a6b7db3Sskrll 5772a6b7db3SskrllReturns a pointer to the first occurrence of the character @var{c} in 5782a6b7db3Sskrllthe string @var{s}, or @code{NULL} if not found. The use of @code{index} is 5792a6b7db3Sskrlldeprecated in new programs in favor of @code{strchr}. 5802a6b7db3Sskrll 5812a6b7db3Sskrll@end deftypefn 5822a6b7db3Sskrll 5832a6b7db3Sskrll@c insque.c:6 58405caefcfSchristos@deftypefn Supplemental void insque (struct qelem *@var{elem}, @ 58505caefcfSchristos struct qelem *@var{pred}) 5862a6b7db3Sskrll@deftypefnx Supplemental void remque (struct qelem *@var{elem}) 5872a6b7db3Sskrll 5882a6b7db3SskrllRoutines to manipulate queues built from doubly linked lists. The 5892a6b7db3Sskrll@code{insque} routine inserts @var{elem} in the queue immediately 5902a6b7db3Sskrllafter @var{pred}. The @code{remque} routine removes @var{elem} from 5912a6b7db3Sskrllits containing queue. These routines expect to be passed pointers to 5922a6b7db3Sskrllstructures which have as their first members a forward pointer and a 5932a6b7db3Sskrllback pointer, like this prototype (although no prototype is provided): 5942a6b7db3Sskrll 5952a6b7db3Sskrll@example 5962a6b7db3Sskrllstruct qelem @{ 5972a6b7db3Sskrll struct qelem *q_forw; 5982a6b7db3Sskrll struct qelem *q_back; 5992a6b7db3Sskrll char q_data[]; 6002a6b7db3Sskrll@}; 6012a6b7db3Sskrll@end example 6022a6b7db3Sskrll 6032a6b7db3Sskrll@end deftypefn 6042a6b7db3Sskrll 605f7172901Schristos@c safe-ctype.c:45 6062a6b7db3Sskrll@deffn Extension ISALPHA (@var{c}) 6072a6b7db3Sskrll@deffnx Extension ISALNUM (@var{c}) 6082a6b7db3Sskrll@deffnx Extension ISBLANK (@var{c}) 6092a6b7db3Sskrll@deffnx Extension ISCNTRL (@var{c}) 6102a6b7db3Sskrll@deffnx Extension ISDIGIT (@var{c}) 6112a6b7db3Sskrll@deffnx Extension ISGRAPH (@var{c}) 6122a6b7db3Sskrll@deffnx Extension ISLOWER (@var{c}) 6132a6b7db3Sskrll@deffnx Extension ISPRINT (@var{c}) 6142a6b7db3Sskrll@deffnx Extension ISPUNCT (@var{c}) 6152a6b7db3Sskrll@deffnx Extension ISSPACE (@var{c}) 6162a6b7db3Sskrll@deffnx Extension ISUPPER (@var{c}) 6172a6b7db3Sskrll@deffnx Extension ISXDIGIT (@var{c}) 6182a6b7db3Sskrll 6192a6b7db3SskrllThese twelve macros are defined by @file{safe-ctype.h}. Each has the 6202a6b7db3Sskrllsame meaning as the corresponding macro (with name in lowercase) 6212a6b7db3Sskrlldefined by the standard header @file{ctype.h}. For example, 6222a6b7db3Sskrll@code{ISALPHA} returns true for alphabetic characters and false for 6232a6b7db3Sskrllothers. However, there are two differences between these macros and 6242a6b7db3Sskrllthose provided by @file{ctype.h}: 6252a6b7db3Sskrll 6262a6b7db3Sskrll@itemize @bullet 6272a6b7db3Sskrll@item These macros are guaranteed to have well-defined behavior for all 6282a6b7db3Sskrllvalues representable by @code{signed char} and @code{unsigned char}, and 6292a6b7db3Sskrllfor @code{EOF}. 6302a6b7db3Sskrll 6312a6b7db3Sskrll@item These macros ignore the current locale; they are true for these 6322a6b7db3Sskrllfixed sets of characters: 6332a6b7db3Sskrll@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada} 6342a6b7db3Sskrll@item @code{ALPHA} @tab @kbd{A-Za-z} 6352a6b7db3Sskrll@item @code{ALNUM} @tab @kbd{A-Za-z0-9} 6362a6b7db3Sskrll@item @code{BLANK} @tab @kbd{space tab} 6372a6b7db3Sskrll@item @code{CNTRL} @tab @code{!PRINT} 6382a6b7db3Sskrll@item @code{DIGIT} @tab @kbd{0-9} 6392a6b7db3Sskrll@item @code{GRAPH} @tab @code{ALNUM || PUNCT} 6402a6b7db3Sskrll@item @code{LOWER} @tab @kbd{a-z} 6412a6b7db3Sskrll@item @code{PRINT} @tab @code{GRAPH ||} @kbd{space} 6422a6b7db3Sskrll@item @code{PUNCT} @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?} 6432a6b7db3Sskrll@item @code{SPACE} @tab @kbd{space tab \n \r \f \v} 6442a6b7db3Sskrll@item @code{UPPER} @tab @kbd{A-Z} 6452a6b7db3Sskrll@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f} 6462a6b7db3Sskrll@end multitable 6472a6b7db3Sskrll 6482a6b7db3SskrllNote that, if the host character set is ASCII or a superset thereof, 6492a6b7db3Sskrllall these macros will return false for all values of @code{char} outside 6502a6b7db3Sskrllthe range of 7-bit ASCII. In particular, both ISPRINT and ISCNTRL return 6512a6b7db3Sskrllfalse for characters with numeric values from 128 to 255. 6522a6b7db3Sskrll@end itemize 6532a6b7db3Sskrll@end deffn 6542a6b7db3Sskrll 655f7172901Schristos@c safe-ctype.c:94 6562a6b7db3Sskrll@deffn Extension ISIDNUM (@var{c}) 6572a6b7db3Sskrll@deffnx Extension ISIDST (@var{c}) 6582a6b7db3Sskrll@deffnx Extension IS_VSPACE (@var{c}) 6592a6b7db3Sskrll@deffnx Extension IS_NVSPACE (@var{c}) 6602a6b7db3Sskrll@deffnx Extension IS_SPACE_OR_NUL (@var{c}) 6612a6b7db3Sskrll@deffnx Extension IS_ISOBASIC (@var{c}) 6622a6b7db3SskrllThese six macros are defined by @file{safe-ctype.h} and provide 6632a6b7db3Sskrlladditional character classes which are useful when doing lexical 6642a6b7db3Sskrllanalysis of C or similar languages. They are true for the following 6652a6b7db3Sskrllsets of characters: 6662a6b7db3Sskrll 6672a6b7db3Sskrll@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada} 6682a6b7db3Sskrll@item @code{IDNUM} @tab @kbd{A-Za-z0-9_} 6692a6b7db3Sskrll@item @code{IDST} @tab @kbd{A-Za-z_} 6702a6b7db3Sskrll@item @code{VSPACE} @tab @kbd{\r \n} 6712a6b7db3Sskrll@item @code{NVSPACE} @tab @kbd{space tab \f \v \0} 6722a6b7db3Sskrll@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE} 6732a6b7db3Sskrll@item @code{ISOBASIC} @tab @code{VSPACE || NVSPACE || PRINT} 6742a6b7db3Sskrll@end multitable 6752a6b7db3Sskrll@end deffn 6762a6b7db3Sskrll 6772a6b7db3Sskrll@c lbasename.c:23 6782a6b7db3Sskrll@deftypefn Replacement {const char*} lbasename (const char *@var{name}) 6792a6b7db3Sskrll 6802a6b7db3SskrllGiven a pointer to a string containing a typical pathname 6812a6b7db3Sskrll(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the 6822a6b7db3Sskrlllast component of the pathname (@samp{ls.c} in this case). The 6832a6b7db3Sskrllreturned pointer is guaranteed to lie within the original 6842a6b7db3Sskrllstring. This latter fact is not true of many vendor C 6852a6b7db3Sskrlllibraries, which return special strings or modify the passed 6862a6b7db3Sskrllstrings for particular input. 6872a6b7db3Sskrll 6882a6b7db3SskrllIn particular, the empty string returns the same empty string, 6892a6b7db3Sskrlland a path ending in @code{/} returns the empty string after it. 6902a6b7db3Sskrll 6912a6b7db3Sskrll@end deftypefn 6922a6b7db3Sskrll 6932a6b7db3Sskrll@c lrealpath.c:25 6942a6b7db3Sskrll@deftypefn Replacement {const char*} lrealpath (const char *@var{name}) 6952a6b7db3Sskrll 6962a6b7db3SskrllGiven a pointer to a string containing a pathname, returns a canonical 6972a6b7db3Sskrllversion of the filename. Symlinks will be resolved, and ``.'' and ``..'' 6982a6b7db3Sskrllcomponents will be simplified. The returned value will be allocated using 6992a6b7db3Sskrll@code{malloc}, or @code{NULL} will be returned on a memory allocation error. 7002a6b7db3Sskrll 7012a6b7db3Sskrll@end deftypefn 7022a6b7db3Sskrll 703f7172901Schristos@c make-relative-prefix.c:23 70405caefcfSchristos@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, @ 70505caefcfSchristos const char *@var{bin_prefix}, const char *@var{prefix}) 7062a6b7db3Sskrll 7072a6b7db3SskrllGiven three paths @var{progname}, @var{bin_prefix}, @var{prefix}, 7082a6b7db3Sskrllreturn the path that is in the same position relative to 7092a6b7db3Sskrll@var{progname}'s directory as @var{prefix} is relative to 7102a6b7db3Sskrll@var{bin_prefix}. That is, a string starting with the directory 7112a6b7db3Sskrllportion of @var{progname}, followed by a relative pathname of the 7122a6b7db3Sskrlldifference between @var{bin_prefix} and @var{prefix}. 7132a6b7db3Sskrll 7142a6b7db3SskrllIf @var{progname} does not contain any directory separators, 7152a6b7db3Sskrll@code{make_relative_prefix} will search @env{PATH} to find a program 7162a6b7db3Sskrllnamed @var{progname}. Also, if @var{progname} is a symbolic link, 7172a6b7db3Sskrllthe symbolic link will be resolved. 7182a6b7db3Sskrll 7192a6b7db3SskrllFor example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta}, 7202a6b7db3Sskrll@var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is 7212a6b7db3Sskrll@code{/red/green/blue/gcc}, then this function will return 7222a6b7db3Sskrll@code{/red/green/blue/../../omega/}. 7232a6b7db3Sskrll 7242a6b7db3SskrllThe return value is normally allocated via @code{malloc}. If no 7252a6b7db3Sskrllrelative prefix can be found, return @code{NULL}. 7262a6b7db3Sskrll 7272a6b7db3Sskrll@end deftypefn 7282a6b7db3Sskrll 729f7172901Schristos@c make-temp-file.c:173 7302a6b7db3Sskrll@deftypefn Replacement char* make_temp_file (const char *@var{suffix}) 7312a6b7db3Sskrll 7322a6b7db3SskrllReturn a temporary file name (as a string) or @code{NULL} if unable to 7332a6b7db3Sskrllcreate one. @var{suffix} is a suffix to append to the file name. The 7342a6b7db3Sskrllstring is @code{malloc}ed, and the temporary file has been created. 7352a6b7db3Sskrll 7362a6b7db3Sskrll@end deftypefn 7372a6b7db3Sskrll 7382a6b7db3Sskrll@c memchr.c:3 73905caefcfSchristos@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, @ 74005caefcfSchristos size_t @var{n}) 7412a6b7db3Sskrll 7422a6b7db3SskrllThis function searches memory starting at @code{*@var{s}} for the 7432a6b7db3Sskrllcharacter @var{c}. The search only ends with the first occurrence of 7442a6b7db3Sskrll@var{c}, or after @var{length} characters; in particular, a null 7452a6b7db3Sskrllcharacter does not terminate the search. If the character @var{c} is 7462a6b7db3Sskrllfound within @var{length} characters of @code{*@var{s}}, a pointer 7472a6b7db3Sskrllto the character is returned. If @var{c} is not found, then @code{NULL} is 7482a6b7db3Sskrllreturned. 7492a6b7db3Sskrll 7502a6b7db3Sskrll@end deftypefn 7512a6b7db3Sskrll 7522a6b7db3Sskrll@c memcmp.c:6 75305caefcfSchristos@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, @ 75405caefcfSchristos size_t @var{count}) 7552a6b7db3Sskrll 7562a6b7db3SskrllCompares the first @var{count} bytes of two areas of memory. Returns 7572a6b7db3Sskrllzero if they are the same, a value less than zero if @var{x} is 7582a6b7db3Sskrlllexically less than @var{y}, or a value greater than zero if @var{x} 7592a6b7db3Sskrllis lexically greater than @var{y}. Note that lexical order is determined 7602a6b7db3Sskrllas if comparing unsigned char arrays. 7612a6b7db3Sskrll 7622a6b7db3Sskrll@end deftypefn 7632a6b7db3Sskrll 7642a6b7db3Sskrll@c memcpy.c:6 76505caefcfSchristos@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, @ 76605caefcfSchristos size_t @var{length}) 7672a6b7db3Sskrll 7682a6b7db3SskrllCopies @var{length} bytes from memory region @var{in} to region 7692a6b7db3Sskrll@var{out}. Returns a pointer to @var{out}. 7702a6b7db3Sskrll 7712a6b7db3Sskrll@end deftypefn 7722a6b7db3Sskrll 773b3ac4aedSchristos@c memmem.c:20 77405caefcfSchristos@deftypefn Supplemental void* memmem (const void *@var{haystack}, @ 77505caefcfSchristos size_t @var{haystack_len} const void *@var{needle}, size_t @var{needle_len}) 776b3ac4aedSchristos 777b3ac4aedSchristosReturns a pointer to the first occurrence of @var{needle} (length 778b3ac4aedSchristos@var{needle_len}) in @var{haystack} (length @var{haystack_len}). 779b3ac4aedSchristosReturns @code{NULL} if not found. 780b3ac4aedSchristos 781b3ac4aedSchristos@end deftypefn 782b3ac4aedSchristos 7832a6b7db3Sskrll@c memmove.c:6 78405caefcfSchristos@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, @ 78505caefcfSchristos size_t @var{count}) 7862a6b7db3Sskrll 7872a6b7db3SskrllCopies @var{count} bytes from memory area @var{from} to memory area 7882a6b7db3Sskrll@var{to}, returning a pointer to @var{to}. 7892a6b7db3Sskrll 7902a6b7db3Sskrll@end deftypefn 7912a6b7db3Sskrll 7922a6b7db3Sskrll@c mempcpy.c:23 79305caefcfSchristos@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, @ 79405caefcfSchristos size_t @var{length}) 7952a6b7db3Sskrll 7962a6b7db3SskrllCopies @var{length} bytes from memory region @var{in} to region 7972a6b7db3Sskrll@var{out}. Returns a pointer to @var{out} + @var{length}. 7982a6b7db3Sskrll 7992a6b7db3Sskrll@end deftypefn 8002a6b7db3Sskrll 8012a6b7db3Sskrll@c memset.c:6 80205caefcfSchristos@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, @ 80305caefcfSchristos size_t @var{count}) 8042a6b7db3Sskrll 8052a6b7db3SskrllSets the first @var{count} bytes of @var{s} to the constant byte 8062a6b7db3Sskrll@var{c}, returning a pointer to @var{s}. 8072a6b7db3Sskrll 8082a6b7db3Sskrll@end deftypefn 8092a6b7db3Sskrll 810f7172901Schristos@c mkstemps.c:60 8112a6b7db3Sskrll@deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len}) 8122a6b7db3Sskrll 8132a6b7db3SskrllGenerate a unique temporary file name from @var{pattern}. 8142a6b7db3Sskrll@var{pattern} has the form: 8152a6b7db3Sskrll 8162a6b7db3Sskrll@example 8172a6b7db3Sskrll @var{path}/ccXXXXXX@var{suffix} 8182a6b7db3Sskrll@end example 8192a6b7db3Sskrll 8202a6b7db3Sskrll@var{suffix_len} tells us how long @var{suffix} is (it can be zero 8212a6b7db3Sskrlllength). The last six characters of @var{pattern} before @var{suffix} 8222a6b7db3Sskrllmust be @samp{XXXXXX}; they are replaced with a string that makes the 8232a6b7db3Sskrllfilename unique. Returns a file descriptor open on the file for 8242a6b7db3Sskrllreading and writing. 8252a6b7db3Sskrll 8262a6b7db3Sskrll@end deftypefn 8272a6b7db3Sskrll 82805caefcfSchristos@c pexecute.txh:278 8292a6b7db3Sskrll@deftypefn Extension void pex_free (struct pex_obj @var{obj}) 8302a6b7db3Sskrll 8312a6b7db3SskrllClean up and free all data associated with @var{obj}. If you have not 8322a6b7db3Sskrllyet called @code{pex_get_times} or @code{pex_get_status}, this will 8332a6b7db3Sskrlltry to kill the subprocesses. 8342a6b7db3Sskrll 8352a6b7db3Sskrll@end deftypefn 8362a6b7db3Sskrll 83705caefcfSchristos@c pexecute.txh:251 83805caefcfSchristos@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, @ 83905caefcfSchristos int @var{count}, int *@var{vector}) 8402a6b7db3Sskrll 8412a6b7db3SskrllReturns the exit status of all programs run using @var{obj}. 8422a6b7db3Sskrll@var{count} is the number of results expected. The results will be 8432a6b7db3Sskrllplaced into @var{vector}. The results are in the order of the calls 8442a6b7db3Sskrllto @code{pex_run}. Returns 0 on error, 1 on success. 8452a6b7db3Sskrll 8462a6b7db3Sskrll@end deftypefn 8472a6b7db3Sskrll 84805caefcfSchristos@c pexecute.txh:261 84905caefcfSchristos@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, @ 85005caefcfSchristos int @var{count}, struct pex_time *@var{vector}) 8512a6b7db3Sskrll 8522a6b7db3SskrllReturns the process execution times of all programs run using 8532a6b7db3Sskrll@var{obj}. @var{count} is the number of results expected. The 8542a6b7db3Sskrllresults will be placed into @var{vector}. The results are in the 8552a6b7db3Sskrllorder of the calls to @code{pex_run}. Returns 0 on error, 1 on 8562a6b7db3Sskrllsuccess. 8572a6b7db3Sskrll 8582a6b7db3Sskrll@code{struct pex_time} has the following fields of the type 8592a6b7db3Sskrll@code{unsigned long}: @code{user_seconds}, 8602a6b7db3Sskrll@code{user_microseconds}, @code{system_seconds}, 8612a6b7db3Sskrll@code{system_microseconds}. On systems which do not support reporting 8622a6b7db3Sskrllprocess times, all the fields will be set to @code{0}. 8632a6b7db3Sskrll 8642a6b7db3Sskrll@end deftypefn 8652a6b7db3Sskrll 8662a6b7db3Sskrll@c pexecute.txh:2 86705caefcfSchristos@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, @ 86805caefcfSchristos const char *@var{pname}, const char *@var{tempbase}) 8692a6b7db3Sskrll 8702a6b7db3SskrllPrepare to execute one or more programs, with standard output of each 8712a6b7db3Sskrllprogram fed to standard input of the next. This is a system 8722a6b7db3Sskrllindependent interface to execute a pipeline. 8732a6b7db3Sskrll 8742a6b7db3Sskrll@var{flags} is a bitwise combination of the following: 8752a6b7db3Sskrll 8762a6b7db3Sskrll@table @code 8772a6b7db3Sskrll 8782a6b7db3Sskrll@vindex PEX_RECORD_TIMES 8792a6b7db3Sskrll@item PEX_RECORD_TIMES 8802a6b7db3SskrllRecord subprocess times if possible. 8812a6b7db3Sskrll 8822a6b7db3Sskrll@vindex PEX_USE_PIPES 8832a6b7db3Sskrll@item PEX_USE_PIPES 8842a6b7db3SskrllUse pipes for communication between processes, if possible. 8852a6b7db3Sskrll 8862a6b7db3Sskrll@vindex PEX_SAVE_TEMPS 8872a6b7db3Sskrll@item PEX_SAVE_TEMPS 8882a6b7db3SskrllDon't delete temporary files used for communication between 8892a6b7db3Sskrllprocesses. 8902a6b7db3Sskrll 8912a6b7db3Sskrll@end table 8922a6b7db3Sskrll 8932a6b7db3Sskrll@var{pname} is the name of program to be executed, used in error 8942a6b7db3Sskrllmessages. @var{tempbase} is a base name to use for any required 8952a6b7db3Sskrlltemporary files; it may be @code{NULL} to use a randomly chosen name. 8962a6b7db3Sskrll 8972a6b7db3Sskrll@end deftypefn 8982a6b7db3Sskrll 89905caefcfSchristos@c pexecute.txh:161 90005caefcfSchristos@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, @ 90105caefcfSchristos int @var{flags}, const char *@var{in_name}) 9022a6b7db3Sskrll 9032a6b7db3SskrllReturn a stream for a temporary file to pass to the first program in 9042a6b7db3Sskrllthe pipeline as input. 9052a6b7db3Sskrll 9062a6b7db3SskrllThe name of the input file is chosen according to the same rules 9072a6b7db3Sskrll@code{pex_run} uses to choose output file names, based on 9082a6b7db3Sskrll@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}. 9092a6b7db3Sskrll 9102a6b7db3SskrllDon't call @code{fclose} on the returned stream; the first call to 9112a6b7db3Sskrll@code{pex_run} closes it automatically. 9122a6b7db3Sskrll 9132a6b7db3SskrllIf @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in 9142a6b7db3Sskrllbinary mode; otherwise, open it in the default mode. Including 9152a6b7db3Sskrll@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix. 9162a6b7db3Sskrll@end deftypefn 9172a6b7db3Sskrll 91805caefcfSchristos@c pexecute.txh:179 91905caefcfSchristos@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, @ 92005caefcfSchristos int @var{binary}) 9212a6b7db3Sskrll 9222a6b7db3SskrllReturn a stream @var{fp} for a pipe connected to the standard input of 9232a6b7db3Sskrllthe first program in the pipeline; @var{fp} is opened for writing. 9242a6b7db3SskrllYou must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call 9252a6b7db3Sskrllthat returned @var{obj}. 9262a6b7db3Sskrll 9272a6b7db3SskrllYou must close @var{fp} using @code{fclose} yourself when you have 9282a6b7db3Sskrllfinished writing data to the pipeline. 9292a6b7db3Sskrll 9302a6b7db3SskrllThe file descriptor underlying @var{fp} is marked not to be inherited 9312a6b7db3Sskrllby child processes. 9322a6b7db3Sskrll 9332a6b7db3SskrllOn systems that do not support pipes, this function returns 9342a6b7db3Sskrll@code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would 9352a6b7db3Sskrlllike to write code that is portable to all systems the @code{pex} 9362a6b7db3Sskrllfunctions support, consider using @code{pex_input_file} instead. 9372a6b7db3Sskrll 9382a6b7db3SskrllThere are two opportunities for deadlock using 9392a6b7db3Sskrll@code{pex_input_pipe}: 9402a6b7db3Sskrll 9412a6b7db3Sskrll@itemize @bullet 9422a6b7db3Sskrll@item 9432a6b7db3SskrllMost systems' pipes can buffer only a fixed amount of data; a process 9442a6b7db3Sskrllthat writes to a full pipe blocks. Thus, if you write to @file{fp} 9452a6b7db3Sskrllbefore starting the first process, you run the risk of blocking when 9462a6b7db3Sskrllthere is no child process yet to read the data and allow you to 9472a6b7db3Sskrllcontinue. @code{pex_input_pipe} makes no promises about the 9482a6b7db3Sskrllsize of the pipe's buffer, so if you need to write any data at all 9492a6b7db3Sskrllbefore starting the first process in the pipeline, consider using 9502a6b7db3Sskrll@code{pex_input_file} instead. 9512a6b7db3Sskrll 9522a6b7db3Sskrll@item 9532a6b7db3SskrllUsing @code{pex_input_pipe} and @code{pex_read_output} together 9542a6b7db3Sskrllmay also cause deadlock. If the output pipe fills up, so that each 9552a6b7db3Sskrllprogram in the pipeline is waiting for the next to read more data, and 9562a6b7db3Sskrllyou fill the input pipe by writing more data to @var{fp}, then there 9572a6b7db3Sskrllis no way to make progress: the only process that could read data from 9582a6b7db3Sskrllthe output pipe is you, but you are blocked on the input pipe. 9592a6b7db3Sskrll 9602a6b7db3Sskrll@end itemize 9612a6b7db3Sskrll 9622a6b7db3Sskrll@end deftypefn 9632a6b7db3Sskrll 96405caefcfSchristos@c pexecute.txh:286 96505caefcfSchristos@deftypefn Extension {const char *} pex_one (int @var{flags}, @ 96605caefcfSchristos const char *@var{executable}, char * const *@var{argv}, @ 96705caefcfSchristos const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, @ 96805caefcfSchristos int *@var{status}, int *@var{err}) 9692a6b7db3Sskrll 9702a6b7db3SskrllAn interface to permit the easy execution of a 9712a6b7db3Sskrllsingle program. The return value and most of the parameters are as 9722a6b7db3Sskrllfor a call to @code{pex_run}. @var{flags} is restricted to a 9732a6b7db3Sskrllcombination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and 9742a6b7db3Sskrll@code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if 9752a6b7db3Sskrll@code{PEX_LAST} were set. On a successful return, @code{*@var{status}} will 9762a6b7db3Sskrllbe set to the exit status of the program. 9772a6b7db3Sskrll 9782a6b7db3Sskrll@end deftypefn 9792a6b7db3Sskrll 98005caefcfSchristos@c pexecute.txh:237 98105caefcfSchristos@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, @ 98205caefcfSchristos int @var{binary}) 9832a6b7db3Sskrll 9842a6b7db3SskrllReturns a @code{FILE} pointer which may be used to read the standard 9852a6b7db3Sskrllerror of the last program in the pipeline. When this is used, 9862a6b7db3Sskrll@code{PEX_LAST} should not be used in a call to @code{pex_run}. After 9872a6b7db3Sskrllthis is called, @code{pex_run} may no longer be called with the same 9882a6b7db3Sskrll@var{obj}. @var{binary} should be non-zero if the file should be 9892a6b7db3Sskrllopened in binary mode. Don't call @code{fclose} on the returned file; 9902a6b7db3Sskrllit will be closed by @code{pex_free}. 9912a6b7db3Sskrll 9922a6b7db3Sskrll@end deftypefn 9932a6b7db3Sskrll 99405caefcfSchristos@c pexecute.txh:224 99505caefcfSchristos@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, @ 99605caefcfSchristos int @var{binary}) 9972a6b7db3Sskrll 9982a6b7db3SskrllReturns a @code{FILE} pointer which may be used to read the standard 9992a6b7db3Sskrlloutput of the last program in the pipeline. When this is used, 10002a6b7db3Sskrll@code{PEX_LAST} should not be used in a call to @code{pex_run}. After 10012a6b7db3Sskrllthis is called, @code{pex_run} may no longer be called with the same 10022a6b7db3Sskrll@var{obj}. @var{binary} should be non-zero if the file should be 10032a6b7db3Sskrllopened in binary mode. Don't call @code{fclose} on the returned file; 10042a6b7db3Sskrllit will be closed by @code{pex_free}. 10052a6b7db3Sskrll 10062a6b7db3Sskrll@end deftypefn 10072a6b7db3Sskrll 100805caefcfSchristos@c pexecute.txh:34 100905caefcfSchristos@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, @ 101005caefcfSchristos int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ 101105caefcfSchristos const char *@var{outname}, const char *@var{errname}, int *@var{err}) 10122a6b7db3Sskrll 10132a6b7db3SskrllExecute one program in a pipeline. On success this returns 10142a6b7db3Sskrll@code{NULL}. On failure it returns an error message, a statically 10152a6b7db3Sskrllallocated string. 10162a6b7db3Sskrll 10172a6b7db3Sskrll@var{obj} is returned by a previous call to @code{pex_init}. 10182a6b7db3Sskrll 10192a6b7db3Sskrll@var{flags} is a bitwise combination of the following: 10202a6b7db3Sskrll 10212a6b7db3Sskrll@table @code 10222a6b7db3Sskrll 10232a6b7db3Sskrll@vindex PEX_LAST 10242a6b7db3Sskrll@item PEX_LAST 10252a6b7db3SskrllThis must be set on the last program in the pipeline. In particular, 10262a6b7db3Sskrllit should be set when executing a single program. The standard output 10272a6b7db3Sskrllof the program will be sent to @var{outname}, or, if @var{outname} is 10282a6b7db3Sskrll@code{NULL}, to the standard output of the calling program. Do @emph{not} 10292a6b7db3Sskrllset this bit if you want to call @code{pex_read_output} 10302a6b7db3Sskrll(described below). After a call to @code{pex_run} with this bit set, 10312a6b7db3Sskrll@var{pex_run} may no longer be called with the same @var{obj}. 10322a6b7db3Sskrll 10332a6b7db3Sskrll@vindex PEX_SEARCH 10342a6b7db3Sskrll@item PEX_SEARCH 10352a6b7db3SskrllSearch for the program using the user's executable search path. 10362a6b7db3Sskrll 10372a6b7db3Sskrll@vindex PEX_SUFFIX 10382a6b7db3Sskrll@item PEX_SUFFIX 10392a6b7db3Sskrll@var{outname} is a suffix. See the description of @var{outname}, 10402a6b7db3Sskrllbelow. 10412a6b7db3Sskrll 10422a6b7db3Sskrll@vindex PEX_STDERR_TO_STDOUT 10432a6b7db3Sskrll@item PEX_STDERR_TO_STDOUT 10442a6b7db3SskrllSend the program's standard error to standard output, if possible. 10452a6b7db3Sskrll 10462a6b7db3Sskrll@vindex PEX_BINARY_INPUT 10472a6b7db3Sskrll@vindex PEX_BINARY_OUTPUT 10482a6b7db3Sskrll@vindex PEX_BINARY_ERROR 10492a6b7db3Sskrll@item PEX_BINARY_INPUT 10502a6b7db3Sskrll@itemx PEX_BINARY_OUTPUT 10512a6b7db3Sskrll@itemx PEX_BINARY_ERROR 10522a6b7db3SskrllThe standard input (output or error) of the program should be read (written) in 10532a6b7db3Sskrllbinary mode rather than text mode. These flags are ignored on systems 10542a6b7db3Sskrllwhich do not distinguish binary mode and text mode, such as Unix. For 10552a6b7db3Sskrllproper behavior these flags should match appropriately---a call to 10562a6b7db3Sskrll@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a 10572a6b7db3Sskrllcall using @code{PEX_BINARY_INPUT}. 10582a6b7db3Sskrll 10592a6b7db3Sskrll@vindex PEX_STDERR_TO_PIPE 10602a6b7db3Sskrll@item PEX_STDERR_TO_PIPE 10612a6b7db3SskrllSend the program's standard error to a pipe, if possible. This flag 10622a6b7db3Sskrllcannot be specified together with @code{PEX_STDERR_TO_STDOUT}. This 10632a6b7db3Sskrllflag can be specified only on the last program in pipeline. 10642a6b7db3Sskrll 10652a6b7db3Sskrll@end table 10662a6b7db3Sskrll 10672a6b7db3Sskrll@var{executable} is the program to execute. @var{argv} is the set of 10682a6b7db3Sskrllarguments to pass to the program; normally @code{@var{argv}[0]} will 10692a6b7db3Sskrllbe a copy of @var{executable}. 10702a6b7db3Sskrll 10712a6b7db3Sskrll@var{outname} is used to set the name of the file to use for standard 10722a6b7db3Sskrlloutput. There are two cases in which no output file will be used: 10732a6b7db3Sskrll 10742a6b7db3Sskrll@enumerate 10752a6b7db3Sskrll@item 10762a6b7db3Sskrllif @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} 10772a6b7db3Sskrllwas set in the call to @code{pex_init}, and the system supports pipes 10782a6b7db3Sskrll 10792a6b7db3Sskrll@item 10802a6b7db3Sskrllif @code{PEX_LAST} is set in @var{flags}, and @var{outname} is 10812a6b7db3Sskrll@code{NULL} 10822a6b7db3Sskrll@end enumerate 10832a6b7db3Sskrll 10842a6b7db3Sskrll@noindent 10852a6b7db3SskrllOtherwise the code will use a file to hold standard 10862a6b7db3Sskrlloutput. If @code{PEX_LAST} is not set, this file is considered to be 10872a6b7db3Sskrlla temporary file, and it will be removed when no longer needed, unless 10882a6b7db3Sskrll@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. 10892a6b7db3Sskrll 10902a6b7db3SskrllThere are two cases to consider when setting the name of the file to 10912a6b7db3Sskrllhold standard output. 10922a6b7db3Sskrll 10932a6b7db3Sskrll@enumerate 10942a6b7db3Sskrll@item 10952a6b7db3Sskrll@code{PEX_SUFFIX} is set in @var{flags}. In this case 10962a6b7db3Sskrll@var{outname} may not be @code{NULL}. If the @var{tempbase} parameter 10972a6b7db3Sskrllto @code{pex_init} was not @code{NULL}, then the output file name is 10982a6b7db3Sskrllthe concatenation of @var{tempbase} and @var{outname}. If 10992a6b7db3Sskrll@var{tempbase} was @code{NULL}, then the output file name is a random 11002a6b7db3Sskrllfile name ending in @var{outname}. 11012a6b7db3Sskrll 11022a6b7db3Sskrll@item 11032a6b7db3Sskrll@code{PEX_SUFFIX} was not set in @var{flags}. In this 11042a6b7db3Sskrllcase, if @var{outname} is not @code{NULL}, it is used as the output 11052a6b7db3Sskrllfile name. If @var{outname} is @code{NULL}, and @var{tempbase} was 11062a6b7db3Sskrllnot NULL, the output file name is randomly chosen using 11072a6b7db3Sskrll@var{tempbase}. Otherwise the output file name is chosen completely 11082a6b7db3Sskrllat random. 11092a6b7db3Sskrll@end enumerate 11102a6b7db3Sskrll 11112a6b7db3Sskrll@var{errname} is the file name to use for standard error output. If 11122a6b7db3Sskrllit is @code{NULL}, standard error is the same as the caller's. 11132a6b7db3SskrllOtherwise, standard error is written to the named file. 11142a6b7db3Sskrll 11152a6b7db3SskrllOn an error return, the code sets @code{*@var{err}} to an @code{errno} 11162a6b7db3Sskrllvalue, or to 0 if there is no relevant @code{errno}. 11172a6b7db3Sskrll 11182a6b7db3Sskrll@end deftypefn 11192a6b7db3Sskrll 112005caefcfSchristos@c pexecute.txh:145 112105caefcfSchristos@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, @ 112205caefcfSchristos int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ 112305caefcfSchristos char * const *@var{env}, int @var{env_size}, const char *@var{outname}, @ 112405caefcfSchristos const char *@var{errname}, int *@var{err}) 11252a6b7db3Sskrll 11262a6b7db3SskrllExecute one program in a pipeline, permitting the environment for the 11272a6b7db3Sskrllprogram to be specified. Behaviour and parameters not listed below are 11282a6b7db3Sskrllas for @code{pex_run}. 11292a6b7db3Sskrll 11302a6b7db3Sskrll@var{env} is the environment for the child process, specified as an array of 11312a6b7db3Sskrllcharacter pointers. Each element of the array should point to a string of the 11322a6b7db3Sskrllform @code{VAR=VALUE}, with the exception of the last element that must be 11332a6b7db3Sskrll@code{NULL}. 11342a6b7db3Sskrll 11352a6b7db3Sskrll@end deftypefn 11362a6b7db3Sskrll 113705caefcfSchristos@c pexecute.txh:301 113805caefcfSchristos@deftypefn Extension int pexecute (const char *@var{program}, @ 113905caefcfSchristos char * const *@var{argv}, const char *@var{this_pname}, @ 114005caefcfSchristos const char *@var{temp_base}, char **@var{errmsg_fmt}, @ 114105caefcfSchristos char **@var{errmsg_arg}, int @var{flags}) 11422a6b7db3Sskrll 11432a6b7db3SskrllThis is the old interface to execute one or more programs. It is 11442a6b7db3Sskrllstill supported for compatibility purposes, but is no longer 11452a6b7db3Sskrlldocumented. 11462a6b7db3Sskrll 11472a6b7db3Sskrll@end deftypefn 11482a6b7db3Sskrll 11492a6b7db3Sskrll@c strsignal.c:541 11502a6b7db3Sskrll@deftypefn Supplemental void psignal (int @var{signo}, char *@var{message}) 11512a6b7db3Sskrll 11522a6b7db3SskrllPrint @var{message} to the standard error, followed by a colon, 11532a6b7db3Sskrllfollowed by the description of the signal specified by @var{signo}, 11542a6b7db3Sskrllfollowed by a newline. 11552a6b7db3Sskrll 11562a6b7db3Sskrll@end deftypefn 11572a6b7db3Sskrll 11582a6b7db3Sskrll@c putenv.c:21 11592a6b7db3Sskrll@deftypefn Supplemental int putenv (const char *@var{string}) 11602a6b7db3Sskrll 11612a6b7db3SskrllUses @code{setenv} or @code{unsetenv} to put @var{string} into 11622a6b7db3Sskrllthe environment or remove it. If @var{string} is of the form 11632a6b7db3Sskrll@samp{name=value} the string is added; if no @samp{=} is present the 11642a6b7db3Sskrllname is unset/removed. 11652a6b7db3Sskrll 11662a6b7db3Sskrll@end deftypefn 11672a6b7db3Sskrll 116805caefcfSchristos@c pexecute.txh:312 11692a6b7db3Sskrll@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) 11702a6b7db3Sskrll 11712a6b7db3SskrllAnother part of the old execution interface. 11722a6b7db3Sskrll 11732a6b7db3Sskrll@end deftypefn 11742a6b7db3Sskrll 11752a6b7db3Sskrll@c random.c:39 11762a6b7db3Sskrll@deftypefn Supplement {long int} random (void) 11772a6b7db3Sskrll@deftypefnx Supplement void srandom (unsigned int @var{seed}) 117805caefcfSchristos@deftypefnx Supplement void* initstate (unsigned int @var{seed}, @ 117905caefcfSchristos void *@var{arg_state}, unsigned long @var{n}) 11802a6b7db3Sskrll@deftypefnx Supplement void* setstate (void *@var{arg_state}) 11812a6b7db3Sskrll 11822a6b7db3SskrllRandom number functions. @code{random} returns a random number in the 11832a6b7db3Sskrllrange 0 to @code{LONG_MAX}. @code{srandom} initializes the random 11842a6b7db3Sskrllnumber generator to some starting point determined by @var{seed} 11852a6b7db3Sskrll(else, the values returned by @code{random} are always the same for each 11862a6b7db3Sskrllrun of the program). @code{initstate} and @code{setstate} allow fine-grained 11872a6b7db3Sskrllcontrol over the state of the random number generator. 11882a6b7db3Sskrll 11892a6b7db3Sskrll@end deftypefn 11902a6b7db3Sskrll 11915ba6b03cSchristos@c concat.c:160 119205caefcfSchristos@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @ 119305caefcfSchristos @dots{}, @code{NULL}) 11942a6b7db3Sskrll 11952a6b7db3SskrllSame as @code{concat}, except that if @var{optr} is not @code{NULL} it 11962a6b7db3Sskrllis freed after the string is created. This is intended to be useful 11972a6b7db3Sskrllwhen you're extending an existing string or building up a string in a 11982a6b7db3Sskrllloop: 11992a6b7db3Sskrll 12002a6b7db3Sskrll@example 12012a6b7db3Sskrll str = reconcat (str, "pre-", str, NULL); 12022a6b7db3Sskrll@end example 12032a6b7db3Sskrll 12042a6b7db3Sskrll@end deftypefn 12052a6b7db3Sskrll 12062a6b7db3Sskrll@c rename.c:6 12072a6b7db3Sskrll@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new}) 12082a6b7db3Sskrll 12092a6b7db3SskrllRenames a file from @var{old} to @var{new}. If @var{new} already 12102a6b7db3Sskrllexists, it is removed. 12112a6b7db3Sskrll 12122a6b7db3Sskrll@end deftypefn 12132a6b7db3Sskrll 12142a6b7db3Sskrll@c rindex.c:5 12152a6b7db3Sskrll@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c}) 12162a6b7db3Sskrll 12172a6b7db3SskrllReturns a pointer to the last occurrence of the character @var{c} in 12182a6b7db3Sskrllthe string @var{s}, or @code{NULL} if not found. The use of @code{rindex} is 12192a6b7db3Sskrlldeprecated in new programs in favor of @code{strrchr}. 12202a6b7db3Sskrll 12212a6b7db3Sskrll@end deftypefn 12222a6b7db3Sskrll 1223f7172901Schristos@c setenv.c:22 122405caefcfSchristos@deftypefn Supplemental int setenv (const char *@var{name}, @ 122505caefcfSchristos const char *@var{value}, int @var{overwrite}) 12262a6b7db3Sskrll@deftypefnx Supplemental void unsetenv (const char *@var{name}) 12272a6b7db3Sskrll 12282a6b7db3Sskrll@code{setenv} adds @var{name} to the environment with value 12292a6b7db3Sskrll@var{value}. If the name was already present in the environment, 12302a6b7db3Sskrllthe new value will be stored only if @var{overwrite} is nonzero. 12312a6b7db3SskrllThe companion @code{unsetenv} function removes @var{name} from the 12322a6b7db3Sskrllenvironment. This implementation is not safe for multithreaded code. 12332a6b7db3Sskrll 12342a6b7db3Sskrll@end deftypefn 12352a6b7db3Sskrll 123605caefcfSchristos@c setproctitle.c:31 123705caefcfSchristos@deftypefn Supplemental void setproctitle (const char *@var{fmt}, ...) 1238b3ac4aedSchristos 1239b3ac4aedSchristosSet the title of a process to @var{fmt}. va args not supported for now, 1240b3ac4aedSchristosbut defined for compatibility with BSD. 1241b3ac4aedSchristos 1242b3ac4aedSchristos@end deftypefn 1243b3ac4aedSchristos 12442a6b7db3Sskrll@c strsignal.c:348 12452a6b7db3Sskrll@deftypefn Extension int signo_max (void) 12462a6b7db3Sskrll 12472a6b7db3SskrllReturns the maximum signal value for which a corresponding symbolic 12482a6b7db3Sskrllname or message is available. Note that in the case where we use the 12492a6b7db3Sskrll@code{sys_siglist} supplied by the system, it is possible for there to 12502a6b7db3Sskrllbe more symbolic names than messages, or vice versa. In fact, the 12512a6b7db3Sskrllmanual page for @code{psignal(3b)} explicitly warns that one should 12522a6b7db3Sskrllcheck the size of the table (@code{NSIG}) before indexing it, since 12532a6b7db3Sskrllnew signal codes may be added to the system before they are added to 12542a6b7db3Sskrllthe table. Thus @code{NSIG} might be smaller than value implied by 12552a6b7db3Sskrllthe largest signo value defined in @code{<signal.h>}. 12562a6b7db3Sskrll 12572a6b7db3SskrllWe return the maximum value that can be used to obtain a meaningful 12582a6b7db3Sskrllsymbolic name or message. 12592a6b7db3Sskrll 12602a6b7db3Sskrll@end deftypefn 12612a6b7db3Sskrll 12622a6b7db3Sskrll@c sigsetmask.c:8 12632a6b7db3Sskrll@deftypefn Supplemental int sigsetmask (int @var{set}) 12642a6b7db3Sskrll 12652a6b7db3SskrllSets the signal mask to the one provided in @var{set} and returns 12662a6b7db3Sskrllthe old mask (which, for libiberty's implementation, will always 12672a6b7db3Sskrllbe the value @code{1}). 12682a6b7db3Sskrll 12692a6b7db3Sskrll@end deftypefn 12702a6b7db3Sskrll 127105caefcfSchristos@c simple-object.txh:96 127205caefcfSchristos@deftypefn Extension {const char *} simple_object_attributes_compare @ 127305caefcfSchristos (simple_object_attributes *@var{attrs1}, simple_object_attributes *@var{attrs2}, @ 127405caefcfSchristos int *@var{err}) 1275b3ac4aedSchristos 1276b3ac4aedSchristosCompare @var{attrs1} and @var{attrs2}. If they could be linked 1277b3ac4aedSchristostogether without error, return @code{NULL}. Otherwise, return an 1278b3ac4aedSchristoserror message and set @code{*@var{err}} to an errno value or @code{0} 1279b3ac4aedSchristosif there is no relevant errno. 1280b3ac4aedSchristos 1281b3ac4aedSchristos@end deftypefn 1282b3ac4aedSchristos 128305caefcfSchristos@c simple-object.txh:81 128405caefcfSchristos@deftypefn Extension {simple_object_attributes *} simple_object_fetch_attributes @ 128505caefcfSchristos (simple_object_read *@var{simple_object}, const char **@var{errmsg}, int *@var{err}) 1286b3ac4aedSchristos 1287b3ac4aedSchristosFetch the attributes of @var{simple_object}. The attributes are 1288b3ac4aedSchristosinternal information such as the format of the object file, or the 1289b3ac4aedSchristosarchitecture it was compiled for. This information will persist until 1290b3ac4aedSchristos@code{simple_object_attributes_release} is called, even if 1291b3ac4aedSchristos@var{simple_object} itself is released. 1292b3ac4aedSchristos 1293b3ac4aedSchristosOn error this returns @code{NULL}, sets @code{*@var{errmsg}} to an 1294b3ac4aedSchristoserror message, and sets @code{*@var{err}} to an errno value or 1295b3ac4aedSchristos@code{0} if there is no relevant errno. 1296b3ac4aedSchristos 1297b3ac4aedSchristos@end deftypefn 1298b3ac4aedSchristos 129905caefcfSchristos@c simple-object.txh:49 130005caefcfSchristos@deftypefn Extension {int} simple_object_find_section @ 130105caefcfSchristos (simple_object_read *@var{simple_object} off_t *@var{offset}, @ 130205caefcfSchristos off_t *@var{length}, const char **@var{errmsg}, int *@var{err}) 1303b3ac4aedSchristos 1304b3ac4aedSchristosLook for the section @var{name} in @var{simple_object}. This returns 1305b3ac4aedSchristosinformation for the first section with that name. 1306b3ac4aedSchristos 1307b3ac4aedSchristosIf found, return 1 and set @code{*@var{offset}} to the offset in the 1308b3ac4aedSchristosfile of the section contents and set @code{*@var{length}} to the 1309b3ac4aedSchristoslength of the section contents. The value in @code{*@var{offset}} 1310b3ac4aedSchristoswill be relative to the offset passed to 1311b3ac4aedSchristos@code{simple_object_open_read}. 1312b3ac4aedSchristos 1313b3ac4aedSchristosIf the section is not found, and no error occurs, 1314b3ac4aedSchristos@code{simple_object_find_section} returns @code{0} and set 1315b3ac4aedSchristos@code{*@var{errmsg}} to @code{NULL}. 1316b3ac4aedSchristos 1317b3ac4aedSchristosIf an error occurs, @code{simple_object_find_section} returns 1318b3ac4aedSchristos@code{0}, sets @code{*@var{errmsg}} to an error message, and sets 1319b3ac4aedSchristos@code{*@var{err}} to an errno value or @code{0} if there is no 1320b3ac4aedSchristosrelevant errno. 1321b3ac4aedSchristos 1322b3ac4aedSchristos@end deftypefn 1323b3ac4aedSchristos 132405caefcfSchristos@c simple-object.txh:27 132505caefcfSchristos@deftypefn Extension {const char *} simple_object_find_sections @ 132605caefcfSchristos (simple_object_read *@var{simple_object}, int (*@var{pfn}) (void *@var{data}, @ 132705caefcfSchristos const char *@var{name}, off_t @var{offset}, off_t @var{length}), @ 132805caefcfSchristos void *@var{data}, int *@var{err}) 1329b3ac4aedSchristos 1330b3ac4aedSchristosThis function calls @var{pfn} for each section in @var{simple_object}. 1331b3ac4aedSchristosIt calls @var{pfn} with the section name, the offset within the file 1332b3ac4aedSchristosof the section contents, and the length of the section contents. The 1333b3ac4aedSchristosoffset within the file is relative to the offset passed to 1334b3ac4aedSchristos@code{simple_object_open_read}. The @var{data} argument to this 1335b3ac4aedSchristosfunction is passed along to @var{pfn}. 1336b3ac4aedSchristos 1337b3ac4aedSchristosIf @var{pfn} returns @code{0}, the loop over the sections stops and 1338b3ac4aedSchristos@code{simple_object_find_sections} returns. If @var{pfn} returns some 1339b3ac4aedSchristosother value, the loop continues. 1340b3ac4aedSchristos 1341b3ac4aedSchristosOn success @code{simple_object_find_sections} returns. On error it 1342b3ac4aedSchristosreturns an error string, and sets @code{*@var{err}} to an errno value 1343b3ac4aedSchristosor @code{0} if there is no relevant errno. 1344b3ac4aedSchristos 1345b3ac4aedSchristos@end deftypefn 1346b3ac4aedSchristos 1347b3ac4aedSchristos@c simple-object.txh:2 134805caefcfSchristos@deftypefn Extension {simple_object_read *} simple_object_open_read @ 134905caefcfSchristos (int @var{descriptor}, off_t @var{offset}, const char *{segment_name}, @ 135005caefcfSchristos const char **@var{errmsg}, int *@var{err}) 1351b3ac4aedSchristos 1352b3ac4aedSchristosOpens an object file for reading. Creates and returns an 1353b3ac4aedSchristos@code{simple_object_read} pointer which may be passed to other 1354b3ac4aedSchristosfunctions to extract data from the object file. 1355b3ac4aedSchristos 1356b3ac4aedSchristos@var{descriptor} holds a file descriptor which permits reading. 1357b3ac4aedSchristos 1358b3ac4aedSchristos@var{offset} is the offset into the file; this will be @code{0} in the 1359b3ac4aedSchristosnormal case, but may be a different value when reading an object file 1360b3ac4aedSchristosin an archive file. 1361b3ac4aedSchristos 1362b3ac4aedSchristos@var{segment_name} is only used with the Mach-O file format used on 1363b3ac4aedSchristosDarwin aka Mac OS X. It is required on that platform, and means to 1364b3ac4aedSchristosonly look at sections within the segment with that name. The 1365b3ac4aedSchristosparameter is ignored on other systems. 1366b3ac4aedSchristos 1367b3ac4aedSchristosIf an error occurs, this functions returns @code{NULL} and sets 1368b3ac4aedSchristos@code{*@var{errmsg}} to an error string and sets @code{*@var{err}} to 1369b3ac4aedSchristosan errno value or @code{0} if there is no relevant errno. 1370b3ac4aedSchristos 1371b3ac4aedSchristos@end deftypefn 1372b3ac4aedSchristos 137305caefcfSchristos@c simple-object.txh:107 137405caefcfSchristos@deftypefn Extension {void} simple_object_release_attributes @ 137505caefcfSchristos (simple_object_attributes *@var{attrs}) 1376b3ac4aedSchristos 1377b3ac4aedSchristosRelease all resources associated with @var{attrs}. 1378b3ac4aedSchristos 1379b3ac4aedSchristos@end deftypefn 1380b3ac4aedSchristos 138105caefcfSchristos@c simple-object.txh:73 138205caefcfSchristos@deftypefn Extension {void} simple_object_release_read @ 138305caefcfSchristos (simple_object_read *@var{simple_object}) 1384b3ac4aedSchristos 1385b3ac4aedSchristosRelease all resources associated with @var{simple_object}. This does 1386b3ac4aedSchristosnot close the file descriptor. 1387b3ac4aedSchristos 1388b3ac4aedSchristos@end deftypefn 1389b3ac4aedSchristos 139005caefcfSchristos@c simple-object.txh:184 139105caefcfSchristos@deftypefn Extension {void} simple_object_release_write @ 139205caefcfSchristos (simple_object_write *@var{simple_object}) 1393b3ac4aedSchristos 1394b3ac4aedSchristosRelease all resources associated with @var{simple_object}. 1395b3ac4aedSchristos 1396b3ac4aedSchristos@end deftypefn 1397b3ac4aedSchristos 139805caefcfSchristos@c simple-object.txh:114 139905caefcfSchristos@deftypefn Extension {simple_object_write *} simple_object_start_write @ 140005caefcfSchristos (simple_object_attributes @var{attrs}, const char *@var{segment_name}, @ 140105caefcfSchristos const char **@var{errmsg}, int *@var{err}) 1402b3ac4aedSchristos 1403b3ac4aedSchristosStart creating a new object file using the object file format 1404b3ac4aedSchristosdescribed in @var{attrs}. You must fetch attribute information from 1405b3ac4aedSchristosan existing object file before you can create a new one. There is 1406b3ac4aedSchristoscurrently no support for creating an object file de novo. 1407b3ac4aedSchristos 1408b3ac4aedSchristos@var{segment_name} is only used with Mach-O as found on Darwin aka Mac 1409b3ac4aedSchristosOS X. The parameter is required on that target. It means that all 1410b3ac4aedSchristossections are created within the named segment. It is ignored for 1411b3ac4aedSchristosother object file formats. 1412b3ac4aedSchristos 1413b3ac4aedSchristosOn error @code{simple_object_start_write} returns @code{NULL}, sets 1414b3ac4aedSchristos@code{*@var{ERRMSG}} to an error message, and sets @code{*@var{err}} 1415b3ac4aedSchristosto an errno value or @code{0} if there is no relevant errno. 1416b3ac4aedSchristos 1417b3ac4aedSchristos@end deftypefn 1418b3ac4aedSchristos 141905caefcfSchristos@c simple-object.txh:153 142005caefcfSchristos@deftypefn Extension {const char *} simple_object_write_add_data @ 142105caefcfSchristos (simple_object_write *@var{simple_object}, @ 142205caefcfSchristos simple_object_write_section *@var{section}, const void *@var{buffer}, @ 142305caefcfSchristos size_t @var{size}, int @var{copy}, int *@var{err}) 1424b3ac4aedSchristos 1425b3ac4aedSchristosAdd data @var{buffer}/@var{size} to @var{section} in 1426b3ac4aedSchristos@var{simple_object}. If @var{copy} is non-zero, the data will be 1427b3ac4aedSchristoscopied into memory if necessary. If @var{copy} is zero, @var{buffer} 1428b3ac4aedSchristosmust persist until @code{simple_object_write_to_file} is called. is 1429b3ac4aedSchristosreleased. 1430b3ac4aedSchristos 1431b3ac4aedSchristosOn success this returns @code{NULL}. On error this returns an error 1432b3ac4aedSchristosmessage, and sets @code{*@var{err}} to an errno value or 0 if there is 1433b3ac4aedSchristosno relevant erro. 1434b3ac4aedSchristos 1435b3ac4aedSchristos@end deftypefn 1436b3ac4aedSchristos 143705caefcfSchristos@c simple-object.txh:134 143805caefcfSchristos@deftypefn Extension {simple_object_write_section *} simple_object_write_create_section @ 143905caefcfSchristos (simple_object_write *@var{simple_object}, const char *@var{name}, @ 144005caefcfSchristos unsigned int @var{align}, const char **@var{errmsg}, int *@var{err}) 1441b3ac4aedSchristos 1442b3ac4aedSchristosAdd a section to @var{simple_object}. @var{name} is the name of the 1443b3ac4aedSchristosnew section. @var{align} is the required alignment expressed as the 1444b3ac4aedSchristosnumber of required low-order 0 bits (e.g., 2 for alignment to a 32-bit 1445b3ac4aedSchristosboundary). 1446b3ac4aedSchristos 1447b3ac4aedSchristosThe section is created as containing data, readable, not writable, not 1448b3ac4aedSchristosexecutable, not loaded at runtime. The section is not written to the 1449b3ac4aedSchristosfile until @code{simple_object_write_to_file} is called. 1450b3ac4aedSchristos 1451b3ac4aedSchristosOn error this returns @code{NULL}, sets @code{*@var{errmsg}} to an 1452b3ac4aedSchristoserror message, and sets @code{*@var{err}} to an errno value or 1453b3ac4aedSchristos@code{0} if there is no relevant errno. 1454b3ac4aedSchristos 1455b3ac4aedSchristos@end deftypefn 1456b3ac4aedSchristos 145705caefcfSchristos@c simple-object.txh:170 145805caefcfSchristos@deftypefn Extension {const char *} simple_object_write_to_file @ 145905caefcfSchristos (simple_object_write *@var{simple_object}, int @var{descriptor}, int *@var{err}) 1460b3ac4aedSchristos 1461b3ac4aedSchristosWrite the complete object file to @var{descriptor}, an open file 1462b3ac4aedSchristosdescriptor. This writes out all the data accumulated by calls to 1463b3ac4aedSchristos@code{simple_object_write_create_section} and 1464b3ac4aedSchristos@var{simple_object_write_add_data}. 1465b3ac4aedSchristos 1466b3ac4aedSchristosThis returns @code{NULL} on success. On error this returns an error 1467b3ac4aedSchristosmessage and sets @code{*@var{err}} to an errno value or @code{0} if 1468b3ac4aedSchristosthere is no relevant errno. 1469b3ac4aedSchristos 1470b3ac4aedSchristos@end deftypefn 1471b3ac4aedSchristos 14722a6b7db3Sskrll@c snprintf.c:28 147305caefcfSchristos@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, @ 147405caefcfSchristos const char *@var{format}, ...) 14752a6b7db3Sskrll 1476b3ac4aedSchristosThis function is similar to @code{sprintf}, but it will write to 1477b3ac4aedSchristos@var{buf} at most @code{@var{n}-1} bytes of text, followed by a 1478b3ac4aedSchristosterminating null byte, for a total of @var{n} bytes. 1479b3ac4aedSchristosOn error the return value is -1, otherwise it returns the number of 1480b3ac4aedSchristosbytes, not including the terminating null byte, that would have been 1481b3ac4aedSchristoswritten had @var{n} been sufficiently large, regardless of the actual 1482b3ac4aedSchristosvalue of @var{n}. Note some pre-C99 system libraries do not implement 1483b3ac4aedSchristosthis correctly so users cannot generally rely on the return value if 1484b3ac4aedSchristosthe system version of this function is used. 14852a6b7db3Sskrll 14862a6b7db3Sskrll@end deftypefn 14872a6b7db3Sskrll 14882a6b7db3Sskrll@c spaces.c:22 14892a6b7db3Sskrll@deftypefn Extension char* spaces (int @var{count}) 14902a6b7db3Sskrll 14912a6b7db3SskrllReturns a pointer to a memory region filled with the specified 14922a6b7db3Sskrllnumber of spaces and null terminated. The returned pointer is 14932a6b7db3Sskrllvalid until at least the next call. 14942a6b7db3Sskrll 14952a6b7db3Sskrll@end deftypefn 14962a6b7db3Sskrll 1497f7172901Schristos@c splay-tree.c:305 149805caefcfSchristos@deftypefn Supplemental splay_tree splay_tree_new_with_typed_alloc @ 149905caefcfSchristos(splay_tree_compare_fn @var{compare_fn}, @ 150005caefcfSchristossplay_tree_delete_key_fn @var{delete_key_fn}, @ 150105caefcfSchristossplay_tree_delete_value_fn @var{delete_value_fn}, @ 150205caefcfSchristossplay_tree_allocate_fn @var{tree_allocate_fn}, @ 150305caefcfSchristossplay_tree_allocate_fn @var{node_allocate_fn}, @ 150405caefcfSchristossplay_tree_deallocate_fn @var{deallocate_fn}, @ 150505caefcfSchristosvoid * @var{allocate_data}) 150605caefcfSchristos 150705caefcfSchristosThis function creates a splay tree that uses two different allocators 150805caefcfSchristos@var{tree_allocate_fn} and @var{node_allocate_fn} to use for allocating the 150905caefcfSchristostree itself and its nodes respectively. This is useful when variables of 151005caefcfSchristosdifferent types need to be allocated with different allocators. 151105caefcfSchristos 151205caefcfSchristosThe splay tree will use @var{compare_fn} to compare nodes, 151305caefcfSchristos@var{delete_key_fn} to deallocate keys, and @var{delete_value_fn} to 1514f7172901Schristosdeallocate values. Keys and values will be deallocated when the 1515f7172901Schristostree is deleted using splay_tree_delete or when a node is removed 1516f7172901Schristosusing splay_tree_remove. splay_tree_insert will release the previously 1517f7172901Schristosinserted key and value using @var{delete_key_fn} and @var{delete_value_fn} 1518f7172901Schristosif the inserted key is already found in the tree. 151905caefcfSchristos 152005caefcfSchristos@end deftypefn 152105caefcfSchristos 15225ba6b03cSchristos@c stack-limit.c:28 15235ba6b03cSchristos@deftypefn Extension void stack_limit_increase (unsigned long @var{pref}) 15245ba6b03cSchristos 15255ba6b03cSchristosAttempt to increase stack size limit to @var{pref} bytes if possible. 15265ba6b03cSchristos 15275ba6b03cSchristos@end deftypefn 15285ba6b03cSchristos 15292a6b7db3Sskrll@c stpcpy.c:23 15302a6b7db3Sskrll@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src}) 15312a6b7db3Sskrll 15322a6b7db3SskrllCopies the string @var{src} into @var{dst}. Returns a pointer to 15332a6b7db3Sskrll@var{dst} + strlen(@var{src}). 15342a6b7db3Sskrll 15352a6b7db3Sskrll@end deftypefn 15362a6b7db3Sskrll 15372a6b7db3Sskrll@c stpncpy.c:23 153805caefcfSchristos@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, @ 153905caefcfSchristos size_t @var{len}) 15402a6b7db3Sskrll 15412a6b7db3SskrllCopies the string @var{src} into @var{dst}, copying exactly @var{len} 15422a6b7db3Sskrlland padding with zeros if necessary. If @var{len} < strlen(@var{src}) 15432a6b7db3Sskrllthen return @var{dst} + @var{len}, otherwise returns @var{dst} + 15442a6b7db3Sskrllstrlen(@var{src}). 15452a6b7db3Sskrll 15462a6b7db3Sskrll@end deftypefn 15472a6b7db3Sskrll 15482a6b7db3Sskrll@c strcasecmp.c:15 15492a6b7db3Sskrll@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2}) 15502a6b7db3Sskrll 15512a6b7db3SskrllA case-insensitive @code{strcmp}. 15522a6b7db3Sskrll 15532a6b7db3Sskrll@end deftypefn 15542a6b7db3Sskrll 15552a6b7db3Sskrll@c strchr.c:6 15562a6b7db3Sskrll@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c}) 15572a6b7db3Sskrll 15582a6b7db3SskrllReturns a pointer to the first occurrence of the character @var{c} in 15592a6b7db3Sskrllthe string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 15602a6b7db3Sskrllnull character, the results are undefined. 15612a6b7db3Sskrll 15622a6b7db3Sskrll@end deftypefn 15632a6b7db3Sskrll 15642a6b7db3Sskrll@c strdup.c:3 15652a6b7db3Sskrll@deftypefn Supplemental char* strdup (const char *@var{s}) 15662a6b7db3Sskrll 15672a6b7db3SskrllReturns a pointer to a copy of @var{s} in memory obtained from 15682a6b7db3Sskrll@code{malloc}, or @code{NULL} if insufficient memory was available. 15692a6b7db3Sskrll 15702a6b7db3Sskrll@end deftypefn 15712a6b7db3Sskrll 1572f7172901Schristos@c strerror.c:675 15732a6b7db3Sskrll@deftypefn Replacement {const char*} strerrno (int @var{errnum}) 15742a6b7db3Sskrll 15752a6b7db3SskrllGiven an error number returned from a system call (typically returned 15762a6b7db3Sskrllin @code{errno}), returns a pointer to a string containing the 15772a6b7db3Sskrllsymbolic name of that error number, as found in @code{<errno.h>}. 15782a6b7db3Sskrll 15792a6b7db3SskrllIf the supplied error number is within the valid range of indices for 15802a6b7db3Sskrllsymbolic names, but no name is available for the particular error 15812a6b7db3Sskrllnumber, then returns the string @samp{Error @var{num}}, where @var{num} 15822a6b7db3Sskrllis the error number. 15832a6b7db3Sskrll 15842a6b7db3SskrllIf the supplied error number is not within the range of valid 15852a6b7db3Sskrllindices, then returns @code{NULL}. 15862a6b7db3Sskrll 15872a6b7db3SskrllThe contents of the location pointed to are only guaranteed to be 15882a6b7db3Sskrllvalid until the next call to @code{strerrno}. 15892a6b7db3Sskrll 15902a6b7db3Sskrll@end deftypefn 15912a6b7db3Sskrll 1592f7172901Schristos@c strerror.c:608 15932a6b7db3Sskrll@deftypefn Supplemental char* strerror (int @var{errnoval}) 15942a6b7db3Sskrll 15952a6b7db3SskrllMaps an @code{errno} number to an error message string, the contents 15962a6b7db3Sskrllof which are implementation defined. On systems which have the 15972a6b7db3Sskrllexternal variables @code{sys_nerr} and @code{sys_errlist}, these 15982a6b7db3Sskrllstrings will be the same as the ones used by @code{perror}. 15992a6b7db3Sskrll 16002a6b7db3SskrllIf the supplied error number is within the valid range of indices for 16012a6b7db3Sskrllthe @code{sys_errlist}, but no message is available for the particular 16022a6b7db3Sskrllerror number, then returns the string @samp{Error @var{num}}, where 16032a6b7db3Sskrll@var{num} is the error number. 16042a6b7db3Sskrll 16052a6b7db3SskrllIf the supplied error number is not a valid index into 16062a6b7db3Sskrll@code{sys_errlist}, returns @code{NULL}. 16072a6b7db3Sskrll 16082a6b7db3SskrllThe returned string is only guaranteed to be valid only until the 16092a6b7db3Sskrllnext call to @code{strerror}. 16102a6b7db3Sskrll 16112a6b7db3Sskrll@end deftypefn 16122a6b7db3Sskrll 16132a6b7db3Sskrll@c strncasecmp.c:15 16142a6b7db3Sskrll@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2}) 16152a6b7db3Sskrll 16162a6b7db3SskrllA case-insensitive @code{strncmp}. 16172a6b7db3Sskrll 16182a6b7db3Sskrll@end deftypefn 16192a6b7db3Sskrll 16202a6b7db3Sskrll@c strncmp.c:6 162105caefcfSchristos@deftypefn Supplemental int strncmp (const char *@var{s1}, @ 162205caefcfSchristos const char *@var{s2}, size_t @var{n}) 16232a6b7db3Sskrll 16242a6b7db3SskrllCompares the first @var{n} bytes of two strings, returning a value as 16252a6b7db3Sskrll@code{strcmp}. 16262a6b7db3Sskrll 16272a6b7db3Sskrll@end deftypefn 16282a6b7db3Sskrll 16292a6b7db3Sskrll@c strndup.c:23 16302a6b7db3Sskrll@deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n}) 16312a6b7db3Sskrll 16322a6b7db3SskrllReturns a pointer to a copy of @var{s} with at most @var{n} characters 16332a6b7db3Sskrllin memory obtained from @code{malloc}, or @code{NULL} if insufficient 16342a6b7db3Sskrllmemory was available. The result is always NUL terminated. 16352a6b7db3Sskrll 16362a6b7db3Sskrll@end deftypefn 16372a6b7db3Sskrll 16385ba6b03cSchristos@c strnlen.c:6 16395ba6b03cSchristos@deftypefn Supplemental size_t strnlen (const char *@var{s}, size_t @var{maxlen}) 16405ba6b03cSchristos 16415ba6b03cSchristosReturns the length of @var{s}, as with @code{strlen}, but never looks 16425ba6b03cSchristospast the first @var{maxlen} characters in the string. If there is no 16435ba6b03cSchristos'\0' character in the first @var{maxlen} characters, returns 16445ba6b03cSchristos@var{maxlen}. 16455ba6b03cSchristos 16465ba6b03cSchristos@end deftypefn 16475ba6b03cSchristos 16482a6b7db3Sskrll@c strrchr.c:6 16492a6b7db3Sskrll@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c}) 16502a6b7db3Sskrll 16512a6b7db3SskrllReturns a pointer to the last occurrence of the character @var{c} in 16522a6b7db3Sskrllthe string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 16532a6b7db3Sskrllnull character, the results are undefined. 16542a6b7db3Sskrll 16552a6b7db3Sskrll@end deftypefn 16562a6b7db3Sskrll 16572a6b7db3Sskrll@c strsignal.c:383 16582a6b7db3Sskrll@deftypefn Supplemental {const char *} strsignal (int @var{signo}) 16592a6b7db3Sskrll 16602a6b7db3SskrllMaps an signal number to an signal message string, the contents of 16612a6b7db3Sskrllwhich are implementation defined. On systems which have the external 16622a6b7db3Sskrllvariable @code{sys_siglist}, these strings will be the same as the 16632a6b7db3Sskrllones used by @code{psignal()}. 16642a6b7db3Sskrll 16652a6b7db3SskrllIf the supplied signal number is within the valid range of indices for 16662a6b7db3Sskrllthe @code{sys_siglist}, but no message is available for the particular 16672a6b7db3Sskrllsignal number, then returns the string @samp{Signal @var{num}}, where 16682a6b7db3Sskrll@var{num} is the signal number. 16692a6b7db3Sskrll 16702a6b7db3SskrllIf the supplied signal number is not a valid index into 16712a6b7db3Sskrll@code{sys_siglist}, returns @code{NULL}. 16722a6b7db3Sskrll 16732a6b7db3SskrllThe returned string is only guaranteed to be valid only until the next 16742a6b7db3Sskrllcall to @code{strsignal}. 16752a6b7db3Sskrll 16762a6b7db3Sskrll@end deftypefn 16772a6b7db3Sskrll 16782a6b7db3Sskrll@c strsignal.c:448 16792a6b7db3Sskrll@deftypefn Extension {const char*} strsigno (int @var{signo}) 16802a6b7db3Sskrll 16812a6b7db3SskrllGiven an signal number, returns a pointer to a string containing the 16822a6b7db3Sskrllsymbolic name of that signal number, as found in @code{<signal.h>}. 16832a6b7db3Sskrll 16842a6b7db3SskrllIf the supplied signal number is within the valid range of indices for 16852a6b7db3Sskrllsymbolic names, but no name is available for the particular signal 16862a6b7db3Sskrllnumber, then returns the string @samp{Signal @var{num}}, where 16872a6b7db3Sskrll@var{num} is the signal number. 16882a6b7db3Sskrll 16892a6b7db3SskrllIf the supplied signal number is not within the range of valid 16902a6b7db3Sskrllindices, then returns @code{NULL}. 16912a6b7db3Sskrll 16922a6b7db3SskrllThe contents of the location pointed to are only guaranteed to be 16932a6b7db3Sskrllvalid until the next call to @code{strsigno}. 16942a6b7db3Sskrll 16952a6b7db3Sskrll@end deftypefn 16962a6b7db3Sskrll 16972a6b7db3Sskrll@c strstr.c:6 16982a6b7db3Sskrll@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub}) 16992a6b7db3Sskrll 17002a6b7db3SskrllThis function searches for the substring @var{sub} in the string 17012a6b7db3Sskrll@var{string}, not including the terminating null characters. A pointer 17022a6b7db3Sskrllto the first occurrence of @var{sub} is returned, or @code{NULL} if the 17032a6b7db3Sskrllsubstring is absent. If @var{sub} points to a string with zero 17042a6b7db3Sskrlllength, the function returns @var{string}. 17052a6b7db3Sskrll 17062a6b7db3Sskrll@end deftypefn 17072a6b7db3Sskrll 17082a6b7db3Sskrll@c strtod.c:27 170905caefcfSchristos@deftypefn Supplemental double strtod (const char *@var{string}, @ 171005caefcfSchristos char **@var{endptr}) 17112a6b7db3Sskrll 17122a6b7db3SskrllThis ISO C function converts the initial portion of @var{string} to a 17132a6b7db3Sskrll@code{double}. If @var{endptr} is not @code{NULL}, a pointer to the 17142a6b7db3Sskrllcharacter after the last character used in the conversion is stored in 17152a6b7db3Sskrllthe location referenced by @var{endptr}. If no conversion is 17162a6b7db3Sskrllperformed, zero is returned and the value of @var{string} is stored in 17172a6b7db3Sskrllthe location referenced by @var{endptr}. 17182a6b7db3Sskrll 17192a6b7db3Sskrll@end deftypefn 17202a6b7db3Sskrll 1721f7172901Schristos@c strerror.c:734 17222a6b7db3Sskrll@deftypefn Extension int strtoerrno (const char *@var{name}) 17232a6b7db3Sskrll 17242a6b7db3SskrllGiven the symbolic name of a error number (e.g., @code{EACCES}), map it 17252a6b7db3Sskrllto an errno value. If no translation is found, returns 0. 17262a6b7db3Sskrll 17272a6b7db3Sskrll@end deftypefn 17282a6b7db3Sskrll 17292a6b7db3Sskrll@c strtol.c:33 173005caefcfSchristos@deftypefn Supplemental {long int} strtol (const char *@var{string}, @ 173105caefcfSchristos char **@var{endptr}, int @var{base}) 173205caefcfSchristos@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, @ 173305caefcfSchristos char **@var{endptr}, int @var{base}) 17342a6b7db3Sskrll 17352a6b7db3SskrllThe @code{strtol} function converts the string in @var{string} to a 17362a6b7db3Sskrlllong integer value according to the given @var{base}, which must be 17372a6b7db3Sskrllbetween 2 and 36 inclusive, or be the special value 0. If @var{base} 17382a6b7db3Sskrllis 0, @code{strtol} will look for the prefixes @code{0} and @code{0x} 17392a6b7db3Sskrllto indicate bases 8 and 16, respectively, else default to base 10. 17402a6b7db3SskrllWhen the base is 16 (either explicitly or implicitly), a prefix of 17412a6b7db3Sskrll@code{0x} is allowed. The handling of @var{endptr} is as that of 17422a6b7db3Sskrll@code{strtod} above. The @code{strtoul} function is the same, except 17432a6b7db3Sskrllthat the converted value is unsigned. 17442a6b7db3Sskrll 17452a6b7db3Sskrll@end deftypefn 17462a6b7db3Sskrll 17475ba6b03cSchristos@c strtoll.c:33 17485ba6b03cSchristos@deftypefn Supplemental {long long int} strtoll (const char *@var{string}, @ 17495ba6b03cSchristos char **@var{endptr}, int @var{base}) 17505ba6b03cSchristos@deftypefnx Supplemental {unsigned long long int} strtoul (@ 17515ba6b03cSchristos const char *@var{string}, char **@var{endptr}, int @var{base}) 17525ba6b03cSchristos 17535ba6b03cSchristosThe @code{strtoll} function converts the string in @var{string} to a 17545ba6b03cSchristoslong long integer value according to the given @var{base}, which must be 17555ba6b03cSchristosbetween 2 and 36 inclusive, or be the special value 0. If @var{base} 17565ba6b03cSchristosis 0, @code{strtoll} will look for the prefixes @code{0} and @code{0x} 17575ba6b03cSchristosto indicate bases 8 and 16, respectively, else default to base 10. 17585ba6b03cSchristosWhen the base is 16 (either explicitly or implicitly), a prefix of 17595ba6b03cSchristos@code{0x} is allowed. The handling of @var{endptr} is as that of 17605ba6b03cSchristos@code{strtod} above. The @code{strtoull} function is the same, except 17615ba6b03cSchristosthat the converted value is unsigned. 17625ba6b03cSchristos 17635ba6b03cSchristos@end deftypefn 17645ba6b03cSchristos 17652a6b7db3Sskrll@c strsignal.c:502 17662a6b7db3Sskrll@deftypefn Extension int strtosigno (const char *@var{name}) 17672a6b7db3Sskrll 17682a6b7db3SskrllGiven the symbolic name of a signal, map it to a signal number. If no 17692a6b7db3Sskrlltranslation is found, returns 0. 17702a6b7db3Sskrll 17712a6b7db3Sskrll@end deftypefn 17722a6b7db3Sskrll 17732a6b7db3Sskrll@c strverscmp.c:25 17742a6b7db3Sskrll@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2}) 17752a6b7db3SskrllThe @code{strverscmp} function compares the string @var{s1} against 17762a6b7db3Sskrll@var{s2}, considering them as holding indices/version numbers. Return 17772a6b7db3Sskrllvalue follows the same conventions as found in the @code{strverscmp} 17782a6b7db3Sskrllfunction. In fact, if @var{s1} and @var{s2} contain no digits, 17792a6b7db3Sskrll@code{strverscmp} behaves like @code{strcmp}. 17802a6b7db3Sskrll 17812a6b7db3SskrllBasically, we compare strings normally (character by character), until 17822a6b7db3Sskrllwe find a digit in each string - then we enter a special comparison 17832a6b7db3Sskrllmode, where each sequence of digits is taken as a whole. If we reach the 17842a6b7db3Sskrllend of these two parts without noticing a difference, we return to the 17852a6b7db3Sskrllstandard comparison mode. There are two types of numeric parts: 17862a6b7db3Sskrll"integral" and "fractional" (those begin with a '0'). The types 17872a6b7db3Sskrllof the numeric parts affect the way we sort them: 17882a6b7db3Sskrll 17892a6b7db3Sskrll@itemize @bullet 17902a6b7db3Sskrll@item 17912a6b7db3Sskrllintegral/integral: we compare values as you would expect. 17922a6b7db3Sskrll 17932a6b7db3Sskrll@item 17942a6b7db3Sskrllfractional/integral: the fractional part is less than the integral one. 17952a6b7db3SskrllAgain, no surprise. 17962a6b7db3Sskrll 17972a6b7db3Sskrll@item 17982a6b7db3Sskrllfractional/fractional: the things become a bit more complex. 17992a6b7db3SskrllIf the common prefix contains only leading zeroes, the longest part is less 18002a6b7db3Sskrllthan the other one; else the comparison behaves normally. 18012a6b7db3Sskrll@end itemize 18022a6b7db3Sskrll 18032a6b7db3Sskrll@smallexample 18042a6b7db3Sskrllstrverscmp ("no digit", "no digit") 18052a6b7db3Sskrll @result{} 0 // @r{same behavior as strcmp.} 18062a6b7db3Sskrllstrverscmp ("item#99", "item#100") 18072a6b7db3Sskrll @result{} <0 // @r{same prefix, but 99 < 100.} 18082a6b7db3Sskrllstrverscmp ("alpha1", "alpha001") 18092a6b7db3Sskrll @result{} >0 // @r{fractional part inferior to integral one.} 18102a6b7db3Sskrllstrverscmp ("part1_f012", "part1_f01") 18112a6b7db3Sskrll @result{} >0 // @r{two fractional parts.} 18122a6b7db3Sskrllstrverscmp ("foo.009", "foo.0") 18132a6b7db3Sskrll @result{} <0 // @r{idem, but with leading zeroes only.} 18142a6b7db3Sskrll@end smallexample 18152a6b7db3Sskrll 18162a6b7db3SskrllThis function is especially useful when dealing with filename sorting, 18172a6b7db3Sskrllbecause filenames frequently hold indices/version numbers. 18182a6b7db3Sskrll@end deftypefun 18192a6b7db3Sskrll 18205ba6b03cSchristos@c timeval-utils.c:43 18215ba6b03cSchristos@deftypefn Extension void timeval_add (struct timeval *@var{a}, @ 18225ba6b03cSchristos struct timeval *@var{b}, struct timeval *@var{result}) 18235ba6b03cSchristos 18245ba6b03cSchristosAdds @var{a} to @var{b} and stores the result in @var{result}. 18255ba6b03cSchristos 18265ba6b03cSchristos@end deftypefn 18275ba6b03cSchristos 18285ba6b03cSchristos@c timeval-utils.c:67 18295ba6b03cSchristos@deftypefn Extension void timeval_sub (struct timeval *@var{a}, @ 18305ba6b03cSchristos struct timeval *@var{b}, struct timeval *@var{result}) 18315ba6b03cSchristos 18325ba6b03cSchristosSubtracts @var{b} from @var{a} and stores the result in @var{result}. 18335ba6b03cSchristos 18345ba6b03cSchristos@end deftypefn 18355ba6b03cSchristos 18362a6b7db3Sskrll@c tmpnam.c:3 18372a6b7db3Sskrll@deftypefn Supplemental char* tmpnam (char *@var{s}) 18382a6b7db3Sskrll 18392a6b7db3SskrllThis function attempts to create a name for a temporary file, which 18402a6b7db3Sskrllwill be a valid file name yet not exist when @code{tmpnam} checks for 18412a6b7db3Sskrllit. @var{s} must point to a buffer of at least @code{L_tmpnam} bytes, 18422a6b7db3Sskrllor be @code{NULL}. Use of this function creates a security risk, and it must 18432a6b7db3Sskrllnot be used in new projects. Use @code{mkstemp} instead. 18442a6b7db3Sskrll 18452a6b7db3Sskrll@end deftypefn 18462a6b7db3Sskrll 18472a6b7db3Sskrll@c unlink-if-ordinary.c:27 18482a6b7db3Sskrll@deftypefn Supplemental int unlink_if_ordinary (const char*) 18492a6b7db3Sskrll 18502a6b7db3SskrllUnlinks the named file, unless it is special (e.g. a device file). 18512a6b7db3SskrllReturns 0 when the file was unlinked, a negative value (and errno set) when 18522a6b7db3Sskrllthere was an error deleting the file, and a positive value if no attempt 18532a6b7db3Sskrllwas made to unlink the file because it is special. 18542a6b7db3Sskrll 18552a6b7db3Sskrll@end deftypefn 18562a6b7db3Sskrll 18572a6b7db3Sskrll@c fopen_unlocked.c:31 18582a6b7db3Sskrll@deftypefn Extension void unlock_std_streams (void) 18592a6b7db3Sskrll 18602a6b7db3SskrllIf the OS supports it, ensure that the standard I/O streams, 18612a6b7db3Sskrll@code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any 18622a6b7db3Sskrllmulti-threaded locking. Otherwise do nothing. 18632a6b7db3Sskrll 18642a6b7db3Sskrll@end deftypefn 18652a6b7db3Sskrll 18662a6b7db3Sskrll@c fopen_unlocked.c:23 18672a6b7db3Sskrll@deftypefn Extension void unlock_stream (FILE * @var{stream}) 18682a6b7db3Sskrll 18692a6b7db3SskrllIf the OS supports it, ensure that the supplied stream is setup to 18702a6b7db3Sskrllavoid any multi-threaded locking. Otherwise leave the @code{FILE} 18712a6b7db3Sskrllpointer unchanged. If the @var{stream} is @code{NULL} do nothing. 18722a6b7db3Sskrll 18732a6b7db3Sskrll@end deftypefn 18742a6b7db3Sskrll 18752a6b7db3Sskrll@c vasprintf.c:47 187605caefcfSchristos@deftypefn Extension int vasprintf (char **@var{resptr}, @ 187705caefcfSchristos const char *@var{format}, va_list @var{args}) 18782a6b7db3Sskrll 18792a6b7db3SskrllLike @code{vsprintf}, but instead of passing a pointer to a buffer, 18802a6b7db3Sskrllyou pass a pointer to a pointer. This function will compute the size 18812a6b7db3Sskrllof the buffer needed, allocate memory with @code{malloc}, and store a 18822a6b7db3Sskrllpointer to the allocated memory in @code{*@var{resptr}}. The value 18832a6b7db3Sskrllreturned is the same as @code{vsprintf} would return. If memory could 18842a6b7db3Sskrllnot be allocated, minus one is returned and @code{NULL} is stored in 18852a6b7db3Sskrll@code{*@var{resptr}}. 18862a6b7db3Sskrll 18872a6b7db3Sskrll@end deftypefn 18882a6b7db3Sskrll 18892a6b7db3Sskrll@c vfork.c:6 18902a6b7db3Sskrll@deftypefn Supplemental int vfork (void) 18912a6b7db3Sskrll 18922a6b7db3SskrllEmulates @code{vfork} by calling @code{fork} and returning its value. 18932a6b7db3Sskrll 18942a6b7db3Sskrll@end deftypefn 18952a6b7db3Sskrll 18962a6b7db3Sskrll@c vprintf.c:3 18972a6b7db3Sskrll@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap}) 189805caefcfSchristos@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, @ 189905caefcfSchristos const char *@var{format}, va_list @var{ap}) 190005caefcfSchristos@deftypefnx Supplemental int vsprintf (char *@var{str}, @ 190105caefcfSchristos const char *@var{format}, va_list @var{ap}) 19022a6b7db3Sskrll 19032a6b7db3SskrllThese functions are the same as @code{printf}, @code{fprintf}, and 19042a6b7db3Sskrll@code{sprintf}, respectively, except that they are called with a 19052a6b7db3Sskrll@code{va_list} instead of a variable number of arguments. Note that 19062a6b7db3Sskrllthey do not call @code{va_end}; this is the application's 19072a6b7db3Sskrllresponsibility. In @libib{} they are implemented in terms of the 19082a6b7db3Sskrllnonstandard but common function @code{_doprnt}. 19092a6b7db3Sskrll 19102a6b7db3Sskrll@end deftypefn 19112a6b7db3Sskrll 19122a6b7db3Sskrll@c vsnprintf.c:28 191305caefcfSchristos@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, @ 191405caefcfSchristos const char *@var{format}, va_list @var{ap}) 19152a6b7db3Sskrll 1916b3ac4aedSchristosThis function is similar to @code{vsprintf}, but it will write to 1917b3ac4aedSchristos@var{buf} at most @code{@var{n}-1} bytes of text, followed by a 1918b3ac4aedSchristosterminating null byte, for a total of @var{n} bytes. On error the 1919b3ac4aedSchristosreturn value is -1, otherwise it returns the number of characters that 1920b3ac4aedSchristoswould have been printed had @var{n} been sufficiently large, 1921b3ac4aedSchristosregardless of the actual value of @var{n}. Note some pre-C99 system 1922b3ac4aedSchristoslibraries do not implement this correctly so users cannot generally 1923b3ac4aedSchristosrely on the return value if the system version of this function is 1924b3ac4aedSchristosused. 19252a6b7db3Sskrll 19262a6b7db3Sskrll@end deftypefn 19272a6b7db3Sskrll 19282a6b7db3Sskrll@c waitpid.c:3 19292a6b7db3Sskrll@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int) 19302a6b7db3Sskrll 19312a6b7db3SskrllThis is a wrapper around the @code{wait} function. Any ``special'' 19322a6b7db3Sskrllvalues of @var{pid} depend on your implementation of @code{wait}, as 19332a6b7db3Sskrlldoes the return value. The third argument is unused in @libib{}. 19342a6b7db3Sskrll 19352a6b7db3Sskrll@end deftypefn 19362a6b7db3Sskrll 1937f7172901Schristos@c argv.c:289 193875f9f1baSchristos@deftypefn Extension int writeargv (char * const *@var{argv}, FILE *@var{file}) 19392a6b7db3Sskrll 19402a6b7db3SskrllWrite each member of ARGV, handling all necessary quoting, to the file 19412a6b7db3Sskrllnamed by FILE, separated by whitespace. Return 0 on success, non-zero 19422a6b7db3Sskrllif an error occurred while writing to FILE. 19432a6b7db3Sskrll 19442a6b7db3Sskrll@end deftypefn 19452a6b7db3Sskrll 19465ba6b03cSchristos@c xasprintf.c:31 19475ba6b03cSchristos@deftypefn Replacement char* xasprintf (const char *@var{format}, ...) 19485ba6b03cSchristos 19495ba6b03cSchristosPrint to allocated string without fail. If @code{xasprintf} fails, 19505ba6b03cSchristosthis will print a message to @code{stderr} (using the name set by 19515ba6b03cSchristos@code{xmalloc_set_program_name}, if any) and then call @code{xexit}. 19525ba6b03cSchristos 19535ba6b03cSchristos@end deftypefn 19545ba6b03cSchristos 19552a6b7db3Sskrll@c xatexit.c:11 19562a6b7db3Sskrll@deftypefun int xatexit (void (*@var{fn}) (void)) 19572a6b7db3Sskrll 19582a6b7db3SskrllBehaves as the standard @code{atexit} function, but with no limit on 19592a6b7db3Sskrllthe number of registered functions. Returns 0 on success, or @minus{}1 on 19602a6b7db3Sskrllfailure. If you use @code{xatexit} to register functions, you must use 19612a6b7db3Sskrll@code{xexit} to terminate your program. 19622a6b7db3Sskrll 19632a6b7db3Sskrll@end deftypefun 19642a6b7db3Sskrll 19652a6b7db3Sskrll@c xmalloc.c:38 19662a6b7db3Sskrll@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize}) 19672a6b7db3Sskrll 19682a6b7db3SskrllAllocate memory without fail, and set it to zero. This routine functions 19692a6b7db3Sskrlllike @code{calloc}, but will behave the same as @code{xmalloc} if memory 19702a6b7db3Sskrllcannot be found. 19712a6b7db3Sskrll 19722a6b7db3Sskrll@end deftypefn 19732a6b7db3Sskrll 19742a6b7db3Sskrll@c xexit.c:22 19752a6b7db3Sskrll@deftypefn Replacement void xexit (int @var{code}) 19762a6b7db3Sskrll 19772a6b7db3SskrllTerminates the program. If any functions have been registered with 19782a6b7db3Sskrllthe @code{xatexit} replacement function, they will be called first. 19792a6b7db3SskrllTermination is handled via the system's normal @code{exit} call. 19802a6b7db3Sskrll 19812a6b7db3Sskrll@end deftypefn 19822a6b7db3Sskrll 19832a6b7db3Sskrll@c xmalloc.c:22 19842a6b7db3Sskrll@deftypefn Replacement void* xmalloc (size_t) 19852a6b7db3Sskrll 19862a6b7db3SskrllAllocate memory without fail. If @code{malloc} fails, this will print 19872a6b7db3Sskrlla message to @code{stderr} (using the name set by 19882a6b7db3Sskrll@code{xmalloc_set_program_name}, 19892a6b7db3Sskrllif any) and then call @code{xexit}. Note that it is therefore safe for 19902a6b7db3Sskrlla program to contain @code{#define malloc xmalloc} in its source. 19912a6b7db3Sskrll 19922a6b7db3Sskrll@end deftypefn 19932a6b7db3Sskrll 19942a6b7db3Sskrll@c xmalloc.c:53 19952a6b7db3Sskrll@deftypefn Replacement void xmalloc_failed (size_t) 19962a6b7db3Sskrll 19972a6b7db3SskrllThis function is not meant to be called by client code, and is listed 19982a6b7db3Sskrllhere for completeness only. If any of the allocation routines fail, this 19992a6b7db3Sskrllfunction will be called to print an error message and terminate execution. 20002a6b7db3Sskrll 20012a6b7db3Sskrll@end deftypefn 20022a6b7db3Sskrll 20032a6b7db3Sskrll@c xmalloc.c:46 20042a6b7db3Sskrll@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name}) 20052a6b7db3Sskrll 20062a6b7db3SskrllYou can use this to set the name of the program used by 20072a6b7db3Sskrll@code{xmalloc_failed} when printing a failure message. 20082a6b7db3Sskrll 20092a6b7db3Sskrll@end deftypefn 20102a6b7db3Sskrll 20112a6b7db3Sskrll@c xmemdup.c:7 201205caefcfSchristos@deftypefn Replacement void* xmemdup (void *@var{input}, @ 201305caefcfSchristos size_t @var{copy_size}, size_t @var{alloc_size}) 20142a6b7db3Sskrll 20152a6b7db3SskrllDuplicates a region of memory without fail. First, @var{alloc_size} bytes 20162a6b7db3Sskrllare allocated, then @var{copy_size} bytes from @var{input} are copied into 20172a6b7db3Sskrllit, and the new memory is returned. If fewer bytes are copied than were 20182a6b7db3Sskrllallocated, the remaining memory is zeroed. 20192a6b7db3Sskrll 20202a6b7db3Sskrll@end deftypefn 20212a6b7db3Sskrll 20222a6b7db3Sskrll@c xmalloc.c:32 20232a6b7db3Sskrll@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size}) 20242a6b7db3SskrllReallocate memory without fail. This routine functions like @code{realloc}, 20252a6b7db3Sskrllbut will behave the same as @code{xmalloc} if memory cannot be found. 20262a6b7db3Sskrll 20272a6b7db3Sskrll@end deftypefn 20282a6b7db3Sskrll 20292a6b7db3Sskrll@c xstrdup.c:7 20302a6b7db3Sskrll@deftypefn Replacement char* xstrdup (const char *@var{s}) 20312a6b7db3Sskrll 20322a6b7db3SskrllDuplicates a character string without fail, using @code{xmalloc} to 20332a6b7db3Sskrllobtain memory. 20342a6b7db3Sskrll 20352a6b7db3Sskrll@end deftypefn 20362a6b7db3Sskrll 20372a6b7db3Sskrll@c xstrerror.c:7 20382a6b7db3Sskrll@deftypefn Replacement char* xstrerror (int @var{errnum}) 20392a6b7db3Sskrll 20402a6b7db3SskrllBehaves exactly like the standard @code{strerror} function, but 20412a6b7db3Sskrllwill never return a @code{NULL} pointer. 20422a6b7db3Sskrll 20432a6b7db3Sskrll@end deftypefn 20442a6b7db3Sskrll 20452a6b7db3Sskrll@c xstrndup.c:23 20462a6b7db3Sskrll@deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n}) 20472a6b7db3Sskrll 20482a6b7db3SskrllReturns a pointer to a copy of @var{s} with at most @var{n} characters 20492a6b7db3Sskrllwithout fail, using @code{xmalloc} to obtain memory. The result is 20502a6b7db3Sskrllalways NUL terminated. 20512a6b7db3Sskrll 20522a6b7db3Sskrll@end deftypefn 20532a6b7db3Sskrll 20545ba6b03cSchristos@c xvasprintf.c:38 20555ba6b03cSchristos@deftypefn Replacement char* xvasprintf (const char *@var{format}, va_list @var{args}) 20565ba6b03cSchristos 20575ba6b03cSchristosPrint to allocated string without fail. If @code{xvasprintf} fails, 20585ba6b03cSchristosthis will print a message to @code{stderr} (using the name set by 20595ba6b03cSchristos@code{xmalloc_set_program_name}, if any) and then call @code{xexit}. 20605ba6b03cSchristos 20615ba6b03cSchristos@end deftypefn 20625ba6b03cSchristos 20632a6b7db3Sskrll 2064