Debian Codegraph @

upstream/debian-unstable/man3/scanf.3

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