1
.\" Copyright (c) 1989, 1990, 1993
2
.\" The Regents of the University of California. All rights reserved.
3
.\" Copyright (c) 1997-2005
4
.\" Herbert Xu <herbert@gondor.apana.org.au>. All rights reserved.
6
.\" This code is derived from software contributed to Berkeley by
7
.\" the Institute of Electrical and Electronics Engineers, Inc.
9
.\" Redistribution and use in source and binary forms, with or without
10
.\" modification, are permitted provided that the following conditions
12
.\" 1. Redistributions of source code must retain the above copyright
13
.\" notice, this list of conditions and the following disclaimer.
14
.\" 2. Redistributions in binary form must reproduce the above copyright
15
.\" notice, this list of conditions and the following disclaimer in the
16
.\" documentation and/or other materials provided with the distribution.
17
.\" 3. Neither the name of the University nor the names of its contributors
18
.\" may be used to endorse or promote products derived from this software
19
.\" without specific prior written permission.
21
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33
.\" from: @(#)printf.1 8.1 (Berkeley) 6/6/93
47
formats and prints its arguments, after the first, under control
52
is a character string which contains three types of objects: plain characters,
53
which are simply copied to standard output, character escape sequences which
54
are converted and copied to the standard output, and format specifications,
55
each of which causes printing of the next successive
60
after the first are treated as strings if the corresponding format is
67
otherwise it is evaluated as a C constant, with the following extensions:
69
.Bl -bullet -offset indent -compact
71
A leading plus or minus sign is allowed.
73
If the leading character is a single or double quote, the value is the
75
code of the next character.
78
The format string is reused as often as necessary to satisfy the
80
Any extra format specifications are evaluated with zero or the null
83
Character escape sequences are in backslash notation as defined in
85
The characters and their meanings are as follows:
86
.Bl -tag -width Ds -offset indent
88
Write an \*[Lt]escape\*[Gt] character.
90
Write a \*[Lt]bell\*[Gt] character.
92
Write a \*[Lt]backspace\*[Gt] character.
94
Write a \*[Lt]form-feed\*[Gt] character.
96
Write a \*[Lt]new-line\*[Gt] character.
98
Write a \*[Lt]carriage return\*[Gt] character.
100
Write a \*[Lt]tab\*[Gt] character.
102
Write a \*[Lt]vertical tab\*[Gt] character.
104
Write a \*[Lt]single quote\*[Gt] character.
106
Write a \*[Lt]double quote\*[Gt] character.
108
Write a backslash character.
110
Write an 8\-bit character whose
112
value is the 1\-, 2\-, or 3\-digit octal number
115
Write an 8\-bit character whose
117
value is the 1\- or 2\-digit hexadecimal number
121
Each format specification is introduced by the percent character
123
The remainder of the format specification includes,
124
in the following order:
126
.It "Zero or more of the following flags:"
130
specifying that the value should be printed in an ``alternative form''.
137
formats, this option has no effect.
140
format the precision of the number is increased to force the first
141
character of the output string to a zero.
145
format, a non-zero result has the string
156
formats, the result will always contain a decimal point, even if no
157
digits follow the point (normally, a decimal point only appears in the
158
results of those formats if a digit follows the decimal point).
163
formats, trailing zeros are not removed from the result as they
165
.\" I turned this off - decided it isn't a valid use of '#'
168
.\" format, backslash-escape sequences are expanded first;
170
A minus sign `\-' which specifies
172
of the output in the indicated field;
174
A `+' character specifying that there should always be
175
a sign placed before the number when using signed formats.
177
A space specifying that a blank should be left before a positive number
179
A `+' overrides a space if both are used;
181
A zero `0' character indicating that zero-padding should be used
182
rather than blank-padding.
183
A `\-' overrides a `0' if both are used;
186
An optional digit string specifying a
188
if the output string has fewer characters than the field width it will
189
be blank-padded on the left (or right, if the left-adjustment indicator
190
has been given) to make up the field width (note that a leading zero
191
is a flag, but an embedded zero is part of a field width);
195
followed by an optional digit string giving a
197
which specifies the number of digits to appear after the decimal point,
202
formats, or the maximum number of characters to be printed
210
formats); if the digit string is missing, the precision is treated
213
A character which indicates the type of format to use (one of
214
.Cm diouxXfwEgGbBcs ) .
217
A field width or precision may be
219
instead of a digit string.
222
supplies the field width or precision.
224
The format characters and their meanings are:
229
is printed as a signed decimal (d or i), unsigned octal, unsigned decimal,
230
or unsigned hexadecimal (X or x), respectively.
234
is printed in the style
236
.Pf [\-]ddd Cm \&. No ddd
238
where the number of d's
239
after the decimal point is equal to the precision specification for
241
If the precision is missing, 6 digits are given; if the precision
242
is explicitly 0, no digits and no decimal point are printed.
246
is printed in the style
248
.Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
251
is one digit before the decimal point and the number after is equal to
252
the precision specification for the argument; when the precision is
253
missing, 6 digits are produced.
254
An upper-case E is used for an `E' format.
263
whichever gives full precision in minimum space.
265
Characters from the string
267
are printed with backslash-escape sequences expanded.
269
The following additional backslash-escape sequences are supported:
274
to ignore any remaining characters in the string operand containing it,
275
any remaining string operands, and any additional characters in
278
Write an 8\-bit character whose
280
value is the 1\-, 2\-, or 3\-digit
284
Write the control character
286
Generates characters `\e000' through `\e037`, and `\e177' (from `\e^?').
290
with the 8th bit set.
291
Generates characters `\e241' through `\e376`.
293
Write the control character
295
with the 8th bit set.
296
Generates characters `\e000' through `\e037`, and `\e177' (from `\eM^?').
299
Characters from the string
301
are printed with unprintable characters backslash-escaped using the
303
.Pf ` Cm \e Ar c No ',
304
.Pf ` Cm \e^ Ar c No ',
305
.Pf ` Cm \eM\- Ar c No '
307
.Pf ` Cm \eM^ Ar c No ',
309
formats described above.
311
The first character of
315
Characters from the string
317
are printed until the end is reached or until the number of characters
318
indicated by the precision specification is reached; if the
319
precision is omitted, all characters in the string are printed.
321
Print a `%'; no argument is used.
324
In no case does a non-existent or small field width cause truncation of
325
a field; padding takes place only if the specified field width exceeds
329
exits 0 on success, 1 on failure.
341
Support for the floating point formats and `*' as a field width and precision
342
are optional in POSIX.
344
The behaviour of the %B format and the \e', \e", \exxx, \ee and
345
\e[M][\-|^]c escape sequences are undefined in POSIX.
347
Since the floating point numbers are translated from
349
to floating-point and
350
then back again, floating-point precision may be lost.
352
Hexadecimal character constants are restricted to, and should be specified
353
as, two character constants. This is contrary to the ISO C standard but
354
does guarantee detection of the end of the constant.