getnameinfo

getnameinfo()

get name information 

Function

SYNOPSIS

#include <sys/socket.h>

#include <netdb.h>

int getnameinfo(const struct sockaddr *sa, socklen_t salen, char *node, socklen_t nodelen, char *service, socklen_t servicelen, int flags);

DESCRIPTION

The getnameinfo() function takes a socket address (as specified by the sa parameter which points to a sockaddr structure) as input and returns the corresponding node name and service location. Essentially, it is the reverse of getaddrinfo().

When the socket address structure contains an IPv4-mapped IPv6 address or an IPv4-compatible IPv6 address, getnameinfo() extracts the IPv4 address and finds the corresponding node name for that address.

Note:

When the address is the IPv6 unspecified address (::), getnameinfo() does not perform a lookup and returns the error code EAI_NONAME. The IPv6 loopback address ( "::1") is also not IPv4-compatible.

The node name found is stored in the buffer pointed to by the node parameter. This buffer has a maximum size of nodelen characters. When node is a null pointer or nodelen is zero, no node name is returned. When no corresponding node name can be found, the buffer pointed to by node is instead set to the numeric form of the socket address in the socket address structure that sa points to.

The service name found is stored in the buffer pointed to by the service parameter. This buffer has a maximum size of servicelen characters. When service is a null pointer or servicelen is zero, no service name is returned. When no service name can be found, the buffer pointed to by service is instead set to the numeric form of the service address (for example, its port number).

By default, getnameinfo() returns the fully-qualified domain name of the host. However, the flags parameter can change this behavior.

PARAMETERS

flags 

Changes the behavior of the getnameinfo() function, based on the setting of the following bits:

NI_NOFQDN 

When set, getnameinfo() returns only the node name portion of the fully-qualified domain name for local hosts.

NI_NUMERICHOST 

When set, getnameinfo() always returns the numeric form of the address contained in the socket address structure pointed to by sa instead of the node name, even when node is not a null pointer and nodelen is non-zero.

NI_NAMEREQD 

When set, getnameinfo() returns an error when the host's name cannot be located.

NI_NUMERICSERV 

When set, getnameinfo() returns the numeric form of the service address (for example, its port number) instead of the service name, even when service is not a null pointer and servlen is non-zero.

NI_NUMERICSCOPE 

When set, getnameinfo() returns the numeric form of the scope identifier (for example, interface index) instead of its name. This flag is ignored when sa is not an IPv6 address.

NI_DGRAM 

When set, this bit specifies that the service is a datagram service (SOCK_DGRAM). By default, getnameinfo() assumes the service is a stream service (SOCK_STREAM).

node 

Points to a buffer where the node name is returned.

nodelen 

Specifies the length of the buffer pointed to by node.

sa 

Points to a sockaddr structure.

salen 

Specifies the length of the sa structure.

service 

Points to a buffer where the service name is returned.

servicelen 

Specifies the length of the buffer pointed to by service.

RETURN VALUES

When successful, getnameinfo() returns zero and sets the node and service buffers to contain the node and service names (if requested).

Otherwise, it returns one of the error codes:

EAI_AGAIN 

The specified name cannot be currently resolved. Further attempts might succeed.

EAI_BADFLAGS 

The flags parameter is set to an invalid value.

EAI_FAIL 

A fatal error (with no recovery possibility) occurred.

EAI_FAMILY 

The specified socket address structure contained an unrecognized address family or the address length was not valid for the specified family.

EAI_MEMORY 

A memory allocation failure occurred while attempting to set aside space for a return value,

EAI_NONAME 

NI_NAMEREQD is set and getnameinfo() cannot find the host's name.

EAI_OVERFLOW 

The buffer pointed to by the node parameter or the service parameter was too small and overflowed.

EAI_SYSTEM 

A system error occurred; the errno variable has been set to indicate that error.

CONFORMANCE

UNIX 03.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

None.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
gai_strerror(), getaddrinfo(), getservbyname(), inet_ntop(), socket()

Miscellaneous:
sockets

PTC MKS Toolkit 10.4 Documentation Build 39.