lib/libc/stdio/wscanf.3

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