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