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