Annotation of src/usr.bin/printf/printf.1, Revision 1.2
1.2 ! deraadt 1: .\" $OpenBSD: printf.1,v 1.1.1.1 1995/10/18 08:45:57 deraadt 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
90: .It Cm \ea
91: Write a <bell> character.
92: .It Cm \eb
93: Write a <backspace> character.
94: .It Cm \ef
95: Write a <form-feed> character.
96: .It Cm \en
97: Write a <new-line> character.
98: .It Cm \er
99: Write a <carriage return> character.
100: .It Cm \et
101: Write a <tab> character.
102: .It Cm \ev
103: Write a <vertical tab> character.
104: .It Cm \e\'
105: Write a <single quote> character.
106: .It Cm \e\e
107: Write a backslash character.
108: .It Cm \e Ns Ar num
109: Write an 8-bit character whose
110: .Tn ASCII
111: value is the 1-, 2-, or 3-digit
112: octal number
113: .Ar num .
114: .El
115: .Pp
116: Each format specification is introduced by the percent character
117: (``%'').
118: The remainder of the format specification includes,
119: in the following order:
120: .Bl -tag -width Ds
121: .It "Zero or more of the following flags:"
122: .Bl -tag -width Ds
123: .It Cm #
124: A `#' character
125: specifying that the value should be printed in an ``alternate form''.
126: For
127: .Cm c ,
128: .Cm d ,
129: and
130: .Cm s ,
131: formats, this option has no effect. For the
132: .Cm o
133: formats the precision of the number is increased to force the first
134: character of the output string to a zero. For the
135: .Cm x
136: .Pq Cm X
137: format, a non-zero result has the string
138: .Li 0x
139: .Pq Li 0X
140: prepended to it. For
141: .Cm e ,
142: .Cm E ,
143: .Cm f ,
144: .Cm g ,
145: and
146: .Cm G ,
147: formats, the result will always contain a decimal point, even if no
148: digits follow the point (normally, a decimal point only appears in the
149: results of those formats if a digit follows the decimal point). For
150: .Cm g
151: and
152: .Cm G
153: formats, trailing zeros are not removed from the result as they
154: would otherwise be;
155: .It Cm \&\-
156: A minus sign `\-' which specifies
157: .Em left adjustment
158: of the output in the indicated field;
159: .It Cm \&+
160: A `+' character specifying that there should always be
161: a sign placed before the number when using signed formats.
162: .It Sq \&\ \&
163: A space specifying that a blank should be left before a positive number
164: for a signed format. A `+' overrides a space if both are used;
165: .It Cm \&0
166: A zero `0' character indicating that zero-padding should be used
167: rather than blank-padding. A `\-' overrides a `0' if both are used;
168: .El
169: .It "Field Width:"
170: An optional digit string specifying a
171: .Em field width ;
172: if the output string has fewer characters than the field width it will
173: be blank-padded on the left (or right, if the left-adjustment indicator
174: has been given) to make up the field width (note that a leading zero
175: is a flag, but an embedded zero is part of a field width);
176: .It Precision:
177: An optional period,
178: .Sq Cm \&.\& ,
179: followed by an optional digit string giving a
180: .Em precision
181: which specifies the number of digits to appear after the decimal point,
182: for
183: .Cm e
184: and
185: .Cm f
186: formats, or the maximum number of characters to be printed
187: from a string; if the digit string is missing, the precision is treated
188: as zero;
189: .It Format:
190: A character which indicates the type of format to use (one of
191: .Cm diouxXfwEgGbcs ) .
192: .El
193: .Pp
194: A field width or precision may be
195: .Sq Cm \&*
196: instead of a digit string.
197: In this case an
198: .Ar argument
199: supplies the field width or precision.
200: .Pp
201: The format characters and their meanings are:
202: .Bl -tag -width Fl
203: .It Cm diouXx
204: The
205: .Ar argument
206: is printed as a signed decimal (d or i), unsigned octal, unsigned decimal,
207: or unsigned hexadecimal (X or x), respectively.
208: .It Cm f
209: The
210: .Ar argument
211: is printed in the style
212: .Sm off
213: .Pf [\-]ddd Cm \&. No ddd
214: .Sm on
215: where the number of d's
216: after the decimal point is equal to the precision specification for
217: the argument.
218: If the precision is missing, 6 digits are given; if the precision
219: is explicitly 0, no digits and no decimal point are printed.
220: .It Cm eE
221: The
222: .Ar argument
223: is printed in the style
224: .Sm off
225: .Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
226: .Sm on
227: where there
228: is one digit before the decimal point and the number after is equal to
229: the precision specification for the argument; when the precision is
230: missing, 6 digits are produced.
231: An upper-case E is used for an `E' format.
232: .It Cm gG
233: The
234: .Ar argument
235: is printed in style
236: .Cm f
237: or in style
238: .Cm e
239: .Pq Cm E
240: whichever gives full precision in minimum space.
241: .It Cm b
242: Characters from the string
243: .Ar argument
244: are printed with backslash-escape sequences expanded.
245: .It Cm c
246: The first character of
247: .Ar argument
248: is printed.
249: .It Cm s
250: Characters from the string
251: .Ar argument
252: are printed until the end is reached or until the number of characters
253: indicated by the precision specification is reached; however if the
254: precision is 0 or missing, all characters in the string are printed.
255: .It Cm \&%
256: Print a `%'; no argument is used.
257: .El
258: .Pp
259: In no case does a non-existent or small field width cause truncation of
260: a field; padding takes place only if the specified field width exceeds
261: the actual width.
262: .Sh RETURN VALUES
263: .Nm Printf
264: exits 0 on success, 1 on failure.
265: .Sh SEE ALSO
266: .Xr echo 1 ,
267: .Xr printf 3
268: .Sh STANDARDS
269: The
270: .Nm printf
271: utility conforms to
272: .St -p1003.2-92 .
273: .Sh BUGS
274: Since arguments are translated from
275: .Tn ASCII
276: to floating-point, and
277: 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