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