Manpages

名 前

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_aliases ホ ス ト の 別 名 の 配 列 。 配 列 は ヌ ル ポ イ ン タ ー で 終 端 さ れ る 。
h_addrtype ア ド レ ス の タ イ プ 。 現 在 は す べ て AF_INET ま た は AF_INET6 で あ る 。
h_length バ イ ト 単 位 で 表 し た ア ド レ ス の 長 さ 。
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/ に 書 か れ て い る 。