X-Git-Url: http://git.sourceforge.jp/view?a=blobdiff_plain;f=libiberty%2Ffunctions.texi;h=b6e8e7acb813fe22784ece8097162fa821082628;hb=c04df53f59b953c94e5d937ed94ed213fc78fb33;hp=2c7b9e1276ac768777e7e36b8fb7fddef8b992aa;hpb=846a645c173e6d1b00187f1feed6104d13cb6ac1;p=pf3gnuchains%2Fgcc-fork.git diff --git a/libiberty/functions.texi b/libiberty/functions.texi index 2c7b9e1276a..b6e8e7acb81 100644 --- a/libiberty/functions.texi +++ b/libiberty/functions.texi @@ -3,6 +3,28 @@ @c Edit the *.c files, configure with --enable-maintainer-mode, @c and let gather-docs build you a new copy. +@c safe-ctype.c:24 +@defvr Extension HOST_CHARSET +This macro indicates the basic character set and encoding used by the +host: more precisely, the encoding used for character constants in +preprocessor @samp{#if} statements (the C "execution character set"). +It is defined by @file{safe-ctype.h}, and will be an integer constant +with one of the following values: + +@ftable @code +@item HOST_CHARSET_UNKNOWN +The host character set is unknown - that is, not one of the next two +possibilities. + +@item HOST_CHARSET_ASCII +The host character set is ASCII. + +@item HOST_CHARSET_EBCDIC +The host character set is some variant of EBCDIC. (Only one of the +nineteen EBCDIC varying characters is tested; exercise caution.) +@end ftable +@end defvr + @c alloca.c:26 @deftypefn Replacement void* alloca (size_t @var{size}) @@ -29,7 +51,7 @@ 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 +not be allocated, minus one is returned and @code{NULL} is stored in @code{*@var{resptr}}. @end deftypefn @@ -174,7 +196,7 @@ argument vector. @end deftypefn -@c strerror.c:566 +@c strerror.c:567 @deftypefn Extension int errno_max (void) Returns the maximum @code{errno} value for which a corresponding @@ -317,7 +339,7 @@ between calls to @code{getpwd}. @end deftypefn -@c hex.c:25 +@c hex.c:30 @deftypefn Extension void hex_init (void) Initializes the array mapping the current character set to @@ -327,7 +349,7 @@ default ASCII-based table will normally be used on ASCII systems. @end deftypefn -@c hex.c:34 +@c hex.c:39 @deftypefn Extension int hex_p (int @var{c}) Evaluates to non-zero if the given character is a valid hex character, @@ -336,14 +358,20 @@ or zero if it is not. Note that the value you pass will be cast to @end deftypefn -@c hex.c:42 -@deftypefn Extension int hex_value (int @var{c}) +@c hex.c:47 +@deftypefn Extension {unsigned int} hex_value (int @var{c}) Returns the numeric equivalent of the given character when interpreted as a hexidecimal digit. The result is undefined if you pass an invalid hex digit. Note that the value you pass will be cast to @code{unsigned char} within the macro. +The @code{hex_value} macro returns @code{unsigned int}, rather than +signed @code{int}, to make it easier to use in parsing addresses from +hex dump files: a signed @code{int} would be sign-extended when +converted to a wider unsigned type --- like @code{bfd_vma}, on some +systems. + @end deftypefn @c index.c:5 @@ -376,6 +404,78 @@ struct qelem @{ @end deftypefn +@c safe-ctype.c:45 +@deffn Extension ISALPHA (@var{c}) +@deffnx Extension ISALNUM (@var{c}) +@deffnx Extension ISBLANK (@var{c}) +@deffnx Extension ISCNTRL (@var{c}) +@deffnx Extension ISDIGIT (@var{c}) +@deffnx Extension ISGRAPH (@var{c}) +@deffnx Extension ISLOWER (@var{c}) +@deffnx Extension ISPRINT (@var{c}) +@deffnx Extension ISPUNCT (@var{c}) +@deffnx Extension ISSPACE (@var{c}) +@deffnx Extension ISUPPER (@var{c}) +@deffnx Extension ISXDIGIT (@var{c}) + +These twelve macros are defined by @file{safe-ctype.h}. Each has the +same meaning as the corresponding macro (with name in lowercase) +defined by the standard header @file{ctype.h}. For example, +@code{ISALPHA} returns true for alphabetic characters and false for +others. However, there are two differences between these macros and +those provided by @file{ctype.h}: + +@itemize @bullet +@item These macros are guaranteed to have well-defined behavior for all +values representable by @code{signed char} and @code{unsigned char}, and +for @code{EOF}. + +@item These macros ignore the current locale; they are true for these +fixed sets of characters: +@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada} +@item @code{ALPHA} @tab @kbd{A-Za-z} +@item @code{ALNUM} @tab @kbd{A-Za-z0-9} +@item @code{BLANK} @tab @kbd{space tab} +@item @code{CNTRL} @tab @code{!PRINT} +@item @code{DIGIT} @tab @kbd{0-9} +@item @code{GRAPH} @tab @code{ALNUM || PUNCT} +@item @code{LOWER} @tab @kbd{a-z} +@item @code{PRINT} @tab @code{GRAPH ||} @kbd{space} +@item @code{PUNCT} @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?} +@item @code{SPACE} @tab @kbd{space tab \n \r \f \v} +@item @code{UPPER} @tab @kbd{A-Z} +@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f} +@end multitable + +Note that, if the host character set is ASCII or a superset thereof, +all these macros will return false for all values of @code{char} outside +the range of 7-bit ASCII. In particular, both ISPRINT and ISCNTRL return +false for characters with numeric values from 128 to 255. +@end itemize +@end deffn + +@c safe-ctype.c:94 +@deffn Extension ISIDNUM (@var{c}) +@deffnx Extension ISIDST (@var{c}) +@deffnx Extension IS_VSPACE (@var{c}) +@deffnx Extension IS_NVSPACE (@var{c}) +@deffnx Extension IS_SPACE_OR_NUL (@var{c}) +@deffnx Extension IS_ISOBASIC (@var{c}) +These six macros are defined by @file{safe-ctype.h} and provide +additional character classes which are useful when doing lexical +analysis of C or similar languages. They are true for the following +sets of characters: + +@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada} +@item @code{IDNUM} @tab @kbd{A-Za-z0-9_} +@item @code{IDST} @tab @kbd{A-Za-z_} +@item @code{VSPACE} @tab @kbd{\r \n} +@item @code{NVSPACE} @tab @kbd{space tab \f \v \0} +@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE} +@item @code{ISOBASIC} @tab @code{VSPACE || NVSPACE || PRINT} +@end multitable +@end deffn + @c lbasename.c:23 @deftypefn Replacement {const char*} lbasename (const char *@var{name}) @@ -398,7 +498,7 @@ and a path ending in @code{/} returns the empty string after it. Given a pointer to a string containing a pathname, returns a canonical version of the filename. Symlinks will be resolved, and ``.'' and ``..'' components will be simplified. The returned value will be allocated using -@code{xmalloc} or @code{malloc}. +@code{malloc}, or @code{NULL} will be returned on a memory allocation error. @end deftypefn @@ -476,6 +576,14 @@ Copies @var{count} bytes from memory area @var{from} to memory area @end deftypefn +@c mempcpy.c:23 +@deftypefn Supplemental void* mempcpy (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} + @var{length}. + +@end deftypefn + @c memset.c:6 @deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count}) @@ -541,7 +649,7 @@ text of the error message with an optional argument (if not needed, @end deftypefn -@c strsignal.c:547 +@c strsignal.c:546 @deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message}) Print @var{message} to the standard error, followed by a colon, @@ -638,7 +746,7 @@ environment. This implementation is not safe for multithreaded code. @end deftypefn -@c strsignal.c:353 +@c strsignal.c:352 @deftypefn Extension int signo_max (void) Returns the maximum signal value for which a corresponding symbolic @@ -665,6 +773,19 @@ be the value @code{1}). @end deftypefn +@c snprintf.c:28 +@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...) + +This function is similar to sprintf, but it will print at most @var{n} +characters. On error the return value is -1, otherwise it returns the +number of characters that would have been printed had @var{n} been +sufficiently large, regardless of the actual value of @var{n}. Note +some pre-C99 system libraries do not implement this correctly so users +cannot generally rely on the return value if the system version of +this function is used. + +@end deftypefn + @c spaces.c:22 @deftypefn Extension char* spaces (int @var{count}) @@ -674,6 +795,24 @@ valid until at least the next call. @end deftypefn +@c stpcpy.c:23 +@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src}) + +Copies the string @var{src} into @var{dst}. Returns a pointer to +@var{dst} + strlen(@var{src}). + +@end deftypefn + +@c stpncpy.c:23 +@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, size_t @var{len}) + +Copies the string @var{src} into @var{dst}, copying exactly @var{len} +and padding with zeros if necessary. If @var{len} < strlen(@var{src}) +then return @var{dst} + @var{len}, otherwise returns @var{dst} + +strlen(@var{src}). + +@end deftypefn + @c strcasecmp.c:15 @deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2}) @@ -698,7 +837,7 @@ Returns a pointer to a copy of @var{s} in memory obtained from @end deftypefn -@c strerror.c:670 +@c strerror.c:671 @deftypefn Replacement {const char*} strerrno (int @var{errnum}) Given an error number returned from a system call (typically returned @@ -718,7 +857,7 @@ valid until the next call to @code{strerrno}. @end deftypefn -@c strerror.c:602 +@c strerror.c:603 @deftypefn Supplemental char* strerror (int @var{errnoval}) Maps an @code{errno} number to an error message string, the contents @@ -763,7 +902,7 @@ null character, the results are undefined. @end deftypefn -@c strsignal.c:388 +@c strsignal.c:387 @deftypefn Supplemental {const char *} strsignal (int @var{signo}) Maps an signal number to an signal message string, the contents of @@ -784,7 +923,7 @@ call to @code{strsignal}. @end deftypefn -@c strsignal.c:452 +@c strsignal.c:451 @deftypefn Extension {const char*} strsigno (int @var{signo}) Given an signal number, returns a pointer to a string containing the @@ -826,7 +965,7 @@ the location referenced by @var{endptr}. @end deftypefn -@c strerror.c:730 +@c strerror.c:731 @deftypefn Extension int strtoerrno (const char *@var{name}) Given the symbolic name of a error number (e.g., @code{EACCES}), map it @@ -850,7 +989,7 @@ that the converted value is unsigned. @end deftypefn -@c strsignal.c:507 +@c strsignal.c:506 @deftypefn Extension int strtosigno (const char *@var{name}) Given the symbolic name of a signal, map it to a signal number. If no @@ -869,7 +1008,7 @@ not be used in new projects. Use @code{mkstemp} instead. @end deftypefn -@c vasprintf.c:48 +@c vasprintf.c:51 @deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args}) Like @code{vsprintf}, but instead of passing a pointer to a buffer, @@ -877,7 +1016,7 @@ 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 +not be allocated, minus one is returned and @code{NULL} is stored in @code{*@var{resptr}}. @end deftypefn @@ -903,6 +1042,19 @@ nonstandard but common function @code{_doprnt}. @end deftypefn +@c vsnprintf.c:28 +@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap}) + +This function is similar to vsprintf, but it will print at most +@var{n} characters. On error the return value is -1, otherwise it +returns the number of characters that would have been printed had +@var{n} been sufficiently large, regardless of the actual value of +@var{n}. Note some pre-C99 system libraries do not implement this +correctly so users cannot generally rely on the return value if the +system version of this function is used. + +@end deftypefn + @c waitpid.c:3 @deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)