release/man3/gethostbyname.3

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