PRINTF(1P) - phpMan

PRINTF(1P)                 POSIX Programmer's Manual                PRINTF(1P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
NAME
       printf - write formatted output
SYNOPSIS
       printf format[argument...]
DESCRIPTION
       The printf utility shall write formatted operands to the standard  out-
       put. The argument operands shall be formatted under control of the for-
       mat operand.
OPTIONS
       None.
OPERANDS
       The following operands shall be supported:
       format A string describing the format to use to write the remaining op-
              erands.  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 internationalization variables
              that are unset or null. (See  the  Base  Definitions  volume  of
              IEEE Std 1003.1-2001,  Section  8.2,  Internationalization Vari-
              ables for the precedence of internationalization variables  used
              to determine the values of locale categories.)
       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 messages 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:
        1. A <space> in the format string, in any context other than a flag of
           a conversion specification, shall be treated as an ordinary charac-
           ter that is copied to the output.
        2. A ' ' character in the format string shall be  treated  as  a  '  '
           character, not as a <space>.
        3. 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 number.
        4. The implementation shall not precede or follow output from the d or
           u conversion specifiers with <blank>s not specified by  the  format
           operand.
        5. The  implementation  shall not precede output from the o conversion
           specifier with zeros not specified by the format operand.
        6. The e, E, f, g, and G conversion specifiers need not be supported.
        7. 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 supported:
            * The  escape  sequences  listed in the Base Definitions volume of
              IEEE Std 1003.1-2001, Chapter 5, File Format  Notation  (  '\\',
              '\a',  '\b', '\f', '\n', '\r', '\t', '\v' ), which shall be con-
              verted 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
            * sequence '\c' which shall not be written and shall cause  printf
              to  ignore  any  remaining characters in the string operand con-
              taining 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 precision is omitted, it shall be taken to be  infi-
       nite, so all bytes up to the end of the converted string shall be writ-
       ten.
        8. For each conversion specification that consumes  an  argument,  the
           next  argument  operand  shall  be  evaluated  and converted to the
           appropriate type for the conversion as specified below.
        9. The format operand shall be reused as often as necessary to satisfy
           the argument operands. Any extra c or s conversion 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  conver-
           sion  specifications and argument operands are present, the results
           are unspecified.
       10. If a character sequence in the format operand  begins  with  a  '%'
           character,  but does not form a valid conversion 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 accumulated 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 performs floating-point calculations and  provides  its
       own  printf  function.  The  bc utility can perform arbitrary-precision
       floating-point arithmetic, but does not  provide  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() function defined in
       the System Interfaces volume of IEEE Std 1003.1-2001  on  which  it  is
       based,  makes  no special provision for dealing with multi-byte charac-
       ters when using the %c conversion specification or when a precision  is
       specified  in  a %b or %s conversion specification. Applications should
       be extremely cautious using either of these  features  when  there  are
       multi-byte characters in the character set.
       No  provision  is  made  in  this  volume of IEEE Std 1003.1-2001 which
       allows field widths and precisions 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 lim-
       ited to, at most, three octal digits, but  hexadecimal  character  con-
       stants  are  only terminated by a non-hex-digit character. In the ISO C
       standard, the "##" concatenation operator 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 constant.
       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 corresponding conver-
       sion specification, the printf utility is required to report an  error.
       Thus,  overflow  and  extraneous  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 supplied by printf to satisfy the last
       %4d conversion specification.
       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-comple-
       ment 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 con-
       vey  the  type  of  information  that should be reported. Note that the
       value shown on standard output is what would be expected as the  return
       value  from  the  strtol() function as defined in the System 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 code-
       set, 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 stan-
              dard codeset
       43     Numeric value of the character '+' in the ISO/IEC 646:1991 stan-
              dard codeset
       45     Numeric value of the character '-' in the ISO/IEC 646:1991 stan-
              dard codeset

       Note that in a locale with multi-byte characters, the value of a  char-
       acter is intended to be the value of the equivalent of the wchar_t rep-
       resentation of the character as described in the System Interfaces vol-
       ume of IEEE Std 1003.1-2001.
RATIONALE
       The printf utility was added to provide functionality that has histori-
       cally been provided by echo. However, due to irreconcilable differences
       in  the  various  versions  of echo extant, the version has few special
       features, 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  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  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.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                           PRINTF(1P)