printf(3S) printf(3S)
NAME
printf, fprintf, sprintf - print formatted output
SYNOPSIS
#include <stdio.h>
int printf(const char *format, .../* args */);
int fprintf(FILE *stream, const char *format, .../* args */);
int sprintf(char *s, const char *format, .../* args */);
DESCRIPTION
printf() writes on the standard output stream stdout.
fprintf() writes on the specified stream.
sprintf() writes in consecutive bytes of storage, starting at s, fol-
lowed by a terminating null character.
It is the user's responsibility to ensure that enough storage is
available. Each function returns the number of characters transmitted
(not including the \0 in the case of sprintf()) or a negative value if
an output error was encountered.
These functions convert, format, and print their args in the specified
format. The format is a character string that can contain three types
of objects:
1. Plain characters that are simply copied to the output stream;
2. Escape sequences that represent non-graphic characters;
3. Conversion specifications.
The following escape sequences produce the associated action on de-
vices capable of the action:
\a Alert. Outputs a tone (BEL character).
\b Backspace. Move the printing position to one character before the
current position, unless the current position is the start of a
line (BS character).
\f Form feed. Move the printing position to the initial printing
position of the next logical page (FF character).
\n Newline. Move the printing position to the start of the next line
(NL character).
\r Return. Move the printing position to the start of the current
line (CR character).
Page 1 Reliant UNIX 5.44 Printed 11/98
printf(3S) printf(3S)
\t Horizontal tab. Move the printing position to the next horizontal
tab position on the current line (TAB character).
\v Vertical tab. Move the printing position to the next vertical tab
position (VT character).
\? Outputs question mark.
\\ Outputs backslash.
\' Outputs apostrophe.
\" Outputs inverted commas.
\octalcode
Character entered in octal code is output in ASCII code.
\xhexadecimalcode
Character entered in hexadecimal code is output in ASCII code.
Example: \100 (oct.) or \x40 (hex.) both give the same @ charac-
ter in ASCII code.
Conversion specifications
Each conversion specification is introduced by the character %. After
the character %, the following appear in sequence:
- An optional field, consisting of a sequence of decimal numbers fol-
lowed by a $, specifying the next arguments to be converted. If
this field is not provided, the arguments following the last con-
verted arguments will be used.
- An optional string of decimal numbers to specify a minimum field
width. If the converted value has fewer characters than the field
width, it will be padded on the left (or right, if the left-adjust-
ment flag described below, has been given) to the field width.
- An optional precision that gives the minimum number of digits to
appear for the d, i, o, u, x, or X conversions (the field is padded
with leading zeros), the number of digits to appear after the
decimal-point character for the e, E, and f conversions, the max-
imum number of significant digits for the g and G conversions, or
the maximum number of characters to be printed from a string in s
conversion. The precision takes the form of a period followed by a
decimal number string; a null digit string is treated as zero. Pad-
ding specified by the precision overrides the padding specified by
the field width.
Page 2 Reliant UNIX 5.44 Printed 11/98
printf(3S) printf(3S)
- A character that indicates the type of conversion to be applied.
A field width, or precision, or both, may be indicated by an asterisk
(*) or a decimal digit string. In this case, an integer argument sup-
plies the field width or precision. The argument that is actually con-
verted is not fetched until the conversion letter is seen, so any
arguments which specify field width or precision must appear before
the argument to be converted. If the precision argument is negative,
it will be changed to zero. A negative field width argument is taken
as a "-" flag, followed by a positive field width.
In format strings containing the %digits$ form of a conversion speci-
fication, a field width or precision may also be indicated by the
sequence *digits$, where digits gives the position in the argument
list of an integer.
When numbered argument specifications are used, specifying the nth
argument requires that all the preceding arguments, from the first to
the (n-1)th, be specified in the format string.
All forms of the printf() functions allow for the insertion of a
language-dependent decimal-point character. The decimal-point charac-
ter is defined by the program's locale (LCNUMERIC). In the C locale,
or in a locale where the decimal-point character is not defined, the
decimal-point character defaults to a period.
Flags
' The integer portion of the result of a decimal conversion (%i, %d,
%u, %f, %g or %G) will be formatted with thousands' grouping char-
acter. For other conversions the behavior is undefined. This flag
is recognized from XPG4 mode onwards.
- The result of the conversion will be left-justified within the
field. (It will be right-justified if this flag is not specified.)
+ The result of a signed conversion will always begin with a sign (+
or -).
<blank>
If the first character of a signed conversion is not a sign, a
space will be placed before the result. This means that the space
will be ignored if it is specified with the + character.
# The value is to be converted to an alternate form. For c, d, i, s,
and u conversions, the flag has no effect. For an o conversion, it
increases the precision to force the first digit of the result to
be a zero. For x (or X) conversion, a non-zero result will have 0x
(or 0X) prepended to it. For e, E, f, g, and G conversions, the
result will always contain a decimal-point character, even if no
digits follow the point (normally, a decimal point appears in the
result of these conversions only if a digit follows it. For g and G
Page 3 Reliant UNIX 5.44 Printed 11/98
printf(3S) printf(3S)
conversions, trailing zeros will not be removed from the result as
they normally are.
0 For d, i, o, u, x, X, e, E, f, g, and G conversions, leading zeros
(following any indication of sign or base) are used to pad to the
field width; no space padding is performed. If the 0 and - flags
both appear, the 0 flag will be ignored. For d, i, o, u, x, and X
conversions, if a precision is specified, the 0 flag will be
ignored. For other conversions, the behavior is undefined.
Each conversion character results in fetching zero or more arguments.
The results are undefined if there are insufficient arguments for the
format. If the format is exhausted while arguments remain, the excess
arguments are ignored.
Conversion characters
c, lc
An argument of type int is converted to an unsigned char, and the
resulting character is printed.
If no l qualifier is present, the int argument is converted to an
unassigned char, and the resulting character is written. Other-
wise, the wintt argument is converted as if by an ls conversion
specification with no precision and an argument that points to a
two-element array of wchart, the first element containing the
wintt argument to the lc conversion specification and the second
a null wide-character.
C The wchart argument is converted to an array of bytes represent-
ing a character, and the resulting character is written. If the
precision is specified, its effect is undefined. The conversion
is the same as that expected from the wctomb() function.
Note: This conversion specification is recognized from XPG4 mode
onwards.
d, i, o, u, x, X
An int type argument is converted to signed decimal (d or i), to
unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal
notation (x and X). The x conversion uses the letters abcdef and
the X conversion uses the letters ABCDEF. The precision specifies
the minimum number of digits to appear. If the value being con-
verted can be represented in fewer digits than the specified
minimum, it will be expanded with leading zeros. The default pre-
cision is 1. The result of converting a zero value with a preci-
sion of zero is no characters.
Page 4 Reliant UNIX 5.44 Printed 11/98
printf(3S) printf(3S)
e, E An argument of type double is converted to decimal notation in
style [-]d.ddde±dd, where there is one digit before the decimal-
point character (which is nonzero if the argument is non-zero)
and the number of digits after it is equal to the precision. When
the precision is missing, six digits are produced; if the preci-
sion is zero and the # flag is not specified, no decimal-point
character appears. The E conversion character will produce a
number with E instead of e introducing the exponent. The exponent
always contains at least two digits. The value is rounded to the
appropriate number of digits.
f An argument of type double is converted to decimal notation in
style [-]ddd.ddd, where the number of digits after the decimal-
point character [see setlocale(3C)] is equal to the precision
specification. If no precision is specified, six digits are out-
put; if the precision is explicitly zero and the # flag is not
specified, no decimal-point character appears. If a decimal-point
appears, at least 1 digit appears before it. The value is rounded
to the appropriate number of digits.
g, G An argument of type double is printed in style f or e (or in
style E in the case of a G conversion character), with the preci-
sion specifying the number of significant digits. If the preci-
sion is zero, a value of 1 is assumed. The style used depends on
the value converted: style e (or E) will be used only if the
exponent resulting from the conversion is less than -4 or greater
than or equal to the precision. Trailing zeros are removed from
the fractional part of the result. A decimal-point character
appears only if it is followed by a digit.
hd, hi, ho, hu, hx, hX
Specifies that the corresponding conversion specifier applies to
a short int or unsigned short int argument. The argument will be
supported according to the C rules for value conversions, and its
value converted to short int or unsigned short int before print-
ing.
hn Specifies that the corresponding conversion specifier applies to
a pointer to a short int argument.
ld, li, lo, lu, lx, lX
Specifies that the corresponding conversion specifier applies to
a long int or unsigned long int argument.
lld, llx
Specifies that the corresponding conversion specifier applies to
a long long int or unsigned long long int argument.
ln Specifies that the corresponding conversion specifier applies to
a pointer to long int argument.
Page 5 Reliant UNIX 5.44 Printed 11/98
printf(3S) printf(3S)
Le, LE, Lf, Lg, LG
Specifies that the corresponding conversion specifier applies to
a long double argument.
Note: If an h, l, or L modifier appears before a conversion
specifiers other than those listed above, the behavior is unde-
fined.
n The argument should be a pointer to an int, into which is written
the number of characters written to the output standard I/O
stream so far by this call to printf(), fprintf(), or sprintf().
No argument is converted.
p The argument is a pointer to void. The value of the pointer is
converted to an implementation-defined set of sequences of print-
able characters, which should be the same as the set of sequences
that are matched by the %p conversion of the scanf() function.
s, ls
The argument is a character pointer to char, and characters from
the string are written up to (but not including) a terminating
null character; if the precision is specified, no more than that
many characters are written. If the precision is not specified,
it is taken to be infinite, so all characters up to the first
null character are printed. A NULL value for an argument will
yield undefined results.
If an l qualifier is present, the argument shall be a pointer to
an array of wchart type. Wide-characters from the array are con-
verted to multibyte characters (each as if by a call to the
wcrtomb() function, with the conversion state describe by an
mbstatet object initialized to zero before the first wide-char-
acter is converted) up to and including a terminating null wide-
character. The resulting multibyte characters are written up to
(but not including) the terminating null character (byte). If no
precision is specified, the array shall contain a null wide-char-
acter. If a precision is specified, no more than that many char-
acters (bytes) are written (including shift sequences, if any),
and the array shall contain a null wide-character if, to equal
the multibyte character sequence length given by the precision,
the function would need to access a wide-character one past the
end of the array. In no case is a partial multibyte character
written. Redundant shift sequences may result if multibyte char-
acters have a state-dependent encoding.
S The argument must be a pointer to an array of type wchart.
Wide-character codes from the array, up to but not including any
terminating null wide-character code, are converted to a sequence
of bytes, and the resulting bytes are written. If the precision
is specified no more than that many bytes are written and only
complete characters are written. If the precision is not speci-
fied, or is greater than the size of the array of converted
Page 6 Reliant UNIX 5.44 Printed 11/98
printf(3S) printf(3S)
bytes, the array of wide-characters must be terminated by a null
wide-character. The conversion is the same as that expected from
the wcstombs() function.
Note: This conversion specification is recognized from XPG4 mode
onwards.
% Print a %; no argument is converted.
If the character after the % or %digits$ sequence is not a valid
conversion character, the results of the conversion are undefined.
If a floating-point value is the internal representation for infinity,
the output is [±]inf, where inf is either inf or INF, depending on the
conversion character. Printing of the sign follows the rules described
above.
If a floating-point value is the internal representation for NaN, the
output is [±]nan0xm. Depending on the conversion character, nan is
either nan or NAN. Additionally, 0xm represents the most significant
part of the mantissa. Again depending on the conversion character, x
will be x or X, and m will use the letters abcdef or ABCDEF. Printing
of the sign follows the rules described above.
In no case does a non-existent or small field width cause truncation
of a field; if the result of a conversion is wider than the field
width, the field is simply expanded to contain the conversion result.
Characters generated by printf() and fprintf() are printed as if the
putc() routine had been called.
EXAMPLES
To print a date and time in the form Sunday, July 3, 10:02, where
weekday and month are pointers to null-terminated strings:
printf("%s, %s %i, %d:%.2d",
weekday, month, day, hour, min);
To print "pi" to 5 decimal places:
printf("pi = %.5f", 4 * atan(1.0));
RETURN VALUES
printf(), fprintf(), and sprintf() return the number of characters
transmitted, or return a negative value if an error was encountered.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
The function will fail if either the stream is unbuffered or the
stream's buffer needed to be flushed and:
Page 7 Reliant UNIX 5.44 Printed 11/98
printf(3S) printf(3S)
EAGAIN The ONONBLOCK flag is set for the file descriptor underly-
ing stream and the process would be delayed in the write
operation.
EBADF The file descriptor underlying stream is not a valid file
descriptor open for writing.
EFBIG An attempt was made to write to a file that exceeds the max-
imum file size or the process' file size limit.
EFBIG The file is a regular file and an attempt was made to write
at or beyond the offset maximum associated with the corre-
sponding stream.
EINTR The write operation was terminated due to the receipt of a
signal, and no data was transferred.
EIO A physical I/O error has occurred, or the process is a
member of a background process group attempting to write to
its controlling terminal, TOSTOP is set, the process is nei-
ther ignoring nor blocking SIGTTOU and the process group of
the process is orphaned. This error may also be returned
under implementation-dependent conditions.
ENOSPC There was no free space remaining on the device containing
the file.
EPIPE An attempt is made to write to a pipe or FIFO that is not
open for reading by any process. A SIGPIPE signal will also
be sent to the process.
The function may fail if:
EILSEQ A wide-character code that does not correspond to a valid
character has been detected.
EINVAL There are insufficient arguments.
ENOMEM Insufficient storage space is available.
ENXIO A request was made of a non-existent device, or the request
was outside the capabilities of the device.
NOTES
Flag ' and conversions %C and %S are recognized from XPG4 mode
onwards.
SEE ALSO
exit(2), lseek(2), write(2), abort(3C), ecvt(3C), setlocale(3C),
putc(3S), scanf(3S), stdio(3S), lfs(5), stdio(5).
Page 8 Reliant UNIX 5.44 Printed 11/98