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