← Back to branch summary

~andreserl/ubuntu/lucid/bind9/bind9-apport-533601

« back to all changes in this revision

Viewing changes to lib/lwres/man/lwres_getipnode.docbook

  • Committer: Bazaar Package Importer
  • Author(s): LaMont Jones, LaMont Jones, Internet Software Consortium, Inc, localization folks
  • Date: 2008-08-02 14:20:20 UTC
  • mfrom: (1.2.1 upstream) (6.1.24 intrepid)
  • Revision ID: james.westby@ubuntu.com-20080802142020-l1hon9jy8lbbjxmg
http://bugs.debian.org/149259
http://bugs.debian.org/492418
http://bugs.debian.org/493392
http://bugs.debian.org/492564
http://bugs.debian.org/490027
http://bugs.debian.org/492949
http://bugs.debian.org/492425
http://bugs.debian.org/491369
http://bugs.debian.org/492048
http://bugs.debian.org/490630
http://bugs.debian.org/492587
[LaMont Jones]

* default to using resolvconf if it is installed
* fix sonames and dependencies.  Closes: #149259, #492418
* Do not build-depend libcap2-dev on non-linux.  Closes: #493392
* drop unused query-loc manpage.  Closes: #492564
* lwresd: Deliver /etc/bind directory.  Closes: #490027
* fix query-source comment in default install

[Internet Software Consortium, Inc]

* 9.5.0-P2.  Closes: #492949

[localization folks]

* l10n: Spanish debconf translation.  Closes: #492425 (Ignacio Mondino)
* l10n: Swedish debconf templates.  Closes: #491369 (Martin Ågren)
* l10n: Japanese debconf translations.  Closes: #492048 (Hideki Yamane
  (Debian-JP))
* l10n: Finnish translation.  Closes: #490630 (Esko Arajärvi)
* l10n: Italian debconf translations.  Closes: #492587 (Alessandro Vietta)

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/lwres/man/lwres_getipnode.docbook
1
 
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
2
 
               "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
 
1
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 
2
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3
3
               [<!ENTITY mdash "&#8212;">]>
4
4
<!--
5
 
 - Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
 
5
 - Copyright (C) 2004, 2005, 2007  Internet Systems Consortium, Inc. ("ISC")
6
6
 - Copyright (C) 2000, 2001, 2003  Internet Software Consortium.
7
7
 -
8
 
 - Permission to use, copy, modify, and distribute this software for any
 
8
 - Permission to use, copy, modify, and/or distribute this software for any
9
9
 - purpose with or without fee is hereby granted, provided that the above
10
10
 - copyright notice and this permission notice appear in all copies.
11
11
 -
18
18
 - PERFORMANCE OF THIS SOFTWARE.
19
19
-->
20
20
 
21
 
<!-- $Id: lwres_getipnode.docbook,v 1.4.2.2.4.3 2005/05/12 21:36:14 sra Exp $ -->
22
 
 
 
21
<!-- $Id: lwres_getipnode.docbook,v 1.12 2007/06/18 23:47:51 tbox Exp $ -->
23
22
<refentry>
24
23
 
25
 
<refentryinfo>
26
 
<date>Jun 30, 2000</date>
27
 
</refentryinfo>
 
24
  <refentryinfo>
 
25
    <date>Jun 30, 2000</date>
 
26
  </refentryinfo>
28
27
 
29
 
<refmeta>
30
 
<refentrytitle>lwres_getipnode</refentrytitle>
31
 
<manvolnum>3</manvolnum>
32
 
<refmiscinfo>BIND9</refmiscinfo>
33
 
</refmeta>
 
28
  <refmeta>
 
29
    <refentrytitle>lwres_getipnode</refentrytitle>
 
30
    <manvolnum>3</manvolnum>
 
31
    <refmiscinfo>BIND9</refmiscinfo>
 
32
  </refmeta>
34
33
 
35
34
  <docinfo>
36
35
    <copyright>
37
36
      <year>2004</year>
38
37
      <year>2005</year>
 
38
      <year>2007</year>
39
39
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
40
40
    </copyright>
41
41
    <copyright>
46
46
    </copyright>
47
47
  </docinfo>
48
48
 
49
 
<refnamediv>
50
 
<refname>lwres_getipnodebyname</refname>
51
 
<refname>lwres_getipnodebyaddr</refname>
52
 
<refname>lwres_freehostent</refname>
53
 
<refpurpose>lightweight resolver nodename / address translation API</refpurpose>
54
 
</refnamediv>
55
 
<refsynopsisdiv>
56
 
<funcsynopsis>
 
49
  <refnamediv>
 
