<!-- Copyright (c) 2000, 2001, 2002, 2003, 2004, 2005, 2008, 2009, 2013 The President and Fellows of Harvard College. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE UNIVERSITY OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. --> <html> <head> <title>stdarg</title> <body bgcolor=#ffffff> <h2 align=center>stdarg</h2> <h4 align=center>OS/161 Reference Manual</h4> <h3>Name</h3> <p> stdarg - handle functions with variable arguments </p> <h3>Library</h3> <p> Standard C Library (libc, -lc) </p> <h3>Synopsis</h3> <p> <tt>#include <stdarg.h></tt><br> <br> <tt>va_start(va_list </tt><em>ap</em><tt>, </tt><em>start-argument</em><tt>);</tt><br> <br> <tt>va_end(va_list </tt><em>ap</em><tt>);</tt><br> <br> <em>type</em><br> <tt>va_arg(va_list </tt><em>ap</em><tt>, </tt><em>type</em><tt>);</tt><br> <br> <tt>va_copy(va_list </tt><em>dest</em><tt>, va_list </tt><em>src</em><tt>);</tt><br> </p> <h3>Description</h3> <p> Functions where the number of arguments is not fixed at compile time can be written using the stdarg facility. This provides a type, <tt>va_list</tt>, and the macros listed above. These allow iterating through the arguments. </p> <p> <tt>va_start</tt> initializes a <tt>va_list</tt> <em>ap</em> to point to the current function's arguments. The <em>start-argument</em> argument should be the name of the last fixed parameter in the calling sequence. (There must be at least one fixed parameter.) </p> <p> <tt>va_end</tt> cleans up a <tt>va_list</tt> once it is no longer needed. While failure to use <tt>va_end</tt> may have no effect on some architectures (in fact, in some cases <tt>va_end</tt> does nothing at all) on other architectures it may be fatal. </p> <p> <tt>va_arg</tt> retrieves the next argument, which is presumed to be of type <em>type</em>. The function must have some way to determine what types to expect, and how many arguments, as this information cannot be extracted from the argument list itself. To rewind, use <tt>va_end</tt> and then <tt>va_start</tt> again. </p> <p> Remember that default C argument promotions occur when passing the variable arguments. There is no run-time checking of any kind, and little to no compile-time checking: if you use <tt>va_arg</tt> to retrieve a type different from that which was passed, you will silently get garbage for that and (usually) all subsequent arguments. </p> <p> <tt>va_copy</tt> assigns a copy of <em>src</em> to <em>dest</em>. Subsequent operations on either will not affect the other. Both copies need to be cleaned up with <tt>va_end</tt>. f/<p> <h3>Restrictions</h3> <p> Because the <tt>va_list</tt> is not necessarily a simple type, but may involve pointers to state maintained elsewhere, it is not necessarily a simple value. Thus, assigning <tt>va_list</tt> objects to each other with `=', memcpy, or the like, or passing them to functions, may not give multiple independent objects. When in doubt, use <tt>va_copy</tt>, or invoke <tt>va_start</tt> multiple times. </p> <h3>Return Values</h3> <p> <tt>va_start</tt>, <tt>va_end</tt>, and <tt>va_copy</tt> do not return anything. <tt>va_arg</tt> returns the value of the requested argument. </p> </body> </html>