]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" This code is derived from software contributed to Berkeley by | |
5 | .\" Chris Torek and the American National Standards Committee X3, | |
6 | .\" on Information Processing Systems. | |
7 | .\" | |
8 | .\" Redistribution and use in source and binary forms, with or without | |
9 | .\" modification, are permitted provided that the following conditions | |
10 | .\" are met: | |
11 | .\" 1. Redistributions of source code must retain the above copyright | |
12 | .\" notice, this list of conditions and the following disclaimer. | |
13 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
14 | .\" notice, this list of conditions and the following disclaimer in the | |
15 | .\" documentation and/or other materials provided with the distribution. | |
16 | .\" 3. All advertising materials mentioning features or use of this software | |
17 | .\" must display the following acknowledgement: | |
18 | .\" This product includes software developed by the University of | |
19 | .\" California, Berkeley and its contributors. | |
20 | .\" 4. Neither the name of the University nor the names of its contributors | |
21 | .\" may be used to endorse or promote products derived from this software | |
22 | .\" without specific prior written permission. | |
23 | .\" | |
24 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
25 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
26 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
27 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
28 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
29 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
30 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
31 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
32 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
33 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
34 | .\" SUCH DAMAGE. | |
35 | .\" | |
36 | .\" @(#)scanf.3 6.14 (Berkeley) 1/8/93 | |
37 | .\" | |
38 | .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu | |
39 | .\" modified to resemble the GNU libio setup used in the Linux libc | |
40 | .\" used in versions 4.x (x>4) and 5 Helmut.Geyer@iwr.uni-heidelberg.de | |
41 | .\" Modified, aeb, 970121 | |
991910a4 MK |
42 | .\" 2005-07-14, mtk, added description of %n$ form; various text |
43 | .\" incorporated from the GNU C library documentation ((C) The | |
44 | .\" Free Software Foundation); other parts substantially rewritten. | |
fea681da MK |
45 | .\" |
46 | .TH SCANF 3 1995-11-01 "LINUX MANPAGE" "Linux Programmer's Manual" | |
47 | .SH NAME | |
48 | scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- input format conversion | |
49 | .SH SYNOPSIS | |
50 | .nf | |
51 | .B #include <stdio.h> | |
52 | .na | |
53 | .BI "int scanf(const char *" format ", ..." ); | |
54 | .br | |
55 | .BI "int fscanf(FILE *" stream ", const char *" format ", ..." ); | |
56 | .br | |
57 | .BI "int sscanf(const char *" str ", const char *" format ", ..." ); | |
58 | .sp | |
59 | .B #include <stdarg.h> | |
60 | .BI "int vscanf(const char *" format ", va_list " ap ); | |
61 | .br | |
62 | .BI "int vsscanf(const char *" str ", const char *" format ", va_list " ap ); | |
63 | .br | |
64 | .BI "int vfscanf(FILE *" stream ", const char *" format ", va_list " ap ); | |
65 | .ad | |
66 | .SH DESCRIPTION | |
67 | The | |
e511ffb6 | 68 | .BR scanf () |
991910a4 | 69 | family of functions scans input according to |
fea681da MK |
70 | .I format |
71 | as described below. This format may contain | |
991910a4 MK |
72 | .IR "conversion specifications" ; |
73 | the results from such conversions, if any, | |
74 | are stored in the locations pointed to by the | |
75 | .I pointer | |
76 | arguments that follow | |
77 | .IR format . | |
78 | Each | |
fea681da | 79 | .I pointer |
991910a4 MK |
80 | argument must be of a type that is appropriate for the value returned |
81 | by the corresponding conversion specification. | |
82 | ||
83 | If the number of conversion specifications in | |
84 | .I format | |
85 | exceeds the number of | |
86 | .I pointer | |
87 | arguments, the results are undefined. | |
88 | If the number of | |
89 | .I pointer | |
90 | arguments exceeds the number of conversion specifications, then the excess | |
91 | .I pointer | |
92 | arguments are evaluated, but are otherwise ignored. | |
93 | ||
94 | The | |
e511ffb6 | 95 | .BR scanf () |
fea681da MK |
96 | function reads input from the standard input stream |
97 | .IR stdin , | |
e511ffb6 | 98 | .BR fscanf () |
fea681da MK |
99 | reads input from the stream pointer |
100 | .IR stream , | |
101 | and | |
e511ffb6 | 102 | .BR sscanf () |
fea681da MK |
103 | reads its input from the character string pointed to by |
104 | .IR str . | |
105 | .PP | |
106 | The | |
e511ffb6 | 107 | .BR vfscanf () |
fea681da MK |
108 | function is analogous to |
109 | .BR vfprintf (3) | |
110 | and reads input from the stream pointer | |
111 | .I stream | |
112 | using a variable argument list of pointers (see | |
113 | .BR stdarg (3). | |
114 | The | |
e511ffb6 | 115 | .BR vscanf () |
fea681da | 116 | function scans a variable argument list from the standard input and the |
e511ffb6 | 117 | .BR vsscanf () |
fea681da | 118 | function scans it from a string; these are analogous to the |
e1d6264d | 119 | .BR vprintf () |
fea681da | 120 | and |
e1d6264d | 121 | .BR vsprintf () |
fea681da MK |
122 | functions respectively. |
123 | .PP | |
991910a4 MK |
124 | The |
125 | .I format | |
126 | string consists of a sequence of | |
127 | .IR directives | |
128 | which describe how to process the sequence of input characters. | |
129 | If processing of a directive fails, no further input is read, and | |
e511ffb6 | 130 | .BR scanf () |
991910a4 MK |
131 | returns. |
132 | A "failure" can be either of the following: | |
133 | .IR "input failure" , | |
134 | meaning that input characters were unavailable, or | |
135 | .IR "matching failure" , | |
136 | meaning that the input was inappropriate (see below). | |
137 | ||
138 | A directive is one of the following: | |
139 | .TP | |
140 | \(bu | |
141 | A sequence of white-space characters (space, tab, newline, etc; see | |
142 | .BR isspace (3)). | |
143 | This directive matches any amount of white space, | |
144 | including none, in the input. | |
145 | .TP | |
146 | \(bu | |
147 | An ordinary character (i.e., one other than white space or '%'). | |
148 | This character must exactly match the next character of input. | |
149 | .TP | |
150 | \(bu | |
151 | A conversion specification, which commences with a '%' (percent) character. | |
152 | A sequence of characters from the input is converted according to | |
153 | this specification, and the result is placed in the corresponding | |
fea681da | 154 | .I pointer |
991910a4 MK |
155 | argument. |
156 | If the next item of input does not match the the conversion specification, | |
157 | the conversion fails \(em this is a | |
158 | .IR "matching failure" . | |
159 | .PP | |
160 | Each | |
161 | .I conversion specification | |
162 | in | |
163 | .I format | |
164 | begins with either the character '%' or the character sequence | |
165 | "\fB%\fP\fIn\fP\fB$\fP" | |
166 | (see below for the distinction; see below) followed by: | |
167 | .TP | |
168 | \(bu | |
169 | An optional '*' assignment-suppression character: | |
e511ffb6 | 170 | .BR scanf () |
991910a4 MK |
171 | reads input as directed by the conversion specification, |
172 | but discards the input. | |
173 | No corresponding | |
174 | .I pointer | |
175 | argument is required, and this specification is not | |
176 | included in the count of successful assignments returned by | |
e511ffb6 | 177 | .BR scanf (). |
991910a4 MK |
178 | .TP |
179 | \(bu | |
180 | An optional 'a' character. | |
181 | This is used with string conversions, and relieves the caller of the | |
182 | need to allocate a corresponding buffer to hold the input: instead, | |
e511ffb6 | 183 | .BR scanf () |
991910a4 MK |
184 | allocates a buffer of sufficient size, |
185 | and assigns the address of this buffer to the corresponding | |
186 | .I pointer | |
187 | argument, which should be a pointer to a | |
188 | .I "char *" | |
189 | variable (this variable does not need to be initialised before the call). | |
190 | The caller should subsequently | |
191 | .BR free (3) | |
192 | this buffer when it is no longer required. | |
193 | This is a GNU extension; | |
194 | C99 employs the 'a' character as a conversion specifier (and | |
195 | it can also be used as such in the GNU implementation). | |
196 | .TP | |
197 | \(bu | |
198 | An optional decimal integer which specifies the | |
199 | .IR "maximum field width" . | |
200 | Reading of characters stops either when this maximum is reached or | |
201 | when a non-matching character is found, whichever happens first. | |
202 | Most conversions discard initial whitespace characters (the exceptions | |
203 | are noted below), | |
204 | and these discarded characters don't count towards the maximum field width. | |
205 | String input conversions store a null terminator ('\\0') | |
206 | to mark the end of the input; | |
207 | the maximum field width does not include this terminator. | |
208 | .TP | |
209 | \(bu | |
210 | An optional | |
211 | .IR "type modifier character" . | |
212 | For example, the | |
213 | .B l | |
214 | type modifier is used with integer conversions such as | |
215 | .I %d | |
216 | to specify that the corresponding | |
217 | .I pointer | |
218 | argument refers to a | |
219 | .I "long int" | |
220 | rather than a pointer to an | |
221 | .IR int . | |
222 | .TP | |
223 | \(bu | |
224 | A | |
225 | .I "conversion specifier" | |
226 | that specifies the type of input conversion to be performed. | |
227 | .PP | |
228 | The conversion specifications in | |
fea681da | 229 | .I format |
991910a4 MK |
230 | are of two forms, either beginning with '%' or beginning with |
231 | "\fB%\fP\fIn\fP\fB$\fP". | |
232 | The two forms should not be mixed in the same | |
fea681da | 233 | .I format |
991910a4 MK |
234 | string, except that a string containing |
235 | "\fB%\fP\fIn\fP\fB$\fP" | |
236 | specifications can include | |
237 | .I %% | |
238 | and | |
239 | .IR %* . | |
240 | If | |
241 | .I format | |
242 | contains '%' | |
243 | specifications then these correspond in order with successive | |
244 | .I pointer | |
245 | arguments. | |
246 | In the | |
247 | "\fB%\fP\fIn\fP\fB$\fP" | |
248 | form (which is specified in SUSv3, but not C99), | |
249 | .I n | |
250 | is a decimal integer that specifies that the converted input should | |
251 | be placed in the location referred to by the | |
252 | .IR n -th | |
253 | .I pointer | |
254 | argument following | |
255 | .IR format . | |
fea681da | 256 | .SH CONVERSIONS |
991910a4 MK |
257 | The following |
258 | .IR "type modifier characters" | |
259 | can appear in a conversion specification: | |
fea681da MK |
260 | .TP |
261 | .B h | |
262 | Indicates that the conversion will be one of | |
991910a4 | 263 | .B diouxX |
fea681da MK |
264 | or |
265 | .B n | |
266 | and the next pointer is a pointer to a | |
991910a4 MK |
267 | .I short int |
268 | or | |
269 | .I unsigned short int | |
fea681da MK |
270 | (rather than |
271 | .IR int ). | |
272 | .TP | |
991910a4 MK |
273 | .B hh |
274 | As for | |
275 | .BR h , | |
276 | but the next pointer is a pointer to a | |
277 | .I signed char | |
278 | or | |
279 | .IR "unsigned char" . | |
280 | .TP | |
281 | .B j | |
282 | As for | |
283 | .BR h , | |
284 | but the next pointer is a pointer to a | |
285 | .I intmax_t | |
286 | or | |
287 | .IR uintmax_t . | |
288 | This modifier was introduced in C99. | |
289 | .TP | |
fea681da MK |
290 | .B l |
291 | Indicates either that the conversion will be one of | |
991910a4 | 292 | .B diouxX |
fea681da MK |
293 | or |
294 | .B n | |
295 | and the next pointer is a pointer to a | |
991910a4 MK |
296 | .I long int |
297 | or | |
298 | .I unsigned long int | |
fea681da MK |
299 | (rather than |
300 | .IR int ), | |
301 | or that the conversion will be one of | |
302 | .B efg | |
303 | and the next pointer is a pointer to | |
304 | .I double | |
305 | (rather than | |
306 | .IR float ). | |
307 | Specifying two | |
308 | .B l | |
991910a4 MK |
309 | characters is equivalent to |
310 | .BR L . | |
311 | If used with | |
312 | .I %c | |
313 | or | |
314 | .I %s | |
315 | the corresponding parameter is considered | |
316 | as a pointer to a wide character or wide character string respectively. | |
317 | .\" This use of l was introduced in Amendment 1 to ISO C90. | |
fea681da MK |
318 | .TP |
319 | .B L | |
320 | Indicates that the conversion will be either | |
321 | .B efg | |
322 | and the next pointer is a pointer to | |
323 | .IR "long double" | |
324 | or the conversion will be | |
325 | .B dioux | |
326 | and the next pointer is a pointer to | |
327 | .IR "long long" . | |
991910a4 MK |
328 | .\" MTK, Jul 05: The following is no longer true for modern |
329 | .\" ANSI C (i.e., C99): | |
330 | .\" (Note that long long is not an | |
331 | .\" ANSI C | |
332 | .\" type. Any program using this will not be portable to all | |
333 | .\" architectures). | |
fea681da MK |
334 | .TP |
335 | .B q | |
991910a4 MK |
336 | equivalent to |
337 | .BR L . | |
338 | This specifier does not exist in ANSI C. | |
339 | .TP | |
340 | .B t | |
341 | As for | |
342 | .BR h , | |
343 | but the next pointer is a pointer to a | |
344 | .IR ptrdiff_t . | |
345 | This modifier was introduced in C99. | |
346 | .TP | |
347 | .B z | |
348 | As for | |
349 | .BR h , | |
350 | but the next pointer is a pointer to a | |
351 | .IR size_t . | |
352 | This modifier was introduced in C99. | |
fea681da | 353 | .PP |
991910a4 MK |
354 | The following |
355 | .I "conversion specifiers" | |
356 | are available: | |
fea681da MK |
357 | .TP |
358 | .B % | |
991910a4 MK |
359 | Matches a literal '%'. That is, |
360 | .I %\&% | |
361 | in the format string matches a | |
362 | single input '%' character. No conversion is done, and assignment does not | |
fea681da MK |
363 | occur. |
364 | .TP | |
365 | .B d | |
366 | Matches an optionally signed decimal integer; | |
367 | the next pointer must be a pointer to | |
368 | .IR int . | |
369 | .TP | |
370 | .B D | |
371 | Equivalent to | |
991910a4 | 372 | .IR ld ; |
fea681da | 373 | this exists only for backwards compatibility. |
991910a4 MK |
374 | (Note: thus only in libc4. In libc5 and glibc the |
375 | .I %D | |
376 | is silently ignored, causing old programs to fail mysteriously.) | |
fea681da MK |
377 | .TP |
378 | .B i | |
379 | Matches an optionally signed integer; the next pointer must be a pointer to | |
380 | .IR int . | |
991910a4 MK |
381 | The integer is read in base 16 if it begins with |
382 | .I 0x | |
383 | or | |
384 | .IR 0X , | |
385 | in base 8 if it begins with | |
386 | .IR 0 , | |
387 | and in base 10 otherwise. | |
388 | Only characters that correspond to the base are used. | |
fea681da MK |
389 | .TP |
390 | .B o | |
391 | Matches an unsigned octal integer; the next pointer must be a pointer to | |
392 | .IR "unsigned int" . | |
393 | .TP | |
394 | .B u | |
395 | Matches an unsigned decimal integer; the next pointer must be a | |
396 | pointer to | |
397 | .IR "unsigned int" . | |
398 | .TP | |
399 | .B x | |
400 | Matches an unsigned hexadecimal integer; the next pointer must | |
401 | be a pointer to | |
402 | .IR "unsigned int" . | |
403 | .TP | |
404 | .B X | |
405 | Equivalent to | |
406 | .BR x . | |
407 | .TP | |
408 | .B f | |
409 | Matches an optionally signed floating-point number; the next pointer must | |
410 | be a pointer to | |
411 | .IR float . | |
412 | .TP | |
413 | .B e | |
414 | Equivalent to | |
415 | .BR f . | |
416 | .TP | |
417 | .B g | |
418 | Equivalent to | |
419 | .BR f . | |
420 | .TP | |
421 | .B E | |
422 | Equivalent to | |
423 | .BR f . | |
424 | .TP | |
991910a4 MK |
425 | .B a |
426 | (C99) Equivalent to | |
427 | .BR f . | |
428 | .TP | |
fea681da | 429 | .B s |
991910a4 MK |
430 | Matches a sequence of non-white-space characters; |
431 | the next pointer must be a pointer to character array that is | |
432 | long enough to hold the input sequence and the terminating null | |
433 | character ('\\0'), which is added automatically. | |
434 | The input string stops at white space or at the maximum field | |
fea681da MK |
435 | width, whichever occurs first. |
436 | .TP | |
437 | .B c | |
991910a4 MK |
438 | Matches a sequence of characters whose length is specified by the |
439 | .I maximum field width | |
440 | (default 1); the next pointer must be a pointer to | |
fea681da MK |
441 | .IR char , |
442 | and there must be enough room for all the characters (no terminating | |
991910a4 | 443 | null character |
fea681da MK |
444 | is added). The usual skip of leading white space is suppressed. To skip |
445 | white space first, use an explicit space in the format. | |
446 | .TP | |
447 | .B \&[ | |
448 | Matches a nonempty sequence of characters from the specified set of | |
449 | accepted characters; the next pointer must be a pointer to | |
450 | .IR char , | |
451 | and there must be enough room for all the characters in the string, plus a | |
991910a4 MK |
452 | terminating null character. |
453 | The usual skip of leading white space is suppressed. The | |
fea681da MK |
454 | string is to be made up of characters in (or not in) a particular set; the |
455 | set is defined by the characters between the open bracket | |
456 | .B [ | |
457 | character and a close bracket | |
458 | .B ] | |
459 | character. The set | |
460 | .I excludes | |
461 | those characters if the first character after the open bracket is a | |
462 | circumflex | |
991910a4 | 463 | .RR ( ^ ). |
fea681da MK |
464 | To include a close bracket in the set, make it the first character after |
465 | the open bracket or the circumflex; any other position will end the set. | |
466 | The hyphen character | |
8c383102 | 467 | .B \- |
fea681da MK |
468 | is also special; when placed between two other characters, it adds all |
469 | intervening characters to the set. To include a hyphen, make it the last | |
991910a4 | 470 | character before the final close bracket. For instance, |
34131745 | 471 | .B [^]0\-9\-] |
991910a4 MK |
472 | means |
473 | the set "everything except close bracket, zero through nine, and hyphen". | |
fea681da MK |
474 | The string ends with the appearance of a character not in the (or, with a |
475 | circumflex, in) set or when the field width runs out. | |
476 | .TP | |
477 | .B p | |
991910a4 MK |
478 | Matches a pointer value (as printed by |
479 | .I %p | |
480 | in | |
fea681da | 481 | .BR printf (3); |
475f1bca | 482 | the next pointer must be a pointer to a pointer to |
fea681da MK |
483 | .IR void . |
484 | .TP | |
485 | .B n | |
486 | Nothing is expected; instead, the number of characters consumed thus far | |
487 | from the input is stored through the next pointer, which must be a pointer | |
488 | to | |
489 | .IR int . | |
490 | This is | |
491 | .I not | |
492 | a conversion, although it can be suppressed with the | |
493 | .B * | |
991910a4 MK |
494 | assignment-suppression character. |
495 | The C standard says: "Execution of a | |
496 | .I %n | |
497 | directive does not increment | |
498 | the assignment count returned at the completion of execution" | |
fea681da | 499 | but the Corrigendum seems to contradict this. Probably it is wise |
991910a4 MK |
500 | not to make any assumptions on the effect of |
501 | .I %n | |
502 | conversions on the return value. | |
fea681da MK |
503 | |
504 | .PP | |
505 | .SH "RETURN VALUE" | |
991910a4 MK |
506 | These functions return the number of input items |
507 | successfully matched and assigned, | |
508 | which can be fewer than provided for, | |
509 | or even zero in the event of an early matching failure. | |
4d9b6984 MK |
510 | |
511 | The value | |
512 | .B EOF | |
513 | is returned if the end of input is reached before the first | |
991910a4 | 514 | successful conversion or matching failure occurs. |
fea681da | 515 | .B EOF |
4d9b6984 MK |
516 | is also returned if a read error occurs, |
517 | in which case the error indicator for the stream (see | |
518 | .BR ferror (3)) | |
519 | is set, and | |
520 | .I errno | |
521 | is set indicate the error. | |
fea681da MK |
522 | .SH "SEE ALSO" |
523 | .BR getc (3), | |
524 | .BR printf (3), | |
525 | .BR strtod (3), | |
526 | .BR strtol (3), | |
527 | .BR strtoul (3) | |
528 | .SH "CONFORMING TO" | |
529 | The functions | |
e511ffb6 MK |
530 | .BR fscanf (), |
531 | .BR scanf (), | |
fea681da | 532 | and |
e511ffb6 | 533 | .BR sscanf () |
fea681da MK |
534 | conform to ANSI X3.159-1989 (``ANSI C''). |
535 | .PP | |
536 | The | |
537 | .B q | |
991910a4 | 538 | specifier is the |
b14d4aa5 | 539 | .I 4.4BSD |
fea681da MK |
540 | notation for |
541 | .IR "long long" , | |
542 | while | |
543 | .B ll | |
544 | or the usage of | |
545 | .B L | |
546 | in integer conversions is the GNU notation. | |
547 | .PP | |
548 | The Linux version of these functions is based on the | |
549 | .I GNU | |
550 | .I libio | |
551 | library. Take a look at the | |
552 | .I info | |
553 | documentation of | |
554 | .I GNU | |
555 | .I libc (glibc-1.08) | |
556 | for a more concise description. | |
557 | .SH BUGS | |
558 | All functions are fully ANSI X3.159-1989 conformant, but provide the | |
991910a4 | 559 | additional specifiers |
fea681da MK |
560 | .B q |
561 | and | |
562 | .B a | |
563 | as well as an additional behaviour of the | |
564 | .B L | |
565 | and | |
566 | .B l | |
991910a4 MK |
567 | specifiers. The latter may be considered to be a bug, as it changes the |
568 | behaviour of specifiers defined in ANSI X3.159-1989. | |
fea681da | 569 | .PP |
991910a4 MK |
570 | Some combinations of the type modifiers and conversion |
571 | specifiers defined by ANSI C do not make sense | |
fea681da MK |
572 | (e.g. |
573 | .BR "%Ld" ). | |
574 | While they may have a well-defined behaviour on Linux, this need not | |
575 | to be so on other architectures. Therefore it usually is better to use | |
991910a4 | 576 | modifiers that are not defined by ANSI C at all, i.e. use |
fea681da MK |
577 | .B q |
578 | instead of | |
579 | .B L | |
580 | in combination with | |
581 | .B diouxX | |
582 | conversions or | |
583 | .BR ll . | |
584 | .PP | |
585 | The usage of | |
586 | .B q | |
587 | is not the same as on | |
b14d4aa5 | 588 | .IR "4.4BSD" , |
fea681da MK |
589 | as it may be used in float conversions equivalently to |
590 | .BR L . |