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.3 2000/08/01 01:21:21 tale 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 define the interface to the lightweight resolver daemon NOT IF IT IS GOING AWAY for looking up hostnames and addresses. They are similar to the standard .Xr gethostent 3 functions provided by as part of the standard system software. 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 are empty stub functions which do nothing. They are provided as placeholders so that calls to the system's .Xr gethostent 3 functions can simply be #defined to their .Xr lwres_res_gethost equivalents. See
p .Fn lwres_gethostbyname and .Fn lwres_gethostbyname2 lookup 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. Both functions call .Fn lwres_getipnodebyname to look up the hostname. 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 . It calls .Fn lwres_getipnodebyaddr to do the reverse lookup.
p .Fn lwres_gethostbyname_r is a thread-safe function for forward lookups. It also calls .Fn lwres_getipnodebyname to lookup the hostname .Fa name . If .Fn lwres_getipnodebyname encounters an error, the 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 .Fn "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 . .Fn lwres_gethostbyaddr_r calls .Fn lwres_getipnodebyaddr to do the work. If this function encounters an error, the error code is returned in .Fa *error . Like 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 are not thread-safe because they free any memory that had been allocated in a previous call to those functions before they perform a lookup. They also set the global variable .Dv lwres_h_errno when they return. The values of this variable are defined in
a lwres/netdb.h . The values and their meaning are defined as follows: l -tag -width HOST_NOT_FOUND t Li NETDB_INTERNAL Internal Error - see .Li errno t Li NETDB_SUCCESS no problem t Li HOST_NOT_FOUND Authoritative Answer Host not found t Li TRY_AGAIN Non-Authoritive Answer Host not found, or .Dv SERVERFAIL t Li NO_RECOVERY Non recoverable errors, .Dv FORMERR , .Dv REFUSED , or .Dv NOTIMP t Li NO_DATA Valid name, but no data record of requested type t Li NO_ADDRESS no address, so look for MX record .El .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 Although .Fn lwres_gethostbyname , .Fn lwres_gethostbyname2 , .Fn lwres_gethostbyaddr and .Fn lwres_endhostent call thread-safe functions to perform lookups, these 3 functions are not thread-safe because they set the global variable .Dv lwres_h_errno which could overwritten if two or more threads called these functions simultaneously. They also release any memory that had been allocated in a previous call to these functions. This emulates the semantics of their equivalent functions in the system's .Xr gethostent 3 functions which use a static buffer that gets overwritten in subsequent calls to those routines.
p Thread-safe versions for name and address lookup are provided by .Fn lwres_gethostbyname_r , and .Fn lwres_gethostbyaddr_r respectively.
p Although the above functions can be considered as drop-in replacements for their equivalents in the system software, there are limitations. The functions that are documented here only use the BIND9 lighweight resolver daemon That implies that they only use the DNS for host and address lookups. Therefore these functions do not perform lookups in
a /etc/hosts or in .Dv NIS/YP or .Dv NIS+ maps which could be supported by the operating system's .Xr gethostent 3 functions.