gethostbyaddr_r()--Get Host Information for IP Address
BSD 4.3 Syntax
#include <netdb.h>
int gethostbyaddr_r(char *host_address,
int address_length,
int address_type,
struct hostent *hostent_struct_addr,
struct hostent_data *hostent_data_struct_addr)
#define _XOPEN_SOURCE 520
#include <netdb.h>
int gethostbyaddr_r(const void *host_address,
socklen_t address_length,
int address_type,
struct hostent *hostent_struct_addr,
struct hostent_data *hostent_data_struct_addr)
Service Program Name: QSOSRV2
Default Public Authority: *USE
Threadsafe: Yes
The gethostbyaddr_r() 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)
Specifies 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)
Specifies the length of the host_address.
address_type (input)
Specifies the domain type of the host address. Currently, AF_INET
is the only value for this parameter that is supported.
hostent_struct_addr (input/output)
Specifies the pointer to a hostent structure where the results will be
placed. All results must be referenced through this structure.
hostent_data_struct_addr (input/output)
Specifies the pointer to the hostent_data structure, which is used to pass
and preserve results between function calls. The field host_control_blk in the
hostent_data structure must be initialized with hexadecimal zeros before its
initial use. If compatibility with other platforms is required, then the entire
hostent_data structure must initialized with hexadecimal zeros before initial
use.
Authorities
No authorization is required.
Return Value
The gethostbyaddr_r() function returns an integer. Possible values
are:
-1 (unsuccessful call)
0 (successful call)
The struct hostent denoted by
hostent_struct_addr and struct
hostent_datadenoted by
hostent_data_struct_addr are both defined in
<netdb.h>. The structure struct
hostentis defined as:
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 size of an address
in octets (for example, the size of an Internet address is 4 octets).
h_addr_list is a pointer to a NULL-terminated list of pointers, each
of which points to a network address (in network byte order) for the host.
Error Conditions
When the gethostbyaddr_r() function fails, h_errno
(defined in <netdb.h>) can be set to:
[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.
When the gethostbyaddr_r() function fails, errno can be
set to:
[EINVAL]
The hostent_data structure was not properly
initialized with hexadecimal zeros before initial use. For corrective action,
see the description for structure hostent_data.
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"
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.
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 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_r() function will attempt to query the domain name
server for information about a host. If the query fails, the information will
be 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 the host information is obtained from the local host table, the table
is opened and the host information is retrieved (if it exists) from the table.
The table is then closed only if a sethostent_r() call with a non-zero
parameter value was not previously done.
If a sethostent_r() call with a non-zero parameter value was
previously done, the gethostbyaddr_r() routine, when obtaining host
information from the domain name server, will communicate with the domain name
server over a connection-oriented transport service (for example, TCP).
Otherwise, gethostbyaddr_r() will use 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 the globalization topic 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>.
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_r() API is mapped to
qso_gethostbyaddr_r98().
Related Information
_XOPEN_SOURCE--Using _XOPEN_SOURCE for the
UNIX 98 compatible interface