printf(P)                                             printf(P)





NAME
       printf - write formatted output

SYNOPSIS
       printf format[argument...]

DESCRIPTION
       The printf utility shall write formatted operands to the
       standard output. The argument operands shall be  format-
       ted under control of the format operand.

OPTIONS
       None.

OPERANDS
       The following operands shall be supported:

       format A  string  describing  the format to use to write
              the  remaining  operands.    See   the   EXTENDED
              DESCRIPTION section.

       argument
              The  strings  to  be  written to standard output,
              under the control of  format.  See  the  EXTENDED
              DESCRIPTION section.


STDIN
       Not used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The  following  environment  variables  shall affect the
       execution of printf:

       LANG   Provide a default value for the internationaliza-
              tion  variables  that are unset or null. (See the
              Base Definitions volume of  IEEE Std 1003.1-2001,
              Section  8.2,  Internationalization Variables for
              the precedence of internationalization  variables
              used  to  determine  the  values  of locale cate-
              gories.)

       LC_ALL If set to a non-empty string value, override  the
              values  of  all  the  other  internationalization
              variables.

       LC_CTYPE
              Determine the locale for  the  interpretation  of
              sequences  of  bytes  of  text data as characters
              (for example, single-byte as  opposed  to  multi-
              byte characters in arguments).

       LC_MESSAGES
              Determine  the  locale  that  should  be  used to
              affect the format and contents of diagnostic mes-
              sages written to standard error.

       LC_NUMERIC

              Determine  the  locale for numeric formatting. It
              shall affect the format of numbers written  using
              the  e  ,  E , f , g , and G conversion specifier
              characters (if supported).

       NLSPATH
              Determine the location of  message  catalogs  for
              the processing of LC_MESSAGES .


ASYNCHRONOUS EVENTS
       Default.

STDOUT
       See the EXTENDED DESCRIPTION section.

STDERR
       The  standard  error  shall  be used only for diagnostic
       messages.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       The format operand shall be used as  the  format  string
       described    in   the   Base   Definitions   volume   of
       IEEE Std 1003.1-2001, Chapter 5,  File  Format  Notation
       with the following exceptions:

       A  <space>  in  the  format string, in any context other
       than a flag of  a  conversion  specification,  shall  be
       treated  as  an ordinary character that is copied to the
       output.

       A '' character in the format string shall be treated  as
       a '' character, not as a <space>.

       In  addition  to  the escape sequences shown in the Base
       Definitions volume of IEEE Std 1003.1-2001,  Chapter  5,
       File  Format Notation ( '\\' , '\a' , '\b' , '\f' , '\n'
       , '\r' , '\t' , '\v' ), "\ddd" , where  ddd  is  a  one,
       two,  or three-digit octal number, shall be written as a
       byte with the numeric value specified by the octal  num-
       ber.

       The  implementation  shall  not precede or follow output
       from the d or u conversion specifiers with <blank>s  not
       specified by the format operand.

       The  implementation  shall not precede output from the o
       conversion specifier with zeros  not  specified  by  the
       format operand.

       The e , E , f , g , and G conversion specifiers need not
       be supported.

       An additional conversion specifier character, b ,  shall
       be  supported as follows. The argument shall be taken to
       be a string that may contain backslash-escape sequences.
       The  following  backslash-escape sequences shall be sup-
       ported:

              The escape sequences listed in the  Base  Defini-
              tions  volume of IEEE Std 1003.1-2001, Chapter 5,
              File Format Notation ( '\\' , '\a' , '\b' ,  '\f'
              ,  '\n'  ,  '\r'  , '\t' , '\v' ), which shall be
              converted to the characters they represent

              "\0ddd" , where ddd  is  a  zero,  one,  two,  or
              three-digit  octal number that shall be converted
              to a byte with the numeric value specified by the
              octal number

              '\c' , which shall not be written and shall cause
              printf to ignore any remaining characters in  the
              string   operand  containing  it,  any  remaining
              string operands, and any additional characters in
              the format operand

       The  interpretation of a backslash followed by any other
       sequence of characters is unspecified.

       Bytes from the converted string shall be  written  until
       the  end  of the string or the number of bytes indicated
       by the precision specification is reached. If the preci-
       sion  is  omitted,  it shall be taken to be infinite, so
       all bytes up to the end of the converted string shall be
       written.

       For each conversion specification that consumes an argu-
       ment, the next argument operand shall be  evaluated  and
       converted  to the appropriate type for the conversion as
       specified below.

       The format operand shall be reused as often as necessary
       to  satisfy the argument operands. Any extra c or s con-
       version specifiers shall  be  evaluated  as  if  a  null
       string  argument  were  supplied; other extra conversion
       specifications shall be evaluated as if a zero  argument
       were  supplied.   If the format operand contains no con-
       version  specifications  and   argument   operands   are
       present, the results are unspecified.

       If  a  character  sequence  in the format operand begins
       with a '%' character, but does not form a valid  conver-
       sion specification, the behavior is unspecified.

       The argument operands shall be treated as strings if the
       corresponding conversion specifier is b , c  ,  or  s  ;
       otherwise,  it  shall  be  evaluated as a C constant, as
       described by the  ISO C  standard,  with  the  following
       extensions:

              A leading plus or minus sign shall be allowed.

              If  the  leading  character  is a single-quote or
              double-quote, the  value  shall  be  the  numeric
              value  in the underlying codeset of the character
              following the single-quote or double-quote.

       If an argument operand cannot  be  completely  converted
       into  an internal value appropriate to the corresponding
       conversion specification, a diagnostic message shall  be
       written to standard error and the utility shall not exit
       with a zero exit status, but shall  continue  processing
       any remaining operands and shall write the value accumu-
       lated at the time the error  was  detected  to  standard
       output.

       It  is not considered an error if an argument operand is
       not completely used for a c or  s  conversion  or  if  a
       string  operand's  first  or second character is used to
       get the numeric value of a character.

