![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to printf.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDTahoe / man / man3|
Return to printf.3 CVS log | Up to [CSRG BSD Unix] / 43BSDTahoe / man / man3 |
1.1 root 1: .\" @(#)printf.3 6.5 (Berkeley) 6/5/88
2: .\"
3: .TH PRINTF 3S "October 22, 1987"
4: .AT 3
5: .SH NAME
6: printf, fprintf, sprintf \- formatted output conversion
7: .SH SYNOPSIS
8: .B #include <stdio.h>
9: .PP
10: .B printf(format
11: .RB [ ,
12: arg ] ...
13: .B )
14: .br
15: .B char *format;
16: .PP
17: .B fprintf(stream, format
18: .RB [ ,
19: arg ] ...
20: .B )
21: .br
22: .SM
23: .B FILE
24: .B *stream;
25: .br
26: .B char *format;
27: .PP
28: .B sprintf(s, format
29: .RB [ ,
30: arg ] ...
31: .B )
32: .br
33: .B char *s, *format;
34: .PP
35: .B #include <varargs.h>
36: .br
37: .B vprintf(format, args)
38: .br
39: .B char *format;
40: .br
41: .B va_list args;
42: .PP
43: .B vfprintf(stream, format, args)
44: .br
45: .B FILE *stream;
46: .br
47: .B char *format;
48: .br
49: .B va_list args;
50: .PP
51: .B vsprintf(s, format, args)
52: .br
53: .B char *s, *format;
54: .br
55: .B va_list args;
56: .SH DESCRIPTION
57: .I Printf
58: places output on the standard output stream
59: .BR stdout .
60: .I Fprintf
61: places output on the named output
62: .IR stream .
63: .I Sprintf
64: places `output' in the string
65: .IR s ,
66: followed by the character `\\0'.
67: Alternate forms, in which the arguments have already been
68: captured using the variable-length argument facilities of
69: .IR varargs (3),
70: are available under the names
71: .IR vprintf ,
72: .IR vfprintf ,
73: and
74: .IR vsprintf .
75: .PP
76: Each of these functions converts, formats, and prints its arguments after
77: the first under control of the first argument.
78: The first argument is a character string which contains two types of objects:
79: plain characters, which are simply copied to the output stream,
80: and conversion specifications, each of which causes conversion and printing
81: of the next successive
82: .I arg
83: .IR printf .
84: .PP
85: Each conversion specification is introduced by the character
86: .BR % .
87: The remainder of the conversion specification includes
88: in the following order
89: .TP
90: .B \(bu
91: Zero or more of the following flags:
92: .RS
93: .TP
94: .B \(bu
95: a `#' character
96: specifying that the value should be converted to an ``alternate form''.
97: For
98: .BR c ,
99: .BR d ,
100: .BR s ,
101: and
102: .BR u ,
103: conversions, this option has no effect. For
104: .B o
105: conversions, the precision of the number is increased to force the first
106: character of the output string to a zero. For
107: .BR x ( X )
108: conversion, a non-zero result has the string
109: .BR 0x ( 0X )
110: prepended to it. For
111: .BR e ,
112: .BR E ,
113: .BR f ,
114: .BR g ,
115: and
116: .BR G ,
117: conversions, the result will always contain a decimal point, even if no
118: digits follow the point (normally, a decimal point only appears in the
119: results of those conversions if a digit follows the decimal point). For
120: .B g
121: and
122: .B G
123: conversions, trailing zeros are not removed from the result as they
124: would otherwise be;
125: .TP
126: .B \(bu
127: a minus sign `\-' which specifies
128: .I "left adjustment"
129: of the converted value in the indicated field;
130: .TP
131: .B \(bu
132: a `+' character specifying that there should always be
133: a sign placed before the number when using signed conversions;
134: .TP
135: .B \(bu
136: a space specifying that a blank should be left before a positive number
137: during a signed conversion. A `+' overrides a space if both are used;
138: .TP
139: .B \(bu
140: a zero `0' character indicating that zero-padding should be used
141: rather than blank-padding. A `\-' overrides a `0' if both are used;
142: .RE
143: .TP
144: .B \(bu
145: an optional digit string specifying a
146: .I "field width;"
147: if the converted value has fewer characters than the field width
148: it will be blank-padded on the left (or right,
149: if the left-adjustment indicator has been given) to make up the field width
150: (note that a leading zero is a flag,
151: but an embedded zero is part of a field width);
152: .TP
153: .B \(bu
154: an optional period, followed by
155: an optional digit string giving a
156: .I precision
157: which specifies the number of digits to appear after the
158: decimal point, for e- and f-conversion, or the maximum number of characters
159: to be printed from a string; if the digit string is missing,
160: the precision is treated as zero;
161: .TP
162: .B \(bu
163: the character
164: .B l
165: specifying that a following
166: .BR d ,
167: .BR i ,
168: .BR o ,
169: .BR x ,
170: or
171: .B u
172: corresponds to a long integer
173: .IR arg ,
174: or that a following
175: .B n
176: corresponds to a pointer to a long integer
177: .IR arg ;
178: .TP
179: .B \(bu
180: the character
181: .B h
182: specifying that a following
183: .BR d ,
184: .BR i ,
185: .BR o ,
186: .BR x ,
187: or
188: .B u
189: corresponds to a short integer
190: .IR arg ,
191: or that a following
192: .B n
193: corresponds to a pointer to a short integer
194: .IR arg ;
195: .TP
196: .B \(bu
197: a character which indicates the type of
198: conversion to be applied.
199: .PP
200: A field width or precision may be `*' instead of a digit string.
201: In this case an integer
202: .I arg
203: supplies
204: the field width or precision.
205: .PP
206: The conversion characters
207: and their meanings are
208: .TP
209: .B dox
210: The integer
211: .I arg
212: is converted to signed decimal, unsigned octal, or
213: unsigned hexadecimal notation respectively.
214: .TP
215: .B i
216: An alias for `d'.
217: .TP
218: .B f
219: The float or double
220: .I arg
221: is converted to decimal notation
222: in the style `[\fB\-\fR]ddd.ddd'
223: where the number of d's after the decimal point
224: is equal to the precision specification
225: for the argument.
226: If the precision
227: is missing,
228: 6 digits are given;
229: if the precision is explicitly 0, no digits and
230: no decimal point are printed.
231: .TP
232: .B eE
233: The float or double
234: .I arg
235: is converted in the style
236: `[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd'
237: where there is one digit before the decimal point and
238: the number after is equal to the
239: precision specification for the argument;
240: when the precision is missing,
241: 6 digits are produced.
242: An uppercase E is used for `E' conversion.
243: .TP
244: .B gG
245: The float or double
246: .I arg
247: is printed in style
248: .B f
249: or in style
250: .B e
251: .RB ( E )
252: whichever gives full precision in minimum space.
253: .TP
254: .B c
255: The character
256: .I arg
257: is printed.
258: .TP
259: .B s
260: .I Arg
261: is taken to be a string (character pointer)
262: and characters from the string are printed until
263: a null character or until
264: the number of characters indicated by the precision
265: specification is reached;
266: however if the precision is 0 or missing
267: all characters up to a null are printed.
268: .TP
269: .B u
270: The unsigned integer
271: .I arg
272: is converted to decimal
273: and printed (the result will be in the
274: range 0 through MAXUINT, where MAXUINT equals 4294967295 on a VAX-11
275: and 65535 on a PDP-11).
276: .TP
277: .B n
278: .I Arg
279: is taken to be a pointer to an integer (possibly
280: .B short
281: or
282: .BR long )
283: through which is stored the number of characters written
284: to the output stream (or string) so far by this call to
285: .B printf
286: (or
287: .BR fprintf ,
288: etc.).
289: .TP
290: .B p
291: .I Arg
292: is taken to be a pointer to
293: .BR void ;
294: it is printed in style
295: .BR x .
296: .TP
297: .B %
298: Print a `%'; no argument is converted.
299: .PP
300: In no case does a non-existent or small field width
301: cause truncation of a field;
302: padding takes place only if the specified field
303: width exceeds the actual width.
304: Characters generated by
305: .I printf
306: are printed as by
307: .IR putc (3S).
308: .PP
309: .SH "RETURN VALUE"
310: The functions all return
311: the number of characters printed, or -1 if an error occurred.
312: .SH EXAMPLES
313: .br
314: To print a date and time in the form `Sunday, July 3, 10:02',
315: where
316: .I weekday
317: and
318: .I month
319: are pointers to null-terminated strings:
320: .RS
321: .HP
322: .nh
323: printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min);
324: .RE
325: .hy
326: .PP
327: To print
328: .if n pi
329: .if t \(*p
330: to 5 decimals:
331: .IP
332: printf("pi = %.5f", 4*atan(1.0));
333: .SH "SEE ALSO"
334: putc(3S), scanf(3S)
335: .SH BUGS
336: The functions still supports \fI%D\fP, \fI%O\fP, and \fI%U\fP. Do not
337: use these formats, as they will be disappearing soon.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.