usr.bin/printf/printf.1

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