lwres_gethostbyname(3)

LWRES_GETHOSTENT(3)           BIND9           LWRES_GETHOSTENT(3)

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

     struct hostent * lwres_gethostbyaddr_r(const char *addr,
                                            int len, int type

     struct hostent * lwres_gethostent_r(struct hostent *resbuf,
                                         char *buf, int buflen

     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 */

ISC                  Last change: 2007-06-18                    1

LWRES_GETHOSTENT(3)           BIND9           LWRES_GETHOSTENT(3)

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

ISC                  Last change: 2007-06-18                    2

LWRES_GETHOSTENT(3)           BIND9           LWRES_GETHOSTENT(3)

     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

ISC                  Last change: 2007-06-18                    3

LWRES_GETHOSTENT(3)           BIND9           LWRES_GETHOSTENT(3)

     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.

AUTHOR

     Internet Systems Consortium, Inc.

COPYRIGHT

     Copyright 8c9 2004, 2005, 2007, 2014-2016 Internet Systems
     Consortium, Inc. ("ISC")
     Copyright 8c9 2001 Internet Software Consortium.

ISC                  Last change: 2007-06-18                    4