![[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] / 43BSDReno / lib / libc / stdio|
Return to printf.3 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / stdio |
1.1 root 1: .\" @(#)printf.3 6.7 (Berkeley) 4/14/89
2: .\"
3: .TH PRINTF 3 "October 22, 1987"
4: .AT 3
5: .SH NAME
6: fprintf, printf, sprintf, vprintf, vfprintf, vsprintf - formatted
7: output conversion
8: .SH SYNOPSIS
9: .B #include <stdio.h>
10: .PP
11: .B printf(format
12: .RB [ ,
13: arg ] ...
14: .B )
15: .br
16: .B char *format;
17: .PP
18: .B fprintf(stream, format
19: .RB [ ,
20: arg ] ...
21: .B )
22: .br
23: .SM
24: .B FILE
25: .B *stream;
26: .br
27: .B char *format;
28: .PP
29: .B sprintf(s, format
30: .RB [ ,
31: arg ] ...
32: .B )
33: .br
34: .B char *s, *format;
35: .PP
36: .B #include <varargs.h>
37: .br
38: .B vprintf(format, args)
39: .br
40: .B char *format;
41: .br
42: .B va_list args;
43: .PP
44: .B vfprintf(stream, format, args)
45: .br
46: .B FILE *stream;
47: .br
48: .B char *format;
49: .br
50: .B va_list args;
51: .PP
52: .B vsprintf(s, format, args)
53: .br
54: .B char *s, *format;
55: .br
56: .B va_list args;
57: .SH DESCRIPTION
58: .I Printf
59: and
60: .I vprintf
61: place output on the standard output stream
62: .BR stdout .
63: .I Fprintf
64: and
65: .I vfprintf
66: place output on the named output
67: .IR stream .
68: .I Sprintf
69: and
70: .I vsprintf
71: copy into the string
72: .IR s ,
73: followed by the character `\e0'.
74: .IR Printf ,
75: .IR fprintf ,
76: and
77: .I sprintf
78: take variadic argument lists directly, while
79: .IR vprintf ,
80: .IR vfprintf ,
81: and
82: .I vsprintf
83: use the variable-length argument facilities of
84: .IR varargs (3)
85: and hence may be called indirectly (see examples).
86: .PP
87: Each function converts, formats, and prints its arguments after the
88: .I format
89: under control of the
90: .I format
91: argument; each returns the the total number of characters printed (not
92: including the trailing `\e0' in
93: .I sprintf
94: and
95: .IR vsprintf ).
96: .I Format
97: is a character string which contains two types of objects: plain characters,
98: which are simply copied to the output stream, and conversion specifications,
99: each of which causes conversion and printing of the next successive
100: .IR arg .
101: .PP
102: Each conversion specification is introduced by the percent character (``%'').
103: The remainder of the conversion specification includes, in the following
104: order,
105: .TP
106: .B \(bu
107: Zero or more of the following flags:
108: .RS
109: .TP
110: .B \(bu
111: a `#' character
112: specifying that the value should be converted to an ``alternate form''.
113: For
114: .BR c ,
115: .BR d ,
116: .BR i ,
117: .BR n ,
118: .BR p ,
119: .BR s ,
120: and
121: .BR u ,
122: conversions, this option has no effect.
123: For
124: .B o
125: conversions, the precision of the number is increased to force the first
126: character of the output string to a zero (except if a zero value is printed
127: with an explicit precision of zero).
128: For
129: .B x
130: and
131: .B X
132: conversions, a non-zero result has the string
133: .B 0x
134: (or
135: .B 0X
136: for
137: .B X
138: conversions) prepended to it.
139: For
140: .BR e ,
141: .BR E ,
142: .BR f ,
143: .BR g ,
144: and
145: .BR G ,
146: conversions, the result will always contain a decimal point, even if no
147: digits follow it (normally, a decimal point appears in the results of
148: those conversions only if a digit follows).
149: For
150: .B g
151: and
152: .B G
153: conversions, trailing zeros are not removed from the result as they
154: would otherwise be.
155: .TP
156: .B \(bu
157: A zero ``0'' character specifying zero padding.
158: For all conversions except
159: .BR n ,
160: the converted value is padded on the left with zeros rather than blanks.
161: If a precision is given with a numeric conversion (
162: .BR d ,
163: .BR i ,
164: .BR o ,
165: .BR u ,
166: .BR i ,
167: .BR x ,
168: and
169: .BR X ),
170: the ``0'' flag is ignored.
171: .TP
172: .B \(bu
173: A minus sign (``-'') specifying left adjustment of the converted value
174: in the indicated field.
175: Except for
176: .B n
177: conversions, the converted value is padded on the right with blanks,
178: rather than on the left with blanks or zeros.
179: A ``-'' overrides a ``0'' if both are given.
180: .TP
181: .B \(bu
182: A space, specifying that a blank should be left before a positive number
183: produced by a signed conversion (
184: .BR d ,
185: .BR e ,
186: .BR E ,
187: .BR f ,
188: .BR g ,
189: .BR G ,
190: or
191: .BR i ).
192: .TP
193: .B \(bu
194: a `+' character specifying that a sign always be placed before a
195: number produced by a signed conversion.
196: A ``+'' overrides a space if both are used.
197: .RE
198: .TP
199: .B \(bu
200: An optional digit string specifying a field width.
201: If the converted value has fewer characters than the field width, it will
202: be padded on the left (or right, if the left-adjustment flag is used) to
203: make up the field width.
204: .TP
205: .B \(bu
206: An optional precision, in the form of a period (``.'') followed by an
207: optional digit string. If the digit string is omitted, the precision
208: is taken as zero. This gives the minimum number of digits to appear for
209: .BR d ,
210: .BR i ,
211: .BR o ,
212: .BR u ,
213: .BR x ,
214: and
215: .B X
216: conversions, the number of digits to appear after the decimal point for
217: .BR e ,
218: .BR E ,
219: and
220: .B f
221: conversions, the maximum number of significant digits for
222: .B g
223: and
224: .B G
225: conversions, or the maximum number of characters to be printed from a
226: string for
227: .B s
228: conversions.
229: .TP
230: .B \(bu
231: The character
232: .BR h ,
233: specifying that a following
234: .BR d ,
235: .BR i ,
236: .BR o ,
237: .BR u ,
238: .BR x ,
239: or
240: .B X
241: conversion corresponds to a
242: .B "short int"
243: or
244: .B "unsigned short int"
245: argument, or that a following
246: .B n
247: conversion corresponds to a pointer to a
248: .B "short int"
249: argument.
250: .TP
251: .B \(bu
252: the character
253: .B l
254: (ell) specifying that a following
255: .BR d ,
256: .BR i ,
257: .BR o ,
258: .BR u ,
259: .BR x ,
260: or
261: .B X
262: conversion corresponds to a
263: .B "long int"
264: or
265: .B "unsigned long int"
266: argument, or that a following
267: .B n
268: conversion corresponds to a pointer to a
269: .B "long int"
270: argument.
271: .TP
272: .B \(bu
273: The character
274: .B L
275: specifying that a following
276: .BR e ,
277: .BR E ,
278: .BR f ,
279: .BR g ,
280: or
281: .B G
282: conversion corresponds to a
283: .B "long double"
284: argument (but note that long double values are not currently supported
285: by the \s-2VAX\s0 and Tahoe compilers).
286: .TP
287: .B \(bu
288: A character which indicates the type of conversion to be applied.
289: .PP
290: A field width or precision may be an asterisk (``*'') instead of a
291: digit string.
292: In this case an
293: .B int
294: argument supplies the value.
295: A negative field width is treated as a left adjustment flag followed by a
296: positive field width; a negative precision is treated as though it were
297: missing.
298: .PP
299: The conversion characters and their meanings are:
300: .TP
301: .B diouxX
302: The
303: .B int
304: (or appropriate variant) argument is converted to signed decimal
305: .RB ( d " and " i ),
306: unsigned octal
307: .RB ( o ),
308: unsigned decimal
309: .RB ( u ),
310: or unsigned hexadecimal
311: .RB ( x " and " X )
312: notation respectively. The letters
313: .B abcdef
314: are used for
315: .B x
316: conversions; the letters
317: .B ABCDEF
318: are used for
319: .B X
320: conversions.
321: The precision, if any, gives the minimum number of digits that must
322: appear; if the converted value requires fewer digits, it is padded on
323: the left with zeros.
324: .TP
325: .B DOU
326: The
327: .B "long int"
328: argument is converted to signed decimal, unsigned octal, or unsigned
329: decimal, as if the format had been
330: .BR ld ,
331: .BR lo ,
332: or
333: .B lu
334: respectively.
335: These conversion characters are deprecated, and will eventually disappear.
336: .TP 8
337: .B eE
338: The
339: .B double
340: argument is rounded and converted in the style
341: `[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd' where there is one digit before the
342: decimal point and the number after is equal to the precision specification
343: for the argument.
344: If the precision is missing, 6 digits are given; if the precision is
345: explicitly zero, no decimal point appears.
346: An
347: .B E
348: conversion uses the letter
349: .B E
350: (rather than
351: .BR e )
352: to introduce the exponent.
353: The exponent always contains at least two digits; if the value is zero,
354: the exponent is 00.
355: .TP 8
356: .B f
357: The
358: .B double
359: argument is rounded and converted to decimal notation in the style
360: `[\fB\-\fR]ddd.ddd' where the number of digits after the decimal point
361: is equal to the precision.
362: If the precision is missing, 6 digits are given; if the precision is
363: explicitly 0, no digits and no decimal point are printed.
364: If a decimal point appears, at least one digit appears before it.
365: .TP 8
366: .B g
367: The
368: .B double
369: argument is printed in style
370: .B f
371: or
372: .B e
373: (or
374: .B E
375: for
376: .B G
377: conversions).
378: The precision specifies the number of significant digits.
379: If the precision is missing, 6 digits are given; if the precision is zero,
380: it is treated as 1.
381: Style
382: .B e
383: is used if the exponent from its conversion is less than -4 or greater than
384: or equal to the precision.
385: Trailing zeros are removed from the fractional part of the result; a
386: decimal point appears only if it is followed by at least one digit.
387: .TP 8
388: .B c
389: The
390: .B int
391: argument is converted to an
392: .B "unsigned char",
393: and the resulting character is printed.
394: .TP 8
395: .B s
396: The
397: .B "char *"
398: argument is taken to be a string (character pointer).
399: Characters from the string are printed until a null character is reached,
400: or until the number of characters indicated by the precision have been
401: printed, whichever occurs first; if a precision is given, no null character
402: need be present.
403: .TP 8
404: .B p
405: The
406: .B "void *"
407: pointer argument is printed in hexadecimal (as if by ``%x'' or ``%lx'').
408: .TP 8
409: .B n
410: The number of characters written so far is stored into the
411: integer indicated by the
412: .B "int *"
413: (or variant) pointer argument.
414: No argument is converted.
415: .TP 8
416: .B %
417: Prints a `%'; no argument is converted.
418: .PP
419: In no case does a non-existent or small field width cause truncation of
420: a field; if the result of a conversion is wider than the field width, the
421: field is expanded to contain it.
422: Similarly, padding takes place only if the specified field width exceeds
423: the actual width.
424: .PP
425: .SH EXAMPLES
426: .br
427: To print a date and time in the form `Sunday, July 3, 10:02',
428: where
429: .I weekday
430: and
431: .I month
432: are pointers to null-terminated strings:
433: .RS
434: .HP
435: .nh
436: printf("%s, %s %d, %02d:%.2d", weekday, month, day, hour, min);
437: .RE
438: .hy
439: .PP
440: To print
441: .if n pi
442: .if t \(*p
443: to 5 decimals:
444: .IP
445: printf("pi = %.5f", 4*atan(1.0));
446: .PP
447: To allocate a 128 byte string and print into it:
448: .RS
449: .nf
450: .ta 1i 2i
451: .sp
452: #include <stdio.h>
453: #include <varargs.h>
454: char *newfmt(va_alist)
455: va_dcl
456: {
457: char *p, *malloc(), fmt;
458: va_list ap;
459: if ((p = malloc(128)) == NULL)
460: return (NULL);
461: va_start(ap);
462: fmt = va_arg(ap, char *);
463: (void) vsprintf(p, fmt, ap);
464: va_end(ap);
465: return (p);
466: }
467: .RE
468: .fi
469: .SH "SEE ALSO"
470: putc(3), scanf(3)
471: .SH BUGS
472: The conversion formats ``%D'', ``%O'', and ``%U'' are not standard and
473: are provided only for backward compatibility.
474: The effect of padding the ``%p'' format with zeros (either by the ``0''
475: flag or by specifying a precision), and the benign effect (i.e., none)
476: of the ``#'' flag on ``%n'' and ``%p'' conversions, as well as other
477: nonsensical combinations such as ``%Ld'', are not standard; such combinations
478: should be avoided.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.