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