1 files changed, 225 insertions, 96 deletions
diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3
index 784bb77..d9cbd95 100644
--- a/lib/libc/stdio/printf.3
+++ b/lib/libc/stdio/printf.3
@@ -36,7 +36,7 @@
 .\"     @(#)printf.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd June 4, 1993
+.Dd November 8, 2001
 .Dt PRINTF 3
 .Os
 .Sh NAME
@@ -191,12 +191,9 @@ 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
+.Bl -tag -width ".So \&\ \& Sc (space)" -compact -offset indent
+.It Sq Cm #
+The value should be converted to an
 .Dq alternate form .
 For
 .Cm c , d , i , n , p , s ,
@@ -220,7 +217,7 @@ for
 .Cm X
 conversions) prepended to it.
 For
-.Cm e , E , f , g ,
+.Cm a , A , e , E , f , F , g ,
 and
 .Cm G
 conversions, the result will always contain a decimal point, even if no
@@ -232,11 +229,8 @@ and
 .Cm G
 conversions, trailing zeros are not removed from the result as they
 would otherwise be.
-.It
-A
-.Cm 0
-(zero)
-character specifying zero padding.
+.It So Cm 0 Sc (zero)
+Zero padding.
 For all conversions except
 .Cm n ,
 the converted value is padded on the left with zeros rather than blanks.
@@ -247,10 +241,9 @@ and
 the
 .Cm 0
 flag is ignored.
-.It
-A negative field width flag
-.Cm \-
-indicates the converted value is to be left adjusted on the field boundary.
+.It Sq Cm \&\-
+A negative field width flag;
+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,
@@ -260,20 +253,30 @@ A
 overrides a
 .Cm 0
 if both are given.
-.It
-A space, specifying that a blank should be left before a positive number
+.It So \&\ \& Sc (space)
+A blank should be left before a positive number
 produced by a signed conversion
