scanf

Syntax

#include <stdio.h> int scanf(const char *format, ...);

Description

This function scans formatted text from stdin and stores it in the variables pointed to by the arguments. See section scanf.

The format string contains regular characters which much match the input exactly as well as a conversion specifiers, which begin with a percent symbol. Any whitespace in the format string matches zero or more of any whitespace characters in the input. Thus, a single space may match a newline and two tabs in the input. All conversions except `c' and `[' also skip leading whitespace automatically. Each conversion specifier contains the following fields:

• An asterisk (`*') which indicates that the input should be converted according to the conversion spec, but not stored anywhere. This allows to describe an input field that is to be skipped.

• A width specifier, which specifies the maximum number of input characters to use in the conversion.

• An optional conversion qualifier, which may be:

  hh

  to specify char;

  h

  to specify short integers;

  j

  to specify intmax_t or uintmax_t integers;

  l

  to specify doubles or long integers;

  ll

  (two lower-case ell letters) to specify long long integers; to specify long doubles, although this is non-standard;

  L

  to specify long doubles;

  t

  to specify ptrdiff_t;

  z

  to specify size_t.

  If the `h' qualifier appears before a specifier that implies conversion to a long or float or double, like in `%hD' or `%hf', it is generally ignored.

• The conversion type specifier(2):

  c

  Copy the next character (or width characters) to the given buffer. This conversion suppresses skipping of the leading whitespace; use `%1s' to read the next non-whitespace character. Unlike with `%s', the copied characters are not terminated with a null character. If the width parameter is not specified, a width of one is implied.

  d

  Convert the input to a signed int using 10 as the base of the number representation.

  hhd

  Convert the input to a signed char using 10 as the base.

  hd

  Convert the input to a signed short using 10 as the base.

  jd

  Convert the input to an intmax_t using 10 as the base.

  ld

  D

  Convert the input to a signed long using 10 as the base.

  Ld

  lld

  lD

  Convert the input to a signed long long using 10 as the base.

  td

  Convert the input to a ptrdiff_t using 10 as the base.

  zd

  Convert the input to a size_t using 10 as the base.

  e

  E

  f

  F

  g

  G

  Convert the input to a floating point number (a float).

  le

  lE

  lf

  lF

  lg

  lG

  Convert the input to a double.

  Le

  LE

  lle

  llE

  Lf

  LF

  llf

  llF

  Lg

  LG

  llg

  llG

  Convert the input to a long double.

  i

  Convert the input, determining base automatically by the presence of 0x or 0 prefixes, and store in a signed int. See section strtol.

  hhi

  Like `i', but stores the result in a signed char.

  hi

  Like `i', but stores the result in a signed short.

  ji

  Like `i', but stores the result in an intmax_t.

  li

  I

  Like `i', but stores the result in a signed long.

  Li

  lli

  lI

  Like `i', but stores the result in a signed long long.

  ti

  Like `i', but stores the result in a ptrdiff_t.

  zi

  Like `i', but stores the result in a size_t.

  n

  Store the number of characters scanned so far into the int pointed to by the argument.

  hhn

  Like `n', but the argument should point to a signed char.

  hn

  Like `n', but the argument should point to a signed short.

  jn

  Like `n', but the argument should point to an intmax_t.

  ln

  Like `n', but the argument should point to a signed long.

  Ln

  lln

  Like `n', but the argument should point to a signed long long.

  tn

  Like `n', but the argument should point to a ptrdiff_t.

  zn

  Like `n', but the argument should point to a size_t.

  o

  Convert the input to an unsigned int, using base 8.

  hho

  Convert the input to an unsigned char, using base 8.

  ho

  Convert the input to an unsigned short, using base 8.

  jo

  Convert the input to an uintmax_t, using base 8.

  lo

  O

  Convert the input to an unsigned long, using base 8.

  Lo

  llo

  lO

  Convert the input to an unsigned long long, using base 8.

  to

  Convert the input to a ptrdiff_t, using base 8.

  zo

  Convert the input to a size_t, using base 8.

  p

  Convert the input to a pointer. This is like using the x format.

  s

  Copy the input to the given string, skipping leading whitespace and copying non-whitespace characters up to the next whitespace. The string stored is then terminated with a null character.

  u

  Convert the input to an unsigned int using 10 as the base.

  hhu

  Convert the input to an unsigned char using 10 as the base.

  hu

  Convert the input to an unsigned short using 10 as the base.

  ju

  Convert the input to an uintmax_t using 10 as the base.

  lu

  U

  Convert the input to an unsigned long using 10 as the base.

  Lu

  llu

  lU

  Convert the input to an unsigned long long using 10 as the base.

  tu

  Convert the input to a ptrdiff_t using 10 as the base.

  zu

  Convert the input to a size_t using 10 as the base.

  x

  X

  Convert the input to an unsigned int, using base 16.

  hhx

  hhX

  Convert the input to an unsigned char, using base 16.

  hx

  hX

  Convert the input to an unsigned short, using base 16.

  jx

  jX

  Convert the input to an uintmax_t, using base 16.

  lx

  lX

  Convert the input to an unsigned long, using base 16.

  Lx

  LX

  llx

  llX

  Convert the input to an unsigned long long, using base 16.

  tx

  tX

  Convert the input to a ptrdiff_t, using base 16.

  zx

  zX

  Convert the input to a size_t, using base 16.

  [...]

  Stores the matched characters in a char array, followed by a terminating null character. If you do not specify the width parameter, scanf behaves as if width had a very large value. Up to width characters are consumed and assigned, provided that they match the specification inside the brackets. The characters between the brackets determine which characters are allowed, and thus when the copying stops. These characters may be regular characters (example: `[abcd]') or a range of characters (example: `[a-d]'). If the first character is a caret (`^'), then the set specifies the set of characters that do not get copied (i.e. the set is negated). To specify that the set contains a close-bracket (`]'), put it immediately after `[' or `[^'. To specify a literal dash (`-'), write it either immediately after `[' or `[^', or immediately before the closing `]'.

  %

  This must match a percent character in the input.

Integer formats make use of strtol or strtoul to perform the actual conversions. Floating-point conversions use strtod and _strtold.

Return Value

The number of items successfully matched and assigned. If input ends, or if there is any input failure before the first item is converted and assigned, EOF is returned. Note that literal characters (including whitespace) in the format string which matched input characters count as "converted items", so input failure after such characters were read and matched will not cause EOF to be returned.

Portability

ANSI/ISO C	C89; C99 (see note 1) (see note 2)
POSIX	1003.2-1992; 1003.1-2001

Notes:

1. The hh, j, t and z conversion specifiers first appeared in the ANSI C99 standard.

2. The conversion specifiers `F', `D', `I', `O', and U are DJGPP extensions; they are provided for compatibility with Borland C and other compilers. The conversion specifiers for the long long data type are GCC extensions. The meaning of `[a-c]' as a range of characters is a very popular extension to ANSI (which merely says a dash "may have a special meaning" in that context).

Example

int x, y; char buf[100]; scanf("%d %d %s", &x, &y, buf); /* read to end-of-line */ scanf("%d %[^\n]\n", &x, buf); /* read letters only */ scanf("%[a-zA-Z]", buf);