1FSCANF(3P)                 POSIX Programmer's Manual                FSCANF(3P)
2
3
4

PROLOG

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
11

NAME

13       fscanf, scanf, sscanf — convert formatted input
14

SYNOPSIS

16       #include <stdio.h>
17
18       int fscanf(FILE *restrict stream, const char *restrict format, ...);
19       int scanf(const char *restrict format, ...);
20       int sscanf(const char *restrict s, const char *restrict format, ...);
21

DESCRIPTION

23       The functionality described on this reference page is aligned with  the
24       ISO C  standard.  Any  conflict between the requirements described here
25       and the ISO C standard is unintentional. This  volume  of  POSIX.1‐2008
26       defers to the ISO C standard.
27
28       The  fscanf()  function  shall  read  from the named input stream.  The
29       scanf() function shall read from the standard input stream stdin.   The
30       sscanf()  function  shall  read from the string s.  Each function reads
31       bytes, interprets them according to a format, and stores the results in
32       its  arguments.  Each  expects,  as  arguments, a control string format
33       described below, and a set of pointer arguments  indicating  where  the
34       converted  input should be stored. The result is undefined if there are
35       insufficient arguments for the format. If the format is exhausted while
36       arguments remain, the excess arguments shall be evaluated but otherwise
37       ignored.
38
39       Conversions can be applied to the nth argument after the format in  the
40       argument  list,  rather than to the next unused argument. In this case,
41       the conversion specifier character % (see below)  is  replaced  by  the
42       sequence   "%n$",   where   n   is  a  decimal  integer  in  the  range
43       [1,{NL_ARGMAX}].  This feature provides for the  definition  of  format
44       strings  that select arguments in an order appropriate to specific lan‐
45       guages. In format strings containing the "%n$" form of conversion spec‐
46       ifications,  it  is unspecified whether numbered arguments in the argu‐
47       ment list can be referenced from the format string more than once.
48
49       The format can contain either form of a  conversion  specification—that
50       is, % or "%n$"—but the two forms cannot be mixed within a single format
51       string. The only exception to this is that %% or %* can be  mixed  with
52       the  "%n$" form. When numbered argument specifications are used, speci‐
53       fying the Nth argument requires that all the  leading  arguments,  from
54       the first to the (N−1)th, are pointers.
55
56       The  fscanf() function in all its forms shall allow detection of a lan‐
57       guage-dependent radix character in the input string. The radix  charac‐
58       ter  is  defined  in  the current locale (category LC_NUMERIC).  In the
59       POSIX locale, or in a locale where the radix character is not  defined,
60       the radix character shall default to a <period> ('.').
61
62       The  format  is a character string, beginning and ending in its initial
63       shift state, if any, composed of zero or more directives.  Each  direc‐
64       tive is composed of one of the following: one or more white-space char‐
65       acters (<space>, <tab>, <newline>, <vertical-tab>, or <form-feed>);  an
66       ordinary character (neither '%' nor a white-space character); or a con‐
67       version specification. Each conversion specification is  introduced  by
68       the character '%' or the character sequence "%n$", after which the fol‐
69       lowing appear in sequence:
70
71        *  An optional assignment-suppressing character '*'.
72
73        *  An optional non-zero decimal integer  that  specifies  the  maximum
74           field width.
75
76        *  An optional assignment-allocation character 'm'.
77
78        *  An  option length modifier that specifies the size of the receiving
79           object.
80
81        *  A conversion specifier character that specifies the type of conver‐
82           sion  to  be applied. The valid conversion specifiers are described
83           below.
84
85       The fscanf() functions shall execute each directive of  the  format  in
86       turn.  If  a  directive  fails,  as  detailed below, the function shall
87       return. Failures are described as input failures (due to  the  unavail‐
88       ability  of  input  bytes)  or  matching failures (due to inappropriate
89       input).
90
91       A directive composed of one or more  white-space  characters  shall  be
92       executed  by reading input until no more valid input can be read, or up
93       to the first byte which is not a white-space character,  which  remains
94       unread.
95
96       A directive that is an ordinary character shall be executed as follows:
97       the next byte shall be read from the input and compared with  the  byte
98       that comprises the directive; if the comparison shows that they are not
99       equivalent, the directive shall fail, and the differing and  subsequent
100       bytes  shall  remain  unread.  Similarly,  if  end-of-file, an encoding
101       error, or a read error prevents a character from being read, the direc‐
102       tive shall fail.
103
104       A  directive that is a conversion specification defines a set of match‐
105       ing input sequences, as described below for each conversion  character.
106       A conversion specification shall be executed in the following steps.
107
108       Input  white-space  characters  (as  specified  by  isspace()) shall be
109       skipped, unless the conversion specification includes a [, c, C,  or  n
110       conversion specifier.
111
112       An  item shall be read from the input, unless the conversion specifica‐
113       tion includes an n conversion specifier. An input item shall be defined
114       as  the  longest  sequence  of input bytes (up to any specified maximum
115       field width, which may be measured in characters or bytes dependent  on
116       the conversion specifier) which is an initial subsequence of a matching
117       sequence. The first byte, if any, after the  input  item  shall  remain
118       unread. If the length of the input item is 0, the execution of the con‐
119       version specification shall fail; this condition is a matching failure,
120       unless  end-of-file, an encoding error, or a read error prevented input
121       from the stream, in which case it is an input failure.
122
123       Except in the case of a % conversion specifier, the input item (or,  in
124       the  case  of  a %n conversion specification, the count of input bytes)
125       shall be converted to a type appropriate to the  conversion  character.
126       If the input item is not a matching sequence, the execution of the con‐
127       version specification fails; this  condition  is  a  matching  failure.
128       Unless assignment suppression was indicated by a '*', the result of the
129       conversion shall be placed in the object pointed to by the first  argu‐
130       ment following the format argument that has not already received a con‐
131       version result if the conversion specification is introduced by  %,  or
132       in  the nth argument if introduced by the character sequence "%n$".  If
133       this object does not have an appropriate type, or if the result of  the
134       conversion cannot be represented in the space provided, the behavior is
135       undefined.
136
137       The %c, %s, and %[  conversion  specifiers  shall  accept  an  optional
138       assignment-allocation  character 'm', which shall cause a memory buffer
139       to be allocated to hold the string converted  including  a  terminating
140       null  character. In such a case, the argument corresponding to the con‐
141       version specifier should be a reference to a pointer variable that will
142       receive  a pointer to the allocated buffer. The system shall allocate a
143       buffer as if malloc() had been called. The application shall be respon‐
144       sible for freeing the memory after usage. If there is insufficient mem‐
145       ory to allocate a buffer, the function shall set errno to [ENOMEM]  and
146       a  conversion error shall result. If the function returns EOF, any mem‐
147       ory successfully allocated for parameters  using  assignment-allocation
148       character 'm' by this call shall be freed before the function returns.
149
150       The length modifiers and their meanings are:
151
152       hh      Specifies  that  a  following d, i, o, u, x, X, or n conversion
153               specifier applies to an argument with type  pointer  to  signed
154               char or unsigned char.
155
156       h       Specifies  that  a  following d, i, o, u, x, X, or n conversion
157               specifier applies to an argument with type pointer to short  or
158               unsigned short.
159
160       l (ell) Specifies  that  a  following d, i, o, u, x, X, or n conversion
161               specifier applies to an argument with type pointer to  long  or
162               unsigned  long; that a following a, A, e, E, f, F, g, or G con‐
163               version specifier applies to an argument with type  pointer  to
164               double;  or  that  a  following c, s, or [ conversion specifier
165               applies to an argument with type pointer to  wchar_t.   If  the
166               'm'  assignment-allocation  character is specified, the conver‐
167               sion applies to an argument with the type pointer to a  pointer
168               to wchar_t.
169
170       ll (ell-ell)
171               Specifies  that  a  following d, i, o, u, x, X, or n conversion
172               specifier applies to an argument with type pointer to long long
173               or unsigned long long.
174
175       j       Specifies  that  a  following d, i, o, u, x, X, or n conversion
176               specifier applies to an argument with type pointer to  intmax_t
177               or uintmax_t.
178
179       z       Specifies  that  a  following d, i, o, u, x, X, or n conversion
180               specifier applies to an argument with type pointer to size_t or
181               the corresponding signed integer type.
182
183       t       Specifies  that  a  following d, i, o, u, x, X, or n conversion
184               specifier applies to an argument with type pointer to ptrdiff_t
185               or the corresponding unsigned type.
186
187       L       Specifies that a following a, A, e, E, f, F, g, or G conversion
188               specifier applies to an argument with type pointer to long dou‐
189               ble.
190
191       If  a  length modifier appears with any conversion specifier other than
192       as specified above, the behavior is undefined.
193
194       The following conversion specifiers are valid:
195
196       d       Matches an optionally signed decimal integer, whose  format  is
197               the  same as expected for the subject sequence of strtol() with
198               the value 10 for the base argument. In the absence  of  a  size
199               modifier,  the  application shall ensure that the corresponding
200               argument is a pointer to int.
201
202       i       Matches an optionally signed integer, whose format is the  same
203               as expected for the subject sequence of strtol() with 0 for the
204               base argument. In the absence of a size modifier, the  applica‐
205               tion  shall ensure that the corresponding argument is a pointer
206               to int.
207
208       o       Matches an optionally signed octal integer, whose format is the
209               same as expected for the subject sequence of strtoul() with the
210               value 8 for the base argument. In the absence of a  size  modi‐
211               fier, the application shall ensure that the corresponding argu‐
212               ment is a pointer to unsigned.
213
214       u       Matches an optionally signed decimal integer, whose  format  is
215               the same as expected for the subject sequence of strtoul() with
216               the value 10 for the base argument. In the absence  of  a  size
217               modifier,  the  application shall ensure that the corresponding
218               argument is a pointer to unsigned.
219
220       x       Matches an optionally signed hexadecimal integer, whose  format
221               is  the  same as expected for the subject sequence of strtoul()
222               with the value 16 for the base argument. In the  absence  of  a
223               size  modifier,  the  application  shall ensure that the corre‐
224               sponding argument is a pointer to unsigned.
225
226       a, e, f, g
227               Matches an optionally signed floating-point  number,  infinity,
228               or  NaN,  whose  format is the same as expected for the subject
229               sequence of strtod().  In the absence of a size  modifier,  the
230               application  shall  ensure that the corresponding argument is a
231               pointer to float.
232
233               If the fprintf() family of functions generates character string
234               representations for infinity and NaN (a symbolic entity encoded
235               in floating-point format)  to  support  IEEE Std 754‐1985,  the
236               fscanf() family of functions shall recognize them as input.
237
238       s       Matches  a  sequence  of bytes that are not white-space charac‐
239               ters. If the 'm' assignment-allocation character is not  speci‐
240               fied, the application shall ensure that the corresponding argu‐
241               ment is a pointer to the initial byte  of  an  array  of  char,
242               signed  char,  or  unsigned  char  large  enough  to accept the
243               sequence and a terminating null character code, which shall  be
244               added  automatically.   Otherwise, the application shall ensure
245               that the corresponding argument is a pointer to a pointer to  a
246               char.
247
248               If  an l (ell) qualifier is present, the input is a sequence of
249               characters that begins in the initial shift state. Each charac‐
250               ter  shall  be converted to a wide character as if by a call to
251               the mbrtowc() function, with the conversion state described  by
252               an  mbstate_t object initialized to zero before the first char‐
253               acter is converted.  If the 'm' assignment-allocation character
254               is  not specified, the application shall ensure that the corre‐
255               sponding argument is a pointer to an  array  of  wchar_t  large
256               enough  to  accept  the  sequence and the terminating null wide
257               character, which shall be added automatically.  Otherwise,  the
258               application  shall  ensure that the corresponding argument is a
259               pointer to a pointer to a wchar_t.
260
261       [       Matches a non-empty sequence of bytes from a  set  of  expected
262               bytes  (the scanset).  The normal skip over white-space charac‐
263               ters shall be suppressed in this case. If the  'm'  assignment-
264               allocation  character  is  not specified, the application shall
265               ensure that the corresponding argument is a pointer to the ini‐
266               tial  byte  of  an array of char, signed char, or unsigned char
267               large enough to accept the  sequence  and  a  terminating  null
268               byte,  which  shall  be  added  automatically.   Otherwise, the
269               application shall ensure that the corresponding argument  is  a
270               pointer to a pointer to a char.
271
272               If  an l (ell) qualifier is present, the input is a sequence of
273               characters that begins in the initial shift state. Each charac‐
274               ter  in  the sequence shall be converted to a wide character as
275               if by a call to the mbrtowc()  function,  with  the  conversion
276               state  described  by  an  mbstate_t  object initialized to zero
277               before the first character is converted.  If  the  'm'  assign‐
278               ment-allocation  character  is  not  specified, the application
279               shall ensure that the corresponding argument is a pointer to an
280               array  of  wchar_t  large enough to accept the sequence and the
281               terminating null wide character, which shall be added automati‐
282               cally.
283               Otherwise,  the application shall ensure that the corresponding
284               argument is a pointer to a pointer to a wchar_t.
285
286               The conversion specification includes all subsequent  bytes  in
287               the  format  string  up  to  and including the matching <right-
288               square-bracket> (']').  The bytes between the  square  brackets
289               (the  scanlist) comprise the scanset, unless the byte after the
290               <left-square-bracket> is a <circumflex> ('^'),  in  which  case
291               the  scanset contains all bytes that do not appear in the scan‐
292               list between the <circumflex> and  the  <right-square-bracket>.
293               If  the conversion specification begins with "[]" or "[^]", the
294               <right-square-bracket> is included in the scanlist and the next
295               <right-square-bracket>  is  the matching <right-square-bracket>
296               that ends the conversion specification;  otherwise,  the  first
297               <right-square-bracket>  is  the  one  that  ends the conversion
298               specification. If a '−' is in the scanlist and is not the first
299               character,  nor  the second where the first character is a '^',
300               nor the last character, the behavior is implementation-defined.
301
302       c       Matches a sequence of bytes of  the  number  specified  by  the
303               field  width  (1 if no field width is present in the conversion
304               specification). No null byte is added.  The  normal  skip  over
305               white-space characters shall be suppressed in this case. If the
306               'm'  assignment-allocation  character  is  not  specified,  the
307               application  shall  ensure that the corresponding argument is a
308               pointer to the initial byte of an array of char,  signed  char,
309               or  unsigned  char large enough to accept the sequence.  Other‐
310               wise, the application shall ensure that the corresponding argu‐
311               ment is a pointer to a pointer to a char.
312
313               If  an  l  (ell)  qualifier  is  present,  the input shall be a
314               sequence of characters that begins in the initial shift  state.
315               Each character in the sequence is converted to a wide character
316               as if by a call to the mbrtowc() function, with the  conversion
317               state  described  by  an  mbstate_t  object initialized to zero
318               before the first character is converted.  No null wide  charac‐
319               ter is added. If the 'm' assignment-allocation character is not
320               specified, the application shall ensure that the  corresponding
321               argument  is  a  pointer to an array of wchar_t large enough to
322               accept the resulting sequence of wide  characters.   Otherwise,
323               the application shall ensure that the corresponding argument is
324               a pointer to a pointer to a wchar_t.
325
326       p       Matches an implementation-defined set of sequences, which shall
327               be  the same as the set of sequences that is produced by the %p
328               conversion specification of the corresponding  fprintf()  func‐
329               tions.  The  application  shall  ensure  that the corresponding
330               argument is a pointer to a pointer to void.  The interpretation
331               of  the input item is implementation-defined. If the input item
332               is a value converted earlier during the same program execution,
333               the  pointer  that  results  shall compare equal to that value;
334               otherwise, the behavior of the %p conversion  specification  is
335               undefined.
336
337       n       No  input  is  consumed.  The application shall ensure that the
338               corresponding argument is a pointer to the integer  into  which
339               shall be written the number of bytes read from the input so far
340               by this call to the fscanf() functions. Execution of a %n  con‐
341               version  specification shall not increment the assignment count
342               returned at the completion of execution  of  the  function.  No
343               argument  shall be converted, but one shall be consumed. If the
344               conversion  specification  includes  an  assignment-suppressing
345               character or a field width, the behavior is undefined.
346
347       C       Equivalent to lc.
348
349       S       Equivalent to ls.
350
351       %       Matches  a  single  '%'  character; no conversion or assignment
352               occurs. The complete conversion specification shall be %%.
353
354       If a conversion specification is invalid, the behavior is undefined.
355
356       The conversion specifiers A, E, F, G, and X are also valid and shall be
357       equivalent to a, e, f, g, and x, respectively.
358
359       If  end-of-file is encountered during input, conversion shall be termi‐
360       nated. If end-of-file occurs before any bytes matching the current con‐
361       version  specification (except for %n) have been read (other than lead‐
362       ing white-space characters, where permitted), execution of the  current
363       conversion  specification shall terminate with an input failure. Other‐
364       wise, unless execution of the current conversion specification is  ter‐
365       minated  with a matching failure, execution of the following conversion
366       specification (if any) shall be terminated with an input failure.
367
368       Reaching the end of the string  in  sscanf()  shall  be  equivalent  to
369       encountering end-of-file for fscanf().
370
371       If conversion terminates on a conflicting input, the offending input is
372       left unread in the input. Any trailing white space (including <newline>
373       characters)  shall be left unread unless matched by a conversion speci‐
374       fication. The success of literal matches and suppressed assignments  is
375       only directly determinable via the %n conversion specification.
376
377       The  fscanf() and scanf() functions may mark the last data access time‐
378       stamp of the file associated with stream  for  update.  The  last  data
379       access  timestamp  shall  be  marked for update by the first successful
380       execution of fgetc(), fgets(), fread(), getc(), getchar(),  getdelim(),
381       getline(),  gets(), fscanf(), or scanf() using stream that returns data
382       not supplied by a prior call to ungetc().
383

RETURN VALUE

385       Upon successful completion, these functions shall return the number  of
386       successfully  matched and assigned input items; this number can be zero
387       in the event of an early matching failure. If the input ends before the
388       first conversion (if any) has completed, and without a matching failure
389       having occurred, EOF shall be returned. If an error occurs  before  the
390       first conversion (if any) has completed, and without a matching failure
391       having occurred, EOF shall be returned and errno shall be set to  indi‐
392       cate  the  error.   If a read error occurs, the error indicator for the
393       stream shall be set.
394

ERRORS

396       For the conditions under which the  fscanf()  functions  fail  and  may
397       fail, refer to fgetc() or fgetwc().
398
399       In addition, the fscanf() function shall fail if:
400
401       EILSEQ Input byte sequence does not form a valid character.
402
403       ENOMEM Insufficient storage space is available.
404
405       In addition, the fscanf() function may fail if:
406
407       EINVAL There are insufficient arguments.
408
409       The following sections are informative.
410

EXAMPLES

412       The call:
413
414           int i, n; float x; char name[50];
415           n = scanf("%d%f%s", &i, &x, name);
416
417       with the input line:
418
419           25 54.32E−1 Hamster
420
421       assigns  to n the value 3, to i the value 25, to x the value 5.432, and
422       name contains the string "Hamster".
423
424       The call:
425
426           int i; float x; char name[50];
427           (void) scanf("%2d%f%*d %[0123456789]", &i, &x, name);
428
429       with input:
430
431           56789 0123 56a72
432
433       assigns 56 to i, 789.0 to x, skips 0123, and places the  string  "56\0"
434       in name.  The next call to getchar() shall return the character 'a'.
435
436   Reading Data into an Array
437       The  following  call uses fscanf() to read three floating-point numbers
438       from standard input into the input array.
439
440           float input[3]; fscanf (stdin, "%f %f %f", input, input+1, input+2);
441

APPLICATION USAGE

443       If the application calling fscanf() has any objects of type  wint_t  or
444       wchar_t,  it  must  also  include  the  <wchar.h>  header to have these
445       objects defined.
446
447       For functions that allocate memory as if by malloc(),  the  application
448       should  release  such memory when it is no longer required by a call to
449       free().  For fscanf(), this is memory allocated  via  use  of  the  'm'
450       assignment-allocation character.
451

RATIONALE

453       This  function  is  aligned with the ISO/IEC 9899:1999 standard, and in
454       doing so a few ``obvious'' things were not included. Specifically,  the
455       set  of characters allowed in a scanset is limited to single-byte char‐
456       acters.  In other similar places, multi-byte characters have been  per‐
457       mitted,  but  for alignment with the ISO/IEC 9899:1999 standard, it has
458       not been done here. Applications needing this could use the correspond‐
459       ing wide-character functions to achieve the desired results.
460

FUTURE DIRECTIONS

462       None.
463

SEE ALSO

465       Section 2.5, Standard I/O Streams, fprintf(), getc(), setlocale(), str‐
466       tod(), strtol(), strtoul(), wcrtomb()
467
468       The Base Definitions volume of POSIX.1‐2008, Chapter 7, Locale,  <lang‐
469       info.h>, <stdio.h>, <wchar.h>
470
472       Portions  of  this text are reprinted and reproduced in electronic form
473       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
474       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
475       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
476       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
477       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
478       event of any discrepancy between this version and the original IEEE and
479       The Open Group Standard, the original IEEE and The Open Group  Standard
480       is  the  referee document. The original Standard can be obtained online
481       at http://www.unix.org/online.html .
482
483       Any typographical or formatting errors that appear  in  this  page  are
484       most likely to have been introduced during the conversion of the source
485       files to man page format. To report such errors,  see  https://www.ker
486       nel.org/doc/man-pages/reporting_bugs.html .
487
488
489
490IEEE/The Open Group                  2013                           FSCANF(3P)
Impressum