478 lines
11 KiB
Groff
478 lines
11 KiB
Groff
.\" $NetBSD: printf.1,v 1.37 2023/02/13 23:02:27 andvar Exp $
|
|
.\"
|
|
.\" Copyright (c) 1989, 1990, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to Berkeley by
|
|
.\" the Institute of Electrical and Electronics Engineers, Inc.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" from: @(#)printf.1 8.1 (Berkeley) 6/6/93
|
|
.\"
|
|
.Dd May 19, 2021
|
|
.Dt PRINTF 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm printf
|
|
.Nd formatted output
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Ar format
|
|
.Op Ar arguments ...
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
formats and prints its arguments, after the first, under control
|
|
of the
|
|
.Ar format .
|
|
The
|
|
.Ar format
|
|
is a character string which contains three types of objects: plain characters,
|
|
which are simply copied to standard output, character escape sequences which
|
|
are converted and copied to the standard output, and format specifications,
|
|
each of which causes printing of the next successive
|
|
.Ar argument .
|
|
.Pp
|
|
The
|
|
.Ar arguments
|
|
after the first are treated as strings if the corresponding format is
|
|
either
|
|
.Cm b ,
|
|
.Cm B ,
|
|
.Cm c ,
|
|
or
|
|
.Cm s ;
|
|
otherwise it is evaluated as a C\~constant, with the following extensions:
|
|
.Bl -bullet -offset indent
|
|
.It
|
|
A leading plus or minus sign is allowed.
|
|
.It
|
|
If the leading character is a single or double quote, the value is the ASCII
|
|
code of the next character.
|
|
.El
|
|
.Pp
|
|
The format string is reused as often as necessary to satisfy the
|
|
.Ar arguments .
|
|
Any extra format specifications are evaluated with zero or the null
|
|
string.
|
|
.Pp
|
|
Character escape sequences are in backslash notation as defined in
|
|
.St -ansiC .
|
|
The characters and their meanings are as follows:
|
|
.Bl -tag -offset indent -width Cm
|
|
.It Cm \ee
|
|
Write an
|
|
.Aq escape
|
|
character.
|
|
.It Cm \ea
|
|
Write a
|
|
.Aq bell
|
|
character.
|
|
.It Cm \eb
|
|
Write a
|
|
.Aq backspace
|
|
character.
|
|
.It Cm \ef
|
|
Write a
|
|
.Aq form-feed
|
|
character.
|
|
.It Cm \en
|
|
Write a
|
|
.Aq new-line
|
|
character.
|
|
.It Cm \er
|
|
Write a
|
|
.Aq carriage return
|
|
character.
|
|
.It Cm \et
|
|
Write a
|
|
.Aq tab
|
|
character.
|
|
.It Cm \ev
|
|
Write a
|
|
.Aq vertical tab
|
|
character.
|
|
.It Cm \e\(aq
|
|
Write a
|
|
.Aq single quote
|
|
character.
|
|
.It Cm \e\*q
|
|
Write a
|
|
.Aq double quote
|
|
character.
|
|
.It Cm \e\e
|
|
Write a backslash character.
|
|
.It Cm \e Ns Ar num
|
|
Write an 8-bit character whose ASCII
|
|
value is the 1-, 2-, or 3-digit octal number
|
|
.Ar num .
|
|
.It Cm \ex Ns Ar xx
|
|
Write an 8-bit character whose ASCII
|
|
value is the 1- or 2-digit hexadecimal number
|
|
.Ar xx .
|
|
.El
|
|
.Pp
|
|
Each format specification is introduced by the percent character
|
|
.Pq Ql \&% .
|
|
To produce a literal percent
|
|
.Pq Ql \&%
|
|
in the output, write the percent character twice:
|
|
.Pq Ql \&%% .
|
|
This is not a format conversion.
|
|
The remainder of the format specification includes,
|
|
in the following order:
|
|
.Bl -tag -width 5n
|
|
.It Zero or more of the following flags :
|
|
.Bl -tag -width Cm
|
|
.It Cm #
|
|
A
|
|
.Ql \&#
|
|
character specifying that the value should be printed in an
|
|
.Dq alternative form .
|
|
For
|
|
.Cm b ,
|
|
.Cm c ,
|
|
.Cm d ,
|
|
and
|
|
.Cm s
|
|
formats, this option has no effect.
|
|
For the
|
|
.Cm o
|
|
format the precision of the number is increased to force the first
|
|
character of the output string to a zero.
|
|
For the
|
|
.Cm x
|
|
.Pq Cm X
|
|
format, a non-zero result has the string
|
|
.Ql 0x
|
|
.Pq Ql 0X
|
|
prepended to it.
|
|
For
|
|
.Cm e ,
|
|
.Cm E ,
|
|
.Cm f ,
|
|
.Cm F ,
|
|
.Cm g ,
|
|
and
|
|
.Cm G
|
|
formats, the result will always contain a decimal point, even if no
|
|
digits follow the point (normally, a decimal point only appears in the
|
|
results of those formats if a digit follows the decimal point).
|
|
For
|
|
.Cm g
|
|
and
|
|
.Cm G
|
|
formats, trailing zeros are not removed from the result as they
|
|
would otherwise be.
|
|
.\" I turned this off - decided it isn't a valid use of '#'
|
|
.\" For the
|
|
.\" .Cm B
|
|
.\" format, backslash-escape sequences are expanded first;
|
|
.It Cm \&\-
|
|
A minus sign which specifies
|
|
.Em left adjustment
|
|
of the output in the indicated field;
|
|
.It Cm \&+
|
|
A plus sign which specifies that there should always be
|
|
a sign placed before the number when using signed formats.
|
|
.It Sq Cm \&\ \&
|
|
A
|
|
.Aq space
|
|
character which specifies that a space should be left before
|
|
a positive number for a signed format.
|
|
A
|
|
.Ql \&+
|
|
overrides a
|
|
.Aq space
|
|
if both are used;
|
|
.It Cm \&0
|
|
A digit zero character which specifies that zero-padding should be used
|
|
rather than space-padding.
|
|
A
|
|
.Ql \-
|
|
overrides a
|
|
.Ql \&0
|
|
if both are used;
|
|
.El
|
|
.It Field Width :
|
|
An optional digit string specifying a
|
|
.Em field width ;
|
|
if the output string has fewer characters than the field width it will
|
|
be space-padded on the left (or right, if the left-adjustment indicator
|
|
has been given) to make up the field width (note that a leading zero
|
|
is a flag, but an embedded zero is part of a field width);
|
|
.It Precision :
|
|
An optional period
|
|
.Pq Ql \&. ,
|
|
followed by an optional digit string giving a
|
|
.Em precision
|
|
which specifies the number of digits to appear after the decimal point,
|
|
for
|
|
.Cm e
|
|
and
|
|
.Cm f
|
|
formats, or the maximum number of characters to be printed
|
|
from a string
|
|
.Sm off
|
|
.Pf ( Cm b ,
|
|
.Sm on
|
|
.Cm B ,
|
|
and
|
|
.Cm s
|
|
formats); if the digit string is missing, the precision is treated
|
|
as zero;
|
|
.It Format :
|
|
A character which indicates the type of format to use (one of
|
|
.Cm diouxXfFeEgGaAbBcs ) .
|
|
.El
|
|
.Pp
|
|
A field width or precision may be
|
|
.Sq Cm \&*
|
|
instead of a digit string.
|
|
In this case an
|
|
.Ar argument
|
|
supplies the field width or precision.
|
|
.Pp
|
|
The format characters and their meanings are:
|
|
.Bl -tag -width Fl
|
|
.It Cm diouXx
|
|
The
|
|
.Ar argument ,
|
|
which must represent an integer constant,
|
|
with an optional leading plus or minus sign,
|
|
is printed as a signed decimal
|
|
.Cm ( d
|
|
or
|
|
.Cm i ) ,
|
|
unsigned octal
|
|
.Cm ( o ) ,
|
|
unsigned decimal
|
|
.Cm ( u ) ,
|
|
or unsigned hexadecimal
|
|
.Cm ( X
|
|
or
|
|
.Cm x ) .
|
|
.It Cm fF
|
|
The
|
|
.Ar argument
|
|
is printed in the style
|
|
.Oo Li \&\- Oc Ns Ar \&\^ddd Ns Li \&\^\&. Ns Ar ddd
|
|
where the number of
|
|
.Ar d Ns \|'s
|
|
after the decimal point is equal to the precision specification for
|
|
the argument.
|
|
If the precision is missing, 6 digits are given; if the precision
|
|
is explicitly 0, no digits and no decimal point are printed.
|
|
If the number is Infinity, or Not-a-Number, then
|
|
.Ql inf
|
|
or
|
|
.Ql nan
|
|
is printed for
|
|
.Cm f
|
|
format, and
|
|
.Ql INF
|
|
or
|
|
.Ql NAN
|
|
for
|
|
.Cm F
|
|
format.
|
|
.It Cm eE
|
|
The
|
|
.Ar argument
|
|
is printed in the style
|
|
.Oo Li \&\- Oc Ns Ar \&\^d Ns Li \&. Ns Ar ddd Ns Li \&\|e\*(Pm Ns Ar \&\|dd
|
|
where there
|
|
is one digit before the decimal point and the number after is equal to
|
|
the precision specification for the argument; when the precision is
|
|
missing, 6 digits are produced.
|
|
An upper-case
|
|
.Ql E
|
|
is used for an
|
|
.Cm E
|
|
format, and upper-case for Infinity and NaN as for
|
|
.Cm F
|
|
format.
|
|
.It Cm gG
|
|
The
|
|
.Ar argument
|
|
is printed in style
|
|
.Cm f
|
|
.Pq Cm F
|
|
or in style
|
|
.Cm e
|
|
.Pq Cm E
|
|
whichever gives full precision in minimum space.
|
|
.It Cm aA
|
|
The
|
|
.Ar argument
|
|
is treated as a floating point number,
|
|
for which the underlying hexadecimal representation is
|
|
printed.
|
|
See
|
|
.Xr printf 3
|
|
for the details.
|
|
.It Cm b
|
|
Characters from the string
|
|
.Ar argument
|
|
are printed with backslash-escape sequences expanded.
|
|
.Pp
|
|
The following additional backslash-escape sequences are supported:
|
|
.Bl -tag -width Cm
|
|
.It Cm \ec
|
|
Causes
|
|
.Nm
|
|
to ignore any remaining characters in the string operand containing it,
|
|
any remaining string operands, and any additional characters in
|
|
the format operand.
|
|
.It Cm \e0 Ns Ar num
|
|
Write an 8-bit character whose ASCII value is the 1-, 2-, or
|
|
3-digit octal number
|
|
.Ar num .
|
|
.It Cm \e^ Ns Ar c
|
|
Write the control character
|
|
.Ar c .
|
|
Generates characters
|
|
.Sq \e000
|
|
through
|
|
.Sq \e037 ,
|
|
and
|
|
.Sq \e177
|
|
(from
|
|
.Ql \e^\&? ) .
|
|
.It Cm \eM^ Ns Ar c
|
|
Write the control character
|
|
.Ar c
|
|
with the 8th bit set.
|
|
Generates characters
|
|
.Sq \e200
|
|
through
|
|
.Sq \e237 ,
|
|
and
|
|
.Sq \e377
|
|
(from
|
|
.Ql \eM^\&? ) .
|
|
.It Cm \eM\- Ns Ar c
|
|
Write the character
|
|
.Ar c
|
|
with the 8th bit set.
|
|
Generates characters
|
|
.Sq \e241
|
|
through
|
|
.Sq \e376 .
|
|
.El
|
|
.It Cm B
|
|
Characters from the string
|
|
.Ar argument
|
|
are printed with unprintable characters backslash-escaped using the
|
|
.Sq Cm \e Ns Ar c ,
|
|
.Sq Cm \e^ Ns Ar c ,
|
|
.Sq Cm \eM^ Ns Ar c ,
|
|
or
|
|
.Sq Cm \eM\- Ns Ar c
|
|
formats described above.
|
|
.It Cm c
|
|
The first character of
|
|
.Ar argument
|
|
is printed.
|
|
.It Cm s
|
|
Characters from the string
|
|
.Ar argument
|
|
are printed until the end is reached or until the number of characters
|
|
indicated by the precision specification is reached; if the
|
|
precision is omitted, all characters in the string are printed.
|
|
.El
|
|
.Pp
|
|
In no case does a non-existent or small field width cause truncation of
|
|
a field; padding takes place only if the specified field width exceeds
|
|
the actual width.
|
|
.Pp
|
|
If the first character of
|
|
.Ar format
|
|
is a dash,
|
|
.Ar format
|
|
must be preceded by a word consisting of two dashes
|
|
.Pq Sq Fl Fl
|
|
to prevent it
|
|
from being interpreted as an option string.
|
|
.Sh EXIT STATUS
|
|
.Ex -std
|
|
.Sh SEE ALSO
|
|
.Xr echo 1 ,
|
|
.Xr printf 3 ,
|
|
.Xr vis 3 ,
|
|
.Xr printf 9
|
|
.Sh STANDARDS
|
|
The
|
|
.Nm
|
|
utility conforms to
|
|
.St -p1003.1-2001 .
|
|
.Pp
|
|
Support for the floating point formats and
|
|
.Sq Cm \&*
|
|
as a field width and precision
|
|
are optional in POSIX.
|
|
.Pp
|
|
The behaviour of the
|
|
.Cm \&%B
|
|
format and the
|
|
.Cm \e\(aq ,
|
|
.Cm \e\*q ,
|
|
.Cm \ee ,
|
|
.Cm \e Ns Ar num ,
|
|
and
|
|
.Cm \e Ns Oo Cm M Oc Ns Oo Cm \- Ns Li \&\(or Ns Cm ^ Oc Ns Ar c
|
|
escape sequences are undefined in POSIX.
|
|
.Sh BUGS
|
|
Since the floating point numbers are translated from ASCII to
|
|
floating-point and then back again, floating-point precision may be lost.
|
|
.Pp
|
|
Hexadecimal character constants are restricted to, and should be specified
|
|
as, two character constants.
|
|
This is contrary to the ISO C standard but
|
|
does guarantee detection of the end of the constant.
|
|
.Sh NOTES
|
|
All formats which treat the
|
|
.Ar argument
|
|
as a number first convert the
|
|
.Ar argument
|
|
from its external representation as a character string
|
|
to an internal numeric representation, and then apply the
|
|
format to the internal numeric representation, producing
|
|
another external character string representation.
|
|
One might expect the
|
|
.Cm \&%c
|
|
format to do likewise, but in fact it does not.
|
|
.Pp
|
|
To convert a string representation of a decimal, octal, or hexadecimal
|
|
number into the corresponding character, two nested
|
|
.Nm
|
|
invocations may be used, in which the inner invocation
|
|
converts the input to an octal string, and the outer
|
|
invocation uses the octal string as part of a format.
|
|
For example, the following command outputs the character whose code
|
|
is 0x0a, which is a newline in ASCII:
|
|
.Pp
|
|
.Dl printf \*q$(printf \(aq\e\e%o\(aq 0x0a)\*q
|