Jun 30, 2000
lwres_gethostent
3
BIND9
2004
2005
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 &mdash; 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 &mdash; 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` &mdash; 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` &mdash; 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.