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