Daily bump.
[official-gcc.git] / libiberty / functions.texi
blobe6ab84c69990b75c84dfa83d3167dcb84484f1ad
1 @c Automatically generated from *.c and others (the comments before
2 @c each entry tell you which file and where in that file).  DO NOT EDIT!
3 @c Edit the *.c files, configure with --enable-maintainer-mode,
4 @c and let gather-docs build you a new copy.
6 @c safe-ctype.c:25
7 @defvr Extension HOST_CHARSET
8 This macro indicates the basic character set and encoding used by the
9 host: more precisely, the encoding used for character constants in
10 preprocessor @samp{#if} statements (the C "execution character set").
11 It is defined by @file{safe-ctype.h}, and will be an integer constant
12 with one of the following values:
14 @ftable @code
15 @item HOST_CHARSET_UNKNOWN
16 The host character set is unknown - that is, not one of the next two
17 possibilities.
19 @item HOST_CHARSET_ASCII
20 The host character set is ASCII.
22 @item HOST_CHARSET_EBCDIC
23 The host character set is some variant of EBCDIC.  (Only one of the
24 nineteen EBCDIC varying characters is tested; exercise caution.)
25 @end ftable
26 @end defvr
28 @c alloca.c:26
29 @deftypefn Replacement void* alloca (size_t @var{size})
31 This function allocates memory which will be automatically reclaimed
32 after the procedure exits.  The @libib{} implementation does not free
33 the memory immediately but will do so eventually during subsequent
34 calls to this function.  Memory is allocated using @code{xmalloc} under
35 normal circumstances.
37 The header file @file{alloca-conf.h} can be used in conjunction with the
38 GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make
39 available this function.  The @code{AC_FUNC_ALLOCA} test requires that
40 client code use a block of preprocessor code to be safe (see the Autoconf
41 manual for more); this header incorporates that logic and more, including
42 the possibility of a GCC built-in function.
44 @end deftypefn
46 @c asprintf.c:32
47 @deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...)
49 Like @code{sprintf}, but instead of passing a pointer to a buffer, you
50 pass a pointer to a pointer.  This function will compute the size of
51 the buffer needed, allocate memory with @code{malloc}, and store a
52 pointer to the allocated memory in @code{*@var{resptr}}.  The value
53 returned is the same as @code{sprintf} would return.  If memory could
54 not be allocated, minus one is returned and @code{NULL} is stored in
55 @code{*@var{resptr}}.
57 @end deftypefn
59 @c atexit.c:6
60 @deftypefn Supplemental int atexit (void (*@var{f})())
62 Causes function @var{f} to be called at exit.  Returns 0.
64 @end deftypefn
66 @c basename.c:6
67 @deftypefn Supplemental char* basename (const char *@var{name})
69 Returns a pointer to the last component of pathname @var{name}.
70 Behavior is undefined if the pathname ends in a directory separator.
72 @end deftypefn
74 @c bcmp.c:6
75 @deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count})
77 Compares the first @var{count} bytes of two areas of memory.  Returns
78 zero if they are the same, nonzero otherwise.  Returns zero if
79 @var{count} is zero.  A nonzero result only indicates a difference,
80 it does not indicate any sorting order (say, by having a positive
81 result mean @var{x} sorts before @var{y}).
83 @end deftypefn
85 @c bcopy.c:3
86 @deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length})
88 Copies @var{length} bytes from memory region @var{in} to region
89 @var{out}.  The use of @code{bcopy} is deprecated in new programs.
91 @end deftypefn
93 @c bsearch.c:33
94 @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 *))
96 Performs a search over an array of @var{nmemb} elements pointed to by
97 @var{base} for a member that matches the object pointed to by @var{key}.
98 The size of each member is specified by @var{size}.  The array contents
99 should be sorted in ascending order according to the @var{compar}
100 comparison function.  This routine should take two arguments pointing to
101 the @var{key} and to an array member, in that order, and should return an
102 integer less than, equal to, or greater than zero if the @var{key} object
103 is respectively less than, matching, or greater than the array member.
105 @end deftypefn
107 @c argv.c:124
108 @deftypefn Extension char** buildargv (char *@var{sp})
110 Given a pointer to a string, parse the string extracting fields
111 separated by whitespace and optionally enclosed within either single
112 or double quotes (which are stripped off), and build a vector of
113 pointers to copies of the string for each field.  The input string
114 remains unchanged.  The last element of the vector is followed by a
115 @code{NULL} element.
117 All of the memory for the pointer array and copies of the string
118 is obtained from @code{malloc}.  All of the memory can be returned to the
119 system with the single function call @code{freeargv}, which takes the
120 returned result of @code{buildargv}, as it's argument.
122 Returns a pointer to the argument vector if successful.  Returns
123 @code{NULL} if @var{sp} is @code{NULL} or if there is insufficient
124 memory to complete building the argument vector.
126 If the input is a null string (as opposed to a @code{NULL} pointer),
127 then buildarg returns an argument vector that has one arg, a null
128 string.
130 @end deftypefn
132 @c bzero.c:6
133 @deftypefn Supplemental void bzero (char *@var{mem}, int @var{count})
135 Zeros @var{count} bytes starting at @var{mem}.  Use of this function
136 is deprecated in favor of @code{memset}.
138 @end deftypefn
140 @c calloc.c:6
141 @deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize})
143 Uses @code{malloc} to allocate storage for @var{nelem} objects of
144 @var{elsize} bytes each, then zeros the memory.
146 @end deftypefn
148 @c choose-temp.c:42
149 @deftypefn Extension char* choose_temp_base (void)
151 Return a prefix for temporary file names or @code{NULL} if unable to
152 find one.  The current directory is chosen if all else fails so the
153 program is exited if a temporary directory can't be found (@code{mktemp}
154 fails).  The buffer for the result is obtained with @code{xmalloc}.
156 This function is provided for backwards compatibility only.  Its use is
157 not recommended.
159 @end deftypefn
161 @c make-temp-file.c:87
162 @deftypefn Replacement char* choose_tmpdir ()
164 Returns a pointer to a directory path suitable for creating temporary
165 files in.
167 @end deftypefn
169 @c clock.c:27
170 @deftypefn Supplemental long clock (void)
172 Returns an approximation of the CPU time used by the process as a
173 @code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the
174 number of seconds used.
176 @end deftypefn
178 @c concat.c:24
179 @deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL})
181 Concatenate zero or more of strings and return the result in freshly
182 @code{xmalloc}ed memory.  Returns @code{NULL} if insufficient memory is
183 available.  The argument list is terminated by the first @code{NULL}
184 pointer encountered.  Pointers to empty strings are ignored.
186 @end deftypefn
188 @c argv.c:52
189 @deftypefn Extension char** dupargv (char **@var{vector})
191 Duplicate an argument vector.  Simply scans through @var{vector},
192 duplicating each argument until the terminating @code{NULL} is found.
193 Returns a pointer to the argument vector if successful.  Returns
194 @code{NULL} if there is insufficient memory to complete building the
195 argument vector.
197 @end deftypefn
199 @c strerror.c:567
200 @deftypefn Extension int errno_max (void)
202 Returns the maximum @code{errno} value for which a corresponding
203 symbolic name or message is available.  Note that in the case where we
204 use the @code{sys_errlist} supplied by the system, it is possible for
205 there to be more symbolic names than messages, or vice versa.  In
206 fact, the manual page for @code{perror(3C)} explicitly warns that one
207 should check the size of the table (@code{sys_nerr}) before indexing
208 it, since new error codes may be added to the system before they are
209 added to the table.  Thus @code{sys_nerr} might be smaller than value
210 implied by the largest @code{errno} value defined in @code{<errno.h>}.
212 We return the maximum value that can be used to obtain a meaningful
213 symbolic name or message.
215 @end deftypefn
217 @c argv.c:348
218 @deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp})
220 The @var{argcp} and @code{argvp} arguments are pointers to the usual
221 @code{argc} and @code{argv} arguments to @code{main}.  This function
222 looks for arguments that begin with the character @samp{@@}.  Any such
223 arguments are interpreted as ``response files''.  The contents of the
224 response file are interpreted as additional command line options.  In
225 particular, the file is separated into whitespace-separated strings;
226 each such string is taken as a command-line option.  The new options
227 are inserted in place of the option naming the response file, and
228 @code{*argcp} and @code{*argvp} will be updated.  If the value of
229 @code{*argvp} is modified by this function, then the new value has
230 been dynamically allocated and can be deallocated by the caller with
231 @code{freeargv}.  However, most callers will simply call
232 @code{expandargv} near the beginning of @code{main} and allow the
233 operating system to free the memory when the program exits.
235 @end deftypefn
237 @c fdmatch.c:23
238 @deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2})
240 Check to see if two open file descriptors refer to the same file.
241 This is useful, for example, when we have an open file descriptor for
242 an unnamed file, and the name of a file that we believe to correspond
243 to that fd.  This can happen when we are exec'd with an already open
244 file (@code{stdout} for example) or from the SVR4 @file{/proc} calls
245 that return open file descriptors for mapped address spaces.  All we
246 have to do is open the file by name and check the two file descriptors
247 for a match, which is done by comparing major and minor device numbers
248 and inode numbers.
250 @end deftypefn
252 @c fopen_unlocked.c:48
253 @deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, const char * @var{mode})
255 Opens and returns a @code{FILE} pointer via @code{fdopen}.  If the
256 operating system supports it, ensure that the stream is setup to avoid
257 any multi-threaded locking.  Otherwise return the @code{FILE} pointer
258 unchanged.
260 @end deftypefn
262 @c ffs.c:3
263 @deftypefn Supplemental int ffs (int @var{valu})
265 Find the first (least significant) bit set in @var{valu}.  Bits are
266 numbered from right to left, starting with bit 1 (corresponding to the
267 value 1).  If @var{valu} is zero, zero is returned.
269 @end deftypefn
271 @c filename_cmp.c:32
272 @deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2})
274 Return zero if the two file names @var{s1} and @var{s2} are equivalent.
275 If not equivalent, the returned value is similar to what @code{strcmp}
276 would return.  In other words, it returns a negative value if @var{s1}
277 is less than @var{s2}, or a positive value if @var{s2} is greater than
278 @var{s2}.
280 This function does not normalize file names.  As a result, this function
281 will treat filenames that are spelled differently as different even in
282 the case when the two filenames point to the same underlying file.
283 However, it does handle the fact that on DOS-like file systems, forward
284 and backward slashes are equal.
286 @end deftypefn
288 @c fnmatch.txh:1
289 @deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags})
291 Matches @var{string} against @var{pattern}, returning zero if it
292 matches, @code{FNM_NOMATCH} if not.  @var{pattern} may contain the
293 wildcards @code{?} to match any one character, @code{*} to match any
294 zero or more characters, or a set of alternate characters in square
295 brackets, like @samp{[a-gt8]}, which match one character (@code{a}
296 through @code{g}, or @code{t}, or @code{8}, in this example) if that one
297 character is in the set.  A set may be inverted (i.e., match anything
298 except what's in the set) by giving @code{^} or @code{!} as the first
299 character in the set.  To include those characters in the set, list them
300 as anything other than the first character of the set.  To include a
301 dash in the set, list it last in the set.  A backslash character makes
302 the following character not special, so for example you could match
303 against a literal asterisk with @samp{\*}.  To match a literal
304 backslash, use @samp{\\}.
306 @code{flags} controls various aspects of the matching process, and is a
307 boolean OR of zero or more of the following values (defined in
308 @code{<fnmatch.h>}):
310 @table @code
312 @item FNM_PATHNAME
313 @itemx FNM_FILE_NAME
314 @var{string} is assumed to be a path name.  No wildcard will ever match
315 @code{/}.
317 @item FNM_NOESCAPE
318 Do not interpret backslashes as quoting the following special character.
320 @item FNM_PERIOD
321 A leading period (at the beginning of @var{string}, or if
322 @code{FNM_PATHNAME} after a slash) is not matched by @code{*} or
323 @code{?} but must be matched explicitly.
325 @item FNM_LEADING_DIR
326 Means that @var{string} also matches @var{pattern} if some initial part
327 of @var{string} matches, and is followed by @code{/} and zero or more
328 characters.  For example, @samp{foo*} would match either @samp{foobar}
329 or @samp{foobar/grill}.
331 @item FNM_CASEFOLD
332 Ignores case when performing the comparison.
334 @end table
336 @end deftypefn
338 @c fopen_unlocked.c:39
339 @deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, const char * @var{mode})
341 Opens and returns a @code{FILE} pointer via @code{fopen}.  If the
342 operating system supports it, ensure that the stream is setup to avoid
343 any multi-threaded locking.  Otherwise return the @code{FILE} pointer
344 unchanged.
346 @end deftypefn
348 @c argv.c:97
349 @deftypefn Extension void freeargv (char **@var{vector})
351 Free an argument vector that was built using @code{buildargv}.  Simply
352 scans through @var{vector}, freeing the memory for each argument until
353 the terminating @code{NULL} is found, and then frees @var{vector}
354 itself.
356 @end deftypefn
358 @c fopen_unlocked.c:57
359 @deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, const char * @var{mode}, FILE * @var{stream})
361 Opens and returns a @code{FILE} pointer via @code{freopen}.  If the
362 operating system supports it, ensure that the stream is setup to avoid
363 any multi-threaded locking.  Otherwise return the @code{FILE} pointer
364 unchanged.
366 @end deftypefn
368 @c getruntime.c:82
369 @deftypefn Replacement long get_run_time (void)
371 Returns the time used so far, in microseconds.  If possible, this is
372 the time used by this process, else it is the elapsed time since the
373 process started.
375 @end deftypefn
377 @c getcwd.c:6
378 @deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len})
380 Copy the absolute pathname for the current working directory into
381 @var{pathname}, which is assumed to point to a buffer of at least
382 @var{len} bytes, and return a pointer to the buffer.  If the current
383 directory's path doesn't fit in @var{len} characters, the result is
384 @code{NULL} and @code{errno} is set.  If @var{pathname} is a null pointer,
385 @code{getcwd} will obtain @var{len} bytes of space using
386 @code{malloc}.
388 @end deftypefn
390 @c getpagesize.c:5
391 @deftypefn Supplemental int getpagesize (void)
393 Returns the number of bytes in a page of memory.  This is the
394 granularity of many of the system memory management routines.  No
395 guarantee is made as to whether or not it is the same as the basic
396 memory management hardware page size.
398 @end deftypefn
400 @c getpwd.c:5
401 @deftypefn Supplemental char* getpwd (void)
403 Returns the current working directory.  This implementation caches the
404 result on the assumption that the process will not call @code{chdir}
405 between calls to @code{getpwd}.
407 @end deftypefn
409 @c gettimeofday.c:12
410 @deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz})
412 Writes the current time to @var{tp}.  This implementation requires
413 that @var{tz} be NULL.  Returns 0 on success, -1 on failure.
415 @end deftypefn
417 @c hex.c:33
418 @deftypefn Extension void hex_init (void)
420 Initializes the array mapping the current character set to
421 corresponding hex values.  This function must be called before any
422 call to @code{hex_p} or @code{hex_value}.  If you fail to call it, a
423 default ASCII-based table will normally be used on ASCII systems.
425 @end deftypefn
427 @c hex.c:42
428 @deftypefn Extension int hex_p (int @var{c})
430 Evaluates to non-zero if the given character is a valid hex character,
431 or zero if it is not.  Note that the value you pass will be cast to
432 @code{unsigned char} within the macro.
434 @end deftypefn
436 @c hex.c:50
437 @deftypefn Extension {unsigned int} hex_value (int @var{c})
439 Returns the numeric equivalent of the given character when interpreted
440 as a hexadecimal digit.  The result is undefined if you pass an
441 invalid hex digit.  Note that the value you pass will be cast to
442 @code{unsigned char} within the macro.
444 The @code{hex_value} macro returns @code{unsigned int}, rather than
445 signed @code{int}, to make it easier to use in parsing addresses from
446 hex dump files: a signed @code{int} would be sign-extended when
447 converted to a wider unsigned type --- like @code{bfd_vma}, on some
448 systems.
450 @end deftypefn
452 @c index.c:5
453 @deftypefn Supplemental char* index (char *@var{s}, int @var{c})
455 Returns a pointer to the first occurrence of the character @var{c} in
456 the string @var{s}, or @code{NULL} if not found.  The use of @code{index} is
457 deprecated in new programs in favor of @code{strchr}.
459 @end deftypefn
461 @c insque.c:6
462 @deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred})
463 @deftypefnx Supplemental void remque (struct qelem *@var{elem})
465 Routines to manipulate queues built from doubly linked lists.  The
466 @code{insque} routine inserts @var{elem} in the queue immediately
467 after @var{pred}.  The @code{remque} routine removes @var{elem} from
468 its containing queue.  These routines expect to be passed pointers to
469 structures which have as their first members a forward pointer and a
470 back pointer, like this prototype (although no prototype is provided):
472 @example
473 struct qelem @{
474   struct qelem *q_forw;
475   struct qelem *q_back;
476   char q_data[];
478 @end example
480 @end deftypefn
482 @c safe-ctype.c:46
483 @deffn  Extension ISALPHA  (@var{c})
484 @deffnx Extension ISALNUM  (@var{c})
485 @deffnx Extension ISBLANK  (@var{c})
486 @deffnx Extension ISCNTRL  (@var{c})
487 @deffnx Extension ISDIGIT  (@var{c})
488 @deffnx Extension ISGRAPH  (@var{c})
489 @deffnx Extension ISLOWER  (@var{c})
490 @deffnx Extension ISPRINT  (@var{c})
491 @deffnx Extension ISPUNCT  (@var{c})
492 @deffnx Extension ISSPACE  (@var{c})
493 @deffnx Extension ISUPPER  (@var{c})
494 @deffnx Extension ISXDIGIT (@var{c})
496 These twelve macros are defined by @file{safe-ctype.h}.  Each has the
497 same meaning as the corresponding macro (with name in lowercase)
498 defined by the standard header @file{ctype.h}.  For example,
499 @code{ISALPHA} returns true for alphabetic characters and false for
500 others.  However, there are two differences between these macros and
501 those provided by @file{ctype.h}:
503 @itemize @bullet
504 @item These macros are guaranteed to have well-defined behavior for all 
505 values representable by @code{signed char} and @code{unsigned char}, and
506 for @code{EOF}.
508 @item These macros ignore the current locale; they are true for these
509 fixed sets of characters:
510 @multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada}
511 @item @code{ALPHA}  @tab @kbd{A-Za-z}
512 @item @code{ALNUM}  @tab @kbd{A-Za-z0-9}
513 @item @code{BLANK}  @tab @kbd{space tab}
514 @item @code{CNTRL}  @tab @code{!PRINT}
515 @item @code{DIGIT}  @tab @kbd{0-9}
516 @item @code{GRAPH}  @tab @code{ALNUM || PUNCT}
517 @item @code{LOWER}  @tab @kbd{a-z}
518 @item @code{PRINT}  @tab @code{GRAPH ||} @kbd{space}
519 @item @code{PUNCT}  @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?}
520 @item @code{SPACE}  @tab @kbd{space tab \n \r \f \v}
521 @item @code{UPPER}  @tab @kbd{A-Z}
522 @item @code{XDIGIT} @tab @kbd{0-9A-Fa-f}
523 @end multitable
525 Note that, if the host character set is ASCII or a superset thereof,
526 all these macros will return false for all values of @code{char} outside
527 the range of 7-bit ASCII.  In particular, both ISPRINT and ISCNTRL return
528 false for characters with numeric values from 128 to 255.
529 @end itemize
530 @end deffn
532 @c safe-ctype.c:95
533 @deffn  Extension ISIDNUM         (@var{c})
534 @deffnx Extension ISIDST          (@var{c})
535 @deffnx Extension IS_VSPACE       (@var{c})
536 @deffnx Extension IS_NVSPACE      (@var{c})
537 @deffnx Extension IS_SPACE_OR_NUL (@var{c})
538 @deffnx Extension IS_ISOBASIC     (@var{c})
539 These six macros are defined by @file{safe-ctype.h} and provide
540 additional character classes which are useful when doing lexical
541 analysis of C or similar languages.  They are true for the following
542 sets of characters:
544 @multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada}
545 @item @code{IDNUM}        @tab @kbd{A-Za-z0-9_}
546 @item @code{IDST}         @tab @kbd{A-Za-z_}
547 @item @code{VSPACE}       @tab @kbd{\r \n}
548 @item @code{NVSPACE}      @tab @kbd{space tab \f \v \0}
549 @item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE}
550 @item @code{ISOBASIC}     @tab @code{VSPACE || NVSPACE || PRINT}
551 @end multitable
552 @end deffn
554 @c lbasename.c:23
555 @deftypefn Replacement {const char*} lbasename (const char *@var{name})
557 Given a pointer to a string containing a typical pathname
558 (@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the
559 last component of the pathname (@samp{ls.c} in this case).  The
560 returned pointer is guaranteed to lie within the original
561 string.  This latter fact is not true of many vendor C
562 libraries, which return special strings or modify the passed
563 strings for particular input.
565 In particular, the empty string returns the same empty string,
566 and a path ending in @code{/} returns the empty string after it.
568 @end deftypefn
570 @c lrealpath.c:25
571 @deftypefn Replacement {const char*} lrealpath (const char *@var{name})
573 Given a pointer to a string containing a pathname, returns a canonical
574 version of the filename.  Symlinks will be resolved, and ``.'' and ``..''
575 components will be simplified.  The returned value will be allocated using
576 @code{malloc}, or @code{NULL} will be returned on a memory allocation error.
578 @end deftypefn
580 @c make-relative-prefix.c:24
581 @deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, const char *@var{bin_prefix}, const char *@var{prefix})
583 Given three paths @var{progname}, @var{bin_prefix}, @var{prefix},
584 return the path that is in the same position relative to
585 @var{progname}'s directory as @var{prefix} is relative to
586 @var{bin_prefix}.  That is, a string starting with the directory
587 portion of @var{progname}, followed by a relative pathname of the
588 difference between @var{bin_prefix} and @var{prefix}.
590 If @var{progname} does not contain any directory separators,
591 @code{make_relative_prefix} will search @env{PATH} to find a program
592 named @var{progname}.  Also, if @var{progname} is a symbolic link,
593 the symbolic link will be resolved.
595 For example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta},
596 @var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is
597 @code{/red/green/blue/gcc}, then this function will return
598 @code{/red/green/blue/../../omega/}.
600 The return value is normally allocated via @code{malloc}.  If no
601 relative prefix can be found, return @code{NULL}.
603 @end deftypefn
605 @c make-temp-file.c:137
606 @deftypefn Replacement char* make_temp_file (const char *@var{suffix})
608 Return a temporary file name (as a string) or @code{NULL} if unable to
609 create one.  @var{suffix} is a suffix to append to the file name.  The
610 string is @code{malloc}ed, and the temporary file has been created.
612 @end deftypefn
614 @c memchr.c:3
615 @deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n})
617 This function searches memory starting at @code{*@var{s}} for the
618 character @var{c}.  The search only ends with the first occurrence of
619 @var{c}, or after @var{length} characters; in particular, a null
620 character does not terminate the search.  If the character @var{c} is
621 found within @var{length} characters of @code{*@var{s}}, a pointer
622 to the character is returned.  If @var{c} is not found, then @code{NULL} is
623 returned.
625 @end deftypefn
627 @c memcmp.c:6
628 @deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count})
630 Compares the first @var{count} bytes of two areas of memory.  Returns
631 zero if they are the same, a value less than zero if @var{x} is
632 lexically less than @var{y}, or a value greater than zero if @var{x}
633 is lexically greater than @var{y}.  Note that lexical order is determined
634 as if comparing unsigned char arrays.
636 @end deftypefn
638 @c memcpy.c:6
639 @deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
641 Copies @var{length} bytes from memory region @var{in} to region
642 @var{out}.  Returns a pointer to @var{out}.
644 @end deftypefn
646 @c memmove.c:6
647 @deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count})
649 Copies @var{count} bytes from memory area @var{from} to memory area
650 @var{to}, returning a pointer to @var{to}.
652 @end deftypefn
654 @c mempcpy.c:23
655 @deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
657 Copies @var{length} bytes from memory region @var{in} to region
658 @var{out}.  Returns a pointer to @var{out} + @var{length}.
660 @end deftypefn
662 @c memset.c:6
663 @deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count})
665 Sets the first @var{count} bytes of @var{s} to the constant byte
666 @var{c}, returning a pointer to @var{s}.
668 @end deftypefn
670 @c mkstemps.c:58
671 @deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len})
673 Generate a unique temporary file name from @var{pattern}.
674 @var{pattern} has the form:
676 @example
677    @var{path}/ccXXXXXX@var{suffix}
678 @end example
680 @var{suffix_len} tells us how long @var{suffix} is (it can be zero
681 length).  The last six characters of @var{pattern} before @var{suffix}
682 must be @samp{XXXXXX}; they are replaced with a string that makes the
683 filename unique.  Returns a file descriptor open on the file for
684 reading and writing.
686 @end deftypefn
688 @c pexecute.txh:266
689 @deftypefn Extension void pex_free (struct pex_obj @var{obj})
691 Clean up and free all data associated with @var{obj}.
693 @end deftypefn
695 @c pexecute.txh:241
696 @deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector})
698 Returns the exit status of all programs run using @var{obj}.
699 @var{count} is the number of results expected.  The results will be
700 placed into @var{vector}.  The results are in the order of the calls
701 to @code{pex_run}.  Returns 0 on error, 1 on success.
703 @end deftypefn
705 @c pexecute.txh:250
706 @deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector})
708 Returns the process execution times of all programs run using
709 @var{obj}.  @var{count} is the number of results expected.  The
710 results will be placed into @var{vector}.  The results are in the
711 order of the calls to @code{pex_run}.  Returns 0 on error, 1 on
712 success.
714 @code{struct pex_time} has the following fields of the type
715 @code{unsigned long}: @code{user_seconds},
716 @code{user_microseconds}, @code{system_seconds},
717 @code{system_microseconds}.  On systems which do not support reporting
718 process times, all the fields will be set to @code{0}.
720 @end deftypefn
722 @c pexecute.txh:2
723 @deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase})
725 Prepare to execute one or more programs, with standard output of each
726 program fed to standard input of the next.  This is a system
727 independent interface to execute a pipeline.
729 @var{flags} is a bitwise combination of the following:
731 @table @code
733 @vindex PEX_RECORD_TIMES
734 @item PEX_RECORD_TIMES
735 Record subprocess times if possible.
737 @vindex PEX_USE_PIPES
738 @item PEX_USE_PIPES
739 Use pipes for communication between processes, if possible.
741 @vindex PEX_SAVE_TEMPS
742 @item PEX_SAVE_TEMPS
743 Don't delete temporary files used for communication between
744 processes.
746 @end table
748 @var{pname} is the name of program to be executed, used in error
749 messages.  @var{tempbase} is a base name to use for any required
750 temporary files; it may be @code{NULL} to use a randomly chosen name.
752 @end deftypefn
754 @c pexecute.txh:155
755 @deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{in_name})
757 Return a stream for a temporary file to pass to the first program in
758 the pipeline as input.
760 The name of the input file is chosen according to the same rules
761 @code{pex_run} uses to choose output file names, based on
762 @var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}.
764 Don't call @code{fclose} on the returned stream; the first call to
765 @code{pex_run} closes it automatically.
767 If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in
768 binary mode; otherwise, open it in the default mode.  Including
769 @code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix.
770 @end deftypefn
772 @c pexecute.txh:172
773 @deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, int @var{binary})
775 Return a stream @var{fp} for a pipe connected to the standard input of
776 the first program in the pipeline; @var{fp} is opened for writing.
777 You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call
778 that returned @var{obj}.
780 You must close @var{fp} using @code{fclose} yourself when you have
781 finished writing data to the pipeline.
783 The file descriptor underlying @var{fp} is marked not to be inherited
784 by child processes.
786 On systems that do not support pipes, this function returns
787 @code{NULL}, and sets @code{errno} to @code{EINVAL}.  If you would
788 like to write code that is portable to all systems the @code{pex}
789 functions support, consider using @code{pex_input_file} instead.
791 There are two opportunities for deadlock using
792 @code{pex_input_pipe}:
794 @itemize @bullet
795 @item
796 Most systems' pipes can buffer only a fixed amount of data; a process
797 that writes to a full pipe blocks.  Thus, if you write to @file{fp}
798 before starting the first process, you run the risk of blocking when
799 there is no child process yet to read the data and allow you to
800 continue.  @code{pex_input_pipe} makes no promises about the
801 size of the pipe's buffer, so if you need to write any data at all
802 before starting the first process in the pipeline, consider using
803 @code{pex_input_file} instead.
805 @item
806 Using @code{pex_input_pipe} and @code{pex_read_output} together
807 may also cause deadlock.  If the output pipe fills up, so that each
808 program in the pipeline is waiting for the next to read more data, and
809 you fill the input pipe by writing more data to @var{fp}, then there
810 is no way to make progress: the only process that could read data from
811 the output pipe is you, but you are blocked on the input pipe.
813 @end itemize
815 @end deftypefn
817 @c pexecute.txh:272
818 @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})
820 An interface to permit the easy execution of a
821 single program.  The return value and most of the parameters are as
822 for a call to @code{pex_run}.  @var{flags} is restricted to a
823 combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and
824 @code{PEX_BINARY_OUTPUT}.  @var{outname} is interpreted as if
825 @code{PEX_LAST} were set.  On a successful return, @code{*@var{status}} will
826 be set to the exit status of the program.
828 @end deftypefn
830 @c pexecute.txh:228
831 @deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, int @var{binary})
833 Returns a @code{FILE} pointer which may be used to read the standard
834 error of the last program in the pipeline.  When this is used,
835 @code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
836 this is called, @code{pex_run} may no longer be called with the same
837 @var{obj}.  @var{binary} should be non-zero if the file should be
838 opened in binary mode.  Don't call @code{fclose} on the returned file;
839 it will be closed by @code{pex_free}.
841 @end deftypefn
843 @c pexecute.txh:216
844 @deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary})
846 Returns a @code{FILE} pointer which may be used to read the standard
847 output of the last program in the pipeline.  When this is used,
848 @code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
849 this is called, @code{pex_run} may no longer be called with the same
850 @var{obj}.  @var{binary} should be non-zero if the file should be
851 opened in binary mode.  Don't call @code{fclose} on the returned file;
852 it will be closed by @code{pex_free}.
854 @end deftypefn
856 @c pexecute.txh:33
857 @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})
859 Execute one program in a pipeline.  On success this returns
860 @code{NULL}.  On failure it returns an error message, a statically
861 allocated string.
863 @var{obj} is returned by a previous call to @code{pex_init}.
865 @var{flags} is a bitwise combination of the following:
867 @table @code
869 @vindex PEX_LAST
870 @item PEX_LAST
871 This must be set on the last program in the pipeline.  In particular,
872 it should be set when executing a single program.  The standard output
873 of the program will be sent to @var{outname}, or, if @var{outname} is
874 @code{NULL}, to the standard output of the calling program.  Do @emph{not}
875 set this bit if you want to call @code{pex_read_output}
876 (described below).  After a call to @code{pex_run} with this bit set,
877 @var{pex_run} may no longer be called with the same @var{obj}.
879 @vindex PEX_SEARCH
880 @item PEX_SEARCH
881 Search for the program using the user's executable search path.
883 @vindex PEX_SUFFIX
884 @item PEX_SUFFIX
885 @var{outname} is a suffix.  See the description of @var{outname},
886 below.
888 @vindex PEX_STDERR_TO_STDOUT
889 @item PEX_STDERR_TO_STDOUT
890 Send the program's standard error to standard output, if possible.
892 @vindex PEX_BINARY_INPUT
893 @vindex PEX_BINARY_OUTPUT
894 @vindex PEX_BINARY_ERROR
895 @item PEX_BINARY_INPUT
896 @itemx PEX_BINARY_OUTPUT
897 @itemx PEX_BINARY_ERROR
898 The standard input (output or error) of the program should be read (written) in
899 binary mode rather than text mode.  These flags are ignored on systems
900 which do not distinguish binary mode and text mode, such as Unix.  For
901 proper behavior these flags should match appropriately---a call to
902 @code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
903 call using @code{PEX_BINARY_INPUT}.
905 @vindex PEX_STDERR_TO_PIPE
906 @item PEX_STDERR_TO_PIPE
907 Send the program's standard error to a pipe, if possible.  This flag
908 cannot be specified together with @code{PEX_STDERR_TO_STDOUT}.  This
909 flag can be specified only on the last program in pipeline.
911 @end table
913 @var{executable} is the program to execute.  @var{argv} is the set of
914 arguments to pass to the program; normally @code{@var{argv}[0]} will
915 be a copy of @var{executable}.
917 @var{outname} is used to set the name of the file to use for standard
918 output.  There are two cases in which no output file will be used:
920 @enumerate
921 @item
922 if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES}
923 was set in the call to @code{pex_init}, and the system supports pipes
925 @item
926 if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
927 @code{NULL}
928 @end enumerate
930 @noindent
931 Otherwise the code will use a file to hold standard
932 output.  If @code{PEX_LAST} is not set, this file is considered to be
933 a temporary file, and it will be removed when no longer needed, unless
934 @code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}.
936 There are two cases to consider when setting the name of the file to
937 hold standard output.
939 @enumerate
940 @item
941 @code{PEX_SUFFIX} is set in @var{flags}.  In this case
942 @var{outname} may not be @code{NULL}.  If the @var{tempbase} parameter
943 to @code{pex_init} was not @code{NULL}, then the output file name is
944 the concatenation of @var{tempbase} and @var{outname}.  If
945 @var{tempbase} was @code{NULL}, then the output file name is a random
946 file name ending in @var{outname}.
948 @item
949 @code{PEX_SUFFIX} was not set in @var{flags}.  In this
950 case, if @var{outname} is not @code{NULL}, it is used as the output
951 file name.  If @var{outname} is @code{NULL}, and @var{tempbase} was
952 not NULL, the output file name is randomly chosen using
953 @var{tempbase}.  Otherwise the output file name is chosen completely
954 at random.
955 @end enumerate
957 @var{errname} is the file name to use for standard error output.  If
958 it is @code{NULL}, standard error is the same as the caller's.
959 Otherwise, standard error is written to the named file.
961 On an error return, the code sets @code{*@var{err}} to an @code{errno}
962 value, or to 0 if there is no relevant @code{errno}.
964 @end deftypefn
966 @c pexecute.txh:142
967 @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})
969 Execute one program in a pipeline, permitting the environment for the
970 program to be specified.  Behaviour and parameters not listed below are
971 as for @code{pex_run}.
973 @var{env} is the environment for the child process, specified as an array of
974 character pointers.  Each element of the array should point to a string of the
975 form @code{VAR=VALUE}, with the exception of the last element that must be
976 @code{NULL}.
978 @end deftypefn
980 @c pexecute.txh:284
981 @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})
983 This is the old interface to execute one or more programs.  It is
984 still supported for compatibility purposes, but is no longer
985 documented.
987 @end deftypefn
989 @c strsignal.c:539
990 @deftypefn Supplemental void psignal (int @var{signo}, char *@var{message})
992 Print @var{message} to the standard error, followed by a colon,
993 followed by the description of the signal specified by @var{signo},
994 followed by a newline.
996 @end deftypefn
998 @c putenv.c:21
999 @deftypefn Supplemental int putenv (const char *@var{string})
1001 Uses @code{setenv} or @code{unsetenv} to put @var{string} into
1002 the environment or remove it.  If @var{string} is of the form
1003 @samp{name=value} the string is added; if no @samp{=} is present the
1004 name is unset/removed.
1006 @end deftypefn
1008 @c pexecute.txh:292
1009 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
1011 Another part of the old execution interface.
1013 @end deftypefn
1015 @c random.c:39
1016 @deftypefn Supplement {long int} random (void)
1017 @deftypefnx Supplement void srandom (unsigned int @var{seed})
1018 @deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n})
1019 @deftypefnx Supplement void* setstate (void *@var{arg_state})
1021 Random number functions.  @code{random} returns a random number in the
1022 range 0 to @code{LONG_MAX}.  @code{srandom} initializes the random
1023 number generator to some starting point determined by @var{seed}
1024 (else, the values returned by @code{random} are always the same for each
1025 run of the program).  @code{initstate} and @code{setstate} allow fine-grained
1026 control over the state of the random number generator.
1028 @end deftypefn
1030 @c concat.c:173
1031 @deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL})
1033 Same as @code{concat}, except that if @var{optr} is not @code{NULL} it
1034 is freed after the string is created.  This is intended to be useful
1035 when you're extending an existing string or building up a string in a
1036 loop:
1038 @example
1039   str = reconcat (str, "pre-", str, NULL);
1040 @end example
1042 @end deftypefn
1044 @c rename.c:6
1045 @deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
1047 Renames a file from @var{old} to @var{new}.  If @var{new} already
1048 exists, it is removed.
1050 @end deftypefn
1052 @c rindex.c:5
1053 @deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
1055 Returns a pointer to the last occurrence of the character @var{c} in
1056 the string @var{s}, or @code{NULL} if not found.  The use of @code{rindex} is
1057 deprecated in new programs in favor of @code{strrchr}.
1059 @end deftypefn
1061 @c setenv.c:22
1062 @deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
1063 @deftypefnx Supplemental void unsetenv (const char *@var{name})
1065 @code{setenv} adds @var{name} to the environment with value
1066 @var{value}.  If the name was already present in the environment,
1067 the new value will be stored only if @var{overwrite} is nonzero.
1068 The companion @code{unsetenv} function removes @var{name} from the
1069 environment.  This implementation is not safe for multithreaded code.
1071 @end deftypefn
1073 @c strsignal.c:348
1074 @deftypefn Extension int signo_max (void)
1076 Returns the maximum signal value for which a corresponding symbolic
1077 name or message is available.  Note that in the case where we use the
1078 @code{sys_siglist} supplied by the system, it is possible for there to
1079 be more symbolic names than messages, or vice versa.  In fact, the
1080 manual page for @code{psignal(3b)} explicitly warns that one should
1081 check the size of the table (@code{NSIG}) before indexing it, since
1082 new signal codes may be added to the system before they are added to
1083 the table.  Thus @code{NSIG} might be smaller than value implied by
1084 the largest signo value defined in @code{<signal.h>}.
1086 We return the maximum value that can be used to obtain a meaningful
1087 symbolic name or message.
1089 @end deftypefn
1091 @c sigsetmask.c:8
1092 @deftypefn Supplemental int sigsetmask (int @var{set})
1094 Sets the signal mask to the one provided in @var{set} and returns
1095 the old mask (which, for libiberty's implementation, will always
1096 be the value @code{1}).
1098 @end deftypefn
1100 @c snprintf.c:28
1101 @deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...)
1103 This function is similar to sprintf, but it will print at most @var{n}
1104 characters.  On error the return value is -1, otherwise it returns the
1105 number of characters that would have been printed had @var{n} been
1106 sufficiently large, regardless of the actual value of @var{n}.  Note
1107 some pre-C99 system libraries do not implement this correctly so users
1108 cannot generally rely on the return value if the system version of
1109 this function is used.
1111 @end deftypefn
1113 @c spaces.c:22
1114 @deftypefn Extension char* spaces (int @var{count})
1116 Returns a pointer to a memory region filled with the specified
1117 number of spaces and null terminated.  The returned pointer is
1118 valid until at least the next call.
1120 @end deftypefn
1122 @c stpcpy.c:23
1123 @deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src})
1125 Copies the string @var{src} into @var{dst}.  Returns a pointer to
1126 @var{dst} + strlen(@var{src}).
1128 @end deftypefn
1130 @c stpncpy.c:23
1131 @deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, size_t @var{len})
1133 Copies the string @var{src} into @var{dst}, copying exactly @var{len}
1134 and padding with zeros if necessary.  If @var{len} < strlen(@var{src})
1135 then return @var{dst} + @var{len}, otherwise returns @var{dst} +
1136 strlen(@var{src}).
1138 @end deftypefn
1140 @c strcasecmp.c:15
1141 @deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
1143 A case-insensitive @code{strcmp}.
1145 @end deftypefn
1147 @c strchr.c:6
1148 @deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
1150 Returns a pointer to the first occurrence of the character @var{c} in
1151 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
1152 null character, the results are undefined.
1154 @end deftypefn
1156 @c strdup.c:3
1157 @deftypefn Supplemental char* strdup (const char *@var{s})
1159 Returns a pointer to a copy of @var{s} in memory obtained from
1160 @code{malloc}, or @code{NULL} if insufficient memory was available.
1162 @end deftypefn
1164 @c strerror.c:670
1165 @deftypefn Replacement {const char*} strerrno (int @var{errnum})
1167 Given an error number returned from a system call (typically returned
1168 in @code{errno}), returns a pointer to a string containing the
1169 symbolic name of that error number, as found in @code{<errno.h>}.
1171 If the supplied error number is within the valid range of indices for
1172 symbolic names, but no name is available for the particular error
1173 number, then returns the string @samp{Error @var{num}}, where @var{num}
1174 is the error number.
1176 If the supplied error number is not within the range of valid
1177 indices, then returns @code{NULL}.
1179 The contents of the location pointed to are only guaranteed to be
1180 valid until the next call to @code{strerrno}.
1182 @end deftypefn
1184 @c strerror.c:603
1185 @deftypefn Supplemental char* strerror (int @var{errnoval})
1187 Maps an @code{errno} number to an error message string, the contents
1188 of which are implementation defined.  On systems which have the
1189 external variables @code{sys_nerr} and @code{sys_errlist}, these
1190 strings will be the same as the ones used by @code{perror}.
1192 If the supplied error number is within the valid range of indices for
1193 the @code{sys_errlist}, but no message is available for the particular
1194 error number, then returns the string @samp{Error @var{num}}, where
1195 @var{num} is the error number.
1197 If the supplied error number is not a valid index into
1198 @code{sys_errlist}, returns @code{NULL}.
1200 The returned string is only guaranteed to be valid only until the
1201 next call to @code{strerror}.
1203 @end deftypefn
1205 @c strncasecmp.c:15
1206 @deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
1208 A case-insensitive @code{strncmp}.
1210 @end deftypefn
1212 @c strncmp.c:6
1213 @deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
1215 Compares the first @var{n} bytes of two strings, returning a value as
1216 @code{strcmp}.
1218 @end deftypefn
1220 @c strndup.c:23
1221 @deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n})
1223 Returns a pointer to a copy of @var{s} with at most @var{n} characters
1224 in memory obtained from @code{malloc}, or @code{NULL} if insufficient
1225 memory was available.  The result is always NUL terminated.
1227 @end deftypefn
1229 @c strrchr.c:6
1230 @deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
1232 Returns a pointer to the last occurrence of the character @var{c} in
1233 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
1234 null character, the results are undefined.
1236 @end deftypefn
1238 @c strsignal.c:383
1239 @deftypefn Supplemental {const char *} strsignal (int @var{signo})
1241 Maps an signal number to an signal message string, the contents of
1242 which are implementation defined.  On systems which have the external
1243 variable @code{sys_siglist}, these strings will be the same as the
1244 ones used by @code{psignal()}.
1246 If the supplied signal number is within the valid range of indices for
1247 the @code{sys_siglist}, but no message is available for the particular
1248 signal number, then returns the string @samp{Signal @var{num}}, where
1249 @var{num} is the signal number.
1251 If the supplied signal number is not a valid index into
1252 @code{sys_siglist}, returns @code{NULL}.
1254 The returned string is only guaranteed to be valid only until the next
1255 call to @code{strsignal}.
1257 @end deftypefn
1259 @c strsignal.c:446
1260 @deftypefn Extension {const char*} strsigno (int @var{signo})
1262 Given an signal number, returns a pointer to a string containing the
1263 symbolic name of that signal number, as found in @code{<signal.h>}.
1265 If the supplied signal number is within the valid range of indices for
1266 symbolic names, but no name is available for the particular signal
1267 number, then returns the string @samp{Signal @var{num}}, where
1268 @var{num} is the signal number.
1270 If the supplied signal number is not within the range of valid
1271 indices, then returns @code{NULL}.
1273 The contents of the location pointed to are only guaranteed to be
1274 valid until the next call to @code{strsigno}.
1276 @end deftypefn
1278 @c strstr.c:6
1279 @deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
1281 This function searches for the substring @var{sub} in the string
1282 @var{string}, not including the terminating null characters.  A pointer
1283 to the first occurrence of @var{sub} is returned, or @code{NULL} if the
1284 substring is absent.  If @var{sub} points to a string with zero
1285 length, the function returns @var{string}.
1287 @end deftypefn
1289 @c strtod.c:27
1290 @deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})
1292 This ISO C function converts the initial portion of @var{string} to a
1293 @code{double}.  If @var{endptr} is not @code{NULL}, a pointer to the
1294 character after the last character used in the conversion is stored in
1295 the location referenced by @var{endptr}.  If no conversion is
1296 performed, zero is returned and the value of @var{string} is stored in
1297 the location referenced by @var{endptr}.
1299 @end deftypefn
1301 @c strerror.c:729
1302 @deftypefn Extension int strtoerrno (const char *@var{name})
1304 Given the symbolic name of a error number (e.g., @code{EACCES}), map it
1305 to an errno value.  If no translation is found, returns 0.
1307 @end deftypefn
1309 @c strtol.c:33
1310 @deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
1311 @deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base})
1313 The @code{strtol} function converts the string in @var{string} to a
1314 long integer value according to the given @var{base}, which must be
1315 between 2 and 36 inclusive, or be the special value 0.  If @var{base}
1316 is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
1317 to indicate bases 8 and 16, respectively, else default to base 10.
1318 When the base is 16 (either explicitly or implicitly), a prefix of
1319 @code{0x} is allowed.  The handling of @var{endptr} is as that of
1320 @code{strtod} above.  The @code{strtoul} function is the same, except
1321 that the converted value is unsigned.
1323 @end deftypefn
1325 @c strsignal.c:500
1326 @deftypefn Extension int strtosigno (const char *@var{name})
1328 Given the symbolic name of a signal, map it to a signal number.  If no
1329 translation is found, returns 0.
1331 @end deftypefn
1333 @c strverscmp.c:25
1334 @deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2})
1335 The @code{strverscmp} function compares the string @var{s1} against
1336 @var{s2}, considering them as holding indices/version numbers.  Return
1337 value follows the same conventions as found in the @code{strverscmp}
1338 function.  In fact, if @var{s1} and @var{s2} contain no digits,
1339 @code{strverscmp} behaves like @code{strcmp}.
1341 Basically, we compare strings normally (character by character), until
1342 we find a digit in each string - then we enter a special comparison
1343 mode, where each sequence of digits is taken as a whole.  If we reach the
1344 end of these two parts without noticing a difference, we return to the
1345 standard comparison mode.  There are two types of numeric parts:
1346 "integral" and "fractional" (those  begin with a '0'). The types
1347 of the numeric parts affect the way we sort them:
1349 @itemize @bullet
1350 @item
1351 integral/integral: we compare values as you would expect.
1353 @item
1354 fractional/integral: the fractional part is less than the integral one.
1355 Again, no surprise.
1357 @item
1358 fractional/fractional: the things become a bit more complex.
1359 If the common prefix contains only leading zeroes, the longest part is less
1360 than the other one; else the comparison behaves normally.
1361 @end itemize
1363 @smallexample
1364 strverscmp ("no digit", "no digit")
1365     @result{} 0    // @r{same behavior as strcmp.}
1366 strverscmp ("item#99", "item#100")
1367     @result{} <0   // @r{same prefix, but 99 < 100.}
1368 strverscmp ("alpha1", "alpha001")
1369     @result{} >0   // @r{fractional part inferior to integral one.}
1370 strverscmp ("part1_f012", "part1_f01")
1371     @result{} >0   // @r{two fractional parts.}
1372 strverscmp ("foo.009", "foo.0")
1373     @result{} <0   // @r{idem, but with leading zeroes only.}
1374 @end smallexample
1376 This function is especially useful when dealing with filename sorting,
1377 because filenames frequently hold indices/version numbers.
1378 @end deftypefun
1380 @c tmpnam.c:3
1381 @deftypefn Supplemental char* tmpnam (char *@var{s})
1383 This function attempts to create a name for a temporary file, which
1384 will be a valid file name yet not exist when @code{tmpnam} checks for
1385 it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
1386 or be @code{NULL}.  Use of this function creates a security risk, and it must
1387 not be used in new projects.  Use @code{mkstemp} instead.
1389 @end deftypefn
1391 @c unlink-if-ordinary.c:27
1392 @deftypefn Supplemental int unlink_if_ordinary (const char*)
1394 Unlinks the named file, unless it is special (e.g. a device file).
1395 Returns 0 when the file was unlinked, a negative value (and errno set) when
1396 there was an error deleting the file, and a positive value if no attempt
1397 was made to unlink the file because it is special.
1399 @end deftypefn
1401 @c fopen_unlocked.c:31
1402 @deftypefn Extension void unlock_std_streams (void)
1404 If the OS supports it, ensure that the standard I/O streams,
1405 @code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any
1406 multi-threaded locking.  Otherwise do nothing.
1408 @end deftypefn
1410 @c fopen_unlocked.c:23
1411 @deftypefn Extension void unlock_stream (FILE * @var{stream})
1413 If the OS supports it, ensure that the supplied stream is setup to
1414 avoid any multi-threaded locking.  Otherwise leave the @code{FILE}
1415 pointer unchanged.  If the @var{stream} is @code{NULL} do nothing.
1417 @end deftypefn
1419 @c vasprintf.c:47
1420 @deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args})
1422 Like @code{vsprintf}, but instead of passing a pointer to a buffer,
1423 you pass a pointer to a pointer.  This function will compute the size
1424 of the buffer needed, allocate memory with @code{malloc}, and store a
1425 pointer to the allocated memory in @code{*@var{resptr}}.  The value
1426 returned is the same as @code{vsprintf} would return.  If memory could
1427 not be allocated, minus one is returned and @code{NULL} is stored in
1428 @code{*@var{resptr}}.
1430 @end deftypefn
1432 @c vfork.c:6
1433 @deftypefn Supplemental int vfork (void)
1435 Emulates @code{vfork} by calling @code{fork} and returning its value.
1437 @end deftypefn
1439 @c vprintf.c:3
1440 @deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
1441 @deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
1442 @deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})
1444 These functions are the same as @code{printf}, @code{fprintf}, and
1445 @code{sprintf}, respectively, except that they are called with a
1446 @code{va_list} instead of a variable number of arguments.  Note that
1447 they do not call @code{va_end}; this is the application's
1448 responsibility.  In @libib{} they are implemented in terms of the
1449 nonstandard but common function @code{_doprnt}.
1451 @end deftypefn
1453 @c vsnprintf.c:28
1454 @deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap})
1456 This function is similar to vsprintf, but it will print at most
1457 @var{n} characters.  On error the return value is -1, otherwise it
1458 returns the number of characters that would have been printed had
1459 @var{n} been sufficiently large, regardless of the actual value of
1460 @var{n}.  Note some pre-C99 system libraries do not implement this
1461 correctly so users cannot generally rely on the return value if the
1462 system version of this function is used.
1464 @end deftypefn
1466 @c waitpid.c:3
1467 @deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
1469 This is a wrapper around the @code{wait} function.  Any ``special''
1470 values of @var{pid} depend on your implementation of @code{wait}, as
1471 does the return value.  The third argument is unused in @libib{}.
1473 @end deftypefn
1475 @c argv.c:293
1476 @deftypefn Extension int writeargv (const char **@var{argv}, FILE *@var{file})
1478 Write each member of ARGV, handling all necessary quoting, to the file
1479 named by FILE, separated by whitespace.  Return 0 on success, non-zero
1480 if an error occurred while writing to FILE.
1482 @end deftypefn
1484 @c xatexit.c:11
1485 @deftypefun int xatexit (void (*@var{fn}) (void))
1487 Behaves as the standard @code{atexit} function, but with no limit on
1488 the number of registered functions.  Returns 0 on success, or @minus{}1 on
1489 failure.  If you use @code{xatexit} to register functions, you must use
1490 @code{xexit} to terminate your program.
1492 @end deftypefun
1494 @c xmalloc.c:38
1495 @deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize})
1497 Allocate memory without fail, and set it to zero.  This routine functions
1498 like @code{calloc}, but will behave the same as @code{xmalloc} if memory
1499 cannot be found.
1501 @end deftypefn
1503 @c xexit.c:22
1504 @deftypefn Replacement void xexit (int @var{code})
1506 Terminates the program.  If any functions have been registered with
1507 the @code{xatexit} replacement function, they will be called first.
1508 Termination is handled via the system's normal @code{exit} call.
1510 @end deftypefn
1512 @c xmalloc.c:22
1513 @deftypefn Replacement void* xmalloc (size_t)
1515 Allocate memory without fail.  If @code{malloc} fails, this will print
1516 a message to @code{stderr} (using the name set by
1517 @code{xmalloc_set_program_name},
1518 if any) and then call @code{xexit}.  Note that it is therefore safe for
1519 a program to contain @code{#define malloc xmalloc} in its source.
1521 @end deftypefn
1523 @c xmalloc.c:53
1524 @deftypefn Replacement void xmalloc_failed (size_t)
1526 This function is not meant to be called by client code, and is listed
1527 here for completeness only.  If any of the allocation routines fail, this
1528 function will be called to print an error message and terminate execution.
1530 @end deftypefn
1532 @c xmalloc.c:46
1533 @deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
1535 You can use this to set the name of the program used by
1536 @code{xmalloc_failed} when printing a failure message.
1538 @end deftypefn
1540 @c xmemdup.c:7
1541 @deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})
1543 Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
1544 are allocated, then @var{copy_size} bytes from @var{input} are copied into
1545 it, and the new memory is returned.  If fewer bytes are copied than were
1546 allocated, the remaining memory is zeroed.
1548 @end deftypefn
1550 @c xmalloc.c:32
1551 @deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size})
1552 Reallocate memory without fail.  This routine functions like @code{realloc},
1553 but will behave the same as @code{xmalloc} if memory cannot be found.
1555 @end deftypefn
1557 @c xstrdup.c:7
1558 @deftypefn Replacement char* xstrdup (const char *@var{s})
1560 Duplicates a character string without fail, using @code{xmalloc} to
1561 obtain memory.
1563 @end deftypefn
1565 @c xstrerror.c:7
1566 @deftypefn Replacement char* xstrerror (int @var{errnum})
1568 Behaves exactly like the standard @code{strerror} function, but
1569 will never return a @code{NULL} pointer.
1571 @end deftypefn
1573 @c xstrndup.c:23
1574 @deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n})
1576 Returns a pointer to a copy of @var{s} with at most @var{n} characters
1577 without fail, using @code{xmalloc} to obtain memory.  The result is
1578 always NUL terminated.
1580 @end deftypefn