
PRINTF(3)                  UNIX Programmer's Manual                  PRINTF(3)

NNAAMMEE
     pprriinnttff, ffpprriinnttff, sspprriinnttff, ssnnpprriinnttff, vvpprriinnttff, vvffpprriinnttff,, vvsspprriinnttff,
     vvssnnpprriinnttff - formatted output conversion

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ssttddiioo..hh>>

     _i_n_t
     pprriinnttff(_c_o_n_s_t _c_h_a_r _*_f_o_r_m_a_t, _._._.)

     _i_n_t
     ffpprriinnttff(_F_I_L_E _*_s_t_r_e_a_m, _c_o_n_s_t _c_h_a_r _*_f_o_r_m_a_t, _._._.)

     _i_n_t
     sspprriinnttff(_c_h_a_r _*_s_t_r, _c_o_n_s_t _c_h_a_r _*_f_o_r_m_a_t, _._._.)

     _i_n_t
     ssnnpprriinnttff(_c_h_a_r _*_s_t_r, _s_i_z_e___t _s_i_z_e, _c_o_n_s_t _c_h_a_r _*_f_o_r_m_a_t, _._._.)

     ##iinncclluuddee <<ssttddaarrgg..hh>>

     _i_n_t
     vvpprriinnttff(_c_o_n_s_t _c_h_a_r _*_f_o_r_m_a_t, _v_a___l_i_s_t _a_p)

     _i_n_t
     vvffpprriinnttff(_F_I_L_E _*_s_t_r_e_a_m, _c_o_n_s_t _c_h_a_r _*_f_o_r_m_a_t, _v_a___l_i_s_t _a_p)

     _i_n_t
     vvsspprriinnttff(_c_h_a_r _*_s_t_r, _c_h_a_r _*_f_o_r_m_a_t, _v_a___l_i_s_t _a_p)

     _i_n_t
     vvssnnpprriinnttff(_c_h_a_r _*_s_t_r, _s_i_z_e___t _s_i_z_e, _c_o_n_s_t _c_h_a_r _*_f_o_r_m_a_t, _v_a___l_i_s_t _a_p)

