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