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