June 18, 2007
lwres_gethostent 3 BIND9
2004 2005 2007 2014 Internet Systems Consortium, Inc. ("ISC")
2001 Internet Software Consortium.
lwres_gethostbyname lwres_gethostbyname2 lwres_gethostbyaddr lwres_gethostent lwres_sethostent lwres_endhostent lwres_gethostbyname_r lwres_gethostbyaddr_r lwres_gethostent_r lwres_sethostent_r lwres_endhostent_r lightweight resolver get network host entry

    #include <lwres/netdb.h>

struct hostent * `lwres_gethostbyname` const char *name struct hostent * `lwres_gethostbyname2` const char *name int af struct hostent * `lwres_gethostbyaddr` const char *addr int len int type struct hostent * `lwres_gethostent` void void `lwres_sethostent` int stayopen void `lwres_endhostent` void struct hostent * `lwres_gethostbyname_r` const char *name struct hostent *resbuf char *buf int buflen int *error struct hostent * `lwres_gethostbyaddr_r` const char *addr int len int type struct hostent *resbuf char *buf int buflen int *error struct hostent * `lwres_gethostent_r` struct hostent *resbuf char *buf int buflen int *error void `lwres_sethostent_r` int stayopen void `lwres_endhostent_r` void

## DESCRIPTION

These functions provide hostname-to-address and address-to-hostname lookups by means of the lightweight resolver. They are similar to the standard gethostent 3 functions provided by most operating systems. They use a struct hostent which is usually defined in `<namedb.h>`.

    struct  hostent {
            char    *h_name;        /* official name of host */
            char    **h_aliases;    /* alias list */
            int     h_addrtype;     /* host address type */
            int     h_length;       /* length of address */
            char    **h_addr_list;  /* list of addresses from name server */
    };
    #define h_addr  h_addr_list[0]  /* address, for backward compatibility */

The members of this structure are:

`h_name`

  The official (canonical) name of the host.

`h_aliases`

  A NULL-terminated array of alternate names (nicknames) for the host.

`h_addrtype`

  The type of address being returned — PF_INET or PF_INET6.

`h_length`

  The length of the address in bytes.

`h_addr_list`

  A NULL terminated array of network addresses for the host. Host addresses are returned in network byte order.

For backward compatibility with very old software, `h_addr` is the first address in `h_addr_list.`

`lwres_gethostent()`, `lwres_sethostent()`, `lwres_endhostent()`, `lwres_gethostent_r()`, `lwres_sethostent_r()` and `lwres_endhostent_r()` provide iteration over the known host entries on systems that provide such functionality through facilities like `/etc/hosts` or NIS. The lightweight resolver does not currently implement these functions; it only provides them as stub functions that always return failure.

`lwres_gethostbyname()` and `lwres_gethostbyname2()` look up the hostname name. `lwres_gethostbyname()` always looks for an IPv4 address while `lwres_gethostbyname2()` looks for an address of protocol family af: either PF_INET or PF_INET6 — IPv4 or IPV6 addresses respectively. Successful calls of the functions return a struct hostentfor the name that was looked up. NULL is returned if the lookups by `lwres_gethostbyname()` or `lwres_gethostbyname2()` fail.

Reverse lookups of addresses are performed by `lwres_gethostbyaddr()`. addr is an address of length len bytes and protocol family type — PF_INET or PF_INET6. `lwres_gethostbyname_r()` is a thread-safe function for forward lookups. If an error occurs, an error code is returned in *error. resbuf is a pointer to a struct hostent which is initialised by a successful call to `lwres_gethostbyname_r()`. buf is a buffer of length len bytes which is used to store the `h_name`, `h_aliases`, and `h_addr_list` elements of the struct hostent returned in resbuf. Successful calls to `lwres_gethostbyname_r()` return resbuf, which is a pointer to the struct hostent it created.

`lwres_gethostbyaddr_r()` is a thread-safe function that performs a reverse lookup of address addr which is len bytes long and is of protocol family type — PF_INET or PF_INET6. If an error occurs, the error code is returned in *error. The other function parameters are identical to those in `lwres_gethostbyname_r()`. resbuf is a pointer to a struct hostent which is initialised by a successful call to `lwres_gethostbyaddr_r()`. buf is a buffer of length len bytes which is used to store the `h_name`, `h_aliases`, and `h_addr_list` elements of the struct hostent returned in resbuf. Successful calls to `lwres_gethostbyaddr_r()` return resbuf, which is a pointer to the `struct hostent()` it created.

## RETURN VALUES

The functions `lwres_gethostbyname()`, `lwres_gethostbyname2()`, `lwres_gethostbyaddr()`, and `lwres_gethostent()` return NULL to indicate an error. In this case the global variable lwres_h_errno will contain one of the following error codes defined in `<lwres/netdb.h>`:

`HOST_NOT_FOUND`

  The host or address was not found.

`TRY_AGAIN`

  A recoverable error occurred, e.g., a timeout. Retrying the lookup may succeed.

`NO_RECOVERY`

  A non-recoverable error occurred.

`NO_DATA`

  The name exists, but has no address information associated with it (or vice versa in the case of a reverse lookup). The code NO_ADDRESS is accepted as a synonym for NO_DATA for backwards compatibility.

lwres_hstrerror 3 translates these error codes to suitable error messages.

`lwres_gethostent()` and `lwres_gethostent_r()` always return NULL.

Successful calls to `lwres_gethostbyname_r()` and `lwres_gethostbyaddr_r()` return resbuf, a pointer to the struct hostent that was initialised by these functions. They return NULL if the lookups fail or if buf was too small to hold the list of addresses and names referenced by the `h_name`, `h_aliases`, and `h_addr_list` elements of the struct hostent. If buf was too small, both `lwres_gethostbyname_r()` and `lwres_gethostbyaddr_r()` set the global variable errno to ERANGE.

## SEE ALSO

gethostent 3 , lwres_getipnode 3 , lwres_hstrerror 3

## BUGS

`lwres_gethostbyname()`, `lwres_gethostbyname2()`, `lwres_gethostbyaddr()` and `lwres_endhostent()` are not thread safe; they return pointers to static data and provide error codes through a global variable. Thread-safe versions for name and address lookup are provided by `lwres_gethostbyname_r()`, and `lwres_gethostbyaddr_r()` respectively.

The resolver daemon does not currently support any non-DNS name services such as `/etc/hosts` or NIS, consequently the above functions don't, either.