-.Cm ( d , e , E , f , g , G ,
+.Cm ( a , A , d , e , E , f , F , g , G ,
 or
 .Cm i ) .
-.It
-A
-.Cm +
-character specifying that a sign always be placed before a
+.It Sq Cm +
+A sign must always be placed before a
 number produced by a signed conversion.
 A
 .Cm +
 overrides a space if both are used.
+.It Sq Cm '
+Decimal conversions
+.Cm ( d , u ,
+or
+.Cm i )
+or the integral portion of a floating point conversion
+.Cm ( f
+or
+.Cm F )
+should be grouped and separated by thousands using
+the non-monetary seperator returned by
+.Xr localeconv 3 .
 .El
 .It
 An optional decimal digit string specifying a minimum field width.
@@ -292,9 +295,9 @@ This gives the minimum number of digits to appear for
 and
 .Cm X
 conversions, the number of digits to appear after the decimal-point for
-.Cm e , E ,
+.Cm a , A , e , E , f ,
 and
-.Cm f
+.Cm F
 conversions, the maximum number of significant digits for
 .Cm g
 and
@@ -304,79 +307,69 @@ string for
 .Cm s
 conversions.
 .It
-The optional character
-.Cm h ,
-specifying that a following
-.Cm d , i , o , u , x ,
+An optional length modifier, that specifies the size of the argument.
+The following length modifiers are valid for the
+.Cm d , i , n , o , u , x ,
 or
 .Cm X
-conversion corresponds to a
-.Vt short int
-or
-.Vt unsigned short int
-argument, or that a following
-.Cm n
-conversion corresponds to a pointer to a
-.Vt short int
-argument.
-.It
-The optional character
-.Cm l
-(ell) specifying that a following
-.Cm d , i , o , u , x ,
-or
-.Cm X
-conversion applies to a pointer to a
-.Vt long int
-or
-.Vt unsigned long int
-argument, or that a following
-.Cm n
-conversion corresponds to a pointer to a
-.Vt long int
-argument.
-.It
-The optional characters
-.Cm ll
-(ell ell) specifying that a following
-.Cm d , i , o , u , x ,
-or
-.Cm X
-conversion applies to a pointer to a
-.Vt long long int
-or
-.Vt unsigned long long int
-argument, or that a following
-.Cm n
-conversion corresponds to a pointer to a
-.Vt long long int
-argument.
-.It
-The optional character
-.Cm q ,
-specifying that a following
-.Cm d , i , o , u , x ,
+conversion:
+.Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt unsigned long long *"
+.It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
+.It Cm hh Ta Vt signed char Ta Vt unsigned char Ta Vt signed char *
+.It Cm h Ta Vt short Ta Vt unsigned short Ta Vt short *
+.It Cm l No (ell) Ta Vt long Ta Vt unsigned long Ta Vt long *
+.It Cm ll No (ell ell) Ta Vt long long Ta Vt unsigned long long Ta Vt long long *
+.It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt intmax_t *
+.It Cm t Ta Vt ptrdiff_t Ta Sy * Ta Vt ptrdiff_t *
+.It Cm z Ta Sy * Ta Vt size_t Ta Sy *
+.It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt quad_t *
+.El
+.Pp
+.Bl -tag -width ".Cm * No -"
+.It Cm * No -
+The
+.Cm t
+modifier, when applied to a
+.Cm o , u , x ,
 or
 .Cm X
-conversion corresponds to a
-.Vt quad int
-or
-.Vt unsigned quad int
-argument, or that a following
+conversion, indicates that the argument is of an unsigned type
+equivalent in size to a
+.Vt ptrdiff_t .
+The
+.Cm z
+modifier, when applied to a
+.Cm d or
+.Cm i
+conversion, indicates that the argument is of a signed type equivalent in
+size to a
+.Vt size_t .
+Similarly, when applied to an
 .Cm n
-conversion corresponds to a pointer to a
-.Vt quad int
-argument.
-.It
-The character
-.Cm L
-specifying that a following
-.Cm e , E , f , g ,
+conversion, it indicates that the argument is a pointer to a signed type
+equivalent in size to a
+.Vt size_t .
+.El
+.Pp
+The following length modifier is valid for the
+.Cm a , A , e , E , f , F , g ,
 or
 .Cm G
-conversion corresponds to a
-.Vt long double
-argument.
+conversion:
+.Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G"
+.It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
+.It Cm L Ta Vt long double
+.El
+.Pp
+The following length modifier is valid for the
+.Cm c
+or
+.Cm s
+conversion:
+.Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
+.It Sy Modifier Ta Cm c Ta Cm s
+.It Cm l No (ell) Ta Vt wint_t Ta Vt wchar_t *
+.El
 .It
 A character that specifies the type of conversion to be applied.
 .El
@@ -457,7 +450,26 @@ conversion uses the letter
 to introduce the exponent.
 The exponent always contains at least two digits; if the value is zero,
 the exponent is 00.
-.It Cm f
+.Pp
+For
+.Cm a , A , e , E , f , F , g ,
+and
+.Cm G
+conversions, positive and negative infinity are represented as
+.Li inf
+and
+.Li -inf
+respectively when using the lowercase conversion character, and
+.Li INF
+and 
+.Li -INF
+respectively when using the uppercase conversion character.
+Similarly, NaN is represented as
+.Li nan
+when using the lowercase conversion, and
+.Li NAN
+when using the uppercase conversion.
+.It Cm fF
 The
 .Vt double
 argument is rounded and converted to decimal notation in the style
@@ -475,6 +487,8 @@ argument is converted in style
 or
 .Cm e
 (or
+.Cm F
+or
 .Cm E
 for
 .Cm G
@@ -488,12 +502,74 @@ 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 aA
+The
+.Vt double
+argument is converted to hexadecimal notation in the style
+.Oo \- Oc Ns 0xh Ns Cm \&. Ns hhhp Ns Oo +- Oc Ns d ,
+where the number of digits after the hexadecimal-point character
+is equal to the precision specification.
+If the precision is missing, it is taken as enough to exactly
+represent the floating-point number; if the precision is
+explicitly zero, no hexadecimal-point character appears.
+This is an exact coversion of the mantissa+exponent internal
+floating point representation; the
+.Oo \- Oc Ns 0xh Ns Cm \&. Ns hhh
+portion represents exactly the mantissa; only denormalized
+mantissas have a zero value to the left of the hexadecimal
+point.
+The
+.Cm p
+is a literal character
+.Qq p ;
+the exponent is preceded by a positive or negative sign
+and is represented in decimal, using only enough characters
+to represent the exponent.
+The
+.Cm A
+conversion uses the prefix
+.Cm 0X
+(rather than
+.Cm 0x ) ,
+the letters
+.Cm ABCDEF
+(rather than
+.Cm abcdef )
+to represent the hex digits, and the letter
+.Cm P
+(rather than
+.Cm p )
+to seperate the mantissa and exponent.
+
+.It Cm C
+Treated as
+.Cm c
+with the
+.Cm l
+(ell) modifier.
 .It Cm c
 The
 .Vt int
 argument is converted to an
 .Vt unsigned char ,
 and the resulting character is written.
+.Pp
+If the
+.Cm l
+(ell) modifier is used, the
+.Vt wint_t
+argument shall be converted to a
+.Vt wchar_t ,
+and the (potentially multi-byte) sequence representing the
+single wide character is written, including any shift sequences.
+If a shift sequence is used, the shift state is also restored
+to the original state after the character.
+.It Cm S
+Treated as
+.Cm s
+with the
+.Cm l
+(ell) modifier.
 .It Cm s
 The
 .Vt char *
@@ -510,6 +586,30 @@ 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.
+.Pp
+If the
+.Cm l
+(ell) modifier is used, the
+.Vt wchar_t *
+argument is expected to be a pointer to an array of wide characters
+(pointer to a wide string).
+For each wide character in the string, the (potentially multi-byte)
+sequence representing the
+wide character is written, including any shift sequences.
+If any shift sequence is used, the shift state is also restored
+to the original state after the string.
+Wide characters from the array are written up to (but not including)
+a terminating wide
+.Dv NUL
+character;
+if a precision is specified, no more than the number of bytes specified are
+written (including shift sequences).  Partial characters are never written.
+If a precision is given, no null character
+need be present; if the precision is not specified, or is greater than
+the number of bytes required to render the multibyte representation of
+the string, the array must contain a terminating wide
+.Dv NUL
+character.
 .It Cm p
 The
 .Vt void *
@@ -538,7 +638,8 @@ character is defined in the program's locale (category
 .Dv LC_NUMERIC ) .
 .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
+a numeric field; if the result of a conversion is wider than the field
+width, the
 field is expanded to contain the conversion result.
 .Sh EXAMPLES
 To print a date and time in the form
@@ -581,7 +682,8 @@ char *newfmt(const char *fmt, ...)
 .Ed
 .Sh SEE ALSO
 .Xr printf 1 ,
-.Xr scanf 3
+.Xr scanf 3 ,
+.Xr setlocale 3
 .Sh STANDARDS
 The
 .Fn fprintf ,
@@ -675,4 +777,31 @@ for later interpolation by
 .Pp
 Always use the proper secure idiom:
 .Pp
-.Dl snprintf(buffer, sizeof(buffer), "%s", string);
+.Dl snprintf(buffer, sizeof(buffer), \*q%s\*q, string);
+.Pp
+The
+.Nm
+family of functions currently lack the ability to use the
+.Qq '
+flag in conjunction with the
+.Qq f
+conversion specifier.  The
+.Qq a
+and
+.Qq A
+conversion specifiers have not yet been implemented.
+The
+.Qq l
+(ell) modifier for the
+.Qq c
+and
+.Qq s
+conversion specifiers, for wide characters and strings, have not yet
+been implemented.
+The
+.Qq L
+modifier for floating point formats simply round the
+.Vt long double
+argument to
+.Vt double ,
+providing no additional precision.