C Printf and Scanf Reference

Table of Contents

Background

printf and scanf are the two standard C programming language functions for console input and output.  A variation of these commands (fprintf and fscanf) also allows I/O to files.  Another (sprintf and sscanf) allows I/O to strings.  (sscanf is especially useful.)  All these as well as many other I/O functions are declared in the standard header file <stdio.h>.

Using scanf is trickier than printf.  This is because of promotion, so that any type smaller than an int is promoted to an int when passed to printf, and floats are promoted to double.  This means there is a single code for most integers and one for most floating point types.  There is no such promotion with scanf arguments, which are actually pointers.  So all types must be exactly specified.  In addition there are security concerns with input that don't apply to output.  (These will be discussed below.  In particular, never use the gets() function in production-quality C code!)

Not discussed here is the new C23 Unicode (and wide character) support.  (Hint:  Use the new *wprintf and *wscanf functions.)

printf

A call to printf looks like this:

printf( "format-string", expression, ... );

Or you can use fprintf to send the output to the screen regardless of any output redirection like this:

fprintf( stderr, "format-string", expression, ... );

The format-string can contain regular characters which are simply printed out, and format specifications or place-holders.  For each place-holder in the format-string there must be one matching expression.  The expressions are converted to strings according to the instructions in the corresponding place-holder and are mixed with the regular text in the format-string.  Then the whole string is output.  Here's an example:

printf( "%i + %i = %i\n", 2, 3, (2+3) );

2 + 3 = 5

The following table shows the different format letters you can use with printf.  Each letter corresponds to a different type of argument expression.  It is important to use the correct letter that matches the type of the expression.  The use of any other letter results in undefined behavior.  (Note the %a and %A are only available in C99, the others should be available with any standard C compiler.)  The arguments can be any expression of the correct type (such as literals), but usually are variables whose values were computer earlier.

In the examples, remember that 17 is an int literal, 17L is a long int literal, 017 is an unsigned octal literal (with the decimal value 1*8 + 7 = 15), 0x17, 0X1A are unsigned hexadecimal literals with decimal values of 1*16 + 7 = 23, and 1*16 + A = 16 + 10 = 26, 17u is an unsigned decimal integer literal, 'A' is a char literal with a decimal value of 65, 3.14 and 0.314E1 are double literals, 3.14f is a float literal, and finally 3.14L is a long double literal.

printf Conversion Specification Formatting Syntax

To control the appearance of the converted arguments, any or all (or none) of the following format controls may be used between the % and the final letter of the conversion specification.  Note these must appear (if at all) in the sequence shown here.  A · is used to indicate a space in the example output where spacing is not obvious.

scanf

The scanf (and related functions) are more difficult to use safely and correctly.  Here we will start with a simple use, but such is almost never safe to use in practice!

A call to scanf looks like this:

Or, reading from a file using a file handle (stdin is a predefined file handle but you can define your own via fopen) looks like this:

scanf Return Values

