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