4.3BSD-Reno/share/man/cat3/vsprintf.0
PRINTF(3) 1987 PRINTF(3)
NNAAMMEE
fprintf, printf, sprintf, vprintf, vfprintf, vsprintf - for-
matted output conversion
SSYYNNOOPPSSIISS
##iinncclluuddee <<ssttddiioo..hh>>
pprriinnttff((ffoorrmmaatt [,, arg ] ... ))
cchhaarr **ffoorrmmaatt;;
ffpprriinnttff((ssttrreeaamm,, ffoorrmmaatt [,, arg ] ... ))
FFIILLEE **ssttrreeaamm;;
cchhaarr **ffoorrmmaatt;;
sspprriinnttff((ss,, ffoorrmmaatt [,, arg ] ... ))
cchhaarr **ss,, **ffoorrmmaatt;;
##iinncclluuddee <<vvaarraarrggss..hh>>
vvpprriinnttff((ffoorrmmaatt,, aarrggss))
cchhaarr **ffoorrmmaatt;;
vvaa__lliisstt aarrggss;;
vvffpprriinnttff((ssttrreeaamm,, ffoorrmmaatt,, aarrggss))
FFIILLEE **ssttrreeaamm;;
cchhaarr **ffoorrmmaatt;;
vvaa__lliisstt aarrggss;;
vvsspprriinnttff((ss,, ffoorrmmaatt,, aarrggss))
cchhaarr **ss,, **ffoorrmmaatt;;
vvaa__lliisstt aarrggss;;
DDEESSCCRRIIPPTTIIOONN
_P_r_i_n_t_f and _v_p_r_i_n_t_f place output on the standard output
stream ssttddoouutt. _F_p_r_i_n_t_f and _v_f_p_r_i_n_t_f place output on the
named output _s_t_r_e_a_m. _S_p_r_i_n_t_f and _v_s_p_r_i_n_t_f copy into the
string _s, followed by the character `\0'. _P_r_i_n_t_f, _f_p_r_i_n_t_f,
and _s_p_r_i_n_t_f take variadic argument lists directly, while
_v_p_r_i_n_t_f, _v_f_p_r_i_n_t_f, and _v_s_p_r_i_n_t_f use the variable-length
argument facilities of _v_a_r_a_r_g_s(3) and hence may be called
indirectly (see examples).
Each function converts, formats, and prints its arguments
after the _f_o_r_m_a_t under control of the _f_o_r_m_a_t argument; each
returns the the total number of characters printed (not
including the trailing `\0' in _s_p_r_i_n_t_f and _v_s_p_r_i_n_t_f). _F_o_r_-
_m_a_t is a character string which contains two types of
objects: plain characters, which are simply copied to the
output stream, and conversion specifications, each of which
causes conversion and printing of the next successive _a_r_g.
Each conversion specification is introduced by the percent
character (``%''). The remainder of the conversion
Printed 7/27/90 October 1
PRINTF(3) 1987 PRINTF(3)
specification includes, in the following order,
oo++ Zero or more of the following flags:
oo++ a `#' character specifying that the value should
be converted to an ``alternate form''. For cc, dd,
ii, nn, pp, ss, and uu, conversions, this option has no
effect. For oo conversions, the precision of the
number is increased to force the first character
of the output string to a zero (except if a zero
value is printed with an explicit precision of
zero). For xx and XX conversions, a non-zero result
has the string 00xx (or 00XX for XX conversions)
prepended to it. For ee, EE, ff, gg, and GG, conver-
sions, the result will always contain a decimal
point, even if no digits follow it (normally, a
decimal point appears in the results of those
conversions only if a digit follows). For gg and GG
conversions, trailing zeros are not removed from
the result as they would otherwise be.
oo++ A zero ``0'' character specifying zero padding.
For all conversions except nn, the converted value
is padded on the left with zeros rather than
blanks. If a precision is given with a numeric
conversion ( dd, ii, oo, uu, ii, xx, and XX), the ``0''
flag is ignored.
oo++ A minus sign (``-'') specifying left adjustment of
the converted value in the indicated field.
Except for nn conversions, the converted value is
padded on the right with blanks, rather than on
the left with blanks or zeros. A ``-'' overrides
a ``0'' if both are given.
oo++ A space, specifying that a blank should be left
before a positive number produced by a signed
conversion ( dd, ee, EE, ff, gg, GG, or ii).
oo++ a `+' character specifying that a sign always be
placed before a number produced by a signed
conversion. A ``+'' overrides a space if both are
used.
oo++ An optional digit string specifying a 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-adjustment flag is used) to make up the field
width.
oo++ An optional precision, in the form of a period (``.'')
followed by an optional digit string. If the digit
Printed 7/27/90 October 2
PRINTF(3) 1987 PRINTF(3)
string is omitted, the precision is taken as zero.
This gives the minimum number of digits to appear for
dd, ii, oo, uu, xx, and XX conversions, the number of digits
to appear after the decimal point for ee, EE, and ff
conversions, the maximum number of significant digits
for gg and GG conversions, or the maximum number of char-
acters to be printed from a string for ss conversions.
oo++ The character hh, specifying that a following dd, ii, oo,
uu, xx, or XX conversion corresponds to a sshhoorrtt iinntt or
uunnssiiggnneedd sshhoorrtt iinntt argument, or that a following nn
conversion corresponds to a pointer to a sshhoorrtt iinntt
argument.
oo++ the character ll (ell) specifying that a following dd, ii,
oo, uu, xx, or XX conversion corresponds to a lloonngg iinntt or
uunnssiiggnneedd lloonngg iinntt argument, or that a following nn
conversion corresponds to a pointer to a lloonngg iinntt argu-
ment.
oo++ The character LL specifying that a following ee, EE, ff, gg,
or GG conversion corresponds to a lloonngg ddoouubbllee argument
(but note that long double values are not currently
supported by the VAX and Tahoe compilers).
oo++ A character which indicates the type of conversion to
be applied.
A field width or precision may be an asterisk (``*'')
instead of a digit string. In this case an iinntt argument
supplies the value. A negative field width is treated as a
left adjustment flag followed by a positive field width; a
negative precision is treated as though it were missing.
The conversion characters and their meanings are:
ddiioouuxxXX
The iinntt (or appropriate variant) argument is converted
to signed decimal (dd and ii), unsigned octal (oo),
unsigned decimal (uu), or unsigned hexadecimal (xx and XX)
notation respectively. The letters aabbccddeeff are used for
xx conversions; the letters AABBCCDDEEFF are used for XX
conversions. The precision, if any, gives the minimum
number of digits that must appear; if the converted
value requires fewer digits, it is padded on the left
with zeros.
DDOOUU The lloonngg iinntt argument is converted to signed decimal,
unsigned octal, or unsigned decimal, as if the format
had been lldd, lloo, or lluu respectively. These conversion
characters are deprecated, and will eventually disap-
pear.
Printed 7/27/90 October 3
PRINTF(3) 1987 PRINTF(3)
eeEE The ddoouubbllee argument is rounded and converted in the
style `[--]d..dddee+_dd' where there is one digit before
the decimal point and the number after is equal to
the precision specification for the argument. If
the precision is missing, 6 digits are given; if the
precision is explicitly zero, no decimal point
appears. An EE conversion uses the letter EE (rather
than ee) to introduce the exponent. The exponent
always contains at least two digits; if the value is
zero, the exponent is 00.
ff The ddoouubbllee argument is rounded and converted to
decimal notation in the style `[--]ddd.ddd' where the
number of digits after the decimal point is equal to
the precision. If the precision is missing, 6
digits are given; if the precision is explicitly 0,
no digits and no decimal point are printed. If a
decimal point appears, at least one digit appears
before it.
gg The ddoouubbllee argument is printed in style ff or ee (or EE
for GG conversions). The precision specifies the
number of significant digits. If the precision is
missing, 6 digits are given; if the precision is
zero, it is treated as 1. Style ee is used if the
exponent from its 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 appears only if it is fol-
lowed by at least one digit.
cc The iinntt argument is converted to an uunnssiiggnneedd cchhaarr ,,
and the resulting character is printed.
ss The cchhaarr ** argument is taken to be a string (charac-
ter pointer). Characters from the string are
printed until a null character is reached, or until
the number of characters indicated by the precision
have been printed, whichever occurs first; if a pre-
cision is given, no null character need be present.
pp The vvooiidd ** pointer argument is printed in hexade-
cimal (as if by ``%x'' or ``%lx'').
nn The number of characters written so far is stored
into the integer indicated by the iinntt ** (or variant)
pointer argument. No argument is converted.
%% Prints a `%'; no argument is converted.
In no case does a non-existent or small field width cause
truncation of a field; if the result of a conversion is
Printed 7/27/90 October 4
PRINTF(3) 1987 PRINTF(3)
wider than the field width, the field is expanded to contain
it. Similarly, padding takes place only if the specified
field width exceeds the actual width.
EEXXAAMMPPLLEESS
To print a date and time in the form `Sunday, July 3,
10:02', where _w_e_e_k_d_a_y and _m_o_n_t_h are pointers to null-
terminated strings:
printf("%s, %s %d, %02d:%.2d", weekday, month, day,
hour, min);
To print pi to 5 decimals:
printf("pi = %.5f", 4*atan(1.0));
To allocate a 128 byte string and print into it:
#include <stdio.h>
#include <varargs.h>
char *newfmt(va_alist)
va_dcl
{
char *p, *malloc(), fmt;
va_list ap;
if ((p = malloc(128)) == NULL)
return (NULL);
va_start(ap);
fmt = va_arg(ap, char *);
(void) vsprintf(p, fmt, ap);
va_end(ap);
return (p);
}
SSEEEE AALLSSOO
putc(3), scanf(3)
BBUUGGSS
The conversion formats ``%D'', ``%O'', and ``%U'' are not
standard and are provided only for backward compatibility.
The effect of padding the ``%p'' format with zeros (either
by the ``0'' flag or by specifying a precision), and the
benign effect (i.e., none) of the ``#'' flag on ``%n'' and
``%p'' conversions, as well as other nonsensical combina-
tions such as ``%Ld'', are not standard; such combinations
should be avoided.
Printed 7/27/90 October 5