189857Sobrien@c Automatically generated from *.c and others (the comments before 289857Sobrien@c each entry tell you which file and where in that file). DO NOT EDIT! 389857Sobrien@c Edit the *.c files, configure with --enable-maintainer-mode, 489857Sobrien@c and let gather-docs build you a new copy. 589857Sobrien 6218822Sdim@c safe-ctype.c:25 7130561Sobrien@defvr Extension HOST_CHARSET 8130561SobrienThis macro indicates the basic character set and encoding used by the 9130561Sobrienhost: more precisely, the encoding used for character constants in 10130561Sobrienpreprocessor @samp{#if} statements (the C "execution character set"). 11130561SobrienIt is defined by @file{safe-ctype.h}, and will be an integer constant 12130561Sobrienwith one of the following values: 13130561Sobrien 14130561Sobrien@ftable @code 15130561Sobrien@item HOST_CHARSET_UNKNOWN 16130561SobrienThe host character set is unknown - that is, not one of the next two 17130561Sobrienpossibilities. 18130561Sobrien 19130561Sobrien@item HOST_CHARSET_ASCII 20130561SobrienThe host character set is ASCII. 21130561Sobrien 22130561Sobrien@item HOST_CHARSET_EBCDIC 23130561SobrienThe host character set is some variant of EBCDIC. (Only one of the 24130561Sobriennineteen EBCDIC varying characters is tested; exercise caution.) 25130561Sobrien@end ftable 26130561Sobrien@end defvr 27130561Sobrien 2889857Sobrien@c alloca.c:26 2989857Sobrien@deftypefn Replacement void* alloca (size_t @var{size}) 3089857Sobrien 3189857SobrienThis function allocates memory which will be automatically reclaimed 3289857Sobrienafter the procedure exits. The @libib{} implementation does not free 3389857Sobrienthe memory immediately but will do so eventually during subsequent 3489857Sobriencalls to this function. Memory is allocated using @code{xmalloc} under 3589857Sobriennormal circumstances. 3689857Sobrien 3789857SobrienThe header file @file{alloca-conf.h} can be used in conjunction with the 3889857SobrienGNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make 3989857Sobrienavailable this function. The @code{AC_FUNC_ALLOCA} test requires that 4089857Sobrienclient code use a block of preprocessor code to be safe (see the Autoconf 4189857Sobrienmanual for more); this header incorporates that logic and more, including 4289857Sobrienthe possibility of a GCC built-in function. 4389857Sobrien 4489857Sobrien@end deftypefn 4589857Sobrien 46218822Sdim@c asprintf.c:32 4789857Sobrien@deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...) 4889857Sobrien 4989857SobrienLike @code{sprintf}, but instead of passing a pointer to a buffer, you 5089857Sobrienpass a pointer to a pointer. This function will compute the size of 5189857Sobrienthe buffer needed, allocate memory with @code{malloc}, and store a 5289857Sobrienpointer to the allocated memory in @code{*@var{resptr}}. The value 5389857Sobrienreturned is the same as @code{sprintf} would return. If memory could 54130561Sobriennot be allocated, minus one is returned and @code{NULL} is stored in 5589857Sobrien@code{*@var{resptr}}. 5689857Sobrien 5789857Sobrien@end deftypefn 5889857Sobrien 5989857Sobrien@c atexit.c:6 6089857Sobrien@deftypefn Supplemental int atexit (void (*@var{f})()) 6189857Sobrien 6289857SobrienCauses function @var{f} to be called at exit. Returns 0. 6389857Sobrien 6489857Sobrien@end deftypefn 6589857Sobrien 6689857Sobrien@c basename.c:6 6789857Sobrien@deftypefn Supplemental char* basename (const char *@var{name}) 6889857Sobrien 6989857SobrienReturns a pointer to the last component of pathname @var{name}. 7089857SobrienBehavior is undefined if the pathname ends in a directory separator. 7189857Sobrien 7289857Sobrien@end deftypefn 7389857Sobrien 7489857Sobrien@c bcmp.c:6 7589857Sobrien@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count}) 7689857Sobrien 7789857SobrienCompares the first @var{count} bytes of two areas of memory. Returns 7889857Sobrienzero if they are the same, nonzero otherwise. Returns zero if 7989857Sobrien@var{count} is zero. A nonzero result only indicates a difference, 8089857Sobrienit does not indicate any sorting order (say, by having a positive 8189857Sobrienresult mean @var{x} sorts before @var{y}). 8289857Sobrien 8389857Sobrien@end deftypefn 8489857Sobrien 8589857Sobrien@c bcopy.c:3 8689857Sobrien@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length}) 8789857Sobrien 8889857SobrienCopies @var{length} bytes from memory region @var{in} to region 8989857Sobrien@var{out}. The use of @code{bcopy} is deprecated in new programs. 9089857Sobrien 9189857Sobrien@end deftypefn 9289857Sobrien 9389857Sobrien@c bsearch.c:33 9489857Sobrien@deftypefn Supplemental void* bsearch (const void *@var{key}, const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, int (*@var{compar})(const void *, const void *)) 9589857Sobrien 9689857SobrienPerforms a search over an array of @var{nmemb} elements pointed to by 9789857Sobrien@var{base} for a member that matches the object pointed to by @var{key}. 9889857SobrienThe size of each member is specified by @var{size}. The array contents 9989857Sobrienshould be sorted in ascending order according to the @var{compar} 10089857Sobriencomparison function. This routine should take two arguments pointing to 10189857Sobrienthe @var{key} and to an array member, in that order, and should return an 10289857Sobrieninteger less than, equal to, or greater than zero if the @var{key} object 10389857Sobrienis respectively less than, matching, or greater than the array member. 10489857Sobrien 10589857Sobrien@end deftypefn 10689857Sobrien 107218822Sdim@c argv.c:124 10889857Sobrien@deftypefn Extension char** buildargv (char *@var{sp}) 10989857Sobrien 11089857SobrienGiven a pointer to a string, parse the string extracting fields 11189857Sobrienseparated by whitespace and optionally enclosed within either single 11289857Sobrienor double quotes (which are stripped off), and build a vector of 11389857Sobrienpointers to copies of the string for each field. The input string 11489857Sobrienremains unchanged. The last element of the vector is followed by a 11589857Sobrien@code{NULL} element. 11689857Sobrien 11789857SobrienAll of the memory for the pointer array and copies of the string 11889857Sobrienis obtained from @code{malloc}. All of the memory can be returned to the 11989857Sobriensystem with the single function call @code{freeargv}, which takes the 12089857Sobrienreturned result of @code{buildargv}, as it's argument. 12189857Sobrien 12289857SobrienReturns a pointer to the argument vector if successful. Returns 12389857Sobrien@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient 12489857Sobrienmemory to complete building the argument vector. 12589857Sobrien 12689857SobrienIf the input is a null string (as opposed to a @code{NULL} pointer), 12789857Sobrienthen buildarg returns an argument vector that has one arg, a null 12889857Sobrienstring. 12989857Sobrien 13089857Sobrien@end deftypefn 13189857Sobrien 13289857Sobrien@c bzero.c:6 13389857Sobrien@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count}) 13489857Sobrien 13589857SobrienZeros @var{count} bytes starting at @var{mem}. Use of this function 13689857Sobrienis deprecated in favor of @code{memset}. 13789857Sobrien 13889857Sobrien@end deftypefn 13989857Sobrien 14089857Sobrien@c calloc.c:6 14189857Sobrien@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize}) 14289857Sobrien 14389857SobrienUses @code{malloc} to allocate storage for @var{nelem} objects of 14489857Sobrien@var{elsize} bytes each, then zeros the memory. 14589857Sobrien 14689857Sobrien@end deftypefn 14789857Sobrien 14889857Sobrien@c choose-temp.c:42 14989857Sobrien@deftypefn Extension char* choose_temp_base (void) 15089857Sobrien 15189857SobrienReturn a prefix for temporary file names or @code{NULL} if unable to 15289857Sobrienfind one. The current directory is chosen if all else fails so the 15389857Sobrienprogram is exited if a temporary directory can't be found (@code{mktemp} 15489857Sobrienfails). The buffer for the result is obtained with @code{xmalloc}. 15589857Sobrien 156218822SdimThis function is provided for backwards compatibility only. Its use is 15789857Sobriennot recommended. 15889857Sobrien 15989857Sobrien@end deftypefn 16089857Sobrien 161218822Sdim@c make-temp-file.c:87 16289857Sobrien@deftypefn Replacement char* choose_tmpdir () 16389857Sobrien 16489857SobrienReturns a pointer to a directory path suitable for creating temporary 16589857Sobrienfiles in. 16689857Sobrien 16789857Sobrien@end deftypefn 16889857Sobrien 16989857Sobrien@c clock.c:27 17089857Sobrien@deftypefn Supplemental long clock (void) 17189857Sobrien 17289857SobrienReturns an approximation of the CPU time used by the process as a 17389857Sobrien@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the 17489857Sobriennumber of seconds used. 17589857Sobrien 17689857Sobrien@end deftypefn 17789857Sobrien 17889857Sobrien@c concat.c:24 17989857Sobrien@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL}) 18089857Sobrien 18189857SobrienConcatenate zero or more of strings and return the result in freshly 18289857Sobrien@code{xmalloc}ed memory. Returns @code{NULL} if insufficient memory is 18389857Sobrienavailable. The argument list is terminated by the first @code{NULL} 18489857Sobrienpointer encountered. Pointers to empty strings are ignored. 18589857Sobrien 18689857Sobrien@end deftypefn 18789857Sobrien 188218822Sdim@c argv.c:52 18989857Sobrien@deftypefn Extension char** dupargv (char **@var{vector}) 19089857Sobrien 19189857SobrienDuplicate an argument vector. Simply scans through @var{vector}, 19289857Sobrienduplicating each argument until the terminating @code{NULL} is found. 19389857SobrienReturns a pointer to the argument vector if successful. Returns 19489857Sobrien@code{NULL} if there is insufficient memory to complete building the 19589857Sobrienargument vector. 19689857Sobrien 19789857Sobrien@end deftypefn 19889857Sobrien 199218822Sdim@c strerror.c:567 20089857Sobrien@deftypefn Extension int errno_max (void) 20189857Sobrien 20289857SobrienReturns the maximum @code{errno} value for which a corresponding 20389857Sobriensymbolic name or message is available. Note that in the case where we 20489857Sobrienuse the @code{sys_errlist} supplied by the system, it is possible for 20589857Sobrienthere to be more symbolic names than messages, or vice versa. In 20689857Sobrienfact, the manual page for @code{perror(3C)} explicitly warns that one 20789857Sobrienshould check the size of the table (@code{sys_nerr}) before indexing 20889857Sobrienit, since new error codes may be added to the system before they are 20989857Sobrienadded to the table. Thus @code{sys_nerr} might be smaller than value 21089857Sobrienimplied by the largest @code{errno} value defined in @code{<errno.h>}. 21189857Sobrien 21289857SobrienWe return the maximum value that can be used to obtain a meaningful 21389857Sobriensymbolic name or message. 21489857Sobrien 21589857Sobrien@end deftypefn 21689857Sobrien 217218822Sdim@c argv.c:293 218218822Sdim@deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp}) 219218822Sdim 220218822SdimThe @var{argcp} and @code{argvp} arguments are pointers to the usual 221218822Sdim@code{argc} and @code{argv} arguments to @code{main}. This function 222218822Sdimlooks for arguments that begin with the character @samp{@@}. Any such 223218822Sdimarguments are interpreted as ``response files''. The contents of the 224218822Sdimresponse file are interpreted as additional command line options. In 225218822Sdimparticular, the file is separated into whitespace-separated strings; 226218822Sdimeach such string is taken as a command-line option. The new options 227218822Sdimare inserted in place of the option naming the response file, and 228218822Sdim@code{*argcp} and @code{*argvp} will be updated. If the value of 229218822Sdim@code{*argvp} is modified by this function, then the new value has 230218822Sdimbeen dynamically allocated and can be deallocated by the caller with 231218822Sdim@code{freeargv}. However, most callers will simply call 232218822Sdim@code{expandargv} near the beginning of @code{main} and allow the 233218822Sdimoperating system to free the memory when the program exits. 234218822Sdim 235218822Sdim@end deftypefn 236218822Sdim 23789857Sobrien@c fdmatch.c:23 23889857Sobrien@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2}) 23989857Sobrien 24089857SobrienCheck to see if two open file descriptors refer to the same file. 24189857SobrienThis is useful, for example, when we have an open file descriptor for 24289857Sobrienan unnamed file, and the name of a file that we believe to correspond 24389857Sobriento that fd. This can happen when we are exec'd with an already open 24489857Sobrienfile (@code{stdout} for example) or from the SVR4 @file{/proc} calls 24589857Sobrienthat return open file descriptors for mapped address spaces. All we 24689857Sobrienhave to do is open the file by name and check the two file descriptors 24789857Sobrienfor a match, which is done by comparing major and minor device numbers 24889857Sobrienand inode numbers. 24989857Sobrien 25089857Sobrien@end deftypefn 25189857Sobrien 252218822Sdim@c fopen_unlocked.c:48 253218822Sdim@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, const char * @var{mode}) 254218822Sdim 255218822SdimOpens and returns a @code{FILE} pointer via @code{fdopen}. If the 256218822Sdimoperating system supports it, ensure that the stream is setup to avoid 257218822Sdimany multi-threaded locking. Otherwise return the @code{FILE} pointer 258218822Sdimunchanged. 259218822Sdim 260218822Sdim@end deftypefn 261218822Sdim 26289857Sobrien@c ffs.c:3 26389857Sobrien@deftypefn Supplemental int ffs (int @var{valu}) 26489857Sobrien 26589857SobrienFind the first (least significant) bit set in @var{valu}. Bits are 26689857Sobriennumbered from right to left, starting with bit 1 (corresponding to the 26789857Sobrienvalue 1). If @var{valu} is zero, zero is returned. 26889857Sobrien 26989857Sobrien@end deftypefn 27089857Sobrien 271218822Sdim@c filename_cmp.c:28 272218822Sdim@deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2}) 273218822Sdim 274218822SdimReturn zero if the two paths @var{s1} and @var{s2} are equivalent. 275218822SdimIf not equivalent, the returned value is similar to what strcmp would 276218822Sdimreturn. In other words, it returns a negative value if @var{s1} is less 277218822Sdimthan @var{s2}, or a positive value if @var{s2} is greater than @var{s2}. 278218822Sdim 279218822SdimThis function does not normalize path names. As a result, this function 280218822Sdimwill treat filenames that are spelled differently as different even in 281218822Sdimthe case when the two filenames point to the same underlying file. 282218822SdimHowever, it does handle the fact that on DOS-like file systems, forward 283218822Sdimand backward slashes are equal. 284218822Sdim 285218822Sdim@end deftypefn 286218822Sdim 28789857Sobrien@c fnmatch.txh:1 28889857Sobrien@deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags}) 28989857Sobrien 29089857SobrienMatches @var{string} against @var{pattern}, returning zero if it 29189857Sobrienmatches, @code{FNM_NOMATCH} if not. @var{pattern} may contain the 29289857Sobrienwildcards @code{?} to match any one character, @code{*} to match any 29389857Sobrienzero or more characters, or a set of alternate characters in square 29489857Sobrienbrackets, like @samp{[a-gt8]}, which match one character (@code{a} 29589857Sobrienthrough @code{g}, or @code{t}, or @code{8}, in this example) if that one 29689857Sobriencharacter is in the set. A set may be inverted (i.e., match anything 29789857Sobrienexcept what's in the set) by giving @code{^} or @code{!} as the first 29889857Sobriencharacter in the set. To include those characters in the set, list them 29989857Sobrienas anything other than the first character of the set. To include a 30089857Sobriendash in the set, list it last in the set. A backslash character makes 30189857Sobrienthe following character not special, so for example you could match 30289857Sobrienagainst a literal asterisk with @samp{\*}. To match a literal 30389857Sobrienbackslash, use @samp{\\}. 30489857Sobrien 30589857Sobrien@code{flags} controls various aspects of the matching process, and is a 30689857Sobrienboolean OR of zero or more of the following values (defined in 30789857Sobrien@code{<fnmatch.h>}): 30889857Sobrien 30989857Sobrien@table @code 31089857Sobrien 31189857Sobrien@item FNM_PATHNAME 31289857Sobrien@itemx FNM_FILE_NAME 31389857Sobrien@var{string} is assumed to be a path name. No wildcard will ever match 31489857Sobrien@code{/}. 31589857Sobrien 31689857Sobrien@item FNM_NOESCAPE 31789857SobrienDo not interpret backslashes as quoting the following special character. 31889857Sobrien 31989857Sobrien@item FNM_PERIOD 32089857SobrienA leading period (at the beginning of @var{string}, or if 32189857Sobrien@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or 32289857Sobrien@code{?} but must be matched explicitly. 32389857Sobrien 32489857Sobrien@item FNM_LEADING_DIR 32589857SobrienMeans that @var{string} also matches @var{pattern} if some initial part 32689857Sobrienof @var{string} matches, and is followed by @code{/} and zero or more 32789857Sobriencharacters. For example, @samp{foo*} would match either @samp{foobar} 32889857Sobrienor @samp{foobar/grill}. 32989857Sobrien 33089857Sobrien@item FNM_CASEFOLD 33189857SobrienIgnores case when performing the comparison. 33289857Sobrien 33389857Sobrien@end table 33489857Sobrien 33589857Sobrien@end deftypefn 33689857Sobrien 337218822Sdim@c fopen_unlocked.c:39 338218822Sdim@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, const char * @var{mode}) 339218822Sdim 340218822SdimOpens and returns a @code{FILE} pointer via @code{fopen}. If the 341218822Sdimoperating system supports it, ensure that the stream is setup to avoid 342218822Sdimany multi-threaded locking. Otherwise return the @code{FILE} pointer 343218822Sdimunchanged. 344218822Sdim 345218822Sdim@end deftypefn 346218822Sdim 347218822Sdim@c argv.c:97 34889857Sobrien@deftypefn Extension void freeargv (char **@var{vector}) 34989857Sobrien 35089857SobrienFree an argument vector that was built using @code{buildargv}. Simply 35189857Sobrienscans through @var{vector}, freeing the memory for each argument until 35289857Sobrienthe terminating @code{NULL} is found, and then frees @var{vector} 35389857Sobrienitself. 35489857Sobrien 35589857Sobrien@end deftypefn 35689857Sobrien 357218822Sdim@c fopen_unlocked.c:57 358218822Sdim@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, const char * @var{mode}, FILE * @var{stream}) 359218822Sdim 360218822SdimOpens and returns a @code{FILE} pointer via @code{freopen}. If the 361218822Sdimoperating system supports it, ensure that the stream is setup to avoid 362218822Sdimany multi-threaded locking. Otherwise return the @code{FILE} pointer 363218822Sdimunchanged. 364218822Sdim 365218822Sdim@end deftypefn 366218822Sdim 367130561Sobrien@c getruntime.c:82 36889857Sobrien@deftypefn Replacement long get_run_time (void) 36989857Sobrien 37089857SobrienReturns the time used so far, in microseconds. If possible, this is 37189857Sobrienthe time used by this process, else it is the elapsed time since the 37289857Sobrienprocess started. 37389857Sobrien 37489857Sobrien@end deftypefn 37589857Sobrien 37689857Sobrien@c getcwd.c:6 37789857Sobrien@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len}) 37889857Sobrien 37989857SobrienCopy the absolute pathname for the current working directory into 38089857Sobrien@var{pathname}, which is assumed to point to a buffer of at least 38189857Sobrien@var{len} bytes, and return a pointer to the buffer. If the current 38289857Sobriendirectory's path doesn't fit in @var{len} characters, the result is 38389857Sobrien@code{NULL} and @code{errno} is set. If @var{pathname} is a null pointer, 38489857Sobrien@code{getcwd} will obtain @var{len} bytes of space using 38589857Sobrien@code{malloc}. 38689857Sobrien 38789857Sobrien@end deftypefn 38889857Sobrien 38989857Sobrien@c getpagesize.c:5 39089857Sobrien@deftypefn Supplemental int getpagesize (void) 39189857Sobrien 39289857SobrienReturns the number of bytes in a page of memory. This is the 39389857Sobriengranularity of many of the system memory management routines. No 39489857Sobrienguarantee is made as to whether or not it is the same as the basic 39589857Sobrienmemory management hardware page size. 39689857Sobrien 39789857Sobrien@end deftypefn 39889857Sobrien 39989857Sobrien@c getpwd.c:5 40089857Sobrien@deftypefn Supplemental char* getpwd (void) 40189857Sobrien 40289857SobrienReturns the current working directory. This implementation caches the 40389857Sobrienresult on the assumption that the process will not call @code{chdir} 40489857Sobrienbetween calls to @code{getpwd}. 40589857Sobrien 40689857Sobrien@end deftypefn 40789857Sobrien 408218822Sdim@c gettimeofday.c:12 409218822Sdim@deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz}) 410218822Sdim 411218822SdimWrites the current time to @var{tp}. This implementation requires 412218822Sdimthat @var{tz} be NULL. Returns 0 on success, -1 on failure. 413218822Sdim 414218822Sdim@end deftypefn 415218822Sdim 416218822Sdim@c hex.c:33 417104834Sobrien@deftypefn Extension void hex_init (void) 418104834Sobrien 419104834SobrienInitializes the array mapping the current character set to 420104834Sobriencorresponding hex values. This function must be called before any 421130561Sobriencall to @code{hex_p} or @code{hex_value}. If you fail to call it, a 422130561Sobriendefault ASCII-based table will normally be used on ASCII systems. 423104834Sobrien 424104834Sobrien@end deftypefn 425104834Sobrien 426218822Sdim@c hex.c:42 427104834Sobrien@deftypefn Extension int hex_p (int @var{c}) 428104834Sobrien 429104834SobrienEvaluates to non-zero if the given character is a valid hex character, 430104834Sobrienor zero if it is not. Note that the value you pass will be cast to 431104834Sobrien@code{unsigned char} within the macro. 432104834Sobrien 433104834Sobrien@end deftypefn 434104834Sobrien 435218822Sdim@c hex.c:50 436218822Sdim@deftypefn Extension {unsigned int} hex_value (int @var{c}) 437104834Sobrien 438104834SobrienReturns the numeric equivalent of the given character when interpreted 439218822Sdimas a hexadecimal digit. The result is undefined if you pass an 440104834Sobrieninvalid hex digit. Note that the value you pass will be cast to 441104834Sobrien@code{unsigned char} within the macro. 442104834Sobrien 443130561SobrienThe @code{hex_value} macro returns @code{unsigned int}, rather than 444130561Sobriensigned @code{int}, to make it easier to use in parsing addresses from 445130561Sobrienhex dump files: a signed @code{int} would be sign-extended when 446130561Sobrienconverted to a wider unsigned type --- like @code{bfd_vma}, on some 447130561Sobriensystems. 448130561Sobrien 449104834Sobrien@end deftypefn 450104834Sobrien 45189857Sobrien@c index.c:5 45289857Sobrien@deftypefn Supplemental char* index (char *@var{s}, int @var{c}) 45389857Sobrien 45489857SobrienReturns a pointer to the first occurrence of the character @var{c} in 45589857Sobrienthe string @var{s}, or @code{NULL} if not found. The use of @code{index} is 45689857Sobriendeprecated in new programs in favor of @code{strchr}. 45789857Sobrien 45889857Sobrien@end deftypefn 45989857Sobrien 46089857Sobrien@c insque.c:6 46189857Sobrien@deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred}) 46289857Sobrien@deftypefnx Supplemental void remque (struct qelem *@var{elem}) 46389857Sobrien 46489857SobrienRoutines to manipulate queues built from doubly linked lists. The 46589857Sobrien@code{insque} routine inserts @var{elem} in the queue immediately 46689857Sobrienafter @var{pred}. The @code{remque} routine removes @var{elem} from 46789857Sobrienits containing queue. These routines expect to be passed pointers to 46889857Sobrienstructures which have as their first members a forward pointer and a 46989857Sobrienback pointer, like this prototype (although no prototype is provided): 47089857Sobrien 47189857Sobrien@example 47289857Sobrienstruct qelem @{ 47389857Sobrien struct qelem *q_forw; 47489857Sobrien struct qelem *q_back; 47589857Sobrien char q_data[]; 47689857Sobrien@}; 47789857Sobrien@end example 47889857Sobrien 47989857Sobrien@end deftypefn 48089857Sobrien 481218822Sdim@c safe-ctype.c:46 482130561Sobrien@deffn Extension ISALPHA (@var{c}) 483130561Sobrien@deffnx Extension ISALNUM (@var{c}) 484130561Sobrien@deffnx Extension ISBLANK (@var{c}) 485130561Sobrien@deffnx Extension ISCNTRL (@var{c}) 486130561Sobrien@deffnx Extension ISDIGIT (@var{c}) 487130561Sobrien@deffnx Extension ISGRAPH (@var{c}) 488130561Sobrien@deffnx Extension ISLOWER (@var{c}) 489130561Sobrien@deffnx Extension ISPRINT (@var{c}) 490130561Sobrien@deffnx Extension ISPUNCT (@var{c}) 491130561Sobrien@deffnx Extension ISSPACE (@var{c}) 492130561Sobrien@deffnx Extension ISUPPER (@var{c}) 493130561Sobrien@deffnx Extension ISXDIGIT (@var{c}) 494130561Sobrien 495130561SobrienThese twelve macros are defined by @file{safe-ctype.h}. Each has the 496130561Sobriensame meaning as the corresponding macro (with name in lowercase) 497130561Sobriendefined by the standard header @file{ctype.h}. For example, 498130561Sobrien@code{ISALPHA} returns true for alphabetic characters and false for 499130561Sobrienothers. However, there are two differences between these macros and 500130561Sobrienthose provided by @file{ctype.h}: 501130561Sobrien 502130561Sobrien@itemize @bullet 503130561Sobrien@item These macros are guaranteed to have well-defined behavior for all 504130561Sobrienvalues representable by @code{signed char} and @code{unsigned char}, and 505130561Sobrienfor @code{EOF}. 506130561Sobrien 507130561Sobrien@item These macros ignore the current locale; they are true for these 508130561Sobrienfixed sets of characters: 509130561Sobrien@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada} 510130561Sobrien@item @code{ALPHA} @tab @kbd{A-Za-z} 511130561Sobrien@item @code{ALNUM} @tab @kbd{A-Za-z0-9} 512130561Sobrien@item @code{BLANK} @tab @kbd{space tab} 513130561Sobrien@item @code{CNTRL} @tab @code{!PRINT} 514130561Sobrien@item @code{DIGIT} @tab @kbd{0-9} 515130561Sobrien@item @code{GRAPH} @tab @code{ALNUM || PUNCT} 516130561Sobrien@item @code{LOWER} @tab @kbd{a-z} 517130561Sobrien@item @code{PRINT} @tab @code{GRAPH ||} @kbd{space} 518130561Sobrien@item @code{PUNCT} @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?} 519130561Sobrien@item @code{SPACE} @tab @kbd{space tab \n \r \f \v} 520130561Sobrien@item @code{UPPER} @tab @kbd{A-Z} 521130561Sobrien@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f} 522130561Sobrien@end multitable 523130561Sobrien 524130561SobrienNote that, if the host character set is ASCII or a superset thereof, 525130561Sobrienall these macros will return false for all values of @code{char} outside 526130561Sobrienthe range of 7-bit ASCII. In particular, both ISPRINT and ISCNTRL return 527130561Sobrienfalse for characters with numeric values from 128 to 255. 528130561Sobrien@end itemize 529130561Sobrien@end deffn 530130561Sobrien 531218822Sdim@c safe-ctype.c:95 532130561Sobrien@deffn Extension ISIDNUM (@var{c}) 533130561Sobrien@deffnx Extension ISIDST (@var{c}) 534130561Sobrien@deffnx Extension IS_VSPACE (@var{c}) 535130561Sobrien@deffnx Extension IS_NVSPACE (@var{c}) 536130561Sobrien@deffnx Extension IS_SPACE_OR_NUL (@var{c}) 537130561Sobrien@deffnx Extension IS_ISOBASIC (@var{c}) 538130561SobrienThese six macros are defined by @file{safe-ctype.h} and provide 539130561Sobrienadditional character classes which are useful when doing lexical 540130561Sobrienanalysis of C or similar languages. They are true for the following 541130561Sobriensets of characters: 542130561Sobrien 543130561Sobrien@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada} 544130561Sobrien@item @code{IDNUM} @tab @kbd{A-Za-z0-9_} 545130561Sobrien@item @code{IDST} @tab @kbd{A-Za-z_} 546130561Sobrien@item @code{VSPACE} @tab @kbd{\r \n} 547130561Sobrien@item @code{NVSPACE} @tab @kbd{space tab \f \v \0} 548130561Sobrien@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE} 549130561Sobrien@item @code{ISOBASIC} @tab @code{VSPACE || NVSPACE || PRINT} 550130561Sobrien@end multitable 551130561Sobrien@end deffn 552130561Sobrien 55389857Sobrien@c lbasename.c:23 55489857Sobrien@deftypefn Replacement {const char*} lbasename (const char *@var{name}) 55589857Sobrien 55689857SobrienGiven a pointer to a string containing a typical pathname 55789857Sobrien(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the 55889857Sobrienlast component of the pathname (@samp{ls.c} in this case). The 55989857Sobrienreturned pointer is guaranteed to lie within the original 56089857Sobrienstring. This latter fact is not true of many vendor C 56189857Sobrienlibraries, which return special strings or modify the passed 56289857Sobrienstrings for particular input. 56389857Sobrien 56489857SobrienIn particular, the empty string returns the same empty string, 56589857Sobrienand a path ending in @code{/} returns the empty string after it. 56689857Sobrien 56789857Sobrien@end deftypefn 56889857Sobrien 569130561Sobrien@c lrealpath.c:25 570130561Sobrien@deftypefn Replacement {const char*} lrealpath (const char *@var{name}) 571130561Sobrien 572130561SobrienGiven a pointer to a string containing a pathname, returns a canonical 573130561Sobrienversion of the filename. Symlinks will be resolved, and ``.'' and ``..'' 574130561Sobriencomponents will be simplified. The returned value will be allocated using 575130561Sobrien@code{malloc}, or @code{NULL} will be returned on a memory allocation error. 576130561Sobrien 577130561Sobrien@end deftypefn 578130561Sobrien 579130561Sobrien@c make-relative-prefix.c:24 580130561Sobrien@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, const char *@var{bin_prefix}, const char *@var{prefix}) 581130561Sobrien 582130561SobrienGiven three paths @var{progname}, @var{bin_prefix}, @var{prefix}, 583130561Sobrienreturn the path that is in the same position relative to 584130561Sobrien@var{progname}'s directory as @var{prefix} is relative to 585130561Sobrien@var{bin_prefix}. That is, a string starting with the directory 586130561Sobrienportion of @var{progname}, followed by a relative pathname of the 587130561Sobriendifference between @var{bin_prefix} and @var{prefix}. 588130561Sobrien 589130561SobrienIf @var{progname} does not contain any directory separators, 590130561Sobrien@code{make_relative_prefix} will search @env{PATH} to find a program 591130561Sobriennamed @var{progname}. Also, if @var{progname} is a symbolic link, 592130561Sobrienthe symbolic link will be resolved. 593130561Sobrien 594130561SobrienFor example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta}, 595130561Sobrien@var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is 596130561Sobrien@code{/red/green/blue/gcc}, then this function will return 597130561Sobrien@code{/red/green/blue/../../omega/}. 598130561Sobrien 599130561SobrienThe return value is normally allocated via @code{malloc}. If no 600130561Sobrienrelative prefix can be found, return @code{NULL}. 601130561Sobrien 602130561Sobrien@end deftypefn 603130561Sobrien 604218822Sdim@c make-temp-file.c:137 60589857Sobrien@deftypefn Replacement char* make_temp_file (const char *@var{suffix}) 60689857Sobrien 60789857SobrienReturn a temporary file name (as a string) or @code{NULL} if unable to 60889857Sobriencreate one. @var{suffix} is a suffix to append to the file name. The 60989857Sobrienstring is @code{malloc}ed, and the temporary file has been created. 61089857Sobrien 61189857Sobrien@end deftypefn 61289857Sobrien 61389857Sobrien@c memchr.c:3 61489857Sobrien@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n}) 61589857Sobrien 61689857SobrienThis function searches memory starting at @code{*@var{s}} for the 61789857Sobriencharacter @var{c}. The search only ends with the first occurrence of 61889857Sobrien@var{c}, or after @var{length} characters; in particular, a null 61989857Sobriencharacter does not terminate the search. If the character @var{c} is 62089857Sobrienfound within @var{length} characters of @code{*@var{s}}, a pointer 62189857Sobriento the character is returned. If @var{c} is not found, then @code{NULL} is 62289857Sobrienreturned. 62389857Sobrien 62489857Sobrien@end deftypefn 62589857Sobrien 62689857Sobrien@c memcmp.c:6 62789857Sobrien@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count}) 62889857Sobrien 62989857SobrienCompares the first @var{count} bytes of two areas of memory. Returns 63089857Sobrienzero if they are the same, a value less than zero if @var{x} is 63189857Sobrienlexically less than @var{y}, or a value greater than zero if @var{x} 63289857Sobrienis lexically greater than @var{y}. Note that lexical order is determined 63389857Sobrienas if comparing unsigned char arrays. 63489857Sobrien 63589857Sobrien@end deftypefn 63689857Sobrien 63789857Sobrien@c memcpy.c:6 63889857Sobrien@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length}) 63989857Sobrien 64089857SobrienCopies @var{length} bytes from memory region @var{in} to region 64189857Sobrien@var{out}. Returns a pointer to @var{out}. 64289857Sobrien 64389857Sobrien@end deftypefn 64489857Sobrien 64589857Sobrien@c memmove.c:6 64689857Sobrien@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count}) 64789857Sobrien 64889857SobrienCopies @var{count} bytes from memory area @var{from} to memory area 64989857Sobrien@var{to}, returning a pointer to @var{to}. 65089857Sobrien 65189857Sobrien@end deftypefn 65289857Sobrien 653130561Sobrien@c mempcpy.c:23 654130561Sobrien@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, size_t @var{length}) 655130561Sobrien 656130561SobrienCopies @var{length} bytes from memory region @var{in} to region 657130561Sobrien@var{out}. Returns a pointer to @var{out} + @var{length}. 658130561Sobrien 659130561Sobrien@end deftypefn 660130561Sobrien 66189857Sobrien@c memset.c:6 66289857Sobrien@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count}) 66389857Sobrien 66489857SobrienSets the first @var{count} bytes of @var{s} to the constant byte 66589857Sobrien@var{c}, returning a pointer to @var{s}. 66689857Sobrien 66789857Sobrien@end deftypefn 66889857Sobrien 669218822Sdim@c mkstemps.c:58 670218822Sdim@deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len}) 67189857Sobrien 672218822SdimGenerate a unique temporary file name from @var{pattern}. 673218822Sdim@var{pattern} has the form: 67489857Sobrien 67589857Sobrien@example 67689857Sobrien @var{path}/ccXXXXXX@var{suffix} 67789857Sobrien@end example 67889857Sobrien 67989857Sobrien@var{suffix_len} tells us how long @var{suffix} is (it can be zero 680218822Sdimlength). The last six characters of @var{pattern} before @var{suffix} 68189857Sobrienmust be @samp{XXXXXX}; they are replaced with a string that makes the 68289857Sobrienfilename unique. Returns a file descriptor open on the file for 68389857Sobrienreading and writing. 68489857Sobrien 68589857Sobrien@end deftypefn 68689857Sobrien 687218822Sdim@c pexecute.txh:266 688218822Sdim@deftypefn Extension void pex_free (struct pex_obj @var{obj}) 68989857Sobrien 690218822SdimClean up and free all data associated with @var{obj}. 69189857Sobrien 692218822Sdim@end deftypefn 69389857Sobrien 694218822Sdim@c pexecute.txh:241 695218822Sdim@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector}) 69689857Sobrien 697218822SdimReturns the exit status of all programs run using @var{obj}. 698218822Sdim@var{count} is the number of results expected. The results will be 699218822Sdimplaced into @var{vector}. The results are in the order of the calls 700218822Sdimto @code{pex_run}. Returns 0 on error, 1 on success. 70189857Sobrien 702218822Sdim@end deftypefn 70389857Sobrien 704218822Sdim@c pexecute.txh:250 705218822Sdim@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector}) 70689857Sobrien 707218822SdimReturns the process execution times of all programs run using 708218822Sdim@var{obj}. @var{count} is the number of results expected. The 709218822Sdimresults will be placed into @var{vector}. The results are in the 710218822Sdimorder of the calls to @code{pex_run}. Returns 0 on error, 1 on 711218822Sdimsuccess. 71289857Sobrien 713218822Sdim@code{struct pex_time} has the following fields of the type 714218822Sdim@code{unsigned long}: @code{user_seconds}, 715218822Sdim@code{user_microseconds}, @code{system_seconds}, 716218822Sdim@code{system_microseconds}. On systems which do not support reporting 717218822Sdimprocess times, all the fields will be set to @code{0}. 71889857Sobrien 71989857Sobrien@end deftypefn 72089857Sobrien 721218822Sdim@c pexecute.txh:2 722218822Sdim@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase}) 72389857Sobrien 724218822SdimPrepare to execute one or more programs, with standard output of each 725218822Sdimprogram fed to standard input of the next. This is a system 726218822Sdimindependent interface to execute a pipeline. 727218822Sdim 728218822Sdim@var{flags} is a bitwise combination of the following: 729218822Sdim 730218822Sdim@table @code 731218822Sdim 732218822Sdim@vindex PEX_RECORD_TIMES 733218822Sdim@item PEX_RECORD_TIMES 734218822SdimRecord subprocess times if possible. 735218822Sdim 736218822Sdim@vindex PEX_USE_PIPES 737218822Sdim@item PEX_USE_PIPES 738218822SdimUse pipes for communication between processes, if possible. 739218822Sdim 740218822Sdim@vindex PEX_SAVE_TEMPS 741218822Sdim@item PEX_SAVE_TEMPS 742218822SdimDon't delete temporary files used for communication between 743218822Sdimprocesses. 744218822Sdim 745218822Sdim@end table 746218822Sdim 747218822Sdim@var{pname} is the name of program to be executed, used in error 748218822Sdimmessages. @var{tempbase} is a base name to use for any required 749218822Sdimtemporary files; it may be @code{NULL} to use a randomly chosen name. 750218822Sdim 751218822Sdim@end deftypefn 752218822Sdim 753218822Sdim@c pexecute.txh:155 754218822Sdim@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{in_name}) 755218822Sdim 756218822SdimReturn a stream for a temporary file to pass to the first program in 757218822Sdimthe pipeline as input. 758218822Sdim 759218822SdimThe name of the input file is chosen according to the same rules 760218822Sdim@code{pex_run} uses to choose output file names, based on 761218822Sdim@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}. 762218822Sdim 763218822SdimDon't call @code{fclose} on the returned stream; the first call to 764218822Sdim@code{pex_run} closes it automatically. 765218822Sdim 766218822SdimIf @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in 767218822Sdimbinary mode; otherwise, open it in the default mode. Including 768218822Sdim@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix. 769218822Sdim@end deftypefn 770218822Sdim 771218822Sdim@c pexecute.txh:172 772218822Sdim@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, int @var{binary}) 773218822Sdim 774218822SdimReturn a stream @var{fp} for a pipe connected to the standard input of 775218822Sdimthe first program in the pipeline; @var{fp} is opened for writing. 776218822SdimYou must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call 777218822Sdimthat returned @var{obj}. 778218822Sdim 779218822SdimYou must close @var{fp} using @code{fclose} yourself when you have 780218822Sdimfinished writing data to the pipeline. 781218822Sdim 782218822SdimThe file descriptor underlying @var{fp} is marked not to be inherited 783218822Sdimby child processes. 784218822Sdim 785218822SdimOn systems that do not support pipes, this function returns 786218822Sdim@code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would 787218822Sdimlike to write code that is portable to all systems the @code{pex} 788218822Sdimfunctions support, consider using @code{pex_input_file} instead. 789218822Sdim 790218822SdimThere are two opportunities for deadlock using 791218822Sdim@code{pex_input_pipe}: 792218822Sdim 793218822Sdim@itemize @bullet 794218822Sdim@item 795218822SdimMost systems' pipes can buffer only a fixed amount of data; a process 796218822Sdimthat writes to a full pipe blocks. Thus, if you write to @file{fp} 797218822Sdimbefore starting the first process, you run the risk of blocking when 798218822Sdimthere is no child process yet to read the data and allow you to 799218822Sdimcontinue. @code{pex_input_pipe} makes no promises about the 800218822Sdimsize of the pipe's buffer, so if you need to write any data at all 801218822Sdimbefore starting the first process in the pipeline, consider using 802218822Sdim@code{pex_input_file} instead. 803218822Sdim 804218822Sdim@item 805218822SdimUsing @code{pex_input_pipe} and @code{pex_read_output} together 806218822Sdimmay also cause deadlock. If the output pipe fills up, so that each 807218822Sdimprogram in the pipeline is waiting for the next to read more data, and 808218822Sdimyou fill the input pipe by writing more data to @var{fp}, then there 809218822Sdimis no way to make progress: the only process that could read data from 810218822Sdimthe output pipe is you, but you are blocked on the input pipe. 811218822Sdim 812218822Sdim@end itemize 813218822Sdim 814218822Sdim@end deftypefn 815218822Sdim 816218822Sdim@c pexecute.txh:272 817218822Sdim@deftypefn Extension {const char *} pex_one (int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, int *@var{status}, int *@var{err}) 818218822Sdim 819218822SdimAn interface to permit the easy execution of a 820218822Sdimsingle program. The return value and most of the parameters are as 821218822Sdimfor a call to @code{pex_run}. @var{flags} is restricted to a 822218822Sdimcombination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and 823218822Sdim@code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if 824218822Sdim@code{PEX_LAST} were set. On a successful return, @code{*@var{status}} will 825218822Sdimbe set to the exit status of the program. 826218822Sdim 827218822Sdim@end deftypefn 828218822Sdim 829218822Sdim@c pexecute.txh:228 830218822Sdim@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, int @var{binary}) 831218822Sdim 832218822SdimReturns a @code{FILE} pointer which may be used to read the standard 833218822Sdimerror of the last program in the pipeline. When this is used, 834218822Sdim@code{PEX_LAST} should not be used in a call to @code{pex_run}. After 835218822Sdimthis is called, @code{pex_run} may no longer be called with the same 836218822Sdim@var{obj}. @var{binary} should be non-zero if the file should be 837218822Sdimopened in binary mode. Don't call @code{fclose} on the returned file; 838218822Sdimit will be closed by @code{pex_free}. 839218822Sdim 840218822Sdim@end deftypefn 841218822Sdim 842218822Sdim@c pexecute.txh:216 843218822Sdim@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary}) 844218822Sdim 845218822SdimReturns a @code{FILE} pointer which may be used to read the standard 846218822Sdimoutput of the last program in the pipeline. When this is used, 847218822Sdim@code{PEX_LAST} should not be used in a call to @code{pex_run}. After 848218822Sdimthis is called, @code{pex_run} may no longer be called with the same 849218822Sdim@var{obj}. @var{binary} should be non-zero if the file should be 850218822Sdimopened in binary mode. Don't call @code{fclose} on the returned file; 851218822Sdimit will be closed by @code{pex_free}. 852218822Sdim 853218822Sdim@end deftypefn 854218822Sdim 855218822Sdim@c pexecute.txh:33 856218822Sdim@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{outname}, const char *@var{errname}, int *@var{err}) 857218822Sdim 858218822SdimExecute one program in a pipeline. On success this returns 859218822Sdim@code{NULL}. On failure it returns an error message, a statically 860218822Sdimallocated string. 861218822Sdim 862218822Sdim@var{obj} is returned by a previous call to @code{pex_init}. 863218822Sdim 864218822Sdim@var{flags} is a bitwise combination of the following: 865218822Sdim 866218822Sdim@table @code 867218822Sdim 868218822Sdim@vindex PEX_LAST 869218822Sdim@item PEX_LAST 870218822SdimThis must be set on the last program in the pipeline. In particular, 871218822Sdimit should be set when executing a single program. The standard output 872218822Sdimof the program will be sent to @var{outname}, or, if @var{outname} is 873218822Sdim@code{NULL}, to the standard output of the calling program. Do @emph{not} 874218822Sdimset this bit if you want to call @code{pex_read_output} 875218822Sdim(described below). After a call to @code{pex_run} with this bit set, 876218822Sdim@var{pex_run} may no longer be called with the same @var{obj}. 877218822Sdim 878218822Sdim@vindex PEX_SEARCH 879218822Sdim@item PEX_SEARCH 880218822SdimSearch for the program using the user's executable search path. 881218822Sdim 882218822Sdim@vindex PEX_SUFFIX 883218822Sdim@item PEX_SUFFIX 884218822Sdim@var{outname} is a suffix. See the description of @var{outname}, 885218822Sdimbelow. 886218822Sdim 887218822Sdim@vindex PEX_STDERR_TO_STDOUT 888218822Sdim@item PEX_STDERR_TO_STDOUT 889218822SdimSend the program's standard error to standard output, if possible. 890218822Sdim 891218822Sdim@vindex PEX_BINARY_INPUT 892218822Sdim@vindex PEX_BINARY_OUTPUT 893218822Sdim@vindex PEX_BINARY_ERROR 894218822Sdim@item PEX_BINARY_INPUT 895218822Sdim@itemx PEX_BINARY_OUTPUT 896218822Sdim@itemx PEX_BINARY_ERROR 897218822SdimThe standard input (output or error) of the program should be read (written) in 898218822Sdimbinary mode rather than text mode. These flags are ignored on systems 899218822Sdimwhich do not distinguish binary mode and text mode, such as Unix. For 900218822Sdimproper behavior these flags should match appropriately---a call to 901218822Sdim@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a 902218822Sdimcall using @code{PEX_BINARY_INPUT}. 903218822Sdim 904218822Sdim@vindex PEX_STDERR_TO_PIPE 905218822Sdim@item PEX_STDERR_TO_PIPE 906218822SdimSend the program's standard error to a pipe, if possible. This flag 907218822Sdimcannot be specified together with @code{PEX_STDERR_TO_STDOUT}. This 908218822Sdimflag can be specified only on the last program in pipeline. 909218822Sdim 910218822Sdim@end table 911218822Sdim 912218822Sdim@var{executable} is the program to execute. @var{argv} is the set of 913218822Sdimarguments to pass to the program; normally @code{@var{argv}[0]} will 914218822Sdimbe a copy of @var{executable}. 915218822Sdim 916218822Sdim@var{outname} is used to set the name of the file to use for standard 917218822Sdimoutput. There are two cases in which no output file will be used: 918218822Sdim 919218822Sdim@enumerate 920218822Sdim@item 921218822Sdimif @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} 922218822Sdimwas set in the call to @code{pex_init}, and the system supports pipes 923218822Sdim 924218822Sdim@item 925218822Sdimif @code{PEX_LAST} is set in @var{flags}, and @var{outname} is 926218822Sdim@code{NULL} 927218822Sdim@end enumerate 928218822Sdim 929218822Sdim@noindent 930218822SdimOtherwise the code will use a file to hold standard 931218822Sdimoutput. If @code{PEX_LAST} is not set, this file is considered to be 932218822Sdima temporary file, and it will be removed when no longer needed, unless 933218822Sdim@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. 934218822Sdim 935218822SdimThere are two cases to consider when setting the name of the file to 936218822Sdimhold standard output. 937218822Sdim 938218822Sdim@enumerate 939218822Sdim@item 940218822Sdim@code{PEX_SUFFIX} is set in @var{flags}. In this case 941218822Sdim@var{outname} may not be @code{NULL}. If the @var{tempbase} parameter 942218822Sdimto @code{pex_init} was not @code{NULL}, then the output file name is 943218822Sdimthe concatenation of @var{tempbase} and @var{outname}. If 944218822Sdim@var{tempbase} was @code{NULL}, then the output file name is a random 945218822Sdimfile name ending in @var{outname}. 946218822Sdim 947218822Sdim@item 948218822Sdim@code{PEX_SUFFIX} was not set in @var{flags}. In this 949218822Sdimcase, if @var{outname} is not @code{NULL}, it is used as the output 950218822Sdimfile name. If @var{outname} is @code{NULL}, and @var{tempbase} was 951218822Sdimnot NULL, the output file name is randomly chosen using 952218822Sdim@var{tempbase}. Otherwise the output file name is chosen completely 953218822Sdimat random. 954218822Sdim@end enumerate 955218822Sdim 956218822Sdim@var{errname} is the file name to use for standard error output. If 957218822Sdimit is @code{NULL}, standard error is the same as the caller's. 958218822SdimOtherwise, standard error is written to the named file. 959218822Sdim 960218822SdimOn an error return, the code sets @code{*@var{err}} to an @code{errno} 961218822Sdimvalue, or to 0 if there is no relevant @code{errno}. 962218822Sdim 963218822Sdim@end deftypefn 964218822Sdim 965218822Sdim@c pexecute.txh:142 966218822Sdim@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, char * const *@var{env}, int @var{env_size}, const char *@var{outname}, const char *@var{errname}, int *@var{err}) 967218822Sdim 968218822SdimExecute one program in a pipeline, permitting the environment for the 969218822Sdimprogram to be specified. Behaviour and parameters not listed below are 970218822Sdimas for @code{pex_run}. 971218822Sdim 972218822Sdim@var{env} is the environment for the child process, specified as an array of 973218822Sdimcharacter pointers. Each element of the array should point to a string of the 974218822Sdimform @code{VAR=VALUE}, with the exception of the last element that must be 975218822Sdim@code{NULL}. 976218822Sdim 977218822Sdim@end deftypefn 978218822Sdim 979218822Sdim@c pexecute.txh:284 980218822Sdim@deftypefn Extension int pexecute (const char *@var{program}, char * const *@var{argv}, const char *@var{this_pname}, const char *@var{temp_base}, char **@var{errmsg_fmt}, char **@var{errmsg_arg}, int @var{flags}) 981218822Sdim 982218822SdimThis is the old interface to execute one or more programs. It is 983218822Sdimstill supported for compatibility purposes, but is no longer 984218822Sdimdocumented. 985218822Sdim 986218822Sdim@end deftypefn 987218822Sdim 988218822Sdim@c strsignal.c:539 989218822Sdim@deftypefn Supplemental void psignal (int @var{signo}, char *@var{message}) 990218822Sdim 99189857SobrienPrint @var{message} to the standard error, followed by a colon, 99289857Sobrienfollowed by the description of the signal specified by @var{signo}, 99389857Sobrienfollowed by a newline. 99489857Sobrien 99589857Sobrien@end deftypefn 99689857Sobrien 99789857Sobrien@c putenv.c:21 99889857Sobrien@deftypefn Supplemental int putenv (const char *@var{string}) 99989857Sobrien 100089857SobrienUses @code{setenv} or @code{unsetenv} to put @var{string} into 100189857Sobrienthe environment or remove it. If @var{string} is of the form 100289857Sobrien@samp{name=value} the string is added; if no @samp{=} is present the 100389857Sobrienname is unset/removed. 100489857Sobrien 100589857Sobrien@end deftypefn 100689857Sobrien 1007218822Sdim@c pexecute.txh:292 100889857Sobrien@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) 100989857Sobrien 1010218822SdimAnother part of the old execution interface. 101189857Sobrien 101289857Sobrien@end deftypefn 101389857Sobrien 101489857Sobrien@c random.c:39 101589857Sobrien@deftypefn Supplement {long int} random (void) 101689857Sobrien@deftypefnx Supplement void srandom (unsigned int @var{seed}) 101789857Sobrien@deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n}) 101889857Sobrien@deftypefnx Supplement void* setstate (void *@var{arg_state}) 101989857Sobrien 102089857SobrienRandom number functions. @code{random} returns a random number in the 102189857Sobrienrange 0 to @code{LONG_MAX}. @code{srandom} initializes the random 102289857Sobriennumber generator to some starting point determined by @var{seed} 102389857Sobrien(else, the values returned by @code{random} are always the same for each 102489857Sobrienrun of the program). @code{initstate} and @code{setstate} allow fine-grained 102589857Sobriencontrol over the state of the random number generator. 102689857Sobrien 102789857Sobrien@end deftypefn 102889857Sobrien 1029218822Sdim@c concat.c:173 103089857Sobrien@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL}) 103189857Sobrien 103289857SobrienSame as @code{concat}, except that if @var{optr} is not @code{NULL} it 103389857Sobrienis freed after the string is created. This is intended to be useful 103489857Sobrienwhen you're extending an existing string or building up a string in a 103589857Sobrienloop: 103689857Sobrien 103789857Sobrien@example 103889857Sobrien str = reconcat (str, "pre-", str, NULL); 103989857Sobrien@end example 104089857Sobrien 104189857Sobrien@end deftypefn 104289857Sobrien 104389857Sobrien@c rename.c:6 104489857Sobrien@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new}) 104589857Sobrien 104689857SobrienRenames a file from @var{old} to @var{new}. If @var{new} already 104789857Sobrienexists, it is removed. 104889857Sobrien 104989857Sobrien@end deftypefn 105089857Sobrien 105189857Sobrien@c rindex.c:5 105289857Sobrien@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c}) 105389857Sobrien 105489857SobrienReturns a pointer to the last occurrence of the character @var{c} in 105589857Sobrienthe string @var{s}, or @code{NULL} if not found. The use of @code{rindex} is 105689857Sobriendeprecated in new programs in favor of @code{strrchr}. 105789857Sobrien 105889857Sobrien@end deftypefn 105989857Sobrien 106089857Sobrien@c setenv.c:22 106189857Sobrien@deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite}) 106289857Sobrien@deftypefnx Supplemental void unsetenv (const char *@var{name}) 106389857Sobrien 106489857Sobrien@code{setenv} adds @var{name} to the environment with value 106589857Sobrien@var{value}. If the name was already present in the environment, 106689857Sobrienthe new value will be stored only if @var{overwrite} is nonzero. 106789857SobrienThe companion @code{unsetenv} function removes @var{name} from the 106889857Sobrienenvironment. This implementation is not safe for multithreaded code. 106989857Sobrien 107089857Sobrien@end deftypefn 107189857Sobrien 1072218822Sdim@c strsignal.c:348 107389857Sobrien@deftypefn Extension int signo_max (void) 107489857Sobrien 107589857SobrienReturns the maximum signal value for which a corresponding symbolic 107689857Sobrienname or message is available. Note that in the case where we use the 107789857Sobrien@code{sys_siglist} supplied by the system, it is possible for there to 107889857Sobrienbe more symbolic names than messages, or vice versa. In fact, the 107989857Sobrienmanual page for @code{psignal(3b)} explicitly warns that one should 108089857Sobriencheck the size of the table (@code{NSIG}) before indexing it, since 108189857Sobriennew signal codes may be added to the system before they are added to 108289857Sobrienthe table. Thus @code{NSIG} might be smaller than value implied by 108389857Sobrienthe largest signo value defined in @code{<signal.h>}. 108489857Sobrien 108589857SobrienWe return the maximum value that can be used to obtain a meaningful 108689857Sobriensymbolic name or message. 108789857Sobrien 108889857Sobrien@end deftypefn 108989857Sobrien 109089857Sobrien@c sigsetmask.c:8 109189857Sobrien@deftypefn Supplemental int sigsetmask (int @var{set}) 109289857Sobrien 109389857SobrienSets the signal mask to the one provided in @var{set} and returns 109489857Sobrienthe old mask (which, for libiberty's implementation, will always 109589857Sobrienbe the value @code{1}). 109689857Sobrien 109789857Sobrien@end deftypefn 109889857Sobrien 1099130561Sobrien@c snprintf.c:28 1100130561Sobrien@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...) 1101130561Sobrien 1102130561SobrienThis function is similar to sprintf, but it will print at most @var{n} 1103130561Sobriencharacters. On error the return value is -1, otherwise it returns the 1104130561Sobriennumber of characters that would have been printed had @var{n} been 1105130561Sobriensufficiently large, regardless of the actual value of @var{n}. Note 1106130561Sobriensome pre-C99 system libraries do not implement this correctly so users 1107130561Sobriencannot generally rely on the return value if the system version of 1108130561Sobrienthis function is used. 1109130561Sobrien 1110130561Sobrien@end deftypefn 1111130561Sobrien 111289857Sobrien@c spaces.c:22 111389857Sobrien@deftypefn Extension char* spaces (int @var{count}) 111489857Sobrien 111589857SobrienReturns a pointer to a memory region filled with the specified 111689857Sobriennumber of spaces and null terminated. The returned pointer is 111789857Sobrienvalid until at least the next call. 111889857Sobrien 111989857Sobrien@end deftypefn 112089857Sobrien 1121130561Sobrien@c stpcpy.c:23 1122130561Sobrien@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src}) 1123130561Sobrien 1124130561SobrienCopies the string @var{src} into @var{dst}. Returns a pointer to 1125130561Sobrien@var{dst} + strlen(@var{src}). 1126130561Sobrien 1127130561Sobrien@end deftypefn 1128130561Sobrien 1129130561Sobrien@c stpncpy.c:23 1130130561Sobrien@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, size_t @var{len}) 1131130561Sobrien 1132130561SobrienCopies the string @var{src} into @var{dst}, copying exactly @var{len} 1133130561Sobrienand padding with zeros if necessary. If @var{len} < strlen(@var{src}) 1134130561Sobrienthen return @var{dst} + @var{len}, otherwise returns @var{dst} + 1135130561Sobrienstrlen(@var{src}). 1136130561Sobrien 1137130561Sobrien@end deftypefn 1138130561Sobrien 113989857Sobrien@c strcasecmp.c:15 114089857Sobrien@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2}) 114189857Sobrien 114289857SobrienA case-insensitive @code{strcmp}. 114389857Sobrien 114489857Sobrien@end deftypefn 114589857Sobrien 114689857Sobrien@c strchr.c:6 114789857Sobrien@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c}) 114889857Sobrien 114989857SobrienReturns a pointer to the first occurrence of the character @var{c} in 115089857Sobrienthe string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 115189857Sobriennull character, the results are undefined. 115289857Sobrien 115389857Sobrien@end deftypefn 115489857Sobrien 115589857Sobrien@c strdup.c:3 115689857Sobrien@deftypefn Supplemental char* strdup (const char *@var{s}) 115789857Sobrien 115889857SobrienReturns a pointer to a copy of @var{s} in memory obtained from 115989857Sobrien@code{malloc}, or @code{NULL} if insufficient memory was available. 116089857Sobrien 116189857Sobrien@end deftypefn 116289857Sobrien 116389857Sobrien@c strerror.c:670 116489857Sobrien@deftypefn Replacement {const char*} strerrno (int @var{errnum}) 116589857Sobrien 116689857SobrienGiven an error number returned from a system call (typically returned 116789857Sobrienin @code{errno}), returns a pointer to a string containing the 116889857Sobriensymbolic name of that error number, as found in @code{<errno.h>}. 116989857Sobrien 117089857SobrienIf the supplied error number is within the valid range of indices for 117189857Sobriensymbolic names, but no name is available for the particular error 117289857Sobriennumber, then returns the string @samp{Error @var{num}}, where @var{num} 117389857Sobrienis the error number. 117489857Sobrien 117589857SobrienIf the supplied error number is not within the range of valid 117689857Sobrienindices, then returns @code{NULL}. 117789857Sobrien 117889857SobrienThe contents of the location pointed to are only guaranteed to be 117989857Sobrienvalid until the next call to @code{strerrno}. 118089857Sobrien 118189857Sobrien@end deftypefn 118289857Sobrien 1183218822Sdim@c strerror.c:603 118489857Sobrien@deftypefn Supplemental char* strerror (int @var{errnoval}) 118589857Sobrien 118689857SobrienMaps an @code{errno} number to an error message string, the contents 118789857Sobrienof which are implementation defined. On systems which have the 118889857Sobrienexternal variables @code{sys_nerr} and @code{sys_errlist}, these 118989857Sobrienstrings will be the same as the ones used by @code{perror}. 119089857Sobrien 119189857SobrienIf the supplied error number is within the valid range of indices for 119289857Sobrienthe @code{sys_errlist}, but no message is available for the particular 119389857Sobrienerror number, then returns the string @samp{Error @var{num}}, where 119489857Sobrien@var{num} is the error number. 119589857Sobrien 119689857SobrienIf the supplied error number is not a valid index into 119789857Sobrien@code{sys_errlist}, returns @code{NULL}. 119889857Sobrien 119989857SobrienThe returned string is only guaranteed to be valid only until the 120089857Sobriennext call to @code{strerror}. 120189857Sobrien 120289857Sobrien@end deftypefn 120389857Sobrien 120489857Sobrien@c strncasecmp.c:15 120589857Sobrien@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2}) 120689857Sobrien 120789857SobrienA case-insensitive @code{strncmp}. 120889857Sobrien 120989857Sobrien@end deftypefn 121089857Sobrien 121189857Sobrien@c strncmp.c:6 121289857Sobrien@deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) 121389857Sobrien 121489857SobrienCompares the first @var{n} bytes of two strings, returning a value as 121589857Sobrien@code{strcmp}. 121689857Sobrien 121789857Sobrien@end deftypefn 121889857Sobrien 1219218822Sdim@c strndup.c:23 1220218822Sdim@deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n}) 1221218822Sdim 1222218822SdimReturns a pointer to a copy of @var{s} with at most @var{n} characters 1223218822Sdimin memory obtained from @code{malloc}, or @code{NULL} if insufficient 1224218822Sdimmemory was available. The result is always NUL terminated. 1225218822Sdim 1226218822Sdim@end deftypefn 1227218822Sdim 122889857Sobrien@c strrchr.c:6 122989857Sobrien@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c}) 123089857Sobrien 123189857SobrienReturns a pointer to the last occurrence of the character @var{c} in 123289857Sobrienthe string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 123389857Sobriennull character, the results are undefined. 123489857Sobrien 123589857Sobrien@end deftypefn 123689857Sobrien 1237218822Sdim@c strsignal.c:383 123889857Sobrien@deftypefn Supplemental {const char *} strsignal (int @var{signo}) 123989857Sobrien 124089857SobrienMaps an signal number to an signal message string, the contents of 124189857Sobrienwhich are implementation defined. On systems which have the external 124289857Sobrienvariable @code{sys_siglist}, these strings will be the same as the 124389857Sobrienones used by @code{psignal()}. 124489857Sobrien 124589857SobrienIf the supplied signal number is within the valid range of indices for 124689857Sobrienthe @code{sys_siglist}, but no message is available for the particular 124789857Sobriensignal number, then returns the string @samp{Signal @var{num}}, where 124889857Sobrien@var{num} is the signal number. 124989857Sobrien 125089857SobrienIf the supplied signal number is not a valid index into 125189857Sobrien@code{sys_siglist}, returns @code{NULL}. 125289857Sobrien 125389857SobrienThe returned string is only guaranteed to be valid only until the next 125489857Sobriencall to @code{strsignal}. 125589857Sobrien 125689857Sobrien@end deftypefn 125789857Sobrien 1258218822Sdim@c strsignal.c:446 125989857Sobrien@deftypefn Extension {const char*} strsigno (int @var{signo}) 126089857Sobrien 126189857SobrienGiven an signal number, returns a pointer to a string containing the 126289857Sobriensymbolic name of that signal number, as found in @code{<signal.h>}. 126389857Sobrien 126489857SobrienIf the supplied signal number is within the valid range of indices for 126589857Sobriensymbolic names, but no name is available for the particular signal 126689857Sobriennumber, then returns the string @samp{Signal @var{num}}, where 126789857Sobrien@var{num} is the signal number. 126889857Sobrien 126989857SobrienIf the supplied signal number is not within the range of valid 127089857Sobrienindices, then returns @code{NULL}. 127189857Sobrien 127289857SobrienThe contents of the location pointed to are only guaranteed to be 127389857Sobrienvalid until the next call to @code{strsigno}. 127489857Sobrien 127589857Sobrien@end deftypefn 127689857Sobrien 127789857Sobrien@c strstr.c:6 127889857Sobrien@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub}) 127989857Sobrien 128089857SobrienThis function searches for the substring @var{sub} in the string 128189857Sobrien@var{string}, not including the terminating null characters. A pointer 128289857Sobriento the first occurrence of @var{sub} is returned, or @code{NULL} if the 128389857Sobriensubstring is absent. If @var{sub} points to a string with zero 128489857Sobrienlength, the function returns @var{string}. 128589857Sobrien 128689857Sobrien@end deftypefn 128789857Sobrien 128889857Sobrien@c strtod.c:27 128989857Sobrien@deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr}) 129089857Sobrien 129189857SobrienThis ISO C function converts the initial portion of @var{string} to a 129289857Sobrien@code{double}. If @var{endptr} is not @code{NULL}, a pointer to the 129389857Sobriencharacter after the last character used in the conversion is stored in 129489857Sobrienthe location referenced by @var{endptr}. If no conversion is 129589857Sobrienperformed, zero is returned and the value of @var{string} is stored in 129689857Sobrienthe location referenced by @var{endptr}. 129789857Sobrien 129889857Sobrien@end deftypefn 129989857Sobrien 1300218822Sdim@c strerror.c:729 130189857Sobrien@deftypefn Extension int strtoerrno (const char *@var{name}) 130289857Sobrien 130389857SobrienGiven the symbolic name of a error number (e.g., @code{EACCES}), map it 130489857Sobriento an errno value. If no translation is found, returns 0. 130589857Sobrien 130689857Sobrien@end deftypefn 130789857Sobrien 130889857Sobrien@c strtol.c:33 130989857Sobrien@deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base}) 131089857Sobrien@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base}) 131189857Sobrien 131289857SobrienThe @code{strtol} function converts the string in @var{string} to a 131389857Sobrienlong integer value according to the given @var{base}, which must be 131489857Sobrienbetween 2 and 36 inclusive, or be the special value 0. If @var{base} 131589857Sobrienis 0, @code{strtol} will look for the prefixes @code{0} and @code{0x} 131689857Sobriento indicate bases 8 and 16, respectively, else default to base 10. 131789857SobrienWhen the base is 16 (either explicitly or implicitly), a prefix of 131889857Sobrien@code{0x} is allowed. The handling of @var{endptr} is as that of 131989857Sobrien@code{strtod} above. The @code{strtoul} function is the same, except 132089857Sobrienthat the converted value is unsigned. 132189857Sobrien 132289857Sobrien@end deftypefn 132389857Sobrien 1324218822Sdim@c strsignal.c:500 132589857Sobrien@deftypefn Extension int strtosigno (const char *@var{name}) 132689857Sobrien 132789857SobrienGiven the symbolic name of a signal, map it to a signal number. If no 132889857Sobrientranslation is found, returns 0. 132989857Sobrien 133089857Sobrien@end deftypefn 133189857Sobrien 1332218822Sdim@c strverscmp.c:25 1333218822Sdim@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2}) 1334218822SdimThe @code{strverscmp} function compares the string @var{s1} against 1335218822Sdim@var{s2}, considering them as holding indices/version numbers. Return 1336218822Sdimvalue follows the same conventions as found in the @code{strverscmp} 1337218822Sdimfunction. In fact, if @var{s1} and @var{s2} contain no digits, 1338218822Sdim@code{strverscmp} behaves like @code{strcmp}. 1339218822Sdim 1340218822SdimBasically, we compare strings normally (character by character), until 1341218822Sdimwe find a digit in each string - then we enter a special comparison 1342218822Sdimmode, where each sequence of digits is taken as a whole. If we reach the 1343218822Sdimend of these two parts without noticing a difference, we return to the 1344218822Sdimstandard comparison mode. There are two types of numeric parts: 1345218822Sdim"integral" and "fractional" (those begin with a '0'). The types 1346218822Sdimof the numeric parts affect the way we sort them: 1347218822Sdim 1348218822Sdim@itemize @bullet 1349218822Sdim@item 1350218822Sdimintegral/integral: we compare values as you would expect. 1351218822Sdim 1352218822Sdim@item 1353218822Sdimfractional/integral: the fractional part is less than the integral one. 1354218822SdimAgain, no surprise. 1355218822Sdim 1356218822Sdim@item 1357218822Sdimfractional/fractional: the things become a bit more complex. 1358218822SdimIf the common prefix contains only leading zeroes, the longest part is less 1359218822Sdimthan the other one; else the comparison behaves normally. 1360218822Sdim@end itemize 1361218822Sdim 1362218822Sdim@smallexample 1363218822Sdimstrverscmp ("no digit", "no digit") 1364218822Sdim @result{} 0 // @r{same behavior as strcmp.} 1365218822Sdimstrverscmp ("item#99", "item#100") 1366218822Sdim @result{} <0 // @r{same prefix, but 99 < 100.} 1367218822Sdimstrverscmp ("alpha1", "alpha001") 1368218822Sdim @result{} >0 // @r{fractional part inferior to integral one.} 1369218822Sdimstrverscmp ("part1_f012", "part1_f01") 1370218822Sdim @result{} >0 // @r{two fractional parts.} 1371218822Sdimstrverscmp ("foo.009", "foo.0") 1372218822Sdim @result{} <0 // @r{idem, but with leading zeroes only.} 1373218822Sdim@end smallexample 1374218822Sdim 1375218822SdimThis function is especially useful when dealing with filename sorting, 1376218822Sdimbecause filenames frequently hold indices/version numbers. 1377218822Sdim@end deftypefun 1378218822Sdim 137989857Sobrien@c tmpnam.c:3 138089857Sobrien@deftypefn Supplemental char* tmpnam (char *@var{s}) 138189857Sobrien 138289857SobrienThis function attempts to create a name for a temporary file, which 138389857Sobrienwill be a valid file name yet not exist when @code{tmpnam} checks for 138489857Sobrienit. @var{s} must point to a buffer of at least @code{L_tmpnam} bytes, 138589857Sobrienor be @code{NULL}. Use of this function creates a security risk, and it must 138689857Sobriennot be used in new projects. Use @code{mkstemp} instead. 138789857Sobrien 138889857Sobrien@end deftypefn 138989857Sobrien 1390218822Sdim@c unlink-if-ordinary.c:27 1391218822Sdim@deftypefn Supplemental int unlink_if_ordinary (const char*) 1392218822Sdim 1393218822SdimUnlinks the named file, unless it is special (e.g. a device file). 1394218822SdimReturns 0 when the file was unlinked, a negative value (and errno set) when 1395218822Sdimthere was an error deleting the file, and a positive value if no attempt 1396218822Sdimwas made to unlink the file because it is special. 1397218822Sdim 1398218822Sdim@end deftypefn 1399218822Sdim 1400218822Sdim@c fopen_unlocked.c:31 1401218822Sdim@deftypefn Extension void unlock_std_streams (void) 1402218822Sdim 1403218822SdimIf the OS supports it, ensure that the standard I/O streams, 1404218822Sdim@code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any 1405218822Sdimmulti-threaded locking. Otherwise do nothing. 1406218822Sdim 1407218822Sdim@end deftypefn 1408218822Sdim 1409218822Sdim@c fopen_unlocked.c:23 1410218822Sdim@deftypefn Extension void unlock_stream (FILE * @var{stream}) 1411218822Sdim 1412218822SdimIf the OS supports it, ensure that the supplied stream is setup to 1413218822Sdimavoid any multi-threaded locking. Otherwise leave the @code{FILE} 1414218822Sdimpointer unchanged. If the @var{stream} is @code{NULL} do nothing. 1415218822Sdim 1416218822Sdim@end deftypefn 1417218822Sdim 1418218822Sdim@c vasprintf.c:47 141989857Sobrien@deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args}) 142089857Sobrien 142189857SobrienLike @code{vsprintf}, but instead of passing a pointer to a buffer, 142289857Sobrienyou pass a pointer to a pointer. This function will compute the size 142389857Sobrienof the buffer needed, allocate memory with @code{malloc}, and store a 142489857Sobrienpointer to the allocated memory in @code{*@var{resptr}}. The value 142589857Sobrienreturned is the same as @code{vsprintf} would return. If memory could 1426130561Sobriennot be allocated, minus one is returned and @code{NULL} is stored in 142789857Sobrien@code{*@var{resptr}}. 142889857Sobrien 142989857Sobrien@end deftypefn 143089857Sobrien 143189857Sobrien@c vfork.c:6 143289857Sobrien@deftypefn Supplemental int vfork (void) 143389857Sobrien 143489857SobrienEmulates @code{vfork} by calling @code{fork} and returning its value. 143589857Sobrien 143689857Sobrien@end deftypefn 143789857Sobrien 143889857Sobrien@c vprintf.c:3 143989857Sobrien@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap}) 144089857Sobrien@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap}) 144189857Sobrien@deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap}) 144289857Sobrien 144389857SobrienThese functions are the same as @code{printf}, @code{fprintf}, and 144489857Sobrien@code{sprintf}, respectively, except that they are called with a 144589857Sobrien@code{va_list} instead of a variable number of arguments. Note that 144689857Sobrienthey do not call @code{va_end}; this is the application's 144789857Sobrienresponsibility. In @libib{} they are implemented in terms of the 144889857Sobriennonstandard but common function @code{_doprnt}. 144989857Sobrien 145089857Sobrien@end deftypefn 145189857Sobrien 1452130561Sobrien@c vsnprintf.c:28 1453130561Sobrien@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap}) 1454130561Sobrien 1455130561SobrienThis function is similar to vsprintf, but it will print at most 1456130561Sobrien@var{n} characters. On error the return value is -1, otherwise it 1457130561Sobrienreturns the number of characters that would have been printed had 1458130561Sobrien@var{n} been sufficiently large, regardless of the actual value of 1459130561Sobrien@var{n}. Note some pre-C99 system libraries do not implement this 1460130561Sobriencorrectly so users cannot generally rely on the return value if the 1461130561Sobriensystem version of this function is used. 1462130561Sobrien 1463130561Sobrien@end deftypefn 1464130561Sobrien 146589857Sobrien@c waitpid.c:3 146689857Sobrien@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int) 146789857Sobrien 146889857SobrienThis is a wrapper around the @code{wait} function. Any ``special'' 146989857Sobrienvalues of @var{pid} depend on your implementation of @code{wait}, as 147089857Sobriendoes the return value. The third argument is unused in @libib{}. 147189857Sobrien 147289857Sobrien@end deftypefn 147389857Sobrien 147489857Sobrien@c xatexit.c:11 147589857Sobrien@deftypefun int xatexit (void (*@var{fn}) (void)) 147689857Sobrien 147789857SobrienBehaves as the standard @code{atexit} function, but with no limit on 147889857Sobrienthe number of registered functions. Returns 0 on success, or @minus{}1 on 147989857Sobrienfailure. If you use @code{xatexit} to register functions, you must use 148089857Sobrien@code{xexit} to terminate your program. 148189857Sobrien 148289857Sobrien@end deftypefun 148389857Sobrien 148489857Sobrien@c xmalloc.c:38 148589857Sobrien@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize}) 148689857Sobrien 148789857SobrienAllocate memory without fail, and set it to zero. This routine functions 148889857Sobrienlike @code{calloc}, but will behave the same as @code{xmalloc} if memory 148989857Sobriencannot be found. 149089857Sobrien 149189857Sobrien@end deftypefn 149289857Sobrien 149389857Sobrien@c xexit.c:22 149489857Sobrien@deftypefn Replacement void xexit (int @var{code}) 149589857Sobrien 149689857SobrienTerminates the program. If any functions have been registered with 149789857Sobrienthe @code{xatexit} replacement function, they will be called first. 149889857SobrienTermination is handled via the system's normal @code{exit} call. 149989857Sobrien 150089857Sobrien@end deftypefn 150189857Sobrien 150289857Sobrien@c xmalloc.c:22 150389857Sobrien@deftypefn Replacement void* xmalloc (size_t) 150489857Sobrien 150589857SobrienAllocate memory without fail. If @code{malloc} fails, this will print 150689857Sobriena message to @code{stderr} (using the name set by 150789857Sobrien@code{xmalloc_set_program_name}, 150889857Sobrienif any) and then call @code{xexit}. Note that it is therefore safe for 150989857Sobriena program to contain @code{#define malloc xmalloc} in its source. 151089857Sobrien 151189857Sobrien@end deftypefn 151289857Sobrien 151389857Sobrien@c xmalloc.c:53 151489857Sobrien@deftypefn Replacement void xmalloc_failed (size_t) 151589857Sobrien 151689857SobrienThis function is not meant to be called by client code, and is listed 151789857Sobrienhere for completeness only. If any of the allocation routines fail, this 151889857Sobrienfunction will be called to print an error message and terminate execution. 151989857Sobrien 152089857Sobrien@end deftypefn 152189857Sobrien 152289857Sobrien@c xmalloc.c:46 152389857Sobrien@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name}) 152489857Sobrien 152589857SobrienYou can use this to set the name of the program used by 152689857Sobrien@code{xmalloc_failed} when printing a failure message. 152789857Sobrien 152889857Sobrien@end deftypefn 152989857Sobrien 153089857Sobrien@c xmemdup.c:7 153189857Sobrien@deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size}) 153289857Sobrien 153389857SobrienDuplicates a region of memory without fail. First, @var{alloc_size} bytes 153489857Sobrienare allocated, then @var{copy_size} bytes from @var{input} are copied into 153589857Sobrienit, and the new memory is returned. If fewer bytes are copied than were 153689857Sobrienallocated, the remaining memory is zeroed. 153789857Sobrien 153889857Sobrien@end deftypefn 153989857Sobrien 154089857Sobrien@c xmalloc.c:32 154189857Sobrien@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size}) 154289857SobrienReallocate memory without fail. This routine functions like @code{realloc}, 154389857Sobrienbut will behave the same as @code{xmalloc} if memory cannot be found. 154489857Sobrien 154589857Sobrien@end deftypefn 154689857Sobrien 154789857Sobrien@c xstrdup.c:7 154889857Sobrien@deftypefn Replacement char* xstrdup (const char *@var{s}) 154989857Sobrien 155089857SobrienDuplicates a character string without fail, using @code{xmalloc} to 155189857Sobrienobtain memory. 155289857Sobrien 155389857Sobrien@end deftypefn 155489857Sobrien 155589857Sobrien@c xstrerror.c:7 155689857Sobrien@deftypefn Replacement char* xstrerror (int @var{errnum}) 155789857Sobrien 155889857SobrienBehaves exactly like the standard @code{strerror} function, but 155989857Sobrienwill never return a @code{NULL} pointer. 156089857Sobrien 156189857Sobrien@end deftypefn 156289857Sobrien 1563218822Sdim@c xstrndup.c:23 1564218822Sdim@deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n}) 156589857Sobrien 1566218822SdimReturns a pointer to a copy of @var{s} with at most @var{n} characters 1567218822Sdimwithout fail, using @code{xmalloc} to obtain memory. The result is 1568218822Sdimalways NUL terminated. 1569218822Sdim 1570218822Sdim@end deftypefn 1571218822Sdim 1572218822Sdim 1573