xref: /original-bsd/lib/libc/stdio/printf.3 (revision ba762ddc)
1.\" Copyright (c) 1990, 1991 The Regents of the University of California.
2.\" All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" Chris Torek.
6.\" %sccs.include.redist.man%
7.\"
8.\"     @(#)printf.3	6.12 (Berkeley) 04/26/91
9.\"
10.Dd
11.Dt PRINTF 3
12.Os
13.Sh NAME
14.Nm printf ,
15.Nm fprintf ,
16.Nm sprintf ,
17.Nm snprintf ,
18.Nm vprintf ,
19.Nm vfprintf,
20.Nm vsprintf ,
21.Nm vsnprintf
22.Nd formatted output conversion
23.Sh SYNOPSIS
24.Fd #include <stdio.h>
25.Ft int
26.Fn printf "const char *format" ...
27.Ft int
28.Fn fprintf "FILE *stream" "const char *format" ...
29.Ft int
30.Fn sprintf "char *str" "const char *format" ...
31.Ft int
32.Fn snprintf "char *str" "size_t size" "const char *format" ...
33.\" .Ft int
34.\" .Fn smprintf "const char *format" ...
35.Fd #include <stdarg.h>
36.Ft int
37.Fn vprintf "const char *format" "va_list ap"
38.Ft int
39.Fn vfprintf "FILE *stream" "const char *format" "va_list ap"
40.Ft int
41.Fn vsprintf "char *str" "char *format" "va_list ap"
42.Ft int
43.Fn vsnprintf "char *str" "size_t size" "const char *format" "va_list ap"
44.\" .Ft int
45.\" .Fn vsmprintf "const char *format" "va_list ap"
46.Sh DESCRIPTION
47The
48.Fn printf
49family of functions produces output according to a
50.Fa format
51as described below.
52.Fn Printf
53and
54.Fn vprintf
55write output to
56.Em stdout,
57the standard output stream;
58.Fn fprintf
59and
60.Fn vfprintf
61write output to the given output
62.Fa stream ;
63.Fn sprintf ,
64.Fn snprintf ,
65.Fn vsprintf ,
66and
67.Fn vsnprintf
68write to the character string
69.Fa str .
70.\" .IR str ;
71.\" and
72.\" .I smprintf
73.\" and
74.\" .I vsmprintf
75.\" dynamically allocate a new string with
76.\" .IR malloc .
77These functions write the output under the control of a
78.Fa format
79string that specifies how subsequent arguments
80(or arguments accessed via the variable-length argument facilities of
81.Xr stdarg 3 )
82are converted for output.
83.\" Except for
84.\" .I smprintf
85.\" and
86.\" .IR vsmprintf ,
87.\" all of these functions return
88These functions return
89the number of characters printed
90(not including the trailing
91.Ql \e0
92used to end output to strings).
93.\" .I Smprintf
94.\" and
95.\" .I vsmprintf
96.\" return a pointer to a string of an appropriate length;
97.\" this pointer should be passed to
98.\" .I free
99.\" to release the associated storage
100.\" when it is no longer needed.
101.\" If sufficient space is not avaliable,
102.\" .I smprintf
103.\" and
104.\" .I vsmprintf
105.\" will return
106.\" .SM
107.\" .BR
108.Fn Snprintf
109and
110.Fn vsnprintf
111will write at most
112.Fa size Ns \-1
113of the characters printed into the output string
114(the
115.Fa size Ns 'th
116character then gets the terminating
117.Ql \e0 ) ;
118if the return value is greater than or equal to the
119.Fa size
120argument, the string was too short
121and some of the printed characters were discarded.
122.Fn Sprintf
123and
124.Fn vsprintf
125effectively assume an infinte
126.Fa size .
127.Pp
128The format string is composed of zero or more directives:
129ordinary
130.\" multibyte
131characters (not
132.Cm % ) ,
133which are copied unchanged to the output stream;
134and conversion specifications, each of which results
135in fetching zero or more subsequent arguments.
136Each conversion specification is introduced by
137the character
138.Cm % .
139The arguments must correspond properly (after type promotion)
140with the conversion specifier.
141After the
142.Cm % ,
143the following appear in sequence:
144.Bl -bullet
145.It
146Zero or more of the following flags:
147.Bl -hyphen -offset indent
148.It
149a
150.Cm #
151character
152specifying that the value should be converted to an ``alternate form''.
153For
154.Cm c ,
155.Cm d ,
156.Cm i ,
157.Cm n ,
158.Cm p ,
159.Cm s ,
160and
161.Cm u ,
162conversions, this option has no effect.
163For
164.Cm o
165conversions, the precision of the number is increased to force the first
166character of the output string to a zero (except if a zero value is printed
167with an explicit precision of zero).
168For
169.Cm x
170and
171.Cm X
172conversions, a non-zero result has the string
173.Ql 0x
174(or
175.Ql 0X
176for
177.Cm X
178conversions) prepended to it.
179For
180.Cm e ,
181.Cm E ,
182.Cm f ,
183.Cm g ,
184and
185.Cm G ,
186conversions, the result will always contain a decimal point, even if no
187digits follow it (normally, a decimal point appears in the results of
188those conversions only if a digit follows).
189For
190.Cm g
191and
192.Cm G
193conversions, trailing zeros are not removed from the result as they
194would otherwise be.
195.It
196A zero
197.Sq Cm \&0
198character specifying zero padding.
199For all conversions except
200.Cm n ,
201the converted value is padded on the left with zeros rather than blanks.
202If a precision is given with a numeric conversion
203.Pf ( Mc d ,
204.Cm i ,
205.Cm o ,
206.Cm u ,
207.Cm i ,
208.Cm x ,
209and
210.Cm X ) ,
211the
212.Sq Cm \&0
213flag is ignored.
214.It
215A negative field width flag
216.Sq Cm \-
217indicates the converted value is to be left adjusted on the field boundary.
218Except for
219.Cm n
220conversions, the converted value is padded on the right with blanks,
221rather than on the left with blanks or zeros.
222A
223.Sq Cm \-
224overrides a
225.Sq Cm \&0
226if both are given.
227.It
228A space, specifying that a blank should be left before a positive number
229produced by a signed conversion
230.Pf ( Cm d ,
231.Cm e ,
232.Cm E ,
233.Cm f ,
234.Cm g ,
235.Cm G ,
236or
237.Cm i ) .
238.It
239a
240.Sq Cm +
241character specifying that a sign always be placed before a
242number produced by a signed conversion.
243A
244.Sq Cm +
245overrides a space if both are used.
246.El
247.It
248An optional decimal digit string specifying a minimum field width.
249If the converted value has fewer characters than the field width, it will
250be padded with spaces on the left (or right, if the left-adjustment
251flag has been given) to fill out
252the field width.
253.It
254An optional precision, in the form of a period
255.Sq Cm \&.
256followed by an
257optional digit string.  If the digit string is omitted, the precision
258is taken as zero.  This gives the minimum number of digits to appear for
259.Cm d ,
260.Cm i ,
261.Cm o ,
262.Cm u ,
263.Cm x ,
264and
265.Cm X
266conversions, the number of digits to appear after the decimal-point for
267.Cm e ,
268.Cm E ,
269and
270.Cm f
271conversions, the maximum number of significant digits for
272.Cm g
273and
274.Cm G
275conversions, or the maximum number of characters to be printed from a
276string for
277.Cm s
278conversions.
279.It
280The optional character
281.Cm h ,
282specifying that a following
283.Cm d ,
284.Cm i ,
285.Cm o ,
286.Cm u ,
287.Cm x ,
288or
289.Cm X
290conversion corresponds to a
291.Em short int
292or
293.Em unsigned short int
294argument, or that a following
295.Cm n
296conversion corresponds to a pointer to a
297.Em short int
298argument.
299.It
300The optional character
301.Cm l
302(ell) specifying that a following
303.Cm d ,
304.Cm i ,
305.Cm o ,
306.Cm u ,
307.Cm x ,
308or
309.Cm X
310conversion applies to a pointer to a
311.Em long int
312or
313.Em unsigned long int
314argument, or that a following
315.Cm n
316conversion corresponds to a pointer to a
317.Em long int
318argument.
319.It
320The character
321.Cm L
322specifying that a following
323.Cm e ,
324.Cm E ,
325.Cm f ,
326.Cm g ,
327or
328.Cm G
329conversion corresponds to a
330.Em long double
331argument (but note that long double values are not currently supported
332by the
333.Tn VAX
334and
335.Tn Tahoe
336compilers).
337.It
338A character that specifies the type of conversion to be applied.
339.El
340.Pp
341A field width or precision, or both, may be indicated by
342an asterisk
343.Ql *
344instead of a
345digit string.
346In this case, an
347.Em int
348argument supplies the field width or precision.
349A negative field width is treated as a left adjustment flag followed by a
350positive field width; a negative precision is treated as though it were
351missing.
352.Pp
353The conversion specifiers and their meanings are:
354.Bl -tag -width "diouxX"
355.It Cm diouxX
356The
357.Em int
358(or appropriate variant) argument is converted to signed decimal
359.Pf ( Cm d
360and
361.Cm i ) ,
362unsigned octal
363.Pq Cm o ,
364unsigned decimal
365.Pq Cm u ,
366or unsigned hexadecimal
367.Pf ( Cm x
368and
369.Cm X )
370notation.  The letters
371.Cm abcdef
372are used for
373.Cm x
374conversions; the letters
375.Cm ABCDEF
376are used for
377.m X
378conversions.
379The precision, if any, gives the minimum number of digits that must
380appear; if the converted value requires fewer digits, it is padded on
381the left with zeros.
382.It Cm DOU
383The
384.Em long int
385argument is converted to signed decimal, unsigned octal, or unsigned
386decimal, as if the format had been
387.Cm ld ,
388.Cm lo ,
389or
390.Cm lu
391respectively.
392These conversion characters are deprecated, and will eventually disappear.
393.It Cm eE
394The
395.Em double
396argument is rounded and converted in the style
397.Sm off
398.Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
399.Sm on
400where there is one digit before the
401decimal-point character
402and the number of digits after it is equal to the precision;
403if the precision is missing,
404it is taken as 6; if the precision is
405zero, no decimal-point character appears.
406An
407.Cm E
408conversion uses the letter
409.Cm E
410(rather than
411.Cm e )
412to introduce the exponent.
413The exponent always contains at least two digits; if the value is zero,
414the exponent is 00.
415.It Cm f
416The
417.Em double
418argument is rounded and converted to decimal notation in the style
419.Sm off
420.Pf [-]ddd Cm \&. No ddd ,
421.Sm on
422where the number of digits after the decimal-point character
423is equal to the precision specification.
424If the precision is missing, it is taken as 6; if the precision is
425explicitly zero, no decimal-point character appears.
426If a decimal point appears, at least one digit appears before it.
427.It Cm g
428The
429.Em double
430argument is converted in style
431.Cm f
432or
433.Cm e
434(or
435.Cm E
436for
437.Cm G
438conversions).
439The precision specifies the number of significant digits.
440If the precision is missing, 6 digits are given; if the precision is zero,
441it is treated as 1.
442Style
443.Cm e
444is used if the exponent from its conversion is less than -4 or greater than
445or equal to the precision.
446Trailing zeros are removed from the fractional part of the result; a
447decimal point appears only if it is followed by at least one digit.
448.It Cm c
449The
450.Em int
451argument is converted to an
452.Em unsigned char ,
453and the resulting character is written.
454.It Cm s
455The
456.Dq Em char *
457argument is expected to be a pointer to an array of character type (pointer
458to a string).
459Characters from the array are written up to (but not including)
460a terminating
461.Dv NUL
462character;
463if a precision is specified, no more than the number specified are
464written.
465If a precision is given, no null character
466need be present; if the precision is not specified, or is greater than
467the size of the array, the array must contain a terminating
468.Dv NUL
469character.
470.It Cm p
471The
472.Dq Em void *
473pointer argument is printed in hexadecimal (as if by
474.Ql %#x
475or
476.Ql %#lx ) .
477.It Cm n
478The number of characters written so far is stored into the
479integer indicated by the
480.Dq Em int *
481(or variant) pointer argument.
482No argument is converted.
483.It Cm %
484A
485.Ql %
486is written. No argument is converted. The complete conversion specification
487is
488.Ql %% .
489.El
490.Pp
491In no case does a non-existent or small field width cause truncation of
492a field; if the result of a conversion is wider than the field width, the
493field is expanded to contain the conversion result.
494.Pp
495.Sh EXAMPLES
496.br
497To print a date and time in the form `Sunday, July 3, 10:02',
498where
499.Em weekday
500and
501.Em month
502are pointers to strings:
503.Bd -literal -offset indent
504#include <stdio.h>
505fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
506	weekday, month, day, hour, min);
507.Ed
508.Pp
509To print \*(Pi
510to five decimal places:
511.Bd -literal -offset indent
512#include <math.h>
513#include <stdio.h>
514fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
515.Ed
516.Pp
517To allocate a 128 byte string and print into it:
518.Bd -literal -offset indent
519#include <stdio.h>
520#include <stdlib.h>
521#include <stdarg.h>
522char *newfmt(const char *fmt, ...)
523{
524		char *p;
525		va_list ap;
526		if ((p = malloc(128)) == NULL)
527			return (NULL);
528		va_start(ap, fmt);
529		(void) vsnprintf(p, 128, fmt, ap);
530		va_end(ap);
531		return (p);
532}
533.Ed
534.Sh SEE ALSO
535.Xr printf 1 ,
536.Xr scanf 3
537.Sh STANDARDS
538The
539.Fn fprintf ,
540.Fn printf ,
541.Fn sprintf ,
542.Fn vprintf ,
543.Fn vfprintf ,
544and
545.Fn vsprintf
546functions
547conform to
548.St -ansiC .
549.Sh HISTORY
550The functions
551.Fn snprintf
552and
553.Fn vsnprintf
554are new to this release.
555.Sh BUGS
556The conversion formats
557.Cm %D ,
558.Cm %O ,
559and
560.Cm %U
561are not standard and
562are provided only for backward compatibility.
563The effect of padding the
564.Cm %p
565format with zeros (either by the
566.Sq Cm 0
567flag or by specifying a precision), and the benign effect (i.e., none)
568of the
569.Sq Cm #
570flag on
571.Cm %n
572and
573.Cm %p
574conversions, as well as other
575nonsensical combinations such as
576.Cm %Ld ,
577are not standard; such combinations
578should be avoided.
579.Pp
580Because
581.Fn sprintf
582and
583.Fn vsprintf
584assume an infinitely long string,
585callers must be careful not to overflow the actual space;
586this is often impossible to assure.
587For safety, programmers should use the
588.Fn snprintf
589interface instead.
590Unfortunately, this interface is not portable.
591