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