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
29                 operands.  See the EXTENDED DESCRIPTION section.
30
31       argument  The  strings to be written to standard output, under the con‐
32                 trol of format.  See the EXTENDED DESCRIPTION section.
33

STDIN

35       Not used.
36

INPUT FILES

38       None.
39

ENVIRONMENT VARIABLES

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

ASYNCHRONOUS EVENTS

71       Default.
72

STDOUT

74       See the EXTENDED DESCRIPTION section.
75

STDERR

77       The standard error shall be used only for diagnostic messages.
78

OUTPUT FILES

80       None.
81

EXTENDED DESCRIPTION

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

EXIT STATUS

186       The following exit values shall be returned:
187
188        0    Successful completion.
189
190       >0    An error occurred.
191

CONSEQUENCES OF ERRORS

193       Default.
194
195       The following sections are informative.
196

APPLICATION USAGE

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

EXAMPLES

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

RATIONALE

330       The printf utility was added to provide functionality that has histori‐
331       cally  been  provided  by echo.  However, due to irreconcilable differ‐
332       ences in the various versions of echo extant, the version has few  spe‐
333       cial features, leaving those to this new printf utility, which is based
334       on one in the Ninth Edition system.
335
336       The EXTENDED DESCRIPTION section almost exactly  matches  the  printf()
337       function  in  the  ISO C standard, although it is described in terms of
338       the  file  format  notation  in  the   Base   Definitions   volume   of
339       POSIX.1‐2017, Chapter 5, File Format Notation.
340
341       Earlier versions of this standard specified that arguments for all con‐
342       versions other than b, c, and s were evaluated in the same  way  (as  C
343       constants,  but with stated exceptions). For implementations supporting
344       the floating-point conversions it was not clear whether integer conver‐
345       sions need only accept integer constants and floating-point conversions
346       need only accept floating-point constants, or  whether  both  types  of
347       conversions  should accept both types of constants. Also by not distin‐
348       guishing between them, the requirement relating to  a  leading  single-
349       quote or double-quote applied to floating-point conversions even though
350       this provided no useful functionality  to  applications  that  was  not
351       already available through the integer conversions. The current standard
352       clarifies the situation by specifying that the arguments for  floating-
353       point  conversions  are  evaluated as if by strtod(), and the arguments
354       for integer conversions are evaluated as C integer constants, with  the
355       special  treatment  of  leading  single-quote and double-quote applying
356       only to integer conversions.
357

FUTURE DIRECTIONS

359       None.
360

SEE ALSO

362       awk, bc, echo
363
364       The Base Definitions volume of POSIX.1‐2017,  Chapter  5,  File  Format
365       Notation, Chapter 8, Environment Variables
366
367       The System Interfaces volume of POSIX.1‐2017, fprintf(), strtod()
368
370       Portions  of  this text are reprinted and reproduced in electronic form
371       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
372       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
373       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
374       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
375       event of any discrepancy between this version and the original IEEE and
376       The  Open Group Standard, the original IEEE and The Open Group Standard
377       is the referee document. The original Standard can be  obtained  online
378       at http://www.opengroup.org/unix/online.html .
379
380       Any  typographical  or  formatting  errors that appear in this page are
381       most likely to have been introduced during the conversion of the source
382       files  to  man page format. To report such errors, see https://www.ker
383       nel.org/doc/man-pages/reporting_bugs.html .
384
385
386
387IEEE/The Open Group                  2017                           PRINTF(1P)
Impressum