printf stuff mei/printf

1 files changed, 355 insertions, 0 deletions

diff --git a/usr/src/mei/printf/formats.7.man b/usr/src/mei/printf/formats.7.man
new file mode 100644
index 0000000..c10ccdf
--- /dev/null
+++ b/usr/src/mei/printf/formats.7.man
@@ -0,0 +1,355 @@
+FORMATS(7)            Standards, Environments, and Macros           FORMATS(7)
+
+NNAAMMEE
+       formats - file format notation
+
+DDEESSCCRRIIPPTTIIOONN
+       Utility descriptions use a syntax to describe the data organization
+       within files—stdin, stdout, stderr, input files, and output files—when
+       that organization is not otherwise obvious. The syntax is similar to
+       that used by the  pprriinnttff(3C) function.  When used for stdin or input
+       file descriptions, this syntax describes the format that could have
+       been used to write the text to be read, not a format that could be used
+       by the ssccaannff(3C) function to read the input file.
+
+   FFoorrmmaatt
+       The description of an individual record is as follows:
+
+         "<ffoorrmmaatt>", [<_a_r_g_1>, <_a_r_g_2>, ..., <_a_r_g_n>]
+
+
+
+       The ffoorrmmaatt is a character string that contains three types of objects
+       defined below:
+
+       _c_h_a_r_a_c_t_e_r_s
+                                     Characters that are not _e_s_c_a_p_e _s_e_q_u_e_n_c_e_s
+                                     or _c_o_n_v_e_r_s_i_o_n _s_p_e_c_i_f_i_c_a_t_i_o_n_s, as
+                                     described below, are copied to the
+                                     output.
+
+
+       _e_s_c_a_p_e _s_e_q_u_e_n_c_e_s
+                                     Represent non-graphic characters.
+
+
+       _c_o_n_v_e_r_s_i_o_n _s_p_e_c_i_f_i_c_a_t_i_o_n_s
+                                     Specifies the output format of each
+                                     argument. (See below.)
+
+
+
+       The following characters have the following special meaning in the
+       format string:
+
+       ```` ''''
+                  (An empty character position.) One or more blank characters.
+
+
+       //\\
+                  Exactly one space character.
+
+
+
+       The notation for spaces allows some flexibility for application output.
+       Note that an empty character position in ffoorrmmaatt represents one or more
+       blank characters on the output (not _w_h_i_t_e _s_p_a_c_e, which can include
+       newline characters). Therefore, another utility that reads that output
+       as its input must be prepared to parse the data using ssccaannff(3C),
+       aawwkk(1), and so forth. The  character is used when exactly one space
+       character is output.
+
+   EEssccaappee SSeeqquueenncceess
+       The following table lists escape sequences and  associated actions on
+       display devices capable of the action.
+
+
+
+
+       SSeeqquueennccee      CChhaarraacctteerr       TTeerrmmiinnaall AAccttiioonn
+       ────────────────────────────────────────────────
+       \\\\         backslash         None.
+       \\aa         alert             Attempts to alert
+                                    the user through
+                                    audible or visible
+                                    notification.
+       \\bb         backspace         Moves the printing
+                                    position to one
+                                    column before the
+                                    current position,
+                                    unless the current
+                                    position is the
+                                    start of a line.
+       \\ff         form-feed         Moves the printing
+                                    position to the
+                                    initial printing
+                                    position of the
+                                    next logical page.
+       \\nn         newline           Moves the printing
+                                    position to the
+                                    start of the next
+                                    line.
+       \\rr         carriage-return   Moves the printing
+                                    position to the
+                                    start of the
+                                    current line.
+       \\tt         tab               Moves the printing
+                                    position to the
+                                    next tab position
+                                    on the current
+                                    line. If there are
+                                    no more tab
+                                    positions left on
+                                    the line, the
+                                    behavior is
+                                    undefined.
+       \\vv         vertical-tab      Moves the printing
+                                    position to the
+                                    start of the next
+                                    vertical tab
+                                    position. If there
+                                    are no more
+                                    vertical tab
+                                    positions left on
+                                    the page, the
+                                    behavior is
+                                    undefined.
+
+
+   CCoonnvveerrssiioonn SSppeecciiffiiccaattiioonnss
+       Each conversion specification is introduced by the percent-sign
+       character (%).  After the character %, the following appear in
+       sequence:
+
+       _f_l_a_g_s
+                                 Zero or more _f_l_a_g_s, in any order, that modify
+                                 the meaning of the conversion specification.
+
+
+       _f_i_e_l_d _w_i_d_t_h
+                                 An optional string of decimal digits to
+                                 specify a minimum _f_i_e_l_d _w_i_d_t_h.  For an output
+                                 field, if the converted value has fewer bytes
+                                 than the field width, it is padded on the
+                                 left (or right, if the left-adjustment flag
+                                 (−), described below, has been given to the
+                                 field width).
+
+
+       _p_r_e_c_i_s_i_o_n
+                                 Gives the minimum number of digits to appear
+                                 for the d, o, i, u, x or X conversions (the
+                                 field is padded with leading zeros), the
+                                 number of digits to appear after the radix
+                                 character for the e and f conversions, the
+                                 maximum number of significant digits for the
+                                 g conversion; or the maximum number of bytes
+                                 to be written from a string in s conversion.
+                                 The precision takes the form of a period (.)
+                                 followed by a decimal digit string; a null
+                                 digit string is treated as zero.
+
+
+       _c_o_n_v_e_r_s_i_o_n _c_h_a_r_a_c_t_e_r_s
+                                 A conversion character (see below) that
+                                 indicates the type of conversion to be
+                                 applied.
+
+
+   _f_l_a_g_s
+       The _f_l_a_g_s and their meanings are:
+
+       _−
+                   The result of the conversion is left-justified within the
+                   field.
+
+
+       _+
+                   The result of a signed conversion always begins with a sign
+                   (+ or −).
+
+
+       _<_s_p_a_c_e_>
+                   If the first character of a signed conversion is not a
+                   sign, a space character is prefixed to the result. This
+                   means that if the space character and + flags both appear,
+                   the space character flag is ignored.
+
+
+       _#
+                   The value is to be converted to an alternative form. For c,
+                   d, i, u, and s conversions, the behaviour is undefined. For
+                   o conversion, it increases the precision to force the first
+                   digit of the result to be a zero. For x or X conversion, a
+                   non-zero result has 0x or 0X prefixed to it, respectively.
+                   For e, E, f, g, and G conversions, the result always
+                   contains a radix character, even if no digits follow the
+                   radix character. For g and G conversions, trailing zeros
+                   are not removed from the result as they usually are.
+
+
+       _0
+                   For d, i, o, u, x, X, e, E, f, g, and G conversions,
+                   leading zeros (following any indication of sign or base)
+                   are used to pad to the field width; no space padding is
+                   performed. If the 0 and − flags both appear, the 0 flag is
+                   ignored. For d, i, o, u, x and X conversions, if a
+                   precision is specified, the 0 flag is ignored. For other
+                   conversions, the behaviour is undefined.
+
+
+   CCoonnvveerrssiioonn CChhaarraacctteerrss
+       Each conversion character results in fetching zero or more arguments.
+       The results are undefined if there are insufficient arguments for the
+       format. If the format is exhausted while arguments remain, the excess
+       arguments are ignored.
+
+
+       The _c_o_n_v_e_r_s_i_o_n _c_h_a_r_a_c_t_e_r_s and their meanings are:
+
+       _d_,_i_,_o_,_u_,_x_,_X
+                       The integer argument is written as signed decimal (d or
+                       i), unsigned octal (o), unsigned decimal (u), or
+                       unsigned hexadecimal notation (x and X). The d and i
+                       specifiers convert to signed decimal in the style
+                       [[−]]_d_d_d_d.  The x conversion uses the numbers and letters
+                       0123456789abcdef and the X conversion uses the numbers
+                       and letters 0123456789ABCDEF. The _p_r_e_c_i_s_i_o_n component
+                       of the argument specifies the minimum number of digits
+                       to appear. If the value being converted can be
+                       represented in fewer digits than the specified minimum,
+                       it is expanded with leading zeros. The default
+                       precision is 1. The result of converting a zero value
+                       with a precision of 0 is no characters. If both the
+                       field width and precision are omitted, the
+                       implementation may precede, follow or precede and
+                       follow numeric arguments of types d, i and u with blank
+                       characters; arguments of type o (octal) may be preceded
+                       with leading zeros.
+
+                       The treatment of integers and spaces is different from
+                       the pprriinnttff(3C) function in that they can be surrounded
+                       with blank characters. This was done so that, given a
+                       format such as:
+
+                         "%d\n",<_f_o_o>
+
+                       the implementation could use a pprriinnttff(()) call such as:
+
+                         printf("%6d\n", _f_o_o);
+
+                       and still conform. This notation is thus somewhat like
+                       ssccaannff(()) in addition to pprriinnttff(())..
+
+
+       _f
+                       The floating point number argument is written in
+                       decimal notation in the style [[−]]_d_d_d._d_d_d, where the
+                       number of digits after the radix character (shown here
+                       as a decimal point) is equal to the _p_r_e_c_i_s_i_o_n
+                       specification. The LLCC__NNUUMMEERRIICC locale category
+                       determines the radix character to use in this format.
+                       If the _p_r_e_c_i_s_i_o_n is omitted from the argument, six
+                       digits are written after the radix character; if the
+                       _p_r_e_c_i_s_i_o_n is explicitly 0, no radix character appears.
+
+
+       _e_,_E
+                       The floating point number argument is written in the
+                       style [[−]]_d._d_d_de±dddd (the symbol ± indicates either a
+                       plus or minus sign), where there is one digit before
+                       the radix character (shown here as a decimal point) and
+                       the number of digits after it is equal to the
+                       precision. The  LLCC__NNUUMMEERRIICC locale category determines
+                       the radix character to use in this format. When the
+                       precision is missing, six digits are  written after the
+                       radix character; if the precision is 0, no radix
+                       character appears. The E conversion character produces
+                       a number with E instead of e introducing the exponent.
+                       The exponent always contains at least two digits.
+                       However, if the value to be written requires an
+                       exponent greater than two digits, additional exponent
+                       digits are written as necessary.
+
+
+       _g_,_G
+                       The floating point number argument is written in style
+                       f or e (or in style E in the case of a G conversion
+                       character), with the precision specifying the number of
+                       significant digits. The style used depends on the value
+                       converted: style g is used only if the exponent
+                       resulting from the conversion is less than −4 or
+                       greater than or equal to the precision. Trailing zeros
+                       are removed from the result. A radix character appears
+                       only if it is followed by a digit.
+
+
+       _c
+                       The integer argument is converted to an uunnssiiggnneedd cchhaarr
+                       and the resulting byte is written.
+
+
+       _s
+                       The argument is taken to be a string and bytes from the
+                       string are written until the end of the string or the
+                       number of bytes indicated by the _p_r_e_c_i_s_i_o_n
+                       specification of the argument is reached. If the
+                       precision is omitted from the argument, it is taken to
+                       be infinite, so all bytes up to the end of the string
+                       are written.
+
+
+       _%
+                       Write a % character; no argument is converted.
+
+
+
+       In no case does a non-existent or insufficient _f_i_e_l_d _w_i_d_t_h cause
+       truncation of a field; if the result of a conversion is wider than the
+       field width, the field is simply expanded to contain the conversion
+       result. The term _f_i_e_l_d _w_i_d_t_h should not be confused with the term
+       _p_r_e_c_i_s_i_o_n used in the description of %s.
+
+
+       One difference from the C function pprriinnttff(()) is that the l and h
+       conversion characters are not used. There is no differentiation between
+       decimal values for type iinntt, type  lloonngg, or type  sshhoorrtt. The
+       specifications %d or %i should be interpreted as an arbitrary length
+       sequence of digits. Also, no distinction is made between single
+       precision and double precision numbers (ffllooaatt or ddoouubbllee in C).  These
+       are simply referred to as floating point numbers.
+
+
+       Many of the output descriptions  use the term lliinnee, such as:
+
+         "%s", <_i_n_p_u_t _l_i_n_e>
+
+
+
+       Since the definition of lliinnee includes the trailing newline character
+       already, there is no need to include a \\nn in the format; a double
+       newline character would otherwise result.
+
+EEXXAAMMPPLLEESS
+       EExxaammppllee 11 To represent the output of a program that prints a date and
+       time in the form Sunday, July 3, 10:02, where _<_w_e_e_k_d_a_y_> and _<_m_o_n_t_h_> are
+       strings:
+
+         "%s,/\%s/\%d,/\%d:%.2d\n",<_w_e_e_k_d_a_y>,<_m_o_n_t_h>,<_d_a_y>,<_h_o_u_r>,<_m_i_n>
+
+
+       EExxaammppllee 22 To show pi written to 5 decimal places:
+
+         "pi/\=/\%.5f\n",<_v_a_l_u_e _o_f _p_i>
+
+
+       EExxaammppllee 33 To show an input file format consisting of five colon-
+       separated fields:
+
+         "%s:%s:%s:%s:%s\n",<_a_r_g_1>,<_a_r_g_2>,<_a_r_g_3>,<_a_r_g_4>,<_a_r_g_5>
+
+
+SSEEEE AALLSSOO
+       aawwkk(1), pprriinnttff(1), pprriinnttff(3C), ssccaannff(3C)
+
+                                March 28, 1995                      FORMATS(7)