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