+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: dig.1,v 1.6 2000/11/30 00:20:37 gson Exp $
---
---.Dd Jun 30, 2000
---.Dt DIG 1
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm dig
---.Nd DNS lookup utility
---.Sh SYNOPSIS
---.Nm dig
---.Op @server
---.Op Fl b Ar address
---.Op Fl c Ar class
---.Op Fl f Ar filename
---.Op Fl k Ar filename
---.Op Fl p Ar port#
---.Op Fl t Ar type
---.Op Fl x Ar addr
---.Op Fl y Ar name:key
---.Op name
---.Op type
---.Op class
---.Op queryopt ...
---.Nm dig
---.Fl h
---.Nm dig
---.Op global-queryopt ...
---.Op query1
---.Op query2 ...
---.Sh DESCRIPTION
---.Pp
---.Nm dig
---(domain information groper) is a flexible tool for interrogating DNS
---name servers.
---It performs DNS lookups and displays the answers that are returned from
---the name server(s) that were queried.
---Most DNS administrators use
---.Nm dig
---to troubleshoot DNS problems because of its flexibility, ease of use and
---clarity of output.
---Other lookup tools tend to have less functionality than
---.Nm dig .
---.Pp
---Although
---.Nm dig
---is normally used with command-line arguments, it also has a batch
---mode of operation for reading lookup requests from a file.
---A brief summary of its command-line arguments and options is printed
---when the
---.Fl h
---option is given.
---Unlike earlier versions, the BIND9 implementation of
---.Nm dig
---allows multiple lookups to be issued from the command line.
---.Pp
---Unless it is told to query a specific name server,
---.Nm dig
---will try each of the servers listed in
---.Pa /etc/resolv.conf .
---.Pp
---When no command line arguments or options are given,
---will perform an NS query for "." (the root).
---.Sh SIMPLE USAGE
---.Pp
---A typical invocation of
---.Nm dig
---looks like:
---.Bd -ragged | -offset indent
---.Ic dig Ar @server name type
---.Ed
---.Pp
---where:
---.Bl -tag -width server
---.It Ar server
---is the name or IP address of the name server to query.
---An IPv4 address can be provided in dotted-decimal notation.
---When the supplied
---.Ar server
---argument is a hostname,
---.Nm dig
---resolves that name before querying that name server.
---If no
---.Ar server
---argument is provided,
---.Nm dig
---consults
---.Pa /etc/resolv.conf
---and queries the name servers listed there.
---The reply from the name server that responds is displayed.
---.It Ar name
---is the name of the resource record that is to be looked up.
---.It Ar type
---indicates what type of query is required - ANY, A, MX, SIG, etc.
---.Ar type
---can be any valid query type.
---If no
---.Ar type
---argument is supplied,
---.Nm dig
---will perform a lookup for an A record.
---.El
---.Pp
---.Sh OPTIONS
---The
---.Fl b
---option sets the source IP address of the query to
---.Ar address .
---This must be a valid
---address on one of the host's network interfaces.
---.Pp
---The default query class (IN for internet) is overridden by the
---.Fl c
---option.
---.Ar class
---is any valid class, such as HS for Hesiod records or CH for
---CHAOSNET records.
---.Pp
---The
---.Fl f
---option makes
---.Nm dig
---operate in batch mode by reading a list of lookup requests to process
---from the file
---.Ar filename .
---The file contains a number of queries, one per line.
---Each entry in the file should be organised in the same way they would be
---presented as queries to
---.Nm dig
---using the command-line interface.
---.Pp
---If a non-standard port number is to be queried, the
---.Fl p
---option is used.
---.Ar port#
---is the port number that
---.Nm dig
---will send its queries instead of the standard DNS port number 53.
---This option would be used to test a name server that has been configured
---to listen for queries on a non-standard port number.
---.Pp
---The
---.Fl t
---option sets the query type to
---.Ar type .
---It can be any valid query type which is supported in BIND9.
---The default query type "A", unless the
---.Fl x
---option is supplied to indicate a reverse lookup.
---A zone transfer can be requested by specifying a type of AXFR.
---When an incremental zone transfer (IXFR) is required,
---.Ar type
---is set to
---.Dv ixfr=N .
---The incremental zone transfer will contain the changes made to the zone
---since the serial number in the zone's SOA record was
---.Ar N .
---.Pp
---Reverse lookups - mapping addresses to names - are simplified
---by the
---.Fl x
---option.
---.Ar addr
---is an IPv4 address in dotted-decimal notation, or a colon-delimited
---IPv6 address.
---When this option is used, there is no need to provide the
---.Ar name ,
---.Ar class
---and
---.Ar type
---arguments.
---.Nm dig
---automatically performs a lookup for a name like
---.Dv 11.12.13.10.in-addr.arpa
---and sets the query type and class to PTR and IN respectively.
---By default, IPv6 addresses are looked up using the
---IP6.ARPA domain and binary labels as defined in RFC2874.
---To use the older RFC1886 method using the IP6.INT domain and "nibble" labels,
---specify the
---.Fl n
---(nibble) option.
---.Pp
---To sign the DNS queries sent by
---.Nm dig
---and their responses using transaction signatures (TSIG),
---specify a TSIG key file using the
---.Fl k
---option. You can also specify the TSIG key itself on the command
---line using the
---.Fl y
---option;
---.Ar name
---is the name of the TSIG key and
---.Ar key
---is the actual key. The key is a base-64 encoded string,
--- typically generated by
---.Xr dnssec-keygen 8 .
---Caution should be taken when using the
---.Fl y
---option on multi-user systems as the key can be visible
---in the output from
---.Xr ps 1
---or in the shell's history file.
---When using TSIG authentication with
---.Nm dig ,
---the name server that is queried needs to know the key and algorithm
---that is being used.
---In BIND, this is done by providing appropriate
---.Dv key
---and
---.Dv server
---statements in
---.Pa named.conf .
---.Sh QUERY OPTIONS
---.Nm dig
---provides a number of query options which affect the way in which
---lookups are made and the results displayed.
---Some of these set or reset flag bits in the query header,
---some determine which sections of the answer get printed,
---and others determine the timeout and retry strategies.
---.Pp
---Each query option is identified by a keyword preceded by a
---plus sign: \*q+\*q.
---Some keywords set or reset an option.
---These may be preceded by the string \*qno\*q to negate the meaning of
---that keyword.
---Other keywords assign values to options like the timeout interval.
---They have the form
---.Dv +keyword=value .
---The query options are:
---.Bl -tag -width +[no]additional
---.It +[no]tcp
---Use [do not use] TCP when querying name servers.
---The default behaviour is to use UDP unless an AXFR or IXFR query is
---requested, in which case a TCP connection is used.
---.It +[no]vc
---Use [do not use] TCP when querying name servers.
---This alternate syntax to
---.Ar +[no]tcp
---is provided for backwards compatibility.
---The "vc" stands for "virtual circuit".
---.It +[no]ignore
---Ignore truncation in UDP responses instead of
---retrying with TCP. By default, TCP retries are
---performed.
---.It +domain=somename
---Set the default domain to
---.Ar somename ,
---as if specified in a
---.Dv domain
---directive in
---.Pa /etc/resolv.conf .
---.It +[no]search
---Use [do not use] the search list in
---.Pa resolv.conf
---(if any).
---The search list is not used by default.
---.It +[no]defname
---Use [do not use] the default domain name, if any, in
---.Pa resolv.conf
---The default is not to append that name to
---.Ar name
---when making queries.
---.It +[no]aaonly
---This option does nothing.
---It is provided for compatibilty with old versions of
---.Nm dig
---where it set an unimplemented resolver flag.
---.It +[no]adflag
---Set [do not set] the AD (authentic data) bit in the query.
---The AD bit currently has a standard meaning only in responses,
---not in queries, but the ability to set the bit in the query
---is provided for completeness.
---.It +[no]cdflag
---Set [do not set] the CD (checking disabled) bit in the query.
---This requests the server to not perform DNSSEC validation
---of responses.
---.It +[no]recursive
---Toggle the setting of the RD (recursion desired) bit in the query.
---This bit is set by default, which means
---.Nm dig .
---normally sends recursive queries.
---Recursion is automatically disabled when the
---.Ar +nssearch
---or
---.Ar +trace
---query options are used.
---.It +[no]nssearch
---When this option is set,
---.Nm dig
---attempts to find the authoritative name servers for the zone containing
---the name being looked up and
---display the SOA record that each name server has for the zone.
---.It +[no]trace
---Toggle tracing of the delegation path from the root name servers for
---the name being looked up.
---Tracing is disabled by default.
---When tracing is enabled,
---.Nm dig
---makes iterative queries to resolve the name being looked up.
---It will follow referrals from the root servers, showing
---the answer from each server that was used to resolve the lookup.
---.It +[no]cmd
---toggles the printing of the initial comment in the output identifying
---the version of
---.Nm dig
---and the query options that have been applied.
---This comment is printed by default.
---.It +[no]short
---Provide a terse answer.
---The default is to print the answer in a verbose form.
---.It +[no]identify
---Show [or do not show] the IP address and port number that supplied the
---answer when the
---.Ar +short
---option is enabled.
---If short form answers are requested, the default is not to show
---the source address and port number of the server that provided the
---answer.
---.It +[no]comments
---Toggle the display of comment lines in the output.
---The default is to print comments.
---.It +[no]stats
---This query option toggles the printing of statistics: when the query was
---made, the size of the reply and so on.
---The default behaviour is to print the query statistics.
---.It +[no]qr
---Print [do not print] the query as it is sent.
---before sending the query. By default, the query is not printed.
---.It +[no]question
---Print [do not print] the question section of a query when an answer is
---returned.
---The default is to print the question section as a comment.
---.It +[no]answer
---Display [do not display] the answer section of a reply.
---The default is to display it.
---.It +[no]authority
---Display [do not display] the authority section of a reply.
---The default is to display it.
---.It +[no]additional
---Display [do not display] the additional section of a reply.
---The default is to display it.
---.It +[no]all
---Set or clear all display flags
---.It +time=T
---Sets the timeout for a query to
---.Dv T
---seconds.
---The default time out is 5 seconds.
---An attempt to set
---.Dv T
---to less than 1 will result in a query timeout of 1 second being applied.
---.It +tries=A
---Sets the number of times to retry UDP queries to server to
---.Dv T
---instead of the default, 3.
---If
---.Dv T
---is less than or equal to zero, the number of retries is silently rounded
---up to 1.
---.It +ndots=D
---Set the number of dots that have to appear in
---.Ar name
---to
---.Dv D
---for it to be considered absolute. The default value is that
---defined using the ndots statement in
---.Pa /etc/resolv.conf ,
---or 1 if no ndots statement is present. Names with fewer
---dots are interpreted as relative names and will be searched
---for in the domains listed in the
---.Dv search
---or
---.Dv domain
---directive in
---.Pa /etc/resolv.conf .
---.It +bufsize=B
---Set the UDP message buffer size advertised using EDNS0 to
---.Dv B
---bytes.
---The maximum and minimum sizes of this buffer are 65535 and 0
---respectively.
---Values outside this range are rounded up or down appropriately.
---.El
---.Sh MULTIPLE QUERIES
---.Pp
---The BIND 9
---implementation of
---.Nm dig
---supports specifying multiple queries on the command line
---(in addition to supporting the
---.Fl f
---batch file option).
---Each of those queries can be supplied with its own set of flags,
---options and query options.
---.Pp
---In this case,
---.Ar query1 ,
---.Ar query2
---and so on represent an individual query in the command-line syntax described
---above.
---Each consists of any of the standard options and flags, the name to be looked
---up, an optional query type and class and any query options that should
---be applied to that query.
---.Pp
---A global set of query options, which should be applied to all queries, can
---also be supplied.
---These global query options must precede the first tuple of name, class, type,
---options, flags, and query options supplied on the command line.
---Any global query options can be overridden by a
---query-specific set of query options.
---For example:
---.Bd -literal
---dig +qr www.isc.org any -x 127.0.0.1 isc.org ns +noqr
---.Ed
---.Pp
---shows how
---.Nm dig
---could be used from the command line to make three lookups: an ANY query
---for
---.Dv www.isc.org ,
---a reverse lookup of 127.0.0.1
---and
---a query for the NS records of
---.Dv isc.org .
---A global query option of
---.Ar +qr
---is applied, so that
---.Nm dig
---shows the initial query it made for each lookup.
---The final query has a local query option of
---.Ar +noqr
---which means that
---.Nm dig
---will not print the initial query when it looks up the
---NS records for
---.Dv isc.org .
---.Sh FILES
---.Pa /etc/resolv.conf
---.Sh SEE ALSO
---.Xr host 1 ,
---.Xr resolver 5 ,
---.Xr named 8 ,
---.Xr dnssec-keygen 8 ,
---.Xr RFC1035 .
---.Sh BUGS
---There are probably too many query options.
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: host.1,v 1.6 2000/11/18 02:57:26 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt HOST 1
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm host
---.Nd DNS lookup utility
---.Sh SYNOPSIS
---.Nm host
---.Op Fl aCdlnrTwv
---.Op Fl c Ar class
---.Op Fl N Ar ndots
---.Op Fl R Ar number
---.Op Fl t Ar type
---.Op Fl W Ar wait
---.Ar name
---.Op Ar server
---.Sh DESCRIPTION
---.Nm host
---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,
---.Nm host
---prints a short summary of its command line arguments and options.
---.Pp
---.Ar name
---is the domain name that is to be looked up.
---It can also be a dotted-decimal IPv4 address
---or a colon-delimited IPv6 address,
---in which case
---.Nm host
---will by default perform a reverse lookup for that address.
---.Ar server
---is an optional argument which is either the name or IP address of the
---name server that
---.Nm host
---should query instead of the server or servers listed in
---.Pa /etc/resolv.conf .
---.Pp
---The
---.Fl a
---(all) option is equivalent to setting the
---.Fl v
---option and asking
---.Nm host
---to make a query of type ANY.
---.Pp
---When the
---.Fl C
---option is used,
---.Nm host
---will attempt to display the SOA records for zone
---.Ar name
---from all the listed authoritative name servers for that zone.
---The list of name servers is defined by the NS records that are found for
---the zone.
---.Pp
---The
---.Fl c
---option instructs to make a DNS query of class
---.Ar class .
---This can be used to lookup Hesiod or Chaosnet class resource records.
---The default class is IN: Internet.
---.Pp
---Verbose output is generated by
---.Nm host
---when the
---.Fl d
---or
---.Fl v
---option is used.
---The two options are equivalent.
---They have been provided for backwards compatibility.
---In previous versions, the
---.Fl d
---option switched on debugging traces and
---.Fl v
---enabled verbose output.
---.Pp
---List mode is selected by the
---.Fl l
---option.
---This makes
---.Nm host
---perform a zone transfer for zone
---.Ar name .
---The argument is provided for compatibility with older implemementations.
---This option is equivalent to making a query of type AXFR.
---.Pp
---The
---.Fl n
---option specifies that reverse lookups of IPv6 addresses should
---use the IP6.INT domain and "nibble" labels as defined in RFC1886.
---The default is to use IP6.ARPA and binary labels as defined in RFC2874.
---.Pp
---The
---.Fl N
---option sets the number of dots that have to be in
---.Ar name
---for it to be considered absolute. The default value is that
---defined using the ndots statement in
---.Pa /etc/resolv.conf ,
---or 1 if no ndots statement is present. Names with fewer
---dots are interpreted as relative names and will be searched
---for in the domains listed in the
---.Dv search
---or
---.Dv domain
---directive in
---.Pa /etc/resolv.conf .
---.Pp
---The number of UDP retries for a lookup can be changed with the
---.Fl R
---option.
---.Ar number
---indicates how many times
---.Nm host
---will repeat a query that does not get answered.
---The default number of retries is 1.
---If
---.Ar number
---is negative or zero, the number of retries will default to 1.
---.Pp
---Non-recursive queries can be made via the
---.Fl r
---option.
---Setting this option clears the
---.Dv RD
---- recursion desired - bit in the query which
---.Nm host
---makes.
---This should mean that the name server receiving the query will not attempt
---to resolve
---.Ar name .
---The
---.Fl r
---option enables
---.Nm host
---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.
---.Pp
---By default
---.Nm host
---uses UDP when making queries.
---The
---.Fl T
---option makes it use a TCP connection when querying the name server.
---TCP will be automatically selected for queries that require it,
---such as zone transfer (AXFR) requests.
---.Pp
---The
---.Fl t
---option is used to select the query type.
---.Ar type
---can be any recognised query type: CNAME, NS, SOA, SIG, KEY, AXFR, etc.
---When no query type is specified,
---.Nm host
---automatically selects an appropriate query type.
---By default it looks for A records, but if the
---.Fl C
---option was given, queries will be made for SOA records,
---and if
---.Ar name
---is a dotted-decimal IPv4 address or colon-delimited IPv6 address,
---.Nm host
---will query for PTR records.
---.Pp
---The time to wait for a reply can be controlled through the
---.Fl W
---and
---.Fl w
---options.
---The
---.Fl W
---option makes
---.Nm host
---wait for
---.Ar wait
---seconds.
---If
---.Ar wait
---is less than one,
---the wait interval is set to one second.
---When the
---.Fl w
---option is used,
---.Nm host
---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.
---.Sh FILES
---.Pa /etc/resolv.conf
---.Sh SEE ALSO
---.Xr dig 1 ,
---.Xr resolver 5
---.Xr named 8 .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: dnssec-keygen.8,v 1.11 2000/11/18 02:57:34 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt DNSSEC-KEYGEN 8
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm dnssec-keygen
---.Nd key generation tool for DNSSEC
---.Sh SYNOPSIS
---.Nm dnssec-keygen
---.Fl a Ar algorithm
---.Fl b Ar keysize
---.Op Fl c Ar class
---.Op Fl e
---.Op Fl g Ar generator
---.Op Fl h
---.Fl n Ar nametype
---.Op Fl p Ar protocol-value
---.Op Fl r Ar randomdev
---.Op Fl s Ar strength-value
---.Op Fl t Ar type
---.Op Fl v Ar level
---.Ar name
---.Sh DESCRIPTION
---.Nm dnssec-keygen
---generates keys for DNSSEC, Secure DNS, as defined in RFC2535.
---It also generates keys for use in Transaction Signatures, TSIG, which
---is defined in RFC2845.
---.Pp
---A short summary of the options and arguments to
---.Nm dnssec-keygen
---is printed by the
---.Fl h
---(help) option.
---.Pp
---The
---.Fl a ,
---.Fl b ,
---and
---.Fl n
---options and their arguments must be supplied when generating keys.
---The domain name that the key has to be generated for is given by
---.Ar name .
---.Pp
---The choice of encryption algorithm is selected by the
---.Fl a
---option to
---.Nm dnssec-keygen .
---.Ar algorithm
---must be one of
---.Dv RSAMD5 ,
---.Dv DH ,
---.Dv DSA
---or
---.Dv HMAC-MD5
---to indicate that an RSA, Diffie-Hellman, Digital Signature
---Algorithm or HMAC-MD5 key is required.
---An argument of
---.Dv RSA
---can also be given, which is equivalent to
---.Dv RSAMD5 .
---The argument identifying the encryption algorithm is case-insensitive.
---DNSSEC specifies DSA as a mandatory algorithm and RSA as a recommended one.
---Implementations of TSIG must support HMAC-MD5.
---.Pp
---The number of bits in the key is determined by the
---.Ar keysize
---argument following the
---.Fl b
---option.
---The choice of key size depends on the algorithm that is used.
---RSA keys must be between 512 and 2048 bits.
---Diffie-Hellman keys must be between 128 and 4096 bits.
---For DSA, the key size must be between 512 and 1024 bits and a multiple
---of 64.
---The length of an HMAC-MD5 key can be between 1 and 512 bits.
---.Pp
---The
---.Fl n
---option specifies how the generated key will be used.
---.Ar nametype
---can be either
---.Dv ZONE ,
---.Dv HOST ,
---.Dv ENTITY ,
---or
---.Dv USER
---to indicate that the key will be used for signing a zone, host,
---entity or user respectively.
---In this context
---.Dv HOST
---and
---.Dv ENTITY
---are identical.
---.Ar nametype
---is case-insensitive.
---.Pp
---The
---.Fl c
---option specifies that the when creating a KEY record, the specified class
---should be used instead of IN.
---.Pp
---The
---.Fl e
---option can only be used when generating RSA keys.
---It tells
---.Nm dnssec-keygen
---to use a large exponent.
---When creating Diffie-Hellman keys, the
---.Fl g
---option selects the Diffie-Hellman generator
---.Ar generator
---that is to be used.
---The only supported values value of
---.Ar generator
---are 2 and 5.
---If no Diffie-Hellman generator is supplied, a known prime
---from RFC2539 will be used if possible; otherwise 2 will be used as the
---generator.
---.Pp
---The
---.Fl p
---option sets the protocol value for the generated key to
---.Ar protocol-value .
---The default is 2 (email) for keys of type
---.Dv USER
---and 3 (DNSSEC) for all other key types.
---Other possible values for this argument are listed in RFC2535 and its
---successors.
---.Pp
---.Nm dnssec-keygen
---uses random numbers to seed the process
---of generating keys.
---If the system does not have a
---.Pa /dev/random
---device that can be used for generating random numbers,
---.Nm dnssec-keygen
---will prompt for keyboard input and use the time intervals between
---keystrokes to provide randomness.
---The
---.Fl r
---option overrides this behaviour, making
---.Nm dnssec-keygen
---use
---.Ar randomdev
---as a source of random data.
---.Pp
---The key's strength value can be set with the
---.Fl s
---option.
---The generated key will sign DNS resource records
---with a strength value of
---.Ar strength-value .
---It should be a number between 0 and 15.
---The default strength is zero.
---The key strength field currently has no defined purpose in DNSSEC.
---.Pp
---The
---.Fl t
---option indicates if the key is to be used for authentication or
---confidentiality.
---.Ar type
---can be one of
---.Dv AUTHCONF ,
---.Dv NOAUTHCONF ,
---.Dv NOAUTH
---or
---.Dv NOCONF .
---The default is
---.Dv AUTHCONF .
---If type is
---.Dv AUTHCONF
---the key can be used for authentication and confidentialty.
---Setting
---.Ar type
---to
---.Dv NOAUTHCONF
---indicates that the key cannot be used for authentication or confidentialty.
---A value of
---.Dv NOAUTH
---means the key can be used for confidentiality but not for
---authentication.
---Similarly,
---.Dv NOCONF
---defines that the key cannot be used for confidentiality though it can
---be used for authentication.
---.Pp
---The
---.Fl v
---option can be used to make
---.Nm dnssec-keygen
---more verbose.
---As the debugging/tracing level
---.Ar level
---increases,
---.Nm dnssec-keygen
---generates increasingly detailed reports about what it is doing.
---The default level is zero.
---.Sh GENERATED KEYS
---When
---.Nm dnssec-keygen
---completes it prints a string of the form
---.Ar Knnnn.+aaa+iiiii
---on the standard output.
---This is an identification string for the key it has generated.
---These strings can be supplied as arguments to
---.Xr dnssec-makekeyset 8 .
---.Pp
---The
---.Ar nnnn.
---part is the dot-terminated domain name given by
---.Ar name .
---The DNSSEC algorithm identifier is indicated by
---.Ar aaa -
---001 for RSA, 002 for Diffie-Hellman, 003 for DSA or 157 for HMAC-MD5.
---.Ar iiiii
---is a five-digit number identifying the key.
---.Pp
---.Nm dnssec-keygen
---creates two files.
---The file names are adapted from the key identification string above.
---They have names of the form:
---.Ar Knnnn.+aaa+iiiii.key
---and
---.Ar Knnnn.+aaa+iiiii.private .
---These contain the public and private parts of the key respectively.
---The files generated by
---.Nm dnssec-keygen
---obey this naming convention to
---make it easy for the signing tool
---.Xr dnssec-signzone 8
---to identify which file(s) have to be read to find the necessary
---key(s) for generating or validating signatures.
---.Pp
---The
---.Ar .key
---file contains a KEY resource record that can be inserted into a zone file
---with a
---.Dv $INCLUDE
---statement.
---The private part of the key is in the
---.Ar .private
---file.
---It contains details of the encryption algorithm that was used and any
---relevant parameters: prime number, exponent, modulus, subprime, etc.
---For obvious security reasons, this file does not have general read
---permission.
---The private part of the key is used by
---.Xr dnssec-signzone 8
---to generate signatures and the public part is used to verify the
---signatures.
---Both
---.Ar .key
---and
---.Ar .private
---key files are generated for symmetric encryption algorithm such as
---HMAC-MD5, even though the public and private key are equivalent.
---.Sh EXAMPLE
---To generate a 768-bit DSA key for the domain
---.Dv example.com ,
---the following command would be issued:
---.Pp
---.Dl # dnssec-keygen -a DSA -b 768 -n ZONE example.com
---.Dl Kexample.com.+003+26160
---.Pp
---.Nm dnssec-keygen
---has printed the key identification string
---.Dv Kexample.com.+003+26160 ,
---indicating a DSA key with identifier 26160.
---It will also have created the files
---.Pa Kexample.com.+003+26160.key
---and
---.Pa Kexample.com.+003+26160.private
---containing respectively the public and private keys for the generated
---DSA key.
---.Sh FILES
---.Pa /dev/random
---.Sh SEE ALSO
---.Xr RFC2535,
---.Xr RFC2845,
---.Xr RFC2539,
---.Xr dnssec-makekeyset 8 ,
---.Xr dnssec-signkey 8 ,
---.Xr dnssec-signzone 8 .
---.Sh BUGS
---The naming convention for the public and private key files is a little
---clumsy.
---It won't work for domain names that are longer than 236 characters
---because of the
---.Ar .+aaa+iiiii.private
---suffix results in filenames that are too long for most
---.Ux
---systems.
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: dnssec-makekeyset.8,v 1.9 2000/11/18 02:57:35 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt DNSSEC-MAKEKEYSET 8
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm dnssec-makekeyset
---.Nd produce a set of DNSSEC keys
---.Sh SYNOPSIS
---.Nm dnssec-makekeyset
---.Op Fl h
---.Op Fl s Ar start-time
---.Op Fl e Ar end-time
---.Op Fl t Ar TTL
---.Op Fl r Ar randomdev
---.Op Fl p
---.Op Fl v Ar level
---.Ar keyfile ....
---.Sh DESCRIPTION
---.Nm dnssec-makekeyset
---generates a key set from one or more keys created by
---.Xr dnssec-keygen 8 .
---It creates a file containing KEY and SIG records for some zone which
---can then be signed by the zone's parent if the parent zone is
---DNSSEC-aware.
---.Ar keyfile
---should be a key identification string as reported by
---.Xr dnssec-keygen 8 :
---i.e.
---.Ar Knnnn.+aaa+iiiii
---where
---.Ar nnnn
---is the name of the key,
---.Ar aaa
---is the encryption algorithm and
---.Ar iiiii
---is the key identifier.
---Multiple
---.Ar keyfile
---arguments can be supplied when there are several keys to be combined
---by
---.Nm dnssec-makekeyset
---into a key set.
---.Pp
---For any SIG records that are in the key set, the start time when the
---SIG records become valid is specified with the
---.Fl s
---option.
---.Ar start-time
---can either be an absolute or relative date.
---An absolute start time is indicated by a number in YYYYMMDDHHMMSS
---notation: 20000530144500 denotes 14:45:00 UTC on May 30th, 2000.
---A relative start time is supplied when
---.Ar start-time
---is given as +N: N seconds from the current time.
---If no
---.Fl s
---option is supplied, the current date and time is used for the start
---time of the SIG records.
---.Pp
---The expiry date for the SIG records can be set by the
---.Fl e
---option.
---Note that in this context, the expiry date specifies when the SIG
---records are no longer valid, not when they are deleted from caches on name
---servers.
---.Ar end-date
---also represents an absolute or relative date.
---YYYYMMDDHHMMSS notation is used as before to indicate an absolute date
---and time.
---When
---.Ar end-date
---is +N,
---it indicates that the SIG records will expire in N seconds after their
---start date.
---If
---.Ar end-date
---is written as now+N,
---the SIG records will expire in N seconds after the current time.
---When no expiry date is set for the SIG records,
---.Nm dnssec-makekeyset
---defaults to an expire time of 30 days from the start time of the SIG
---records.
---.Pp
---An alternate source of random data can be specified with the
---.Fl r
---option.
---.Ar randomdev
---is the name of the file to use to obtain random data.
---By default
---.Pa /dev/random
---is used if this device is available.
---If it is not provided by the operating system and no
---.Fl r
---option is used,
---.Nm dnssec-makekeyset
---will prompt the user for input from the keyboard and use the time
---between keystrokes to derive some random data.
---.Pp
---The
---.Fl p
---option instructs
---.Nm dnssec-makekeyset
---to use pseudo-random data when self-signing the keyset. This is faster, but
---less secure, than using genuinely random data for signing.
---This option may be useful when the entropy source is limited.
---.Pp
---The
---.Fl t
---option is followed by a time-to-live argument
---.Ar TTL
---which indicates the TTL value that will be assigned to the assembled KEY
---and SIG records in the output file.
---.Ar TTL
---is expressed in seconds.
---If no
---.Fl t
---option is provided,
---.Nm dnssec-makekeyset
---prints a warning and uses a default TTL of 3600 seconds.
---.Pp
---The
---.Fl v
---option can be used to make
---.Nm dnssec-makekeyset
---more verbose.
---As the debugging/tracing level
---.Ar level
---increases,
---.Nm dnssec-makekeyset
---generates increasingly detailed reports about what it is doing.
---The default level is zero.
---.Pp
---The
---.Fl h
---option makes
---.Nm dnssec-makekeyset
---to print a short summary of its options and arguments.
---.Pp
---If
---.Nm dnssec-makekeyset
---is successful, it creates a file name of the form
---.Ar keyset-nnnn. .
---This file contains the KEY and SIG records for domain
---.Dv nnnn ,
---the domain name part from the key file identifier produced when
---.Nm dnssec-keygen
---created the domain's public and private keys.
---The
---.Ar keyset
---file can then be transferred to the DNS administrator of the parent
---zone for them to sign the contents with
---.Xr dnssec-signkey 8 .
---.Sh EXAMPLE
---The following command generates a key set for the DSA key for
---.Dv example.com
---that was shown in the
---.Xr dnssec-keygen 8
---man page.
---The backslash is for typographic reasons and would not be provided on
---the command line when running
---.Nm dnssec-makekeyset .
---.nf
---.Dl # dnssec-makekeyset -t 86400 -s 20000701120000 \e\p
---.Dl -e +2592000 Kexample.com.+003+26160
---.fi
---.Pp
---.Nm dnssec-makekeyset
---will create a file called
---.Pa keyset-example.com.
---containing a SIG and KEY record for
---.Dv example.com.
---These records will have a TTL of 86400 seconds (1 day).
---The SIG record becomes valid at noon UTC on July 1st 2000 and expires
---30 days (2592000 seconds) later.
---.Pp
---The DNS administrator for
---.Dv example.com
---could then send
---.Pa keyset-example.com.
---to the DNS administrator for
---.Dv .com
---so that they could sign the resource records in the file.
---This assumes that the
---.Dv .com
---zone is DNSSEC-aware and the administrators of the two zones have some
---mechanism for authenticating each other and exchanging the keys and
---signatures securely.
---.Sh FILES
---.Pa /dev/random .
---.Sh SEE ALSO
---.Xr RFC2535 ,
---.Xr dnssec-keygen 8 ,
---.Xr dnssec-signkey 8 .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: dnssec-signkey.8,v 1.11 2000/11/18 02:57:37 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt DNSSEC-SIGNKEY 8
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm dnssec-signkey
---.Nd DNSSEC keyset signing tool
---.Sh SYNOPSIS
---.Nm dnssec-signkey
---.Op Fl h
---.Op Fl s Ar start-time
---.Op Fl e Ar end-time
---.Op Fl c Ar class
---.Op Fl p
---.Op Fl r Ar randomdev
---.Op Fl v Ar level
---.Ar keyset
---.Ar keyfile ...
---.Sh DESCRIPTION
---.Nm dnssec-signkey
---is used to sign a key set for a child zone.
---Typically this would be provided by a
---.Ar keyset
---file generated by
---.Xr dnssec-makekeyset 8 .
---This provides a mechanism for a DNSSEC-aware zone to sign the keys of
---any DNSSEC-aware child zones.
---The child zone's key set gets signed with the zone keys for its parent
---zone.
---.Ar keyset
---will be the pathname of the child zone's
---.Ar keyset
---file.
---Each
---.Ar keyfile
---argument will be a key identification string as reported by
---.Xr dnssec-keygen 8
---for the parent zone.
---This allows the child's keys to be signed by more than one
---parent zone key.
---.Pp
---The
---.Fl h
---option makes
---.Nm dnssec-signkey
---print a short summary of its command line options
---and arguments.
---.Pp
---By default, the validity period of the generated SIG records is copied
---from that of the signatures in the input key set. This may be overriden
---with the
---.Fl s
---and
---.Fl e
---options, both of which must be present if either is.
---The start of the validity period is specified with the
---.Fl s
---option.
---.Ar start-time
---can either be an absolute or relative date.
---An absolute start time is indicated by a number in YYYYMMDDHHMMSS
---notation: 20000530144500 denotes 14:45:00 UTC on May 30th, 2000.
---A relative start time is supplied when
---.Ar start-time
---is given as +N: N seconds from the current time.
---If no
---.Fl s
---option is supplied, the current date and time is used for the start
---time of the SIG records.
---.Pp
---The expiry date for the SIG records can be set by the
---.Fl e
---option.
---Note that in this context, the expiry date specifies when the SIG
---records are no longer valid, not when they are deleted from caches on name
---servers.
---.Ar end-date
---also represents an absolute or relative date.
---YYYYMMDDHHMMSS notation is used as before to indicate an absolute date
---and time.
---When
---.Ar end-date
---is +N,
---it indicates that the SIG records will expire in N seconds after their
---start date.
---If
---.Ar end-date
---is written as now+N,
---the SIG records will expire in N seconds after the current time.
---.Pp
---The
---.Fl c
---option specifies that the KEY records in the input and output key sets should
---have the specified class instead of IN.
---.Pp
---.Nm dnssec-signkey
---may need random numbers in the process of generating keys.
---If the system does not have a
---.Pa /dev/random
---device that can be used for generating random numbers,
---.Nm dnssec-signkey
---will prompt for keyboard input and use the time intervals between
---keystrokes to provide randomness.
---The
---.Fl r
---option overrides this behaviour, making
---.Nm dnssec-signkey
---use
---.Ar randomdev
---as a source of random data.
---.Pp
---The
---.Fl p
---option instructs
---.Nm dnssec-signkey
---to use pseudo-random data when signing the keys. This is faster, but
---less secure, than using genuinely random data for signing.
---This option may be useful when there are many child zone keysets to
---sign or if the entropy source is limited.
---It could also be used for short-lived keys and signatures that don't
---require as much protection against cryptanalysis, such as when the key
---will be discarded long before it could be compromised.
---.Pp
---The
---.Fl v
---option can be used to make
---.Nm dnssec-signkey
---more verbose.
---As the debugging/tracing level
---.Ar level
---increases,
---.Nm dnssec-signkey
---generates increasingly detailed reports about what it is doing.
---The default level is zero.
---.Pp
---When
---.Nm dnssec-signkey
---completes successfully, it generates a file called
---.Ar signedkey-nnnn.
---containing the signed keys for child zone
---.Ar nnnn .
---The keys from the
---.Ar keyset
---file will have been signed by the parent zone's key or keys which were
---supplied as
---.Ar keyfile
---arguments.
---This file should be sent to the DNS administrator of the child zone.
---They arrange for its contents to be incorporated into the zone file
---when it next gets signed with
---.Xr dnssec-signzone 8 .
---A copy of the generated
---.Ar signedkey
---file should be kept by the parent zone's DNS administrator, since
---it will be needed when signing the parent zone.
---.Sh EXAMPLE
---The DNS administrator for a DNSSEC-aware
---.Dv .com
---zone would use the following command to make
---.Nm dnssec-signkey
---sign the
---.Ar keyset
---file for
---.Dv example.com
---created in the example shown in the man page for
---.Xr dnssec-makekeyset 8 :
---.Pp
---.Dl # dnssec-signkey keyset-example.com. Kcom.+003+51944
---.Pp
---where
---.Dv Kcom.+003+51944
---was a key file identifier that was produced when
---.Xr dnssec-keygen 8
---generated a key for the
---.Dv .com
---zone.
---.Pp
---.Nm dnssec-signkey
---will produce a file called
---.Dv signedkey-example.com.
---which has the keys for
---.Dv example.com
---signed by the
---.Dv com
---zone's zone key.
---.Sh FILES
---.Pa /dev/random
---.Sh SEE ALSO
---.Xr RFC2535,
---.Xr dnssec-keygen 8 ,
---.Xr dnssec-makekeyset 8 ,
---.Xr dnssec-signzone 8 .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: dnssec-signzone.8,v 1.15 2000/11/18 02:57:38 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt DNSSEC-SIGNZONE 8
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm dnssec-signzone
---.Nd DNSSEC zone signing tool
---.Sh SYNOPSIS
---.Nm dnssec-signzone
---.Op Fl a
---.Op Fl c Ar class
---.Op Fl d Ar directory
---.Op Fl s Ar start-time
---.Op Fl e Ar end-time
---.Op Fl i Ar interval
---.Op Fl o Ar origin
---.Op Fl f Ar output-file
---.Op Fl p
---.Op Fl r Ar randomdev
---.Op Fl t
---.Op Fl v Ar level
---.Ar zonefile
---.Op keyfile ....
---.Sh DESCRIPTION
---.Pp
---.Nm dnssec-signzone
---is used to sign a zone.
---Any
---.Ar signedkey
---files for the zone to be signed should be present in the current
---directory, along with the keys that will be used to sign the zone.
---If no
---.Ar keyfile
---arguments are supplied, the default behaviour is to use all of the zone's
---keys that are present in the current directory.
---Providing specific
---.Ar keyfile
---arguments constrains
---.Nm dnssec-signzone
---to only use those keys for signing the zone.
---Each
---.Ar keyfile
---argument would be an identification string for a key created with
---.Xr dnssec-keygen 8 .
---If the zone to be signed has any secure subzones, the
---.Ar signedkey
---files for those subzones need to be available in the
---current working directory used by
---.Nm dnssec-signzone .
---.Pp
---.Ar zonefile
---is the name of the unsigned zone file.
---Unless the file name is the same as the name of the zone, the
---.Fl o
---option should be given.
---.Ar origin
---will be the fully qualified domain origin for the zone.
---.Pp
---.Nm dnssec-signzone
---will generate NXT and SIG records for the zone and produce a signed
---version of the zone.
---If there is a
---.Ar signedkey
---file from the zone's parent, the parent's signatures will be
---incorporated into the generated signed zone file.
---The security status of delegations from the the signed zone
---- i.e. whether the child zones are DNSSEC-aware or not - is
---set according to the presence or absence of a
---.Ar signedkey
---file for the child in case.
---.Pp
---By default,
---.Nm dnssec-signzone
---generates a file called
---.Ar zonefile.signed
---containing the signed zone file.
---The output file name can be overridden usign the
---.Fl f
---option.
---.\" Don't hyphenate YYYYMMDDHHMMSS
---.nh YYYYMMDDHHMMSS
---.Pp
---.Nm dnssec-signzone
---does not verify the signatures by default.
---The
---.Fl a
---option makes it verify the signatures it generated.
---.Pp
---The date and time when the generated
---SIG records become valid can be specified with the
---.Fl s
---option.
---.Ar start-time
---can either be an absolute or relative date.
---An absolute start time is indicated by a number in YYYYMMDDHHMMSS
---notation: 20000530144500 denotes 14:45:00 UTC on May 30th, 2000.
---A relative start time is supplied when
---.Ar start-time
---is given as +N: N seconds from the current time.
---If no
---.Fl s
---option is supplied, the current date and time is used for the start
---time of the SIG records.
---.Pp
---The expiry date for the SIG records can be set by the
---.Fl e
---option.
---Note that in this context, the expiry date specifies when the SIG
---records are no longer valid, not when they are deleted from caches on name
---servers.
---.Ar end-date
---also represents an absolute or relative date.
---YYYYMMDDHHMMSS notation is used as before to indicate an absolute date
---and time.
---When
---.Ar end-date
---is +N,
---it indicates that the SIG records will expire in N seconds after their
---start date.
---If
---.Ar end-date
---is supplied as now+N,
---the SIG records will expire in N seconds after the current time.
---When no expiry date is set for the SIG records,
---.Nm dnssec-signzone
---defaults to an expire time of 30 days from the start time of the SIG
---records.
---.Pp
---When a previously signed zone is passed as input to
---.Nm dnssec-signzone ,
---records may be resigned. Whether or not to resign records is configurable
---by using the
---.Fl i
---option, which specifies the cycle interval as an offset from the current time
---(in seconds). If a SIG record expires after the cycle interval, it is
---retained. Otherwise, it is considered to be expiring soon, and
---.Nm dnssec-signzone
---will remove it and generate a new SIG record to replace it.
---.Pp
---The default cycle interval is one quarter of the difference between the
---specified signature end and start dates. So if the
---.Fl e
---and
---.Fl s
---options are not specified,
---.Nm dnssec-signzone
---generates signatures that are valid for 30 days from the current date
---by default, with a cycle interval of 7.5 days. Therefore, if any SIG records
---are due to expire in less than 7.5 days, they would be replaced
---with new ones.
---.Pp
---.Nm dnssec-signzone
---may need random numbers in the process of signing the zone.
---If the system does not have a
---.Pa /dev/random
---device that can be used for generating random numbers,
---.Nm dnssec-signzone
---will prompt for keyboard input and use the time intervals between
---keystrokes to provide randomness.
---The
---.Fl r
---option overrides this behaviour, making
---.Nm dnssec-signzone
---use
---.Ar randomdev
---as a source of random data.
---.Pp
---The
---.Fl p
---option instructs
---.Nm dnssec-signzone
---to use pseudo-random data when signing the keys. This is faster, but
---less secure, than using genuinely random data for signing.
---This option may be useful when signing large zones or when the
---entropy source is limited.
---.Pp
---The
---.Fl t
---option causes
---.Nm dnssec-signzone
---to print various statistics after signing the zone.
---.Pp
---The
---.Fl c
---option specifies that the KEY records in the input and output key sets should
---have the specified class instead of IN.
---.Pp
---The
---.Fl d
---option specifies that
---.Nm dnssec-signzone
---should look in a directory other than the current directory for signedkey
---files.
---.Pp
---An option of
---.Fl h
---makes
---.Nm dnssec-signzone
---print a short summary of its command line options
---and arguments.
---.Pp
---The
---.Fl v
---option can be used to make
---.Nm dnssec-signzone
---more verbose.
---As the debugging/tracing level
---.Ar level
---increases,
---.Nm dnssec-signzone
---generates increasingly detailed reports about what it is doing.
---The default level is zero.
---.Sh EXAMPLE
---The example below shows how
---.Nm dnssec-signzone
---could be used to sign the
---.Dv example.com
---zone with the key that was generated in the example given in the
---man page for
---.Xr dnssec-keygen 8 .
---The zone file for this zone is
---.Dv example.com ,
---which is the same as the origin, so there is no need to use the
---.Fl o
---option to set the origin.
---The zone's keys were either appended to the zone file or
---incorporated using a
---.Dv $INCLUDE
---statement.
---If there was a
---.Ar signedkey
---file from the parent zone - i.e.
---.Dv signedkey-example.com.
---- it should be present in the current directory.
---This allows the parent zone's signature to be included in the signed
---version of the
---.Dv example.com
---zone.
---.Pp
---.Dl # dnssec-signzone example.com Kexample.com.+003+26160
---.Pp
---.Nm dnssec-signzone
---will create a file called
---.Dv example.com.signed ,
---the signed version of the
---.Dv example.com
---zone.
---This file can then be referenced in a
---.Dv zone{}
---statement in
---.Pa /etc/named.conf
---so that it can be loaded by the name server.
---.Sh FILES
---.Pa /dev/random
---.Sh SEE ALSO
---.Xr RFC2535,
---.Xr dnssec-keygen 8 ,
---.Xr dnssec-signkey 8 .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwresd.8,v 1.9 2000/11/18 02:57:27 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRESD 8
---.Os BIND9 9
---.ds vT BIND 9 Programmer's Manual
---.Sh NAME
---.Nm lwresd
---.Nd lightweight resolver daemon
---.Sh SYNOPSIS
---.Nm lwresd
---.Op Fl C Ar config-file
---.Op Fl d Ar debuglevel
---.Op Fl f g s
---.Op Fl i Ar pid-file
---.Op Fl n Ar #cpus
---.Op Fl P Ar listen-port#
---.Op Fl p Ar port#
---.Op Fl t Ar directory
---.Op Fl u Ar user-id
---.Op Fl v
---.Sh DESCRIPTION
---.Nm lwresd
---is the daemon providing name lookup services to clients that use
---the BIND 9 lightweight resolver library.
---It is essentially a stripped-down, caching-only name server that
---answers queries using the BIND 9 lightweight resolver protocol
---rather than the DNS protocol.
---.Pp
---.Nm lwresd
---listens for resolver queries on a UDP port on the IPv4 loopback
---interface, 127.0.0.1.
---This means that
---.Nm lwresd
---can only be used by processes running on the local machine.
---By default UDP port number 921 is used for lightweight resolver
---requests and responses.
---.Pp
---Incoming lightweight resolver requests are decoded by
---.Nm lwresd
---which then resolves them using the DNS protocol.
---When the DNS lookup completes,
---.Nm lwresd
---encodes the answers from the name servers in the lightweight
---resolver format and returns them to the client that made the original
---request.
---.Pp
---If
---.Pa /etc/resolv.conf
---contains any
---.Sy nameserver
---entries,
---.Nm lwresd
---sends recursive DNS queries to those servers. This
---is similar to the use of forwarders in a chaching name
---server. If no
---.Sy nameserver
---entries are present, or if forwarding fails,
---.Nm lwresd
---resolves the queries autonomously starting at the
---root name servers, using a compiled-in list of root
---servers hints.
---.Pp
---The options to
---.Nm lwresd
---are as follows:
---.Bl -tag -width Ds
---.It Fl C
---use
---.Ar config-file
---as the configuration file instead of the default,
---.Pa /etc/resolv.conf .
---.It Fl d
---set the daemon's debug level to
---.Ar debuglevel .
---Debugging traces from
---.Nm lwresd
---become more verbose as the debug level increases.
---.It Fl f
---run
---.Nm lwresd
---in the foreground.
---.It Fl g
---run
---.Nm lwresd
---in the foreground and force all logging to
---.Dv stderr .
---.It Fl i
---write the daemon's process id to
---.Ar pid-file
---instead of the default pathname.
---.It Fl n
---create
---.Ar #cpus
---worker threads to take advantage of multiple CPUs.
---If no option is given,
---.Nm lwresd
---will try to determine the number of CPUs present and create
---one thread per CPU. If
---.Nm lwresd
---is unable to determine the number of CPUs, a single worker thread
---is created.
---.It Fl P
---listen for lightweight resolver queries on the loopback interface
---using UDP port
---.Ar port#
---instead of the default port number, 921.
---.It Fl p
---send DNS lookups to port number
---.Ar listen-port#
---when querying name servers.
---This provides a way of testing the lightweight resolver daemon with a
---name server that listens for queries on a non-standard port number.
---.It Fl s
---write memory usage statistics to
---.Dv stdout
---on exit.
---This option is only of interest to BIND 9 developers and may be
---removed or changed in a future release.
---.It Fl t
---tells
---.Nm lwresd
---to chroot() to
---.Ar directory
---immediately after reading its configuration file.
---.It Fl u
---run
---.Nm lwresd
---as
---.Ar user-id ,
---which is a user name or numeric id that must be present in the
---password file.
---The lightweight resolver daemon will change its user-id after it has
---carried out any privileged operations, such as writing the process-id
---file or binding a socket to a privileged port (typically any port
---less than 1024).
---.It Fl v
---report the version number and exit.
---.El
---.Sh FILES
---.Bl -tag -width /var/run/lwresd.pid -compact
---.It Pa /etc/resolv.conf
---default configuration file
---.It Pa /var/run/lwresd.pid
---default process-id file
---.El
---.Sh SEE ALSO
---.Xr named 8 ,
---.Xr lwres 3 .
---.Sh NOTES
---.Nm lwresd
---is a daemon for lightweight resolvers, not a lightweight daemon
---for resolvers.
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: named.8,v 1.11 2000/11/18 02:57:29 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt NAMED 8
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm named
---.Nd Internet domain name server
---.Sh SYNOPSIS
---.Nm named
---.Op Fl c Ar config-file
---.Op Fl d Ar debuglevel
---.Op Fl f g s
---.Op Fl n Ar #cpus
---.Op Fl p Ar port#
---.Op Fl t Ar directory
---.Op Fl u Ar user-id
---.Op Fl v
---.Op Fl x Ar cache-file
---.Sh DESCRIPTION
---.Nm named
---is a Domain Name System (DNS) server, part of the BIND 9 distribution
---from ISC. For more information on the DNS, see RFCs 1033, 1034, and 1035.
---.Pp
---When invoked without arguments,
---.Nm named
---will read the default configuration file
---.Pa /etc/named.conf ,
---read any initial data, and listen for queries.
---.Pp
---The options to
---.Nm named
---are as follows:
---.Bl -tag -width Ds
---.It Fl c
---use
---.Ar config-file
---as the configuration file instead of the default,
---.Pa /etc/named.conf .
---To ensure that reloading the configuration file continues to
---work after the server has changed its working directory
---due to to a possible
---.Dv directory
---option in the configuration file,
---.Ar config-file
---should be an absolute pathname.
---.It Fl d
---set the daemon's debug level to
---.Ar debuglevel .
---Debugging traces from
---.Nm named
---become more verbose as the debug level increases.
---.It Fl f
---run
---.Nm named
---in the foreground.
---.It Fl g
---run
---.Nm named
---in the foreground and force all logging to
---.Dv stderr .
---.It Fl n
---create
---.Ar #cpus
---worker threads to take advantage of multiple CPUs.
---If no option is given,
---.Nm named
---will try to determine the number of CPUs present and create
---one thread per CPU. If
---.Nm named
---is unable to determine the number of CPUs, a single worker thread
---is created.
---.It Fl p
---listen for queries on port
---.Ar port#
---instead of the default port number, 53.
---.It Fl s
---write memory usage statistics to
---.Dv stdout
---on exit.
---This option is mainly of interest
---to BIND9 developers and may be removed or changed in a future release.
---.It Fl t
---tells
---.Nm named
---to chroot() to
---.Ar directory
---immediately after reading its config file.
---This should be used in conjunction with the
---.Fl u
---option, as chrooting a process running as root doesn't
---enhance security on most systems - the way chroot() is defined
---allows a process with root privileges to escape the chroot jail.
---.It Fl u
---run
---.Nm named
---as UID
---.Ar user-id .
---.Nm named
---will change its UID after it has
---carried out any privileged operations, such as
---creating sockets that listen on privileged ports.
---.Pp
---On Linux,
---.Nm named
---uses the kernel's capability mechanism to drop
---all root privileges except the ability to bind() to a privileged
---port. Unfortunately, this means that the "-u" option only works
---when
---.Nm named
---is run on 2.3.99-pre3 or later kernel, since previous
---kernels did not allow privileges to be retained after setuid().
---.It Fl v
---report the version number and exit.
---.It Fl x
---load data from
---.Ar cache-file .
---into the cache of the default view.
---This option must not be used.
---It is only of interest
---to BIND9 developers and may be removed or changed in a future release.
---.El
---.Sh SIGNALS
---In routine operation, signals should not be used to \*qcontrol\*q the
---name server.
---.Nm rndc
---should be used instead.
---Sending the name server a
---.Dv SIGHUP
---signal forces a reload of the server.
---A
---.Dv SIGINT
---or
---.Dv SIGTERM
---signal can be used to gracefully shut down the server.
---Sending any other signals to the name server
---will have an undefined outcome.
---.\".Sh CONFIGURATION FILE FORMAT
---.\".Nm named 's
---.\"configuration file is too complex to describe in detail here.
---.\"A complete description is provided in the BIND9 Administrator
---.\"Reference Manual.
---.Sh FILES
---.Bl -tag -width /var/run/named.pid -compact
---.It Pa /etc/named.conf
---default configuration file
---.It Pa /var/run/named.pid
---default process-id file
---.El
---.Sh SEE ALSO
---.Xr RFC1033 ,
---.Xr RFC1034 ,
---.Xr RFC1035 ,
---.Xr rndc 8 ,
---.Xr lwresd 8 ,
---BIND9 Administrator Reference Manual, June 2000.
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: nsupdate.8,v 1.11 2000/11/30 00:20:38 gson Exp $
---
---.Dd Jun 30, 2000
---.Dt NSUPDATE 8
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm nsupdate
---.Nd Dynamic DNS update utility
---.Sh SYNOPSIS
---.Nm nsupdate
---.Op Fl d
---.Oo
---.Fl y Ar keyname:secret |
---.Fl k Ar keyfile
---.Oc
---.Op Fl v
---.Op filename
---.Sh DESCRIPTION
---.Nm nsupdate
---is used to submit Dynamic DNS Update requests as defined in RFC2136
---to a name server.
---This allows resource records to be added or removed from a zone
---without manually editing the zone file.
---A single update request can contain requests to add or remove more than one
---resource record.
---.Pp
---Zones that are under dynamic control via
---.Nm nsupdate
---or a DHCP server should not be edited by hand.
---Manual edits could
---conflict with dynamic updates and cause data to be lost.
---.Pp
---The resource records that are dynamically added or removed with
---.Nm nsupdate
---have to be in the same zone.
---Requests are sent to the zone's master server.
---This is identified by the MNAME field of the zone's SOA record.
---.Pp
---The
---.Fl d
---option makes
---.Nm nsupdate
---operate in debug mode.
---This provides tracing information about the update requests that are
---made and the replies received from the name server.
---.Pp
---Transaction signatures can be used to authenticate the Dynamic DNS
---updates.
---These use the TSIG resource record type described in RFC2845.
---The signatures rely on a shared secret that should only be known to
---.Nm nsupdate
---and the name server.
---Currently, the only supported encryption algorithm for TSIG is
---HMAC-MD5, which is defined in RFC 2104.
---Once other algorithms are defined for TSIG, applications will need to
---ensure they select the appropriate algorithm as well as the key when
---authenticating each other.
---For instance suitable
---.Dv key
---and
---.Dv server
---statements would be added to
---.Pa /etc/named.conf
---so that the name server can associate the appropriate secret key
---and algorithm with the IP address of the
---client application that will be using TSIG authentication.
---.Nm nsupdate
---does not read
---.Pa /etc/named.conf .
---.Pp
---.Nm nsupdate
---uses the
---.Fl y
---or
---.Fl k
---option to provide the shared secret needed to generate a TSIG record
---for authenticating Dynamic DNS update requests.
---These options are mutually exclusive.
---With the
---.Fl k
---option,
---.Nm nsupdate
---reads the shared secret from the file
---.Ar keyfile ,
---whose name is of the form
---.Pa K{name}.+157.+{random}.private .
---For historical
---reasons, the file
---.Pa K{name}.+157.+{random}.key
---must also be present. When the
---.Fl y
---option is used, a signature is generated from
---.Ar keyname:secret.
---.Ar keyname
---is the name of the key,
---and
---.Ar secret
---is the base64 encoded shared secret.
---Use of the
---.Fl y
---option is discouraged because the shared secret is supplied as a command
---line argument in clear text.
---This may be visible in the output from
---.Xr ps 1
---or in a history file maintained by the user's shell.
---.Pp
---By default
---.Nm nsupdate
---uses UDP to send update requests to the name server.
---The
---.Fl v
---option makes
---.Nm nsupdate
---use a TCP connection.
---This may be preferable when a batch of update requests is made.
---.Sh INPUT FORMAT
---.Nm nsupdate
---reads input from
---.Ar filename
---or standard input.
---Each command is supplied on exactly one line of input.
---Some commands are for administrative purposes.
---The others are either update instructions or prerequisite checks on the
---contents of the zone.
---These checks set conditions that some name or set of
---resource records (RRset) either exists or is absent from the zone.
---These conditions must be met if the entire update request is to succeed.
---Updates will be rejected if the tests for the prerequisite conditions fail.
---.Pp
---Every update request consists of zero or more prerequisites
---and zero or more updates.
---This allows a suitably authenticated update request to proceed if some
---specified resource records are present or missing from the zone.
---A blank input line causes the accumulated commands to be sent as one Dynamic
---DNS update request to the name server.
---.Pp
---The command formats and their meaning are as follows:
---.Bl -ohang indent
---.It Xo
---.Ic server Va servername Op port
---.Xc
---.sp 1
---Sends all dynamic update requests to the name server
---.Va servername .
---When no server statement is provided,
---.Nm nsupdate
---will send updates to the master server of the correct zone.
---The MNAME field of that zone's SOA record will identify the master
---server for that zone.
---.Va port
---is the port number on
---.Va servername
---where the dynamic update requests get sent.
---If no port number is specified, the default DNS port number of 53 is
---used.
---.It Xo
---.Ic local Va address Op port
---.Xc
---.sp 1
---Sends all dynamic update requests using the local
---.Va address .
---When no local statement is provided,
---.Nm nsupdate
---will send updates using an address and port choosen by the system.
---.Va port
---can additionally be used to make requests come from a specific port.
---If no port number is specified, the system will assign one.
---.It Xo
---.Ic zone Va zonename
---.Xc
---.sp 1
---Specifies that all updates are to be made to the zone
---.Va zonename .
---If no
---.Va zone
---statement is provided,
---.Nm nsupdate
---will attempt determine the correct zone to update based on the rest of the input.
---.It Xo
---.Ic prereq nxdomain Va domain-name
---.Xc
---.sp 1
---Requires that no resource record of any type exists with name
---.Va domain-name .
---.It Xo
---.Ic prereq yxdomain Va domain-name
---.Xc
---.sp 1
---Requires that
---.Va domain-name
---exists (has as at least one resource record, of any type).
---.It Xo
---.Ic prereq nxrrset Va domain-name Op class
---.Va type
---.Xc
---.sp 1
---Requires that no resource record exists of the specified
---.Va type ,
---.Va class
---and
---.Va domain-name .
---If
---.Va class
---is omitted, IN (internet) is assumed.
---.It Xo
---.Ic prereq yxrrset
---.Va domain-name Op class
---.Va type
---.Xc
---.sp 1
---This requires that a resource record of the specified
---.Va type ,
---.Va class
---and
---.Va domain-name
---must exist.
---If
---.Va class
---is omitted, IN (internet) is assumed.
---.It Xo
---.Ic prereq yxrrset
---.Va domain-name Op class
---.Va type data...
---.Xc
---.sp 1
---The
---.Va data
---from each set of prerequisites of this form
---sharing a common
---.Va type ,
---.Va class ,
---and
---.Va domain-name
---are combined to form a set of RRs. This set of RRs must
---exactly match the set of RRs existing in the zone at the
---given
---.Va type ,
---.Va class ,
---and
---.Va domain-name .
---The
---.Va data
---are written in the standard text representation of the resource record's
---RDATA.
---.It Xo
---.Ic update delete
---.Va domain-name Op class
---.Va Op type Op data...
---.Xc
---.sp 1
---Deletes any resource records named
---.Va domain-name .
---If
---.Va type
---and
---.Va data
---is provided, only matching resource records will be removed.
---The internet class is assumed if
---.Va class
---is not supplied.
---.It Xo
---.Ic update add
---.Va domain-name ttl Op class
---.Va type data..
---.Xc
---.sp 1
---Adds a new resource record with the specified
---.Va ttl ,
---.Va class
---and
---.Va data .
---.El
---.Sh EXAMPLES
---The examples below show how
---.Nm nsupdate
---could be used to insert and delete resource records from the
---.Dv example.com
---zone.
---Notice that the input in each example contains a trailing blank line so that
---a group of commands are sent as one dynamic update request to the
---master name server for
---.Dv example.com .
---.Bd -literal -offset indent
---# nsupdate
---> update delete oldhost.example.com A
---> update add newhost.example.com 86400 A 172.16.1.1
--->
---.Ed
---.Pp
---Any A records for
---.Dv oldhost.example.com
---are deleted.
---and an A record for
---.Dv newhost.example.com
---it IP address 172.16.1.1 is added.
---The newly-added record has a 1 day TTL (86400 seconds)
---.Bd -literal -offset indent
---# nsupdate
---> prereq nxdomain nickname.example.com
---> update add nickname.example.com CNAME somehost.example.com
--->
---.Ed
---.Pp
---The prerequisite condition gets the name server to check that there
---are no resource records of any type for
---.Dv nickname.example.com .
---If there are, the update request fails.
---If this name does not exist, a CNAME for it is added.
---This ensures that when the CNAME is added, it cannot conflict with the
---long-standing rule in RFC1034 that a name must not exist as any other
---record type if it exists as a CNAME.
---(The rule has been updated for DNSSEC in RFC2535 to allow CNAMEs to have
---SIG, KEY and NXT records.)
---.Pp
---.Sh FILES
---.Bl -tag -width K{name}.+157.+{random}.private -compact
---.It Pa /etc/resolv.conf
---used to identify default name server
---.It Pa K{name}.+157.+{random}.key
---base-64 encoding of HMAC-MD5 key created by
---.Xr dnssec-keygen 8 .
---.It Pa K{name}.+157.+{random}.private
---base-64 encoding of HMAC-MD5 key created by
---.Xr dnssec-keygen 8 .
---.El
---.Sh SEE ALSO
---.Xr RFC2136 ,
---.Xr RFC2137 ,
---.Xr RFC2104 ,
---.Xr RFC2845 ,
---.Xr RFC1034 ,
---.Xr RFC2535 ,
---.Xr named 8 ,
---.Xr dnssec-keygen 8 .
---.Sh BUGS
---The TSIG key is redundantly stored in two separate files.
---This is a consequence of nsupdate using the DST library
---for its cryptographic operations, and may change in future
---releases.
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: rndc.8,v 1.11 2000/11/30 00:20:39 gson Exp $
---
---.Dd Jun 30, 2000
---.Dt RDNC 8
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm rdnc
---.Nd name server control utility
---.Sh SYNOPSIS
---.Nm rndc
---.Op Fl c Ar config-file
---.Op Fl M
---.Op Fl m
---.Op Fl p Ar port#
---.Op Fl s Ar server
---.Op Fl v
---.Op Fl y Ar key_id
---.Ar command ....
---.Sh DESCRIPTION
---This command allows the system administrator to control the operation
---of a name server.
---It supersedes the
---.Xr ndc 8
---utility that was provided in old BIND releases.
---If
---.Nm rndc
---is invoked with no command line options or arguments, it
---prints a short summary of the supported commands and the available
---options and their arguments.
---.Pp
---.Nm rndc
---communicates with the name server over a TCP connection,
---sending commands authenticated with digital signatures.
---In the current versions of
---.Nm rndc
---and
---.Xr named 8
---the only supported encryption algorithm is HMAC-MD5, which uses a
---shared secret on each end of the connection.
---This provides TSIG-style authentication for the command request
---and the name server's response.
---All commands sent over the channel
---must be signed by a key_id known to the server.
---.Pp
---.Nm rndc
---reads its default configuration file,
---.Pa /etc/rndc.conf
---to determine how to contact the name server and decide what algorithm
---and keys is should use.
---The
---.Fl c
---option can be used to specify an alternate configuration file.
---.Pp
---.Ar server
---is the name or address of the server which matches a
---.Dv server
---statement in the configuration file for
---.Nm rndc .
---If no
---.Ar server
---is supplied on the command line, the host named by the
---.Dv default-server
---clause in the
---.Dv option
---statement of the configuration file will be used.
---.Pp
---The
---.Fl p
---option can be used to make
---.Nm rndc
---send commands to TCP port number
---.Ar port#
---on the system running the name server instead of BIND 9's
---default control channel port of 953.
---.Pp
---The
---.Fl y
---option identifies the
---.Ar key_id
---to use from the configuration file.
---.Ar key_id
---must be known by
---.Xr named
---with the same algorithm and secret string in order for
---control message validation to succeed.
---If no
---.Fl y
---option is provided,
---.Nm rndc
---will first look for a
---.Dv key
---clause in the
---.Dv server
---statement of the server being used, or if no
---.Dv server
---statement is present for that host, then the
---.Dv default-key
---clause of the
---.Dv options
---statement.
---Note that the configuration file for
---.Nm rdnc
---contains shared secrets which are used to send authenticated
---control commands to name servers.
---It should therefore not have general read or write access.
---.Pp
---The
---.Fl M ,
---.Fl m ,
---and
---.Fl v
---options provided debugging information and are primarily of interest
---only to the BIND 9 developers.
---They might be changed or removed in future releases.
---.Pp
---For the complete set of commands supported by rndc, see the
---BIND 9 Administrator Reference Manual or run
---.Nm rndc
---without arguments to see its help message.
---.Pp
---.Sh LIMITATIONS
---.Nm rndc
---does not yet support all the commands of the BIND 8
---.Xr ndc
---utility.
---.Pp
---There is currently no way to provide the shared secret for a key_id
---without using the configuration file.
---.Pp
---Several error messages could be clearer.
---For example, trying to connect
---from an address that is not in the list of acceptable addresses
---configured into
---.Xr named
---will result in the error message "end of file" when the server
---unceremoniously closes the connection.
---.Sh SEE ALSO
---.Xr rndc.conf 5 ,
---.Xr named 8 ,
---.Xr named.conf 5 ,
---.Xr RFC2845 ,
---.Xr ndc 8 .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: rndc.conf.5,v 1.8 2000/11/30 00:20:40 gson Exp $
---
---.Dd Jun 30, 2000
---.Dt RDNC.CONF 5
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm rdnc.conf
---.Nd rdnc configuration file
---.Sh SYNOPSIS
---.Nm rdnc.conf
---.Sh DESCRIPTION
---The BIND9 utility for controlling the name server,
---.Nm rndc ,
---has its own configuration file
---.Pa /etc/rndc.conf .
---This file has a similar structure and syntax to
---.Pa named.conf ,
---the file used to configure the name server.
---Statements are enclosed in braces and terminated with a semi-colon.
---Clauses in the statements are also semi-colon terminated.
---The usual comment styles are supported:
---.Bl -tag -width UNIX-style:
---.It C style: /* */
---.It C++ style: // to end of line
---.It Unix style: # to end of line
---.El
---.Pp
---.Pa rndc.conf
---is much simpler than
---.Pa named.conf .
---The file uses three statements: an
---.Dv options
---statement, a
---.Dv server
---statement and a
---.Dv key
---statement.
---.Pp
---The
---.Dv options
---statement contains two clauses.
---The
---.Dv default-server
---clause
---is followed by the name or address of a name server.
---This host will
---be used when no name server is given as an argument to
---.Nm rndc .
---The
---.Dv default-key
---clause
---is followed by the name of a key which is identified by a
---.Dv key
---statement.
---If no
---.Fl y
---option is provided on the
---.Xr rndc
---command line, and no
---.Dv key
---clause is found in a a matching
---.Dv server
---statement, this default key will be used to authenticate the server's
---commands and responses.
---.Pp
---After the keyword
---.Dv server ,
---the
---.Dv server
---statement is followed by a string which is the hostname or address for a
---name server.
---The statement has a single clause,
---.Dv key .
---The key name must match the name of a
---.Dv key
---statement in the file.
---.Pp
---The
---.Dv key
---statement begins with an identifying string, the name of the key.
---The statement has two clauses.
---.Dv algorithm
---identifies the encryption algorithm for
---.Nm rndc
---to use; currently only HMAC-MD5 is supported.
---This is followed by a
---.Dv secret
---clause which contains the base-64 encoding of the
---algorithm's encryption key.
---The base-64 string is enclosed in double quotes.
---.Pp
---There are two common ways to generate the base-64 string for the
---.Dv secret .
---The BIND 9 program
---.Xr dnssec-keygen 8
---can be used to generate a random key, or the
---.Xr mmencode 1
---program, also known as
---.Xr mimencode 1 ,
---can be used to generate a base-64 string from known input.
---.Xr mmencode
---does not ship with BIND 9 but is available on many systems.
---See the
---.Sx EXAMPLES
---section for sample command lines for each.
---.Pp
---Host and key names must be quoted using double quotes if they
---match a keyword, such as having a key named "key".
---.Sh EXAMPLE
---.Bd -literal indent
---options {
--- default-server localhost;
--- default-key samplekey;
---};
---
---server localhost {
--- key samplekey;
---};
---
---key samplekey {
--- algorithm hmac-md5;
--- secret "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
---};
---.Ed
---.Pp
---In the above example,
---.Nm rndc
---will by default use the server at localhost (127.0.0.1) and the key called
---.Dv samplekey .
---Commands to the localhost server will use the
---.Dv samplekey
---key.
---The
---.Dv key
---statement indicates that
---.Dv samplekey
---uses the HMAC-MD5 algorithm and its
---.Dv secret
---clause contains the base-64 encoding of the HMAC-MD5 secret enclosed
---in double quotes.
---.Pp
---To generate a random secret with
---.Xr dnssec-keygen :
---.Bd -literal indent
---$ dnssec-keygen -a hmac-md5 -b 128 -n user rndc
---.Ed
---.Pp
---The base-64 string will appear in two files,
---.Pa Krndc.+157.+{random}.key
---and
---.Pa Krndc.+157.+{random}.private .
---After extracting the key to be
---placed in the
---.Nm rndc.conf
---and
---.Xr named.conf
---.Dv key
---statements, the
---.Pa .key
---and
---.Pa .private
---files can be removed.
---.Pp
---To generate a secret from known input with
---.Xr mmenode :
---.Bd -literal indent
---$ echo "known plaintext for a secret" | mmencode
---.Ed
---.Sh LIMITATIONS
---There is currently no way to specify the port for
---.Xr rndc
---to use. This will be remedied in future releases by allowing a
---.Dv port
---clause to the
---.Dv server
---statement and a
---.Dv default-port
---clause to the
---.Dv options
---statement.
---.Sh SEE ALSO
---.Xr rndc 8 ,
---.Xr named.conf 8 ,
---.Xr dnssec-keygen 8 ,
---.Xr mmencode 1 ,
---"BIND9 Administrators Manual".
+++ /dev/null
---/*
--- * Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
--- * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
--- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
--- * INTERNET SOFTWARE CONSORTIUM 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: dirdb.c,v 1.5 2000/11/20 19:49:59 bwelling Exp $ */
---
---#include <config.h>
---
---#include <stdio.h>
---#include <string.h>
---#include <unistd.h>
---#include <sys/stat.h>
---#include <sys/sysmacros.h>
---
---#include <isc/mem.h>
---#include <isc/print.h>
---#include <isc/result.h>
---#include <isc/util.h>
---
---#include <dns/sdb.h>
---
---#include <named/globals.h>
---
---/*
--- * A simple database driver that returns basic directory information.
--- */
---
---static dns_sdbimplementation_t *dirdb = NULL;
---
---#define CHECK(op) \
--- do { result = (op); \
--- if (result != ISC_R_SUCCESS) return (result); \
--- } while (0)
---
---#define CHECKN(op) \
--- do { n = (op); \
--- if (n < 0) return (ISC_R_FAILURE); \
--- } while (0)
---
---
---/*
--- * This database operates on relative names.
--- *
--- * Any name will be interpreted as a pathname offset from the directory
--- * specified in the configuration file.
--- */
---static isc_result_t
---dirdb_lookup(const char *zone, const char *name, void *dbdata,
--- dns_sdblookup_t *lookup)
---{
--- char filename[255];
--- char filename2[255];
--- char buf[1024];
--- struct stat statbuf;
--- isc_result_t result;
--- int n;
---
--- UNUSED(zone);
--- UNUSED(dbdata);
---
--- if (strcmp(name, "@") == 0)
--- snprintf(filename, sizeof(filename), "%s", (char *)dbdata);
--- else
--- snprintf(filename, sizeof(filename), "%s/%s",
--- (char *)dbdata, name);
--- CHECKN(lstat(filename, &statbuf));
---
--- if (S_ISDIR(statbuf.st_mode))
--- CHECK(dns_sdb_putrr(lookup, "txt", 3600, "dir"));
--- else if (S_ISCHR(statbuf.st_mode) || S_ISBLK(statbuf.st_mode)) {
--- CHECKN(snprintf(buf, sizeof(buf),
--- "\"%sdev\" \"major %d\" \"minor %d\"",
--- S_ISCHR(statbuf.st_mode) ? "chr" : "blk",
--- major(statbuf.st_rdev),
--- minor(statbuf.st_rdev)));
--- CHECK(dns_sdb_putrr(lookup, "txt", 3600, buf));
--- } else if (S_ISFIFO(statbuf.st_mode))
--- CHECK(dns_sdb_putrr(lookup, "txt", 3600, "pipe"));
--- else if (S_ISSOCK(statbuf.st_mode))
--- CHECK(dns_sdb_putrr(lookup, "txt", 3600, "socket"));
--- else if (S_ISLNK(statbuf.st_mode)) {
--- CHECKN(readlink(filename, filename2, sizeof(filename2) - 1));
--- buf[n] = 0;
--- CHECKN(snprintf(buf, sizeof(buf), "\"symlink\" \"%s\"",
--- filename2));
--- CHECK(dns_sdb_putrr(lookup, "txt", 3600, buf));
--- } else if (!S_ISREG(statbuf.st_mode))
--- CHECK(dns_sdb_putrr(lookup, "txt", 3600, "unknown"));
--- else {
--- CHECKN(snprintf(buf, sizeof(buf), "\"file\" \"size = %u\"",
--- (unsigned int)statbuf.st_size));
--- CHECK(dns_sdb_putrr(lookup, "txt", 3600, buf));
--- }
---
--- return (ISC_R_SUCCESS);
---}
---
---/*
--- * lookup () does not return SOA or NS records, so authority() must be defined.
--- */
---static isc_result_t
---dirdb_authority(const char *zone, void *dbdata, dns_sdblookup_t *lookup) {
--- isc_result_t result;
---
--- UNUSED(zone);
--- UNUSED(dbdata);
---
--- result = dns_sdb_putsoa(lookup, "ns", "hostmaster", 0);
--- INSIST(result == ISC_R_SUCCESS);
--- result = dns_sdb_putrr(lookup, "ns", 86400, "ns1");
--- INSIST(result == ISC_R_SUCCESS);
--- result = dns_sdb_putrr(lookup, "ns", 86400, "ns2");
--- INSIST(result == ISC_R_SUCCESS);
--- return (ISC_R_SUCCESS);
---}
---
---/*
--- * Each database stores the top-level directory as the dbdata opaque
--- * object. The create() function allocates it. argv[0] holds the top
--- * level directory.
--- */
---static isc_result_t
---dirdb_create(const char *zone, int argc, char **argv,
--- void *driverdata, void **dbdata)
---{
--- UNUSED(zone);
--- UNUSED(driverdata);
---
--- if (argc < 1)
--- return (ISC_R_FAILURE);
--- *dbdata = isc_mem_strdup((isc_mem_t *)driverdata, argv[0]);
--- if (*dbdata == NULL)
--- return (ISC_R_NOMEMORY);
--- return (ISC_R_SUCCESS);
---}
---
---/*
--- * The destroy() function frees the memory allocated by create().
--- */
---static void
---dirdb_destroy(const char *zone, void *driverdata, void **dbdata) {
--- UNUSED(zone);
--- UNUSED(driverdata);
--- isc_mem_free((isc_mem_t *)driverdata, *dbdata);
---}
---
---/*
--- * This zone does not support zone transfer, so allnodes() is NULL.
--- */
---static dns_sdbmethods_t dirdb_methods = {
--- dirdb_lookup,
--- dirdb_authority,
--- NULL, /* allnodes */
--- dirdb_create,
--- dirdb_destroy
---};
---
---/*
--- * Wrapper around dns_sdb_register(). Note that the first ns_g_mctx is
--- * being passed as the "driverdata" parameter, so that will it will be
--- * passed to create() and destroy().
--- */
---isc_result_t
---dirdb_init(void) {
--- unsigned int flags;
--- flags = DNS_SDBFLAG_RELATIVEOWNER | DNS_SDBFLAG_RELATIVERDATA;
--- return (dns_sdb_register("dir", &dirdb_methods, ns_g_mctx, flags,
--- ns_g_mctx, &dirdb));
---}
---
---/*
--- * Wrapper around dns_sdb_unregister().
--- */
---void
---dirdb_clear(void) {
--- if (dirdb != NULL)
--- dns_sdb_unregister(&dirdb);
---}
+++ /dev/null
---/*
--- * Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
--- * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
--- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
--- * INTERNET SOFTWARE CONSORTIUM 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: dirdb.h,v 1.1 2000/11/18 01:29:11 bwelling Exp $ */
---
---#include <isc/types.h>
---
---isc_result_t dirdb_init(void);
---
---void dirdb_clear(void);
---
+++ /dev/null
---/*
--- * Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
--- * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
--- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
--- * INTERNET SOFTWARE CONSORTIUM 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: pgsqldb.c,v 1.9 2000/11/22 21:18:12 bwelling Exp $ */
---
---#include <config.h>
---
---#include <stdio.h>
---#include <string.h>
---#include <stdlib.h>
---
---#include <pgsql/libpq-fe.h>
---
---#include <isc/mem.h>
---#include <isc/print.h>
---#include <isc/result.h>
---#include <isc/util.h>
---
---#include <dns/sdb.h>
---#include <dns/result.h>
---
---#include <named/globals.h>
---
---/*
--- * A simple database driver that interfaces to a PostgreSQL database. This
--- * is not complete, and not designed for general use. It opens one
--- * connection to the database per zone, which is inefficient. It also may
--- * not support multiple threads and probably doesn't handle quoting correctly.
--- *
--- * The table must contain the fields "name", "rdtype", and "rdata", and
--- * is expected to contain a properly constructed zone. The program "zonetodb"
--- * creates such a table.
--- */
---
---static dns_sdbimplementation_t *pgsqldb = NULL;
---
---struct dbinfo {
--- PGconn *conn;
--- char *table;
---};
---
---/*
--- * Canonicalize a string before writing it to the database.
--- * "dest" must be an array of at least size 2*strlen(source) + 1.
--- */
---static void
---quotestring(const char *source, char *dest) {
--- while (*source != 0) {
--- if (*source == '\'')
--- *dest++ = '\'';
--- /* SQL doesn't treat \ as special, but PostgreSQL does */
--- else if (*source == '\\')
--- *dest++ = '\\';
--- *dest++ = *source++;
--- }
--- *dest++ = 0;
---}
---
---/*
--- * This database operates on absolute names.
--- *
--- * Queries are converted into SQL queries and issued synchronously. Errors
--- * are handled really badly.
--- */
---static isc_result_t
---pgsqldb_lookup(const char *zone, const char *name, void *dbdata,
--- dns_sdblookup_t *lookup)
---{
--- isc_result_t result;
--- struct dbinfo *dbi = dbdata;
--- PGresult *res;
--- char str[1500];
--- char *canonname;
--- int i;
---
--- UNUSED(zone);
---
--- canonname = isc_mem_get(ns_g_mctx, strlen(name) * 2 + 1);
--- if (canonname == NULL)
--- return (ISC_R_NOMEMORY);
--- quotestring(name, canonname);
--- snprintf(str, sizeof(str),
--- "SELECT TTL,RDTYPE,RDATA FROM \"%s\" WHERE "
--- "lower(NAME) = lower('%s')", dbi->table, canonname);
--- isc_mem_put(ns_g_mctx, canonname, strlen(name) * 2 + 1);
--- res = PQexec(dbi->conn, str);
--- if (!res || PQresultStatus(res) != PGRES_TUPLES_OK) {
--- PQclear(res);
--- return (ISC_R_FAILURE);
--- }
--- if (PQntuples(res) == 0) {
--- PQclear(res);
--- return (ISC_R_NOTFOUND);
--- }
---
--- for (i = 0; i < PQntuples(res); i++) {
--- char *ttlstr = PQgetvalue(res, i, 0);
--- char *type = PQgetvalue(res, i, 1);
--- char *data = PQgetvalue(res, i, 2);
--- dns_ttl_t ttl;
--- char *endp;
--- ttl = strtol(ttlstr, &endp, 10);
--- if (*endp != '\0') {
--- PQclear(res);
--- return (DNS_R_BADTTL);
--- }
--- result = dns_sdb_putrr(lookup, type, ttl, data);
--- if (result != ISC_R_SUCCESS) {
--- PQclear(res);
--- return (ISC_R_FAILURE);
--- }
--- }
---
--- PQclear(res);
--- return (ISC_R_SUCCESS);
---}
---
---/*
--- * Issue an SQL query to return all nodes in the database and fill the
--- * allnodes structure.
--- */
---static isc_result_t
---pgsqldb_allnodes(const char *zone, void *dbdata, dns_sdballnodes_t *allnodes) {
--- struct dbinfo *dbi = dbdata;
--- PGresult *res;
--- isc_result_t result;
--- char str[1500];
--- int i;
---
--- UNUSED(zone);
---
--- snprintf(str, sizeof(str),
--- "SELECT TTL,NAME,RDTYPE,RDATA FROM \"%s\" ORDER BY NAME",
--- dbi->table);
--- res = PQexec(dbi->conn, str);
--- if (!res || PQresultStatus(res) != PGRES_TUPLES_OK ) {
--- PQclear(res);
--- return (ISC_R_FAILURE);
--- }
--- if (PQntuples(res) == 0) {
--- PQclear(res);
--- return (ISC_R_NOTFOUND);
--- }
---
--- for (i = 0; i < PQntuples(res); i++) {
--- char *ttlstr = PQgetvalue(res, i, 0);
--- char *name = PQgetvalue(res, i, 1);
--- char *type = PQgetvalue(res, i, 2);
--- char *data = PQgetvalue(res, i, 3);
--- dns_ttl_t ttl;
--- char *endp;
--- ttl = strtol(ttlstr, &endp, 10);
--- if (*endp != '\0') {
--- PQclear(res);
--- return (DNS_R_BADTTL);
--- }
--- result = dns_sdb_putnamedrr(allnodes, name, type, ttl, data);
--- if (result != ISC_R_SUCCESS) {
--- PQclear(res);
--- return (ISC_R_FAILURE);
--- }
--- }
---
--- PQclear(res);
--- return (ISC_R_SUCCESS);
---}
---
---/*
--- * Create a connection to the database and save a copy of the table name.
--- * Save these in dbdata. argv[0] is the name of the database and
--- * argv[1] is the name of the table.
--- */
---static isc_result_t
---pgsqldb_create(const char *zone, int argc, char **argv,
--- void *driverdata, void **dbdata)
---{
--- struct dbinfo *dbi;
---
--- UNUSED(zone);
--- UNUSED(driverdata);
---
--- if (argc < 2)
--- return (ISC_R_FAILURE);
---
--- dbi = isc_mem_get(ns_g_mctx, sizeof(struct dbinfo));
--- if (dbi == NULL)
--- return (ISC_R_NOMEMORY);
--- dbi->table = isc_mem_strdup(ns_g_mctx, argv[1]);
--- if (dbi->table == NULL) {
--- isc_mem_put(ns_g_mctx, dbi, sizeof(struct dbinfo));
--- return (ISC_R_NOMEMORY);
--- }
---
--- dbi->conn = PQsetdb(NULL, NULL, NULL, NULL, argv[0]);
--- if (PQstatus(dbi->conn) == CONNECTION_BAD) {
--- PQfinish(dbi->conn);
--- isc_mem_free(ns_g_mctx, dbi->table);
--- isc_mem_put(ns_g_mctx, dbi, sizeof(struct dbinfo));
--- return (ISC_R_FAILURE);
--- }
---
--- *dbdata = dbi;
--- return (ISC_R_SUCCESS);
---}
---
---/*
--- * Close the connection to the database.
--- */
---static void
---pgsqldb_destroy(const char *zone, void *driverdata, void **dbdata) {
--- struct dbinfo *dbi = *dbdata;
---
--- UNUSED(zone);
--- UNUSED(driverdata);
---
--- PQfinish(dbi->conn);
--- isc_mem_free(ns_g_mctx, dbi->table);
--- isc_mem_put(ns_g_mctx, dbi, sizeof(struct dbinfo));
---}
---
---/*
--- * Since the SQL database corresponds to a zone, the authority data should
--- * be returned by the lookup() function. Therefore the authority() function
--- * is NULL.
--- */
---static dns_sdbmethods_t pgsqldb_methods = {
--- pgsqldb_lookup,
--- NULL, /* authority */
--- pgsqldb_allnodes,
--- pgsqldb_create,
--- pgsqldb_destroy
---};
---
---/*
--- * Wrapper around dns_sdb_register().
--- */
---isc_result_t
---pgsqldb_init(void) {
--- unsigned int flags;
--- flags = 0;
--- return (dns_sdb_register("pgsql", &pgsqldb_methods, NULL, flags,
--- ns_g_mctx, &pgsqldb));
---}
---
---/*
--- * Wrapper around dns_sdb_unregister().
--- */
---void
---pgsqldb_clear(void) {
--- if (pgsqldb != NULL)
--- dns_sdb_unregister(&pgsqldb);
---}
+++ /dev/null
---/*
--- * Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
--- * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
--- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
--- * INTERNET SOFTWARE CONSORTIUM 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: pgsqldb.h,v 1.1 2000/11/18 01:29:12 bwelling Exp $ */
---
---#include <isc/types.h>
---
---isc_result_t pgsqldb_init(void);
---
---void pgsqldb_clear(void);
---
+++ /dev/null
---/*
--- * Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
--- * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
--- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
--- * INTERNET SOFTWARE CONSORTIUM 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: zonetodb.c,v 1.7 2000/11/20 19:56:12 bwelling Exp $ */
---
---#include <isc/buffer.h>
---#include <isc/mem.h>
---#include <isc/print.h>
---#include <isc/result.h>
---
---#include <dns/db.h>
---#include <dns/dbiterator.h>
---#include <dns/fixedname.h>
---#include <dns/name.h>
---#include <dns/rdata.h>
---#include <dns/rdataset.h>
---#include <dns/rdatasetiter.h>
---#include <dns/result.h>
---
---#include <pgsql/libpq-fe.h>
---
---/*
--- * Generate a PostgreSQL table from a zone.
--- *
--- * This is compiled this with something like the following (assuming bind9 has
--- * been installed):
--- *
--- * gcc -g `isc-config.sh --cflags isc dns` -c zonetodb.c
--- * gcc -g -o zonetodb zonetodb.o `isc-config.sh --libs isc dns` -lpq
--- */
---
---PGconn *conn = NULL;
---char *dbname, *dbtable;
---char str[10240];
---
---void
---closeandexit(int status) {
--- if (conn != NULL)
--- PQfinish(conn);
--- exit(status);
---}
---
---void
---check_result(isc_result_t result, const char *message) {
--- if (result != ISC_R_SUCCESS) {
--- fprintf(stderr, "%s: %s\n", message,
--- isc_result_totext(result));
--- closeandexit(1);
--- }
---}
---
---/*
--- * Canonicalize a string before writing it to the database.
--- * "dest" must be an array of at least size 2*strlen(source) + 1.
--- */
---static void
---quotestring(const char *source, char *dest) {
--- while (*source != 0) {
--- if (*source == '\'')
--- *dest++ = '\'';
--- else if (*source == '\\')
--- *dest++ = '\\';
--- *dest++ = *source++;
--- }
--- *dest++ = 0;
---}
---
---void
---addrdata(dns_name_t *name, dns_ttl_t ttl, dns_rdata_t *rdata) {
--- unsigned char namearray[DNS_NAME_MAXTEXT + 1];
--- unsigned char canonnamearray[2 * DNS_NAME_MAXTEXT + 1];
--- unsigned char typearray[20];
--- unsigned char canontypearray[40];
--- unsigned char dataarray[2048];
--- unsigned char canondataarray[4096];
--- isc_buffer_t b;
--- isc_result_t result;
--- PGresult *res;
---
--- isc_buffer_init(&b, namearray, sizeof(namearray) - 1);
--- result = dns_name_totext(name, ISC_TRUE, &b);
--- check_result(result, "dns_name_totext");
--- namearray[isc_buffer_usedlength(&b)] = 0;
--- quotestring(namearray, canonnamearray);
---
--- isc_buffer_init(&b, typearray, sizeof(typearray) - 1);
--- result = dns_rdatatype_totext(rdata->type, &b);
--- check_result(result, "dns_rdatatype_totext");
--- typearray[isc_buffer_usedlength(&b)] = 0;
--- quotestring(typearray, canontypearray);
---
--- isc_buffer_init(&b, dataarray, sizeof(dataarray) - 1);
--- result = dns_rdata_totext(rdata, NULL, &b);
--- check_result(result, "dns_rdata_totext");
--- dataarray[isc_buffer_usedlength(&b)] = 0;
--- quotestring(dataarray, canondataarray);
---
--- snprintf(str, sizeof(str),
--- "INSERT INTO %s (NAME, TTL, RDTYPE, RDATA)"
--- " VALUES ('%s', %d, '%s', '%s')",
--- dbtable, canonnamearray, ttl, canontypearray, canondataarray);
--- printf("%s\n", str);
--- res = PQexec(conn, str);
--- if (!res || PQresultStatus(res) != PGRES_COMMAND_OK) {
--- fprintf(stderr, "INSERT INTO command failed: %s\n",
--- PQresultErrorMessage(res));
--- PQclear(res);
--- closeandexit(1);
--- }
--- PQclear(res);
---}
---
---int
---main(int argc, char **argv) {
--- char *porigin, *zonefile;
--- dns_fixedname_t forigin, fname;
--- dns_name_t *origin, *name;
--- dns_db_t *db = NULL;
--- dns_dbiterator_t *dbiter;
--- dns_dbnode_t *node;
--- dns_rdatasetiter_t *rdsiter;
--- dns_rdataset_t rdataset;
--- dns_rdata_t rdata;
--- isc_mem_t *mctx = NULL;
--- isc_buffer_t b;
--- isc_result_t result;
--- PGresult *res;
---
--- if (argc != 5) {
--- printf("usage: %s origin file dbname dbtable\n", argv[0]);
--- printf("Note that dbname must be an existing database.\n");
--- exit(1);
--- }
---
--- porigin = argv[1];
--- zonefile = argv[2];
--- dbname = argv[3];
--- dbtable = argv[4];
---
--- mctx = NULL;
--- result = isc_mem_create(0, 0, &mctx);
--- check_result(result, "isc_mem_create");
---
--- isc_buffer_init(&b, porigin, strlen(porigin));
--- isc_buffer_add(&b, strlen(porigin));
--- dns_fixedname_init(&forigin);
--- origin = dns_fixedname_name(&forigin);
--- result = dns_name_fromtext(origin, &b, dns_rootname, ISC_FALSE, NULL);
--- check_result(result, "dns_name_fromtext");
---
--- db = NULL;
--- result = dns_db_create(mctx, "rbt", origin, dns_dbtype_zone,
--- dns_rdataclass_in, 0, NULL, &db);
--- check_result(result, "dns_db_create");
---
--- result = dns_db_load(db, zonefile);
--- check_result(result, "dns_db_load");
---
--- printf("Connecting to '%s'\n", dbname);
--- conn = PQsetdb(NULL, NULL, NULL, NULL, dbname);
--- if (PQstatus(conn) == CONNECTION_BAD) {
--- fprintf(stderr, "Connection to database '%s' failed: %s\n",
--- dbname, PQerrorMessage(conn));
--- closeandexit(1);
--- }
---
--- snprintf(str, sizeof(str),
--- "DROP TABLE %s", dbtable);
--- printf("%s\n", str);
--- res = PQexec(conn, str);
--- if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
--- fprintf(stderr, "DROP TABLE command failed: %s\n",
--- PQresultErrorMessage(res));
--- PQclear(res);
---
--- snprintf(str, sizeof(str), "BEGIN");
--- printf("%s\n", str);
--- res = PQexec(conn, str);
--- if (!res || PQresultStatus(res) != PGRES_COMMAND_OK) {
--- fprintf(stderr, "BEGIN command failed: %s\n",
--- PQresultErrorMessage(res));
--- PQclear(res);
--- closeandexit(1);
--- }
--- PQclear(res);
---
--- snprintf(str, sizeof(str),
--- "CREATE TABLE %s "
--- "(NAME TEXT, TTL INTEGER, RDTYPE TEXT, RDATA TEXT)",
--- dbtable);
--- printf("%s\n", str);
--- res = PQexec(conn, str);
--- if (!res || PQresultStatus(res) != PGRES_COMMAND_OK) {
--- fprintf(stderr, "CREATE TABLE command failed: %s\n",
--- PQresultErrorMessage(res));
--- PQclear(res);
--- closeandexit(1);
--- }
--- PQclear(res);
---
--- dbiter = NULL;
--- result = dns_db_createiterator(db, ISC_FALSE, &dbiter);
--- check_result(result, "dns_db_createiterator()");
---
--- result = dns_dbiterator_first(dbiter);
--- check_result(result, "dns_dbiterator_first");
---
--- dns_fixedname_init(&fname);
--- name = dns_fixedname_name(&fname);
--- dns_rdataset_init(&rdataset);
--- dns_rdata_init(&rdata);
---
--- while (result == ISC_R_SUCCESS) {
--- node = NULL;
--- result = dns_dbiterator_current(dbiter, &node, name);
--- if (result == ISC_R_NOMORE)
--- break;
--- check_result(result, "dns_dbiterator_current");
---
--- rdsiter = NULL;
--- result = dns_db_allrdatasets(db, node, NULL, 0, &rdsiter);
--- check_result(result, "dns_db_allrdatasets");
---
--- result = dns_rdatasetiter_first(rdsiter);
--- check_result(result, "dns_rdatasetiter_first");
---
--- while (result == ISC_R_SUCCESS) {
--- dns_rdatasetiter_current(rdsiter, &rdataset);
--- result = dns_rdataset_first(&rdataset);
--- check_result(result, "dns_rdataset_first");
--- while (result == ISC_R_SUCCESS) {
--- dns_rdataset_current(&rdataset, &rdata);
--- addrdata(name, rdataset.ttl, &rdata);
--- dns_rdata_reset(&rdata);
--- result = dns_rdataset_next(&rdataset);
--- }
--- dns_rdataset_disassociate(&rdataset);
--- result = dns_rdatasetiter_next(rdsiter);
--- }
--- dns_rdatasetiter_destroy(&rdsiter);
--- dns_db_detachnode(db, &node);
--- result = dns_dbiterator_next(dbiter);
--- }
---
--- snprintf(str, sizeof(str), "COMMIT TRANSACTION");
--- printf("%s\n", str);
--- res = PQexec(conn, str);
--- if (!res || PQresultStatus(res) != PGRES_COMMAND_OK) {
--- fprintf(stderr, "COMMIT command failed: %s\n",
--- PQresultErrorMessage(res));
--- PQclear(res);
--- closeandexit(1);
--- }
--- PQclear(res);
--- dns_dbiterator_destroy(&dbiter);
--- dns_db_detach(&db);
--- isc_mem_destroy(&mctx);
--- closeandexit(0);
---}
+++ /dev/null
---# Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---# DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---# INTERNET SOFTWARE CONSORTIUM 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: lookup.tcl,v 1.5 2000/11/18 01:35:05 gson Exp $
---
---#
---# Sample lookup procedure for tcldb
---#
---
---proc lookup {zone name} {
--- global dbargs
--- switch -- $name {
--- @ { return [list \
--- {SOA 86400 "ns1.isp.nil. hostmaster.isp.nil. \
--- 0 3600 1800 1814400 3600"} \
--- {NS 86400 "ns1.isp.nil."} \
--- {NS 86400 "ns2.isp.nil."} \
--- {MX 86400 "10 mail.isp.nil."} ] }
--- www { return [list [list A 3600 $dbargs($zone)] ] }
--- }
--- return NXDOMAIN
---}
+++ /dev/null
---/*
--- * Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
--- * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
--- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
--- * INTERNET SOFTWARE CONSORTIUM 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: tcldb.c,v 1.5 2000/11/20 18:24:41 gson Exp $ */
---
---#include <config.h>
---
---#include <string.h>
---#include <stdlib.h>
---#include <unistd.h>
---#include <sys/stat.h>
---
---#include <isc/mem.h>
---#include <isc/print.h>
---#include <isc/result.h>
---#include <isc/util.h>
---
---#include <dns/log.h>
---#include <dns/sdb.h>
---
---#include <named/globals.h>
---
---#include <tcl.h>
---
---#include <tcldb.h>
---
---/*
--- * A simple database driver that calls Tcl procedures to define
--- * the contents of the DNS namespace.
--- */
---
---#define CHECK(op) \
--- do { result = (op); \
--- if (result != ISC_R_SUCCESS) return (result); \
--- } while (0)
---
---typedef struct tcldb_driver {
--- isc_mem_t *mctx;
--- Tcl_Interp *interp;
---} tcldb_driver_t;
---
---static tcldb_driver_t *the_driver = NULL;
---
---static dns_sdbimplementation_t *tcldb = NULL;
---
---static isc_result_t
---tcldb_driver_create(isc_mem_t *mctx, tcldb_driver_t **driverp) {
--- int tclres;
--- isc_result_t result = ISC_R_SUCCESS;
--- tcldb_driver_t *driver = isc_mem_get(mctx, sizeof(tcldb_driver_t));
--- if (driver == NULL)
--- return (ISC_R_NOMEMORY);
--- driver->mctx = mctx;
--- driver->interp = Tcl_CreateInterp();
---
--- tclres = Tcl_EvalFile(driver->interp, (char *) "lookup.tcl");
--- if (tclres != TCL_OK) {
--- isc_log_write(dns_lctx, DNS_LOGCATEGORY_GENERAL,
--- DNS_LOGMODULE_SDB, ISC_LOG_ERROR,
--- "initializing tcldb: "
--- "loading 'lookup.tcl' failed: %s",
--- driver->interp->result);
--- result = ISC_R_FAILURE;
--- goto cleanup;
--- }
--- *driverp = driver;
--- return (ISC_R_SUCCESS);
---
--- cleanup:
--- isc_mem_put(mctx, driver, sizeof(tcldb_driver_t));
--- return (result);
---
---}
---
---static void
---tcldb_driver_destroy(tcldb_driver_t **driverp) {
--- tcldb_driver_t *driver = *driverp;
--- Tcl_DeleteInterp(driver->interp);
--- isc_mem_put(driver->mctx, driver, sizeof(tcldb_driver_t));
---}
---
---/*
--- * Perform a lookup, by invoking the Tcl procedure "lookup".
--- */
---static isc_result_t
---tcldb_lookup(const char *zone, const char *name, void *dbdata,
--- dns_sdblookup_t *lookup)
---{
--- isc_result_t result = ISC_R_SUCCESS;
--- int tclres;
--- int rrc; /* RR count */
--- char **rrv; /* RR vector */
--- int i;
--- char *cmdv[3];
--- char *cmd;
---
--- tcldb_driver_t *driver = (tcldb_driver_t *) dbdata;
---
--- cmdv[0] = "lookup";
--- cmdv[1] = zone;
--- cmdv[2] = name;
--- cmd = Tcl_Merge(3, cmdv);
--- tclres = Tcl_Eval(driver->interp, cmd);
--- Tcl_Free(cmd);
---
--- if (tclres != TCL_OK) {
--- isc_log_write(dns_lctx, DNS_LOGCATEGORY_GENERAL,
--- DNS_LOGMODULE_SDB, ISC_LOG_ERROR,
--- "zone '%s': tcl lookup function failed: %s",
--- zone, driver->interp->result);
--- return (ISC_R_FAILURE);
--- }
---
--- if (strcmp(driver->interp->result, "NXDOMAIN") == 0) {
--- result = ISC_R_NOTFOUND;
--- goto fail;
--- }
---
--- tclres = Tcl_SplitList(driver->interp, driver->interp->result,
--- &rrc, &rrv);
--- if (tclres != TCL_OK)
--- goto malformed;
---
--- for (i = 0; i < rrc; i++) {
--- isc_result_t tmpres;
--- int fieldc; /* Field count */
--- char **fieldv; /* Field vector */
--- tclres = Tcl_SplitList(driver->interp, rrv[i],
--- &fieldc, &fieldv);
--- if (tclres != TCL_OK) {
--- tmpres = ISC_R_FAILURE;
--- goto failrr;
--- }
--- if (fieldc != 3)
--- goto malformed;
--- tmpres = dns_sdb_putrr(lookup, fieldv[0], atoi(fieldv[1]),
--- fieldv[2]);
--- Tcl_Free((char *) fieldv);
--- failrr:
--- if (tmpres != ISC_R_SUCCESS)
--- result = tmpres;
--- }
--- Tcl_Free((char *) rrv);
--- if (result == ISC_R_SUCCESS)
--- return (result);
---
--- malformed:
--- isc_log_write(dns_lctx, DNS_LOGCATEGORY_GENERAL,
--- DNS_LOGMODULE_SDB, ISC_LOG_ERROR,
--- "zone '%s': "
--- "malformed return value from tcl lookup function: %s",
--- zone, driver->interp->result);
--- result = ISC_R_FAILURE;
--- fail:
--- return (result);
---}
---
---/*
--- * Set up per-zone state. In our case, the database arguments of the
--- * zone are collected into a Tcl list and assigned to an element of
--- * the global array "dbargs".
--- */
---static isc_result_t
---tcldb_create(const char *zone, int argc, char **argv,
--- void *driverdata, void **dbdata)
---{
--- tcldb_driver_t *driver = (tcldb_driver_t *) driverdata;
---
--- char *list = Tcl_Merge(argc, argv);
---
--- Tcl_SetVar2(driver->interp, (char *) "dbargs", (char *) zone, list, 0);
---
--- Tcl_Free(list);
---
--- *dbdata = driverdata;
---
--- return (ISC_R_SUCCESS);
---}
---
---/*
--- * This driver does not support zone transfer, so allnodes() is NULL.
--- */
---static dns_sdbmethods_t tcldb_methods = {
--- tcldb_lookup,
--- NULL, /* authority */
--- NULL, /* allnodes */
--- tcldb_create,
--- NULL /* destroy */
---};
---
---/*
--- * Initialize the tcldb driver.
--- */
---isc_result_t
---tcldb_init(void) {
--- isc_result_t result;
--- int flags = DNS_SDBFLAG_RELATIVEOWNER | DNS_SDBFLAG_RELATIVERDATA;
---
--- result = tcldb_driver_create(ns_g_mctx, &the_driver);
--- if (result != ISC_R_SUCCESS)
--- return (result);
---
--- return (dns_sdb_register("tcl", &tcldb_methods, the_driver, flags,
--- ns_g_mctx, &tcldb));
---}
---
---/*
--- * Wrapper around dns_sdb_unregister().
--- */
---void
---tcldb_clear(void) {
--- if (tcldb != NULL)
--- dns_sdb_unregister(&tcldb);
--- if (the_driver != NULL)
--- tcldb_driver_destroy(&the_driver);
---}
+++ /dev/null
---/*
--- * Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
--- * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
--- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
--- * INTERNET SOFTWARE CONSORTIUM 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: tcldb.h,v 1.3 2000/11/18 01:29:12 bwelling Exp $ */
---
---#include <isc/types.h>
---
---isc_result_t tcldb_init(void);
---
---void tcldb_clear(void);
---
+++ /dev/null
---/*
--- * Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
--- * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
--- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
--- * INTERNET SOFTWARE CONSORTIUM 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: timedb.c,v 1.4 2000/11/20 19:50:02 bwelling Exp $ */
---
---#include <config.h>
---
---#include <string.h>
---#include <stdio.h>
---#include <time.h>
---
---#include <isc/print.h>
---#include <isc/result.h>
---#include <isc/util.h>
---
---#include <dns/sdb.h>
---
---#include <named/globals.h>
---
---/*
--- * A simple database driver that enables the server to return the
--- * current time in a DNS record.
--- */
---
---static dns_sdbimplementation_t *timedb = NULL;
---
---/*
--- * This database operates on relative names.
--- *
--- * "time" and "@" return the time in a TXT record.
--- * "clock" is a CNAME to "time"
--- * "current" is a DNAME to "@" (try time.current.time)
--- */
---static isc_result_t
---timedb_lookup(const char *zone, const char *name, void *dbdata,
--- dns_sdblookup_t *lookup)
---{
--- isc_result_t result;
---
--- UNUSED(zone);
--- UNUSED(dbdata);
---
--- if (strcmp(name, "@") == 0 || strcmp(name, "time") == 0) {
--- time_t now = time(NULL);
--- char buf[100];
--- int n;
---
--- /*
--- * Call ctime to create the string, put it in quotes, and
--- * remove the trailing newline.
--- */
--- n = snprintf(buf, sizeof(buf), "\"%s", ctime(&now));
--- if (n < 0)
--- return (ISC_R_FAILURE);
--- buf[n - 1] = '\"';
--- result = dns_sdb_putrr(lookup, "txt", 1, buf);
--- if (result != ISC_R_SUCCESS)
--- return (ISC_R_FAILURE);
--- } else if (strcmp(name, "clock") == 0) {
--- result = dns_sdb_putrr(lookup, "cname", 1, "time");
--- if (result != ISC_R_SUCCESS)
--- return (ISC_R_FAILURE);
--- } else if (strcmp(name, "current") == 0) {
--- result = dns_sdb_putrr(lookup, "dname", 1, "@");
--- if (result != ISC_R_SUCCESS)
--- return (ISC_R_FAILURE);
--- } else
--- return (ISC_R_NOTFOUND);
---
--- return (ISC_R_SUCCESS);
---}
---
---/*
--- * lookup() does not return SOA or NS records, so authority() must be defined.
--- */
---static isc_result_t
---timedb_authority(const char *zone, void *dbdata, dns_sdblookup_t *lookup) {
--- isc_result_t result;
---
--- UNUSED(zone);
--- UNUSED(dbdata);
---
--- result = dns_sdb_putsoa(lookup, "localhost.", "root.localhost.", 0);
--- if (result != ISC_R_SUCCESS)
--- return (ISC_R_FAILURE);
---
--- result = dns_sdb_putrr(lookup, "ns", 86400, "ns1.localdomain.");
--- if (result != ISC_R_SUCCESS)
--- return (ISC_R_FAILURE);
--- result = dns_sdb_putrr(lookup, "ns", 86400, "ns2.localdomain.");
--- if (result != ISC_R_SUCCESS)
--- return (ISC_R_FAILURE);
---
--- return (ISC_R_SUCCESS);
---}
---
---/*
--- * This zone does not support zone transfer, so allnodes() is NULL. There
--- * is no database specific data, so create() and destroy() are NULL.
--- */
---static dns_sdbmethods_t timedb_methods = {
--- timedb_lookup,
--- timedb_authority,
--- NULL, /* allnodes */
--- NULL, /* create */
--- NULL /* destroy */
---};
---
---/*
--- * Wrapper around dns_sdb_register().
--- */
---isc_result_t
---timedb_init(void) {
--- unsigned int flags;
--- flags = DNS_SDBFLAG_RELATIVEOWNER | DNS_SDBFLAG_RELATIVERDATA;
--- return (dns_sdb_register("time", &timedb_methods, NULL, flags,
--- ns_g_mctx, &timedb));
---}
---
---/*
--- * Wrapper around dns_sdb_unregister().
--- */
---void
---timedb_clear(void) {
--- if (timedb != NULL)
--- dns_sdb_unregister(&timedb);
---}
+++ /dev/null
---/*
--- * Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
--- * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
--- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
--- * INTERNET SOFTWARE CONSORTIUM 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: timedb.h,v 1.1 2000/11/18 01:29:14 bwelling Exp $ */
---
---#include <isc/types.h>
---
---isc_result_t timedb_init(void);
---
---void timedb_clear(void);
---
+++ /dev/null
---Copyright (C) 2000 Internet Software Consortium.
---See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
---
---Notes on CVS Usage
---
---Accessing the repository
---
---
---The recommended way of accessing the BIND 9 CVS repository is by ssh
---to rc.isc.org, using the following environment settings:
---
--- CVSROOT=:ext:rc.isc.org:/proj/cvs/isc
--- CVS_RSH=ssh
---
---
---Creating a release branch
---
---
---Here's how the 9.0 release branch was created:
---
--- cvs rtag v9_0_base bind9
--- cvs rtag -b -r v9_0_base v9_0 bind9
---
---
---
---Renaming files by respository copy
---
---
---When you need to rename or move a file that is under CVS control, use
---the "repository copy" method as described in the following text
---borrowed from an ancient CVS FAQ:
---
--- 2C.4 How do I rename a file?
---
--- CVS does not offer a way to rename a file in a way that CVS can
--- track later. See Section 4B for more information.
---
--- Here is the best way to get the effect of renaming, while
--- preserving the change log:
---
--- 1. Copy the RCS (",v") file directly in the Repository.
---
--- cp $CVSROOT/<odir>/<ofile>,v $CVSROOT/<ndir>/<nfile>,v
---
--- 2. Remove the old file using CVS.
---
--- By duplicating the file, you will preserve the change
--- history and the ability to retrieve earlier revisions of the
--- old file via the "-r <tag/rev>" or "-D <date>" options to
--- "checkout" and "update".
---
--- cd <working-dir>/<odir>
--- rm <ofile>
--- cvs remove <ofile>
--- cvs commit <ofile>
---
--- 3. Retrieve <newfile> and remove all the Tags from it.
---
--- By stripping off all the old Tags, the "checkout -r" and
--- "update -r" commands won't retrieve revisions Tagged before
--- the renaming.
---
--- cd <working-dir>/<ndir>
--- cvs update <nfile>
--- cvs log <nfile> # Save the list of Tags
--- cvs tag -d <tag1> <nfile>
--- cvs tag -d <tag2> <nfile>
--- . . .
---
---
--- This technique can be used to rename files within one directory or
--- across different directories. You can apply this idea to
--- directories too, as long as you apply the above to each file and
--- don't delete the old directory.
---
--- Of course, you have to change the build system (e.g. Makefile) in
--- your <working-dir> to know about the name change.
---
---
---Pulling up a newly added file to a release branch:
---
---In a mainline working tree, do something like this:
---
--- cvs tag v9_0_base file
--- cvs tag -b -r v9_0_base v9_0 file
---
---
---$Id: cvs-usage,v 1.5 2000/08/09 04:37:32 tale Exp $
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: resolver.5,v 1.2 2000/11/18 02:57:31 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt RESOLVER 5
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm resolver
---.Nd resolver configuration file
---.Sh SYNOPSIS
---.Pa /etc/resolv.conf
---.Sh DESCRIPTION
---The
---.Nm resolver
---and
---.Nm "BIND9 lightwreight resolver"
---are sets of routines in the C library and BIND9 library respectively
---that provide access to the Internet Domain Name System.
---The resolver configuration file,
---.Pa /etc/resolv.conf ,
---is normally gets read
---by the resolver and lightweight resolver
---routines to initialise low-level resolver data structures the first time
---that a process invokes those routines.
---The file contains a list of
---keywords with values that provide various types of
---information, such as the IP addresses of the servers that should be
---used when making lookup requests.
---.Pp
---Each keyword and value must appear on a single line.
---The value follows the keyword, separated by white space.
---The hash character '#' or semi-colon ';' introduce comments.
---Anything from either of these characters to the end of the line
---is treated as a comment and ignored.
---.\" XXXJR - Don't think the next para is relevant. Not every host will run
---.\" a name server or lightweight resolver. Those that don't will need
---.\" a resolv.conf so they can send their lookups somewhere sensible.
---.\".Pp
---.\"On a normally configured system, this file should not be necessary.
---.\"The only name server to be queried will be on the local machine,
---.\"the domain name is determined from the host name,
---.\"and the domain search path is constructed from the domain name.
---.Pp
---The available configuration directives are:
---.Bl -tag -width "nameserver"
---.It Li nameserver
---Internet address of a name server that the resolver should query.
---The IP address of the server can be supplied in the usual notation:
---either in dotted-decimal form for an IPv4 addess or in double colon
---form described in RFC1884 for an IPv6 address.
---Up to three nameserver directives can be listed.
---See
---.Dv LWRES_CONFMAXNAMESERVERS
---in
---.Pa <lwres/lwres.h> .
---If more than
---.Dv LWRES_CONFMAXNAMESERVERS
---nameserver directives are present in the file,
---only the first three are used.
---Any others are ignored.
---.Pp
---When there are multiple servers, the resolver
---library queries them in the order listed.
---If no
---.Li nameserver
---entries are present, the default is to attempt to use the name server or
---lightweight resolver daemon on the local machine.
---The algorithm used is to try a server, and if the query times out,
---try the next, until out of name servers,
---then repeat trying all the name servers
---until a maximum number of retries are made.
---.It Li domain
---Local domain name.
---Most queries for names within this domain can use short names
---relative to the local domain.
---When no
---.Li domain
---entry is present, the domain is determined from the local host name returned by
---.Xr gethostname 2 ;
---the domain part is taken to be everything after the first
---.Sq \&. .
---Finally, if the host name does not contain a domain part, the root
---domain is assumed.
---.It Li search
---Search list for host-name lookup.
---The search list is normally determined from the local domain name;
---by default, it contains only the local domain name.
---This may be changed by listing the desired domain search path
---following the
---.Li search
---keyword with spaces or tabs separating the names.
---Most resolver
---queries will be attempted using each component
---of the search path in turn until a match is found.
---Note that this process may be slow and will generate a lot of network
---traffic if the servers for the listed domains are not local,
---and that queries will time out if no server is available
---for one of the domains.
---.Pp
---The search list is currently limited to eight domains
---with a total of 256 characters.
---See
---.Dv LWRES_CONFMAXSEARCH
---and
---.Dv LWRES_CONFMAXLINELEN
---in
---.Pa lwres/lwres.h .
---.It Li sortlist
---Allows addresses returned by gethostbyname to be sorted.
---A
---.Li sortlist
---is specified by IP address netmask pairs.
---The netmask is optional and defaults to the natural netmask of the net.
---The IP address and optional network pairs are separated by slashes.
---Up to 10 pairs may be specified.
---For example:
---.Bd -literal -offset indent
---sortlist 130.155.160.0/255.255.240.0 130.155.0.0
---.Ed
---.It Li options
---Allows certain internal
---.Nm resolver
---variables to be modified.
---The syntax is
---.D1 Li options Ar option ...
---where
---.Ar option
---is one of the following:
---.Bl -tag -width "no_tld_query"
---.It Li ndots: Ns Ar n
---sets a threshold for the number of dots which
---must appear in a name given to
---.Fn res_query
---(see
---.Xr resolver 3 )
---before an
---.Em initial absolute query
---will be made.
---The default for
---.Ar n
---is
---.Dq 1 ,
---meaning that if there are
---.Em any
---dots in a name, the name will be tried first as an absolute name before any
---.Em search list
---elements are appended to it.
---Acceptable values of
---.Ar n
---are between 0 and 255 inclusive.
---.It debug
---enables debugging traces for the resolver
---XXXJR if anything actually looked at
---.Dv confdata->resdebug .
---At present the option is just recognised but not used by
---the BIND9 implementation.
---.It no_tld_query
---tells the resolver not to attempt to resolve a
---top level domain name, i.e. a name containing no dots.
---Use of this option does not prevent the resolver from obeying the
---standard
---.Ar domain
---and
---.Ar search
---rules with the given name.
---XXXJR At present this option is recognised but is otherwise unused
---in BIND9.
---.It missing
---XXXJR what about the other BIND8 resolver options like rotate and
---timeout? Shouldn't these be provided for backwards compatibility?
---.El
---.El
---.Pp
---The
---.Li domain
---and
---.Li search
---keywords are mutually exclusive.
---If more than one instance of these keywords is present,
---the last instance wins.
---.Sh FILES
---.Pa /etc/resolv.conf
---.Pa <lwres/lwres.h>
---.Sh SEE ALSO
---.Xr gethostbyname 3 ,
---.Xr lwres_config 3 ,
---.Xr lwres 3 ,
---.Xr resolver 3 ,
---.Xr hostname 7 ,
---.Xr lwresd 8 ,
---.Xr named 8 ,
---"BIND9 Administrators Manual".
---.Sh BUGS
---Unrecognised directives and syntax errors in
---.Pa /etc/resolv.conf
---are usually silently ignored, though
---.Er LWRES_R_FAILURE
---can be returned by the lightweight resolver functions described in
---.Xr lwres_config 3
---which parse this file.
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres.3,v 1.8 2000/12/04 18:37:35 gson Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres
---.Nd introduction to the lightweight resolver library
---.Sh SYNOPSIS
---.Fd #include <lwres/lwres.h>
---.Sh DESCRIPTION
---The BIND 9 lightweight resolver library is a simple, name service
---independent stub resolver library. It provides hostname-to-address
---and address-to-hostname lookup services to applications by
---transmitting lookup requests to a resolver daemon
---.Nm lwresd
---running on the local host. The resover daemon performs the
---lookup using the DNS or possibly other name service protocols,
---and returns the results to the application through the library.
---The library and resolver daemon communicate using a simple
---UDP-based protocol.
---.Pp
---.Sh OVERVIEW
---The lwresd library implements multiple name service APIs.
---The standard
---.Fn gethostbyname ,
---.Fn gethostbyaddr ,
---.Fn gethostbyname_r ,
---.Fn gethostbyaddr_r ,
---.Fn getaddrinfo ,
---.Fn getipnodebyname ,
---and
---.Fn getipnodebyaddr
---functions are all supported. To allow the lwres library to coexist
---with system libraries that define functions of the same name,
---the library defines these functions with names prefixed by
---.Va lwres_ .
---To define the standard names, applications must include the
---header file
---.Fd <lwres/netdb.h>
---which contains macro definitions mapping the standard function names
---into
---.Va lwres_
---prefixed ones. Operating system vendors who integrate the lwres
---library into their base distributions should rename the functions
---in the library proper so that the renaming macros are not needed.
---.Pp
---The library also provides a native API consisting of the functions
---.Fn lwres_getaddrsbyname
---and
---.Fn lwres_getnamebyaddr .
---These may be called by applications that require more detailed
---control over the lookup process than the standard functions
---provide.
---.Pp
---In addition to these name service independent address lookup
---functions, the library implements a new, experimental API
---for looking up arbitrary DNS resource records, using the
---.Fn lwres_getaddrsbyname
---function.
---.Pp
---Finally, there is a low-level API for converting lookup
---requests and responses to and from raw lwres protocol packets.
---This API can be used by clients requiring nonblocking operation,
---and is also used when implementing the server side of the lwres
---protocol, for example in the
---.Nm lwresd
---resolver daemon. The use of this low-level API in clients
---and servers is outlined in the following sections.
---.P
---.Sh CLIENT-SIDE LOW-LEVEL API CALL FLOW
---When a client program wishes to make an lwres request using the
---native low-level API, it typically performs the following
---sequence of actions.
---.Pp
---(1) Allocate or use an existing lwres_packet_t, called "pkt" below.
---.Pp
---(2) Set pkt.recvlength to the maximum length we will accept.
---This is done so the receiver of our packets knows how large our receive
---buffer is. The "default" is a constant in lwres.h: LWRES_RECVLENGTH = 4096.
---.Pp
---(3) Set the pkt.serial to a unique serial number. This value is echoed
---back to the application by the remote server.
---.Pp
---(4) Set pkt.pktflags. Usually this is set to 0.
---.Pp
---(5) Set pkt.result to 0.
---.Pp
---(6) Call lwres_*request_render, or marshall in the data using the primitives
---such as lwres_packet_render() and storing the packet data.
---.Pp
---(7) Transmit the resulting buffer.
---.Pp
---(8) Call lwres_*response_parse() to parse any packets received.
---.Pp
---(9) Verify that the opcode and serial match a request, and process the
---packet specific information contained in the body.
---.Sh SERVER-SIDE LOW-LEVEL API CALL FLOW
---When implementing the server side of the lightweight resolver
---protocol using the lwres library, a sequence of actions like the
---following is typically involved in processing each request packet.
---.Pp
---Note that the same lwres_packet_t is used
---in both the _parse() and _render() calls, with only a few modifications made
---to the packet header's contents between uses. This method is recommended
---as it keeps the serial, opcode, and other fields correct.
---.Pp
---(1) When a packet is received, call lwres_*request_parse() to
---unmarshall it. This returns a lwres_packet_t (also called pkt, below)
---as well as a data specific type, such as lwres_gabnrequest_t.
---.Pp
---(2) Process the request in the data specific type.
---.Pp
---(3) Set the pkt.result, pkt.recvlength as above. All other fields can
---be left untouched since they were filled in by the *_parse() call
---above. If using lwres_*response_render(), pkt.pktflags will be set up
---properly. Otherwise, the LWRES_LWPACKETFLAG_RESPONSE bit should be
---set.
---.Pp
---(4) Call the data specific rendering function, such as
---lwres_gabnresponse_render().
---.Pp
---(5) Send the resulting packet to the client.
---.Pp
---.Sh SEE ALSO
---.Xr lwres_gethostent 3 ,
---.Xr lwres_getipnode 3 ,
---.Xr lwres_getnameinfo 3 ,
---.Xr lwres_noop 3 ,
---.Xr lwres_gabn 3 ,
---.Xr lwres_gnba 3 ,
---.Xr lwres_context 3 ,
---.Xr lwres_config 3 ,
---.Xr resolver 5 ,
---.Xr lwresd 8 .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_addr_parse.3,v 1.4 2000/11/18 02:59:13 bwelling Exp $
---
---.so lwres_resutil.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer.3,v 1.5 2000/11/18 02:59:15 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_BUFFER 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_buffer_init ,
---.Nm lwres_buffer_invalidate ,
---.Nm lwres_buffer_add ,
---.Nm lwres_buffer_subtract ,
---.Nm lwres_buffer_clear ,
---.Nm lwres_buffer_first ,
---.Nm lwres_buffer_forward ,
---.Nm lwres_buffer_back ,
---.Nm lwres_buffer_getuint8 ,
---.Nm lwres_buffer_putuint8 ,
---.Nm lwres_buffer_getuint16 ,
---.Nm lwres_buffer_putuint16 ,
---.Nm lwres_buffer_getuint32 ,
---.Nm lwres_buffer_putuint32 ,
---.Nm lwres_buffer_putmem ,
---.Nm lwres_buffer_getmem
---.Nd lightweight resolver buffer management
---.Sh SYNOPSIS
---.Fd #include <lwres/lwbuffer.h>
---.Fd
---.Ft void
---.Fo lwres_buffer_init
---.Fa "lwres_buffer_t *b"
---.Fa "void *base"
---.Fa "unsigned int length"
---.Fc
---.Ft void
---.Fo lwres_buffer_invalidate
---.Fa "lwres_buffer_t *b"
---.Fc
---.Ft void
---.Fo lwres_buffer_add
---.Fa "lwres_buffer_t *b"
---.Fa "unsigned int n"
---.Fc
---.Ft void
---.Fo lwres_buffer_subtract
---.Fa "lwres_buffer_t *b"
---.Fa "unsigned int n"
---.Fc
---.Ft void
---.Fo lwres_buffer_clear
---.Fa "lwres_buffer_t *b"
---.Fc
---.Ft void
---.Fo lwres_buffer_first
---.Fa "lwres_buffer_t *b"
---.Fc
---.Ft void
---.Fo lwres_buffer_forward
---.Fa "lwres_buffer_t *b"
---.Fa "unsigned int n"
---.Fc
---.Ft void
---.Fo lwres_buffer_back
---.Fa "lwres_buffer_t *b"
---.Fa "unsigned int n"
---.Fc
---.Ft lwres_uint8_t
---.Fo lwres_buffer_getuint8
---.Fa "lwres_buffer_t *b"
---.Fc
---.Ft void
---.Fo lwres_buffer_putuint8
---.Fa "lwres_buffer_t *b"
---.Fa "lwres_uint8_t val"
---.Fc
---.Ft lwres_uint16_t
---.Fo lwres_buffer_getuint16
---.Fa "lwres_buffer_t *b"
---.Fc
---.Ft void
---.Fo lwres_buffer_putuint16
---.Fa "lwres_buffer_t *b"
---.Fa "lwres_uint16_t val"
---.Fc
---.Ft lwres_uint32_t
---.Fo lwres_buffer_getuint32
---.Fa "lwres_buffer_t *b"
---.Fc
---.Ft void
---.Fo lwres_buffer_putuint32
---.Fa "lwres_buffer_t *b"
---.Fa "lwres_uint32_t val"
---.Fc
---.Ft void
---.Fo lwres_buffer_putmem
---.Fa "lwres_buffer_t *b"
---.Fa "const unsigned char *base"
---.Fa "unsigned int length"
---.Fc
---.Ft void
---.Fo lwres_buffer_getmem
---.Fa "lwres_buffer_t *b"
---.Fa "unsigned char *base"
---.Fa "unsigned int length"
---.Fc
---.Sh DESCRIPTION
---
---
---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
---.Va isc_buffer_
---functions in the ISC library.
---.Pp
---A buffer is a region of memory, together with a set of related
---subregions.
---The \*qused region\*q and the \*qavailable\*q 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.
---.Pp
---The used region is further subdivided into two disjoint regions: the
---\*qconsumed region\*q and the \*qremaining region\*q.
---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 \*qcurrent\*q offset (if any).
---The \*qremaining\*q 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.
---.Pp
---The \*qactive region\*q 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.
---.Pp
---.Bd -literal -offset indent
---
--- /------------entire length---------------\\
--- /----- used region -----\\/-- available --\\
--- +----------------------------------------+
--- | consumed | remaining | |
--- +----------------------------------------+
--- a b c d e
---
--- a == base of buffer.
--- b == current pointer. Can be anywhere between a and d.
--- c == active pointer. Meaningful between b and d.
--- d == used pointer.
--- e == length of buffer.
---
--- a-e == entire length of buffer.
--- a-d == used region.
--- a-b == consumed region.
--- b-d == remaining region.
--- b-c == optional active region.
---.Ed
---.Pp
---.Fn lwres_buffer_init
---initializes the
---.Dv lwres_buffer_t
---.Fa *b
---and assocates it with the memory region of size
---.Fa length
---bytes starting at location
---.Fa base.
---.Pp
---.Fn lwres_buffer_invalidate
---marks the buffer
---.Fa *b
---as invalid. Invalidating a buffer after use is not required,
---but makes it possible to catch its possible accidental use.
---.Pp
---The functions
---.Fn lwres_buffer_add
---and
---.Fn lwres_buffer_subtract
---respectively increase and decrease the used space in
---buffer
---.Fa *b
---by
---.Fa n
---bytes.
---.Fn lwres_buffer_add
---checks for buffer overflow and
---.Fn lwres_buffer_subtract
---checks for underflow.
---These functions do not allocate or deallocate memory.
---They just change the value of
---.Li used .
---.Pp
---A buffer is re-initialised by
---.Fn lwres_buffer_clear .
---The function sets
---.Li used ,
---.Li current
---and
---.Li active
---to zero.
---.Pp
---.Fn lwres_buffer_first
---makes the consumed region of buffer
---.Fa *p
---empty by setting
---.Li current
---to zero (the start of the buffer).
---.Pp
---.Fn lwres_buffer_forward
---increases the consumed region of buffer
---.Fa *b
---by
---.Fa n
---bytes, checking for overflow.
---Similarly,
---.Fn lwres_buffer_back
---decreases buffer
---.Fa b 's
---consumed region by
---.Fa n
---bytes and checks for underflow.
---.Pp
---.Fn lwres_buffer_getuint8
---reads an unsigned 8-bit integer from
---.Fa *b
---and returns it.
---.Fn lwres_buffer_putuint8
---writes the unsigned 8-bit integer
---.Fa val
---to buffer
---.Fa *b .
---.Pp
---.Fn lwres_buffer_getuint16
---and
---.Fn lwres_buffer_getuint32
---are identical to
---.Fn lwres_buffer_putuint8
---except that they respectively read an unsigned 16-bit or 32-bit integer
---in network byte order from
---.Fa b .
---Similarly,
---.Fn lwres_buffer_putuint16
---and
---.Fn lwres_buffer_putuint32
---writes the unsigned 16-bit or 32-bit integer
---.Fa val
---to buffer
---.Fa b ,
---in network byte order.
---.Pp
---Arbitrary amounts of data are read or written from a lightweight
---resolver buffer with
---.Fn lwres_buffer_getmem
---and
---.Fn lwres_buffer_putmem
---respectively.
---.Fn lwres_buffer_putmem
---copies
---.Fa length
---bytes of memory at
---.Fa base
---to
---.Fa b.
---Conversely,
---.Fn lwres_buffer_getmem
---copies
---.Fa length
---bytes of memory from
---.Fa b
---to
---.Fa base .
---.Sh SEE ALSO
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_add.3,v 1.4 2000/11/18 02:59:16 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_back.3,v 1.4 2000/11/18 02:59:17 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_clear.3,v 1.4 2000/11/18 02:59:18 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_first.3,v 1.4 2000/11/18 02:59:19 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_forward.3,v 1.4 2000/11/18 02:59:20 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_getmem.3,v 1.4 2000/11/18 02:59:21 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_getuint16.3,v 1.4 2000/11/18 02:59:22 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_getuint32.3,v 1.4 2000/11/18 02:59:24 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_getuint8.3,v 1.4 2000/11/18 02:59:25 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_init.3,v 1.4 2000/11/18 02:59:26 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_invalidate.3,v 1.4 2000/11/18 02:59:28 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_putmem.3,v 1.4 2000/11/18 02:59:29 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_putuint16.3,v 1.4 2000/11/18 02:59:30 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_putuint32.3,v 1.4 2000/11/18 02:59:31 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_putuint8.3,v 1.4 2000/11/18 02:59:32 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_buffer_subtract.3,v 1.4 2000/11/18 02:59:33 bwelling Exp $
---
---.so lwres_buffer.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_conf_clear.3,v 1.4 2000/11/18 02:59:34 bwelling Exp $
---
---.so lwres_config.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_conf_get.3,v 1.4 2000/11/18 02:59:35 bwelling Exp $
---
---.so lwres_config.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_conf_init.3,v 1.4 2000/11/18 02:59:37 bwelling Exp $
---
---.so lwres_config.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_conf_parse.3,v 1.4 2000/11/18 02:59:38 bwelling Exp $
---
---.so lwres_config.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_conf_print.3,v 1.4 2000/11/18 02:59:39 bwelling Exp $
---
---.so lwres_config.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_config.3,v 1.5 2000/12/04 18:37:37 gson Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_CONFIG 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_conf_init ,
---.Nm lwres_conf_clear ,
---.Nm lwres_conf_parse ,
---.Nm lwres_conf_print ,
---.Nm lwres_conf_get
---.Nd lightweight resolver configuration
---.Sh SYNOPSIS
---.Fd #include <lwres/lwres.h>
---.Fd
---.Ft void
---.Fo lwres_conf_init
---.Fa "lwres_context_t *ctx"
---.Fc
---.Ft void
---.Fo lwres_conf_clear
---.Fa "lwres_context_t *ctx"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_conf_parse
---.Fa "lwres_context_t *ctx"
---.Fa "const char *filename"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_conf_print
---.Fa "lwres_context_t *ctx"
---.Fa "FILE *fp"
---.Fc
---.Ft lwres_conf_t *
---.Fo lwres_conf_get
---.Fa "lwres_context_t *ctx"
---.Fc
---.Sh DESCRIPTION
---.Fn lwres_conf_init
---creates an empty
---.Dv lwres_conf_t
---structure for lightweight resolver context
---.Fa ctx .
---.Pp
---.Fn lwres_conf_clear
---frees up all the internal memory used by
---that
---.Dv lwres_conf_t
---structure in resolver context
---.Fa ctx .
---.Pp
---.Fn lwres_conf_parse
---opens the file
---.Fa filename
---and parses it to initialise the resolver context
---.Fa ctx 's
---.Dv lwres_conf_t
---structure.
---.Pp
---.Fn lwres_conf_print
---prints the
---.Dv lwres_conf_t
---structure for resolver context
---.Fa ctx
---to the
---.Dv FILE
---.Fa fp.
---.Sh RETURN VALUES
---.Fn lwres_conf_parse
---returns
---.Er LWRES_R_SUCCESS
---if it successfully read and parsed
---.Fa filename .
---It returns
---.Er LWRES_R_FAILURE
---if
---.Fa filename
---could not be opened or contained incorrect
---resolver statements.
---.Pp
---.Fn lwres_conf_print
---returns
---.Er LWRES_R_SUCCESS
---unless an error occurred when converting the network addresses to a
---numeric host address string.
---If this happens, the function returns
---.Er LWRES_R_FAILURE .
---.Sh SEE ALSO
---.Xr stdio 3 ,
---.Xr resolver 5 .
---.Sh FILES
---.Pa /etc/resolv.conf
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_context.3,v 1.5 2000/11/18 02:59:42 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_CONTEXT 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_context_create ,
---.Nm lwres_context_destroy ,
---.Nm lwres_context_nextserial ,
---.Nm lwres_context_initserial ,
---.Nm lwres_context_freemem ,
---.Nm lwres_context_allocmem ,
---.Nm lwres_context_sendrecv
---.Nd lightweight resolver context management
---.Sh SYNOPSIS
---.Fd #include <lwres/lwres.h>
---.Fd
---.Ft lwres_result_t
---.Fo lwres_context_create
---.Fa "lwres_context_t **contextp"
---.Fa "void *arg"
---.Fa "lwres_malloc_t malloc_function"
---.Fa "lwres_free_t free_function"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_context_destroy
---.Fa "lwres_context_t **contextp"
---.Fc
---.Ft void
---.Fo lwres_context_initserial
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_uint32_t serial"
---.Fc
---.Ft lwres_uint32_t
---.Fo lwres_context_nextserial
---.Fa "lwres_context_t *ctx"
---.Fc
---.Ft void
---.Fo lwres_context_freemem
---.Fa "lwres_context_t *ctx"
---.Fa "void *mem"
---.Fa "size_t len"
---.Fc
---.Ft void
---.Fo lwres_context_allocmem
---.Fa "lwres_context_t *ctx"
---.Fa "size_t len"
---.Fc
---.Ft void *
---.Fo lwres_context_sendrecv
---.Fa "lwres_context_t *ctx"
---.Fa "void *sendbase"
---.Fa "int sendlen"
---.Fa "void *recvbase"
---.Fa "int recvlen"
---.Fa "int *recvd_len"
---.Fc
---.Sh DESCRIPTION
---.Fn lwres_context_create
---creates a
---.Dv lwres_context_t
---structure for use in lightweight resolver operations.
---It holds a socket and other data needed for communicating
---with a resolver daemon.
---The new
---.Dv lwres_context_t
---is returned throught
---.Fa contextp ,
---a pointer to a
---.Dv "lwres_context_t"
---pointer. This
---.Dv "lwres_context_t"
---pointer must initially be NULL, and is modified
---to point to the newly created
---.Dv "lwres_context_t" .
---.Pp
---When the lightweight resolver needs to perform dynamic memory
---allocation, it will call
---.Fa malloc_function
---to allocate memory and
---.Fa free_function
---to free it. If
---.Fa malloc_function
---and
---.Fa free_function
---are NULL, memory is allocated using
---.Xr malloc 3
---and
---.Xr free 3 .
---It is not permitted to have a NULL
---.Fa malloc_function
---and a non-NULL
---.Fa free_function
---or vice versa.
---.Fa arg
---is passed as the first parameter to the memory
---allocation functions.
---If
---.Fa malloc_function
---and
---.Fa free_function
---are NULL,
---.Fa arg
---is unused and should be passed as NULL.
---.P
---Once memory for the structure has been allocated,
---it is initialized using
---.Xr lwres_conf_init 3
---and returned via
---.Fa *contextp .
---.Pp
---.Fn lwres_context_destroy
---destroys a
---.Dv "lwres_context_t" ,
---closing its socket.
---.Fa contextp
---is a pointer to a pointer to the context that is to be destroyed.
---The pointer will be set to NULL when the context has been destroyed.
---.Pp
---The context holds a serial number that is used to identify resolver
---request packets and associate responses with the corresponding requests.
---This serial number is controlled using
---.Fn lwres_context_initserial
---and
---.Fn lwres_context_nextserial .
---.Fn lwres_context_initserial
---sets the serial number for context
---.Fa *ctx
---to
---.Fa serial .
---.Fn lwres_context_nextserial
---increments the serial number and returns the previous value.
---.Pp
---Memory for a lightweight resolver context is allocated and freed using
---.Fn lwres_context_allocmem
---and
---.Fn lwres_context_freemem .
---These use whatever allocations were defined when the context was
---created with
---.Fn lwres_context_create .
---.Fn lwres_context_allocmem
---allocates
---.Fa len
---bytes of memory and if successful returns a pointer to the allocated
---storage.
---.Fn lwres_context_allocmem
---checks that
---.Fa len
---must be greater than 0.
---.Fn lwres_context_freemem
---frees
---.Fa len
---bytes of space starting at location
---.Fa mem .
---.Pp
---.Fn lwres_context_sendrecv
---performs I/O for the context
---.Fa ctx .
---Data are read and written from the context's socket.
---It writes data from
---.Fa sendbase
---- typically a lightweight resolver query packet -
---and waits for a reply which is copied to the receive buffer at
---.Fa recvbase .
---The number of bytes that were written to this receive buffer is
---returned in
---.Fa *recvd_len .
---.Sh RETURN VALUES
---.Fn lwres_context_create
---returns
---.Er LWRES_R_NOMEMORY
---if memory for the
---.Dv "struct lwres_context"
---could not be allocated,
---.Er LWRES_R_SUCCESS
---otherwise.
---.Pp
---Successful calls to the memory allocator
---.Fn lwres_context_allocmem
---return a pointer to the start of the allocated space.
---It returns NULL if memory could not be allocated.
---.Pp
---.Er LWRES_R_SUCCESS
---is returned when
---.Fn lwres_context_sendrecv
---completes successfully.
---.Er LWRES_R_IOERROR
---is returned if an I/O error occurs and
---.Er LWRES_R_TIMEOUT
---is returned if
---.Fn lwres_context_sendrecv
---times out waiting for a response.
---.Sh SEE ALSO
---.Xr lwres_conf_init 3 ,
---.Xr malloc 3 ,
---.Xr free 3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_context_allocmem.3,v 1.4 2000/11/18 02:59:43 bwelling Exp $
---
---.so lwres_context.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_context_create.3,v 1.4 2000/11/18 02:59:44 bwelling Exp $
---
---.so lwres_context.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_context_destroy.3,v 1.4 2000/11/18 02:59:45 bwelling Exp $
---
---.so lwres_context.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_context_freemem.3,v 1.4 2000/11/18 02:59:46 bwelling Exp $
---
---.so lwres_context.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_context_initserial.3,v 1.4 2000/11/18 02:59:47 bwelling Exp $
---
---.so lwres_context.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_context_nextserial.3,v 1.4 2000/11/18 02:59:48 bwelling Exp $
---
---.so lwres_context.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_context_sendrecv.3,v 1.4 2000/11/18 02:59:49 bwelling Exp $
---
---.so lwres_context.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_endhostent.3,v 1.4 2000/11/18 02:59:51 bwelling Exp $
---
---.so lwres_gethostent.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_endhostent_r.3,v 1.4 2000/11/18 02:59:52 bwelling Exp $
---
---.so lwres_gethostent.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_freeaddrinfo.3,v 1.4 2000/11/18 02:59:54 bwelling Exp $
---
---.so lwres_getaddrinfo.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_freehostent.3,v 1.4 2000/11/18 02:59:55 bwelling Exp $
---
---.so lwres_getipnode.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gabn.3,v 1.5 2000/11/18 02:59:56 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_GABN 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_gabnrequest_render ,
---.Nm lwres_gabnresponse_render ,
---.Nm lwres_gabnrequest_parse ,
---.Nm lwres_gabnresponse_parse ,
---.Nm lwres_gabnresponse_free ,
---.Nm lwres_gabnrequest_free
---.Nd lightweight resolver getaddrbyname message handling
---.Sh SYNOPSIS
---.Fd #include <lwres/lwres.h>
---.Fd
---.Ft lwres_result_t
---.Fo lwres_gabnrequest_render
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_gabnrequest_t *req"
---.Fa "lwres_lwpacket_t *pkt"
---.Fa "lwres_buffer_t *b"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_gabnresponse_render
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_gabnresponse_t *req"
---.Fa "lwres_lwpacket_t *pkt"
---.Fa "lwres_buffer_t *b"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_gabnrequest_parse
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_buffer_t *b"
---.Fa "lwres_lwpacket_t *pkt"
---.Fa "lwres_gabnrequest_t **structp"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_gabnresponse_parse
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_buffer_t *b"
---.Fa "lwres_lwpacket_t *pkt"
---.Fa "lwres_gabnresponse_t **structp"
---.Fc
---.Ft void
---.Fo lwres_gabnresponse_free
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_gabnresponse_t **structp"
---.Fc
---.Ft void
---.Fo lwres_gabnrequest_free
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_gabnrequest_t **structp"
---.Fc
---.Sh DESCRIPTION
---These are low-level routines for creating and parsing
---lightweight resolver name-to-address lookup request and
---response messages.
---.P
---There are four main functions for the getaddrbyname opcode.
---One render function converts a getaddrbyname request structure -
---.Dv lwres_gabnrequest_t -
---to the lighweight resolver's canonical format.
---It is complemented by a parse function that converts a packet in this
---canonical format to a getaddrbyname request structure.
---Another render function converts the getaddrbyname response structure -
---.Dv lwres_gabnresponse_t
---to the canonical format.
---This is complemented by a parse function which converts a packet in
---canonical format to a getaddrbyname response structure.
---.Pp
---These structures are defined in
---.Pa <lwres/lwres.h> .
---They are shown below.
---.Bd -literal -offset indent
---#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
---
---typedef struct lwres_addr lwres_addr_t;
---typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
---
---typedef struct {
--- lwres_uint32_t flags;
--- lwres_uint32_t addrtypes;
--- lwres_uint16_t namelen;
--- char *name;
---} lwres_gabnrequest_t;
---
---typedef struct {
--- lwres_uint32_t flags;
--- lwres_uint16_t naliases;
--- lwres_uint16_t naddrs;
--- char *realname;
--- char **aliases;
--- lwres_uint16_t realnamelen;
--- lwres_uint16_t *aliaslen;
--- lwres_addrlist_t addrs;
--- void *base;
--- size_t baselen;
---} lwres_gabnresponse_t;
---.Ed
---.Pp
---.Fn lwres_gabnrequest_render
---uses resolver context
---.Fa ctx
---to convert getaddrbyname request structure
---.Fa req
---to canonical format.
---The packet header structure
---.Fa pkt
---is initialised and transferred to
---buffer
---.Fa b .
---The contents of
---.Fa *req
---are then appended to the buffer in canonical format.
---.Fn lwres_gabnresponse_render
---performs the same task, except it converts a getaddrbyname response structure
---.Dv lwres_gabnresponse_t
---to the lightweight resolver's canonical format.
---.Pp
---.Fn lwres_gabnrequest_parse
---uses context
---.Fa ctx
---to convert the contents of packet
---.Fa pkt
---to a
---.Dv lwres_gabnrequest_t
---structure.
---Buffer
---.Fa b
---provides space to be used for storing this structure.
---When the function succeeds, the resulting
---.Dv lwres_gabnrequest_t
---is made available through
---.Fa *structp .
---.Fn lwres_gabnresponse_parse
---offers the same semantics as
---.Fn lwres_gabnrequest_parse
---except it yields a
---.Dv lwres_gabnresponse_t
---structure.
---.Pp
---.Fn lwres_gabnresponse_free
---and
---.Fn lwres_gabnrequest_free
---release the memory in resolver context
---.Fa ctx
---that was allocated to the
---.Dv lwres_gabnresponse_t
---or
---.Dv lwres_gabnrequest_t
---structures referenced via
---.Fa structp .
---Any memory associated with ancillary buffers and strings for those
---structures is also discarded.
---.Sh RETURN VALUES
---The getaddrbyname opcode functions
---.Fn lwres_gabnrequest_render ,
---.Fn lwres_gabnresponse_render
---.Fn lwres_gabnrequest_parse
---and
---.Fn lwres_gabnresponse_parse
---all return
---.Er LWRES_R_SUCCESS
---on success.
---They return
---.Er LWRES_R_NOMEMORY
---if memory allocation fails.
---.Er LWRES_R_UNEXPECTEDEND
---is returned if the available space in the buffer
---.Fa b
---is too small to accommodate the packet header or the
---.Dv lwres_gabnrequest_t
---and
---.Dv lwres_gabnresponse_t
---structures.
---.Fn lwres_gabnrequest_parse
---and
---.Fn lwres_gabnresponse_parse
---will return
---.Er LWRES_R_UNEXPECTEDEND
---if the buffer is not empty after decoding the received packet.
---These functions will return
---.Er LWRES_R_FAILURE
---if
---.Li pktflags
---in the packet header structure
---.Dv lwres_lwpacket_t
---indicate that the packet is not a response to an earlier query.
---.Sh SEE ALSO
---.Xr lwres_packet 3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gabnrequest_free.3,v 1.4 2000/11/18 02:59:57 bwelling Exp $
---
---.so lwres_gabn.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gabnrequest_parse.3,v 1.4 2000/11/18 02:59:58 bwelling Exp $
---
---.so lwres_gabn.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gabnrequest_render.3,v 1.4 2000/11/18 03:00:00 bwelling Exp $
---
---.so lwres_gabn.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gabnresponse_free.3,v 1.4 2000/11/18 03:00:01 bwelling Exp $
---
---.so lwres_gabn.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gabnresponse_parse.3,v 1.4 2000/11/18 03:00:02 bwelling Exp $
---
---.so lwres_gabn.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gabnresponse_render.3,v 1.4 2000/11/18 03:00:03 bwelling Exp $
---
---.so lwres_gabn.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gai_strerror.3,v 1.5 2000/11/18 03:00:05 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_GAI_STRERROR 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm gai_strerror
---.Nd print suitable error string
---.Sh SYNOPSIS
---.Fd #include <lwres/netdb.h>
---.Fd
---.Ft char *
---.Fo gai_strerror
---.Fa "int ecode"
---.Fc
---.Sh DESCRIPTION
---.Fn lwres_gai_strerror
---returns an error message corresponding to an error code returned by
---.Fn getaddrinfo .
---The following error codes and their meaning are defined in
---.Aq Pa include/lwres/netdb.h .
---.Bl -tag -width EAI_ADDRFAMILY -offset indent -compact
---.It Dv EAI_ADDRFAMILY
---address family for hostname not supported
---.It Dv EAI_AGAIN
---temporary failure in name resolution
---.It Dv EAI_BADFLAGS
---invalid value for
---.Li ai_flags
---.It Dv EAI_FAIL
---non-recoverable failure in name resolution
---.It Dv EAI_FAMILY
---.Li ai_family
---not supported
---.It Dv EAI_MEMORY
---memory allocation failure
---.It Dv EAI_NODATA
---no address associated with hostname
---.It Dv EAI_NONAME
---hostname or servname not provided, or not known
---.It Dv EAI_SERVICE
---servname not supported for
---.Li ai_socktype
---.It Dv EAI_SOCKTYPE
---.Li ai_socktype
---not supported
---.It Dv EAI_SYSTEM
---system error returned in errno
---.El
---The message \*qinvalid error code\*q is returned if
---.Fa ecode
---is out of range.
---.Pp
---.Li ai_flags ,
---.Li ai_family
---and
---.Li ai_socktype
---are elements of the
---.Dv "struct addrinfo"
---used by
---.Fn lwres_getaddrinfo .
---.Sh SEE ALSO
---.Xr strerror 3 ,
---.Xr lwres_getaddrinfo 3 ,
---.Xr getaddrinfo 3 ,
---.Xr RFC2133 .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_getaddrinfo.3,v 1.7 2000/11/18 03:00:08 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_GETADDRINFO 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_getaddrinfo ,
---.Nm lwres_freeaddrinfo
---.Nd socket address structure to host and service name
---.Sh SYNOPSIS
---.Fd #include <lwres/netdb.h>
---.Fd
---.Ft int
---.Fo lwres_getaddrinfo
---.Fa "const char *hostname"
---.Fa "const char *servname"
---.Fa "const struct addrinfo *hints"
---.Fa "struct addrinfo **res"
---.Fc
---.Ft void
---.Fo lwres_freeaddrinfo
---.Fa "struct addrinfo *ai"
---.Fc
---.Pp
---If the operating system does not provide a
---.Dv "struct addrinfo" ,
---the following structure is used:
---.Pp
---.Bd -literal -offset indent
---struct addrinfo {
--- int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
--- int ai_family; /* PF_xxx */
--- int ai_socktype; /* SOCK_xxx */
--- int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
--- size_t ai_addrlen; /* length of ai_addr */
--- char *ai_canonname; /* canonical name for hostname */
--- struct sockaddr *ai_addr; /* binary address */
--- struct addrinfo *ai_next; /* next structure in linked list */
---};
---.Ed
---.Sh DESCRIPTION
---.Pp
---.Fn lwres_getaddrinfo
---is used to get a list of IP addresses and port numbers for host
---.Fa hostname
---and service
---.Fa servname .
---The function is the lightweight resolver's implementation of
---.Fn getaddrinfo
---as defined in RFC2133.
---.Fa hostname
---and
---.Fa servname
---are pointers to null-terminated
---strings or
---.Dv NULL .
---.Fa hostname
---is either a host name or a numeric host address string: a dotted decimal
---IPv4 address or an IPv6 address.
---.Fa servname
---is either a decimal port number or a service name as listed in
---.Pa /etc/services .
---.Pp
---.Fa hints
---is an optional pointer to a
---.Dv "struct addrinfo" .
---This structure can be used to provide hints concerning the type of socket
---that the caller supports or wishes to use.
---The caller can supply the following structure elements in
---.Fa *hints :
---.Bl -tag -width ai_socktyp -offset indent -compact
---.It Li ai_family
---the protocol family that should be used.
---When
---.Li ai_family
---is set to
---.Dv PF_UNSPEC ,
---it means the caller will accept any protocol family supported by the
---operating system.
---.It Dv ai_socktype
---denotes the type of socket -
---.Dv SOCK_STREAM ,
---.Dv SOCK_DGRAM
---or
---.Dv SOCK_RAW
---- that is wanted.
---When
---.Li ai_socktype
---is zero the caller will accept any socket type.
---.It Li ai_protocol
---indicates which transport protocol is wanted: IPPROTO_UDP or
---IPPROTO_TCP.
---If
---.Li ai_protocol
---is zero the caller will accept any protocol.
---.It Li ai_flags
---Flag bits.
---If the
---.Dv AI_CANONNAME
---bit is set, a successful call to
---.Fn lwres_getaddrinfo
---will return a a null-terminated string containing the canonical name
---of the specified hostname in
---.Li ai_canonname
---of the first
---.Dv addrinfo
---structure returned.
---Setting the
---.Dv AI_PASSIVE
---bit indicates that the returned socket address structure is intended
---for used in a call to
---.Xr bind 2 .
---In this case, if the hostname argument is a
---.Dv NULL
---pointer, then the IP address portion of the socket
---address structure will be set to
---.Dv INADDR_ANY
---for an IPv4 address or
---.Dv IN6ADDR_ANY_INIT
---for an IPv6 address.
---.Pp
---When
---.Li ai_flags
---does not set the
---.Dv AI_PASSIVE
---bit, the returned socket address structure will be ready
---for use in a call to
---.Xr connect 2
---for a connection-oriented protocol or
---.Xr connect 2 ,
---.Xr sendto 2 ,
---or
---.Xr sendmsg 2
---if a connectionless protocol was chosen.
---The IP address portion of the socket address structure will be
---set to the loopback address if
---.Fa hostname
---is a
---.Dv NULL
---pointer and
---.Dv AI_PASSIVE
---is not set in
---.Li ai_flags .
---.Pp
---If
---.Li ai_flags
---is set to
---.Dv AI_NUMERICHOST
---it indicates that
---.Fa hostname
---should be treated as a numeric string defining an IPv4 or IPv6 address
---and no name resolution should be attempted.
---.El
---.Pp
---All other elements of the
---.Dv "struct addrinfo"
---passed via
---.Fa hints
---must be zero.
---.Pp
---A
---.Fa hints
---of
---.Dv NULL
---is treated as if the caller provided a
---.Dv "struct addrinfo"
---initialized to zero with
---.Li ai_family set to
---.Li PF_UNSPEC .
---.Pp
---After a successful call to
---.Fn lwres_getaddrinfo ,
---.Fa *res
---is a pointer to a linked list of one or more
---.Dv addrinfo
---structures.
---Each
---.Dv "struct addrinfo"
---in this list cn be processed by following
---the
---.Li ai_next
---pointer, until a
---.Dv NULL
---pointer is encountered.
---The three members
---.Li ai_family ,
---.Li ai_socktype ,
---and
---.Li ai_protocol
---in each
---returned
---.Dv addrinfo
---structure contain the corresponding arguments for a call to
---.Xr socket 2 .
---For each
---.Dv addrinfo
---structure in the list, the
---.Li ai_addr
---member points to a filled-in socket address structure of length
---.Li ai_addrlen .
---.Pp
---All of the information returned by
---.Fn lwres_getaddrinfo
---is dynamically allocated: the addrinfo structures, and the socket
---address structures and canonical host name strings pointed to by the
---.Li addrinfo structures.
---Memory allocated for the dynamically allocated structures created by
---a successful call to
---.Fn lwres_getaddrinfo
---is released by
---.Fn lwres_freeaddrinfo .
---.Fa ai
---is a pointer to a
---.Dv "struct addrinfo"
---created by a call to
---.Fn lwres_getaddrinfo .
---.Sh RETURN VALUES
---.Fn lwres_getaddrinfo
---returns zero on success or one of the error codes listed in
---.Xr gai_strerror 3
---if an error occurs.
---If both
---.Fa hostname
---and
---.Fa servname
---are
---.Dv NULL
---.Fn lwres_getaddrinfo
---returns
---.Er EAI_NONAME .
---.Sh SEE ALSO
---.Xr lwres 3 ,
---.Xr lwres_getaddrinfo 3 ,
---.Xr lwres_freeaddrinfo 3 ,
---.Xr lwres_gai_strerror 3 ,
---.Xr RFC2133 ,
---.Xr getservbyname 3 ,
---.Xr bind 2 ,
---.Xr connect 2 ,
---.Xr sendto 2 ,
---.Xr sendmsg 2 ,
---.Xr socket 2 .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_getaddrsbyname.3,v 1.4 2000/11/18 03:00:10 bwelling Exp $
---
---.so lwres_resutil.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gethostbyaddr.3,v 1.4 2000/11/18 03:00:12 bwelling Exp $
---
---.so lwres_gethostent.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gethostbyaddr_r.3,v 1.4 2000/11/18 03:00:15 bwelling Exp $
---
---.so lwres_gethostent.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gethostbyname.3,v 1.4 2000/11/18 03:00:17 bwelling Exp $
---
---.so lwres_gethostent.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gethostbyname2.3,v 1.4 2000/11/18 03:00:19 bwelling Exp $
---
---.so lwres_gethostent.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gethostbyname_r.3,v 1.4 2000/11/18 03:00:20 bwelling Exp $
---
---.so lwres_gethostent.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gethostent.3,v 1.6 2000/12/04 18:37:38 gson Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_GETHOSTENT 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_gethostbyname ,
---.Nm lwres_gethostbyname2 ,
---.Nm lwres_gethostbyaddr ,
---.Nm lwres_gethostent ,
---.Nm lwres_sethostent ,
---.Nm lwres_endhostent ,
---.Nm lwres_gethostbyname_r ,
---.Nm lwres_gethostbyaddr_r ,
---.Nm lwres_gethostent_r ,
---.Nm lwres_sethostent_r ,
---.Nm lwres_endhostent_r
---.Nd lightweight resolver get network host entry
---.Sh SYNOPSIS
---.Fd #include <lwres/netdb.h>
---.Fd
---.Ft struct hostent *
---.Fo lwres_gethostbyname
---.Fa "const char *name"
---.Fc
---.Ft struct hostent *
---.Fo lwres_gethostbyname2
---.Fa "const char *name"
---.Fa "int af"
---.Fc
---.Ft struct hostent *
---.Fo lwres_gethostbyaddr
---.Fa "const char *addr"
---.Fa "int len"
---.Fa "int type"
---.Fc
---.Ft struct hostent *
---.Fo lwres_gethostent
---.Fa "void"
---.Fc
---.Ft void
---.Fo lwres_sethostent
---.Fa "int stayopen"
---.Fc
---.Ft void
---.Fo lwres_endhostent
---.Fa "void"
---.Fc
---.Ft struct hostent *
---.Fo lwres_gethostbyname_r
---.Fa "const char *name"
---.Fa "struct hostent *resbuf"
---.Fa "char *buf"
---.Fa "int buflen"
---.Fa "int *error"
---.Fc
---.Ft struct hostent *
---.Fo lwres_gethostbyaddr_r
---.Fa "const char *addr"
---.Fa "int len"
---.Fa "int type"
---.Fa "struct hostent *resbuf"
---.Fa "char *buf"
---.Fa "int buflen"
---.Fa "int *error"
---.Fc
---.Ft struct hostent *
---.Fo lwres_gethostent_r
---.Fa "struct hostent *resbuf"
---.Fa "char *buf"
---.Fa "int buflen"
---.Fa "int *error"
---.Fc
---.Ft void
---.Fo lwres_sethostent_r
---.Fa "int stayopen"
---.Fc
---.Ft void
---.Fo lwres_endhostent_r
---.Fa "void"
---.Fc
---.Sh DESCRIPTION
---These functions provide hostname-to-address and
---address-to-hostname lookups by means of the lightweight resolver.
---They are similar to the standard
---.Xr gethostent 3
---functions provided by most operating systems.
---They use a
---.Dv "struct hostent"
---which is usually defined in
---.Pa <namedb.h> .
---.Bd -literal
---struct hostent {
--- char *h_name; /* official name of host */
--- char **h_aliases; /* alias list */
--- int h_addrtype; /* host address type */
--- int h_length; /* length of address */
--- char **h_addr_list; /* list of addresses from name server */
---};
---#define h_addr h_addr_list[0] /* address, for backward compatibility */
---.Ed
---.Pp
---The members of this structure are:
---.Bl -tag -width h_addr_list
---.It Li h_name
---The official (canonical) name of the host.
---.It Li h_aliases
---A NULL-terminated array of alternate names (nicknames) for the host.
---.It Li h_addrtype
---The type of address being returned -
---.Dv PF_INET
---or
---.Dv PF_INET6 .
---.It Li h_length
---The length of the address in bytes.
---.It Li h_addr_list
---A
---.Dv NULL
---terminated array of network addresses for the host.
---Host addresses are returned in network byte order.
---.El
---.Pp
---For backward compatibility with very old software,
---.Li h_addr
---is the first address in
---.Li h_addr_list.
---.Pp
---.Fn lwres_gethostent ,
---.Fn lwres_sethostent ,
---.Fn lwres_endhostent ,
---.Fn lwres_gethostent_r ,
---.Fn lwres_sethostent_r
---and
---.Fn lwres_endhostent_r
---provide iteration over the known host entries on systems that
---provide such functionality through facilities like
---.Pa /etc/hosts
---or NIS. The lightweight resolver does not currently implement
---these functions; it only provides them as stub functions that always
---return failure.
---.Pp
---.Fn lwres_gethostbyname
---and
---.Fn lwres_gethostbyname2
---look up the hostname
---.Fa name .
---.Fn lwres_gethostbyname
---always looks for an IPv4 address while
---.Fn lwres_gethostbyname2
---looks for an address of protocol family
---.Fa af :
---either
---.Dv PF_INET
---or
---.Dv PF_INET6
---- IPv4 or IPV6 addresses respectively.
---Successful calls of the functions return a
---.Dv "struct hostent" for
---the name that was looked up.
---.Dv NULL
---is returned if the lookups by
---.Fn lwres_gethostbyname
---or
---.Fn lwres_gethostbyname2
---fail.
---.Pp
---Reverse lookups of addresses are performed by
---.Fn lwres_gethostbyaddr .
---.Fa addr
---is an address of length
---.Fa len
---bytes and protocol family
---.Fa type -
---.Dv PF_INET
---or
---.Dv PF_INET6 .
---.Fn lwres_gethostbyname_r
---is a thread-safe function for forward lookups.
---If an error occurs, an error code is returned in
---.Fa *error .
---.Fa resbuf
---is a pointer to a
---.Dv "struct hostent"
---which is initialised by a successful call to
---.Fn lwres_gethostbyname_r .
---.Fa buf
---is a buffer of length
---.Fa len
---bytes which is used to store the
---.Li h_name ,
---.Li h_aliases ,
---and
---.Li h_addr_list
---elements of the
---.Dv "struct hostent"
---returned in
---.Fa resbuf .
---Successful calls to
---.Fn lwres_gethostbyname_r
---return
---.Fa resbuf ,
---which is a pointer to the
---.Dv "struct hostent"
---it created.
---.Pp
---.Fn lwres_gethostbyaddr_r
---is a thread-safe function that performs a reverse lookup of address
---.Fa addr
---which is
---.Fa len
---bytes long
---and is of protocol family
---.Fa type -
---.Dv PF_INET
---or
---.Dv PF_INET6 .
---If an error occurs, the error code is returned in
---.Fa *error .
---The other function parameters are identical to those in
---.Fn lwres_gethostbyname_r .
---.Fa resbuf
---is a pointer to a
---.Dv "struct hostent"
---which is initialised by a successful call to
---.Fn lwres_gethostbyaddr_r .
---.Fa buf
---is a buffer of length
---.Fa len
---bytes which is used to store the
---.Li h_name ,
---.Li h_aliases ,
---and
---.Li h_addr_list
---elements of the
---.Dv "struct hostent"
---returned in
---.Fa resbuf .
---Successful calls to
---.Fn lwres_gethostbyaddr_r
---return
---.Fa resbuf ,
---which is a pointer to the
---.Fn "struct hostent"
---it created.
---.Sh RETURN VALUES
---.Pp
---The functions
---.Fn lwres_gethostbyname ,
---.Fn lwres_gethostbyname2 ,
---.Fn lwres_gethostbyaddr ,
---and
---.Fn lwres_gethostent
---return NULL to indicate an error. In this case the global variable
---.Dv lwres_h_errno
---will contain one of the following error codes defined in
---.Pa <lwres/netdb.h> :
---.Bl -tag -width HOST_NOT_FOUND
---.It Li HOST_NOT_FOUND
---The host or address was not found.
---.It Li TRY_AGAIN
---A recoverable error occurred, e.g., a timeout.
---Retrying the lookup may succeed.
---.It Li NO_RECOVERY
---A non-recoverable error occurred.
---.It Li NO_DATA
---The name exists, but has no address information
---associated with it (or vice versa in the case
---of a reverse lookup). The code NO_ADDRESS
---is accepted as a synonym for NO_DATA for backwards
---compatibility.
---.El
---.Pp
---.Xr lwres_hstrerror 3
---translates these error codes to suitable error messages.
---.Pp
---.Fn lwres_gethostent
---and
---.Fn lwres_gethostent_r
---always return
---.Dv NULL .
---.Pp
---Successful calls to
---.Fn lwres_gethostbyname_r
---and
---.Fn lwres_gethostbyaddr_r
---return
---.Fa resbuf ,
---a pointer to the
---.Dv "struct hostent"
---that was initialised by these functions.
---They return
---.Dv NULL
---if the lookups fail
---or if
---.Fa buf
---was too small to hold the list of addresses and names referenced by
---the
---.Li h_name ,
---.Li h_aliases ,
---and
---.Li h_addr_list
---elements of the
---.Dv "struct hostent" .
---If
---.Fa buf
---was too small, both
---.Fn lwres_gethostbyname_r
---and
---.Fn lwres_gethostbyaddr_r
---set the global variable
---.Dv errno
---to
---.Er ERANGE .
---.Sh SEE ALSO
---.Xr gethostent 3 ,
---.Xr lwres_getipnode 3 ,
---.Xr lwres_hstrerror 3
---.Sh BUGS
---.Fn lwres_gethostbyname ,
---.Fn lwres_gethostbyname2 ,
---.Fn lwres_gethostbyaddr
---and
---.Fn lwres_endhostent
---are not thread safe; they return pointers to static data and
---provide error codes through a global variable.
---Thread-safe versions for name and address lookup are provided by
---.Fn lwres_gethostbyname_r ,
---and
---.Fn lwres_gethostbyaddr_r
---respectively.
---.Pp
---The resolver daemon does not currently support any non-DNS
---name services such as
---.Pa /etc/hosts
---or
---.Dv NIS ,
---consequently the above functions don't, either.
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gethostent_r.3,v 1.4 2000/11/18 03:00:22 bwelling Exp $
---
---.so lwres_gethostent.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_getipnode.3,v 1.5 2000/11/18 03:00:23 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_GETIPNODE 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_getipnodebyname ,
---.Nm lwres_getipnodebyaddr ,
---.Nm lwres_freehostent
---.Nd lightweight resolver nodename / address translation API
---.Sh SYNOPSIS
---.Fd #include <lwres/netdb.h>
---.Fd
---.Ft struct hostent *
---.Fo lwres_getipnodebyname
---.Fa "const char *name"
---.Fa "int af"
---.Fa "int flags"
---.Fa "int *error_num"
---.Fc
---.Ft struct hostent *
---.Fo lwres_getipnodebyaddr
---.Fa "const void *src"
---.Fa "size_t len"
---.Fa "int af"
---.Fa "int *error_num"
---.Fc
---.Ft void
---.Fo lwres_freehostent
---.Fa "struct hostent *he"
---.Fc
---.Sh DESCRIPTION
---These functions perform thread safe, protocol independent
---nodename-to-address and address-to-nodename
---translation as defined in RFC2553.
---.Pp
---They use a
---.Dv "struct hostent"
---which is defined in
---.Pa namedb.h :
---.Bd -literal
---struct hostent {
--- char *h_name; /* official name of host */
--- char **h_aliases; /* alias list */
--- int h_addrtype; /* host address type */
--- int h_length; /* length of address */
--- char **h_addr_list; /* list of addresses from name server */
---};
---#define h_addr h_addr_list[0] /* address, for backward compatibility */
---.Ed
---.Pp
---The members of this structure are:
---.Bl -tag -width h_addr_list
---.It Li h_name
---The official (canonical) name of the host.
---.It Li h_aliases
---A NULL-terminated array of alternate names (nicknames) for the host.
---.It Li h_addrtype
---The type of address being returned - usually
---.Dv PF_INET
---or
---.Dv PF_INET6 .
---.It Li h_length
---The length of the address in bytes.
---.It Li h_addr_list
---A
---.Dv NULL
---terminated array of network addresses for the host.
---Host addresses are returned in network byte order.
---.El
---.Pp
---.Fn lwres_getipnodebyname
---looks up addresses of protocol family
---.Fa af
---for the hostname
---.Fa name .
---The
---.Fa flags
---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:
---.Bl -tag -width AI_ADDRCONFIG
---.It Li AI_V4MAPPED
---This is used with an
---.Fa af
---of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
---IPv6 addresses.
---.It Li AI_ALL
---This is used with an
---.Fa af
---of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
---If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
---IPv6 addresses.
---.It Li AI_ADDRCONFIG
---Only return an IPv6 or IPv4 address if here is an active network
---interface of that type. This is not currently implemented
---in the BIND 9 lightweight resolver, and the flag is ignored.
---.It Li AI_DEFAULT
---This default sets the
---.Li AI_V4MAPPED
---and
---.Li AI_ADDRCONFIG
---flag bits.
---.El
---.Pp
---.Fn lwres_getipnodebyaddr
---performs a reverse lookup
---of address
---.Fa src
---which is
---.Fa len
---bytes long.
---.Fa af
---denotes the protocol family, typically
---.Dv PF_INET
---or
---.Dv PF_INET6 .
---.Pp
---.Fn lwres_freehostent
---releases all the memory associated with
---the
---.Dv "struct hostent"
---pointer
---.Fa he .
---Any memory allocated for the
---.Li h_name ,
---.Li h_addr_list
---and
---.Li h_aliases
---is freed, as is the memory for the
---.Dv hostent
---structure itself.
---.Sh RETURN VALUES
---If an error occurs,
---.Fn lwres_getipnodebyname
---and
---.Fn lwres_getipnodebyaddr
---set
---.Fa *error_num
---to an approriate error code and the function returns a
---.Dv NULL
---pointer.
---The error codes and their meanings are defined in
---.Pa <lwres/netdb.h> :
---.Bl -tag -width HOST_NOT_FOUND
---.It Li HOST_NOT_FOUND
---No such host is known.
---.It Li NO_ADDRESS
---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.
---.It Li TRY_AGAIN
---A temporary and possibly transient error occurred, such as a
---failure of a server to respond. The request may succeed if
---retried.
---.It Li NO_RECOVERY
---An unexpected failure occurred, and retrying the request
---is pointless.
---.El
---.Pp
---.Xr lwres_hstrerror 3
---translates these error codes to suitable error messages.
---.Sh SEE ALSO
---.Xr RFC2553 ,
---.Xr lwres 3 ,
---.Xr lwres_gethostent 3 ,
---.Xr lwres_getaddrinfo 3 ,
---.Xr lwres_getnameinfo 3 ,
---.Xr lwres_hstrerror 3 .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_getipnodebyaddr.3,v 1.4 2000/11/18 03:00:25 bwelling Exp $
---
---.so lwres_getipnode.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_getipnodebyname.3,v 1.4 2000/11/18 03:00:26 bwelling Exp $
---
---.so lwres_getipnode.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_getnamebyaddr.3,v 1.4 2000/11/18 03:00:27 bwelling Exp $
---
---.so lwres_resutil.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_getnameinfo.3,v 1.7 2000/12/04 18:37:39 gson Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_GETNAMEINFO 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_getnameinfo
---.Nd lightweight resolver socket address structure to hostname and service name
---.Sh SYNOPSIS
---.Fd #include <lwres/netdb.h>
---.Fd
---.Ft int
---.Fo lwres_getnameinfo
---.Fa "const struct sockaddr *sa"
---.Fa "size_t salen"
---.Fa "char *host"
---.Fa "size_t hostlen"
---.Fa "char *serv"
---.Fa "size_t servlen"
---.Fa "int flags"
---.Fc
---.Sh DESCRIPTION
---.Pp
---This function is equivalent to the
---.Xr getnameinfo 3
---function defined in RFC2133.
---.Fn lwres_getnameinfo
---returns the hostname for the
---.Dv "struct sockaddr"
---.Fa sa
---which is
---.Fa salen
---bytes long.
---The hostname is of length
---.Fa hostlen
---and is returned via
---.Fa *host.
---The maximum length of the hostname is
---1025 bytes:
---.Li NI_MAXHOST .
---.Pp
---The name of the service associated with the port number in
---.Fa sa
---is returned in
---.Fa *serv.
---It is
---.Fa servlen
---bytes long.
---The maximum length of the service name is
---.Li NI_MAXSERV
---- 32 bytes.
---.Pp
---The
---.Fa flags
---argument sets the following bits:
---.Bl -tag -width NI_NUMERICSERV
---.It Li NI_NOFQDN
---A fully qualified domain name is not required for local hosts.
---The local part of the fully qualified domain name is returned instead.
---.It Li NI_NUMERICHOST
---Return the address in numeric form, as if calling inet_ntop(),
---instead of a host name.
---.It Li NI_NAMEREQD
---A name is required. If the hostname cannot be found in the DNS and
---this flag is set, a non-zero error code is returned.
---If the hostname is not found and the flag is not set, the
---address is returned in numeric form.
---.It Li NI_NUMERICSERV
---The service name is returned as a digit string representing the port number.
---.It Li NI_DGRAM
---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.
---.El
---.Pp
---.Sh RETURN VALUES
---.Fn lwres_getnameinfo
---returns 0 on success or a non-zero error code if an error occurs.
---.\"
---.\" The error codes below were invented by the ISC/Nominum. They
---.\" should be defined in RFC2133 before getting documented here.
---.\" XXXJR 28/6/00
---.\" The error codes are:
---.\" Bl -tag -width ENI_NOSERVNAME
---.\" It Li ENI_NOSOCKET
---.\" there was no socket in
---.\" Fa sa
---.\" It Li ENI_NOSERVNAME
---.\" no service name was found
---.\" It Li ENI_NOHOSTNAME
---.\" no hostname was found
---.\" It Li ENI_MEMORY
---.\" memory could not be allocated
---.\" It Li ENI_SYSTEM
---.\" a system error occurred
---.\" It Li ENI_FAMILY
---.\" an unsupported protocol family was requested
---.\" It Li ENI_SALEN
---.\" Fa salen
---.\" is the wrong number of bytes for the address in
---.\" Fa sa .
---.Sh SEE ALSO
---.Xr RFC2133 ,
---.Xr getservbyport 3 ,
---.Xr lwres 3 ,
---.Xr lwres_getnameinfo 3 ,
---.Xr lwres_getnamebyaddr 3 .
---.Xr lwres_net_ntop 3 .
---.Sh BUGS
---RFC2133 fails to define what the nonzero return values of
---.Xr getnameinfo 3
---are.
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_getrrsetbyname.3,v 1.3 2000/11/29 22:55:11 gson Exp $
---
---.Dd Oct 18, 2000
---.Dt LWRES_GETRRSETBYNAME 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_getrrsetbyname ,
---.Nm lwres_freerrset
---.Nd retrieve DNS records
---.Sh SYNOPSIS
---.Fd #include <lwres/netdb.h>
---.Fd
---.Ft int
---.Fo lwres_getrrsetbyname
---.Fa "const char *hostname"
---.Fa "unsigned int rdclass"
---.Fa "unsigned int rdtype"
---.Fa "unsigned int flags"
---.Fa "struct rrsetinfo **res"
---.Fc
---.Ft void
---.Fo lwres_freerrset
---.Fa "struct rrsetinfo *rrset"
---.Fc
---.Pp
---The following structures are used:
---.Pp
---.Bd -literal -offset indent
---struct rdatainfo {
--- unsigned int rdi_length; /* length of data */
--- unsigned char *rdi_data; /* record data */
---};
---
---struct rrsetinfo {
--- unsigned int rri_flags; /* RRSET_VALIDATED... */
--- unsigned int rri_rdclass; /* class number */
--- unsigned int rri_rdtype; /* RR type number */
--- unsigned int rri_ttl; /* time to live */
--- unsigned int rri_nrdatas; /* size of rdatas array */
--- unsigned int rri_nsigs; /* size of sigs array */
--- char *rri_name; /* canonical name */
--- struct rdatainfo *rri_rdatas; /* individual records */
--- struct rdatainfo *rri_sigs; /* individual signatures */
---};
---.Ed
---.Sh DESCRIPTION
---.Pp
---.Fn lwres_getrrsetbyname
---gets a set of resource records associated with a
---.Fa hostname ,
---.Fa class ,
---and
---.Fa type .
---.Fa hostname
---is
---a pointer a to null-terminated string. The
---.Fa flags
---field is currently unused and must be zero.
---.Pp
---After a successful call to
---.Fn lwres_getrrsetbyname ,
---.Fa *res
---is a pointer to an
---.Dv rrsetinfo
---structure, containing a list of one or more
---.Dv rdatainfo
---structures containing resource records and potentially another list of
---.Dv rdatainfo
---structures containing SIG resource records
---associated with those records.
---The members
---.Li rri_rdclass
---and
---.Li rri_rdtype
---are copied from the parameters.
---.Li rri_ttl
---and
---.Li rri_name
---are properties of the obtained rrset.
---The resource records contained in
---.Li rri_rdatas
---and
---.Li rri_sigs
---are in uncompressed DNS wire format.
---Properties of the rdataset are represented in the
---.Li rri_flags
---bitfield. If the RRSET_VALIDATED bit is set, the data has been DNSSEC
---validated and the signatures verified.
---.Pp
---All of the information returned by
---.Fn lwres_getrrsetbyname
---is dynamically allocated: the
---.Li rrsetinfo
---and
---.Li rdatainfo
---structures,
---and the canonical host name strings pointed to by the
---.Li rrsetinfo structure.
---Memory allocated for the dynamically allocated structures created by
---a successful call to
---.Fn lwres_getrrsetbyname
---is released by
---.Fn lwres_freerrset .
---.Fa rrset
---is a pointer to a
---.Dv "struct rrset"
---created by a call to
---.Fn lwres_getrrsetbyname .
---.Pp
---.Sh RETURN VALUES
---.Fn lwres_getrrsetbyname
---returns zero on success or an error code if an error occurs. The defined
---error codes are ERRSET_NOMEMORY (memory could not be allocated),
---ERRSET_INVAL (a parameter is invalid) and ERRSET_FAIL (other failure).
---.Sh SEE ALSO
---.Xr lwres 3 .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gnba.3,v 1.5 2000/11/18 03:00:30 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_GNBA 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_gnbarequest_render ,
---.Nm lwres_gnbaresponse_render ,
---.Nm lwres_gnbarequest_parse ,
---.Nm lwres_gnbaresponse_parse ,
---.Nm lwres_gnbaresponse_free ,
---.Nm lwres_gnbarequest_free
---.Nd lightweight resolver getnamebyaddress message handling
---.Sh SYNOPSIS
---.Fd #include <lwres/lwres.h>
---.Fd
---.Ft lwres_result_t
---.Fo lwres_gnbarequest_render
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_gnbarequest_t *req"
---.Fa "lwres_lwpacket_t *pkt"
---.Fa "lwres_buffer_t *b"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_gnbaresponse_render
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_gnbaresponse_t *req"
---.Fa "lwres_lwpacket_t *pkt"
---.Fa "lwres_buffer_t *b"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_gnbarequest_parse
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_buffer_t *b"
---.Fa "lwres_lwpacket_t *pkt"
---.Fa "lwres_gnbarequest_t **structp"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_gnbaresponse_parse
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_buffer_t *b"
---.Fa "lwres_lwpacket_t *pkt"
---.Fa "lwres_gnbaresponse_t **structp"
---.Fc
---.Ft void
---.Fo lwres_gnbaresponse_free
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_gnbaresponse_t **structp"
---.Fc
---.Ft void
---.Fo lwres_gnbarequest_free
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_gnbarequest_t **structp"
---.Fc
---.Sh DESCRIPTION
---These are low-level routines for creating and parsing
---lightweight resolver address-to-name lookup request and
---response messages.
---.Pp
---There are four main functions for the getnamebyaddr opcode.
---One render function converts a getnamebyaddr request structure -
---.Dv lwres_gnbarequest_t -
---to the lighweight resolver's canonical format.
---It is complemented by a parse function that converts a packet in this
---canonical format to a getnamebyaddr request structure.
---Another render function converts the getnamebyaddr response structure -
---.Dv lwres_gnbaresponse_t
---to the canonical format.
---This is complemented by a parse function which converts a packet in
---canonical format to a getnamebyaddr response structure.
---.Pp
---These structures are defined in
---.Pa lwres/lwres.h .
---They are shown below.
---.Bd -literal -offset indent
---#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U
---
---typedef struct {
--- lwres_uint32_t flags;
--- lwres_addr_t addr;
---} lwres_gnbarequest_t;
---
---typedef struct {
--- lwres_uint32_t flags;
--- lwres_uint16_t naliases;
--- char *realname;
--- char **aliases;
--- lwres_uint16_t realnamelen;
--- lwres_uint16_t *aliaslen;
--- void *base;
--- size_t baselen;
---} lwres_gnbaresponse_t;
---.Ed
---.Pp
---.Fn lwres_gnbarequest_render
---uses resolver context
---.Fa ctx
---to convert getnamebyaddr request structure
---.Fa req
---to canonical format.
---The packet header structure
---.Fa pkt
---is initialised and transferred to
---buffer
---.Fa b .
---The contents of
---.Fa *req
---are then appended to the buffer in canonical format.
---.Fn lwres_gnbaresponse_render
---performs the same task, except it converts a getnamebyaddr response structure
---.Dv lwres_gnbaresponse_t
---to the lightweight resolver's canonical format.
---.Pp
---.Fn lwres_gnbarequest_parse
---uses context
---.Fa ctx
---to convert the contents of packet
---.Fa pkt
---to a
---.Dv lwres_gnbarequest_t
---structure.
---Buffer
---.Fa b
---provides space to be used for storing this structure.
---When the function succeeds, the resulting
---.Dv lwres_gnbarequest_t
---is made available through
---.Fa *structp .
---.Fn lwres_gnbaresponse_parse
---offers the same semantics as
---.Fn lwres_gnbarequest_parse
---except it yields a
---.Dv lwres_gnbaresponse_t
---structure.
---.Pp
---.Fn lwres_gnbaresponse_free
---and
---.Fn lwres_gnbarequest_free
---release the memory in resolver context
---.Fa ctx
---that was allocated to the
---.Dv lwres_gnbaresponse_t
---or
---.Dv lwres_gnbarequest_t
---structures referenced via
---.Fa structp .
---Any memory associated with ancillary buffers and strings for those
---structures is also discarded.
---.Sh RETURN VALUES
---The getnamebyaddr opcode functions
---.Fn lwres_gnbarequest_render ,
---.Fn lwres_gnbaresponse_render
---.Fn lwres_gnbarequest_parse
---and
---.Fn lwres_gnbaresponse_parse
---all return
---.Er LWRES_R_SUCCESS
---on success.
---They return
---.Er LWRES_R_NOMEMORY
---if memory allocation fails.
---.Er LWRES_R_UNEXPECTEDEND
---is returned if the available space in the buffer
---.Fa b
---is too small to accommodate the packet header or the
---.Dv lwres_gnbarequest_t
---and
---.Dv lwres_gnbaresponse_t
---structures.
---.Fn lwres_gnbarequest_parse
---and
---.Fn lwres_gnbaresponse_parse
---will return
---.Er LWRES_R_UNEXPECTEDEND
---if the buffer is not empty after decoding the received packet.
---These functions will return
---.Er LWRES_R_FAILURE
---if
---.Li pktflags
---in the packet header structure
---.Dv lwres_lwpacket_t
---indicate that the packet is not a response to an earlier query.
---.Sh SEE ALSO
---.Xr lwres_packet 3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gnbarequest_free.3,v 1.4 2000/11/18 03:00:31 bwelling Exp $
---
---.so lwres_gnba.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gnbarequest_parse.3,v 1.4 2000/11/18 03:00:33 bwelling Exp $
---
---.so lwres_gnba.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gnbarequest_render.3,v 1.4 2000/11/18 03:00:34 bwelling Exp $
---
---.so lwres_gnba.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gnbaresponse_free.3,v 1.4 2000/11/18 03:00:36 bwelling Exp $
---
---.so lwres_gnba.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gnbaresponse_parse.3,v 1.4 2000/11/18 03:00:37 bwelling Exp $
---
---.so lwres_gnba.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_gnbaresponse_render.3,v 1.4 2000/11/18 03:00:38 bwelling Exp $
---
---.so lwres_gnba.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_herror.3,v 1.4 2000/11/18 03:00:39 bwelling Exp $
---
---.so lwres_hstrerror.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_hstrerror.3,v 1.5 2000/12/04 18:37:40 gson Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_ERROR 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_herror ,
---.Nm lwres_hstrerror
---.Nd lightweight resolver error message generation
---.Sh SYNOPSIS
---.Fd #include <lwres/netdb.h>
---.Fd
---.Ft void
---.Fo lwres_herror
---.Fa "const char *s"
---.Fc
---.Ft const char *
---.Fo lwres_hstrerror
---.Fa "int err"
---.Fc
---.Sh DESCRIPTION
---.Fn lwres_herror
---prints the string
---.Fa s
---on
---.Dv stderr
---followed by the string generated by
---.Fn lwres_hstrerror
---for the error code stored in the global variable
---.Li lwres_h_errno .
---.Pp
---.Fn lwres_hstrerror
---returns an appropriate string for the error code gievn by
---.Fa err .
---The values of the error codes and messages are as follows:
---.Bl -tag -width HOST_NOT_FOUND
---.It Li NETDB_SUCCESS
---\*qResolver Error 0 (no error)\*q
---.It Li HOST_NOT_FOUND
---\*qUnknown host\*q
---.It Li TRY_AGAIN
---\*qHost name lookup failure\*q
---.It Li NO_RECOVERY
---\*qUnknown server error\*q
---.It Li NO_DATA
---\*qNo address associated with name\*q
---.El
---.Sh RETURN VALUES
---The string \*qUnknown resolver error\*q is returned by
---.Fn lwres_hstrerror
---when the value of
---.Li lwres_h_errno
---is not a valid error code.
---.Sh SEE ALSO
---.Xr herror 3 ,
---.Xr lwres_hstrerror 3 .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_inetntop.3,v 1.4 2000/11/18 03:00:43 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_INETNTOP 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_net_ntop
---.Nd lightweight resolver IP address presentation
---.Sh SYNOPSIS
---.Fd #include <lwres/net.h>
---.Fd
---.Ft const char *
---.Fo lwres_net_ntop
---.Fa "int af"
---.Fa "const void *src"
---.Fa "char *dst"
---.Fa "size_t size"
---.Fc
---.Sh DESCRIPTION
---.Fn lwres_net_ntop
---converts an IP address of protocol family
---.Fa af
---- IPv4 or IPv6 - at location
---.Fa src
---from network format to its conventional representation as a string.
---For IPv4 addresses, that string would be a dotted-decimal.
---An IPv6 address would be represented in colon notation as described in
---RFC1884.
---.Pp
---The generated string is copied to
---.Fa dst
---provided
---.Fa size
---indicates it is long enough to store the ASCII representation
---of the address.
---.Sh RETURN VALUES
---.Pp
---If successful, the function returns
---.Fa dst :
---a pointer to a string containing
---the presentation format of the address.
---.Fn lwres_net_ntop
---returns
---.Dv NULL
---and sets the global variable
---.Li errno
---to
---.Er EAFNOSUPPORT
---if the protocol family given in
---.Fa af
---is not supported.
---.Sh SEE ALSO
---.Xr RFC1884 ,
---.Xr inet_ntop 3 ,
---.Xr errno 3 .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_lwpacket_parseheader.3,v 1.4 2000/11/18 03:00:44 bwelling Exp $
---
---.so lwres_packet.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_lwpacket_renderheader.3,v 1.4 2000/11/18 03:00:45 bwelling Exp $
---
---.so lwres_packet.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_net_ntop.3,v 1.4 2000/11/18 03:00:46 bwelling Exp $
---
---.so lwres_inetntop.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_noop.3,v 1.5 2000/11/18 03:00:47 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_NOOP 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_nooprequest_render ,
---.Nm lwres_noopresponse_render ,
---.Nm lwres_nooprequest_parse ,
---.Nm lwres_noopresponse_parse ,
---.Nm lwres_noopresponse_free ,
---.Nm lwres_nooprequest_free
---.Nd lightweight resolver no-op message handling
---.Sh SYNOPSIS
---.Fd #include <lwres/lwres.h>
---.Fd
---.Ft lwres_result_t
---.Fo lwres_nooprequest_render
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_nooprequest_t *req"
---.Fa "lwres_lwpacket_t *pkt"
---.Fa "lwres_buffer_t *b"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_noopresponse_render
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_noopresponse_t *req"
---.Fa "lwres_lwpacket_t *pkt"
---.Fa "lwres_buffer_t *b"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_nooprequest_parse
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_buffer_t *b"
---.Fa "lwres_lwpacket_t *pkt"
---.Fa "lwres_nooprequest_t **structp"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_noopresponse_parse
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_buffer_t *b"
---.Fa "lwres_lwpacket_t *pkt"
---.Fa "lwres_noopresponse_t **structp"
---.Fc
---.Ft void
---.Fo lwres_noopresponse_free
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_noopresponse_t **structp"
---.Fc
---.Ft void
---.Fo lwres_nooprequest_free
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_nooprequest_t **structp"
---.Fc
---.Sh DESCRIPTION
---These are low-level routines for creating and parsing
---lightweight resolver no-op request and response messages.
---.P
---The no-op message is analogous to a \*qping\*q packet:
---a packet is sent to the resolver daemon and is simply echoed back.
---The opcode is intended to allow a client to determine if the server is
---operational or not.
---.Pp
---There are four main functions for the no-op opcode.
---One render function converts a no-op request structure -
---.Dv lwres_nooprequest_t -
---to the lighweight resolver's canonical format.
---It is complemented by a parse function that converts a packet in this
---canonical format to a no-op request structure.
---Another render function converts the no-op response structure -
---.Dv lwres_noopresponse_t
---to the canonical format.
---This is complemented by a parse function which converts a packet in
---canonical format to a no-op response structure.
---.Pp
---These structures are defined in
---.Pa lwres/lwres.h .
---They are shown below.
---.Bd -literal -offset indent
---#define LWRES_OPCODE_NOOP 0x00000000U
---
---typedef struct {
--- lwres_uint16_t datalength;
--- unsigned char *data;
---} lwres_nooprequest_t;
---
---typedef struct {
--- lwres_uint16_t datalength;
--- unsigned char *data;
---} lwres_noopresponse_t;
---.Ed
---Although the structures have different types, they are identical.
---This is because the no-op opcode simply echos whatever data was sent:
---the response is therefore identical to the request.
---.Pp
---.Fn lwres_nooprequest_render
---uses resolver context
---.Fa ctx
---to convert no-op request structure
---.Fa req
---to canonical format.
---The packet header structure
---.Fa pkt
---is initialised and transferred to
---buffer
---.Fa b .
---The contents of
---.Fa *req
---are then appended to the buffer in canonical format.
---.Fn lwres_noopresponse_render
---performs the same task, except it converts a no-op response structure
---.Dv lwres_noopresponse_t
---to the lightweight resolver's canonical format.
---.Pp
---.Fn lwres_nooprequest_parse
---uses context
---.Fa ctx
---to convert the contents of packet
---.Fa pkt
---to a
---.Dv lwres_nooprequest_t
---structure.
---Buffer
---.Fa b
---provides space to be used for storing this structure.
---When the function succeeds, the resulting
---.Dv lwres_nooprequest_t
---is made available through
---.Fa *structp .
---.Fn lwres_noopresponse_parse
---offers the same semantics as
---.Fn lwres_nooprequest_parse
---except it yields a
---.Dv lwres_noopresponse_t
---structure.
---.Pp
---.Fn lwres_noopresponse_free
---and
---.Fn lwres_nooprequest_free
---release the memory in resolver context
---.Fa ctx
---that was allocated to the
---.Dv lwres_noopresponse_t
---or
---.Dv lwres_nooprequest_t
---structures referenced via
---.Fa structp .
---.Sh RETURN VALUES
---The no-op opcode functions
---.Fn lwres_nooprequest_render ,
---.Fn lwres_noopresponse_render
---.Fn lwres_nooprequest_parse
---and
---.Fn lwres_noopresponse_parse
---all return
---.Er LWRES_R_SUCCESS
---on success.
---They return
---.Er LWRES_R_NOMEMORY
---if memory allocation fails.
---.Er LWRES_R_UNEXPECTEDEND
---is returned if the available space in the buffer
---.Fa b
---is too small to accommodate the packet header or the
---.Dv lwres_nooprequest_t
---and
---.Dv lwres_noopresponse_t
---structures.
---.Fn lwres_nooprequest_parse
---and
---.Fn lwres_noopresponse_parse
---will return
---.Er LWRES_R_UNEXPECTEDEND
---if the buffer is not empty after decoding the received packet.
---These functions will return
---.Er LWRES_R_FAILURE
---if
---.Li pktflags
---in the packet header structure
---.Dv lwres_lwpacket_t
---indicate that the packet is not a response to an earlier query.
---.Sh SEE ALSO
---.Xr lwres_packet 3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_nooprequest_free.3,v 1.4 2000/11/18 03:00:48 bwelling Exp $
---
---.so lwres_noop.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_nooprequest_parse.3,v 1.4 2000/11/18 03:00:50 bwelling Exp $
---
---.so lwres_noop.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_nooprequest_render.3,v 1.4 2000/11/18 03:00:51 bwelling Exp $
---
---.so lwres_noop.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_noopresponse_free.3,v 1.4 2000/11/18 03:00:53 bwelling Exp $
---
---.so lwres_noop.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_noopresponse_parse.3,v 1.4 2000/11/18 03:00:54 bwelling Exp $
---
---.so lwres_noop.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_noopresponse_render.3,v 1.4 2000/11/18 03:00:55 bwelling Exp $
---
---.so lwres_noop.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_packet.3,v 1.5 2000/11/18 03:00:56 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_PACKET 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_lwpacket_renderheader ,
---.Nm lwres_lwpacket_parseheader
---.Nd lightweight resolver packet handling functions
---.Sh SYNOPSIS
---.Fd #include <lwres/lwbuffer.h>
---.Fd #include <lwres/lwpacket.h>
---.Fd #include <lwres/result.h>
---.Fd
---.Ft lwres_result_t
---.Fo lwres_lwpacket_renderheader
---.Fa "lwres_buffer_t *b"
---.Fa "lwres_lwpacket_t *pkt"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_lwpacket_parseheader
---.Fa "lwres_buffer_t *b"
---.Fa "lwres_lwpacket_t *pkt"
---.Fc
---.Sh DESCRIPTION
---These functions rely on a
---.Dv "struct lwres_lwpacket"
---which is defined in
---.Pa lwres/lwpacket.h .
---.Bd -literal -offset indent
---typedef struct lwres_lwpacket lwres_lwpacket_t;
---
---struct lwres_lwpacket {
--- lwres_uint32_t length;
--- lwres_uint16_t version;
--- lwres_uint16_t pktflags;
--- lwres_uint32_t serial;
--- lwres_uint32_t opcode;
--- lwres_uint32_t result;
--- lwres_uint32_t recvlength;
--- lwres_uint16_t authtype;
--- lwres_uint16_t authlength;
---};
---.Ed
---.Pp
---.Pp
---The elements of this structure are:
---.Bl -tag -width recvlength
---.It Li length
---the overall packet length, including the entire packet header.
---This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
---calls.
---.It Li version
---the header format. There is currently only one format,
---.Dv LWRES_LWPACKETVERSION_0 .
---This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
---calls.
---.It Li pktflags
---library-defined flags for this packet: for instance whether the packet
---is a request or a reply. Flag values can be set, but not defined by
---the caller.
---This field is filled in by the application wit the exception of the
---LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the
---lwres_gabn_*() and lwres_gnba_*() calls.
---.It Li serial
---is set by the requestor and is returned in all replies. If two or more
---packets from the same source have the same serial number and are from
---the same source, they are assumed to be duplicates and the latter ones
---may be dropped.
---This field must be set by the application.
---.It Li opcode
---indicates the operation.
---Opcodes between 0x00000000 and 0x03ffffff are
---reserved for use by the lightweight resolver library. Opcodes between
---0x04000000 and 0xffffffff are application defined.
---This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
---calls.
---.It Li result
---is only valid for replies.
---Results between 0x04000000 and 0xffffffff are application defined.
---Results between 0x00000000 and 0x03ffffff are reserved for library use.
---This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
---calls.
---.It Li recvlength
---is the maximum buffer size that the receiver can handle on requests
---and the size of the buffer needed to satisfy a request when the buffer
---is too large for replies.
---This field is supplied by the application.
---.It Li authtype
---defines the packet level authentication that is used.
---Authorisation types between 0x1000 and 0xffff are application defined
---and types between 0x0000 and 0x0fff are reserved for library use.
---Currently these are not used and must be zero.
---.It Li authlen
---gives the length of the authentication data.
---Since packet authentication is currently not used, this must be zero.
---.El
---.Pp
---The following opcodes are currently defined:
---.Bl -tag -width GETADDRSBYNAME
---.It Li NOOP
---Success is always returned and the packet contents are echoed.
---The lwres_noop_*() functions should be used for this type.
---.It Li GETADDRSBYNAME
---returns all known addresses for a given name.
---The lwres_gabn_*() functions should be used for this type.
---.It Li GETNAMEBYADDR
---return the hostname for the given address.
---The lwres_gnba_*() functions should be used for this type.
---.El
---.Pp
---.Fn lwres_lwpacket_renderheader
---transfers the contents of lightweight resolver packet structure
---.Dv lwres_lwpacket_t
---.Fa *pkt
---in network byte order to the lightweight resolver buffer,
---.Fa *b .
---.Pp
---.Fn lwres_lwpacket_parseheader
---performs the converse operation.
---It transfers data in network byte order from buffer
---.Fa *b
---to resolver packet
---.Fa *pkt .
---The contents of the buffer
---.Fa b
---should correspond to a
---.Dv "lwres_lwpacket_t" .
---.Pp
---Both functions have assertion checks to ensure that
---.Fa b
---and
---.Fa pkt
---are not
---.Dv NULL .
---.Sh RETURN VALUES
---Successful calls to
---.Fn lwres_lwpacket_renderheader
---and
---.Fn lwres_lwpacket_parseheader
---return
---.Er LWRES_R_SUCCESS .
---If there is insufficient space to copy data between the buffer
---.Fa *b
---and lightweight resolver packet
---.Fa *pkt
---both functions return
---.Er LWRES_R_UNEXPECTEDEND .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_resutil.3,v 1.4 2000/11/18 03:00:57 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt LWRES_RESUTIL 3
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm lwres_string_parse ,
---.Nm lwres_addr_parse ,
---.Nm lwres_getaddrsbyname ,
---.Nm lwres_getnamebyaddr
---.Nd lightweight resolver utility functions
---.Sh SYNOPSIS
---.Fd #include <lwres/lwres.h>
---.Fd
---.Ft lwres_result_t
---.Fo lwres_string_parse
---.Fa "lwres_buffer_t *b"
---.Fa "char **c"
---.Fa "lwres_uint16_t *len"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_addr_parse
---.Fa "lwres_buffer_t *b"
---.Fa "lwres_addr_t *addr"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_getaddrsbyname
---.Fa "lwres_context_t *ctx"
---.Fa "const char *name"
---.Fa "lwres_uint32_t addrtypes"
---.Fa "lwres_gabnresponse_t **structp"
---.Fc
---.Ft lwres_result_t
---.Fo lwres_getnamebyaddr
---.Fa "lwres_context_t *ctx"
---.Fa "lwres_uint32_t addrtype"
---.Fa "lwres_uint16_t addrlen"
---.Fa "const unsigned char *addr"
---.Fa "lwres_gnbaresponse_t **structp"
---.Fc
---.Sh DESCRIPTION
---.Fn lwres_string_parse
---retrieves a DNS-encoded string starting the current pointer of
---lightweight resolver buffer
---.Fa b :
---i.e.
---.Li b->current .
---When the function returns, the address of the first byte of the
---encoded string is returned via
---.Fa *c
---and the length of that string is given by
---.Fa *len .
---The buffer's current pointer is advanced to point at the character
---following the string length, the encoded string, and the trailing
---.Dv NULL
---character.
---.Fn lwres_string_parse
---has an assertion check that
---.Fa b
---is not
---.Dv NULL .
---.Pp
---.Fn lwres_addr_parse
---extracts an address from the buffer
---.Fa b .
---It checks that
---.Fa addr
---is not null.
---The buffer's current pointer
---.Li b->current
---is presumed to point at an encoded address: the address preceded by a
---32-bit protocol family identifier and a 16-bit length field.
---The encoded address is copied to
---.Li addr->address
---and
---.Li addr->length
---indicates the size in bytes of the address that was copied.
---.Li b->current
---is advanced to point at the next byte of available data in the buffer
---following the encoded address.
---.Pp
---.Fn lwres_getaddrsbyname
---and
---.Fn lwres_getnamebyaddr
---use the
---.Dv "lwres_gnbaresponse_t"
---structure defined below:
---.Bd -literal -offset indent
---typedef struct {
--- lwres_uint32_t flags;
--- lwres_uint16_t naliases;
--- lwres_uint16_t naddrs;
--- char *realname;
--- char **aliases;
--- lwres_uint16_t realnamelen;
--- lwres_uint16_t *aliaslen;
--- lwres_addrlist_t addrs;
--- void *base;
--- size_t baselen;
---} lwres_gabnresponse_t;
---.Ed
---The contents of this structure are not manipulated directly but
---they are controlled through the
---.Xr lwres_gabn 3
---functions.
---.Pp
---The lightweight resolver uses
---.Fn lwres_getaddrsbyname
---to perform foward lookups.
---Hostname
---.Fa name
---is looked up using the resolver context
---.Fa ctx
---for memory allocation.
---.Fa addrtypes
---is a bitmask indicating which type of addresses are to be looked up.
---Current values for this bitmask are
---.Dv LWRES_ADDRTYPE_V4
---for IPv4 addresses and
---.Dv LWRES_ADDRTYPE_V6
---for IPv6 addresses.
---Results of the lookup are returned in
---.Fa *structp .
---.Fn lwres_getaddrsbyname
---checks that its pointer arguments are not
---.Dv NULL
---and that
---.Fa addrtypes
---is non-zero.
---.Pp
---.Fn lwres_getnamebyaddr
---performs reverse lookups.
---Resolver context
---.Fa ctx
---is used for memory allocation.
---The address type is indicated by
---.Fa addrtype :
---.Dv LWRES_ADDRTYPE_V4
---or
---.Dv LWRES_ADDRTYPE_V6 .
---The address to be looked up is given by
---.Fa addr
---and its length is
---.Fa addrlen
---bytes.
---The result of the function call is made available through
---.Fa *structp .
---Like
---.Fn lwres_getaddrsbyname ,
---.Fn lwres_getnamebyaddr
---uses assertion checking to ensure its pointer arguments are not
---.Dv NULL
---and
---.Fa addrtype
---is not zero.
---.Fn lwres_getaddrsbyname
---also checks that
---.Fa addrlen
---is non-zero.
---.Sh RETURN VALUES
---Successful calls to
---.Fn lwres_string_parse
---and
---.Fn lwres_addr_parse
---return
---.Er LWRES_R_SUCCESS.
---Both functions return
---.Er LWRES_R_FAILURE
---if the buffer is corrupt or
---.Er LWRES_R_UNEXPECTEDEND
---if the buffer has less space than expected for the components of the
---encoded string or address.
---.Pp
---.Fn lwres_getaddrsbyname
---returns
---.Er LWRES_R_SUCCESS
---on success and it returns
---.Er LWRES_R_NOTFOUND
---if the hostname
---.Fa name
---could not be found.
---.Pp
---.Er LWRES_R_SUCCESS
---is returned by a successful call to
---.Fn lwres_getnamebyaddr .
---.Pp
---Both
---.Fn lwres_getaddrsbyname
---and
---.Fn lwres_getnamebyaddr
---return
---.Er LWRES_R_NOMEMORY
---when memory allocation requests fail and
---.Er LWRES_R_UNEXPECTEDEND
---if the buffers used for sending queries and receiving replies are too
---small.
---.Sh SEE ALSO
---.Xr lwres_buffer 3 ,
---.Xr lwres_gabn 3 .
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_sethostent.3,v 1.4 2000/11/18 03:00:58 bwelling Exp $
---
---.so lwres_gethostent.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_sethostent_r.3,v 1.4 2000/11/18 03:00:59 bwelling Exp $
---
---.so lwres_gethostent.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: lwres_string_parse.3,v 1.4 2000/11/18 03:01:00 bwelling Exp $
---
---.so lwres_resutil.3
+++ /dev/null
---.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
---.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
---.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
---.\" INTERNET SOFTWARE CONSORTIUM 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: resolver.5,v 1.2 2000/11/18 02:57:31 bwelling Exp $
---
---.Dd Jun 30, 2000
---.Dt RESOLVER 5
---.Os BIND9 9
---.ds vT BIND9 Programmer's Manual
---.Sh NAME
---.Nm resolver
---.Nd resolver configuration file
---.Sh SYNOPSIS
---.Pa /etc/resolv.conf
---.Sh DESCRIPTION
---The
---.Nm resolver
---and
---.Nm "BIND9 lightwreight resolver"
---are sets of routines in the C library and BIND9 library respectively
---that provide access to the Internet Domain Name System.
---The resolver configuration file,
---.Pa /etc/resolv.conf ,
---is normally gets read
---by the resolver and lightweight resolver
---routines to initialise low-level resolver data structures the first time
---that a process invokes those routines.
---The file contains a list of
---keywords with values that provide various types of
---information, such as the IP addresses of the servers that should be
---used when making lookup requests.
---.Pp
---Each keyword and value must appear on a single line.
---The value follows the keyword, separated by white space.
---The hash character '#' or semi-colon ';' introduce comments.
---Anything from either of these characters to the end of the line
---is treated as a comment and ignored.
---.\" XXXJR - Don't think the next para is relevant. Not every host will run
---.\" a name server or lightweight resolver. Those that don't will need
---.\" a resolv.conf so they can send their lookups somewhere sensible.
---.\".Pp
---.\"On a normally configured system, this file should not be necessary.
---.\"The only name server to be queried will be on the local machine,
---.\"the domain name is determined from the host name,
---.\"and the domain search path is constructed from the domain name.
---.Pp
---The available configuration directives are:
---.Bl -tag -width "nameserver"
---.It Li nameserver
---Internet address of a name server that the resolver should query.
---The IP address of the server can be supplied in the usual notation:
---either in dotted-decimal form for an IPv4 addess or in double colon
---form described in RFC1884 for an IPv6 address.
---Up to three nameserver directives can be listed.
---See
---.Dv LWRES_CONFMAXNAMESERVERS
---in
---.Pa <lwres/lwres.h> .
---If more than
---.Dv LWRES_CONFMAXNAMESERVERS
---nameserver directives are present in the file,
---only the first three are used.
---Any others are ignored.
---.Pp
---When there are multiple servers, the resolver
---library queries them in the order listed.
---If no
---.Li nameserver
---entries are present, the default is to attempt to use the name server or
---lightweight resolver daemon on the local machine.
---The algorithm used is to try a server, and if the query times out,
---try the next, until out of name servers,
---then repeat trying all the name servers
---until a maximum number of retries are made.
---.It Li domain
---Local domain name.
---Most queries for names within this domain can use short names
---relative to the local domain.
---When no
---.Li domain
---entry is present, the domain is determined from the local host name returned by
---.Xr gethostname 2 ;
---the domain part is taken to be everything after the first
---.Sq \&. .
---Finally, if the host name does not contain a domain part, the root
---domain is assumed.
---.It Li search
---Search list for host-name lookup.
---The search list is normally determined from the local domain name;
---by default, it contains only the local domain name.
---This may be changed by listing the desired domain search path
---following the
---.Li search
---keyword with spaces or tabs separating the names.
---Most resolver
---queries will be attempted using each component
---of the search path in turn until a match is found.
---Note that this process may be slow and will generate a lot of network
---traffic if the servers for the listed domains are not local,
---and that queries will time out if no server is available
---for one of the domains.
---.Pp
---The search list is currently limited to eight domains
---with a total of 256 characters.
---See
---.Dv LWRES_CONFMAXSEARCH
---and
---.Dv LWRES_CONFMAXLINELEN
---in
---.Pa lwres/lwres.h .
---.It Li sortlist
---Allows addresses returned by gethostbyname to be sorted.
---A
---.Li sortlist
---is specified by IP address netmask pairs.
---The netmask is optional and defaults to the natural netmask of the net.
---The IP address and optional network pairs are separated by slashes.
---Up to 10 pairs may be specified.
---For example:
---.Bd -literal -offset indent
---sortlist 130.155.160.0/255.255.240.0 130.155.0.0
---.Ed
---.It Li options
---Allows certain internal
---.Nm resolver
---variables to be modified.
---The syntax is
---.D1 Li options Ar option ...
---where
---.Ar option
---is one of the following:
---.Bl -tag -width "no_tld_query"
---.It Li ndots: Ns Ar n
---sets a threshold for the number of dots which
---must appear in a name given to
---.Fn res_query
---(see
---.Xr resolver 3 )
---before an
---.Em initial absolute query
---will be made.
---The default for
---.Ar n
---is
---.Dq 1 ,
---meaning that if there are
---.Em any
---dots in a name, the name will be tried first as an absolute name before any
---.Em search list
---elements are appended to it.
---Acceptable values of
---.Ar n
---are between 0 and 255 inclusive.
---.It debug
---enables debugging traces for the resolver
---XXXJR if anything actually looked at
---.Dv confdata->resdebug .
---At present the option is just recognised but not used by
---the BIND9 implementation.
---.It no_tld_query
---tells the resolver not to attempt to resolve a
---top level domain name, i.e. a name containing no dots.
---Use of this option does not prevent the resolver from obeying the
---standard
---.Ar domain
---and
---.Ar search
---rules with the given name.
---XXXJR At present this option is recognised but is otherwise unused
---in BIND9.
---.It missing
---XXXJR what about the other BIND8 resolver options like rotate and
---timeout? Shouldn't these be provided for backwards compatibility?
---.El
---.El
---.Pp
---The
---.Li domain
---and
---.Li search
---keywords are mutually exclusive.
---If more than one instance of these keywords is present,
---the last instance wins.
---.Sh FILES
---.Pa /etc/resolv.conf
---.Pa <lwres/lwres.h>
---.Sh SEE ALSO
---.Xr gethostbyname 3 ,
---.Xr lwres_config 3 ,
---.Xr lwres 3 ,
---.Xr resolver 3 ,
---.Xr hostname 7 ,
---.Xr lwresd 8 ,
---.Xr named 8 ,
---"BIND9 Administrators Manual".
---.Sh BUGS
---Unrecognised directives and syntax errors in
---.Pa /etc/resolv.conf
---are usually silently ignored, though
---.Er LWRES_R_FAILURE
---can be returned by the lightweight resolver functions described in
---.Xr lwres_config 3
---which parse this file.
projects / thirdparty / bind9.git / commitdiff
