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