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