SCANF(3)                       Library Routines                       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 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 pointed to by str.  The vfscanf func-
       tion 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 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 may also contain other characters.   White  space  (such  as
       blanks,  tabs,  or  newlines)  in the format string match any amount of
       white space, including none, in 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.

              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).

              L      Indicates that the conversion will be efg  and  the  next
                     pointer  is  a pointer to long double.  (This type is not
                     implemented; the L flag is currently ignored.)

       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 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  the  format
                     string  matches a single input '%' character.  No conver-
                     sion 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; this exists only for backwards compati-
                     bility.

              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 corre-
                     spond to the base are used.

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

              O      Equivalent  to  lo; this exists for backwards compatibil-
                     ity.

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

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

              X      Equivalent to lx; this violates the ANSI/C standard,  but
                     is backwards compatible with previous UNIX systems.

              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 lf; this violates the ANSI/C standard,  but
                     is backwards compatible with previous UNIX systems.

              F      Equivalent to lf; this exists only for backwards compati-
                     bility.

              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 all the sequence  and  the
                     terminating  NUL  character.   The  input string 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 the format.

              [      Matches a nonempty sequence of characters from the speci-
                     fied 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 NUL
                     character.  The usual skip of leading white space is sup-
                     pressed.   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  char-
                     acters 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 char-
                     acter 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 circum-
                     flex, 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 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.

       For  backwards  compatibility,  other conversion characters (except \0)
       are taken as if they were %d or, if uppercase, %ld, and a  'conversion'
       of %\0 causes an immediate return of EOF.  The F and X conversions will
       be changed in the future to conform to the ANSI/C standard, after which
       they will act like f and x respectively.



RETURN VALUES

       These functions return the number of input items assigned, which can be
       fewer than provided for, or even zero, in 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 an input failure occurs before any conver-
       sion such as an end-of-file occurs. If an error or  end-of-file  occurs
       after  conversion  has begun, the number of conversions which were suc-
       cessfully completed is returned.


SEE ALSO

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


STANDARDS

       The functions fscanf, scanf, and sscanf conform to ANSI/C.


HISTORY

       The functions vscanf, vsscanf and vfscanf are new to this release.


BUGS

       The ORCA/C stdio implementation also provides a  %b  format  specifier,
       for Pascal-type strings.  This is not currently implemented.

       The current situation with %F and %X conversions is unfortunate.

       All  of  the  backwards  compatibility  formats  will be removed in the
       future.

       Numerical strings are truncated to 512 characters; for example, %f  and
       %d are implicitly %512f and %512d.



GNO                            15 September 1997                      SCANF(3)

Man(1) output converted with man2html