getnameinfoのヘルプ・マニュアル
日本語 英語
getnameinfo --help
man getnameinfo
GETNAMEINFO(3) Linux Programmer’s Manual GETNAMEINFO(3)
名前
getnameinfo - アドレスから名前への変換をプロトコルに依存しないかたちで
行う
書式
#include
#include
int getnameinfo(const struct sockaddr *sa, socklen_t salen,
char *host, size_t hostlen,
char *serv, size_t servlen, int flags);
glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照):
getnameinfo(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE
説明
getnameinfo() 関数は、 getaddrinfo(3) の逆の動作を行う。つまり、プロ ト
コ ルに依存しないかたちでソケットアドレスから対応するホスト名とサービス
への変換を行う。この関数は gethostbyaddr(3) と getservbyport(3) の機 能
を 一つにしたものだが、これらの関数と違い、 getnameinfo(3) はリエントラ
ントであり、IPv4 と IPv6 の差分に依存しないかたちでプログラムを書くこと
ができる。
sa 引き数は、 IP アドレスとポート番号の情報を保持している汎用的なソケッ
トアドレス構造体 (sockaddr_in 型または sockaddr_in6 型) へのポインタ で
あ る。 salen は sa のサイズである。 host と serv 引き数は、(それぞれサ
イズが hostlen と servlen の) 呼び出し側で確保されたバッファへのポイ ン
タ であり、ホスト名とサービス名を含む NULL 終端された文字列がそれぞれの
バッファに格納される。
ホスト名が不要であることをこの関数に伝えるには、 host に NULL を指定 す
るか、 hostlen に 0 を指定する。同様に、サービス名が不要な場合は、 serv
に NULL を指定するか、 servlen に 0 を指定する。しかし、ホスト名とサ ー
ビ ス名の両方を不要だと指定することはできない (いずれか一方は要求するこ
と)。
flags 引き数で getnameinfo() の動作を変えることができる。指定できる値は
以下の通り:
NI_NAMEREQD
指定すると、ホスト名が決定できなかった場合にエラーを返す。
NI_DGRAM
指 定 す る と 、ストリームベース (TCP) でなくデータグラムベース
(UDP) のサービスを対象にする。数は少ないが、 UDP と TCP で違うサ
ービスを提供しているポート (512-514) に対して必要となる。
NI_NOFQDN
指 定 す る と、ローカルなホストには fully qualified domain name
(FQDN) のホスト名の部分のみを返す。
NI_NUMERICHOST
指定すると、数値形式のホスト名が返される。 (指定しなくても、ノー
ドの名前が決定できない場合は数値形式が返ることがある)。
NI_NUMERICSERV
指定すると、数値形式のサービス名 (例えばポート番号) が返される (
指定しなくても、サービス名が決定できない場合は数値形式が返ること
がある)。
国際化ドメイン名のための getnameinfo() の拡張
glibc 2.3.4 から、 getnameinfo() に拡張が行われ、ホスト名と国際化ドメイ
ン名 (Internationalized Domain Name; IDN) 形式との間で透過的な変換が で
きるようになっている (IDN 形式については RFC 3490 の Internationalizing
Domain Names in Applications (IDNA) を参照)。3つのフラグが新たに定義 さ
れている:
NI_IDN このフラグを指定すると、必要であれば、検索処理で見つかった名前は
IDN 形式からロケールに応じた符号化形式に変換される。 ASCII 文 字
だけの名前はこの変換では影響を受けない。このため、既存のプログラ
ムや環境でこのフラグを使うことができる。
NI_IDN_ALLOW_UNASSIGNED, NI_IDN_USE_STD3_ASCII_RULES
これらのフラグをセットすると、IDNA 処理で使 用 さ れ る フ ラ グ
IDNA_ALLOW_UNASSIGNED (未割り当ての Unicode のコードポイントを許
容) と IDNA_USE_STD3_ASCII_RULES (出力が STD3 準拠のホスト名かを
チェックする) がそれぞれ有効になる。
返り値
成 功 すると 0 が返り、(要求されていれば) ノードとサービスの名前が NULL
終端された文字列の形式でそれぞれの指定バッファに返される (バッファの 長
さ にあうように縮められるかもしれない)。エラーの場合は、以下の 0 以外の
エラー・コードが返される:
EAI_AGAIN
指定された名前が現時点では解決できなかった。後で再試行してみるこ
と。
EAI_BADFLAGS
flags 引き数に不正な値が与えられた。
EAI_FAIL
回復できないエラーが発生した。
EAI_FAMILY
指定したアドレスファミリーが認識できなかった。あるいはアドレスの
長さが指定されたファミリーに合うものでなかった。
EAI_MEMORY
メモリが足りない。
EAI_NONAME
与えられたパラメータでは名前が解決できない。 NI_NAMEREQD が設 定
されていたがホスト名が決定できなかったか、ホスト名もサービス名も
要求されなかった。
EAI_OVERFLOW
host または serv が指しているバッファが小さすぎた。
EAI_SYSTEM
システムエラーが起った。エラーコードは errno に設定される。
gai_strerror(3) 関数を使うと、これらのエラー・コードを、エラー・レポ ー
トに適した人間が読みやすい文字列に翻訳してくれる。
ファイル
/etc/hosts
/etc/nsswitch.conf
/etc/resolv.conf
バージョン
getnameinfo() は、glibc バージョン 2.1 以降で提供されている。
準拠
RFC 2553, POSIX.1-2001.
注意
適切なバッファサイズを選択できるように、 に以下の定数が定義さ
れている。
#define NI_MAXHOST 1025
#define NI_MAXSERV 32
前者は、最近のバージョンの BIND のヘッダファイル 中 の
定 数 MAXDNAME と同じ値である。後者は、割り当て済の数値について記した現
在の RFC に列挙されてサービスから推量した値である。
例
以下のコードは、指定されたソケットアドレスに対するホストとサービスの 数
値 表式を取得しようと試みる。特定のアドレスファミリーに対する参照情報は
一切ハードコードされていないことに着目してほしい。
struct sockaddr *sa; /* input */
socklen_t len; /* input */
char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
if (getnameinfo(sa, len, hbuf, sizeof(hbuf), sbuf,
sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
printf("host=%s, serv=%s\n", hbuf, sbuf);
以下ではソケットアドレスに逆向きのアドレスマッピングが存在するかをチ ェ
ックしている。
struct sockaddr *sa; /* input */
socklen_t len; /* input */
char hbuf[NI_MAXHOST];
if (getnameinfo(sa, len, hbuf, sizeof(hbuf),
NULL, 0, NI_NAMEREQD))
printf("could not resolve hostname");
else
printf("host=%s\n", hbuf);
getnameinfo() を使ったプログラム例が getaddrinfo(3) に記載されている。
関連項目
accept(2), getpeername(2), getsockname(2), recvfrom(2), socket(2),
getaddrinfo(3), gethostbyaddr(3), getservbyname(3), getservbyport(3),
inet_ntop(3), hosts(5), services(5), hostname(7), named(8)
R. Gilligan, S. Thomson, J. Bound and W. Stevens, Basic Socket Inter-
face Extensions for IPv6, RFC 2553, March 1999.
Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped
Addresses, internet draft, work in progress. ftp://ftp.ietf.org/inter-
net-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt
Craig Metz, Protocol Independence Using the Sockets API, Proceedings of
the freenix track: 2000 USENIX annual technical conference, June 2000.
http://www.usenix.org/publications/library/proceed-
ings/usenix2000/freenix/metzprotocol.html
GNU 2009-02-23 GETNAMEINFO(3)
GETNAMEINFO(3) Linux Programmer’s Manual GETNAMEINFO(3)
NAME
getnameinfo - address-to-name translation in protocol-independent man-
ner
SYNOPSIS
#include
#include
int getnameinfo(const struct sockaddr *sa, socklen_t salen,
char *host, size_t hostlen,
char *serv, size_t servlen, int flags);
Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
getnameinfo(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE
DESCRIPTION
The getnameinfo() function is the inverse of getaddrinfo(3): it con-
verts a socket address to a corresponding host and service, in a proto-
col-independent manner. It combines the functionality of gethost-
byaddr(3) and getservbyport(3), but unlike those functions, getad-
drinfo(3) is reentrant and allows programs to eliminate IPv4-versus-
IPv6 dependencies.
The sa argument is a pointer to a generic socket address structure (of
type sockaddr_in or sockaddr_in6) of size salen that holds the input IP
address and port number. The arguments host and serv are pointers to
caller-allocated buffers (of size hostlen and servlen respectively)
into which getnameinfo() places null-terminated strings containing the
host and service names respectively.
The caller can specify that no hostname (or no service name) is
required by providing a NULL host (or serv) argument or a zero hostlen
(or servlen) argument. However, at least one of hostname or service
name must be requested.
The flags argument modifies the behavior of getnameinfo() as follows:
NI_NAMEREQD
If set, then an error is returned if the hostname cannot be
determined.
NI_DGRAM
If set, then the service is datagram (UDP) based rather than
stream (TCP) based. This is required for the few ports
(512-514) that have different services for UDP and TCP.
NI_NOFQDN
If set, return only the hostname part of the fully qualified
domain name for local hosts.
NI_NUMERICHOST
If set, then the numeric form of the hostname is returned.
(When not set, this will still happen in case the node’s name
cannot be determined.)
NI_NUMERICSERV
If set, then the numeric form of the service address is
returned. (When not set, this will still happen in case the
service’s name cannot be determined.)
Extensions to getaddrinfo() for Internationalized Domain Names
Starting with glibc 2.3.4, getnameinfo() has been extended to selec-
tively allow hostnames to be transparently converted to and from the
Internationalized Domain Name (IDN) format (see RFC 3490, Internation-
alizing Domain Names in Applications (IDNA)). Three new flags are
defined:
NI_IDN If this flag is used, then the name found in the lookup process
is converted from IDN format to the locale’s encoding if neces-
sary. ASCII-only names are not affected by the conversion,
which makes this flag usable in existing programs and environ-
ments.
NI_IDN_ALLOW_UNASSIGNED, NI_IDN_USE_STD3_ASCII_RULES
Setting these flags will enable the IDNA_ALLOW_UNASSIGNED (allow
unassigned Unicode code points) and IDNA_USE_STD3_ASCII_RULES
(check output to make sure it is a STD3 conforming hostname)
flags respectively to be used in the IDNA handling.
RETURN VALUE
On success 0 is returned, and node and service names, if requested, are
filled with null-terminated strings, possibly truncated to fit the
specified buffer lengths. On error one of the following non-zero error
codes is returned:
EAI_AGAIN
The name could not be resolved at this time. Try again later.
EAI_BADFLAGS
The flags argument has an invalid value.
EAI_FAIL
A non-recoverable error occurred.
EAI_FAMILY
The address family was not recognized, or the address length was
invalid for the specified family.
EAI_MEMORY
Out of memory.
EAI_NONAME
The name does not resolve for the supplied arguments.
NI_NAMEREQD is set and the host’s name cannot be located, or
neither hostname nor service name were requested.
EAI_OVERFLOW
The buffer pointed to by host or serv was too small.
EAI_SYSTEM
A system error occurred. The error code can be found in errno.
The gai_strerror(3) function translates these error codes to a human
readable string, suitable for error reporting.
FILES
/etc/hosts
/etc/nsswitch.conf
/etc/resolv.conf
VERSIONS
getnameinfo() is provided in glibc since version 2.1.
CONFORMING TO
RFC 2553, POSIX.1-2001.
NOTES
In order to assist the programmer in choosing reasonable sizes for the
supplied buffers, defines the constants
#define NI_MAXHOST 1025
#define NI_MAXSERV 32
The former is the constant MAXDNAME in recent versions of BIND’s
header file. The latter is a guess based on the ser-
vices listed in the current Assigned Numbers RFC.
EXAMPLE
The following code tries to get the numeric hostname and service name,
for a given socket address. Note that there is no hardcoded reference
to a particular address family.
struct sockaddr *sa; /* input */
socklen_t len; /* input */
char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
if (getnameinfo(sa, len, hbuf, sizeof(hbuf), sbuf,
sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
printf("host=%s, serv=%s\n", hbuf, sbuf);
The following version checks if the socket address has a reverse
address mapping.
struct sockaddr *sa; /* input */
socklen_t len; /* input */
char hbuf[NI_MAXHOST];
if (getnameinfo(sa, len, hbuf, sizeof(hbuf),
NULL, 0, NI_NAMEREQD))
printf("could not resolve hostname");
else
printf("host=%s\n", hbuf);
An example program using getnameinfo() can be found in getaddrinfo(3).
SEE ALSO
accept(2), getpeername(2), getsockname(2), recvfrom(2), socket(2),
getaddrinfo(3), gethostbyaddr(3), getservbyname(3), getservbyport(3),
inet_ntop(3), hosts(5), services(5), hostname(7), named(8)
R. Gilligan, S. Thomson, J. Bound and W. Stevens, Basic Socket Inter-
face Extensions for IPv6, RFC 2553, March 1999.
Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped
Addresses, internet draft, work in progress. ftp://ftp.ietf.org/inter-
net-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt
Craig Metz, Protocol Independence Using the Sockets API, Proceedings of
the freenix track: 2000 USENIX annual technical conference, June 2000.
http://www.usenix.org/publications/library/proceed-
ings/usenix2000/freenix/metzprotocol.html
COLOPHON
This page is part of release 3.22 of the Linux man-pages project. A
description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
GNU 2009-02-23 GETNAMEINFO(3)