contrib/bind-9.2.4rc7/lib/lwres/man/lwres_getipnode.3

   1 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   2 .\" Copyright (C) 2000, 2001, 2003  Internet Software Consortium.
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
   9 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  10 .\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  11 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  12 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  13 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  14 .\" PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .\" $Id: lwres_getipnode.3,v 1.13.2.3 2004/03/15 04:45:02 marka Exp $
  17 .\"
  18 .TH "LWRES_GETIPNODE" "3" "Jun 30, 2000" "BIND9" ""
  19 .SH NAME
  20 lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent \- lightweight resolver nodename / address translation API
  21 .SH SYNOPSIS
  22 \fB#include <lwres/netdb.h>
  23 .sp
  24 .na
  25 struct hostent *
  26 lwres_getipnodebyname(const char *name, int af, int flags, int *error_num);
  27 .ad
  28 .sp
  29 .na
  30 struct hostent *
  31 lwres_getipnodebyaddr(const void *src, size_t len, int af, int *error_num);
  32 .ad
  33 .sp
  34 .na
  35 void
  36 lwres_freehostent(struct hostent *he);
  37 .ad
  38 \fR
  39 .SH "DESCRIPTION"
  40 .PP
  41 These functions perform thread safe, protocol independent
  42 nodename-to-address and address-to-nodename
  43 translation as defined in RFC2553.
  44 .PP
  45 They use a
  46 \fBstruct hostent\fR
  47 which is defined in
  48 \fInamedb.h\fR:
  49 .sp
  50 .nf
  51 struct  hostent {
  52         char    *h_name;        /* official name of host */
  53         char    **h_aliases;    /* alias list */
  54         int     h_addrtype;     /* host address type */
  55         int     h_length;       /* length of address */
  56         char    **h_addr_list;  /* list of addresses from name server */
  57 };
  58 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
  59 .sp
  60 .fi
  61 .PP
  62 The members of this structure are:
  63 .TP
  64 \fBh_name\fR
  65 The official (canonical) name of the host.
  66 .TP
  67 \fBh_aliases\fR
  68 A NULL-terminated array of alternate names (nicknames) for the host.
  69 .TP
  70 \fBh_addrtype\fR
  71 The type of address being returned - usually
  72 \fBPF_INET\fR
  73 or
  74 \fBPF_INET6\fR.
  75 .TP
  76 \fBh_length\fR
  77 The length of the address in bytes.
  78 .TP
  79 \fBh_addr_list\fR
  80 A
  81 \fBNULL\fR
  82 terminated array of network addresses for the host.
  83 Host addresses are returned in network byte order.
  84 .PP
  85 \fBlwres_getipnodebyname()\fR
  86 looks up addresses of protocol family
  87 \fIaf\fR
  88 for the hostname
  89 \fIname\fR.
  90 The
  91 \fIflags\fR
  92 parameter contains ORed flag bits to
  93 specify the types of addresses that are searched
  94 for, and the types of addresses that are returned.
  95 The flag bits are:
  96 .TP
  97 \fBAI_V4MAPPED\fR
  98 This is used with an
  99 \fIaf\fR
 100 of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
 101 IPv6 addresses.
 102 .TP
 103 \fBAI_ALL\fR
 104 This is used with an
 105 \fIaf\fR
 106 of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
 107 If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
 108 IPv6 addresses.
 109 .TP
 110 \fBAI_ADDRCONFIG\fR
 111 Only return an IPv6 or IPv4 address if here is an active network
 112 interface of that type. This is not currently implemented
 113 in the BIND 9 lightweight resolver, and the flag is ignored.
 114 .TP
 115 \fBAI_DEFAULT\fR
 116 This default sets the
 117 AI_V4MAPPED
 118 and
 119 AI_ADDRCONFIG
 120 flag bits.
 121 .PP
 122 \fBlwres_getipnodebyaddr()\fR
 123 performs a reverse lookup
 124 of address
 125 \fIsrc\fR
 126 which is
 127 \fIlen\fR
 128 bytes long.
 129 \fIaf\fR
 130 denotes the protocol family, typically
 131 \fBPF_INET\fR
 132 or
 133 \fBPF_INET6\fR.
 134 .PP
 135 \fBlwres_freehostent()\fR
 136 releases all the memory associated with
 137 the
 138 \fBstruct hostent\fR
 139 pointer
 140 \fIhe\fR.
 141 Any memory allocated for the
 142 h_name,
 143 h_addr_list
 144 and
 145 h_aliases
 146 is freed, as is the memory for the
 147 \fBhostent\fR
 148 structure itself.
 149 .SH "RETURN VALUES"
 150 .PP
 151 If an error occurs,
 152 \fBlwres_getipnodebyname()\fR
 153 and
 154 \fBlwres_getipnodebyaddr()\fR
 155 set
 156 \fI*error_num\fR
 157 to an appropriate error code and the function returns a
 158 \fBNULL\fR
 159 pointer.
 160 The error codes and their meanings are defined in
 161 \fI<lwres/netdb.h>\fR:
 162 .TP
 163 \fBHOST_NOT_FOUND\fR
 164 No such host is known.
 165 .TP
 166 \fBNO_ADDRESS\fR
 167 The server recognised the request and the name but no address is
 168 available. Another type of request to the name server for the
 169 domain might return an answer.
 170 .TP
 171 \fBTRY_AGAIN\fR
 172 A temporary and possibly transient error occurred, such as a
 173 failure of a server to respond. The request may succeed if
 174 retried.
 175 .TP
 176 \fBNO_RECOVERY\fR
 177 An unexpected failure occurred, and retrying the request
 178 is pointless.
 179 .PP
 180 \fBlwres_hstrerror\fR(3)
 181 translates these error codes to suitable error messages.
 182 .SH "SEE ALSO"
 183 .PP
 184 \fBRFC2553\fR,
 185 \fBlwres\fR(3),
 186 \fBlwres_gethostent\fR(3),
 187 \fBlwres_getaddrinfo\fR(3),
 188 \fBlwres_getnameinfo\fR(3),
 189 \fBlwres_hstrerror\fR(3).