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

       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.

COPYRIGHT

       Copyright © 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
       Copyright © 2001 Internet Software Consortium.