aboutsummaryrefslogtreecommitdiff
path: root/libiberty/functions.texi
diff options
context:
space:
mode:
Diffstat (limited to 'libiberty/functions.texi')
-rw-r--r--libiberty/functions.texi515
1 files changed, 515 insertions, 0 deletions
diff --git a/libiberty/functions.texi b/libiberty/functions.texi
new file mode 100644
index 0000000..e2ea020
--- /dev/null
+++ b/libiberty/functions.texi
@@ -0,0 +1,515 @@
+@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 respecitively 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 if 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 occurance 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 occurance 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 occurance 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 NUM"}, where 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 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 NUM"}, where 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 occurance 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 NUL characters. A pointer
+to the first occurance 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 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 funtions. 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:37
+@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} rpelacement 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 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:52
+@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:45
+@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:31
+@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
+
+