initial import of NetBSD tree

1 files changed, 640 insertions, 0 deletions

diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3
new file mode 100644
index 00000000000..fb13c4f1008
--- /dev/null
+++ b/lib/libc/stdio/printf.3
@@ -0,0 +1,640 @@
+.\"	$NetBSD: printf.3,v 1.5 1995/02/02 01:15:49 jtc Exp $
+.\"
+.\" 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
+.\"
+.Dd June 4, 1993
+.Dt PRINTF 3
+.Os
+.Sh NAME
+.Nm printf ,
+.Nm fprintf ,
+.Nm sprintf ,
+.Nm snprintf ,
+.Nm vprintf ,
+.Nm vfprintf,
+.Nm vsprintf ,
+.Nm vsnprintf
+.Nd formatted output conversion
+.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 smprintf "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" "char *format" "va_list ap"
+.Ft int
+.Fn vsnprintf "char *str" "size_t size" "const char *format" "va_list ap"
+.\" .Ft int
+.\" .Fn vsmprintf "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 .
+.\" .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
+.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.
+.\" Except for
+.\" .I smprintf
+.\" and
+.\" .IR vsmprintf ,
+.\" all of these functions return
+These functions return
+the number of characters printed
+(not including the trailing
+.Ql \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
+.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.
+.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
+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 ( Mc 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 (but note that long double values are not currently supported
+by the
+.Tn VAX
+and
+.Tn Tahoe
+compilers).
+.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 *
+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.
+.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 g
+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 snprintf
+and
+.Fn vsnprintf
+are new to this release.
+.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 impossible to assure.
+For safety, programmers should use the
+.Fn snprintf
+interface instead.
+Unfortunately, this interface is not portable.