LWRES_GETHOSTENT(3)LWRES_GETHOSTENT(3)NAME
lwres_gethostbyname, lwres_gethostbyname2, lwres_gethost-
byaddr, lwres_gethostent, lwres_sethostent, lwres_endhos-
tent, 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 *res-
buf, 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 (nick-
names) 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_endhos-
tent(), 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_geth-
ostbyaddr(). addr is an address of length len bytes and
protocol family type -- PF_INET or PF_INET6. lwres_geth-
ostbyname_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_gethostby-
name_r() . buf is a buffer of length len bytes which is
used to store the h_name, h_aliases, and h_addr_list ele-
ments of the struct hostent returned in resbuf. Success-
ful 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 cre-
ated.
RETURN VALUES
The functions lwres_gethostbyname(), lwres_gethostby-
name2(), 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 suit-
able 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_gethost-
byname_r() and lwres_gethostbyaddr_r() set the global
variable errno to ERANGE.
SEE ALSOgethostent(3), lwres_getipnode(3), lwres_hstrerror(3)BUGSlwres_gethostbyname(), lwres_gethostbyname2(), lwres_geth-
ostbyaddr() 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_gethostby-
name_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)
