va_start()

va_start() マクロは最初に呼び出さなければならない。これは ap を初期化し、 va_arg() と va_end() で用いることができるようにする。

引き数 last は引き数リストのうち、可変な部分の直前に置かれる引き数の名前である。つまり呼び出された関数が型を知っている最後の引き数である。

この引き数はレジスタ変数や関数、配列として宣言してはならない。この引き数のアドレスが va_start() マクロで用いられるかもしれないからである。

va_arg()

va_arg() マクロは、呼び出し時に指定された引き数のうち、次の位置にあるものを指定した型 type の値として取得する。引き数 ap は va_list ap で、 va_start() によって初期化されている必要がある。 va_arg() を呼び出すごとに ap は変更され、次回の呼び出しの際に、さらに次の引き数を返すようになる。引き数 type は型の名前である。 type の前に * を付ければ、オブジェクトへの型付きポインタが得られる。

va_start() マクロの直後に va_arg() を最初に実行すると、 last の次の引き数が返る。続けて実行すると、残りの引き数がそれぞれ返る。

次の引き数がなかったり、 type が次の引き数の実際の型と互換でない場合 (デフォルトの引き数変換で扱えなかった場合) には、予測できないエラーが起こる。

ap が va_arg(ap,type) の形で関数に渡されると、 ap の値は関数から返って来た後は不定となる。

va_end()

va_start() が実行される毎に、同じ関数内で対応する va_end() が実行されなければならない。 va_end( ap ) が呼び出された後、変数 ap の値は不定となる。 va_start() と va_end() の組を何回も並べて使うことも可能である。 va_end() はマクロかもしれないし関数かもしれない。

va_copy()

The va_copy() macro copies the (previously initialized) variable argument list src to dest. The behavior is as if va_start() were applied to dest with the same last argument, followed by the same number of va_arg() invocations that was used to reach the current state of src. すぐ分かる va_list の実装は、variadic な関数のスタックフレームのポインタである。このような場合(ほとんどはそうである)、単に以下のようにすればいいように思える。

va_list aq = ap;

残念ながら、(長さ 1の)ポインタの配列として扱うシステムもある。そのような場合、以下のようにする必要がある。

va_list aq;
*aq = *ap;

最後に、引き数をレジスタで渡すシステムの場合、 va_start() でメモリを割り当て、引き数を格納し、次の引き数がどれかを指し示すようにする必要がある。そして va_arg() でリストを順番にたどり、 va_end() で割り当てたメモリを開放する。このような状況に対応するため、C99 では va_copy() マクロを追加し、前述のような割り当ては以下のように置き換えられるようにした。

va_list aq;
va_copy(aq, ap);
...
va_end(aq);

va_copy() が実行されるごとに、対応する va_end() を同じ関数内で実行しなければならない。この名前はまだ draft proposal なので、 va_copy() の代わりに __va_copy を用いるシステムもある。