EXIT STATUS
       The following exit values shall be returned:

        0     Successful completion.

       >0     An error occurred.


CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       The floating-point formatting conversion  specifications
       of  printf()  are not required because all arithmetic in
       the shell is integer arithmetic.  The awk  utility  per-
       forms  floating-point  calculations and provides its own
       printf function. The bc utility can  perform  arbitrary-
       precision  floating-point  arithmetic, but does not pro-
       vide extensive  formatting  capabilities.  (This  printf
       utility  cannot  really  be used to format bc output; it
       does not support arbitrary  precision.)  Implementations
       are encouraged to support the floating-point conversions
       as an extension.

       Note that this printf utility, like the  printf()  func-
       tion   defined   in  the  System  Interfaces  volume  of
       IEEE Std 1003.1-2001 on which it is based, makes no spe-
       cial  provision  for  dealing with multi-byte characters
       when using the %c conversion  specification  or  when  a
       precision is specified in a %b or %s conversion specifi-
       cation. Applications should be extremely cautious  using
       either of these features when there are multi-byte char-
       acters in the character set.

       No   provision   is   made    in    this    volume    of
       IEEE Std 1003.1-2001  which allows field widths and pre-
       cisions to be specified as '*'  since  the  '*'  can  be
       replaced  directly  in  the  format  operand using shell
       variable substitution.  Implementations can also provide
       this feature as an extension if they so choose.

       Hexadecimal  character constants as defined in the ISO C
       standard  are  not  recognized  in  the  format  operand
       because  there is no consistent way to detect the end of
       the constant. Octal character constants are limited  to,
       at  most,  three octal digits, but hexadecimal character
       constants are only terminated by a non-hex-digit charac-
       ter. In the ISO C standard, the "##" concatenation oper-
       ator can be used to terminate a constant and  follow  it
       with  a  hexadecimal  character  to  be written.  In the
       shell, concatenation occurs before  the  printf  utility
       has  a  chance  to parse the end of the hexadecimal con-
       stant.

       The %b 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 echo utility.  See also the APPLICATION
       USAGE section of echo  for  ways  to  use  printf  as  a
       replacement  for  all of the traditional versions of the
       echo utility.

       If an argument cannot be parsed correctly for the corre-
       sponding conversion specification, the printf utility is
       required to report an error. Thus, overflow and extrane-
       ous  characters at the end of an argument being used for
       a numeric conversion shall be reported as errors.

