OSDN Git Service

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