mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-09-04 00:25:29 +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

50
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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000-2002 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: named-checkconf.docbook,v 1.11 2005/05/11 05:55:35 sra Exp $ -->
<!-- $Id: named-checkconf.docbook,v 1.10 2005/04/07 03:49:55 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>June 14, 2000</date> <date>June 14, 2000</date>
@@ -29,6 +29,20 @@
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </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> <refnamediv>
<refname><application>named-checkconf</application></refname> <refname><application>named-checkconf</application></refname>
<refpurpose>named configuration file syntax checking tool</refpurpose> <refpurpose>named configuration file syntax checking tool</refpurpose>
@@ -47,9 +61,9 @@
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><command>named-checkconf</command>
<command>named-checkconf</command> checks the syntax, but not checks the syntax, but not the semantics, of a named
the semantics, of a named configuration file. configuration file.
</para> </para>
</refsect1> </refsect1>
@@ -61,7 +75,8 @@
<term>-t <replaceable class="parameter">directory</replaceable></term> <term>-t <replaceable class="parameter">directory</replaceable></term>
<listitem> <listitem>
<para> <para>
chroot to <filename>directory</filename> so that include chroot to <filename>directory</filename> so that
include
directives in the configuration file are processed as if directives in the configuration file are processed as if
run by a similarly chrooted named. run by a similarly chrooted named.
</para> </para>
@@ -113,17 +128,16 @@
<refsect1> <refsect1>
<title>RETURN VALUES</title> <title>RETURN VALUES</title>
<para> <para><command>named-checkconf</command>
<command>named-checkconf</command> returns an exit status of 1 if returns an exit status of 1 if
errors were detected and 0 otherwise. errors were detected and 0 otherwise.
</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
<refentrytitle>named</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, </citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>. <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
</para> </para>
@@ -131,16 +145,12 @@
<refsect1> <refsect1>
<title>AUTHOR</title> <title>AUTHOR</title>
<para> <para><corpauthor>Internet Systems Consortium</corpauthor>
<corpauthor>Internet Systems Consortium</corpauthor>
</para> </para>
</refsect1> </refsect1>
</refentry> </refentry><!--
<!--
- Local variables: - Local variables:
- mode: sgml - mode: sgml
- End: - End:
--> -->

65
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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000-2002 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: named-checkzone.docbook,v 1.17 2005/05/11 05:55:35 sra Exp $ -->
<!-- $Id: named-checkzone.docbook,v 1.16 2005/04/07 03:49:55 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>June 13, 2000</date> <date>June 13, 2000</date>
@@ -29,6 +29,20 @@
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </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> <refnamediv>
<refname><application>named-checkzone</application></refname> <refname><application>named-checkzone</application></refname>
<refpurpose>zone file validity checking tool</refpurpose> <refpurpose>zone file validity checking tool</refpurpose>
@@ -56,12 +70,11 @@
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><command>named-checkzone</command>
<command>named-checkzone</command> checks the syntax and integrity of checks the syntax and integrity of a zone file. It performs the
a zone file. It performs the same checks as <command>named</command> same checks as <command>named</command> does when loading a
does when loading a zone. This makes zone. This makes <command>named-checkzone</command> useful for
<command>named-checkzone</command> useful for checking zone checking zone files before configuring them into a name server.
files before configuring them into a name server.
</para> </para>
</refsect1> </refsect1>
@@ -104,6 +117,7 @@
When loading the zone file read the journal if it exists. When loading the zone file read the journal if it exists.
</para> </para>
</listitem> </listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term>-c <replaceable class="parameter">class</replaceable></term> <term>-c <replaceable class="parameter">class</replaceable></term>
@@ -118,7 +132,8 @@
<term>-k <replaceable class="parameter">mode</replaceable></term> <term>-k <replaceable class="parameter">mode</replaceable></term>
<listitem> <listitem>
<para> <para>
Perform <command>"check-name"</command> checks with the specified failure mode. Perform <command>"check-name"</command> checks with
the specified failure mode.
Possible modes are <command>"fail"</command>, Possible modes are <command>"fail"</command>,
<command>"warn"</command> (default) and <command>"warn"</command> (default) and
<command>"ignore"</command>. <command>"ignore"</command>.
@@ -151,7 +166,8 @@
<term>-t <replaceable class="parameter">directory</replaceable></term> <term>-t <replaceable class="parameter">directory</replaceable></term>
<listitem> <listitem>
<para> <para>
chroot to <filename>directory</filename> so that include chroot to <filename>directory</filename> so that
include
directives in the configuration file are processed as if directives in the configuration file are processed as if
run by a similarly chrooted named. run by a similarly chrooted named.
</para> </para>
@@ -162,7 +178,8 @@
<term>-w <replaceable class="parameter">directory</replaceable></term> <term>-w <replaceable class="parameter">directory</replaceable></term>
<listitem> <listitem>
<para> <para>
chdir to <filename>directory</filename> so that relative chdir to <filename>directory</filename> so that
relative
filenames in master file $INCLUDE directives work. This filenames in master file $INCLUDE directives work. This
is similar to the directory clause in is similar to the directory clause in
<filename>named.conf</filename>. <filename>named.conf</filename>.
@@ -186,7 +203,8 @@
Specify whether to check for non-terminal wildcards. Specify whether to check for non-terminal wildcards.
Non-terminal wildcards are almost always the result of a Non-terminal wildcards are almost always the result of a
failure to understand the wildcard matching algorithm (RFC 1034). failure to understand the wildcard matching algorithm (RFC 1034).
Possible modes are <command>"warn"</command> (default) and Possible modes are <command>"warn"</command> (default)
and
<command>"ignore"</command>. <command>"ignore"</command>.
</para> </para>
</listitem> </listitem>
@@ -216,17 +234,16 @@
<refsect1> <refsect1>
<title>RETURN VALUES</title> <title>RETURN VALUES</title>
<para> <para><command>named-checkzone</command>
<command>named-checkzone</command> returns an exit status of 1 if returns an exit status of 1 if
errors were detected and 0 otherwise. errors were detected and 0 otherwise.
</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
<refentrytitle>named</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, </citerefentry>,
<citetitle>RFC 1035</citetitle>, <citetitle>RFC 1035</citetitle>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>. <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
@@ -235,16 +252,12 @@
<refsect1> <refsect1>
<title>AUTHOR</title> <title>AUTHOR</title>
<para> <para><corpauthor>Internet Systems Consortium</corpauthor>
<corpauthor>Internet Systems Consortium</corpauthor>
</para> </para>
</refsect1> </refsect1>
</refentry> </refentry><!--
<!--
- Local variables: - Local variables:
- mode: sgml - mode: sgml
- End: - End:
--> -->

1433
bin/dig/dig.docbook
View File

File diff suppressed because it is too large Load Diff

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

583
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") - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
- -
@@ -14,9 +16,7 @@
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: nslookup.docbook,v 1.6 2005/05/11 05:55:36 sra Exp $ -->
<!-- $Id: nslookup.docbook,v 1.5 2004/08/30 00:54:45 marka Exp $ -->
<!-- <!--
- Copyright (c) 1985, 1989 - Copyright (c) 1985, 1989
- The Regents of the University of California. All rights reserved. - The Regents of the University of California. All rights reserved.
@@ -49,272 +49,431 @@
- OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- SUCH DAMAGE. - SUCH DAMAGE.
--> -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Jun 30, 2000</date> <date>Jun 30, 2000</date>
</refentryinfo> </refentryinfo>
<refmeta> <refmeta>
<refentrytitle>nslookup</refentrytitle> <refentrytitle>nslookup</refentrytitle>
<manvolnum>1</manvolnum> <manvolnum>1</manvolnum>
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>nslookup</refname> <refname>nslookup</refname>
<refpurpose>query Internet name servers interactively</refpurpose> <refpurpose>query Internet name servers interactively</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <docinfo>
<cmdsynopsis> <copyright>
<year>2004</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<cmdsynopsis>
<command>nslookup</command> <command>nslookup</command>
<arg><option>-option</option></arg> <arg><option>-option</option></arg>
<arg choice=opt>name | -</arg> <arg choice="opt">name | -</arg>
<arg choice=opt>server</arg> <arg choice="opt">server</arg>
</cmdsynopsis> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><command>Nslookup</command>
<command>Nslookup</command> is a program to query Internet domain name servers. <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
has two modes: interactive and non-interactive. Interactive mode allows the user to query name servers for information about various hosts and
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
domains or to print a list of hosts in a domain. Non-interactive mode is is
used to print just the name and requested information for a host or used to print just the name and requested information for a host or
domain. domain.
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>ARGUMENTS</title> <title>ARGUMENTS</title>
<para> <para>
Interactive mode is entered in the following cases: Interactive mode is entered in the following cases:
<OrderedList Numeration=Loweralpha> <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>
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>
</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>
<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>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>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>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>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> <listitem>
<para>Prints the current values of the frequently used <para>
options to <command>set</command>. Information about the current default 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>
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>
</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>
<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/>
</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>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>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>?</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>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. server and host is also printed.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry><term><constant>class=</constant><replaceable>value</replaceable></term> <varlistentry>
<listitem><para> <term><constant>class=</constant><replaceable>value</replaceable></term>
<listitem>
<para>
Change the query class to one of: Change the query class to one of:
<variablelist> <variablelist>
<varlistentry><term><constant>IN</constant></term> <varlistentry>
<listitem><para>the Internet class</para></listitem></varlistentry> <term><constant>IN</constant></term>
<varlistentry><term><constant>CH</constant></term> <listitem>
<listitem><para>the Chaos class</para></listitem></varlistentry> <para>
<varlistentry><term><constant>HS</constant></term> the Internet class
<listitem><para>the Hesiod class</para></listitem></varlistentry> </para>
<varlistentry><term><constant>ANY</constant></term> </listitem>
<listitem><para>wildcard</para></listitem></varlistentry> </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> </variablelist>
The class specifies the protocol group of the information. The class specifies the protocol group of the information.
</para><para>
</para>
<para>
(Default = IN; abbreviation = cl) (Default = IN; abbreviation = cl)
</para></listitem> </para>
</listitem>
</varlistentry> </varlistentry>
<varlistentry><term><constant><replaceable><optional>no</optional></replaceable>debug</constant></term> <varlistentry>
<listitem><para> <term><constant>
<replaceable><optional>no</optional></replaceable>debug</constant></term>
<listitem>
<para>
Turn debugging mode on. A lot more information is Turn debugging mode on. A lot more information is
printed about the packet sent to the server and the printed about the packet sent to the server and the
resulting answer. resulting answer.
</para><para> </para>
<para>
(Default = nodebug; abbreviation = <optional>no</optional>deb) (Default = nodebug; abbreviation = <optional>no</optional>deb)
</para></listitem></varlistentry> </para>
</listitem>
</varlistentry>
<varlistentry><term><constant><replaceable><optional>no</optional></replaceable>d2</constant></term> <varlistentry>
<listitem><para> <term><constant>
<replaceable><optional>no</optional></replaceable>d2</constant></term>
<listitem>
<para>
Turn debugging mode on. A lot more information is Turn debugging mode on. A lot more information is
printed about the packet sent to the server and the printed about the packet sent to the server and the
resulting answer. resulting answer.
</para><para> </para>
<para>
(Default = nod2) (Default = nod2)
</para></listitem></varlistentry> </para>
</listitem>
</varlistentry>
<varlistentry><term><constant>domain=</constant><replaceable>name</replaceable></term> <varlistentry>
<listitem><para> <term><constant>domain=</constant><replaceable>name</replaceable></term>
<listitem>
<para>
Sets the search list to <replaceable>name</replaceable>. Sets the search list to <replaceable>name</replaceable>.
</para></listitem></varlistentry> </para>
</listitem>
</varlistentry>
<varlistentry><term><constant><replaceable><optional>no</optional></replaceable>search</constant></term> <varlistentry>
<listitem><para> <term><constant>
<replaceable><optional>no</optional></replaceable>search</constant></term>
<listitem>
<para>
If the lookup request contains at least one period but If the lookup request contains at least one period but
doesn't end with a trailing period, append the domain doesn't end with a trailing period, append the domain
names in the domain search list to the request until an names in the domain search list to the request until an
answer is received. answer is received.
</para><para> </para>
<para>
(Default = search) (Default = search)
</para></listitem></varlistentry> </para>
</listitem>
</varlistentry>
<varlistentry><term><constant>port=</constant><replaceable>value</replaceable></term> <varlistentry>
<listitem><para> <term><constant>port=</constant><replaceable>value</replaceable></term>
<listitem>
<para>
Change the default TCP/UDP name server port to <replaceable>value</replaceable>. Change the default TCP/UDP name server port to <replaceable>value</replaceable>.
</para><para> </para>
<para>
(Default = 53; abbreviation = po) (Default = 53; abbreviation = po)
</para></listitem></varlistentry> </para>
</listitem>
</varlistentry>
<varlistentry><term><constant>querytype=</constant><replaceable>value</replaceable></term> <varlistentry>
<listitem><para></para></listitem></varlistentry> <term><constant>querytype=</constant><replaceable>value</replaceable></term>
<listitem>
<para/>
</listitem>
</varlistentry>
<varlistentry><term><constant>type=</constant><replaceable>value</replaceable></term> <varlistentry>
<listitem><para> <term><constant>type=</constant><replaceable>value</replaceable></term>
<listitem>
<para>
Change the top of the information query. Change the top of the information query.
</para><para> </para>
<para>
(Default = A; abbreviations = q, ty) (Default = A; abbreviations = q, ty)
</para></listitem></varlistentry> </para>
</listitem>
</varlistentry>
<varlistentry><term><constant><replaceable><optional>no</optional></replaceable>recurse</constant></term> <varlistentry>
<listitem><para> <term><constant>
Tell the name server to query other servers if it does not have the <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. information.
</para><para> </para>
<para>
(Default = recurse; abbreviation = [no]rec) (Default = recurse; abbreviation = [no]rec)
</para></listitem></varlistentry> </para>
</listitem>
</varlistentry>
<varlistentry><term><constant>retry=</constant><replaceable>number</replaceable></term> <varlistentry>
<listitem><para> <term><constant>retry=</constant><replaceable>number</replaceable></term>
<listitem>
<para>
Set the number of retries to number. Set the number of retries to number.
</para></listitem></varlistentry> </para>
</listitem>
</varlistentry>
<varlistentry><term><constant>timeout=</constant><replaceable>number</replaceable></term> <varlistentry>
<listitem><para> <term><constant>timeout=</constant><replaceable>number</replaceable></term>
<listitem>
<para>
Change the initial timeout interval for waiting for a Change the initial timeout interval for waiting for a
reply to number seconds. reply to number seconds.
</para></listitem></varlistentry> </para>
</listitem>
</varlistentry>
<varlistentry><term><constant><replaceable><optional>no</optional></replaceable>vc</constant></term> <varlistentry>
<listitem><para> <term><constant>
Always use a virtual circuit when sending requests to the server. <replaceable><optional>no</optional></replaceable>vc</constant></term>
</para><para> <listitem>
<para>
Always use a virtual circuit when sending requests to the
server.
</para>
<para>
(Default = novc) (Default = novc)
</para></listitem></varlistentry> </para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para></listitem></varlistentry> </para>
</variablelist> </listitem>
</refsect1> </varlistentry>
</variablelist>
</refsect1>
<refsect1> <refsect1>
<title>FILES</title> <title>FILES</title>
<para> <para><filename>/etc/resolv.conf</filename>
<filename>/etc/resolv.conf</filename> </para>
</para> </refsect1>
</refsect1>
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>dig</refentrytitle><manvolnum>1</manvolnum>
<refentrytitle>dig</refentrytitle><manvolnum>1</manvolnum> </citerefentry>,
</citerefentry>, <citerefentry>
<citerefentry> <refentrytitle>host</refentrytitle><manvolnum>1</manvolnum>
<refentrytitle>host</refentrytitle><manvolnum>1</manvolnum> </citerefentry>,
</citerefentry>, <citerefentry>
<citerefentry> <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum> </citerefentry>.
</citerefentry>. </para>
</para> </refsect1>
</refsect1>
<refsect1> <refsect1>
<title>Author</title> <title>Author</title>
<para> <para>
Andrew Cherenson Andrew Cherenson
</para> </para>
</refsect1> </refsect1>
</refentry> </refentry><!--
- Local variables:
- mode: sgml
- End:
-->

96
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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000-2003 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: dnssec-keygen.docbook,v 1.11 2005/05/11 05:55:36 sra Exp $ -->
<!-- $Id: dnssec-keygen.docbook,v 1.10 2005/04/07 03:49:55 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>June 30, 2000</date> <date>June 30, 2000</date>
@@ -34,6 +34,21 @@
<refpurpose>DNSSEC key generation tool</refpurpose> <refpurpose>DNSSEC key generation tool</refpurpose>
</refnamediv> </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> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>dnssec-keygen</command> <command>dnssec-keygen</command>
@@ -57,11 +72,10 @@
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><command>dnssec-keygen</command>
<command>dnssec-keygen</command> generates keys for DNSSEC generates keys for DNSSEC (Secure DNS), as defined in RFC 2535
(Secure DNS), as defined in RFC 2535 and RFC &lt;TBA\&gt;. It can also generate and RFC &lt;TBA\&gt;. It can also generate keys for use with
keys for use with TSIG (Transaction Signatures), as TSIG (Transaction Signatures), as defined in RFC 2845.
defined in RFC 2845.
</para> </para>
</refsect1> </refsect1>
@@ -79,7 +93,8 @@
are case insensitive. are case insensitive.
</para> </para>
<para> <para>
Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement algorithm, Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
algorithm,
and DSA is recommended. For TSIG, HMAC-MD5 is mandatory. and DSA is recommended. For TSIG, HMAC-MD5 is mandatory.
</para> </para>
<para> <para>
@@ -93,7 +108,8 @@
<listitem> <listitem>
<para> <para>
Specifies the number of bits in the key. The choice of key Specifies the number of bits in the key. The choice of key
size depends on the algorithm used. RSAMD5 / RSASHA1 keys must be between size depends on the algorithm used. RSAMD5 / RSASHA1 keys must be
between
512 and 2048 bits. Diffie Hellman 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 128 and 4096 bits. DSA keys must be between 512 and 1024
bits and an exact multiple of 64. HMAC-MD5 keys must be bits and an exact multiple of 64. HMAC-MD5 keys must be
@@ -108,8 +124,10 @@
<para> <para>
Specifies the owner type of the key. The value of Specifies the owner type of the key. The value of
<option>nametype</option> must either be ZONE (for a DNSSEC <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)), zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
USER (for a key associated with a user(KEY)) or OTHER (DNSKEY). These values are a host (KEY)),
USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
These values are
case insensitive. case insensitive.
</para> </para>
</listitem> </listitem>
@@ -194,7 +212,8 @@
Specifies the source of randomness. If the operating Specifies the source of randomness. If the operating
system does not provide a <filename>/dev/random</filename> system does not provide a <filename>/dev/random</filename>
or equivalent device, the default source of randomness or equivalent device, the default source of randomness
is keyboard input. <filename>randomdev</filename> specifies is keyboard input. <filename>randomdev</filename>
specifies
the name of a character device or file containing random the name of a character device or file containing random
data to be used instead of the default. The special value data to be used instead of the default. The special value
<filename>keyboard</filename> indicates that keyboard <filename>keyboard</filename> indicates that keyboard
@@ -241,7 +260,8 @@
<refsect1> <refsect1>
<title>GENERATED KEYS</title> <title>GENERATED KEYS</title>
<para> <para>
When <command>dnssec-keygen</command> completes successfully, When <command>dnssec-keygen</command> completes
successfully,
it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename> it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
to the standard output. This is an identification string for to the standard output. This is an identification string for
the key it has generated. These strings can be used as arguments the key it has generated. These strings can be used as arguments
@@ -249,36 +269,38 @@
</para> </para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para><filename>nnnn</filename> is the key name.
<filename>nnnn</filename> is the key name.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para><filename>aaa</filename> is the numeric representation
<filename>aaa</filename> is the numeric representation of the of the
algorithm. algorithm.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para><filename>iiiii</filename> is the key identifier (or
<filename>iiiii</filename> is the key identifier (or footprint). footprint).
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para> <para><command>dnssec-keygen</command>
<command>dnssec-keygen</command> creates two file, with names based creates two file, with names based
on the printed string. <filename>Knnnn.+aaa+iiiii.key</filename> on the printed string. <filename>Knnnn.+aaa+iiiii.key</filename>
contains the public key, and contains the public key, and
<filename>Knnnn.+aaa+iiiii.private</filename> contains the private <filename>Knnnn.+aaa+iiiii.private</filename> contains the
private
key. key.
</para> </para>
<para> <para>
The <filename>.key</filename> file contains a DNS KEY record that The <filename>.key</filename> file contains a DNS KEY record
that
can be inserted into a zone file (directly or with a $INCLUDE can be inserted into a zone file (directly or with a $INCLUDE
statement). statement).
</para> </para>
<para> <para>
The <filename>.private</filename> file contains algorithm specific The <filename>.private</filename> file contains algorithm
specific
fields. For obvious security reasons, this file does not have fields. For obvious security reasons, this file does not have
general read permission. general read permission.
</para> </para>
@@ -296,28 +318,25 @@
<userinput>example.com</userinput>, the following command would be <userinput>example.com</userinput>, the following command would be
issued: issued:
</para> </para>
<para> <para><userinput>dnssec-keygen -a DSA -b 768 -n ZONE example.com</userinput>
<userinput>dnssec-keygen -a DSA -b 768 -n ZONE example.com</userinput>
</para> </para>
<para> <para>
The command would print a string of the form: The command would print a string of the form:
</para> </para>
<para> <para><userinput>Kexample.com.+003+26160</userinput>
<userinput>Kexample.com.+003+26160</userinput>
</para> </para>
<para> <para>
In this example, <command>dnssec-keygen</command> creates In this example, <command>dnssec-keygen</command> creates
the files <filename>Kexample.com.+003+26160.key</filename> and the files <filename>Kexample.com.+003+26160.key</filename>
and
<filename>Kexample.com.+003+26160.private</filename> <filename>Kexample.com.+003+26160.private</filename>
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
<refentrytitle>dnssec-signzone</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, </citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>, <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
<citetitle>RFC 2535</citetitle>, <citetitle>RFC 2535</citetitle>,
@@ -328,14 +347,11 @@
<refsect1> <refsect1>
<title>AUTHOR</title> <title>AUTHOR</title>
<para> <para><corpauthor>Internet Systems Consortium</corpauthor>
<corpauthor>Internet Systems Consortium</corpauthor>
</para> </para>
</refsect1> </refsect1>
</refentry> </refentry><!--
<!--
- Local variables: - Local variables:
- mode: sgml - mode: sgml
- End: - End:

