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