@comment ctype.h
@comment ISO
@deftypefun int islower (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c The is* macros call __ctype_b_loc to get the ctype array from the
+@c current locale, and then index it by c. __ctype_b_loc reads from
+@c thread-local memory the (indirect) pointer to the ctype array, which
+@c may involve one word access to the global locale object, if that's
+@c the active locale for the thread, and the array, being part of the
+@c locale data, is undeletable, so there's no thread-safety issue. We
+@c might want to mark these with @mtslocale to flag to callers that
+@c changing locales might affect them, even if not these simpler
+@c functions.
Returns true if @var{c} is a lower-case letter. The letter need not be
from the Latin alphabet, any alphabet representable is valid.
@end deftypefun
@comment ctype.h
@comment ISO
@deftypefun int isupper (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is an upper-case letter. The letter need not be
from the Latin alphabet, any alphabet representable is valid.
@end deftypefun
@comment ctype.h
@comment ISO
@deftypefun int isalpha (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is an alphabetic character (a letter). If
@code{islower} or @code{isupper} is true of a character, then
@code{isalpha} is also true.
@comment ctype.h
@comment ISO
@deftypefun int isdigit (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a decimal digit (@samp{0} through @samp{9}).
@end deftypefun
@comment ctype.h
@comment ISO
@deftypefun int isalnum (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is an alphanumeric character (a letter or
number); in other words, if either @code{isalpha} or @code{isdigit} is
true of a character, then @code{isalnum} is also true.
@comment ctype.h
@comment ISO
@deftypefun int isxdigit (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a hexadecimal digit.
Hexadecimal digits include the normal decimal digits @samp{0} through
@samp{9} and the letters @samp{A} through @samp{F} and
@comment ctype.h
@comment ISO
@deftypefun int ispunct (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a punctuation character.
This means any printing character that is not alphanumeric or a space
character.
@comment ctype.h
@comment ISO
@deftypefun int isspace (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a @dfn{whitespace} character. In the standard
@code{"C"} locale, @code{isspace} returns true for only the standard
whitespace characters:
@comment ctype.h
@comment ISO
@deftypefun int isblank (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a blank character; that is, a space or a tab.
This function was originally a GNU extension, but was added in @w{ISO C99}.
@end deftypefun
@comment ctype.h
@comment ISO
@deftypefun int isgraph (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a graphic character; that is, a character
that has a glyph associated with it. The whitespace characters are not
considered graphic.
@comment ctype.h
@comment ISO
@deftypefun int isprint (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a printing character. Printing characters
include all the graphic characters, plus the space (@samp{ }) character.
@end deftypefun
@comment ctype.h
@comment ISO
@deftypefun int iscntrl (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a control character (that is, a character that
is not a printing character).
@end deftypefun
@comment ctype.h
@comment SVID, BSD
@deftypefun int isascii (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a 7-bit @code{unsigned char} value that fits
into the US/UK ASCII character set. This function is a BSD extension
and is also an SVID extension.
@comment ctype.h
@comment ISO
@deftypefun int tolower (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c The to* macros/functions call different functions that use different
+@c arrays than those of__ctype_b_loc, but the access patterns and
+@c thus safety guarantees are the same.
If @var{c} is an upper-case letter, @code{tolower} returns the corresponding
lower-case letter. If @var{c} is not an upper-case letter,
@var{c} is returned unchanged.
@comment ctype.h
@comment ISO
@deftypefun int toupper (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
If @var{c} is a lower-case letter, @code{toupper} returns the corresponding
upper-case letter. Otherwise @var{c} is returned unchanged.
@end deftypefun
@comment ctype.h
@comment SVID, BSD
@deftypefun int toascii (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function converts @var{c} to a 7-bit @code{unsigned char} value
that fits into the US/UK ASCII character set, by clearing the high-order
bits. This function is a BSD extension and is also an SVID extension.
@comment ctype.h
@comment SVID
@deftypefun int _tolower (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This is identical to @code{tolower}, and is provided for compatibility
with the SVID. @xref{SVID}.@refill
@end deftypefun
@comment ctype.h
@comment SVID
@deftypefun int _toupper (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This is identical to @code{toupper}, and is provided for compatibility
with the SVID.
@end deftypefun
@comment wctype.h
@comment ISO
@deftypefun wctype_t wctype (const char *@var{property})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c Although the source code of wctype contains multiple references to
+@c the locale, that could each reference different locale_data objects
+@c should the global locale object change while active, the compiler can
+@c and does combine them all into a single dereference that resolves
+@c once to the LCTYPE locale object used throughout the function, so it
+@c is safe in (optimized) practice, if not in theory, even when the
+@c locale changes. Ideally we'd explicitly save the resolved
+@c locale_data object to make it visibly safe instead of safe only under
+@c compiler optimizations, but given the decision that setlocale is
+@c MT-Unsafe, all this would afford us would be the ability to not mark
+@c this function with @mtslocale.
The @code{wctype} returns a value representing a class of wide
characters which is identified by the string @var{property}. Beside
some standard properties each locale can define its own ones. In case
@comment wctype.h
@comment ISO
@deftypefun int iswctype (wint_t @var{wc}, wctype_t @var{desc})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c The compressed lookup table returned by wctype is read-only.
This function returns a nonzero value if @var{wc} is in the character
class specified by @var{desc}. @var{desc} must previously be returned
by a successful call to @code{wctype}.
@comment wctype.h
@comment ISO
@deftypefun int iswalnum (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c The implicit wctype call in the isw* functions is actually an
+@c optimized version because the category has a known offset, but the
+@c wctype is equally safe when optimized, unsafe with changing locales
+@c if not optimized (thus @mtslocale). Since it's not a macro, we
+@c always optimize, and the locale can't change in any MT-Safe way, it's
+@c fine. The test whether wc is ASCII to use the non-wide is*
+@c macro/function doesn't bring any other safety issues: the test does
+@c not depend on the locale, and each path after the decision resolves
+@c the locale object only once.
This function returns a nonzero value if @var{wc} is an alphanumeric
character (a letter or number); in other words, if either @code{iswalpha}
or @code{iswdigit} is true of a character, then @code{iswalnum} is also
@comment wctype.h
@comment ISO
@deftypefun int iswalpha (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
Returns true if @var{wc} is an alphabetic character (a letter). If
@code{iswlower} or @code{iswupper} is true of a character, then
@code{iswalpha} is also true.
@comment wctype.h
@comment ISO
@deftypefun int iswcntrl (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
Returns true if @var{wc} is a control character (that is, a character that
is not a printing character).
@comment wctype.h
@comment ISO
@deftypefun int iswdigit (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
Returns true if @var{wc} is a digit (e.g., @samp{0} through @samp{9}).
Please note that this function does not only return a nonzero value for
@emph{decimal} digits, but for all kinds of digits. A consequence is
@comment wctype.h
@comment ISO
@deftypefun int iswgraph (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
Returns true if @var{wc} is a graphic character; that is, a character
that has a glyph associated with it. The whitespace characters are not
considered graphic.
@comment ctype.h
@comment ISO
@deftypefun int iswlower (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
Returns true if @var{wc} is a lower-case letter. The letter need not be
from the Latin alphabet, any alphabet representable is valid.
@comment wctype.h
@comment ISO
@deftypefun int iswprint (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
Returns true if @var{wc} is a printing character. Printing characters
include all the graphic characters, plus the space (@samp{ }) character.
@comment wctype.h
@comment ISO
@deftypefun int iswpunct (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
Returns true if @var{wc} is a punctuation character.
This means any printing character that is not alphanumeric or a space
character.
@comment wctype.h
@comment ISO
@deftypefun int iswspace (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
Returns true if @var{wc} is a @dfn{whitespace} character. In the standard
@code{"C"} locale, @code{iswspace} returns true for only the standard
whitespace characters:
@comment wctype.h
@comment ISO
@deftypefun int iswupper (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
Returns true if @var{wc} is an upper-case letter. The letter need not be
from the Latin alphabet, any alphabet representable is valid.
@comment wctype.h
@comment ISO
@deftypefun int iswxdigit (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
Returns true if @var{wc} is a hexadecimal digit.
Hexadecimal digits include the normal decimal digits @samp{0} through
@samp{9} and the letters @samp{A} through @samp{F} and
@comment wctype.h
@comment ISO
@deftypefun int iswblank (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
Returns true if @var{wc} is a blank character; that is, a space or a tab.
This function was originally a GNU extension, but was added in @w{ISO C99}.
It is declared in @file{wchar.h}.
@comment wctype.h
@comment ISO
@deftypefun wctrans_t wctrans (const char *@var{property})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c Similar implementation, same caveats as wctype.
The @code{wctrans} function has to be used to find out whether a named
mapping is defined in the current locale selected for the
@code{LC_CTYPE} category. If the returned value is non-zero, you can use
@comment wctype.h
@comment ISO
@deftypefun wint_t towctrans (wint_t @var{wc}, wctrans_t @var{desc})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Same caveats as iswctype.
@code{towctrans} maps the input character @var{wc}
according to the rules of the mapping for which @var{desc} is a
descriptor, and returns the value it finds. @var{desc} must be
@comment wctype.h
@comment ISO
@deftypefun wint_t towlower (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c Same caveats as iswalnum, just using a wctrans rather than a wctype
+@c table.
If @var{wc} is an upper-case letter, @code{towlower} returns the corresponding
lower-case letter. If @var{wc} is not an upper-case letter,
@var{wc} is returned unchanged.
@comment wctype.h
@comment ISO
@deftypefun wint_t towupper (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
If @var{wc} is a lower-case letter, @code{towupper} returns the corresponding
upper-case letter. Otherwise @var{wc} is returned unchanged.
projects / platform / upstream / glibc.git / commitdiff