EXAMPLES
       To alert the user and then print and read  a  series  of
       prompts:


              printf "\aPlease fill in the following: \nName: "
              read name
              printf "Phone number: "
              read phone

       To  read  out  a  list of right and wrong answers from a
       file, calculate the percentage correctly, and print them
       out.  The numbers are right-justified and separated by a
       single <tab>. The percentage is written to  one  decimal
       place of accuracy:


              while read right wrong ; do
                  percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc)
                  printf "%2d right\t%2d wrong\t(%s%%)\n" \
                      $right $wrong $percent
              done < database_file
       The command:


              printf "%5d%4d\n" 1 21 321 4321 54321

       produces:


                 1  21
                3214321
              54321   0

       Note  that  the  format  operand  is used three times to
       print all of the given strings and that a '0'  was  sup-
       plied by printf to satisfy the last %4d conversion spec-
       ification.

       The printf utility is required to notify the  user  when
       conversion  errors  are detected while producing numeric
       output; thus, the following results would be expected on
       an  implementation  with 32-bit twos-complement integers
       when %d is specified as the format operand:
                Standard
Argument        Output          Diagnostic Output
5a              5               printf: "5a" not completely converted
9999999999      2147483647      printf: "9999999999" arithmetic overflow
-9999999999     -2147483648     printf: "-9999999999" arithmetic overflow
ABC             0               printf: "ABC" expected numeric value

       The diagnostic message  format  is  not  specified,  but
       these  examples  convey  the  type  of  information that
       should be reported. Note that the value shown  on  stan-
       dard  output  is  what  would  be expected as the return
       value from the strtol() function as defined in the  Sys-
       tem Interfaces volume of IEEE Std 1003.1-2001. A similar
       correspondence exists between %u and strtoul() and %e  ,
       %f  ,  and  %g (if the implementation supports floating-
       point conversions) and strtod().

       In a locale using the ISO/IEC 646:1991 standard  as  the
       underlying codeset, the command:


              printf "%d\n" 3 +3 -3 \'3 \"+3 "'-3"

       produces:

       3      Numeric value of constant 3

       3      Numeric value of constant 3

       -3     Numeric value of constant -3

       51     Numeric   value  of  the  character  '3'  in  the
              ISO/IEC 646:1991 standard codeset

       43     Numeric  value  of  the  character  '+'  in   the
              ISO/IEC 646:1991 standard codeset

       45     Numeric   value  of  the  character  '-'  in  the
              ISO/IEC 646:1991 standard codeset


       Note that in a locale with  multi-byte  characters,  the
       value  of a character is intended to be the value of the
       equivalent of the wchar_t representation of the  charac-
       ter  as  described  in  the  System Interfaces volume of
       IEEE Std 1003.1-2001.

RATIONALE
       The printf utility was added  to  provide  functionality
       that  has  historically  been provided by echo. However,
       due to irreconcilable differences in  the  various  ver-
       sions  of  echo extant, the version has few special fea-
       tures, leaving those to this new printf  utility,  which
       is based on one in the Ninth Edition system.

       The  EXTENDED DESCRIPTION section almost exactly matches
       the printf() function in the ISO C standard, although it
       is described in terms of the file format notation in the
       Base Definitions volume of IEEE Std 1003.1-2001, Chapter
       5, File Format Notation.

FUTURE DIRECTIONS
       None.

SEE ALSO
       awk  ,  bc  ,  echo  ,  the  System Interfaces volume of
       IEEE Std 1003.1-2001, printf()

COPYRIGHT
       Portions of this text are reprinted  and  reproduced  in
       electronic  form  from  IEEE  Std  1003.1, 2003 Edition,
       Standard for Information Technology -- Portable  Operat-
       ing System Interface (POSIX), The Open Group Base Speci-
       fications Issue 6, Copyright (C) 2001-2003 by the Insti-
       tute  of  Electrical  and Electronics Engineers, Inc and
       The Open Group. In the event of any discrepancy  between
       this  version  and  the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group  Standard
       is  the  referee  document. The original Standard can be
       obtained        online        at        http://www.open-
       group.org/unix/online.html .



POSIX                         2003                    printf(P)
