getnameinfo(3SOCKET) (man pages section 3: Networking Library Functions)

man pages section 3: Networking Library Functions

getnameinfo(3SOCKET)

NAME

getaddrinfo, getnameinfo, freeaddrinfo, gai_strerror– translate between node name and address

SYNOPSIS

cc [[flag …]] file … -lsocket -lnsl [[library …]] 
#include <sys/socket.h>
#include <netdb.h>

nodename

servname

hints

res

sa

salen

host

hostlen

serv

servlen

flags

ai

errcode

DESCRIPTION

These functions perform translations from node name to address and from address to node name in a protocol-independent manner.

The getaddrinfo() function performs the node name to address translation. The nodename and servname arguments are pointers to null-terminated strings or NULL. One or both of these arguments must be a non-null pointer. In the normal client scenario, both the nodename and servname are specified. In the normal server scenario, only the servname is specified. A non-null nodename string can be either a node name or a numeric host address string (a dotted-decimal IPv4 address or an IPv6 hex address). A non-null servname string can be either a service name or a decimal port number.

The caller can optionally pass an addrinfo structure, pointed to by the third argument, to provide hints concerning the type of socket that the caller supports.

The addrinfo structure is defined as:

struct addrinfo {
int              ai_flags;      /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
int              ai_family;     /* PF_xxx */
int              ai_socktype;   /* SOCK_xxx */
int              ai_protocol;   /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
size_t           ai_addrlen;    /* length of ai_addr */
char             *ai_canonname; /* canonical name for nodename */
struct sockaddr  *ai_addr;      /* binary address */
struct addrinfo  *ai_next;      /* next structure in linked list */
};

In this hints structure, all members other than ai_flags, ai_family, ai_socktype, and ai_protocol must be 0 or a null pointer. A value of PF_UNSPEC for ai_family indicates that the caller will accept any protocol family. A value of 0 for ai_socktype indicates that the caller will accept any socket type. A value of 0 for ai_protocol indicates that the caller will accept any protocol. For example, if the caller handles only TCP and not UDP, then the ai_socktype member of the hints structure should be set to SOCK_STREAM when getaddrinfo() is called. If the caller handles only IPv4 and not IPv6, then the ai_family member of the hints structure should be set to PF_INET when getaddrinfo() is called. If the third argument to getaddrinfo() is a null pointer, it is as if the caller had filled in an addrinfo structure initialized to 0 with ai_family set to PF_UNSPEC.

Upon success, a pointer to a linked list of one or more addrinfo structures is returned through the final argument. The caller can process each addrinfo structure in this list by following the ai_next pointer, until a null pointer is encountered. In each returned addrinfo structure the three members ai_family, ai_socktype, and ai_protocol are the corresponding arguments for a call to the socket(3SOCKET) function. In each addrinfo structure the ai_addr member points to a filled-in socket address structure whose length is specified by the ai_addrlen member.

If the AI_PASSIVE bit is set in the ai_flags member of the hints structure, the caller plans to use the returned socket address structure in a call to bind(3SOCKET). In this case, if the nodename argument is a null pointer, the IP address portion of the socket address structure will be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 address.

If the AI_PASSIVE bit is not set in the ai_flags member of the hints structure, then the returned socket address structure will be ready for a call to connect(3SOCKET) (for a connection-oriented protocol) or either connect(3SOCKET), sendto(3SOCKET), or sendmsg(3SOCKET) (for a connectionless protocol). If the nodename argument is a null pointer, the IP address portion of the socket address structure will be set to the loopback address.

If the AI_CANONNAME bit is set in the ai_flags member of the hints structure, then upon successful return the ai_canonname member of the first addrinfo structure in the linked list will point to a null-terminated string containing the canonical name of the specified nodename.

If the AI_NUMERICHOST bit is set in the ai_flags member of the hints structure, then a non-null nodename string must be a numeric host address string. Otherwise an error of EAI_NONAME is returned. This flag prevents any type of name resolution service (such as DNS) from being called.

All of the information returned by getaddrinfo() is dynamically allocated: the addrinfo structures as well as the socket address structures and canonical node name strings pointed to by the addrinfo structures. The freeaddrinfo() function is called to return this information to the system the function . For freeaddrinfo(), the addrinfo structure pointed to by the ai argument is freed, along with any dynamic storage pointed to by the structure. This operation is repeated until a null ai_next pointer is encountered.

To aid applications in printing error messages based on the EAI_* codes returned by getaddrinfo(), the gai_strerror() is defined. The argument is one of the EAI_* values defined below and the return value points to a string describing the error. If the argument is not one of the EAI_* values, the function still returns a pointer to a string whose contents indicate an unknown error.

The getnameinfo() function looks up an IP address and port number provided by the caller in the name service database and system-specific database, and returns text strings for both in buffers provided by the caller. The function indicates successful completion by a 0 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 node name associated with the IP address in the buffer pointed to by the host argument. The caller provides the size of this buffer with 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 0 value for the hostlen or servlen arguments. Otherwise, the caller must provide buffers large enough to hold the node name and the service name, including the terminating null characters.

To aid the application in allocating buffers for these two returned strings, the following constants are defined in <netdb.h>:

#define NI_MAXHOST  1025
#define NI_MAXSERV    32

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 name service database and returned. If the flag bit NI_NOFQDN is set, only the node name 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 name service, the numeric form of the host's address is returned instead of its name, for example, by calling inet_ntop() (see inet(3SOCKET)) instead of getipnodebyname(3SOCKET). If the flag bit NI_NAMEREQD is set, an error is returned if the host's name cannot be located in the name service database.

If the flag bit NI_NUMERICSERV is set, the numeric form of the service address is returned (for example, its port number) instead of its name. The two NI_NUMERIC* 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(3SOCKET) to be called with a second argument of "udp" instead of the default "tcp". This is required for the few ports (for example, 512-514) that have different services for UDP and TCP.

These NI_* flags are defined in <netdb.h> along with the AI_* flags already defined for getaddrinfo().

RETURN VALUES

For getaddrinfo(), if the query is successful, a pointer to a linked list of one or more addrinfo structures is returned by the fourth argument and the function returns 0. If the query fails, a non-zero error code will be returned. For getnameinfo(), if successful, the strings hostname and service are copied into host and serv, respectively. If unsuccessful, zero values for either hostlen or servlen will suppress the associated lookup; in this case no data is copied into the applicable buffer. If gai_strerror() is successful, a pointer to a string containing an error message appropriate for the EAI_* errors is returned. If errcode is not one of the EAI_* values, a pointer to a string indicating an unknown error is returned.

ERRORS

The following names are the error values returned by getaddrinfo() and are defined in <netdb.h>:

EAI_ADDRFAMILY  address family for nodename not supported
EAI_AGAIN       temporary failure in name resolution
EAI_BADFLAGS    invalid value for ai_flags
EAI_FAIL        non-recoverable failure in name resolution
EAI_FAMILY      ai_family not supported
EAI_MEMORY      memory allocation failure
EAI_NODATA      no address associated with nodename
EAI_NONAME      nodename nor servname provided, or not known
EAI_SERVICE     servname not supported for ai_socktype
EAI_SOCKTYPE    ai_socktype not supported
EAI_SYSTEM      system error returned in errno

FILES

/etc/inet/hosts: host name database
/etc/inet/ipnodes: local database that associates names of nodes with IP addresses
/etc/netconfig: network configuration database
/etc/nsswitch.conf: configuration file for the name service switch