Print this page
12953 convert printf(3c) and vprintf(3c) to mdoc
Change-Id: Iffbfe29bbd443e1a7ad0fc33fd7a7851428a3dc8
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/vprintf.3c.man.txt
+++ new/usr/src/man/man3c/vprintf.3c.man.txt
1 1 VPRINTF(3C) Standard C Library Functions VPRINTF(3C)
2 2
3 -
4 -
5 3 NAME
6 - vprintf, vfprintf, vsprintf, vsnprintf, vasprintf - print formatted
7 - output of a variable argument list
4 + vprintf, vfprintf, vsprintf, vsnprintf, vasprintf - print formatted
5 + output of a variable argument list
8 6
7 +LIBRARY
8 + Standard C Library (libc, -lc)
9 +
9 10 SYNOPSIS
10 - #include <stdio.h>
11 - #include <stdarg.h>
11 + #include <stdarg.h>
12 + #include <stdio.h>
12 13
13 - int vprintf(const char *format, va_list ap);
14 + int
15 + vprintf(const char *format, va_list);
14 16
17 + int
18 + vfprintf(FILE *stream, const char *format, va_list ap);
15 19
16 - int vfprintf(FILE *stream, const char *format, va_list ap);
20 + int
21 + vsprintf(char *s, const char *format, va_list ap);
17 22
23 + int
24 + vsnprintf(char *s, size_t n, const char *format, va_list ap);
18 25
19 - int vsprintf(char *s, const char *format, va_list ap);
26 + int
27 + vasprintf(char **ret, const char *format, va_list ap);
20 28
21 -
22 - int vsnprintf(char *s, size_t n, const char *format, va_list ap);
23 -
24 -
25 - int vasprintf(char **ret, const char *format, va_list ap);
26 -
27 -
28 29 DESCRIPTION
29 - The vprintf(), vfprintf(), vsprintf(), vsnprintf(), and vasprintf()
30 - functions are the same as printf(), fprintf(), sprintf(), snprintf(),
31 - and asprintf(), respectively, except that instead of being called with
32 - a variable number of arguments, they are called with an argument list
33 - as defined in the <stdarg.h> header. See printf(3C).
30 + The vprintf(), vfprintf(), vsprintf(), vsnprintf(), and vasprintf()
31 + functions are the same as printf(), fprintf(), sprintf(), snprintf(), and
32 + asprintf(), respectively, except that instead of being called with a
33 + variable number of arguments, they are called with an argument list as
34 + defined in the <stdarg.h> header. See printf(3C).
34 35
36 + The <stdarg.h> header defines the type va_list and a set of macros for
37 + advancing through a list of arguments whose number and types may vary.
38 + The argument ap to the vprint family of functions is of type va_list.
39 + This argument is used with the <stdarg.h> header file macros va_start(),
40 + va_arg(), and va_end() (see stdarg(3EXT)). The EXAMPLES section below
41 + demonstrates the use of va_start() and va_end() with vprintf().
35 42
36 - The <stdarg.h> header defines the type va_list and a set of macros for
37 - advancing through a list of arguments whose number and types may vary.
38 - The argument ap to the vprint family of functions is of type va_list.
39 - This argument is used with the <stdarg.h> header file macros
40 - va_start(), va_arg(), and va_end() (see stdarg(3EXT)). The EXAMPLES
41 - section below demonstrates the use of va_start() and va_end() with
42 - vprintf().
43 + The macro va_alist() is used as the parameter list in a function
44 + definition, as in the function called error() in the example below. The
45 + macro `va_start(ap, name)', where ap is of type va_list and name is the
46 + rightmost parameter (just before ...), must be called before any attempt
47 + to traverse and access unnamed arguments is made. The `va_end(ap)' macro
48 + must be invoked when all desired arguments have been accessed. The
49 + argument list in ap can be traversed again if va_start() is called again
50 + after va_end(). In the example below, the error() arguments (arg1, arg2,
51 + ...) are passed to vfprintf() in the argument ap.
43 52
44 -
45 - The macro va_alist() is used as the parameter list in a function
46 - definition, as in the function called error() in the example below. The
47 - macro va_start(ap, name), where ap is of type va_list and name is the
48 - rightmost parameter (just before ...), must be called before any
49 - attempt to traverse and access unnamed arguments is made. The
50 - va_end(ap) macro must be invoked when all desired arguments have been
51 - accessed. The argument list in ap can be traversed again if va_start()
52 - is called again after va_end(). In the example below, the error()
53 - arguments (arg1, arg2, ...) are passed to vfprintf() in the argument
54 - ap.
55 -
56 53 RETURN VALUES
57 - Refer to printf(3C).
54 + Refer to printf(3C).
58 55
59 -ERRORS
60 - The vprintf() and vfprintf() functions will fail if either the stream
61 - is unbuffered or the stream's buffer needed to be flushed and:
62 -
63 - EFBIG
64 - The file is a regular file and an attempt was made to write at
65 - or beyond the offset maximum.
66 -
67 -
68 56 EXAMPLES
69 - Example 1 Using vprintf() to write an error routine.
57 + Example 1 Using vprintf() to write an error routine.
70 58
59 + The following demonstrates how vfprintf() could be used to write an error
60 + routine:
71 61
72 - The following demonstrates how vfprintf() could be used to write an
73 - error routine:
62 + #include <stdarg.h>
63 + #include <stdio.h>
74 64
65 + /*
66 + * error should be called like
67 + * error(function_name, format, arg1, ...);
68 + */
69 + void
70 + error(char *function_name, char *format, ...)
71 + {
72 + va_list ap;
75 73
76 - #include <stdio.h>
77 - #include <stdarg.h>
78 - ...
79 - /*
80 - * error should be called like
81 - * error(function_name, format, arg1, ...);
82 - */
83 - void error(char *function_name, char *format, ...)
84 - {
85 - va_list ap;
86 - va_start(ap, format);
87 - /* print out name of function causing error */
88 - (void) fprintf(stderr, "ERR in %s: ", function_name);
89 - /* print out remainder of message */
90 - (void) vfprintf(stderr, format, ap);
91 - va_end(ap);
92 - (void) abort();
93 - }
74 + va_start(ap, format);
94 75
76 + /* Print out name of function causing error */
77 + (void) fprintf(stderr, "ERR in %s: ", function_name);
95 78
96 -ATTRIBUTES
97 - See attributes(5) for descriptions of the following attributes:
79 + /* Print out remainder of message */
80 + (void) vfprintf(stderr, format, ap);
98 81
82 + va_end(ap);
99 83
84 + (void) abort();
85 + }
100 86
87 +ERRORS
88 + The vfprintf() function will fail if either the stream is unbuffered or
89 + the stream's buffer needed to be flushed and:
101 90
102 - +--------------------+-----------------+
103 - | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
104 - +--------------------+-----------------+
105 - |Interface Stability | Committed |
106 - +--------------------+-----------------+
107 - |MT-Level | See below. |
108 - +--------------------+-----------------+
109 - |Standard | See below. |
110 - +--------------------+-----------------+
91 + EFBIG The file is a regular file and an attempt was made to
92 + write at or beyond the offset maximum.
111 93
94 +INTERFACE STABILITY
95 + Committed
112 96
113 - All of these functions can be used safely in multithreaded
114 - applications, as long as setlocale(3C) is not being called to change
115 - the locale.
97 +MT-LEVEL
98 + All of these functions can be used safely in multithreaded applications,
99 + as long as setlocale(3C) is not being called to change the locale.
116 100
117 -
118 - See standards(5) for the standards conformance of vprintf(),
119 - vfprintf(), vsprintf(), and vsnprintf(). The vasprintf() function is
120 - modeled on the one that appears in the FreeBSD, NetBSD, and GNU C
121 - libraries.
122 -
123 101 SEE ALSO
124 - printf(3C), attributes(5), stdarg(3EXT), attributes(5), standards(5)
102 + printf(3C), stdarg(3EXT), attributes(5), standards(5)
125 103
104 +STANDARDS
105 + See standards(5) for the standards conformance of vprintf(), vfprintf(),
106 + vsprintf(), and vsnprintf(). The vasprintf() function is modeled on the
107 + one that appears in the FreeBSD, NetBSD, and GNU C libraries.
108 +
126 109 NOTES
127 - The vsnprintf() return value when n = 0 was changed in the Solaris 10
128 - release. The change was based on the SUSv3 specification. The previous
129 - behavior was based on the initial SUSv2 specification, where
130 - vsnprintf() when n = 0 returns an unspecified value less than 1.
110 + The vsnprintf() return value when n is 0 was changed in the Solaris 10
111 + release. The change was based on the SUSv3 specification. The previous
112 + behavior was based on the initial SUSv2 specification, where vsnprintf()
113 + when n is 0 returns an unspecified value less than 1.
131 114
132 -
133 -
134 - January 7, 2009 VPRINTF(3C)
115 +illumos July 10, 2020 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX