man3/scanf.3

   1 '\" t
   2 .\" Copyright 2022 Alejandro Colomar <alx@kernel.org>
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH scanf 3 (date) "Linux man-pages (unreleased)"
   6 .SH NAME
   7 scanf, fscanf, vscanf, vfscanf \- input FILE format conversion
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <stdio.h>
  14 .P
  15 .BI "int scanf(const char *restrict " format ", ...);"
  16 .BI "int fscanf(FILE *restrict " stream ,
  17 .BI "           const char *restrict " format ", ...);"
  18 .P
  19 .B #include <stdarg.h>
  20 .P
  21 .BI "int vscanf(const char *restrict " format ", va_list " ap );
  22 .BI "int vfscanf(FILE *restrict " stream ,
  23 .BI "           const char *restrict " format ", va_list " ap );
  24 .fi
  25 .P
  26 .RS -4
  27 Feature Test Macro Requirements for glibc (see
  28 .BR feature_test_macros (7)):
  29 .RE
  30 .P
  31 .BR vscanf (),
  32 .BR vfscanf ():
  33 .nf
  34     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  35 .fi
  36 .SH DESCRIPTION
  37 The
  38 .BR scanf ()
  39 family of functions scans formatted input like
  40 .BR sscanf (3),
  41 but read from a
  42 .IR FILE .
  43 It is very difficult to use these functions correctly,
  44 and it is preferable to read entire lines with
  45 .BR fgets (3)
  46 or
  47 .BR getline (3)
  48 and parse them later with
  49 .BR sscanf (3)
  50 or more specialized functions such as
  51 .BR strtol (3).
  52 .P
  53 The
  54 .BR scanf ()
  55 function reads input from the standard input stream
  56 .I stdin
  57 and
  58 .BR fscanf ()
  59 reads input from the stream pointer
  60 .IR stream .
  61 .P
  62 The
  63 .BR vfscanf ()
  64 function is analogous to
  65 .BR vfprintf (3)
  66 and reads input from the stream pointer
  67 .I stream
  68 using a variable argument list of pointers (see
  69 .BR stdarg (3).
  70 The
  71 .BR vscanf ()
  72 function is analogous to
  73 .BR vprintf (3)
  74 and reads from the standard input.
  75 .SH RETURN VALUE
  76 On success, these functions return the number of input items
  77 successfully matched and assigned;
  78 this can be fewer than provided for,
  79 or even zero, in the event of an early matching failure.
  80 .P
  81 The value
  82 .B EOF
  83 is returned if the end of input is reached before either the first
  84 successful conversion or a matching failure occurs.
  85 .B EOF
  86 is also returned if a read error occurs,
  87 in which case the error indicator for the stream (see
  88 .BR ferror (3))
  89 is set, and
  90 .I errno
  91 is set to indicate the error.
  92 .SH ERRORS
  93 .TP
  94 .B EAGAIN
  95 The file descriptor underlying
  96 .I stream
  97 is marked nonblocking, and the read operation would block.
  98 .TP
  99 .B EBADF
 100 The file descriptor underlying
 101 .I stream
 102 is invalid, or not open for reading.
 103 .TP
 104 .B EILSEQ
 105 Input byte sequence does not form a valid character.
 106 .TP
 107 .B EINTR
 108 The read operation was interrupted by a signal; see
 109 .BR signal (7).
 110 .TP
 111 .B EINVAL
 112 Not enough arguments; or
 113 .I format
 114 is NULL.
 115 .TP
 116 .B ENOMEM
 117 Out of memory.
 118 .SH ATTRIBUTES
 119 For an explanation of the terms used in this section, see
 120 .BR attributes (7).
 121 .TS
 122 allbox;
 123 lbx lb lb
 124 l l l.
 125 Interface       Attribute       Value
 126 T{
 127 .na
 128 .nh
 129 .BR scanf (),
 130 .BR fscanf (),
 131 .BR vscanf (),
 132 .BR vfscanf ()
 133 T}      Thread safety   MT-Safe locale
 134 .TE
 135 .SH STANDARDS
 136 C11, POSIX.1-2008.
 137 .SH HISTORY
 138 C99, POSIX.1-2001.
 139 .SH CAVEATS
 140 These functions make it difficult to
 141 distinguish newlines from other white space,
 142 This is especially problematic with line-buffered input,
 143 like the standard input stream.
 144 .P
 145 These functions can't report errors after the last
 146 non-suppressed conversion specification.
 147 .SH BUGS
 148 It is impossible to accurately know
 149 how many characters these functions have consumed from the input stream,
 150 since they only report the number of successful conversions.
 151 For example,
 152 if the input is "123\en\ a",
 153 .I scanf(\[dq]%d\ %d\[dq], &a, &b)
 154 will consume the digits, the newline, and the space, but not the letter a.
 155 This makes it difficult to recover from invalid input.
 156 .SH SEE ALSO
 157 .BR fgets (3),
 158 .BR getline (3),
 159 .BR sscanf (3)