OSDN Git Service

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