ssccaannff() -- STDIO Function (libc)

Accept and format input
#iinncclluuddee <ssttddiioo.hh>
iinntt ssccaannff(_f_o_r_m_a_t, _a_r_g_1, ... _a_r_g_N)
cchhaarr *_f_o_r_m_a_t; [ddaattaa ttyyppee] *_a_r_g_1, ... *_a_r_g_N;

ssccaannff() reads the  standard input, and uses the string  _f_o_r_m_a_t to specify a
format for each _a_r_g_1 through _a_r_g_N, each of which must be a pointer.

ssccaannff() reads  one character at a time from  _f_o_r_m_a_t; 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.

ssccaannff()  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 iinntt.

The following modifiers can be used within the conversion string:

11. An asterisk `*', which tells ssccaannff to skip the next conversion; that is,
   read the next token but do not write it into the corresponding argument.

22. A decimal integer, which tells ssccaannff 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3. One of the three modifiers hh, ll, or LL, whose use is described below.

_M_o_d_i_f_i_e_r_s
The following three modifiers may be used before a conversion specifier:

hh    When used  before the conversion  specifiers dd, ii,  oo, uu, xx,  or XX, it
     specifies that the corresponding argument  points to a sshhoorrtt iinntt or an
     uunnssiiggnneedd  sshhoorrtt  iinntt.   When used  before  nn,  it  indicates that  the
     corresponding  argument points  to  a sshhoorrtt  iinntt.  In  implementations
     where sshhoorrtt iinntt and iinntt are synonymous, it is not needed.  However, it
     is useful in writing portable code.

ll    When  used before  the conversion  specifiers  ee, EE,  ff, FF,  or GG,  it
     indicates that  the corresponding argument  points to a  ddoouubbllee rather
     than a ffllooaatt.

LL    When  used before  the conversion  specifiers  ee, EE,  ff, FF,  or GG,  it
     indicates  that the  corresponding argument  points  to a  lloonngg ddoouubbllee
     rather than a ffllooaatt.

_C_o_n_v_e_r_s_i_o_n _S_p_e_c_i_f_i_e_r_s
ssccaannff() recognizes the following conversion specifiers:

cc  Assign the next input character to the next _a_r_g, which should be of type
   cchhaarr *.   The field width  specifies the number  of characters (default,
   one).  ssccaannff() does  not write a null character at  the end of the array
   it creates.  This specifier forces ssccaannff() to read and store white-space
   characters and numerals, as well as letters.

dd  Convert the token to a decimal integer.  The format should be equivalent
   to that expected  by the function ssttrrttooll() with a  base argument of ten.
   The corresponding argument should point to an iinntt.

DD  Assign the  decimal integer from the  next input field to  the next _a_r_g,
   which should be of type lloonngg *.

ee  Convert the  token to a floating-point number.  The  format of the token
   should be  that expected by  the function ssttrrttoodd()  for a floating-point
   number  that  uses  exponential  notation.  The  corresponding  argument
   should point to a ffllooaatt if  no modifiers are present, to a ddoouubbllee if the
   ll modifier is present, or to a lloonngg ddoouubbllee if the LL modifier is present.

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

ff  Convert the  token to a floating-point number.  The  format of the token
   should be  that expected by  the function ssttrrttoodd()  for a floating-point
   number that  uses decimal  notation.  The corresponding  argument should
   point to a ddoouubbllee.

gg  Convert the  token to a floating-point number.  The  format of the token
   should of  that expected by  the function ssttrrttoodd()  for a floating-point
   number that  uses either exponential notation  or decimal notation.  The
   corresponding  argument should  point  to a  ffllooaatt if  no modifiers  are
   present, to a  ddoouubbllee if the ll modifier is  present, or to a lloonngg ddoouubbllee
   if the LL modifier is present.

GG  Same as gg.

ii  Convert the token to a decimal integer.  The format should be equivalent
   to that expected by the function  ssttrrttooll() with a base argument of zero.
   The corresponding argument should point to an iinntt.

nn  Do not read any text.   Write into the corresponding argument the number
   of characters that ssccaannff() has read up to this point.  The corresponding
   argument should point to an iinntt.

oo  Assign the  octal integer  from the  next input field  to the  next _a_r_g,
   which should be of type iinntt *.

OO  Assign the  octal integer  from the  next input field  to the  next _a_r_g,
   which should be of type lloonngg *.

pp  The  ANSI  standard  states  that  the  behavior of  the  %pp  conversion
   specificer  is implementation-specific.  Under  COHERENT, %p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p specifier  reads the  contents  of bbuuff  and turns  them into  an
   address, which it then uses to  initialize the pointer ffoooo.  You can use
   the %pp specifier  to turn back into an address  the output of pprriinnttff()'s
   %pp specifier.   Please note that abuse of this  specifier can create all
   manner of fascinating bugs within your programs: _C_a_v_e_a_t _u_t_i_l_i_t_o_r.

rr  The next argument  points to an array of new  arguments that may be used
   recursively.  The first argument of the list is a cchhaarr * 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s  Assign  the string  from the  next input  field to  the next  _a_r_g, which
   should be of  type cchhaarr *.  The array to  which the cchhaarr * points should
   be long enough to accept the string and a terminating null character.

uu  Convert  the  token  to  an  unsigned  integer.  The  format  should  be
   equivalent  to  that expected  by  the function  ssttrrttoouull()  with a  base
   argument of  ten.  See ssttrrttoouull for  more information.  The corresponding
   argument should point to an uunnssiiggnneedd iinntt.

xx  Convert the  token from hexadecimal  notation to a  signed integer.  The
   format should be equivalent to that expected by the function ssttrrttooll with
   a base  argument of  16.  See  the Lexicon entry  for ssttrrttooll()  for more
   information.   The corresponding  argument should  point to  an uunnssiiggnneedd
   iinntt.

XX  Same as  xx. Prior to  release 4.2 of  COHERENT, XX meant the  same as the
   current llxx; that is, the corresponding argument points to a lloonngg instead
   of an  iinntt. This has been  changed to conform to  the ANSI Standard, and
   may require that some code be rewritten.

It is  important to remember  that ssccaannff() 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 ssccaannff()  a second  time, which
leads to unexpected results.

_E_x_a_m_p_l_e
The following example uses ssccaannff() 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);
}

_S_e_e _A_l_s_o
ffssccaannff(), lliibbcc, ssssccaannff()
ANSI Standard, section 7.9.6.4
POSIX Standard, section 8.1

_D_i_a_g_n_o_s_t_i_c_s
ssccaannff()  returns the  number of  arguments  filled.  It  returns EOF  if no
arguments can be filled or if an error occurs.

_N_o_t_e_s
Because C does not perform type  checking, it is essential that an argument
match its specification.  For that  reason, ssccaannff() is best used to process
only data that you are certain are in the correct data format.  Rather than
use ssccaannff() to obtain a string from the keyboard: we recommend that you use
ggeettss() to obtain the string, and use ssttrrttookk() or ssssccaannff() to parse it.
