|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH PRINTF "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
printf
|
|
Packit |
7cfc04 |
\(em write formatted output
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
printf \fIformat\fB [\fIargument\fR...\fB]\fR
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR printf
|
|
Packit |
7cfc04 |
utility shall write formatted operands to the standard output. The
|
|
Packit |
7cfc04 |
.IR argument
|
|
Packit |
7cfc04 |
operands shall be formatted under control of the
|
|
Packit |
7cfc04 |
.IR format
|
|
Packit |
7cfc04 |
operand.
|
|
Packit |
7cfc04 |
.SH OPTIONS
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH OPERANDS
|
|
Packit |
7cfc04 |
The following operands shall be supported:
|
|
Packit |
7cfc04 |
.IP "\fIformat\fR" 10
|
|
Packit |
7cfc04 |
A string describing the format to use to write the remaining operands.
|
|
Packit |
7cfc04 |
See the EXTENDED DESCRIPTION section.
|
|
Packit |
7cfc04 |
.IP "\fIargument\fR" 10
|
|
Packit |
7cfc04 |
The strings to be written to standard output, under the control of
|
|
Packit |
7cfc04 |
.IR format .
|
|
Packit |
7cfc04 |
See the EXTENDED DESCRIPTION section.
|
|
Packit |
7cfc04 |
.SH STDIN
|
|
Packit |
7cfc04 |
Not used.
|
|
Packit |
7cfc04 |
.SH "INPUT FILES"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "ENVIRONMENT VARIABLES"
|
|
Packit |
7cfc04 |
The following environment variables shall affect the execution of
|
|
Packit |
7cfc04 |
.IR printf :
|
|
Packit |
7cfc04 |
.IP "\fILANG\fP" 10
|
|
Packit |
7cfc04 |
Provide a default value for the internationalization variables that are
|
|
Packit |
7cfc04 |
unset or null. (See the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Section 8.2" ", " "Internationalization Variables"
|
|
Packit |
7cfc04 |
the precedence of internationalization variables used to determine the
|
|
Packit |
7cfc04 |
values of locale categories.)
|
|
Packit |
7cfc04 |
.IP "\fILC_ALL\fP" 10
|
|
Packit |
7cfc04 |
If set to a non-empty string value, override the values of all the
|
|
Packit |
7cfc04 |
other internationalization variables.
|
|
Packit |
7cfc04 |
.IP "\fILC_CTYPE\fP" 10
|
|
Packit |
7cfc04 |
Determine the locale for the interpretation of sequences of bytes of
|
|
Packit |
7cfc04 |
text data as characters (for example, single-byte as opposed to
|
|
Packit |
7cfc04 |
multi-byte characters in arguments).
|
|
Packit |
7cfc04 |
.IP "\fILC_MESSAGES\fP" 10
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
Determine the locale that should be used to affect the format and
|
|
Packit |
7cfc04 |
contents of diagnostic messages written to standard error.
|
|
Packit |
7cfc04 |
.IP "\fILC_NUMERIC\fP" 10
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
Determine the locale for numeric formatting. It shall affect the
|
|
Packit |
7cfc04 |
format of numbers written using the
|
|
Packit |
7cfc04 |
.BR e ,
|
|
Packit |
7cfc04 |
.BR E ,
|
|
Packit |
7cfc04 |
.BR f ,
|
|
Packit |
7cfc04 |
.BR g ,
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR G
|
|
Packit |
7cfc04 |
conversion specifier characters (if supported).
|
|
Packit |
7cfc04 |
.IP "\fINLSPATH\fP" 10
|
|
Packit |
7cfc04 |
Determine the location of message catalogs for the processing of
|
|
Packit |
7cfc04 |
.IR LC_MESSAGES .
|
|
Packit |
7cfc04 |
.SH "ASYNCHRONOUS EVENTS"
|
|
Packit |
7cfc04 |
Default.
|
|
Packit |
7cfc04 |
.SH STDOUT
|
|
Packit |
7cfc04 |
See the EXTENDED DESCRIPTION section.
|
|
Packit |
7cfc04 |
.SH STDERR
|
|
Packit |
7cfc04 |
The standard error shall be used only for diagnostic messages.
|
|
Packit |
7cfc04 |
.SH "OUTPUT FILES"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "EXTENDED DESCRIPTION"
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR format
|
|
Packit |
7cfc04 |
operand shall be used as the
|
|
Packit |
7cfc04 |
.IR format
|
|
Packit |
7cfc04 |
string described in the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Chapter 5" ", " "File Format Notation"
|
|
Packit |
7cfc04 |
with the following exceptions:
|
|
Packit |
7cfc04 |
.IP " 1." 4
|
|
Packit |
7cfc04 |
A
|
|
Packit |
7cfc04 |
<space>
|
|
Packit |
7cfc04 |
in the format string, in any context other than a flag of a conversion
|
|
Packit |
7cfc04 |
specification, shall be treated as an ordinary character that is copied
|
|
Packit |
7cfc04 |
to the output.
|
|
Packit |
7cfc04 |
.IP " 2." 4
|
|
Packit |
7cfc04 |
A
|
|
Packit |
7cfc04 |
.BR ' '
|
|
Packit |
7cfc04 |
character in the format string shall be treated as a
|
|
Packit |
7cfc04 |
.BR ' '
|
|
Packit |
7cfc04 |
character, not as a
|
|
Packit |
7cfc04 |
<space>.
|
|
Packit |
7cfc04 |
.IP " 3." 4
|
|
Packit |
7cfc04 |
In addition to the escape sequences shown in the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Chapter 5" ", " "File Format Notation"
|
|
Packit |
7cfc04 |
(\c
|
|
Packit |
7cfc04 |
.BR '\e\e' ,
|
|
Packit |
7cfc04 |
.BR '\ea' ,
|
|
Packit |
7cfc04 |
.BR '\eb' ,
|
|
Packit |
7cfc04 |
.BR '\ef' ,
|
|
Packit |
7cfc04 |
.BR '\en' ,
|
|
Packit |
7cfc04 |
.BR '\er' ,
|
|
Packit |
7cfc04 |
.BR '\et' ,
|
|
Packit |
7cfc04 |
.BR '\ev' ),
|
|
Packit |
7cfc04 |
.BR \(dq\eddd\(dq ,
|
|
Packit |
7cfc04 |
where
|
|
Packit |
7cfc04 |
.IR ddd
|
|
Packit |
7cfc04 |
is a one, two, or three-digit octal number, shall be written as a byte
|
|
Packit |
7cfc04 |
with the numeric value specified by the octal number.
|
|
Packit |
7cfc04 |
.IP " 4." 4
|
|
Packit |
7cfc04 |
The implementation shall not precede or follow output from the
|
|
Packit |
7cfc04 |
.BR d
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR u
|
|
Packit |
7cfc04 |
conversion specifiers with
|
|
Packit |
7cfc04 |
<blank>
|
|
Packit |
7cfc04 |
characters not specified by the
|
|
Packit |
7cfc04 |
.IR format
|
|
Packit |
7cfc04 |
operand.
|
|
Packit |
7cfc04 |
.IP " 5." 4
|
|
Packit |
7cfc04 |
The implementation shall not precede output from the
|
|
Packit |
7cfc04 |
.BR o
|
|
Packit |
7cfc04 |
conversion specifier with zeros not specified by the
|
|
Packit |
7cfc04 |
.IR format
|
|
Packit |
7cfc04 |
operand.
|
|
Packit |
7cfc04 |
.IP " 6." 4
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR a ,
|
|
Packit |
7cfc04 |
.BR A ,
|
|
Packit |
7cfc04 |
.BR e ,
|
|
Packit |
7cfc04 |
.BR E ,
|
|
Packit |
7cfc04 |
.BR f ,
|
|
Packit |
7cfc04 |
.BR F ,
|
|
Packit |
7cfc04 |
.BR g ,
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR G
|
|
Packit |
7cfc04 |
conversion specifiers need not be supported.
|
|
Packit |
7cfc04 |
.IP " 7." 4
|
|
Packit |
7cfc04 |
An additional conversion specifier character,
|
|
Packit |
7cfc04 |
.BR b ,
|
|
Packit |
7cfc04 |
shall be supported as follows. The argument shall be taken to be a
|
|
Packit |
7cfc04 |
string that may contain
|
|
Packit |
7cfc04 |
<backslash>-escape
|
|
Packit |
7cfc04 |
sequences. The following
|
|
Packit |
7cfc04 |
<backslash>-escape
|
|
Packit |
7cfc04 |
sequences shall be supported:
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.IP -- 4
|
|
Packit |
7cfc04 |
The escape sequences listed in the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Chapter 5" ", " "File Format Notation"
|
|
Packit |
7cfc04 |
(\c
|
|
Packit |
7cfc04 |
.BR '\e\e' ,
|
|
Packit |
7cfc04 |
.BR '\ea' ,
|
|
Packit |
7cfc04 |
.BR '\eb' ,
|
|
Packit |
7cfc04 |
.BR '\ef' ,
|
|
Packit |
7cfc04 |
.BR '\en' ,
|
|
Packit |
7cfc04 |
.BR '\er' ,
|
|
Packit |
7cfc04 |
.BR '\et' ,
|
|
Packit |
7cfc04 |
.BR '\ev' ),
|
|
Packit |
7cfc04 |
which shall be converted to the characters they represent
|
|
Packit |
7cfc04 |
.IP -- 4
|
|
Packit |
7cfc04 |
.BR \(dq\e0ddd\(dq ,
|
|
Packit |
7cfc04 |
where
|
|
Packit |
7cfc04 |
.IR ddd
|
|
Packit |
7cfc04 |
is a zero, one, two, or three-digit octal number that shall be
|
|
Packit |
7cfc04 |
converted to a byte with the numeric value specified by the octal
|
|
Packit |
7cfc04 |
number
|
|
Packit |
7cfc04 |
.IP -- 4
|
|
Packit |
7cfc04 |
.BR '\ec' ,
|
|
Packit |
7cfc04 |
which shall not be written and shall cause
|
|
Packit |
7cfc04 |
.IR printf
|
|
Packit |
7cfc04 |
to ignore any remaining characters in the string operand containing it,
|
|
Packit |
7cfc04 |
any remaining string operands, and any additional characters in the
|
|
Packit |
7cfc04 |
.IR format
|
|
Packit |
7cfc04 |
operand
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The interpretation of a
|
|
Packit |
7cfc04 |
<backslash>
|
|
Packit |
7cfc04 |
followed by any other sequence of characters is unspecified.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Bytes from the converted string shall be written until the end of the
|
|
Packit |
7cfc04 |
string or the number of bytes indicated by the precision specification
|
|
Packit |
7cfc04 |
is reached. If the precision is omitted, it shall be taken to be
|
|
Packit |
7cfc04 |
infinite, so all bytes up to the end of the converted string shall be
|
|
Packit |
7cfc04 |
written.
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.IP " 8." 4
|
|
Packit |
7cfc04 |
For each conversion specification that consumes an argument, the next
|
|
Packit |
7cfc04 |
argument operand shall be evaluated and converted to the appropriate
|
|
Packit |
7cfc04 |
type for the conversion as specified below.
|
|
Packit |
7cfc04 |
.IP " 9." 4
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR format
|
|
Packit |
7cfc04 |
operand shall be reused as often as necessary to satisfy the argument
|
|
Packit |
7cfc04 |
operands. Any extra
|
|
Packit |
7cfc04 |
.BR c
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR s
|
|
Packit |
7cfc04 |
conversion specifiers shall be evaluated as if a null string
|
|
Packit |
7cfc04 |
argument were supplied; other extra conversion specifications shall be
|
|
Packit |
7cfc04 |
evaluated as if a zero argument were supplied. If the
|
|
Packit |
7cfc04 |
.IR format
|
|
Packit |
7cfc04 |
operand contains no conversion specifications and
|
|
Packit |
7cfc04 |
.IR argument
|
|
Packit |
7cfc04 |
operands are present, the results are unspecified.
|
|
Packit |
7cfc04 |
.IP 10. 4
|
|
Packit |
7cfc04 |
If a character sequence in the
|
|
Packit |
7cfc04 |
.IR format
|
|
Packit |
7cfc04 |
operand begins with a
|
|
Packit |
7cfc04 |
.BR '%'
|
|
Packit |
7cfc04 |
character, but does not form a valid conversion specification, the
|
|
Packit |
7cfc04 |
behavior is unspecified.
|
|
Packit |
7cfc04 |
.IP 11. 4
|
|
Packit |
7cfc04 |
The argument to the
|
|
Packit |
7cfc04 |
.BR c
|
|
Packit |
7cfc04 |
conversion specifier can be a string containing zero or more bytes. If
|
|
Packit |
7cfc04 |
it contains one or more bytes, the first byte shall be written and any
|
|
Packit |
7cfc04 |
additional bytes shall be ignored. If the argument is an empty string,
|
|
Packit |
7cfc04 |
it is unspecified whether nothing is written or a null byte is written.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR argument
|
|
Packit |
7cfc04 |
operands shall be treated as strings if the corresponding conversion
|
|
Packit |
7cfc04 |
specifier is
|
|
Packit |
7cfc04 |
.BR b ,
|
|
Packit |
7cfc04 |
.BR c ,
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR s ,
|
|
Packit |
7cfc04 |
and shall be evaluated as if by the
|
|
Packit |
7cfc04 |
\fIstrtod\fR()
|
|
Packit |
7cfc04 |
function if the corresponding conversion specifier is
|
|
Packit |
7cfc04 |
.BR a ,
|
|
Packit |
7cfc04 |
.BR A ,
|
|
Packit |
7cfc04 |
.BR e ,
|
|
Packit |
7cfc04 |
.BR E ,
|
|
Packit |
7cfc04 |
.BR f ,
|
|
Packit |
7cfc04 |
.BR F ,
|
|
Packit |
7cfc04 |
.BR g ,
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR G .
|
|
Packit |
7cfc04 |
Otherwise, they shall be evaluated as unsuffixed C integer constants,
|
|
Packit |
7cfc04 |
as described by the ISO\ C standard, with the following extensions:
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
A leading
|
|
Packit |
7cfc04 |
<plus-sign>
|
|
Packit |
7cfc04 |
or minus-sign shall be allowed.
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
If the leading character is a single-quote or double-quote, the value
|
|
Packit |
7cfc04 |
shall be the numeric value in the underlying codeset of the character
|
|
Packit |
7cfc04 |
following the single-quote or double-quote.
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
Suffixed integer constants may be allowed.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If an argument operand cannot be completely converted into an internal
|
|
Packit |
7cfc04 |
value appropriate to the corresponding conversion specification, a
|
|
Packit |
7cfc04 |
diagnostic message shall be written to standard error and the utility
|
|
Packit |
7cfc04 |
shall not exit with a zero exit status, but shall continue processing
|
|
Packit |
7cfc04 |
any remaining operands and shall write the value accumulated at the
|
|
Packit |
7cfc04 |
time the error was detected to standard output.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
It is not considered an error if an argument operand is not completely
|
|
Packit |
7cfc04 |
used for a
|
|
Packit |
7cfc04 |
.BR c
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR s
|
|
Packit |
7cfc04 |
conversion.
|
|
Packit |
7cfc04 |
.SH "EXIT STATUS"
|
|
Packit |
7cfc04 |
The following exit values shall be returned:
|
|
Packit |
7cfc04 |
.IP "\00" 6
|
|
Packit |
7cfc04 |
Successful completion.
|
|
Packit |
7cfc04 |
.IP >0 6
|
|
Packit |
7cfc04 |
An error occurred.
|
|
Packit |
7cfc04 |
.SH "CONSEQUENCES OF ERRORS"
|
|
Packit |
7cfc04 |
Default.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
The floating-point formatting conversion specifications of
|
|
Packit |
7cfc04 |
\fIprintf\fR()
|
|
Packit |
7cfc04 |
are not required because all arithmetic in the shell is integer
|
|
Packit |
7cfc04 |
arithmetic. The
|
|
Packit |
7cfc04 |
.IR awk
|
|
Packit |
7cfc04 |
utility performs floating-point calculations and provides its own
|
|
Packit |
7cfc04 |
.BR printf
|
|
Packit |
7cfc04 |
function. The
|
|
Packit |
7cfc04 |
.IR bc
|
|
Packit |
7cfc04 |
utility can perform arbitrary-precision floating-point arithmetic, but
|
|
Packit |
7cfc04 |
does not provide extensive formatting capabilities. (This
|
|
Packit |
7cfc04 |
.IR printf
|
|
Packit |
7cfc04 |
utility cannot really be used to format
|
|
Packit |
7cfc04 |
.IR bc
|
|
Packit |
7cfc04 |
output; it does not support arbitrary precision.) Implementations are
|
|
Packit |
7cfc04 |
encouraged to support the floating-point conversions as an extension.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Note that this
|
|
Packit |
7cfc04 |
.IR printf
|
|
Packit |
7cfc04 |
utility, like the
|
|
Packit |
7cfc04 |
\fIprintf\fR()
|
|
Packit |
7cfc04 |
function defined in the System Interfaces volume of POSIX.1\(hy2008 on which it is based, makes no special
|
|
Packit |
7cfc04 |
provision for dealing with multi-byte characters when using the
|
|
Packit |
7cfc04 |
.BR %c
|
|
Packit |
7cfc04 |
conversion specification or when a precision is specified in a
|
|
Packit |
7cfc04 |
.BR %b
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR %s
|
|
Packit |
7cfc04 |
conversion specification. Applications should be extremely cautious
|
|
Packit |
7cfc04 |
using either of these features when there are multi-byte characters in
|
|
Packit |
7cfc04 |
the character set.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
No provision is made in this volume of POSIX.1\(hy2008 which allows field widths and precisions
|
|
Packit |
7cfc04 |
to be specified as
|
|
Packit |
7cfc04 |
.BR '*'
|
|
Packit |
7cfc04 |
since the
|
|
Packit |
7cfc04 |
.BR '*'
|
|
Packit |
7cfc04 |
can be replaced directly in the
|
|
Packit |
7cfc04 |
.IR format
|
|
Packit |
7cfc04 |
operand using shell variable substitution. Implementations can also
|
|
Packit |
7cfc04 |
provide this feature as an extension if they so choose.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Hexadecimal character constants as defined in the ISO\ C standard are not
|
|
Packit |
7cfc04 |
recognized in the
|
|
Packit |
7cfc04 |
.IR format
|
|
Packit |
7cfc04 |
operand because there is no consistent way to detect the end of the
|
|
Packit |
7cfc04 |
constant. Octal character constants are limited to, at most, three
|
|
Packit |
7cfc04 |
octal digits, but hexadecimal character constants are only terminated
|
|
Packit |
7cfc04 |
by a non-hex-digit character. In the ISO\ C standard, the
|
|
Packit |
7cfc04 |
.BR \(dq##\(dq
|
|
Packit |
7cfc04 |
concatenation operator can be used to terminate a constant and follow
|
|
Packit |
7cfc04 |
it with a hexadecimal character to be written. In the shell,
|
|
Packit |
7cfc04 |
concatenation occurs before the
|
|
Packit |
7cfc04 |
.IR printf
|
|
Packit |
7cfc04 |
utility has a chance to parse the end of the hexadecimal constant.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR %b
|
|
Packit |
7cfc04 |
conversion specification is not part of the ISO\ C standard; it has been added
|
|
Packit |
7cfc04 |
here as a portable way to process
|
|
Packit |
7cfc04 |
<backslash>-escapes
|
|
Packit |
7cfc04 |
expanded in string operands as provided by the
|
|
Packit |
7cfc04 |
.IR echo
|
|
Packit |
7cfc04 |
utility. See also the APPLICATION USAGE section of
|
|
Packit |
7cfc04 |
.IR "\fIecho\fR\^"
|
|
Packit |
7cfc04 |
for ways to use
|
|
Packit |
7cfc04 |
.IR printf
|
|
Packit |
7cfc04 |
as a replacement for all of the traditional versions of the
|
|
Packit |
7cfc04 |
.IR echo
|
|
Packit |
7cfc04 |
utility.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If an argument cannot be parsed correctly for the corresponding
|
|
Packit |
7cfc04 |
conversion specification, the
|
|
Packit |
7cfc04 |
.IR printf
|
|
Packit |
7cfc04 |
utility is required to report an error. Thus, overflow and extraneous
|
|
Packit |
7cfc04 |
characters at the end of an argument being used for a numeric
|
|
Packit |
7cfc04 |
conversion shall be reported as errors.
|
|
Packit |
7cfc04 |
.SH EXAMPLES
|
|
Packit |
7cfc04 |
To alert the user and then print and read a series of prompts:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
printf "\eaPlease fill in the following: \enName: "
|
|
Packit |
7cfc04 |
read name
|
|
Packit |
7cfc04 |
printf "Phone number: "
|
|
Packit |
7cfc04 |
read phone
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
To read out a list of right and wrong answers from a file, calculate
|
|
Packit |
7cfc04 |
the percentage correctly, and print them out. The numbers are
|
|
Packit |
7cfc04 |
right-justified and separated by a single
|
|
Packit |
7cfc04 |
<tab>.
|
|
Packit |
7cfc04 |
The percentage is written to one decimal place of accuracy:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
while read right wrong ; do
|
|
Packit |
7cfc04 |
percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc)
|
|
Packit |
7cfc04 |
printf "%2d right\et%2d wrong\et(%s%%)\en" \e
|
|
Packit |
7cfc04 |
$right $wrong $percent
|
|
Packit |
7cfc04 |
done < database_file
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
The command:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
printf "%5d%4d\en" 1 21 321 4321 54321
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
produces:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
1 21
|
|
Packit |
7cfc04 |
3214321
|
|
Packit |
7cfc04 |
54321 0
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Note that the
|
|
Packit |
7cfc04 |
.IR format
|
|
Packit |
7cfc04 |
operand is used three times to print all of the given strings and that
|
|
Packit |
7cfc04 |
a
|
|
Packit |
7cfc04 |
.BR '0'
|
|
Packit |
7cfc04 |
was supplied by
|
|
Packit |
7cfc04 |
.IR printf
|
|
Packit |
7cfc04 |
to satisfy the last
|
|
Packit |
7cfc04 |
.BR %4d
|
|
Packit |
7cfc04 |
conversion specification.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR printf
|
|
Packit |
7cfc04 |
utility is required to notify the user when conversion errors are
|
|
Packit |
7cfc04 |
detected while producing numeric output; thus, the following results
|
|
Packit |
7cfc04 |
would be expected on an implementation with 32-bit twos-complement
|
|
Packit |
7cfc04 |
integers when
|
|
Packit |
7cfc04 |
.BR %d
|
|
Packit |
7cfc04 |
is specified as the
|
|
Packit |
7cfc04 |
.IR format
|
|
Packit |
7cfc04 |
operand:
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
.TS
|
|
Packit |
7cfc04 |
center tab(@) box;
|
|
Packit |
7cfc04 |
cB | cB | cB
|
|
Packit |
7cfc04 |
cB | cB | cB
|
|
Packit |
7cfc04 |
lf5 | lf5 | lf7.
|
|
Packit |
7cfc04 |
@Standard
|
|
Packit |
7cfc04 |
Argument@Output@Diagnostic Output
|
|
Packit |
7cfc04 |
_
|
|
Packit |
7cfc04 |
5a@5@printf: "5a" not completely converted
|
|
Packit |
7cfc04 |
9999999999@2147483647@printf: "9999999999" arithmetic overflow
|
|
Packit |
7cfc04 |
\(mi9999999999@\(mi2147483648@printf: "\(mi9999999999" arithmetic overflow
|
|
Packit |
7cfc04 |
ABC@0@printf: "ABC" expected numeric value
|
|
Packit |
7cfc04 |
.TE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The diagnostic message format is not specified, but these examples
|
|
Packit |
7cfc04 |
convey the type of information that should be reported. Note that the
|
|
Packit |
7cfc04 |
value shown on standard output is what would be expected as the return
|
|
Packit |
7cfc04 |
value from the
|
|
Packit |
7cfc04 |
\fIstrtol\fR()
|
|
Packit |
7cfc04 |
function as defined in the System Interfaces volume of POSIX.1\(hy2008. A similar correspondence exists
|
|
Packit |
7cfc04 |
between
|
|
Packit |
7cfc04 |
.BR %u
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
\fIstrtoul\fR()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR %e ,
|
|
Packit |
7cfc04 |
.BR %f ,
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR %g
|
|
Packit |
7cfc04 |
(if the implementation supports floating-point conversions) and
|
|
Packit |
7cfc04 |
\fIstrtod\fR().
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
In a locale using the ISO/IEC\ 646:\|1991 standard as the underlying codeset, the command:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
printf "%d\en" 3 +3 \(mi3 \e'3 \e"+3 "'\(mi3"
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
produces:
|
|
Packit |
7cfc04 |
.IP 3 6
|
|
Packit |
7cfc04 |
Numeric value of constant 3
|
|
Packit |
7cfc04 |
.IP 3 6
|
|
Packit |
7cfc04 |
Numeric value of constant 3
|
|
Packit |
7cfc04 |
.IP "\(mi3" 6
|
|
Packit |
7cfc04 |
Numeric value of constant \(mi3
|
|
Packit |
7cfc04 |
.IP 51 6
|
|
Packit |
7cfc04 |
Numeric value of the character
|
|
Packit |
7cfc04 |
.BR '3'
|
|
Packit |
7cfc04 |
in the ISO/IEC\ 646:\|1991 standard codeset
|
|
Packit |
7cfc04 |
.IP 43 6
|
|
Packit |
7cfc04 |
Numeric value of the character
|
|
Packit |
7cfc04 |
.BR '\(pl'
|
|
Packit |
7cfc04 |
in the ISO/IEC\ 646:\|1991 standard codeset
|
|
Packit |
7cfc04 |
.IP 45 6
|
|
Packit |
7cfc04 |
Numeric value of the character
|
|
Packit |
7cfc04 |
.BR '\(mi'
|
|
Packit |
7cfc04 |
in the ISO/IEC\ 646:\|1991 standard codeset
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Note that in a locale with multi-byte characters, the value of a
|
|
Packit |
7cfc04 |
character is intended to be the value of the equivalent of the
|
|
Packit |
7cfc04 |
.BR wchar_t
|
|
Packit |
7cfc04 |
representation of the character as described in the System Interfaces volume of POSIX.1\(hy2008.
|
|
Packit |
7cfc04 |
.SH RATIONALE
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR printf
|
|
Packit |
7cfc04 |
utility was added to provide functionality that has historically been
|
|
Packit |
7cfc04 |
provided by
|
|
Packit |
7cfc04 |
.IR echo .
|
|
Packit |
7cfc04 |
However, due to irreconcilable differences in the various versions of
|
|
Packit |
7cfc04 |
.IR echo
|
|
Packit |
7cfc04 |
extant, the version has few special features, leaving those to this new
|
|
Packit |
7cfc04 |
.IR printf
|
|
Packit |
7cfc04 |
utility, which is based on one in the Ninth Edition system.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The EXTENDED DESCRIPTION section almost exactly matches the
|
|
Packit |
7cfc04 |
\fIprintf\fR()
|
|
Packit |
7cfc04 |
function in the ISO\ C standard, although it is described in terms of the file
|
|
Packit |
7cfc04 |
format notation in the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Chapter 5" ", " "File Format Notation".
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Earlier versions of this standard specified that arguments for all
|
|
Packit |
7cfc04 |
conversions other than
|
|
Packit |
7cfc04 |
.BR b ,
|
|
Packit |
7cfc04 |
.BR c ,
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR s
|
|
Packit |
7cfc04 |
were evaluated in the same way (as C constants, but with stated
|
|
Packit |
7cfc04 |
exceptions). For implementations supporting the floating-point conversions
|
|
Packit |
7cfc04 |
it was not clear whether integer conversions need only accept integer
|
|
Packit |
7cfc04 |
constants and floating-point conversions need only accept floating-point
|
|
Packit |
7cfc04 |
constants, or whether both types of conversions should accept both
|
|
Packit |
7cfc04 |
types of constants. Also by not distinguishing between them, the
|
|
Packit |
7cfc04 |
requirement relating to a leading single-quote or double-quote applied
|
|
Packit |
7cfc04 |
to floating-point conversions even though this provided no useful
|
|
Packit |
7cfc04 |
functionality to applications that was not already available through
|
|
Packit |
7cfc04 |
the integer conversions. The current standard clarifies the situation
|
|
Packit |
7cfc04 |
by specifying that the arguments for floating-point conversions are
|
|
Packit |
7cfc04 |
evaluated as if by
|
|
Packit |
7cfc04 |
\fIstrtod\fR(),
|
|
Packit |
7cfc04 |
and the arguments for integer conversions are evaluated as C integer
|
|
Packit |
7cfc04 |
constants, with the special treatment of leading single-quote and
|
|
Packit |
7cfc04 |
double-quote applying only to integer conversions.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "\fIawk\fR\^",
|
|
Packit |
7cfc04 |
.IR "\fIbc\fR\^",
|
|
Packit |
7cfc04 |
.IR "\fIecho\fR\^"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Chapter 5" ", " "File Format Notation",
|
|
Packit |
7cfc04 |
.IR "Chapter 8" ", " "Environment Variables"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The System Interfaces volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "\fIfprintf\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIstrtod\fR\^(\|)"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|