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