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$
  37 .\"
  38 .Dd June 6, 1993
  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 .Nm Printf
  49 formats and prints its arguments, after the first, under control
  50 of the
  51 .Ar format  .
  52 The
  53 .Ar format
  54 is a character string which contains three types of objects: plain characters,
  55 which are simply copied to standard output, character escape sequences which
  56 are converted and copied to the standard output, and format specifications,
  57 each of which causes printing of the next successive
  58 .Ar argument  .
  59 .Pp
  60 The
  61 .Ar arguments
  62 after the first are treated as strings if the corresponding format is
  63 either
  64 .Cm c
  65 or
  66 .Cm s ;
  67 otherwise it is evaluated as a C constant, with the following extensions:
  68 .Pp
  69 .Bl -bullet -offset indent -compact
  70 .It
  71 A leading plus or minus sign is allowed.
  72 .It
  73 If the leading character is a single or double quote, or not a digit,
  74 plus, or minus sign, the value is the ASCII code of the next character.
  75 .El
  76 .Pp
  77 The format string is reused as often as necessary to satisfy the
  78 .Ar arguments  .
  79 Any extra format specifications are evaluated with zero or the null
  80 string.
  81 .Pp
  82 Character escape sequences are in backslash notation as defined in the
  83 draft proposed
  84 .Tn ANSI C
  85 Standard
  86 .Tn X3J11 .
  87 The characters and their meanings
  88 are as follows:
  89 .Bl -tag -width Ds -offset indent
  90 .It Cm \ea
  91 Write a <bell> character.
  92 .It Cm \eb
  93 Write a <backspace> character.
  94 .It Cm \ef
  95 Write a <form-feed> character.
  96 .It Cm \en
  97 Write a <new-line> character.
  98 .It Cm \er
  99 Write a <carriage return> character.
 100 .It Cm \et
 101 Write a <tab> character.
 102 .It Cm \ev
 103 Write a <vertical tab> character.
 104 .It Cm \e\'
 105 Write a <single quote> character.
 106 .It Cm \e\e
 107 Write a backslash character.
 108 .It Cm \e Ns Ar num
 109 Write an 8-bit character whose
 110 .Tn ASCII
 111 value is the 1-, 2-, or 3-digit
 112 octal number
 113 .Ar num .
 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 c  ,
 128 .Cm d ,
 129 and
 130 .Cm s  ,
 131 formats, this option has no effect.  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.  For the
 135 .Cm x
 136 .Pq Cm X
 137 format, a non-zero result has the string
 138 .Li 0x
 139 .Pq Li 0X
 140 prepended to it.  For
 141 .Cm e  ,
 142 .Cm E ,
 143 .Cm f  ,
 144 .Cm 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).  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.  A `+' overrides a space if both are used;
 165 .It Cm \&0
 166 A zero `0' character indicating that zero-padding should be used
 167 rather than blank-padding.  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 characters 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 characters 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 diouxXfwEgGcs ) .
 192 .El
 193 .Pp
 194 A field width or precision may be
 195 .Sq Cm \&*
 196 instead of a digit string.
 197 In this case an
 198 .Ar argument
 199 supplies the field width or precision.
 200 .Pp
 201 The format characters and their meanings are:
 202 .Bl -tag -width Fl
 203 .It Cm diouXx
 204 The
 205 .Ar argument
 206 is printed as a signed decimal (d or i), unsigned octal, unsigned decimal,
 207 or unsigned hexadecimal (X or x), respectively.
 208 .It Cm f
 209 The
 210 .Ar argument
 211 is printed in the style `[\-]ddd.ddd' where the number of d's
 212 after the decimal point is equal to the precision specification for
 213 the argument.
 214 If the precision is missing, 6 digits are given; if the precision
 215 is explicitly 0, no digits and no decimal point are printed.
 216 .It Cm eE
 217 The
 218 .Ar argument
 219 is printed in the style
 220 .Cm e
 221 .`[-]d.ddd Ns \(+-dd\'
 222 where there
 223 is one digit before the decimal point and the number after is equal to
 224 the precision specification for the argument; when the precision is
 225 missing, 6 digits are produced.
 226 An upper-case E is used for an `E' format.
 227 .It Cm gG
 228 The
 229 .Ar argument
 230 is printed in style
 231 .Cm f
 232 or in style
 233 .Cm e
 234 .Pq Cm E
 235 whichever gives full precision in minimum space.
 236 .It Cm c
 237 The first character of
 238 .Ar argument
 239 is printed.
 240 .It Cm s
 241 Characters from the string
 242 .Ar argument
 243 are printed until the end is reached or until the number of characters
 244 indicated by the precision specification is reached; however if the
 245 precision is 0 or missing, all characters in the string are printed.
 246 .It Cm \&%
 247 Print a `%'; no argument is used.
 248 .El
 249 .Pp
 250 In no case does a non-existent or small field width cause truncation of
 251 a field; padding takes place only if the specified field width exceeds
 252 the actual width.
 253 .Pp
 254 Some shells may provide a builtin
 255 .Nm
 256 command which is similar or identical to this utility.
 257 Consult the
 258 .Xr builtin 1
 259 manual page.
 260 .Sh RETURN VALUES
 261 .Nm Printf
 262 exits 0 on success, 1 on failure.
 263 .Sh SEE ALSO
 264 .Xr builtin 1 ,
 265 .Xr csh 1 ,
 266 .Xr printf 3 ,
 267 .Xr sh 1
 268 .Sh HISTORY
 269 The
 270 .Nm
 271 command appeared in
 272 .Bx 4.3 Reno .
 273 It is modeled
 274 after the standard library function,
 275 .Xr printf 3 .
 276 .Sh BUGS
 277 Since the floating point numbers are translated from
 278 .Tn ASCII
 279 to floating-point and
 280 then back again, floating-point precision may be lost.
 281 .Pp
 282 .Tn ANSI
 283 hexadecimal character constants were deliberately not provided.
 284 .Pp
 285 The escape sequence \e000 is the string terminator.  When present in the
 286 .Ar format  ,
 287 the
 288 .Ar format
 289 will be truncated at the \e000 character.