| blob | 05d373780823b889f26e1159e8f56dd61c4ca1d4 |
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 .P
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 .P
38 .BI "int isascii(int " c );
39 .BI "int isblank(int " c );
40 .P
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 .P
54 .BI "int isascii_l(int " c ", locale_t " locale );
55 .fi
56 .P
57 .RS -4
58 Feature Test Macro Requirements for glibc (see
59 .BR feature_test_macros (7)):
60 .RE
61 .ad l
62 .P
63 .BR isascii ():
64 .nf
65 _XOPEN_SOURCE
66 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
67 || /* glibc <= 2.19: */ _SVID_SOURCE
68 .fi
69 .P
70 .BR isblank ():
71 .nf
72 _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
73 .fi
74 .P
75 .BR \%salnum_l (),
76 .BR \%salpha_l (),
77 .BR \%sblank_l (),
78 .BR \%scntrl_l (),
79 .BR \%sdigit_l (),
80 .BR \%sgraph_l (),
81 .BR \%slower_l (),
82 .BR \%sprint_l (),
83 .BR \%spunct_l (),
84 .BR \%sspace_l (),
85 .BR \%supper_l (),
86 .BR \%sxdigit_l ():
87 .nf
88 Since glibc 2.10:
89 _XOPEN_SOURCE >= 700
90 Before glibc 2.10:
91 _GNU_SOURCE
92 .fi
93 .P
94 .BR isascii_l ():
95 .nf
96 Since glibc 2.10:
97 _XOPEN_SOURCE >= 700 && (_SVID_SOURCE || _BSD_SOURCE)
98 Before glibc 2.10:
99 _GNU_SOURCE
100 .fi
101 .ad
102 .SH DESCRIPTION
103 These functions check whether
104 .IR c ,
105 which must have the value of an
106 .I unsigned char
107 or
108 .BR EOF ,
109 falls into a certain character class according to the specified locale.
110 The functions without the
111 "_l" suffix perform the check based on the current locale.
112 .P
113 The functions with the "_l" suffix perform the check
114 based on the locale specified by the locale object
115 .IR locale .
116 The behavior of these functions is undefined if
117 .I locale
118 is the special locale object
119 .B LC_GLOBAL_LOCALE
120 (see
121 .BR duplocale (3))
122 or is not a valid locale object handle.
123 .P
124 The list below explains the operation of the functions without
125 the "_l" suffix;
126 the functions with the "_l" suffix differ only in using the locale object
127 .I locale
128 instead of the current locale.
129 .TP
130 .BR isalnum ()
131 checks for an alphanumeric character; it is equivalent to
132 .BI "(isalpha(" c ") || isdigit(" c "))" \fR.
133 .TP
134 .BR isalpha ()
135 checks for an alphabetic character; in the standard \fB"C"\fP
136 locale, it is equivalent to
137 .BI "(isupper(" c ") || islower(" c "))" \fR.
138 In some locales, there may be additional characters for which
139 .BR isalpha ()
140 is true\[em]letters which are neither uppercase nor lowercase.
141 .TP
142 .BR isascii ()
143 checks whether \fIc\fP is a 7-bit
144 .I unsigned char
145 value that fits into
146 the ASCII character set.
147 .TP
148 .BR isblank ()
149 checks for a blank character; that is, a space or a tab.
150 .TP
151 .BR iscntrl ()
152 checks for a control character.
153 .TP
154 .BR isdigit ()
155 checks for a digit (0 through 9).
156 .TP
157 .BR isgraph ()
158 checks for any printable character except space.
159 .TP
160 .BR islower ()
161 checks for a lowercase character.
162 .TP
163 .BR isprint ()
164 checks for any printable character including space.
165 .TP
166 .BR ispunct ()
167 checks for any printable character which is not a space or an
168 alphanumeric character.
169 .TP
170 .BR isspace ()
171 checks for white-space characters.
172 In the
173 .B \[dq]C\[dq]
174 and
175 .B \[dq]POSIX\[dq]
176 locales, these are: space, form-feed
177 .RB ( \[aq]\ef\[aq] ),
178 newline
179 .RB ( \[aq]\en\[aq] ),
180 carriage return
181 .RB ( \[aq]\er\[aq] ),
182 horizontal tab
183 .RB ( \[aq]\et\[aq] ),
184 and vertical tab
185 .RB ( \[aq]\ev\[aq] ).
186 .TP
187 .BR isupper ()
188 checks for an uppercase letter.
189 .TP
190 .BR isxdigit ()
191 checks for hexadecimal digits, that is, one of
192 .br
193 .BR "0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F" .
194 .SH RETURN VALUE
195 The values returned are nonzero if the character
196 .I c
197 falls into the tested class, and zero if not.
198 .SH ATTRIBUTES
199 For an explanation of the terms used in this section, see
200 .BR attributes (7).
201 .TS
202 allbox;
203 lbx lb lb
204 l l l.
205 Interface Attribute Value
206 T{
207 .na
208 .nh
209 .BR isalnum (),
210 .BR isalpha (),
211 .BR isascii (),
212 .BR isblank (),
213 .BR iscntrl (),
214 .BR isdigit (),
215 .BR isgraph (),
216 .BR islower (),
217 .BR isprint (),
218 .BR ispunct (),
219 .BR isspace (),
220 .BR isupper (),
221 .BR isxdigit ()
222 T} Thread safety MT-Safe
223 .TE
224 .\" FIXME: need a thread-safety statement about the *_l functions
225 .SH STANDARDS
226 .TP
227 .BR isalnum ()
228 .TQ
229 .BR isalpha ()
230 .TQ
231 .BR iscntrl ()
232 .TQ
233 .BR isdigit ()
234 .TQ
235 .BR isgraph ()
236 .TQ
237 .BR islower ()
238 .TQ
239 .BR isprint ()
240 .TQ
241 .BR ispunct ()
242 .TQ
243 .BR isspace ()
244 .TQ
245 .BR isupper ()
246 .TQ
247 .BR isxdigit ()
248 .TQ
249 .BR isblank ()
250 C11, POSIX.1-2008.
251 .TP
252 .BR isascii ()
253 .TQ
254 .BR isalnum_l ()
255 .TQ
256 .BR isalpha_l ()
257 .TQ
258 .BR isblank_l ()
259 .TQ
260 .BR iscntrl_l ()
261 .TQ
262 .BR isdigit_l ()
263 .TQ
264 .BR isgraph_l ()
265 .TQ
266 .BR islower_l ()
267 .TQ
268 .BR isprint_l ()
269 .TQ
270 .BR ispunct_l ()
271 .TQ
272 .BR isspace_l ()
273 .TQ
274 .BR isupper_l ()
275 .TQ
276 .BR isxdigit_l ()
277 POSIX.1-2008.
278 .TP
279 .BR isascii_l ()
280 GNU.
281 .SH HISTORY
282 .TP
283 .BR isalnum ()
284 .TQ
285 .BR isalpha ()
286 .TQ
287 .BR iscntrl ()
288 .TQ
289 .BR isdigit ()
290 .TQ
291 .BR isgraph ()
292 .TQ
293 .BR islower ()
294 .TQ
295 .BR isprint ()
296 .TQ
297 .BR ispunct ()
298 .TQ
299 .BR isspace ()
300 .TQ
301 .BR isupper ()
302 .TQ
303 .BR isxdigit ()
304 C89, POSIX.1-2001.
305 .TP
306 .BR isblank ()
307 C99, POSIX.1-2001.
308 .TP
309 .BR isascii ()
310 POSIX.1-2001 (XSI).
311 .IP
312 POSIX.1-2008 marks it as obsolete,
313 noting that it cannot be used portably in a localized application.
314 .TP
315 .BR isalnum_l ()
316 .TQ
317 .BR isalpha_l ()
318 .TQ
319 .BR isblank_l ()
320 .TQ
321 .BR iscntrl_l ()
322 .TQ
323 .BR isdigit_l ()
324 .TQ
325 .BR isgraph_l ()
326 .TQ
327 .BR islower_l ()
328 .TQ
329 .BR isprint_l ()
330 .TQ
331 .BR ispunct_l ()
332 .TQ
333 .BR isspace_l ()
334 .TQ
335 .BR isupper_l ()
336 .TQ
337 .BR isxdigit_l ()
338 glibc 2.3.
339 POSIX.1-2008.
340 .TP
341 .BR isascii_l ()
342 glibc 2.3.
343 .SH CAVEATS
344 The standards require that the argument
345 .I c
346 for these functions is either
347 .B EOF
348 or a value that is representable in the type
349 .IR "unsigned char" ;
350 otherwise,
351 the behavior is undefined.
352 If the argument
353 .I c
354 is of type
355 .IR char ,
356 it must be cast to
357 .IR "unsigned char" ,
358 as in the following example:
359 .P
360 .in +4n
361 .EX
362 char c;
363 \&...
364 res = toupper((unsigned char) c);
365 .EE
366 .in
367 .P
368 This is necessary because
369 .I char
370 may be the equivalent of
371 .IR "signed char" ,
372 in which case a byte where the top bit is set would be sign extended when
373 converting to
374 .IR int ,
375 yielding a value that is outside the range of
376 .IR "unsigned char" .
377 .P
378 The details of what characters belong to which class depend on the
379 locale.
380 For example,
381 .BR isupper ()
382 will not recognize an A-umlaut (\(:A) as an uppercase letter in the default
383 .B "C"
384 locale.
385 .SH SEE ALSO
386 .BR iswalnum (3),
387 .BR iswalpha (3),
388 .BR iswblank (3),
389 .BR iswcntrl (3),
390 .BR iswdigit (3),
391 .BR iswgraph (3),
392 .BR iswlower (3),
393 .BR iswprint (3),
394 .BR iswpunct (3),
395 .BR iswspace (3),
396 .BR iswupper (3),
397 .BR iswxdigit (3),
398 .BR newlocale (3),
399 .BR setlocale (3),
400 .BR toascii (3),
401 .BR tolower (3),
402 .BR toupper (3),
403 .BR uselocale (3),
404 .BR ascii (7),
405 .BR locale (7)