1mNAME0m
       format - Format a string in the style of sprintf

1mSYNOPSIS0m
       1mformat 4m22mformatString24m ?4marg24m 4marg24m 4m...24m?


1mINTRODUCTION0m
       This command generates a formatted string in the same way as the ANSI C
       1msprintf 22mprocedure (it uses 1msprintf  22min  its  implementation).   4mFormat-0m
       4mString24m  indicates  how  to format the result, using 1m% 22mconversion speci-
       fiers as in 1msprintf22m, and the additional arguments, if any, provide val-
       ues to be substituted into the result.  The return value from 1mformat 22mis
       the formatted string.


1mDETAILS ON FORMATTING0m
       The command operates by scanning 4mformatString24m from left to right.  Each
       character  from  the  format  string  is  appended to the result string
       unless it is a percent sign.  If the character is a 1m% 22mthen  it  is  not
       copied  to  the result string.  Instead, the characters following the 1m%0m
       character are treated as a conversion specifier.  The conversion speci-
       fier controls the conversion of the next successive 4marg24m to a particular
       format and the result is appended to the result string in place of  the
       conversion  specifier.   If there are multiple conversion specifiers in
       the format string, then each one controls the conversion of  one  addi-
       tional  4marg24m.   The 1mformat 22mcommand must be given enough 4marg24ms to meet the
       needs of all of the conversion specifiers in 4mformatString24m.

       Each conversion specifier may contain up to  six  different  parts:  an
       XPG3  position specifier, a set of flags, a minimum field width, a pre-
       cision, a length modifier, and a conversion character.   Any  of  these
       fields  may be omitted except for the conversion character.  The fields
       that are present must appear in the order given above.  The  paragraphs
       below discuss each of these fields in turn.

       If  the 1m% 22mis followed by a decimal number and a 1m$22m, as in ``1m%2$d22m'', then
       the value to convert is not taken from the  next  sequential  argument.
       Instead, it is taken from the argument indicated by the number, where 1
       corresponds to the first 4marg24m.  If  the  conversion  specifier  requires
       multiple  arguments  because of 1m* 22mcharacters in the specifier then suc-
       cessive arguments are used, starting with the  argument  given  by  the
       number.   This  follows the XPG3 conventions for positional specifiers.
       If there are any positional specifiers in 4mformatString24m then all of  the
       specifiers must be positional.

       The  second  portion  of  a conversion specifier may contain any of the
       following flag characters, in any order:

       1m-         22mSpecifies that the converted argument should  be  left-justi-
                 fied  in its field (numbers are normally right-justified with
                 leading spaces if needed).

       1m+         22mSpecifies that a number should always be printed with a sign,
                 even if positive.

       4mspace24m     Specifies  that  a  space should be added to the beginning of
                 the number if the first character isn't a sign.

       1m0         22mSpecifies that the number should be padded on the  left  with
                 zeroes instead of spaces.

       1m#         22mRequests an alternate output form. For 1mo 22mand 1mO 22mconversions it
                 guarantees that the first digit is always 1m022m.  For 1mx 22mor 1mX 22mcon-
                 versions, 1m0x 22mor 1m0X 22m(respectively) will be added to the begin-
                 ning of the result unless it is zero.  For all floating-point
                 conversions (1me22m, 1mE22m, 1mf22m, 1mg22m, and 1mG22m) it guarantees that the result
                 always has a decimal point.  For 1mg 22mand 1mG 22mconversions it spec-
                 ifies that trailing zeroes should not be removed.

       The  third portion of a conversion specifier is a number giving a mini-
       mum field width for this conversion.  It  is  typically  used  to  make
       columns  line  up in tabular printouts.  If the converted argument con-
       tains fewer characters than the minimum field width  then  it  will  be
       padded  so that it is as wide as the minimum field width.  Padding nor-
       mally occurs by adding extra spaces on the left of the converted  argu-
       ment,  but the 1m0 22mand 1m- 22mflags may be used to specify padding with zeroes
       on the left or with spaces on the right, respectively.  If the  minimum
       field width is specified as 1m* 22mrather than a number, then the next argu-
       ment to the 1mformat 22mcommand determines the minimum field width; it  must
       be a numeric string.

       The fourth portion of a conversion specifier is a precision, which con-
       sists of a period followed by a number.  The number is used in  differ-
       ent  ways  for  different  conversions.  For 1me22m, 1mE22m, and 1mf 22mconversions it
       specifies the number of digits to appear to the right  of  the  decimal
       point.  For 1mg 22mand 1mG 22mconversions it specifies the total number of digits
       to appear, including those on both sides of the decimal point (however,
       trailing  zeroes  after  the decimal point will still be omitted unless
       the 1m# 22mflag has been specified).  For integer conversions, it  specifies
       a  minimum  number  of digits to print (leading zeroes will be added if
       necessary).  For 1ms 22mconversions it specifies the maximum number of char-
       acters to be printed; if the string is longer than this then the trail-
       ing characters will be dropped.  If the precision is specified  with  1m*0m
       rather  than  a  number  then  the  next argument to the 1mformat 22mcommand
       determines the precision; it must be a numeric string.

       The fifth part of a conversion specifier is a  length  modifier,  which
       must  be 1mh 22mor 1ml22m.  If it is 1mh 22mit specifies that the numeric value should
       be truncated to a 16-bit  value  before  converting.   This  option  is
       rarely useful.  The 1ml 22mmodifier is ignored.

       The  last  thing  in  a conversion specifier is an alphabetic character
       that determines what kind of conversion to perform.  The following con-
       version characters are currently supported:

       1md         22mConvert integer to signed decimal string.

       1mu         22mConvert integer to unsigned decimal string.

       1mi         22mConvert  integer  to  signed decimal string;  the integer may
                 either be in decimal, in octal (with a leading 1m022m) or in  hex-
                 adecimal (with a leading 1m0x22m).

       1mo         22mConvert integer to unsigned octal string.

       1mx 22mor 1mX    22mConvert  integer to unsigned hexadecimal string, using digits
                 ``0123456789abcdef'' for 1mx 22mand ``0123456789ABCDEF'' for 1mX22m).

       1mc         22mConvert integer to the Unicode character it represents.

       1ms         22mNo conversion; just insert string.

       1mf         22mConvert floating-point number to signed decimal string of the
                 form  4mxx.yyy24m,  where  the  number of 4my24m's is determined by the
                 precision (default: 6).  If the precision is 0 then no  deci-
                 mal point is output.

       1me 22mor 1me    22mConvert  floating-point  number to scientific notation in the
                 form 4mx.yyy24m1me+-4m22mzz24m, where the number of 4my24m's is determined by the
                 precision  (default: 6).  If the precision is 0 then no deci-
                 mal point is output.  If the 1mE 22mform is used then 1mE 22mis printed
                 instead of 1me22m.

       1mg 22mor 1mG    22mIf  the  exponent is less than -4 or greater than or equal to
                 the precision, then convert floating-point number as  for  1m%e0m
                 or  1m%E22m.   Otherwise convert as for 1m%f22m.  Trailing zeroes and a
                 trailing decimal point are omitted.

       1m%         22mNo conversion: just insert 1m%22m.

       For the numerical conversions the argument being converted must  be  an
       integer  or  floating-point  string;  format  converts  the argument to
       binary and then converts it back to a string according to  the  conver-
       sion specifier.


1mDIFFERENCES FROM ANSI SPRINTF0m
       The  behavior  of  the format command is the same as the ANSI C 1msprintf0m
       procedure except for the following differences:

       [1]    1m%p 22mand 1m%n 22mspecifiers are not currently supported.

       [2]    For 1m%c 22mconversions the argument must be a decimal string,  which
              will then be converted to the corresponding character value.

       [3]    The  1ml 22mmodifier is ignored;  integer values are always converted
              as if there were no modifier present and real values are  always
              converted as if the 1ml 22mmodifier were present (i.e. type 1mdouble 22mis
              used for the internal representation).  If  the  1mh  22mmodifier  is
              specified then integer values are truncated to 1mshort 22mbefore con-
              version.


1mSEE ALSO0m
       sprintf(3), string(n)


1mKEYWORDS0m
