diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/printf.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/printf.1p | 587 |
1 files changed, 587 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/printf.1p b/man-pages-posix-2017/man1p/printf.1p new file mode 100644 index 0000000..410aaae --- /dev/null +++ b/man-pages-posix-2017/man1p/printf.1p @@ -0,0 +1,587 @@ +'\" 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 . |