man3/isalpha.3

   1 '\" t
   2 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Modified Sat Jul 24 19:10:00 1993 by Rik Faith (faith@cs.unc.edu)
   7 .\" Modified Sun Aug 21 17:51:50 1994 by Rik Faith (faith@cs.unc.edu)
   8 .\" Modified Sat Sep  2 21:52:01 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
   9 .\" Modified Mon May 27 22:55:26 1996 by Martin Schulze (joey@linux.de)
  10 .\"
  11 .TH isalpha 3 (date) "Linux man-pages (unreleased)"
  12 .SH NAME
  13 isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower,
  14 isprint, ispunct, isspace, isupper, isxdigit,
  15 isalnum_l, isalpha_l, isascii_l, isblank_l, iscntrl_l,
  16 isdigit_l, isgraph_l, islower_l,
  17 isprint_l, ispunct_l, isspace_l, isupper_l, isxdigit_l
  18 \- character classification functions
  19 .SH LIBRARY
  20 Standard C library
  21 .RI ( libc ", " \-lc )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <ctype.h>
  25 .PP
  26 .BI "int isalnum(int " c );
  27 .BI "int isalpha(int " c );
  28 .BI "int iscntrl(int " c );
  29 .BI "int isdigit(int " c );
  30 .BI "int isgraph(int " c );
  31 .BI "int islower(int " c );
  32 .BI "int isprint(int " c );
  33 .BI "int ispunct(int " c );
  34 .BI "int isspace(int " c );
  35 .BI "int isupper(int " c );
  36 .BI "int isxdigit(int " c );
  37 .PP
  38 .BI "int isascii(int " c );
  39 .BI "int isblank(int " c );
  40 .PP
  41 .BI "int isalnum_l(int " c ", locale_t " locale );
  42 .BI "int isalpha_l(int " c ", locale_t " locale );
  43 .BI "int isblank_l(int " c ", locale_t " locale );
  44 .BI "int iscntrl_l(int " c ", locale_t " locale );
  45 .BI "int isdigit_l(int " c ", locale_t " locale );
  46 .BI "int isgraph_l(int " c ", locale_t " locale );
  47 .BI "int islower_l(int " c ", locale_t " locale );
  48 .BI "int isprint_l(int " c ", locale_t " locale );
  49 .BI "int ispunct_l(int " c ", locale_t " locale );
  50 .BI "int isspace_l(int " c ", locale_t " locale );
  51 .BI "int isupper_l(int " c ", locale_t " locale );
  52 .BI "int isxdigit_l(int " c ", locale_t " locale );
  53 .PP
  54 .BI "int isascii_l(int " c ", locale_t " locale );
  55 .fi
  56 .PP
  57 .RS -4
  58 Feature Test Macro Requirements for glibc (see
  59 .BR feature_test_macros (7)):
  60 .RE
  61 .ad l
  62 .PP
  63 .BR isascii ():
  64 .nf
  65     _XOPEN_SOURCE
  66         || /* Glibc >= 2.19: */ _DEFAULT_SOURCE
  67         || /* Glibc <= 2.19: */ _SVID_SOURCE
  68 .fi
  69 .PP
  70 .BR isblank ():
  71 .nf
  72     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  73 .fi
  74 .nh
  75 .PP
  76 .BR isalnum_l (),
  77 .BR isalpha_l (),
  78 .BR isblank_l (),
  79 .BR iscntrl_l (),
  80 .BR isdigit_l (),
  81 .BR isgraph_l (),
  82 .BR islower_l (),
  83 .BR isprint_l (),
  84 .BR ispunct_l (),
  85 .BR isspace_l (),
  86 .BR isupper_l (),
  87 .BR isxdigit_l ():
  88 .hy
  89 .nf
  90     Since glibc 2.10:
  91         _XOPEN_SOURCE >= 700
  92     Before glibc 2.10:
  93         _GNU_SOURCE
  94 .fi
  95 .PP
  96 .BR isascii_l ():
  97 .nf
  98     Since glibc 2.10:
  99         _XOPEN_SOURCE >= 700 && (_SVID_SOURCE || _BSD_SOURCE)
 100     Before glibc 2.10:
 101         _GNU_SOURCE
 102 .fi
 103 .ad
 104 .SH DESCRIPTION
 105 These functions check whether
 106 .IR c ,
 107 which must have the value of an
 108 .I unsigned char
 109 or
 110 .BR EOF ,
 111 falls into a certain character class according to the specified locale.
 112 The functions without the
 113 "_l" suffix perform the check based on the current locale.
 114 .PP
 115 The functions with the "_l" suffix perform the check
 116 based on the locale specified by the locale object
 117 .IR locale .
 118 The behavior of these functions is undefined if
 119 .I locale
 120 is the special locale object
 121 .B LC_GLOBAL_LOCALE
 122 (see
 123 .BR duplocale (3))
 124 or is not a valid locale object handle.
 125 .PP
 126 The list below explains the operation of the functions without
 127 the "_l" suffix;
 128 the functions with the "_l" suffix differ only in using the locale object
 129 .I locale
 130 instead of the current locale.
 131 .TP
 132 .BR isalnum ()
 133 checks for an alphanumeric character; it is equivalent to
 134 .BI "(isalpha(" c ") || isdigit(" c "))" \fR.
 135 .TP
 136 .BR isalpha ()
 137 checks for an alphabetic character; in the standard \fB"C"\fP
 138 locale, it is equivalent to
 139 .BI "(isupper(" c ") || islower(" c "))" \fR.
 140 In some locales, there may be additional characters for which
 141 .BR isalpha ()
 142 is true\(emletters which are neither uppercase nor lowercase.
 143 .TP
 144 .BR isascii ()
 145 checks whether \fIc\fP is a 7-bit
 146 .I unsigned char
 147 value that fits into
 148 the ASCII character set.
 149 .TP
 150 .BR isblank ()
 151 checks for a blank character; that is, a space or a tab.
 152 .TP
 153 .BR iscntrl ()
 154 checks for a control character.
 155 .TP
 156 .BR isdigit ()
 157 checks for a digit (0 through 9).
 158 .TP
 159 .BR isgraph ()
 160 checks for any printable character except space.
 161 .TP
 162 .BR islower ()
 163 checks for a lowercase character.
 164 .TP
 165 .BR isprint ()
 166 checks for any printable character including space.
 167 .TP
 168 .BR ispunct ()
 169 checks for any printable character which is not a space or an
 170 alphanumeric character.
 171 .TP
 172 .BR isspace ()
 173 checks for white-space characters.
 174 In the
 175 .B """C"""
 176 and
 177 .B """POSIX"""
 178 locales, these are: space, form-feed
 179 .RB ( \(aq\ef\(aq ),
 180 newline
 181 .RB ( \(aq\en\(aq ),
 182 carriage return
 183 .RB ( \(aq\er\(aq ),
 184 horizontal tab
 185 .RB ( \(aq\et\(aq ),
 186 and vertical tab
 187 .RB ( \(aq\ev\(aq ).
 188 .TP
 189 .BR isupper ()
 190 checks for an uppercase letter.
 191 .TP
 192 .BR isxdigit ()
 193 checks for hexadecimal digits, that is, one of
 194 .br
 195 .BR "0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F" .
 196 .SH RETURN VALUE
 197 The values returned are nonzero if the character
 198 .I c
 199 falls into the tested class, and zero if not.
 200 .SH VERSIONS
 201 .BR isalnum_l (),
 202 .BR isalpha_l (),
 203 .BR isblank_l (),
 204 .BR iscntrl_l (),
 205 .BR isdigit_l (),
 206 .BR isgraph_l (),
 207 .BR islower_l (),
 208 .BR isprint_l (),
 209 .BR ispunct_l (),
 210 .BR isspace_l (),
 211 .BR isupper_l (),
 212 .BR isxdigit_l (),
 213 and
 214 .BR isascii_l ()
 215 are available since glibc 2.3.
 216 .SH ATTRIBUTES
 217 For an explanation of the terms used in this section, see
 218 .BR attributes (7).
 219 .ad l
 220 .nh
 221 .TS
 222 allbox;
 223 lbx lb lb
 224 l l l.
 225 Interface       Attribute       Value
 226 T{
 227 .BR isalnum (),
 228 .BR isalpha (),
 229 .BR isascii (),
 230 .BR isblank (),
 231 .BR iscntrl (),
 232 .BR isdigit (),
 233 .BR isgraph (),
 234 .BR islower (),
 235 .BR isprint (),
 236 .BR ispunct (),
 237 .BR isspace (),
 238 .BR isupper (),
 239 .BR isxdigit ()
 240 T}      Thread safety   MT-Safe
 241 .TE
 242 .hy
 243 .ad
 244 .sp 1
 245 .\" FIXME: need a thread-safety statement about the *_l functions
 246 .SH STANDARDS
 247 C89 specifies
 248 .BR isalnum (),
 249 .BR isalpha (),
 250 .BR iscntrl (),
 251 .BR isdigit (),
 252 .BR isgraph (),
 253 .BR islower (),
 254 .BR isprint (),
 255 .BR ispunct (),
 256 .BR isspace (),
 257 .BR isupper (),
 258 and
 259 .BR isxdigit (),
 260 but not
 261 .BR isascii ()
 262 and
 263 .BR isblank ().
 264 POSIX.1-2001
 265 also specifies those functions, and also
 266 .BR isascii ()
 267 (as an XSI extension)
 268 and
 269 .BR isblank ().
 270 C99 specifies all of the preceding functions, except
 271 .BR isascii ().
 272 .PP
 273 POSIX.1-2008 marks
 274 .BR isascii ()
 275 as obsolete,
 276 noting that it cannot be used portably in a localized application.
 277 .PP
 278 POSIX.1-2008 specifies
 279 .BR isalnum_l (),
 280 .BR isalpha_l (),
 281 .BR isblank_l (),
 282 .BR iscntrl_l (),
 283 .BR isdigit_l (),
 284 .BR isgraph_l (),
 285 .BR islower_l (),
 286 .BR isprint_l (),
 287 .BR ispunct_l (),
 288 .BR isspace_l (),
 289 .BR isupper_l (),
 290 and
 291 .BR isxdigit_l ().
 292 .PP
 293 .BR isascii_l ()
 294 is a GNU extension.
 295 .SH NOTES
 296 The standards require that the argument
 297 .I c
 298 for these functions is either
 299 .B EOF
 300 or a value that is representable in the type
 301 .IR "unsigned char" .
 302 If the argument
 303 .I c
 304 is of type
 305 .IR char ,
 306 it must be cast to
 307 .IR "unsigned char" ,
 308 as in the following example:
 309 .PP
 310 .in +4n
 311 .EX
 312 char c;
 313 \&...
 314 res = toupper((unsigned char) c);
 315 .EE
 316 .in
 317 .PP
 318 This is necessary because
 319 .I char
 320 may be the equivalent of
 321 .IR "signed char" ,
 322 in which case a byte where the top bit is set would be sign extended when
 323 converting to
 324 .IR int ,
 325 yielding a value that is outside the range of
 326 .IR "unsigned char" .
 327 .PP
 328 The details of what characters belong to which class depend on the
 329 locale.
 330 For example,
 331 .BR isupper ()
 332 will not recognize an A-umlaut (\(:A) as an uppercase letter in the default
 333 .B "C"
 334 locale.
 335 .SH SEE ALSO
 336 .BR iswalnum (3),
 337 .BR iswalpha (3),
 338 .BR iswblank (3),
 339 .BR iswcntrl (3),
 340 .BR iswdigit (3),
 341 .BR iswgraph (3),
 342 .BR iswlower (3),
 343 .BR iswprint (3),
 344 .BR iswpunct (3),
 345 .BR iswspace (3),
 346 .BR iswupper (3),
 347 .BR iswxdigit (3),
 348 .BR newlocale (3),
 349 .BR setlocale (3),
 350 .BR toascii (3),
 351 .BR tolower (3),
 352 .BR toupper (3),
 353 .BR uselocale (3),
 354 .BR ascii (7),
 355 .BR locale (7)