morpheus-base

morpheus base system
git clone git://git.2f30.org/morpheus-base
Log | Files | Refs

printf.1 (10108B)


      1 .\"	$OpenBSD: src/usr.bin/printf/printf.1,v 1.27 2014/05/25 07:36:36 jmc Exp $
      2 .\"
      3 .\" Copyright (c) 1989, 1990 The Regents of the University of California.
      4 .\" All rights reserved.
      5 .\"
      6 .\" This code is derived from software contributed to Berkeley by
      7 .\" the Institute of Electrical and Electronics Engineers, Inc.
      8 .\"
      9 .\" Redistribution and use in source and binary forms, with or without
     10 .\" modification, are permitted provided that the following conditions
     11 .\" are met:
     12 .\" 1. Redistributions of source code must retain the above copyright
     13 .\"    notice, this list of conditions and the following disclaimer.
     14 .\" 2. Redistributions in binary form must reproduce the above copyright
     15 .\"    notice, this list of conditions and the following disclaimer in the
     16 .\"    documentation and/or other materials provided with the distribution.
     17 .\" 3. Neither the name of the University nor the names of its contributors
     18 .\"    may be used to endorse or promote products derived from this software
     19 .\"    without specific prior written permission.
     20 .\"
     21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
     22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
     23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
     24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
     25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
     26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
     27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
     29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
     30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
     31 .\" SUCH DAMAGE.
     32 .\"
     33 .\"	from: @(#)printf.1	5.11 (Berkeley) 7/24/91
     34 .\"
     35 .Dd $Mdocdate: May 13 2014 $
     36 .Dt PRINTF 1
     37 .Os
     38 .Sh NAME
     39 .Nm printf
     40 .Nd formatted output
     41 .Sh SYNOPSIS
     42 .Nm printf
     43 .Ar format
     44 .Op Ar argument ...
     45 .Sh DESCRIPTION
     46 .Nm printf
     47 formats and prints its arguments, after the first, under control
     48 of the
     49 .Ar format .
     50 The
     51 .Ar format
     52 is a character string which contains three types of objects: plain characters,
     53 which are simply copied to standard output, character escape sequences which
     54 are converted and copied to the standard output, and format specifications,
     55 each of which causes printing of the next successive
     56 .Ar argument .
     57 .Pp
     58 The arguments after the first are treated as strings
     59 if the corresponding format is
     60 .Cm b ,
     61 .Cm c
     62 or
     63 .Cm s ;
     64 otherwise it is evaluated as a C constant, with the following extensions:
     65 .Bl -bullet -offset indent
     66 .It
     67 A leading plus or minus sign is allowed.
     68 .It
     69 If the leading character is a single or double quote, the value is the
     70 .Tn ASCII
     71 code of the next character.
     72 .El
     73 .Pp
     74 The format string is reused as often as necessary to satisfy the arguments.
     75 Any extra format specifications are evaluated with zero or the null
     76 string.
     77 .Pp
     78 Character escape sequences are in backslash notation as defined in
     79 .St -ansiC .
     80 The characters and their meanings are as follows:
     81 .Pp
     82 .Bl -tag -width Ds -offset indent -compact
     83 .It Cm \ee
     84 Write an <escape> character.
     85 .It Cm \ea
     86 Write a <bell> character.
     87 .It Cm \eb
     88 Write a <backspace> character.
     89 .It Cm \ef
     90 Write a <form-feed> character.
     91 .It Cm \en
     92 Write a <new-line> character.
     93 .It Cm \er
     94 Write a <carriage return> character.
     95 .It Cm \et
     96 Write a <tab> character.
     97 .It Cm \ev
     98 Write a <vertical tab> character.
     99 .It Cm \e\'
    100 Write a <single quote> character.
    101 .It Cm \e\e
    102 Write a backslash character.
    103 .It Cm \e Ns Ar num
    104 Write an 8-bit character whose
    105 .Tn ASCII
    106 value is the 1-, 2-, or 3-digit
    107 octal number
    108 .Ar num .
    109 .El
    110 .Pp
    111 Each format specification is introduced by the percent
    112 .Pq Sq \&%
    113 character.
    114 The remainder of the format specifiers include,
    115 in the following order:
    116 .Bl -tag -width Ds
    117 .It "Zero or more of the following flags:"
    118 .Bl -tag -width Ds
    119 .It Cm #
    120 Specifies that the value should be printed in an
    121 .Dq alternate form .
    122 For the
    123 .Cm o
    124 format the precision of the number is increased to force the first
    125 character of the output string to a zero.
    126 For the
    127 .Cm x
    128 .Pq Cm X
    129 format, a non-zero result has the string
    130 .Li 0x
    131 .Pq Li 0X
    132 prepended to it.
    133 For
    134 .Cm a ,
    135 .Cm A ,
    136 .Cm e ,
    137 .Cm E ,
    138 .Cm f ,
    139 .Cm F ,
    140 .Cm g ,
    141 and
    142 .Cm G
    143 formats, the result will always contain a decimal point, even if no
    144 digits follow the point (normally, a decimal point only appears in the
    145 results of those formats if a digit follows the decimal point).
    146 For
    147 .Cm g
    148 and
    149 .Cm G
    150 formats, trailing zeros are not removed from the result as they
    151 would otherwise be.
    152 For all other formats, behaviour is undefined.
    153 .It Cm \&\-
    154 Specifies the
    155 .Em left adjustment
    156 of the output in the indicated field.
    157 .It Cm \&+
    158 Specifies that there should always be
    159 a sign placed before the number when using signed formats.
    160 .It Sq \&\ \&
    161 A space specifies that a blank should be left before a positive number
    162 for a signed format.
    163 A
    164 .Ql +
    165 overrides a space if both are used.
    166 .It Cm \&0
    167 A zero character specifies that zero-padding should be used
    168 rather than blank-padding.
    169 This flag is ignored if used with a precision
    170 specifier and any of the
    171 .Cm d , i , o , u ,
    172 or
    173 .Cm x
    174 .Pq Cm X
    175 formats.
    176 A
    177 .Ql \&-
    178 overrides a
    179 .Ql \&0
    180 if both are used.
    181 .El
    182 .It "Field Width:"
    183 An optional digit string specifying a
    184 .Em field width ;
    185 if the output string has fewer characters than the field width it will
    186 be blank-padded on the left (or right, if the left-adjustment indicator
    187 has been given) to make up the field width (note that a leading zero
    188 is a flag, but an embedded zero is part of a field width).
    189 .It Precision:
    190 An optional period
    191 .Pq Sq \&. ,
    192 followed by an optional digit string giving a
    193 .Em precision
    194 which specifies the number of digits to appear after the decimal point,
    195 for
    196 .Cm e
    197 and
    198 .Cm f
    199 formats, or the maximum number of characters to be printed
    200 from a string; if the digit string is missing, the precision is treated
    201 as zero.
    202 .It Format:
    203 A character which indicates the type of format to use (one of
    204 .Cm diouxXfFeEgGaAbcs ) .
    205 .El
    206 .Pp
    207 A field width or precision may be
    208 .Ql \&*
    209 instead of a digit string.
    210 In this case an
    211 .Ar argument
    212 supplies the field width or precision.
    213 .Pp
    214 The format characters and their meanings are:
    215 .Bl -tag -width Fl
    216 .It Cm diouXx
    217 The
    218 .Ar argument
    219 is printed as a signed decimal
    220 .Pq Cm d No or Cm i ,
    221 unsigned octal, unsigned decimal,
    222 or unsigned hexadecimal
    223 .Pq Cm x No or Cm X ,
    224 respectively.
    225 .It Cm fF
    226 The
    227 .Ar argument
    228 is printed in the style
    229 .Sm off
    230 .Pf [\-]ddd Cm \&. No ddd
    231 .Sm on
    232 where the number of d's
    233 after the decimal point is equal to the precision specification for
    234 the argument.
    235 If the precision is missing, 6 digits are given; if the precision
    236 is explicitly 0, no digits and no decimal point are printed.
    237 .Pp
    238 If the argument is infinity, it will be converted to [-]inf
    239 .Pq Cm f
    240 or [-]INF
    241 .Pq Cm F ,
    242 respectively.
    243 If the argument is not-a-number (NaN), it will be converted to
    244 [-]nan
    245 .Pq Cm f
    246 or [-]NAN
    247 .Pq Cm F ,
    248 respectively.
    249 .It Cm eE
    250 The
    251 .Ar argument
    252 is printed in the style
    253 .Sm off
    254 .Pf [\-]d Cm \&. No ddd Cm e No \*(Pmdd
    255 .Sm on
    256 where there
    257 is one digit before the decimal point and the number after is equal to
    258 the precision specification for the argument; when the precision is
    259 missing, 6 digits are produced.
    260 An upper-case
    261 .Sq E
    262 is used for an
    263 .Cm E
    264 format.
    265 .Pp
    266 If the argument is infinity, it will be converted to [-]inf
    267 .Pq Cm e
    268 or [-]INF
    269 .Pq Cm E ,
    270 respectively.
    271 If the argument is not-a-number (NaN), it will be converted to
    272 [-]nan
    273 .Pq Cm e
    274 or [-]NAN
    275 .Pq Cm E ,
    276 respectively.
    277 .It Cm gG
    278 The
    279 .Ar argument
    280 is printed in style
    281 .Cm f
    282 or in style
    283 .Cm e
    284 .Pq Cm E
    285 whichever gives full precision in minimum space.
    286 .Pp
    287 If the argument is infinity, it will be converted to [-]inf
    288 .Pq Cm g
    289 or [-]INF
    290 .Pq Cm G ,
    291 respectively.
    292 If the argument is not-a-number (NaN), it will be converted to
    293 [-]nan
    294 .Pq Cm g
    295 or [-]NAN
    296 .Pq Cm G ,
    297 respectively.
    298 .It Cm aA
    299 The
    300 .Ar argument
    301 is printed in style
    302 .Sm off
    303 .Pf [\-]0xh Cm \&. No hhh Cm p No [\*(Pm]d
    304 .Sm on
    305 where there is one digit before the hexadecimal point and the number
    306 after is equal to the precision specification for the argument.
    307 When the precision is missing, enough digits are produced to convey
    308 the argument's exact double-precision floating-point representation.
    309 .Pp
    310 If the argument is infinity, it will be converted to [-]inf
    311 .Pq Cm a
    312 or [-]INF
    313 .Pq Cm A ,
    314 respectively.
    315 If the argument is not-a-number (NaN), it will be converted to
    316 [-]nan
    317 .Pq Cm a
    318 or [-]NAN
    319 .Pq Cm A ,
    320 respectively.
    321 .It Cm b
    322 Characters from the string
    323 .Ar argument
    324 are printed with backslash-escape sequences expanded.
    325 .It Cm c
    326 The first character of
    327 .Ar argument
    328 is printed.
    329 .It Cm s
    330 Characters from the string
    331 .Ar argument
    332 are printed until the end is reached or until the number of characters
    333 indicated by the precision specification is reached; however if the
    334 precision is 0 or missing, all characters in the string are printed.
    335 .It Cm \&%
    336 Print a
    337 .Ql \&% ;
    338 no argument is used.
    339 .El
    340 .Pp
    341 In no case does a non-existent or small field width cause truncation of
    342 a field; padding takes place only if the specified field width exceeds
    343 the actual width.
    344 .Sh EXIT STATUS
    345 .Ex -std printf
    346 .Sh EXAMPLES
    347 Convert a hexadecimal value to decimal and print it out:
    348 .Pp
    349 .D1 Ic $ printf \&"%d\en\&" 0x20
    350 .Pp
    351 Print the decimal representation of the character 'a' (see
    352 .Xr ascii 7 ) :
    353 .Pp
    354 .D1 Ic $ printf \&"%d\en\&" \e'a
    355 .Sh SEE ALSO
    356 .Xr echo 1 ,
    357 .Xr printf 3
    358 .Sh STANDARDS
    359 The
    360 .Nm
    361 utility is compliant with the
    362 .St -p1003.1-2008
    363 specification.
    364 .Pp
    365 The escape sequences \ee and \e' are extensions to that specification.
    366 .Sh HISTORY
    367 The
    368 .Nm
    369 command appeared in
    370 .Bx 4.3 Reno .
    371 .Sh CAVEATS
    372 It is important never to pass a string with user-supplied data as a
    373 format without using
    374 .Ql %s .
    375 An attacker can put format specifiers in the string to mangle your stack,
    376 leading to a possible security hole.
    377 .Pp
    378 Always be sure to use the proper secure idiom:
    379 .Bd -literal -offset indent
    380 printf "%s" "$STRING"
    381 .Ed
    382 .Sh BUGS
    383 Since arguments are translated from
    384 .Tn ASCII
    385 to floating-point, and
    386 then back again, floating-point precision may be lost.