Commit | Line | Data |
---|---|---|
a4ba6264 KB |
1 | .\" Copyright (c) 1989 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms are permitted | |
5 | .\" provided that the above copyright notice and this paragraph are | |
6 | .\" duplicated in all such forms and that any documentation, | |
7 | .\" advertising materials, and other materials related to such | |
8 | .\" distribution and use acknowledge that the software was developed | |
9 | .\" by the University of California, Berkeley. The name of the | |
10 | .\" University may not be used to endorse or promote products derived | |
11 | .\" from this software without specific prior written permission. | |
12 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR | |
13 | .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED | |
14 | .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. | |
15 | .\" | |
0e206801 | 16 | .\" @(#)printf.1 5.4 (Berkeley) %G% |
a4ba6264 KB |
17 | .\" |
18 | .TH PRINTF 1 " | |
19 | .AT 1 | |
20 | .SH NAME | |
21 | printf \- formatted output | |
22 | .SH SYNOPSIS | |
23 | .PP | |
24 | .B printf format [ arguments ... ] | |
25 | .SH DESCRIPTION | |
26 | .I Printf | |
27 | formats and prints its arguments, after the first, under control | |
28 | of the | |
29 | .IR format . | |
30 | The | |
31 | .I format | |
32 | is a character string which contains three types of objects: plain characters, | |
33 | which are simply copied to standard output, character escape sequences which | |
34 | are converted and copied to the standard output, and format specifications, | |
35 | each of which causes printing of the next successive | |
36 | .IR argument . | |
37 | .PP | |
38 | The | |
39 | .I arguments | |
40 | after the first are treated as strings if the corresponding format is | |
41 | either | |
42 | .I c | |
43 | or | |
44 | .IR s ; | |
45 | otherwise it is evaluated as a C constant, with the following extensions: | |
46 | .in +0.5i | |
47 | A leading plus or minus sign is allowed. | |
48 | .br | |
49 | If the leading character is a single or double quote, or not a digit, | |
50 | plus, or minus sign, the value is the ASCII code of the next character. | |
51 | .in -0.5i | |
52 | .PP | |
53 | The format string is reused as often as necessary to satisfy the | |
54 | .IR arguments . | |
55 | Any extra format specifications are evaluated with zero or the null | |
56 | string. | |
57 | .PP | |
58 | Character escape sequences are in backslash notation as defined in the | |
59 | draft proposed ANSI C Standard X3J11. The characters and their meanings | |
60 | are as follows: | |
61 | .TP | |
62 | .B \ea | |
f78448a3 | 63 | Write a <bell> character. |
a4ba6264 KB |
64 | .TP |
65 | .B \eb | |
66 | Write a <backspace> character. | |
67 | .TP | |
68 | .B \ef | |
69 | Write a <form-feed> character. | |
70 | .TP | |
71 | .B \en | |
72 | Write a <new-line> character. | |
73 | .TP | |
74 | .B \er | |
75 | Write a <carriage return> character. | |
76 | .TP | |
77 | .B \et | |
78 | Write a <tab> character. | |
79 | .TP | |
80 | .B \ev | |
81 | Write a <vertical tab> character. | |
82 | .TP | |
f78448a3 KB |
83 | .B \e' |
84 | Write a <single quote> character. | |
85 | .TP | |
a4ba6264 KB |
86 | .B \e\e |
87 | Write a backslash character. | |
88 | .TP | |
89 | .B \enum | |
90 | Write an 8-bit character whose numeric value is the 1-, 2-, or 3-digit | |
91 | octal number | |
92 | .IR num . | |
93 | .PP | |
94 | Each format specification is introduced by the percent character | |
95 | (``%''). | |
96 | The remainder of the format specification includes, in the | |
97 | following order: | |
98 | .TP | |
99 | .B \(bu | |
100 | Zero or more of the following flags: | |
101 | .RS | |
102 | .TP | |
103 | .B \(bu | |
104 | a `#' character | |
105 | specifying that the value should be printed in an ``alternate form''. | |
106 | For | |
107 | .BR c , | |
108 | .BR d , | |
109 | and | |
110 | .BR s , | |
111 | formats, this option has no effect. For the | |
112 | .B o | |
113 | formats the precision of the number is increased to force the first | |
114 | character of the output string to a zero. For the | |
115 | .BR x ( X ) | |
116 | format, 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 | formats, 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 formats if a digit follows the decimal point). For | |
128 | .B g | |
129 | and | |
130 | .B G | |
131 | formats, trailing zeros are not removed from the result as they | |
132 | would otherwise be; | |
133 | .TP | |
134 | .B \(bu | |
135 | a minus sign `\-' which specifies | |
136 | .I "left adjustment" | |
137 | of the output in the indicated field; | |
138 | .TP | |
139 | .B \(bu | |
140 | a `+' character specifying that there should always be | |
141 | a sign placed before the number when using signed formats. | |
142 | .TP | |
143 | .B \(bu | |
144 | a space specifying that a blank should be left before a positive number | |
145 | for a signed format. A `+' overrides a space if both are used; | |
146 | .TP | |
147 | .B \(bu | |
148 | a zero `0' character indicating that zero-padding should be used | |
149 | rather than blank-padding. A `\-' overrides a `0' if both are used; | |
150 | .RE | |
151 | .TP | |
152 | .B \(bu | |
153 | an optional digit string specifying a | |
154 | .I "field width;" | |
155 | if the output string has fewer characters than the field width it will | |
156 | be blank-padded on the left (or right, if the left-adjustment indicator | |
157 | has been given) to make up the field width (note that a leading zero | |
158 | is a flag, but an embedded zero is part of a field width); | |
159 | .TP | |
160 | .B \(bu | |
161 | an optional period, followed by an optional digit string giving a | |
162 | .I precision | |
163 | which specifies the number of digits to appear after the decimal point, | |
164 | for e- and f-formats, or the maximum number of characters to be printed | |
165 | from a string; if the digit string is missing, the precision is treated | |
166 | as zero; | |
167 | .TP | |
168 | .B \(bu | |
169 | a character which indicates the type of format to use. | |
170 | .PP | |
171 | A field width or precision may be `*' instead of a digit string. | |
172 | In this case an | |
173 | .I argument | |
174 | supplies the field width or precision. | |
175 | .PP | |
176 | The format characters and their meanings are: | |
177 | .TP | |
a0486b62 | 178 | .B diouXx |
a4ba6264 KB |
179 | The |
180 | .I argument | |
a0486b62 KB |
181 | is printed as a signed decimal (d or i), unsigned decimal, unsigned octal, |
182 | or unsigned hexadecimal (X or x), respectively. | |
a4ba6264 KB |
183 | .TP |
184 | .B f | |
185 | The | |
186 | .I argument | |
187 | is printed in the style `[\fB\-\fR]ddd.ddd' where the number of d's | |
188 | after the decimal point is equal to the precision specification for | |
189 | the argument. | |
190 | If the precision is missing, 6 digits are printed after the decimal point; | |
191 | if the precision is explicitly 0, no digits and no decimal point are printed. | |
192 | .TP | |
193 | .B eE | |
194 | The | |
195 | .I argument | |
196 | is printed in the style `[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd' where there | |
197 | is one digit before the decimal point and the number after is equal to | |
198 | the precision specification for the argument; when the precision is | |
199 | missing, 6 digits are printed after the decimal point. | |
200 | An upper-case E is used for an `E' format. | |
201 | .TP | |
202 | .B gG | |
203 | The | |
204 | .I argument | |
205 | is printed in style | |
206 | .B f | |
207 | or in style | |
208 | .B e | |
209 | .RB ( E ) | |
210 | whichever gives full precision in minimum space. | |
211 | .TP | |
212 | .B c | |
213 | The first character of | |
214 | .I argument | |
215 | is printed. | |
216 | .TP | |
217 | .B s | |
218 | Characters from the string | |
219 | .I argument | |
220 | are printed until the end is reached or until the number of characters | |
221 | indicated by the precision specification is reached; however if the | |
222 | precision is 0 or missing, all characters in the string are printed. | |
223 | .TP | |
224 | .B % | |
225 | Print a `%'; no argument is used. | |
226 | .PP | |
227 | In no case does a non-existent or small field width cause truncation of | |
228 | a field; padding takes place only if the specified field width exceeds | |
229 | the actual width. | |
230 | .SH DIAGNOSTICS | |
231 | None. | |
232 | .SH "RETURN VALUE" | |
233 | .IR Printf 's | |
234 | exit value is the number of characters printed. If an error occurs, | |
235 | printf exits with a -1. | |
236 | .SH "SEE ALSO" | |
237 | printf(3) | |
0e206801 KB |
238 | .SH BUGS |
239 | Since the number is translated from ASCII to floating-point, and | |
240 | then back again, floating-point precision may be lost. | |
241 | .PP | |
242 | ANSI hexadecimal character constants were deliberately not provided. |