draft/man3/getnameinfo.3

   1 .\" This page is in the public domain.
   2 .\" Almost all details are from RFC 2553.
   3 .\"
   4 .\" 2004-12-14, mtk, Added EAI_OVERFLOW error
   5 .\" 2004-12-14 Fixed description of error return
   6 .\"
   7 .\" Translated 2005-02-26, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
   8 .\" Updated 2007-01-07, Akihiro MOTOKI, LDP v2.43
   9 .\" Updated 2008-08-11, Akihiro MOTOKI, LDP v3.05
  10 .\" Updated 2010-04-10, Akihiro MOTOKI, LDP v3.24
  11 .\"
  12 .TH GETNAMEINFO 3 2009-12-03 "GNU" "Linux Programmer's Manual"
  13 .\"O .SH NAME
  14 .SH 名前
  15 .\"O getnameinfo \- address-to-name translation in protocol-independent manner
  16 getnameinfo \- アドレスから名前への変換をプロトコルに依存しないかたちで行う
  17 .\"O .SH SYNOPSIS
  18 .SH 書式
  19 .nf
  20 .B #include <sys/socket.h>
  21 .B #include <netdb.h>
  22 .sp
  23 .BI "int getnameinfo(const struct sockaddr *" "sa" ", socklen_t " "salen" ,
  24 .BI "                char *" "host" ", size_t " "hostlen" ,
  25 .BI "                char *" "serv" ", size_t " "servlen" ", int " "flags" );
  26 .fi
  27 .sp
  28 .in -4n
  29 .\"O Feature Test Macro Requirements for glibc (see
  30 .\"O .BR feature_test_macros (7)):
  31 glibc 向けの機能検査マクロの要件
  32 .RB ( feature_test_macros (7)
  33 参照):
  34 .ad l
  35 .in
  36 .sp
  37 .BR getnameinfo ():
  38 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
  39 .ad b
  40 .\"O .SH DESCRIPTION
  41 .SH 説明
  42 .\"O The
  43 .\"O .BR getnameinfo ()
  44 .\"O function is the inverse of
  45 .\"O .BR getaddrinfo (3):
  46 .\"O it converts a socket address to a corresponding host and service,
  47 .\"O in a protocol-independent manner.
  48 .\"O It combines the functionality of
  49 .\"O .BR gethostbyaddr (3)
  50 .\"O and
  51 .\"O .BR getservbyport (3),
  52 .\"O but unlike those functions,
  53 .\"O .BR getaddrinfo (3)
  54 .\"O is reentrant and allows programs to eliminate
  55 .\"O IPv4-versus-IPv6 dependencies.
  56 .BR getnameinfo ()
  57 関数は、
  58 .BR getaddrinfo (3)
  59 の逆の動作を行う。つまり、プロトコルに依存しないかたちで
  60 ソケットアドレスから対応するホスト名とサービスへの変換を行う。
  61 この関数は
  62 .BR gethostbyaddr (3)
  63 と
  64 .BR getservbyport (3)
  65 の機能を一つにしたものだが、
  66 これらの関数と違い、
  67 .BR getnameinfo (3)
  68 はリエントラントであり、IPv4 と IPv6 の差分に依存しないかたちで
  69 プログラムを書くことができる。
  70
  71 .\"O The
  72 .\"O .I sa
  73 .\"O argument is a pointer to a generic socket address structure
  74 .\"O (of type
  75 .\"O .I sockaddr_in
  76 .\"O or
  77 .\"O .IR sockaddr_in6 )
  78 .\"O of size
  79 .\"O .I salen
  80 .\"O that holds the input IP address and port number.
  81 .I sa
  82 引き数は、
  83 IP アドレスとポート番号の情報を保持している
  84 汎用的なソケットアドレス構造体
  85 .RI ( sockaddr_in
  86 型または
  87 .I sockaddr_in6
  88 型) へのポインタである。
  89 .I salen
  90 は
  91 .I sa
  92 のサイズである。
  93 .\"O The arguments
  94 .\"O .I host
  95 .\"O and
  96 .\"O .I serv
  97 .\"O are pointers to caller-allocated buffers (of size
  98 .\"O .I hostlen
  99 .\"O and
 100 .\"O .I servlen
 101 .\"O respectively) into which
 102 .\"O .BR getnameinfo ()
 103 .\"O places null-terminated strings containing the host and
 104 .\"O service names respectively.
 105 .I host
 106 と
 107 .I serv
 108 引き数は、(それぞれサイズが
 109 .I hostlen
 110 と
 111 .I servlen
 112 の) 呼び出し側で確保されたバッファへのポインタであり、
 113 ホスト名とサービス名を含む NULL 終端された文字列が
 114 それぞれのバッファに格納される。
 115
 116 .\"O The caller can specify that no hostname (or no service name)
 117 .\"O is required by providing a NULL
 118 .\"O .I host
 119 .\"O (or
 120 .\"O .IR serv )
 121 .\"O argument or a zero
 122 .\"O .I hostlen
 123 .\"O (or
 124 .\"O .IR servlen )
 125 .\"O argument.
 126 .\"O However, at least one of hostname or service name
 127 .\"O must be requested.
 128 ホスト名が不要であることをこの関数に伝えるには、
 129 .I host
 130 に NULL を指定するか、
 131 .I hostlen
 132 に 0 を指定する。同様に、サービス名が不要な場合は、
 133 .I serv
 134 に NULL を指定するか、
 135 .I servlen
 136 に 0 を指定する。
 137 しかし、ホスト名とサービス名の両方を不要だと指定することはできない
 138 (いずれか一方は要求すること)。
 139
 140 .\"O The
 141 .\"O .I flags
 142 .\"O argument modifies the behavior of
 143 .\"O .BR getnameinfo ()
 144 .\"O as follows:
 145 .I flags
 146 引き数で
 147 .BR getnameinfo ()
 148 の動作を変えることができる。指定できる値は以下の通り:
 149 .TP
 150 .B NI_NAMEREQD
 151 .\"O If set, then an error is returned if the hostname cannot be determined.
 152 指定すると、ホスト名が決定できなかった場合にエラーを返す。
 153 .TP
 154 .B NI_DGRAM
 155 .\"O If set, then the service is datagram (UDP) based rather than
 156 .\"O stream (TCP) based.
 157 .\"O This is required for the few ports (512-514)
 158 .\"O that have different services for UDP and TCP.
 159 指定すると、ストリームベース (TCP) でなくデータグラムベース (UDP)
 160 のサービスを対象にする。数は少ないが、
 161 UDP と TCP で違うサービスを提供しているポート
 162 (512-514) に対して必要となる。
 163 .TP
 164 .B NI_NOFQDN
 165 .\"O If set, return only the hostname part of the fully qualified domain name
 166 .\"O for local hosts.
 167 指定すると、ローカルなホストには fully qualified domain name (FQDN) の
 168 ホスト名の部分のみを返す。
 169 .TP
 170 .B NI_NUMERICHOST
 171 .\"O If set, then the numeric form of the hostname is returned.
 172 .\"O .\" For example, by calling
 173 .\"O .\" .BR inet_ntop ()
 174 .\"O .\" instead of
 175 .\"O .\" .BR gethostbyaddr ().
 176 .\"O (When not set, this will still happen in case the node's name
 177 .\"O cannot be determined.)
 178 指定すると、数値形式のホスト名が返される。
 179 .\" 例えば
 180 .\" .BR gethostbyaddr ()
 181 .\" の代わりに
 182 .\" .BR inet_ntop ()
 183 .\" を呼ぶ
 184 (指定しなくても、ノードの名前が決定できない場合は数値形式が返ることがある)。
 185 .\" POSIX.1-2003 has NI_NUMERICSCOPE, but glibc doesn't have it.
 186 .TP
 187 .B NI_NUMERICSERV
 188 .\"O If set, then the numeric form of the service address is returned.
 189 .\"O (When not set, this will still happen in case the service's name
 190 .\"O cannot be determined.)
 191 指定すると、数値形式のサービス名 (例えばポート番号) が返される
 192 (指定しなくても、サービス名が決定できない場合は数値形式が返ることがある)。
 193 .\"O .SS "Extensions to getaddrinfo() for Internationalized Domain Names"
 194 .SS "国際化ドメイン名のための getnameinfo() の拡張"
 195 .\"O motoki: 原文の getaddrinfo() は getnameinfo() の間違いと思われる。
 196 .PP
 197 .\"O Starting with glibc 2.3.4,
 198 .\"O .BR getnameinfo ()
 199 .\"O has been extended to selectively allow
 200 .\"O hostnames to be transparently converted to and from the
 201 .\"O Internationalized Domain Name (IDN) format (see RFC 3490,
 202 .\"O .IR "Internationalizing Domain Names in Applications (IDNA)" ).
 203 .\"O Three new flags are defined:
 204 glibc 2.3.4 から、
 205 .BR getnameinfo ()
 206 に拡張が行われ、ホスト名と
 207 国際化ドメイン名 (Internationalized Domain Name; IDN) 形式との間で
 208 透過的な変換ができるようになっている
 209 (IDN 形式については RFC 3490 の
 210 .I "Internationalizing Domain Names in Applications (IDNA)"
 211 を参照)。3つのフラグが新たに定義されている:
 212 .TP
 213 .B NI_IDN
 214 .\"O If this flag is used, then the name found in the lookup process is
 215 .\"O converted from IDN format to the locale's encoding if necessary.
 216 .\"O ASCII-only names are not affected by the conversion, which
 217 .\"O makes this flag usable in existing programs and environments.
 218 このフラグを指定すると、必要であれば、検索処理で見つかった名前は
 219 IDN 形式からロケールに応じた符号化形式に変換される。
 220 ASCII 文字だけの名前はこの変換では影響を受けない。このため、
 221 既存のプログラムや環境でこのフラグを使うことができる。
 222 .TP
 223 .BR NI_IDN_ALLOW_UNASSIGNED ", " NI_IDN_USE_STD3_ASCII_RULES
 224 .\"O Setting these flags will enable the
 225 .\"O IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and
 226 .\"O IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3
 227 .\"O conforming host name)
 228 .\"O flags respectively to be used in the IDNA handling.
 229 これらのフラグをセットすると、IDNA 処理で使用されるフラグ
 230 IDNA_ALLOW_UNASSIGNED (未割り当ての Unicode のコードポイントを許容) と
 231 IDNA_USE_STD3_ASCII_RULES (出力が STD3 準拠のホスト名かをチェックする)
 232 がそれぞれ有効になる。
 233 .\"O .SH "RETURN VALUE"
 234 .SH 返り値
 235 .\" FIXME glibc defines the following additional errors, some which
 236 .\" can probably be returned by getnameinfo(); they need to
 237 .\" be documented.
 238 .\" #ifdef __USE_GNU
 239 .\" #define EAI_INPROGRESS  -100  /* Processing request in progress.  */
 240 .\" #define EAI_CANCELED    -101  /* Request canceled.  */
 241 .\" #define EAI_NOTCANCELED -102  /* Request not canceled.  */
 242 .\" #define EAI_ALLDONE     -103  /* All requests done.  */
 243 .\" #define EAI_INTR        -104  /* Interrupted by a signal.  */
 244 .\" #define EAI_IDN_ENCODE  -105  /* IDN encoding failed.  */
 245 .\" #endif
 246 .\"O On success 0 is returned, and node and service names, if requested,
 247 .\"O are filled with null-terminated strings, possibly truncated to fit
 248 .\"O the specified buffer lengths.
 249 .\"O On error one of the following nonzero error codes is returned:
 250 成功すると 0 が返り、(要求されていれば) ノードとサービスの名前が
 251 NULL 終端された文字列の形式でそれぞれの指定バッファに返される
 252 (バッファの長さにあうように縮められるかもしれない)。
 253 エラーの場合は、以下の 0 以外のエラー・コードが返される:
 254 .TP
 255 .B EAI_AGAIN
 256 .\"O The name could not be resolved at this time.
 257 .\"O Try again later.
 258 指定された名前が現時点では解決できなかった。
 259 後で再試行してみること。
 260 .TP
 261 .B EAI_BADFLAGS
 262 .\"O The
 263 .\"O .I flags
 264 .\"O argument has an invalid value.
 265 .I flags
 266 引き数に不正な値が与えられた。
 267 .TP
 268 .B EAI_FAIL
 269 .\"O A nonrecoverable error occurred.
 270 回復できないエラーが発生した。
 271 .TP
 272 .B EAI_FAMILY
 273 .\"O The address family was not recognized,
 274 .\"O or the address length was invalid for the specified family.
 275 指定したアドレスファミリーが認識できなかった。
 276 あるいはアドレスの長さが指定されたファミリーに合うものでなかった。
 277 .TP
 278 .B EAI_MEMORY
 279 .\"O Out of memory.
 280 メモリが足りない。
 281 .TP
 282 .B EAI_NONAME
 283 .\"O The name does not resolve for the supplied arguments.
 284 .\"O .B NI_NAMEREQD
 285 .\"O is set and the host's name cannot be located,
 286 .\"O or neither hostname nor service name were requested.
 287 与えられたパラメータでは名前が解決できない。
 288 .B NI_NAMEREQD
 289 が設定されていたがホスト名が決定できなかったか、
 290 ホスト名もサービス名も要求されなかった。
 291 .TP
 292 .B EAI_OVERFLOW
 293 .\"O The buffer pointed to by
 294 .\"O .I host
 295 .\"O or
 296 .\"O .I serv
 297 .\"O was too small.
 298 .I host
 299 または
 300 .I serv
 301 が指しているバッファが小さすぎた。
 302 .TP
 303 .B EAI_SYSTEM
 304 .\"O A system error occurred.
 305 .\"O The error code can be found in
 306 .\"O .IR errno .
 307 システムエラーが起った。
 308 エラーコードは
 309 .I errno
 310 に設定される。
 311 .PP
 312 .\"O The
 313 .\"O .BR gai_strerror (3)
 314 .\"O function translates these error codes to a human readable string,
 315 .\"O suitable for error reporting.
 316 .BR gai_strerror (3)
 317 関数を使うと、これらのエラー・コードを、エラー・レポートに適した
 318 人間が読みやすい文字列に翻訳してくれる。
 319 .\"O .SH FILES
 320 .SH ファイル
 321 /etc/hosts
 322 .br
 323 /etc/nsswitch.conf
 324 .br
 325 /etc/resolv.conf
 326 .\"O .SH VERSIONS
 327 .SH バージョン
 328 .\"O .BR getnameinfo ()
 329 .\"O is provided in glibc since version 2.1.
 330 .BR getnameinfo ()
 331 は、glibc バージョン 2.1 以降で提供されている。
 332 .\"O .SH "CONFORMING TO"
 333 .SH 準拠
 334 RFC\ 2553, POSIX.1-2001.
 335 .\"O .SH NOTES
 336 .SH 注意
 337 .\"O In order to assist the programmer in choosing reasonable sizes
 338 .\"O for the supplied buffers,
 339 .\"O .I <netdb.h>
 340 .\"O defines the constants
 341 適切なバッファサイズを選択できるように、
 342 .I <netdb.h>
 343 に以下の定数が定義されている。
 344 .in +4n
 345 .nf
 346
 347 #define NI_MAXHOST      1025
 348 #define NI_MAXSERV      32
 349 .fi
 350 .in
 351
 352 .\"O Since glibc 2.8,
 353 .\"O these definitions are exposed only if one of the feature test macros
 354 .\"O .BR _BSD_SOURCE ,
 355 .\"O .BR _SVID_SOURCE ,
 356 .\"O or
 357 .\"O .BR _GNU_SOURCE
 358 .\"O is defined.
 359 glibc 2.8 以降では、機能検査マクロ
 360 .BR _BSD_SOURCE ,
 361 .BR _SVID_SOURCE ,
 362 .BR _GNU_SOURCE
 363 のいずれかが定義された場合にのみ、これらの定義が公開される。
 364 .PP
 365 .\"O The former is the constant
 366 .\"O .B MAXDNAME
 367 .\"O in recent versions of BIND's
 368 .\"O .I <arpa/nameser.h>
 369 .\"O header file.
 370 .\"O The latter is a guess based on the services listed
 371 .\"O in the current Assigned Numbers RFC.
 372 前者は、最近のバージョンの BIND のヘッダファイル
 373 .I <arpa/nameser.h>
 374 中の定数
 375 .B MAXDNAME
 376 と同じ値である。
 377 後者は、割り当て済の数値について記した現在の RFC に
 378 列挙されてサービスから推量した値である。
 379 .\"O .SH EXAMPLE
 380 .SH 例
 381 .\"O The following code tries to get the numeric hostname and service name,
 382 .\"O for a given socket address.
 383 .\"O Note that there is no hardcoded reference to
 384 .\"O a particular address family.
 385 以下のコードは、指定されたソケットアドレスに対する
 386 ホストとサービスの数値表式を取得しようと試みる。
 387 特定のアドレスファミリーに対する参照情報は
 388 一切ハードコードされていないことに着目してほしい。
 389
 390 .in +4n
 391 .nf
 392 struct sockaddr *sa;    /* input */
 393 socklen_t len;          /* input */
 394 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
 395
 396 if (getnameinfo(sa, len, hbuf, sizeof(hbuf), sbuf,
 397             sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
 398     printf("host=%s, serv=%s\en", hbuf, sbuf);
 399 .fi
 400 .in
 401
 402 .\"O The following version checks if the socket address has a
 403 .\"O reverse address mapping.
 404 以下ではソケットアドレスに
 405 逆向きのアドレスマッピングが存在するかをチェックしている。
 406
 407 .in +4n
 408 .nf
 409 struct sockaddr *sa;    /* input */
 410 socklen_t len;          /* input */
 411 char hbuf[NI_MAXHOST];
 412
 413 if (getnameinfo(sa, len, hbuf, sizeof(hbuf),
 414             NULL, 0, NI_NAMEREQD))
 415     printf("could not resolve hostname");
 416 else
 417     printf("host=%s\en", hbuf);
 418 .fi
 419 .in
 420 .PP
 421 .\"O An example program using
 422 .\"O .BR getnameinfo ()
 423 .\"O can be found in
 424 .\"O .BR getaddrinfo (3).
 425 .BR getnameinfo ()
 426 を使ったプログラム例が
 427 .BR getaddrinfo (3)
 428 に記載されている。
 429 .\"O .SH "SEE ALSO"
 430 .SH 関連項目
 431 .BR accept (2),
 432 .BR getpeername (2),
 433 .BR getsockname (2),
 434 .BR recvfrom (2),
 435 .BR socket (2),
 436 .BR getaddrinfo (3),
 437 .BR gethostbyaddr (3),
 438 .BR getservbyname (3),
 439 .BR getservbyport (3),
 440 .BR inet_ntop (3),
 441 .BR hosts (5),
 442 .BR services (5),
 443 .BR hostname (7),
 444 .BR named (8)
 445 .LP
 446 R. Gilligan, S. Thomson, J. Bound and W. Stevens,
 447 .IR "Basic Socket Interface Extensions for IPv6" ,
 448 RFC\ 2553, March 1999.
 449 .LP
 450 Tatsuya Jinmei and Atsushi Onoe,
 451 .IR "An Extension of Format for IPv6 Scoped Addresses" ,
 452 internet draft, work in progress.
 453 ftp://ftp.ietf.org/internet\-drafts/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt
 454 .LP
 455 Craig Metz,
 456 .IR "Protocol Independence Using the Sockets API" ,
 457 Proceedings of the freenix track:
 458 2000 USENIX annual technical conference, June 2000.
 459 http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html