3 fscanf, scanf, sscanf, vfscanf \- scan formatted input
7 .B "#include <stdio.h>"
10 int fscanf(FILE *f, char *format, ...)
13 int scanf(char *format, ... )
16 int sscanf(char *s, char *format, ...)
19 int vfscanf(FILE *stream, char *format, char *args)
22 reads from the named input stream
26 under control of the string pointed to by
28 that specifies the admissible input sequences and how they are to be converted
29 for assignment, using subsequent arguments as pointers to the objects
30 to receive the converted input.
31 If there are insufficient arguments for the format, the behavior is undefined.
32 If the format is exhausted while arguments remain, the excess arguments
33 are evaluated (as always) but are otherwise ignored.
38 are the same, but they read from
40 and the character string
48 argument is a pointer to an argument in an argument list of the
49 calling function and the effect is as if the calling function's
50 argument list from that point on is passed to the scanf routines.
52 The format is composed of zero or more directives:
53 one or more white-space characters; an ordinary character (not
55 or a conversion specification.
56 Each conversion specification is introduced by the character
60 the following appear in sequence:
63 An optional assignment-suppressing character
66 An optional decimal integer that specifies the maximum field width.
73 indicating the size of the receiving object.
74 The conversion specifiers
81 if the corresponding argument is a pointer to
83 rather than a pointer to
89 Similarly, the conversion specifiers
96 if the corresponding argument is a pointer to
99 rather than a pointer to
103 if it is a pointer to
106 Finally, the conversion specifiers
113 if the corresponding argument is a pointer to
115 rather than a pointer to
119 if it is a pointer to
127 appears with any other conversion specifier, the behavior is undefined.
129 A character that specifies the type of conversion to be applied.
130 The valid conversion specifiers are described below.
134 executes each directive of the format in turn.
135 If a directive fails, as detailed below,
138 Failures are described as input failures (due to the unavailability
140 or matching failures (due to inappropriate input).
142 A directive composed of white space is executed by reading input up
143 to the first non-white-space character (which remains unread),
144 or until no more characters can be read.
146 A directive that is an ordinary character is executed by reading
147 the next character from the stream.
148 If if differs from the one comprising the directive,
149 the directive fails, and the differing and subsequent characters
152 A directive that is a conversion specification defines a set of
153 matching input sequences, as described below for each specifier.
154 A conversion specification is executed in the following steps:
156 Input white-space characters (as specified by
160 are skipped, unless the specification includes a
167 An input item is read from the stream,
168 unless the specification includes an
171 An input item is defined as the longest sequence of input characters
172 (up to any specified maximum field width) which is an initial
173 subsequence of a matching sequence.
174 The first character, if any, after the input item remains unread.
175 If the length of the input item is zero, the execution of
176 the directive fails: this condition is a matching failure,
177 unless an error prevented input from the stream,
178 in which case it is an input failure.
180 Except in the case of a
182 specifier, the input item (or, in the case of a
184 directive, the count of input characters)
185 is converted to a type appropriate to the conversion specifier.
186 If the input item is not a matching sequence, the execution of
187 the directive fails: this condition is a matching failure.
188 Unless assignment suppression was indicated by a
190 the result of the conversion is placed in the object pointed to by the
191 first argument following the
193 argument that has not already received a conversion result.
194 If this object does not have an appropriate type,
195 or if the result of the conversion cannot be represented
196 in the space provided, the behavior is undefined.
198 The following conversion specifiers are valid:
201 Matches an optionally signed decimal integer,
202 whose format is the same as expected for the subject sequence
207 function with 10 for the
210 The corresponding argument shall be a pointer to
214 Matches an optionally signed decimal integer,
215 whose format is the same as expected for the subject sequence
218 function with 0 for the
221 The corresponding argument shall be a pointer to
225 Matches an optionally signed octal integer,
226 whose format is the same as expected for the subject sequence
231 function with 8 for the
234 The corresponding argument shall be a pointer to
239 Matches an optionally signed decimal integer,
240 whose format is the same as expected for the subject sequence
243 function with 10 for the
246 The corresponding argument shall be a pointer to
251 Matches an optionally signed hexadecimal integer,
252 whose format is the same as expected for the subject sequence
255 function with 16 for the
258 The corresponding argument shall be a pointer to
263 Matches an optionally signed floating-point number, whose format is
264 the same as expected for the subject string of the
269 The corresponding argument shall be a pointer to
273 Matches a sequence of non-white-space characters.
274 The corresponding argument shall be a pointer to the initial
275 character of an array large enough to accept the sequence
276 and a terminating NUL (0) character, which will be added automatically.
279 Matches a nonempty sequence of characters from a set of expected
282 The corresponding argument shall be a pointer to the initial
283 character of an array large enough to accept the sequence and a terminating
284 NUL character, which will be added automatically.
285 The conversion specifier includes all subsequent characters in the
287 string, up to and including the matching right brace
289 The characters between the brackets (the
291 comprise the scanset, unless the character after the left bracket
294 in which case the scanset contains all characters that do not appear
295 in the scanlist between the circumflex and the right bracket.
296 As a special case, if the conversion specifier begins with
300 the right bracket character is in the scanlist and the next
301 right bracket character is the matching right bracket
302 that ends the specification.
305 character is in the scanlist and is not the first, nor the second
306 where the first character is a
308 nor the last character, the behavior is implementation-defined
309 (in Plan 9: the scanlist includes all characters in the
312 range between the two characters on either side of the
316 Matches a sequence of characters of the number specified by the field width
317 (1 if no field width is present in the directive).
318 The corresponding argument shall be a pointer to the initial character
319 of an array large enough to accept the sequence.
320 No NUL character is added.
323 Matches an implementation-defined set of sequences,
324 which should be the same as the set of sequences that may be
330 (in Plan 9, a hexadecimal number).
331 The corresponding argument shall be a pointer to a pointer to
333 The interpretation of the input item is implementation defined;
334 however, for any input item other than a value converted earlier
335 during the same program execution, the behavior of the
337 conversion is undefined.
340 No input is consumed.
341 The corresponding argument shall be a pointer to integer into which
342 is written the number of characters read from the input stream so far
347 directive does not increment the assignment count returned at the
354 no conversion or assignment occurs.
355 The complete conversion specification shall be
359 If a conversion specification is invalid, the behavior is undefined.
361 The conversion specifiers
366 are also valid and behave the same as, respectively,
372 If end-of-file is encountered during input, conversion is terminated.
373 If end-of-file occurs before any characters matching the current
374 directive have been read (other than leading white space,
375 where permitted), execution of the current directive terminates with
377 otherwise, unless execution of the current directive is terminated
378 with a matching failure, execution of the following directive
379 (if any) is terminated with an input failure.
381 If conversion terminates on a conflicting input character,
382 the offending input character is left unread in the input stream.
383 Trailing white space (including newline characters) is left unread
384 unless matched by a directive.
385 The success of literal matches and suppressed assignments is not
386 directly determinable other than via the
390 The return value from
392 is the number of input items assigned, which can be fewer than
393 provided for, or even zero, in the event of an early matching failure.
394 However, if an input failure occurs before any conversion,