Libc-1158.50.2.tar.gz

[apple/libc.git] / stdio / FreeBSD / printf.3

diff --git a/stdio/FreeBSD/printf.3 b/stdio/FreeBSD/printf.3
index a14c8feff0f58c2023fa44aa9dbcadecc822c584..850fa989ef576f90999ad7cd361ac52bdc86e3c0 100644 (file)
--- a/stdio/FreeBSD/printf.3
+++ b/stdio/FreeBSD/printf.3
@@ -13,10 +13,6 @@
 .\" 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.
 .\" 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.
 .\" 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.


@@ -34,14 +30,14 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)printf.3   8.1 (Berkeley) 6/4/93
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)printf.3   8.1 (Berkeley) 6/4/93

-.\" $FreeBSD: src/lib/libc/stdio/printf.3,v 1.58 2004/10/16 16:00:01 stefanf Exp $
+.\" $FreeBSD$

 .\"
 .\"

-.Dd October 16, 2004
+.Dd December 2, 2009

 .Dt PRINTF 3
 .Os
 .Sh NAME
 .Dt PRINTF 3
 .Os
 .Sh NAME

-.Nm printf , fprintf , sprintf , snprintf , asprintf ,
-.Nm vprintf , vfprintf, vsprintf , vsnprintf , vasprintf
+.Nm printf , fprintf , sprintf , snprintf , asprintf , dprintf ,
+.Nm vprintf , vfprintf, vsprintf , vsnprintf , vasprintf, vdprintf

 .Nd formatted output conversion
 .Sh LIBRARY
 .Lb libc
 .Nd formatted output conversion
 .Sh LIBRARY
 .Lb libc


@@ -57,6 +53,8 @@
 .Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ...
 .Ft int
 .Fn asprintf "char **ret" "const char *format" ...
 .Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ...
 .Ft int
 .Fn asprintf "char **ret" "const char *format" ...

+.Ft int
+.Fn dprintf "int fd" "const char * restrict format" ...

 .In stdarg.h
 .Ft int
 .Fn vprintf "const char * restrict format" "va_list ap"
 .In stdarg.h
 .Ft int
 .Fn vprintf "const char * restrict format" "va_list ap"


@@ -68,6 +66,8 @@
 .Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
 .Ft int
 .Fn vasprintf "char **ret" "const char *format" "va_list ap"
 .Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
 .Ft int
 .Fn vasprintf "char **ret" "const char *format" "va_list ap"

+.Ft int
+.Fn vdprintf "int fd" "const char * restrict format" "va_list ap"

 .Sh DESCRIPTION
 The
 .Fn printf
 .Sh DESCRIPTION
 The
 .Fn printf


@@ -87,6 +87,10 @@ and
 .Fn vfprintf
 write output to the given output
 .Fa stream ;
 .Fn vfprintf
 write output to the given output
 .Fa stream ;

+.Fn dprintf
+and
+.Fn vdprintf
+write output to the given file descriptor;

 .Fn sprintf ,
 .Fn snprintf ,
 .Fn vsprintf ,
 .Fn sprintf ,
 .Fn snprintf ,
 .Fn vsprintf ,


@@ -101,6 +105,12 @@ and
 dynamically allocate a new string with
 .Xr malloc 3 .
 .Pp
 dynamically allocate a new string with
 .Xr malloc 3 .
 .Pp

+Extended locale versions of these functions are documented in
+.Xr printf_l 3 .
+See
+.Xr xlocale 3
+for more information.
+.Pp

 These functions write the output under the control of a
 .Fa format
 string that specifies how subsequent arguments
 These functions write the output under the control of a
 .Fa format
 string that specifies how subsequent arguments


@@ -108,20 +118,6 @@ string that specifies how subsequent arguments
 .Xr stdarg 3 )
 are converted for output.
 .Pp
 .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) or a negative value if an output error occurs,
-except for
-.Fn snprintf
-and
-.Fn vsnprintf ,
-which return the number of characters that would have been printed if the
-.Fa size
-were unlimited
-(again, not including the final
-.Ql \e0 ) .
-.Pp

 The
 .Fn asprintf
 and
 The
 .Fn asprintf
 and


@@ -159,15 +155,23 @@ 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.
 .Fa size
 argument, the string was too short
 and some of the printed characters were discarded.

-The output is always null-terminated.
+The output is always null-terminated, unless
+.Fa size
+is 0.

 .Pp
 The
 .Fn sprintf
 and
 .Fn vsprintf
 functions
 .Pp
 The
 .Fn sprintf
 and
 .Fn vsprintf
 functions

-effectively assume an infinite
-.Fa size .
+effectively assume a
+.Fa size
+of
+.Dv INT_MAX + 1.
+.Pp
+For those routines that write to a user-provided character string,
+that string and the format strings should not overlap, as the
+behavior is undefined.

 .Pp
 The format string is composed of zero or more directives:
 ordinary
 .Pp
 The format string is composed of zero or more directives:
 ordinary


