Commit | Line | Data |
---|---|---|
e1ce5433 | 1 | .\" @(#)printf.3 6.1 (Berkeley) %G% |
c3ce85c3 | 2 | .\" |
e1ce5433 | 3 | .TH PRINTF 3S "" |
c3ce85c3 KM |
4 | .AT 3 |
5 | .SH NAME | |
6 | printf, fprintf, sprintf \- formatted output conversion | |
7 | .SH SYNOPSIS | |
8 | .B #include <stdio.h> | |
9 | .PP | |
10 | .B printf(format | |
11 | .RB [ , | |
12 | arg ] ... | |
13 | .B ) | |
14 | .br | |
15 | .B char *format; | |
16 | .PP | |
17 | .B fprintf(stream, format | |
18 | .RB [ , | |
19 | arg ] ... | |
20 | .B ) | |
21 | .br | |
22 | .SM | |
23 | .B FILE | |
24 | .B *stream; | |
25 | .br | |
26 | .B char *format; | |
27 | .PP | |
28 | .B sprintf(s, format | |
29 | .RB [ , | |
30 | arg ] ... | |
31 | .B ) | |
32 | .br | |
33 | .B char *s, format; | |
ef8094b4 KM |
34 | .PP |
35 | .B #include <varargs.h> | |
36 | .br | |
37 | .B _doprnt(format, args, stream) | |
38 | .br | |
39 | .B char *format; | |
40 | .br | |
41 | .B va_list *args; | |
42 | .br | |
43 | .B FILE *stream; | |
c3ce85c3 KM |
44 | .SH DESCRIPTION |
45 | .I Printf | |
46 | places output on the standard output stream | |
ef8094b4 | 47 | .BR stdout . |
c3ce85c3 KM |
48 | .I Fprintf |
49 | places output on the named output | |
50 | .IR stream . | |
51 | .I Sprintf | |
52 | places `output' in the string | |
ef8094b4 | 53 | .IR s , |
c3ce85c3 | 54 | followed by the character `\\0'. |
ef8094b4 KM |
55 | All of these routines work by calling the internal |
56 | routine | |
57 | .B _doprnt, | |
58 | using the variable-length argument facilities of | |
59 | .IR varargs (3). | |
c3ce85c3 | 60 | .PP |
ef8094b4 KM |
61 | Each of these functions converts, formats, and prints its arguments after |
62 | the first under control of the first argument. | |
63 | The first argument is a character string which contains two types of objects: | |
64 | plain characters, which are simply copied to the output stream, | |
65 | and conversion specifications, each of which causes conversion and printing | |
c3ce85c3 KM |
66 | of the next successive |
67 | .I arg | |
68 | .IR printf . | |
69 | .PP | |
ef8094b4 | 70 | Each conversion specification is introduced by the character |
c3ce85c3 KM |
71 | .BR % . |
72 | Following the | |
73 | .BR % , | |
74 | there may be | |
75 | .TP | |
ef8094b4 | 76 | .B \(bu |
c3ce85c3 KM |
77 | an optional minus sign `\-' which specifies |
78 | .I "left adjustment" | |
ef8094b4 | 79 | of the converted value in the indicated field; |
c3ce85c3 | 80 | .TP |
ef8094b4 | 81 | .B \(bu |
c3ce85c3 KM |
82 | an optional digit string specifying a |
83 | .I "field width;" | |
ef8094b4 | 84 | if the converted value has fewer characters than the field width |
c3ce85c3 | 85 | it will be blank-padded on the left (or right, |
ef8094b4 | 86 | if the left-adjustment indicator has been given) to make up the field width; |
c3ce85c3 KM |
87 | if the field width begins with a zero, |
88 | zero-padding will be done instead of blank-padding; | |
89 | .TP | |
ef8094b4 | 90 | .B \(bu |
c3ce85c3 KM |
91 | an optional period |
92 | .RB ` . ' | |
ef8094b4 | 93 | which serves to separate the field width from the next digit string; |
c3ce85c3 | 94 | .TP |
ef8094b4 KM |
95 | .B \(bu |
96 | an optional digit string specifying a | |
c3ce85c3 | 97 | .I precision |
ef8094b4 KM |
98 | which specifies the number of digits to appear after the |
99 | decimal point, for e- and f-conversion, or the maximum number of characters | |
c3ce85c3 KM |
100 | to be printed from a string; |
101 | .TP | |
ef8094b4 KM |
102 | .B \(bu |
103 | an optional `#' character | |
104 | specifying that the value should be converted to an ``alternate form''. | |
105 | For | |
106 | .BR c , | |
107 | .BR d , | |
108 | .BR s , | |
109 | and | |
110 | .BR u , | |
111 | conversions, this option has no effect. For | |
112 | .B o | |
113 | conversions, the precision of the number is increased to force the first | |
114 | character of the output string to a zero. For | |
115 | .BR x ( X ) | |
116 | conversion, a non-zero result has the string | |
117 | .BR 0x ( 0X ) | |
118 | prepended to it. For | |
119 | .BR e , | |
120 | .BR E , | |
121 | .BR f , | |
122 | .BR g , | |
123 | and | |
124 | .BR G , | |
125 | conversions, the result will always contain a decimal point, even if no | |
126 | digits follow the point (normally, a decimal point only appears in the | |
127 | results of those conversions if a digit follows the decimal point). For | |
128 | .B g | |
129 | and | |
130 | .B G | |
131 | conversions, trailing zeros are not removed from the result as they | |
132 | would otherwise be. | |
133 | .TP | |
134 | .B \(bu | |
c3ce85c3 KM |
135 | the character |
136 | .B l | |
137 | specifying that a following | |
138 | .BR d , | |
139 | .BR o , | |
140 | .BR x , | |
141 | or | |
142 | .B u | |
143 | corresponds to a long integer | |
ef8094b4 | 144 | .IR arg . |
c3ce85c3 | 145 | .TP |
ef8094b4 | 146 | .B \(bu |
c3ce85c3 KM |
147 | a character which indicates the type of |
148 | conversion to be applied. | |
149 | .PP | |
150 | A field width or precision may be `*' instead of a digit string. | |
151 | In this case an integer | |
152 | .I arg | |
153 | supplies | |
154 | the field width or precision. | |
155 | .PP | |
156 | The conversion characters | |
157 | and their meanings are | |
158 | .TP | |
159 | .B dox | |
160 | The integer | |
161 | .I arg | |
162 | is converted to decimal, octal, or | |
163 | hexadecimal notation respectively. | |
164 | .TP | |
165 | .B f | |
166 | The float or double | |
167 | .I arg | |
168 | is converted to decimal notation | |
169 | in the style `[\fB\-\fR]ddd.ddd' | |
170 | where the number of d's after the decimal point | |
171 | is equal to the precision specification | |
172 | for the argument. | |
173 | If the precision | |
174 | is missing, | |
175 | 6 digits are given; | |
176 | if the precision is explicitly 0, no digits and | |
177 | no decimal point are printed. | |
178 | .TP | |
179 | .B e | |
180 | The float or double | |
181 | .I arg | |
182 | is converted in the style | |
183 | `[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd' | |
184 | where there is one digit before the decimal point and | |
185 | the number after is equal to the | |
186 | precision specification for the argument; | |
187 | when the precision is missing, | |
188 | 6 digits are produced. | |
189 | .TP | |
190 | .B g | |
191 | The float or double | |
192 | .I arg | |
193 | is printed in style | |
194 | .BR d , | |
195 | in style | |
196 | .BR f , | |
197 | or in | |
198 | style | |
199 | .BR e , | |
200 | whichever gives full precision in minimum space. | |
201 | .TP | |
202 | .B c | |
203 | The character | |
204 | .I arg | |
205 | is printed. | |
206 | .TP | |
207 | .B s | |
208 | .I Arg | |
209 | is taken to be a string (character pointer) | |
210 | and characters from the string are printed until | |
211 | a null character or until | |
212 | the number of characters indicated by the precision | |
213 | specification is reached; | |
214 | however if the precision is 0 or missing | |
215 | all characters up to a null are printed. | |
216 | .TP | |
217 | .B u | |
218 | The unsigned integer | |
219 | .I arg | |
220 | is converted to decimal | |
221 | and printed (the result will be in the | |
222 | range 0 through MAXUINT, where MAXUINT equals 4294967295 on a VAX-11 | |
223 | and 65535 on a PDP-11). | |
224 | .TP | |
225 | .B % | |
226 | Print a `%'; no argument is converted. | |
227 | .PP | |
228 | In no case does a non-existent or small field width | |
229 | cause truncation of a field; | |
230 | padding takes place only if the specified field | |
231 | width exceeds the actual width. | |
232 | Characters generated by | |
233 | .I printf | |
234 | are printed by | |
ef8094b4 | 235 | .IR putc (3S). |
c3ce85c3 KM |
236 | .PP |
237 | .B Examples | |
238 | .br | |
239 | To print a date and time in the form `Sunday, July 3, 10:02', | |
240 | where | |
241 | .I weekday | |
242 | and | |
243 | .I month | |
244 | are pointers to null-terminated strings: | |
245 | .RS | |
246 | .HP | |
247 | .nh | |
248 | printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min); | |
249 | .RE | |
250 | .hy | |
251 | .PP | |
252 | To print | |
253 | .if n pi | |
254 | .if t \(*p | |
255 | to 5 decimals: | |
256 | .IP | |
257 | printf("pi = %.5f", 4*atan(1.0)); | |
258 | .SH "SEE ALSO" | |
ef8094b4 KM |
259 | putc(3S), |
260 | scanf(3S), | |
c3ce85c3 KM |
261 | ecvt(3) |
262 | .SH BUGS | |
263 | Very wide fields (>128 characters) fail. |