OSDN Git Service

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