summaryrefslogtreecommitdiffstats
path: root/lib/libc/stdio/printf.3
diff options
context:
space:
mode:
authorpeter <peter@FreeBSD.org>1996-05-27 10:49:43 +0000
committerpeter <peter@FreeBSD.org>1996-05-27 10:49:43 +0000
commitfbe63391875b9762cc438066b5f20fce1ab43a26 (patch)
tree46b469e307f5817e3d72000c1cb25e1b95261d2d /lib/libc/stdio/printf.3
parent83ae023014d7ed4c9a0e539a355ced30d9fb758b (diff)
downloadFreeBSD-src-fbe63391875b9762cc438066b5f20fce1ab43a26.zip
FreeBSD-src-fbe63391875b9762cc438066b5f20fce1ab43a26.tar.gz
Add an implementation of the gnu-ish asprintf() and vasprintf(). They are
not based on gpl'ed code, just prototype and usage. I'm not 100% certain they behave the same while the system is in trouble (eg: malloc() failing) but in those circumstances all bets would be off anyway. These routines work like sprintf() and vsprintf(), except that instead of using a fixed buffer, they allocate memory and return it to the user and it's the user's responsibility to free() it. They have allocate as much memory as they need (and can get), so the size of strings it can deal with is limited only by the amount of memory it can malloc() on your behalf. There are a few gpl'ed programs starting to use this interface, and it's becoming more common with the scares about security risks with sprintf(). I dont like the look of the code that the various programs (including cvs, gdb, libg++, etc) provide if configure can't find it on the system. It should be possible to modify the stdio core code to provide this interface more efficiently, I was more worried about having something that worked and was secure. :-) (I noticed that there was once intended to be a smprintf() routine when our stdio was written for 4.4BSD, but it looks pretty stillborn, and it's intended interface is not clear). Since Linux and gnu libc have this interface, it seemed silly to bring yet another one onto the scene.
Diffstat (limited to 'lib/libc/stdio/printf.3')
-rw-r--r--lib/libc/stdio/printf.380
1 files changed, 47 insertions, 33 deletions
diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3
index 4238a90..e675b3e 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
@@ -600,6 +605,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
+FreeBSD-2.2.
.Sh BUGS
The conversion formats
.Cm \&%D ,
OpenPOWER on IntegriCloud