unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

formats(5)            Standards, Environments, and Macros           formats(5)



NAME
       formats - file format notation

DESCRIPTION
       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  printf(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  scanf(3C) function to read the input file.

   Format
       The description of an individual record is as follows:

       "<format>", [<arg1>, <arg2>, ..., <argn>]


       The  format  is a character string that contains three types of objects
       defined below:

       characters              Characters that are  not  escape  sequences  or
                               conversion  specifications, as described below,
                               are copied to the output.



       escape sequences        Represent non-graphic characters.



       conversion specificationspecifies the output format of  each  argument.
                               (See below.)



       The following characters have the following special meaning in the for-
       mat 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 format represents one or  more
       blank characters on the output (not white space, which can include new-
       line characters). Therefore, another utility that reads that output  as
       its  input  must be prepared to parse the data using scanf(3C), awk(1),
       and so forth. The  character is used when exactly one  space  character
       is output.

   Escape Sequences
       The  following  table lists escape sequences and  associated actions on
       display devices capable of the action.


       tab();   cw(1.208333i)   cw(1.152778i)   lw(3.138889i)    cw(1.208333i)
       lw(1.152778i)  lw(3.138889i).  SequenceCharacterTerminal Action \\back-
       slashNone.  \aalertT{ Attempts to alert the  user  through  audible  or
       visible  notification.  T} \bbackspaceT{ Moves the printing position to
       one column before the current position, unless the current position  is
       the  start  of a line.  T} \fform-feedT{ Moves the printing position to
       the initial printing position of the next logical page.  T} \nnewlineT{
       Moves  the  printing position to the start of the next line.  T} \rcar-
       riage-returnT{ Moves the printing position to the start of the  current
       line.   T} \ttabT{ 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.  T} \vvertical-tabT{ Moves the print-
       ing 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.  T}


   Conversion Specifications
       Each conversion specification is introduced by the percent-sign charac-
       ter (%). After the character %, the following appear in sequence:

       flags                   Zero  or  more flags, in any order, that modify
                               the meaning of the conversion specification.



       field width             An optional string of decimal digits to specify
                               a  minimum field width. 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).



       precision               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.



       conversion characters   A conversion character (see below)  that  indi-
                               cates the type of conversion to be applied.



   flags
       The flags 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 -).



       &lt;space&gt;         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 charac-
                       ter,  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 pad-
                       ding is performed. If the 0 and -  flags  both  appear,
                       the  0 flag is ignored. For d, i, o, u, x and X conver-
                       sions, if a precision  is  specified,  the  0  flag  is
                       ignored.  For other conversions, the behaviour is unde-
                       fined.



   Conversion Characters
       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 conversion characters 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
                       [-]dddd.  The x conversion uses the numbers and letters
                       0123456789abcdef and the X conversion uses the  numbers
                       and  letters  0123456789ABCDEF. The precision component
                       of the argument specifies the minimum number of  digits
                       to  appear.  If the value being converted can be repre-
                       sented 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 pre-
                       cision  of  0 is no characters. If both the field width
                       and precision are omitted, the implementation may  pre-
                       cede, 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 printf(3C) function in that they can be  surrounded
                       with  blank  characters. This was done so that, given a
                       format such as:


                       "%d\n",<foo>

                       the implementation could use a printf() call such as:


                       printf("%6d\n", foo);

                       and still conform. This notation is thus somewhat  like
                       scanf() in addition to printf().



       f               The  floating point number argument is written in deci-
                       mal notation in the style [-]ddd.ddd, where the  number
                       of  digits  after  the radix character (shown here as a
                       decimal point) is equal to the precision specification.
                       The  LC_NUMERIC  locale  category  determines the radix
                       character to use in this format. If  the  precision  is
                       omitted from the argument, six digits are written after
                       the radix character; if the precision is explicitly  0,
                       no radix character appears.



       e,E             The  floating  point  number argument is written in the
                       style [-]d.ddde+-dd (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 preci-
                       sion. The  LC_NUMERIC locale  category  determines  the
                       radix  character to use in this format. When the preci-
                       sion is missing, six  digits  are   written  after  the
                       radix  character; if the precision is 0, no radix char-
                       acter appears. The E conversion  character  produces  a
                       number  with  E  instead of e introducing the exponent.
                       The exponent always contains at least two digits.  How-
                       ever,  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 result-
                       ing 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 unsigned char
                       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  precision  specifica-
                       tion  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 field width cause trun-
       cation 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 field width should not be confused with the term  pre-
       cision used in the description of %s.

       One difference from the C function printf() is that the l and h conver-
       sion characters are not used. There is no differentiation between deci-
       mal values for type int, type  long, or type  short. The specifications
       %d or %i should be interpreted as an arbitrary length sequence of  dig-
       its.  Also,  no distinction is made between single precision and double
       precision numbers (float or double in C).  These are simply referred to
       as floating point numbers.

       Many of the output descriptions  use the term line, such as:

       "%s", <input line>


       Since  the  definition  of line includes the trailing newline character
       already, there is no need to include a \n in the format; a double  new-
       line character would otherwise result.

EXAMPLES
       Example  1: To represent the output of a program that prints a date and
       time in the form Sunday, July 3, 10:02, where &lt;weekday&gt; and &lt;month&gt; are
       strings:

       "%s,/\%s/\%d,/\%d:%.2d\n",<weekday>,<month>,<day>,<hour>,<min>


       Example 2: To show pi written to 5 decimal places:

       "pi/\=/\%.5f\n",<value of pi>


       Example  3: To show an input file format consisting of five colon-sepa-
       rated fields:

       "%s:%s:%s:%s:%s\n",<arg1>,<arg2>,<arg3>,<arg4>,<arg5>


SEE ALSO
       awk(1), printf(1), printf(3C), scanf(3C)



SunOS 5.10                        28 Mar 1995                       formats(5)