getnameinfo - address-to-nodename translation in protocolindependent
manner
#include <sys/types.h>
#include <sys/socket.h>
#include <netdb.h>
int
getnameinfo(const struct sockaddr *sa, socklen_t salen, char
*host,
size_t hostlen, char *serv, size_t servlen, int
flags);
The getnameinfo() function is defined for protocol-independent addressto-nodename
translation. Its functionality is a reverse
conversion of
getaddrinfo(3), and implements similar functionality to
gethostbyaddr(3)
and getservbyport(3) in a more sophisticated manner.
This function looks up an IP address and port number provided by the
caller in the DNS and system-specific database, and returns
text strings
for both in buffers provided by the caller. The function
indicates successful
completion by a zero return value; a non-zero return
value indicates
failure.
The first argument, sa, points to either a sockaddr_in
structure (for
IPv4) or a sockaddr_in6 structure (for IPv6) that holds the
IP address
and port number. The salen argument gives the length of the
sockaddr_in
or sockaddr_in6 structure.
The function returns the nodename associated with the IP address in the
buffer pointed to by the host argument. The caller provides
the size of
this buffer via the hostlen argument. The service name associated with
the port number is returned in the buffer pointed to by
serv, and the
servlen argument gives the length of this buffer. The
caller specifies
not to return either string by providing a zero value for
the hostlen or
servlen arguments. Otherwise, the caller must provide
buffers large
enough to hold the nodename and the service name, including
the terminating
null characters.
Unfortunately most systems do not provide constants that
specify the maximum
size of either a fully-qualified domain name or a service name.
Therefore to aid the application in allocating buffers for
these two returned
strings the following constants are defined in
<netdb.h>:
#define NI_MAXHOST MAXHOSTNAMELEN
#define NI_MAXSERV 32
The first value is actually defined as the constant MAXDNAME
in recent
versions of BIND's <arpa/nameser.h> header (older versions
of BIND define
this constant to be 256) and the second is a guess based on
the services
listed in the current Assigned Numbers RFC.
The final argument is a flag that changes the default actions of this
function. By default the fully-qualified domain name (FQDN)
for the host
is looked up in the DNS and returned. If the flag bit
NI_NOFQDN is set,
only the nodename portion of the FQDN is returned for local
hosts.
If the flag bit NI_NUMERICHOST is set, or if the host's name
cannot be
located in the DNS, the numeric form of the host's address
is returned
instead of its name (e.g., by calling inet_ntop() instead of
gethostbyaddr()). If the flag bit NI_NAMEREQD is set, an
error is returned
if the host's name cannot be located in the DNS.
If the flag bit NI_NUMERICSERV is set, the numeric form of
the service
address is returned (e.g., its port number) instead of its
name. The two
NI_NUMERICxxx flags are required to support the -n flag that
many commands
provide.
A fifth flag bit, NI_DGRAM, specifies that the service is a
datagram service,
and causes getservbyport() to be called with a second
argument of
"udp" instead of its default of "tcp". This is required for
the few
ports (512-514) that have different services for UDP and
TCP.
These NI_xxx flags are defined in <netdb.h>.
Extension for scoped IPv6 address [Toc] [Back]
The implementation allows experimental numeric IPv6 address
notation with
scope identifier. IPv6 link-local address will appear as a
string like
``fe80::1%ne0''. Refer to getaddrinfo(3) for the notation.
The following code tries to get a numeric hostname, and service name, for
given socket address. Observe that there is no hardcoded
reference to a
particular address family.
struct sockaddr *sa; /* input */
char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf),
sbuf,
sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
errx(1, "could not get numeric hostname");
/*NOTREACHED*/
}
printf("host=%s, serv=%s0, hbuf, sbuf);
The following version checks if the socket address has reverse address
mapping.
struct sockaddr *sa; /* input */
char hbuf[NI_MAXHOST];
if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf),
NULL, 0,
NI_NAMEREQD)) {
errx(1, "could not resolve hostname");
/*NOTREACHED*/
}
printf("host=%s0, hbuf);
The function indicates successful completion by a zero return value; a
non-zero return value indicates failure. Error codes are as
below:
EAI_AGAIN The name could not be resolved at this time.
Future attempts
may succeed.
EAI_BADFLAGS The flags had 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 There was a memory allocation failure.
EAI_NONAME The name does not resolve for the supplied parameters.
NI_NAMEREQD is set and the host's name cannot
be located,
or both nodename and servname were null.
EAI_SYSTEM A system error occurred. The error code can
be found in
errno.
getaddrinfo(3), gethostbyaddr(3), getservbyport(3),
hosts(5),
resolv.conf(5), services(5), hostname(7), named(8)
R. Gilligan, S. Thomson, J. Bound, and W. Stevens, Basic
Socket Interface
Extensions for IPv6, RFC 2553, March 1999.
Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for
IPv6 Scoped
Addresses, internet draft, draft-ietf-ipngwg-scopedaddr-format-02.txt,
work in progress material.
Craig Metz, "Protocol Independence Using the Sockets API",
Proceedings of
the freenix track: 2000 USENIX annual technical conference,
June 2000.
The getnameinfo() function is defined in IEEE POSIX 1003.1g
draft specification,
and documented in ``Basic Socket Interface Extensions for
IPv6'' (RFC 2553).
The implementation first appeared in WIDE Hydrangea IPv6
protocol stack
kit.
getnameinfo() returns both numeric and FQDN notation of the
address specified
in sa. There is no return value that indicates if the
string returned
in host is a result of binary to numeric-text translation (like
inet_ntop(3)), or the result of DNS reverse lookup. Therefore, malicious
parties could set up a PTR record as below:
1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1
and trick the caller of getnameinfo() into believing that sa
is 10.1.1.1
when it actually is 127.0.0.1.
To prevent such attacks, the use of NI_NAMEREQD is recommended when you
use the result of getnameinfo() for access control purposes:
struct sockaddr *sa;
socklen_t salen;
char addr[NI_MAXHOST];
struct addrinfo hints, *res;
int error;
error = getnameinfo(sa, salen, addr, sizeof(addr),
NULL, 0, NI_NAMEREQD);
if (error == 0) {
memset(&hints, 0, sizeof(hints));
hints.ai_socktype = SOCK_DGRAM; /*dummy*/
hints.ai_flags = AI_NUMERICHOST;
if (getaddrinfo(addr, "0", &hints, &res) == 0)
{
/* malicious PTR record */
freeaddrinfo(res);
printf("bogus PTR record0);
return -1;
}
/* addr is FQDN as a result of PTR lookup */
} else {
/* addr is numeric string */
error = getnameinfo(sa, salen, addr, sizeof(addr),
NULL, 0, NI_NUMERICHOST);
}
The current implementation is not thread-safe.
The text was shamelessly copied from RFC 2553.
OpenBSD intentionally uses a different NI_MAXHOST value from
what RFC
2553 suggests, to avoid buffer length handling mistakes.
OpenBSD 3.6 May 25, 1995
[ Back ] |
