194 lines
7.9 KiB
HTML
194 lines
7.9 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title><stdarg.h></title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="<stdarg.h>"></a> <a name="tag_13_45"></a><!-- <stdarg.h> -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_13_45_01"></a>NAME</h4>
|
|
|
|
<blockquote>stdarg.h - handle variable argument list</blockquote>
|
|
|
|
<h4><a name="tag_13_45_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><tt>#include <stdarg.h><br>
|
|
<br>
|
|
void va_start(va_list</tt> <i>ap</i><tt>,</tt> <i>argN</i><tt>);<br>
|
|
void va_copy(va_list</tt> <i>dest</i><tt>, va_list</tt> <i>src</i><tt>);<br>
|
|
type va_arg(va_list</tt> <i>ap</i><tt>,</tt> <i>type</i><tt>);<br>
|
|
void va_end(va_list</tt> <i>ap</i><tt>);<br>
|
|
</tt></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_45_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<div class="box"><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]"
|
|
border="0"> The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the
|
|
requirements described here and the ISO C standard is unintentional. This volume of IEEE Std 1003.1-2001 defers to
|
|
the ISO C standard. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></div>
|
|
|
|
<p>The <i><stdarg.h></i> header shall contain a set of macros which allows portable functions that accept variable argument
|
|
lists to be written. Functions that have variable argument lists (such as <a href="../functions/printf.html"><i>printf</i>()</a>)
|
|
but do not use these macros are inherently non-portable, as different systems use different argument-passing conventions.</p>
|
|
|
|
<p>The type <b>va_list</b> shall be defined for variables used to traverse the list.</p>
|
|
|
|
<p>The <i>va_start</i>() macro is invoked to initialize <i>ap</i> to the beginning of the list before any calls to
|
|
<i>va_arg</i>().</p>
|
|
|
|
<p>The <i>va_copy</i>() macro initializes <i>dest</i> as a copy of <i>src</i>, as if the <i>va_start</i>() macro had been applied
|
|
to <i>dest</i> followed by the same sequence of uses of the <i>va_arg</i>() macro as had previously been used to reach the present
|
|
state of <i>src</i>. Neither the <i>va_copy</i>() nor <i>va_start</i>() macro shall be invoked to reinitialize <i>dest</i> without
|
|
an intervening invocation of the <i>va_end</i>() macro for the same <i>dest</i>.</p>
|
|
|
|
<p>The object <i>ap</i> may be passed as an argument to another function; if that function invokes the <i>va_arg</i>() macro with
|
|
parameter <i>ap</i>, the value of <i>ap</i> in the calling function is unspecified and shall be passed to the <i>va_end</i>() macro
|
|
prior to any further reference to <i>ap</i>. The parameter <i>argN</i> is the identifier of the rightmost parameter in the variable
|
|
parameter list in the function definition (the one just before the ...). If the parameter <i>argN</i> is declared with the
|
|
<b>register</b> storage class, with a function type or array type, or with a type that is not compatible with the type that results
|
|
after application of the default argument promotions, the behavior is undefined.</p>
|
|
|
|
<p>The <i>va_arg</i>() macro shall return the next argument in the list pointed to by <i>ap</i>. Each invocation of <i>va_arg</i>()
|
|
modifies <i>ap</i> so that the values of successive arguments are returned in turn. The <i>type</i> parameter shall be a type name
|
|
specified such that the type of a pointer to an object that has the specified type can be obtained simply by postfixing a
|
|
<tt>'*'</tt> to type. If there is no actual next argument, or if <i>type</i> is not compatible with the type of the actual next
|
|
argument (as promoted according to the default argument promotions), the behavior is undefined, except for the following cases:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>One type is a signed integer type, the other type is the corresponding unsigned integer type, and the value is representable in
|
|
both types.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>One type is a pointer to <b>void</b> and the other is a pointer to a character type.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Both types are pointers. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Different types can be mixed, but it is up to the routine to know what type of argument is expected.</p>
|
|
|
|
<p>The <i>va_end</i>() macro is used to clean up; it invalidates <i>ap</i> for use (unless <i>va_start</i>() or <i>va_copy</i>() is
|
|
invoked again).</p>
|
|
|
|
<p>Each invocation of the <i>va_start</i>() and <i>va_copy</i>() macros shall be matched by a corresponding invocation of the
|
|
<i>va_end</i>() macro in the same function.</p>
|
|
|
|
<p>Multiple traversals, each bracketed by <i>va_start</i>() ... <i>va_end</i>(), are possible.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_45_04"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>This example is a possible implementation of <a href="../functions/execl.html"><i>execl</i>()</a>:</p>
|
|
|
|
<pre>
|
|
<tt>#include <stdarg.h>
|
|
<br>
|
|
#define MAXARGS 31
|
|
|
|
<br>
|
|
/*
|
|
* execl is called by
|
|
* execl(file, arg1, arg2, ..., (char *)(0));
|
|
*/
|
|
int execl(const char *file, const char *args, ...)
|
|
{
|
|
va_list ap;
|
|
char *array[MAXARGS +1];
|
|
int argno = 0;
|
|
<br>
|
|
va_start(ap, args);
|
|
while (args != 0 && argno < MAXARGS)
|
|
{
|
|
array[argno++] = args;
|
|
args = va_arg(ap, const char *);
|
|
}
|
|
array[argno] = (char *) 0;
|
|
va_end(ap);
|
|
return execv(file, array);
|
|
}
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_13_45_05"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>It is up to the calling routine to communicate to the called routine how many arguments there are, since it is not always
|
|
possible for the called routine to determine this in any other way. For example, <a href=
|
|
"../functions/execl.html"><i>execl</i>()</a> is passed a null pointer to signal the end of the list. The <a href=
|
|
"../functions/printf.html"><i>printf</i>()</a> function can tell how many arguments are there by the <i>format</i> argument.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_45_06"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_45_07"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_45_08"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p>The System Interfaces volume of IEEE Std 1003.1-2001, <i>exec</i>, <a href=
|
|
"../functions/printf.html"><i>printf</i>()</a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_45_09"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 4. Derived from the ANSI C standard.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_45_10"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>This reference page is updated to align with the ISO/IEC 9899:1999 standard.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|