1 '\" te
2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
3 .\" Copyright 1992, X/Open Company Limited All Rights Reserved
4 .\" 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"
14 .SH NAME
15 printf \- write formatted output
16 .SH SYNOPSIS
17 .SS "/usr/bin/printf"
18 .LP
19 .nf
20 \fBprintf\fR \fIformat\fR [\fIargument\fR]...
21 .fi
22
23 .SS "ksh93"
24 .LP
25 .nf
26 \fBprintf\fR \fIformat\fR [\fIstring\fR...]
27 .fi
28
29 .SH DESCRIPTION
30 .SS "/usr/bin/printf"
31 .sp
32 .LP
33 The \fBprintf\fR utility writes each string operand to standard output using
73 .RE
74 .RS +4
75 .TP
76 .ie t \(bu
77 .el o
78 The program does not precede or follow output from the \fBd\fR or \fBu\fR
79 conversion specifications with blank characters not specified by the
80 \fIformat\fR operand.
81 .RE
82 .RS +4
83 .TP
84 .ie t \(bu
85 .el o
86 The program does not precede output from the \fBo\fR conversion specification
87 with zeros not specified by the \fIformat\fR operand.
88 .RE
89 .RS +4
90 .TP
91 .ie t \(bu
92 .el o
93 An additional conversion character, \fBb\fR, is supported as follows. The
94 argument is taken to be a string that can contain backslash-escape sequences.
95 The following backslash-escape sequences are supported:
96 .RS +4
97 .TP
98 .ie t \(bu
99 .el o
100 the escape sequences listed on the \fBformats\fR(5) manual page (\fB\e\e\fR,
101 \fB\ea\fR, \fB\eb\fR, \fB\ef\fR, \fB\en\fR, \fB\er\fR, \fB\et\fR, \fB\ev\fR),
102 which are converted to the characters they represent
103 .RE
104 .RS +4
105 .TP
106 .ie t \(bu
107 .el o
108 \fB\e0\fR\fIddd\fR, where \fIddd\fR is a zero-, one-, two- or three-digit octal
109 number that is converted to a byte with the numeric value specified by the
110 octal number
111 .RE
112 .RS +4
113 .TP
114 .ie t \(bu
115 .el o
116 \fB\ec\fR, which is written and causes \fBprintf\fR to ignore any remaining
117 characters in the string operand containing it, any remaining string operands
118 and any additional characters in the \fIformat\fR operand.
119 .RE
120 .RE
121 The interpretation of a backslash followed by any other sequence of characters
122 is unspecified.
123 .sp
124 Bytes from the converted string are written until the end of the string or the
125 number of bytes indicated by the precision specification is reached. If the
126 precision is omitted, it is taken to be infinite, so all bytes up to the end of
127 the converted string are written. For each specification that consumes an
128 argument, the next argument operand is evaluated and converted to the
129 appropriate type for the conversion as specified below. The \fIformat\fR
130 operand is reused as often as necessary to satisfy the argument operands. Any
131 extra \fBc\fR or \fBs\fR conversion specifications are evaluated as if a null
132 string argument were supplied; other extra conversion specifications are
133 evaluated as if a zero argument were supplied. If the \fIformat\fR operand
134 contains no conversion specifications and \fIargument\fR operands are present,
135 the results are unspecified. If a character sequence in the \fIformat\fR
136 operand begins with a \fB%\fR character, but does not form a valid conversion
137 specification, the behavior is unspecified.
138 .RE
139
140 .sp
141 .ne 2
142 .na
143 \fB\fIargument\fR\fR
144 .ad
145 .RS 12n
146 The strings to be written to standard output, under the control of
147 \fBformat\fR. The \fIargument\fR operands are treated as strings if the
148 corresponding conversion character is \fBb\fR, \fBc\fR or \fBs\fR. Otherwise,
149 it is evaluated as a C constant, as described by the ISO C standard, with the
150 following extensions:
151 .RS +4
152 .TP
153 .ie t \(bu
369 The escape sequences \fB\eE\fR and \fB\ee\fR expand to the escape character
370 which is octal 033 in ASCII.
371 .RE
372 .RS +4
373 .TP
374 .ie t \(bu
375 .el o
376 The escape sequence \fB\ecx\fR expands to CTRL-x.
377 .RE
378 .RS +4
379 .TP
380 .ie t \(bu
381 .el o
382 The escape sequence \fB\eC[.\fR\fIname\fR\fB\&.]\fR expands to the collating
383 element \fIname\fR.
384 .RE
385 .RS +4
386 .TP
387 .ie t \(bu
388 .el o
389 The escape sequence \fB\ex{hex}\fRexpands to the character corresponding to the
390 hexadecimal value \fBhex\fR.
391 .RE
392 .RS +4
393 .TP
394 .ie t \(bu
395 .el o
396 The format modifier flag = can be used to center a field to a specified width.
397 When the output is a terminal, the character width is used rather than the
398 number of bytes.
399 .RE
400 .RS +4
401 .TP
402 .ie t \(bu
403 .el o
404 Each of the integral format specifiers can have a third modifier after width
405 and precision that specifies the base of the conversion from 2 to 64. In this
406 case, the \fB#\fR modifier causes \fIbase\fR\fB#\fR to be prepended to the
407 value.
408 .RE
409 .RS +4
410 .TP
414 specified to cause the output to be written in units of 1000 with a suffix of
415 one of \fBk M G T P E\fR.
416 .RE
417 .RS +4
418 .TP
419 .ie t \(bu
420 .el o
421 The \fB#\fR modifier can be used with the \fBi\fR specifier to cause the output
422 to be written in units of \fB1024\fR with a suffix of one of \fBKi Mi Gi Ti Pi
423 Ei\fR.
424 .RE
425 .sp
426 .LP
427 If there are more \fIstring\fR operands than format specifiers, the format
428 string is reprocessed from the beginning. If there are fewer \fIstring\fR
429 operands than format specifiers, then \fIstring\fR specifiers are treated as if
430 empty strings were supplied, numeric conversions are treated as if \fB0\fR was
431 supplied, and time conversions are treated as if \fBnow\fR was supplied.
432 .sp
433 .LP
434 \fB/usr/bin/printf\fR is equivalent to \fBksh93\fR's \fBprintf\fR built-in and
435 \fBprint -f\fR, which allows additional options to be specified.
436 .SH USAGE
437 .SS "/usr/bin/printf"
438 .sp
439 .LP
440 The \fBprintf\fR utility, like the \fBprintf\fR(3C) function on which it is
441 based, makes no special provision for dealing with multi-byte characters when
442 using the \fB%c\fR conversion specification. Applications should be extremely
443 cautious using either of these features when there are multi-byte characters in
444 the character set.
445 .sp
446 .LP
447 Field widths and precisions cannot be specified as \fB*\fR.
448 .sp
449 .LP
450 The \fB%b\fR conversion specification is not part of the ISO C standard; it has
451 been added here as a portable way to process backslash escapes expanded in
452 string operands as provided by the \fBecho\fR utility. See also the USAGE
453 section of the \fBecho\fR(1) manual page for ways to use \fBprintf\fR as a
454 replacement for all of the traditional versions of the \fBecho\fR utility.
455 .sp
456 .LP
457 If an argument cannot be parsed correctly for the corresponding conversion
458 specification, the \fBprintf\fR utility reports an error. Thus, overflow and
459 extraneous characters at the end of an argument being used for a numeric
460 conversion are to be reported as errors.
461 .sp
462 .LP
463 It is not considered an error if an argument operand is not completely used for
464 a \fBc\fR or \fBs\fR conversion or if a string operand's first or second
465 character is used to get the numeric value of a character.
466 .SH EXAMPLES
467 .SS "/usr/bin/printf"
468 .LP
469 \fBExample 1 \fRPrinting a Series of Prompts
821
822 .sp
823 .LP
824 Whereas for EU usage, format could be the string:
825
826 .sp
827 .in +2
828 .nf
829 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
830 .fi
831 .in -2
832 .sp
833
834 .sp
835 .LP
836 Note that the '$' characters must be properly escaped, such as
837
838 .sp
839 .in +2
840 .nf
841 "%1\$s, %3\$d. %2\$s, %4\$d:%5\$.2d\en" in this case
842 .fi
843 .in -2
844 .sp
845
846 .sp
847 .LP
848 producing the message:
849
850 .sp
851 .in +2
852 .nf
853 Sunday, 3. July, 10:02
854 .fi
855 .in -2
856 .sp
857
858 .SH ENVIRONMENT VARIABLES
859 .sp
860 .LP
861 See \fBenviron\fR(5) for descriptions of the following environment variables
|
1 '\" te
2 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
3 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
4 .\" Copyright 1992, X/Open Company Limited All Rights Reserved
5 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
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"
36 .SH NAME
37 printf \- write formatted output
38 .SH SYNOPSIS
39 .SS "/usr/bin/printf"
40 .LP
41 .nf
42 \fBprintf\fR \fIformat\fR [\fIargument\fR]...
43 .fi
44
45 .SS "ksh93"
46 .LP
47 .nf
48 \fBprintf\fR \fIformat\fR [\fIstring\fR...]
49 .fi
50
51 .SH DESCRIPTION
52 .SS "/usr/bin/printf"
53 .sp
54 .LP
55 The \fBprintf\fR utility writes each string operand to standard output using
95 .RE
96 .RS +4
97 .TP
98 .ie t \(bu
99 .el o
100 The program does not precede or follow output from the \fBd\fR or \fBu\fR
101 conversion specifications with blank characters not specified by the
102 \fIformat\fR operand.
103 .RE
104 .RS +4
105 .TP
106 .ie t \(bu
107 .el o
108 The program does not precede output from the \fBo\fR conversion specification
109 with zeros not specified by the \fIformat\fR operand.
110 .RE
111 .RS +4
112 .TP
113 .ie t \(bu
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
137 An additional conversion character, \fBb\fR, is supported as follows. The
138 argument is taken to be a string that can contain backslash-escape sequences.
139 The following backslash-escape sequences are supported:
140 .RS +4
141 .TP
142 .ie t \(bu
143 .el o
144 the escape sequences listed on the \fBformats\fR(5) manual page (\fB\e\e\fR,
145 \fB\ea\fR, \fB\eb\fR, \fB\ef\fR, \fB\en\fR, \fB\er\fR, \fB\et\fR, \fB\ev\fR),
146 which are converted to the characters they represent
147 .RE
148 .RS +4
149 .TP
150 .ie t \(bu
151 .el o
152 \fB\e0\fR\fIddd\fR, where \fIddd\fR is a zero-, one-, two- or three-digit octal
153 number that is converted to a byte with the numeric value specified by the
154 octal number
155 .RE
156 .RS +4
157 .TP
158 .ie t \(bu
159 .el o
160 \fB\ec\fR, which is written and causes \fBprintf\fR to ignore any remaining
161 characters in the string operand containing it, any remaining string operands
162 and any additional characters in the \fIformat\fR operand.
163 .RE
164 .RE
165 The interpretation of a backslash followed by any other sequence of characters
166 is unspecified.
167 .sp
168 Bytes from the converted string are written until the end of the string or the
169 number of bytes indicated by the precision specification is reached. If the
170 precision is omitted, it is taken to be infinite, so all bytes up to the end of
171 the converted string are written. For each specification that consumes an
172 argument, the next argument operand is evaluated and converted to the
173 appropriate type for the conversion as specified below. The \fIformat\fR
174 operand is reused as often as necessary to satisfy the argument operands. Any
175 extra \fBc\fR or \fBs\fR conversion specifications are evaluated as if a null
176 string argument were supplied; other extra conversion specifications are
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
186 contains no conversion specifications and \fIargument\fR operands are present,
187 the results are unspecified. If a character sequence in the \fIformat\fR
188 operand begins with a \fB%\fR character, but does not form a valid conversion
189 specification, the behavior is unspecified.
190 .RE
191
192 .sp
193 .ne 2
194 .na
195 \fB\fIargument\fR\fR
196 .ad
197 .RS 12n
198 The strings to be written to standard output, under the control of
199 \fBformat\fR. The \fIargument\fR operands are treated as strings if the
200 corresponding conversion character is \fBb\fR, \fBc\fR or \fBs\fR. Otherwise,
201 it is evaluated as a C constant, as described by the ISO C standard, with the
202 following extensions:
203 .RS +4
204 .TP
205 .ie t \(bu
421 The escape sequences \fB\eE\fR and \fB\ee\fR expand to the escape character
422 which is octal 033 in ASCII.
423 .RE
424 .RS +4
425 .TP
426 .ie t \(bu
427 .el o
428 The escape sequence \fB\ecx\fR expands to CTRL-x.
429 .RE
430 .RS +4
431 .TP
432 .ie t \(bu
433 .el o
434 The escape sequence \fB\eC[.\fR\fIname\fR\fB\&.]\fR expands to the collating
435 element \fIname\fR.
436 .RE
437 .RS +4
438 .TP
439 .ie t \(bu
440 .el o
441 The escape sequence \fB\ex{hex}\fR expands to the character corresponding to
442 the hexadecimal value \fBhex\fR.
443 .RE
444 .RS +4
445 .TP
446 .ie t \(bu
447 .el o
448 The format modifier flag = can be used to center a field to a specified width.
449 When the output is a terminal, the character width is used rather than the
450 number of bytes.
451 .RE
452 .RS +4
453 .TP
454 .ie t \(bu
455 .el o
456 Each of the integral format specifiers can have a third modifier after width
457 and precision that specifies the base of the conversion from 2 to 64. In this
458 case, the \fB#\fR modifier causes \fIbase\fR\fB#\fR to be prepended to the
459 value.
460 .RE
461 .RS +4
462 .TP
466 specified to cause the output to be written in units of 1000 with a suffix of
467 one of \fBk M G T P E\fR.
468 .RE
469 .RS +4
470 .TP
471 .ie t \(bu
472 .el o
473 The \fB#\fR modifier can be used with the \fBi\fR specifier to cause the output
474 to be written in units of \fB1024\fR with a suffix of one of \fBKi Mi Gi Ti Pi
475 Ei\fR.
476 .RE
477 .sp
478 .LP
479 If there are more \fIstring\fR operands than format specifiers, the format
480 string is reprocessed from the beginning. If there are fewer \fIstring\fR
481 operands than format specifiers, then \fIstring\fR specifiers are treated as if
482 empty strings were supplied, numeric conversions are treated as if \fB0\fR was
483 supplied, and time conversions are treated as if \fBnow\fR was supplied.
484 .sp
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
493 \fB/usr/bin/printf\fR is equivalent to \fBksh93\fR's \fBprintf\fR built-in and
494 \fBprint -f\fR, which allows additional options to be specified.
495 .SH USAGE
496 .SS "/usr/bin/printf"
497 .sp
498 .LP
499 The \fBprintf\fR utility, like the \fBprintf\fR(3C) function on which it is
500 based, makes no special provision for dealing with multi-byte characters when
501 using the \fB%c\fR conversion specification. Applications should be extremely
502 cautious using either of these features when there are multi-byte characters in
503 the character set.
504 .sp
505 .LP
506 The \fB%b\fR conversion specification is not part of the ISO C standard; it has
507 been added here as a portable way to process backslash escapes expanded in
508 string operands as provided by the \fBecho\fR utility. See also the USAGE
509 section of the \fBecho\fR(1) manual page for ways to use \fBprintf\fR as a
510 replacement for all of the traditional versions of the \fBecho\fR utility.
511 .sp
512 .LP
513 If an argument cannot be parsed correctly for the corresponding conversion
514 specification, the \fBprintf\fR utility reports an error. Thus, overflow and
515 extraneous characters at the end of an argument being used for a numeric
516 conversion are to be reported as errors.
517 .sp
518 .LP
519 It is not considered an error if an argument operand is not completely used for
520 a \fBc\fR or \fBs\fR conversion or if a string operand's first or second
521 character is used to get the numeric value of a character.
522 .SH EXAMPLES
523 .SS "/usr/bin/printf"
524 .LP
525 \fBExample 1 \fRPrinting a Series of Prompts
877
878 .sp
879 .LP
880 Whereas for EU usage, format could be the string:
881
882 .sp
883 .in +2
884 .nf
885 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
886 .fi
887 .in -2
888 .sp
889
890 .sp
891 .LP
892 Note that the '$' characters must be properly escaped, such as
893
894 .sp
895 .in +2
896 .nf
897 "%1\e$s, %3\e$d. %2\e$s, %4\e$d:%5\e$.2d\en" in this case
898 .fi
899 .in -2
900 .sp
901
902 .sp
903 .LP
904 producing the message:
905
906 .sp
907 .in +2
908 .nf
909 Sunday, 3. July, 10:02
910 .fi
911 .in -2
912 .sp
913
914 .SH ENVIRONMENT VARIABLES
915 .sp
916 .LP
917 See \fBenviron\fR(5) for descriptions of the following environment variables
|