1PRINTF(3) 386BSD Programmer's Manual PRINTF(3) 2 3NNAAMMEE 4 pprriinnttff, ffpprriinnttff, sspprriinnttff, ssnnpprriinnttff, vvpprriinnttff, vvffpprriinnttff,, vvsspprriinnttff, 5 vvssnnpprriinnttff - formatted output conversion 6 7SSYYNNOOPPSSIISS 8 ##iinncclluuddee <<ssttddiioo..hh>> 9 10 _i_n_t 11 pprriinnttff(_c_o_n_s_t _c_h_a_r *_f_o_r_m_a_t, ...) 12 13 _i_n_t 14 ffpprriinnttff(_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, ...) 15 16 _i_n_t 17 sspprriinnttff(_c_h_a_r *_s_t_r, _c_o_n_s_t _c_h_a_r *_f_o_r_m_a_t, ...) 18 19 _i_n_t 20 ssnnpprriinnttff(_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, ...) 21 22 ##iinncclluuddee <<ssttddaarrgg..hh>> 23 24 _i_n_t 25 vvpprriinnttff(_c_o_n_s_t _c_h_a_r *_f_o_r_m_a_t, _v_a__l_i_s_t _a_p) 26 27 _i_n_t 28 vvffpprriinnttff(_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) 29 30 _i_n_t 31 vvsspprriinnttff(_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) 32 33 _i_n_t 34 vvssnnpprriinnttff(_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) 35 36DDEESSCCRRIIPPTTIIOONN 37 The pprriinnttff() family of functions produces output according to a _f_o_r_m_a_t as 38 described below. PPrriinnttff() and vvpprriinnttff() write output to _s_t_d_o_u_t, the 39 standard output stream; ffpprriinnttff() and vvffpprriinnttff() write output to the 40 given output _s_t_r_e_a_m; sspprriinnttff(), ssnnpprriinnttff(), vvsspprriinnttff(), and vvssnnpprriinnttff() 41 write to the character string _s_t_r. These functions write the output under 42 the control of a _f_o_r_m_a_t string that specifies how subsequent arguments 43 (or arguments accessed via the variable-length argument facilities of 44 stdarg(3)) are converted for output. These functions return the number 45 of characters printed (not including the trailing `\0' used to end output 46 to strings). SSnnpprriinnttff() and vvssnnpprriinnttff() will write at most _s_i_z_e-1 of the 47 characters printed into the output string (the _s_i_z_e'th character then 48 gets the terminating `\0'); if the return value is greater than or equal 49 to the _s_i_z_e argument, the string was too short and some of the printed 50 characters were discarded. SSpprriinnttff() and vvsspprriinnttff() effectively assume 51 an infinte _s_i_z_e. 52 53 The format string is composed of zero or more directives: ordinary 54 characters (not %%), which are copied unchanged to the output stream; and 55 conversion specifications, each of which results in fetching zero or more 56 subsequent arguments. Each conversion specification is introduced by the 57 character %%. The arguments must correspond properly (after type 58 promotion) with the conversion specifier. After the %%, the following 59 appear in sequence: 60 61 oo Zero or more of the following flags: 62 63 -- a ## character specifying that the value should be converted 64 to an ``alternate form''. For cc, dd, ii, nn, pp, ss, and uu, 65 conversions, this option has no effect. For oo conversions, 66 the precision of the number is increased to force the first 67 character of the output string to a zero (except if a zero 68 value is printed with an explicit precision of zero). For 69 xx and XX conversions, a non-zero result has the string `0x' 70 (or `0X' for XX conversions) prepended to it. For ee, EE, ff, 71 gg, and GG, conversions, the result will always contain a 72 decimal point, even if no digits follow it (normally, a 73 decimal point appears in the results of those conversions 74 only if a digit follows). For gg and GG conversions, 75 trailing zeros are not removed from the result as they 76 would otherwise be. 77 78 -- A zero `00' character specifying zero padding. For all 79 conversions except nn, the converted value is padded on the 80 left with zeros rather than blanks. If a precision is 81 given with a numeric conversion (Mc d, ii, oo, uu, ii, xx, and 82 XX), the `00' flag is ignored. 83 84 -- A negative field width flag `--' indicates the converted 85 value is to be left adjusted on the field boundary. Except 86 for nn conversions, the converted value is padded on the 87 right with blanks, rather than on the left with blanks or 88 zeros. A `--' overrides a `00' if both are given. 89 90 -- A space, specifying that a blank should be left before a 91 positive number produced by a signed conversion (dd, ee, EE, 92 ff, gg, GG, or ii). 93 94 -- a `++' character specifying that a sign always be placed 95 before a number produced by a signed conversion. A `++' 96 overrides a space if both are used. 97 98 oo An optional decimal digit string specifying a minimum field width. 99 If the converted value has fewer characters than the field width, it 100 will be padded with spaces on the left (or right, if the left- 101 adjustment flag has been given) to fill out the field width. 102 103 oo An optional precision, in the form of a period `..' followed by an 104 optional digit string. If the digit string is omitted, the precision 105 is taken as zero. This gives the minimum number of digits to appear 106 for dd, ii, oo, uu, xx, and XX conversions, the number of digits to appear 107 after the decimal-point for ee, EE, and ff conversions, the maximum 108 number of significant digits for gg and GG conversions, or the maximum 109 number of characters to be printed from a string for ss conversions. 110 111 oo The optional character hh, specifying that a following dd, ii, oo, uu, xx, 112 or XX 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 113 argument, or that a following nn conversion corresponds to a pointer 114 to a _s_h_o_r_t _i_n_t argument. 115 116 oo The optional character ll (ell) specifying that a following dd, ii, oo, 117 uu, xx, or XX conversion applies to a pointer to a _l_o_n_g _i_n_t or _u_n_s_i_g_n_e_d 118 _l_o_n_g _i_n_t argument, or that a following nn conversion corresponds to a 119 pointer to a _l_o_n_g _i_n_t argument. 120 121 oo The character LL specifying that a following ee, EE, ff, gg, or GG 122 conversion corresponds to a _l_o_n_g _d_o_u_b_l_e argument (but note that long 123 double values are not currently supported by the VAX and Tahoe 124 compilers). 125 126 oo A character that specifies the type of conversion to be applied. 127 128 A field width or precision, or both, may be indicated by an asterisk `*' 129 instead of a digit string. In this case, an _i_n_t argument supplies the 130 field width or precision. A negative field width is treated as a left 131 adjustment flag followed by a positive field width; a negative precision 132 is treated as though it were missing. 133 134 The conversion specifiers and their meanings are: 135 136 ddiioouuxxXX The _i_n_t (or appropriate variant) argument is converted to signed 137 decimal (dd and ii), unsigned octal (oo), unsigned decimal (uu), or 138 unsigned hexadecimal (xx and XX) notation. The letters aabbccddeeff are 139 used for xx conversions; the letters AABBCCDDEEFF are used for 140 conversions. The precision, if any, gives the minimum number of 141 digits that must appear; if the converted value requires fewer 142 digits, it is padded on the left with zeros. 143 144 DDOOUU The _l_o_n_g _i_n_t argument is converted to signed decimal, unsigned 145 octal, or unsigned decimal, as if the format had been lldd, lloo, or 146 lluu respectively. These conversion characters are deprecated, and 147 will eventually disappear. 148 149 eeEE The _d_o_u_b_l_e argument is rounded and converted in the style 150 [-]d..dddee+-dd where there is one digit before the decimal-point 151 character and the number of digits after it is equal to the 152 precision; if the precision is missing, it is taken as 6; if the 153 precision is zero, no decimal-point character appears. An EE 154 conversion uses the letter EE (rather than ee) to introduce the 155 exponent. The exponent always contains at least two digits; if 156 the value is zero, the exponent is 00. 157 158 ff The _d_o_u_b_l_e argument is rounded and converted to decimal notation 159 in the style [-]ddd..ddd, where the number of digits after the 160 decimal-point character is equal to the precision specification. 161 If the precision is missing, it is taken as 6; if the precision 162 is explicitly zero, no decimal-point character appears. If a 163 decimal point appears, at least one digit appears before it. 164 165 gg The _d_o_u_b_l_e argument is converted in style ff or ee (or EE for GG 166 conversions). The precision specifies the number of significant 167 digits. If the precision is missing, 6 digits are given; if the 168 precision is zero, it is treated as 1. Style ee is used if the 169 exponent from its conversion is less than -4 or greater than or 170 equal to the precision. Trailing zeros are removed from the 171 fractional part of the result; a decimal point appears only if it 172 is followed by at least one digit. 173 174 cc The _i_n_t argument is converted to an _u_n_s_i_g_n_e_d _c_h_a_r, and the 175 resulting character is written. 176 177 ss The ``_c_h_a_r *'' argument is expected to be a pointer to an array 178 of character type (pointer to a string). Characters from the 179 array are written up to (but not including) a terminating NUL 180 character; if a precision is specified, no more than the number 181 specified are written. If a precision is given, no null 182 character need be present; if the precision is not specified, or 183 is greater than the size of the array, the array must contain a 184 terminating NUL character. 185 186 pp The ``_v_o_i_d *'' pointer argument is printed in hexadecimal (as if 187 by `%#x' or `%#lx'). 188 189 nn The number of characters written so far is stored into the 190 integer indicated by the ``_i_n_t *'' (or variant) pointer argument. 191 No argument is converted. 192 193 %% A `%' is written. No argument is converted. The complete 194 conversion specification is `%%'. 195 196 In no case does a non-existent or small field width cause truncation of a 197 field; if the result of a conversion is wider than the field width, the 198 field is expanded to contain the conversion result. 199 200EEXXAAMMPPLLEESS 201 To print a date and time in the form `Sunday, July 3, 10:02', where 202 _w_e_e_k_d_a_y and _m_o_n_t_h are pointers to strings: 203 204 #include <stdio.h> 205 fprintf(stdout, "%s, %s %d, %.2d:%.2d\n", 206 weekday, month, day, hour, min); 207 208 To print pi to five decimal places: 209 210 #include <math.h> 211 #include <stdio.h> 212 fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0)); 213 214 To allocate a 128 byte string and print into it: 215 216 #include <stdio.h> 217 #include <stdlib.h> 218 #include <stdarg.h> 219 char *newfmt(const char *fmt, ...) 220 { 221 char *p; 222 va_list ap; 223 if ((p = malloc(128)) == NULL) 224 return (NULL); 225 va_start(ap, fmt); 226 (void) vsnprintf(p, 128, fmt, ap); 227 va_end(ap); 228 return (p); 229 } 230 231SSEEEE AALLSSOO 232 printf(1), scanf(3) 233 234SSTTAANNDDAARRDDSS 235 The ffpprriinnttff(), pprriinnttff(), sspprriinnttff(), vvpprriinnttff(), vvffpprriinnttff(), and vvsspprriinnttff() 236 functions conform to ANSI C3.159-1989 (``ANSI C''). 237 238HHIISSTTOORRYY 239 The functions ssnnpprriinnttff() and vvssnnpprriinnttff() are new to this release. 240 241BBUUGGSS 242 The conversion formats %%DD, %%OO, and %%UU are not standard and are provided 243 only for backward compatibility. The effect of padding the %%pp format 244 with zeros (either by the `00' flag or by specifying a precision), and the 245 benign effect (i.e., none) of the `##' flag on %%nn and %%pp conversions, as 246 well as other nonsensical combinations such as %%LLdd, are not standard; 247 such combinations should be avoided. 248 249 Because sspprriinnttff() and vvsspprriinnttff() assume an infinitely long string, 250 callers must be careful not to overflow the actual space; this is often 251 impossible to assure. For safety, programmers should use the ssnnpprriinnttff() 252 interface instead. Unfortunately, this interface is not portable. 253 254BSD Experimental July 30, 1991 4 255 256 257 258 259 260 261 262 263 264 265