The gethostbyname() 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_name
(Input) The pointer to the character string that contains the name of the
host for which information is to be retrieved.
Authorities
Authorization of *R (allow access to the object) to the host aliases file
specified by the HOSTALIASES environment variable.
You also need *X authority to each directory in the path of the host aliases
file.
Return Value
gethostbyname() returns a pointer. Possible values are:
NULL (unsuccessful)
p (successful), where p is a pointer to struct
hostent.
The structure struct hostent is 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 gethostbyname() 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_name
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 gethostbyname() function fails, errno can be set
to:
[EACCES]
Permission denied. The process does not have the
appropriate privileges to the host aliases file specified by the
HOSTALIASES environment variable.
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.
The pointer returned by gethostbyname() points to static storage
that is overwritten on subsequent calls to the gethostbyname(),
gethostbyaddr(), 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 address.
If the host_name parameter does specify a domain qualified name,
the gethostbyaddr() function appends a domain name to the specified
host name, if possible. The domain name that is appended is configured
with System i Navigator or with the CFGTCP menu option 12, Change TCP/IP domain 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() with a nonzero
parameter value was not previously done.
If a sethostent() with a nonzero parameter value was previously
done, the gethostbyname() routine, 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,
gethostbyname() uses a connectionless transport service (for example,
UDP).
A job has a coded character set identifier (CCSID) and a default CCSID. The
default CCSID is the same as the job CCSID unless the job CCSID specifies
65535, which requests that no translation be performed. In this case,
the default CCSID is set by the system based on the language ID in effect for
the job.
If the host information is retrieved from the domain name server, sockets
converts the host name specified by the host_name parameter from the
default (CCSID) to ASCII before communicating with the domain name server. If
the host information is retrieved from the local host table, no conversion is
done on the host name specified by the host_name parameter unless the
CCSID of the job is something other than 65535. In addition, the host names
returned in the hostent structure will be returned in the default CCSID of the
job if they are obtained from the domain name server. For translation to occur
for the host names returned in the hostent structure when they are obtained
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 gethostbyname() function in a multithreaded
environment. See the multithread alternative gethostbyname_r()
function.
gethostbyname() will resolve local host aliases to a domain name
which are then resolved with a query using DNS. See res_hostalias() for more information about aliases.
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 gethostbyname() API is mapped to
qso_gethostbyname98().
Related Information
_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98
compatible interface