diff options
Diffstat (limited to 'libiberty/functions.texi')
| -rw-r--r-- | libiberty/functions.texi | 435 |
1 files changed, 428 insertions, 7 deletions
diff --git a/libiberty/functions.texi b/libiberty/functions.texi index 59df233..6668ce3 100644 --- a/libiberty/functions.texi +++ b/libiberty/functions.texi @@ -21,6 +21,19 @@ the possibility of a GCC built-in function. @end deftypefn +@c asprintf.c:33 +@deftypefn Extension int asprintf (char **@var{resptr}, char *@var{format}, ...) + +Like @code{sprintf}, but instead of passing a pointer to a buffer, you +pass a pointer to a pointer. This function will compute the size of +the buffer needed, allocate memory with @code{malloc}, and store a +pointer to the allocated memory in @code{*@var{resptr}}. The value +returned is the same as @code{sprintf} would return. If memory could +not be allocated, zero is returned and @code{NULL} is stored in +@code{*@var{resptr}}. + +@end deftypefn + @c atexit.c:6 @deftypefn Supplemental int atexit (void (*@var{f})()) @@ -69,6 +82,31 @@ is respectively less than, matching, or greater than the array member. @end deftypefn +@c argv.c:139 +@deftypefn Extension char** buildargv (char *@var{sp}) + +Given a pointer to a string, parse the string extracting fields +separated by whitespace and optionally enclosed within either single +or double quotes (which are stripped off), and build a vector of +pointers to copies of the string for each field. The input string +remains unchanged. The last element of the vector is followed by a +@code{NULL} element. + +All of the memory for the pointer array and copies of the string +is obtained from @code{malloc}. All of the memory can be returned to the +system with the single function call @code{freeargv}, which takes the +returned result of @code{buildargv}, as it's argument. + +Returns a pointer to the argument vector if successful. Returns +@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient +memory to complete building the argument vector. + +If the input is a null string (as opposed to a @code{NULL} pointer), +then buildarg returns an argument vector that has one arg, a null +string. + +@end deftypefn + @c bzero.c:6 @deftypefn Supplemental void bzero (char *@var{mem}, int @var{count}) @@ -85,6 +123,27 @@ Uses @code{malloc} to allocate storage for @var{nelem} objects of @end deftypefn +@c choose-temp.c:42 +@deftypefn Extension char* choose_temp_base () + +Return a prefix for temporary file names or @code{NULL} if unable to +find one. The current directory is chosen if all else fails so the +program is exited if a temporary directory can't be found (@code{mktemp} +fails). The buffer for the result is obtained with @code{xmalloc}. + +This function is provided for backwards compatability only. Its use is +not recommended. + +@end deftypefn + +@c make-temp-file.c:88 +@deftypefn Replacement char* choose_tmpdir () + +Returns a pointer to a directory path suitable for creating temporary +files in. + +@end deftypefn + @c clock.c:27 @deftypefn Supplemental long clock (void) @@ -94,8 +153,29 @@ number of seconds used. @end deftypefn +@c concat.c:24 +@deftypefn Extension char* concat (char *@var{s1}, char *@var{s2}, ..., @code{NULL}) + +Concatenate zero or more of strings and return the result in freshly +xmalloc'd memory. Returns @code{NULL} if insufficient memory is +available. The argument list is terminated by the first @code{NULL} +pointer encountered. Pointers to empty strings are ignored. + +@end deftypefn + +@c argv.c:65 +@deftypefn Extension char** dupargv (char **@var{vector}) + +Duplicate an argument vector. Simply scans through @var{vector}, +duplicating each argument until the terminating @code{NULL} is found. +Returns a pointer to the argument vector if successful. Returns +@code{NULL} if there is insufficient memory to complete building the +argument vector. + +@end deftypefn + @c strerror.c:566 -@deftypefn Replacement int errno_max (void) +@deftypefn Extension 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 @@ -112,6 +192,99 @@ symbolic name or message. @end deftypefn +@c fdmatch.c:23 +@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2}) + +Check to see if two open file descriptors refer to the same file. +This is useful, for example, when we have an open file descriptor for +an unnamed file, and the name of a file that we believe to correspond +to that fd. This can happen when we are exec'd with an already open +file (@code{stdout} for example) or from the SVR4 @file{/proc} calls +that return open file descriptors for mapped address spaces. All we +have to do is open the file by name and check the two file descriptors +for a match, which is done by comparing major and minor device numbers +and inode numbers. + +@end deftypefn + +@c ffs.c:3 +@deftypefn Supplemental int ffs (int @var{valu}) + +Find the first (least significant) bit set in @var{valu}. Bits are +numbered from right to left, starting with bit 1 (corresponding to the +value 1). If @var{valu} is zero, zero is returned. + +@end deftypefn + +@c fnmatch.txh:1 +@deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags}) + +Matches @var{string} against @var{pattern}, returning zero if it +matches, @code{FNM_NOMATCH} if not. @var{pattern} may contain the +wildcards @code{?} to match any one character, @code{*} to match any +zero or more characters, or a set of alternate characters in square +brackets, like @samp{[a-gt8]}, which match one character (@code{a} +through @code{g}, or @code{t}, or @code{8}, in this example) if that one +character is in the set. A set may be inverted (i.e. match anything +except what's in the set) by giving @code{^} or @code{!} as the first +character in the set. To include those characters in the set, list them +as anything other than the first character of the set. To include a +dash in the set, list it last in the set. A backslash character makes +the following character not special, so for example you could match +against a literal asterisk with @samp{\*}. To match a literal +backslash, use @samp{\\}. + +@code{flags} controls various aspects of the matching process, and is a +boolean OR of zero or more of the following values (defined in +@code{<fnmatch.h>}: + +@table @code + +@item FNM_PATHNAME +@itemx FNM_FILE_NAME +@var{string} is assumed to be a path name. No wildcard will ever match +@code{/}. + +@item FNM_NOESCAPE +Do not interpret backslashes as quoting the following special character. + +@item FNM_PERIOD +A leading period (at the beginning of @var{string}, or if +@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or +@code{?} but must be matched explicitly. + +@item FNM_LEADING_DIR +Means that @var{string} also matches @var{pattern} if some initial part +of @var{string} matches, and is followed by @code{/} and zero or more +characters. For example, @samp{foo*} would match either @samp{foobar} +or @samp{foobar/grill}. + +@item FNM_CASEFOLD +Ignores case when performing the comparison. + +@end table + +@end deftypefn + +@c argv.c:111 +@deftypefn Extension void freeargv (char **@var{vector}) + +Free an argument vector that was built using @code{buildargv}. Simply +scans through @var{vector}, freeing the memory for each argument until +the terminating @code{NULL} is found, and then frees @var{vector} +itself. + +@end deftypefn + +@c getruntime.c:78 +@deftypefn Replacement long get_run_time () + +Returns the time used so far, in microseconds. If possible, this is +the time used by this process, else it is the elapsed time since the +process started. + +@end deftypefn + @c getcwd.c:6 @deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len}) @@ -153,6 +326,52 @@ deprecated in new programs in favor of @code{strchr}. @end deftypefn +@c insque.c:6 +@deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred}) +@deftypefnx Supplemental void remque (struct qelem *@var{elem}) + +Routines to manipulate queues built from doubly linked lists. The +@code{insque} routine inserts @var{elem} in the queue immediately +after @var{pred}. The @code{remque} routine removes @var{elem} from +its containing queue. These routines expect to be passed pointers to +structures which have as their first members a forward pointer and a +back pointer, like this prototype (although no prototype is provided): + +@example +struct qelem @{ + struct qelem *q_forw; + struct qelem *q_back; + char q_data[]; +@}; +@end example + +@end deftypefn + +@c lbasename.c:23 +@deftypefn Replacement {const char*} lbasename (const char *@var{name}) + +Given a pointer to a string containing a typical pathname +(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the +last component of the pathname (@samp{ls.c} in this case). The +returned pointer is guaranteed to lie within the original +string. This latter fact is not true of many vendor C +libraries, which return special strings or modify the passed +strings for particular input. + +In particular, the empty string returns the same empty string, +and a path ending in @code{/} returns the empty string after it. + +@end deftypefn + +@c make-temp-file.c:138 +@deftypefn Replacement char* make_temp_file (const char *@var{suffix}) + +Return a temporary file name (as a string) or @code{NULL} if unable to +create one. @var{suffix} is a suffix to append to the file name. The +string is malloced, and the temporary file has been created. + +@end deftypefn + @c memchr.c:3 @deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n}) @@ -201,6 +420,71 @@ Sets the first @var{count} bytes of @var{s} to the constant byte @end deftypefn +@c mkstemps.c:54 +@deftypefn Replacement int mkstemps (char *@var{template}, int @var{suffix_len}) + +Generate a unique temporary file name from @var{template}. +@var{template} has the form: + +@example + <path>/ccXXXXXX<suffix> +@end example + +@var{suffix_len} tells us how long <suffix> is (it can be zero +length). The last six characters of @var{template} before <suffix> +must be @code{XXXXXX}; they are replaced with a string that makes the +filename unique. Returns a file descriptor open on the file for +reading and writing. + +@end deftypefn + +@c pexecute.c:67 +@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) + +Executes a program. + +@var{program} and @var{argv} are the arguments to +@code{execv}/@code{execvp}. + +@var{this_pname} is name of the calling program (i.e. @code{argv[0]}). + +@var{temp_base} is the path name, sans suffix, of a temporary file to +use if needed. This is currently only needed for MS-DOS ports that +don't use @code{go32} (do any still exist?). Ports that don't need it +can pass @code{NULL}. + +(@var{flags} & @code{PEXECUTE_SEARCH}) is non-zero if @code{$PATH} should be searched +(??? It's not clear that GCC passes this flag correctly). (@var{flags} & +@code{PEXECUTE_FIRST}) is nonzero for the first process in chain. +(@var{flags} & @code{PEXECUTE_FIRST}) is nonzero for the last process +in chain. The first/last flags could be simplified to only mark the +last of a chain of processes but that requires the caller to always +mark the last one (and not give up early if some error occurs). +It's more robust to require the caller to mark both ends of the chain. + +The result is the pid on systems like Unix where we +@code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we +use @code{spawn}. It is up to the caller to wait for the child. + +The result is the WEXITSTATUS on systems like MS-DOS where we +@code{spawn} and wait for the child here. + +Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the +text of the error message with an optional argument (if not needed, +@var{errmsg_arg} is set to @code{NULL}), and -1 is returned. +@code{errno} is available to the caller to use. + +@end deftypefn + +@c strsignal.c:547 +@deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message}) + +Print @var{message} to the standard error, followed by a colon, +followed by the description of the signal specified by @var{signo}, +followed by a newline. + +@end deftypefn + @c putenv.c:21 @deftypefn Supplemental int putenv (const char *@var{string}) @@ -211,6 +495,53 @@ name is unset/removed. @end deftypefn +@c pexecute.c:104 +@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) + +Waits for a program started by @code{pexecute} to finish. + +@var{pid} is the process id of the task to wait for. @var{status} is +the `status' argument to wait. @var{flags} is currently unused (allows +future enhancement without breaking upward compatibility). Pass 0 for now. + +The result is the pid of the child reaped, or -1 for failure +(@code{errno} says why). + +On systems that don't support waiting for a particular child, @var{pid} is +ignored. On systems like MS-DOS that don't really multitask @code{pwait} +is just a mechanism to provide a consistent interface for the caller. + +@end deftypefn + +@c random.c:39 +@deftypefn Supplement {long int} random () +@deftypefnx Supplement void srandom (unsigned int @var{seed}) +@deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n}) +@deftypefnx Supplement void* setstate (void *@var{arg_state}) + +Random number functions. @code{random} returns a random number in the +range @code{0..LONG_MAX}. @code{srandom} initializes the random +number generator to some starting point determined by @var{seed} +(else, the values returned by @code{random} are always the same for each +run of the program). @code{initstate} and @code{setstate} allow fine-grain +control over the state of the random number generator. + +@end deftypefn + +@c concat.c:177 +@deftypefn Extension char* reconcat (char *@var{optr}, char *@var{s1}, ..., @code{NULL}) + +Same as @code{concat}, except that if @var{optr} is not @code{NULL} it +is freed after the string is created. This is intended to be useful +when you're extending an existing string or building up a string in a +loop: + +@example + str = reconcat (str, "pre-", str, NULL); +@end example + +@end deftypefn + @c rename.c:6 @deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new}) @@ -240,6 +571,24 @@ environment. This implementation is not safe for multithreaded code. @end deftypefn +@c strsignal.c:353 +@deftypefn Extension int signo_max () + +Returns the maximum signal value for which a corresponding symbolic +name or message is available. Note that in the case where we use the +@code{sys_siglist} 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{psignal(3b)} explicitly warns that one should +check the size of the table (@code{NSIG}) before indexing it, since +new signal codes may be added to the system before they are added to +the table. Thus @code{NSIG} might be smaller than value implied by +the largest signo value defined in @code{<signal.h>}. + +We return the maximum value that can be used to obtain a meaningful +symbolic name or message. + +@end deftypefn + @c sigsetmask.c:8 @deftypefn Supplemental int sigsetmask (int @var{set}) @@ -249,6 +598,15 @@ be the value @code{1}). @end deftypefn +@c spaces.c:22 +@deftypefn Extension char* spaces (int @var{count}) + +Returns a pointer to a memory region filled with the specified +number of spaces and null terminated. The returned pointer is +valid until at least the next call. + +@end deftypefn + @c strcasecmp.c:15 @deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2}) @@ -274,7 +632,7 @@ Returns a pointer to a copy of @var{s} in memory obtained from @end deftypefn @c strerror.c:670 -@deftypefn Replacement const char* strerrno (int @var{errnum}) +@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 @@ -282,7 +640,7 @@ symbolic name of that error number, as found in @code{<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} +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 @@ -294,7 +652,7 @@ valid until the next call to @code{strerrno}. @end deftypefn @c strerror.c:602 -@deftypefn Replacement char* strerror (int @var{errnoval}) +@deftypefn Supplemental 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 @@ -303,7 +661,7 @@ 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 +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 @@ -338,6 +696,46 @@ null character, the results are undefined. @end deftypefn +@c strsignal.c:388 +@deftypefn Supplemental {const char *} strsignal (int @var{signo}) + +Maps an signal number to an signal message string, the contents of +which are implementation defined. On systems which have the external +variable @code{sys_siglist}, these strings will be the same as the +ones used by @code{psignal()}. + +If the supplied signal number is within the valid range of indices for +the @code{sys_siglist}, but no message is available for the particular +signal number, then returns the string @samp{Signal @var{num}}, where +@var{num} is the signal number. + +If the supplied signal number is not a valid index into +@code{sys_siglist}, returns @code{NULL}. + +The returned string is only guaranteed to be valid only until the next +call to @code{strsignal}. + +@end deftypefn + +@c strsignal.c:452 +@deftypefn Extension {const char*} strsigno (int @var{signo}) + +Given an signal number, returns a pointer to a string containing the +symbolic name of that signal number, as found in @code{<signal.h>}. + +If the supplied signal number is within the valid range of indices for +symbolic names, but no name is available for the particular signal +number, then returns the string @samp{Signal @var{num}}, where +@var{num} is the signal number. + +If the supplied signal number is not within the range of valid +indices, then returns @code{NULL}. + +The contents of the location pointed to are only guaranteed to be +valid until the next call to @code{strsigno}. + +@end deftypefn + @c strstr.c:6 @deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub}) @@ -362,7 +760,7 @@ the location referenced by @var{endptr}. @end deftypefn @c strerror.c:730 -@deftypefn Replacement int strtoerrno (const char *@var{name}) +@deftypefn Extension int strtoerrno (const char *@var{name}) Given the symbolic name of a error number (e.g., @code{EACCES}), map it to an errno value. If no translation is found, returns 0. @@ -371,6 +769,7 @@ to an errno value. If no translation is found, returns 0. @c strtol.c:33 @deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base}) +@deftypefnx Supplemental {unsigned long int} strtoul (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 @@ -379,7 +778,16 @@ 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. +@code{strtod} above. The @code{strtoul} function is the same, except +that the converted value is unsigned. + +@end deftypefn + +@c strsignal.c:507 +@deftypefn Extension int strtosigno (const char *@var{name}) + +Given the symbolic name of a signal, map it to a signal number. If no +translation is found, returns 0. @end deftypefn @@ -394,6 +802,19 @@ not be used in new projects. Use @code{mkstemp} instead. @end deftypefn +@c vasprintf.c:48 +@deftypefn Extension int vasprintf (char **@var{resptr}, char *@var{format}, va_list @var{args}) + +Like @code{vsprintf}, but instead of passing a pointer to a buffer, +you pass a pointer to a pointer. This function will compute the size +of the buffer needed, allocate memory with @code{malloc}, and store a +pointer to the allocated memory in @code{*@var{resptr}}. The value +returned is the same as @code{vsprintf} would return. If memory could +not be allocated, zero is returned and @code{NULL} is stored in +@code{*@var{resptr}}. + +@end deftypefn + @c vfork.c:6 @deftypefn Supplemental int vfork (void) |