Magellan Linux

  • Back to homepage
    • /[magellan-source]/trunk/mkinitrd-magellan/klibc/usr/dash/bltin/printf.1

    Contents of /trunk/mkinitrd-magellan/klibc/usr/dash/bltin/printf.1

    Parent Directory Parent Directory | Revision Log Revision Log

    Revision 532 - (show annotations) (download)
    Sat Sep 1 22:45:15 2007 UTC (16 years, 8 months ago) by niro
    File size: 10069 byte(s) 
    -import if magellan mkinitrd; it is a fork of redhats mkinitrd-5.0.8 with all magellan patches and features; deprecates magellan-src/mkinitrd
    1 .\" Copyright (c) 1989, 1990, 1993
    2 .\" The Regents of the University of California. All rights reserved.
    3 .\" Copyright (c) 1997-2005
    4 .\" Herbert Xu <herbert@gondor.apana.org.au>. 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 8.1 (Berkeley) 6/6/93
    34 .\"
    35 .Dd November 5, 1993
    36 .Dt PRINTF 1
    37 .Os
    38 .Sh NAME
    39 .Nm printf
    40 .Nd formatted output
    41 .Sh SYNOPSIS
    42 .Nm
    43 .Ar format
    44 .Op Ar arguments ...
    45 .Sh DESCRIPTION
    46 .Nm
    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
    59 .Ar arguments
    60 after the first are treated as strings if the corresponding format is
    61 either
    62 .Cm b ,
    63 .Cm B ,
    64 .Cm c
    65 or
    66 .Cm s ;
    67 otherwise it is evaluated as a C constant, with the following extensions:
    68 .Pp
    69 .Bl -bullet -offset indent -compact
    70 .It
    71 A leading plus or minus sign is allowed.
    72 .It
    73 If the leading character is a single or double quote, the value is the
    74 .Tn ASCII
    75 code of the next character.
    76 .El
    77 .Pp
    78 The format string is reused as often as necessary to satisfy the
    79 .Ar arguments .
    80 Any extra format specifications are evaluated with zero or the null
    81 string.
    82 .Pp
    83 Character escape sequences are in backslash notation as defined in
    84 .St -ansiC .
    85 The characters and their meanings are as follows:
    86 .Bl -tag -width Ds -offset indent
    87 .It Cm \ee
    88 Write an \*[Lt]escape\*[Gt] character.
    89 .It Cm \ea
    90 Write a \*[Lt]bell\*[Gt] character.
    91 .It Cm \eb
    92 Write a \*[Lt]backspace\*[Gt] character.
    93 .It Cm \ef
    94 Write a \*[Lt]form-feed\*[Gt] character.
    95 .It Cm \en
    96 Write a \*[Lt]new-line\*[Gt] character.
    97 .It Cm \er
    98 Write a \*[Lt]carriage return\*[Gt] character.
    99 .It Cm \et
    100 Write a \*[Lt]tab\*[Gt] character.
    101 .It Cm \ev
    102 Write a \*[Lt]vertical tab\*[Gt] character.
    103 .It Cm \e\'
    104 Write a \*[Lt]single quote\*[Gt] character.
    105 .It Cm \e"
    106 Write a \*[Lt]double quote\*[Gt] character.
    107 .It Cm \e\e
    108 Write a backslash character.
    109 .It Cm \e Ns Ar num
    110 Write an 8\-bit character whose
    111 .Tn ASCII
    112 value is the 1\-, 2\-, or 3\-digit octal number
    113 .Ar num .
    114 .It Cm \ex Ns Ar xx
    115 Write an 8\-bit character whose
    116 .Tn ASCII
    117 value is the 1\- or 2\-digit hexadecimal number
    118 .Ar xx .
    119 .El
    120 .Pp
    121 Each format specification is introduced by the percent character
    122 (``%'').
    123 The remainder of the format specification includes,
    124 in the following order:
    125 .Bl -tag -width Ds
    126 .It "Zero or more of the following flags:"
    127 .Bl -tag -width Ds
    128 .It Cm #
    129 A `#' character
    130 specifying that the value should be printed in an ``alternative form''.
    131 For
    132 .Cm b ,
    133 .Cm c ,
    134 .Cm d ,
    135 and
    136 .Cm s
    137 formats, this option has no effect.
    138 For the
    139 .Cm o
    140 format the precision of the number is increased to force the first
    141 character of the output string to a zero.
    142 For the
    143 .Cm x
    144 .Pq Cm X
    145 format, a non-zero result has the string
    146 .Li 0x
    147 .Pq Li 0X
    148 prepended to it.
    149 For
    150 .Cm e ,
    151 .Cm E ,
    152 .Cm f ,
    153 .Cm g ,
    154 and
    155 .Cm G
    156 formats, the result will always contain a decimal point, even if no
    157 digits follow the point (normally, a decimal point only appears in the
    158 results of those formats if a digit follows the decimal point).
    159 For
    160 .Cm g
    161 and
    162 .Cm G
    163 formats, trailing zeros are not removed from the result as they
    164 would otherwise be.
    165 .\" I turned this off - decided it isn't a valid use of '#'
    166 .\" For the
    167 .\" .Cm B
    168 .\" format, backslash-escape sequences are expanded first;
    169 .It Cm \&\-
    170 A minus sign `\-' which specifies
    171 .Em left adjustment
    172 of the output in the indicated field;
    173 .It Cm \&+
    174 A `+' character specifying that there should always be
    175 a sign placed before the number when using signed formats.
    176 .It Sq \&\ \&
    177 A space specifying that a blank should be left before a positive number
    178 for a signed format.
    179 A `+' overrides a space if both are used;
    180 .It Cm \&0
    181 A zero `0' character indicating that zero-padding should be used
    182 rather than blank-padding.
    183 A `\-' overrides a `0' if both are used;
    184 .El
    185 .It "Field Width:"
    186 An optional digit string specifying a
    187 .Em field width ;
    188 if the output string has fewer characters than the field width it will
    189 be blank-padded on the left (or right, if the left-adjustment indicator
    190 has been given) to make up the field width (note that a leading zero
    191 is a flag, but an embedded zero is part of a field width);
    192 .It Precision :
    193 An optional period,
    194 .Sq Cm \&.\& ,
    195 followed by an optional digit string giving a
    196 .Em precision
    197 which specifies the number of digits to appear after the decimal point,
    198 for
    199 .Cm e
    200 and
    201 .Cm f
    202 formats, or the maximum number of characters to be printed
    203 from a string
    204 .Sm off
    205 .Pf ( Cm b No ,
    206 .Sm on
    207 .Cm B
    208 and
    209 .Cm s
    210 formats); if the digit string is missing, the precision is treated
    211 as zero;
    212 .It Format :
    213 A character which indicates the type of format to use (one of
    214 .Cm diouxXfwEgGbBcs ) .
    215 .El
    216 .Pp
    217 A field width or precision may be
    218 .Sq Cm \&*
    219 instead of a digit string.
    220 In this case an
    221 .Ar argument
    222 supplies the field width or precision.
    223 .Pp
    224 The format characters and their meanings are:
    225 .Bl -tag -width Fl
    226 .It Cm diouXx
    227 The
    228 .Ar argument
    229 is printed as a signed decimal (d or i), unsigned octal, unsigned decimal,
    230 or unsigned hexadecimal (X or x), respectively.
    231 .It Cm f
    232 The
    233 .Ar argument
    234 is printed in the style
    235 .Sm off
    236 .Pf [\-]ddd Cm \&. No ddd
    237 .Sm on
    238 where the number of d's
    239 after the decimal point is equal to the precision specification for
    240 the argument.
    241 If the precision is missing, 6 digits are given; if the precision
    242 is explicitly 0, no digits and no decimal point are printed.
    243 .It Cm eE
    244 The
    245 .Ar argument
    246 is printed in the style
    247 .Sm off
    248 .Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
    249 .Sm on
    250 where there
    251 is one digit before the decimal point and the number after is equal to
    252 the precision specification for the argument; when the precision is
    253 missing, 6 digits are produced.
    254 An upper-case E is used for an `E' format.
    255 .It Cm gG
    256 The
    257 .Ar argument
    258 is printed in style
    259 .Cm f
    260 or in style
    261 .Cm e
    262 .Pq Cm E
    263 whichever gives full precision in minimum space.
    264 .It Cm b
    265 Characters from the string
    266 .Ar argument
    267 are printed with backslash-escape sequences expanded.
    268 .br
    269 The following additional backslash-escape sequences are supported:
    270 .Bl -tag -width Ds
    271 .It Cm \ec
    272 Causes
    273 .Nm
    274 to ignore any remaining characters in the string operand containing it,
    275 any remaining string operands, and any additional characters in
    276 the format operand.
    277 .It Cm \e0 Ns Ar num
    278 Write an 8\-bit character whose
    279 .Tn ASCII
    280 value is the 1\-, 2\-, or 3\-digit
    281 octal number
    282 .Ar num .
    283 .It Cm \e^ Ns Ar c
    284 Write the control character
    285 .Ar c .
    286 Generates characters `\e000' through `\e037`, and `\e177' (from `\e^?').
    287 .It Cm \eM\- Ns Ar c
    288 Write the character
    289 .Ar c
    290 with the 8th bit set.
    291 Generates characters `\e241' through `\e376`.
    292 .It Cm \eM^ Ns Ar c
    293 Write the control character
    294 .Ar c
    295 with the 8th bit set.
    296 Generates characters `\e000' through `\e037`, and `\e177' (from `\eM^?').
    297 .El
    298 .It Cm B
    299 Characters from the string
    300 .Ar argument
    301 are printed with unprintable characters backslash-escaped using the
    302 .Sm off
    303 .Pf ` Cm \e Ar c No ',
    304 .Pf ` Cm \e^ Ar c No ',
    305 .Pf ` Cm \eM\- Ar c No '
    306 or
    307 .Pf ` Cm \eM^ Ar c No ',
    308 .Sm on
    309 formats described above.
    310 .It Cm c
    311 The first character of
    312 .Ar argument
    313 is printed.
    314 .It Cm s
    315 Characters from the string
    316 .Ar argument
    317 are printed until the end is reached or until the number of characters
    318 indicated by the precision specification is reached; if the
    319 precision is omitted, all characters in the string are printed.
    320 .It Cm \&%
    321 Print a `%'; no argument is used.
    322 .El
    323 .Pp
    324 In no case does a non-existent or small field width cause truncation of
    325 a field; padding takes place only if the specified field width exceeds
    326 the actual width.
    327 .Sh EXIT STATUS
    328 .Nm
    329 exits 0 on success, 1 on failure.
    330 .Sh SEE ALSO
    331 .Xr echo 1 ,
    332 .Xr printf 3 ,
    333 .Xr printf 9
    334 .Xr vis 3
    335 .Sh STANDARDS
    336 The
    337 .Nm
    338 utility conforms to
    339 .St -p1003.1-2001 .
    340 .Pp
    341 Support for the floating point formats and `*' as a field width and precision
    342 are optional in POSIX.
    343 .Pp
    344 The behaviour of the %B format and the \e', \e", \exxx, \ee and
    345 \e[M][\-|^]c escape sequences are undefined in POSIX.
    346 .Sh BUGS
    347 Since the floating point numbers are translated from
    348 .Tn ASCII
    349 to floating-point and
    350 then back again, floating-point precision may be lost.
    351 .Pp
    352 Hexadecimal character constants are restricted to, and should be specified
    353 as, two character constants. This is contrary to the ISO C standard but
    354 does guarantee detection of the end of the constant.