Print this page
12953 convert printf(3c) and vprintf(3c) to mdoc
Change-Id: Iffbfe29bbd443e1a7ad0fc33fd7a7851428a3dc8
*** 1,134 ****
VPRINTF(3C) Standard C Library Functions VPRINTF(3C)
-
-
NAME
vprintf, 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 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(), 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).
-
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(5) 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(5) 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), attributes(5), stdarg(3EXT), attributes(5), standards(5)
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.
!
!
! January 7, 2009 VPRINTF(3C)
--- 1,115 ----
VPRINTF(3C) Standard C Library Functions VPRINTF(3C)
NAME
vprintf, vfprintf, vsprintf, vsnprintf, vasprintf - print formatted
output of a variable argument list
+ LIBRARY
+ Standard C Library (libc, -lc)
+
SYNOPSIS
#include <stdarg.h>
+ #include <stdio.h>
! int
! vprintf(const char *format, va_list);
+ 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(), 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).
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).
EXAMPLES
Example 1 Using vprintf() to write an error routine.
+ The following demonstrates how vfprintf() could be used to write an error
+ routine:
#include <stdarg.h>
! #include <stdio.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();
}
+ ERRORS
+ The vfprintf() function 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.
+ INTERFACE STABILITY
+ Committed
+ MT-LEVEL
+ 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 ALSO
! printf(3C), stdarg(3EXT), attributes(5), standards(5)
+ STANDARDS
+ See standards(5) 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.
+
NOTES
! The vsnprintf() return value when n is 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 is 0 returns an unspecified value less than 1.
! illumos July 10, 2020 illumos