PageRenderTime 53ms CodeModel.GetById 35ms app.highlight 10ms RepoModel.GetById 2ms app.codeStats 0ms

/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.html

https://bitbucket.org/freebsd/freebsd-head/
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 &#8212; 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 &lt;lwres/netdb.h&gt;</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 &#8212;
135              <span class="type">SOCK_STREAM</span>,
136              <span class="type">SOCK_DGRAM</span>
137              or
138              <span class="type">SOCK_RAW</span>
139              &#8212; 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>