man3/isalpha.3

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