diff options
Diffstat (limited to 'coreutils-5.3.0-bin/man/cat1p/printf.1p.txt')
| -rw-r--r-- | coreutils-5.3.0-bin/man/cat1p/printf.1p.txt | 401 |
1 files changed, 401 insertions, 0 deletions
diff --git a/coreutils-5.3.0-bin/man/cat1p/printf.1p.txt b/coreutils-5.3.0-bin/man/cat1p/printf.1p.txt new file mode 100644 index 0000000..b68a7cd --- /dev/null +++ b/coreutils-5.3.0-bin/man/cat1p/printf.1p.txt @@ -0,0 +1,401 @@ +printf(P) printf(P) + + + + + +NAME + printf - write formatted output + +SYNOPSIS + printf format[argument...] + +DESCRIPTION + The printf utility shall write formatted operands to the + standard output. The argument operands shall be format- + ted under control of the format operand. + +OPTIONS + None. + +OPERANDS + The following operands shall be supported: + + format A string describing the format to use to write + the remaining operands. See the EXTENDED + DESCRIPTION section. + + argument + The strings to be written to standard output, + under the control of format. See the EXTENDED + DESCRIPTION section. + + +STDIN + Not used. + +INPUT FILES + None. + +ENVIRONMENT VARIABLES + The following environment variables shall affect the + execution of printf: + + LANG Provide a default value for the internationaliza- + tion 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 cate- + gories.) + + LC_ALL If set to a non-empty string value, override the + values of all the other internationalization + variables. + + LC_CTYPE + 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). + + LC_MESSAGES + Determine the locale that should be used to + affect the format and contents of diagnostic mes- + sages written to standard error. + + LC_NUMERIC + + Determine the locale for numeric formatting. It + shall affect the format of numbers written using + the e , E , f , g , and G conversion specifier + characters (if supported). + + NLSPATH + Determine the location of message catalogs for + the processing of LC_MESSAGES . + + +ASYNCHRONOUS EVENTS + Default. + +STDOUT + See the EXTENDED DESCRIPTION section. + +STDERR + The standard error shall be used only for diagnostic + messages. + +OUTPUT FILES + None. + +EXTENDED DESCRIPTION + The format operand shall be used as the format string + described in the Base Definitions volume of + IEEE Std 1003.1-2001, Chapter 5, File Format Notation + with the following exceptions: + + 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. + + A '' character in the format string shall be treated as + a '' character, not as a <space>. + + In addition to the escape sequences shown in the Base + Definitions volume of IEEE Std 1003.1-2001, Chapter 5, + File Format Notation ( '\\' , '\a' , '\b' , '\f' , '\n' + , '\r' , '\t' , '\v' ), "\ddd" , where ddd is a one, + two, or three-digit octal number, shall be written as a + byte with the numeric value specified by the octal num- + ber. + + The implementation shall not precede or follow output + from the d or u conversion specifiers with <blank>s not + specified by the format operand. + + The implementation shall not precede output from the o + conversion specifier with zeros not specified by the + format operand. + + The e , E , f , g , and G conversion specifiers need not + be supported. + + An additional conversion specifier character, b , 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 sup- + ported: + + The escape sequences listed in the Base Defini- + tions volume of IEEE Std 1003.1-2001, Chapter 5, + File Format Notation ( '\\' , '\a' , '\b' , '\f' + , '\n' , '\r' , '\t' , '\v' ), which shall be + converted to the characters they represent + + "\0ddd" , where 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 + + '\c' , which shall not be written and shall cause + printf to ignore any remaining characters in the + string operand containing it, any remaining + string operands, and any additional characters in + the format operand + + The interpretation of a backslash followed by any other + sequence of characters is unspecified. + + 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 preci- + sion is omitted, it shall be taken to be infinite, so + all bytes up to the end of the converted string shall be + written. + + For each conversion specification that consumes an argu- + ment, the next argument operand shall be evaluated and + converted to the appropriate type for the conversion as + specified below. + + The format operand shall be reused as often as necessary + to satisfy the argument operands. Any extra c or s con- + version 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 format operand contains no con- + version specifications and argument operands are + present, the results are unspecified. + + If a character sequence in the format operand begins + with a '%' character, but does not form a valid conver- + sion specification, the behavior is unspecified. + + The argument operands shall be treated as strings if the + corresponding conversion specifier is b , c , or s ; + otherwise, it shall be evaluated as a C constant, as + described by the ISO C standard, with the following + extensions: + + A leading plus or minus sign shall be allowed. + + 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. + + 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 accumu- + lated at the time the error was detected to standard + output. + + It is not considered an error if an argument operand is + not completely used for a c or s conversion or if a + string operand's first or second character is used to + get the numeric value of a character. + +EXIT STATUS + The following exit values shall be returned: + + 0 Successful completion. + + >0 An error occurred. + + +CONSEQUENCES OF ERRORS + Default. + + The following sections are informative. + +APPLICATION USAGE + The floating-point formatting conversion specifications + of printf() are not required because all arithmetic in + the shell is integer arithmetic. The awk utility per- + forms floating-point calculations and provides its own + printf function. The bc utility can perform arbitrary- + precision floating-point arithmetic, but does not pro- + vide extensive formatting capabilities. (This printf + utility cannot really be used to format bc output; it + does not support arbitrary precision.) Implementations + are encouraged to support the floating-point conversions + as an extension. + + Note that this printf utility, like the printf() func- + tion defined in the System Interfaces volume of + IEEE Std 1003.1-2001 on which it is based, makes no spe- + cial provision for dealing with multi-byte characters + when using the %c conversion specification or when a + precision is specified in a %b or %s conversion specifi- + cation. Applications should be extremely cautious using + either of these features when there are multi-byte char- + acters in the character set. + + No provision is made in this volume of + IEEE Std 1003.1-2001 which allows field widths and pre- + cisions to be specified as '*' since the '*' can be + replaced directly in the format operand using shell + variable substitution. Implementations can also provide + this feature as an extension if they so choose. + + Hexadecimal character constants as defined in the ISO C + standard are not recognized in the 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 charac- + ter. In the ISO C standard, the "##" concatenation oper- + ator can be used to terminate a constant and follow it + with a hexadecimal character to be written. In the + shell, concatenation occurs before the printf utility + has a chance to parse the end of the hexadecimal con- + stant. + + The %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 echo utility. See also the APPLICATION + USAGE section of echo for ways to use printf as a + replacement for all of the traditional versions of the + echo utility. + + If an argument cannot be parsed correctly for the corre- + sponding conversion specification, the printf utility is + required to report an error. Thus, overflow and extrane- + ous characters at the end of an argument being used for + a numeric conversion shall be reported as errors. + +EXAMPLES + To alert the user and then print and read a series of + prompts: + + + printf "\aPlease fill in the following: \nName: " + read name + printf "Phone number: " + read phone + + 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: + + + while 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 + The command: + + + printf "%5d%4d\n" 1 21 321 4321 54321 + + produces: + + + 1 21 + 3214321 + 54321 0 + + Note that the format operand is used three times to + print all of the given strings and that a '0' was sup- + plied by printf to satisfy the last %4d conversion spec- + ification. + + The 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 %d is specified as the format operand: + 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 + + 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 stan- + dard output is what would be expected as the return + value from the strtol() function as defined in the Sys- + tem Interfaces volume of IEEE Std 1003.1-2001. A similar + correspondence exists between %u and strtoul() and %e , + %f , and %g (if the implementation supports floating- + point conversions) and strtod(). + + In a locale using the ISO/IEC 646:1991 standard as the + underlying codeset, the command: + + + printf "%d\n" 3 +3 -3 \'3 \"+3 "'-3" + + produces: + + 3 Numeric value of constant 3 + + 3 Numeric value of constant 3 + + -3 Numeric value of constant -3 + + 51 Numeric value of the character '3' in the + ISO/IEC 646:1991 standard codeset + + 43 Numeric value of the character '+' in the + ISO/IEC 646:1991 standard codeset + + 45 Numeric value of the character '-' in the + ISO/IEC 646:1991 standard codeset + + + 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 wchar_t representation of the charac- + ter as described in the System Interfaces volume of + IEEE Std 1003.1-2001. + +RATIONALE + The printf utility was added to provide functionality + that has historically been provided by echo. However, + due to irreconcilable differences in the various ver- + sions of echo extant, the version has few special fea- + tures, leaving those to this new printf utility, which + is based on one in the Ninth Edition system. + + The EXTENDED DESCRIPTION section almost exactly matches + the printf() 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. + +FUTURE DIRECTIONS + None. + +SEE ALSO + awk , bc , echo , the System Interfaces volume of + IEEE Std 1003.1-2001, printf() + +COPYRIGHT + Portions of this text are reprinted and reproduced in + electronic form from IEEE Std 1003.1, 2003 Edition, + Standard for Information Technology -- Portable Operat- + ing System Interface (POSIX), The Open Group Base Speci- + fications Issue 6, Copyright (C) 2001-2003 by the Insti- + tute 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.open- + group.org/unix/online.html . + + + +POSIX 2003 printf(P) |