fscanf(), scanf(), sscanf() — Read and format data

The format string pointed to by format-string can contain one or more of the following:

• White space characters, as specified by isspace(), such as blanks and newline characters. A white space character causes fscanf(), scanf(), and sscanf() to read, but not to store, all consecutive white space characters in the input up to the next character that is not white space. One white space character in format-string matches any combination of white space characters in the input.
• Characters that are not white space, except for the percent sign character (%). A non-white space character causes fscanf(), scanf(), and sscanf() to read, but not to store, a matching non-white space character. If the next character in the input stream does not match, the function ends.
• Conversion specifications which are introduced by the percent sign (%) or the sequence (%n$) where n is a decimal integer in the range [1,NL_ARGMAX]. A conversion specification causes fscanf(), scanf(), and sscanf() to read and convert characters in the input into values of a conversion specifier. The value is assigned to an argument in the argument list.

An input field is defined as:

• All characters until a white space character (space, tab, or newline) is encountered
• All characters until a character is encountered that cannot be converted according to the conversion specification
• All characters until the field width is reached.

Syntax of Conversion Specification for fscanf(), scanf(), and sscanf()

>>-%--+---+--+-------+--+----+--conversion specifier-----------><
      '-*-'  '-width-'  +-h--+                         
                        +-hh-+                         
                        +-l--+                         
                        +-ll-+                         
                        +-j--+                         
                        +-t--+                         
                        +-z--+                         
                        +-D--+                         
                        +-DD-+                         
                        +-H--+                         
                        '-L--'                         

Optional prefix: The optional prefix characters used to indicate the size of the argument expected are explained:

Prefix

Meaning

h

Specifies that the d, i, o, u, x, X, or n conversion specifier applies to an argument with type pointer to short or unsigned short.

hh

Specifies that the d, i, o, u, x, X, or n conversion specifier applies to an argument with type pointer to signed char or unsigned char.

l

