1PRINTF(1P)                 POSIX Programmer's Manual                PRINTF(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       printf - write formatted output
13

SYNOPSIS

15       printf format[argument...]
16

DESCRIPTION

18       The printf utility shall write formatted operands to the standard  out‐
19       put. The argument operands shall be formatted under control of the for‐
20       mat operand.
21

OPTIONS

23       None.
24

OPERANDS

26       The following operands shall be supported:
27
28       format A string describing the format to use to write the remaining op‐
29              erands.  See the EXTENDED DESCRIPTION section.
30
31       argument
32              The  strings to be written to standard output, under the control
33              of format. See the EXTENDED DESCRIPTION section.
34
35

STDIN

37       Not used.
38

INPUT FILES

40       None.
41

ENVIRONMENT VARIABLES

43       The following environment  variables  shall  affect  the  execution  of
44       printf:
45
46       LANG   Provide  a  default value for the internationalization variables
47              that are unset or null. (See  the  Base  Definitions  volume  of
48              IEEE Std 1003.1-2001,  Section  8.2,  Internationalization Vari‐
49              ables for the precedence of internationalization variables  used
50              to determine the values of locale categories.)
51
52       LC_ALL If  set  to a non-empty string value, override the values of all
53              the other internationalization variables.
54
55       LC_CTYPE
56              Determine the locale for  the  interpretation  of  sequences  of
57              bytes  of  text  data as characters (for example, single-byte as
58              opposed to multi-byte characters in arguments).
59
60       LC_MESSAGES
61              Determine the locale that should be used to  affect  the  format
62              and contents of diagnostic messages written to standard error.
63
64       LC_NUMERIC
65
66              Determine the locale for numeric formatting. It shall affect the
67              format of numbers written using the e, E, f, g, and G conversion
68              specifier characters (if supported).
69
70       NLSPATH
71              Determine the location of message catalogs for the processing of
72              LC_MESSAGES .
73
74

ASYNCHRONOUS EVENTS

76       Default.
77

STDOUT

79       See the EXTENDED DESCRIPTION section.
80

STDERR

82       The standard error shall be used only for diagnostic messages.
83

OUTPUT FILES

85       None.
86

EXTENDED DESCRIPTION

88       The format operand shall be used as the format string described in  the
89       Base Definitions volume of IEEE Std 1003.1-2001, Chapter 5, File Format
90       Notation with the following exceptions:
91
92        1. A <space> in the format string, in any context other than a flag of
93           a conversion specification, shall be treated as an ordinary charac‐
94           ter that is copied to the output.
95
96        2. A ' ' character in the format string shall be  treated  as  a  '  '
97           character, not as a <space>.
98
99        3. In  addition  to the escape sequences shown in the Base Definitions
100           volume of IEEE Std 1003.1-2001, Chapter 5, File Format  Notation  (
101           '\\', '\a', '\b', '\f', '\n', '\r', '\t', '\v' ), "\ddd", where ddd
102           is a one, two, or three-digit octal number, shall be written  as  a
103           byte with the numeric value specified by the octal number.
104
105        4. The implementation shall not precede or follow output from the d or
106           u conversion specifiers with <blank>s not specified by  the  format
107           operand.
108
109        5. The  implementation  shall not precede output from the o conversion
110           specifier with zeros not specified by the format operand.
111
112        6. The e, E, f, g, and G conversion specifiers need not be supported.
113
114        7. An additional conversion specifier character, b, shall be supported
115           as  follows.  The  argument  shall be taken to be a string that may
116           contain backslash-escape sequences. The following  backslash-escape
117           sequences shall be supported:
118
119            * The  escape  sequences  listed in the Base Definitions volume of
120              IEEE Std 1003.1-2001, Chapter 5, File Format  Notation  (  '\\',
121              '\a',  '\b', '\f', '\n', '\r', '\t', '\v' ), which shall be con‐
122              verted to the characters they represent
123
124            * "\0ddd", where ddd is a zero, one,  two,  or  three-digit  octal
125              number  that shall be converted to a byte with the numeric value
126              specified by the octal number
127
128            * sequence '\c' which shall not be written and shall cause  printf
129              to  ignore  any  remaining characters in the string operand con‐
130              taining it, any remaining string operands,  and  any  additional
131              characters in the format operand
132
133       The  interpretation  of  a  backslash followed by any other sequence of
134       characters is unspecified.
135
136       Bytes from the converted string shall be written until the end  of  the
137       string  or the number of bytes indicated by the precision specification
138       is reached. If the precision is omitted, it shall be taken to be  infi‐
139       nite, so all bytes up to the end of the converted string shall be writ‐
140       ten.
141
142        8. For each conversion specification that consumes  an  argument,  the
143           next  argument  operand  shall  be  evaluated  and converted to the
144           appropriate type for the conversion as specified below.
145
146        9. The format operand shall be reused as often as necessary to satisfy
147           the argument operands. Any extra c or s conversion specifiers shall
148           be evaluated as if a null  string  argument  were  supplied;  other
149           extra  conversion  specifications  shall  be evaluated as if a zero
150           argument were supplied.  If the format operand contains no  conver‐
151           sion  specifications and argument operands are present, the results
152           are unspecified.
153
154       10. If a character sequence in the format operand  begins  with  a  '%'
155           character,  but does not form a valid conversion specification, the
156           behavior is unspecified.
157
158       The argument operands shall be treated as strings if the  corresponding
159       conversion  specifier  is b, c, or s ; otherwise, it shall be evaluated
160       as a C constant, as described by the ISO C standard, with the following
161       extensions:
162
163        * A leading plus or minus sign shall be allowed.
164
165        * If  the  leading  character  is  a single-quote or double-quote, the
166          value shall be the numeric value in the underlying  codeset  of  the
167          character following the single-quote or double-quote.
168
169       If  an argument operand cannot be completely converted into an internal
170       value appropriate to  the  corresponding  conversion  specification,  a
171       diagnostic  message  shall be written to standard error and the utility
172       shall not exit with a zero exit status, but shall  continue  processing
173       any  remaining  operands  and  shall write the value accumulated at the
174       time the error was detected to standard output.
175
176       It is not considered an error if an argument operand is not  completely
177       used  for  a c or s conversion or if a string operand's first or second
178       character is used to get the numeric value of a character.
179