50
    <refname>lwres_getipnodebyname</refname>
 
51
    <refname>lwres_getipnodebyaddr</refname>
 
52
    <refname>lwres_freehostent</refname>
 
53
    <refpurpose>lightweight resolver nodename / address translation API</refpurpose>
 
54
  </refnamediv>
 
55
  <refsynopsisdiv>
 
56
    <funcsynopsis>
57
57
<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
58
58
<funcprototype>
59
 
<funcdef>
 
59
        <funcdef>
60
60
struct hostent *
61
61
<function>lwres_getipnodebyname</function></funcdef>
62
 
<paramdef>const char *name</paramdef>
63
 
<paramdef>int af</paramdef>
64
 
<paramdef>int flags</paramdef>
65
 
<paramdef>int *error_num</paramdef>
66
 
</funcprototype>
 
62
        <paramdef>const char *<parameter>name</parameter></paramdef>
 
63
        <paramdef>int <parameter>af</parameter></paramdef>
 
64
        <paramdef>int <parameter>flags</parameter></paramdef>
 
65
        <paramdef>int *<parameter>error_num</parameter></paramdef>
 
66
        </funcprototype>
67
67
<funcprototype>
68
 
<funcdef>
 
68
        <funcdef>
69
69
struct hostent *
70
70
<function>lwres_getipnodebyaddr</function></funcdef>
71
 
<paramdef>const void *src</paramdef>
72
 
<paramdef>size_t len</paramdef>
73
 
<paramdef>int af</paramdef>
74
 
<paramdef>int *error_num</paramdef>
75
 
</funcprototype>
 
71
        <paramdef>const void *<parameter>src</parameter></paramdef>
 
72
        <paramdef>size_t <parameter>len</parameter></paramdef>
 
73
        <paramdef>int <parameter>af</parameter></paramdef>
 
74
        <paramdef>int *<parameter>error_num</parameter></paramdef>
 
75
        </funcprototype>
76
76
<funcprototype>
77
 
<funcdef>
 
77
        <funcdef>
78
78
void
79
79
<function>lwres_freehostent</function></funcdef>
80
 
<paramdef>struct hostent *he</paramdef>
81
 
</funcprototype>
 
80
        <paramdef>struct hostent *<parameter>he</parameter></paramdef>
 
81
      </funcprototype>
82
82
</funcsynopsis>
83
 
</refsynopsisdiv>
84
 
 
85
 
<refsect1>
86
 
<title>DESCRIPTION</title>
87
 
 
88
 
<para>
89
 
These functions perform thread safe, protocol independent
90
 
nodename-to-address and address-to-nodename 
91
 
translation as defined in RFC2553.
92
 
</para>
93
 
 
94
 
<para>
95
 
They use a
96
 
<type>struct hostent</type>
97
 
which is defined in
98
 
<filename>namedb.h</filename>:
99
 
<programlisting>
 
83
  </refsynopsisdiv>
 
84
 
 
85
  <refsect1>
 
86
    <title>DESCRIPTION</title>
 
87
 
 
88
    <para>
 
89
      These functions perform thread safe, protocol independent
 
90
      nodename-to-address and address-to-nodename
 
91
      translation as defined in RFC2553.
 
92
    </para>
 
93
 
 
94
    <para>
 
95
      They use a
 
96
      <type>struct hostent</type>
 
97
      which is defined in
 
98
      <filename>namedb.h</filename>:
 
99
    </para>
 
100
    <para><programlisting>
100
101
struct  hostent {
101
102
        char    *h_name;        /* official name of host */
102
103
        char    **h_aliases;    /* alias list */
106
107
};
107
108
#define h_addr  h_addr_list[0]  /* address, for backward compatibility */
108
109
</programlisting>
109
 
</para>
110
 
 
111
 
<para>
112
 
The members of this structure are:
113
 
<variablelist>
114
 
<varlistentry><term><constant>h_name</constant></term>
115
 
<listitem>
116
 
<para>
117
 
The official (canonical) name of the host.
118
 
</para>
119
 
</listitem></varlistentry>
120
 
<varlistentry><term><constant>h_aliases</constant></term>
121
 
<listitem>
122
 
<para>
123
 
A NULL-terminated array of alternate names (nicknames) for the host.
124
 
</para>
125
 
</listitem></varlistentry>
126
 
<varlistentry><term><constant>h_addrtype</constant></term>
127
 
<listitem>
128
 
<para>
129
 
The type of address being returned - usually
130
 
<type>PF_INET</type>
131
 
or
132
 
<type>PF_INET6</type>.
133
 
 
134
 
