gethostbyaddr()--Get Host Information for IP Address
BSD 4.3 Syntax
#include <netdb.h> struct hostent *gethostbyaddr(char *host_address, int address_length, int address_type)
Service Program Name: QSOSRV2
Default Public Authority: *USE
Threadsafe: No; see Usage Notes.
UNIX® 98 Compatible Syntax
#define _XOPEN_SOURCE 520 #include <netdb.h> struct hostent *gethostbyaddr(const void *host_address, socklen_t address_length, int address_type)
Service Program Name: QSOSRV2
Default Public Authority: *USE
Threadsafe: No; see Usage Notes.
The gethostbyaddr() function is used to retrieve information about a host.
There are two versions of the API, as shown above. The base IBM® i API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro.
Parameters
- host_address
- (Input) The pointer to a structure of type in_addr that
contains the address of the host for which information is to be retrieved.
- address_length
- (Input) The length of the host_address.
- address_type
- (Input) The domain type of the host address. AF_INET is the only value for this parameter that is supported.
Authorities
No authorization is required.
Return Value
gethostbyaddr() returns a pointer. Possible values are:
- NULL (unsuccessful)
- p (successful), where p is a pointer to struct hostent, defined in <netdb.h>.
struct hostent { char *h_name; char **h_aliases; int h_addrtype; int h_length; char **h_addr_list; }; #define h_addr h_addr_list[0]
h_name points to the character string that contains the name of the host. h_aliases is a pointer to a NULL-terminated list of pointers, each of which points to a character string that represents an alternative name for the host. h_addrtype contains the address type of the host (for example, AF_INET). h_length contains the address length. h_addr_list is a pointer to a NULL-terminated list of pointers, each of which points to a network address for the host, in network byte order. Note that the array of address pointers points to structures of type in_addr defined in <netinet/in.h>.
Error Conditions
When gethostbyaddr() fails, h_errno (defined in <netdb.h>) can be set to one of the following:
- [HOST_NOT_FOUND]
The host name specified by the host_address parameter was not found.
- [NO_DATA]
The host name is a valid name, but there is no corresponding IP address.
- [NO_RECOVERY]
An unrecoverable error has occurred.
- [TRY_AGAIN]
The local server did not receive a response from an authoritative server. An attempt at a later time may succeed.
Usage Notes
- System i® Navigator or the
following CL commands can be
used to access the local host table:
- ADDTCPHTE (Add TCP/IP Host Table Entry)
- RMVTCPHTE (Remove TCP/IP Host Table Entry)
- CHGTCPHTE (Change TCP/IP Host Table Entry)
- RNMTCPHTE (Rename TCP/IP Host Table Entry)
- MRGTCPHT (Merge TCP/IP Host Tables)
- CFGTCP (Configure TCP/IP), option "10. Work with TCP/IP host table entries"
- ADDTCPHTE (Add TCP/IP Host Table Entry)
- There are limits to both the number of entries and the size of those entries
returned in the hostent structure. The limits
are defined in <netdb.h> and entries may be truncated.
The string and pointer arrays should be traversed by looking for null terminators
rather than relying on hardcoded limits.
- The pointer returned by gethostbyaddr() points to static storage
that is overwritten on subsequent calls to the gethostbyaddr(),
gethostbyname(), or gethostent() functions.
- There are two sources from which host information can be obtained: the
domain name server, and the local host table. The path taken depends on
whether an IP address is configured for a name server with System i Navigator or with option 12, Change TCP/IP domain information, on the Configure TCP/IP (CFGTCP) menu.
Note: A person with a UNIX background would expect this information to exist in a file known as /etc/resolv.conf. If the IP address is found (indicating that the local network is a domain network), the gethostbyaddr() function attempts to query the domain name server for information about a host. If the query fails, the information is obtained from the local host table. If the name server IP address is not found (indicating that local network is a flat network), the local host table is used to obtain the host information.
- When host information is retrieved from the local host table, the opened
table is only closed if a sethostent() with a nonzero parameter value
was not previously done.
- If a sethostent() with a nonzero parameter value was previously
done, gethostbyaddr(), when obtaining host information from the domain
name server, communicates with the domain name server over a
connection-oriented transport service (for example, TCP). Otherwise,
gethostbyaddr() uses a connectionless transport service (for example,
UDP).
- If the host information is obtained from the domain name server, the
information is returned in the default coded character set identifier (CCSID)
currently in effect for the job. (The default CCSID is the same as the job
CCSID unless 65535 is requested, in which case the default CCSID is set based
on the language ID of the job. See globalization for more information.) If the
host information is retrieved from the local host table, the default CCSID of
the job is not used. To request translation of the host information when it is
retrieved from the local host table, you must use a job CCSID of something
other than 65535.
- Address families are defined in <sys/socket.h>, and
the in_addr structure is defined in
<netinet/in.h>.
- Do not use the gethostbyaddr() function in a multithreaded
environment. See the multithread alternative gethostbyaddr_r()
function.
- When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the gethostbyaddr() API is mapped to qso_gethostbyaddr98().
Related Information
- _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98
compatible interface
- hstrerror()--Retrieve Resolver Error
Message
- res_hostalias()--Retrieve the host alias
- gethostbyname()--Get Host Information for Host
Name
- gethostent()--Get Next Entry from Local Host Table
- sethostent()--Open Local Host Table
- endhostent()--Close Local Host Table
- getaddrinfo()--Get Address Information
- getnameinfo()--Get Name Information for Socket Address
API introduced: V3R1