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