fprintf(S-osr5)
fprintf, printf, snprintf, sprintf, vfprintf, vprintf, vsnprinf, vsprintf --
place print output on stream
Syntax
cc . . . -lc
#include <stdio.h>
int fprintf(FILE *strm, const char *format, .../* args */);
int printf(const char *format, .../* args */);
int snprintf(char *s, size_t maxsize, const char *format, .../* args */);
int sprintf(char *s, const char *format, .../* args */);
#include <stdarg.h>
int vfprintf(FILE *strm, const char *format, va_list args);
int vprintf(const char *format, va_list args);
int vsnprintf(char *s, size_t maxsize, const char *format, va_list args);
int vsprintf(char *s, const char *format, va_list args);
Description
Each of these functions converts, formats, and outputs
its args under control of the character string format.
Each function returns the number of characters transmitted
(not including the terminating null character in the case of
snprintf, sprintf, vsnprintf and vsprintf)
or a negative value if an output error was encountered.
fprintf and vfprintf place output on strm.
printf and vprintf place output
on the standard output stream stdout.
sprintf and vsprintf place output,
followed by a null character (\0),
in consecutive bytes starting at s.
It is the caller's responsibility to ensure
that enough storage is available.
snprintf (vsnprintf) behaves like sprintf (vsprintf),
except that no more than maxsize characters are placed into the array,
including the terminating null character.
If more than maxsize characters were requested,
the output array will contain exactly maxsize characters,
with a null character being the last
(when maxsize is nonzero);
a negative value is returned.
The ``v'' functions take their arguments through
the single va_list object passed.
See
varargs(S-osr5).
The format consists of zero or more ordinary characters
(not %)
which are directly copied to the output,
and zero or more conversion specifications,
each of which is introduced by the a %
and results in the fetching of zero or more associated args.
Each conversion specification takes the following general form and sequence:
%[pos$][flags][width][.prec][size]fmt
pos$-
An optional entry,
consisting of one or more decimal digits
followed by a $ character,
that specifies the number of the
next arg to access.
The first arg
(just after format)
is numbered 1.
If this entry is not present,
the arg following the most recently
used arg will be accessed.
flags-
Zero or more characters that
change the meaning of the conversion specification.
The flag characters and their meanings are:
--
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 -).
(It will begin with a sign only when a
negative value is converted if this flag
is not specified.)
space-
If the first character of a signed conversion is not a sign,
or if a signed conversion results in no characters,
a space will be prefixed to the result.
If the space and + flags both appear,
the space flag will be ignored.
#-
The value is to be converted to an alternate form,
depending on the fmt character:
a, A, e, E, f, F, g, G-
The result will contain a decimal point character,
even if no digits follow.
(Normally,
the decimal point character is only present
when fractional digits are produced.)
b, B-
A nonzero result will have 0b or 0B prefixed to it.
g, G-
Trailing zero digits will not be removed from the result,
as they normally are.
o-
The precision is increased
(only when necessary)
to force a zero as the first digit.
x, X-
A nonzero result will have 0x or 0X prefixed to it.
For other conversions,
the behavior is undefined.
0-
For all numeric conversions
(a, A, e, E, f, F, g, G,
b, B, d, i, o, u, x and X),
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 the integer numeric conversions
(b, B, d, i, o, u, x and X),
if a precision is specified,
the 0 flag will be ignored.
For other conversions, the behavior is undefined.
´-
(an apostrophe)
The nonfractional portion of the result of a decimal numeric conversion
(d, i, u, f, F, g and G)
will be grouped by the current locale's
thousands' separator character.
width-
An optional entry that consists of either
one or more decimal digits,
or an asterisk (*),
or an asterisk followed by one or more decimal digits and a $.
It specifies the minimum field width:
If the converted value has fewer characters than the field width,
it will be padded
(with space by default)
on the left or right
(see the above flags description)
to the field width.
.prec-
An optional entry that consists of a period (.)
that precedes either
zero or more decimal digits,
or an asterisk (*),
or an asterisk followed by one or more decimal digits and a $.
It specifies a value that depends on the fmt character:
a, A, e, E, f, F-
It specifies the number of fractional digits
(those after the decimal point character).
For the hexadecimal floating conversions
(a and A),
the number of fractional digits is just sufficient
to produce an exact representation of the value
(trailing zero digits are removed);
for the other conversions,
the default number of fractional digits is 6.
b, B, d, i, o, u, x, X-
It specifies the minimum number of digits to appear.
The default minimum number of digits is 1.
g, G-
It specifies the maximum number of significant digits.
The default number of significant digits is 6.
s, S-
It specifies the maximum number of bytes to output.
The default is to take all elements up to the null terminator
(the entire string).
If only a period is specified,
the precision is taken to be zero.
For other conversions,
the behavior is undefined.
size -
An optional hh, h, l (ell),ll, L,
j, t or z that specifies other than the default
argument type, depending on the fmt character:
a, A, e, E, f, F, g, G-
The default argument type is double;
an l is ignored for compatibility with the scanf functions
(a float arg will have been promoted to double);
an L or ll causes a long double arg to be converted.
b, B, o, u, x, X-
The default argument type is unsigned int;
an hh causes the unsigned int arg
to be narrowed to unsigned char before conversion;
an h causes the unsigned int arg
to be narrowed to unsigned short before conversion;
an l causes an unsigned long arg
to be converted; an L or ll causes an unsigned
long long arg to be converted.
c-
The default argument type is int
which is narrowed to unsigned char before output;
an l causes a wchar_t arg to be converted
(to a multibyte character).
lc is a synonym for C.
d, i-
The default argument type is int;
an hh causes the int arg
to be narrowed to signed char before conversion;
an h causes the int arg
to be narrowed to short before conversion;
an l causes a long arg to be converted;
n L or ll causes a long long arg to be converted.
n-
The default argument type is pointer to int;
an h changes it to be a pointer to short,
an l to pointer to long,
and L or ll to pointer to long long.
s-
The default argument type is pointer the first element of a character array;
an l changes it to be
a pointer to the first element of a wchar_t array.
ls is a synonym for S.
If a size appears other than in these combinations,
the behavior is undefined.
fmt-
A conversion character (described below) that
shows the type of conversion to be applied.
When a field width or precision includes an asterisk (*),
an int arg supplies the width or precision value,
and is said to be ``indirect''.
A negative indirect field width value is taken
as a - flag followed
by a positive field width.
A negative indirect precision value will be taken as zero.
When an indirect field width or precision includes a $,
the decimal digits similarly specify the number of the arg
that supplies the field width or precision.
Otherwise,
an int arg following the most recently
used arg will be accessed
for the indirect field width, or precision, or both,
in that order;
the arg to be converted
immediately follows these.
Thus,
if a conversion specification includes pos$
as well as a $-less indirect field width, or precision, or both,
pos is taken to be the number of the int arg
used for the first $-less indirection,
not the arg to be converted.
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 at least once,
in a consistent way,
in the format string.
The conversion characters and their meanings are:
a, A-
The floating arg is converted
to hexadecimal floating notation in the style
[-]0xh.hhhp±d.
The binary exponent of the converted value
(d)
is one or more decimal digits.
The number of fractional hexadecimal digits h
is equal to the precision.
If the precision is missing,
the result will have just enough digits
to represent the value exactly.
The value is rounded when fewer fractional digits is specified.
If the precision is zero and the # flag is not specified,
no decimal point character appears.
The single digit to the left of the
decimal point character is nonzero for normal values.
The A conversion specifier produces a value
with 0X and P instead of 0x and p.
b, B, o, u, x, X-
The unsigned integer arg is converted to
unsigned binary (b and B),
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 converted can be represented in fewer digits,
it will be expanded with leading zeros.
The default precision is 1.
The result of converting a zero value with a
precision of zero is no characters.
A j causes an uintmax_t argument to
be converted; a t causes an argument with the
unsigned type corresponding to ptrdiff_t to be
converted; a z causes a size_t
argument to be converted.
c-
The integer arg is converted to an unsigned char,
and the resulting character is output.
C, lc-
The wide character wchar_t arg
is converted into a multibyte character and output.
d, i-
The integer arg is converted to signed decimal.
The precision specifies the minimum number of digits to appear;
if the value being converted can be represented in fewer digits,
it will be expanded with leading zeros.
The default precision is 1.
The result of converting a zero value with a
precision of zero is no characters.
e, E-
The floating arg is converted to the style
[-]d.ddde±dd,
where there is one digit before the decimal point character
(which is nonzero if the argument is nonzero)
and the number of digits after it is equal to the precision.
If the precision is missing,
it is taken as 6;
if the precision is zero and the # flag is not specified,
no decimal point character appears.
The value is rounded to the appropriate number of digits.
The E conversion character will produce a number
with E instead of e introducing the exponent.
The exponent always contains at least two digits.
If the value is zero,
the exponent is zero.
f, F-
The floating arg is converted to decimal notation
in the style [-]ddd.ddd,
where the number of fractional digits
is equal to the precision specification.
If the precision is missing, it is taken as 6;
if the precision is zero and the # flag is not specified,
no decimal point character appears.
If a decimal point character appears,
at least one digit appears before it.
The value is rounded to the appropriate number of digits.
g, G-
The floating arg is converted in style e or f
(or in style E or F
in the case of a G conversion character),
with the precision specifying the number of significant digits.
If the precision is zero, it is taken as one.
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.
n-
The arg is taken to be a pointer to an integer
into which is written the
number of characters output so far by this call.
No argument is converted.
p-
The arg is taken to be a pointer to void.
The value of the pointer is converted to an
sequence of printable characters,
which matches those read by
the %p conversion of the
fscanf(S-osr5)
functions.
s-
The arg is taken to be
a pointer to the first element of an array of characters.
Characters from the array are written up to (but not including)
a terminating null character;
if a precision is specified,
no more than that many characters are written.
If a precision is not specified
or is greater than the size of the array,
the array must contain a terminating null character.
(A null pointer for arg will yield undefined results.)
S, ls-
The arg is taken to be
a pointer to the first element of an array of wchar_t.
Wide characters from the string are converted into
multibyte characters,
and output until a null wide character is encountered
or the number of bytes
given by the precision wide would be surpassed.
If the precision specification is missing,
it is taken to be infinite.
In no case will a partial multibyte character be output.
%-
Output a %; no argument is converted.
If the form of the conversion specification
does not match any of the above,
the results of the conversion are undefined.
Similarly,
the results are undefined if there are insufficient args for the format.
If the format is exhausted while args remain,
the excess args are ignored.
If a floating-point value represents an infinity,
the output is [±]``inf'',
where ``inf'' is
infinity or INFINITY
when the field width or precision is at least 8
and inf or INF otherwise,
the uppercase versions used only for a capitol conversion character.
Output of the sign follows the rules described above.
If a floating-point value has
the internal representation for a NaN (not-a-number),
the output is [±]nan[(m)].
Depending on the conversion character,
``nan'' is similarly either nan or NAN.
If the represented NaN matches the architecture's default,
no (``m'') will be output.
Otherwise ``m'' represents the bits
from the significand
in hexadecimal with abcdef or ABCDEF used,
depending on the case of the conversion character.
Output of the sign follows the rules described above.
Otherwise,
the locale's decimal point character will be
used to introduce the fractional digits
of a floating-point value.
A nonexistent or small field width does not
cause truncation of a field;
if the result of a conversion is wider than the field width,
the field is expanded to contain the conversion result.
Characters generated on streams
(stdout or strm)
are printed as if the putc
function had been called repeatedly.
Return values
These functions return the number of characters transmitted
(not counting the terminating null character for
sprintf, vsprintf, snprintf and vsnprintf),
or return a negative value if an error was encountered.
The functions fprintf, printf, vfprintf,
and vprintf fail
if either the stream is unbuffered or the
stream's buffer needed to be flushed and an attempt was made
to write at or beyond the offset maximum.
Usage
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 to 5 decimal places:
printf("pi = %.5f", 4 * atan(1.0));
The following two calls to printf
both produce the same result of 10 10 00300 10:
printf("%d %1$d %.*d %1$d", 10, 5, 300);
printf("%d %1$d %3$.*2$d %1$d", 10, 5, 300);
The following shows a simple use of vfprintf,
a function that writes formatted output to stderr by default.
#include <stdarg.h>
#include <stdio.h>
void errprintf(FILE *fp, const char *fmt, ...)
{
va_list ap;
va_start(ap, fmt);
if (fp == 0)
fp = stderr;
(void)vfprintf(fp, fmt, ap);
va_end(ap);
}
See also
abort(S-osr5),
ecvt(S-osr5),
exit(S-osr5),
fscanf(S-osr5),
fwprintf(S-osr5),
fwscanf(S-osr5),
lseek(S-osr5),
putc(S-osr5),
setlocale(S-osr5),
varargs(S-osr5),
write(S-osr5)
Standards conformance
fprintf(S-osr5),
printf(S-osr5)
and
sprintf(S-osr5)
are conformant with:
X/Open Portability Guide, Issue 3, 1989
;
ANSI X3.159-1989 Programming Language -- C
;
Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2)
;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1)
;
and
NIST FIPS 151-1
.
vfprintf(S-osr5),
vprintf(S-osr5),
and
vsprintf(S-osr5)
are conformant with
:
X/Open Portability Guide, Issue 3, 1989
;
and
ANSI X3.159-1989 Programming Language -- C
.
snprintf(S-osr5)
is not part of any currently supported standard;
it was developed by UNIX System Laboratories, Inc. and
is maintained by The SCO Group.
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 -- 02 June 2005