1SCANF(3) Linux Programmer's Manual SCANF(3)
2
6 scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - input format conver‐
7 sion
8
10 #include <stdio.h>
11 int scanf(const char *format, ...);
13 int fscanf(FILE *stream, const char *format, ...);
14 int sscanf(const char *str, const char *format, ...);
15 #include <stdarg.h>
17 int vscanf(const char *format, va_list ap);
19 int vsscanf(const char *str, const char *format, va_list ap);
20 int vfscanf(FILE *stream, const char *format, va_list ap);
21 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
23 vscanf(), vsscanf(), vfscanf(): _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE;
25 or cc -std=c99
26
28 The scanf() family of functions scans input according to format as
29 described below. This format may contain conversion specifications;
30 the results from such conversions, if any, are stored in the locations
31 pointed to by the pointer arguments that follow format. Each pointer
32 argument must be of a type that is appropriate for the value returned
33 by the corresponding conversion specification.
34 If the number of conversion specifications in format exceeds the number
36 of pointer arguments, the results are undefined. If the number of
37 pointer arguments exceeds the number of conversion specifications, then
38 the excess pointer arguments are evaluated, but are otherwise ignored.
39 The scanf() function reads input from the standard input stream stdin,
41 fscanf() reads input from the stream pointer stream, and sscanf() reads
42 its input from the character string pointed to by str.
43 The vfscanf() function is analogous to vfprintf(3) and reads input from
45 the stream pointer stream using a variable argument list of pointers
46 (see stdarg(3). The vscanf() function scans a variable argument list
47 from the standard input and the vsscanf() function scans it from a
48 string; these are analogous to the vprintf(3) and vsprintf(3) functions
49 respectively.
50 The format string consists of a sequence of directives which describe
52 how to process the sequence of input characters. If processing of a
53 directive fails, no further input is read, and scanf() returns. A
54 "failure" can be either of the following: input failure, meaning that
55 input characters were unavailable, or matching failure, meaning that
56 the input was inappropriate (see below).
57 A directive is one of the following:
59 · A sequence of white-space characters (space, tab, newline, etc.;
61 see isspace(3)). This directive matches any amount of white
62 space, including none, in the input.
63 · An ordinary character (i.e., one other than white space or '%').
65 This character must exactly match the next character of input.
66 · A conversion specification, which commences with a '%' (percent)
68 character. A sequence of characters from the input is converted
69 according to this specification, and the result is placed in the
70 corresponding pointer argument. If the next item of input does
71 not match the conversion specification, the conversion fails —
72 this is a matching failure.
73 Each conversion specification in format begins with either the charac‐
75 ter '%' or the character sequence "%n$" (see below for the distinction)
76 followed by:
77 · An optional '*' assignment-suppression character: scanf() reads
79 input as directed by the conversion specification, but discards
80 the input. No corresponding pointer argument is required, and
81 this specification is not included in the count of successful
82 assignments returned by scanf().
83 · An optional 'a' character. This is used with string conver‐
85 sions, and relieves the caller of the need to allocate a corre‐
86 sponding buffer to hold the input: instead, scanf() allocates a
87 buffer of sufficient size, and assigns the address of this buf‐
88 fer to the corresponding pointer argument, which should be a
89 pointer to a char * variable (this variable does not need to be
90 initialized before the call). The caller should subsequently
91 free(3) this buffer when it is no longer required. This is a
92 GNU extension; C99 employs the 'a' character as a conversion
93 specifier (and it can also be used as such in the GNU implemen‐
94 tation).
95 · An optional decimal integer which specifies the maximum field
97 width. Reading of characters stops either when this maximum is
98 reached or when a nonmatching character is found, whichever hap‐
99 pens first. Most conversions discard initial white space char‐
100 acters (the exceptions are noted below), and these discarded
101 characters don't count towards the maximum field width. String
102 input conversions store a null terminator ('\0') to mark the end
103 of the input; the maximum field width does not include this ter‐
104 minator.
105 · An optional type modifier character. For example, the l type
107 modifier is used with integer conversions such as %d to specify
108 that the corresponding pointer argument refers to a long int
109 rather than a pointer to an int.
110 · A conversion specifier that specifies the type of input conver‐
112 sion to be performed.
113 The conversion specifications in format are of two forms, either begin‐
115 ning with '%' or beginning with "%n$". The two forms should not be
116 mixed in the same format string, except that a string containing "%n$"
117 specifications can include %% and %*. If format contains '%' specifi‐
118 cations then these correspond in order with successive pointer argu‐
119 ments. In the "%n$" form (which is specified in POSIX.1-2001, but not
120 C99), n is a decimal integer that specifies that the converted input
121 should be placed in the location referred to by the n-th pointer argu‐
122 ment following format.
123 Conversions
125 The following type modifier characters can appear in a conversion spec‐
126 ification:
127 h Indicates that the conversion will be one of d, i, o, u, x, X,
129 or n and the next pointer is a pointer to a short int or
130 unsigned short int (rather than int).
131 hh As for h, but the next pointer is a pointer to a signed char or
133 unsigned char.
134 j As for h, but the next pointer is a pointer to an intmax_t or a
136 uintmax_t. This modifier was introduced in C99.
137 l Indicates either that the conversion will be one of d, i, o, u,
139 x, X, or n and the next pointer is a pointer to a long int or
140 unsigned long int (rather than int), or that the conversion will
141 be one of e, f, or g and the next pointer is a pointer to double
142 (rather than float). Specifying two l characters is equivalent
143 to L. If used with %c or %s the corresponding parameter is con‐
144 sidered as a pointer to a wide character or wide-character
145 string respectively.
146 L Indicates that the conversion will be either e, f, or g and the
148 next pointer is a pointer to long double or the conversion will
149 be d, i, o, u, or x and the next pointer is a pointer to long
150 long.
151 q equivalent to L. This specifier does not exist in ANSI C.
153 t As for h, but the next pointer is a pointer to a ptrdiff_t.
155 This modifier was introduced in C99.
156 z As for h, but the next pointer is a pointer to a size_t. This
158 modifier was introduced in C99.
159 The following conversion specifiers are available:
161 % Matches a literal '%'. That is, %% in the format string matches
163 a single input '%' character. No conversion is done (but ini‐
164 tial white space characters are discarded), and assignment does
165 not occur.
166 d Matches an optionally signed decimal integer; the next pointer
168 must be a pointer to int.
169 D Equivalent to ld; this exists only for backwards compatibility.
171 (Note: thus only in libc4. In libc5 and glibc the %D is
172 silently ignored, causing old programs to fail mysteriously.)
173 i Matches an optionally signed integer; the next pointer must be a
175 pointer to int. The integer is read in base 16 if it begins
176 with 0x or 0X, in base 8 if it begins with 0, and in base 10
177 otherwise. Only characters that correspond to the base are
178 used.
179 o Matches an unsigned octal integer; the next pointer must be a
181 pointer to unsigned int.
182 u Matches an unsigned decimal integer; the next pointer must be a
184 pointer to unsigned int.
185 x Matches an unsigned hexadecimal integer; the next pointer must
187 be a pointer to unsigned int.
188 X Equivalent to x.
190 f Matches an optionally signed floating-point number; the next
192 pointer must be a pointer to float.
193 e Equivalent to f.
195 g Equivalent to f.
197 E Equivalent to f.
199 a (C99) Equivalent to f.
201 s Matches a sequence of non-white-space characters; the next
203 pointer must be a pointer to character array that is long enough
204 to hold the input sequence and the terminating null character
205 ('\0'), which is added automatically. The input string stops at
206 white space or at the maximum field width, whichever occurs
207 first.
208 c Matches a sequence of characters whose length is specified by
210 the maximum field width (default 1); the next pointer must be a
211 pointer to char, and there must be enough room for all the char‐
212 acters (no terminating null byte is added). The usual skip of
213 leading white space is suppressed. To skip white space first,
214 use an explicit space in the format.
215 [ Matches a nonempty sequence of characters from the specified set
217 of accepted characters; the next pointer must be a pointer to
218 char, and there must be enough room for all the characters in
219 the string, plus a terminating null byte. The usual skip of
220 leading white space is suppressed. The string is to be made up
221 of characters in (or not in) a particular set; the set is
222 defined by the characters between the open bracket [ character
223 and a close bracket ] character. The set excludes those charac‐
224 ters if the first character after the open bracket is a circum‐
225 flex (^). To include a close bracket in the set, make it the
226 first character after the open bracket or the circumflex; any
227 other position will end the set. The hyphen character - is also
228 special; when placed between two other characters, it adds all
229 intervening characters to the set. To include a hyphen, make it
230 the last character before the final close bracket. For
231 instance, [^]0-9-] means the set "everything except close
232 bracket, zero through nine, and hyphen". The string ends with
233 the appearance of a character not in the (or, with a circumflex,
234 in) set or when the field width runs out.
235 p Matches a pointer value (as printed by %p in printf(3); the next
237 pointer must be a pointer to a pointer to void.
238 n Nothing is expected; instead, the number of characters consumed
240 thus far from the input is stored through the next pointer,
241 which must be a pointer to int. This is not a conversion,
242 although it can be suppressed with the * assignment-suppression
243 character. The C standard says: "Execution of a %n directive
244 does not increment the assignment count returned at the comple‐
245 tion of execution" but the Corrigendum seems to contradict this.
246 Probably it is wise not to make any assumptions on the effect of
247 %n conversions on the return value.
248
250 These functions return the number of input items successfully matched
251 and assigned, which can be fewer than provided for, or even zero in the
252 event of an early matching failure.
253 The value EOF is returned if the end of input is reached before either
255 the first successful conversion or a matching failure occurs. EOF is
256 also returned if a read error occurs, in which case the error indicator
257 for the stream (see ferror(3)) is set, and errno is set indicate the
258 error.
259
261 EAGAIN The file descriptor underlying stream is marked nonblocking, and
262 the read operation would block.
263 EBADF The file descriptor underlying stream is invalid, or not open
265 for reading.
266 EILSEQ Input byte sequence does not form a valid character.
268 EINTR The read operation was interrupted by a signal; see signal(7).
270 EINVAL Not enough arguments; or format is NULL.
272 ENOMEM Out of memory.
274 ERANGE The result of an integer conversion would exceed the size that
276 can be stored in the corresponding integer type.
277
279 The functions fscanf(), scanf(), and sscanf() conform to C89 and C99
280 and POSIX.1-2001. These standards do not specify the ERANGE error.
281 The q specifier is the 4.4BSD notation for long long, while ll or the
283 usage of L in integer conversions is the GNU notation.
284 The Linux version of these functions is based on the GNU libio library.
286 Take a look at the info documentation of GNU libc (glibc-1.08) for a
287 more concise description.
288
290 The GNU C library supports a nonstandard extension that causes the
291 library to dynamically allocate a string of sufficient size for input
292 strings for the %s and %a[range] conversion specifiers. To make use of
293 this feature, specify a as a length modifier (thus %as or %a[range]).
294 The caller must free(3) the returned string, as in the following exam‐
295 ple:
296 char *p;
298 int n;
299 errno = 0;
301 n = scanf("%a[a-z]", &p);
302 if (n == 1) {
303 printf("read: %s\n", p);
304 free(p);
305 } else if (errno != 0) {
306 perror("scanf");
307 } else {
308 fprintf(stderr, "No matching characters\n"):
309 }
310 As shown in the above example, it is only necessary to call free(3) if
312 the scanf() call successfully read a string.
313 The a modifier is not available if the program is compiled with gcc
315 -std=c99 or gcc -D_ISOC99_SOURCE (unless _GNU_SOURCE is also speci‐
316 fied), in which case the a is interpreted as a specifier for floating-
317 point numbers (see above).
318 Since version 2.7, glibc also provides the m modifier for the same pur‐
320 pose as the a modifier. The m modifier has the following advantages:
321 * It may also be applied to %c conversion specifiers (e.g., %3mc).
323 * It avoids ambiguity with respect to the %a floating-point conversion
325 specifier (and is unaffected by gcc -std=c99 etc.)
326 * It is specified in the upcoming revision of the POSIX.1 standard.
328
330 All functions are fully C89 conformant, but provide the additional
331 specifiers q and a as well as an additional behavior of the L and l
332 specifiers. The latter may be considered to be a bug, as it changes
333 the behavior of specifiers defined in C89.
334 Some combinations of the type modifiers and conversion specifiers
336 defined by ANSI C do not make sense (e.g. %Ld). While they may have a
337 well-defined behavior on Linux, this need not to be so on other archi‐
338 tectures. Therefore it usually is better to use modifiers that are not
339 defined by ANSI C at all, that is, use q instead of L in combination
340 with d, i, o, u, x, and X conversions or ll.
341 The usage of q is not the same as on 4.4BSD, as it may be used in float
343 conversions equivalently to L.
344
346 getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)
347
349 This page is part of release 3.25 of the Linux man-pages project. A
350 description of the project, and information about reporting bugs, can
351 be found at http://www.kernel.org/doc/man-pages/.
352GNU 2008-07-12 SCANF(3)