VPRINTF(3C) Standard C Library Functions VPRINTF(3C)
NAME
vprintf, vdprintf, vfprintf, vsprintf, vsnprintf, vasprintf - print
formatted output of a variable argument list
SYNOPSIS
#include <stdio.h>
#include <stdarg.h>
int vprintf(
const char *format,
va_list ap);
int vdprintf(
int fildes,
const char *format,
va_list ap);
int vfprintf(
FILE *stream,
const char *format,
va_list ap);
int vsprintf(
char *s,
const char *format,
va_list ap);
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(),
vdprintf(),
vfprintf(),
vsprintf(),
vsnprintf(), and
vasprintf() functions are the same as
printf(),
dprintf(),
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).
The
<stdarg.h> header defines the type
va_list and a set of macros
for advancing through a list of arguments whose number and types may
vary. The argument
ap to the
vprint family of functions is of type
va_list. This argument is used with the <
stdarg.h> header file macros
va_start(),
va_arg(), and
va_end() (see
stdarg(3EXT)). The
EXAMPLES section below demonstrates the use of
va_start() and
va_end() with
vprintf().
The macro
va_alist() is used as the parameter list in a function
definition, as in the function called
error() in the example below.
The macro
va_start(ap, name), where
ap is of type
va_list and
name is
the rightmost parameter (just before ...), must be called before any
attempt to traverse and access unnamed arguments is made. The
va_end(ap) macro must be invoked when all desired arguments have been
accessed. The argument list in
ap can be traversed again if
va_start() is called again after
va_end(). In the example below, the
error() arguments (
arg1,
arg2, ...) are passed to
vfprintf() in the
argument
ap.
RETURN VALUES
Refer to
printf(3C).
ERRORS
The
vprintf() and
vfprintf() functions will fail if either the
stream is unbuffered or the
stream's buffer needed to be flushed and:
EFBIG The file is a regular file and an attempt was made to write
at or beyond the offset maximum.
EXAMPLES
Example 1: Using vprintf() to write an error routine.
The following demonstrates how
vfprintf() could be used to write an
error routine:
#include <stdio.h>
#include <stdarg.h>
...
/*
* error should be called like
* error(function_name, format, arg1, ...);
*/
void error(char *function_name, char *format, ...)
{
va_list ap;
va_start(ap, format);
/* print out name of function causing error */
(void) fprintf(stderr, "ERR in %s: ", function_name);
/* print out remainder of message */
(void) vfprintf(stderr, format, ap);
va_end(ap);
(void) abort();
}
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | See below. |
+--------------------+-----------------+
|Standard | See below. |
+--------------------+-----------------+
All of these functions can be used safely in multithreaded
applications, as long as
setlocale(3C) is not being called to change
the locale.
See
standards(7) for the standards conformance of
vprintf(),
vfprintf(),
vsprintf(), and
vsnprintf(). The
vasprintf() function is
modeled on the one that appears in the FreeBSD, NetBSD, and GNU C
libraries.
SEE ALSO
printf(3C),
stdarg(3EXT),
attributes(7),
standards(7)NOTES
The
vsnprintf() return value when
n = 0 was changed in the Solaris 10
release. The change was based on the SUSv3 specification. The
previous behavior was based on the initial SUSv2 specification, where
vsnprintf() when
n = 0 returns an unspecified value less than 1.
April 25, 2024 VPRINTF(3C)
