Socket address structure to hostname and service name.

#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);

Description

The getnameinfo() function is used to convert a sockaddr structure to a pair of host name and service strings. It is a replacement for and provides more flexibility than the gethostbyaddr and getservbyport functions and is the converse of the getaddrinfo function.

If a link-layer address is passed to getnameinfo(), its ASCII representation will be stored in host. The string pointed to by serv will be set to the empty string if non-NULL; flags will always be ignored. This is intended as a replacement for the legacy link_ntoa function.

The structure sa should point to either a sockaddr_in, sockaddr_in6, or sockaddr_dl structure (for IPv4, IPv6 or link-layer respectively) that is salen bytes long.

The host and service names associated with sa are stored in host and serv which have length parameters hostlen and servlen. The maximum v alue for hostlen is NI_MAXHOST and the maximum value for servlen is NI_MAXSERV, as defined by If a length parameter is zero, no string will be stored. Otherwise, enough space must be provided to store the host name or service string plus a byte for the NUL terminator.

The flags argument is formed by OR Ns 'ing the following values:

NI_NOFQDN	A fully qualified domain name is not required for local hosts. The local part of the fully qualified domain name is returned instead.
NI_NUMERICHOST	Return the address in numeric form, as if calling inet_ntop, instead of a host name.
NI_NAMEREQD	A name is required. If the host name cannot be found in DNS and this flag is set, a non-zero error code is returned. If the host name is not found and the flag is not set, the address is returned in numeric form.
NI_NUMERICSERV	The service name is returned as a digit string representing the port number.
NI_DGRAM	Specifies that the service being looked up 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.

This implementation allows numeric IPv6 address notation with scope identifier, as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. IPv6 link-local address will appear as a string like "fe80::1%ne0" "." Refer to getaddrinfo for more information.

Remarks

The following code tries to get a numeric host name, and service name, for a 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=%s\en", hbuf, sbuf);

The following version checks if the socket address has a 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=%s\en", hbuf);

Return Values

getnameinfo() returns zero on success or one of the error codes listed in gai_strerror if an error occurs.

Requirements

See Also

Basic Socket Interface Extensions for IPv6 RFC 2553 March 1999 "IPv6 Scoped Address Architecture" internet draft draft-ietf-ipv6-scoping-arch-02.txt Protocol Independence Using the Sockets API, "Proceedings of the freenix track: 2000 USENIX annual technical conference" June 2000