OSDN Git Service

2007-01-31 Andrew Haley <aph@redhat.com>
[pf3gnuchains/gcc-fork.git] / libiberty / functions.texi
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.
5
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:
13
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.
18
19 @item HOST_CHARSET_ASCII
20 The host character set is ASCII.
21
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
27
28 @c alloca.c:26
29 @deftypefn Replacement void* alloca (size_t @var{size})
30
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.
36
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.
43
44 @end deftypefn
45
46 @c asprintf.c:32
47 @deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...)
48
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}}.
56
57 @end deftypefn
58
59 @c atexit.c:6
60 @deftypefn Supplemental int atexit (void (*@var{f})())
61
62 Causes function @var{f} to be called at exit.  Returns 0.
63
64 @end deftypefn
65
66 @c basename.c:6
67 @deftypefn Supplemental char* basename (const char *@var{name})
68
69 Returns a pointer to the last component of pathname @var{name}.
70 Behavior is undefined if the pathname ends in a directory separator.
71
72 @end deftypefn
73
74 @c bcmp.c:6
75 @deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count})
76
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}).
82
83 @end deftypefn
84
85 @c bcopy.c:3
86 @deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length})
87
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.
90
91 @end deftypefn
92
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 *))
95
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.
104
105 @end deftypefn
106
107 @c argv.c:124
108 @deftypefn Extension char** buildargv (char *@var{sp})
109
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.
116
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.
121
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.
125
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.
129
130 @end deftypefn
131
132 @c bzero.c:6
133 @deftypefn Supplemental void bzero (char *@var{mem}, int @var{count})
134
135 Zeros @var{count} bytes starting at @var{mem}.  Use of this function
136 is deprecated in favor of @code{memset}.
137
138 @end deftypefn
139
140 @c calloc.c:6
141 @deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize})
142
143 Uses @code{malloc} to allocate storage for @var{nelem} objects of
144 @var{elsize} bytes each, then zeros the memory.
145
146 @end deftypefn
147
148 @c choose-temp.c:42
149 @deftypefn Extension char* choose_temp_base (void)
150
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}.
155
156 This function is provided for backwards compatability only.  Its use is
157 not recommended.
158
159 @end deftypefn
160
161 @c make-temp-file.c:87
162 @deftypefn Replacement char* choose_tmpdir ()
163
164 Returns a pointer to a directory path suitable for creating temporary
165 files in.
166
167 @end deftypefn
168
169 @c clock.c:27
170 @deftypefn Supplemental long clock (void)
171
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.
175
176 @end deftypefn
177
178 @c concat.c:24
179 @deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL})
180
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.
185
186 @end deftypefn
187
188 @c argv.c:52
189 @deftypefn Extension char** dupargv (char **@var{vector})
190
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.
196
197 @end deftypefn
198
199 @c strerror.c:567
200 @deftypefn Extension int errno_max (void)
201
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>}.
211
212 We return the maximum value that can be used to obtain a meaningful
213 symbolic name or message.
214
215 @end deftypefn
216
217 @c argv.c:293
218 @deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp})
219
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.
234
235 @end deftypefn
236
237 @c fdmatch.c:23
238 @deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2})
239
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.
249
250 @end deftypefn
251
252 @c fopen_unlocked.c:48
253 @deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, const char * @var{mode})
254
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.
259
260 @end deftypefn
261
262 @c ffs.c:3
263 @deftypefn Supplemental int ffs (int @var{valu})
264
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.
268
269 @end deftypefn
270
271 @c fnmatch.txh:1
272 @deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags})
273
274 Matches @var{string} against @var{pattern}, returning zero if it
275 matches, @code{FNM_NOMATCH} if not.  @var{pattern} may contain the
276 wildcards @code{?} to match any one character, @code{*} to match any
277 zero or more characters, or a set of alternate characters in square
278 brackets, like @samp{[a-gt8]}, which match one character (@code{a}
279 through @code{g}, or @code{t}, or @code{8}, in this example) if that one
280 character is in the set.  A set may be inverted (i.e., match anything
281 except what's in the set) by giving @code{^} or @code{!} as the first
282 character in the set.  To include those characters in the set, list them
283 as anything other than the first character of the set.  To include a
284 dash in the set, list it last in the set.  A backslash character makes
285 the following character not special, so for example you could match
286 against a literal asterisk with @samp{\*}.  To match a literal
287 backslash, use @samp{\\}.
288
289 @code{flags} controls various aspects of the matching process, and is a
290 boolean OR of zero or more of the following values (defined in
291 @code{<fnmatch.h>}):
292
293 @table @code
294
295 @item FNM_PATHNAME
296 @itemx FNM_FILE_NAME
297 @var{string} is assumed to be a path name.  No wildcard will ever match
298 @code{/}.
299
300 @item FNM_NOESCAPE
301 Do not interpret backslashes as quoting the following special character.
302
303 @item FNM_PERIOD
304 A leading period (at the beginning of @var{string}, or if
305 @code{FNM_PATHNAME} after a slash) is not matched by @code{*} or
306 @code{?} but must be matched explicitly.
307
308 @item FNM_LEADING_DIR
309 Means that @var{string} also matches @var{pattern} if some initial part
310 of @var{string} matches, and is followed by @code{/} and zero or more
311 characters.  For example, @samp{foo*} would match either @samp{foobar}
312 or @samp{foobar/grill}.
313
314 @item FNM_CASEFOLD
315 Ignores case when performing the comparison.
316
317 @end table
318
319 @end deftypefn
320
321 @c fopen_unlocked.c:39
322 @deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, const char * @var{mode})
323
324 Opens and returns a @code{FILE} pointer via @code{fopen}.  If the
325 operating system supports it, ensure that the stream is setup to avoid
326 any multi-threaded locking.  Otherwise return the @code{FILE} pointer
327 unchanged.
328
329 @end deftypefn
330
331 @c argv.c:97
332 @deftypefn Extension void freeargv (char **@var{vector})
333
334 Free an argument vector that was built using @code{buildargv}.  Simply
335 scans through @var{vector}, freeing the memory for each argument until
336 the terminating @code{NULL} is found, and then frees @var{vector}
337 itself.
338
339 @end deftypefn
340
341 @c fopen_unlocked.c:57
342 @deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, const char * @var{mode}, FILE * @var{stream})
343
344 Opens and returns a @code{FILE} pointer via @code{freopen}.  If the
345 operating system supports it, ensure that the stream is setup to avoid
346 any multi-threaded locking.  Otherwise return the @code{FILE} pointer
347 unchanged.
348
349 @end deftypefn
350
351 @c getruntime.c:82
352 @deftypefn Replacement long get_run_time (void)
353
354 Returns the time used so far, in microseconds.  If possible, this is
355 the time used by this process, else it is the elapsed time since the
356 process started.
357
358 @end deftypefn
359
360 @c getcwd.c:6
361 @deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len})
362
363 Copy the absolute pathname for the current working directory into
364 @var{pathname}, which is assumed to point to a buffer of at least
365 @var{len} bytes, and return a pointer to the buffer.  If the current
366 directory's path doesn't fit in @var{len} characters, the result is
367 @code{NULL} and @code{errno} is set.  If @var{pathname} is a null pointer,
368 @code{getcwd} will obtain @var{len} bytes of space using
369 @code{malloc}.
370
371 @end deftypefn
372
373 @c getpagesize.c:5
374 @deftypefn Supplemental int getpagesize (void)
375
376 Returns the number of bytes in a page of memory.  This is the
377 granularity of many of the system memory management routines.  No
378 guarantee is made as to whether or not it is the same as the basic
379 memory management hardware page size.
380
381 @end deftypefn
382
383 @c getpwd.c:5
384 @deftypefn Supplemental char* getpwd (void)
385
386 Returns the current working directory.  This implementation caches the
387 result on the assumption that the process will not call @code{chdir}
388 between calls to @code{getpwd}.
389
390 @end deftypefn
391
392 @c gettimeofday.c:12
393 @deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz})
394
395 Writes the current time to @var{tp}.  This implementation requires
396 that @var{tz} be NULL.  Returns 0 on success, -1 on failure.
397
398 @end deftypefn
399
400 @c hex.c:33
401 @deftypefn Extension void hex_init (void)
402
403 Initializes the array mapping the current character set to
404 corresponding hex values.  This function must be called before any
405 call to @code{hex_p} or @code{hex_value}.  If you fail to call it, a
406 default ASCII-based table will normally be used on ASCII systems.
407
408 @end deftypefn
409
410 @c hex.c:42
411 @deftypefn Extension int hex_p (int @var{c})
412
413 Evaluates to non-zero if the given character is a valid hex character,
414 or zero if it is not.  Note that the value you pass will be cast to
415 @code{unsigned char} within the macro.
416
417 @end deftypefn
418
419 @c hex.c:50
420 @deftypefn Extension {unsigned int} hex_value (int @var{c})
421
422 Returns the numeric equivalent of the given character when interpreted
423 as a hexidecimal digit.  The result is undefined if you pass an
424 invalid hex digit.  Note that the value you pass will be cast to
425 @code{unsigned char} within the macro.
426
427 The @code{hex_value} macro returns @code{unsigned int}, rather than
428 signed @code{int}, to make it easier to use in parsing addresses from
429 hex dump files: a signed @code{int} would be sign-extended when
430 converted to a wider unsigned type --- like @code{bfd_vma}, on some
431 systems.
432
433 @end deftypefn
434
435 @c index.c:5
436 @deftypefn Supplemental char* index (char *@var{s}, int @var{c})
437
438 Returns a pointer to the first occurrence of the character @var{c} in
439 the string @var{s}, or @code{NULL} if not found.  The use of @code{index} is
440 deprecated in new programs in favor of @code{strchr}.
441
442 @end deftypefn
443
444 @c insque.c:6
445 @deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred})
446 @deftypefnx Supplemental void remque (struct qelem *@var{elem})
447
448 Routines to manipulate queues built from doubly linked lists.  The
449 @code{insque} routine inserts @var{elem} in the queue immediately
450 after @var{pred}.  The @code{remque} routine removes @var{elem} from
451 its containing queue.  These routines expect to be passed pointers to
452 structures which have as their first members a forward pointer and a
453 back pointer, like this prototype (although no prototype is provided):
454
455 @example
456 struct qelem @{
457   struct qelem *q_forw;
458   struct qelem *q_back;
459   char q_data[];
460 @};
461 @end example
462
463 @end deftypefn
464
465 @c safe-ctype.c:46
466 @deffn  Extension ISALPHA  (@var{c})
467 @deffnx Extension ISALNUM  (@var{c})
468 @deffnx Extension ISBLANK  (@var{c})
469 @deffnx Extension ISCNTRL  (@var{c})
470 @deffnx Extension ISDIGIT  (@var{c})
471 @deffnx Extension ISGRAPH  (@var{c})
472 @deffnx Extension ISLOWER  (@var{c})
473 @deffnx Extension ISPRINT  (@var{c})
474 @deffnx Extension ISPUNCT  (@var{c})
475 @deffnx Extension ISSPACE  (@var{c})
476 @deffnx Extension ISUPPER  (@var{c})
477 @deffnx Extension ISXDIGIT (@var{c})
478
479 These twelve macros are defined by @file{safe-ctype.h}.  Each has the
480 same meaning as the corresponding macro (with name in lowercase)
481 defined by the standard header @file{ctype.h}.  For example,
482 @code{ISALPHA} returns true for alphabetic characters and false for
483 others.  However, there are two differences between these macros and
484 those provided by @file{ctype.h}:
485
486 @itemize @bullet
487 @item These macros are guaranteed to have well-defined behavior for all 
488 values representable by @code{signed char} and @code{unsigned char}, and
489 for @code{EOF}.
490
491 @item These macros ignore the current locale; they are true for these
492 fixed sets of characters:
493 @multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada}
494 @item @code{ALPHA}  @tab @kbd{A-Za-z}
495 @item @code{ALNUM}  @tab @kbd{A-Za-z0-9}
496 @item @code{BLANK}  @tab @kbd{space tab}
497 @item @code{CNTRL}  @tab @code{!PRINT}
498 @item @code{DIGIT}  @tab @kbd{0-9}
499 @item @code{GRAPH}  @tab @code{ALNUM || PUNCT}
500 @item @code{LOWER}  @tab @kbd{a-z}
501 @item @code{PRINT}  @tab @code{GRAPH ||} @kbd{space}
502 @item @code{PUNCT}  @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?}
503 @item @code{SPACE}  @tab @kbd{space tab \n \r \f \v}
504 @item @code{UPPER}  @tab @kbd{A-Z}
505 @item @code{XDIGIT} @tab @kbd{0-9A-Fa-f}
506 @end multitable
507
508 Note that, if the host character set is ASCII or a superset thereof,
509 all these macros will return false for all values of @code{char} outside
510 the range of 7-bit ASCII.  In particular, both ISPRINT and ISCNTRL return
511 false for characters with numeric values from 128 to 255.
512 @end itemize
513 @end deffn
514
515 @c safe-ctype.c:95
516 @deffn  Extension ISIDNUM         (@var{c})
517 @deffnx Extension ISIDST          (@var{c})
518 @deffnx Extension IS_VSPACE       (@var{c})
519 @deffnx Extension IS_NVSPACE      (@var{c})
520 @deffnx Extension IS_SPACE_OR_NUL (@var{c})
521 @deffnx Extension IS_ISOBASIC     (@var{c})
522 These six macros are defined by @file{safe-ctype.h} and provide
523 additional character classes which are useful when doing lexical
524 analysis of C or similar languages.  They are true for the following
525 sets of characters:
526
527 @multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada}
528 @item @code{IDNUM}        @tab @kbd{A-Za-z0-9_}
529 @item @code{IDST}         @tab @kbd{A-Za-z_}
530 @item @code{VSPACE}       @tab @kbd{\r \n}
531 @item @code{NVSPACE}      @tab @kbd{space tab \f \v \0}
532 @item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE}
533 @item @code{ISOBASIC}     @tab @code{VSPACE || NVSPACE || PRINT}
534 @end multitable
535 @end deffn
536
537 @c lbasename.c:23
538 @deftypefn Replacement {const char*} lbasename (const char *@var{name})
539
540 Given a pointer to a string containing a typical pathname
541 (@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the
542 last component of the pathname (@samp{ls.c} in this case).  The
543 returned pointer is guaranteed to lie within the original
544 string.  This latter fact is not true of many vendor C
545 libraries, which return special strings or modify the passed
546 strings for particular input.
547
548 In particular, the empty string returns the same empty string,
549 and a path ending in @code{/} returns the empty string after it.
550
551 @end deftypefn
552
553 @c lrealpath.c:25
554 @deftypefn Replacement {const char*} lrealpath (const char *@var{name})
555
556 Given a pointer to a string containing a pathname, returns a canonical
557 version of the filename.  Symlinks will be resolved, and ``.'' and ``..''
558 components will be simplified.  The returned value will be allocated using
559 @code{malloc}, or @code{NULL} will be returned on a memory allocation error.
560
561 @end deftypefn
562
563 @c make-relative-prefix.c:24
564 @deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, const char *@var{bin_prefix}, const char *@var{prefix})
565
566 Given three paths @var{progname}, @var{bin_prefix}, @var{prefix},
567 return the path that is in the same position relative to
568 @var{progname}'s directory as @var{prefix} is relative to
569 @var{bin_prefix}.  That is, a string starting with the directory
570 portion of @var{progname}, followed by a relative pathname of the
571 difference between @var{bin_prefix} and @var{prefix}.
572
573 If @var{progname} does not contain any directory separators,
574 @code{make_relative_prefix} will search @env{PATH} to find a program
575 named @var{progname}.  Also, if @var{progname} is a symbolic link,
576 the symbolic link will be resolved.
577
578 For example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta},
579 @var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is
580 @code{/red/green/blue/gcc}, then this function will return
581 @code{/red/green/blue/../../omega/}.
582
583 The return value is normally allocated via @code{malloc}.  If no
584 relative prefix can be found, return @code{NULL}.
585
586 @end deftypefn
587
588 @c make-temp-file.c:137
589 @deftypefn Replacement char* make_temp_file (const char *@var{suffix})
590
591 Return a temporary file name (as a string) or @code{NULL} if unable to
592 create one.  @var{suffix} is a suffix to append to the file name.  The
593 string is @code{malloc}ed, and the temporary file has been created.
594
595 @end deftypefn
596
597 @c memchr.c:3
598 @deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n})
599
600 This function searches memory starting at @code{*@var{s}} for the
601 character @var{c}.  The search only ends with the first occurrence of
602 @var{c}, or after @var{length} characters; in particular, a null
603 character does not terminate the search.  If the character @var{c} is
604 found within @var{length} characters of @code{*@var{s}}, a pointer
605 to the character is returned.  If @var{c} is not found, then @code{NULL} is
606 returned.
607
608 @end deftypefn
609
610 @c memcmp.c:6
611 @deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count})
612
613 Compares the first @var{count} bytes of two areas of memory.  Returns
614 zero if they are the same, a value less than zero if @var{x} is
615 lexically less than @var{y}, or a value greater than zero if @var{x}
616 is lexically greater than @var{y}.  Note that lexical order is determined
617 as if comparing unsigned char arrays.
618
619 @end deftypefn
620
621 @c memcpy.c:6
622 @deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
623
624 Copies @var{length} bytes from memory region @var{in} to region
625 @var{out}.  Returns a pointer to @var{out}.
626
627 @end deftypefn
628
629 @c memmove.c:6
630 @deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count})
631
632 Copies @var{count} bytes from memory area @var{from} to memory area
633 @var{to}, returning a pointer to @var{to}.
634
635 @end deftypefn
636
637 @c mempcpy.c:23
638 @deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
639
640 Copies @var{length} bytes from memory region @var{in} to region
641 @var{out}.  Returns a pointer to @var{out} + @var{length}.
642
643 @end deftypefn
644
645 @c memset.c:6
646 @deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count})
647
648 Sets the first @var{count} bytes of @var{s} to the constant byte
649 @var{c}, returning a pointer to @var{s}.
650
651 @end deftypefn
652
653 @c mkstemps.c:58
654 @deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len})
655
656 Generate a unique temporary file name from @var{pattern}.
657 @var{pattern} has the form:
658
659 @example
660    @var{path}/ccXXXXXX@var{suffix}
661 @end example
662
663 @var{suffix_len} tells us how long @var{suffix} is (it can be zero
664 length).  The last six characters of @var{pattern} before @var{suffix}
665 must be @samp{XXXXXX}; they are replaced with a string that makes the
666 filename unique.  Returns a file descriptor open on the file for
667 reading and writing.
668
669 @end deftypefn
670
671 @c pexecute.txh:266
672 @deftypefn Extension void pex_free (struct pex_obj @var{obj})
673
674 Clean up and free all data associated with @var{obj}.
675
676 @end deftypefn
677
678 @c pexecute.txh:241
679 @deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector})
680
681 Returns the exit status of all programs run using @var{obj}.
682 @var{count} is the number of results expected.  The results will be
683 placed into @var{vector}.  The results are in the order of the calls
684 to @code{pex_run}.  Returns 0 on error, 1 on success.
685
686 @end deftypefn
687
688 @c pexecute.txh:250
689 @deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector})
690
691 Returns the process execution times of all programs run using
692 @var{obj}.  @var{count} is the number of results expected.  The
693 results will be placed into @var{vector}.  The results are in the
694 order of the calls to @code{pex_run}.  Returns 0 on error, 1 on
695 success.
696
697 @code{struct pex_time} has the following fields of the type
698 @code{unsigned long}: @code{user_seconds},
699 @code{user_microseconds}, @code{system_seconds},
700 @code{system_microseconds}.  On systems which do not support reporting
701 process times, all the fields will be set to @code{0}.
702
703 @end deftypefn
704
705 @c pexecute.txh:2
706 @deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase})
707
708 Prepare to execute one or more programs, with standard output of each
709 program fed to standard input of the next.  This is a system
710 independent interface to execute a pipeline.
711
712 @var{flags} is a bitwise combination of the following:
713
714 @table @code
715
716 @vindex PEX_RECORD_TIMES
717 @item PEX_RECORD_TIMES
718 Record subprocess times if possible.
719
720 @vindex PEX_USE_PIPES
721 @item PEX_USE_PIPES
722 Use pipes for communication between processes, if possible.
723
724 @vindex PEX_SAVE_TEMPS
725 @item PEX_SAVE_TEMPS
726 Don't delete temporary files used for communication between
727 processes.
728
729 @end table
730
731 @var{pname} is the name of program to be executed, used in error
732 messages.  @var{tempbase} is a base name to use for any required
733 temporary files; it may be @code{NULL} to use a randomly chosen name.
734
735 @end deftypefn
736
737 @c pexecute.txh:155
738 @deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{in_name})
739
740 Return a stream for a temporary file to pass to the first program in
741 the pipeline as input.
742
743 The name of the input file is chosen according to the same rules
744 @code{pex_run} uses to choose output file names, based on
745 @var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}.
746
747 Don't call @code{fclose} on the returned stream; the first call to
748 @code{pex_run} closes it automatically.
749
750 If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in
751 binary mode; otherwise, open it in the default mode.  Including
752 @code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix.
753 @end deftypefn
754
755 @c pexecute.txh:172
756 @deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, int @var{binary})
757
758 Return a stream @var{fp} for a pipe connected to the standard input of
759 the first program in the pipeline; @var{fp} is opened for writing.
760 You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call
761 that returned @var{obj}.
762
763 You must close @var{fp} using @code{fclose} yourself when you have
764 finished writing data to the pipeline.
765
766 The file descriptor underlying @var{fp} is marked not to be inherited
767 by child processes.
768
769 On systems that do not support pipes, this function returns
770 @code{NULL}, and sets @code{errno} to @code{EINVAL}.  If you would
771 like to write code that is portable to all systems the @code{pex}
772 functions support, consider using @code{pex_input_file} instead.
773
774 There are two opportunities for deadlock using
775 @code{pex_input_pipe}:
776
777 @itemize @bullet
778 @item
779 Most systems' pipes can buffer only a fixed amount of data; a process
780 that writes to a full pipe blocks.  Thus, if you write to @file{fp}
781 before starting the first process, you run the risk of blocking when
782 there is no child process yet to read the data and allow you to
783 continue.  @code{pex_input_pipe} makes no promises about the
784 size of the pipe's buffer, so if you need to write any data at all
785 before starting the first process in the pipeline, consider using
786 @code{pex_input_file} instead.
787
788 @item
789 Using @code{pex_input_pipe} and @code{pex_read_output} together
790 may also cause deadlock.  If the output pipe fills up, so that each
791 program in the pipeline is waiting for the next to read more data, and
792 you fill the input pipe by writing more data to @var{fp}, then there
793 is no way to make progress: the only process that could read data from
794 the output pipe is you, but you are blocked on the input pipe.
795
796 @end itemize
797
798 @end deftypefn
799
800 @c pexecute.txh:272
801 @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})
802
803 An interface to permit the easy execution of a
804 single program.  The return value and most of the parameters are as
805 for a call to @code{pex_run}.  @var{flags} is restricted to a
806 combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and
807 @code{PEX_BINARY_OUTPUT}.  @var{outname} is interpreted as if
808 @code{PEX_LAST} were set.  On a successful return, @code{*@var{status}} will
809 be set to the exit status of the program.
810
811 @end deftypefn
812
813 @c pexecute.txh:228
814 @deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, int @var{binary})
815
816 Returns a @code{FILE} pointer which may be used to read the standard
817 error of the last program in the pipeline.  When this is used,
818 @code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
819 this is called, @code{pex_run} may no longer be called with the same
820 @var{obj}.  @var{binary} should be non-zero if the file should be
821 opened in binary mode.  Don't call @code{fclose} on the returned file;
822 it will be closed by @code{pex_free}.
823
824 @end deftypefn
825
826 @c pexecute.txh:216
827 @deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary})
828
829 Returns a @code{FILE} pointer which may be used to read the standard
830 output of the last program in the pipeline.  When this is used,
831 @code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
832 this is called, @code{pex_run} may no longer be called with the same
833 @var{obj}.  @var{binary} should be non-zero if the file should be
834 opened in binary mode.  Don't call @code{fclose} on the returned file;
835 it will be closed by @code{pex_free}.
836
837 @end deftypefn
838
839 @c pexecute.txh:33
840 @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})
841
842 Execute one program in a pipeline.  On success this returns
843 @code{NULL}.  On failure it returns an error message, a statically
844 allocated string.
845
846 @var{obj} is returned by a previous call to @code{pex_init}.
847
848 @var{flags} is a bitwise combination of the following:
849
850 @table @code
851
852 @vindex PEX_LAST
853 @item PEX_LAST
854 This must be set on the last program in the pipeline.  In particular,
855 it should be set when executing a single program.  The standard output
856 of the program will be sent to @var{outname}, or, if @var{outname} is
857 @code{NULL}, to the standard output of the calling program.  Do @emph{not}
858 set this bit if you want to call @code{pex_read_output}
859 (described below).  After a call to @code{pex_run} with this bit set,
860 @var{pex_run} may no longer be called with the same @var{obj}.
861
862 @vindex PEX_SEARCH
863 @item PEX_SEARCH
864 Search for the program using the user's executable search path.
865
866 @vindex PEX_SUFFIX
867 @item PEX_SUFFIX
868 @var{outname} is a suffix.  See the description of @var{outname},
869 below.
870
871 @vindex PEX_STDERR_TO_STDOUT
872 @item PEX_STDERR_TO_STDOUT
873 Send the program's standard error to standard output, if possible.
874
875 @vindex PEX_BINARY_INPUT
876 @vindex PEX_BINARY_OUTPUT
877 @vindex PEX_BINARY_ERROR
878 @item PEX_BINARY_INPUT
879 @itemx PEX_BINARY_OUTPUT
880 @itemx PEX_BINARY_ERROR
881 The standard input (output or error) of the program should be read (written) in
882 binary mode rather than text mode.  These flags are ignored on systems
883 which do not distinguish binary mode and text mode, such as Unix.  For
884 proper behavior these flags should match appropriately---a call to
885 @code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
886 call using @code{PEX_BINARY_INPUT}.
887
888 @vindex PEX_STDERR_TO_PIPE
889 @item PEX_STDERR_TO_PIPE
890 Send the program's standard error to a pipe, if possible.  This flag
891 cannot be specified together with @code{PEX_STDERR_TO_STDOUT}.  This
892 flag can be specified only on the last program in pipeline.
893
894 @end table
895
896 @var{executable} is the program to execute.  @var{argv} is the set of
897 arguments to pass to the program; normally @code{@var{argv}[0]} will
898 be a copy of @var{executable}.
899
900 @var{outname} is used to set the name of the file to use for standard
901 output.  There are two cases in which no output file will be used:
902
903 @enumerate
904 @item
905 if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES}
906 was set in the call to @code{pex_init}, and the system supports pipes
907
908 @item
909 if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
910 @code{NULL}
911 @end enumerate
912
913 @noindent
914 Otherwise the code will use a file to hold standard
915 output.  If @code{PEX_LAST} is not set, this file is considered to be
916 a temporary file, and it will be removed when no longer needed, unless
917 @code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}.
918
919 There are two cases to consider when setting the name of the file to
920 hold standard output.
921
922 @enumerate
923 @item
924 @code{PEX_SUFFIX} is set in @var{flags}.  In this case
925 @var{outname} may not be @code{NULL}.  If the @var{tempbase} parameter
926 to @code{pex_init} was not @code{NULL}, then the output file name is
927 the concatenation of @var{tempbase} and @var{outname}.  If
928 @var{tempbase} was @code{NULL}, then the output file name is a random
929 file name ending in @var{outname}.
930
931 @item
932 @code{PEX_SUFFIX} was not set in @var{flags}.  In this
933 case, if @var{outname} is not @code{NULL}, it is used as the output
934 file name.  If @var{outname} is @code{NULL}, and @var{tempbase} was
935 not NULL, the output file name is randomly chosen using
936 @var{tempbase}.  Otherwise the output file name is chosen completely
937 at random.
938 @end enumerate
939
940 @var{errname} is the file name to use for standard error output.  If
941 it is @code{NULL}, standard error is the same as the caller's.
942 Otherwise, standard error is written to the named file.
943
944 On an error return, the code sets @code{*@var{err}} to an @code{errno}
945 value, or to 0 if there is no relevant @code{errno}.
946
947 @end deftypefn
948
949 @c pexecute.txh:142
950 @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})
951
952 Execute one program in a pipeline, permitting the environment for the
953 program to be specified.  Behaviour and parameters not listed below are
954 as for @code{pex_run}.
955
956 @var{env} is the environment for the child process, specified as an array of
957 character pointers.  Each element of the array should point to a string of the
958 form @code{VAR=VALUE}, with the exception of the last element that must be
959 @code{NULL}.
960
961 @end deftypefn
962
963 @c pexecute.txh:284
964 @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})
965
966 This is the old interface to execute one or more programs.  It is
967 still supported for compatibility purposes, but is no longer
968 documented.
969
970 @end deftypefn
971
972 @c strsignal.c:539
973 @deftypefn Supplemental void psignal (int @var{signo}, char *@var{message})
974
975 Print @var{message} to the standard error, followed by a colon,
976 followed by the description of the signal specified by @var{signo},
977 followed by a newline.
978
979 @end deftypefn
980
981 @c putenv.c:21
982 @deftypefn Supplemental int putenv (const char *@var{string})
983
984 Uses @code{setenv} or @code{unsetenv} to put @var{string} into
985 the environment or remove it.  If @var{string} is of the form
986 @samp{name=value} the string is added; if no @samp{=} is present the
987 name is unset/removed.
988
989 @end deftypefn
990
991 @c pexecute.txh:292
992 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
993
994 Another part of the old execution interface.
995
996 @end deftypefn
997
998 @c random.c:39
999 @deftypefn Supplement {long int} random (void)
1000 @deftypefnx Supplement void srandom (unsigned int @var{seed})
1001 @deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n})
1002 @deftypefnx Supplement void* setstate (void *@var{arg_state})
1003
1004 Random number functions.  @code{random} returns a random number in the
1005 range 0 to @code{LONG_MAX}.  @code{srandom} initializes the random
1006 number generator to some starting point determined by @var{seed}
1007 (else, the values returned by @code{random} are always the same for each
1008 run of the program).  @code{initstate} and @code{setstate} allow fine-grained
1009 control over the state of the random number generator.
1010
1011 @end deftypefn
1012
1013 @c concat.c:173
1014 @deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL})
1015
1016 Same as @code{concat}, except that if @var{optr} is not @code{NULL} it
1017 is freed after the string is created.  This is intended to be useful
1018 when you're extending an existing string or building up a string in a
1019 loop:
1020
1021 @example
1022   str = reconcat (str, "pre-", str, NULL);
1023 @end example
1024
1025 @end deftypefn
1026
1027 @c rename.c:6
1028 @deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
1029
1030 Renames a file from @var{old} to @var{new}.  If @var{new} already
1031 exists, it is removed.
1032
1033 @end deftypefn
1034
1035 @c rindex.c:5
1036 @deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
1037
1038 Returns a pointer to the last occurrence of the character @var{c} in
1039 the string @var{s}, or @code{NULL} if not found.  The use of @code{rindex} is
1040 deprecated in new programs in favor of @code{strrchr}.
1041
1042 @end deftypefn
1043
1044 @c setenv.c:22
1045 @deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
1046 @deftypefnx Supplemental void unsetenv (const char *@var{name})
1047
1048 @code{setenv} adds @var{name} to the environment with value
1049 @var{value}.  If the name was already present in the environment,
1050 the new value will be stored only if @var{overwrite} is nonzero.
1051 The companion @code{unsetenv} function removes @var{name} from the
1052 environment.  This implementation is not safe for multithreaded code.
1053
1054 @end deftypefn
1055
1056 @c strsignal.c:348
1057 @deftypefn Extension int signo_max (void)
1058
1059 Returns the maximum signal value for which a corresponding symbolic
1060 name or message is available.  Note that in the case where we use the
1061 @code{sys_siglist} supplied by the system, it is possible for there to
1062 be more symbolic names than messages, or vice versa.  In fact, the
1063 manual page for @code{psignal(3b)} explicitly warns that one should
1064 check the size of the table (@code{NSIG}) before indexing it, since
1065 new signal codes may be added to the system before they are added to
1066 the table.  Thus @code{NSIG} might be smaller than value implied by
1067 the largest signo value defined in @code{<signal.h>}.
1068
1069 We return the maximum value that can be used to obtain a meaningful
1070 symbolic name or message.
1071
1072 @end deftypefn
1073
1074 @c sigsetmask.c:8
1075 @deftypefn Supplemental int sigsetmask (int @var{set})
1076
1077 Sets the signal mask to the one provided in @var{set} and returns
1078 the old mask (which, for libiberty's implementation, will always
1079 be the value @code{1}).
1080
1081 @end deftypefn
1082
1083 @c snprintf.c:28
1084 @deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...)
1085
1086 This function is similar to sprintf, but it will print at most @var{n}
1087 characters.  On error the return value is -1, otherwise it returns the
1088 number of characters that would have been printed had @var{n} been
1089 sufficiently large, regardless of the actual value of @var{n}.  Note
1090 some pre-C99 system libraries do not implement this correctly so users
1091 cannot generally rely on the return value if the system version of
1092 this function is used.
1093
1094 @end deftypefn
1095
1096 @c spaces.c:22
1097 @deftypefn Extension char* spaces (int @var{count})
1098
1099 Returns a pointer to a memory region filled with the specified
1100 number of spaces and null terminated.  The returned pointer is
1101 valid until at least the next call.
1102
1103 @end deftypefn
1104
1105 @c stpcpy.c:23
1106 @deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src})
1107
1108 Copies the string @var{src} into @var{dst}.  Returns a pointer to
1109 @var{dst} + strlen(@var{src}).
1110
1111 @end deftypefn
1112
1113 @c stpncpy.c:23
1114 @deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, size_t @var{len})
1115
1116 Copies the string @var{src} into @var{dst}, copying exactly @var{len}
1117 and padding with zeros if necessary.  If @var{len} < strlen(@var{src})
1118 then return @var{dst} + @var{len}, otherwise returns @var{dst} +
1119 strlen(@var{src}).
1120
1121 @end deftypefn
1122
1123 @c strcasecmp.c:15
1124 @deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
1125
1126 A case-insensitive @code{strcmp}.
1127
1128 @end deftypefn
1129
1130 @c strchr.c:6
1131 @deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
1132
1133 Returns a pointer to the first occurrence of the character @var{c} in
1134 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
1135 null character, the results are undefined.
1136
1137 @end deftypefn
1138
1139 @c strdup.c:3
1140 @deftypefn Supplemental char* strdup (const char *@var{s})
1141
1142 Returns a pointer to a copy of @var{s} in memory obtained from
1143 @code{malloc}, or @code{NULL} if insufficient memory was available.
1144
1145 @end deftypefn
1146
1147 @c strerror.c:670
1148 @deftypefn Replacement {const char*} strerrno (int @var{errnum})
1149
1150 Given an error number returned from a system call (typically returned
1151 in @code{errno}), returns a pointer to a string containing the
1152 symbolic name of that error number, as found in @code{<errno.h>}.
1153
1154 If the supplied error number is within the valid range of indices for
1155 symbolic names, but no name is available for the particular error
1156 number, then returns the string @samp{Error @var{num}}, where @var{num}
1157 is the error number.
1158
1159 If the supplied error number is not within the range of valid
1160 indices, then returns @code{NULL}.
1161
1162 The contents of the location pointed to are only guaranteed to be
1163 valid until the next call to @code{strerrno}.
1164
1165 @end deftypefn
1166
1167 @c strerror.c:603
1168 @deftypefn Supplemental char* strerror (int @var{errnoval})
1169
1170 Maps an @code{errno} number to an error message string, the contents
1171 of which are implementation defined.  On systems which have the
1172 external variables @code{sys_nerr} and @code{sys_errlist}, these
1173 strings will be the same as the ones used by @code{perror}.
1174
1175 If the supplied error number is within the valid range of indices for
1176 the @code{sys_errlist}, but no message is available for the particular
1177 error number, then returns the string @samp{Error @var{num}}, where
1178 @var{num} is the error number.
1179
1180 If the supplied error number is not a valid index into
1181 @code{sys_errlist}, returns @code{NULL}.
1182
1183 The returned string is only guaranteed to be valid only until the
1184 next call to @code{strerror}.
1185
1186 @end deftypefn
1187
1188 @c strncasecmp.c:15
1189 @deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
1190
1191 A case-insensitive @code{strncmp}.
1192
1193 @end deftypefn
1194
1195 @c strncmp.c:6
1196 @deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
1197
1198 Compares the first @var{n} bytes of two strings, returning a value as
1199 @code{strcmp}.
1200
1201 @end deftypefn
1202
1203 @c strndup.c:23
1204 @deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n})
1205
1206 Returns a pointer to a copy of @var{s} with at most @var{n} characters
1207 in memory obtained from @code{malloc}, or @code{NULL} if insufficient
1208 memory was available.  The result is always NUL terminated.
1209
1210 @end deftypefn
1211
1212 @c strrchr.c:6
1213 @deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
1214
1215 Returns a pointer to the last occurrence of the character @var{c} in
1216 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
1217 null character, the results are undefined.
1218
1219 @end deftypefn
1220
1221 @c strsignal.c:383
1222 @deftypefn Supplemental {const char *} strsignal (int @var{signo})
1223
1224 Maps an signal number to an signal message string, the contents of
1225 which are implementation defined.  On systems which have the external
1226 variable @code{sys_siglist}, these strings will be the same as the
1227 ones used by @code{psignal()}.
1228
1229 If the supplied signal number is within the valid range of indices for
1230 the @code{sys_siglist}, but no message is available for the particular
1231 signal number, then returns the string @samp{Signal @var{num}}, where
1232 @var{num} is the signal number.
1233
1234 If the supplied signal number is not a valid index into
1235 @code{sys_siglist}, returns @code{NULL}.
1236
1237 The returned string is only guaranteed to be valid only until the next
1238 call to @code{strsignal}.
1239
1240 @end deftypefn
1241
1242 @c strsignal.c:446
1243 @deftypefn Extension {const char*} strsigno (int @var{signo})
1244
1245 Given an signal number, returns a pointer to a string containing the
1246 symbolic name of that signal number, as found in @code{<signal.h>}.
1247
1248 If the supplied signal number is within the valid range of indices for
1249 symbolic names, but no name is available for the particular signal
1250 number, then returns the string @samp{Signal @var{num}}, where
1251 @var{num} is the signal number.
1252
1253 If the supplied signal number is not within the range of valid
1254 indices, then returns @code{NULL}.
1255
1256 The contents of the location pointed to are only guaranteed to be
1257 valid until the next call to @code{strsigno}.
1258
1259 @end deftypefn
1260
1261 @c strstr.c:6
1262 @deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
1263
1264 This function searches for the substring @var{sub} in the string
1265 @var{string}, not including the terminating null characters.  A pointer
1266 to the first occurrence of @var{sub} is returned, or @code{NULL} if the
1267 substring is absent.  If @var{sub} points to a string with zero
1268 length, the function returns @var{string}.
1269
1270 @end deftypefn
1271
1272 @c strtod.c:27
1273 @deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})
1274
1275 This ISO C function converts the initial portion of @var{string} to a
1276 @code{double}.  If @var{endptr} is not @code{NULL}, a pointer to the
1277 character after the last character used in the conversion is stored in
1278 the location referenced by @var{endptr}.  If no conversion is
1279 performed, zero is returned and the value of @var{string} is stored in
1280 the location referenced by @var{endptr}.
1281
1282 @end deftypefn
1283
1284 @c strerror.c:729
1285 @deftypefn Extension int strtoerrno (const char *@var{name})
1286
1287 Given the symbolic name of a error number (e.g., @code{EACCES}), map it
1288 to an errno value.  If no translation is found, returns 0.
1289
1290 @end deftypefn
1291
1292 @c strtol.c:33
1293 @deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
1294 @deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base})
1295
1296 The @code{strtol} function converts the string in @var{string} to a
1297 long integer value according to the given @var{base}, which must be
1298 between 2 and 36 inclusive, or be the special value 0.  If @var{base}
1299 is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
1300 to indicate bases 8 and 16, respectively, else default to base 10.
1301 When the base is 16 (either explicitly or implicitly), a prefix of
1302 @code{0x} is allowed.  The handling of @var{endptr} is as that of
1303 @code{strtod} above.  The @code{strtoul} function is the same, except
1304 that the converted value is unsigned.
1305
1306 @end deftypefn
1307
1308 @c strsignal.c:500
1309 @deftypefn Extension int strtosigno (const char *@var{name})
1310
1311 Given the symbolic name of a signal, map it to a signal number.  If no
1312 translation is found, returns 0.
1313
1314 @end deftypefn
1315
1316 @c strverscmp.c:25
1317 @deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2})
1318 The @code{strverscmp} function compares the string @var{s1} against
1319 @var{s2}, considering them as holding indices/version numbers.  Return
1320 value follows the same conventions as found in the @code{strverscmp}
1321 function.  In fact, if @var{s1} and @var{s2} contain no digits,
1322 @code{strverscmp} behaves like @code{strcmp}.
1323
1324 Basically, we compare strings normally (character by character), until
1325 we find a digit in each string - then we enter a special comparison
1326 mode, where each sequence of digits is taken as a whole.  If we reach the
1327 end of these two parts without noticing a difference, we return to the
1328 standard comparison mode.  There are two types of numeric parts:
1329 "integral" and "fractional" (those  begin with a '0'). The types
1330 of the numeric parts affect the way we sort them:
1331
1332 @itemize @bullet
1333 @item
1334 integral/integral: we compare values as you would expect.
1335
1336 @item
1337 fractional/integral: the fractional part is less than the integral one.
1338 Again, no surprise.
1339
1340 @item
1341 fractional/fractional: the things become a bit more complex.
1342 If the common prefix contains only leading zeroes, the longest part is less
1343 than the other one; else the comparison behaves normally.
1344 @end itemize
1345
1346 @smallexample
1347 strverscmp ("no digit", "no digit")
1348     @result{} 0    // @r{same behavior as strcmp.}
1349 strverscmp ("item#99", "item#100")
1350     @result{} <0   // @r{same prefix, but 99 < 100.}
1351 strverscmp ("alpha1", "alpha001")
1352     @result{} >0   // @r{fractional part inferior to integral one.}
1353 strverscmp ("part1_f012", "part1_f01")
1354     @result{} >0   // @r{two fractional parts.}
1355 strverscmp ("foo.009", "foo.0")
1356     @result{} <0   // @r{idem, but with leading zeroes only.}
1357 @end smallexample
1358
1359 This function is especially useful when dealing with filename sorting,
1360 because filenames frequently hold indices/version numbers.
1361 @end deftypefun
1362
1363 @c tmpnam.c:3
1364 @deftypefn Supplemental char* tmpnam (char *@var{s})
1365
1366 This function attempts to create a name for a temporary file, which
1367 will be a valid file name yet not exist when @code{tmpnam} checks for
1368 it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
1369 or be @code{NULL}.  Use of this function creates a security risk, and it must
1370 not be used in new projects.  Use @code{mkstemp} instead.
1371
1372 @end deftypefn
1373
1374 @c unlink-if-ordinary.c:27
1375 @deftypefn Supplemental int unlink_if_ordinary (const char*)
1376
1377 Unlinks the named file, unless it is special (e.g. a device file).
1378 Returns 0 when the file was unlinked, a negative value (and errno set) when
1379 there was an error deleting the file, and a positive value if no attempt
1380 was made to unlink the file because it is special.
1381
1382 @end deftypefn
1383
1384 @c fopen_unlocked.c:31
1385 @deftypefn Extension void unlock_std_streams (void)
1386
1387 If the OS supports it, ensure that the standard I/O streams,
1388 @code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any
1389 multi-threaded locking.  Otherwise do nothing.
1390
1391 @end deftypefn
1392
1393 @c fopen_unlocked.c:23
1394 @deftypefn Extension void unlock_stream (FILE * @var{stream})
1395
1396 If the OS supports it, ensure that the supplied stream is setup to
1397 avoid any multi-threaded locking.  Otherwise leave the @code{FILE}
1398 pointer unchanged.  If the @var{stream} is @code{NULL} do nothing.
1399
1400 @end deftypefn
1401
1402 @c vasprintf.c:47
1403 @deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args})
1404
1405 Like @code{vsprintf}, but instead of passing a pointer to a buffer,
1406 you pass a pointer to a pointer.  This function will compute the size
1407 of the buffer needed, allocate memory with @code{malloc}, and store a
1408 pointer to the allocated memory in @code{*@var{resptr}}.  The value
1409 returned is the same as @code{vsprintf} would return.  If memory could
1410 not be allocated, minus one is returned and @code{NULL} is stored in
1411 @code{*@var{resptr}}.
1412
1413 @end deftypefn
1414
1415 @c vfork.c:6
1416 @deftypefn Supplemental int vfork (void)
1417
1418 Emulates @code{vfork} by calling @code{fork} and returning its value.
1419
1420 @end deftypefn
1421
1422 @c vprintf.c:3
1423 @deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
1424 @deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
1425 @deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})
1426
1427 These functions are the same as @code{printf}, @code{fprintf}, and
1428 @code{sprintf}, respectively, except that they are called with a
1429 @code{va_list} instead of a variable number of arguments.  Note that
1430 they do not call @code{va_end}; this is the application's
1431 responsibility.  In @libib{} they are implemented in terms of the
1432 nonstandard but common function @code{_doprnt}.
1433
1434 @end deftypefn
1435
1436 @c vsnprintf.c:28
1437 @deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap})
1438
1439 This function is similar to vsprintf, but it will print at most
1440 @var{n} characters.  On error the return value is -1, otherwise it
1441 returns the number of characters that would have been printed had
1442 @var{n} been sufficiently large, regardless of the actual value of
1443 @var{n}.  Note some pre-C99 system libraries do not implement this
1444 correctly so users cannot generally rely on the return value if the
1445 system version of this function is used.
1446
1447 @end deftypefn
1448
1449 @c waitpid.c:3
1450 @deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
1451
1452 This is a wrapper around the @code{wait} function.  Any ``special''
1453 values of @var{pid} depend on your implementation of @code{wait}, as
1454 does the return value.  The third argument is unused in @libib{}.
1455
1456 @end deftypefn
1457
1458 @c xatexit.c:11
1459 @deftypefun int xatexit (void (*@var{fn}) (void))
1460
1461 Behaves as the standard @code{atexit} function, but with no limit on
1462 the number of registered functions.  Returns 0 on success, or @minus{}1 on
1463 failure.  If you use @code{xatexit} to register functions, you must use
1464 @code{xexit} to terminate your program.
1465
1466 @end deftypefun
1467
1468 @c xmalloc.c:38
1469 @deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize})
1470
1471 Allocate memory without fail, and set it to zero.  This routine functions
1472 like @code{calloc}, but will behave the same as @code{xmalloc} if memory
1473 cannot be found.
1474
1475 @end deftypefn
1476
1477 @c xexit.c:22
1478 @deftypefn Replacement void xexit (int @var{code})
1479
1480 Terminates the program.  If any functions have been registered with
1481 the @code{xatexit} replacement function, they will be called first.
1482 Termination is handled via the system's normal @code{exit} call.
1483
1484 @end deftypefn
1485
1486 @c xmalloc.c:22
1487 @deftypefn Replacement void* xmalloc (size_t)
1488
1489 Allocate memory without fail.  If @code{malloc} fails, this will print
1490 a message to @code{stderr} (using the name set by
1491 @code{xmalloc_set_program_name},
1492 if any) and then call @code{xexit}.  Note that it is therefore safe for
1493 a program to contain @code{#define malloc xmalloc} in its source.
1494
1495 @end deftypefn
1496
1497 @c xmalloc.c:53
1498 @deftypefn Replacement void xmalloc_failed (size_t)
1499
1500 This function is not meant to be called by client code, and is listed
1501 here for completeness only.  If any of the allocation routines fail, this
1502 function will be called to print an error message and terminate execution.
1503
1504 @end deftypefn
1505
1506 @c xmalloc.c:46
1507 @deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
1508
1509 You can use this to set the name of the program used by
1510 @code{xmalloc_failed} when printing a failure message.
1511
1512 @end deftypefn
1513
1514 @c xmemdup.c:7
1515 @deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})
1516
1517 Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
1518 are allocated, then @var{copy_size} bytes from @var{input} are copied into
1519 it, and the new memory is returned.  If fewer bytes are copied than were
1520 allocated, the remaining memory is zeroed.
1521
1522 @end deftypefn
1523
1524 @c xmalloc.c:32
1525 @deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size})
1526 Reallocate memory without fail.  This routine functions like @code{realloc},
1527 but will behave the same as @code{xmalloc} if memory cannot be found.
1528
1529 @end deftypefn
1530
1531 @c xstrdup.c:7
1532 @deftypefn Replacement char* xstrdup (const char *@var{s})
1533
1534 Duplicates a character string without fail, using @code{xmalloc} to
1535 obtain memory.
1536
1537 @end deftypefn
1538
1539 @c xstrerror.c:7
1540 @deftypefn Replacement char* xstrerror (int @var{errnum})
1541
1542 Behaves exactly like the standard @code{strerror} function, but
1543 will never return a @code{NULL} pointer.
1544
1545 @end deftypefn
1546
1547 @c xstrndup.c:23
1548 @deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n})
1549
1550 Returns a pointer to a copy of @var{s} with at most @var{n} characters
1551 without fail, using @code{xmalloc} to obtain memory.  The result is
1552 always NUL terminated.
1553
1554 @end deftypefn
1555
1556