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