Annotation of src/usr.bin/printf/printf.1, Revision 1.18
1.18 ! jmc 1: .\" $OpenBSD: printf.1,v 1.17 2007/05/30 04:41:34 jmc Exp $
1.10 aaron 2: .\"
1.1 deraadt 3: .\" Copyright (c) 1989, 1990 The Regents of the University of California.
4: .\" 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.
1.16 millert 17: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 18: .\" may be used to endorse or promote products derived from this software
19: .\" without specific prior written permission.
20: .\"
21: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31: .\" SUCH DAMAGE.
32: .\"
33: .\" from: @(#)printf.1 5.11 (Berkeley) 7/24/91
34: .\"
1.18 ! jmc 35: .Dd $Mdocdate$
1.1 deraadt 36: .Dt PRINTF 1
37: .Os
38: .Sh NAME
39: .Nm printf
40: .Nd formatted output
41: .Sh SYNOPSIS
1.7 aaron 42: .Nm printf
1.1 deraadt 43: .Ar format
1.11 aaron 44: .Op Ar arguments ...
1.1 deraadt 45: .Sh DESCRIPTION
1.5 aaron 46: .Nm printf
1.1 deraadt 47: formats and prints its arguments, after the first, under control
48: of the
1.10 aaron 49: .Ar format .
1.1 deraadt 50: The
51: .Ar format
52: is a character string which contains three types of objects: plain characters,
53: which are simply copied to standard output, character escape sequences which
54: are converted and copied to the standard output, and format specifications,
55: each of which causes printing of the next successive
1.10 aaron 56: .Ar argument .
1.1 deraadt 57: .Pp
58: The
59: .Ar arguments
60: after the first are treated as strings if the corresponding format is
61: .Cm b ,
62: .Cm c
63: or
64: .Cm s ;
65: otherwise it is evaluated as a C constant, with the following extensions:
1.10 aaron 66: .Bl -bullet -offset indent
1.1 deraadt 67: .It
68: A leading plus or minus sign is allowed.
69: .It
1.7 aaron 70: If the leading character is a single or double quote, the value is the
1.1 deraadt 71: .Tn ASCII
72: code of the next character.
73: .El
74: .Pp
75: The format string is reused as often as necessary to satisfy the
1.10 aaron 76: .Ar arguments .
1.1 deraadt 77: Any extra format specifications are evaluated with zero or the null
78: string.
79: .Pp
1.7 aaron 80: Character escape sequences are in backslash notation as defined in
1.1 deraadt 81: .St -ansiC .
1.10 aaron 82: The characters and their meanings are as follows:
83: .Pp
84: .Bl -tag -width Ds -offset indent -compact
1.4 deraadt 85: .It Cm \ee
86: Write an <escape> character.
1.1 deraadt 87: .It Cm \ea
88: Write a <bell> character.
89: .It Cm \eb
90: Write a <backspace> character.
91: .It Cm \ef
92: Write a <form-feed> character.
93: .It Cm \en
94: Write a <new-line> character.
95: .It Cm \er
96: Write a <carriage return> character.
97: .It Cm \et
98: Write a <tab> character.
99: .It Cm \ev
100: Write a <vertical tab> character.
101: .It Cm \e\'
102: Write a <single quote> character.
103: .It Cm \e\e
104: Write a backslash character.
1.7 aaron 105: .It Cm \e Ns Ar num
1.1 deraadt 106: Write an 8-bit character whose
107: .Tn ASCII
108: value is the 1-, 2-, or 3-digit
109: octal number
110: .Ar num .
111: .El
112: .Pp
1.6 aaron 113: Each format specification is introduced by the percent
114: .Pq Sq \&%
115: character.
1.10 aaron 116: The remainder of the format specifiers include,
1.1 deraadt 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 #
1.6 aaron 122: Specifies that the value should be printed in an
123: .Dq alternate form .
124: For the
1.10 aaron 125: .Cm c ,
1.1 deraadt 126: .Cm d ,
127: and
1.5 aaron 128: .Cm s
1.10 aaron 129: formats, this option has no effect.
130: For the
1.1 deraadt 131: .Cm o
1.6 aaron 132: format the precision of the number is increased to force the first
1.10 aaron 133: character of the output string to a zero.
134: For the
1.1 deraadt 135: .Cm x
136: .Pq Cm X
137: format, a non-zero result has the string
138: .Li 0x
139: .Pq Li 0X
1.10 aaron 140: prepended to it.
141: For
142: .Cm e ,
1.1 deraadt 143: .Cm E ,
1.10 aaron 144: .Cm f ,
1.1 deraadt 145: .Cm g ,
146: and
1.5 aaron 147: .Cm G
1.1 deraadt 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
1.10 aaron 150: results of those formats if a digit follows the decimal point).
151: For
1.1 deraadt 152: .Cm g
153: and
154: .Cm G
155: formats, trailing zeros are not removed from the result as they
1.5 aaron 156: would otherwise be.
1.1 deraadt 157: .It Cm \&\-
1.6 aaron 158: Specifies the
1.1 deraadt 159: .Em left adjustment
1.5 aaron 160: of the output in the indicated field.
1.1 deraadt 161: .It Cm \&+
1.6 aaron 162: Specifies that there should always be
1.1 deraadt 163: a sign placed before the number when using signed formats.
164: .It Sq \&\ \&
1.6 aaron 165: A space specifies that a blank should be left before a positive number
1.10 aaron 166: for a signed format.
167: A
168: .Ql +
1.6 aaron 169: overrides a space if both are used.
1.1 deraadt 170: .It Cm \&0
1.6 aaron 171: A zero character specifies that zero-padding should be used
1.10 aaron 172: rather than blank-padding.
173: This flag is ignored if used with a precision
1.6 aaron 174: specifier and any of the
175: .Cm d , i , o , u ,
176: or
177: .Cm x
178: .Pq Cm X
1.10 aaron 179: formats.
180: A
181: .Ql \&-
1.6 aaron 182: overrides a
1.10 aaron 183: .Ql \&0
1.6 aaron 184: if both are used.
1.1 deraadt 185: .El
186: .It "Field Width:"
187: An optional digit string specifying a
188: .Em field width ;
189: if the output string has fewer characters than the field width it will
190: be blank-padded on the left (or right, if the left-adjustment indicator
191: has been given) to make up the field width (note that a leading zero
1.5 aaron 192: is a flag, but an embedded zero is part of a field width).
1.1 deraadt 193: .It Precision:
1.6 aaron 194: An optional period
195: .Pq Sq \&. ,
1.1 deraadt 196: followed by an optional digit string giving a
197: .Em precision
198: which specifies the number of digits to appear after the decimal point,
199: for
200: .Cm e
1.7 aaron 201: and
1.1 deraadt 202: .Cm f
203: formats, or the maximum number of characters to be printed
204: from a string; if the digit string is missing, the precision is treated
1.5 aaron 205: as zero.
1.1 deraadt 206: .It Format:
207: A character which indicates the type of format to use (one of
1.3 d 208: .Cm diouxXfEgGbcs ) .
1.1 deraadt 209: .El
210: .Pp
211: A field width or precision may be
1.10 aaron 212: .Ql \&*
1.1 deraadt 213: instead of a digit string.
214: In this case an
215: .Ar argument
216: supplies the field width or precision.
217: .Pp
218: The format characters and their meanings are:
219: .Bl -tag -width Fl
220: .It Cm diouXx
221: The
222: .Ar argument
1.6 aaron 223: is printed as a signed decimal
224: .Pq Cm d No or Cm i ,
225: unsigned octal, unsigned decimal,
226: or unsigned hexadecimal
227: .Pq Cm x No or Cm X ,
228: respectively.
1.1 deraadt 229: .It Cm f
230: The
231: .Ar argument
1.7 aaron 232: is printed in the style
1.1 deraadt 233: .Sm off
234: .Pf [\-]ddd Cm \&. No ddd
235: .Sm on
236: where the number of d's
237: after the decimal point is equal to the precision specification for
238: the argument.
239: If the precision is missing, 6 digits are given; if the precision
240: is explicitly 0, no digits and no decimal point are printed.
241: .It Cm eE
242: The
243: .Ar argument
1.7 aaron 244: is printed in the style
1.1 deraadt 245: .Sm off
246: .Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
247: .Sm on
248: where there
249: is one digit before the decimal point and the number after is equal to
250: the precision specification for the argument; when the precision is
251: missing, 6 digits are produced.
1.6 aaron 252: An upper-case
1.10 aaron 253: .Sq E
1.6 aaron 254: is used for an
255: .Cm E
256: format.
1.1 deraadt 257: .It Cm gG
258: The
259: .Ar argument
260: is printed in style
261: .Cm f
262: or in style
263: .Cm e
264: .Pq Cm E
265: whichever gives full precision in minimum space.
266: .It Cm b
267: Characters from the string
268: .Ar argument
269: are printed with backslash-escape sequences expanded.
270: .It Cm c
271: The first character of
272: .Ar argument
273: is printed.
274: .It Cm s
275: Characters from the string
276: .Ar argument
277: are printed until the end is reached or until the number of characters
278: indicated by the precision specification is reached; however if the
279: precision is 0 or missing, all characters in the string are printed.
280: .It Cm \&%
1.6 aaron 281: Print a
1.10 aaron 282: .Ql \&% ;
1.6 aaron 283: no argument is used.
1.1 deraadt 284: .El
285: .Pp
286: In no case does a non-existent or small field width cause truncation of
287: a field; padding takes place only if the specified field width exceeds
288: the actual width.
1.9 aaron 289: .Pp
290: The
291: .Nm
292: utility exits 0 on success or 1 on failure.
1.8 aaron 293: .Sh EXAMPLES
1.15 jmc 294: Convert a hexadecimal value to decimal and print it out:
1.8 aaron 295: .Pp
1.14 deraadt 296: .D1 Ic $ printf \&"%d\en\&" 0x20
1.8 aaron 297: .Pp
298: Print the decimal representation of the character 'a' (see
299: .Xr ascii 7 ) :
300: .Pp
1.14 deraadt 301: .D1 Ic $ printf \&"%d\en\&" \e'a
1.1 deraadt 302: .Sh SEE ALSO
303: .Xr echo 1 ,
304: .Xr printf 3
305: .Sh STANDARDS
306: The
1.17 jmc 307: .Nm
308: utility is compliant with the
309: .St -p1003.1-2004
310: specification.
1.9 aaron 311: .Sh HISTORY
312: The
313: .Nm
314: command appeared in
315: .Bx 4.3 Reno .
1.12 aaron 316: .Sh CAVEATS
1.13 pjanzen 317: It is important never to pass a string with user-supplied data as a
1.12 aaron 318: format without using
319: .Ql %s .
320: An attacker can put format specifiers in the string to mangle your stack,
321: leading to a possible security hole.
322: .Pp
1.13 pjanzen 323: Always be sure to use the proper secure idiom:
1.12 aaron 324: .Bd -literal -offset indent
325: printf "%s" "$STRING"
326: .Ed
1.1 deraadt 327: .Sh BUGS
328: Since arguments are translated from
329: .Tn ASCII
330: to floating-point, and
331: then back again, floating-point precision may be lost.
![[BACK]](/icons/back.gif){kind=icon}
Return to printf.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / printf