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 .\" 4. 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$
  33 .\"
  34 .Dd May 28, 2011
  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 character code of the next character.
  72 .El
  73 .Pp
  74 The format string is reused as often as necessary to satisfy the
  75 .Ar arguments .
  76 Any extra format specifications are evaluated with zero or the null
  77 string.
  78 .Pp
  79 Character escape sequences are in backslash notation as defined in the
  80 .St -ansiC ,
  81 with extensions.
  82 The characters and their meanings
  83 are as follows:
  84 .Pp
  85 .Bl -tag -width Ds -offset indent -compact
  86 .It Cm \ea
  87 Write a <bell> character.
  88 .It Cm \eb
  89 Write a <backspace> character.
  90 .It Cm \ec
  91 Ignore remaining characters in this string.
  92 .It Cm \ef
  93 Write a <form-feed> character.
  94 .It Cm \en
  95 Write a <new-line> character.
  96 .It Cm \er
  97 Write a <carriage return> character.
  98 .It Cm \et
  99 Write a <tab> character.
 100 .It Cm \ev
 101 Write a <vertical tab> character.
 102 .It Cm \e\'
 103 Write a <single quote> character.
 104 .It Cm \e\e
 105 Write a backslash character.
 106 .It Cm \e Ns Ar num
 107 Write a byte whose
 108 value is the 1-, 2-, or 3-digit
 109 octal number
 110 .Ar num .
 111 Multibyte characters can be constructed using multiple
 112 .Cm \e Ns Ar num
 113 sequences.
 114 .El
 115 .Pp
 116 Each format specification is introduced by the percent character
 117 (``%'').
 118 The remainder of the format specification includes,
 119 in the following order:
 120 .Bl -tag -width Ds
 121 .It "Zero or more of the following flags:"
 122 .Bl -tag -width Ds
 123 .It Cm #
 124 A `#' character
 125 specifying that the value should be printed in an ``alternate form''.
 126 For
 127 .Cm b , c , d , s
 128 and
 129 .Cm u
 130 formats, this option has no effect.
 131 For the
 132 .Cm o
 133 formats the precision of the number is increased to force the first
 134 character of the output string to a zero.
 135 For the
 136 .Cm x
 137 .Pq Cm X
 138 format, a non-zero result has the string
 139 .Li 0x
 140 .Pq Li 0X
 141 prepended to it.
 142 For
 143 .Cm a , A , e , E , f , F , g
 144 and
 145 .Cm G
 146 formats, the result will always contain a decimal point, even if no
 147 digits follow the point (normally, a decimal point only appears in the
 148 results of those formats if a digit follows the decimal point).
 149 For
 150 .Cm g
 151 and
 152 .Cm G
 153 formats, trailing zeros are not removed from the result as they
 154 would otherwise be;
 155 .It Cm \&\-
 156 A minus sign `\-' which specifies
 157 .Em left adjustment
 158 of the output in the indicated field;
 159 .It Cm \&+
 160 A `+' character specifying that there should always be
 161 a sign placed before the number when using signed formats.
 162 .It Sq \&\ \&
 163 A space specifying that a blank should be left before a positive number
 164 for a signed format.
 165 A `+' overrides a space if both are used;
 166 .It Cm \&0
 167 A zero `0' character indicating that zero-padding should be used
 168 rather than blank-padding.
 169 A `\-' overrides a `0' if both are used;
 170 .El
 171 .It "Field Width:"
 172 An optional digit string specifying a
 173 .Em field width ;
 174 if the output string has fewer bytes than the field width it will
 175 be blank-padded on the left (or right, if the left-adjustment indicator
 176 has been given) to make up the field width (note that a leading zero
 177 is a flag, but an embedded zero is part of a field width);
 178 .It Precision:
 179 An optional period,
 180 .Sq Cm \&.\& ,
 181 followed by an optional digit string giving a
 182 .Em precision
 183 which specifies the number of digits to appear after the decimal point,
 184 for
 185 .Cm e
 186 and
 187 .Cm f
 188 formats, or the maximum number of bytes to be printed
 189 from a string; if the digit string is missing, the precision is treated
 190 as zero;
 191 .It Format:
 192 A character which indicates the type of format to use (one of
 193 .Cm diouxXfFeEgGaAcsb ) .
 194 The uppercase formats differ from their lowercase counterparts only in
 195 that the output of the former is entirely in uppercase.
 196 The floating-point format specifiers
 197 .Pq Cm fFeEgGaA
 198 may be prefixed by an
 199 .Cm L
 200 to request that additional precision be used, if available.
 201 .El
 202 .Pp
 203 A field width or precision may be
 204 .Sq Cm \&*
 205 instead of a digit string.
 206 In this case an
 207 .Ar argument
 208 supplies the field width or precision.
 209 .Pp
 210 The format characters and their meanings are:
 211 .Bl -tag -width Fl
 212 .It Cm diouXx
 213 The
 214 .Ar argument
 215 is printed as a signed decimal (d or i), unsigned octal, unsigned decimal,
 216 or unsigned hexadecimal (X or x), respectively.
 217 .It Cm fF
 218 The
 219 .Ar argument
 220 is printed in the style `[\-]ddd.ddd' where the number of d's
 221 after the decimal point is equal to the precision specification for
 222 the argument.
 223 If the precision is missing, 6 digits are given; if the precision
 224 is explicitly 0, no digits and no decimal point are printed.
 225 The values \*[If] and \*[Na] are printed as
 226 .Ql inf
 227 and
 228 .Ql nan ,
 229 respectively.
 230 .It Cm eE
 231 The
 232 .Ar argument
 233 is printed in the style
 234 .Cm e
 235 .Sm off
 236 .Sq Op - Ar d.ddd No \(+- Ar dd
 237 .Sm on
 238 where there
 239 is one digit before the decimal point and the number after is equal to
 240 the precision specification for the argument; when the precision is
 241 missing, 6 digits are produced.
 242 The values \*[If] and \*[Na] are printed as
 243 .Ql inf
 244 and
 245 .Ql nan ,
 246 respectively.
 247 .It Cm gG
 248 The
 249 .Ar argument
 250 is printed in style
 251 .Cm f
 252 .Pq Cm F
 253 or in style
 254 .Cm e
 255 .Pq Cm E
 256 whichever gives full precision in minimum space.
 257 .It Cm aA
 258 The
 259 .Ar argument
 260 is printed in style
 261 .Sm off
 262 .Sq Op - Ar h.hhh No \(+- Li p Ar d
 263 .Sm on
 264 where there is one digit before the hexadecimal point and the number
 265 after is equal to the precision specification for the argument;
 266 when the precision is missing, enough digits are produced to convey
 267 the argument's exact double-precision floating-point representation.
 268 The values \*[If] and \*[Na] are printed as
 269 .Ql inf
 270 and
 271 .Ql nan ,
 272 respectively.
 273 .It Cm c
 274 The first byte of
 275 .Ar argument
 276 is printed.
 277 .It Cm s
 278 Bytes from the string
 279 .Ar argument
 280 are printed until the end is reached or until the number of bytes
 281 indicated by the precision specification is reached; however if the
 282 precision is 0 or missing, the string is printed entirely.
 283 .It Cm b
 284 As for
 285 .Cm s ,
 286 but interpret character escapes in backslash notation in the string
 287 .Ar argument .
 288 The permitted escape sequences are slightly different in that
 289 octal escapes are
 290 .Cm \e0 Ns Ar num
 291 instead of
 292 .Cm \e Ns Ar num .
 293 .It Cm \&%
 294 Print a `%'; no argument is used.
 295 .El
 296 .Pp
 297 The decimal point
 298 character is defined in the program's locale (category
 299 .Dv LC_NUMERIC ) .
 300 .Pp
 301 In no case does a non-existent or small field width cause truncation of
 302 a field; padding takes place only if the specified field width exceeds
 303 the actual width.
 304 .Pp
 305 Some shells may provide a builtin
 306 .Nm
 307 command which is similar or identical to this utility.
 308 Consult the
 309 .Xr builtin 1
 310 manual page.
 311 .Sh EXIT STATUS
 312 .Ex -std
 313 .Sh COMPATIBILITY
 314 The traditional
 315 .Bx
 316 behavior of converting arguments of numeric formats not beginning
 317 with a digit to the
 318 .Tn ASCII
 319 code of the first character is not supported.
 320 .Sh SEE ALSO
 321 .Xr builtin 1 ,
 322 .Xr echo 1 ,
 323 .Xr sh 1 ,
 324 .Xr printf 3
 325 .Sh STANDARDS
 326 The
 327 .Nm
 328 command is expected to be compatible with the
 329 .St -p1003.2
 330 specification.
 331 .Sh HISTORY
 332 The
 333 .Nm
 334 command appeared in
 335 .Bx 4.3 Reno .
 336 It is modeled
 337 after the standard library function,
 338 .Xr printf 3 .
 339 .Sh CAVEATS
 340 .Tn ANSI
 341 hexadecimal character constants were deliberately not provided.
 342 .Pp
 343 Trying to print a dash ("-") as the first character causes
 344 .Nm
 345 to interpret the dash as a program argument.
 346 .Nm --
 347 must be used before
 348 .Ar format .
 349 .Pp
 350 If the locale contains multibyte characters
 351 (such as UTF-8),
 352 the
 353 .Cm c
 354 format and
 355 .Cm b
 356 and
 357 .Cm s
 358 formats with a precision
 359 may not operate as expected.
 360 .Sh BUGS
 361 Since the floating point numbers are translated from
 362 .Tn ASCII
 363 to floating-point and
 364 then back again, floating-point precision may be lost.
 365 (By default, the number is translated to an IEEE-754 double-precision
 366 value before being printed.
 367 The
 368 .Cm L
 369 modifier may produce additional precision, depending on the hardware platform.)
 370 .Pp
 371 The escape sequence \e000 is the string terminator.
 372 When present in the argument for the
 373 .Cm b
 374 format, the argument will be truncated at the \e000 character.
 375 .Pp
 376 Multibyte characters are not recognized in format strings (this is only
 377 a problem if
 378 .Ql %
 379 can appear inside a multibyte character).