summaryrefslogtreecommitdiffstats
path: root/lib/libc/stdio/printf.3
diff options
context:
space:
mode:
Diffstat (limited to 'lib/libc/stdio/printf.3')
-rw-r--r--lib/libc/stdio/printf.3100
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.
OpenPOWER on IntegriCloud