1scanf(3C)                Standard C Library Functions                scanf(3C)
2
3
4

NAME

6       scanf,  fscanf,  sscanf,  vscanf,  vfscanf, vsscanf - convert formatted
7       input
8

SYNOPSIS

10       #include <stdio.h>
11
12       int scanf(const char *restrict format...);
13
14
15       int fscanf(FILE *restrict stream, const char *restrict format...);
16
17
18       int sscanf(const char *restrict s, const char *restrict format...);
19
20
21       #include <stdarg.h>
22       #include <stdio.h>
23
24       int vscanf(const char *format, va_list arg);
25
26
27       int vfscanf(FILE *stream, const char *format, va_list arg);
28
29
30       int vsscanf(const char *s, const char *format, va_list arg);
31
32

DESCRIPTION

34       The scanf() function reads from the standard input stream stdin.
35
36
37       The fscanf() function reads from the named input stream.
38
39
40       The sscanf() function reads from the string s.
41
42
43       The vscanf(), vfscanf(), and vsscanf() functions are equivalent to  the
44       scanf(),  fscanf(),  and  sscanf() functions, respectively, except that
45       instead of being called with a variable number of arguments,  they  are
46       called  with  an  argument  list  as defined by the <stdarg.h> header .
47       These functions do not invoke the va_end()  macro.  Applications  using
48       these functions should call va_end(ap) afterwards to clean up.
49
50
51       Each  function  reads bytes, interprets them according to a format, and
52       stores the results in its arguments. Each expects, as arguments, a con‐
53       trol  string  format  described  below,  and a set of pointer arguments
54       indicating where the converted input should be stored.  The  result  is
55       undefined  if  there  are insufficient arguments for the format. If the
56       format is exhausted while arguments remain, the  excess  arguments  are
57       evaluated but are otherwise ignored.
58
59
60       Conversions  can be applied to the nth argument after the format in the
61       argument list, rather than to the next unused argument. In  this  case,
62       the conversion character % (see below) is replaced by the sequence %n$,
63       where n is a decimal integer in the range [1, NL_ARGMAX]. This  feature
64       provides  for the definition of format strings that select arguments in
65       an order appropriate to specific languages. In format strings  contain‐
66       ing  the  %n$  form  of  conversion  specifications,  it is unspecified
67       whether numbered arguments in the argument list can be referenced  from
68       the format string more than once.
69
70
71       The  format can contain either form of a conversion specification, that
72       is, % or %n$, but the two forms cannot normally be mixed within a  sin‐
73       gle  format  string. The only exception to this is that %% or %* can be
74       mixed with the %n$ form.
75
76
77       The scanf() function in all its forms allows for detection  of  a  lan‐
78       guage-dependent radix character in the input string.  The radix charac‐
79       ter is defined in the program's locale (category  LC_NUMERIC).  In  the
80       POSIX  locale, or in a locale where the radix character is not defined,
81       the radix character defaults to a period (.).
82
83
84       The format is a character string, beginning and ending in  its  initial
85       shift  state,  if any, composed of zero or more directives. Each direc‐
86       tive is composed of one of the following:
87
88           o      one or more white-space  characters  (space,  tab,  newline,
89                  vertical-tab or form-feed characters);
90
91           o      an  ordinary  character (neither % nor a white-space charac‐
92                  ter); or
93
94           o      a conversion specification.
95
96   Conversion Specifications
97       Each conversion specification is introduced by the character %  or  the
98       character sequence %n$, after which the following appear in sequence:
99
100           o      An optional assignment-suppressing character *.
101
102           o      An optional non-zero decimal integer that specifies the max‐
103                  imum field width.
104
105           o      An option length modifier that specifies  the  size  of  the
106                  receiving object.
107
108           o      A  conversion specifier character that specifies the type of
109                  conversion to be applied. The  valid  conversion  characters
110                  are described below.
111
112
113       The scanf() functions execute each directive of the format in turn.  If
114       a directive fails, as detailed below, the function  returns.   Failures
115       are  described  as  input  failures (due to the unavailability of input
116       bytes) or matching failures (due to inappropriate input).
117
118
119       A directive composed of one or more white-space characters is  executed
120       by  reading  input  until no more valid input can be read, or up to the
121       first byte which is not a white-space character which remains unread.
122
123
124       A directive that is an ordinary character is executed as  follows.  The
125       next  byte  is read from the input and compared with the byte that com‐
126       prises the directive; if the comparison shows that they are not equiva‐
127       lent,  the  directive  fails,  and  the  differing and subsequent bytes
128       remain unread.
129
130
131       A directive that is a conversion specification defines a set of  match‐
132       ing  input sequences, as described below for each conversion character.
133       A conversion specification is executed in the following steps:
134
135
136       Input white-space characters (as specified by isspace(3C)) are skipped,
137       unless the conversion specification includes a [, c, C, or n conversion
138       character.
139
140
141       An item is read from the  input  unless  the  conversion  specification
142       includes an n conversion character. The length of the item read is lim‐
143       ited to any specified maximum field  width,  which  is  interpreted  in
144       either  characters  or  bytes depending on the conversion character. In
145       Solaris default mode, the input item is defined as the longest sequence
146       of  input  bytes that forms a matching sequence. In some cases, scanf()
147       might need to read several extra characters beyond the end of the input
148       item  to  find  the  end of a matching sequence. In C99/SUSv3 mode, the
149       input item is defined as the longest sequence of input bytes  that  is,
150       or  is  a prefix of, a matching sequence. With this definition, scanf()
151       need only read at most one character beyond the end of the input  item.
152       Therefore,  in  C99/SUSv3  mode,  some sequences that are acceptable to
153       strtod(3C), strtol(3C),  and  similar  functions  are  unacceptable  to
154       scanf(). In either mode, scanf() attempts to push back any excess bytes
155       read using ungetc(3C). Assuming all such attempts  succeed,  the  first
156       byte, if any, after the input item remains unread. If the length of the
157       input item is 0, the conversion fails. This  condition  is  a  matching
158       failure  unless  end-of-file,  an  encoding error, or a read error pre‐
159       vented input from the stream, in which case it is an input failure.
160
161
162       Except in the case of a % conversion character, the input item (or,  in
163       the case of a %n conversion specification, the count of input bytes) is
164       converted to a type appropriate to the  conversion  character.  If  the
165       input  item is not a matching sequence, the execution of the conversion
166       specification fails; this  condition  is  a  matching  failure.  Unless
167       assignment  suppression was indicated by a *, the result of the conver‐
168       sion is placed in the object pointed to by the first argument following
169       the  format  argument that has not already received a conversion result
170       if the conversion specification is introduced by %, or in the nth argu‐
171       ment  if  introduced by the character sequence %n$. If this object does
172       not have an appropriate type, or if the result of the conversion cannot
173       be represented in the space provided, the behavior is undefined.
174
175   Length Modifiers
176       The length modifiers and their meanings are:
177
178       hh              Specifies  that a following d, i, o, u, x, X, or n con‐
179                       version specifier applies  to  an  argument  with  type
180                       pointer to signed char or unsigned char.
181
182
183       h               Specifies  that a following d, i, o, u, x, X, or n con‐
184                       version specifier applies  to  an  argument  with  type
185                       pointer to short or unsigned short.
186
187
188       l (ell)         Specifies  that a following d, i, o, u, x, X, or n con‐
189                       version specifier applies  to  an  argument  with  type
190                       pointer  to  long or unsigned long; that a following a,
191                       A, e, E, f, F, g, or G conversion specifier applies  to
192                       an argument with type pointer to double; or that a fol‐
193                       lowing c, s, or [ conversion specifier  applies  to  an
194                       argument with type pointer to wchar_t.
195
196
197       ll (ell-ell)    Specifies  that a following d, i, o, u, x, X, or n con‐
198                       version specifier applies  to  an  argument  with  type
199                       pointer to long long or unsigned long long.
200
201
202       j               Specifies  that a following d, i, o, u, x, X, or n con‐
203                       version specifier applies  to  an  argument  with  type
204                       pointer to intmax_t or uintmax_t.
205
206
207       z               Specifies  that a following d, i, o, u, x, X, or n con‐
208                       version specifier applies  to  an  argument  with  type
209                       pointer  to  size_t or the corresponding signed integer
210                       type.
211
212
213       t               Specifies that a following d, i, o, u, x, X, or n  con‐
214                       version  specifier  applies  to  an  argument with type
215                       pointer to  ptrdiff_t  or  the  corresponding  unsigned
216                       type.
217
218
219       L               Specifies  that  a  following a, A, e, E, f, F, g, or G
220                       conversion specifier applies to an argument  with  type
221                       pointer to long double.
222
223
224
225       If  a  length modifier appears with any conversion specifier other than
226       as specified above, the behavior is undefined.
227
228   Conversion Characters
229       The following conversion characters are valid:
230
231       d          Matches an optionally signed decimal integer,  whose  format
232                  is  the  same  as  expected for the subject sequence of str‐
233                  tol(3C) with the value 10 for  the  base  argument.  In  the
234                  absence  of a size modifier, the corresponding argument must
235                  be a pointer to int.
236
237
238       i          Matches an optionally signed integer, whose  format  is  the
239                  same as expected for the subject sequence of strtol() with 0
240                  for the base argument. In the absence of  a  size  modifier,
241                  the corresponding argument must be a pointer to int.
242
243
244       o          Matches  an optionally signed octal integer, whose format is
245                  the same as expected for the subject sequence of strtoul(3C)
246                  with  the value 8 for the base argument. In the absence of a
247                  size modifier, the corresponding argument must be a  pointer
248                  to unsigned int.
249
250
251       u          Matches  an  optionally signed decimal integer, whose format
252                  is the same as expected for the  subject  sequence  of  str‐
253                  toul()  with  the  value  10  for  the base argument. In the
254                  absence of a size modifier, the corresponding argument  must
255                  be a pointer to unsigned int.
256
257
258       x          Matches an optionally signed hexadecimal integer, whose for‐
259                  mat is the same as expected for the subject sequence of str‐
260                  toul()  with  the  value  16  for  the base argument. In the
261                  absence of a size modifier, the corresponding argument  must
262                  be a pointer to unsigned int.
263
264
265       a,e,f,g    Matches  an  optionally signed floating-point number, infin‐
266                  ity, or NaN, whose format is the same as  expected  for  the
267                  subject  sequence  of  strtod(3C).  In the absence of a size
268                  modifier, the corresponding argument must be  a  pointer  to
269                  float. The e, f, and g specifiers match hexadecimal floating
270                  point values only in C99/SUSv3 (see standards(5)) mode,  but
271                  the  a  specifier  always matches hexadecimal floating point
272                  values.
273
274                  These  conversion  specifiers  match  any  subject  sequence
275                  accepted  by  strtod(3C),  including the INF, INFINITY, NAN,
276                  and NAN(n-char-sequence) forms.  The result of  the  conver‐
277                  sion is the same as that of calling strtod() (or strtof() or
278                  strtold()) with the matching sequence, including the raising
279                  of  floating  point  exceptions  and the setting of errno to
280                  ERANGE, if applicable.
281
282
283       s          Matches a sequence of bytes that are not white-space charac‐
284                  ters.  The  corresponding  argument must be a pointer to the
285                  initial byte of an array of char, signed char,  or  unsigned
286                  char  large  enough to accept the sequence and a terminating
287                  null character code, which will be added automatically.
288
289                  If an l (ell) qualifier is present, the input is a  sequence
290                  of  characters that begins in the initial shift state.  Each
291                  character is converted to a wide-character as if by  a  call
292                  to  the  mbrtowc(3C)  function,  with  the  conversion state
293                  described by an mbstate_t object initialized to zero  before
294                  the  first  character is converted.  The corresponding argu‐
295                  ment must be a pointer to an array of wchar_t  large  enough
296                  to  accept the sequence and the terminating null  wide-char‐
297                  acter, which will be added automatically.
298
299
300       [          Matches a non-empty sequence of characters  from  a  set  of
301                  expected  characters  (the  scanset).  The  normal skip over
302                  white-space characters is suppressed in this case. The  cor‐
303                  responding argument must be a pointer to the initial byte of
304                  an array of char, signed char, or unsigned char large enough
305                  to  accept  the  sequence and a terminating null byte, which
306                  will be added automatically.
307
308                  If an l (ell) qualifier is present, the input is a  sequence
309                  of  characters that begins in the initial shift state.  Each
310                  character in the sequence is converted to  a  wide-character
311                  as  if by a call to the mbrtowc() function, with the conver‐
312                  sion state described by an mbstate_t object  initialized  to
313                  zero  before  the  first character is converted.  The corre‐
314                  sponding argument must be a pointer to an array  of  wchar_t
315                  large enough to accept the sequence and the terminating null
316                  wide-character, which will be added automatically.
317
318                  The conversion specification includes all subsequent charac‐
319                  ters  in  the format string up to and including the matching
320                  right square bracket (]). The characters between the  square
321                  brackets  (the  scanlist)  comprise  the scanset, unless the
322                  character after the left square bracket is a circumflex (^),
323                  in  which  case  the scanset contains all characters that do
324                  not appear in the scanlist between the  circumflex  and  the
325                  right square bracket. If the conversion specification begins
326                  with [] or [^], the right square bracket is included in  the
327                  scanlist  and  the next right square bracket is the matching
328                  right square bracket that ends the conversion specification;
329                  otherwise  the  first  right  square bracket is the one that
330                  ends the conversion specification. If a - is in the scanlist
331                  and  is  not  the  first character, nor the second where the
332                  first character is a ^, nor the last character, it indicates
333                  a range of characters to be matched.
334
335
336       c          Matches  a sequence of characters of the number specified by
337                  the field width (1 if no field width is present in the  con‐
338                  version specification). The corresponding argument must be a
339                  pointer to the initial byte of  an  array  of  char,  signed
340                  char,  or unsigned char large enough to accept the sequence.
341                  No null byte is added.  The  normal  skip  over  white-space
342                  characters is suppressed in this case.
343
344                  If  an l (ell) qualifier is present, the input is a sequence
345                  of characters that begins in the initial shift state.   Each
346                  character  in  the sequence is converted to a wide-character
347                  as if by a call to the mbrtowc() function, with the  conver‐
348                  sion  state  described by an mbstate_t object initialized to
349                  zero before the first character is  converted.   The  corre‐
350                  sponding  argument  must be a pointer to an array of wchar_t
351                  large enough to accept the resulting sequence of  wide-char‐
352                  acters.  No null wide-character is added.
353
354
355       p          Matches  the set of sequences that is the same as the set of
356                  sequences that is produced by the %p conversion of the  cor‐
357                  responding  printf(3C) functions. The corresponding argument
358                  must be a pointer to a pointer to void. If the input item is
359                  a value converted earlier during the same program execution,
360                  the pointer that results will compare equal to  that  value;
361                  otherwise the behavior of the %p conversion is undefined.
362
363
364       n          No  input  is consumed. The corresponding argument must be a
365                  pointer to the integer into which is to be written the  num‐
366                  ber  of bytes read from the input so far by this call to the
367                  scanf() functions. Execution of a %n  conversion  specifica‐
368                  tion does not increment the assignment count returned at the
369                  completion of execution of the function.
370
371
372       C          Same as lc.
373
374
375       S          Same as ls.
376
377
378       %          Matches a single %; no conversion or assignment occurs.  The
379                  complete conversion specification must be %%.
380
381
382
383       If a conversion specification is invalid, the behavior is undefined.
384
385
386       The  conversion  characters A, E, F, G, and X are also valid and behave
387       the same as, respectively, a, e, f, g, and x.
388
389
390       If end-of-file is encountered during input, conversion  is  terminated.
391       If  end-of-file occurs before any bytes matching the current conversion
392       specification (except for %n) have been read (other than leading white-
393       space characters, where permitted), execution of the current conversion
394       specification terminates with an input failure.  Otherwise, unless exe‐
395       cution  of  the  current  conversion specification is terminated with a
396       matching failure, execution of the following  conversion  specification
397       (if any) is terminated with an input failure.
398
399
400       Reaching  the end of the string in sscanf() is equivalent to encounter‐
401       ing end-of-file for fscanf().
402
403
404       If conversion terminates on a conflicting input, the offending input is
405       left  unread  in the input. Any trailing white space (including newline
406       characters) is left unread unless matched by  a  conversion  specifica‐
407       tion. The success of literal matches and suppressed assignments is only
408       directly determinable via the %n conversion specification.
409
410
411       The fscanf() and scanf() functions may mark the st_atime field  of  the
412       file  associated  with  stream  for  update. The st_atime field will be
413       marked for update by  the  first  successful  execution  of  fgetc(3C),
414       fgets(3C),  fread(3C),  fscanf(),  getc(3C),  getchar(3C), gets(3C), or
415       scanf() using stream that returns data not supplied by a prior call  to
416       ungetc(3C).
417

RETURN VALUES

419       Upon  successful  completion, these functions return the number of suc‐
420       cessfully matched and assigned input items; this number can be 0 in the
421       event of an early matching failure.  If the input ends before the first
422       matching failure or conversion, EOF  is  returned.   If  a  read  error
423       occurs  the error indicator for the stream is set, EOF is returned, and
424       errno is set to indicate the error.
425

ERRORS

427       For the conditions under which the scanf() functions will fail and  may
428       fail, refer to fgetc(3C) or fgetwc(3C).
429
430
431       In addition, fscanf() may fail if:
432
433       EILSEQ    Input byte sequence does not form a valid character.
434
435
436       EINVAL    There are insufficient arguments.
437
438

USAGE

440       If  the  application  calling  the scanf() functions has any objects of
441       type wint_t or wchar_t, it must also include the  header  <wchar.h>  to
442       have these objects defined.
443

EXAMPLES

445       Example 1 The call:
446
447         int i, n; float x; char name[50];
448         n = scanf("%d%f%s", &i, &x, name)
449
450
451
452       with the input line:
453
454
455         25 54.32E-1 Hamster
456
457
458
459       will  assign to n the value 3, to i the value 25, to x the value 5.432,
460       and name will contain the string Hamster.
461
462
463       Example 2 The call:
464
465         int i; float x; char name[50];
466         (void) scanf("%2d%f%*d %[0123456789]", &i, &x, name);
467
468
469
470       with input:
471
472
473         56789 0123 56a72
474
475
476
477       will assign 56 to i, 789.0 to x, skip 0123, and place the  string  56\0
478       in name. The next call to getchar(3C) will return the character a.
479
480

ATTRIBUTES

482       See attributes(5) for descriptions of the following attributes:
483
484
485
486
487       ┌─────────────────────────────┬─────────────────────────────┐
488       │ATTRIBUTE TYPE               │ATTRIBUTE VALUE              │
489       ├─────────────────────────────┼─────────────────────────────┤
490       │CSI                          │Enabled                      │
491       ├─────────────────────────────┼─────────────────────────────┤
492       │Interface Stability          │Committed                    │
493       ├─────────────────────────────┼─────────────────────────────┤
494       │MT-Level                     │MT-Safe                      │
495       ├─────────────────────────────┼─────────────────────────────┤
496       │Standard                     │See standards(5).            │
497       └─────────────────────────────┴─────────────────────────────┘
498

SEE ALSO

500       fgetc(3C),  fgets(3C),  fgetwc(3C), fread(3C), isspace(3C), printf(3C),
501       setlocale(3C),  strtod(3C),   strtol(3C),   strtoul(3C),   wcrtomb(3C),
502       ungetc(3C), attributes(5), standards(5)
503

NOTES

505       The  behavior  of  the conversion specifier "%%" has changed for all of
506       the functions described on this manual page. Previously the "%%" speci‐
507       fier  accepted a "%" character from input only if there were no preced‐
508       ing whitespace characters.  The new behavior accepts "%" even if  there
509       are  preceding whitespace characters. This new behavior now aligns with
510       the description on this manual page and in various  standards.  If  the
511       old  behavior  is  desired, the conversion specification "%*[%]" can be
512       used.
513
514
515
516SunOS 5.11                        10 Jul 2008                        scanf(3C)
Impressum