lib/libc/stdio/wscanf.3

   1 .\" Copyright (c) 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Chris Torek and the American National Standards Committee X3,
   6 .\" on Information Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)scanf.3     8.2 (Berkeley) 12/11/93
  33 .\" FreeBSD: src/lib/libc/stdio/scanf.3,v 1.24 2003/06/28 09:03:25 das Exp
  34 .\" $FreeBSD: head/lib/libc/stdio/wscanf.3 235363 2012-05-12 20:27:13Z joel $
  35 .\"
  36 .Dd July 5, 2003
  37 .Dt WSCANF 3
  38 .Os
  39 .Sh NAME
  40 .Nm wscanf ,
  41 .Nm fwscanf ,
  42 .Nm swscanf ,
  43 .Nm vwscanf ,
  44 .Nm vswscanf ,
  45 .Nm vfwscanf
  46 .Nd wide character input format conversion
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In stdio.h
  51 .In wchar.h
  52 .Ft int
  53 .Fn wscanf "const wchar_t * restrict format" ...
  54 .Ft int
  55 .Fn fwscanf "FILE * restrict stream" "const wchar_t * restrict format" ...
  56 .Ft int
  57 .Fn swscanf "const wchar_t * restrict str" "const wchar_t * restrict format" ...
  58 .In stdarg.h
  59 .Ft int
  60 .Fn vwscanf "const wchar_t * restrict format" "va_list ap"
  61 .Ft int
  62 .Fn vswscanf "const wchar_t * restrict str" "const wchar_t * restrict format" "va_list ap"
  63 .Ft int
  64 .Fn vfwscanf "FILE * restrict stream" "const wchar_t * restrict format" "va_list ap"
  65 .Sh DESCRIPTION
  66 The
  67 .Fn wscanf
  68 family of functions scans input according to a
  69 .Fa format
  70 as described below.
  71 This format may contain
  72 .Em conversion specifiers ;
  73 the results from such conversions, if any,
  74 are stored through the
  75 .Em pointer
  76 arguments.
  77 The
  78 .Fn wscanf
  79 function
  80 reads input from the standard input stream
  81 .Dv stdin ,
  82 .Fn fwscanf
  83 reads input from the stream pointer
  84 .Fa stream ,
  85 and
  86 .Fn swscanf
  87 reads its input from the wide character string pointed to by
  88 .Fa str .
  89 The
  90 .Fn vfwscanf
  91 function
  92 is analogous to
  93 .Xr vfwprintf 3
  94 and reads input from the stream pointer
  95 .Fa stream
  96 using a variable argument list of pointers (see
  97 .Xr stdarg 3 ) .
  98 The
  99 .Fn vwscanf
 100 function scans a variable argument list from the standard input and
 101 the
 102 .Fn vswscanf
 103 function scans it from a wide character string;
 104 these are analogous to
 105 the
 106 .Fn vwprintf
 107 and
 108 .Fn vswprintf
 109 functions respectively.
 110 Each successive
 111 .Em pointer
 112 argument must correspond properly with
 113 each successive conversion specifier
 114 (but see the
 115 .Cm *
 116 conversion below).
 117 All conversions are introduced by the
 118 .Cm %
 119 (percent sign) character.
 120 The
 121 .Fa format
 122 string
 123 may also contain other characters.
 124 White space (such as blanks, tabs, or newlines) in the
 125 .Fa format
 126 string match any amount of white space, including none, in the input.
 127 Everything else
 128 matches only itself.
 129 Scanning stops
 130 when an input character does not match such a format character.
 131 Scanning also stops
 132 when an input conversion cannot be made (see below).
 133 .Sh CONVERSIONS
 134 Following the
 135 .Cm %
 136 character introducing a conversion
 137 there may be a number of
 138 .Em flag
 139 characters, as follows:
 140 .Bl -tag -width ".Cm l No (ell)"
 141 .It Cm *
 142 Suppresses assignment.
 143 The conversion that follows occurs as usual, but no pointer is used;
 144 the result of the conversion is simply discarded.
 145 .It Cm hh
 146 Indicates that the conversion will be one of
 147 .Cm dioux
 148 or
 149 .Cm n
 150 and the next pointer is a pointer to a
 151 .Vt char
 152 (rather than
 153 .Vt int ) .
 154 .It Cm h
 155 Indicates that the conversion will be one of
 156 .Cm dioux
 157 or
 158 .Cm n
 159 and the next pointer is a pointer to a
 160 .Vt "short int"
 161 (rather than
 162 .Vt int ) .
 163 .It Cm l No (ell)
 164 Indicates that the conversion will be one of
 165 .Cm dioux
 166 or
 167 .Cm n
 168 and the next pointer is a pointer to a
 169 .Vt "long int"
 170 (rather than
 171 .Vt int ) ,
 172 that the conversion will be one of
 173 .Cm a , e , f ,
 174 or
 175 .Cm g
 176 and the next pointer is a pointer to
 177 .Vt double
 178 (rather than
 179 .Vt float ) ,
 180 or that the conversion will be one of
 181 .Cm c
 182 or
 183 .Cm s
 184 and the next pointer is a pointer to an array of
 185 .Vt wchar_t
 186 (rather than
 187 .Vt char ) .
 188 .It Cm ll No (ell ell)
 189 Indicates that the conversion will be one of
 190 .Cm dioux
 191 or
 192 .Cm n
 193 and the next pointer is a pointer to a
 194 .Vt "long long int"
 195 (rather than
 196 .Vt int ) .
 197 .It Cm L
 198 Indicates that the conversion will be one of
 199 .Cm a , e , f ,
 200 or
 201 .Cm g
 202 and the next pointer is a pointer to
 203 .Vt "long double" .
 204 .It Cm j
 205 Indicates that the conversion will be one of
 206 .Cm dioux
 207 or
 208 .Cm n
 209 and the next pointer is a pointer to a
 210 .Vt intmax_t
 211 (rather than
 212 .Vt int ) .
 213 .It Cm t
 214 Indicates that the conversion will be one of
 215 .Cm dioux
 216 or
 217 .Cm n
 218 and the next pointer is a pointer to a
 219 .Vt ptrdiff_t
 220 (rather than
 221 .Vt int ) .
 222 .It Cm z
 223 Indicates that the conversion will be one of
 224 .Cm dioux
 225 or
 226 .Cm n
 227 and the next pointer is a pointer to a
 228 .Vt size_t
 229 (rather than
 230 .Vt int ) .
 231 .It Cm q
 232 (deprecated.)
 233 Indicates that the conversion will be one of
 234 .Cm dioux
 235 or
 236 .Cm n
 237 and the next pointer is a pointer to a
 238 .Vt "long long int"
 239 (rather than
 240 .Vt int ) .
 241 .El
 242 .Pp
 243 In addition to these flags,
 244 there may be an optional maximum field width,
 245 expressed as a decimal integer,
 246 between the
 247 .Cm %
 248 and the conversion.
 249 If no width is given,
 250 a default of
 251 .Dq infinity
 252 is used (with one exception, below);
 253 otherwise at most this many characters are scanned
 254 in processing the conversion.
 255 Before conversion begins,
 256 most conversions skip white space;
 257 this white space is not counted against the field width.
 258 .Pp
 259 The following conversions are available:
 260 .Bl -tag -width XXXX
 261 .It Cm %
 262 Matches a literal
 263 .Ql % .
 264 That is,
 265 .Dq Li %%
 266 in the format string
 267 matches a single input
 268 .Ql %
 269 character.
 270 No conversion is done, and assignment does not occur.
 271 .It Cm d
 272 Matches an optionally signed decimal integer;
 273 the next pointer must be a pointer to
 274 .Vt int .
 275 .It Cm i
 276 Matches an optionally signed integer;
 277 the next pointer must be a pointer to
 278 .Vt int .
 279 The integer is read in base 16 if it begins
 280 with
 281 .Ql 0x
 282 or
 283 .Ql 0X ,
 284 in base 8 if it begins with
 285 .Ql 0 ,
 286 and in base 10 otherwise.
 287 Only characters that correspond to the base are used.
 288 .It Cm o
 289 Matches an octal integer;
 290 the next pointer must be a pointer to
 291 .Vt "unsigned int" .
 292 .It Cm u
 293 Matches an optionally signed decimal integer;
 294 the next pointer must be a pointer to
 295 .Vt "unsigned int" .
 296 .It Cm x , X
 297 Matches an optionally signed hexadecimal integer;
 298 the next pointer must be a pointer to
 299 .Vt "unsigned int" .
 300 .It Cm a , A , e , E , f , F , g , G
 301 Matches a floating-point number in the style of
 302 .Xr wcstod 3 .
 303 The next pointer must be a pointer to
 304 .Vt float
 305 (unless
 306 .Cm l
 307 or
 308 .Cm L
 309 is specified.)
 310 .It Cm s
 311 Matches a sequence of non-white-space wide characters;
 312 the next pointer must be a pointer to
 313 .Vt char ,
 314 and the array must be large enough to accept the multibyte representation
 315 of all the sequence and the
 316 terminating
 317 .Dv NUL
 318 character.
 319 The input string stops at white space
 320 or at the maximum field width, whichever occurs first.
 321 .Pp
 322 If an
 323 .Cm l
 324 qualifier is present, the next pointer must be a pointer to
 325 .Vt wchar_t ,
 326 into which the input will be placed.
 327 .It Cm S
 328 The same as
 329 .Cm ls .
 330 .It Cm c
 331 Matches a sequence of
 332 .Em width
 333 count
 334 wide characters (default 1);
 335 the next pointer must be a pointer to
 336 .Vt char ,
 337 and there must be enough room for the multibyte representation
 338 of all the characters
 339 (no terminating
 340 .Dv NUL
 341 is added).
 342 The usual skip of leading white space is suppressed.
 343 To skip white space first, use an explicit space in the format.
 344 .Pp
 345 If an
 346 .Cm l
 347 qualifier is present, the next pointer must be a pointer to
 348 .Vt wchar_t ,
 349 into which the input will be placed.
 350 .It Cm C
 351 The same as
 352 .Cm lc .
 353 .It Cm \&[
 354 Matches a nonempty sequence of characters from the specified set
 355 of accepted characters;
 356 the next pointer must be a pointer to
 357 .Vt char ,
 358 and there must be enough room for the multibyte representation of
 359 all the characters in the string,
 360 plus a terminating
 361 .Dv NUL
 362 character.
 363 The usual skip of leading white space is suppressed.
 364 The string is to be made up of characters in
 365 (or not in)
 366 a particular set;
 367 the set is defined by the characters between the open bracket
 368 .Cm \&[
 369 character
 370 and a close bracket
 371 .Cm \&]
 372 character.
 373 The set
 374 .Em excludes
 375 those characters
 376 if the first character after the open bracket is a circumflex
 377 .Cm ^ .
 378 To include a close bracket in the set,
 379 make it the first character after the open bracket
 380 or the circumflex;
 381 any other position will end the set.
 382 To include a hyphen in the set,
 383 make it the last character before the final close bracket;
 384 some implementations of
 385 .Fn wscanf
 386 use
 387 .Dq Li A-Z
 388 to represent the range of characters between
 389 .Ql A
 390 and
 391 .Ql Z .
 392 The string ends with the appearance of a character not in the
 393 (or, with a circumflex, in) set
 394 or when the field width runs out.
 395 .Pp
 396 If an
 397 .Cm l
 398 qualifier is present, the next pointer must be a pointer to
 399 .Vt wchar_t ,
 400 into which the input will be placed.
 401 .It Cm p
 402 Matches a pointer value (as printed by
 403 .Ql %p
 404 in
 405 .Xr wprintf 3 ) ;
 406 the next pointer must be a pointer to
 407 .Vt void .
 408 .It Cm n
 409 Nothing is expected;
 410 instead, the number of characters consumed thus far from the input
 411 is stored through the next pointer,
 412 which must be a pointer to
 413 .Vt int .
 414 This is
 415 .Em not
 416 a conversion, although it can be suppressed with the
 417 .Cm *
 418 flag.
 419 .El
 420 .Pp
 421 The decimal point
 422 character is defined in the program's locale (category
 423 .Dv LC_NUMERIC ) .
 424 .Pp
 425 For backwards compatibility, a
 426 .Dq conversion
 427 of
 428 .Ql %\e0
 429 causes an immediate return of
 430 .Dv EOF .
 431 .Sh RETURN VALUES
 432 These
 433 functions
 434 return
 435 the number of input items assigned, which can be fewer than provided
 436 for, or even zero, in the event of a matching failure.
 437 Zero
 438 indicates that, while there was input available,
 439 no conversions were assigned;
 440 typically this is due to an invalid input character,
 441 such as an alphabetic character for a
 442 .Ql %d
 443 conversion.
 444 The value
 445 .Dv EOF
 446 is returned if an input failure occurs before any conversion such as an
 447 end-of-file occurs.
 448 If an error or end-of-file occurs after conversion
 449 has begun,
 450 the number of conversions which were successfully completed is returned.
 451 .Sh SEE ALSO
 452 .Xr fgetwc 3 ,
 453 .Xr scanf 3 ,
 454 .Xr wcrtomb 3 ,
 455 .Xr wcstod 3 ,
 456 .Xr wcstol 3 ,
 457 .Xr wcstoul 3 ,
 458 .Xr wprintf 3
 459 .Sh STANDARDS
 460 The
 461 .Fn fwscanf ,
 462 .Fn wscanf ,
 463 .Fn swscanf ,
 464 .Fn vfwscanf ,
 465 .Fn vwscanf
 466 and
 467 .Fn vswscanf
 468 functions
 469 conform to
 470 .St -isoC-99 .
 471 .Sh BUGS
 472 In addition to the bugs documented in
 473 .Xr scanf 3 ,
 474 .Fn wscanf
 475 does not support the
 476 .Dq Li A-Z
 477 notation for specifying character ranges with the character
 478 class conversion
 479 .Pq Sq Cm %[ .