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