| blob | 7743d2ef1a48015f0d5c1443810a84188c4e48cc |
1 .\" @(#)scanf.3s 6.1 (Berkeley) 5/15/85
2 .\"
3 .TH SCANF 3 "May 15, 1985"
4 .AT 3
5 .SH NAME
6 scanf, fscanf, sscanf, vscanf, vfscanf, vsscanf \- formatted input conversion
7 .SH SYNOPSIS
8 .nf
9 .ft B
10 #include <stdio.h>
11 #include <stdarg.h>
13 int scanf(const char *\fIformat\fP \fR[\fP, \fIpointer\fP\fR] ...\fP)
14 int fscanf(FILE *\fIstream\fP, const char *\fIformat\fP \fR[\fP, \fIpointer\fP\fR] ...\fP)
15 int sscanf(const char *\fIs\fP, const char *\fIformat\fP \fR[\fP, \fIpointer\fP\fR] ...\fP)
16 int vscanf(const char *\fIformat\fP, va_list \fIargs\fP)
17 int vfscanf(FILE *\fIstream\fP, const char *\fIformat\fP, va_list \fIargs\fP)
18 int vsscanf(const char *\fIs\fP, const char *\fIformat\fP, va_list \fIargs\fP)
19 .SH DESCRIPTION
20 .B Scanf
21 reads from the standard input stream
22 .BR stdin .
23 .B Fscanf
24 reads from the named input
25 .IR stream .
26 .B Sscanf
27 reads from the character string
28 .IR s .
29 Each function reads characters, interprets
30 them according to a format, and stores the results in its arguments.
31 Each expects as arguments
32 a control string
33 .IR format ,
34 described below,
35 and a set of
36 .I pointer
37 arguments
38 indicating where the converted input should be stored.
39 .PP
40 The
41 .B v*scanf
42 functions can be used to make functions like the first three by using the
43 .BR stdarg (3)
44 method to process the argument pointers.
45 .PP
46 The
47 control string
48 usually contains
49 conversion specifications, which are used to direct interpretation
50 of input sequences.
51 The control string may contain:
52 .TP 4
53 1.
54 Blanks, tabs or newlines,
55 which match optional white space in the input.
56 .TP 4
57 2.
58 An ordinary character (not %) which must match
59 the next character of the input stream.
60 .TP 4
61 3.
62 Conversion specifications, consisting of the
63 character
64 .BR % ,
65 an optional assignment suppressing character
66 .BR * ,
67 an optional numerical maximum field width, and a conversion
68 character.
69 .PP
70 A conversion specification directs the conversion of the
71 next input field; the result
72 is placed in the variable pointed to by the corresponding argument,
73 unless assignment suppression was
74 indicated by
75 .BR * .
76 An input field is defined as a string of non-space characters;
77 it extends to the next inappropriate character or until the field
78 width, if specified, is exhausted.
79 .PP
80 The conversion character indicates the interpretation of the
81 input field; the corresponding pointer argument must
82 usually be of a restricted type.
83 The following conversion characters are legal:
84 .TP 4
85 .B %
86 a single `%' is expected
87 in the input at this point;
88 no assignment is done.
89 .TP 4
90 .B d
91 a decimal integer is expected;
92 the corresponding argument should be an integer pointer.
93 .TP 4
94 .B o
95 an octal integer is expected;
96 the corresponding argument should be a integer pointer.
97 .TP 4
98 .B x
99 a hexadecimal integer is expected;
100 the corresponding argument should be an integer pointer.
101 .ti -0.2i
102 .TP 4
103 .B s
104 a character string is expected;
105 the corresponding argument should be a character pointer
106 pointing to an array of characters large enough to accept the
107 string and a terminating `\e0', which will be added.
108 The input field is terminated by a space character
109 or a newline.
110 .TP 4
111 .B c
112 a character is expected; the
113 corresponding argument should be a character pointer.
114 The normal skip over space characters is suppressed
115 in this case;
116 to read the next non-space character, try
117 `%1s'.
118 If a field width is given, the corresponding argument
119 should refer to a character array, and the
120 indicated number of characters is read.
121 .TP 4
122 .B efg
123 a floating point number is expected;
124 the next field is converted accordingly and stored through the
125 corresponding argument, which should be a pointer to a
126 .BR float .
127 The input format for
128 floating point numbers is
129 an optionally signed
130 string of digits
131 possibly containing a decimal point, followed by an optional
132 exponent field consisting of an E or e followed by an optionally signed integer.
133 .TP 4
134 .B [
135 indicates a string not to be delimited by space characters.
136 The left bracket is followed by a set of characters and a right
137 bracket; the characters between the brackets define a set
138 of characters making up the string.
139 If the first character
140 is not circumflex (\|^\|), the input field
141 is all characters until the first character not in the set between
142 the brackets; if the first character
143 after the left bracket is ^, the input field is all characters
144 until the first character which is in the remaining set of characters
145 between the brackets.
146 The corresponding argument must point to a character array.
147 .PP
148 The conversion characters
149 .BR d ,
150 .B o
151 and
152 .B x
153 may be capitalized or preceded by
154 .B l
155 to indicate that a pointer to
156 .B long
157 rather than to
158 .B int
159 is in the argument list.
160 Similarly, the conversion characters
161 .BR e ,
162 .B f
163 or
164 .B g
165 may be capitalized or
166 preceded by
167 .B l
168 to indicate a pointer to
169 .B double
170 rather than to
171 .BR float .
172 The conversion characters
173 .BR d ,
174 .B o
175 and
176 .B x
177 may be preceded by
178 .B h
179 to indicate a pointer to
180 .B short
181 rather than to
182 .BR int .
183 .PP
184 The
185 .B scanf
186 functions return the number of successfully matched and assigned input
187 items.
188 This can be used to decide how many input items were found.
189 The constant
190 .SM
191 .B EOF
192 is returned upon end of input; note that this is different
193 from 0, which means that no conversion was done;
194 if conversion was intended, it was frustrated by an
195 inappropriate character in the input.
196 .PP
197 For example, the call
198 .IP "\&" 10
199 int i; float x; char name[50];
200 .br
201 scanf("%d%f%s", &i, &x, name);
202 .PP
203 with the input line
204 .IP
205 25 54.32E\(mi1 thompson
206 .PP
207 will assign to
208 .B i
209 the value
210 25,
211 .B x
212 the value 5.432, and
213 .B name
214 will contain `\fBthompson\e0\fP' .
215 Or,
216 .IP
217 int i; float x; char name[50];
218 .br
219 scanf("%2d%f%*d%[1234567890]", &i, &x, name);
220 .PP
221 with input
222 .IP
223 56789 0123 56a72
224 .PP
225 will assign 56 to
226 .BR i ,
227 789.0 to
228 .BR x ,
229 skip `0123',
230 and place the string `56\e0' in
231 .BR name .
232 The next call to
233 .B getchar
234 will return `a'.
235 .SH "SEE ALSO"
236 .BR atof (3),
237 .BR getc (3),
238 .BR printf (3),
239 .BR stdarg (3).
240 .SH DIAGNOSTICS
241 The
242 .B scanf
243 functions return
244 .SM
245 .B EOF
246 on end of input,
247 and a short count for missing or illegal data items.
248 .SH BUGS
249 The success of literal matches and suppressed
250 assignments is not directly
251 determinable.