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 .\"
  44 .\" Japanese Version Copyright (c) 1998-2000 NAKANO Takeo all rights reserved.
  45 .\" Translated 1998-04-30, NAKANO Takeo <nakano@apm.seikei.ac.jp>
  46 .\" Modified 1998-12-06, NAKANO Takeo
  47 .\" Updated & Modified 1999-10-12, NAKANO Takeo
  48 .\" Updated & Modified 2001-07-01, Yuichi SATO <ysato@h4.dion.ne.jp>
  49 .\" Updated & Modified 2002-01-03, Yuichi SATO
  50 .\" Updated & Modified 2003-11-27, Yuichi SATO <ysato444@yahoo.co.jp>
  51 .\" Updated & Modified 2005-01-10, Yuichi SATO
  52 .\" Updated 2006-01-18, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  53 .\" Updated 2007-06-11, Akihiro MOTOKI, LDP v2.54
  54 .\" Updated 2008-08-08, Akihiro MOTOKI, LDP v3.05
  55 .\"
  56 .TH GETHOSTBYNAME 3 2013\-09\-04 "" "Linux Programmer's Manual"
  57 .SH 名前
  58 gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, h_errno,
  59 herror, hstrerror, gethostbyaddr_r, gethostbyname2, gethostbyname2_r,
  60 gethostbyname_r, gethostent_r \- ネットワーク上のホストのエントリを取得する
  61 .SH 書式
  62 .nf
  63 \fB#include <netdb.h>\fP
  64 \fBextern int h_errno;\fP
  65 .sp
  66 \fBstruct hostent *gethostbyname(const char *\fP\fIname\fP\fB);\fP
  67 .sp
  68 \fB#include <sys/socket.h>\fP       /* AF_INET を使う場合 */
  69 \fBstruct hostent *gethostbyaddr(const void *\fP\fIaddr\fP\fB,\fP
  70 \fB                              socklen_t \fP\fIlen\fP\fB, int \fP\fItype\fP\fB);\fP
  71 .sp
  72 \fBvoid sethostent(int \fP\fIstayopen\fP\fB);\fP
  73 .sp
  74 \fBvoid endhostent(void);\fP
  75 .sp
  76 \fBvoid herror(const char *\fP\fIs\fP\fB);\fP
  77 .sp
  78 \fBconst char *hstrerror(int \fP\fIerr\fP\fB);\fP
  79 .sp
  80 /* System V/POSIX 拡張 */
  81 .br
  82 \fBstruct hostent *gethostent(void);\fP
  83 .sp
  84 /* GNU 拡張 */
  85 .br
  86 \fBstruct hostent *gethostbyname2(const char *\fP\fIname\fP\fB, int \fP\fIaf\fP\fB);\fP
  87 .sp
  88 \fBint gethostent_r(\fP
  89 \fB        struct hostent *\fP\fIret\fP\fB, char *\fP\fIbuf\fP\fB, size_t \fP\fIbuflen\fP\fB,\fP
  90 \fB        struct hostent **\fP\fIresult\fP\fB, int *\fP\fIh_errnop\fP\fB);\fP
  91 .sp
  92 \fBint gethostbyaddr_r(const void *\fP\fIaddr\fP\fB, socklen_t \fP\fIlen\fP\fB, int \fP\fItype\fP\fB,\fP
  93 \fB        struct hostent *\fP\fIret\fP\fB, char *\fP\fIbuf\fP\fB, size_t \fP\fIbuflen\fP\fB,\fP
  94 \fB        struct hostent **\fP\fIresult\fP\fB, int *\fP\fIh_errnop\fP\fB);\fP
  95 .sp
  96 \fBint gethostbyname_r(const char *\fP\fIname\fP\fB,\fP
  97 \fB        struct hostent *\fP\fIret\fP\fB, char *\fP\fIbuf\fP\fB, size_t \fP\fIbuflen\fP\fB,\fP
  98 \fB        struct hostent **\fP\fIresult\fP\fB, int *\fP\fIh_errnop\fP\fB);\fP
  99 .sp
 100 \fBint gethostbyname2_r(const char *\fP\fIname\fP\fB, int \fP\fIaf,\fP
 101 \fB        struct hostent *\fP\fIret\fP\fB, char *\fP\fIbuf\fP\fB, size_t \fP\fIbuflen\fP\fB,\fP
 102 \fB        struct hostent **\fP\fIresult\fP\fB, int *\fP\fIh_errnop\fP\fB);\fP
 103 .fi
 104 .sp
 105 .in -4n
 106 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
 107 .in
 108 .sp
 109 .PD 0
 110 .ad l
 111 \fBgethostbyname2\fP(), \fBgethostent_r\fP(), \fBgethostbyaddr_r\fP(),
 112 \fBgethostbyname_r\fP(), \fBgethostbyname2_r\fP():
 113 .RS 4
 114 _BSD_SOURCE || _SVID_SOURCE
 115 .RE
 116
 117 \fBherror\fP(), \fBhstrerror\fP():
 118 .RS 4
 119 .TP  4
 120 Since glibc 2.12:
 121 _BSD_SOURCE || _SVID_SOURCE
 122 .TP  4
 123 From glibc 2.8 to glibc 2.11:
 124 _BSD_SOURCE || _SVID_SOURCE || _GNU_SOURCE
 125 .TP
 126 glibc 2.8 より前:
 127 なし
 128 .RE
 129
 130 \fBh_errno\fP:
 131 .RS 4
 132 .TP  4
 133 Since glibc 2.12:
 134 _BSD_SOURCE || _SVID_SOURCE ||
 135     (_POSIX_C_SOURCE < 200809L && _XOPEN_SOURCE < 700)
 136 .TP
 137 Before glibc 2.12:
 138 なし
 139 .RE
 140 .ad b
 141 .PD
 142 .SH 説明
 143 The \fBgethostbyname*\fP(), \fBgethostbyaddr*\fP(), \fBherror\fP(), and
 144 \fBhstrerror\fP()  functions are obsolete.  Applications should use
 145 \fBgetaddrinfo\fP(3), \fBgetnameinfo\fP(3), and \fBgai_strerror\fP(3)  instead.
 146
 147 \fBgethostbyname\fP()  関数は与えられたホスト名 \fIname\fP に対応する構造体 \fIhostent\fP を返す。 \fIname\fP
 148 にはホスト名、ドット区切りの IPv4 アドレス (\fBinet_addr\fP(3)  参照)、コロン区切りの IPv6 アドレス
 149 (おそらくドット区切りでも大丈夫)  のいずれかを指定する (IPv6 アドレスの記述方法については RFC\ 1884 を参考にしてほしい)。
 150 \fIname\fP が IPv4 か IPv6 のアドレスだった場合、 名前解決 (lookup) は行われない。その場合には、
 151 \fBgethostbyname\fP()  は \fIname\fP をそのまま \fIhostent\fP 構造体の \fIh_name\fP フィールドにコピーし、
 152 さらに \fIname\fP を \fIstruct in_addr\fP 形式で表したデータを \fIhostent\fP 構造体の \fIh_addr_list[0]\fP
 153 フィールドに入れて、その \fIhostent\fP 構造体を返す。 \fIname\fP がドットで終了していて、かつ環境変数 \fBHOSTALIASES\fP
 154 が設定されている場合、まず \fBHOSTALIASES\fP で指定されているエイリアスファイルから \fIname\fP のエントリが検索される
 155 (ファイルのフォーマットについては \fBhostname\fP(7)  を参照のこと)。 \fIname\fP
 156 がドットで終了していなければ、現在のドメインとその親ドメインが検索される。
 157 .PP
 158 \fBgethostbyaddr\fP()  関数は与えられたホストアドレス \fIaddr\fP (長さ \fIlen\fP、 タイプ \fItype\fP)
 159 に対応する構造体 \fIhostent\fP を返す。 用いることのできるタイプは \fBAF_INET\fP と \fBAF_INET6\fP である。
 160 ホストアドレス引き数はアドレスタイプに依存した 構造体へのポインタである。 例えば、アドレスタイプ \fBAF_INET\fP に対しては
 161 (\fBinet_addr\fP(3)  の呼び出しで得られる)  \fIstruct in_addr *\fP である。
 162 .PP
 163 \fBsethostent\fP()  関数は、ネームサーバへの接続形態を指定する。 \fIstayopen\fP が真 (1)
 164 ならば、ネームサーバへの問い合わせには、 接続された TCP ソケットを用い、連続した問い合わせの間に接続を維持する。
 165 偽ならばネームサーバへの問い合わせに UDP データグラムを用いる。
 166 .PP
 167 \fBendhostent\fP()  関数はネームサーバへの問い合わせに用いた TCP 接続の利用を終了する。
 168 .PP
 169 (廃止予定の)  \fBherror\fP()  関数は現在の \fIh_errno\fP に対応するエラーメッセージを標準エラー \fIstderr\fP に出力する。
 170 .PP
 171 (廃止予定の)  \fBhstrerror\fP()  関数はエラー番号 (通常は \fIh_errno\fP) を引き数に取り、
 172 対応するエラーメッセージ文字列を返す。
 173 .PP
 174 .\" (See
 175 .\" .BR resolv+ (8)).
 176 \fBgethostbyname\fP()  と \fBgethostbyaddr\fP()  によって実行されるドメイン名の問い合わせでは、ネームサーバ
 177 \fBnamed\fP(8)、 \fI/etc/hosts\fP のデータ行、および Network Information Service (NIS または
 178 YP)  が組み合わせて使用される。何が使用されるかは、 \fI/etc/host.conf\fP の \fIorder\fP 行の内容により決まる。
 179 デフォルトでは、まず \fBnamed\fP(8)  に問い合わせを行い、次いで \fI/etc/hosts\fP を参照する。
 180 .PP
 181 \fIhostent\fP 構造体は \fI<netdb.h>\fP で以下のように定義されている:
 182 .sp
 183 .in +4n
 184 .nf
 185 .ne 7
 186 struct hostent {
 187     char  *h_name;            /* official name of host */
 188     char **h_aliases;         /* alias list */
 189     int    h_addrtype;        /* host address type */
 190     int    h_length;          /* length of address */
 191     char **h_addr_list;       /* list of addresses */
 192 }
 193 #define h_addr h_addr_list[0] /* 過去との互換性のため */
 194 .fi
 195 .in
 196 .PP
 197 \fIhostent\fP 構造体のメンバは以下の通り。
 198 .TP
 199 \fIh_name\fP
 200 ホストの正式名 (official name)。
 201 .TP
 202 \fIh_aliases\fP
 203 ホストの別名の配列。配列は NULL ポインタで終端される。
 204 .TP
 205 \fIh_addrtype\fP
 206 アドレスのタイプ。現在はすべて \fBAF_INET\fP または \fBAF_INET6\fP である。
 207 .TP
 208 \fIh_length\fP
 209 バイト単位で表したアドレスの長さ。
 210 .TP
 211 \fIh_addr_list\fP
 212 ホストのネットワークアドレスへのポインタの配列。 配列は NULL ポインタで終端される。 ネットワークアドレスはネットワークバイトオーダ形式である。
 213 .TP
 214 \fIh_addr\fP
 215 \fIh_addr_list\fP の最初のアドレス。過去との互換性を保つためのものである。
 216 .SH 返り値
 217 \fBgethostbyname\fP()  および \fBgethostbyaddr\fP()  関数は \fIhostent\fP 構造体を返す。エラーが起こったら
 218 NULL ポインタを返す。エラーの際には \fIh_errno\fP 変数がエラーの番号を保持する。 返り値が NULL
 219 でない場合、静的データをポインタで指していることもある。 以下の「注意」を参照すること。
 220 .SH エラー
 221 \fIh_errno\fP 変数は以下の値を取りうる。
 222 .TP
 223 \fBHOST_NOT_FOUND\fP
 224 指定したホストが見つからない。
 225 .TP
 226 \fBNO_ADDRESS  または  NO_DATA\fP
 227 指定した名前は有効だが IP アドレスを持っていない。
 228 .TP
 229 \fBNO_RECOVERY\fP
 230 ネームサーバの復旧不能なエラーが起こった。
 231 .TP
 232 \fBTRY_AGAIN\fP
 233 authoritative なネームサーバで一時的なエラーが起こった。 時間をおいてもう一度試すこと。
 234 .SH ファイル
 235 .TP
 236 \fI/etc/host.conf\fP
 237 名前解決の設定ファイル
 238 .TP
 239 \fI/etc/hosts\fP
 240 ホストのデータベースファイル
 241 .TP
 242 \fI/etc/nsswitch.conf\fP
 243 ネームサービス切替設定
 244 .SH 準拠
 245 POSIX.1\-2001 では、 \fBgethostbyname\fP(), \fBgethostbyaddr\fP(), \fBsethostent\fP(),
 246 \fBendhostent\fP(), \fBgethostent\fP(), \fIh_errno\fP が規定されており、 \fBgethostbyaddr\fP()  と
 247 \fBgethostbyname\fP()  は廃止予定であるとされている。 POSIX.1\-2008 では \fBgethostbyname\fP(),
 248 \fBgethostbyaddr\fP(), \fIh_errno\fP の仕様が削除されている。 代わりに、 \fBgetaddrinfo\fP(3)  と
 249 \fBgetnameinfo\fP(3)  の使用が推奨されている。
 250 .SH 注意
 251 \fBgethostbyname\fP()  および \fBgethostbyaddr\fP()  関数は静的データへのポインタを返す。
 252 このポインタは、その後の呼び出しで上書きされるかもしれない。 \fIhostent\fP
 253 構造体はポインタを含んでいるので、構造体のコピーだけでは不十分である; より深いコピーが必要である。
 254 .LP
 255 オリジナルの BSD の実装では、 \fBgethostbyname\fP()  の \fIlen\fP 引き数は \fIint\fP であった。 SUSv2
 256 標準はバグが多く、 \fBgethostbyaddr\fP()  の \fIlen\fP パラメータを \fIsize_t\fP 型として宣言している。 (これは誤りで、
 257 \fIsize_t\fP 型ではなく \fIint\fP 型でなければならない。 POSIX.1\-2001 ではこれを \fIsocklen_t\fP
 258 としているが、これは OK。)  \fBaccept\fP(2)  も参照。
 259 .LP
 260 \fBgethostbyaddr\fP()  の BSD のプロトタイプは、最初の引き数として \fIconst char\ *\fP を使う。
 261 .SS "System V/POSIX 拡張"
 262 .\" e.g., Linux, FreeBSD, UnixWare, HP-UX
 263 .\" e.g., FreeBSD, AIX
 264 POSIX では、 \fBgethostent\fP()  が必須とされている。 この関数はホストデータベースの次のエントリを返す。 DNS/BIND
 265 を使う場合はあまり意味を持たないが、 ホストデータベースが 1 行ずつ読み込まれるファイルである場合は意味がある。
 266 多くのシステムでは、この名前のルーチンはファイル \fI/etc/hosts\fP を読み込む。 DNS
 267 サポートなしでライブラリがビルドされた場合にのみ利用可能である。 glibc 版は ipv6 エントリを無視する。 この関数はリエントラント
 268 (reentrant) ではなく、 glibc にはリエントラント版の \fBgethostent_r\fP()  が追加された。
 269 .SS "GNU 拡張"
 270 glibc2 には \fBgethostbyname2\fP()  もあり、 \fBgethostbyname\fP()  と同じように動作するが、
 271 こちらはアドレスが属するアドレスファミリーを指定することができる。
 272 .LP
 273 glibc2 にはリエントラントな \fBgethostent_r\fP(), \fBgethostbyaddr_r\fP(),
 274 \fBgethostbyname_r\fP()  と \fBgethostbyname2_r\fP()  もある。 呼び出し側は、成功時に結果が格納される
 275 \fIhostent\fP 構造体 \fIret\fP と、大きさ \fIbuflen\fP の一時的な作業バッファ \fIbuf\fP を提供する。
 276 コール終了後、成功した場合 \fIresult\fP は結果を指している。 エラーの場合、またはエントリが見つからなかった場合、 \fIresult\fP は
 277 NULL になる。 これらの関数は、成功した場合 0 を返し、失敗の場合は 0 以外のエラー番号を返す。
 278 これらの関数のリエントラントでないバージョンが返すエラーに加えて、 これらの関数は、 \fIbuf\fP が小さすぎた場合に \fBERANGE\fP
 279 を返す。この場合はもっと大きなバッファを用意して 関数呼び出しを再度行うべきである。 大域変数 \fIh_errno\fP
 280 は変更されないが、エラー番号を格納する変数のアドレスが \fIh_errnop\fP に渡される。
 281 .SH バグ
 282 .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973
 283 \fBgethostbyname\fP()  は、16進数表現のドット区切りの IPv4 アドレス文字列の要素を認識しない。
 284 .SH 関連項目
 285 .\" .BR getipnodebyaddr (3),
 286 .\" .BR getipnodebyname (3),
 287 .\" .BR resolv+ (8)
 288 \fBgetaddrinfo\fP(3), \fBgetnameinfo\fP(3), \fBinet\fP(3), \fBinet_ntop\fP(3),
 289 \fBinet_pton\fP(3), \fBresolver\fP(3), \fBhosts\fP(5), \fBnsswitch.conf\fP(5),
 290 \fBhostname\fP(7), \fBnamed\fP(8)
 291 .SH この文書について
 292 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.54 の一部
 293 である。プロジェクトの説明とバグ報告に関する情報は
 294 http://www.kernel.org/doc/man\-pages/ に書かれている。