/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.html
HTML | 322 lines | 289 code | 16 blank | 17 comment | 0 complexity | 3ce1a0c80ebd0476ae9c3d989ef9379c 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_getaddrinfo</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_getaddrinfo, lwres_freeaddrinfo — socket address structure to host and service name</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"> 37int 38<b class="fsfunc">lwres_getaddrinfo</b>(</code></td> 39<td>const char * </td> 40<td> 41<var class="pdparam">hostname</var>, </td> 42</tr> 43<tr> 44<td> </td> 45<td>const char * </td> 46<td> 47<var class="pdparam">servname</var>, </td> 48</tr> 49<tr> 50<td> </td> 51<td>const struct addrinfo * </td> 52<td> 53<var class="pdparam">hints</var>, </td> 54</tr> 55<tr> 56<td> </td> 57<td>struct addrinfo ** </td> 58<td> 59<var class="pdparam">res</var><code>)</code>;</td> 60</tr> 61</table> 62<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr> 63<td><code class="funcdef"> 64void 65<b class="fsfunc">lwres_freeaddrinfo</b>(</code></td> 66<td>struct addrinfo * </td> 67<td> 68<var class="pdparam">ai</var><code>)</code>;</td> 69</tr></table> 70</div> 71<p> 72 If the operating system does not provide a 73 <span class="type">struct addrinfo</span>, 74 the following structure is used: 75 </p> 76<pre class="programlisting"> 77struct addrinfo { 78 int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ 79 int ai_family; /* PF_xxx */ 80 int ai_socktype; /* SOCK_xxx */ 81 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 82 size_t ai_addrlen; /* length of ai_addr */ 83 char *ai_canonname; /* canonical name for hostname */ 84 struct sockaddr *ai_addr; /* binary address */ 85 struct addrinfo *ai_next; /* next structure in linked list */ 86}; 87</pre> 88<p> 89 </p> 90</div> 91<div class="refsect1" lang="en"> 92<a name="id2543416"></a><h2>DESCRIPTION</h2> 93<p><code class="function">lwres_getaddrinfo()</code> 94 is used to get a list of IP addresses and port numbers for host 95 <em class="parameter"><code>hostname</code></em> and service 96 <em class="parameter"><code>servname</code></em>. 97 98 The function is the lightweight resolver's implementation of 99 <code class="function">getaddrinfo()</code> as defined in RFC2133. 100 <em class="parameter"><code>hostname</code></em> and 101 <em class="parameter"><code>servname</code></em> are pointers to null-terminated 102 strings or <span class="type">NULL</span>. 103 104 <em class="parameter"><code>hostname</code></em> is either a host name or a 105 numeric host address string: a dotted decimal IPv4 address or an 106 IPv6 address. <em class="parameter"><code>servname</code></em> is either a 107 decimal port number or a service name as listed in 108 <code class="filename">/etc/services</code>. 109 </p> 110<p><em class="parameter"><code>hints</code></em> 111 is an optional pointer to a 112 <span class="type">struct addrinfo</span>. 113 This structure can be used to provide hints concerning the type of 114 socket 115 that the caller supports or wishes to use. 116 The caller can supply the following structure elements in 117 <em class="parameter"><code>*hints</code></em>: 118 119 </p> 120<div class="variablelist"><dl> 121<dt><span class="term"><code class="constant">ai_family</code></span></dt> 122<dd><p> 123 The protocol family that should be used. 124 When 125 <code class="constant">ai_family</code> 126 is set to 127 <span class="type">PF_UNSPEC</span>, 128 it means the caller will accept any protocol family supported by 129 the 130 operating system. 131 </p></dd> 132<dt><span class="term"><code class="constant">ai_socktype</code></span></dt> 133<dd><p> 134 denotes the type of socket — 135 <span class="type">SOCK_STREAM</span>, 136 <span class="type">SOCK_DGRAM</span> 137 or 138 <span class="type">SOCK_RAW</span> 139 — that is wanted. 140 When 141 <code class="constant">ai_socktype</code> 142 is zero the caller will accept any socket type. 143 </p></dd> 144<dt><span class="term"><code class="constant">ai_protocol</code></span></dt> 145<dd><p> 146 indicates which transport protocol is wanted: IPPROTO_UDP or 147 IPPROTO_TCP. 148 If 149 <code class="constant">ai_protocol</code> 150 is zero the caller will accept any protocol. 151 </p></dd> 152<dt><span class="term"><code class="constant">ai_flags</code></span></dt> 153<dd> 154<p> 155 Flag bits. 156 If the 157 <span class="type">AI_CANONNAME</span> 158 bit is set, a successful call to 159 <code class="function">lwres_getaddrinfo()</code> 160 will return a null-terminated string containing the canonical 161 name 162 of the specified hostname in 163 <code class="constant">ai_canonname</code> 164 of the first 165 <span class="type">addrinfo</span> 166 structure returned. 167 Setting the 168 <span class="type">AI_PASSIVE</span> 169 bit indicates that the returned socket address structure is 170 intended 171 for used in a call to 172 <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>. 173 174 In this case, if the hostname argument is a 175 <span class="type">NULL</span> 176 pointer, then the IP address portion of the socket 177 address structure will be set to 178 <span class="type">INADDR_ANY</span> 179 for an IPv4 address or 180 <span class="type">IN6ADDR_ANY_INIT</span> 181 for an IPv6 address. 182 </p> 183<p> 184 When 185 <code class="constant">ai_flags</code> 186 does not set the 187 <span class="type">AI_PASSIVE</span> 188 bit, the returned socket address structure will be ready 189 for use in a call to 190 <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span> 191 for a connection-oriented protocol or 192 <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>, 193 194 <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>, 195 196 or 197 <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span> 198 if a connectionless protocol was chosen. 199 The IP address portion of the socket address structure will be 200 set to the loopback address if 201 <em class="parameter"><code>hostname</code></em> 202 is a 203 <span class="type">NULL</span> 204 pointer and 205 <span class="type">AI_PASSIVE</span> 206 is not set in 207 <code class="constant">ai_flags</code>. 208 </p> 209<p> 210 If 211 <code class="constant">ai_flags</code> 212 is set to 213 <span class="type">AI_NUMERICHOST</span> 214 it indicates that 215 <em class="parameter"><code>hostname</code></em> 216 should be treated as a numeric string defining an IPv4 or IPv6 217 address 218 and no name resolution should be attempted. 219 </p> 220</dd> 221</dl></div> 222<p> 223 </p> 224<p> 225 All other elements of the <span class="type">struct addrinfo</span> passed 226 via <em class="parameter"><code>hints</code></em> must be zero. 227 </p> 228<p> 229 A <em class="parameter"><code>hints</code></em> of <span class="type">NULL</span> is 230 treated as if 231 the caller provided a <span class="type">struct addrinfo</span> initialized to zero 232 with <code class="constant">ai_family</code>set to 233 <code class="constant">PF_UNSPEC</code>. 234 </p> 235<p> 236 After a successful call to 237 <code class="function">lwres_getaddrinfo()</code>, 238 <em class="parameter"><code>*res</code></em> 239 is a pointer to a linked list of one or more 240 <span class="type">addrinfo</span> 241 structures. 242 Each 243 <span class="type">struct addrinfo</span> 244 in this list cn be processed by following 245 the 246 <code class="constant">ai_next</code> 247 pointer, until a 248 <span class="type">NULL</span> 249 pointer is encountered. 250 The three members 251 <code class="constant">ai_family</code>, 252 <code class="constant">ai_socktype</code>, 253 and 254 <code class="constant">ai_protocol</code> 255 in each 256 returned 257 <span class="type">addrinfo</span> 258 structure contain the corresponding arguments for a call to 259 <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>. 260 For each 261 <span class="type">addrinfo</span> 262 structure in the list, the 263 <code class="constant">ai_addr</code> 264 member points to a filled-in socket address structure of length 265 <code class="constant">ai_addrlen</code>. 266 </p> 267<p> 268 All of the information returned by 269 <code class="function">lwres_getaddrinfo()</code> 270 is dynamically allocated: the addrinfo structures, and the socket 271 address structures and canonical host name strings pointed to by the 272 <code class="constant">addrinfo</code>structures. 273 Memory allocated for the dynamically allocated structures created by 274 a successful call to 275 <code class="function">lwres_getaddrinfo()</code> 276 is released by 277 <code class="function">lwres_freeaddrinfo()</code>. 278 <em class="parameter"><code>ai</code></em> 279 is a pointer to a 280 <span class="type">struct addrinfo</span> 281 created by a call to 282 <code class="function">lwres_getaddrinfo()</code>. 283 </p> 284</div> 285<div class="refsect1" lang="en"> 286<a name="id2543794"></a><h2>RETURN VALUES</h2> 287<p><code class="function">lwres_getaddrinfo()</code> 288 returns zero on success or one of the error codes listed in 289 <span class="citerefentry"><span class="refentrytitle">gai_strerror</span>(3)</span> 290 if an error occurs. If both <em class="parameter"><code>hostname</code></em> and 291 <em class="parameter"><code>servname</code></em> are <span class="type">NULL</span> 292 <code class="function">lwres_getaddrinfo()</code> returns 293 <span class="errorcode">EAI_NONAME</span>. 294 </p> 295</div> 296<div class="refsect1" lang="en"> 297<a name="id2543831"></a><h2>SEE ALSO</h2> 298<p><span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>, 299 300 <span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>, 301 302 <span class="citerefentry"><span class="refentrytitle">lwres_freeaddrinfo</span>(3)</span>, 303 304 <span class="citerefentry"><span class="refentrytitle">lwres_gai_strerror</span>(3)</span>, 305 306 <span class="citerefentry"><span class="refentrytitle">RFC2133</span></span>, 307 308 <span class="citerefentry"><span class="refentrytitle">getservbyname</span>(3)</span>, 309 310 <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>, 311 312 <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>, 313 314 <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>, 315 316 <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span>, 317 318 <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>. 319 </p> 320</div> 321</div></body> 322</html>