GETHOSTBYNAME(3) | FreeBSD Library Functions Manual | GETHOSTBYNAME(3) |
名称
gethostbyname, gethostbyname2, gethostbyaddr, gethostent, sethostent, endhostent, herror, hstrerror — ネットワークホストのエントリを取得するライブラリ
Standard C Library (libc, -lc)書式
#include < netdb.h>int h_errno;
struct hostent *
gethostbyname( const char *name);
struct hostent *
gethostbyname2( const char *name, int af);
struct hostent *
gethostbyaddr( const void *addr, socklen_t len, int af);
struct hostent *
gethostent( void);
void
sethostent( int stayopen);
void
endhostent( void);
void
herror( const char *string);
const char *
hstrerror( int err);
解説
gethostbyname(), gethostbyname2() と gethostbyaddr() 関数は、それぞれ、名前で参照されるか、またはアドレスによって参照されるインターネットホストについて記述する次の構造体があるオブジェクトへのポインタを返します。
gethostbyname() または gethostbyname2() に渡される name 引数は、 ヌル文字 で終了するホスト名を指すべきです。 gethostbyaddr() に渡される addr 引数は、バイナリ形式の len バイト長のアドレスを指すべきです (すなわち、人間に読み込み可能な ASCII 形式の IP アドレスではない)。 af 引数は、このアドレスのアドレスファミリ (例えば、 AF_INET, AF_INET6、その他) を指定します。
返される構造体は、ネームサーバ named(8) から、 /etc/hosts の行から取り出されたフィールドから、または yp(8) システムによって供給されたデータベースエントリから取得される情報を含んでいます。検索の順序は、 nsswitch.conf(5) の‘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
- ホストのための代替の名前の NULL で終了する配列。
- h_addrtype
- 返されるアドレスのタイプ。通常、 AF_INET。
- h_length
- アドレスのバイト単位の長さ。
- h_addr_list
- ホストのためのネットワークアドレスの NULL で終了する配列。ホストアドレスは、ネットワークバイト順で返されます。
- h_addr
- h_addr_list の最初のアドレス。これは、後方互換性のためです。
ネームサーバを使用するとき、 gethostbyname() と gethostbyname2() は、名前がドットで終わっていないなら、現在のドメインと親のドメインの指定されたホストを検索します。名前にドットが含まれていないなら、そして環境変数“ HOSTALIASES”に別名ファイルの名前が含まれているなら、別名ファイルは、最初に入力名と一致する別名を検索されます。ドメイン検索手続きと別名ファイルの形式については、 hostname(7) を参照してください。
gethostbyname2() 関数は、例えば、 AF_INET6 のための AF_INET 以外のアドレスファミリで検索を可能にすることを目的としている、 gethostbyname() の発展形です。
sethostent() 関数は、問い合わせのために接続された TCP ソケットの使用を要求するために使用されます。 stayopen フラグが 0 でないなら、 TCP を使用してネームサーバにすべての問い合わせを送るためのオプションを設定し、 gethostbyname(), gethostbyname2() と gethostbyaddr() へのそれぞれ呼び出し後に接続を保持するためのオプションを設定します。そうでなければ、問い合わせは UDP データグラムを使用して実行されます。
endhostent() 関数は、 TCP 接続をクローズします。
herror() 関数は、文字列引数 string、定数文字列“ :
”と h_errno の値に対応するメッセージから成る診断出力へのメッセージを書き込みます。
hstrerror() 関数は、 err 引数の値に対応するメッセージテキストである文字列を返します。
関連ファイル
- /etc/hosts
- /etc/nsswitch.conf
- /etc/resolv.conf
使用例
特定の IP アドレスに関連しているホスト名を印刷 (表示) します。
const char *ipstr = "127.0.0.1"; struct in_addr ip; struct hostent *hp; if (!inet_aton(ipstr, &ip)) errx(1, "can't parse IP address %s", ipstr); if ((hp = gethostbyaddr((const void *)&ip, sizeof ip, AF_INET)) == NULL) errx(1, "no name associated with %s", ipstr); printf("name associated with %s is %s\n", ipstr, hp->h_name);
診断
gethostbyname(), gethostbyname2() と gethostbyaddr() からのエラーリターン状態は、 NULL ポインタが返ることによって示されます。整数 h_errno は、次に、これが、一時的な失敗か、無効または未知のホスト名かどうかを調べるためにチェックされます。失敗を記述するエラーメッセージをプリントするために、ルーチン herror() を使用することができます。引数 string が NULL でないなら、コロンと空白を続けて印刷 (表示) されます。エラーメッセージは、終端の改行を付けて印刷 (表示) されます。変数 h_errno は、次の値を持つことができます:
- HOST_NOT_FOUND
- そのようなホストは、知られていません。
- TRY_AGAIN
- これは、通常、一時的なエラーで、ローカルサーバが信頼できるサーバからの応答を受け取らなかったことを意味します。しばらく経ってからの再試行は、成功するかもしれません。
- NO_RECOVERY
- ある予期しないサーバの失敗に遭遇しました。これは、回復不可能なエラーです。
- NO_DATA
- 要求された名前は、有効ですが、IP アドレスがありません。これは、一時的エラーではありません。これは、名前がネームサーバに知られているが、この名前に関連したアドレスがないことを意味します。このドメイン名を使用するネームサーバへの別のタイプの要求は、答えをもたらします。例えば、メール発送者は、このドメインのために登録されます。
警告
Standard C Library (libc, -lc) がネームサーバでなく、 /etc/hosts で検索するためのルーチンのみを使用して構築されたとき、 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 ではじめて登場しました。バグ
これらの関数は、スレッド特有のデータ記憶域を使用します。データが将来の使用のための必要とされるなら、それは、あらゆる以後の呼び出しがそれを上書きする前に、コピーされるべきです。これらの関数は、スレッドセーフですが、いまだに、代わりに getaddrinfo(3) 関数ファミリを使用することをお勧めします。
インターネットアドレス形式だけが現在解釈されます。
May 12, 2006 | FreeBSD |