diff options
Diffstat (limited to 'lib/libc/stdio/printf.3')
-rw-r--r-- | lib/libc/stdio/printf.3 | 100 |
1 files changed, 64 insertions, 36 deletions
diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3 index 70f8b99..2ff5238 100644 --- a/lib/libc/stdio/printf.3 +++ b/lib/libc/stdio/printf.3 @@ -43,10 +43,12 @@ .Nm fprintf , .Nm sprintf , .Nm snprintf , +.Nm asprintf , .Nm vprintf , .Nm vfprintf, .Nm vsprintf , -.Nm vsnprintf +.Nm vsnprintf , +.Nm vasprintf .Nd formatted output conversion .Sh SYNOPSIS .Fd #include <stdio.h> @@ -58,8 +60,8 @@ .Fn sprintf "char *str" "const char *format" ... .Ft int .Fn snprintf "char *str" "size_t size" "const char *format" ... -.\" .Ft int -.\" .Fn smprintf "const char *format" ... +.Ft int +.Fn asprintf "char **ret" "const char *format" ... .Fd #include <stdarg.h> .Ft int .Fn vprintf "const char *format" "va_list ap" @@ -69,8 +71,8 @@ .Fn vsprintf "char *str" "char *format" "va_list ap" .Ft int .Fn vsnprintf "char *str" "size_t size" "const char *format" "va_list ap" -.\" .Ft int -.\" .Fn vsmprintf "const char *format" "va_list ap" +.Ft int +.Fn vasprintf "char **ret" "const char *format" "va_list ap" .Sh DESCRIPTION The .Fn printf @@ -94,45 +96,47 @@ write output to the given output and .Fn vsnprintf write to the character string -.Fa str . -.\" .IR str ; -.\" and -.\" .I smprintf -.\" and -.\" .I vsmprintf -.\" dynamically allocate a new string with -.\" .IR malloc . +.Fa str ; +and +.Fn asprintf +and +.Fn vasprintf +dynamically allocate a new string with +.Xr malloc 3 +/ +.Xr realloc 3 . +.Pp These functions write the output under the control of a .Fa format string that specifies how subsequent arguments (or arguments accessed via the variable-length argument facilities of .Xr stdarg 3 ) are converted for output. -.\" Except for -.\" .I smprintf -.\" and -.\" .IR vsmprintf , -.\" all of these functions return +.Pp These functions return the number of characters printed (not including the trailing .Ql \e0 used to end output to strings). -.\" .I Smprintf -.\" and -.\" .I vsmprintf -.\" return a pointer to a string of an appropriate length; -.\" this pointer should be passed to -.\" .I free -.\" to release the associated storage -.\" when it is no longer needed. -.\" If sufficient space is not avaliable, -.\" .I smprintf -.\" and -.\" .I vsmprintf -.\" will return -.\" .SM -.\" .BR +.Pp +.Fn Asprintf +and +.Fn vasprintf +return a pointer to a buffer sufficiently large to hold the +string in the +.Fa ret +argument; +This pointer should be passed to +.Xr free 3 +to release the allocated storage when it is no longer needed. +If sufficient space cannot be allocated, +.Fn asprintf +and +.Fn vasprintf +will return -1 and set +.Fa ret +to be a NULL pointer. +.Pp .Fn Snprintf and .Fn vsnprintf @@ -147,6 +151,7 @@ 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. +.Pp .Fn Sprintf and .Fn vsprintf @@ -171,6 +176,16 @@ After the the following appear in sequence: .Bl -bullet .It +An optional field, consisting of a decimal digit string followed by a +.Cm $ , +specifying the next argument to access . +If this field is not provided, the argument following the last +argument accessed will be used. +Arguments are numbered starting at +.Cm 1 . +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 @@ -228,7 +243,7 @@ For all conversions except .Cm n , the converted value is padded on the left with zeros rather than blanks. If a precision is given with a numeric conversion -.Pf ( Mc d , +.Pf ( Cm d , .Cm i , .Cm o , .Cm u , @@ -389,6 +404,8 @@ A character that specifies the type of conversion to be applied. A field width or precision, or both, may be indicated by an asterisk .Ql * +or an asterisk followed by one or more decimal digits and a +.Ql $ instead of a digit string. In this case, an @@ -397,6 +414,8 @@ argument supplies the field width or precision. A negative field width is treated as a left adjustment flag followed by a positive field width; a negative precision is treated as though it were missing. +If a single format directive mixes positional (nn$) +and non-positional arguments, the results are undefined. .Pp The conversion specifiers and their meanings are: .Bl -tag -width "diouxX" @@ -422,7 +441,7 @@ are used for conversions; the letters .Cm ABCDEF are used for -.m X +.Cm X conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on @@ -600,6 +619,15 @@ The functions and .Fn vsnprintf are new to this release. +.Pp +The functions +.Fn asprintf +and +.Fn vasprintf +first appeared in the GNU C library. This implementation is thought +to be compatable but is not derived from the GNU code. This implementation +was written by Peter Wemm <peter@FreeBSD.org> and first appeared in +.Fx 2.2 . .Sh BUGS The conversion formats .Cm \&%D , @@ -631,7 +659,7 @@ and .Fn vsprintf assume an infinitely long string, callers must be careful not to overflow the actual space; -this is often impossible to assure. +this is often hard to assure. For safety, programmers should use the .Fn snprintf interface instead. |