endhostent, freehostent, gethostbyaddr, gethostbyname, gethostent, getipnodebyaddr, getipnodebyname, sethostent - network host database functions
#include <netdb.h>
struct hostent *gethostent(void);
void sethostent(int stayopen);
void endhostent(void);
struct hostent *getipnodebyaddr (const void *addr, socklen_t len, int type, int *error_num);
struct hostent *gethostbyaddr(const void *addr, socklen_t len, int type);
struct hostent *getipnodebyname (const char *name, int type, int flags, int *error_num);
struct hostent *gethostbyname(const char *name);
void freehostent(struct hostent *ptr);
These functions enable applications to retrieve information about hosts. This information is considered to be stored in a database that can be accessed sequentially or randomly. Implementation of this database is unspecified.
- Note:
- In many cases it will be implemented by the Domain Name System, see referenced documents RFC 1034, RFC 1035 and RFC 1886.
Entries are returned in hostent structures. The
sethostent() function opens a connection to the database and sets the next entry for retrieval to the first entry in the database. If the stayopen argument is non-zero, the connection will not be closed by a call togethostent() ,getipnodebyname() ,gethostbyname() ,getipnodebyaddr() , orgethostbyaddr() .The
gethostent() function reads the next entry in the database, opening a connection to the database if necessary.The
endhostent() function closes the connection to the database.The
getipnodebyaddr() function returns the entry containing addresses of address family type for the host with address addr, opening a connection to the database if necessary. Argument len contains the length of the address pointed to by addr. If an error occurs, the appropriate error code is returned in error_num. Functiongetipnodebyaddr() is thread-safe.The
gethostbyaddr() function is a legacy function whose use is deprecated in favour ofgetipnodebyaddr() . It returns an entry containing addresses of address family type for the host with address addr. len contains the length of the address pointed to by addr. It need not be thread-safe.The addr argument of
getipnodebyaddr() orgethostbyaddr() must be an in_addr structure when type is AF_INET, and must be an in6_addr structure when type is AF_INET6. It contains a binary format (that is, not null-terminated) address in network byte order. Thegethostbyaddr() function is not guaranteed to return addresses of address families other than AF_INET, even when such addresses exist in the database.If
gethostbyaddr() orgetipnodebyaddr() returns a record then its h_addrtype field is the same as the type argument that was passed to the function, and its h_addr_list field lists a single address that is a copy of the addr argument that was passed to the function. If type is AF_INET6 and addr is an IPv4-mapped IPv6 address or an IPv4-compatible IPv6 address then the h_name and h_aliases fields are those that would have been returned for address family AF_INET and address equal to the last four bytes of addr.If
getipnodebyaddr() orgethostbyaddr() is called with addr containing the IPv6 unspecified address (all bytes zero) then no query is performed and the function fails with error [HOST_NOT_FOUND].The
getipnodebyname() function returns the entry containing addresses of address family type for the host with name name, opening a connection to the database if necessary. Argument flags affects what information is returned. If an error occurs, the appropriate error code is returned in error_num. Functiongetipnodebyname() is thread-safe.The
gethostbyname() function is a legacy function whose use is deprecated in favour ofgetipnodebyname() . It returns an entry containing addresses of address family AF_INET for the host with name name. It need not be thread-safe.The name argument of
getipnodebyname() can be either a node name or a numeric address string. For IPv4 a numeric address string will be in the dotted-decimal notation described on the man page forinet_addr() . For IPv6 a numeric address string will be in one of the standard IPv6 text forms described on the man page forinet_pton() . The name argument ofgethostbyname() can be a node name; the behavior ofgethostbyname() when passed a numeric address string is unspecified.If name is a dotted-decimal IPv4 address and af equals AF_INET, or name is an IPv6 hex address and af equals AF_INET6, the members of the returned hostent structure are as follows:
- h_name
- points to a copy of the name argument
- h_aliases
- is a NULL pointer
- h_addrtype
- is a copy of the type argument
- h_length
- is either 4 (for AF_INET) or 16 (for AF_INET6)
- h_addr_list[0]
- is a pointer to the 4-byte or 16-byte binary address
- h_addr_list[1]
- is a NULL pointer
If name is a dotted-decimal IPv4 address and af equals AF_INET6 and AI_V4MAPPED is set in flags, an IPv4-mapped IPv6 address is returned, and:
- h_name
- points to an IPv6 hex address containing the IPv4-mapped IPv6 address
- h_aliases
- is a NULL pointer
- h_addrtype
- is AF_INET6
- h_length
- is 16
- h_addr_list[0]
- is a pointer to the 16-byte binary address
- h_addr_list[1]
- is a NULL pointer
If name is a dotted-decimal IPv4 address and af equals AF_INET6 and AI_V4MAPPED is not set, then NULL is returned with error [HOST_NOT_FOUND].
It is an error when name is an IPv6 hex address and af equals AF_INET. The function's return value is a NULL pointer with error [HOST_NOT_FOUND].
If name is not a numeric address string and is an alias for a valid host name then
getipnodebyname() orgethostbyname() returns information about the host name to which the alias refers, and name is included in the list of aliases returned.If name is a node name then operation of the
getipnodebyname() function is modified by the value of the flags argument, as follows:
- If flags is 0 and type is AF_INET, then a query is made for IPv4 addresses. If it is successful, the IPv4 addresses are returned and the h_length member of the hostent structure will be 4. Otherwise, the function returns a NULL pointer.
- If flags is 0 and if type is AF_INET6, then a query is made for IPv6 addresses. If it is successful, the IPv6 addresses are returned and the h_length member of the hostent structure will be 16. If unsuccessful, the function returns a NULL pointer.
- If the AI_V4MAPPED flag is set and type is AF_INET6, then a query is made for IPv6 addresses. If it is successful, the IPv6 addresses are returned, and no query is made for IPv4 addresses. If it is not successful, a query is made for IPv4 addresses and any found are returned as IPv4-mapped IPv6 addresses. h_length will be 16 in either case of addresses being returned. The AI_V4MAPPED flag is ignored unless type is AF_INET6.
- If the AI_ALL and AI_V4MAPPED flags are both set and type is AF_INET6, then a query is made for IPv6 addresses, and any found are returned. Another query is then made for IPv4 addresses, and any found are returned as IPv4-mapped IPv6 addresses, and h_length is 16. Only if both queries fail does the function return a NULL pointer. This flag is ignored unless type is AF_INET6.
- The AI_ADDRCONFIG flag specifies that a query for IPv6 addresses should be made only if the node has at least one IPv6 source address configured, and that a query for IPv4 addresses should be made only if the node has at least one IPv4 source address configured.
- If the AI_V4MAPPED and AI_ADDRCONFIG flags are both set and type is AF_INET6, then
- If the node has at least one IPv6 source address configured, a query is made for IPv6 addresses
- If it is successful, the IPv6 addresses are returned and no query is made for IPv4 addresses
- If the node has no IPv6 source address configured, or if the query for IPv6 addresses is not successful, then if the node has at least one IPv4 source address configured, a query is made for IPv4 addresses and any found are returned as IPv4-mapped IPv6 addresses.
h_length will be 16 in either case of addresses being returned.
- Macro AI_DEFAULT is defined as the logical OR of AI_V4MAPPED and AI_ADDRCONFIG.
- Note:
- It is intended that setting flags to AI_DEFAULT will be appropriate for most applications.
The
freehostent() function frees the memory occupied by the hostent structure pointed to by hostent and any structures pointed to from that structure, provided that hostent was obtained by a call togetipnodebyaddr() orgetipnodebyname() . Applications must not callfreehostent() except to pass it a pointer that was obtained fromgetipnodebyaddr() orgetipnodebyname() .
On successful completion,getipnodebyaddr() ,gethostbyaddr() ,getipnodebyname() ,gethostbyname() andgethostent() return a pointer to a hostent structure if the requested entry was found, and a null pointer if the end of the database was reached or the requested entry was not found.On unsuccessful completion,
getipnodebyaddr() andgetipnodebyname() will set their error_num argument to indicate the error, whilegethostbyaddr() andgethostbyname() will set h_errno to indicate it.
No errors are defined forendhostent() ,gethostent() andsethostent() .The
getipnodebyaddr() ,getipnodebyname() ,gethostbyaddr() andgethostbyname() functions will fail in the following cases. Functionsgetipnodebyaddr() andgetipnodebyname() will return the value shown in the list below in error_num; functionsgethostbyaddr() andgethostbyname() will set h_errno to that value. Any changes to errno are unspecified.
- [HOST_NOT_FOUND]
No such host is known.
- [NO_DATA]
- The server recognised the request and the name but no address is available. Another type of request to the name server for the domain might return an answer.
- [NO_RECOVERY]
- An unexpected server failure occurred which can not be recovered.
- [TRY_AGAIN]
- A temporary and possibly transient error occurred, such as a failure of a server to respond.
The hostent structure returned bygetipnodebyaddr() andgetipnodebyname() , and any structures pointed to from those structures, are dynamically allocated. Applications should callfreehostent() to free the memory used by these structures when they are no longer needed.The
gethostent() ,gethostbyaddr() , andgethostbyname() functions may return pointers to static data, which may be overwritten by subsequent calls to any of these functions. Applications must not callfreehostent() for this area.
endservent() ,htonl() ,inet_addr() ,<netdb.h> .
First released in Issue 4.Specifications of
getipnodebyaddr() .getipnodebyname() andfreehostent() were added in Issue 5.2.
Contents | Next section | Index |