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