Provided by: manpages-ja-dev_0.5.0.0.20180315+dfsg-1_all 
名前
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)