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>
|
---|
12 |
|
---|
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.
|
---|