lwres_gethostent

## Name

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

## Synopsis

    #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 lwres_sethostent(` | int | stayopen`)`;

`void lwres_endhostent(` |  | `)`;

`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(` |  | `)`;

## 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.