stdarg

OS/161 Reference Manual

Name

stdarg - handle functions with variable arguments

Library

Standard C Library (libc, -lc)

Synopsis

#include <stdarg.h>

va_start(va_list ap, start-argument);

va_end(va_list ap);

type
va_arg(va_list ap, type);

va_copy(va_list dest, va_list src);

Description

Functions where the number of arguments is not fixed at compile time can be written using the stdarg facility. This provides a type, va_list, and the macros listed above, which allow iterating through the arguments.

va_start initializes a va_list ap to point to the current function's arguments. The start-argument argument should be the name of the last fixed parameter in the calling sequence.

va_end cleans up a va_list once it is no longer needed. While failure to use va_end may have no effect on some architectures (in fact, in some cases va_end does nothing at all) on other architectures it may be fatal.

va_arg retrieves the next argument, which is presumed to be of type type. 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 va_end and then va_start again.

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 retrieve a type different from that which was passed using va_arg, you will silently get garbage for that and all subsequent arguments.

va_copy assigns a copy of src to dest. Subsequent operations on either will not affect the other.

Restrictions

Because the va_list is not necessarily a simple type, but may involve pointers to state maintained elsewhere, it is not necessarily a simple value. Thus, assigning va_lists to each other with `=', memcpy, or the like, or passing them to functions, may not give multiple independent objects. When in doubt, use va_copy, or invoke va_start multiple times.

Return Values

va_start, va_end, and va_copy do not return anything. va_arg returns the value of the requested argument.