1FSCANF(3P) POSIX Programmer's Manual FSCANF(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 fscanf, scanf, sscanf - convert formatted input
13
15 #include <stdio.h>
16 int fscanf(FILE *restrict stream, const char *restrict format, ... );
18 int scanf(const char *restrict format, ... );
19 int sscanf(const char *restrict s, const char *restrict format, ... );
20
23 The fscanf() function shall read from the named input stream. The
24 scanf() function shall read from the standard input stream stdin. The
25 sscanf() function shall read from the string s. Each function reads
26 bytes, interprets them according to a format, and stores the results in
27 its arguments. Each expects, as arguments, a control string format
28 described below, and a set of pointer arguments indicating where the
29 converted input should be stored. The result is undefined if there are
30 insufficient arguments for the format. If the format is exhausted
31 while arguments remain, the excess arguments shall be evaluated but
32 otherwise ignored.
33 Conversions can be applied to the nth argument after the format in the
35 argument list, rather than to the next unused argument. In this case,
36 the conversion specifier character % (see below) is replaced by the
37 sequence "%n$", where n is a decimal integer in the range
38 [1,{NL_ARGMAX}]. This feature provides for the definition of format
39 strings that select arguments in an order appropriate to specific lan‐
40 guages. In format strings containing the "%n$" form of conversion spec‐
41 ifications, it is unspecified whether numbered arguments in the argu‐
42 ment list can be referenced from the format string more than once.
43 The format can contain either form of a conversion specification-that
45 is, % or "%n$"-but the two forms cannot be mixed within a single format
46 string. The only exception to this is that %% or %* can be mixed with
47 the "%n$" form. When numbered argument specifications are used, speci‐
48 fying the Nth argument requires that all the leading arguments, from
49 the first to the ( N-1)th, are pointers.
50 The fscanf() function in all its forms shall allow detection of a lan‐
52 guage-dependent radix character in the input string. The radix charac‐
53 ter is defined in the program's locale (category LC_NUMERIC ). In the
54 POSIX locale, or in a locale where the radix character is not defined,
55 the radix character shall default to a period ( '.' ).
56 The format is a character string, beginning and ending in its initial
58 shift state, if any, composed of zero or more directives. Each direc‐
59 tive is composed of one of the following: one or more white-space char‐
60 acters ( <space>s, <tab>s, <newline>s, <vertical-tab>s, or <form-
61 feed>s); an ordinary character (neither '%' nor a white-space charac‐
62 ter); or a conversion specification. Each conversion specification is
63 introduced by the character '%' or the character sequence "%n$", after
64 which the following appear in sequence:
65 * An optional assignment-suppressing character '*' .
67 * An optional non-zero decimal integer that specifies the maximum
69 field width.
70 * An option length modifier that specifies the size of the receiving
72 object.
73 * A conversion specifier character that specifies the type of conver‐
75 sion to be applied. The valid conversion specifiers are described
76 below.
77 The fscanf() functions shall execute each directive of the format in
79 turn. If a directive fails, as detailed below, the function shall
80 return. Failures are described as input failures (due to the unavail‐
81 ability of input bytes) or matching failures (due to inappropriate
82 input).
83 A directive composed of one or more white-space characters shall be
85 executed by reading input until no more valid input can be read, or up
86 to the first byte which is not a white-space character, which remains
87 unread.
88 A directive that is an ordinary character shall be executed as follows:
90 the next byte shall be read from the input and compared with the byte
91 that comprises the directive; if the comparison shows that they are not
92 equivalent, the directive shall fail, and the differing and subsequent
93 bytes shall remain unread. Similarly, if end-of-file, an encoding
94 error, or a read error prevents a character from being read, the direc‐
95 tive shall fail.
96 A directive that is a conversion specification defines a set of match‐
98 ing input sequences, as described below for each conversion character.
99 A conversion specification shall be executed in the following steps.
100 Input white-space characters (as specified by isspace()) shall be
102 skipped, unless the conversion specification includes a [, c, C, or n
103 conversion specifier.
104 An item shall be read from the input, unless the conversion specifica‐
106 tion includes an n conversion specifier. An input item shall be defined
107 as the longest sequence of input bytes (up to any specified maximum
108 field width, which may be measured in characters or bytes dependent on
109 the conversion specifier) which is an initial subsequence of a matching
110 sequence. The first byte, if any, after the input item shall remain
111 unread. If the length of the input item is 0, the execution of the con‐
112 version specification shall fail; this condition is a matching failure,
113 unless end-of-file, an encoding error, or a read error prevented input
114 from the stream, in which case it is an input failure.
115 Except in the case of a % conversion specifier, the input item (or, in
117 the case of a %n conversion specification, the count of input bytes)
118 shall be converted to a type appropriate to the conversion character.
119 If the input item is not a matching sequence, the execution of the con‐
120 version specification fails; this condition is a matching failure.
121 Unless assignment suppression was indicated by a '*', the result of the
122 conversion shall be placed in the object pointed to by the first argu‐
123 ment following the format argument that has not already received a con‐
124 version result if the conversion specification is introduced by %, or
125 in the nth argument if introduced by the character sequence "%n$". If
126 this object does not have an appropriate type, or if the result of the
127 conversion cannot be represented in the space provided, the behavior is
128 undefined.
129 The length modifiers and their meanings are:
131 hh Specifies that a following d, i, o, u, x, X, or n conversion
133 specifier applies to an argument with type pointer to signed
134 char or unsigned char.
135 h Specifies that a following d, i, o, u, x, X, or n conversion
137 specifier applies to an argument with type pointer to short or
138 unsigned short.
139 l (ell)
141 Specifies that a following d, i, o, u, x, X, or n conversion
142 specifier applies to an argument with type pointer to long or
143 unsigned long; that a following a, A, e, E, f, F, g, or G con‐
144 version specifier applies to an argument with type pointer to
145 double; or that a following c, s, or [ conversion specifier
146 applies to an argument with type pointer to wchar_t.
147 ll (ell-ell)
149 Specifies that a following d, i, o, u, x, X, or n conversion
151 specifier applies to an argument with type pointer to long long
152 or unsigned long long.
153 j Specifies that a following d, i, o, u, x, X, or n conversion
155 specifier applies to an argument with type pointer to intmax_t
156 or uintmax_t.
157 z Specifies that a following d, i, o, u, x, X, or n conversion
159 specifier applies to an argument with type pointer to size_t or
160 the corresponding signed integer type.
161 t Specifies that a following d, i, o, u, x, X, or n conversion
163 specifier applies to an argument with type pointer to ptrdiff_t
164 or the corresponding unsigned type.
165 L Specifies that a following a, A, e, E, f, F, g, or G conversion
167 specifier applies to an argument with type pointer to long dou‐
168 ble.
169 If a length modifier appears with any conversion specifier other than
172 as specified above, the behavior is undefined.
173 The following conversion specifiers are valid:
175 d Matches an optionally signed decimal integer, whose format is
177 the same as expected for the subject sequence of strtol() with
178 the value 10 for the base argument. In the absence of a size
179 modifier, the application shall ensure that the corresponding
180 argument is a pointer to int.
181 i Matches an optionally signed integer, whose format is the same
183 as expected for the subject sequence of strtol() with 0 for the
184 base argument. In the absence of a size modifier, the applica‐
185 tion shall ensure that the corresponding argument is a pointer
186 to int.
187 o Matches an optionally signed octal integer, whose format is the
189 same as expected for the subject sequence of strtoul() with the
190 value 8 for the base argument. In the absence of a size modi‐
191 fier, the application shall ensure that the corresponding argu‐
192 ment is a pointer to unsigned.
193 u Matches an optionally signed decimal integer, whose format is
195 the same as expected for the subject sequence of strtoul() with
196 the value 10 for the base argument. In the absence of a size
197 modifier, the application shall ensure that the corresponding
198 argument is a pointer to unsigned.
199 x Matches an optionally signed hexadecimal integer, whose format
201 is the same as expected for the subject sequence of strtoul()
202 with the value 16 for the base argument. In the absence of a
203 size modifier, the application shall ensure that the correspond‐
204 ing argument is a pointer to unsigned.
205 a, e, f, g
207 Matches an optionally signed floating-point number, infinity, or
209 NaN, whose format is the same as expected for the subject
210 sequence of strtod(). In the absence of a size modifier, the
211 application shall ensure that the corresponding argument is a
212 pointer to float.
213 If the fprintf() family of functions generates character string repre‐
215 sentations for infinity and NaN (a symbolic entity encoded in floating-
216 point format) to support IEEE Std 754-1985, the fscanf() family of
217 functions shall recognize them as input.
218 s Matches a sequence of bytes that are not white-space characters.
220 The application shall ensure that the corresponding argument is
221 a pointer to the initial byte of an array of char, signed char,
222 or unsigned char large enough to accept the sequence and a ter‐
223 minating null character code, which shall be added automati‐
224 cally.
225 If an l (ell) qualifier is present, the input is a sequence of charac‐
227 ters that begins in the initial shift state. Each character shall be
228 converted to a wide character as if by a call to the mbrtowc() func‐
229 tion, with the conversion state described by an mbstate_t object ini‐
230 tialized to zero before the first character is converted. The applica‐
231 tion shall ensure that the corresponding argument is a pointer to an
232 array of wchar_t large enough to accept the sequence and the terminat‐
233 ing null wide character, which shall be added automatically.
234 [ Matches a non-empty sequence of bytes from a set of expected
236 bytes (the scanset). The normal skip over white-space characters
237 shall be suppressed in this case. The application shall ensure
238 that the corresponding argument is a pointer to the initial byte
239 of an array of char, signed char, or unsigned char large enough
240 to accept the sequence and a terminating null byte, which shall
241 be added automatically.
242 If an l (ell) qualifier is present, the input is a sequence of charac‐
244 ters that begins in the initial shift state. Each character in the
245 sequence shall be converted to a wide character as if by a call to the
246 mbrtowc() function, with the conversion state described by an mbstate_t
247 object initialized to zero before the first character is converted. The
248 application shall ensure that the corresponding argument is a pointer
249 to an array of wchar_t large enough to accept the sequence and the ter‐
250 minating null wide character, which shall be added automatically.
251 The conversion specification includes all subsequent bytes in the for‐
253 mat string up to and including the matching right square bracket ( ']'
254 ). The bytes between the square brackets (the scanlist) comprise the
255 scanset, unless the byte after the left square bracket is a circumflex
256 ( '^' ), in which case the scanset contains all bytes that do not
257 appear in the scanlist between the circumflex and the right square
258 bracket. If the conversion specification begins with "[]" or "[^]",
259 the right square bracket is included in the scanlist and the next right
260 square bracket is the matching right square bracket that ends the con‐
261 version specification; otherwise, the first right square bracket is the
262 one that ends the conversion specification. If a '-' is in the scanlist
263 and is not the first character, nor the second where the first charac‐
264 ter is a '^', nor the last character, the behavior is implementation-
265 defined.
266 c Matches a sequence of bytes of the number specified by the field
268 width (1 if no field width is present in the conversion specifi‐
269 cation). The application shall ensure that the corresponding
270 argument is a pointer to the initial byte of an array of char,
271 signed char, or unsigned char large enough to accept the
272 sequence. No null byte is added. The normal skip over white-
273 space characters shall be suppressed in this case.
274 If an l (ell) qualifier is present, the input shall be a sequence of
276 characters that begins in the initial shift state. Each character in
277 the sequence is converted to a wide character as if by a call to the
278 mbrtowc() function, with the conversion state described by an mbstate_t
279 object initialized to zero before the first character is converted. The
280 application shall ensure that the corresponding argument is a pointer
281 to an array of wchar_t large enough to accept the resulting sequence of
282 wide characters. No null wide character is added.
283 p Matches an implementation-defined set of sequences, which shall
285 be the same as the set of sequences that is produced by the %p
286 conversion specification of the corresponding fprintf() func‐
287 tions. The application shall ensure that the corresponding argu‐
288 ment is a pointer to a pointer to void. The interpretation of
289 the input item is implementation-defined. If the input item is a
290 value converted earlier during the same program execution, the
291 pointer that results shall compare equal to that value; other‐
292 wise, the behavior of the %p conversion specification is unde‐
293 fined.
294 n No input is consumed. The application shall ensure that the cor‐
296 responding argument is a pointer to the integer into which shall
297 be written the number of bytes read from the input so far by
298 this call to the fscanf() functions. Execution of a %n conver‐
299 sion specification shall not increment the assignment count
300 returned at the completion of execution of the function. No
301 argument shall be converted, but one shall be consumed. If the
302 conversion specification includes an assignment-suppressing
303 character or a field width, the behavior is undefined.
304 C Equivalent to lc .
306 S Equivalent to ls .
308 % Matches a single '%' character; no conversion or assignment
310 occurs. The complete conversion specification shall be %% .
311 If a conversion specification is invalid, the behavior is undefined.
314 The conversion specifiers A, E, F, G, and X are also valid and shall be
316 equivalent to a, e, f, g, and x, respectively.
317 If end-of-file is encountered during input, conversion shall be termi‐
319 nated. If end-of-file occurs before any bytes matching the current
320 conversion specification (except for %n ) have been read (other than
321 leading white-space characters, where permitted), execution of the cur‐
322 rent conversion specification shall terminate with an input failure.
323 Otherwise, unless execution of the current conversion specification is
324 terminated with a matching failure, execution of the following conver‐
325 sion specification (if any) shall be terminated with an input failure.
326 Reaching the end of the string in sscanf() shall be equivalent to
328 encountering end-of-file for fscanf().
329 If conversion terminates on a conflicting input, the offending input is
331 left unread in the input. Any trailing white space (including <new‐
332 line>s) shall be left unread unless matched by a conversion specifica‐
333 tion. The success of literal matches and suppressed assignments is only
334 directly determinable via the %n conversion specification.
335 The fscanf() and scanf() functions may mark the st_atime field of the
337 file associated with stream for update. The st_atime field shall be
338 marked for update by the first successful execution of fgetc(),
339 fgets(), fread(), getc(), getchar(), gets(), fscanf(), or fscanf()
340 using stream that returns data not supplied by a prior call to
341 ungetc().
342
344 Upon successful completion, these functions shall return the number of
345 successfully matched and assigned input items; this number can be zero
346 in the event of an early matching failure. If the input ends before the
347 first matching failure or conversion, EOF shall be returned. If a read
348 error occurs, the error indicator for the stream is set, EOF shall be
349 returned, and errno shall be set to indicate the error.
350
352 For the conditions under which the fscanf() functions fail and may
353 fail, refer to fgetc() or fgetwc().
354 In addition, fscanf() may fail if:
356 EILSEQ Input byte sequence does not form a valid character.
358 EINVAL There are insufficient arguments.
360 The following sections are informative.
363
365 The call:
366 int i, n; float x; char name[50];
369 n = scanf("%d%f%s", &i, &x, name);
370 with the input line:
372 25 54.32E-1 Hamster
375 assigns to n the value 3, to i the value 25, to x the value 5.432, and
377 name contains the string "Hamster" .
378 The call:
380 int i; float x; char name[50];
383 (void) scanf("%2d%f%*d %[0123456789]", &i, &x, name);
384 with input:
386 56789 0123 56a72
389 assigns 56 to i, 789.0 to x, skips 0123, and places the string "56\0"
391 in name. The next call to getchar() shall return the character 'a' .
392 Reading Data into an Array
394 The following call uses fscanf() to read three floating-point numbers
395 from standard input into the input array.
396 float input[3]; fscanf (stdin, "%f %f %f", input, input+1, input+2);
399
401 If the application calling fscanf() has any objects of type wint_t or
402 wchar_t, it must also include the <wchar.h> header to have these
403 objects defined.
404
406 This function is aligned with the ISO/IEC 9899:1999 standard, and in
407 doing so a few "obvious" things were not included. Specifically, the
408 set of characters allowed in a scanset is limited to single-byte char‐
409 acters. In other similar places, multi-byte characters have been per‐
410 mitted, but for alignment with the ISO/IEC 9899:1999 standard, it has
411 not been done here. Applications needing this could use the correspond‐
412 ing wide-character functions to achieve the desired results.
413
415 None.
416
418 getc(), printf(), setlocale(), strtod(), strtol(), strtoul(), wcr‐
419 tomb(), the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 7,
420 Locale, <langinfo.h>, <stdio.h>, <wchar.h>
421
423 Portions of this text are reprinted and reproduced in electronic form
424 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
425 -- Portable Operating System Interface (POSIX), The Open Group Base
426 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
427 Electrical and Electronics Engineers, Inc and The Open Group. In the
428 event of any discrepancy between this version and the original IEEE and
429 The Open Group Standard, the original IEEE and The Open Group Standard
430 is the referee document. The original Standard can be obtained online
431 at http://www.opengroup.org/unix/online.html .
432IEEE/The Open Group 2003 FSCANF(3P)