getnameinfo (BPX1GNI, BPX4GNI) — Get the host name and service name from a socket address

Function

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.

Requirements

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.

Format

The syntax format is as follows:

CALL BPX1GNI,(SockAddr,
              SockAddr_Length,
              Service_Buffer,
              Service_Buffer_Length,
              Host_Buffer,
              Host_Buffer_Length,
              Flags,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4GNI with the same parameters.

Parameters

SockAddr

Supplied parameter

Type:: Structure
Length:: Specified by SockAddr_Length

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.

SockAddr_Length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the SockAddr parameter.

Service_Buffer

Supplied and returned parameter

Type:: Character
Character set:: EBCDIC
Length:: Specified by Service_Buffer_Length

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.

Service_Buffer_Length

Supplied and returned parameter

Type:: Integer
Length:: Fullword

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.

Host_Buffer

Supplied and returned parameter

Type:: Character
Character set:: EBCDIC
Length:: Specified by Node_Buffer_Length

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

Host_Buffer_Length

Supplied and returned parameter

Type:: Integer
Length:: Fullword

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.

Flags

Supplied parameter

Type:: Integer
Length:: Fullword

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_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the getnameinfo service returns one of the following:

0, if the request is successful.
-1, if the request is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the getnameinfo service stores the return code. The getnameinfo service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS Communications Server: IP and SNA Codes. The getnameinfo service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EAI_NONAME	The host name does not resolve for the supplied parameters. One of the following conditions occurred: NI_NAMEREQD is set, and the host name cannot be located. Both host name and service name were null.
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.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

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 Communications Server: IP and SNA Codes.

Usage notes

The getnameinfo service supports a fully thread-safe environment.
You must specify either Service_Buffer and Service_Buffer_Length, or Host_Buffer and Host_Buffer_Length.

getnameinfo (BPX1GNI, BPX4GNI) — Get the host name and service name from a socket address

Function

Requirements

Format

Parameters

Usage notes

Related services

Characteristics and restrictions

Examples