diff options
Diffstat (limited to 'usr/src/mei/printf/printf.1.man')
| -rw-r--r-- | usr/src/mei/printf/printf.1.man | 692 |
1 files changed, 692 insertions, 0 deletions
diff --git a/usr/src/mei/printf/printf.1.man b/usr/src/mei/printf/printf.1.man new file mode 100644 index 0000000..259e9a9 --- /dev/null +++ b/usr/src/mei/printf/printf.1.man @@ -0,0 +1,692 @@ +PRINTF(1) User Commands PRINTF(1) + +NNAAMMEE + printf - write formatted output + +SSYYNNOOPPSSIISS + //uussrr//bbiinn//pprriinnttff + pprriinnttff _f_o_r_m_a_t [_a_r_g_u_m_e_n_t]... + + + kksshh9933 + pprriinnttff _f_o_r_m_a_t [_s_t_r_i_n_g...] + + +DDEESSCCRRIIPPTTIIOONN + //uussrr//bbiinn//pprriinnttff + The pprriinnttff utility writes each string operand to standard output using + _f_o_r_m_a_t to control the output format. + +OOPPEERRAANNDDSS + //uussrr//bbiinn//pprriinnttff + The following operands are supported by //uussrr//bbiinn//pprriinnttff: + + _f_o_r_m_a_t + A string describing the format to use to write the + remaining operands. The _f_o_r_m_a_t operand is used as the + _f_o_r_m_a_t string described on the ffoorrmmaattss(7) manual page, with + the following exceptions: + + o A SSPPAACCEE character in the format string, in any + context other than a flag of a conversion + specification, is treated as an ordinary + character that is copied to the output. + + o A character in the format string is treated as a + character, not as a SSPPAACCEE character. + + o In addition to the escape sequences described on + the ffoorrmmaattss(7) manual page (\\\\, \\aa, \\bb, \\ff, \\nn, + \\rr, \\tt, \\vv), \\_d_d_d, where _d_d_d is a one-, two- or + three-digit octal number, is written as a byte + with the numeric value specified by the octal + number. + + o The program does not precede or follow output + from the dd or uu conversion specifications with + blank characters not specified by the _f_o_r_m_a_t + operand. + + o The program does not precede output from the oo + conversion specification with zeros not + specified by the _f_o_r_m_a_t operand. + + o The argument used for the conversion character + (or width or precision parameters, see below) + may be taken from the _nnth argument instead of + the next unused argument, by specifying _n$$ + immediately following the %% character, or the ** + character (for width or precision arguments). + If _n$$ appears in any conversions in the format + string, then it must be used for all + conversions, including any variable width or + precision specifiers. + + o The special character ** may be used instead of a + string of decimal digits to indicate a minimum + field width or a precision. In this case the + next available argument is used (or the _nth if + the form _n$$ is used), treating its value as a + decimal string. + + o An additional conversion character, bb, is + supported as follows. The argument is taken to + be a string that can contain backslash-escape + sequences. The following backslash-escape + sequences are supported: + + o the escape sequences listed on the + ffoorrmmaattss(7) manual page (\\\\, \\aa, \\bb, \\ff, \\nn, + \\rr, \\tt, \\vv), which are converted to the + characters they represent + + o \\00_d_d_d, where _d_d_d is a zero-, one-, two- or + three-digit octal number that is converted + to a byte with the numeric value specified + by the octal number + + o \\cc, which is written and causes pprriinnttff to + ignore any remaining characters in the + string operand containing it, any remaining + string operands and any additional + characters in the _f_o_r_m_a_t operand. + The interpretation of a backslash followed by any other + sequence of characters is unspecified. + + Bytes from the converted string are 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 is taken to be infinite, so all bytes up to the + end of the converted string are written. For each + specification that consumes an argument, the next argument + operand is evaluated and converted to the appropriate type + for the conversion as specified below. The _f_o_r_m_a_t operand + is reused as often as necessary to satisfy the argument + operands. Any extra cc or ss conversion specifications are + evaluated as if a null string argument were supplied; other + extra conversion specifications are evaluated as if a zero + argument were supplied. + + When there are more argument operands than format + specifiers, and the format includes _n$$ position indicators, + then the format is reprocessed from the beginning as above, + but with the argument list starting from the next argument + after the highest _nth argument previously encountered. + + If the _f_o_r_m_a_t operand contains no conversion specifications + and _a_r_g_u_m_e_n_t operands are present, the results are + unspecified. If a character sequence in the _f_o_r_m_a_t operand + begins with a %% character, but does not form a valid + conversion specification, the behavior is unspecified. + + + _a_r_g_u_m_e_n_t + The strings to be written to standard output, under the + control of ffoorrmmaatt. The _a_r_g_u_m_e_n_t operands are treated as + strings if the corresponding conversion character is bb, cc + or ss. Otherwise, it is evaluated as a C constant, as + described by the ISO C standard, with the following + extensions: + + o A leading plus or minus sign is allowed. + + o If the leading character is a single- or double- + quote, the value is the numeric value in the + underlying codeset of the character following + the single- or double-quote. + If an argument operand cannot be completely converted into + an internal value appropriate to the corresponding + conversion specification, a diagnostic message is written + to standard error and the utility does not exit with a zero + exit status, but continues processing any remaining + operands and writes the value accumulated at the time the + error was detected to standard output. + + + kksshh9933 + The _f_o_r_m_a_t operands support the full range of ANSI C/C99/XPG6 + formatting specifiers as well as additional specifiers: + + %%bb + Each character in the string operand is processed specially, as + follows: + + \\aa + Alert character. + + + \\bb + Backspace character. + + + \\cc + Terminate output without appending NEWLINE. The remaining + string operands are ignored. + + + \\EE + Escape character (AASSCCIIII octal 003333). + + + \\ff + FORM FEED character. + + + \\nn + NEWLINE character. + + + \\tt + TAB character. + + + \\vv + Vertical tab character. + + + \\\\ + Backslash character. + + + \\00_x + The 8-bit character whose AASSCCIIII code is the 11-, 22-, or + 33-digit octal number _x. + + + + %%BB + Treat the argument as a variable name and output the value + without converting it to a string. This is most useful for + variables of type --bb. + + + %%HH + Output string with characters <<, &&, >>, "", and non-printable + characters, properly escaped for use in HTML and XML documents. + + + %%PP + Treat _s_t_r_i_n_g as an extended regular expression and convert it to + a shell pattern. + + + %%qq + Output _s_t_r_i_n_g quoted in a manner that it can be read in by the + shell to get back the same string. However, empty strings + resulting from missing string operands are not quoted. + + + %%RR + Treat _s_t_r_i_n_g as an shell pattern expression and convert it to an + extended regular expression. + + + %%TT + Treat _s_t_r_i_n_g as a date/time string and format it. The TT can be + preceded by (_d_f_o_r_m_a_t), where _d_f_o_r_m_a_t is a date format as defined + by the ddaattee(1) command. + + + %%ZZ + Output a byte whose value is 00. + + + + When performing conversions of _s_t_r_i_n_g to satisfy a numeric format + specifier, if the first character of _s_t_r_i_n_g is ""oorr'', the value is the + numeric value in the underlying code set of the character following the + ""oorr''. Otherwise, _s_t_r_i_n_g is treated like a shell arithmetic expression + and evaluated. + + + If a _s_t_r_i_n_g operand cannot be completely converted into a value + appropriate for that format specifier, an error occurs, but remaining + _s_t_r_i_n_g operands continue to be processed. + + + In addition to the format specifier extensions, the following + extensions of ANSI C/C99/XPG6 are permitted in format specifiers: + + o The escape sequences \\EE and \\ee expand to the escape + character which is octal 033 in ASCII. + + o The escape sequence \\ccxx expands to CTRL-x. + + o The escape sequence \\CC[[.._n_a_m_e..]] expands to the collating + element _n_a_m_e. + + o The escape sequence \\xx{{hheexx}} expands to the character + corresponding to the hexadecimal value hheexx. + + o The format modifier flag = can be used to center a field to + a specified width. When the output is a terminal, the + character width is used rather than the number of bytes. + + o Each of the integral format specifiers can have a third + modifier after width and precision that specifies the base + of the conversion from 2 to 64. In this case, the ## modifier + causes _b_a_s_e## to be prepended to the value. + + o The ## modifier can be used with the dd specifier when no base + is specified to cause the output to be written in units of + 1000 with a suffix of one of kk MM GG TT PP EE. + + o The ## modifier can be used with the ii specifier to cause the + output to be written in units of 11002244 with a suffix of one + of KKii MMii GGii TTii PPii EEii. + + + If there are more _s_t_r_i_n_g operands than format specifiers, the format + string is reprocessed from the beginning. If there are fewer _s_t_r_i_n_g + operands than format specifiers, then _s_t_r_i_n_g specifiers are treated as + if empty strings were supplied, numeric conversions are treated as if 00 + was supplied, and time conversions are treated as if nnooww was supplied. + + + When there are more argument operands than format specifiers, and the + format includes _n$$ position indicators, then the format is reprocessed + from the beginning as above, but with the argument list starting from + the next argument after the highest _nth argument previously + encountered. + + + //uussrr//bbiinn//pprriinnttff is equivalent to kksshh9933's pprriinnttff built-in and pprriinntt --ff, + which allows additional options to be specified. + +UUSSAAGGEE + //uussrr//bbiinn//pprriinnttff + The pprriinnttff utility, like the pprriinnttff(3C) function on which it is based, + makes no special provision for dealing with multi-byte characters when + using the %%cc conversion specification. Applications should be extremely + cautious using either of these features when there are multi-byte + characters in the character set. + + + The %%bb 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 eecchhoo utility. See also + the USAGE section of the eecchhoo(1) manual page for ways to use pprriinnttff as + a replacement for all of the traditional versions of the eecchhoo utility. + + + If an argument cannot be parsed correctly for the corresponding + conversion specification, the pprriinnttff utility reports an error. Thus, + overflow and extraneous characters at the end of an argument being used + for a numeric conversion are to be reported as errors. + + + It is not considered an error if an argument operand is not completely + used for a cc or ss conversion or if a string operand's first or second + character is used to get the numeric value of a character. + +EEXXAAMMPPLLEESS + //uussrr//bbiinn//pprriinnttff + EExxaammppllee 11 Printing a Series of Prompts + + + The following example alerts the user, then prints and reads a series + of prompts: + + + example% pprriinnttff ""\\aaPPlleeaassee ffiillll iinn tthhee ffoolllloowwiinngg:: \\nnNNaammee:: "" + rreeaadd nnaammee + pprriinnttff ""PPhhoonnee nnuummbbeerr:: "" + rreeaadd pphhoonnee + + + + EExxaammppllee 22 Printing a Table of Calculations + + + The following example prints a table of calculations. It reads out a + list of right and wrong answers from a file, calculates the percentage + correctly, and prints them out. The numbers are right-justified and + separated by a single tab character. The percentage is written to one + decimal place of accuracy: + + + example% wwhhiillee rreeaadd rriigghhtt wwrroonngg ;; ddoo + ppeerrcceenntt==$$((eecchhoo ""ssccaallee==11;;(($$rriigghhtt**110000))//(($$rriigghhtt++$$wwrroonngg))"" || bbcc)) + pprriinnttff ""%%22dd rriigghhtt\\tt%%22dd wwrroonngg\\tt((%%ss%%%%))\\nn"" \\ + $$rriigghhtt $$wwrroonngg $$ppeerrcceenntt + ddoonnee << ddaattaabbaassee__ffiillee + + + + EExxaammppllee 33 Printing number strings + + + The command: + + + example% pprriinnttff ""%%55dd%%44dd\\nn"" 11 2211 332211 44332211 5544332211 + + + + + produces: + + + 1 21 + 3214321 + 54321 0 + + + + + The _f_o_r_m_a_t operand is used three times to print all of the given + strings and that a 00 was supplied by pprriinnttff to satisfy the last %%44dd + conversion specification. + + + EExxaammppllee 44 Tabulating Conversion Errors + + + The following example tabulates conversion errors. + + + + The pprriinnttff utility tells the user when conversion errors are detected + while producing numeric output. These results would be expected on an + implementation with 32-bit twos-complement integers when %%dd is + specified as the _f_o_r_m_a_t operand: + + + + + + ┌───────────────────────────────────────────────────────────────────┐ + │ Arguments Standard Diagnostic │ + │5a 5 printf: 5a not completely converted │ + │9999999999 2147483647 printf: 9999999999: Results too large │ + │-9999999999 -2147483648 printf: -9999999999: Results too large │ + │ABC 0 printf: ABC expected numeric value │ + └───────────────────────────────────────────────────────────────────┘ + + + The value shown on standard output is what would be expected as the + return value from the function ssttrrttooll(3C). A similar correspondence + exists between %%uu and ssttrrttoouull(3C), and %%ee, %%ff and %%gg and ssttrrttoodd(3C). + + + EExxaammppllee 55 Printing Output for a Specific Locale + + + The following example prints output for a specific locale. In a locale + using the ISO/IEC 646:1991 standard as the underlying codeset, the + command: + + + example% pprriinnttff ""%%dd\\nn"" 33 ++33 --33 \\''33 \\""++33 ""''--33"" + + + + + produces: + + + + + + ┌──────────────────────────────────┐ + │33 Numeric value of constant 3 │ + │33 Numeric value of constant 3 │ + │−−33 Numeric value of constant −3 │ + │5511 Numeric value of the │ + │ character `3' in the ISO/IEC │ + │ 646:1991 standard codeset │ + │4433 Numeric value of the │ + │ character `+' in the ISO/IEC │ + │ 646:1991 standard codeset │ + │4455 Numeric value of the │ + │ character `−' in the SO/IEC │ + │ 646:1991 standard codeset │ + └──────────────────────────────────┘ + + + In a locale with multi-byte characters, the value of a character is + intended to be the value of the equivalent of the wwcchhaarr__tt + representation of the character. + + + + If an argument operand cannot be completely converted into an internal + value appropriate to the corresponding conversion specification, a + diagnostic message is written to standard error and the utility does + exit with a zero exit status, but continues processing any remaining + operands and writes the value accumulated at the time the error was + detected to standard output. + + + EExxaammppllee 66 Alternative floating point representation 1 + + + The pprriinnttff utility supports an alternative floating point + representation (see pprriinnttff(3C) entry for the "%%aa"/"%%AA"), which allows + the output of floating-point values in a format that avoids the usual + base16 to base10 rounding errors. + + + example% printf "%a\n" 2 3.1 NaN + + + + + produces: + + + 0x1.0000000000000000000000000000p+01 + 0x1.8ccccccccccccccccccccccccccdp+01 + nan + + + + EExxaammppllee 77 Alternative floating point representation 2 + + + The following example shows two different representations of the same + floating-point value. + + + example% x=2 ; printf "%f == %a\n" x x + + + + + produces: + + + 2.000000 == 0x1.0000000000000000000000000000p+01 + + + + EExxaammppllee 88 Output of unicode values + + + The following command will print the EURO unicode symbol (code-point + 0x20ac). + + + example% LC_ALL=en_US.UTF-8 printf "[20ac]\n" + + + + + produces: + + + <euro> + + + + + where "<euro>" represents the EURO currency symbol character. + + + EExxaammppllee 99 Convert unicode character to unicode code-point value + + + The following command will print the hexadecimal value of a given + character. + + + example% export LC_ALL=en_US.UTF-8 + example% printf "%x\n" "'<euro>" + + + + + where "<euro>" represents the EURO currency symbol character (code- + point 0x20ac). + + + + produces: + + + 20ac + + + + EExxaammppllee 1100 Print the numeric value of an ASCII character + + example% printf "%d\n" "'A" + + + + + produces: + + + 65 + + + + EExxaammppllee 1111 Print the language-independent date and time format + + + To print the language-independent date and time format, the following + statement could be used: + + + example% printf "format" weekday month day hour min + + + + + For example, + + + $ printf format "Sunday" "July" 3 10 2 + + + + + For American usage, format could be the string: + + + "%s, %s %d, %d:%.2d\n" + + + + + producing the message: + + + Sunday, July 3, 10:02 + + + + + Whereas for EU usage, format could be the string: + + + "%1$s, %3$d. %2$s, %4$d:%5$.2d\n" + + + + + Note that the '$' characters must be properly escaped, such as + + + "%1\$s, %3\$d. %2\$s, %4\$d:%5\$.2d\n" in this case + + + + + producing the message: + + + Sunday, 3. July, 10:02 + + + +EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS + See eennvviirroonn(7) for descriptions of the following environment variables + that affect the execution of pprriinnttff: LLAANNGG, LLCC__AALLLL, LLCC__CCTTYYPPEE, + LLCC__MMEESSSSAAGGEESS, LLCC__NNUUMMEERRIICC, and NNLLSSPPAATTHH. + +EEXXIITT SSTTAATTUUSS + The following exit values are returned: + + 00 + Successful completion. + + + >>00 + An error occurred. + + +AATTTTRRIIBBUUTTEESS + See aattttrriibbuutteess(7) for descriptions of the following attributes: + + //uussrr//bbiinn//pprriinnttff + + + + ┌────────────────────┬───────────────────┐ + │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │ + ├────────────────────┼───────────────────┤ + │CSI │ Enabled │ + ├────────────────────┼───────────────────┤ + │Interface Stability │ Committed │ + ├────────────────────┼───────────────────┤ + │Standard │ See ssttaannddaarrddss(7). │ + └────────────────────┴───────────────────┘ + + kksshh9933 + + + + ┌────────────────────┬─────────────────┐ + │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │ + ├────────────────────┼─────────────────┤ + │Interface Stability │ Uncommitted │ + └────────────────────┴─────────────────┘ + +SSEEEE AALLSSOO + aawwkk(1), bbcc(1), ddaattee(1), eecchhoo(1), kksshh9933(1), pprriinnttff(3C), ssttrrttoodd(3C), + ssttrrttooll(3C), ssttrrttoouull(3C), aattttrriibbuutteess(7), eennvviirroonn(7), ffoorrmmaattss(7), + ssttaannddaarrddss(7) + +NNOOTTEESS + Using format specifiers (characters following '%') which are not listed + in the pprriinnttff(3C) or this manual page will result in undefined + behavior. + + + Using escape sequences (the character following a backslash ('\')) + which are not listed in the pprriinnttff(3C) or this manual page will result + in undefined behavior. + + + Floating-point values follow C99, XPG6 and IEEE 754 standard behavior + and can handle values the same way as the platform's |lloonngg ddoouubbllee| + datatype. + + + Floating-point values handle the sign separately which allows signs for + values like NaN (for example, -nan), Infinite (for example, -inf) and + zero (for example, -0.0). + + May 11, 2014 PRINTF(1) |