661 lines
15 KiB
Groff
661 lines
15 KiB
Groff
.\" Copyright (c) 1990, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to Berkeley by
|
|
.\" Chris Torek and the American National Standards Committee X3,
|
|
.\" on Information Processing Systems.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)printf.3 8.1 (Berkeley) 6/4/93
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd June 4, 1993
|
|
.Dt PRINTF 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm printf ,
|
|
.Nm fprintf ,
|
|
.Nm sprintf ,
|
|
.Nm snprintf ,
|
|
.Nm asprintf ,
|
|
.Nm vprintf ,
|
|
.Nm vfprintf,
|
|
.Nm vsprintf ,
|
|
.Nm vsnprintf ,
|
|
.Nm vasprintf
|
|
.Nd formatted output conversion
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.Fd #include <stdio.h>
|
|
.Ft int
|
|
.Fn printf "const char *format" ...
|
|
.Ft int
|
|
.Fn fprintf "FILE *stream" "const char *format" ...
|
|
.Ft int
|
|
.Fn sprintf "char *str" "const char *format" ...
|
|
.Ft int
|
|
.Fn snprintf "char *str" "size_t size" "const char *format" ...
|
|
.Ft int
|
|
.Fn asprintf "char **ret" "const char *format" ...
|
|
.Fd #include <stdarg.h>
|
|
.Ft int
|
|
.Fn vprintf "const char *format" "va_list ap"
|
|
.Ft int
|
|
.Fn vfprintf "FILE *stream" "const char *format" "va_list ap"
|
|
.Ft int
|
|
.Fn vsprintf "char *str" "const char *format" "va_list ap"
|
|
.Ft int
|
|
.Fn vsnprintf "char *str" "size_t size" "const char *format" "va_list ap"
|
|
.Ft int
|
|
.Fn vasprintf "char **ret" "const char *format" "va_list ap"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn printf
|
|
family of functions produces output according to a
|
|
.Fa format
|
|
as described below.
|
|
.Fn Printf
|
|
and
|
|
.Fn vprintf
|
|
write output to
|
|
.Em stdout,
|
|
the standard output stream;
|
|
.Fn fprintf
|
|
and
|
|
.Fn vfprintf
|
|
write output to the given output
|
|
.Fa stream ;
|
|
.Fn sprintf ,
|
|
.Fn snprintf ,
|
|
.Fn vsprintf ,
|
|
and
|
|
.Fn vsnprintf
|
|
write to the character string
|
|
.Fa str ;
|
|
and
|
|
.Fn asprintf
|
|
and
|
|
.Fn vasprintf
|
|
dynamically allocate a new string with
|
|
.Xr malloc 3 .
|
|
.Pp
|
|
These functions write the output under the control of a
|
|
.Fa format
|
|
string that specifies how subsequent arguments
|
|
(or arguments accessed via the variable-length argument facilities of
|
|
.Xr stdarg 3 )
|
|
are converted for output.
|
|
.Pp
|
|
These functions return
|
|
the number of characters printed
|
|
(not including the trailing
|
|
.Ql \e0
|
|
used to end output to strings).
|
|
.Pp
|
|
.Fn Asprintf
|
|
and
|
|
.Fn vasprintf
|
|
return a pointer to a buffer sufficiently large to hold the
|
|
string in the
|
|
.Fa ret
|
|
argument;
|
|
This pointer should be passed to
|
|
.Xr free 3
|
|
to release the allocated storage when it is no longer needed.
|
|
If sufficient space cannot be allocated,
|
|
.Fn asprintf
|
|
and
|
|
.Fn vasprintf
|
|
will return -1 and set
|
|
.Fa ret
|
|
to be a NULL pointer.
|
|
.Pp
|
|
.Fn Snprintf
|
|
and
|
|
.Fn vsnprintf
|
|
will write at most
|
|
.Fa size Ns \-1
|
|
of the characters printed into the output string
|
|
(the
|
|
.Fa size Ns 'th
|
|
character then gets the terminating
|
|
.Ql \e0 ) ;
|
|
if the return value is greater than or equal to the
|
|
.Fa size
|
|
argument, the string was too short
|
|
and some of the printed characters were discarded.
|
|
.Pp
|
|
.Fn Sprintf
|
|
and
|
|
.Fn vsprintf
|
|
effectively assume an infinite
|
|
.Fa size .
|
|
.Pp
|
|
The format string is composed of zero or more directives:
|
|
ordinary
|
|
.\" multibyte
|
|
characters (not
|
|
.Cm % ) ,
|
|
which are copied unchanged to the output stream;
|
|
and conversion specifications, each of which results
|
|
in fetching zero or more subsequent arguments.
|
|
Each conversion specification is introduced by
|
|
the character
|
|
.Cm % .
|
|
The arguments must correspond properly (after type promotion)
|
|
with the conversion specifier.
|
|
After the
|
|
.Cm % ,
|
|
the following appear in sequence:
|
|
.Bl -bullet
|
|
.It
|
|
An optional field, consisting of a decimal digit string followed by a
|
|
.Cm $ ,
|
|
specifying the next argument to access .
|
|
If this field is not provided, the argument following the last
|
|
argument accessed will be used.
|
|
Arguments are numbered starting at
|
|
.Cm 1 .
|
|
If unaccessed arguments in the format string are interspersed with ones that
|
|
are accessed the results will be indeterminate.
|
|
.It
|
|
Zero or more of the following flags:
|
|
.Bl -hyphen
|
|
.It
|
|
A
|
|
.Cm #
|
|
character
|
|
specifying that the value should be converted to an ``alternate form''.
|
|
For
|
|
.Cm c ,
|
|
.Cm d ,
|
|
.Cm i ,
|
|
.Cm n ,
|
|
.Cm p ,
|
|
.Cm s ,
|
|
and
|
|
.Cm u ,
|
|
conversions, this option has no effect.
|
|
For
|
|
.Cm o
|
|
conversions, the precision of the number is increased to force the first
|
|
character of the output string to a zero (except if a zero value is printed
|
|
with an explicit precision of zero).
|
|
For
|
|
.Cm x
|
|
and
|
|
.Cm X
|
|
conversions, a non-zero result has the string
|
|
.Ql 0x
|
|
(or
|
|
.Ql 0X
|
|
for
|
|
.Cm X
|
|
conversions) prepended to it.
|
|
For
|
|
.Cm e ,
|
|
.Cm E ,
|
|
.Cm f ,
|
|
.Cm g ,
|
|
and
|
|
.Cm G ,
|
|
conversions, the result will always contain a decimal point, even if no
|
|
digits follow it (normally, a decimal point appears in the results of
|
|
those conversions only if a digit follows).
|
|
For
|
|
.Cm g
|
|
and
|
|
.Cm G
|
|
conversions, trailing zeros are not removed from the result as they
|
|
would otherwise be.
|
|
.It
|
|
A zero
|
|
.Sq Cm \&0
|
|
character specifying zero padding.
|
|
For all conversions except
|
|
.Cm n ,
|
|
the converted value is padded on the left with zeros rather than blanks.
|
|
If a precision is given with a numeric conversion
|
|
.Pf ( Cm d ,
|
|
.Cm i ,
|
|
.Cm o ,
|
|
.Cm u ,
|
|
.Cm i ,
|
|
.Cm x ,
|
|
and
|
|
.Cm X ) ,
|
|
the
|
|
.Sq Cm \&0
|
|
flag is ignored.
|
|
.It
|
|
A negative field width flag
|
|
.Sq Cm \-
|
|
indicates the converted value is to be left adjusted on the field boundary.
|
|
Except for
|
|
.Cm n
|
|
conversions, the converted value is padded on the right with blanks,
|
|
rather than on the left with blanks or zeros.
|
|
A
|
|
.Sq Cm \-
|
|
overrides a
|
|
.Sq Cm \&0
|
|
if both are given.
|
|
.It
|
|
A space, specifying that a blank should be left before a positive number
|
|
produced by a signed conversion
|
|
.Pf ( Cm d ,
|
|
.Cm e ,
|
|
.Cm E ,
|
|
.Cm f ,
|
|
.Cm g ,
|
|
.Cm G ,
|
|
or
|
|
.Cm i ) .
|
|
.It
|
|
A
|
|
.Sq Cm +
|
|
character specifying that a sign always be placed before a
|
|
number produced by a signed conversion.
|
|
A
|
|
.Sq Cm +
|
|
overrides a space if both are used.
|
|
.El
|
|
.It
|
|
An optional decimal digit string specifying a minimum field width.
|
|
If the converted value has fewer characters than the field width, it will
|
|
be padded with spaces on the left (or right, if the left-adjustment
|
|
flag has been given) to fill out
|
|
the field width.
|
|
.It
|
|
An optional precision, in the form of a period
|
|
.Sq Cm \&.
|
|
followed by an
|
|
optional digit string. If the digit string is omitted, the precision
|
|
is taken as zero. This gives the minimum number of digits to appear for
|
|
.Cm d ,
|
|
.Cm i ,
|
|
.Cm o ,
|
|
.Cm u ,
|
|
.Cm x ,
|
|
and
|
|
.Cm X
|
|
conversions, the number of digits to appear after the decimal-point for
|
|
.Cm e ,
|
|
.Cm E ,
|
|
and
|
|
.Cm f
|
|
conversions, the maximum number of significant digits for
|
|
.Cm g
|
|
and
|
|
.Cm G
|
|
conversions, or the maximum number of characters to be printed from a
|
|
string for
|
|
.Cm s
|
|
conversions.
|
|
.It
|
|
The optional character
|
|
.Cm h ,
|
|
specifying that a following
|
|
.Cm d ,
|
|
.Cm i ,
|
|
.Cm o ,
|
|
.Cm u ,
|
|
.Cm x ,
|
|
or
|
|
.Cm X
|
|
conversion corresponds to a
|
|
.Em short int
|
|
or
|
|
.Em unsigned short int
|
|
argument, or that a following
|
|
.Cm n
|
|
conversion corresponds to a pointer to a
|
|
.Em short int
|
|
argument.
|
|
.It
|
|
The optional character
|
|
.Cm l
|
|
(ell) specifying that a following
|
|
.Cm d ,
|
|
.Cm i ,
|
|
.Cm o ,
|
|
.Cm u ,
|
|
.Cm x ,
|
|
or
|
|
.Cm X
|
|
conversion applies to a pointer to a
|
|
.Em long int
|
|
or
|
|
.Em unsigned long int
|
|
argument, or that a following
|
|
.Cm n
|
|
conversion corresponds to a pointer to a
|
|
.Em long int
|
|
argument.
|
|
.It
|
|
The optional character
|
|
.Cm q ,
|
|
specifying that a following
|
|
.Cm d ,
|
|
.Cm i ,
|
|
.Cm o ,
|
|
.Cm u ,
|
|
.Cm x ,
|
|
or
|
|
.Cm X
|
|
conversion corresponds to a
|
|
.Em quad int
|
|
or
|
|
.Em unsigned quad int
|
|
argument, or that a following
|
|
.Cm n
|
|
conversion corresponds to a pointer to a
|
|
.Em quad int
|
|
argument.
|
|
.It
|
|
The character
|
|
.Cm L
|
|
specifying that a following
|
|
.Cm e ,
|
|
.Cm E ,
|
|
.Cm f ,
|
|
.Cm g ,
|
|
or
|
|
.Cm G
|
|
conversion corresponds to a
|
|
.Em long double
|
|
argument.
|
|
.It
|
|
A character that specifies the type of conversion to be applied.
|
|
.El
|
|
.Pp
|
|
A field width or precision, or both, may be indicated by
|
|
an asterisk
|
|
.Ql *
|
|
or an asterisk followed by one or more decimal digits and a
|
|
.Ql $
|
|
instead of a
|
|
digit string.
|
|
In this case, an
|
|
.Em int
|
|
argument supplies the field width or precision.
|
|
A negative field width is treated as a left adjustment flag followed by a
|
|
positive field width; a negative precision is treated as though it were
|
|
missing.
|
|
If a single format directive mixes positional (nn$)
|
|
and non-positional arguments, the results are undefined.
|
|
.Pp
|
|
The conversion specifiers and their meanings are:
|
|
.Bl -tag -width "diouxX"
|
|
.It Cm diouxX
|
|
The
|
|
.Em int
|
|
(or appropriate variant) argument is converted to signed decimal
|
|
.Pf ( Cm d
|
|
and
|
|
.Cm i ) ,
|
|
unsigned octal
|
|
.Pq Cm o ,
|
|
unsigned decimal
|
|
.Pq Cm u ,
|
|
or unsigned hexadecimal
|
|
.Pf ( Cm x
|
|
and
|
|
.Cm X )
|
|
notation. The letters
|
|
.Cm abcdef
|
|
are used for
|
|
.Cm x
|
|
conversions; the letters
|
|
.Cm ABCDEF
|
|
are used for
|
|
.Cm X
|
|
conversions.
|
|
The precision, if any, gives the minimum number of digits that must
|
|
appear; if the converted value requires fewer digits, it is padded on
|
|
the left with zeros.
|
|
.It Cm DOU
|
|
The
|
|
.Em long int
|
|
argument is converted to signed decimal, unsigned octal, or unsigned
|
|
decimal, as if the format had been
|
|
.Cm ld ,
|
|
.Cm lo ,
|
|
or
|
|
.Cm lu
|
|
respectively.
|
|
These conversion characters are deprecated, and will eventually disappear.
|
|
.It Cm eE
|
|
The
|
|
.Em double
|
|
argument is rounded and converted in the style
|
|
.Sm off
|
|
.Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
|
|
.Sm on
|
|
where there is one digit before the
|
|
decimal-point character
|
|
and the number of digits after it is equal to the precision;
|
|
if the precision is missing,
|
|
it is taken as 6; if the precision is
|
|
zero, no decimal-point character appears.
|
|
An
|
|
.Cm E
|
|
conversion uses the letter
|
|
.Cm E
|
|
(rather than
|
|
.Cm e )
|
|
to introduce the exponent.
|
|
The exponent always contains at least two digits; if the value is zero,
|
|
the exponent is 00.
|
|
.It Cm f
|
|
The
|
|
.Em double
|
|
argument is rounded and converted to decimal notation in the style
|
|
.Sm off
|
|
.Pf [-]ddd Cm \&. No ddd ,
|
|
.Sm on
|
|
where the number of digits after the decimal-point character
|
|
is equal to the precision specification.
|
|
If the precision is missing, it is taken as 6; if the precision is
|
|
explicitly zero, no decimal-point character appears.
|
|
If a decimal point appears, at least one digit appears before it.
|
|
.It Cm gG
|
|
The
|
|
.Em double
|
|
argument is converted in style
|
|
.Cm f
|
|
or
|
|
.Cm e
|
|
(or
|
|
.Cm E
|
|
for
|
|
.Cm G
|
|
conversions).
|
|
The precision specifies the number of significant digits.
|
|
If the precision is missing, 6 digits are given; if the precision is zero,
|
|
it is treated as 1.
|
|
Style
|
|
.Cm e
|
|
is used if the exponent from its conversion is less than -4 or greater than
|
|
or equal to the precision.
|
|
Trailing zeros are removed from the fractional part of the result; a
|
|
decimal point appears only if it is followed by at least one digit.
|
|
.It Cm c
|
|
The
|
|
.Em int
|
|
argument is converted to an
|
|
.Em unsigned char ,
|
|
and the resulting character is written.
|
|
.It Cm s
|
|
The
|
|
.Dq Em char *
|
|
argument is expected to be a pointer to an array of character type (pointer
|
|
to a string).
|
|
Characters from the array are written up to (but not including)
|
|
a terminating
|
|
.Dv NUL
|
|
character;
|
|
if a precision is specified, no more than the number specified are
|
|
written.
|
|
If a precision is given, no null character
|
|
need be present; if the precision is not specified, or is greater than
|
|
the size of the array, the array must contain a terminating
|
|
.Dv NUL
|
|
character.
|
|
.It Cm p
|
|
The
|
|
.Dq Em void *
|
|
pointer argument is printed in hexadecimal (as if by
|
|
.Ql %#x
|
|
or
|
|
.Ql %#lx ) .
|
|
.It Cm n
|
|
The number of characters written so far is stored into the
|
|
integer indicated by the
|
|
.Dq Em int *
|
|
(or variant) pointer argument.
|
|
No argument is converted.
|
|
.It Cm %
|
|
A
|
|
.Ql %
|
|
is written.
|
|
No argument is converted.
|
|
The complete conversion specification
|
|
is
|
|
.Ql %% .
|
|
.El
|
|
.Pp
|
|
In no case does a non-existent or small field width cause truncation of
|
|
a field; if the result of a conversion is wider than the field width, the
|
|
field is expanded to contain the conversion result.
|
|
.Pp
|
|
.Sh EXAMPLES
|
|
.br
|
|
To print a date and time in the form `Sunday, July 3, 10:02',
|
|
where
|
|
.Em weekday
|
|
and
|
|
.Em month
|
|
are pointers to strings:
|
|
.Bd -literal -offset indent
|
|
#include <stdio.h>
|
|
fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
|
|
weekday, month, day, hour, min);
|
|
.Ed
|
|
.Pp
|
|
To print \*(Pi
|
|
to five decimal places:
|
|
.Bd -literal -offset indent
|
|
#include <math.h>
|
|
#include <stdio.h>
|
|
fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
|
|
.Ed
|
|
.Pp
|
|
To allocate a 128 byte string and print into it:
|
|
.Bd -literal -offset indent
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
#include <stdarg.h>
|
|
char *newfmt(const char *fmt, ...)
|
|
{
|
|
char *p;
|
|
va_list ap;
|
|
if ((p = malloc(128)) == NULL)
|
|
return (NULL);
|
|
va_start(ap, fmt);
|
|
(void) vsnprintf(p, 128, fmt, ap);
|
|
va_end(ap);
|
|
return (p);
|
|
}
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr printf 1 ,
|
|
.Xr scanf 3
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn fprintf ,
|
|
.Fn printf ,
|
|
.Fn sprintf ,
|
|
.Fn vprintf ,
|
|
.Fn vfprintf ,
|
|
and
|
|
.Fn vsprintf
|
|
functions
|
|
conform to
|
|
.St -ansiC .
|
|
.Sh HISTORY
|
|
The functions
|
|
.Fn asprintf
|
|
and
|
|
.Fn vasprintf
|
|
first appeared in the GNU C library.
|
|
These were implemented by Peter Wemm <peter@FreeBSD.org> in
|
|
.Fx 2.2 ,
|
|
but were later replaced with a different implementation
|
|
from Todd C. Miller <Todd.Miller@courtesan.com> for
|
|
.Ox 2.3 .
|
|
.Sh BUGS
|
|
The conversion formats
|
|
.Cm \&%D ,
|
|
.Cm \&%O ,
|
|
and
|
|
.Cm %U
|
|
are not standard and
|
|
are provided only for backward compatibility.
|
|
The effect of padding the
|
|
.Cm %p
|
|
format with zeros (either by the
|
|
.Sq Cm 0
|
|
flag or by specifying a precision), and the benign effect (i.e., none)
|
|
of the
|
|
.Sq Cm #
|
|
flag on
|
|
.Cm %n
|
|
and
|
|
.Cm %p
|
|
conversions, as well as other
|
|
nonsensical combinations such as
|
|
.Cm %Ld ,
|
|
are not standard; such combinations
|
|
should be avoided.
|
|
.Pp
|
|
Because
|
|
.Fn sprintf
|
|
and
|
|
.Fn vsprintf
|
|
assume an infinitely long string,
|
|
callers must be careful not to overflow the actual space;
|
|
this is often hard to assure.
|
|
For safety, programmers should use the
|
|
.Fn snprintf
|
|
interface instead.
|
|
Unfortunately, this interface is not portable.
|