EXIT STATUS

181       The following exit values shall be returned:
182
183        0     Successful completion.
184
185       >0     An error occurred.
186
187

CONSEQUENCES OF ERRORS

189       Default.
190
191       The following sections are informative.
192

APPLICATION USAGE

194       The floating-point formatting conversion specifications of printf() are
195       not required because all arithmetic in the shell is integer arithmetic.
196       The awk utility performs floating-point calculations and  provides  its
197       own  printf  function.  The  bc utility can perform arbitrary-precision
198       floating-point arithmetic, but does not  provide  extensive  formatting
199       capabilities.  (This  printf utility cannot really be used to format bc
200       output; it does not support arbitrary precision.)  Implementations  are
201       encouraged to support the floating-point conversions as an extension.
202
203       Note  that  this  printf utility, like the printf() function defined in
204       the System Interfaces volume of IEEE Std 1003.1-2001  on  which  it  is
205       based,  makes  no special provision for dealing with multi-byte charac‐
206       ters when using the %c conversion specification or when a precision  is
207       specified  in  a %b or %s conversion specification. Applications should
208       be extremely cautious using either of these  features  when  there  are
209       multi-byte characters in the character set.
210
211       No  provision  is  made  in  this  volume of IEEE Std 1003.1-2001 which
212       allows field widths and precisions to be specified as '*' since the '*'
213       can  be  replaced  directly  in the format operand using shell variable
214       substitution.  Implementations can also  provide  this  feature  as  an
215       extension if they so choose.
216
217       Hexadecimal  character  constants  as defined in the ISO C standard are
218       not recognized in the format operand because there is no consistent way
219       to  detect  the end of the constant. Octal character constants are lim‐
220       ited to, at most, three octal digits, but  hexadecimal  character  con‐
221       stants  are  only terminated by a non-hex-digit character. In the ISO C
222       standard, the "##" concatenation operator can be used  to  terminate  a
223       constant  and follow it with a hexadecimal character to be written.  In
224       the shell, concatenation occurs before the printf utility has a  chance
225       to parse the end of the hexadecimal constant.
226
227       The  %b  conversion specification is not part of the ISO C standard; it
228       has been added here as a portable  way  to  process  backslash  escapes
229       expanded  in string operands as provided by the echo utility.  See also
230       the APPLICATION USAGE section of echo for  ways  to  use  printf  as  a
231       replacement for all of the traditional versions of the echo utility.
232
233       If an argument cannot be parsed correctly for the corresponding conver‐
234       sion specification, the printf utility is required to report an  error.
235       Thus,  overflow  and  extraneous  characters  at the end of an argument
236       being used for a numeric conversion shall be reported as errors.
237

