Differential D25462 Diff 73973 head/usr.bin/printf/printf.1

Changeset View

Standalone View

head/usr.bin/printf/printf.1

	Show All 25 Lines
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" 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			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" @(#)printf.1 8.1 (Berkeley) 6/6/93			.\" @(#)printf.1 8.1 (Berkeley) 6/6/93
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd July 29, 2019			.Dd July 1, 2020
	.Dt PRINTF 1			.Dt PRINTF 1
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm printf			.Nm printf
	.Nd formatted output			.Nd formatted output
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.Nm			.Nm
	.Ar format Op Ar arguments ...			.Ar format Op Ar arguments ...
	▲ Show 20 Lines • Show All 268 Lines • ▼ Show 20 Lines
	Some shells may provide a builtin			Some shells may provide a builtin
	.Nm			.Nm
	command which is similar or identical to this utility.			command which is similar or identical to this utility.
	Consult the			Consult the
	.Xr builtin 1			.Xr builtin 1
	manual page.			manual page.
	.Sh EXIT STATUS			.Sh EXIT STATUS
	.Ex -std			.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			.Sh COMPATIBILITY
	The traditional			The traditional
	.Bx			.Bx
	behavior of converting arguments of numeric formats not beginning			behavior of converting arguments of numeric formats not beginning
	with a digit to the			with a digit to the ASCII
	.Tn ASCII
	code of the first character is not supported.			code of the first character is not supported.
	.Sh SEE ALSO			.Sh SEE ALSO
	.Xr builtin 1 ,			.Xr builtin 1 ,
	.Xr echo 1 ,			.Xr echo 1 ,
	.Xr sh 1 ,			.Xr sh 1 ,
	.Xr printf 3			.Xr printf 3
	.Sh STANDARDS			.Sh STANDARDS
	The			The
	.Nm			.Nm
	command is expected to be compatible with the			command is expected to be compatible with the
	.St -p1003.2			.St -p1003.2
	specification.			specification.
	.Sh HISTORY			.Sh HISTORY
	The			The
	.Nm			.Nm
	command appeared in			command appeared in
	.Bx 4.3 Reno .			.Bx 4.3 Reno .
	It is modeled			It is modeled
	after the standard library function,			after the standard library function,
	.Xr printf 3 .			.Xr printf 3 .
	.Sh CAVEATS			.Sh CAVEATS
	.Tn ANSI			ANSI hexadecimal character constants were deliberately not provided.
	hexadecimal character constants were deliberately not provided.
	.Pp			.Pp
	Trying to print a dash ("-") as the first character causes			Trying to print a dash ("-") as the first character causes
	.Nm			.Nm
	to interpret the dash as a program argument.			to interpret the dash as a program argument.
	.Nm --			.Nm --
	must be used before			must be used before
	.Ar format .			.Ar format .
	.Pp			.Pp
	If the locale contains multibyte characters			If the locale contains multibyte characters
	(such as UTF-8),			(such as UTF-8),
	the			the
	.Cm c			.Cm c
	format and			format and
	.Cm b			.Cm b
	and			and
	.Cm s			.Cm s
	formats with a precision			formats with a precision
	may not operate as expected.			may not operate as expected.
	.Sh BUGS			.Sh BUGS
	Since the floating point numbers are translated from			Since the floating point numbers are translated from ASCII
	.Tn ASCII			to floating-point and then back again, floating-point precision may be lost.
	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			(By default, the number is translated to an IEEE-754 double-precision
	value before being printed.			value before being printed.
	The			The
	.Cm L			.Cm L
	modifier may produce additional precision, depending on the hardware platform.)			modifier may produce additional precision, depending on the hardware platform.)
	.Pp			.Pp
	The escape sequence \e000 is the string terminator.			The escape sequence \e000 is the string terminator.
	When present in the argument for the			When present in the argument for the
	.Cm b			.Cm b
	format, the argument will be truncated at the \e000 character.			format, the argument will be truncated at the \e000 character.
	.Pp			.Pp
	Multibyte characters are not recognized in format strings (this is only			Multibyte characters are not recognized in format strings (this is only
	a problem if			a problem if
	.Ql %			.Ql %
	can appear inside a multibyte character).			can appear inside a multibyte character).