Print this page
4818 printf(1) should support n$ width and precision specifiers
4854 printf(1) doesn't support %b and \c properly
Reviewed by: Keith Wesolowski <keith.wesolowski@joyent.com>
Approved by: TBD
Split |
Close |
Expand all |
Collapse all |
--- old/usr/src/man/man1/printf.1
+++ new/usr/src/man/man1/printf.1
1 1 '\" te
2 +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 3 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
3 4 .\" Copyright 1992, X/Open Company Limited All Rights Reserved
4 5 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
5 -.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/.
6 -.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
7 -.\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
8 -.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
9 -.\" This notice shall appear on any product containing this material.
10 -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
11 -.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
12 -.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
13 -.TH PRINTF 1 "Aug 11, 2009"
6 +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
7 +.\" permission to reproduce portions of its copyrighted documentation.
8 +.\" Original documentation from The Open Group can be obtained online at
9 +.\" http://www.opengroup.org/bookstore/.
10 +.\" The Institute of Electrical and Electronics Engineers and The Open Group,
11 +.\" have given us permission to reprint portions of their documentation. In the
12 +.\" following statement, the phrase "this text" refers to portions of the
13 +.\" system documentation. Portions of this text are reprinted and reproduced in
14 +.\" electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004
15 +.\" Edition, Standard for Information Technology -- Portable Operating System
16 +.\" Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright
17 +.\" (C) 2001-2004 by the Institute of Electrical and Electronics Engineers,
18 +.\" Inc and The Open Group. In the event of any discrepancy between these
19 +.\" versions and the original IEEE and The Open Group Standard, the original
20 +.\" IEEE and The Open Group Standard is the referee document. The original
21 +.\" Standard can be obtained online at
22 +.\" http://www.opengroup.org/unix/online.html.
23 +.\" This notice shall appear on any product containing this material.
24 +.\" The contents of this file are subject to the terms of the Common
25 +.\" Development and Distribution License (the "License"). You may not use this
26 +.\" file except in compliance with the License.
27 +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or
28 +.\" http://www.opensolaris.org/os/licensing. See the License for the specific
29 +.\" language governing permissions and limitations under the License.
30 +.\" When distributing Covered Code, include this CDDL HEADER in each file and
31 +.\" include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable,
32 +.\" add the following below this CDDL HEADER, with the fields enclosed by
33 +.\" brackets "[]" replaced with your own identifying information:
34 +.\" Portions Copyright [yyyy] [name of copyright owner]
35 +.TH PRINTF 1 "May 11, 2014"
14 36 .SH NAME
15 37 printf \- write formatted output
16 38 .SH SYNOPSIS
17 39 .SS "/usr/bin/printf"
18 40 .LP
19 41 .nf
20 42 \fBprintf\fR \fIformat\fR [\fIargument\fR]...
21 43 .fi
22 44
23 45 .SS "ksh93"
24 46 .LP
25 47 .nf
26 48 \fBprintf\fR \fIformat\fR [\fIstring\fR...]
27 49 .fi
28 50
29 51 .SH DESCRIPTION
30 52 .SS "/usr/bin/printf"
31 53 .sp
32 54 .LP
33 55 The \fBprintf\fR utility writes each string operand to standard output using
34 56 \fIformat\fR to control the output format.
35 57 .SH OPERANDS
36 58 .SS "/usr/bin/printf"
37 59 .sp
38 60 .LP
39 61 The following operands are supported by \fB/usr/bin/printf\fR:
40 62 .sp
41 63 .ne 2
42 64 .na
43 65 \fB\fIformat\fR\fR
44 66 .ad
45 67 .RS 12n
46 68 A string describing the format to use to write the remaining operands. The
47 69 \fIformat\fR operand is used as the \fIformat\fR string described on the
48 70 \fBformats\fR(5) manual page, with the following exceptions:
49 71 .RS +4
50 72 .TP
51 73 .ie t \(bu
52 74 .el o
53 75 A \fBSPACE\fR character in the format string, in any context other than a flag
54 76 of a conversion specification, is treated as an ordinary character that is
55 77 copied to the output.
56 78 .RE
57 79 .RS +4
58 80 .TP
59 81 .ie t \(bu
60 82 .el o
61 83 A character in the format string is treated as a character, not as a
62 84 \fBSPACE\fR character.
63 85 .RE
64 86 .RS +4
65 87 .TP
66 88 .ie t \(bu
67 89 .el o
68 90 In addition to the escape sequences described on the \fBformats\fR(5) manual
69 91 page (\fB\e\e\fR, \fB\ea\fR, \fB\eb\fR, \fB\ef\fR, \fB\en\fR, \fB\er\fR,
70 92 \fB\et\fR, \fB\ev\fR), \fB\e\fR\fIddd\fR, where \fIddd\fR is a one-, two- or
71 93 three-digit octal number, is written as a byte with the numeric value specified
72 94 by the octal number.
73 95 .RE
74 96 .RS +4
75 97 .TP
76 98 .ie t \(bu
77 99 .el o
78 100 The program does not precede or follow output from the \fBd\fR or \fBu\fR
79 101 conversion specifications with blank characters not specified by the
80 102 \fIformat\fR operand.
81 103 .RE
82 104 .RS +4
↓ open down ↓ |
59 lines elided |
↑ open up ↑ |
83 105 .TP
84 106 .ie t \(bu
85 107 .el o
86 108 The program does not precede output from the \fBo\fR conversion specification
87 109 with zeros not specified by the \fIformat\fR operand.
88 110 .RE
89 111 .RS +4
90 112 .TP
91 113 .ie t \(bu
92 114 .el o
115 +The argument used for the conversion character (or width or precision
116 +parameters, see below) may be taken from the \fIn\fRnth argument instead
117 +of the next unused argument, by specifying \fIn\fR\fB$\fR immediately following
118 +the \fB%\fR character, or the \fB*\fR character (for width or precision
119 +arguments).
120 +If \fIn\fR\fB$\fR appears in any conversions in the format string,
121 +then it must be used for all conversions, including any variable width or
122 +precision specifiers.
123 +.RE
124 +.RS +4
125 +.TP
126 +.ie t \(bu
127 +.el o
128 +The special character \fB*\fR may be used instead of a string of decimal digits
129 +to indicate a minimum field width or a precision. In this case the next
130 +available argument is used (or the \fIn\fRth if the form \fIn\fR\fB$\fR is
131 +used), treating its value as a decimal string.
132 +.RE
133 +.RS +4
134 +.TP
135 +.ie t \(bu
136 +.el o
93 137 An additional conversion character, \fBb\fR, is supported as follows. The
94 138 argument is taken to be a string that can contain backslash-escape sequences.
95 139 The following backslash-escape sequences are supported:
96 140 .RS +4
97 141 .TP
98 142 .ie t \(bu
99 143 .el o
100 144 the escape sequences listed on the \fBformats\fR(5) manual page (\fB\e\e\fR,
101 145 \fB\ea\fR, \fB\eb\fR, \fB\ef\fR, \fB\en\fR, \fB\er\fR, \fB\et\fR, \fB\ev\fR),
102 146 which are converted to the characters they represent
103 147 .RE
104 148 .RS +4
105 149 .TP
106 150 .ie t \(bu
107 151 .el o
108 152 \fB\e0\fR\fIddd\fR, where \fIddd\fR is a zero-, one-, two- or three-digit octal
109 153 number that is converted to a byte with the numeric value specified by the
110 154 octal number
111 155 .RE
112 156 .RS +4
113 157 .TP
114 158 .ie t \(bu
115 159 .el o
116 160 \fB\ec\fR, which is written and causes \fBprintf\fR to ignore any remaining
117 161 characters in the string operand containing it, any remaining string operands
118 162 and any additional characters in the \fIformat\fR operand.
119 163 .RE
120 164 .RE
121 165 The interpretation of a backslash followed by any other sequence of characters
122 166 is unspecified.
↓ open down ↓ |
20 lines elided |
↑ open up ↑ |
123 167 .sp
124 168 Bytes from the converted string are written until the end of the string or the
125 169 number of bytes indicated by the precision specification is reached. If the
126 170 precision is omitted, it is taken to be infinite, so all bytes up to the end of
127 171 the converted string are written. For each specification that consumes an
128 172 argument, the next argument operand is evaluated and converted to the
129 173 appropriate type for the conversion as specified below. The \fIformat\fR
130 174 operand is reused as often as necessary to satisfy the argument operands. Any
131 175 extra \fBc\fR or \fBs\fR conversion specifications are evaluated as if a null
132 176 string argument were supplied; other extra conversion specifications are
133 -evaluated as if a zero argument were supplied. If the \fIformat\fR operand
177 +evaluated as if a zero argument were supplied.
178 +.sp
179 +When there are more argument operands than format specifiers, and the
180 +format includes \fIn\fR\fB$\fR position indicators, then the format is
181 +reprocessed from the beginning as above, but with the argument list starting
182 +from the next argument after the highest \fIn\fRth argument previously
183 +encountered.
184 +.sp
185 +If the \fIformat\fR operand
134 186 contains no conversion specifications and \fIargument\fR operands are present,
135 187 the results are unspecified. If a character sequence in the \fIformat\fR
136 188 operand begins with a \fB%\fR character, but does not form a valid conversion
137 189 specification, the behavior is unspecified.
138 190 .RE
139 191
140 192 .sp
141 193 .ne 2
142 194 .na
143 195 \fB\fIargument\fR\fR
144 196 .ad
145 197 .RS 12n
146 198 The strings to be written to standard output, under the control of
147 199 \fBformat\fR. The \fIargument\fR operands are treated as strings if the
148 200 corresponding conversion character is \fBb\fR, \fBc\fR or \fBs\fR. Otherwise,
149 201 it is evaluated as a C constant, as described by the ISO C standard, with the
150 202 following extensions:
151 203 .RS +4
152 204 .TP
153 205 .ie t \(bu
154 206 .el o
155 207 A leading plus or minus sign is allowed.
156 208 .RE
157 209 .RS +4
158 210 .TP
159 211 .ie t \(bu
160 212 .el o
161 213 If the leading character is a single- or double-quote, the value is the numeric
162 214 value in the underlying codeset of the character following the single- or
163 215 double-quote.
164 216 .RE
165 217 If an argument operand cannot be completely converted into an internal value
166 218 appropriate to the corresponding conversion specification, a diagnostic message
167 219 is written to standard error and the utility does not exit with a zero exit
168 220 status, but continues processing any remaining operands and writes the value
169 221 accumulated at the time the error was detected to standard output.
170 222 .RE
171 223
172 224 .SS "ksh93"
173 225 .sp
174 226 .LP
175 227 The \fIformat\fR operands support the full range of ANSI C/C99/XPG6 formatting
176 228 specifiers as well as additional specifiers:
177 229 .sp
178 230 .ne 2
179 231 .na
180 232 \fB\fB%b\fR\fR
181 233 .ad
182 234 .RS 6n
183 235 Each character in the string operand is processed specially, as follows:
184 236 .sp
185 237 .ne 2
186 238 .na
187 239 \fB\fB\ea\fR\fR
188 240 .ad
189 241 .RS 8n
190 242 Alert character.
191 243 .RE
192 244
193 245 .sp
194 246 .ne 2
195 247 .na
196 248 \fB\fB\eb\fR\fR
197 249 .ad
198 250 .RS 8n
199 251 Backspace character.
200 252 .RE
201 253
202 254 .sp
203 255 .ne 2
204 256 .na
205 257 \fB\fB\ec\fR\fR
206 258 .ad
207 259 .RS 8n
208 260 Terminate output without appending NEWLINE. The remaining string operands are
209 261 ignored.
210 262 .RE
211 263
212 264 .sp
213 265 .ne 2
214 266 .na
215 267 \fB\fB\eE\fR\fR
216 268 .ad
217 269 .RS 8n
218 270 Escape character (\fBASCII\fR octal \fB033\fR).
219 271 .RE
220 272
221 273 .sp
222 274 .ne 2
223 275 .na
224 276 \fB\fB\ef\fR\fR
225 277 .ad
226 278 .RS 8n
227 279 FORM FEED character.
228 280 .RE
229 281
230 282 .sp
231 283 .ne 2
232 284 .na
233 285 \fB\fB\en\fR\fR
234 286 .ad
235 287 .RS 8n
236 288 NEWLINE character.
237 289 .RE
238 290
239 291 .sp
240 292 .ne 2
241 293 .na
242 294 \fB\fB\et\fR\fR
243 295 .ad
244 296 .RS 8n
245 297 TAB character.
246 298 .RE
247 299
248 300 .sp
249 301 .ne 2
250 302 .na
251 303 \fB\fB\ev\fR\fR
252 304 .ad
253 305 .RS 8n
254 306 Vertical tab character.
255 307 .RE
256 308
257 309 .sp
258 310 .ne 2
259 311 .na
260 312 \fB\fB\e\e\fR\fR
261 313 .ad
262 314 .RS 8n
263 315 Backslash character.
264 316 .RE
265 317
266 318 .sp
267 319 .ne 2
268 320 .na
269 321 \fB\fB\e0\fR\fIx\fR\fR
270 322 .ad
271 323 .RS 8n
272 324 The 8-bit character whose \fBASCII\fR code is the \fB1\fR-, \fB2\fR-, or
273 325 \fB3\fR-digit octal number \fIx\fR.
274 326 .RE
275 327
276 328 .RE
277 329
278 330 .sp
279 331 .ne 2
280 332 .na
281 333 \fB\fB%B\fR\fR
282 334 .ad
283 335 .RS 6n
284 336 Treat the argument as a variable name and output the value without converting
285 337 it to a string. This is most useful for variables of type \fB-b\fR.
286 338 .RE
287 339
288 340 .sp
289 341 .ne 2
290 342 .na
291 343 \fB\fB%H\fR\fR
292 344 .ad
293 345 .RS 6n
294 346 Output string with characters \fB<\fR, \fB&\fR, \fB>\fR, \fB"\fR, and
295 347 non-printable characters, properly escaped for use in HTML and XML documents.
296 348 .RE
297 349
298 350 .sp
299 351 .ne 2
300 352 .na
301 353 \fB\fB%P\fR\fR
302 354 .ad
303 355 .RS 6n
304 356 Treat \fIstring\fR as an extended regular expression and convert it to a shell
305 357 pattern.
306 358 .RE
307 359
308 360 .sp
309 361 .ne 2
310 362 .na
311 363 \fB\fB%q\fR\fR
312 364 .ad
313 365 .RS 6n
314 366 Output \fIstring\fR quoted in a manner that it can be read in by the shell to
315 367 get back the same string. However, empty strings resulting from missing string
316 368 operands are not quoted.
317 369 .RE
318 370
319 371 .sp
320 372 .ne 2
321 373 .na
322 374 \fB\fB%R\fR\fR
323 375 .ad
324 376 .RS 6n
325 377 Treat \fIstring\fR as an shell pattern expression and convert it to an extended
326 378 regular expression.
327 379 .RE
328 380
329 381 .sp
330 382 .ne 2
331 383 .na
332 384 \fB\fB%T\fR\fR
333 385 .ad
334 386 .RS 6n
335 387 Treat \fIstring\fR as a date/time string and format it. The \fBT\fR can be
336 388 preceded by (\fIdformat\fR), where \fIdformat\fR is a date format as defined by
337 389 the \fBdate\fR(1) command.
338 390 .RE
339 391
340 392 .sp
341 393 .ne 2
342 394 .na
343 395 \fB\fB%Z\fR\fR
344 396 .ad
345 397 .RS 6n
346 398 Output a byte whose value is \fB0\fR.
347 399 .RE
348 400
349 401 .sp
350 402 .LP
351 403 When performing conversions of \fIstring\fR to satisfy a numeric format
352 404 specifier, if the first character of \fIstring\fR is \fB"or'\fR, the value is
353 405 the numeric value in the underlying code set of the character following the
354 406 \fB"or'\fR. Otherwise, \fIstring\fR is treated like a shell arithmetic
355 407 expression and evaluated.
356 408 .sp
357 409 .LP
358 410 If a \fIstring\fR operand cannot be completely converted into a value
359 411 appropriate for that format specifier, an error occurs, but remaining
360 412 \fIstring\fR operands continue to be processed.
361 413 .sp
362 414 .LP
363 415 In addition to the format specifier extensions, the following extensions of
364 416 ANSI C/C99/XPG6 are permitted in format specifiers:
365 417 .RS +4
366 418 .TP
367 419 .ie t \(bu
368 420 .el o
369 421 The escape sequences \fB\eE\fR and \fB\ee\fR expand to the escape character
370 422 which is octal 033 in ASCII.
371 423 .RE
372 424 .RS +4
373 425 .TP
374 426 .ie t \(bu
375 427 .el o
376 428 The escape sequence \fB\ecx\fR expands to CTRL-x.
377 429 .RE
378 430 .RS +4
↓ open down ↓ |
235 lines elided |
↑ open up ↑ |
379 431 .TP
380 432 .ie t \(bu
381 433 .el o
382 434 The escape sequence \fB\eC[.\fR\fIname\fR\fB\&.]\fR expands to the collating
383 435 element \fIname\fR.
384 436 .RE
385 437 .RS +4
386 438 .TP
387 439 .ie t \(bu
388 440 .el o
389 -The escape sequence \fB\ex{hex}\fRexpands to the character corresponding to the
390 -hexadecimal value \fBhex\fR.
441 +The escape sequence \fB\ex{hex}\fR expands to the character corresponding to
442 +the hexadecimal value \fBhex\fR.
391 443 .RE
392 444 .RS +4
393 445 .TP
394 446 .ie t \(bu
395 447 .el o
396 448 The format modifier flag = can be used to center a field to a specified width.
397 449 When the output is a terminal, the character width is used rather than the
398 450 number of bytes.
399 451 .RE
400 452 .RS +4
401 453 .TP
402 454 .ie t \(bu
403 455 .el o
404 456 Each of the integral format specifiers can have a third modifier after width
405 457 and precision that specifies the base of the conversion from 2 to 64. In this
406 458 case, the \fB#\fR modifier causes \fIbase\fR\fB#\fR to be prepended to the
407 459 value.
408 460 .RE
409 461 .RS +4
410 462 .TP
411 463 .ie t \(bu
412 464 .el o
413 465 The \fB#\fR modifier can be used with the \fBd\fR specifier when no base is
414 466 specified to cause the output to be written in units of 1000 with a suffix of
415 467 one of \fBk M G T P E\fR.
416 468 .RE
417 469 .RS +4
418 470 .TP
419 471 .ie t \(bu
420 472 .el o
421 473 The \fB#\fR modifier can be used with the \fBi\fR specifier to cause the output
422 474 to be written in units of \fB1024\fR with a suffix of one of \fBKi Mi Gi Ti Pi
423 475 Ei\fR.
↓ open down ↓ |
23 lines elided |
↑ open up ↑ |
424 476 .RE
425 477 .sp
426 478 .LP
427 479 If there are more \fIstring\fR operands than format specifiers, the format
428 480 string is reprocessed from the beginning. If there are fewer \fIstring\fR
429 481 operands than format specifiers, then \fIstring\fR specifiers are treated as if
430 482 empty strings were supplied, numeric conversions are treated as if \fB0\fR was
431 483 supplied, and time conversions are treated as if \fBnow\fR was supplied.
432 484 .sp
433 485 .LP
486 +When there are more argument operands than format specifiers, and the
487 +format includes \fIn\fR\fB$\fR position indicators, then the format is
488 +reprocessed from the beginning as above, but with the argument list starting
489 +from the next argument after the highest \fIn\fRth argument previously
490 +encountered.
491 +.sp
492 +.LP
434 493 \fB/usr/bin/printf\fR is equivalent to \fBksh93\fR's \fBprintf\fR built-in and
435 494 \fBprint -f\fR, which allows additional options to be specified.
436 495 .SH USAGE
437 496 .SS "/usr/bin/printf"
438 497 .sp
439 498 .LP
440 499 The \fBprintf\fR utility, like the \fBprintf\fR(3C) function on which it is
441 500 based, makes no special provision for dealing with multi-byte characters when
442 501 using the \fB%c\fR conversion specification. Applications should be extremely
443 502 cautious using either of these features when there are multi-byte characters in
444 503 the character set.
445 504 .sp
446 505 .LP
447 -Field widths and precisions cannot be specified as \fB*\fR.
448 -.sp
449 -.LP
450 506 The \fB%b\fR conversion specification is not part of the ISO C standard; it has
451 507 been added here as a portable way to process backslash escapes expanded in
452 508 string operands as provided by the \fBecho\fR utility. See also the USAGE
453 509 section of the \fBecho\fR(1) manual page for ways to use \fBprintf\fR as a
454 510 replacement for all of the traditional versions of the \fBecho\fR utility.
455 511 .sp
456 512 .LP
457 513 If an argument cannot be parsed correctly for the corresponding conversion
458 514 specification, the \fBprintf\fR utility reports an error. Thus, overflow and
459 515 extraneous characters at the end of an argument being used for a numeric
460 516 conversion are to be reported as errors.
461 517 .sp
462 518 .LP
463 519 It is not considered an error if an argument operand is not completely used for
464 520 a \fBc\fR or \fBs\fR conversion or if a string operand's first or second
465 521 character is used to get the numeric value of a character.
466 522 .SH EXAMPLES
467 523 .SS "/usr/bin/printf"
468 524 .LP
469 525 \fBExample 1 \fRPrinting a Series of Prompts
470 526 .sp
471 527 .LP
472 528 The following example alerts the user, then prints and reads a series of
473 529 prompts:
474 530
475 531 .sp
476 532 .in +2
477 533 .nf
478 534 example% \fBprintf "\eaPlease fill in the following: \enName: "
479 535 read name
480 536 printf "Phone number: "
481 537 read phone\fR
482 538 .fi
483 539 .in -2
484 540 .sp
485 541
486 542 .LP
487 543 \fBExample 2 \fRPrinting a Table of Calculations
488 544 .sp
489 545 .LP
490 546 The following example prints a table of calculations. It reads out a list of
491 547 right and wrong answers from a file, calculates the percentage correctly, and
492 548 prints them out. The numbers are right-justified and separated by a single tab
493 549 character. The percentage is written to one decimal place of accuracy:
494 550
495 551 .sp
496 552 .in +2
497 553 .nf
498 554 example% \fBwhile read right wrong ; do
499 555 percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc)
500 556 printf "%2d right\et%2d wrong\et(%s%%)\en" \e
501 557 $right $wrong $percent
502 558 done < database_file\fR
503 559 .fi
504 560 .in -2
505 561 .sp
506 562
507 563 .LP
508 564 \fBExample 3 \fRPrinting number strings
509 565 .sp
510 566 .LP
511 567 The command:
512 568
513 569 .sp
514 570 .in +2
515 571 .nf
516 572 example% \fBprintf "%5d%4d\en" 1 21 321 4321 54321\fR
517 573 .fi
518 574 .in -2
519 575 .sp
520 576
521 577 .sp
522 578 .LP
523 579 produces:
524 580
525 581 .sp
526 582 .in +2
527 583 .nf
528 584 1 21
529 585 3214321
530 586 54321 0
531 587 .fi
532 588 .in -2
533 589 .sp
534 590
535 591 .sp
536 592 .LP
537 593 The \fIformat\fR operand is used three times to print all of the given strings
538 594 and that a \fB0\fR was supplied by \fBprintf\fR to satisfy the last \fB%4d\fR
539 595 conversion specification.
540 596
541 597 .LP
542 598 \fBExample 4 \fRTabulating Conversion Errors
543 599 .sp
544 600 .LP
545 601 The following example tabulates conversion errors.
546 602
547 603 .sp
548 604 .LP
549 605 The \fBprintf\fR utility tells the user when conversion errors are detected
550 606 while producing numeric output. These results would be expected on an
551 607 implementation with 32-bit twos-complement integers when \fB%d\fR is specified
552 608 as the \fIformat\fR operand:
553 609
554 610 .sp
555 611
556 612 .sp
557 613 .TS
558 614 box;
559 615 c c c
560 616 l l l .
561 617 Arguments Standard Diagnostic
562 618 5a 5 printf: 5a not completely converted
563 619 9999999999 2147483647 printf: 9999999999: Results too large
564 620 -9999999999 -2147483648 printf: -9999999999: Results too large
565 621 ABC 0 printf: ABC expected numeric value
566 622 .TE
567 623
568 624 .sp
569 625 .LP
570 626 The value shown on standard output is what would be expected as the return
571 627 value from the function \fBstrtol\fR(3C). A similar correspondence exists
572 628 between \fB%u\fR and \fBstrtoul\fR(3C), and \fB%e\fR, \fB%f\fR and \fB%g\fR and
573 629 \fBstrtod\fR(3C).
574 630
575 631 .LP
576 632 \fBExample 5 \fRPrinting Output for a Specific Locale
577 633 .sp
578 634 .LP
579 635 The following example prints output for a specific locale. In a locale using
580 636 the ISO/IEC 646:1991 standard as the underlying codeset, the command:
581 637
582 638 .sp
583 639 .in +2
584 640 .nf
585 641 example% \fBprintf "%d\en" 3 +3 -3 \e'3 \e"+3 "'-3"\fR
586 642 .fi
587 643 .in -2
588 644 .sp
589 645
590 646 .sp
591 647 .LP
592 648 produces:
593 649
594 650 .sp
595 651
596 652 .sp
597 653 .TS
598 654 box;
599 655 l l
600 656 l l .
601 657 \fB3\fR Numeric value of constant 3
602 658 \fB3\fR Numeric value of constant 3
603 659 \fB\(mi3\fR Numeric value of constant \(mi3
604 660 \fB51\fR T{
605 661 Numeric value of the character `3' in the ISO/IEC 646:1991 standard codeset
606 662 T}
607 663 \fB43\fR T{
608 664 Numeric value of the character `+' in the ISO/IEC 646:1991 standard codeset
609 665 T}
610 666 \fB45\fR T{
611 667 Numeric value of the character `\(mi' in the SO/IEC 646:1991 standard codeset
612 668 T}
613 669 .TE
614 670
615 671 .sp
616 672 .LP
617 673 In a locale with multi-byte characters, the value of a character is intended to
618 674 be the value of the equivalent of the \fBwchar_t\fR representation of the
619 675 character.
620 676
621 677 .sp
622 678 .LP
623 679 If an argument operand cannot be completely converted into an internal value
624 680 appropriate to the corresponding conversion specification, a diagnostic message
625 681 is written to standard error and the utility does exit with a zero exit status,
626 682 but continues processing any remaining operands and writes the value
627 683 accumulated at the time the error was detected to standard output.
628 684
629 685 .LP
630 686 \fBExample 6 \fRAlternative floating point representation 1
631 687 .sp
632 688 .LP
633 689 The \fBprintf\fR utility supports an alternative floating point representation
634 690 (see \fBprintf\fR(3C) entry for the "\fB%a\fR"/"\fB%A\fR"), which allows the
635 691 output of floating-point values in a format that avoids the usual base16 to
636 692 base10 rounding errors.
637 693
638 694 .sp
639 695 .in +2
640 696 .nf
641 697 example% printf "%a\en" 2 3.1 NaN
642 698 .fi
643 699 .in -2
644 700 .sp
645 701
646 702 .sp
647 703 .LP
648 704 produces:
649 705
650 706 .sp
651 707 .in +2
652 708 .nf
653 709 0x1.0000000000000000000000000000p+01
654 710 0x1.8ccccccccccccccccccccccccccdp+01
655 711 nan
656 712 .fi
657 713 .in -2
658 714 .sp
659 715
660 716 .LP
661 717 \fBExample 7 \fRAlternative floating point representation 2
662 718 .sp
663 719 .LP
664 720 The following example shows two different representations of the same
665 721 floating-point value.
666 722
667 723 .sp
668 724 .in +2
669 725 .nf
670 726 example% x=2 ; printf "%f == %a\en" x x
671 727 .fi
672 728 .in -2
673 729 .sp
674 730
675 731 .sp
676 732 .LP
677 733 produces:
678 734
679 735 .sp
680 736 .in +2
681 737 .nf
682 738 2.000000 == 0x1.0000000000000000000000000000p+01
683 739 .fi
684 740 .in -2
685 741 .sp
686 742
687 743 .LP
688 744 \fBExample 8 \fROutput of unicode values
689 745 .sp
690 746 .LP
691 747 The following command will print the EURO unicode symbol (code-point 0x20ac).
692 748
693 749 .sp
694 750 .in +2
695 751 .nf
696 752 example% LC_ALL=en_US.UTF-8 printf "\u[20ac]\en"
697 753 .fi
698 754 .in -2
699 755 .sp
700 756
701 757 .sp
702 758 .LP
703 759 produces:
704 760
705 761 .sp
706 762 .in +2
707 763 .nf
708 764 <euro>
709 765 .fi
710 766 .in -2
711 767 .sp
712 768
713 769 .sp
714 770 .LP
715 771 where "<euro>" represents the EURO currency symbol character.
716 772
717 773 .LP
718 774 \fBExample 9 \fRConvert unicode character to unicode code-point value
719 775 .sp
720 776 .LP
721 777 The following command will print the hexadecimal value of a given character.
722 778
723 779 .sp
724 780 .in +2
725 781 .nf
726 782 example% export LC_ALL=en_US.UTF-8
727 783 example% printf "%x\en" "'<euro>"
728 784 .fi
729 785 .in -2
730 786 .sp
731 787
732 788 .sp
733 789 .LP
734 790 where "<euro>" represents the EURO currency symbol character (code-point
735 791 0x20ac).
736 792
737 793 .sp
738 794 .LP
739 795 produces:
740 796
741 797 .sp
742 798 .in +2
743 799 .nf
744 800 20ac
745 801 .fi
746 802 .in -2
747 803 .sp
748 804
749 805 .LP
750 806 \fBExample 10 \fRPrint the numeric value of an ASCII character
751 807 .sp
752 808 .in +2
753 809 .nf
754 810 example% printf "%d\en" "'A"
755 811 .fi
756 812 .in -2
757 813 .sp
758 814
759 815 .sp
760 816 .LP
761 817 produces:
762 818
763 819 .sp
764 820 .in +2
765 821 .nf
766 822 65
767 823 .fi
768 824 .in -2
769 825 .sp
770 826
771 827 .LP
772 828 \fBExample 11 \fRPrint the language-independent date and time format
773 829 .sp
774 830 .LP
775 831 To print the language-independent date and time format, the following statement
776 832 could be used:
777 833
778 834 .sp
779 835 .in +2
780 836 .nf
781 837 example% printf "format" weekday month day hour min
782 838 .fi
783 839 .in -2
784 840 .sp
785 841
786 842 .sp
787 843 .LP
788 844 For example,
789 845
790 846 .sp
791 847 .in +2
792 848 .nf
793 849 $ printf format "Sunday" "July" 3 10 2
794 850 .fi
795 851 .in -2
796 852 .sp
797 853
798 854 .sp
799 855 .LP
800 856 For American usage, format could be the string:
801 857
802 858 .sp
803 859 .in +2
804 860 .nf
805 861 "%s, %s %d, %d:%.2d\en"
806 862 .fi
807 863 .in -2
808 864 .sp
809 865
810 866 .sp
811 867 .LP
812 868 producing the message:
813 869
814 870 .sp
815 871 .in +2
816 872 .nf
817 873 Sunday, July 3, 10:02
818 874 .fi
819 875 .in -2
820 876 .sp
821 877
822 878 .sp
823 879 .LP
824 880 Whereas for EU usage, format could be the string:
825 881
826 882 .sp
827 883 .in +2
828 884 .nf
829 885 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
830 886 .fi
↓ open down ↓ |
371 lines elided |
↑ open up ↑ |
831 887 .in -2
832 888 .sp
833 889
834 890 .sp
835 891 .LP
836 892 Note that the '$' characters must be properly escaped, such as
837 893
838 894 .sp
839 895 .in +2
840 896 .nf
841 -"%1\$s, %3\$d. %2\$s, %4\$d:%5\$.2d\en" in this case
897 +"%1\e$s, %3\e$d. %2\e$s, %4\e$d:%5\e$.2d\en" in this case
842 898 .fi
843 899 .in -2
844 900 .sp
845 901
846 902 .sp
847 903 .LP
848 904 producing the message:
849 905
850 906 .sp
851 907 .in +2
852 908 .nf
853 909 Sunday, 3. July, 10:02
854 910 .fi
855 911 .in -2
856 912 .sp
857 913
858 914 .SH ENVIRONMENT VARIABLES
859 915 .sp
860 916 .LP
861 917 See \fBenviron\fR(5) for descriptions of the following environment variables
862 918 that affect the execution of \fBprintf\fR: \fBLANG\fR, \fBLC_ALL\fR,
863 919 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, \fBLC_NUMERIC\fR, and \fBNLSPATH\fR.
864 920 .SH EXIT STATUS
865 921 .sp
866 922 .LP
867 923 The following exit values are returned:
868 924 .sp
869 925 .ne 2
870 926 .na
871 927 \fB\fB0\fR\fR
872 928 .ad
873 929 .RS 6n
874 930 Successful completion.
875 931 .RE
876 932
877 933 .sp
878 934 .ne 2
879 935 .na
880 936 \fB\fB>0\fR\fR
881 937 .ad
882 938 .RS 6n
883 939 An error occurred.
884 940 .RE
885 941
886 942 .SH ATTRIBUTES
887 943 .sp
888 944 .LP
889 945 See \fBattributes\fR(5) for descriptions of the following attributes:
890 946 .SS "/usr/bin/printf"
891 947 .sp
892 948
893 949 .sp
894 950 .TS
895 951 box;
896 952 c | c
897 953 l | l .
898 954 ATTRIBUTE TYPE ATTRIBUTE VALUE
899 955 _
900 956 CSI Enabled
901 957 _
902 958 Interface Stability Committed
903 959 _
904 960 Standard See \fBstandards\fR(5).
905 961 .TE
906 962
907 963 .SS "ksh93"
908 964 .sp
909 965
910 966 .sp
911 967 .TS
912 968 box;
913 969 c | c
914 970 l | l .
915 971 ATTRIBUTE TYPE ATTRIBUTE VALUE
916 972 _
917 973 Interface Stability Uncommitted
918 974 .TE
919 975
920 976 .SH SEE ALSO
921 977 .sp
922 978 .LP
923 979 \fBawk\fR(1), \fBbc\fR(1), \fBdate\fR(1), \fBecho\fR(1), \fBksh93\fR(1),
924 980 \fBprintf\fR(3C), \fBstrtod\fR(3C), \fBstrtol\fR(3C), \fBstrtoul\fR(3C),
925 981 \fBattributes\fR(5), \fBenviron\fR(5), \fBformats\fR(5), \fBstandards\fR(5)
926 982 .SH NOTES
927 983 .sp
928 984 .LP
929 985 Using format specifiers (characters following '%') which are not listed in the
930 986 \fBprintf\fR(3C) or this manual page will result in undefined behavior.
931 987 .sp
932 988 .LP
933 989 Using escape sequences (the character following a backslash ('\e')) which are
934 990 not listed in the \fBprintf\fR(3C) or this manual page will result in undefined
935 991 behavior.
936 992 .sp
937 993 .LP
938 994 Floating-point values follow C99, XPG6 and IEEE 754 standard behavior and can
939 995 handle values the same way as the platform's |\fBlong double\fR| datatype.
940 996 .sp
941 997 .LP
942 998 Floating-point values handle the sign separately which allows signs for values
943 999 like NaN (for example, -nan), Infinite (for example, -inf) and zero (for
944 1000 example, -0.0).
↓ open down ↓ |
93 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX