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 and let gather-docs build you a new copy.
5
6 @c alloca.c:26
7 @deftypefn Replacement void* alloca (size_t @var{size})
8
9 This function allocates memory which will be automatically reclaimed
10 after the procedure exits.  The @libib{} implementation does not free
11 the memory immediately but will do so eventually during subsequent
12 calls to this function.  Memory is allocated using @code{xmalloc} under
13 normal circumstances.
14
15 The header file @file{alloca-conf.h} can be used in conjunction with the
16 GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make
17 available this function.  The @code{AC_FUNC_ALLOCA} test requires that
18 client code use a block of preprocessor code to be safe (see the Autoconf
19 manual for more); this header incorporates that logic and more, including
20 the possibility of a GCC built-in function.
21
22 @end deftypefn
23
24 @c asprintf.c:33
25 @deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...)
26
27 Like @code{sprintf}, but instead of passing a pointer to a buffer, you
28 pass a pointer to a pointer.  This function will compute the size of
29 the buffer needed, allocate memory with @code{malloc}, and store a
30 pointer to the allocated memory in @code{*@var{resptr}}.  The value
31 returned is the same as @code{sprintf} would return.  If memory could
32 not be allocated, zero is returned and @code{NULL} is stored in
33 @code{*@var{resptr}}.
34
35 @end deftypefn
36
37 @c atexit.c:6
38 @deftypefn Supplemental int atexit (void (*@var{f})())
39
40 Causes function @var{f} to be called at exit.  Returns 0.
41
42 @end deftypefn
43
44 @c basename.c:6
45 @deftypefn Supplemental char* basename (const char *@var{name})
46
47 Returns a pointer to the last component of pathname @var{name}.
48 Behavior is undefined if the pathname ends in a directory separator.
49
50 @end deftypefn
51
52 @c bcmp.c:6
53 @deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count})
54
55 Compares the first @var{count} bytes of two areas of memory.  Returns
56 zero if they are the same, nonzero otherwise.  Returns zero if
57 @var{count} is zero.  A nonzero result only indicates a difference,
58 it does not indicate any sorting order (say, by having a positive
59 result mean @var{x} sorts before @var{y}).
60
61 @end deftypefn
62
63 @c bcopy.c:3
64 @deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length})
65
66 Copies @var{length} bytes from memory region @var{in} to region
67 @var{out}.  The use of @code{bcopy} is deprecated in new programs.
68
69 @end deftypefn
70
71 @c bsearch.c:33
72 @deftypefn Supplemental void* bsearch (const void *@var{key}, const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, int (*@var{compar})(const void *, const void *))
73
74 Performs a search over an array of @var{nmemb} elements pointed to by
75 @var{base} for a member that matches the object pointed to by @var{key}.
76 The size of each member is specified by @var{size}.  The array contents
77 should be sorted in ascending order according to the @var{compar}
78 comparison function.  This routine should take two arguments pointing to
79 the @var{key} and to an array member, in that order, and should return an
80 integer less than, equal to, or greater than zero if the @var{key} object
81 is respectively less than, matching, or greater than the array member.
82
83 @end deftypefn
84
85 @c argv.c:139
86 @deftypefn Extension char** buildargv (char *@var{sp})
87
88 Given a pointer to a string, parse the string extracting fields
89 separated by whitespace and optionally enclosed within either single
90 or double quotes (which are stripped off), and build a vector of
91 pointers to copies of the string for each field.  The input string
92 remains unchanged.  The last element of the vector is followed by a
93 @code{NULL} element.
94
95 All of the memory for the pointer array and copies of the string
96 is obtained from @code{malloc}.  All of the memory can be returned to the
97 system with the single function call @code{freeargv}, which takes the
98 returned result of @code{buildargv}, as it's argument.
99
100 Returns a pointer to the argument vector if successful.  Returns
101 @code{NULL} if @var{sp} is @code{NULL} or if there is insufficient
102 memory to complete building the argument vector.
103
104 If the input is a null string (as opposed to a @code{NULL} pointer),
105 then buildarg returns an argument vector that has one arg, a null
106 string.
107
108 @end deftypefn
109
110 @c bzero.c:6
111 @deftypefn Supplemental void bzero (char *@var{mem}, int @var{count})
112
113 Zeros @var{count} bytes starting at @var{mem}.  Use of this function
114 is deprecated in favor of @code{memset}.
115
116 @end deftypefn
117
118 @c calloc.c:6
119 @deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize})
120
121 Uses @code{malloc} to allocate storage for @var{nelem} objects of
122 @var{elsize} bytes each, then zeros the memory.
123
124 @end deftypefn
125
126 @c choose-temp.c:42
127 @deftypefn Extension char* choose_temp_base (void)
128
129 Return a prefix for temporary file names or @code{NULL} if unable to
130 find one.  The current directory is chosen if all else fails so the
131 program is exited if a temporary directory can't be found (@code{mktemp}
132 fails).  The buffer for the result is obtained with @code{xmalloc}.
133
134 This function is provided for backwards compatability only.  Its use is
135 not recommended.
136
137 @end deftypefn
138
139 @c make-temp-file.c:88
140 @deftypefn Replacement char* choose_tmpdir ()
141
142 Returns a pointer to a directory path suitable for creating temporary
143 files in.
144
145 @end deftypefn
146
147 @c clock.c:27
148 @deftypefn Supplemental long clock (void)
149
150 Returns an approximation of the CPU time used by the process as a
151 @code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the
152 number of seconds used.
153
154 @end deftypefn
155
156 @c concat.c:24
157 @deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL})
158
159 Concatenate zero or more of strings and return the result in freshly
160 @code{xmalloc}ed memory.  Returns @code{NULL} if insufficient memory is
161 available.  The argument list is terminated by the first @code{NULL}
162 pointer encountered.  Pointers to empty strings are ignored.
163
164 @end deftypefn
165
166 @c argv.c:65
167 @deftypefn Extension char** dupargv (char **@var{vector})
168
169 Duplicate an argument vector.  Simply scans through @var{vector},
170 duplicating each argument until the terminating @code{NULL} is found.
171 Returns a pointer to the argument vector if successful.  Returns
172 @code{NULL} if there is insufficient memory to complete building the
173 argument vector.
174
175 @end deftypefn
176
177 @c strerror.c:566
178 @deftypefn Extension int errno_max (void)
179
180 Returns the maximum @code{errno} value for which a corresponding
181 symbolic name or message is available.  Note that in the case where we
182 use the @code{sys_errlist} supplied by the system, it is possible for
183 there to be more symbolic names than messages, or vice versa.  In
184 fact, the manual page for @code{perror(3C)} explicitly warns that one
185 should check the size of the table (@code{sys_nerr}) before indexing
186 it, since new error codes may be added to the system before they are
187 added to the table.  Thus @code{sys_nerr} might be smaller than value
188 implied by the largest @code{errno} value defined in @code{<errno.h>}.
189
190 We return the maximum value that can be used to obtain a meaningful
191 symbolic name or message.
192
193 @end deftypefn
194
195 @c fdmatch.c:23
196 @deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2})
197
198 Check to see if two open file descriptors refer to the same file.
199 This is useful, for example, when we have an open file descriptor for
200 an unnamed file, and the name of a file that we believe to correspond
201 to that fd.  This can happen when we are exec'd with an already open
202 file (@code{stdout} for example) or from the SVR4 @file{/proc} calls
203 that return open file descriptors for mapped address spaces.  All we
204 have to do is open the file by name and check the two file descriptors
205 for a match, which is done by comparing major and minor device numbers
206 and inode numbers.
207
208 @end deftypefn
209
210 @c ffs.c:3
211 @deftypefn Supplemental int ffs (int @var{valu})
212
213 Find the first (least significant) bit set in @var{valu}.  Bits are
214 numbered from right to left, starting with bit 1 (corresponding to the
215 value 1).  If @var{valu} is zero, zero is returned.
216
217 @end deftypefn
218
219 @c fnmatch.txh:1
220 @deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags})
221
222 Matches @var{string} against @var{pattern}, returning zero if it
223 matches, @code{FNM_NOMATCH} if not.  @var{pattern} may contain the
224 wildcards @code{?} to match any one character, @code{*} to match any
225 zero or more characters, or a set of alternate characters in square
226 brackets, like @samp{[a-gt8]}, which match one character (@code{a}
227 through @code{g}, or @code{t}, or @code{8}, in this example) if that one
228 character is in the set.  A set may be inverted (i.e., match anything
229 except what's in the set) by giving @code{^} or @code{!} as the first
230 character in the set.  To include those characters in the set, list them
231 as anything other than the first character of the set.  To include a
232 dash in the set, list it last in the set.  A backslash character makes
233 the following character not special, so for example you could match
234 against a literal asterisk with @samp{\*}.  To match a literal
235 backslash, use @samp{\\}.
236
237 @code{flags} controls various aspects of the matching process, and is a
238 boolean OR of zero or more of the following values (defined in
239 @code{<fnmatch.h>}):
240
241 @table @code
242
243 @item FNM_PATHNAME
244 @itemx FNM_FILE_NAME
245 @var{string} is assumed to be a path name.  No wildcard will ever match
246 @code{/}.
247
248 @item FNM_NOESCAPE
249 Do not interpret backslashes as quoting the following special character.
250
251 @item FNM_PERIOD
252 A leading period (at the beginning of @var{string}, or if
253 @code{FNM_PATHNAME} after a slash) is not matched by @code{*} or
254 @code{?} but must be matched explicitly.
255
256 @item FNM_LEADING_DIR
257 Means that @var{string} also matches @var{pattern} if some initial part
258 of @var{string} matches, and is followed by @code{/} and zero or more
259 characters.  For example, @samp{foo*} would match either @samp{foobar}
260 or @samp{foobar/grill}.
261
262 @item FNM_CASEFOLD
263 Ignores case when performing the comparison.
264
265 @end table
266
267 @end deftypefn
268
269 @c argv.c:111
270 @deftypefn Extension void freeargv (char **@var{vector})
271
272 Free an argument vector that was built using @code{buildargv}.  Simply
273 scans through @var{vector}, freeing the memory for each argument until
274 the terminating @code{NULL} is found, and then frees @var{vector}
275 itself.
276
277 @end deftypefn
278
279 @c getruntime.c:82
280 @deftypefn Replacement long get_run_time (void)
281
282 Returns the time used so far, in microseconds.  If possible, this is
283 the time used by this process, else it is the elapsed time since the
284 process started.
285
286 @end deftypefn
287
288 @c getcwd.c:6
289 @deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len})
290
291 Copy the absolute pathname for the current working directory into
292 @var{pathname}, which is assumed to point to a buffer of at least
293 @var{len} bytes, and return a pointer to the buffer.  If the current
294 directory's path doesn't fit in @var{len} characters, the result is
295 @code{NULL} and @code{errno} is set.  If @var{pathname} is a null pointer,
296 @code{getcwd} will obtain @var{len} bytes of space using
297 @code{malloc}.
298
299 @end deftypefn
300
301 @c getpagesize.c:5
302 @deftypefn Supplemental int getpagesize (void)
303
304 Returns the number of bytes in a page of memory.  This is the
305 granularity of many of the system memory management routines.  No
306 guarantee is made as to whether or not it is the same as the basic
307 memory management hardware page size.
308
309 @end deftypefn
310
311 @c getpwd.c:5
312 @deftypefn Supplemental char* getpwd (void)
313
314 Returns the current working directory.  This implementation caches the
315 result on the assumption that the process will not call @code{chdir}
316 between calls to @code{getpwd}.
317
318 @end deftypefn
319
320 @c hex.c:25
321 @deftypefn Extension void hex_init (void)
322
323 Initializes the array mapping the current character set to
324 corresponding hex values.  This function must be called before any
325 call to @code{hex_p} or @code{hex_value}.  If you fail to call it, a
326 default ASCII-based table will normally be used on ASCII systems.
327
328 @end deftypefn
329
330 @c hex.c:34
331 @deftypefn Extension int hex_p (int @var{c})
332
333 Evaluates to non-zero if the given character is a valid hex character,
334 or zero if it is not.  Note that the value you pass will be cast to
335 @code{unsigned char} within the macro.
336
337 @end deftypefn
338
339 @c hex.c:42
340 @deftypefn Extension int hex_value (int @var{c})
341
342 Returns the numeric equivalent of the given character when interpreted
343 as a hexidecimal digit.  The result is undefined if you pass an
344 invalid hex digit.  Note that the value you pass will be cast to
345 @code{unsigned char} within the macro.
346
347 @end deftypefn
348
349 @c index.c:5
350 @deftypefn Supplemental char* index (char *@var{s}, int @var{c})
351
352 Returns a pointer to the first occurrence of the character @var{c} in
353 the string @var{s}, or @code{NULL} if not found.  The use of @code{index} is
354 deprecated in new programs in favor of @code{strchr}.
355
356 @end deftypefn
357
358 @c insque.c:6
359 @deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred})
360 @deftypefnx Supplemental void remque (struct qelem *@var{elem})
361
362 Routines to manipulate queues built from doubly linked lists.  The
363 @code{insque} routine inserts @var{elem} in the queue immediately
364 after @var{pred}.  The @code{remque} routine removes @var{elem} from
365 its containing queue.  These routines expect to be passed pointers to
366 structures which have as their first members a forward pointer and a
367 back pointer, like this prototype (although no prototype is provided):
368
369 @example
370 struct qelem @{
371   struct qelem *q_forw;
372   struct qelem *q_back;
373   char q_data[];
374 @};
375 @end example
376
377 @end deftypefn
378
379 @c lbasename.c:23
380 @deftypefn Replacement {const char*} lbasename (const char *@var{name})
381
382 Given a pointer to a string containing a typical pathname
383 (@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the
384 last component of the pathname (@samp{ls.c} in this case).  The
385 returned pointer is guaranteed to lie within the original
386 string.  This latter fact is not true of many vendor C
387 libraries, which return special strings or modify the passed
388 strings for particular input.
389
390 In particular, the empty string returns the same empty string,
391 and a path ending in @code{/} returns the empty string after it.
392
393 @end deftypefn
394
395 @c make-relative-prefix.c:24
396 @deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, const char *@var{bin_prefix}, const char *@var{prefix})
397
398 Given three strings @var{progname}, @var{bin_prefix}, @var{prefix}, return a string
399 that gets to @var{prefix} starting with the directory portion of @var{progname} and
400 a relative pathname of the difference between @var{bin_prefix} and @var{prefix}.
401
402 For example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta}, @var{prefix}
403 is @code{/alpha/beta/gamma/omega/}, and @var{progname} is @code{/red/green/blue/gcc},
404 then this function will return @code{/red/green/blue/../../omega/}.
405
406 The return value is normally allocated via @code{malloc}.  If no relative prefix
407 can be found, return @code{NULL}.
408
409 @end deftypefn
410
411 @c make-temp-file.c:138
412 @deftypefn Replacement char* make_temp_file (const char *@var{suffix})
413
414 Return a temporary file name (as a string) or @code{NULL} if unable to
415 create one.  @var{suffix} is a suffix to append to the file name.  The
416 string is @code{malloc}ed, and the temporary file has been created.
417
418 @end deftypefn
419
420 @c memchr.c:3
421 @deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n})
422
423 This function searches memory starting at @code{*@var{s}} for the
424 character @var{c}.  The search only ends with the first occurrence of
425 @var{c}, or after @var{length} characters; in particular, a null
426 character does not terminate the search.  If the character @var{c} is
427 found within @var{length} characters of @code{*@var{s}}, a pointer
428 to the character is returned.  If @var{c} is not found, then @code{NULL} is
429 returned.
430
431 @end deftypefn
432
433 @c memcmp.c:6
434 @deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count})
435
436 Compares the first @var{count} bytes of two areas of memory.  Returns
437 zero if they are the same, a value less than zero if @var{x} is
438 lexically less than @var{y}, or a value greater than zero if @var{x}
439 is lexically greater than @var{y}.  Note that lexical order is determined
440 as if comparing unsigned char arrays.
441
442 @end deftypefn
443
444 @c memcpy.c:6
445 @deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
446
447 Copies @var{length} bytes from memory region @var{in} to region
448 @var{out}.  Returns a pointer to @var{out}.
449
450 @end deftypefn
451
452 @c memmove.c:6
453 @deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count})
454
455 Copies @var{count} bytes from memory area @var{from} to memory area
456 @var{to}, returning a pointer to @var{to}.
457
458 @end deftypefn
459
460 @c memset.c:6
461 @deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count})
462
463 Sets the first @var{count} bytes of @var{s} to the constant byte
464 @var{c}, returning a pointer to @var{s}.
465
466 @end deftypefn
467
468 @c mkstemps.c:54
469 @deftypefn Replacement int mkstemps (char *@var{template}, int @var{suffix_len})
470
471 Generate a unique temporary file name from @var{template}.
472 @var{template} has the form:
473
474 @example
475    @var{path}/ccXXXXXX@var{suffix}
476 @end example
477
478 @var{suffix_len} tells us how long @var{suffix} is (it can be zero
479 length).  The last six characters of @var{template} before @var{suffix}
480 must be @samp{XXXXXX}; they are replaced with a string that makes the
481 filename unique.  Returns a file descriptor open on the file for
482 reading and writing.
483
484 @end deftypefn
485
486 @c pexecute.c:67
487 @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 flags)
488
489 Executes a program.
490
491 @var{program} and @var{argv} are the arguments to
492 @code{execv}/@code{execvp}.
493
494 @var{this_pname} is name of the calling program (i.e., @code{argv[0]}).
495
496 @var{temp_base} is the path name, sans suffix, of a temporary file to
497 use if needed.  This is currently only needed for MS-DOS ports that
498 don't use @code{go32} (do any still exist?).  Ports that don't need it
499 can pass @code{NULL}.
500
501 (@code{@var{flags} & PEXECUTE_SEARCH}) is non-zero if @env{PATH} should be searched
502 (??? It's not clear that GCC passes this flag correctly).  (@code{@var{flags} &
503 PEXECUTE_FIRST}) is nonzero for the first process in chain.
504 (@code{@var{flags} & PEXECUTE_FIRST}) is nonzero for the last process
505 in chain.  The first/last flags could be simplified to only mark the
506 last of a chain of processes but that requires the caller to always
507 mark the last one (and not give up early if some error occurs).
508 It's more robust to require the caller to mark both ends of the chain.
509
510 The result is the pid on systems like Unix where we
511 @code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we
512 use @code{spawn}.  It is up to the caller to wait for the child.
513
514 The result is the @code{WEXITSTATUS} on systems like MS-DOS where we
515 @code{spawn} and wait for the child here.
516
517 Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the
518 text of the error message with an optional argument (if not needed,
519 @var{errmsg_arg} is set to @code{NULL}), and @minus{}1 is returned.
520 @code{errno} is available to the caller to use.
521
522 @end deftypefn
523
524 @c strsignal.c:547
525 @deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message})
526
527 Print @var{message} to the standard error, followed by a colon,
528 followed by the description of the signal specified by @var{signo},
529 followed by a newline.
530
531 @end deftypefn
532
533 @c putenv.c:21
534 @deftypefn Supplemental int putenv (const char *@var{string})
535
536 Uses @code{setenv} or @code{unsetenv} to put @var{string} into
537 the environment or remove it.  If @var{string} is of the form
538 @samp{name=value} the string is added; if no @samp{=} is present the
539 name is unset/removed.
540
541 @end deftypefn
542
543 @c pexecute.c:104
544 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
545
546 Waits for a program started by @code{pexecute} to finish.
547
548 @var{pid} is the process id of the task to wait for. @var{status} is
549 the `status' argument to wait. @var{flags} is currently unused (allows
550 future enhancement without breaking upward compatibility).  Pass 0 for now.
551
552 The result is the pid of the child reaped, or -1 for failure
553 (@code{errno} says why).
554
555 On systems that don't support waiting for a particular child, @var{pid} is
556 ignored.  On systems like MS-DOS that don't really multitask @code{pwait}
557 is just a mechanism to provide a consistent interface for the caller.
558
559 @end deftypefn
560
561 @c random.c:39
562 @deftypefn Supplement {long int} random (void)
563 @deftypefnx Supplement void srandom (unsigned int @var{seed})
564 @deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n})
565 @deftypefnx Supplement void* setstate (void *@var{arg_state})
566
567 Random number functions.  @code{random} returns a random number in the
568 range 0 to @code{LONG_MAX}.  @code{srandom} initializes the random
569 number generator to some starting point determined by @var{seed}
570 (else, the values returned by @code{random} are always the same for each
571 run of the program).  @code{initstate} and @code{setstate} allow fine-grained
572 control over the state of the random number generator.
573
574 @end deftypefn
575
576 @c concat.c:177
577 @deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL})
578
579 Same as @code{concat}, except that if @var{optr} is not @code{NULL} it
580 is freed after the string is created.  This is intended to be useful
581 when you're extending an existing string or building up a string in a
582 loop:
583
584 @example
585   str = reconcat (str, "pre-", str, NULL);
586 @end example
587
588 @end deftypefn
589
590 @c rename.c:6
591 @deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
592
593 Renames a file from @var{old} to @var{new}.  If @var{new} already
594 exists, it is removed.
595
596 @end deftypefn
597
598 @c rindex.c:5
599 @deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
600
601 Returns a pointer to the last occurrence of the character @var{c} in
602 the string @var{s}, or @code{NULL} if not found.  The use of @code{rindex} is
603 deprecated in new programs in favor of @code{strrchr}.
604
605 @end deftypefn
606
607 @c setenv.c:22
608 @deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
609 @deftypefnx Supplemental void unsetenv (const char *@var{name})
610
611 @code{setenv} adds @var{name} to the environment with value
612 @var{value}.  If the name was already present in the environment,
613 the new value will be stored only if @var{overwrite} is nonzero.
614 The companion @code{unsetenv} function removes @var{name} from the
615 environment.  This implementation is not safe for multithreaded code.
616
617 @end deftypefn
618
619 @c strsignal.c:353
620 @deftypefn Extension int signo_max (void)
621
622 Returns the maximum signal value for which a corresponding symbolic
623 name or message is available.  Note that in the case where we use the
624 @code{sys_siglist} supplied by the system, it is possible for there to
625 be more symbolic names than messages, or vice versa.  In fact, the
626 manual page for @code{psignal(3b)} explicitly warns that one should
627 check the size of the table (@code{NSIG}) before indexing it, since
628 new signal codes may be added to the system before they are added to
629 the table.  Thus @code{NSIG} might be smaller than value implied by
630 the largest signo value defined in @code{<signal.h>}.
631
632 We return the maximum value that can be used to obtain a meaningful
633 symbolic name or message.
634
635 @end deftypefn
636
637 @c sigsetmask.c:8
638 @deftypefn Supplemental int sigsetmask (int @var{set})
639
640 Sets the signal mask to the one provided in @var{set} and returns
641 the old mask (which, for libiberty's implementation, will always
642 be the value @code{1}).
643
644 @end deftypefn
645
646 @c spaces.c:22
647 @deftypefn Extension char* spaces (int @var{count})
648
649 Returns a pointer to a memory region filled with the specified
650 number of spaces and null terminated.  The returned pointer is
651 valid until at least the next call.
652
653 @end deftypefn
654
655 @c strcasecmp.c:15
656 @deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
657
658 A case-insensitive @code{strcmp}.
659
660 @end deftypefn
661
662 @c strchr.c:6
663 @deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
664
665 Returns a pointer to the first occurrence of the character @var{c} in
666 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
667 null character, the results are undefined.
668
669 @end deftypefn
670
671 @c strdup.c:3
672 @deftypefn Supplemental char* strdup (const char *@var{s})
673
674 Returns a pointer to a copy of @var{s} in memory obtained from
675 @code{malloc}, or @code{NULL} if insufficient memory was available.
676
677 @end deftypefn
678
679 @c strerror.c:670
680 @deftypefn Replacement {const char*} strerrno (int @var{errnum})
681
682 Given an error number returned from a system call (typically returned
683 in @code{errno}), returns a pointer to a string containing the
684 symbolic name of that error number, as found in @code{<errno.h>}.
685
686 If the supplied error number is within the valid range of indices for
687 symbolic names, but no name is available for the particular error
688 number, then returns the string @samp{Error @var{num}}, where @var{num}
689 is the error number.
690
691 If the supplied error number is not within the range of valid
692 indices, then returns @code{NULL}.
693
694 The contents of the location pointed to are only guaranteed to be
695 valid until the next call to @code{strerrno}.
696
697 @end deftypefn
698
699 @c strerror.c:602
700 @deftypefn Supplemental char* strerror (int @var{errnoval})
701
702 Maps an @code{errno} number to an error message string, the contents
703 of which are implementation defined.  On systems which have the
704 external variables @code{sys_nerr} and @code{sys_errlist}, these
705 strings will be the same as the ones used by @code{perror}.
706
707 If the supplied error number is within the valid range of indices for
708 the @code{sys_errlist}, but no message is available for the particular
709 error number, then returns the string @samp{Error @var{num}}, where
710 @var{num} is the error number.
711
712 If the supplied error number is not a valid index into
713 @code{sys_errlist}, returns @code{NULL}.
714
715 The returned string is only guaranteed to be valid only until the
716 next call to @code{strerror}.
717
718 @end deftypefn
719
720 @c strncasecmp.c:15
721 @deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
722
723 A case-insensitive @code{strncmp}.
724
725 @end deftypefn
726
727 @c strncmp.c:6
728 @deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
729
730 Compares the first @var{n} bytes of two strings, returning a value as
731 @code{strcmp}.
732
733 @end deftypefn
734
735 @c strrchr.c:6
736 @deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
737
738 Returns a pointer to the last occurrence of the character @var{c} in
739 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
740 null character, the results are undefined.
741
742 @end deftypefn
743
744 @c strsignal.c:388
745 @deftypefn Supplemental {const char *} strsignal (int @var{signo})
746
747 Maps an signal number to an signal message string, the contents of
748 which are implementation defined.  On systems which have the external
749 variable @code{sys_siglist}, these strings will be the same as the
750 ones used by @code{psignal()}.
751
752 If the supplied signal number is within the valid range of indices for
753 the @code{sys_siglist}, but no message is available for the particular
754 signal number, then returns the string @samp{Signal @var{num}}, where
755 @var{num} is the signal number.
756
757 If the supplied signal number is not a valid index into
758 @code{sys_siglist}, returns @code{NULL}.
759
760 The returned string is only guaranteed to be valid only until the next
761 call to @code{strsignal}.
762
763 @end deftypefn
764
765 @c strsignal.c:452
766 @deftypefn Extension {const char*} strsigno (int @var{signo})
767
768 Given an signal number, returns a pointer to a string containing the
769 symbolic name of that signal number, as found in @code{<signal.h>}.
770
771 If the supplied signal number is within the valid range of indices for
772 symbolic names, but no name is available for the particular signal
773 number, then returns the string @samp{Signal @var{num}}, where
774 @var{num} is the signal number.
775
776 If the supplied signal number is not within the range of valid
777 indices, then returns @code{NULL}.
778
779 The contents of the location pointed to are only guaranteed to be
780 valid until the next call to @code{strsigno}.
781
782 @end deftypefn
783
784 @c strstr.c:6
785 @deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
786
787 This function searches for the substring @var{sub} in the string
788 @var{string}, not including the terminating null characters.  A pointer
789 to the first occurrence of @var{sub} is returned, or @code{NULL} if the
790 substring is absent.  If @var{sub} points to a string with zero
791 length, the function returns @var{string}.
792
793 @end deftypefn
794
795 @c strtod.c:27
796 @deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})
797
798 This ISO C function converts the initial portion of @var{string} to a
799 @code{double}.  If @var{endptr} is not @code{NULL}, a pointer to the
800 character after the last character used in the conversion is stored in
801 the location referenced by @var{endptr}.  If no conversion is
802 performed, zero is returned and the value of @var{string} is stored in
803 the location referenced by @var{endptr}.
804
805 @end deftypefn
806
807 @c strerror.c:730
808 @deftypefn Extension int strtoerrno (const char *@var{name})
809
810 Given the symbolic name of a error number (e.g., @code{EACCES}), map it
811 to an errno value.  If no translation is found, returns 0.
812
813 @end deftypefn
814
815 @c strtol.c:33
816 @deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
817 @deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base})
818
819 The @code{strtol} function converts the string in @var{string} to a
820 long integer value according to the given @var{base}, which must be
821 between 2 and 36 inclusive, or be the special value 0.  If @var{base}
822 is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
823 to indicate bases 8 and 16, respectively, else default to base 10.
824 When the base is 16 (either explicitly or implicitly), a prefix of
825 @code{0x} is allowed.  The handling of @var{endptr} is as that of
826 @code{strtod} above.  The @code{strtoul} function is the same, except
827 that the converted value is unsigned.
828
829 @end deftypefn
830
831 @c strsignal.c:507
832 @deftypefn Extension int strtosigno (const char *@var{name})
833
834 Given the symbolic name of a signal, map it to a signal number.  If no
835 translation is found, returns 0.
836
837 @end deftypefn
838
839 @c tmpnam.c:3
840 @deftypefn Supplemental char* tmpnam (char *@var{s})
841
842 This function attempts to create a name for a temporary file, which
843 will be a valid file name yet not exist when @code{tmpnam} checks for
844 it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
845 or be @code{NULL}.  Use of this function creates a security risk, and it must
846 not be used in new projects.  Use @code{mkstemp} instead.
847
848 @end deftypefn
849
850 @c vasprintf.c:48
851 @deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args})
852
853 Like @code{vsprintf}, but instead of passing a pointer to a buffer,
854 you pass a pointer to a pointer.  This function will compute the size
855 of the buffer needed, allocate memory with @code{malloc}, and store a
856 pointer to the allocated memory in @code{*@var{resptr}}.  The value
857 returned is the same as @code{vsprintf} would return.  If memory could
858 not be allocated, zero is returned and @code{NULL} is stored in
859 @code{*@var{resptr}}.
860
861 @end deftypefn
862
863 @c vfork.c:6
864 @deftypefn Supplemental int vfork (void)
865
866 Emulates @code{vfork} by calling @code{fork} and returning its value.
867
868 @end deftypefn
869
870 @c vprintf.c:3
871 @deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
872 @deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
873 @deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})
874
875 These functions are the same as @code{printf}, @code{fprintf}, and
876 @code{sprintf}, respectively, except that they are called with a
877 @code{va_list} instead of a variable number of arguments.  Note that
878 they do not call @code{va_end}; this is the application's
879 responsibility.  In @libib{} they are implemented in terms of the
880 nonstandard but common function @code{_doprnt}.
881
882 @end deftypefn
883
884 @c waitpid.c:3
885 @deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
886
887 This is a wrapper around the @code{wait} function.  Any ``special''
888 values of @var{pid} depend on your implementation of @code{wait}, as
889 does the return value.  The third argument is unused in @libib{}.
890
891 @end deftypefn
892
893 @c xatexit.c:11
894 @deftypefun int xatexit (void (*@var{fn}) (void))
895
896 Behaves as the standard @code{atexit} function, but with no limit on
897 the number of registered functions.  Returns 0 on success, or @minus{}1 on
898 failure.  If you use @code{xatexit} to register functions, you must use
899 @code{xexit} to terminate your program.
900
901 @end deftypefun
902
903 @c xmalloc.c:38
904 @deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize})
905
906 Allocate memory without fail, and set it to zero.  This routine functions
907 like @code{calloc}, but will behave the same as @code{xmalloc} if memory
908 cannot be found.
909
910 @end deftypefn
911
912 @c xexit.c:22
913 @deftypefn Replacement void xexit (int @var{code})
914
915 Terminates the program.  If any functions have been registered with
916 the @code{xatexit} replacement function, they will be called first.
917 Termination is handled via the system's normal @code{exit} call.
918
919 @end deftypefn
920
921 @c xmalloc.c:22
922 @deftypefn Replacement void* xmalloc (size_t)
923
924 Allocate memory without fail.  If @code{malloc} fails, this will print
925 a message to @code{stderr} (using the name set by
926 @code{xmalloc_set_program_name},
927 if any) and then call @code{xexit}.  Note that it is therefore safe for
928 a program to contain @code{#define malloc xmalloc} in its source.
929
930 @end deftypefn
931
932 @c xmalloc.c:53
933 @deftypefn Replacement void xmalloc_failed (size_t)
934
935 This function is not meant to be called by client code, and is listed
936 here for completeness only.  If any of the allocation routines fail, this
937 function will be called to print an error message and terminate execution.
938
939 @end deftypefn
940
941 @c xmalloc.c:46
942 @deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
943
944 You can use this to set the name of the program used by
945 @code{xmalloc_failed} when printing a failure message.
946
947 @end deftypefn
948
949 @c xmemdup.c:7
950 @deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})
951
952 Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
953 are allocated, then @var{copy_size} bytes from @var{input} are copied into
954 it, and the new memory is returned.  If fewer bytes are copied than were
955 allocated, the remaining memory is zeroed.
956
957 @end deftypefn
958
959 @c xmalloc.c:32
960 @deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size})
961 Reallocate memory without fail.  This routine functions like @code{realloc},
962 but will behave the same as @code{xmalloc} if memory cannot be found.
963
964 @end deftypefn
965
966 @c xstrdup.c:7
967 @deftypefn Replacement char* xstrdup (const char *@var{s})
968
969 Duplicates a character string without fail, using @code{xmalloc} to
970 obtain memory.
971
972 @end deftypefn
973
974 @c xstrerror.c:7
975 @deftypefn Replacement char* xstrerror (int @var{errnum})
976
977 Behaves exactly like the standard @code{strerror} function, but
978 will never return a @code{NULL} pointer.
979
980 @end deftypefn
981
982