manual/LDP_man-pages/draft/man3/getaddrinfo.3

   1 .\" Copyright (c) 2007, 2008 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" and Copyright (c) 2006 Ulrich Drepper <drepper@redhat.com>
   3 .\" A few pieces of an earlier version remain:
   4 .\" Copyright 2000, Sam Varshavchik <mrsam@courier-mta.com>
   5 .\"
   6 .\" %%%LICENSE_START(VERBATIM)
   7 .\" Permission is granted to make and distribute verbatim copies of this
   8 .\" manual provided the copyright notice and this permission notice are
   9 .\" preserved on all copies.
  10 .\"
  11 .\" Permission is granted to copy and distribute modified versions of this
  12 .\" manual under the conditions for verbatim copying, provided that the
  13 .\" entire resulting derived work is distributed under the terms of a
  14 .\" permission notice identical to this one.
  15 .\"
  16 .\" Since the Linux kernel and libraries are constantly changing, this
  17 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  18 .\" responsibility for errors or omissions, or for damages resulting from
  19 .\" the use of the information contained herein.  The author(s) may not
  20 .\" have taken the same level of care in the production of this manual,
  21 .\" which is licensed free of charge, as they might when working
  22 .\" professionally.
  23 .\"
  24 .\" Formatted or processed versions of this manual, if unaccompanied by
  25 .\" the source, must acknowledge the copyright and authors of this work.
  26 .\" %%%LICENSE_END
  27 .\"
  28 .\" References: RFC 2553
  29 .\"
  30 .\" 2005-08-09, mtk, added AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED,
  31 .\"                     and AI_NUMERICSERV.
  32 .\" 2006-11-25, Ulrich Drepper <drepper@redhat.com>
  33 .\"     Add text describing Internationalized Domain Name extensions.
  34 .\" 2007-06-08, mtk: added example programs
  35 .\" 2008-02-26, mtk; clarify discussion of NULL 'hints' argument; other
  36 .\"     minor rewrites.
  37 .\" 2008-06-18, mtk: many parts rewritten
  38 .\" 2008-12-04, Petr Baudis <pasky@suse.cz>
  39 .\"     Describe results ordering and reference /etc/gai.conf.
  40 .\"
  41 .\" FIXME . glibc's 2.9 NEWS file documents DCCP and UDP-lite support
  42 .\"           and is SCTP support now also there?
  43 .\"
  44 .\"*******************************************************************
  45 .\"
  46 .\" This file was generated with po4a. Translate the source file.
  47 .\"
  48 .\"*******************************************************************
  49 .\"
  50 .\" Japanese Version Copyright (c) 2001 NAKANO Takeo all rights reserved.
  51 .\" Translated Sun Jan 14 2001 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
  52 .\" Updated 2005-10-09 by Kentaro Shirakata <argrath@ub32.org>
  53 .\" Updated 2007-01-01 by Kentaro Shirakata <argrath@ub32.org>
  54 .\" Updated 2007-06-13, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.55
  55 .\" Updated 2008-04-04, Akihiro MOTOKI, LDP v2.79
  56 .\" Updated 2008-08-11, Akihiro MOTOKI, LDP v3.05
  57 .\" Updated 2008-11-09, Akihiro MOTOKI, LDP v3.13
  58 .\" Updated 2008-12-26, Akihiro MOTOKI, LDP v3.15
  59 .\" Updated 2010-04-18, Akihiro MOTOKI, LDP v3.24
  60 .\" Updated 2012-04-30, Akihiro MOTOKI <amotoki@gmail.com>
  61 .\" Updated 2012-05-29, Akihiro MOTOKI <amotoki@gmail.com>
  62 .\" Updated 2013-05-01, Akihiro MOTOKI <amotoki@gmail.com>
  63 .\"
  64 .TH GETADDRINFO 3 2020\-11\-01 GNU "Linux Programmer's Manual"
  65 .SH 名前
  66 getaddrinfo, freeaddrinfo, gai_strerror \- ネットワークのアドレスとサービスを変換する
  67 .SH 書式
  68 .nf
  69 \fB#include <sys/types.h>\fP
  70 \fB#include <sys/socket.h>\fP
  71 \fB#include <netdb.h>\fP
  72 .PP
  73 \fBint getaddrinfo(const char *\fP\fInode\fP\fB, const char *\fP\fIservice\fP\fB,\fP
  74 \fB                const struct addrinfo *\fP\fIhints\fP\fB,\fP
  75 \fB                struct addrinfo **\fP\fIres\fP\fB);\fP
  76 .PP
  77 \fBvoid freeaddrinfo(struct addrinfo *\fP\fIres\fP\fB);\fP
  78 .PP
  79 \fBconst char *gai_strerror(int \fP\fIerrcode\fP\fB);\fP
  80 .fi
  81 .PP
  82 .RS -4
  83 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  84 .ad l
  85 .RE
  86 .PP
  87 \fBgetaddrinfo\fP(),
  88 \fBfreeaddrinfo\fP(),
  89 \fBgai_strerror\fP():
  90     Since glibc 2.22: _POSIX_C_SOURCE >= 200112L
  91     Glibc 2.21 and earlier: _POSIX_C_SOURCE
  92 .ad b
  93 .SH 説明
  94 .\" .BR getipnodebyname (3),
  95 .\" .BR getipnodebyaddr (3),
  96 \fBgetaddrinfo\fP()  は、(インターネットのホストとサービスを識別する)  \fInode\fP と \fIservice\fP を渡すと、一つ以上の
  97 \fIaddrinfo\fP 構造体を返す。それぞれの \fIaddrinfo\fP 構造体には、 \fBbind\fP(2)  や \fBconnect\fP(2)
  98 を呼び出す際に指定できるインターネットアドレスが格納されている。 \fBgetaddrinfo\fP()  関数は、 \fBgethostbyname\fP(3)
  99 と \fBgetservbyname\fP(3) の機能をまとめて一つのインターフェースにしたものであるが、 これらの関数と違い、
 100 \fBgetaddrinfo\fP() はリエントラントであり、 \fBgetaddrinfo\fP() を使うことでプログラムは IPv4 と IPv6
 101 の違いに関する依存関係を なくすことができる。
 102 .PP
 103 \fBgetaddrinfo\fP()  が用いる \fIaddrinfo\fP 構造体は以下のフィールドを含む。
 104 .PP
 105 .in +4n
 106 .EX
 107 struct addrinfo {
 108     int              ai_flags;
 109     int              ai_family;
 110     int              ai_socktype;
 111     int              ai_protocol;
 112     socklen_t        ai_addrlen;
 113     struct sockaddr *ai_addr;
 114     char            *ai_canonname;
 115     struct addrinfo *ai_next;
 116 };
 117 .EE
 118 .in
 119 .PP
 120 \fIhints\fP 引数は \fIaddrinfo\fP 構造体を指し示し、この構造体を用いて \fIres\fP
 121 が指すリストに入れて返すソケットアドレス構造体を選択するための基準を指定する。 \fIhints\fP が NULL でない場合、 \fIhints\fP は
 122 \fIaddrinfo\fP 構造体を指し示し、その構造体のフィールド \fIai_family\fP, \fIai_socktype\fP,
 123 \fIai_protocol\fP で \fBgetaddrinfo\fP()  が返すソケットアドレス集合に対する基準を指定する。
 124 .TP
 125 \fIai_family\fP
 126 このフィールドは返されるアドレスの希望のアドレスファミリーを指定する。 このフィールドに指定できる有効な値としては \fBAF_INET\fP と
 127 \fBAF_INET6\fP がある。 また、値 \fBAF_UNSPEC\fP を指定すると、 \fBgetaddrinfo\fP()  は \fInode\fP と
 128 \fIservice\fP で使用できるいずれかのアドレスファミリー (例えば IPv4 か IPv6) の ソケットアドレスを返すことを求められる。
 129 .TP
 130 \fIai_socktype\fP
 131 このフィールドは推奨のソケット型 (例えば \fBSOCK_STREAM\fP や \fBSOCK_DGRAM\fP)  を指定する。 このフィールドに 0
 132 を指定すると、任意のソケット型のソケットアドレスを \fBgetaddrinfo\fP()  が返してよいことを意味する。
 133 .TP
 134 \fIai_protocol\fP
 135 このフィールドは返されるソケットアドレスのプロトコルを指定する。 このフィールドに 0 を指定すると、任意のプロトコルののソケットアドレスを
 136 \fBgetaddrinfo\fP()  が返してよいことを意味する。
 137 .TP
 138 \fIai_flags\fP
 139 このフィールドは、追加のオプション (下記) を指定する。 複数のフラグを指定する際には、それらのビット単位の OR をとって指定する。
 140 .PP
 141 \fIhints\fP が指し示す構造体の他のすべてのフィールドには 0 かヌルポインターを適切に入れなければならない。
 142 .PP
 143 \fIhints\fP に NULL を指定するのは、 \fIai_socktype\fP と \fIai_protocol\fP に 0 を、 \fIai_family\fP
 144 に \fBAF_UNSPEC\fP を、 \fIai_flags\fP に \fB(AI_V4MAPPED\ |\ AI_ADDRCONFIG)\fP
 145 を設定するのと等価である (POSIX では \fIai_flags\fP には別のデフォルト値が規定されている; 「備考」を参照)。 \fInode\fP
 146 には、数値形式のネットワークアドレス (IPv4 の場合は \fBinet_aton\fP(3)  でサポートされているドット区切りの数字による表記、
 147 IPv6 の場合は \fBinet_pton\fP(3)  でサポートされている 16 進数の文字列形式) もしくは ネットワークホスト名を指定する。
 148 ネットワークホスト名を指定した場合には、そのネットワークアドレスが検索され、 名前解決が行なわれる。 \fIhints.ai_flags\fP に
 149 \fBAI_NUMERICHOST\fP フラグが含まれている場合は、 \fInode\fP は数値形式のネットワークアドレスでなければならない。
 150 \fBAI_NUMERICHOST\fP フラグを使うと、時間の掛かる可能性のあるネットワークホストアドレスの検索は すべて抑制される。
 151 .PP
 152 \fIhints.ai_flags\fP に \fBAI_PASSIVE\fP フラグが指定され、かつ \fInode\fP が NULL の場合、
 153 返されるソケットアドレスは コネクションを \fBaccept\fP(2)  するためのソケットを \fBbind\fP(2)  するのに適したものとなる。
 154 返されるソケットアドレスには「ワイルドカードアドレス」 (IPv4 アドレスの場合は \fBINADDR_ANY\fP、 IPv6 アドレスの場合は
 155 \fBIN6ADDR_ANY_INIT\fP)  が入る。 ワイルドカードアドレスは、任意のホストのネットワークアドレスで接続を
 156 受け付けようとするアプリケーション (通常はサーバー) で用いられる。 \fInode\fP が NULL でない場合、 \fBAI_PASSIVE\fP
 157 フラグは無視される。
 158 .PP
 159 \fIhints.ai_flags\fP に \fBAI_PASSIVE\fP フラグがセットされていない場合、 返されるソケットアドレスは
 160 \fBconnect\fP(2), \fBsendto\fP(2), \fBsendmsg\fP(2)  での使用に適したものとなる。 \fInode\fP が NULL
 161 の場合、ネットワークアドレスにはループバックインターフェイスの アドレス (IPv4 アドレスの場合は \fBINADDR_LOOPBACK\fP IPv6
 162 アドレスの場合は \fBIN6ADDR_LOOPBACK_INIT\fP)\fBが設定される。\fP これは同じホスト上で動作している接続相手と通信するような
 163 アプリケーションで用いられる。
 164 .PP
 165 \fIservice\fP により、返される各アドレス構造体のポート番号が決まる。 この引数がサービス名 (\fBservices\fP(5)  参照)
 166 の場合、対応するポート番号に翻訳される。 この引数には 10 進数も指定することができ、 この場合にはバイナリへの変換だけが行われる。
 167 \fIservice\fP が NULL の場合、返されるソケットアドレスのポート番号は 初期化されないままとなる。 \fIhints.ai_flags\fP に
 168 \fBAI_NUMERICSERV\fP が指定され、かつ \fIservice\fP が NULL でない場合、 \fIservice\fP
 169 は数値のポート番号を含む文字列を指し示さなければならない。 このフラグは、名前解決サービスが不要であることが分かっている場合に、
 170 サービスの起動を抑制するために用いられる。
 171 .PP
 172 \fInode\fP と \fIservice\fP のどちらかは NULL にしてよいが、両方同時に NULL にしてはならない。
 173 .PP
 174 \fBgetaddrinfo\fP()  関数は、 \fIaddrinfo\fP 構造体のメモリー確保を行い、 \fIaddrinfo\fP
 175 構造体のリンクリストを初期化し、 \fIres\fP にリストの先頭へのポインターを入れて返す。 このとき、各構造体のネットワークアドレスは \fInode\fP
 176 と \fIservice\fP に一致し、 \fIhints\fP で課されたすべての制限を満たすものとなる。 リンクリストの要素は \fIai_next\fP
 177 フィールドにより連結される。
 178 .PP
 179 リンクリストの \fIaddrinfo\fP 構造体は複数個になることもあり、その理由はいくつかある。 ネットワークホストがマルチホームである、
 180 複数のプロトコルでアクセスできる (例えば \fBAF_INET\fP と \fBAF_INET6\fP の両方) 、 複数のソケット種別で同じサービスが利用できる
 181 (例えば、ひとつが \fBSOCK_STREM\fP アドレスで、もうひとつが \fBSOCK_DGRAM\fP アドレスである)、がある。
 182 通常は、アプリケーションは返された順序でアドレスを試すべきである。 \fBgetaddrinfo\fP()  の中で使用される並べ替え関数は RFC\ 3484 で定義されている。 特殊なシステムでは、 \fI/etc/gai.conf\fP を編集することで、この順序を微調整することができる
 183 (\fI/etc/gai.conf\fP は glibc 2.5 以降で利用できる)。
 184 .PP
 185 .\" In glibc prior to 2.3.4, the ai_canonname of each addrinfo
 186 .\" structure was set pointing to the canonical name; that was
 187 .\" more than POSIX.1-2001 specified, or other implementations provided.
 188 .\" MTK, Aug 05
 189 \fIhints.ai_flags\fP に \fBAI_CANONNAME\fP フラグが含まれている場合、返されるリストの最初の \fIaddrinfo\fP
 190 構造体の \fIai_canonname\fP フィールドはホストの公式な名前を指すように設定される。
 191 .PP
 192 返される各々の \fIaddrinfo\fP 構造体の残りのフィールドは以下のように初期化される。
 193 .IP * 2
 194 \fIai_family\fP, \fIai_socktype\fP, \fIai_protocol\fP フィールドはソケット生成パラメーターを返す
 195 (これらのフィールドの意味は \fBsocket\fP(2)  の同じ名前の引数と同じである)。 例えば、 \fIai_family\fP は \fBAF_INET\fP
 196 や \fBAF_INET6\fP を返し、 \fIai_socktype\fP は \fBSOCK_DGRAM\fP や \fBSOCK_STREAM\fP を返し、
 197 \fIai_protocol\fP はそのソケットのプロトコルを返す。
 198 .IP *
 199 \fIai_addr\fP フィールドにはソケットアドレスへのポインターが書き込まれ、 \fIai_addrlen\fP
 200 フィールドにはソケットアドレスの長さがバイト単位で書き込まれる。
 201 .PP
 202 \fIhints.ai_flags\fP が \fBAI_ADDRCONFIG\fP を含む場合、 \fIres\fP が指すリストには、ローカルシステムに最低一つの
 203 IPv4 アドレスが設定されている場合のみ IPv4 アドレスが返され、 ローカルシステムに最低一つの IPv6 アドレスが設定されている場合にのみ
 204 IPv6 アドレスが返される。 なお、この場合には、ループバックアドレスは有効に設定されたアドレスとはみなされない。 このフラグは、例えば、IPv4
 205 だけのシステムで、 \fBgetaddrinfo\fP() が必ず IPv6 ソケットアドレスを返さないことを保証するのに役立つ。 IPv4
 206 だけのシステムでは、IPv6 アドレスは \fBconnect\fP(2) や \fBbind\fP(2) で必ず失敗することになる。
 207 .PP
 208 \fIhints.ai_flags\fP に \fBAI_V4MAPPED\fP が指定されていて、 \fIhints.ai_family\fP に
 209 \fBAF_INET6\fP が指定され、 マッチする IPv6 アドレスが見つからなかった場合、 \fIres\fP が指すリストには IPv4\-mapped
 210 IPv6 アドレスが返される。 \fIhints.ai_flags\fP に \fBAI_V4MAPPED\fP と \fBAI_ALL\fP
 211 の両方が指定されている場合、 \fIres\fP が指すリストには IPv6 アドレスと IPv4\-mapped IPv6 アドレスの 両方が返される。
 212 \fBAI_V4MAPPED\fP が指定されていない場合、 \fBAI_ALL\fP は無視される。
 213 .PP
 214 \fBfreeaddrinfo\fP()  関数は、 リンクリスト \fIres\fP に対して動的に割り当てられたメモリーを解放する。
 215 .SS "国際化ドメイン名のための getaddrinfo() の拡張"
 216 glibc 2.3.4 から、 \fBgetaddrinfo\fP()  は入出力するホスト名を透過的に国際化ドメイン名 (IDN) 形式 (RFC 3490
 217 の \fIInternationalizing Domain Names in Applications (IDNA)\fP を参照のこと)
 218 と変換することを選択的に認めるように拡張されている。 4 つの新しいフラグが定義されている:
 219 .TP
 220 \fBAI_IDN\fP
 221 このフラグが指定されると、 \fInode\fP で与えられたノード名は必要があれば IDN 形式に変換される。
 222 ソース符号化形式は現在のロケールのものである。
 223 .IP
 224 .\" Implementation Detail:
 225 .\" To minimize effects on system performance the implementation might
 226 .\" want to check whether the input string contains any non-ASCII
 227 .\" characters.  If there are none the IDN step can be skipped completely.
 228 .\" On systems which allow not-ASCII safe encodings for a locale this
 229 .\" might be a problem.
 230 入力名に非 ASCII 文字が含まれている場合、 IDN 符号化形式が使われる。 非 ASCII
 231 文字が含まれている(ピリオドで区切られる)部分ノード名は、 名前解決機能に渡される前に ASCII 互換符号化形式 (ACE) を使って 符号化される。
 232 .TP
 233 \fBAI_CANONIDN\fP
 234 \fBAI_CANONNAME\fP が指定されている場合、 \fBgetaddrinfo\fP()  は名前の検索に成功した後、 返された \fIaddrinfo\fP
 235 構造体に対応するノードの正規名を返す。 返り値は名前解決機能から返された値の正確なコピーである。
 236 .IP
 237 .\"
 238 .\"Implementation Detail:
 239 .\"If no component of the returned name starts with xn\-\- the IDN
 240 .\"step can be skipped, therefore avoiding unnecessary slowdowns.
 241 \fBAI_CANONIDN\fP 名前が ACE で符号化されている場合、一つまたは複数の名前の構成要素の先頭に \fIxn\-\-\fP を含んでいる。
 242 これらの構成要素を読み込み可能な形に変換するために、 \fBAI_CANONNAME\fP と共に \fBAI_CANONIDN\fP フラグを渡すことも出来る。
 243 返される文字列は現在のロケールの符号化形式で符号化されている。
 244 .TP
 245 \fBAI_IDN_ALLOW_UNASSIGNED\fP, \fBAI_IDN_USE_STD3_ASCII_RULES\fP
 246 これらのフラグをセットすると、IDNA 処理で使用されるフラグ IDNA_ALLOW_UNASSIGNED (未割り当ての Unicode
 247 のコードポイントを許容) と IDNA_USE_STD3_ASCII_RULES (出力が STD3 準拠のホスト名かをチェックする)
 248 がそれぞれ有効になる。
 249 .SH 返り値
 250 .\" FIXME glibc defines the following additional errors, some which
 251 .\" can probably be returned by getaddrinfo(); they need to
 252 .\" be documented.
 253 .\"    #ifdef __USE_GNU
 254 .\"    #define EAI_INPROGRESS  -100  /* Processing request in progress.  */
 255 .\"    #define EAI_CANCELED    -101  /* Request canceled.  */
 256 .\"    #define EAI_NOTCANCELED -102  /* Request not canceled.  */
 257 .\"    #define EAI_ALLDONE     -103  /* All requests done.  */
 258 .\"    #define EAI_INTR        -104  /* Interrupted by a signal.  */
 259 .\"    #define EAI_IDN_ENCODE  -105  /* IDN encoding failed.  */
 260 .\"    #endif
 261 \fBgetaddrinfo\fP()  は成功すると 0 を返し、失敗すると以下の非 0 のエラーコードのいずれかを返す。
 262 .TP
 263 \fBEAI_ADDRFAMILY\fP
 264 .\" Not in SUSv3
 265 指定されたネットワークホストには、 要求されたアドレスファミリーのネットワークアドレスがない。
 266 .TP
 267 \fBEAI_AGAIN\fP
 268 ネームサーバーから一時的な失敗 (temporary failure)  を意味する返事が返された。後でもう一度試してみよ。
 269 .TP
 270 \fBEAI_BADFLAGS\fP
 271 \fIhints.ai_flags\fP のフラグに不正なフラグが含まれている。または、 \fIhints.ai_flags\fP に
 272 \fBAI_CANONNAME\fP が含まれていて、かつ \fIname\fP が NULL であった。
 273 .TP
 274 \fBEAI_FAIL\fP
 275 ネームサーバーから恒久的な失敗 (permanent failure)  を意味する返事が返された。
 276 .TP
 277 \fBEAI_FAMILY\fP
 278 要求されたアドレスファミリーがサポートされていない。
 279 .TP
 280 \fBEAI_MEMORY\fP
 281 メモリーが足りない。
 282 .TP
 283 \fBEAI_NODATA\fP
 284 .\" Not in SUSv3
 285 指定されたネットワークホストは存在するが、 ネットワークアドレスがひとつも定義されていない。
 286 .TP
 287 \fBEAI_NONAME\fP
 288 \fInode\fP と \fIservice\fP のどちらかが不明、または \fInode\fP と \fIservice\fP の両方が NULL だった場合、または
 289 \fBAI_NUMERICSERV\fP が \fIhints.ai_flags\fP に指定されていて、 \fIhints.ai_flags\fP と
 290 \fIservice\fP が数値のポート番号の文字列でない。
 291 .TP
 292 \fBEAI_SERVICE\fP
 293 要求されたサービスは、要求されたソケットタイプでは利用できない。 他のソケットタイプでなら利用可能かもしれない。 このエラーが発生する例としては、
 294 \fIservice\fP が "shell" (ストリームソケットでのみ利用できるサービス) で、 \fIhints.ai_protocol\fP に
 295 \fBIPPROTO_UDP\fP が指定されたり、 \fIhints.ai_socktype\fP に \fBSOCK_DGRAM\fP が指定されたりした場合がある。
 296 また、 \fIservice\fP が NULL 以外で、 \fIhints.ai_socktype\fP に \fBSOCK_RAW\fP
 297 (サービスの考え方をサポートしていないソケット種別)  が指定された場合にも、このエラーが発生する。
 298 .TP
 299 \fBEAI_SOCKTYPE\fP
 300 要求されたソケットタイプがサポートされていない。 このエラーが発生する例としては、 \fIhints.ai_socktype\fP と
 301 \fIhints.ai_protocol\fP が矛盾している場合 (例えば \fIhints.ai_socktype\fP が \fBSOCK_DGRAM\fP で
 302 \fIhints.ai_protocol\fP が \fBIPPROTO_TCP\fP)  がある。
 303 .TP
 304 \fBEAI_SYSTEM\fP
 305 その他のシステムエラー。詳しくは \fIerrno\fP を調べること。
 306 .PP
 307 \fBgai_strerror\fP()  関数を用いると、これらのエラーコードを人間に可読な文字列に変換できるので、 エラー報告に適するだろう。
 308 .SH ファイル
 309 \fI/etc/gai.conf\fP
 310 .SH 属性
 311 この節で使用されている用語の説明は \fBattributes\fP(7) を参照のこと。
 312 .TS
 313 allbox;
 314 lbw15 lb lb
 315 l l l.
 316 Interface       Attribute       Value
 317 T{
 318 \fBgetaddrinfo\fP()
 319 T}      Thread safety   MT\-Safe env locale
 320 T{
 321 \fBfreeaddrinfo\fP(),
 322 \fBgai_strerror\fP()
 323 T}      Thread safety   MT\-Safe
 324 .TE
 325 .sp 1
 326 .SH 準拠
 327 POSIX.1\-2001, POSIX.1\-2008.  \fBgetaddrinfo\fP()  関数は RFC 2553 に記載されている。
 328 .SH 注意
 329 \fBgetaddrinfo\fP()  は、IPv6 scope\-ID を指定するために \fIaddress\fP\fB%\fP\fIscope\-id\fP
 330 記法をサポートしている。
 331 .PP
 332 \fBAI_ADDRCONFIG\fP, \fBAI_ALL\fP, \fBAI_V4MAPPED\fP は glibc 2.3.3 以降で利用可能である。
 333 \fBAI_NUMERICSERV\fP は glibc 2.3.4 以降で利用可能である。
 334 .PP
 335 .\" POSIX.1-2001, POSIX.1-2008
 336 POSIX.1 によると、 \fIhints\fP に NULL が指定された場合、 \fIai_flags\fP を 0 とみなすべきとされている。 GNU C
 337 ライブラリでは、この場合に、代わりに \fIai_flags\fP を \fB(AI_V4MAPPED\ |\ AI_ADDRCONFIG)\fP
 338 とみなすようになっている。 この値の方が標準規格の改善になると考えられているからである。
 339 .SH 例
 340 .\" getnameinfo.3 refers to this example
 341 .\" socket.2 refers to this example
 342 .\" bind.2 refers to this example
 343 .\" connect.2 refers to this example
 344 .\" recvfrom.2 refers to this example
 345 .\" sendto.2 refers to this example
 346 以下のプログラムは、 \fBgetaddrinfo\fP(), \fBgai_strerror\fP(), \fBfreeaddrinfo\fP(),
 347 \fBgetnameinfo\fP(3)  の使い方を示したものである。 プログラムは UDP データグラムの echo サーバとクライアントである。
 348 .SS サーバのプログラム
 349 \&
 350 .EX
 351 #include <sys/types.h>
 352 #include <stdio.h>
 353 #include <stdlib.h>
 354 #include <unistd.h>
 355 #include <string.h>
 356 #include <sys/socket.h>
 357 #include <netdb.h>
 358
 359 #define BUF_SIZE 500
 360
 361 int
 362 main(int argc, char *argv[])
 363 {
 364     struct addrinfo hints;
 365     struct addrinfo *result, *rp;
 366     int sfd, s;
 367     struct sockaddr_storage peer_addr;
 368     socklen_t peer_addr_len;
 369     ssize_t nread;
 370     char buf[BUF_SIZE];
 371
 372     if (argc != 2) {
 373         fprintf(stderr, "Usage: %s port\en", argv[0]);
 374         exit(EXIT_FAILURE);
 375     }
 376
 377     memset(&hints, 0, sizeof(hints));
 378     hints.ai_family = AF_UNSPEC;    /* Allow IPv4 or IPv6 */
 379     hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
 380     hints.ai_flags = AI_PASSIVE;    /* For wildcard IP address */
 381     hints.ai_protocol = 0;          /* Any protocol */
 382     hints.ai_canonname = NULL;
 383     hints.ai_addr = NULL;
 384     hints.ai_next = NULL;
 385
 386     s = getaddrinfo(NULL, argv[1], &hints, &result);
 387     if (s != 0) {
 388         fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s));
 389         exit(EXIT_FAILURE);
 390     }
 391
 392     /* getaddrinfo() returns a list of address structures.
 393        Try each address until we successfully bind(2).
 394        If socket(2) (or bind(2)) fails, we (close the socket
 395        and) try the next address. */
 396
 397     for (rp = result; rp != NULL; rp = rp\->ai_next) {
 398         sfd = socket(rp\->ai_family, rp\->ai_socktype,
 399                 rp\->ai_protocol);
 400         if (sfd == \-1)
 401             continue;
 402
 403         if (bind(sfd, rp\->ai_addr, rp\->ai_addrlen) == 0)
 404             break;                  /* Success */
 405
 406         close(sfd);
 407     }
 408
 409     freeaddrinfo(result);           /* No longer needed */
 410
 411     if (rp == NULL) {               /* No address succeeded */
 412         fprintf(stderr, "Could not bind\en");
 413         exit(EXIT_FAILURE);
 414     }
 415
 416     /* Read datagrams and echo them back to sender */
 417
 418     for (;;) {
 419         peer_addr_len = sizeof(peer_addr);
 420         nread = recvfrom(sfd, buf, BUF_SIZE, 0,
 421                 (struct sockaddr *) &peer_addr, &peer_addr_len);
 422         if (nread == \-1)
 423             continue;               /* Ignore failed request */
 424
 425         char host[NI_MAXHOST], service[NI_MAXSERV];
 426
 427         s = getnameinfo((struct sockaddr *) &peer_addr,
 428                         peer_addr_len, host, NI_MAXHOST,
 429                         service, NI_MAXSERV, NI_NUMERICSERV);
 430         if (s == 0)
 431             printf("Received %zd bytes from %s:%s\en",
 432                     nread, host, service);
 433         else
 434             fprintf(stderr, "getnameinfo: %s\en", gai_strerror(s));
 435
 436         if (sendto(sfd, buf, nread, 0,
 437                     (struct sockaddr *) &peer_addr,
 438                     peer_addr_len) != nread)
 439             fprintf(stderr, "Error sending response\en");
 440     }
 441 }
 442 .EE
 443 .SS クライアントのプログラム
 444 \&
 445 .EX
 446 #include <sys/types.h>
 447 #include <sys/socket.h>
 448 #include <netdb.h>
 449 #include <stdio.h>
 450 #include <stdlib.h>
 451 #include <unistd.h>
 452 #include <string.h>
 453
 454 #define BUF_SIZE 500
 455
 456 int
 457 main(int argc, char *argv[])
 458 {
 459     struct addrinfo hints;
 460     struct addrinfo *result, *rp;
 461     int sfd, s;
 462     size_t len;
 463     ssize_t nread;
 464     char buf[BUF_SIZE];
 465
 466     if (argc < 3) {
 467         fprintf(stderr, "Usage: %s host port msg...\en", argv[0]);
 468         exit(EXIT_FAILURE);
 469     }
 470
 471     /* Obtain address(es) matching host/port */
 472
 473     memset(&hints, 0, sizeof(hints));
 474     hints.ai_family = AF_UNSPEC;    /* Allow IPv4 or IPv6 */
 475     hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
 476     hints.ai_flags = 0;
 477     hints.ai_protocol = 0;          /* Any protocol */
 478
 479     s = getaddrinfo(argv[1], argv[2], &hints, &result);
 480     if (s != 0) {
 481         fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s));
 482         exit(EXIT_FAILURE);
 483     }
 484
 485     /* getaddrinfo() returns a list of address structures.
 486        Try each address until we successfully connect(2).
 487        If socket(2) (or connect(2)) fails, we (close the socket
 488        and) try the next address. */
 489
 490     for (rp = result; rp != NULL; rp = rp\->ai_next) {
 491         sfd = socket(rp\->ai_family, rp\->ai_socktype,
 492                      rp\->ai_protocol);
 493         if (sfd == \-1)
 494             continue;
 495
 496         if (connect(sfd, rp\->ai_addr, rp\->ai_addrlen) != \-1)
 497             break;                  /* Success */
 498
 499         close(sfd);
 500     }
 501
 502     freeaddrinfo(result);           /* No longer needed */
 503
 504     if (rp == NULL) {               /* No address succeeded */
 505         fprintf(stderr, "Could not connect\en");
 506         exit(EXIT_FAILURE);
 507     }
 508
 509     /* Send remaining command\-line arguments as separate
 510        datagrams, and read responses from server */
 511
 512     for (int j = 3; j < argc; j++) {
 513         len = strlen(argv[j]) + 1;
 514                 /* +1 for terminating null byte */
 515
 516         if (len > BUF_SIZE) {
 517             fprintf(stderr,
 518                     "Ignoring long message in argument %d\en", j);
 519             continue;
 520         }
 521
 522         if (write(sfd, argv[j], len) != len) {
 523             fprintf(stderr, "partial/failed write\en");
 524             exit(EXIT_FAILURE);
 525         }
 526
 527         nread = read(sfd, buf, BUF_SIZE);
 528         if (nread == \-1) {
 529             perror("read");
 530             exit(EXIT_FAILURE);
 531         }
 532
 533         printf("Received %zd bytes: %s\en", nread, buf);
 534     }
 535
 536     exit(EXIT_SUCCESS);
 537 }
 538 .EE
 539 .SH 関連項目
 540 .\" .BR getipnodebyaddr (3),
 541 .\" .BR getipnodebyname (3),
 542 \fBgetaddrinfo_a\fP(3), \fBgethostbyname\fP(3), \fBgetnameinfo\fP(3), \fBinet\fP(3),
 543 \fBgai.conf\fP(5), \fBhostname\fP(7), \fBip\fP(7)
 544 .SH この文書について
 545 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
 546 \%https://www.kernel.org/doc/man\-pages/ に書かれている。