mirror of
https://github.com/GnoConsortium/gno.git
synced 2024-09-11 14:54:54 +00:00
640 lines
14 KiB
Groff
640 lines
14 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
|
|
.\"
|
|
.TH PRINTF 3 "15 September 1997" GNO "Library Routines"
|
|
.SH NAME
|
|
.BR printf ,
|
|
.BR fprintf ,
|
|
.BR sprintf ,
|
|
.BR snprintf ,
|
|
.BR vprintf ,
|
|
.BR vfprintf,
|
|
.BR vsprintf ,
|
|
.BR vsnprintf
|
|
\- formatted output conversion
|
|
.SH SYNOPSIS
|
|
#include <stdio.h>
|
|
.sp 1
|
|
int \fBprintf\fR (const char *\fIformat\fR, ...);
|
|
.br
|
|
int \fBfprintf\fR (FILE *\fIstream\fR, const char *\fIformat\fR, ...);
|
|
.br
|
|
int \fBsprintf\fR (char *\fIstr\fR, const char *\fIformat\fR, ...);
|
|
.br
|
|
int \fBsnprintf\fR (char *\fIstr\fR, size_t \fIsize\fR, const char *\fIformat\fR, ...);
|
|
.\" .br
|
|
.\" int \fBsmprintf\fR (const char *\fIformat\fR, ...);
|
|
.sp 1
|
|
#include <stdarg.h>
|
|
.sp 1
|
|
int \fBvprintf\fR (const char *\fIformat\fR, va_list \fIap\fR);
|
|
.br
|
|
int \fBvfprintf\fR (FILE *\fIstream\fR, const char *\fIformat\fR, va_list \fIap\fR);
|
|
.br
|
|
int \fBvsprintf\fR (char *\fIstr\fR, char *\fIformat\fR, va_list \fIap\fR);
|
|
.br
|
|
int \fBvsnprintf\fR (char *\fIstr\fR, size_t \fIsize\fR, const char *\fIformat\fR, va_list \fIap\fR);
|
|
.\" .br
|
|
.\" int \fBvsmprintf\fR (const char *\fIformat\fR, va_list \fIap\fR);
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR printf
|
|
family of functions produces output according to a
|
|
.I format
|
|
as described below.
|
|
.BR Printf
|
|
and
|
|
.BR vprintf
|
|
write output to
|
|
.IR stdout,
|
|
the standard output stream;
|
|
.BR fprintf
|
|
and
|
|
.BR vfprintf
|
|
write output to the given output
|
|
.IR stream .
|
|
.BR sprintf ,
|
|
.BR snprintf ,
|
|
.BR vsprintf ,
|
|
and
|
|
.BR vsnprintf
|
|
write to the character string
|
|
.IR str .
|
|
.\" .IR str ;
|
|
.\" and
|
|
.\" .I smprintf
|
|
.\" and
|
|
.\" .I vsmprintf
|
|
.\" dynamically allocate a new string with
|
|
.\" .IR malloc .
|
|
These functions write the output under the control of a
|
|
.I format
|
|
string that specifies how subsequent arguments
|
|
(or arguments accessed via the variable-length argument facilities of
|
|
.BR stdarg (3))
|
|
are converted for output.
|
|
.\" Except for
|
|
.\" .I smprintf
|
|
.\" and
|
|
.\" .IR vsmprintf ,
|
|
.\" all of these functions return
|
|
These functions return
|
|
the number of characters printed
|
|
(not including the trailing
|
|
.BR \e0
|
|
used to end output to strings).
|
|
.\" .I Smprintf
|
|
.\" and
|
|
.\" .I vsmprintf
|
|
.\" return a pointer to a string of an appropriate length;
|
|
.\" this pointer should be passed to
|
|
.\" .I free
|
|
.\" to release the associated storage
|
|
.\" when it is no longer needed.
|
|
.\" If sufficient space is not avaliable,
|
|
.\" .I smprintf
|
|
.\" and
|
|
.\" .I vsmprintf
|
|
.\" will return
|
|
.\" .SM
|
|
.\" .BR
|
|
.BR Snprintf
|
|
and
|
|
.BR vsnprintf
|
|
will write at most
|
|
.IR size
|
|
of the characters printed into the output string
|
|
(the
|
|
.I size
|
|
character then gets the terminating
|
|
.BR \e0 );
|
|
if the return value is greater than or equal to the
|
|
.I size
|
|
argument, the string was too short
|
|
and some of the printed characters were discarded.
|
|
.BR Sprintf
|
|
and
|
|
.BR vsprintf
|
|
effectively assume an infinite
|
|
.IR size .
|
|
.LP
|
|
The format string is composed of zero or more directives:
|
|
ordinary
|
|
.\" multibyte
|
|
characters (not
|
|
.BR % ),
|
|
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
|
|
.BR % .
|
|
The arguments must correspond properly (after type promotion)
|
|
with the conversion specifier.
|
|
After the
|
|
.BR % ,
|
|
the following appear in sequence:
|
|
.RS
|
|
.sp 1
|
|
Zero or more of the following flags:
|
|
.RS
|
|
A
|
|
.BR #
|
|
character
|
|
specifying that the value should be converted to an ``alternate form''.
|
|
For
|
|
.BR c ,
|
|
.BR d ,
|
|
.BR i ,
|
|
.BR n ,
|
|
.BR p ,
|
|
.BR s ,
|
|
and
|
|
.BR u ,
|
|
conversions, this option has no effect.
|
|
For
|
|
.BR 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
|
|
.BR x
|
|
and
|
|
.BR X
|
|
conversions, a non-zero result has the string
|
|
.BR 0x
|
|
(or
|
|
.BR 0X
|
|
for
|
|
.BR X
|
|
conversions) 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 it (normally, a decimal point appears in the results of
|
|
those conversions only if a digit follows).
|
|
For
|
|
.BR g
|
|
and
|
|
.BR G
|
|
conversions, trailing zeros are not removed from the result as they
|
|
would otherwise be.
|
|
.sp 1
|
|
A zero
|
|
.RB ( \&0 )
|
|
character specifying zero padding.
|
|
For all conversions except
|
|
.BR n ,
|
|
the converted value is padded on the left with zeros rather than blanks.
|
|
If a precision is given with a numeric conversion
|
|
.BR d ,
|
|
.BR i ,
|
|
.BR o ,
|
|
.BR u ,
|
|
.BR i ,
|
|
.BR x ,
|
|
and
|
|
.BR X ) ,
|
|
the
|
|
.BR \&0
|
|
flag is ignored.
|
|
.sp 1
|
|
A negative field width flag
|
|
.RB ( \- )
|
|
indicates the converted value is to be left adjusted on the field boundary.
|
|
Except for
|
|
.BR n
|
|
conversions, the converted value is padded on the right with blanks,
|
|
rather than on the left with blanks or zeros.
|
|
A
|
|
.B \-
|
|
overrides a
|
|
.B \&0
|
|
if both are given.
|
|
.sp 1
|
|
A space, specifying that a blank should be left before a positive number
|
|
produced by a signed conversion
|
|
.RB ( d ,
|
|
.BR e ,
|
|
.BR E ,
|
|
.BR f ,
|
|
.BR g ,
|
|
.BR G ,
|
|
or
|
|
.BR i ).
|
|
.sp 1
|
|
A
|
|
.B +
|
|
character specifying that a sign always be placed before a
|
|
number produced by a signed conversion.
|
|
A
|
|
.B +
|
|
overrides a space if both are used.
|
|
.RE
|
|
.sp 1
|
|
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.
|
|
.sp 1
|
|
An optional precision, in the form of a period
|
|
.RB ( \&. )
|
|
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
|
|
.BR d ,
|
|
.BR i ,
|
|
.BR o ,
|
|
.BR u ,
|
|
.BR x ,
|
|
and
|
|
.BR X
|
|
conversions, the number of digits to appear after the decimal-point for
|
|
.BR e ,
|
|
.BR E ,
|
|
and
|
|
.BR f
|
|
conversions, the maximum number of significant digits for
|
|
.BR g
|
|
and
|
|
.BR G
|
|
conversions, or the maximum number of characters to be printed from a
|
|
string for
|
|
.BR s
|
|
conversions.
|
|
.sp 1
|
|
The optional character
|
|
.BR h ,
|
|
specifying that a following
|
|
.BR d ,
|
|
.BR i ,
|
|
.BR o ,
|
|
.BR u ,
|
|
.BR x ,
|
|
or
|
|
.BR X
|
|
conversion corresponds to a
|
|
.IR "short int"
|
|
or
|
|
.IR "unsigned short int"
|
|
argument, or that a following
|
|
.BR n
|
|
conversion corresponds to a pointer to a
|
|
.IR "short int"
|
|
argument.
|
|
.sp 1
|
|
The optional character
|
|
.BR l
|
|
(ell) specifying that a following
|
|
.BR d ,
|
|
.BR i ,
|
|
.BR o ,
|
|
.BR u ,
|
|
.BR x ,
|
|
or
|
|
.BR X
|
|
conversion applies to a pointer to a
|
|
.IR "long int"
|
|
or
|
|
.IR "unsigned long int"
|
|
argument, or that a following
|
|
.BR n
|
|
conversion corresponds to a pointer to a
|
|
.IR "long int"
|
|
argument.
|
|
.sp 1
|
|
The optional character
|
|
.BR q ,
|
|
specifying that a following
|
|
.BR d ,
|
|
.BR i ,
|
|
.BR o ,
|
|
.BR u ,
|
|
.BR x ,
|
|
or
|
|
.BR X
|
|
conversion corresponds to a
|
|
.IR "quad int"
|
|
or
|
|
.IR "unsigned quad int"
|
|
argument, or that a following
|
|
.BR n
|
|
conversion corresponds to a pointer to a
|
|
.IR "quad int"
|
|
argument.
|
|
.sp 1
|
|
The character
|
|
.BR L
|
|
specifying that a following
|
|
.BR e ,
|
|
.BR E ,
|
|
.BR f ,
|
|
.BR g ,
|
|
or
|
|
.BR G
|
|
conversion corresponds to a
|
|
.IR "long double"
|
|
argument (but note that long double values are not currently supported
|
|
by the ORCA/C, VAX, and Tahoe compilers).
|
|
.sp 1
|
|
A character that specifies the type of conversion to be applied.
|
|
.RE
|
|
.LP
|
|
A field width or precision, or both, may be indicated by
|
|
an asterisk
|
|
.BR *
|
|
instead of a
|
|
digit string.
|
|
In this case, an
|
|
.IR 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.
|
|
.LP
|
|
The conversion specifiers and their meanings are:
|
|
.RS
|
|
.IP \fBdiouxX\fR
|
|
The
|
|
.IR int
|
|
(or appropriate variant) argument is converted to signed decimal
|
|
.RB ( d
|
|
and
|
|
.BR i ),
|
|
unsigned octal
|
|
.RB ( o ),
|
|
unsigned decimal
|
|
.RB ( u ),
|
|
or unsigned hexadecimal
|
|
.RB ( x
|
|
and
|
|
.BR X )
|
|
notation. The letters
|
|
.BR abcdef
|
|
are used for
|
|
.BR x
|
|
conversions; the letters
|
|
.BR ABCDEF
|
|
are used for
|
|
.BR 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.
|
|
.IP \fBDOU\fR
|
|
The
|
|
.IR "long int"
|
|
argument is converted to signed decimal, unsigned octal, or unsigned
|
|
decimal, as if the format had been
|
|
.BR ld ,
|
|
.BR lo ,
|
|
or
|
|
.BR lu
|
|
respectively.
|
|
These conversion characters are deprecated, and will eventually disappear.
|
|
.IP \fBeE\fR
|
|
The
|
|
.IR double
|
|
argument is rounded and converted in the style
|
|
.nf
|
|
[\-]\fId\fR\&.\fIddd\fRe(+|-)\fIdd\fR
|
|
.fi
|
|
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
|
|
.BR E
|
|
conversion uses the letter
|
|
.BR E
|
|
(rather than
|
|
.BR e )
|
|
to introduce the exponent.
|
|
The exponent always contains at least two digits; if the value is zero,
|
|
the exponent is 00.
|
|
.IP \fBf\fR
|
|
The
|
|
.IR double
|
|
argument is rounded and converted to decimal notation in the style
|
|
.nf
|
|
[-]\fIddd\fR\&.\fIddd\fR,
|
|
.fi
|
|
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.
|
|
.IP \fBg\fR
|
|
The
|
|
.IR double
|
|
argument is converted in style
|
|
.BR f
|
|
or
|
|
.BR e
|
|
(or
|
|
.BR E
|
|
for
|
|
.BR 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
|
|
.BR 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.
|
|
.IP \fBc\fR
|
|
The
|
|
.IR int
|
|
argument is converted to an
|
|
.IR "unsigned char" ,
|
|
and the resulting character is written.
|
|
.IP \fBs\fR
|
|
The
|
|
.I "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
|
|
.BR NULL
|
|
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
|
|
.BR NUL
|
|
character.
|
|
.IP \fBp\fR
|
|
The
|
|
.I "void *"
|
|
pointer argument is printed in hexadecimal (as if by
|
|
.BR %#x
|
|
or
|
|
.BR %#lx ).
|
|
.IP \fBn\fR
|
|
The number of characters written so far is stored into the
|
|
integer indicated by the
|
|
.I "int *"
|
|
(or variant) pointer argument.
|
|
No argument is converted.
|
|
.IP \fB%\fR
|
|
A
|
|
.BR %
|
|
is written. No argument is converted. The complete conversion specification
|
|
is
|
|
.BR %% .
|
|
.RE
|
|
.LP
|
|
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.
|
|
.LP
|
|
.SH EXAMPLES
|
|
To print a date and time in the form `Sunday, July 3, 10:02',
|
|
where
|
|
.IR weekday
|
|
and
|
|
.IR month
|
|
are pointers to strings:
|
|
.nf
|
|
|
|
#include <stdio.h>
|
|
fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
|
|
weekday, month, day, hour, min);
|
|
|
|
.fi
|
|
.LP
|
|
To print Pi
|
|
to five decimal places:
|
|
.nf
|
|
|
|
#include <math.h>
|
|
#include <stdio.h>
|
|
fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
|
|
|
|
.fi
|
|
.LP
|
|
To allocate a 128 byte string and print into it:
|
|
.nf
|
|
|
|
#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);
|
|
}
|
|
.fi
|
|
.SH SEE ALSO
|
|
.BR printf (1),
|
|
.BR scanf (3)
|
|
.SH STANDARDS
|
|
The
|
|
.BR fprintf ,
|
|
.BR printf ,
|
|
.BR sprintf ,
|
|
.BR vprintf ,
|
|
.BR vfprintf ,
|
|
and
|
|
.BR vsprintf
|
|
functions
|
|
conform to ANSI/C.
|
|
.SH HISTORY
|
|
The functions
|
|
.BR snprintf
|
|
and
|
|
.BR vsnprintf
|
|
are new to this release.
|
|
.SH BUGS
|
|
The ORCA/C stdio implementation also provides a
|
|
.BR %b
|
|
format specifier, for Pascal-type strings. This is not currently implemented.
|
|
.LP
|
|
The conversion formats
|
|
.BR \&%D ,
|
|
.BR \&%O ,
|
|
and
|
|
.BR %U
|
|
are not standard and
|
|
are provided only for backward compatibility.
|
|
The effect of padding the
|
|
.BR %p
|
|
format with zeros (either by the
|
|
.B 0
|
|
flag or by specifying a precision), and the benign effect (i.e., none)
|
|
of the
|
|
.B #
|
|
flag on
|
|
.BR %n
|
|
and
|
|
.BR %p
|
|
conversions, as well as other
|
|
nonsensical combinations such as
|
|
.BR %Ld ,
|
|
are not standard; such combinations
|
|
should be avoided.
|
|
.LP
|
|
Because
|
|
.BR sprintf
|
|
and
|
|
.BR vsprintf
|
|
assume an infinitely long string,
|
|
callers must be careful not to overflow the actual space;
|
|
this is often impossible to assure.
|
|
For safety, programmers should use the
|
|
.BR snprintf
|
|
interface instead.
|
|
Unfortunately, this interface is not portable.
|