Annotation of src/usr.bin/printf/printf.1, Revision 1.13
1.13 ! pjanzen 1: .\" $OpenBSD: printf.1,v 1.12 2000/10/19 18:18:54 aaron 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.
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 5.11 (Berkeley) 7/24/91
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
1.7 aaron 46: .Nm printf
1.1 deraadt 47: .Ar format
1.11 aaron 48: .Op Ar arguments ...
1.1 deraadt 49: .Sh DESCRIPTION
1.5 aaron 50: .Nm printf
1.1 deraadt 51: formats and prints its arguments, after the first, under control
52: of the
1.10 aaron 53: .Ar format .
1.1 deraadt 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
1.10 aaron 60: .Ar argument .
1.1 deraadt 61: .Pp
62: The
63: .Ar arguments
64: after the first are treated as strings if the corresponding format is
65: .Cm b ,
66: .Cm c
67: or
68: .Cm s ;
69: otherwise it is evaluated as a C constant, with the following extensions:
1.10 aaron 70: .Bl -bullet -offset indent
1.1 deraadt 71: .It
72: A leading plus or minus sign is allowed.
73: .It
1.7 aaron 74: If the leading character is a single or double quote, the value is the
1.1 deraadt 75: .Tn ASCII
76: code of the next character.
77: .El
78: .Pp
79: The format string is reused as often as necessary to satisfy the
1.10 aaron 80: .Ar arguments .
1.1 deraadt 81: Any extra format specifications are evaluated with zero or the null
82: string.
83: .Pp
1.7 aaron 84: Character escape sequences are in backslash notation as defined in
1.1 deraadt 85: .St -ansiC .
1.10 aaron 86: The characters and their meanings are as follows:
87: .Pp
88: .Bl -tag -width Ds -offset indent -compact
1.4 deraadt 89: .It Cm \ee
90: Write an <escape> character.
1.1 deraadt 91: .It Cm \ea
92: Write a <bell> character.
93: .It Cm \eb
94: Write a <backspace> character.
95: .It Cm \ef
96: Write a <form-feed> character.
97: .It Cm \en
98: Write a <new-line> character.
99: .It Cm \er
100: Write a <carriage return> character.
101: .It Cm \et
102: Write a <tab> character.
103: .It Cm \ev
104: Write a <vertical tab> character.
105: .It Cm \e\'
106: Write a <single quote> character.
107: .It Cm \e\e
108: Write a backslash character.
1.7 aaron 109: .It Cm \e Ns Ar num
1.1 deraadt 110: Write an 8-bit character whose
111: .Tn ASCII
112: value is the 1-, 2-, or 3-digit
113: octal number
114: .Ar num .
115: .El
116: .Pp
1.6 aaron 117: Each format specification is introduced by the percent
118: .Pq Sq \&%
119: character.
1.10 aaron 120: The remainder of the format specifiers include,
1.1 deraadt 121: in the following order:
122: .Bl -tag -width Ds
123: .It "Zero or more of the following flags:"
124: .Bl -tag -width Ds
125: .It Cm #
1.6 aaron 126: Specifies that the value should be printed in an
127: .Dq alternate form .
128: For the
1.10 aaron 129: .Cm c ,
1.1 deraadt 130: .Cm d ,
131: and
1.5 aaron 132: .Cm s
1.10 aaron 133: formats, this option has no effect.
134: For the
1.1 deraadt 135: .Cm o
1.6 aaron 136: format the precision of the number is increased to force the first
1.10 aaron 137: character of the output string to a zero.
138: For the
1.1 deraadt 139: .Cm x
140: .Pq Cm X
141: format, a non-zero result has the string
142: .Li 0x
143: .Pq Li 0X
1.10 aaron 144: prepended to it.
145: For
146: .Cm e ,
1.1 deraadt 147: .Cm E ,
1.10 aaron 148: .Cm f ,
1.1 deraadt 149: .Cm g ,
150: and
1.5 aaron 151: .Cm G
1.1 deraadt 152: formats, the result will always contain a decimal point, even if no
153: digits follow the point (normally, a decimal point only appears in the
1.10 aaron 154: results of those formats if a digit follows the decimal point).
155: For
1.1 deraadt 156: .Cm g
157: and
158: .Cm G
159: formats, trailing zeros are not removed from the result as they
1.5 aaron 160: would otherwise be.
1.1 deraadt 161: .It Cm \&\-
1.6 aaron 162: Specifies the
1.1 deraadt 163: .Em left adjustment
1.5 aaron 164: of the output in the indicated field.
1.1 deraadt 165: .It Cm \&+
1.6 aaron 166: Specifies that there should always be
1.1 deraadt 167: a sign placed before the number when using signed formats.
168: .It Sq \&\ \&
1.6 aaron 169: A space specifies that a blank should be left before a positive number
1.10 aaron 170: for a signed format.
171: A
172: .Ql +
1.6 aaron 173: overrides a space if both are used.
1.1 deraadt 174: .It Cm \&0
1.6 aaron 175: A zero character specifies that zero-padding should be used
1.10 aaron 176: rather than blank-padding.
177: This flag is ignored if used with a precision
1.6 aaron 178: specifier and any of the
179: .Cm d , i , o , u ,
180: or
181: .Cm x
182: .Pq Cm X
1.10 aaron 183: formats.
184: A
185: .Ql \&-
1.6 aaron 186: overrides a
1.10 aaron 187: .Ql \&0
1.6 aaron 188: if both are used.
1.1 deraadt 189: .El
190: .It "Field Width:"
191: An optional digit string specifying a
192: .Em field width ;
193: if the output string has fewer characters than the field width it will
194: be blank-padded on the left (or right, if the left-adjustment indicator
195: has been given) to make up the field width (note that a leading zero
1.5 aaron 196: is a flag, but an embedded zero is part of a field width).
1.1 deraadt 197: .It Precision:
1.6 aaron 198: An optional period
199: .Pq Sq \&. ,
1.1 deraadt 200: followed by an optional digit string giving a
201: .Em precision
202: which specifies the number of digits to appear after the decimal point,
203: for
204: .Cm e
1.7 aaron 205: and
1.1 deraadt 206: .Cm f
207: formats, or the maximum number of characters to be printed
208: from a string; if the digit string is missing, the precision is treated
1.5 aaron 209: as zero.
1.1 deraadt 210: .It Format:
211: A character which indicates the type of format to use (one of
1.3 d 212: .Cm diouxXfEgGbcs ) .
1.1 deraadt 213: .El
214: .Pp
215: A field width or precision may be
1.10 aaron 216: .Ql \&*
1.1 deraadt 217: instead of a digit string.
218: In this case an
219: .Ar argument
220: supplies the field width or precision.
221: .Pp
222: The format characters and their meanings are:
223: .Bl -tag -width Fl
224: .It Cm diouXx
225: The
226: .Ar argument
1.6 aaron 227: is printed as a signed decimal
228: .Pq Cm d No or Cm i ,
229: unsigned octal, unsigned decimal,
230: or unsigned hexadecimal
231: .Pq Cm x No or Cm X ,
232: respectively.
1.1 deraadt 233: .It Cm f
234: The
235: .Ar argument
1.7 aaron 236: is printed in the style
1.1 deraadt 237: .Sm off
238: .Pf [\-]ddd Cm \&. No ddd
239: .Sm on
240: where the number of d's
241: after the decimal point is equal to the precision specification for
242: the argument.
243: If the precision is missing, 6 digits are given; if the precision
244: is explicitly 0, no digits and no decimal point are printed.
245: .It Cm eE
246: The
247: .Ar argument
1.7 aaron 248: is printed in the style
1.1 deraadt 249: .Sm off
250: .Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
251: .Sm on
252: where there
253: is one digit before the decimal point and the number after is equal to
254: the precision specification for the argument; when the precision is
255: missing, 6 digits are produced.
1.6 aaron 256: An upper-case
1.10 aaron 257: .Sq E
1.6 aaron 258: is used for an
259: .Cm E
260: format.
1.1 deraadt 261: .It Cm gG
262: The
263: .Ar argument
264: is printed in style
265: .Cm f
266: or in style
267: .Cm e
268: .Pq Cm E
269: whichever gives full precision in minimum space.
270: .It Cm b
271: Characters from the string
272: .Ar argument
273: are printed with backslash-escape sequences expanded.
274: .It Cm c
275: The first character of
276: .Ar argument
277: is printed.
278: .It Cm s
279: Characters from the string
280: .Ar argument
281: are printed until the end is reached or until the number of characters
282: indicated by the precision specification is reached; however if the
283: precision is 0 or missing, all characters in the string are printed.
284: .It Cm \&%
1.6 aaron 285: Print a
1.10 aaron 286: .Ql \&% ;
1.6 aaron 287: no argument is used.
1.1 deraadt 288: .El
289: .Pp
290: In no case does a non-existent or small field width cause truncation of
291: a field; padding takes place only if the specified field width exceeds
292: the actual width.
1.9 aaron 293: .Pp
294: The
295: .Nm
296: utility exits 0 on success or 1 on failure.
1.8 aaron 297: .Sh EXAMPLES
298: Convert a hexidecimal value to decimal and print it out:
299: .Pp
300: .D1 Ic printf \&"%d\en\&" 0x20
301: .Pp
302: Print the decimal representation of the character 'a' (see
303: .Xr ascii 7 ) :
304: .Pp
305: .D1 Ic printf \&"%d\en\&" \e'a
1.1 deraadt 306: .Sh SEE ALSO
307: .Xr echo 1 ,
308: .Xr printf 3
309: .Sh STANDARDS
310: The
311: .Nm printf
1.7 aaron 312: utility conforms to
1.1 deraadt 313: .St -p1003.2-92 .
1.9 aaron 314: .Sh HISTORY
315: The
316: .Nm
317: command appeared in
318: .Bx 4.3 Reno .
1.12 aaron 319: .Sh CAVEATS
1.13 ! pjanzen 320: It is important never to pass a string with user-supplied data as a
1.12 aaron 321: format without using
322: .Ql %s .
323: An attacker can put format specifiers in the string to mangle your stack,
324: leading to a possible security hole.
325: .Pp
1.13 ! pjanzen 326: Always be sure to use the proper secure idiom:
1.12 aaron 327: .Bd -literal -offset indent
328: printf "%s" "$STRING"
329: .Ed
1.1 deraadt 330: .Sh BUGS
331: Since arguments are translated from
332: .Tn ASCII
333: to floating-point, and
334: 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