61
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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000-2003 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: dnssec-signzone.docbook,v 1.16 2005/05/11 05:55:36 sra Exp $ -->
<!-- $Id: dnssec-signzone.docbook,v 1.15 2005/04/07 03:49:56 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>June 30, 2000</date> <date>June 30, 2000</date>
@@ -34,6 +34,21 @@
<refpurpose>DNSSEC zone signing tool</refpurpose> <refpurpose>DNSSEC zone signing tool</refpurpose>
</refnamediv> </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> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>dnssec-signzone</command> <command>dnssec-signzone</command>
@@ -63,8 +78,8 @@
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><command>dnssec-signzone</command>
<command>dnssec-signzone</command> signs a zone. It generates signs a zone. It generates
NSEC and RRSIG records and produces a signed version of the NSEC and RRSIG records and produces a signed version of the
zone. The security status of delegations from the signed zone zone. The security status of delegations from the signed zone
(that is, whether the child zones are secure or not) is (that is, whether the child zones are secure or not) is
@@ -171,7 +186,8 @@
<listitem> <listitem>
<para> <para>
The name of the output file containing the signed zone. The The name of the output file containing the signed zone. The
default is to append <filename>.signed</filename> to the default is to append <filename>.signed</filename> to
the
input file. input file.
</para> </para>
</listitem> </listitem>
@@ -202,7 +218,8 @@
The default cycle interval is one quarter of the difference The default cycle interval is one quarter of the difference
between the signature end and start times. So if neither between the signature end and start times. So if neither
<option>end-time</option> or <option>start-time</option> <option>end-time</option> or <option>start-time</option>
are specified, <command>dnssec-signzone</command> generates are specified, <command>dnssec-signzone</command>
generates
signatures that are valid for 30 days, with a cycle signatures that are valid for 30 days, with a cycle
interval of 7.5 days. Therefore, if any existing RRSIG records interval of 7.5 days. Therefore, if any existing RRSIG records
are due to expire in less than 7.5 days, they would be are due to expire in less than 7.5 days, they would be
@@ -212,7 +229,7 @@
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>-j <replaceable class="parameter">jitter</replaceable></term>
<listitem> <listitem>
<para> <para>
When signing a zone with a fixed signature lifetime, all When signing a zone with a fixed signature lifetime, all
@@ -274,7 +291,8 @@
Specifies the source of randomness. If the operating Specifies the source of randomness. If the operating
system does not provide a <filename>/dev/random</filename> system does not provide a <filename>/dev/random</filename>
or equivalent device, the default source of randomness or equivalent device, the default source of randomness
is keyboard input. <filename>randomdev</filename> specifies is keyboard input. <filename>randomdev</filename>
specifies
the name of a character device or file containing random the name of a character device or file containing random
data to be used instead of the default. The special value data to be used instead of the default. The special value
<filename>keyboard</filename> indicates that keyboard <filename>keyboard</filename> indicates that keyboard
@@ -340,20 +358,22 @@
The following command signs the <userinput>example.com</userinput> The following command signs the <userinput>example.com</userinput>
zone with the DSA key generated in the <command>dnssec-keygen</command> 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 man page. The zone's keys must be in the zone. If there are
<filename>keyset</filename> files associated with child zones, <filename>keyset</filename> files associated with child
zones,
they must be in the current directory. they must be in the current directory.
<userinput>example.com</userinput>, the following command would be <userinput>example.com</userinput>, the following command would be
issued: issued:
</para> </para>
<para> <para><userinput>dnssec-signzone -o example.com db.example.com
<userinput>dnssec-signzone -o example.com db.example.com Kexample.com.+003+26160</userinput> Kexample.com.+003+26160</userinput>
</para> </para>
<para> <para>
The command would print a string of the form: The command would print a string of the form:
</para> </para>
<para> <para>
In this example, <command>dnssec-signzone</command> creates In this example, <command>dnssec-signzone</command> creates
the file <filename>db.example.com.signed</filename>. This file the file <filename>db.example.com.signed</filename>. This
file
should be referenced in a zone statement in a should be referenced in a zone statement in a
<filename>named.conf</filename> file. <filename>named.conf</filename> file.
</para> </para>
@@ -361,10 +381,8 @@
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
<refentrytitle>dnssec-keygen</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, </citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>, <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
<citetitle>RFC 2535</citetitle>. <citetitle>RFC 2535</citetitle>.
@@ -373,14 +391,11 @@
<refsect1> <refsect1>
<title>AUTHOR</title> <title>AUTHOR</title>
<para> <para><corpauthor>Internet Systems Consortium</corpauthor>
<corpauthor>Internet Systems Consortium</corpauthor>
</para> </para>
</refsect1> </refsect1>
</refentry> </refentry><!--
<!--
- Local variables: - Local variables:
- mode: sgml - mode: sgml
- End: - End:

72
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) 2004 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwresd.docbook,v 1.9 2005/05/11 05:55:36 sra Exp $ -->
<!-- $Id: lwresd.docbook,v 1.8 2004/06/03 02:22:32 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>June 30, 2000</date> <date>June 30, 2000</date>
@@ -34,6 +34,18 @@
<refpurpose>lightweight resolver daemon</refpurpose> <refpurpose>lightweight resolver daemon</refpurpose>
</refnamediv> </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> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>lwresd</command> <command>lwresd</command>
@@ -54,15 +66,17 @@
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para>
<command>lwresd</command> is the daemon providing name lookup <para><command>lwresd</command>
is the daemon providing name lookup
services to clients that use the BIND 9 lightweight resolver services to clients that use the BIND 9 lightweight resolver
library. It is essentially a stripped-down, caching-only name library. It is essentially a stripped-down, caching-only name
server that answers queries using the BIND 9 lightweight server that answers queries using the BIND 9 lightweight
resolver protocol rather than the DNS protocol. resolver protocol rather than the DNS protocol.
</para> </para>
<para>
<command>lwresd</command> listens for resolver queries on a <para><command>lwresd</command>
listens for resolver queries on a
UDP port on the IPv4 loopback interface, 127.0.0.1. This UDP port on the IPv4 loopback interface, 127.0.0.1. This
means that <command>lwresd</command> can only be used by means that <command>lwresd</command> can only be used by
processes running on the local machine. By default UDP port processes running on the local machine. By default UDP port
@@ -96,8 +110,7 @@
<term>-C <replaceable class="parameter">config-file</replaceable></term> <term>-C <replaceable class="parameter">config-file</replaceable></term>
<listitem> <listitem>
<para> <para>
Use <replaceable Use <replaceable class="parameter">config-file</replaceable> as the
class="parameter">config-file</replaceable> as the
configuration file instead of the default, configuration file instead of the default,
<filename>/etc/resolv.conf</filename>. <filename>/etc/resolv.conf</filename>.
</para> </para>
@@ -108,8 +121,7 @@
<term>-d <replaceable class="parameter">debug-level</replaceable></term> <term>-d <replaceable class="parameter">debug-level</replaceable></term>
<listitem> <listitem>
<para> <para>
Set the daemon's debug level to <replaceable Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>.
class="parameter">debug-level</replaceable>.
Debugging traces from <command>lwresd</command> become Debugging traces from <command>lwresd</command> become
more verbose as the debug level increases. more verbose as the debug level increases.
</para> </para>
@@ -139,8 +151,7 @@
<term>-n <replaceable class="parameter">#cpus</replaceable></term> <term>-n <replaceable class="parameter">#cpus</replaceable></term>
<listitem> <listitem>
<para> <para>
Create <replaceable Create <replaceable class="parameter">#cpus</replaceable> worker threads
class="parameter">#cpus</replaceable> worker threads
to take advantage of multiple CPUs. If not specified, to take advantage of multiple CPUs. If not specified,
<command>lwresd</command> will try to determine the <command>lwresd</command> will try to determine the
number of CPUs present and create one thread per CPU. number of CPUs present and create one thread per CPU.
@@ -165,8 +176,7 @@
<term>-p <replaceable class="parameter">port</replaceable></term> <term>-p <replaceable class="parameter">port</replaceable></term>
<listitem> <listitem>
<para> <para>
Send DNS lookups to port <replaceable Send DNS lookups to port <replaceable class="parameter">port</replaceable>. If not
class="parameter">port</replaceable>. If not
specified, the default is port 53. This provides a specified, the default is port 53. This provides a
way of testing the lightweight resolver daemon with a way of testing the lightweight resolver daemon with a
name server that listens for queries on a non-standard name server that listens for queries on a non-standard
@@ -194,9 +204,8 @@
<varlistentry> <varlistentry>
<term>-t <replaceable class="parameter">directory</replaceable></term> <term>-t <replaceable class="parameter">directory</replaceable></term>
<listitem> <listitem>
<para> <para><function>chroot()</function>
<function>chroot()</function> to <replaceable to <replaceable class="parameter">directory</replaceable> after
class="parameter">directory</replaceable> after
processing the command line arguments, but before processing the command line arguments, but before
reading the configuration file. reading the configuration file.
</para> </para>
@@ -216,9 +225,8 @@
<varlistentry> <varlistentry>
<term>-u <replaceable class="parameter">user</replaceable></term> <term>-u <replaceable class="parameter">user</replaceable></term>
<listitem> <listitem>
<para> <para><function>setuid()</function>
<function>setuid()</function> to <replaceable to <replaceable class="parameter">user</replaceable> after completing
class="parameter">user</replaceable> after completing
privileged operations, such as creating sockets that privileged operations, such as creating sockets that
listen on privileged ports. listen on privileged ports.
</para> </para>
@@ -267,33 +275,25 @@
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
<refentrytitle>named</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres</refentrytitle> <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
<manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>resolver</refentrytitle> <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
<manvolnum>5</manvolnum>
</citerefentry>. </citerefentry>.
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>AUTHOR</title> <title>AUTHOR</title>
<para> <para><corpauthor>Internet Systems Consortium</corpauthor>
<corpauthor>Internet Systems Consortium</corpauthor>
</para> </para>
</refsect1> </refsect1>
</refentry> </refentry><!--
<!--
- Local variables: - Local variables:
- mode: sgml - mode: sgml
- End: - End:

