mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-31 14:35:26 +00:00
Code Issues Releases Wiki Activity

1856. [doc] Switch Docbook toolchain from DSSSL to XSL.

Browse Source
This commit is contained in:
Rob Austein
2005-05-11 05:55:41 +00:00
parent 2941824604
commit 268a447506
49 changed files with 17602 additions and 12172 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
bin/check/named-checkconf.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000-2002 Internet Software Consortium.
@@ -15,9 +17,7 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: named-checkconf.docbook,v 1.10 2005/04/07 03:49:55 marka Exp $ -->
<!-- $Id: named-checkconf.docbook,v 1.11 2005/05/11 05:55:35 sra Exp $ -->
<refentry>
<refentryinfo>
<date>June 14, 2000</date>
@@ -29,6 +29,20 @@
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<year>2002</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname><application>named-checkconf</application></refname>
<refpurpose>named configuration file syntax checking tool</refpurpose>
@@ -47,9 +61,9 @@
<refsect1>
<title>DESCRIPTION</title>
<para>
<command>named-checkconf</command> checks the syntax, but not
the semantics, of a named configuration file.
<para><command>named-checkconf</command>
checks the syntax, but not the semantics, of a named
configuration file.
</para>
</refsect1>
@@ -59,52 +73,53 @@
<variablelist>
<varlistentry>
<term>-t <replaceable class="parameter">directory</replaceable></term>
<listitem>
<para>
chroot to <filename>directory</filename> so that include
directives in the configuration file are processed as if
run by a similarly chrooted named.
</para>
</listitem>
<listitem>
<para>
chroot to <filename>directory</filename> so that
include
directives in the configuration file are processed as if
run by a similarly chrooted named.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-v</term>
<listitem>
<para>
Print the version of the <command>named-checkconf</command>
program and exit.
</para>
</listitem>
<listitem>
<para>
Print the version of the <command>named-checkconf</command>
program and exit.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-z</term>
<listitem>
<para>
Perform a check load the master zonefiles found in
<filename>named.conf</filename>.
</para>
</listitem>
<listitem>
<para>
Perform a check load the master zonefiles found in
<filename>named.conf</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-j</term>
<listitem>
<para>
When loading a zonefile read the journal if it exists.
</para>
</listitem>
<listitem>
<para>
When loading a zonefile read the journal if it exists.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>filename</term>
<listitem>
<para>
The name of the configuration file to be checked. If not
specified, it defaults to <filename>/etc/named.conf</filename>.
</para>
</listitem>
<listitem>
<para>
The name of the configuration file to be checked. If not
specified, it defaults to <filename>/etc/named.conf</filename>.
</para>
</listitem>
</varlistentry>
</variablelist>
@@ -113,17 +128,16 @@
<refsect1>
<title>RETURN VALUES</title>
<para>
<command>named-checkconf</command> returns an exit status of 1 if
errors were detected and 0 otherwise.
<para><command>named-checkconf</command>
returns an exit status of 1 if
errors were detected and 0 otherwise.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>named</refentrytitle>
<manvolnum>8</manvolnum>
<para><citerefentry>
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>.
</para>
@@ -131,16 +145,12 @@
<refsect1>
<title>AUTHOR</title>
<para>
<corpauthor>Internet Systems Consortium</corpauthor>
<para><corpauthor>Internet Systems Consortium</corpauthor>
</para>
</refsect1>
</refentry>
<!--
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

201
bin/check/named-checkzone.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000-2002 Internet Software Consortium.
@@ -15,9 +17,7 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: named-checkzone.docbook,v 1.16 2005/04/07 03:49:55 marka Exp $ -->
<!-- $Id: named-checkzone.docbook,v 1.17 2005/05/11 05:55:35 sra Exp $ -->
<refentry>
<refentryinfo>
<date>June 13, 2000</date>
@@ -29,6 +29,20 @@
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<year>2002</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname><application>named-checkzone</application></refname>
<refpurpose>zone file validity checking tool</refpurpose>
@@ -56,12 +70,11 @@
<refsect1>
<title>DESCRIPTION</title>
<para>
<command>named-checkzone</command> checks the syntax and integrity of
a zone file. It performs the same checks as <command>named</command>
does when loading a zone. This makes
<command>named-checkzone</command> useful for checking zone
files before configuring them into a name server.
<para><command>named-checkzone</command>
checks the syntax and integrity of a zone file. It performs the
same checks as <command>named</command> does when loading a
zone. This makes <command>named-checkzone</command> useful for
checking zone files before configuring them into a name server.
</para>
</refsect1>
@@ -71,78 +84,80 @@
<variablelist>
<varlistentry>
<term>-d</term>
<listitem>
<para>
Enable debugging.
</para>
</listitem>
<listitem>
<para>
Enable debugging.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-q</term>
<listitem>
<para>
Quiet mode - exit code only.
</para>
</listitem>
<listitem>
<para>
Quiet mode - exit code only.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-v</term>
<listitem>
<para>
Print the version of the <command>named-checkzone</command>
program and exit.
</para>
</listitem>
<listitem>
<para>
Print the version of the <command>named-checkzone</command>
program and exit.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-j</term>
<listitem>
<para>
When loading the zone file read the journal if it exists.
</para>
When loading the zone file read the journal if it exists.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-c <replaceable class="parameter">class</replaceable></term>
<listitem>
<para>
Specify the class of the zone. If not specified "IN" is assumed.
</para>
</listitem>
<listitem>
<para>
Specify the class of the zone. If not specified "IN" is assumed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-k <replaceable class="parameter">mode</replaceable></term>
<listitem>
<para>
Perform <command>"check-name"</command> checks with the specified failure mode.
Possible modes are <command>"fail"</command>,
<command>"warn"</command> (default) and
<command>"ignore"</command>.
</para>
</listitem>
<listitem>
<para>
Perform <command>"check-name"</command> checks with
the specified failure mode.
Possible modes are <command>"fail"</command>,
<command>"warn"</command> (default) and
<command>"ignore"</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-n <replaceable class="parameter">mode</replaceable></term>
<listitem>
<para>
Specify whether NS records should be checked to see if they
are addresses. Possible modes are <command>"fail"</command>,
<command>"warn"</command> (default) and
<command>"ignore"</command>.
</para>
</listitem>
<listitem>
<para>
Specify whether NS records should be checked to see if they
are addresses. Possible modes are <command>"fail"</command>,
<command>"warn"</command> (default) and
<command>"ignore"</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-o <replaceable class="parameter">filename</replaceable></term>
<listitem>
<para>
Write zone output to <filename>filename</filename>.
Write zone output to <filename>filename</filename>.
</para>
</listitem>
</varlistentry>
@@ -151,9 +166,10 @@
<term>-t <replaceable class="parameter">directory</replaceable></term>
<listitem>
<para>
chroot to <filename>directory</filename> so that include
directives in the configuration file are processed as if
run by a similarly chrooted named.
chroot to <filename>directory</filename> so that
include
directives in the configuration file are processed as if
run by a similarly chrooted named.
</para>
</listitem>
</varlistentry>
@@ -162,52 +178,54 @@
<term>-w <replaceable class="parameter">directory</replaceable></term>
<listitem>
<para>
chdir to <filename>directory</filename> so that relative
filenames in master file $INCLUDE directives work. This
is similar to the directory clause in
<filename>named.conf</filename>.
chdir to <filename>directory</filename> so that
relative
filenames in master file $INCLUDE directives work. This
is similar to the directory clause in
<filename>named.conf</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-D</term>
<listitem>
<para>
Dump zone file in canonical format.
</para>
</listitem>
<listitem>
<para>
Dump zone file in canonical format.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-W <replaceable class="parameter">mode</replaceable></term>
<listitem>
<para>
Specify whether to check for non-terminal wildcards.
Non-terminal wildcards are almost always the result of a
failure to understand the wildcard matching algorithm (RFC 1034).
Possible modes are <command>"warn"</command> (default) and
<command>"ignore"</command>.
</para>
</listitem>
<listitem>
<para>
Specify whether to check for non-terminal wildcards.
Non-terminal wildcards are almost always the result of a
failure to understand the wildcard matching algorithm (RFC 1034).
Possible modes are <command>"warn"</command> (default)
and
<command>"ignore"</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>zonename</term>
<listitem>
<para>
The domain name of the zone being checked.
</para>
</listitem>
<listitem>
<para>
The domain name of the zone being checked.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>filename</term>
<listitem>
<para>
The name of the zone file.
</para>
</listitem>
<listitem>
<para>
The name of the zone file.
</para>
</listitem>
</varlistentry>
</variablelist>
@@ -216,17 +234,16 @@
<refsect1>
<title>RETURN VALUES</title>
<para>
<command>named-checkzone</command> returns an exit status of 1 if
errors were detected and 0 otherwise.
<para><command>named-checkzone</command>
returns an exit status of 1 if
errors were detected and 0 otherwise.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>named</refentrytitle>
<manvolnum>8</manvolnum>
<para><citerefentry>
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citetitle>RFC 1035</citetitle>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>.
@@ -235,16 +252,12 @@
<refsect1>
<title>AUTHOR</title>
<para>
<corpauthor>Internet Systems Consortium</corpauthor>
<para><corpauthor>Internet Systems Consortium</corpauthor>
</para>
</refsect1>
</refentry>
<!--
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

1433
bin/dig/dig.docbook
View File

File diff suppressed because it is too large Load Diff

390
bin/dig/host.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000-2002 Internet Software Consortium.
@@ -15,204 +17,236 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: host.docbook,v 1.7 2004/11/10 22:04:25 marka Exp $ -->
<!-- $Id: host.docbook,v 1.8 2005/05/11 05:55:36 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>host</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>host</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>host</refname>
<refpurpose>DNS lookup utility</refpurpose>
</refnamediv>
<refnamediv>
<refname>host</refname>
<refpurpose>DNS lookup utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>host</command>
<arg><option>-aCdlnrTwv</option></arg>
<arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
<arg><option>-N <replaceable class="parameter">ndots</replaceable></option></arg>
<arg><option>-R <replaceable class="parameter">number</replaceable></option></arg>
<arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
<arg><option>-W <replaceable class="parameter">wait</replaceable></option></arg>
<arg><option>-m <replaceable class="parameter">flag</replaceable></option></arg>
<arg><option>-4</option></arg>
<arg><option>-6</option></arg>
<arg choice=req>name</arg>
<arg choice=opt>server</arg>
</cmdsynopsis>
</refsynopsisdiv>
<docinfo>
<copyright>
<year>2004</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<year>2002</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refsect1>
<title>DESCRIPTION</title>
<para>
<command>host</command>
is a simple utility for performing DNS lookups.
It is normally used to convert names to IP addresses and vice versa.
When no arguments or options are given,
<command>host</command>
prints a short summary of its command line arguments and options.
</para>
<refsynopsisdiv>
<cmdsynopsis>
<command>host</command>
<arg><option>-aCdlnrTwv</option></arg>
<arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
<arg><option>-N <replaceable class="parameter">ndots</replaceable></option></arg>
<arg><option>-R <replaceable class="parameter">number</replaceable></option></arg>
<arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
<arg><option>-W <replaceable class="parameter">wait</replaceable></option></arg>
<arg><option>-m <replaceable class="parameter">flag</replaceable></option></arg>
<arg><option>-4</option></arg>
<arg><option>-6</option></arg>
<arg choice="req">name</arg>
<arg choice="opt">server</arg>
</cmdsynopsis>
</refsynopsisdiv>
<para>
<parameter>name</parameter> is the domain name that is to be looked
up. It can also be a dotted-decimal IPv4 address or a colon-delimited
IPv6 address, in which case <command>host</command> will by default
perform a reverse lookup for that address.
<parameter>server</parameter> is an optional argument which is either
the name or IP address of the name server that <command>host</command>
should query instead of the server or servers listed in
<filename>/etc/resolv.conf</filename>.
</para>
<refsect1>
<title>DESCRIPTION</title>
<para>
The <option>-a</option> (all) option is equivalent to setting the
<option>-v</option> option and asking <command>host</command> to make
a query of type ANY.
</para>
<para><command>host</command>
is a simple utility for performing DNS lookups.
It is normally used to convert names to IP addresses and vice versa.
When no arguments or options are given,
<command>host</command>
prints a short summary of its command line arguments and options.
</para>
<para>
When the <option>-C</option> option is used, <command>host</command>
will attempt to display the SOA records for zone
<parameter>name</parameter> from all the listed authoritative name
servers for that zone. The list of name servers is defined by the NS
records that are found for the zone.
</para>
<para><parameter>name</parameter> is the domain name that is to be
looked
up. It can also be a dotted-decimal IPv4 address or a colon-delimited
IPv6 address, in which case <command>host</command> will by
default
perform a reverse lookup for that address.
<parameter>server</parameter> is an optional argument which
is either
the name or IP address of the name server that <command>host</command>
should query instead of the server or servers listed in
<filename>/etc/resolv.conf</filename>.
</para>
<para>
The <option>-c</option> option instructs to make a DNS query of class
<parameter>class</parameter>. This can be used to lookup Hesiod or
Chaosnet class resource records. The default class is IN (Internet).
</para>
<para>
The <option>-a</option> (all) option is equivalent to setting the
<option>-v</option> option and asking <command>host</command> to make
a query of type ANY.
</para>
<para>
Verbose output is generated by <command>host</command> when the
<option>-d</option> or <option>-v</option> option is used. The two
options are equivalent. They have been provided for backwards
compatibility. In previous versions, the <option>-d</option> option
switched on debugging traces and <option>-v</option> enabled verbose
output.
</para>
<para>
When the <option>-C</option> option is used, <command>host</command>
will attempt to display the SOA records for zone
<parameter>name</parameter> from all the listed
authoritative name
servers for that zone. The list of name servers is defined by the NS
records that are found for the zone.
</para>
<para>
List mode is selected by the <option>-l</option> option. This makes
<command>host</command> perform a zone transfer for zone
<parameter>name</parameter>. Transfer the zone printing out the NS, PTR
and address records (A/AAAA). If combined with <option>-a</option>
all records will be printed.
</para>
<para>
The <option>-c</option> option instructs to make a DNS query of class
<parameter>class</parameter>. This can be used to lookup
Hesiod or
Chaosnet class resource records. The default class is IN (Internet).
</para>
<para>
The <option>-i</option>
option specifies that reverse lookups of IPv6 addresses should
use the IP6.INT domain as defined in RFC1886.
The default is to use IP6.ARPA.
</para>
<para>
Verbose output is generated by <command>host</command> when
the
<option>-d</option> or <option>-v</option> option is used. The two
options are equivalent. They have been provided for backwards
compatibility. In previous versions, the <option>-d</option> option
switched on debugging traces and <option>-v</option> enabled verbose
output.
</para>
<para>
The <option>-N</option> option sets the number of dots that have to be
in <parameter>name</parameter> for it to be considered absolute. The
default value is that defined using the ndots statement in
<filename>/etc/resolv.conf</filename>, or 1 if no ndots statement is
present. Names with fewer dots are interpreted as relative names and
will be searched for in the domains listed in the <type>search</type>
or <type>domain</type> directive in
<filename>/etc/resolv.conf</filename>.
</para>
<para>
List mode is selected by the <option>-l</option> option. This makes
<command>host</command> perform a zone transfer for zone
<parameter>name</parameter>. Transfer the zone printing out
the NS, PTR
and address records (A/AAAA). If combined with <option>-a</option>
all records will be printed.
</para>
<para>
The number of UDP retries for a lookup can be changed with the
<option>-R</option> option. <parameter>number</parameter> indicates
how many times <command>host</command> will repeat a query that does
not get answered. The default number of retries is 1. If
<parameter>number</parameter> is negative or zero, the number of
retries will default to 1.
</para>
<para>
The <option>-i</option>
option specifies that reverse lookups of IPv6 addresses should
use the IP6.INT domain as defined in RFC1886.
The default is to use IP6.ARPA.
</para>
<para>
Non-recursive queries can be made via the <option>-r</option> option.
Setting this option clears the <type>RD</type> &mdash; recursion
desired &mdash; bit in the query which <command>host</command> makes.
This should mean that the name server receiving the query will not
attempt to resolve <parameter>name</parameter>. The
<option>-r</option> option enables <command>host</command> to mimic
the behaviour of a name server by making non-recursive queries and
expecting to receive answers to those queries that are usually
referrals to other name servers.
</para>
<para>
The <option>-N</option> option sets the number of dots that have to be
in <parameter>name</parameter> for it to be considered
absolute. The
default value is that defined using the ndots statement in
<filename>/etc/resolv.conf</filename>, or 1 if no ndots
statement is
present. Names with fewer dots are interpreted as relative names and
will be searched for in the domains listed in the <type>search</type>
or <type>domain</type> directive in
<filename>/etc/resolv.conf</filename>.
</para>
<para>
By default <command>host</command> uses UDP when making queries. The
<option>-T</option> option makes it use a TCP connection when querying
the name server. TCP will be automatically selected for queries that
require it, such as zone transfer (AXFR) requests.
</para>
<para>
The number of UDP retries for a lookup can be changed with the
<option>-R</option> option. <parameter>number</parameter>
indicates
how many times <command>host</command> will repeat a query
that does
not get answered. The default number of retries is 1. If
<parameter>number</parameter> is negative or zero, the
number of
retries will default to 1.
</para>
<para>
The <option>-4</option> option forces <command>host</command> to only
use IPv4 query transport. The <option>-6</option> option forces
<command>host</command> to only use IPv6 query transport.
</para>
<para>
Non-recursive queries can be made via the <option>-r</option> option.
Setting this option clears the <type>RD</type> &mdash; recursion
desired &mdash; bit in the query which <command>host</command> makes.
This should mean that the name server receiving the query will not
attempt to resolve <parameter>name</parameter>. The
<option>-r</option> option enables <command>host</command>
to mimic
the behaviour of a name server by making non-recursive queries and
expecting to receive answers to those queries that are usually
referrals to other name servers.
</para>
<para>
The <option>-t</option> option is used to select the query type.
<parameter>type</parameter> can be any recognised query type: CNAME,
NS, SOA, SIG, KEY, AXFR, etc. When no query type is specified,
<command>host</command> automatically selects an appropriate query
type. By default it looks for A records, but if the
<option>-C</option> option was given, queries will be made for SOA
records, and if <parameter>name</parameter> is a dotted-decimal IPv4
address or colon-delimited IPv6 address, <command>host</command> will
query for PTR records. If a query type of IXFR is chosen the starting
serial number can be specified by appending an equal followed by the
starting serial number (e.g. -t IXFR=12345678).
</para>
<para>
By default <command>host</command> uses UDP when making
queries. The
<option>-T</option> option makes it use a TCP connection when querying
the name server. TCP will be automatically selected for queries that
require it, such as zone transfer (AXFR) requests.
</para>
<para>
The time to wait for a reply can be controlled through the
<option>-W</option> and <option>-w</option> options. The
<option>-W</option> option makes <command>host</command> wait for
<parameter>wait</parameter> seconds. If <parameter>wait</parameter>
is less than one, the wait interval is set to one second. When the
<option>-w</option> option is used, <command>host</command> will
effectively wait forever for a reply. The time to wait for a response
will be set to the number of seconds given by the hardware's maximum
value for an integer quantity.
</para>
<para>
The <option>-4</option> option forces <command>host</command> to only
use IPv4 query transport. The <option>-6</option> option forces
<command>host</command> to only use IPv6 query transport.
</para>
<para>
The <option>-m</option> can be used to set the memory usage debugging flags
<parameter>record</parameter>, <parameter>usage</parameter> and
<parameter>trace</parameter>.
</para>
</refsect1>
<para>
The <option>-t</option> option is used to select the query type.
<parameter>type</parameter> can be any recognised query
type: CNAME,
NS, SOA, SIG, KEY, AXFR, etc. When no query type is specified,
<command>host</command> automatically selects an appropriate
query
type. By default it looks for A records, but if the
<option>-C</option> option was given, queries will be made for SOA
records, and if <parameter>name</parameter> is a
dotted-decimal IPv4
address or colon-delimited IPv6 address, <command>host</command> will
query for PTR records. If a query type of IXFR is chosen the starting
serial number can be specified by appending an equal followed by the
starting serial number (e.g. -t IXFR=12345678).
</para>
<refsect1>
<title>FILES</title>
<para>
<filename>/etc/resolv.conf</filename>
</para>
</refsect1>
<para>
The time to wait for a reply can be controlled through the
<option>-W</option> and <option>-w</option> options. The
<option>-W</option> option makes <command>host</command>
wait for
<parameter>wait</parameter> seconds. If <parameter>wait</parameter>
is less than one, the wait interval is set to one second. When the
<option>-w</option> option is used, <command>host</command>
will
effectively wait forever for a reply. The time to wait for a response
will be set to the number of seconds given by the hardware's maximum
value for an integer quantity.
</para>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>dig</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>.
</para>
<para>
The <option>-m</option> can be used to set the memory usage debugging
flags
<parameter>record</parameter>, <parameter>usage</parameter> and
<parameter>trace</parameter>.
</para>
</refsect1>
</refsect1>
</refentry>
<refsect1>
<title>FILES</title>
<para><filename>/etc/resolv.conf</filename>
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>dig</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

633
bin/dig/nslookup.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
-
@@ -14,13 +16,11 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: nslookup.docbook,v 1.5 2004/08/30 00:54:45 marka Exp $ -->
<!-- $Id: nslookup.docbook,v 1.6 2005/05/11 05:55:36 sra Exp $ -->
<!--
- Copyright (c) 1985, 1989
- The Regents of the University of California. All rights reserved.
-
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
@@ -36,7 +36,7 @@
- 4. Neither the name of the University nor the names of its contributors
- may be used to endorse or promote products derived from this software
- without specific prior written permission.
-
-
- THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
- ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
@@ -49,272 +49,431 @@
- OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- SUCH DAMAGE.
-->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>nslookup</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>nslookup</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>nslookup</refname>
<refpurpose>query Internet name servers interactively</refpurpose>
</refnamediv>
<refnamediv>
<refname>nslookup</refname>
<refpurpose>query Internet name servers interactively</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>nslookup</command>
<arg><option>-option</option></arg>
<arg choice=opt>name | -</arg>
<arg choice=opt>server</arg>
</cmdsynopsis>
</refsynopsisdiv>
<docinfo>
<copyright>
<year>2004</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
</docinfo>
<refsect1>
<title>DESCRIPTION</title>
<para>
<command>Nslookup</command>
is a program to query Internet domain name servers. <command>Nslookup</command>
has two modes: interactive and non-interactive. Interactive mode allows
the user to query name servers for information about various hosts and
domains or to print a list of hosts in a domain. Non-interactive mode is
used to print just the name and requested information for a host or
domain.
</para>
</refsect1>
<refsynopsisdiv>
<cmdsynopsis>
<command>nslookup</command>
<arg><option>-option</option></arg>
<arg choice="opt">name | -</arg>
<arg choice="opt">server</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>ARGUMENTS</title>
<para>
Interactive mode is entered in the following cases:
<OrderedList Numeration=Loweralpha>
<Listitem>
<para>
when no arguments are given (the default name server will be used)
</para>
</Listitem>
<Listitem>
<para>
when the first argument is a hyphen (-) and the second argument is
the host name or Internet address of a name server.
</para>
</Listitem>
</OrderedList>
</para>
<refsect1>
<title>DESCRIPTION</title>
<para><command>Nslookup</command>
is a program to query Internet domain name servers. <command>Nslookup</command>
has two modes: interactive and non-interactive. Interactive mode allows
the user to query name servers for information about various hosts and
domains or to print a list of hosts in a domain. Non-interactive mode
is
used to print just the name and requested information for a host or
domain.
</para>
</refsect1>
<para>
Non-interactive mode is used when the name or Internet address of the
host to be looked up is given as the first argument. The optional second
argument specifies the host name or address of a name server.
</para>
<refsect1>
<title>ARGUMENTS</title>
<para>
Interactive mode is entered in the following cases:
<orderedlist numeration="loweralpha">
<listitem>
<para>
when no arguments are given (the default name server will be used)
</para>
</listitem>
<listitem>
<para>
when the first argument is a hyphen (-) and the second argument is
the host name or Internet address of a name server.
</para>
</listitem>
</orderedlist>
</para>
<para>
Options can also be specified on the command line if they precede the
arguments and are prefixed with a hyphen. For example, to
change the default query type to host information, and the initial timeout to 10 seconds, type:
<InformalExample>
<PROGRAMLISTING>
<para>
Non-interactive mode is used when the name or Internet address of the
host to be looked up is given as the first argument. The optional second
argument specifies the host name or address of a name server.
</para>
<para>
Options can also be specified on the command line if they precede the
arguments and are prefixed with a hyphen. For example, to
change the default query type to host information, and the initial
timeout to 10 seconds, type:
<informalexample>
<programlisting>
nslookup -query=hinfo -timeout=10
</PROGRAMLISTING>
</InformalExample>
</para>
</programlisting>
</informalexample>
</para>
</refsect1>
</refsect1>
<refsect1>
<title>INTERACTIVE COMMANDS</title>
<variablelist>
<varlistentry><term>host <optional>server</optional></term>
<listitem><para>
Look up information for host using the current default server or
using server, if specified. If host is an Internet address and
the query type is A or PTR, the name of the host is returned.
If host is a name and does not have a trailing period, the
search list is used to qualify the name.
</para>
<refsect1>
<title>INTERACTIVE COMMANDS</title>
<variablelist>
<varlistentry>
<term>host <optional>server</optional></term>
<listitem>
<para>
Look up information for host using the current default server or
using server, if specified. If host is an Internet address and
the query type is A or PTR, the name of the host is returned.
If host is a name and does not have a trailing period, the
search list is used to qualify the name.
</para>
<para>
To look up a host not in the current domain, append a period to
the name.
</para></listitem></varlistentry>
<para>
To look up a host not in the current domain, append a period to
the name.
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>server</constant> <replaceable class="parameter">domain</replaceable></term>
<listitem><para></para></listitem></varlistentry>
<varlistentry><term><constant>lserver</constant> <replaceable class="parameter">domain</replaceable></term>
<listitem><para>
Change the default server to <replaceable>domain</replaceable>; <constant>lserver</constant> uses the initial
server to look up information about <replaceable>domain</replaceable>, while <constant>server</constant> uses
the current default server. If an authoritative answer can't be
found, the names of servers that might have the answer are
returned.
</para></listitem></varlistentry>
<varlistentry>
<term><constant>server</constant> <replaceable class="parameter">domain</replaceable></term>
<listitem>
<para/>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>lserver</constant> <replaceable class="parameter">domain</replaceable></term>
<listitem>
<para>
Change the default server to <replaceable>domain</replaceable>; <constant>lserver</constant> uses the initial
server to look up information about <replaceable>domain</replaceable>, while <constant>server</constant> uses
the current default server. If an authoritative answer can't be
found, the names of servers that might have the answer are
returned.
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>root</constant></term>
<listitem><para>not implemented</para></listitem></varlistentry>
<varlistentry>
<term><constant>root</constant></term>
<listitem>
<para>
not implemented
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>finger</constant></term>
<listitem><para>not implemented</para></listitem></varlistentry>
<varlistentry>
<term><constant>finger</constant></term>
<listitem>
<para>
not implemented
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>ls</constant></term>
<listitem><para>not implemented</para></listitem></varlistentry>
<varlistentry>
<term><constant>ls</constant></term>
<listitem>
<para>
not implemented
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>view</constant></term>
<listitem><para>not implemented</para></listitem></varlistentry>
<varlistentry>
<term><constant>view</constant></term>
<listitem>
<para>
not implemented
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>help</constant></term>
<listitem><para>not implemented</para></listitem></varlistentry>
<varlistentry>
<term><constant>help</constant></term>
<listitem>
<para>
not implemented
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>?</constant></term>
<listitem><para>not implemented</para></listitem></varlistentry>
<varlistentry>
<term><constant>?</constant></term>
<listitem>
<para>
not implemented
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>exit</constant></term>
<listitem><para>Exits the program.</para></listitem></varlistentry>
<varlistentry>
<term><constant>exit</constant></term>
<listitem>
<para>
Exits the program.
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>set</constant> <replaceable>keyword<optional>=value</optional></replaceable></term>
<listitem><para>This command is used to change state information that affects
the lookups. Valid keywords are:
<variablelist>
<varlistentry><term><constant>all</constant></term>
<listitem>
<para>Prints the current values of the frequently used
options to <command>set</command>. Information about the current default
server and host is also printed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>set</constant>
<replaceable>keyword<optional>=value</optional></replaceable></term>
<listitem>
<para>
This command is used to change state information that affects
the lookups. Valid keywords are:
<variablelist>
<varlistentry>
<term><constant>all</constant></term>
<listitem>
<para>
Prints the current values of the frequently used
options to <command>set</command>.
Information about the current default
server and host is also printed.
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>class=</constant><replaceable>value</replaceable></term>
<listitem><para>
Change the query class to one of:
<variablelist>
<varlistentry><term><constant>IN</constant></term>
<listitem><para>the Internet class</para></listitem></varlistentry>
<varlistentry><term><constant>CH</constant></term>
<listitem><para>the Chaos class</para></listitem></varlistentry>
<varlistentry><term><constant>HS</constant></term>
<listitem><para>the Hesiod class</para></listitem></varlistentry>
<varlistentry><term><constant>ANY</constant></term>
<listitem><para>wildcard</para></listitem></varlistentry>
</variablelist>
The class specifies the protocol group of the information.
</para><para>
(Default = IN; abbreviation = cl)
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>class=</constant><replaceable>value</replaceable></term>
<listitem>
<para>
Change the query class to one of:
<variablelist>
<varlistentry>
<term><constant>IN</constant></term>
<listitem>
<para>
the Internet class
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>CH</constant></term>
<listitem>
<para>
the Chaos class
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>HS</constant></term>
<listitem>
<para>
the Hesiod class
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>ANY</constant></term>
<listitem>
<para>
wildcard
</para>
</listitem>
</varlistentry>
</variablelist>
The class specifies the protocol group of the information.
<varlistentry><term><constant><replaceable><optional>no</optional></replaceable>debug</constant></term>
<listitem><para>
Turn debugging mode on. A lot more information is
printed about the packet sent to the server and the
resulting answer.
</para><para>
(Default = nodebug; abbreviation = <optional>no</optional>deb)
</para></listitem></varlistentry>
</para>
<para>
(Default = IN; abbreviation = cl)
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant><replaceable><optional>no</optional></replaceable>d2</constant></term>
<listitem><para>
Turn debugging mode on. A lot more information is
printed about the packet sent to the server and the
resulting answer.
</para><para>
(Default = nod2)
</para></listitem></varlistentry>
<varlistentry>
<term><constant>
<replaceable><optional>no</optional></replaceable>debug</constant></term>
<listitem>
<para>
Turn debugging mode on. A lot more information is
printed about the packet sent to the server and the
resulting answer.
</para>
<para>
(Default = nodebug; abbreviation = <optional>no</optional>deb)
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>domain=</constant><replaceable>name</replaceable></term>
<listitem><para>
Sets the search list to <replaceable>name</replaceable>.
</para></listitem></varlistentry>
<varlistentry>
<term><constant>
<replaceable><optional>no</optional></replaceable>d2</constant></term>
<listitem>
<para>
Turn debugging mode on. A lot more information is
printed about the packet sent to the server and the
resulting answer.
</para>
<para>
(Default = nod2)
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant><replaceable><optional>no</optional></replaceable>search</constant></term>
<listitem><para>
If the lookup request contains at least one period but
doesn't end with a trailing period, append the domain
names in the domain search list to the request until an
answer is received.
</para><para>
(Default = search)
</para></listitem></varlistentry>
<varlistentry>
<term><constant>domain=</constant><replaceable>name</replaceable></term>
<listitem>
<para>
Sets the search list to <replaceable>name</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>port=</constant><replaceable>value</replaceable></term>
<listitem><para>
Change the default TCP/UDP name server port to <replaceable>value</replaceable>.
</para><para>
(Default = 53; abbreviation = po)
</para></listitem></varlistentry>
<varlistentry>
<term><constant>
<replaceable><optional>no</optional></replaceable>search</constant></term>
<listitem>
<para>
If the lookup request contains at least one period but
doesn't end with a trailing period, append the domain
names in the domain search list to the request until an
answer is received.
</para>
<para>
(Default = search)
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>querytype=</constant><replaceable>value</replaceable></term>
<listitem><para></para></listitem></varlistentry>
<varlistentry>
<term><constant>port=</constant><replaceable>value</replaceable></term>
<listitem>
<para>
Change the default TCP/UDP name server port to <replaceable>value</replaceable>.
</para>
<para>
(Default = 53; abbreviation = po)
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>type=</constant><replaceable>value</replaceable></term>
<listitem><para>
Change the top of the information query.
</para><para>
(Default = A; abbreviations = q, ty)
</para></listitem></varlistentry>
<varlistentry>
<term><constant>querytype=</constant><replaceable>value</replaceable></term>
<listitem>
<para/>
</listitem>
</varlistentry>
<varlistentry><term><constant><replaceable><optional>no</optional></replaceable>recurse</constant></term>
<listitem><para>
Tell the name server to query other servers if it does not have the
information.
</para><para>
(Default = recurse; abbreviation = [no]rec)
</para></listitem></varlistentry>
<varlistentry>
<term><constant>type=</constant><replaceable>value</replaceable></term>
<listitem>
<para>
Change the top of the information query.
</para>
<para>
(Default = A; abbreviations = q, ty)
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>retry=</constant><replaceable>number</replaceable></term>
<listitem><para>
Set the number of retries to number.
</para></listitem></varlistentry>
<varlistentry>
<term><constant>
<replaceable><optional>no</optional></replaceable>recurse</constant></term>
<listitem>
<para>
Tell the name server to query other servers if it does not
have the
information.
</para>
<para>
(Default = recurse; abbreviation = [no]rec)
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>timeout=</constant><replaceable>number</replaceable></term>
<listitem><para>
Change the initial timeout interval for waiting for a
reply to number seconds.
</para></listitem></varlistentry>
<varlistentry>
<term><constant>retry=</constant><replaceable>number</replaceable></term>
<listitem>
<para>
Set the number of retries to number.
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant><replaceable><optional>no</optional></replaceable>vc</constant></term>
<listitem><para>
Always use a virtual circuit when sending requests to the server.
</para><para>
(Default = novc)
</para></listitem></varlistentry>
<varlistentry>
<term><constant>timeout=</constant><replaceable>number</replaceable></term>
<listitem>
<para>
Change the initial timeout interval for waiting for a
reply to number seconds.
</para>
</listitem>
</varlistentry>
</variablelist>
</para></listitem></varlistentry>
</variablelist>
</refsect1>
<varlistentry>
<term><constant>
<replaceable><optional>no</optional></replaceable>vc</constant></term>
<listitem>
<para>
Always use a virtual circuit when sending requests to the
server.
</para>
<para>
(Default = novc)
</para>
</listitem>
</varlistentry>
<refsect1>
<title>FILES</title>
<para>
<filename>/etc/resolv.conf</filename>
</para>
</refsect1>
</variablelist>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>dig</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>host</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>.
</para>
</refsect1>
<refsect1>
<title>FILES</title>
<para><filename>/etc/resolv.conf</filename>
</para>
</refsect1>
<refsect1>
<title>Author</title>
<para>
Andrew Cherenson
</para>
</refsect1>
</refentry>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>dig</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>host</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>.
</para>
</refsect1>
<refsect1>
<title>Author</title>
<para>
Andrew Cherenson
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

