The getnameinfo callable service resolves a socket address into a host name and a service name. The TCP/IP Services resolver attempts to resolve the socket address through a name server, if one is present, or through the local data sets.
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1GNI): | 31-bit |
AMODE (BPX4GNI): | 64-bit |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
|
AMODE 64 callers use BPX4GNI with the same parameters.
The name of a field that contains the socket address to be resolved. The socket address consists of an address family, a port number, and an IP address. If the IP address is a link-local IPv6 address, the socket address can also contain a zone index field.
The IP address is resolved to a host name and returned in the Host_Buffer parameter. The port number is resolved to a service name and returned in the Service_Buffer parameter. The zone index field is resolved to an interface name and appended to the host name in the form hostname%scope information.
The format of SockAddr is determined by the domain in which the socket descriptor was created. See BPXYSOCK — Map SOCKADDR structure and constants for additional information on the format of SockAddr.
The name of a fullword that contains the length of the SockAddr parameter.
The name of a field into which the service name, resolved from the port number that was specified as part of the SockAddr parameter, is returned as an EBCDIC string. The maximum length of the returned service name is 32 bytes. If the storage specified is inadequate to contain the resolved service name, the service name is returned only up to the specified storage, and truncation can occur.
The name of a fullword that contains the length of the Service_Buffer parameter. Upon return from the getnameinfo service, Service_Buffer_Length contains the length of the name returned in the Service_Buffer parameter.
If Service_Buffer_Length is zero, nothing is returned in Service_Buffer.
The name of a field into which the host name, resolved from the IP address that was specified as part of the SockAddr parameter, is returned as an EBCDIC string. The maximum length of the returned host name is 255 bytes. If the storage specified is inadequate to contain the resolved host name, the host name is returned only up to the specified storage, and truncation can occur.
If the IP address specified as part of the SockAddr parameter represents a link-local IPv6 address and the zone index specified as part of the SockAddr parameter is nonzero, then the information returned includes scope information in the form hostname%scope information. When the NI_NUMERICSCOPE flag is specified with the Flags parameter, the scope information returned is the zone index value in numeric form (EBCDIC decimal); otherwise, the scope information returned is the interface name associated with the zone index. The maximum length for the combined hostname and scope information remains 255 bytes.
If the NI_NUMERICHOST flag is specified with the Flags parameter, or the host name cannot be located, the IP address, specified as part of the SockAddr parameter, is returned in Host_Buffer in numeric form (EBCDIC decimal).
The name of a fullword that contains the length of the Host_Buffer parameter.
Upon return from the getnameinfo service, Host_Buffer_Length contains the length of the name returned in the Host_Buffer parameter.
If Host_Buffer_Length is zero, nothing is returned in Host_Buffer.
The name of a fullword that contains flags for controlling the resolution of the socket address.
Flag | Value | Description |
---|---|---|
NI_NOFQDN | X'00000001' | Only the host name portion of the FQDN is to be returned for local hosts. |
NI_NUMERICHOST | X'00000002' | The numeric form of the host's address is to be returned, instead of its name. |
NI_NAMEREQD | X'00000004' | If the host name cannot be located, an error or NULL character is to be returned. |
NI_NUMERICSERV | X'00000008' | The numeric form of the service name is to be returned (its port number), instead of its name. |
NI_DGRAM | X'00000010' | The service is a datagram service (SOCK_DGRAM). The default behavior is to assume that the service is a stream service. |
NI_NUMERICSCOPE | X'00000020' | The numeric form of the scope information is to be returned (the zone index), rather than the interface name. |
Return_code | Explanation |
---|---|
EAI_NONAME | The host name does not resolve for the supplied parameters.
One of the following conditions occurred:
|
EAI_BADFLAGS | The flags parameter had an incorrect value. |
EAI_FAMILY | The address family was not recognized, or the address length was not valid for the specified family. |
EAI_MEMORY | A memory allocation failure occurred. |
EAI_AGAIN | The specified host address could not be resolved within the configured time interval, or the resolver address space has not been started. The request can be retried later. |
EAI_FAIL | An unrecoverable error occurred. |
The name of a fullword in which the getnameinfo service stores the reason code. The getnameinfo service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS V2R1.0 Communications Server: IP and SNA Codes.
None.
For an example using this callable service, see BPX1GNI (getnameinfo) example.