summaryrefslogtreecommitdiff
path: root/libiberty/functions.texi
blob: c00d047dfa8054b3b047315b530a1add2f9a525a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
@c Automatically generated from *.c and others (the comments before
@c each entry tell you which file and where in that file).  DO NOT EDIT!
@c Edit the *.c files, configure with --enable-maintainer-mode,
@c and let gather-docs build you a new copy.

@c alloca.c:26
@deftypefn Replacement void* alloca (size_t)

This function allocates memory which will be automatically reclaimed
after the procedure exits.  The @libib{} implementation does not free
the memory immediately but will do so eventually during subsequent
calls to this function.  Memory is allocated using @code{xmalloc} under
normal circumstances.

The header file @file{alloca-conf.h} can be used in conjunction with the
GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make
available this function.  The @code{AC_FUNC_ALLOCA} test requires that
client code use a block of preprocessor code to be safe (see the Autoconf
manual for more); this header incorporates that logic and more, including
the possibility of a GCC builtin function.

@end deftypefn

@c atexit.c:6
@deftypefn Supplemental int atexit (void (*@var{f})())

Causes function @var{f} to be called at exit.  Returns 0.

@end deftypefn

@c basename.c:6
@deftypefn Supplemental char* basename (const char *@var{name})

Returns a pointer to the last component of pathname @var{name}.
Behavior is undefined if the pathname ends in a directory separator.

@end deftypefn

@c bcmp.c:6
@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count})

Compares the first @var{count} bytes of two areas of memory.  Returns
zero if they are the same, non-zero otherwise.  Returns zero if
@var{count} is zero.  A non-zero result only indicates a difference,
it does not indicate any sorting order (say, by having a positive
result mean @var{x} sorts before @var{y}).

@end deftypefn

@c bcopy.c:3
@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length})

Copies @var{length} bytes from memory region @var{in} to region
@var{out}.  The use of @code{bcopy} is deprecated in new programs.

@end deftypefn

@c bsearch.c:33
@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 *))

Performs a search over an array of @var{nmemb} elements pointed to by
@var{base} for a member that matches the object pointed to by @var{key}.
The size of each member is specified by @var{size}.  The array contents
should be sorted in ascending order according to the @var{compar}
comparison function.  This routine should take two arguments pointing to
the @var{key} and to an array member, in that order, and should return an
integer less than, equal to, or greater than zero if the @var{key} object
is respectively less than, matching, or greater than the array member.

@end deftypefn

@c bzero.c:6
@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count})

Zeros @var{count} bytes starting at @var{mem}.  Use of this function
is deprecated in favor of @code{memset}.

@end deftypefn

@c calloc.c:6
@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize})

Uses @code{malloc} to allocate storage for @var{nelem} objects of
@var{elsize} bytes each, then zeros the memory.

@end deftypefn

@c clock.c:27
@deftypefn Supplemental long clock ()

Returns an approximation of the CPU time used by the process as a
@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the
number of seconds used.

@end deftypefn

@c strerror.c:566
@deftypefn Replacement int errno_max (void)

Returns the maximum @code{errno} value for which a corresponding
symbolic name or message is available.  Note that in the case where we
use the @code{sys_errlist} supplied by the system, it is possible for
there to be more symbolic names than messages, or vice versa.  In
fact, the manual page for @code{perror(3C)} explicitly warns that one
should check the size of the table (@code{sys_nerr}) before indexing
it, since new error codes may be added to the system before they are
added to the table.  Thus @code{sys_nerr} might be smaller than value
implied by the largest @code{errno} value defined in @file{errno.h}.

We return the maximum value that can be used to obtain a meaningful
symbolic name or message.

@end deftypefn

@c getcwd.c:6
@deftypefn Supplemental char* getcwd (char *@var{pathname}, @var{len})

Copy the absolute pathname for the current working directory into
@var{pathname}, which is assumed to point to a buffer of at least
@var{len} bytes, and return a pointer to the buffer.  If the current
directory's path doesn't fit in @var{len} characters, the result is
NULL and @var{errno} is set.  If @var{pathname} is a null pointer,
@code{getcwd} will obtain @var{len} bytes of space using
@code{malloc}.

@end deftypefn

@c getpagesize.c:5
@deftypefn Supplemental int getpagesize ()

Returns the number of bytes in a page of memory.  This is the
granularity of many of the system memory management routines.  No
guarantee is made as to whether or not it is the same as the basic
memory management hardware page size.

@end deftypefn

@c getpwd.c:5
@deftypefn Supplemental char* getpwd ()

Returns the current working directory.  This implementation caches the
result on the assumption that the process will not call @code{chdir}
between calls to @code{getpwd}.

@end deftypefn

@c index.c:5
@deftypefn Supplemental char* index (char *@var{s}, int @var{c})

Returns a pointer to the first occurrence of the character @var{c} in
the string @var{s}, or NULL if not found.  The use of @code{index} is
deprecated in new programs in favor of @code{strchr}.

@end deftypefn

