| @@ -1,411 +1,418 @@ | | | @@ -1,411 +1,418 @@ |
1 | .\" $NetBSD: printf.1,v 1.25 2014/04/13 01:45:34 snj Exp $ | | 1 | .\" $NetBSD: printf.1,v 1.26 2018/03/12 00:42:05 dholland Exp $ |
2 | .\" | | 2 | .\" |
3 | .\" Copyright (c) 1989, 1990, 1993 | | 3 | .\" Copyright (c) 1989, 1990, 1993 |
4 | .\" The Regents of the University of California. All rights reserved. | | 4 | .\" The Regents of the University of California. All rights reserved. |
5 | .\" | | 5 | .\" |
6 | .\" This code is derived from software contributed to Berkeley by | | 6 | .\" This code is derived from software contributed to Berkeley by |
7 | .\" the Institute of Electrical and Electronics Engineers, Inc. | | 7 | .\" the Institute of Electrical and Electronics Engineers, Inc. |
8 | .\" | | 8 | .\" |
9 | .\" Redistribution and use in source and binary forms, with or without | | 9 | .\" Redistribution and use in source and binary forms, with or without |
10 | .\" modification, are permitted provided that the following conditions | | 10 | .\" modification, are permitted provided that the following conditions |
11 | .\" are met: | | 11 | .\" are met: |
12 | .\" 1. Redistributions of source code must retain the above copyright | | 12 | .\" 1. Redistributions of source code must retain the above copyright |
13 | .\" notice, this list of conditions and the following disclaimer. | | 13 | .\" notice, this list of conditions and the following disclaimer. |
14 | .\" 2. Redistributions in binary form must reproduce the above copyright | | 14 | .\" 2. Redistributions in binary form must reproduce the above copyright |
15 | .\" notice, this list of conditions and the following disclaimer in the | | 15 | .\" notice, this list of conditions and the following disclaimer in the |
16 | .\" documentation and/or other materials provided with the distribution. | | 16 | .\" documentation and/or other materials provided with the distribution. |
17 | .\" 3. Neither the name of the University nor the names of its contributors | | 17 | .\" 3. Neither the name of the University nor the names of its contributors |
18 | .\" may be used to endorse or promote products derived from this software | | 18 | .\" may be used to endorse or promote products derived from this software |
19 | .\" without specific prior written permission. | | 19 | .\" without specific prior written permission. |
20 | .\" | | 20 | .\" |
21 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | | 21 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
22 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | | 22 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
23 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | | 23 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
24 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | | 24 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
25 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | | 25 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
26 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | | 26 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
27 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | | 27 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
28 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | | 28 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
29 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | | 29 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
30 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | | 30 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
31 | .\" SUCH DAMAGE. | | 31 | .\" SUCH DAMAGE. |
32 | .\" | | 32 | .\" |
33 | .\" from: @(#)printf.1 8.1 (Berkeley) 6/6/93 | | 33 | .\" from: @(#)printf.1 8.1 (Berkeley) 6/6/93 |
34 | .\" | | 34 | .\" |
35 | .Dd May 6, 2008 | | 35 | .Dd March 11, 2018 |
36 | .Dt PRINTF 1 | | 36 | .Dt PRINTF 1 |
37 | .Os | | 37 | .Os |
38 | .Sh NAME | | 38 | .Sh NAME |
39 | .Nm printf | | 39 | .Nm printf |
40 | .Nd formatted output | | 40 | .Nd formatted output |
41 | .Sh SYNOPSIS | | 41 | .Sh SYNOPSIS |
42 | .Nm | | 42 | .Nm |
43 | .Ar format | | 43 | .Ar format |
44 | .Op Ar arguments ... | | 44 | .Op Ar arguments ... |
45 | .Sh DESCRIPTION | | 45 | .Sh DESCRIPTION |
46 | .Nm | | 46 | .Nm |
47 | formats and prints its arguments, after the first, under control | | 47 | formats and prints its arguments, after the first, under control |
48 | of the | | 48 | of the |
49 | .Ar format . | | 49 | .Ar format . |
50 | The | | 50 | The |
51 | .Ar format | | 51 | .Ar format |
52 | is a character string which contains three types of objects: plain characters, | | 52 | is a character string which contains three types of objects: plain characters, |
53 | which are simply copied to standard output, character escape sequences which | | 53 | which are simply copied to standard output, character escape sequences which |
54 | are converted and copied to the standard output, and format specifications, | | 54 | are converted and copied to the standard output, and format specifications, |
55 | each of which causes printing of the next successive | | 55 | each of which causes printing of the next successive |
56 | .Ar argument . | | 56 | .Ar argument . |
57 | .Pp | | 57 | .Pp |
58 | The | | 58 | The |
59 | .Ar arguments | | 59 | .Ar arguments |
60 | after the first are treated as strings if the corresponding format is | | 60 | after the first are treated as strings if the corresponding format is |
61 | either | | 61 | either |
62 | .Cm b , | | 62 | .Cm b , |
63 | .Cm B , | | 63 | .Cm B , |
64 | .Cm c , | | 64 | .Cm c , |
65 | or | | 65 | or |
66 | .Cm s ; | | 66 | .Cm s ; |
67 | otherwise it is evaluated as a C constant, with the following extensions: | | 67 | otherwise it is evaluated as a C constant, with the following extensions: |
68 | .Pp | | 68 | .Pp |
69 | .Bl -bullet -offset indent -compact | | 69 | .Bl -bullet -offset indent -compact |
70 | .It | | 70 | .It |
71 | A leading plus or minus sign is allowed. | | 71 | A leading plus or minus sign is allowed. |
72 | .It | | 72 | .It |
73 | If the leading character is a single or double quote, the value is the | | 73 | If the leading character is a single or double quote, the value is the |
74 | .Tn ASCII | | 74 | .Tn ASCII |
75 | code of the next character. | | 75 | code of the next character. |
76 | .El | | 76 | .El |
77 | .Pp | | 77 | .Pp |
78 | The format string is reused as often as necessary to satisfy the | | 78 | The format string is reused as often as necessary to satisfy the |
79 | .Ar arguments . | | 79 | .Ar arguments . |
80 | Any extra format specifications are evaluated with zero or the null | | 80 | Any extra format specifications are evaluated with zero or the null |
81 | string. | | 81 | string. |
82 | .Pp | | 82 | .Pp |
83 | Character escape sequences are in backslash notation as defined in | | 83 | Character escape sequences are in backslash notation as defined in |
84 | .St -ansiC . | | 84 | .St -ansiC . |
85 | The characters and their meanings are as follows: | | 85 | The characters and their meanings are as follows: |
86 | .Bl -tag -width Ds -offset indent | | 86 | .Bl -tag -width Ds -offset indent |
87 | .It Cm \ee | | 87 | .It Cm \ee |
88 | Write an | | 88 | Write an |
89 | .Aq escape | | 89 | .Aq escape |
90 | character. | | 90 | character. |
91 | .It Cm \ea | | 91 | .It Cm \ea |
92 | Write a | | 92 | Write a |
93 | .Aq bell | | 93 | .Aq bell |
94 | character. | | 94 | character. |
95 | .It Cm \eb | | 95 | .It Cm \eb |
96 | Write a | | 96 | Write a |
97 | .Aq backspace | | 97 | .Aq backspace |
98 | character. | | 98 | character. |
99 | .It Cm \ef | | 99 | .It Cm \ef |
100 | Write a | | 100 | Write a |
101 | .Aq form-feed | | 101 | .Aq form-feed |
102 | character. | | 102 | character. |
103 | .It Cm \en | | 103 | .It Cm \en |
104 | Write a | | 104 | Write a |
105 | .Aq new-line | | 105 | .Aq new-line |
106 | character. | | 106 | character. |
107 | .It Cm \er | | 107 | .It Cm \er |
108 | Write a | | 108 | Write a |
109 | .Aq carriage return | | 109 | .Aq carriage return |
110 | character. | | 110 | character. |
111 | .It Cm \et | | 111 | .It Cm \et |
112 | Write a | | 112 | Write a |
113 | .Aq tab | | 113 | .Aq tab |
114 | character. | | 114 | character. |
115 | .It Cm \ev | | 115 | .It Cm \ev |
116 | Write a | | 116 | Write a |
117 | .Aq vertical tab | | 117 | .Aq vertical tab |
118 | character. | | 118 | character. |
119 | .It Cm \e\' | | 119 | .It Cm \e\' |
120 | Write a | | 120 | Write a |
121 | .Aq single quote | | 121 | .Aq single quote |
122 | character. | | 122 | character. |
123 | .It Cm \e" | | 123 | .It Cm \e" |
124 | Write a | | 124 | Write a |
125 | .Aq double quote | | 125 | .Aq double quote |
126 | character. | | 126 | character. |
127 | .It Cm \e\e | | 127 | .It Cm \e\e |
128 | Write a backslash character. | | 128 | Write a backslash character. |
129 | .It Cm \e Ns Ar num | | 129 | .It Cm \e Ns Ar num |
130 | Write an 8\-bit character whose | | 130 | Write an 8\-bit character whose |
131 | .Tn ASCII | | 131 | .Tn ASCII |
132 | value is the 1\-, 2\-, or 3\-digit octal number | | 132 | value is the 1\-, 2\-, or 3\-digit octal number |
133 | .Ar num . | | 133 | .Ar num . |
134 | .It Cm \ex Ns Ar xx | | 134 | .It Cm \ex Ns Ar xx |
135 | Write an 8\-bit character whose | | 135 | Write an 8\-bit character whose |
136 | .Tn ASCII | | 136 | .Tn ASCII |
137 | value is the 1\- or 2\-digit hexadecimal number | | 137 | value is the 1\- or 2\-digit hexadecimal number |
138 | .Ar xx . | | 138 | .Ar xx . |
139 | .El | | 139 | .El |
140 | .Pp | | 140 | .Pp |
141 | Each format specification is introduced by the percent character | | 141 | Each format specification is introduced by the percent character |
142 | .Pq Dq \&% . | | 142 | .Pq Dq \&% . |
143 | The remainder of the format specification includes, | | 143 | The remainder of the format specification includes, |
144 | in the following order: | | 144 | in the following order: |
145 | .Bl -tag -width Ds | | 145 | .Bl -tag -width Ds |
146 | .It Zero or more of the following flags : | | 146 | .It Zero or more of the following flags : |
147 | .Bl -tag -width Ds | | 147 | .Bl -tag -width Ds |
148 | .It Cm # | | 148 | .It Cm # |
149 | A | | 149 | A |
150 | .Sq # | | 150 | .Sq # |
151 | character specifying that the value should be printed in an | | 151 | character specifying that the value should be printed in an |
152 | .Dq alternative form . | | 152 | .Dq alternative form . |
153 | For | | 153 | For |
154 | .Cm b , | | 154 | .Cm b , |
155 | .Cm c , | | 155 | .Cm c , |
156 | .Cm d , | | 156 | .Cm d , |
157 | and | | 157 | and |
158 | .Cm s | | 158 | .Cm s |
159 | formats, this option has no effect. | | 159 | formats, this option has no effect. |
160 | For the | | 160 | For the |
161 | .Cm o | | 161 | .Cm o |
162 | format the precision of the number is increased to force the first | | 162 | format the precision of the number is increased to force the first |
163 | character of the output string to a zero. | | 163 | character of the output string to a zero. |
164 | For the | | 164 | For the |
165 | .Cm x | | 165 | .Cm x |
166 | .Pq Cm X | | 166 | .Pq Cm X |
167 | format, a non-zero result has the string | | 167 | format, a non-zero result has the string |
168 | .Li 0x | | 168 | .Li 0x |
169 | .Pq Li 0X | | 169 | .Pq Li 0X |
170 | prepended to it. | | 170 | prepended to it. |
171 | For | | 171 | For |
172 | .Cm e , | | 172 | .Cm e , |
173 | .Cm E , | | 173 | .Cm E , |
174 | .Cm f , | | 174 | .Cm f , |
175 | .Cm g , | | 175 | .Cm g , |
176 | and | | 176 | and |
177 | .Cm G | | 177 | .Cm G |
178 | formats, the result will always contain a decimal point, even if no | | 178 | formats, the result will always contain a decimal point, even if no |
179 | digits follow the point (normally, a decimal point only appears in the | | 179 | digits follow the point (normally, a decimal point only appears in the |
180 | results of those formats if a digit follows the decimal point). | | 180 | results of those formats if a digit follows the decimal point). |
181 | For | | 181 | For |
182 | .Cm g | | 182 | .Cm g |
183 | and | | 183 | and |
184 | .Cm G | | 184 | .Cm G |
185 | formats, trailing zeros are not removed from the result as they | | 185 | formats, trailing zeros are not removed from the result as they |
186 | would otherwise be. | | 186 | would otherwise be. |
187 | .\" I turned this off - decided it isn't a valid use of '#' | | 187 | .\" I turned this off - decided it isn't a valid use of '#' |
188 | .\" For the | | 188 | .\" For the |
189 | .\" .Cm B | | 189 | .\" .Cm B |
190 | .\" format, backslash-escape sequences are expanded first; | | 190 | .\" format, backslash-escape sequences are expanded first; |
191 | .It Cm \&\- | | 191 | .It Cm \&\- |
192 | A minus sign | | 192 | A minus sign |
193 | .Sq \- | | 193 | .Sq \- |
194 | which specifies | | 194 | which specifies |
195 | .Em left adjustment | | 195 | .Em left adjustment |
196 | of the output in the indicated field; | | 196 | of the output in the indicated field; |
197 | .It Cm \&+ | | 197 | .It Cm \&+ |
198 | A | | 198 | A |
199 | .Sq \&+ | | 199 | .Sq \&+ |
200 | character specifying that there should always be | | 200 | character specifying that there should always be |
201 | a sign placed before the number when using signed formats. | | 201 | a sign placed before the number when using signed formats. |
202 | .It Sq \&\ \& | | 202 | .It Sq \&\ \& |
203 | A space specifying that a blank should be left before a positive number | | 203 | A space specifying that a blank should be left before a positive number |
204 | for a signed format. | | 204 | for a signed format. |
205 | A | | 205 | A |
206 | .Sq \&+ | | 206 | .Sq \&+ |
207 | overrides a space if both are used; | | 207 | overrides a space if both are used; |
208 | .It Cm \&0 | | 208 | .It Cm \&0 |
209 | A zero `0' character indicating that zero-padding should be used | | 209 | A zero `0' character indicating that zero-padding should be used |
210 | rather than blank-padding. | | 210 | rather than blank-padding. |
211 | A | | 211 | A |
212 | .Sq \- | | 212 | .Sq \- |
213 | overrides a | | 213 | overrides a |
214 | .Sq \&0 | | 214 | .Sq \&0 |
215 | if both are used; | | 215 | if both are used; |
216 | .El | | 216 | .El |
217 | .It Field Width : | | 217 | .It Field Width : |
218 | An optional digit string specifying a | | 218 | An optional digit string specifying a |
219 | .Em field width ; | | 219 | .Em field width ; |
220 | if the output string has fewer characters than the field width it will | | 220 | if the output string has fewer characters than the field width it will |
221 | be blank-padded on the left (or right, if the left-adjustment indicator | | 221 | be blank-padded on the left (or right, if the left-adjustment indicator |
222 | has been given) to make up the field width (note that a leading zero | | 222 | has been given) to make up the field width (note that a leading zero |
223 | is a flag, but an embedded zero is part of a field width); | | 223 | is a flag, but an embedded zero is part of a field width); |
224 | .It Precision : | | 224 | .It Precision : |
225 | An optional period, | | 225 | An optional period, |
226 | .Sq Cm \&. , | | 226 | .Sq Cm \&. , |
227 | followed by an optional digit string giving a | | 227 | followed by an optional digit string giving a |
228 | .Em precision | | 228 | .Em precision |
229 | which specifies the number of digits to appear after the decimal point, | | 229 | which specifies the number of digits to appear after the decimal point, |
230 | for | | 230 | for |
231 | .Cm e | | 231 | .Cm e |
232 | and | | 232 | and |
233 | .Cm f | | 233 | .Cm f |
234 | formats, or the maximum number of characters to be printed | | 234 | formats, or the maximum number of characters to be printed |
235 | from a string | | 235 | from a string |
236 | .Sm off | | 236 | .Sm off |
237 | .Pf ( Cm b , | | 237 | .Pf ( Cm b , |
238 | .Sm on | | 238 | .Sm on |
239 | .Cm B , | | 239 | .Cm B , |
240 | and | | 240 | and |
241 | .Cm s | | 241 | .Cm s |
242 | formats); if the digit string is missing, the precision is treated | | 242 | formats); if the digit string is missing, the precision is treated |
243 | as zero; | | 243 | as zero; |
244 | .It Format : | | 244 | .It Format : |
245 | A character which indicates the type of format to use (one of | | 245 | A character which indicates the type of format to use (one of |
246 | .Cm diouxXfwEgGbBcs ) . | | 246 | .Cm diouxXfwEgGbBcs ) . |
247 | .El | | 247 | .El |
248 | .Pp | | 248 | .Pp |
249 | A field width or precision may be | | 249 | A field width or precision may be |
250 | .Sq Cm \&* | | 250 | .Sq Cm \&* |
251 | instead of a digit string. | | 251 | instead of a digit string. |
252 | In this case an | | 252 | In this case an |
253 | .Ar argument | | 253 | .Ar argument |
254 | supplies the field width or precision. | | 254 | supplies the field width or precision. |
255 | .Pp | | 255 | .Pp |
256 | The format characters and their meanings are: | | 256 | The format characters and their meanings are: |
257 | .Bl -tag -width Fl | | 257 | .Bl -tag -width Fl |
258 | .It Cm diouXx | | 258 | .It Cm diouXx |
259 | The | | 259 | The |
260 | .Ar argument | | 260 | .Ar argument |
261 | is printed as a signed decimal (d or i), unsigned octal, unsigned decimal, | | 261 | is printed as a signed decimal (d or i), unsigned octal, unsigned decimal, |
262 | or unsigned hexadecimal (X or x), respectively. | | 262 | or unsigned hexadecimal (X or x), respectively. |
263 | .It Cm f | | 263 | .It Cm f |
264 | The | | 264 | The |
265 | .Ar argument | | 265 | .Ar argument |
266 | is printed in the style | | 266 | is printed in the style |
267 | .Sm off | | 267 | .Sm off |
268 | .Pf [\-]ddd Cm \&. No ddd | | 268 | .Pf [\-]ddd Cm \&. No ddd |
269 | .Sm on | | 269 | .Sm on |
270 | where the number of d's | | 270 | where the number of d's |
271 | after the decimal point is equal to the precision specification for | | 271 | after the decimal point is equal to the precision specification for |
272 | the argument. | | 272 | the argument. |
273 | If the precision is missing, 6 digits are given; if the precision | | 273 | If the precision is missing, 6 digits are given; if the precision |
274 | is explicitly 0, no digits and no decimal point are printed. | | 274 | is explicitly 0, no digits and no decimal point are printed. |
275 | .It Cm eE | | 275 | .It Cm eE |
276 | The | | 276 | The |
277 | .Ar argument | | 277 | .Ar argument |
278 | is printed in the style | | 278 | is printed in the style |
279 | .Sm off | | 279 | .Sm off |
280 | .Pf [\-]d Cm \&. No ddd Cm e No \*(Pmdd | | 280 | .Pf [\-]d Cm \&. No ddd Cm e No \*(Pmdd |
281 | .Sm on | | 281 | .Sm on |
282 | where there | | 282 | where there |
283 | is one digit before the decimal point and the number after is equal to | | 283 | is one digit before the decimal point and the number after is equal to |
284 | the precision specification for the argument; when the precision is | | 284 | the precision specification for the argument; when the precision is |
285 | missing, 6 digits are produced. | | 285 | missing, 6 digits are produced. |
286 | An upper-case E is used for an | | 286 | An upper-case E is used for an |
287 | .Sq E | | 287 | .Sq E |
288 | format. | | 288 | format. |
289 | .It Cm gG | | 289 | .It Cm gG |
290 | The | | 290 | The |
291 | .Ar argument | | 291 | .Ar argument |
292 | is printed in style | | 292 | is printed in style |
293 | .Cm f | | 293 | .Cm f |
294 | or in style | | 294 | or in style |
295 | .Cm e | | 295 | .Cm e |
296 | .Pq Cm E | | 296 | .Pq Cm E |
297 | whichever gives full precision in minimum space. | | 297 | whichever gives full precision in minimum space. |
298 | .It Cm b | | 298 | .It Cm b |
299 | Characters from the string | | 299 | Characters from the string |
300 | .Ar argument | | 300 | .Ar argument |
301 | are printed with backslash-escape sequences expanded. | | 301 | are printed with backslash-escape sequences expanded. |
302 | .Pp | | 302 | .Pp |
303 | The following additional backslash-escape sequences are supported: | | 303 | The following additional backslash-escape sequences are supported: |
304 | .Bl -tag -width Ds | | 304 | .Bl -tag -width Ds |
305 | .It Cm \ec | | 305 | .It Cm \ec |
306 | Causes | | 306 | Causes |
307 | .Nm | | 307 | .Nm |
308 | to ignore any remaining characters in the string operand containing it, | | 308 | to ignore any remaining characters in the string operand containing it, |
309 | any remaining string operands, and any additional characters in | | 309 | any remaining string operands, and any additional characters in |
310 | the format operand. | | 310 | the format operand. |
311 | .It Cm \e0 Ns Ar num | | 311 | .It Cm \e0 Ns Ar num |
312 | Write an 8\-bit character whose | | 312 | Write an 8\-bit character whose |
313 | .Tn ASCII | | 313 | .Tn ASCII |
314 | value is the 1\-, 2\-, or 3\-digit | | 314 | value is the 1\-, 2\-, or 3\-digit |
315 | octal number | | 315 | octal number |
316 | .Ar num . | | 316 | .Ar num . |
317 | .It Cm \e^ Ns Ar c | | 317 | .It Cm \e^ Ns Ar c |
318 | Write the control character | | 318 | Write the control character |
319 | .Ar c . | | 319 | .Ar c . |
320 | Generates characters `\e000' through `\e037`, and `\e177' (from `\e^?'). | | 320 | Generates characters `\e000' through `\e037`, and `\e177' (from `\e^?'). |
321 | .It Cm \eM\- Ns Ar c | | 321 | .It Cm \eM\- Ns Ar c |
322 | Write the character | | 322 | Write the character |
323 | .Ar c | | 323 | .Ar c |
324 | with the 8th bit set. | | 324 | with the 8th bit set. |
325 | Generates characters `\e241' through `\e376`. | | 325 | Generates characters `\e241' through `\e376`. |
326 | .It Cm \eM^ Ns Ar c | | 326 | .It Cm \eM^ Ns Ar c |
327 | Write the control character | | 327 | Write the control character |
328 | .Ar c | | 328 | .Ar c |
329 | with the 8th bit set. | | 329 | with the 8th bit set. |
330 | Generates characters `\e200' through `\e237`, and `\e377' (from `\eM^?'). | | 330 | Generates characters `\e200' through `\e237`, and `\e377' (from `\eM^?'). |
331 | .El | | 331 | .El |
332 | .It Cm B | | 332 | .It Cm B |
333 | Characters from the string | | 333 | Characters from the string |
334 | .Ar argument | | 334 | .Ar argument |
335 | are printed with unprintable characters backslash-escaped using the | | 335 | are printed with unprintable characters backslash-escaped using the |
336 | .Sm off | | 336 | .Sm off |
337 | .Pf ` Cm \e Ar c No ', | | 337 | .Pf ` Cm \e Ar c No ', |
338 | .Pf ` Cm \e^ Ar c No ', | | 338 | .Pf ` Cm \e^ Ar c No ', |
339 | .Pf ` Cm \eM\- Ar c No ' | | 339 | .Pf ` Cm \eM\- Ar c No ' |
340 | or | | 340 | or |
341 | .Pf ` Cm \eM^ Ar c No ', | | 341 | .Pf ` Cm \eM^ Ar c No ', |
342 | .Sm on | | 342 | .Sm on |
343 | formats described above. | | 343 | formats described above. |
344 | .It Cm c | | 344 | .It Cm c |
345 | The first character of | | 345 | The first character of |
346 | .Ar argument | | 346 | .Ar argument |
347 | is printed. | | 347 | is printed. |
348 | .It Cm s | | 348 | .It Cm s |
349 | Characters from the string | | 349 | Characters from the string |
350 | .Ar argument | | 350 | .Ar argument |
351 | are printed until the end is reached or until the number of characters | | 351 | are printed until the end is reached or until the number of characters |
352 | indicated by the precision specification is reached; if the | | 352 | indicated by the precision specification is reached; if the |
353 | precision is omitted, all characters in the string are printed. | | 353 | precision is omitted, all characters in the string are printed. |
354 | .It Cm \&% | | 354 | .It Cm \&% |
355 | Print a `%'; no argument is used. | | 355 | Print a `%'; no argument is used. |
356 | .El | | 356 | .El |
357 | .Pp | | 357 | .Pp |
358 | In no case does a non-existent or small field width cause truncation of | | 358 | In no case does a non-existent or small field width cause truncation of |
359 | a field; padding takes place only if the specified field width exceeds | | 359 | a field; padding takes place only if the specified field width exceeds |
360 | the actual width. | | 360 | the actual width. |
| | | 361 | .Pp |
| | | 362 | If the first character of |
| | | 363 | .Ar format |
| | | 364 | is a dash, |
| | | 365 | .Ar format |
| | | 366 | must be preceded by a word consisting of two dashes (--) to prevent it |
| | | 367 | from being interpreted as an option string. |
361 | .Sh EXIT STATUS | | 368 | .Sh EXIT STATUS |
362 | .Ex -std | | 369 | .Ex -std |
363 | .Sh SEE ALSO | | 370 | .Sh SEE ALSO |
364 | .Xr echo 1 , | | 371 | .Xr echo 1 , |
365 | .Xr printf 3 , | | 372 | .Xr printf 3 , |
366 | .Xr vis 3 , | | 373 | .Xr vis 3 , |
367 | .Xr printf 9 | | 374 | .Xr printf 9 |
368 | .Sh STANDARDS | | 375 | .Sh STANDARDS |
369 | The | | 376 | The |
370 | .Nm | | 377 | .Nm |
371 | utility conforms to | | 378 | utility conforms to |
372 | .St -p1003.1-2001 . | | 379 | .St -p1003.1-2001 . |
373 | .Pp | | 380 | .Pp |
374 | Support for the floating point formats and `*' as a field width and precision | | 381 | Support for the floating point formats and `*' as a field width and precision |
375 | are optional in POSIX. | | 382 | are optional in POSIX. |
376 | .Pp | | 383 | .Pp |
377 | The behaviour of the %B format and the \e', \e", \exxx, \ee and | | 384 | The behaviour of the %B format and the \e', \e", \exxx, \ee and |
378 | \e[M][\-|^]c escape sequences are undefined in POSIX. | | 385 | \e[M][\-|^]c escape sequences are undefined in POSIX. |
379 | .Sh BUGS | | 386 | .Sh BUGS |
380 | Since the floating point numbers are translated from | | 387 | Since the floating point numbers are translated from |
381 | .Tn ASCII | | 388 | .Tn ASCII |
382 | to floating-point and | | 389 | to floating-point and |
383 | then back again, floating-point precision may be lost. | | 390 | then back again, floating-point precision may be lost. |
384 | .Pp | | 391 | .Pp |
385 | Hexadecimal character constants are restricted to, and should be specified | | 392 | Hexadecimal character constants are restricted to, and should be specified |
386 | as, two character constants. | | 393 | as, two character constants. |
387 | This is contrary to the ISO C standard but | | 394 | This is contrary to the ISO C standard but |
388 | does guarantee detection of the end of the constant. | | 395 | does guarantee detection of the end of the constant. |
389 | .Sh NOTES | | 396 | .Sh NOTES |
390 | All formats which treat the | | 397 | All formats which treat the |
391 | .Ar argument | | 398 | .Ar argument |
392 | as a number first convert the | | 399 | as a number first convert the |
393 | .Ar argument | | 400 | .Ar argument |
394 | from its external representation as a character string | | 401 | from its external representation as a character string |
395 | to an internal numeric representation, and then apply the | | 402 | to an internal numeric representation, and then apply the |
396 | format to the internal numeric representation, producing | | 403 | format to the internal numeric representation, producing |
397 | another external character string representation. | | 404 | another external character string representation. |
398 | One might expect the | | 405 | One might expect the |
399 | .Cm \&%c | | 406 | .Cm \&%c |
400 | format to do likewise, but in fact it does not. | | 407 | format to do likewise, but in fact it does not. |
401 | .Pp | | 408 | .Pp |
402 | To convert a string representation of a decimal, octal, or hexadecimal | | 409 | To convert a string representation of a decimal, octal, or hexadecimal |
403 | number into the corresponding character, two nested | | 410 | number into the corresponding character, two nested |
404 | .Nm | | 411 | .Nm |
405 | invocations may be used, in which the inner invocation | | 412 | invocations may be used, in which the inner invocation |
406 | converts the input to an octal string, and the outer | | 413 | converts the input to an octal string, and the outer |
407 | invocation uses the octal string as part of a format. | | 414 | invocation uses the octal string as part of a format. |
408 | For example, the following command outputs the character whose code | | 415 | For example, the following command outputs the character whose code |
409 | is 0x0A, which is a newline in ASCII: | | 416 | is 0x0A, which is a newline in ASCII: |
410 | .Pp | | 417 | .Pp |
411 | .Dl printf \&"$(printf \&"\e\e%o" \&"0x0A")" | | 418 | .Dl printf \&"$(printf \&"\e\e%o" \&"0x0A")" |