.\" SUCH DAMAGE.
.\"
.\" @(#)printf.3 8.1 (Berkeley) 6/4/93
-.\" $FreeBSD: src/lib/libc/stdio/printf.3,v 1.64 2009/12/02 07:51:25 brueffer Exp $
+.\" $FreeBSD$
.\"
.Dd December 2, 2009
.Dt PRINTF 3
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
-.Fd "#define _WITH_DPRINTF"
.In stdio.h
.Ft int
.Fn printf "const char * restrict format" ...
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
.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
.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
-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
A
.Cm +
overrides a space if both are used.
-.It Sq Cm '
+.It So "'" Sc (apostrophe)
Decimal conversions
.Cm ( d , u ,
or
.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
.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
.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
.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.
and
.Li 0xc.9p-2
are all equivalent.
-.Fx 8.0
-and later always prints finite non-zero numbers using
-.Ql 1
-as the digit before the hexadecimal point.
+The format chosen depends on the internal representation of the
+number, but the implementation guarantees that the length of the
+mantissa will be minimized.
Zeroes are always represented with a mantissa of 0 (preceded by a
.Ql -
if appropriate) and an exponent of
.Vt "int *"
(or variant) pointer argument.
No argument is converted.
+The
+.Fa format
+argument must be in write-protected memory if this specifier is used; see
+.Sx SECURITY CONSIDERATIONS
+below.
.It Cm %
A
.Ql %
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" ,
return (p);
}
.Ed
-.Sh SECURITY CONSIDERATIONS
-The
-.Fn sprintf
-and
-.Fn vsprintf
-functions are easily misused in a manner which enables malicious users
-to arbitrarily change a running program's functionality through
-a buffer overflow attack.
-Because
-.Fn sprintf
-and
-.Fn vsprintf
-assume an infinitely long string,
-callers must be careful not to overflow the actual space;
-this is often hard to assure.
-For safety, programmers should use the
-.Fn snprintf
-interface instead.
-For example:
-.Bd -literal
-void
-foo(const char *arbitrary_string, const char *and_another)
-{
- char onstack[8];
-
-#ifdef BAD
- /*
- * This first sprintf is bad behavior. Do not use sprintf!
- */
- sprintf(onstack, "%s, %s", arbitrary_string, and_another);
-#else
- /*
- * The following two lines demonstrate better use of
- * snprintf().
- */
- snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string,
- and_another);
-#endif
-}
-.Ed
-.Pp
-The
-.Fn printf
-and
-.Fn sprintf
-family of functions are also easily misused in a manner
-allowing malicious users to arbitrarily change a running program's
-functionality by either causing the program
-to print potentially sensitive data
-.Dq "left on the stack" ,
-or causing it to generate a memory fault or bus error
-by dereferencing an invalid pointer.
-.Pp
-.Cm %n
-can be used to write arbitrary data to potentially carefully-selected
-addresses.
-Programmers are therefore strongly advised to never pass untrusted strings
-as the
-.Fa format
-argument, as an attacker can put format specifiers in the string
-to mangle your stack,
-leading to a possible security hole.
-This holds true even if the string was built using a function like
-.Fn snprintf ,
-as the resulting string may still contain user-supplied conversion specifiers
-for later interpolation by
-.Fn printf .
-.Pp
-Always use the proper secure idiom:
-.Pp
-.Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"
.Sh COMPATIBILITY
-Many application writers used the name
-.Va dprintf
-before the
-.Fn dprintf
-function was introduced in
-.St -p1003.1 ,
-so a prototype is not provided by default in order to avoid
-compatibility problems.
-Applications that wish to use the
-.Fn dprintf
-function described herein should either request a strict
-.St -p1003.1-2008
-environment by defining the macro
-.Dv _POSIX_C_SOURCE
-to the value 200809 or greater, or by defining the macro
-.Dv _WITH_DPRINTF ,
-prior to the inclusion of
-.In stdio.h .
-For compatibility with GNU libc, defining either
-.Dv _BSD_SOURCE
-or
-.Dv _GNU_SOURCE
-prior to the inclusion of
-.In stdio.h
-will also make
-.Fn dprintf
-available.
-.Pp
The conversion formats
.Cm \&%D , \&%O ,
and
-.Cm %U
+.Cm \&%U
are not standard and
are provided only for backward compatibility.
The effect of padding the
.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
.Tn GNU C
library.
These were implemented by
-.An Peter Wemm Aq peter@FreeBSD.org
+.An Peter Wemm Aq Mt 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 .
+.Ox 2.3
+by
+.An Todd C. Miller Aq Mt Todd.Miller@courtesan.com .
The
.Fn dprintf
and
family of functions do not correctly handle multibyte characters in the
.Fa format
argument.
+.Sh SECURITY CONSIDERATIONS
+The
+.Fn sprintf
+and
+.Fn vsprintf
+functions are easily misused in a manner which enables malicious users
+to arbitrarily change a running program's functionality through
+a buffer overflow attack.
+Because
+.Fn sprintf
+and
+.Fn vsprintf
+assume an infinitely long string,
+callers must be careful not to overflow the actual space;
+this is often hard to assure.
+For safety, programmers should use the
+.Fn snprintf
+interface instead.
+For example:
+.Bd -literal
+void
+foo(const char *arbitrary_string, const char *and_another)
+{
+ char onstack[8];
+
+#ifdef BAD
+ /*
+ * This first sprintf is bad behavior. Do not use sprintf!
+ */
+ sprintf(onstack, "%s, %s", arbitrary_string, and_another);
+#else
+ /*
+ * The following two lines demonstrate better use of
+ * snprintf().
+ */
+ snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string,
+ and_another);
+#endif
+}
+.Ed
+.Pp
+The
+.Fn printf
+and
+.Fn sprintf
+family of functions are also easily misused in a manner
+allowing malicious users to arbitrarily change a running program's
+functionality by either causing the program
+to print potentially sensitive data
+.Dq "left on the stack" ,
+or causing it to generate a memory fault or bus error
+by dereferencing an invalid pointer.
+.Pp
+.Cm %n
+can be used to write arbitrary data to potentially carefully-selected
+addresses.
+Programmers are therefore strongly advised to never pass untrusted strings
+as the
+.Fa format
+argument, as an attacker can put format specifiers in the string
+to mangle your stack,
+leading to a possible security hole.
+This holds true even if the string was built using a function like
+.Fn snprintf ,
+as the resulting string may still contain user-supplied conversion specifiers
+for later interpolation by
+.Fn printf .
+For this reason, a
+.Fa format
+argument containing
+.Cm %n
+is assumed to be untrustworthy if located in writable memory (i.e. memory with
+protection PROT_WRITE; see
+.Xr mprotect 2 )
+and any attempt to use such an argument is fatal.
+Practically, this means that
+.Cm %n
+is permitted in literal
+.Fa format
+strings but disallowed in
+.Fa format
+strings located in normal stack- or heap-allocated memory.
+.Pp
+Always use the proper secure idiom:
+.Pp
+.Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"
projects / apple / libc.git / blobdiff