1SCANF(3)                   Linux Programmer's Manual                  SCANF(3)
2
3
4

NAME

6       scanf,  fscanf, sscanf, vscanf, vsscanf, vfscanf - input format conver‐
7       sion
8

SYNOPSIS

10       #include <stdio.h>
11
12       int scanf(const char *format, ...);
13       int fscanf(FILE *stream, const char *format, ...);
14       int sscanf(const char *str, const char *format, ...);
15
16       #include <stdarg.h>
17
18       int vscanf(const char *format, va_list ap);
19       int vsscanf(const char *str, const char *format, va_list ap);
20       int vfscanf(FILE *stream, const char *format, va_list ap);
21
22   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
23
24       vscanf(), vsscanf(), vfscanf(): _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE;
25       or cc -std=c99
26

DESCRIPTION

28       The  scanf()  family  of  functions  scans input according to format as
29       described below.  This format may  contain  conversion  specifications;
30       the  results from such conversions, if any, are stored in the locations
31       pointed to by the pointer arguments that follow format.   Each  pointer
32       argument  must  be of a type that is appropriate for the value returned
33       by the corresponding conversion specification.
34
35       If the number of conversion specifications in format exceeds the number
36       of  pointer  arguments,  the  results  are undefined.  If the number of
37       pointer arguments exceeds the number of conversion specifications, then
38       the excess pointer arguments are evaluated, but are otherwise ignored.
39
40       The  scanf() function reads input from the standard input stream stdin,
41       fscanf() reads input from the stream pointer stream, and sscanf() reads
42       its input from the character string pointed to by str.
43
44       The vfscanf() function is analogous to vfprintf(3) and reads input from
45       the stream pointer stream using a variable argument  list  of  pointers
46       (see  stdarg(3).   The vscanf() function scans a variable argument list
47       from the standard input and the vsscanf()  function  scans  it  from  a
48       string; these are analogous to the vprintf(3) and vsprintf(3) functions
49       respectively.
50
51       The format string consists of a sequence of directives  which  describe
52       how  to  process  the sequence of input characters.  If processing of a
53       directive fails, no further input is  read,  and  scanf()  returns.   A
54       "failure"  can  be either of the following: input failure, meaning that
55       input characters were unavailable, or matching  failure,  meaning  that
56       the input was inappropriate (see below).
57
58       A directive is one of the following:
59
60       ·      A sequence of white-space characters (space, tab, newline, etc.;
61              see isspace(3)).  This directive matches  any  amount  of  white
62              space, including none, in the input.
63
64       ·      An ordinary character (i.e., one other than white space or '%').
65              This character must exactly match the next character of input.
66
67       ·      A conversion specification, which commences with a '%' (percent)
68              character.  A sequence of characters from the input is converted
69              according to this specification, and the result is placed in the
70              corresponding  pointer argument.  If the next item of input does
71              not match the conversion specification, the conversion  fails  —
72              this is a matching failure.
73
74       Each  conversion specification in format begins with either the charac‐
75       ter '%' or the character sequence "%n$" (see below for the distinction)
76       followed by:
77
78       ·      An  optional '*' assignment-suppression character: scanf() reads
79              input as directed by the conversion specification, but  discards
80              the  input.   No corresponding pointer argument is required, and
81              this specification is not included in the  count  of  successful
82              assignments returned by scanf().
83
84       ·      An  optional  'a'  character.   This is used with string conver‐
85              sions, and relieves the caller of the need to allocate a  corre‐
86              sponding  buffer to hold the input: instead, scanf() allocates a
87              buffer of sufficient size, and assigns the address of this  buf‐
88              fer  to  the  corresponding  pointer argument, which should be a
89              pointer to a char * variable (this variable does not need to  be
90              initialized  before  the  call).  The caller should subsequently
91              free(3) this buffer when it is no longer required.   This  is  a
92              GNU  extension;  C99  employs  the 'a' character as a conversion
93              specifier (and it can also be used as such in the GNU  implemen‐
94              tation).
95
96       ·      An  optional  decimal  integer which specifies the maximum field
97              width.  Reading of characters stops either when this maximum  is
98              reached or when a nonmatching character is found, whichever hap‐
99              pens first.  Most conversions discard initial white space  char‐
100              acters  (the  exceptions  are  noted below), and these discarded
101              characters don't count towards the maximum field width.   String
102              input conversions store a null terminator ('\0') to mark the end
103              of the input; the maximum field width does not include this ter‐
104              minator.
105
106       ·      An  optional  type  modifier character.  For example, the l type
107              modifier is used with integer conversions such as %d to  specify
108              that  the  corresponding  pointer  argument refers to a long int
109              rather than a pointer to an int.
110
111       ·      A conversion specifier that specifies the type of input  conver‐
112              sion to be performed.
113
114       The conversion specifications in format are of two forms, either begin‐
115       ning with '%' or beginning with "%n$".  The two  forms  should  not  be
116       mixed  in the same format string, except that a string containing "%n$"
117       specifications can include %% and %*.  If format contains '%'  specifi‐
118       cations  then  these  correspond in order with successive pointer argu‐
119       ments.  In the "%n$" form (which is specified in POSIX.1-2001, but  not
120       C99),  n  is  a decimal integer that specifies that the converted input
121       should be placed in the location referred to by the n-th pointer  argu‐
122       ment following format.
123
124   Conversions
125       The following type modifier characters can appear in a conversion spec‐
126       ification:
127
128       h      Indicates that the conversion will be one of d, i, o, u,  x,  X,
129              or  n  and  the  next  pointer  is  a  pointer to a short int or
130              unsigned short int (rather than int).
131
132       hh     As for h, but the next pointer is a pointer to a signed char  or
133              unsigned char.
134
135       j      As  for h, but the next pointer is a pointer to an intmax_t or a
136              uintmax_t.  This modifier was introduced in C99.
137
138       l      Indicates either that the conversion will be one of d, i, o,  u,
139              x,  X,  or  n and the next pointer is a pointer to a long int or
140              unsigned long int (rather than int), or that the conversion will
141              be one of e, f, or g and the next pointer is a pointer to double
142              (rather than float).  Specifying two l characters is  equivalent
143              to L.  If used with %c or %s the corresponding parameter is con‐
144              sidered as a pointer  to  a  wide  character  or  wide-character
145              string respectively.
146
147       L      Indicates  that the conversion will be either e, f, or g and the
148              next pointer is a pointer to long double or the conversion  will
149              be  d,  i,  o, u, or x and the next pointer is a pointer to long
150              long.
151
152       q      equivalent to L.  This specifier does not exist in ANSI C.
153
154       t      As for h, but the next pointer is  a  pointer  to  a  ptrdiff_t.
155              This modifier was introduced in C99.
156
157       z      As  for  h, but the next pointer is a pointer to a size_t.  This
158              modifier was introduced in C99.
159
160       The following conversion specifiers are available:
161
162       %      Matches a literal '%'.  That is, %% in the format string matches
163              a  single  input '%' character.  No conversion is done (but ini‐
164              tial white space characters are discarded), and assignment  does
165              not occur.
166
167       d      Matches  an  optionally signed decimal integer; the next pointer
168              must be a pointer to int.
169
170       D      Equivalent to ld; this exists only for backwards  compatibility.
171              (Note:  thus  only  in  libc4.   In  libc5  and  glibc the %D is
172              silently ignored, causing old programs to fail mysteriously.)
173
174       i      Matches an optionally signed integer; the next pointer must be a
175              pointer  to  int.   The  integer is read in base 16 if it begins
176              with 0x or 0X, in base 8 if it begins with 0,  and  in  base  10
177              otherwise.   Only  characters  that  correspond  to the base are
178              used.
179
180       o      Matches an unsigned octal integer; the next pointer  must  be  a
181              pointer to unsigned int.
182
183       u      Matches  an unsigned decimal integer; the next pointer must be a
184              pointer to unsigned int.
185
186       x      Matches an unsigned hexadecimal integer; the next  pointer  must
187              be a pointer to unsigned int.
188
189       X      Equivalent to x.
190
191       f      Matches  an  optionally  signed  floating-point number; the next
192              pointer must be a pointer to float.
193
194       e      Equivalent to f.
195
196       g      Equivalent to f.
197
198       E      Equivalent to f.
199
200       a      (C99) Equivalent to f.
201
202       s      Matches a  sequence  of  non-white-space  characters;  the  next
203              pointer must be a pointer to character array that is long enough
204              to hold the input sequence and the  terminating  null  character
205              ('\0'), which is added automatically.  The input string stops at
206              white space or at the  maximum  field  width,  whichever  occurs
207              first.
208
209       c      Matches  a  sequence  of characters whose length is specified by
210              the maximum field width (default 1); the next pointer must be  a
211              pointer to char, and there must be enough room for all the char‐
212              acters (no terminating null byte is added).  The usual  skip  of
213              leading  white  space is suppressed.  To skip white space first,
214              use an explicit space in the format.
215
216       [      Matches a nonempty sequence of characters from the specified set
217              of  accepted  characters;  the next pointer must be a pointer to
218              char, and there must be enough room for all  the  characters  in
219              the  string,  plus  a  terminating null byte.  The usual skip of
220              leading white space is suppressed.  The string is to be made  up
221              of  characters  in  (or  not  in)  a  particular set; the set is
222              defined by the characters between the open bracket  [  character
223              and a close bracket ] character.  The set excludes those charac‐
224              ters if the first character after the open bracket is a  circum‐
225              flex  (^).   To  include a close bracket in the set, make it the
226              first character after the open bracket or  the  circumflex;  any
227              other position will end the set.  The hyphen character - is also
228              special; when placed between two other characters, it  adds  all
229              intervening characters to the set.  To include a hyphen, make it
230              the  last  character  before  the  final  close  bracket.    For
231              instance,  [^]0-9-]  means  the  set  "everything  except  close
232              bracket, zero through nine, and hyphen".  The string  ends  with
233              the appearance of a character not in the (or, with a circumflex,
234              in) set or when the field width runs out.
235
236       p      Matches a pointer value (as printed by %p in printf(3); the next
237              pointer must be a pointer to a pointer to void.
238
239       n      Nothing  is expected; instead, the number of characters consumed
240              thus far from the input is  stored  through  the  next  pointer,
241              which  must  be  a  pointer  to  int.  This is not a conversion,
242              although it can be suppressed with the *  assignment-suppression
243              character.   The  C  standard says: "Execution of a %n directive
244              does not increment the assignment count returned at the  comple‐
245              tion of execution" but the Corrigendum seems to contradict this.
246              Probably it is wise not to make any assumptions on the effect of
247              %n conversions on the return value.
248

RETURN VALUE

250       These  functions  return the number of input items successfully matched
251       and assigned, which can be fewer than provided for, or even zero in the
252       event of an early matching failure.
253
254       The  value EOF is returned if the end of input is reached before either
255       the first successful conversion or a matching failure occurs.   EOF  is
256       also returned if a read error occurs, in which case the error indicator
257       for the stream (see ferror(3)) is set, and errno is  set  indicate  the
258       error.
259

ERRORS

261       EAGAIN The file descriptor underlying stream is marked nonblocking, and
262              the read operation would block.
263
264       EBADF  The file descriptor underlying stream is invalid,  or  not  open
265              for reading.
266
267       EILSEQ Input byte sequence does not form a valid character.
268
269       EINTR  The read operation was interrupted by a signal; see signal(7).
270
271       EINVAL Not enough arguments; or format is NULL.
272
273       ENOMEM Out of memory.
274
275       ERANGE The  result  of an integer conversion would exceed the size that
276              can be stored in the corresponding integer type.
277

CONFORMING TO

279       The functions fscanf(), scanf(), and sscanf() conform to  C89  and  C99
280       and POSIX.1-2001.  These standards do not specify the ERANGE error.
281
282       The  q  specifier is the 4.4BSD notation for long long, while ll or the
283       usage of L in integer conversions is the GNU notation.
284
285       The Linux version of these functions is based on the GNU libio library.
286       Take  a  look  at the info documentation of GNU libc (glibc-1.08) for a
287       more concise description.
288

NOTES

290       The GNU C library supports a  nonstandard  extension  that  causes  the
291       library  to  dynamically allocate a string of sufficient size for input
292       strings for the %s and %a[range] conversion specifiers.  To make use of
293       this  feature,  specify a as a length modifier (thus %as or %a[range]).
294       The caller must free(3) the returned string, as in the following  exam‐
295       ple:
296
297           char *p;
298           int n;
299
300           errno = 0;
301           n = scanf("%a[a-z]", &p);
302           if (n == 1) {
303               printf("read: %s\n", p);
304               free(p);
305           } else if (errno != 0) {
306               perror("scanf");
307           } else {
308               fprintf(stderr, "No matching characters\n"):
309           }
310
311       As  shown in the above example, it is only necessary to call free(3) if
312       the scanf() call successfully read a string.
313
314       The a modifier is not available if the program  is  compiled  with  gcc
315       -std=c99  or  gcc  -D_ISOC99_SOURCE  (unless _GNU_SOURCE is also speci‐
316       fied), in which case the a is interpreted as a specifier for  floating-
317       point numbers (see above).
318
319       Since version 2.7, glibc also provides the m modifier for the same pur‐
320       pose as the a modifier.  The m modifier has the following advantages:
321
322       * It may also be applied to %c conversion specifiers (e.g., %3mc).
323
324       * It avoids ambiguity with respect to the %a floating-point  conversion
325         specifier (and is unaffected by gcc -std=c99 etc.)
326
327       * It is specified in the upcoming revision of the POSIX.1 standard.
328

BUGS

330       All  functions  are  fully  C89  conformant, but provide the additional
331       specifiers q and a as well as an additional behavior of  the  L  and  l
332       specifiers.   The  latter  may be considered to be a bug, as it changes
333       the behavior of specifiers defined in C89.
334
335       Some combinations of  the  type  modifiers  and  conversion  specifiers
336       defined by ANSI C do not make sense (e.g.  %Ld).  While they may have a
337       well-defined behavior on Linux, this need not to be so on other  archi‐
338       tectures.  Therefore it usually is better to use modifiers that are not
339       defined by ANSI C at all, that is, use q instead of  L  in  combination
340       with d, i, o, u, x, and X conversions or ll.
341
342       The usage of q is not the same as on 4.4BSD, as it may be used in float
343       conversions equivalently to L.
344

SEE ALSO

346       getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)
347

COLOPHON

349       This page is part of release 3.25 of the Linux  man-pages  project.   A
350       description  of  the project, and information about reporting bugs, can
351       be found at http://www.kernel.org/doc/man-pages/.
352
353
354
355GNU                               2008-07-12                          SCANF(3)
Impressum