gethostbyname

Autres langues

Langue: ja

Autres versions - même langue

Version: 2007-07-26 (fedora - 25/11/07)

Section: 3 (Bibliothèques de fonctions)

Sommaire

名前

gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, herror, hstrerror - ネットワーク上のホストのエントリを取得する

書式

 #include <netdb.h>
 extern int h_errno;
 
 struct hostent *gethostbyname(const char *name);
 
 #include <sys/socket.h>       /* AF_INET を使う場合 */
 struct hostent *gethostbyaddr(const void *addr, socklen_t len, int type);
 
 void sethostent(int stayopen);
 
 void endhostent(void);
 
 void herror(const char *s);
 
 const char *hstrerror(int err);
 
 /* System V/POSIX 拡張 */
 

 struct hostent *gethostent(void);
 
 /* GNU 拡張 */
 

 struct hostent *gethostbyname2(const char *name, int af);
 
 int gethostent_r(
         struct hostent *ret, char *buf, size_t buflen,
         struct hostent **result, int *h_errnop);
 
 int gethostbyname_r(const char *name,
         struct hostent *ret, char *buf, size_t buflen,
         struct hostent **result, int *h_errnop);
 
 int gethostbyname2_r(const char *name, int af,
         struct hostent *ret, char *buf, size_t buflen,
         struct hostent **result, int *h_errnop);

glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照):

gethostbyname2(), gethostent_r(), gethostbyname_r(), gethostbyname2_r(): _BSD_SOURCE || _SVID_SOURCE

説明

gethostbyname() 関数は与えられたホスト名 name に対応する構造体 hostent を返す。 name にはホスト名、ドット区切りの IPv4 アドレス、コロン区切りの (ドット区切りでも大丈夫かもしれない) IPv6 アドレスのいずれかを指定する (IPv6 アドレスの記述方法については RFC 1884 を参考にしてほしい)。 name が IPv4 か IPv6 のアドレスだった場合、 名前解決 (lookup) は行われない。その場合には、 gethostbyname() は name をそのまま hostent 構造体の h_name フィールドにコピーし、 さらに name を struct in_addr 形式で表したデータを hostent 構造体の h_addr_list[0] フィールドに入れて、その hostent 構造体を返す。 name がドットで終了していて、かつ環境変数 HOSTALIASES が設定されている場合、まず HOSTALIASES で指定されているエイリアスファイルから name のエントリが検索される (ファイルのフォーマットについては hostname(7) を参照のこと)。 name がドットで終了していなければ、現在のドメインとその親ドメインが検索される。

gethostbyaddr() 関数は与えられたホストアドレス addr (長さ len、 タイプ type) に対応する構造体 hostent を返す。 用いることのできるタイプは AF_INET と AF_INET6 である。 ホストアドレス引き数はアドレスタイプに依存した 構造体へのポインタである。 例えば、アドレスタイプ AF_INET に対しては (inet_addr(3) の呼び出しで得られる) struct in_addr * である。

sethostent() 関数は、ネームサーバへの接続形態を指定する。 stayopen が真 (1) ならば、ネームサーバへの問い合わせには、 接続された TCP ソケットを用い、連続した問い合わせの間に接続を維持する。 偽ならばネームサーバへの問い合わせに UDP データグラムを用いる。

endhostent() 関数はネームサーバへの問い合わせに用いた TCP 接続の利用を終了する。

(廃止予定の) herror() 関数は現在の h_errno に対応するエラーメッセージを標準エラー stderr に出力する。

(廃止予定の) hstrerror() 関数はエラー番号 (通常は h_errno) を引き数に取り、 対応するエラーメッセージ文字列を返す。

gethostbyname() と gethostbyaddr() によって実行されるドメイン名の問い合わせでは、ネームサーバ named(8)、 /etc/hosts のデータ行、および Network Information Service (NIS または YP) が組み合わせて使用される。何が使用されるかは、 /etc/host.conf の order 行の内容により決まる。 デフォルトでは、まず named(8) に問い合わせを行い、次いで /etc/hosts を参照する。

hostent 構造体は <netdb.h> で以下のように定義されている:

 struct hostent {
     char  *h_name;            /* official name of host */
     char **h_aliases;         /* alias list */
     int    h_addrtype;        /* host address type */
     int    h_length;          /* length of address */
     char **h_addr_list;       /* list of addresses */
 }
 #define h_addr h_addr_list[0] /* 過去との互換性のため */

