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.
Specifier |
Effect |
Default precision |
d |
signed decimal |
1 |
i |
signed decimal |
1 |
u |
unsigned decimal |
1 |
o |
unsigned octal |
1 |
x |
unsigned hexadecimal (0 –f ) |
1 |
X |
unsigned hexadecimal (0 –F ) |
1 |
|
Precision specifies minimum number of digits, expanded
with leading zeros if necessary. Printing a value
of zero with zero precision outputs no characters. |
|
f |
Print a double with precision
digits (rounded) after the decimal point. To suppress
the decimal point use a precision of explicitly zero.
Otherwise, at least one digit appears in front of the point. |
6 |
e , E |
Print a double in exponential format, rounded, with one
digit before the decimal point, precision after it. A
precision of zero suppresses the decimal point. There will
be at least two digits in the exponent, which is printed as
1.23e15 in e format, or 1.23E15
in E format. |
6 |
g,G |
Use style f , or e (E with
G ) depending on the exponent. If the exponent is less
than −4 or ≥ precision, f is not
used. Trailing zeros are suppressed, a decimal point is only
printed if there is a following digit. |
unspecified |
c |
The int argument is converted
to an unsigned char and the
resultant character printed. |
|
s |
Print a string up to precision digits long. If
precision is not specified, or is greater than the
length of the string, the string must be NUL
terminated. |
infinite |
p |
Display the value of a (void * ) pointer in a
system-dependent way. |
|
n |
The argument must be a pointer to an integer. The number of
characters output so far by this call will be written into
the integer. |
|
% |
A % |
— |
Table 9.5. Conversions
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);
Name |
Purpose |
fprintf |
General formatted output as described.
Output is written to the file indicated
by stream . |
printf |
Identical to fprintf with a first
argument equal to stdout . |
sprintf |
Identical to fprintf except that the
output is not written to a file, but
written into the character array pointed
to by s . |
vfprintf |
Formatted output as for fprintf , but
with the variable argument list replaced
by arg which must have been initialized
by va_start . va_end is not called by
this function. |
vprintf |
Identical to vfprintf with a first
argument equal to stdout . |
vsprintf |
Formatted output as for sprintf , but
with the variable argument list replaced
by arg which must have been initialized
by va_start . va_end is not called by
this function. |
Table 9.6. Functions performing formatted output
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.
Specifier |
Modifies |
Converts |
l |
d i o u x |
long int |
h |
d i o u x |
short int |
l |
e f |
double |
L |
e f |
long double |
Table 9.7. Size specifiers
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.
|
Printer-friendly version
The C Book
This book is published as a matter of historical interest.
Please read the
copyright and disclaimer information.
GBdirect Ltd provides up-to-date training and consultancy in
C,
Embedded C,
C++
and a wide range of
other subjects based on
open standards if you happen to be interested.
|