GETHOSTBYNAME(3)

名称
gethostbyname, gethostbyname2, gethostbyaddr, gethostent, sethostent, endhostent, herror, hstrerror - ネットワークホストのエントリの取得

ライブラリ
libc

書式
#include <netdb.h> extern int h_errno; struct hostent * gethostbyname(const char *name) struct hostent * gethostbyname2(const char *name, int af) struct hostent * gethostbyaddr(const char *addr, int len, int type) struct hostent * gethostent(void) void sethostent(int stayopen) void endhostent(void) void herror(const char *string) const char * hstrerror(int err)

解説
gethostbyname(), gethostbyname2(), gethostbyaddr() 関数はそれぞれ、次に示す構造を持つオブジェクトへのポインタを返します。 構造体には、名前またはアドレスによって参照されるインターネットホストが 記述されていて、ネームサーバ named(8) から、または /etc/hosts にある行の内訳フィールドから得られた情報を含んでいます。 ローカルのネームサーバが実行されていない場合、これらのルーチンは /etc/hosts を検索します。

    struct  hostent {
            char    *h_name;        /* ホストの正式名 */
            char    **h_aliases;    /* 別名リスト */
            int     h_addrtype;     /* ホストアドレスタイプ */
            int     h_length;       /* アドレスの長さ */
            char    **h_addr_list;  /* ネームサーバからのアドレスリスト */
    };
    #define h_addr  h_addr_list[0]  /* アドレス、後方互換用 */

この構造体のメンバは次のとおりです。

h_name
    ホストの正式名。

h_aliases
    ホストの別名 (エイリアス) のヌルで終わる配列。

h_addrtype
    返されるアドレスのタイプであり、通常は AF_INET 。

h_length
    アドレスのバイト数による長さ。

h_addr_list
    ホストのネットワークアドレスのヌルで終わる配列。 ホストアドレスはネットワークバイトオーダで返されます。

h_addr
    h_addr_list にある最初のアドレスであり、後方互換用。

ネームサーバを使用する場合、名前がドットで終わっていない時は gethostbyname() および gethostbyname2() は名前が付いたホストを、現在のドメインと親のドメインから検索します。 名前にドットが含まれてなく、且つ環境変数 “HOSTALIASES” にエイリアスファイルの名前が含まれている場合は、 入力名に適合するエイリアスが、まずエイリアスファイルから検索されます。 ドメイン検索の手続きとエイリアスファイルの書式については、 hostname(7) を参照してください。

gethostbyname2() 関数は gethostbyname() の発展型で、 AF_INET 以外のアドレスファミリ、たとえば AF_INET6 での検索を可能にするためのものです。ただし現在は、 af 引数に AF_INET を指定する必要があります。他の値を指定すると gethostbyname2() 関数は、 h_errno を NETDB_INTERNAL に設定した後で、 NULL を返します。

sethostent() 関数は、問い合わせの際に接続された TCP ソケットを使いたい場合に使用できます。 stayopen フラグが 0 でなければ、 TCP によってすべての問い合わせをネームサーバに送り、 gethostbyname(), gethostbyname2(), gethostbyaddr() のそれぞれ呼び出し後にも、接続を保持するようにオプションを設定します。 フラグが 0 の時、問い合わせは UDP データグラムを使用して 実行されます。

endhostent() 関数は TCP 接続をクローズします。

herror() 関数は診断出力にメッセージを書き出します。 診断出力は文字列パラメータ s と、定数文字列 ": " と、 h_errno の値に対応するメッセージで構成されます。

hstrerror() 関数は、 err パラメータの値に対応するメッセージテキストの 文字列を返します。

関連ファイル
/etc/hosts
/etc/host.conf
/etc/resolv.conf

診断
gethostbyname(), gethostbyname2(), gethostbyaddr() のエラー状態は、 NULL ポインタが返ることで示されます。その場合は外部整数 h_errno をチェックすることにより、 一時的なエラーであるのか、 無効または未知のホスト名を指定したためかを判断できます。 herror() ルーチンによって、エラーを記述するエラーメッセージを表示できます。 引数 string は NULL でなければ表示され、後にコロンとスペースが続きます。 エラーメッセージが終端の改行とともに印刷されます。

変数 h_errno は次の値を取り得ます。

HOST_NOT_FOUND
    指定した名前のホストが未知です。

TRY_AGAIN
    これは通常は一時的なエラーで、ローカルサーバが公式サーバ から応答が得られなかったことを意味します。しばらくして再度試みると成功する 場合があります。

NO_RECOVERY
    なんらかの予期しないサーバエラーが発生しました。 これは回復不能なエラーです。

NO_DATA
    要求された名前は有効ですが、IP アドレスがありません。 これは一時的なエラーではありません。 指定したホスト名がネームサーバには知られているにもかかわらず、 対応するアドレスがないという意味です。 このネームサーバに対して同じドメイン名で別なタイプの要求を行うと、 回答が得られるかもしれません。 たとえばメールフォワーダがそのドメインに登録されている場合があります。

関連項目
getaddrinfo(3), resolver(3), hosts(5), hostname(7), named(8)

警告
ネームサーバは検索せずに /etc/hosts だけを検索するルーチンを使用するように libc(3) が構築された場合、 gethostent() 関数が定義され、 sethostent() および endhostent() が再定義されます。

gethostent() 関数は、 /etc/hosts ファイルの次の行を読み込みます。 この際、必要ならばファイルをオープンします。

sethostent() 関数はファイル /etc/hosts をオープンもしくはリワインドします。 stayopen 引数が 0 でなければ、 gethostbyname(), gethostbyname2(), gethostbyaddr() のそれぞれの呼び出しの後、ファイルはクローズされません。

endhostent() 関数はファイルをクローズします。

歴史
herror() 関数は 4.3BSD で登場しました。 endhostent(), gethostbyaddr(), gethostbyname(), gethostent(), sethostent() 関数は 4.2BSD で登場しました。 gethostbyname2() 関数は BIND バージョン 4.9.4 ではじめて登場しました。

バグ
これらの関数は静的データ記憶域を使用します。 後でこのデータを使う必要がある場合は、以後のこれらの関数呼び出しで データが上書きされる前に、コピーして保存する必要があります。 なお、アドレスデータとして受け入れるのは現在、 インターネットアドレスフォーマットだけです。