124 lines
4.1 KiB
HTML
124 lines
4.1 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>stdarg(3)</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<H1>stdarg(3)</H1>
|
|
<HR>
|
|
<PRE>
|
|
|
|
</PRE>
|
|
<H2>NAME</H2><PRE>
|
|
stdarg - variable argument list
|
|
|
|
|
|
</PRE>
|
|
<H2>SYNOPSIS</H2><PRE>
|
|
<STRONG>#include</STRONG> <STRONG><stdarg.h></STRONG>
|
|
|
|
<STRONG>void</STRONG> <STRONG>va_start(va_list</STRONG> <EM>ap</EM><STRONG>,</STRONG> <EM>argtypeN</EM> <EM>parmN</EM><STRONG>)</STRONG>
|
|
<EM>type</EM> <STRONG>va_arg(va_list</STRONG> <EM>ap</EM><STRONG>,</STRONG> <EM>type</EM><STRONG>)</STRONG>
|
|
<STRONG>void</STRONG> <STRONG>va_end(va_list</STRONG> <EM>ap</EM><STRONG>)</STRONG>
|
|
|
|
|
|
</PRE>
|
|
<H2>DESCRIPTION</H2><PRE>
|
|
This set of macros provides a means of writing portable procedures that
|
|
accept variable argument lists. Routines having variable argument lists
|
|
(such as <STRONG><A HREF="../man3/printf.3.html">printf(3)</A></STRONG>) that do not use <STRONG>stdarg</STRONG> are inherently nonportable,
|
|
since different machines use different argument passing conventions.
|
|
|
|
A function that accepts a variable argument list is declared with "..."
|
|
at the end of its parameter list. It must have at least one normal
|
|
argument before the "...". For example:
|
|
|
|
int printf(const char *format, ...) { /* code */ }
|
|
int fprintf(FILE *stream, const char *format, ...) { /* code */ }
|
|
|
|
<STRONG>va_list</STRONG> is a type which is used for the variable <EM>ap</EM> within the body of a
|
|
variable argument function which is used to traverse the list.
|
|
|
|
<STRONG>va_start</STRONG>(<EM>ap</EM>, <EM>parmN</EM>) is called to initialize <EM>ap</EM> to the beginning of the
|
|
list. The last true parameter of the function, <EM>parmN</EM>, must be supplied
|
|
to allow <STRONG>va_start</STRONG> to compute the address of the first variable parameter.
|
|
|
|
<STRONG>va_arg</STRONG>(<EM>ap</EM>, <EM>type</EM>) will return the next argument in the list pointed to by
|
|
<EM>ap</EM>. <EM>Type</EM> is the type to which the expected argument will be converted
|
|
when passed as an argument.
|
|
|
|
Different types can be mixed, but it is up to the routine to know what
|
|
type of argument is expected, since it cannot be determined at runtime.
|
|
|
|
<STRONG>va_end</STRONG>(<EM>ap</EM>) must be used to finish up.
|
|
|
|
Multiple traversals, each bracketed by <STRONG>va_start</STRONG> ... <STRONG>va_end,</STRONG> are
|
|
possible.
|
|
|
|
|
|
</PRE>
|
|
<H2>EXAMPLE</H2><PRE>
|
|
<STRONG>#include</STRONG> <stdarg.h>
|
|
|
|
execl(<STRONG>const</STRONG> <STRONG>char</STRONG> *path, <STRONG>...</STRONG>)
|
|
{
|
|
<STRONG>va_list</STRONG> ap;
|
|
<STRONG>char</STRONG> *args[100];
|
|
<STRONG>int</STRONG> argno = 0;
|
|
<STRONG>va_start</STRONG>(ap, path);
|
|
<STRONG>while</STRONG> ((args[argno++] = <STRONG>va_arg</STRONG>(ap, <STRONG>char</STRONG> *)) != NULL) {}
|
|
<STRONG>va_end</STRONG>(ap);
|
|
<STRONG>return</STRONG> execv(path, args);
|
|
}
|
|
|
|
|
|
</PRE>
|
|
<H2>NOTES</H2><PRE>
|
|
It is up to the calling routine to determine how many arguments there
|
|
are, since it is not possible to determine this from the stack frame.
|
|
For example, <STRONG>execl</STRONG> passes a null pointer to signal the end of the list.
|
|
<STRONG>Printf</STRONG> can tell how many arguments are supposed to be there by the
|
|
format.
|
|
|
|
The macros <STRONG>va_start</STRONG> and <STRONG>va_end</STRONG> may be arbitrarily complex; for example,
|
|
<STRONG>va_start</STRONG> might contain an opening brace, which is closed by a matching
|
|
brace in <STRONG>va_end</STRONG>. Thus, they should only be used where they could be
|
|
placed within a single complex statement.
|
|
|
|
|
|
</PRE>
|
|
<H2>BUGS</H2><PRE>
|
|
It is impossible to properly show the macros as C declarations as is done
|
|
in the synopsis. They can never be coded as C functions, because all
|
|
three macros use their arguments by address, and the <EM>type</EM> field is
|
|
certainly impossible. Just look at them as being part of the C language,
|
|
like <STRONG>sizeof</STRONG>.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</PRE>
|
|
</BODY>
|
|
</HTML>
|