getaddrinfo サブルーチン

目的

プロトコルに依存しないホスト名からアドレスへの変換。

ライブラリー

ライブラリー (libc.a)

構文

#include <sys/socket.h>
#include <netdb.h>
int getaddrinfo (hostname, servname, hints, res)
const char *hostname;
const char *servname;
const struct addrinfo *hints;
struct addrinfo **res;

説明

hostname および servname パラメーターは、参照されるホスト名またはサービス名 (あるいはその両方) を記述します。 ゼロまたはこれらの引数の 1 つが NULL である可能性があります。 NULL 以外のホスト名は、ホスト名または数値のホスト・アドレス・ストリング ( IPv4 の場合は小数点付き 10 進数、 IPv6の場合は 16 進数) のいずれかです。 NULL 以外の servname は、サービス名または 10 進数のポート番号のいずれかです。

hints パラメーターは、必要な戻り情報に関するヒントを指定します。 hostname および servname パラメーターは、ヌル終了ストリングまたは NULL を指すポインターです。 これらの引数の一方または両方が NULL 以外のポインターでなければなりません。 通常のクライアント・シナリオでは、 hostname パラメーターと servname パラメーターの両方が指定されます。 通常のサーバー・シナリオでは、 servname パラメーターのみが指定されます。 NULL 以外のホスト名ストリングは、ホスト名または数値のホスト・アドレス・ストリング (例えば、小数点付き 10 進数の IPv4 アドレスまたは IPv6 16 進アドレス) のいずれかにすることができます。 NULL 以外の servname ストリングは、サービス名または 10 進数のポート番号のいずれかにすることができます。

呼び出し元は、オプションで、 hints パラメーターによって指し示される addrinfo 構造体を渡して、呼び出し元がサポートするソケットのタイプに関するヒントを提供することができます。 この hints 構造体では、 ai_flags、 ai_eflags ai_family、 ai_socktype以外のすべてのメンバー また、 ai_protocol はゼロまたは NULL ポインターでなければなりません。 ai_family の PF_UNSPEC の値は、呼び出し元が任意のプロトコル・ファミリーを受け入れることを意味します。 ai_socktype の値がゼロの場合、呼び出し元は任意のソケット・タイプを受け入れます。 ai_protocol の値がゼロの場合、呼び出し元は任意のプロトコルを受け入れます。 例えば、呼び出し元が TCP のみを処理し、UDP は処理しない場合、 getaddrinfo サブルーチンを呼び出すときに、 hints 構造体の ai_socktype メンバーを SOCK_STREAM に設定する必要があります。 呼び出し側が IPv4 のみを処理し、 IPv6を処理しない場合は、 getaddrinfo を呼び出すときに、 hints 構造体の ai_family メンバーを PF_INET に設定する必要があります。 getaddrinfo の hints パラメーターが NULL ポインターの場合、これは、呼び出し元が ai_family を PF_UNSPEC に設定してゼロに初期化された addrinfo 構造体を埋める場合と同じです。

正常に戻ると、1 つ以上の addrinfo 構造体のリンク・リストへのポインターが res パラメーターを介して戻されます。 呼び出し側は、NULL ポインターが検出されるまで、 ai_next ポインターに従って、このリスト内の各 addrinfo 構造体を処理することができます。 返された各 addrinfo 構造で、3 つのメンバー ai_family、 ai_socktype、 および ai_protocol は、 socket サブルーチンへの呼び出しに対応する引数です。 各 addrinfo 構造体において、 ai_addr メンバーは、 ai_addrlen メンバーによって長さが指定されている埋め込みソケット・アドレス構造体を指します。

AI_PASSIVE ビットが hints 構造体の ai_flags メンバーに設定されている場合、呼び出し元は、 bind サブルーチンへの呼び出しで、戻されたソケット・アドレス構造体を使用することを計画します。 hostname パラメーターが NULL ポインターの場合、ソケット・アドレス構造体の IP アドレス部分は、 IPv4 アドレスの場合は INADDR_ANY に、 IPv6 アドレスの場合は IN6ADDR_ANY_INIT に設定されます。

AI_PASSIVE ビットが hints 構造体の ai_flags メンバーに設定されていない場合、戻されたソケット・アドレス構造体は、 connect サブルーチン (コネクション・オリエンテッド・プロトコルの場合) または connectへの呼び出しの準備ができています。 sendto、または sendmsg サブルーチン (コネクションレス・プロトコルの場合)。 hostname パラメーターが NULL ポインターの場合、ソケット・アドレス構造体の IP アドレス部分はループバック・アドレスに設定されます。

