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