draft/man3/getaddrinfo_a.3

   1 .\" Copyright (c) 2009 Petr Baudis <pasky@suse.cz>
   2 .\" and clean-ups and additions (C) 2010 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" References: http://people.redhat.com/drepper/asynchnl.pdf,
  27 .\"     http://www.imperialviolet.org/2005/06/01/asynchronous-dns-lookups-with-glibc.html
  28 .\"
  29 .\"*******************************************************************
  30 .\"
  31 .\" This file was generated with po4a. Translate the source file.
  32 .\"
  33 .\"*******************************************************************
  34 .TH GETADDRINFO_A 3 2014\-05\-28 GNU "Linux Programmer's Manual"
  35 .SH 名前
  36 getaddrinfo_a, gai_suspend, gai_error, gai_cancel \- 非同期のネットワークアドレスとサービスの変換
  37 .SH 書式
  38 .nf
  39 \fB#define _GNU_SOURCE\fP         /* feature_test_macros(7) 参照 */
  40 \fB#include <netdb.h>\fP
  41 .sp
  42 \fBint getaddrinfo_a(int \fP\fImode\fP\fB, struct gaicb *\fP\fIlist[]\fP\fB,\fP
  43 \fB                int \fP\fInitems\fP\fB, struct sigevent *\fP\fIsevp\fP\fB);\fP
  44 .sp
  45 \fBint gai_suspend(const struct gaicb * const \fP\fIlist[]\fP\fB, int \fP\fInitems\fP\fB,\fP
  46 \fB                const struct timespec *\fP\fItimeout\fP\fB);\fP
  47 .sp
  48 \fBint gai_error(struct gaicb *\fP\fIreq\fP\fB);\fP
  49 .sp
  50 \fBint gai_cancel(struct gaicb *\fP\fIreq\fP\fB);\fP
  51 .sp
  52 \fI\-lanl\fP でリンクする。
  53 .fi
  54 .SH 説明
  55 \fBgetaddrinfo_a\fP() 関数は \fBgetaddrinfo\fP(3) と同じ処理を実行するが、 複数の名前検索を非同期で実行でき、
  56 検索処理の完了の通知ができる点が異なる。
  57
  58 \fImode\fP 引き数は以下の値のいずれかを指定する。
  59 .TP
  60 \fBGAI_WAIT\fP
  61 検索を同期で実行する。 呼び出しは検索が完了するまで停止 (block) する。
  62 .TP
  63 \fBGAI_NOWAIT\fP
  64 検索を非同期で実行する。 呼び出しは直ちに返り、 要求はバックグラウンドで処理される。 以下の \fIsevp\fP 引き数の議論を参照。
  65 .PP
  66 配列 \fIlist\fP は処理すべき検索要求を指定する。 \fInitems\fP 引き数は \fIlist\fP の要素数を指定する。
  67 要求された検索命令は並列に開始される。 \fIlist\fP の NULL 要素は無視される。 各要求は以下のように定義された \fIgaicb\fP
  68 構造体で規定される。
  69 .sp
  70 .in +4n
  71 .nf
  72 struct gaicb {
  73     const char            *ar_name;
  74     const char            *ar_service;
  75     const struct addrinfo *ar_request;
  76     struct addrinfo       *ar_result;
  77 };
  78 .fi
  79 .in
  80
  81 この構造体の要素は \fBgetaddrinfo\fP(3) の引き数に対応している。 したがって、 \fIar_name\fP はインターネットホストを示す
  82 \fInode\fP 引き数に、 \fIar_service\fP はサービスを示す \fIservice\fP 引き数に対応する。 \fIar_request\fP 要素は、
  83 返されたソケットアドレス構造体を選択する基準を示す \fIhints\fP 引き数に対応する。 最後の \fIar_request\fP は \fIres\fP
  84 引き数に対応する。 この要素を初期化する必要はなく、この要素は要求が解決されると自動的にセットされる。 最後の 2 つの要素が参照している
  85 \fIaddrinfo\fP 構造体については \fBgetaddrinfo\fP(3) に説明がある。
  86
  87 \fImode\fP に \fBGAI_NOWAIT\fP が指定された場合、 解決した要求に関する通知を \fIsevp\fP 引き数が指す \fIsigevent\fP
  88 構造体を使って受け取ることができる。 この構造体の定義と一般的な説明については \fBsigevent\fP(7) を参照。
  89 \fIsevp\->sigev_notify\fP フィールドには以下の値を指定できる。
  90 .TP
  91 \fBSIGEV_NONE\fP
  92 通知は行わない。
  93 .TP
  94 \fBSIGEV_SIGNAL\fP
  95 .\" si_pid and si_uid are also set, to the values of the calling process,
  96 .\" which doesn't provide useful information, so we'll skip mentioning it.
  97 検索が完了した際に、 プロセスに対してシグナル \fIsigev_signo\fP を生成する。 一般的な説明は \fBsigevent\fP(7) を参照。
  98 \fIsiginfo_t\fP 構造体の \fIsi_code\fP フィールドには \fBSI_ASYNCNL\fP がセットされる。
  99 .TP
 100 \fBSIGEV_THREAD\fP
 101 検索が完了した際に、 \fIsigev_notify_function\fP を新しいスレッドの開始関数であるかのように起動する。 詳細は
 102 \fBsigevent\fP(7) を参照。
 103 .PP
 104 \fBSIGEV_SIGNAL\fP と \fBSIGEV_THREAD\fP では、 \fIsevp\->sigev_value.sival_ptr\fP が
 105 \fIlist\fP を指すようにしておくと役立つことがある。
 106
 107 \fBgai_suspend\fP() 関数は呼び出し元のスレッドの実行を中断し、 配列 \fIlist\fP 内の一つ以上の要求が完了するのを待つ。
 108 \fInitems\fP 引き数は配列 \fIlist\fP の大きさを指定する。 呼び出しは以下のいずれかの状況になるまで停止する。
 109 .IP * 3
 110 \fIlist\fP 内の一つ以上の操作が完了した。
 111 .IP *
 112 呼び出しが補足されたシグナルに割り込まれた。
 113 .IP *
 114 \fItimeout\fP で指定された期間が経過した。 この引き数は、秒とナノ秒でタイムアウトを指定する (\fItimespec\fP 構造体の詳細は
 115 \fBnanosleep\fP(2) を参照)。 \fItimeout\fP が NULL の場合、 (上記のイベントのいずれかが発生するまで)
 116 呼び出しは無限に停止する。
 117 .PP
 118 どの要求が完了したかは明示的な通知は行われない。 どの要求が完了したかを知るためには、 要求のリストに対して \fBgai_error\fP()
 119 を繰り返し呼び出す必要がある。
 120
 121 \fBgai_error\fP() 関数は要求 \fIreq\fP のステータスを返す。 要求がまだ完了していない場合は \fBEAI_INPROGRESS\fP が、
 122 要求が正常に処理された場合は 0 が、 要求を解決できなかった場合はエラーコードが返される。
 123
 124 \fBgai_cancel\fP() 関数は要求 \fIreq\fP をキャンセルする。 要求が正常にキャンセルされた場合、 要求のエラーステータスに
 125 \fBEAI_CANCELLED\fP が設定され、 通常の非同期通知が実行される。 要求が現在処理中でキャンセルできない場合もある。 この場合
 126 \fBgai_cancel\fP() が呼ばれなかったかのように処理が行われる。 \fIreq\fP が NULL の場合、
 127 そのプロセスが行ったすべての処理中の要求をキャンセルしようとする。
 128 .SH 返り値
 129 \fBgetaddrinfo_a\fP() 関数はすべての要求が正常にキューに追加されると 0 を返す。 または、以下のいずれかの 0
 130 でないエラーコードを返す。
 131 .TP
 132 \fBEAI_AGAIN\fP
 133 検索要求をキューに入れるために必要なリソースがなかった。 アプリケーションは書く要求のエラーステータスを確認し、
 134 どの要求が失敗したかを判定することができる。
 135 .TP
 136 \fBEAI_MEMORY\fP
 137 メモリーが足りない。
 138 .TP
 139 \fBEAI_SYSTEM\fP
 140 \fImode\fP が無効である。
 141 .PP
 142 \fBgai_suspend\fP() 関数はリストの要求の少なくともひとつが完了すると 0 を返す。 それ以外の場合、 以下の 0
 143 でないエラーコードのいずれかを返す。
 144 .TP
 145 \fBEAI_AGAIN\fP
 146 いずれかの要求が完了する前に指定されたタイムアウト時間が満了した。
 147 .TP
 148 \fBEAI_ALLDONE\fP
 149 指定された関数には実際には要求がなかった。
 150 .TP
 151 \fBEAI_INTR\fP
 152 シグナルが関数に割り込んだ。 この割り込みは検索要求が完了したことを示すシグナル通知により起こる場合もある。
 153 .PP
 154 \fBgai_error\fP() 関数は、 完了していない検索要求に対して \fBEAI_INPROGRESS\fP を返し、 成功で完了した検索に対して 0
 155 を返す。 \fBgetaddrinfo\fP(3) が返すエラーコードのいずれかを返す場合もある。
 156 要求の完了前に明示的に要求がキャンセルされた場合はエラーコード \fBEAI_CANCELLED\fP を返す。
 157
 158 \fBgai_cancel\fP() 関数はこれらの値のいずれかを返すことがある。
 159 .TP
 160 \fBEAI_CANCELLED\fP
 161 要求は正常にキャンセルされた。
 162 .TP
 163 \fBEAI_NOTCANCELLED\fP
 164 要求はキャンセルされていない。
 165 .TP
 166 \fBEAI_ALLDONE\fP
 167 要求はすでに完了している。
 168 .PP
 169 \fBgai_strerror\fP(3) 関数を使うと、 これらのエラーコードを、 エラーレポートに適した人間が読みやすい文字列に翻訳してくれる。
 170 .SH 準拠
 171 これらの関数は GNU 拡張である。 バージョン 2.2.3 で初めて glibc に登場した。
 172 .SH 注意
 173 \fBgetaddrinfo_a\fP() インターフェースは \fBlio_listio\fP(3) インターフェースの後にモデル化された。
 174 .SH 例
 175 ここでは二つの例を示す。 一つは複数の要求を同期処理で並行して解決する例で、 もう一つは非同期機能を使った複雑な例である。
 176 .SS 同期型の例
 177 以下のプログラムは単に複数のホスト名の解決を並行で行う。 \fBgetaddrinfo\fP(3)
 178 を使って順番にホスト名の解決を行うのに比べて速度が向上する。 このプログラムは以下のように使う。
 179 .in +4n
 180 .nf
 181
 182 $ \fB./a.out ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz\fP
 183 ftp.us.kernel.org: 128.30.2.36
 184 enoent.linuxfoundation.org: Name or service not known
 185 gnu.cz: 87.236.197.13
 186 .fi
 187 .in
 188 .PP
 189 プログラムのソースコードは以下のとおりである。
 190 .nf
 191
 192 #define _GNU_SOURCE
 193 #include <netdb.h>
 194 #include <stdio.h>
 195 #include <stdlib.h>
 196 #include <string.h>
 197
 198 int
 199 main(int argc, char *argv[])
 200 {
 201     int i, ret;
 202     struct gaicb *reqs[argc \- 1];
 203     char host[NI_MAXHOST];
 204     struct addrinfo *res;
 205
 206     if (argc < 2) {
 207         fprintf(stderr, "Usage: %s HOST...\en", argv[0]);
 208         exit(EXIT_FAILURE);
 209     }
 210
 211     for (i = 0; i < argc \- 1; i++) {
 212         reqs[i] = malloc(sizeof(*reqs[0]));
 213         if (reqs[i] == NULL) {
 214             perror("malloc");
 215             exit(EXIT_FAILURE);
 216         }
 217         memset(reqs[i], 0, sizeof(*reqs[0]));
 218         reqs[i]\->ar_name = argv[i + 1];
 219     }
 220
 221     ret = getaddrinfo_a(GAI_WAIT, reqs, argc \- 1, NULL);
 222     if (ret != 0) {
 223         fprintf(stderr, "getaddrinfo_a() failed: %s\en",
 224                 gai_strerror(ret));
 225         exit(EXIT_FAILURE);
 226     }
 227
 228     for (i = 0; i < argc \- 1; i++) {
 229         printf("%s: ", reqs[i]\->ar_name);
 230         ret = gai_error(reqs[i]);
 231         if (ret == 0) {
 232             res = reqs[i]\->ar_result;
 233
 234             ret = getnameinfo(res\->ai_addr, res\->ai_addrlen,
 235                     host, sizeof(host),
 236                     NULL, 0, NI_NUMERICHOST);
 237             if (ret != 0) {
 238                 fprintf(stderr, "getnameinfo() failed: %s\en",
 239                         gai_strerror(ret));
 240                 exit(EXIT_FAILURE);
 241             }
 242             puts(host);
 243
 244         } else {
 245             puts(gai_strerror(ret));
 246         }
 247     }
 248     exit(EXIT_SUCCESS);
 249 }
 250 .fi
 251 .SS 非同期型の例
 252 この例は \fBgetaddrinfo_a\fP() の簡単な対話式のフロントエンドである。 通知機能は使っていない。
 253 .PP
 254 セッションの実行例は以下のようになる。
 255 .in +4n
 256 .nf
 257
 258 $ \fB./a.out\fP
 259 > a ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz
 260 > c 2
 261 [2] gnu.cz: Request not canceled
 262 > w 0 1
 263 [00] ftp.us.kernel.org: Finished
 264 > l
 265 [00] ftp.us.kernel.org: 216.165.129.139
 266 [01] enoent.linuxfoundation.org: Processing request in progress
 267 [02] gnu.cz: 87.236.197.13
 268 > l
 269 [00] ftp.us.kernel.org: 216.165.129.139
 270 [01] enoent.linuxfoundation.org: Name or service not known
 271 [02] gnu.cz: 87.236.197.13
 272 .fi
 273 .in
 274 .PP
 275 プログラムのソースは以下のとおりである。
 276
 277 .nf
 278 #define _GNU_SOURCE
 279 #include <netdb.h>
 280 #include <stdio.h>
 281 #include <stdlib.h>
 282 #include <string.h>
 283
 284 static struct gaicb **reqs = NULL;
 285 static int nreqs = 0;
 286
 287 static char *
 288 getcmd(void)
 289 {
 290     static char buf[256];
 291
 292     fputs("> ", stdout); fflush(stdout);
 293     if (fgets(buf, sizeof(buf), stdin) == NULL)
 294         return NULL;
 295
 296     if (buf[strlen(buf) \- 1] == \(aq\en\(aq)
 297         buf[strlen(buf) \- 1] = 0;
 298
 299     return buf;
 300 }
 301
 302 /* Add requests for specified hostnames */
 303 static void
 304 add_requests(void)
 305 {
 306     int nreqs_base = nreqs;
 307     char *host;
 308     int ret;
 309
 310     while ((host = strtok(NULL, " "))) {
 311         nreqs++;
 312         reqs = realloc(reqs, nreqs * sizeof(reqs[0]));
 313
 314         reqs[nreqs \- 1] = calloc(1, sizeof(*reqs[0]));
 315         reqs[nreqs \- 1]\->ar_name = strdup(host);
 316     }
 317
 318     /* Queue nreqs_base..nreqs requests. */
 319
 320     ret = getaddrinfo_a(GAI_NOWAIT, &reqs[nreqs_base],
 321                         nreqs \- nreqs_base, NULL);
 322     if (ret) {
 323         fprintf(stderr, "getaddrinfo_a() failed: %s\en",
 324                 gai_strerror(ret));
 325         exit(EXIT_FAILURE);
 326     }
 327 }
 328
 329 /* Wait until at least one of specified requests completes */
 330 static void
 331 wait_requests(void)
 332 {
 333     char *id;
 334     int i, ret, n;
 335     struct gaicb const **wait_reqs = calloc(nreqs, sizeof(*wait_reqs));
 336                 /* NULL elements are ignored by gai_suspend(). */
 337
 338     while ((id = strtok(NULL, " ")) != NULL) {
 339         n = atoi(id);
 340
 341         if (n >= nreqs) {
 342             printf("Bad request number: %s\en", id);
 343             return;
 344         }
 345
 346         wait_reqs[n] = reqs[n];
 347     }
 348
 349     ret = gai_suspend(wait_reqs, nreqs, NULL);
 350     if (ret) {
 351         printf("gai_suspend(): %s\en", gai_strerror(ret));
 352         return;
 353     }
 354
 355     for (i = 0; i < nreqs; i++) {
 356         if (wait_reqs[i] == NULL)
 357             continue;
 358
 359         ret = gai_error(reqs[i]);
 360         if (ret == EAI_INPROGRESS)
 361             continue;
 362
 363         printf("[%02d] %s: %s\en", i, reqs[i]\->ar_name,
 364                ret == 0 ? "Finished" : gai_strerror(ret));
 365     }
 366 }
 367
 368 /* Cancel specified requests */
 369 static void
 370 cancel_requests(void)
 371 {
 372     char *id;
 373     int ret, n;
 374
 375     while ((id = strtok(NULL, " ")) != NULL) {
 376         n = atoi(id);
 377
 378         if (n >= nreqs) {
 379             printf("Bad request number: %s\en", id);
 380             return;
 381         }
 382
 383         ret = gai_cancel(reqs[n]);
 384         printf("[%s] %s: %s\en", id, reqs[atoi(id)]\->ar_name,
 385                gai_strerror(ret));
 386     }
 387 }
 388
 389 /* List all requests */
 390 static void
 391 list_requests(void)
 392 {
 393     int i, ret;
 394     char host[NI_MAXHOST];
 395     struct addrinfo *res;
 396
 397     for (i = 0; i < nreqs; i++) {
 398         printf("[%02d] %s: ", i, reqs[i]\->ar_name);
 399         ret = gai_error(reqs[i]);
 400
 401         if (!ret) {
 402             res = reqs[i]\->ar_result;
 403
 404             ret = getnameinfo(res\->ai_addr, res\->ai_addrlen,
 405                               host, sizeof(host),
 406                               NULL, 0, NI_NUMERICHOST);
 407             if (ret) {
 408                 fprintf(stderr, "getnameinfo() failed: %s\en",
 409                         gai_strerror(ret));
 410                 exit(EXIT_FAILURE);
 411             }
 412             puts(host);
 413         } else {
 414             puts(gai_strerror(ret));
 415         }
 416     }
 417 }
 418
 419 int
 420 main(int argc, char *argv[])
 421 {
 422     char *cmdline;
 423     char *cmd;
 424
 425     while ((cmdline = getcmd()) != NULL) {
 426         cmd = strtok(cmdline, " ");
 427
 428         if (cmd == NULL) {
 429             list_requests();
 430         } else {
 431             switch (cmd[0]) {
 432             case \(aqa\(aq:
 433                 add_requests();
 434                 break;
 435             case \(aqw\(aq:
 436                 wait_requests();
 437                 break;
 438             case \(aqc\(aq:
 439                 cancel_requests();
 440                 break;
 441             case \(aql\(aq:
 442                 list_requests();
 443                 break;
 444             default:
 445                 fprintf(stderr, "Bad command: %c\en", cmd[0]);
 446                 break;
 447             }
 448         }
 449     }
 450     exit(EXIT_SUCCESS);
 451 }
 452 .fi
 453 .SH 関連項目
 454 \fBgetaddrinfo\fP(3), \fBinet\fP(3), \fBlio_listio\fP(3), \fBhostname\fP(7), \fBip\fP(7),
 455 \fBsigevent\fP(7)
 456 .SH この文書について
 457 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.78 の一部
 458 である。プロジェクトの説明とバグ報告に関する情報は
 459 http://www.kernel.org/doc/man\-pages/ に書かれている。