Outputs data to a stream input/output file according to the format.
[Format]
#include <stdio.h>
long fprintf (FILE *fp, const char *control[, arg]...);
[Parameters]
fp File pointer
control Pointer to string indicating format
arg,... List of data to be output according to format
[Return values]
Normal: Number of characters converted and output
Abnormal: Negative value
[Remarks]
The fprintf function converts and edits parameter arg according to the string that represents the format pointed to by control, and outputs the result to the stream input/output file indicated by file pointer fp.
The fprintf function returns the number of characters converted and output when the function is terminated successfully, or a negative value if an error occurs.
The format specifications are shown below.
Overview of Formats
The string that represents the format is made up of two kinds of string.
A character other than a conversion specification shown below is output unchanged.
- | Conversion specifications |
A conversion specification is a string beginning with % that specifies the conversion method for the following parameter. The conversion specifications format conforms to the following rules:
When there is no parameter to be actually output according to this conversion specification, the behavior is not guaranteed. In addition, when the number of parameters to be actually output is greater than the conversion specification, the excess parameters are ignored.
Description of Conversion Specifications
Flags specify modifications to the data to be output, such as addition of a sign. The types of flag that can be specified and their meanings are shown in Table 7.9.
Table 7.9 | Flag Types and Their Meanings |
|
|
|
|
–
|
If the number of converted data characters is less than the field width, the data will be output left-justified within the field.
|
|
+
|
A plus or minus sign will be prefixed to the result of a signed conversion.
|
|
space
|
If the first character of a signed conversion result is not a sign, a space will be prefixed to the result. If the space and + flags are both specified, the space flag will be ignored.
|
|
#
|
The converted data is to be modified according to the conversion types described in Table 7.11.
1. For c, d, i, s, and u conversions
This flag is ignored.
2. For o conversion
The converted data is prefixed with 0.
3. For x or X conversion
The converted data is prefixed with 0x (or 0X)
4. For e, E, f, g, and G conversions
A decimal point is output even if the converted data has no fractional part. With g and G conversions, the 0 suffixed to the converted data are not removed.
|
The number of characters in the converted data to be output is specified as a decimal number.
If the number of converted data characters is less than the field width, the data is prefixed with spaces up to the field width. (However, if '-' is specified as a flag, spaces are suffixed to the data.)
If the number of converted data characters exceeds the field width, the field width is extended to allow the converted result to be output.
If the field width specification begins with 0, the output data is prefixed with characters "0", not spaces.
The precision of the converted data is specified according to the type of conversion, as described in Table 7.11.
The precision is specified in the form of a period (.) followed by a decimal integer. If the decimal integer is omitted, 0 is assumed to be specified.
If the specified precision is incompatible with the field width specification, the field width specification is ignored.
The precision specification has the following meanings according to the conversion type.
- | For d, i, o, u, x, and X conversions |
The minimum number of digits in the converted data is specified.
- | For e, E, and f conversions |
The number of digits after the decimal point in the converted data is specified.
The maximum number of significant digits in the converted data is specified.
The maximum number of printed digits is specified.
(d) | Parameter size specification |
For d, i, o, u, x, X, e, E, f, g, and G conversions (see Table 7.10), the size (short type, long type, long long type, or long double type) of the data to be converted is specified. In other conversions, this specification is ignored. Table 7.10 shows the types of size specification and their meanings.
Table 7.10 | Parameter Size Specification Types and Meanings |
|
|
|
|
|
1
|
hh
|
For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions, specifies that the data to be converted is of signed char type or unsigned char type. For n conversion, specifies that the data to be converted is of pointer type to signed char type.
|
|
2
|
h
|
For d, i, o, u, x, and X conversions, specifies that the data to be converted is of short type or unsigned short type. For n conversion, specifies that the data to be converted is of pointer type to short type.
|
|
3
|
l
|
For d, i, o, u, x, and X conversions, specifies that the data to be converted is of long type, unsigned long type, or double type.
|
|
4
|
L
|
For e, E, f, g, and G conversions, specifies that the data to be converted is of long double type.
|
|
5
|
ll
|
For d, i, o, u, x, and X conversions, specifies that the data to be converted is of long long type or unsigned long long type. For n conversion, specifies that the data to be converted is of pointer type to long long type.
|
|
6
|
j
|
For d, i, o, u, x, and X conversions, specifies that the data to be converted is of intmax_t type or uintmax_t type. For n conversion, specifies that the data to be converted is of pointer type to size_t type.
|
|
7
|
z
|
For d, i, o, u, x, and X conversions, specifies that the data to be converted is of size_t type or signed integer type corresponding to size_t type. For n conversion, specifies that the data to be converted is of pointer type to size_t type.
|
|
8
|
t
|
For d, i, o, u, x, and X conversions, specifies that the data to be converted is of ptrdiff_t type or unsigned integer type corresponding to ptrdiff_t type. For n conversion, specifies that the data to be converted is of pointer type to ptrdiff_t type.
|
The format into which the data is to be converted is specified.
If the data to be converted is structure or array type, or is a pointer pointing to those types, the behavior is not guaranteed except when a character array is converted by s conversion or when a pointer is converted by p conversion. Table 7.11 shows the conversion specifier and conversion methods. If a letter which is not shown in this table is specified as the conversion specifier, the behavior is not guaranteed. The behavior, if a character that is not a letter is specified, depends on the compiler.
Table 7.11 | Conversion Specifiers and Conversion Methods |
|
|
|
|
|
|
|
|
1
|
d
|
d conversion
|
int type data is converted to a signed decimal string. d conversion and i conversion have the same specification.
|
int type
|
The precision specification indicates the minimum number of characters output. If the number of converted data characters is less than the precision specification, the string is prefixed with zeros. If the precision is omitted, 1 is assumed. If conversion and output of data with a value of 0 is attempted with 0 specified as the precision, nothing will be output.
|
|
2
|
i
|
i conversion
|
int type
|
|
3
|
o
|
o conversion
|
int type data is converted to an unsigned octal string.
|
int type
|
|
4
|
u
|
u conversion
|
int type data is converted to an unsigned decimal string.
|
int type
|
|
5
|
x
|
x conversion
|
int type data is converted to unsigned hexadecimal. a, b, c, d, e, and f are used as hexadecimal characters.
|
int type
|
|
6
|
X
|
X conversion
|
int type data is converted to unsigned hexadecimal. A, B, C, D, E, and F are used as hexadecimal characters.
|
int type
|
|
7
|
f
|
f conversion
|
double type data is converted to a decimal string with the format [-] ddd.ddd.
|
double type
|
The precision specification indicates the number of digits after the decimal point. When there are characters after the decimal point, at least one digit is output before the decimal point. When the precision is omitted, 6 is assumed. When 0 is specified as the precision, the decimal point and subsequent characters are not output. The output data is rounded.
|
|
8
|
F
|
F conversion
|
double type
|
|
9
|
e
|
e conversion
|
double type data is converted to a decimal string with the format [-] d.ddde±dd. At least two digits are output as the exponent.
|
double type
|
The precision specification indicates the number of digits after the decimal point. The format is such that one digit is output before the decimal point in the converted characters, and a number of digits equal to the precision are output after the decimal point. When the precision is omitted, 6 is assumed. When 0 is specified as the precision, characters after the decimal point are not output. The output data is rounded.
|
|
10
|
E
|
E conversion
|
double type data is converted to a decimal string with the format [-] d.dddE±dd. At least two digits are output as the exponent.
|
double type
|
|
11
|
g
|
g conversion (or G conversion)
|
Whether f conversion format output or e conversion (or E conversion) format output is performed is determined by the value to be converted and the precision value that specifies the number of significant digits. Then double type data is output. If the exponent of the converted data is less than –4, or larger than the precision that indicates the number of significant digits, conversion to e (or E) format is performed.
|
double type
|
The precision specification indicates the maximum number of significant digits in the converted data.
|
|
12
|
G
|
double type
|
|
13
|
a
|
a conversion
|
double type data is converted to a hexadecimal string with the [-]0xh.hhhhp ± d format. At least one digit is output as the exponent.
|
double type
|
The precision specification indicates the number of digits after the decimal point. The format is such that one digit is output before the decimal point in the converted characters, and a number of digits equal to the precision are output after the decimal point. When the precision is omitted, a precision sufficient for representing an accurate value is assumed. When 0 is specified as the precision, characters after the decimal point are not output. The output data is rounded.
|
|
14
|
A
|
A conversion
|
double type data is converted to a hexadecimal string with the [-]0Xh.hhhhP ± d format. At least one digit is output as the exponent.
|
double type
|
|
15
|
c
|
c conversion
|
int type data is converted to unsigned char data, with conversion to the character corresponding to that data.
|
int type
|
The precision specification is invalid.
|
|
16
|
s
|
s conversion
|
The string pointed to by pointer to char type are output up to the null character indicating the end of the string or up to the number of characters specified by the precision. (Null characters are not output. Space, horizontal tab, and new-line characters are not included in the converted string.)
|
Pointer to char type
|
The precision specification indicates the number of characters to be output. If the precision is omitted, characters are output up to, but not including, the null character in the string pointed to by the data. (Null characters are not output. Space, horizontal tab, and new-line characters are not included in the converted string.)
|
|
17
|
p
|
p conversion
|
Assuming data as a pointer, conversion is performed to a string of compiler-defined printable characters.
|
Pointer to void type
|
The precision specification is invalid.
|
|
18
|
n
|
No conversion is performed.
|
Data is regarded as a pointer to int type, and the number of characters output so far is set in the storage area pointed to by that data.
|
Pointer to int type
|
|
|
19
|
%
|
No conversion is performed.
|
% is output.
|
None
|
|
(f) | * specification for field width or precision |
* can be specified as the field width or precision specification value. In this case, the value of the parameter corresponding to the conversion specification is used as the field width or precision specification value. When this parameter has a negative field width, it is interpreted as flag '–' and a positive field width. When the parameter has a negative precision, the precision is interpreted as being omitted.
