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