350
bin/dnssec/dnssec-keygen.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000-2003 Internet Software Consortium.
@@ -15,9 +17,7 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: dnssec-keygen.docbook,v 1.10 2005/04/07 03:49:55 marka Exp $ -->
<!-- $Id: dnssec-keygen.docbook,v 1.11 2005/05/11 05:55:36 sra Exp $ -->
<refentry>
<refentryinfo>
<date>June 30, 2000</date>
@@ -34,6 +34,21 @@
<refpurpose>DNSSEC key generation tool</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<year>2002</year>
<year>2003</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<cmdsynopsis>
<command>dnssec-keygen</command>
@@ -57,11 +72,10 @@
<refsect1>
<title>DESCRIPTION</title>
<para>
<command>dnssec-keygen</command> generates keys for DNSSEC
(Secure DNS), as defined in RFC 2535 and RFC &lt;TBA\&gt;. It can also generate
keys for use with TSIG (Transaction Signatures), as
defined in RFC 2845.
<para><command>dnssec-keygen</command>
generates keys for DNSSEC (Secure DNS), as defined in RFC 2535
and RFC &lt;TBA\&gt;. It can also generate keys for use with
TSIG (Transaction Signatures), as defined in RFC 2845.
</para>
</refsect1>
@@ -71,168 +85,173 @@
<variablelist>
<varlistentry>
<term>-a <replaceable class="parameter">algorithm</replaceable></term>
<listitem>
<para>
Selects the cryptographic algorithm. The value of
<option>algorithm</option> must be one of RSAMD5 (RSA) or RSASHA1,
DSA, DH (Diffie Hellman), or HMAC-MD5. These values
are case insensitive.
</para>
<para>
Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement algorithm,
and DSA is recommended. For TSIG, HMAC-MD5 is mandatory.
</para>
<para>
Note 2: HMAC-MD5 and DH automatically set the -k flag.
</para>
</listitem>
<listitem>
<para>
Selects the cryptographic algorithm. The value of
<option>algorithm</option> must be one of RSAMD5 (RSA) or RSASHA1,
DSA, DH (Diffie Hellman), or HMAC-MD5. These values
are case insensitive.
</para>
<para>
Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
algorithm,
and DSA is recommended. For TSIG, HMAC-MD5 is mandatory.
</para>
<para>
Note 2: HMAC-MD5 and DH automatically set the -k flag.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-b <replaceable class="parameter">keysize</replaceable></term>
<listitem>
<para>
Specifies the number of bits in the key. The choice of key
size depends on the algorithm used. RSAMD5 / RSASHA1 keys must be between
512 and 2048 bits. Diffie Hellman keys must be between
128 and 4096 bits. DSA keys must be between 512 and 1024
bits and an exact multiple of 64. HMAC-MD5 keys must be
between 1 and 512 bits.
</para>
</listitem>
<listitem>
<para>
Specifies the number of bits in the key. The choice of key
size depends on the algorithm used. RSAMD5 / RSASHA1 keys must be
between
512 and 2048 bits. Diffie Hellman keys must be between
128 and 4096 bits. DSA keys must be between 512 and 1024
bits and an exact multiple of 64. HMAC-MD5 keys must be
between 1 and 512 bits.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-n <replaceable class="parameter">nametype</replaceable></term>
<listitem>
<para>
Specifies the owner type of the key. The value of
<option>nametype</option> must either be ZONE (for a DNSSEC
zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with a host (KEY)),
USER (for a key associated with a user(KEY)) or OTHER (DNSKEY). These values are
case insensitive.
</para>
</listitem>
<listitem>
<para>
Specifies the owner type of the key. The value of
<option>nametype</option> must either be ZONE (for a DNSSEC
zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
a host (KEY)),
USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
These values are
case insensitive.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-c <replaceable class="parameter">class</replaceable></term>
<listitem>
<para>
Indicates that the DNS record containing the key should have
the specified class. If not specified, class IN is used.
</para>
</listitem>
<listitem>
<para>
Indicates that the DNS record containing the key should have
the specified class. If not specified, class IN is used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-e</term>
<listitem>
<para>
If generating an RSAMD5/RSASHA1 key, use a large exponent.
</para>
</listitem>
<listitem>
<para>
If generating an RSAMD5/RSASHA1 key, use a large exponent.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-f <replaceable class="parameter">flag</replaceable></term>
<listitem>
<para>
Set the specified flag in the flag field of the KEY/DNSKEY record.
The only recognized flag is KSK (Key Signing Key) DNSKEY.
</para>
</listitem>
<listitem>
<para>
Set the specified flag in the flag field of the KEY/DNSKEY record.
The only recognized flag is KSK (Key Signing Key) DNSKEY.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-g <replaceable class="parameter">generator</replaceable></term>
<listitem>
<para>
If generating a Diffie Hellman key, use this generator.
Allowed values are 2 and 5. If no generator
is specified, a known prime from RFC 2539 will be used
if possible; otherwise the default is 2.
</para>
</listitem>
<listitem>
<para>
If generating a Diffie Hellman key, use this generator.
Allowed values are 2 and 5. If no generator
is specified, a known prime from RFC 2539 will be used
if possible; otherwise the default is 2.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-h</term>
<listitem>
<para>
Prints a short summary of the options and arguments to
<command>dnssec-keygen</command>.
</para>
</listitem>
<listitem>
<para>
Prints a short summary of the options and arguments to
<command>dnssec-keygen</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-k</term>
<listitem>
<para>
Generate KEY records rather than DNSKEY records.
</para>
</listitem>
<listitem>
<para>
Generate KEY records rather than DNSKEY records.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-p <replaceable class="parameter">protocol</replaceable></term>
<listitem>
<para>
Sets the protocol value for the generated key. The protocol
is a number between 0 and 255. The default is 3 (DNSSEC).
Other possible values for this argument are listed in
RFC 2535 and its successors.
</para>
</listitem>
<listitem>
<para>
Sets the protocol value for the generated key. The protocol
is a number between 0 and 255. The default is 3 (DNSSEC).
Other possible values for this argument are listed in
RFC 2535 and its successors.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-r <replaceable class="parameter">randomdev</replaceable></term>
<listitem>
<para>
Specifies the source of randomness. If the operating
system does not provide a <filename>/dev/random</filename>
or equivalent device, the default source of randomness
is keyboard input. <filename>randomdev</filename> specifies
the name of a character device or file containing random
data to be used instead of the default. The special value
<filename>keyboard</filename> indicates that keyboard
input should be used.
</para>
</listitem>
<listitem>
<para>
Specifies the source of randomness. If the operating
system does not provide a <filename>/dev/random</filename>
or equivalent device, the default source of randomness
is keyboard input. <filename>randomdev</filename>
specifies
the name of a character device or file containing random
data to be used instead of the default. The special value
<filename>keyboard</filename> indicates that keyboard
input should be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-s <replaceable class="parameter">strength</replaceable></term>
<listitem>
<para>
Specifies the strength value of the key. The strength is
a number between 0 and 15, and currently has no defined
purpose in DNSSEC.
</para>
</listitem>
<listitem>
<para>
Specifies the strength value of the key. The strength is
a number between 0 and 15, and currently has no defined
purpose in DNSSEC.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-t <replaceable class="parameter">type</replaceable></term>
<listitem>
<para>
Indicates the use of the key. <option>type</option> must be
one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
is AUTHCONF. AUTH refers to the ability to authenticate
data, and CONF the ability to encrypt data.
</para>
</listitem>
<listitem>
<para>
Indicates the use of the key. <option>type</option> must be
one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
is AUTHCONF. AUTH refers to the ability to authenticate
data, and CONF the ability to encrypt data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-v <replaceable class="parameter">level</replaceable></term>
<listitem>
<para>
Sets the debugging level.
</para>
</listitem>
<listitem>
<para>
Sets the debugging level.
</para>
</listitem>
</varlistentry>
</variablelist>
@@ -241,83 +260,83 @@
<refsect1>
<title>GENERATED KEYS</title>
<para>
When <command>dnssec-keygen</command> completes successfully,
it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
to the standard output. This is an identification string for
the key it has generated. These strings can be used as arguments
to <command>dnssec-makekeyset</command>.
When <command>dnssec-keygen</command> completes
successfully,
it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
to the standard output. This is an identification string for
the key it has generated. These strings can be used as arguments
to <command>dnssec-makekeyset</command>.
</para>
<itemizedlist>
<listitem>
<para>
<filename>nnnn</filename> is the key name.
<para><filename>nnnn</filename> is the key name.
</para>
</listitem>
<listitem>
<para>
<filename>aaa</filename> is the numeric representation of the
<para><filename>aaa</filename> is the numeric representation
of the
algorithm.
</para>
</listitem>
<listitem>
<para>
<filename>iiiii</filename> is the key identifier (or footprint).
<para><filename>iiiii</filename> is the key identifier (or
footprint).
</para>
</listitem>
</itemizedlist>
<para>
<command>dnssec-keygen</command> creates two file, with names based
on the printed string. <filename>Knnnn.+aaa+iiiii.key</filename>
contains the public key, and
<filename>Knnnn.+aaa+iiiii.private</filename> contains the private
key.
<para><command>dnssec-keygen</command>
creates two file, with names based
on the printed string. <filename>Knnnn.+aaa+iiiii.key</filename>
contains the public key, and
<filename>Knnnn.+aaa+iiiii.private</filename> contains the
private
key.
</para>
<para>
The <filename>.key</filename> file contains a DNS KEY record that
can be inserted into a zone file (directly or with a $INCLUDE
statement).
The <filename>.key</filename> file contains a DNS KEY record
that
can be inserted into a zone file (directly or with a $INCLUDE
statement).
</para>
<para>
The <filename>.private</filename> file contains algorithm specific
fields. For obvious security reasons, this file does not have
general read permission.
The <filename>.private</filename> file contains algorithm
specific
fields. For obvious security reasons, this file does not have
general read permission.
</para>
<para>
Both <filename>.key</filename> and <filename>.private</filename>
files are generated for symmetric encryption algorithm such as
HMAC-MD5, even though the public and private key are equivalent.
Both <filename>.key</filename> and <filename>.private</filename>
files are generated for symmetric encryption algorithm such as
HMAC-MD5, even though the public and private key are equivalent.
</para>
</refsect1>
<refsect1>
<title>EXAMPLE</title>
<para>
To generate a 768-bit DSA key for the domain
<userinput>example.com</userinput>, the following command would be
issued:
To generate a 768-bit DSA key for the domain
<userinput>example.com</userinput>, the following command would be
issued:
</para>
<para><userinput>dnssec-keygen -a DSA -b 768 -n ZONE example.com</userinput>
</para>
<para>
<userinput>dnssec-keygen -a DSA -b 768 -n ZONE example.com</userinput>
The command would print a string of the form:
</para>
<para><userinput>Kexample.com.+003+26160</userinput>
</para>
<para>
The command would print a string of the form:
</para>
<para>
<userinput>Kexample.com.+003+26160</userinput>
</para>
<para>
In this example, <command>dnssec-keygen</command> creates
the files <filename>Kexample.com.+003+26160.key</filename> and
<filename>Kexample.com.+003+26160.private</filename>
In this example, <command>dnssec-keygen</command> creates
the files <filename>Kexample.com.+003+26160.key</filename>
and
<filename>Kexample.com.+003+26160.private</filename>
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>dnssec-signzone</refentrytitle>
<manvolnum>8</manvolnum>
<para><citerefentry>
<refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>,
<citetitle>RFC 2535</citetitle>,
@@ -328,14 +347,11 @@
<refsect1>
<title>AUTHOR</title>
<para>
<corpauthor>Internet Systems Consortium</corpauthor>
<para><corpauthor>Internet Systems Consortium</corpauthor>
</para>
</refsect1>
</refentry>
<!--
</refentry><!--
- Local variables:
- mode: sgml
- End:

427
bin/dnssec/dnssec-signzone.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000-2003 Internet Software Consortium.
@@ -15,9 +17,7 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: dnssec-signzone.docbook,v 1.15 2005/04/07 03:49:56 marka Exp $ -->
<!-- $Id: dnssec-signzone.docbook,v 1.16 2005/05/11 05:55:36 sra Exp $ -->
<refentry>
<refentryinfo>
<date>June 30, 2000</date>
@@ -34,6 +34,21 @@
<refpurpose>DNSSEC zone signing tool</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<year>2002</year>
<year>2003</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<cmdsynopsis>
<command>dnssec-signzone</command>
@@ -63,13 +78,13 @@
<refsect1>
<title>DESCRIPTION</title>
<para>
<command>dnssec-signzone</command> signs a zone. It generates
NSEC and RRSIG records and produces a signed version of the
zone. The security status of delegations from the signed zone
(that is, whether the child zones are secure or not) is
determined by the presence or absence of a
<filename>keyset</filename> file for each child zone.
<para><command>dnssec-signzone</command>
signs a zone. It generates
NSEC and RRSIG records and produces a signed version of the
zone. The security status of delegations from the signed zone
(that is, whether the child zones are secure or not) is
determined by the presence or absence of a
<filename>keyset</filename> file for each child zone.
</para>
</refsect1>
@@ -79,256 +94,259 @@
<variablelist>
<varlistentry>
<term>-a</term>
<listitem>
<para>
Verify all generated signatures.
</para>
</listitem>
<listitem>
<para>
Verify all generated signatures.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-c <replaceable class="parameter">class</replaceable></term>
<listitem>
<para>
Specifies the DNS class of the zone.
</para>
</listitem>
<listitem>
<para>
Specifies the DNS class of the zone.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-k <replaceable class="parameter">key</replaceable></term>
<listitem>
<para>
Treat specified key as a key signing key ignoring any
key flags. This option may be specified multiple times.
</para>
</listitem>
<listitem>
<para>
Treat specified key as a key signing key ignoring any
key flags. This option may be specified multiple times.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-l <replaceable class="parameter">domain</replaceable></term>
<listitem>
<para>
Generate a DLV set in addition to the key (DNSKEY) and DS sets.
The domain is appended to the name of the records.
</para>
</listitem>
<listitem>
<para>
Generate a DLV set in addition to the key (DNSKEY) and DS sets.
The domain is appended to the name of the records.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-d <replaceable class="parameter">directory</replaceable></term>
<listitem>
<para>
Look for <filename>keyset</filename> files in
<option>directory</option> as the directory
</para>
</listitem>
<listitem>
<para>
Look for <filename>keyset</filename> files in
<option>directory</option> as the directory
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-g</term>
<listitem>
<para>
Generate DS records for child zones from keyset files.
Existing DS records will be removed.
</para>
</listitem>
<listitem>
<para>
Generate DS records for child zones from keyset files.
Existing DS records will be removed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-s <replaceable class="parameter">start-time</replaceable></term>
<listitem>
<para>
Specify the date and time when the generated RRSIG records
become valid. This can be either an absolute or relative
time. An absolute start time is indicated by a number
in YYYYMMDDHHMMSS notation; 20000530144500 denotes
14:45:00 UTC on May 30th, 2000. A relative start time is
indicated by +N, which is N seconds from the current time.
If no <option>start-time</option> is specified, the current
time minus 1 hour (to allow for clock skew) is used.
</para>
</listitem>
<listitem>
<para>
Specify the date and time when the generated RRSIG records
become valid. This can be either an absolute or relative
time. An absolute start time is indicated by a number
in YYYYMMDDHHMMSS notation; 20000530144500 denotes
14:45:00 UTC on May 30th, 2000. A relative start time is
indicated by +N, which is N seconds from the current time.
If no <option>start-time</option> is specified, the current
time minus 1 hour (to allow for clock skew) is used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-e <replaceable class="parameter">end-time</replaceable></term>
<listitem>
<para>
Specify the date and time when the generated RRSIG records
expire. As with <option>start-time</option>, an absolute
time is indicated in YYYYMMDDHHMMSS notation. A time relative
to the start time is indicated with +N, which is N seconds from
the start time. A time relative to the current time is
indicated with now+N. If no <option>end-time</option> is
specified, 30 days from the start time is used as a default.
</para>
</listitem>
<listitem>
<para>
Specify the date and time when the generated RRSIG records
expire. As with <option>start-time</option>, an absolute
time is indicated in YYYYMMDDHHMMSS notation. A time relative
to the start time is indicated with +N, which is N seconds from
the start time. A time relative to the current time is
indicated with now+N. If no <option>end-time</option> is
specified, 30 days from the start time is used as a default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-f <replaceable class="parameter">output-file</replaceable></term>
<listitem>
<para>
The name of the output file containing the signed zone. The
default is to append <filename>.signed</filename> to the
input file.
</para>
</listitem>
<listitem>
<para>
The name of the output file containing the signed zone. The
default is to append <filename>.signed</filename> to
the
input file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-h</term>
<listitem>
<para>
Prints a short summary of the options and arguments to
<command>dnssec-signzone</command>.
</para>
</listitem>
<listitem>
<para>
Prints a short summary of the options and arguments to
<command>dnssec-signzone</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-i <replaceable class="parameter">interval</replaceable></term>
<listitem>
<para>
When a previously signed zone is passed as input, records
may be resigned. The <option>interval</option> option
specifies the cycle interval as an offset from the current
time (in seconds). If a RRSIG record expires after the
cycle interval, it is retained. Otherwise, it is considered
to be expiring soon, and it will be replaced.
</para>
<para>
The default cycle interval is one quarter of the difference
between the signature end and start times. So if neither
<option>end-time</option> or <option>start-time</option>
are specified, <command>dnssec-signzone</command> generates
signatures that are valid for 30 days, with a cycle
interval of 7.5 days. Therefore, if any existing RRSIG records
are due to expire in less than 7.5 days, they would be
replaced.
</para>
</listitem>
<listitem>
<para>
When a previously signed zone is passed as input, records
may be resigned. The <option>interval</option> option
specifies the cycle interval as an offset from the current
time (in seconds). If a RRSIG record expires after the
cycle interval, it is retained. Otherwise, it is considered
to be expiring soon, and it will be replaced.
</para>
<para>
The default cycle interval is one quarter of the difference
between the signature end and start times. So if neither
<option>end-time</option> or <option>start-time</option>
are specified, <command>dnssec-signzone</command>
generates
signatures that are valid for 30 days, with a cycle
interval of 7.5 days. Therefore, if any existing RRSIG records
are due to expire in less than 7.5 days, they would be
replaced.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<listitem>
<para>
When signing a zone with a fixed signature lifetime, all
RRSIG records issued at the time of signing expires
simultaneously. If the zone is incrementally signed, i.e.
a previously signed zone is passed as input to the signer,
all expired signatures has to be regenerated at about the
same time. The <option>jitter</option> option specifies a
jitter window that will be used to randomize the signature
expire time, thus spreading incremental signature
regeneration over time.
</para>
<para>
Signature lifetime jitter also to some extent benefits
validators and servers by spreading out cache expiration,
i.e. if large numbers of RRSIGs don't expire at the same time
from all caches there will be less congestion than if all
validators need to refetch at mostly the same time.
</para>
</listitem>
<term>-j <replaceable class="parameter">jitter</replaceable></term>
<listitem>
<para>
When signing a zone with a fixed signature lifetime, all
RRSIG records issued at the time of signing expires
simultaneously. If the zone is incrementally signed, i.e.
a previously signed zone is passed as input to the signer,
all expired signatures has to be regenerated at about the
same time. The <option>jitter</option> option specifies a
jitter window that will be used to randomize the signature
expire time, thus spreading incremental signature
regeneration over time.
</para>
<para>
Signature lifetime jitter also to some extent benefits
validators and servers by spreading out cache expiration,
i.e. if large numbers of RRSIGs don't expire at the same time
from all caches there will be less congestion than if all
validators need to refetch at mostly the same time.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-n <replaceable class="parameter">ncpus</replaceable></term>
<listitem>
<para>
Specifies the number of threads to use. By default, one
thread is started for each detected CPU.
</para>
</listitem>
<listitem>
<para>
Specifies the number of threads to use. By default, one
thread is started for each detected CPU.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-o <replaceable class="parameter">origin</replaceable></term>
<listitem>
<para>
The zone origin. If not specified, the name of the zone file
is assumed to be the origin.
</para>
</listitem>
<listitem>
<para>
The zone origin. If not specified, the name of the zone file
is assumed to be the origin.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-p</term>
<listitem>
<para>
Use pseudo-random data when signing the zone. This is faster,
but less secure, than using real random data. This option
may be useful when signing large zones or when the entropy
source is limited.
</para>
</listitem>
<listitem>
<para>
Use pseudo-random data when signing the zone. This is faster,
but less secure, than using real random data. This option
may be useful when signing large zones or when the entropy
source is limited.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-r <replaceable class="parameter">randomdev</replaceable></term>
<listitem>
<para>
Specifies the source of randomness. If the operating
system does not provide a <filename>/dev/random</filename>
or equivalent device, the default source of randomness
is keyboard input. <filename>randomdev</filename> specifies
the name of a character device or file containing random
data to be used instead of the default. The special value
<filename>keyboard</filename> indicates that keyboard
input should be used.
</para>
</listitem>
<listitem>
<para>
Specifies the source of randomness. If the operating
system does not provide a <filename>/dev/random</filename>
or equivalent device, the default source of randomness
is keyboard input. <filename>randomdev</filename>
specifies
the name of a character device or file containing random
data to be used instead of the default. The special value
<filename>keyboard</filename> indicates that keyboard
input should be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-t</term>
<listitem>
<para>
Print statistics at completion.
</para>
</listitem>
<listitem>
<para>
Print statistics at completion.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-v <replaceable class="parameter">level</replaceable></term>
<listitem>
<para>
Sets the debugging level.
</para>
</listitem>
<listitem>
<para>
Sets the debugging level.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-z</term>
<listitem>
<para>
Ignore KSK flag on key when determining what to sign.
</para>
</listitem>
<listitem>
<para>
Ignore KSK flag on key when determining what to sign.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>zonefile</term>
<listitem>
<para>
The file containing the zone to be signed.
Sets the debugging level.
</para>
</listitem>
<listitem>
<para>
The file containing the zone to be signed.
Sets the debugging level.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>key</term>
<listitem>
<para>
The keys used to sign the zone. If no keys are specified, the
default all zone keys that have private key files in the
current directory.
</para>
</listitem>
<listitem>
<para>
The keys used to sign the zone. If no keys are specified, the
default all zone keys that have private key files in the
current directory.
</para>
</listitem>
</varlistentry>
</variablelist>
@@ -337,34 +355,34 @@
<refsect1>
<title>EXAMPLE</title>
<para>
The following command signs the <userinput>example.com</userinput>
zone with the DSA key generated in the <command>dnssec-keygen</command>
man page. The zone's keys must be in the zone. If there are
<filename>keyset</filename> files associated with child zones,
they must be in the current directory.
<userinput>example.com</userinput>, the following command would be
issued:
The following command signs the <userinput>example.com</userinput>
zone with the DSA key generated in the <command>dnssec-keygen</command>
man page. The zone's keys must be in the zone. If there are
<filename>keyset</filename> files associated with child
zones,
they must be in the current directory.
<userinput>example.com</userinput>, the following command would be
issued:
</para>
<para><userinput>dnssec-signzone -o example.com db.example.com
Kexample.com.+003+26160</userinput>
</para>
<para>
<userinput>dnssec-signzone -o example.com db.example.com Kexample.com.+003+26160</userinput>
The command would print a string of the form:
</para>
<para>
The command would print a string of the form:
</para>
<para>
In this example, <command>dnssec-signzone</command> creates
the file <filename>db.example.com.signed</filename>. This file
should be referenced in a zone statement in a
<filename>named.conf</filename> file.
In this example, <command>dnssec-signzone</command> creates
the file <filename>db.example.com.signed</filename>. This
file
should be referenced in a zone statement in a
<filename>named.conf</filename> file.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>dnssec-keygen</refentrytitle>
<manvolnum>8</manvolnum>
<para><citerefentry>
<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>,
<citetitle>RFC 2535</citetitle>.
@@ -373,14 +391,11 @@
<refsect1>
<title>AUTHOR</title>
<para>
<corpauthor>Internet Systems Consortium</corpauthor>
<para><corpauthor>Internet Systems Consortium</corpauthor>
</para>
</refsect1>
</refentry>
<!--
</refentry><!--
- Local variables:
- mode: sgml
- End:

316
bin/named/lwresd.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,9 +17,7 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwresd.docbook,v 1.8 2004/06/03 02:22:32 marka Exp $ -->
<!-- $Id: lwresd.docbook,v 1.9 2005/05/11 05:55:36 sra Exp $ -->
<refentry>
<refentryinfo>
<date>June 30, 2000</date>
@@ -34,6 +34,18 @@
<refpurpose>lightweight resolver daemon</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2004</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<cmdsynopsis>
<command>lwresd</command>
@@ -54,37 +66,39 @@
<refsect1>
<title>DESCRIPTION</title>
<para>
<command>lwresd</command> is the daemon providing name lookup
services to clients that use the BIND 9 lightweight resolver
library. It is essentially a stripped-down, caching-only name
server that answers queries using the BIND 9 lightweight
resolver protocol rather than the DNS protocol.
<para><command>lwresd</command>
is the daemon providing name lookup
services to clients that use the BIND 9 lightweight resolver
library. It is essentially a stripped-down, caching-only name
server that answers queries using the BIND 9 lightweight
resolver protocol rather than the DNS protocol.
</para>
<para><command>lwresd</command>
listens for resolver queries on a
UDP port on the IPv4 loopback interface, 127.0.0.1. This
means that <command>lwresd</command> can only be used by
processes running on the local machine. By default UDP port
number 921 is used for lightweight resolver requests and
responses.
</para>
<para>
<command>lwresd</command> listens for resolver queries on a
UDP port on the IPv4 loopback interface, 127.0.0.1. This
means that <command>lwresd</command> can only be used by
processes running on the local machine. By default UDP port
number 921 is used for lightweight resolver requests and
responses.
Incoming lightweight resolver requests are decoded by the
server which then resolves them using the DNS protocol. When
the DNS lookup completes, <command>lwresd</command> encodes
the answers in the lightweight resolver format and returns
them to the client that made the request.
</para>
<para>
Incoming lightweight resolver requests are decoded by the
server which then resolves them using the DNS protocol. When
the DNS lookup completes, <command>lwresd</command> encodes
the answers in the lightweight resolver format and returns
them to the client that made the request.
</para>
<para>
If <filename>/etc/resolv.conf</filename> contains any
<option>nameserver</option> entries, <command>lwresd</command>
sends recursive DNS queries to those servers. This is similar
to the use of forwarders in a caching name server. If no
<option>nameserver</option> entries are present, or if
forwarding fails, <command>lwresd</command> resolves the
queries autonomously starting at the root name servers, using
a built-in list of root server hints.
If <filename>/etc/resolv.conf</filename> contains any
<option>nameserver</option> entries, <command>lwresd</command>
sends recursive DNS queries to those servers. This is similar
to the use of forwarders in a caching name server. If no
<option>nameserver</option> entries are present, or if
forwarding fails, <command>lwresd</command> resolves the
queries autonomously starting at the root name servers, using
a built-in list of root server hints.
</para>
</refsect1>
@@ -93,145 +107,139 @@
<variablelist>
<varlistentry>
<term>-C <replaceable class="parameter">config-file</replaceable></term>
<listitem>
<para>
Use <replaceable
class="parameter">config-file</replaceable> as the
configuration file instead of the default,
<filename>/etc/resolv.conf</filename>.
<term>-C <replaceable class="parameter">config-file</replaceable></term>
<listitem>
<para>
Use <replaceable class="parameter">config-file</replaceable> as the
configuration file instead of the default,
<filename>/etc/resolv.conf</filename>.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-d <replaceable class="parameter">debug-level</replaceable></term>
<listitem>
<para>
Set the daemon's debug level to <replaceable
class="parameter">debug-level</replaceable>.
Debugging traces from <command>lwresd</command> become
more verbose as the debug level increases.
<term>-d <replaceable class="parameter">debug-level</replaceable></term>
<listitem>
<para>
Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>.
Debugging traces from <command>lwresd</command> become
more verbose as the debug level increases.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-f</term>
<listitem>
<para>
Run the server in the foreground (i.e. do not daemonize).
<term>-f</term>
<listitem>
<para>
Run the server in the foreground (i.e. do not daemonize).
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-g</term>
<listitem>
<para>
Run the server in the foreground and force all logging
to <filename>stderr</filename>.
<term>-g</term>
<listitem>
<para>
Run the server in the foreground and force all logging
to <filename>stderr</filename>.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-n <replaceable class="parameter">#cpus</replaceable></term>
<listitem>
<para>
Create <replaceable
class="parameter">#cpus</replaceable> worker threads
to take advantage of multiple CPUs. If not specified,
<command>lwresd</command> will try to determine the
number of CPUs present and create one thread per CPU.
If it is unable to determine the number of CPUs, a
single worker thread will be created.
<term>-n <replaceable class="parameter">#cpus</replaceable></term>
<listitem>
<para>
Create <replaceable class="parameter">#cpus</replaceable> worker threads
to take advantage of multiple CPUs. If not specified,
<command>lwresd</command> will try to determine the
number of CPUs present and create one thread per CPU.
If it is unable to determine the number of CPUs, a
single worker thread will be created.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-P <replaceable class="parameter">port</replaceable></term>
<listitem>
<para>
Listen for lightweight resolver queries on port
<replaceable class="parameter">port</replaceable>. If
not specified, the default is port 921.
<term>-P <replaceable class="parameter">port</replaceable></term>
<listitem>
<para>
Listen for lightweight resolver queries on port
<replaceable class="parameter">port</replaceable>. If
not specified, the default is port 921.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-p <replaceable class="parameter">port</replaceable></term>
<listitem>
<para>
Send DNS lookups to port <replaceable
class="parameter">port</replaceable>. If not
specified, the default is port 53. This provides a
way of testing the lightweight resolver daemon with a
name server that listens for queries on a non-standard
port number.
<term>-p <replaceable class="parameter">port</replaceable></term>
<listitem>
<para>
Send DNS lookups to port <replaceable class="parameter">port</replaceable>. If not
specified, the default is port 53. This provides a
way of testing the lightweight resolver daemon with a
name server that listens for queries on a non-standard
port number.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-s</term>
<listitem>
<para>
Write memory usage statistics to <filename>stdout</filename>
on exit.
<term>-s</term>
<listitem>
<para>
Write memory usage statistics to <filename>stdout</filename>
on exit.
</para>
<note>
<para>
This option is mainly of interest to BIND 9 developers
and may be removed or changed in a future release.
</para>
</note>
</listitem>
<note>
<para>
This option is mainly of interest to BIND 9 developers
and may be removed or changed in a future release.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>-t <replaceable class="parameter">directory</replaceable></term>
<listitem>
<para>
<function>chroot()</function> to <replaceable
class="parameter">directory</replaceable> after
processing the command line arguments, but before
reading the configuration file.
<term>-t <replaceable class="parameter">directory</replaceable></term>
<listitem>
<para><function>chroot()</function>
to <replaceable class="parameter">directory</replaceable> after
processing the command line arguments, but before
reading the configuration file.
</para>
<warning>
<para>
This option should be used in conjunction with the
<option>-u</option> option, as chrooting a process
running as root doesn't enhance security on most
systems; the way <function>chroot()</function> is
defined allows a process with root privileges to
escape a chroot jail.
</para>
</warning>
</listitem>
<warning>
<para>
This option should be used in conjunction with the
<option>-u</option> option, as chrooting a process
running as root doesn't enhance security on most
systems; the way <function>chroot()</function> is
defined allows a process with root privileges to
escape a chroot jail.
</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
<term>-u <replaceable class="parameter">user</replaceable></term>
<listitem>
<para>
<function>setuid()</function> to <replaceable
class="parameter">user</replaceable> after completing
privileged operations, such as creating sockets that
listen on privileged ports.
<term>-u <replaceable class="parameter">user</replaceable></term>
<listitem>
<para><function>setuid()</function>
to <replaceable class="parameter">user</replaceable> after completing
privileged operations, such as creating sockets that
listen on privileged ports.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-v</term>
<listitem>
<para>
Report the version number and exit.
<term>-v</term>
<listitem>
<para>
Report the version number and exit.
</para>
</listitem>
</listitem>
</varlistentry>
</variablelist>
@@ -244,21 +252,21 @@
<variablelist>
<varlistentry>
<term><filename>/etc/resolv.conf</filename></term>
<listitem>
<para>
The default configuration file.
<term><filename>/etc/resolv.conf</filename></term>
<listitem>
<para>
The default configuration file.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/var/run/lwresd.pid</filename></term>
<listitem>
<para>
The default process-id file.
<term><filename>/var/run/lwresd.pid</filename></term>
<listitem>
<para>
The default process-id file.
</para>
</listitem>
</listitem>
</varlistentry>
</variablelist>
@@ -267,33 +275,25 @@
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>named</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>resolver</refentrytitle>
<manvolnum>5</manvolnum>
</citerefentry>.
<para><citerefentry>
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
</citerefentry>.
</para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>
<corpauthor>Internet Systems Consortium</corpauthor>
<para><corpauthor>Internet Systems Consortium</corpauthor>
</para>
</refsect1>
</refentry>
<!--
</refentry><!--
- Local variables:
- mode: sgml
- End:

