PageRenderTime 26ms CodeModel.GetById 15ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 0ms

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

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 388 lines | 354 code | 34 blank | 0 comment | 0 complexity | d360cbef8ac9daef29f720805148de3f MD5 | raw file
  1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  2               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
  3	       [<!ENTITY mdash "&#8212;">]>
  4<!--
  5 - Copyright (C) 2004, 2005, 2007, 2012  Internet Systems Consortium, Inc. ("ISC")
  6 - Copyright (C) 2000, 2001, 2003  Internet Software Consortium.
  7 -
  8 - Permission to use, copy, modify, and/or distribute this software for any
  9 - purpose with or without fee is hereby granted, provided that the above
 10 - copyright notice and this permission notice appear in all copies.
 11 -
 12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 14 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 18 - PERFORMANCE OF THIS SOFTWARE.
 19-->
 20
 21<!-- $Id$ -->
 22<refentry>
 23
 24  <refentryinfo>
 25    <date>Jun 30, 2000</date>
 26  </refentryinfo>
 27
 28  <refmeta>
 29    <refentrytitle>lwres_getaddrinfo</refentrytitle>
 30    <manvolnum>3</manvolnum>
 31    <refmiscinfo>BIND9</refmiscinfo>
 32  </refmeta>
 33
 34  <docinfo>
 35    <copyright>
 36      <year>2004</year>
 37      <year>2005</year>
 38      <year>2007</year>
 39      <year>2012</year>
 40      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
 41    </copyright>
 42    <copyright>
 43      <year>2000</year>
 44      <year>2001</year>
 45      <year>2003</year>
 46      <holder>Internet Software Consortium.</holder>
 47    </copyright>
 48  </docinfo>
 49
 50  <refnamediv>
 51    <refname>lwres_getaddrinfo</refname>
 52    <refname>lwres_freeaddrinfo</refname>
 53    <refpurpose>socket address structure to host and service name</refpurpose>
 54  </refnamediv>
 55  <refsynopsisdiv>
 56    <funcsynopsis>
 57<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
 58<funcprototype>
 59        <funcdef>
 60int
 61<function>lwres_getaddrinfo</function></funcdef>
 62        <paramdef>const char *<parameter>hostname</parameter></paramdef>
 63        <paramdef>const char *<parameter>servname</parameter></paramdef>
 64        <paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef>
 65        <paramdef>struct addrinfo **<parameter>res</parameter></paramdef>
 66        </funcprototype>
 67<funcprototype>
 68        <funcdef>
 69void
 70<function>lwres_freeaddrinfo</function></funcdef>
 71        <paramdef>struct addrinfo *<parameter>ai</parameter></paramdef>
 72      </funcprototype>
 73</funcsynopsis>
 74
 75    <para>
 76      If the operating system does not provide a
 77      <type>struct addrinfo</type>,
 78      the following structure is used:
 79    </para>
 80    <para><programlisting>
 81struct  addrinfo {
 82        int             ai_flags;       /* AI_PASSIVE, AI_CANONNAME */
 83        int             ai_family;      /* PF_xxx */
 84        int             ai_socktype;    /* SOCK_xxx */
 85        int             ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
 86        size_t          ai_addrlen;     /* length of ai_addr */
 87        char            *ai_canonname;  /* canonical name for hostname */
 88        struct sockaddr *ai_addr;       /* binary address */
 89        struct addrinfo *ai_next;       /* next structure in linked list */
 90};
 91</programlisting>
 92    </para>
 93
 94  </refsynopsisdiv>
 95
 96  <refsect1>
 97    <title>DESCRIPTION</title>
 98
 99    <para><function>lwres_getaddrinfo()</function>
