share/man/man3c/ctype.3c

   1 '\" te
   2 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   3 .\" Copyright 2016 Joyent, Inc.
   4 .\" Copyright 1989 AT&T.  Copyright (c) 1992, X/Open Company Limited  All Rights Reserved.  Portions Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   8 .\"  This notice shall appear on any product containing this material.
   9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  12 .TH CTYPE 3C "Mar 14, 2016"
  13 .SH NAME
  14 ctype, isalpha, isalnum, isascii, isblank, iscntrl, isdigit, islower,
  15 isprint, isspace, isupper, ispunct, isgraph, isxdigit, isalpha_l,
  16 isalnum_l, isblank_l, iscntrl_l, isdigit_l, islower_l, isprint_l,
  17 isspace_l, isupper_l, ispunct_l, isgraph_l, isxdigit_l \- character handling
  18 .SH SYNOPSIS
  19 .LP
  20 .nf
  21 #include <ctype.h>
  22
  23 \fBint\fR \fBisalpha\fR(\fBint\fR \fIc\fR);
  24 .fi
  25 .LP
  26 .nf
  27 \fBint\fR \fBisalnum\fR(\fBint\fR \fIc\fR);
  28 .fi
  29 .LP
  30 .nf
  31 \fBint\fR \fBisascii\fR(\fBint\fR \fIc\fR);
  32 .fi
  33 .LP
  34 .nf
  35 \fBint\fR \fBisblank\fR(\fBint\fR \fIc\fR);
  36 .fi
  37 .LP
  38 .nf
  39 \fBint\fR \fBiscntrl\fR(\fBint\fR \fIc\fR);
  40 .fi
  41 .LP
  42 .nf
  43 \fBint\fR \fBisdigit\fR(\fBint\fR \fIc\fR);
  44 .fi
  45 .LP
  46 .nf
  47 \fBint\fR \fBisgraph\fR(\fBint\fR \fIc\fR);
  48 .fi
  49 .LP
  50 .nf
  51 \fBint\fR \fBislower\fR(\fBint\fR \fIc\fR);
  52 .fi
  53 .LP
  54 .nf
  55 \fBint\fR \fBisprint\fR(\fBint\fR \fIc\fR);
  56 .fi
  57 .LP
  58 .nf
  59 \fBint\fR \fBispunct\fR(\fBint\fR \fIc\fR);
  60 .fi
  61 .LP
  62 .nf
  63 \fBint\fR \fBisspace\fR(\fBint\fR \fIc\fR);
  64 .fi
  65 .LP
  66 .nf
  67 \fBint\fR \fBisupper\fR(\fBint\fR \fIc\fR);
  68 .fi
  69 .LP
  70 .nf
  71 \fBint\fR \fBisxdigit\fR(\fBint\fR \fIc\fR);
  72 .fi
  73 .LP
  74 .nf
  75 \fBint\fR \fBisalpha_l\fR(\fBint\fR \fIc\fR, \fBlocale_t\fR \fIloc\fR);
  76 .fi
  77 .LP
  78 .nf
  79 \fBint\fR \fBisalnum_l\fR(\fBint\fR \fIc\fR, \fBlocale_t\fR \fIloc\fR);
  80 .fi
  81 .LP
  82 .nf
  83 \fBint\fR \fBisblank_l\fR(\fBint\fR \fIc\fR, \fBlocale_t\fR \fIloc\fR);
  84 .fi
  85 .LP
  86 .nf
  87 \fBint\fR \fBiscntrl_l\fR(\fBint\fR \fIc\fR, \fBlocale_t\fR \fIloc\fR);
  88 .fi
  89 .LP
  90 .nf
  91 \fBint\fR \fBisdigit_l\fR(\fBint\fR \fIc\fR, \fBlocale_t\fR \fIloc\fR);
  92 .fi
  93 .LP
  94 .nf
  95 \fBint\fR \fBisgraph_l\fR(\fBint\fR \fIc\fR, \fBlocale_t\fR \fIloc\fR);
  96 .fi
  97 .LP
  98 .nf
  99 \fBint\fR \fBislower_l\fR(\fBint\fR \fIc\fR, \fBlocale_t\fR \fIloc\fR);
 100 .fi
 101 .LP
 102 .nf
 103 \fBint\fR \fBisprint_l\fR(\fBint\fR \fIc\fR, \fBlocale_t\fR \fIloc\fR);
 104 .fi
 105 .LP
 106 .nf
 107 \fBint\fR \fBispunct_l\fR(\fBint\fR \fIc\fR, \fBlocale_t\fR \fIloc\fR);
 108 .fi
 109 .LP
 110 .nf
 111 \fBint\fR \fBisspace_l\fR(\fBint\fR \fIc\fR, \fBlocale_t\fR \fIloc\fR);
 112 .fi
 113 .LP
 114 .nf
 115 \fBint\fR \fBisupper_l\fR(\fBint\fR \fIc\fR, \fBlocale_t\fR \fIloc\fR);
 116 .fi
 117 .LP
 118 .nf
 119 \fBint\fR \fBisxdigit_l\fR(\fBint\fR \fIc\fR, \fBlocale_t\fR \fIloc\fR);
 120 .fi
 121 .SH DESCRIPTION
 122 .LP
 123 These functions classify character-coded integer values. Each is a
 124 predicate returning non-zero for true, \fB0\fR for false. The behavior
 125 of these macros, except \fBisascii()\fR, is affected by the current
 126 locale (see \fBsetlocale\fR(3C) and \fBuselocale\fR(3C)). To modify
 127 the behavior, change the \fBLC_TYPE\fR category in \fBsetlocale()\fR, that is,
 128 \fBsetlocale(\fR\fBLC_CTYPE\fR, \fInewlocale\fR). In the "C" locale,
 129 or in a locale where character type information is not defined,
 130 characters are classified according to the rules of the \fBUS-ASCII\fR
 131 7-bit coded character set.
 132 .LP
 133 The functions \fBisalnum_l()\fR, \fBisalpha_l()\fR, \fBisblank_l()\fR,
 134 \fBiscntrl_l\fR, \fBisdigit_l()\fR, \fBisgraph_l()\fr,
 135 \fBislower_l()\fR, \fBisprint_l()\fR, \fBispunct_l()\fR,
 136 \fBisspace_l()\fR, \fBisupper_l()\fR, and \fBisxdigit_l()\fR all behave
 137 identically to their counterparts without the '\fB_l\fR' prefix, except
 138 that instead of acting on the current locale, they perform the test on
 139 the locale specified in the argument \fIloc\fR.
 140 .LP
 141 The \fBisascii()\fR macro is defined on all integer values. The rest are
 142 defined only where the argument is an \fBint\fR, the value of which is
 143 representable as an \fBunsigned char\fR, or \fBEOF\fR, which is defined by the
 144 <\fBstdio.h\fR> header and represents end-of-file.
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fBisalpha()\fR\fR
 149 .ad
 150 .RS 13n
 151 Tests for any character for which \fBisupper()\fR or \fBislower()\fR is true,
 152 or any character that is one of the current locale-defined set of characters
 153 for which none of \fBiscntrl()\fR, \fBisdigit()\fR, \fBispunct()\fR, or
 154 \fBisspace()\fR is true. In "C" locale, \fBisalpha()\fR returns true only for
 155 the characters for which \fBisupper()\fR or \fBislower()\fR is true.
 156 .RE
 157
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBisalnum()\fR\fR
 162 .ad
 163 .RS 13n
 164 Tests for any character for which \fBisalpha()\fR or \fBisdigit()\fR is true
 165 (letter or digit).
 166 .RE
 167
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBisascii()\fR\fR
 172 .ad
 173 .RS 13n
 174 Tests for any ASCII character, code between \fB0\fR and \fB0177\fR inclusive.
 175 .RE
 176
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fBisblank()\fR\fR
 181 .ad
 182 .RS 13n
 183 Tests whether \fIc\fR is a character of class blank in the current locale. This
 184 macro/function is not available to applications conforming to standards prior
 185 to SUSv3. See \fBstandards\fR(5)
 186 .RE
 187
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fBiscntrl()\fR\fR
 192 .ad
 193 .RS 13n
 194 Tests for any ``control character'' as defined by the character set.
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fBisdigit()\fR\fR
 201 .ad
 202 .RS 13n
 203 Tests for any decimal-digit character.
 204 .RE
 205
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fBisgraph()\fR\fR
 210 .ad
 211 .RS 13n
 212 Tests for any character for which \fBisalnum()\fR and \fBispunct()\fR are true,
 213 or any character in the current locale-defined "graph" class which is neither a
 214 space ("\|") nor a character for which \fBiscntrl()\fR is true.
 215 .RE
 216
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fBislower()\fR\fR
 221 .ad
 222 .RS 13n
 223 Tests for any character that is a lower-case letter or is one of the current
 224 locale-defined set of characters for which none of \fBiscntrl()\fR,
 225 \fBisdigit()\fR, \fBispunct()\fR, \fBisspace()\fR, or \fBisupper()\fR is true.
 226 In the "C" locale, \fBislower()\fR returns true only for the characters defined
 227 as lower-case \fBASCII\fR characters.
 228 .RE
 229
 230 .sp
 231 .ne 2
 232 .na
 233 \fB\fBisprint()\fR\fR
 234 .ad
 235 .RS 13n
 236 Tests for any character for which \fBiscntrl()\fR is false, and
 237 \fBisalnum()\fR, \fBisgraph()\fR, \fBispunct()\fR, the space character ("\|"),
 238 and the characters in the current locale-defined "print" class are true.
 239 .RE
 240
 241 .sp
 242 .ne 2
 243 .na
 244 \fB\fBispunct()\fR\fR
 245 .ad
 246 .RS 13n
 247 Tests for any printing character which is neither a space ("\|") nor a
 248 character for which \fBisalnum()\fR or \fBiscntrl()\fR is true.
 249 .RE
 250
 251 .sp
 252 .ne 2
 253 .na
 254 \fB\fBisspace()\fR\fR
 255 .ad
 256 .RS 13n
 257 Tests for any space, tab, carriage-return, newline, vertical-tab or form-feed
 258 (standard white-space characters) or for one of the current locale-defined set
 259 of characters for which \fBisalnum()\fR is false.  In the "C" locale,
 260 \fBisspace()\fR returns true only for the standard white-space characters.
 261 .RE
 262
 263 .sp
 264 .ne 2
 265 .na
 266 \fB\fBisupper()\fR\fR
 267 .ad
 268 .RS 13n
 269 Tests for any character that is an upper-case letter or is one of the current
 270 locale-defined set of characters for which none of \fBiscntrl()\fR,
 271 \fBisdigit()\fR, \fBispunct()\fR, \fBisspace()\fR, or \fBislower()\fR is true.
 272 In the "C" locale, \fBisupper()\fR returns true only for the characters defined
 273 as upper-case \fBASCII\fR characters.
 274 .RE
 275
 276 .sp
 277 .ne 2
 278 .na
 279 \fB\fBisxdigit()\fR\fR
 280 .ad
 281 .RS 14n
 282 Tests for any hexadecimal-digit character (\fB[0\(mi9]\fR, \fB[A\(miF]\fR, or
 283 \fB[a\(mif]\fR or the current locale-defined sets of characters representing
 284 the hexadecimal digits \fB10\fR to \fB15\fR inclusive). In the "C" locale, only
 285 .sp
 286 .in +2
 287 .nf
 288 0 1 2 3 4 5 6 7 8 9 A B C D E F a b c d e f
 289 .fi
 290 .in -2
 291
 292 are included.
 293 .RE
 294
 295 .SH RETURN VALUES
 296 .LP
 297 If the argument to any of the character handling macros is not in the domain of
 298 the function, the result is undefined. Otherwise, the macro or function returns
 299 non-zero if the classification is \fBTRUE\fR and \fB0\fR if the classification
 300 is \fBFALSE\fR.
 301 .SH ATTRIBUTES
 302 .LP
 303 See \fBattributes\fR(5) for descriptions of the following attributes:
 304 .TS
 305 box;
 306 c | c
 307 l | l .
 308 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 309 _
 310 CSI     Enabled
 311 _
 312 Interface Stability     Standard
 313 _
 314 MT-Level        MT-Safe
 315 .TE
 316
 317 .SH SEE ALSO
 318 .LP
 319 \fBnewlocale\fR(3C), \fBsetlocale\fR(3C), \fBuselocale\fR(3C),
 320 \fBstdio\fR(3C), \fBascii\fR(5), \fBenviron\fR(5),
 321 \fBstandards\fR(5)