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_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.
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 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.