9.11. Formatted I/O

There are a number of related functions used for formatted I/O, each one determining the format of the I/O from a format string. For output, the format string consists of plain text, which is output unchanged, and embedded format specifications which call for some special processing of one of the remaining arguments to the function. On input, the plain text must match what is seen in the input stream; the format specifications again specify what the meaning of remaining arguments is.

Each format specification is introduced by a % character, followed by the rest of the specification.

9.11.1. Output: the printf family

For those functions performing output, the format specification takes the following form, with optional parts enclosed in brackets:

%<flags><field width><precision><length>conversion

The meaning of flags, field width, precision, length, and conversion are given below, although tersely. For more detail, it is worth looking at what the Standard says.

flags

Zero or more of the following:

-

Left justify the conversion within its field.

+

A signed conversion will always start with a plus or minus sign.

space

If the first character of a signed conversion is not a sign, insert a space. Overridden by + if present.

#

Forces an alternative form of output. The first digit of an octal conversion will always be a 0; inserts 0X in front of a non-zero hexadecimal conversion; forces a decimal point in all floating point conversions even if one is not necessary; does not remove trailing zeros from g and G conversions.

0

Pad d, i, o, u, x, X, e, E, f, F and G conversions on the left with zeros up to the field width. Overidden by the - flag. If a precision is specified for the d, i, o, u, x or X conversions, the flag is ignored. The behaviour is undefined for other conversions.

field width

A decimal integer specifying the minimum output field width. This will be exceeded if necessary. If an asterisk is used here, the next argument is converted to an integer and used for the value of the field width; if the value is negative it is treated as a - flag followed by a positive field width. Output that would be less than the field width is padded with spaces (zeros if the field width integer starts with a zero) to fit. The padding is on the left unless the left-adjustment flag is specified.

precision

This starts with a period ‘.’. It specifies the minimum number of digits for d, i, o, u, x, or X conversions; the number of digits after the decimal point for e, E, f conversions; the maximum number of digits for g and G conversions; the number of characters to be printed from a string for s conversion. The amount of padding overrides the field width. If an asterisk is used here, the next argument is converted to an integer and used for the value of the field width. If the value is negative, it is treated as if it were missing. If only the period is present, the precision is taken to be zero.

length

h preceding a specifier to print an integral type causes it to be treated as if it were a short. (Note that the various sorts of short are always promoted to one of the flavours of int when passed as an argument.) l works like h but applies to a long integral argument. L is used to indicate that a long double argument is to be printed, and only applies to the floating-point specifiers. These are cause undefined behaviour if they are used with the ‘wrong’ type of conversion.

conversion

See Table 9.5.

The functions that use these formats are described in Table 9.6. All need the inclusion of <stdio.h>. Their declarations are as shown.

#include <stdio.h>

int fprintf(FILE *stream, const char *format, ...);
int printf(const char *format, ...);
int sprintf(char *s, const char *format, ...);

#include <stdarg.h>     /* as well as stdio.h */
int vfprintf(FILE *stream, const char *format, va list arg);
int vprintf(const char *format, va list arg);
int vsprintf(char *s, const char *format, va list arg);

All of the above functions return the number of characters output, or a negative value on error. The trailing null is not counted by sprintf and vsprintf.

Implementations must permit at least 509 characters to be produced by any single conversion.

9.11.2. Input: the scanf family

A number of functions exist analogous to the printf family, but for the purposes of input instead. The most immediate difference between the two families is that the scanf group needs to be passed pointers to their arguments, so that the values read can be assigned to the proper destinations. Forgetting to pass a pointer is a very common error, and one which the compiler cannot detect—the variable argument list prevents it.

The format string is used to control interpretation of a stream of input data, which generally contains values to be assigned to the objects pointed to by the remaining arguments to scanf. The contents of the format string may contain:

white space

This causes the input stream to be read up to the next non-white-space character.

ordinary character

Anything except white-space or % characters. The next character in the input stream must match this character.

conversion specification

This is a % character, followed by an optional * character (which suppresses the conversion), followed by an optional nonzero decimal integer specifying the maximum field width, an optional h, l or L to control the length of the conversion and finally a non-optional conversion specifier. Note that use of h, l, or L will affect the type of pointer which must be used.

Except for the specifiers c, n and [, a field of input is a sequence of non-space characters starting at the first non-space character in the input. It terminates at the first conflicting character or when the input field width is reached.

The result is put into wherever the corresponding argument points, unless the assignment is suppressed using the * mentioned already. The following conversion specifiers may be used:

d i o u x

Convert a signed integer, a signed integer in a form acceptable to strtol, an octal integer, an unsigned integer and a hexadecimal integer respectively.

e f g

Convert a float (not a double).

s

Read a string, and add a null at the end. The string is terminated by whitespace on input (which is not read as part of the string).

[

Read a string. A list of characters, called the scan set follows the [. A ] delimits the list. Characters are read until (but not including) the first character which is not in the scan set. If the first character in the list is a circumflex ^, then the scan set includes any character not in the list. If the initial sequence is [^] or [], the ] is not a delimiter, but part of the list and another ] will be needed to end the list. If there is a minus sign (-) in the list, it must be either the first or the last character; otherwise the meaning is implementation defined.

c

Read a single character; white space is significant here. To read the first non-white space character, use %1s. A field width indicates that an array of characters is to be read.

p

Read a (void *) pointer previously written out using the %p of one of the printfs.

%

A % is expected in the input, no assignment is made.

n

Return as an integer the number of characters read by this call so far.

The size specifiers have the effect shown in Table 9.7.

The functions are described below, with the following declarations:

#include <stdio.h>

int fscanf(FILE *stream, const char *format, ...);
int sscanf(const char *s, const char *format, ...);
int scanf(const char *format, ...);

Fscanf takes its input from the designated stream, scanf is identical to fscanf with a first argument of stdin, and sscanf takes its input from the designated character array.

If an input failure occurs before any conversion, EOF is returned. Otherwise, the number of successful conversions is returned: this may be zero if no conversions are performed.

An input failure is caused by reading EOF or reaching the end of the input string (as appropriate). A conversion failure is caused by a failure to match the proper pattern for a particular conversion.