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