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():
25           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE ||
26           _POSIX_C_SOURCE >= 200112L;
27           or cc -std=c99
28

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

CONFORMING TO

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

NOTES

288       The GNU C library supported the dynamic allocation conversion specifier
289       (as  a  nonstandard extension) via the a character.  This feature seems
290       to be present at least as far back as glibc 2.0.
291
292       It is not available if the program is compiled with gcc -std=c99 or gcc
293       -D_ISOC99_SOURCE  (unless _GNU_SOURCE is also specified), in which case
294       the a is interpreted as a specifier  for  floating-point  numbers  (see
295       above).
296
297       Since version 2.7, glibc also provides the m modifier for the same pur‐
298       pose as the a modifier.  The m modifier has the following advantages:
299
300       * It may also be applied to %c conversion specifiers (e.g., %3mc).
301
302       * It avoids ambiguity with respect to the %a floating-point  conversion
303         specifier (and is unaffected by gcc -std=c99 etc.)
304
305       * It is specified in the POSIX.1-2008 standard.
306

BUGS

308       All  functions  are  fully  C89  conformant, but provide the additional
309       specifiers q and a as well as an additional behavior of  the  L  and  l
310       specifiers.   The  latter  may be considered to be a bug, as it changes
311       the behavior of specifiers defined in C89.
312
313       Some combinations of  the  type  modifiers  and  conversion  specifiers
314       defined by ANSI C do not make sense (e.g., %Ld).  While they may have a
315       well-defined behavior on Linux, this need not to be so on other  archi‐
316       tectures.  Therefore it usually is better to use modifiers that are not
317       defined by ANSI C at all, that is, use q instead of  L  in  combination
318       with d, i, o, u, x, and X conversions or ll.
319
320       The usage of q is not the same as on 4.4BSD, as it may be used in float
321       conversions equivalently to L.
322

EXAMPLE

324       To use the dynamic allocation conversion  specifier,  specify  m  as  a
325       length  modifier  (thus %ms or %m[range]).  The caller must free(3) the
326       returned string, as in the following example:
327
328           char *p;
329           int n;
330
331           errno = 0;
332           n = scanf("%m[a-z]", &p);
333           if (n == 1) {
334               printf("read: %s\n", p);
335               free(p);
336           } else if (errno != 0) {
337               perror("scanf");
338           } else {
339               fprintf(stderr, "No matching characters\n");
340           }
341
342       As shown in the above example, it is necessary to call free(3) only  if
343       the scanf() call successfully read a string.
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.53 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                               2013-01-30                          SCANF(3)
Impressum