hostent 構造体のメンバは以下の通り。

h_name
ホストの正式名 (official name)。
h_aliases
ホストの別名の配列。配列は NULL ポインタで終端される。
h_addrtype
アドレスのタイプ。現在はすべて AF_INET または AF_INET6 である。
h_length
バイト単位で表したアドレスの長さ。
h_addr_list
ホストのネットワークアドレスへのポインタの配列。 配列は NULL ポインタで終端される。 ネットワークアドレスはネットワークバイトオーダ形式である。
h_addr
h_addr_list の最初のアドレス。過去との互換性を保つためのものである。

返り値

gethostbyname() および gethostbyaddr() 関数は hostent 構造体を返す。エラーが起こったら NULL ポインタを返す。エラーの際には h_errno 変数がエラーの番号を保持する。 返り値が NULL でない場合、静的データをポインタで指していることもある。 以下の「注意」を参照すること。

エラー

h_errno 変数は以下の値を取りうる。
HOST_NOT_FOUND
指定したホストが見つからない。
NO_ADDRESS または NO_DATA
指定した名前は有効だが IP アドレスを持っていない。
NO_RECOVERY
ネームサーバの復旧不能なエラーが起こった。
TRY_AGAIN
authoritative なネームサーバで一時的なエラーが起こった。 時間をおいてもう一度試すこと。

ファイル

/etc/host.conf
名前解決の設定ファイル
/etc/hosts
ホストのデータベースファイル
/etc/nsswitch.conf
ネームサービス切替設定

準拠

4.3BSD, POSIX.1-2001.

注意

gethostbyname() および gethostbyaddr() 関数は静的データへのポインタを返す。 このポインタは、その後の呼び出しで上書きされるかもしれない。 hostent 構造体はポインタを含んでいるので、構造体のコピーだけでは不十分である; より深いコピーが必要である。

オリジナルの BSD の実装では、 gethostbyname() の len 引き数は int であった。 SUSv2 標準はバグが多く、 gethostbyaddr() の len パラメータを size_t 型として宣言している。 (これは誤りで、 size_t 型ではなく int 型でなければならない。 POSIX.1-2001 ではこれを socklen_t としているが、これは OK。) accept(2) も参照。

gethostbyaddr() の BSD のプロトタイプは、最初の引き数として const char * を使う。

POSIX.1-2001 では gethostbyaddr() および gethostbyname() を廃止予定であるとされている。 getaddrinfo(3), getnameinfo(3), gai_strerror(3) を参照。

System V/POSIX 拡張

POSIX では、 gethostent() が必須とされている。 この関数はホストデータベースの次のエントリを返す。 DNS/BIND を使う場合はあまり意味を持たないが、 ホストデータベースが 1 行ずつ読み込まれるファイルである場合は意味がある。 多くのシステムでは、この名前のルーチンはファイル /etc/hosts を読み込む。 DNS サポートなしでライブラリがビルドされた場合にのみ利用可能である。 glibc 版は ipv6 エントリを無視する。 この関数はリエントラント (reentrant) ではなく、 glibc にはリエントラント版の gethostent_r() が追加された。

GNU 拡張

glibc2 には gethostbyname2() もあり、 gethostbyname() と同じように動作するが、 こちらはアドレスが属するアドレスファミリーを指定することができる。

glibc2 にはリエントラントな gethostbyname_r() と gethostbyname2_r() もある。 これらの関数は、成功した場合は 0 を返し、失敗した場合は 0 以外を返す。 現在のところ、この呼び出しの結果はアドレスが ret の構造体に格納される。 呼び出しが失敗した場合は *result が NULL になり、成功した場合は *result が結果を指し示す。 補足データは長さ buflen のバッファ buf に格納される。 (バッファが小さすぎる場合、これらの関数は ERANGE を返す。) 大域変数 h_errno は変更されないが、エラー番号を格納する変数のアドレスが h_errnop に渡される。

関連項目

getaddrinfo(3), getipnodebyaddr(3), getipnodebyname(3), getnameinfo(3), inet_ntop(3), inet_pton(3), resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8)