@@ -211,8 +215,7 @@ conversions, this option has no effect.
 For
 .Cm o
 conversions, the precision of the number is increased to force the first
 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).
+character of the output string to a zero.

 For
 .Cm x
 and
 For
 .Cm x
 and


@@ -273,7 +276,7 @@ number produced by a signed conversion.
 A
 .Cm +
 overrides a space if both are used.
 A
 .Cm +
 overrides a space if both are used.

-.It Sq Cm '
+.It So "'" Sc (apostrophe)

 Decimal conversions
 .Cm ( d , u ,
 or
 Decimal conversions
 .Cm ( d , u ,
 or


@@ -287,6 +290,20 @@ the non-monetary separator returned by
 .Xr localeconv 3 .
 .El
 .It
 .Xr localeconv 3 .
 .El
 .It

+An optional separator character (
+.Cm \ , | \;  | \ : | _
+) used for separating multiple values when printing an AltiVec or SSE vector,
+or other multi-value unit.
+.Pp
+NOTE: This is an extension to the
+.Fn printf
+specification.
+Behaviour of these values for
+.Fn printf 
+is only defined for operating systems conforming to the 
+AltiVec Technology Programming Interface Manual.
+(At time of writing this includes only Mac OS X 10.2 and later.)
+.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
 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


@@ -379,6 +396,34 @@ conversion:
 .It Sy Modifier Ta Cm c Ta Cm s
 .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
 .El
 .It Sy Modifier Ta Cm c Ta Cm s
 .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
 .El

+.Pp
+The AltiVec Technology Programming Interface Manual also defines five additional length modifiers
+which can be used (in place of the conventional length modifiers) for the printing of AltiVec or SSE vectors:
+.Bl -tag -compact
+.It Cm v
+Treat the argument as a vector value, unit length will be determined by the conversion
+specifier (default = 16 8-bit units for all integer conversions, 
+4 32-bit units for floating point conversions).
+.It Cm vh, hv
+Treat the argument as a vector of 8 16-bit units.
+.It Cm vl, lv
+Treat the argument as a vector of 4 32-bit units.
+.El
+.Pp
+NOTE: The vector length specifiers are extensions to the
+.Fn printf
+specification.
+Behaviour of these values for
+.Fn printf 
+is only defined for operating systems conforming to the 
+AltiVec Technology Programming Interface Manual.
+(At time of writing this includes only Mac OS X 10.2 and later.)
+.Pp
+As a further extension, for SSE2 64-bit units:
+.Bl -tag -compact
+.It Cm vll, llv
+Treat the argument as a vector of 2 64-bit units.
+.El

 .It
 A character that specifies the type of conversion to be applied.
 .El
 .It
 A character that specifies the type of conversion to be applied.
 .El


@@ -445,7 +490,7 @@ The
 .Vt double
 argument is rounded and converted in the style
 .Sm off
 .Vt double
 argument is rounded and converted in the style
 .Sm off

-.Oo \- Oc Ar d Li \&. Ar ddd Li e \\*[Pm] Ar dd
+.Oo \- Oc Ar d Li \&. Ar ddd Li e \(+- Ar dd

 .Sm on
 where there is one digit before the
 decimal-point character
 .Sm on
 where there is one digit before the
 decimal-point character


@@ -521,7 +566,7 @@ The
 .Vt double
 argument is rounded and converted to hexadecimal notation in the style
 .Sm off
 .Vt double
 argument is rounded and converted to hexadecimal notation in the style
 .Sm off

-.Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \\*[Pm] Oc Ar d ,
+.Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \(+- Oc Ar d ,

 .Sm on
 where the number of digits after the hexadecimal-point character
 is equal to the precision specification.
 .Sm on
 where the number of digits after the hexadecimal-point character
 is equal to the precision specification.


@@ -553,7 +598,7 @@ to separate the mantissa and exponent.
 Note that there may be multiple valid ways to represent floating-point
 numbers in this hexadecimal format.
 For example,
 Note that there may be multiple valid ways to represent floating-point
 numbers in this hexadecimal format.
 For example,

-.Li 0x3.24p+0 , 0x6.48p-1
+.Li 0x1.92p+1 , 0x3.24p+0 , 0x6.48p-1 ,

 and
 .Li 0xc.9p-2
 are all equivalent.
 and
 .Li 0xc.9p-2
 are all equivalent.


@@ -665,6 +710,21 @@ In no case does a non-existent or small field width cause truncation of
 a numeric field; if the result of a conversion is wider than the field
 width, the
 field is expanded to contain the conversion result.
 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 RETURN VALUES
+These functions return the number of characters printed
+(not including the trailing
+.Ql \e0
+used to end output to strings),
+except for
+.Fn snprintf
+and
+.Fn vsnprintf ,
+which return the number of characters that would have been printed if the
+.Fa size
+were unlimited
+(again, not including the final
+.Ql \e0 ) .
+These functions return a negative value if an error occurs.

 .Sh EXAMPLES
 To print a date and time in the form
 .Dq Li "Sunday, July 3, 10:02" ,
 .Sh EXAMPLES
 To print a date and time in the form
 .Dq Li "Sunday, July 3, 10:02" ,


@@ -704,6 +764,106 @@ char *newfmt(const char *fmt, ...)
        return (p);
 }
 .Ed
        return (p);
 }
 .Ed

+.Sh COMPATIBILITY
+The conversion formats
+.Cm \&%D , \&%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
+.Cm 0
+flag or by specifying a precision), and the benign effect (i.e., none)
+of the
+.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.
+.Sh ERRORS
+In addition to the errors documented for the
+.Xr write 2
+system call, the
+.Fn printf
+family of functions may fail if:
+.Bl -tag -width Er
+.It Bq Er EILSEQ
+An invalid wide character code was encountered.
+.It Bq Er ENOMEM
+Insufficient storage space is available.
+.El
+.Sh SEE ALSO
+.Xr printf 1 ,
+.Xr printf_l 3 ,
+.Xr fmtcheck 3 ,
+.Xr scanf 3 ,
+.Xr setlocale 3 ,
+.Xr stdarg 3 ,
+.Xr wprintf 3
+.Sh STANDARDS
+Subject to the caveats noted in the
+.Sx BUGS
+section below, the
+.Fn fprintf ,
+.Fn printf ,
+.Fn sprintf ,
+.Fn vprintf ,
+.Fn vfprintf ,
+and
+.Fn vsprintf
+functions
+conform to
+.St -ansiC
+and
+.St -isoC-99 .
+With the same reservation, the
+.Fn snprintf
+and
+.Fn vsnprintf
+functions conform to
+.St -isoC-99 ,
+while
+.Fn dprintf
+and
+.Fn vdprintf
+conform to
+.St -p1003.1-2008 .
+.Sh HISTORY
+The functions
+.Fn asprintf
+and
+.Fn vasprintf
+first appeared in the
+.Tn GNU C
+library.
+These were implemented by
+.An Peter Wemm Aq Mt peter@FreeBSD.org
+in
+.Fx 2.2 ,
+but were later replaced with a different implementation
+from
+.Ox 2.3
+by
+.An Todd C. Miller Aq Mt Todd.Miller@courtesan.com .
+The
+.Fn dprintf
+and
+.Fn vdprintf
+functions were added in
+.Fx 8.0 .
+.Sh BUGS
+The
+.Nm
+family of functions do not correctly handle multibyte characters in the
+.Fa format
+argument.

 .Sh SECURITY CONSIDERATIONS
 The
 .Fn sprintf
 .Sh SECURITY CONSIDERATIONS
 The
 .Fn sprintf


@@ -775,94 +935,3 @@ for later interpolation by
 Always use the proper secure idiom:
 .Pp
 .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"
 Always use the proper secure idiom:
 .Pp
 .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"

-.Sh ERRORS
-In addition to the errors documented for the
-.Xr write 2
-system call, the
-.Fn printf
-family of functions may fail if:
-.Bl -tag -width Er
-.It Bq Er EILSEQ
-An invalid wide character code was encountered.
-.It Bq Er ENOMEM
-Insufficient storage space is available.
-.El
-.Sh SEE ALSO
-.Xr printf 1 ,
-.Xr fmtcheck 3 ,
-.Xr scanf 3 ,
-.Xr setlocale 3 ,
-.Xr wprintf 3
-.Rs
-.%T "The FreeBSD Security Architecture"
-.Re
-(See
-.Pa "/usr/share/doc/{to be determined}" . )
-.Sh STANDARDS
-Subject to the caveats noted in the
-.Sx BUGS
-section below, the
-.Fn fprintf ,
-.Fn printf ,
-.Fn sprintf ,
-.Fn vprintf ,
-.Fn vfprintf ,
-and
-.Fn vsprintf
-functions
-conform to
-.St -ansiC
-and
-.St -isoC-99 .
-With the same reservation, the
-.Fn snprintf
-and
-.Fn vsnprintf
-functions conform to
-.St -isoC-99 .
-.Sh HISTORY
-The functions
-.Fn asprintf
-and
-.Fn vasprintf
-first appeared in the
-.Tn GNU C
-library.
-These were implemented by
-.An Peter Wemm Aq peter@FreeBSD.org
-in
-.Fx 2.2 ,
-but were later replaced with a different implementation
-from
-.An Todd C. Miller Aq Todd.Miller@courtesan.com
-for
-.Ox 2.3 .
-.Sh BUGS
-The conversion formats
-.Cm \&%D , \&%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
-.Cm 0
-flag or by specifying a precision), and the benign effect (i.e., none)
-of the
-.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
-The
-.Nm
-family of functions do not correctly handle multibyte characters in the
-.Fa format
-argument.