Add printf.1
This commit is contained in:
sin
parent
d348bb22c9
commit
7c6f2f60e6
386
printf.1
Normal file
386
printf.1
Normal file
|
|
@ -0,0 +1,386 @@
|
||||||
|
.\" $OpenBSD: src/usr.bin/printf/printf.1,v 1.27 2014/05/25 07:36:36 jmc Exp $
|
||||||
|
.\"
|
||||||
|
.\" Copyright (c) 1989, 1990 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 5.11 (Berkeley) 7/24/91
|
||||||
|
.\"
|
||||||
|
.Dd $Mdocdate: May 13 2014 $
|
||||||
|
.Dt PRINTF 1
|
||||||
|
.Os
|
||||||
|
.Sh NAME
|
||||||
|
.Nm printf
|
||||||
|
.Nd formatted output
|
||||||
|
.Sh SYNOPSIS
|
||||||
|
.Nm printf
|
||||||
|
.Ar format
|
||||||
|
.Op Ar argument ...
|
||||||
|
.Sh DESCRIPTION
|
||||||
|
.Nm printf
|
||||||
|
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 arguments after the first are treated as strings
|
||||||
|
if the corresponding format is
|
||||||
|
.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
|
||||||
|
.Tn ASCII
|
||||||
|
code of the next character.
|
||||||
|
.El
|
||||||
|
.Pp
|
||||||
|
The format string is reused as often as necessary to satisfy the 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:
|
||||||
|
.Pp
|
||||||
|
.Bl -tag -width Ds -offset indent -compact
|
||||||
|
.It Cm \ee
|
||||||
|
Write an <escape> character.
|
||||||
|
.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 an 8-bit character whose
|
||||||
|
.Tn ASCII
|
||||||
|
value is the 1-, 2-, or 3-digit
|
||||||
|
octal number
|
||||||
|
.Ar num .
|
||||||
|
.El
|
||||||
|
.Pp
|
||||||
|
Each format specification is introduced by the percent
|
||||||
|
.Pq Sq \&%
|
||||||
|
character.
|
||||||
|
The remainder of the format specifiers include,
|
||||||
|
in the following order:
|
||||||
|
.Bl -tag -width Ds
|
||||||
|
.It "Zero or more of the following flags:"
|
||||||
|
.Bl -tag -width Ds
|
||||||
|
.It Cm #
|
||||||
|
Specifies that the value should be printed in an
|
||||||
|
.Dq alternate form .
|
||||||
|
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
|
||||||
|
.Li 0x
|
||||||
|
.Pq Li 0X
|
||||||
|
prepended to it.
|
||||||
|
For
|
||||||
|
.Cm a ,
|
||||||
|
.Cm A ,
|
||||||
|
.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.
|
||||||
|
For all other formats, behaviour is undefined.
|
||||||
|
.It Cm \&\-
|
||||||
|
Specifies the
|
||||||
|
.Em left adjustment
|
||||||
|
of the output in the indicated field.
|
||||||
|
.It Cm \&+
|
||||||
|
Specifies that there should always be
|
||||||
|
a sign placed before the number when using signed formats.
|
||||||
|
.It Sq \&\ \&
|
||||||
|
A space specifies that a blank should be left before a positive number
|
||||||
|
for a signed format.
|
||||||
|
A
|
||||||
|
.Ql +
|
||||||
|
overrides a space if both are used.
|
||||||
|
.It Cm \&0
|
||||||
|
A zero character specifies that zero-padding should be used
|
||||||
|
rather than blank-padding.
|
||||||
|
This flag is ignored if used with a precision
|
||||||
|
specifier and any of the
|
||||||
|
.Cm d , i , o , u ,
|
||||||
|
or
|
||||||
|
.Cm x
|
||||||
|
.Pq Cm X
|
||||||
|
formats.
|
||||||
|
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 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
|
||||||
|
.Pq Sq \&. ,
|
||||||
|
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; 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 diouxXfFeEgGaAbcs ) .
|
||||||
|
.El
|
||||||
|
.Pp
|
||||||
|
A field width or precision may be
|
||||||
|
.Ql \&*
|
||||||
|
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
|
||||||
|
.Pq Cm d No or Cm i ,
|
||||||
|
unsigned octal, unsigned decimal,
|
||||||
|
or unsigned hexadecimal
|
||||||
|
.Pq Cm x No or Cm X ,
|
||||||
|
respectively.
|
||||||
|
.It Cm fF
|
||||||
|
The
|
||||||
|
.Ar argument
|
||||||
|
is printed in the style
|
||||||
|
.Sm off
|
||||||
|
.Pf [\-]ddd Cm \&. No ddd
|
||||||
|
.Sm on
|
||||||
|
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.
|
||||||
|
.Pp
|
||||||
|
If the argument is infinity, it will be converted to [-]inf
|
||||||
|
.Pq Cm f
|
||||||
|
or [-]INF
|
||||||
|
.Pq Cm F ,
|
||||||
|
respectively.
|
||||||
|
If the argument is not-a-number (NaN), it will be converted to
|
||||||
|
[-]nan
|
||||||
|
.Pq Cm f
|
||||||
|
or [-]NAN
|
||||||
|
.Pq Cm F ,
|
||||||
|
respectively.
|
||||||
|
.It Cm eE
|
||||||
|
The
|
||||||
|
.Ar argument
|
||||||
|
is printed in the style
|
||||||
|
.Sm off
|
||||||
|
.Pf [\-]d Cm \&. No ddd Cm e No \*(Pmdd
|
||||||
|
.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.
|
||||||
|
An upper-case
|
||||||
|
.Sq E
|
||||||
|
is used for an
|
||||||
|
.Cm E
|
||||||
|
format.
|
||||||
|
.Pp
|
||||||
|
If the argument is infinity, it will be converted to [-]inf
|
||||||
|
.Pq Cm e
|
||||||
|
or [-]INF
|
||||||
|
.Pq Cm E ,
|
||||||
|
respectively.
|
||||||
|
If the argument is not-a-number (NaN), it will be converted to
|
||||||
|
[-]nan
|
||||||
|
.Pq Cm e
|
||||||
|
or [-]NAN
|
||||||
|
.Pq Cm E ,
|
||||||
|
respectively.
|
||||||
|
.It Cm gG
|
||||||
|
The
|
||||||
|
.Ar argument
|
||||||
|
is printed in style
|
||||||
|
.Cm f
|
||||||
|
or in style
|
||||||
|
.Cm e
|
||||||
|
.Pq Cm E
|
||||||
|
whichever gives full precision in minimum space.
|
||||||
|
.Pp
|
||||||
|
If the argument is infinity, it will be converted to [-]inf
|
||||||
|
.Pq Cm g
|
||||||
|
or [-]INF
|
||||||
|
.Pq Cm G ,
|
||||||
|
respectively.
|
||||||
|
If the argument is not-a-number (NaN), it will be converted to
|
||||||
|
[-]nan
|
||||||
|
.Pq Cm g
|
||||||
|
or [-]NAN
|
||||||
|
.Pq Cm G ,
|
||||||
|
respectively.
|
||||||
|
.It Cm aA
|
||||||
|
The
|
||||||
|
.Ar argument
|
||||||
|
is printed in style
|
||||||
|
.Sm off
|
||||||
|
.Pf [\-]0xh Cm \&. No hhh Cm p No [\*(Pm]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.
|
||||||
|
.Pp
|
||||||
|
If the argument is infinity, it will be converted to [-]inf
|
||||||
|
.Pq Cm a
|
||||||
|
or [-]INF
|
||||||
|
.Pq Cm A ,
|
||||||
|
respectively.
|
||||||
|
If the argument is not-a-number (NaN), it will be converted to
|
||||||
|
[-]nan
|
||||||
|
.Pq Cm a
|
||||||
|
or [-]NAN
|
||||||
|
.Pq Cm A ,
|
||||||
|
respectively.
|
||||||
|
.It Cm b
|
||||||
|
Characters from the string
|
||||||
|
.Ar argument
|
||||||
|
are printed with backslash-escape sequences expanded.
|
||||||
|
.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; however if the
|
||||||
|
precision is 0 or missing, all characters in the string are printed.
|
||||||
|
.It Cm \&%
|
||||||
|
Print a
|
||||||
|
.Ql \&% ;
|
||||||
|
no argument is used.
|
||||||
|
.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.
|
||||||
|
.Sh EXIT STATUS
|
||||||
|
.Ex -std printf
|
||||||
|
.Sh EXAMPLES
|
||||||
|
Convert a hexadecimal value to decimal and print it out:
|
||||||
|
.Pp
|
||||||
|
.D1 Ic $ printf \&"%d\en\&" 0x20
|
||||||
|
.Pp
|
||||||
|
Print the decimal representation of the character 'a' (see
|
||||||
|
.Xr ascii 7 ) :
|
||||||
|
.Pp
|
||||||
|
.D1 Ic $ printf \&"%d\en\&" \e'a
|
||||||
|
.Sh SEE ALSO
|
||||||
|
.Xr echo 1 ,
|
||||||
|
.Xr printf 3
|
||||||
|
.Sh STANDARDS
|
||||||
|
The
|
||||||
|
.Nm
|
||||||
|
utility is compliant with the
|
||||||
|
.St -p1003.1-2008
|
||||||
|
specification.
|
||||||
|
.Pp
|
||||||
|
The escape sequences \ee and \e' are extensions to that specification.
|
||||||
|
.Sh HISTORY
|
||||||
|
The
|
||||||
|
.Nm
|
||||||
|
command appeared in
|
||||||
|
.Bx 4.3 Reno .
|
||||||
|
.Sh CAVEATS
|
||||||
|
It is important never to pass a string with user-supplied data as a
|
||||||
|
format without using
|
||||||
|
.Ql %s .
|
||||||
|
An attacker can put format specifiers in the string to mangle your stack,
|
||||||
|
leading to a possible security hole.
|
||||||
|
.Pp
|
||||||
|
Always be sure to use the proper secure idiom:
|
||||||
|
.Bd -literal -offset indent
|
||||||
|
printf "%s" "$STRING"
|
||||||
|
.Ed
|
||||||
|
.Sh BUGS
|
||||||
|
Since arguments are translated from
|
||||||
|
.Tn ASCII
|
||||||
|
to floating-point, and
|
||||||
|
then back again, floating-point precision may be lost.
|
||||||
Loading…
Reference in New Issue
Block a user