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