| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
RFC2553 |
both | z/OS® V1R4 |
#define _OPEN_SYS_SOCK_IPV6
#include <sys/socket.h>
#include <netdb.h>
int getnameinfo(cons struct sockaddr *sa, socklen_t salen,
char *host, socklen_t hostlen,
char *serv, socklen_t servlen,
int flags);SUSV3
#define _POSIX_C_SOURCE 200112L
#include <sys/socket.h>
#include <netdb.h>
int getnameinfo(cons struct sockaddr *__restrict__ sa, socklen_t salen,
char *__restrict__ host, socklen_t hostlen, char *__restrict__ serv,
socklen_t servlen, int flags);The getnameinfo() function translates a socket address to a node name and service location. The getnameinfo() 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 sa argument 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 sockaddr_in6 structure may also contain a zone index value, if the IPv6 address represented by this sockaddr_in6 structure is a link-local address. The salen argument gives the length of the sockaddr_in or sockaddr_in6 structure.
If the socket address structure contains an IPv4-mapped IPv6 address or an IPv4-compatible IPv6 address, the embedded IPv4 address is extracted and the the lookup is performed on the IPv4 address.
The node name associated with the IP address is returned in the buffer pointed to by the host argument. The caller provides the size of this buffer in the hostlen argument. The caller specifies not to return the node name by specifying a zero value for hostlen or a null host argument. If the node's name cannot be located, the numeric form of the node's address is returned instead of its name. If a zone index value was present in the sockaddr_in6 structure, the numeric form of the zone index, or the interface name associated with the zone index, is appended to the node name returned, using the format node name%scope information.
If the size of the buffer specified in the hostlen argument is insufficient to contain the entire node name, or node name and scope information combination, up to hostlen characters will be copied into the buffer as a null terminated string.
The service name associated with the port number is returned in the buffer pointed to by the serv argument, and the servlen argument gives the length of this buffer. The caller specifies not to the service name by specifying a zero value for servlen or a null serv argument. If the service's name cannot be located, the numeric of the service address (for example, its port number) will be returned instead of its name.
If the size of the buffer specified in the servlen argument is insufficient to contain the entire service name, up to servlen characters will be copied into the buffer as a null terminated string.
The final argument, flags, is a flag that changes the default actions of this function. By default the fully-qualified domain name (FQDN) for the host is 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, the numeric form of the host's address is returned instead of its name.
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.
If the flag bit NI_NUMERICSCOPE is set, the numeric form of the scope identifier is returned (for example, zone index) instead of its name. This flag is ignored if the sa argument is not an IPv6 address.
If the flag bit NI_DGRAM is set, this 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 flag is required for the few ports (for example, [512,514]) that have different services for UDP and TCP.
Special behavior for SUSv3: Starting with z/OS V1.9, environment variable _EDC_SUSV3 can be used to control the behavior of getnameinfo() with respect to detecting if the buffer pointed to by the host or serv argument is too small to contain the entire resolved name. The function will fail and return EAI_OVERFLOW. By default, getnameinfo() will truncate the values pointed to by host or serv and return successfully. When _EDC_SUSV3 is set to 1, getnameinfo() will check for insufficient size buffers to contain the resolved name.
Upon successful completion, getnameinfo() returns the node and service names, if requested, in the buffers provided. The returned names are always null-terminated strings.
A zero return value for getnameinfo() indicates successful completion; a non-zero return value indicates failure. The possible values for the failures are listed as follows.
For more information on the above error codes, refer to z/OS V2R1.0 Communications Server: IP and SNA Codes.