NAME

endhostent, freehostent, gethostbyaddr, gethostbyname, gethostent, getipnodebyaddr, getipnodebyname, sethostent - network host database functions

SYNOPSIS

#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);

DESCRIPTION

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 to gethostent(), getipnodebyname(), gethostbyname(), getipnodebyaddr(), or gethostbyaddr().

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. Function getipnodebyaddr() is thread-safe.

The gethostbyaddr() function is a legacy function whose use is deprecated in favour of getipnodebyaddr(). 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() or gethostbyaddr() 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. The gethostbyaddr() function is not guaranteed to return addresses of address families other than AF_INET, even when such addresses exist in the database.

If gethostbyaddr() or getipnodebyaddr() 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() or gethostbyaddr() 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. Function getipnodebyname() is thread-safe.

The gethostbyname() function is a legacy function whose use is deprecated in favour of getipnodebyname(). 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 for inet_addr(). For IPv6 a numeric address string will be in one of the standard IPv6 text forms described on the man page for inet_pton(). The name argument of gethostbyname() can be a node name; the behavior of gethostbyname() 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() or gethostbyname() 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 to getipnodebyaddr() or getipnodebyname(). Applications must not call freehostent() except to pass it a pointer that was obtained from getipnodebyaddr() or getipnodebyname().

RETURN VALUE

On successful completion, getipnodebyaddr(), gethostbyaddr(), getipnodebyname(), gethostbyname() and gethostent() 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() and getipnodebyname() will set their error_num argument to indicate the error, while gethostbyaddr() and gethostbyname() will set h_errno to indicate it.

ERRORS

No errors are defined for endhostent(), gethostent() and sethostent().

The getipnodebyaddr(), getipnodebyname(), gethostbyaddr() and gethostbyname() functions will fail in the following cases. Functions getipnodebyaddr() and getipnodebyname() will return the value shown in the list below in error_num; functions gethostbyaddr() and gethostbyname() 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.

APPLICATION USAGE

The hostent structure returned by getipnodebyaddr() and getipnodebyname(), and any structures pointed to from those structures, are dynamically allocated. Applications should call freehostent() to free the memory used by these structures when they are no longer needed.

The gethostent(), gethostbyaddr(), and gethostbyname() functions may return pointers to static data, which may be overwritten by subsequent calls to any of these functions. Applications must not call freehostent() for this area.

SEE ALSO

endservent(), htonl(), inet_addr(), <netdb.h>.

CHANGE HISTORY

First released in Issue 4.

Specifications of getipnodebyaddr(). getipnodebyname() and freehostent() were added in Issue 5.2.