printf/printf.1

   1 .\"     $NetBSD: printf.1,v 1.10 1998/08/22 14:54:48 garbled Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1990, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" the Institute of Electrical and Electronics Engineers, Inc.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"     This product includes software developed by the University of
  20 .\"     California, Berkeley and its contributors.
  21 .\" 4. Neither the name of the University nor the names of its contributors
  22 .\"    may be used to endorse or promote products derived from this software
  23 .\"    without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  35 .\" SUCH DAMAGE.
  36 .\"
  37 .\"     from: @(#)printf.1      8.1 (Berkeley) 6/6/93
  38 .\"
  39 .Dd November 5, 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
  48 .Op Ar arguments  ...
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 utility formats and prints its arguments, after the first, under control
  53 of the
  54 .Ar format  .
  55 The
  56 .Ar format
  57 is a character string which contains three types of objects: plain characters,
  58 which are simply copied to standard output, character escape sequences which
  59 are converted and copied to the standard output, and format specifications,
  60 each of which causes printing of the next successive
  61 .Ar argument  .
  62 .Pp
  63 The
  64 .Ar arguments
  65 after the first are treated as strings if the corresponding format is
  66 either
  67 .Cm b ,
  68 .Cm c
  69 or
  70 .Cm s ;
  71 otherwise it is evaluated as a C constant, with the following extensions:
  72 .Pp
  73 .Bl -bullet -offset indent -compact
  74 .It
  75 A leading plus or minus sign is allowed.
  76 .It
  77 If the leading character is a single or double quote, the value is the
  78 .Tn ASCII
  79 code of the next character.
  80 .El
  81 .Pp
  82 The format string is reused as often as necessary to satisfy the
  83 .Ar arguments  .
  84 Any extra format specifications are evaluated with zero or the null
  85 string.
  86 .Pp
  87 Character escape sequences are in backslash notation as defined in
  88 .St -ansiC .
  89 The characters and their meanings
  90 are as follows:
  91 .Bl -tag -width Ds -offset indent
  92 .It Cm \ee
  93 Write an <escape> character.
  94 .It Cm \ea
  95 Write a <bell> character.
  96 .It Cm \eb
  97 Write a <backspace> character.
  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 Write an 8-bit character whose
 114 .Tn ASCII
 115 value is the 1-, 2-, or 3-digit
 116 octal number
 117 .Ar num .
 118 .El
 119 .Pp
 120 Each format specification is introduced by the percent character
 121 (``%'').
 122 The remainder of the format specification includes,
 123 in the following order:
 124 .Bl -tag -width Ds
 125 .It "Zero or more of the following flags:"
 126 .Bl -tag -width Ds
 127 .It Cm #
 128 A `#' character
 129 specifying that the value should be printed in an ``alternative form''.
 130 For
 131 .Cm c  ,
 132 .Cm 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  ,
 146 .Cm E ,
 147 .Cm f  ,
 148 .Cm 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).  For
 154 .Cm g
 155 and
 156 .Cm G
 157 formats, trailing zeros are not removed from the result as they
 158 would otherwise be;
 159 .It Cm \&\-
 160 A minus sign `\-' which specifies
 161 .Em left adjustment
 162 of the output in the indicated field;
 163 .It Cm \&+
 164 A `+' character specifying that there should always be
 165 a sign placed before the number when using signed formats.
 166 .It Sq \&\ \&
 167 A space specifying that a blank should be left before a positive number
 168 for a signed format.  A `+' overrides a space if both are used;
 169 .It Cm \&0
 170 A zero `0' character indicating that zero-padding should be used
 171 rather than blank-padding.  A `\-' overrides a `0' if both are used;
 172 .El
 173 .It "Field Width:"
 174 An optional digit string specifying a
 175 .Em field width ;
 176 if the output string has fewer characters than the field width it will
 177 be blank-padded on the left (or right, if the left-adjustment indicator
 178 has been given) to make up the field width (note that a leading zero
 179 is a flag, but an embedded zero is part of a field width);
 180 .It Precision:
 181 An optional period,
 182 .Sq Cm \&.\& ,
 183 followed by an optional digit string giving a
 184 .Em precision
 185 which specifies the number of digits to appear after the decimal point,
 186 for
 187 .Cm e
 188 and
 189 .Cm f
 190 formats, or the maximum number of characters to be printed
 191 from a string; if the digit string is missing, the precision is treated
 192 as zero;
 193 .It Format:
 194 A character which indicates the type of format to use (one of
 195 .Cm diouxXfwEgGbcs ) .
 196 .El
 197 .Pp
 198 A field width or precision may be
 199 .Sq Cm \&*
 200 instead of a digit string.
 201 In this case an
 202 .Ar argument
 203 supplies the field width or precision.
 204 .Pp
 205 The format characters and their meanings are:
 206 .Bl -tag -width Fl
 207 .It Cm diouXx
 208 The
 209 .Ar argument
 210 is printed as a signed decimal (d or i), unsigned octal, unsigned decimal,
 211 or unsigned hexadecimal (X or x), respectively.
 212 .It Cm f
 213 The
 214 .Ar argument
 215 is printed in the style
 216 .Sm off
 217 .Pf [\-]ddd Cm \&. No ddd
 218 .Sm on
 219 where the number of d's
 220 after the decimal point is equal to the precision specification for
 221 the argument.
 222 If the precision is missing, 6 digits are given; if the precision
 223 is explicitly 0, no digits and no decimal point are printed.
 224 .It Cm eE
 225 The
 226 .Ar argument
 227 is printed in the style
 228 .Sm off
 229 .Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
 230 .Sm on
 231 where there
 232 is one digit before the decimal point and the number after is equal to
 233 the precision specification for the argument; when the precision is
 234 missing, 6 digits are produced.
 235 An upper-case E is used for an `E' format.
 236 .It Cm gG
 237 The
 238 .Ar argument
 239 is printed in style
 240 .Cm f
 241 or in style
 242 .Cm e
 243 .Pq Cm E
 244 whichever gives full precision in minimum space.
 245 .It Cm b
 246 Characters from the string
 247 .Ar argument
 248 are printed with backslash-escape sequences expanded.
 249 .It Cm c
 250 The first character of
 251 .Ar argument
 252 is printed.
 253 .It Cm s
 254 Characters from the string
 255 .Ar argument
 256 are printed until the end is reached or until the number of characters
 257 indicated by the precision specification is reached; however if the
 258 precision is 0 or missing, all characters in the string are printed.
 259 .It Cm \&%
 260 Print a `%'; no argument is used.
 261 .El
 262 .Pp
 263 In no case does a non-existent or small field width cause truncation of
 264 a field; padding takes place only if the specified field width exceeds
 265 the actual width.
 266 .Sh RETURN VALUES
 267 .Nm
 268 exits 0 on success, 1 on failure.
 269 .Sh SEE ALSO
 270 .Xr echo 1 ,
 271 .Xr printf 3
 272 .Sh STANDARDS
 273 The
 274 .Nm
 275 utility mostly conforms to
 276 .St -p1003.2-92 .
 277 .Sh BUGS
 278 Since the floating point numbers are translated from
 279 .Tn ASCII
 280 to floating-point and
 281 then back again, floating-point precision may be lost.
 282 .Pp
 283 Parsing of - arguments is also somewhat different from
 284 .Xr printf 3 ,
 285 where unknown arguments are simply printed instead of being
 286 flagged as errors.