lib/liblwres/man/lwres_getipnode.3

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