X-Git-Url: https://git.saurik.com/apple/libc.git/blobdiff_plain/1f2f436a38f7ae2d39a943ad2898d8fed4ed2e58..HEAD:/stdio/FreeBSD/printf.3 diff --git a/stdio/FreeBSD/printf.3 b/stdio/FreeBSD/printf.3 index cbafaf9..380ffeb 100644 --- a/stdio/FreeBSD/printf.3 +++ b/stdio/FreeBSD/printf.3 @@ -30,7 +30,7 @@ .\" 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 @@ -42,7 +42,6 @@ .Sh LIBRARY .Lb libc .Sh SYNOPSIS -.Fd "#define _WITH_DPRINTF" .In stdio.h .Ft int .Fn printf "const char * restrict format" ... @@ -106,6 +105,12 @@ and 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 @@ -113,20 +118,6 @@ 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 @@ -164,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. -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 @@ -277,7 +276,7 @@ number produced by a signed conversion. A .Cm + overrides a space if both are used. -.It Sq Cm ' +.It So "'" Sc (apostrophe) Decimal conversions .Cm ( d , u , or @@ -291,6 +290,20 @@ the non-monetary separator returned by .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 @@ -383,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 +.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 @@ -449,7 +490,7 @@ The .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 @@ -525,7 +566,7 @@ The .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. @@ -561,10 +602,9 @@ For example, 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 @@ -652,6 +692,11 @@ integer indicated by the .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 % @@ -670,6 +715,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. +.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" , @@ -709,110 +769,11 @@ char *newfmt(const char *fmt, ...) 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 @@ -845,9 +806,11 @@ 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 @@ -886,14 +849,14 @@ first appeared 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 @@ -906,3 +869,89 @@ The 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);"