draft/man3/stdarg.3

   1 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the American National Standards Committee X3, on Information
   6 .\" Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)stdarg.3    6.8 (Berkeley) 6/29/91
  37 .\"
  38 .\" Converted for Linux, Mon Nov 29 15:11:11 1993, faith@cs.unc.edu
  39 .\" Additions, 2001-10-14, aeb
  40 .\"
  41 .\" Japanese Version Copyright (c) 1998 NAKANO Takeo all rights reserved.
  42 .\" Translated Fri Mar 22 1998 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
  43 .\" Updated Tue Oct 16 2001 by Kentaro Shirakata <argrath@ub32.org>
  44 .\"
  45 .TH STDARG 3  2001-10-14 "" "Linux Programmer's Manual"
  46 .SH 名前
  47 stdarg, va_start, va_arg, va_end, va_copy \- 個数・型が可変な引数リスト
  48 .SH 書式
  49 .B #include <stdarg.h>
  50 .sp
  51 .BI "void va_start(va_list " ap ", " last );
  52 .br
  53 .IB type " va_arg(va_list " ap ", " type );
  54 .br
  55 .BI "void va_end(va_list " ap );
  56 .br
  57 .BI "void va_copy(va_list " dest ", va_list " src );
  58 .\"O .SH DESCRIPTION
  59 .SH 説明
  60 .\"O A function may be called with a varying number of arguments of varying
  61 .\"O types.
  62 .\"O The include file
  63 .\"O .I <stdarg.h>
  64 .\"O declares a type
  65 .\"O .I va_list
  66 .\"O and defines three macros for stepping through a list of arguments whose
  67 .\"O number and types are not known to the called function.
  68 関数は呼び出しに際して、個数や型が可変な引数をとることができる。
  69 インクルードファイル
  70 .I <stdarg.h>
  71 では
  72 .I va_list
  73 型が宣言されており、3 つのマクロが定義されている。これらを用いると、
  74 呼び出された関数側では個数や型を知らない引き数のリストを、順に一
  75 つづつ読み込むことができる。
  76 .PP
  77 .\"O The called function must declare an object of type
  78 .\"O .I va_list
  79 .\"O which is used by the macros
  80 .\"O .BR va_start (),
  81 .\"O .BR va_arg (),
  82 .\"O and
  83 .\"O .BR va_end ().
  84 呼び出される関数では、
  85 .I va_list
  86 型のオブジェクトが宣言されていなければならない。このオブジェクトが
  87 .BR va_start (),
  88 .BR va_arg (),
  89 .BR va_end ()
  90 の各マクロによって扱われる。
  91 .SS va_start()
  92 .\"O The
  93 .\"O .BR va_start ()
  94 .\"O macro initializes
  95 .\"O .I ap
  96 .\"O for subsequent use by
  97 .\"O .BR va_arg ()
  98 .\"O and
  99 .\"O .BR va_end (),
 100 .\"O and must be called first.
 101 .BR va_start ()
 102 マクロは最初に呼び出さなければならない。これは
 103 .I ap
 104 を初期化し、
 105 .BR va_arg ()
 106 と
 107 .BR va_end ()
 108 で用いることができるようにする。
 109 .PP
 110 .\"O The argument
 111 .\"O .I last
 112 .\"O is the name of the last argument before the variable argument list, that is,
 113 .\"O the last argument of which the calling function knows the type.
 114 引き数
 115 .I last
 116 は引き数リストのうち、可変な部分の直前に置かれる引き数の名前であ
 117 る。つまり呼び出された関数が型を知っている最後の引き数である。
 118 .PP
 119 .\"O Because the address of this argument may be used in the
 120 .\"O .BR va_start ()
 121 .\"O macro, it should not be declared as a register variable,
 122 .\"O or as a function or an array type.
 123 この引き数はレジスタ変数や関数、配列として
 124 宣言してはならない。この引き数のアドレスが
 125 .BR va_start ()
 126 マクロで用いられるかもしれないからである。
 127 .SS va_arg()
 128 .\"O The
 129 .\"O .BR va_arg ()
 130 .\"O macro expands to an expression that has the type and value of the next
 131 .\"O argument in the call.
 132 .\"O The argument
 133 .\"O .I ap
 134 .\"O is the
 135 .\"O .I va_list
 136 .\"O .I ap
 137 .\"O initialized by
 138 .\"O .BR va_start ().
 139 .BR va_arg ()
 140 マクロは、呼び出し時に指定された引き数のうち、
 141 次の位置にあるものを指定した型
 142 .I type
 143 の値として取得する。
 144 引き数
 145 .I ap
 146 は
 147 .I va_list
 148 .I ap
 149 で、
 150 .BR va_start ()
 151 によって初期化されている必要がある。
 152 .\"O Each call to
 153 .\"O .BR va_arg ()
 154 .\"O modifies
 155 .\"O .I ap
 156 .\"O so that the next call returns the next argument.
 157 .\"O The argument
 158 .\"O .I type
 159 .\"O is a type name specified so that the type of a pointer to an object that
 160 .\"O has the specified type can be obtained simply by adding a * to
 161 .\"O .IR type .
 162 .BR va_arg ()
 163 を呼び出すごとに
 164 .I ap
 165 は変更され、次回の呼び出しの際に、さらに次の引き数を返すようになる。
 166 引き数
 167 .I type
 168 は型の名前である。
 169 .I type
 170 の前に * を付ければ、オブジェクトへの型付きポインタが得られる。
 171 .PP
 172 .\"O The first use of the
 173 .\"O .BR va_arg ()
 174 .\"O macro after that of the
 175 .\"O .BR va_start ()
 176 .\"O macro returns the argument after
 177 .\"O .IR last .
 178 .\"O Successive invocations return the values of the remaining arguments.
 179 .BR va_start ()
 180 マクロの直後に
 181 .BR va_arg ()
 182 を最初に実行すると、
 183 .I last
 184 の次の引き数が返る。続けて実行すると、残りの引き数がそれぞれ返る。
 185 .PP
 186 .\"O If there is no next argument, or if
 187 .\"O .I type
 188 .\"O is not compatible with the type of the actual next argument (as promoted
 189 .\"O according to the default argument promotions), random errors will occur.
 190 次の引き数がなかったり、
 191 .I type
 192 が次の引き数の実際の型と互換でない場合 (デフォルトの引き数変換で扱
 193 えなかった場合) には、予測できないエラーが起こる。
 194 .PP
 195 .\"O If
 196 .\"O .I ap
 197 .\"O is passed to a function that uses
 198 .\"O .BI va_arg( ap , type )
 199 .\"O then the value of
 200 .\"O .I ap
 201 .\"O is undefined after the return of that function.
 202 .I ap
 203 が
 204 .BI va_arg( ap , type )
 205 の形で関数に渡されると、
 206 .I ap
 207 の値は関数から返って来た後は不定となる。
 208 .SS va_end()
 209 .\"O Each invocation of
 210 .\"O .BR va_start ()
 211 .\"O must be matched by a corresponding invocation of
 212 .\"O .BR va_end ()
 213 .\"O in the same function.
 214 .\"O After the call
 215 .\"O .BI va_end( ap )
 216 .\"O the variable
 217 .\"O .I ap
 218 .\"O is undefined.
 219 .\"O Multiple traversals of the list, each
 220 .\"O bracketed by
 221 .\"O .BR va_start ()
 222 .\"O and
 223 .\"O .BR va_end ()
 224 .\"O are possible.
 225 .BR va_start ()
 226 が実行される毎に、同じ関数内で対応する
 227 .BR va_end ()
 228 が実行されなければならない。
 229 .BI va_end( ap )
 230 が呼び出された後、変数
 231 .I ap
 232 の値は不定となる。
 233 .BR va_start ()
 234 と
 235 .BR va_end ()
 236 の組を何回も並べて使うことも可能である。
 237 .\"O .BR va_end ()
 238 .\"O may be a macro or a function.
 239 .BR va_end ()
 240 はマクロかもしれないし関数かもしれない。
 241 .SS va_copy()
 242 .\"O .\" Proposal from clive@demon.net, 1997-02-28
 243 .\"O An obvious implementation would have a
 244 .\"O .I va_list
 245 .\"O be a pointer to the stack frame of the variadic function.
 246 すぐ分かる
 247 .I va_list
 248 の実装は、variadic な関数のスタックフレームのポインタである。
 249 .\"argrath: variadic?
 250 .\"O In such a setup (by far the most common) there seems
 251 .\"O nothing against an assignment
 252 このような場合(ほとんどはそうである)、
 253 単に以下のようにすればいいように思える。
 254 .in +4n
 255 .nf
 256
 257 va_list aq = ap;
 258
 259 .fi
 260 .in
 261 .\"O Unfortunately, there are also systems that make it an
 262 .\"O array of pointers (of length 1), and there one needs
 263 残念ながら、(長さ 1の)ポインタの配列として扱うシステムもある。
 264 そのような場合、以下のようにする必要がある。
 265 .in +4n
 266 .nf
 267
 268 va_list aq;
 269 *aq = *ap;
 270
 271 .fi
 272 .in
 273 .\"O Finally, on systems where arguments are passed in registers,
 274 .\"O it may be necessary for
 275 .\"O .BR va_start ()
 276 .\"O to allocate memory, store the arguments there, and also
 277 .\"O an indication of which argument is next, so that
 278 .\"O .BR va_arg ()
 279 .\"O can step through the list.
 280 .\"O Now
 281 .\"O .BR va_end ()
 282 .\"O can free the allocated memory again.
 283 最後に、引き数をレジスタで渡すシステムの場合、
 284 .BR va_start ()
 285 でメモリを割り当て、引き数を格納し、
 286 次の引き数がどれかを指し示すようにする必要がある。
 287 そして
 288 .BR va_arg ()
 289 でリストを順番にたどり、
 290 .BR va_end ()
 291 で割り当てたメモリを開放する。
 292 .\"O To accommodate this situation, C99 adds a macro
 293 .\"O .BR va_copy (),
 294 .\"O so that the above assignment can be replaced by
 295 このような状況に対応するため、C99 では
 296 .BR va_copy ()
 297 マクロを追加し、
 298 前述のような割り当ては以下のように置き換えられるようにした。
 299 .in +4n
 300 .nf
 301
 302 va_list aq;
 303 va_copy(aq, ap);
 304 \&...
 305 va_end(aq);
 306
 307 .fi
 308 .in
 309 .RE
 310 .\"O Each invocation of
 311 .\"O .BR va_copy ()
 312 .\"O must be matched by a corresponding invocation of
 313 .\"O .BR va_end ()
 314 .\"O in the same function.
 315 .BR va_copy ()
 316 が実行されるごとに、
 317 対応する
 318 .BR va_end ()
 319 を同じ関数内で実行しなければならない。
 320 .\"O Some systems that do not supply
 321 .\"O .BR va_copy ()
 322 .\"O have
 323 .\"O .B __va_copy
 324 .\"O instead, since that was the name used in the draft proposal.
 325 この名前はまだ draft proposal なので、
 326 .BR va_copy ()
 327 の代わりに
 328 .B __va_copy
 329 を用いるシステムもある。
 330 .SH 準拠
 331 .BR va_start (),
 332 .BR va_arg (),
 333 .BR va_end ()
 334 マクロは C89 準拠である。
 335 .\"O C99 defines the
 336 .\"O .BR va_copy ()
 337 .\"O macro.
 338 .BR va_copy ()
 339 は C99 で定義されている。
 340 .\"O .SH NOTES
 341 .SH 注意
 342 .\"O These macros are
 343 .\"O .I not
 344 .\"O compatible with the historic macros they replace.
 345 .\"O A backward-compatible version can be found in the include file
 346 .\"O .IR <varargs.h> .
 347 これらのマクロは、以前から用いられてきた同等のマクロ群と
 348 互換では\fIない\fP。過去のものと互換なバージョンは、
 349 インクルードファイル
 350 .I <varargs.h>
 351 に存在する。
 352 .PP
 353 .\"O The historic setup is:
 354 歴史的なセットアップは以下のとおりである。
 355 .in +4n
 356 .nf
 357
 358 #include <varargs.h>
 359
 360 void
 361 foo(va_alist)
 362     va_dcl
 363 {
 364     va_list ap;
 365
 366     va_start(ap);
 367     while (...) {
 368         ...
 369         x = va_arg(ap, type);
 370         ...
 371     }
 372     va_end(ap);
 373 }
 374
 375 .fi
 376 .in
 377 .\"O On some systems,
 378 .\"O .I va_end
 379 .\"O contains a closing \(aq}\(aq matching a \(aq{\(aq in
 380 .\"O .IR va_start ,
 381 .\"O so that both macros must occur in the same function, and in a way
 382 .\"O that allows this.
 383 .I va_start
 384 マクロに \(aq}\(aq を含み、
 385 .I va_end
 386 マクロに対応する \(aq{\(aq を含むシステムもあるので、
 387 この二つのマクロは同じ関数になければならない。
 388 .\"O .SH BUGS
 389 .SH バグ
 390 .\"O Unlike the
 391 .\"O .B varargs
 392 .\"O macros, the
 393 .\"O .B stdarg
 394 .\"O macros do not permit programmers to code a function with no fixed
 395 .\"O arguments.
 396 .\"O This problem generates work mainly when converting
 397 .\"O .B varargs
 398 .\"O code to
 399 .\"O .B stdarg
 400 .\"O code, but it also creates difficulties for variadic functions that wish to
 401 .\"O pass all of their arguments on to a function that takes a
 402 .\"O .I va_list
 403 .\"O argument, such as
 404 .\"O .BR vfprintf (3).
 405 .B varargs
 406 マクロとは異なり、
 407 .B stdarg
 408 マクロでは固定引き数なしで関数を指定することが許されていない。
 409 これは
 410 .B varargs
 411 ベースのコードを
 412 .B stdarg
 413 のコードに書き換えるときに、面倒な作業のもとになる。
 414 また、すべての引き数を
 415 .I va_list
 416 として可変個指定したいような場合
 417 .RB ( vfprintf (3)
 418 など) にも障害となる。
 419 .\"O .SH EXAMPLE
 420 .SH 例
 421 関数
 422 .I foo
 423 は書式文字からなる文字列を受け入れ、その書式文字に対応する型で可変個の
 424 引き数を読み込み、印字する。
 425 .nf
 426
 427 #include <stdio.h>
 428 #include <stdarg.h>
 429
 430 void
 431 foo(char *fmt, ...)
 432 {
 433     va_list ap;
 434     int d;
 435     char c, *s;
 436
 437     va_start(ap, fmt);
 438     while (*fmt)
 439         switch (*fmt++) {
 440         case \(aqs\(aq:              /* string */
 441             s = va_arg(ap, char *);
 442             printf("string %s\en", s);
 443             break;
 444         case \(aqd\(aq:              /* int */
 445             d = va_arg(ap, int);
 446             printf("int %d\en", d);
 447             break;
 448         case \(aqc\(aq:              /* char */
 449             /* need a cast here since va_arg only
 450                takes fully promoted types */
 451             c = (char) va_arg(ap, int);
 452             printf("char %c\en", c);
 453             break;
 454         }
 455     va_end(ap);
 456 }
 457 .fi