draft/man3/getnameinfo.3

   1 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
   2 .\" This page is in the public domain.
   3 .\" %%%LICENSE_END
   4 .\"
   5 .\" Almost all details are from RFC 2553.
   6 .\"
   7 .\" 2004-12-14, mtk, Added EAI_OVERFLOW error
   8 .\" 2004-12-14 Fixed description of error return
   9 .\"
  10 .\"*******************************************************************
  11 .\"
  12 .\" This file was generated with po4a. Translate the source file.
  13 .\"
  14 .\"*******************************************************************
  15 .TH GETNAMEINFO 3 2013\-01\-15 GNU "Linux Programmer's Manual"
  16 .SH 名前
  17 getnameinfo \- アドレスから名前への変換をプロトコルに依存しないかたちで行う
  18 .SH 書式
  19 .nf
  20 \fB#include <sys/socket.h>\fP
  21 \fB#include <netdb.h>\fP
  22 .sp
  23 \fBint getnameinfo(const struct sockaddr *\fP\fIsa\fP\fB, socklen_t \fP\fIsalen\fP\fB,\fP
  24 \fB                char *\fP\fIhost\fP\fB, size_t \fP\fIhostlen\fP\fB,\fP
  25 \fB                char *\fP\fIserv\fP\fB, size_t \fP\fIservlen\fP\fB, int \fP\fIflags\fP\fB);\fP
  26 .fi
  27 .sp
  28 .in -4n
  29 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  30 .ad l
  31 .in
  32 .sp
  33 \fBgetnameinfo\fP(): _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE ||
  34 _POSIX_SOURCE
  35 .ad b
  36 .SH 説明
  37 \fBgetnameinfo\fP()  関数は、 \fBgetaddrinfo\fP(3)  の逆の動作を行う。つまり、プロトコルに依存しないかたちで
  38 ソケットアドレスから対応するホスト名とサービスへの変換を行う。 この関数は \fBgethostbyaddr\fP(3)  と
  39 \fBgetservbyport\fP(3)  の機能を一つにしたものだが、 これらの関数と違い、 \fBgetnameinfo\fP(3)
  40 はリエントラントであり、IPv4 と IPv6 の差分に依存しないかたちで プログラムを書くことができる。
  41
  42 \fIsa\fP 引き数は、 IP アドレスとポート番号の情報を保持している 汎用的なソケットアドレス構造体 (\fIsockaddr_in\fP 型または
  43 \fIsockaddr_in6\fP 型) へのポインタである。 \fIsalen\fP は \fIsa\fP のサイズである。 \fIhost\fP と \fIserv\fP
  44 引き数は、(それぞれサイズが \fIhostlen\fP と \fIservlen\fP の) 呼び出し側で確保されたバッファへのポインタであり、
  45 ホスト名とサービス名を含む NULL 終端された文字列が それぞれのバッファに格納される。
  46
  47 ホスト名が不要であることをこの関数に伝えるには、 \fIhost\fP に NULL を指定するか、 \fIhostlen\fP に 0
  48 を指定する。同様に、サービス名が不要な場合は、 \fIserv\fP に NULL を指定するか、 \fIservlen\fP に 0 を指定する。
  49 しかし、ホスト名とサービス名の両方を不要だと指定することはできない (いずれか一方は要求すること)。
  50
  51 \fIflags\fP 引き数で \fBgetnameinfo\fP()  の動作を変えることができる。指定できる値は以下の通り:
  52 .TP
  53 \fBNI_NAMEREQD\fP
  54 指定すると、ホスト名が決定できなかった場合にエラーを返す。
  55 .TP
  56 \fBNI_DGRAM\fP
  57 指定すると、ストリームベース (TCP) でなくデータグラムベース (UDP)  のサービスを対象にする。数は少ないが、 UDP と TCP
  58 で違うサービスを提供しているポート (512\-514) に対して必要となる。
  59 .TP
  60 \fBNI_NOFQDN\fP
  61 指定すると、ローカルなホストには fully qualified domain name (FQDN) の ホスト名の部分のみを返す。
  62 .TP
  63 \fBNI_NUMERICHOST\fP
  64 .\" For example, by calling
  65 .\" .BR inet_ntop ()
  66 .\" instead of
  67 .\" .BR gethostbyaddr ().
  68 .\" POSIX.1-2003 has NI_NUMERICSCOPE, but glibc doesn't have it.
  69 指定すると、数値形式のホスト名が返される。 (指定しなくても、ノードの名前が決定できない場合は数値形式が返ることがある)。
  70 .TP
  71 \fBNI_NUMERICSERV\fP
  72 指定すると、数値形式のサービス名 (例えばポート番号) が返される (指定しなくても、サービス名が決定できない場合は数値形式が返ることがある)。
  73 .SS "国際化ドメイン名のための getnameinfo() の拡張"
  74 .PP
  75 glibc 2.3.4 から、 \fBgetnameinfo\fP()  に拡張が行われ、ホスト名と 国際化ドメイン名 (Internationalized
  76 Domain Name; IDN) 形式との間で 透過的な変換ができるようになっている (IDN 形式については RFC 3490 の
  77 \fIInternationalizing Domain Names in Applications (IDNA)\fP
  78 を参照)。3つのフラグが新たに定義されている:
  79 .TP
  80 \fBNI_IDN\fP
  81 このフラグを指定すると、必要であれば、検索処理で見つかった名前は IDN 形式からロケールに応じた符号化形式に変換される。 ASCII
  82 文字だけの名前はこの変換では影響を受けない。このため、 既存のプログラムや環境でこのフラグを使うことができる。
  83 .TP
  84 \fBNI_IDN_ALLOW_UNASSIGNED\fP, \fBNI_IDN_USE_STD3_ASCII_RULES\fP
  85 これらのフラグをセットすると、IDNA 処理で使用されるフラグ IDNA_ALLOW_UNASSIGNED (未割り当ての Unicode
  86 のコードポイントを許容) と IDNA_USE_STD3_ASCII_RULES (出力が STD3 準拠のホスト名かをチェックする)
  87 がそれぞれ有効になる。
  88 .SH 返り値
  89 .\" FIXME glibc defines the following additional errors, some which
  90 .\" can probably be returned by getnameinfo(); they need to
  91 .\" be documented.
  92 .\" #ifdef __USE_GNU
  93 .\" #define EAI_INPROGRESS  -100  /* Processing request in progress.  */
  94 .\" #define EAI_CANCELED    -101  /* Request canceled.  */
  95 .\" #define EAI_NOTCANCELED -102  /* Request not canceled.  */
  96 .\" #define EAI_ALLDONE     -103  /* All requests done.  */
  97 .\" #define EAI_INTR        -104  /* Interrupted by a signal.  */
  98 .\" #define EAI_IDN_ENCODE  -105  /* IDN encoding failed.  */
  99 .\" #endif
 100 成功すると 0 が返り、(要求されていれば) ノードとサービスの名前が NULL 終端された文字列の形式でそれぞれの指定バッファに返される
 101 (バッファの長さにあうように縮められるかもしれない)。 エラーの場合は、以下の 0 以外のエラー・コードが返される:
 102 .TP
 103 \fBEAI_AGAIN\fP
 104 指定された名前が現時点では解決できなかった。 後で再試行してみること。
 105 .TP
 106 \fBEAI_BADFLAGS\fP
 107 \fIflags\fP 引き数に不正な値が与えられた。
 108 .TP
 109 \fBEAI_FAIL\fP
 110 回復できないエラーが発生した。
 111 .TP
 112 \fBEAI_FAMILY\fP
 113 指定したアドレスファミリーが認識できなかった。 あるいはアドレスの長さが指定されたファミリーに合うものでなかった。
 114 .TP
 115 \fBEAI_MEMORY\fP
 116 メモリが足りない。
 117 .TP
 118 \fBEAI_NONAME\fP
 119 与えられたパラメータでは名前が解決できない。 \fBNI_NAMEREQD\fP が設定されていたがホスト名が決定できなかったか、
 120 ホスト名もサービス名も要求されなかった。
 121 .TP
 122 \fBEAI_OVERFLOW\fP
 123 \fIhost\fP または \fIserv\fP が指しているバッファが小さすぎた。
 124 .TP
 125 \fBEAI_SYSTEM\fP
 126 システムエラーが起った。 エラーコードは \fIerrno\fP に設定される。
 127 .PP
 128 \fBgai_strerror\fP(3) 関数を使うと、これらのエラー・コードを、エラー・レポートに適した 人間が読みやすい文字列に翻訳してくれる。
 129 .SH ファイル
 130 /etc/hosts
 131 .br
 132 /etc/nsswitch.conf
 133 .br
 134 /etc/resolv.conf
 135 .SH バージョン
 136 \fBgetnameinfo\fP()  は、glibc バージョン 2.1 以降で提供されている。
 137 .SH 準拠
 138 RFC\ 2553, POSIX.1\-2001.
 139 .SH 注意
 140 適切なバッファサイズを選択できるように、 \fI<netdb.h>\fP に以下の定数が定義されている。
 141 .in +4n
 142 .nf
 143
 144 #define NI_MAXHOST      1025
 145 #define NI_MAXSERV      32
 146 .fi
 147 .in
 148
 149 glibc 2.8 以降では、機能検査マクロ \fB_BSD_SOURCE\fP, \fB_SVID_SOURCE\fP, \fB_GNU_SOURCE\fP
 150 のいずれかが定義された場合にのみ、これらの定義が公開される。
 151 .PP
 152 前者は、最近のバージョンの BIND のヘッダファイル \fI<arpa/nameser.h>\fP 中の定数 \fBMAXDNAME\fP
 153 と同じ値である。 後者は、割り当て済の数値について記した現在の RFC に 列挙されてサービスから推量した値である。
 154 .SH 例
 155 以下のコードは、指定されたソケットアドレスに対する ホストとサービスの数値表式を取得しようと試みる。 特定のアドレスファミリーに対する参照情報は
 156 一切ハードコードされていないことに着目してほしい。
 157
 158 .in +4n
 159 .nf
 160 struct sockaddr *sa;    /* input */
 161 socklen_t len;          /* input */
 162 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
 163
 164 if (getnameinfo(sa, len, hbuf, sizeof(hbuf), sbuf,
 165             sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
 166     printf("host=%s, serv=%s\en", hbuf, sbuf);
 167 .fi
 168 .in
 169
 170 以下ではソケットアドレスに 逆向きのアドレスマッピングが存在するかをチェックしている。
 171
 172 .in +4n
 173 .nf
 174 struct sockaddr *sa;    /* input */
 175 socklen_t len;          /* input */
 176 char hbuf[NI_MAXHOST];
 177
 178 if (getnameinfo(sa, len, hbuf, sizeof(hbuf),
 179             NULL, 0, NI_NAMEREQD))
 180     printf("could not resolve hostname");
 181 else
 182     printf("host=%s\en", hbuf);
 183 .fi
 184 .in
 185 .PP
 186 \fBgetnameinfo\fP()  を使ったプログラム例が \fBgetaddrinfo\fP(3)  に記載されている。
 187 .SH 関連項目
 188 \fBaccept\fP(2), \fBgetpeername\fP(2), \fBgetsockname\fP(2), \fBrecvfrom\fP(2),
 189 \fBsocket\fP(2), \fBgetaddrinfo\fP(3), \fBgethostbyaddr\fP(3), \fBgetservbyname\fP(3),
 190 \fBgetservbyport\fP(3), \fBinet_ntop\fP(3), \fBhosts\fP(5), \fBservices\fP(5),
 191 \fBhostname\fP(7), \fBnamed\fP(8)
 192
 193 R. Gilligan, S. Thomson, J. Bound and W. Stevens, \fIBasic Socket Interface
 194 Extensions for IPv6\fP, RFC\ 2553, March 1999.
 195
 196 Tatsuya Jinmei and Atsushi Onoe, \fIAn Extension of Format for IPv6 Scoped
 197 Addresses\fP, internet draft, work in progress
 198 .UR ftp://ftp.ietf.org\:/internet\-drafts\:/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt
 199 .UE .
 200
 201 Craig Metz, \fIProtocol Independence Using the Sockets API\fP, Proceedings of
 202 the freenix track: 2000 USENIX annual technical conference, June 2000
 203 .ad l
 204 .UR http://www.usenix.org\:/publications\:/library\:/proceedings\:/usenix2000\:/freenix\:/metzprotocol.html
 205 .UE .
 206 .SH この文書について
 207 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
 208 である。プロジェクトの説明とバグ報告に関する情報は
 209 http://www.kernel.org/doc/man\-pages/ に書かれている。