original/man3/scanf.3

   1 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
   2 .\" 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 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"     This product includes software developed by the University of
  20 .\"     California, Berkeley and its contributors.
  21 .\" 4. Neither the name of the University nor the names of its contributors
  22 .\"    may be used to endorse or promote products derived from this software
  23 .\"    without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  35 .\" SUCH DAMAGE.
  36 .\" %%%LICENSE_END
  37 .\"
  38 .\"     @(#)scanf.3     6.14 (Berkeley) 1/8/93
  39 .\"
  40 .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu
  41 .\" modified to resemble the GNU libio setup used in the Linux libc
  42 .\" used in versions 4.x (x>4) and 5   Helmut.Geyer@iwr.uni-heidelberg.de
  43 .\" Modified, aeb, 970121
  44 .\" 2005-07-14, mtk, added description of %n$ form; various text
  45 .\"     incorporated from the GNU C library documentation ((C) The
  46 .\"     Free Software Foundation); other parts substantially rewritten.
  47 .\"
  48 .\" 2008-06-23, mtk
  49 .\"     Add ERRORS section.
  50 .\"     Document the 'a' and 'm' modifiers for dynamic string allocation.
  51 .\"
  52 .TH SCANF 3  2013-01-30 "GNU" "Linux Programmer's Manual"
  53 .SH NAME
  54 scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- input format conversion
  55 .SH SYNOPSIS
  56 .nf
  57 .B #include <stdio.h>
  58
  59 .BI "int scanf(const char *" format ", ...);"
  60 .BI "int fscanf(FILE *" stream ", const char *" format ", ...);"
  61 .BI "int sscanf(const char *" str ", const char *" format ", ...);"
  62 .sp
  63 .B #include <stdarg.h>
  64
  65 .BI "int vscanf(const char *" format ", va_list " ap );
  66 .BI "int vsscanf(const char *" str ", const char *" format ", va_list " ap );
  67 .BI "int vfscanf(FILE *" stream ", const char *" format ", va_list " ap );
  68 .fi
  69 .sp
  70 .in -4n
  71 Feature Test Macro Requirements for glibc (see
  72 .BR feature_test_macros (7)):
  73 .in
  74 .ad l
  75 .sp
  76 .BR vscanf (),
  77 .BR vsscanf (),
  78 .BR vfscanf ():
  79 .RS 4
  80 _XOPEN_SOURCE\ >=\ 600 || _ISOC99_SOURCE ||
  81 _POSIX_C_SOURCE\ >=\ 200112L;
  82 .br
  83 or
  84 .I "cc -std=c99"
  85 .ad
  86 .RE
  87 .SH DESCRIPTION
  88 The
  89 .BR scanf ()
  90 family of functions scans input according to
  91 .I format
  92 as described below.
  93 This format may contain
  94 .IR "conversion specifications" ;
  95 the results from such conversions, if any,
  96 are stored in the locations pointed to by the
  97 .I pointer
  98 arguments that follow
  99 .IR format .
 100 Each
 101 .I pointer
 102 argument must be of a type that is appropriate for the value returned
 103 by the corresponding conversion specification.
 104
 105 If the number of conversion specifications in
 106 .I format
 107 exceeds the number of
 108 .I pointer
 109 arguments, the results are undefined.
 110 If the number of
 111 .I pointer
 112 arguments exceeds the number of conversion specifications, then the excess
 113 .I pointer
 114 arguments are evaluated, but are otherwise ignored.
 115
 116 The
 117 .BR scanf ()
 118 function reads input from the standard input stream
 119 .IR stdin ,
 120 .BR fscanf ()
 121 reads input from the stream pointer
 122 .IR stream ,
 123 and
 124 .BR sscanf ()
 125 reads its input from the character string pointed to by
 126 .IR str .
 127 .PP
 128 The
 129 .BR vfscanf ()
 130 function is analogous to
 131 .BR vfprintf (3)
 132 and reads input from the stream pointer
 133 .I stream
 134 using a variable argument list of pointers (see
 135 .BR stdarg (3).
 136 The
 137 .BR vscanf ()
 138 function scans a variable argument list from the standard input and the
 139 .BR vsscanf ()
 140 function scans it from a string; these are analogous to the
 141 .BR vprintf (3)
 142 and
 143 .BR vsprintf (3)
 144 functions respectively.
 145 .PP
 146 The
 147 .I format
 148 string consists of a sequence of
 149 .I directives
 150 which describe how to process the sequence of input characters.
 151 If processing of a directive fails, no further input is read, and
 152 .BR scanf ()
 153 returns.
 154 A "failure" can be either of the following:
 155 .IR "input failure" ,
 156 meaning that input characters were unavailable, or
 157 .IR "matching failure" ,
 158 meaning that the input was inappropriate (see below).
 159
 160 A directive is one of the following:
 161 .TP
 162 \(bu
 163 A sequence of white-space characters (space, tab, newline, etc.; see
 164 .BR isspace (3)).
 165 This directive matches any amount of white space,
 166 including none, in the input.
 167 .TP
 168 \(bu
 169 An ordinary character (i.e., one other than white space or \(aq%\(aq).
 170 This character must exactly match the next character of input.
 171 .TP
 172 \(bu
 173 A conversion specification,
 174 which commences with a \(aq%\(aq (percent) character.
 175 A sequence of characters from the input is converted according to
 176 this specification, and the result is placed in the corresponding
 177 .I pointer
 178 argument.
 179 If the next item of input does not match the conversion specification,
 180 the conversion fails\(emthis is a
 181 .IR "matching failure" .
 182 .PP
 183 Each
 184 .I conversion specification
 185 in
 186 .I format
 187 begins with either the character \(aq%\(aq or the character sequence
 188 "\fB%\fP\fIn\fP\fB$\fP"
 189 (see below for the distinction) followed by:
 190 .TP
 191 \(bu
 192 An optional \(aq*\(aq assignment-suppression character:
 193 .BR scanf ()
 194 reads input as directed by the conversion specification,
 195 but discards the input.
 196 No corresponding
 197 .I pointer
 198 argument is required, and this specification is not
 199 included in the count of successful assignments returned by
 200 .BR scanf ().
 201 .TP
 202 \(bu
 203 An optional \(aqm\(aq character.
 204 This is used with string conversions
 205 .RI ( %s ,
 206 .IR %c ,
 207 .IR %[ ),
 208 and relieves the caller of the
 209 need to allocate a corresponding buffer to hold the input: instead,
 210 .BR scanf ()
 211 allocates a buffer of sufficient size,
 212 and assigns the address of this buffer to the corresponding
 213 .I pointer
 214 argument, which should be a pointer to a
 215 .I "char *"
 216 variable (this variable does not need to be initialized before the call).
 217 The caller should subsequently
 218 .BR free (3)
 219 this buffer when it is no longer required.
 220 .TP
 221 \(bu
 222 An optional decimal integer which specifies the
 223 .IR "maximum field width" .
 224 Reading of characters stops either when this maximum is reached or
 225 when a nonmatching character is found, whichever happens first.
 226 Most conversions discard initial white space characters (the exceptions
 227 are noted below),
 228 and these discarded characters don't count toward the maximum field width.
 229 String input conversions store a terminating null byte (\(aq\\0\(aq)
 230 to mark the end of the input;
 231 the maximum field width does not include this terminator.
 232 .TP
 233 \(bu
 234 An optional
 235 .IR "type modifier character" .
 236 For example, the
 237 .B l
 238 type modifier is used with integer conversions such as
 239 .B %d
 240 to specify that the corresponding
 241 .I pointer
 242 argument refers to a
 243 .I "long int"
 244 rather than a pointer to an
 245 .IR int .
 246 .TP
 247 \(bu
 248 A
 249 .I "conversion specifier"
 250 that specifies the type of input conversion to be performed.
 251 .PP
 252 The conversion specifications in
 253 .I format
 254 are of two forms, either beginning with \(aq%\(aq or beginning with
 255 "\fB%\fP\fIn\fP\fB$\fP".
 256 The two forms should not be mixed in the same
 257 .I format
 258 string, except that a string containing
 259 "\fB%\fP\fIn\fP\fB$\fP"
 260 specifications can include
 261 .B %%
 262 and
 263 .BR %* .
 264 If
 265 .I format
 266 contains \(aq%\(aq
 267 specifications then these correspond in order with successive
 268 .I pointer
 269 arguments.
 270 In the
 271 "\fB%\fP\fIn\fP\fB$\fP"
 272 form (which is specified in POSIX.1-2001, but not C99),
 273 .I n
 274 is a decimal integer that specifies that the converted input should
 275 be placed in the location referred to by the
 276 .IR n -th
 277 .I pointer
 278 argument following
 279 .IR format .
 280 .SS Conversions
 281 The following
 282 .I "type modifier characters"
 283 can appear in a conversion specification:
 284 .TP
 285 .B h
 286 Indicates that the conversion will be one of
 287 \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP
 288 and the next pointer is a pointer to a
 289 .I short int
 290 or
 291 .I unsigned short int
 292 (rather than
 293 .IR int ).
 294 .TP
 295 .B hh
 296 As for
 297 .BR h ,
 298 but the next pointer is a pointer to a
 299 .I signed char
 300 or
 301 .IR "unsigned char" .
 302 .TP
 303 .B j
 304 As for
 305 .BR h ,
 306 but the next pointer is a pointer to an
 307 .I intmax_t
 308 or a
 309 .IR uintmax_t .
 310 This modifier was introduced in C99.
 311 .TP
 312 .B l
 313 Indicates either that the conversion will be one of
 314 \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP
 315 and the next pointer is a pointer to a
 316 .I long int
 317 or
 318 .I unsigned long int
 319 (rather than
 320 .IR int ),
 321 or that the conversion will be one of
 322 \fBe\fP, \fBf\fP, or \fBg\fP
 323 and the next pointer is a pointer to
 324 .I double
 325 (rather than
 326 .IR float ).
 327 Specifying two
 328 .B l
 329 characters is equivalent to
 330 .BR L .
 331 If used with
 332 .B %c
 333 or
 334 .B %s
 335 the corresponding parameter is considered
 336 as a pointer to a wide character or wide-character string respectively.
 337 .\" This use of l was introduced in Amendment 1 to ISO C90.
 338 .TP
 339 .B L
 340 Indicates that the conversion will be either
 341 \fBe\fP, \fBf\fP, or \fBg\fP
 342 and the next pointer is a pointer to
 343 .I "long double"
 344 or the conversion will be
 345 \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, or \fBx\fP
 346 and the next pointer is a pointer to
 347 .IR "long long" .
 348 .\" MTK, Jul 05: The following is no longer true for modern
 349 .\" ANSI C (i.e., C99):
 350 .\" (Note that long long is not an
 351 .\" ANSI C
 352 .\" type. Any program using this will not be portable to all
 353 .\" architectures).
 354 .TP
 355 .B q
 356 equivalent to
 357 .BR L .
 358 This specifier does not exist in ANSI C.
 359 .TP
 360 .B t
 361 As for
 362 .BR h ,
 363 but the next pointer is a pointer to a
 364 .IR ptrdiff_t .
 365 This modifier was introduced in C99.
 366 .TP
 367 .B z
 368 As for
 369 .BR h ,
 370 but the next pointer is a pointer to a
 371 .IR size_t .
 372 This modifier was introduced in C99.
 373 .PP
 374 The following
 375 .I "conversion specifiers"
 376 are available:
 377 .TP
 378 .B %
 379 Matches a literal \(aq%\(aq.
 380 That is,
 381 .B %\&%
 382 in the format string matches a
 383 single input \(aq%\(aq character.
 384 No conversion is done (but initial white space characters are discarded),
 385 and assignment does not occur.
 386 .TP
 387 .B d
 388 Matches an optionally signed decimal integer;
 389 the next pointer must be a pointer to
 390 .IR int .
 391 .TP
 392 .B D
 393 Equivalent to
 394 .IR ld ;
 395 this exists only for backward compatibility.
 396 (Note: thus only in libc4.
 397 In libc5 and glibc the
 398 .B %D
 399 is silently ignored, causing old programs to fail mysteriously.)
 400 .TP
 401 .B i
 402 Matches an optionally signed integer; the next pointer must be a pointer to
 403 .IR int .
 404 The integer is read in base 16 if it begins with
 405 .I 0x
 406 or
 407 .IR 0X ,
 408 in base 8 if it begins with
 409 .IR 0 ,
 410 and in base 10 otherwise.
 411 Only characters that correspond to the base are used.
 412 .TP
 413 .B o
 414 Matches an unsigned octal integer; the next pointer must be a pointer to
 415 .IR "unsigned int" .
 416 .TP
 417 .B u
 418 Matches an unsigned decimal integer; the next pointer must be a
 419 pointer to
 420 .IR "unsigned int" .
 421 .TP
 422 .B x
 423 Matches an unsigned hexadecimal integer; the next pointer must
 424 be a pointer to
 425 .IR "unsigned int" .
 426 .TP
 427 .B X
 428 Equivalent to
 429 .BR x .
 430 .TP
 431 .B f
 432 Matches an optionally signed floating-point number; the next pointer must
 433 be a pointer to
 434 .IR float .
 435 .TP
 436 .B e
 437 Equivalent to
 438 .BR f .
 439 .TP
 440 .B g
 441 Equivalent to
 442 .BR f .
 443 .TP
 444 .B E
 445 Equivalent to
 446 .BR f .
 447 .TP
 448 .B a
 449 (C99) Equivalent to
 450 .BR f .
 451 .TP
 452 .B s
 453 Matches a sequence of non-white-space characters;
 454 the next pointer must be a pointer to character array that is
 455 long enough to hold the input sequence and
 456 the terminating null byte (\(aq\\0\(aq), which is added automatically.
 457 The input string stops at white space or at the maximum field
 458 width, whichever occurs first.
 459 .TP
 460 .B c
 461 Matches a sequence of characters whose length is specified by the
 462 .I maximum field width
 463 (default 1); the next pointer must be a pointer to
 464 .IR char ,
 465 and there must be enough room for all the characters (no terminating
 466 null byte
 467 is added).
 468 The usual skip of leading white space is suppressed.
 469 To skip white space first, use an explicit space in the format.
 470 .TP
 471 .B \&[
 472 Matches a nonempty sequence of characters from the specified set of
 473 accepted characters; the next pointer must be a pointer to
 474 .IR char ,
 475 and there must be enough room for all the characters in the string, plus a
 476 terminating null byte.
 477 The usual skip of leading white space is suppressed.
 478 The string is to be made up of characters in (or not in) a particular set;
 479 the set is defined by the characters between the open bracket
 480 .B [
 481 character and a close bracket
 482 .B ]
 483 character.
 484 The set
 485 .I excludes
 486 those characters if the first character after the open bracket is a
 487 circumflex
 488 .RB ( ^ ).
 489 To include a close bracket in the set, make it the first character after
 490 the open bracket or the circumflex; any other position will end the set.
 491 The hyphen character
 492 .B \-
 493 is also special; when placed between two other characters, it adds all
 494 intervening characters to the set.
 495 To include a hyphen, make it the last
 496 character before the final close bracket.
 497 For instance,
 498 .B [^]0\-9\-]
 499 means
 500 the set "everything except close bracket, zero through nine, and hyphen".
 501 The string ends with the appearance of a character not in the (or, with a
 502 circumflex, in) set or when the field width runs out.
 503 .TP
 504 .B p
 505 Matches a pointer value (as printed by
 506 .B %p
 507 in
 508 .BR printf (3);
 509 the next pointer must be a pointer to a pointer to
 510 .IR void .
 511 .TP
 512 .B n
 513 Nothing is expected; instead, the number of characters consumed thus far
 514 from the input is stored through the next pointer, which must be a pointer
 515 to
 516 .IR int .
 517 This is
 518 .I not
 519 a conversion, although it can be suppressed with the
 520 .B *
 521 assignment-suppression character.
 522 The C standard says: "Execution of a
 523 .B %n
 524 directive does not increment
 525 the assignment count returned at the completion of execution"
 526 but the Corrigendum seems to contradict this.
 527 Probably it is wise
 528 not to make any assumptions on the effect of
 529 .B %n
 530 conversions on the return value.
 531 .SH RETURN VALUE
 532 These functions return the number of input items
 533 successfully matched and assigned,
 534 which can be fewer than provided for,
 535 or even zero in the event of an early matching failure.
 536
 537 The value
 538 .B EOF
 539 is returned if the end of input is reached before either the first
 540 successful conversion or a matching failure occurs.
 541 .B EOF
 542 is also returned if a read error occurs,
 543 in which case the error indicator for the stream (see
 544 .BR ferror (3))
 545 is set, and
 546 .I errno
 547 is set indicate the error.
 548 .SH ERRORS
 549 .TP
 550 .B EAGAIN
 551 The file descriptor underlying
 552 .I stream
 553 is marked nonblocking, and the read operation would block.
 554 .TP
 555 .B EBADF
 556 The file descriptor underlying
 557 .I stream
 558 is invalid, or not open for reading.
 559 .TP
 560 .B EILSEQ
 561 Input byte sequence does not form a valid character.
 562 .TP
 563 .B EINTR
 564 The read operation was interrupted by a signal; see
 565 .BR signal (7).
 566 .TP
 567 .B EINVAL
 568 Not enough arguments; or
 569 .I format
 570 is NULL.
 571 .TP
 572 .B ENOMEM
 573 Out of memory.
 574 .TP
 575 .B ERANGE
 576 The result of an integer conversion would exceed the size
 577 that can be stored in the corresponding integer type.
 578 .SH CONFORMING TO
 579 The functions
 580 .BR fscanf (),
 581 .BR scanf (),
 582 and
 583 .BR sscanf ()
 584 conform to C89 and C99 and POSIX.1-2001.
 585 These standards do not specify the
 586 .B ERANGE
 587 error.
 588 .PP
 589 The
 590 .B q
 591 specifier is the 4.4BSD notation for
 592 .IR "long long" ,
 593 while
 594 .B ll
 595 or the usage of
 596 .B L
 597 in integer conversions is the GNU notation.
 598 .PP
 599 The Linux version of these functions is based on the
 600 .I GNU
 601 .I libio
 602 library.
 603 Take a look at the
 604 .I info
 605 documentation of
 606 .I GNU
 607 .I libc (glibc-1.08)
 608 for a more concise description.
 609 .SH NOTES
 610 The GNU C library supported the dynamic allocation conversion specifier
 611 (as a nonstandard extension) via the
 612 .B a
 613 character.  This feature
 614 seems to be present at least as far back as glibc 2.0.
 615 .PP
 616 It is not available if the program is compiled with
 617 .I "gcc -std=c99"
 618 or
 619 .IR "gcc -D_ISOC99_SOURCE"
 620 (unless
 621 .B _GNU_SOURCE
 622 is also specified), in which case the
 623 .B a
 624 is interpreted as a specifier for floating-point numbers (see above).
 625
 626 Since version 2.7, glibc also provides the
 627 .B m
 628 modifier for the same purpose as the
 629 .BR a
 630 modifier.
 631 The
 632 .B m
 633 modifier has the following advantages:
 634 .IP * 2
 635 It may also be applied to
 636 .B %c
 637 conversion specifiers (e.g.,
 638 .BR %3mc ).
 639 .IP *
 640 It avoids ambiguity with respect to the
 641 .B %a
 642 floating-point conversion specifier (and is unaffected by
 643 .IR "gcc -std=c99"
 644 etc.)
 645 .IP *
 646 It is specified in the POSIX.1-2008 standard.
 647 .SH BUGS
 648 All functions are fully C89 conformant, but provide the
 649 additional specifiers
 650 .B q
 651 and
 652 .B a
 653 as well as an additional behavior of the
 654 .B L
 655 and
 656 .B l
 657 specifiers.
 658 The latter may be considered to be a bug, as it changes the
 659 behavior of specifiers defined in C89.
 660 .PP
 661 Some combinations of the type modifiers and conversion
 662 specifiers defined by ANSI C do not make sense
 663 (e.g.,
 664 .BR "%Ld" ).
 665 While they may have a well-defined behavior on Linux, this need not
 666 to be so on other architectures.
 667 Therefore it usually is better to use
 668 modifiers that are not defined by ANSI C at all, that is, use
 669 .B q
 670 instead of
 671 .B L
 672 in combination with
 673 \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, and \fBX\fP
 674 conversions or
 675 .BR ll .
 676 .PP
 677 The usage of
 678 .B q
 679 is not the same as on 4.4BSD,
 680 as it may be used in float conversions equivalently to
 681 .BR L .
 682 .SH EXAMPLE
 683 To use the dynamic allocation conversion specifier, specify
 684 .B m
 685 as a length modifier (thus
 686 .B %ms
 687 or
 688 \fB%m[\fP\fIrange\fP\fB]\fP).
 689 The caller must
 690 .BR free (3)
 691 the returned string, as in the following example:
 692 .in +4n
 693 .nf
 694
 695 char *p;
 696 int n;
 697
 698 errno = 0;
 699 n = scanf("%m[a-z]", &p);
 700 if (n == 1) {
 701     printf("read: %s\\n", p);
 702     free(p);
 703 } else if (errno != 0) {
 704     perror("scanf");
 705 } else {
 706     fprintf(stderr, "No matching characters\\n");
 707 }
 708 .fi
 709 .in
 710 .PP
 711 As shown in the above example, it is necessary to call
 712 .BR free (3)
 713 only if the
 714 .BR scanf ()
 715 call successfully read a string.
 716 .SH SEE ALSO
 717 .BR getc (3),
 718 .BR printf (3),
 719 .BR setlocale (3),
 720 .BR strtod (3),
 721 .BR strtol (3),
 722 .BR strtoul (3)