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