diff options
Diffstat (limited to 'man1p/printf.1p')
| -rw-r--r-- | man1p/printf.1p | 426 |
1 files changed, 426 insertions, 0 deletions
diff --git a/man1p/printf.1p b/man1p/printf.1p new file mode 100644 index 000000000..6be3a2459 --- /dev/null +++ b/man1p/printf.1p @@ -0,0 +1,426 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PRINTF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" printf +.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 +of numbers written using the \fBe\fP , \fBE\fP , +\fBf\fP , \fBg\fP , and \fBG\fP conversion specifier characters (if +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 +( \fB'\\\\'\fP , \fB'\\a'\fP , \fB'\\b'\fP , \fB'\\f'\fP , +\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 +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 +The \fBe\fP , \fBE\fP , \fBf\fP , \fBg\fP , and \fBG\fP conversion +specifiers need not be supported. +.LP +.IP " 7." 4 +An additional conversion specifier character, \fBb\fP , shall be supported +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, +Chapter 5, File Format Notation ( \fB'\\\\'\fP , \fB'\\a'\fP , \fB'\\b'\fP +, \fB'\\f'\fP , +\fB'\\n'\fP , \fB'\\r'\fP , \fB'\\t'\fP , \fB'\\v'\fP ), which shall +be converted to the characters they represent +.LP +.IP " *" 3 +\fB"\\0ddd"\fP , where \fIddd\fP 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 +.LP +.IP " *" 3 +\fB'\\c'\fP , which shall not be written and shall cause \fIprintf\fP +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 +conversion specifier is \fBb\fP , \fBc\fP , +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 +and \fIstrtoul\fP() and \fB%e\fP , \fB%f\fP , and \fB%g\fP (if the +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 +\fIawk\fP , \fIbc\fP , \fIecho\fP , the System +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 . |