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 *restrict format, ...);
13       int fscanf(FILE *restrict stream,
14                  const char *restrict format, ...);
15       int sscanf(const char *restrict str,
16                  const char *restrict format, ...);
17
18       #include <stdarg.h>
19
20       int vscanf(const char *restrict format, va_list ap);
21       int vfscanf(FILE *restrict stream,
22                  const char *restrict format, va_list ap);
23       int vsscanf(const char *restrict str,
24                  const char *restrict format, va_list ap);
25
26   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
27
28       vscanf(), vsscanf(), vfscanf():
29           _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
30

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

ATTRIBUTES

282       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
283       tributes(7).
284
285       ┌─────────────────────────────────────┬───────────────┬────────────────┐
286Interface                            Attribute     Value          
287       ├─────────────────────────────────────┼───────────────┼────────────────┤
288scanf(), fscanf(), sscanf(),         │ Thread safety │ MT-Safe locale │
289vscanf(), vsscanf(), vfscanf()       │               │                │
290       └─────────────────────────────────────┴───────────────┴────────────────┘
291

CONFORMING TO

293       The functions fscanf(), scanf(), and sscanf() conform to  C89  and  C99
294       and POSIX.1-2001.  These standards do not specify the ERANGE error.
295
296       The  q  specifier is the 4.4BSD notation for long long, while ll or the
297       usage of L in integer conversions is the GNU notation.
298
299       The Linux version of these functions is based on the GNU libio library.
300       Take  a  look  at the info documentation of GNU libc (glibc-1.08) for a
301       more concise description.
302

NOTES

304   The 'a' assignment-allocation modifier
305       Originally, the GNU C library supported dynamic allocation  for  string
306       inputs (as a nonstandard extension) via the a character.  (This feature
307       is present at least as far back as glibc 2.0.)  Thus, one  could  write
308       the  following  to  have scanf() allocate a buffer for an input string,
309       with a pointer to that buffer being returned in *buf:
310
311           char *buf;
312           scanf("%as", &buf);
313
314       The use of the letter a for this purpose was problematic,  since  a  is
315       also specified by the ISO C standard as a synonym for f (floating-point
316       input).  POSIX.1-2008 instead specifies the m modifier  for  assignment
317       allocation (as documented in DESCRIPTION, above).
318
319       Note  that  the  a modifier is not available if the program is compiled
320       with gcc -std=c99 or gcc -D_ISOC99_SOURCE (unless _GNU_SOURCE  is  also
321       specified),  in  which  case  the  a  is interpreted as a specifier for
322       floating-point numbers (see above).
323
324       Support for the m modifier was added to  glibc  starting  with  version
325       2.7, and new programs should use that modifier instead of a.
326
327       As  well as being standardized by POSIX, the m modifier has the follow‐
328       ing further advantages over the use of a:
329
330       * It may also be applied to %c conversion specifiers (e.g., %3mc).
331
332       * It avoids ambiguity with respect to the %a floating-point  conversion
333         specifier (and is unaffected by gcc -std=c99 etc.).
334

BUGS

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

EXAMPLES

352       To use the dynamic allocation conversion  specifier,  specify  m  as  a
353       length  modifier  (thus %ms or %m[range]).  The caller must free(3) the
354       returned string, as in the following example:
355
356           char *p;
357           int n;
358
359           errno = 0;
360           n = scanf("%m[a-z]", &p);
361           if (n == 1) {
362               printf("read: %s\n", p);
363               free(p);
364           } else if (errno != 0) {
365               perror("scanf");
366           } else {
367               fprintf(stderr, "No matching characters\n");
368           }
369
370       As shown in the above example, it is necessary to call free(3) only  if
371       the scanf() call successfully read a string.
372

SEE ALSO

374       getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)
375

COLOPHON

377       This  page  is  part of release 5.13 of the Linux man-pages project.  A
378       description of the project, information about reporting bugs,  and  the
379       latest     version     of     this    page,    can    be    found    at
380       https://www.kernel.org/doc/man-pages/.
381
382
383
384GNU                               2021-03-22                          SCANF(3)
Impressum