daily update
[binutils.git] / libiberty / functions.texi
blob34566d8f17abefa997039589d2d08a3743a35d2b
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}.  If you have not
692 yet called @code{pex_get_times} or @code{pex_get_status}, this will
693 try to kill the subprocesses.
695 @end deftypefn
697 @c pexecute.txh:241
698 @deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector})
700 Returns the exit status of all programs run using @var{obj}.
701 @var{count} is the number of results expected.  The results will be
702 placed into @var{vector}.  The results are in the order of the calls
703 to @code{pex_run}.  Returns 0 on error, 1 on success.
705 @end deftypefn
707 @c pexecute.txh:250
708 @deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector})
710 Returns the process execution times of all programs run using
711 @var{obj}.  @var{count} is the number of results expected.  The
712 results will be placed into @var{vector}.  The results are in the
713 order of the calls to @code{pex_run}.  Returns 0 on error, 1 on
714 success.
716 @code{struct pex_time} has the following fields of the type
717 @code{unsigned long}: @code{user_seconds},
718 @code{user_microseconds}, @code{system_seconds},
719 @code{system_microseconds}.  On systems which do not support reporting
720 process times, all the fields will be set to @code{0}.
722 @end deftypefn
724 @c pexecute.txh:2
725 @deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase})
727 Prepare to execute one or more programs, with standard output of each
728 program fed to standard input of the next.  This is a system
729 independent interface to execute a pipeline.
731 @var{flags} is a bitwise combination of the following:
733 @table @code
735 @vindex PEX_RECORD_TIMES
736 @item PEX_RECORD_TIMES
737 Record subprocess times if possible.
739 @vindex PEX_USE_PIPES
740 @item PEX_USE_PIPES
741 Use pipes for communication between processes, if possible.
743 @vindex PEX_SAVE_TEMPS
744 @item PEX_SAVE_TEMPS
745 Don't delete temporary files used for communication between
746 processes.
748 @end table
750 @var{pname} is the name of program to be executed, used in error
751 messages.  @var{tempbase} is a base name to use for any required
752 temporary files; it may be @code{NULL} to use a randomly chosen name.
754 @end deftypefn
756 @c pexecute.txh:155
757 @deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{in_name})
759 Return a stream for a temporary file to pass to the first program in
760 the pipeline as input.
762 The name of the input file is chosen according to the same rules
763 @code{pex_run} uses to choose output file names, based on
764 @var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}.
766 Don't call @code{fclose} on the returned stream; the first call to
767 @code{pex_run} closes it automatically.
769 If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in
770 binary mode; otherwise, open it in the default mode.  Including
771 @code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix.
772 @end deftypefn
774 @c pexecute.txh:172
775 @deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, int @var{binary})
777 Return a stream @var{fp} for a pipe connected to the standard input of
778 the first program in the pipeline; @var{fp} is opened for writing.
779 You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call
780 that returned @var{obj}.
782 You must close @var{fp} using @code{fclose} yourself when you have
783 finished writing data to the pipeline.
785 The file descriptor underlying @var{fp} is marked not to be inherited
786 by child processes.
788 On systems that do not support pipes, this function returns
789 @code{NULL}, and sets @code{errno} to @code{EINVAL}.  If you would
790 like to write code that is portable to all systems the @code{pex}
791 functions support, consider using @code{pex_input_file} instead.
793 There are two opportunities for deadlock using
794 @code{pex_input_pipe}:
796 @itemize @bullet
797 @item
798 Most systems' pipes can buffer only a fixed amount of data; a process
799 that writes to a full pipe blocks.  Thus, if you write to @file{fp}
800 before starting the first process, you run the risk of blocking when
801 there is no child process yet to read the data and allow you to
802 continue.  @code{pex_input_pipe} makes no promises about the
803 size of the pipe's buffer, so if you need to write any data at all
804 before starting the first process in the pipeline, consider using
805 @code{pex_input_file} instead.
807 @item
808 Using @code{pex_input_pipe} and @code{pex_read_output} together
809 may also cause deadlock.  If the output pipe fills up, so that each
810 program in the pipeline is waiting for the next to read more data, and
811 you fill the input pipe by writing more data to @var{fp}, then there
812 is no way to make progress: the only process that could read data from
813 the output pipe is you, but you are blocked on the input pipe.
815 @end itemize
817 @end deftypefn
819 @c pexecute.txh:274
820 @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})
822 An interface to permit the easy execution of a
823 single program.  The return value and most of the parameters are as
824 for a call to @code{pex_run}.  @var{flags} is restricted to a
825 combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and
826 @code{PEX_BINARY_OUTPUT}.  @var{outname} is interpreted as if
827 @code{PEX_LAST} were set.  On a successful return, @code{*@var{status}} will
828 be set to the exit status of the program.
830 @end deftypefn
832 @c pexecute.txh:228
833 @deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, int @var{binary})
835 Returns a @code{FILE} pointer which may be used to read the standard
836 error of the last program in the pipeline.  When this is used,
837 @code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
838 this is called, @code{pex_run} may no longer be called with the same
839 @var{obj}.  @var{binary} should be non-zero if the file should be
840 opened in binary mode.  Don't call @code{fclose} on the returned file;
841 it will be closed by @code{pex_free}.
843 @end deftypefn
845 @c pexecute.txh:216
846 @deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary})
848 Returns a @code{FILE} pointer which may be used to read the standard
849 output of the last program in the pipeline.  When this is used,
850 @code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
851 this is called, @code{pex_run} may no longer be called with the same
852 @var{obj}.  @var{binary} should be non-zero if the file should be
853 opened in binary mode.  Don't call @code{fclose} on the returned file;
854 it will be closed by @code{pex_free}.
856 @end deftypefn
858 @c pexecute.txh:33
859 @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})
861 Execute one program in a pipeline.  On success this returns
862 @code{NULL}.  On failure it returns an error message, a statically
863 allocated string.
865 @var{obj} is returned by a previous call to @code{pex_init}.
867 @var{flags} is a bitwise combination of the following:
869 @table @code
871 @vindex PEX_LAST
872 @item PEX_LAST
873 This must be set on the last program in the pipeline.  In particular,
874 it should be set when executing a single program.  The standard output
875 of the program will be sent to @var{outname}, or, if @var{outname} is
876 @code{NULL}, to the standard output of the calling program.  Do @emph{not}
877 set this bit if you want to call @code{pex_read_output}
878 (described below).  After a call to @code{pex_run} with this bit set,
879 @var{pex_run} may no longer be called with the same @var{obj}.
881 @vindex PEX_SEARCH
882 @item PEX_SEARCH
883 Search for the program using the user's executable search path.
885 @vindex PEX_SUFFIX
886 @item PEX_SUFFIX
887 @var{outname} is a suffix.  See the description of @var{outname},
888 below.
890 @vindex PEX_STDERR_TO_STDOUT
891 @item PEX_STDERR_TO_STDOUT
892 Send the program's standard error to standard output, if possible.
894 @vindex PEX_BINARY_INPUT
895 @vindex PEX_BINARY_OUTPUT
896 @vindex PEX_BINARY_ERROR
897 @item PEX_BINARY_INPUT
898 @itemx PEX_BINARY_OUTPUT
899 @itemx PEX_BINARY_ERROR
900 The standard input (output or error) of the program should be read (written) in
901 binary mode rather than text mode.  These flags are ignored on systems
902 which do not distinguish binary mode and text mode, such as Unix.  For
903 proper behavior these flags should match appropriately---a call to
904 @code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
905 call using @code{PEX_BINARY_INPUT}.
907 @vindex PEX_STDERR_TO_PIPE
908 @item PEX_STDERR_TO_PIPE
909 Send the program's standard error to a pipe, if possible.  This flag
910 cannot be specified together with @code{PEX_STDERR_TO_STDOUT}.  This
911 flag can be specified only on the last program in pipeline.
913 @end table
915 @var{executable} is the program to execute.  @var{argv} is the set of
916 arguments to pass to the program; normally @code{@var{argv}[0]} will
917 be a copy of @var{executable}.
919 @var{outname} is used to set the name of the file to use for standard
920 output.  There are two cases in which no output file will be used:
922 @enumerate
923 @item
924 if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES}
925 was set in the call to @code{pex_init}, and the system supports pipes
927 @item
928 if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
929 @code{NULL}
930 @end enumerate
932 @noindent
933 Otherwise the code will use a file to hold standard
934 output.  If @code{PEX_LAST} is not set, this file is considered to be
935 a temporary file, and it will be removed when no longer needed, unless
936 @code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}.
938 There are two cases to consider when setting the name of the file to
939 hold standard output.
941 @enumerate
942 @item
943 @code{PEX_SUFFIX} is set in @var{flags}.  In this case
944 @var{outname} may not be @code{NULL}.  If the @var{tempbase} parameter
945 to @code{pex_init} was not @code{NULL}, then the output file name is
946 the concatenation of @var{tempbase} and @var{outname}.  If
947 @var{tempbase} was @code{NULL}, then the output file name is a random
948 file name ending in @var{outname}.
950 @item
951 @code{PEX_SUFFIX} was not set in @var{flags}.  In this
952 case, if @var{outname} is not @code{NULL}, it is used as the output
953 file name.  If @var{outname} is @code{NULL}, and @var{tempbase} was
954 not NULL, the output file name is randomly chosen using
955 @var{tempbase}.  Otherwise the output file name is chosen completely
956 at random.
957 @end enumerate
959 @var{errname} is the file name to use for standard error output.  If
960 it is @code{NULL}, standard error is the same as the caller's.
961 Otherwise, standard error is written to the named file.
963 On an error return, the code sets @code{*@var{err}} to an @code{errno}
964 value, or to 0 if there is no relevant @code{errno}.
966 @end deftypefn
968 @c pexecute.txh:142
969 @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})
971 Execute one program in a pipeline, permitting the environment for the
972 program to be specified.  Behaviour and parameters not listed below are
973 as for @code{pex_run}.
975 @var{env} is the environment for the child process, specified as an array of
976 character pointers.  Each element of the array should point to a string of the
977 form @code{VAR=VALUE}, with the exception of the last element that must be
978 @code{NULL}.
980 @end deftypefn
982 @c pexecute.txh:286
983 @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})
985 This is the old interface to execute one or more programs.  It is
986 still supported for compatibility purposes, but is no longer
987 documented.
989 @end deftypefn
991 @c strsignal.c:541
992 @deftypefn Supplemental void psignal (int @var{signo}, char *@var{message})
994 Print @var{message} to the standard error, followed by a colon,
995 followed by the description of the signal specified by @var{signo},
996 followed by a newline.
998 @end deftypefn
1000 @c putenv.c:21
1001 @deftypefn Supplemental int putenv (const char *@var{string})
1003 Uses @code{setenv} or @code{unsetenv} to put @var{string} into
1004 the environment or remove it.  If @var{string} is of the form
1005 @samp{name=value} the string is added; if no @samp{=} is present the
1006 name is unset/removed.
1008 @end deftypefn
1010 @c pexecute.txh:294
1011 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
1013 Another part of the old execution interface.
1015 @end deftypefn
1017 @c random.c:39
1018 @deftypefn Supplement {long int} random (void)
1019 @deftypefnx Supplement void srandom (unsigned int @var{seed})
1020 @deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n})
1021 @deftypefnx Supplement void* setstate (void *@var{arg_state})
1023 Random number functions.  @code{random} returns a random number in the
1024 range 0 to @code{LONG_MAX}.  @code{srandom} initializes the random
1025 number generator to some starting point determined by @var{seed}
1026 (else, the values returned by @code{random} are always the same for each
1027 run of the program).  @code{initstate} and @code{setstate} allow fine-grained
1028 control over the state of the random number generator.
1030 @end deftypefn
1032 @c concat.c:173
1033 @deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL})
1035 Same as @code{concat}, except that if @var{optr} is not @code{NULL} it
1036 is freed after the string is created.  This is intended to be useful
1037 when you're extending an existing string or building up a string in a
1038 loop:
1040 @example
1041   str = reconcat (str, "pre-", str, NULL);
1042 @end example
1044 @end deftypefn
1046 @c rename.c:6
1047 @deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
1049 Renames a file from @var{old} to @var{new}.  If @var{new} already
1050 exists, it is removed.
1052 @end deftypefn
1054 @c rindex.c:5
1055 @deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
1057 Returns a pointer to the last occurrence of the character @var{c} in
1058 the string @var{s}, or @code{NULL} if not found.  The use of @code{rindex} is
1059 deprecated in new programs in favor of @code{strrchr}.
1061 @end deftypefn
1063 @c setenv.c:22
1064 @deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
1065 @deftypefnx Supplemental void unsetenv (const char *@var{name})
1067 @code{setenv} adds @var{name} to the environment with value
1068 @var{value}.  If the name was already present in the environment,
1069 the new value will be stored only if @var{overwrite} is nonzero.
1070 The companion @code{unsetenv} function removes @var{name} from the
1071 environment.  This implementation is not safe for multithreaded code.
1073 @end deftypefn
1075 @c strsignal.c:348
1076 @deftypefn Extension int signo_max (void)
1078 Returns the maximum signal value for which a corresponding symbolic
1079 name or message is available.  Note that in the case where we use the
1080 @code{sys_siglist} supplied by the system, it is possible for there to
1081 be more symbolic names than messages, or vice versa.  In fact, the
1082 manual page for @code{psignal(3b)} explicitly warns that one should
1083 check the size of the table (@code{NSIG}) before indexing it, since
1084 new signal codes may be added to the system before they are added to
1085 the table.  Thus @code{NSIG} might be smaller than value implied by
1086 the largest signo value defined in @code{<signal.h>}.
1088 We return the maximum value that can be used to obtain a meaningful
1089 symbolic name or message.
1091 @end deftypefn
1093 @c sigsetmask.c:8
1094 @deftypefn Supplemental int sigsetmask (int @var{set})
1096 Sets the signal mask to the one provided in @var{set} and returns
1097 the old mask (which, for libiberty's implementation, will always
1098 be the value @code{1}).
1100 @end deftypefn
1102 @c snprintf.c:28
1103 @deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...)
1105 This function is similar to sprintf, but it will print at most @var{n}
1106 characters.  On error the return value is -1, otherwise it returns the
1107 number of characters that would have been printed had @var{n} been
1108 sufficiently large, regardless of the actual value of @var{n}.  Note
1109 some pre-C99 system libraries do not implement this correctly so users
1110 cannot generally rely on the return value if the system version of
1111 this function is used.
1113 @end deftypefn
1115 @c spaces.c:22
1116 @deftypefn Extension char* spaces (int @var{count})
1118 Returns a pointer to a memory region filled with the specified
1119 number of spaces and null terminated.  The returned pointer is
1120 valid until at least the next call.
1122 @end deftypefn
1124 @c stpcpy.c:23
1125 @deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src})
1127 Copies the string @var{src} into @var{dst}.  Returns a pointer to
1128 @var{dst} + strlen(@var{src}).
1130 @end deftypefn
1132 @c stpncpy.c:23
1133 @deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, size_t @var{len})
1135 Copies the string @var{src} into @var{dst}, copying exactly @var{len}
1136 and padding with zeros if necessary.  If @var{len} < strlen(@var{src})
1137 then return @var{dst} + @var{len}, otherwise returns @var{dst} +
1138 strlen(@var{src}).
1140 @end deftypefn
1142 @c strcasecmp.c:15
1143 @deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
1145 A case-insensitive @code{strcmp}.
1147 @end deftypefn
1149 @c strchr.c:6
1150 @deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
1152 Returns a pointer to the first occurrence of the character @var{c} in
1153 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
1154 null character, the results are undefined.
1156 @end deftypefn
1158 @c strdup.c:3
1159 @deftypefn Supplemental char* strdup (const char *@var{s})
1161 Returns a pointer to a copy of @var{s} in memory obtained from
1162 @code{malloc}, or @code{NULL} if insufficient memory was available.
1164 @end deftypefn
1166 @c strerror.c:670
1167 @deftypefn Replacement {const char*} strerrno (int @var{errnum})
1169 Given an error number returned from a system call (typically returned
1170 in @code{errno}), returns a pointer to a string containing the
1171 symbolic name of that error number, as found in @code{<errno.h>}.
1173 If the supplied error number is within the valid range of indices for
1174 symbolic names, but no name is available for the particular error
1175 number, then returns the string @samp{Error @var{num}}, where @var{num}
1176 is the error number.
1178 If the supplied error number is not within the range of valid
1179 indices, then returns @code{NULL}.
1181 The contents of the location pointed to are only guaranteed to be
1182 valid until the next call to @code{strerrno}.
1184 @end deftypefn
1186 @c strerror.c:603
1187 @deftypefn Supplemental char* strerror (int @var{errnoval})
1189 Maps an @code{errno} number to an error message string, the contents
1190 of which are implementation defined.  On systems which have the
1191 external variables @code{sys_nerr} and @code{sys_errlist}, these
1192 strings will be the same as the ones used by @code{perror}.
1194 If the supplied error number is within the valid range of indices for
1195 the @code{sys_errlist}, but no message is available for the particular
1196 error number, then returns the string @samp{Error @var{num}}, where
1197 @var{num} is the error number.
1199 If the supplied error number is not a valid index into
1200 @code{sys_errlist}, returns @code{NULL}.
1202 The returned string is only guaranteed to be valid only until the
1203 next call to @code{strerror}.
1205 @end deftypefn
1207 @c strncasecmp.c:15
1208 @deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
1210 A case-insensitive @code{strncmp}.
1212 @end deftypefn
1214 @c strncmp.c:6
1215 @deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
1217 Compares the first @var{n} bytes of two strings, returning a value as
1218 @code{strcmp}.
1220 @end deftypefn
1222 @c strndup.c:23
1223 @deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n})
1225 Returns a pointer to a copy of @var{s} with at most @var{n} characters
1226 in memory obtained from @code{malloc}, or @code{NULL} if insufficient
1227 memory was available.  The result is always NUL terminated.
1229 @end deftypefn
1231 @c strrchr.c:6
1232 @deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
1234 Returns a pointer to the last occurrence of the character @var{c} in
1235 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
1236 null character, the results are undefined.
1238 @end deftypefn
1240 @c strsignal.c:383
1241 @deftypefn Supplemental {const char *} strsignal (int @var{signo})
1243 Maps an signal number to an signal message string, the contents of
1244 which are implementation defined.  On systems which have the external
1245 variable @code{sys_siglist}, these strings will be the same as the
1246 ones used by @code{psignal()}.
1248 If the supplied signal number is within the valid range of indices for
1249 the @code{sys_siglist}, but no message is available for the particular
1250 signal number, then returns the string @samp{Signal @var{num}}, where
1251 @var{num} is the signal number.
1253 If the supplied signal number is not a valid index into
1254 @code{sys_siglist}, returns @code{NULL}.
1256 The returned string is only guaranteed to be valid only until the next
1257 call to @code{strsignal}.
1259 @end deftypefn
1261 @c strsignal.c:448
1262 @deftypefn Extension {const char*} strsigno (int @var{signo})
1264 Given an signal number, returns a pointer to a string containing the
1265 symbolic name of that signal number, as found in @code{<signal.h>}.
1267 If the supplied signal number is within the valid range of indices for
1268 symbolic names, but no name is available for the particular signal
1269 number, then returns the string @samp{Signal @var{num}}, where
1270 @var{num} is the signal number.
1272 If the supplied signal number is not within the range of valid
1273 indices, then returns @code{NULL}.
1275 The contents of the location pointed to are only guaranteed to be
1276 valid until the next call to @code{strsigno}.
1278 @end deftypefn
1280 @c strstr.c:6
1281 @deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
1283 This function searches for the substring @var{sub} in the string
1284 @var{string}, not including the terminating null characters.  A pointer
1285 to the first occurrence of @var{sub} is returned, or @code{NULL} if the
1286 substring is absent.  If @var{sub} points to a string with zero
1287 length, the function returns @var{string}.
1289 @end deftypefn
1291 @c strtod.c:27
1292 @deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})
1294 This ISO C function converts the initial portion of @var{string} to a
1295 @code{double}.  If @var{endptr} is not @code{NULL}, a pointer to the
1296 character after the last character used in the conversion is stored in
1297 the location referenced by @var{endptr}.  If no conversion is
1298 performed, zero is returned and the value of @var{string} is stored in
1299 the location referenced by @var{endptr}.
1301 @end deftypefn
1303 @c strerror.c:729
1304 @deftypefn Extension int strtoerrno (const char *@var{name})
1306 Given the symbolic name of a error number (e.g., @code{EACCES}), map it
1307 to an errno value.  If no translation is found, returns 0.
1309 @end deftypefn
1311 @c strtol.c:33
1312 @deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
1313 @deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base})
1315 The @code{strtol} function converts the string in @var{string} to a
1316 long integer value according to the given @var{base}, which must be
1317 between 2 and 36 inclusive, or be the special value 0.  If @var{base}
1318 is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
1319 to indicate bases 8 and 16, respectively, else default to base 10.
1320 When the base is 16 (either explicitly or implicitly), a prefix of
1321 @code{0x} is allowed.  The handling of @var{endptr} is as that of
1322 @code{strtod} above.  The @code{strtoul} function is the same, except
1323 that the converted value is unsigned.
1325 @end deftypefn
1327 @c strsignal.c:502
1328 @deftypefn Extension int strtosigno (const char *@var{name})
1330 Given the symbolic name of a signal, map it to a signal number.  If no
1331 translation is found, returns 0.
1333 @end deftypefn
1335 @c strverscmp.c:25
1336 @deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2})
1337 The @code{strverscmp} function compares the string @var{s1} against
1338 @var{s2}, considering them as holding indices/version numbers.  Return
1339 value follows the same conventions as found in the @code{strverscmp}
1340 function.  In fact, if @var{s1} and @var{s2} contain no digits,
1341 @code{strverscmp} behaves like @code{strcmp}.
1343 Basically, we compare strings normally (character by character), until
1344 we find a digit in each string - then we enter a special comparison
1345 mode, where each sequence of digits is taken as a whole.  If we reach the
1346 end of these two parts without noticing a difference, we return to the
1347 standard comparison mode.  There are two types of numeric parts:
1348 "integral" and "fractional" (those  begin with a '0'). The types
1349 of the numeric parts affect the way we sort them:
1351 @itemize @bullet
1352 @item
1353 integral/integral: we compare values as you would expect.
1355 @item
1356 fractional/integral: the fractional part is less than the integral one.
1357 Again, no surprise.
1359 @item
1360 fractional/fractional: the things become a bit more complex.
1361 If the common prefix contains only leading zeroes, the longest part is less
1362 than the other one; else the comparison behaves normally.
1363 @end itemize
1365 @smallexample
1366 strverscmp ("no digit", "no digit")
1367     @result{} 0    // @r{same behavior as strcmp.}
1368 strverscmp ("item#99", "item#100")
1369     @result{} <0   // @r{same prefix, but 99 < 100.}
1370 strverscmp ("alpha1", "alpha001")
1371     @result{} >0   // @r{fractional part inferior to integral one.}
1372 strverscmp ("part1_f012", "part1_f01")
1373     @result{} >0   // @r{two fractional parts.}
1374 strverscmp ("foo.009", "foo.0")
1375     @result{} <0   // @r{idem, but with leading zeroes only.}
1376 @end smallexample
1378 This function is especially useful when dealing with filename sorting,
1379 because filenames frequently hold indices/version numbers.
1380 @end deftypefun
1382 @c tmpnam.c:3
1383 @deftypefn Supplemental char* tmpnam (char *@var{s})
1385 This function attempts to create a name for a temporary file, which
1386 will be a valid file name yet not exist when @code{tmpnam} checks for
1387 it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
1388 or be @code{NULL}.  Use of this function creates a security risk, and it must
1389 not be used in new projects.  Use @code{mkstemp} instead.
1391 @end deftypefn
1393 @c unlink-if-ordinary.c:27
1394 @deftypefn Supplemental int unlink_if_ordinary (const char*)
1396 Unlinks the named file, unless it is special (e.g. a device file).
1397 Returns 0 when the file was unlinked, a negative value (and errno set) when
1398 there was an error deleting the file, and a positive value if no attempt
1399 was made to unlink the file because it is special.
1401 @end deftypefn
1403 @c fopen_unlocked.c:31
1404 @deftypefn Extension void unlock_std_streams (void)
1406 If the OS supports it, ensure that the standard I/O streams,
1407 @code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any
1408 multi-threaded locking.  Otherwise do nothing.
1410 @end deftypefn
1412 @c fopen_unlocked.c:23
1413 @deftypefn Extension void unlock_stream (FILE * @var{stream})
1415 If the OS supports it, ensure that the supplied stream is setup to
1416 avoid any multi-threaded locking.  Otherwise leave the @code{FILE}
1417 pointer unchanged.  If the @var{stream} is @code{NULL} do nothing.
1419 @end deftypefn
1421 @c vasprintf.c:47
1422 @deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args})
1424 Like @code{vsprintf}, but instead of passing a pointer to a buffer,
1425 you pass a pointer to a pointer.  This function will compute the size
1426 of the buffer needed, allocate memory with @code{malloc}, and store a
1427 pointer to the allocated memory in @code{*@var{resptr}}.  The value
1428 returned is the same as @code{vsprintf} would return.  If memory could
1429 not be allocated, minus one is returned and @code{NULL} is stored in
1430 @code{*@var{resptr}}.
1432 @end deftypefn
1434 @c vfork.c:6
1435 @deftypefn Supplemental int vfork (void)
1437 Emulates @code{vfork} by calling @code{fork} and returning its value.
1439 @end deftypefn
1441 @c vprintf.c:3
1442 @deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
1443 @deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
1444 @deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})
1446 These functions are the same as @code{printf}, @code{fprintf}, and
1447 @code{sprintf}, respectively, except that they are called with a
1448 @code{va_list} instead of a variable number of arguments.  Note that
1449 they do not call @code{va_end}; this is the application's
1450 responsibility.  In @libib{} they are implemented in terms of the
1451 nonstandard but common function @code{_doprnt}.
1453 @end deftypefn
1455 @c vsnprintf.c:28
1456 @deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap})
1458 This function is similar to vsprintf, but it will print at most
1459 @var{n} characters.  On error the return value is -1, otherwise it
1460 returns the number of characters that would have been printed had
1461 @var{n} been sufficiently large, regardless of the actual value of
1462 @var{n}.  Note some pre-C99 system libraries do not implement this
1463 correctly so users cannot generally rely on the return value if the
1464 system version of this function is used.
1466 @end deftypefn
1468 @c waitpid.c:3
1469 @deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
1471 This is a wrapper around the @code{wait} function.  Any ``special''
1472 values of @var{pid} depend on your implementation of @code{wait}, as
1473 does the return value.  The third argument is unused in @libib{}.
1475 @end deftypefn
1477 @c argv.c:293
1478 @deftypefn Extension int writeargv (const char **@var{argv}, FILE *@var{file})
1480 Write each member of ARGV, handling all necessary quoting, to the file
1481 named by FILE, separated by whitespace.  Return 0 on success, non-zero
1482 if an error occurred while writing to FILE.
1484 @end deftypefn
1486 @c xatexit.c:11
1487 @deftypefun int xatexit (void (*@var{fn}) (void))
1489 Behaves as the standard @code{atexit} function, but with no limit on
1490 the number of registered functions.  Returns 0 on success, or @minus{}1 on
1491 failure.  If you use @code{xatexit} to register functions, you must use
1492 @code{xexit} to terminate your program.
1494 @end deftypefun
1496 @c xmalloc.c:38
1497 @deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize})
1499 Allocate memory without fail, and set it to zero.  This routine functions
1500 like @code{calloc}, but will behave the same as @code{xmalloc} if memory
1501 cannot be found.
1503 @end deftypefn
1505 @c xexit.c:22
1506 @deftypefn Replacement void xexit (int @var{code})
1508 Terminates the program.  If any functions have been registered with
1509 the @code{xatexit} replacement function, they will be called first.
1510 Termination is handled via the system's normal @code{exit} call.
1512 @end deftypefn
1514 @c xmalloc.c:22
1515 @deftypefn Replacement void* xmalloc (size_t)
1517 Allocate memory without fail.  If @code{malloc} fails, this will print
1518 a message to @code{stderr} (using the name set by
1519 @code{xmalloc_set_program_name},
1520 if any) and then call @code{xexit}.  Note that it is therefore safe for
1521 a program to contain @code{#define malloc xmalloc} in its source.
1523 @end deftypefn
1525 @c xmalloc.c:53
1526 @deftypefn Replacement void xmalloc_failed (size_t)
1528 This function is not meant to be called by client code, and is listed
1529 here for completeness only.  If any of the allocation routines fail, this
1530 function will be called to print an error message and terminate execution.
1532 @end deftypefn
1534 @c xmalloc.c:46
1535 @deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
1537 You can use this to set the name of the program used by
1538 @code{xmalloc_failed} when printing a failure message.
1540 @end deftypefn
1542 @c xmemdup.c:7
1543 @deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})
1545 Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
1546 are allocated, then @var{copy_size} bytes from @var{input} are copied into
1547 it, and the new memory is returned.  If fewer bytes are copied than were
1548 allocated, the remaining memory is zeroed.
1550 @end deftypefn
1552 @c xmalloc.c:32
1553 @deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size})
1554 Reallocate memory without fail.  This routine functions like @code{realloc},
1555 but will behave the same as @code{xmalloc} if memory cannot be found.
1557 @end deftypefn
1559 @c xstrdup.c:7
1560 @deftypefn Replacement char* xstrdup (const char *@var{s})
1562 Duplicates a character string without fail, using @code{xmalloc} to
1563 obtain memory.
1565 @end deftypefn
1567 @c xstrerror.c:7
1568 @deftypefn Replacement char* xstrerror (int @var{errnum})
1570 Behaves exactly like the standard @code{strerror} function, but
1571 will never return a @code{NULL} pointer.
1573 @end deftypefn
1575 @c xstrndup.c:23
1576 @deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n})
1578 Returns a pointer to a copy of @var{s} with at most @var{n} characters
1579 without fail, using @code{xmalloc} to obtain memory.  The result is
1580 always NUL terminated.
1582 @end deftypefn