AI_CANONNAME ビットが hints 構造体の ai_flags メンバーに設定されている場合、正常に戻されると、リンク・リスト内の最初の addrinfo 構造体の ai_canonname メンバーは、指定されたホスト名の正規名を含む NULL 終了ストリングを指します。

AI_NUMERICHOST フラグが指定されている場合、指定された非 NULL ノード名ストリングは数値ホスト・アドレス・ストリングです。 それ以外の場合は、(EAI_NONAME) エラーが戻されます。 このフラグは、どのタイプのネーム・レゾリューション・サービス (DNS など) も呼び出されないようにします。

AI_NUMERICSERV フラグが指定されている場合、提供される非 NULL servname ストリングは数値ポート・ストリングです。 それ以外の場合は、(EAI_NONAME) エラーが戻されます。 このフラグは、どのタイプのネーム・レゾリューション・サービスも呼び出されないようにします。

AI_V4MAPPED フラグが AF_INET6の ai_family 値とともに指定されている場合、 getaddrinfo サブルーチンは、一致する IPv6 アドレス (ai_addrlen が 16) が見つからない場合、 IPv4-mapped IPv6 アドレスを返します。 例えば、DNS を使用している場合、AAAA または A6 レコードが見つからないと、A レコードに対して照会が行われます。 検出されたものはすべて、 IPv4-mapped IPv6 アドレスとして戻されます。 AI_V4MAPPED フラグは、 ai_family が AF_INET6と等しくない限り、無視されます。

AI_EXTFLAGS が hints 構造体の ai_flags メンバーに指定され、 ai_eflags がゼロ以外の値に指定されている場合、アドレス選択アルゴリズムが影響を受けます。 アドレス選択アルゴリズムは、各 addrinfo 構造の ai_addr メンバーに含まれるアドレスと、このアドレスに到達できるソース・アドレスを考慮して、一連の順序付き規則 (RFC 3484) を使用して、戻された addrinfo 構造のリストを配列します。 ai_eflags は、優先設定を表します。これは、上位の規則が以前にアドレスのセットを順序付けしていない場合に、以下に示す規則が適用されることを意味します。

ai_eflags は、以下のフラグの組み合わせに設定できます。

例えば、 IPV6_PREFER_SRC_TMP ai_eflags は、アドレス選択アルゴリズムが、一時アドレスから到達可能なアドレスを持つ戻された addrinfo 構造体を、可能な限り、パブリック・アドレスから到達可能なアドレスを持つ addrinfo 構造体の前に配列することを意味します。 矛盾するフラグ (例えば、 IPV6_PREFER_SRC_TMP と IPV6_PREFER_SRC_PUBLIC) を同時に設定すると、エラー EINVAL が発生します。

AI_ADDRCONFIG フラグが指定されている場合、AAAA または A6 レコードの照会は、ノードに少なくとも 1 つの IPv6 ソース・アドレスが構成されている場合にのみ行われます。 A レコードの照会は、ノードに少なくとも 1 つの IPv4 ソース・アドレスが構成されている場合にのみ行われます。 ループバック・アドレスは、構成されたソース・アドレスとして有効ではないと見なされます。

getaddrinfo サブルーチンによって戻されるすべての情報 ( addrinfo 構造体、ソケット・アドレス構造体、および addrinfo 構造体が指す正規ホスト名ストリング) が動的に割り振られます。 この情報をシステムに戻すために、 freeaddrinfo サブルーチンが呼び出されます。

addrinfo 構造は、次のように定義されます。

struct addrinfo {
  int               ai_flags;          /* AI_PASSIVE, AI_CANONNAME */
  int               ai_family;         /* PF_xxx */
  int               ai_socktype;       /* SOCK_xxx */
  int               ai_protocol;       /* 0 or IP=PROTO_xxx for IPv4 and IPv6 */
  size_t            ai_addrlen;        /* length of ai_addr */
  char              *ai_canonname;     /* canoncial name for hostname */
  struct sockaddr   *ai_addr;          /* binary address */
  struct addrinfo   *ai_next;          /* next structure in linked list */
  int ai_eflags; /* Extended flags for special usage */
}

戻り値

照会が成功すると、1 つ以上の addrinfo 構造のリンク・リストへのポインターが res パラメーターを介して戻されます。 ゼロの戻り値は成功を示します。 照会が失敗すると、ゼロ以外のエラー・コードが返されます。

エラー・コード

以下の名前は、ゼロ以外のエラー・コードです。 詳しい定義については、 netdb.h を参照してください。