release/man3/gethostbyname.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" References consulted:
  24 .\"     Linux libc source code
  25 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  26 .\"     386BSD man pages
  27 .\" Modified 1993-05-22, David Metcalfe
  28 .\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu)
  29 .\" Modified 1997-02-16, Andries Brouwer (aeb@cwi.nl)
  30 .\" Modified 1998-12-21, Andries Brouwer (aeb@cwi.nl)
  31 .\" Modified 2000-08-12, Andries Brouwer (aeb@cwi.nl)
  32 .\" Modified 2001-05-19, Andries Brouwer (aeb@cwi.nl)
  33 .\" Modified 2002-08-05, Michael Kerrisk
  34 .\" Modified 2004-10-31, Andries Brouwer
  35 .\"
  36 .\"*******************************************************************
  37 .\"
  38 .\" This file was generated with po4a. Translate the source file.
  39 .\"
  40 .\"*******************************************************************
  41 .TH GETHOSTBYNAME 3 2010\-10\-04 "" "Linux Programmer's Manual"
  42 .SH 名前
  43 gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, h_errno,
  44 herror, hstrerror, gethostbyaddr_r, gethostbyname2, gethostbyname2_r,
  45 gethostbyname_r, gethostent_r \- ネットワーク上のホストのエントリを取得する
  46 .SH 書式
  47 .nf
  48 \fB#include <netdb.h>\fP
  49 \fBextern int h_errno;\fP
  50 .sp
  51 \fBstruct hostent *gethostbyname(const char *\fP\fIname\fP\fB);\fP
  52 .sp
  53 \fB#include <sys/socket.h>\fP       /* AF_INET を使う場合 */
  54 \fBstruct hostent *gethostbyaddr(const void *\fP\fIaddr\fP\fB,\fP
  55 \fB                              socklen_t \fP\fIlen\fP\fB, int \fP\fItype\fP\fB);\fP
  56 .sp
  57 \fBvoid sethostent(int \fP\fIstayopen\fP\fB);\fP
  58 .sp
  59 \fBvoid endhostent(void);\fP
  60 .sp
  61 \fBvoid herror(const char *\fP\fIs\fP\fB);\fP
  62 .sp
  63 \fBconst char *hstrerror(int \fP\fIerr\fP\fB);\fP
  64 .sp
  65 /* System V/POSIX 拡張 */
  66 .br
  67 \fBstruct hostent *gethostent(void);\fP
  68 .sp
  69 /* GNU 拡張 */
  70 .br
  71 \fBstruct hostent *gethostbyname2(const char *\fP\fIname\fP\fB, int \fP\fIaf\fP\fB);\fP
  72 .sp
  73 \fBint gethostent_r(\fP
  74 \fB        struct hostent *\fP\fIret\fP\fB, char *\fP\fIbuf\fP\fB, size_t \fP\fIbuflen\fP\fB,\fP
  75 \fB        struct hostent **\fP\fIresult\fP\fB, int *\fP\fIh_errnop\fP\fB);\fP
  76 .sp
  77 \fBint gethostbyaddr_r(const void *\fP\fIaddr\fP\fB, socklen_t \fP\fIlen\fP\fB, int \fP\fItype\fP\fB,\fP
  78 \fB        struct hostent *\fP\fIret\fP\fB, char *\fP\fIbuf\fP\fB, size_t \fP\fIbuflen\fP\fB,\fP
  79 \fB        struct hostent **\fP\fIresult\fP\fB, int *\fP\fIh_errnop\fP\fB);\fP
  80 .sp
  81 \fBint gethostbyname_r(const char *\fP\fIname\fP\fB,\fP
  82 \fB        struct hostent *\fP\fIret\fP\fB, char *\fP\fIbuf\fP\fB, size_t \fP\fIbuflen\fP\fB,\fP
  83 \fB        struct hostent **\fP\fIresult\fP\fB, int *\fP\fIh_errnop\fP\fB);\fP
  84 .sp
  85 \fBint gethostbyname2_r(const char *\fP\fIname\fP\fB, int \fP\fIaf,\fP
  86 \fB        struct hostent *\fP\fIret\fP\fB, char *\fP\fIbuf\fP\fB, size_t \fP\fIbuflen\fP\fB,\fP
  87 \fB        struct hostent **\fP\fIresult\fP\fB, int *\fP\fIh_errnop\fP\fB);\fP
  88 .fi
  89 .sp
  90 .in -4n
  91 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  92 .in
  93 .sp
  94 .PD 0
  95 .ad l
  96 \fBgethostbyname2\fP(), \fBgethostent_r\fP(), \fBgethostbyaddr_r\fP(),
  97 \fBgethostbyname_r\fP(), \fBgethostbyname2_r\fP():
  98 .RS 4
  99 _BSD_SOURCE || _SVID_SOURCE
 100 .RE
 101
 102 \fBherror\fP(), \fBhstrerror\fP():
 103 .RS 4
 104 .TP  4
 105 glibc 2.8 以降:
 106 _BSD_SOURCE || _SVID_SOURCE || _GNU_SOURCE
 107 .TP
 108 glibc 2.8 より前:
 109 なし
 110 .RE
 111 .ad b
 112 .PD
 113 .SH 説明
 114 \fBgethostbyname*\fP()  と \fBgethostbyaddr*\fP()  は過去のものである。 アプリケーションでは、代わりに
 115 \fBgetaddrinfo\fP(3)  と \fBgetnameinfo\fP(3)  を使用すること。
 116
 117 \fBgethostbyname\fP()  関数は与えられたホスト名 \fIname\fP に対応する構造体 \fIhostent\fP を返す。 \fIname\fP
 118 にはホスト名、ドット区切りの IPv4 アドレス (\fBinet_addr\fP(3)  参照)、コロン区切りの IPv6 アドレス
 119 (おそらくドット区切りでも大丈夫)  のいずれかを指定する (IPv6 アドレスの記述方法については RFC\ 1884 を参考にしてほしい)。
 120 \fIname\fP が IPv4 か IPv6 のアドレスだった場合、 名前解決 (lookup) は行われない。その場合には、
 121 \fBgethostbyname\fP()  は \fIname\fP をそのまま \fIhostent\fP 構造体の \fIh_name\fP フィールドにコピーし、
 122 さらに \fIname\fP を \fIstruct in_addr\fP 形式で表したデータを \fIhostent\fP 構造体の \fIh_addr_list[0]\fP
 123 フィールドに入れて、その \fIhostent\fP 構造体を返す。 \fIname\fP がドットで終了していて、かつ環境変数 \fBHOSTALIASES\fP
 124 が設定されている場合、まず \fBHOSTALIASES\fP で指定されているエイリアスファイルから \fIname\fP のエントリが検索される
 125 (ファイルのフォーマットについては \fBhostname\fP(7)  を参照のこと)。 \fIname\fP
 126 がドットで終了していなければ、現在のドメインとその親ドメインが検索される。
 127 .PP
 128 \fBgethostbyaddr\fP()  関数は与えられたホストアドレス \fIaddr\fP (長さ \fIlen\fP、 タイプ \fItype\fP)
 129 に対応する構造体 \fIhostent\fP を返す。 用いることのできるタイプは \fBAF_INET\fP と \fBAF_INET6\fP である。
 130 ホストアドレス引き数はアドレスタイプに依存した 構造体へのポインタである。 例えば、アドレスタイプ \fBAF_INET\fP に対しては
 131 (\fBinet_addr\fP(3)  の呼び出しで得られる)  \fIstruct in_addr *\fP である。
 132 .PP
 133 \fBsethostent\fP()  関数は、ネームサーバへの接続形態を指定する。 \fIstayopen\fP が真 (1)
 134 ならば、ネームサーバへの問い合わせには、 接続された TCP ソケットを用い、連続した問い合わせの間に接続を維持する。
 135 偽ならばネームサーバへの問い合わせに UDP データグラムを用いる。
 136 .PP
 137 \fBendhostent\fP()  関数はネームサーバへの問い合わせに用いた TCP 接続の利用を終了する。
 138 .PP
 139 (廃止予定の)  \fBherror\fP()  関数は現在の \fIh_errno\fP に対応するエラーメッセージを標準エラー \fIstderr\fP に出力する。
 140 .PP
 141 (廃止予定の)  \fBhstrerror\fP()  関数はエラー番号 (通常は \fIh_errno\fP) を引き数に取り、
 142 対応するエラーメッセージ文字列を返す。
 143 .PP
 144 .\" (See
 145 .\" .BR resolv+ (8)).
 146 \fBgethostbyname\fP()  と \fBgethostbyaddr\fP()  によって実行されるドメイン名の問い合わせでは、ネームサーバ
 147 \fBnamed\fP(8)、 \fI/etc/hosts\fP のデータ行、および Network Information Service (NIS または
 148 YP)  が組み合わせて使用される。何が使用されるかは、 \fI/etc/host.conf\fP の \fIorder\fP 行の内容により決まる。
 149 デフォルトでは、まず \fBnamed\fP(8)  に問い合わせを行い、次いで \fI/etc/hosts\fP を参照する。
 150 .PP
 151 \fIhostent\fP 構造体は \fI<netdb.h>\fP で以下のように定義されている:
 152 .sp
 153 .in +4n
 154 .nf
 155 .ne 7
 156 struct hostent {
 157     char  *h_name;            /* official name of host */
 158     char **h_aliases;         /* alias list */
 159     int    h_addrtype;        /* host address type */
 160     int    h_length;          /* length of address */
 161     char **h_addr_list;       /* list of addresses */
 162 }
 163 #define h_addr h_addr_list[0] /* 過去との互換性のため */
 164 .fi
 165 .in
 166 .PP
 167 \fIhostent\fP 構造体のメンバは以下の通り。
 168 .TP
 169 \fIh_name\fP
 170 ホストの正式名 (official name)。
 171 .TP
 172 \fIh_aliases\fP
 173 ホストの別名の配列。配列は NULL ポインタで終端される。
 174 .TP
 175 \fIh_addrtype\fP
 176 アドレスのタイプ。現在はすべて \fBAF_INET\fP または \fBAF_INET6\fP である。
 177 .TP
 178 \fIh_length\fP
 179 バイト単位で表したアドレスの長さ。
 180 .TP
 181 \fIh_addr_list\fP
 182 ホストのネットワークアドレスへのポインタの配列。 配列は NULL ポインタで終端される。 ネットワークアドレスはネットワークバイトオーダ形式である。
 183 .TP
 184 \fIh_addr\fP
 185 \fIh_addr_list\fP の最初のアドレス。過去との互換性を保つためのものである。
 186 .SH 返り値
 187 \fBgethostbyname\fP()  および \fBgethostbyaddr\fP()  関数は \fIhostent\fP 構造体を返す。エラーが起こったら
 188 NULL ポインタを返す。エラーの際には \fIh_errno\fP 変数がエラーの番号を保持する。 返り値が NULL
 189 でない場合、静的データをポインタで指していることもある。 以下の「注意」を参照すること。
 190 .SH エラー
 191 \fIh_errno\fP 変数は以下の値を取りうる。
 192 .TP
 193 \fBHOST_NOT_FOUND\fP
 194 指定したホストが見つからない。
 195 .TP
 196 \fBNO_ADDRESS  または  NO_DATA\fP
 197 指定した名前は有効だが IP アドレスを持っていない。
 198 .TP
 199 \fBNO_RECOVERY\fP
 200 ネームサーバの復旧不能なエラーが起こった。
 201 .TP
 202 \fBTRY_AGAIN\fP
 203 authoritative なネームサーバで一時的なエラーが起こった。 時間をおいてもう一度試すこと。
 204 .SH ファイル
 205 .TP
 206 \fI/etc/host.conf\fP
 207 名前解決の設定ファイル
 208 .TP
 209 \fI/etc/hosts\fP
 210 ホストのデータベースファイル
 211 .TP
 212 \fI/etc/nsswitch.conf\fP
 213 ネームサービス切替設定
 214 .SH 準拠
 215 POSIX.1\-2001 では、 \fBgethostbyname\fP(), \fBgethostbyaddr\fP(), \fBsethostent\fP(),
 216 \fBendhostent\fP(), \fBgethostent\fP(), \fIh_errno\fP が規定されており、 \fBgethostbyaddr\fP()  と
 217 \fBgethostbyname\fP()  は廃止予定であるとされている。 POSIX.1\-2008 では \fBgethostbyname\fP(),
 218 \fBgethostbyaddr\fP(), \fIh_errno\fP の仕様が削除されている。 代わりに、 \fBgetaddrinfo\fP(3)  と
 219 \fBgetnameinfo\fP(3)  の使用が推奨されている。
 220 .SH 注意
 221 \fBgethostbyname\fP()  および \fBgethostbyaddr\fP()  関数は静的データへのポインタを返す。
 222 このポインタは、その後の呼び出しで上書きされるかもしれない。 \fIhostent\fP
 223 構造体はポインタを含んでいるので、構造体のコピーだけでは不十分である; より深いコピーが必要である。
 224 .LP
 225 オリジナルの BSD の実装では、 \fBgethostbyname\fP()  の \fIlen\fP 引き数は \fIint\fP であった。 SUSv2
 226 標準はバグが多く、 \fBgethostbyaddr\fP()  の \fIlen\fP パラメータを \fIsize_t\fP 型として宣言している。 (これは誤りで、
 227 \fIsize_t\fP 型ではなく \fIint\fP 型でなければならない。 POSIX.1\-2001 ではこれを \fIsocklen_t\fP
 228 としているが、これは OK。)  \fBaccept\fP(2)  も参照。
 229 .LP
 230 \fBgethostbyaddr\fP()  の BSD のプロトタイプは、最初の引き数として \fIconst char *\fP を使う。
 231 .SS "System V/POSIX 拡張"
 232 .\" e.g., Linux, FreeBSD, UnixWare, HP-UX
 233 .\" e.g., FreeBSD, AIX
 234 POSIX では、 \fBgethostent\fP()  が必須とされている。 この関数はホストデータベースの次のエントリを返す。 DNS/BIND
 235 を使う場合はあまり意味を持たないが、 ホストデータベースが 1 行ずつ読み込まれるファイルである場合は意味がある。
 236 多くのシステムでは、この名前のルーチンはファイル \fI/etc/hosts\fP を読み込む。 DNS
 237 サポートなしでライブラリがビルドされた場合にのみ利用可能である。 glibc 版は ipv6 エントリを無視する。 この関数はリエントラント
 238 (reentrant) ではなく、 glibc にはリエントラント版の \fBgethostent_r\fP()  が追加された。
 239 .SS "GNU 拡張"
 240 glibc2 には \fBgethostbyname2\fP()  もあり、 \fBgethostbyname\fP()  と同じように動作するが、
 241 こちらはアドレスが属するアドレスファミリーを指定することができる。
 242 .LP
 243 glibc2 にはリエントラントな \fBgethostent_r\fP(), \fBgethostbyaddr_r\fP(),
 244 \fBgethostbyname_r\fP()  と \fBgethostbyname2_r\fP()  もある。 呼び出し側は、成功時に結果が格納される
 245 \fIhostent\fP 構造体 \fIret\fP と、大きさ \fIbuflen\fP の一時的な作業バッファ \fIbuf\fP を提供する。
 246 コール終了後、成功した場合 \fIresult\fP は結果を指している。 エラーの場合、またはエントリが見つからなかった場合、 \fIresult\fP は
 247 NULL になる。 これらの関数は、成功した場合 0 を返し、失敗の場合は 0 以外のエラー番号を返す。
 248 これらの関数のリエントラントでないバージョンが返すエラーに加えて、 これらの関数は、 \fIbuf\fP が小さすぎた場合に \fBERANGE\fP
 249 を返す。この場合はもっと大きなバッファを用意して 関数呼び出しを再度行うべきである。 大域変数 \fIh_errno\fP
 250 は変更されないが、エラー番号を格納する変数のアドレスが \fIh_errnop\fP に渡される。
 251 .SH バグ
 252 .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973
 253 \fBgethostbyname\fP()  は、16進数表現のドット区切りの IPv4 アドレス文字列の要素を認識しない。
 254 .SH 関連項目
 255 .\" .BR getipnodebyaddr (3),
 256 .\" .BR getipnodebyname (3),
 257 \fBgetaddrinfo\fP(3), \fBgetnameinfo\fP(3), \fBinet\fP(3), \fBinet_ntop\fP(3),
 258 \fBinet_pton\fP(3), \fBresolver\fP(3), \fBhosts\fP(5), \fBnsswitch.conf\fP(5),
 259 \fBhostname\fP(7), \fBnamed\fP(8)
 260 .\" .BR resolv+ (8)