171
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") - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: named.conf.docbook,v 1.9 2005/05/11 05:55:36 sra Exp $ -->
<!-- $Id: named.conf.docbook,v 1.8 2005/01/17 00:46:01 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Aug 13, 2004</date> <date>Aug 13, 2004</date>
@@ -33,6 +33,14 @@
<refpurpose>configuration file for named</refpurpose> <refpurpose>configuration file for named</refpurpose>
</refnamediv> </refnamediv>
<docinfo>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
</docinfo>
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>named.conf</command> <command>named.conf</command>
@@ -41,8 +49,8 @@
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><filename>named.conf</filename> is the configuration file
<filename>named.conf</filename> is the configuration file for for
<command>named</command>. Statements are enclosed <command>named</command>. Statements are enclosed
in braces and terminated with a semi-colon. Clauses in in braces and terminated with a semi-colon. Clauses in
the statements are also semi-colon terminated. The usual the statements are also semi-colon terminated. The usual
@@ -59,37 +67,37 @@
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>ACL</title> <title>ACL</title>
<LITERALLAYOUT> <literallayout>
acl <replaceable>string</replaceable> { <replaceable>address_match_element</replaceable>; ... }; acl <replaceable>string</replaceable> { <replaceable>address_match_element</replaceable>; ... };
</LITERALLAYOUT> </literallayout>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>KEY</title> <title>KEY</title>
<LITERALLAYOUT> <literallayout>
key <replaceable>domain_name</replaceable> { key <replaceable>domain_name</replaceable> {
algorithm <replaceable>string</replaceable>; algorithm <replaceable>string</replaceable>;
secret <replaceable>string</replaceable>; secret <replaceable>string</replaceable>;
}; };
</LITERALLAYOUT> </literallayout>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>MASTERS</title> <title>MASTERS</title>
<LITERALLAYOUT> <literallayout>
masters <replaceable>string</replaceable> <optional> port <replaceable>integer</replaceable> </optional> { masters <replaceable>string</replaceable> <optional> port <replaceable>integer</replaceable> </optional> {
( <replaceable>masters</replaceable> | <replaceable>ipv4_address</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>; ... <replaceable>ipv6_address</replaceable> <optional>port <replaceable>integer</replaceable></optional> ) <optional> key <replaceable>string</replaceable> </optional>; ...
}; };
</LITERALLAYOUT> </literallayout>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>SERVER</title> <title>SERVER</title>
<LITERALLAYOUT> <literallayout>
server ( <replaceable>ipv4_address<optional>/prefixlen</optional></replaceable> | <replaceable>ipv6_address<optional>/prefixlen</optional></replaceable> ) { server ( <replaceable>ipv4_address<optional>/prefixlen</optional></replaceable> | <replaceable>ipv6_address<optional>/prefixlen</optional></replaceable> ) {
bogus <replaceable>boolean</replaceable>; bogus <replaceable>boolean</replaceable>;
edns <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 support-ixfr <replaceable>boolean</replaceable>; // obsolete
}; };
</LITERALLAYOUT> </literallayout>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>TRUSTED-KEYS</title> <title>TRUSTED-KEYS</title>
<LITERALLAYOUT> <literallayout>
trusted-keys { trusted-keys {
<replaceable>domain_name</replaceable> <replaceable>flags</replaceable> <replaceable>protocol</replaceable> <replaceable>algorithm</replaceable> <replaceable>key</replaceable>; ... <replaceable>domain_name</replaceable> <replaceable>flags</replaceable> <replaceable>protocol</replaceable> <replaceable>algorithm</replaceable> <replaceable>key</replaceable>; ...
}; };
</LITERALLAYOUT> </literallayout>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>CONTROLS</title> <title>CONTROLS</title>
<LITERALLAYOUT> <literallayout>
controls { controls {
inet ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> | * ) inet ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> | * )
<optional> port ( <replaceable>integer</replaceable> | * ) </optional> <optional> port ( <replaceable>integer</replaceable> | * ) </optional>
@@ -127,12 +135,12 @@ controls {
<optional> keys { <replaceable>string</replaceable>; ... } </optional>; <optional> keys { <replaceable>string</replaceable>; ... } </optional>;
unix <replaceable>unsupported</replaceable>; // not implemented unix <replaceable>unsupported</replaceable>; // not implemented
}; };
</LITERALLAYOUT> </literallayout>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>LOGGING</title> <title>LOGGING</title>
<LITERALLAYOUT> <literallayout>
logging { logging {
channel <replaceable>string</replaceable> { channel <replaceable>string</replaceable> {
file <replaceable>log_file</replaceable>; file <replaceable>log_file</replaceable>;
@@ -146,12 +154,12 @@ logging {
}; };
category <replaceable>string</replaceable> { <replaceable>string</replaceable>; ... }; category <replaceable>string</replaceable> { <replaceable>string</replaceable>; ... };
}; };
</LITERALLAYOUT> </literallayout>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>LWRES</title> <title>LWRES</title>
<LITERALLAYOUT> <literallayout>
lwres { lwres {
listen-on <optional> port <replaceable>integer</replaceable> </optional> { listen-on <optional> port <replaceable>integer</replaceable> </optional> {
( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> ) <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>; ... }; search { <replaceable>string</replaceable>; ... };
ndots <replaceable>integer</replaceable>; ndots <replaceable>integer</replaceable>;
}; };
</LITERALLAYOUT> </literallayout>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>OPTIONS</title> <title>OPTIONS</title>
<LITERALLAYOUT> <literallayout>
options { options {
avoid-v4-udp-ports { <replaceable>port</replaceable>; ... }; avoid-v4-udp-ports { <replaceable>port</replaceable>; ... };
avoid-v6-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 treat-cr-as-space <replaceable>boolean</replaceable>; // obsolete
use-id-pool <replaceable>boolean</replaceable>; // obsolete use-id-pool <replaceable>boolean</replaceable>; // obsolete
}; };
</LITERALLAYOUT> </literallayout>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>VIEW</title> <title>VIEW</title>
<LITERALLAYOUT> <literallayout>
view <replaceable>string</replaceable> <replaceable>optional_class</replaceable> { view <replaceable>string</replaceable> <replaceable>optional_class</replaceable> {
match-clients { <replaceable>address_match_element</replaceable>; ... }; match-clients { <replaceable>address_match_element</replaceable>; ... };
match-destinations { <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 maintain-ixfr-base <replaceable>boolean</replaceable>; // obsolete
max-ixfr-log-size <replaceable>size</replaceable>; // obsolete max-ixfr-log-size <replaceable>size</replaceable>; // obsolete
}; };
</LITERALLAYOUT> </literallayout>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>ZONE</title> <title>ZONE</title>
<LITERALLAYOUT> <literallayout>
zone <replaceable>string</replaceable> <replaceable>optional_class</replaceable> { zone <replaceable>string</replaceable> <replaceable>optional_class</replaceable> {
type ( master | slave | stub | hint | type ( master | slave | stub | hint |
forward | delegation-only ); forward | delegation-only );
@@ -508,33 +516,30 @@ zone <replaceable>string</replaceable> <replaceable>optional_class</replaceable>
max-ixfr-log-size <replaceable>size</replaceable>; // obsolete max-ixfr-log-size <replaceable>size</replaceable>; // obsolete
pubkey <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; // obsolete pubkey <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; // obsolete
}; };
</LITERALLAYOUT> </literallayout>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>FILES</title> <title>FILES</title>
<para> <para><filename>/etc/named.conf</filename>
<filename>/etc/named.conf</filename> </para>
</para> </refsect1>
</refsect1>
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum> </citerefentry>,
</citerefentry>, <citerefentry>
<citerefentry> <refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>
<refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum> </citerefentry>,
</citerefentry>, <citerefentry>
<citerefentry> <refentrytitle>BIND 9 Administrator Reference Manual</refentrytitle>
<refentrytitle>BIND 9 Adminstrators Reference Manual</refentrytitle> </citerefentry>.
</citerefentry>. </para>
</para> </refsect1>
</refsect1>
</refentry> </refentry><!--
<!--
- Local variables: - Local variables:
- mode: sgml - mode: sgml
- End: - End:

85
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) 2004 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001, 2003 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: named.docbook,v 1.9 2005/05/11 05:55:36 sra Exp $ -->
<!-- $Id: named.docbook,v 1.8 2004/06/03 02:22:33 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>June 30, 2000</date> <date>June 30, 2000</date>
@@ -34,6 +34,19 @@
<refpurpose>Internet domain name server</refpurpose> <refpurpose>Internet domain name server</refpurpose>
</refnamediv> </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> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>named</command> <command>named</command>
@@ -55,13 +68,14 @@
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><command>named</command>
<command>named</command> is a Domain Name System (DNS) server, is a Domain Name System (DNS) server,
part of the BIND 9 distribution from ISC. For more part of the BIND 9 distribution from ISC. For more
information on the DNS, see RFCs 1033, 1034, and 1035. information on the DNS, see RFCs 1033, 1034, and 1035.
</para> </para>
<para> <para>
When invoked without arguments, <command>named</command> will When invoked without arguments, <command>named</command>
will
read the default configuration file read the default configuration file
<filename>/etc/named.conf</filename>, read any initial <filename>/etc/named.conf</filename>, read any initial
data, and listen for queries. data, and listen for queries.
@@ -97,16 +111,14 @@
<term>-c <replaceable class="parameter">config-file</replaceable></term> <term>-c <replaceable class="parameter">config-file</replaceable></term>
<listitem> <listitem>
<para> <para>
Use <replaceable Use <replaceable class="parameter">config-file</replaceable> as the
class="parameter">config-file</replaceable> as the
configuration file instead of the default, configuration file instead of the default,
<filename>/etc/named.conf</filename>. To <filename>/etc/named.conf</filename>. To
ensure that reloading the configuration file continues ensure that reloading the configuration file continues
to work after the server has changed its working to work after the server has changed its working
directory due to to a possible directory due to to a possible
<option>directory</option> option in the configuration <option>directory</option> option in the configuration
file, <replaceable file, <replaceable class="parameter">config-file</replaceable> should be
class="parameter">config-file</replaceable> should be
an absolute pathname. an absolute pathname.
</para> </para>
</listitem> </listitem>
@@ -116,8 +128,7 @@
<term>-d <replaceable class="parameter">debug-level</replaceable></term> <term>-d <replaceable class="parameter">debug-level</replaceable></term>
<listitem> <listitem>
<para> <para>
Set the daemon's debug level to <replaceable Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>.
class="parameter">debug-level</replaceable>.
Debugging traces from <command>named</command> become Debugging traces from <command>named</command> become
more verbose as the debug level increases. more verbose as the debug level increases.
</para> </para>
@@ -147,8 +158,7 @@
<term>-n <replaceable class="parameter">#cpus</replaceable></term> <term>-n <replaceable class="parameter">#cpus</replaceable></term>
<listitem> <listitem>
<para> <para>
Create <replaceable Create <replaceable class="parameter">#cpus</replaceable> worker threads
class="parameter">#cpus</replaceable> worker threads
to take advantage of multiple CPUs. If not specified, to take advantage of multiple CPUs. If not specified,
<command>named</command> will try to determine the <command>named</command> will try to determine the
number of CPUs present and create one thread per CPU. number of CPUs present and create one thread per CPU.
@@ -162,8 +172,7 @@
<term>-p <replaceable class="parameter">port</replaceable></term> <term>-p <replaceable class="parameter">port</replaceable></term>
<listitem> <listitem>
<para> <para>
Listen for queries on port <replaceable Listen for queries on port <replaceable class="parameter">port</replaceable>. If not
class="parameter">port</replaceable>. If not
specified, the default is port 53. specified, the default is port 53.
</para> </para>
</listitem> </listitem>
@@ -187,9 +196,8 @@
<varlistentry> <varlistentry>
<term>-t <replaceable class="parameter">directory</replaceable></term> <term>-t <replaceable class="parameter">directory</replaceable></term>
<listitem> <listitem>
<para> <para><function>chroot()</function>
<function>chroot()</function> to <replaceable to <replaceable class="parameter">directory</replaceable> after
class="parameter">directory</replaceable> after
processing the command line arguments, but before processing the command line arguments, but before
reading the configuration file. reading the configuration file.
</para> </para>
@@ -209,9 +217,8 @@
<varlistentry> <varlistentry>
<term>-u <replaceable class="parameter">user</replaceable></term> <term>-u <replaceable class="parameter">user</replaceable></term>
<listitem> <listitem>
<para> <para><function>setuid()</function>
<function>setuid()</function> to <replaceable to <replaceable class="parameter">user</replaceable> after completing
class="parameter">user</replaceable> after completing
privileged operations, such as creating sockets that privileged operations, such as creating sockets that
listen on privileged ports. listen on privileged ports.
</para> </para>
@@ -219,10 +226,12 @@
<para> <para>
On Linux, <command>named</command> uses the kernel's On Linux, <command>named</command> uses the kernel's
capability mechanism to drop all root privileges capability mechanism to drop all root privileges
except the ability to <function>bind()</function> to a except the ability to <function>bind()</function> to
a
privileged port and set process resource limits. privileged port and set process resource limits.
Unfortunately, this means that the <option>-u</option> Unfortunately, this means that the <option>-u</option>
option only works when <command>named</command> is run option only works when <command>named</command> is
run
on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or
later, since previous kernels did not allow privileges later, since previous kernels did not allow privileges
to be retained after <function>setuid()</function>. to be retained after <function>setuid()</function>.
@@ -244,8 +253,7 @@
<term>-x <replaceable class="parameter">cache-file</replaceable></term> <term>-x <replaceable class="parameter">cache-file</replaceable></term>
<listitem> <listitem>
<para> <para>
Load data from <replaceable Load data from <replaceable class="parameter">cache-file</replaceable> into the
class="parameter">cache-file</replaceable> into the
cache of the default view. cache of the default view.
</para> </para>
<warning> <warning>
@@ -302,9 +310,9 @@
<title>CONFIGURATION</title> <title>CONFIGURATION</title>
<para> <para>
The <command>named</command> configuration file is too complex The <command>named</command> configuration file is too complex
to describe in detail here. A complete description is to describe in detail here. A complete description is provided
provided in the <citetitle>BIND 9 Administrator Reference in the
Manual</citetitle>. <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
</para> </para>
</refsect1> </refsect1>
@@ -337,17 +345,14 @@
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citetitle>RFC 1033</citetitle>,
<citetitle>RFC 1033</citetitle>,
<citetitle>RFC 1034</citetitle>, <citetitle>RFC 1034</citetitle>,
<citetitle>RFC 1035</citetitle>, <citetitle>RFC 1035</citetitle>,
<citerefentry> <citerefentry>
<refentrytitle>rndc</refentrytitle> <refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>
<manvolnum>8</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwresd</refentrytitle> <refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>
<manvolnum>8</manvolnum>
</citerefentry>, </citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>. <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
</para> </para>
@@ -355,15 +360,11 @@
<refsect1> <refsect1>
<title>AUTHOR</title> <title>AUTHOR</title>
<para> <para><corpauthor>Internet Systems Consortium</corpauthor>
<corpauthor>Internet Systems Consortium</corpauthor>
</para> </para>
</refsect1> </refsect1>
</refentry> </refentry><!--
<!--
- Local variables: - Local variables:
- mode: sgml - mode: sgml
- End: - End:

1186
bin/nsupdate/nsupdate.docbook
View File

File diff suppressed because it is too large Load Diff

70
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) 2004 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2001, 2003 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: rndc-confgen.docbook,v 1.8 2005/05/11 05:55:37 sra Exp $ -->
<!-- $Id: rndc-confgen.docbook,v 1.7 2004/06/03 02:22:34 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Aug 27, 2001</date> <date>Aug 27, 2001</date>
@@ -34,6 +34,18 @@
<refpurpose>rndc key generation tool</refpurpose> <refpurpose>rndc key generation tool</refpurpose>
</refnamediv> </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> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>rndc-confgen</command> <command>rndc-confgen</command>
@@ -52,8 +64,8 @@
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><command>rndc-confgen</command>
<command>rndc-confgen</command> generates configuration files generates configuration files
for <command>rndc</command>. It can be used as a for <command>rndc</command>. It can be used as a
convenient alternative to writing the convenient alternative to writing the
<filename>rndc.conf</filename> file <filename>rndc.conf</filename> file
@@ -80,7 +92,8 @@
This creates a file <filename>rndc.key</filename> This creates a file <filename>rndc.key</filename>
in <filename>/etc</filename> (or whatever in <filename>/etc</filename> (or whatever
<varname>sysconfdir</varname> <varname>sysconfdir</varname>
was specified as when <acronym>BIND</acronym> was built) was specified as when <acronym>BIND</acronym> was
built)
that is read by both <command>rndc</command> that is read by both <command>rndc</command>
and <command>named</command> on startup. The and <command>named</command> on startup. The
<filename>rndc.key</filename> file defines a default <filename>rndc.key</filename> file defines a default
@@ -91,7 +104,8 @@
</para> </para>
<para> <para>
Running <command>rndc-confgen -a</command> allows Running <command>rndc-confgen -a</command> allows
BIND 9 and <command>rndc</command> to be used as drop-in BIND 9 and <command>rndc</command> to be used as
drop-in
replacements for BIND 8 and <command>ndc</command>, replacements for BIND 8 and <command>ndc</command>,
with no changes to the existing BIND 8 with no changes to the existing BIND 8
<filename>named.conf</filename> file. <filename>named.conf</filename> file.
@@ -100,7 +114,8 @@
If a more elaborate configuration than that If a more elaborate configuration than that
generated by <command>rndc-confgen -a</command> generated by <command>rndc-confgen -a</command>
is required, for example if rndc is to be used remotely, is required, for example if rndc is to be used remotely,
you should run <command>rndc-confgen</command> without the you should run <command>rndc-confgen</command> without
the
<command>-a</command> option and set up a <command>-a</command> option and set up a
<filename>rndc.conf</filename> and <filename>rndc.conf</filename> and
<filename>named.conf</filename> <filename>named.conf</filename>
@@ -169,7 +184,8 @@
authorization. If the operating authorization. If the operating
system does not provide a <filename>/dev/random</filename> system does not provide a <filename>/dev/random</filename>
or equivalent device, the default source of randomness or equivalent device, the default source of randomness
is keyboard input. <filename>randomdev</filename> specifies is keyboard input. <filename>randomdev</filename>
specifies
the name of a character device or file containing random the name of a character device or file containing random
data to be used instead of the default. The special value data to be used instead of the default. The special value
<filename>keyboard</filename> indicates that keyboard <filename>keyboard</filename> indicates that keyboard
@@ -207,9 +223,12 @@
<term>-u <replaceable class="parameter">user</replaceable></term> <term>-u <replaceable class="parameter">user</replaceable></term>
<listitem> <listitem>
<para> <para>
Used with the <command>-a</command> option to set the owner Used with the <command>-a</command> option to set the
of the <filename>rndc.key</filename> file generated. If owner
<command>-t</command> is also specified only the file in 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. the chroot area has its owner changed.
</para> </para>
</listitem> </listitem>
@@ -224,8 +243,7 @@
To allow <command>rndc</command> to be used with To allow <command>rndc</command> to be used with
no manual configuration, run no manual configuration, run
</para> </para>
<para> <para><userinput>rndc-confgen -a</userinput>
<userinput>rndc-confgen -a</userinput>
</para> </para>
<para> <para>
To print a sample <filename>rndc.conf</filename> file and To print a sample <filename>rndc.conf</filename> file and
@@ -233,25 +251,20 @@
statements to be manually inserted into <filename>named.conf</filename>, statements to be manually inserted into <filename>named.conf</filename>,
run run
</para> </para>
<para> <para><userinput>rndc-confgen</userinput>
<userinput>rndc-confgen</userinput>
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>
<refentrytitle>rndc</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>rndc.conf</refentrytitle> <refentrytitle>rndc.conf</refentrytitle><manvolnum>5</manvolnum>
<manvolnum>5</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>named</refentrytitle> <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
<manvolnum>8</manvolnum>
</citerefentry>, </citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>. <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
</para> </para>
@@ -259,14 +272,11 @@
<refsect1> <refsect1>
<title>AUTHOR</title> <title>AUTHOR</title>
<para> <para><corpauthor>Internet Systems Consortium</corpauthor>
<corpauthor>Internet Systems Consortium</corpauthor>
</para> </para>
</refsect1> </refsect1>
</refentry> </refentry><!--
<!--
- Local variables: - Local variables:
- mode: sgml - mode: sgml
- End: - End:

90
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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: rndc.conf.docbook,v 1.10 2005/05/11 05:55:37 sra Exp $ -->
<!-- $Id: rndc.conf.docbook,v 1.9 2005/04/07 03:49:59 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>June 30, 2000</date> <date>June 30, 2000</date>
@@ -34,6 +34,19 @@
<refpurpose>rndc configuration file</refpurpose> <refpurpose>rndc configuration file</refpurpose>
</refnamediv> </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> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>rndc.conf</command> <command>rndc.conf</command>
@@ -42,8 +55,7 @@
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><filename>rndc.conf</filename> is the configuration file
<filename>rndc.conf</filename> is the configuration file
for <command>rndc</command>, the BIND 9 name server control for <command>rndc</command>, the BIND 9 name server control
utility. This file has a similar structure and syntax to utility. This file has a similar structure and syntax to
<filename>named.conf</filename>. Statements are enclosed <filename>named.conf</filename>. Statements are enclosed
@@ -60,8 +72,7 @@
<para> <para>
Unix style: # to end of line Unix style: # to end of line
</para> </para>
<para> <para><filename>rndc.conf</filename> is much simpler than
<filename>rndc.conf</filename> is much simpler than
<filename>named.conf</filename>. The file uses three <filename>named.conf</filename>. The file uses three
statements: an options statement, a server statement statements: an options statement, a server statement
and a key statement. and a key statement.
@@ -107,18 +118,22 @@
The <option>key</option> statement begins with an identifying The <option>key</option> statement begins with an identifying
string, the name of the key. The statement has two clauses. string, the name of the key. The statement has two clauses.
<option>algorithm</option> identifies the encryption algorithm <option>algorithm</option> identifies the encryption algorithm
for <command>rndc</command> to use; currently only HMAC-MD5 is for <command>rndc</command> to use; currently only HMAC-MD5
is
supported. This is followed by a secret clause which contains supported. This is followed by a secret clause which contains
the base-64 encoding of the algorithm's encryption key. The the base-64 encoding of the algorithm's encryption key. The
base-64 string is enclosed in double quotes. base-64 string is enclosed in double quotes.
</para> </para>
<para> <para>
There are two common ways to generate the base-64 string for the There are two common ways to generate the base-64 string for the
secret. The BIND 9 program <command>rndc-confgen</command> can secret. The BIND 9 program <command>rndc-confgen</command>
can
be used to generate a random key, or the be used to generate a random key, or the
<command>mmencode</command> program, also known as <command>mmencode</command> program, also known as
<command>mimencode</command>, can be used to generate a base-64 <command>mimencode</command>, can be used to generate a
string from known input. <command>mmencode</command> does not base-64
string from known input. <command>mmencode</command> does
not
ship with BIND 9 but is available on many systems. See the ship with BIND 9 but is available on many systems. See the
EXAMPLE section for sample command lines for each. EXAMPLE section for sample command lines for each.
</para> </para>
@@ -127,34 +142,44 @@
<refsect1> <refsect1>
<title>EXAMPLE</title> <title>EXAMPLE</title>
<programlisting> <para><programlisting>
options { options {
default-server localhost; default-server localhost;
default-key samplekey; default-key samplekey;
}; };
</programlisting>
</para>
<para><programlisting>
server localhost { server localhost {
key samplekey; key samplekey;
}; };
</programlisting>
</para>
<para><programlisting>
server testserver { server testserver {
key testkey; key testkey;
addresses { localhost port 5353; }; addresses { localhost port 5353; };
}; };
</programlisting>
</para>
<para><programlisting>
key samplekey { key samplekey {
algorithm hmac-md5; algorithm hmac-md5;
secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz"; secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
}; };
</programlisting>
</para>
<para><programlisting>
key testkey { key testkey {
algorithm hmac-md5; algorithm hmac-md5;
secret "R3HI8P6BKw9ZwXwN3VZKuQ=="; secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
} }
</programlisting> </programlisting>
</para>
<para> <para>
In the above example, <command>rndc</command> will by default use In the above example, <command>rndc</command> will by
default use
the server at localhost (127.0.0.1) and the key called samplekey. the server at localhost (127.0.0.1) and the key called samplekey.
Commands to the localhost server will use the samplekey key, which Commands to the localhost server will use the samplekey key, which
must also be defined in the server's configuration file with the must also be defined in the server's configuration file with the
@@ -169,11 +194,11 @@
<para> <para>
To generate a random secret with <command>rndc-confgen</command>: To generate a random secret with <command>rndc-confgen</command>:
</para> </para>
<para> <para><userinput>rndc-confgen</userinput>
<userinput>rndc-confgen</userinput>
</para> </para>
<para> <para>
A complete <filename>rndc.conf</filename> file, including the A complete <filename>rndc.conf</filename> file, including
the
randomly generated key, will be written to the standard randomly generated key, will be written to the standard
output. Commented out <option>key</option> and output. Commented out <option>key</option> and
<option>controls</option> statements for <option>controls</option> statements for
@@ -182,8 +207,7 @@
<para> <para>
To generate a base-64 secret with <command>mmencode</command>: To generate a base-64 secret with <command>mmencode</command>:
</para> </para>
<para> <para><userinput>echo "known plaintext for a secret" | mmencode</userinput>
<userinput>echo "known plaintext for a secret" | mmencode</userinput>
</para> </para>
</refsect1> </refsect1>
@@ -200,18 +224,14 @@
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>
<refentrytitle>rndc</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>rndc-confgen</refentrytitle> <refentrytitle>rndc-confgen</refentrytitle><manvolnum>8</manvolnum>
<manvolnum>8</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>mmencode</refentrytitle> <refentrytitle>mmencode</refentrytitle><manvolnum>1</manvolnum>
<manvolnum>1</manvolnum>
</citerefentry>, </citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>. <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
</para> </para>
@@ -219,16 +239,12 @@
<refsect1> <refsect1>
<title>AUTHOR</title> <title>AUTHOR</title>
<para> <para><corpauthor>Internet Systems Consortium</corpauthor>
<corpauthor>Internet Systems Consortium</corpauthor>
</para> </para>
</refsect1> </refsect1>
</refentry> </refentry><!--
<!--
- Local variables: - Local variables:
- mode: sgml - mode: sgml
- End: - End:
--> -->

78
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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: rndc.docbook,v 1.12 2005/05/11 05:55:37 sra Exp $ -->
<!-- $Id: rndc.docbook,v 1.11 2005/04/07 03:50:00 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>June 30, 2000</date> <date>June 30, 2000</date>
@@ -34,6 +34,19 @@
<refpurpose>name server control utility</refpurpose> <refpurpose>name server control utility</refpurpose>
</refnamediv> </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> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>rndc</command> <command>rndc</command>
@@ -50,8 +63,8 @@
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><command>rndc</command>
<command>rndc</command> controls the operation of a name controls the operation of a name
server. It supersedes the <command>ndc</command> utility server. It supersedes the <command>ndc</command> utility
that was provided in old BIND releases. If that was provided in old BIND releases. If
<command>rndc</command> is invoked with no command line <command>rndc</command> is invoked with no command line
@@ -59,8 +72,8 @@
supported commands and the available options and their supported commands and the available options and their
arguments. arguments.
</para> </para>
<para> <para><command>rndc</command>
<command>rndc</command> communicates with the name server communicates with the name server
over a TCP connection, sending commands authenticated with over a TCP connection, sending commands authenticated with
digital signatures. In the current versions of digital signatures. In the current versions of
<command>rndc</command> and <command>named</command> named <command>rndc</command> and <command>named</command> named
@@ -71,8 +84,8 @@
over the channel must be signed by a key_id known to the over the channel must be signed by a key_id known to the
server. server.
</para> </para>
<para> <para><command>rndc</command>
<command>rndc</command> reads a configuration file to reads a configuration file to
determine how to contact the name server and decide what determine how to contact the name server and decide what
algorithm and key it should use. algorithm and key it should use.
</para> </para>
@@ -112,7 +125,8 @@
Use <replaceable class="parameter">key-file</replaceable> Use <replaceable class="parameter">key-file</replaceable>
as the key file instead of the default, as the key file instead of the default,
<filename>/etc/rndc.key</filename>. The key in <filename>/etc/rndc.key</filename>. The key in
<filename>/etc/rndc.key</filename> will be used to authenticate <filename>/etc/rndc.key</filename> will be used to
authenticate
commands sent to the server if the <replaceable class="parameter">config-file</replaceable> commands sent to the server if the <replaceable class="parameter">config-file</replaceable>
does not exist. does not exist.
</para> </para>
@@ -122,11 +136,11 @@
<varlistentry> <varlistentry>
<term>-s <replaceable class="parameter">server</replaceable></term> <term>-s <replaceable class="parameter">server</replaceable></term>
<listitem> <listitem>
<para> <para><replaceable class="parameter">server</replaceable> is
<replaceable class="parameter">server</replaceable> is
the name or address of the server which matches a the name or address of the server which matches a
server statement in the configuration file for server statement in the configuration file for
<command>rndc</command>. If no server is supplied on the <command>rndc</command>. If no server is supplied on
the
command line, the host named by the default-server clause command line, the host named by the default-server clause
in the option statement of the configuration file will be in the option statement of the configuration file will be
used. used.
@@ -139,7 +153,8 @@
<listitem> <listitem>
<para> <para>
Send commands to TCP port Send commands to TCP port
<replaceable class="parameter">port</replaceable> instead <replaceable class="parameter">port</replaceable>
instead
of BIND 9's default control channel port, 953. of BIND 9's default control channel port, 953.
</para> </para>
</listitem> </listitem>
@@ -160,7 +175,8 @@
<para> <para>
Use the key <replaceable class="parameter">keyid</replaceable> Use the key <replaceable class="parameter">keyid</replaceable>
from the configuration file. from the configuration file.
<replaceable class="parameter">keyid</replaceable> must be <replaceable class="parameter">keyid</replaceable>
must be
known by named with the same algorithm and secret string known by named with the same algorithm and secret string
in order for control message validation to succeed. in order for control message validation to succeed.
If no <replaceable class="parameter">keyid</replaceable> If no <replaceable class="parameter">keyid</replaceable>
@@ -181,15 +197,16 @@
<para> <para>
For the complete set of commands supported by <command>rndc</command>, For the complete set of commands supported by <command>rndc</command>,
see the BIND 9 Administrator Reference Manual or run 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> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>LIMITATIONS</title> <title>LIMITATIONS</title>
<para> <para><command>rndc</command>
<command>rndc</command> does not yet support all the commands of does not yet support all the commands of
the BIND 8 <command>ndc</command> utility. the BIND 8 <command>ndc</command> utility.
</para> </para>
<para> <para>
@@ -203,22 +220,17 @@
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>rndc.conf</refentrytitle><manvolnum>5</manvolnum>
<refentrytitle>rndc.conf</refentrytitle>
<manvolnum>5</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>named</refentrytitle> <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
<manvolnum>8</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>named.conf</refentrytitle> <refentrytitle>named.conf</refentrytitle><manvolnum>5</manvolnum>
<manvolnum>5</manvolnum>
</citerefentry> </citerefentry>
<citerefentry> <citerefentry>
<refentrytitle>ndc</refentrytitle> <refentrytitle>ndc</refentrytitle><manvolnum>8</manvolnum>
<manvolnum>8</manvolnum>
</citerefentry>, </citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>. <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
</para> </para>
@@ -226,16 +238,12 @@
<refsect1> <refsect1>
<title>AUTHOR</title> <title>AUTHOR</title>
<para> <para><corpauthor>Internet Systems Consortium</corpauthor>
<corpauthor>Internet Systems Consortium</corpauthor>
</para> </para>
</refsect1> </refsect1>
</refentry> </refentry><!--
<!--
- Local variables: - Local variables:
- mode: sgml - mode: sgml
- End: - End:
--> -->

171
configure.in
View File

@@ -18,7 +18,7 @@ AC_DIVERT_PUSH(1)dnl
esyscmd([sed "s/^/# /" COPYRIGHT])dnl esyscmd([sed "s/^/# /" COPYRIGHT])dnl
AC_DIVERT_POP()dnl AC_DIVERT_POP()dnl
AC_REVISION($Revision: 1.375 $) AC_REVISION($Revision: 1.376 $)
AC_INIT(lib/dns/name.c) AC_INIT(lib/dns/name.c)
AC_PREREQ(2.13) AC_PREREQ(2.13)
@@ -1836,25 +1836,29 @@ AC_SUBST(ISC_PLATFORM_HAVEIFNAMETOINDEX)
# a developer editing the documentation source. # 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. # Look for TeX.
# #
AC_PATH_PROGS(JADETEX, jadetex, jadetex) AC_PATH_PROGS(LATEX, latex, latex)
AC_SUBST(JADETEX) AC_SUBST(LATEX)
AC_PATH_PROGS(PDFJADETEX, pdfjadetex, pdfjadetex) AC_PATH_PROGS(PDFLATEX, pdflatex, pdflatex)
AC_SUBST(PDFJADETEX) 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) # Subroutine for searching for an ordinary file (e.g., a stylesheet)
@@ -1891,74 +1895,60 @@ AC_SUBST($1)
]) ])
# #
# Look for the SGML catalog. # Look for Docbook-XSL stylesheets. Location probably varies by
# Its location varies, so far we have seen: # 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 docbook_xsl_trees="/usr/pkg/share/xsl /usr/local/share/xsl /usr/share/xsl"
# Linux /usr/local/share/dsssl/docbook/catalog
# /usr/share/sgml/docbook/dsssl-stylesheets/catalog
# #
catalogpath="" # Look for stylesheets we need.
for d in $sgmltrees #
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 do
catalogpath="$catalogpath $d" dd=$d/db2latex/xsl/figures
for s in docbook/dsssl-stylesheets if test -d $dd
do then
catalogpath="$catalogpath $d/$s" XSLT_DB2LATEX_ADMONITIONS=$dd
done AC_MSG_RESULT($dd)
break
fi
done done
NOM_PATH_FILE(SGMLCATALOG, catalog, $catalogpath) if test "X$XSLT_DB2LATEX_ADMONITIONS" = "X"
then
# AC_MSG_RESULT(not found)
# Look for the HTML stylesheet html/docbook.dsl, used for XSLT_DB2LATEX_ADMONITIONS=db2latex/xsl/figures
# formatting man pages in HTML. Its location varies, fi
# so far we have seen: AC_SUBST(XSLT_DB2LATEX_ADMONITIONS)
#
# 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)
# #
# Substitutions # Substitutions
@@ -2016,6 +2006,20 @@ LIBBIND9_API=$srcdir/lib/bind9/api
AC_SUBST_FILE(LIBLWRES_API) AC_SUBST_FILE(LIBLWRES_API)
LIBLWRES_API=$srcdir/lib/lwres/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( AC_OUTPUT(
make/rules make/rules
make/includes make/includes
@@ -2086,14 +2090,13 @@ AC_OUTPUT(
bin/dnssec/Makefile bin/dnssec/Makefile
doc/Makefile doc/Makefile
doc/arm/Makefile doc/arm/Makefile
doc/arm/nominum-docbook-html.dsl
doc/arm/nominum-docbook-print.dsl
doc/arm/validate.sh
doc/misc/Makefile doc/misc/Makefile
docutil/docbook2man-wrapper.sh
isc-config.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. # Tell Emacs to edit this file in shell mode.
# Local Variables: # Local Variables:

13
doc/arm/.cvsignore
View File

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

13654
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 # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
# PERFORMANCE OF THIS SOFTWARE. # 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@ srcdir = @srcdir@
VPATH = @srcdir@ VPATH = @srcdir@
@@ -23,47 +23,41 @@ top_srcdir = @top_srcdir@
MANOBJS = Bv9ARM.html MANOBJS = Bv9ARM.html
PDFOBJS = Bv9ARM.pdf
distclean:: distclean::
rm -f validate.sh rm -f validate.sh
rm -f nominum-docbook-html.dsl nominum-docbook-print.dsl rm -f nominum-docbook-html.dsl nominum-docbook-print.dsl
rm -f HTML.index HTML.manifest rm -f HTML.index HTML.manifest
doc man:: ${MANOBJS} doc man:: ${MANOBJS} ${PDFOBJS}
docclean manclean maintainer-clean:: clean::
rm -f *.html 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 docclean manclean maintainer-clean:: clean
${OPENJADE} -v \ rm -f *.html *.pdf
-c ${SGMLCATALOG} \
-t sgml \
-d ./nominum-docbook-html.dsl \
${XMLDCL} ./Bv9ARM-book.xml
rm -f HTML.index HTML.manifest
Bv9ARM-book.rtf: Bv9ARM-book.xml nominum-docbook-print.dsl Bv9ARM.html: Bv9ARM-book.xml
${OPENJADE} -v \ ${XSLTPROC} --stringparam root.filename Bv9ARM \
-c ${SGMLCATALOG} \ ${top_srcdir}/doc/xsl/isc-docbook-chunk.xsl \
-t rtf \ Bv9ARM-book.xml
-d ./nominum-docbook-print.dsl \
${XMLDCL} ./Bv9ARM-book.xml
Bv9ARM-book.tex: Bv9ARM-book.xml nominum-docbook-print.dsl Bv9ARM.tex: Bv9ARM-book.xml
${OPENJADE} -v \ ${XSLTPROC} ${top_srcdir}/doc/xsl/pre-latex.xsl Bv9ARM-book.xml | \
-c ${SGMLCATALOG} \ ${XSLTPROC} ${top_srcdir}/doc/xsl/isc-docbook-latex.xsl - | \
-d ./nominum-docbook-print.dsl \ @PERL@ latex-fixup.pl >$@.tmp
-t tex \ if test -s $@.tmp; then mv $@.tmp $@; else rm -f $@.tmp; exit 1; fi
${XMLDCL} ./Bv9ARM-book.xml
Bv9ARM-book.dvi: Bv9ARM-book.tex Bv9ARM.dvi: Bv9ARM.tex
rm -f Bv9ARM-book.aux Bv9ARM-book.dvi Bv9ARM-book.log rm -f Bv9ARM-book.aux Bv9ARM-book.dvi Bv9ARM-book.log
${JADETEX} ./Bv9ARM-book.tex || true ${LATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@
${JADETEX} ./Bv9ARM-book.tex || true ${LATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@
${JADETEX} ./Bv9ARM-book.tex || true ${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 rm -f Bv9ARM-book.aux Bv9ARM-book.pdf Bv9ARM-book.log
${PDFJADETEX} ./Bv9ARM-book.tex || true ${PDFLATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@
${PDFJADETEX} ./Bv9ARM-book.tex || true ${PDFLATEX} '\batchmode\input Bv9ARM.tex' || rm -f $@
${PDFJADETEX} ./Bv9ARM-book.tex || true ${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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres.docbook,v 1.6 2005/05/11 05:55:39 sra Exp $ -->
<!-- $Id: lwres.docbook,v 1.5 2005/04/07 03:50:00 marka Exp $ -->
<refentry> <refentry>
<refentryinfo>
<date>Jun 30, 2000</date> <refentryinfo>
</refentryinfo> <date>Jun 30, 2000</date>
<refmeta> </refentryinfo>
<refentrytitle>lwres</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres</refname>
<refpurpose>introduction to the lightweight resolver library</refpurpose>
</refnamediv>
<refsynopsisdiv> <refmeta>
<funcsynopsis> <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> <funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
</funcsynopsis> </funcsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para>
The BIND 9 lightweight resolver library is a simple, name service The BIND 9 lightweight resolver library is a simple, name service
independent stub resolver library. It provides hostname-to-address independent stub resolver library. It provides hostname-to-address
and address-to-hostname lookup services to applications by and address-to-hostname lookup services to applications by
transmitting lookup requests to a resolver daemon transmitting lookup requests to a resolver daemon
<command>lwresd</command> <command>lwresd</command>
running on the local host. The resover daemon performs the running on the local host. The resover daemon performs the
lookup using the DNS or possibly other name service protocols, lookup using the DNS or possibly other name service protocols,
and returns the results to the application through the library. and returns the results to the application through the library.
The library and resolver daemon communicate using a simple The library and resolver daemon communicate using a simple
UDP-based protocol. UDP-based protocol.
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>OVERVIEW</title> <title>OVERVIEW</title>
<para> <para>
The lwresd library implements multiple name service APIs. The lwresd library implements multiple name service APIs.
The standard The standard
<function>gethostbyname()</function>, <function>gethostbyname()</function>,
<function>gethostbyaddr()</function>, <function>gethostbyaddr()</function>,
<function>gethostbyname_r()</function>, <function>gethostbyname_r()</function>,
<function>gethostbyaddr_r()</function>, <function>gethostbyaddr_r()</function>,
<function>getaddrinfo()</function>, <function>getaddrinfo()</function>,
<function>getipnodebyname()</function>, <function>getipnodebyname()</function>,
and and
<function>getipnodebyaddr()</function> <function>getipnodebyaddr()</function>
functions are all supported. To allow the lwres library to coexist functions are all supported. To allow the lwres library to coexist
with system libraries that define functions of the same name, with system libraries that define functions of the same name,
the library defines these functions with names prefixed by the library defines these functions with names prefixed by
<literal>lwres_</literal>. <literal>lwres_</literal>.
To define the standard names, applications must include the To define the standard names, applications must include the
header file header file
<filename>&lt;lwres/netdb.h&gt;</filename> <filename>&lt;lwres/netdb.h&gt;</filename>
which contains macro definitions mapping the standard function names which contains macro definitions mapping the standard function names
into into
<literal>lwres_</literal> <literal>lwres_</literal>
prefixed ones. Operating system vendors who integrate the lwres prefixed ones. Operating system vendors who integrate the lwres
library into their base distributions should rename the functions library into their base distributions should rename the functions
in the library proper so that the renaming macros are not needed. in the library proper so that the renaming macros are not needed.
</para> </para>
<para> <para>
The library also provides a native API consisting of the functions The library also provides a native API consisting of the functions
<function>lwres_getaddrsbyname()</function> <function>lwres_getaddrsbyname()</function>
and and
<function>lwres_getnamebyaddr()</function>. <function>lwres_getnamebyaddr()</function>.
These may be called by applications that require more detailed These may be called by applications that require more detailed
control over the lookup process than the standard functions control over the lookup process than the standard functions
provide. provide.
</para> </para>
<para> <para>
In addition to these name service independent address lookup In addition to these name service independent address lookup
functions, the library implements a new, experimental API functions, the library implements a new, experimental API
for looking up arbitrary DNS resource records, using the for looking up arbitrary DNS resource records, using the
<function>lwres_getaddrsbyname()</function> <function>lwres_getaddrsbyname()</function>
function. function.
</para> </para>
<para> <para>
Finally, there is a low-level API for converting lookup Finally, there is a low-level API for converting lookup
requests and responses to and from raw lwres protocol packets. requests and responses to and from raw lwres protocol packets.
This API can be used by clients requiring nonblocking operation, This API can be used by clients requiring nonblocking operation,
and is also used when implementing the server side of the lwres and is also used when implementing the server side of the lwres
protocol, for example in the protocol, for example in the
<command>lwresd</command> <command>lwresd</command>
resolver daemon. The use of this low-level API in clients resolver daemon. The use of this low-level API in clients
and servers is outlined in the following sections. and servers is outlined in the following sections.
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title> <title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title>
<para> <para>
When a client program wishes to make an lwres request using the When a client program wishes to make an lwres request using the
native low-level API, it typically performs the following native low-level API, it typically performs the following
sequence of actions. sequence of actions.
</para> </para>
<para> <para>
(1) Allocate or use an existing <type>lwres_packet_t</type>, (1) Allocate or use an existing <type>lwres_packet_t</type>,
called <varname>pkt</varname> below. called <varname>pkt</varname> below.
</para> </para>
<para> <para>
(2) Set <structfield>pkt.recvlength</structfield> to the maximum length we will accept. (2) Set <structfield>pkt.recvlength</structfield> to the maximum length
This is done so the receiver of our packets knows how large our receive we will accept.
buffer is. The "default" is a constant in This is done so the receiver of our packets knows how large our receive
<filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>. buffer is. The "default" is a constant in
</para> <filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>.
<para> </para>
(3) Set <structfield>pkt.serial</structfield> <para>
to a unique serial number. This value is echoed (3) Set <structfield>pkt.serial</structfield>
back to the application by the remote server. to a unique serial number. This value is echoed
</para> back to the application by the remote server.
<para> </para>
(4) Set <structfield>pkt.pktflags</structfield>. Usually this is set to 0. <para>
</para> (4) Set <structfield>pkt.pktflags</structfield>. Usually this is set to
<para> 0.
(5) Set <structfield>pkt.result</structfield> to 0. </para>
</para> <para>
<para> (5) Set <structfield>pkt.result</structfield> to 0.
(6) Call <function>lwres_*request_render()</function>, </para>
or marshall in the data using the primitives <para>
such as <function>lwres_packet_render()</function> (6) Call <function>lwres_*request_render()</function>,
and storing the packet data. or marshall in the data using the primitives
</para> such as <function>lwres_packet_render()</function>
<para> and storing the packet data.
(7) Transmit the resulting buffer. </para>
</para> <para>
<para> (7) Transmit the resulting buffer.
(8) Call <function>lwres_*response_parse()</function> </para>
to parse any packets received. <para>
</para> (8) Call <function>lwres_*response_parse()</function>
<para> to parse any packets received.
(9) Verify that the opcode and serial match a request, and process the </para>
packet specific information contained in the body. <para>
</para> (9) Verify that the opcode and serial match a request, and process the
</refsect1> packet specific information contained in the body.
<refsect1> </para>
<title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title> </refsect1>
<para> <refsect1>
When implementing the server side of the lightweight resolver <title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title>
protocol using the lwres library, a sequence of actions like the <para>
following is typically involved in processing each request packet. When implementing the server side of the lightweight resolver
</para> protocol using the lwres library, a sequence of actions like the
<para> following is typically involved in processing each request packet.
Note that the same <type>lwres_packet_t</type> is used </para>
in both the <function>_parse()</function> and <function>_render()</function> calls, <para>
with only a few modifications made Note that the same <type>lwres_packet_t</type> is used
to the packet header's contents between uses. This method is recommended in both the <function>_parse()</function> and <function>_render()</function> calls,
as it keeps the serial, opcode, and other fields correct. with only a few modifications made
</para> to the packet header's contents between uses. This method is
<para> recommended
(1) When a packet is received, call <function>lwres_*request_parse()</function> to as it keeps the serial, opcode, and other fields correct.
unmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below) </para>
as well as a data specific type, such as <type>lwres_gabnrequest_t</type>. <para>
</para> (1) When a packet is received, call <function>lwres_*request_parse()</function> to
<para> unmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below)
(2) Process the request in the data specific type. as well as a data specific type, such as <type>lwres_gabnrequest_t</type>.
</para> </para>
<para> <para>
(3) Set the <structfield>pkt.result</structfield>, (2) Process the request in the data specific type.
<structfield>pkt.recvlength</structfield> as above. All other fields can </para>
be left untouched since they were filled in by the <function>*_parse()</function> call <para>
above. If using <function>lwres_*response_render()</function>, (3) Set the <structfield>pkt.result</structfield>,
<structfield>pkt.pktflags</structfield> will be set up <structfield>pkt.recvlength</structfield> as above. All other fields
properly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be can
set. be left untouched since they were filled in by the <function>*_parse()</function> call
</para> above. If using <function>lwres_*response_render()</function>,
<para> <structfield>pkt.pktflags</structfield> will be set up
(4) Call the data specific rendering function, such as properly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be
<function>lwres_gabnresponse_render()</function>. set.
</para> </para>
<para> <para>
(5) Send the resulting packet to the client. (4) Call the data specific rendering function, such as
</para> <function>lwres_gabnresponse_render()</function>.
<para> </para>
</para> <para>
</refsect1> (5) Send the resulting packet to the client.
<refsect1> </para>
<title>SEE ALSO</title> <para></para>
<para> </refsect1>
<citerefentry> <refsect1>
<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum> <title>SEE ALSO</title>
</citerefentry>, <para><citerefentry>
<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum> <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum> <refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>. </citerefentry>.
</para> </para>
</refsect1> </refsect1>
</refentry> </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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_buffer.docbook,v 1.6 2005/05/11 05:55:39 sra Exp $ -->
<!-- $Id: lwres_buffer.docbook,v 1.5 2005/04/07 03:50:00 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Jun 30, 2000</date> <date>Jun 30, 2000</date>
</refentryinfo> </refentryinfo>
<refmeta> <refmeta>
<refentrytitle>lwres_buffer</refentrytitle> <refentrytitle>lwres_buffer</refentrytitle>
<manvolnum>3</manvolnum> <manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <docinfo>
<refname>lwres_buffer_init</refname> <copyright>
<refname>lwres_buffer_invalidate</refname> <year>2004</year>
<refname>lwres_buffer_add</refname> <year>2005</year>
<refname>lwres_buffer_subtract</refname> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
<refname>lwres_buffer_clear</refname> </copyright>
<refname>lwres_buffer_first</refname> <copyright>
<refname>lwres_buffer_forward</refname> <year>2000</year>
<refname>lwres_buffer_back</refname> <year>2001</year>
<refname>lwres_buffer_getuint8</refname> <holder>Internet Software Consortium</holder>
<refname>lwres_buffer_putuint8</refname> </copyright>
<refname>lwres_buffer_getuint16</refname> </docinfo>
<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>
<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> <funcsynopsisinfo>
#include &lt;lwres/lwbuffer.h&gt; #include &lt;lwres/lwbuffer.h&gt;
</funcsynopsisinfo> </funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_buffer_init</function></funcdef> <function>lwres_buffer_init</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>void *base</paramdef> <paramdef>void *<parameter>base</parameter></paramdef>
<paramdef>unsigned int length</paramdef> <paramdef>unsigned int <parameter>length</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_buffer_invalidate</function></funcdef> <function>lwres_buffer_invalidate</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_buffer_add</function></funcdef> <function>lwres_buffer_add</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>unsigned int n</paramdef> <paramdef>unsigned int <parameter>n</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_buffer_subtract</function></funcdef> <function>lwres_buffer_subtract</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>unsigned int n</paramdef> <paramdef>unsigned int <parameter>n</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_buffer_clear</function></funcdef> <function>lwres_buffer_clear</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_buffer_first</function></funcdef> <function>lwres_buffer_first</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_buffer_forward</function></funcdef> <function>lwres_buffer_forward</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>unsigned int n</paramdef> <paramdef>unsigned int <parameter>n</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_buffer_back</function></funcdef> <function>lwres_buffer_back</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>unsigned int n</paramdef> <paramdef>unsigned int <parameter>n</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_uint8_t lwres_uint8_t
<function>lwres_buffer_getuint8</function></funcdef> <function>lwres_buffer_getuint8</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_buffer_putuint8</function></funcdef> <function>lwres_buffer_putuint8</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_uint8_t val</paramdef> <paramdef>lwres_uint8_t <parameter>val</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_uint16_t lwres_uint16_t
<function>lwres_buffer_getuint16</function></funcdef> <function>lwres_buffer_getuint16</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_buffer_putuint16</function></funcdef> <function>lwres_buffer_putuint16</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_uint16_t val</paramdef> <paramdef>lwres_uint16_t <parameter>val</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_uint32_t lwres_uint32_t
<function>lwres_buffer_getuint32</function></funcdef> <function>lwres_buffer_getuint32</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_buffer_putuint32</function></funcdef> <function>lwres_buffer_putuint32</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_uint32_t val</paramdef> <paramdef>lwres_uint32_t <parameter>val</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_buffer_putmem</function></funcdef> <function>lwres_buffer_putmem</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>const unsigned char *base</paramdef> <paramdef>const unsigned char *<parameter>base</parameter></paramdef>
<paramdef>unsigned int length</paramdef> <paramdef>unsigned int <parameter>length</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_buffer_getmem</function></funcdef> <function>lwres_buffer_getmem</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>unsigned char *base</paramdef> <paramdef>unsigned char *<parameter>base</parameter></paramdef>
<paramdef>unsigned int length</paramdef> <paramdef>unsigned int <parameter>length</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </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---------------\\ /------------entire length---------------\\
/----- used region -----\\/-- available --\\ /----- used region -----\\/-- available --\\
+----------------------------------------+ +----------------------------------------+
| consumed | remaining | | | consumed | remaining | |
+----------------------------------------+ +----------------------------------------+
a b c d e a b c d e
</programlisting>
</para>
<para><programlisting>
a == base of buffer. a == base of buffer.
b == current pointer. Can be anywhere between a and d. b == current pointer. Can be anywhere between a and d.
c == active pointer. Meaningful between b and d. c == active pointer. Meaningful between b and d.
d == used pointer. d == used pointer.
e == length of buffer. e == length of buffer.
</programlisting>
</para>
<para><programlisting>
a-e == entire length of buffer. a-e == entire length of buffer.
a-d == used region. a-d == used region.
a-b == consumed region. a-b == consumed region.
b-d == remaining region. b-d == remaining region.
b-c == optional active region. b-c == optional active region.
</programlisting> </programlisting>
</para> </para>
<para> <para><function>lwres_buffer_init()</function>
<function>lwres_buffer_init()</function> initializes the
initializes the <type>lwres_buffer_t</type>
<type>lwres_buffer_t</type> <parameter>*b</parameter>
<parameter>*b</parameter> and assocates it with the memory region of size
and assocates it with the memory region of size <parameter>length</parameter>
<parameter>length</parameter> bytes starting at location
bytes starting at location <parameter>base.</parameter>
<parameter>base.</parameter> </para>
</para> <para><function>lwres_buffer_invalidate()</function>
<para> marks the buffer <parameter>*b</parameter>
<function>lwres_buffer_invalidate()</function> as invalid. Invalidating a buffer after use is not required,
marks the buffer but makes it possible to catch its possible accidental use.
<parameter>*b</parameter> </para>
as invalid. Invalidating a buffer after use is not required, <para>
but makes it possible to catch its possible accidental use. The functions
</para> <function>lwres_buffer_add()</function>
<para> and
The functions <function>lwres_buffer_subtract()</function>
<function>lwres_buffer_add()</function> respectively increase and decrease the used space in
and buffer
<function>lwres_buffer_subtract()</function> <parameter>*b</parameter>
respectively increase and decrease the used space in by
buffer <parameter>n</parameter>
<parameter>*b</parameter> bytes.
by <function>lwres_buffer_add()</function>
<parameter>n</parameter> checks for buffer overflow and
bytes. <function>lwres_buffer_subtract()</function>
<function>lwres_buffer_add()</function> checks for underflow.
checks for buffer overflow and These functions do not allocate or deallocate memory.
<function>lwres_buffer_subtract()</function> They just change the value of
checks for underflow. <structfield>used</structfield>.
These functions do not allocate or deallocate memory. </para>
They just change the value of <para>
<structfield>used</structfield>. A buffer is re-initialised by
</para> <function>lwres_buffer_clear()</function>.
<para> The function sets
A buffer is re-initialised by <structfield>used</structfield>,
<function>lwres_buffer_clear()</function>. <structfield>current</structfield>
The function sets and
<structfield>used</structfield> , <structfield>active</structfield>
<structfield>current</structfield> to zero.
and </para>
<structfield>active</structfield> <para><function>lwres_buffer_first</function>
to zero. makes the consumed region of buffer
</para> <parameter>*p</parameter>
<para> empty by setting
<function>lwres_buffer_first</function> <structfield>current</structfield>
makes the consumed region of buffer to zero (the start of the buffer).
<parameter>*p</parameter> </para>
empty by setting <para><function>lwres_buffer_forward()</function>
<structfield>current</structfield> increases the consumed region of buffer
to zero (the start of the buffer). <parameter>*b</parameter>
</para> by
<para> <parameter>n</parameter>
<function>lwres_buffer_forward()</function> bytes, checking for overflow.
increases the consumed region of buffer Similarly,
<parameter>*b</parameter> <function>lwres_buffer_back()</function>
by decreases buffer
<parameter>n</parameter> <parameter>b</parameter>'s
bytes, checking for overflow. consumed region by
Similarly, <parameter>n</parameter>
<function>lwres_buffer_back()</function> bytes and checks for underflow.
decreases buffer </para>
<parameter>b</parameter>'s <para><function>lwres_buffer_getuint8()</function>
consumed region by reads an unsigned 8-bit integer from
<parameter>n</parameter> <parameter>*b</parameter>
bytes and checks for underflow. and returns it.
</para> <function>lwres_buffer_putuint8()</function>
<para> writes the unsigned 8-bit integer
<function>lwres_buffer_getuint8()</function> <parameter>val</parameter>
reads an unsigned 8-bit integer from to buffer
<parameter>*b</parameter> <parameter>*b</parameter>.
and returns it. </para>
<function>lwres_buffer_putuint8()</function> <para><function>lwres_buffer_getuint16()</function>
writes the unsigned 8-bit integer and
<parameter>val</parameter> <function>lwres_buffer_getuint32()</function>
to buffer are identical to
<parameter>*b</parameter>. <function>lwres_buffer_putuint8()</function>
</para> except that they respectively read an unsigned 16-bit or 32-bit integer
<para> in network byte order from
<function>lwres_buffer_getuint16()</function> <parameter>b</parameter>.
and Similarly,
<function>lwres_buffer_getuint32()</function> <function>lwres_buffer_putuint16()</function>
are identical to and
<function>lwres_buffer_putuint8()</function> <function>lwres_buffer_putuint32()</function>
except that they respectively read an unsigned 16-bit or 32-bit integer writes the unsigned 16-bit or 32-bit integer
in network byte order from <parameter>val</parameter>
<parameter>b</parameter>. to buffer
Similarly, <parameter>b</parameter>,
<function>lwres_buffer_putuint16()</function> in network byte order.
and </para>
<function>lwres_buffer_putuint32()</function> <para>
writes the unsigned 16-bit or 32-bit integer Arbitrary amounts of data are read or written from a lightweight
<parameter>val</parameter> resolver buffer with
to buffer <function>lwres_buffer_getmem()</function>
<parameter>b</parameter>, and
in network byte order. <function>lwres_buffer_putmem()</function>
</para> respectively.
<para> <function>lwres_buffer_putmem()</function>
Arbitrary amounts of data are read or written from a lightweight copies
resolver buffer with <parameter>length</parameter>
<function>lwres_buffer_getmem()</function> bytes of memory at
and <parameter>base</parameter>
<function>lwres_buffer_putmem()</function> to
respectively. <parameter>b</parameter>.
<function>lwres_buffer_putmem()</function> Conversely,
copies <function>lwres_buffer_getmem()</function>
<parameter>length</parameter> copies
bytes of memory at <parameter>length</parameter>
<parameter>base</parameter> bytes of memory from
to <parameter>b</parameter>
<parameter>b</parameter>. to
Conversely, <parameter>base</parameter>.
<function>lwres_buffer_getmem()</function> </para>
copies </refsect1>
<parameter>length</parameter> </refentry><!--
bytes of memory from - Local variables:
<parameter>b</parameter> - mode: sgml
to - End:
<parameter>base</parameter>. -->
</para>
</refsect1>
</refentry>

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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_config.docbook,v 1.5 2005/05/11 05:55:39 sra Exp $ -->
<!-- $Id: lwres_config.docbook,v 1.4 2005/04/07 03:50:01 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Jun 30, 2000</date> <date>Jun 30, 2000</date>
</refentryinfo> </refentryinfo>
<refmeta> <refmeta>
<refentrytitle>lwres_config</refentrytitle> <refentrytitle>lwres_config</refentrytitle>
<manvolnum>3</manvolnum> <manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <docinfo>
<refname>lwres_conf_init</refname> <copyright>
<refname>lwres_conf_clear</refname> <year>2004</year>
<refname>lwres_conf_parse</refname> <year>2005</year>
<refname>lwres_conf_print</refname> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
<refname>lwres_conf_get</refname> </copyright>
<refpurpose>lightweight resolver configuration</refpurpose> <copyright>
</refnamediv> <year>2000</year>
<year>2001</year>
<holder>Internet Software Consortium</holder>
</copyright>
</docinfo>
<refsynopsisdiv> <refnamediv>
<funcsynopsis> <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> <funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_conf_init</function></funcdef> <function>lwres_conf_init</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_conf_clear</function></funcdef> <function>lwres_conf_clear</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_conf_parse</function></funcdef> <function>lwres_conf_parse</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>const char *filename</paramdef> <paramdef>const char *<parameter>filename</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_conf_print</function></funcdef> <function>lwres_conf_print</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>FILE *fp</paramdef> <paramdef>FILE *<parameter>fp</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_conf_t * lwres_conf_t *
<function>lwres_conf_get</function></funcdef> <function>lwres_conf_get</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <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>
<title>RETURN VALUES</title> <para><function>lwres_conf_init()</function>
<para> creates an empty
<function>lwres_conf_parse()</function> <type>lwres_conf_t</type>
returns structure for lightweight resolver context
<errorcode>LWRES_R_SUCCESS</errorcode> <parameter>ctx</parameter>.
if it successfully read and parsed </para>
<parameter>filename</parameter>.
It returns <para><function>lwres_conf_clear()</function>
<errorcode>LWRES_R_FAILURE</errorcode> frees up all the internal memory used by
if that
<parameter>filename</parameter> <type>lwres_conf_t</type>
could not be opened or contained incorrect structure in resolver context
resolver statements. <parameter>ctx</parameter>.
</para> </para>
<para>
<function>lwres_conf_print()</function> <para><function>lwres_conf_parse()</function>
returns opens the file
<errorcode>LWRES_R_SUCCESS</errorcode> <parameter>filename</parameter>
unless an error occurred when converting the network addresses to a and parses it to initialise the resolver context
numeric host address string. <parameter>ctx</parameter>'s
If this happens, the function returns <type>lwres_conf_t</type>
<errorcode>LWRES_R_FAILURE</errorcode>. structure.
</para> </para>
</refsect1>
<refsect1> <para><function>lwres_conf_print()</function>
<title>SEE ALSO</title> prints the
<para> <type>lwres_conf_t</type>
<citerefentry> structure for resolver context
<refentrytitle>stdio</refentrytitle><manvolnum>3</manvolnum> <parameter>ctx</parameter>
</citerefentry>, to the
<citerefentry> <type>FILE</type>
<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum> <parameter>fp</parameter>.
</citerefentry>. </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>FILES</title>
<para> <title>RETURN VALUES</title>
<filename>/etc/resolv.conf</filename>
</para> <para><function>lwres_conf_parse()</function>
</refsect1> returns <errorcode>LWRES_R_SUCCESS</errorcode>
</refentry> 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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001, 2003 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_context.docbook,v 1.7 2005/05/11 05:55:39 sra Exp $ -->
<!-- $Id: lwres_context.docbook,v 1.6 2005/04/07 03:50:01 marka Exp $ -->
<refentry> <refentry>
<refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<date>Jun 30, 2000</date> <refmeta>
</refentryinfo> <refentrytitle>lwres_context</refentrytitle>
<refmeta> <manvolnum>3</manvolnum>
<refentrytitle>lwres_context</refentrytitle> <refmiscinfo>BIND9</refmiscinfo>
<manvolnum>3</manvolnum> </refmeta>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta> <docinfo>
<refnamediv> <copyright>
<refname>lwres_context_create</refname> <year>2004</year>
<refname>lwres_context_destroy</refname> <year>2005</year>
<refname>lwres_context_nextserial</refname> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
<refname>lwres_context_initserial</refname> </copyright>
<refname>lwres_context_freemem</refname> <copyright>
<refname>lwres_context_allocmem</refname> <year>2000</year>
<refname>lwres_context_sendrecv</refname> <year>2001</year>
<refpurpose>lightweight resolver context management</refpurpose> <year>2003</year>
</refnamediv> <holder>Internet Software Consortium</holder>
<refsynopsisdiv> </copyright>
<funcsynopsis> </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> <funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_context_create</function></funcdef> <function>lwres_context_create</function></funcdef>
<paramdef>lwres_context_t **contextp</paramdef> <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
<paramdef>void *arg</paramdef> <paramdef>void *<parameter>arg</parameter></paramdef>
<paramdef>lwres_malloc_t malloc_function</paramdef> <paramdef>lwres_malloc_t <parameter>malloc_function</parameter></paramdef>
<paramdef>lwres_free_t free_function</paramdef> <paramdef>lwres_free_t <parameter>free_function</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_context_destroy</function></funcdef> <function>lwres_context_destroy</function></funcdef>
<paramdef>lwres_context_t **contextp</paramdef> <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_context_initserial</function></funcdef> <function>lwres_context_initserial</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_uint32_t serial</paramdef> <paramdef>lwres_uint32_t <parameter>serial</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_uint32_t lwres_uint32_t
<function>lwres_context_nextserial</function></funcdef> <function>lwres_context_nextserial</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_context_freemem</function></funcdef> <function>lwres_context_freemem</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>void *mem</paramdef> <paramdef>void *<parameter>mem</parameter></paramdef>
<paramdef>size_t len</paramdef> <paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_context_allocmem</function></funcdef> <function>lwres_context_allocmem</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>size_t len</paramdef> <paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void * void *
<function>lwres_context_sendrecv</function></funcdef> <function>lwres_context_sendrecv</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>void *sendbase</paramdef> <paramdef>void *<parameter>sendbase</parameter></paramdef>
<paramdef>int sendlen</paramdef> <paramdef>int <parameter>sendlen</parameter></paramdef>
<paramdef>void *recvbase</paramdef> <paramdef>void *<parameter>recvbase</parameter></paramdef>
<paramdef>int recvlen</paramdef> <paramdef>int <parameter>recvlen</parameter></paramdef>
<paramdef>int *recvd_len</paramdef> <paramdef>int *<parameter>recvd_len</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <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>,
a pointer to a <para><function>lwres_context_create()</function>
<type>lwres_context_t</type> creates a <type>lwres_context_t</type> structure for use in
pointer. This lightweight resolver operations. It holds a socket and other
<type>lwres_context_t</type> data needed for communicating with a resolver daemon. The new
pointer must initially be NULL, and is modified <type>lwres_context_t</type> is returned through
to point to the newly created <parameter>contextp</parameter>, a pointer to a
<type>lwres_context_t</type>. <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> It is not permitted to have a NULL
<para> <parameter>malloc_function</parameter> and a non-NULL
When the lightweight resolver needs to perform dynamic memory <parameter>free_function</parameter> or vice versa.
allocation, it will call <parameter>arg</parameter> is passed as the first parameter to
<parameter>malloc_function</parameter> the memory allocation functions. If
to allocate memory and <parameter>malloc_function</parameter> and
<parameter>free_function</parameter> <parameter>free_function</parameter> are NULL,
<parameter>arg</parameter> is unused and should be passed as
NULL.
</para>
to free it. If <para>
<parameter>malloc_function</parameter> Once memory for the structure has been allocated,
and it is initialized using
<parameter>free_function</parameter> <citerefentry>
<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
and returned via <parameter>*contextp</parameter>.
</para>
are NULL, memory is allocated using <para><function>lwres_context_destroy()</function>
.Xr malloc 3 destroys a <type>lwres_context_t</type>, closing its socket.
and <parameter>contextp</parameter> is a pointer to a pointer to the
<citerefentry> context that is to be destroyed. The pointer will be set to
<refentrytitle>free</refentrytitle><manvolnum>3</manvolnum> NULL when the context has been destroyed.
</citerefentry>. </para>
It is not permitted to have a NULL <para>
<parameter>malloc_function</parameter> The context holds a serial number that is used to identify
and a non-NULL resolver request packets and associate responses with the
<parameter>free_function</parameter> corresponding requests. This serial number is controlled using
or vice versa. <function>lwres_context_initserial()</function> and
<parameter>arg</parameter> <function>lwres_context_nextserial()</function>.
is passed as the first parameter to the memory <function>lwres_context_initserial()</function> sets the serial
allocation functions. number for context <parameter>*ctx</parameter> to
If <parameter>serial</parameter>.
<parameter>malloc_function</parameter> <function>lwres_context_nextserial()</function> increments the
and serial number and returns the previous value.
<parameter>free_function</parameter> </para>
are NULL,
<parameter>arg</parameter>
is unused and should be passed as NULL. <para>
</para> Memory for a lightweight resolver context is allocated and freed
<para> using <function>lwres_context_allocmem()</function> and
Once memory for the structure has been allocated, <function>lwres_context_freemem()</function>. These use
it is initialized using whatever allocations were defined when the context was created
<citerefentry> with <function>lwres_context_create()</function>.
<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum> <function>lwres_context_allocmem()</function> allocates
</citerefentry> <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 <para><function>lwres_context_sendrecv()</function>
<parameter>*contextp</parameter>. 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> <refsect1>
<para> <title>RETURN VALUES</title>
<function>lwres_context_destroy()</function>
destroys a
<type>lwres_context_t</type>,
closing its socket. <para><function>lwres_context_create()</function>
<parameter>contextp</parameter> returns <errorcode>LWRES_R_NOMEMORY</errorcode> if memory for
is a pointer to a pointer to the context that is to be destroyed. the <type>struct lwres_context</type> could not be allocated,
The pointer will be set to NULL when the context has been destroyed. <errorcode>LWRES_R_SUCCESS</errorcode> otherwise.
</para> </para>
<para> <para>
The context holds a serial number that is used to identify resolver Successful calls to the memory allocator
request packets and associate responses with the corresponding requests. <function>lwres_context_allocmem()</function>
This serial number is controlled using return a pointer to the start of the allocated space.
<function>lwres_context_initserial()</function> It returns NULL if memory could not be allocated.
and </para>
<function>lwres_context_nextserial()</function>. <para><errorcode>LWRES_R_SUCCESS</errorcode>
<function>lwres_context_initserial()</function> is returned when
sets the serial number for context <function>lwres_context_sendrecv()</function>
<parameter>*ctx</parameter> completes successfully.
to <errorcode>LWRES_R_IOERROR</errorcode>
<parameter>serial</parameter>. 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> <citerefentry>
increments the serial number and returns the previous value. <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
</para> </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> <citerefentry>
<para> <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
<function>lwres_context_sendrecv()</function> </citerefentry>.
performs I/O for the context </para>
<parameter>ctx</parameter>. </refsect1>
</refentry><!--
Data are read and written from the context's socket. - Local variables:
It writes data from - mode: sgml
<parameter>sendbase</parameter> - End:
&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>

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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_gabn.docbook,v 1.6 2005/05/11 05:55:39 sra Exp $ -->
<!-- $Id: lwres_gabn.docbook,v 1.5 2005/04/07 03:50:01 marka Exp $ -->
<refentry> <refentry>
<refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<date>Jun 30, 2000</date> <refmeta>
</refentryinfo> <refentrytitle>lwres_gabn</refentrytitle>
<refmeta> <manvolnum>3</manvolnum>
<refentrytitle>lwres_gabn</refentrytitle> <refmiscinfo>BIND9</refmiscinfo>
<manvolnum>3</manvolnum> </refmeta>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta> <docinfo>
<refnamediv> <copyright>
<refname>lwres_gabnrequest_render</refname> <year>2004</year>
<refname>lwres_gabnresponse_render</refname> <year>2005</year>
<refname>lwres_gabnrequest_parse</refname> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
<refname>lwres_gabnresponse_parse</refname> </copyright>
<refname>lwres_gabnresponse_free</refname> <copyright>
<refname>lwres_gabnrequest_free</refname> <year>2000</year>
<refpurpose>lightweight resolver getaddrbyname message handling</refpurpose> <year>2001</year>
</refnamediv> <holder>Internet Software Consortium</holder>
<refsynopsisdiv> </copyright>
<funcsynopsis> </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> <funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_gabnrequest_render</function></funcdef> <function>lwres_gabnrequest_render</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_gabnrequest_t *req</paramdef> <paramdef>lwres_gabnrequest_t *<parameter>req</parameter></paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef> <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_gabnresponse_render</function></funcdef> <function>lwres_gabnresponse_render</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_gabnresponse_t *req</paramdef> <paramdef>lwres_gabnresponse_t *<parameter>req</parameter></paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef> <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_gabnrequest_parse</function></funcdef> <function>lwres_gabnrequest_parse</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef> <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_gabnrequest_t **structp</paramdef> <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_gabnresponse_parse</function></funcdef> <function>lwres_gabnresponse_parse</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef> <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_gabnresponse_t **structp</paramdef> <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_gabnresponse_free</function></funcdef> <function>lwres_gabnresponse_free</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_gabnresponse_t **structp</paramdef> <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_gabnrequest_free</function></funcdef> <function>lwres_gabnrequest_free</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_gabnrequest_t **structp</paramdef> <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para>
These are low-level routines for creating and parsing These are low-level routines for creating and parsing
lightweight resolver name-to-address lookup request and lightweight resolver name-to-address lookup request and
response messages. response messages.
</para><para> </para>
There are four main functions for the getaddrbyname opcode. <para>
One render function converts a getaddrbyname request structure &mdash; There are four main functions for the getaddrbyname opcode.
<type>lwres_gabnrequest_t</type> &mdash; One render function converts a getaddrbyname request structure &mdash;
to the lighweight resolver's canonical format. <type>lwres_gabnrequest_t</type> &mdash;
It is complemented by a parse function that converts a packet in this to the lighweight resolver's canonical format.
canonical format to a getaddrbyname request structure. It is complemented by a parse function that converts a packet in this
Another render function converts the getaddrbyname response structure &mdash; canonical format to a getaddrbyname request structure.
<type>lwres_gabnresponse_t</type> &mdash; Another render function converts the getaddrbyname response structure
to the canonical format. &mdash; <type>lwres_gabnresponse_t</type> &mdash;
This is complemented by a parse function which converts a packet in to the canonical format.
canonical format to a getaddrbyname response structure. This is complemented by a parse function which converts a packet in
</para> canonical format to a getaddrbyname response structure.
<para> </para>
These structures are defined in <para>
<filename>&lt;lwres/lwres.h&gt;</filename>. These structures are defined in
They are shown below. <filename>&lt;lwres/lwres.h&gt;</filename>.
<programlisting> They are shown below.
</para>
<para><programlisting>
#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U #define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
</programlisting>
</para>
<para><programlisting>
typedef struct lwres_addr lwres_addr_t; typedef struct lwres_addr lwres_addr_t;
typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
</programlisting>
</para>
<para><programlisting>
typedef struct { typedef struct {
lwres_uint32_t flags; lwres_uint32_t flags;
lwres_uint32_t addrtypes; lwres_uint32_t addrtypes;
lwres_uint16_t namelen; lwres_uint16_t namelen;
char *name; char *name;
} lwres_gabnrequest_t; } lwres_gabnrequest_t;
</programlisting>
</para>
<para><programlisting>
typedef struct { typedef struct {
lwres_uint32_t flags; lwres_uint32_t flags;
lwres_uint16_t naliases; lwres_uint16_t naliases;
@@ -142,114 +164,95 @@ typedef struct {
size_t baselen; size_t baselen;
} lwres_gabnresponse_t; } lwres_gabnresponse_t;
</programlisting> </programlisting>
</para> </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>.
The contents of <para><function>lwres_gabnrequest_render()</function>
<parameter>*req</parameter> uses resolver context <parameter>ctx</parameter> to convert
are then appended to the buffer in canonical format. getaddrbyname request structure <parameter>req</parameter> to
<function>lwres_gabnresponse_render()</function> canonical format. The packet header structure
performs the same task, except it converts a getaddrbyname response structure <parameter>pkt</parameter> is initialised and transferred to
<type>lwres_gabnresponse_t</type> buffer <parameter>b</parameter>.
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>.
<function>lwres_gabnresponse_parse()</function> The contents of <parameter>*req</parameter> are then appended to
offers the same semantics as the buffer in canonical format.
<function>lwres_gabnrequest_parse()</function> <function>lwres_gabnresponse_render()</function> performs the
except it yields a same task, except it converts a getaddrbyname response structure
<type>lwres_gabnresponse_t</type> <type>lwres_gabnresponse_t</type> to the lightweight resolver's
structure. canonical format.
</para> </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 <para><function>lwres_gabnrequest_parse()</function>
structures is also discarded. uses context <parameter>ctx</parameter> to convert the contents
</para> of packet <parameter>pkt</parameter> to a
</refsect1> <type>lwres_gabnrequest_t</type> structure. Buffer
<refsect1> <parameter>b</parameter> provides space to be used for storing
<title>RETURN VALUES</title> this structure. When the function succeeds, the resulting
<para> <type>lwres_gabnrequest_t</type> is made available through
The getaddrbyname opcode functions <parameter>*structp</parameter>.
<function>lwres_gabnrequest_render()</function>,
<function>lwres_gabnresponse_render()</function> <function>lwres_gabnresponse_parse()</function> offers the same
<function>lwres_gabnrequest_parse()</function> semantics as <function>lwres_gabnrequest_parse()</function>
and except it yields a <type>lwres_gabnresponse_t</type> structure.
<function>lwres_gabnresponse_parse()</function> </para>
all return
<errorcode>LWRES_R_SUCCESS</errorcode> <para><function>lwres_gabnresponse_free()</function>
on success. and <function>lwres_gabnrequest_free()</function> release the
They return memory in resolver context <parameter>ctx</parameter> that was
<errorcode>LWRES_R_NOMEMORY</errorcode> allocated to the <type>lwres_gabnresponse_t</type> or
if memory allocation fails. <type>lwres_gabnrequest_t</type> structures referenced via
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode> <parameter>structp</parameter>.
is returned if the available space in the buffer
<parameter>b</parameter> Any memory associated with ancillary buffers and strings for
is too small to accommodate the packet header or the those structures is also discarded.
<type>lwres_gabnrequest_t</type> </para>
and </refsect1>
<type>lwres_gabnresponse_t</type> <refsect1>
structures. <title>RETURN VALUES</title>
<function>lwres_gabnrequest_parse()</function> <para>
and The getaddrbyname opcode functions
<function>lwres_gabnresponse_parse()</function> <function>lwres_gabnrequest_render()</function>,
will return <function>lwres_gabnresponse_render()</function>
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode> <function>lwres_gabnrequest_parse()</function>
if the buffer is not empty after decoding the received packet. and
These functions will return <function>lwres_gabnresponse_parse()</function>
<errorcode>LWRES_R_FAILURE</errorcode> all return
if <errorcode>LWRES_R_SUCCESS</errorcode>
<structfield>pktflags</structfield> on success.
in the packet header structure They return
<type>lwres_lwpacket_t</type> <errorcode>LWRES_R_NOMEMORY</errorcode>
indicate that the packet is not a response to an earlier query. if memory allocation fails.
</para> <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
</refsect1> is returned if the available space in the buffer
<refsect1> <parameter>b</parameter>
<title>SEE ALSO</title> is too small to accommodate the packet header or the
<para> <type>lwres_gabnrequest_t</type>
<citerefentry> and
<refentrytitle>lwres_packet</refentrytitle><manvolnum>3 <type>lwres_gabnresponse_t</type>
</manvolnum> structures.
</citerefentry> <function>lwres_gabnrequest_parse()</function>
</para> and
</refsect1> <function>lwres_gabnresponse_parse()</function>
</refentry> 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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_gai_strerror.docbook,v 1.6 2005/05/11 05:55:40 sra Exp $ -->
<!-- $Id: lwres_gai_strerror.docbook,v 1.5 2005/04/07 03:50:02 marka Exp $ -->
<refentry> <refentry>
<refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<date>Jun 30, 2000</date> <refmeta>
</refentryinfo> <refentrytitle>lwres_gai_strerror</refentrytitle>
<refmeta> <manvolnum>3</manvolnum>
<refentrytitle>lwres_gai_strerror</refentrytitle> <refmiscinfo>BIND9</refmiscinfo>
<manvolnum>3</manvolnum> </refmeta>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta> <docinfo>
<refnamediv> <copyright>
<refname>gai_strerror</refname> <year>2004</year>
<refpurpose>print suitable error string</refpurpose> <year>2005</year>
</refnamediv> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
<refsynopsisdiv> </copyright>
<funcsynopsis> <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> <funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
char * char *
<function>gai_strerror</function></funcdef> <function>gai_strerror</function></funcdef>
<paramdef>int ecode</paramdef> <paramdef>int <parameter>ecode</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <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> <para><function>lwres_gai_strerror()</function>
<title>SEE ALSO</title> returns an error message corresponding to an error code returned by
<para> <function>getaddrinfo()</function>.
<citerefentry> The following error codes and their meaning are defined in
<refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum> <filename>include/lwres/netdb.h</filename>.
</citerefentry>, <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> <refsect1>
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum> <title>SEE ALSO</title>
</citerefentry>, <para><citerefentry>
<refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>RFC2133</refentrytitle> <refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>. </citerefentry>,
</para>
</refsect1> <citerefentry>
</refentry> <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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001, 2003 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_getaddrinfo.docbook,v 1.9 2005/05/11 05:55:40 sra Exp $ -->
<!-- $Id: lwres_getaddrinfo.docbook,v 1.8 2005/04/07 03:50:02 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Jun 30, 2000</date> <date>Jun 30, 2000</date>
</refentryinfo> </refentryinfo>
<refmeta> <refmeta>
<refentrytitle>lwres_getaddrinfo</refentrytitle> <refentrytitle>lwres_getaddrinfo</refentrytitle>
<manvolnum>3</manvolnum> <manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <docinfo>
<refname>lwres_getaddrinfo</refname> <copyright>
<refname>lwres_freeaddrinfo</refname> <year>2004</year>
<refpurpose>socket address structure to host and service name</refpurpose> <year>2005</year>
</refnamediv> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
<refsynopsisdiv> </copyright>
<funcsynopsis> <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> <funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
int int
<function>lwres_getaddrinfo</function></funcdef> <function>lwres_getaddrinfo</function></funcdef>
<paramdef>const char *hostname</paramdef> <paramdef>const char *<parameter>hostname</parameter></paramdef>
<paramdef>const char *servname</paramdef> <paramdef>const char *<parameter>servname</parameter></paramdef>
<paramdef>const struct addrinfo *hints</paramdef> <paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef>
<paramdef>struct addrinfo **res</paramdef> <paramdef>struct addrinfo **<parameter>res</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_freeaddrinfo</function></funcdef> <function>lwres_freeaddrinfo</function></funcdef>
<paramdef>struct addrinfo *ai</paramdef> <paramdef>struct addrinfo *<parameter>ai</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
<para> <para>
If the operating system does not provide a If the operating system does not provide a
<type>struct addrinfo</type>, <type>struct addrinfo</type>,
the following structure is used: the following structure is used:
</para>
<programlisting> <para><programlisting>
struct addrinfo { struct addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
int ai_family; /* PF_xxx */ int ai_family; /* PF_xxx */
@@ -72,301 +86,300 @@ struct addrinfo {
struct addrinfo *ai_next; /* next structure in linked list */ struct addrinfo *ai_next; /* next structure in linked list */
}; };
</programlisting> </programlisting>
</para> </para>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <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>.
The function is the lightweight resolver's implementation of <para><function>lwres_getaddrinfo()</function>
<function>getaddrinfo()</function> is used to get a list of IP addresses and port numbers for host
as defined in RFC2133. <parameter>hostname</parameter> and service
<parameter>hostname</parameter> <parameter>servname</parameter>.
and
<parameter>servname</parameter>
are pointers to null-terminated
strings or
<type>NULL</type>.
<parameter>hostname</parameter> The function is the lightweight resolver's implementation of
is either a host name or a numeric host address string: a dotted decimal <function>getaddrinfo()</function> as defined in RFC2133.
IPv4 address or an IPv6 address. <parameter>hostname</parameter> and
<parameter>servname</parameter> <parameter>servname</parameter> are pointers to null-terminated
is either a decimal port number or a service name as listed in strings or <type>NULL</type>.
<filename>/etc/services</filename>.
</para>
<para> <parameter>hostname</parameter> is either a host name or a
<parameter>hints</parameter> numeric host address string: a dotted decimal IPv4 address or an
is an optional pointer to a IPv6 address. <parameter>servname</parameter> is either a
<type>struct addrinfo</type>. decimal port number or a service name as listed in
This structure can be used to provide hints concerning the type of socket <filename>/etc/services</filename>.
that the caller supports or wishes to use. </para>
The caller can supply the following structure elements in
<parameter>*hints</parameter>:
<variablelist> <para><parameter>hints</parameter>
<varlistentry><term><constant>ai_family</constant></term> is an optional pointer to a
<listitem> <type>struct addrinfo</type>.
<para>The protocol family that should be used. This structure can be used to provide hints concerning the type of
When socket
<constant>ai_family</constant> that the caller supports or wishes to use.
is set to The caller can supply the following structure elements in
<type>PF_UNSPEC</type>, <parameter>*hints</parameter>:
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>.
In this case, if the hostname argument is a <variablelist>
<type>NULL</type> <varlistentry>
pointer, then the IP address portion of the socket <term><constant>ai_family</constant></term>
address structure will be set to <listitem>
<type>INADDR_ANY</type> <para>
for an IPv4 address or The protocol family that should be used.
<type>IN6ADDR_ANY_INIT</type> When
for an IPv6 address. <constant>ai_family</constant>
</para> is set to
<para> <type>PF_UNSPEC</type>,
When it means the caller will accept any protocol family supported by
<constant>ai_flags</constant> the
does not set the operating system.
<type>AI_PASSIVE</type> </para>
bit, the returned socket address structure will be ready </listitem>
for use in a call to </varlistentry>
<citerefentry> <varlistentry>
<refentrytitle>connect</refentrytitle><manvolnum>2 <term><constant>ai_socktype</constant></term>
</manvolnum> <listitem>
</citerefentry> <para>
for a connection-oriented protocol or denotes the type of socket &mdash;
<citerefentry> <type>SOCK_STREAM</type>,
<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum> <type>SOCK_DGRAM</type>
</citerefentry>, 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> In this case, if the hostname argument is a
<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum> <type>NULL</type>
</citerefentry>, 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>
<citerefentry> <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
<refentrytitle>sendmsg</refentrytitle><manvolnum>2 </citerefentry>,
</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> or
All other elements of the <type>struct addrinfo</type> passed <citerefentry>
via <parameter>hints</parameter> must be zero. <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
</para> </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> <para>
A <parameter>hints</parameter> of <type>NULL</type> is treated as if All other elements of the <type>struct addrinfo</type> passed
the caller provided a <type>struct addrinfo</type> initialized to zero via <parameter>hints</parameter> must be zero.
with <constant>ai_family</constant>set to </para>
<constant>PF_UNSPEC</constant>.
</para>
<para> <para>
After a successful call to A <parameter>hints</parameter> of <type>NULL</type> is
<function>lwres_getaddrinfo()</function>, treated as if
<parameter>*res</parameter> the caller provided a <type>struct addrinfo</type> initialized to zero
is a pointer to a linked list of one or more with <constant>ai_family</constant>set to
<type>addrinfo</type> <constant>PF_UNSPEC</constant>.
structures. </para>
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> <para>
All of the information returned by After a successful call to
<function>lwres_getaddrinfo()</function> <function>lwres_getaddrinfo()</function>,
is dynamically allocated: the addrinfo structures, and the socket <parameter>*res</parameter>
address structures and canonical host name strings pointed to by the is a pointer to a linked list of one or more
<constant>addrinfo</constant>structures. <type>addrinfo</type>
Memory allocated for the dynamically allocated structures created by structures.
a successful call to Each
<function>lwres_getaddrinfo()</function> <type>struct addrinfo</type>
is released by in this list cn be processed by following
<function>lwres_freeaddrinfo()</function>. the
<parameter>ai</parameter> <constant>ai_next</constant>
is a pointer to a pointer, until a
<type>struct addrinfo</type> <type>NULL</type>
created by a call to pointer is encountered.
<function>lwres_getaddrinfo()</function>. The three members
</para> <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> </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>.
</para> <refsect1>
</refsect1> <title>RETURN VALUES</title>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry> <para><function>lwres_getaddrinfo()</function>
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum> returns zero on success or one of the error codes listed in
</citerefentry>, <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> <citerefentry>
<refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>RFC2133</refentrytitle> <refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>RFC2133</refentrytitle>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum> <refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum> <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum> <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum> <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum> <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>. </citerefentry>,
</para>
</refsect1> <citerefentry>
</refentry> <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. - Copyright (C) 2001 Internet Software Consortium.
- -
- Permission to use, copy, modify, and distribute this software for any - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_gethostent.docbook,v 1.7 2005/05/11 05:55:40 sra Exp $ -->
<!-- $Id: lwres_gethostent.docbook,v 1.6 2004/03/05 05:12:56 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Jun 30, 2000</date> <date>Jun 30, 2000</date>
</refentryinfo> </refentryinfo>
<refmeta> <refmeta>
<refentrytitle>lwres_gethostent</refentrytitle> <refentrytitle>lwres_gethostent</refentrytitle>
<manvolnum>3</manvolnum> <manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <docinfo>
<refname>lwres_gethostbyname</refname> <copyright>
<refname>lwres_gethostbyname2</refname> <year>2004</year>
<refname>lwres_gethostbyaddr</refname> <year>2005</year>
<refname>lwres_gethostent</refname> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
<refname>lwres_sethostent</refname> </copyright>
<refname>lwres_endhostent</refname> <copyright>
<refname>lwres_gethostbyname_r</refname> <year>2001</year>
<refname>lwres_gethostbyaddr_r</refname> <holder>Internet Software Consortium</holder>
<refname>lwres_gethostent_r</refname> </copyright>
<refname>lwres_sethostent_r</refname> </docinfo>
<refname>lwres_endhostent_r</refname>
<refpurpose>lightweight resolver get network host entry</refpurpose> <refnamediv>
</refnamediv> <refname>lwres_gethostbyname</refname>
<refsynopsisdiv> <refname>lwres_gethostbyname2</refname>
<funcsynopsis> <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> <funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
struct hostent * struct hostent *
<function>lwres_gethostbyname</function></funcdef> <function>lwres_gethostbyname</function></funcdef>
<paramdef>const char *name</paramdef> <paramdef>const char *<parameter>name</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
struct hostent * struct hostent *
<function>lwres_gethostbyname2</function></funcdef> <function>lwres_gethostbyname2</function></funcdef>
<paramdef>const char *name</paramdef> <paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>int af</paramdef> <paramdef>int <parameter>af</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
struct hostent * struct hostent *
<function>lwres_gethostbyaddr</function></funcdef> <function>lwres_gethostbyaddr</function></funcdef>
<paramdef>const char *addr</paramdef> <paramdef>const char *<parameter>addr</parameter></paramdef>
<paramdef>int len</paramdef> <paramdef>int <parameter>len</parameter></paramdef>
<paramdef>int type</paramdef> <paramdef>int <parameter>type</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
struct hostent * struct hostent *
<function>lwres_gethostent</function></funcdef> <function>lwres_gethostent</function></funcdef>
<paramdef>void</paramdef> <paramdef>void</paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_sethostent</function></funcdef> <function>lwres_sethostent</function></funcdef>
<paramdef>int stayopen</paramdef> <paramdef>int <parameter>stayopen</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_endhostent</function></funcdef> <function>lwres_endhostent</function></funcdef>
<paramdef>void</paramdef> <paramdef>void</paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
struct hostent * struct hostent *
<function>lwres_gethostbyname_r</function></funcdef> <function>lwres_gethostbyname_r</function></funcdef>
<paramdef>const char *name</paramdef> <paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>struct hostent *resbuf</paramdef> <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef>
<paramdef>char *buf</paramdef> <paramdef>char *<parameter>buf</parameter></paramdef>
<paramdef>int buflen</paramdef> <paramdef>int <parameter>buflen</parameter></paramdef>
<paramdef>int *error</paramdef> <paramdef>int *<parameter>error</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
struct hostent * struct hostent *
<function>lwres_gethostbyaddr_r</function></funcdef> <function>lwres_gethostbyaddr_r</function></funcdef>
<paramdef>const char *addr</paramdef> <paramdef>const char *<parameter>addr</parameter></paramdef>
<paramdef>int len</paramdef> <paramdef>int <parameter>len</parameter></paramdef>
<paramdef>int type</paramdef> <paramdef>int <parameter>type</parameter></paramdef>
<paramdef>struct hostent *resbuf</paramdef> <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef>
<paramdef>char *buf</paramdef> <paramdef>char *<parameter>buf</parameter></paramdef>
<paramdef>int buflen</paramdef> <paramdef>int <parameter>buflen</parameter></paramdef>
<paramdef>int *error</paramdef> <paramdef>int *<parameter>error</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
struct hostent * struct hostent *
<function>lwres_gethostent_r</function></funcdef> <function>lwres_gethostent_r</function></funcdef>
<paramdef>struct hostent *resbuf</paramdef> <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef>
<paramdef>char *buf</paramdef> <paramdef>char *<parameter>buf</parameter></paramdef>
<paramdef>int buflen</paramdef> <paramdef>int <parameter>buflen</parameter></paramdef>
<paramdef>int *error</paramdef> <paramdef>int *<parameter>error</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_sethostent_r</function></funcdef> <function>lwres_sethostent_r</function></funcdef>
<paramdef>int stayopen</paramdef> <paramdef>int <parameter>stayopen</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_endhostent_r</function></funcdef> <function>lwres_endhostent_r</function></funcdef>
<paramdef>void</paramdef> <paramdef>void</paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para>
These functions provide hostname-to-address and These functions provide hostname-to-address and
address-to-hostname lookups by means of the lightweight resolver. address-to-hostname lookups by means of the lightweight resolver.
They are similar to the standard They are similar to the standard
<citerefentry> <citerefentry>
<refentrytitle>gethostent</refentrytitle><manvolnum>3 <refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum>
</manvolnum> </citerefentry>
</citerefentry> functions provided by most operating systems.
functions provided by most operating systems. They use a
They use a <type>struct hostent</type>
<type>struct hostent</type> which is usually defined in
which is usually defined in <filename>&lt;namedb.h&gt;</filename>.
<filename>&lt;namedb.h&gt;</filename>. </para>
<para><programlisting>
<programlisting>
struct hostent { struct hostent {
char *h_name; /* official name of host */ char *h_name; /* official name of host */
char **h_aliases; /* alias list */ char **h_aliases; /* alias list */
@@ -158,250 +169,269 @@ struct hostent {
}; };
#define h_addr h_addr_list[0] /* address, for backward compatibility */ #define h_addr h_addr_list[0] /* address, for backward compatibility */
</programlisting> </programlisting>
</para> </para>
<para> <para>
The members of this structure are: The members of this structure are:
<variablelist> <variablelist>
<varlistentry><term><constant>h_name</constant></term> <varlistentry>
<listitem> <term><constant>h_name</constant></term>
<para> <listitem>
The official (canonical) name of the host. <para>
</para> The official (canonical) name of the host.
</listitem></varlistentry> </para>
<varlistentry><term><constant>h_aliases</constant></term> </listitem>
<listitem> </varlistentry>
<para> <varlistentry>
A NULL-terminated array of alternate names (nicknames) for the host. <term><constant>h_aliases</constant></term>
</para> <listitem>
</listitem></varlistentry> <para>
<varlistentry><term><constant>h_addrtype</constant></term> A NULL-terminated array of alternate names (nicknames) for the
<listitem> host.
<para> </para>
The type of address being returned &mdash; </listitem>
<type>PF_INET</type> </varlistentry>
or <varlistentry>
<type>PF_INET6</type>. <term><constant>h_addrtype</constant></term>
</para> <listitem>
</listitem></varlistentry> <para>
<varlistentry><term><constant>h_length</constant></term> The type of address being returned &mdash;
<listitem> <type>PF_INET</type>
<para> or
The length of the address in bytes. <type>PF_INET6</type>.
</para> </para>
</listitem></varlistentry> </listitem>
<varlistentry><term><constant>h_addr_list</constant></term> </varlistentry>
<listitem> <varlistentry>
<para> <term><constant>h_length</constant></term>
A <type>NULL</type> <listitem>
terminated array of network addresses for the host. <para>
Host addresses are returned in network byte order. The length of the address in bytes.
</para> </para>
</listitem></varlistentry> </listitem>
</variablelist> </varlistentry>
</para> <varlistentry>
<para> <term><constant>h_addr_list</constant></term>
For backward compatibility with very old software, <listitem>
<constant>h_addr</constant> <para>
is the first address in A <type>NULL</type>
<constant>h_addr_list.</constant> terminated array of network addresses for the host.
</para> Host addresses are returned in network byte order.
<para> </para>
<function>lwres_gethostent()</function>, </listitem>
<function>lwres_sethostent()</function>, </varlistentry>
<function>lwres_endhostent()</function>, </variablelist>
<function>lwres_gethostent_r()</function>, </para>
<function>lwres_sethostent_r()</function> <para>
and For backward compatibility with very old software,
<function>lwres_endhostent_r()</function> <constant>h_addr</constant>
provide iteration over the known host entries on systems that is the first address in
provide such functionality through facilities like <constant>h_addr_list.</constant>
<filename>/etc/hosts</filename> </para>
or NIS. The lightweight resolver does not currently implement <para><function>lwres_gethostent()</function>,
these functions; it only provides them as stub functions that always <function>lwres_sethostent()</function>,
return failure. <function>lwres_endhostent()</function>,
</para> <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><function>lwres_gethostbyname()</function>
<function>lwres_gethostbyname()</function> and and <function>lwres_gethostbyname2()</function> look up the
<function>lwres_gethostbyname2()</function> look up the hostname hostname <parameter>name</parameter>.
<parameter>name</parameter>. <function>lwres_gethostbyname()</function> always looks for an
<function>lwres_gethostbyname()</function> always looks for an IPv4 IPv4 address while <function>lwres_gethostbyname2()</function>
address while <function>lwres_gethostbyname2()</function> looks for an looks for an address of protocol family
address of protocol family <parameter>af</parameter>: either <parameter>af</parameter>: either <type>PF_INET</type> or
<type>PF_INET</type> or <type>PF_INET6</type> &mdash; IPv4 or IPV6 <type>PF_INET6</type> &mdash; IPv4 or IPV6 addresses
addresses respectively. Successful calls of the functions return a respectively. Successful calls of the functions return a
<type>struct hostent</type>for the name that was looked up. <type>struct hostent</type>for the name that was looked up.
<type>NULL</type> is returned if the lookups by <type>NULL</type> is returned if the lookups by
<function>lwres_gethostbyname()</function> or <function>lwres_gethostbyname()</function> or
<function>lwres_gethostbyname2()</function> fail. <function>lwres_gethostbyname2()</function> fail.
</para> </para>
<para> <para>
Reverse lookups of addresses are performed by Reverse lookups of addresses are performed by
<function>lwres_gethostbyaddr()</function>. <function>lwres_gethostbyaddr()</function>.
<parameter>addr</parameter> is an address of length <parameter>addr</parameter> is an address of length
<parameter>len</parameter> bytes and protocol family <parameter>len</parameter> bytes and protocol family
<parameter>type</parameter> &mdash; <type>PF_INET</type> or <parameter>type</parameter> &mdash; <type>PF_INET</type> or
<type>PF_INET6</type>. <type>PF_INET6</type>.
<function>lwres_gethostbyname_r()</function> is a thread-safe function <function>lwres_gethostbyname_r()</function> is a
for forward lookups. If an error occurs, an error code is returned in thread-safe function
<parameter>*error</parameter>. for forward lookups. If an error occurs, an error code is returned in
<parameter>resbuf</parameter> is a pointer to a <type>struct <parameter>*error</parameter>.
hostent</type> which is initialised by a successful call to <parameter>resbuf</parameter> is a pointer to a
<function>lwres_gethostbyname_r()</function> . <type>struct hostent</type> which is initialised by a successful call to
<parameter>buf</parameter> is a buffer of length <function>lwres_gethostbyname_r()</function>.
<parameter>len</parameter> bytes which is used to store the <parameter>buf</parameter> is a buffer of length
<constant>h_name</constant>, <constant>h_aliases</constant>, and <parameter>len</parameter> bytes which is used to store the
<constant>h_addr_list</constant> elements of the <type>struct <constant>h_name</constant>, <constant>h_aliases</constant>, and
hostent</type> returned in <parameter>resbuf</parameter>. <constant>h_addr_list</constant> elements of the
Successful calls to <function>lwres_gethostbyname_r()</function> <type>struct hostent</type> returned in <parameter>resbuf</parameter>.
return <parameter>resbuf</parameter>, Successful calls to <function>lwres_gethostbyname_r()</function>
which is a pointer to the <type>struct hostent</type> it created. return <parameter>resbuf</parameter>,
</para> which is a pointer to the <type>struct hostent</type> it created.
</para>
<para> <para><function>lwres_gethostbyaddr_r()</function>
<function>lwres_gethostbyaddr_r()</function> is a thread-safe function is a thread-safe function
that performs a reverse lookup of address <parameter>addr</parameter> that performs a reverse lookup of address <parameter>addr</parameter>
which is <parameter>len</parameter> bytes long and is of protocol which is <parameter>len</parameter> bytes long and is of
family <parameter>type</parameter> &mdash; <type>PF_INET</type> or protocol
<type>PF_INET6</type>. If an error occurs, the error code is returned family <parameter>type</parameter> &mdash; <type>PF_INET</type> or
in <parameter>*error</parameter>. The other function parameters are <type>PF_INET6</type>. If an error occurs, the error code is returned
identical to those in <function>lwres_gethostbyname_r()</function>. in <parameter>*error</parameter>. The other function
<parameter>resbuf</parameter> is a pointer to a <type>struct parameters are
hostent</type> which is initialised by a successful call to identical to those in <function>lwres_gethostbyname_r()</function>.
<function>lwres_gethostbyaddr_r()</function>. <parameter>resbuf</parameter> is a pointer to a
<parameter>buf</parameter> is a buffer of length <type>struct hostent</type> which is initialised by a successful call to
<parameter>len</parameter> bytes which is used to store the <function>lwres_gethostbyaddr_r()</function>.
<constant>h_name</constant>, <constant>h_aliases</constant>, and <parameter>buf</parameter> is a buffer of length
<constant>h_addr_list</constant> elements of the <type>struct <parameter>len</parameter> bytes which is used to store the
hostent</type> returned in <parameter>resbuf</parameter>. Successful <constant>h_name</constant>, <constant>h_aliases</constant>, and
calls to <function>lwres_gethostbyaddr_r()</function> return <constant>h_addr_list</constant> elements of the
<parameter>resbuf</parameter>, which is a pointer to the <type>struct hostent</type> returned in <parameter>resbuf</parameter>.
<function>struct hostent()</function> it created. Successful calls to <function>lwres_gethostbyaddr_r()</function> return
</para> <parameter>resbuf</parameter>, which is a pointer to the
<function>struct hostent()</function> it created.
</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>RETURN VALUES</title> <title>RETURN VALUES</title>
<para> <para>
The functions The functions
<function>lwres_gethostbyname()</function>, <function>lwres_gethostbyname()</function>,
<function>lwres_gethostbyname2()</function>, <function>lwres_gethostbyname2()</function>,
<function>lwres_gethostbyaddr()</function>, <function>lwres_gethostbyaddr()</function>,
and and
<function>lwres_gethostent()</function> <function>lwres_gethostent()</function>
return NULL to indicate an error. In this case the global variable return NULL to indicate an error. In this case the global variable
<type>lwres_h_errno</type> <type>lwres_h_errno</type>
will contain one of the following error codes defined in will contain one of the following error codes defined in
<filename>&lt;lwres/netdb.h&gt;</filename>: <filename>&lt;lwres/netdb.h&gt;</filename>:
<variablelist> <variablelist>
<varlistentry><term><constant>HOST_NOT_FOUND</constant></term> <varlistentry>
<listitem> <term><constant>HOST_NOT_FOUND</constant></term>
<para> <listitem>
The host or address was not found. <para>
</para> The host or address was not found.
</listitem></varlistentry> </para>
<varlistentry><term><constant>TRY_AGAIN</constant></term> </listitem>
<listitem> </varlistentry>
<para> <varlistentry>
A recoverable error occurred, e.g., a timeout. <term><constant>TRY_AGAIN</constant></term>
Retrying the lookup may succeed. <listitem>
</para> <para>
</listitem></varlistentry> A recoverable error occurred, e.g., a timeout.
<varlistentry><term><constant>NO_RECOVERY</constant></term> Retrying the lookup may succeed.
<listitem> </para>
<para> </listitem>
A non-recoverable error occurred. </varlistentry>
</para> <varlistentry>
</listitem></varlistentry> <term><constant>NO_RECOVERY</constant></term>
<varlistentry><term><constant>NO_DATA</constant></term> <listitem>
<listitem> <para>
<para> A non-recoverable error occurred.
The name exists, but has no address information </para>
associated with it (or vice versa in the case </listitem>
of a reverse lookup). The code NO_ADDRESS </varlistentry>
is accepted as a synonym for NO_DATA for backwards <varlistentry>
compatibility. <term><constant>NO_DATA</constant></term>
</para> <listitem>
</listitem></varlistentry> <para>
</variablelist> The name exists, but has no address information
</para> 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> <para><citerefentry>
<citerefentry> <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3 </citerefentry>
</manvolnum> translates these error codes to suitable error messages.
</citerefentry> </para>
translates these error codes to suitable error messages.
</para>
<para> <para><function>lwres_gethostent()</function>
<function>lwres_gethostent()</function> and <function>lwres_gethostent_r()</function>
and always return <type>NULL</type>.
<function>lwres_gethostent_r()</function> </para>
always return
<type>NULL</type>.
</para>
<para> <para>
Successful calls to <function>lwres_gethostbyname_r()</function> and Successful calls to <function>lwres_gethostbyname_r()</function> and
<function>lwres_gethostbyaddr_r()</function> return <function>lwres_gethostbyaddr_r()</function> return
<parameter>resbuf</parameter>, a pointer to the <type>struct <parameter>resbuf</parameter>, a pointer to the
hostent</type> that was initialised by these functions. They return <type>struct hostent</type> that was initialised by these functions. They return
<type>NULL</type> if the lookups fail or if <parameter>buf</parameter> <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 was too small to hold the list of addresses and names referenced by
the <constant>h_name</constant>, <constant>h_aliases</constant>, and the <constant>h_name</constant>, <constant>h_aliases</constant>, and
<constant>h_addr_list</constant> elements of the <type>struct <constant>h_addr_list</constant> elements of the
hostent</type>. If <parameter>buf</parameter> was too small, both <type>struct hostent</type>.
<function>lwres_gethostbyname_r()</function> and If <parameter>buf</parameter> was too small, both
<function>lwres_gethostbyaddr_r()</function> set the global variable <function>lwres_gethostbyname_r()</function> and
<type>errno</type> to <errorcode>ERANGE</errorcode>. <function>lwres_gethostbyaddr_r()</function> set the global
</para> variable
<type>errno</type> to <errorcode>ERANGE</errorcode>.
</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum>
<refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum> </citerefentry>,
</citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3 <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
</manvolnum> </citerefentry>
</citerefentry> </para>
</para> </refsect1>
</refsect1>
<refsect1> <refsect1>
<title>BUGS</title> <title>BUGS</title>
<para> <para><function>lwres_gethostbyname()</function>,
<function>lwres_gethostbyname()</function>, <function>lwres_gethostbyname2()</function>,
<function>lwres_gethostbyname2()</function>, <function>lwres_gethostbyaddr()</function>
<function>lwres_gethostbyaddr()</function> and
and <function>lwres_endhostent()</function>
<function>lwres_endhostent()</function> are not thread safe; they return pointers to static data and
are not thread safe; they return pointers to static data and provide error codes through a global variable.
provide error codes through a global variable. Thread-safe versions for name and address lookup are provided by
Thread-safe versions for name and address lookup are provided by <function>lwres_gethostbyname_r()</function>,
<function>lwres_gethostbyname_r()</function>, and
and <function>lwres_gethostbyaddr_r()</function>
<function>lwres_gethostbyaddr_r()</function> respectively.
respectively. </para>
</para> <para>
<para> The resolver daemon does not currently support any non-DNS
The resolver daemon does not currently support any non-DNS name services such as
name services such as <filename>/etc/hosts</filename>
<filename>/etc/hosts</filename> or
or <type>NIS</type>,
<type>NIS</type>, consequently the above functions don't, either.
consequently the above functions don't, either. </para>
</para> </refsect1>
</refsect1> </refentry><!--
</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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001, 2003 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_getipnode.docbook,v 1.8 2005/05/11 05:55:40 sra Exp $ -->
<!-- $Id: lwres_getipnode.docbook,v 1.7 2005/04/07 03:50:02 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Jun 30, 2000</date> <date>Jun 30, 2000</date>
</refentryinfo> </refentryinfo>
<refmeta> <refmeta>
<refentrytitle>lwres_getipnode</refentrytitle> <refentrytitle>lwres_getipnode</refentrytitle>
<manvolnum>3</manvolnum> <manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <docinfo>
<refname>lwres_getipnodebyname</refname> <copyright>
<refname>lwres_getipnodebyaddr</refname> <year>2004</year>
<refname>lwres_freehostent</refname> <year>2005</year>
<refpurpose>lightweight resolver nodename / address translation API</refpurpose> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</refnamediv> </copyright>
<refsynopsisdiv> <copyright>
<funcsynopsis> <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> <funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
struct hostent * struct hostent *
<function>lwres_getipnodebyname</function></funcdef> <function>lwres_getipnodebyname</function></funcdef>
<paramdef>const char *name</paramdef> <paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>int af</paramdef> <paramdef>int <parameter>af</parameter></paramdef>
<paramdef>int flags</paramdef> <paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>int *error_num</paramdef> <paramdef>int *<parameter>error_num</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
struct hostent * struct hostent *
<function>lwres_getipnodebyaddr</function></funcdef> <function>lwres_getipnodebyaddr</function></funcdef>
<paramdef>const void *src</paramdef> <paramdef>const void *<parameter>src</parameter></paramdef>
<paramdef>size_t len</paramdef> <paramdef>size_t <parameter>len</parameter></paramdef>
<paramdef>int af</paramdef> <paramdef>int <parameter>af</parameter></paramdef>
<paramdef>int *error_num</paramdef> <paramdef>int *<parameter>error_num</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_freehostent</function></funcdef> <function>lwres_freehostent</function></funcdef>
<paramdef>struct hostent *he</paramdef> <paramdef>struct hostent *<parameter>he</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para>
These functions perform thread safe, protocol independent These functions perform thread safe, protocol independent
nodename-to-address and address-to-nodename nodename-to-address and address-to-nodename
translation as defined in RFC2553. translation as defined in RFC2553.
</para> </para>
<para> <para>
They use a They use a
<type>struct hostent</type> <type>struct hostent</type>
which is defined in which is defined in
<filename>namedb.h</filename>: <filename>namedb.h</filename>:
<programlisting> </para>
<para><programlisting>
struct hostent { struct hostent {
char *h_name; /* official name of host */ char *h_name; /* official name of host */
char **h_aliases; /* alias list */ char **h_aliases; /* alias list */
@@ -90,218 +105,225 @@ struct hostent {
}; };
#define h_addr h_addr_list[0] /* address, for backward compatibility */ #define h_addr h_addr_list[0] /* address, for backward compatibility */
</programlisting> </programlisting>
</para> </para>
<para> <para>
The members of this structure are: The members of this structure are:
<variablelist> <variablelist>
<varlistentry><term><constant>h_name</constant></term> <varlistentry>
<listitem> <term><constant>h_name</constant></term>
<para> <listitem>
The official (canonical) name of the host. <para>
</para> The official (canonical) name of the host.
</listitem></varlistentry> </para>
<varlistentry><term><constant>h_aliases</constant></term> </listitem>
<listitem> </varlistentry>
<para> <varlistentry>
A NULL-terminated array of alternate names (nicknames) for the host. <term><constant>h_aliases</constant></term>
</para> <listitem>
</listitem></varlistentry> <para>
<varlistentry><term><constant>h_addrtype</constant></term> A NULL-terminated array of alternate names (nicknames) for the
<listitem> host.
<para> </para>
The type of address being returned - usually </listitem>
<type>PF_INET</type> </varlistentry>
or <varlistentry>
<type>PF_INET6</type>. <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> </para>
</listitem></varlistentry> </listitem>
<varlistentry><term><constant>h_length</constant></term> </varlistentry>
<listitem> <varlistentry>
<para> <term><constant>h_length</constant></term>
The length of the address in bytes. <listitem>
</para> <para>
</listitem></varlistentry> The length of the address in bytes.
<varlistentry><term><constant>h_addr_list</constant></term> </para>
<listitem> </listitem>
<para> </varlistentry>
A <varlistentry>
<type>NULL</type> <term><constant>h_addr_list</constant></term>
terminated array of network addresses for the host. <listitem>
Host addresses are returned in network byte order. <para>
</para> A
</listitem></varlistentry> <type>NULL</type>
</variablelist> terminated array of network addresses for the host.
</para> Host addresses are returned in network byte order.
<para> </para>
<function>lwres_getipnodebyname()</function> </listitem>
looks up addresses of protocol family </varlistentry>
<parameter>af</parameter> </variablelist>
</para>
for the hostname <para><function>lwres_getipnodebyname()</function>
<parameter>name</parameter>. 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 <variablelist>
<parameter>flags</parameter> <varlistentry>
parameter contains ORed flag bits to <term><constant>AI_V4MAPPED</constant></term>
specify the types of addresses that are searched <listitem>
for, and the types of addresses that are returned. <para>
The flag bits are: This is used with an
<variablelist> <parameter>af</parameter>
<varlistentry><term><constant>AI_V4MAPPED</constant></term> of AF_INET6, and causes IPv4 addresses to be returned as
<listitem> IPv4-mapped
<para> IPv6 addresses.
This is used with an </para>
<parameter>af</parameter> </listitem>
of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped </varlistentry>
IPv6 addresses. <varlistentry>
</para> <term><constant>AI_ALL</constant></term>
</listitem></varlistentry> <listitem>
<varlistentry><term><constant>AI_ALL</constant></term> <para>
<listitem> This is used with an
<para> <parameter>af</parameter>
This is used with an of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
<parameter>af</parameter> be returned.
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
If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped mapped
IPv6 addresses. IPv6 addresses.
</para> </para>
</listitem></varlistentry> </listitem>
<varlistentry><term><constant>AI_ADDRCONFIG</constant></term> </varlistentry>
<listitem> <varlistentry>
<para> <term><constant>AI_ADDRCONFIG</constant></term>
Only return an IPv6 or IPv4 address if here is an active network <listitem>
interface of that type. This is not currently implemented <para>
in the BIND 9 lightweight resolver, and the flag is ignored. Only return an IPv6 or IPv4 address if here is an active network
</para> interface of that type. This is not currently implemented
</listitem></varlistentry> in the BIND 9 lightweight resolver, and the flag is ignored.
<varlistentry><term><constant>AI_DEFAULT</constant></term> </para>
<listitem> </listitem>
<para> </varlistentry>
This default sets the <varlistentry>
<constant>AI_V4MAPPED</constant> <term><constant>AI_DEFAULT</constant></term>
and <listitem>
<constant>AI_ADDRCONFIG</constant> <para>
flag bits. This default sets the
</para> <constant>AI_V4MAPPED</constant>
</listitem></varlistentry> and
</variablelist> <constant>AI_ADDRCONFIG</constant>
</para> flag bits.
<para> </para>
<function>lwres_getipnodebyaddr()</function> </listitem>
performs a reverse lookup </varlistentry>
of address </variablelist>
<parameter>src</parameter> </para>
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_getipnodebyaddr()</function>
<para> performs a reverse lookup of address <parameter>src</parameter>
<function>lwres_freehostent()</function> which is <parameter>len</parameter> bytes long.
releases all the memory associated with <parameter>af</parameter> denotes the protocol family, typically
the <type>PF_INET</type> or <type>PF_INET6</type>.
<type>struct hostent</type> </para>
pointer <para><function>lwres_freehostent()</function>
<parameter>he</parameter>. 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 <citerefentry>
<constant>h_name</constant>, <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<constant>h_addr_list</constant> <citerefentry>
and <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
<constant>h_aliases</constant> </citerefentry>,
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> <citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, </citerefentry>.
</para>
<citerefentry> </refsect1>
<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum> </refentry><!--
</citerefentry>, - Local variables:
- mode: sgml
<citerefentry> - End:
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum> -->
</citerefentry>.
</para>
</refsect1>
</refentry>

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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_getnameinfo.docbook,v 1.6 2005/05/11 05:55:40 sra Exp $ -->
<!-- $Id: lwres_getnameinfo.docbook,v 1.5 2005/04/07 03:50:02 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Jun 30, 2000</date> <date>Jun 30, 2000</date>
</refentryinfo> </refentryinfo>
<refmeta> <refmeta>
<refentrytitle>lwres_getnameinfo</refentrytitle> <refentrytitle>lwres_getnameinfo</refentrytitle>
<manvolnum>3</manvolnum> <manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <docinfo>
<refname>lwres_getnameinfo</refname> <copyright>
<refpurpose>lightweight resolver socket address structure to hostname and service name</refpurpose> <year>2004</year>
</refnamediv> <year>2005</year>
<refsynopsisdiv> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
<funcsynopsis> </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> <funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
int int
<function>lwres_getnameinfo</function></funcdef> <function>lwres_getnameinfo</function></funcdef>
<paramdef>const struct sockaddr *sa</paramdef> <paramdef>const struct sockaddr *<parameter>sa</parameter></paramdef>
<paramdef>size_t salen</paramdef> <paramdef>size_t <parameter>salen</parameter></paramdef>
<paramdef>char *host</paramdef> <paramdef>char *<parameter>host</parameter></paramdef>
<paramdef>size_t hostlen</paramdef> <paramdef>size_t <parameter>hostlen</parameter></paramdef>
<paramdef>char *serv</paramdef> <paramdef>char *<parameter>serv</parameter></paramdef>
<paramdef>size_t servlen</paramdef> <paramdef>size_t <parameter>servlen</parameter></paramdef>
<paramdef>int flags</paramdef> <paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> This function is equivalent to the <citerefentry> <para>
<refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum> This function is equivalent to the
</citerefentry> function defined in RFC2133. <citerefentry>
<function>lwres_getnameinfo()</function> returns the hostname for the <refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum>
<type>struct sockaddr</type> <parameter>sa</parameter> which is </citerefentry> function defined in RFC2133.
<parameter>salen</parameter> bytes long. The hostname is of length <function>lwres_getnameinfo()</function> returns the
<parameter>hostlen</parameter> and is returned via hostname for the
<parameter>*host.</parameter> The maximum length of the hostname is <type>struct sockaddr</type> <parameter>sa</parameter> which
1025 bytes: <constant>NI_MAXHOST</constant>.</para> 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 <para> The name of the service associated with the port number in
<parameter>sa</parameter> is returned in <parameter>*serv.</parameter> <parameter>sa</parameter> is returned in <parameter>*serv.</parameter>
It is <parameter>servlen</parameter> bytes long. The maximum length It is <parameter>servlen</parameter> bytes long. The
of the service name is <constant>NI_MAXSERV</constant> - 32 bytes. maximum length
</para> of the service name is <constant>NI_MAXSERV</constant> - 32
bytes.
</para>
<para> The <parameter>flags</parameter> argument sets the following <para>
bits: The <parameter>flags</parameter> argument sets the
<variablelist> following
<varlistentry><term><constant>NI_NOFQDN</constant></term> bits:
<listitem> <variablelist>
<para> <varlistentry>
A fully qualified domain name is not required for local hosts. <term><constant>NI_NOFQDN</constant></term>
The local part of the fully qualified domain name is returned instead. <listitem>
</para></listitem></varlistentry> <para>
<varlistentry><term><constant>NI_NUMERICHOST</constant></term> A fully qualified domain name is not required for local hosts.
<listitem> The local part of the fully qualified domain name is returned
<para> instead.
Return the address in numeric form, as if calling inet_ntop(), </para>
instead of a host name. </listitem>
</para></listitem></varlistentry> </varlistentry>
<varlistentry><term><constant>NI_NAMEREQD</constant></term> <varlistentry>
<listitem> <term><constant>NI_NUMERICHOST</constant></term>
<para> <listitem>
A name is required. If the hostname cannot be found in the DNS and <para>
this flag is set, a non-zero error code is returned. Return the address in numeric form, as if calling inet_ntop(),
If the hostname is not found and the flag is not set, the instead of a host name.
address is returned in numeric form. </para>
</para></listitem></varlistentry> </listitem>
<varlistentry><term><constant>NI_NUMERICSERV</constant></term> </varlistentry>
<listitem> <varlistentry>
<para> <term><constant>NI_NAMEREQD</constant></term>
The service name is returned as a digit string representing the port number. <listitem>
</para></listitem></varlistentry> <para>
<varlistentry><term><constant>NI_DGRAM</constant></term> A name is required. If the hostname cannot be found in the DNS
<listitem> and
<para> this flag is set, a non-zero error code is returned.
Specifies that the service being looked up is a datagram If the hostname is not found and the flag is not set, the
service, and causes getservbyport() to be called with a second address is returned in numeric form.
argument of "udp" instead of its default of "tcp". This is required </para>
for the few ports (512-514) that have different services for UDP and </listitem>
TCP. </varlistentry>
</para></listitem></varlistentry> <varlistentry>
</variablelist> <term><constant>NI_NUMERICSERV</constant></term>
</para> <listitem>
</refsect1> <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> <refsect1>
<title>RETURN VALUES</title> <title>RETURN VALUES</title>
<para> <para><function>lwres_getnameinfo()</function>
<function>lwres_getnameinfo()</function> returns 0 on success or a non-zero error code if an error occurs.
returns 0 on success or a non-zero error code if an error occurs. </para>
</para> </refsect1>
</refsect1> <refsect1>
<refsect1> <title>SEE ALSO</title>
<title>SEE ALSO</title> <para><citerefentry>
<para> <refentrytitle>RFC2133</refentrytitle>
<citerefentry> </citerefentry>,
<refentrytitle>RFC2133</refentrytitle> <citerefentry>
</citerefentry>, <refentrytitle>getservbyport</refentrytitle><manvolnum>3</manvolnum>
<citerefentry> </citerefentry>,
<refentrytitle>getservbyport</refentrytitle><manvolnum>3</manvolnum> <citerefentry>
</citerefentry>, <refentrytitle>lwres</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_getnameinfo</refentrytitle><manvolnum>3</manvolnum> <citerefentry>
</citerefentry>, <refentrytitle>lwres_getnamebyaddr</refentrytitle><manvolnum>3</manvolnum>
<citerefentry> </citerefentry>.
<refentrytitle>lwres_getnamebyaddr</refentrytitle><manvolnum>3</manvolnum> <citerefentry>
</citerefentry>. <refentrytitle>lwres_net_ntop</refentrytitle><manvolnum>3</manvolnum>
<citerefentry> </citerefentry>.
<refentrytitle>lwres_net_ntop</refentrytitle><manvolnum>3</manvolnum> </para>
</citerefentry>. </refsect1>
</refsect1> <refsect1>
<refsect1> <title>BUGS</title>
<title>BUGS</title> <para>
<para> RFC2133 fails to define what the nonzero return values of
RFC2133 fails to define what the nonzero return values of <citerefentry>
<citerefentry> <refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum>
<refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum> </citerefentry>
</citerefentry> are.
are. </para>
</para> </refsect1>
</refsect1> </refentry><!--
</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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_getrrsetbyname.docbook,v 1.6 2005/05/11 05:55:40 sra Exp $ -->
<!-- $Id: lwres_getrrsetbyname.docbook,v 1.5 2005/04/07 03:50:03 marka Exp $ -->
<refentry> <refentry>
<refentryinfo>
<refentryinfo>
<date>Oct 18, 2000</date>
</refentryinfo>
<date>Oct 18, 2000</date> <refmeta>
</refentryinfo> <refentrytitle>lwres_getrrsetbyname</refentrytitle>
<refmeta> <manvolnum>3</manvolnum>
<refentrytitle>lwres_getrrsetbyname</refentrytitle> <refmiscinfo>BIND9</refmiscinfo>
<manvolnum>3</manvolnum> </refmeta>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta> <docinfo>
<refnamediv> <copyright>
<refname>lwres_getrrsetbyname</refname> <year>2004</year>
<refname>lwres_freerrset</refname> <year>2005</year>
<refpurpose>retrieve DNS records</refpurpose> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</refnamediv> </copyright>
<refsynopsisdiv> <copyright>
<funcsynopsis> <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> <funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
int int
<function>lwres_getrrsetbyname</function></funcdef> <function>lwres_getrrsetbyname</function></funcdef>
<paramdef>const char *hostname</paramdef> <paramdef>const char *<parameter>hostname</parameter></paramdef>
<paramdef>unsigned int rdclass</paramdef> <paramdef>unsigned int <parameter>rdclass</parameter></paramdef>
<paramdef>unsigned int rdtype</paramdef> <paramdef>unsigned int <parameter>rdtype</parameter></paramdef>
<paramdef>unsigned int flags</paramdef> <paramdef>unsigned int <parameter>flags</parameter></paramdef>
<paramdef>struct rrsetinfo **res</paramdef> <paramdef>struct rrsetinfo **<parameter>res</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_freerrset</function></funcdef> <function>lwres_freerrset</function></funcdef>
<paramdef>struct rrsetinfo *rrset</paramdef> <paramdef>struct rrsetinfo *<parameter>rrset</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
<para> <para>
The following structures are used: The following structures are used:
<programlisting> </para>
<para><programlisting>
struct rdatainfo { struct rdatainfo {
unsigned int rdi_length; /* length of data */ unsigned int rdi_length; /* length of data */
unsigned char *rdi_data; /* record data */ unsigned char *rdi_data; /* record data */
}; };
</programlisting>
</para>
<para><programlisting>
struct rrsetinfo { struct rrsetinfo {
unsigned int rri_flags; /* RRSET_VALIDATED... */ unsigned int rri_flags; /* RRSET_VALIDATED... */
unsigned int rri_rdclass; /* class number */ unsigned int rri_rdclass; /* class number */
@@ -75,134 +92,130 @@ struct rrsetinfo {
struct rdatainfo *rri_sigs; /* individual signatures */ struct rdatainfo *rri_sigs; /* individual signatures */
}; };
</programlisting> </programlisting>
</para> </para>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><function>lwres_getrrsetbyname()</function>
<function>lwres_getrrsetbyname()</function> gets a set of resource records associated with a
gets a set of resource records associated with a <parameter>hostname</parameter>, <parameter>class</parameter>,
<parameter>hostname</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>rrset</parameter> is a pointer to a <type>struct
<parameter>type</parameter>. 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> <varlistentry>
is <term><constant>ERRSET_NONAME</constant></term>
a pointer a to null-terminated string. The <listitem>
<parameter>flags</parameter> <para>
field is currently unused and must be zero. the name does not exist
</para> </para>
<para> </listitem>
After a successful call to </varlistentry>
<function>lwres_getrrsetbyname()</function>,
<parameter>*res</parameter> <varlistentry>
is a pointer to an <term><constant>ERRSET_NODATA</constant></term>
<type>rrsetinfo</type> <listitem>
structure, containing a list of one or more <para>
<type>rdatainfo</type> the name exists, but does not have data of the desired type
structures containing resource records and potentially another list of </para>
<type>rdatainfo</type> </listitem>
structures containing SIG resource records </varlistentry>
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.
Memory allocated for the dynamically allocated structures created by <varlistentry>
a successful call to <term><constant>ERRSET_NOMEMORY</constant></term>
<function>lwres_getrrsetbyname()</function> <listitem>
is released by <para>
<function>lwres_freerrset()</function>. memory could not be allocated
</para>
</listitem>
</varlistentry>
<parameter>rrset</parameter> <varlistentry>
is a pointer to a <term><constant>ERRSET_INVAL</constant></term>
<type>struct rrset</type> <listitem>
created by a call to <para>
<function>lwres_getrrsetbyname()</function>. a parameter is invalid
</para>
</listitem>
</varlistentry>
</para> <varlistentry>
<para> <term><constant>ERRSET_FAIL</constant></term>
</para> <listitem>
</refsect1> <para>
<refsect1> other failure
<title>RETURN VALUES</title> </para>
<para> </listitem>
<function>lwres_getrrsetbyname()</function> </varlistentry>
returns zero on success, and one of the following error
codes if an error occurred:
<variablelist>
<varlistentry><term><constant>ERRSET_NONAME</constant></term> <varlistentry>
<listitem><para> <term><constant/></term>
the name does not exist <listitem>
</para></listitem></varlistentry> <para></para>
</listitem>
</varlistentry>
<varlistentry><term><constant>ERRSET_NODATA</constant></term> </variablelist>
<listitem><para>
the name exists, but does not have data of the desired type
</para></listitem></varlistentry>
<varlistentry><term><constant>ERRSET_NOMEMORY</constant></term> </para>
<listitem><para> </refsect1>
memory could not be allocated <refsect1>
</para></listitem></varlistentry> <title>SEE ALSO</title>
<para><citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
<varlistentry><term><constant>ERRSET_INVAL</constant></term> </refsect1>
<listitem><para> </refentry><!--
a parameter is invalid - Local variables:
</para></listitem></varlistentry> - mode: sgml
- End:
<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>

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

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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_hstrerror.docbook,v 1.7 2005/05/11 05:55:40 sra Exp $ -->
<!-- $Id: lwres_hstrerror.docbook,v 1.6 2005/04/07 03:50:03 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Jun 30, 2000</date> <date>Jun 30, 2000</date>
</refentryinfo> </refentryinfo>
<refmeta> <refmeta>
<refentrytitle>lwres_hstrerror</refentrytitle> <refentrytitle>lwres_hstrerror</refentrytitle>
<manvolnum>3</manvolnum> <manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <docinfo>
<refname>lwres_herror</refname> <copyright>
<refname>lwres_hstrerror</refname> <year>2004</year>
<refpurpose>lightweight resolver error message generation</refpurpose> <year>2005</year>
</refnamediv> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
<refsynopsisdiv> </copyright>
<funcsynopsis> <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> <funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_herror</function></funcdef> <function>lwres_herror</function></funcdef>
<paramdef>const char *s</paramdef> <paramdef>const char *<parameter>s</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
const char * const char *
<function>lwres_hstrerror</function></funcdef> <function>lwres_hstrerror</function></funcdef>
<paramdef>int err</paramdef> <paramdef>int <parameter>err</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><function>lwres_herror()</function>
<function>lwres_herror()</function> prints the string prints the string <parameter>s</parameter> on
<parameter>s</parameter> on <type>stderr</type> followed by the string <type>stderr</type> followed by the string generated by
generated by <function>lwres_hstrerror()</function> for the error code <function>lwres_hstrerror()</function> for the error code stored
stored in the global variable <constant>lwres_h_errno</constant>. in the global variable <constant>lwres_h_errno</constant>.
</para> </para>
<para> <para><function>lwres_hstrerror()</function>
<function>lwres_hstrerror()</function> returns an appropriate string returns an appropriate string for the error code gievn by
for the error code gievn by <parameter>err</parameter>. The values of <parameter>err</parameter>. The values of the error codes and
the error codes and messages are as follows: messages are as follows:
<variablelist> <variablelist>
<varlistentry><term><errorcode>NETDB_SUCCESS</errorcode></term> <varlistentry>
<listitem> <term><errorcode>NETDB_SUCCESS</errorcode></term>
<para> <listitem>
<errorname>Resolver Error 0 (no error)</errorname> <para><errorname>Resolver Error 0 (no error)</errorname>
</para></listitem></varlistentry> </para>
<varlistentry><term><errorcode>HOST_NOT_FOUND</errorcode></term> </listitem>
<listitem> </varlistentry>
<para> <varlistentry>
<errorname>Unknown host</errorname> <term><errorcode>HOST_NOT_FOUND</errorcode></term>
</para></listitem></varlistentry> <listitem>
<varlistentry><term><errorcode>TRY_AGAIN</errorcode></term> <para><errorname>Unknown host</errorname>
<listitem> </para>
<para> </listitem>
<errorname>Host name lookup failure</errorname> </varlistentry>
</para></listitem></varlistentry> <varlistentry>
<varlistentry><term><errorcode>NO_RECOVERY</errorcode></term> <term><errorcode>TRY_AGAIN</errorcode></term>
<listitem> <listitem>
<para> <para><errorname>Host name lookup failure</errorname>
<errorname>Unknown server error</errorname> </para>
</para></listitem></varlistentry> </listitem>
<varlistentry><term><errorcode>NO_DATA</errorcode></term> </varlistentry>
<listitem> <varlistentry>
<para> <term><errorcode>NO_RECOVERY</errorcode></term>
<errorname>No address associated with name</errorname> <listitem>
</para></listitem></varlistentry> <para><errorname>Unknown server error</errorname>
</variablelist> </para>
</para> </listitem>
</refsect1> </varlistentry>
<varlistentry>
<term><errorcode>NO_DATA</errorcode></term>
<listitem>
<para><errorname>No address associated with name</errorname>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1> <refsect1>
<title>RETURN VALUES</title> <title>RETURN VALUES</title>
<para> <para>
The string <errorname>Unknown resolver error</errorname> is returned by The string <errorname>Unknown resolver error</errorname> is returned by
<function>lwres_hstrerror()</function> <function>lwres_hstrerror()</function>
when the value of when the value of
<constant>lwres_h_errno</constant> <constant>lwres_h_errno</constant>
is not a valid error code. is not a valid error code.
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>herror</refentrytitle><manvolnum>3</manvolnum>
<refentrytitle>herror</refentrytitle><manvolnum>3</manvolnum> </citerefentry>,
</citerefentry>,
<citerefentry> <citerefentry>
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum> <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>. </citerefentry>.
</para> </para>
</refsect1> </refsect1>
</refentry> </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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_inetntop.docbook,v 1.6 2005/05/11 05:55:40 sra Exp $ -->
<!-- $Id: lwres_inetntop.docbook,v 1.5 2005/04/07 03:50:03 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Jun 30, 2000</date> <date>Jun 30, 2000</date>
</refentryinfo> </refentryinfo>
<refmeta> <refmeta>
<refentrytitle>lwres_inetntop</refentrytitle> <refentrytitle>lwres_inetntop</refentrytitle>
<manvolnum>3</manvolnum> <manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <docinfo>
<refname>lwres_net_ntop</refname> <copyright>
<refpurpose>lightweight resolver IP address presentation</refpurpose> <year>2004</year>
</refnamediv> <year>2005</year>
<refsynopsisdiv> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
<funcsynopsis> </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> <funcsynopsisinfo>#include &lt;lwres/net.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
const char * const char *
<function>lwres_net_ntop</function></funcdef> <function>lwres_net_ntop</function></funcdef>
<paramdef>int af</paramdef> <paramdef>int <parameter>af</parameter></paramdef>
<paramdef>const void *src</paramdef> <paramdef>const void *<parameter>src</parameter></paramdef>
<paramdef>char *dst</paramdef> <paramdef>char *<parameter>dst</parameter></paramdef>
<paramdef>size_t size</paramdef> <paramdef>size_t <parameter>size</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><function>lwres_net_ntop()</function>
<function>lwres_net_ntop()</function> converts an IP address of converts an IP address of protocol family
protocol family <parameter>af</parameter> &mdash; IPv4 or IPv6 &mdash; <parameter>af</parameter> &mdash; IPv4 or IPv6 &mdash; at
at location <parameter>src</parameter> from network format to its location <parameter>src</parameter> from network format to its
conventional representation as a string. For IPv4 addresses, that conventional representation as a string. For IPv4 addresses,
string would be a dotted-decimal. An IPv6 address would be that string would be a dotted-decimal. An IPv6 address would be
represented in colon notation as described in RFC1884. represented in colon notation as described in RFC1884.
</para> </para>
<para> <para>
The generated string is copied to <parameter>dst</parameter> provided The generated string is copied to <parameter>dst</parameter>
<parameter>size</parameter> indicates it is long enough to store the provided
ASCII representation of the address. <parameter>size</parameter> indicates it is long enough to
</para> store the
ASCII representation of the address.
</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>RETURN VALUES</title> <title>RETURN VALUES</title>
<para> <para>
If successful, the function returns <parameter>dst</parameter>: If successful, the function returns <parameter>dst</parameter>:
a pointer to a string containing the presentation format of the a pointer to a string containing the presentation format of the
address. <function>lwres_net_ntop()</function> returns address. <function>lwres_net_ntop()</function> returns
<type>NULL</type> and sets the global variable <type>NULL</type> and sets the global variable
<constant>errno</constant> to <errorcode>EAFNOSUPPORT</errorcode> if <constant>errno</constant> to <errorcode>EAFNOSUPPORT</errorcode> if
the protocol family given in <parameter>af</parameter> is not the protocol family given in <parameter>af</parameter> is
supported. not
</para> supported.
</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>RFC1884</refentrytitle>
<refentrytitle>RFC1884</refentrytitle> </citerefentry>,
</citerefentry>, <citerefentry>
<citerefentry> <refentrytitle>inet_ntop</refentrytitle><manvolnum>3</manvolnum>
<refentrytitle>inet_ntop</refentrytitle><manvolnum>3</manvolnum> </citerefentry>,
</citerefentry>, <citerefentry>
<citerefentry> <refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum>
<refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum> </citerefentry>.
</citerefentry>. </para>
</para> </refsect1>
</refsect1> </refentry><!--
</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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_noop.docbook,v 1.7 2005/05/11 05:55:40 sra Exp $ -->
<!-- $Id: lwres_noop.docbook,v 1.6 2005/04/07 03:50:03 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Jun 30, 2000</date> <date>Jun 30, 2000</date>
</refentryinfo> </refentryinfo>
<refmeta> <refmeta>
<refentrytitle>lwres_noop</refentrytitle> <refentrytitle>lwres_noop</refentrytitle>
<manvolnum>3</manvolnum> <manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <docinfo>
<refname>lwres_nooprequest_render</refname> <copyright>
<refname>lwres_noopresponse_render</refname> <year>2004</year>
<refname>lwres_nooprequest_parse</refname> <year>2005</year>
<refname>lwres_noopresponse_parse</refname> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
<refname>lwres_noopresponse_free</refname> </copyright>
<refname>lwres_nooprequest_free</refname> <copyright>
<refpurpose>lightweight resolver no-op message handling</refpurpose> <year>2000</year>
</refnamediv> <year>2001</year>
<refsynopsisdiv> <holder>Internet Software Consortium</holder>
<funcsynopsis> </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> <funcsynopsisinfo>
#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo> #include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_nooprequest_render</function></funcdef> <function>lwres_nooprequest_render</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_nooprequest_t *req</paramdef> <paramdef>lwres_nooprequest_t *<parameter>req</parameter></paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef> <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_noopresponse_render</function></funcdef> <function>lwres_noopresponse_render</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_noopresponse_t *req</paramdef> <paramdef>lwres_noopresponse_t *<parameter>req</parameter></paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef> <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_nooprequest_parse</function></funcdef> <function>lwres_nooprequest_parse</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef> <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_nooprequest_t **structp</paramdef> <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_noopresponse_parse</function></funcdef> <function>lwres_noopresponse_parse</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef> <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
<paramdef>lwres_noopresponse_t **structp</paramdef> <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_noopresponse_free</function></funcdef> <function>lwres_noopresponse_free</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_noopresponse_t **structp</paramdef> <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
void void
<function>lwres_nooprequest_free</function></funcdef> <function>lwres_nooprequest_free</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_nooprequest_t **structp</paramdef> <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para>
These are low-level routines for creating and parsing These are low-level routines for creating and parsing
lightweight resolver no-op request and response messages. lightweight resolver no-op request and response messages.
</para> </para>
<para> <para>
The no-op message is analogous to a <command>ping</command> packet: The no-op message is analogous to a <command>ping</command>
a packet is sent to the resolver daemon and is simply echoed back. packet:
The opcode is intended to allow a client to determine if the server is a packet is sent to the resolver daemon and is simply echoed back.
operational or not. The opcode is intended to allow a client to determine if the server is
</para> operational or not.
<para> </para>
There are four main functions for the no-op opcode. <para>
One render function converts a no-op request structure &mdash; There are four main functions for the no-op opcode.
<type>lwres_nooprequest_t</type> &mdash; One render function converts a no-op request structure &mdash;
to the lighweight resolver's canonical format. <type>lwres_nooprequest_t</type> &mdash;
It is complemented by a parse function that converts a packet in this to the lighweight resolver's canonical format.
canonical format to a no-op request structure. It is complemented by a parse function that converts a packet in this
Another render function converts the no-op response structure &mdash; canonical format to a no-op request structure.
<type>lwres_noopresponse_t</type> Another render function converts the no-op response structure &mdash;
to the canonical format. <type>lwres_noopresponse_t</type>
This is complemented by a parse function which converts a packet in to the canonical format.
canonical format to a no-op response structure. This is complemented by a parse function which converts a packet in
</para> canonical format to a no-op response structure.
<para> </para>
These structures are defined in <para>
<filename>lwres/lwres.h</filename>. These structures are defined in
<filename>lwres/lwres.h</filename>.
They are shown below. They are shown below.
<programlisting> </para>
<para><programlisting>
#define LWRES_OPCODE_NOOP 0x00000000U #define LWRES_OPCODE_NOOP 0x00000000U
</programlisting>
</para>
<para><programlisting>
typedef struct { typedef struct {
lwres_uint16_t datalength; lwres_uint16_t datalength;
unsigned char *data; unsigned char *data;
} lwres_nooprequest_t; } lwres_nooprequest_t;
</programlisting>
</para>
<para><programlisting>
typedef struct { typedef struct {
lwres_uint16_t datalength; lwres_uint16_t datalength;
unsigned char *data; unsigned char *data;
} lwres_noopresponse_t; } lwres_noopresponse_t;
</programlisting> </programlisting>
Although the structures have different types, they are identical. </para>
This is because the no-op opcode simply echos whatever data was sent: <para>
the response is therefore identical to the request. Although the structures have different types, they are identical.
</para> This is because the no-op opcode simply echos whatever data was sent:
the response is therefore identical to the request.
</para>
<para> <para><function>lwres_nooprequest_render()</function>
<function>lwres_nooprequest_render()</function> uses resolver uses resolver context <parameter>ctx</parameter> to convert
context <parameter>ctx</parameter> to convert no-op request structure no-op request structure <parameter>req</parameter> to canonical
<parameter>req</parameter> to canonical format. The packet header format. The packet header structure <parameter>pkt</parameter>
structure <parameter>pkt</parameter> is initialised and transferred to is initialised and transferred to buffer
buffer <parameter>b</parameter>. The contents of <parameter>b</parameter>. The contents of
<parameter>*req</parameter> are then appended to the buffer in <parameter>*req</parameter> are then appended to the buffer in
canonical format. <function>lwres_noopresponse_render()</function> canonical format.
performs the same task, except it converts a no-op response structure <function>lwres_noopresponse_render()</function> performs the
<type>lwres_noopresponse_t</type> to the lightweight resolver's same task, except it converts a no-op response structure
canonical format. <type>lwres_noopresponse_t</type> to the lightweight resolver's
</para> canonical format.
</para>
<para> <para><function>lwres_nooprequest_parse()</function>
<function>lwres_nooprequest_parse()</function> uses context uses context <parameter>ctx</parameter> to convert the contents
<parameter>ctx</parameter> to convert the contents of packet of packet <parameter>pkt</parameter> to a
<parameter>pkt</parameter> to a <type>lwres_nooprequest_t</type> <type>lwres_nooprequest_t</type> structure. Buffer
structure. Buffer <parameter>b</parameter> provides space to be used <parameter>b</parameter> provides space to be used for storing
for storing this structure. When the function succeeds, the resulting this structure. When the function succeeds, the resulting
<type>lwres_nooprequest_t</type> is made available through <type>lwres_nooprequest_t</type> is made available through
<parameter>*structp</parameter>. <parameter>*structp</parameter>.
<function>lwres_noopresponse_parse()</function> offers the same <function>lwres_noopresponse_parse()</function> offers the same
semantics as <function>lwres_nooprequest_parse()</function> except it semantics as <function>lwres_nooprequest_parse()</function>
yields a <type>lwres_noopresponse_t</type> structure. except it yields a <type>lwres_noopresponse_t</type> structure.
</para> </para>
<para> <para><function>lwres_noopresponse_free()</function>
<function>lwres_noopresponse_free()</function> and and <function>lwres_nooprequest_free()</function> release the
<function>lwres_nooprequest_free()</function> release the memory in memory in resolver context <parameter>ctx</parameter> that was
resolver context <parameter>ctx</parameter> that was allocated to the allocated to the <type>lwres_noopresponse_t</type> or
<type>lwres_noopresponse_t</type> or <type>lwres_nooprequest_t</type> <type>lwres_nooprequest_t</type> structures referenced via
structures referenced via <parameter>structp</parameter>. <parameter>structp</parameter>.
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>RETURN VALUES</title> <title>RETURN VALUES</title>
<para> <para>
The no-op opcode functions The no-op opcode functions
<function>lwres_nooprequest_render()</function>, <function>lwres_nooprequest_render()</function>,
<function>lwres_noopresponse_render()</function> <function>lwres_noopresponse_render()</function>
<function>lwres_nooprequest_parse()</function> <function>lwres_nooprequest_parse()</function>
and and
<function>lwres_noopresponse_parse()</function> <function>lwres_noopresponse_parse()</function>
all return all return
<errorcode>LWRES_R_SUCCESS</errorcode> <errorcode>LWRES_R_SUCCESS</errorcode>
on success. on success.
They return They return
<errorcode>LWRES_R_NOMEMORY</errorcode> <errorcode>LWRES_R_NOMEMORY</errorcode>
if memory allocation fails. if memory allocation fails.
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode> <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
is returned if the available space in the buffer is returned if the available space in the buffer
<parameter>b</parameter> <parameter>b</parameter>
is too small to accommodate the packet header or the is too small to accommodate the packet header or the
<type>lwres_nooprequest_t</type> <type>lwres_nooprequest_t</type>
and and
<type>lwres_noopresponse_t</type> <type>lwres_noopresponse_t</type>
structures. structures.
<function>lwres_nooprequest_parse()</function> <function>lwres_nooprequest_parse()</function>
and and
<function>lwres_noopresponse_parse()</function> <function>lwres_noopresponse_parse()</function>
will return will return
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode> <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
if the buffer is not empty after decoding the received packet. if the buffer is not empty after decoding the received packet.
These functions will return These functions will return
<errorcode>LWRES_R_FAILURE</errorcode> <errorcode>LWRES_R_FAILURE</errorcode>
if if
<constant>pktflags</constant> <constant>pktflags</constant>
in the packet header structure in the packet header structure
<type>lwres_lwpacket_t</type> <type>lwres_lwpacket_t</type>
indicate that the packet is not a response to an earlier query. indicate that the packet is not a response to an earlier query.
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>SEE ALSO</title> <title>SEE ALSO</title>
<para> <para><citerefentry>
<citerefentry> <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
<refentrytitle>lwres_packet</refentrytitle><manvolnum>3 </citerefentry>
</manvolnum> </para>
</citerefentry> </refsect1>
</para> </refentry><!--
</refsect1> - Local variables:
</refentry> - 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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_packet.docbook,v 1.9 2005/05/11 05:55:41 sra Exp $ -->
<!-- $Id: lwres_packet.docbook,v 1.8 2005/04/07 03:50:04 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Jun 30, 2000</date> <date>Jun 30, 2000</date>
</refentryinfo> </refentryinfo>
<refmeta> <refmeta>
<refentrytitle>lwres_packet</refentrytitle> <refentrytitle>lwres_packet</refentrytitle>
<manvolnum>3</manvolnum> <manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <docinfo>
<refname>lwres_lwpacket_renderheader</refname> <copyright>
<refname>lwres_lwpacket_parseheader</refname> <year>2004</year>
<refpurpose>lightweight resolver packet handling functions</refpurpose> <year>2005</year>
</refnamediv> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
<refsynopsisdiv> </copyright>
<funcsynopsis> <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> <funcsynopsisinfo>#include &lt;lwres/lwpacket.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_lwpacket_renderheader</function></funcdef> <function>lwres_lwpacket_renderheader</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef> <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_lwpacket_parseheader</function></funcdef> <function>lwres_lwpacket_parseheader</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_lwpacket_t *pkt</paramdef> <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para>
These functions rely on a These functions rely on a
<type>struct lwres_lwpacket</type> <type>struct lwres_lwpacket</type>
which is defined in which is defined in
<filename>lwres/lwpacket.h</filename>. <filename>lwres/lwpacket.h</filename>.
</para>
<programlisting> <para><programlisting>
typedef struct lwres_lwpacket lwres_lwpacket_t; typedef struct lwres_lwpacket lwres_lwpacket_t;
</programlisting>
</para>
<para><programlisting>
struct lwres_lwpacket { struct lwres_lwpacket {
lwres_uint32_t length; lwres_uint32_t length;
lwres_uint16_t version; lwres_uint16_t version;
@@ -77,142 +93,197 @@ struct lwres_lwpacket {
lwres_uint16_t authlength; lwres_uint16_t authlength;
}; };
</programlisting> </programlisting>
</para> </para>
<para> <para>
The elements of this structure are: The elements of this structure are:
<variablelist> <variablelist>
<varlistentry><term><constant>length</constant></term> <varlistentry>
<listitem> <term><constant>length</constant></term>
<para> <listitem>
the overall packet length, including the entire packet header. <para>
This field is filled in by the lwres_gabn_*() and lwres_gnba_*() the overall packet length, including the entire packet header.
calls. This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
</para></listitem></varlistentry> calls.
<varlistentry><term><constant>version</constant></term> </para>
<listitem> </listitem>
<para> </varlistentry>
the header format. There is currently only one format, <varlistentry>
<type>LWRES_LWPACKETVERSION_0</type>. <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_*() This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
calls. calls.
</para></listitem></varlistentry> </para>
<varlistentry><term><constant>pktflags</constant></term> </listitem>
<listitem> </varlistentry>
<para> <varlistentry>
library-defined flags for this packet: for instance whether the packet <term><constant>pktflags</constant></term>
is a request or a reply. Flag values can be set, but not defined by <listitem>
the caller. <para>
This field is filled in by the application wit the exception of the library-defined flags for this packet: for instance whether the
LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the packet
lwres_gabn_*() and lwres_gnba_*() calls. is a request or a reply. Flag values can be set, but not defined
</para></listitem></varlistentry> by
<varlistentry><term><constant>serial</constant></term> the caller.
<listitem> This field is filled in by the application wit the exception of
<para> the
is set by the requestor and is returned in all replies. If two or more LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in
packets from the same source have the same serial number and are from the
the same source, they are assumed to be duplicates and the latter ones lwres_gabn_*() and lwres_gnba_*() calls.
may be dropped. </para>
This field must be set by the application. </listitem>
</para></listitem></varlistentry> </varlistentry>
<varlistentry><term><constant>opcode</constant></term> <varlistentry>
<listitem> <term><constant>serial</constant></term>
<para> <listitem>
indicates the operation. <para>
Opcodes between 0x00000000 and 0x03ffffff are is set by the requestor and is returned in all replies. If two
reserved for use by the lightweight resolver library. Opcodes between or more
0x04000000 and 0xffffffff are application defined. packets from the same source have the same serial number and are
This field is filled in by the lwres_gabn_*() and lwres_gnba_*() from
calls. the same source, they are assumed to be duplicates and the
</para></listitem></varlistentry> latter ones
<varlistentry><term><constant>result</constant></term> may be dropped.
<listitem> This field must be set by the application.
<para> </para>
is only valid for replies. </listitem>
Results between 0x04000000 and 0xffffffff are application defined. </varlistentry>
Results between 0x00000000 and 0x03ffffff are reserved for library use. <varlistentry>
This field is filled in by the lwres_gabn_*() and lwres_gnba_*() <term><constant>opcode</constant></term>
calls. <listitem>
</para></listitem></varlistentry> <para>
<varlistentry><term><constant>recvlength</constant></term> indicates the operation.
<listitem> Opcodes between 0x00000000 and 0x03ffffff are
<para> reserved for use by the lightweight resolver library. Opcodes
is the maximum buffer size that the receiver can handle on requests between
and the size of the buffer needed to satisfy a request when the buffer 0x04000000 and 0xffffffff are application defined.
is too large for replies. This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
This field is supplied by the application. calls.
</para></listitem></varlistentry> </para>
<varlistentry><term><constant>authtype</constant></term> </listitem>
<listitem> </varlistentry>
<para> <varlistentry>
defines the packet level authentication that is used. <term><constant>result</constant></term>
Authorisation types between 0x1000 and 0xffff are application defined <listitem>
and types between 0x0000 and 0x0fff are reserved for library use. <para>
Currently these are not used and must be zero. is only valid for replies.
</para></listitem></varlistentry> Results between 0x04000000 and 0xffffffff are application
<varlistentry><term><constant>authlen</constant></term> defined.
<listitem> Results between 0x00000000 and 0x03ffffff are reserved for
<para> library use.
gives the length of the authentication data. This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
Since packet authentication is currently not used, this must be zero. calls.
</para></listitem></varlistentry> </para>
</variablelist> </listitem>
</para> </varlistentry>
<para> <varlistentry>
The following opcodes are currently defined: <term><constant>recvlength</constant></term>
<variablelist> <listitem>
<varlistentry><term><constant>NOOP</constant></term> <para>
<listitem> is the maximum buffer size that the receiver can handle on
<para> requests
Success is always returned and the packet contents are echoed. and the size of the buffer needed to satisfy a request when the
The lwres_noop_*() functions should be used for this type. buffer
</para></listitem></varlistentry> is too large for replies.
<varlistentry><term><constant>GETADDRSBYNAME</constant></term> This field is supplied by the application.
<listitem> </para>
<para> </listitem>
returns all known addresses for a given name. </varlistentry>
The lwres_gabn_*() functions should be used for this type. <varlistentry>
</para></listitem></varlistentry> <term><constant>authtype</constant></term>
<varlistentry><term><constant>GETNAMEBYADDR</constant></term> <listitem>
<listitem> <para>
<para> defines the packet level authentication that is used.
return the hostname for the given address. Authorisation types between 0x1000 and 0xffff are application
The lwres_gnba_*() functions should be used for this type. defined
</para></listitem></varlistentry> and types between 0x0000 and 0x0fff are reserved for library
</variablelist> use.
</para> 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> <para><function>lwres_lwpacket_renderheader()</function>
<function>lwres_lwpacket_renderheader()</function> transfers the transfers the contents of lightweight resolver packet structure
contents of lightweight resolver packet structure <type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in
<type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in network network byte order to the lightweight resolver buffer,
byte order to the lightweight resolver buffer, <parameter>*b</parameter>.
<parameter>*b</parameter>. </para>
</para>
<para> <para><function>lwres_lwpacket_parseheader()</function>
<function>lwres_lwpacket_parseheader()</function> performs the performs the converse operation. It transfers data in network
converse operation. It transfers data in network byte order from byte order from buffer <parameter>*b</parameter> to resolver
buffer <parameter>*b</parameter> to resolver packet packet <parameter>*pkt</parameter>. The contents of the buffer
<parameter>*pkt</parameter>. The contents of the buffer <parameter>b</parameter> should correspond to a
<parameter>b</parameter> should correspond to a <type>lwres_lwpacket_t</type>.
<type>lwres_lwpacket_t</type>. </para>
</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>RETURN VALUES</title> <title>RETURN VALUES</title>
<para> Successful calls to <para>
<function>lwres_lwpacket_renderheader()</function> and Successful calls to
<function>lwres_lwpacket_parseheader()</function> return <function>lwres_lwpacket_renderheader()</function> and
<errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient <function>lwres_lwpacket_parseheader()</function> return
space to copy data between the buffer <parameter>*b</parameter> and <errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient
lightweight resolver packet <parameter>*pkt</parameter> both functions space to copy data between the buffer <parameter>*b</parameter> and
return <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>. lightweight resolver packet <parameter>*pkt</parameter> both
</para> functions
return <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>.
</para>
</refsect1> </refsect1>
</refentry> </refentry><!--
- Local variables:
- mode: sgml
- End:
-->

337
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) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2000, 2001 Internet Software Consortium. - 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 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE. - PERFORMANCE OF THIS SOFTWARE.
--> -->
<!-- $Id: lwres_resutil.docbook,v 1.8 2005/05/11 05:55:41 sra Exp $ -->
<!-- $Id: lwres_resutil.docbook,v 1.7 2005/04/07 03:50:04 marka Exp $ -->
<refentry> <refentry>
<refentryinfo> <refentryinfo>
<date>Jun 30, 2000</date> <date>Jun 30, 2000</date>
</refentryinfo> </refentryinfo>
<refmeta> <refmeta>
<refentrytitle>lwres_resutil</refentrytitle> <refentrytitle>lwres_resutil</refentrytitle>
<manvolnum>3</manvolnum> <manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo> <refmiscinfo>BIND9</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <docinfo>
<refname>lwres_string_parse</refname> <copyright>
<refname>lwres_addr_parse</refname> <year>2004</year>
<refname>lwres_getaddrsbyname</refname> <year>2005</year>
<refname>lwres_getnamebyaddr</refname> <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
<refpurpose>lightweight resolver utility functions</refpurpose> </copyright>
</refnamediv> <copyright>
<refsynopsisdiv> <year>2000</year>
<funcsynopsis> <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> <funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_string_parse</function></funcdef> <function>lwres_string_parse</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>char **c</paramdef> <paramdef>char **<parameter>c</parameter></paramdef>
<paramdef>lwres_uint16_t *len</paramdef> <paramdef>lwres_uint16_t *<parameter>len</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_addr_parse</function></funcdef> <function>lwres_addr_parse</function></funcdef>
<paramdef>lwres_buffer_t *b</paramdef> <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
<paramdef>lwres_addr_t *addr</paramdef> <paramdef>lwres_addr_t *<parameter>addr</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_getaddrsbyname</function></funcdef> <function>lwres_getaddrsbyname</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>const char *name</paramdef> <paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>lwres_uint32_t addrtypes</paramdef> <paramdef>lwres_uint32_t <parameter>addrtypes</parameter></paramdef>
<paramdef>lwres_gabnresponse_t **structp</paramdef> <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype> <funcprototype>
<funcdef> <funcdef>
lwres_result_t lwres_result_t
<function>lwres_getnamebyaddr</function></funcdef> <function>lwres_getnamebyaddr</function></funcdef>
<paramdef>lwres_context_t *ctx</paramdef> <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
<paramdef>lwres_uint32_t addrtype</paramdef> <paramdef>lwres_uint32_t <parameter>addrtype</parameter></paramdef>
<paramdef>lwres_uint16_t addrlen</paramdef> <paramdef>lwres_uint16_t <parameter>addrlen</parameter></paramdef>
<paramdef>const unsigned char *addr</paramdef> <paramdef>const unsigned char *<parameter>addr</parameter></paramdef>
<paramdef>lwres_gnbaresponse_t **structp</paramdef> <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>DESCRIPTION</title> <title>DESCRIPTION</title>
<para> <para><function>lwres_string_parse()</function>
<function>lwres_string_parse()</function> retrieves a DNS-encoded retrieves a DNS-encoded string starting the current pointer of
string starting the current pointer of lightweight resolver buffer lightweight resolver buffer <parameter>b</parameter>: i.e.
<parameter>b</parameter>: i.e. <constant>b-&gt;current</constant>. <constant>b-&gt;current</constant>. When the function returns,
When the function returns, the address of the first byte of the the address of the first byte of the encoded string is returned
encoded string is returned via <parameter>*c</parameter> and the via <parameter>*c</parameter> and the length of that string is
length of that string is given by <parameter>*len</parameter>. The given by <parameter>*len</parameter>. The buffer's current
buffer's current pointer is advanced to point at the character pointer is advanced to point at the character following the
following the string length, the encoded string, and the trailing string length, the encoded string, and the trailing
<type>NULL</type> character. <type>NULL</type> character.
</para> </para>
<para> <para><function>lwres_addr_parse()</function>
<function>lwres_addr_parse()</function> extracts an address from the extracts an address from the buffer <parameter>b</parameter>.
buffer <parameter>b</parameter>. The buffer's current pointer The buffer's current pointer <constant>b-&gt;current</constant>
<constant>b-&gt;current</constant> is presumed to point at an encoded is presumed to point at an encoded address: the address preceded
address: the address preceded by a 32-bit protocol family identifier by a 32-bit protocol family identifier and a 16-bit length
and a 16-bit length field. The encoded address is copied to field. The encoded address is copied to
<constant>addr-&gt;address</constant> and <constant>addr-&gt;address</constant> and
<constant>addr-&gt;length</constant> indicates the size in bytes of <constant>addr-&gt;length</constant> indicates the size in bytes
the address that was copied. <constant>b-&gt;current</constant> is of the address that was copied.
advanced to point at the next byte of available data in the buffer <constant>b-&gt;current</constant> is advanced to point at the
following the encoded address. next byte of available data in the buffer following the encoded
</para> address.
</para>
<para> <para><function>lwres_getaddrsbyname()</function>
<function>lwres_getaddrsbyname()</function> and <function>lwres_getnamebyaddr()</function> use the
and <type>lwres_gnbaresponse_t</type> structure defined below:
<function>lwres_getnamebyaddr()</function> </para>
use the
<type>lwres_gnbaresponse_t</type> <para><programlisting>
structure defined below:
<programlisting>
typedef struct { typedef struct {
lwres_uint32_t flags; lwres_uint32_t flags;
lwres_uint16_t naliases; lwres_uint16_t naliases;
@@ -125,97 +137,100 @@ typedef struct {
void *base; void *base;
size_t baselen; size_t baselen;
} lwres_gabnresponse_t; } lwres_gabnresponse_t;
</programlisting> </programlisting></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> <para>
The lightweight resolver uses The contents of this structure are not manipulated directly but
<function>lwres_getaddrsbyname()</function> to perform foward lookups. they are controlled through the
Hostname <parameter>name</parameter> is looked up using the resolver <citerefentry>
context <parameter>ctx</parameter> for memory allocation. <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
<parameter>addrtypes</parameter> is a bitmask indicating which type of </citerefentry>
addresses are to be looked up. Current values for this bitmask are functions.
<type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and </para>
<type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the
lookup are returned in <parameter>*structp</parameter>.
</para>
<para> <para>
<function>lwres_getnamebyaddr()</function> performs reverse lookups. The lightweight resolver uses
Resolver context <parameter>ctx</parameter> is used for memory <function>lwres_getaddrsbyname()</function> to perform
allocation. The address type is indicated by foward lookups.
<parameter>addrtype</parameter>: <type>LWRES_ADDRTYPE_V4</type> or Hostname <parameter>name</parameter> is looked up using the
<type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is given resolver
by <parameter>addr</parameter> and its length is context <parameter>ctx</parameter> for memory allocation.
<parameter>addrlen</parameter> bytes. The result of the function call <parameter>addrtypes</parameter> is a bitmask indicating
is made available through <parameter>*structp</parameter>. which type of
</para> addresses are to be looked up. Current values for this bitmask are
</refsect1> <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> <para><function>lwres_getnamebyaddr()</function>
<title>RETURN VALUES</title> performs reverse lookups. Resolver context
<para> <parameter>ctx</parameter> is used for memory allocation. The
Successful calls to address type is indicated by <parameter>addrtype</parameter>:
<function>lwres_string_parse()</function> <type>LWRES_ADDRTYPE_V4</type> or
and <type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is
<function>lwres_addr_parse()</function> given by <parameter>addr</parameter> and its length is
return <parameter>addrlen</parameter> bytes. The result of the
<errorcode>LWRES_R_SUCCESS.</errorcode> function call is made available through
Both functions return <parameter>*structp</parameter>.
<errorcode>LWRES_R_FAILURE</errorcode> </para>
if the buffer is corrupt or </refsect1>
<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> <refsect1>
Both <title>RETURN VALUES</title>
<function>lwres_getaddrsbyname()</function> <para>
and Successful calls to
<function>lwres_getnamebyaddr()</function> <function>lwres_string_parse()</function>
return and
<errorcode>LWRES_R_NOMEMORY</errorcode> <function>lwres_addr_parse()</function>
when memory allocation requests fail and return
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode> <errorcode>LWRES_R_SUCCESS.</errorcode>
if the buffers used for sending queries and receiving replies are too Both functions return
small. <errorcode>LWRES_R_FAILURE</errorcode>
</para> 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> <para><function>lwres_getaddrsbyname()</function>
<refsect1> returns <errorcode>LWRES_R_SUCCESS</errorcode> on success and it
<title>SEE ALSO</title> returns <errorcode>LWRES_R_NOTFOUND</errorcode> if the hostname
<para> <parameter>name</parameter> could not be found.
<citerefentry> </para>
<refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum> <para><errorcode>LWRES_R_SUCCESS</errorcode>
</citerefentry>, is returned by a successful call to
<function>lwres_getnamebyaddr()</function>.
</para>
<citerefentry> <para>
<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum> Both
</citerefentry>. <function>lwres_getaddrsbyname()</function>
</para> 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> </refsect1>
</refentry> <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 # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
# PERFORMANCE OF THIS SOFTWARE. # 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. ### Common Makefile rules for BIND 9.
@@ -179,6 +179,16 @@ INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_SCRIPT = @INSTALL_SCRIPT@ INSTALL_SCRIPT = @INSTALL_SCRIPT@
INSTALL_DATA = @INSTALL_DATA@ 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 -> HTML
### DocBook -> man page ### DocBook -> man page
@@ -186,42 +196,29 @@ INSTALL_DATA = @INSTALL_DATA@
.SUFFIXES: .docbook .html .1 .2 .3 .4 .5 .6 .7 .8 .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: .docbook.html:
${OPENJADE} -c ${SGMLCATALOG} -t sgml -d ${HTMLSTYLE} $< ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-docbook-html.xsl $<
echo "" >> r1.htm
cat ${top_srcdir}/docutil/HTML_COPYRIGHT r1.htm > $@
rm -f r1.htm
.docbook.1: .docbook.1:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.2: .docbook.2:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.3: .docbook.3:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.4: .docbook.4:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.5: .docbook.5:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.6: .docbook.6:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.7: .docbook.7:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<
.docbook.8: .docbook.8:
sh ${top_srcdir}/docutil/docbook2man-wrapper.sh ${top_srcdir} $< $@ ${XSLTPROC} -o $@ ${top_srcdir}/doc/xsl/isc-manpage.xsl $<