OSDN Git Service

f914adb436b0b358fce1a9729232449415eda09d
[pf3gnuchains/gcc-fork.git] / libiberty / functions.texi
1 @c Automatically generated from *.c and others (the comments before
2 @c each entry tell you which file and where in that file).  DO NOT EDIT!
3 @c Edit the *.c files, configure with --enable-maintainer-mode,
4 @c and let gather-docs build you a new copy.
5
6 @c alloca.c:26
7 @deftypefn Replacement void* alloca (size_t)
8
9 This function allocates memory which will be automatically reclaimed
10 after the procedure exits.  The @libib{} implementation does not free
11 the memory immediately but will do so eventually during subsequent
12 calls to this function.  Memory is allocated using @code{xmalloc} under
13 normal circumstances.
14
15 The header file @file{alloca-conf.h} can be used in conjunction with the
16 GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make
17 available this function.  The @code{AC_FUNC_ALLOCA} test requires that
18 client code use a block of preprocessor code to be safe (see the Autoconf
19 manual for more); this header incorporates that logic and more, including
20 the possibility of a GCC builtin function.
21
22 @end deftypefn
23
24 @c atexit.c:6
25 @deftypefn Supplemental int atexit (void (*@var{f})())
26
27 Causes function @var{f} to be called at exit.  Returns 0.
28
29 @end deftypefn
30
31 @c basename.c:6
32 @deftypefn Supplemental char* basename (const char *@var{name})
33
34 Returns a pointer to the last component of pathname @var{name}.
35 Behavior is undefined if the pathname ends in a directory separator.
36
37 @end deftypefn
38
39 @c bcmp.c:6
40 @deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count})
41
42 Compares the first @var{count} bytes of two areas of memory.  Returns
43 zero if they are the same, non-zero otherwise.  Returns zero if
44 @var{count} is zero.  A non-zero result only indicates a difference,
45 it does not indicate any sorting order (say, by having a positive
46 result mean @var{x} sorts before @var{y}).
47
48 @end deftypefn
49
50 @c bcopy.c:3
51 @deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length})
52
53 Copies @var{length} bytes from memory region @var{in} to region
54 @var{out}.  The use of @code{bcopy} is deprecated in new programs.
55
56 @end deftypefn
57
58 @c bsearch.c:33
59 @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 *))
60
61 Performs a search over an array of @var{nmemb} elements pointed to by
62 @var{base} for a member that matches the object pointed to by @var{key}.
63 The size of each member is specified by @var{size}.  The array contents
64 should be sorted in ascending order according to the @var{compar}
65 comparison function.  This routine should take two arguments pointing to
66 the @var{key} and to an array member, in that order, and should return an
67 integer less than, equal to, or greater than zero if the @var{key} object
68 is respectively less than, matching, or greater than the array member.
69
70 @end deftypefn
71
72 @c bzero.c:6
73 @deftypefn Supplemental void bzero (char *@var{mem}, int @var{count})
74
75 Zeros @var{count} bytes starting at @var{mem}.  Use of this function
76 is deprecated in favor of @code{memset}.
77
78 @end deftypefn
79
80 @c calloc.c:6
81 @deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize})
82
83 Uses @code{malloc} to allocate storage for @var{nelem} objects of
84 @var{elsize} bytes each, then zeros the memory.
85
86 @end deftypefn
87
88 @c clock.c:27
89 @deftypefn Supplemental long clock ()
90
91 Returns an approximation of the CPU time used by the process as a
92 @code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the
93 number of seconds used.
94
95 @end deftypefn
96
97 @c strerror.c:566
98 @deftypefn Replacement int errno_max (void)
99
100 Returns the maximum @code{errno} value for which a corresponding
101 symbolic name or message is available.  Note that in the case where we
102 use the @code{sys_errlist} supplied by the system, it is possible for
103 there to be more symbolic names than messages, or vice versa.  In
104 fact, the manual page for @code{perror(3C)} explicitly warns that one
105 should check the size of the table (@code{sys_nerr}) before indexing
106 it, since new error codes may be added to the system before they are
107 added to the table.  Thus @code{sys_nerr} might be smaller than value
108 implied by the largest @code{errno} value defined in @file{errno.h}.
109
110 We return the maximum value that can be used to obtain a meaningful
111 symbolic name or message.
112
113 @end deftypefn
114
115 @c getcwd.c:6
116 @deftypefn Supplemental char* getcwd (char *@var{pathname}, @var{len})
117
118 Copy the absolute pathname for the current working directory into
119 @var{pathname}, which is assumed to point to a buffer of at least
120 @var{len} bytes, and return a pointer to the buffer.  If the current
121 directory's path doesn't fit in @var{len} characters, the result is
122 NULL and @var{errno} is set.  If @var{pathname} is a null pointer,
123 @code{getcwd} will obtain @var{len} bytes of space using
124 @code{malloc}.
125
126 @end deftypefn
127
128 @c getpagesize.c:5
129 @deftypefn Supplemental int getpagesize ()
130
131 Returns the number of bytes in a page of memory.  This is the
132 granularity of many of the system memory management routines.  No
133 guarantee is made as to whether or not it is the same as the basic
134 memory management hardware page size.
135
136 @end deftypefn
137
138 @c getpwd.c:5
139 @deftypefn Supplemental char* getpwd ()
140
141 Returns the current working directory.  This implementation caches the
142 result on the assumption that the process will not call @code{chdir}
143 between calls to @code{getpwd}.
144
145 @end deftypefn
146
147 @c index.c:5
148 @deftypefn Supplemental char* index (char *@var{s}, int @var{c})
149
150 Returns a pointer to the first occurance of the character @var{c} in
151 the string @var{s}, or NULL if not found.  The use of @code{index} is
152 deprecated in new programs in favor of @code{strchr}.
153
154 @end deftypefn
155
156 @c memchr.c:3
157 @deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n})
158
159 This function searches memory starting at @code{*}@var{src} for the
160 character @var{c}.  The search only ends with the first occurrence of
161 @var{c}, or after @var{length} characters; in particular, a null
162 character does not terminate the search.  If the character @var{c} is
163 found within @var{length} characters of @code{*}@var{src}, a pointer
164 to the character is returned. If @var{c} is not found, then NULL is
165 returned.
166
167 @end deftypefn
168
169 @c memcmp.c:6
170 @deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count})
171
172 Compares the first @var{count} bytes of two areas of memory.  Returns
173 zero if they are the same, a value less than zero if @var{x} is
174 lexically less than @var{y}, or a value greater than zero if @var{x}
175 is lexically greater than @var{y}.  Note that lexical order is determined
176 as if comparing unsigned char arrays.
177
178 @end deftypefn
179
180 @c memcpy.c:6
181 @deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
182
183 Copies @var{length} bytes from memory region @var{in} to region
184 @var{out}.  Returns a pointer to @var{out}.
185
186 @end deftypefn
187
188 @c memmove.c:6
189 @deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count})
190
191 Copies @var{count} bytes from memory area @var{from} to memory area
192 @var{to}, returning a pointer to @var{to}.
193
194 @end deftypefn
195
196 @c memset.c:6
197 @deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count})
198
199 Sets the first @var{count} bytes of @var{s} to the constant byte
200 @var{c}, returning a pointer to @var{s}.
201
202 @end deftypefn
203
204 @c putenv.c:21
205 @deftypefn Supplemental int putenv (const char *@var{string})
206
207 Uses @code{setenv} or @code{unsetenv} to put @var{string} into
208 the environment or remove it.  If @var{string} is of the form
209 @samp{name=value} the string is added; if no `=' is present the
210 name is unset/removed.
211
212 @end deftypefn
213
214 @c rename.c:6
215 @deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
216
217 Renames a file from @var{old} to @var{new}.  If @var{new} already
218 exists, it is removed.
219
220 @end deftypefn
221
222 @c rindex.c:5
223 @deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
224
225 Returns a pointer to the last occurance of the character @var{c} in
226 the string @var{s}, or NULL if not found.  The use of @code{rindex} is
227 deprecated in new programs in favor of @code{strrchr}.
228
229 @end deftypefn
230
231 @c setenv.c:22
232 @deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
233 @deftypefnx Supplemental void unsetenv (const char *@var{name})
234
235 @code{setenv} adds @var{name} to the environment with value
236 @var{value}.  If the name was already present in the environment,
237 the new value will be stored only if @var{overwrite} is non-zero.
238 The companion @code{unsetenv} function removes @var{name} from the
239 environment.  This implementation is not safe for multithreaded code.
240
241 @end deftypefn
242
243 @c sigsetmask.c:8
244 @deftypefn Supplemental int sigsetmask (int @var{set})
245
246 Sets the signal mask to the one provided in @var{set} and returns
247 the old mask (which, for libiberty's implementation, will always
248 be the value @code{1}).
249
250 @end deftypefn
251
252 @c strcasecmp.c:15
253 @deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
254
255 A case-insensitive @code{strcmp}.
256
257 @end deftypefn
258
259 @c strchr.c:6
260 @deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
261
262 Returns a pointer to the first occurance of the character @var{c} in
263 the string @var{s}, or NULL if not found.  If @var{c} is itself the
264 null character, the results are undefined.
265
266 @end deftypefn
267
268 @c strdup.c:3
269 @deftypefn Supplemental char* strdup (const char *@var{s})
270
271 Returns a pointer to a copy of @var{s} in memory obtained from
272 @code{malloc}, or NULL if insufficient memory was available.
273
274 @end deftypefn
275
276 @c strerror.c:670
277 @deftypefn Replacement const char* strerrno (int @var{errnum})
278
279 Given an error number returned from a system call (typically returned
280 in @code{errno}), returns a pointer to a string containing the
281 symbolic name of that error number, as found in @file{errno.h}.
282
283 If the supplied error number is within the valid range of indices for
284 symbolic names, but no name is available for the particular error
285 number, then returns the string @samp{"Error NUM"}, where NUM is the
286 error number.
287
288 If the supplied error number is not within the range of valid
289 indices, then returns NULL.
290
291 The contents of the location pointed to are only guaranteed to be
292 valid until the next call to strerrno.
293
294 @end deftypefn
295
296 @c strerror.c:602
297 @deftypefn Replacement char* strerror (int @var{errnoval})
298
299 Maps an @code{errno} number to an error message string, the contents
300 of which are implementation defined.  On systems which have the
301 external variables @code{sys_nerr} and @code{sys_errlist}, these
302 strings will be the same as the ones used by @code{perror}.
303
304 If the supplied error number is within the valid range of indices for
305 the @code{sys_errlist}, but no message is available for the particular
306 error number, then returns the string @samp{"Error NUM"}, where NUM is
307 the error number.
308
309 If the supplied error number is not a valid index into
310 @code{sys_errlist}, returns NULL.
311
312 The returned string is only guaranteed to be valid only until the
313 next call to @code{strerror}.
314
315 @end deftypefn
316
317 @c strncasecmp.c:15
318 @deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
319
320 A case-insensitive @code{strncmp}.
321
322 @end deftypefn
323
324 @c strncmp.c:6
325 @deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
326
327 Compares the first @var{n} bytes of two strings, returning a value as
328 @code{strcmp}.
329
330 @end deftypefn
331
332 @c strrchr.c:6
333 @deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
334
335 Returns a pointer to the last occurance of the character @var{c} in
336 the string @var{s}, or NULL if not found.  If @var{c} is itself the
337 null character, the results are undefined.
338
339 @end deftypefn
340
341 @c strstr.c:6
342 @deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
343
344 This function searches for the substring @var{sub} in the string
345 @var{string}, not including the terminating NUL characters.  A pointer
346 to the first occurance of @var{sub} is returned, or NULL if the
347 substring is absent.  If @var{sub} points to a string with zero
348 length, the function returns @var{string}.
349
350 @end deftypefn
351
352 @c strtod.c:27
353 @deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})
354
355 This ANSI C function converts the initial portion of @var{string} to a
356 @code{double}.  If @var{endptr} is not NULL, a pointer to the
357 character after the last character used in the conversion is stored in
358 the location referenced by @var{endptr}.  If no conversion is
359 performed, zero is returned and the value of @var{string} is stored in
360 the location referenced by @var{endptr}.
361
362 @end deftypefn
363
364 @c strerror.c:730
365 @deftypefn Replacement int strtoerrno (const char *@var{name})
366
367 Given the symbolic name of a error number (e.g., @code{EACCESS}), map it
368 to an errno value.  If no translation is found, returns 0.
369
370 @end deftypefn
371
372 @c strtol.c:33
373 @deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
374
375 The @code{strtol} function converts the string in @var{string} to a
376 long integer value according to the given @var{base}, which must be
377 between 2 and 36 inclusive, or be the special value 0.  If @var{base}
378 is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
379 to indicate bases 8 and 16, respectively, else default to base 10.
380 When the base is 16 (either explicitly or implicitly), a prefix of
381 @code{0x} is allowed.  The handling of endptr is as that of
382 @code{strtod} above.
383
384 @end deftypefn
385
386 @c tmpnam.c:3
387 @deftypefn Supplemental char* tmpnam (char *@var{s})
388
389 This function attempts to create a name for a temporary file, which
390 will be a valid file name yet not exist when @code{tmpnam} checks for
391 it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
392 or be NULL.  Use of this function creates a security risk, and it must
393 not be used in new projects.  Use @code{mkstemp} instead.
394
395 @end deftypefn
396
397 @c vfork.c:6
398 @deftypefn Supplemental int vfork ()
399
400 Emulates @code{vfork} by calling @code{fork} and returning its value.
401
402 @end deftypefn
403
404 @c vprintf.c:3
405 @deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
406 @deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
407 @deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})
408
409 These functions are the same as @code{printf}, @code{fprintf}, and
410 @code{sprintf}, respectively, except that they are called with a
411 @code{va_list} instead of a variable number of arguments.  Note that
412 they do not call @code{va_end}; this is the application's
413 responsibility.  In @libib{} they are implemented in terms of the
414 nonstandard but common function @code{_doprnt}.
415
416 @end deftypefn
417
418 @c waitpid.c:3
419 @deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
420
421 This is a wrapper around the @code{wait} function.  Any ``special''
422 values of @var{pid} depend on your implementation of @code{wait}, as
423 does the return value.  The third argument is unused in @libib{}.
424
425 @end deftypefn
426
427 @c xatexit.c:11
428 @deftypefun int xatexit (void (*@var{fn}) (void))
429
430 Behaves as the standard @code{atexit} function, but with no limit on
431 the number of registered funtions.  Returns 0 on success, or -1 on
432 failure.  If you use @code{xatexit} to register functions, you must use
433 @code{xexit} to terminate your program.
434
435 @end deftypefun
436
437 @c xmalloc.c:37
438 @deftypefn Replacement void* xcalloc (size_t, size_t)
439
440 Allocate memory without fail, and set it to zero.  This routine functions
441 like @code{calloc}, but will behave the same as @code{xmalloc} if memory
442 cannot be found.
443
444 @end deftypefn
445
446 @c xexit.c:22
447 @deftypefn Replacement void xexit (int @var{code})
448
449 Terminates the program.  If any functions have been registered with
450 the @code{xatexit} rpelacement function, they will be called first.
451 Termination is handled via the system's normal @code{exit} call.
452
453 @end deftypefn
454
455 @c xmalloc.c:22
456 @deftypefn Replacement void* xmalloc (size_t)
457
458 Allocate memory without fail.  If @code{malloc} fails, this will print
459 a message to stderr (using the name set by @code{xmalloc_set_program_name},
460 if any) and then call @code{xexit}.  Note that it is therefore safe for
461 a program to contain @code{#define malloc xmalloc} in its source.
462
463 @end deftypefn
464
465 @c xmalloc.c:52
466 @deftypefn Replacement void xmalloc_failed (size_t)
467
468 This function is not meant to be called by client code, and is listed
469 here for completeness only.  If any of the allocation routines fail, this
470 function will be called to print an error message and terminate execution.
471
472 @end deftypefn
473
474 @c xmalloc.c:45
475 @deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
476
477 You can use this to set the name of the program used by
478 @code{xmalloc_failed} when printing a failure message.
479
480 @end deftypefn
481
482 @c xmemdup.c:7
483 @deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})
484
485 Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
486 are allocated, then @var{copy_size} bytes from @var{input} are copied into
487 it, and the new memory is returned.  If fewer bytes are copied than were
488 allocated, the remaining memory is zeroed.
489
490 @end deftypefn
491
492 @c xmalloc.c:31
493 @deftypefn Replacement void* xrealloc (void*, size_t)
494 Reallocate memory without fail.  This routine functions like @code{realloc},
495 but will behave the same as @code{xmalloc} if memory cannot be found.
496
497 @end deftypefn
498
499 @c xstrdup.c:7
500 @deftypefn Replacement char* xstrdup (const char *@var{s})
501
502 Duplicates a character string without fail, using @code{xmalloc} to
503 obtain memory.
504
505 @end deftypefn
506
507 @c xstrerror.c:7
508 @deftypefn Replacement char* xstrerror (int @var{errnum})
509
510 Behaves exactly like the standard @code{strerror} function, but
511 will never return a NULL pointer.
512
513 @end deftypefn
514
515