Commit | Line | Data |
---|---|---|
858d320c KB |
1 | .\" Copyright (c) 1990 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3abda555 | 3 | .\" |
858d320c KB |
4 | .\" This code is derived from software contributed to Berkeley by |
5 | .\" Chris Torek. | |
6 | .\" | |
7 | .\" %sccs.include.redist.man% | |
8 | .\" | |
571f1310 | 9 | .\" @(#)scanf.3 6.4 (Berkeley) %G% |
858d320c KB |
10 | .\" |
11 | .TH SCANF 3 "" | |
12 | .UC 7 | |
3abda555 | 13 | .SH NAME |
571f1310 | 14 | scanf, fscanf, sscanf, vfscanf \- formatted input conversion |
3abda555 KM |
15 | .SH SYNOPSIS |
16 | .B #include <stdio.h> | |
17 | .PP | |
18 | .B scanf(format | |
858d320c | 19 | [ , pointer ... ] |
3abda555 KM |
20 | .B ) |
21 | .br | |
22 | .B char *format; | |
23 | .PP | |
24 | .B fscanf(stream, format | |
858d320c | 25 | [ , pointer ... ] |
3abda555 KM |
26 | .B ) |
27 | .br | |
28 | .SM | |
29 | .B FILE | |
30 | .B *stream; | |
31 | .br | |
32 | .B char *format; | |
33 | .PP | |
858d320c KB |
34 | .B sscanf(str, format |
35 | [ , pointer ... ] | |
3abda555 KM |
36 | .B ) |
37 | .br | |
571f1310 DS |
38 | .B char *str; |
39 | .br | |
40 | .B char *format; | |
41 | .PP | |
42 | .B #include <varargs.h> | |
43 | .PP | |
44 | .B vfscanf(stream, format, ap) | |
45 | .br | |
46 | .SM | |
47 | .B FILE | |
48 | .B *stream; | |
49 | .br | |
50 | .B char *format; | |
51 | .br | |
52 | .B va_list ap; | |
53 | .br | |
3abda555 | 54 | .SH DESCRIPTION |
858d320c KB |
55 | The |
56 | .I scanf | |
57 | family of functions scans input according to a | |
58 | .I format | |
59 | as described below. | |
60 | This format may contain | |
61 | .IR "conversion specifiers" ; | |
62 | the results from such conversions, if any, | |
63 | are stored through the | |
64 | .I pointer | |
65 | arguments. | |
3abda555 | 66 | .I Scanf |
858d320c KB |
67 | reads the standard input stream |
68 | .BR stdin , | |
69 | .I fscanf | |
70 | reads the named input | |
71 | .IR stream , | |
72 | and | |
73 | .I sscanf | |
3abda555 | 74 | reads from the character string |
858d320c | 75 | .IR str . |
571f1310 DS |
76 | .I Vfscanf |
77 | is analogous to | |
78 | .I vfprintf | |
79 | and reads from a named input | |
80 | .I stream | |
81 | using a variable argument list of pointers (see | |
82 | .IR varargs (3)). | |
858d320c | 83 | Each successive |
3abda555 | 84 | .I pointer |
858d320c KB |
85 | argument must correspond properly with |
86 | each successive conversion specifier | |
87 | (but see `suppression' below). | |
88 | All conversions are introduced by the | |
89 | .B % | |
90 | (percent sign) character. | |
3abda555 | 91 | The |
858d320c KB |
92 | .I format |
93 | string | |
94 | may also contain other characters. | |
95 | White space (such as blanks, tabs, or newlines) in the | |
96 | .I format | |
97 | string match any amount of white space, including none, in the input. | |
98 | Everything else | |
99 | matches only itself. | |
100 | Scanning stops | |
101 | when an input character does not match such a format character. | |
102 | Scanning also stops | |
103 | when an input conversion cannot be made (see below). | |
104 | ||
105 | .SH CONVERSIONS | |
106 | Following the | |
107 | .B % | |
108 | character introducing a conversion | |
109 | there may be a number of | |
110 | .I flag | |
111 | characters, as follows: | |
3abda555 | 112 | .TP 4 |
858d320c KB |
113 | .B * |
114 | suppresses assignment. | |
115 | The conversion that follows occurs as usual, but no pointer is used; | |
116 | the result of the conversion is simply discarded. | |
3abda555 | 117 | .TP 4 |
858d320c KB |
118 | .B h |
119 | indicates that the conversion will be one of | |
120 | .B dioux | |
121 | or | |
122 | .B n | |
123 | and the next pointer is a pointer to a | |
124 | .B short int | |
125 | (rather than | |
126 | .BR int ). | |
3abda555 | 127 | .TP 4 |
858d320c KB |
128 | .B l |
129 | indicates either that the conversion will be one of | |
130 | .B dioux | |
131 | or | |
132 | .B n | |
133 | and the next pointer is a pointer to a | |
134 | .B long int | |
135 | (rather than | |
136 | .BR int ), | |
137 | or that the conversion will be one of | |
138 | .B efg | |
139 | and the next pointer is a pointer to | |
140 | .B double | |
141 | (rather than | |
142 | .BR float ). | |
143 | .TP 4 | |
144 | .B L | |
145 | indicates that the conversion will be | |
146 | .B efg | |
147 | and the next pointer is a pointer to | |
148 | .BR "long double" . | |
149 | (This type is not implemented; the | |
150 | .B L | |
151 | flag is currently ignored.) | |
3abda555 | 152 | .PP |
858d320c KB |
153 | In addition to these flags, |
154 | there may be an optional maximum field width, | |
155 | expressed as a decimal integer, | |
156 | between the | |
157 | .B % | |
158 | and the conversion. | |
159 | If no width is given, | |
160 | a default of `infinity' is used (with one exception, below); | |
161 | otherwise at most this many characters are scanned | |
162 | in processing the conversion. | |
163 | Before conversion begins, | |
164 | most conversions skip white space; | |
165 | this white space is not counted against the field width. | |
3abda555 | 166 | .PP |
858d320c | 167 | The following conversions are available: |
3abda555 | 168 | .TP 4 |
858d320c KB |
169 | .B % |
170 | matches a literal `%'. | |
171 | That is, `%%' in the format string | |
172 | matches a single input `%' character. | |
173 | No conversion is done, and no assignment occurs. | |
3abda555 | 174 | .TP 4 |
858d320c | 175 | .B d |
3abda555 | 176 | a decimal integer is expected; |
858d320c KB |
177 | the next pointer must be a pointer to |
178 | .BR int . | |
179 | .TP 4 | |
180 | .B D | |
181 | equivalent to | |
182 | .BR ld ; | |
183 | this exists only for backwards compatibility. | |
184 | .TP 4 | |
185 | .B i | |
186 | an integer is expected; | |
187 | the next pointer must be a pointer to | |
188 | .BR int . | |
189 | The integer is read in base 16 if it begins with `0x' or `0X', | |
190 | in base 8 if it begins with `0', and in base 10 otherwise. | |
191 | Only characters that correspond to the base are used. | |
3abda555 | 192 | .TP 4 |
858d320c | 193 | .B o |
3abda555 | 194 | an octal integer is expected; |
858d320c KB |
195 | the next pointer must be a pointer to |
196 | .BR "unsigned int" . | |
197 | .TP 4 | |
198 | .B O | |
199 | equivalent to | |
200 | .BR lo ; | |
201 | this exists for backwards compatibility. | |
202 | .TP 4 | |
203 | .B u | |
204 | a signed or unsigned decimal integer is expected; | |
205 | the next pointer must be a pointer to | |
206 | .BR "unsigned int" . | |
3abda555 | 207 | .TP 4 |
858d320c KB |
208 | .B x |
209 | a signed or unsigned hexadecimal integer is expected; | |
210 | the next pointer must be a pointer to | |
211 | .BR "unsigned int" . | |
212 | .TP 4 | |
213 | .B X | |
214 | equivalent to | |
215 | .BR lx ; | |
216 | this violates the ANSI C standard X3.159-1989, | |
217 | but is backwards compatible with previous | |
218 | .UX | |
219 | systems. | |
220 | .TP 4 | |
221 | .B f | |
222 | a floating-point number is expected; | |
223 | the next pointer must be a pointer to | |
224 | .BR float . | |
225 | .TP 4 | |
226 | .B e | |
227 | equivalent to | |
228 | .BR f . | |
3abda555 | 229 | .TP 4 |
858d320c KB |
230 | .B g |
231 | equivalent to | |
232 | .BR f . | |
3abda555 | 233 | .TP 4 |
858d320c KB |
234 | .B E |
235 | equivalent to | |
236 | .BR lf ; | |
237 | this violates the ANSI C standard X3.159-1989, | |
238 | but is backwards compatible with previous | |
239 | .UX | |
240 | systems. | |
3abda555 | 241 | .TP 4 |
858d320c KB |
242 | .B F |
243 | equivalent to | |
244 | .BR lf ; | |
245 | this exists only for backwards compatibility. | |
3abda555 | 246 | .TP 4 |
858d320c KB |
247 | .B s |
248 | a string is expected; | |
249 | the next pointer must be a pointer to | |
250 | .BR char , | |
251 | and there must be enough room for all the characters in the string, | |
252 | plus a terminating `\e0'. | |
253 | The input string stops at white space | |
254 | or at the maximum field width, whichever occurs first. | |
255 | .TP 4 | |
256 | .B c | |
257 | .I width | |
258 | characters (default 1) are expected; | |
259 | the next pointer must be a pointer to | |
260 | .BR char , | |
261 | and there must be enough room for all the characters | |
262 | (no terminating `\e0' is added). | |
263 | The usual skip of leading white space is suppressed. | |
264 | To skip white space first, use an explicit space in the format. | |
265 | .TP 4 | |
266 | .B [ | |
267 | a string is expected; | |
268 | the next pointer must be a pointer to | |
269 | .BR char , | |
270 | and there must be enough room for all the characters in the string, | |
271 | plus a terminating `\e0'. | |
272 | The usual skip of leading white space is suppressed. | |
273 | The string is to be made up of characters in | |
274 | (or not in) | |
275 | a particular set; | |
276 | the set is defined by the characters between the open bracket | |
277 | .B [ | |
278 | character | |
279 | and a close bracket | |
280 | .B ] | |
281 | character. | |
282 | The set | |
283 | .I excludes | |
284 | those characters | |
285 | if the first character after the open bracket is a circumflex | |
286 | .BR ^ . | |
287 | To include a close bracket in the set, | |
288 | make it the first character after the open bracket | |
289 | or the circumflex; | |
290 | any other position will end the set. | |
291 | The hyphen character | |
292 | .B \- | |
293 | is also special; | |
294 | when placed between two other characters, | |
295 | it adds all intervening characters to the set. | |
296 | To include a hyphen, | |
297 | make it the last character before the final close bracket. | |
298 | For instance, `[^]0-9-]' | |
299 | means the set `everything except close bracket, zero through nine, | |
300 | and hyphen'. | |
301 | The string ends at the first character not in | |
302 | (or, with a circumflex, in) | |
303 | the set, or when the field width runs out. | |
304 | .TP 4 | |
305 | .B p | |
306 | a pointer value (as printed by `%p' in | |
307 | .IR printf (3)) | |
308 | is expected; | |
309 | the next pointer must be a pointer to | |
310 | .BR void . | |
311 | .TP 4 | |
312 | .B n | |
313 | nothing is expected; | |
314 | instead, the number of characters consumed thus far from the input | |
315 | is stored through the next pointer, | |
316 | which must be a pointer to | |
317 | .BR int . | |
318 | This is | |
319 | .I not | |
320 | a conversion, although it can be suppressed with the | |
321 | .B * | |
322 | flag. | |
3abda555 | 323 | .PP |
858d320c KB |
324 | For backwards compatibility, |
325 | other conversion characters (except '\e0') | |
326 | are taken as if they were `%d' or, if uppercase, `%ld', | |
327 | and a `conversion' of `%\e0' causes an immediate return of | |
328 | .SM | |
329 | .BR EOF . | |
330 | The | |
331 | .B F | |
3abda555 | 332 | and |
858d320c KB |
333 | .B X |
334 | conversions will be changed in the future | |
335 | to conform to the ANSI C standard, | |
336 | after which they will act like | |
3abda555 | 337 | .B f |
3abda555 KM |
338 | and |
339 | .B x | |
858d320c | 340 | respectively. |
3abda555 KM |
341 | .PP |
342 | The | |
343 | .I scanf | |
858d320c | 344 | functions return the number of successfully assigned conversions, or |
3abda555 KM |
345 | .SM |
346 | .B EOF | |
858d320c KB |
347 | if nothing was assigned |
348 | before the end of input (or an error during input) was encountered. | |
349 | A return value of 0 | |
350 | indicates that, while there was input available, | |
351 | no conversions were assigned; | |
352 | typically this is due to an invalid input character, | |
353 | such as an alphabetic character for a `%d' conversion. | |
3abda555 | 354 | .SH "SEE ALSO" |
858d320c KB |
355 | strtol(3), |
356 | strtoul(3), | |
86198885 KB |
357 | getc(3), |
358 | printf(3) | |
858d320c | 359 | .SH "RETURN VALUE" |
3abda555 KM |
360 | The |
361 | .I scanf | |
362 | functions return | |
363 | .SM | |
364 | .B EOF | |
365 | on end of input, | |
858d320c | 366 | or a short count for missing or illegal data items. |
3abda555 | 367 | .SH BUGS |
858d320c KB |
368 | The current situation with |
369 | .B %F | |
370 | and | |
371 | .B %X | |
372 | conversions is unfortunate. | |
373 | .br | |
374 | All of the backwards compatibility formats will be removed in the future. | |
571f1310 DS |
375 | .br |
376 | There is no | |
377 | .I vscanf | |
378 | or | |
379 | .IR vsscanf . | |
380 | .\" Had to draw the line somewhere! |