scanf returns a useful error code.  The return value is an int which indicates the number of conversions requested that (1) matched some input, (2) were converted without error, and (3) were assigned without any problems.  (Matching only, or matching and converting only, doesn't count in the return value.)  Depending on the error encountered the return value may be zero, EOF (a symbolic constant usually defined to be -1), or some other integer less than the number of requested conversions.  Because so many problems in programs are a result of bad user input, it is common practice in production-quality code to always check the return value of scanf.

Here's an example use of scanf that attempts to read in two integers from an input file called foo that is formatted with lines like this:

The C code fragment to read the numbers into variables height and width should look something like this:

int height, width;
if ( fscanf( foo, "Height: %i, Width: %i", &height, &width ) != 2 )
{  fprintf( stderr, "###Error with Scanf: bad input data.\a\n" );
   // Do error processing, maybe just "continue" or "break".
}

Here the fscanf is requesting two conversions, so if all goes well the return value should be 2.  Note how the fscanf uses all three types of entries (regular text, white-space, and conversion specifiers).  Although text such as "Height:" and "," are matched, they don't count toward the return value.

Matching input

The system keeps track of which input has been seen so far.  Every call to scanf picks up from where the last one stopped matching input.  This means that if an error occurred with the previous scanf, the input it failed to match is still left unread, as if the user typed ahead.  If care isn't taken to discard error input, and a loop is used to read the input, your program can get caught in an infinite loop.  (See below for an example and further discussion.)

For example, consider this program fragment that reads in an age; assume it is inside a loop:

    scanf( "%i", &age );

If the input is "help" instead of a number, this will cause the scanf to fail when attempting to match an integer ("%i"), and the word help is left unread.  So the next time through the loop, the scanf doesn't wait for fresh user input, it tries to convert help again.

Similarly, if the input were "17.5", the "%i" will match the first two characters only (the 17), leaving the .5 as unread input for the next call to scanf.

Even if the input is correct, as "29", the newline that ended the input is still left unread.  Normally that isn't a problem since most conversions automatically skip leading white-space such as the trailing newline from the previous line.  However some conversions ("%c" and "%[") don't skip any leading white-space so you have to do it manually.

Note that all input functions that read from stdin share the same input buffer, so if a call to scanf("%i", &anInt); is followed by a call to getchar(), the newline left unread by scanf is read in now.  This is not usually what is wanted.

A final warning: Some older compilers will not match any regular text after the last conversion specifier in the conversion-string.  This bug would prevent the example for "%%" below from working correctly.

scanf Format Specification Syntax

The control of input conversion is much simpler than for output conversions.  Any, all, or none of the following format modifiers may be used between the % and the final letter of the conversion specification.  Note these must appear (if at all) in the sequence shown here.  A · is used to indicate a space in the example output where spacing is not obvious.

Examples Using scanf and Other Input Techniques

1. Example:  Matching

   The scanf call:

   int i;  float x;  char name[50];
   scanf( "%2d%f%*d %[0123456789]", &i, &x, name );
   

   With this input:

   56789 0123 56a72
   

   will assign to i the value 56 and to x the value 789.0, will skip 0123, and assign to name the sequence 56\0 (the string "56").  The next character to be read from the input will be a.





2. Example:  non-GUI Interactive Input

   A simple (and common) example reads an int from a user this way:

   int age;
   for ( ;; )
   {  fprintf( stderr, "Please enter your age: " );
      if ( scanf( "%i", &age ) == 1 )
         break;
      // Do some sort of error processing:
      fprintf( stderr, "\nError reading in the age, please try again.\n" );
   }
   printf( "You are %i years old.\n", age );
   

   Note the use of fprintf to send the output to the screen even if output was redirected.  Some common error processing is to reset the variables and try again, using a loop as shown here.  Sometimes a count of attempts is kept and the user is only given a certain number of attempts before the program gives up.





3. Example: Line (record) at a time input

   A problem with scanf is that it leaves any unmatched input unread.  This may be a problem for applications that expect line oriented input.  When each line (or record) of input is to be processed independently, an error such as bad data on one line can cause errors when attempting to read the following line.

   Consider the code above to read in an age.  If the input entered by the user was non-numeric such as the word "help", the "h" would not match the "%i" and would be left unread.  When the for loop repeated, the scanf would encounter the "h" again and immediately fail.  This would cause an infinite loop!

   A similar problem would exist if the user entered "29.5" for their age.  The first time through the loop the scanf would read the 29.  If the next input expected was a person's name or ID or whatever, the ".5" will be read next.

   Another common problem with this approach is mixing scanf with getchar or getc.  The scanf typically leaves the newline unread, so a call to read the next character retrieves that instead of the character the programmer expected to get.  (This problem may be worse on DOS based systems, which have two characters to mark the end of lines.)

   The solution is to use fgets (see note) to read input a line at a time into a buffer, then use the sscanf function to parse the contents of the buffer.  With this approach each input operation consumes (reads) an entire line of input, even if it had errors.  The next input operation starts fresh with the next line of input.

   Here's an example to illustrate the technique:

   char buf[BUFSIZ];     /* Buffer for a line of input. */
   int age;
   
   fprintf( stderr, "Please enter your age: " );
   // Loop until the user enters a correct value:
   while ( fgets( buf, sizeof(buf), stdin ) != NULL )
   {
      if ( sscanf( buf, "%i", &age ) == 1 )
         break;
      // Do some sort of error processing:
      fprintf( stderr, "\nError reading in the age, please try again." );
      fprintf( stderr, "Please enter your age: " );
   }
   // age has been correctly read at this point.
   

   The call to fgets reads all input up to and including a newline.  It then copies that line of input into buf, adding a '\0' at the end to form a valid C string.  The terminating newline is also copied into buf.  On EOF, fgets returns NULL.  (EOF and NULL are defined in <stdio.h>.)  If the input is larger than the size of the buffer, than only the input that will fit is consumed (read).  Note fgets is smart enough to reserve space for the '\0' from the size given.  In this case the maximum input read would be BUFSIZ-1.

   The sscanf works just like scanf or fscanf.  The first argument to sscanf is the string to read from (instead of stdin as for scanf).  If the fgets doesn't detect EOF but the sscanf fails to match any input using "%s", the input must have been a blank line.  When using "%i" and not a "%s", the return value doesn't tell if the input was a blank line or some other error.





4. Example: Detecting extraneous input

   The line at a time example above works well but doesn't detect all errors.  Consider what would happen if the user entered 29.5 for an age, or 32,500 for some numeric value (such as a person's income in dollars).  While the fgets will read the whole line, the sscanf will only read 29 in the first case and 32 in the second.  In both cases sscanf will return 1 and the errors would go undetected.

   In order to detect such extra input on the line scanf must attempt to match it, convert it, and assign it to a variable.  Then the return value will be 2 if extra input was present.  There are two ways to do this.  If extra white space is not considered an error you can use "%s" instead of the "%[" used below:

   char buf[BUFSIZ], junk[BUFSIZ];
   int income;
   
   fprintf( stderr, "Please enter your income: " );
   // Loop until the user enters a correct value:
   while ( fgets( buf, sizeof(buf), stdin ) != NULL )
   {
      if ( sscanf( buf, "%i%[^\n]", &income, junk ) == 1 )
         break;
      // Do some sort of error processing:
      fprintf( stderr, "\nError reading your income, please try again.\n" );
      fprintf( stderr, "Please enter your income: " );
   }
   // income correctly enters read at this point.
   

   Here the sscanf will skip leading white space (%i does this automatically), match digits until the first non-digit, convert the matched string to an int and assign the result to income.  sscanf then matches any remaining characters (up to but not including a newline) and stores the string in junk.  If there were no input errors, the %i would succeed but the %[^\n] will fail to match any input.  The return value would therefore be 1.  However if any extra input was encountered the %[^\n] will match it and assign the string to junk.  This would cause sscanf to return 2.  If the user input was "$32500, the %i would fail to match anything and the return value would be 0.  This technique will therefore catch any input errors and consume the entire line (record) whether or not errors were present.

