日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
GETADDRINFO(3) FreeBSD ライブラリ関数マニュアル GETADDRINFO(3)
名称
getaddrinfo, freeaddrinfo -- ホストとサービス名へのソケットアドレス構造体
書式
#include <sys/types.h>
#include <sys/socket.h>
#include <netdb.h>
int
getaddrinfo(const char *hostname, const char *servname,
const struct addrinfo *hints, struct addrinfo **res);
void
freeaddrinfo(struct addrinfo *ai);
解説
getaddrinfo() 関数は、ホスト hostname とサービス servname のためにアドレ
スとポート番号のリストを取得するために使用されます。それは、
gethostbyname(3) と getservbyname(3) 関数を置換し、より多くの柔軟性を提供
します。
hostname と servname 引数は、ヌル文字で終了する文字列へのポインタか NULL
ポインタのいずれかです。hostname のための受け入れできる値は、有効なホスト
名またはドット付きの数値 IPv4 アドレス、IPv6 アドレスまたは UNIX ドメイン
アドレスから成る数値ホストアドレス文字列のいずれかです。servname は、
services(5) でリストされた 10 進数のポート番号かサービス名のいずれかで
す。少なくとも hostname と servname の 1 つは、非 NULL でなければなりませ
ん。
hints は、struct addrinfo へのオプションのポインタで、<netdb.h> で定義さ
れています:
struct addrinfo {
int ai_flags; /* 入力フラグ */
int ai_family; /* ソケットのためのアドレスファミリ */
int ai_socktype; /* ソケットタイプ */
int ai_protocol; /* ソケットのためのプロトコル */
socklen_t ai_addrlen; /* ソケットアドレスの長さ */
struct sockaddr *ai_addr; /* ソケットのためのソケットアドレス */
char *ai_canonname; /* サービス位置のための標準名 */
struct addrinfo *ai_next; /* リストの中の次のポインタ */
};
この構造体は、呼び出し側サポートか使用したいソケットのタイプに関してヒン
ト (hints) を提供するために使用することができます。呼び出し側は、hints で
次の構造体要素を供給することができます:
ai_family 使用されるべきであるアドレスファミリです。ai_family が
AF_UNSPEC に設定されるとき、呼び出し側がオペレーティングシ
ステムによってサポートされたあらゆるアドレスファミリを受け
付けることを意味します。
ai_socktype 必要とするソケットのタイプを示します: SOCK_STREAM,
SOCK_DGRAM, SOCK_SEQPACKET または SOCK_RAW です。
ai_socktype が 0 であるときに、呼び出し側は、どんなソケッ
トタイプも受け付けます。
ai_protocol IPPROTO_UDP, IPPROTO_TCP, IPPROTO_SCTP または
IPPROTO_UDPLITE の望まれている転送プロトコルを示します。
ai_protocol が 0 であるなら、呼び出し側は、どんなプロトコ
ルも受け付けます。
ai_flags hints パラメータが指す ai_flags フィールドは、0 に設定され
るか、または値 AI_ADDRCONFIG, AI_ALL, AI_CANONNAME,
AI_NUMERICHOST, AI_NUMERICSERV, AI_PASSIVE と AI_V4MAPPED
の 1 つ以上のビット単位の論理和 (OR) となります。UNIX ドメ
インアドレスに対して ai_flags は、無視されます。
AI_ADDRCONFIG AI_ADDRCONFIG ビットが設定されるなら、IPv4
アドレスは、ローカルシステムで設定される場
合のみ、返されるべきであり、IPv6 アドレス
は、IPv6 アドレスがローカルシステムで設定
される場合にだけ、返されます。
AI_ALL AI_ALL フラグが AI_V4MAPPED フラグで使用さ
れるなら、getaddrinfo() は、すべての一致す
る IPv6 と IPv4 アドレスを返します。
例えば、DNS を使用するとき、問い合わせは、
AAAA レコードと A レコードの両方のために行
われ、getaddrinfo() は、両方の問い合わせの
組み合わされた結果を返します。見つけられた
あらゆる IPv4 アドレスは、IPv4 マップされ
た IPv6 アドレスとして返されます。
AI_V4MAPPED フラグなしの AI_ALL フラグは、
無視されます。
AI_CANONNAME AI_CANONNAME ビットが設定されているなら、
getaddrinfo() への呼び出しが成功すれば、返
された最初の addrinfo 構造体の
ai_canonname 要素で指定されたホスト名の標
準の名前を含むヌル文字で終了した文字列を返
します。
AI_NUMERICHOST AI_NUMERICHOST ビットが設定されているな
ら、hostname は、IPv4 または IPv6 を定義す
る数値文字列として扱われるべきである、また
はどんな名前解決も試みられるべきでないこと
を示します。
AI_NUMERICSERV AI_NUMERICSERV ビットが設定されるなら、供
給された NULL でない servname 文字列は、数
値ポート文字列となります。そうでなければ、
EAI_NONAME エラーが返されます。このビット
は、呼び出される任意のタイプの名前解決サー
ビス (例えば、NIS+) を抑制します。
AI_PASSIVE AI_PASSIVE ビットが設定されているなら、返
されたソケットアドレス構造体は、bind(2) へ
の呼び出しで使用するためのもであることを示
します。この場合、hostname 引数が NULL ポ
インタであるなら、ソケットアドレス構造体の
IP アドレスの部分は、IPv4 アドレスのための
INADDR_ANY か IPv6 アドレスのための
IN6ADDR_ANY_INIT に設定されます。
AI_PASSIVE ビットが設定されていないなら、
返されたソケットアドレス構造体は、接続指向
のプロトコルのためには、connect(2) への呼
び出しが、コネクションレスのプロトコルが選
ばれるなら、connect(2), sendto(2), または
sendmsg(2) への呼び出しが使える状態です。
ソケットアドレス構造体の IP アドレスの部分
の hostname が NULL ポインタで AI_PASSIVE
が設定されていないなら、ループバックアドレ
スに設定されます。
AI_V4MAPPED AI_V4MAPPED フラグが AF_INET6 の ai_family
とともに指定されるなら、getaddrinfo() は、
一致している IPv6 アドレス (ai_addrlen
は、16 となります) を見つけることで、IPv4
マップされた IPv6 アドレスを返します。
例えば、DNS を使用するとき、AAAA レコード
が見つけられないなら、問い合わせは、A レ
コードのために行われ、あらゆる見つかるもの
は、IPv4 マップされた IPv6 アドレスとして
返されます。
AI_V4MAPPED フラグは、ai_family が
AF_INET6 と等しくないなら、無視されます。
hints を通して渡された addrinfo 構造体の他のすべての要素は、0 か NULL ポ
インタでなければなりません。
hints が NULL ポインタであるなら、getaddrinfo() は、まるで呼び出し側が
AF_UNSPEC に設定された ai_family と他のすべての要素が 0 または NULL に設
定された struct addrinfo を提供したかのように振る舞います。
getaddrinfo() 呼び出しが成功した後で、*res は、1 つ以上の addrinfo 構造体
のリンクリストへのポインタです。リストは、NULL ポインタが遭遇するまでそれ
ぞれの addrinfo 構造体で ai_next ポインタに従って横断することができます。
それぞれ返された addrinfo 構造体は、socket(2) への呼び出しに適している、3
つのメンバを含んでいます: ai_family, ai_socktype と ai_protocol。リストの
中の addrinfo 構造体ごとに、ai_addr メンバは、長さ ai_addrlen の書き込ま
れたソケットアドレス構造体を指します。
getaddrinfo() の、この実装は、RFC 4007 の第 11 章で文書化されているように
スコープ識別子がある数値 IPv6 アドレス記法を許します。パーセント文字とス
コープ識別子をアドレスに追加することによって、アドレスのための
sin6_scope_id フィールドを満たすことができます。これは、スコープアドレス
の管理をより簡単にして、スコープアドレスのカットアンドペースト入力を許し
ます。
現時点では、コードは、形式付きリンクローカルのアドレスだけをサポートしま
す。スコープ識別子は、リンク (ne0 のような) に関連しているハードウェアイ
ンタフェースの名前に決め打ちされます。例として、``fe80::1%ne0'' は、``ne0
インタフェースに関連するリンク上の fe80::1'' を意味します。
現在の実装は、インタフェースとリンクと 1 対 1 の関係を仮定していますが、
必ずしも仕様として本当ではありません。
すべての情報は、getaddrinfo() によって動的に割り付けられて返されます: そ
れは、ソケットアドレス構造体と同様に addrinfo 構造体自体と addrinfo 構造
体に含まれる標準のホスト名の文字列です。
getaddrinfo() への呼び出しが成功することによって作成された動的に割り付け
られた構造体に割り付けられたメモリは、freeaddrinfo() 関数によって解放され
ます。ai ポインタは、getaddrinfo() への呼び出しによって作成された
addrinfo 構造体を指すべきです。
実装に関する注
freeadrinfo(NULL) の振る舞いは、Version 4 of the Single UNIX
Specification (``SUSv4'') と RFC 3493 の両方によって特定されないままにさ
れています。現在の実装は、他のオペレーティングシステムの実装の詳細に依存
しているプログラムとの互換性のための NULL 引数を無視します。
戻り値
getaddrinfo() は、成功すれば 0 を、エラーが発生するなら gai_strerror(3)
に記載されたエラーコードの 1 つを返します。
使用例
次のコードは、ストリームソケットを通して ``www.kame.net'' サービス
``http'' に接続しようと試みます。それは、アドレスファミリにかかわらず利用
可能なすべてのアドレスを通ってループします。宛先 (終点) が IPv4 アドレス
として解決するなら、AF_INET ソケットを使用します。同様に、IPv6 として解決
するなら AF_INET6 ソケットが使用されます。特定のアドレスファミリに決めう
ちされた参照がないことに注意してください。getaddrinfo() が IPv4/v6 でない
アドレスを返しても、コードは、動作します。
struct addrinfo hints, *res, *res0;
int error;
int s;
const char *cause = NULL;
memset(&hints, 0, sizeof(hints));
hints.ai_family = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
error = getaddrinfo("www.kame.net", "http", &hints, &res0);
if (error) {
errx(1, "%s", gai_strerror(error));
/* NOTREACHED */
}
s = -1;
for (res = res0; res; res = res->ai_next) {
s = socket(res->ai_family, res->ai_socktype,
res->ai_protocol);
if (s < 0) {
cause = "socket";
continue;
}
if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
cause = "connect";
close(s);
s = -1;
continue;
}
break; /* オーケ、1 つを取得 */
}
if (s < 0) {
err(1, "%s", cause);
/* NOTREACHED */
}
freeaddrinfo(res0);
次の例は、利用可能なすべてのアドレスファミリのためにサービス ``http'' で
ワイルドカードリッスンソケットをオープンしようと試みています。
struct addrinfo hints, *res, *res0;
int error;
int s[MAXSOCK];
int nsock;
const char *cause = NULL;
memset(&hints, 0, sizeof(hints));
hints.ai_family = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_flags = AI_PASSIVE;
error = getaddrinfo(NULL, "http", &hints, &res0);
if (error) {
errx(1, "%s", gai_strerror(error));
/* NOTREACHED */
}
nsock = 0;
for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
s[nsock] = socket(res->ai_family, res->ai_socktype,
res->ai_protocol);
if (s[nsock] < 0) {
cause = "socket";
continue;
}
if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
cause = "bind";
close(s[nsock]);
continue;
}
(void) listen(s[nsock], 5);
nsock++;
}
if (nsock == 0) {
err(1, "%s", cause);
/* NOTREACHED */
}
freeaddrinfo(res0);
関連項目
bind(2), connect(2), send(2), socket(2), gai_strerror(3),
gethostbyname(3), getnameinfo(3), getservbyname(3), resolver(3), inet(4),
inet6(4), unix(4), hosts(5), resolv.conf(5), services(5), hostname(7),
named(8)
R. Gilligan, S. Thomson, J. Bound, J. McCann, and W. Stevens, Basic
Socket Interface Extensions for IPv6, RFC 3493, February 2003.
S. Deering, B. Haberman, T. Jinmei, E. Nordmark, and B. Zill, IPv6 Scoped
Address Architecture, RFC 4007, March 2005.
Craig Metz, "Protocol Independence Using the Sockets API", Proceedings of
the freenix track: 2000 USENIX annual technical conference, June 2000.
規格
getaddrinfo() 関数は、IEEE Std 1003.1-2004 (``POSIX.1'') 仕様で定義され、
RFC 3493, ``Basic Socket Interface Extensions for IPv6'' で文書化されまし
た。
FreeBSD 11.2 September 13, 2017 FreeBSD 11.2