commit 7c6f2f60e6fb61f76a4d7f0fa3ea22a58144a31f
parent d348bb22c9368aa96b3edafa8285a009c5fe08b6
Author: sin <sin@2f30.org>
Date: Mon, 29 Sep 2014 14:35:35 +0100
Add printf.1
Diffstat:
| A | printf.1 | | | 386 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 386 insertions(+), 0 deletions(-)
diff --git a/printf.1 b/printf.1
@@ -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.
