Copyright (C) 2000 Internet Software Consortium.

Permission to use, copy, modify, and distribute this document 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_getipnode.3,v 1.1 2000/06/27 21:53:05 jim Exp $

.Dd Jun 30, 2000 .Dt LWRES_GETIPNODE 3 .Os BIND9 9 .Sh NAME .Nm lwres_getipnodebyname , .Nm lwres_getipnodebyaddr , .Nm lwres_freehostent .Nd lookup functions for the lightweight resolver .Sh SYNOPSIS .Fd #include <lwres/lwres.h> .Fd .Ft struct hostent * .Fo lwres_getipnodebyname .Fa "const char *name" .Fa "int af" .Fa "int flags" .Fa "int *error_num" .Fc .Ft struct hostent * .Fo lwres_getipnodebyaddr .Fa "const void *src" .Fa "size_t len" .Fa "int af" .Fa "int *error_num" .Fc .Ft void .Fo lwres_freehostent .Fa "struct hostent *he" .Fc .Sh DESCRIPTION These functions 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_getipnodebyname looks up the hostname .Fa name of protocol family .Fa af . The .Fa flags parameter sets bits that indicate how IPv6 and IPv4 addresses should presented. The value of those flags are: l -tag -width AI_ADDRCONFIG t Li AI_V4MAPPED return an IPv4 address mapped to an IPv6 address t Li AI_ALL return all possible addresses t Li AI_ADDRCONFIG only return an IPv6 or IPv4 address if here is an active network interface of that type. t Li AI_DEFAULT this default sets the .Li AI_V4MAPPED and .Li AI_ADDRCONFIG flag bits. .El

p The value of .Dv AF_INET6 is sometimes added to .Fa flags . When .Fa flags is set to .Li "AI_V4MAPPED + AF_INET6" .Fn lwres_getipnodebyname will look for an IPv6 address and if this is not found it will look for an IPv4 address and map it to an IPv6 address. When .Fa flags is .Li "AI_ALL + AI_V4MAPPED + AF_INET6" , .Fn lwres_getipnodebyname returns mapped IPv4 addresses and IPv6 addresses. .Fn lwres_getipnodebyname calls .Fn lwres_context_create to create a resolver context for the lookup and then calls .Fn lwres_getaddrsbyname to lookup the name using that resolver context.

p .Fn lwres_getipnodebyaddr performs a thread-safe reverse lookup of address .Fa src which is .Fa len bytes long. .Fa af denotes the protocol family: .Dv PF_INET or .Dv PF_INET6 . .Fn lwres_getipnodebyaddr also sets up a resolver context by calling .Fn lwres_context_create. It then calls .Fn lwres_getnamebyaddr to make the query.

p Both .Fn lwres_getipnodebyname and .Fn lwres_getipnodebyaddr will free any memory that was allocated during intermediate stages of the lookup by calling .Fn lwres_gnbaresponse_free . Both functions call .Fn lwres_getipnodebyaddr immediately before they return so that the created resolver context gets discarded.

p .Fn lwres_freehostent releases all the memory associated with the .Dv "struct hostent" pointer .Fa he . Any memory allocated for the .Li h_name , .Li h_addr_list and .Li h_aliases is freed, as is the memory for the .Dv hostent structure itself. .Sh RETURN VALUES If an error occurs, .Fn lwres_getipnodebyname and .Fn lwres_getipnodebyaddr set .Fa *error_num to an approriate error code and the function returns a .Dv NULL pointer. The error codes and their meanings are defined in

a lwres/netdb.h . 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

p .Xr lwres_hstrerror 3 translates these error codes to suitable error messages. .Sh SEE ALSO .Xr lwres_res_getaddrsbyname 3 , .Xr lwres_res_context_create 3 , .Xr lwres_res_context_destroy 3 , .Xr lwres_res_gnbaresponse_free 3 , .Xr lwres_res_getaddrsbyaddr 3 , .Xr free 3 , .Xr lwres_hstrerror 3 .