Commit | Line | Data |
---|---|---|
7b089094 WJ |
1 | .\" Copyright (c) 1989, 1990 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" This code is derived from software contributed to Berkeley by | |
5 | .\" the Institute of Electrical and Electronics Engineers, Inc. | |
6 | .\" | |
7 | .\" Redistribution and use in source and binary forms, with or without | |
8 | .\" modification, are permitted provided that the following conditions | |
9 | .\" are met: | |
10 | .\" 1. Redistributions of source code must retain the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer. | |
12 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer in the | |
14 | .\" documentation and/or other materials provided with the distribution. | |
15 | .\" 3. All advertising materials mentioning features or use of this software | |
16 | .\" must display the following acknowledgement: | |
17 | .\" This product includes software developed by the University of | |
18 | .\" California, Berkeley and its contributors. | |
19 | .\" 4. Neither the name of the University nor the names of its contributors | |
20 | .\" may be used to endorse or promote products derived from this software | |
21 | .\" without specific prior written permission. | |
22 | .\" | |
23 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
24 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
25 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
26 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
27 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
28 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
29 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
30 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
31 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
32 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
33 | .\" SUCH DAMAGE. | |
34 | .\" | |
35 | .\" @(#)printf.1 5.11 (Berkeley) 7/24/91 | |
36 | .\" | |
37 | .Dd July 24, 1991 | |
38 | .Dt PRINTF 1 | |
39 | .Os | |
40 | .Sh NAME | |
41 | .Nm printf | |
42 | .Nd formatted output | |
43 | .Sh SYNOPSIS | |
44 | .Nm printf format | |
45 | .Op arguments ... | |
46 | .Sh DESCRIPTION | |
47 | .Nm Printf | |
48 | formats and prints its arguments, after the first, under control | |
49 | of the | |
50 | .Ar format . | |
51 | The | |
52 | .Ar format | |
53 | is a character string which contains three types of objects: plain characters, | |
54 | which are simply copied to standard output, character escape sequences which | |
55 | are converted and copied to the standard output, and format specifications, | |
56 | each of which causes printing of the next successive | |
57 | .Ar argument . | |
58 | .Pp | |
59 | The | |
60 | .Ar arguments | |
61 | after the first are treated as strings if the corresponding format is | |
62 | either | |
63 | .Cm c | |
64 | or | |
65 | .Cm s ; | |
66 | otherwise it is evaluated as a C constant, with the following extensions: | |
67 | .Pp | |
68 | .Bl -bullet -offset indent -compact | |
69 | .It | |
70 | A leading plus or minus sign is allowed. | |
71 | .It | |
72 | If the leading character is a single or double quote, or not a digit, | |
73 | plus, or minus sign, the value is the ASCII code of the next character. | |
74 | .El | |
75 | .Pp | |
76 | The format string is reused as often as necessary to satisfy the | |
77 | .Ar arguments . | |
78 | Any extra format specifications are evaluated with zero or the null | |
79 | string. | |
80 | .Pp | |
81 | Character escape sequences are in backslash notation as defined in the | |
82 | draft proposed | |
83 | .Tn ANSI C | |
84 | Standard | |
85 | .Tn X3J11 . | |
86 | The characters and their meanings | |
87 | are as follows: | |
88 | .Bl -tag -width Ds -offset indent | |
89 | .It Cm \ea | |
90 | Write a <bell> character. | |
91 | .It Cm \eb | |
92 | Write a <backspace> character. | |
93 | .It Cm \ef | |
94 | Write a <form-feed> character. | |
95 | .It Cm \en | |
96 | Write a <new-line> character. | |
97 | .It Cm \er | |
98 | Write a <carriage return> character. | |
99 | .It Cm \et | |
100 | Write a <tab> character. | |
101 | .It Cm \ev | |
102 | Write a <vertical tab> character. | |
103 | .It Cm \e\' | |
104 | Write a <single quote> character. | |
105 | .It Cm \e\e | |
106 | Write a backslash character. | |
107 | .It Cm \e Ns Ar num | |
108 | Write an 8-bit character whose | |
109 | .Tn ASCII | |
110 | value is the 1-, 2-, or 3-digit | |
111 | octal number | |
112 | .Ar num . | |
113 | .El | |
114 | .Pp | |
115 | Each format specification is introduced by the percent character | |
116 | (``%''). | |
117 | The remainder of the format specification includes, | |
118 | in the following order: | |
119 | .Bl -tag -width Ds | |
120 | .It "Zero or more of the following flags:" | |
121 | .Bl -tag -width Ds | |
122 | .It Cm # | |
123 | A `#' character | |
124 | specifying that the value should be printed in an ``alternate form''. | |
125 | For | |
126 | .Cm c , | |
127 | .Cm d , | |
128 | and | |
129 | .Cm s , | |
130 | formats, this option has no effect. For the | |
131 | .Cm o | |
132 | formats the precision of the number is increased to force the first | |
133 | character of the output string to a zero. For the | |
134 | .Cm x | |
135 | .Pq Cm X | |
136 | format, a non-zero result has the string | |
137 | .Li 0x | |
138 | .Pq Li 0X | |
139 | prepended to it. For | |
140 | .Cm e , | |
141 | .Cm E , | |
142 | .Cm f , | |
143 | .Cm g , | |
144 | and | |
145 | .Cm G , | |
146 | formats, the result will always contain a decimal point, even if no | |
147 | digits follow the point (normally, a decimal point only appears in the | |
148 | results of those formats if a digit follows the decimal point). For | |
149 | .Cm g | |
150 | and | |
151 | .Cm G | |
152 | formats, trailing zeros are not removed from the result as they | |
153 | would otherwise be; | |
154 | .It Cm \&\- | |
155 | A minus sign `\-' which specifies | |
156 | .Em left adjustment | |
157 | of the output in the indicated field; | |
158 | .It Cm \&+ | |
159 | A `+' character specifying that there should always be | |
160 | a sign placed before the number when using signed formats. | |
161 | .It Sq \&\ \& | |
162 | A space specifying that a blank should be left before a positive number | |
163 | for a signed format. A `+' overrides a space if both are used; | |
164 | .It Cm \&0 | |
165 | A zero `0' character indicating that zero-padding should be used | |
166 | rather than blank-padding. A `\-' overrides a `0' if both are used; | |
167 | .El | |
168 | .It "Field Width:" | |
169 | An optional digit string specifying a | |
170 | .Em field width ; | |
171 | if the output string has fewer characters than the field width it will | |
172 | be blank-padded on the left (or right, if the left-adjustment indicator | |
173 | has been given) to make up the field width (note that a leading zero | |
174 | is a flag, but an embedded zero is part of a field width); | |
175 | .It Precision: | |
176 | An optional period, | |
177 | .Sq Cm \&.\& , | |
178 | followed by an optional digit string giving a | |
179 | .Em precision | |
180 | which specifies the number of digits to appear after the decimal point, | |
181 | for | |
182 | .Cm e | |
183 | and | |
184 | .Cm f | |
185 | formats, or the maximum number of characters to be printed | |
186 | from a string; if the digit string is missing, the precision is treated | |
187 | as zero; | |
188 | .It Format: | |
189 | A character which indicates the type of format to use (one of | |
190 | .Cm diouxXfwEgGcs ) . | |
191 | .El | |
192 | .Pp | |
193 | A field width or precision may be | |
194 | .Sq Cm \&* | |
195 | instead of a digit string. | |
196 | In this case an | |
197 | .Ar argument | |
198 | supplies the field width or precision. | |
199 | .Pp | |
200 | The format characters and their meanings are: | |
201 | .Bl -tag -width Fl | |
202 | .It Cm diouXx | |
203 | The | |
204 | .Ar argument | |
205 | is printed as a signed decimal (d or i), unsigned decimal, unsigned octal, | |
206 | or unsigned hexadecimal (X or x), respectively. | |
207 | .It Cm f | |
208 | The | |
209 | .Ar argument | |
210 | is printed in the style `[\-]ddd.ddd' where the number of d's | |
211 | after the decimal point is equal to the precision specification for | |
212 | the argument. | |
213 | If the precision is missing, 6 digits are given; if the precision | |
214 | is explicitly 0, no digits and no decimal point are printed. | |
215 | .It Cm eE | |
216 | The | |
217 | .Ar argument | |
218 | is printed in the style | |
219 | .Cm e | |
220 | .`[-]d.ddd Ns \(+-dd\' | |
221 | where there | |
222 | is one digit before the decimal point and the number after is equal to | |
223 | the precision specification for the argument; when the precision is | |
224 | missing, 6 digits are produced. | |
225 | An upper-case E is used for an `E' format. | |
226 | .It Cm gG | |
227 | The | |
228 | .Ar argument | |
229 | is printed in style | |
230 | .Cm f | |
231 | or in style | |
232 | .Cm e | |
233 | .Pq Cm E | |
234 | whichever gives full precision in minimum space. | |
235 | .It Cm c | |
236 | The first character of | |
237 | .Ar argument | |
238 | is printed. | |
239 | .It Cm s | |
240 | Characters from the string | |
241 | .Ar argument | |
242 | are printed until the end is reached or until the number of characters | |
243 | indicated by the precision specification is reached; however if the | |
244 | precision is 0 or missing, all characters in the string are printed. | |
245 | .It Cm \&% | |
246 | Print a `%'; no argument is used. | |
247 | .El | |
248 | .Pp | |
249 | In no case does a non-existent or small field width cause truncation of | |
250 | a field; padding takes place only if the specified field width exceeds | |
251 | the actual width. | |
252 | .Sh RETURN VALUES | |
253 | .Nm Printf | |
254 | exits 0 on success, 1 on failure. | |
255 | .Sh SEE ALSO | |
256 | .Xr printf 3 | |
257 | .Sh HISTORY | |
258 | The | |
259 | .Nm printf | |
260 | command appeared in | |
261 | .Bx 4.3 Reno . | |
262 | It is modeled | |
263 | after the standard library function, | |
264 | .Xr printf 3 . | |
265 | .Sh BUGS | |
266 | Since the number is translated from | |
267 | .Tn ASCII | |
268 | to floating-point, and | |
269 | then back again, floating-point precision may be lost. | |
270 | .Pp | |
271 | .Tn ANSI | |
272 | hexadecimal character constants were deliberately not provided. |