NAME

getnameinfo - get name information

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, unsigned int flags);

DESCRIPTION

The getnameinfo() translates a socket address to a node name and service location, all of which are defined as with getaddrinfo().

The argument sa points to a socket address structure to be translated.

If the argument node is non-NULL and the argument nodelen is nonzero, then the argument node points to a buffer able to contain up to nodelen characters that will receive the node name as a null-terminated string. If the argument node is NULL or the argument nodelen is zero, the node name will not be returned. If the node's name cannot be located, the numeric form of the node's address is returned instead of its name.

If the argument service is non-NULL and the argument servicelen is nonzero, then the argument service points to a buffer able to contain up to servicelen characters that will receive the service name as a null-terminated string. If the argument service is NULL or the argument servicelen is zero, the service name will not be returned. If the service's name cannot be located, the numeric form of the service address (for example, its port number) is returned instead of its name.

The arguments node and service cannot both be NULL.

The flags argument is a flag that changes the default actions of the function. By default the fully-qualified domain name (FQDN) for the host is returned, but

• 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, the numeric form of the host's address is returned instead of its name, under all circumstances.

• If the flag bit NI_NAMEREQD is set, an error is returned if the host's name cannot be located.

• 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, under all circumstances.

• If the flag bit NI_DGRAM is set, this indicates that the service is a datagram service (SOCK_DGRAM). The default behavior is to assume that the service is a stream service (SOCK_STREAM).

Notes:

1. The two NI_NUMERICxxx flags are required to support the "-n" flag that many commands provide.

2. The NI_DGRAM flag is required for the few AF_INET/AF_INET6 port numbers (for example, 512-514) that represent different services for UDP and TCP.

Function getnameinfo() must be thread-safe.

RETURN VALUE

A zero return value for getnameinfo() indicates successful completion; a non-zero return value indicates failure.

On successful completion, function getnameinfo() returns the node and service names, if requested, in the buffers provided. The returned names are always null-terminated strings, and may be truncated if the actual values are longer than can be stored in the buffers provided. If the returned values are to be used as part of any further name resolution (for example, passed to getaddrinfo()), callers must either provide buffers large enough to store any result possible on the system or must check for truncation and handle that case appropriately.

ERRORS

[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.

SEE ALSO

getaddrinfo(), getservbyname(), getservbyport(), inet_ntop(), socket(), <netdb.h>, <sys/socket.h>.

CHANGE HISTORY

First released in Issue 5.2.