PageRenderTime 29ms CodeModel.GetById 17ms app.highlight 5ms RepoModel.GetById 0ms app.codeStats 1ms

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

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 332 lines | 314 code | 18 blank | 0 comment | 0 complexity | 8ac335fd07933933ffffbb0eee8cca33 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_getipnode</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_getipnodebyname</refname>
 52    <refname>lwres_getipnodebyaddr</refname>
 53    <refname>lwres_freehostent</refname>
 54    <refpurpose>lightweight resolver nodename / address translation API</refpurpose>
 55  </refnamediv>
 56  <refsynopsisdiv>
 57    <funcsynopsis>
 58<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
 59<funcprototype>
 60        <funcdef>
 61struct hostent *
 62<function>lwres_getipnodebyname</function></funcdef>
 63        <paramdef>const char *<parameter>name</parameter></paramdef>
 64        <paramdef>int <parameter>af</parameter></paramdef>
 65        <paramdef>int <parameter>flags</parameter></paramdef>
 66        <paramdef>int *<parameter>error_num</parameter></paramdef>
 67        </funcprototype>
 68<funcprototype>
 69        <funcdef>
 70struct hostent *
 71<function>lwres_getipnodebyaddr</function></funcdef>
 72        <paramdef>const void *<parameter>src</parameter></paramdef>
 73        <paramdef>size_t <parameter>len</parameter></paramdef>
 74        <paramdef>int <parameter>af</parameter></paramdef>
 75        <paramdef>int *<parameter>error_num</parameter></paramdef>
 76        </funcprototype>
 77<funcprototype>
 78        <funcdef>
 79void
 80<function>lwres_freehostent</function></funcdef>
 81        <paramdef>struct hostent *<parameter>he</parameter></paramdef>
 82      </funcprototype>
 83</funcsynopsis>
 84  </refsynopsisdiv>
 85
 86  <refsect1>
 87    <title>DESCRIPTION</title>
 88
 89    <para>
 90      These functions perform thread safe, protocol independent
 91      nodename-to-address and address-to-nodename
 92      translation as defined in RFC2553.
 93    </para>
 94
 95    <para>
 96      They use a
 97      <type>struct hostent</type>
 98      which is defined in
 99      <filename>namedb.h</filename>:
