gethostbyname(3)

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

標準 C ライブラリ (libc, −lc)

#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_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/host.conf
/etc/resolv.conf

診断

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

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

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

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 ではじめて登場しまし た。

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

FreeBSD 10.0 May 25, 1995 FreeBSD 10.0