Commit | Line | Data |
---|---|---|
709bb17f | 1 | .\" @(#)printf.3 6.3 (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 | 71 | .BR % . |
faccd919 JB |
72 | The remainder of the conversion specification includes |
73 | in the following order | |
c3ce85c3 | 74 | .TP |
ef8094b4 | 75 | .B \(bu |
faccd919 JB |
76 | Zero or more of following flags: |
77 | .RS | |
c3ce85c3 | 78 | .TP |
ef8094b4 | 79 | .B \(bu |
faccd919 | 80 | a `#' character |
ef8094b4 KM |
81 | specifying that the value should be converted to an ``alternate form''. |
82 | For | |
83 | .BR c , | |
84 | .BR d , | |
85 | .BR s , | |
86 | and | |
87 | .BR u , | |
88 | conversions, this option has no effect. For | |
89 | .B o | |
90 | conversions, the precision of the number is increased to force the first | |
91 | character of the output string to a zero. For | |
92 | .BR x ( X ) | |
93 | conversion, a non-zero result has the string | |
94 | .BR 0x ( 0X ) | |
95 | prepended to it. For | |
96 | .BR e , | |
97 | .BR E , | |
98 | .BR f , | |
99 | .BR g , | |
100 | and | |
101 | .BR G , | |
102 | conversions, the result will always contain a decimal point, even if no | |
103 | digits follow the point (normally, a decimal point only appears in the | |
104 | results of those conversions if a digit follows the decimal point). For | |
105 | .B g | |
106 | and | |
107 | .B G | |
108 | conversions, trailing zeros are not removed from the result as they | |
109 | would otherwise be. | |
110 | .TP | |
111 | .B \(bu | |
faccd919 JB |
112 | a minus sign `\-' which specifies |
113 | .I "left adjustment" | |
114 | of the converted value in the indicated field; | |
115 | .TP | |
116 | .B \(bu | |
709bb17f | 117 | a `+' character specifying that there should always be |
faccd919 JB |
118 | a sign placed before the number when using signed conversions. |
119 | .TP | |
120 | .B \(bu | |
121 | a space specifying that a blank should be left before a positive number | |
122 | during a signed conversion. A `+' overrides a space if both are used. | |
123 | .RE | |
124 | .TP | |
125 | .B \(bu | |
126 | an optional digit string specifying a | |
127 | .I "field width;" | |
128 | if the converted value has fewer characters than the field width | |
129 | it will be blank-padded on the left (or right, | |
130 | if the left-adjustment indicator has been given) to make up the field width; | |
131 | if the field width begins with a zero, | |
132 | zero-padding will be done instead of blank-padding; | |
133 | .TP | |
134 | .B \(bu | |
135 | an optional period | |
136 | .RB ` . ' | |
137 | which serves to separate the field width from the next digit string; | |
138 | .TP | |
139 | .B \(bu | |
140 | an optional digit string specifying a | |
141 | .I precision | |
142 | which specifies the number of digits to appear after the | |
143 | decimal point, for e- and f-conversion, or the maximum number of characters | |
144 | to be printed from a string; | |
145 | .TP | |
146 | .B \(bu | |
c3ce85c3 KM |
147 | the character |
148 | .B l | |
149 | specifying that a following | |
150 | .BR d , | |
151 | .BR o , | |
152 | .BR x , | |
153 | or | |
154 | .B u | |
155 | corresponds to a long integer | |
ef8094b4 | 156 | .IR arg . |
c3ce85c3 | 157 | .TP |
ef8094b4 | 158 | .B \(bu |
c3ce85c3 KM |
159 | a character which indicates the type of |
160 | conversion to be applied. | |
161 | .PP | |
162 | A field width or precision may be `*' instead of a digit string. | |
163 | In this case an integer | |
164 | .I arg | |
165 | supplies | |
166 | the field width or precision. | |
167 | .PP | |
168 | The conversion characters | |
169 | and their meanings are | |
170 | .TP | |
171 | .B dox | |
172 | The integer | |
173 | .I arg | |
174 | is converted to decimal, octal, or | |
175 | hexadecimal notation respectively. | |
176 | .TP | |
177 | .B f | |
178 | The float or double | |
179 | .I arg | |
180 | is converted to decimal notation | |
181 | in the style `[\fB\-\fR]ddd.ddd' | |
182 | where the number of d's after the decimal point | |
183 | is equal to the precision specification | |
184 | for the argument. | |
185 | If the precision | |
186 | is missing, | |
187 | 6 digits are given; | |
188 | if the precision is explicitly 0, no digits and | |
189 | no decimal point are printed. | |
190 | .TP | |
191 | .B e | |
192 | The float or double | |
193 | .I arg | |
194 | is converted in the style | |
195 | `[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd' | |
196 | where there is one digit before the decimal point and | |
197 | the number after is equal to the | |
198 | precision specification for the argument; | |
199 | when the precision is missing, | |
200 | 6 digits are produced. | |
201 | .TP | |
202 | .B g | |
203 | The float or double | |
204 | .I arg | |
205 | is printed in style | |
206 | .BR d , | |
207 | in style | |
208 | .BR f , | |
209 | or in | |
210 | style | |
211 | .BR e , | |
212 | whichever gives full precision in minimum space. | |
213 | .TP | |
214 | .B c | |
215 | The character | |
216 | .I arg | |
217 | is printed. | |
218 | .TP | |
219 | .B s | |
220 | .I Arg | |
221 | is taken to be a string (character pointer) | |
222 | and characters from the string are printed until | |
223 | a null character or until | |
224 | the number of characters indicated by the precision | |
225 | specification is reached; | |
226 | however if the precision is 0 or missing | |
227 | all characters up to a null are printed. | |
228 | .TP | |
229 | .B u | |
230 | The unsigned integer | |
231 | .I arg | |
232 | is converted to decimal | |
233 | and printed (the result will be in the | |
234 | range 0 through MAXUINT, where MAXUINT equals 4294967295 on a VAX-11 | |
235 | and 65535 on a PDP-11). | |
236 | .TP | |
237 | .B % | |
238 | Print a `%'; no argument is converted. | |
239 | .PP | |
240 | In no case does a non-existent or small field width | |
241 | cause truncation of a field; | |
242 | padding takes place only if the specified field | |
243 | width exceeds the actual width. | |
244 | Characters generated by | |
245 | .I printf | |
246 | are printed by | |
ef8094b4 | 247 | .IR putc (3S). |
c3ce85c3 KM |
248 | .PP |
249 | .B Examples | |
250 | .br | |
251 | To print a date and time in the form `Sunday, July 3, 10:02', | |
252 | where | |
253 | .I weekday | |
254 | and | |
255 | .I month | |
256 | are pointers to null-terminated strings: | |
257 | .RS | |
258 | .HP | |
259 | .nh | |
260 | printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min); | |
261 | .RE | |
262 | .hy | |
263 | .PP | |
264 | To print | |
265 | .if n pi | |
266 | .if t \(*p | |
267 | to 5 decimals: | |
268 | .IP | |
269 | printf("pi = %.5f", 4*atan(1.0)); | |
270 | .SH "SEE ALSO" | |
ef8094b4 KM |
271 | putc(3S), |
272 | scanf(3S), | |
c3ce85c3 KM |
273 | ecvt(3) |
274 | .SH BUGS | |
275 | Very wide fields (>128 characters) fail. |