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 .Nm
  51 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 b ,
  67 .Cm c
  68 or
  69 .Cm s ;
  70 otherwise it is evaluated as a C constant, with the following extensions:
  71 .Pp
  72 .Bl -bullet -offset indent -compact
  73 .It
  74 A leading plus or minus sign is allowed.
  75 .It
  76 If the leading character is a single or double quote, the value is the
  77 .Tn ASCII
  78 code of the next character.
  79 .El
  80 .Pp
  81 The format string is reused as often as necessary to satisfy the
  82 .Ar arguments  .
  83 Any extra format specifications are evaluated with zero or the null
  84 string.
  85 .Pp
  86 Character escape sequences are in backslash notation as defined in
  87 .St -ansiC .
  88 The characters and their meanings
  89 are as follows:
  90 .Bl -tag -width Ds -offset indent
  91 .It Cm \ee
  92 Write an <escape> character.
  93 .It Cm \ea
  94 Write a <bell> character.
  95 .It Cm \eb
  96 Write a <backspace> character.
  97 .It Cm \ef
  98 Write a <form-feed> character.
  99 .It Cm \en
 100 Write a <new-line> character.
 101 .It Cm \er
 102 Write a <carriage return> character.
 103 .It Cm \et
 104 Write a <tab> character.
 105 .It Cm \ev
 106 Write a <vertical tab> character.
 107 .It Cm \e\'
 108 Write a <single quote> character.
 109 .It Cm \e\e
 110 Write a backslash character.
 111 .It Cm \e Ns Ar num
 112 Write an 8-bit character whose
 113 .Tn ASCII
 114 value is the 1-, 2-, or 3-digit
 115 octal number
 116 .Ar num .
 117 .El
 118 .Pp
 119 Each format specification is introduced by the percent character
 120 (``%'').
 121 The remainder of the format specification includes,
 122 in the following order:
 123 .Bl -tag -width Ds
 124 .It "Zero or more of the following flags:"
 125 .Bl -tag -width Ds
 126 .It Cm #
 127 A `#' character
 128 specifying that the value should be printed in an ``alternative form''.
 129 For
 130 .Cm c  ,
 131 .Cm d ,
 132 and
 133 .Cm s  ,
 134 formats, this option has no effect.  For the
 135 .Cm o
 136 formats the precision of the number is increased to force the first
 137 character of the output string to a zero.  For the
 138 .Cm x
 139 .Pq Cm X
 140 format, a non-zero result has the string
 141 .Li 0x
 142 .Pq Li 0X
 143 prepended to it.  For
 144 .Cm e  ,
 145 .Cm E ,
 146 .Cm f  ,
 147 .Cm g ,
 148 and
 149 .Cm G  ,
 150 formats, the result will always contain a decimal point, even if no
 151 digits follow the point (normally, a decimal point only appears in the
 152 results of those formats if a digit follows the decimal point).  For
 153 .Cm g
 154 and
 155 .Cm G
 156 formats, trailing zeros are not removed from the result as they
 157 would otherwise be;
 158 .It Cm \&\-
 159 A minus sign `\-' which specifies
 160 .Em left adjustment
 161 of the output in the indicated field;
 162 .It Cm \&+
 163 A `+' character specifying that there should always be
 164 a sign placed before the number when using signed formats.
 165 .It Sq \&\ \&
 166 A space specifying that a blank should be left before a positive number
 167 for a signed format.  A `+' overrides a space if both are used;
 168 .It Cm \&0
 169 A zero `0' character indicating that zero-padding should be used
 170 rather than blank-padding.  A `\-' overrides a `0' if both are used;
 171 .El
 172 .It "Field Width:"
 173 An optional digit string specifying a
 174 .Em field width ;
 175 if the output string has fewer characters than the field width it will
 176 be blank-padded on the left (or right, if the left-adjustment indicator
 177 has been given) to make up the field width (note that a leading zero
 178 is a flag, but an embedded zero is part of a field width);
 179 .It Precision:
 180 An optional period,
 181 .Sq Cm \&.\& ,
 182 followed by an optional digit string giving a
 183 .Em precision
 184 which specifies the number of digits to appear after the decimal point,
 185 for
 186 .Cm e
 187 and
 188 .Cm f
 189 formats, or the maximum number of characters to be printed
 190 from a string; if the digit string is missing, the precision is treated
 191 as zero;
 192 .It Format:
 193 A character which indicates the type of format to use (one of
 194 .Cm diouxXfwEgGbcs ) .
 195 .El
 196 .Pp
 197 A field width or precision may be
 198 .Sq Cm \&*
 199 instead of a digit string.
 200 In this case an
 201 .Ar argument
 202 supplies the field width or precision.
 203 .Pp
 204 The format characters and their meanings are:
 205 .Bl -tag -width Fl
 206 .It Cm diouXx
 207 The
 208 .Ar argument
 209 is printed as a signed decimal (d or i), unsigned octal, unsigned decimal,
 210 or unsigned hexadecimal (X or x), respectively.
 211 .It Cm f
 212 The
 213 .Ar argument
 214 is printed in the style
 215 .Sm off
 216 .Pf [\-]ddd Cm \&. No ddd
 217 .Sm on
 218 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 .It Cm eE
 224 The
 225 .Ar argument
 226 is printed in the style
 227 .Sm off
 228 .Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
 229 .Sm on
 230 where there
 231 is one digit before the decimal point and the number after is equal to
 232 the precision specification for the argument; when the precision is
 233 missing, 6 digits are produced.
 234 An upper-case E is used for an `E' format.
 235 .It Cm gG
 236 The
 237 .Ar argument
 238 is printed in style
 239 .Cm f
 240 or in style
 241 .Cm e
 242 .Pq Cm E
 243 whichever gives full precision in minimum space.
 244 .It Cm b
 245 Characters from the string
 246 .Ar argument
 247 are printed with backslash-escape sequences expanded.
 248 .It Cm c
 249 The first character of
 250 .Ar argument
 251 is printed.
 252 .It Cm s
 253 Characters from the string
 254 .Ar argument
 255 are printed until the end is reached or until the number of characters
 256 indicated by the precision specification is reached; however if the
 257 precision is 0 or missing, all characters in the string are printed.
 258 .It Cm \&%
 259 Print a `%'; no argument is used.
 260 .El
 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 .Sh RETURN VALUES
 266 .Nm
 267 exits 0 on success, 1 on failure.
 268 .Sh SEE ALSO
 269 .Xr echo 1 ,
 270 .Xr printf 3
 271 .Sh STANDARDS
 272 The
 273 .Nm
 274 utility mostly conforms to
 275 .St -p1003.2-92 .
 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 Parsing of - arguments is also somewhat different from
 283 .Xr printf 3 ,
 284 where unknown arguments are simply printed instead of being
 285 flagged as errors.