X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=libiberty%2Ffunctions.texi;h=1784ae720a1b935378b52b74e3f20ce407364e50;hb=de54374205650be71237ce51ef7981d30ddd78dc;hp=9f49ff484d60813ed770e83b56ca4f6bc79f4080;hpb=6dd7f013b41d1577eba29df0f52f34a513fdeb4c;p=deliverable%2Fbinutils-gdb.git diff --git a/libiberty/functions.texi b/libiberty/functions.texi index 9f49ff484d..1784ae720a 100644 --- a/libiberty/functions.texi +++ b/libiberty/functions.texi @@ -1,29 +1,7 @@ @c Automatically generated from *.c and others (the comments before @c each entry tell you which file and where in that file). DO NOT EDIT! @c Edit the *.c files, configure with --enable-maintainer-mode, -@c and let gather-docs build you a new copy. - -@c safe-ctype.c:25 -@defvr Extension HOST_CHARSET -This macro indicates the basic character set and encoding used by the -host: more precisely, the encoding used for character constants in -preprocessor @samp{#if} statements (the C "execution character set"). -It is defined by @file{safe-ctype.h}, and will be an integer constant -with one of the following values: - -@ftable @code -@item HOST_CHARSET_UNKNOWN -The host character set is unknown - that is, not one of the next two -possibilities. - -@item HOST_CHARSET_ASCII -The host character set is ASCII. - -@item HOST_CHARSET_EBCDIC -The host character set is some variant of EBCDIC. (Only one of the -nineteen EBCDIC varying characters is tested; exercise caution.) -@end ftable -@end defvr +@c run 'make stamp-functions' and gather-docs will build a new copy. @c alloca.c:26 @deftypefn Replacement void* alloca (size_t @var{size}) @@ -91,7 +69,9 @@ Copies @var{length} bytes from memory region @var{in} to region @end deftypefn @c bsearch.c:33 -@deftypefn Supplemental void* bsearch (const void *@var{key}, const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, int (*@var{compar})(const void *, const void *)) +@deftypefn Supplemental void* bsearch (const void *@var{key}, @ + const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, @ + int (*@var{compar})(const void *, const void *)) Performs a search over an array of @var{nmemb} elements pointed to by @var{base} for a member that matches the object pointed to by @var{key}. @@ -104,7 +84,7 @@ is respectively less than, matching, or greater than the array member. @end deftypefn -@c argv.c:124 +@c argv.c:138 @deftypefn Extension char** buildargv (char *@var{sp}) Given a pointer to a string, parse the string extracting fields @@ -115,7 +95,7 @@ remains unchanged. The last element of the vector is followed by a @code{NULL} element. All of the memory for the pointer array and copies of the string -is obtained from @code{malloc}. All of the memory can be returned to the +is obtained from @code{xmalloc}. All of the memory can be returned to the system with the single function call @code{freeargv}, which takes the returned result of @code{buildargv}, as it's argument. @@ -145,7 +125,17 @@ Uses @code{malloc} to allocate storage for @var{nelem} objects of @end deftypefn -@c choose-temp.c:42 +@c filename_cmp.c:201 +@deftypefn Extension int canonical_filename_eq (const char *@var{a}, const char *@var{b}) + +Return non-zero if file names @var{a} and @var{b} are equivalent. +This function compares the canonical versions of the filenames as returned by +@code{lrealpath()}, so that so that different file names pointing to the same +underlying file are treated as being identical. + +@end deftypefn + +@c choose-temp.c:45 @deftypefn Extension char* choose_temp_base (void) Return a prefix for temporary file names or @code{NULL} if unable to @@ -158,8 +148,8 @@ not recommended. @end deftypefn -@c make-temp-file.c:87 -@deftypefn Replacement char* choose_tmpdir () +@c make-temp-file.c:95 +@deftypefn Replacement const char* choose_tmpdir () Returns a pointer to a directory path suitable for creating temporary files in. @@ -176,17 +166,53 @@ number of seconds used. @end deftypefn @c concat.c:24 -@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL}) +@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @ + @dots{}, @code{NULL}) Concatenate zero or more of strings and return the result in freshly -@code{xmalloc}ed memory. Returns @code{NULL} if insufficient memory is -available. The argument list is terminated by the first @code{NULL} -pointer encountered. Pointers to empty strings are ignored. +@code{xmalloc}ed memory. The argument list is terminated by the first +@code{NULL} pointer encountered. Pointers to empty strings are ignored. @end deftypefn -@c argv.c:52 -@deftypefn Extension char** dupargv (char **@var{vector}) +@c argv.c:487 +@deftypefn Extension int countargv (char * const *@var{argv}) + +Return the number of elements in @var{argv}. +Returns zero if @var{argv} is NULL. + +@end deftypefn + +@c crc32.c:140 +@deftypefn Extension {unsigned int} crc32 (const unsigned char *@var{buf}, @ + int @var{len}, unsigned int @var{init}) + +Compute the 32-bit CRC of @var{buf} which has length @var{len}. The +starting value is @var{init}; this may be used to compute the CRC of +data split across multiple buffers by passing the return value of each +call as the @var{init} parameter of the next. + +This is used by the @command{gdb} remote protocol for the @samp{qCRC} +command. In order to get the same results as gdb for a block of data, +you must pass the first CRC parameter as @code{0xffffffff}. + +This CRC can be specified as: + + Width : 32 + Poly : 0x04c11db7 + Init : parameter, typically 0xffffffff + RefIn : false + RefOut : false + XorOut : 0 + +This differs from the "standard" CRC-32 algorithm in that the values +are not reflected, and there is no final XOR value. These differences +make it easy to compose the values of multiple blocks. + +@end deftypefn + +@c argv.c:59 +@deftypefn Extension char** dupargv (char * const *@var{vector}) Duplicate an argument vector. Simply scans through @var{vector}, duplicating each argument until the terminating @code{NULL} is found. @@ -196,7 +222,7 @@ argument vector. @end deftypefn -@c strerror.c:567 +@c strerror.c:572 @deftypefn Extension int errno_max (void) Returns the maximum @code{errno} value for which a corresponding @@ -214,7 +240,7 @@ symbolic name or message. @end deftypefn -@c argv.c:293 +@c argv.c:344 @deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp}) The @var{argcp} and @code{argvp} arguments are pointers to the usual @@ -249,8 +275,9 @@ and inode numbers. @end deftypefn -@c fopen_unlocked.c:48 -@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, const char * @var{mode}) +@c fopen_unlocked.c:49 +@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, @ + const char * @var{mode}) Opens and returns a @code{FILE} pointer via @code{fdopen}. If the operating system supports it, ensure that the stream is setup to avoid @@ -268,8 +295,61 @@ value 1). If @var{valu} is zero, zero is returned. @end deftypefn +@c filename_cmp.c:37 +@deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2}) + +Return zero if the two file names @var{s1} and @var{s2} are equivalent. +If not equivalent, the returned value is similar to what @code{strcmp} +would return. In other words, it returns a negative value if @var{s1} +is less than @var{s2}, or a positive value if @var{s2} is greater than +@var{s2}. + +This function does not normalize file names. As a result, this function +will treat filenames that are spelled differently as different even in +the case when the two filenames point to the same underlying file. +However, it does handle the fact that on DOS-like file systems, forward +and backward slashes are equal. + +@end deftypefn + +@c filename_cmp.c:183 +@deftypefn Extension int filename_eq (const void *@var{s1}, const void *@var{s2}) + +Return non-zero if file names @var{s1} and @var{s2} are equivalent. +This function is for use with hashtab.c hash tables. + +@end deftypefn + +@c filename_cmp.c:152 +@deftypefn Extension hashval_t filename_hash (const void *@var{s}) + +Return the hash value for file name @var{s} that will be compared +using filename_cmp. +This function is for use with hashtab.c hash tables. + +@end deftypefn + +@c filename_cmp.c:94 +@deftypefn Extension int filename_ncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) + +Return zero if the two file names @var{s1} and @var{s2} are equivalent +in range @var{n}. +If not equivalent, the returned value is similar to what @code{strncmp} +would return. In other words, it returns a negative value if @var{s1} +is less than @var{s2}, or a positive value if @var{s2} is greater than +@var{s2}. + +This function does not normalize file names. As a result, this function +will treat filenames that are spelled differently as different even in +the case when the two filenames point to the same underlying file. +However, it does handle the fact that on DOS-like file systems, forward +and backward slashes are equal. + +@end deftypefn + @c fnmatch.txh:1 -@deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags}) +@deftypefn Replacement int fnmatch (const char *@var{pattern}, @ + const char *@var{string}, int @var{flags}) Matches @var{string} against @var{pattern}, returning zero if it matches, @code{FNM_NOMATCH} if not. @var{pattern} may contain the @@ -319,7 +399,8 @@ Ignores case when performing the comparison. @end deftypefn @c fopen_unlocked.c:39 -@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, const char * @var{mode}) +@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, @ + const char * @var{mode}) Opens and returns a @code{FILE} pointer via @code{fopen}. If the operating system supports it, ensure that the stream is setup to avoid @@ -328,7 +409,7 @@ unchanged. @end deftypefn -@c argv.c:97 +@c argv.c:93 @deftypefn Extension void freeargv (char **@var{vector}) Free an argument vector that was built using @code{buildargv}. Simply @@ -338,8 +419,9 @@ itself. @end deftypefn -@c fopen_unlocked.c:57 -@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, const char * @var{mode}, FILE * @var{stream}) +@c fopen_unlocked.c:59 +@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, @ + const char * @var{mode}, FILE * @var{stream}) Opens and returns a @code{FILE} pointer via @code{freopen}. If the operating system supports it, ensure that the stream is setup to avoid @@ -348,7 +430,7 @@ unchanged. @end deftypefn -@c getruntime.c:82 +@c getruntime.c:86 @deftypefn Replacement long get_run_time (void) Returns the time used so far, in microseconds. If possible, this is @@ -432,6 +514,46 @@ systems. @end deftypefn +@c safe-ctype.c:24 +@defvr Extension HOST_CHARSET +This macro indicates the basic character set and encoding used by the +host: more precisely, the encoding used for character constants in +preprocessor @samp{#if} statements (the C "execution character set"). +It is defined by @file{safe-ctype.h}, and will be an integer constant +with one of the following values: + +@ftable @code +@item HOST_CHARSET_UNKNOWN +The host character set is unknown - that is, not one of the next two +possibilities. + +@item HOST_CHARSET_ASCII +The host character set is ASCII. + +@item HOST_CHARSET_EBCDIC +The host character set is some variant of EBCDIC. (Only one of the +nineteen EBCDIC varying characters is tested; exercise caution.) +@end ftable +@end defvr + +@c hashtab.c:327 +@deftypefn Supplemental htab_t htab_create_typed_alloc (size_t @var{size}, @ +htab_hash @var{hash_f}, htab_eq @var{eq_f}, htab_del @var{del_f}, @ +htab_alloc @var{alloc_tab_f}, htab_alloc @var{alloc_f}, @ +htab_free @var{free_f}) + +This function creates a hash table that uses two different allocators +@var{alloc_tab_f} and @var{alloc_f} to use for allocating the table itself +and its entries respectively. This is useful when variables of different +types need to be allocated with different allocators. + +The created hash table is slightly larger than @var{size} and it is +initially empty (all the hash table entries are @code{HTAB_EMPTY_ENTRY}). +The function returns the created hash table, or @code{NULL} if memory +allocation fails. + +@end deftypefn + @c index.c:5 @deftypefn Supplemental char* index (char *@var{s}, int @var{c}) @@ -442,7 +564,8 @@ deprecated in new programs in favor of @code{strchr}. @end deftypefn @c insque.c:6 -@deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred}) +@deftypefn Supplemental void insque (struct qelem *@var{elem}, @ + struct qelem *@var{pred}) @deftypefnx Supplemental void remque (struct qelem *@var{elem}) Routines to manipulate queues built from doubly linked lists. The @@ -462,7 +585,7 @@ struct qelem @{ @end deftypefn -@c safe-ctype.c:46 +@c safe-ctype.c:45 @deffn Extension ISALPHA (@var{c}) @deffnx Extension ISALNUM (@var{c}) @deffnx Extension ISBLANK (@var{c}) @@ -512,7 +635,7 @@ false for characters with numeric values from 128 to 255. @end itemize @end deffn -@c safe-ctype.c:95 +@c safe-ctype.c:94 @deffn Extension ISIDNUM (@var{c}) @deffnx Extension ISIDST (@var{c}) @deffnx Extension IS_VSPACE (@var{c}) @@ -560,8 +683,9 @@ components will be simplified. The returned value will be allocated using @end deftypefn -@c make-relative-prefix.c:24 -@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, const char *@var{bin_prefix}, const char *@var{prefix}) +@c make-relative-prefix.c:23 +@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, @ + const char *@var{bin_prefix}, const char *@var{prefix}) Given three paths @var{progname}, @var{bin_prefix}, @var{prefix}, return the path that is in the same position relative to @@ -585,7 +709,7 @@ relative prefix can be found, return @code{NULL}. @end deftypefn -@c make-temp-file.c:137 +@c make-temp-file.c:173 @deftypefn Replacement char* make_temp_file (const char *@var{suffix}) Return a temporary file name (as a string) or @code{NULL} if unable to @@ -595,7 +719,8 @@ string is @code{malloc}ed, and the temporary file has been created. @end deftypefn @c memchr.c:3 -@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n}) +@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, @ + size_t @var{n}) This function searches memory starting at @code{*@var{s}} for the character @var{c}. The search only ends with the first occurrence of @@ -608,7 +733,8 @@ returned. @end deftypefn @c memcmp.c:6 -@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count}) +@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, @ + size_t @var{count}) Compares the first @var{count} bytes of two areas of memory. Returns zero if they are the same, a value less than zero if @var{x} is @@ -619,15 +745,27 @@ as if comparing unsigned char arrays. @end deftypefn @c memcpy.c:6 -@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length}) +@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, @ + size_t @var{length}) Copies @var{length} bytes from memory region @var{in} to region @var{out}. Returns a pointer to @var{out}. @end deftypefn +@c memmem.c:20 +@deftypefn Supplemental void* memmem (const void *@var{haystack}, @ + size_t @var{haystack_len} const void *@var{needle}, size_t @var{needle_len}) + +Returns a pointer to the first occurrence of @var{needle} (length +@var{needle_len}) in @var{haystack} (length @var{haystack_len}). +Returns @code{NULL} if not found. + +@end deftypefn + @c memmove.c:6 -@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count}) +@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, @ + size_t @var{count}) Copies @var{count} bytes from memory area @var{from} to memory area @var{to}, returning a pointer to @var{to}. @@ -635,7 +773,8 @@ Copies @var{count} bytes from memory area @var{from} to memory area @end deftypefn @c mempcpy.c:23 -@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, size_t @var{length}) +@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, @ + size_t @var{length}) Copies @var{length} bytes from memory region @var{in} to region @var{out}. Returns a pointer to @var{out} + @var{length}. @@ -643,14 +782,15 @@ Copies @var{length} bytes from memory region @var{in} to region @end deftypefn @c memset.c:6 -@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count}) +@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, @ + size_t @var{count}) Sets the first @var{count} bytes of @var{s} to the constant byte @var{c}, returning a pointer to @var{s}. @end deftypefn -@c mkstemps.c:58 +@c mkstemps.c:60 @deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len}) Generate a unique temporary file name from @var{pattern}. @@ -668,15 +808,18 @@ reading and writing. @end deftypefn -@c pexecute.txh:266 +@c pexecute.txh:278 @deftypefn Extension void pex_free (struct pex_obj @var{obj}) -Clean up and free all data associated with @var{obj}. +Clean up and free all data associated with @var{obj}. If you have not +yet called @code{pex_get_times} or @code{pex_get_status}, this will +try to kill the subprocesses. @end deftypefn -@c pexecute.txh:241 -@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector}) +@c pexecute.txh:251 +@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, @ + int @var{count}, int *@var{vector}) Returns the exit status of all programs run using @var{obj}. @var{count} is the number of results expected. The results will be @@ -685,8 +828,9 @@ to @code{pex_run}. Returns 0 on error, 1 on success. @end deftypefn -@c pexecute.txh:250 -@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector}) +@c pexecute.txh:261 +@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, @ + int @var{count}, struct pex_time *@var{vector}) Returns the process execution times of all programs run using @var{obj}. @var{count} is the number of results expected. The @@ -703,7 +847,8 @@ process times, all the fields will be set to @code{0}. @end deftypefn @c pexecute.txh:2 -@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase}) +@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, @ + const char *@var{pname}, const char *@var{tempbase}) Prepare to execute one or more programs, with standard output of each program fed to standard input of the next. This is a system @@ -734,8 +879,9 @@ temporary files; it may be @code{NULL} to use a randomly chosen name. @end deftypefn -@c pexecute.txh:155 -@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{in_name}) +@c pexecute.txh:161 +@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, @ + int @var{flags}, const char *@var{in_name}) Return a stream for a temporary file to pass to the first program in the pipeline as input. @@ -752,8 +898,9 @@ binary mode; otherwise, open it in the default mode. Including @code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix. @end deftypefn -@c pexecute.txh:172 -@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, int @var{binary}) +@c pexecute.txh:179 +@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, @ + int @var{binary}) Return a stream @var{fp} for a pipe connected to the standard input of the first program in the pipeline; @var{fp} is opened for writing. @@ -797,8 +944,11 @@ the output pipe is you, but you are blocked on the input pipe. @end deftypefn -@c pexecute.txh:272 -@deftypefn Extension {const char *} pex_one (int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, int *@var{status}, int *@var{err}) +@c pexecute.txh:286 +@deftypefn Extension {const char *} pex_one (int @var{flags}, @ + const char *@var{executable}, char * const *@var{argv}, @ + const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, @ + int *@var{status}, int *@var{err}) An interface to permit the easy execution of a single program. The return value and most of the parameters are as @@ -810,8 +960,9 @@ be set to the exit status of the program. @end deftypefn -@c pexecute.txh:228 -@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, int @var{binary}) +@c pexecute.txh:237 +@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, @ + int @var{binary}) Returns a @code{FILE} pointer which may be used to read the standard error of the last program in the pipeline. When this is used, @@ -823,8 +974,9 @@ it will be closed by @code{pex_free}. @end deftypefn -@c pexecute.txh:216 -@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary}) +@c pexecute.txh:224 +@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, @ + int @var{binary}) Returns a @code{FILE} pointer which may be used to read the standard output of the last program in the pipeline. When this is used, @@ -836,8 +988,10 @@ it will be closed by @code{pex_free}. @end deftypefn -@c pexecute.txh:33 -@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{outname}, const char *@var{errname}, int *@var{err}) +@c pexecute.txh:34 +@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, @ + int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ + const char *@var{outname}, const char *@var{errname}, int *@var{err}) Execute one program in a pipeline. On success this returns @code{NULL}. On failure it returns an error message, a statically @@ -946,8 +1100,11 @@ value, or to 0 if there is no relevant @code{errno}. @end deftypefn -@c pexecute.txh:142 -@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, char * const *@var{env}, int @var{env_size}, const char *@var{outname}, const char *@var{errname}, int *@var{err}) +@c pexecute.txh:145 +@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, @ + int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ + char * const *@var{env}, int @var{env_size}, const char *@var{outname}, @ + const char *@var{errname}, int *@var{err}) Execute one program in a pipeline, permitting the environment for the program to be specified. Behaviour and parameters not listed below are @@ -960,8 +1117,11 @@ form @code{VAR=VALUE}, with the exception of the last element that must be @end deftypefn -@c pexecute.txh:284 -@deftypefn Extension int pexecute (const char *@var{program}, char * const *@var{argv}, const char *@var{this_pname}, const char *@var{temp_base}, char **@var{errmsg_fmt}, char **@var{errmsg_arg}, int @var{flags}) +@c pexecute.txh:301 +@deftypefn Extension int pexecute (const char *@var{program}, @ + char * const *@var{argv}, const char *@var{this_pname}, @ + const char *@var{temp_base}, char **@var{errmsg_fmt}, @ + char **@var{errmsg_arg}, int @var{flags}) This is the old interface to execute one or more programs. It is still supported for compatibility purposes, but is no longer @@ -969,7 +1129,7 @@ documented. @end deftypefn -@c strsignal.c:539 +@c strsignal.c:541 @deftypefn Supplemental void psignal (int @var{signo}, char *@var{message}) Print @var{message} to the standard error, followed by a colon, @@ -988,7 +1148,7 @@ name is unset/removed. @end deftypefn -@c pexecute.txh:292 +@c pexecute.txh:312 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) Another part of the old execution interface. @@ -998,7 +1158,8 @@ Another part of the old execution interface. @c random.c:39 @deftypefn Supplement {long int} random (void) @deftypefnx Supplement void srandom (unsigned int @var{seed}) -@deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n}) +@deftypefnx Supplement void* initstate (unsigned int @var{seed}, @ + void *@var{arg_state}, unsigned long @var{n}) @deftypefnx Supplement void* setstate (void *@var{arg_state}) Random number functions. @code{random} returns a random number in the @@ -1010,8 +1171,9 @@ control over the state of the random number generator. @end deftypefn -@c concat.c:173 -@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL}) +@c concat.c:160 +@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @ + @dots{}, @code{NULL}) Same as @code{concat}, except that if @var{optr} is not @code{NULL} it is freed after the string is created. This is intended to be useful @@ -1042,7 +1204,8 @@ deprecated in new programs in favor of @code{strrchr}. @end deftypefn @c setenv.c:22 -@deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite}) +@deftypefn Supplemental int setenv (const char *@var{name}, @ + const char *@var{value}, int @var{overwrite}) @deftypefnx Supplemental void unsetenv (const char *@var{name}) @code{setenv} adds @var{name} to the environment with value @@ -1053,6 +1216,14 @@ environment. This implementation is not safe for multithreaded code. @end deftypefn +@c setproctitle.c:31 +@deftypefn Supplemental void setproctitle (const char *@var{fmt}, ...) + +Set the title of a process to @var{fmt}. va args not supported for now, +but defined for compatibility with BSD. + +@end deftypefn + @c strsignal.c:348 @deftypefn Extension int signo_max (void) @@ -1080,16 +1251,220 @@ be the value @code{1}). @end deftypefn +@c simple-object.txh:96 +@deftypefn Extension {const char *} simple_object_attributes_compare @ + (simple_object_attributes *@var{attrs1}, simple_object_attributes *@var{attrs2}, @ + int *@var{err}) + +Compare @var{attrs1} and @var{attrs2}. If they could be linked +together without error, return @code{NULL}. Otherwise, return an +error message and set @code{*@var{err}} to an errno value or @code{0} +if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:81 +@deftypefn Extension {simple_object_attributes *} simple_object_fetch_attributes @ + (simple_object_read *@var{simple_object}, const char **@var{errmsg}, int *@var{err}) + +Fetch the attributes of @var{simple_object}. The attributes are +internal information such as the format of the object file, or the +architecture it was compiled for. This information will persist until +@code{simple_object_attributes_release} is called, even if +@var{simple_object} itself is released. + +On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an +error message, and sets @code{*@var{err}} to an errno value or +@code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:49 +@deftypefn Extension {int} simple_object_find_section @ + (simple_object_read *@var{simple_object} off_t *@var{offset}, @ + off_t *@var{length}, const char **@var{errmsg}, int *@var{err}) + +Look for the section @var{name} in @var{simple_object}. This returns +information for the first section with that name. + +If found, return 1 and set @code{*@var{offset}} to the offset in the +file of the section contents and set @code{*@var{length}} to the +length of the section contents. The value in @code{*@var{offset}} +will be relative to the offset passed to +@code{simple_object_open_read}. + +If the section is not found, and no error occurs, +@code{simple_object_find_section} returns @code{0} and set +@code{*@var{errmsg}} to @code{NULL}. + +If an error occurs, @code{simple_object_find_section} returns +@code{0}, sets @code{*@var{errmsg}} to an error message, and sets +@code{*@var{err}} to an errno value or @code{0} if there is no +relevant errno. + +@end deftypefn + +@c simple-object.txh:27 +@deftypefn Extension {const char *} simple_object_find_sections @ + (simple_object_read *@var{simple_object}, int (*@var{pfn}) (void *@var{data}, @ + const char *@var{name}, off_t @var{offset}, off_t @var{length}), @ + void *@var{data}, int *@var{err}) + +This function calls @var{pfn} for each section in @var{simple_object}. +It calls @var{pfn} with the section name, the offset within the file +of the section contents, and the length of the section contents. The +offset within the file is relative to the offset passed to +@code{simple_object_open_read}. The @var{data} argument to this +function is passed along to @var{pfn}. + +If @var{pfn} returns @code{0}, the loop over the sections stops and +@code{simple_object_find_sections} returns. If @var{pfn} returns some +other value, the loop continues. + +On success @code{simple_object_find_sections} returns. On error it +returns an error string, and sets @code{*@var{err}} to an errno value +or @code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:2 +@deftypefn Extension {simple_object_read *} simple_object_open_read @ + (int @var{descriptor}, off_t @var{offset}, const char *{segment_name}, @ + const char **@var{errmsg}, int *@var{err}) + +Opens an object file for reading. Creates and returns an +@code{simple_object_read} pointer which may be passed to other +functions to extract data from the object file. + +@var{descriptor} holds a file descriptor which permits reading. + +@var{offset} is the offset into the file; this will be @code{0} in the +normal case, but may be a different value when reading an object file +in an archive file. + +@var{segment_name} is only used with the Mach-O file format used on +Darwin aka Mac OS X. It is required on that platform, and means to +only look at sections within the segment with that name. The +parameter is ignored on other systems. + +If an error occurs, this functions returns @code{NULL} and sets +@code{*@var{errmsg}} to an error string and sets @code{*@var{err}} to +an errno value or @code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:107 +@deftypefn Extension {void} simple_object_release_attributes @ + (simple_object_attributes *@var{attrs}) + +Release all resources associated with @var{attrs}. + +@end deftypefn + +@c simple-object.txh:73 +@deftypefn Extension {void} simple_object_release_read @ + (simple_object_read *@var{simple_object}) + +Release all resources associated with @var{simple_object}. This does +not close the file descriptor. + +@end deftypefn + +@c simple-object.txh:184 +@deftypefn Extension {void} simple_object_release_write @ + (simple_object_write *@var{simple_object}) + +Release all resources associated with @var{simple_object}. + +@end deftypefn + +@c simple-object.txh:114 +@deftypefn Extension {simple_object_write *} simple_object_start_write @ + (simple_object_attributes @var{attrs}, const char *@var{segment_name}, @ + const char **@var{errmsg}, int *@var{err}) + +Start creating a new object file using the object file format +described in @var{attrs}. You must fetch attribute information from +an existing object file before you can create a new one. There is +currently no support for creating an object file de novo. + +@var{segment_name} is only used with Mach-O as found on Darwin aka Mac +OS X. The parameter is required on that target. It means that all +sections are created within the named segment. It is ignored for +other object file formats. + +On error @code{simple_object_start_write} returns @code{NULL}, sets +@code{*@var{ERRMSG}} to an error message, and sets @code{*@var{err}} +to an errno value or @code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:153 +@deftypefn Extension {const char *} simple_object_write_add_data @ + (simple_object_write *@var{simple_object}, @ + simple_object_write_section *@var{section}, const void *@var{buffer}, @ + size_t @var{size}, int @var{copy}, int *@var{err}) + +Add data @var{buffer}/@var{size} to @var{section} in +@var{simple_object}. If @var{copy} is non-zero, the data will be +copied into memory if necessary. If @var{copy} is zero, @var{buffer} +must persist until @code{simple_object_write_to_file} is called. is +released. + +On success this returns @code{NULL}. On error this returns an error +message, and sets @code{*@var{err}} to an errno value or 0 if there is +no relevant erro. + +@end deftypefn + +@c simple-object.txh:134 +@deftypefn Extension {simple_object_write_section *} simple_object_write_create_section @ + (simple_object_write *@var{simple_object}, const char *@var{name}, @ + unsigned int @var{align}, const char **@var{errmsg}, int *@var{err}) + +Add a section to @var{simple_object}. @var{name} is the name of the +new section. @var{align} is the required alignment expressed as the +number of required low-order 0 bits (e.g., 2 for alignment to a 32-bit +boundary). + +The section is created as containing data, readable, not writable, not +executable, not loaded at runtime. The section is not written to the +file until @code{simple_object_write_to_file} is called. + +On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an +error message, and sets @code{*@var{err}} to an errno value or +@code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:170 +@deftypefn Extension {const char *} simple_object_write_to_file @ + (simple_object_write *@var{simple_object}, int @var{descriptor}, int *@var{err}) + +Write the complete object file to @var{descriptor}, an open file +descriptor. This writes out all the data accumulated by calls to +@code{simple_object_write_create_section} and +@var{simple_object_write_add_data}. + +This returns @code{NULL} on success. On error this returns an error +message and sets @code{*@var{err}} to an errno value or @code{0} if +there is no relevant errno. + +@end deftypefn + @c snprintf.c:28 -@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...) +@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, @ + const char *@var{format}, ...) -This function is similar to sprintf, but it will print at most @var{n} -characters. On error the return value is -1, otherwise it returns the -number of characters that would have been printed had @var{n} been -sufficiently large, regardless of the actual value of @var{n}. Note -some pre-C99 system libraries do not implement this correctly so users -cannot generally rely on the return value if the system version of -this function is used. +This function is similar to @code{sprintf}, but it will write to +@var{buf} at most @code{@var{n}-1} bytes of text, followed by a +terminating null byte, for a total of @var{n} bytes. +On error the return value is -1, otherwise it returns the number of +bytes, not including the terminating null byte, that would have been +written had @var{n} been sufficiently large, regardless of the actual +value of @var{n}. Note some pre-C99 system libraries do not implement +this correctly so users cannot generally rely on the return value if +the system version of this function is used. @end deftypefn @@ -1102,6 +1477,38 @@ valid until at least the next call. @end deftypefn +@c splay-tree.c:305 +@deftypefn Supplemental splay_tree splay_tree_new_with_typed_alloc @ +(splay_tree_compare_fn @var{compare_fn}, @ +splay_tree_delete_key_fn @var{delete_key_fn}, @ +splay_tree_delete_value_fn @var{delete_value_fn}, @ +splay_tree_allocate_fn @var{tree_allocate_fn}, @ +splay_tree_allocate_fn @var{node_allocate_fn}, @ +splay_tree_deallocate_fn @var{deallocate_fn}, @ +void * @var{allocate_data}) + +This function creates a splay tree that uses two different allocators +@var{tree_allocate_fn} and @var{node_allocate_fn} to use for allocating the +tree itself and its nodes respectively. This is useful when variables of +different types need to be allocated with different allocators. + +The splay tree will use @var{compare_fn} to compare nodes, +@var{delete_key_fn} to deallocate keys, and @var{delete_value_fn} to +deallocate values. Keys and values will be deallocated when the +tree is deleted using splay_tree_delete or when a node is removed +using splay_tree_remove. splay_tree_insert will release the previously +inserted key and value using @var{delete_key_fn} and @var{delete_value_fn} +if the inserted key is already found in the tree. + +@end deftypefn + +@c stack-limit.c:28 +@deftypefn Extension void stack_limit_increase (unsigned long @var{pref}) + +Attempt to increase stack size limit to @var{pref} bytes if possible. + +@end deftypefn + @c stpcpy.c:23 @deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src}) @@ -1111,7 +1518,8 @@ Copies the string @var{src} into @var{dst}. Returns a pointer to @end deftypefn @c stpncpy.c:23 -@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, size_t @var{len}) +@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, @ + size_t @var{len}) Copies the string @var{src} into @var{dst}, copying exactly @var{len} and padding with zeros if necessary. If @var{len} < strlen(@var{src}) @@ -1144,7 +1552,7 @@ Returns a pointer to a copy of @var{s} in memory obtained from @end deftypefn -@c strerror.c:670 +@c strerror.c:675 @deftypefn Replacement {const char*} strerrno (int @var{errnum}) Given an error number returned from a system call (typically returned @@ -1164,7 +1572,7 @@ valid until the next call to @code{strerrno}. @end deftypefn -@c strerror.c:603 +@c strerror.c:608 @deftypefn Supplemental char* strerror (int @var{errnoval}) Maps an @code{errno} number to an error message string, the contents @@ -1193,7 +1601,8 @@ A case-insensitive @code{strncmp}. @end deftypefn @c strncmp.c:6 -@deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) +@deftypefn Supplemental int strncmp (const char *@var{s1}, @ + const char *@var{s2}, size_t @var{n}) Compares the first @var{n} bytes of two strings, returning a value as @code{strcmp}. @@ -1209,6 +1618,16 @@ memory was available. The result is always NUL terminated. @end deftypefn +@c strnlen.c:6 +@deftypefn Supplemental size_t strnlen (const char *@var{s}, size_t @var{maxlen}) + +Returns the length of @var{s}, as with @code{strlen}, but never looks +past the first @var{maxlen} characters in the string. If there is no +'\0' character in the first @var{maxlen} characters, returns +@var{maxlen}. + +@end deftypefn + @c strrchr.c:6 @deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c}) @@ -1239,7 +1658,7 @@ call to @code{strsignal}. @end deftypefn -@c strsignal.c:446 +@c strsignal.c:448 @deftypefn Extension {const char*} strsigno (int @var{signo}) Given an signal number, returns a pointer to a string containing the @@ -1270,7 +1689,8 @@ length, the function returns @var{string}. @end deftypefn @c strtod.c:27 -@deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr}) +@deftypefn Supplemental double strtod (const char *@var{string}, @ + char **@var{endptr}) This ISO C function converts the initial portion of @var{string} to a @code{double}. If @var{endptr} is not @code{NULL}, a pointer to the @@ -1281,7 +1701,7 @@ the location referenced by @var{endptr}. @end deftypefn -@c strerror.c:729 +@c strerror.c:734 @deftypefn Extension int strtoerrno (const char *@var{name}) Given the symbolic name of a error number (e.g., @code{EACCES}), map it @@ -1290,8 +1710,10 @@ to an errno value. If no translation is found, returns 0. @end deftypefn @c strtol.c:33 -@deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base}) -@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base}) +@deftypefn Supplemental {long int} strtol (const char *@var{string}, @ + char **@var{endptr}, int @var{base}) +@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, @ + char **@var{endptr}, int @var{base}) The @code{strtol} function converts the string in @var{string} to a long integer value according to the given @var{base}, which must be @@ -1305,7 +1727,25 @@ that the converted value is unsigned. @end deftypefn -@c strsignal.c:500 +@c strtoll.c:33 +@deftypefn Supplemental {long long int} strtoll (const char *@var{string}, @ + char **@var{endptr}, int @var{base}) +@deftypefnx Supplemental {unsigned long long int} strtoul (@ + const char *@var{string}, char **@var{endptr}, int @var{base}) + +The @code{strtoll} function converts the string in @var{string} to a +long long integer value according to the given @var{base}, which must be +between 2 and 36 inclusive, or be the special value 0. If @var{base} +is 0, @code{strtoll} will look for the prefixes @code{0} and @code{0x} +to indicate bases 8 and 16, respectively, else default to base 10. +When the base is 16 (either explicitly or implicitly), a prefix of +@code{0x} is allowed. The handling of @var{endptr} is as that of +@code{strtod} above. The @code{strtoull} function is the same, except +that the converted value is unsigned. + +@end deftypefn + +@c strsignal.c:502 @deftypefn Extension int strtosigno (const char *@var{name}) Given the symbolic name of a signal, map it to a signal number. If no @@ -1360,6 +1800,22 @@ This function is especially useful when dealing with filename sorting, because filenames frequently hold indices/version numbers. @end deftypefun +@c timeval-utils.c:43 +@deftypefn Extension void timeval_add (struct timeval *@var{a}, @ + struct timeval *@var{b}, struct timeval *@var{result}) + +Adds @var{a} to @var{b} and stores the result in @var{result}. + +@end deftypefn + +@c timeval-utils.c:67 +@deftypefn Extension void timeval_sub (struct timeval *@var{a}, @ + struct timeval *@var{b}, struct timeval *@var{result}) + +Subtracts @var{b} from @var{a} and stores the result in @var{result}. + +@end deftypefn + @c tmpnam.c:3 @deftypefn Supplemental char* tmpnam (char *@var{s}) @@ -1400,7 +1856,8 @@ pointer unchanged. If the @var{stream} is @code{NULL} do nothing. @end deftypefn @c vasprintf.c:47 -@deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args}) +@deftypefn Extension int vasprintf (char **@var{resptr}, @ + const char *@var{format}, va_list @var{args}) Like @code{vsprintf}, but instead of passing a pointer to a buffer, you pass a pointer to a pointer. This function will compute the size @@ -1421,8 +1878,10 @@ Emulates @code{vfork} by calling @code{fork} and returning its value. @c vprintf.c:3 @deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap}) -@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap}) -@deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap}) +@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, @ + const char *@var{format}, va_list @var{ap}) +@deftypefnx Supplemental int vsprintf (char *@var{str}, @ + const char *@var{format}, va_list @var{ap}) These functions are the same as @code{printf}, @code{fprintf}, and @code{sprintf}, respectively, except that they are called with a @@ -1434,15 +1893,18 @@ nonstandard but common function @code{_doprnt}. @end deftypefn @c vsnprintf.c:28 -@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap}) +@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, @ + const char *@var{format}, va_list @var{ap}) -This function is similar to vsprintf, but it will print at most -@var{n} characters. On error the return value is -1, otherwise it -returns the number of characters that would have been printed had -@var{n} been sufficiently large, regardless of the actual value of -@var{n}. Note some pre-C99 system libraries do not implement this -correctly so users cannot generally rely on the return value if the -system version of this function is used. +This function is similar to @code{vsprintf}, but it will write to +@var{buf} at most @code{@var{n}-1} bytes of text, followed by a +terminating null byte, for a total of @var{n} bytes. On error the +return value is -1, otherwise it returns the number of characters that +would have been printed had @var{n} been sufficiently large, +regardless of the actual value of @var{n}. Note some pre-C99 system +libraries do not implement this correctly so users cannot generally +rely on the return value if the system version of this function is +used. @end deftypefn @@ -1455,6 +1917,24 @@ does the return value. The third argument is unused in @libib{}. @end deftypefn +@c argv.c:289 +@deftypefn Extension int writeargv (char * const *@var{argv}, FILE *@var{file}) + +Write each member of ARGV, handling all necessary quoting, to the file +named by FILE, separated by whitespace. Return 0 on success, non-zero +if an error occurred while writing to FILE. + +@end deftypefn + +@c xasprintf.c:31 +@deftypefn Replacement char* xasprintf (const char *@var{format}, ...) + +Print to allocated string without fail. If @code{xasprintf} fails, +this will print a message to @code{stderr} (using the name set by +@code{xmalloc_set_program_name}, if any) and then call @code{xexit}. + +@end deftypefn + @c xatexit.c:11 @deftypefun int xatexit (void (*@var{fn}) (void)) @@ -1512,7 +1992,8 @@ You can use this to set the name of the program used by @end deftypefn @c xmemdup.c:7 -@deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size}) +@deftypefn Replacement void* xmemdup (void *@var{input}, @ + size_t @var{copy_size}, size_t @var{alloc_size}) Duplicates a region of memory without fail. First, @var{alloc_size} bytes are allocated, then @var{copy_size} bytes from @var{input} are copied into @@ -1553,4 +2034,13 @@ always NUL terminated. @end deftypefn +@c xvasprintf.c:38 +@deftypefn Replacement char* xvasprintf (const char *@var{format}, va_list @var{args}) + +Print to allocated string without fail. If @code{xvasprintf} fails, +this will print a message to @code{stderr} (using the name set by +@code{xmalloc_set_program_name}, if any) and then call @code{xexit}. + +@end deftypefn +