--- cci/usr/src/man/man3/printf.3s	2019/07/28 12:24:19	1.1
+++ cci/usr/src/man/man3/printf.3s	2019/07/28 12:27:05	1.1.1.2
@@ -1,231 +1,392 @@
 .TH PRINTF 3S "1 April 1981"
 .SH NAME
-printf, fprintf, sprintf \- formatted output conversion
+printf, fprintf, sprintf \- print formatted output
 .SH SYNOPSIS
-.B #include <stdio.h>
+.B "#include <stdio.h>"
 .PP
-.B printf(format
-.RB [ ,
-arg ] ...
+.B "int printf (format"
+[
+.B ,
+arg ] .\|.\|.
 .B )
 .br
-.B char *format;
+.B "char \(**format;"
 .PP
-.B fprintf(stream, format
-.RB [ ,
-arg ] ...
+.B "int fprintf (stream, format"
+[
+.B ,
+arg ] .\|.\|.
 .B )
 .br
 .SM
 .B FILE
-.B *stream;
+.B \(**stream;
 .br
-.B char *format;
+.B "char \(**format;"
 .PP
-.B sprintf(s, format
-.RB [ ,
-arg ] ...
+.B "int sprintf (s, format"
+[
+.B ,
+arg ] .\|.\|.
 .B )
 .br
-.B char *s, format;
-.PP
-.B #include <varargs.h>
-.br
-.B _doprnt(format, args, stream)
-.br
-.B char *format;
-.br
-.B va_list *args;
-.br
-.B FILE *stream;
+.B "char \(**s, format;"
 .SH DESCRIPTION
-.I Printf
+.I Printf\^
 places output on the standard output stream
-.BR stdout .
-.I Fprintf
+.IR stdout .
+.I Fprintf\^
 places output on the named output
 .IR stream .
-.I Sprintf
-places `output' in the string
-.IR s ,
-followed by the character `\\0'.
-All of these routines work by calling the internal
-routine
-.B _doprnt,
-using the variable-length argument facilities of
-.IR varargs (3).
-.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 .
+.I Sprintf\^
+places ``output,''
+followed by the null character
+.RB ( \e0 ),
+in consecutive bytes starting at
+.RI \(** s ;
+it is the user's responsibility to ensure that
+enough storage is available.
+Each function returns the number of characters
+transmitted (not including the
+.B \e0
+in the case of
+.IR sprintf ),
+or
+a negative value if an output error was encountered.
 .PP
-Each conversion specification is introduced by the character
+Each of these functions
+converts, formats, and prints its
+.IR arg s
+under control of the
+.IR format .
+The
+.I format\^
+is a character string
+that contains
+two types of objects:
+plain characters, which are simply copied to the
+output stream,
+and conversion specifications,
+each of which results in fetching of
+zero or more
+.IR arg s.
+The results are undefined if there are insufficient
+.IR arg s
+for the format.
+If the format is exhausted while
+.IR arg s
+remain, the excess
+.IR arg s
+are simply ignored.
+.PP
+Each conversion specification is introduced by
+the character
 .BR % .
-Following the
+After the
 .BR % ,
-there may be
-.TP
-.B \(bu
-an optional minus sign `\-' which specifies
-.I "left adjustment"
-of the converted value in the indicated field;
-.TP
-.B \(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
-.B \(bu
-an optional period
-.RB ` . '
-which serves to separate the field width from the next digit string;
-.TP
-.B \(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
-.B \(bu
-the character
+the following
+appear in sequence:
+.PP
+.RS
+Zero or more
+.IR flags ,
+which modify the meaning of
+the conversion specification.
+.PP
+An optional decimal digit string specifying a minimum
+.IR "field width" .
+If the converted value has fewer characters
+than the field width,
+it will be padded on the left (or right,
+if the left-adjustment flag `\-', described below, has been
+given) to the field width.
+If the field width for an s conversion is preceded by a 0, the
+string is right adjusted with zero-padding on the left.
+.PP
+A
+.I precision\^
+that gives
+the minimum number of digits to appear for the
+.BR d ,
+.BR o ,
+.BR u ,
+.BR x ,
+or
+.B X
+conversions,
+the number of digits to appear after the
+decimal point for the
+.B e
+and
+.B f
+conversions,
+the maximum number of significant digits
+for the
+.B g
+conversion,
+or the maximum number of characters
+to be printed from a string in
+.B s
+conversion.
+The precision takes the form of a period
+.RB ( \&. )
+followed by a decimal digit string;
+a null digit string is treated as zero.
+.PP
+An optional
 .B l
-specifying that a following
+(ell) specifying that a following
 .BR d ,
 .BR o ,
+.BR u ,
 .BR x ,
 or
-.B u
-corresponds to a long integer
+.B X
+conversion character applies to a long
+integer
 .IR arg .
-.TP
-.B \(bu
-a character which indicates the type of
+An
+.B l
+before any other conversion character is ignored.
+.PP
+A character that indicates the type of
 conversion to be applied.
+.RE
 .PP
-A field width or precision may be `*' instead of a digit string.
-In this case an integer
-.I arg
+A field width or precision may be
+indicated by an asterisk
+.RB ( \(** )
+instead of a digit string.
+In this case, an integer
+.I arg\^
 supplies
 the field width or precision.
+The
+.I arg\^
+that is actually converted is not fetched until
+the conversion letter is seen, so the
+.IR arg s
+specifying field width or precision must appear
+.I before\^
+the
+.I arg\^
+(if any) to be converted.
+.PP
+The flag characters and their meanings are:
+.PD 0
+.TP 10
+.B \-
+The result of the conversion will be left-justified within the field.
+.TP
+.B +
+The result of a signed
+conversion will always begin with a sign
+.RB ( +
+or
+.BR \- ).
+.TP
+blank
+If the first character of a signed conversion is not a sign, a blank
+will be prefixed to the result.
+This implies that if the blank and
+.B +
+flags both appear, the blank flag will be ignored.
+.TP
+.B #
+This flag specifies that the value is to be converted
+to an ``alternate form.''\ 
+For
+.BR c ,
+.BR d ,
+.BR s ,
+and
+.B u
+conversions, the flag has no effect.
+For
+.B o
+conversion, it increases the precision to force
+the first digit of the result to be a zero.
+For
+.B x or X
+conversion, a non-zero result will have
+.B 0x or 0X
+prefixed to it.
+For
+.BR e ,
+.BR E ,
+.BR f ,
+.BR g ,
+and
+.B G
+conversions, the result will always contain a decimal point,
+even if no digits follow the point (normally, a decimal point
+appears in the result of these conversions only if a digit
+follows it).
+For
+.B g
+and
+.B G
+conversions, trailing zeroes will
+.I not\^
+be removed from the result
+(which they normally are).
+.PD
 .PP
 The conversion characters
-and their meanings are
-.TP
-.B dox
+and their meanings are:
+.PP
+.PD 0
+.TP 10
+\f3d\fP,\f3o\fP,\f3u\fP,\f3x\fP,\f3X\fP
 The integer
-.I arg
-is converted to decimal, octal, or
-hexadecimal notation respectively.
+.I arg\^
+is converted to signed decimal,
+unsigned octal, decimal, or
+hexadecimal notation
+.RB ( x
+and
+.BR X ),
+respectively;
+the letters
+.B abcdef
+are used for
+.B x
+conversion and the letters
+.SM
+.B ABCDEF
+for
+.B X
+conversion.
+The precision specifies the minimum number of digits
+to appear; if the value being converted can be represented
+in fewer digits, it will be expanded with leading blanks.
+(For compatibility with older versions,
+padding with leading zeroes may alternatively be specified by
+prepending a zero to the field width.
+This does not imply an octal value for the field width.)
+The default precision is 1.
+The result of converting a zero value with a precision
+of zero is a null string.
 .TP
-.B f
+.BR f
 The float or double
-.I arg
+.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.
+in the style ``[\f3\-\fP]ddd\f3.\fPddd,''
+where the number of digits after the decimal point
+is equal to the precision specification.
 If the precision
 is missing,
-6 digits are given;
-if the precision is explicitly 0, no digits and
-no decimal point are printed.
+six digits are output;
+if the precision is explicitly 0,
+no decimal point appears.
 .TP
-.B e
+.BR e , E
 The float or double
-.I arg
+.I arg\^
 is converted in the style
-`[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd'
+``[\f3\-\fP]d\f3.\fPddd\f3e\(+-\fPdd,''
 where there is one digit before the decimal point and
-the number after is equal to the
-precision specification for the argument;
+the number of digits after it is equal to the
+precision;
 when the precision is missing,
-6 digits are produced.
+six digits are produced;
+if the precision is zero, no decimal point appears.
+The
+.B E
+format code will produce a number with
+.B E
+instead of
+.B e
+introducing the exponent.
+The exponent always contains at least two digits.
 .TP
-.B g
+.BR g , G
 The float or double
-.I arg
+.I arg\^
 is printed in style
-.BR d ,
-in style
-.BR f ,
-or in
+.BR f
+or
+.BR e
+(or in style
+.B E
+in the case of a
+.B G
+format code),
+with the precision specifying the number of significant digits.
+The style used depends on the value converted:
 style
-.BR e ,
-whichever gives full precision in minimum space.
+.B e
+will be used only if the exponent resulting from
+the conversion is less than \-4 or greater than the precision.
+Trailing zeroes are removed from the result; a decimal point
+appears only if it is followed by a digit.
 .TP
 .B c
 The character
-.I arg
+.I arg\^
 is printed.
 .TP
 .B s
-.I Arg
+The
+.I arg\^
 is taken to be a string (character pointer)
 and characters from the string are printed until
-a null character or until
+a null character
+.RB ( \e0 )
+is encountered or
 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 Power 6/32).
+specification is reached.
+If the precision is missing, it is taken to be infinite, so
+all characters up to the first null character are printed.
+A 
+.SM NULL
+value for
+.I arg\^
+will yield undefined results.
 .TP
 .B %
-Print a `%'; no argument is converted.
+Print a
+.BR % ;
+no argument is converted.
+.PD
 .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.
+if the result of a conversion is wider than the field width,
+the field is simply expanded to contain the conversion result.
 Characters generated by
-.I printf
-are printed by 
-.IR putc (3S).
-.PP
-.B Examples
-.br
-To print a date and time in the form `Sunday, July 3, 10:02',
+.I printf\^
+and
+.I fprintf\^
+are printed as if
+.IR putc (3S)
+had been called.
+.SH EXAMPLES
+To print a date and time in the form ``Sunday, July 3, 10:02,''
 where
-.I weekday
+.I weekday\^
 and
-.I month
+.I month\^
 are pointers to null-terminated strings:
 .RS
-.HP
 .nh
-printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min);
+.PP
+printf("%s,\ %s\ %d,\ %d\fB:\fP%\fB.\fP2d",\ weekday,\ month,\ day,\ hour,\ min);
 .RE
-.hy
 .PP
+.hy 14
 To print
-.if n pi
+.if n .I pi\^
 .if t \(*p
-to 5 decimals:
-.IP
-printf("pi = %.5f", 4*atan(1.0));
-.SH "SEE ALSO"
+to 5 decimal places:
+.RS
+.PP
+printf("pi \|= \|%\f3.\fP5f", \|4 \(** atan(1\f3.\fP0));
+.RE
+.SH SEE ALSO
+ecvt(3C),
 putc(3S),
 scanf(3S),
-ecvt(3)
-.SH BUGS
-Very wide fields (>128 characters) fail.
-.br
-Due to the large size of the floating-point emulating package,
-the `e', `f' and `g' formats are only available
-with the `-lf' loader flag; otherwise a `?' is printed.
+stdio(3S).
+.\"	%W% of %G%