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
#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); |
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_nameThe official (canonical) name of the host.
h_aliasesA NULL-terminated array of alternate names (nicknames) for the host.
h_addrtypeThe type of address being returned — PF_INET or PF_INET6.
h_lengthThe length of the address in bytes.
h_addr_listA 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.
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_FOUNDThe host or address was not found.
TRY_AGAINA recoverable error occurred, e.g., a timeout. Retrying the lookup may succeed.
NO_RECOVERYA non-recoverable error occurred.
NO_DATAThe 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.
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.