Annotation of src/usr.bin/printf/printf.1, Revision 1.19
1.19 ! martynas 1: .\" $OpenBSD: printf.1,v 1.18 2007/05/31 19:20:14 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.19 ! martynas 35: .Dd $Mdocdate: May 31 2007 $
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.19 ! martynas 145: .Cm F ,
1.1 deraadt 146: .Cm g ,
147: and
1.5 aaron 148: .Cm G
1.1 deraadt 149: formats, the result will always contain a decimal point, even if no
150: digits follow the point (normally, a decimal point only appears in the
1.10 aaron 151: results of those formats if a digit follows the decimal point).
152: For
1.1 deraadt 153: .Cm g
154: and
155: .Cm G
156: formats, trailing zeros are not removed from the result as they
1.5 aaron 157: would otherwise be.
1.1 deraadt 158: .It Cm \&\-
1.6 aaron 159: Specifies the
1.1 deraadt 160: .Em left adjustment
1.5 aaron 161: of the output in the indicated field.
1.1 deraadt 162: .It Cm \&+
1.6 aaron 163: Specifies that there should always be
1.1 deraadt 164: a sign placed before the number when using signed formats.
165: .It Sq \&\ \&
1.6 aaron 166: A space specifies that a blank should be left before a positive number
1.10 aaron 167: for a signed format.
168: A
169: .Ql +
1.6 aaron 170: overrides a space if both are used.
1.1 deraadt 171: .It Cm \&0
1.6 aaron 172: A zero character specifies that zero-padding should be used
1.10 aaron 173: rather than blank-padding.
174: This flag is ignored if used with a precision
1.6 aaron 175: specifier and any of the
176: .Cm d , i , o , u ,
177: or
178: .Cm x
179: .Pq Cm X
1.10 aaron 180: formats.
181: A
182: .Ql \&-
1.6 aaron 183: overrides a
1.10 aaron 184: .Ql \&0
1.6 aaron 185: if both are used.
1.1 deraadt 186: .El
187: .It "Field Width:"
188: An optional digit string specifying a
189: .Em field width ;
190: if the output string has fewer characters than the field width it will
191: be blank-padded on the left (or right, if the left-adjustment indicator
192: has been given) to make up the field width (note that a leading zero
1.5 aaron 193: is a flag, but an embedded zero is part of a field width).
1.1 deraadt 194: .It Precision:
1.6 aaron 195: An optional period
196: .Pq Sq \&. ,
1.1 deraadt 197: followed by an optional digit string giving a
198: .Em precision
199: which specifies the number of digits to appear after the decimal point,
200: for
201: .Cm e
1.7 aaron 202: and
1.1 deraadt 203: .Cm f
204: formats, or the maximum number of characters to be printed
205: from a string; if the digit string is missing, the precision is treated
1.5 aaron 206: as zero.
1.1 deraadt 207: .It Format:
208: A character which indicates the type of format to use (one of
1.19 ! martynas 209: .Cm diouxXfFeEgGbcs ) .
1.1 deraadt 210: .El
211: .Pp
212: A field width or precision may be
1.10 aaron 213: .Ql \&*
1.1 deraadt 214: instead of a digit string.
215: In this case an
216: .Ar argument
217: supplies the field width or precision.
218: .Pp
219: The format characters and their meanings are:
220: .Bl -tag -width Fl
221: .It Cm diouXx
222: The
223: .Ar argument
1.6 aaron 224: is printed as a signed decimal
225: .Pq Cm d No or Cm i ,
226: unsigned octal, unsigned decimal,
227: or unsigned hexadecimal
228: .Pq Cm x No or Cm X ,
229: respectively.
1.19 ! martynas 230: .It Cm fF
1.1 deraadt 231: The
232: .Ar argument
1.7 aaron 233: is printed in the style
1.1 deraadt 234: .Sm off
235: .Pf [\-]ddd Cm \&. No ddd
236: .Sm on
237: where the number of d's
238: after the decimal point is equal to the precision specification for
239: the argument.
240: If the precision is missing, 6 digits are given; if the precision
241: is explicitly 0, no digits and no decimal point are printed.
1.19 ! martynas 242: .Pp
! 243: If the argument is infinity, it will be converted to [-]inf
! 244: .Pq Cm f
! 245: or [-]INF
! 246: .Pq Cm F ,
! 247: respectively.
! 248: If the argument is not-a-number (NaN), it will be converted to
! 249: [-]nan
! 250: .Pq Cm f
! 251: or [-]NAN
! 252: .Pq Cm F ,
! 253: respectively.
1.1 deraadt 254: .It Cm eE
255: The
256: .Ar argument
1.7 aaron 257: is printed in the style
1.1 deraadt 258: .Sm off
259: .Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
260: .Sm on
261: where there
262: is one digit before the decimal point and the number after is equal to
263: the precision specification for the argument; when the precision is
264: missing, 6 digits are produced.
1.6 aaron 265: An upper-case
1.10 aaron 266: .Sq E
1.6 aaron 267: is used for an
268: .Cm E
269: format.
1.1 deraadt 270: .It Cm gG
271: The
272: .Ar argument
273: is printed in style
274: .Cm f
275: or in style
276: .Cm e
277: .Pq Cm E
278: whichever gives full precision in minimum space.
279: .It Cm b
280: Characters from the string
281: .Ar argument
282: are printed with backslash-escape sequences expanded.
283: .It Cm c
284: The first character of
285: .Ar argument
286: is printed.
287: .It Cm s
288: Characters from the string
289: .Ar argument
290: are printed until the end is reached or until the number of characters
291: indicated by the precision specification is reached; however if the
292: precision is 0 or missing, all characters in the string are printed.
293: .It Cm \&%
1.6 aaron 294: Print a
1.10 aaron 295: .Ql \&% ;
1.6 aaron 296: no argument is used.
1.1 deraadt 297: .El
298: .Pp
299: In no case does a non-existent or small field width cause truncation of
300: a field; padding takes place only if the specified field width exceeds
301: the actual width.
1.9 aaron 302: .Pp
303: The
304: .Nm
305: utility exits 0 on success or 1 on failure.
1.8 aaron 306: .Sh EXAMPLES
1.15 jmc 307: Convert a hexadecimal value to decimal and print it out:
1.8 aaron 308: .Pp
1.14 deraadt 309: .D1 Ic $ printf \&"%d\en\&" 0x20
1.8 aaron 310: .Pp
311: Print the decimal representation of the character 'a' (see
312: .Xr ascii 7 ) :
313: .Pp
1.14 deraadt 314: .D1 Ic $ printf \&"%d\en\&" \e'a
1.1 deraadt 315: .Sh SEE ALSO
316: .Xr echo 1 ,
317: .Xr printf 3
318: .Sh STANDARDS
319: The
1.17 jmc 320: .Nm
321: utility is compliant with the
322: .St -p1003.1-2004
323: specification.
1.9 aaron 324: .Sh HISTORY
325: The
326: .Nm
327: command appeared in
328: .Bx 4.3 Reno .
1.12 aaron 329: .Sh CAVEATS
1.13 pjanzen 330: It is important never to pass a string with user-supplied data as a
1.12 aaron 331: format without using
332: .Ql %s .
333: An attacker can put format specifiers in the string to mangle your stack,
334: leading to a possible security hole.
335: .Pp
1.13 pjanzen 336: Always be sure to use the proper secure idiom:
1.12 aaron 337: .Bd -literal -offset indent
338: printf "%s" "$STRING"
339: .Ed
1.1 deraadt 340: .Sh BUGS
341: Since arguments are translated from
342: .Tn ASCII
343: to floating-point, and
344: 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