Annotation of src/usr.bin/printf/printf.1, Revision 1.9
1.9 ! aaron 1: .\" $OpenBSD: printf.1,v 1.8 2000/01/22 12:46:30 aaron Exp $
1.1 deraadt 2: .\" Copyright (c) 1989, 1990 The Regents of the University of California.
3: .\" All rights reserved.
4: .\"
5: .\" This code is derived from software contributed to Berkeley by
6: .\" the Institute of Electrical and Electronics Engineers, Inc.
7: .\"
8: .\" Redistribution and use in source and binary forms, with or without
9: .\" modification, are permitted provided that the following conditions
10: .\" are met:
11: .\" 1. Redistributions of source code must retain the above copyright
12: .\" notice, this list of conditions and the following disclaimer.
13: .\" 2. Redistributions in binary form must reproduce the above copyright
14: .\" notice, this list of conditions and the following disclaimer in the
15: .\" documentation and/or other materials provided with the distribution.
16: .\" 3. All advertising materials mentioning features or use of this software
17: .\" must display the following acknowledgement:
18: .\" This product includes software developed by the University of
19: .\" California, Berkeley and its contributors.
20: .\" 4. Neither the name of the University nor the names of its contributors
21: .\" may be used to endorse or promote products derived from this software
22: .\" without specific prior written permission.
23: .\"
24: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34: .\" SUCH DAMAGE.
35: .\"
36: .\" from: @(#)printf.1 5.11 (Berkeley) 7/24/91
37: .\"
38: .Dd November 5, 1993
39: .Dt PRINTF 1
40: .Os
41: .Sh NAME
42: .Nm printf
43: .Nd formatted output
44: .Sh SYNOPSIS
1.7 aaron 45: .Nm printf
1.1 deraadt 46: .Ar format
47: .Op Ar arguments ...
48: .Sh DESCRIPTION
1.5 aaron 49: .Nm printf
1.1 deraadt 50: formats and prints its arguments, after the first, under control
51: of the
52: .Ar format .
53: The
54: .Ar format
55: is a character string which contains three types of objects: plain characters,
56: which are simply copied to standard output, character escape sequences which
57: are converted and copied to the standard output, and format specifications,
58: each of which causes printing of the next successive
59: .Ar argument .
60: .Pp
61: The
62: .Ar arguments
63: after the first are treated as strings if the corresponding format is
64: .Cm b ,
65: .Cm c
66: or
67: .Cm s ;
68: otherwise it is evaluated as a C constant, with the following extensions:
69: .Pp
70: .Bl -bullet -offset indent -compact
71: .It
72: A leading plus or minus sign is allowed.
73: .It
1.7 aaron 74: If the leading character is a single or double quote, the value is the
1.1 deraadt 75: .Tn ASCII
76: code of the next character.
77: .El
78: .Pp
79: The format string is reused as often as necessary to satisfy the
80: .Ar arguments .
81: Any extra format specifications are evaluated with zero or the null
82: string.
83: .Pp
1.7 aaron 84: Character escape sequences are in backslash notation as defined in
1.1 deraadt 85: .St -ansiC .
86: The characters and their meanings
87: are as follows:
88: .Bl -tag -width Ds -offset indent
1.4 deraadt 89: .It Cm \ee
90: Write an <escape> character.
1.1 deraadt 91: .It Cm \ea
92: Write a <bell> character.
93: .It Cm \eb
94: Write a <backspace> character.
95: .It Cm \ef
96: Write a <form-feed> character.
97: .It Cm \en
98: Write a <new-line> character.
99: .It Cm \er
100: Write a <carriage return> character.
101: .It Cm \et
102: Write a <tab> character.
103: .It Cm \ev
104: Write a <vertical tab> character.
105: .It Cm \e\'
106: Write a <single quote> character.
107: .It Cm \e\e
108: Write a backslash character.
1.7 aaron 109: .It Cm \e Ns Ar num
1.1 deraadt 110: Write an 8-bit character whose
111: .Tn ASCII
112: value is the 1-, 2-, or 3-digit
113: octal number
114: .Ar num .
115: .El
116: .Pp
1.6 aaron 117: Each format specification is introduced by the percent
118: .Pq Sq \&%
119: character.
1.1 deraadt 120: The remainder of the format specification includes,
121: in the following order:
122: .Bl -tag -width Ds
123: .It "Zero or more of the following flags:"
124: .Bl -tag -width Ds
125: .It Cm #
1.6 aaron 126: Specifies that the value should be printed in an
127: .Dq alternate form .
128: For the
1.1 deraadt 129: .Cm c ,
130: .Cm d ,
131: and
1.5 aaron 132: .Cm s
1.1 deraadt 133: formats, this option has no effect. For the
134: .Cm o
1.6 aaron 135: format the precision of the number is increased to force the first
1.1 deraadt 136: character of the output string to a zero. For the
137: .Cm x
138: .Pq Cm X
139: format, a non-zero result has the string
140: .Li 0x
141: .Pq Li 0X
142: prepended to it. For
143: .Cm e ,
144: .Cm E ,
145: .Cm f ,
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
151: results of those formats if a digit follows the decimal point). For
152: .Cm g
153: and
154: .Cm G
155: formats, trailing zeros are not removed from the result as they
1.5 aaron 156: would otherwise be.
1.1 deraadt 157: .It Cm \&\-
1.6 aaron 158: Specifies the
1.1 deraadt 159: .Em left adjustment
1.5 aaron 160: of the output in the indicated field.
1.1 deraadt 161: .It Cm \&+
1.6 aaron 162: Specifies that there should always be
1.1 deraadt 163: a sign placed before the number when using signed formats.
164: .It Sq \&\ \&
1.6 aaron 165: A space specifies that a blank should be left before a positive number
166: for a signed format. A
167: .Dq +
168: overrides a space if both are used.
1.1 deraadt 169: .It Cm \&0
1.6 aaron 170: A zero character specifies that zero-padding should be used
171: rather than blank-padding. This flag is ignored if used with a precision
172: specifier and any of the
173: .Cm d , i , o , u ,
174: or
175: .Cm x
176: .Pq Cm X
177: formats. A
178: .Dq \&-
179: overrides a
180: .Dq \&0
181: if both are used.
1.1 deraadt 182: .El
183: .It "Field Width:"
184: An optional digit string specifying a
185: .Em field width ;
186: if the output string has fewer characters than the field width it will
187: be blank-padded on the left (or right, if the left-adjustment indicator
188: has been given) to make up the field width (note that a leading zero
1.5 aaron 189: is a flag, but an embedded zero is part of a field width).
1.1 deraadt 190: .It Precision:
1.6 aaron 191: An optional period
192: .Pq Sq \&. ,
1.1 deraadt 193: followed by an optional digit string giving a
194: .Em precision
195: which specifies the number of digits to appear after the decimal point,
196: for
197: .Cm e
1.7 aaron 198: and
1.1 deraadt 199: .Cm f
200: formats, or the maximum number of characters to be printed
201: from a string; if the digit string is missing, the precision is treated
1.5 aaron 202: as zero.
1.1 deraadt 203: .It Format:
204: A character which indicates the type of format to use (one of
1.3 d 205: .Cm diouxXfEgGbcs ) .
1.1 deraadt 206: .El
207: .Pp
208: A field width or precision may be
1.6 aaron 209: .Dq \&*
1.1 deraadt 210: instead of a digit string.
211: In this case an
212: .Ar argument
213: supplies the field width or precision.
214: .Pp
215: The format characters and their meanings are:
216: .Bl -tag -width Fl
217: .It Cm diouXx
218: The
219: .Ar argument
1.6 aaron 220: is printed as a signed decimal
221: .Pq Cm d No or Cm i ,
222: unsigned octal, unsigned decimal,
223: or unsigned hexadecimal
224: .Pq Cm x No or Cm X ,
225: respectively.
1.1 deraadt 226: .It Cm f
227: The
228: .Ar argument
1.7 aaron 229: is printed in the style
1.1 deraadt 230: .Sm off
231: .Pf [\-]ddd Cm \&. No ddd
232: .Sm on
233: where the number of d's
234: after the decimal point is equal to the precision specification for
235: the argument.
236: If the precision is missing, 6 digits are given; if the precision
237: is explicitly 0, no digits and no decimal point are printed.
238: .It Cm eE
239: The
240: .Ar argument
1.7 aaron 241: is printed in the style
1.1 deraadt 242: .Sm off
243: .Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
244: .Sm on
245: where there
246: is one digit before the decimal point and the number after is equal to
247: the precision specification for the argument; when the precision is
248: missing, 6 digits are produced.
1.6 aaron 249: An upper-case
250: .Dq E
251: is used for an
252: .Cm E
253: format.
1.1 deraadt 254: .It Cm gG
255: The
256: .Ar argument
257: is printed in style
258: .Cm f
259: or in style
260: .Cm e
261: .Pq Cm E
262: whichever gives full precision in minimum space.
263: .It Cm b
264: Characters from the string
265: .Ar argument
266: are printed with backslash-escape sequences expanded.
267: .It Cm c
268: The first character of
269: .Ar argument
270: is printed.
271: .It Cm s
272: Characters from the string
273: .Ar argument
274: are printed until the end is reached or until the number of characters
275: indicated by the precision specification is reached; however if the
276: precision is 0 or missing, all characters in the string are printed.
277: .It Cm \&%
1.6 aaron 278: Print a
279: .Dq \&% ;
280: no argument is used.
1.1 deraadt 281: .El
282: .Pp
283: In no case does a non-existent or small field width cause truncation of
284: a field; padding takes place only if the specified field width exceeds
285: the actual width.
1.9 ! aaron 286: .Pp
! 287: The
! 288: .Nm
! 289: utility exits 0 on success or 1 on failure.
1.8 aaron 290: .Sh EXAMPLES
291: Convert a hexidecimal value to decimal and print it out:
292: .Pp
293: .D1 Ic printf \&"%d\en\&" 0x20
294: .Pp
295: Print the decimal representation of the character 'a' (see
296: .Xr ascii 7 ) :
297: .Pp
298: .D1 Ic printf \&"%d\en\&" \e'a
1.1 deraadt 299: .Sh SEE ALSO
300: .Xr echo 1 ,
301: .Xr printf 3
302: .Sh STANDARDS
303: The
304: .Nm printf
1.7 aaron 305: utility conforms to
1.1 deraadt 306: .St -p1003.2-92 .
1.9 ! aaron 307: .Sh HISTORY
! 308: The
! 309: .Nm
! 310: command appeared in
! 311: .Bx 4.3 Reno .
1.1 deraadt 312: .Sh BUGS
313: Since arguments are translated from
314: .Tn ASCII
315: to floating-point, and
316: 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