Daily bump.
[official-gcc.git] / libiberty / functions.texi
blobaf7760d89bef135059a058ce84eb940897dd45c4
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.
6 @c alloca.c:26
7 @deftypefn Replacement void* alloca (size_t @var{size})
9 This function allocates memory which will be automatically reclaimed
10 after the procedure exits.  The @libib{} implementation does not free
11 the memory immediately but will do so eventually during subsequent
12 calls to this function.  Memory is allocated using @code{xmalloc} under
13 normal circumstances.
15 The header file @file{alloca-conf.h} can be used in conjunction with the
16 GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make
17 available this function.  The @code{AC_FUNC_ALLOCA} test requires that
18 client code use a block of preprocessor code to be safe (see the Autoconf
19 manual for more); this header incorporates that logic and more, including
20 the possibility of a GCC built-in function.
22 @end deftypefn
24 @c asprintf.c:33
25 @deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...)
27 Like @code{sprintf}, but instead of passing a pointer to a buffer, you
28 pass a pointer to a pointer.  This function will compute the size of
29 the buffer needed, allocate memory with @code{malloc}, and store a
30 pointer to the allocated memory in @code{*@var{resptr}}.  The value
31 returned is the same as @code{sprintf} would return.  If memory could
32 not be allocated, zero is returned and @code{NULL} is stored in
33 @code{*@var{resptr}}.
35 @end deftypefn
37 @c atexit.c:6
38 @deftypefn Supplemental int atexit (void (*@var{f})())
40 Causes function @var{f} to be called at exit.  Returns 0.
42 @end deftypefn
44 @c basename.c:6
45 @deftypefn Supplemental char* basename (const char *@var{name})
47 Returns a pointer to the last component of pathname @var{name}.
48 Behavior is undefined if the pathname ends in a directory separator.
50 @end deftypefn
52 @c bcmp.c:6
53 @deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count})
55 Compares the first @var{count} bytes of two areas of memory.  Returns
56 zero if they are the same, nonzero otherwise.  Returns zero if
57 @var{count} is zero.  A nonzero result only indicates a difference,
58 it does not indicate any sorting order (say, by having a positive
59 result mean @var{x} sorts before @var{y}).
61 @end deftypefn
63 @c bcopy.c:3
64 @deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length})
66 Copies @var{length} bytes from memory region @var{in} to region
67 @var{out}.  The use of @code{bcopy} is deprecated in new programs.
69 @end deftypefn
71 @c bsearch.c:33
72 @deftypefn Supplemental void* bsearch (const void *@var{key}, const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, int (*@var{compar})(const void *, const void *))
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.
83 @end deftypefn
85 @c argv.c:139
86 @deftypefn Extension char** buildargv (char *@var{sp})
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.
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.
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.
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.
108 @end deftypefn
110 @c bzero.c:6
111 @deftypefn Supplemental void bzero (char *@var{mem}, int @var{count})
113 Zeros @var{count} bytes starting at @var{mem}.  Use of this function
114 is deprecated in favor of @code{memset}.
116 @end deftypefn
118 @c calloc.c:6
119 @deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize})
121 Uses @code{malloc} to allocate storage for @var{nelem} objects of
122 @var{elsize} bytes each, then zeros the memory.
124 @end deftypefn
126 @c choose-temp.c:42
127 @deftypefn Extension char* choose_temp_base (void)
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}.
134 This function is provided for backwards compatability only.  Its use is
135 not recommended.
137 @end deftypefn
139 @c make-temp-file.c:88
140 @deftypefn Replacement char* choose_tmpdir ()
142 Returns a pointer to a directory path suitable for creating temporary
143 files in.
145 @end deftypefn
147 @c clock.c:27
148 @deftypefn Supplemental long clock (void)
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.
154 @end deftypefn
156 @c concat.c:24
157 @deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL})
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.
164 @end deftypefn
166 @c argv.c:65
167 @deftypefn Extension char** dupargv (char **@var{vector})
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.
175 @end deftypefn
177 @c strerror.c:566
178 @deftypefn Extension int errno_max (void)
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>}.
190 We return the maximum value that can be used to obtain a meaningful
191 symbolic name or message.
193 @end deftypefn
195 @c fdmatch.c:23
196 @deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2})
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.
208 @end deftypefn
210 @c ffs.c:3
211 @deftypefn Supplemental int ffs (int @var{valu})
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.
217 @end deftypefn
219 @c fnmatch.txh:1
220 @deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags})
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{\\}.
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>}):
241 @table @code
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{/}.
248 @item FNM_NOESCAPE
249 Do not interpret backslashes as quoting the following special character.
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.
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}.
262 @item FNM_CASEFOLD
263 Ignores case when performing the comparison.
265 @end table
267 @end deftypefn
269 @c argv.c:111
270 @deftypefn Extension void freeargv (char **@var{vector})
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.
277 @end deftypefn
279 @c getruntime.c:78
280 @deftypefn Replacement long get_run_time (void)
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.
286 @end deftypefn
288 @c getcwd.c:6
289 @deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len})
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}.
299 @end deftypefn
301 @c getpagesize.c:5
302 @deftypefn Supplemental int getpagesize (void)
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.
309 @end deftypefn
311 @c getpwd.c:5
312 @deftypefn Supplemental char* getpwd (void)
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}.
318 @end deftypefn
320 @c index.c:5
321 @deftypefn Supplemental char* index (char *@var{s}, int @var{c})
323 Returns a pointer to the first occurrence of the character @var{c} in
324 the string @var{s}, or @code{NULL} if not found.  The use of @code{index} is
325 deprecated in new programs in favor of @code{strchr}.
327 @end deftypefn
329 @c insque.c:6
330 @deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred})
331 @deftypefnx Supplemental void remque (struct qelem *@var{elem})
333 Routines to manipulate queues built from doubly linked lists.  The
334 @code{insque} routine inserts @var{elem} in the queue immediately
335 after @var{pred}.  The @code{remque} routine removes @var{elem} from
336 its containing queue.  These routines expect to be passed pointers to
337 structures which have as their first members a forward pointer and a
338 back pointer, like this prototype (although no prototype is provided):
340 @example
341 struct qelem @{
342   struct qelem *q_forw;
343   struct qelem *q_back;
344   char q_data[];
346 @end example
348 @end deftypefn
350 @c lbasename.c:23
351 @deftypefn Replacement {const char*} lbasename (const char *@var{name})
353 Given a pointer to a string containing a typical pathname
354 (@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the
355 last component of the pathname (@samp{ls.c} in this case).  The
356 returned pointer is guaranteed to lie within the original
357 string.  This latter fact is not true of many vendor C
358 libraries, which return special strings or modify the passed
359 strings for particular input.
361 In particular, the empty string returns the same empty string,
362 and a path ending in @code{/} returns the empty string after it.
364 @end deftypefn
366 @c make-temp-file.c:138
367 @deftypefn Replacement char* make_temp_file (const char *@var{suffix})
369 Return a temporary file name (as a string) or @code{NULL} if unable to
370 create one.  @var{suffix} is a suffix to append to the file name.  The
371 string is @code{malloc}ed, and the temporary file has been created.
373 @end deftypefn
375 @c memchr.c:3
376 @deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n})
378 This function searches memory starting at @code{*@var{s}} for the
379 character @var{c}.  The search only ends with the first occurrence of
380 @var{c}, or after @var{length} characters; in particular, a null
381 character does not terminate the search.  If the character @var{c} is
382 found within @var{length} characters of @code{*@var{s}}, a pointer
383 to the character is returned.  If @var{c} is not found, then @code{NULL} is
384 returned.
386 @end deftypefn
388 @c memcmp.c:6
389 @deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count})
391 Compares the first @var{count} bytes of two areas of memory.  Returns
392 zero if they are the same, a value less than zero if @var{x} is
393 lexically less than @var{y}, or a value greater than zero if @var{x}
394 is lexically greater than @var{y}.  Note that lexical order is determined
395 as if comparing unsigned char arrays.
397 @end deftypefn
399 @c memcpy.c:6
400 @deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
402 Copies @var{length} bytes from memory region @var{in} to region
403 @var{out}.  Returns a pointer to @var{out}.
405 @end deftypefn
407 @c memmove.c:6
408 @deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count})
410 Copies @var{count} bytes from memory area @var{from} to memory area
411 @var{to}, returning a pointer to @var{to}.
413 @end deftypefn
415 @c memset.c:6
416 @deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count})
418 Sets the first @var{count} bytes of @var{s} to the constant byte
419 @var{c}, returning a pointer to @var{s}.
421 @end deftypefn
423 @c mkstemps.c:54
424 @deftypefn Replacement int mkstemps (char *@var{template}, int @var{suffix_len})
426 Generate a unique temporary file name from @var{template}.
427 @var{template} has the form:
429 @example
430    @var{path}/ccXXXXXX@var{suffix}
431 @end example
433 @var{suffix_len} tells us how long @var{suffix} is (it can be zero
434 length).  The last six characters of @var{template} before @var{suffix}
435 must be @samp{XXXXXX}; they are replaced with a string that makes the
436 filename unique.  Returns a file descriptor open on the file for
437 reading and writing.
439 @end deftypefn
441 @c pexecute.c:67
442 @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)
444 Executes a program.
446 @var{program} and @var{argv} are the arguments to
447 @code{execv}/@code{execvp}.
449 @var{this_pname} is name of the calling program (i.e., @code{argv[0]}).
451 @var{temp_base} is the path name, sans suffix, of a temporary file to
452 use if needed.  This is currently only needed for MS-DOS ports that
453 don't use @code{go32} (do any still exist?).  Ports that don't need it
454 can pass @code{NULL}.
456 (@code{@var{flags} & PEXECUTE_SEARCH}) is non-zero if @env{PATH} should be searched
457 (??? It's not clear that GCC passes this flag correctly).  (@code{@var{flags} &
458 PEXECUTE_FIRST}) is nonzero for the first process in chain.
459 (@code{@var{flags} & PEXECUTE_FIRST}) is nonzero for the last process
460 in chain.  The first/last flags could be simplified to only mark the
461 last of a chain of processes but that requires the caller to always
462 mark the last one (and not give up early if some error occurs).
463 It's more robust to require the caller to mark both ends of the chain.
465 The result is the pid on systems like Unix where we
466 @code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we
467 use @code{spawn}.  It is up to the caller to wait for the child.
469 The result is the @code{WEXITSTATUS} on systems like MS-DOS where we
470 @code{spawn} and wait for the child here.
472 Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the
473 text of the error message with an optional argument (if not needed,
474 @var{errmsg_arg} is set to @code{NULL}), and @minus{}1 is returned.
475 @code{errno} is available to the caller to use.
477 @end deftypefn
479 @c strsignal.c:547
480 @deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message})
482 Print @var{message} to the standard error, followed by a colon,
483 followed by the description of the signal specified by @var{signo},
484 followed by a newline.
486 @end deftypefn
488 @c putenv.c:21
489 @deftypefn Supplemental int putenv (const char *@var{string})
491 Uses @code{setenv} or @code{unsetenv} to put @var{string} into
492 the environment or remove it.  If @var{string} is of the form
493 @samp{name=value} the string is added; if no @samp{=} is present the
494 name is unset/removed.
496 @end deftypefn
498 @c pexecute.c:104
499 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
501 Waits for a program started by @code{pexecute} to finish.
503 @var{pid} is the process id of the task to wait for. @var{status} is
504 the `status' argument to wait. @var{flags} is currently unused (allows
505 future enhancement without breaking upward compatibility).  Pass 0 for now.
507 The result is the pid of the child reaped, or -1 for failure
508 (@code{errno} says why).
510 On systems that don't support waiting for a particular child, @var{pid} is
511 ignored.  On systems like MS-DOS that don't really multitask @code{pwait}
512 is just a mechanism to provide a consistent interface for the caller.
514 @end deftypefn
516 @c random.c:39
517 @deftypefn Supplement {long int} random (void)
518 @deftypefnx Supplement void srandom (unsigned int @var{seed})
519 @deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n})
520 @deftypefnx Supplement void* setstate (void *@var{arg_state})
522 Random number functions.  @code{random} returns a random number in the
523 range 0 to @code{LONG_MAX}.  @code{srandom} initializes the random
524 number generator to some starting point determined by @var{seed}
525 (else, the values returned by @code{random} are always the same for each
526 run of the program).  @code{initstate} and @code{setstate} allow fine-grained
527 control over the state of the random number generator.
529 @end deftypefn
531 @c concat.c:177
532 @deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL})
534 Same as @code{concat}, except that if @var{optr} is not @code{NULL} it
535 is freed after the string is created.  This is intended to be useful
536 when you're extending an existing string or building up a string in a
537 loop:
539 @example
540   str = reconcat (str, "pre-", str, NULL);
541 @end example
543 @end deftypefn
545 @c rename.c:6
546 @deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
548 Renames a file from @var{old} to @var{new}.  If @var{new} already
549 exists, it is removed.
551 @end deftypefn
553 @c rindex.c:5
554 @deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
556 Returns a pointer to the last occurrence of the character @var{c} in
557 the string @var{s}, or @code{NULL} if not found.  The use of @code{rindex} is
558 deprecated in new programs in favor of @code{strrchr}.
560 @end deftypefn
562 @c setenv.c:22
563 @deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
564 @deftypefnx Supplemental void unsetenv (const char *@var{name})
566 @code{setenv} adds @var{name} to the environment with value
567 @var{value}.  If the name was already present in the environment,
568 the new value will be stored only if @var{overwrite} is nonzero.
569 The companion @code{unsetenv} function removes @var{name} from the
570 environment.  This implementation is not safe for multithreaded code.
572 @end deftypefn
574 @c strsignal.c:353
575 @deftypefn Extension int signo_max (void)
577 Returns the maximum signal value for which a corresponding symbolic
578 name or message is available.  Note that in the case where we use the
579 @code{sys_siglist} supplied by the system, it is possible for there to
580 be more symbolic names than messages, or vice versa.  In fact, the
581 manual page for @code{psignal(3b)} explicitly warns that one should
582 check the size of the table (@code{NSIG}) before indexing it, since
583 new signal codes may be added to the system before they are added to
584 the table.  Thus @code{NSIG} might be smaller than value implied by
585 the largest signo value defined in @code{<signal.h>}.
587 We return the maximum value that can be used to obtain a meaningful
588 symbolic name or message.
590 @end deftypefn
592 @c sigsetmask.c:8
593 @deftypefn Supplemental int sigsetmask (int @var{set})
595 Sets the signal mask to the one provided in @var{set} and returns
596 the old mask (which, for libiberty's implementation, will always
597 be the value @code{1}).
599 @end deftypefn
601 @c spaces.c:22
602 @deftypefn Extension char* spaces (int @var{count})
604 Returns a pointer to a memory region filled with the specified
605 number of spaces and null terminated.  The returned pointer is
606 valid until at least the next call.
608 @end deftypefn
610 @c strcasecmp.c:15
611 @deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
613 A case-insensitive @code{strcmp}.
615 @end deftypefn
617 @c strchr.c:6
618 @deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
620 Returns a pointer to the first occurrence of the character @var{c} in
621 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
622 null character, the results are undefined.
624 @end deftypefn
626 @c strdup.c:3
627 @deftypefn Supplemental char* strdup (const char *@var{s})
629 Returns a pointer to a copy of @var{s} in memory obtained from
630 @code{malloc}, or @code{NULL} if insufficient memory was available.
632 @end deftypefn
634 @c strerror.c:670
635 @deftypefn Replacement {const char*} strerrno (int @var{errnum})
637 Given an error number returned from a system call (typically returned
638 in @code{errno}), returns a pointer to a string containing the
639 symbolic name of that error number, as found in @code{<errno.h>}.
641 If the supplied error number is within the valid range of indices for
642 symbolic names, but no name is available for the particular error
643 number, then returns the string @samp{Error @var{num}}, where @var{num}
644 is the error number.
646 If the supplied error number is not within the range of valid
647 indices, then returns @code{NULL}.
649 The contents of the location pointed to are only guaranteed to be
650 valid until the next call to @code{strerrno}.
652 @end deftypefn
654 @c strerror.c:602
655 @deftypefn Supplemental char* strerror (int @var{errnoval})
657 Maps an @code{errno} number to an error message string, the contents
658 of which are implementation defined.  On systems which have the
659 external variables @code{sys_nerr} and @code{sys_errlist}, these
660 strings will be the same as the ones used by @code{perror}.
662 If the supplied error number is within the valid range of indices for
663 the @code{sys_errlist}, but no message is available for the particular
664 error number, then returns the string @samp{Error @var{num}}, where
665 @var{num} is the error number.
667 If the supplied error number is not a valid index into
668 @code{sys_errlist}, returns @code{NULL}.
670 The returned string is only guaranteed to be valid only until the
671 next call to @code{strerror}.
673 @end deftypefn
675 @c strncasecmp.c:15
676 @deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
678 A case-insensitive @code{strncmp}.
680 @end deftypefn
682 @c strncmp.c:6
683 @deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
685 Compares the first @var{n} bytes of two strings, returning a value as
686 @code{strcmp}.
688 @end deftypefn
690 @c strrchr.c:6
691 @deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
693 Returns a pointer to the last occurrence of the character @var{c} in
694 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
695 null character, the results are undefined.
697 @end deftypefn
699 @c strsignal.c:388
700 @deftypefn Supplemental {const char *} strsignal (int @var{signo})
702 Maps an signal number to an signal message string, the contents of
703 which are implementation defined.  On systems which have the external
704 variable @code{sys_siglist}, these strings will be the same as the
705 ones used by @code{psignal()}.
707 If the supplied signal number is within the valid range of indices for
708 the @code{sys_siglist}, but no message is available for the particular
709 signal number, then returns the string @samp{Signal @var{num}}, where
710 @var{num} is the signal number.
712 If the supplied signal number is not a valid index into
713 @code{sys_siglist}, returns @code{NULL}.
715 The returned string is only guaranteed to be valid only until the next
716 call to @code{strsignal}.
718 @end deftypefn
720 @c strsignal.c:452
721 @deftypefn Extension {const char*} strsigno (int @var{signo})
723 Given an signal number, returns a pointer to a string containing the
724 symbolic name of that signal number, as found in @code{<signal.h>}.
726 If the supplied signal number is within the valid range of indices for
727 symbolic names, but no name is available for the particular signal
728 number, then returns the string @samp{Signal @var{num}}, where
729 @var{num} is the signal number.
731 If the supplied signal number is not within the range of valid
732 indices, then returns @code{NULL}.
734 The contents of the location pointed to are only guaranteed to be
735 valid until the next call to @code{strsigno}.
737 @end deftypefn
739 @c strstr.c:6
740 @deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
742 This function searches for the substring @var{sub} in the string
743 @var{string}, not including the terminating null characters.  A pointer
744 to the first occurrence of @var{sub} is returned, or @code{NULL} if the
745 substring is absent.  If @var{sub} points to a string with zero
746 length, the function returns @var{string}.
748 @end deftypefn
750 @c strtod.c:27
751 @deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})
753 This ISO C function converts the initial portion of @var{string} to a
754 @code{double}.  If @var{endptr} is not @code{NULL}, a pointer to the
755 character after the last character used in the conversion is stored in
756 the location referenced by @var{endptr}.  If no conversion is
757 performed, zero is returned and the value of @var{string} is stored in
758 the location referenced by @var{endptr}.
760 @end deftypefn
762 @c strerror.c:730
763 @deftypefn Extension int strtoerrno (const char *@var{name})
765 Given the symbolic name of a error number (e.g., @code{EACCES}), map it
766 to an errno value.  If no translation is found, returns 0.
768 @end deftypefn
770 @c strtol.c:33
771 @deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
772 @deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base})
774 The @code{strtol} function converts the string in @var{string} to a
775 long integer value according to the given @var{base}, which must be
776 between 2 and 36 inclusive, or be the special value 0.  If @var{base}
777 is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
778 to indicate bases 8 and 16, respectively, else default to base 10.
779 When the base is 16 (either explicitly or implicitly), a prefix of
780 @code{0x} is allowed.  The handling of @var{endptr} is as that of
781 @code{strtod} above.  The @code{strtoul} function is the same, except
782 that the converted value is unsigned.
784 @end deftypefn
786 @c strsignal.c:507
787 @deftypefn Extension int strtosigno (const char *@var{name})
789 Given the symbolic name of a signal, map it to a signal number.  If no
790 translation is found, returns 0.
792 @end deftypefn
794 @c tmpnam.c:3
795 @deftypefn Supplemental char* tmpnam (char *@var{s})
797 This function attempts to create a name for a temporary file, which
798 will be a valid file name yet not exist when @code{tmpnam} checks for
799 it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
800 or be @code{NULL}.  Use of this function creates a security risk, and it must
801 not be used in new projects.  Use @code{mkstemp} instead.
803 @end deftypefn
805 @c vasprintf.c:48
806 @deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args})
808 Like @code{vsprintf}, but instead of passing a pointer to a buffer,
809 you pass a pointer to a pointer.  This function will compute the size
810 of the buffer needed, allocate memory with @code{malloc}, and store a
811 pointer to the allocated memory in @code{*@var{resptr}}.  The value
812 returned is the same as @code{vsprintf} would return.  If memory could
813 not be allocated, zero is returned and @code{NULL} is stored in
814 @code{*@var{resptr}}.
816 @end deftypefn
818 @c vfork.c:6
819 @deftypefn Supplemental int vfork (void)
821 Emulates @code{vfork} by calling @code{fork} and returning its value.
823 @end deftypefn
825 @c vprintf.c:3
826 @deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
827 @deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
828 @deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})
830 These functions are the same as @code{printf}, @code{fprintf}, and
831 @code{sprintf}, respectively, except that they are called with a
832 @code{va_list} instead of a variable number of arguments.  Note that
833 they do not call @code{va_end}; this is the application's
834 responsibility.  In @libib{} they are implemented in terms of the
835 nonstandard but common function @code{_doprnt}.
837 @end deftypefn
839 @c waitpid.c:3
840 @deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
842 This is a wrapper around the @code{wait} function.  Any ``special''
843 values of @var{pid} depend on your implementation of @code{wait}, as
844 does the return value.  The third argument is unused in @libib{}.
846 @end deftypefn
848 @c xatexit.c:11
849 @deftypefun int xatexit (void (*@var{fn}) (void))
851 Behaves as the standard @code{atexit} function, but with no limit on
852 the number of registered functions.  Returns 0 on success, or @minus{}1 on
853 failure.  If you use @code{xatexit} to register functions, you must use
854 @code{xexit} to terminate your program.
856 @end deftypefun
858 @c xmalloc.c:38
859 @deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize})
861 Allocate memory without fail, and set it to zero.  This routine functions
862 like @code{calloc}, but will behave the same as @code{xmalloc} if memory
863 cannot be found.
865 @end deftypefn
867 @c xexit.c:22
868 @deftypefn Replacement void xexit (int @var{code})
870 Terminates the program.  If any functions have been registered with
871 the @code{xatexit} replacement function, they will be called first.
872 Termination is handled via the system's normal @code{exit} call.
874 @end deftypefn
876 @c xmalloc.c:22
877 @deftypefn Replacement void* xmalloc (size_t)
879 Allocate memory without fail.  If @code{malloc} fails, this will print
880 a message to @code{stderr} (using the name set by
881 @code{xmalloc_set_program_name},
882 if any) and then call @code{xexit}.  Note that it is therefore safe for
883 a program to contain @code{#define malloc xmalloc} in its source.
885 @end deftypefn
887 @c xmalloc.c:53
888 @deftypefn Replacement void xmalloc_failed (size_t)
890 This function is not meant to be called by client code, and is listed
891 here for completeness only.  If any of the allocation routines fail, this
892 function will be called to print an error message and terminate execution.
894 @end deftypefn
896 @c xmalloc.c:46
897 @deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
899 You can use this to set the name of the program used by
900 @code{xmalloc_failed} when printing a failure message.
902 @end deftypefn
904 @c xmemdup.c:7
905 @deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})
907 Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
908 are allocated, then @var{copy_size} bytes from @var{input} are copied into
909 it, and the new memory is returned.  If fewer bytes are copied than were
910 allocated, the remaining memory is zeroed.
912 @end deftypefn
914 @c xmalloc.c:32
915 @deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size})
916 Reallocate memory without fail.  This routine functions like @code{realloc},
917 but will behave the same as @code{xmalloc} if memory cannot be found.
919 @end deftypefn
921 @c xstrdup.c:7
922 @deftypefn Replacement char* xstrdup (const char *@var{s})
924 Duplicates a character string without fail, using @code{xmalloc} to
925 obtain memory.
927 @end deftypefn
929 @c xstrerror.c:7
930 @deftypefn Replacement char* xstrerror (int @var{errnum})
932 Behaves exactly like the standard @code{strerror} function, but
933 will never return a @code{NULL} pointer.
935 @end deftypefn