100      is used to get a list of IP addresses and port numbers for host
101      <parameter>hostname</parameter> and service
102      <parameter>servname</parameter>.
103
104      The function is the lightweight resolver's implementation of
105      <function>getaddrinfo()</function> as defined in RFC2133.
106      <parameter>hostname</parameter> and
107      <parameter>servname</parameter> are pointers to null-terminated
108      strings or <type>NULL</type>.
109
110      <parameter>hostname</parameter> is either a host name or a
111      numeric host address string: a dotted decimal IPv4 address or an
112      IPv6 address.  <parameter>servname</parameter> is either a
113      decimal port number or a service name as listed in
114      <filename>/etc/services</filename>.
115    </para>
116
117    <para><parameter>hints</parameter>
118      is an optional pointer to a
119      <type>struct addrinfo</type>.
120      This structure can be used to provide hints concerning the type of
121      socket
122      that the caller supports or wishes to use.
123      The caller can supply the following structure elements in
124      <parameter>*hints</parameter>:
125
126      <variablelist>
127        <varlistentry>
128          <term><constant>ai_family</constant></term>
129          <listitem>
130            <para>
131              The protocol family that should be used.
132              When
133              <constant>ai_family</constant>
134              is set to
135              <type>PF_UNSPEC</type>,
136              it means the caller will accept any protocol family supported by
137              the
138              operating system.
139            </para>
140          </listitem>
141        </varlistentry>
142        <varlistentry>
143          <term><constant>ai_socktype</constant></term>
144          <listitem>
145            <para>
146              denotes the type of socket &mdash;
147              <type>SOCK_STREAM</type>,
148              <type>SOCK_DGRAM</type>
149              or
150              <type>SOCK_RAW</type>
151              &mdash; that is wanted.
152              When
153              <constant>ai_socktype</constant>
154              is zero the caller will accept any socket type.
155            </para>
156          </listitem>
157        </varlistentry>
158        <varlistentry>
159          <term><constant>ai_protocol</constant></term>
160          <listitem>
161            <para>
162              indicates which transport protocol is wanted: IPPROTO_UDP or
163              IPPROTO_TCP.
164              If
165              <constant>ai_protocol</constant>
166              is zero the caller will accept any protocol.
167            </para>
168          </listitem>
169        </varlistentry>
170        <varlistentry>
171          <term><constant>ai_flags</constant></term>
172          <listitem>
173            <para>
174              Flag bits.
175              If the
176              <type>AI_CANONNAME</type>
177              bit is set, a successful call to
178              <function>lwres_getaddrinfo()</function>
179              will return a null-terminated string containing the canonical
180              name
181              of the specified hostname in
182              <constant>ai_canonname</constant>
183              of the first
184              <type>addrinfo</type>
185              structure returned.
186              Setting the
187              <type>AI_PASSIVE</type>
188              bit indicates that the returned socket address structure is
189              intended
190              for used in a call to
191              <citerefentry>
192                <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
193              </citerefentry>.
194
195              In this case, if the hostname argument is a
196              <type>NULL</type>
197              pointer, then the IP address portion of the socket
198              address structure will be set to
199              <type>INADDR_ANY</type>
200              for an IPv4 address or
201              <type>IN6ADDR_ANY_INIT</type>
202              for an IPv6 address.
203            </para>
204            <para>
205              When
206              <constant>ai_flags</constant>
207              does not set the
208              <type>AI_PASSIVE</type>
209              bit, the returned socket address structure will be ready
210              for use in a call to
211              <citerefentry>
212                <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
213              </citerefentry>
214              for a connection-oriented protocol or
215              <citerefentry>
216                <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
217              </citerefentry>,
218
219              <citerefentry>
220                <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
221              </citerefentry>,
222
223              or
224              <citerefentry>
225                <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
226              </citerefentry>
227              if a connectionless protocol was chosen.
228              The IP address portion of the socket address structure will be
229              set to the loopback address if
230              <parameter>hostname</parameter>
231              is a
232              <type>NULL</type>
233              pointer and
234              <type>AI_PASSIVE</type>
235              is not set in
236              <constant>ai_flags</constant>.
237            </para>
238            <para>
239              If
240              <constant>ai_flags</constant>
241              is set to
242              <type>AI_NUMERICHOST</type>
243              it indicates that
244              <parameter>hostname</parameter>
245              should be treated as a numeric string defining an IPv4 or IPv6
246              address
247              and no name resolution should be attempted.
248            </para>
249          </listitem>
250        </varlistentry>
251      </variablelist>
252    </para>
253
254    <para>
255      All other elements of the <type>struct addrinfo</type> passed
256      via <parameter>hints</parameter> must be zero.
257    </para>
258
259    <para>
260      A <parameter>hints</parameter> of <type>NULL</type> is
261      treated as if
262      the caller provided a <type>struct addrinfo</type> initialized to zero
263      with <constant>ai_family</constant>set to
264      <constant>PF_UNSPEC</constant>.
265    </para>
266
267    <para>
268      After a successful call to
269      <function>lwres_getaddrinfo()</function>,
270      <parameter>*res</parameter>
271      is a pointer to a linked list of one or more
272      <type>addrinfo</type>
273      structures.
274      Each
275      <type>struct addrinfo</type>
276      in this list cn be processed by following
277      the
278      <constant>ai_next</constant>
279      pointer, until a
280      <type>NULL</type>
281      pointer is encountered.
282      The three members
283      <constant>ai_family</constant>,
284      <constant>ai_socktype</constant>,
285      and
286      <constant>ai_protocol</constant>
287      in each
288      returned
289      <type>addrinfo</type>
290      structure contain the corresponding arguments for a call to
291      <citerefentry>
292        <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
293      </citerefentry>.
294      For each
295      <type>addrinfo</type>
296      structure in the list, the
297      <constant>ai_addr</constant>
298      member points to a filled-in socket address structure of length
299      <constant>ai_addrlen</constant>.
300    </para>
301
302    <para>
303      All of the information returned by
304      <function>lwres_getaddrinfo()</function>
305      is dynamically allocated: the addrinfo structures, and the socket
306      address structures and canonical host name strings pointed to by the
307      <constant>addrinfo</constant>structures.
308      Memory allocated for the dynamically allocated structures created by
309      a successful call to
310      <function>lwres_getaddrinfo()</function>
311      is released by
312      <function>lwres_freeaddrinfo()</function>.
313      <parameter>ai</parameter>
314      is a pointer to a
315      <type>struct addrinfo</type>
316      created by a call to
317      <function>lwres_getaddrinfo()</function>.
318    </para>
319
320  </refsect1>
321
322  <refsect1>
323    <title>RETURN VALUES</title>
324
325    <para><function>lwres_getaddrinfo()</function>
326      returns zero on success or one of the error codes listed in
327      <citerefentry>
328        <refentrytitle>gai_strerror</refentrytitle><manvolnum>3</manvolnum>
329      </citerefentry>
330      if an error occurs.  If both <parameter>hostname</parameter> and
331      <parameter>servname</parameter> are <type>NULL</type>
332      <function>lwres_getaddrinfo()</function> returns
333      <errorcode>EAI_NONAME</errorcode>.
334    </para>
335  </refsect1>
336  <refsect1>
337    <title>SEE ALSO</title>
338    <para><citerefentry>
339        <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
340      </citerefentry>,
341
342      <citerefentry>
343        <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
344      </citerefentry>,
345
346      <citerefentry>
347        <refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
348      </citerefentry>,
349
350      <citerefentry>
351        <refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
352      </citerefentry>,
353
354      <citerefentry>
355        <refentrytitle>RFC2133</refentrytitle>
356      </citerefentry>,
357
358      <citerefentry>
359        <refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
360      </citerefentry>,
361
362      <citerefentry>
363        <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
364      </citerefentry>,
365
366      <citerefentry>
367        <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
368      </citerefentry>,
369
370      <citerefentry>
371        <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
372      </citerefentry>,
373
374      <citerefentry>
375        <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
376      </citerefentry>,
377
378      <citerefentry>
379        <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
380      </citerefentry>.
381    </para>
382
383  </refsect1>
384</refentry><!--
385 - Local variables:
386 - mode: sgml
387 - End:
388-->