OSDN Git Service

f6d0a23f1e642309d1404f5080e3b29825b3bc6c
[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 run 'make stamp-functions' and gather-docs will build a new copy.
5
6 @c alloca.c:26
7 @deftypefn Replacement void* alloca (size_t @var{size})
8
9 This function allocates memory which will be automatically reclaimed
10 after the procedure exits.  The @libib{} implementation does not free
11 the memory immediately but will do so eventually during subsequent
12 calls to this function.  Memory is allocated using @code{xmalloc} under
13 normal circumstances.
14
15 The header file @file{alloca-conf.h} can be used in conjunction with the
16 GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make
17 available this function.  The @code{AC_FUNC_ALLOCA} test requires that
18 client code use a block of preprocessor code to be safe (see the Autoconf
19 manual for more); this header incorporates that logic and more, including
20 the possibility of a GCC built-in function.
21
22 @end deftypefn
23
24 @c asprintf.c:32
25 @deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...)
26
27 Like @code{sprintf}, but instead of passing a pointer to a buffer, you
28 pass a pointer to a pointer.  This function will compute the size of
29 the buffer needed, allocate memory with @code{malloc}, and store a
30 pointer to the allocated memory in @code{*@var{resptr}}.  The value
31 returned is the same as @code{sprintf} would return.  If memory could
32 not be allocated, minus one is returned and @code{NULL} is stored in
33 @code{*@var{resptr}}.
34
35 @end deftypefn
36
37 @c atexit.c:6
38 @deftypefn Supplemental int atexit (void (*@var{f})())
39
40 Causes function @var{f} to be called at exit.  Returns 0.
41
42 @end deftypefn
43
44 @c basename.c:6
45 @deftypefn Supplemental char* basename (const char *@var{name})
46
47 Returns a pointer to the last component of pathname @var{name}.
48 Behavior is undefined if the pathname ends in a directory separator.
49
50 @end deftypefn
51
52 @c bcmp.c:6
53 @deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count})
54
55 Compares the first @var{count} bytes of two areas of memory.  Returns
56 zero if they are the same, nonzero otherwise.  Returns zero if
57 @var{count} is zero.  A nonzero result only indicates a difference,
58 it does not indicate any sorting order (say, by having a positive
59 result mean @var{x} sorts before @var{y}).
60
61 @end deftypefn
62
63 @c bcopy.c:3
64 @deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length})
65
66 Copies @var{length} bytes from memory region @var{in} to region
67 @var{out}.  The use of @code{bcopy} is deprecated in new programs.
68
69 @end deftypefn
70
71 @c bsearch.c:33
72 @deftypefn Supplemental void* bsearch (const void *@var{key}, @
73   const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, @
74   int (*@var{compar})(const void *, const void *))
75
76 Performs a search over an array of @var{nmemb} elements pointed to by
77 @var{base} for a member that matches the object pointed to by @var{key}.
78 The size of each member is specified by @var{size}.  The array contents
79 should be sorted in ascending order according to the @var{compar}
80 comparison function.  This routine should take two arguments pointing to
81 the @var{key} and to an array member, in that order, and should return an
82 integer less than, equal to, or greater than zero if the @var{key} object
83 is respectively less than, matching, or greater than the array member.
84
85 @end deftypefn
86
87 @c argv.c:142
88 @deftypefn Extension char** buildargv (char *@var{sp})
89
90 Given a pointer to a string, parse the string extracting fields
91 separated by whitespace and optionally enclosed within either single
92 or double quotes (which are stripped off), and build a vector of
93 pointers to copies of the string for each field.  The input string
94 remains unchanged.  The last element of the vector is followed by a
95 @code{NULL} element.
96
97 All of the memory for the pointer array and copies of the string
98 is obtained from @code{malloc}.  All of the memory can be returned to the
99 system with the single function call @code{freeargv}, which takes the
100 returned result of @code{buildargv}, as it's argument.
101
102 Returns a pointer to the argument vector if successful.  Returns
103 @code{NULL} if @var{sp} is @code{NULL} or if there is insufficient
104 memory to complete building the argument vector.
105
106 If the input is a null string (as opposed to a @code{NULL} pointer),
107 then buildarg returns an argument vector that has one arg, a null
108 string.
109
110 @end deftypefn
111
112 @c bzero.c:6
113 @deftypefn Supplemental void bzero (char *@var{mem}, int @var{count})
114
115 Zeros @var{count} bytes starting at @var{mem}.  Use of this function
116 is deprecated in favor of @code{memset}.
117
118 @end deftypefn
119
120 @c calloc.c:6
121 @deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize})
122
123 Uses @code{malloc} to allocate storage for @var{nelem} objects of
124 @var{elsize} bytes each, then zeros the memory.
125
126 @end deftypefn
127
128 @c choose-temp.c:46
129 @deftypefn Extension char* choose_temp_base (void)
130
131 Return a prefix for temporary file names or @code{NULL} if unable to
132 find one.  The current directory is chosen if all else fails so the
133 program is exited if a temporary directory can't be found (@code{mktemp}
134 fails).  The buffer for the result is obtained with @code{xmalloc}.
135
136 This function is provided for backwards compatibility only.  Its use is
137 not recommended.
138
139 @end deftypefn
140
141 @c make-temp-file.c:96
142 @deftypefn Replacement char* choose_tmpdir ()
143
144 Returns a pointer to a directory path suitable for creating temporary
145 files in.
146
147 @end deftypefn
148
149 @c clock.c:27
150 @deftypefn Supplemental long clock (void)
151
152 Returns an approximation of the CPU time used by the process as a
153 @code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the
154 number of seconds used.
155
156 @end deftypefn
157
158 @c concat.c:24
159 @deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @
160   @dots{}, @code{NULL})
161
162 Concatenate zero or more of strings and return the result in freshly
163 @code{xmalloc}ed memory.  Returns @code{NULL} if insufficient memory is
164 available.  The argument list is terminated by the first @code{NULL}
165 pointer encountered.  Pointers to empty strings are ignored.
166
167 @end deftypefn
168
169 @c crc32.c:141
170 @deftypefn Extension {unsigned int} crc32 (const unsigned char *@var{buf}, @
171   int @var{len}, unsigned int @var{init})
172
173 Compute the 32-bit CRC of @var{buf} which has length @var{len}.  The
174 starting value is @var{init}; this may be used to compute the CRC of
175 data split across multiple buffers by passing the return value of each
176 call as the @var{init} parameter of the next.
177
178 This is intended to match the CRC used by the @command{gdb} remote
179 protocol for the @samp{qCRC} command.  In order to get the same
180 results as gdb for a block of data, you must pass the first CRC
181 parameter as @code{0xffffffff}.
182
183 This CRC can be specified as:
184
185   Width  : 32
186   Poly   : 0x04c11db7
187   Init   : parameter, typically 0xffffffff
188   RefIn  : false
189   RefOut : false
190   XorOut : 0
191
192 This differs from the "standard" CRC-32 algorithm in that the values
193 are not reflected, and there is no final XOR value.  These differences
194 make it easy to compose the values of multiple blocks.
195
196 @end deftypefn
197
198 @c argv.c:52
199 @deftypefn Extension char** dupargv (char **@var{vector})
200
201 Duplicate an argument vector.  Simply scans through @var{vector},
202 duplicating each argument until the terminating @code{NULL} is found.
203 Returns a pointer to the argument vector if successful.  Returns
204 @code{NULL} if there is insufficient memory to complete building the
205 argument vector.
206
207 @end deftypefn
208
209 @c strerror.c:567
210 @deftypefn Extension int errno_max (void)
211
212 Returns the maximum @code{errno} value for which a corresponding
213 symbolic name or message is available.  Note that in the case where we
214 use the @code{sys_errlist} supplied by the system, it is possible for
215 there to be more symbolic names than messages, or vice versa.  In
216 fact, the manual page for @code{perror(3C)} explicitly warns that one
217 should check the size of the table (@code{sys_nerr}) before indexing
218 it, since new error codes may be added to the system before they are
219 added to the table.  Thus @code{sys_nerr} might be smaller than value
220 implied by the largest @code{errno} value defined in @code{<errno.h>}.
221
222 We return the maximum value that can be used to obtain a meaningful
223 symbolic name or message.
224
225 @end deftypefn
226
227 @c argv.c:361
228 @deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp})
229
230 The @var{argcp} and @code{argvp} arguments are pointers to the usual
231 @code{argc} and @code{argv} arguments to @code{main}.  This function
232 looks for arguments that begin with the character @samp{@@}.  Any such
233 arguments are interpreted as ``response files''.  The contents of the
234 response file are interpreted as additional command line options.  In
235 particular, the file is separated into whitespace-separated strings;
236 each such string is taken as a command-line option.  The new options
237 are inserted in place of the option naming the response file, and
238 @code{*argcp} and @code{*argvp} will be updated.  If the value of
239 @code{*argvp} is modified by this function, then the new value has
240 been dynamically allocated and can be deallocated by the caller with
241 @code{freeargv}.  However, most callers will simply call
242 @code{expandargv} near the beginning of @code{main} and allow the
243 operating system to free the memory when the program exits.
244
245 @end deftypefn
246
247 @c fdmatch.c:23
248 @deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2})
249
250 Check to see if two open file descriptors refer to the same file.
251 This is useful, for example, when we have an open file descriptor for
252 an unnamed file, and the name of a file that we believe to correspond
253 to that fd.  This can happen when we are exec'd with an already open
254 file (@code{stdout} for example) or from the SVR4 @file{/proc} calls
255 that return open file descriptors for mapped address spaces.  All we
256 have to do is open the file by name and check the two file descriptors
257 for a match, which is done by comparing major and minor device numbers
258 and inode numbers.
259
260 @end deftypefn
261
262 @c fopen_unlocked.c:49
263 @deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, @
264   const char * @var{mode})
265
266 Opens and returns a @code{FILE} pointer via @code{fdopen}.  If the
267 operating system supports it, ensure that the stream is setup to avoid
268 any multi-threaded locking.  Otherwise return the @code{FILE} pointer
269 unchanged.
270
271 @end deftypefn
272
273 @c ffs.c:3
274 @deftypefn Supplemental int ffs (int @var{valu})
275
276 Find the first (least significant) bit set in @var{valu}.  Bits are
277 numbered from right to left, starting with bit 1 (corresponding to the
278 value 1).  If @var{valu} is zero, zero is returned.
279
280 @end deftypefn
281
282 @c filename_cmp.c:32
283 @deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2})
284
285 Return zero if the two file names @var{s1} and @var{s2} are equivalent.
286 If not equivalent, the returned value is similar to what @code{strcmp}
287 would return.  In other words, it returns a negative value if @var{s1}
288 is less than @var{s2}, or a positive value if @var{s2} is greater than
289 @var{s2}.
290
291 This function does not normalize file names.  As a result, this function
292 will treat filenames that are spelled differently as different even in
293 the case when the two filenames point to the same underlying file.
294 However, it does handle the fact that on DOS-like file systems, forward
295 and backward slashes are equal.
296
297 @end deftypefn
298
299 @c fnmatch.txh:1
300 @deftypefn Replacement int fnmatch (const char *@var{pattern}, @
301   const char *@var{string}, int @var{flags})
302
303 Matches @var{string} against @var{pattern}, returning zero if it
304 matches, @code{FNM_NOMATCH} if not.  @var{pattern} may contain the
305 wildcards @code{?} to match any one character, @code{*} to match any
306 zero or more characters, or a set of alternate characters in square
307 brackets, like @samp{[a-gt8]}, which match one character (@code{a}
308 through @code{g}, or @code{t}, or @code{8}, in this example) if that one
309 character is in the set.  A set may be inverted (i.e., match anything
310 except what's in the set) by giving @code{^} or @code{!} as the first
311 character in the set.  To include those characters in the set, list them
312 as anything other than the first character of the set.  To include a
313 dash in the set, list it last in the set.  A backslash character makes
314 the following character not special, so for example you could match
315 against a literal asterisk with @samp{\*}.  To match a literal
316 backslash, use @samp{\\}.
317
318 @code{flags} controls various aspects of the matching process, and is a
319 boolean OR of zero or more of the following values (defined in
320 @code{<fnmatch.h>}):
321
322 @table @code
323
324 @item FNM_PATHNAME
325 @itemx FNM_FILE_NAME
326 @var{string} is assumed to be a path name.  No wildcard will ever match
327 @code{/}.
328
329 @item FNM_NOESCAPE
330 Do not interpret backslashes as quoting the following special character.
331
332 @item FNM_PERIOD
333 A leading period (at the beginning of @var{string}, or if
334 @code{FNM_PATHNAME} after a slash) is not matched by @code{*} or
335 @code{?} but must be matched explicitly.
336
337 @item FNM_LEADING_DIR
338 Means that @var{string} also matches @var{pattern} if some initial part
339 of @var{string} matches, and is followed by @code{/} and zero or more
340 characters.  For example, @samp{foo*} would match either @samp{foobar}
341 or @samp{foobar/grill}.
342
343 @item FNM_CASEFOLD
344 Ignores case when performing the comparison.
345
346 @end table
347
348 @end deftypefn
349
350 @c fopen_unlocked.c:39
351 @deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, @
352   const char * @var{mode})
353
354 Opens and returns a @code{FILE} pointer via @code{fopen}.  If the
355 operating system supports it, ensure that the stream is setup to avoid
356 any multi-threaded locking.  Otherwise return the @code{FILE} pointer
357 unchanged.
358
359 @end deftypefn
360
361 @c argv.c:97
362 @deftypefn Extension void freeargv (char **@var{vector})
363
364 Free an argument vector that was built using @code{buildargv}.  Simply
365 scans through @var{vector}, freeing the memory for each argument until
366 the terminating @code{NULL} is found, and then frees @var{vector}
367 itself.
368
369 @end deftypefn
370
371 @c fopen_unlocked.c:59
372 @deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, @
373   const char * @var{mode}, FILE * @var{stream})
374
375 Opens and returns a @code{FILE} pointer via @code{freopen}.  If the
376 operating system supports it, ensure that the stream is setup to avoid
377 any multi-threaded locking.  Otherwise return the @code{FILE} pointer
378 unchanged.
379
380 @end deftypefn
381
382 @c getruntime.c:82
383 @deftypefn Replacement long get_run_time (void)
384
385 Returns the time used so far, in microseconds.  If possible, this is
386 the time used by this process, else it is the elapsed time since the
387 process started.
388
389 @end deftypefn
390
391 @c getcwd.c:6
392 @deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len})
393
394 Copy the absolute pathname for the current working directory into
395 @var{pathname}, which is assumed to point to a buffer of at least
396 @var{len} bytes, and return a pointer to the buffer.  If the current
397 directory's path doesn't fit in @var{len} characters, the result is
398 @code{NULL} and @code{errno} is set.  If @var{pathname} is a null pointer,
399 @code{getcwd} will obtain @var{len} bytes of space using
400 @code{malloc}.
401
402 @end deftypefn
403
404 @c getpagesize.c:5
405 @deftypefn Supplemental int getpagesize (void)
406
407 Returns the number of bytes in a page of memory.  This is the
408 granularity of many of the system memory management routines.  No
409 guarantee is made as to whether or not it is the same as the basic
410 memory management hardware page size.
411
412 @end deftypefn
413
414 @c getpwd.c:5
415 @deftypefn Supplemental char* getpwd (void)
416
417 Returns the current working directory.  This implementation caches the
418 result on the assumption that the process will not call @code{chdir}
419 between calls to @code{getpwd}.
420
421 @end deftypefn
422
423 @c gettimeofday.c:12
424 @deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz})
425
426 Writes the current time to @var{tp}.  This implementation requires
427 that @var{tz} be NULL.  Returns 0 on success, -1 on failure.
428
429 @end deftypefn
430
431 @c hex.c:33
432 @deftypefn Extension void hex_init (void)
433
434 Initializes the array mapping the current character set to
435 corresponding hex values.  This function must be called before any
436 call to @code{hex_p} or @code{hex_value}.  If you fail to call it, a
437 default ASCII-based table will normally be used on ASCII systems.
438
439 @end deftypefn
440
441 @c hex.c:42
442 @deftypefn Extension int hex_p (int @var{c})
443
444 Evaluates to non-zero if the given character is a valid hex character,
445 or zero if it is not.  Note that the value you pass will be cast to
446 @code{unsigned char} within the macro.
447
448 @end deftypefn
449
450 @c hex.c:50
451 @deftypefn Extension {unsigned int} hex_value (int @var{c})
452
453 Returns the numeric equivalent of the given character when interpreted
454 as a hexadecimal digit.  The result is undefined if you pass an
455 invalid hex digit.  Note that the value you pass will be cast to
456 @code{unsigned char} within the macro.
457
458 The @code{hex_value} macro returns @code{unsigned int}, rather than
459 signed @code{int}, to make it easier to use in parsing addresses from
460 hex dump files: a signed @code{int} would be sign-extended when
461 converted to a wider unsigned type --- like @code{bfd_vma}, on some
462 systems.
463
464 @end deftypefn
465
466 @c safe-ctype.c:25
467 @defvr Extension HOST_CHARSET
468 This macro indicates the basic character set and encoding used by the
469 host: more precisely, the encoding used for character constants in
470 preprocessor @samp{#if} statements (the C "execution character set").
471 It is defined by @file{safe-ctype.h}, and will be an integer constant
472 with one of the following values:
473
474 @ftable @code
475 @item HOST_CHARSET_UNKNOWN
476 The host character set is unknown - that is, not one of the next two
477 possibilities.
478
479 @item HOST_CHARSET_ASCII
480 The host character set is ASCII.
481
482 @item HOST_CHARSET_EBCDIC
483 The host character set is some variant of EBCDIC.  (Only one of the
484 nineteen EBCDIC varying characters is tested; exercise caution.)
485 @end ftable
486 @end defvr
487
488 @c hashtab.c:336
489 @deftypefn Supplemental htab_t htab_create_typed_alloc (size_t @var{size}, @
490 htab_hash @var{hash_f}, htab_eq @var{eq_f}, htab_del @var{del_f}, @
491 htab_alloc @var{alloc_tab_f}, htab_alloc @var{alloc_f}, @
492 htab_free @var{free_f})
493
494 This function creates a hash table that uses two different allocators
495 @var{alloc_tab_f} and @var{alloc_f} to use for allocating the table itself
496 and its entries respectively.  This is useful when variables of different
497 types need to be allocated with different allocators.
498
499 The created hash table is slightly larger than @var{size} and it is
500 initially empty (all the hash table entries are @code{HTAB_EMPTY_ENTRY}).
501 The function returns the created hash table, or @code{NULL} if memory
502 allocation fails.
503
504 @end deftypefn
505
506 @c index.c:5
507 @deftypefn Supplemental char* index (char *@var{s}, int @var{c})
508
509 Returns a pointer to the first occurrence of the character @var{c} in
510 the string @var{s}, or @code{NULL} if not found.  The use of @code{index} is
511 deprecated in new programs in favor of @code{strchr}.
512
513 @end deftypefn
514
515 @c insque.c:6
516 @deftypefn Supplemental void insque (struct qelem *@var{elem}, @
517   struct qelem *@var{pred})
518 @deftypefnx Supplemental void remque (struct qelem *@var{elem})
519
520 Routines to manipulate queues built from doubly linked lists.  The
521 @code{insque} routine inserts @var{elem} in the queue immediately
522 after @var{pred}.  The @code{remque} routine removes @var{elem} from
523 its containing queue.  These routines expect to be passed pointers to
524 structures which have as their first members a forward pointer and a
525 back pointer, like this prototype (although no prototype is provided):
526
527 @example
528 struct qelem @{
529   struct qelem *q_forw;
530   struct qelem *q_back;
531   char q_data[];
532 @};
533 @end example
534
535 @end deftypefn
536
537 @c safe-ctype.c:46
538 @deffn  Extension ISALPHA  (@var{c})
539 @deffnx Extension ISALNUM  (@var{c})
540 @deffnx Extension ISBLANK  (@var{c})
541 @deffnx Extension ISCNTRL  (@var{c})
542 @deffnx Extension ISDIGIT  (@var{c})
543 @deffnx Extension ISGRAPH  (@var{c})
544 @deffnx Extension ISLOWER  (@var{c})
545 @deffnx Extension ISPRINT  (@var{c})
546 @deffnx Extension ISPUNCT  (@var{c})
547 @deffnx Extension ISSPACE  (@var{c})
548 @deffnx Extension ISUPPER  (@var{c})
549 @deffnx Extension ISXDIGIT (@var{c})
550
551 These twelve macros are defined by @file{safe-ctype.h}.  Each has the
552 same meaning as the corresponding macro (with name in lowercase)
553 defined by the standard header @file{ctype.h}.  For example,
554 @code{ISALPHA} returns true for alphabetic characters and false for
555 others.  However, there are two differences between these macros and
556 those provided by @file{ctype.h}:
557
558 @itemize @bullet
559 @item These macros are guaranteed to have well-defined behavior for all 
560 values representable by @code{signed char} and @code{unsigned char}, and
561 for @code{EOF}.
562
563 @item These macros ignore the current locale; they are true for these
564 fixed sets of characters:
565 @multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada}
566 @item @code{ALPHA}  @tab @kbd{A-Za-z}
567 @item @code{ALNUM}  @tab @kbd{A-Za-z0-9}
568 @item @code{BLANK}  @tab @kbd{space tab}
569 @item @code{CNTRL}  @tab @code{!PRINT}
570 @item @code{DIGIT}  @tab @kbd{0-9}
571 @item @code{GRAPH}  @tab @code{ALNUM || PUNCT}
572 @item @code{LOWER}  @tab @kbd{a-z}
573 @item @code{PRINT}  @tab @code{GRAPH ||} @kbd{space}
574 @item @code{PUNCT}  @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?}
575 @item @code{SPACE}  @tab @kbd{space tab \n \r \f \v}
576 @item @code{UPPER}  @tab @kbd{A-Z}
577 @item @code{XDIGIT} @tab @kbd{0-9A-Fa-f}
578 @end multitable
579
580 Note that, if the host character set is ASCII or a superset thereof,
581 all these macros will return false for all values of @code{char} outside
582 the range of 7-bit ASCII.  In particular, both ISPRINT and ISCNTRL return
583 false for characters with numeric values from 128 to 255.
584 @end itemize
585 @end deffn
586
587 @c safe-ctype.c:95
588 @deffn  Extension ISIDNUM         (@var{c})
589 @deffnx Extension ISIDST          (@var{c})
590 @deffnx Extension IS_VSPACE       (@var{c})
591 @deffnx Extension IS_NVSPACE      (@var{c})
592 @deffnx Extension IS_SPACE_OR_NUL (@var{c})
593 @deffnx Extension IS_ISOBASIC     (@var{c})
594 These six macros are defined by @file{safe-ctype.h} and provide
595 additional character classes which are useful when doing lexical
596 analysis of C or similar languages.  They are true for the following
597 sets of characters:
598
599 @multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada}
600 @item @code{IDNUM}        @tab @kbd{A-Za-z0-9_}
601 @item @code{IDST}         @tab @kbd{A-Za-z_}
602 @item @code{VSPACE}       @tab @kbd{\r \n}
603 @item @code{NVSPACE}      @tab @kbd{space tab \f \v \0}
604 @item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE}
605 @item @code{ISOBASIC}     @tab @code{VSPACE || NVSPACE || PRINT}
606 @end multitable
607 @end deffn
608
609 @c lbasename.c:23
610 @deftypefn Replacement {const char*} lbasename (const char *@var{name})
611
612 Given a pointer to a string containing a typical pathname
613 (@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the
614 last component of the pathname (@samp{ls.c} in this case).  The
615 returned pointer is guaranteed to lie within the original
616 string.  This latter fact is not true of many vendor C
617 libraries, which return special strings or modify the passed
618 strings for particular input.
619
620 In particular, the empty string returns the same empty string,
621 and a path ending in @code{/} returns the empty string after it.
622
623 @end deftypefn
624
625 @c lrealpath.c:25
626 @deftypefn Replacement {const char*} lrealpath (const char *@var{name})
627
628 Given a pointer to a string containing a pathname, returns a canonical
629 version of the filename.  Symlinks will be resolved, and ``.'' and ``..''
630 components will be simplified.  The returned value will be allocated using
631 @code{malloc}, or @code{NULL} will be returned on a memory allocation error.
632
633 @end deftypefn
634
635 @c make-relative-prefix.c:24
636 @deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, @
637   const char *@var{bin_prefix}, const char *@var{prefix})
638
639 Given three paths @var{progname}, @var{bin_prefix}, @var{prefix},
640 return the path that is in the same position relative to
641 @var{progname}'s directory as @var{prefix} is relative to
642 @var{bin_prefix}.  That is, a string starting with the directory
643 portion of @var{progname}, followed by a relative pathname of the
644 difference between @var{bin_prefix} and @var{prefix}.
645
646 If @var{progname} does not contain any directory separators,
647 @code{make_relative_prefix} will search @env{PATH} to find a program
648 named @var{progname}.  Also, if @var{progname} is a symbolic link,
649 the symbolic link will be resolved.
650
651 For example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta},
652 @var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is
653 @code{/red/green/blue/gcc}, then this function will return
654 @code{/red/green/blue/../../omega/}.
655
656 The return value is normally allocated via @code{malloc}.  If no
657 relative prefix can be found, return @code{NULL}.
658
659 @end deftypefn
660
661 @c make-temp-file.c:174
662 @deftypefn Replacement char* make_temp_file (const char *@var{suffix})
663
664 Return a temporary file name (as a string) or @code{NULL} if unable to
665 create one.  @var{suffix} is a suffix to append to the file name.  The
666 string is @code{malloc}ed, and the temporary file has been created.
667
668 @end deftypefn
669
670 @c memchr.c:3
671 @deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, @
672   size_t @var{n})
673
674 This function searches memory starting at @code{*@var{s}} for the
675 character @var{c}.  The search only ends with the first occurrence of
676 @var{c}, or after @var{length} characters; in particular, a null
677 character does not terminate the search.  If the character @var{c} is
678 found within @var{length} characters of @code{*@var{s}}, a pointer
679 to the character is returned.  If @var{c} is not found, then @code{NULL} is
680 returned.
681
682 @end deftypefn
683
684 @c memcmp.c:6
685 @deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, @
686   size_t @var{count})
687
688 Compares the first @var{count} bytes of two areas of memory.  Returns
689 zero if they are the same, a value less than zero if @var{x} is
690 lexically less than @var{y}, or a value greater than zero if @var{x}
691 is lexically greater than @var{y}.  Note that lexical order is determined
692 as if comparing unsigned char arrays.
693
694 @end deftypefn
695
696 @c memcpy.c:6
697 @deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, @
698   size_t @var{length})
699
700 Copies @var{length} bytes from memory region @var{in} to region
701 @var{out}.  Returns a pointer to @var{out}.
702
703 @end deftypefn
704
705 @c memmem.c:20
706 @deftypefn Supplemental void* memmem (const void *@var{haystack}, @
707   size_t @var{haystack_len} const void *@var{needle}, size_t @var{needle_len})
708
709 Returns a pointer to the first occurrence of @var{needle} (length
710 @var{needle_len}) in @var{haystack} (length @var{haystack_len}).
711 Returns @code{NULL} if not found.
712
713 @end deftypefn
714
715 @c memmove.c:6
716 @deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, @
717   size_t @var{count})
718
719 Copies @var{count} bytes from memory area @var{from} to memory area
720 @var{to}, returning a pointer to @var{to}.
721
722 @end deftypefn
723
724 @c mempcpy.c:23
725 @deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, @
726   size_t @var{length})
727
728 Copies @var{length} bytes from memory region @var{in} to region
729 @var{out}.  Returns a pointer to @var{out} + @var{length}.
730
731 @end deftypefn
732
733 @c memset.c:6
734 @deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, @
735   size_t @var{count})
736
737 Sets the first @var{count} bytes of @var{s} to the constant byte
738 @var{c}, returning a pointer to @var{s}.
739
740 @end deftypefn
741
742 @c mkstemps.c:58
743 @deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len})
744
745 Generate a unique temporary file name from @var{pattern}.
746 @var{pattern} has the form:
747
748 @example
749    @var{path}/ccXXXXXX@var{suffix}
750 @end example
751
752 @var{suffix_len} tells us how long @var{suffix} is (it can be zero
753 length).  The last six characters of @var{pattern} before @var{suffix}
754 must be @samp{XXXXXX}; they are replaced with a string that makes the
755 filename unique.  Returns a file descriptor open on the file for
756 reading and writing.
757
758 @end deftypefn
759
760 @c pexecute.txh:278
761 @deftypefn Extension void pex_free (struct pex_obj @var{obj})
762
763 Clean up and free all data associated with @var{obj}.  If you have not
764 yet called @code{pex_get_times} or @code{pex_get_status}, this will
765 try to kill the subprocesses.
766
767 @end deftypefn
768
769 @c pexecute.txh:251
770 @deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, @
771   int @var{count}, int *@var{vector})
772
773 Returns the exit status of all programs run using @var{obj}.
774 @var{count} is the number of results expected.  The results will be
775 placed into @var{vector}.  The results are in the order of the calls
776 to @code{pex_run}.  Returns 0 on error, 1 on success.
777
778 @end deftypefn
779
780 @c pexecute.txh:261
781 @deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, @
782   int @var{count}, struct pex_time *@var{vector})
783
784 Returns the process execution times of all programs run using
785 @var{obj}.  @var{count} is the number of results expected.  The
786 results will be placed into @var{vector}.  The results are in the
787 order of the calls to @code{pex_run}.  Returns 0 on error, 1 on
788 success.
789
790 @code{struct pex_time} has the following fields of the type
791 @code{unsigned long}: @code{user_seconds},
792 @code{user_microseconds}, @code{system_seconds},
793 @code{system_microseconds}.  On systems which do not support reporting
794 process times, all the fields will be set to @code{0}.
795
796 @end deftypefn
797
798 @c pexecute.txh:2
799 @deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, @
800   const char *@var{pname}, const char *@var{tempbase})
801
802 Prepare to execute one or more programs, with standard output of each
803 program fed to standard input of the next.  This is a system
804 independent interface to execute a pipeline.
805
806 @var{flags} is a bitwise combination of the following:
807
808 @table @code
809
810 @vindex PEX_RECORD_TIMES
811 @item PEX_RECORD_TIMES
812 Record subprocess times if possible.
813
814 @vindex PEX_USE_PIPES
815 @item PEX_USE_PIPES
816 Use pipes for communication between processes, if possible.
817
818 @vindex PEX_SAVE_TEMPS
819 @item PEX_SAVE_TEMPS
820 Don't delete temporary files used for communication between
821 processes.
822
823 @end table
824
825 @var{pname} is the name of program to be executed, used in error
826 messages.  @var{tempbase} is a base name to use for any required
827 temporary files; it may be @code{NULL} to use a randomly chosen name.
828
829 @end deftypefn
830
831 @c pexecute.txh:161
832 @deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, @
833   int @var{flags}, const char *@var{in_name})
834
835 Return a stream for a temporary file to pass to the first program in
836 the pipeline as input.
837
838 The name of the input file is chosen according to the same rules
839 @code{pex_run} uses to choose output file names, based on
840 @var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}.
841
842 Don't call @code{fclose} on the returned stream; the first call to
843 @code{pex_run} closes it automatically.
844
845 If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in
846 binary mode; otherwise, open it in the default mode.  Including
847 @code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix.
848 @end deftypefn
849
850 @c pexecute.txh:179
851 @deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, @
852   int @var{binary})
853
854 Return a stream @var{fp} for a pipe connected to the standard input of
855 the first program in the pipeline; @var{fp} is opened for writing.
856 You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call
857 that returned @var{obj}.
858
859 You must close @var{fp} using @code{fclose} yourself when you have
860 finished writing data to the pipeline.
861
862 The file descriptor underlying @var{fp} is marked not to be inherited
863 by child processes.
864
865 On systems that do not support pipes, this function returns
866 @code{NULL}, and sets @code{errno} to @code{EINVAL}.  If you would
867 like to write code that is portable to all systems the @code{pex}
868 functions support, consider using @code{pex_input_file} instead.
869
870 There are two opportunities for deadlock using
871 @code{pex_input_pipe}:
872
873 @itemize @bullet
874 @item
875 Most systems' pipes can buffer only a fixed amount of data; a process
876 that writes to a full pipe blocks.  Thus, if you write to @file{fp}
877 before starting the first process, you run the risk of blocking when
878 there is no child process yet to read the data and allow you to
879 continue.  @code{pex_input_pipe} makes no promises about the
880 size of the pipe's buffer, so if you need to write any data at all
881 before starting the first process in the pipeline, consider using
882 @code{pex_input_file} instead.
883
884 @item
885 Using @code{pex_input_pipe} and @code{pex_read_output} together
886 may also cause deadlock.  If the output pipe fills up, so that each
887 program in the pipeline is waiting for the next to read more data, and
888 you fill the input pipe by writing more data to @var{fp}, then there
889 is no way to make progress: the only process that could read data from
890 the output pipe is you, but you are blocked on the input pipe.
891
892 @end itemize
893
894 @end deftypefn
895
896 @c pexecute.txh:286
897 @deftypefn Extension {const char *} pex_one (int @var{flags}, @
898   const char *@var{executable}, char * const *@var{argv}, @
899   const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, @
900   int *@var{status}, int *@var{err})
901
902 An interface to permit the easy execution of a
903 single program.  The return value and most of the parameters are as
904 for a call to @code{pex_run}.  @var{flags} is restricted to a
905 combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and
906 @code{PEX_BINARY_OUTPUT}.  @var{outname} is interpreted as if
907 @code{PEX_LAST} were set.  On a successful return, @code{*@var{status}} will
908 be set to the exit status of the program.
909
910 @end deftypefn
911
912 @c pexecute.txh:237
913 @deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, @
914   int @var{binary})
915
916 Returns a @code{FILE} pointer which may be used to read the standard
917 error of the last program in the pipeline.  When this is used,
918 @code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
919 this is called, @code{pex_run} may no longer be called with the same
920 @var{obj}.  @var{binary} should be non-zero if the file should be
921 opened in binary mode.  Don't call @code{fclose} on the returned file;
922 it will be closed by @code{pex_free}.
923
924 @end deftypefn
925
926 @c pexecute.txh:224
927 @deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, @
928   int @var{binary})
929
930 Returns a @code{FILE} pointer which may be used to read the standard
931 output of the last program in the pipeline.  When this is used,
932 @code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
933 this is called, @code{pex_run} may no longer be called with the same
934 @var{obj}.  @var{binary} should be non-zero if the file should be
935 opened in binary mode.  Don't call @code{fclose} on the returned file;
936 it will be closed by @code{pex_free}.
937
938 @end deftypefn
939
940 @c pexecute.txh:34
941 @deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, @
942   int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @
943   const char *@var{outname}, const char *@var{errname}, int *@var{err})
944
945 Execute one program in a pipeline.  On success this returns
946 @code{NULL}.  On failure it returns an error message, a statically
947 allocated string.
948
949 @var{obj} is returned by a previous call to @code{pex_init}.
950
951 @var{flags} is a bitwise combination of the following:
952
953 @table @code
954
955 @vindex PEX_LAST
956 @item PEX_LAST
957 This must be set on the last program in the pipeline.  In particular,
958 it should be set when executing a single program.  The standard output
959 of the program will be sent to @var{outname}, or, if @var{outname} is
960 @code{NULL}, to the standard output of the calling program.  Do @emph{not}
961 set this bit if you want to call @code{pex_read_output}
962 (described below).  After a call to @code{pex_run} with this bit set,
963 @var{pex_run} may no longer be called with the same @var{obj}.
964
965 @vindex PEX_SEARCH
966 @item PEX_SEARCH
967 Search for the program using the user's executable search path.
968
969 @vindex PEX_SUFFIX
970 @item PEX_SUFFIX
971 @var{outname} is a suffix.  See the description of @var{outname},
972 below.
973
974 @vindex PEX_STDERR_TO_STDOUT
975 @item PEX_STDERR_TO_STDOUT
976 Send the program's standard error to standard output, if possible.
977
978 @vindex PEX_BINARY_INPUT
979 @vindex PEX_BINARY_OUTPUT
980 @vindex PEX_BINARY_ERROR
981 @item PEX_BINARY_INPUT
982 @itemx PEX_BINARY_OUTPUT
983 @itemx PEX_BINARY_ERROR
984 The standard input (output or error) of the program should be read (written) in
985 binary mode rather than text mode.  These flags are ignored on systems
986 which do not distinguish binary mode and text mode, such as Unix.  For
987 proper behavior these flags should match appropriately---a call to
988 @code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
989 call using @code{PEX_BINARY_INPUT}.
990
991 @vindex PEX_STDERR_TO_PIPE
992 @item PEX_STDERR_TO_PIPE
993 Send the program's standard error to a pipe, if possible.  This flag
994 cannot be specified together with @code{PEX_STDERR_TO_STDOUT}.  This
995 flag can be specified only on the last program in pipeline.
996
997 @end table
998
999 @var{executable} is the program to execute.  @var{argv} is the set of
1000 arguments to pass to the program; normally @code{@var{argv}[0]} will
1001 be a copy of @var{executable}.
1002
1003 @var{outname} is used to set the name of the file to use for standard
1004 output.  There are two cases in which no output file will be used:
1005
1006 @enumerate
1007 @item
1008 if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES}
1009 was set in the call to @code{pex_init}, and the system supports pipes
1010
1011 @item
1012 if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
1013 @code{NULL}
1014 @end enumerate
1015
1016 @noindent
1017 Otherwise the code will use a file to hold standard
1018 output.  If @code{PEX_LAST} is not set, this file is considered to be
1019 a temporary file, and it will be removed when no longer needed, unless
1020 @code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}.
1021
1022 There are two cases to consider when setting the name of the file to
1023 hold standard output.
1024
1025 @enumerate
1026 @item
1027 @code{PEX_SUFFIX} is set in @var{flags}.  In this case
1028 @var{outname} may not be @code{NULL}.  If the @var{tempbase} parameter
1029 to @code{pex_init} was not @code{NULL}, then the output file name is
1030 the concatenation of @var{tempbase} and @var{outname}.  If
1031 @var{tempbase} was @code{NULL}, then the output file name is a random
1032 file name ending in @var{outname}.
1033
1034 @item
1035 @code{PEX_SUFFIX} was not set in @var{flags}.  In this
1036 case, if @var{outname} is not @code{NULL}, it is used as the output
1037 file name.  If @var{outname} is @code{NULL}, and @var{tempbase} was
1038 not NULL, the output file name is randomly chosen using
1039 @var{tempbase}.  Otherwise the output file name is chosen completely
1040 at random.
1041 @end enumerate
1042
1043 @var{errname} is the file name to use for standard error output.  If
1044 it is @code{NULL}, standard error is the same as the caller's.
1045 Otherwise, standard error is written to the named file.
1046
1047 On an error return, the code sets @code{*@var{err}} to an @code{errno}
1048 value, or to 0 if there is no relevant @code{errno}.
1049
1050 @end deftypefn
1051
1052 @c pexecute.txh:145
1053 @deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, @
1054   int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @
1055   char * const *@var{env}, int @var{env_size}, const char *@var{outname}, @
1056   const char *@var{errname}, int *@var{err})
1057
1058 Execute one program in a pipeline, permitting the environment for the
1059 program to be specified.  Behaviour and parameters not listed below are
1060 as for @code{pex_run}.
1061
1062 @var{env} is the environment for the child process, specified as an array of
1063 character pointers.  Each element of the array should point to a string of the
1064 form @code{VAR=VALUE}, with the exception of the last element that must be
1065 @code{NULL}.
1066
1067 @end deftypefn
1068
1069 @c pexecute.txh:301
1070 @deftypefn Extension int pexecute (const char *@var{program}, @
1071   char * const *@var{argv}, const char *@var{this_pname}, @
1072   const char *@var{temp_base}, char **@var{errmsg_fmt}, @
1073   char **@var{errmsg_arg}, int @var{flags})
1074
1075 This is the old interface to execute one or more programs.  It is
1076 still supported for compatibility purposes, but is no longer
1077 documented.
1078
1079 @end deftypefn
1080
1081 @c strsignal.c:541
1082 @deftypefn Supplemental void psignal (int @var{signo}, char *@var{message})
1083
1084 Print @var{message} to the standard error, followed by a colon,
1085 followed by the description of the signal specified by @var{signo},
1086 followed by a newline.
1087
1088 @end deftypefn
1089
1090 @c putenv.c:21
1091 @deftypefn Supplemental int putenv (const char *@var{string})
1092
1093 Uses @code{setenv} or @code{unsetenv} to put @var{string} into
1094 the environment or remove it.  If @var{string} is of the form
1095 @samp{name=value} the string is added; if no @samp{=} is present the
1096 name is unset/removed.
1097
1098 @end deftypefn
1099
1100 @c pexecute.txh:312
1101 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
1102
1103 Another part of the old execution interface.
1104
1105 @end deftypefn
1106
1107 @c random.c:39
1108 @deftypefn Supplement {long int} random (void)
1109 @deftypefnx Supplement void srandom (unsigned int @var{seed})
1110 @deftypefnx Supplement void* initstate (unsigned int @var{seed}, @
1111   void *@var{arg_state}, unsigned long @var{n})
1112 @deftypefnx Supplement void* setstate (void *@var{arg_state})
1113
1114 Random number functions.  @code{random} returns a random number in the
1115 range 0 to @code{LONG_MAX}.  @code{srandom} initializes the random
1116 number generator to some starting point determined by @var{seed}
1117 (else, the values returned by @code{random} are always the same for each
1118 run of the program).  @code{initstate} and @code{setstate} allow fine-grained
1119 control over the state of the random number generator.
1120
1121 @end deftypefn
1122
1123 @c concat.c:174
1124 @deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @
1125   @dots{}, @code{NULL})
1126
1127 Same as @code{concat}, except that if @var{optr} is not @code{NULL} it
1128 is freed after the string is created.  This is intended to be useful
1129 when you're extending an existing string or building up a string in a
1130 loop:
1131
1132 @example
1133   str = reconcat (str, "pre-", str, NULL);
1134 @end example
1135
1136 @end deftypefn
1137
1138 @c rename.c:6
1139 @deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
1140
1141 Renames a file from @var{old} to @var{new}.  If @var{new} already
1142 exists, it is removed.
1143
1144 @end deftypefn
1145
1146 @c rindex.c:5
1147 @deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
1148
1149 Returns a pointer to the last occurrence of the character @var{c} in
1150 the string @var{s}, or @code{NULL} if not found.  The use of @code{rindex} is
1151 deprecated in new programs in favor of @code{strrchr}.
1152
1153 @end deftypefn
1154
1155 @c setenv.c:23
1156 @deftypefn Supplemental int setenv (const char *@var{name}, @
1157   const char *@var{value}, int @var{overwrite})
1158 @deftypefnx Supplemental void unsetenv (const char *@var{name})
1159
1160 @code{setenv} adds @var{name} to the environment with value
1161 @var{value}.  If the name was already present in the environment,
1162 the new value will be stored only if @var{overwrite} is nonzero.
1163 The companion @code{unsetenv} function removes @var{name} from the
1164 environment.  This implementation is not safe for multithreaded code.
1165
1166 @end deftypefn
1167
1168 @c setproctitle.c:31
1169 @deftypefn Supplemental void setproctitle (const char *@var{fmt}, ...)
1170
1171 Set the title of a process to @var{fmt}. va args not supported for now,
1172 but defined for compatibility with BSD. 
1173
1174 @end deftypefn
1175
1176 @c strsignal.c:348
1177 @deftypefn Extension int signo_max (void)
1178
1179 Returns the maximum signal value for which a corresponding symbolic
1180 name or message is available.  Note that in the case where we use the
1181 @code{sys_siglist} supplied by the system, it is possible for there to
1182 be more symbolic names than messages, or vice versa.  In fact, the
1183 manual page for @code{psignal(3b)} explicitly warns that one should
1184 check the size of the table (@code{NSIG}) before indexing it, since
1185 new signal codes may be added to the system before they are added to
1186 the table.  Thus @code{NSIG} might be smaller than value implied by
1187 the largest signo value defined in @code{<signal.h>}.
1188
1189 We return the maximum value that can be used to obtain a meaningful
1190 symbolic name or message.
1191
1192 @end deftypefn
1193
1194 @c sigsetmask.c:8
1195 @deftypefn Supplemental int sigsetmask (int @var{set})
1196
1197 Sets the signal mask to the one provided in @var{set} and returns
1198 the old mask (which, for libiberty's implementation, will always
1199 be the value @code{1}).
1200
1201 @end deftypefn
1202
1203 @c simple-object.txh:96
1204 @deftypefn Extension {const char *} simple_object_attributes_compare @
1205   (simple_object_attributes *@var{attrs1}, simple_object_attributes *@var{attrs2}, @
1206    int *@var{err})
1207
1208 Compare @var{attrs1} and @var{attrs2}.  If they could be linked
1209 together without error, return @code{NULL}.  Otherwise, return an
1210 error message and set @code{*@var{err}} to an errno value or @code{0}
1211 if there is no relevant errno.
1212
1213 @end deftypefn
1214
1215 @c simple-object.txh:81
1216 @deftypefn Extension {simple_object_attributes *} simple_object_fetch_attributes @
1217   (simple_object_read *@var{simple_object}, const char **@var{errmsg}, int *@var{err})
1218
1219 Fetch the attributes of @var{simple_object}.  The attributes are
1220 internal information such as the format of the object file, or the
1221 architecture it was compiled for.  This information will persist until
1222 @code{simple_object_attributes_release} is called, even if
1223 @var{simple_object} itself is released.
1224
1225 On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an
1226 error message, and sets @code{*@var{err}} to an errno value or
1227 @code{0} if there is no relevant errno.
1228
1229 @end deftypefn
1230
1231 @c simple-object.txh:49
1232 @deftypefn Extension {int} simple_object_find_section @
1233   (simple_object_read *@var{simple_object} off_t *@var{offset}, @
1234   off_t *@var{length}, const char **@var{errmsg}, int *@var{err})
1235
1236 Look for the section @var{name} in @var{simple_object}.  This returns
1237 information for the first section with that name.
1238
1239 If found, return 1 and set @code{*@var{offset}} to the offset in the
1240 file of the section contents and set @code{*@var{length}} to the
1241 length of the section contents.  The value in @code{*@var{offset}}
1242 will be relative to the offset passed to
1243 @code{simple_object_open_read}.
1244
1245 If the section is not found, and no error occurs,
1246 @code{simple_object_find_section} returns @code{0} and set
1247 @code{*@var{errmsg}} to @code{NULL}.
1248
1249 If an error occurs, @code{simple_object_find_section} returns
1250 @code{0}, sets @code{*@var{errmsg}} to an error message, and sets
1251 @code{*@var{err}} to an errno value or @code{0} if there is no
1252 relevant errno.
1253
1254 @end deftypefn
1255
1256 @c simple-object.txh:27
1257 @deftypefn Extension {const char *} simple_object_find_sections @
1258   (simple_object_read *@var{simple_object}, int (*@var{pfn}) (void *@var{data}, @
1259   const char *@var{name}, off_t @var{offset}, off_t @var{length}), @
1260   void *@var{data}, int *@var{err})
1261
1262 This function calls @var{pfn} for each section in @var{simple_object}.
1263 It calls @var{pfn} with the section name, the offset within the file
1264 of the section contents, and the length of the section contents.  The
1265 offset within the file is relative to the offset passed to
1266 @code{simple_object_open_read}.  The @var{data} argument to this
1267 function is passed along to @var{pfn}.
1268
1269 If @var{pfn} returns @code{0}, the loop over the sections stops and
1270 @code{simple_object_find_sections} returns.  If @var{pfn} returns some
1271 other value, the loop continues.
1272
1273 On success @code{simple_object_find_sections} returns.  On error it
1274 returns an error string, and sets @code{*@var{err}} to an errno value
1275 or @code{0} if there is no relevant errno.
1276
1277 @end deftypefn
1278
1279 @c simple-object.txh:2
1280 @deftypefn Extension {simple_object_read *} simple_object_open_read @
1281   (int @var{descriptor}, off_t @var{offset}, const char *{segment_name}, @
1282   const char **@var{errmsg}, int *@var{err})
1283
1284 Opens an object file for reading.  Creates and returns an
1285 @code{simple_object_read} pointer which may be passed to other
1286 functions to extract data from the object file.
1287
1288 @var{descriptor} holds a file descriptor which permits reading.
1289
1290 @var{offset} is the offset into the file; this will be @code{0} in the
1291 normal case, but may be a different value when reading an object file
1292 in an archive file.
1293
1294 @var{segment_name} is only used with the Mach-O file format used on
1295 Darwin aka Mac OS X.  It is required on that platform, and means to
1296 only look at sections within the segment with that name.  The
1297 parameter is ignored on other systems.
1298
1299 If an error occurs, this functions returns @code{NULL} and sets
1300 @code{*@var{errmsg}} to an error string and sets @code{*@var{err}} to
1301 an errno value or @code{0} if there is no relevant errno.
1302
1303 @end deftypefn
1304
1305 @c simple-object.txh:107
1306 @deftypefn Extension {void} simple_object_release_attributes @
1307   (simple_object_attributes *@var{attrs})
1308
1309 Release all resources associated with @var{attrs}.
1310
1311 @end deftypefn
1312
1313 @c simple-object.txh:73
1314 @deftypefn Extension {void} simple_object_release_read @
1315   (simple_object_read *@var{simple_object})
1316
1317 Release all resources associated with @var{simple_object}.  This does
1318 not close the file descriptor.
1319
1320 @end deftypefn
1321
1322 @c simple-object.txh:184
1323 @deftypefn Extension {void} simple_object_release_write @
1324   (simple_object_write *@var{simple_object})
1325
1326 Release all resources associated with @var{simple_object}.
1327
1328 @end deftypefn
1329
1330 @c simple-object.txh:114
1331 @deftypefn Extension {simple_object_write *} simple_object_start_write @
1332   (simple_object_attributes @var{attrs}, const char *@var{segment_name}, @
1333   const char **@var{errmsg}, int *@var{err})
1334
1335 Start creating a new object file using the object file format
1336 described in @var{attrs}.  You must fetch attribute information from
1337 an existing object file before you can create a new one.  There is
1338 currently no support for creating an object file de novo.
1339
1340 @var{segment_name} is only used with Mach-O as found on Darwin aka Mac
1341 OS X.  The parameter is required on that target.  It means that all
1342 sections are created within the named segment.  It is ignored for
1343 other object file formats.
1344
1345 On error @code{simple_object_start_write} returns @code{NULL}, sets
1346 @code{*@var{ERRMSG}} to an error message, and sets @code{*@var{err}}
1347 to an errno value or @code{0} if there is no relevant errno.
1348
1349 @end deftypefn
1350
1351 @c simple-object.txh:153
1352 @deftypefn Extension {const char *} simple_object_write_add_data @
1353   (simple_object_write *@var{simple_object}, @
1354   simple_object_write_section *@var{section}, const void *@var{buffer}, @
1355   size_t @var{size}, int @var{copy}, int *@var{err})
1356
1357 Add data @var{buffer}/@var{size} to @var{section} in
1358 @var{simple_object}.  If @var{copy} is non-zero, the data will be
1359 copied into memory if necessary.  If @var{copy} is zero, @var{buffer}
1360 must persist until @code{simple_object_write_to_file} is called.  is
1361 released.
1362
1363 On success this returns @code{NULL}.  On error this returns an error
1364 message, and sets @code{*@var{err}} to an errno value or 0 if there is
1365 no relevant erro.
1366
1367 @end deftypefn
1368
1369 @c simple-object.txh:134
1370 @deftypefn Extension {simple_object_write_section *} simple_object_write_create_section @
1371   (simple_object_write *@var{simple_object}, const char *@var{name}, @
1372   unsigned int @var{align}, const char **@var{errmsg}, int *@var{err})
1373
1374 Add a section to @var{simple_object}.  @var{name} is the name of the
1375 new section.  @var{align} is the required alignment expressed as the
1376 number of required low-order 0 bits (e.g., 2 for alignment to a 32-bit
1377 boundary).
1378
1379 The section is created as containing data, readable, not writable, not
1380 executable, not loaded at runtime.  The section is not written to the
1381 file until @code{simple_object_write_to_file} is called.
1382
1383 On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an
1384 error message, and sets @code{*@var{err}} to an errno value or
1385 @code{0} if there is no relevant errno.
1386
1387 @end deftypefn
1388
1389 @c simple-object.txh:170
1390 @deftypefn Extension {const char *} simple_object_write_to_file @
1391   (simple_object_write *@var{simple_object}, int @var{descriptor}, int *@var{err})
1392
1393 Write the complete object file to @var{descriptor}, an open file
1394 descriptor.  This writes out all the data accumulated by calls to
1395 @code{simple_object_write_create_section} and
1396 @var{simple_object_write_add_data}.
1397
1398 This returns @code{NULL} on success.  On error this returns an error
1399 message and sets @code{*@var{err}} to an errno value or @code{0} if
1400 there is no relevant errno.
1401
1402 @end deftypefn
1403
1404 @c snprintf.c:28
1405 @deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, @
1406   const char *@var{format}, ...)
1407
1408 This function is similar to @code{sprintf}, but it will write to
1409 @var{buf} at most @code{@var{n}-1} bytes of text, followed by a
1410 terminating null byte, for a total of @var{n} bytes.
1411 On error the return value is -1, otherwise it returns the number of
1412 bytes, not including the terminating null byte, that would have been
1413 written had @var{n} been sufficiently large, regardless of the actual
1414 value of @var{n}.  Note some pre-C99 system libraries do not implement
1415 this correctly so users cannot generally rely on the return value if
1416 the system version of this function is used.
1417
1418 @end deftypefn
1419
1420 @c spaces.c:22
1421 @deftypefn Extension char* spaces (int @var{count})
1422
1423 Returns a pointer to a memory region filled with the specified
1424 number of spaces and null terminated.  The returned pointer is
1425 valid until at least the next call.
1426
1427 @end deftypefn
1428
1429 @c splay-tree.c:303
1430 @deftypefn Supplemental splay_tree splay_tree_new_with_typed_alloc @
1431 (splay_tree_compare_fn @var{compare_fn}, @
1432 splay_tree_delete_key_fn @var{delete_key_fn}, @
1433 splay_tree_delete_value_fn @var{delete_value_fn}, @
1434 splay_tree_allocate_fn @var{tree_allocate_fn}, @
1435 splay_tree_allocate_fn @var{node_allocate_fn}, @
1436 splay_tree_deallocate_fn @var{deallocate_fn}, @
1437 void * @var{allocate_data})
1438
1439 This function creates a splay tree that uses two different allocators
1440 @var{tree_allocate_fn} and @var{node_allocate_fn} to use for allocating the
1441 tree itself and its nodes respectively.  This is useful when variables of
1442 different types need to be allocated with different allocators.
1443
1444 The splay tree will use @var{compare_fn} to compare nodes,
1445 @var{delete_key_fn} to deallocate keys, and @var{delete_value_fn} to
1446 deallocate values.
1447
1448 @end deftypefn
1449
1450 @c stpcpy.c:23
1451 @deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src})
1452
1453 Copies the string @var{src} into @var{dst}.  Returns a pointer to
1454 @var{dst} + strlen(@var{src}).
1455
1456 @end deftypefn
1457
1458 @c stpncpy.c:23
1459 @deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, @
1460   size_t @var{len})
1461
1462 Copies the string @var{src} into @var{dst}, copying exactly @var{len}
1463 and padding with zeros if necessary.  If @var{len} < strlen(@var{src})
1464 then return @var{dst} + @var{len}, otherwise returns @var{dst} +
1465 strlen(@var{src}).
1466
1467 @end deftypefn
1468
1469 @c strcasecmp.c:15
1470 @deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
1471
1472 A case-insensitive @code{strcmp}.
1473
1474 @end deftypefn
1475
1476 @c strchr.c:6
1477 @deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
1478
1479 Returns a pointer to the first occurrence of the character @var{c} in
1480 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
1481 null character, the results are undefined.
1482
1483 @end deftypefn
1484
1485 @c strdup.c:3
1486 @deftypefn Supplemental char* strdup (const char *@var{s})
1487
1488 Returns a pointer to a copy of @var{s} in memory obtained from
1489 @code{malloc}, or @code{NULL} if insufficient memory was available.
1490
1491 @end deftypefn
1492
1493 @c strerror.c:670
1494 @deftypefn Replacement {const char*} strerrno (int @var{errnum})
1495
1496 Given an error number returned from a system call (typically returned
1497 in @code{errno}), returns a pointer to a string containing the
1498 symbolic name of that error number, as found in @code{<errno.h>}.
1499
1500 If the supplied error number is within the valid range of indices for
1501 symbolic names, but no name is available for the particular error
1502 number, then returns the string @samp{Error @var{num}}, where @var{num}
1503 is the error number.
1504
1505 If the supplied error number is not within the range of valid
1506 indices, then returns @code{NULL}.
1507
1508 The contents of the location pointed to are only guaranteed to be
1509 valid until the next call to @code{strerrno}.
1510
1511 @end deftypefn
1512
1513 @c strerror.c:603
1514 @deftypefn Supplemental char* strerror (int @var{errnoval})
1515
1516 Maps an @code{errno} number to an error message string, the contents
1517 of which are implementation defined.  On systems which have the
1518 external variables @code{sys_nerr} and @code{sys_errlist}, these
1519 strings will be the same as the ones used by @code{perror}.
1520
1521 If the supplied error number is within the valid range of indices for
1522 the @code{sys_errlist}, but no message is available for the particular
1523 error number, then returns the string @samp{Error @var{num}}, where
1524 @var{num} is the error number.
1525
1526 If the supplied error number is not a valid index into
1527 @code{sys_errlist}, returns @code{NULL}.
1528
1529 The returned string is only guaranteed to be valid only until the
1530 next call to @code{strerror}.
1531
1532 @end deftypefn
1533
1534 @c strncasecmp.c:15
1535 @deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
1536
1537 A case-insensitive @code{strncmp}.
1538
1539 @end deftypefn
1540
1541 @c strncmp.c:6
1542 @deftypefn Supplemental int strncmp (const char *@var{s1}, @
1543   const char *@var{s2}, size_t @var{n})
1544
1545 Compares the first @var{n} bytes of two strings, returning a value as
1546 @code{strcmp}.
1547
1548 @end deftypefn
1549
1550 @c strndup.c:23
1551 @deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n})
1552
1553 Returns a pointer to a copy of @var{s} with at most @var{n} characters
1554 in memory obtained from @code{malloc}, or @code{NULL} if insufficient
1555 memory was available.  The result is always NUL terminated.
1556
1557 @end deftypefn
1558
1559 @c strrchr.c:6
1560 @deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
1561
1562 Returns a pointer to the last occurrence of the character @var{c} in
1563 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
1564 null character, the results are undefined.
1565
1566 @end deftypefn
1567
1568 @c strsignal.c:383
1569 @deftypefn Supplemental {const char *} strsignal (int @var{signo})
1570
1571 Maps an signal number to an signal message string, the contents of
1572 which are implementation defined.  On systems which have the external
1573 variable @code{sys_siglist}, these strings will be the same as the
1574 ones used by @code{psignal()}.
1575
1576 If the supplied signal number is within the valid range of indices for
1577 the @code{sys_siglist}, but no message is available for the particular
1578 signal number, then returns the string @samp{Signal @var{num}}, where
1579 @var{num} is the signal number.
1580
1581 If the supplied signal number is not a valid index into
1582 @code{sys_siglist}, returns @code{NULL}.
1583
1584 The returned string is only guaranteed to be valid only until the next
1585 call to @code{strsignal}.
1586
1587 @end deftypefn
1588
1589 @c strsignal.c:448
1590 @deftypefn Extension {const char*} strsigno (int @var{signo})
1591
1592 Given an signal number, returns a pointer to a string containing the
1593 symbolic name of that signal number, as found in @code{<signal.h>}.
1594
1595 If the supplied signal number is within the valid range of indices for
1596 symbolic names, but no name is available for the particular signal
1597 number, then returns the string @samp{Signal @var{num}}, where
1598 @var{num} is the signal number.
1599
1600 If the supplied signal number is not within the range of valid
1601 indices, then returns @code{NULL}.
1602
1603 The contents of the location pointed to are only guaranteed to be
1604 valid until the next call to @code{strsigno}.
1605
1606 @end deftypefn
1607
1608 @c strstr.c:6
1609 @deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
1610
1611 This function searches for the substring @var{sub} in the string
1612 @var{string}, not including the terminating null characters.  A pointer
1613 to the first occurrence of @var{sub} is returned, or @code{NULL} if the
1614 substring is absent.  If @var{sub} points to a string with zero
1615 length, the function returns @var{string}.
1616
1617 @end deftypefn
1618
1619 @c strtod.c:27
1620 @deftypefn Supplemental double strtod (const char *@var{string}, @
1621   char **@var{endptr})
1622
1623 This ISO C function converts the initial portion of @var{string} to a
1624 @code{double}.  If @var{endptr} is not @code{NULL}, a pointer to the
1625 character after the last character used in the conversion is stored in
1626 the location referenced by @var{endptr}.  If no conversion is
1627 performed, zero is returned and the value of @var{string} is stored in
1628 the location referenced by @var{endptr}.
1629
1630 @end deftypefn
1631
1632 @c strerror.c:729
1633 @deftypefn Extension int strtoerrno (const char *@var{name})
1634
1635 Given the symbolic name of a error number (e.g., @code{EACCES}), map it
1636 to an errno value.  If no translation is found, returns 0.
1637
1638 @end deftypefn
1639
1640 @c strtol.c:33
1641 @deftypefn Supplemental {long int} strtol (const char *@var{string}, @
1642   char **@var{endptr}, int @var{base})
1643 @deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, @
1644   char **@var{endptr}, int @var{base})
1645
1646 The @code{strtol} function converts the string in @var{string} to a
1647 long integer value according to the given @var{base}, which must be
1648 between 2 and 36 inclusive, or be the special value 0.  If @var{base}
1649 is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
1650 to indicate bases 8 and 16, respectively, else default to base 10.
1651 When the base is 16 (either explicitly or implicitly), a prefix of
1652 @code{0x} is allowed.  The handling of @var{endptr} is as that of
1653 @code{strtod} above.  The @code{strtoul} function is the same, except
1654 that the converted value is unsigned.
1655
1656 @end deftypefn
1657
1658 @c strsignal.c:502
1659 @deftypefn Extension int strtosigno (const char *@var{name})
1660
1661 Given the symbolic name of a signal, map it to a signal number.  If no
1662 translation is found, returns 0.
1663
1664 @end deftypefn
1665
1666 @c strverscmp.c:25
1667 @deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2})
1668 The @code{strverscmp} function compares the string @var{s1} against
1669 @var{s2}, considering them as holding indices/version numbers.  Return
1670 value follows the same conventions as found in the @code{strverscmp}
1671 function.  In fact, if @var{s1} and @var{s2} contain no digits,
1672 @code{strverscmp} behaves like @code{strcmp}.
1673
1674 Basically, we compare strings normally (character by character), until
1675 we find a digit in each string - then we enter a special comparison
1676 mode, where each sequence of digits is taken as a whole.  If we reach the
1677 end of these two parts without noticing a difference, we return to the
1678 standard comparison mode.  There are two types of numeric parts:
1679 "integral" and "fractional" (those  begin with a '0'). The types
1680 of the numeric parts affect the way we sort them:
1681
1682 @itemize @bullet
1683 @item
1684 integral/integral: we compare values as you would expect.
1685
1686 @item
1687 fractional/integral: the fractional part is less than the integral one.
1688 Again, no surprise.
1689
1690 @item
1691 fractional/fractional: the things become a bit more complex.
1692 If the common prefix contains only leading zeroes, the longest part is less
1693 than the other one; else the comparison behaves normally.
1694 @end itemize
1695
1696 @smallexample
1697 strverscmp ("no digit", "no digit")
1698     @result{} 0    // @r{same behavior as strcmp.}
1699 strverscmp ("item#99", "item#100")
1700     @result{} <0   // @r{same prefix, but 99 < 100.}
1701 strverscmp ("alpha1", "alpha001")
1702     @result{} >0   // @r{fractional part inferior to integral one.}
1703 strverscmp ("part1_f012", "part1_f01")
1704     @result{} >0   // @r{two fractional parts.}
1705 strverscmp ("foo.009", "foo.0")
1706     @result{} <0   // @r{idem, but with leading zeroes only.}
1707 @end smallexample
1708
1709 This function is especially useful when dealing with filename sorting,
1710 because filenames frequently hold indices/version numbers.
1711 @end deftypefun
1712
1713 @c tmpnam.c:3
1714 @deftypefn Supplemental char* tmpnam (char *@var{s})
1715
1716 This function attempts to create a name for a temporary file, which
1717 will be a valid file name yet not exist when @code{tmpnam} checks for
1718 it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
1719 or be @code{NULL}.  Use of this function creates a security risk, and it must
1720 not be used in new projects.  Use @code{mkstemp} instead.
1721
1722 @end deftypefn
1723
1724 @c unlink-if-ordinary.c:27
1725 @deftypefn Supplemental int unlink_if_ordinary (const char*)
1726
1727 Unlinks the named file, unless it is special (e.g. a device file).
1728 Returns 0 when the file was unlinked, a negative value (and errno set) when
1729 there was an error deleting the file, and a positive value if no attempt
1730 was made to unlink the file because it is special.
1731
1732 @end deftypefn
1733
1734 @c fopen_unlocked.c:31
1735 @deftypefn Extension void unlock_std_streams (void)
1736
1737 If the OS supports it, ensure that the standard I/O streams,
1738 @code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any
1739 multi-threaded locking.  Otherwise do nothing.
1740
1741 @end deftypefn
1742
1743 @c fopen_unlocked.c:23
1744 @deftypefn Extension void unlock_stream (FILE * @var{stream})
1745
1746 If the OS supports it, ensure that the supplied stream is setup to
1747 avoid any multi-threaded locking.  Otherwise leave the @code{FILE}
1748 pointer unchanged.  If the @var{stream} is @code{NULL} do nothing.
1749
1750 @end deftypefn
1751
1752 @c vasprintf.c:47
1753 @deftypefn Extension int vasprintf (char **@var{resptr}, @
1754   const char *@var{format}, va_list @var{args})
1755
1756 Like @code{vsprintf}, but instead of passing a pointer to a buffer,
1757 you pass a pointer to a pointer.  This function will compute the size
1758 of the buffer needed, allocate memory with @code{malloc}, and store a
1759 pointer to the allocated memory in @code{*@var{resptr}}.  The value
1760 returned is the same as @code{vsprintf} would return.  If memory could
1761 not be allocated, minus one is returned and @code{NULL} is stored in
1762 @code{*@var{resptr}}.
1763
1764 @end deftypefn
1765
1766 @c vfork.c:6
1767 @deftypefn Supplemental int vfork (void)
1768
1769 Emulates @code{vfork} by calling @code{fork} and returning its value.
1770
1771 @end deftypefn
1772
1773 @c vprintf.c:3
1774 @deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
1775 @deftypefnx Supplemental int vfprintf (FILE *@var{stream}, @
1776   const char *@var{format}, va_list @var{ap})
1777 @deftypefnx Supplemental int vsprintf (char *@var{str}, @
1778   const char *@var{format}, va_list @var{ap})
1779
1780 These functions are the same as @code{printf}, @code{fprintf}, and
1781 @code{sprintf}, respectively, except that they are called with a
1782 @code{va_list} instead of a variable number of arguments.  Note that
1783 they do not call @code{va_end}; this is the application's
1784 responsibility.  In @libib{} they are implemented in terms of the
1785 nonstandard but common function @code{_doprnt}.
1786
1787 @end deftypefn
1788
1789 @c vsnprintf.c:28
1790 @deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, @
1791   const char *@var{format}, va_list @var{ap})
1792
1793 This function is similar to @code{vsprintf}, but it will write to
1794 @var{buf} at most @code{@var{n}-1} bytes of text, followed by a
1795 terminating null byte, for a total of @var{n} bytes.  On error the
1796 return value is -1, otherwise it returns the number of characters that
1797 would have been printed had @var{n} been sufficiently large,
1798 regardless of the actual value of @var{n}.  Note some pre-C99 system
1799 libraries do not implement this correctly so users cannot generally
1800 rely on the return value if the system version of this function is
1801 used.
1802
1803 @end deftypefn
1804
1805 @c waitpid.c:3
1806 @deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
1807
1808 This is a wrapper around the @code{wait} function.  Any ``special''
1809 values of @var{pid} depend on your implementation of @code{wait}, as
1810 does the return value.  The third argument is unused in @libib{}.
1811
1812 @end deftypefn
1813
1814 @c argv.c:306
1815 @deftypefn Extension int writeargv (const char **@var{argv}, FILE *@var{file})
1816
1817 Write each member of ARGV, handling all necessary quoting, to the file
1818 named by FILE, separated by whitespace.  Return 0 on success, non-zero
1819 if an error occurred while writing to FILE.
1820
1821 @end deftypefn
1822
1823 @c xatexit.c:11
1824 @deftypefun int xatexit (void (*@var{fn}) (void))
1825
1826 Behaves as the standard @code{atexit} function, but with no limit on
1827 the number of registered functions.  Returns 0 on success, or @minus{}1 on
1828 failure.  If you use @code{xatexit} to register functions, you must use
1829 @code{xexit} to terminate your program.
1830
1831 @end deftypefun
1832
1833 @c xmalloc.c:38
1834 @deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize})
1835
1836 Allocate memory without fail, and set it to zero.  This routine functions
1837 like @code{calloc}, but will behave the same as @code{xmalloc} if memory
1838 cannot be found.
1839
1840 @end deftypefn
1841
1842 @c xexit.c:22
1843 @deftypefn Replacement void xexit (int @var{code})
1844
1845 Terminates the program.  If any functions have been registered with
1846 the @code{xatexit} replacement function, they will be called first.
1847 Termination is handled via the system's normal @code{exit} call.
1848
1849 @end deftypefn
1850
1851 @c xmalloc.c:22
1852 @deftypefn Replacement void* xmalloc (size_t)
1853
1854 Allocate memory without fail.  If @code{malloc} fails, this will print
1855 a message to @code{stderr} (using the name set by
1856 @code{xmalloc_set_program_name},
1857 if any) and then call @code{xexit}.  Note that it is therefore safe for
1858 a program to contain @code{#define malloc xmalloc} in its source.
1859
1860 @end deftypefn
1861
1862 @c xmalloc.c:53
1863 @deftypefn Replacement void xmalloc_failed (size_t)
1864
1865 This function is not meant to be called by client code, and is listed
1866 here for completeness only.  If any of the allocation routines fail, this
1867 function will be called to print an error message and terminate execution.
1868
1869 @end deftypefn
1870
1871 @c xmalloc.c:46
1872 @deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
1873
1874 You can use this to set the name of the program used by
1875 @code{xmalloc_failed} when printing a failure message.
1876
1877 @end deftypefn
1878
1879 @c xmemdup.c:7
1880 @deftypefn Replacement void* xmemdup (void *@var{input}, @
1881   size_t @var{copy_size}, size_t @var{alloc_size})
1882
1883 Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
1884 are allocated, then @var{copy_size} bytes from @var{input} are copied into
1885 it, and the new memory is returned.  If fewer bytes are copied than were
1886 allocated, the remaining memory is zeroed.
1887
1888 @end deftypefn
1889
1890 @c xmalloc.c:32
1891 @deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size})
1892 Reallocate memory without fail.  This routine functions like @code{realloc},
1893 but will behave the same as @code{xmalloc} if memory cannot be found.
1894
1895 @end deftypefn
1896
1897 @c xstrdup.c:7
1898 @deftypefn Replacement char* xstrdup (const char *@var{s})
1899
1900 Duplicates a character string without fail, using @code{xmalloc} to
1901 obtain memory.
1902
1903 @end deftypefn
1904
1905 @c xstrerror.c:7
1906 @deftypefn Replacement char* xstrerror (int @var{errnum})
1907
1908 Behaves exactly like the standard @code{strerror} function, but
1909 will never return a @code{NULL} pointer.
1910
1911 @end deftypefn
1912
1913 @c xstrndup.c:23
1914 @deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n})
1915
1916 Returns a pointer to a copy of @var{s} with at most @var{n} characters
1917 without fail, using @code{xmalloc} to obtain memory.  The result is
1918 always NUL terminated.
1919
1920 @end deftypefn
1921
1922