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