Annotation of src/usr.bin/printf/printf.1, Revision 1.4
1.4 ! deraadt 1: .\" $OpenBSD: printf.1,v 1.3 1998/06/12 12:13:35 d 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
45: .Nm printf
46: .Ar format
47: .Op Ar arguments ...
48: .Sh DESCRIPTION
49: .Nm Printf
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: either
65: .Cm b ,
66: .Cm c
67: or
68: .Cm s ;
69: otherwise it is evaluated as a C constant, with the following extensions:
70: .Pp
71: .Bl -bullet -offset indent -compact
72: .It
73: A leading plus or minus sign is allowed.
74: .It
75: If the leading character is a single or double quote, the value is the
76: .Tn ASCII
77: code of the next character.
78: .El
79: .Pp
80: The format string is reused as often as necessary to satisfy the
81: .Ar arguments .
82: Any extra format specifications are evaluated with zero or the null
83: string.
84: .Pp
85: Character escape sequences are in backslash notation as defined in
86: .St -ansiC .
87: The characters and their meanings
88: are as follows:
89: .Bl -tag -width Ds -offset indent
1.4 ! deraadt 90: .It Cm \ee
! 91: Write an <escape> character.
1.1 deraadt 92: .It Cm \ea
93: Write a <bell> character.
94: .It Cm \eb
95: Write a <backspace> character.
96: .It Cm \ef
97: Write a <form-feed> character.
98: .It Cm \en
99: Write a <new-line> character.
100: .It Cm \er
101: Write a <carriage return> character.
102: .It Cm \et
103: Write a <tab> character.
104: .It Cm \ev
105: Write a <vertical tab> character.
106: .It Cm \e\'
107: Write a <single quote> character.
108: .It Cm \e\e
109: Write a backslash character.
110: .It Cm \e Ns Ar num
111: Write an 8-bit character whose
112: .Tn ASCII
113: value is the 1-, 2-, or 3-digit
114: octal number
115: .Ar num .
116: .El
117: .Pp
118: Each format specification is introduced by the percent character
119: (``%'').
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 #
126: A `#' character
127: specifying that the value should be printed in an ``alternate form''.
128: For
129: .Cm c ,
130: .Cm d ,
131: and
132: .Cm s ,
133: formats, this option has no effect. For the
134: .Cm o
135: formats the precision of the number is increased to force the first
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
148: .Cm G ,
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
156: would otherwise be;
157: .It Cm \&\-
158: A minus sign `\-' which specifies
159: .Em left adjustment
160: of the output in the indicated field;
161: .It Cm \&+
162: A `+' character specifying that there should always be
163: a sign placed before the number when using signed formats.
164: .It Sq \&\ \&
165: A space specifying that a blank should be left before a positive number
166: for a signed format. A `+' overrides a space if both are used;
167: .It Cm \&0
168: A zero `0' character indicating that zero-padding should be used
169: rather than blank-padding. A `\-' overrides a `0' if both are used;
170: .El
171: .It "Field Width:"
172: An optional digit string specifying a
173: .Em field width ;
174: if the output string has fewer characters than the field width it will
175: be blank-padded on the left (or right, if the left-adjustment indicator
176: has been given) to make up the field width (note that a leading zero
177: is a flag, but an embedded zero is part of a field width);
178: .It Precision:
179: An optional period,
180: .Sq Cm \&.\& ,
181: followed by an optional digit string giving a
182: .Em precision
183: which specifies the number of digits to appear after the decimal point,
184: for
185: .Cm e
186: and
187: .Cm f
188: formats, or the maximum number of characters to be printed
189: from a string; if the digit string is missing, the precision is treated
190: as zero;
191: .It Format:
192: A character which indicates the type of format to use (one of
1.3 d 193: .Cm diouxXfEgGbcs ) .
1.1 deraadt 194: .El
195: .Pp
196: A field width or precision may be
197: .Sq Cm \&*
198: instead of a digit string.
199: In this case an
200: .Ar argument
201: supplies the field width or precision.
202: .Pp
203: The format characters and their meanings are:
204: .Bl -tag -width Fl
205: .It Cm diouXx
206: The
207: .Ar argument
208: is printed as a signed decimal (d or i), unsigned octal, unsigned decimal,
209: or unsigned hexadecimal (X or x), respectively.
210: .It Cm f
211: The
212: .Ar argument
213: is printed in the style
214: .Sm off
215: .Pf [\-]ddd Cm \&. No ddd
216: .Sm on
217: where the number of d's
218: after the decimal point is equal to the precision specification for
219: the argument.
220: If the precision is missing, 6 digits are given; if the precision
221: is explicitly 0, no digits and no decimal point are printed.
222: .It Cm eE
223: The
224: .Ar argument
225: is printed in the style
226: .Sm off
227: .Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
228: .Sm on
229: where there
230: is one digit before the decimal point and the number after is equal to
231: the precision specification for the argument; when the precision is
232: missing, 6 digits are produced.
233: An upper-case E is used for an `E' format.
234: .It Cm gG
235: The
236: .Ar argument
237: is printed in style
238: .Cm f
239: or in style
240: .Cm e
241: .Pq Cm E
242: whichever gives full precision in minimum space.
243: .It Cm b
244: Characters from the string
245: .Ar argument
246: are printed with backslash-escape sequences expanded.
247: .It Cm c
248: The first character of
249: .Ar argument
250: is printed.
251: .It Cm s
252: Characters from the string
253: .Ar argument
254: are printed until the end is reached or until the number of characters
255: indicated by the precision specification is reached; however if the
256: precision is 0 or missing, all characters in the string are printed.
257: .It Cm \&%
258: Print a `%'; no argument is used.
259: .El
260: .Pp
261: In no case does a non-existent or small field width cause truncation of
262: a field; padding takes place only if the specified field width exceeds
263: the actual width.
264: .Sh RETURN VALUES
265: .Nm Printf
266: exits 0 on success, 1 on failure.
267: .Sh SEE ALSO
268: .Xr echo 1 ,
269: .Xr printf 3
270: .Sh STANDARDS
271: The
272: .Nm printf
273: utility conforms to
274: .St -p1003.2-92 .
275: .Sh BUGS
276: Since arguments are translated from
277: .Tn ASCII
278: to floating-point, and
279: 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