(ell) Specifies that the d, i, o, u, x, X, or n conversion specifier applies to an argument with type pointer to long or unsigned long; the following a, A, e, E, f, F, g, or G conversion specifier applies to an argument with type pointer to double; and the following c, s, or [ conversion specifier applies to an argument with type pointer to wchar_t.

ll

(ell-ell) Specifies that the d, i, o, u, x, X, or n conversion specifier applies to an argument with type pointer to long long or unsigned long long.

j

Specifies that the d, i, o, u, x, X, or n conversion specifier applies to an argument with type pointer to intmax_t or uintmax_t.

t

Specifies that the d, i, o, u, x, X, or n conversion specifier applies to an argument with type pointer to ptrdiff_t or the corresponding unsigned type.

z

Specifies that the d, i, o, u, x, X, or n conversion specifier applies to an argument with type pointer to size_t or the corresponding signed integer type.

D

Specifies that the e, E, f, F, g, or G conversion specifier applies to an argument with type pointer to _Decimal64 float.

DD

Specifies that the e, E, f, F, g, or G conversion specifier applies to an argument with type pointer to _Decimal128 float.

H

Specifies that the e, E, f, F, g, or G conversion specifier applies to an argument with type pointer to _Decimal32 float.

L

Specifies that the a, A, e, E, f, F, g, or G conversion specifier applies to an argument with type pointer to long double.

Conversion specifier: Table 1 explains the valid conversion specifiers and their meanings are in.

Special behavior for XPG4.2:

• When the %n$ conversion specification is found, the value of the input field is converted according to the conversion specification and stored in the location specified by the nth argument in the argument list. Numbered arguments in the argument list can only be referenced once from format-string.
• The format-string can contain either form of the conversion specification, that is, % or %n$ but the two forms cannot be mixed within a single format-string except that %% or %* can be mixed with the %n$ form.

Many z/OS XL C/C++ formatted input functions, including the fscanf family, recognize special infinity and NaN floating-point number input sequences when the invoking thread is in IEEE Binary Floating-Point mode as determined by __isBFP().

• The special sequence for infinity input is an optional plus or minus sign, then the character sequence INF, where the individual characters may be uppercase or lowercase, and then a white space character (space, tab, or newline), a NULL character (\0) or EOF.
• The special sequence for NaN input is an optional plus or minus sign, then the character sequence NANS for a signalling NaN or NANQ for a quiet NaN, where the individual characters may be uppercase or lowercase, then an optional NaN ordinal sequence, and then a a white space character (space, tab, or newline), a NULL character (\0) or EOF.

  For binary floating point NANs: A NaN ordinal sequence is a left-parenthesis character, “(”, followed by a digit sequence representing an integer n, where 1 <= n <= INT_MAX-1, followed by a right-parenthesis character, “)”. If the NaN ordinal sequence is omitted, NaN ordinal sequence (1) is assumed. The integer value, n, corresponding to a NaN ordinal sequence determines what IEEE Binary Floating-Point NaN fraction bits are produced by formatted input functions.

  For a signalling NaN, these functions produce NaN fraction bits (left to right) by reversing the bits (right to left) of the even integer value 2*n.

  For a quiet NaN they produce NaN fraction bits (left to right) by reversing the bits (right to left) of the odd integer value 2*n-1.

  For decimal floating point NANs: A NaN ordinal sequence is a left parenthesis character, "(", followed by a decimal digit sequence of up to 6 digits for a _Decimal32 output number, up to 15 digits for a _Decimal64 output value, or up to 33 digits for a _Decimal128 output value, followed by a right parenthesis, ")". If the NaN ordinal sequence is omitted, NaN ordinal sequence "(0)" is assumed. If the NaN ordinal sequence is shorter than 6, 15, or 33 digits, it will be padded on the left with "0" digits so that the length becomes 6, 15, or, 33 digits for _Decimal32, _Decimal64, and _Decimal128 values respectively.

  For decimal floating point numbers, the digits are not reversed, and both odd or even NaN ordinal sequences can be specified for either a Quiet NAN or Signalling NAN.

CELEBF42

⁄* CELEBF42
                                              
   This example scans various types of data                                     

 *⁄                                                                             
#include <stdio.h>                                                              
                                                                                
int main(void)                                                                  
{                                                                               
   int i;                                                                       
   float fp;                                                                    
   char c, s[81];                                                               
                                                                                
   printf("Enter an integer, a real number, a character "                       
          "and a string : \n");                                                 
   if (scanf("%d %f %c %s", &i, &fp, &c, s) != 4)                               
      printf("Not all of the fields were assigned\n");                          
   else                                                                         
   {                                                                            
      printf("integer = %d\n", i);                                              
      printf("real number = %f\n", fp);                                         
      printf("character = %c\n", c);                                            
      printf("string = %s\n",s);                                                
   }                                                                            
}                                                                               

If input is: 12 2.5 a yes, then output would be:

Enter an integer, a real number, a character and a string:
integer = 12
real number = 2.500000
character = a
string = yes

CELEBF43

/* CELEBF43
   This example converts a hexadecimal integer to a decimal integer.
   The while loop ends if the input value is not a hexadecimal integer.
 */
#include <stdio.h>

int main(void)
{
   int number;

   printf("Enter a hexadecimal number or anything else to quit:\n");
   while (scanf("%x",&number))
      {
      printf("Hexadecimal Number = %x\n",number);
      printf("Decimal Number     = %d\n",number);
      }
}

If input is: 0x231 0xf5e 0x1 q, then output would be:

Enter a hexadecimal number or anything else to quit:
Hexadecimal Number = 231
Decimal Number     = 561
Hexadecimal Number = f5e
Decimal Number     = 3934
Hexadecimal Number = 1
Decimal Number     = 1

CELEBF44

/* CELEBF44
   The next example illustrates the use of scanf() to input fixed-point
   decimal data types. This example works under C only, not C++.
 */
#include <stdio.h>
#include <decimal.h>

decimal(15,4) pd01;
decimal(10,2) pd02;
decimal(5,5) pd03;

int main(void) {
  printf("\nFirst time :-------------------------------\n");
  printf("Enter three fixed-point decimal number\n");
  printf("  (15,4) (10,2) (5,5)\n");
  if (scanf("%D(15,4) %D(10,2) %D(5,5)", &pd01, &pd02, &pd03) != 3) {
    printf("Error found in scanf\n");
  } else {
    printf("pd01 = %D(15,4)\n", pd01);
    printf("pd02 = %D(10,2)\n", pd02);
    printf("pd03 = %D(5,5)\n", pd03);
  }
  printf("\nSecond time :------------------------------\n");
  printf("Enter three fixed-point decimal number\n");
  printf("  (15,4) (10,2) (5,5)\n");
  if (scanf("%D(15,4) %D(10,2) %D(5,5)", &pd01, &pd02, &pd03) != 3) {
    printf("Error found in scanf\n");
  } else {
    printf("pd01 = %D(15,4)\n", pd01);
    printf("pd02 = %D(10,2)\n", pd02);
    printf("pd03 = %D(5,5)\n", pd03);
  }
  return(0);
}

Output

First time :-------------------------------
Enter three fixed-point decimal number
  (15,4) (10,2) (5,5)
12345678901.2345 -987.6 .24680
pd01 = 12345678901.2345
pd02 = -987.60
pd03 = 0.24680

Second time :------------------------------
Enter three fixed-point decimal number
  (15,4) (10,2) (5,5)
123456789013579.24680 123.4567890 987
pd01 = 12345678901.3579
pd02 = 123.45
pd03 = 0.98700

CELEBF46

/* CELEBF46
   The next example opens the file myfile.dat for reading and then scans
   this file for a string, a long integer value, a character, and a
   floating-point value.
 */
#include <stdio.h>
#define  MAX_LEN  80

int main(void)
{
   FILE *stream;
   long l;
   float fp;
   char s[MAX_LEN + 1];
   char c;

   stream = fopen("myfile.dat", "r");

   /* Put in various data. */
   fscanf(stream, "%s", &s[0]);
   fscanf(stream, "%ld", &l);
   fscanf(stream, "%c", &c);
   fscanf(stream, "%f", &fp);

   printf("string = %s\n", s);
   printf("long double = %ld\n", l);
   printf("char = %c\n", c);
   printf("float = %f\n", fp);
}

If myfile.dat contains abcdefghijklmnopqrstuvwxyz 343.2, then the expected output is:

string = abcdefghijklmnopqrstuvwxyz
long double = 343
char = .
float = 2.000000

CELEBS32

/* CELEBS32
   This example uses sscanf() to read various data from the string
   tokenstring, and then displays the data.
 */
#include <stdio.h>
#define  SIZE  81

int main(void)
{
char *tokenstring = "15 12 14";
int i;
float fp;
char s[SIZE];
char c;

   /* Input various data                              */
   printf("No. of conversions=%d\n",
      sscanf(tokenstring, "%s %c%d%f", s, &c, &i, &fp));

   /* If there were no space between %s and %c,       */
   /* sscanf would read the first character following */
   /* the string, which is a blank space.             */

   /* Display the data */
   printf("string = %s\n",s);
   printf("character = %c\n",c);
   printf("integer = %d\n",i);
   printf("floating-point number = %f\n",fp);
}

You would see this output from example CELEBS32.

No. of conversions = 4
string = 15
character = 1
integer = 2
floating-point number = 14.000000