/contrib/bind9/lib/lwres/man/lwres_getipnode.html
HTML | 279 lines | 255 code | 7 blank | 17 comment | 0 complexity | 12b16571180607b05143abb64d4558af MD5 | raw file
1<!-- 2 - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC") 3 - Copyright (C) 2000, 2001, 2003 Internet Software Consortium. 4 - 5 - Permission to use, copy, modify, and/or distribute this software for any 6 - purpose with or without fee is hereby granted, provided that the above 7 - copyright notice and this permission notice appear in all copies. 8 - 9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 - PERFORMANCE OF THIS SOFTWARE. 16--> 17<!-- $Id$ --> 18<html> 19<head> 20<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 21<title>lwres_getipnode</title> 22<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> 23</head> 24<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> 25<a name="id2476275"></a><div class="titlepage"></div> 26<div class="refnamediv"> 27<h2>Name</h2> 28<p>lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent — lightweight resolver nodename / address translation API</p> 29</div> 30<div class="refsynopsisdiv"> 31<h2>Synopsis</h2> 32<div class="funcsynopsis"> 33<pre class="funcsynopsisinfo">#include <lwres/netdb.h></pre> 34<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 35<tr> 36<td><code class="funcdef"> 37struct hostent * 38<b class="fsfunc">lwres_getipnodebyname</b>(</code></td> 39<td>const char * </td> 40<td> 41<var class="pdparam">name</var>, </td> 42</tr> 43<tr> 44<td> </td> 45<td>int </td> 46<td> 47<var class="pdparam">af</var>, </td> 48</tr> 49<tr> 50<td> </td> 51<td>int </td> 52<td> 53<var class="pdparam">flags</var>, </td> 54</tr> 55<tr> 56<td> </td> 57<td>int * </td> 58<td> 59<var class="pdparam">error_num</var><code>)</code>;</td> 60</tr> 61</table> 62<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 63<tr> 64<td><code class="funcdef"> 65struct hostent * 66<b class="fsfunc">lwres_getipnodebyaddr</b>(</code></td> 67<td>const void * </td> 68<td> 69<var class="pdparam">src</var>, </td> 70</tr> 71<tr> 72<td> </td> 73<td>size_t </td> 74<td> 75<var class="pdparam">len</var>, </td> 76</tr> 77<tr> 78<td> </td> 79<td>int </td> 80<td> 81<var class="pdparam">af</var>, </td> 82</tr> 83<tr> 84<td> </td> 85<td>int * </td> 86<td> 87<var class="pdparam">error_num</var><code>)</code>;</td> 88</tr> 89</table> 90<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr> 91<td><code class="funcdef"> 92void 93<b class="fsfunc">lwres_freehostent</b>(</code></td> 94<td>struct hostent * </td> 95<td> 96<var class="pdparam">he</var><code>)</code>;</td> 97</tr></table> 98</div> 99</div> 100<div class="refsect1" lang="en"> 101<a name="id2543435"></a><h2>DESCRIPTION</h2> 102<p> 103 These functions perform thread safe, protocol independent 104 nodename-to-address and address-to-nodename 105 translation as defined in RFC2553. 106 </p> 107<p> 108 They use a 109 <span class="type">struct hostent</span> 110 which is defined in 111 <code class="filename">namedb.h</code>: 112 </p> 113<pre class="programlisting"> 114struct hostent { 115 char *h_name; /* official name of host */ 116 char **h_aliases; /* alias list */ 117 int h_addrtype; /* host address type */ 118 int h_length; /* length of address */ 119 char **h_addr_list; /* list of addresses from name server */ 120}; 121#define h_addr h_addr_list[0] /* address, for backward compatibility */ 122</pre> 123<p> 124 </p> 125<p> 126 The members of this structure are: 127 </p> 128<div class="variablelist"><dl> 129<dt><span class="term"><code class="constant">h_name</code></span></dt> 130<dd><p> 131 The official (canonical) name of the host. 132 </p></dd> 133<dt><span class="term"><code class="constant">h_aliases</code></span></dt> 134<dd><p> 135 A NULL-terminated array of alternate names (nicknames) for the 136 host. 137 </p></dd> 138<dt><span class="term"><code class="constant">h_addrtype</code></span></dt> 139<dd><p> 140 The type of address being returned - usually 141 <span class="type">PF_INET</span> 142 or 143 <span class="type">PF_INET6</span>. 144 145 </p></dd> 146<dt><span class="term"><code class="constant">h_length</code></span></dt> 147<dd><p> 148 The length of the address in bytes. 149 </p></dd> 150<dt><span class="term"><code class="constant">h_addr_list</code></span></dt> 151<dd><p> 152 A 153 <span class="type">NULL</span> 154 terminated array of network addresses for the host. 155 Host addresses are returned in network byte order. 156 </p></dd> 157</dl></div> 158<p> 159 </p> 160<p><code class="function">lwres_getipnodebyname()</code> 161 looks up addresses of protocol family <em class="parameter"><code>af</code></em> 162 for the hostname <em class="parameter"><code>name</code></em>. The 163 <em class="parameter"><code>flags</code></em> parameter contains ORed flag bits 164 to specify the types of addresses that are searched for, and the 165 types of addresses that are returned. The flag bits are: 166 167 </p> 168<div class="variablelist"><dl> 169<dt><span class="term"><code class="constant">AI_V4MAPPED</code></span></dt> 170<dd><p> 171 This is used with an 172 <em class="parameter"><code>af</code></em> 173 of AF_INET6, and causes IPv4 addresses to be returned as 174 IPv4-mapped 175 IPv6 addresses. 176 </p></dd> 177<dt><span class="term"><code class="constant">AI_ALL</code></span></dt> 178<dd><p> 179 This is used with an 180 <em class="parameter"><code>af</code></em> 181 of AF_INET6, and causes all known addresses (IPv6 and IPv4) to 182 be returned. 183 If AI_V4MAPPED is also set, the IPv4 addresses are return as 184 mapped 185 IPv6 addresses. 186 </p></dd> 187<dt><span class="term"><code class="constant">AI_ADDRCONFIG</code></span></dt> 188<dd><p> 189 Only return an IPv6 or IPv4 address if here is an active network 190 interface of that type. This is not currently implemented 191 in the BIND 9 lightweight resolver, and the flag is ignored. 192 </p></dd> 193<dt><span class="term"><code class="constant">AI_DEFAULT</code></span></dt> 194<dd><p> 195 This default sets the 196 <code class="constant">AI_V4MAPPED</code> 197 and 198 <code class="constant">AI_ADDRCONFIG</code> 199 flag bits. 200 </p></dd> 201</dl></div> 202<p> 203 </p> 204<p><code class="function">lwres_getipnodebyaddr()</code> 205 performs a reverse lookup of address <em class="parameter"><code>src</code></em> 206 which is <em class="parameter"><code>len</code></em> bytes long. 207 <em class="parameter"><code>af</code></em> denotes the protocol family, typically 208 <span class="type">PF_INET</span> or <span class="type">PF_INET6</span>. 209 </p> 210<p><code class="function">lwres_freehostent()</code> 211 releases all the memory associated with the <span class="type">struct 212 hostent</span> pointer <em class="parameter"><code>he</code></em>. Any memory 213 allocated for the <code class="constant">h_name</code>, 214 <code class="constant">h_addr_list</code> and 215 <code class="constant">h_aliases</code> is freed, as is the memory for 216 the <span class="type">hostent</span> structure itself. 217 </p> 218</div> 219<div class="refsect1" lang="en"> 220<a name="id2543693"></a><h2>RETURN VALUES</h2> 221<p> 222 If an error occurs, 223 <code class="function">lwres_getipnodebyname()</code> 224 and 225 <code class="function">lwres_getipnodebyaddr()</code> 226 set 227 <em class="parameter"><code>*error_num</code></em> 228 to an appropriate error code and the function returns a 229 <span class="type">NULL</span> 230 pointer. 231 The error codes and their meanings are defined in 232 <code class="filename"><lwres/netdb.h></code>: 233 </p> 234<div class="variablelist"><dl> 235<dt><span class="term"><code class="constant">HOST_NOT_FOUND</code></span></dt> 236<dd><p> 237 No such host is known. 238 </p></dd> 239<dt><span class="term"><code class="constant">NO_ADDRESS</code></span></dt> 240<dd><p> 241 The server recognised the request and the name but no address is 242 available. Another type of request to the name server for the 243 domain might return an answer. 244 </p></dd> 245<dt><span class="term"><code class="constant">TRY_AGAIN</code></span></dt> 246<dd><p> 247 A temporary and possibly transient error occurred, such as a 248 failure of a server to respond. The request may succeed if 249 retried. 250 </p></dd> 251<dt><span class="term"><code class="constant">NO_RECOVERY</code></span></dt> 252<dd><p> 253 An unexpected failure occurred, and retrying the request 254 is pointless. 255 </p></dd> 256</dl></div> 257<p> 258 </p> 259<p><span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span> 260 translates these error codes to suitable error messages. 261 </p> 262</div> 263<div class="refsect1" lang="en"> 264<a name="id2543790"></a><h2>SEE ALSO</h2> 265<p><span class="citerefentry"><span class="refentrytitle">RFC2553</span></span>, 266 267 <span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>, 268 269 <span class="citerefentry"><span class="refentrytitle">lwres_gethostent</span>(3)</span>, 270 271 <span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>, 272 273 <span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>, 274 275 <span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>. 276 </p> 277</div> 278</div></body> 279</html>