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