1scanf(3C) Standard C Library Functions scanf(3C)
2
6 scanf, fscanf, sscanf, vscanf, vfscanf, vsscanf - convert formatted
7 input
8
10 #include <stdio.h>
11 int scanf(const char *restrict format...);
13 int fscanf(FILE *restrict stream, const char *restrict format...);
16 int sscanf(const char *restrict s, const char *restrict format...);
19 #include <stdarg.h>
22 #include <stdio.h>
23 int vscanf(const char *format, va_list arg);
25 int vfscanf(FILE *stream, const char *format, va_list arg);
28 int vsscanf(const char *s, const char *format, va_list arg);
31
34 The scanf() function reads from the standard input stream stdin.
35 The fscanf() function reads from the named input stream.
38 The sscanf() function reads from the string s.
41 The vscanf(), vfscanf(), and vsscanf() functions are equivalent to the
44 scanf(), fscanf(), and sscanf() functions, respectively, except that
45 instead of being called with a variable number of arguments, they are
46 called with an argument list as defined by the <stdarg.h> header .
47 These functions do not invoke the va_end() macro. Applications using
48 these functions should call va_end(ap) afterwards to clean up.
49 Each function reads bytes, interprets them according to a format, and
52 stores the results in its arguments. Each expects, as arguments, a con‐
53 trol string format described below, and a set of pointer arguments
54 indicating where the converted input should be stored. The result is
55 undefined if there are insufficient arguments for the format. If the
56 format is exhausted while arguments remain, the excess arguments are
57 evaluated but are otherwise ignored.
58 Conversions can be applied to the nth argument after the format in the
61 argument list, rather than to the next unused argument. In this case,
62 the conversion character % (see below) is replaced by the sequence %n$,
63 where n is a decimal integer in the range [1, NL_ARGMAX]. This feature
64 provides for the definition of format strings that select arguments in
65 an order appropriate to specific languages. In format strings contain‐
66 ing the %n$ form of conversion specifications, it is unspecified
67 whether numbered arguments in the argument list can be referenced from
68 the format string more than once.
69 The format can contain either form of a conversion specification, that
72 is, % or %n$, but the two forms cannot normally be mixed within a sin‐
73 gle format string. The only exception to this is that %% or %* can be
74 mixed with the %n$ form.
75 The scanf() function in all its forms allows for detection of a lan‐
78 guage-dependent radix character in the input string. The radix charac‐
79 ter is defined in the program's locale (category LC_NUMERIC). In the
80 POSIX locale, or in a locale where the radix character is not defined,
81 the radix character defaults to a period (.).
82 The format is a character string, beginning and ending in its initial
85 shift state, if any, composed of zero or more directives. Each direc‐
86 tive is composed of one of the following:
87 o one or more white-space characters (space, tab, newline,
89 vertical-tab or form-feed characters);
90 o an ordinary character (neither % nor a white-space charac‐
92 ter); or
93 o a conversion specification.
95 Conversion Specifications
97 Each conversion specification is introduced by the character % or the
98 character sequence %n$, after which the following appear in sequence:
99 o An optional assignment-suppressing character *.
101 o An optional non-zero decimal integer that specifies the max‐
103 imum field width.
104 o An option length modifier that specifies the size of the
106 receiving object.
107 o A conversion specifier character that specifies the type of
109 conversion to be applied. The valid conversion characters
110 are described below.
111 The scanf() functions execute each directive of the format in turn. If
114 a directive fails, as detailed below, the function returns. Failures
115 are described as input failures (due to the unavailability of input
116 bytes) or matching failures (due to inappropriate input).
117 A directive composed of one or more white-space characters is executed
120 by reading input until no more valid input can be read, or up to the
121 first byte which is not a white-space character which remains unread.
122 A directive that is an ordinary character is executed as follows. The
125 next byte is read from the input and compared with the byte that com‐
126 prises the directive; if the comparison shows that they are not equiva‐
127 lent, the directive fails, and the differing and subsequent bytes
128 remain unread.
129 A directive that is a conversion specification defines a set of match‐
132 ing input sequences, as described below for each conversion character.
133 A conversion specification is executed in the following steps:
134 Input white-space characters (as specified by isspace(3C)) are skipped,
137 unless the conversion specification includes a [, c, C, or n conversion
138 character.
139 An item is read from the input unless the conversion specification
142 includes an n conversion character. The length of the item read is lim‐
143 ited to any specified maximum field width, which is interpreted in
144 either characters or bytes depending on the conversion character. In
145 Solaris default mode, the input item is defined as the longest sequence
146 of input bytes that forms a matching sequence. In some cases, scanf()
147 might need to read several extra characters beyond the end of the input
148 item to find the end of a matching sequence. In C99/SUSv3 mode, the
149 input item is defined as the longest sequence of input bytes that is,
150 or is a prefix of, a matching sequence. With this definition, scanf()
151 need only read at most one character beyond the end of the input item.
152 Therefore, in C99/SUSv3 mode, some sequences that are acceptable to
153 strtod(3C), strtol(3C), and similar functions are unacceptable to
154 scanf(). In either mode, scanf() attempts to push back any excess bytes
155 read using ungetc(3C). Assuming all such attempts succeed, the first
156 byte, if any, after the input item remains unread. If the length of the
157 input item is 0, the conversion fails. This condition is a matching
158 failure unless end-of-file, an encoding error, or a read error pre‐
159 vented input from the stream, in which case it is an input failure.
160 Except in the case of a % conversion character, the input item (or, in
163 the case of a %n conversion specification, the count of input bytes) is
164 converted to a type appropriate to the conversion character. If the
165 input item is not a matching sequence, the execution of the conversion
166 specification fails; this condition is a matching failure. Unless
167 assignment suppression was indicated by a *, the result of the conver‐
168 sion is placed in the object pointed to by the first argument following
169 the format argument that has not already received a conversion result
170 if the conversion specification is introduced by %, or in the nth argu‐
171 ment if introduced by the character sequence %n$. If this object does
172 not have an appropriate type, or if the result of the conversion cannot
173 be represented in the space provided, the behavior is undefined.
174 Length Modifiers
176 The length modifiers and their meanings are:
177 hh Specifies that a following d, i, o, u, x, X, or n con‐
179 version specifier applies to an argument with type
180 pointer to signed char or unsigned char.
181 h Specifies that a following d, i, o, u, x, X, or n con‐
184 version specifier applies to an argument with type
185 pointer to short or unsigned short.
186 l (ell) Specifies that a following d, i, o, u, x, X, or n con‐
189 version specifier applies to an argument with type
190 pointer to long or unsigned long; that a following a,
191 A, e, E, f, F, g, or G conversion specifier applies to
192 an argument with type pointer to double; or that a fol‐
193 lowing c, s, or [ conversion specifier applies to an
194 argument with type pointer to wchar_t.
195 ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n con‐
198 version specifier applies to an argument with type
199 pointer to long long or unsigned long long.
200 j Specifies that a following d, i, o, u, x, X, or n con‐
203 version specifier applies to an argument with type
204 pointer to intmax_t or uintmax_t.
205 z Specifies that a following d, i, o, u, x, X, or n con‐
208 version specifier applies to an argument with type
209 pointer to size_t or the corresponding signed integer
210 type.
211 t Specifies that a following d, i, o, u, x, X, or n con‐
214 version specifier applies to an argument with type
215 pointer to ptrdiff_t or the corresponding unsigned
216 type.
217 L Specifies that a following a, A, e, E, f, F, g, or G
220 conversion specifier applies to an argument with type
221 pointer to long double.
222 If a length modifier appears with any conversion specifier other than
226 as specified above, the behavior is undefined.
227 Conversion Characters
229 The following conversion characters are valid:
230 d Matches an optionally signed decimal integer, whose format
232 is the same as expected for the subject sequence of str‐
233 tol(3C) with the value 10 for the base argument. In the
234 absence of a size modifier, the corresponding argument must
235 be a pointer to int.
236 i Matches an optionally signed integer, whose format is the
239 same as expected for the subject sequence of strtol() with 0
240 for the base argument. In the absence of a size modifier,
241 the corresponding argument must be a pointer to int.
242 o Matches an optionally signed octal integer, whose format is
245 the same as expected for the subject sequence of strtoul(3C)
246 with the value 8 for the base argument. In the absence of a
247 size modifier, the corresponding argument must be a pointer
248 to unsigned int.
249 u Matches an optionally signed decimal integer, whose format
252 is the same as expected for the subject sequence of str‐
253 toul() with the value 10 for the base argument. In the
254 absence of a size modifier, the corresponding argument must
255 be a pointer to unsigned int.
256 x Matches an optionally signed hexadecimal integer, whose for‐
259 mat is the same as expected for the subject sequence of str‐
260 toul() with the value 16 for the base argument. In the
261 absence of a size modifier, the corresponding argument must
262 be a pointer to unsigned int.
263 a,e,f,g Matches an optionally signed floating-point number, infin‐
266 ity, or NaN, whose format is the same as expected for the
267 subject sequence of strtod(3C). In the absence of a size
268 modifier, the corresponding argument must be a pointer to
269 float. The e, f, and g specifiers match hexadecimal floating
270 point values only in C99/SUSv3 (see standards(5)) mode, but
271 the a specifier always matches hexadecimal floating point
272 values.
273 These conversion specifiers match any subject sequence
275 accepted by strtod(3C), including the INF, INFINITY, NAN,
276 and NAN(n-char-sequence) forms. The result of the conver‐
277 sion is the same as that of calling strtod() (or strtof() or
278 strtold()) with the matching sequence, including the raising
279 of floating point exceptions and the setting of errno to
280 ERANGE, if applicable.
281 s Matches a sequence of bytes that are not white-space charac‐
284 ters. The corresponding argument must be a pointer to the
285 initial byte of an array of char, signed char, or unsigned
286 char large enough to accept the sequence and a terminating
287 null character code, which will be added automatically.
288 If an l (ell) qualifier is present, the input is a sequence
290 of characters that begins in the initial shift state. Each
291 character is converted to a wide-character as if by a call
292 to the mbrtowc(3C) function, with the conversion state
293 described by an mbstate_t object initialized to zero before
294 the first character is converted. The corresponding argu‐
295 ment must be a pointer to an array of wchar_t large enough
296 to accept the sequence and the terminating null wide-char‐
297 acter, which will be added automatically.
298 [ Matches a non-empty sequence of characters from a set of
301 expected characters (the scanset). The normal skip over
302 white-space characters is suppressed in this case. The cor‐
303 responding argument must be a pointer to the initial byte of
304 an array of char, signed char, or unsigned char large enough
305 to accept the sequence and a terminating null byte, which
306 will be added automatically.
307 If an l (ell) qualifier is present, the input is a sequence
309 of characters that begins in the initial shift state. Each
310 character in the sequence is converted to a wide-character
311 as if by a call to the mbrtowc() function, with the conver‐
312 sion state described by an mbstate_t object initialized to
313 zero before the first character is converted. The corre‐
314 sponding argument must be a pointer to an array of wchar_t
315 large enough to accept the sequence and the terminating null
316 wide-character, which will be added automatically.
317 The conversion specification includes all subsequent charac‐
319 ters in the format string up to and including the matching
320 right square bracket (]). The characters between the square
321 brackets (the scanlist) comprise the scanset, unless the
322 character after the left square bracket is a circumflex (^),
323 in which case the scanset contains all characters that do
324 not appear in the scanlist between the circumflex and the
325 right square bracket. If the conversion specification begins
326 with [] or [^], the right square bracket is included in the
327 scanlist and the next right square bracket is the matching
328 right square bracket that ends the conversion specification;
329 otherwise the first right square bracket is the one that
330 ends the conversion specification. If a - is in the scanlist
331 and is not the first character, nor the second where the
332 first character is a ^, nor the last character, it indicates
333 a range of characters to be matched.
334 c Matches a sequence of characters of the number specified by
337 the field width (1 if no field width is present in the con‐
338 version specification). The corresponding argument must be a
339 pointer to the initial byte of an array of char, signed
340 char, or unsigned char large enough to accept the sequence.
341 No null byte is added. The normal skip over white-space
342 characters is suppressed in this case.
343 If an l (ell) qualifier is present, the input is a sequence
345 of characters that begins in the initial shift state. Each
346 character in the sequence is converted to a wide-character
347 as if by a call to the mbrtowc() function, with the conver‐
348 sion state described by an mbstate_t object initialized to
349 zero before the first character is converted. The corre‐
350 sponding argument must be a pointer to an array of wchar_t
351 large enough to accept the resulting sequence of wide-char‐
352 acters. No null wide-character is added.
353 p Matches the set of sequences that is the same as the set of
356 sequences that is produced by the %p conversion of the cor‐
357 responding printf(3C) functions. The corresponding argument
358 must be a pointer to a pointer to void. If the input item is
359 a value converted earlier during the same program execution,
360 the pointer that results will compare equal to that value;
361 otherwise the behavior of the %p conversion is undefined.
362 n No input is consumed. The corresponding argument must be a
365 pointer to the integer into which is to be written the num‐
366 ber of bytes read from the input so far by this call to the
367 scanf() functions. Execution of a %n conversion specifica‐
368 tion does not increment the assignment count returned at the
369 completion of execution of the function.
370 C Same as lc.
373 S Same as ls.
376 % Matches a single %; no conversion or assignment occurs. The
379 complete conversion specification must be %%.
380 If a conversion specification is invalid, the behavior is undefined.
384 The conversion characters A, E, F, G, and X are also valid and behave
387 the same as, respectively, a, e, f, g, and x.
388 If end-of-file is encountered during input, conversion is terminated.
391 If end-of-file occurs before any bytes matching the current conversion
392 specification (except for %n) have been read (other than leading white-
393 space characters, where permitted), execution of the current conversion
394 specification terminates with an input failure. Otherwise, unless exe‐
395 cution of the current conversion specification is terminated with a
396 matching failure, execution of the following conversion specification
397 (if any) is terminated with an input failure.
398 Reaching the end of the string in sscanf() is equivalent to encounter‐
401 ing end-of-file for fscanf().
402 If conversion terminates on a conflicting input, the offending input is
405 left unread in the input. Any trailing white space (including newline
406 characters) is left unread unless matched by a conversion specifica‐
407 tion. The success of literal matches and suppressed assignments is only
408 directly determinable via the %n conversion specification.
409 The fscanf() and scanf() functions may mark the st_atime field of the
412 file associated with stream for update. The st_atime field will be
413 marked for update by the first successful execution of fgetc(3C),
414 fgets(3C), fread(3C), fscanf(), getc(3C), getchar(3C), gets(3C), or
415 scanf() using stream that returns data not supplied by a prior call to
416 ungetc(3C).
417
419 Upon successful completion, these functions return the number of suc‐
420 cessfully matched and assigned input items; this number can be 0 in the
421 event of an early matching failure. If the input ends before the first
422 matching failure or conversion, EOF is returned. If a read error
423 occurs the error indicator for the stream is set, EOF is returned, and
424 errno is set to indicate the error.
425
427 For the conditions under which the scanf() functions will fail and may
428 fail, refer to fgetc(3C) or fgetwc(3C).
429 In addition, fscanf() may fail if:
432 EILSEQ Input byte sequence does not form a valid character.
434 EINVAL There are insufficient arguments.
437
440 If the application calling the scanf() functions has any objects of
441 type wint_t or wchar_t, it must also include the header <wchar.h> to
442 have these objects defined.
443
445 Example 1 The call:
446 int i, n; float x; char name[50];
448 n = scanf("%d%f%s", &i, &x, name)
449 with the input line:
453 25 54.32E-1 Hamster
456 will assign to n the value 3, to i the value 25, to x the value 5.432,
460 and name will contain the string Hamster.
461 Example 2 The call:
464 int i; float x; char name[50];
466 (void) scanf("%2d%f%*d %[0123456789]", &i, &x, name);
467 with input:
471 56789 0123 56a72
474 will assign 56 to i, 789.0 to x, skip 0123, and place the string 56\0
478 in name. The next call to getchar(3C) will return the character a.
479
482 See attributes(5) for descriptions of the following attributes:
483 ┌─────────────────────────────┬─────────────────────────────┐
488 │ATTRIBUTE TYPE │ATTRIBUTE VALUE │
489 ├─────────────────────────────┼─────────────────────────────┤
490 │CSI │Enabled │
491 ├─────────────────────────────┼─────────────────────────────┤
492 │Interface Stability │Committed │
493 ├─────────────────────────────┼─────────────────────────────┤
494 │MT-Level │MT-Safe │
495 ├─────────────────────────────┼─────────────────────────────┤
496 │Standard │See standards(5). │
497 └─────────────────────────────┴─────────────────────────────┘
498
500 fgetc(3C), fgets(3C), fgetwc(3C), fread(3C), isspace(3C), printf(3C),
501 setlocale(3C), strtod(3C), strtol(3C), strtoul(3C), wcrtomb(3C),
502 ungetc(3C), attributes(5), standards(5)
503
505 The behavior of the conversion specifier "%%" has changed for all of
506 the functions described on this manual page. Previously the "%%" speci‐
507 fier accepted a "%" character from input only if there were no preced‐
508 ing whitespace characters. The new behavior accepts "%" even if there
509 are preceding whitespace characters. This new behavior now aligns with
510 the description on this manual page and in various standards. If the
511 old behavior is desired, the conversion specification "%*[%]" can be
512 used.
513SunOS 5.11 10 Jul 2008 scanf(3C)