usr.bin/printf/printf.1

   1 .\"     $NetBSD: printf.1,v 1.22 2008/09/01 09:20:41 dholland Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1990, 1993
   4 .\"     The Regents of the University of California.  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 May 6, 2008
  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
  89 .Aq escape
  90 character.
  91 .It Cm \ea
  92 Write a
  93 .Aq bell
  94 character.
  95 .It Cm \eb
  96 Write a
  97 .Aq backspace
  98 character.
  99 .It Cm \ef
 100 Write a
 101 .Aq form-feed
 102 character.
 103 .It Cm \en
 104 Write a
 105 .Aq new-line
 106 character.
 107 .It Cm \er
 108 Write a
 109 .Aq carriage return
 110 character.
 111 .It Cm \et
 112 Write a
 113 .Aq tab
 114 character.
 115 .It Cm \ev
 116 Write a
 117 .Aq vertical tab
 118 character.
 119 .It Cm \e\'
 120 Write a
 121 .Aq single quote
 122 character.
 123 .It Cm \e"
 124 Write a
 125 .Aq double quote
 126 character.
 127 .It Cm \e\e
 128 Write a backslash character.
 129 .It Cm \e Ns Ar num
 130 Write an 8\-bit character whose
 131 .Tn ASCII
 132 value is the 1\-, 2\-, or 3\-digit octal number
 133 .Ar num .
 134 .It Cm \ex Ns Ar xx
 135 Write an 8\-bit character whose
 136 .Tn ASCII
 137 value is the 1\- or 2\-digit hexadecimal number
 138 .Ar xx .
 139 .El
 140 .Pp
 141 Each format specification is introduced by the percent character
 142 .Pq Dq \&% .
 143 The remainder of the format specification includes,
 144 in the following order:
 145 .Bl -tag -width Ds
 146 .It Zero or more of the following flags :
 147 .Bl -tag -width Ds
 148 .It Cm #
 149 A
 150 .Sq #
 151 character specifying that the value should be printed in an
 152 .Dq alternative form .
 153 For
 154 .Cm b ,
 155 .Cm c ,
 156 .Cm d ,
 157 and
 158 .Cm s
 159 formats, this option has no effect.
 160 For the
 161 .Cm o
 162 format the precision of the number is increased to force the first
 163 character of the output string to a zero.
 164 For the
 165 .Cm x
 166 .Pq Cm X
 167 format, a non-zero result has the string
 168 .Li 0x
 169 .Pq Li 0X
 170 prepended to it.
 171 For
 172 .Cm e ,
 173 .Cm E ,
 174 .Cm f ,
 175 .Cm g ,
 176 and
 177 .Cm G
 178 formats, the result will always contain a decimal point, even if no
 179 digits follow the point (normally, a decimal point only appears in the
 180 results of those formats if a digit follows the decimal point).
 181 For
 182 .Cm g
 183 and
 184 .Cm G
 185 formats, trailing zeros are not removed from the result as they
 186 would otherwise be.
 187 .\" I turned this off - decided it isn't a valid use of '#'
 188 .\" For the
 189 .\" .Cm B
 190 .\" format, backslash-escape sequences are expanded first;
 191 .It Cm \&\-
 192 A minus sign
 193 .Sq \-
 194 which specifies
 195 .Em left adjustment
 196 of the output in the indicated field;
 197 .It Cm \&+
 198 A
 199 .Sq \&+
 200 character specifying that there should always be
 201 a sign placed before the number when using signed formats.
 202 .It Sq \&\ \&
 203 A space specifying that a blank should be left before a positive number
 204 for a signed format.
 205 A
 206 .Sq \&+
 207 overrides a space if both are used;
 208 .It Cm \&0
 209 A zero `0' character indicating that zero-padding should be used
 210 rather than blank-padding.
 211 A
 212 .Sq \-
 213 overrides a
 214 .Sq \&0
 215 if both are used;
 216 .El
 217 .It Field Width :
 218 An optional digit string specifying a
 219 .Em field width ;
 220 if the output string has fewer characters than the field width it will
 221 be blank-padded on the left (or right, if the left-adjustment indicator
 222 has been given) to make up the field width (note that a leading zero
 223 is a flag, but an embedded zero is part of a field width);
 224 .It Precision :
 225 An optional period,
 226 .Sq Cm \&. ,
 227 followed by an optional digit string giving a
 228 .Em precision
 229 which specifies the number of digits to appear after the decimal point,
 230 for
 231 .Cm e
 232 and
 233 .Cm f
 234 formats, or the maximum number of characters to be printed
 235 from a string
 236 .Sm off
 237 .Pf ( Cm b ,
 238 .Sm on
 239 .Cm B ,
 240 and
 241 .Cm s
 242 formats); if the digit string is missing, the precision is treated
 243 as zero;
 244 .It Format :
 245 A character which indicates the type of format to use (one of
 246 .Cm diouxXfwEgGbBcs ) .
 247 .El
 248 .Pp
 249 A field width or precision may be
 250 .Sq Cm \&*
 251 instead of a digit string.
 252 In this case an
 253 .Ar argument
 254 supplies the field width or precision.
 255 .Pp
 256 The format characters and their meanings are:
 257 .Bl -tag -width Fl
 258 .It Cm diouXx
 259 The
 260 .Ar argument
 261 is printed as a signed decimal (d or i), unsigned octal, unsigned decimal,
 262 or unsigned hexadecimal (X or x), respectively.
 263 .It Cm f
 264 The
 265 .Ar argument
 266 is printed in the style
 267 .Sm off
 268 .Pf [\-]ddd Cm \&. No ddd
 269 .Sm on
 270 where the number of d's
 271 after the decimal point is equal to the precision specification for
 272 the argument.
 273 If the precision is missing, 6 digits are given; if the precision
 274 is explicitly 0, no digits and no decimal point are printed.
 275 .It Cm eE
 276 The
 277 .Ar argument
 278 is printed in the style
 279 .Sm off
 280 .Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
 281 .Sm on
 282 where there
 283 is one digit before the decimal point and the number after is equal to
 284 the precision specification for the argument; when the precision is
 285 missing, 6 digits are produced.
 286 An upper-case E is used for an
 287 .Sq E
 288 format.
 289 .It Cm gG
 290 The
 291 .Ar argument
 292 is printed in style
 293 .Cm f
 294 or in style
 295 .Cm e
 296 .Pq Cm E
 297 whichever gives full precision in minimum space.
 298 .It Cm b
 299 Characters from the string
 300 .Ar argument
 301 are printed with backslash-escape sequences expanded.
 302 .Pp
 303 The following additional backslash-escape sequences are supported:
 304 .Bl -tag -width Ds
 305 .It Cm \ec
 306 Causes
 307 .Nm
 308 to ignore any remaining characters in the string operand containing it,
 309 any remaining string operands, and any additional characters in
 310 the format operand.
 311 .It Cm \e0 Ns Ar num
 312 Write an 8\-bit character whose
 313 .Tn ASCII
 314 value is the 1\-, 2\-, or 3\-digit
 315 octal number
 316 .Ar num .
 317 .It Cm \e^ Ns Ar c
 318 Write the control character
 319 .Ar c .
 320 Generates characters `\e000' through `\e037`, and `\e177' (from `\e^?').
 321 .It Cm \eM\- Ns Ar c
 322 Write the character
 323 .Ar c
 324 with the 8th bit set.
 325 Generates characters `\e241' through `\e376`.
 326 .It Cm \eM^ Ns Ar c
 327 Write the control character
 328 .Ar c
 329 with the 8th bit set.
 330 Generates characters `\e200' through `\e237`, and `\e377' (from `\eM^?').
 331 .El
 332 .It Cm B
 333 Characters from the string
 334 .Ar argument
 335 are printed with unprintable characters backslash-escaped using the
 336 .Sm off
 337 .Pf ` Cm \e Ar c No ',
 338 .Pf ` Cm \e^ Ar c No ',
 339 .Pf ` Cm \eM\- Ar c No '
 340 or
 341 .Pf ` Cm \eM^ Ar c No ',
 342 .Sm on
 343 formats described above.
 344 .It Cm c
 345 The first character of
 346 .Ar argument
 347 is printed.
 348 .It Cm s
 349 Characters from the string
 350 .Ar argument
 351 are printed until the end is reached or until the number of characters
 352 indicated by the precision specification is reached; if the
 353 precision is omitted, all characters in the string are printed.
 354 .It Cm \&%
 355 Print a `%'; no argument is used.
 356 .El
 357 .Pp
 358 In no case does a non-existent or small field width cause truncation of
 359 a field; padding takes place only if the specified field width exceeds
 360 the actual width.
 361 .Sh EXIT STATUS
 362 .Nm
 363 exits 0 on success, 1 on failure.
 364 .Sh SEE ALSO
 365 .Xr echo 1 ,
 366 .Xr printf 3 ,
 367 .Xr vis 3 ,
 368 .Xr printf 9
 369 .Sh STANDARDS
 370 The
 371 .Nm
 372 utility conforms to
 373 .St -p1003.1-2001 .
 374 .Pp
 375 Support for the floating point formats and `*' as a field width and precision
 376 are optional in POSIX.
 377 .Pp
 378 The behaviour of the %B format and the \e', \e", \exxx, \ee and
 379 \e[M][\-|^]c escape sequences are undefined in POSIX.
 380 .Sh BUGS
 381 Since the floating point numbers are translated from
 382 .Tn ASCII
 383 to floating-point and
 384 then back again, floating-point precision may be lost.
 385 .Pp
 386 Hexadecimal character constants are restricted to, and should be specified
 387 as, two character constants.
 388 This is contrary to the ISO C standard but
 389 does guarantee detection of the end of the constant.
 390 .Sh NOTES
 391 All formats which treat the
 392 .Ar argument
 393 as a number first convert the
 394 .Ar argument
 395 from its external representation as a character string
 396 to an internal numeric representation, and then apply the
 397 format to the internal numeric representation, producing
 398 another external character string representation.
 399 One might expect the
 400 .Cm \&%c
 401 format to do likewise, but in fact it does not.
 402 .Pp
 403 To convert a string representation of a decimal, octal, or hexadecimal
 404 number into the corresponding character, two nested
 405 .Nm
 406 invocations may be used, in which the inner invocation
 407 converts the input to an octal string, and the outer
 408 invocation uses the octal string as part of a format.
 409 For example, the following command outputs the character whose code
 410 is 0x0A, which is a newline in ASCII:
 411 .Pp
 412 .Dl printf \&"$(printf \&"\e\e%o" \&"0x0A")"