diff options
Diffstat (limited to 'static/freebsd/man3/stdarg.3 3.html')
| -rw-r--r-- | static/freebsd/man3/stdarg.3 3.html | 182 |
1 files changed, 182 insertions, 0 deletions
diff --git a/static/freebsd/man3/stdarg.3 3.html b/static/freebsd/man3/stdarg.3 3.html new file mode 100644 index 00000000..287f235a --- /dev/null +++ b/static/freebsd/man3/stdarg.3 3.html @@ -0,0 +1,182 @@ +<table class="head"> + <tr> + <td class="head-ltitle">STDARG(3)</td> + <td class="head-vol">Library Functions Manual</td> + <td class="head-rtitle">STDARG(3)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">stdarg</code> — <span class="Nd">variable + argument lists</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="In">#include + <<a class="In">stdarg.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">va_start</code>(<var class="Fa" style="white-space: nowrap;">va_list + ap</var>, <var class="Fa" style="white-space: nowrap;">last</var>);</p> +<p class="Pp"><var class="Ft">type</var> + <br/> + <code class="Fn">va_arg</code>(<var class="Fa" style="white-space: nowrap;">va_list + ap</var>, <var class="Fa" style="white-space: nowrap;">type</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">va_copy</code>(<var class="Fa" style="white-space: nowrap;">va_list + dest</var>, <var class="Fa" style="white-space: nowrap;">va_list + src</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">va_end</code>(<var class="Fa" style="white-space: nowrap;">va_list + ap</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">A function may be called with a varying number of arguments of + varying types. The include file + <code class="In"><<a class="In">stdarg.h</a>></code> declares a type + (<i class="Em">va_list</i>) and defines four macros for stepping through a + list of arguments whose number and types are not known to the called + function.</p> +<p class="Pp" id="va_start">The called function must declare an object of type + <i class="Em">va_list</i> which is used by the macros + <a class="permalink" href="#va_start"><code class="Fn">va_start</code></a>(), + <code class="Fn">va_arg</code>(), <code class="Fn">va_copy</code>(), and + <code class="Fn">va_end</code>().</p> +<p class="Pp" id="va_start~2">The + <a class="permalink" href="#va_start~2"><code class="Fn">va_start</code></a>() + macro initializes <var class="Fa">ap</var> for subsequent use by + <code class="Fn">va_arg</code>(), <code class="Fn">va_copy</code>(), and + <code class="Fn">va_end</code>(), and must be called first.</p> +<p class="Pp">The parameter <var class="Fa">last</var> is the name of the last + parameter before the variable argument list, i.e., the last parameter of + which the calling function knows the type.</p> +<p class="Pp" id="va_start~3">Because the address of this parameter is used in + the + <a class="permalink" href="#va_start~3"><code class="Fn">va_start</code></a>() + macro, it should not be declared as a register variable, or as a function or + an array type.</p> +<p class="Pp" id="va_arg">The + <a class="permalink" href="#va_arg"><code class="Fn">va_arg</code></a>() + macro expands to an expression that has the type and value of the next + argument in the call. The parameter <var class="Fa">ap</var> is the + <i class="Em">va_list</i> <var class="Fa">ap</var> initialized by + <code class="Fn">va_start</code>() or <code class="Fn">va_copy</code>(). + Each call to <code class="Fn">va_arg</code>() modifies + <var class="Fa">ap</var> so that the next call returns the next argument. + The parameter <var class="Fa">type</var> is a type name specified so that + the type of a pointer to an object that has the specified type can be + obtained simply by adding a * to <var class="Fa">type</var>.</p> +<p class="Pp">If there is no next argument, or if <var class="Fa">type</var> is + not compatible with the type of the actual next argument (as promoted + according to the default argument promotions), random errors will occur.</p> +<p class="Pp" id="va_arg~2">The first use of the + <a class="permalink" href="#va_arg~2"><code class="Fn">va_arg</code></a>() + macro after that of the <code class="Fn">va_start</code>() macro returns the + argument after <var class="Fa">last</var>. Successive invocations return the + values of the remaining arguments.</p> +<p class="Pp" id="va_copy">The + <a class="permalink" href="#va_copy"><code class="Fn">va_copy</code></a>() + macro copies a variable argument list, previously initialized by + <code class="Fn">va_start</code>(), from <var class="Fa">src</var> to + <var class="Fa">dest</var>. The state is preserved such that it is + equivalent to calling <code class="Fn">va_start</code>() with the same + second argument used with <var class="Fa">src</var>, and calling + <code class="Fn">va_arg</code>() the same number of times as called with + <var class="Fa">src</var>.</p> +<p class="Pp" id="va_end">The + <a class="permalink" href="#va_end"><code class="Fn">va_end</code></a>() + macro cleans up any state associated with the variable argument list + <var class="Fa">ap</var>.</p> +<p class="Pp" id="va_start~4">Each invocation of + <a class="permalink" href="#va_start~4"><code class="Fn">va_start</code></a>() + or <code class="Fn">va_copy</code>() must be paired with a corresponding + invocation of <code class="Fn">va_end</code>() in the same function.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">The <code class="Fn">va_arg</code>() macro returns the value of + the next argument.</p> +<p class="Pp">The <code class="Fn">va_start</code>(), + <code class="Fn">va_copy</code>(), and <code class="Fn">va_end</code>() + macros return no value.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">The function + <a class="permalink" href="#foo"><i class="Em" id="foo">foo</i></a> takes a + string of format characters and prints out the argument associated with each + format character based on the type.</p> +<div class="Bd Pp Bd-indent Li"> +<pre>void foo(char *fmt, ...) +{ + va_list ap; + int d; + char c, *s; + + va_start(ap, fmt); + while (*fmt) + switch(*fmt++) { + case 's': /* string */ + s = va_arg(ap, char *); + printf("string %s\n", s); + break; + case 'd': /* int */ + d = va_arg(ap, int); + printf("int %d\n", d); + break; + case 'c': /* char */ + /* Note: char is promoted to int. */ + c = va_arg(ap, int); + printf("char %c\n", c); + break; + } + va_end(ap); +}</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="COMPATIBILITY"><a class="permalink" href="#COMPATIBILITY">COMPATIBILITY</a></h1> +<p class="Pp">These macros are + <a class="permalink" href="#not"><i class="Em" id="not">not</i></a> + compatible with the historic macros they replace.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="STANDARDS"><a class="permalink" href="#STANDARDS">STANDARDS</a></h1> +<p class="Pp">The <code class="Fn">va_start</code>(), + <code class="Fn">va_arg</code>(), <code class="Fn">va_copy</code>(), and + <code class="Fn">va_end</code>() macros conform to <span class="St">ISO/IEC + 9899:1999 (“ISO C99”)</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Fn">va_start</code>(), + <code class="Fn">va_arg</code>() and <code class="Fn">va_end</code>() macros + were introduced in <span class="St">ANSI X3.159-1989 + (“ANSI C89”)</span>. The + <code class="Fn">va_copy</code>() macro was introduced in + <span class="St">ISO/IEC 9899:1999 + (“ISO C99”)</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">Unlike the <i class="Em">varargs</i> macros, the + <code class="Nm">stdarg</code> macros do not permit programmers to code a + function with no fixed arguments. This problem generates work mainly when + converting <i class="Em">varargs</i> code to <code class="Nm">stdarg</code> + code, but it also creates difficulties for variadic functions that wish to + pass all of their arguments on to a function that takes a + <i class="Em">va_list</i> argument, such as + <a class="Xr">vfprintf(3)</a>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">October 18, 2024</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |