Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
$Id: lwres_gethostent.3,v 1.7 2001/01/09 21:49:49 bwelling Exp $
.Dd Jun 30, 2000 .Dt LWRES_GETHOSTENT 3 .Os BIND9 9 .Sh NAME .Nm lwres_gethostbyname , .Nm lwres_gethostbyname2 , .Nm lwres_gethostbyaddr , .Nm lwres_gethostent , .Nm lwres_sethostent , .Nm lwres_endhostent , .Nm lwres_gethostbyname_r , .Nm lwres_gethostbyaddr_r , .Nm lwres_gethostent_r , .Nm lwres_sethostent_r , .Nm lwres_endhostent_r .Nd lightweight resolver get network host entry .Sh SYNOPSIS .Fd #include <lwres/netdb.h> .Fd .Ft struct hostent * .Fo lwres_gethostbyname .Fa "const char *name" .Fc .Ft struct hostent * .Fo lwres_gethostbyname2 .Fa "const char *name" .Fa "int af" .Fc .Ft struct hostent * .Fo lwres_gethostbyaddr .Fa "const char *addr" .Fa "int len" .Fa "int type" .Fc .Ft struct hostent * .Fo lwres_gethostent .Fa "void" .Fc .Ft void .Fo lwres_sethostent .Fa "int stayopen" .Fc .Ft void .Fo lwres_endhostent .Fa "void" .Fc .Ft struct hostent * .Fo lwres_gethostbyname_r .Fa "const char *name" .Fa "struct hostent *resbuf" .Fa "char *buf" .Fa "int buflen" .Fa "int *error" .Fc .Ft struct hostent * .Fo lwres_gethostbyaddr_r .Fa "const char *addr" .Fa "int len" .Fa "int type" .Fa "struct hostent *resbuf" .Fa "char *buf" .Fa "int buflen" .Fa "int *error" .Fc .Ft struct hostent * .Fo lwres_gethostent_r .Fa "struct hostent *resbuf" .Fa "char *buf" .Fa "int buflen" .Fa "int *error" .Fc .Ft void .Fo lwres_sethostent_r .Fa "int stayopen" .Fc .Ft void .Fo lwres_endhostent_r .Fa "void" .Fc .Sh DESCRIPTION These functions provide hostname-to-address and address-to-hostname lookups by means of the lightweight resolver. They are similar to the standard .Xr gethostent 3 functions provided by most operating systems. They use a .Dv "struct hostent" which is usually defined in
a <namedb.h> . d -literal 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 */ .Ed
p The members of this structure are: l -tag -width h_addr_list t Li h_name The official (canonical) name of the host. t Li h_aliases A NULL-terminated array of alternate names (nicknames) for the host. t Li h_addrtype The type of address being returned - .Dv PF_INET or .Dv PF_INET6 . t Li h_length The length of the address in bytes. t Li h_addr_list A .Dv NULL terminated array of network addresses for the host. Host addresses are returned in network byte order. .El
p For backward compatibility with very old software, .Li h_addr is the first address in .Li h_addr_list.
p .Fn lwres_gethostent , .Fn lwres_sethostent , .Fn lwres_endhostent , .Fn lwres_gethostent_r , .Fn lwres_sethostent_r and .Fn lwres_endhostent_r provide iteration over the known host entries on systems that provide such functionality through facilities like
a /etc/hosts or NIS. The lightweight resolver does not currently implement these functions; it only provides them as stub functions that always return failure.
p .Fn lwres_gethostbyname and .Fn lwres_gethostbyname2 look up the hostname .Fa name . .Fn lwres_gethostbyname always looks for an IPv4 address while .Fn lwres_gethostbyname2 looks for an address of protocol family .Fa af : either .Dv PF_INET or .Dv PF_INET6 - IPv4 or IPV6 addresses respectively. Successful calls of the functions return a .Dv "struct hostent" for the name that was looked up. .Dv NULL is returned if the lookups by .Fn lwres_gethostbyname or .Fn lwres_gethostbyname2 fail.
p Reverse lookups of addresses are performed by .Fn lwres_gethostbyaddr . .Fa addr is an address of length .Fa len bytes and protocol family .Fa type - .Dv PF_INET or .Dv PF_INET6 . .Fn lwres_gethostbyname_r is a thread-safe function for forward lookups. If an error occurs, an error code is returned in .Fa *error . .Fa resbuf is a pointer to a .Dv "struct hostent" which is initialised by a successful call to .Fn lwres_gethostbyname_r . .Fa buf is a buffer of length .Fa len bytes which is used to store the .Li h_name , .Li h_aliases , and .Li h_addr_list elements of the .Dv "struct hostent" returned in .Fa resbuf . Successful calls to .Fn lwres_gethostbyname_r return .Fa resbuf , which is a pointer to the .Dv "struct hostent" it created.
p .Fn lwres_gethostbyaddr_r is a thread-safe function that performs a reverse lookup of address .Fa addr which is .Fa len bytes long and is of protocol family .Fa type - .Dv PF_INET or .Dv PF_INET6 . If an error occurs, the error code is returned in .Fa *error . The other function parameters are identical to those in .Fn lwres_gethostbyname_r . .Fa resbuf is a pointer to a .Dv "struct hostent" which is initialised by a successful call to .Fn lwres_gethostbyaddr_r . .Fa buf is a buffer of length .Fa len bytes which is used to store the .Li h_name , .Li h_aliases , and .Li h_addr_list elements of the .Dv "struct hostent" returned in .Fa resbuf . Successful calls to .Fn lwres_gethostbyaddr_r return .Fa resbuf , which is a pointer to the .Fn "struct hostent" it created. .Sh RETURN VALUES
p The functions .Fn lwres_gethostbyname , .Fn lwres_gethostbyname2 , .Fn lwres_gethostbyaddr , and .Fn lwres_gethostent return NULL to indicate an error. In this case the global variable .Dv lwres_h_errno will contain one of the following error codes defined in
a <lwres/netdb.h> : l -tag -width HOST_NOT_FOUND t Li HOST_NOT_FOUND The host or address was not found. t Li TRY_AGAIN A recoverable error occurred, e.g., a timeout. Retrying the lookup may succeed. t Li NO_RECOVERY A non-recoverable error occurred. t Li 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. .El
p .Xr lwres_hstrerror 3 translates these error codes to suitable error messages.
p .Fn lwres_gethostent and .Fn lwres_gethostent_r always return .Dv NULL .
p Successful calls to .Fn lwres_gethostbyname_r and .Fn lwres_gethostbyaddr_r return .Fa resbuf , a pointer to the .Dv "struct hostent" that was initialised by these functions. They return .Dv NULL if the lookups fail or if .Fa buf was too small to hold the list of addresses and names referenced by the .Li h_name , .Li h_aliases , and .Li h_addr_list elements of the .Dv "struct hostent" . If .Fa buf was too small, both .Fn lwres_gethostbyname_r and .Fn lwres_gethostbyaddr_r set the global variable .Dv errno to .Er ERANGE . .Sh SEE ALSO .Xr gethostent 3 , .Xr lwres_getipnode 3 , .Xr lwres_hstrerror 3 .Sh BUGS .Fn lwres_gethostbyname , .Fn lwres_gethostbyname2 , .Fn lwres_gethostbyaddr and .Fn 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 .Fn lwres_gethostbyname_r , and .Fn lwres_gethostbyaddr_r respectively.
p The resolver daemon does not currently support any non-DNS name services such as
a /etc/hosts or .Dv NIS , consequently the above functions don't, either.