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