@c memchr.c:3
@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n})

This function searches memory starting at @code{*}@var{src} for the
character @var{c}.  The search only ends with the first occurrence of
@var{c}, or after @var{length} characters; in particular, a null
character does not terminate the search.  If the character @var{c} is
found within @var{length} characters of @code{*}@var{src}, a pointer
to the character is returned. If @var{c} is not found, then NULL is
returned.

@end deftypefn

@c memcmp.c:6
@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count})

Compares the first @var{count} bytes of two areas of memory.  Returns
zero if they are the same, a value less than zero if @var{x} is
lexically less than @var{y}, or a value greater than zero if @var{x}
is lexically greater than @var{y}.  Note that lexical order is determined
as if comparing unsigned char arrays.

@end deftypefn

@c memcpy.c:6
@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length})

Copies @var{length} bytes from memory region @var{in} to region
@var{out}.  Returns a pointer to @var{out}.

@end deftypefn

@c memmove.c:6
@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count})

Copies @var{count} bytes from memory area @var{from} to memory area
@var{to}, returning a pointer to @var{to}.

@end deftypefn

@c memset.c:6
@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count})

Sets the first @var{count} bytes of @var{s} to the constant byte
@var{c}, returning a pointer to @var{s}.

@end deftypefn

@c putenv.c:21
@deftypefn Supplemental int putenv (const char *@var{string})

