* hppa.h (ldwa, ldda): Add ordered opcodes.
[binutils.git] / libiberty / functions.texi
blob18b2480a78157486f90404ca1553b339694cb44b
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:82
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 hex.c:25
321 @deftypefn Extension void hex_init (void)
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.
328 @end deftypefn
330 @c hex.c:34
331 @deftypefn Extension int hex_p (int @var{c})
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.
337 @end deftypefn
339 @c hex.c:42
340 @deftypefn Extension int hex_value (int @var{c})
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.
347 @end deftypefn
349 @c index.c:5
350 @deftypefn Supplemental char* index (char *@var{s}, int @var{c})
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}.
356 @end deftypefn
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})
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):
369 @example
370 struct qelem @{
371   struct qelem *q_forw;
372   struct qelem *q_back;
373   char q_data[];
375 @end example
377 @end deftypefn
379 @c lbasename.c:23
380 @deftypefn Replacement {const char*} lbasename (const char *@var{name})
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.
390 In particular, the empty string returns the same empty string,
391 and a path ending in @code{/} returns the empty string after it.
393 @end deftypefn
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})
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}.
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/}.
406 The return value is normally allocated via @code{malloc}.  If no relative prefix
407 can be found, return @code{NULL}.
409 @end deftypefn
411 @c make-temp-file.c:138
412 @deftypefn Replacement char* make_temp_file (const char *@var{suffix})
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.
418 @end deftypefn
420 @c memchr.c:3
421 @deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n})
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.
431 @end deftypefn
433 @c memcmp.c:6
434 @deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count})
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.
442 @end deftypefn
444 @c memcpy.c:6
445 @deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
447 Copies @var{length} bytes from memory region @var{in} to region
448 @var{out}.  Returns a pointer to @var{out}.
450 @end deftypefn
452 @c memmove.c:6
453 @deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count})
455 Copies @var{count} bytes from memory area @var{from} to memory area
456 @var{to}, returning a pointer to @var{to}.
458 @end deftypefn
460 @c memset.c:6
461 @deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count})
463 Sets the first @var{count} bytes of @var{s} to the constant byte
464 @var{c}, returning a pointer to @var{s}.
466 @end deftypefn
468 @c mkstemps.c:54
469 @deftypefn Replacement int mkstemps (char *@var{template}, int @var{suffix_len})
471 Generate a unique temporary file name from @var{template}.
472 @var{template} has the form:
474 @example
475    @var{path}/ccXXXXXX@var{suffix}
476 @end example
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.
484 @end deftypefn
486 @c pexecute.txh:1
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)
489 Executes a program.
491 @var{program} and @var{argv} are the arguments to
492 @code{execv}/@code{execvp}.
494 @var{this_pname} is name of the calling program (i.e., @code{argv[0]}).
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}.
501 (@code{@var{flags} & PEXECUTE_SEARCH}) is non-zero if @env{PATH}
502 should be searched (??? It's not clear that GCC passes this flag
503 correctly).  (@code{@var{flags} & PEXECUTE_FIRST}) is nonzero for the
504 first process in chain.  (@code{@var{flags} & PEXECUTE_FIRST}) is
505 nonzero for the last process in chain.  The first/last flags could be
506 simplified to only mark the last of a chain of processes but that
507 requires the caller to always mark the last one (and not give up
508 early if some error occurs).  It's more robust to require the caller
509 to mark both ends of the chain.
511 The result is the pid on systems like Unix where we
512 @code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we
513 use @code{spawn}.  It is up to the caller to wait for the child.
515 The result is the @code{WEXITSTATUS} on systems like MS-DOS where we
516 @code{spawn} and wait for the child here.
518 Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the
519 text of the error message with an optional argument (if not needed,
520 @var{errmsg_arg} is set to @code{NULL}), and @minus{}1 is returned.
521 @code{errno} is available to the caller to use.
523 @end deftypefn
525 @c strsignal.c:547
526 @deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message})
528 Print @var{message} to the standard error, followed by a colon,
529 followed by the description of the signal specified by @var{signo},
530 followed by a newline.
532 @end deftypefn
534 @c putenv.c:21
535 @deftypefn Supplemental int putenv (const char *@var{string})
537 Uses @code{setenv} or @code{unsetenv} to put @var{string} into
538 the environment or remove it.  If @var{string} is of the form
539 @samp{name=value} the string is added; if no @samp{=} is present the
540 name is unset/removed.
542 @end deftypefn
544 @c pexecute.txh:39
545 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
547 Waits for a program started by @code{pexecute} to finish.
549 @var{pid} is the process id of the task to wait for. @var{status} is
550 the `status' argument to wait. @var{flags} is currently unused
551 (allows future enhancement without breaking upward compatibility).
552 Pass 0 for now.
554 The result is the pid of the child reaped, or -1 for failure
555 (@code{errno} says why).
557 On systems that don't support waiting for a particular child,
558 @var{pid} is ignored.  On systems like MS-DOS that don't really
559 multitask @code{pwait} is just a mechanism to provide a consistent
560 interface for the caller.
562 @end deftypefn
564 @c random.c:39
565 @deftypefn Supplement {long int} random (void)
566 @deftypefnx Supplement void srandom (unsigned int @var{seed})
567 @deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n})
568 @deftypefnx Supplement void* setstate (void *@var{arg_state})
570 Random number functions.  @code{random} returns a random number in the
571 range 0 to @code{LONG_MAX}.  @code{srandom} initializes the random
572 number generator to some starting point determined by @var{seed}
573 (else, the values returned by @code{random} are always the same for each
574 run of the program).  @code{initstate} and @code{setstate} allow fine-grained
575 control over the state of the random number generator.
577 @end deftypefn
579 @c concat.c:177
580 @deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL})
582 Same as @code{concat}, except that if @var{optr} is not @code{NULL} it
583 is freed after the string is created.  This is intended to be useful
584 when you're extending an existing string or building up a string in a
585 loop:
587 @example
588   str = reconcat (str, "pre-", str, NULL);
589 @end example
591 @end deftypefn
593 @c rename.c:6
594 @deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
596 Renames a file from @var{old} to @var{new}.  If @var{new} already
597 exists, it is removed.
599 @end deftypefn
601 @c rindex.c:5
602 @deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
604 Returns a pointer to the last occurrence of the character @var{c} in
605 the string @var{s}, or @code{NULL} if not found.  The use of @code{rindex} is
606 deprecated in new programs in favor of @code{strrchr}.
608 @end deftypefn
610 @c setenv.c:22
611 @deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
612 @deftypefnx Supplemental void unsetenv (const char *@var{name})
614 @code{setenv} adds @var{name} to the environment with value
615 @var{value}.  If the name was already present in the environment,
616 the new value will be stored only if @var{overwrite} is nonzero.
617 The companion @code{unsetenv} function removes @var{name} from the
618 environment.  This implementation is not safe for multithreaded code.
620 @end deftypefn
622 @c strsignal.c:353
623 @deftypefn Extension int signo_max (void)
625 Returns the maximum signal value for which a corresponding symbolic
626 name or message is available.  Note that in the case where we use the
627 @code{sys_siglist} supplied by the system, it is possible for there to
628 be more symbolic names than messages, or vice versa.  In fact, the
629 manual page for @code{psignal(3b)} explicitly warns that one should
630 check the size of the table (@code{NSIG}) before indexing it, since
631 new signal codes may be added to the system before they are added to
632 the table.  Thus @code{NSIG} might be smaller than value implied by
633 the largest signo value defined in @code{<signal.h>}.
635 We return the maximum value that can be used to obtain a meaningful
636 symbolic name or message.
638 @end deftypefn
640 @c sigsetmask.c:8
641 @deftypefn Supplemental int sigsetmask (int @var{set})
643 Sets the signal mask to the one provided in @var{set} and returns
644 the old mask (which, for libiberty's implementation, will always
645 be the value @code{1}).
647 @end deftypefn
649 @c spaces.c:22
650 @deftypefn Extension char* spaces (int @var{count})
652 Returns a pointer to a memory region filled with the specified
653 number of spaces and null terminated.  The returned pointer is
654 valid until at least the next call.
656 @end deftypefn
658 @c strcasecmp.c:15
659 @deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
661 A case-insensitive @code{strcmp}.
663 @end deftypefn
665 @c strchr.c:6
666 @deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
668 Returns a pointer to the first occurrence of the character @var{c} in
669 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
670 null character, the results are undefined.
672 @end deftypefn
674 @c strdup.c:3
675 @deftypefn Supplemental char* strdup (const char *@var{s})
677 Returns a pointer to a copy of @var{s} in memory obtained from
678 @code{malloc}, or @code{NULL} if insufficient memory was available.
680 @end deftypefn
682 @c strerror.c:670
683 @deftypefn Replacement {const char*} strerrno (int @var{errnum})
685 Given an error number returned from a system call (typically returned
686 in @code{errno}), returns a pointer to a string containing the
687 symbolic name of that error number, as found in @code{<errno.h>}.
689 If the supplied error number is within the valid range of indices for
690 symbolic names, but no name is available for the particular error
691 number, then returns the string @samp{Error @var{num}}, where @var{num}
692 is the error number.
694 If the supplied error number is not within the range of valid
695 indices, then returns @code{NULL}.
697 The contents of the location pointed to are only guaranteed to be
698 valid until the next call to @code{strerrno}.
700 @end deftypefn
702 @c strerror.c:602
703 @deftypefn Supplemental char* strerror (int @var{errnoval})
705 Maps an @code{errno} number to an error message string, the contents
706 of which are implementation defined.  On systems which have the
707 external variables @code{sys_nerr} and @code{sys_errlist}, these
708 strings will be the same as the ones used by @code{perror}.
710 If the supplied error number is within the valid range of indices for
711 the @code{sys_errlist}, but no message is available for the particular
712 error number, then returns the string @samp{Error @var{num}}, where
713 @var{num} is the error number.
715 If the supplied error number is not a valid index into
716 @code{sys_errlist}, returns @code{NULL}.
718 The returned string is only guaranteed to be valid only until the
719 next call to @code{strerror}.
721 @end deftypefn
723 @c strncasecmp.c:15
724 @deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
726 A case-insensitive @code{strncmp}.
728 @end deftypefn
730 @c strncmp.c:6
731 @deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
733 Compares the first @var{n} bytes of two strings, returning a value as
734 @code{strcmp}.
736 @end deftypefn
738 @c strrchr.c:6
739 @deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
741 Returns a pointer to the last occurrence of the character @var{c} in
742 the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
743 null character, the results are undefined.
745 @end deftypefn
747 @c strsignal.c:388
748 @deftypefn Supplemental {const char *} strsignal (int @var{signo})
750 Maps an signal number to an signal message string, the contents of
751 which are implementation defined.  On systems which have the external
752 variable @code{sys_siglist}, these strings will be the same as the
753 ones used by @code{psignal()}.
755 If the supplied signal number is within the valid range of indices for
756 the @code{sys_siglist}, but no message is available for the particular
757 signal number, then returns the string @samp{Signal @var{num}}, where
758 @var{num} is the signal number.
760 If the supplied signal number is not a valid index into
761 @code{sys_siglist}, returns @code{NULL}.
763 The returned string is only guaranteed to be valid only until the next
764 call to @code{strsignal}.
766 @end deftypefn
768 @c strsignal.c:452
769 @deftypefn Extension {const char*} strsigno (int @var{signo})
771 Given an signal number, returns a pointer to a string containing the
772 symbolic name of that signal number, as found in @code{<signal.h>}.
774 If the supplied signal number is within the valid range of indices for
775 symbolic names, but no name is available for the particular signal
776 number, then returns the string @samp{Signal @var{num}}, where
777 @var{num} is the signal number.
779 If the supplied signal number is not within the range of valid
780 indices, then returns @code{NULL}.
782 The contents of the location pointed to are only guaranteed to be
783 valid until the next call to @code{strsigno}.
785 @end deftypefn
787 @c strstr.c:6
788 @deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
790 This function searches for the substring @var{sub} in the string
791 @var{string}, not including the terminating null characters.  A pointer
792 to the first occurrence of @var{sub} is returned, or @code{NULL} if the
793 substring is absent.  If @var{sub} points to a string with zero
794 length, the function returns @var{string}.
796 @end deftypefn
798 @c strtod.c:27
799 @deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})
801 This ISO C function converts the initial portion of @var{string} to a
802 @code{double}.  If @var{endptr} is not @code{NULL}, a pointer to the
803 character after the last character used in the conversion is stored in
804 the location referenced by @var{endptr}.  If no conversion is
805 performed, zero is returned and the value of @var{string} is stored in
806 the location referenced by @var{endptr}.
808 @end deftypefn
810 @c strerror.c:730
811 @deftypefn Extension int strtoerrno (const char *@var{name})
813 Given the symbolic name of a error number (e.g., @code{EACCES}), map it
814 to an errno value.  If no translation is found, returns 0.
816 @end deftypefn
818 @c strtol.c:33
819 @deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
820 @deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base})
822 The @code{strtol} function converts the string in @var{string} to a
823 long integer value according to the given @var{base}, which must be
824 between 2 and 36 inclusive, or be the special value 0.  If @var{base}
825 is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
826 to indicate bases 8 and 16, respectively, else default to base 10.
827 When the base is 16 (either explicitly or implicitly), a prefix of
828 @code{0x} is allowed.  The handling of @var{endptr} is as that of
829 @code{strtod} above.  The @code{strtoul} function is the same, except
830 that the converted value is unsigned.
832 @end deftypefn
834 @c strsignal.c:507
835 @deftypefn Extension int strtosigno (const char *@var{name})
837 Given the symbolic name of a signal, map it to a signal number.  If no
838 translation is found, returns 0.
840 @end deftypefn
842 @c tmpnam.c:3
843 @deftypefn Supplemental char* tmpnam (char *@var{s})
845 This function attempts to create a name for a temporary file, which
846 will be a valid file name yet not exist when @code{tmpnam} checks for
847 it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
848 or be @code{NULL}.  Use of this function creates a security risk, and it must
849 not be used in new projects.  Use @code{mkstemp} instead.
851 @end deftypefn
853 @c vasprintf.c:48
854 @deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args})
856 Like @code{vsprintf}, but instead of passing a pointer to a buffer,
857 you pass a pointer to a pointer.  This function will compute the size
858 of the buffer needed, allocate memory with @code{malloc}, and store a
859 pointer to the allocated memory in @code{*@var{resptr}}.  The value
860 returned is the same as @code{vsprintf} would return.  If memory could
861 not be allocated, zero is returned and @code{NULL} is stored in
862 @code{*@var{resptr}}.
864 @end deftypefn
866 @c vfork.c:6
867 @deftypefn Supplemental int vfork (void)
869 Emulates @code{vfork} by calling @code{fork} and returning its value.
871 @end deftypefn
873 @c vprintf.c:3
874 @deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
875 @deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
876 @deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})
878 These functions are the same as @code{printf}, @code{fprintf}, and
879 @code{sprintf}, respectively, except that they are called with a
880 @code{va_list} instead of a variable number of arguments.  Note that
881 they do not call @code{va_end}; this is the application's
882 responsibility.  In @libib{} they are implemented in terms of the
883 nonstandard but common function @code{_doprnt}.
885 @end deftypefn
887 @c waitpid.c:3
888 @deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
890 This is a wrapper around the @code{wait} function.  Any ``special''
891 values of @var{pid} depend on your implementation of @code{wait}, as
892 does the return value.  The third argument is unused in @libib{}.
894 @end deftypefn
896 @c xatexit.c:11
897 @deftypefun int xatexit (void (*@var{fn}) (void))
899 Behaves as the standard @code{atexit} function, but with no limit on
900 the number of registered functions.  Returns 0 on success, or @minus{}1 on
901 failure.  If you use @code{xatexit} to register functions, you must use
902 @code{xexit} to terminate your program.
904 @end deftypefun
906 @c xmalloc.c:38
907 @deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize})
909 Allocate memory without fail, and set it to zero.  This routine functions
910 like @code{calloc}, but will behave the same as @code{xmalloc} if memory
911 cannot be found.
913 @end deftypefn
915 @c xexit.c:22
916 @deftypefn Replacement void xexit (int @var{code})
918 Terminates the program.  If any functions have been registered with
919 the @code{xatexit} replacement function, they will be called first.
920 Termination is handled via the system's normal @code{exit} call.
922 @end deftypefn
924 @c xmalloc.c:22
925 @deftypefn Replacement void* xmalloc (size_t)
927 Allocate memory without fail.  If @code{malloc} fails, this will print
928 a message to @code{stderr} (using the name set by
929 @code{xmalloc_set_program_name},
930 if any) and then call @code{xexit}.  Note that it is therefore safe for
931 a program to contain @code{#define malloc xmalloc} in its source.
933 @end deftypefn
935 @c xmalloc.c:53
936 @deftypefn Replacement void xmalloc_failed (size_t)
938 This function is not meant to be called by client code, and is listed
939 here for completeness only.  If any of the allocation routines fail, this
940 function will be called to print an error message and terminate execution.
942 @end deftypefn
944 @c xmalloc.c:46
945 @deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
947 You can use this to set the name of the program used by
948 @code{xmalloc_failed} when printing a failure message.
950 @end deftypefn
952 @c xmemdup.c:7
953 @deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})
955 Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
956 are allocated, then @var{copy_size} bytes from @var{input} are copied into
957 it, and the new memory is returned.  If fewer bytes are copied than were
958 allocated, the remaining memory is zeroed.
960 @end deftypefn
962 @c xmalloc.c:32
963 @deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size})
964 Reallocate memory without fail.  This routine functions like @code{realloc},
965 but will behave the same as @code{xmalloc} if memory cannot be found.
967 @end deftypefn
969 @c xstrdup.c:7
970 @deftypefn Replacement char* xstrdup (const char *@var{s})
972 Duplicates a character string without fail, using @code{xmalloc} to
973 obtain memory.
975 @end deftypefn
977 @c xstrerror.c:7
978 @deftypefn Replacement char* xstrerror (int @var{errnum})
980 Behaves exactly like the standard @code{strerror} function, but
981 will never return a @code{NULL} pointer.
983 @end deftypefn