</para>
135
 
</listitem></varlistentry>
136
 
<varlistentry><term><constant>h_length</constant></term>
137
 
<listitem>
138
 
<para>
139
 
The length of the address in bytes.
140
 
</para>
141
 
</listitem></varlistentry>
142
 
<varlistentry><term><constant>h_addr_list</constant></term>
143
 
<listitem>
144
 
<para>
145
 
A
146
 
<type>NULL</type>
147
 
terminated array of network addresses for the host.
148
 
Host addresses are returned in network byte order.
149
 
</para>
150
 
</listitem></varlistentry>
151
 
</variablelist>
152
 
</para>
153
 
<para>
154
 
<function>lwres_getipnodebyname()</function>
155
 
looks up addresses of protocol family
156
 
<parameter>af</parameter>
157
 
 
158
 
for the hostname
159
 
<parameter>name</parameter>.
160
 
 
161
 
The
162
 
<parameter>flags</parameter>
163
 
parameter contains ORed flag bits to 
164
 
specify the types of addresses that are searched
165
 
for, and the types of addresses that are returned. 
166
 
The flag bits are:
167
 
<variablelist>
168
 
<varlistentry><term><constant>AI_V4MAPPED</constant></term>
169
 
<listitem>
170
 
<para>
171
 
This is used with an
172
 
<parameter>af</parameter>
173
 
of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
174
 
IPv6 addresses.
175
 
</para>
176
 
</listitem></varlistentry>
177
 
<varlistentry><term><constant>AI_ALL</constant></term>
178
 
<listitem>
179
 
<para>
180
 
This is used with an
181
 
<parameter>af</parameter>
182
 
of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
183
 
If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
184
 
IPv6 addresses.
185
 
</para>
186
 
</listitem></varlistentry>
187
 
<varlistentry><term><constant>AI_ADDRCONFIG</constant></term>
188
 
<listitem>
189
 
<para>
190
 
Only return an IPv6 or IPv4 address if here is an active network
191
 
interface of that type.  This is not currently implemented
192
 
in the BIND 9 lightweight resolver, and the flag is ignored.
193
 
</para>
194
 
</listitem></varlistentry>
195
 
<varlistentry><term><constant>AI_DEFAULT</constant></term>
196
 
<listitem>
197
 
<para>
198
 
This default sets the
199
 
<constant>AI_V4MAPPED</constant>
200
 
and
201
 
<constant>AI_ADDRCONFIG</constant>
202
 
flag bits.
203
 
</para>
204
 
</listitem></varlistentry>
205
 
</variablelist>
206
 
</para>
207
 
<para>
208
 
<function>lwres_getipnodebyaddr()</function>
209
 
performs a reverse lookup
210
 
of address
211
 
<parameter>src</parameter>
212
 
which is
213
 
<parameter>len</parameter>
214
 
bytes long.
215
 
<parameter>af</parameter>
216
 
denotes the protocol family, typically
217
 
<type>PF_INET</type>
218
 
or
219
 
<type>PF_INET6</type>.
220
 
 
221
 
</para>
222
 
<para>
223
 
<function>lwres_freehostent()</function>
224
 
releases all the memory associated with
225
 
the
226
 
<type>struct hostent</type>
227
 
pointer
228
 
<parameter>he</parameter>.
229
 
 
230
 
Any memory allocated for the
231
 
<constant>h_name</constant>,
232
 
 
233
 
<constant>h_addr_list</constant>
234
 
and
235
 
<constant>h_aliases</constant>
236
 
is freed, as is the memory for the
237
 
<type>hostent</type>
238
 
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><term><constant>HOST_NOT_FOUND</constant></term>
257
 
<listitem>
258
 
<para>
259
 
No such host is known.
260
 
</para>
261
 
</listitem></varlistentry>
262
 
<varlistentry><term><constant>NO_ADDRESS</constant></term>
263
 
<listitem>
264
 
<para>
265
 
The server recognised the request and the name but no address is
266
 
available.  Another type of request to the name server for the
267
 
domain might return an answer.
268
 
</para>
269
 
</listitem></varlistentry>
270
 
<varlistentry><term><constant>TRY_AGAIN</constant></term>
271
 
<listitem>
272
 
<para>
273
 
A temporary and possibly transient error occurred, such as a
274
 
failure of a server to respond.  The request may succeed if
275
 
retried.
276
 
</para>
277
 
</listitem></varlistentry>
278
 
<varlistentry><term><constant>NO_RECOVERY</constant></term>
279
 
<listitem>
280
 
<para>
281
 
An unexpected failure occurred, and retrying the request
282
 