Uses @code{setenv} or @code{unsetenv} to put @var{string} into
the environment or remove it.  If @var{string} is of the form
@samp{name=value} the string is added; if no `=' is present the
name is unset/removed.

@end deftypefn

@c rename.c:6
@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})

Renames a file from @var{old} to @var{new}.  If @var{new} already
exists, it is removed.

@end deftypefn

@c rindex.c:5
@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})

Returns a pointer to the last occurrence of the character @var{c} in
the string @var{s}, or NULL if not found.  The use of @code{rindex} is
deprecated in new programs in favor of @code{strrchr}.

@end deftypefn

@c setenv.c:22
@deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
@deftypefnx Supplemental void unsetenv (const char *@var{name})

@code{setenv} adds @var{name} to the environment with value
@var{value}.  If the name was already present in the environment,
the new value will be stored only if @var{overwrite} is non-zero.
The companion @code{unsetenv} function removes @var{name} from the
environment.  This implementation is not safe for multithreaded code.

@end deftypefn

@c sigsetmask.c:8
@deftypefn Supplemental int sigsetmask (int @var{set})

Sets the signal mask to the one provided in @var{set} and returns
the old mask (which, for libiberty's implementation, will always
be the value @code{1}).

@end deftypefn

@c strcasecmp.c:15
@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})

A case-insensitive @code{strcmp}.

@end deftypefn

@c strchr.c:6
@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})

Returns a pointer to the first occurrence of the character @var{c} in
the string @var{s}, or NULL if not found.  If @var{c} is itself the
null character, the results are undefined.

@end deftypefn

@c strdup.c:3
@deftypefn Supplemental char* strdup (const char *@var{s})

Returns a pointer to a copy of @var{s} in memory obtained from
@code{malloc}, or NULL if insufficient memory was available.

@end deftypefn

@c strerror.c:670
@deftypefn Replacement const char* strerrno (int @var{errnum})

Given an error number returned from a system call (typically returned
in @code{errno}), returns a pointer to a string containing the
symbolic name of that error number, as found in @file{errno.h}.

If the supplied error number is within the valid range of indices for
symbolic names, but no name is available for the particular error
number, then returns the string @samp{"Error @var{num}"}, where @var{num}
is the error number.

If the supplied error number is not within the range of valid
indices, then returns NULL.

The contents of the location pointed to are only guaranteed to be
valid until the next call to @code{strerrno}.

@end deftypefn

@c strerror.c:602
@deftypefn Replacement char* strerror (int @var{errnoval})

Maps an @code{errno} number to an error message string, the contents
of which are implementation defined.  On systems which have the
external variables @code{sys_nerr} and @code{sys_errlist}, these
strings will be the same as the ones used by @code{perror}.

If the supplied error number is within the valid range of indices for
the @code{sys_errlist}, but no message is available for the particular
error number, then returns the string @samp{"Error @var{num}"}, where
@var{num} is the error number.

If the supplied error number is not a valid index into
@code{sys_errlist}, returns NULL.

The returned string is only guaranteed to be valid only until the
next call to @code{strerror}.

@end deftypefn

@c strncasecmp.c:15
@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})

A case-insensitive @code{strncmp}.

@end deftypefn

@c strncmp.c:6
@deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})

Compares the first @var{n} bytes of two strings, returning a value as
@code{strcmp}.

@end deftypefn

@c strrchr.c:6
@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})

Returns a pointer to the last occurrence of the character @var{c} in
the string @var{s}, or NULL if not found.  If @var{c} is itself the
null character, the results are undefined.

@end deftypefn

@c strstr.c:6
@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})

This function searches for the substring @var{sub} in the string
@var{string}, not including the terminating null characters.  A pointer
to the first occurrence of @var{sub} is returned, or NULL if the
substring is absent.  If @var{sub} points to a string with zero
length, the function returns @var{string}.

@end deftypefn

@c strtod.c:27
@deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})

This ANSI C function converts the initial portion of @var{string} to a
@code{double}.  If @var{endptr} is not NULL, a pointer to the
character after the last character used in the conversion is stored in
the location referenced by @var{endptr}.  If no conversion is
performed, zero is returned and the value of @var{string} is stored in
the location referenced by @var{endptr}.

@end deftypefn

@c strerror.c:730
@deftypefn Replacement int strtoerrno (const char *@var{name})

Given the symbolic name of a error number (e.g., @code{EACCESS}), map it
to an errno value.  If no translation is found, returns 0.

@end deftypefn

@c strtol.c:33
@deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})

The @code{strtol} function converts the string in @var{string} to a
long integer value according to the given @var{base}, which must be
between 2 and 36 inclusive, or be the special value 0.  If @var{base}
is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
to indicate bases 8 and 16, respectively, else default to base 10.
When the base is 16 (either explicitly or implicitly), a prefix of
@code{0x} is allowed.  The handling of @var{endptr} is as that of
@code{strtod} above.

@end deftypefn

@c tmpnam.c:3
@deftypefn Supplemental char* tmpnam (char *@var{s})

This function attempts to create a name for a temporary file, which
will be a valid file name yet not exist when @code{tmpnam} checks for
it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
or be NULL.  Use of this function creates a security risk, and it must
not be used in new projects.  Use @code{mkstemp} instead.

@end deftypefn

@c vfork.c:6
@deftypefn Supplemental int vfork ()

Emulates @code{vfork} by calling @code{fork} and returning its value.

@end deftypefn

@c vprintf.c:3
@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
@deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})

These functions are the same as @code{printf}, @code{fprintf}, and
@code{sprintf}, respectively, except that they are called with a
@code{va_list} instead of a variable number of arguments.  Note that
they do not call @code{va_end}; this is the application's
responsibility.  In @libib{} they are implemented in terms of the
nonstandard but common function @code{_doprnt}.

@end deftypefn

@c waitpid.c:3
@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)

This is a wrapper around the @code{wait} function.  Any ``special''
values of @var{pid} depend on your implementation of @code{wait}, as
does the return value.  The third argument is unused in @libib{}.

@end deftypefn

@c xatexit.c:11
@deftypefun int xatexit (void (*@var{fn}) (void))

Behaves as the standard @code{atexit} function, but with no limit on
the number of registered functions.  Returns 0 on success, or -1 on
failure.  If you use @code{xatexit} to register functions, you must use
@code{xexit} to terminate your program.

@end deftypefun

@c xmalloc.c:38
@deftypefn Replacement void* xcalloc (size_t, size_t)

Allocate memory without fail, and set it to zero.  This routine functions
like @code{calloc}, but will behave the same as @code{xmalloc} if memory
cannot be found.

@end deftypefn

@c xexit.c:22
@deftypefn Replacement void xexit (int @var{code})

Terminates the program.  If any functions have been registered with
the @code{xatexit} replacement function, they will be called first.
Termination is handled via the system's normal @code{exit} call.

@end deftypefn

@c xmalloc.c:22
@deftypefn Replacement void* xmalloc (size_t)

Allocate memory without fail.  If @code{malloc} fails, this will print
a message to @code{stderr} (using the name set by
@code{xmalloc_set_program_name},
if any) and then call @code{xexit}.  Note that it is therefore safe for
a program to contain @code{#define malloc xmalloc} in its source.

@end deftypefn

@c xmalloc.c:53
@deftypefn Replacement void xmalloc_failed (size_t)

This function is not meant to be called by client code, and is listed
here for completeness only.  If any of the allocation routines fail, this
function will be called to print an error message and terminate execution.

@end deftypefn

@c xmalloc.c:46
@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})

You can use this to set the name of the program used by
@code{xmalloc_failed} when printing a failure message.

@end deftypefn

@c xmemdup.c:7
@deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})

Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
are allocated, then @var{copy_size} bytes from @var{input} are copied into
it, and the new memory is returned.  If fewer bytes are copied than were
allocated, the remaining memory is zeroed.

@end deftypefn

@c xmalloc.c:32
@deftypefn Replacement void* xrealloc (void*, size_t)
Reallocate memory without fail.  This routine functions like @code{realloc},
but will behave the same as @code{xmalloc} if memory cannot be found.

@end deftypefn

@c xstrdup.c:7
@deftypefn Replacement char* xstrdup (const char *@var{s})

Duplicates a character string without fail, using @code{xmalloc} to
obtain memory.

@end deftypefn

@c xstrerror.c:7
@deftypefn Replacement char* xstrerror (int @var{errnum})

Behaves exactly like the standard @code{strerror} function, but
will never return a NULL pointer.

@end deftypefn