Seth Woolley's Man Viewer

scanf(3) - fscanf, scanf, sscanf, vfscanf, vscanf, vsscanf, fscanf, scanf, sscanf, vfscanf, vscanf, vsscanf - input format conversion - man 3 scanf

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

SCANF(3)                   Linux Programmer's Manual                  SCANF(3)



NAME
       scanf,  fscanf, sscanf, vscanf, vsscanf, vfscanf - input format conver-
       sion

SYNOPSIS
       #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);

DESCRIPTION
       The scanf family of functions scans input  according  to  a  format  as
       described  below.   This  format may contain conversion specifiers; the
       results from such conversions, if(3,n) any, are stored through  the  pointer
       arguments.   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(3,n) 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(3,n);  these  are  analogous  to  the  vprintf and vsprintf functions
       respectively.

       Each successive pointer argument must  correspond  properly  with  each
       successive  conversion  specifier  (but  see `suppression' below).  All
       conversions are introduced by the % (percent sign) character.  The for-
       mat  string(3,n)  may  also  contain other characters.  White space (such as
       blanks, tabs, or newlines) in(1,8) the format string(3,n)  match  any  amount  of
       white  space,  including  none,  in(1,8) the input.  Everything else matches
       only itself.  Scanning stops when an input  character  does  not  match
       such  a format character.  Scanning also stops when an input conversion
       cannot be made (see below).

CONVERSIONS
       Following the % character introducing a conversion there may be a  num-
       ber of flag characters, as follows:

       *      Suppresses  assignment.   The  conversion that follows occurs as
              usual, but no pointer is used; the result of the  conversion  is
              simply discarded.

       a      (glibc) Indicates that the conversion will be s, the needed mem-
              ory space for the string(3,n) will be malloc'ed  and the  pointer  to
              it will be assigned to the char pointer variable, which does not
              have to be initialized before.  This flag does not exist in(1,8) ANSI
              C (C89) and has a different meaning in(1,8) C99.

       a      (C99) Equivalent to f.

       h      Indicates  that the conversion will be one of dioux or n and the
              next pointer is a pointer to a short int (rather than int).

       l      Indicates either that the conversion will be one of dioux  or  n
              and  the  next  pointer  is a pointer to a long int (rather than
              int), or that the conversion will be one of  efg  and  the  next
              pointer  is a pointer to double (rather than float).  Specifying
              two l flags is equivalent to the L flag.

       L      Indicates that the conversion will be either efg  and  the  next
              pointer  is  a  pointer to long double or the conversion will be
              dioux and the next pointer is a pointer  to  long  long.   (Note
              that  long  long  is  not an ANSI C type. Any program using this
              will not be portable to all architectures).

       q      equivalent to L.  This flag does not exist in(1,8) ANSI C.

       In addition to these flags, there may  be  an  optional  maximum  field
       width,  expressed  as  a decimal integer, between the % and the conver-
       sion.  If no width is given, a default of `infinity' is used (with  one
       exception,  below);  otherwise at most this many characters are scanned
       in(1,8) processing the conversion.  Before conversion begins,  most  conver-
       sions  skip  white  space;  this white space is not counted against the
       field width.

       The following conversions are available:

       %      Matches a literal `%'.  That  is,  `%%'  in(1,8)  the  format  string(3,n)
              matches  a  single  input `%' character.  No conversion is done,
              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(1,8); this exists only for backwards compatibility.
              (Note: thus only in(1,8) 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(2,n,1 builtins) in(1,8) base  16  if(3,n)  it  begins
              with  `0x' or `0X', in(1,8) base 8 if(3,n) it begins with `0', and in(1,8) base
              10 otherwise.  Only characters that correspond to the  base  are
              used.

       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.

       s      Matches  a  sequence  of  non-white-space  characters;  the next
              pointer must be a pointer to char, and the array must  be  large
              enough  to accept(2,8) all the sequence and the terminating NUL char-
              acter.  The input string(3,n) stops at white space or at the  maximum
              field width, whichever occurs first.

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

       [      Matches a nonempty sequence of characters from the specified set(7,n,1 builtins)
              of accepted characters; the next pointer must be  a  pointer  to
              char,  and  there  must be enough room for all the characters in(1,8)
              the string(3,n), plus a terminating NUL character.  The usual skip of
              leading  white space is suppressed.  The string(3,n) is to be made up
              of characters in(1,8) (or not  in(1,8))  a  particular  set(7,n,1 builtins);  the  set(7,n,1 builtins)  is
              defined  by  the characters between the open(2,3,n) bracket [ character
              and a close(2,7,n) bracket ] character.  The set(7,n,1 builtins) excludes those charac-
              ters  if(3,n) the first character after the open(2,3,n) bracket is a circum-
              flex ^.  To include a close(2,7,n) bracket in(1,8)  the  set(7,n,1 builtins),  make  it  the
              first  character  after  the open(2,3,n) 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(2,7,n)  bracket.   For
              instance, `[^]0-9-]' means  the  set(7,n,1 builtins)  `everything  except  close(2,7,n)
              bracket,  zero  through nine, and hyphen'.  The string(3,n) ends with
              the appearance of a character not in(1,8) the (or, with a circumflex,
              in(1,8)) set(7,n,1 builtins) or when the field width runs out.

       p      Matches  a  pointer  value (as printed by `%p' in(1,8) printf(1,3,1 builtins)(3); the
              next pointer must be 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,
              although  it  can be suppressed with the * flag.  The C standard
              says: `Execution of  a  %n  directive  does  not  increment  the
              assignment  count  returned  at the completion of execution' but
              the Corrigendum seems to contradict this. Probably  it  is  wise
              not  to  make any assumptions on the effect of %n conversions on
              the return value.



RETURN VALUE
       These functions return the number of input items assigned, which can be
       fewer than provided for, or even zero, in(1,8) the event of a matching fail-
       ure.  Zero indicates that, while there was input available, no  conver-
       sions  were assigned; typically this is due to an invalid input charac-
       ter, such as an alphabetic character for a `%d' conversion.  The  value
       EOF  is  returned if(3,n) an input failure occurs before any conversion such
       as an end-of-file occurs. If an error(8,n) or end-of-file occurs after  con-
       version(1,3,5)  has  begun,  the number of conversions which were successfully
       completed is returned.

SEE ALSO
       getc(3), printf(1,3,1 builtins)(3), strtod(3), strtol(3), strtoul(3)

CONFORMING TO
       The functions fscanf, scanf, and sscanf  conform  to  ANSI  X3.159-1989
       (``ANSI C'').

       The q flag is the BSD 4.4 notation for long long, while ll or the usage
       of L in(1,8) integer conversions is the GNU notation.

       The Linux version(1,3,5) of these functions is based on the GNU libio library.
       Take  a  look(1,8,3 Search::Dict)  at the info(1,5,n) documentation of GNU libc (glibc-1.08) for a
       more concise description.

BUGS
       All functions are fully ANSI X3.159-1989 conformant,  but  provide  the
       additional  flags  q  and a as well as an additional behaviour of the L
       and l flags. The latter may be considered to be a bug,  as  it  changes
       the behaviour of flags defined in(1,8) ANSI X3.159-1989.

       Some  combinations  of  flags defined by ANSI C are not making sense in(1,8)
       ANSI C (e.g.  %Ld).  While they may have a  well-defined  behaviour  on
       Linux, this need not to be so on other architectures. Therefore it usu-
       ally is better to use flags that are not defined by ANSI C at all, i.e.
       use q instead of L in(1,8) combination with diouxX conversions or ll.

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



LINUX MANPAGE                     1995-11-01                          SCANF(3)

References for this manual (incoming links)