is pointless.
283
 
</para>
284
 
</listitem></varlistentry>
285
 
</variablelist>
286
 
</para>
287
 
<para>
288
 
<citerefentry>
289
 
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
290
 
</manvolnum>
291
 
</citerefentry>
292
 
translates these error codes to suitable error messages.
293
 
</para>
294
 
</refsect1>
295
 
<refsect1>
296
 
<title>SEE ALSO</title>
297
 
<para>
298
 
<citerefentry>
299
 
<refentrytitle>RFC2553</refentrytitle>
300
 
</citerefentry>,
301
 
 
302
 
<citerefentry>
303
 
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
304
 
</citerefentry>,
305
 
 
306
 
<citerefentry>
307
 
<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
308
 
</citerefentry>,
309
 
 
310
 
<citerefentry>
311
 
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
312
 
</citerefentry>,
313
 
 
314
 
<citerefentry>
315
 
<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
316
 
</citerefentry>,
317
 
 
318
 
<citerefentry>
319
 
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
320
 
</citerefentry>.
321
 
</para>
322
 
</refsect1>
323
 
</refentry>
 
110
    </para>
 
111
 
 
112
    <para>
 
113
      The members of this structure are:
 
114
      <variablelist>
 
115
        <varlistentry>
 
116
          <term><constant>h_name</constant></term>
 
117
          <listitem>
 
118
            <para>
 
119
              The official (canonical) name of the host.
 
120
            </para>
 
121
          </listitem>
 
122
        </varlistentry>
 
123
        <varlistentry>
 
124
          <term><constant>h_aliases</constant></term>
 
125
          <listitem>
 
126
            <para>
 
127
              A NULL-terminated array of alternate names (nicknames) for the
 
128
              host.
 
129
            </para>
 
130
          </listitem>
 
131
        </varlistentry>
 
132
        <varlistentry>
 
133
          <term><constant>h_addrtype</constant></term>
 
134
          <listitem>
 
135
            <para>
 
136
              The type of address being returned - usually
 
137
              <type>PF_INET</type>
 
138
              or
 
139
              <type>PF_INET6</type>.
 
140
 
 
141
            </para>
 
142
          </listitem>
 
143
        </varlistentry>
 
144
        <varlistentry>
 
145
          <term><constant>h_length</constant></term>
 
146
          <listitem>
 
147
            <para>
 
148
              The length of the address in bytes.
 
149
            </para>
 
150
          </listitem>
 
151
        </varlistentry>
 
152
        <varlistentry>
 
153
          <term><constant>h_addr_list</constant></term>
 
154
          <listitem>
 
155
            <para>
 
156
              A
 
157
              <type>NULL</type>
 
158
              terminated array of network addresses for the host.
 
159
              Host addresses are returned in network byte order.
 
160
            </para>
 
161
          </listitem>
 
162
        </varlistentry>
 
163
      </variablelist>
 
164
    </para>
 
165
 
 
166
    <para><function>lwres_getipnodebyname()</function>
 
167
      looks up addresses of protocol family <parameter>af</parameter>
 
168
      for the hostname <parameter>name</parameter>.  The
 
169
      <parameter>flags</parameter> parameter contains ORed flag bits
 
170
      to specify the types of addresses that are searched for, and the
 
171
      types of addresses that are returned.  The flag bits are:
 
172
 
 
173
      <variablelist>
 
174
        <varlistentry>
 
175
          <term><constant>AI_V4MAPPED</constant></term>
 
176
          <listitem>
 
177
            <para>
 
178
              This is used with an
 
179
              <parameter>af</parameter>
 
180
              of AF_INET6, and causes IPv4 addresses to be returned as
 
181
              IPv4-mapped
 
182
              IPv6 addresses.
 
183
            </para>
 
184
          </listitem>
 
185
        </varlistentry>
 
186
        <varlistentry>
 
187
          <term><constant>AI_ALL</constant></term>
 
188
          <listitem>
 
189
            <para>
 
190
              This is used with an
 
191
              <parameter>af</parameter>
 
192
              of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
 
193
              be returned.
 
194
              If AI_V4MAPPED is also set, the IPv4 addresses are return as
 
195
              mapped
 
196
              IPv6 addresses.
 
197
            </para>
 
198
          </listitem>
 
199
        </varlistentry>
 
200
        <varlistentry>
 
201
          <term><constant>AI_ADDRCONFIG</constant></term>
 
202
          <listitem>
 
203
            <para>
 
204
              Only return an IPv6 or IPv4 address if here is an active network
 
205
              interface of that type.  This is not currently implemented
 
