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.8.2.7 2002/07/15 07:37:49 keramida Exp $
  37 .\" $DragonFly: src/usr.bin/printf/printf.1,v 1.3 2005/08/05 17:50:50 swildner Exp $
  38 .\"
  39 .Dd June 6, 1993
  40 .Dt PRINTF 1
  41 .Os
  42 .Sh NAME
  43 .Nm printf
  44 .Nd formatted output
  45 .Sh SYNOPSIS
  46 .Nm
  47 .Ar format Op Ar arguments  ...
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 utility formats and prints its arguments, after the first, under control
  52 of the
  53 .Ar format  .
  54 The
  55 .Ar format
  56 is a character string which contains three types of objects: plain characters,
  57 which are simply copied to standard output, character escape sequences which
  58 are converted and copied to the standard output, and format specifications,
  59 each of which causes printing of the next successive
  60 .Ar argument  .
  61 .Pp
  62 The
  63 .Ar arguments
  64 after the first are treated as strings if the corresponding format is
  65 either
  66 .Cm c , b
  67 or
  68 .Cm s ;
  69 otherwise it is evaluated as a C constant, with the following extensions:
  70 .Pp
  71 .Bl -bullet -offset indent -compact
  72 .It
  73 A leading plus or minus sign is allowed.
  74 .It
  75 If the leading character is a single or double quote, the value is the
  76 .Tn ASCII
  77 code of the next character.
  78 .El
  79 .Pp
  80 The format string is reused as often as necessary to satisfy the
  81 .Ar arguments  .
  82 Any extra format specifications are evaluated with zero or the null
  83 string.
  84 .Pp
  85 Character escape sequences are in backslash notation as defined in the
  86 .St -ansiC ,
  87 with extensions.
  88 The characters and their meanings
  89 are as follows:
  90 .Pp
  91 .Bl -tag -width Ds -offset indent -compact
  92 .It Cm \ea
  93 Write a <bell> character.
  94 .It Cm \eb
  95 Write a <backspace> character.
  96 .It Cm \ec
  97 Ignore remaining characters in this string.
  98 .It Cm \ef
  99 Write a <form-feed> character.
 100 .It Cm \en
 101 Write a <new-line> character.
 102 .It Cm \er
 103 Write a <carriage return> character.
 104 .It Cm \et
 105 Write a <tab> character.
 106 .It Cm \ev
 107 Write a <vertical tab> character.
 108 .It Cm \e\'
 109 Write a <single quote> character.
 110 .It Cm \e\e
 111 Write a backslash character.
 112 .It Cm \e Ns Ar num
 113 .It Cm \e0 Ns Ar num
 114 Write an 8-bit character whose
 115 .Tn ASCII
 116 value is the 1-, 2-, or 3-digit
 117 octal number
 118 .Ar num .
 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.  For the
 136 .Cm o
 137 formats the precision of the number is increased to force the first
 138 character of the output string to a zero.  For the
 139 .Cm x
 140 .Pq Cm X
 141 format, a non-zero result has the string
 142 .Li 0x
 143 .Pq Li 0X
 144 prepended to it.  For
 145 .Cm e , E , f , g ,
 146 and
 147 .Cm G ,
 148 formats, the result will always contain a decimal point, even if no
 149 digits follow the point (normally, a decimal point only appears in the
 150 results of those formats if a digit follows the decimal point).  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.  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.  A `\-' overrides a `0' if both are used;
 169 .El
 170 .It "Field Width:"
 171 An optional digit string specifying a
 172 .Em field width ;
 173 if the output string has fewer characters than the field width it will
 174 be blank-padded on the left (or right, if the left-adjustment indicator
 175 has been given) to make up the field width (note that a leading zero
 176 is a flag, but an embedded zero is part of a field width);
 177 .It Precision:
 178 An optional period,
 179 .Sq Cm \&.\& ,
 180 followed by an optional digit string giving a
 181 .Em precision
 182 which specifies the number of digits to appear after the decimal point,
 183 for
 184 .Cm e
 185 and
 186 .Cm f
 187 formats, or the maximum number of characters to be printed
 188 from a string; if the digit string is missing, the precision is treated
 189 as zero;
 190 .It Format:
 191 A character which indicates the type of format to use (one of
 192 .Cm diouxXfwEgGcsb ) .
 193 .El
 194 .Pp
 195 A field width or precision may be
 196 .Sq Cm \&*
 197 instead of a digit string.
 198 In this case an
 199 .Ar argument
 200 supplies the field width or precision.
 201 .Pp
 202 The format characters and their meanings are:
 203 .Bl -tag -width Fl
 204 .It Cm diouXx
 205 The
 206 .Ar argument
 207 is printed as a signed decimal (d or i), unsigned octal, unsigned decimal,
 208 or unsigned hexadecimal (X or x), respectively.
 209 .It Cm f
 210 The
 211 .Ar argument
 212 is printed in the style `[\-]ddd.ddd' where the number of d's
 213 after the decimal point is equal to the precision specification for
 214 the argument.
 215 If the precision is missing, 6 digits are given; if the precision
 216 is explicitly 0, no digits and no decimal point are printed.
 217 .It Cm eE
 218 The
 219 .Ar argument
 220 is printed in the style
 221 .Cm e
 222 .Sm off
 223 .Sq Op - Ar d.ddd No \(+- Ar dd
 224 .Sm on
 225 where there
 226 is one digit before the decimal point and the number after is equal to
 227 the precision specification for the argument; when the precision is
 228 missing, 6 digits are produced.
 229 An upper-case E is used for an `E' format.
 230 .It Cm gG
 231 The
 232 .Ar argument
 233 is printed in style
 234 .Cm f
 235 or in style
 236 .Cm e
 237 .Pq Cm E
 238 whichever gives full precision in minimum space.
 239 .It Cm c
 240 The first character of
 241 .Ar argument
 242 is printed.
 243 .It Cm s
 244 Characters from the string
 245 .Ar argument
 246 are printed until the end is reached or until the number of characters
 247 indicated by the precision specification is reached; however if the
 248 precision is 0 or missing, all characters in the string are printed.
 249 .It Cm b
 250 As for
 251 .Cm s ,
 252 but interpret character escapes in backslash notation in the string
 253 .Ar argument .
 254 .It Cm \&%
 255 Print a `%'; no argument is used.
 256 .El
 257 .Pp
 258 The decimal point
 259 character is defined in the program's locale (category
 260 .Dv LC_NUMERIC ) .
 261 .Pp
 262 In no case does a non-existent or small field width cause truncation of
 263 a field; padding takes place only if the specified field width exceeds
 264 the actual width.
 265 .Pp
 266 Some shells may provide a builtin
 267 .Nm
 268 command which is similar or identical to this utility.
 269 Consult the
 270 .Xr builtin 1
 271 manual page.
 272 .Sh DIAGNOSTICS
 273 .Ex -std
 274 .Sh COMPATIBILITY
 275 The traditional
 276 .Bx
 277 behavior of converting arguments of numeric formats not beginning
 278 with a digit to the
 279 .Tn ASCII
 280 code of the first character is not supported.
 281 .Sh SEE ALSO
 282 .Xr echo 1 ,
 283 .Xr printf 3
 284 .Sh STANDARDS
 285 The
 286 .Nm
 287 command is expected to be compatible with the
 288 .St -p1003.2
 289 specification.
 290 .Sh HISTORY
 291 The
 292 .Nm
 293 command appeared in
 294 .Bx 4.3 Reno .
 295 It is modeled
 296 after the standard library function,
 297 .Xr printf 3 .
 298 .Sh BUGS
 299 Since the floating point numbers are translated from
 300 .Tn ASCII
 301 to floating-point and
 302 then back again, floating-point precision may be lost.
 303 .Pp
 304 .Tn ANSI
 305 hexadecimal character constants were deliberately not provided.
 306 .Pp
 307 The escape sequence \e000 is the string terminator.  When present in the
 308 .Ar format ,
 309 the
 310 .Ar format
 311 will be truncated at the \e000 character.