printf.1 (11442B)
- .\" SPDX-License-Identifier: BSD-3-Clause
- .\" 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.
- .\"
- .Dd July 1, 2020
- .Dt PRINTF 1
- .Os
- .Sh NAME
- .Nm printf
- .Nd formatted output
- .Sh SYNOPSIS
- .Nm
- .Ar format Op Ar argument...
- .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 argument
- 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 argument .
- 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 \ex Ns Ar hex-num
- Write a byte whose
- value is the 1- or 2-digits
- hexadecimal number
- .Ar hex-num .
- .It Cm \e Ns Ar num
- Write a byte whose
- value is the 1-, 2-, or 3-digit
- octal number
- .Ar num .
- .El
- Multibyte characters can be constructed using multiple
- .Cm \ex Ns Ar hex-num
- or
- .Cm \e Ns Ar num
- sequences.
- .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 EXAMPLES
- Print the string
- .Qq hello :
- .Bd -literal -offset indent
- $ printf "%s\en" hello
- hello
- .Ed
- .Pp
- Same as above, but notice that the format string is not quoted and hence we
- do not get the expected behavior:
- .Bd -literal -offset indent
- $ printf %s\en hello
- hellon$
- .Ed
- .Pp
- Print arguments forcing sign only for the first argument:
- .Bd -literal -offset indent
- $ printf "%+d\en%d\en%d\en" 1 -2 13
- +1
- -2
- 13
- .Ed
- .Pp
- Same as above, but the single format string will be applied to the three
- arguments:
- .Bd -literal -offset indent
- $ printf "%+d\en" 1 -2 13
- +1
- -2
- +13
- .Ed
- .Pp
- Print number using only two digits after the decimal point:
- .Bd -literal -offset indent
- $ printf "%.2f\en" 31.7456
- 31.75
- .Ed
- .Sh COMPATIBILITY
- The traditional
- .Bx
- behavior of converting arguments of numeric formats not beginning
- with a digit to the 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.
- The
- .Cm \ex Ns Ar hex-num
- backslash-escape is an extension.
- .Sh HISTORY
- The
- .Nm
- command appeared in
- .Bx 4.3 Reno .
- It is modeled
- after the standard library function,
- .Xr printf 3 .
- .Sh CAVEATS
- 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 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).