265 lines
6.1 KiB
Groff
265 lines
6.1 KiB
Groff
.\" @(#)printf.3s 6.3 (Berkeley) 6/5/86
|
|
.\"
|
|
.TH PRINTF 3 "June 5, 1986"
|
|
.AT 3
|
|
.SH NAME
|
|
printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf \- formatted output conversion
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <sys/types.h>
|
|
#include <stdio.h>
|
|
#include <stdarg.h>
|
|
|
|
int printf(const char *\fIformat\fP \fR[\fP, \fIarg\fP\fR] ...\fP);
|
|
int fprintf(FILE *\fIstream\fP, const char *\fIformat\fP \fR[\fP, \fIarg\fP\fR] ...\fP);
|
|
int sprintf(char *\fIs\fP, const char *\fIformat\fP \fR[\fP, \fIarg\fP\fR] ...\fP);
|
|
int snprintf(char *\fIs\fP, size_t \fIn\fP, const char *\fIformat\fP \fR[\fP, \fIarg\fP\fR] ...\fP);
|
|
int vprintf(const char *\fIformat\fP, va_list \fIargs\fP);
|
|
int vfprintf(FILE *\fIstream\fP, const char *\fIformat\fP, va_list \fIargs\fP);
|
|
int vsprintf(char *\fIs\fP, const char *\fIformat\fP, va_list \fIargs\fP);
|
|
int vsnprintf(char *\fIs\fP, size_t \fIn\fP, const char *\fIformat\fP, va_list \fIargs\fP);
|
|
.ft R
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.B Printf
|
|
places output on the standard output stream
|
|
.BR stdout .
|
|
.B Fprintf
|
|
places output on the named output
|
|
.IR stream .
|
|
.B Sprintf
|
|
places `output' in the string
|
|
.IR s ,
|
|
followed by the character `\e0'.
|
|
.B Snprintf
|
|
(Minix-vmd only)
|
|
is like
|
|
.B sprintf
|
|
except that no more than
|
|
.IR n \-1
|
|
characters are written to
|
|
.I s
|
|
followed by a `\e0'.
|
|
.PP
|
|
The
|
|
.B v*printf
|
|
functions can be used to make functions like the first four by using the
|
|
.BR stdarg (3)
|
|
method to process the argument.
|
|
.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
|
|
.IR arg .
|
|
.PP
|
|
Each conversion specification is introduced by the character
|
|
.BR % .
|
|
The remainder of the conversion specification includes
|
|
in the following order
|
|
.TP
|
|
\(bu
|
|
Zero or more of following flags:
|
|
.RS
|
|
.TP
|
|
\(bu
|
|
a `#' character
|
|
specifying that the value should be converted to an ``alternate form''.
|
|
For
|
|
.BR c ,
|
|
.BR d ,
|
|
.BR s ,
|
|
and
|
|
.BR u
|
|
conversions, this option has no effect. For
|
|
.B o
|
|
conversions, the precision of the number is increased to force the first
|
|
character of the output string to a zero. For
|
|
.BR x ( X )
|
|
conversion, a non-zero result has the string
|
|
.BR 0x ( 0X )
|
|
prepended to it. For
|
|
.BR e ,
|
|
.BR E ,
|
|
.BR f ,
|
|
.BR g ,
|
|
and
|
|
.BR G
|
|
conversions, the result will always contain a decimal point, even if no
|
|
digits follow the point (normally, a decimal point only appears in the
|
|
results of those conversions if a digit follows the decimal point). For
|
|
.B g
|
|
and
|
|
.B G
|
|
conversions, trailing zeros are not removed from the result as they
|
|
would otherwise be.
|
|
.TP
|
|
\(bu
|
|
a minus sign `\-' which specifies
|
|
.I "left adjustment"
|
|
of the converted value in the indicated field;
|
|
.TP
|
|
\(bu
|
|
a `+' character specifying that there should always be
|
|
a sign placed before the number when using signed conversions.
|
|
.TP
|
|
\(bu
|
|
a space specifying that a blank should be left before a positive number
|
|
during a signed conversion. A `+' overrides a space if both are used.
|
|
.RE
|
|
.TP
|
|
\(bu
|
|
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
|
|
\(bu
|
|
an optional period
|
|
.RB ` . '
|
|
which serves to separate the field width from the next digit string;
|
|
.TP
|
|
\(bu
|
|
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
|
|
\(bu
|
|
the character
|
|
.B l
|
|
specifying that a following
|
|
.BR d ,
|
|
.BR o ,
|
|
.BR x ,
|
|
or
|
|
.B u
|
|
corresponds to a long integer
|
|
.IR arg .
|
|
.TP
|
|
\(bu
|
|
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 X
|
|
Like
|
|
.BR x ,
|
|
but use upper case instead of lower case.
|
|
.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.
|
|
.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.
|
|
.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
|
|
.B printf
|
|
are printed by
|
|
.BR 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:
|
|
.PP
|
|
.RS
|
|
printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min);
|
|
.RE
|
|
.PP
|
|
To print
|
|
.if n pi
|
|
.if t \(*p
|
|
to 5 decimals:
|
|
.IP
|
|
printf("pi = %.5f", 4*atan(1.0));
|
|
.SH "SEE ALSO"
|
|
.BR putc (3),
|
|
.BR scanf (3),
|
|
.BR ecvt (3),
|
|
.BR stdarg (3).
|