185
bin/named/named.conf.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
-
@@ -14,9 +16,7 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: named.conf.docbook,v 1.8 2005/01/17 00:46:01 marka Exp $ -->
<!-- $Id: named.conf.docbook,v 1.9 2005/05/11 05:55:36 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Aug 13, 2004</date>
@@ -33,6 +33,14 @@
<refpurpose>configuration file for named</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<cmdsynopsis>
<command>named.conf</command>
@@ -41,55 +49,55 @@
<refsect1>
<title>DESCRIPTION</title>
<para>
<filename>named.conf</filename> is the configuration file for
<command>named</command>. Statements are enclosed
in braces and terminated with a semi-colon. Clauses in
the statements are also semi-colon terminated. The usual
comment styles are supported:
<para><filename>named.conf</filename> is the configuration file
for
<command>named</command>. Statements are enclosed
in braces and terminated with a semi-colon. Clauses in
the statements are also semi-colon terminated. The usual
comment styles are supported:
</para>
<para>
C style: /* */
C style: /* */
</para>
<para>
C++ style: // to end of line
C++ style: // to end of line
</para>
<para>
Unix style: # to end of line
Unix style: # to end of line
</para>
</refsect1>
<refsect1>
<title>ACL</title>
<LITERALLAYOUT>
<refsect1>
<title>ACL</title>
<literallayout>
acl <replaceable>string</replaceable> { <replaceable>address_match_element</replaceable>; ... };
</LITERALLAYOUT>
</refsect1>
</literallayout>
</refsect1>
<refsect1>
<title>KEY</title>
<LITERALLAYOUT>
<refsect1>
<title>KEY</title>
<literallayout>
key <replaceable>domain_name</replaceable> {
algorithm <replaceable>string</replaceable>;
secret <replaceable>string</replaceable>;
};
</LITERALLAYOUT>
</refsect1>
</literallayout>
</refsect1>
<refsect1>
<title>MASTERS</title>
<LITERALLAYOUT>
<refsect1>
<title>MASTERS</title>
<literallayout>
masters <replaceable>string</replaceable> <optional> port <replaceable>integer</replaceable> </optional> {
( <replaceable>masters</replaceable> | <replaceable>ipv4_address</replaceable> <optional>port <replaceable>integer</replaceable></optional> |
<replaceable>ipv6_address</replaceable> <optional>port <replaceable>integer</replaceable></optional> ) <optional> key <replaceable>string</replaceable> </optional>; ...
};
</LITERALLAYOUT>
</refsect1>
</literallayout>
</refsect1>
<refsect1>
<title>SERVER</title>
<LITERALLAYOUT>
<refsect1>
<title>SERVER</title>
<literallayout>
server ( <replaceable>ipv4_address<optional>/prefixlen</optional></replaceable> | <replaceable>ipv6_address<optional>/prefixlen</optional></replaceable> ) {
bogus <replaceable>boolean</replaceable>;
edns <replaceable>boolean</replaceable>;
@@ -105,21 +113,21 @@ server ( <replaceable>ipv4_address<optional>/prefixlen</optional></replaceable>
support-ixfr <replaceable>boolean</replaceable>; // obsolete
};
</LITERALLAYOUT>
</refsect1>
</literallayout>
</refsect1>
<refsect1>
<title>TRUSTED-KEYS</title>
<LITERALLAYOUT>
<refsect1>
<title>TRUSTED-KEYS</title>
<literallayout>
trusted-keys {
<replaceable>domain_name</replaceable> <replaceable>flags</replaceable> <replaceable>protocol</replaceable> <replaceable>algorithm</replaceable> <replaceable>key</replaceable>; ...
};
</LITERALLAYOUT>
</refsect1>
</literallayout>
</refsect1>
<refsect1>
<title>CONTROLS</title>
<LITERALLAYOUT>
<refsect1>
<title>CONTROLS</title>
<literallayout>
controls {
inet ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> | * )
<optional> port ( <replaceable>integer</replaceable> | * ) </optional>
@@ -127,12 +135,12 @@ controls {
<optional> keys { <replaceable>string</replaceable>; ... } </optional>;
unix <replaceable>unsupported</replaceable>; // not implemented
};
</LITERALLAYOUT>
</refsect1>
</literallayout>
</refsect1>
<refsect1>
<title>LOGGING</title>
<LITERALLAYOUT>
<refsect1>
<title>LOGGING</title>
<literallayout>
logging {
channel <replaceable>string</replaceable> {
file <replaceable>log_file</replaceable>;
@@ -146,12 +154,12 @@ logging {
};
category <replaceable>string</replaceable> { <replaceable>string</replaceable>; ... };
};
</LITERALLAYOUT>
</refsect1>
</literallayout>
</refsect1>
<refsect1>
<title>LWRES</title>
<LITERALLAYOUT>
<refsect1>
<title>LWRES</title>
<literallayout>
lwres {
listen-on <optional> port <replaceable>integer</replaceable> </optional> {
( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> ) <optional> port <replaceable>integer</replaceable> </optional>; ...
@@ -160,12 +168,12 @@ lwres {
search { <replaceable>string</replaceable>; ... };
ndots <replaceable>integer</replaceable>;
};
</LITERALLAYOUT>
</refsect1>
</literallayout>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<LITERALLAYOUT>
<refsect1>
<title>OPTIONS</title>
<literallayout>
options {
avoid-v4-udp-ports { <replaceable>port</replaceable>; ... };
avoid-v6-udp-ports { <replaceable>port</replaceable>; ... };
@@ -307,12 +315,12 @@ options {
treat-cr-as-space <replaceable>boolean</replaceable>; // obsolete
use-id-pool <replaceable>boolean</replaceable>; // obsolete
};
</LITERALLAYOUT>
</refsect1>
</literallayout>
</refsect1>
<refsect1>
<title>VIEW</title>
<LITERALLAYOUT>
<refsect1>
<title>VIEW</title>
<literallayout>
view <replaceable>string</replaceable> <replaceable>optional_class</replaceable> {
match-clients { <replaceable>address_match_element</replaceable>; ... };
match-destinations { <replaceable>address_match_element</replaceable>; ... };
@@ -429,12 +437,12 @@ view <replaceable>string</replaceable> <replaceable>optional_class</replaceable>
maintain-ixfr-base <replaceable>boolean</replaceable>; // obsolete
max-ixfr-log-size <replaceable>size</replaceable>; // obsolete
};
</LITERALLAYOUT>
</refsect1>
</literallayout>
</refsect1>
<refsect1>
<title>ZONE</title>
<LITERALLAYOUT>
<refsect1>
<title>ZONE</title>
<literallayout>
zone <replaceable>string</replaceable> <replaceable>optional_class</replaceable> {
type ( master | slave | stub | hint |
forward | delegation-only );
@@ -508,33 +516,30 @@ zone <replaceable>string</replaceable> <replaceable>optional_class</replaceable>
max-ixfr-log-size <replaceable>size</replaceable>; // obsolete
pubkey <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; // obsolete
};
</LITERALLAYOUT>
</refsect1>
</literallayout>
</refsect1>
<refsect1>
<title>FILES</title>
<para>
<filename>/etc/named.conf</filename>
</para>
</refsect1>
<refsect1>
<title>FILES</title>
<para><filename>/etc/named.conf</filename>
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>BIND 9 Adminstrators Reference Manual</refentrytitle>
</citerefentry>.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>BIND 9 Administrator Reference Manual</refentrytitle>
</citerefentry>.
</para>
</refsect1>
</refentry>
<!--
</refentry><!--
- Local variables:
- mode: sgml
- End:

389
bin/named/named.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
@@ -15,9 +17,7 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: named.docbook,v 1.8 2004/06/03 02:22:33 marka Exp $ -->
<!-- $Id: named.docbook,v 1.9 2005/05/11 05:55:36 sra Exp $ -->
<refentry>
<refentryinfo>
<date>June 30, 2000</date>
@@ -34,6 +34,19 @@
<refpurpose>Internet domain name server</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2004</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<year>2003</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<cmdsynopsis>
<command>named</command>
@@ -55,16 +68,17 @@
<refsect1>
<title>DESCRIPTION</title>
<para>
<command>named</command> is a Domain Name System (DNS) server,
part of the BIND 9 distribution from ISC. For more
information on the DNS, see RFCs 1033, 1034, and 1035.
<para><command>named</command>
is a Domain Name System (DNS) server,
part of the BIND 9 distribution from ISC. For more
information on the DNS, see RFCs 1033, 1034, and 1035.
</para>
<para>
When invoked without arguments, <command>named</command> will
read the default configuration file
<filename>/etc/named.conf</filename>, read any initial
data, and listen for queries.
When invoked without arguments, <command>named</command>
will
read the default configuration file
<filename>/etc/named.conf</filename>, read any initial
data, and listen for queries.
</para>
</refsect1>
@@ -73,189 +87,183 @@
<variablelist>
<varlistentry>
<term>-4</term>
<listitem>
<para>
Use IPv4 only even if the host machine is capable of IPv6.
<option>-4</option> and <option>-6</option> are mutually
exclusive.
<term>-4</term>
<listitem>
<para>
Use IPv4 only even if the host machine is capable of IPv6.
<option>-4</option> and <option>-6</option> are mutually
exclusive.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-6</term>
<listitem>
<para>
Use IPv6 only even if the host machine is capable of IPv4.
<option>-4</option> and <option>-6</option> are mutually
exclusive.
<term>-6</term>
<listitem>
<para>
Use IPv6 only even if the host machine is capable of IPv4.
<option>-4</option> and <option>-6</option> are mutually
exclusive.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-c <replaceable class="parameter">config-file</replaceable></term>
<listitem>
<para>
Use <replaceable
class="parameter">config-file</replaceable> as the
configuration file instead of the default,
<filename>/etc/named.conf</filename>. To
ensure that reloading the configuration file continues
to work after the server has changed its working
directory due to to a possible
<option>directory</option> option in the configuration
file, <replaceable
class="parameter">config-file</replaceable> should be
an absolute pathname.
<term>-c <replaceable class="parameter">config-file</replaceable></term>
<listitem>
<para>
Use <replaceable class="parameter">config-file</replaceable> as the
configuration file instead of the default,
<filename>/etc/named.conf</filename>. To
ensure that reloading the configuration file continues
to work after the server has changed its working
directory due to to a possible
<option>directory</option> option in the configuration
file, <replaceable class="parameter">config-file</replaceable> should be
an absolute pathname.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-d <replaceable class="parameter">debug-level</replaceable></term>
<listitem>
<para>
Set the daemon's debug level to <replaceable
class="parameter">debug-level</replaceable>.
Debugging traces from <command>named</command> become
more verbose as the debug level increases.
<term>-d <replaceable class="parameter">debug-level</replaceable></term>
<listitem>
<para>
Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>.
Debugging traces from <command>named</command> become
more verbose as the debug level increases.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-f</term>
<listitem>
<para>
Run the server in the foreground (i.e. do not daemonize).
<term>-f</term>
<listitem>
<para>
Run the server in the foreground (i.e. do not daemonize).
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-g</term>
<listitem>
<para>
Run the server in the foreground and force all logging
to <filename>stderr</filename>.
<term>-g</term>
<listitem>
<para>
Run the server in the foreground and force all logging
to <filename>stderr</filename>.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-n <replaceable class="parameter">#cpus</replaceable></term>
<listitem>
<para>
Create <replaceable
class="parameter">#cpus</replaceable> worker threads
to take advantage of multiple CPUs. If not specified,
<command>named</command> will try to determine the
number of CPUs present and create one thread per CPU.
If it is unable to determine the number of CPUs, a
single worker thread will be created.
<term>-n <replaceable class="parameter">#cpus</replaceable></term>
<listitem>
<para>
Create <replaceable class="parameter">#cpus</replaceable> worker threads
to take advantage of multiple CPUs. If not specified,
<command>named</command> will try to determine the
number of CPUs present and create one thread per CPU.
If it is unable to determine the number of CPUs, a
single worker thread will be created.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-p <replaceable class="parameter">port</replaceable></term>
<listitem>
<para>
Listen for queries on port <replaceable
class="parameter">port</replaceable>. If not
specified, the default is port 53.
<term>-p <replaceable class="parameter">port</replaceable></term>
<listitem>
<para>
Listen for queries on port <replaceable class="parameter">port</replaceable>. If not
specified, the default is port 53.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-s</term>
<listitem>
<para>
Write memory usage statistics to <filename>stdout</filename> on exit.
<term>-s</term>
<listitem>
<para>
Write memory usage statistics to <filename>stdout</filename> on exit.
</para>
<note>
<para>
This option is mainly of interest to BIND 9 developers
and may be removed or changed in a future release.
</para>
</note>
</listitem>
<note>
<para>
This option is mainly of interest to BIND 9 developers
and may be removed or changed in a future release.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>-t <replaceable class="parameter">directory</replaceable></term>
<listitem>
<para>
<function>chroot()</function> to <replaceable
class="parameter">directory</replaceable> after
processing the command line arguments, but before
reading the configuration file.
<term>-t <replaceable class="parameter">directory</replaceable></term>
<listitem>
<para><function>chroot()</function>
to <replaceable class="parameter">directory</replaceable> after
processing the command line arguments, but before
reading the configuration file.
</para>
<warning>
<para>
This option should be used in conjunction with the
<option>-u</option> option, as chrooting a process
running as root doesn't enhance security on most
systems; the way <function>chroot()</function> is
defined allows a process with root privileges to
escape a chroot jail.
</para>
</warning>
</listitem>
<warning>
<para>
This option should be used in conjunction with the
<option>-u</option> option, as chrooting a process
running as root doesn't enhance security on most
systems; the way <function>chroot()</function> is
defined allows a process with root privileges to
escape a chroot jail.
</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
<term>-u <replaceable class="parameter">user</replaceable></term>
<listitem>
<para>
<function>setuid()</function> to <replaceable
class="parameter">user</replaceable> after completing
privileged operations, such as creating sockets that
listen on privileged ports.
<term>-u <replaceable class="parameter">user</replaceable></term>
<listitem>
<para><function>setuid()</function>
to <replaceable class="parameter">user</replaceable> after completing
privileged operations, such as creating sockets that
listen on privileged ports.
</para>
<note>
<para>
On Linux, <command>named</command> uses the kernel's
capability mechanism to drop all root privileges
except the ability to <function>bind()</function> to a
privileged port and set process resource limits.
Unfortunately, this means that the <option>-u</option>
option only works when <command>named</command> is run
on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or
later, since previous kernels did not allow privileges
to be retained after <function>setuid()</function>.
</para>
</note>
</listitem>
<note>
<para>
On Linux, <command>named</command> uses the kernel's
capability mechanism to drop all root privileges
except the ability to <function>bind()</function> to
a
privileged port and set process resource limits.
Unfortunately, this means that the <option>-u</option>
option only works when <command>named</command> is
run
on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or
later, since previous kernels did not allow privileges
to be retained after <function>setuid()</function>.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>-v</term>
<listitem>
<para>
Report the version number and exit.
<term>-v</term>
<listitem>
<para>
Report the version number and exit.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>-x <replaceable class="parameter">cache-file</replaceable></term>
<listitem>
<para>
Load data from <replaceable
class="parameter">cache-file</replaceable> into the
cache of the default view.
<term>-x <replaceable class="parameter">cache-file</replaceable></term>
<listitem>
<para>
Load data from <replaceable class="parameter">cache-file</replaceable> into the
cache of the default view.
</para>
<warning>
<para>
This option must not be used. It is only of interest
to BIND 9 developers and may be removed or changed in a
future release.
</para>
</warning>
</listitem>
<warning>
<para>
This option must not be used. It is only of interest
to BIND 9 developers and may be removed or changed in a
future release.
</para>
</warning>
</listitem>
</varlistentry>
</variablelist>
@@ -265,35 +273,35 @@
<refsect1>
<title>SIGNALS</title>
<para>
In routine operation, signals should not be used to control
the nameserver; <command>rndc</command> should be used
instead.
In routine operation, signals should not be used to control
the nameserver; <command>rndc</command> should be used
instead.
</para>
<variablelist>
<varlistentry>
<term>SIGHUP</term>
<listitem>
<para>
Force a reload of the server.
<term>SIGHUP</term>
<listitem>
<para>
Force a reload of the server.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>SIGINT, SIGTERM</term>
<listitem>
<para>
Shut down the server.
<term>SIGINT, SIGTERM</term>
<listitem>
<para>
Shut down the server.
</para>
</listitem>
</listitem>
</varlistentry>
</variablelist>
<para>
The result of sending any other signals to the server is undefined.
The result of sending any other signals to the server is undefined.
</para>
</refsect1>
@@ -301,10 +309,10 @@
<refsect1>
<title>CONFIGURATION</title>
<para>
The <command>named</command> configuration file is too complex
to describe in detail here. A complete description is
provided in the <citetitle>BIND 9 Administrator Reference
Manual</citetitle>.
The <command>named</command> configuration file is too complex
to describe in detail here. A complete description is provided
in the
<citetitle>BIND 9 Administrator Reference Manual</citetitle>.
</para>
</refsect1>
@@ -314,21 +322,21 @@
<variablelist>
<varlistentry>
<term><filename>/etc/named.conf</filename></term>
<listitem>
<para>
The default configuration file.
<term><filename>/etc/named.conf</filename></term>
<listitem>
<para>
The default configuration file.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/var/run/named.pid</filename></term>
<listitem>
<para>
The default process-id file.
<term><filename>/var/run/named.pid</filename></term>
<listitem>
<para>
The default process-id file.
</para>
</listitem>
</listitem>
</varlistentry>
</variablelist>
@@ -337,33 +345,26 @@
<refsect1>
<title>SEE ALSO</title>
<para>
<citetitle>RFC 1033</citetitle>,
<citetitle>RFC 1034</citetitle>,
<citetitle>RFC 1035</citetitle>,
<citerefentry>
<refentrytitle>rndc</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwresd</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>.
<para><citetitle>RFC 1033</citetitle>,
<citetitle>RFC 1034</citetitle>,
<citetitle>RFC 1035</citetitle>,
<citerefentry>
<refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>.
</para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>
<corpauthor>Internet Systems Consortium</corpauthor>
<para><corpauthor>Internet Systems Consortium</corpauthor>
</para>
</refsect1>
</refentry>
<!--
</refentry><!--
- Local variables:
- mode: sgml
- End:

1190
bin/nsupdate/nsupdate.docbook
View File

File diff suppressed because it is too large Load Diff

292
bin/rndc/rndc-confgen.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2001, 2003 Internet Software Consortium.
@@ -15,9 +17,7 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: rndc-confgen.docbook,v 1.7 2004/06/03 02:22:34 marka Exp $ -->
<!-- $Id: rndc-confgen.docbook,v 1.8 2005/05/11 05:55:37 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Aug 27, 2001</date>
@@ -34,6 +34,18 @@
<refpurpose>rndc key generation tool</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2004</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2001</year>
<year>2003</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<cmdsynopsis>
<command>rndc-confgen</command>
@@ -52,18 +64,18 @@
<refsect1>
<title>DESCRIPTION</title>
<para>
<command>rndc-confgen</command> generates configuration files
for <command>rndc</command>. It can be used as a
convenient alternative to writing the
<filename>rndc.conf</filename> file
and the corresponding <command>controls</command>
and <command>key</command>
statements in <filename>named.conf</filename> by hand.
Alternatively, it can be run with the <command>-a</command>
option to set up a <filename>rndc.key</filename> file and
avoid the need for a <filename>rndc.conf</filename> file
and a <command>controls</command> statement altogether.
<para><command>rndc-confgen</command>
generates configuration files
for <command>rndc</command>. It can be used as a
convenient alternative to writing the
<filename>rndc.conf</filename> file
and the corresponding <command>controls</command>
and <command>key</command>
statements in <filename>named.conf</filename> by hand.
Alternatively, it can be run with the <command>-a</command>
option to set up a <filename>rndc.key</filename> file and
avoid the need for a <filename>rndc.conf</filename> file
and a <command>controls</command> statement altogether.
</para>
</refsect1>
@@ -74,145 +86,152 @@
<variablelist>
<varlistentry>
<term>-a</term>
<listitem>
<para>
Do automatic <command>rndc</command> configuration.
This creates a file <filename>rndc.key</filename>
in <filename>/etc</filename> (or whatever
<varname>sysconfdir</varname>
was specified as when <acronym>BIND</acronym> was built)
that is read by both <command>rndc</command>
and <command>named</command> on startup. The
<filename>rndc.key</filename> file defines a default
command channel and authentication key allowing
<command>rndc</command> to communicate with
<command>named</command> on the local host
with no further configuration.
</para>
<para>
Running <command>rndc-confgen -a</command> allows
BIND 9 and <command>rndc</command> to be used as drop-in
replacements for BIND 8 and <command>ndc</command>,
with no changes to the existing BIND 8
<filename>named.conf</filename> file.
</para>
<listitem>
<para>
If a more elaborate configuration than that
generated by <command>rndc-confgen -a</command>
is required, for example if rndc is to be used remotely,
you should run <command>rndc-confgen</command> without the
<command>-a</command> option and set up a
<filename>rndc.conf</filename> and
<filename>named.conf</filename>
as directed.
Do automatic <command>rndc</command> configuration.
This creates a file <filename>rndc.key</filename>
in <filename>/etc</filename> (or whatever
<varname>sysconfdir</varname>
was specified as when <acronym>BIND</acronym> was
built)
that is read by both <command>rndc</command>
and <command>named</command> on startup. The
<filename>rndc.key</filename> file defines a default
command channel and authentication key allowing
<command>rndc</command> to communicate with
<command>named</command> on the local host
with no further configuration.
</para>
</listitem>
<para>
Running <command>rndc-confgen -a</command> allows
BIND 9 and <command>rndc</command> to be used as
drop-in
replacements for BIND 8 and <command>ndc</command>,
with no changes to the existing BIND 8
<filename>named.conf</filename> file.
</para>
<para>
If a more elaborate configuration than that
generated by <command>rndc-confgen -a</command>
is required, for example if rndc is to be used remotely,
you should run <command>rndc-confgen</command> without
the
<command>-a</command> option and set up a
<filename>rndc.conf</filename> and
<filename>named.conf</filename>
as directed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-b <replaceable class="parameter">keysize</replaceable></term>
<listitem>
<para>
Specifies the size of the authentication key in bits.
Must be between 1 and 512 bits; the default is 128.
</para>
</listitem>
<listitem>
<para>
Specifies the size of the authentication key in bits.
Must be between 1 and 512 bits; the default is 128.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-c <replaceable class="parameter">keyfile</replaceable></term>
<listitem>
<para>
Used with the <command>-a</command> option to specify
an alternate location for <filename>rndc.key</filename>.
</para>
</listitem>
<listitem>
<para>
Used with the <command>-a</command> option to specify
an alternate location for <filename>rndc.key</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-h</term>
<listitem>
<para>
Prints a short summary of the options and arguments to
<command>rndc-confgen</command>.
</para>
</listitem>
<listitem>
<para>
Prints a short summary of the options and arguments to
<command>rndc-confgen</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-k <replaceable class="parameter">keyname</replaceable></term>
<listitem>
<para>
Specifies the key name of the rndc authentication key.
This must be a valid domain name.
The default is <constant>rndc-key</constant>.
</para>
</listitem>
<listitem>
<para>
Specifies the key name of the rndc authentication key.
This must be a valid domain name.
The default is <constant>rndc-key</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-p <replaceable class="parameter">port</replaceable></term>
<listitem>
<para>
Specifies the command channel port where <command>named</command>
listens for connections from <command>rndc</command>.
The default is 953.
</para>
</listitem>
<listitem>
<para>
Specifies the command channel port where <command>named</command>
listens for connections from <command>rndc</command>.
The default is 953.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-r <replaceable class="parameter">randomfile</replaceable></term>
<listitem>
<para>
Specifies a source of random data for generating the
authorization. If the operating
system does not provide a <filename>/dev/random</filename>
or equivalent device, the default source of randomness
is keyboard input. <filename>randomdev</filename> specifies
the name of a character device or file containing random
data to be used instead of the default. The special value
<filename>keyboard</filename> indicates that keyboard
input should be used.
</para>
</listitem>
<listitem>
<para>
Specifies a source of random data for generating the
authorization. If the operating
system does not provide a <filename>/dev/random</filename>
or equivalent device, the default source of randomness
is keyboard input. <filename>randomdev</filename>
specifies
the name of a character device or file containing random
data to be used instead of the default. The special value
<filename>keyboard</filename> indicates that keyboard
input should be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-s <replaceable class="parameter">address</replaceable></term>
<listitem>
<para>
Specifies the IP address where <command>named</command>
listens for command channel connections from
<command>rndc</command>. The default is the loopback
address 127.0.0.1.
</para>
</listitem>
<listitem>
<para>
Specifies the IP address where <command>named</command>
listens for command channel connections from
<command>rndc</command>. The default is the loopback
address 127.0.0.1.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-t <replaceable class="parameter">chrootdir</replaceable></term>
<listitem>
<para>
Used with the <command>-a</command> option to specify
a directory where <command>named</command> will run
chrooted. An additional copy of the <filename>rndc.key</filename>
will be written relative to this directory so that
it will be found by the chrooted <command>named</command>.
</para>
</listitem>
<listitem>
<para>
Used with the <command>-a</command> option to specify
a directory where <command>named</command> will run
chrooted. An additional copy of the <filename>rndc.key</filename>
will be written relative to this directory so that
it will be found by the chrooted <command>named</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-u <replaceable class="parameter">user</replaceable></term>
<listitem>
<para>
Used with the <command>-a</command> option to set the owner
of the <filename>rndc.key</filename> file generated. If
<command>-t</command> is also specified only the file in
the chroot area has its owner changed.
</para>
</listitem>
<listitem>
<para>
Used with the <command>-a</command> option to set the
owner
of the <filename>rndc.key</filename> file generated.
If
<command>-t</command> is also specified only the file
in
the chroot area has its owner changed.
</para>
</listitem>
</varlistentry>
</variablelist>
@@ -221,37 +240,31 @@
<refsect1>
<title>EXAMPLES</title>
<para>
To allow <command>rndc</command> to be used with
no manual configuration, run
To allow <command>rndc</command> to be used with
no manual configuration, run
</para>
<para><userinput>rndc-confgen -a</userinput>
</para>
<para>
<userinput>rndc-confgen -a</userinput>
To print a sample <filename>rndc.conf</filename> file and
corresponding <command>controls</command> and <command>key</command>
statements to be manually inserted into <filename>named.conf</filename>,
run
</para>
<para>
To print a sample <filename>rndc.conf</filename> file and
corresponding <command>controls</command> and <command>key</command>
statements to be manually inserted into <filename>named.conf</filename>,
run
</para>
<para>
<userinput>rndc-confgen</userinput>
<para><userinput>rndc-confgen</userinput>
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>rndc</refentrytitle>
<manvolnum>8</manvolnum>
<para><citerefentry>
<refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>rndc.conf</refentrytitle>
<manvolnum>5</manvolnum>
<refentrytitle>rndc.conf</refentrytitle><manvolnum>5</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>named</refentrytitle>
<manvolnum>8</manvolnum>
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>.
</para>
@@ -259,14 +272,11 @@
<refsect1>
<title>AUTHOR</title>
<para>
<corpauthor>Internet Systems Consortium</corpauthor>
<para><corpauthor>Internet Systems Consortium</corpauthor>
</para>
</refsect1>
</refentry>
<!--
</refentry><!--
- Local variables:
- mode: sgml
- End:

244
bin/rndc/rndc.conf.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,9 +17,7 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: rndc.conf.docbook,v 1.9 2005/04/07 03:49:59 marka Exp $ -->
<!-- $Id: rndc.conf.docbook,v 1.10 2005/05/11 05:55:37 sra Exp $ -->
<refentry>
<refentryinfo>
<date>June 30, 2000</date>
@@ -34,6 +34,19 @@
<refpurpose>rndc configuration file</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<cmdsynopsis>
<command>rndc.conf</command>
@@ -42,176 +55,183 @@
<refsect1>
<title>DESCRIPTION</title>
<para>
<filename>rndc.conf</filename> is the configuration file
for <command>rndc</command>, the BIND 9 name server control
utility. This file has a similar structure and syntax to
<filename>named.conf</filename>. Statements are enclosed
in braces and terminated with a semi-colon. Clauses in
the statements are also semi-colon terminated. The usual
comment styles are supported:
<para><filename>rndc.conf</filename> is the configuration file
for <command>rndc</command>, the BIND 9 name server control
utility. This file has a similar structure and syntax to
<filename>named.conf</filename>. Statements are enclosed
in braces and terminated with a semi-colon. Clauses in
the statements are also semi-colon terminated. The usual
comment styles are supported:
</para>
<para>
C style: /* */
C style: /* */
</para>
<para>
C++ style: // to end of line
C++ style: // to end of line
</para>
<para>
Unix style: # to end of line
Unix style: # to end of line
</para>
<para><filename>rndc.conf</filename> is much simpler than
<filename>named.conf</filename>. The file uses three
statements: an options statement, a server statement
and a key statement.
</para>
<para>
<filename>rndc.conf</filename> is much simpler than
<filename>named.conf</filename>. The file uses three
statements: an options statement, a server statement
and a key statement.
The <option>options</option> statement contains five clauses.
The <option>default-server</option> clause is followed by the
name or address of a name server. This host will be used when
no name server is given as an argument to
<command>rndc</command>. The <option>default-key</option>
clause is followed by the name of a key which is identified by
a <option>key</option> statement. If no
<option>keyid</option> is provided on the rndc command line,
and no <option>key</option> clause is found in a matching
<option>server</option> statement, this default key will be
used to authenticate the server's commands and responses. The
<option>default-port</option> clause is followed by the port
to connect to on the remote name server. If no
<option>port</option> option is provided on the rndc command
line, and no <option>port</option> clause is found in a
matching <option>server</option> statement, this default port
will be used to connect.
The <option>default-source-address</option> and
<option>default-source-address-v6</option> clauses which
can be used to set the IPv4 and IPv6 source addresses
respectively.
</para>
<para>
The <option>options</option> statement contains five clauses.
The <option>default-server</option> clause is followed by the
name or address of a name server. This host will be used when
no name server is given as an argument to
<command>rndc</command>. The <option>default-key</option>
clause is followed by the name of a key which is identified by
a <option>key</option> statement. If no
<option>keyid</option> is provided on the rndc command line,
and no <option>key</option> clause is found in a matching
<option>server</option> statement, this default key will be
used to authenticate the server's commands and responses. The
<option>default-port</option> clause is followed by the port
to connect to on the remote name server. If no
<option>port</option> option is provided on the rndc command
line, and no <option>port</option> clause is found in a
matching <option>server</option> statement, this default port
will be used to connect.
The <option>default-source-address</option> and
<option>default-source-address-v6</option> clauses which
can be used to set the IPv4 and IPv6 source addresses
respectively.
After the <option>server</option> keyword, the server
statement includes a string which is the hostname or address
for a name server. The statement has three possible clauses:
<option>key</option>, <option>port</option> and
<option>addresses</option>. The key name must match the
name of a key statement in the file. The port number
specifies the port to connect to. If an <option>addresses</option>
clause is supplied these addresses will be used instead of
the server name. Each address can take a optional port.
If an <option>source-address</option> or <option>source-address-v6</option>
of supplied then these will be used to specify the IPv4 and IPv6
source addresses respectively.
</para>
<para>
After the <option>server</option> keyword, the server
statement includes a string which is the hostname or address
for a name server. The statement has three possible clauses:
<option>key</option>, <option>port</option> and
<option>addresses</option>. The key name must match the
name of a key statement in the file. The port number
specifies the port to connect to. If an <option>addresses</option>
clause is supplied these addresses will be used instead of
the server name. Each address can take a optional port.
If an <option>source-address</option> or <option>source-address-v6</option>
of supplied then these will be used to specify the IPv4 and IPv6
source addresses respectively.
The <option>key</option> statement begins with an identifying
string, the name of the key. The statement has two clauses.
<option>algorithm</option> identifies the encryption algorithm
for <command>rndc</command> to use; currently only HMAC-MD5
is
supported. This is followed by a secret clause which contains
the base-64 encoding of the algorithm's encryption key. The
base-64 string is enclosed in double quotes.
</para>
<para>
The <option>key</option> statement begins with an identifying
string, the name of the key. The statement has two clauses.
<option>algorithm</option> identifies the encryption algorithm
for <command>rndc</command> to use; currently only HMAC-MD5 is
supported. This is followed by a secret clause which contains
the base-64 encoding of the algorithm's encryption key. The
base-64 string is enclosed in double quotes.
</para>
<para>
There are two common ways to generate the base-64 string for the
secret. The BIND 9 program <command>rndc-confgen</command> can
be used to generate a random key, or the
<command>mmencode</command> program, also known as
<command>mimencode</command>, can be used to generate a base-64
string from known input. <command>mmencode</command> does not
ship with BIND 9 but is available on many systems. See the
EXAMPLE section for sample command lines for each.
There are two common ways to generate the base-64 string for the
secret. The BIND 9 program <command>rndc-confgen</command>
can
be used to generate a random key, or the
<command>mmencode</command> program, also known as
<command>mimencode</command>, can be used to generate a
base-64
string from known input. <command>mmencode</command> does
not
ship with BIND 9 but is available on many systems. See the
EXAMPLE section for sample command lines for each.
</para>
</refsect1>
<refsect1>
<title>EXAMPLE</title>
<programlisting>
<para><programlisting>
options {
default-server localhost;
default-key samplekey;
};
</programlisting>
</para>
<para><programlisting>
server localhost {
key samplekey;
};
</programlisting>
</para>
<para><programlisting>
server testserver {
key testkey;
addresses { localhost port 5353; };
};
</programlisting>
</para>
<para><programlisting>
key samplekey {
algorithm hmac-md5;
secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
};
</programlisting>
</para>
<para><programlisting>
key testkey {
algorithm hmac-md5;
secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
}
</programlisting>
</para>
<para>
In the above example, <command>rndc</command> will by default use
the server at localhost (127.0.0.1) and the key called samplekey.
Commands to the localhost server will use the samplekey key, which
must also be defined in the server's configuration file with the
same name and secret. The key statement indicates that samplekey
uses the HMAC-MD5 algorithm and its secret clause contains the
base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
In the above example, <command>rndc</command> will by
default use
the server at localhost (127.0.0.1) and the key called samplekey.
Commands to the localhost server will use the samplekey key, which
must also be defined in the server's configuration file with the
same name and secret. The key statement indicates that samplekey
uses the HMAC-MD5 algorithm and its secret clause contains the
base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
</para>
<para>
If <command>rndc -s testserver</command> is used then <command>rndc</command> will
connect to server on localhost port 5353 using the key testkey.
If <command>rndc -s testserver</command> is used then <command>rndc</command> will
connect to server on localhost port 5353 using the key testkey.
</para>
<para>
To generate a random secret with <command>rndc-confgen</command>:
To generate a random secret with <command>rndc-confgen</command>:
</para>
<para><userinput>rndc-confgen</userinput>
</para>
<para>
<userinput>rndc-confgen</userinput>
A complete <filename>rndc.conf</filename> file, including
the
randomly generated key, will be written to the standard
output. Commented out <option>key</option> and
<option>controls</option> statements for
<filename>named.conf</filename> are also printed.
</para>
<para>
A complete <filename>rndc.conf</filename> file, including the
randomly generated key, will be written to the standard
output. Commented out <option>key</option> and
<option>controls</option> statements for
<filename>named.conf</filename> are also printed.
To generate a base-64 secret with <command>mmencode</command>:
</para>
<para>
To generate a base-64 secret with <command>mmencode</command>:
</para>
<para>
<userinput>echo "known plaintext for a secret" | mmencode</userinput>
<para><userinput>echo "known plaintext for a secret" | mmencode</userinput>
</para>
</refsect1>
<refsect1>
<title>NAME SERVER CONFIGURATION</title>
<para>
The name server must be configured to accept rndc connections and
to recognize the key specified in the <filename>rndc.conf</filename>
file, using the controls statement in <filename>named.conf</filename>.
See the sections on the <option>controls</option> statement in the
BIND 9 Administrator Reference Manual for details.
The name server must be configured to accept rndc connections and
to recognize the key specified in the <filename>rndc.conf</filename>
file, using the controls statement in <filename>named.conf</filename>.
See the sections on the <option>controls</option> statement in the
BIND 9 Administrator Reference Manual for details.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>rndc</refentrytitle>
<manvolnum>8</manvolnum>
<para><citerefentry>
<refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>rndc-confgen</refentrytitle>
<manvolnum>8</manvolnum>
<refentrytitle>rndc-confgen</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>mmencode</refentrytitle>
<manvolnum>1</manvolnum>
<refentrytitle>mmencode</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>.
</para>
@@ -219,16 +239,12 @@
<refsect1>
<title>AUTHOR</title>
<para>
<corpauthor>Internet Systems Consortium</corpauthor>
<para><corpauthor>Internet Systems Consortium</corpauthor>
</para>
</refsect1>
</refentry>
<!--
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

240
bin/rndc/rndc.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,9 +17,7 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: rndc.docbook,v 1.11 2005/04/07 03:50:00 marka Exp $ -->
<!-- $Id: rndc.docbook,v 1.12 2005/05/11 05:55:37 sra Exp $ -->
<refentry>
<refentryinfo>
<date>June 30, 2000</date>
@@ -34,6 +34,19 @@
<refpurpose>name server control utility</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<cmdsynopsis>
<command>rndc</command>
@@ -50,31 +63,31 @@
<refsect1>
<title>DESCRIPTION</title>
<para>
<command>rndc</command> controls the operation of a name
server. It supersedes the <command>ndc</command> utility
that was provided in old BIND releases. If
<command>rndc</command> is invoked with no command line
options or arguments, it prints a short summary of the
supported commands and the available options and their
arguments.
<para><command>rndc</command>
controls the operation of a name
server. It supersedes the <command>ndc</command> utility
that was provided in old BIND releases. If
<command>rndc</command> is invoked with no command line
options or arguments, it prints a short summary of the
supported commands and the available options and their
arguments.
</para>
<para>
<command>rndc</command> communicates with the name server
over a TCP connection, sending commands authenticated with
digital signatures. In the current versions of
<command>rndc</command> and <command>named</command> named
the only supported authentication algorithm is HMAC-MD5,
which uses a shared secret on each end of the connection.
This provides TSIG-style authentication for the command
request and the name server's response. All commands sent
over the channel must be signed by a key_id known to the
server.
<para><command>rndc</command>
communicates with the name server
over a TCP connection, sending commands authenticated with
digital signatures. In the current versions of
<command>rndc</command> and <command>named</command> named
the only supported authentication algorithm is HMAC-MD5,
which uses a shared secret on each end of the connection.
This provides TSIG-style authentication for the command
request and the name server's response. All commands sent
over the channel must be signed by a key_id known to the
server.
</para>
<para>
<command>rndc</command> reads a configuration file to
determine how to contact the name server and decide what
algorithm and key it should use.
<para><command>rndc</command>
reads a configuration file to
determine how to contact the name server and decide what
algorithm and key it should use.
</para>
</refsect1>
@@ -84,96 +97,99 @@
<variablelist>
<varlistentry>
<term>-b <replaceable class="parameter">source-address</replaceable></term>
<listitem>
<para>
Use <replaceable class="parameter">source-address</replaceable>
as the source address for the connection to the server.
Multiple instances are permitted to allow setting of both
the IPv4 and IPv6 source addresses.
</para>
</listitem>
<listitem>
<para>
Use <replaceable class="parameter">source-address</replaceable>
as the source address for the connection to the server.
Multiple instances are permitted to allow setting of both
the IPv4 and IPv6 source addresses.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-c <replaceable class="parameter">config-file</replaceable></term>
<listitem>
<para>
Use <replaceable class="parameter">config-file</replaceable>
as the configuration file instead of the default,
<filename>/etc/rndc.conf</filename>.
</para>
</listitem>
<listitem>
<para>
Use <replaceable class="parameter">config-file</replaceable>
as the configuration file instead of the default,
<filename>/etc/rndc.conf</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-k <replaceable class="parameter">key-file</replaceable></term>
<listitem>
<para>
Use <replaceable class="parameter">key-file</replaceable>
as the key file instead of the default,
<filename>/etc/rndc.key</filename>. The key in
<filename>/etc/rndc.key</filename> will be used to authenticate
commands sent to the server if the <replaceable class="parameter">config-file</replaceable>
does not exist.
</para>
</listitem>
<listitem>
<para>
Use <replaceable class="parameter">key-file</replaceable>
as the key file instead of the default,
<filename>/etc/rndc.key</filename>. The key in
<filename>/etc/rndc.key</filename> will be used to
authenticate
commands sent to the server if the <replaceable class="parameter">config-file</replaceable>
does not exist.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-s <replaceable class="parameter">server</replaceable></term>
<listitem>
<para>
<replaceable class="parameter">server</replaceable> is
the name or address of the server which matches a
server statement in the configuration file for
<command>rndc</command>. If no server is supplied on the
command line, the host named by the default-server clause
in the option statement of the configuration file will be
used.
</para>
</listitem>
<listitem>
<para><replaceable class="parameter">server</replaceable> is
the name or address of the server which matches a
server statement in the configuration file for
<command>rndc</command>. If no server is supplied on
the
command line, the host named by the default-server clause
in the option statement of the configuration file will be
used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-p <replaceable class="parameter">port</replaceable></term>
<listitem>
<para>
Send commands to TCP port
<replaceable class="parameter">port</replaceable> instead
of BIND 9's default control channel port, 953.
</para>
</listitem>
<listitem>
<para>
Send commands to TCP port
<replaceable class="parameter">port</replaceable>
instead
of BIND 9's default control channel port, 953.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-V</term>
<listitem>
<para>
Enable verbose logging.
</para>
</listitem>
<listitem>
<para>
Enable verbose logging.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-y <replaceable class="parameter">keyid</replaceable></term>
<listitem>
<para>
Use the key <replaceable class="parameter">keyid</replaceable>
from the configuration file.
<replaceable class="parameter">keyid</replaceable> must be
known by named with the same algorithm and secret string
in order for control message validation to succeed.
If no <replaceable class="parameter">keyid</replaceable>
is specified, <command>rndc</command> will first look
for a key clause in the server statement of the server
being used, or if no server statement is present for that
host, then the default-key clause of the options statement.
Note that the configuration file contains shared secrets
which are used to send authenticated control commands
to name servers. It should therefore not have general read
or write access.
</para>
</listitem>
<listitem>
<para>
Use the key <replaceable class="parameter">keyid</replaceable>
from the configuration file.
<replaceable class="parameter">keyid</replaceable>
must be
known by named with the same algorithm and secret string
in order for control message validation to succeed.
If no <replaceable class="parameter">keyid</replaceable>
is specified, <command>rndc</command> will first look
for a key clause in the server statement of the server
being used, or if no server statement is present for that
host, then the default-key clause of the options statement.
Note that the configuration file contains shared secrets
which are used to send authenticated control commands
to name servers. It should therefore not have general read
or write access.
</para>
</listitem>
</varlistentry>
</variablelist>
@@ -181,44 +197,40 @@
<para>
For the complete set of commands supported by <command>rndc</command>,
see the BIND 9 Administrator Reference Manual or run
<command>rndc</command> without arguments to see its help message.
<command>rndc</command> without arguments to see its help
message.
</para>
</refsect1>
<refsect1>
<title>LIMITATIONS</title>
<para>
<command>rndc</command> does not yet support all the commands of
the BIND 8 <command>ndc</command> utility.
<para><command>rndc</command>
does not yet support all the commands of
the BIND 8 <command>ndc</command> utility.
</para>
<para>
There is currently no way to provide the shared secret for a
<option>key_id</option> without using the configuration file.
There is currently no way to provide the shared secret for a
<option>key_id</option> without using the configuration file.
</para>
<para>
Several error messages could be clearer.
Several error messages could be clearer.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>rndc.conf</refentrytitle>
<manvolnum>5</manvolnum>
<para><citerefentry>
<refentrytitle>rndc.conf</refentrytitle><manvolnum>5</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>named</refentrytitle>
<manvolnum>8</manvolnum>
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>named.conf</refentrytitle>
<manvolnum>5</manvolnum>
<refentrytitle>named.conf</refentrytitle><manvolnum>5</manvolnum>
</citerefentry>
<citerefentry>
<refentrytitle>ndc</refentrytitle>
<manvolnum>8</manvolnum>
<refentrytitle>ndc</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>.
</para>
@@ -226,16 +238,12 @@
<refsect1>
<title>AUTHOR</title>
<para>
<corpauthor>Internet Systems Consortium</corpauthor>
<para><corpauthor>Internet Systems Consortium</corpauthor>
</para>
</refsect1>
</refentry>
<!--
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

171
configure.in
View File

@@ -18,7 +18,7 @@ AC_DIVERT_PUSH(1)dnl
esyscmd([sed "s/^/# /" COPYRIGHT])dnl
AC_DIVERT_POP()dnl
AC_REVISION($Revision: 1.375 $)
AC_REVISION($Revision: 1.376 $)
AC_INIT(lib/dns/name.c)
AC_PREREQ(2.13)
@@ -1836,25 +1836,29 @@ AC_SUBST(ISC_PLATFORM_HAVEIFNAMETOINDEX)
# a developer editing the documentation source.
#
# Directory trees where SGML files are commonly found.
sgmltrees="/usr/pkg/share/sgml /usr/local/share/sgml /usr/share/sgml"
#
# Look for openjade. Plain jade is no longer supported.
#
AC_PATH_PROGS(OPENJADE, openjade, openjade)
AC_SUBST(OPENJADE)
#
# Look for TeX.
#
AC_PATH_PROGS(JADETEX, jadetex, jadetex)
AC_SUBST(JADETEX)
AC_PATH_PROGS(LATEX, latex, latex)
AC_SUBST(LATEX)
AC_PATH_PROGS(PDFJADETEX, pdfjadetex, pdfjadetex)
AC_SUBST(PDFJADETEX)
AC_PATH_PROGS(PDFLATEX, pdflatex, pdflatex)
AC_SUBST(PDFLATEX)
#
# Look for xsltproc (libxslt)
#
AC_PATH_PROG(XSLTPROC, xsltproc, xsltproc)
AC_SUBST(XSLTPROC)
#
# Look for xmllint (libxml2)
#
AC_PATH_PROG(XMLLINT, xmllint, xmllint)
AC_SUBST(XMLLINT)
#
# Subroutine for searching for an ordinary file (e.g., a stylesheet)
@@ -1891,74 +1895,60 @@ AC_SUBST($1)
])
#
# Look for the SGML catalog.
# Its location varies, so far we have seen:
# Look for Docbook-XSL stylesheets. Location probably varies by
# system. Guessing where it might be found, based on where SGML stuff
# lives on some systems. FreeBSD is the only one I'm sure of at the
# moment.
#
# NetBSD /usr/pkg/share/sgml/docbook/catalog
# FreeBSD /usr/local/share/sgml/docbook/catalog
# Linux /usr/local/share/dsssl/docbook/catalog
# /usr/share/sgml/docbook/dsssl-stylesheets/catalog
docbook_xsl_trees="/usr/pkg/share/xsl /usr/local/share/xsl /usr/share/xsl"
#
catalogpath=""
for d in $sgmltrees
# Look for stylesheets we need.
#
NOM_PATH_FILE(XSLT_DOCBOOK_STYLE_HTML, docbook/html/docbook.xsl, $docbook_xsl_trees)
NOM_PATH_FILE(XSLT_DOCBOOK_STYLE_XHTML, docbook/xhtml/docbook.xsl, $docbook_xsl_trees)
NOM_PATH_FILE(XSLT_DOCBOOK_STYLE_MAN, docbook/manpages/docbook.xsl, $docbook_xsl_trees)
NOM_PATH_FILE(XSLT_DOCBOOK_CHUNK_HTML, docbook/html/chunk.xsl, $docbook_xsl_trees)
NOM_PATH_FILE(XSLT_DOCBOOK_CHUNK_XHTML, docbook/xhtml/chunk.xsl, $docbook_xsl_trees)
#
# Same dance for db2latex
#
# No idea where this lives except on FreeBSD.
#
db2latex_xsl_trees="/usr/local/share"
#
# Look for stylesheets we need.
#
NOM_PATH_FILE(XSLT_DB2LATEX_STYLE, db2latex/xsl/docbook.xsl, $db2latex_xsl_trees)
#
# Look for "admonition" image directory. Can't use NOM_PATH_FILE()
# because it's a directory, so just do the same things, inline.
#
AC_MSG_CHECKING(for db2latex/xsl/figures)
for d in $db2latex_xsl_trees
do
catalogpath="$catalogpath $d"
for s in docbook/dsssl-stylesheets
do
catalogpath="$catalogpath $d/$s"
done
dd=$d/db2latex/xsl/figures
if test -d $dd
then
XSLT_DB2LATEX_ADMONITIONS=$dd
AC_MSG_RESULT($dd)
break
fi
done
NOM_PATH_FILE(SGMLCATALOG, catalog, $catalogpath)
#
# Look for the HTML stylesheet html/docbook.dsl, used for
# formatting man pages in HTML. Its location varies,
# so far we have seen:
#
# NetBSD /usr/pkg/share/sgml/docbook/dsssl/modular/
# FreeBSD /usr/local/share/sgml/docbook/dsssl/modular/
# Linux /usr/local/share/dsssl/docbook/
# /usr/share/sgml/docbook/dsssl-stylesheets/
#
# Ditto for the print stylesheet print/docbook.dsl.
#
stylepath=""
for d in $sgmltrees
do
for s in docbook/dsssl/modular dsssl/docbook docbook/dsssl-stylesheets
do
stylepath="$stylepath $d/$s"
done
done
NOM_PATH_FILE(HTMLSTYLE, html/docbook.dsl, $stylepath)
NOM_PATH_FILE(PRINTSTYLE, print/docbook.dsl, $stylepath)
#
# Look for XML declarations.
# Its location varies, so far we have seen:
#
# NetBSD /usr/pkg/share/sgml/docbook/dsssl/modular/dtds/decls/
# FreeBSD /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/
# Linux /usr/local/share/dsssl/docbook/dtds/decls/
# /usr/share/sgml/docbook/dsssl-stylesheets/dtds/decls/
#
xmlpath=""
for d in $sgmltrees
do
for s in docbook/dsssl/modular dsssl/docbook docbook/dsssl-stylesheets
do
xmlpath="$xmlpath $d/$s"
done
done
NOM_PATH_FILE(XMLDCL, dtds/decls/xml.dcl, $xmlpath)
#
# Look for docbook2man-spec.pl
#
NOM_PATH_FILE(DOCBOOK2MANSPEC, docbook2X/docbook2man-spec.pl, $sgmltrees)
if test "X$XSLT_DB2LATEX_ADMONITIONS" = "X"
then
AC_MSG_RESULT(not found)
XSLT_DB2LATEX_ADMONITIONS=db2latex/xsl/figures
fi
AC_SUBST(XSLT_DB2LATEX_ADMONITIONS)
#
# Substitutions
@@ -2016,6 +2006,20 @@ LIBBIND9_API=$srcdir/lib/bind9/api
AC_SUBST_FILE(LIBLWRES_API)
LIBLWRES_API=$srcdir/lib/lwres/api
#
# Commands to run at the end of config.status.
# Don't just put these into configure, it won't work right if somebody
# runs config.status directly (which autoconf allows).
#
AC_CONFIG_COMMANDS(
[chmod],
[chmod a+x isc-config.sh])
#
# Do it
#
AC_OUTPUT(
make/rules
make/includes
@@ -2086,14 +2090,13 @@ AC_OUTPUT(
bin/dnssec/Makefile
doc/Makefile
doc/arm/Makefile
doc/arm/nominum-docbook-html.dsl
doc/arm/nominum-docbook-print.dsl
doc/arm/validate.sh
doc/misc/Makefile
docutil/docbook2man-wrapper.sh
isc-config.sh
doc/xsl/isc-docbook-chunk.xsl
doc/xsl/isc-docbook-html.xsl
doc/xsl/isc-docbook-latex.xsl
doc/xsl/isc-manpage.xsl
)
chmod a+x isc-config.sh
# Tell Emacs to edit this file in shell mode.
# Local Variables:

13
doc/arm/.cvsignore
View File

@@ -1,8 +1,9 @@
Makefile
gendvi.sh
genhtml.sh
genpdf.sh
validate.sh
nominum-docbook-html.dsl
nominum-docbook-print.dsl
catalog
Bv9ARM.aux
Bv9ARM.brf
Bv9ARM.glo
Bv9ARM.idx
Bv9ARM.log
Bv9ARM.out
Bv9ARM.tex

15632
doc/arm/Bv9ARM-book.xml
View File

File diff suppressed because it is too large Load Diff

58
doc/arm/Makefile.in
View File

@@ -13,7 +13,7 @@
# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
# PERFORMANCE OF THIS SOFTWARE.
# $Id: Makefile.in,v 1.12 2004/03/05 05:04:43 marka Exp $
# $Id: Makefile.in,v 1.13 2005/05/11 05:55:34 sra Exp $
srcdir = @srcdir@
VPATH = @srcdir@
@@ -23,47 +23,41 @@ top_srcdir = @top_srcdir@
MANOBJS = Bv9ARM.html
PDFOBJS = Bv9ARM.pdf
distclean::
rm -f validate.sh
rm -f nominum-docbook-html.dsl nominum-docbook-print.dsl
rm -f HTML.index HTML.manifest
doc man:: ${MANOBJS}
doc man:: ${MANOBJS} ${PDFOBJS}
docclean manclean maintainer-clean::
rm -f *.html
clean::
rm -f Bv9ARM.aux Bv9ARM.brf Bv9ARM.glo Bv9ARM.idx
rm -f Bv9ARM.log Bv9ARM.out Bv9ARM.tex Bv9ARM.tex.tmp
Bv9ARM.html: Bv9ARM-book.xml nominum-docbook-html.dsl
${OPENJADE} -v \
-c ${SGMLCATALOG} \
-t sgml \
-d ./nominum-docbook-html.dsl \
${XMLDCL} ./Bv9ARM-book.xml
rm -f HTML.index HTML.manifest
docclean manclean maintainer-clean:: clean
rm -f *.html *.pdf
Bv9ARM-book.rtf: Bv9ARM-book.xml nominum-docbook-print.dsl
${OPENJADE} -v \
-c ${SGMLCATALOG} \
-t rtf \
-d ./nominum-docbook-print.dsl \
${XMLDCL} ./Bv9ARM-book.xml
Bv9ARM.html: Bv9ARM-book.xml
${XSLTPROC} --stringparam root.filename Bv9ARM \
${top_srcdir}/doc/xsl/isc-docbook-chunk.xsl \
Bv9ARM-book.xml
Bv9ARM-book.tex: Bv9ARM-book.xml nominum-docbook-print.dsl
${OPENJADE} -v \
-c ${SGMLCATALOG} \
-d ./nominum-docbook-print.dsl \
-t tex \
${XMLDCL} ./Bv9ARM-book.xml
Bv9ARM.tex: Bv9ARM-book.xml
${XSLTPROC} ${top_srcdir}/doc/xsl/pre-latex.xsl Bv9ARM-book.xml | \
${XSLTPROC} ${top_srcdir}/doc/xsl/isc-docbook-latex.xsl - | \
@PERL@ latex-fixup.pl >$@.tmp
if test -s $@.tmp; then mv $@.tmp $@; else rm -f $@.tmp; exit 1; fi
Bv9ARM-book.dvi: Bv9ARM-book.tex
Bv9ARM.dvi: Bv9ARM.tex
rm -f Bv9ARM-book.aux Bv9ARM-book.dvi Bv9ARM-book.log
${JADETEX} ./Bv9ARM-book.tex || true
${JADETEX} ./Bv9ARM-book.tex || true
${JADETEX} ./Bv9ARM-book.tex || true
${LATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@
${LATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@
${LATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@
Bv9ARM-book.pdf: Bv9ARM-book.tex
Bv9ARM.pdf: Bv9ARM.tex
rm -f Bv9ARM-book.aux Bv9ARM-book.pdf Bv9ARM-book.log
${PDFJADETEX} ./Bv9ARM-book.tex || true
${PDFJADETEX} ./Bv9ARM-book.tex || true
${PDFJADETEX} ./Bv9ARM-book.tex || true
${PDFLATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@
${PDFLATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@
${PDFLATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@

BIN
doc/arm/isc.color.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 6.2 KiB

45
doc/arm/latex-fixup.pl Normal file
View File

@@ -0,0 +1,45 @@
#!/usr/bin/perl -w
#
# Copyright (C) 2005 Internet Systems Consortium, Inc. ("ISC")
#
# Permission to use, copy, modify, and distribute this software for any
# purpose with or without fee is hereby granted, provided that the above
# copyright notice and this permission notice appear in all copies.
#
# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
# AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
# INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
# LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
# PERFORMANCE OF THIS SOFTWARE.
# $Id: latex-fixup.pl,v 1.2 2005/05/11 05:55:33 sra Exp $
# Sadly, the final stages of generating a presentable PDF file always
# seem to require some manual tweaking. Doesn't seem to matter what
# typesetting tool one uses, sane forms of automation only go so far,
# at least with present technology.
#
# This script is intended to be a collection of tweaks. The theory is
# that, while we can't avoid the need for tweaking, we can at least
# write the silly things down in a form that a program might be able
# to execute. Undoubtedly everythig in here will break, eventually,
# at which point it will need to be updated, but since the alternative
# is to do the final editing by hand every time, this approach seems
# the lesser of two evils.
while (<>) {
# At the moment, the only tweak we have is fixup for a db2latex
# oops. LaTeX2e does not like having tables with duplicate names.
# Perhaps the dblatex project will fix this someday, but we can
# get by with just deleting the offending LaTeX commands for now.
s/\\addtocounter\{table\}\{-1\}//g;
# Add any further tweaking here.
# Write out whatever we have now.
print;
}

148
doc/arm/nominum-docbook-html.dsl.in
View File

@@ -1,148 +0,0 @@
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY dbstyle SYSTEM "@HTMLSTYLE@" CDATA DSSSL>
]>
<style-sheet>
<style-specification use="docbook">
<style-specification-body>
<!-- ;; your stuff goes here... -->
(define %html-prefix%
;; Add the specified prefix to HTML output filenames
"Bv9ARM.")
(define %use-id-as-filename%
;; Use ID attributes as name for component HTML files?
#t)
(define %root-filename%
;; Name for the root HTML document
"Bv9ARM")
(define %section-autolabel%
;; REFENTRY section-autolabel
;; PURP Are sections enumerated?
;; DESC
;; If true, unlabeled sections will be enumerated.
;; /DESC
;; AUTHOR N/A
;; /REFENTRY
#t)
(define %html-ext%
;; REFENTRY html-ext
;; PURP Default extension for HTML output files
;; DESC
;; The default extension for HTML output files.
;; /DESC
;; AUTHOR N/A
;; /REFENTRY
".html")
(define nochunks
;; REFENTRY nochunks
;; PURP Suppress chunking of output pages
;; DESC
;; If true, the entire source document is formatted as a single HTML
;; document and output on stdout.
;; (This option can conveniently be set with '-V nochunks' on the
;; Jade command line).
;; /DESC
;; AUTHOR N/A
;; /REFENTRY
#f)
(define rootchunk
;; REFENTRY rootchunk
;; PURP Make a chunk for the root element when nochunks is used
;; DESC
;; If true, a chunk will be created for the root element, even though
;; nochunks is specified. This option has no effect if nochunks is not
;; true.
;; (This option can conveniently be set with '-V rootchunk' on the
;; Jade command line).
;; /DESC
;; AUTHOR N/A
;; /REFENTRY
#t)
(define html-index
;; REFENTRY html-index
;; PURP HTML indexing?
;; DESC
;; Turns on HTML indexing. If true, then index data will be written
;; to the file defined by 'html-index-filename'. This data can be
;; collated and turned into a DocBook index with bin/collateindex.pl.
;; /DESC
;; AUTHOR N/A
;; /REFENTRY
#t)
(define html-manifest
;; REFENTRY html-manifest
;; PURP Write a manifest?
;; DESC
;; If not '#f' then the list of HTML files created by the stylesheet
;; will be written to the file named by 'html-manifest-filename'.
;; /DESC
;; AUTHOR N/A
;; /REFENTRY
#t)
(define (chunk-element-list)
(list (normalize "preface")
(normalize "chapter")
(normalize "appendix")
(normalize "article")
(normalize "glossary")
(normalize "bibliography")
(normalize "index")
(normalize "colophon")
(normalize "setindex")
(normalize "reference")
(normalize "refentry")
(normalize "part")
(normalize "book") ;; just in case nothing else matches...
(normalize "set") ;; sets are definitely chunks...
))
;
; Add some cell padding to tables so that they don't look so cramped
; in Netscape.
;
; The following definition was cut-and-pasted from dbtable.dsl and the
; single line containing the word CELLPADDING was added.
;
(element tgroup
(let* ((wrapper (parent (current-node)))
(frameattr (attribute-string (normalize "frame") wrapper))
(pgwide (attribute-string (normalize "pgwide") wrapper))
(footnotes (select-elements (descendants (current-node))
(normalize "footnote")))
(border (if (equal? frameattr (normalize "none"))
'(("BORDER" "0"))
'(("BORDER" "1"))))
(width (if (equal? pgwide "1")
(list (list "WIDTH" ($table-width$)))
'()))
(head (select-elements (children (current-node)) (normalize "thead")))
(body (select-elements (children (current-node)) (normalize "tbody")))
(feet (select-elements (children (current-node)) (normalize "tfoot"))))
(make element gi: "TABLE"
attributes: (append
'(("CELLPADDING" "3"))
border
width
(if %cals-table-class%
(list (list "CLASS" %cals-table-class%))
'()))
(process-node-list head)
(process-node-list body)
(process-node-list feet)
(make-table-endnotes))))
</style-specification-body>
</style-specification>
<external-specification id="docbook" document="dbstyle">
</style-sheet>

42
doc/arm/nominum-docbook-print.dsl.in
View File

@@ -1,42 +0,0 @@
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY dbstyle SYSTEM "@PRINTSTYLE@" CDATA DSSSL>
]>
<style-sheet>
<style-specification use="docbook">
<style-specification-body>
<!-- ;; your stuff goes here... -->
(define %generate-book-titlepage% #t)
(define %section-autolabel%
;; REFENTRY section-autolabel
;; PURP Are sections enumerated?
;; DESC
;; If true, unlabeled sections will be enumerated.
;; /DESC
;; AUTHOR N/A
;; /REFENTRY
#t)
;; Margins around cell contents
;; (define %cals-cell-before-row-margin% 20pt)
;; (define %cals-cell-after-row-margin% 20pt)
;; seems to be a bug in JadeTeX -- we get a wierd indent on table
;; cells for the first line only. This is a workaround.
;; Adam Di Carlo, adam@onshore.com
(define %cals-cell-before-column-margin% 5pt)
(define %cals-cell-after-column-margin% 5pt)
;; Inheritable start and end indent for cell contents
(define %cals-cell-content-start-indent% 5pt)
(define %cals-cell-content-end-indent% 5pt)
</style-specification-body>
</style-specification>
<external-specification id="docbook" document="dbstyle">
</style-sheet>

21
doc/arm/validate.sh.in
View File

@@ -1,21 +0,0 @@
#!/bin/sh
#
# Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
# Copyright (C) 2000, 2001 Internet Software Consortium.
#
# Permission to use, copy, modify, and distribute this software for any
# purpose with or without fee is hereby granted, provided that the above
# copyright notice and this permission notice appear in all copies.
#
# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
# AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
# INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
# LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
# PERFORMANCE OF THIS SOFTWARE.
# $Id: validate.sh.in,v 1.3 2004/03/05 05:04:43 marka Exp $
nsgmls -sv @SGMLDIR@/docbook/dsssl/modular/dtds/decls/xml.dcl \
Bv9ARM-book.xml

4
doc/xsl/.cvsignore Normal file
View File

@@ -0,0 +1,4 @@
isc-docbook-chunk.xsl
isc-docbook-html.xsl
isc-docbook-latex.xsl
isc-manpage.xsl

71
doc/xsl/copyright.xsl Normal file
View File

@@ -0,0 +1,71 @@
<!--
- Copyright (C) 2005 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: copyright.xsl,v 1.2 2005/05/11 05:55:37 sra Exp $ -->
<!-- Generate ISC copyright comments from Docbook copyright metadata. -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:template name="isc.copyright.format">
<xsl:param name="text"/>
<xsl:value-of select="$isc.copyright.leader"/>
<xsl:value-of select="normalize-space(substring-before($text, '&#10;'))"/>
<xsl:text>&#10;</xsl:text>
<xsl:variable name="rest" select="substring-after($text, '&#10;')"/>
<xsl:if test="translate($rest, '&#9;&#32;', '')">
<xsl:call-template name="isc.copyright.format">
<xsl:with-param name="text" select="$rest"/>
</xsl:call-template>
</xsl:if>
</xsl:template>
<xsl:variable name="isc.copyright">
<xsl:call-template name="isc.copyright.format">
<xsl:with-param name="text">
<xsl:for-each select="/refentry/docinfo/copyright | /book/bookinfo/copyright">
<xsl:text>Copyright (C) </xsl:text>
<xsl:call-template name="copyright.years">
<xsl:with-param name="years" select="year"/>
</xsl:call-template>
<xsl:text> </xsl:text>
<xsl:value-of select="holder"/>
<xsl:text>&#10;</xsl:text>
</xsl:for-each>
<xsl:text>
Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.
</xsl:text>
</xsl:with-param>
</xsl:call-template>
</xsl:variable>
</xsl:stylesheet>
<!--
- Local variables:
- mode: sgml
- End:
-->

63
doc/xsl/isc-docbook-chunk.xsl.in Normal file
View File

@@ -0,0 +1,63 @@
<!--
- Copyright (C) 2005 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: isc-docbook-chunk.xsl.in,v 1.2 2005/05/11 05:55:38 sra Exp $ -->
<!-- ISC customizations for Docbook-XSL chunked HTML generator -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<!-- Import the Docbook HTML stuff -->
<xsl:import href="@XSLT_DOCBOOK_CHUNK_HTML@"/>
<!-- Readable HTML output, please -->
<xsl:output indent="yes"/>
<xsl:param name="chunker.output.indent" select="'yes'"/>
<!-- Chunk at section level, please -->
<xsl:param name="chunk.section.depth" select="0"/>
<!-- Generate chunk filenames from id attribute values -->
<xsl:param name="use.id.as.filename" select="1"/>
<!-- ANSI C function prototypes, please -->
<xsl:param name="funcsynopsis.style">ansi</xsl:param>
<!-- Use ranges when constructing copyrights -->
<xsl:param name="make.year.ranges" select="1"/>
<!-- Include our copyright generator -->
<xsl:include href="copyright.xsl"/>
<!-- Set comment convention for this output format -->
<xsl:param name="isc.copyright.leader"> - </xsl:param>
<!-- Override Docbook template to insert copyright -->
<xsl:template name="user.preroot">
<xsl:comment>
<xsl:text>&#10;</xsl:text>
<xsl:value-of select="$isc.copyright"/>
</xsl:comment>
<xsl:text>&#10;</xsl:text>
</xsl:template>
</xsl:stylesheet>
<!--
- Local variables:
- mode: sgml
- End:
-->

56
doc/xsl/isc-docbook-html.xsl.in Normal file
View File

@@ -0,0 +1,56 @@
<!--
- Copyright (C) 2005 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: isc-docbook-html.xsl.in,v 1.2 2005/05/11 05:55:38 sra Exp $ -->
<!-- ISC customizations for Docbook-XSL HTML generator -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<!-- Import the Docbook HTML stuff -->
<xsl:import href="@XSLT_DOCBOOK_STYLE_HTML@"/>
<!-- Readable HTML output, please -->
<xsl:output indent="yes"/>
<!-- ANSI C function prototypes, please -->
<xsl:param name="funcsynopsis.style">ansi</xsl:param>
<!-- Use ranges when constructing copyrights -->
<xsl:param name="make.year.ranges" select="1"/>
<!-- Include our copyright generator -->
<xsl:include href="copyright.xsl"/>
<!-- Set comment convention for this output format -->
<xsl:param name="isc.copyright.leader"> - </xsl:param>
<!-- Override Docbook template to insert copyright -->
<xsl:template name="user.preroot">
<xsl:comment>
<xsl:text>&#10;</xsl:text>
<xsl:value-of select="$isc.copyright"/>
</xsl:comment>
<xsl:text>&#10;</xsl:text>
</xsl:template>
</xsl:stylesheet>
<!--
- Local variables:
- mode: sgml
- End:
-->

82
doc/xsl/isc-docbook-latex.xsl.in Normal file
View File

@@ -0,0 +1,82 @@
<!--
- Copyright (C) 2005 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: isc-docbook-latex.xsl.in,v 1.2 2005/05/11 05:55:38 sra Exp $ -->
<!-- ISC customizations for db2latex generator -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<!-- Import the db2latex stuff -->
<xsl:import href="@XSLT_DB2LATEX_STYLE@"/>
<!-- Blank lines between paragraphs, please -->
<xsl:param name="latex.use.parskip" select="1"/>
<!-- Least bad current option for constructing tables -->
<xsl:param name="latex.use.ltxtable" select="1"/>
<xsl:param name="latex.use.longtable" select="1"/>
<!-- LaTeX2e documentclass options. -->
<xsl:param name="latex.documentclass.common" select="''"/>
<!-- This documentation is in English (or maybe Bad English) -->
<xsl:param name="latex.babel.language" select="'english'"/>
<xsl:param name="l10n.gentext.default.language" select="'en'"/>
<!-- Where to find "admonition" graphics -->
<xsl:param name="admon.graphics.path" select="'@XSLT_DB2LATEX_ADMONITIONS@'"/>
<!-- ANSI C function prototypes, please -->
<xsl:param name="funcsynopsis.style">ansi</xsl:param>
<!-- Patch around db2latex (0.8pre1) bug -->
<xsl:template match="copyright/year">
<xsl:apply-templates />
<xsl:if test="position() != last()">
<xsl:text>, </xsl:text>
</xsl:if>
</xsl:template>
<!-- Include our copyright generator -->
<xsl:include href="copyright.xsl"/>
<!-- Set comment convention for this output format -->
<xsl:param name="isc.copyright.leader">% </xsl:param>
<!-- Intercept top level to prepend copyright -->
<xsl:template match="/">
<xsl:value-of select="$isc.copyright"/>
<xsl:apply-imports/>
</xsl:template>
<!--
- Add support for multiple <para/> elements in a table entry.
- db2latex is already typesetting the table entry as a parbox,
- so we just have to insert the paragraph breaks.
-->
<xsl:template match="tbody/row/entry/para[position() != last()]">
<xsl:apply-imports/>
<xsl:text> \par </xsl:text>
</xsl:template>
</xsl:stylesheet>
<!--
- Local variables:
- mode: sgml
- End:
-->

131
doc/xsl/isc-manpage.xsl.in Normal file
View File

@@ -0,0 +1,131 @@
<!--
- Copyright (C) 2005 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: isc-manpage.xsl.in,v 1.2 2005/05/11 05:55:38 sra Exp $ -->
<!-- ISC customizations for Docbook-XSL manual page generator. -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<!-- Import the Docbook manpages stuff -->
<xsl:import href="@XSLT_DOCBOOK_STYLE_MAN@"/>
<!-- Include our copyright generator -->
<xsl:include href="copyright.xsl"/>
<!-- Set comment string for this output format -->
<xsl:param name="isc.copyright.leader">.\" </xsl:param>
<!-- We're not writing any kind of SGML, thanks -->
<xsl:output method="text" encoding="us-ascii"/>
<!-- ANSI C function prototypes, please -->
<xsl:param name="funcsynopsis.style">ansi</xsl:param>
<!-- Use ranges when constructing copyrights -->
<xsl:param name="make.year.ranges" select="1"/>
<!-- Stuff we want in our nroff preamble. -->
<xsl:variable name="isc.nroff.preamble">
<xsl:text>.hy 0&#10;</xsl:text>
<xsl:text>.ad l&#10;</xsl:text>
</xsl:variable>
<!--
- Override Docbook template to insert our copyright,
- disable chunking, and suppress output of .so files.
-->
<xsl:template name="write.text.chunk">
<xsl:if test="substring($content, 1, 4) != '.so ' or
substring-after($content, '&#10;') != ''">
<xsl:call-template name="isc.no.blanks">
<xsl:with-param name="text" select="
concat($isc.copyright,
$isc.copyright.leader, '&#10;',
$isc.nroff.preamble,
$content)"/>
</xsl:call-template>
</xsl:if>
</xsl:template>
<!--
- Suppress blank lines in nroff source we output.
-->
<xsl:template name="isc.no.blanks">
<xsl:param name="text"/>
<xsl:choose>
<xsl:when test="contains($text, '&#10;')">
<xsl:call-template name="isc.no.blanks">
<xsl:with-param name="text"
select="substring-before($text, '&#10;')"/>
</xsl:call-template>
<xsl:call-template name="isc.no.blanks">
<xsl:with-param name="text"
select="substring-after($text, '&#10;')"/>
</xsl:call-template>
</xsl:when>
<xsl:when test="translate($text, '&#9;&#32;', '')">
<xsl:value-of select="$text"/>
<xsl:text>&#10;</xsl:text>
</xsl:when>
</xsl:choose>
</xsl:template>
<!--
- Override Docbook template to change formatting.
- We just want the element name in boldface, no subsection header.
-->
<xsl:template match="caution|important|note|tip|warning">
<xsl:text>&#10;.RS&#10;.B "</xsl:text>
<!-- capitalize word -->
<xsl:value-of
select="translate (substring (name(.), 1, 1), 'cintw', 'CINTW')" />
<xsl:value-of select="substring (name(), 2)" />
<xsl:if test="title">
<xsl:text>: </xsl:text>
<xsl:value-of select="title[1]"/>
</xsl:if>
<xsl:text>:"&#10;</xsl:text>
<xsl:apply-templates/>
<xsl:text>&#10;.RE&#10;</xsl:text>
</xsl:template>
<!--
- Override template to change formatting.
- We don't want hyphenation or justification.
-->
<xsl:template match="cmdsynopsis">
<xsl:text>.HP </xsl:text>
<xsl:value-of select="string-length (normalize-space (command)) + 1"/>
<xsl:text>&#10;</xsl:text>
<xsl:apply-templates/>
</xsl:template>
<!--
- Override template to change formatting.
- We don't want hyphenation or justification.
-->
<xsl:template match="funcsynopsis">
<xsl:apply-templates/>
</xsl:template>
</xsl:stylesheet>
<!--
- Local variables:
- mode: sgml
- End:
-->

55
doc/xsl/pre-latex.xsl Normal file
View File

@@ -0,0 +1,55 @@
<!--
- Copyright (C) 2005 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: pre-latex.xsl,v 1.2 2005/05/11 05:55:38 sra Exp $ -->
<!--
- Whack &mdash; into something that won't choke LaTeX.
- There's probably a better way to do this, but this will work for now.
-->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:variable name="mdash" select="'&#8212;'"/>
<xsl:template name="fix-mdash" match="text()[contains(., $mdash)]">
<xsl:param name="s" select="."/>
<xsl:choose>
<xsl:when test="contains($s, $mdash)">
<xsl:value-of select="substring-before($s, $mdash)"/>
<xsl:text>---</xsl:text>
<xsl:call-template name="fix-mdash">
<xsl:with-param name="s" select="substring-after($s, $mdash)"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$s"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template match="@*|node()">
<xsl:copy>
<xsl:copy-of select="@*"/>
<xsl:apply-templates/>
</xsl:copy>
</xsl:template>
<xsl:template match="/">
<xsl:apply-templates/>
</xsl:template>
</xsl:stylesheet>

40
docutil/docbook2man-wrapper.sh.in
View File

@@ -1,40 +0,0 @@
#!/bin/sh
#
# Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
# Copyright (C) 2001, 2002 Internet Software Consortium.
#
# Permission to use, copy, modify, and distribute this software for any
# purpose with or without fee is hereby granted, provided that the above
# copyright notice and this permission notice appear in all copies.
#
# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
# AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
# INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
# LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
# PERFORMANCE OF THIS SOFTWARE.
# $Id: docbook2man-wrapper.sh.in,v 1.5 2004/03/05 05:04:58 marka Exp $
case $# in
3) ;;
*) echo "$0: wrong number of arguments" >&2; exit 1 ;;
esac
top_srcdir=$1
source=$2
target=$3
ONSGMLS=onsgmls
SGMLSPL=sgmlspl
SGMLCATALOG=@SGMLCATALOG@
DOCBOOK2MANSPEC=@DOCBOOK2MANSPEC@
${ONSGMLS} -c ${SGMLCATALOG} $source | ${SGMLSPL} ${DOCBOOK2MANSPEC}
rm -f $target.tmp
grep -v 'auto-generated by docbook2man' $target > $target.tmp
rm -f $target
cat ${top_srcdir}/docutil/MAN_COPYRIGHT > $target
cat $target.tmp >> $target
rm -f manpage.* $target.tmp

442
lib/lwres/man/lwres.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,230 +17,248 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres.docbook,v 1.5 2005/04/07 03:50:00 marka Exp $ -->
<!-- $Id: lwres.docbook,v 1.6 2005/05/11 05:55:39 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres</refname>
<refpurpose>introduction to the lightweight resolver library</refpurpose>
</refnamediv>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refsynopsisdiv>
<funcsynopsis>
<refmeta>
<refentrytitle>lwres</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres</refname>
<refpurpose>introduction to the lightweight resolver library</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
</funcsynopsis>
</refsynopsisdiv>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
The BIND 9 lightweight resolver library is a simple, name service
independent stub resolver library. It provides hostname-to-address
and address-to-hostname lookup services to applications by
transmitting lookup requests to a resolver daemon
<command>lwresd</command>
running on the local host. The resover daemon performs the
lookup using the DNS or possibly other name service protocols,
and returns the results to the application through the library.
The library and resolver daemon communicate using a simple
UDP-based protocol.
</para>
</refsect1>
<refsect1>
<title>DESCRIPTION</title>
<para>
The BIND 9 lightweight resolver library is a simple, name service
independent stub resolver library. It provides hostname-to-address
and address-to-hostname lookup services to applications by
transmitting lookup requests to a resolver daemon
<command>lwresd</command>
running on the local host. The resover daemon performs the
lookup using the DNS or possibly other name service protocols,
and returns the results to the application through the library.
The library and resolver daemon communicate using a simple
UDP-based protocol.
</para>
</refsect1>
<refsect1>
<title>OVERVIEW</title>
<para>
The lwresd library implements multiple name service APIs.
The standard
<function>gethostbyname()</function>,
<function>gethostbyaddr()</function>,
<function>gethostbyname_r()</function>,
<function>gethostbyaddr_r()</function>,
<function>getaddrinfo()</function>,
<function>getipnodebyname()</function>,
and
<function>getipnodebyaddr()</function>
functions are all supported. To allow the lwres library to coexist
with system libraries that define functions of the same name,
the library defines these functions with names prefixed by
<literal>lwres_</literal>.
To define the standard names, applications must include the
header file
<filename>&lt;lwres/netdb.h&gt;</filename>
which contains macro definitions mapping the standard function names
into
<literal>lwres_</literal>
prefixed ones. Operating system vendors who integrate the lwres
library into their base distributions should rename the functions
in the library proper so that the renaming macros are not needed.
</para>
<para>
The library also provides a native API consisting of the functions
<function>lwres_getaddrsbyname()</function>
and
<function>lwres_getnamebyaddr()</function>.
These may be called by applications that require more detailed
control over the lookup process than the standard functions
provide.
</para>
<para>
In addition to these name service independent address lookup
functions, the library implements a new, experimental API
for looking up arbitrary DNS resource records, using the
<function>lwres_getaddrsbyname()</function>
function.
</para>
<para>
Finally, there is a low-level API for converting lookup
requests and responses to and from raw lwres protocol packets.
This API can be used by clients requiring nonblocking operation,
and is also used when implementing the server side of the lwres
protocol, for example in the
<command>lwresd</command>
resolver daemon. The use of this low-level API in clients
and servers is outlined in the following sections.
</para>
</refsect1>
<refsect1>
<title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title>
<para>
When a client program wishes to make an lwres request using the
native low-level API, it typically performs the following
sequence of actions.
</para>
<para>
(1) Allocate or use an existing <type>lwres_packet_t</type>,
called <varname>pkt</varname> below.
</para>
<para>
(2) Set <structfield>pkt.recvlength</structfield> to the maximum length we will accept.
This is done so the receiver of our packets knows how large our receive
buffer is. The "default" is a constant in
<filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>.
</para>
<para>
(3) Set <structfield>pkt.serial</structfield>
to a unique serial number. This value is echoed
back to the application by the remote server.
</para>
<para>
(4) Set <structfield>pkt.pktflags</structfield>. Usually this is set to 0.
</para>
<para>
(5) Set <structfield>pkt.result</structfield> to 0.
</para>
<para>
(6) Call <function>lwres_*request_render()</function>,
or marshall in the data using the primitives
such as <function>lwres_packet_render()</function>
and storing the packet data.
</para>
<para>
(7) Transmit the resulting buffer.
</para>
<para>
(8) Call <function>lwres_*response_parse()</function>
to parse any packets received.
</para>
<para>
(9) Verify that the opcode and serial match a request, and process the
packet specific information contained in the body.
</para>
</refsect1>
<refsect1>
<title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title>
<para>
When implementing the server side of the lightweight resolver
protocol using the lwres library, a sequence of actions like the
following is typically involved in processing each request packet.
</para>
<para>
Note that the same <type>lwres_packet_t</type> is used
in both the <function>_parse()</function> and <function>_render()</function> calls,
with only a few modifications made
to the packet header's contents between uses. This method is recommended
as it keeps the serial, opcode, and other fields correct.
</para>
<para>
(1) When a packet is received, call <function>lwres_*request_parse()</function> to
unmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below)
as well as a data specific type, such as <type>lwres_gabnrequest_t</type>.
</para>
<para>
(2) Process the request in the data specific type.
</para>
<para>
(3) Set the <structfield>pkt.result</structfield>,
<structfield>pkt.recvlength</structfield> as above. All other fields can
be left untouched since they were filled in by the <function>*_parse()</function> call
above. If using <function>lwres_*response_render()</function>,
<structfield>pkt.pktflags</structfield> will be set up
properly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be
set.
</para>
<para>
(4) Call the data specific rendering function, such as
<function>lwres_gabnresponse_render()</function>.
</para>
<para>
(5) Send the resulting packet to the client.
</para>
<para>
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<refsect1>
<title>OVERVIEW</title>
<para>
The lwresd library implements multiple name service APIs.
The standard
<function>gethostbyname()</function>,
<function>gethostbyaddr()</function>,
<function>gethostbyname_r()</function>,
<function>gethostbyaddr_r()</function>,
<function>getaddrinfo()</function>,
<function>getipnodebyname()</function>,
and
<function>getipnodebyaddr()</function>
functions are all supported. To allow the lwres library to coexist
with system libraries that define functions of the same name,
the library defines these functions with names prefixed by
<literal>lwres_</literal>.
To define the standard names, applications must include the
header file
<filename>&lt;lwres/netdb.h&gt;</filename>
which contains macro definitions mapping the standard function names
into
<literal>lwres_</literal>
prefixed ones. Operating system vendors who integrate the lwres
library into their base distributions should rename the functions
in the library proper so that the renaming macros are not needed.
</para>
<para>
The library also provides a native API consisting of the functions
<function>lwres_getaddrsbyname()</function>
and
<function>lwres_getnamebyaddr()</function>.
These may be called by applications that require more detailed
control over the lookup process than the standard functions
provide.
</para>
<para>
In addition to these name service independent address lookup
functions, the library implements a new, experimental API
for looking up arbitrary DNS resource records, using the
<function>lwres_getaddrsbyname()</function>
function.
</para>
<para>
Finally, there is a low-level API for converting lookup
requests and responses to and from raw lwres protocol packets.
This API can be used by clients requiring nonblocking operation,
and is also used when implementing the server side of the lwres
protocol, for example in the
<command>lwresd</command>
resolver daemon. The use of this low-level API in clients
and servers is outlined in the following sections.
</para>
</refsect1>
<refsect1>
<title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title>
<para>
When a client program wishes to make an lwres request using the
native low-level API, it typically performs the following
sequence of actions.
</para>
<para>
(1) Allocate or use an existing <type>lwres_packet_t</type>,
called <varname>pkt</varname> below.
</para>
<para>
(2) Set <structfield>pkt.recvlength</structfield> to the maximum length
we will accept.
This is done so the receiver of our packets knows how large our receive
buffer is. The "default" is a constant in
<filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>.
</para>
<para>
(3) Set <structfield>pkt.serial</structfield>
to a unique serial number. This value is echoed
back to the application by the remote server.
</para>
<para>
(4) Set <structfield>pkt.pktflags</structfield>. Usually this is set to
0.
</para>
<para>
(5) Set <structfield>pkt.result</structfield> to 0.
</para>
<para>
(6) Call <function>lwres_*request_render()</function>,
or marshall in the data using the primitives
such as <function>lwres_packet_render()</function>
and storing the packet data.
</para>
<para>
(7) Transmit the resulting buffer.
</para>
<para>
(8) Call <function>lwres_*response_parse()</function>
to parse any packets received.
</para>
<para>
(9) Verify that the opcode and serial match a request, and process the
packet specific information contained in the body.
</para>
</refsect1>
<refsect1>
<title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title>
<para>
When implementing the server side of the lightweight resolver
protocol using the lwres library, a sequence of actions like the
following is typically involved in processing each request packet.
</para>
<para>
Note that the same <type>lwres_packet_t</type> is used
in both the <function>_parse()</function> and <function>_render()</function> calls,
with only a few modifications made
to the packet header's contents between uses. This method is
recommended
as it keeps the serial, opcode, and other fields correct.
</para>
<para>
(1) When a packet is received, call <function>lwres_*request_parse()</function> to
unmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below)
as well as a data specific type, such as <type>lwres_gabnrequest_t</type>.
</para>
<para>
(2) Process the request in the data specific type.
</para>
<para>
(3) Set the <structfield>pkt.result</structfield>,
<structfield>pkt.recvlength</structfield> as above. All other fields
can
be left untouched since they were filled in by the <function>*_parse()</function> call
above. If using <function>lwres_*response_render()</function>,
<structfield>pkt.pktflags</structfield> will be set up
properly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be
set.
</para>
<para>
(4) Call the data specific rendering function, such as
<function>lwres_gabnresponse_render()</function>.
</para>
<para>
(5) Send the resulting packet to the client.
</para>
<para></para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>.
<citerefentry>
<refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry>
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

552
lib/lwres/man/lwres_buffer.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,364 +17,376 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_buffer.docbook,v 1.5 2005/04/07 03:50:00 marka Exp $ -->
<!-- $Id: lwres_buffer.docbook,v 1.6 2005/05/11 05:55:39 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_buffer</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres_buffer</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_buffer_init</refname>
<refname>lwres_buffer_invalidate</refname>
<refname>lwres_buffer_add</refname>
<refname>lwres_buffer_subtract</refname>
<refname>lwres_buffer_clear</refname>
<refname>lwres_buffer_first</refname>
<refname>lwres_buffer_forward</refname>
<refname>lwres_buffer_back</refname>
<refname>lwres_buffer_getuint8</refname>
<refname>lwres_buffer_putuint8</refname>
<refname>lwres_buffer_getuint16</refname>
<refname>lwres_buffer_putuint16</refname>
<refname>lwres_buffer_getuint32</refname>
<refname>lwres_buffer_putuint32</refname>
<refname>lwres_buffer_putmem</refname>
<refname>lwres_buffer_getmem</refname>
<refpurpose>lightweight resolver buffer management</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<refnamediv>
<refname>lwres_buffer_init</refname>
<refname>lwres_buffer_invalidate</refname>
<refname>lwres_buffer_add</refname>
<refname>lwres_buffer_subtract</refname>
<refname>lwres_buffer_clear</refname>
<refname>lwres_buffer_first</refname>
<refname>lwres_buffer_forward</refname>
<refname>lwres_buffer_back</refname>
<refname>lwres_buffer_getuint8</refname>
<refname>lwres_buffer_putuint8</refname>
<refname>lwres_buffer_getuint16</refname>
<refname>lwres_buffer_putuint16</refname>
<refname>lwres_buffer_getuint32</refname>
<refname>lwres_buffer_putuint32</refname>
<refname>lwres_buffer_putmem</refname>
<refname>lwres_buffer_getmem</refname>
<refpurpose>lightweight resolver buffer management</refpurpose>
</refnamediv>
<funcsynopsis>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;lwres/lwbuffer.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_buffer_init</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>void *base</paramdef>
<paramdef>unsigned int length</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>void *<parameter>base</parameter></paramdef>
<paramdef>unsigned int <parameter>length</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_buffer_invalidate</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_buffer_add</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>unsigned int n</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>unsigned int <parameter>n</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_buffer_subtract</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>unsigned int n</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>unsigned int <parameter>n</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_buffer_clear</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_buffer_first</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_buffer_forward</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>unsigned int n</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>unsigned int <parameter>n</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_buffer_back</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>unsigned int n</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>unsigned int <parameter>n</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_uint8_t
<function>lwres_buffer_getuint8</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_buffer_putuint8</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>lwres_uint8_t val</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_uint8_t <parameter>val</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_uint16_t
<function>lwres_buffer_getuint16</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_buffer_putuint16</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>lwres_uint16_t val</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_uint16_t <parameter>val</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_uint32_t
<function>lwres_buffer_getuint32</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_buffer_putuint32</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>lwres_uint32_t val</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_uint32_t <parameter>val</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_buffer_putmem</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>const unsigned char *base</paramdef>
<paramdef>unsigned int length</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>const unsigned char *<parameter>base</parameter></paramdef>
<paramdef>unsigned int <parameter>length</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_buffer_getmem</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>unsigned char *base</paramdef>
<paramdef>unsigned int length</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>unsigned char *<parameter>base</parameter></paramdef>
<paramdef>unsigned int <parameter>length</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
</refsynopsisdiv>
<refsect1>
<refsect1>
<title>DESCRIPTION</title>
<para>
These functions provide bounds checked access to a region of memory
where data is being read or written.
They are based on, and similar to, the
<literal>isc_buffer_</literal>
functions in the ISC library.
</para>
<para>
A buffer is a region of memory, together with a set of related
subregions.
The <emphasis>used region</emphasis> and the
<emphasis>available</emphasis> region are disjoint, and
their union is the buffer's region.
The used region extends from the beginning of the buffer region to the
last used byte.
The available region extends from one byte greater than the last used
byte to the end of the buffer's region.
The size of the used region can be changed using various
buffer commands.
Initially, the used region is empty.
</para>
<para>
The used region is further subdivided into two disjoint regions: the
<emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
The union of these two regions is the used region.
The consumed region extends from the beginning of the used region to
the byte before the <emphasis>current</emphasis> offset (if any).
The <emphasis>remaining</emphasis> region the current pointer to the end of the used
region.
The size of the consumed region can be changed using various
buffer commands.
Initially, the consumed region is empty.
</para>
<para>
The <emphasis>active region</emphasis> is an (optional) subregion of the remaining
region.
It extends from the current offset to an offset in the
remaining region.
Initially, the active region is empty.
If the current offset advances beyond the chosen offset,
the active region will also be empty.
</para>
<para>
<programlisting>
<title>DESCRIPTION</title>
<para>
These functions provide bounds checked access to a region of memory
where data is being read or written.
They are based on, and similar to, the
<literal>isc_buffer_</literal>
functions in the ISC library.
</para>
<para>
A buffer is a region of memory, together with a set of related
subregions.
The <emphasis>used region</emphasis> and the
<emphasis>available</emphasis> region are disjoint, and
their union is the buffer's region.
The used region extends from the beginning of the buffer region to the
last used byte.
The available region extends from one byte greater than the last used
byte to the end of the buffer's region.
The size of the used region can be changed using various
buffer commands.
Initially, the used region is empty.
</para>
<para>
The used region is further subdivided into two disjoint regions: the
<emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
The union of these two regions is the used region.
The consumed region extends from the beginning of the used region to
the byte before the <emphasis>current</emphasis> offset (if any).
The <emphasis>remaining</emphasis> region the current pointer to the end
of the used
region.
The size of the consumed region can be changed using various
buffer commands.
Initially, the consumed region is empty.
</para>
<para>
The <emphasis>active region</emphasis> is an (optional) subregion of the
remaining
region.
It extends from the current offset to an offset in the
remaining region.
Initially, the active region is empty.
If the current offset advances beyond the chosen offset,
the active region will also be empty.
</para>
<para><programlisting>
/------------entire length---------------\\
/----- used region -----\\/-- available --\\
+----------------------------------------+
| consumed | remaining | |
+----------------------------------------+
a b c d e
</programlisting>
</para>
<para><programlisting>
a == base of buffer.
b == current pointer. Can be anywhere between a and d.
c == active pointer. Meaningful between b and d.
d == used pointer.
e == length of buffer.
</programlisting>
</para>
<para><programlisting>
a-e == entire length of buffer.
a-d == used region.
a-b == consumed region.
b-d == remaining region.
b-c == optional active region.
</programlisting>
</para>
<para>
<function>lwres_buffer_init()</function>
initializes the
<type>lwres_buffer_t</type>
<parameter>*b</parameter>
and assocates it with the memory region of size
<parameter>length</parameter>
bytes starting at location
<parameter>base.</parameter>
</para>
<para>
<function>lwres_buffer_invalidate()</function>
marks the buffer
<parameter>*b</parameter>
as invalid. Invalidating a buffer after use is not required,
but makes it possible to catch its possible accidental use.
</para>
<para>
The functions
<function>lwres_buffer_add()</function>
and
<function>lwres_buffer_subtract()</function>
respectively increase and decrease the used space in
buffer
<parameter>*b</parameter>
by
<parameter>n</parameter>
bytes.
<function>lwres_buffer_add()</function>
checks for buffer overflow and
<function>lwres_buffer_subtract()</function>
checks for underflow.
These functions do not allocate or deallocate memory.
They just change the value of
<structfield>used</structfield>.
</para>
<para>
A buffer is re-initialised by
<function>lwres_buffer_clear()</function>.
The function sets
<structfield>used</structfield> ,
<structfield>current</structfield>
and
<structfield>active</structfield>
to zero.
</para>
<para>
<function>lwres_buffer_first</function>
makes the consumed region of buffer
<parameter>*p</parameter>
empty by setting
<structfield>current</structfield>
to zero (the start of the buffer).
</para>
<para>
<function>lwres_buffer_forward()</function>
increases the consumed region of buffer
<parameter>*b</parameter>
by
<parameter>n</parameter>
bytes, checking for overflow.
Similarly,
<function>lwres_buffer_back()</function>
decreases buffer
<parameter>b</parameter>'s
consumed region by
<parameter>n</parameter>
bytes and checks for underflow.
</para>
<para>
<function>lwres_buffer_getuint8()</function>
reads an unsigned 8-bit integer from
<parameter>*b</parameter>
and returns it.
<function>lwres_buffer_putuint8()</function>
writes the unsigned 8-bit integer
<parameter>val</parameter>
to buffer
<parameter>*b</parameter>.
</para>
<para>
<function>lwres_buffer_getuint16()</function>
and
<function>lwres_buffer_getuint32()</function>
are identical to
<function>lwres_buffer_putuint8()</function>
except that they respectively read an unsigned 16-bit or 32-bit integer
in network byte order from
<parameter>b</parameter>.
Similarly,
<function>lwres_buffer_putuint16()</function>
and
<function>lwres_buffer_putuint32()</function>
writes the unsigned 16-bit or 32-bit integer
<parameter>val</parameter>
to buffer
<parameter>b</parameter>,
in network byte order.
</para>
<para>
Arbitrary amounts of data are read or written from a lightweight
resolver buffer with
<function>lwres_buffer_getmem()</function>
and
<function>lwres_buffer_putmem()</function>
respectively.
<function>lwres_buffer_putmem()</function>
copies
<parameter>length</parameter>
bytes of memory at
<parameter>base</parameter>
to
<parameter>b</parameter>.
Conversely,
<function>lwres_buffer_getmem()</function>
copies
<parameter>length</parameter>
bytes of memory from
<parameter>b</parameter>
to
<parameter>base</parameter>.
</para>
</refsect1>
</refentry>
</para>
<para><function>lwres_buffer_init()</function>
initializes the
<type>lwres_buffer_t</type>
<parameter>*b</parameter>
and assocates it with the memory region of size
<parameter>length</parameter>
bytes starting at location
<parameter>base.</parameter>
</para>
<para><function>lwres_buffer_invalidate()</function>
marks the buffer <parameter>*b</parameter>
as invalid. Invalidating a buffer after use is not required,
but makes it possible to catch its possible accidental use.
</para>
<para>
The functions
<function>lwres_buffer_add()</function>
and
<function>lwres_buffer_subtract()</function>
respectively increase and decrease the used space in
buffer
<parameter>*b</parameter>
by
<parameter>n</parameter>
bytes.
<function>lwres_buffer_add()</function>
checks for buffer overflow and
<function>lwres_buffer_subtract()</function>
checks for underflow.
These functions do not allocate or deallocate memory.
They just change the value of
<structfield>used</structfield>.
</para>
<para>
A buffer is re-initialised by
<function>lwres_buffer_clear()</function>.
The function sets
<structfield>used</structfield>,
<structfield>current</structfield>
and
<structfield>active</structfield>
to zero.
</para>
<para><function>lwres_buffer_first</function>
makes the consumed region of buffer
<parameter>*p</parameter>
empty by setting
<structfield>current</structfield>
to zero (the start of the buffer).
</para>
<para><function>lwres_buffer_forward()</function>
increases the consumed region of buffer
<parameter>*b</parameter>
by
<parameter>n</parameter>
bytes, checking for overflow.
Similarly,
<function>lwres_buffer_back()</function>
decreases buffer
<parameter>b</parameter>'s
consumed region by
<parameter>n</parameter>
bytes and checks for underflow.
</para>
<para><function>lwres_buffer_getuint8()</function>
reads an unsigned 8-bit integer from
<parameter>*b</parameter>
and returns it.
<function>lwres_buffer_putuint8()</function>
writes the unsigned 8-bit integer
<parameter>val</parameter>
to buffer
<parameter>*b</parameter>.
</para>
<para><function>lwres_buffer_getuint16()</function>
and
<function>lwres_buffer_getuint32()</function>
are identical to
<function>lwres_buffer_putuint8()</function>
except that they respectively read an unsigned 16-bit or 32-bit integer
in network byte order from
<parameter>b</parameter>.
Similarly,
<function>lwres_buffer_putuint16()</function>
and
<function>lwres_buffer_putuint32()</function>
writes the unsigned 16-bit or 32-bit integer
<parameter>val</parameter>
to buffer
<parameter>b</parameter>,
in network byte order.
</para>
<para>
Arbitrary amounts of data are read or written from a lightweight
resolver buffer with
<function>lwres_buffer_getmem()</function>
and
<function>lwres_buffer_putmem()</function>
respectively.
<function>lwres_buffer_putmem()</function>
copies
<parameter>length</parameter>
bytes of memory at
<parameter>base</parameter>
to
<parameter>b</parameter>.
Conversely,
<function>lwres_buffer_getmem()</function>
copies
<parameter>length</parameter>
bytes of memory from
<parameter>b</parameter>
to
<parameter>base</parameter>.
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

250
lib/lwres/man/lwres_config.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,145 +17,155 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_config.docbook,v 1.4 2005/04/07 03:50:01 marka Exp $ -->
<!-- $Id: lwres_config.docbook,v 1.5 2005/05/11 05:55:39 sra Exp $ -->
<refentry>
<refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_config</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres_config</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_conf_init</refname>
<refname>lwres_conf_clear</refname>
<refname>lwres_conf_parse</refname>
<refname>lwres_conf_print</refname>
<refname>lwres_conf_get</refname>
<refpurpose>lightweight resolver configuration</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<funcsynopsis>
<refnamediv>
<refname>lwres_conf_init</refname>
<refname>lwres_conf_clear</refname>
<refname>lwres_conf_parse</refname>
<refname>lwres_conf_print</refname>
<refname>lwres_conf_get</refname>
<refpurpose>lightweight resolver configuration</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_conf_init</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_conf_clear</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_conf_parse</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>const char *filename</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>const char *<parameter>filename</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_conf_print</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>FILE *fp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>FILE *<parameter>fp</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_conf_t *
<function>lwres_conf_get</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
<function>lwres_conf_init()</function>
creates an empty
<type>lwres_conf_t</type>
structure for lightweight resolver context
<parameter>ctx</parameter>.
</para>
<para>
<function>lwres_conf_clear()</function>
frees up all the internal memory used by
that
<type>lwres_conf_t</type>
structure in resolver context
<parameter>ctx</parameter>.
</para>
<para>
<function>lwres_conf_parse()</function>
opens the file
<parameter>filename</parameter>
and parses it to initialise the resolver context
<parameter>ctx</parameter>'s
<type>lwres_conf_t</type>
structure.
</para>
<para>
<function>lwres_conf_print()</function>
prints the
<type>lwres_conf_t</type>
structure for resolver context
<parameter>ctx</parameter>
to the
<type>FILE</type>
<parameter>fp</parameter>.
</para>
</refsect1>
<refsect1>
<refsect1>
<title>DESCRIPTION</title>
<title>RETURN VALUES</title>
<para>
<function>lwres_conf_parse()</function>
returns
<errorcode>LWRES_R_SUCCESS</errorcode>
if it successfully read and parsed
<parameter>filename</parameter>.
It returns
<errorcode>LWRES_R_FAILURE</errorcode>
if
<parameter>filename</parameter>
could not be opened or contained incorrect
resolver statements.
</para>
<para>
<function>lwres_conf_print()</function>
returns
<errorcode>LWRES_R_SUCCESS</errorcode>
unless an error occurred when converting the network addresses to a
numeric host address string.
If this happens, the function returns
<errorcode>LWRES_R_FAILURE</errorcode>.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>stdio</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
</citerefentry>.
</refsect1>
<refsect1>
<title>FILES</title>
<para>
<filename>/etc/resolv.conf</filename>
</para>
</refsect1>
</refentry>
<para><function>lwres_conf_init()</function>
creates an empty
<type>lwres_conf_t</type>
structure for lightweight resolver context
<parameter>ctx</parameter>.
</para>
<para><function>lwres_conf_clear()</function>
frees up all the internal memory used by
that
<type>lwres_conf_t</type>
structure in resolver context
<parameter>ctx</parameter>.
</para>
<para><function>lwres_conf_parse()</function>
opens the file
<parameter>filename</parameter>
and parses it to initialise the resolver context
<parameter>ctx</parameter>'s
<type>lwres_conf_t</type>
structure.
</para>
<para><function>lwres_conf_print()</function>
prints the
<type>lwres_conf_t</type>
structure for resolver context
<parameter>ctx</parameter>
to the
<type>FILE</type>
<parameter>fp</parameter>.
</para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para><function>lwres_conf_parse()</function>
returns <errorcode>LWRES_R_SUCCESS</errorcode>
if it successfully read and parsed
<parameter>filename</parameter>.
It returns <errorcode>LWRES_R_FAILURE</errorcode>
if <parameter>filename</parameter>
could not be opened or contained incorrect
resolver statements.
</para>
<para><function>lwres_conf_print()</function>
returns <errorcode>LWRES_R_SUCCESS</errorcode>
unless an error occurred when converting the network addresses to a
numeric host address string.
If this happens, the function returns
<errorcode>LWRES_R_FAILURE</errorcode>.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>stdio</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
</citerefentry>.
</para>
</refsect1>
<refsect1>
<title>FILES</title>
<para><filename>/etc/resolv.conf</filename>
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

437
lib/lwres/man/lwres_context.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
@@ -15,269 +17,244 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_context.docbook,v 1.6 2005/04/07 03:50:01 marka Exp $ -->
<!-- $Id: lwres_context.docbook,v 1.7 2005/05/11 05:55:39 sra Exp $ -->
<refentry>
<refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_context</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_context_create</refname>
<refname>lwres_context_destroy</refname>
<refname>lwres_context_nextserial</refname>
<refname>lwres_context_initserial</refname>
<refname>lwres_context_freemem</refname>
<refname>lwres_context_allocmem</refname>
<refname>lwres_context_sendrecv</refname>
<refpurpose>lightweight resolver context management</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<refmeta>
<refentrytitle>lwres_context</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<year>2003</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname>lwres_context_create</refname>
<refname>lwres_context_destroy</refname>
<refname>lwres_context_nextserial</refname>
<refname>lwres_context_initserial</refname>
<refname>lwres_context_freemem</refname>
<refname>lwres_context_allocmem</refname>
<refname>lwres_context_sendrecv</refname>
<refpurpose>lightweight resolver context management</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_context_create</function></funcdef>
<paramdef>lwres_context_t **contextp</paramdef>
<paramdef>void *arg</paramdef>
<paramdef>lwres_malloc_t malloc_function</paramdef>
<paramdef>lwres_free_t free_function</paramdef>
</funcprototype>
<paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
<paramdef>void *<parameter>arg</parameter></paramdef>
<paramdef>lwres_malloc_t <parameter>malloc_function</parameter></paramdef>
<paramdef>lwres_free_t <parameter>free_function</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_context_destroy</function></funcdef>
<paramdef>lwres_context_t **contextp</paramdef>
</funcprototype>
<paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_context_initserial</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_uint32_t serial</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_uint32_t <parameter>serial</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_uint32_t
<function>lwres_context_nextserial</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_context_freemem</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>void *mem</paramdef>
<paramdef>size_t len</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>void *<parameter>mem</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_context_allocmem</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>size_t len</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void *
<function>lwres_context_sendrecv</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>void *sendbase</paramdef>
<paramdef>int sendlen</paramdef>
<paramdef>void *recvbase</paramdef>
<paramdef>int recvlen</paramdef>
<paramdef>int *recvd_len</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>void *<parameter>sendbase</parameter></paramdef>
<paramdef>int <parameter>sendlen</parameter></paramdef>
<paramdef>void *<parameter>recvbase</parameter></paramdef>
<paramdef>int <parameter>recvlen</parameter></paramdef>
<paramdef>int *<parameter>recvd_len</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
<function>lwres_context_create()</function>
creates a
<type>lwres_context_t</type>
structure for use in lightweight resolver operations.
It holds a socket and other data needed for communicating
with a resolver daemon.
The new
<type>lwres_context_t</type>
is returned through
<parameter>contextp</parameter>,
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
a pointer to a
<type>lwres_context_t</type>
pointer. This
<type>lwres_context_t</type>
pointer must initially be NULL, and is modified
to point to the newly created
<type>lwres_context_t</type>.
<para><function>lwres_context_create()</function>
creates a <type>lwres_context_t</type> structure for use in
lightweight resolver operations. It holds a socket and other
data needed for communicating with a resolver daemon. The new
<type>lwres_context_t</type> is returned through
<parameter>contextp</parameter>, a pointer to a
<type>lwres_context_t</type> pointer. This
<type>lwres_context_t</type> pointer must initially be NULL, and
is modified to point to the newly created
<type>lwres_context_t</type>.
</para>
<para>
When the lightweight resolver needs to perform dynamic memory
allocation, it will call
<parameter>malloc_function</parameter>
to allocate memory and
<parameter>free_function</parameter>
to free it. If
<parameter>malloc_function</parameter>
and
<parameter>free_function</parameter>
are NULL, memory is allocated using
<citerefentry>
<refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
and
<citerefentry>
<refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
<para>
When the lightweight resolver needs to perform dynamic memory
allocation, it will call
<parameter>malloc_function</parameter>
to allocate memory and
<parameter>free_function</parameter>
It is not permitted to have a NULL
<parameter>malloc_function</parameter> and a non-NULL
<parameter>free_function</parameter> or vice versa.
<parameter>arg</parameter> is passed as the first parameter to
the memory allocation functions. If
<parameter>malloc_function</parameter> and
<parameter>free_function</parameter> are NULL,
<parameter>arg</parameter> is unused and should be passed as
NULL.
</para>
to free it. If
<parameter>malloc_function</parameter>
and
<parameter>free_function</parameter>
<para>
Once memory for the structure has been allocated,
it is initialized using
<citerefentry>
<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
and returned via <parameter>*contextp</parameter>.
</para>
are NULL, memory is allocated using
.Xr malloc 3
and
<citerefentry>
<refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
<para><function>lwres_context_destroy()</function>
destroys a <type>lwres_context_t</type>, closing its socket.
<parameter>contextp</parameter> is a pointer to a pointer to the
context that is to be destroyed. The pointer will be set to
NULL when the context has been destroyed.
</para>
It is not permitted to have a NULL
<parameter>malloc_function</parameter>
and a non-NULL
<parameter>free_function</parameter>
or vice versa.
<parameter>arg</parameter>
is passed as the first parameter to the memory
allocation functions.
If
<parameter>malloc_function</parameter>
and
<parameter>free_function</parameter>
are NULL,
<parameter>arg</parameter>
<para>
The context holds a serial number that is used to identify
resolver request packets and associate responses with the
corresponding requests. This serial number is controlled using
<function>lwres_context_initserial()</function> and
<function>lwres_context_nextserial()</function>.
<function>lwres_context_initserial()</function> sets the serial
number for context <parameter>*ctx</parameter> to
<parameter>serial</parameter>.
<function>lwres_context_nextserial()</function> increments the
serial number and returns the previous value.
</para>
is unused and should be passed as NULL.
</para>
<para>
Once memory for the structure has been allocated,
it is initialized using
<citerefentry>
<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
<para>
Memory for a lightweight resolver context is allocated and freed
using <function>lwres_context_allocmem()</function> and
<function>lwres_context_freemem()</function>. These use
whatever allocations were defined when the context was created
with <function>lwres_context_create()</function>.
<function>lwres_context_allocmem()</function> allocates
<parameter>len</parameter> bytes of memory and if successful
returns a pointer to the allocated storage.
<function>lwres_context_freemem()</function> frees
<parameter>len</parameter> bytes of space starting at location
<parameter>mem</parameter>.
</para>
and returned via
<parameter>*contextp</parameter>.
<para><function>lwres_context_sendrecv()</function>
performs I/O for the context <parameter>ctx</parameter>. Data
are read and written from the context's socket. It writes data
from <parameter>sendbase</parameter> &mdash; typically a
lightweight resolver query packet &mdash; and waits for a reply
which is copied to the receive buffer at
<parameter>recvbase</parameter>. The number of bytes that were
written to this receive buffer is returned in
<parameter>*recvd_len</parameter>.
</para>
</refsect1>
</para>
<para>
<function>lwres_context_destroy()</function>
destroys a
<type>lwres_context_t</type>,
<refsect1>
<title>RETURN VALUES</title>
closing its socket.
<parameter>contextp</parameter>
is a pointer to a pointer to the context that is to be destroyed.
The pointer will be set to NULL when the context has been destroyed.
</para>
<para>
The context holds a serial number that is used to identify resolver
request packets and associate responses with the corresponding requests.
This serial number is controlled using
<function>lwres_context_initserial()</function>
and
<function>lwres_context_nextserial()</function>.
<function>lwres_context_initserial()</function>
sets the serial number for context
<parameter>*ctx</parameter>
to
<parameter>serial</parameter>.
<para><function>lwres_context_create()</function>
returns <errorcode>LWRES_R_NOMEMORY</errorcode> if memory for
the <type>struct lwres_context</type> could not be allocated,
<errorcode>LWRES_R_SUCCESS</errorcode> otherwise.
</para>
<para>
Successful calls to the memory allocator
<function>lwres_context_allocmem()</function>
return a pointer to the start of the allocated space.
It returns NULL if memory could not be allocated.
</para>
<para><errorcode>LWRES_R_SUCCESS</errorcode>
is returned when
<function>lwres_context_sendrecv()</function>
completes successfully.
<errorcode>LWRES_R_IOERROR</errorcode>
is returned if an I/O error occurs and
<errorcode>LWRES_R_TIMEOUT</errorcode>
is returned if
<function>lwres_context_sendrecv()</function>
times out waiting for a response.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<function>lwres_context_nextserial()</function>
increments the serial number and returns the previous value.
</para>
<para>
Memory for a lightweight resolver context is allocated and freed using
<function>lwres_context_allocmem()</function>
and
<function>lwres_context_freemem()</function>.
These use whatever allocations were defined when the context was
created with
<function>lwres_context_create()</function>.
<function>lwres_context_allocmem()</function>
allocates
<parameter>len</parameter>
bytes of memory and if successful returns a pointer to the allocated
storage.
<function>lwres_context_freemem()</function>
frees
<parameter>len</parameter>
bytes of space starting at location
<parameter>mem</parameter>.
<citerefentry>
<refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
</para>
<para>
<function>lwres_context_sendrecv()</function>
performs I/O for the context
<parameter>ctx</parameter>.
Data are read and written from the context's socket.
It writes data from
<parameter>sendbase</parameter>
&mdash; typically a lightweight resolver query packet &mdash;
and waits for a reply which is copied to the receive buffer at
<parameter>recvbase</parameter>.
The number of bytes that were written to this receive buffer is
returned in
<parameter>*recvd_len</parameter>.
</para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
<function>lwres_context_create()</function>
returns
<errorcode>LWRES_R_NOMEMORY</errorcode>
if memory for the
<type>struct lwres_context</type>
could not be allocated,
<errorcode>LWRES_R_SUCCESS</errorcode>
otherwise.
</para>
<para>
Successful calls to the memory allocator
<function>lwres_context_allocmem()</function>
return a pointer to the start of the allocated space.
It returns NULL if memory could not be allocated.
</para>
<para>
<errorcode>LWRES_R_SUCCESS</errorcode>
is returned when
<function>lwres_context_sendrecv()</function>
completes successfully.
<errorcode>LWRES_R_IOERROR</errorcode>
is returned if an I/O error occurs and
<errorcode>LWRES_R_TIMEOUT</errorcode>
is returned if
<function>lwres_context_sendrecv()</function>
times out waiting for a response.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>free</refentrytitle><manvolnum>3
</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry>
<citerefentry>
<refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

385
lib/lwres/man/lwres_gabn.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,120 +17,140 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_gabn.docbook,v 1.5 2005/04/07 03:50:01 marka Exp $ -->
<!-- $Id: lwres_gabn.docbook,v 1.6 2005/05/11 05:55:39 sra Exp $ -->
<refentry>
<refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_gabn</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_gabnrequest_render</refname>
<refname>lwres_gabnresponse_render</refname>
<refname>lwres_gabnrequest_parse</refname>
<refname>lwres_gabnresponse_parse</refname>
<refname>lwres_gabnresponse_free</refname>
<refname>lwres_gabnrequest_free</refname>
<refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<refmeta>
<refentrytitle>lwres_gabn</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname>lwres_gabnrequest_render</refname>
<refname>lwres_gabnresponse_render</refname>
<refname>lwres_gabnrequest_parse</refname>
<refname>lwres_gabnresponse_parse</refname>
<refname>lwres_gabnresponse_free</refname>
<refname>lwres_gabnrequest_free</refname>
<refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_gabnrequest_render</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_gabnrequest_t *req</paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef>
<paramdef>lwres_buffer_t *b</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_gabnrequest_t *<parameter>req</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_gabnresponse_render</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_gabnresponse_t *req</paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef>
<paramdef>lwres_buffer_t *b</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_gabnresponse_t *<parameter>req</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_gabnrequest_parse</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef>
<paramdef>lwres_gabnrequest_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_gabnresponse_parse</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef>
<paramdef>lwres_gabnresponse_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_gabnresponse_free</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_gabnresponse_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_gabnrequest_free</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_gabnrequest_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
These are low-level routines for creating and parsing
lightweight resolver name-to-address lookup request and
response messages.
</para><para>
There are four main functions for the getaddrbyname opcode.
One render function converts a getaddrbyname request structure &mdash;
<type>lwres_gabnrequest_t</type> &mdash;
to the lighweight resolver's canonical format.
It is complemented by a parse function that converts a packet in this
canonical format to a getaddrbyname request structure.
Another render function converts the getaddrbyname response structure &mdash;
<type>lwres_gabnresponse_t</type> &mdash;
to the canonical format.
This is complemented by a parse function which converts a packet in
canonical format to a getaddrbyname response structure.
</para>
<para>
These structures are defined in
<filename>&lt;lwres/lwres.h&gt;</filename>.
They are shown below.
<programlisting>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
These are low-level routines for creating and parsing
lightweight resolver name-to-address lookup request and
response messages.
</para>
<para>
There are four main functions for the getaddrbyname opcode.
One render function converts a getaddrbyname request structure &mdash;
<type>lwres_gabnrequest_t</type> &mdash;
to the lighweight resolver's canonical format.
It is complemented by a parse function that converts a packet in this
canonical format to a getaddrbyname request structure.
Another render function converts the getaddrbyname response structure
&mdash; <type>lwres_gabnresponse_t</type> &mdash;
to the canonical format.
This is complemented by a parse function which converts a packet in
canonical format to a getaddrbyname response structure.
</para>
<para>
These structures are defined in
<filename>&lt;lwres/lwres.h&gt;</filename>.
They are shown below.
</para>
<para><programlisting>
#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
</programlisting>
</para>
<para><programlisting>
typedef struct lwres_addr lwres_addr_t;
typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
</programlisting>
</para>
<para><programlisting>
typedef struct {
lwres_uint32_t flags;
lwres_uint32_t addrtypes;
lwres_uint16_t namelen;
char *name;
} lwres_gabnrequest_t;
</programlisting>
</para>
<para><programlisting>
typedef struct {
lwres_uint32_t flags;
lwres_uint16_t naliases;
@@ -142,114 +164,95 @@ typedef struct {
size_t baselen;
} lwres_gabnresponse_t;
</programlisting>
</para>
<para>
<function>lwres_gabnrequest_render()</function>
uses resolver context
<parameter>ctx</parameter>
to convert getaddrbyname request structure
<parameter>req</parameter>
to canonical format.
The packet header structure
<parameter>pkt</parameter>
is initialised and transferred to
buffer
<parameter>b</parameter>.
</para>
The contents of
<parameter>*req</parameter>
are then appended to the buffer in canonical format.
<function>lwres_gabnresponse_render()</function>
performs the same task, except it converts a getaddrbyname response structure
<type>lwres_gabnresponse_t</type>
to the lightweight resolver's canonical format.
</para>
<para>
<function>lwres_gabnrequest_parse()</function>
uses context
<parameter>ctx</parameter>
to convert the contents of packet
<parameter>pkt</parameter>
to a
<type>lwres_gabnrequest_t</type>
structure.
Buffer
<parameter>b</parameter>
provides space to be used for storing this structure.
When the function succeeds, the resulting
<type>lwres_gabnrequest_t</type>
is made available through
<parameter>*structp</parameter>.
<para><function>lwres_gabnrequest_render()</function>
uses resolver context <parameter>ctx</parameter> to convert
getaddrbyname request structure <parameter>req</parameter> to
canonical format. The packet header structure
<parameter>pkt</parameter> is initialised and transferred to
buffer <parameter>b</parameter>.
<function>lwres_gabnresponse_parse()</function>
offers the same semantics as
<function>lwres_gabnrequest_parse()</function>
except it yields a
<type>lwres_gabnresponse_t</type>
structure.
</para>
<para>
<function>lwres_gabnresponse_free()</function>
and
<function>lwres_gabnrequest_free()</function>
release the memory in resolver context
<parameter>ctx</parameter>
that was allocated to the
<type>lwres_gabnresponse_t</type>
or
<type>lwres_gabnrequest_t</type>
structures referenced via
<parameter>structp</parameter>.
The contents of <parameter>*req</parameter> are then appended to
the buffer in canonical format.
<function>lwres_gabnresponse_render()</function> performs the
same task, except it converts a getaddrbyname response structure
<type>lwres_gabnresponse_t</type> to the lightweight resolver's
canonical format.
</para>
Any memory associated with ancillary buffers and strings for those
structures is also discarded.
</para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
The getaddrbyname opcode functions
<function>lwres_gabnrequest_render()</function>,
<function>lwres_gabnresponse_render()</function>
<function>lwres_gabnrequest_parse()</function>
and
<function>lwres_gabnresponse_parse()</function>
all return
<errorcode>LWRES_R_SUCCESS</errorcode>
on success.
They return
<errorcode>LWRES_R_NOMEMORY</errorcode>
if memory allocation fails.
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
is returned if the available space in the buffer
<parameter>b</parameter>
is too small to accommodate the packet header or the
<type>lwres_gabnrequest_t</type>
and
<type>lwres_gabnresponse_t</type>
structures.
<function>lwres_gabnrequest_parse()</function>
and
<function>lwres_gabnresponse_parse()</function>
will return
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
if the buffer is not empty after decoding the received packet.
These functions will return
<errorcode>LWRES_R_FAILURE</errorcode>
if
<structfield>pktflags</structfield>
in the packet header structure
<type>lwres_lwpacket_t</type>
indicate that the packet is not a response to an earlier query.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>lwres_packet</refentrytitle><manvolnum>3
</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
<para><function>lwres_gabnrequest_parse()</function>
uses context <parameter>ctx</parameter> to convert the contents
of packet <parameter>pkt</parameter> to a
<type>lwres_gabnrequest_t</type> structure. Buffer
<parameter>b</parameter> provides space to be used for storing
this structure. When the function succeeds, the resulting
<type>lwres_gabnrequest_t</type> is made available through
<parameter>*structp</parameter>.
<function>lwres_gabnresponse_parse()</function> offers the same
semantics as <function>lwres_gabnrequest_parse()</function>
except it yields a <type>lwres_gabnresponse_t</type> structure.
</para>
<para><function>lwres_gabnresponse_free()</function>
and <function>lwres_gabnrequest_free()</function> release the
memory in resolver context <parameter>ctx</parameter> that was
allocated to the <type>lwres_gabnresponse_t</type> or
<type>lwres_gabnrequest_t</type> structures referenced via
<parameter>structp</parameter>.
Any memory associated with ancillary buffers and strings for
those structures is also discarded.
</para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
The getaddrbyname opcode functions
<function>lwres_gabnrequest_render()</function>,
<function>lwres_gabnresponse_render()</function>
<function>lwres_gabnrequest_parse()</function>
and
<function>lwres_gabnresponse_parse()</function>
all return
<errorcode>LWRES_R_SUCCESS</errorcode>
on success.
They return
<errorcode>LWRES_R_NOMEMORY</errorcode>
if memory allocation fails.
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
is returned if the available space in the buffer
<parameter>b</parameter>
is too small to accommodate the packet header or the
<type>lwres_gabnrequest_t</type>
and
<type>lwres_gabnresponse_t</type>
structures.
<function>lwres_gabnrequest_parse()</function>
and
<function>lwres_gabnresponse_parse()</function>
will return
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
if the buffer is not empty after decoding the received packet.
These functions will return
<errorcode>LWRES_R_FAILURE</errorcode>
if
<structfield>pktflags</structfield>
in the packet header structure
<type>lwres_lwpacket_t</type>
indicate that the packet is not a response to an earlier query.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

301
lib/lwres/man/lwres_gai_strerror.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,147 +17,182 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_gai_strerror.docbook,v 1.5 2005/04/07 03:50:02 marka Exp $ -->
<!-- $Id: lwres_gai_strerror.docbook,v 1.6 2005/05/11 05:55:40 sra Exp $ -->
<refentry>
<refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_gai_strerror</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gai_strerror</refname>
<refpurpose>print suitable error string</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<refmeta>
<refentrytitle>lwres_gai_strerror</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname>lwres_gai_strerror</refname>
<refpurpose>print suitable error string</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
char *
<function>gai_strerror</function></funcdef>
<paramdef>int ecode</paramdef>
</funcprototype>
<paramdef>int <parameter>ecode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
<function>lwres_gai_strerror()</function>
returns an error message corresponding to an error code returned by
<function>getaddrinfo()</function>.
The following error codes and their meaning are defined in
<filename>include/lwres/netdb.h</filename>.
<variablelist>
<varlistentry><term><errorcode>EAI_ADDRFAMILY</errorcode></term>
<listitem>
<para>
address family for hostname not supported
</para>
</listitem></varlistentry>
<varlistentry><term><errorcode>EAI_AGAIN</errorcode></term>
<listitem>
<para>
temporary failure in name resolution
</para>
</listitem></varlistentry>
<varlistentry><term><errorcode>EAI_BADFLAGS</errorcode></term>
<listitem>
<para>
invalid value for
<constant>ai_flags</constant>
</para>
</listitem></varlistentry>
<varlistentry><term><errorcode>EAI_FAIL</errorcode></term>
<listitem>
<para>
non-recoverable failure in name resolution
</para>
</listitem></varlistentry>
<varlistentry><term><errorcode>EAI_FAMILY</errorcode></term>
<listitem>
<para>
<constant>ai_family</constant> not supported
</para>
</listitem></varlistentry>
<varlistentry><term><errorcode>EAI_MEMORY</errorcode></term>
<listitem>
<para>
memory allocation failure
</para>
</listitem></varlistentry>
<varlistentry><term><errorcode>EAI_NODATA</errorcode></term>
<listitem>
<para>
no address associated with hostname
</para>
</listitem></varlistentry>
<varlistentry><term><errorcode>EAI_NONAME</errorcode></term>
<listitem>
<para>
hostname or servname not provided, or not known
</para>
</listitem></varlistentry>
<varlistentry><term><errorcode>EAI_SERVICE</errorcode></term>
<listitem>
<para>
servname not supported for <constant>ai_socktype</constant>
</para>
</listitem></varlistentry>
<varlistentry><term><errorcode>EAI_SOCKTYPE</errorcode></term>
<listitem>
<para>
<constant>ai_socktype</constant> not supported
</para>
</listitem></varlistentry>
<varlistentry><term><errorcode>EAI_SYSTEM</errorcode></term>
<listitem>
<para>
system error returned in errno
</para>
</listitem></varlistentry>
</variablelist>
The message <errorname>invalid error code</errorname> is returned if
<parameter>ecode</parameter>
is out of range.
</para>
<para>
<constant>ai_flags</constant>,
<constant>ai_family</constant>
and
<constant>ai_socktype</constant>
are elements of the
<type>struct addrinfo</type>
used by
<function>lwres_getaddrinfo()</function>.
</para>
</refsect1>
<refsect1>
<title>DESCRIPTION</title>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<para><function>lwres_gai_strerror()</function>
returns an error message corresponding to an error code returned by
<function>getaddrinfo()</function>.
The following error codes and their meaning are defined in
<filename>include/lwres/netdb.h</filename>.
<variablelist>
<varlistentry>
<term><errorcode>EAI_ADDRFAMILY</errorcode></term>
<listitem>
<para>
address family for hostname not supported
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EAI_AGAIN</errorcode></term>
<listitem>
<para>
temporary failure in name resolution
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EAI_BADFLAGS</errorcode></term>
<listitem>
<para>
invalid value for
<constant>ai_flags</constant>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EAI_FAIL</errorcode></term>
<listitem>
<para>
non-recoverable failure in name resolution
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EAI_FAMILY</errorcode></term>
<listitem>
<para><constant>ai_family</constant> not supported
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EAI_MEMORY</errorcode></term>
<listitem>
<para>
memory allocation failure
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EAI_NODATA</errorcode></term>
<listitem>
<para>
no address associated with hostname
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EAI_NONAME</errorcode></term>
<listitem>
<para>
hostname or servname not provided, or not known
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EAI_SERVICE</errorcode></term>
<listitem>
<para>
servname not supported for <constant>ai_socktype</constant>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EAI_SOCKTYPE</errorcode></term>
<listitem>
<para><constant>ai_socktype</constant> not supported
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EAI_SYSTEM</errorcode></term>
<listitem>
<para>
system error returned in errno
</para>
</listitem>
</varlistentry>
</variablelist>
The message <errorname>invalid error code</errorname> is returned if
<parameter>ecode</parameter>
is out of range.
</para>
<para><constant>ai_flags</constant>,
<constant>ai_family</constant>
and
<constant>ai_socktype</constant>
are elements of the
<type>struct addrinfo</type>
used by
<function>lwres_getaddrinfo()</function>.
</para>
</refsect1>
<citerefentry>
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>RFC2133</refentrytitle>
</citerefentry>.
</para>
</refsect1>
</refentry>
<citerefentry>
<refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>RFC2133</refentrytitle>
</citerefentry>.
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

623
lib/lwres/man/lwres_getaddrinfo.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
@@ -15,52 +17,64 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_getaddrinfo.docbook,v 1.8 2005/04/07 03:50:02 marka Exp $ -->
<!-- $Id: lwres_getaddrinfo.docbook,v 1.9 2005/05/11 05:55:40 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_getaddrinfo</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres_getaddrinfo</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_getaddrinfo</refname>
<refname>lwres_freeaddrinfo</refname>
<refpurpose>socket address structure to host and service name</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<year>2003</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname>lwres_getaddrinfo</refname>
<refname>lwres_freeaddrinfo</refname>
<refpurpose>socket address structure to host and service name</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
int
<function>lwres_getaddrinfo</function></funcdef>
<paramdef>const char *hostname</paramdef>
<paramdef>const char *servname</paramdef>
<paramdef>const struct addrinfo *hints</paramdef>
<paramdef>struct addrinfo **res</paramdef>
</funcprototype>
<paramdef>const char *<parameter>hostname</parameter></paramdef>
<paramdef>const char *<parameter>servname</parameter></paramdef>
<paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef>
<paramdef>struct addrinfo **<parameter>res</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_freeaddrinfo</function></funcdef>
<paramdef>struct addrinfo *ai</paramdef>
</funcprototype>
<paramdef>struct addrinfo *<parameter>ai</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
If the operating system does not provide a
<type>struct addrinfo</type>,
the following structure is used:
<programlisting>
<para>
If the operating system does not provide a
<type>struct addrinfo</type>,
the following structure is used:
</para>
<para><programlisting>
struct addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
int ai_family; /* PF_xxx */
@@ -72,301 +86,300 @@ struct addrinfo {
struct addrinfo *ai_next; /* next structure in linked list */
};
</programlisting>
</para>
</para>
</refsynopsisdiv>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
<function>lwres_getaddrinfo()</function>
is used to get a list of IP addresses and port numbers for host
<parameter>hostname</parameter>
and service
<parameter>servname</parameter>.
<refsect1>
<title>DESCRIPTION</title>
The function is the lightweight resolver's implementation of
<function>getaddrinfo()</function>
as defined in RFC2133.
<parameter>hostname</parameter>
and
<parameter>servname</parameter>
are pointers to null-terminated
strings or
<type>NULL</type>.
<para><function>lwres_getaddrinfo()</function>
is used to get a list of IP addresses and port numbers for host
<parameter>hostname</parameter> and service
<parameter>servname</parameter>.
<parameter>hostname</parameter>
is either a host name or a numeric host address string: a dotted decimal
IPv4 address or an IPv6 address.
<parameter>servname</parameter>
is either a decimal port number or a service name as listed in
<filename>/etc/services</filename>.
</para>
The function is the lightweight resolver's implementation of
<function>getaddrinfo()</function> as defined in RFC2133.
<parameter>hostname</parameter> and
<parameter>servname</parameter> are pointers to null-terminated
strings or <type>NULL</type>.
<para>
<parameter>hints</parameter>
is an optional pointer to a
<type>struct addrinfo</type>.
This structure can be used to provide hints concerning the type of socket
that the caller supports or wishes to use.
The caller can supply the following structure elements in
<parameter>*hints</parameter>:
<parameter>hostname</parameter> is either a host name or a
numeric host address string: a dotted decimal IPv4 address or an
IPv6 address. <parameter>servname</parameter> is either a
decimal port number or a service name as listed in
<filename>/etc/services</filename>.
</para>
<variablelist>
<varlistentry><term><constant>ai_family</constant></term>
<listitem>
<para>The protocol family that should be used.
When
<constant>ai_family</constant>
is set to
<type>PF_UNSPEC</type>,
it means the caller will accept any protocol family supported by the
operating system.
</para></listitem></varlistentry>
<varlistentry><term><constant>ai_socktype</constant></term>
<listitem>
<para>
denotes the type of socket &mdash;
<type>SOCK_STREAM</type>,
<type>SOCK_DGRAM</type>
or
<type>SOCK_RAW</type>
&mdash; that is wanted.
When
<constant>ai_socktype</constant>
is zero the caller will accept any socket type.
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>ai_protocol</constant></term>
<listitem>
<para>
indicates which transport protocol is wanted: IPPROTO_UDP or
IPPROTO_TCP.
If
<constant>ai_protocol</constant>
is zero the caller will accept any protocol.
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>ai_flags</constant></term>
<listitem>
<para>
Flag bits.
If the
<type>AI_CANONNAME</type>
bit is set, a successful call to
<function>lwres_getaddrinfo()</function>
will return a null-terminated string containing the canonical name
of the specified hostname in
<constant>ai_canonname</constant>
of the first
<type>addrinfo</type>
structure returned.
Setting the
<type>AI_PASSIVE</type>
bit indicates that the returned socket address structure is intended
for used in a call to
<citerefentry>
<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>.
<para><parameter>hints</parameter>
is an optional pointer to a
<type>struct addrinfo</type>.
This structure can be used to provide hints concerning the type of
socket
that the caller supports or wishes to use.
The caller can supply the following structure elements in
<parameter>*hints</parameter>:
In this case, if the hostname argument is a
<type>NULL</type>
pointer, then the IP address portion of the socket
address structure will be set to
<type>INADDR_ANY</type>
for an IPv4 address or
<type>IN6ADDR_ANY_INIT</type>
for an IPv6 address.
</para>
<para>
When
<constant>ai_flags</constant>
does not set the
<type>AI_PASSIVE</type>
bit, the returned socket address structure will be ready
for use in a call to
<citerefentry>
<refentrytitle>connect</refentrytitle><manvolnum>2
</manvolnum>
</citerefentry>
for a connection-oriented protocol or
<citerefentry>
<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
<variablelist>
<varlistentry>
<term><constant>ai_family</constant></term>
<listitem>
<para>
The protocol family that should be used.
When
<constant>ai_family</constant>
is set to
<type>PF_UNSPEC</type>,
it means the caller will accept any protocol family supported by
the
operating system.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>ai_socktype</constant></term>
<listitem>
<para>
denotes the type of socket &mdash;
<type>SOCK_STREAM</type>,
<type>SOCK_DGRAM</type>
or
<type>SOCK_RAW</type>
&mdash; that is wanted.
When
<constant>ai_socktype</constant>
is zero the caller will accept any socket type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>ai_protocol</constant></term>
<listitem>
<para>
indicates which transport protocol is wanted: IPPROTO_UDP or
IPPROTO_TCP.
If
<constant>ai_protocol</constant>
is zero the caller will accept any protocol.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>ai_flags</constant></term>
<listitem>
<para>
Flag bits.
If the
<type>AI_CANONNAME</type>
bit is set, a successful call to
<function>lwres_getaddrinfo()</function>
will return a null-terminated string containing the canonical
name
of the specified hostname in
<constant>ai_canonname</constant>
of the first
<type>addrinfo</type>
structure returned.
Setting the
<type>AI_PASSIVE</type>
bit indicates that the returned socket address structure is
intended
for used in a call to
<citerefentry>
<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>.
<citerefentry>
<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
In this case, if the hostname argument is a
<type>NULL</type>
pointer, then the IP address portion of the socket
address structure will be set to
<type>INADDR_ANY</type>
for an IPv4 address or
<type>IN6ADDR_ANY_INIT</type>
for an IPv6 address.
</para>
<para>
When
<constant>ai_flags</constant>
does not set the
<type>AI_PASSIVE</type>
bit, the returned socket address structure will be ready
for use in a call to
<citerefentry>
<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>
for a connection-oriented protocol or
<citerefentry>
<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
or
<citerefentry>
<refentrytitle>sendmsg</refentrytitle><manvolnum>2
</manvolnum>
</citerefentry>
if a connectionless protocol was chosen.
The IP address portion of the socket address structure will be
set to the loopback address if
<parameter>hostname</parameter>
is a
<type>NULL</type>
pointer and
<type>AI_PASSIVE</type>
is not set in
<constant>ai_flags</constant>.
</para>
<para>
If
<constant>ai_flags</constant>
is set to
<type>AI_NUMERICHOST</type>
it indicates that
<parameter>hostname</parameter>
should be treated as a numeric string defining an IPv4 or IPv6 address
and no name resolution should be attempted.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<citerefentry>
<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
<para>
All other elements of the <type>struct addrinfo</type> passed
via <parameter>hints</parameter> must be zero.
</para>
or
<citerefentry>
<refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>
if a connectionless protocol was chosen.
The IP address portion of the socket address structure will be
set to the loopback address if
<parameter>hostname</parameter>
is a
<type>NULL</type>
pointer and
<type>AI_PASSIVE</type>
is not set in
<constant>ai_flags</constant>.
</para>
<para>
If
<constant>ai_flags</constant>
is set to
<type>AI_NUMERICHOST</type>
it indicates that
<parameter>hostname</parameter>
should be treated as a numeric string defining an IPv4 or IPv6
address
and no name resolution should be attempted.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
A <parameter>hints</parameter> of <type>NULL</type> is treated as if
the caller provided a <type>struct addrinfo</type> initialized to zero
with <constant>ai_family</constant>set to
<constant>PF_UNSPEC</constant>.
</para>
<para>
All other elements of the <type>struct addrinfo</type> passed
via <parameter>hints</parameter> must be zero.
</para>
<para>
After a successful call to
<function>lwres_getaddrinfo()</function>,
<parameter>*res</parameter>
is a pointer to a linked list of one or more
<type>addrinfo</type>
structures.
Each
<type>struct addrinfo</type>
in this list cn be processed by following
the
<constant>ai_next</constant>
pointer, until a
<type>NULL</type>
pointer is encountered.
The three members
<constant>ai_family</constant>,
<constant>ai_socktype</constant>,
and
<constant>ai_protocol</constant>
in each
returned
<type>addrinfo</type>
structure contain the corresponding arguments for a call to
<citerefentry>
<refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>.
For each
<type>addrinfo</type>
structure in the list, the
<constant>ai_addr</constant>
member points to a filled-in socket address structure of length
<constant>ai_addrlen</constant>.
</para>
<para>
A <parameter>hints</parameter> of <type>NULL</type> is
treated as if
the caller provided a <type>struct addrinfo</type> initialized to zero
with <constant>ai_family</constant>set to
<constant>PF_UNSPEC</constant>.
</para>
<para>
All of the information returned by
<function>lwres_getaddrinfo()</function>
is dynamically allocated: the addrinfo structures, and the socket
address structures and canonical host name strings pointed to by the
<constant>addrinfo</constant>structures.
Memory allocated for the dynamically allocated structures created by
a successful call to
<function>lwres_getaddrinfo()</function>
is released by
<function>lwres_freeaddrinfo()</function>.
<parameter>ai</parameter>
is a pointer to a
<type>struct addrinfo</type>
created by a call to
<function>lwres_getaddrinfo()</function>.
</para>
<para>
After a successful call to
<function>lwres_getaddrinfo()</function>,
<parameter>*res</parameter>
is a pointer to a linked list of one or more
<type>addrinfo</type>
structures.
Each
<type>struct addrinfo</type>
in this list cn be processed by following
the
<constant>ai_next</constant>
pointer, until a
<type>NULL</type>
pointer is encountered.
The three members
<constant>ai_family</constant>,
<constant>ai_socktype</constant>,
and
<constant>ai_protocol</constant>
in each
returned
<type>addrinfo</type>
structure contain the corresponding arguments for a call to
<citerefentry>
<refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>.
For each
<type>addrinfo</type>
structure in the list, the
<constant>ai_addr</constant>
member points to a filled-in socket address structure of length
<constant>ai_addrlen</constant>.
</para>
</refsect1>
<para>
All of the information returned by
<function>lwres_getaddrinfo()</function>
is dynamically allocated: the addrinfo structures, and the socket
address structures and canonical host name strings pointed to by the
<constant>addrinfo</constant>structures.
Memory allocated for the dynamically allocated structures created by
a successful call to
<function>lwres_getaddrinfo()</function>
is released by
<function>lwres_freeaddrinfo()</function>.
<parameter>ai</parameter>
is a pointer to a
<type>struct addrinfo</type>
created by a call to
<function>lwres_getaddrinfo()</function>.
</para>
<refsect1>
<title>RETURN VALUES</title>
<para>
<function>lwres_getaddrinfo()</function>
returns zero on success or one of the error codes listed in
<citerefentry>
<refentrytitle>gai_strerror</refentrytitle><manvolnum>3
</manvolnum>
</citerefentry>
if an error occurs.
If both
<parameter>hostname</parameter>
and
<parameter>servname</parameter>
are
<type>NULL</type>
<function>lwres_getaddrinfo()</function>
returns
<errorcode>EAI_NONAME</errorcode>.
</refsect1>
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<refsect1>
<title>RETURN VALUES</title>
<citerefentry>
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<para><function>lwres_getaddrinfo()</function>
returns zero on success or one of the error codes listed in
<citerefentry>
<refentrytitle>gai_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
if an error occurs. If both <parameter>hostname</parameter> and
<parameter>servname</parameter> are <type>NULL</type>
<function>lwres_getaddrinfo()</function> returns
<errorcode>EAI_NONAME</errorcode>.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>RFC2133</refentrytitle>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>RFC2133</refentrytitle>
</citerefentry>,
<citerefentry>
<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>.
</para>
<citerefentry>
<refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>,
</refsect1>
</refentry>
<citerefentry>
<refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

690
lib/lwres/man/lwres_gethostent.docbook
View File

@@ -1,6 +1,8 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2001 Internet Software Consortium.
-
- Permission to use, copy, modify, and distribute this software for any
@@ -15,140 +17,149 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_gethostent.docbook,v 1.6 2004/03/05 05:12:56 marka Exp $ -->
<!-- $Id: lwres_gethostent.docbook,v 1.7 2005/05/11 05:55:40 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_gethostent</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres_gethostent</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_gethostbyname</refname>
<refname>lwres_gethostbyname2</refname>
<refname>lwres_gethostbyaddr</refname>
<refname>lwres_gethostent</refname>
<refname>lwres_sethostent</refname>
<refname>lwres_endhostent</refname>
<refname>lwres_gethostbyname_r</refname>
<refname>lwres_gethostbyaddr_r</refname>
<refname>lwres_gethostent_r</refname>
<refname>lwres_sethostent_r</refname>
<refname>lwres_endhostent_r</refname>
<refpurpose>lightweight resolver get network host entry</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname>lwres_gethostbyname</refname>
<refname>lwres_gethostbyname2</refname>
<refname>lwres_gethostbyaddr</refname>
<refname>lwres_gethostent</refname>
<refname>lwres_sethostent</refname>
<refname>lwres_endhostent</refname>
<refname>lwres_gethostbyname_r</refname>
<refname>lwres_gethostbyaddr_r</refname>
<refname>lwres_gethostent_r</refname>
<refname>lwres_sethostent_r</refname>
<refname>lwres_endhostent_r</refname>
<refpurpose>lightweight resolver get network host entry</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
struct hostent *
<function>lwres_gethostbyname</function></funcdef>
<paramdef>const char *name</paramdef>
</funcprototype>
<paramdef>const char *<parameter>name</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
struct hostent *
<function>lwres_gethostbyname2</function></funcdef>
<paramdef>const char *name</paramdef>
<paramdef>int af</paramdef>
</funcprototype>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>int <parameter>af</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
struct hostent *
<function>lwres_gethostbyaddr</function></funcdef>
<paramdef>const char *addr</paramdef>
<paramdef>int len</paramdef>
<paramdef>int type</paramdef>
</funcprototype>
<paramdef>const char *<parameter>addr</parameter></paramdef>
<paramdef>int <parameter>len</parameter></paramdef>
<paramdef>int <parameter>type</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
struct hostent *
<function>lwres_gethostent</function></funcdef>
<paramdef>void</paramdef>
</funcprototype>
<paramdef>void</paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_sethostent</function></funcdef>
<paramdef>int stayopen</paramdef>
</funcprototype>
<paramdef>int <parameter>stayopen</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_endhostent</function></funcdef>
<paramdef>void</paramdef>
</funcprototype>
<paramdef>void</paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
struct hostent *
<function>lwres_gethostbyname_r</function></funcdef>
<paramdef>const char *name</paramdef>
<paramdef>struct hostent *resbuf</paramdef>
<paramdef>char *buf</paramdef>
<paramdef>int buflen</paramdef>
<paramdef>int *error</paramdef>
</funcprototype>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>struct hostent *<parameter>resbuf</parameter></paramdef>
<paramdef>char *<parameter>buf</parameter></paramdef>
<paramdef>int <parameter>buflen</parameter></paramdef>
<paramdef>int *<parameter>error</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
struct hostent *
<function>lwres_gethostbyaddr_r</function></funcdef>
<paramdef>const char *addr</paramdef>
<paramdef>int len</paramdef>
<paramdef>int type</paramdef>
<paramdef>struct hostent *resbuf</paramdef>
<paramdef>char *buf</paramdef>
<paramdef>int buflen</paramdef>
<paramdef>int *error</paramdef>
</funcprototype>
<paramdef>const char *<parameter>addr</parameter></paramdef>
<paramdef>int <parameter>len</parameter></paramdef>
<paramdef>int <parameter>type</parameter></paramdef>
<paramdef>struct hostent *<parameter>resbuf</parameter></paramdef>
<paramdef>char *<parameter>buf</parameter></paramdef>
<paramdef>int <parameter>buflen</parameter></paramdef>
<paramdef>int *<parameter>error</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
struct hostent *
<function>lwres_gethostent_r</function></funcdef>
<paramdef>struct hostent *resbuf</paramdef>
<paramdef>char *buf</paramdef>
<paramdef>int buflen</paramdef>
<paramdef>int *error</paramdef>
</funcprototype>
<paramdef>struct hostent *<parameter>resbuf</parameter></paramdef>
<paramdef>char *<parameter>buf</parameter></paramdef>
<paramdef>int <parameter>buflen</parameter></paramdef>
<paramdef>int *<parameter>error</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_sethostent_r</function></funcdef>
<paramdef>int stayopen</paramdef>
</funcprototype>
<paramdef>int <parameter>stayopen</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_endhostent_r</function></funcdef>
<paramdef>void</paramdef>
</funcprototype>
<paramdef>void</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
These functions provide hostname-to-address and
address-to-hostname lookups by means of the lightweight resolver.
They are similar to the standard
<citerefentry>
<refentrytitle>gethostent</refentrytitle><manvolnum>3
</manvolnum>
</citerefentry>
functions provided by most operating systems.
They use a
<type>struct hostent</type>
which is usually defined in
<filename>&lt;namedb.h&gt;</filename>.
<programlisting>
<refsect1>
<title>DESCRIPTION</title>
<para>
These functions provide hostname-to-address and
address-to-hostname lookups by means of the lightweight resolver.
They are similar to the standard
<citerefentry>
<refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
functions provided by most operating systems.
They use a
<type>struct hostent</type>
which is usually defined in
<filename>&lt;namedb.h&gt;</filename>.
</para>
<para><programlisting>
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
@@ -158,250 +169,269 @@ struct hostent {
};
#define h_addr h_addr_list[0] /* address, for backward compatibility */
</programlisting>
</para>
<para>
The members of this structure are:
<variablelist>
<varlistentry><term><constant>h_name</constant></term>
<listitem>
<para>
The official (canonical) name of the host.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>h_aliases</constant></term>
<listitem>
<para>
A NULL-terminated array of alternate names (nicknames) for the host.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>h_addrtype</constant></term>
<listitem>
<para>
The type of address being returned &mdash;
<type>PF_INET</type>
or
<type>PF_INET6</type>.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>h_length</constant></term>
<listitem>
<para>
The length of the address in bytes.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>h_addr_list</constant></term>
<listitem>
<para>
A <type>NULL</type>
terminated array of network addresses for the host.
Host addresses are returned in network byte order.
</para>
</listitem></varlistentry>
</variablelist>
</para>
<para>
For backward compatibility with very old software,
<constant>h_addr</constant>
is the first address in
<constant>h_addr_list.</constant>
</para>
<para>
<function>lwres_gethostent()</function>,
<function>lwres_sethostent()</function>,
<function>lwres_endhostent()</function>,
<function>lwres_gethostent_r()</function>,
<function>lwres_sethostent_r()</function>
and
<function>lwres_endhostent_r()</function>
provide iteration over the known host entries on systems that
provide such functionality through facilities like
<filename>/etc/hosts</filename>
or NIS. The lightweight resolver does not currently implement
these functions; it only provides them as stub functions that always
return failure.
</para>
</para>
<para>
The members of this structure are:
<variablelist>
<varlistentry>
<term><constant>h_name</constant></term>
<listitem>
<para>
The official (canonical) name of the host.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>h_aliases</constant></term>
<listitem>
<para>
A NULL-terminated array of alternate names (nicknames) for the
host.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>h_addrtype</constant></term>
<listitem>
<para>
The type of address being returned &mdash;
<type>PF_INET</type>
or
<type>PF_INET6</type>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>h_length</constant></term>
<listitem>
<para>
The length of the address in bytes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>h_addr_list</constant></term>
<listitem>
<para>
A <type>NULL</type>
terminated array of network addresses for the host.
Host addresses are returned in network byte order.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
For backward compatibility with very old software,
<constant>h_addr</constant>
is the first address in
<constant>h_addr_list.</constant>
</para>
<para><function>lwres_gethostent()</function>,
<function>lwres_sethostent()</function>,
<function>lwres_endhostent()</function>,
<function>lwres_gethostent_r()</function>,
<function>lwres_sethostent_r()</function>
and
<function>lwres_endhostent_r()</function>
provide iteration over the known host entries on systems that
provide such functionality through facilities like
<filename>/etc/hosts</filename>
or NIS. The lightweight resolver does not currently implement
these functions; it only provides them as stub functions that always
return failure.
</para>
<para>
<function>lwres_gethostbyname()</function> and
<function>lwres_gethostbyname2()</function> look up the hostname
<parameter>name</parameter>.
<function>lwres_gethostbyname()</function> always looks for an IPv4
address while <function>lwres_gethostbyname2()</function> looks for an
address of protocol family <parameter>af</parameter>: either
<type>PF_INET</type> or <type>PF_INET6</type> &mdash; IPv4 or IPV6
addresses respectively. Successful calls of the functions return a
<type>struct hostent</type>for the name that was looked up.
<type>NULL</type> is returned if the lookups by
<function>lwres_gethostbyname()</function> or
<function>lwres_gethostbyname2()</function> fail.
</para>
<para><function>lwres_gethostbyname()</function>
and <function>lwres_gethostbyname2()</function> look up the
hostname <parameter>name</parameter>.
<function>lwres_gethostbyname()</function> always looks for an
IPv4 address while <function>lwres_gethostbyname2()</function>
looks for an address of protocol family
<parameter>af</parameter>: either <type>PF_INET</type> or
<type>PF_INET6</type> &mdash; IPv4 or IPV6 addresses
respectively. Successful calls of the functions return a
<type>struct hostent</type>for the name that was looked up.
<type>NULL</type> is returned if the lookups by
<function>lwres_gethostbyname()</function> or
<function>lwres_gethostbyname2()</function> fail.
</para>
<para>
Reverse lookups of addresses are performed by
<function>lwres_gethostbyaddr()</function>.
<parameter>addr</parameter> is an address of length
<parameter>len</parameter> bytes and protocol family
<parameter>type</parameter> &mdash; <type>PF_INET</type> or
<type>PF_INET6</type>.
<function>lwres_gethostbyname_r()</function> is a thread-safe function
for forward lookups. If an error occurs, an error code is returned in
<parameter>*error</parameter>.
<parameter>resbuf</parameter> is a pointer to a <type>struct
hostent</type> which is initialised by a successful call to
<function>lwres_gethostbyname_r()</function> .
<parameter>buf</parameter> is a buffer of length
<parameter>len</parameter> bytes which is used to store the
<constant>h_name</constant>, <constant>h_aliases</constant>, and
<constant>h_addr_list</constant> elements of the <type>struct
hostent</type> returned in <parameter>resbuf</parameter>.
Successful calls to <function>lwres_gethostbyname_r()</function>
return <parameter>resbuf</parameter>,
which is a pointer to the <type>struct hostent</type> it created.
</para>
<para>
Reverse lookups of addresses are performed by
<function>lwres_gethostbyaddr()</function>.
<parameter>addr</parameter> is an address of length
<parameter>len</parameter> bytes and protocol family
<parameter>type</parameter> &mdash; <type>PF_INET</type> or
<type>PF_INET6</type>.
<function>lwres_gethostbyname_r()</function> is a
thread-safe function
for forward lookups. If an error occurs, an error code is returned in
<parameter>*error</parameter>.
<parameter>resbuf</parameter> is a pointer to a
<type>struct hostent</type> which is initialised by a successful call to
<function>lwres_gethostbyname_r()</function>.
<parameter>buf</parameter> is a buffer of length
<parameter>len</parameter> bytes which is used to store the
<constant>h_name</constant>, <constant>h_aliases</constant>, and
<constant>h_addr_list</constant> elements of the
<type>struct hostent</type> returned in <parameter>resbuf</parameter>.
Successful calls to <function>lwres_gethostbyname_r()</function>
return <parameter>resbuf</parameter>,
which is a pointer to the <type>struct hostent</type> it created.
</para>
<para>
<function>lwres_gethostbyaddr_r()</function> is a thread-safe function
that performs a reverse lookup of address <parameter>addr</parameter>
which is <parameter>len</parameter> bytes long and is of protocol
family <parameter>type</parameter> &mdash; <type>PF_INET</type> or
<type>PF_INET6</type>. If an error occurs, the error code is returned
in <parameter>*error</parameter>. The other function parameters are
identical to those in <function>lwres_gethostbyname_r()</function>.
<parameter>resbuf</parameter> is a pointer to a <type>struct
hostent</type> which is initialised by a successful call to
<function>lwres_gethostbyaddr_r()</function>.
<parameter>buf</parameter> is a buffer of length
<parameter>len</parameter> bytes which is used to store the
<constant>h_name</constant>, <constant>h_aliases</constant>, and
<constant>h_addr_list</constant> elements of the <type>struct
hostent</type> returned in <parameter>resbuf</parameter>. Successful
calls to <function>lwres_gethostbyaddr_r()</function> return
<parameter>resbuf</parameter>, which is a pointer to the
<function>struct hostent()</function> it created.
</para>
<para><function>lwres_gethostbyaddr_r()</function>
is a thread-safe function
that performs a reverse lookup of address <parameter>addr</parameter>
which is <parameter>len</parameter> bytes long and is of
protocol
family <parameter>type</parameter> &mdash; <type>PF_INET</type> or
<type>PF_INET6</type>. If an error occurs, the error code is returned
in <parameter>*error</parameter>. The other function
parameters are
identical to those in <function>lwres_gethostbyname_r()</function>.
<parameter>resbuf</parameter> is a pointer to a
<type>struct hostent</type> which is initialised by a successful call to
<function>lwres_gethostbyaddr_r()</function>.
<parameter>buf</parameter> is a buffer of length
<parameter>len</parameter> bytes which is used to store the
<constant>h_name</constant>, <constant>h_aliases</constant>, and
<constant>h_addr_list</constant> elements of the
<type>struct hostent</type> returned in <parameter>resbuf</parameter>.
Successful calls to <function>lwres_gethostbyaddr_r()</function> return
<parameter>resbuf</parameter>, which is a pointer to the
<function>struct hostent()</function> it created.
</para>
</refsect1>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
The functions
<function>lwres_gethostbyname()</function>,
<function>lwres_gethostbyname2()</function>,
<function>lwres_gethostbyaddr()</function>,
and
<function>lwres_gethostent()</function>
return NULL to indicate an error. In this case the global variable
<type>lwres_h_errno</type>
will contain one of the following error codes defined in
<filename>&lt;lwres/netdb.h&gt;</filename>:
<refsect1>
<title>RETURN VALUES</title>
<para>
The functions
<function>lwres_gethostbyname()</function>,
<function>lwres_gethostbyname2()</function>,
<function>lwres_gethostbyaddr()</function>,
and
<function>lwres_gethostent()</function>
return NULL to indicate an error. In this case the global variable
<type>lwres_h_errno</type>
will contain one of the following error codes defined in
<filename>&lt;lwres/netdb.h&gt;</filename>:
<variablelist>
<varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
<listitem>
<para>
The host or address was not found.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>TRY_AGAIN</constant></term>
<listitem>
<para>
A recoverable error occurred, e.g., a timeout.
Retrying the lookup may succeed.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>NO_RECOVERY</constant></term>
<listitem>
<para>
A non-recoverable error occurred.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>NO_DATA</constant></term>
<listitem>
<para>
The name exists, but has no address information
associated with it (or vice versa in the case
of a reverse lookup). The code NO_ADDRESS
is accepted as a synonym for NO_DATA for backwards
compatibility.
</para>
</listitem></varlistentry>
</variablelist>
</para>
<variablelist>
<varlistentry>
<term><constant>HOST_NOT_FOUND</constant></term>
<listitem>
<para>
The host or address was not found.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>TRY_AGAIN</constant></term>
<listitem>
<para>
A recoverable error occurred, e.g., a timeout.
Retrying the lookup may succeed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>NO_RECOVERY</constant></term>
<listitem>
<para>
A non-recoverable error occurred.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>NO_DATA</constant></term>
<listitem>
<para>
The name exists, but has no address information
associated with it (or vice versa in the case
of a reverse lookup). The code NO_ADDRESS
is accepted as a synonym for NO_DATA for backwards
compatibility.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<citerefentry>
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
</manvolnum>
</citerefentry>
translates these error codes to suitable error messages.
</para>
<para><citerefentry>
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
translates these error codes to suitable error messages.
</para>
<para>
<function>lwres_gethostent()</function>
and
<function>lwres_gethostent_r()</function>
always return
<type>NULL</type>.
</para>
<para><function>lwres_gethostent()</function>
and <function>lwres_gethostent_r()</function>
always return <type>NULL</type>.
</para>
<para>
Successful calls to <function>lwres_gethostbyname_r()</function> and
<function>lwres_gethostbyaddr_r()</function> return
<parameter>resbuf</parameter>, a pointer to the <type>struct
hostent</type> that was initialised by these functions. They return
<type>NULL</type> if the lookups fail or if <parameter>buf</parameter>
was too small to hold the list of addresses and names referenced by
the <constant>h_name</constant>, <constant>h_aliases</constant>, and
<constant>h_addr_list</constant> elements of the <type>struct
hostent</type>. If <parameter>buf</parameter> was too small, both
<function>lwres_gethostbyname_r()</function> and
<function>lwres_gethostbyaddr_r()</function> set the global variable
<type>errno</type> to <errorcode>ERANGE</errorcode>.
</para>
<para>
Successful calls to <function>lwres_gethostbyname_r()</function> and
<function>lwres_gethostbyaddr_r()</function> return
<parameter>resbuf</parameter>, a pointer to the
<type>struct hostent</type> that was initialised by these functions. They return
<type>NULL</type> if the lookups fail or if <parameter>buf</parameter>
was too small to hold the list of addresses and names referenced by
the <constant>h_name</constant>, <constant>h_aliases</constant>, and
<constant>h_addr_list</constant> elements of the
<type>struct hostent</type>.
If <parameter>buf</parameter> was too small, both
<function>lwres_gethostbyname_r()</function> and
<function>lwres_gethostbyaddr_r()</function> set the global
variable
<type>errno</type> to <errorcode>ERANGE</errorcode>.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
</manvolnum>
</citerefentry>
</para>
</refsect1>
<citerefentry>
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1>
<title>BUGS</title>
<para>
<function>lwres_gethostbyname()</function>,
<function>lwres_gethostbyname2()</function>,
<function>lwres_gethostbyaddr()</function>
and
<function>lwres_endhostent()</function>
are not thread safe; they return pointers to static data and
provide error codes through a global variable.
Thread-safe versions for name and address lookup are provided by
<function>lwres_gethostbyname_r()</function>,
and
<function>lwres_gethostbyaddr_r()</function>
respectively.
</para>
<para>
The resolver daemon does not currently support any non-DNS
name services such as
<filename>/etc/hosts</filename>
or
<type>NIS</type>,
consequently the above functions don't, either.
</para>
</refsect1>
</refentry>
<refsect1>
<title>BUGS</title>
<para><function>lwres_gethostbyname()</function>,
<function>lwres_gethostbyname2()</function>,
<function>lwres_gethostbyaddr()</function>
and
<function>lwres_endhostent()</function>
are not thread safe; they return pointers to static data and
provide error codes through a global variable.
Thread-safe versions for name and address lookup are provided by
<function>lwres_gethostbyname_r()</function>,
and
<function>lwres_gethostbyaddr_r()</function>
respectively.
</para>
<para>
The resolver daemon does not currently support any non-DNS
name services such as
<filename>/etc/hosts</filename>
or
<type>NIS</type>,
consequently the above functions don't, either.
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

530
lib/lwres/man/lwres_getipnode.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
@@ -15,72 +17,85 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_getipnode.docbook,v 1.7 2005/04/07 03:50:02 marka Exp $ -->
<!-- $Id: lwres_getipnode.docbook,v 1.8 2005/05/11 05:55:40 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_getipnode</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres_getipnode</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_getipnodebyname</refname>
<refname>lwres_getipnodebyaddr</refname>
<refname>lwres_freehostent</refname>
<refpurpose>lightweight resolver nodename / address translation API</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<year>2003</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname>lwres_getipnodebyname</refname>
<refname>lwres_getipnodebyaddr</refname>
<refname>lwres_freehostent</refname>
<refpurpose>lightweight resolver nodename / address translation API</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
struct hostent *
<function>lwres_getipnodebyname</function></funcdef>
<paramdef>const char *name</paramdef>
<paramdef>int af</paramdef>
<paramdef>int flags</paramdef>
<paramdef>int *error_num</paramdef>
</funcprototype>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>int <parameter>af</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>int *<parameter>error_num</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
struct hostent *
<function>lwres_getipnodebyaddr</function></funcdef>
<paramdef>const void *src</paramdef>
<paramdef>size_t len</paramdef>
<paramdef>int af</paramdef>
<paramdef>int *error_num</paramdef>
</funcprototype>
<paramdef>const void *<parameter>src</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
<paramdef>int <parameter>af</parameter></paramdef>
<paramdef>int *<parameter>error_num</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_freehostent</function></funcdef>
<paramdef>struct hostent *he</paramdef>
</funcprototype>
<paramdef>struct hostent *<parameter>he</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<refsect1>
<title>DESCRIPTION</title>
<para>
These functions perform thread safe, protocol independent
nodename-to-address and address-to-nodename
translation as defined in RFC2553.
</para>
<para>
These functions perform thread safe, protocol independent
nodename-to-address and address-to-nodename
translation as defined in RFC2553.
</para>
<para>
They use a
<type>struct hostent</type>
which is defined in
<filename>namedb.h</filename>:
<programlisting>
<para>
They use a
<type>struct hostent</type>
which is defined in
<filename>namedb.h</filename>:
</para>
<para><programlisting>
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
@@ -90,218 +105,225 @@ struct hostent {
};
#define h_addr h_addr_list[0] /* address, for backward compatibility */
</programlisting>
</para>
</para>
<para>
The members of this structure are:
<variablelist>
<varlistentry><term><constant>h_name</constant></term>
<listitem>
<para>
The official (canonical) name of the host.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>h_aliases</constant></term>
<listitem>
<para>
A NULL-terminated array of alternate names (nicknames) for the host.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>h_addrtype</constant></term>
<listitem>
<para>
The type of address being returned - usually
<type>PF_INET</type>
or
<type>PF_INET6</type>.
<para>
The members of this structure are:
<variablelist>
<varlistentry>
<term><constant>h_name</constant></term>
<listitem>
<para>
The official (canonical) name of the host.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>h_aliases</constant></term>
<listitem>
<para>
A NULL-terminated array of alternate names (nicknames) for the
host.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>h_addrtype</constant></term>
<listitem>
<para>
The type of address being returned - usually
<type>PF_INET</type>
or
<type>PF_INET6</type>.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>h_length</constant></term>
<listitem>
<para>
The length of the address in bytes.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>h_addr_list</constant></term>
<listitem>
<para>
A
<type>NULL</type>
terminated array of network addresses for the host.
Host addresses are returned in network byte order.
</para>
</listitem></varlistentry>
</variablelist>
</para>
<para>
<function>lwres_getipnodebyname()</function>
looks up addresses of protocol family
<parameter>af</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>h_length</constant></term>
<listitem>
<para>
The length of the address in bytes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>h_addr_list</constant></term>
<listitem>
<para>
A
<type>NULL</type>
terminated array of network addresses for the host.
Host addresses are returned in network byte order.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
for the hostname
<parameter>name</parameter>.
<para><function>lwres_getipnodebyname()</function>
looks up addresses of protocol family <parameter>af</parameter>
for the hostname <parameter>name</parameter>. The
<parameter>flags</parameter> parameter contains ORed flag bits
to specify the types of addresses that are searched for, and the
types of addresses that are returned. The flag bits are:
The
<parameter>flags</parameter>
parameter contains ORed flag bits to
specify the types of addresses that are searched
for, and the types of addresses that are returned.
The flag bits are:
<variablelist>
<varlistentry><term><constant>AI_V4MAPPED</constant></term>
<listitem>
<para>
This is used with an
<parameter>af</parameter>
of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
IPv6 addresses.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>AI_ALL</constant></term>
<listitem>
<para>
This is used with an
<parameter>af</parameter>
of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
IPv6 addresses.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>AI_ADDRCONFIG</constant></term>
<listitem>
<para>
Only return an IPv6 or IPv4 address if here is an active network
interface of that type. This is not currently implemented
in the BIND 9 lightweight resolver, and the flag is ignored.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>AI_DEFAULT</constant></term>
<listitem>
<para>
This default sets the
<constant>AI_V4MAPPED</constant>
and
<constant>AI_ADDRCONFIG</constant>
flag bits.
</para>
</listitem></varlistentry>
</variablelist>
</para>
<para>
<function>lwres_getipnodebyaddr()</function>
performs a reverse lookup
of address
<parameter>src</parameter>
which is
<parameter>len</parameter>
bytes long.
<parameter>af</parameter>
denotes the protocol family, typically
<type>PF_INET</type>
or
<type>PF_INET6</type>.
<variablelist>
<varlistentry>
<term><constant>AI_V4MAPPED</constant></term>
<listitem>
<para>
This is used with an
<parameter>af</parameter>
of AF_INET6, and causes IPv4 addresses to be returned as
IPv4-mapped
IPv6 addresses.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>AI_ALL</constant></term>
<listitem>
<para>
This is used with an
<parameter>af</parameter>
of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
be returned.
If AI_V4MAPPED is also set, the IPv4 addresses are return as
mapped
IPv6 addresses.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>AI_ADDRCONFIG</constant></term>
<listitem>
<para>
Only return an IPv6 or IPv4 address if here is an active network
interface of that type. This is not currently implemented
in the BIND 9 lightweight resolver, and the flag is ignored.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>AI_DEFAULT</constant></term>
<listitem>
<para>
This default sets the
<constant>AI_V4MAPPED</constant>
and
<constant>AI_ADDRCONFIG</constant>
flag bits.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</para>
<para>
<function>lwres_freehostent()</function>
releases all the memory associated with
the
<type>struct hostent</type>
pointer
<parameter>he</parameter>.
<para><function>lwres_getipnodebyaddr()</function>
performs a reverse lookup of address <parameter>src</parameter>
which is <parameter>len</parameter> bytes long.
<parameter>af</parameter> denotes the protocol family, typically
<type>PF_INET</type> or <type>PF_INET6</type>.
</para>
<para><function>lwres_freehostent()</function>
releases all the memory associated with the <type>struct
hostent</type> pointer <parameter>he</parameter>. Any memory
allocated for the <constant>h_name</constant>,
<constant>h_addr_list</constant> and
<constant>h_aliases</constant> is freed, as is the memory for
the <type>hostent</type> structure itself.
</para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
If an error occurs,
<function>lwres_getipnodebyname()</function>
and
<function>lwres_getipnodebyaddr()</function>
set
<parameter>*error_num</parameter>
to an appropriate error code and the function returns a
<type>NULL</type>
pointer.
The error codes and their meanings are defined in
<filename>&lt;lwres/netdb.h&gt;</filename>:
<variablelist>
<varlistentry>
<term><constant>HOST_NOT_FOUND</constant></term>
<listitem>
<para>
No such host is known.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>NO_ADDRESS</constant></term>
<listitem>
<para>
The server recognised the request and the name but no address is
available. Another type of request to the name server for the
domain might return an answer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>TRY_AGAIN</constant></term>
<listitem>
<para>
A temporary and possibly transient error occurred, such as a
failure of a server to respond. The request may succeed if
retried.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>NO_RECOVERY</constant></term>
<listitem>
<para>
An unexpected failure occurred, and retrying the request
is pointless.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para><citerefentry>
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
translates these error codes to suitable error messages.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>RFC2553</refentrytitle>
</citerefentry>,
Any memory allocated for the
<constant>h_name</constant>,
<citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<constant>h_addr_list</constant>
and
<constant>h_aliases</constant>
is freed, as is the memory for the
<type>hostent</type>
structure itself.
</para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
If an error occurs,
<function>lwres_getipnodebyname()</function>
and
<function>lwres_getipnodebyaddr()</function>
set
<parameter>*error_num</parameter>
to an appropriate error code and the function returns a
<type>NULL</type>
pointer.
The error codes and their meanings are defined in
<filename>&lt;lwres/netdb.h&gt;</filename>:
<variablelist>
<varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
<listitem>
<para>
No such host is known.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>NO_ADDRESS</constant></term>
<listitem>
<para>
The server recognised the request and the name but no address is
available. Another type of request to the name server for the
domain might return an answer.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>TRY_AGAIN</constant></term>
<listitem>
<para>
A temporary and possibly transient error occurred, such as a
failure of a server to respond. The request may succeed if
retried.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>NO_RECOVERY</constant></term>
<listitem>
<para>
An unexpected failure occurred, and retrying the request
is pointless.
</para>
</listitem></varlistentry>
</variablelist>
</para>
<para>
<citerefentry>
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
</manvolnum>
</citerefentry>
translates these error codes to suitable error messages.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>RFC2553</refentrytitle>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry>
<citerefentry>
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

297
lib/lwres/man/lwres_getnameinfo.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,140 +17,187 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_getnameinfo.docbook,v 1.5 2005/04/07 03:50:02 marka Exp $ -->
<!-- $Id: lwres_getnameinfo.docbook,v 1.6 2005/05/11 05:55:40 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_getnameinfo</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres_getnameinfo</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_getnameinfo</refname>
<refpurpose>lightweight resolver socket address structure to hostname and service name</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname>lwres_getnameinfo</refname>
<refpurpose>lightweight resolver socket address structure to hostname and
service name
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
int
<function>lwres_getnameinfo</function></funcdef>
<paramdef>const struct sockaddr *sa</paramdef>
<paramdef>size_t salen</paramdef>
<paramdef>char *host</paramdef>
<paramdef>size_t hostlen</paramdef>
<paramdef>char *serv</paramdef>
<paramdef>size_t servlen</paramdef>
<paramdef>int flags</paramdef>
</funcprototype>
<paramdef>const struct sockaddr *<parameter>sa</parameter></paramdef>
<paramdef>size_t <parameter>salen</parameter></paramdef>
<paramdef>char *<parameter>host</parameter></paramdef>
<paramdef>size_t <parameter>hostlen</parameter></paramdef>
<paramdef>char *<parameter>serv</parameter></paramdef>
<paramdef>size_t <parameter>servlen</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<refsect1>
<title>DESCRIPTION</title>
<para> This function is equivalent to the <citerefentry>
<refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> function defined in RFC2133.
<function>lwres_getnameinfo()</function> returns the hostname for the
<type>struct sockaddr</type> <parameter>sa</parameter> which is
<parameter>salen</parameter> bytes long. The hostname is of length
<parameter>hostlen</parameter> and is returned via
<parameter>*host.</parameter> The maximum length of the hostname is
1025 bytes: <constant>NI_MAXHOST</constant>.</para>
<para>
This function is equivalent to the
<citerefentry>
<refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> function defined in RFC2133.
<function>lwres_getnameinfo()</function> returns the
hostname for the
<type>struct sockaddr</type> <parameter>sa</parameter> which
is
<parameter>salen</parameter> bytes long. The hostname is of
length
<parameter>hostlen</parameter> and is returned via
<parameter>*host.</parameter> The maximum length of the
hostname is
1025 bytes: <constant>NI_MAXHOST</constant>.
</para>
<para> The name of the service associated with the port number in
<parameter>sa</parameter> is returned in <parameter>*serv.</parameter>
It is <parameter>servlen</parameter> bytes long. The maximum length
of the service name is <constant>NI_MAXSERV</constant> - 32 bytes.
</para>
<para> The name of the service associated with the port number in
<parameter>sa</parameter> is returned in <parameter>*serv.</parameter>
It is <parameter>servlen</parameter> bytes long. The
maximum length
of the service name is <constant>NI_MAXSERV</constant> - 32
bytes.
</para>
<para> The <parameter>flags</parameter> argument sets the following
bits:
<variablelist>
<varlistentry><term><constant>NI_NOFQDN</constant></term>
<listitem>
<para>
A fully qualified domain name is not required for local hosts.
The local part of the fully qualified domain name is returned instead.
</para></listitem></varlistentry>
<varlistentry><term><constant>NI_NUMERICHOST</constant></term>
<listitem>
<para>
Return the address in numeric form, as if calling inet_ntop(),
instead of a host name.
</para></listitem></varlistentry>
<varlistentry><term><constant>NI_NAMEREQD</constant></term>
<listitem>
<para>
A name is required. If the hostname cannot be found in the DNS and
this flag is set, a non-zero error code is returned.
If the hostname is not found and the flag is not set, the
address is returned in numeric form.
</para></listitem></varlistentry>
<varlistentry><term><constant>NI_NUMERICSERV</constant></term>
<listitem>
<para>
The service name is returned as a digit string representing the port number.
</para></listitem></varlistentry>
<varlistentry><term><constant>NI_DGRAM</constant></term>
<listitem>
<para>
Specifies that the service being looked up is a datagram
service, and causes getservbyport() to be called with a second
argument of "udp" instead of its default of "tcp". This is required
for the few ports (512-514) that have different services for UDP and
TCP.
</para></listitem></varlistentry>
</variablelist>
</para>
</refsect1>
<para>
The <parameter>flags</parameter> argument sets the
following
bits:
<variablelist>
<varlistentry>
<term><constant>NI_NOFQDN</constant></term>
<listitem>
<para>
A fully qualified domain name is not required for local hosts.
The local part of the fully qualified domain name is returned
instead.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>NI_NUMERICHOST</constant></term>
<listitem>
<para>
Return the address in numeric form, as if calling inet_ntop(),
instead of a host name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>NI_NAMEREQD</constant></term>
<listitem>
<para>
A name is required. If the hostname cannot be found in the DNS
and
this flag is set, a non-zero error code is returned.
If the hostname is not found and the flag is not set, the
address is returned in numeric form.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>NI_NUMERICSERV</constant></term>
<listitem>
<para>
The service name is returned as a digit string representing the
port number.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>NI_DGRAM</constant></term>
<listitem>
<para>
Specifies that the service being looked up is a datagram
service, and causes getservbyport() to be called with a second
argument of "udp" instead of its default of "tcp". This is
required
for the few ports (512-514) that have different services for UDP
and
TCP.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
<function>lwres_getnameinfo()</function>
returns 0 on success or a non-zero error code if an error occurs.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>RFC2133</refentrytitle>
</citerefentry>,
<citerefentry>
<refentrytitle>getservbyport</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getnamebyaddr</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
<citerefentry>
<refentrytitle>lwres_net_ntop</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</refsect1>
<refsect1>
<title>BUGS</title>
<para>
RFC2133 fails to define what the nonzero return values of
<citerefentry>
<refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
are.
</para>
</refsect1>
</refentry>
<refsect1>
<title>RETURN VALUES</title>
<para><function>lwres_getnameinfo()</function>
returns 0 on success or a non-zero error code if an error occurs.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>RFC2133</refentrytitle>
</citerefentry>,
<citerefentry>
<refentrytitle>getservbyport</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_getnamebyaddr</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
<citerefentry>
<refentrytitle>lwres_net_ntop</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
<refsect1>
<title>BUGS</title>
<para>
RFC2133 fails to define what the nonzero return values of
<citerefentry>
<refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
are.
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

317
lib/lwres/man/lwres_getrrsetbyname.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,54 +17,69 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_getrrsetbyname.docbook,v 1.5 2005/04/07 03:50:03 marka Exp $ -->
<!-- $Id: lwres_getrrsetbyname.docbook,v 1.6 2005/05/11 05:55:40 sra Exp $ -->
<refentry>
<refentryinfo>
<refentryinfo>
<date>Oct 18, 2000</date>
</refentryinfo>
<date>Oct 18, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_getrrsetbyname</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_getrrsetbyname</refname>
<refname>lwres_freerrset</refname>
<refpurpose>retrieve DNS records</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<refmeta>
<refentrytitle>lwres_getrrsetbyname</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname>lwres_getrrsetbyname</refname>
<refname>lwres_freerrset</refname>
<refpurpose>retrieve DNS records</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
int
<function>lwres_getrrsetbyname</function></funcdef>
<paramdef>const char *hostname</paramdef>
<paramdef>unsigned int rdclass</paramdef>
<paramdef>unsigned int rdtype</paramdef>
<paramdef>unsigned int flags</paramdef>
<paramdef>struct rrsetinfo **res</paramdef>
</funcprototype>
<paramdef>const char *<parameter>hostname</parameter></paramdef>
<paramdef>unsigned int <parameter>rdclass</parameter></paramdef>
<paramdef>unsigned int <parameter>rdtype</parameter></paramdef>
<paramdef>unsigned int <parameter>flags</parameter></paramdef>
<paramdef>struct rrsetinfo **<parameter>res</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_freerrset</function></funcdef>
<paramdef>struct rrsetinfo *rrset</paramdef>
</funcprototype>
<paramdef>struct rrsetinfo *<parameter>rrset</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The following structures are used:
<programlisting>
<para>
The following structures are used:
</para>
<para><programlisting>
struct rdatainfo {
unsigned int rdi_length; /* length of data */
unsigned char *rdi_data; /* record data */
};
</programlisting>
</para>
<para><programlisting>
struct rrsetinfo {
unsigned int rri_flags; /* RRSET_VALIDATED... */
unsigned int rri_rdclass; /* class number */
@@ -75,134 +92,130 @@ struct rrsetinfo {
struct rdatainfo *rri_sigs; /* individual signatures */
};
</programlisting>
</para>
</refsynopsisdiv>
</para>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
<function>lwres_getrrsetbyname()</function>
gets a set of resource records associated with a
<parameter>hostname</parameter>,
<refsect1>
<title>DESCRIPTION</title>
<para><function>lwres_getrrsetbyname()</function>
gets a set of resource records associated with a
<parameter>hostname</parameter>, <parameter>class</parameter>,
and <parameter>type</parameter>.
<parameter>hostname</parameter> is a pointer a to
null-terminated string. The <parameter>flags</parameter> field
is currently unused and must be zero.
</para>
<para>
After a successful call to
<function>lwres_getrrsetbyname()</function>,
<parameter>*res</parameter> is a pointer to an
<type>rrsetinfo</type> structure, containing a list of one or
more <type>rdatainfo</type> structures containing resource
records and potentially another list of <type>rdatainfo</type>
structures containing SIG resource records associated with those
records. The members <constant>rri_rdclass</constant> and
<constant>rri_rdtype</constant> are copied from the parameters.
<constant>rri_ttl</constant> and <constant>rri_name</constant>
are properties of the obtained rrset. The resource records
contained in <constant>rri_rdatas</constant> and
<constant>rri_sigs</constant> are in uncompressed DNS wire
format. Properties of the rdataset are represented in the
<constant>rri_flags</constant> bitfield. If the RRSET_VALIDATED
bit is set, the data has been DNSSEC validated and the
signatures verified.
</para>
<para>
All of the information returned by
<function>lwres_getrrsetbyname()</function> is dynamically
allocated: the <constant>rrsetinfo</constant> and
<constant>rdatainfo</constant> structures, and the canonical
host name strings pointed to by the
<constant>rrsetinfo</constant>structure.
<parameter>class</parameter>,
Memory allocated for the dynamically allocated structures
created by a successful call to
<function>lwres_getrrsetbyname()</function> is released by
<function>lwres_freerrset()</function>.
and
<parameter>type</parameter>.
<parameter>rrset</parameter> is a pointer to a <type>struct
rrset</type> created by a call to
<function>lwres_getrrsetbyname()</function>.
</para>
<para></para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para><function>lwres_getrrsetbyname()</function>
returns zero on success, and one of the following error codes if
an error occurred:
<variablelist>
<parameter>hostname</parameter>
is
a pointer a to null-terminated string. The
<parameter>flags</parameter>
field is currently unused and must be zero.
</para>
<para>
After a successful call to
<function>lwres_getrrsetbyname()</function>,
<varlistentry>
<term><constant>ERRSET_NONAME</constant></term>
<listitem>
<para>
the name does not exist
</para>
</listitem>
</varlistentry>
<parameter>*res</parameter>
is a pointer to an
<type>rrsetinfo</type>
structure, containing a list of one or more
<type>rdatainfo</type>
structures containing resource records and potentially another list of
<type>rdatainfo</type>
structures containing SIG resource records
associated with those records.
The members
<constant>rri_rdclass</constant>
and
<constant>rri_rdtype</constant>
are copied from the parameters.
<constant>rri_ttl</constant>
and
<constant>rri_name</constant>
are properties of the obtained rrset.
The resource records contained in
<constant>rri_rdatas</constant>
and
<constant>rri_sigs</constant>
are in uncompressed DNS wire format.
Properties of the rdataset are represented in the
<constant>rri_flags</constant>
bitfield. If the RRSET_VALIDATED bit is set, the data has been DNSSEC
validated and the signatures verified.
</para>
<para>
All of the information returned by
<function>lwres_getrrsetbyname()</function>
is dynamically allocated: the
<constant>rrsetinfo</constant>
and
<constant>rdatainfo</constant>
structures,
and the canonical host name strings pointed to by the
<constant>rrsetinfo</constant>structure.
<varlistentry>
<term><constant>ERRSET_NODATA</constant></term>
<listitem>
<para>
the name exists, but does not have data of the desired type
</para>
</listitem>
</varlistentry>
Memory allocated for the dynamically allocated structures created by
a successful call to
<function>lwres_getrrsetbyname()</function>
is released by
<function>lwres_freerrset()</function>.
<varlistentry>
<term><constant>ERRSET_NOMEMORY</constant></term>
<listitem>
<para>
memory could not be allocated
</para>
</listitem>
</varlistentry>
<parameter>rrset</parameter>
is a pointer to a
<type>struct rrset</type>
created by a call to
<function>lwres_getrrsetbyname()</function>.
<varlistentry>
<term><constant>ERRSET_INVAL</constant></term>
<listitem>
<para>
a parameter is invalid
</para>
</listitem>
</varlistentry>
</para>
<para>
</para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
<function>lwres_getrrsetbyname()</function>
returns zero on success, and one of the following error
codes if an error occurred:
<variablelist>
<varlistentry>
<term><constant>ERRSET_FAIL</constant></term>
<listitem>
<para>
other failure
</para>
</listitem>
</varlistentry>
<varlistentry><term><constant>ERRSET_NONAME</constant></term>
<listitem><para>
the name does not exist
</para></listitem></varlistentry>
<varlistentry>
<term><constant/></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
<varlistentry><term><constant>ERRSET_NODATA</constant></term>
<listitem><para>
the name exists, but does not have data of the desired type
</para></listitem></varlistentry>
</variablelist>
<varlistentry><term><constant>ERRSET_NOMEMORY</constant></term>
<listitem><para>
memory could not be allocated
</para></listitem></varlistentry>
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
<varlistentry><term><constant>ERRSET_INVAL</constant></term>
<listitem><para>
a parameter is invalid
</para></listitem></varlistentry>
<varlistentry><term><constant>ERRSET_FAIL</constant></term>
<listitem><para>
other failure
</para></listitem></varlistentry>
<varlistentry><term><constant></constant></term>
<listitem><para>
</para></listitem></varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

382
lib/lwres/man/lwres_gnba.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,129 +17,146 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_gnba.docbook,v 1.6 2005/04/07 03:50:03 marka Exp $ -->
<!-- $Id: lwres_gnba.docbook,v 1.7 2005/05/11 05:55:40 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_gnba</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres_gnba</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_gnbarequest_render</refname>
<refname>lwres_gnbaresponse_render</refname>
<refname>lwres_gnbarequest_parse</refname>
<refname>lwres_gnbaresponse_parse</refname>
<refname>lwres_gnbaresponse_free</refname>
<refname>lwres_gnbarequest_free</refname>
<refpurpose>lightweight resolver getnamebyaddress message handling</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<refnamediv>
<refname>lwres_gnbarequest_render</refname>
<refname>lwres_gnbaresponse_render</refname>
<refname>lwres_gnbarequest_parse</refname>
<refname>lwres_gnbaresponse_parse</refname>
<refname>lwres_gnbaresponse_free</refname>
<refname>lwres_gnbarequest_free</refname>
<refpurpose>lightweight resolver getnamebyaddress message handling</refpurpose>
</refnamediv>
<funcsynopsis>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;lwres/lwres.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_gnbarequest_render</function>
</funcdef>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_gnbarequest_t *<parameter>req</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_gnbarequest_t *<parameter>req</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_gnbaresponse_render</function>
</funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_gnbaresponse_t *req</paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef>
<paramdef>lwres_buffer_t *b</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_gnbaresponse_t *<parameter>req</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_gnbarequest_parse</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef>
<paramdef>lwres_gnbarequest_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_gnbaresponse_parse</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef>
<paramdef>lwres_gnbaresponse_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_gnbaresponse_free</function>
</funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_gnbaresponse_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_gnbarequest_free</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_gnbarequest_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
These are low-level routines for creating and parsing
lightweight resolver address-to-name lookup request and
response messages.
</para>
<para>
There are four main functions for the getnamebyaddr opcode.
One render function converts a getnamebyaddr request structure &mdash;
<type>lwres_gnbarequest_t</type> &mdash;
to the lightweight resolver's canonical format.
It is complemented by a parse function that converts a packet in this
canonical format to a getnamebyaddr request structure.
Another render function converts the getnamebyaddr response structure &mdash;
<type>lwres_gnbaresponse_t</type>
to the canonical format.
This is complemented by a parse function which converts a packet in
canonical format to a getnamebyaddr response structure.
</para>
<para>
These structures are defined in
<filename>lwres/lwres.h</filename>.
They are shown below.
<programlisting>
<refsect1>
<title>DESCRIPTION</title>
<para>
These are low-level routines for creating and parsing
lightweight resolver address-to-name lookup request and
response messages.
</para>
<para>
There are four main functions for the getnamebyaddr opcode.
One render function converts a getnamebyaddr request structure &mdash;
<type>lwres_gnbarequest_t</type> &mdash;
to the lightweight resolver's canonical format.
It is complemented by a parse function that converts a packet in this
canonical format to a getnamebyaddr request structure.
Another render function converts the getnamebyaddr response structure
&mdash;
<type>lwres_gnbaresponse_t</type>
to the canonical format.
This is complemented by a parse function which converts a packet in
canonical format to a getnamebyaddr response structure.
</para>
<para>
These structures are defined in
<filename>lwres/lwres.h</filename>.
They are shown below.
</para>
<para><programlisting>
#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U
</programlisting>
</para>
<para><programlisting>
typedef struct {
lwres_uint32_t flags;
lwres_addr_t addr;
} lwres_gnbarequest_t;
</programlisting>
</para>
<para><programlisting>
typedef struct {
lwres_uint32_t flags;
lwres_uint16_t naliases;
@@ -149,111 +168,92 @@ typedef struct {
size_t baselen;
} lwres_gnbaresponse_t;
</programlisting>
</para>
<para>
<function>lwres_gnbarequest_render()</function>
uses resolver context
<varname>ctx</varname>
to convert getnamebyaddr request structure
<varname>req</varname>
to canonical format.
The packet header structure
<varname>pkt</varname>
is initialised and transferred to
buffer
<varname>b</varname>.
The contents of
<varname>*req</varname>
are then appended to the buffer in canonical format.
<function>lwres_gnbaresponse_render()</function>
performs the same task, except it converts a getnamebyaddr response structure
<type>lwres_gnbaresponse_t</type>
to the lightweight resolver's canonical format.
</para>
<para>
<function>lwres_gnbarequest_parse()</function>
uses context
<varname>ctx</varname>
to convert the contents of packet
<varname>pkt</varname>
to a
<type>lwres_gnbarequest_t</type>
structure.
Buffer
<varname>b</varname>
provides space to be used for storing this structure.
When the function succeeds, the resulting
<type>lwres_gnbarequest_t</type>
is made available through
<varname>*structp</varname>.
<function>lwres_gnbaresponse_parse()</function>
offers the same semantics as
<function>lwres_gnbarequest_parse()</function>
except it yields a
<type>lwres_gnbaresponse_t</type>
structure.
</para>
<para>
<function>lwres_gnbaresponse_free()</function>
and
<function>lwres_gnbarequest_free()</function>
release the memory in resolver context
<varname>ctx</varname>
that was allocated to the
<type>lwres_gnbaresponse_t</type>
or
<type>lwres_gnbarequest_t</type>
structures referenced via
<varname>structp</varname>.
Any memory associated with ancillary buffers and strings for those
structures is also discarded.
</para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
The getnamebyaddr opcode functions
<function>lwres_gnbarequest_render()</function>,
<function>lwres_gnbaresponse_render()</function>
<function>lwres_gnbarequest_parse()</function>
and
<function>lwres_gnbaresponse_parse()</function>
all return
<errorcode>LWRES_R_SUCCESS</errorcode>
on success.
They return
<errorcode>LWRES_R_NOMEMORY</errorcode>
if memory allocation fails.
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
is returned if the available space in the buffer
<varname>b</varname>
is too small to accommodate the packet header or the
<type>lwres_gnbarequest_t</type>
and
<type>lwres_gnbaresponse_t</type>
structures.
<function>lwres_gnbarequest_parse()</function>
and
<function>lwres_gnbaresponse_parse()</function>
will return
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
if the buffer is not empty after decoding the received packet.
These functions will return
<errorcode>LWRES_R_FAILURE</errorcode>
if
<structfield>pktflags</structfield>
in the packet header structure
<type>lwres_lwpacket_t</type>
indicate that the packet is not a response to an earlier query.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>lwres_packet</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry>
</para>
<para><function>lwres_gnbarequest_render()</function>
uses resolver context <varname>ctx</varname> to convert
getnamebyaddr request structure <varname>req</varname> to
canonical format. The packet header structure
<varname>pkt</varname> is initialised and transferred to buffer
<varname>b</varname>. The contents of <varname>*req</varname>
are then appended to the buffer in canonical format.
<function>lwres_gnbaresponse_render()</function> performs the
same task, except it converts a getnamebyaddr response structure
<type>lwres_gnbaresponse_t</type> to the lightweight resolver's
canonical format.
</para>
<para><function>lwres_gnbarequest_parse()</function>
uses context <varname>ctx</varname> to convert the contents of
packet <varname>pkt</varname> to a
<type>lwres_gnbarequest_t</type> structure. Buffer
<varname>b</varname> provides space to be used for storing this
structure. When the function succeeds, the resulting
<type>lwres_gnbarequest_t</type> is made available through
<varname>*structp</varname>.
<function>lwres_gnbaresponse_parse()</function> offers the same
semantics as <function>lwres_gnbarequest_parse()</function>
except it yields a <type>lwres_gnbaresponse_t</type> structure.
</para>
<para><function>lwres_gnbaresponse_free()</function>
and <function>lwres_gnbarequest_free()</function> release the
memory in resolver context <varname>ctx</varname> that was
allocated to the <type>lwres_gnbaresponse_t</type> or
<type>lwres_gnbarequest_t</type> structures referenced via
<varname>structp</varname>. Any memory associated with
ancillary buffers and strings for those structures is also
discarded.
</para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
The getnamebyaddr opcode functions
<function>lwres_gnbarequest_render()</function>,
<function>lwres_gnbaresponse_render()</function>
<function>lwres_gnbarequest_parse()</function>
and
<function>lwres_gnbaresponse_parse()</function>
all return
<errorcode>LWRES_R_SUCCESS</errorcode>
on success.
They return
<errorcode>LWRES_R_NOMEMORY</errorcode>
if memory allocation fails.
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
is returned if the available space in the buffer
<varname>b</varname>
is too small to accommodate the packet header or the
<type>lwres_gnbarequest_t</type>
and
<type>lwres_gnbaresponse_t</type>
structures.
<function>lwres_gnbarequest_parse()</function>
and
<function>lwres_gnbaresponse_parse()</function>
will return
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
if the buffer is not empty after decoding the received packet.
These functions will return
<errorcode>LWRES_R_FAILURE</errorcode>
if
<structfield>pktflags</structfield>
in the packet header structure
<type>lwres_lwpacket_t</type>
indicate that the packet is not a response to an earlier query.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

204
lib/lwres/man/lwres_hstrerror.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,110 +17,134 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_hstrerror.docbook,v 1.6 2005/04/07 03:50:03 marka Exp $ -->
<!-- $Id: lwres_hstrerror.docbook,v 1.7 2005/05/11 05:55:40 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_hstrerror</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres_hstrerror</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_herror</refname>
<refname>lwres_hstrerror</refname>
<refpurpose>lightweight resolver error message generation</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname>lwres_herror</refname>
<refname>lwres_hstrerror</refname>
<refpurpose>lightweight resolver error message generation</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_herror</function></funcdef>
<paramdef>const char *s</paramdef>
</funcprototype>
<paramdef>const char *<parameter>s</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
const char *
<function>lwres_hstrerror</function></funcdef>
<paramdef>int err</paramdef>
</funcprototype>
<paramdef>int <parameter>err</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<refsect1>
<title>DESCRIPTION</title>
<para>
<function>lwres_herror()</function> prints the string
<parameter>s</parameter> on <type>stderr</type> followed by the string
generated by <function>lwres_hstrerror()</function> for the error code
stored in the global variable <constant>lwres_h_errno</constant>.
</para>
<para><function>lwres_herror()</function>
prints the string <parameter>s</parameter> on
<type>stderr</type> followed by the string generated by
<function>lwres_hstrerror()</function> for the error code stored
in the global variable <constant>lwres_h_errno</constant>.
</para>
<para>
<function>lwres_hstrerror()</function> returns an appropriate string
for the error code gievn by <parameter>err</parameter>. The values of
the error codes and messages are as follows:
<para><function>lwres_hstrerror()</function>
returns an appropriate string for the error code gievn by
<parameter>err</parameter>. The values of the error codes and
messages are as follows:
<variablelist>
<varlistentry><term><errorcode>NETDB_SUCCESS</errorcode></term>
<listitem>
<para>
<errorname>Resolver Error 0 (no error)</errorname>
</para></listitem></varlistentry>
<varlistentry><term><errorcode>HOST_NOT_FOUND</errorcode></term>
<listitem>
<para>
<errorname>Unknown host</errorname>
</para></listitem></varlistentry>
<varlistentry><term><errorcode>TRY_AGAIN</errorcode></term>
<listitem>
<para>
<errorname>Host name lookup failure</errorname>
</para></listitem></varlistentry>
<varlistentry><term><errorcode>NO_RECOVERY</errorcode></term>
<listitem>
<para>
<errorname>Unknown server error</errorname>
</para></listitem></varlistentry>
<varlistentry><term><errorcode>NO_DATA</errorcode></term>
<listitem>
<para>
<errorname>No address associated with name</errorname>
</para></listitem></varlistentry>
</variablelist>
</para>
</refsect1>
<variablelist>
<varlistentry>
<term><errorcode>NETDB_SUCCESS</errorcode></term>
<listitem>
<para><errorname>Resolver Error 0 (no error)</errorname>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>HOST_NOT_FOUND</errorcode></term>
<listitem>
<para><errorname>Unknown host</errorname>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>TRY_AGAIN</errorcode></term>
<listitem>
<para><errorname>Host name lookup failure</errorname>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>NO_RECOVERY</errorcode></term>
<listitem>
<para><errorname>Unknown server error</errorname>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>NO_DATA</errorcode></term>
<listitem>
<para><errorname>No address associated with name</errorname>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
The string <errorname>Unknown resolver error</errorname> is returned by
<function>lwres_hstrerror()</function>
when the value of
<constant>lwres_h_errno</constant>
is not a valid error code.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>herror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<refsect1>
<title>RETURN VALUES</title>
<para>
The string <errorname>Unknown resolver error</errorname> is returned by
<function>lwres_hstrerror()</function>
when the value of
<constant>lwres_h_errno</constant>
is not a valid error code.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>herror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
<citerefentry>
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

155
lib/lwres/man/lwres_inetntop.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,85 +17,102 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_inetntop.docbook,v 1.5 2005/04/07 03:50:03 marka Exp $ -->
<!-- $Id: lwres_inetntop.docbook,v 1.6 2005/05/11 05:55:40 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_inetntop</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres_inetntop</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_net_ntop</refname>
<refpurpose>lightweight resolver IP address presentation</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname>lwres_net_ntop</refname>
<refpurpose>lightweight resolver IP address presentation</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/net.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
const char *
<function>lwres_net_ntop</function></funcdef>
<paramdef>int af</paramdef>
<paramdef>const void *src</paramdef>
<paramdef>char *dst</paramdef>
<paramdef>size_t size</paramdef>
</funcprototype>
<paramdef>int <parameter>af</parameter></paramdef>
<paramdef>const void *<parameter>src</parameter></paramdef>
<paramdef>char *<parameter>dst</parameter></paramdef>
<paramdef>size_t <parameter>size</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<refsect1>
<title>DESCRIPTION</title>
<para>
<function>lwres_net_ntop()</function> converts an IP address of
protocol family <parameter>af</parameter> &mdash; IPv4 or IPv6 &mdash;
at location <parameter>src</parameter> from network format to its
conventional representation as a string. For IPv4 addresses, that
string would be a dotted-decimal. An IPv6 address would be
represented in colon notation as described in RFC1884.
</para>
<para><function>lwres_net_ntop()</function>
converts an IP address of protocol family
<parameter>af</parameter> &mdash; IPv4 or IPv6 &mdash; at
location <parameter>src</parameter> from network format to its
conventional representation as a string. For IPv4 addresses,
that string would be a dotted-decimal. An IPv6 address would be
represented in colon notation as described in RFC1884.
</para>
<para>
The generated string is copied to <parameter>dst</parameter> provided
<parameter>size</parameter> indicates it is long enough to store the
ASCII representation of the address.
</para>
<para>
The generated string is copied to <parameter>dst</parameter>
provided
<parameter>size</parameter> indicates it is long enough to
store the
ASCII representation of the address.
</para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
If successful, the function returns <parameter>dst</parameter>:
a pointer to a string containing the presentation format of the
address. <function>lwres_net_ntop()</function> returns
<type>NULL</type> and sets the global variable
<constant>errno</constant> to <errorcode>EAFNOSUPPORT</errorcode> if
the protocol family given in <parameter>af</parameter> is not
supported.
</para>
<para>
If successful, the function returns <parameter>dst</parameter>:
a pointer to a string containing the presentation format of the
address. <function>lwres_net_ntop()</function> returns
<type>NULL</type> and sets the global variable
<constant>errno</constant> to <errorcode>EAFNOSUPPORT</errorcode> if
the protocol family given in <parameter>af</parameter> is
not
supported.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>RFC1884</refentrytitle>
</citerefentry>,
<citerefentry>
<refentrytitle>inet_ntop</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>RFC1884</refentrytitle>
</citerefentry>,
<citerefentry>
<refentrytitle>inet_ntop</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

368
lib/lwres/man/lwres_noop.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,215 +17,237 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_noop.docbook,v 1.6 2005/04/07 03:50:03 marka Exp $ -->
<!-- $Id: lwres_noop.docbook,v 1.7 2005/05/11 05:55:40 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_noop</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres_noop</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_nooprequest_render</refname>
<refname>lwres_noopresponse_render</refname>
<refname>lwres_nooprequest_parse</refname>
<refname>lwres_noopresponse_parse</refname>
<refname>lwres_noopresponse_free</refname>
<refname>lwres_nooprequest_free</refname>
<refpurpose>lightweight resolver no-op message handling</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname>lwres_nooprequest_render</refname>
<refname>lwres_noopresponse_render</refname>
<refname>lwres_nooprequest_parse</refname>
<refname>lwres_noopresponse_parse</refname>
<refname>lwres_noopresponse_free</refname>
<refname>lwres_nooprequest_free</refname>
<refpurpose>lightweight resolver no-op message handling</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_nooprequest_render</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_nooprequest_t *req</paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef>
<paramdef>lwres_buffer_t *b</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_nooprequest_t *<parameter>req</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_noopresponse_render</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_noopresponse_t *req</paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef>
<paramdef>lwres_buffer_t *b</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_noopresponse_t *<parameter>req</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_nooprequest_parse</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef>
<paramdef>lwres_nooprequest_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_noopresponse_parse</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef>
<paramdef>lwres_noopresponse_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_noopresponse_free</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_noopresponse_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
void
<function>lwres_nooprequest_free</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_nooprequest_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
These are low-level routines for creating and parsing
lightweight resolver no-op request and response messages.
</para>
<para>
The no-op message is analogous to a <command>ping</command> packet:
a packet is sent to the resolver daemon and is simply echoed back.
The opcode is intended to allow a client to determine if the server is
operational or not.
</para>
<para>
There are four main functions for the no-op opcode.
One render function converts a no-op request structure &mdash;
<type>lwres_nooprequest_t</type> &mdash;
to the lighweight resolver's canonical format.
It is complemented by a parse function that converts a packet in this
canonical format to a no-op request structure.
Another render function converts the no-op response structure &mdash;
<type>lwres_noopresponse_t</type>
to the canonical format.
This is complemented by a parse function which converts a packet in
canonical format to a no-op response structure.
</para>
<para>
These structures are defined in
<filename>lwres/lwres.h</filename>.
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
These are low-level routines for creating and parsing
lightweight resolver no-op request and response messages.
</para>
<para>
The no-op message is analogous to a <command>ping</command>
packet:
a packet is sent to the resolver daemon and is simply echoed back.
The opcode is intended to allow a client to determine if the server is
operational or not.
</para>
<para>
There are four main functions for the no-op opcode.
One render function converts a no-op request structure &mdash;
<type>lwres_nooprequest_t</type> &mdash;
to the lighweight resolver's canonical format.
It is complemented by a parse function that converts a packet in this
canonical format to a no-op request structure.
Another render function converts the no-op response structure &mdash;
<type>lwres_noopresponse_t</type>
to the canonical format.
This is complemented by a parse function which converts a packet in
canonical format to a no-op response structure.
</para>
<para>
These structures are defined in
<filename>lwres/lwres.h</filename>.
They are shown below.
<programlisting>
They are shown below.
</para>
<para><programlisting>
#define LWRES_OPCODE_NOOP 0x00000000U
</programlisting>
</para>
<para><programlisting>
typedef struct {
lwres_uint16_t datalength;
unsigned char *data;
} lwres_nooprequest_t;
</programlisting>
</para>
<para><programlisting>
typedef struct {
lwres_uint16_t datalength;
unsigned char *data;
} lwres_noopresponse_t;
</programlisting>
Although the structures have different types, they are identical.
This is because the no-op opcode simply echos whatever data was sent:
the response is therefore identical to the request.
</para>
</para>
<para>
Although the structures have different types, they are identical.
This is because the no-op opcode simply echos whatever data was sent:
the response is therefore identical to the request.
</para>
<para>
<function>lwres_nooprequest_render()</function> uses resolver
context <parameter>ctx</parameter> to convert no-op request structure
<parameter>req</parameter> to canonical format. The packet header
structure <parameter>pkt</parameter> is initialised and transferred to
buffer <parameter>b</parameter>. The contents of
<parameter>*req</parameter> are then appended to the buffer in
canonical format. <function>lwres_noopresponse_render()</function>
performs the same task, except it converts a no-op response structure
<type>lwres_noopresponse_t</type> to the lightweight resolver's
canonical format.
</para>
<para><function>lwres_nooprequest_render()</function>
uses resolver context <parameter>ctx</parameter> to convert
no-op request structure <parameter>req</parameter> to canonical
format. The packet header structure <parameter>pkt</parameter>
is initialised and transferred to buffer
<parameter>b</parameter>. The contents of
<parameter>*req</parameter> are then appended to the buffer in
canonical format.
<function>lwres_noopresponse_render()</function> performs the
same task, except it converts a no-op response structure
<type>lwres_noopresponse_t</type> to the lightweight resolver's
canonical format.
</para>
<para>
<function>lwres_nooprequest_parse()</function> uses context
<parameter>ctx</parameter> to convert the contents of packet
<parameter>pkt</parameter> to a <type>lwres_nooprequest_t</type>
structure. Buffer <parameter>b</parameter> provides space to be used
for storing this structure. When the function succeeds, the resulting
<type>lwres_nooprequest_t</type> is made available through
<parameter>*structp</parameter>.
<function>lwres_noopresponse_parse()</function> offers the same
semantics as <function>lwres_nooprequest_parse()</function> except it
yields a <type>lwres_noopresponse_t</type> structure.
</para>
<para><function>lwres_nooprequest_parse()</function>
uses context <parameter>ctx</parameter> to convert the contents
of packet <parameter>pkt</parameter> to a
<type>lwres_nooprequest_t</type> structure. Buffer
<parameter>b</parameter> provides space to be used for storing
this structure. When the function succeeds, the resulting
<type>lwres_nooprequest_t</type> is made available through
<parameter>*structp</parameter>.
<function>lwres_noopresponse_parse()</function> offers the same
semantics as <function>lwres_nooprequest_parse()</function>
except it yields a <type>lwres_noopresponse_t</type> structure.
</para>
<para>
<function>lwres_noopresponse_free()</function> and
<function>lwres_nooprequest_free()</function> release the memory in
resolver context <parameter>ctx</parameter> that was allocated to the
<type>lwres_noopresponse_t</type> or <type>lwres_nooprequest_t</type>
structures referenced via <parameter>structp</parameter>.
</para>
<para><function>lwres_noopresponse_free()</function>
and <function>lwres_nooprequest_free()</function> release the
memory in resolver context <parameter>ctx</parameter> that was
allocated to the <type>lwres_noopresponse_t</type> or
<type>lwres_nooprequest_t</type> structures referenced via
<parameter>structp</parameter>.
</para>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
The no-op opcode functions
<function>lwres_nooprequest_render()</function>,
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para>
The no-op opcode functions
<function>lwres_nooprequest_render()</function>,
<function>lwres_noopresponse_render()</function>
<function>lwres_nooprequest_parse()</function>
and
<function>lwres_noopresponse_parse()</function>
all return
<errorcode>LWRES_R_SUCCESS</errorcode>
on success.
They return
<errorcode>LWRES_R_NOMEMORY</errorcode>
if memory allocation fails.
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
is returned if the available space in the buffer
<parameter>b</parameter>
is too small to accommodate the packet header or the
<type>lwres_nooprequest_t</type>
and
<type>lwres_noopresponse_t</type>
structures.
<function>lwres_nooprequest_parse()</function>
and
<function>lwres_noopresponse_parse()</function>
will return
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
if the buffer is not empty after decoding the received packet.
These functions will return
<errorcode>LWRES_R_FAILURE</errorcode>
if
<constant>pktflags</constant>
in the packet header structure
<type>lwres_lwpacket_t</type>
indicate that the packet is not a response to an earlier query.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>lwres_packet</refentrytitle><manvolnum>3
</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
<function>lwres_noopresponse_render()</function>
<function>lwres_nooprequest_parse()</function>
and
<function>lwres_noopresponse_parse()</function>
all return
<errorcode>LWRES_R_SUCCESS</errorcode>
on success.
They return
<errorcode>LWRES_R_NOMEMORY</errorcode>
if memory allocation fails.
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
is returned if the available space in the buffer
<parameter>b</parameter>
is too small to accommodate the packet header or the
<type>lwres_nooprequest_t</type>
and
<type>lwres_noopresponse_t</type>
structures.
<function>lwres_nooprequest_parse()</function>
and
<function>lwres_noopresponse_parse()</function>
will return
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
if the buffer is not empty after decoding the received packet.
These functions will return
<errorcode>LWRES_R_FAILURE</errorcode>
if
<constant>pktflags</constant>
in the packet header structure
<type>lwres_lwpacket_t</type>
indicate that the packet is not a response to an earlier query.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

409
lib/lwres/man/lwres_packet.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,56 +17,70 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_packet.docbook,v 1.8 2005/04/07 03:50:04 marka Exp $ -->
<!-- $Id: lwres_packet.docbook,v 1.9 2005/05/11 05:55:41 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_packet</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres_packet</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_lwpacket_renderheader</refname>
<refname>lwres_lwpacket_parseheader</refname>
<refpurpose>lightweight resolver packet handling functions</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname>lwres_lwpacket_renderheader</refname>
<refname>lwres_lwpacket_parseheader</refname>
<refpurpose>lightweight resolver packet handling functions</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/lwpacket.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_lwpacket_renderheader</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_lwpacket_parseheader</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
These functions rely on a
<type>struct lwres_lwpacket</type>
which is defined in
<filename>lwres/lwpacket.h</filename>.
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
These functions rely on a
<type>struct lwres_lwpacket</type>
which is defined in
<filename>lwres/lwpacket.h</filename>.
</para>
<programlisting>
<para><programlisting>
typedef struct lwres_lwpacket lwres_lwpacket_t;
</programlisting>
</para>
<para><programlisting>
struct lwres_lwpacket {
lwres_uint32_t length;
lwres_uint16_t version;
@@ -77,142 +93,197 @@ struct lwres_lwpacket {
lwres_uint16_t authlength;
};
</programlisting>
</para>
</para>
<para>
The elements of this structure are:
<variablelist>
<varlistentry><term><constant>length</constant></term>
<listitem>
<para>
the overall packet length, including the entire packet header.
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
calls.
</para></listitem></varlistentry>
<varlistentry><term><constant>version</constant></term>
<listitem>
<para>
the header format. There is currently only one format,
<type>LWRES_LWPACKETVERSION_0</type>.
<para>
The elements of this structure are:
<variablelist>
<varlistentry>
<term><constant>length</constant></term>
<listitem>
<para>
the overall packet length, including the entire packet header.
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
calls.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>version</constant></term>
<listitem>
<para>
the header format. There is currently only one format,
<type>LWRES_LWPACKETVERSION_0</type>.
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
calls.
</para></listitem></varlistentry>
<varlistentry><term><constant>pktflags</constant></term>
<listitem>
<para>
library-defined flags for this packet: for instance whether the packet
is a request or a reply. Flag values can be set, but not defined by
the caller.
This field is filled in by the application wit the exception of the
LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the
lwres_gabn_*() and lwres_gnba_*() calls.
</para></listitem></varlistentry>
<varlistentry><term><constant>serial</constant></term>
<listitem>
<para>
is set by the requestor and is returned in all replies. If two or more
packets from the same source have the same serial number and are from
the same source, they are assumed to be duplicates and the latter ones
may be dropped.
This field must be set by the application.
</para></listitem></varlistentry>
<varlistentry><term><constant>opcode</constant></term>
<listitem>
<para>
indicates the operation.
Opcodes between 0x00000000 and 0x03ffffff are
reserved for use by the lightweight resolver library. Opcodes between
0x04000000 and 0xffffffff are application defined.
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
calls.
</para></listitem></varlistentry>
<varlistentry><term><constant>result</constant></term>
<listitem>
<para>
is only valid for replies.
Results between 0x04000000 and 0xffffffff are application defined.
Results between 0x00000000 and 0x03ffffff are reserved for library use.
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
calls.
</para></listitem></varlistentry>
<varlistentry><term><constant>recvlength</constant></term>
<listitem>
<para>
is the maximum buffer size that the receiver can handle on requests
and the size of the buffer needed to satisfy a request when the buffer
is too large for replies.
This field is supplied by the application.
</para></listitem></varlistentry>
<varlistentry><term><constant>authtype</constant></term>
<listitem>
<para>
defines the packet level authentication that is used.
Authorisation types between 0x1000 and 0xffff are application defined
and types between 0x0000 and 0x0fff are reserved for library use.
Currently these are not used and must be zero.
</para></listitem></varlistentry>
<varlistentry><term><constant>authlen</constant></term>
<listitem>
<para>
gives the length of the authentication data.
Since packet authentication is currently not used, this must be zero.
</para></listitem></varlistentry>
</variablelist>
</para>
<para>
The following opcodes are currently defined:
<variablelist>
<varlistentry><term><constant>NOOP</constant></term>
<listitem>
<para>
Success is always returned and the packet contents are echoed.
The lwres_noop_*() functions should be used for this type.
</para></listitem></varlistentry>
<varlistentry><term><constant>GETADDRSBYNAME</constant></term>
<listitem>
<para>
returns all known addresses for a given name.
The lwres_gabn_*() functions should be used for this type.
</para></listitem></varlistentry>
<varlistentry><term><constant>GETNAMEBYADDR</constant></term>
<listitem>
<para>
return the hostname for the given address.
The lwres_gnba_*() functions should be used for this type.
</para></listitem></varlistentry>
</variablelist>
</para>
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
calls.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>pktflags</constant></term>
<listitem>
<para>
library-defined flags for this packet: for instance whether the
packet
is a request or a reply. Flag values can be set, but not defined
by
the caller.
This field is filled in by the application wit the exception of
the
LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in
the
lwres_gabn_*() and lwres_gnba_*() calls.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>serial</constant></term>
<listitem>
<para>
is set by the requestor and is returned in all replies. If two
or more
packets from the same source have the same serial number and are
from
the same source, they are assumed to be duplicates and the
latter ones
may be dropped.
This field must be set by the application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>opcode</constant></term>
<listitem>
<para>
indicates the operation.
Opcodes between 0x00000000 and 0x03ffffff are
reserved for use by the lightweight resolver library. Opcodes
between
0x04000000 and 0xffffffff are application defined.
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
calls.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>result</constant></term>
<listitem>
<para>
is only valid for replies.
Results between 0x04000000 and 0xffffffff are application
defined.
Results between 0x00000000 and 0x03ffffff are reserved for
library use.
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
calls.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>recvlength</constant></term>
<listitem>
<para>
is the maximum buffer size that the receiver can handle on
requests
and the size of the buffer needed to satisfy a request when the
buffer
is too large for replies.
This field is supplied by the application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>authtype</constant></term>
<listitem>
<para>
defines the packet level authentication that is used.
Authorisation types between 0x1000 and 0xffff are application
defined
and types between 0x0000 and 0x0fff are reserved for library
use.
Currently these are not used and must be zero.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>authlen</constant></term>
<listitem>
<para>
gives the length of the authentication data.
Since packet authentication is currently not used, this must be
zero.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The following opcodes are currently defined:
<variablelist>
<varlistentry>
<term><constant>NOOP</constant></term>
<listitem>
<para>
Success is always returned and the packet contents are echoed.
The lwres_noop_*() functions should be used for this type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GETADDRSBYNAME</constant></term>
<listitem>
<para>
returns all known addresses for a given name.
The lwres_gabn_*() functions should be used for this type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GETNAMEBYADDR</constant></term>
<listitem>
<para>
return the hostname for the given address.
The lwres_gnba_*() functions should be used for this type.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<function>lwres_lwpacket_renderheader()</function> transfers the
contents of lightweight resolver packet structure
<type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in network
byte order to the lightweight resolver buffer,
<parameter>*b</parameter>.
</para>
<para><function>lwres_lwpacket_renderheader()</function>
transfers the contents of lightweight resolver packet structure
<type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in
network byte order to the lightweight resolver buffer,
<parameter>*b</parameter>.
</para>
<para>
<function>lwres_lwpacket_parseheader()</function> performs the
converse operation. It transfers data in network byte order from
buffer <parameter>*b</parameter> to resolver packet
<parameter>*pkt</parameter>. The contents of the buffer
<parameter>b</parameter> should correspond to a
<type>lwres_lwpacket_t</type>.
</para>
<para><function>lwres_lwpacket_parseheader()</function>
performs the converse operation. It transfers data in network
byte order from buffer <parameter>*b</parameter> to resolver
packet <parameter>*pkt</parameter>. The contents of the buffer
<parameter>b</parameter> should correspond to a
<type>lwres_lwpacket_t</type>.
</para>
</refsect1>
</refsect1>
<refsect1>
<title>RETURN VALUES</title>
<para> Successful calls to
<function>lwres_lwpacket_renderheader()</function> and
<function>lwres_lwpacket_parseheader()</function> return
<errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient
space to copy data between the buffer <parameter>*b</parameter> and
lightweight resolver packet <parameter>*pkt</parameter> both functions
return <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>.
</para>
<refsect1>
<title>RETURN VALUES</title>
<para>
Successful calls to
<function>lwres_lwpacket_renderheader()</function> and
<function>lwres_lwpacket_parseheader()</function> return
<errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient
space to copy data between the buffer <parameter>*b</parameter> and
lightweight resolver packet <parameter>*pkt</parameter> both
functions
return <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>.
</para>
</refsect1>
</refentry>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

343
lib/lwres/man/lwres_resutil.docbook
View File

@@ -1,4 +1,6 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium.
@@ -15,104 +17,114 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_resutil.docbook,v 1.7 2005/04/07 03:50:04 marka Exp $ -->
<!-- $Id: lwres_resutil.docbook,v 1.8 2005/05/11 05:55:41 sra Exp $ -->
<refentry>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_resutil</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres_resutil</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_string_parse</refname>
<refname>lwres_addr_parse</refname>
<refname>lwres_getaddrsbyname</refname>
<refname>lwres_getnamebyaddr</refname>
<refpurpose>lightweight resolver utility functions</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refnamediv>
<refname>lwres_string_parse</refname>
<refname>lwres_addr_parse</refname>
<refname>lwres_getaddrsbyname</refname>
<refname>lwres_getnamebyaddr</refname>
<refpurpose>lightweight resolver utility functions</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_string_parse</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>char **c</paramdef>
<paramdef>lwres_uint16_t *len</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>char **<parameter>c</parameter></paramdef>
<paramdef>lwres_uint16_t *<parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_addr_parse</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef>
<paramdef>lwres_addr_t *addr</paramdef>
</funcprototype>
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_addr_t *<parameter>addr</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_getaddrsbyname</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>const char *name</paramdef>
<paramdef>lwres_uint32_t addrtypes</paramdef>
<paramdef>lwres_gabnresponse_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>lwres_uint32_t <parameter>addrtypes</parameter></paramdef>
<paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>
<funcdef>
lwres_result_t
<function>lwres_getnamebyaddr</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef>
<paramdef>lwres_uint32_t addrtype</paramdef>
<paramdef>lwres_uint16_t addrlen</paramdef>
<paramdef>const unsigned char *addr</paramdef>
<paramdef>lwres_gnbaresponse_t **structp</paramdef>
</funcprototype>
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_uint32_t <parameter>addrtype</parameter></paramdef>
<paramdef>lwres_uint16_t <parameter>addrlen</parameter></paramdef>
<paramdef>const unsigned char *<parameter>addr</parameter></paramdef>
<paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<refsect1>
<title>DESCRIPTION</title>
<para>
<function>lwres_string_parse()</function> retrieves a DNS-encoded
string starting the current pointer of lightweight resolver buffer
<parameter>b</parameter>: i.e. <constant>b-&gt;current</constant>.
When the function returns, the address of the first byte of the
encoded string is returned via <parameter>*c</parameter> and the
length of that string is given by <parameter>*len</parameter>. The
buffer's current pointer is advanced to point at the character
following the string length, the encoded string, and the trailing
<type>NULL</type> character.
</para>
<para><function>lwres_string_parse()</function>
retrieves a DNS-encoded string starting the current pointer of
lightweight resolver buffer <parameter>b</parameter>: i.e.
<constant>b-&gt;current</constant>. When the function returns,
the address of the first byte of the encoded string is returned
via <parameter>*c</parameter> and the length of that string is
given by <parameter>*len</parameter>. The buffer's current
pointer is advanced to point at the character following the
string length, the encoded string, and the trailing
<type>NULL</type> character.
</para>
<para>
<function>lwres_addr_parse()</function> extracts an address from the
buffer <parameter>b</parameter>. The buffer's current pointer
<constant>b-&gt;current</constant> is presumed to point at an encoded
address: the address preceded by a 32-bit protocol family identifier
and a 16-bit length field. The encoded address is copied to
<constant>addr-&gt;address</constant> and
<constant>addr-&gt;length</constant> indicates the size in bytes of
the address that was copied. <constant>b-&gt;current</constant> is
advanced to point at the next byte of available data in the buffer
following the encoded address.
</para>
<para><function>lwres_addr_parse()</function>
extracts an address from the buffer <parameter>b</parameter>.
The buffer's current pointer <constant>b-&gt;current</constant>
is presumed to point at an encoded address: the address preceded
by a 32-bit protocol family identifier and a 16-bit length
field. The encoded address is copied to
<constant>addr-&gt;address</constant> and
<constant>addr-&gt;length</constant> indicates the size in bytes
of the address that was copied.
<constant>b-&gt;current</constant> is advanced to point at the
next byte of available data in the buffer following the encoded
address.
</para>
<para>
<function>lwres_getaddrsbyname()</function>
and
<function>lwres_getnamebyaddr()</function>
use the
<type>lwres_gnbaresponse_t</type>
structure defined below:
<programlisting>
<para><function>lwres_getaddrsbyname()</function>
and <function>lwres_getnamebyaddr()</function> use the
<type>lwres_gnbaresponse_t</type> structure defined below:
</para>
<para><programlisting>
typedef struct {
lwres_uint32_t flags;
lwres_uint16_t naliases;
@@ -125,97 +137,100 @@ typedef struct {
void *base;
size_t baselen;
} lwres_gabnresponse_t;
</programlisting>
The contents of this structure are not manipulated directly but
they are controlled through the
<citerefentry>
<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3
</manvolnum>
</citerefentry>
functions.
</para>
</programlisting></para>
<para>
The lightweight resolver uses
<function>lwres_getaddrsbyname()</function> to perform foward lookups.
Hostname <parameter>name</parameter> is looked up using the resolver
context <parameter>ctx</parameter> for memory allocation.
<parameter>addrtypes</parameter> is a bitmask indicating which type of
addresses are to be looked up. Current values for this bitmask are
<type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and
<type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the
lookup are returned in <parameter>*structp</parameter>.
</para>
<para>
The contents of this structure are not manipulated directly but
they are controlled through the
<citerefentry>
<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
functions.
</para>
<para>
<function>lwres_getnamebyaddr()</function> performs reverse lookups.
Resolver context <parameter>ctx</parameter> is used for memory
allocation. The address type is indicated by
<parameter>addrtype</parameter>: <type>LWRES_ADDRTYPE_V4</type> or
<type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is given
by <parameter>addr</parameter> and its length is
<parameter>addrlen</parameter> bytes. The result of the function call
is made available through <parameter>*structp</parameter>.
</para>
</refsect1>
<para>
The lightweight resolver uses
<function>lwres_getaddrsbyname()</function> to perform
foward lookups.
Hostname <parameter>name</parameter> is looked up using the
resolver
context <parameter>ctx</parameter> for memory allocation.
<parameter>addrtypes</parameter> is a bitmask indicating
which type of
addresses are to be looked up. Current values for this bitmask are
<type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and
<type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the
lookup are returned in <parameter>*structp</parameter>.
</para>
<refsect1>
<title>RETURN VALUES</title>
<para>
Successful calls to
<function>lwres_string_parse()</function>
and
<function>lwres_addr_parse()</function>
return
<errorcode>LWRES_R_SUCCESS.</errorcode>
Both functions return
<errorcode>LWRES_R_FAILURE</errorcode>
if the buffer is corrupt or
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
if the buffer has less space than expected for the components of the
encoded string or address.
</para>
<para>
<function>lwres_getaddrsbyname()</function>
returns
<errorcode>LWRES_R_SUCCESS</errorcode>
on success and it returns
<errorcode>LWRES_R_NOTFOUND</errorcode>
if the hostname
<parameter>name</parameter>
could not be found.
</para>
<para>
<errorcode>LWRES_R_SUCCESS</errorcode>
is returned by a successful call to
<function>lwres_getnamebyaddr()</function>.
</para>
<para><function>lwres_getnamebyaddr()</function>
performs reverse lookups. Resolver context
<parameter>ctx</parameter> is used for memory allocation. The
address type is indicated by <parameter>addrtype</parameter>:
<type>LWRES_ADDRTYPE_V4</type> or
<type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is
given by <parameter>addr</parameter> and its length is
<parameter>addrlen</parameter> bytes. The result of the
function call is made available through
<parameter>*structp</parameter>.
</para>
</refsect1>
<para>
Both
<function>lwres_getaddrsbyname()</function>
and
<function>lwres_getnamebyaddr()</function>
return
<errorcode>LWRES_R_NOMEMORY</errorcode>
when memory allocation requests fail and
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
if the buffers used for sending queries and receiving replies are too
small.
</para>
<refsect1>
<title>RETURN VALUES</title>
<para>
Successful calls to
<function>lwres_string_parse()</function>
and
<function>lwres_addr_parse()</function>
return
<errorcode>LWRES_R_SUCCESS.</errorcode>
Both functions return
<errorcode>LWRES_R_FAILURE</errorcode>
if the buffer is corrupt or
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
if the buffer has less space than expected for the components of the
encoded string or address.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<para><function>lwres_getaddrsbyname()</function>
returns <errorcode>LWRES_R_SUCCESS</errorcode> on success and it
returns <errorcode>LWRES_R_NOTFOUND</errorcode> if the hostname
<parameter>name</parameter> could not be found.
</para>
<para><errorcode>LWRES_R_SUCCESS</errorcode>
is returned by a successful call to
<function>lwres_getnamebyaddr()</function>.
</para>
<citerefentry>
<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
<para>
Both
<function>lwres_getaddrsbyname()</function>
and
<function>lwres_getnamebyaddr()</function>
return
<errorcode>LWRES_R_NOMEMORY</errorcode>
when memory allocation requests fail and
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
if the buffers used for sending queries and receiving replies are too
small.
</para>
</refsect1>
</refentry>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->

57
make/rules.in
View File

@@ -13,7 +13,7 @@
# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
# PERFORMANCE OF THIS SOFTWARE.
# $Id: rules.in,v 1.50 2005/03/31 04:21:03 marka Exp $
# $Id: rules.in,v 1.51 2005/05/11 05:55:41 sra Exp $
###
### Common Makefile rules for BIND 9.
@@ -179,6 +179,16 @@ INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_SCRIPT = @INSTALL_SCRIPT@
INSTALL_DATA = @INSTALL_DATA@
###
### Programs used when generating documentation. It's ok for these
### not to exist when not generating documentation.
###
XSLTPROC = @XSLTPROC@ --novalid
PERL = @PERL@
LATEX = @LATEX@
PDFLATEX = @PDFLATEX@
###
### DocBook -> HTML
### DocBook -> man page
@@ -186,42 +196,29 @@ INSTALL_DATA = @INSTALL_DATA@
.SUFFIXES: .docbook .html .1 .2 .3 .4 .5 .6 .7 .8
OPENJADE = @OPENJADE@
SGMLCATALOG = @SGMLCATALOG@
HTMLSTYLE = @HTMLSTYLE@
XMLDCL = @XMLDCL@
DOCBOOK2MANSPEC = @DOCBOOK2MANSPEC@
JADETEX = @JADETEX@
PDFJADETEX = @PDFJADETEX@
ONSGMLS = onsgmls
SGMLSPL = sgmlspl
#
# Note: this rule assumes the docbook.dsl stylesheet
# is being used. If another stylesheet is used, the
# filename 'r1.htm' in the rule might have to be
# be changed.
#
.docbook.html:
${OPENJADE} -c ${SGMLCATALOG} -t sgml -d ${HTMLSTYLE} $<
echo "" >> r1.htm
cat ${top_srcdir}/docutil/HTML_COPYRIGHT r1.htm > $@
rm -f r1.htm
${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-docbook-html.xsl $<
.docbook.1:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@
${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.2:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@
${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.3:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@
${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.4:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@
${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.5:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@
${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.6:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@
${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.7:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@
${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.8:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@
${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<