DDEESSCCRRIIPPTTIIOONN
     The pprriinnttff() family of functions produces output according to a _f_o_r_m_a_t as
     described below.  PPrriinnttff() and vvpprriinnttff() write output to _s_t_d_o_u_t_, the
     standard output stream; ffpprriinnttff() and vvffpprriinnttff() write output to the giv-
     en output _s_t_r_e_a_m; sspprriinnttff(), ssnnpprriinnttff(), vvsspprriinnttff(), and vvssnnpprriinnttff()
     write to the character string _s_t_r. These functions write the output under
     the control of a _f_o_r_m_a_t string that specifies how subsequent arguments
     (or arguments accessed via the variable-length argument facilities of
     stdarg(3))  are converted for output.  These functions return the number
     of characters printed (not including the trailing `\0' used to end output
     to strings).  SSnnpprriinnttff() and vvssnnpprriinnttff() will write at most _s_i_z_e-1 of the
     characters printed into the output string (the _s_i_z_e'th character then
     gets the terminating `\0'); if the return value is greater than or equal
     to the _s_i_z_e argument, the string was too short and some of the printed
     characters were discarded.  SSpprriinnttff() and vvsspprriinnttff() effectively assume
     an infinte _s_i_z_e.

     The format string is composed of zero or more directives: ordinary char-
     acters (not %%), which are copied unchanged to the output stream; and con-
     version specifications, each of which results in fetching zero or more
     subsequent arguments.  Each conversion specification is introduced by the
     character %%. The arguments must correspond properly (after type promo-
     tion) with the conversion specifier.  After the %%, the following appear
     in sequence:

     oo   Zero or more of the following flags:

               --   a ## character specifying that the value should be converted
                   to an ``alternate form''.  For cc, dd, ii, nn, pp, ss, and uu,
                   conversions, this option has no effect.  For oo 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
                   xx and XX conversions, a non-zero result has the string `0x'
                   (or `0X' for XX conversions) prepended to it.  For ee, EE, ff,
                   gg, and GG, conversions, 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 gg and GG conversions, trail-
                   ing zeros are not removed from the result as they would
                   otherwise be.

               --   A zero `00' character specifying zero padding.  For all con-
                   versions except nn, the converted value is padded on the
                   left with zeros rather than blanks.  If a precision is giv-
                   en with a numeric conversion (Mc d, ii, oo, uu, ii, xx, and XX),
                   the `00' flag is ignored.

               --   A negative field width flag `--' indicates the converted
                   value is to be left adjusted on the field boundary.  Except
                   for nn conversions, the converted value is padded on the
                   right with blanks, rather than on the left with blanks or
                   zeros.  A `--' overrides a `00' if both are given.

               --   A space, specifying that a blank should be left before a
                   positive number produced by a signed conversion (dd, ee, EE,
                   ff, gg, GG, or ii).

               --   a `++' character specifying that a sign always be placed be-
                   fore a number produced by a signed conversion.  A `++' over-
                   rides a space if both are used.

     oo   An optional decimal digit string specifying a minimum field width.
         If the converted value has fewer characters than the field width, it
         will be padded with spaces on the left (or right, if the left-
         adjustment flag has been given) to fill out the field width.

     oo   An optional precision, in the form of a period `..' followed by an op-
         tional digit string.  If the digit string is omitted, the precision
         is taken as zero.  This gives the minimum number of digits to appear
         for dd, ii, oo, uu, xx, and XX conversions, the number of digits to appear
         after the decimal-point for ee, EE, and ff conversions, the maximum num-
         ber of significant digits for gg and GG conversions, or the maximum
         number of characters to be printed from a string for ss conversions.

     oo   The optional character hh, specifying that a following dd, ii, oo, uu, xx,
         or XX conversion corresponds to a _s_h_o_r_t _i_n_t or _u_n_s_i_g_n_e_d _s_h_o_r_t _i_n_t ar-
         gument, or that a following nn conversion corresponds to a pointer to
         a _s_h_o_r_t _i_n_t argument.

     oo   The optional character ll (ell) specifying that a following dd, ii, oo,
         uu, xx, or XX conversion applies to a pointer to a _l_o_n_g _i_n_t or _u_n_s_i_g_n_e_d
         _l_o_n_g _i_n_t argument, or that a following nn conversion corresponds to a
         pointer to a _l_o_n_g _i_n_t argument.

     oo   The character LL specifying that a following ee, EE, ff, gg, or GG conver-
         sion corresponds to a _l_o_n_g _d_o_u_b_l_e argument (but note that long double
         values are not currently supported by the VAX and Tahoe compilers).

     oo   A character that specifies the type of conversion to be applied.

     A field width or precision, or both, may be indicated by an asterisk `*'
     instead of a digit string.  In this case, an _i_n_t argument supplies the
     field width or precision.  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 specifiers and their meanings are:

     ddiioouuxxXX  The _i_n_t (or appropriate variant) argument is converted to signed
             decimal (dd and ii), unsigned octal (oo), unsigned decimal (uu), or
             unsigned hexadecimal (xx and XX) notation.  The letters aabbccddeeff are
             used for xx conversions; the letters AABBCCDDEEFF are used for conver-
             sions.  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.

     DDOOUU     The _l_o_n_g _i_n_t argument is converted to signed decimal, unsigned
             octal, or unsigned decimal, as if the format had been lldd, lloo, or
             lluu respectively.  These conversion characters are deprecated, and
             will eventually disappear.

     eeEE      The _d_o_u_b_l_e argument is rounded and converted in the style
             [-]d..dddee+-dd where there is one digit before the decimal-point
             character and the number of digits after it is equal to the pre-
             cision; if the precision is missing, it is taken as 6; if the
             precision is zero, no decimal-point character appears.  An EE con-
             version uses the letter EE (rather than ee) to introduce the expo-
             nent.  The exponent always contains at least two digits; if the
             value is zero, the exponent is 00.

     ff       The _d_o_u_b_l_e argument is rounded and converted to decimal notation
             in the style [-]ddd..ddd, where the number of digits after the
             decimal-point character is equal to the precision specification.
             If the precision is missing, it is taken as 6; if the precision
             is explicitly zero, no decimal-point character appears.  If a
             decimal point appears, at least one digit appears before it.

     gg       The _d_o_u_b_l_e argument is converted in style ff or ee (or EE for GG con-
             versions).  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 ee 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 followed by at least one digit.

     cc       The _i_n_t argument is converted to an _u_n_s_i_g_n_e_d _c_h_a_r, and the re-
             sulting character is written.

     ss       The ``_c_h_a_r _*'' argument is expected to be a pointer to an array
             of character type (pointer to a string).  Characters from the ar-
             ray are written up to (but not including) a terminating NUL char-
             acter; if a precision is specified, no more than the number spec-
             ified are written.  If a precision is given, no null character
             need be present; if the precision is not specified, or is greater
             than the size of the array, the array must contain a terminating
             NUL character.

     pp       The ``_v_o_i_d _*'' pointer argument is printed in hexadecimal (as if
             by `%#x' or `%#lx').

     nn       The number of characters written so far is stored into the inte-
             ger indicated by the ``_i_n_t _*'' (or variant) pointer argument.  No
             argument is converted.

     %%       A `%' is written. No argument is converted. The complete conver-
             sion specification is `%%'.

     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 expanded to contain the conversion result.

EEXXAAMMPPLLEESS
     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 strings:

           #include <stdio.h>
           fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
                   weekday, month, day, hour, min);

     To print pi to five decimal places:

           #include <math.h>
           #include <stdio.h>
           fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));

     To allocate a 128 byte string and print into it:

           #include <stdio.h>
           #include <stdlib.h>
           #include <stdarg.h>
           char *newfmt(const char *fmt, ...)
           {
                           char *p;
                           va_list ap;
                           if ((p = malloc(128)) == NULL)
                                   return (NULL);
                           va_start(ap, fmt);
                           (void) vsnprintf(p, 128, fmt, ap);
                           va_end(ap);
                           return (p);
           }

SSEEEE AALLSSOO
     printf(1),  scanf(3)

SSTTAANNDDAARRDDSS
     The ffpprriinnttff(), pprriinnttff(), sspprriinnttff(), vvpprriinnttff(), vvffpprriinnttff(), and vvsspprriinnttff()
     functions conform to ANSI C3.159-1989 (``ANSI C'').

HHIISSTTOORRYY
     The functions ssnnpprriinnttff() and vvssnnpprriinnttff() are new to this release.

BBUUGGSS
     The conversion formats %%DD, %%OO, and %%UU are not standard and are provided
     only for backward compatibility.  The effect of padding the %%pp format
     with zeros (either by the `00' flag or by specifying a precision), and the
     benign effect (i.e., none) of the `##' flag on %%nn and %%pp conversions, as
     well as other nonsensical combinations such as %%LLdd, are not standard;
     such combinations should be avoided.

     Because sspprriinnttff() and vvsspprriinnttff() assume an infinitely long string,
     callers must be careful not to overflow the actual space; this is often
     impossible to assure.  For safety, programmers should use the ssnnpprriinnttff()
     interface instead.  Unfortunately, this interface is not portable.

BSD Experimental                 July 30, 1991                               4










