draft/man3/getipnodebyname.3

   1 .\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com>
   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: RFC 2553
  24 .\"
  25 .\" Japanese Version Copyright (c) 2001 NAKANO Takeo all rights reserved.
  26 .\" Translated Sun Jan 14 2001 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
  27 .\" Updated Tue Nov 26 2002 by Kentaro Shirakata <argrath@ub32.org>
  28 .\"
  29 .\"WORD:        null pointer    ヌル・ポインター
  30 .\"
  31 .TH GETIPNODEBYNAME 3 2010-09-04 "Linux" "Linux Programmer's Manual"
  32 .\"O .SH NAME
  33 .\"O getipnodebyname, getipnodebyaddr, freehostent \- get network
  34 .\"O hostnames and addresses
  35 .SH 名前
  36 getipnodebyname, getipnodebyaddr, freehostent \- ネットワークホストの名前とアドレスの取得
  37 .\"O .SH SYNOPSIS
  38 .SH 書式
  39 .nf
  40 .B #include <sys/types.h>
  41 .B #include <sys/socket.h>
  42 .B #include <netdb.h>
  43 .sp
  44 .BI "struct hostent *getipnodebyname(const char *" name ", int " af ,
  45 .BI "                                int " flags ", int *" error_num );
  46 .sp
  47 .BI "struct hostent *getipnodebyaddr(const void *" addr ", size_t " len ,
  48 .BI "                                int " af ", int *" "error_num" );
  49 .sp
  50 .BI "void freehostent(struct hostent *" "ip" );
  51 .fi
  52 .\"O .SH DESCRIPTION
  53 .SH 説明
  54 .\"O These functions are deprecated (and unavailable in glibc).
  55 .\"O Use
  56 .\"O .BR getaddrinfo (3)
  57 .\"O and
  58 .\"O .BR getnameinfo (3)
  59 .\"O instead.
  60 これらの関数は非推奨である (glibc では利用できない)。
  61 代わりに
  62 .BR getaddrinfo (3)
  63 と
  64 .BR getnameinfo (3)
  65 を使うこと。
  66 .LP
  67 .\"O The
  68 .\"O .BR getipnodebyname ()
  69 .\"O and
  70 .\"O .BR getipnodebyaddr ()
  71 .\"O functions return the names and addresses of a network host.
  72 .\"O These functions return a pointer to the
  73 .\"O following structure:
  74 .BR getipnodebyname ()
  75 と
  76 .BR getipnodebyaddr ()
  77 は、ネットワークホストの名前とアドレスを返す。
  78 これらの関数は、以下の構造体へのポインタを返す。
  79 .sp
  80 .in +4n
  81 .nf
  82 struct hostent {
  83     char  *h_name;
  84     char **h_aliases;
  85     int    h_addrtype;
  86     int    h_length;
  87     char **h_addr_list;
  88 };
  89 .fi
  90 .in
  91 .PP
  92 .\"O These functions replace the
  93 .\"O .BR gethostbyname (3)
  94 .\"O and
  95 .\"O .BR gethostbyaddr (3)
  96 .\"O functions, which could only access the IPv4 network address family.
  97 .\"O The
  98 .\"O .BR getipnodebyname ()
  99 .\"O and
 100 .\"O .BR getipnodebyaddr ()
 101 .\"O functions can access multiple network address families.
 102 これらの関数は、 IPv4 ネットワークアドレスファミリにしかアクセスできない
 103 .BR gethostbyname (3)
 104 や
 105 .BR gethostbyaddr (3)
 106 を置き換えるものである。
 107 .BR getipnodebyname ()
 108 関数と
 109 .BR getipnodebyaddr ()
 110 関数は複数のネットワークアドレスファミリーにアクセス可能になっている。
 111 .PP
 112 .\"O Unlike the
 113 .\"O .B gethostby
 114 .\"O functions,
 115 .\"O these functions return pointers to dynamically allocated memory.
 116 .\"O The
 117 .\"O .BR freehostent ()
 118 .\"O function is used to release the dynamically allocated memory
 119 .\"O after the caller no longer needs the
 120 .\"O .I hostent
 121 .\"O structure.
 122 これらの関数は、
 123 .B gethostby
 124 の関数群と異なり、動的に割り当てられたメモリへのポインタを返す。
 125 呼び出し元がこれらの
 126 .I hostent
 127 構造体を必要としなくなった後は、
 128 .BR freehostent ()
 129 関数を用いれば動的な割り当てメモリを解放できる。
 130 .\"O .SS getipnodebyname() arguments
 131 .SS getipnodebyname() の引き数
 132 .\"O The
 133 .\"O .BR getipnodebyname ()
 134 .\"O function
 135 .\"O looks up network addresses for the host
 136 .\"O specified by the
 137 .\"O .I name
 138 .\"O argument.
 139 .\"O The
 140 .\"O .I af
 141 .\"O argument specifies one of the following values:
 142 .BR getipnodebyname ()
 143 関数は
 144 .I name
 145 引き数で指定されたホストのネットワークアドレスを引く。
 146 .I af
 147 引き数には以下の値のいずれかを指定する。
 148 .TP
 149 .B AF_INET
 150 .\"O The
 151 .\"O .I name
 152 .\"O argument points to a dotted-quad IPv4 address or a name
 153 .\"O of an IPv4 network host.
 154 .I name
 155 引き数は、ドットで 4 つに区切られた IPv4 アドレスか、
 156 IPv4 ネットワークホストの名前へのポインタである。
 157 .TP
 158 .B AF_INET6
 159 .\"O The
 160 .\"O .I name
 161 .\"O argument points to a hexadecimal IPv6 address or a name
 162 .\"O of an IPv6 network host.
 163 .I name
 164 引き数は、16 進の IPv6 アドレスか、
 165 IPv6 ネットワークホストの名前へのポインタである。
 166 .PP
 167 .\"O The
 168 .\"O .I flags
 169 .\"O argument specifies additional options.
 170 .\"O More than one option can be specified by bitwise OR-ing
 171 .\"O them together.
 172 .\"O .I flags
 173 .\"O should be set to 0
 174 .\"O if no options are desired.
 175 .I flags
 176 パラメータには追加のオプションを指定する。
 177 複数のフラグを指定するには、それらのビット単位の OR をとって指定すればよい。
 178 オプションをひとつも指定したくないときには、
 179 .I flags
 180 に 0 を設定する必要がある。
 181 .TP
 182 .B AI_V4MAPPED
 183 .\"O This flag is used with
 184 .\"O .B AF_INET6
 185 .\"O to request a query for IPv4 addresses instead of
 186 .\"O IPv6 addresses; the IPv4 addresses will
 187 .\"O be mapped to IPv6 addresses.
 188 このフラグは
 189 .B AF_INET6
 190 と共に用いられ、IPv6 アドレスの代わりに IPv4 アドレスを問い合わせる。
 191 問い合わせる IPv4 アドレスは IPv6 アドレスにマップされる。
 192 .TP
 193 .B AI_ALL
 194 .\"O This flag is used with
 195 .\"O .B AI_V4MAPPED
 196 .\"O to request a query for both IPv4 and IPv6 addresses.
 197 .\"O Any IPv4 address found will be mapped to an IPv6 address.
 198 このフラグは
 199 .B AI_V4MAPPED
 200 と共に用いられ、IPv4 アドレスと IPv6 アドレスの両方を問い合わせる。
 201 見つかった IPv4 アドレスは、すべて IPv6 アドレスにマップされる。
 202 .TP
 203 .B AI_ADDRCONFIG
 204 .\"O This flag is used with
 205 .\"O .B AF_INET6
 206 .\"O to
 207 .\"O further request that queries for IPv6 addresses should not be made unless
 208 .\"O the system has at least one IPv6 address assigned to a network interface,
 209 .\"O and that queries for IPv4 addresses should not be made unless the
 210 .\"O system has at least one IPv4 address assigned to a network interface.
 211 .\"O This flag may be used by itself or with the
 212 .\"O .B AI_V4MAPPED
 213 .\"O flag.
 214 このフラグは
 215 .B AF_INET6
 216 と共に用いられ、
 217 IPv6 が割り当てられたネットワークインターフェースが
 218 システムにひとつもなければ IPv6 アドレスの問い合わせを行わず、
 219 IPv4 が割り当てられたネットワークインターフェースが
 220 システムにひとつもなければ IPv4 アドレスの問い合わせを行わないように要求する。
 221 このフラグは単独でも、あるいは
 222 .B AI_V4MAPPED
 223 フラグと共にでも用いることができる。
 224 .TP
 225 .B AI_DEFAULT
 226 .\"O This flag is equivalent to
 227 .\"O .BR "(AI_ADDRCONFIG | AI_V4MAPPED)" .
 228 このフラグは
 229 .BR (AI_ADDRCONFIG | AI_V4MAPPED)
 230 と等価である。
 231 .\"O .SS getipnodebyaddr() arguments
 232 .SS "getipnodebyaddr() の引き数"
 233 .\"O The
 234 .\"O .BR getipnodebyaddr ()
 235 .\"O function
 236 .\"O looks up the name of the host whose
 237 .\"O network address is
 238 .\"O specified by the
 239 .\"O .I addr
 240 .\"O argument.
 241 .\"O The
 242 .\"O .I af
 243 .\"O argument specifies one of the following values:
 244 .BR getipnodebyaddr ()
 245 関数は、ネットワークアドレスが
 246 .I addr
 247 引き数で指定されたホストの名前を引く。
 248 .I af
 249 引き数には以下の値のいずれかを指定する。
 250 .TP
 251 .B AF_INET
 252 .\"O The
 253 .\"O .I addr
 254 .\"O argument points to a
 255 .\"O .I struct in_addr
 256 .\"O and
 257 .\"O .I len
 258 .\"O must be set to
 259 .\"O .IR "sizeof(struct in_addr)" .
 260 .I addr
 261 引き数は
 262 .I struct in_addr
 263 へのポインターであり、
 264 .I len
 265 引き数は
 266 .I sizeof(struct in_addr)
 267 に設定しなければならない。
 268 .TP
 269 .B AF_INET6
 270 .\"O The
 271 .\"O .I addr
 272 .\"O argument points to a
 273 .\"O .I struct in6_addr
 274 .\"O and
 275 .\"O .I len
 276 .\"O must be set to
 277 .\"O .IR "sizeof(struct in6_addr)" .
 278 .I addr
 279 引き数は
 280 .I struct in6_addr
 281 へのポインターであり、
 282 .I len
 283 引き数は
 284 .I sizeof(struct in6_addr)
 285 に設定しなければならない。
 286 .\"O .SH "RETURN VALUE"
 287 .SH 返り値
 288 .\"O A NULL pointer is returned if an error occurred, and
 289 .\"O .I error_num
 290 .\"O will contain an error code from the following list:
 291 エラーが起こるとヌル・ポインターが返され、
 292 .I error_num
 293 に以下にリストされたエラーコードのいずれかが設定される。
 294 .TP
 295 .B HOST_NOT_FOUND
 296 .\"O The hostname or network address was not found.
 297 ホスト名またはネットワークアドレスが見つからなかった。
 298 .TP
 299 .B NO_ADDRESS
 300 .\"O The domain name server recognized the network address or name,
 301 .\"O but no answer was returned.
 302 .\"O This can happen if the network host has only IPv4 addresses and
 303 .\"O a request has been made for IPv6 information only, or vice versa.
 304 ドメインネームサーバーは
 305 そのネットワークアドレスまたはネットワーク名を認識したが、
 306 返事が返ってこなかった。原因としては、
 307 例えば IPv4 アドレスしか持たないネットワークホストに対して
 308 IPv6 の情報の問い合わせが行われた (およびその逆) などが考えられる。
 309 .TP
 310 .B NO_RECOVERY
 311 .\"O The domain name server returned a permanent failure response.
 312 ドメインネームサーバーから恒久的な失敗 (permanent failure)
 313 を意味する返事が返された。
 314 .TP
 315 .B TRY_AGAIN
 316 .\"O The domain name server returned a temporary failure response.
 317 .\"O You might have better luck next time.
 318 ネームサーバーから一時的な失敗 (temporary failure)
 319 を意味する返事が返された。次にはもうちょっと運が必要かも。
 320 .PP
 321 .\"O A successful query returns a pointer to a
 322 .\"O .I hostent
 323 .\"O structure that contains the following fields:
 324 問い合わせに成功すると、
 325 .I hostent
 326 構造体へのポインタが返される。
 327 この構造体は以下のフィールドからなる。
 328 .TP
 329 .I h_name
 330 .\"O This is the official name of this network host.
 331 これはこのネットワークホストのオフィシャルな名前である。
 332 .TP
 333 .I h_aliases
 334 .\"O This is an array of pointers to unofficial aliases for the same host.
 335 .\"O The array is terminated by a NULL pointer.
 336 これは、そのホストのオフィシャルでない別名へのポインターの配列である。
 337 配列はヌル・ポインターで終端する。
 338 .TP
 339 .I h_addrtype
 340 .\"O This is a copy of the
 341 .\"O .I af
 342 .\"O argument to
 343 .\"O .BR getipnodebyname ()
 344 .\"O or
 345 .\"O .BR getipnodebyaddr ().
 346 .\"O .I h_addrtype
 347 .\"O will always be
 348 .\"O .B AF_INET
 349 .\"O if the
 350 .\"O .I af
 351 .\"O argument was
 352 .\"O .BR AF_INET .
 353 .\"O .I h_addrtype
 354 .\"O will always be
 355 .\"O .B AF_INET6
 356 .\"O if the
 357 .\"O .I af
 358 .\"O argument was
 359 .\"O .BR AF_INET6 .
 360 これは
 361 .BR getipnodebyname ()
 362 または
 363 .BR getipnodebyaddr ()
 364 に与えられた
 365 .I af
 366 引き数のコピーである。
 367 .I af
 368 引き数が
 369 .B AF_INET
 370 なら
 371 .I h_addrtype
 372 は常に
 373 .B AF_INET
 374 になり、
 375 .I af
 376 引き数が
 377 .B AF_INET6
 378 なら
 379 .I h_addrtype
 380 も常に
 381 .B AF_INET6
 382 になる。
 383 .TP
 384 .I h_length
 385 .\"O This field will be set to
 386 .\"O .I sizeof(struct in_addr)
 387 .\"O if
 388 .\"O .I h_addrtype
 389 .\"O is
 390 .\"O .BR AF_INET ,
 391 .\"O and to
 392 .\"O .I sizeof(struct in6_addr)
 393 .\"O if
 394 .\"O .I h_addrtype
 395 .\"O is
 396 .\"O .BR AF_INET6 .
 397 このフィールドは、
 398 .I h_addrtype
 399 が
 400 .B AF_INET
 401 なら
 402 .I sizeof(struct in_addr)
 403 に、
 404 .I h_addrtype
 405 が
 406 .B AF_INET6
 407 なら
 408 .I sizeof(struct in6_addr)
 409 に設定される。
 410 .TP
 411 .I h_addr_list
 412 .\"O This is an array of one or more pointers to network address structures for the
 413 .\"O network host.
 414 .\"O The array is terminated by a NULL pointer.
 415 これはひとつ以上のポインターの配列で、
 416 それぞれのポインターは、
 417 そのネットワークホストに対応するネットワークアドレス構造体を指す。
 418 この配列はヌル・ポインターで終端する。
 419 .\"O .SH "CONFORMING TO"
 420 .SH 準拠
 421 RFC\ 2553.
 422 .\"O .\" Not in POSIX.1-2001.
 423 .\" POSIX.1-2001 にはない。
 424 .\"O .SH NOTES
 425 .SH 注意
 426 .\"O These functions were present in glibc 2.1.91-95, but were
 427 .\"O removed again.
 428 .\"O Several UNIX-like systems support them, but all
 429 .\"O call them deprecated.
 430 これらの関数は glibc 2.1.91-95 に存在したが、再び削除された。
 431 いくつかの UNIX 風システムはこれらの関数に対応しているが、
 432 これらの関数は全て推奨されない。
 433 .\"O .SH "SEE ALSO"
 434 .SH 関連項目
 435 .BR getaddrinfo (3),
 436 .BR getnameinfo (3),
 437 .BR inet_ntop (3),
 438 .BR inet_pton (3)