206
              in the BIND 9 lightweight resolver, and the flag is ignored.
 
207
            </para>
 
208
          </listitem>
 
209
        </varlistentry>
 
210
        <varlistentry>
 
211
          <term><constant>AI_DEFAULT</constant></term>
 
212
          <listitem>
 
213
            <para>
 
214
              This default sets the
 
215
              <constant>AI_V4MAPPED</constant>
 
216
              and
 
217
              <constant>AI_ADDRCONFIG</constant>
 
218
              flag bits.
 
219
            </para>
 
220
          </listitem>
 
221
        </varlistentry>
 
222
      </variablelist>
 
223
    </para>
 
224
 
 
225
    <para><function>lwres_getipnodebyaddr()</function>
 
226
      performs a reverse lookup of address <parameter>src</parameter>
 
227
      which is <parameter>len</parameter> bytes long.
 
228
      <parameter>af</parameter> denotes the protocol family, typically
 
229
      <type>PF_INET</type> or <type>PF_INET6</type>.
 
230
    </para>
 
231
    <para><function>lwres_freehostent()</function>
 
232
      releases all the memory associated with the <type>struct
 
233
      hostent</type> pointer <parameter>he</parameter>.  Any memory
 
234
      allocated for the <constant>h_name</constant>,
 
235
      <constant>h_addr_list</constant> and
 
236
      <constant>h_aliases</constant> is freed, as is the memory for
 
237
      the <type>hostent</type> structure itself.
 
238
    </para>
 
239
  </refsect1>
 
240
  <refsect1>
 
241
    <title>RETURN VALUES</title>
 
242
    <para>
 
243
      If an error occurs,
 
244
      <function>lwres_getipnodebyname()</function>
 
245
      and
 
246
      <function>lwres_getipnodebyaddr()</function>
 
247
      set
 
248
      <parameter>*error_num</parameter>
 
249
      to an appropriate error code and the function returns a
 
250
      <type>NULL</type>
 
251
      pointer.
 
252
      The error codes and their meanings are defined in
 
253
      <filename>&lt;lwres/netdb.h&gt;</filename>:
 
254
      <variablelist>
 
255
        <varlistentry>
 
256
          <term><constant>HOST_NOT_FOUND</constant></term>
 
257
          <listitem>
 
258
            <para>
 
259
              No such host is known.
 
260
            </para>
 
261
          </listitem>
 
262
        </varlistentry>
 
263
        <varlistentry>
 
264
          <term><constant>NO_ADDRESS</constant></term>
 
265
          <listitem>
 
266
            <para>
 
267
              The server recognised the request and the name but no address is
 
268
              available.  Another type of request to the name server for the
 
269
              domain might return an answer.
 
270
            </para>
 
271
          </listitem>
 
272
        </varlistentry>
 
273
        <varlistentry>
 
274
          <term><constant>TRY_AGAIN</constant></term>
 
275
          <listitem>
 
276
            <para>
 
277
              A temporary and possibly transient error occurred, such as a
 
278
              failure of a server to respond.  The request may succeed if
 
279
              retried.
 
280
            </para>
 
281
          </listitem>
 
282
        </varlistentry>
 
283
        <varlistentry>
 
284
          <term><constant>NO_RECOVERY</constant></term>
 
285
          <listitem>
 
286
            <para>
 
287
              An unexpected failure occurred, and retrying the request
 
288
              is pointless.
 
289
            </para>
 
290
          </listitem>
 
291
        </varlistentry>
 
292
      </variablelist>
 
293
    </para>
 
294
    <para><citerefentry>
 
295
        <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
 
296
      </citerefentry>
 
297
      translates these error codes to suitable error messages.
 
298
    </para>
 
299
  </refsect1>
 
300
  <refsect1>
 
301
    <title>SEE ALSO</title>
 
302
    <para><citerefentry>
 
303
        <refentrytitle>RFC2553</refentrytitle>
 
304
      </citerefentry>,
 
305
 
 
306
      <citerefentry>
 
307
        <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
 
308
      </citerefentry>,
 
309
 
 
310
      <citerefentry>
 
311
        <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
 
312
      </citerefentry>,
 
313
 
 
314
      <citerefentry>
 
315
        <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
 
316
      </citerefentry>,
 
317
 
 
318
      <citerefentry>
 
319
        <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
 
320
      </citerefentry>,
 
321
 
 
322
      <citerefentry>
 
323
        <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
 
324
      </citerefentry>.
 
325
    </para>
 
326
  </refsect1>
 
327
</refentry><!--
 
328
 - Local variables:
 
329
 - mode: sgml
 
330
 - End:
 
331
-->