Character Constants

Below is a table of character constants.  These can be used individually (as a char literal by surrounding the constant with single quotes) or as part of a double-quoted string literal.

Notes:

The C standard doesn't use the term Unicode character much, the authors prefer the term Universal character.  It's pretty clear that they mean Unicode though, since it is referred to by it's official name of "ISO/IEC 10646" in several places.  Unicode is actually a 4 byte per character encoding, however most non-Asian characters are found in the lower half of the character set, so the 2 byte form is common.  (Actually Unicode is often stored in files in a form called UTF-8.)

Such characters are called wchar_t constants.  You can make a literal for one as follows:  L'\u00A9' (which is the same character as '\xA9', namely the "©" symbol).  You can also form wide strings such as:  L"\u00A92001", which translates to the string "©2001".

(Technically, regular strings are multi-byte character strings as they can often hold multi-byte characters.  It depends on the locale, the compiler, the platform (Windows allows only 1 or 2 byte characters), and the specific character in question.  There's a whole host of string and character conversion functions such as mbstows (multi-byte string to wide string) and wstombs.  To deal properly with all Unicode input or output, I generally use the ICU Unicode library.

This information was extracted from ISO/IEC 9899, second edition (the C99 Standard), mostly from sections 7.19.6.1 and 7.19.6.2.  Some information comes from a draft of the C23 standard.