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 

       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 .

       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
       :

       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.



BIND9                      Jun 30, 2000       LWRES_GETHOSTENT(3)