gethostbyname - ライブラリコールの説明 - Linux コマンド集 一覧表

gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, herror, hstrerror - ネットワーク上のホストのエントリを取得する

#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, int 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 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);

gethostbyname ()関数は与えられたホスト名 name に対応する構造体 hostent を返す。ここで name はホスト名、ドット区切りの IPv4 アドレス、コロン区切りの (ドット区切りでも大丈夫かもしれない) IPv6 アドレスのいずれかである。 (IPv6 アドレスの記述については RFC1884 を参考にしてほしい)。 name が IPv4 か IPv6 のアドレスだった場合には、 名前引き (lookup) は行われない。 gethostbyname ()は単に name をそのまま hostent 構造体の h_name フィールドにコピーし、 さらに name を struct in_addr 形式で表したデータを同構造体の h_addr_list[0] フィールドに入れて、その構造体を返す。 name がドットで終了していて、かつ環境変数 HOSTALIASES が設定されている場合は、まず HOSTALIASES で指定されているエイリアスファイルから name のエントリが検索される (ファイルのフォーマットについては   hostname (7) を参照のこと)。 name がドットで終了していなければ現在のドメインとその親ドメインが検索される。

gethostbyaddr ()関数は与えられたホストアドレス addr (長さ len 、 タイプ type ) に対応する構造体 hostent を返す。 用いることのできるタイプは AF_INET と AF_INET6 である。 ホストアドレス引き数はアドレスタイプに依存した 構造体へのポインタである。 例えば、アドレスタイプ AF_INET に対しては (inet_addr () の呼び出しで得られる) struct in_addr * である。

sethostent ()関数は、ネームサーバーへの接続様式を指定する。 stayopen が真 (1) ならば、ネームサーバーへの問い合わせには、 接続された TCP ソケットを用い、連続した問い合わせの間に接続を維持する。 偽ならばネームサーバーへの問い合わせに UDP データグラムを用いる。

endhostent ()関数はネームサーバーへの問い合わせに用いた TCP 接続の利用を終了する。

herror ()関数 (もう古い) は現在の h_errno に対応するエラーメッセージを stderr に出力する。

hsterror ()関数 (もう古い) はエラー番号 (典型的には 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]		/* for backward compatibility */

hostent 構造体のメンバは以下の通り。

h_name

ホストの正式名 (official name)。

h_aliases

ホストの別名の配列。配列は NULL ポインタで終端される。

h_addrtype

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

h_length

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

h_addr_list

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

h_addr

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

gethostbyname ()および gethostbyaddr ()関数は hostent 構造体を返す。エラーが起こったら NULL ポインタを返す。エラーの際には 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

ネームサービス切替設定

4.3BSD, POSIX.1-2001.

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

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

glibc2 にはリエントラントな gethostbyname_r ()と gethostbyname2_r ()もある。 これらの関数は、成功した場合は 0 を返し、失敗した場合は 0 以外を返す。 現在のところ、この呼び出しの結果はアドレスが ret の構造体に格納される。 呼び出しの後、失敗した場合は * result が NULL になり、成功した場合は * result が結果を指し示す。 補足データは長さ buflen のバッファ buf に格納される。 (バッファが小さすぎる場合、これらの関数は ERANGE を返す。) 大域変数 h_errno は変更されないが、エラー番号を格納する変数のアドレスが h_errnop に渡される。

gethostbyname ()および gethostbyaddr ()関数は静的データへのポインタを返す。 このポインタは、その後の呼び出しで上書きされるかもしれない。 hostent 構造体はポインタを含んでいるので、構造体のコピーだけでは不十分である; より深いコピーが必要である。

SUS-v2 はバグが多く、 gethostbyaddr ()の len パラメータを size_t 型として宣言している。 (これは誤りで、 size_t 型ではなく int 型でなければならない。 POSIX.1-2001 ではこれを socklen_t としているが、これは OK。)

gethostbyaddr ()の BSD のプロトタイプは、最初の引き数として const char * を使う。

POSIX.1-2001 では gethostbyaddr ()および gethostbyname ()を廃れかかったものとされている。   getaddrinfo (3),   getnameinfo (3),  gai_strerror (3)を参照。

  getaddrinfo (3),  getipnodebyaddr (3),  getipnodebyname (3),   getnameinfo (3),   inet_ntop (3),   inet_pton (3),   resolver (3),   hosts (5),   nsswitch.conf (5),   hostname (7),   named (8)