+.TH PRINTF 3S
+.SH NAME
+printf, fprintf, sprintf \- formatted output conversion
+.SH SYNOPSIS
+.B #include <stdio.h>
+.PP
+.B printf(format
+.RB [ ,
+arg ] ...
+.B )
+.br
+.B char *format;
+.PP
+.B fprintf(stream, format
+.RB [ ,
+arg ] ...
+.B )
+.br
+.SM
+.B FILE
+.B *stream;
+.br
+.B char *format;
+.PP
+.B sprintf(s, format
+.RB [ ,
+arg ] ...
+.B )
+.br
+.B char *s, format;
+.SH DESCRIPTION
+.I Printf
+places output on the standard output stream
+.IR stdout .
+.I Fprintf
+places output on the named output
+.IR stream .
+.I Sprintf
+places `output' in the string
+.I s,
+followed by the character `\\0'.
+.PP
+Each of these functions
+converts, formats, and prints its arguments after the first
+under control of the first argument.
+The first argument is a character string
+which contains
+two types of objects:
+plain characters, which are simply copied to the
+output stream,
+and conversion specifications,
+each of which causes conversion and printing
+of the next successive
+.I arg
+.IR printf .
+.PP
+Each conversion specification is introduced by
+the character
+.BR % .
+Following the
+.BR % ,
+there may be
+.TP
+\-
+an optional minus sign `\-' which specifies
+.I "left adjustment"
+of the converted value
+in the
+indicated field;
+.TP
+\-
+an optional digit string specifying a
+.I "field width;"
+if the converted value has fewer characters
+than the field width
+it will be blank-padded on the left (or right,
+if the left-adjustment indicator has been
+given) to make up the field width;
+if the field width begins with a zero,
+zero-padding will be done instead of blank-padding;
+.TP
+\-
+an optional period
+.RB ` . '
+which serves to
+separate the field width from the
+next digit string;
+.TP
+\-
+an optional digit string
+specifying a
+.I precision
+which specifies
+the number of digits to appear after the
+decimal point, for e- and f-conversion,
+or the maximum number of characters
+to be printed from a string;
+.TP
+\-
+the character
+.B l
+specifying that a following
+.BR d ,
+.BR o ,
+.BR x ,
+or
+.B u
+corresponds to a long integer
+.I arg.
+(A capitalized conversion code accomplishes
+the same thing.)
+.TP
+\-
+a character which indicates the type of
+conversion to be applied.
+.PP
+A field width or precision may be `*' instead of a digit string.
+In this case an integer
+.I arg
+supplies
+the field width or precision.
+.PP
+The conversion characters
+and their meanings are
+.TP
+.B dox
+The integer
+.I arg
+is converted to decimal, octal, or
+hexadecimal notation respectively.
+.TP
+.B f
+The float or double
+.I arg
+is converted to decimal notation
+in the style `[\fB\-\fR]ddd.ddd'
+where the number of d's after the decimal point
+is equal to the precision specification
+for the argument.
+If the precision
+is missing,
+6 digits are given;
+if the precision is explicitly 0, no digits and
+no decimal point are printed.
+.TP
+.B e
+The float or double
+.I arg
+is converted in the style
+`[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd'
+where there is one digit before the decimal point and
+the number after is equal to the
+precision specification for the argument;
+when the precision is missing,
+6 digits are produced.
+.TP
+.B g
+The float or double
+.I arg
+is printed in style
+.BR d ,
+in style
+.BR f ,
+or in
+style
+.BR e ,
+whichever gives full precision in minimum space.
+.TP
+.B c
+The character
+.I arg
+is printed.
+Null characters are ignored.
+.TP
+.B s
+.I Arg
+is taken to be a string (character pointer)
+and characters from the string are printed until
+a null character or until
+the number of characters indicated by the precision
+specification is reached;
+however if the precision is 0 or missing
+all characters up to a null are printed.
+.TP
+.B u
+The unsigned integer
+.I arg
+is converted to decimal
+and printed (the result will be in the
+range 0 through MAXUINT, where MAXUINT equals 4294967295 on a VAX-11
+and 65536 on a PDP-11).
+.TP
+.B %
+Print a `%'; no argument is converted.
+.PP
+In no case does a non-existent or small field width
+cause truncation of a field;
+padding takes place only if the specified field
+width exceeds the actual width.
+Characters generated by
+.I printf
+are printed by
+.IR putc (3).
+.PP
+.B Examples
+.br
+To print a date and time in the form `Sunday, July 3, 10:02',
+where
+.I weekday
+and
+.I month
+are pointers to null-terminated strings:
+.RS
+.HP
+.nh
+printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min);
+.RE
+.hy
+.PP
+To print
+.if n pi
+.if t \(*p
+to 5 decimals:
+.IP
+printf("pi = %.5f", 4*atan(1.0));
+.SH "SEE ALSO"
+putc(3),
+scanf(3),
+ecvt(3)
+.SH BUGS
+Very wide fields (>128 characters) fail.
projects / unix-history / commitdiff