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