gethostbyname

GETHOSTBYNAME(3)            Linux Programmer's Manual           GETHOSTBYNAME(3)



名前
       gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent,
       h_errno, herror, hstrerror, gethostbyaddr_r, gethostbyname2,
       gethostbyname2_r, gethostbyname_r, gethostent_r - ネットワーク上のホストのエントリーを取得する

書式
       #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 gethostbyaddr_r(const void *addr, socklen_t len, int type,
               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(), gethostbyaddr_r(), gethostbyname_r(),
       gethostbyname2_r():
           _BSD_SOURCE || _SVID_SOURCE

       herror(), hstrerror():
           glibc 2.8 以降:
               _BSD_SOURCE || _SVID_SOURCE
           glibc 2.8 より前:
               なし

       h_errno:
           glibc 2.12 以降:
               _BSD_SOURCE || _SVID_SOURCE ||
                   (_POSIX_C_SOURCE < 200809L && _XOPEN_SOURCE < 700)
           glibc 2.12 より前:
               なし

説明
       関数 gethostbyname*(), gethostbyaddr*(), herror(), hstrerror は過去のものである。
       アプリケーションは、代わりに getaddrinfo(3), getnameinfo(3), gai_strerror(3) を使用すること。

       gethostbyname()  関数は与えられたホスト名 name に対応する構造体 hostent を返す。 name
       にはホスト名、ドット区切りの IPv4 アドレス (inet_addr(3)  参照)、コロン区切りの 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
              ホストの別名の配列。配列はヌルポインターで終端される。

       h_addrtype
              アドレスのタイプ。現在はすべて AF_INET または AF_INET6 である。

       h_length
              バイト単位で表したアドレスの長さ。

       h_addr_list
              ホストのネットワークアドレスへのポインターの配列。 配列はヌルポインターで終端される。
              ネットワークアドレスはネットワークバイトオーダ形式である。

       h_addr h_addr_list の最初のアドレス。過去との互換性を保つためのものである。

返り値
       gethostbyname()  および gethostbyaddr()  関数は hostent
       構造体を返す。エラーが起こったらヌルポインターを返す。エラーの際には 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
              ネームサービス切替設定

準拠
       POSIX.1-2001 では、 gethostbyname(), gethostbyaddr(), sethostent(),
       endhostent(), gethostent(), h_errno が規定されており、 gethostbyaddr()  と
       gethostbyname()  は廃止予定であるとされている。 POSIX.1-2008 では gethostbyname(),
       gethostbyaddr(), h_errno の仕様が削除されている。 代わりに、 getaddrinfo(3)getnameinfo(3)  の使用が推奨されている。

注意
       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 * を使う。

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

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

       glibc2 にはリエントラントな gethostent_r(), gethostbyaddr_r(), gethostbyname_r()  と
       gethostbyname2_r()  もある。 呼び出し側は、成功時に結果が格納される hostent 構造体 ret と、大きさ buflen
       の一時的な作業バッファー buf を提供する。 コール終了後、成功した場合 result は結果を指している。
       エラーの場合、またはエントリーが見つからなかった場合、 result は NULL になる。 これらの関数は、成功した場合 0
       を返し、失敗の場合は 0 以外のエラー番号を返す。 これらの関数のリエントラントでないバージョンが返すエラーに加えて、 これらの関数は、 buf
       が小さすぎた場合に ERANGE を返す。この場合はもっと大きなバッファーを用意して 関数呼び出しを再度行うべきである。 大域変数 h_errno
       は変更されないが、エラー番号を格納する変数のアドレスが h_errnop に渡される。

バグ
       gethostbyname()  は、16進数表現のドット区切りの IPv4 アドレス文字列の要素を認識しない。

関連項目
       getaddrinfo(3), getnameinfo(3), inet(3), inet_ntop(3), inet_pton(3),
       resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8)

この文書について
       この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部
       である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。



                                   2014-03-11                   GETHOSTBYNAME(3)