mirror of git://git.suckless.org/sbase
Add printf.1
This commit is contained in:
sin
parent
d348bb22c9
commit
7c6f2f60e6
|
|
@ -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