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