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

NAME

6       fscanf, scanf, sscanf - convert formatted input
7

SYNOPSIS

9       #include <stdio.h>
10
11       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
15

DESCRIPTION

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
28       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
38       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
45       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
51       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
60        * An optional assignment-suppressing character '*' .
61
62        * An optional non-zero decimal  integer  that  specifies  the  maximum
63          field width.
64
65        * An  option  length modifier that specifies the size of the receiving
66          object.
67
68        * A conversion specifier character that specifies the type of  conver‐
69          sion  to  be  applied. The valid conversion specifiers are described
70          below.
71
72       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
78       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
83       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
91       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
95       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
99       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
110       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
124       The length modifiers and their meanings are:
125
126       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
130       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
134       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
142       ll (ell-ell)
143
144              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
148       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
152       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
156       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
160       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
164
165       If  a  length modifier appears with any conversion specifier other than
166       as specified above, the behavior is undefined.
167
168       The following conversion specifiers are valid:
169
170       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
176       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
182       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
188       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
194       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
200       a, e, f, g
201
202              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
208       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
213       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
220       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
229       [      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
237       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
246       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
261       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
269       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
278       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
289       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
299       C      Equivalent to lc .
300
301       S      Equivalent to ls .
302
303       %      Matches  a  single  '%'  character;  no conversion or assignment
304              occurs. The complete conversion specification shall be %% .
305
306
307       If a conversion specification is invalid, the behavior is undefined.
308
309       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
312       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
321       Reaching the end of the string  in  sscanf()  shall  be  equivalent  to
322       encountering end-of-file for fscanf().
323
324       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
330       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

RETURN VALUE

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

ERRORS

346       For  the  conditions  under  which  the fscanf() functions fail and may
347       fail, refer to fgetc() or fgetwc() .
348
349       In addition, fscanf() may fail if:
350
351       EILSEQ Input byte sequence does not form a valid character.
352
353       EINVAL There are insufficient arguments.
354
355
356       The following sections are informative.
357

EXAMPLES

359       The call:
360
361
362              int i, n; float x; char name[50];
363              n = scanf("%d%f%s", &i, &x, name);
364
365       with the input line:
366
367
368              25 54.32E-1 Hamster
369
370       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
373       The call:
374
375
376              int i; float x; char name[50];
377              (void) scanf("%2d%f%*d %[0123456789]", &i, &x, name);
378
379       with input:
380
381
382              56789 0123 56a72
383
384       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
387   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
391
392              float input[3]; fscanf (stdin, "%f %f %f", input, input+1, input+2);
393

APPLICATION USAGE

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

RATIONALE

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

FUTURE DIRECTIONS

409       None.
410

SEE ALSO

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 .
426
427
428
429IEEE/The Open Group                  2003                            FSCANF(P)
Impressum