hbase

heirloom base
git clone git://git.2f30.org/hbase
Log | Files | Refs | README

printf.1 (6103B)


      1 .\"
      2 .\" Copyright (c) 2005 Gunnar Ritter
      3 .\"
      4 .\" This software is provided 'as-is', without any express or implied
      5 .\" warranty. In no event will the authors be held liable for any damages
      6 .\" arising from the use of this software.
      7 .\"
      8 .\" Permission is granted to anyone to use this software for any purpose,
      9 .\" including commercial applications, and to alter it and redistribute
     10 .\" it freely, subject to the following restrictions:
     11 .\"
     12 .\" 1. The origin of this software must not be misrepresented; you must not
     13 .\"    claim that you wrote the original software. If you use this software
     14 .\"    in a product, an acknowledgment in the product documentation would be
     15 .\"    appreciated but is not required.
     16 .\"
     17 .\" 2. Altered source versions must be plainly marked as such, and must not be
     18 .\"    misrepresented as being the original software.
     19 .\"
     20 .\" 3. This notice may not be removed or altered from any source distribution.
     21 .\"
     22 .\" Sccsid @(#)printf.1	1.2 (gritter) 7/17/05
     23 .TH PRINTF 1 "7/17/05" "Heirloom Toolchest" "User Commands"
     24 .SH NAME
     25 printf \- print a text string
     26 .SH SYNOPSIS
     27 \fBprintf\fR \fIformat\fR [\fIargument\fR ...]
     28 .SH DESCRIPTION
     29 The
     30 .I printf
     31 command writes a string to standard output
     32 with a controlled
     33 .IR format .
     34 It is essentially a utility variant of the `C' language function
     35 .IR printf (3).
     36 .PP
     37 Most characters in the
     38 .I format
     39 string
     40 are simply copied.
     41 The only exceptions are the backslash `\e' and percent `%' characters.
     42 .PP
     43 The backslash `\e' character in the
     44 .I format
     45 string
     46 serves as an escape for the following character.
     47 The sequences
     48 `\ea' (alert),
     49 `\eb' (backspace),
     50 `\ef' (formfeed),
     51 `\en' (newline),
     52 `\er' (carriage return),
     53 `\et' (tabulator),
     54 and `\ev' (vertical tabulator)
     55 cause the corresponding control characters to be printed.
     56 The sequence `\e\fInnn\fR',
     57 where
     58 .I nnn
     59 is a one-, two-, or three-digit octal number,
     60 cause the character (byte) with the corresponding number
     61 to be printed.
     62 `\e\e' prints the backslash character itself.
     63 .PP
     64 The percent `%' character in the
     65 .I format
     66 string introduces a conversion specification
     67 consisting of up to five parts,
     68 of which the first four are optional:
     69 .TP 14
     70 .I position
     71 A positive decimal integer followed by a dollar `$' character
     72 that specifies the
     73 .I argument
     74 to be used instead of the next unused one
     75 for the following conversions.
     76 .TP 14
     77 .I flags
     78 Zero or more of
     79 .RS
     80 .PD 0
     81 .TP 8
     82 .B \-
     83 left-justify the field
     84 .TP 8
     85 .B +
     86 always include a sign when printing a number
     87 .TP
     88 <space>
     89 prefix the result by a space if there is no sign
     90 .TP 8
     91 .B #
     92 alternate format
     93 .TP 8
     94 .B 0
     95 pad numbers with leading zeros
     96 .PD
     97 .RE
     98 .TP 14
     99 .I field width
    100 A decimal number giving the minimum width of the output printed.
    101 The output is padded if necessary,
    102 as controlled by the flags described above.
    103 By default, no padding is performed.
    104 If the field width is `*',
    105 it is taken from the next unused
    106 .IR argument .
    107 .TP 14
    108 .I precision
    109 A dot `.',
    110 followed by a decimal number giving
    111 the minimum digits written for integer numeric conversions,
    112 the minumum digits after the radix character
    113 for floating-point numeric conversions,
    114 or maximum bytes written for string conversions.
    115 If the precisision is `.*',
    116 it is taken from the next unused
    117 .IR argument .
    118 .TP 14
    119 .I specifier
    120 A character controlling the type of the conversion performed:
    121 .RS
    122 .PD 0
    123 .TP 5
    124 .B s
    125 The next unused
    126 .I argument
    127 is written as a plain string.
    128 .TP 5
    129 .B b
    130 The next unused
    131 .I argument
    132 is written as a string containing escape sequences
    133 similar to those of
    134 .IR echo (1).
    135 The backslash sequences described above are supported,
    136 except that the octal number must be prefixed by a zero
    137 as in `\e0\fInnn\fR'.
    138 A `\ec' sequence causes
    139 .I printf
    140 to exit immediately when it is encountered.
    141 .TP 5
    142 .B c
    143 The first character (byte) of the next unused
    144 .I argument
    145 is written.
    146 Any following characters in this argument are ignored.
    147 .TP 5
    148 .BR d ", i
    149 The next unused
    150 .I argument
    151 is written as a signed decimal number.
    152 .TP 5
    153 .B o
    154 The next unused
    155 .I argument
    156 is written as an octal number.
    157 With the `#' flag,
    158 it is prefixed by `0'.
    159 .TP 5
    160 .B u
    161 The next unused
    162 .I argument
    163 is written as an unsigned decimal number.
    164 .TP 5
    165 .B x
    166 The next unused
    167 .I argument
    168 is written as a hexadecimal number,
    169 using lowercase characters.
    170 With the `#' flag,
    171 it is prefixed by `0x'.
    172 .TP 5
    173 .B X
    174 The next unused
    175 .I argument
    176 is written as a hexadecimal number,
    177 using uppercase characters.
    178 With the `#' flag,
    179 it is prefixed by `0X'.
    180 .TP 5
    181 .B f
    182 The next unused
    183 .I argument
    184 is written as a floating-point number
    185 in the style `[\-]\fInnn.nnn\fR'.
    186 .TP 5
    187 .B e
    188 The next unused
    189 .I argument
    190 is written as a floating-point number
    191 in the style `[\-]\fIn.nnn\fRe[+|\-]\fInn'.
    192 .TP 5
    193 .B E
    194 The next unused
    195 .I argument
    196 is written as a floating-point number
    197 in the style `[\-]\fIn.nnn\fRE[+|\-]\fInn'.
    198 .TP 5
    199 .B g
    200 The next unused
    201 .I argument
    202 is written as a floating-point number
    203 like an integer if there is no fractional part,
    204 as described for `f' if the exponent is small,
    205 or as described for `g' if the exponent is large.
    206 .TP 5
    207 .B G
    208 The next unused
    209 .I argument
    210 is written as a floating-point number
    211 like an integer if there is no fractional part,
    212 as described for `f' if the exponent is small,
    213 or as described for `G' if the exponent is large.
    214 .TP 5
    215 .B %
    216 A percent character is printed.
    217 No
    218 .I argument
    219 is consumed.
    220 .PD
    221 .RE
    222 .PP
    223 If the argument for the numeric specifiers starts with a
    224 single- or double quote (`'\fIc\fR' or `"\fIc\fR'),
    225 the numeric value of the following character (byte sequence)
    226 in the current character encoding is used.
    227 .PP
    228 If the
    229 .I format
    230 string consumes at least an
    231 .IR argument ,
    232 no format specification contains a
    233 .I position
    234 part,
    235 but there are still unused
    236 .I arguments
    237 after the entire format string has been evaluated once,
    238 it is evaluated repeatedly until all arguments are consumed.
    239 Missing
    240 .I arguments
    241 default to the empty string for string conversions,
    242 and to zero if a numeric value is expected.
    243 .SH "ENVIRONMENT VARIABLES"
    244 .TP
    245 .BR LANG ", " LC_ALL
    246 See
    247 .IR locale (7).
    248 .TP
    249 .B LC_CTYPE
    250 Determines the mapping of bytes to characters
    251 for `'\fIc\fR' and `"\fIc\fR'.
    252 .SH "SEE ALSO"
    253 echo(1),
    254 printf(3)