scanf() -- STDIO Function (libc)

Accept and format input
#include <stdio.h>
int scanf(format, arg1, ... argN)
char *format; [data type] *arg1, ... *argN;

scanf() reads the  standard input, and uses the string  format to specify a
format for each arg1 through argN, each of which must be a pointer.

scanf() reads  one character at a time from  format; white space characters
are  ignored.  The  percent sign  character  `%' marks  the beginning  of a
conversion specification.  `%'  may be followed by characters that indicate
the width of the input field and the type of conversion to be done.

scanf()  reads  the  standard  input  until  the  return  key  is  pressed.
Inappropriate characters are thrown away; e.g., it will not try to write an
alphabetic character into an int.

scanf()  returns the  number of  arguments  filled.  It  returns EOF  if no
arguments can be filled or if an error occurs.

Modifiers

The following modifiers can be used within the conversion string:

1. An asterisk `*', which tells scanf to skip the next conversion; that is,
   read the next token but do not write it into the corresponding argument.

2. A decimal integer, which tells scanf the maximum width of the next field
   being  read.   How  the field  width  is  used  varies among  conversion
   specifier.  See the table of specifiers below for more information.

3. One of the three modifiers h, l, or L, whose use is described below.

Modifiers

The following three modifiers may be used before a conversion specifier:

h    When used  before the conversion  specifiers d, i,  o, u, x,  or X, it
     specifies that the corresponding argument  points to a short int or an
     unsigned  short  int.   When used  before  n,  it  indicates that  the
     corresponding  argument points  to  a short  int.  In  implementations
     where short int and int are synonymous, it is not needed.  However, it
     is useful in writing portable code.

l    When  used before  the conversion  specifiers  e, E,  f, F,  or G,  it
     indicates that  the corresponding argument  points to a  double rather
     than a float.

L    When  used before  the conversion  specifiers  e, E,  f, F,  or G,  it
     indicates  that the  corresponding argument  points  to a  long double
     rather than a float.

Conversion Specifiers

scanf() recognizes the following conversion specifiers:

c  Assign the next input character to the next arg, which should be of type
   char *.   The field width  specifies the number  of characters (default,
   one).  scanf() does  not write a null character at  the end of the array
   it creates.  This specifier forces scanf() to read and store white-space
   characters and numerals, as well as letters.

d  Convert the token to a decimal integer.  The format should be equivalent
   to that expected  by the function strtol() with a  base argument of ten.
   The corresponding argument should point to an int.

D  Assign the  decimal integer from the  next input field to  the next arg,
   which should be of type long *.

e  Convert the  token to a floating-point number.  The  format of the token
   should be  that expected by  the function strtod()  for a floating-point
   number  that  uses  exponential  notation.  The  corresponding  argument
   should point to a float if  no modifiers are present, to a double if the
   l modifier is present, or to a long double if the L modifier is present.

E  Same as  e. Prior to release 4.2 of  COHERENT, this conversion specifier
   converted the token to a double. This change has been made to conform to
   the ANSI Standard, and may require that some code be rewritten.

f  Convert the  token to a floating-point number.  The  format of the token
   should be  that expected by  the function strtod()  for a floating-point
   number that  uses decimal  notation.  The corresponding  argument should
   point to a double.

g  Convert the  token to a floating-point number.  The  format of the token
   should of  that expected by  the function strtod()  for a floating-point
   number that  uses either exponential notation  or decimal notation.  The
   corresponding  argument should  point  to a  float if  no modifiers  are
   present, to a  double if the l modifier is  present, or to a long double
   if the L modifier is present.

G  Same as g.

i  Convert the token to a decimal integer.  The format should be equivalent
   to that expected by the function  strtol() with a base argument of zero.
   The corresponding argument should point to an int.

n  Do not read any text.   Write into the corresponding argument the number
   of characters that scanf() has read up to this point.  The corresponding
   argument should point to an int.

o  Assign the  octal integer  from the  next input field  to the  next arg,
   which should be of type int *.

O  Assign the  octal integer  from the  next input field  to the  next arg,
   which should be of type long *.

p  The  ANSI  standard  states  that  the  behavior of  the  %p  conversion
   specificer  is implementation-specific.  Under  COHERENT, %p  converts a
   strings of digits in hexadecimal notation into an address.  For example,
   in the code

       char buf[] = "0x7FFFFDBC";
       char *foo;
       ...
       sscanf(buf, "%p", &foo);

   the  %p specifier  reads the  contents  of buf  and turns  them into  an
   address, which it then uses to  initialize the pointer foo.  You can use
   the %p specifier  to turn back into an address  the output of printf()'s
   %p specifier.   Please note that abuse of this  specifier can create all
   manner of fascinating bugs within your programs: Caveat utilitor.

r  The next argument  points to an array of new  arguments that may be used
   recursively.  The first argument of the list is a char * that contains a
   new format  string.  When the  list is exhausted,  the routine continues
   from where it left off in the original format string.

s  Assign  the string  from the  next input  field to  the next  arg, which
   should be of  type char *.  The array to  which the char * points should
   be long enough to accept the string and a terminating null character.

u  Convert  the  token  to  an  unsigned  integer.  The  format  should  be
   equivalent  to  that expected  by  the function  strtoul()  with a  base
   argument of  ten.  See strtoul for  more information.  The corresponding
   argument should point to an unsigned int.

x  Convert the  token from hexadecimal  notation to a  signed integer.  The
   format should be equivalent to that expected by the function strtol with
   a base  argument of  16.  See  the Lexicon entry  for strtol()  for more
   information.   The corresponding  argument should  point to  an unsigned
   int.

X  Same as  x. Prior to  release 4.2 of  COHERENT, X meant the  same as the
   current lx; that is, the corresponding argument points to a long instead
   of an  int. This has been  changed to conform to  the ANSI Standard, and
   may require that some code be rewritten.

It is  important to remember  that scanf() reads  up, but not  through, the
newline  character: the  newline  remains in  the  standard input  device's
buffer until  you dispose  of it somehow.   Programmers have been  known to
forget  to empty  the buffer  before calling scanf()  a second  time, which
leads to unexpected results.

Example

The following example uses scanf() in a brief dialogue with the user.

#include <stdio.h>

main()
{
    int left, right;

    printf("No. of fingers on your left hand:  ");
    /* force message to appear on screen */
    fflush(stdout);
    scanf("%d", &left);

    /* eat newline char */
    while(getchar() != '\n')
        ;

    printf("No. of fingers on your right hand:  ");
    fflush(stdout);
    scanf("%d", &right);

    /* again, eat newline */
    while(getchar() != '\n')
        ;

    printf("You've %d left fingers, %d right, & %d total\n",
        left, right, left+right);
}

See Also

fscanf(),
libc,
sscanf()
ANSI Standard, §7.9.6.4
POSIX Standard, §8.1

Notes

Because C does not perform type  checking, it is essential that an argument
match its specification.  For that  reason, scanf() is best used to process
only data that you are certain are in the correct data format.  Rather than
use scanf() to obtain a string from the keyboard: we recommend that you use
gets() to obtain the string, and use strtok() or sscanf() to parse it.

© 2012 by Stephen A. Ness