gethostbyaddr (BPX1GHA, BPX4GHA) Get the IP address and alias of a host name for the specified IP address

Function

The gethostbyaddr callable service returns the alias names and the internet addresses of a host whose address is specified as input. The TCP/IP Services resolver tries to resolve the host address through a name server, if one is present. If a name server is not present, the resolver searches for the HOSTS.ADDRINFO data set (or /etc hosts data set) until a matching host address is found, or until an EOF marker is reached.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1GHA):	31-bit
AMODE (BPX4GHA):	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

CALL BPX1GHA,(Address,
              Address_length,
              Hostent_ptr,
              Domain,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4GHA with the same parameters. Hostent_ptr is a doubleword pointer field.

Parameters

Address

Supplied parameter

Type:: Hexadecimal string
Length:: Length specified by Address_length

The name of a hexadecimal string that contains the IP address of the host being queried. This is a fullword field for IPv4 addresses. (IPv6 addresses are not supported.)

Address_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the address that is being passed in the Address parameter. This is 4 for IPv4 addresses. No other addresses are currently supported.

Hostent_ptr

Returned parameter

Type:: Pointer
Length:: Fullword (doubleword)

The name of a field that contains a pointer to the Hostent structure. The Hostent structure contains the following fields:

h_name: The address of the host name returned by the service. The host name is a variable-length field that is ended by X'00'.
h_aliases: The address of a list of addresses that point to the alias names returned by the service. The list is ended by the pointer X'00000000'. Each alias name is a variable-length field that is ended by X'00'.
h_addrtype: The value 2, which signifies AF_INET.
h_length: The length of the host internet addresses pointed to by h_addr_list.
h_addr_list: The address of a list of addresses that point to the host internet addresses returned by this service. This list is ended by the pointer X'00000000'.

Domain

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the numeric value of the domain for this query. Only the value of 2 (AF_INET) is currently supported.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the gethostbyaddr 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 gethostbyaddr service stores the return code. The gethostbyaddr service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The gethostbyaddr service can return one of the following values in the Return_code parameter:

Return_code	Explanation
HOST_NOT_FOUND	The host name specified by the Address parameter was not found.
TRY_AGAIN	The host address specified by the Address parameter could not be resolved within the configured time interval. The request can be retried later.
NO_RECOVERY	An unrecoverable error occurred.
NO_DATA	The requested Address parameter is valid, but it does not have a record at the name server.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the gethostbyaddr service stores the reason code. The gethostbyaddr service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value.

Reason codes lower than decimal 4096 are z/OS UNIX System Services return codes, and are documented in z/OS UNIX System Services Messages and Codes. Reason codes greater than decimal 4096 are returned by the resolver, and are described in z/OS V2R1.0 Communications Server: IP and SNA Codes.

An assembler macro (EZBREHST) that contains the hostent structure, gethostbyxxxx return codes, and reason codes is shipped in the installation's MACLIB SMP/E DDEF location.

Related services

gethostbyname (BPX1GHN, BPX4GHN) Get IP information for specified host domain names

Characteristics and restrictions

The gethostbyaddr service does not support a fully reentrant environment. The Hostent structure that is returned is allocated at a task level. This area will be reused on subsequent gethostbyaddr calls. Therefore, within a task only one call can be occurring at a time. For example, if the mainline task has issued a gethostbyaddr call that has not completed, a signal handler that interrupts that thread's processing should not invoke the gethostbyaddr service.

Examples

For an example using this callable service, see BPX1GHA (gethostbyaddr) example.