release/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 .SH 名前
  14 getnameinfo \- アドレスから名前への変換をプロトコルに依存しないかたちで行う
  15 .SH 書式
  16 .nf
  17 .B #include <sys/socket.h>
  18 .B #include <netdb.h>
  19 .sp
  20 .BI "int getnameinfo(const struct sockaddr *" "sa" ", socklen_t " "salen" ,
  21 .BI "                char *" "host" ", size_t " "hostlen" ,
  22 .BI "                char *" "serv" ", size_t " "servlen" ", int " "flags" );
  23 .fi
  24 .sp
  25 .in -4n
  26 glibc 向けの機能検査マクロの要件
  27 .RB ( feature_test_macros (7)
  28 参照):
  29 .ad l
  30 .in
  31 .sp
  32 .BR getnameinfo ():
  33 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
  34 .ad b
  35 .SH 説明
  36 .BR getnameinfo ()
  37 関数は、
  38 .BR getaddrinfo (3)
  39 の逆の動作を行う。つまり、プロトコルに依存しないかたちで
  40 ソケットアドレスから対応するホスト名とサービスへの変換を行う。
  41 この関数は
  42 .BR gethostbyaddr (3)
  43 と
  44 .BR getservbyport (3)
  45 の機能を一つにしたものだが、
  46 これらの関数と違い、
  47 .BR getnameinfo (3)
  48 はリエントラントであり、IPv4 と IPv6 の差分に依存しないかたちで
  49 プログラムを書くことができる。
  50
  51 .I sa
  52 引き数は、
  53 IP アドレスとポート番号の情報を保持している
  54 汎用的なソケットアドレス構造体
  55 .RI ( sockaddr_in
  56 型または
  57 .I sockaddr_in6
  58 型) へのポインタである。
  59 .I salen
  60 は
  61 .I sa
  62 のサイズである。
  63 .I host
  64 と
  65 .I serv
  66 引き数は、(それぞれサイズが
  67 .I hostlen
  68 と
  69 .I servlen
  70 の) 呼び出し側で確保されたバッファへのポインタであり、
  71 ホスト名とサービス名を含む NULL 終端された文字列が
  72 それぞれのバッファに格納される。
  73
  74 ホスト名が不要であることをこの関数に伝えるには、
  75 .I host
  76 に NULL を指定するか、
  77 .I hostlen
  78 に 0 を指定する。同様に、サービス名が不要な場合は、
  79 .I serv
  80 に NULL を指定するか、
  81 .I servlen
  82 に 0 を指定する。
  83 しかし、ホスト名とサービス名の両方を不要だと指定することはできない
  84 (いずれか一方は要求すること)。
  85
  86 .I flags
  87 引き数で
  88 .BR getnameinfo ()
  89 の動作を変えることができる。指定できる値は以下の通り:
  90 .TP
  91 .B NI_NAMEREQD
  92 指定すると、ホスト名が決定できなかった場合にエラーを返す。
  93 .TP
  94 .B NI_DGRAM
  95 指定すると、ストリームベース (TCP) でなくデータグラムベース (UDP)
  96 のサービスを対象にする。数は少ないが、
  97 UDP と TCP で違うサービスを提供しているポート
  98 (512-514) に対して必要となる。
  99 .TP
 100 .B NI_NOFQDN
 101 指定すると、ローカルなホストには fully qualified domain name (FQDN) の
 102 ホスト名の部分のみを返す。
 103 .TP
 104 .B NI_NUMERICHOST
 105 指定すると、数値形式のホスト名が返される。
 106 .\" 例えば
 107 .\" .BR gethostbyaddr ()
 108 .\" の代わりに
 109 .\" .BR inet_ntop ()
 110 .\" を呼ぶ
 111 (指定しなくても、ノードの名前が決定できない場合は数値形式が返ることがある)。
 112 .\" POSIX.1-2003 has NI_NUMERICSCOPE, but glibc doesn't have it.
 113 .TP
 114 .B NI_NUMERICSERV
 115 指定すると、数値形式のサービス名 (例えばポート番号) が返される
 116 (指定しなくても、サービス名が決定できない場合は数値形式が返ることがある)。
 117 .SS "国際化ドメイン名のための getnameinfo() の拡張"
 118 .PP
 119 glibc 2.3.4 から、
 120 .BR getnameinfo ()
 121 に拡張が行われ、ホスト名と
 122 国際化ドメイン名 (Internationalized Domain Name; IDN) 形式との間で
 123 透過的な変換ができるようになっている
 124 (IDN 形式については RFC 3490 の
 125 .I "Internationalizing Domain Names in Applications (IDNA)"
 126 を参照)。3つのフラグが新たに定義されている:
 127 .TP
 128 .B NI_IDN
 129 このフラグを指定すると、必要であれば、検索処理で見つかった名前は
 130 IDN 形式からロケールに応じた符号化形式に変換される。
 131 ASCII 文字だけの名前はこの変換では影響を受けない。このため、
 132 既存のプログラムや環境でこのフラグを使うことができる。
 133 .TP
 134 .BR NI_IDN_ALLOW_UNASSIGNED ", " NI_IDN_USE_STD3_ASCII_RULES
 135 これらのフラグをセットすると、IDNA 処理で使用されるフラグ
 136 IDNA_ALLOW_UNASSIGNED (未割り当ての Unicode のコードポイントを許容) と
 137 IDNA_USE_STD3_ASCII_RULES (出力が STD3 準拠のホスト名かをチェックする)
 138 がそれぞれ有効になる。
 139 .SH 返り値
 140 .\" FIXME glibc defines the following additional errors, some which
 141 .\" can probably be returned by getnameinfo(); they need to
 142 .\" be documented.
 143 .\" #ifdef __USE_GNU
 144 .\" #define EAI_INPROGRESS  -100  /* Processing request in progress.  */
 145 .\" #define EAI_CANCELED    -101  /* Request canceled.  */
 146 .\" #define EAI_NOTCANCELED -102  /* Request not canceled.  */
 147 .\" #define EAI_ALLDONE     -103  /* All requests done.  */
 148 .\" #define EAI_INTR        -104  /* Interrupted by a signal.  */
 149 .\" #define EAI_IDN_ENCODE  -105  /* IDN encoding failed.  */
 150 .\" #endif
 151 成功すると 0 が返り、(要求されていれば) ノードとサービスの名前が
 152 NULL 終端された文字列の形式でそれぞれの指定バッファに返される
 153 (バッファの長さにあうように縮められるかもしれない)。
 154 エラーの場合は、以下の 0 以外のエラー・コードが返される:
 155 .TP
 156 .B EAI_AGAIN
 157 指定された名前が現時点では解決できなかった。
 158 後で再試行してみること。
 159 .TP
 160 .B EAI_BADFLAGS
 161 .I flags
 162 引き数に不正な値が与えられた。
 163 .TP
 164 .B EAI_FAIL
 165 回復できないエラーが発生した。
 166 .TP
 167 .B EAI_FAMILY
 168 指定したアドレスファミリーが認識できなかった。
 169 あるいはアドレスの長さが指定されたファミリーに合うものでなかった。
 170 .TP
 171 .B EAI_MEMORY
 172 メモリが足りない。
 173 .TP
 174 .B EAI_NONAME
 175 与えられたパラメータでは名前が解決できない。
 176 .B NI_NAMEREQD
 177 が設定されていたがホスト名が決定できなかったか、
 178 ホスト名もサービス名も要求されなかった。
 179 .TP
 180 .B EAI_OVERFLOW
 181 .I host
 182 または
 183 .I serv
 184 が指しているバッファが小さすぎた。
 185 .TP
 186 .B EAI_SYSTEM
 187 システムエラーが起った。
 188 エラーコードは
 189 .I errno
 190 に設定される。
 191 .PP
 192 .BR gai_strerror (3)
 193 関数を使うと、これらのエラー・コードを、エラー・レポートに適した
 194 人間が読みやすい文字列に翻訳してくれる。
 195 .SH ファイル
 196 /etc/hosts
 197 .br
 198 /etc/nsswitch.conf
 199 .br
 200 /etc/resolv.conf
 201 .SH バージョン
 202 .BR getnameinfo ()
 203 は、glibc バージョン 2.1 以降で提供されている。
 204 .SH 準拠
 205 RFC\ 2553, POSIX.1-2001.
 206 .SH 注意
 207 適切なバッファサイズを選択できるように、
 208 .I <netdb.h>
 209 に以下の定数が定義されている。
 210 .in +4n
 211 .nf
 212
 213 #define NI_MAXHOST      1025
 214 #define NI_MAXSERV      32
 215 .fi
 216 .in
 217
 218 glibc 2.8 以降では、機能検査マクロ
 219 .BR _BSD_SOURCE ,
 220 .BR _SVID_SOURCE ,
 221 .BR _GNU_SOURCE
 222 のいずれかが定義された場合にのみ、これらの定義が公開される。
 223 .PP
 224 前者は、最近のバージョンの BIND のヘッダファイル
 225 .I <arpa/nameser.h>
 226 中の定数
 227 .B MAXDNAME
 228 と同じ値である。
 229 後者は、割り当て済の数値について記した現在の RFC に
 230 列挙されてサービスから推量した値である。
 231 .SH 例
 232 以下のコードは、指定されたソケットアドレスに対する
 233 ホストとサービスの数値表式を取得しようと試みる。
 234 特定のアドレスファミリーに対する参照情報は
 235 一切ハードコードされていないことに着目してほしい。
 236
 237 .in +4n
 238 .nf
 239 struct sockaddr *sa;    /* input */
 240 socklen_t len;          /* input */
 241 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
 242
 243 if (getnameinfo(sa, len, hbuf, sizeof(hbuf), sbuf,
 244             sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
 245     printf("host=%s, serv=%s\en", hbuf, sbuf);
 246 .fi
 247 .in
 248
 249 以下ではソケットアドレスに
 250 逆向きのアドレスマッピングが存在するかをチェックしている。
 251
 252 .in +4n
 253 .nf
 254 struct sockaddr *sa;    /* input */
 255 socklen_t len;          /* input */
 256 char hbuf[NI_MAXHOST];
 257
 258 if (getnameinfo(sa, len, hbuf, sizeof(hbuf),
 259             NULL, 0, NI_NAMEREQD))
 260     printf("could not resolve hostname");
 261 else
 262     printf("host=%s\en", hbuf);
 263 .fi
 264 .in
 265 .PP
 266 .BR getnameinfo ()
 267 を使ったプログラム例が
 268 .BR getaddrinfo (3)
 269 に記載されている。
 270 .SH 関連項目
 271 .BR accept (2),
 272 .BR getpeername (2),
 273 .BR getsockname (2),
 274 .BR recvfrom (2),
 275 .BR socket (2),
 276 .BR getaddrinfo (3),
 277 .BR gethostbyaddr (3),
 278 .BR getservbyname (3),
 279 .BR getservbyport (3),
 280 .BR inet_ntop (3),
 281 .BR hosts (5),
 282 .BR services (5),
 283 .BR hostname (7),
 284 .BR named (8)
 285 .LP
 286 R. Gilligan, S. Thomson, J. Bound and W. Stevens,
 287 .IR "Basic Socket Interface Extensions for IPv6" ,
 288 RFC\ 2553, March 1999.
 289 .LP
 290 Tatsuya Jinmei and Atsushi Onoe,
 291 .IR "An Extension of Format for IPv6 Scoped Addresses" ,
 292 internet draft, work in progress.
 293 ftp://ftp.ietf.org/internet\-drafts/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt
 294 .LP
 295 Craig Metz,
 296 .IR "Protocol Independence Using the Sockets API" ,
 297 Proceedings of the freenix track:
 298 2000 USENIX annual technical conference, June 2000.
 299 http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html