1 .\" Copyright (c) 2009 Petr Baudis <pasky@suse.cz>
2 .\" and clean-ups and additions (C) 2010 Michael Kerrisk <mtk.manpages@gmail.com>
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.
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.
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
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .\" References: http://people.redhat.com/drepper/asynchnl.pdf,
27 .\" http://www.imperialviolet.org/2005/06/01/asynchronous-dns-lookups-with-glibc.html
29 .\"*******************************************************************
31 .\" This file was generated with po4a. Translate the source file.
33 .\"*******************************************************************
34 .TH GETADDRINFO_A 3 2014\-05\-28 GNU "Linux Programmer's Manual"
36 getaddrinfo_a, gai_suspend, gai_error, gai_cancel \- 非同期のネットワークアドレスとサービスの変換
39 \fB#define _GNU_SOURCE\fP /* feature_test_macros(7) 参照 */
40 \fB#include <netdb.h>\fP
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
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
48 \fBint gai_error(struct gaicb *\fP\fIreq\fP\fB);\fP
50 \fBint gai_cancel(struct gaicb *\fP\fIreq\fP\fB);\fP
55 \fBgetaddrinfo_a\fP() 関数は \fBgetaddrinfo\fP(3) と同じ処理を実行するが、 複数の名前検索を非同期で実行でき、
58 \fImode\fP 引き数は以下の値のいずれかを指定する。
61 検索を同期で実行する。 呼び出しは検索が完了するまで停止 (block) する。
64 検索を非同期で実行する。 呼び出しは直ちに返り、 要求はバックグラウンドで処理される。 以下の \fIsevp\fP 引き数の議論を参照。
66 配列 \fIlist\fP は処理すべき検索要求を指定する。 \fInitems\fP 引き数は \fIlist\fP の要素数を指定する。
67 要求された検索命令は並列に開始される。 \fIlist\fP の NULL 要素は無視される。 各要求は以下のように定義された \fIgaicb\fP
74 const char *ar_service;
75 const struct addrinfo *ar_request;
76 struct addrinfo *ar_result;
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) に説明がある。
87 \fImode\fP に \fBGAI_NOWAIT\fP が指定された場合、 解決した要求に関する通知を \fIsevp\fP 引き数が指す \fIsigevent\fP
88 構造体を使って受け取ることができる。 この構造体の定義と一般的な説明については \fBsigevent\fP(7) を参照。
89 \fIsevp\->sigev_notify\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 がセットされる。
101 検索が完了した際に、 \fIsigev_notify_function\fP を新しいスレッドの開始関数であるかのように起動する。 詳細は
102 \fBsigevent\fP(7) を参照。
104 \fBSIGEV_SIGNAL\fP と \fBSIGEV_THREAD\fP では、 \fIsevp\->sigev_value.sival_ptr\fP が
105 \fIlist\fP を指すようにしておくと役立つことがある。
107 \fBgai_suspend\fP() 関数は呼び出し元のスレッドの実行を中断し、 配列 \fIlist\fP 内の一つ以上の要求が完了するのを待つ。
108 \fInitems\fP 引き数は配列 \fIlist\fP の大きさを指定する。 呼び出しは以下のいずれかの状況になるまで停止する。
110 \fIlist\fP 内の一つ以上の操作が完了した。
112 呼び出しが補足されたシグナルに割り込まれた。
114 \fItimeout\fP で指定された期間が経過した。 この引き数は、秒とナノ秒でタイムアウトを指定する (\fItimespec\fP 構造体の詳細は
115 \fBnanosleep\fP(2) を参照)。 \fItimeout\fP が NULL の場合、 (上記のイベントのいずれかが発生するまで)
118 どの要求が完了したかは明示的な通知は行われない。 どの要求が完了したかを知るためには、 要求のリストに対して \fBgai_error\fP()
121 \fBgai_error\fP() 関数は要求 \fIreq\fP のステータスを返す。 要求がまだ完了していない場合は \fBEAI_INPROGRESS\fP が、
122 要求が正常に処理された場合は 0 が、 要求を解決できなかった場合はエラーコードが返される。
124 \fBgai_cancel\fP() 関数は要求 \fIreq\fP をキャンセルする。 要求が正常にキャンセルされた場合、 要求のエラーステータスに
125 \fBEAI_CANCELLED\fP が設定され、 通常の非同期通知が実行される。 要求が現在処理中でキャンセルできない場合もある。 この場合
126 \fBgai_cancel\fP() が呼ばれなかったかのように処理が行われる。 \fIreq\fP が NULL の場合、
127 そのプロセスが行ったすべての処理中の要求をキャンセルしようとする。
129 \fBgetaddrinfo_a\fP() 関数はすべての要求が正常にキューに追加されると 0 を返す。 または、以下のいずれかの 0
133 検索要求をキューに入れるために必要なリソースがなかった。 アプリケーションは書く要求のエラーステータスを確認し、
134 どの要求が失敗したかを判定することができる。
142 \fBgai_suspend\fP() 関数はリストの要求の少なくともひとつが完了すると 0 を返す。 それ以外の場合、 以下の 0
146 いずれかの要求が完了する前に指定されたタイムアウト時間が満了した。
149 指定された関数には実際には要求がなかった。
152 シグナルが関数に割り込んだ。 この割り込みは検索要求が完了したことを示すシグナル通知により起こる場合もある。
154 \fBgai_error\fP() 関数は、 完了していない検索要求に対して \fBEAI_INPROGRESS\fP を返し、 成功で完了した検索に対して 0
155 を返す。 \fBgetaddrinfo\fP(3) が返すエラーコードのいずれかを返す場合もある。
156 要求の完了前に明示的に要求がキャンセルされた場合はエラーコード \fBEAI_CANCELLED\fP を返す。
158 \fBgai_cancel\fP() 関数はこれらの値のいずれかを返すことがある。
163 \fBEAI_NOTCANCELLED\fP
169 \fBgai_strerror\fP(3) 関数を使うと、 これらのエラーコードを、 エラーレポートに適した人間が読みやすい文字列に翻訳してくれる。
171 これらの関数は GNU 拡張である。 バージョン 2.2.3 で初めて glibc に登場した。
173 \fBgetaddrinfo_a\fP() インターフェースは \fBlio_listio\fP(3) インターフェースの後にモデル化された。
175 ここでは二つの例を示す。 一つは複数の要求を同期処理で並行して解決する例で、 もう一つは非同期機能を使った複雑な例である。
177 以下のプログラムは単に複数のホスト名の解決を並行で行う。 \fBgetaddrinfo\fP(3)
178 を使って順番にホスト名の解決を行うのに比べて速度が向上する。 このプログラムは以下のように使う。
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
189 プログラムのソースコードは以下のとおりである。
199 main(int argc, char *argv[])
202 struct gaicb *reqs[argc \- 1];
203 char host[NI_MAXHOST];
204 struct addrinfo *res;
207 fprintf(stderr, "Usage: %s HOST...\en", argv[0]);
211 for (i = 0; i < argc \- 1; i++) {
212 reqs[i] = malloc(sizeof(*reqs[0]));
213 if (reqs[i] == NULL) {
217 memset(reqs[i], 0, sizeof(*reqs[0]));
218 reqs[i]\->ar_name = argv[i + 1];
221 ret = getaddrinfo_a(GAI_WAIT, reqs, argc \- 1, NULL);
223 fprintf(stderr, "getaddrinfo_a() failed: %s\en",
228 for (i = 0; i < argc \- 1; i++) {
229 printf("%s: ", reqs[i]\->ar_name);
230 ret = gai_error(reqs[i]);
232 res = reqs[i]\->ar_result;
234 ret = getnameinfo(res\->ai_addr, res\->ai_addrlen,
236 NULL, 0, NI_NUMERICHOST);
238 fprintf(stderr, "getnameinfo() failed: %s\en",
245 puts(gai_strerror(ret));
252 この例は \fBgetaddrinfo_a\fP() の簡単な対話式のフロントエンドである。 通知機能は使っていない。
259 > a ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz
261 [2] gnu.cz: Request not canceled
263 [00] ftp.us.kernel.org: Finished
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
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
284 static struct gaicb **reqs = NULL;
285 static int nreqs = 0;
290 static char buf[256];
292 fputs("> ", stdout); fflush(stdout);
293 if (fgets(buf, sizeof(buf), stdin) == NULL)
296 if (buf[strlen(buf) \- 1] == \(aq\en\(aq)
297 buf[strlen(buf) \- 1] = 0;
302 /* Add requests for specified hostnames */
306 int nreqs_base = nreqs;
310 while ((host = strtok(NULL, " "))) {
312 reqs = realloc(reqs, nreqs * sizeof(reqs[0]));
314 reqs[nreqs \- 1] = calloc(1, sizeof(*reqs[0]));
315 reqs[nreqs \- 1]\->ar_name = strdup(host);
318 /* Queue nreqs_base..nreqs requests. */
320 ret = getaddrinfo_a(GAI_NOWAIT, &reqs[nreqs_base],
321 nreqs \- nreqs_base, NULL);
323 fprintf(stderr, "getaddrinfo_a() failed: %s\en",
329 /* Wait until at least one of specified requests completes */
335 struct gaicb const **wait_reqs = calloc(nreqs, sizeof(*wait_reqs));
336 /* NULL elements are ignored by gai_suspend(). */
338 while ((id = strtok(NULL, " ")) != NULL) {
342 printf("Bad request number: %s\en", id);
346 wait_reqs[n] = reqs[n];
349 ret = gai_suspend(wait_reqs, nreqs, NULL);
351 printf("gai_suspend(): %s\en", gai_strerror(ret));
355 for (i = 0; i < nreqs; i++) {
356 if (wait_reqs[i] == NULL)
359 ret = gai_error(reqs[i]);
360 if (ret == EAI_INPROGRESS)
363 printf("[%02d] %s: %s\en", i, reqs[i]\->ar_name,
364 ret == 0 ? "Finished" : gai_strerror(ret));
368 /* Cancel specified requests */
370 cancel_requests(void)
375 while ((id = strtok(NULL, " ")) != NULL) {
379 printf("Bad request number: %s\en", id);
383 ret = gai_cancel(reqs[n]);
384 printf("[%s] %s: %s\en", id, reqs[atoi(id)]\->ar_name,
389 /* List all requests */
394 char host[NI_MAXHOST];
395 struct addrinfo *res;
397 for (i = 0; i < nreqs; i++) {
398 printf("[%02d] %s: ", i, reqs[i]\->ar_name);
399 ret = gai_error(reqs[i]);
402 res = reqs[i]\->ar_result;
404 ret = getnameinfo(res\->ai_addr, res\->ai_addrlen,
406 NULL, 0, NI_NUMERICHOST);
408 fprintf(stderr, "getnameinfo() failed: %s\en",
414 puts(gai_strerror(ret));
420 main(int argc, char *argv[])
425 while ((cmdline = getcmd()) != NULL) {
426 cmd = strtok(cmdline, " ");
445 fprintf(stderr, "Bad command: %c\en", cmd[0]);
454 \fBgetaddrinfo\fP(3), \fBinet\fP(3), \fBlio_listio\fP(3), \fBhostname\fP(7), \fBip\fP(7),
457 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.77 の一部
458 である。プロジェクトの説明とバグ報告に関する情報は
459 http://www.kernel.org/doc/man\-pages/ に書かれている。