ABCDEFGHIJKLMNOPQRSTUVWXYZ

lwres_gethostbyname

LWRES_GETHOSTENT(3)                                        LWRES_GETHOSTENT(3)



NAME
       lwres_gethostbyname,     lwres_gethostbyname2,     lwres_gethostbyaddr,
       lwres_gethostent, lwres_sethostent, lwres_endhostent,  lwres_gethostby-
       name_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_geth-
       ostent_r(), lwres_sethostent_r() and lwres_endhostent_r() provide iter-
       ation over the known host entries on systems that  provide  such  func-
       tionality  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.  Suc-
       cessful calls of the functions return a struct hostentfor the name that
       was looked up.  NULL is returned if  the  lookups  by  lwres_gethostby-
       name() 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.   Suc-
       cessful  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 proto-
       col 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_gethost-
       byaddr_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  mes-
       sages.

       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_geth-
       ostbyname_r(), and lwres_gethostbyaddr_r() respectively.

       The  resolver  daemon  does not currently support any non-DNS name ser-
       vices such as /etc/hosts  or  NIS,  consequently  the  above  functions
       don't, either.



BIND9                            Jun 30, 2000              LWRES_GETHOSTENT(3)