2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "PRINTF" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" printf
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH PROLOG
|
|
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
|
|
The Linux implementation of this interface may differ (consult
|
|
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
|
|
or the interface may not be implemented on Linux.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
printf \- write formatted output
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fBprintf\fP \fIformat\fP\fB[\fP\fIargument\fP\fB...\fP\fB]\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fIprintf\fP utility shall write formatted operands to the standard
|
|
|
|
output. The \fIargument\fP operands shall be formatted
|
|
|
|
under control of the \fIformat\fP operand.
|
|
|
|
.SH OPTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH OPERANDS
|
|
|
|
.LP
|
|
|
|
The following operands shall be supported:
|
|
|
|
.TP 7
|
|
|
|
\fIformat\fP
|
|
|
|
A string describing the format to use to write the remaining operands.
|
|
|
|
See the EXTENDED DESCRIPTION section.
|
|
|
|
.TP 7
|
|
|
|
\fIargument\fP
|
|
|
|
The strings to be written to standard output, under the control of
|
|
|
|
\fIformat\fP. See the EXTENDED DESCRIPTION section.
|
|
|
|
.sp
|
|
|
|
.SH STDIN
|
|
|
|
.LP
|
|
|
|
Not used.
|
|
|
|
.SH INPUT FILES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH ENVIRONMENT VARIABLES
|
|
|
|
.LP
|
|
|
|
The following environment variables shall affect the execution of
|
|
|
|
\fIprintf\fP:
|
|
|
|
.TP 7
|
|
|
|
\fILANG\fP
|
|
|
|
Provide a default value for the internationalization variables that
|
|
|
|
are unset or null. (See the Base Definitions volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
|
|
|
for
|
|
|
|
the precedence of internationalization variables used to determine
|
|
|
|
the values of locale categories.)
|
|
|
|
.TP 7
|
|
|
|
\fILC_ALL\fP
|
|
|
|
If set to a non-empty string value, override the values of all the
|
|
|
|
other internationalization variables.
|
|
|
|
.TP 7
|
|
|
|
\fILC_CTYPE\fP
|
|
|
|
Determine the locale for the interpretation of sequences of bytes
|
|
|
|
of text data as characters (for example, single-byte as
|
|
|
|
opposed to multi-byte characters in arguments).
|
|
|
|
.TP 7
|
|
|
|
\fILC_MESSAGES\fP
|
|
|
|
Determine the locale that should be used to affect the format and
|
|
|
|
contents of diagnostic messages written to standard
|
|
|
|
error.
|
|
|
|
.TP 7
|
|
|
|
\fILC_NUMERIC\fP
|
|
|
|
.sp
|
|
|
|
Determine the locale for numeric formatting. It shall affect the format
|
2007-09-20 06:36:16 +00:00
|
|
|
of numbers written using the \fBe\fP, \fBE\fP,
|
|
|
|
\fBf\fP, \fBg\fP, and \fBG\fP conversion specifier characters (if
|
2004-11-03 13:51:07 +00:00
|
|
|
supported).
|
|
|
|
.TP 7
|
|
|
|
\fINLSPATH\fP
|
|
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
|
|
\&.\fP
|
|
|
|
.sp
|
|
|
|
.SH ASYNCHRONOUS EVENTS
|
|
|
|
.LP
|
|
|
|
Default.
|
|
|
|
.SH STDOUT
|
|
|
|
.LP
|
|
|
|
See the EXTENDED DESCRIPTION section.
|
|
|
|
.SH STDERR
|
|
|
|
.LP
|
|
|
|
The standard error shall be used only for diagnostic messages.
|
|
|
|
.SH OUTPUT FILES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH EXTENDED DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fIformat\fP operand shall be used as the \fIformat\fP string
|
|
|
|
described in the Base Definitions volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001, Chapter 5, File Format Notation with the following
|
|
|
|
exceptions:
|
|
|
|
.IP " 1." 4
|
|
|
|
A <space> in the format string, in any context other than a flag of
|
|
|
|
a conversion specification, shall be treated as an
|
|
|
|
ordinary character that is copied to the output.
|
|
|
|
.LP
|
|
|
|
.IP " 2." 4
|
|
|
|
A \fB' '\fP character in the format string shall be treated as a \fB' '\fP
|
|
|
|
character, not as a <space>.
|
|
|
|
.LP
|
|
|
|
.IP " 3." 4
|
|
|
|
In addition to the escape sequences shown in the Base Definitions
|
|
|
|
volume of IEEE\ Std\ 1003.1-2001, Chapter 5, File Format Notation
|
2007-09-20 06:36:16 +00:00
|
|
|
( \fB'\\\\'\fP, \fB'\\a'\fP, \fB'\\b'\fP, \fB'\\f'\fP,
|
2007-09-20 17:56:19 +00:00
|
|
|
\fB'\\n'\fP, \fB'\\r'\fP, \fB'\\t'\fP, \fB'\\v'\fP ), \fB"\\ddd"\fP,
|
|
|
|
where \fIddd\fP is a one, two, or three-digit
|
2004-11-03 13:51:07 +00:00
|
|
|
octal number, shall be written as a byte with the numeric value specified
|
|
|
|
by the octal number.
|
|
|
|
.LP
|
|
|
|
.IP " 4." 4
|
|
|
|
The implementation shall not precede or follow output from the \fBd\fP
|
|
|
|
or \fBu\fP conversion specifiers with
|
|
|
|
<blank>s not specified by the \fIformat\fP operand.
|
|
|
|
.LP
|
|
|
|
.IP " 5." 4
|
|
|
|
The implementation shall not precede output from the \fBo\fP conversion
|
|
|
|
specifier with zeros not specified by the
|
|
|
|
\fIformat\fP operand.
|
|
|
|
.LP
|
|
|
|
.IP " 6." 4
|
2007-09-20 06:36:16 +00:00
|
|
|
The \fBe\fP, \fBE\fP, \fBf\fP, \fBg\fP, and \fBG\fP conversion
|
2004-11-03 13:51:07 +00:00
|
|
|
specifiers need not be supported.
|
|
|
|
.LP
|
|
|
|
.IP " 7." 4
|
2007-09-20 06:36:16 +00:00
|
|
|
An additional conversion specifier character, \fBb\fP, shall be supported
|
2004-11-03 13:51:07 +00:00
|
|
|
as follows. The argument shall be taken to be a
|
|
|
|
string that may contain backslash-escape sequences. The following
|
|
|
|
backslash-escape sequences shall be supported:
|
|
|
|
.RS
|
|
|
|
.IP " *" 3
|
|
|
|
The escape sequences listed in the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
2007-09-20 17:56:19 +00:00
|
|
|
Chapter 5, File Format Notation ( \fB'\\\\'\fP, \fB'\\a'\fP, \fB'\\b'\fP,
|
|
|
|
\fB'\\f'\fP,
|
2007-09-20 06:36:16 +00:00
|
|
|
\fB'\\n'\fP, \fB'\\r'\fP, \fB'\\t'\fP, \fB'\\v'\fP ), which shall
|
2004-11-03 13:51:07 +00:00
|
|
|
be converted to the characters they represent
|
|
|
|
.LP
|
|
|
|
.IP " *" 3
|
2007-09-20 06:36:16 +00:00
|
|
|
\fB"\\0ddd"\fP, where \fIddd\fP is a zero, one, two, or three-digit
|
2004-11-03 13:51:07 +00:00
|
|
|
octal number that shall be converted to a byte with the
|
|
|
|
numeric value specified by the octal number
|
|
|
|
.LP
|
|
|
|
.IP " *" 3
|
2007-09-20 06:36:16 +00:00
|
|
|
\fB'\\c'\fP, which shall not be written and shall cause \fIprintf\fP
|
2004-11-03 13:51:07 +00:00
|
|
|
to ignore any remaining characters in the string
|
|
|
|
operand containing it, any remaining string operands, and any additional
|
|
|
|
characters in the \fIformat\fP operand
|
|
|
|
.LP
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
The interpretation of a backslash followed by any other sequence of
|
|
|
|
characters is unspecified.
|
|
|
|
.LP
|
|
|
|
Bytes from the converted string shall be written until the end of
|
|
|
|
the string or the number of bytes indicated by the precision
|
|
|
|
specification is reached. If the precision is omitted, it shall be
|
|
|
|
taken to be infinite, so all bytes up to the end of the
|
|
|
|
converted string shall be written.
|
|
|
|
.LP
|
|
|
|
.IP " 8." 4
|
|
|
|
For each conversion specification that consumes an argument, the next
|
|
|
|
argument operand shall be evaluated and converted to the
|
|
|
|
appropriate type for the conversion as specified below.
|
|
|
|
.LP
|
|
|
|
.IP " 9." 4
|
|
|
|
The \fIformat\fP operand shall be reused as often as necessary to
|
|
|
|
satisfy the argument operands. Any extra \fBc\fP or
|
|
|
|
\fBs\fP conversion specifiers shall be evaluated as if a null string
|
|
|
|
argument were supplied; other extra conversion
|
|
|
|
specifications shall be evaluated as if a zero argument were supplied.
|
|
|
|
If the \fIformat\fP operand contains no conversion
|
|
|
|
specifications and \fIargument\fP operands are present, the results
|
|
|
|
are unspecified.
|
|
|
|
.LP
|
|
|
|
.IP "10." 4
|
|
|
|
If a character sequence in the \fIformat\fP operand begins with a
|
|
|
|
\fB'%'\fP character, but does not form a valid conversion
|
|
|
|
specification, the behavior is unspecified.
|
|
|
|
.LP
|
|
|
|
.LP
|
|
|
|
The \fIargument\fP operands shall be treated as strings if the corresponding
|
2007-09-20 06:36:16 +00:00
|
|
|
conversion specifier is \fBb\fP, \fBc\fP,
|
2004-11-03 13:51:07 +00:00
|
|
|
or \fBs\fP ; otherwise, it shall be evaluated as a C constant, as
|
|
|
|
described by the ISO\ C standard, with the following
|
|
|
|
extensions:
|
|
|
|
.IP " *" 3
|
|
|
|
A leading plus or minus sign shall be allowed.
|
|
|
|
.LP
|
|
|
|
.IP " *" 3
|
|
|
|
If the leading character is a single-quote or double-quote, the value
|
|
|
|
shall be the numeric value in the underlying codeset of
|
|
|
|
the character following the single-quote or double-quote.
|
|
|
|
.LP
|
|
|
|
.LP
|
|
|
|
If an argument operand cannot be completely converted into an internal
|
|
|
|
value appropriate to the corresponding conversion
|
|
|
|
specification, a diagnostic message shall be written to standard error
|
|
|
|
and the utility shall not exit with a zero exit status, but
|
|
|
|
shall continue processing any remaining operands and shall write the
|
|
|
|
value accumulated at the time the error was detected to
|
|
|
|
standard output.
|
|
|
|
.LP
|
|
|
|
It is not considered an error if an argument operand is not completely
|
|
|
|
used for a \fBc\fP or \fBs\fP conversion or if a
|
|
|
|
string operand's first or second character is used to get the numeric
|
|
|
|
value of a character.
|
|
|
|
.SH EXIT STATUS
|
|
|
|
.LP
|
|
|
|
The following exit values shall be returned:
|
|
|
|
.TP 7
|
|
|
|
\ 0
|
|
|
|
Successful completion.
|
|
|
|
.TP 7
|
|
|
|
>0
|
|
|
|
An error occurred.
|
|
|
|
.sp
|
|
|
|
.SH CONSEQUENCES OF ERRORS
|
|
|
|
.LP
|
|
|
|
Default.
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
The floating-point formatting conversion specifications of \fIprintf\fP()
|
|
|
|
are not
|
|
|
|
required because all arithmetic in the shell is integer arithmetic.
|
|
|
|
The \fIawk\fP utility
|
|
|
|
performs floating-point calculations and provides its own \fBprintf\fP
|
|
|
|
function. The \fIbc\fP
|
|
|
|
utility can perform arbitrary-precision floating-point arithmetic,
|
|
|
|
but does not provide extensive formatting capabilities. (This
|
|
|
|
\fIprintf\fP utility cannot really be used to format \fIbc\fP output;
|
|
|
|
it does not support
|
|
|
|
arbitrary precision.) Implementations are encouraged to support the
|
|
|
|
floating-point conversions as an extension.
|
|
|
|
.LP
|
|
|
|
Note that this \fIprintf\fP utility, like the \fIprintf\fP() function
|
|
|
|
defined in the
|
|
|
|
System Interfaces volume of IEEE\ Std\ 1003.1-2001 on which it is
|
|
|
|
based, makes no special provision for dealing with
|
|
|
|
multi-byte characters when using the \fB%c\fP conversion specification
|
|
|
|
or when a precision is specified in a \fB%b\fP or
|
|
|
|
\fB%s\fP conversion specification. Applications should be extremely
|
|
|
|
cautious using either of these features when there are
|
|
|
|
multi-byte characters in the character set.
|
|
|
|
.LP
|
|
|
|
No provision is made in this volume of IEEE\ Std\ 1003.1-2001 which
|
|
|
|
allows field widths and precisions to be specified
|
|
|
|
as \fB'*'\fP since the \fB'*'\fP can be replaced directly in the \fIformat\fP
|
|
|
|
operand using shell variable substitution.
|
|
|
|
Implementations can also provide this feature as an extension if they
|
|
|
|
so choose.
|
|
|
|
.LP
|
|
|
|
Hexadecimal character constants as defined in the ISO\ C standard
|
|
|
|
are not recognized in the \fIformat\fP operand because
|
|
|
|
there is no consistent way to detect the end of the constant. Octal
|
|
|
|
character constants are limited to, at most, three octal
|
|
|
|
digits, but hexadecimal character constants are only terminated by
|
|
|
|
a non-hex-digit character. In the ISO\ C standard, the
|
|
|
|
\fB"##"\fP concatenation operator can be used to terminate a constant
|
|
|
|
and follow it with a hexadecimal character to be written.
|
|
|
|
In the shell, concatenation occurs before the \fIprintf\fP utility
|
|
|
|
has a chance to parse the end of the hexadecimal constant.
|
|
|
|
.LP
|
|
|
|
The \fB%b\fP conversion specification is not part of the ISO\ C standard;
|
|
|
|
it has been added here as a portable way to
|
|
|
|
process backslash escapes expanded in string operands as provided
|
|
|
|
by the \fIecho\fP utility.
|
|
|
|
See also the APPLICATION USAGE section of \fIecho\fP for ways to use
|
|
|
|
\fIprintf\fP as a replacement for
|
|
|
|
all of the traditional versions of the \fIecho\fP utility.
|
|
|
|
.LP
|
|
|
|
If an argument cannot be parsed correctly for the corresponding conversion
|
|
|
|
specification, the \fIprintf\fP utility is required
|
|
|
|
to report an error. Thus, overflow and extraneous characters at the
|
|
|
|
end of an argument being used for a numeric conversion shall be
|
|
|
|
reported as errors.
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
To alert the user and then print and read a series of prompts:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBprintf "\\aPlease fill in the following: \\nName: "
|
|
|
|
read name
|
|
|
|
printf "Phone number: "
|
|
|
|
read phone
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
To read out a list of right and wrong answers from a file, calculate
|
|
|
|
the percentage correctly, and print them out. The numbers
|
|
|
|
are right-justified and separated by a single <tab>. The percentage
|
|
|
|
is written to one decimal place of accuracy:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBwhile read right wrong ; do
|
|
|
|
percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc)
|
|
|
|
printf "%2d right\\t%2d wrong\\t(%s%%)\\n" \\
|
|
|
|
$right $wrong $percent
|
|
|
|
done < database_file
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
The command:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBprintf "%5d%4d\\n" 1 21 321 4321 54321
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
produces:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB 1 21
|
|
|
|
3214321
|
|
|
|
54321 0
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
Note that the \fIformat\fP operand is used three times to print all
|
|
|
|
of the given strings and that a \fB'0'\fP was supplied
|
|
|
|
by \fIprintf\fP to satisfy the last \fB%4d\fP conversion specification.
|
|
|
|
.LP
|
|
|
|
The \fIprintf\fP utility is required to notify the user when conversion
|
|
|
|
errors are detected while producing numeric output;
|
|
|
|
thus, the following results would be expected on an implementation
|
|
|
|
with 32-bit twos-complement integers when \fB%d\fP is
|
|
|
|
specified as the \fIformat\fP operand:
|
|
|
|
.TS C
|
|
|
|
center; l1 l1 l.
|
|
|
|
\fB\ \fP \fBStandard\fP \fB\ \fP
|
|
|
|
\fBArgument\fP \fBOutput\fP \fBDiagnostic Output\fP
|
|
|
|
5a 5 printf: "5a" not completely converted
|
|
|
|
9999999999 2147483647 printf: "9999999999" arithmetic overflow
|
|
|
|
-9999999999 -2147483648 printf: "-9999999999" arithmetic overflow
|
|
|
|
ABC 0 printf: "ABC" expected numeric value
|
|
|
|
.TE
|
|
|
|
.LP
|
|
|
|
The diagnostic message format is not specified, but these examples
|
|
|
|
convey the type of information that should be reported. Note
|
|
|
|
that the value shown on standard output is what would be expected
|
|
|
|
as the return value from the \fIstrtol\fP() function as defined in
|
|
|
|
the System Interfaces volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001. A similar correspondence exists between \fB%u\fP
|
2007-09-20 06:36:16 +00:00
|
|
|
and \fIstrtoul\fP() and \fB%e\fP, \fB%f\fP, and \fB%g\fP (if the
|
2004-11-03 13:51:07 +00:00
|
|
|
implementation supports
|
|
|
|
floating-point conversions) and \fIstrtod\fP().
|
|
|
|
.LP
|
|
|
|
In a locale using the ISO/IEC\ 646:1991 standard as the underlying
|
|
|
|
codeset, the command:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBprintf "%d\\n" 3 +3 -3 \\'3 \\"+3 "'-3"
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
produces:
|
|
|
|
.TP 7
|
|
|
|
3
|
|
|
|
Numeric value of constant 3
|
|
|
|
.TP 7
|
|
|
|
3
|
|
|
|
Numeric value of constant 3
|
|
|
|
.TP 7
|
|
|
|
-3
|
|
|
|
Numeric value of constant -3
|
|
|
|
.TP 7
|
|
|
|
51
|
|
|
|
Numeric value of the character \fB'3'\fP in the ISO/IEC\ 646:1991
|
|
|
|
standard codeset
|
|
|
|
.TP 7
|
|
|
|
43
|
|
|
|
Numeric value of the character \fB'+'\fP in the ISO/IEC\ 646:1991
|
|
|
|
standard codeset
|
|
|
|
.TP 7
|
|
|
|
45
|
|
|
|
Numeric value of the character \fB'-'\fP in the ISO/IEC\ 646:1991
|
|
|
|
standard codeset
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
Note that in a locale with multi-byte characters, the value of a character
|
|
|
|
is intended to be the value of the equivalent of the
|
|
|
|
\fBwchar_t\fP representation of the character as described in the
|
|
|
|
System Interfaces volume of IEEE\ Std\ 1003.1-2001.
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
The \fIprintf\fP utility was added to provide functionality that has
|
|
|
|
historically been provided by \fIecho\fP. However, due to irreconcilable
|
|
|
|
differences in the various versions of \fIecho\fP extant, the version
|
|
|
|
has few special features, leaving those to this new \fIprintf\fP
|
|
|
|
utility, which is based on one in the Ninth Edition system.
|
|
|
|
.LP
|
|
|
|
The EXTENDED DESCRIPTION section almost exactly matches the \fIprintf\fP()
|
|
|
|
function in
|
|
|
|
the ISO\ C standard, although it is described in terms of the file
|
|
|
|
format notation in the Base Definitions volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001, Chapter 5, File Format Notation.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
2007-09-20 06:36:16 +00:00
|
|
|
\fIawk\fP, \fIbc\fP, \fIecho\fP, the System
|
2004-11-03 13:51:07 +00:00
|
|
|
Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIprintf\fP()
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
|
|
event of any discrepancy between this version 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 .
|