gethostbyname_r()--Get Host Information for Host Name
BSD 4.3 Syntax
#include <netdb.h> int gethostbyname_r(char *host_name, struct hostent *hostent_struct_addr, struct hostent_data *hostent_data_struct_addr)
Service Program Name: QSOSRV2
Default Public Authority: *USE
UNIX® 98 Compatible Syntax
#define _XOPEN_SOURCE 520 #include <netdb.h> int gethostbyname_r(const char *host_name, struct hostent *hostent_struct_addr, struct hostent_data *hostent_data_struct_addr)
Service Program Name: QSOSRV2
Default Public Authority: *USE
The gethostbyname_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.
- host_name (input)
- Specifies the pointer to the character string that contains the name of the
host for which information is to be retrieved.
- 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 be initialized with hexadecimal zeros before initial use.
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.
The gethostbyname_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
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.
When the gethostbyname_r() function fails, h_errno (defined in <netdb.h>) can be set to:
The host name specified by the host_name parameter was not found.
The host name is a valid name, but there is no corresponding IP address.
An unrecoverable error has occurred.
The local server did not receive a response from an authoritative server. An attempt at a later time may succeed.
When the gethostbyname_r() function fails, errno can be set to:
Permission denied. The process does not have the appropriate privileges to the host aliases file specified by the HOSTALIASES environment variable.
The hostent_data structure was not initialized with hexadecimal zeros before initial use. For corrective action, see the description for structure hostent_data.
- 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
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 address.
- If the host_name parameter does specify a domain qualified name,
the gethostbyaddr_r() function will append a domain name to the
specified host name, if possible. The domain name that will be 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_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 gethostbyname_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, gethostbyname_r() will use 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
If the host information is retrieved from the domain name server, sockets converts the host name specified by the host_name parameter 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, host names returned in the hostent 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
- gethostbyname_r() 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_r() API is mapped to qso_gethostbyname_r98().
- _XOPEN_SOURCE--Using _XOPEN_SOURCE for the
UNIX 98 compatible interface
- hstrerror()--Retrieve Resolver Error
- res_hostalias()--Retrieve the host alias
- endhostent_r()--Close Local Host Table
- gethostbyaddr_r()--Get Host Information for IP
- gethostent_r()--Get Next Entry from Local Host Table
- sethostent_r()--Open Local Host Table
- getaddrinfo()--Get Address Information
- getnameinfo()--Get Name Information for Socket Address
API introduced: V3R1