printf stuff mei/printf

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)