lib/libc/stdio/wscanf.3

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