gethostent_r()--Get Next Entry from Local Host Table
Syntax
#include <netdb.h> int gethostent_r(struct hostent *hostent_struct_addr, struct hostent_data *hostent_data_struct_addr)
Service Program Name: QSOSRV2
Default Public Authority: *USE
Threadsafe: Yes
The gethostent_r() function is used to retrieve information from the local host table. When the gethostent_r() is first called, the table is opened, and the first entry is returned. Each subsequent call of gethostent_r() results in the next entry in the table being returned. To close the table, use endhostent_r().
Parameters
- struct hostent *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.
- struct hostent_data *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 to hexadecimal zeros before initial use.
Authorities
No authorization is required.
Return Value
The gethostent_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_data denoted by hostent_data_struct_addr are both defined in <netdb.h>. The structure struct hostent is 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 or AF_INET6).
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.
Note that the array of address pointers points to structures of type
in_addr or in6_addr defined in <netinet/in.h>.
Error Conditions
When the gethostent_r() function fails, errno can be set to:
- [EINVAL]
The hostent_data structure was not properly initialized to 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.
An exception to these limits is made for gethostent() and gethostent_r(). If there are more than NETDB_MAX_ARRAY_SIZE aliases in an entry, then the first NETDB_MAX_ARRAY_SIZE aliases will be returned in the struct hostent structure. The next call to gethostent() will then return the same address with the next NETDB_MAX_ARRAY_SIZE aliases. Each subsequent call to gethostent() will return additional aliases until all the aliases in the entry have been returned.
- A coded character set identifier (CCSID) of 65535 for the job requests that no translation be performed. For translation to occur for the host names returned in the hostent structure, the job CCSID must be something other than 65535.
Related Information
- gethostbyaddr_r()--Get Host Information for IP
Address
- gethostbyname_r()--Get Host Information for Host
Name
- endhostent_r()--Close Local Host Table
- sethostent_r()--Open Local Host Table
- getaddrinfo()--Get Address Information
- getnameinfo()--Get Name Information for Socket Address
API introduced: V3R1