I am sponsoring this automatic case for myself.
1. Introduction
This case adds two new functions to the C library, asprintf()
and vasprintf() as follows:
int asprintf(char **ret, const char *format, ...);
int vasprintf(char **ret, const char *format, va_list ap);
The committment level of these interfaces is Committed.
The release binding is "patch"
(so it can be back-ported to Solaris 10 if required).
2. Discussion
Linux and the various BSD operating systems provide the *asprintf()
family of functions. These behave as sprintf(), except that they
allocate a string large enough to hold the result, and return a
pointer to that string. The caller is later expected to free()
this buffer.
Both functions return the same values as the corresponding sprintf()
variant with one addition:
The asprintf() and vasprintf() functions may fail if:
ENOMEM Insufficient storage space is available.
The contents of 'ret' on failure varies between current
implementations. This case proposes to set 'ret' to NULL on failure
(as the BSD implementation does, unlike the Linux implementation
which leaves it as undefined).
Note that there is some extant usage of asnprintf() and vasnprintf()
functions, mostly via a library called gnulib, which is typically
used to provide missing functionality in cross-platform software.
As no OS actually implements these variants, and they have a
somewhat strange interface, this case does not propose an
implementation of them for Solaris.
3. Interface table
Both functions are Committed.
Both are derived from OpenBSD source.
4. References
4508459 Solaris should have asprintf() and vasprintf() functions
5. Manual page differences
(See the materials directory for the full old and new man pages.)
--- printf.3c.old Wed Dec 17 12:02:14 2008
+++ printf.3c Wed Dec 17 12:46:03 2008
@@ -6,7 +6,7 @@
NAME
- printf, fprintf, sprintf, snprintf - print formatted output
+ printf, fprintf, sprintf, snprintf, asprintf - print formatted output
SYNOPSIS
#include <stdio.h>
@@ -27,6 +27,10 @@
const char *restrict format, /* args*/ ...);
+ int asprintf(char **ret, const char *restrict format,
+ /* args*/ ...);
+
+
DESCRIPTION
The printf() function places output on the standard output
stream stdout.
@@ -51,6 +55,15 @@
written into the array.
+ The asprintf() function is the same as the sprintf() function
+ except that it returns, in the ret argument, a pointer to a
+ buffer sufficiently large to hold the output string. This
+ pointer should be passed to free(3C) to release the allocated
+ storage when it is no longer needed. If sufficient space
+ cannot be allocated, the asprintf() function returns -1 and
+ sets ret to be a NULL pointer.
+
+
Each of these functions converts, formats, and prints its
arguments under control of the format. The format is a char-
acter string, beginning and ending in its initial shift
@@ -611,9 +624,10 @@
call to exit(3C) or abort(3C).
RETURN VALUES
- The printf(), fprintf(), and sprintf() functions return the
+ The printf(), fprintf(), sprintf(), and asprintf() functions
+ return the
number of bytes transmitted (excluding the terminating null
- byte in the case of sprintf()).
+ byte in the case of sprintf() and asprintf()).
The snprintf() function returns the number of bytes that
@@ -622,7 +636,7 @@
n is 0 on a call to snprintf(), s can be a null pointer and
the number of bytes that would have been written if n had
been sufficiently large (excluding the terminating null
- byte) are returned.
+ byte) is returned.
Each function returns a negative value if an output error
@@ -653,7 +667,7 @@
- The printf() and fprintf() functions may fail if:
+ The printf(), fprintf(), and asprintf() functions may fail if:
ENOMEM Insufficient storage space is available.
@@ -798,14 +812,19 @@
- The sprintf() and snprintf() functions are Async-Signal-
- Safe. The printf() and fprintf() functions can be used
- safely in multithreaded applications, as long as
- setlocale(3C) is not being called to change the locale.
+ The printf(), fprintf(), sprintf(), and snprintf() functions
+ are Standard. The asprintf() function is modeled on the one
+ that appears in the FreeBSD, NetBSD, and GNU C libraries.
+ All of these functions can be used safely in multithreaded
+ applications, as long as setlocale(3C) is not being called
+ to change the locale.
+
+ The sprintf() and snprintf() functions are Async-Signal-Safe.
+
SEE ALSO
exit(2), lseek(2), write(2), abort(3C), ecvt(3C), exit(3C),
- fclose(3C), fflush(3C), fputwc(3C), putc(3C), scanf(3C),
+ fclose(3C), fflush(3C), fputwc(3C), free(3C), putc(3C), scanf(3C),
setlocale(3C), stdio(3C), vprintf(3C), wcstombs(3C),
wctomb(3C), attributes(5), environ(5), standards(5)
--- vprintf.3c.old Wed Dec 17 12:02:25 2008
+++ vprintf.3c Wed Dec 17 20:04:02 2008
@@ -6,8 +6,8 @@
NAME
- vprintf, vfprintf, vsprintf, vsnprintf - print formatted
- output of a variable argument list
+ vprintf, vfprintf, vsprintf, vsnprintf, vasprintf - print
+ formatted output of a variable argument list
SYNOPSIS
#include <stdio.h>
@@ -25,10 +25,14 @@
int vsnprintf(char *s, size_t n, const char *format, va_list ap);
+ int vasprintf(char **ret, const char *format, va_list ap);
+
+
DESCRIPTION
- The vprintf(), vfprintf(), vsprintf() and vsnprintf() func-
- tions are the same as printf(), fprintf(), sprintf(), and
- snprintf(), respectively, except that instead of being
+ The vprintf(), vfprintf(), vsprintf(), vsnprintf(), and
+ vasprintf() functions are the same as printf(), fprintf(),
+ sprintf(), snprintf(), and asprintf(), respectively, except
+ that instead of being
called with a variable number of arguments, they are called
with an argument list as defined in the <stdarg.h> header.
See printf(3C).
@@ -104,7 +108,7 @@
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
- | Interface Stability | Standard |
+ | Interface Stability | Committed |
|_____________________________|_____________________________|
| MT-Level | See below. |
|_____________________________|_____________________________|
@@ -111,9 +115,16 @@
- The vprintf() and vfprintf() functions are MT-Safe. The
- vsprintf() and vsnprintf() functions are Async-Signal-Safe.
+ The vprintf(), vfprintf(), vsprintf(), and vsnprintf() functions
+ are Standard. The vasprintf() function is modeled on the one
+ that appears in the FreeBSD, NetBSD, and GNU C libraries.
+ All of these functions can be used safely in multithreaded
+ applications, as long as setlocale(3C) is not being called
+ to change the locale.
+
+ The vsprintf() and vsnprintf() functions are Async-Signal-Safe.
+
SEE ALSO
printf(3C), attributes(5), stdarg(3EXT), attributes(5),
standards(5)
