scanf,   fscanf,  sscanf,  vscanf,  vsscanf,  vfscanf  -  input  format


   #include <stdio.h>

   int scanf(const char *format, ...);
   int fscanf(FILE *stream, const char *format, ...);
   int sscanf(const char *str, const char *format, ...);

   #include <stdarg.h>

   int vscanf(const char *format, va_list ap);
   int vsscanf(const char *str, const char *format, va_list ap);
   int vfscanf(FILE *stream, const char *format, va_list ap);

   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

   vscanf(), vsscanf(), vfscanf():
       _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L


   The scanf() family of functions scans  input  according  to  format  as
   described  below.   This  format may contain conversion specifications;
   the results from such conversions, if any, are stored in the  locations
   pointed  to  by the pointer arguments that follow format.  Each pointer
   argument must be of a type that is appropriate for the  value  returned
   by the corresponding conversion specification.

   If the number of conversion specifications in format exceeds the number
   of pointer arguments, the results are  undefined.   If  the  number  of
   pointer arguments exceeds the number of conversion specifications, then
   the excess pointer arguments are evaluated, but are otherwise ignored.

   The scanf() function reads input from the standard input stream  stdin,
   fscanf() reads input from the stream pointer stream, and sscanf() reads
   its input from the character string pointed to by str.

   The vfscanf() function is analogous to vfprintf(3) and reads input from
   the  stream  pointer  stream using a variable argument list of pointers
   (see stdarg(3).  The vscanf() function scans a variable  argument  list
   from  the  standard  input  and  the vsscanf() function scans it from a
   string; these are analogous to the vprintf(3) and vsprintf(3) functions

   The  format  string consists of a sequence of directives which describe
   how to process the sequence of input characters.  If  processing  of  a
   directive  fails,  no  further  input  is read, and scanf() returns.  A
   "failure" can be either of the following: input failure,  meaning  that
   input  characters  were  unavailable, or matching failure, meaning that
   the input was inappropriate (see below).

   A directive is one of the following:

   ·      A sequence of white-space characters (space, tab, newline, etc.;
          see  isspace(3)).   This  directive  matches any amount of white
          space, including none, in the input.

   ·      An ordinary character (i.e., one other than white space or '%').
          This character must exactly match the next character of input.

   ·      A conversion specification, which commences with a '%' (percent)
          character.  A sequence of characters from the input is converted
          according to this specification, and the result is placed in the
          corresponding pointer argument.  If the next item of input  does
          not  match  the  conversion specification, the conversion fails—
          this is a matching failure.

   Each  conversion  specification  in  format  begins  with  either   the
   character  '%'  or  the  character  sequence  "%n$"  (see below for the
   distinction) followed by:

   ·      An optional '*' assignment-suppression character: scanf()  reads
          input  as directed by the conversion specification, but discards
          the input.  No corresponding pointer argument is  required,  and
          this  specification  is  not included in the count of successful
          assignments returned by scanf().

   ·      An optional 'm' character.  This is used with string conversions
          (%s,  %c, %[), and relieves the caller of the need to allocate a
          corresponding  buffer  to  hold  the  input:  instead,   scanf()
          allocates  a  buffer of sufficient size, and assigns the address
          of this buffer to  the  corresponding  pointer  argument,  which
          should be a pointer to a char * variable (this variable does not
          need to be initialized before  the  call).   The  caller  should
          subsequently free(3) this buffer when it is no longer required.

   ·      An  optional  decimal  integer which specifies the maximum field
          width.  Reading of characters stops either when this maximum  is
          reached  or  when  a  nonmatching  character is found, whichever
          happens first.  Most conversions  discard  initial  white  space
          characters (the exceptions are noted below), and these discarded
          characters don't count toward the maximum field  width.   String
          input  conversions  store a terminating null byte ('\0') to mark
          the end of the input; the maximum field width does  not  include
          this terminator.

   ·      An  optional  type  modifier character.  For example, the l type
          modifier is used with integer conversions such as %d to  specify
          that  the  corresponding  pointer  argument refers to a long int
          rather than a pointer to an int.

   ·      A  conversion  specifier  that  specifies  the  type  of   input
          conversion to be performed.

   The  conversion  specifications  in  format  are  of  two forms, either
   beginning with '%' or beginning with "%n$".  The two forms  should  not
   be  mixed  in  the  same format string, except that a string containing
   "%n$" specifications can include %% and %*.   If  format  contains  '%'
   specifications,  then these correspond in order with successive pointer
   arguments.  In the "%n$" form (which is specified in POSIX.1-2001,  but
   not  C99),  n  is  a  decimal integer that specifies that the converted
   input should be placed in the location referred to by the n-th  pointer
   argument following format.

   The  following  type  modifier  characters  can  appear in a conversion

   h      Indicates that the conversion will be one of d, i, o, u,  x,  X,
          or  n  and  the  next  pointer  is  a  pointer to a short int or
          unsigned short int (rather than int).

   hh     As for h, but the next pointer is a pointer to a signed char  or
          unsigned char.

   j      As  for h, but the next pointer is a pointer to an intmax_t or a
          uintmax_t.  This modifier was introduced in C99.

   l      Indicates either that the conversion will be one of d, i, o,  u,
          x,  X,  or  n and the next pointer is a pointer to a long int or
          unsigned long int (rather than int), or that the conversion will
          be one of e, f, or g and the next pointer is a pointer to double
          (rather than float).  Specifying two l characters is  equivalent
          to  L.   If  used  with %c or %s, the corresponding parameter is
          considered as a pointer to a wide  character  or  wide-character
          string respectively.

   L      Indicates  that the conversion will be either e, f, or g and the
          next pointer is a pointer to long double or the conversion  will
          be  d,  i,  o, u, or x and the next pointer is a pointer to long

   q      equivalent to L.  This specifier does not exist in ANSI C.

   t      As for h, but the next pointer is  a  pointer  to  a  ptrdiff_t.
          This modifier was introduced in C99.

   z      As  for  h, but the next pointer is a pointer to a size_t.  This
          modifier was introduced in C99.

   The following conversion specifiers are available:

   %      Matches a literal '%'.  That is, %% in the format string matches
          a  single  input  '%'  character.   No  conversion  is done (but
          initial white space characters are  discarded),  and  assignment
          does not occur.

   d      Matches  an  optionally signed decimal integer; the next pointer
          must be a pointer to int.

   D      Equivalent to ld; this exists only for  backward  compatibility.
          (Note:  thus  only  in  libc4.   In  libc5  and  glibc the %D is
          silently ignored, causing old programs to fail mysteriously.)

   i      Matches an optionally signed integer; the next pointer must be a
          pointer  to  int.   The  integer is read in base 16 if it begins
          with 0x or 0X, in base 8 if it begins with 0,  and  in  base  10
          otherwise.   Only  characters  that  correspond  to the base are

   o      Matches an unsigned octal integer; the next pointer  must  be  a
          pointer to unsigned int.

   u      Matches  an unsigned decimal integer; the next pointer must be a
          pointer to unsigned int.

   x      Matches an unsigned hexadecimal integer; the next  pointer  must
          be a pointer to unsigned int.

   X      Equivalent to x.

   f      Matches  an  optionally  signed  floating-point number; the next
          pointer must be a pointer to float.

   e      Equivalent to f.

   g      Equivalent to f.

   E      Equivalent to f.

   a      (C99) Equivalent to f.

   s      Matches a  sequence  of  non-white-space  characters;  the  next
          pointer  must be a pointer to the initial element of a character
          array that is long enough to hold the  input  sequence  and  the
          terminating null byte ('\0'), which is added automatically.  The
          input string stops at white space or at the maximum field width,
          whichever occurs first.

   c      Matches  a  sequence  of characters whose length is specified by
          the maximum field width (default 1); the next pointer must be  a
          pointer  to  char,  and  there  must  be enough room for all the
          characters (no terminating null byte is added).  The usual  skip
          of  leading  white  space  is  suppressed.   To skip white space
          first, use an explicit space in the format.

   [      Matches a nonempty sequence of characters from the specified set
          of  accepted  characters;  the next pointer must be a pointer to
          char, and there must be enough room for all  the  characters  in
          the  string,  plus  a  terminating null byte.  The usual skip of
          leading white space is suppressed.  The string is to be made  up
          of  characters  in  (or  not  in)  a  particular set; the set is
          defined by the characters between the open bracket  [  character
          and  a  close  bracket  ]  character.   The  set  excludes those
          characters if the first character after the open  bracket  is  a
          circumflex  (^).  To include a close bracket in the set, make it
          the first character after the open bracket  or  the  circumflex;
          any  other position will end the set.  The hyphen character - is
          also special; when placed between two other characters, it  adds
          all  intervening  characters  to  the set.  To include a hyphen,
          make it the last character before the final close bracket.   For
          instance,  [^]0-9-]  means  the  set  "everything  except  close
          bracket, zero through nine, and hyphen".  The string  ends  with
          the appearance of a character not in the (or, with a circumflex,
          in) set or when the field width runs out.

   p      Matches a pointer value (as printed by %p in printf(3); the next
          pointer must be a pointer to a pointer to void.

   n      Nothing  is expected; instead, the number of characters consumed
          thus far from the input is  stored  through  the  next  pointer,
          which  must  be  a pointer to int.  This is not a conversion and
          does not increase the  count  returned  by  the  function.   The
          assignment  can  be suppressed with the * assignment-suppression
          character, but the effect on  the  return  value  is  undefined.
          Therefore %*n conversions should not be used.


   On   success,   these  functions  return  the  number  of  input  items
   successfully matched and assigned; this can be fewer than provided for,
   or even zero, in the event of an early matching failure.

   The  value EOF is returned if the end of input is reached before either
   the first successful conversion or a matching failure occurs.   EOF  is
   also returned if a read error occurs, in which case the error indicator
   for the stream (see ferror(3)) is set, and errno is set to indicate the


   EAGAIN The file descriptor underlying stream is marked nonblocking, and
          the read operation would block.

   EBADF  The file descriptor underlying stream is invalid,  or  not  open
          for reading.

   EILSEQ Input byte sequence does not form a valid character.

   EINTR  The read operation was interrupted by a signal; see signal(7).

   EINVAL Not enough arguments; or format is NULL.

   ENOMEM Out of memory.

   ERANGE The  result  of an integer conversion would exceed the size that
          can be stored in the corresponding integer type.


   For  an  explanation  of  the  terms  used   in   this   section,   see

   │InterfaceAttributeValue          │
   │scanf(), fscanf(),   │ Thread safety │ MT-Safe locale │
   │sscanf(), vscanf(),  │               │                │
   │vsscanf(), vfscanf() │               │                │


   The  functions  fscanf(),  scanf(), and sscanf() conform to C89 and C99
   and POSIX.1-2001.  These standards do not specify the ERANGE error.

   The q specifier is the 4.4BSD notation for long long, while ll  or  the
   usage of L in integer conversions is the GNU notation.

   The Linux version of these functions is based on the GNU libio library.
   Take a look at the info documentation of GNU libc  (glibc-1.08)  for  a
   more concise description.


   The 'a' assignment-allocation modifier
   Originally,  the  GNU C library supported dynamic allocation for string
   inputs (as a nonstandard extension) via the a character.  (This feature
   is  present  at least as far back as glibc 2.0.)  Thus, one could write
   the following to have scanf() allocate a buffer for  an  input  string,
   with a pointer to that buffer being returned in *buf:

       char *buf;
       scanf("%as", &buf);

   The  use  of  the letter a for this purpose was problematic, since a is
   also specified by the ISO C standard as a synonym for f (floating-point
   input).   POSIX.1-2008  instead specifies the m modifier for assignment
   allocation (as documented in DESCRIPTION, above).

   Note that the a modifier is not available if the  program  is  compiled
   with  gcc  -std=c99 or gcc -D_ISOC99_SOURCE (unless _GNU_SOURCE is also
   specified), in which case the a  is  interpreted  as  a  specifier  for
   floating-point numbers (see above).

   Support  for  the  m  modifier was added to glibc starting with version
   2.7, and new programs should use that modifier instead of a.

   As well as  being  standardized  by  POSIX,  the  m  modifier  has  the
   following further advantages over the use of a:

   * It may also be applied to %c conversion specifiers (e.g., %3mc).

   * It  avoids ambiguity with respect to the %a floating-point conversion
     specifier (and is unaffected by gcc -std=c99 etc.).


   All functions are fully C89  conformant,  but  provide  the  additional
   specifiers  q  and  a  as well as an additional behavior of the L and l
   specifiers.  The latter may be considered to be a bug,  as  it  changes
   the behavior of specifiers defined in C89.

   Some  combinations  of  the  type  modifiers  and conversion specifiers
   defined by ANSI C do not make sense (e.g., %Ld).  While they may have a
   well-defined  behavior  on  Linux,  this  need  not  to  be so on other
   architectures.  Therefore it usually is better to  use  modifiers  that
   are  not  defined  by  ANSI  C  at  all, that is, use q instead of L in
   combination with d, i, o, u, x, and X conversions or ll.

   The usage of q is not the same as on 4.4BSD, as it may be used in float
   conversions equivalently to L.


   To  use  the  dynamic  allocation  conversion specifier, specify m as a
   length modifier (thus %ms or %m[range]).  The caller must  free(3)  the
   returned string, as in the following example:

       char *p;
       int n;

       errno = 0;
       n = scanf("%m[a-z]", &p);
       if (n == 1) {
           printf("read: %s\n", p);
       } else if (errno != 0) {
       } else {
           fprintf(stderr, "No matching characters\n");

   As  shown in the above example, it is necessary to call free(3) only if
   the scanf() call successfully read a string.


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


   This page is part of release 4.09 of the Linux  man-pages  project.   A
   description  of  the project, information about reporting bugs, and the
   latest    version    of    this    page,    can     be     found     at

More Linux Commands

pcre_get_stringtable_entries(3) - Perl-compatible regular ex
This convenience function finds, for a compiled pattern, the first and last entries for a given name in the table that translates capturing parenthesis names in

key_defined(3ncurses) - check if a keycode is defined.......
This is an extension to the curses library. It permits an application to determine if a string is currently bound to any keycode. RETURN VALUE If the string is

strcspn(3) - search a string for a set of characters........
The strspn() function calculates the length (in bytes) of the initial segment of s which consists entirely of bytes in accept. The strcspn() function calculates

XChangeFeedbackControl(3) - query and change input device fe
These requests are provided to manipulate those input devices that support feedbacks. A BadMatch error will be generated if the requested device does not suppor

fdformat(8) - low-level format a floppy disk (Man Page).....
fdformat does a low-level format on a floppy disk. device is usually one of the following (for floppy devices the major = 2, and the minor is shown for informat

perlinterp(1) - An overview of the Perl interpreter.........
This document provides an overview of how the Perl interpreter works at the level of C code, along with pointers to the relevant C source code files. ELEMENTS O

iso-8859-1(7) - ISO 8859-1 character set encoded in octal, d
iso-8859-1.7 - The ISO 8859 standard includes several 8-bit extensions to the ASCII character set (also known as ISO 646-IRV). Especially important is ISO 8859-

newslog(5) - Description of INN log files - Linux man page
Most log files created by Usenet programs reside in the pathlog directory set in inn.conf and have a .log extension. Several versions are usually kept with an a

RootWindowOfScreen(3) - screen information functions and mac
The BlackPixelOfScreen macro returns the black pixel value of the specified screen. The WhitePixelOfScreen macro returns the white pixel value of the specified

glPolygonMode(3gl) - select a polygon rasterization mode....
glPolygonMode controls the interpretation of polygons for rasterization. face describes which polygons mode applies to: front-facing polygons (GL_FRONT), back-f

gnutls_x509_crl_get_extension_info(3) - API function........
This function will return the requested extension OID in the CRL, and the critical flag for it. The extension OID will be stored as a string in the provided buf

ip2cc(1) - lookup country from IP address or hostname.......
Ip2cc is a program to lookup countries of IP addresses. Ip2cc has two modes: interactive and non-interactive. Interactive mode allows the user to query more tha

We can't live, work or learn in freedom unless the software we use is free.