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