386 lines
10 KiB
Groff
386 lines
10 KiB
Groff
.\" 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.
|
|
.\"
|
|
.\" @(#)printf.1 8.1 (Berkeley) 6/6/93
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd July 29, 2019
|
|
.Dt PRINTF 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm printf
|
|
.Nd formatted output
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Ar format Op Ar arguments ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility 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 c , b
|
|
or
|
|
.Cm s ;
|
|
otherwise it is evaluated as a C constant, with the following extensions:
|
|
.Pp
|
|
.Bl -bullet -offset indent -compact
|
|
.It
|
|
A leading plus or minus sign is allowed.
|
|
.It
|
|
If the leading character is a single or double quote, the value is the
|
|
character 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 the
|
|
.St -ansiC ,
|
|
with extensions.
|
|
The characters and their meanings
|
|
are as follows:
|
|
.Pp
|
|
.Bl -tag -width Ds -offset indent -compact
|
|
.It Cm \ea
|
|
Write a <bell> character.
|
|
.It Cm \eb
|
|
Write a <backspace> character.
|
|
.It Cm \ef
|
|
Write a <form-feed> character.
|
|
.It Cm \en
|
|
Write a <new-line> character.
|
|
.It Cm \er
|
|
Write a <carriage return> character.
|
|
.It Cm \et
|
|
Write a <tab> character.
|
|
.It Cm \ev
|
|
Write a <vertical tab> character.
|
|
.It Cm \e\'
|
|
Write a <single quote> character.
|
|
.It Cm \e\e
|
|
Write a backslash character.
|
|
.It Cm \e Ns Ar num
|
|
Write a byte whose
|
|
value is the 1-, 2-, or 3-digit
|
|
octal number
|
|
.Ar num .
|
|
Multibyte characters can be constructed using multiple
|
|
.Cm \e Ns Ar num
|
|
sequences.
|
|
.El
|
|
.Pp
|
|
Each format specification is introduced by the percent character
|
|
(``%'').
|
|
The remainder of the format specification includes,
|
|
in the following order:
|
|
.Bl -tag -width Ds
|
|
.It "Zero or more of the following flags:"
|
|
.Bl -tag -width Ds
|
|
.It Cm #
|
|
A `#' character
|
|
specifying that the value should be printed in an ``alternate form''.
|
|
For
|
|
.Cm b , c , d , s
|
|
and
|
|
.Cm u
|
|
formats, this option has no effect.
|
|
For the
|
|
.Cm o
|
|
formats 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
|
|
.Li 0x
|
|
.Pq Li 0X
|
|
prepended to it.
|
|
For
|
|
.Cm a , A , e , E , f , F , 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;
|
|
.It Cm \&\-
|
|
A minus sign `\-' which specifies
|
|
.Em left adjustment
|
|
of the output in the indicated field;
|
|
.It Cm \&+
|
|
A `+' character specifying that there should always be
|
|
a sign placed before the number when using signed formats.
|
|
.It Sq \&\ \&
|
|
A space specifying that a blank should be left before a positive number
|
|
for a signed format.
|
|
A `+' overrides a space if both are used;
|
|
.It Cm \&0
|
|
A zero `0' character indicating that zero-padding should be used
|
|
rather than blank-padding.
|
|
A `\-' overrides a `0' if both are used;
|
|
.El
|
|
.It "Field Width:"
|
|
An optional digit string specifying a
|
|
.Em field width ;
|
|
if the output string has fewer bytes than the field width it will
|
|
be blank-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,
|
|
.Sq Cm \&.\& ,
|
|
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 bytes to be printed
|
|
from a string; 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 diouxXfFeEgGaAcsb ) .
|
|
The uppercase formats differ from their lowercase counterparts only in
|
|
that the output of the former is entirely in uppercase.
|
|
The floating-point format specifiers
|
|
.Pq Cm fFeEgGaA
|
|
may be prefixed by an
|
|
.Cm L
|
|
to request that additional precision be used, if available.
|
|
.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
|
|
is printed as a signed decimal (d or i), unsigned octal, unsigned decimal,
|
|
or unsigned hexadecimal (X or x), respectively.
|
|
.It Cm fF
|
|
The
|
|
.Ar argument
|
|
is printed in the style `[\-]ddd.ddd' where the number of d'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.
|
|
The values \*[If] and \*[Na] are printed as
|
|
.Ql inf
|
|
and
|
|
.Ql nan ,
|
|
respectively.
|
|
.It Cm eE
|
|
The
|
|
.Ar argument
|
|
is printed in the style
|
|
.Cm e
|
|
.Sm off
|
|
.Sq Op - Ar d.ddd No \(+- Ar dd
|
|
.Sm on
|
|
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.
|
|
The values \*[If] and \*[Na] are printed as
|
|
.Ql inf
|
|
and
|
|
.Ql nan ,
|
|
respectively.
|
|
.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 printed in style
|
|
.Sm off
|
|
.Sq Op - Ar h.hhh No \(+- Li p Ar d
|
|
.Sm on
|
|
where there is one digit before the hexadecimal point and the number
|
|
after is equal to the precision specification for the argument;
|
|
when the precision is missing, enough digits are produced to convey
|
|
the argument's exact double-precision floating-point representation.
|
|
The values \*[If] and \*[Na] are printed as
|
|
.Ql inf
|
|
and
|
|
.Ql nan ,
|
|
respectively.
|
|
.It Cm c
|
|
The first byte of
|
|
.Ar argument
|
|
is printed.
|
|
.It Cm s
|
|
Bytes from the string
|
|
.Ar argument
|
|
are printed until the end is reached or until the number of bytes
|
|
indicated by the precision specification is reached; however if the
|
|
precision is 0 or missing, the string is printed entirely.
|
|
.It Cm b
|
|
As for
|
|
.Cm s ,
|
|
but interpret character escapes in backslash notation in the string
|
|
.Ar argument .
|
|
The permitted escape sequences are slightly different in that
|
|
octal escapes are
|
|
.Cm \e0 Ns Ar num
|
|
instead of
|
|
.Cm \e Ns Ar num
|
|
and that an additional escape sequence
|
|
.Cm \ec
|
|
stops further output from this
|
|
.Nm
|
|
invocation.
|
|
.It Cm n$
|
|
Allows reordering of the output according to
|
|
.Ar argument .
|
|
.It Cm \&%
|
|
Print a `%'; no argument is used.
|
|
.El
|
|
.Pp
|
|
The decimal point
|
|
character is defined in the program's locale (category
|
|
.Dv LC_NUMERIC ) .
|
|
.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
|
|
Some shells may provide a builtin
|
|
.Nm
|
|
command which is similar or identical to this utility.
|
|
Consult the
|
|
.Xr builtin 1
|
|
manual page.
|
|
.Sh EXIT STATUS
|
|
.Ex -std
|
|
.Sh COMPATIBILITY
|
|
The traditional
|
|
.Bx
|
|
behavior of converting arguments of numeric formats not beginning
|
|
with a digit to the
|
|
.Tn ASCII
|
|
code of the first character is not supported.
|
|
.Sh SEE ALSO
|
|
.Xr builtin 1 ,
|
|
.Xr echo 1 ,
|
|
.Xr sh 1 ,
|
|
.Xr printf 3
|
|
.Sh STANDARDS
|
|
The
|
|
.Nm
|
|
command is expected to be compatible with the
|
|
.St -p1003.2
|
|
specification.
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
command appeared in
|
|
.Bx 4.3 Reno .
|
|
It is modeled
|
|
after the standard library function,
|
|
.Xr printf 3 .
|
|
.Sh CAVEATS
|
|
.Tn ANSI
|
|
hexadecimal character constants were deliberately not provided.
|
|
.Pp
|
|
Trying to print a dash ("-") as the first character causes
|
|
.Nm
|
|
to interpret the dash as a program argument.
|
|
.Nm --
|
|
must be used before
|
|
.Ar format .
|
|
.Pp
|
|
If the locale contains multibyte characters
|
|
(such as UTF-8),
|
|
the
|
|
.Cm c
|
|
format and
|
|
.Cm b
|
|
and
|
|
.Cm s
|
|
formats with a precision
|
|
may not operate as expected.
|
|
.Sh BUGS
|
|
Since the floating point numbers are translated from
|
|
.Tn ASCII
|
|
to floating-point and
|
|
then back again, floating-point precision may be lost.
|
|
(By default, the number is translated to an IEEE-754 double-precision
|
|
value before being printed.
|
|
The
|
|
.Cm L
|
|
modifier may produce additional precision, depending on the hardware platform.)
|
|
.Pp
|
|
The escape sequence \e000 is the string terminator.
|
|
When present in the argument for the
|
|
.Cm b
|
|
format, the argument will be truncated at the \e000 character.
|
|
.Pp
|
|
Multibyte characters are not recognized in format strings (this is only
|
|
a problem if
|
|
.Ql %
|
|
can appear inside a multibyte character).
|