unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



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 other-
     wise  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 specifications
           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 char-
           acters.

     /\    Exactly one space character.

     The notation for spaces allows some flexibility for applica-
     tion output. Note that an empty character position in format
     represents one or more blank characters on the  output  (not
     white  space,  which can include newline characters). There-
     fore, 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.





SunOS 5.9           Last change: 28 Mar 1995                    1






Standards, Environments, and Macros                    formats(5)



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

       Sequence        Character      Terminal Action
          \\        backslash         None.
          \a        alert             Attempts  to  alert  the   user
                                      through   audible   or  visible
                                      notification.
          \b        backspace         Moves the printing position  to
                                      one  column  before the current
                                      position,  unless  the  current
                                      position  is  the  start  of  a
                                      line.
          \f        form-feed         Moves the printing position  to
                                      the  initial  printing position
                                      of the next logical page.
          \n        newline           Moves the printing position  to
                                      the start of the next line.
          \r        carriage-return   Moves the printing position  to
                                      the start of the current line.
          \t        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  unde-
                                      fined.
          \v        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.


  Conversion Specifications
     Each conversion specification is introduced by the  percent-
     sign  character  (%).  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 con-
           verted 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



SunOS 5.9           Last change: 28 Mar 1995                    2






Standards, Environments, and Macros                    formats(5)



           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 writ-
           ten 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 indicates  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 -).

     <space>
           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  preci-
           sion  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 charac-
           ter. 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.

  Conversion Characters
     Each conversion character results in fetching zero  or  more
     arguments.   The   results   are   undefined  if  there  are



SunOS 5.9           Last change: 28 Mar 1995                    3






Standards, Environments, and Macros                    formats(5)



     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
           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 fol-
           low  numeric  arguments of types d, i and u with blank
           characters; arguments of type o (octal)  may  be  pre-
           ceded 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
           decimal  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 specifi-
           cation. The LC_NUMERIC locale category determines  the
           radix  character  to use in this format. If the preci-
           sion is omitted from  the  argument,  six  digits  are
           written after the radix character; if the precision is
           explicitly 0, no radix character appears.




SunOS 5.9           Last change: 28 Mar 1995                    4






Standards, Environments, and Macros                    formats(5)



     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 pre-
           cision. 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
           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 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 specif-
           ication  of the argument is reached.  If the precision
           is omitted from the argument, it is taken to be infin-
           ite,  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  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 field width
     should not be confused with the term precision used  in  the
     description of %s.

     One difference from the C function printf() is  that  the  l
     and  h  conversion characters are not used. There is no dif-
     ferentiation between  decimal  values  for  type  int,  type
     long,  or type  short. 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



SunOS 5.9           Last change: 28 Mar 1995                    5






Standards, Environments, and Macros                    formats(5)



     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 newline 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
     <weekday> and <month> 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-separated fields:

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

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


























SunOS 5.9           Last change: 28 Mar 1995                    6