100    </para>
101    <para><programlisting>
102struct  hostent {
103        char    *h_name;        /* official name of host */
104        char    **h_aliases;    /* alias list */
105        int     h_addrtype;     /* host address type */
106        int     h_length;       /* length of address */
107        char    **h_addr_list;  /* list of addresses from name server */
108};
109#define h_addr  h_addr_list[0]  /* address, for backward compatibility */
110</programlisting>
111    </para>
112
113    <para>
114      The members of this structure are:
115      <variablelist>
116        <varlistentry>
117          <term><constant>h_name</constant></term>
118          <listitem>
119            <para>
120              The official (canonical) name of the host.
121            </para>
122          </listitem>
123        </varlistentry>
124        <varlistentry>
125          <term><constant>h_aliases</constant></term>
126          <listitem>
127            <para>
128              A NULL-terminated array of alternate names (nicknames) for the
129              host.
130            </para>
131          </listitem>
132        </varlistentry>
133        <varlistentry>
134          <term><constant>h_addrtype</constant></term>
135          <listitem>
136            <para>
137              The type of address being returned - usually
138              <type>PF_INET</type>
139              or
140              <type>PF_INET6</type>.
141
142            </para>
143          </listitem>
144        </varlistentry>
145        <varlistentry>
146          <term><constant>h_length</constant></term>
147          <listitem>
148            <para>
149              The length of the address in bytes.
150            </para>
151          </listitem>
152        </varlistentry>
153        <varlistentry>
154          <term><constant>h_addr_list</constant></term>
155          <listitem>
156            <para>
157              A
158              <type>NULL</type>
159              terminated array of network addresses for the host.
160              Host addresses are returned in network byte order.
161            </para>
162          </listitem>
163        </varlistentry>
164      </variablelist>
165    </para>
166
167    <para><function>lwres_getipnodebyname()</function>
168      looks up addresses of protocol family <parameter>af</parameter>
169      for the hostname <parameter>name</parameter>.  The
170      <parameter>flags</parameter> parameter contains ORed flag bits
171      to specify the types of addresses that are searched for, and the
172      types of addresses that are returned.  The flag bits are:
173
174      <variablelist>
175        <varlistentry>
176          <term><constant>AI_V4MAPPED</constant></term>
177          <listitem>
178            <para>
179              This is used with an
180              <parameter>af</parameter>
181              of AF_INET6, and causes IPv4 addresses to be returned as
182              IPv4-mapped
183              IPv6 addresses.
184            </para>
185          </listitem>
186        </varlistentry>
187        <varlistentry>
188          <term><constant>AI_ALL</constant></term>
189          <listitem>
190            <para>
191              This is used with an
192              <parameter>af</parameter>
193              of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
194              be returned.
195              If AI_V4MAPPED is also set, the IPv4 addresses are return as
196              mapped
197              IPv6 addresses.
198            </para>
199          </listitem>
200        </varlistentry>
201        <varlistentry>
202          <term><constant>AI_ADDRCONFIG</constant></term>
203          <listitem>
204            <para>
205              Only return an IPv6 or IPv4 address if here is an active network
206              interface of that type.  This is not currently implemented
207              in the BIND 9 lightweight resolver, and the flag is ignored.
208            </para>
209          </listitem>
210        </varlistentry>
211        <varlistentry>
212          <term><constant>AI_DEFAULT</constant></term>
213          <listitem>
214            <para>
215              This default sets the
216              <constant>AI_V4MAPPED</constant>
217              and
218              <constant>AI_ADDRCONFIG</constant>
219              flag bits.
220            </para>
221          </listitem>
222        </varlistentry>
223      </variablelist>
224    </para>
225
226    <para><function>lwres_getipnodebyaddr()</function>
227      performs a reverse lookup of address <parameter>src</parameter>
228      which is <parameter>len</parameter> bytes long.
229      <parameter>af</parameter> denotes the protocol family, typically
230      <type>PF_INET</type> or <type>PF_INET6</type>.
231    </para>
232    <para><function>lwres_freehostent()</function>
233      releases all the memory associated with the <type>struct
234      hostent</type> pointer <parameter>he</parameter>.  Any memory
235      allocated for the <constant>h_name</constant>,
236      <constant>h_addr_list</constant> and
237      <constant>h_aliases</constant> is freed, as is the memory for
238      the <type>hostent</type> structure itself.
239    </para>
240  </refsect1>
241  <refsect1>
242    <title>RETURN VALUES</title>
243    <para>
244      If an error occurs,
245      <function>lwres_getipnodebyname()</function>
246      and
247      <function>lwres_getipnodebyaddr()</function>
248      set
249      <parameter>*error_num</parameter>
250      to an appropriate error code and the function returns a
251      <type>NULL</type>
252      pointer.
253      The error codes and their meanings are defined in
254      <filename>&lt;lwres/netdb.h&gt;</filename>:
255      <variablelist>
256        <varlistentry>
257          <term><constant>HOST_NOT_FOUND</constant></term>
258          <listitem>
259            <para>
260              No such host is known.
261            </para>
262          </listitem>
263        </varlistentry>
264        <varlistentry>
265          <term><constant>NO_ADDRESS</constant></term>
266          <listitem>
267            <para>
268              The server recognised the request and the name but no address is
269              available.  Another type of request to the name server for the
270              domain might return an answer.
271            </para>
272          </listitem>
273        </varlistentry>
274        <varlistentry>
275          <term><constant>TRY_AGAIN</constant></term>
276          <listitem>
277            <para>
278              A temporary and possibly transient error occurred, such as a
279              failure of a server to respond.  The request may succeed if
280              retried.
281            </para>
282          </listitem>
283        </varlistentry>
284        <varlistentry>
285          <term><constant>NO_RECOVERY</constant></term>
286          <listitem>
287            <para>
288              An unexpected failure occurred, and retrying the request
289              is pointless.
290            </para>
291          </listitem>
292        </varlistentry>
293      </variablelist>
294    </para>
295    <para><citerefentry>
296        <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
297      </citerefentry>
298      translates these error codes to suitable error messages.
299    </para>
300  </refsect1>
301  <refsect1>
302    <title>SEE ALSO</title>
303    <para><citerefentry>
304        <refentrytitle>RFC2553</refentrytitle>
305      </citerefentry>,
306
307      <citerefentry>
308        <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
309      </citerefentry>,
310
311      <citerefentry>
312        <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
313      </citerefentry>,
314
315      <citerefentry>
316        <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
317      </citerefentry>,
318
319      <citerefentry>
320        <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
321      </citerefentry>,
322
323      <citerefentry>
324        <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
325      </citerefentry>.
326    </para>
327  </refsect1>
328</refentry><!--
329 - Local variables:
330 - mode: sgml
331 - End:
332-->