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