Print this page
12953 convert printf(3c) and vprintf(3c) to mdoc
Change-Id: Iffbfe29bbd443e1a7ad0fc33fd7a7851428a3dc8
@@ -42,162 +42,220 @@
.\"
.\" 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>
+.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>
-
-\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, \&.\|.\|.);
+ * error(function_name, format, arg1, ...);
*/
-void error(char *function_name, char *format, \&.\|.\|.)
+void
+error(char *function_name, char *format, ...)
{
va_list ap;
+
va_start(ap, format);
- /* print out name of function causing error */
+
+ /* Print out name of function causing error */
(void) fprintf(stderr, "ERR in %s: ", function_name);
- /* print out remainder of message */
+
+ /* 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
+.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 \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.
+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.