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)