Print this page
12953 convert printf(3c) and vprintf(3c) to mdoc
Change-Id: Iffbfe29bbd443e1a7ad0fc33fd7a7851428a3dc8
*** 42,203 ****
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
.\"
! .TH VPRINTF 3C "Jan 7, 2009"
! .SH NAME
! vprintf, vfprintf, vsprintf, vsnprintf, vasprintf \- print formatted output of
! a variable argument list
! .SH SYNOPSIS
! .LP
! .nf
! #include <stdio.h>
#include <stdarg.h>
-
- \fBint\fR \fBvprintf\fR(\fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIap\fR);
- .fi
-
- .LP
- .nf
- \fBint\fR \fBvfprintf\fR(\fBFILE *\fR\fIstream\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIap\fR);
- .fi
-
- .LP
- .nf
- \fBint\fR \fBvsprintf\fR(\fBchar *\fR\fIs\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIap\fR);
- .fi
-
- .LP
- .nf
- \fBint\fR \fBvsnprintf\fR(\fBchar *\fR\fIs\fR, \fBsize_t\fR \fIn\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIap\fR);
- .fi
-
- .LP
- .nf
- \fBint\fR \fBvasprintf\fR(\fBchar **\fR\fIret\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIap\fR);
- .fi
-
- .SH DESCRIPTION
- .sp
- .LP
- The \fBvprintf()\fR, \fBvfprintf()\fR, \fBvsprintf()\fR, \fBvsnprintf()\fR, and
- \fBvasprintf()\fR functions are the same as \fBprintf()\fR, \fBfprintf()\fR,
- \fBsprintf()\fR, \fBsnprintf()\fR, and \fBasprintf()\fR, respectively, except
- that instead of being called with a variable number of arguments, they are
- called with an argument list as defined in the \fB<stdarg.h>\fR header. See
- \fBprintf\fR(3C).
- .sp
- .LP
- The \fB<stdarg.h>\fR header defines the type \fBva_list\fR and a set of macros
- for advancing through a list of arguments whose number and types may vary. The
- argument \fIap\fR to the \fBvprint\fR family of functions is of type
- \fBva_list\fR. This argument is used with the <\fBstdarg.h\fR> header file
- macros \fBva_start()\fR, \fBva_arg()\fR, and \fBva_end()\fR (see
- \fBstdarg\fR(3EXT)). The \fBEXAMPLES\fR section below demonstrates the use of
- \fBva_start()\fR and \fBva_end()\fR with \fBvprintf()\fR.
- .sp
- .LP
- The macro \fBva_alist()\fR is used as the parameter list in a function
- definition, as in the function called \fBerror()\fR in the example below. The
- macro \fBva_start(\fR\fIap, name\fR\fB),\fR where \fIap\fR is of type
- \fBva_list\fR and \fIname\fR is the rightmost parameter (just before
- \|.\|.\|.), must be called before any attempt to traverse and access unnamed
- arguments is made. The \fBva_end(\fR\fIap\fR\fB)\fR macro must be invoked when
- all desired arguments have been accessed. The argument list in \fIap\fR can be
- traversed again if \fBva_start()\fR is called again after \fBva_end()\fR. In
- the example below, the \fBerror()\fR arguments (\fIarg1\fR, \fIarg2\fR,
- \&.\|.\|.) are passed to \fBvfprintf()\fR in the argument \fIap\fR.
- .SH RETURN VALUES
- .sp
- .LP
- Refer to \fBprintf\fR(3C).
- .SH ERRORS
- .sp
- .LP
- The \fBvprintf()\fR and \fBvfprintf()\fR functions will fail if either the
- \fIstream\fR is unbuffered or the \fIstream\fR's buffer needed to be flushed
- and:
- .sp
- .ne 2
- .na
- \fB\fBEFBIG\fR\fR
- .ad
- .RS 9n
- The file is a regular file and an attempt was made to write at or beyond the
- offset maximum.
- .RE
-
- .SH EXAMPLES
- .LP
- \fBExample 1 \fRUsing \fBvprintf()\fR to write an error routine.
- .sp
- .LP
- The following demonstrates how \fBvfprintf()\fR could be used to write an error
- routine:
-
- .sp
- .in +2
- .nf
#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();
}
! .fi
! .in -2
!
! .SH ATTRIBUTES
! .sp
! .LP
! See \fBattributes\fR(5) for descriptions of the following attributes:
! .sp
!
! .sp
! .TS
! box;
! c | c
! l | l .
! ATTRIBUTE TYPE ATTRIBUTE VALUE
! _
! Interface Stability Committed
! _
! MT-Level See below.
! _
! Standard See below.
! .TE
!
! .sp
! .LP
All of these functions can be used safely in multithreaded applications, as
! long as \fBsetlocale\fR(3C) is not being called to change the locale.
! .sp
! .LP
! See \fBstandards\fR(5) for the standards conformance of \fBvprintf()\fR,
! \fBvfprintf()\fR, \fBvsprintf()\fR, and \fBvsnprintf()\fR. The
! \fBvasprintf()\fR function is modeled on the one that appears in the FreeBSD,
! NetBSD, and GNU C libraries.
! .SH SEE ALSO
! .sp
! .LP
! \fBprintf\fR(3C), \fBattributes\fR(5), \fBstdarg\fR(3EXT), \fBattributes\fR(5),
! \fBstandards\fR(5)
! .SH NOTES
! .sp
! .LP
! The \fBvsnprintf()\fR return value when \fIn\fR = 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 \fBvsnprintf()\fR
! when \fIn\fR = 0 returns an unspecified value less than 1.
--- 42,261 ----
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
.\"
! .Dd July 10, 2020
! .Dt VPRINTF 3C
! .Os
! .Sh NAME
! .Nm vprintf ,
! .Nm vfprintf ,
! .Nm vsprintf ,
! .Nm vsnprintf ,
! .Nm vasprintf
! .Nd print formatted output of a variable argument list
! .Sh LIBRARY
! .Lb libc
! .Sh SYNOPSIS
! .In stdarg.h
! .In stdio.h
! .Ft int
! .Fo vprintf
! .Fa "const char *format"
! .Fa va_list
! .Fc
! .Ft int
! .Fo vfprintf
! .Fa "FILE *stream"
! .Fa "const char *format"
! .Fa "va_list ap"
! .Fc
! .Ft int
! .Fo vsprintf
! .Fa "char *s"
! .Fa "const char *format"
! .Fa "va_list ap"
! .Fc
! .Ft int
! .Fo vsnprintf
! .Fa "char *s"
! .Fa "size_t n"
! .Fa "const char *format"
! .Fa "va_list ap"
! .Fc
! .Ft int
! .Fo vasprintf
! .Fa "char **ret"
! .Fa "const char *format"
! .Fa "va_list ap"
! .Fc
! .Sh DESCRIPTION
! The
! .Fn vprintf ,
! .Fn vfprintf ,
! .Fn vsprintf ,
! .Fn vsnprintf ,
! and
! .Fn vasprintf
! functions are the same as
! .Fn printf ,
! .Fn fprintf ,
! .Fn sprintf ,
! .Fn snprintf ,
! and
! .Fn 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
! .In stdarg.h
! header.
! See
! .Xr printf 3C .
! .Pp
! The
! .In stdarg.h
! header defines the type
! .Vt va_list
! and a set of macros for advancing through a list of arguments whose number and
! types may vary.
! The argument
! .Fa ap
! to the vprint family of functions is of type
! .Vt va_list .
! This argument is used with the
! .In stdarg.h
! header file macros
! .Fn va_start ,
! .Fn va_arg ,
! and
! .Fn va_end
! .Pq see Xr stdarg 3EXT .
! The
! .Sx EXAMPLES
! section below demonstrates the use of
! .Fn va_start
! and
! .Fn va_end
! with
! .Fn vprintf .
! .Pp
! The macro
! .Fn va_alist
! is used as the parameter list in a function definition, as in the function
! called
! .Fn error
! in the example below.
! The macro
! .Ql va_start(ap, name) ,
! where
! .Va ap
! is of type
! .Vt va_list
! and
! .Va name
! is the rightmost parameter (just before ...), must be called before any attempt
! to traverse and access unnamed arguments is made.
! The
! .Ql va_end(ap)
! macro must be invoked when all desired arguments have been accessed.
! The argument list in
! .Va ap
! can be traversed again if
! .Fn va_start
! is called again after
! .Fn va_end .
! In the example below, the
! .Fn error
! arguments (arg1, arg2, ...) are passed to
! .Fn vfprintf
! in the argument
! .Va ap .
! .Sh RETURN VALUES
! Refer to
! .Xr printf 3C .
! .Sh EXAMPLES
! .Sy Example 1
! Using
! .Fn vprintf
! to write an error routine.
! .Pp
! The following demonstrates how
! .Fn vfprintf
! could be used to write an error routine:
! .Bd -literal
#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();
}
! .Ed
! .Sh ERRORS
! The
! .Fn vfprintf
! function will fail if either the
! .Fa stream
! is unbuffered or the
! .Fa stream Ns 's
! buffer needed to be flushed and:
! .Bl -tag -width Er
! .It Er EFBIG
! The file is a regular file and an attempt was made to write at or beyond the
! offset maximum.
! .El
! .Sh INTERFACE STABILITY
! .Sy Committed
! .Sh MT-LEVEL
All of these functions can be used safely in multithreaded applications, as
! long as
! .Xr setlocale 3C
! is not being called to change the locale.
! .Sh SEE ALSO
! .Xr printf 3C ,
! .Xr stdarg 3EXT ,
! .Xr attributes 5 ,
! .Xr standards 5
! .Sh STANDARDS
! See
! .Xr standards 5
! for the standards conformance of
! .Fn vprintf ,
! .Fn vfprintf ,
! .Fn vsprintf ,
! and
! .Fn vsnprintf .
! The
! .Fn vasprintf
! function is modeled on the one that appears in the
! .Fx ,
! .Nx ,
! and GNU C libraries.
! .Sh NOTES
! The
! .Fn vsnprintf
! return value when
! .Fa 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
! .Fn vsnprintf
! when
! .Fa n
! is 0 returns an unspecified value less than 1.