![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to printf.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / usr.bin / printf|
Return to printf.1 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / usr.bin / printf |
1.1 root 1: .\" Copyright (c) 1989, 1990 The Regents of the University of California.
2: .\" All rights reserved.
3: .\"
4: .\" Redistribution and use in source and binary forms are permitted provided
5: .\" that: (1) source distributions retain this entire copyright notice and
6: .\" comment, and (2) distributions including binaries display the following
7: .\" acknowledgement: ``This product includes software developed by the
8: .\" University of California, Berkeley and its contributors'' in the
9: .\" documentation or other materials provided with the distribution and in
10: .\" all advertising materials mentioning features or use of this software.
11: .\" Neither the name of the University nor the names of its contributors may
12: .\" be used to endorse or promote products derived from this software without
13: .\" specific prior written permission.
14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
17: .\"
18: .\" @(#)printf.1 5.8 (Berkeley) 7/24/90
19: .\"
20: .Dd July 24, 1990
21: .Dt PRINTF 1
22: .AT 1
23: .Sh NAME
24: .Nm printf
25: .Nd formatted output
26: .Sh SYNOPSIS
27: .Pp
28: .Nm printf format
29: .Op arguments ...
30: .Sh DESCRIPTION
31: .Nm Printf
32: formats and prints its arguments, after the first, under control
33: of the
34: .Ar format .
35: The
36: .Ar format
37: is a character string which contains three types of objects: plain characters,
38: which are simply copied to standard output, character escape sequences which
39: are converted and copied to the standard output, and format specifications,
40: each of which causes printing of the next successive
41: .Ar argument .
42: .Pp
43: The
44: .Ar arguments
45: after the first are treated as strings if the corresponding format is
46: either
47: .Cm c
48: or
49: .Cm s ;
50: otherwise it is evaluated as a C constant, with the following extensions:
51: .Pp
52: .Df I
53: A leading plus or minus sign is allowed.
54: .br
55: If the leading character is a single or double quote, or not a digit,
56: plus, or minus sign, the value is the ASCII code of the next character.
57: .De
58: .Pp
59: The format string is reused as often as necessary to satisfy the
60: .Ar arguments .
61: Any extra format specifications are evaluated with zero or the null
62: string.
63: .Pp
64: Character escape sequences are in backslash notation as defined in the
65: draft proposed ANSI C Standard X3J11. The characters and their meanings
66: are as follows:
67: .Tw Ds
68: .Tp Cm \ea
69: Write a <bell> character.
70: .Tp Cm \eb
71: Write a <backspace> character.
72: .Tp Cm \ef
73: Write a <form-feed> character.
74: .Tp Cm \en
75: Write a <new-line> character.
76: .Tp Cm \er
77: Write a <carriage return> character.
78: .Tp Cm \et
79: Write a <tab> character.
80: .Tp Cm \ev
81: Write a <vertical tab> character.
82: .Tp Cm \e\'
83: Write a <single quote> character.
84: .Tp Cm \e\e
85: Write a backslash character.
86: .Tp Cx Cm \e
87: .Ar num
88: .Cx
89: Write an 8-bit character whose ASCII value is the 1-, 2-, or 3-digit
90: octal number
91: .Ar num .
92: .Tp
93: .Pp
94: Each format specification is introduced by the percent character
95: (``%'').
96: The remainder of the format specification includes, in the
97: following order:
98: .Pp
99: Zero or more of the following flags:
100: .Pp
101: .Ds I
102: .Tw Ds
103: .Tp Cm #
104: A `#' character
105: specifying that the value should be printed in an ``alternate form''.
106: For
107: .Cm c ,
108: .Cm d ,
109: and
110: .Cm s ,
111: formats, this option has no effect. For the
112: .Cm o
113: formats the precision of the number is increased to force the first
114: character of the output string to a zero. For the
115: .Cm x
116: .Pq Cm X
117: format, a non-zero result has the string
118: .Li 0x
119: .Pq Li 0X
120: prepended to it. For
121: .Cm e ,
122: .Cm E ,
123: .Cm f ,
124: .Cm g ,
125: and
126: .Cm G ,
127: formats, the result will always contain a decimal point, even if no
128: digits follow the point (normally, a decimal point only appears in the
129: results of those formats if a digit follows the decimal point). For
130: .Cm g
131: and
132: .Cm G
133: formats, trailing zeros are not removed from the result as they
134: would otherwise be;
135: .Tp Cm \&\-
136: A minus sign `\-' which specifies
137: .Em left adjustment
138: of the output in the indicated field;
139: .Tp Cm \&+
140: A `+' character specifying that there should always be
141: a sign placed before the number when using signed formats.
142: .Tp Sq \&\ \&
143: A space specifying that a blank should be left before a positive number
144: for a signed format. A `+' overrides a space if both are used;
145: .Tp Cm \&0
146: A zero `0' character indicating that zero-padding should be used
147: rather than blank-padding. A `\-' overrides a `0' if both are used;
148: .Tp
149: .De
150: .Pp
151: .Tw Ds
152: .Tp Field Width:
153: An optional digit string specifying a
154: .Em field width ;
155: if the output string has fewer characters than the field width it will
156: be blank-padded on the left (or right, if the left-adjustment indicator
157: has been given) to make up the field width (note that a leading zero
158: is a flag, but an embedded zero is part of a field width);
159: .Tp Precision:
160: An optional period,
161: .Sq Cm \&.\& ,
162: followed by an optional digit string giving a
163: .Em precision
164: which specifies the number of digits to appear after the decimal point,
165: for
166: .Cm e
167: and
168: .Cm f
169: formats, or the maximum number of characters to be printed
170: from a string; if the digit string is missing, the precision is treated
171: as zero;
172: .Tp Format:
173: A character which indicates the type of format to use (one of
174: .Cm diouxXfwEgGcs ) .
175: .Tp
176: .Pp
177: A field width or precision may be
178: .Sq Cm \&*
179: instead of a digit string.
180: In this case an
181: .Ar argument
182: supplies the field width or precision.
183: .Pp
184: The format characters and their meanings are:
185: .Tw Fl
186: .Tp Cm diouXx
187: The
188: .Ar argument
189: is printed as a signed decimal (d or i), unsigned decimal, unsigned octal,
190: or unsigned hexadecimal (X or x), respectively.
191: .Tp Cm f
192: The
193: .Ar argument
194: is printed in the style `[\-]ddd.ddd' where the number of d's
195: after the decimal point is equal to the precision specification for
196: the argument.
197: If the precision is missing, 6 digits are given; if the precision
198: is explicitly 0, no digits and no decimal point are printed.
199: .Tp Cm eE
200: The
201: .Ar argument
202: is printed in the style
203: .Cx `[-]d.ddd
204: .Cm e
205: .Cx \(+-dd\'
206: .Cx
207: where there
208: is one digit before the decimal point and the number after is equal to
209: the precision specification for the argument; when the precision is
210: missing, 6 digits are produced.
211: An upper-case E is used for an `E' format.
212: .Tp Cm gG
213: The
214: .Ar argument
215: is printed in style
216: .Cm f
217: or in style
218: .Cm e
219: .Pq Cm E
220: whichever gives full precision in minimum space.
221: .Tp Cm c
222: The first character of
223: .Ar argument
224: is printed.
225: .Tp Cm s
226: Characters from the string
227: .Ar argument
228: are printed until the end is reached or until the number of characters
229: indicated by the precision specification is reached; however if the
230: precision is 0 or missing, all characters in the string are printed.
231: .Tp Cm \&%
232: Print a `%'; no argument is used.
233: .Tp
234: .Pp
235: In no case does a non-existent or small field width cause truncation of
236: a field; padding takes place only if the specified field width exceeds
237: the actual width.
238: .Sh RETURN VALUE
239: .Nm Printf
240: exits 0 on success, 1 on failure.
241: .Sh SEE ALSO
242: .Xr printf 3
243: .Sh HISTORY
244: .Nm Printf
245: as a command, appears in 4.3+Reno BSD. It is modeled
246: after the standard library function,
247: .Xr printf 3 .
248: .Sh BUGS
249: Since the number is translated from ASCII to floating-point, and
250: then back again, floating-point precision may be lost.
251: .Pp
252: ANSI hexadecimal character constants were deliberately not provided.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.