EXAMPLES

239       To alert the user and then print and read a series of prompts:
240
241
242              printf "\aPlease fill in the following: \nName: "
243              read name
244              printf "Phone number: "
245              read phone
246
247       To read out a list of right and wrong answers from  a  file,  calculate
248       the  percentage  correctly,  and print them out. The numbers are right-
249       justified and separated by a single <tab>. The percentage is written to
250       one decimal place of accuracy:
251
252
253              while read right wrong ; do
254                  percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc)
255                  printf "%2d right\t%2d wrong\t(%s%%)\n" \
256                      $right $wrong $percent
257              done < database_file
258       The command:
259
260
261              printf "%5d%4d\n" 1 21 321 4321 54321
262
263       produces:
264
265
266                 1  21
267                3214321
268              54321   0
269
270       Note  that  the  format operand is used three times to print all of the
271       given strings and that a '0' was supplied by printf to satisfy the last
272       %4d conversion specification.
273
274       The  printf  utility  is  required  to  notify the user when conversion
275       errors are detected while producing numeric output; thus, the following
276       results would be expected on an implementation with 32-bit twos-comple‐
277       ment integers when %d is specified as the format operand:
278
279                      Standard
280          Argument    Output      Diagnostic Output
281          5a          5           printf: "5a" not completely converted
282          9999999999  2147483647  printf: "9999999999" arithmetic overflow
283          -9999999999 -2147483648 printf: "-9999999999" arithmetic overflow
284          ABC         0           printf: "ABC" expected numeric value
285
286       The diagnostic message format is not specified, but these examples con‐
287       vey  the  type  of  information  that should be reported. Note that the
288       value shown on standard output is what would be expected as the  return
289       value  from  the  strtol() function as defined in the System Interfaces
290       volume of IEEE Std 1003.1-2001. A similar correspondence exists between
291       %u  and  strtoul()  and  %e, %f, and %g (if the implementation supports
292       floating-point conversions) and strtod().
293
294       In a locale using the ISO/IEC 646:1991 standard as the underlying code‐
295       set, the command:
296
297
298              printf "%d\n" 3 +3 -3 \'3 \"+3 "'-3"
299
300       produces:
301
302       3      Numeric value of constant 3
303
304       3      Numeric value of constant 3
305
306       -3     Numeric value of constant -3
307
308       51     Numeric value of the character '3' in the ISO/IEC 646:1991 stan‐
309              dard codeset
310
311       43     Numeric value of the character '+' in the ISO/IEC 646:1991 stan‐
312              dard codeset
313
314       45     Numeric value of the character '-' in the ISO/IEC 646:1991 stan‐
315              dard codeset
316
317
318       Note that in a locale with multi-byte characters, the value of a  char‐
319       acter is intended to be the value of the equivalent of the wchar_t rep‐
320       resentation of the character as described in the System Interfaces vol‐
321       ume of IEEE Std 1003.1-2001.
322

RATIONALE

324       The printf utility was added to provide functionality that has histori‐
325       cally been provided by echo. However, due to irreconcilable differences
326       in  the  various  versions  of echo extant, the version has few special
327       features, leaving those to this new printf utility, which is  based  on
328       one in the Ninth Edition system.
329
330       The  EXTENDED  DESCRIPTION  section almost exactly matches the printf()
331       function in the ISO C standard, although it is described  in  terms  of
332       the   file   format   notation   in  the  Base  Definitions  volume  of
333       IEEE Std 1003.1-2001, Chapter 5, File Format Notation.
334

FUTURE DIRECTIONS

336       None.
337

SEE ALSO

339       awk, bc, echo, the System Interfaces  volume  of  IEEE Std 1003.1-2001,
340       printf()
341
343       Portions  of  this text are reprinted and reproduced in electronic form
344       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
345       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
346       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
347       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
348       event of any discrepancy between this version and the original IEEE and
349       The  Open Group Standard, the original IEEE and The Open Group Standard
350       is the referee document. The original Standard can be  obtained  online
351       at http://www.opengroup.org/unix/online.html .
352
353
354
355IEEE/The Open Group                  2003                           PRINTF(1P)
Impressum