Commit | Line | Data |
---|---|---|
b5dc1377 | 1 | .\" Copyright (c) 1989, 1990 The Regents of the University of California. |
a4ba6264 KB |
2 | .\" All rights reserved. |
3 | .\" | |
ae122740 KB |
4 | .\" This code is derived from software contributed to Berkeley by |
5 | .\" the Institute of Electrical and Electronics Engineers, Inc. | |
6 | .\" | |
b5dc1377 | 7 | .\" %sccs.include.redist.man% |
a4ba6264 | 8 | .\" |
ae122740 | 9 | .\" @(#)printf.1 5.10 (Berkeley) %G% |
a4ba6264 | 10 | .\" |
ee9b0a0a | 11 | .Vx |
b5dc1377 CL |
12 | .Dd |
13 | .Dt PRINTF 1 | |
a4ba6264 | 14 | .AT 1 |
b5dc1377 CL |
15 | .Sh NAME |
16 | .Nm printf | |
17 | .Nd formatted output | |
18 | .Sh SYNOPSIS | |
19 | .Pp | |
20 | .Nm printf format | |
21 | .Op arguments ... | |
22 | .Sh DESCRIPTION | |
23 | .Nm Printf | |
a4ba6264 KB |
24 | formats and prints its arguments, after the first, under control |
25 | of the | |
b5dc1377 | 26 | .Ar format . |
a4ba6264 | 27 | The |
b5dc1377 | 28 | .Ar format |
a4ba6264 KB |
29 | is a character string which contains three types of objects: plain characters, |
30 | which are simply copied to standard output, character escape sequences which | |
31 | are converted and copied to the standard output, and format specifications, | |
32 | each of which causes printing of the next successive | |
b5dc1377 CL |
33 | .Ar argument . |
34 | .Pp | |
a4ba6264 | 35 | The |
b5dc1377 | 36 | .Ar arguments |
a4ba6264 KB |
37 | after the first are treated as strings if the corresponding format is |
38 | either | |
b5dc1377 | 39 | .Cm c |
a4ba6264 | 40 | or |
b5dc1377 | 41 | .Cm s ; |
a4ba6264 | 42 | otherwise it is evaluated as a C constant, with the following extensions: |
b5dc1377 CL |
43 | .Pp |
44 | .Df I | |
a4ba6264 | 45 | A leading plus or minus sign is allowed. |
b5dc1377 | 46 | .br |
a4ba6264 KB |
47 | If the leading character is a single or double quote, or not a digit, |
48 | plus, or minus sign, the value is the ASCII code of the next character. | |
b5dc1377 CL |
49 | .De |
50 | .Pp | |
a4ba6264 | 51 | The format string is reused as often as necessary to satisfy the |
b5dc1377 | 52 | .Ar arguments . |
a4ba6264 KB |
53 | Any extra format specifications are evaluated with zero or the null |
54 | string. | |
b5dc1377 | 55 | .Pp |
a4ba6264 KB |
56 | Character escape sequences are in backslash notation as defined in the |
57 | draft proposed ANSI C Standard X3J11. The characters and their meanings | |
58 | are as follows: | |
b5dc1377 CL |
59 | .Tw Ds |
60 | .Tp Cm \ea | |
f78448a3 | 61 | Write a <bell> character. |
b5dc1377 | 62 | .Tp Cm \eb |
a4ba6264 | 63 | Write a <backspace> character. |
b5dc1377 | 64 | .Tp Cm \ef |
a4ba6264 | 65 | Write a <form-feed> character. |
b5dc1377 | 66 | .Tp Cm \en |
a4ba6264 | 67 | Write a <new-line> character. |
b5dc1377 | 68 | .Tp Cm \er |
a4ba6264 | 69 | Write a <carriage return> character. |
b5dc1377 | 70 | .Tp Cm \et |
a4ba6264 | 71 | Write a <tab> character. |
b5dc1377 | 72 | .Tp Cm \ev |
a4ba6264 | 73 | Write a <vertical tab> character. |
b5dc1377 | 74 | .Tp Cm \e\' |
f78448a3 | 75 | Write a <single quote> character. |
b5dc1377 | 76 | .Tp Cm \e\e |
a4ba6264 | 77 | Write a backslash character. |
b5dc1377 CL |
78 | .Tp Cx Cm \e |
79 | .Ar num | |
80 | .Cx | |
5325ced3 | 81 | Write an 8-bit character whose ASCII value is the 1-, 2-, or 3-digit |
a4ba6264 | 82 | octal number |
b5dc1377 CL |
83 | .Ar num . |
84 | .Tp | |
85 | .Pp | |
a4ba6264 KB |
86 | Each format specification is introduced by the percent character |
87 | (``%''). | |
88 | The remainder of the format specification includes, in the | |
89 | following order: | |
b5dc1377 | 90 | .Pp |
a4ba6264 | 91 | Zero or more of the following flags: |
b5dc1377 CL |
92 | .Pp |
93 | .Ds I | |
94 | .Tw Ds | |
95 | .Tp Cm # | |
96 | A `#' character | |
a4ba6264 | 97 | specifying that the value should be printed in an ``alternate form''. |
b5dc1377 CL |
98 | For |
99 | .Cm c , | |
100 | .Cm d , | |
a4ba6264 | 101 | and |
b5dc1377 | 102 | .Cm s , |
a4ba6264 | 103 | formats, this option has no effect. For the |
b5dc1377 | 104 | .Cm o |
a4ba6264 KB |
105 | formats the precision of the number is increased to force the first |
106 | character of the output string to a zero. For the | |
b5dc1377 CL |
107 | .Cm x |
108 | .Pq Cm X | |
a4ba6264 | 109 | format, a non-zero result has the string |
b5dc1377 CL |
110 | .Li 0x |
111 | .Pq Li 0X | |
112 | prepended to it. For | |
113 | .Cm e , | |
114 | .Cm E , | |
115 | .Cm f , | |
116 | .Cm g , | |
a4ba6264 | 117 | and |
b5dc1377 | 118 | .Cm G , |
a4ba6264 KB |
119 | formats, the result will always contain a decimal point, even if no |
120 | digits follow the point (normally, a decimal point only appears in the | |
121 | results of those formats if a digit follows the decimal point). For | |
b5dc1377 | 122 | .Cm g |
a4ba6264 | 123 | and |
b5dc1377 | 124 | .Cm G |
a4ba6264 KB |
125 | formats, trailing zeros are not removed from the result as they |
126 | would otherwise be; | |
b5dc1377 CL |
127 | .Tp Cm \&\- |
128 | A minus sign `\-' which specifies | |
129 | .Em left adjustment | |
a4ba6264 | 130 | of the output in the indicated field; |
b5dc1377 CL |
131 | .Tp Cm \&+ |
132 | A `+' character specifying that there should always be | |
a4ba6264 | 133 | a sign placed before the number when using signed formats. |
b5dc1377 CL |
134 | .Tp Sq \&\ \& |
135 | A space specifying that a blank should be left before a positive number | |
a4ba6264 | 136 | for a signed format. A `+' overrides a space if both are used; |
b5dc1377 CL |
137 | .Tp Cm \&0 |
138 | A zero `0' character indicating that zero-padding should be used | |
a4ba6264 | 139 | rather than blank-padding. A `\-' overrides a `0' if both are used; |
b5dc1377 CL |
140 | .Tp |
141 | .De | |
142 | .Pp | |
143 | .Tw Ds | |
144 | .Tp Field Width: | |
145 | An optional digit string specifying a | |
146 | .Em field width ; | |
a4ba6264 KB |
147 | if the output string has fewer characters than the field width it will |
148 | be blank-padded on the left (or right, if the left-adjustment indicator | |
149 | has been given) to make up the field width (note that a leading zero | |
150 | is a flag, but an embedded zero is part of a field width); | |
b5dc1377 CL |
151 | .Tp Precision: |
152 | An optional period, | |
153 | .Sq Cm \&.\& , | |
154 | followed by an optional digit string giving a | |
155 | .Em precision | |
a4ba6264 | 156 | which specifies the number of digits to appear after the decimal point, |
b5dc1377 CL |
157 | for |
158 | .Cm e | |
159 | and | |
160 | .Cm f | |
161 | formats, or the maximum number of characters to be printed | |
a4ba6264 KB |
162 | from a string; if the digit string is missing, the precision is treated |
163 | as zero; | |
b5dc1377 CL |
164 | .Tp Format: |
165 | A character which indicates the type of format to use (one of | |
166 | .Cm diouxXfwEgGcs ) . | |
167 | .Tp | |
168 | .Pp | |
169 | A field width or precision may be | |
170 | .Sq Cm \&* | |
171 | instead of a digit string. | |
a4ba6264 | 172 | In this case an |
b5dc1377 | 173 | .Ar argument |
a4ba6264 | 174 | supplies the field width or precision. |
b5dc1377 | 175 | .Pp |
a4ba6264 | 176 | The format characters and their meanings are: |
b5dc1377 CL |
177 | .Tw Fl |
178 | .Tp Cm diouXx | |
a4ba6264 | 179 | The |
b5dc1377 | 180 | .Ar 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. | |
b5dc1377 | 183 | .Tp Cm f |
a4ba6264 | 184 | The |
b5dc1377 CL |
185 | .Ar argument |
186 | is printed in the style `[\-]ddd.ddd' where the number of d's | |
a4ba6264 KB |
187 | after the decimal point is equal to the precision specification for |
188 | the argument. | |
5325ced3 CL |
189 | If the precision is missing, 6 digits are given; if the precision |
190 | is explicitly 0, no digits and no decimal point are printed. | |
b5dc1377 | 191 | .Tp Cm eE |
a4ba6264 | 192 | The |
b5dc1377 CL |
193 | .Ar argument |
194 | is printed in the style | |
195 | .Cx `[-]d.ddd | |
196 | .Cm e | |
197 | .Cx \(+-dd\' | |
198 | .Cx | |
199 | where there | |
a4ba6264 KB |
200 | is one digit before the decimal point and the number after is equal to |
201 | the precision specification for the argument; when the precision is | |
5325ced3 | 202 | missing, 6 digits are produced. |
a4ba6264 | 203 | An upper-case E is used for an `E' format. |
b5dc1377 | 204 | .Tp Cm gG |
a4ba6264 | 205 | The |
b5dc1377 | 206 | .Ar argument |
a4ba6264 | 207 | is printed in style |
b5dc1377 | 208 | .Cm f |
a4ba6264 | 209 | or in style |
b5dc1377 CL |
210 | .Cm e |
211 | .Pq Cm E | |
a4ba6264 | 212 | whichever gives full precision in minimum space. |
b5dc1377 | 213 | .Tp Cm c |
a4ba6264 | 214 | The first character of |
b5dc1377 | 215 | .Ar argument |
a4ba6264 | 216 | is printed. |
b5dc1377 | 217 | .Tp Cm s |
a4ba6264 | 218 | Characters from the string |
b5dc1377 | 219 | .Ar argument |
a4ba6264 KB |
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. | |
b5dc1377 | 223 | .Tp Cm \&% |
a4ba6264 | 224 | Print a `%'; no argument is used. |
b5dc1377 CL |
225 | .Tp |
226 | .Pp | |
a4ba6264 KB |
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. | |
b5dc1377 CL |
230 | .Sh RETURN VALUE |
231 | .Nm Printf | |
5d351dd2 | 232 | exits 0 on success, 1 on failure. |
b5dc1377 CL |
233 | .Sh SEE ALSO |
234 | .Xr printf 3 | |
235 | .Sh HISTORY | |
5325ced3 CL |
236 | .Nm Printf |
237 | as a command, appears in 4.3+Reno BSD. It is modeled | |
238 | after the standard library function, | |
239 | .Xr printf 3 . | |
b5dc1377 | 240 | .Sh BUGS |
0e206801 KB |
241 | Since the number is translated from ASCII to floating-point, and |
242 | then back again, floating-point precision may be lost. | |
b5dc1377 | 243 | .Pp |
0e206801 | 244 | ANSI hexadecimal character constants were deliberately not provided. |