116288Salanb@c Automatically generated from *.c and others (the comments before 216710Smchung@c each entry tell you which file and where in that file). DO NOT EDIT! 316288Salanb@c Edit the *.c files, configure with --enable-maintainer-mode, 416288Salanb@c run 'make stamp-functions' and gather-docs will build a new copy. 516288Salanb 616288Salanb@c alloca.c:26 716288Salanb@deftypefn Replacement void* alloca (size_t @var{size}) 816288Salanb 916288SalanbThis function allocates memory which will be automatically reclaimed 1016288Salanbafter the procedure exits. The @libib{} implementation does not free 1116288Salanbthe memory immediately but will do so eventually during subsequent 1216288Salanbcalls to this function. Memory is allocated using @code{xmalloc} under 1316288Salanbnormal circumstances. 1416288Salanb 1516288SalanbThe header file @file{alloca-conf.h} can be used in conjunction with the 1616288SalanbGNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make 1716288Salanbavailable this function. The @code{AC_FUNC_ALLOCA} test requires that 1816288Salanbclient code use a block of preprocessor code to be safe (see the Autoconf 1916288Salanbmanual for more); this header incorporates that logic and more, including 2016288Salanbthe possibility of a GCC built-in function. 2116288Salanb 2216288Salanb@end deftypefn 2316288Salanb 2416288Salanb@c asprintf.c:32 2516288Salanb@deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...) 2616288Salanb 2716288SalanbLike @code{sprintf}, but instead of passing a pointer to a buffer, you 2816288Salanbpass a pointer to a pointer. This function will compute the size of 2916288Salanbthe buffer needed, allocate memory with @code{malloc}, and store a 3016288Salanbpointer to the allocated memory in @code{*@var{resptr}}. The value 3117549Salanbreturned is the same as @code{sprintf} would return. If memory could 3216288Salanbnot be allocated, minus one is returned and @code{NULL} is stored in 3316598Smchung@code{*@var{resptr}}. 3416598Smchung 3516598Smchung@end deftypefn 3616598Smchung 3716598Smchung@c atexit.c:6 3817408Salanb@deftypefn Supplemental int atexit (void (*@var{f})()) 3917408Salanb 4017408SalanbCauses function @var{f} to be called at exit. Returns 0. 4117549Salanb 4217408Salanb@end deftypefn 4316288Salanb 4416288Salanb@c basename.c:6 4517549Salanb@deftypefn Supplemental char* basename (const char *@var{name}) 4616288Salanb 4716288SalanbReturns a pointer to the last component of pathname @var{name}. 4816355SredestadBehavior is undefined if the pathname ends in a directory separator. 4917549Salanb 5016288Salanb@end deftypefn 5116288Salanb 5217408Salanb@c bcmp.c:6 5317408Salanb@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count}) 5416288Salanb 5516288SalanbCompares the first @var{count} bytes of two areas of memory. Returns 5616288Salanbzero if they are the same, nonzero otherwise. Returns zero if 5717549Salanb@var{count} is zero. A nonzero result only indicates a difference, 5817408Salanbit does not indicate any sorting order (say, by having a positive 5916288Salanbresult mean @var{x} sorts before @var{y}). 6016288Salanb 6116710Smchung@end deftypefn 6216710Smchung 6317549Salanb@c bcopy.c:3 6417408Salanb@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length}) 6516288Salanb 6616288SalanbCopies @var{length} bytes from memory region @var{in} to region 6716288Salanb@var{out}. The use of @code{bcopy} is deprecated in new programs. 6817549Salanb 6916288Salanb@end deftypefn 7016937Salanb 7116710Smchung@c bsearch.c:33 7216710Smchung@deftypefn Supplemental void* bsearch (const void *@var{key}, @ 7316710Smchung const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, @ 7416288Salanb int (*@var{compar})(const void *, const void *)) 7516288Salanb 7616288SalanbPerforms a search over an array of @var{nmemb} elements pointed to by 7716288Salanb@var{base} for a member that matches the object pointed to by @var{key}. 7816288SalanbThe size of each member is specified by @var{size}. The array contents 7916288Salanbshould be sorted in ascending order according to the @var{compar} 8016598Smchungcomparison function. This routine should take two arguments pointing to 8117549Salanbthe @var{key} and to an array member, in that order, and should return an 8216288Salanbinteger less than, equal to, or greater than zero if the @var{key} object 8316288Salanbis respectively less than, matching, or greater than the array member. 8416288Salanb 8516288Salanb@end deftypefn 8616288Salanb 8716288Salanb@c bsearch_r.c:33 8817549Salanb@deftypefn Supplemental void* bsearch_r (const void *@var{key}, @ 8917549Salanb const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, @ 9017549Salanb int (*@var{compar})(const void *, const void *, void *), void *@var{arg}) 9117549Salanb 9216288SalanbPerforms a search over an array of @var{nmemb} elements pointed to by 9317549Salanb@var{base} for a member that matches the object pointed to by @var{key}. 9417549SalanbThe size of each member is specified by @var{size}. The array contents 9516288Salanbshould be sorted in ascending order according to the @var{compar} 9617549Salanbcomparison function. This routine should take three arguments: the first 9717549Salanbtwo point to the @var{key} and to an array member, and the last is passed 9816288Salanbdown unchanged from @code{bsearch_r}'s last argument. It should return an 9917549Salanbinteger less than, equal to, or greater than zero if the @var{key} object 10016288Salanbis respectively less than, matching, or greater than the array member. 10116288Salanb 10216288Salanb@end deftypefn 10317549Salanb 10417549Salanb@c argv.c:138 10517549Salanb@deftypefn Extension char** buildargv (char *@var{sp}) 10617549Salanb 10717549SalanbGiven a pointer to a string, parse the string extracting fields 10817549Salanbseparated by whitespace and optionally enclosed within either single 10917549Salanbor double quotes (which are stripped off), and build a vector of 11017549Salanbpointers to copies of the string for each field. The input string 11117549Salanbremains unchanged. The last element of the vector is followed by a 11216288Salanb@code{NULL} element. 11316288Salanb 11417549SalanbAll of the memory for the pointer array and copies of the string 11516288Salanbis obtained from @code{xmalloc}. All of the memory can be returned to the 11616288Salanbsystem with the single function call @code{freeargv}, which takes the 11716288Salanbreturned result of @code{buildargv}, as it's argument. 11816288Salanb 11916288SalanbReturns a pointer to the argument vector if successful. Returns 12016288Salanb@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient 12116288Salanbmemory to complete building the argument vector. 12216288Salanb 12316288SalanbIf the input is a null string (as opposed to a @code{NULL} pointer), 12416288Salanbthen buildarg returns an argument vector that has one arg, a null 12516288Salanbstring. 12616288Salanb 12716288Salanb@end deftypefn 12816288Salanb 12916288Salanb@c bzero.c:6 13016288Salanb@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count}) 13116288Salanb 13216288SalanbZeros @var{count} bytes starting at @var{mem}. Use of this function 13316288Salanbis deprecated in favor of @code{memset}. 13416288Salanb 13516288Salanb@end deftypefn 13616598Smchung 13716598Smchung@c calloc.c:6 13816598Smchung@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize}) 13916598Smchung 14016598SmchungUses @code{malloc} to allocate storage for @var{nelem} objects of 14116710Smchung@var{elsize} bytes each, then zeros the memory. 14216710Smchung 14316710Smchung@end deftypefn 14416710Smchung 14516710Smchung@c filename_cmp.c:201 14616288Salanb@deftypefn Extension int canonical_filename_eq (const char *@var{a}, const char *@var{b}) 14716598Smchung 14816598SmchungReturn non-zero if file names @var{a} and @var{b} are equivalent. 14917549SalanbThis function compares the canonical versions of the filenames as returned by 15016288Salanb@code{lrealpath()}, so that so that different file names pointing to the same 15116288Salanbunderlying file are treated as being identical. 15216288Salanb 15316288Salanb@end deftypefn 15416288Salanb 15516288Salanb@c choose-temp.c:45 15616288Salanb@deftypefn Extension char* choose_temp_base (void) 15716288Salanb 15816288SalanbReturn a prefix for temporary file names or @code{NULL} if unable to 15917549Salanbfind one. The current directory is chosen if all else fails so the 16017549Salanbprogram is exited if a temporary directory can't be found (@code{mktemp} 16117549Salanbfails). The buffer for the result is obtained with @code{xmalloc}. 16217549Salanb 16317549SalanbThis function is provided for backwards compatibility only. Its use is 16417549Salanbnot recommended. 16517549Salanb 16617549Salanb@end deftypefn 16717549Salanb 16817549Salanb@c make-temp-file.c:95 16917549Salanb@deftypefn Replacement const char* choose_tmpdir () 17016288Salanb 17117549SalanbReturns a pointer to a directory path suitable for creating temporary 17217549Salanbfiles in. 17317549Salanb 17417549Salanb@end deftypefn 17517549Salanb 17617549Salanb@c clock.c:27 17717549Salanb@deftypefn Supplemental long clock (void) 17817549Salanb 17917549SalanbReturns an approximation of the CPU time used by the process as a 18017549Salanb@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the 18117549Salanbnumber of seconds used. 18216288Salanb 18316598Smchung@end deftypefn 18416598Smchung 18516288Salanb@c concat.c:24 18617549Salanb@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @ 18716288Salanb @dots{}, @code{NULL}) 18817549Salanb 18916288SalanbConcatenate zero or more of strings and return the result in freshly 19016288Salanb@code{xmalloc}ed memory. The argument list is terminated by the first 19116288Salanb@code{NULL} pointer encountered. Pointers to empty strings are ignored. 19217549Salanb 19316288Salanb@end deftypefn 19417549Salanb 19517549Salanb@c argv.c:495 19617549Salanb@deftypefn Extension int countargv (char * const *@var{argv}) 19717549Salanb 19817549SalanbReturn the number of elements in @var{argv}. 19917549SalanbReturns zero if @var{argv} is NULL. 20017549Salanb 20117549Salanb@end deftypefn 20217549Salanb 20317549Salanb@c crc32.c:140 20417549Salanb@deftypefn Extension {unsigned int} crc32 (const unsigned char *@var{buf}, @ 20517549Salanb int @var{len}, unsigned int @var{init}) 20617549Salanb 20717549SalanbCompute the 32-bit CRC of @var{buf} which has length @var{len}. The 20817549Salanbstarting value is @var{init}; this may be used to compute the CRC of 20916288Salanbdata split across multiple buffers by passing the return value of each 21016598Smchungcall as the @var{init} parameter of the next. 21116288Salanb 21216288SalanbThis is used by the @command{gdb} remote protocol for the @samp{qCRC} 21316288Salanbcommand. In order to get the same results as gdb for a block of data, 21416288Salanbyou must pass the first CRC parameter as @code{0xffffffff}. 21516288Salanb 21616288SalanbThis CRC can be specified as: 21717549Salanb 21817549Salanb Width : 32 21917549Salanb Poly : 0x04c11db7 22017549Salanb Init : parameter, typically 0xffffffff 22117549Salanb RefIn : false 22217549Salanb RefOut : false 22317549Salanb XorOut : 0 22417549Salanb 22517549SalanbThis differs from the "standard" CRC-32 algorithm in that the values 22617549Salanbare not reflected, and there is no final XOR value. These differences 22717549Salanbmake it easy to compose the values of multiple blocks. 22817549Salanb 22917549Salanb@end deftypefn 23017549Salanb 23117549Salanb@c argv.c:59 23217549Salanb@deftypefn Extension char** dupargv (char * const *@var{vector}) 23317549Salanb 23417549SalanbDuplicate an argument vector. Simply scans through @var{vector}, 23517549Salanbduplicating each argument until the terminating @code{NULL} is found. 23617549SalanbReturns a pointer to the argument vector if successful. Returns 23717549Salanb@code{NULL} if there is insufficient memory to complete building the 23817549Salanbargument vector. 23917549Salanb 24017549Salanb@end deftypefn 24117549Salanb 24217549Salanb@c strerror.c:572 24317549Salanb@deftypefn Extension int errno_max (void) 24417549Salanb 24517549SalanbReturns the maximum @code{errno} value for which a corresponding 24617549Salanbsymbolic name or message is available. Note that in the case where we 24717549Salanbuse the @code{sys_errlist} supplied by the system, it is possible for 24817549Salanbthere to be more symbolic names than messages, or vice versa. In 24917549Salanbfact, the manual page for @code{perror(3C)} explicitly warns that one 25017549Salanbshould check the size of the table (@code{sys_nerr}) before indexing 25117549Salanbit, since new error codes may be added to the system before they are 25217549Salanbadded to the table. Thus @code{sys_nerr} might be smaller than value 25317549Salanbimplied by the largest @code{errno} value defined in @code{<errno.h>}. 25417549Salanb 25517549SalanbWe return the maximum value that can be used to obtain a meaningful 25617549Salanbsymbolic name or message. 25717549Salanb 25817549Salanb@end deftypefn 25917549Salanb 26017549Salanb@c argv.c:352 26117549Salanb@deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp}) 26217549Salanb 26317549SalanbThe @var{argcp} and @code{argvp} arguments are pointers to the usual 26417549Salanb@code{argc} and @code{argv} arguments to @code{main}. This function 26517549Salanblooks for arguments that begin with the character @samp{@@}. Any such 26617549Salanbarguments are interpreted as ``response files''. The contents of the 26717549Salanbresponse file are interpreted as additional command line options. In 26817549Salanbparticular, the file is separated into whitespace-separated strings; 26917549Salanbeach such string is taken as a command-line option. The new options 27017549Salanbare inserted in place of the option naming the response file, and 27117549Salanb@code{*argcp} and @code{*argvp} will be updated. If the value of 27217549Salanb@code{*argvp} is modified by this function, then the new value has 27317549Salanbbeen dynamically allocated and can be deallocated by the caller with 27417549Salanb@code{freeargv}. However, most callers will simply call 27517549Salanb@code{expandargv} near the beginning of @code{main} and allow the 27617549Salanboperating system to free the memory when the program exits. 27717549Salanb 27817549Salanb@end deftypefn 27916288Salanb 28017549Salanb@c fdmatch.c:23 28117549Salanb@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2}) 28217549Salanb 28317549SalanbCheck to see if two open file descriptors refer to the same file. 28417549SalanbThis is useful, for example, when we have an open file descriptor for 28517549Salanban unnamed file, and the name of a file that we believe to correspond 28617549Salanbto that fd. This can happen when we are exec'd with an already open 28717549Salanbfile (@code{stdout} for example) or from the SVR4 @file{/proc} calls 28817549Salanbthat return open file descriptors for mapped address spaces. All we 28917549Salanbhave to do is open the file by name and check the two file descriptors 29017549Salanbfor a match, which is done by comparing major and minor device numbers 29117549Salanband inode numbers. 29217549Salanb 29317549Salanb@end deftypefn 29417549Salanb 29517549Salanb@c fopen_unlocked.c:49 29617549Salanb@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, @ 29717549Salanb const char * @var{mode}) 29817549Salanb 29917549SalanbOpens and returns a @code{FILE} pointer via @code{fdopen}. If the 30016288Salanboperating system supports it, ensure that the stream is setup to avoid 30117549Salanbany multi-threaded locking. Otherwise return the @code{FILE} pointer 30217549Salanbunchanged. 30317549Salanb 30417549Salanb@end deftypefn 30517549Salanb 30617549Salanb@c ffs.c:3 30717549Salanb@deftypefn Supplemental int ffs (int @var{valu}) 30817549Salanb 30917549SalanbFind the first (least significant) bit set in @var{valu}. Bits are 31017549Salanbnumbered from right to left, starting with bit 1 (corresponding to the 31117549Salanbvalue 1). If @var{valu} is zero, zero is returned. 31217549Salanb 31317549Salanb@end deftypefn 31417549Salanb 31517549Salanb@c filename_cmp.c:37 31617549Salanb@deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2}) 31717549Salanb 31817549SalanbReturn zero if the two file names @var{s1} and @var{s2} are equivalent. 31917549SalanbIf not equivalent, the returned value is similar to what @code{strcmp} 32017549Salanbwould return. In other words, it returns a negative value if @var{s1} 32117549Salanbis less than @var{s2}, or a positive value if @var{s2} is greater than 32217549Salanb@var{s2}. 32317549Salanb 32417549SalanbThis function does not normalize file names. As a result, this function 32517549Salanbwill treat filenames that are spelled differently as different even in 32617549Salanbthe case when the two filenames point to the same underlying file. 32717549SalanbHowever, it does handle the fact that on DOS-like file systems, forward 32817549Salanband backward slashes are equal. 32917549Salanb 33017549Salanb@end deftypefn 33116288Salanb 33216288Salanb@c filename_cmp.c:183 33316598Smchung@deftypefn Extension int filename_eq (const void *@var{s1}, const void *@var{s2}) 33417549Salanb 33516598SmchungReturn non-zero if file names @var{s1} and @var{s2} are equivalent. 33616598SmchungThis function is for use with hashtab.c hash tables. 33716710Smchung 33816598Smchung@end deftypefn 33916288Salanb 34017549Salanb@c filename_cmp.c:152 34117549Salanb@deftypefn Extension hashval_t filename_hash (const void *@var{s}) 34216288Salanb 34317549SalanbReturn the hash value for file name @var{s} that will be compared 34417549Salanbusing filename_cmp. 34516710SmchungThis function is for use with hashtab.c hash tables. 34616710Smchung 34716710Smchung@end deftypefn 34816710Smchung 34916288Salanb@c filename_cmp.c:94 35016288Salanb@deftypefn Extension int filename_ncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) 35116288Salanb 35216288SalanbReturn zero if the two file names @var{s1} and @var{s2} are equivalent 35316598Smchungin range @var{n}. 35416710SmchungIf not equivalent, the returned value is similar to what @code{strncmp} 35516710Smchungwould return. In other words, it returns a negative value if @var{s1} 35616710Smchungis less than @var{s2}, or a positive value if @var{s2} is greater than 35716288Salanb@var{s2}. 35816288Salanb 35916288SalanbThis function does not normalize file names. As a result, this function 36016598Smchungwill treat filenames that are spelled differently as different even in 36116598Smchungthe case when the two filenames point to the same underlying file. 36216598SmchungHowever, it does handle the fact that on DOS-like file systems, forward 36316598Smchungand backward slashes are equal. 36416598Smchung 36516598Smchung@end deftypefn 36616598Smchung 36716598Smchung@c fnmatch.txh:1 36816598Smchung@deftypefn Replacement int fnmatch (const char *@var{pattern}, @ 36916598Smchung const char *@var{string}, int @var{flags}) 37016598Smchung 37116937SalanbMatches @var{string} against @var{pattern}, returning zero if it 37216937Salanbmatches, @code{FNM_NOMATCH} if not. @var{pattern} may contain the 37316937Salanbwildcards @code{?} to match any one character, @code{*} to match any 37416937Salanbzero or more characters, or a set of alternate characters in square 37516598Smchungbrackets, like @samp{[a-gt8]}, which match one character (@code{a} 37616598Smchungthrough @code{g}, or @code{t}, or @code{8}, in this example) if that one 37716598Smchungcharacter is in the set. A set may be inverted (i.e., match anything 37816598Smchungexcept what's in the set) by giving @code{^} or @code{!} as the first 37916598Smchungcharacter in the set. To include those characters in the set, list them 38016598Smchungas anything other than the first character of the set. To include a 38116288Salanbdash in the set, list it last in the set. A backslash character makes 38216288Salanbthe following character not special, so for example you could match 38316288Salanbagainst a literal asterisk with @samp{\*}. To match a literal 38416288Salanbbackslash, use @samp{\\}. 38516288Salanb 38616288Salanb@code{flags} controls various aspects of the matching process, and is a 38716288Salanbboolean OR of zero or more of the following values (defined in 38816288Salanb@code{<fnmatch.h>}): 38916288Salanb 39016288Salanb@table @code 39116288Salanb 39216288Salanb@item FNM_PATHNAME 39316288Salanb@itemx FNM_FILE_NAME 39416288Salanb@var{string} is assumed to be a path name. No wildcard will ever match 39516288Salanb@code{/}. 39616288Salanb 39716288Salanb@item FNM_NOESCAPE 39816288SalanbDo not interpret backslashes as quoting the following special character. 39916288Salanb 40016288Salanb@item FNM_PERIOD 40116288SalanbA leading period (at the beginning of @var{string}, or if 40216288Salanb@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or 40316288Salanb@code{?} but must be matched explicitly. 40416288Salanb 40516288Salanb@item FNM_LEADING_DIR 40616288SalanbMeans that @var{string} also matches @var{pattern} if some initial part 40716288Salanbof @var{string} matches, and is followed by @code{/} and zero or more 40816288Salanbcharacters. For example, @samp{foo*} would match either @samp{foobar} 40916288Salanbor @samp{foobar/grill}. 41016288Salanb 41116598Smchung@item FNM_CASEFOLD 41216598SmchungIgnores case when performing the comparison. 41316598Smchung 41416288Salanb@end table 41516288Salanb 41616288Salanb@end deftypefn 41716288Salanb 41816288Salanb@c fopen_unlocked.c:39 41916288Salanb@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, @ 42016288Salanb const char * @var{mode}) 42116288Salanb 42216288SalanbOpens and returns a @code{FILE} pointer via @code{fopen}. If the 42316288Salanboperating system supports it, ensure that the stream is setup to avoid 42416288Salanbany multi-threaded locking. Otherwise return the @code{FILE} pointer 42516288Salanbunchanged. 42616288Salanb 42716288Salanb@end deftypefn 42816288Salanb 42916288Salanb@c argv.c:93 43016288Salanb@deftypefn Extension void freeargv (char **@var{vector}) 43116288Salanb 43216288SalanbFree an argument vector that was built using @code{buildargv}. Simply 43316288Salanbscans through @var{vector}, freeing the memory for each argument until 43416288Salanbthe terminating @code{NULL} is found, and then frees @var{vector} 43516288Salanbitself. 43616288Salanb 43716710Smchung@end deftypefn 43816710Smchung 43916710Smchung@c fopen_unlocked.c:59 44016710Smchung@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, @ 44116710Smchung const char * @var{mode}, FILE * @var{stream}) 44216710Smchung 44316710SmchungOpens and returns a @code{FILE} pointer via @code{freopen}. If the 44416710Smchungoperating system supports it, ensure that the stream is setup to avoid 44516710Smchungany multi-threaded locking. Otherwise return the @code{FILE} pointer 44616710Smchungunchanged. 44716710Smchung 44816710Smchung@end deftypefn 44916710Smchung 45016710Smchung@c getruntime.c:86 45116710Smchung@deftypefn Replacement long get_run_time (void) 45216710Smchung 45316710SmchungReturns the time used so far, in microseconds. If possible, this is 45416710Smchungthe time used by this process, else it is the elapsed time since the 45516710Smchungprocess started. 45616710Smchung 45716710Smchung@end deftypefn 45816710Smchung 45916288Salanb@c getcwd.c:6 46017549Salanb@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len}) 46117549Salanb 46216288SalanbCopy the absolute pathname for the current working directory into 46316598Smchung@var{pathname}, which is assumed to point to a buffer of at least 46417549Salanb@var{len} bytes, and return a pointer to the buffer. If the current 46516288Salanbdirectory's path doesn't fit in @var{len} characters, the result is 46616288Salanb@code{NULL} and @code{errno} is set. If @var{pathname} is a null pointer, 46716288Salanb@code{getcwd} will obtain @var{len} bytes of space using 46817549Salanb@code{malloc}. 46916288Salanb 47016288Salanb@end deftypefn 47116710Smchung 47216710Smchung@c getpagesize.c:5 47316710Smchung@deftypefn Supplemental int getpagesize (void) 47416710Smchung 47516710SmchungReturns the number of bytes in a page of memory. This is the 47616710Smchunggranularity of many of the system memory management routines. No 47716710Smchungguarantee is made as to whether or not it is the same as the basic 47816710Smchungmemory management hardware page size. 47917549Salanb 48017549Salanb@end deftypefn 48116710Smchung 48216710Smchung@c getpwd.c:5 48316710Smchung@deftypefn Supplemental char* getpwd (void) 48416710Smchung 48516598SmchungReturns the current working directory. This implementation caches the 48616288Salanbresult on the assumption that the process will not call @code{chdir} 48716288Salanbbetween calls to @code{getpwd}. 48816288Salanb 48916710Smchung@end deftypefn 49016710Smchung 49116710Smchung@c gettimeofday.c:12 49216710Smchung@deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz}) 49317549Salanb 49417549SalanbWrites the current time to @var{tp}. This implementation requires 49516710Smchungthat @var{tz} be NULL. Returns 0 on success, -1 on failure. 49616710Smchung 49716288Salanb@end deftypefn 49816288Salanb 49916598Smchung@c hex.c:33 50016288Salanb@deftypefn Extension void hex_init (void) 50116288Salanb 50216288SalanbInitializes the array mapping the current character set to 50316598Smchungcorresponding hex values. This function must be called before any 50416598Smchungcall to @code{hex_p} or @code{hex_value}. If you fail to call it, a 50516598Smchungdefault ASCII-based table will normally be used on ASCII systems. 50616598Smchung 50716598Smchung@end deftypefn 50816598Smchung 50916598Smchung@c hex.c:42 51016598Smchung@deftypefn Extension int hex_p (int @var{c}) 51116598Smchung 51216288SalanbEvaluates to non-zero if the given character is a valid hex character, 51316288Salanbor zero if it is not. Note that the value you pass will be cast to 51416288Salanb@code{unsigned char} within the macro. 51516288Salanb 51616288Salanb@end deftypefn 51716288Salanb 51817549Salanb@c hex.c:50 51917549Salanb@deftypefn Extension {unsigned int} hex_value (int @var{c}) 52016288Salanb 52116288SalanbReturns the numeric equivalent of the given character when interpreted 52216288Salanbas a hexadecimal digit. The result is undefined if you pass an 52316288Salanbinvalid hex digit. Note that the value you pass will be cast to 52416288Salanb@code{unsigned char} within the macro. 52516288Salanb 52616288SalanbThe @code{hex_value} macro returns @code{unsigned int}, rather than 52716288Salanbsigned @code{int}, to make it easier to use in parsing addresses from 52816288Salanbhex dump files: a signed @code{int} would be sign-extended when 52916288Salanbconverted to a wider unsigned type --- like @code{bfd_vma}, on some 53016288Salanbsystems. 53116288Salanb 53216937Salanb@end deftypefn 53316937Salanb 53416937Salanb@c safe-ctype.c:24 53516937Salanb@defvr Extension HOST_CHARSET 53616288SalanbThis macro indicates the basic character set and encoding used by the 53716288Salanbhost: more precisely, the encoding used for character constants in 53816288Salanbpreprocessor @samp{#if} statements (the C "execution character set"). 53916288SalanbIt is defined by @file{safe-ctype.h}, and will be an integer constant 54016288Salanbwith one of the following values: 54116288Salanb 54216288Salanb@ftable @code 54316288Salanb@item HOST_CHARSET_UNKNOWN 54416288SalanbThe host character set is unknown - that is, not one of the next two 54516288Salanbpossibilities. 54616288Salanb 54716937Salanb@item HOST_CHARSET_ASCII 54816288SalanbThe host character set is ASCII. 54916288Salanb 55016288Salanb@item HOST_CHARSET_EBCDIC 55116288SalanbThe host character set is some variant of EBCDIC. (Only one of the 55216288Salanbnineteen EBCDIC varying characters is tested; exercise caution.) 55316288Salanb@end ftable 55417549Salanb@end defvr 55517549Salanb 55617549Salanb@c hashtab.c:327 55716288Salanb@deftypefn Supplemental htab_t htab_create_typed_alloc (size_t @var{size}, @ 55817549Salanbhtab_hash @var{hash_f}, htab_eq @var{eq_f}, htab_del @var{del_f}, @ 55916288Salanbhtab_alloc @var{alloc_tab_f}, htab_alloc @var{alloc_f}, @ 56016288Salanbhtab_free @var{free_f}) 56116288Salanb 56216288SalanbThis function creates a hash table that uses two different allocators 56316288Salanb@var{alloc_tab_f} and @var{alloc_f} to use for allocating the table itself 56416288Salanband its entries respectively. This is useful when variables of different 56516288Salanbtypes need to be allocated with different allocators. 56617549Salanb 56717549SalanbThe created hash table is slightly larger than @var{size} and it is 56817549Salanbinitially empty (all the hash table entries are @code{HTAB_EMPTY_ENTRY}). 56917549SalanbThe function returns the created hash table, or @code{NULL} if memory 57017549Salanballocation fails. 57116288Salanb 57216288Salanb@end deftypefn 57316288Salanb 57416288Salanb@c index.c:5 57516288Salanb@deftypefn Supplemental char* index (char *@var{s}, int @var{c}) 57616288Salanb 57716288SalanbReturns a pointer to the first occurrence of the character @var{c} in 57816598Smchungthe string @var{s}, or @code{NULL} if not found. The use of @code{index} is 57916598Smchungdeprecated in new programs in favor of @code{strchr}. 58016598Smchung 58116288Salanb@end deftypefn 58216598Smchung 58316288Salanb@c insque.c:6 58416288Salanb@deftypefn Supplemental void insque (struct qelem *@var{elem}, @ 58516288Salanb struct qelem *@var{pred}) 58616288Salanb@deftypefnx Supplemental void remque (struct qelem *@var{elem}) 58716288Salanb 58816288SalanbRoutines to manipulate queues built from doubly linked lists. The 58916288Salanb@code{insque} routine inserts @var{elem} in the queue immediately 59016288Salanbafter @var{pred}. The @code{remque} routine removes @var{elem} from 59116288Salanbits containing queue. These routines expect to be passed pointers to 59216288Salanbstructures which have as their first members a forward pointer and a 59316288Salanbback pointer, like this prototype (although no prototype is provided): 59416288Salanb 59516288Salanb@example 59616288Salanbstruct qelem @{ 59716288Salanb struct qelem *q_forw; 59816288Salanb struct qelem *q_back; 59916288Salanb char q_data[]; 60016288Salanb@}; 60116288Salanb@end example 60216288Salanb 60316288Salanb@end deftypefn 60417549Salanb 60517549Salanb@c safe-ctype.c:45 60616288Salanb@deffn Extension ISALPHA (@var{c}) 60717549Salanb@deffnx Extension ISALNUM (@var{c}) 60817549Salanb@deffnx Extension ISBLANK (@var{c}) 60917549Salanb@deffnx Extension ISCNTRL (@var{c}) 61017549Salanb@deffnx Extension ISDIGIT (@var{c}) 61117549Salanb@deffnx Extension ISGRAPH (@var{c}) 61217549Salanb@deffnx Extension ISLOWER (@var{c}) 61317549Salanb@deffnx Extension ISPRINT (@var{c}) 61417549Salanb@deffnx Extension ISPUNCT (@var{c}) 61517549Salanb@deffnx Extension ISSPACE (@var{c}) 61616288Salanb@deffnx Extension ISUPPER (@var{c}) 61717549Salanb@deffnx Extension ISXDIGIT (@var{c}) 61817549Salanb 61917549SalanbThese twelve macros are defined by @file{safe-ctype.h}. Each has the 62017549Salanbsame meaning as the corresponding macro (with name in lowercase) 62117549Salanbdefined by the standard header @file{ctype.h}. For example, 62216288Salanb@code{ISALPHA} returns true for alphabetic characters and false for 62317549Salanbothers. However, there are two differences between these macros and 62417549Salanbthose provided by @file{ctype.h}: 62516937Salanb 62617549Salanb@itemize @bullet 62717549Salanb@item These macros are guaranteed to have well-defined behavior for all 62817549Salanbvalues representable by @code{signed char} and @code{unsigned char}, and 62917549Salanbfor @code{EOF}. 63017549Salanb 63116937Salanb@item These macros ignore the current locale; they are true for these 63217549Salanbfixed sets of characters: 63317549Salanb@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada} 63417549Salanb@item @code{ALPHA} @tab @kbd{A-Za-z} 63517549Salanb@item @code{ALNUM} @tab @kbd{A-Za-z0-9} 63617549Salanb@item @code{BLANK} @tab @kbd{space tab} 63716937Salanb@item @code{CNTRL} @tab @code{!PRINT} 63817549Salanb@item @code{DIGIT} @tab @kbd{0-9} 63917549Salanb@item @code{GRAPH} @tab @code{ALNUM || PUNCT} 64016288Salanb@item @code{LOWER} @tab @kbd{a-z} 64117549Salanb@item @code{PRINT} @tab @code{GRAPH ||} @kbd{space} 64217549Salanb@item @code{PUNCT} @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?} 64317408Salanb@item @code{SPACE} @tab @kbd{space tab \n \r \f \v} 64416288Salanb@item @code{UPPER} @tab @kbd{A-Z} 64516288Salanb@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f} 64616288Salanb@end multitable 64716937Salanb 64817549SalanbNote that, if the host character set is ASCII or a superset thereof, 64917549Salanball these macros will return false for all values of @code{char} outside 65017549Salanbthe range of 7-bit ASCII. In particular, both ISPRINT and ISCNTRL return 65117549Salanbfalse for characters with numeric values from 128 to 255. 65217549Salanb@end itemize 65317549Salanb@end deffn 65417549Salanb 65517549Salanb@c safe-ctype.c:94 65617549Salanb@deffn Extension ISIDNUM (@var{c}) 65717549Salanb@deffnx Extension ISIDST (@var{c}) 65817549Salanb@deffnx Extension IS_VSPACE (@var{c}) 65917549Salanb@deffnx Extension IS_NVSPACE (@var{c}) 66017549Salanb@deffnx Extension IS_SPACE_OR_NUL (@var{c}) 66117549Salanb@deffnx Extension IS_ISOBASIC (@var{c}) 66217549SalanbThese six macros are defined by @file{safe-ctype.h} and provide 66317549Salanbadditional character classes which are useful when doing lexical 66417549Salanbanalysis of C or similar languages. They are true for the following 66516288Salanbsets of characters: 66617549Salanb 66717549Salanb@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada} 66817549Salanb@item @code{IDNUM} @tab @kbd{A-Za-z0-9_} 66917549Salanb@item @code{IDST} @tab @kbd{A-Za-z_} 67017549Salanb@item @code{VSPACE} @tab @kbd{\r \n} 67117549Salanb@item @code{NVSPACE} @tab @kbd{space tab \f \v \0} 67217549Salanb@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE} 67317549Salanb@item @code{ISOBASIC} @tab @code{VSPACE || NVSPACE || PRINT} 67417549Salanb@end multitable 67517549Salanb@end deffn 67617549Salanb 67717549Salanb@c lbasename.c:23 67817549Salanb@deftypefn Replacement {const char*} lbasename (const char *@var{name}) 67917549Salanb 68017549SalanbGiven a pointer to a string containing a typical pathname 68117549Salanb(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the 68217549Salanblast component of the pathname (@samp{ls.c} in this case). The 68317549Salanbreturned pointer is guaranteed to lie within the original 68417549Salanbstring. This latter fact is not true of many vendor C 68517549Salanblibraries, which return special strings or modify the passed 68617549Salanbstrings for particular input. 68717549Salanb 68817549SalanbIn particular, the empty string returns the same empty string, 68917549Salanband a path ending in @code{/} returns the empty string after it. 69017549Salanb 69117549Salanb@end deftypefn 69217549Salanb 69317549Salanb@c lrealpath.c:25 69417549Salanb@deftypefn Replacement {const char*} lrealpath (const char *@var{name}) 69517549Salanb 69617549SalanbGiven a pointer to a string containing a pathname, returns a canonical 69717549Salanbversion of the filename. Symlinks will be resolved, and ``.'' and ``..'' 69817549Salanbcomponents will be simplified. The returned value will be allocated using 69917549Salanb@code{malloc}, or @code{NULL} will be returned on a memory allocation error. 70017549Salanb 70117549Salanb@end deftypefn 70217549Salanb 70317549Salanb@c make-relative-prefix.c:23 70417549Salanb@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, @ 70517549Salanb const char *@var{bin_prefix}, const char *@var{prefix}) 70617549Salanb 70717549SalanbGiven three paths @var{progname}, @var{bin_prefix}, @var{prefix}, 70817549Salanbreturn the path that is in the same position relative to 70917549Salanb@var{progname}'s directory as @var{prefix} is relative to 71017549Salanb@var{bin_prefix}. That is, a string starting with the directory 71117549Salanbportion of @var{progname}, followed by a relative pathname of the 71217549Salanbdifference between @var{bin_prefix} and @var{prefix}. 71317549Salanb 71417549SalanbIf @var{progname} does not contain any directory separators, 71517549Salanb@code{make_relative_prefix} will search @env{PATH} to find a program 71617549Salanbnamed @var{progname}. Also, if @var{progname} is a symbolic link, 71717549Salanbthe symbolic link will be resolved. 71817549Salanb 71917549SalanbFor example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta}, 72017549Salanb@var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is 72116288Salanb@code{/red/green/blue/gcc}, then this function will return 72216288Salanb@code{/red/green/blue/../../omega/}. 72316288Salanb 72416288SalanbThe return value is normally allocated via @code{malloc}. If no 72516288Salanbrelative prefix can be found, return @code{NULL}. 72616288Salanb 72716288Salanb@end deftypefn 72816288Salanb 72916288Salanb@c make-temp-file.c:173 73016288Salanb@deftypefn Replacement char* make_temp_file (const char *@var{suffix}) 73116598Smchung 73216598SmchungReturn a temporary file name (as a string) or @code{NULL} if unable to 73316288Salanbcreate one. @var{suffix} is a suffix to append to the file name. The 73416288Salanbstring is @code{malloc}ed, and the temporary file has been created. 73516288Salanb 73616288Salanb@end deftypefn 73716288Salanb 73816288Salanb@c memchr.c:3 73916288Salanb@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, @ 74016288Salanb size_t @var{n}) 74116937Salanb 74217549SalanbThis function searches memory starting at @code{*@var{s}} for the 74316937Salanbcharacter @var{c}. The search only ends with the first occurrence of 74417549Salanb@var{c}, or after @var{length} characters; in particular, a null 74517549Salanbcharacter does not terminate the search. If the character @var{c} is 74617549Salanbfound within @var{length} characters of @code{*@var{s}}, a pointer 74716937Salanbto the character is returned. If @var{c} is not found, then @code{NULL} is 74816937Salanbreturned. 74916937Salanb 75016937Salanb@end deftypefn 75116937Salanb 75216937Salanb@c memcmp.c:6 75316937Salanb@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, @ 75416937Salanb size_t @var{count}) 75517549Salanb 75617549SalanbCompares the first @var{count} bytes of two areas of memory. Returns 75717549Salanbzero if they are the same, a value less than zero if @var{x} is 75817549Salanblexically less than @var{y}, or a value greater than zero if @var{x} 75917549Salanbis lexically greater than @var{y}. Note that lexical order is determined 76017549Salanbas if comparing unsigned char arrays. 76117549Salanb 76217549Salanb@end deftypefn 76317549Salanb 76417549Salanb@c memcpy.c:6 76517549Salanb@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, @ 76617549Salanb size_t @var{length}) 76717549Salanb 76817549SalanbCopies @var{length} bytes from memory region @var{in} to region 76917549Salanb@var{out}. Returns a pointer to @var{out}. 77017549Salanb 77117549Salanb@end deftypefn 77216937Salanb 77317549Salanb@c memmem.c:20 77416937Salanb@deftypefn Supplemental void* memmem (const void *@var{haystack}, @ 77516937Salanb size_t @var{haystack_len} const void *@var{needle}, size_t @var{needle_len}) 77616937Salanb 77717549SalanbReturns a pointer to the first occurrence of @var{needle} (length 77816937Salanb@var{needle_len}) in @var{haystack} (length @var{haystack_len}). 77916937SalanbReturns @code{NULL} if not found. 78017162Salanb 78116937Salanb@end deftypefn 78217549Salanb 78316937Salanb@c memmove.c:6 78416937Salanb@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, @ 78516937Salanb size_t @var{count}) 78616937Salanb 78716937SalanbCopies @var{count} bytes from memory area @var{from} to memory area 78816937Salanb@var{to}, returning a pointer to @var{to}. 78916937Salanb 79016937Salanb@end deftypefn 79116937Salanb 79216937Salanb@c mempcpy.c:23 79316937Salanb@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, @ 79416937Salanb size_t @var{length}) 79517549Salanb 79616288SalanbCopies @var{length} bytes from memory region @var{in} to region 79717549Salanb@var{out}. Returns a pointer to @var{out} + @var{length}. 79816288Salanb 79917549Salanb@end deftypefn 80017549Salanb 80116288Salanb@c memset.c:6 80216288Salanb@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, @ 80316288Salanb size_t @var{count}) 80416288Salanb 80516288SalanbSets the first @var{count} bytes of @var{s} to the constant byte 80616288Salanb@var{c}, returning a pointer to @var{s}. 80716288Salanb 80816288Salanb@end deftypefn 80916288Salanb 81016288Salanb@c mkstemps.c:60 81116598Smchung@deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len}) 81216598Smchung 81316288SalanbGenerate a unique temporary file name from @var{pattern}. 81416288Salanb@var{pattern} has the form: 81516288Salanb 81616288Salanb@example 81716288Salanb @var{path}/ccXXXXXX@var{suffix} 81816288Salanb@end example 81916288Salanb 82016288Salanb@var{suffix_len} tells us how long @var{suffix} is (it can be zero 82116288Salanblength). The last six characters of @var{pattern} before @var{suffix} 82216288Salanbmust be @samp{XXXXXX}; they are replaced with a string that makes the 82316288Salanbfilename unique. Returns a file descriptor open on the file for 82416937Salanbreading and writing. 82517549Salanb 82616288Salanb@end deftypefn 82717549Salanb 82816288Salanb@c pexecute.txh:278 82917549Salanb@deftypefn Extension void pex_free (struct pex_obj @var{obj}) 83016288Salanb 83116288SalanbClean up and free all data associated with @var{obj}. If you have not 83216288Salanbyet called @code{pex_get_times} or @code{pex_get_status}, this will 83316288Salanbtry to kill the subprocesses. 83416288Salanb 83516288Salanb@end deftypefn 83616288Salanb 83716288Salanb@c pexecute.txh:251 83816288Salanb@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, @ 83916288Salanb int @var{count}, int *@var{vector}) 84016288Salanb 84116598SmchungReturns the exit status of all programs run using @var{obj}. 84216288Salanb@var{count} is the number of results expected. The results will be 84316288Salanbplaced into @var{vector}. The results are in the order of the calls 84416288Salanbto @code{pex_run}. Returns 0 on error, 1 on success. 84516288Salanb 84616598Smchung@end deftypefn 84716288Salanb 84816288Salanb@c pexecute.txh:261 84916288Salanb@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, @ 85016288Salanb int @var{count}, struct pex_time *@var{vector}) 85116288Salanb 85216288SalanbReturns the process execution times of all programs run using 85316288Salanb@var{obj}. @var{count} is the number of results expected. The 85416288Salanbresults will be placed into @var{vector}. The results are in the 85516288Salanborder of the calls to @code{pex_run}. Returns 0 on error, 1 on 85616288Salanbsuccess. 85716288Salanb 85816288Salanb@code{struct pex_time} has the following fields of the type 85916288Salanb@code{unsigned long}: @code{user_seconds}, 86017408Salanb@code{user_microseconds}, @code{system_seconds}, 86117549Salanb@code{system_microseconds}. On systems which do not support reporting 86217408Salanbprocess times, all the fields will be set to @code{0}. 86317549Salanb 86417549Salanb@end deftypefn 86517549Salanb 86617549Salanb@c pexecute.txh:2 86717549Salanb@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, @ 86817549Salanb const char *@var{pname}, const char *@var{tempbase}) 86917549Salanb 87017549SalanbPrepare to execute one or more programs, with standard output of each 87117549Salanbprogram fed to standard input of the next. This is a system 87217408Salanbindependent interface to execute a pipeline. 87317408Salanb 87417408Salanb@var{flags} is a bitwise combination of the following: 87517549Salanb 87617408Salanb@table @code 87717549Salanb 87817549Salanb@vindex PEX_RECORD_TIMES 87917549Salanb@item PEX_RECORD_TIMES 88017549SalanbRecord subprocess times if possible. 88117549Salanb 88217549Salanb@vindex PEX_USE_PIPES 88317549Salanb@item PEX_USE_PIPES 88417549SalanbUse pipes for communication between processes, if possible. 88517549Salanb 88617549Salanb@vindex PEX_SAVE_TEMPS 88717549Salanb@item PEX_SAVE_TEMPS 88817549SalanbDon't delete temporary files used for communication between 88917549Salanbprocesses. 89017549Salanb 89117549Salanb@end table 89217549Salanb 89317549Salanb@var{pname} is the name of program to be executed, used in error 89417408Salanbmessages. @var{tempbase} is a base name to use for any required 89517408Salanbtemporary files; it may be @code{NULL} to use a randomly chosen name. 89617408Salanb 89717408Salanb@end deftypefn 89817408Salanb 89917408Salanb@c pexecute.txh:161 90017549Salanb@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, @ 90117549Salanb int @var{flags}, const char *@var{in_name}) 90217549Salanb 90317549SalanbReturn a stream for a temporary file to pass to the first program in 90417549Salanbthe pipeline as input. 90517549Salanb 90617549SalanbThe name of the input file is chosen according to the same rules 90717549Salanb@code{pex_run} uses to choose output file names, based on 90817549Salanb@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}. 90917549Salanb 91017549SalanbDon't call @code{fclose} on the returned stream; the first call to 91117549Salanb@code{pex_run} closes it automatically. 91217549Salanb 91317549SalanbIf @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in 91417549Salanbbinary mode; otherwise, open it in the default mode. Including 91517549Salanb@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix. 91617549Salanb@end deftypefn 91717549Salanb 91817549Salanb@c pexecute.txh:179 91917549Salanb@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, @ 92017549Salanb int @var{binary}) 92117549Salanb 92217549SalanbReturn a stream @var{fp} for a pipe connected to the standard input of 92317549Salanbthe first program in the pipeline; @var{fp} is opened for writing. 92417549SalanbYou must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call 92517408Salanbthat returned @var{obj}. 92617408Salanb 92717408SalanbYou must close @var{fp} using @code{fclose} yourself when you have 92817408Salanbfinished writing data to the pipeline. 92917408Salanb 93017549SalanbThe file descriptor underlying @var{fp} is marked not to be inherited 93117549Salanbby child processes. 93217408Salanb 93317408SalanbOn systems that do not support pipes, this function returns 93417408Salanb@code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would 93517549Salanblike to write code that is portable to all systems the @code{pex} 93617408Salanbfunctions support, consider using @code{pex_input_file} instead. 93717549Salanb 93817549SalanbThere are two opportunities for deadlock using 93917549Salanb@code{pex_input_pipe}: 94017549Salanb 94117408Salanb@itemize @bullet 94217549Salanb@item 94317408SalanbMost systems' pipes can buffer only a fixed amount of data; a process 94417408Salanbthat writes to a full pipe blocks. Thus, if you write to @file{fp} 94517408Salanbbefore starting the first process, you run the risk of blocking when 94617408Salanbthere is no child process yet to read the data and allow you to 94717408Salanbcontinue. @code{pex_input_pipe} makes no promises about the 94817408Salanbsize of the pipe's buffer, so if you need to write any data at all 94917408Salanbbefore starting the first process in the pipeline, consider using 95017408Salanb@code{pex_input_file} instead. 95117408Salanb 95217408Salanb@item 95317408SalanbUsing @code{pex_input_pipe} and @code{pex_read_output} together 95417408Salanbmay also cause deadlock. If the output pipe fills up, so that each 95517408Salanbprogram in the pipeline is waiting for the next to read more data, and 95617408Salanbyou fill the input pipe by writing more data to @var{fp}, then there 95717408Salanbis no way to make progress: the only process that could read data from 95817408Salanbthe output pipe is you, but you are blocked on the input pipe. 95917408Salanb 96017408Salanb@end itemize 96117408Salanb 96217408Salanb@end deftypefn 96317549Salanb 96417549Salanb@c pexecute.txh:286 96517549Salanb@deftypefn Extension {const char *} pex_one (int @var{flags}, @ 96617549Salanb const char *@var{executable}, char * const *@var{argv}, @ 96717549Salanb const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, @ 96816288Salanb int *@var{status}, int *@var{err}) 96917549Salanb 97017549SalanbAn interface to permit the easy execution of a 97117549Salanbsingle program. The return value and most of the parameters are as 97217549Salanbfor a call to @code{pex_run}. @var{flags} is restricted to a 97317549Salanbcombination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and 97417549Salanb@code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if 97517549Salanb@code{PEX_LAST} were set. On a successful return, @code{*@var{status}} will 97617549Salanbbe set to the exit status of the program. 97717549Salanb 97817549Salanb@end deftypefn 97917549Salanb 98017549Salanb@c pexecute.txh:237 98117549Salanb@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, @ 98217549Salanb int @var{binary}) 98317549Salanb 98417549SalanbReturns a @code{FILE} pointer which may be used to read the standard 98517549Salanberror of the last program in the pipeline. When this is used, 98617549Salanb@code{PEX_LAST} should not be used in a call to @code{pex_run}. After 98716288Salanbthis is called, @code{pex_run} may no longer be called with the same 98817549Salanb@var{obj}. @var{binary} should be non-zero if the file should be 98917549Salanbopened in binary mode. Don't call @code{fclose} on the returned file; 99017549Salanbit will be closed by @code{pex_free}. 99117549Salanb 99217549Salanb@end deftypefn 99317549Salanb 99417549Salanb@c pexecute.txh:224 99517549Salanb@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, @ 99617549Salanb int @var{binary}) 99717549Salanb 99817549SalanbReturns a @code{FILE} pointer which may be used to read the standard 99916288Salanboutput of the last program in the pipeline. When this is used, 100016288Salanb@code{PEX_LAST} should not be used in a call to @code{pex_run}. After 100116288Salanbthis is called, @code{pex_run} may no longer be called with the same 100216288Salanb@var{obj}. @var{binary} should be non-zero if the file should be 100316288Salanbopened in binary mode. Don't call @code{fclose} on the returned file; 100416288Salanbit will be closed by @code{pex_free}. 100516288Salanb 100616288Salanb@end deftypefn 100716288Salanb 100816288Salanb@c pexecute.txh:34 100916288Salanb@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, @ 101016288Salanb int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ 101116288Salanb const char *@var{outname}, const char *@var{errname}, int *@var{err}) 101216288Salanb 101316288SalanbExecute one program in a pipeline. On success this returns 101416288Salanb@code{NULL}. On failure it returns an error message, a statically 101516288Salanballocated string. 101616288Salanb 101716288Salanb@var{obj} is returned by a previous call to @code{pex_init}. 101816288Salanb 101916288Salanb@var{flags} is a bitwise combination of the following: 102016288Salanb 102116288Salanb@table @code 102216288Salanb 102316288Salanb@vindex PEX_LAST 102416288Salanb@item PEX_LAST 102516288SalanbThis must be set on the last program in the pipeline. In particular, 102616288Salanbit should be set when executing a single program. The standard output 102716288Salanbof the program will be sent to @var{outname}, or, if @var{outname} is 102816288Salanb@code{NULL}, to the standard output of the calling program. Do @emph{not} 102916288Salanbset this bit if you want to call @code{pex_read_output} 103016288Salanb(described below). After a call to @code{pex_run} with this bit set, 103116288Salanb@var{pex_run} may no longer be called with the same @var{obj}. 103216288Salanb 103316288Salanb@vindex PEX_SEARCH 103416288Salanb@item PEX_SEARCH 103516288SalanbSearch for the program using the user's executable search path. 103616288Salanb 103716288Salanb@vindex PEX_SUFFIX 103816288Salanb@item PEX_SUFFIX 103916288Salanb@var{outname} is a suffix. See the description of @var{outname}, 104016288Salanbbelow. 104116288Salanb 104216288Salanb@vindex PEX_STDERR_TO_STDOUT 104316288Salanb@item PEX_STDERR_TO_STDOUT 104416288SalanbSend the program's standard error to standard output, if possible. 104516288Salanb 104616288Salanb@vindex PEX_BINARY_INPUT 104716288Salanb@vindex PEX_BINARY_OUTPUT 104816288Salanb@vindex PEX_BINARY_ERROR 104916937Salanb@item PEX_BINARY_INPUT 105016288Salanb@itemx PEX_BINARY_OUTPUT 105116288Salanb@itemx PEX_BINARY_ERROR 105216288SalanbThe standard input (output or error) of the program should be read (written) in 105316288Salanbbinary mode rather than text mode. These flags are ignored on systems 105416288Salanbwhich do not distinguish binary mode and text mode, such as Unix. For 105516288Salanbproper behavior these flags should match appropriately---a call to 105616288Salanb@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a 105716288Salanbcall using @code{PEX_BINARY_INPUT}. 105816288Salanb 105916288Salanb@vindex PEX_STDERR_TO_PIPE 106016288Salanb@item PEX_STDERR_TO_PIPE 106116288SalanbSend the program's standard error to a pipe, if possible. This flag 106216288Salanbcannot be specified together with @code{PEX_STDERR_TO_STDOUT}. This 106316288Salanbflag can be specified only on the last program in pipeline. 106416288Salanb 106516288Salanb@end table 106616288Salanb 106716288Salanb@var{executable} is the program to execute. @var{argv} is the set of 106816288Salanbarguments to pass to the program; normally @code{@var{argv}[0]} will 106916288Salanbbe a copy of @var{executable}. 107016288Salanb 107116288Salanb@var{outname} is used to set the name of the file to use for standard 107216288Salanboutput. There are two cases in which no output file will be used: 107316288Salanb 107416288Salanb@enumerate 107516288Salanb@item 107616288Salanbif @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} 107716288Salanbwas set in the call to @code{pex_init}, and the system supports pipes 107816288Salanb 107916288Salanb@item 108016288Salanbif @code{PEX_LAST} is set in @var{flags}, and @var{outname} is 108116288Salanb@code{NULL} 108216288Salanb@end enumerate 108316288Salanb 108416288Salanb@noindent 108516288SalanbOtherwise the code will use a file to hold standard 108616288Salanboutput. If @code{PEX_LAST} is not set, this file is considered to be 108716288Salanba temporary file, and it will be removed when no longer needed, unless 108816288Salanb@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. 108916288Salanb 109016288SalanbThere are two cases to consider when setting the name of the file to 109116288Salanbhold standard output. 109216288Salanb 109316288Salanb@enumerate 109416288Salanb@item 109516288Salanb@code{PEX_SUFFIX} is set in @var{flags}. In this case 109616288Salanb@var{outname} may not be @code{NULL}. If the @var{tempbase} parameter 109716288Salanbto @code{pex_init} was not @code{NULL}, then the output file name is 109816288Salanbthe concatenation of @var{tempbase} and @var{outname}. If 109916288Salanb@var{tempbase} was @code{NULL}, then the output file name is a random 110016288Salanbfile name ending in @var{outname}. 110116288Salanb 110216690Salanb@item 110316288Salanb@code{PEX_SUFFIX} was not set in @var{flags}. In this 110416288Salanbcase, if @var{outname} is not @code{NULL}, it is used as the output 110516690Salanbfile name. If @var{outname} is @code{NULL}, and @var{tempbase} was 110616690Salanbnot NULL, the output file name is randomly chosen using 110716690Salanb@var{tempbase}. Otherwise the output file name is chosen completely 110816288Salanbat random. 110916288Salanb@end enumerate 111016288Salanb 111116288Salanb@var{errname} is the file name to use for standard error output. If 111216288Salanbit is @code{NULL}, standard error is the same as the caller's. 111316288SalanbOtherwise, standard error is written to the named file. 111416288Salanb 111516288SalanbOn an error return, the code sets @code{*@var{err}} to an @code{errno} 111616288Salanbvalue, or to 0 if there is no relevant @code{errno}. 111716288Salanb 111816288Salanb@end deftypefn 111916288Salanb 112016288Salanb@c pexecute.txh:145 112116288Salanb@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, @ 112216288Salanb int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ 112316288Salanb char * const *@var{env}, int @var{env_size}, const char *@var{outname}, @ 112416288Salanb const char *@var{errname}, int *@var{err}) 112516288Salanb 112616288SalanbExecute one program in a pipeline, permitting the environment for the 112716288Salanbprogram to be specified. Behaviour and parameters not listed below are 112816288Salanbas for @code{pex_run}. 112916288Salanb 113016288Salanb@var{env} is the environment for the child process, specified as an array of 113116288Salanbcharacter pointers. Each element of the array should point to a string of the 113216288Salanbform @code{VAR=VALUE}, with the exception of the last element that must be 113316288Salanb@code{NULL}. 113416288Salanb 113516288Salanb@end deftypefn 113616288Salanb 113716288Salanb@c pexecute.txh:301 113816288Salanb@deftypefn Extension int pexecute (const char *@var{program}, @ 113916288Salanb char * const *@var{argv}, const char *@var{this_pname}, @ 114016288Salanb const char *@var{temp_base}, char **@var{errmsg_fmt}, @ 114116288Salanb char **@var{errmsg_arg}, int @var{flags}) 114216288Salanb 114316288SalanbThis is the old interface to execute one or more programs. It is 114416288Salanbstill supported for compatibility purposes, but is no longer 114516288Salanbdocumented. 114616288Salanb 114716288Salanb@end deftypefn 114816288Salanb 114916288Salanb@c strsignal.c:541 115016288Salanb@deftypefn Supplemental void psignal (int @var{signo}, char *@var{message}) 115116288Salanb 115216288SalanbPrint @var{message} to the standard error, followed by a colon, 115316288Salanbfollowed by the description of the signal specified by @var{signo}, 115416288Salanbfollowed by a newline. 115516288Salanb 115616288Salanb@end deftypefn 115716288Salanb 115816288Salanb@c putenv.c:21 115916288Salanb@deftypefn Supplemental int putenv (const char *@var{string}) 116016288Salanb 116116288SalanbUses @code{setenv} or @code{unsetenv} to put @var{string} into 116216288Salanbthe environment or remove it. If @var{string} is of the form 116316288Salanb@samp{name=value} the string is added; if no @samp{=} is present the 116416288Salanbname is unset/removed. 116516288Salanb 116616288Salanb@end deftypefn 116716288Salanb 116816288Salanb@c pexecute.txh:312 116916288Salanb@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) 117016288Salanb 117116288SalanbAnother part of the old execution interface. 117216288Salanb 117316288Salanb@end deftypefn 117416288Salanb 117516288Salanb@c random.c:39 117616288Salanb@deftypefn Supplement {long int} random (void) 117716288Salanb@deftypefnx Supplement void srandom (unsigned int @var{seed}) 117816288Salanb@deftypefnx Supplement void* initstate (unsigned int @var{seed}, @ 117916288Salanb void *@var{arg_state}, unsigned long @var{n}) 118016288Salanb@deftypefnx Supplement void* setstate (void *@var{arg_state}) 118116288Salanb 118216288SalanbRandom number functions. @code{random} returns a random number in the 118316288Salanbrange 0 to @code{LONG_MAX}. @code{srandom} initializes the random 118416288Salanbnumber generator to some starting point determined by @var{seed} 118516288Salanb(else, the values returned by @code{random} are always the same for each 118616288Salanbrun of the program). @code{initstate} and @code{setstate} allow fine-grained 118716288Salanbcontrol over the state of the random number generator. 118816288Salanb 118916288Salanb@end deftypefn 119016288Salanb 119116288Salanb@c concat.c:160 119216288Salanb@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @ 119316288Salanb @dots{}, @code{NULL}) 119416288Salanb 119516288SalanbSame as @code{concat}, except that if @var{optr} is not @code{NULL} it 119616288Salanbis freed after the string is created. This is intended to be useful 119716288Salanbwhen you're extending an existing string or building up a string in a 119816288Salanbloop: 119916288Salanb 120016288Salanb@example 120116288Salanb str = reconcat (str, "pre-", str, NULL); 120216288Salanb@end example 120316288Salanb 120416288Salanb@end deftypefn 120516288Salanb 120616288Salanb@c rename.c:6 120716288Salanb@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new}) 120816288Salanb 120916288SalanbRenames a file from @var{old} to @var{new}. If @var{new} already 121016288Salanbexists, it is removed. 121116288Salanb 121216288Salanb@end deftypefn 121316288Salanb 121416288Salanb@c rindex.c:5 121516288Salanb@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c}) 121616288Salanb 121716288SalanbReturns a pointer to the last occurrence of the character @var{c} in 121816288Salanbthe string @var{s}, or @code{NULL} if not found. The use of @code{rindex} is 121916288Salanbdeprecated in new programs in favor of @code{strrchr}. 122016288Salanb 122116288Salanb@end deftypefn 122216288Salanb 122316288Salanb@c setenv.c:22 122416288Salanb@deftypefn Supplemental int setenv (const char *@var{name}, @ 122516288Salanb const char *@var{value}, int @var{overwrite}) 122616288Salanb@deftypefnx Supplemental void unsetenv (const char *@var{name}) 122716288Salanb 122816288Salanb@code{setenv} adds @var{name} to the environment with value 122916288Salanb@var{value}. If the name was already present in the environment, 123016288Salanbthe new value will be stored only if @var{overwrite} is nonzero. 123116288SalanbThe companion @code{unsetenv} function removes @var{name} from the 123216288Salanbenvironment. This implementation is not safe for multithreaded code. 123316288Salanb 123416288Salanb@end deftypefn 123516288Salanb 123616288Salanb@c setproctitle.c:31 123716288Salanb@deftypefn Supplemental void setproctitle (const char *@var{fmt}, ...) 123816288Salanb 123916288SalanbSet the title of a process to @var{fmt}. va args not supported for now, 124016288Salanbbut defined for compatibility with BSD. 124116288Salanb 124216288Salanb@end deftypefn 124316288Salanb 124416288Salanb@c strsignal.c:348 124516288Salanb@deftypefn Extension int signo_max (void) 124616288Salanb 124716288SalanbReturns the maximum signal value for which a corresponding symbolic 124816288Salanbname or message is available. Note that in the case where we use the 124916288Salanb@code{sys_siglist} supplied by the system, it is possible for there to 125016288Salanbbe more symbolic names than messages, or vice versa. In fact, the 125116288Salanbmanual page for @code{psignal(3b)} explicitly warns that one should 125216288Salanbcheck the size of the table (@code{NSIG}) before indexing it, since 125316288Salanbnew signal codes may be added to the system before they are added to 125416288Salanbthe table. Thus @code{NSIG} might be smaller than value implied by 125516288Salanbthe largest signo value defined in @code{<signal.h>}. 125616288Salanb 125716288SalanbWe return the maximum value that can be used to obtain a meaningful 125816288Salanbsymbolic name or message. 125916288Salanb 126016288Salanb@end deftypefn 126116288Salanb 126216288Salanb@c sigsetmask.c:8 126316288Salanb@deftypefn Supplemental int sigsetmask (int @var{set}) 126416288Salanb 126516288SalanbSets the signal mask to the one provided in @var{set} and returns 126616288Salanbthe old mask (which, for libiberty's implementation, will always 126716288Salanbbe the value @code{1}). 126816288Salanb 126916288Salanb@end deftypefn 127016288Salanb 127116288Salanb@c simple-object.txh:96 127216288Salanb@deftypefn Extension {const char *} simple_object_attributes_compare @ 127316288Salanb (simple_object_attributes *@var{attrs1}, simple_object_attributes *@var{attrs2}, @ 127416288Salanb int *@var{err}) 127516288Salanb 127616288SalanbCompare @var{attrs1} and @var{attrs2}. If they could be linked 127716288Salanbtogether without error, return @code{NULL}. Otherwise, return an 127816288Salanberror message and set @code{*@var{err}} to an errno value or @code{0} 127916288Salanbif there is no relevant errno. 128016288Salanb 128116288Salanb@end deftypefn 128216288Salanb 128316288Salanb@c simple-object.txh:81 128416288Salanb@deftypefn Extension {simple_object_attributes *} simple_object_fetch_attributes @ 128516288Salanb (simple_object_read *@var{simple_object}, const char **@var{errmsg}, int *@var{err}) 128616288Salanb 128716288SalanbFetch the attributes of @var{simple_object}. The attributes are 128816288Salanbinternal information such as the format of the object file, or the 128916288Salanbarchitecture it was compiled for. This information will persist until 129016288Salanb@code{simple_object_attributes_release} is called, even if 129116288Salanb@var{simple_object} itself is released. 129216288Salanb 129316288SalanbOn error this returns @code{NULL}, sets @code{*@var{errmsg}} to an 129416288Salanberror message, and sets @code{*@var{err}} to an errno value or 129516288Salanb@code{0} if there is no relevant errno. 129616288Salanb 129716288Salanb@end deftypefn 129816288Salanb 129916288Salanb@c simple-object.txh:49 130016288Salanb@deftypefn Extension {int} simple_object_find_section @ 130116288Salanb (simple_object_read *@var{simple_object} off_t *@var{offset}, @ 130216288Salanb off_t *@var{length}, const char **@var{errmsg}, int *@var{err}) 130316288Salanb 130416288SalanbLook for the section @var{name} in @var{simple_object}. This returns 130516288Salanbinformation for the first section with that name. 130616288Salanb 130716288SalanbIf found, return 1 and set @code{*@var{offset}} to the offset in the 130816288Salanbfile of the section contents and set @code{*@var{length}} to the 130916288Salanblength of the section contents. The value in @code{*@var{offset}} 131016288Salanbwill be relative to the offset passed to 131116288Salanb@code{simple_object_open_read}. 131216288Salanb 131316288SalanbIf the section is not found, and no error occurs, 131416288Salanb@code{simple_object_find_section} returns @code{0} and set 131516288Salanb@code{*@var{errmsg}} to @code{NULL}. 131616288Salanb 131716288SalanbIf an error occurs, @code{simple_object_find_section} returns 131816288Salanb@code{0}, sets @code{*@var{errmsg}} to an error message, and sets 131916288Salanb@code{*@var{err}} to an errno value or @code{0} if there is no 132016288Salanbrelevant errno. 132116288Salanb 132216288Salanb@end deftypefn 132316288Salanb 132416288Salanb@c simple-object.txh:27 132516288Salanb@deftypefn Extension {const char *} simple_object_find_sections @ 132616288Salanb (simple_object_read *@var{simple_object}, int (*@var{pfn}) (void *@var{data}, @ 132716288Salanb const char *@var{name}, off_t @var{offset}, off_t @var{length}), @ 132816288Salanb void *@var{data}, int *@var{err}) 132916288Salanb 133016288SalanbThis function calls @var{pfn} for each section in @var{simple_object}. 133116288SalanbIt calls @var{pfn} with the section name, the offset within the file 133216288Salanbof the section contents, and the length of the section contents. The 133316288Salanboffset within the file is relative to the offset passed to 133416288Salanb@code{simple_object_open_read}. The @var{data} argument to this 133516288Salanbfunction is passed along to @var{pfn}. 133616288Salanb 133716288SalanbIf @var{pfn} returns @code{0}, the loop over the sections stops and 133816288Salanb@code{simple_object_find_sections} returns. If @var{pfn} returns some 133916288Salanbother value, the loop continues. 134016288Salanb 134116288SalanbOn success @code{simple_object_find_sections} returns. On error it 134216288Salanbreturns an error string, and sets @code{*@var{err}} to an errno value 134316288Salanbor @code{0} if there is no relevant errno. 134416288Salanb 134516288Salanb@end deftypefn 134616288Salanb 134716288Salanb@c simple-object.txh:2 134816288Salanb@deftypefn Extension {simple_object_read *} simple_object_open_read @ 134916288Salanb (int @var{descriptor}, off_t @var{offset}, const char *{segment_name}, @ 135016288Salanb const char **@var{errmsg}, int *@var{err}) 135116288Salanb 135216288SalanbOpens an object file for reading. Creates and returns an 135316288Salanb@code{simple_object_read} pointer which may be passed to other 135416288Salanbfunctions to extract data from the object file. 135516288Salanb 135616288Salanb@var{descriptor} holds a file descriptor which permits reading. 135716288Salanb 135816288Salanb@var{offset} is the offset into the file; this will be @code{0} in the 135916288Salanbnormal case, but may be a different value when reading an object file 136016288Salanbin an archive file. 136116288Salanb 136216288Salanb@var{segment_name} is only used with the Mach-O file format used on 136316288SalanbDarwin aka Mac OS X. It is required on that platform, and means to 136416288Salanbonly look at sections within the segment with that name. The 136516288Salanbparameter is ignored on other systems. 136616288Salanb 136716288SalanbIf an error occurs, this functions returns @code{NULL} and sets 136816288Salanb@code{*@var{errmsg}} to an error string and sets @code{*@var{err}} to 136916288Salanban errno value or @code{0} if there is no relevant errno. 137016288Salanb 137116288Salanb@end deftypefn 137216288Salanb 137316288Salanb@c simple-object.txh:107 137416288Salanb@deftypefn Extension {void} simple_object_release_attributes @ 137516288Salanb (simple_object_attributes *@var{attrs}) 137616288Salanb 137716288SalanbRelease all resources associated with @var{attrs}. 137816288Salanb 137916288Salanb@end deftypefn 138016288Salanb 138116288Salanb@c simple-object.txh:73 138216288Salanb@deftypefn Extension {void} simple_object_release_read @ 138316598Smchung (simple_object_read *@var{simple_object}) 138416598Smchung 138516598SmchungRelease all resources associated with @var{simple_object}. This does 138616598Smchungnot close the file descriptor. 138716598Smchung 138816598Smchung@end deftypefn 138916598Smchung 139016598Smchung@c simple-object.txh:184 139116288Salanb@deftypefn Extension {void} simple_object_release_write @ 139216288Salanb (simple_object_write *@var{simple_object}) 139316288Salanb 139416288SalanbRelease all resources associated with @var{simple_object}. 139516288Salanb 139616288Salanb@end deftypefn 139716288Salanb 139816288Salanb@c simple-object.txh:114 139916288Salanb@deftypefn Extension {simple_object_write *} simple_object_start_write @ 140016288Salanb (simple_object_attributes @var{attrs}, const char *@var{segment_name}, @ 140116288Salanb const char **@var{errmsg}, int *@var{err}) 140216288Salanb 140316288SalanbStart creating a new object file using the object file format 140416288Salanbdescribed in @var{attrs}. You must fetch attribute information from 140516288Salanban existing object file before you can create a new one. There is 140616288Salanbcurrently no support for creating an object file de novo. 140716288Salanb 140816288Salanb@var{segment_name} is only used with Mach-O as found on Darwin aka Mac 140916288SalanbOS X. The parameter is required on that target. It means that all 141016288Salanbsections are created within the named segment. It is ignored for 141116288Salanbother object file formats. 141216288Salanb 141316288SalanbOn error @code{simple_object_start_write} returns @code{NULL}, sets 141416288Salanb@code{*@var{ERRMSG}} to an error message, and sets @code{*@var{err}} 141516288Salanbto an errno value or @code{0} if there is no relevant errno. 141616288Salanb 141716288Salanb@end deftypefn 141816288Salanb 141916288Salanb@c simple-object.txh:153 142016288Salanb@deftypefn Extension {const char *} simple_object_write_add_data @ 142116288Salanb (simple_object_write *@var{simple_object}, @ 142216288Salanb simple_object_write_section *@var{section}, const void *@var{buffer}, @ 142316288Salanb size_t @var{size}, int @var{copy}, int *@var{err}) 142416288Salanb 142516288SalanbAdd data @var{buffer}/@var{size} to @var{section} in 142616288Salanb@var{simple_object}. If @var{copy} is non-zero, the data will be 142716288Salanbcopied into memory if necessary. If @var{copy} is zero, @var{buffer} 142816288Salanbmust persist until @code{simple_object_write_to_file} is called. is 142916288Salanbreleased. 143016288Salanb 143116288SalanbOn success this returns @code{NULL}. On error this returns an error 143216288Salanbmessage, and sets @code{*@var{err}} to an errno value or 0 if there is 143316288Salanbno relevant erro. 143416288Salanb 143516288Salanb@end deftypefn 143616288Salanb 143716288Salanb@c simple-object.txh:134 143816337Sredestad@deftypefn Extension {simple_object_write_section *} simple_object_write_create_section @ 143916288Salanb (simple_object_write *@var{simple_object}, const char *@var{name}, @ 144016337Sredestad unsigned int @var{align}, const char **@var{errmsg}, int *@var{err}) 144116288Salanb 144216288SalanbAdd a section to @var{simple_object}. @var{name} is the name of the 144316288Salanbnew section. @var{align} is the required alignment expressed as the 144416288Salanbnumber of required low-order 0 bits (e.g., 2 for alignment to a 32-bit 144516288Salanbboundary). 144616288Salanb 144716288SalanbThe section is created as containing data, readable, not writable, not 144816288Salanbexecutable, not loaded at runtime. The section is not written to the 144916288Salanbfile until @code{simple_object_write_to_file} is called. 145016288Salanb 145116288SalanbOn error this returns @code{NULL}, sets @code{*@var{errmsg}} to an 145216288Salanberror message, and sets @code{*@var{err}} to an errno value or 145316288Salanb@code{0} if there is no relevant errno. 145416288Salanb 145516288Salanb@end deftypefn 145616288Salanb 145716288Salanb@c simple-object.txh:170 145816288Salanb@deftypefn Extension {const char *} simple_object_write_to_file @ 145916288Salanb (simple_object_write *@var{simple_object}, int @var{descriptor}, int *@var{err}) 146016288Salanb 146116288SalanbWrite the complete object file to @var{descriptor}, an open file 146216288Salanbdescriptor. This writes out all the data accumulated by calls to 146316288Salanb@code{simple_object_write_create_section} and 146416288Salanb@var{simple_object_write_add_data}. 146516288Salanb 146616288SalanbThis returns @code{NULL} on success. On error this returns an error 146716288Salanbmessage and sets @code{*@var{err}} to an errno value or @code{0} if 146816288Salanbthere is no relevant errno. 146916288Salanb 147016288Salanb@end deftypefn 147116288Salanb 147216288Salanb@c snprintf.c:28 147316288Salanb@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, @ 147416288Salanb const char *@var{format}, ...) 147516288Salanb 147616288SalanbThis function is similar to @code{sprintf}, but it will write to 147716288Salanb@var{buf} at most @code{@var{n}-1} bytes of text, followed by a 147816288Salanbterminating null byte, for a total of @var{n} bytes. 147916288SalanbOn error the return value is -1, otherwise it returns the number of 148016288Salanbbytes, not including the terminating null byte, that would have been 148116288Salanbwritten had @var{n} been sufficiently large, regardless of the actual 148216288Salanbvalue of @var{n}. Note some pre-C99 system libraries do not implement 148316288Salanbthis correctly so users cannot generally rely on the return value if 148416288Salanbthe system version of this function is used. 148516288Salanb 148616288Salanb@end deftypefn 148716288Salanb 148816288Salanb@c spaces.c:22 148916288Salanb@deftypefn Extension char* spaces (int @var{count}) 149016288Salanb 149116288SalanbReturns a pointer to a memory region filled with the specified 149216288Salanbnumber of spaces and null terminated. The returned pointer is 149316288Salanbvalid until at least the next call. 149416288Salanb 149516288Salanb@end deftypefn 149616288Salanb 149716288Salanb@c splay-tree.c:305 149816288Salanb@deftypefn Supplemental splay_tree splay_tree_new_with_typed_alloc @ 149916288Salanb(splay_tree_compare_fn @var{compare_fn}, @ 150016288Salanbsplay_tree_delete_key_fn @var{delete_key_fn}, @ 150116288Salanbsplay_tree_delete_value_fn @var{delete_value_fn}, @ 150216288Salanbsplay_tree_allocate_fn @var{tree_allocate_fn}, @ 150316288Salanbsplay_tree_allocate_fn @var{node_allocate_fn}, @ 150416288Salanbsplay_tree_deallocate_fn @var{deallocate_fn}, @ 150516288Salanbvoid * @var{allocate_data}) 150616288Salanb 150716288SalanbThis function creates a splay tree that uses two different allocators 150816288Salanb@var{tree_allocate_fn} and @var{node_allocate_fn} to use for allocating the 150916288Salanbtree itself and its nodes respectively. This is useful when variables of 151016288Salanbdifferent types need to be allocated with different allocators. 151116288Salanb 151216288SalanbThe splay tree will use @var{compare_fn} to compare nodes, 151316288Salanb@var{delete_key_fn} to deallocate keys, and @var{delete_value_fn} to 151416288Salanbdeallocate values. Keys and values will be deallocated when the 151516288Salanbtree is deleted using splay_tree_delete or when a node is removed 151616288Salanbusing splay_tree_remove. splay_tree_insert will release the previously 151716288Salanbinserted key and value using @var{delete_key_fn} and @var{delete_value_fn} 151816288Salanbif the inserted key is already found in the tree. 151916288Salanb 152016288Salanb@end deftypefn 152116288Salanb 152216288Salanb@c stack-limit.c:28 152316288Salanb@deftypefn Extension void stack_limit_increase (unsigned long @var{pref}) 152416288Salanb 152516288SalanbAttempt to increase stack size limit to @var{pref} bytes if possible. 152616288Salanb 152716288Salanb@end deftypefn 152816288Salanb 152916288Salanb@c stpcpy.c:23 153016288Salanb@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src}) 153116288Salanb 153216288SalanbCopies the string @var{src} into @var{dst}. Returns a pointer to 153316288Salanb@var{dst} + strlen(@var{src}). 153416288Salanb 153516288Salanb@end deftypefn 153616288Salanb 153716288Salanb@c stpncpy.c:23 153816288Salanb@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, @ 153916288Salanb size_t @var{len}) 154016288Salanb 154116288SalanbCopies the string @var{src} into @var{dst}, copying exactly @var{len} 154216288Salanband padding with zeros if necessary. If @var{len} < strlen(@var{src}) 154316288Salanbthen return @var{dst} + @var{len}, otherwise returns @var{dst} + 154416288Salanbstrlen(@var{src}). 154516288Salanb 154616288Salanb@end deftypefn 154716288Salanb 154816288Salanb@c strcasecmp.c:15 154916288Salanb@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2}) 155016288Salanb 155116288SalanbA case-insensitive @code{strcmp}. 155216288Salanb 155316288Salanb@end deftypefn 155416288Salanb 155516288Salanb@c strchr.c:6 155616288Salanb@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c}) 155716288Salanb 155816288SalanbReturns a pointer to the first occurrence of the character @var{c} in 155916288Salanbthe string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 156016288Salanbnull character, the results are undefined. 156116288Salanb 156216288Salanb@end deftypefn 156316288Salanb 156416288Salanb@c strdup.c:3 156516288Salanb@deftypefn Supplemental char* strdup (const char *@var{s}) 156616288Salanb 156716288SalanbReturns a pointer to a copy of @var{s} in memory obtained from 156816288Salanb@code{malloc}, or @code{NULL} if insufficient memory was available. 156916288Salanb 157016288Salanb@end deftypefn 157116288Salanb 157216288Salanb@c strerror.c:675 157316288Salanb@deftypefn Replacement {const char*} strerrno (int @var{errnum}) 157416288Salanb 157516288SalanbGiven an error number returned from a system call (typically returned 157616288Salanbin @code{errno}), returns a pointer to a string containing the 157716288Salanbsymbolic name of that error number, as found in @code{<errno.h>}. 157816288Salanb 157916288SalanbIf the supplied error number is within the valid range of indices for 158016288Salanbsymbolic names, but no name is available for the particular error 158116288Salanbnumber, then returns the string @samp{Error @var{num}}, where @var{num} 158216288Salanbis the error number. 158316288Salanb 158416288SalanbIf the supplied error number is not within the range of valid 158516288Salanbindices, then returns @code{NULL}. 158616288Salanb 158716288SalanbThe contents of the location pointed to are only guaranteed to be 158816288Salanbvalid until the next call to @code{strerrno}. 158916288Salanb 159016288Salanb@end deftypefn 159116288Salanb 159216288Salanb@c strerror.c:608 159316288Salanb@deftypefn Supplemental char* strerror (int @var{errnoval}) 159416288Salanb 159516288SalanbMaps an @code{errno} number to an error message string, the contents 159616288Salanbof which are implementation defined. On systems which have the 159716288Salanbexternal variables @code{sys_nerr} and @code{sys_errlist}, these 159816288Salanbstrings will be the same as the ones used by @code{perror}. 159916288Salanb 160016288SalanbIf the supplied error number is within the valid range of indices for 160116288Salanbthe @code{sys_errlist}, but no message is available for the particular 160216288Salanberror number, then returns the string @samp{Error @var{num}}, where 160316288Salanb@var{num} is the error number. 160416288Salanb 160516288SalanbIf the supplied error number is not a valid index into 160616288Salanb@code{sys_errlist}, returns @code{NULL}. 160716288Salanb 160816288SalanbThe returned string is only guaranteed to be valid only until the 160916288Salanbnext call to @code{strerror}. 161016288Salanb 161116288Salanb@end deftypefn 161216288Salanb 161316288Salanb@c strncasecmp.c:15 161416288Salanb@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2}) 161516288Salanb 161616288SalanbA case-insensitive @code{strncmp}. 161716288Salanb 161816288Salanb@end deftypefn 161916288Salanb 162016288Salanb@c strncmp.c:6 162116288Salanb@deftypefn Supplemental int strncmp (const char *@var{s1}, @ 162216288Salanb const char *@var{s2}, size_t @var{n}) 162316288Salanb 162416288SalanbCompares the first @var{n} bytes of two strings, returning a value as 162516288Salanb@code{strcmp}. 162616288Salanb 162716288Salanb@end deftypefn 162816288Salanb 162916288Salanb@c strndup.c:23 163016288Salanb@deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n}) 163116288Salanb 163216288SalanbReturns a pointer to a copy of @var{s} with at most @var{n} characters 163316288Salanbin memory obtained from @code{malloc}, or @code{NULL} if insufficient 163416288Salanbmemory was available. The result is always NUL terminated. 163516288Salanb 163616288Salanb@end deftypefn 163716288Salanb 163816288Salanb@c strnlen.c:6 163916288Salanb@deftypefn Supplemental size_t strnlen (const char *@var{s}, size_t @var{maxlen}) 164016288Salanb 164116288SalanbReturns the length of @var{s}, as with @code{strlen}, but never looks 164216288Salanbpast the first @var{maxlen} characters in the string. If there is no 164316288Salanb'\0' character in the first @var{maxlen} characters, returns 164416288Salanb@var{maxlen}. 164516288Salanb 164616288Salanb@end deftypefn 164716288Salanb 164816288Salanb@c strrchr.c:6 164916288Salanb@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c}) 165016288Salanb 165116288SalanbReturns a pointer to the last occurrence of the character @var{c} in 165216288Salanbthe string @var{s}, or @code{NULL} if not found. If @var{c} is itself the 165316288Salanbnull character, the results are undefined. 165416288Salanb 165516288Salanb@end deftypefn 165616288Salanb 165716288Salanb@c strsignal.c:383 165816288Salanb@deftypefn Supplemental {const char *} strsignal (int @var{signo}) 165916288Salanb 166016288SalanbMaps an signal number to an signal message string, the contents of 166116288Salanbwhich are implementation defined. On systems which have the external 166216288Salanbvariable @code{sys_siglist}, these strings will be the same as the 166316288Salanbones used by @code{psignal()}. 166416288Salanb 166516288SalanbIf the supplied signal number is within the valid range of indices for 166616288Salanbthe @code{sys_siglist}, but no message is available for the particular 166716288Salanbsignal number, then returns the string @samp{Signal @var{num}}, where 166816288Salanb@var{num} is the signal number. 166916288Salanb 167016288SalanbIf the supplied signal number is not a valid index into 167116288Salanb@code{sys_siglist}, returns @code{NULL}. 167216288Salanb 167316288SalanbThe returned string is only guaranteed to be valid only until the next 167416288Salanbcall to @code{strsignal}. 167516288Salanb 167616288Salanb@end deftypefn 167716288Salanb 167816288Salanb@c strsignal.c:448 167916288Salanb@deftypefn Extension {const char*} strsigno (int @var{signo}) 168016288Salanb 168116288SalanbGiven an signal number, returns a pointer to a string containing the 168216288Salanbsymbolic name of that signal number, as found in @code{<signal.h>}. 168316288Salanb 168416288SalanbIf the supplied signal number is within the valid range of indices for 168516288Salanbsymbolic names, but no name is available for the particular signal 168616288Salanbnumber, then returns the string @samp{Signal @var{num}}, where 168716288Salanb@var{num} is the signal number. 168816288Salanb 168916288SalanbIf the supplied signal number is not within the range of valid 169016288Salanbindices, then returns @code{NULL}. 169116288Salanb 169216288SalanbThe contents of the location pointed to are only guaranteed to be 169316288Salanbvalid until the next call to @code{strsigno}. 169416288Salanb 169516288Salanb@end deftypefn 169616288Salanb 169716288Salanb@c strstr.c:6 169816288Salanb@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub}) 169916288Salanb 170016288SalanbThis function searches for the substring @var{sub} in the string 170116288Salanb@var{string}, not including the terminating null characters. A pointer 170216288Salanbto the first occurrence of @var{sub} is returned, or @code{NULL} if the 170316288Salanbsubstring is absent. If @var{sub} points to a string with zero 170416288Salanblength, the function returns @var{string}. 170516288Salanb 170616288Salanb@end deftypefn 170716288Salanb 170816288Salanb@c strtod.c:27 170916288Salanb@deftypefn Supplemental double strtod (const char *@var{string}, @ 171016288Salanb char **@var{endptr}) 171116288Salanb 171216288SalanbThis ISO C function converts the initial portion of @var{string} to a 171316288Salanb@code{double}. If @var{endptr} is not @code{NULL}, a pointer to the 171417408Salanbcharacter after the last character used in the conversion is stored in 171517549Salanbthe location referenced by @var{endptr}. If no conversion is 171617549Salanbperformed, zero is returned and the value of @var{string} is stored in 171717549Salanbthe location referenced by @var{endptr}. 171817549Salanb 171917549Salanb@end deftypefn 172017549Salanb 172117549Salanb@c strerror.c:734 172217549Salanb@deftypefn Extension int strtoerrno (const char *@var{name}) 172317549Salanb 172417549SalanbGiven the symbolic name of a error number (e.g., @code{EACCES}), map it 172517549Salanbto an errno value. If no translation is found, returns 0. 172617549Salanb 172717549Salanb@end deftypefn 172817549Salanb 172917549Salanb@c strtol.c:33 173017549Salanb@deftypefn Supplemental {long int} strtol (const char *@var{string}, @ 173117549Salanb char **@var{endptr}, int @var{base}) 173217549Salanb@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, @ 173317549Salanb char **@var{endptr}, int @var{base}) 173417549Salanb 173517549SalanbThe @code{strtol} function converts the string in @var{string} to a 173617549Salanblong integer value according to the given @var{base}, which must be 173717549Salanbbetween 2 and 36 inclusive, or be the special value 0. If @var{base} 173817549Salanbis 0, @code{strtol} will look for the prefixes @code{0} and @code{0x} 173917549Salanbto indicate bases 8 and 16, respectively, else default to base 10. 174017549SalanbWhen the base is 16 (either explicitly or implicitly), a prefix of 174117549Salanb@code{0x} is allowed. The handling of @var{endptr} is as that of 174217549Salanb@code{strtod} above. The @code{strtoul} function is the same, except 174317549Salanbthat the converted value is unsigned. 174417549Salanb 174517549Salanb@end deftypefn 174617549Salanb 174717549Salanb@c strtoll.c:33 174817549Salanb@deftypefn Supplemental {long long int} strtoll (const char *@var{string}, @ 174917549Salanb char **@var{endptr}, int @var{base}) 175017549Salanb@deftypefnx Supplemental {unsigned long long int} strtoul (@ 175117549Salanb const char *@var{string}, char **@var{endptr}, int @var{base}) 175217549Salanb 175317549SalanbThe @code{strtoll} function converts the string in @var{string} to a 175417549Salanblong long integer value according to the given @var{base}, which must be 175517549Salanbbetween 2 and 36 inclusive, or be the special value 0. If @var{base} 175617549Salanbis 0, @code{strtoll} will look for the prefixes @code{0} and @code{0x} 175717549Salanbto indicate bases 8 and 16, respectively, else default to base 10. 175817549SalanbWhen the base is 16 (either explicitly or implicitly), a prefix of 175917549Salanb@code{0x} is allowed. The handling of @var{endptr} is as that of 176017549Salanb@code{strtod} above. The @code{strtoull} function is the same, except 176117549Salanbthat the converted value is unsigned. 176217549Salanb 176317549Salanb@end deftypefn 176417549Salanb 176517549Salanb@c strsignal.c:502 176617549Salanb@deftypefn Extension int strtosigno (const char *@var{name}) 176717549Salanb 176817549SalanbGiven the symbolic name of a signal, map it to a signal number. If no 176917549Salanbtranslation is found, returns 0. 177017549Salanb 177117549Salanb@end deftypefn 177217549Salanb 177317549Salanb@c strverscmp.c:25 177417549Salanb@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2}) 177517549SalanbThe @code{strverscmp} function compares the string @var{s1} against 177617549Salanb@var{s2}, considering them as holding indices/version numbers. Return 177717549Salanbvalue follows the same conventions as found in the @code{strverscmp} 177817549Salanbfunction. In fact, if @var{s1} and @var{s2} contain no digits, 177917549Salanb@code{strverscmp} behaves like @code{strcmp}. 178017549Salanb 178117549SalanbBasically, we compare strings normally (character by character), until 178217549Salanbwe find a digit in each string - then we enter a special comparison 178317549Salanbmode, where each sequence of digits is taken as a whole. If we reach the 178417549Salanbend of these two parts without noticing a difference, we return to the 178517549Salanbstandard comparison mode. There are two types of numeric parts: 178617549Salanb"integral" and "fractional" (those begin with a '0'). The types 178717549Salanbof the numeric parts affect the way we sort them: 178817549Salanb 178917549Salanb@itemize @bullet 179017549Salanb@item 179117549Salanbintegral/integral: we compare values as you would expect. 179217549Salanb 179317549Salanb@item 179417549Salanbfractional/integral: the fractional part is less than the integral one. 179517549SalanbAgain, no surprise. 179617549Salanb 179717549Salanb@item 179817549Salanbfractional/fractional: the things become a bit more complex. 179917549SalanbIf the common prefix contains only leading zeroes, the longest part is less 180017549Salanbthan the other one; else the comparison behaves normally. 180117549Salanb@end itemize 180217549Salanb 180317549Salanb@smallexample 180417549Salanbstrverscmp ("no digit", "no digit") 180517549Salanb @result{} 0 // @r{same behavior as strcmp.} 180617549Salanbstrverscmp ("item#99", "item#100") 180717549Salanb @result{} <0 // @r{same prefix, but 99 < 100.} 180817549Salanbstrverscmp ("alpha1", "alpha001") 180917549Salanb @result{} >0 // @r{fractional part inferior to integral one.} 181017549Salanbstrverscmp ("part1_f012", "part1_f01") 181117549Salanb @result{} >0 // @r{two fractional parts.} 181217549Salanbstrverscmp ("foo.009", "foo.0") 181317549Salanb @result{} <0 // @r{idem, but with leading zeroes only.} 181417549Salanb@end smallexample 181517549Salanb 181617549SalanbThis function is especially useful when dealing with filename sorting, 181717549Salanbbecause filenames frequently hold indices/version numbers. 181817549Salanb@end deftypefun 181917549Salanb 182017549Salanb@c timeval-utils.c:43 182117549Salanb@deftypefn Extension void timeval_add (struct timeval *@var{a}, @ 182217549Salanb struct timeval *@var{b}, struct timeval *@var{result}) 182317549Salanb 182417549SalanbAdds @var{a} to @var{b} and stores the result in @var{result}. 182517549Salanb 182617549Salanb@end deftypefn 182717549Salanb 182817549Salanb@c timeval-utils.c:67 182917549Salanb@deftypefn Extension void timeval_sub (struct timeval *@var{a}, @ 183017549Salanb struct timeval *@var{b}, struct timeval *@var{result}) 183117549Salanb 183217549SalanbSubtracts @var{b} from @var{a} and stores the result in @var{result}. 183317549Salanb 183417549Salanb@end deftypefn 183517549Salanb 183617549Salanb@c tmpnam.c:3 183717549Salanb@deftypefn Supplemental char* tmpnam (char *@var{s}) 183817549Salanb 183917549SalanbThis function attempts to create a name for a temporary file, which 184017549Salanbwill be a valid file name yet not exist when @code{tmpnam} checks for 184117549Salanbit. @var{s} must point to a buffer of at least @code{L_tmpnam} bytes, 184217549Salanbor be @code{NULL}. Use of this function creates a security risk, and it must 184317549Salanbnot be used in new projects. Use @code{mkstemp} instead. 184417549Salanb 184517549Salanb@end deftypefn 184617549Salanb 184717549Salanb@c unlink-if-ordinary.c:27 184817549Salanb@deftypefn Supplemental int unlink_if_ordinary (const char*) 184917549Salanb 185017549SalanbUnlinks the named file, unless it is special (e.g. a device file). 185117549SalanbReturns 0 when the file was unlinked, a negative value (and errno set) when 185217549Salanbthere was an error deleting the file, and a positive value if no attempt 185317549Salanbwas made to unlink the file because it is special. 185417549Salanb 185517408Salanb@end deftypefn 185617549Salanb 185717549Salanb@c fopen_unlocked.c:31 185817549Salanb@deftypefn Extension void unlock_std_streams (void) 185917549Salanb 186017549SalanbIf the OS supports it, ensure that the standard I/O streams, 186117549Salanb@code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any 186217549Salanbmulti-threaded locking. Otherwise do nothing. 186317549Salanb 186417549Salanb@end deftypefn 186517549Salanb 186617549Salanb@c fopen_unlocked.c:23 186717549Salanb@deftypefn Extension void unlock_stream (FILE * @var{stream}) 186817408Salanb 186917408SalanbIf the OS supports it, ensure that the supplied stream is setup to 187017408Salanbavoid any multi-threaded locking. Otherwise leave the @code{FILE} 187117408Salanbpointer unchanged. If the @var{stream} is @code{NULL} do nothing. 187217408Salanb 187317408Salanb@end deftypefn 187417408Salanb 187517408Salanb@c vasprintf.c:47 187617408Salanb@deftypefn Extension int vasprintf (char **@var{resptr}, @ 187717408Salanb const char *@var{format}, va_list @var{args}) 187817408Salanb 187917408SalanbLike @code{vsprintf}, but instead of passing a pointer to a buffer, 188017408Salanbyou pass a pointer to a pointer. This function will compute the size 188117408Salanbof the buffer needed, allocate memory with @code{malloc}, and store a 188216288Salanbpointer to the allocated memory in @code{*@var{resptr}}. The value 1883returned is the same as @code{vsprintf} would return. If memory could 1884not be allocated, minus one is returned and @code{NULL} is stored in 1885@code{*@var{resptr}}. 1886 1887@end deftypefn 1888 1889@c vfork.c:6 1890@deftypefn Supplemental int vfork (void) 1891 1892Emulates @code{vfork} by calling @code{fork} and returning its value. 1893 1894@end deftypefn 1895 1896@c vprintf.c:3 1897@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap}) 1898@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, @ 1899 const char *@var{format}, va_list @var{ap}) 1900@deftypefnx Supplemental int vsprintf (char *@var{str}, @ 1901 const char *@var{format}, va_list @var{ap}) 1902 1903These functions are the same as @code{printf}, @code{fprintf}, and 1904@code{sprintf}, respectively, except that they are called with a 1905@code{va_list} instead of a variable number of arguments. Note that 1906they do not call @code{va_end}; this is the application's 1907responsibility. In @libib{} they are implemented in terms of the 1908nonstandard but common function @code{_doprnt}. 1909 1910@end deftypefn 1911 1912@c vsnprintf.c:28 1913@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, @ 1914 const char *@var{format}, va_list @var{ap}) 1915 1916This function is similar to @code{vsprintf}, but it will write to 1917@var{buf} at most @code{@var{n}-1} bytes of text, followed by a 1918terminating null byte, for a total of @var{n} bytes. On error the 1919return value is -1, otherwise it returns the number of characters that 1920would have been printed had @var{n} been sufficiently large, 1921regardless of the actual value of @var{n}. Note some pre-C99 system 1922libraries do not implement this correctly so users cannot generally 1923rely on the return value if the system version of this function is 1924used. 1925 1926@end deftypefn 1927 1928@c waitpid.c:3 1929@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int) 1930 1931This is a wrapper around the @code{wait} function. Any ``special'' 1932values of @var{pid} depend on your implementation of @code{wait}, as 1933does the return value. The third argument is unused in @libib{}. 1934 1935@end deftypefn 1936 1937@c argv.c:289 1938@deftypefn Extension int writeargv (char * const *@var{argv}, FILE *@var{file}) 1939 1940Write each member of ARGV, handling all necessary quoting, to the file 1941named by FILE, separated by whitespace. Return 0 on success, non-zero 1942if an error occurred while writing to FILE. 1943 1944@end deftypefn 1945 1946@c xasprintf.c:31 1947@deftypefn Replacement char* xasprintf (const char *@var{format}, ...) 1948 1949Print to allocated string without fail. If @code{xasprintf} fails, 1950this will print a message to @code{stderr} (using the name set by 1951@code{xmalloc_set_program_name}, if any) and then call @code{xexit}. 1952 1953@end deftypefn 1954 1955@c xatexit.c:11 1956@deftypefun int xatexit (void (*@var{fn}) (void)) 1957 1958Behaves as the standard @code{atexit} function, but with no limit on 1959the number of registered functions. Returns 0 on success, or @minus{}1 on 1960failure. If you use @code{xatexit} to register functions, you must use 1961@code{xexit} to terminate your program. 1962 1963@end deftypefun 1964 1965@c xmalloc.c:38 1966@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize}) 1967 1968Allocate memory without fail, and set it to zero. This routine functions 1969like @code{calloc}, but will behave the same as @code{xmalloc} if memory 1970cannot be found. 1971 1972@end deftypefn 1973 1974@c xexit.c:22 1975@deftypefn Replacement void xexit (int @var{code}) 1976 1977Terminates the program. If any functions have been registered with 1978the @code{xatexit} replacement function, they will be called first. 1979Termination is handled via the system's normal @code{exit} call. 1980 1981@end deftypefn 1982 1983@c xmalloc.c:22 1984@deftypefn Replacement void* xmalloc (size_t) 1985 1986Allocate memory without fail. If @code{malloc} fails, this will print 1987a message to @code{stderr} (using the name set by 1988@code{xmalloc_set_program_name}, 1989if any) and then call @code{xexit}. Note that it is therefore safe for 1990a program to contain @code{#define malloc xmalloc} in its source. 1991 1992@end deftypefn 1993 1994@c xmalloc.c:53 1995@deftypefn Replacement void xmalloc_failed (size_t) 1996 1997This function is not meant to be called by client code, and is listed 1998here for completeness only. If any of the allocation routines fail, this 1999function will be called to print an error message and terminate execution. 2000 2001@end deftypefn 2002 2003@c xmalloc.c:46 2004@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name}) 2005 2006You can use this to set the name of the program used by 2007@code{xmalloc_failed} when printing a failure message. 2008 2009@end deftypefn 2010 2011@c xmemdup.c:7 2012@deftypefn Replacement void* xmemdup (void *@var{input}, @ 2013 size_t @var{copy_size}, size_t @var{alloc_size}) 2014 2015Duplicates a region of memory without fail. First, @var{alloc_size} bytes 2016are allocated, then @var{copy_size} bytes from @var{input} are copied into 2017it, and the new memory is returned. If fewer bytes are copied than were 2018allocated, the remaining memory is zeroed. 2019 2020@end deftypefn 2021 2022@c xmalloc.c:32 2023@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size}) 2024Reallocate memory without fail. This routine functions like @code{realloc}, 2025but will behave the same as @code{xmalloc} if memory cannot be found. 2026 2027@end deftypefn 2028 2029@c xstrdup.c:7 2030@deftypefn Replacement char* xstrdup (const char *@var{s}) 2031 2032Duplicates a character string without fail, using @code{xmalloc} to 2033obtain memory. 2034 2035@end deftypefn 2036 2037@c xstrerror.c:7 2038@deftypefn Replacement char* xstrerror (int @var{errnum}) 2039 2040Behaves exactly like the standard @code{strerror} function, but 2041will never return a @code{NULL} pointer. 2042 2043@end deftypefn 2044 2045@c xstrndup.c:23 2046@deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n}) 2047 2048Returns a pointer to a copy of @var{s} with at most @var{n} characters 2049without fail, using @code{xmalloc} to obtain memory. The result is 2050always NUL terminated. 2051 2052@end deftypefn 2053 2054@c xvasprintf.c:38 2055@deftypefn Replacement char* xvasprintf (const char *@var{format}, va_list @var{args}) 2056 2057Print to allocated string without fail. If @code{xvasprintf} fails, 2058this will print a message to @code{stderr} (using the name set by 2059@code{xmalloc_set_program_name}, if any) and then call @code{xexit}. 2060 2061@end deftypefn 2062 2063 2064