Commit | Line | Data |
---|---|---|
8bb980a3 C |
1 | PRINTF(3) BSD Programmer's Manual PRINTF(3) |
2 | ||
3 | N\bNA\bAM\bME\bE | |
4 | p\bpr\bri\bin\bnt\btf\bf, f\bfp\bpr\bri\bin\bnt\btf\bf, s\bsp\bpr\bri\bin\bnt\btf\bf, s\bsn\bnp\bpr\bri\bin\bnt\btf\bf, v\bvp\bpr\bri\bin\bnt\btf\bf, v\bvf\bfp\bpr\bri\bin\bnt\btf\bf,\b, v\bvs\bsp\bpr\bri\bin\bnt\btf\bf, | |
5 | v\bvs\bsn\bnp\bpr\bri\bin\bnt\btf\bf - formatted output conversion | |
6 | ||
7 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS | |
8 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdi\bio\bo.\b.h\bh>\b> | |
9 | ||
10 | _\bi_\bn_\bt | |
11 | p\bpr\bri\bin\bnt\btf\bf(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bo_\br_\bm_\ba_\bt, _\b._\b._\b.); | |
12 | ||
13 | _\bi_\bn_\bt | |
14 | f\bfp\bpr\bri\bin\bnt\btf\bf(_\bF_\bI_\bL_\bE _\b*_\bs_\bt_\br_\be_\ba_\bm, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bo_\br_\bm_\ba_\bt, _\b._\b._\b.); | |
15 | ||
16 | _\bi_\bn_\bt | |
17 | s\bsp\bpr\bri\bin\bnt\btf\bf(_\bc_\bh_\ba_\br _\b*_\bs_\bt_\br, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bo_\br_\bm_\ba_\bt, _\b._\b._\b.); | |
18 | ||
19 | _\bi_\bn_\bt | |
20 | s\bsn\bnp\bpr\bri\bin\bnt\btf\bf(_\bc_\bh_\ba_\br _\b*_\bs_\bt_\br, _\bs_\bi_\bz_\be_\b__\bt _\bs_\bi_\bz_\be, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bo_\br_\bm_\ba_\bt, _\b._\b._\b.); | |
21 | ||
22 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bda\bar\brg\bg.\b.h\bh>\b> | |
23 | ||
24 | _\bi_\bn_\bt | |
25 | v\bvp\bpr\bri\bin\bnt\btf\bf(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bo_\br_\bm_\ba_\bt, _\bv_\ba_\b__\bl_\bi_\bs_\bt _\ba_\bp); | |
26 | ||
27 | _\bi_\bn_\bt | |
28 | v\bvf\bfp\bpr\bri\bin\bnt\btf\bf(_\bF_\bI_\bL_\bE _\b*_\bs_\bt_\br_\be_\ba_\bm, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bo_\br_\bm_\ba_\bt, _\bv_\ba_\b__\bl_\bi_\bs_\bt _\ba_\bp); | |
29 | ||
30 | _\bi_\bn_\bt | |
31 | v\bvs\bsp\bpr\bri\bin\bnt\btf\bf(_\bc_\bh_\ba_\br _\b*_\bs_\bt_\br, _\bc_\bh_\ba_\br _\b*_\bf_\bo_\br_\bm_\ba_\bt, _\bv_\ba_\b__\bl_\bi_\bs_\bt _\ba_\bp); | |
32 | ||
33 | _\bi_\bn_\bt | |
34 | v\bvs\bsn\bnp\bpr\bri\bin\bnt\btf\bf(_\bc_\bh_\ba_\br _\b*_\bs_\bt_\br, _\bs_\bi_\bz_\be_\b__\bt _\bs_\bi_\bz_\be, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bo_\br_\bm_\ba_\bt, _\bv_\ba_\b__\bl_\bi_\bs_\bt _\ba_\bp); | |
35 | ||
36 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN | |
37 | The p\bpr\bri\bin\bnt\btf\bf() family of functions produces output according to a _\bf_\bo_\br_\bm_\ba_\bt as | |
38 | described below. P\bPr\bri\bin\bnt\btf\bf() and v\bvp\bpr\bri\bin\bnt\btf\bf() write output to _\bs_\bt_\bd_\bo_\bu_\bt_\b, the | |
39 | standard output stream; f\bfp\bpr\bri\bin\bnt\btf\bf() and v\bvf\bfp\bpr\bri\bin\bnt\btf\bf() write output to the giv- | |
40 | en output _\bs_\bt_\br_\be_\ba_\bm; s\bsp\bpr\bri\bin\bnt\btf\bf(), s\bsn\bnp\bpr\bri\bin\bnt\btf\bf(), v\bvs\bsp\bpr\bri\bin\bnt\btf\bf(), and v\bvs\bsn\bnp\bpr\bri\bin\bnt\btf\bf() | |
41 | write to the character string _\bs_\bt_\br. These functions write the output under | |
42 | the control of a _\bf_\bo_\br_\bm_\ba_\bt 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). S\bSn\bnp\bpr\bri\bin\bnt\btf\bf() and v\bvs\bsn\bnp\bpr\bri\bin\bnt\btf\bf() will write at most _\bs_\bi_\bz_\be-1 of the | |
47 | characters printed into the output string (the _\bs_\bi_\bz_\be'th character then | |
48 | gets the terminating `\0'); if the return value is greater than or equal | |
49 | to the _\bs_\bi_\bz_\be argument, the string was too short and some of the printed | |
50 | characters were discarded. S\bSp\bpr\bri\bin\bnt\btf\bf() and v\bvs\bsp\bpr\bri\bin\bnt\btf\bf() effectively assume | |
51 | an infinite _\bs_\bi_\bz_\be. | |
52 | ||
53 | The format string is composed of zero or more directives: ordinary char- | |
54 | acters (not %\b%), which are copied unchanged to the output stream; and con- | |
55 | version specifications, each of which results in fetching zero or more | |
56 | subsequent arguments. Each conversion specification is introduced by the | |
57 | character %\b%. The arguments must correspond properly (after type promo- | |
58 | tion) with the conversion specifier. After the %\b%, the following appear | |
59 | in sequence: | |
60 | ||
61 | +\b+\bo\bo Zero or more of the following flags: | |
62 | ||
63 | -\b- A #\b# character specifying that the value should be converted to an | |
64 | ``alternate form''. For c\bc, d\bd, i\bi, n\bn, p\bp, s\bs, and u\bu, conversions, | |
65 | this option has no effect. For o\bo conversions, the precision of | |
66 | the number is increased to force the first character of the out- | |
67 | put string to a zero (except if a zero value is printed with an | |
68 | explicit precision of zero). For x\bx and X\bX conversions, a non-zero | |
69 | result has the string `0x' (or `0X' for X\bX conversions) prepended | |
70 | to it. For e\be, E\bE, f\bf, g\bg, and G\bG, conversions, the result will al- | |
71 | ways contain a decimal point, even if no digits follow it (nor- | |
72 | mally, a decimal point appears in the results of those conver- | |
73 | sions only if a digit follows). For g\bg and G\bG conversions, trail- | |
74 | ing zeros are not removed from the result as they would otherwise | |
75 | be. | |
76 | ||
77 | -\b- A zero `0\b0' character specifying zero padding. For all conver- | |
78 | sions except n\bn, the converted value is padded on the left with | |
79 | zeros rather than blanks. If a precision is given with a numeric | |
80 | conversion (Mc d, i\bi, o\bo, u\bu, i\bi, x\bx, and X\bX), the `0\b0' flag is ignored. | |
81 | ||
82 | -\b- A negative field width flag `-\b-' indicates the converted value is | |
83 | to be left adjusted on the field boundary. Except for n\bn conver- | |
84 | sions, the converted value is padded on the right with blanks, | |
85 | rather than on the left with blanks or zeros. A `-\b-' overrides a | |
86 | `0\b0' if both are given. | |
87 | ||
88 | -\b- A space, specifying that a blank should be left before a positive | |
89 | number produced by a signed conversion (d\bd, e\be, E\bE, f\bf, g\bg, G\bG, or i\bi). | |
90 | ||
91 | -\b- A `+\b+' character specifying that a sign always be placed before a | |
92 | number produced by a signed conversion. A `+\b+' overrides a space | |
93 | if both are used. | |
94 | ||
95 | +\b+\bo\bo An optional decimal digit string specifying a minimum field width. | |
96 | If the converted value has fewer characters than the field width, it | |
97 | will be padded with spaces on the left (or right, if the left- | |
98 | adjustment flag has been given) to fill out the field width. | |
99 | ||
100 | +\b+\bo\bo An optional precision, in the form of a period `.\b.' followed by an op- | |
101 | tional digit string. If the digit string is omitted, the precision | |
102 | is taken as zero. This gives the minimum number of digits to appear | |
103 | for d\bd, i\bi, o\bo, u\bu, x\bx, and X\bX conversions, the number of digits to appear | |
104 | after the decimal-point for e\be, E\bE, and f\bf conversions, the maximum num- | |
105 | ber of significant digits for g\bg and G\bG conversions, or the maximum | |
106 | number of characters to be printed from a string for s\bs conversions. | |
107 | ||
108 | +\b+\bo\bo The optional character h\bh, specifying that a following d\bd, i\bi, o\bo, u\bu, x\bx, | |
109 | or X\bX conversion corresponds to a _\bs_\bh_\bo_\br_\bt _\bi_\bn_\bt or _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bs_\bh_\bo_\br_\bt _\bi_\bn_\bt ar- | |
110 | gument, or that a following n\bn conversion corresponds to a pointer to | |
111 | a _\bs_\bh_\bo_\br_\bt _\bi_\bn_\bt argument. | |
112 | ||
113 | +\b+\bo\bo The optional character l\bl (ell) specifying that a following d\bd, i\bi, o\bo, | |
114 | u\bu, x\bx, or X\bX conversion applies to a pointer to a _\bl_\bo_\bn_\bg _\bi_\bn_\bt or _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd | |
115 | _\bl_\bo_\bn_\bg _\bi_\bn_\bt argument, or that a following n\bn conversion corresponds to a | |
116 | pointer to a _\bl_\bo_\bn_\bg _\bi_\bn_\bt argument. | |
117 | ||
118 | +\b+\bo\bo The optional character q\bq, specifying that a following d\bd, i\bi, o\bo, u\bu, x\bx, | |
119 | or X\bX conversion corresponds to a _\bq_\bu_\ba_\bd _\bi_\bn_\bt or _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bq_\bu_\ba_\bd _\bi_\bn_\bt argu- | |
120 | ment, or that a following n\bn conversion corresponds to a pointer to a | |
121 | _\bq_\bu_\ba_\bd _\bi_\bn_\bt argument. | |
122 | ||
123 | +\b+\bo\bo The character L\bL specifying that a following e\be, E\bE, f\bf, g\bg, or G\bG conver- | |
124 | sion corresponds to a _\bl_\bo_\bn_\bg _\bd_\bo_\bu_\bb_\bl_\be argument (but note that long double | |
125 | values are not currently supported by the VAX and Tahoe compilers). | |
126 | ||
127 | +\b+\bo\bo A character that specifies the type of conversion to be applied. | |
128 | ||
129 | A field width or precision, or both, may be indicated by an asterisk `*' | |
130 | instead of a digit string. In this case, an _\bi_\bn_\bt argument supplies the | |
131 | field width or precision. A negative field width is treated as a left | |
132 | adjustment flag followed by a positive field width; a negative precision | |
133 | is treated as though it were missing. | |
134 | ||
135 | The conversion specifiers and their meanings are: | |
136 | ||
137 | d\bdi\bio\bou\bux\bxX\bX The _\bi_\bn_\bt (or appropriate variant) argument is converted to signed | |
138 | decimal (d\bd and i\bi), unsigned octal (o\bo), unsigned decimal (u\bu), or | |
139 | unsigned hexadecimal (x\bx and X\bX) notation. The letters a\bab\bbc\bcd\bde\bef\bf are | |
140 | used for x\bx conversions; the letters A\bAB\bBC\bCD\bDE\bEF\bF are used for conver- | |
141 | sions. The precision, if any, gives the minimum number of digits | |
142 | that must appear; if the converted value requires fewer digits, | |
143 | it is padded on the left with zeros. | |
144 | ||
145 | D\bDO\bOU\bU The _\bl_\bo_\bn_\bg _\bi_\bn_\bt argument is converted to signed decimal, unsigned | |
146 | octal, or unsigned decimal, as if the format had been l\bld\bd, l\blo\bo, or | |
147 | l\blu\bu respectively. These conversion characters are deprecated, and | |
148 | will eventually disappear. | |
149 | ||
150 | e\beE\bE The _\bd_\bo_\bu_\bb_\bl_\be argument is rounded and converted in the style | |
151 | [-]d.\b.ddde\be+-dd where there is one digit before the decimal-point | |
152 | character and the number of digits after it is equal to the pre- | |
153 | cision; if the precision is missing, it is taken as 6; if the | |
154 | precision is zero, no decimal-point character appears. An E\bE con- | |
155 | version uses the letter E\bE (rather than e\be) to introduce the expo- | |
156 | nent. The exponent always contains at least two digits; if the | |
157 | value is zero, the exponent is 00. | |
158 | ||
159 | f\bf The _\bd_\bo_\bu_\bb_\bl_\be argument is rounded and converted to decimal notation | |
160 | in the style [-]ddd.\b.ddd, where the number of digits after the | |
161 | decimal-point character is equal to the precision specification. | |
162 | If the precision is missing, it is taken as 6; if the precision | |
163 | is explicitly zero, no decimal-point character appears. If a | |
164 | decimal point appears, at least one digit appears before it. | |
165 | ||
166 | g\bg The _\bd_\bo_\bu_\bb_\bl_\be argument is converted in style f\bf or e\be (or E\bE for G\bG con- | |
167 | versions). The precision specifies the number of significant | |
168 | digits. If the precision is missing, 6 digits are given; if the | |
169 | precision is zero, it is treated as 1. Style e\be is used if the | |
170 | exponent from its conversion is less than -4 or greater than or | |
171 | equal to the precision. Trailing zeros are removed from the | |
172 | fractional part of the result; a decimal point appears only if it | |
173 | is followed by at least one digit. | |
174 | ||
175 | c\bc The _\bi_\bn_\bt argument is converted to an _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bc_\bh_\ba_\br, and the re- | |
176 | sulting character is written. | |
177 | ||
178 | s\bs The ``_\bc_\bh_\ba_\br _\b*'' argument is expected to be a pointer to an array | |
179 | of character type (pointer to a string). Characters from the ar- | |
180 | ray are written up to (but not including) a terminating NUL char- | |
181 | acter; if a precision is specified, no more than the number spec- | |
182 | ified are written. If a precision is given, no null character | |
183 | need be present; if the precision is not specified, or is greater | |
184 | than the size of the array, the array must contain a terminating | |
185 | NUL character. | |
186 | ||
187 | p\bp The ``_\bv_\bo_\bi_\bd _\b*'' pointer argument is printed in hexadecimal (as if | |
188 | by `%#x' or `%#lx'). | |
189 | ||
190 | n\bn The number of characters written so far is stored into the inte- | |
191 | ger indicated by the ``_\bi_\bn_\bt _\b*'' (or variant) pointer argument. No | |
192 | argument is converted. | |
193 | ||
194 | %\b% A `%' is written. No argument is converted. The complete conver- | |
195 | sion specification is `%%'. | |
196 | ||
197 | ||
198 | In no case does a non-existent or small field width cause truncation of a | |
199 | field; if the result of a conversion is wider than the field width, the | |
200 | field is expanded to contain the conversion result. | |
201 | ||
202 | E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS | |
203 | To print a date and time in the form `Sunday, July 3, 10:02', where | |
204 | _\bw_\be_\be_\bk_\bd_\ba_\by and _\bm_\bo_\bn_\bt_\bh are pointers to strings: | |
205 | ||
206 | #include <stdio.h> | |
207 | fprintf(stdout, "%s, %s %d, %.2d:%.2d\n", | |
208 | weekday, month, day, hour, min); | |
209 | ||
210 | To print pi to five decimal places: | |
211 | ||
212 | #include <math.h> | |
213 | #include <stdio.h> | |
214 | fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0)); | |
215 | ||
216 | To allocate a 128 byte string and print into it: | |
217 | ||
218 | #include <stdio.h> | |
219 | #include <stdlib.h> | |
220 | #include <stdarg.h> | |
221 | char *newfmt(const char *fmt, ...) | |
222 | { | |
223 | char *p; | |
224 | va_list ap; | |
225 | if ((p = malloc(128)) == NULL) | |
226 | return (NULL); | |
227 | va_start(ap, fmt); | |
228 | (void) vsnprintf(p, 128, fmt, ap); | |
229 | va_end(ap); | |
230 | return (p); | |
231 | } | |
232 | ||
233 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO | |
234 | printf(1), scanf(3) | |
235 | ||
236 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS | |
237 | The f\bfp\bpr\bri\bin\bnt\btf\bf(), p\bpr\bri\bin\bnt\btf\bf(), s\bsp\bpr\bri\bin\bnt\btf\bf(), v\bvp\bpr\bri\bin\bnt\btf\bf(), v\bvf\bfp\bpr\bri\bin\bnt\btf\bf(), and v\bvs\bsp\bpr\bri\bin\bnt\btf\bf() | |
238 | functions conform to ANSI C X3.159-1989 (``ANSI C ''). | |
239 | ||
240 | H\bHI\bIS\bST\bTO\bOR\bRY\bY | |
241 | The functions s\bsn\bnp\bpr\bri\bin\bnt\btf\bf() and v\bvs\bsn\bnp\bpr\bri\bin\bnt\btf\bf() are new to this release. | |
242 | ||
243 | B\bBU\bUG\bGS\bS | |
244 | The conversion formats %\b%D\bD, %\b%O\bO, and %\b%U\bU are not standard and are provided | |
245 | only for backward compatibility. The effect of padding the %\b%p\bp format | |
246 | with zeros (either by the `0\b0' flag or by specifying a precision), and the | |
247 | benign effect (i.e., none) of the `#\b#' flag on %\b%n\bn and %\b%p\bp conversions, as | |
248 | well as other nonsensical combinations such as %\b%L\bLd\bd, are not standard; | |
249 | such combinations should be avoided. | |
250 | ||
251 | Because s\bsp\bpr\bri\bin\bnt\btf\bf() and v\bvs\bsp\bpr\bri\bin\bnt\btf\bf() assume an infinitely long string, | |
252 | callers must be careful not to overflow the actual space; this is often | |
253 | impossible to assure. For safety, programmers should use the s\bsn\bnp\bpr\bri\bin\bnt\btf\bf() | |
254 | interface instead. Unfortunately, this interface is not portable. | |
255 | ||
256 | 4.4BSD June 4, 1993 4 |