+++ /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 $
-
-.\"
-.\" $Id: host.1,v 1.3 2000/08/01 01:18:42 tale 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 aCdlrTwv
--.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,
-It can also be a dotted-decimal string representing an IPv4 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
-before the root name servers are queried for that name.
-The default number of dots is zero.
-Unlike previous versions of
-.Nm host ,
-the BIND9 implementation does not append domain names from the
--.Dv domain
- directive in
-or
-.Dv search
-directives in
--.Pa /etc/resolv.conf .
-Therefore
-.Ar name
-should be a fully-qualified domain name.
--.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
-This should mean that the name server receiving the query will not attemp
--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.
-TCP queries will be automatically made when the query type requires
-that a TCP connection: zone transfer (AXFR) requests for example.
--.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
-By default it looks for A records unless the
--.Fl C
- option was given, queries will be made for SOA records,
- and if
-option is supplied or
--.Ar name
- is a dotted-decimal IPv4 address or colon-delimited IPv6 address,
-is a dotted-decimal IPv4 address.
-These will make
--.Nm host
- will query for PTR records.
-look for SOA and PTR records respectively.
--.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 .
-.Sh BUGS
-.Nm host
-does not yet know how to handle command line arguments that are IPv6
-addresses, even though the record types for those addresses are
-fully supported by the BIND9 DNS library.
-.Pp
-Apart from this self-contradicting sentence, the
-.Fl D
-option is undocumented.
+++ /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 $
-
-.\"
-.\" $Id: dnssec-keygen.8,v 1.7 2000/08/01 01:18:49 tale 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 $
-
-.\"
-.\" $Id: dnssec-makekeyset.8,v 1.8 2000/08/01 01:18:50 tale 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 $
-
-.\"
-.\" $Id: dnssec-signkey.8,v 1.9 2000/08/01 01:18:51 tale 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.16 2000/12/07 02:20:07 bwelling Exp $
-
-.\"
-.\" $Id: dnssec-signzone.8,v 1.11 2000/08/01 01:18:52 tale 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 c Ar cycle-time
--.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
- .Op Fl n Ar nthreads
--.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
-.Fl c
-option, which specifies the cycle period as an offset from the current time
-(in seconds). If a SIG record expires after the cycle period, 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
-The default cycle period 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
-by default, with a cycle period 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
-.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 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.
-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
--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.
- .Pp
- The
- .Fl n
- option can be used to change the threading behavior. By default,
- .Nm dnssec-signzone
- attempts to determine the number of CPUs present, and create one thread
- per CPU. The
- .Fl n
- option causes a different number of threads to be created.
--.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 $
-
-.\"
-.\" $Id: lwresd.8,v 1.6 2000/08/01 01:18:43 tale 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 query-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#
-.Ar query-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 p
-listen for lightweight resolver queries on the loopback interface
-using UDP port
-.Ar port#
-instead of the default port number, 921.
--.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 $
-
-.\"
-.\" $Id: named.8,v 1.5 2000/08/01 01:18:44 tale 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
-.Nd Internet domain name server (DNS)
--.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.
-is the ISC implementation of an Internet domain name server.
-See RFCs 1033, 1034, and 1035 for more information on the Internet
-domain name system.
-For historical reasons, the ISC's DNS software is known as BIND -
-Berkeley Internet Name Daemon - because it was originally
-supplied with BSD
-.Ux
-releases.
--.Pp
- When invoked without arguments,
-Without any arguments,
--.Nm named
--will read the default configuration file
--.Pa /etc/named.conf ,
--read any initial data, and listen for queries.
-It is also possible to use the BIND9 name server
-as a lightweight resolver server
-.Nm lwresd .
-However when operating as a lightweight resolver server,
-.Nm named
-is functionally and logically distinct from a
-conventional name server.
-More information can be found in
-.Xr lwresd 8 .
-.Pp
-Although some command-line options can be used with
-.Nm named ,
-the name server's behaviour is mainly controlled by its configuration file,
-.Pa /etc/named.conf .
-Refer to the BIND9 Administrator Reference Manual for further details.
--.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 named.conf 5 ,
-.Xr zonefile 5 ,
--.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 $
-
-.\"
-.\" $Id: nsupdate.8,v 1.4 2000/08/01 01:18:45 tale 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
-A single update request could 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.
-conflict with dynamic updates or the name server's transaction log
-activities which keep the file copy of the zone consistent with its
-internal representation in the name server's memory.
--.Pp
- The resource records that are dynamically added or removed with
-The names of 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
-.Dv key{}
--and
- .Dv server
-.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
-and
--.Fl k
- option to provide the shared secret needed to generate a TSIG record
-options to provide the shared secret needed to generate a TSIG record
--for authenticating Dynamic DNS update requests.
--These options are mutually exclusive.
- With the
-The
--.Fl k
- option,
-option gets
--.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
-to read the shared secret from the file
-.Ar keyfile .
-When the
--.Fl y
- option is used, a signature is generated from
-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.
-is a string comprising the shared secret, typically written in base-64
-encoding.
--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.
-This may be preferable when a batch of update requests are made.
--.Sh INPUT FORMAT
--.Nm nsupdate
- reads input from
- .Ar filename
- or standard input.
-reads commands from its 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.
-and one 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.
-will determine the correct zone to update based on the rest of the input
-data if no
-.Va zone
-statement is provided.
--.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).
-exists 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
-.Va type Op data...
--.Xc
--.sp 1
- This requires that a resource record of the specified
-This requires that a resource record of the specified type
--.Va type ,
--.Va class
- and
-and name
--.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
-If
--.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
-is supplied, it has to exactly match the corresponding RDATA for
-.Va name .
--.Va data
- are written in the standard text representation of the resource record's
-is 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 NAME SERVER PROCESSING
--.Pp
-When a successful update request is made, the BIND9 name server
-increments the serial number in the zone's SOA record.
-A transaction log file is written containing details of the resource
-records that have been added or removed.
-This allows the name server to roll forward to the current state of the
-zone if it is restarted before a fresh copy of the zone file is written
-out by the name server.
-XXXJR WHEN DOES IT DO THAT???
-It then sends a NOTIFY message to the zone's slave servers to inform
-them that the zone's contents have changed.
--.Sh FILES
--.Bl -tag -width K{name}.+157.+{random}.private -compact
- .It Pa /etc/resolv.conf
- used to identify default name server
-.It Pa /etc/named.conf
-name server configuration file
--.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.
-The
-.Fl D
-and
-.Fl M
-options are not documented apart from this self-referential paragraph.
-They provide additional debugging information which is primarily of interest
-to the BIND9 developers.
-These options might be changed or removed 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 $
-
-.\"
-.\" $Id: rndc.8,v 1.8 2000/08/01 01:18:46 tale 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
-.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
-.Dv options{}
--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
-.Dv server{}
--statement of the server being used, or if no
- .Dv server
-.Dv server{}
--statement is present for that host, then the
--.Dv default-key
--clause of the
- .Dv options
-.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
-The only valid value for
-.Ar command
-is \*qreload\*q, which forces the name server to reload its configuation
-file and zones.
-Further commands will be provided in future releases as the management
-capabilities of
--.Nm rndc
- without arguments to see its help message.
- .Pp
-are extended.
--.Sh LIMITATIONS
--.Nm rndc
- does not yet support all the commands of the BIND 8
-currently only supports the
-.Dv reload
-command.
-Future releases will provide more commands so that
-.Nm rndc
-offers at least as many management capabilities as the old
--.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.9 2000/12/15 00:24:10 gson Exp $
-
-.\"
-.\" $Id: rndc.conf.5,v 1.6 2000/08/01 01:18:48 tale 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
-.Dv options{}
--statement, a
- .Dv server
-.Dv server{}
--statement and a
- .Dv key
-.Dv key{}
--statement.
--.Pp
--The
- .Dv options
-.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
-.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
-.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
-.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
-.Dv key{}
--statement in the file.
--.Pp
--The
- .Dv key
-.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
-.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
-.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 NAME SERVER CONFIGURATION
- The name server must be configured to accept
- .Xr rndc
- connections and to recognize the key specified in
- the
- .Nm rndc.conf
- file, using the
- .Dv controls
- statement in
- .Nm named.conf .
- See the sections on the
- .Dv controls
- statement in the BIND 9 Administrator Reference Manual for
- details.
--.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
-.Dv server{}
--statement and a
--.Dv default-port
--clause to the
- .Dv options
-.Dv options{}
--statement.
--.Sh SEE ALSO
--.Xr rndc 8 ,
-.Xr named.conf 8 ,
--.Xr dnssec-keygen 8 ,
--.Xr mmencode 1 ,
- "BIND 9 Administrator Reference Manual".
-"BIND9 Administrators Manual".
+++ /dev/null
--Copyright (C) 2000 Internet Software Consortium.
- See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
-See COPYRIGHT in the source root or http://www.isc.org/copyright 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 $
-$Id: cvs-usage,v 1.4 2000/08/01 01:18:22 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: lwres.3,v 1.8 2000/12/04 18:37:35 gson Exp $
-
-.\"
-.\" $Id: lwres.3,v 1.3 2000/08/01 01:20:24 tale 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
-.Nd introduction to the lightweight resolver
--.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
-The lightweight resolver provides a simple way for clients to perform
-forward and reverse lookups.
-Instead of looking up the names or addresses directly, clients can send
-requests to the lightweight 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
-which does hard work of performing the lookups for them.
-Clients can just use the lightweight resolver library to format a
-request to get a hostname for an IP address or vice versa, send it to
--.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.
-and wait for a response.
--.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.
-The lightweight resolver in BIND 9 consists of three components:
-a client, a server and a protocol.
-Clients use the functions provided by the lightweight resolver library
-to encode requests and decode responses.
-The server for the lightweight resolver is
-.Nm lwresd .
-In reality this is implemented by the name server,
-.Nm named ,
-though when operating as the lightweight resolver server,
-.Nm lwresd
-is functionally and logically distinct from the actual name server.
-The protocol consists of a number of opcodes, each of which has a
-request and response structure associated with it.
-The lightweight resolver library contains functions to convert these
-structures to and from the canonical format whenver they are sent to
-.Nm lwresd .
-.Sh RATIONALE
--.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.
-Conventional DNS lookups of hostnames and IPv4 addresses are usually
-simple and straightforward.
-A client can issue queries to map a hostname to an IPv4 address or
-from an IPv4 address to a hostname.
-Many DNS queries can be needed to lookup IPv6 addresses.
-It may be necessary to resolve potentially variable-length partial
-IPv6 addresses: aggregation and site-level identifiers for instance.
-Keeping track of all of these queries and assembling the answers to
-return the hostname or IPv6 address is very hard work and error-prone.
-Further complexity can be caused by DNAME chains.
-If the answers are signed using DNSSEC, additional queries may be needed
-to verify the signatures.
-The consequence of this is that clients can be overwhelmed with the
-amount of work needed to resolve IPv6 addresses.
-BIND9 provides a lightweight resolver to eliminate these problems if
-applications had to resolve IPv6 addresses for themselves.
--.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.
-Instead of looking up the hostnames or IPv6 addresses directly, clients
-can use the lightweight resolver to get the name server to do the work.
-Clients construct simple questions like \*qwhat is the hostname for
-the following address?\*q or \*qwhat are the addresses of hostname
-.Dv host.example.com?\*q
-The lightweight resolver functions take these questions and format
-them into queries which are sent to
-.Nm lwresd .
-Replies from the lightweight resolver server are then decoded to return
-an answer to the client which made the original request.
-.Sh CANONICAL FORMAT
--.Pp
- (2) Process the request in the data specific type.
-The lightweight resolver's canonical data format has been arranged for
-efficiency.
-All integer values are in network byte order.
-Addresses are also in network byte order.
-This means that, at least for IPv4 and IPv6 addresses, they can be
-used directly in network system calls without needing to be byte
-swapped.
-Character strings get prefixed by a length and are always terminated
-with a
-.Dv NUL
-character.
-This simplifies structure handling and parsing for both the server
-receiving a request and the client receiving a reply.
-It also eliminates data copying by enabling a mapping structure to
-directly point at data in the actual receive buffer.
-.Sh OPCODES
--.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.
-Every lightweight resolver operation uses a unique opcode.
-Each opcode is assigned a number.
-Opcodes in the range 0x00000000 and 0x03ffffff are reserved for use by
-the lightweight resolver library.
-Opcodes between 0x04000000 and 0xffffffff have been set aside for use by
-applications.
--.Pp
- (4) Call the data specific rendering function, such as
- lwres_gabnresponse_render().
-Three opcodes are currently defined:
-.Bl -tag -width LWRES_OPCODE_GETADDRSBYNAME
-.It Li LWRES_OPCODE_NOOP
-The no-op opcode is essentially an echo operation, comparable to
-.Xr ping 1 .
-The server simply returns the entire data region that had been sent by
-the client.
-Therefore clients can use this opcode to determine if the server is
-operational or not.
-It can also be used by clients to check the version number and any
-parameters of the lightweight resolver protocol that are supported by the
-server.
-.It Li LWRES_OPCODE_GETADDRSBYNAME
-This opcode is used to get all the known addresses for a hostname.
-In principle, this could also return information from NIS/YP or
-.Pa /etc/hosts ,
-though this is not implemented yet.
-Flags can be set in the request structure that is used for this opcode
-to indicate whether IPv4 or IPv6 addresses or both should be returned.
-.It Li LWRES_OPCODE_GETNAMEBYADDR
-This provides the complementary operation to
-.Dv LWRES_OPCODE_GETADDRSBYNAME .
-It returns the hostname for the address that was supplied in the
-request structure.
-.El
-.\"
-.\" XXXJR
-.\" We don't need this section, at least not yet. 23/6/00
-.\"
-.\" .Sh OPCODE REPLIES
-.\" .Pp
-.\" Replies to lightweight resolver operations contain return codes.
-.\" Results between 0x04000000 and 0xffffffff are application defined.
-.\" The lightweight resolver library reserves result codes between
-.\" 0x00000000 and 0x03ffffff.
-.\" These occupy the same reserved range used for ISC return values that
-.\" are defined in
-.\" .Pa isc/resultclass.h .
-.\" This means that, if appropriate, it would be trivial to map those ISC
-.\" return values to lightweight resolver packet result codes.
-.Sh STRUCTURE AND PACKET ENCODING/DECODING
-Each opcode has two structures: one for the request and one for the
-response.
-Clients use the lightweight resolver functions to construct the
-request structure and send it to the name server.
-The name server decodes the request, carries out the operation and
-fills in an opcode-specific response structure which is returned to
-the client.
--.Pp
- (5) Send the resulting packet to the client.
-For every opcode, three functions operate on these structures.
-A
-.Ar render
-function converts the structure to canonical form and a
-.Ar parse
-function translates from the canonical form to the op-code specific
-structure.
-Memory allocated to the opcode's request or reply structures is
-discarded using the
-.Ar free
-function.
-Clients will typically use the op-code specific
-.Ar xxx_request_render ,
-.Ar xxx_response_parse
-and
-.Ar xxx_response_free
-functions.
-The name server will use the
-.Ar xxx_request_parse ,
-.Ar xxx_response_render
-and
-.Ar xxx_request_free
-functions.
--.Pp
-For example, the no-op opcode -
-.Dv LWRES_OPCODE_NOOP
-- uses
-.Dv lwres_nooprequest_t
-and
-.Dv lwres_noopresponse_t
-structures for the requests and responses used in the no-op operation.
-.Fn lwres_nooprequest_render
-takes a
-.Dv lwres_nooprequest_t
-structure and converts into a packet in lightweight resolver canonical
-format.
-Similarly
-.Fn lwres_noopresponse_render
-converts a
-.Dv lwres_noopresponse_t
-structure into a packet in lightweight resolver canonical format.
-.Fn lwres_nooprequest_parse
-takes a packet in canonical format and fills in a corresponding
-.Dv lwres_nooprequest_t
-structure.
-A
-.Dv lwres_noopresponse_t
-structure is set up by\p
-passing a response packet in canonical format to
-.Fn lwres_noopresponse_render .
-.Fn lwres_nooprequest_free
-and
-.Fn lwres_noopresponse_free
-releases the memory allocated to the
-.Dv lwres_nooprequest_t
-and
-.Dv lwres_noopresponse_t
-structures respectively.
-.\"
-.\" XXXJR
-.\" NOT YET.
-.\" This is just a placeholder to indicate where the section on the
-.\" lwres security API should be documented once this is implemented.
-.\" There's no point in documenting vapourware, especially if the
-.\" API is likely to change between now and then. 23/6/00
-.\" .Sh SECURITY
-.\" The lightweight resolver provides hooks for requesting the use of
-.\" DNSSEC for authenticating requests and responses.
-.\" This interface is not currently implemented and is likely to
-.\" change.
-.\" It is mentioned here to indicate the capabilities that can be expected
-.\" in future releases of the lightweight resolver.
-.\" .Pp
-.\" The following flag bits have been allocated.
-.\" .Bl -tag -width LWRES_FLAG_TRUSTNOTREQUIRED
-.\" .It Li LWRES_FLAG_TRUSTDEFAULT
-.\" Let the server decide whether to use DNSSEC or not.
-.\" .It Li LWRES_FLAG_TRUSTNOTREQUIRED
-.\" DNSSEC authentication of the DNS queries and replies is not required
-.\" .It Li LWRES_FLAG_TRUSTREQUIRED
-.\" Any DNSSEC data found when resolving the query must validate and the
-.\" server must be DNSSEC-aware.
-.\" .It Li LWRES_FLAG_TRUSTRESERVED
-.\" Reserved for future use.
-.\" .El
-.Sh CLIENT SETUP
-Every client that uses the lightweight resolver needs to create and
-maintain its own state.
-Library calls are provided to manage that data structure, a resolver
-context.
-If the client uses threads, it either has to provide its own locking
-primitives on that context structure or else create a context for each
-thread.
-See
-.Xr lwres_context 3 .
-Once the context has been created,
-.Fn lwres_conf_init
-is called to read
-.Pa /etc/resolv.conf
-so that various options such as sort lists, search lists and so on can
-be applied.
-.Sh CLIENT INTERFACE
-The simplest interface to the lightweight resolver is provided by
-.Fn lwres_getaddrsbyname
-and
-.Fn lwres_getnamebyaddr .
-These functions are blocking calls.
-A client will wait after sending a request until either a response is
-returned or else a timeout interval occurs.
-If non-blocking operations are required, the client will need to
-call the opcode-specific
-.Ar request_render
-and
-.Ar response_parse
-directly.
-.Sh SERVER INTERFACE
-Service for the lightweight resolver is provided by the lightweight
-resolver daemon,
-.Nm lwresd .
-It listens on port number 921 of the loopback interface and expects to
-receive packets in the lightweight resolver's canonical format
-described above.
--.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 .
-.Xr lwres_getipnode 3
-.Xr lwresd 8 ,
-.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: lwres_addr_parse.3,v 1.4 2000/11/18 02:59:13 bwelling Exp $
-
-.\"
-.\" $Id: lwres_addr_parse.3,v 1.3 2000/08/01 01:20:25 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer.3,v 1.3 2000/08/01 01:20:26 tale 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.
-These functions use the following structure as a buffer descriptor to
-manage the actual storage:
-.Bd -literal -offset indent
-typedef struct lwres_buffer lwres_buffer_t;
-struct lwres_buffer {
- unsigned int magic;
- unsigned char *base;
- /* The following integers are byte offsets from 'base'. */
- unsigned int length;
- unsigned int used;
- unsigned int current;
- unsigned int active;
-};
-.Ed
-The main reason for making the buffer structure public is so that
-buffer operations can be implemented using macros.
-Applications should not manipulate this structure directly.
-They should use the functions listed below.
--.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
-Except for
-.Fn lwres_buffer_init ,
-all of the buffer managements functions contain an assertion check
-that
-.Fa b
-is a pointer to a valid lightweight resolver buffer.
--.Pp
--.Fn lwres_buffer_init
- initializes the
- .Dv lwres_buffer_t
-makes the
-.Dv "struct lwres_buffer"
-referenced by
--.Fa *b
- and assocates it with the memory region of size
-to be associated with a memory region of size
--.Fa length
--bytes starting at location
--.Fa base.
-The function checks that
-.Fa *b is not
-.Dv NULL .
--.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.
-The
-.Dv lwres_buffer_t
-.Fa *b
-is invalidated by
-.Fn lwres_buffer_invalidate .
-.Fa *b
-must be a valid lightweight resolver buffer.
--.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.
-.Fa *b
--.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 .
-.Li b->used .
--.Pp
- A buffer is re-initialised by
-A lightweight resolver buffer is re-initialised by
--.Fn lwres_buffer_clear .
--The function sets
- .Li used ,
- .Li current
-.Li b->used ,
-.Li b->current
--and
- .Li active
-.Li b->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).
-.Li b->current
-to zero: the start of the buffer.
--.Pp
- .Fn lwres_buffer_forward
- increases the consumed region of buffer
-The consumed region of buffer
--.Fa *b
- by
-is increased by
--.Fa n
- bytes, checking for overflow.
-bytes
-using
-.Fn lwres_buffer_forward .
-The function checks for buffer overflow.
--Similarly,
--.Fn lwres_buffer_back
--decreases buffer
--.Fa b 's
--consumed region by
--.Fa n
- bytes and checks for underflow.
-bytes and checks for buffer underflow.
--.Pp
--.Fn lwres_buffer_getuint8
--reads an unsigned 8-bit integer from
--.Fa *b
--and returns it.
-The function checks that it does not read past the end of the buffer's
-consumed region.
--.Fn lwres_buffer_putuint8
--writes the unsigned 8-bit integer
--.Fa val
--to buffer
--.Fa *b .
-It checks that the buffer has available space for
-.Fa val .
--.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 .
-except that they respectively read an unsigned 16-bit or 32-bit integer from
-.Fa b
-converting it from network byte order to host byte order before
-returning its value.
--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.
-converting it from host byte order to 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 .
-For both functions,
-.Fa base
-should point to at least
-.Fa length
-bytes of valid memory.
-.Fa base
-.Sh RETURN VALUES
-.Fn lwres_buffer_getuint8 ,
-.Fn lwres_buffer_getuint16
-and
-.Fn lwres_buffer_getuint32
-return an 8-, 16- or 32-bit unsigned integer respectively from the
-current offset in buffer
-.Fa b .
-The 16- and 32-bit quantities are presented in host byte order even
-though they are stored in network byte order inside the buffer.
--.Sh SEE ALSO
-.Sh BUGS
-Buffers have no synchronization.
-Clients must ensure exclusive access for thread-safe operations.
+++ /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 $
-
-.\"
-.\" $Id: lwres_buffer_add.3,v 1.3 2000/08/01 01:20:27 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_back.3,v 1.3 2000/08/01 01:20:28 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_clear.3,v 1.3 2000/08/01 01:20:29 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_first.3,v 1.3 2000/08/01 01:20:30 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_forward.3,v 1.3 2000/08/01 01:20:31 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_getmem.3,v 1.3 2000/08/01 01:20:33 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_getuint16.3,v 1.3 2000/08/01 01:20:34 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_getuint32.3,v 1.3 2000/08/01 01:20:35 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_getuint8.3,v 1.3 2000/08/01 01:20:36 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_init.3,v 1.3 2000/08/01 01:20:37 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_invalidate.3,v 1.3 2000/08/01 01:20:38 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_putmem.3,v 1.3 2000/08/01 01:20:39 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_putuint16.3,v 1.3 2000/08/01 01:20:40 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_putuint32.3,v 1.3 2000/08/01 01:20:41 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_putuint8.3,v 1.3 2000/08/01 01:20:42 tale 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 $
-
-.\"
-.\" $Id: lwres_buffer_subtract.3,v 1.3 2000/08/01 01:20:43 tale 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_get.3,v 1.4 2000/11/18 02:59:35 bwelling Exp $
-
-.\"
-.\" $Id: lwres_conf_get.3,v 1.3 2000/08/01 01:20:46 tale 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 $
-
-.\"
-.\" $Id: lwres_conf_init.3,v 1.3 2000/08/01 01:20:47 tale 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 $
-
-.\"
-.\" $Id: lwres_conf_parse.3,v 1.3 2000/08/01 01:20:48 tale 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 $
-
-.\"
-.\" $Id: lwres_conf_print.3,v 1.3 2000/08/01 01:20:50 tale 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 $
-
-.\"
-.\" $Id: lwres_config.3,v 1.3 2000/08/01 01:20:51 tale 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 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 $
-
-.\"
-.\" $Id: lwres_context.3,v 1.3 2000/08/01 01:20:52 tale 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
-.Nd lightweight resolver memory allocation routines
--.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
-.Fo lwres_context_nextserial
--.Fa "lwres_context_t *ctx"
- .Fa "lwres_uint32_t serial"
--.Fc
--.Ft lwres_uint32_t
- .Fo lwres_context_nextserial
-.Fo lwres_context_initserial
--.Fa "lwres_context_t *ctx"
-.Fa "lwres_uint32_t serial"
--.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
-.Bd -literal -offset indent
-struct lwres_context {
- unsigned int timeout; /* time to wait for reply */
- lwres_uint32_t serial; /* serial number state */
- /*
- * For network I/O.
- */
- int sock; /* socket to send on */
- /*
- * Function pointers for allocating memory.
- */
- lwres_malloc_t malloc;
- lwres_free_t free;
- void *arg;
- /*
- * resolv.conf-like data
- */
- lwres_conf_t confdata;
-};
-
-typedef struct lwres_context lwres_context_t;
-.Ed
--.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
-is used to create a
--.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
-structure for use in lightweight resolver operations and associate
-general purpose memory allocation functions with that structure.
-.Fa *contextp
-is a pointer to a
-.Dv "struct lwres_context" .
-It must be non-NULL, which in turn implies that
-.Fa **contextp
-is also non-NULL.
--.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 free_function
-are pointers to the functions the context should use for allocating
-and freeing memory respectively.
-Both function pointers must either be non-NULL or NULL.
-It is not permitted to use a custom allocator - i.e
--.Fa malloc_function
- and a non-NULL
-is non-NULL -
-with a NULL
--.Fa free_function
--or vice versa.
- .Fa arg
- is passed as the first parameter to the memory
- allocation functions.
- If
- .Fa malloc_function
-If both function pointers are NULL, the lightweight resolver's
-internal allocation routines which call
-.Xr malloc 3
--and
- .Fa free_function
- are NULL,
- .Fa arg
- is unused and should be passed as NULL.
- .P
-.Xr free 3
-are used.
-.Fa arg
-is passed as the initial parameter to the memory
-allocation functions.
-The argument is passed but not used in the internal allocation
-and deallocation routines.
--Once memory for the structure has been allocated,
- it is initialized using
- .Xr lwres_conf_init 3
- and returned via
-.Xr lwres_conf_init 3
-is called to initialise it.
-The structure is then returned via
--.Fa *contextp .
--.Pp
- .Fn lwres_context_destroy
- destroys a
- .Dv "lwres_context_t" ,
- closing its socket.
- .Fa contextp
-A
-.Dv "struct lwres_context"
-is destroyed by
-.Fn lwres_context_destroy.
-.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.
-It must be non-NULL, as should
-.Fa *contextp .
-If the context has an open socket, it is closed before the structure
-is discarded.
--.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
-The context's serial number is controlled with
--.Fn lwres_context_initserial
--and
--.Fn lwres_context_nextserial .
-Both require that
-.Fa ctx
-is not NULL.
--.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.
-returns the current serial number for the context and increments
-.Dv ctx->serial .
--.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 .
-It has assertion checks to ensure that
-.Fa mem
-is not null and
-.Fa len
-is not zero.
-.Pp
-If the lightweight resolver's memory allocation functions are used,
-.Fa len
-bytes in the allocated buffer will be set to '0xe5' on allocation
-or '0xa9' when they are freed.
--.Pp
--.Fn lwres_context_sendrecv
--performs I/O for the context
--.Fa ctx .
- Data are read and written from the context's socket.
-Data are read and written from the context's socket
-.Dv ctx->sock .
--It writes data from
--.Fa sendbase
- - typically a lightweight resolver query packet -
-- typically a DNS query -
--and waits for a reply which is copied to the receive buffer at
-.Fa recvbase .
-.Fa sendbase
-is a pointer to the
-.Fa sendlen
-bytes of data that are to be sent using
-.Xr sendto 2.
-Up to
-.Fn recvlen
-bytes of data that are returned by a call to
-.Xr recvfrom 2
-on the socket are copied to
--.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,
-could not be allocated, otherwise
--.Er LWRES_R_SUCCESS
- otherwise.
-is returned.
--.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.
-is returned if the
-.Xr recvfrom 2
-call times out.
--.Sh SEE ALSO
--.Xr lwres_conf_init 3 ,
--.Xr malloc 3 ,
- .Xr free 3
-.Xr free 3 ,
-.Xr close 2 ,
-.Xr memset 3 ,
-.Xr sendto 2 ,
-.Xr recvfrom 2 .
-.Sh BUGS
-The
-.Dv lwres_context_t
-structures and the functions which operate on them are not thread-safe.
+++ /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 $
-
-.\"
-.\" $Id: lwres_context_allocmem.3,v 1.3 2000/08/01 01:20:53 tale 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 $
-
-.\"
-.\" $Id: lwres_context_create.3,v 1.3 2000/08/01 01:20:54 tale 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 $
-
-.\"
-.\" $Id: lwres_context_destroy.3,v 1.3 2000/08/01 01:20:55 tale 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 $
-
-.\"
-.\" $Id: lwres_context_freemem.3,v 1.3 2000/08/01 01:20:56 tale 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 $
-
-.\"
-.\" $Id: lwres_context_initserial.3,v 1.3 2000/08/01 01:20:57 tale 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 $
-
-.\"
-.\" $Id: lwres_context_nextserial.3,v 1.3 2000/08/01 01:20:58 tale 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 $
-
-.\"
-.\" $Id: lwres_context_sendrecv.3,v 1.3 2000/08/01 01:20:59 tale 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 $
-
-.\"
-.\" $Id: lwres_endhostent.3,v 1.3 2000/08/01 01:21:00 tale 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 $
-
-.\"
-.\" $Id: lwres_endhostent_r.3,v 1.3 2000/08/01 01:21:01 tale 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 $
-
-.\"
-.\" $Id: lwres_freeaddrinfo.3,v 1.3 2000/08/01 01:21:02 tale 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 $
-
-.\"
-.\" $Id: lwres_freehostent.3,v 1.3 2000/08/01 01:21:04 tale 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 $
-
-.\"
-.\" $Id: lwres_gabn.3,v 1.3 2000/08/01 01:21:05 tale 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
-.Nd lightweight resolver getaddrbyname functions
--.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
-These functions implement the lightweight resolver's getaddrbyname opcode
-.Dv LWRES_OPCODE_GETADDRSBYNAME .
-They provide a forward lookup mechanism, mapping a hostname to its
-address or addresses.
-.Pp
--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> .
-.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 $
-
-.\"
-.\" $Id: lwres_gabnrequest_free.3,v 1.3 2000/08/01 01:21:06 tale 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 $
-
-.\"
-.\" $Id: lwres_gabnrequest_parse.3,v 1.3 2000/08/01 01:21:07 tale 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 $
-
-.\"
-.\" $Id: lwres_gabnrequest_render.3,v 1.3 2000/08/01 01:21:08 tale 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 $
-
-.\"
-.\" $Id: lwres_gabnresponse_free.3,v 1.3 2000/08/01 01:21:09 tale 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 $
-
-.\"
-.\" $Id: lwres_gabnresponse_parse.3,v 1.3 2000/08/01 01:21:10 tale 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 $
-
-.\"
-.\" $Id: lwres_gabnresponse_render.3,v 1.3 2000/08/01 01:21:11 tale 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 $
-
-.\"
-.\" $Id: lwres_gai_strerror.3,v 1.3 2000/08/01 01:21:12 tale 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 .
-.Fn gai_strerror
-returns a suitable error message for the error code
-.Fa ecode .
-The message \*qinvalid error code\*q is returned if
-.Fa ecode
-is out of range.
--The following error codes and their meaning are defined in
--.Aq Pa include/lwres/netdb.h .
-They can be returned by
-.Fn getaddrinfo .
--.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
-.Dv "struct addrinfo" used by
--.Fn lwres_getaddrinfo .
--.Sh SEE ALSO
- .Xr strerror 3 ,
-.Xr errno 2 ,
-.Xr perror 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 $
-
-.\"
-.\" $Id: lwres_getaddrinfo.3,v 1.3 2000/08/01 01:21:13 tale 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 #include <lwres/lwres.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
-the following structure is used
--.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
-and
--.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
-arguments 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.
-either a host name or a numeric host address string: a dotted decimal
-IPv4 address or an IPv6 hex 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.
-indicates which transport protocol is wanted: UDP or TCP.
--If
--.Li ai_protocol
--is zero the caller will accept any protocol.
--.It Li ai_flags
- Flag bits.
-sets some 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
-the
-.Dv non-NuLL
--.Fa hostname
- should be treated as a numeric string defining an IPv4 or IPv6 address
- and no name resolution should be attempted.
-should be treated as a numeric string defining an IPv4 or IPv6 address.
-This will prevent a numeric IPv4 address from being considered as a domain
-name when
-.Fn lwres_getaddrinfo
-is looking for IPv6 addresses or vice versa.
--.El
--.Pp
--All other elements of the
--.Dv "struct addrinfo"
--passed via
- .Fa hints
-.Fa arg
--must be zero.
--.Pp
- A
- .Fa hints
- of
-If
-.Fa arg
-is not supplied, a
--.Dv NULL
- is treated as if the caller provided a
-pointer should be given for this argument.
-It will be treated as if the caller provided an
--.Dv "struct addrinfo"
- initialized to zero with
-structure 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
-.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 ,
-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
-.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 bind 2
-.Xr connect 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 $
-
-.\"
-.\" $Id: lwres_getaddrsbyname.3,v 1.3 2000/08/01 01:21:15 tale 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 $
-
-.\"
-.\" $Id: lwres_gethostbyaddr.3,v 1.3 2000/08/01 01:21:16 tale 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 $
-
-.\"
-.\" $Id: lwres_gethostbyaddr_r.3,v 1.3 2000/08/01 01:21:17 tale 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 $
-
-.\"
-.\" $Id: lwres_gethostbyname.3,v 1.3 2000/08/01 01:21:18 tale 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 $
-
-.\"
-.\" $Id: lwres_gethostbyname2.3,v 1.3 2000/08/01 01:21:19 tale 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 $
-
-.\"
-.\" $Id: lwres_gethostbyname_r.3,v 1.3 2000/08/01 01:21:20 tale 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 $
-
-.\"
-.\" $Id: lwres_gethostent.3,v 1.3 2000/08/01 01:21:21 tale 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
-These functions define the interface to the lightweight resolver
-daemon \fPNOT IF IT IS GOING AWAY\fP
-for looking up hostnames and addresses. They are similar to the
-standard
--.Xr gethostent 3
- functions provided by most operating systems.
-functions provided by as part of the standard system software.
--They use a
--.Dv "struct hostent"
--which is usually defined in
- .Pa <namedb.h> .
-.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.
-are empty stub functions which do nothing.
-They are provided as placeholders so that calls to the system's
-.Xr gethostent 3
-functions can simply be #defined to their
-.Xr lwres_res_gethost
-equivalents.
-See
-.Pa lwres/netdb.h .
--.Pp
--.Fn lwres_gethostbyname
--and
--.Fn lwres_gethostbyname2
- look up the hostname
-lookup 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.
-Both functions call
-.Fn lwres_getipnodebyname
-to look up the hostname.
--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 .
-It calls
-.Fn lwres_getipnodebyaddr
-to do the reverse lookup.
-.Pp
--.Fn lwres_gethostbyname_r
--is a thread-safe function for forward lookups.
- If an error occurs, an error code is returned in
-It also calls
-.Fn lwres_getipnodebyname
-to lookup the hostname
-.Fa name .
-If
-.Fn lwres_getipnodebyname
-encounters an error, the 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"
-.Fn "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
-.Fn lwres_gethostbyaddr_r
-calls
-.Fn lwres_getipnodebyaddr
-to do the work.
-If this function encounters an error, the error code is returned in
--.Fa *error .
-Like
--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
-are not thread-safe because they free any memory that had been allocated
-in a previous call to those functions before they perform a lookup.
-They also set the global variable
--.Dv lwres_h_errno
- will contain one of the following error codes defined in
- .Pa <lwres/netdb.h> :
-when they return.
-The values of this variable are defined in
-.Pa lwres/netdb.h .
-The values and their meaning are defined as follows:
--.Bl -tag -width HOST_NOT_FOUND
-.It Li NETDB_INTERNAL
-Internal Error - see
-.Li errno
-.It Li NETDB_SUCCESS
-no problem
--.It Li HOST_NOT_FOUND
- The host or address was not found.
-Authoritative Answer Host not found
--.It Li TRY_AGAIN
- A recoverable error occurred, e.g., a timeout.
- Retrying the lookup may succeed.
-Non-Authoritive Answer Host not found, or
-.Dv SERVERFAIL
--.It Li NO_RECOVERY
- A non-recoverable error occurred.
-Non recoverable errors,
-.Dv FORMERR ,
-.Dv REFUSED ,
-or
-.Dv NOTIMP
--.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.
-Valid name, but no data record of requested type
-.It Li NO_ADDRESS
-no address, so look for MX record
--.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
-.DV errno
--to
--.Er ERANGE .
--.Sh SEE ALSO
--.Xr gethostent 3 ,
--.Xr lwres_getipnode 3 ,
--.Xr lwres_hstrerror 3
--.Sh BUGS
-Although
--.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.
-call thread-safe functions to perform lookups, these 3 functions
-are not thread-safe because they set the global variable
-.Dv lwres_h_errno
-which could
-overwritten if two or more threads called these functions
-simultaneously.
-They also release any memory that had been allocated in a previous call
-to these functions.
-This emulates the semantics of their equivalent functions in the
-system's
-.Xr gethostent 3
-functions which use a static buffer that gets overwritten in subsequent
-calls to those routines.
-.Pp
--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
-Although the above functions can be considered as drop-in replacements
-for their equivalents in the system software, there are limitations.
-The functions that are documented here only use the BIND9 lighweight
-resolver daemon
-That implies that they only use the DNS for host and address lookups.
-Therefore these functions do not perform lookups in
--.Pa /etc/hosts
-or in
-.Dv NIS/YP
--or
- .Dv NIS ,
- consequently the above functions don't, either.
-.Dv NIS+
-maps which could be supported by the operating system's
-.Xr gethostent 3
-functions.
+++ /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 $
-
-.\"
-.\" $Id: lwres_gethostent_r.3,v 1.3 2000/08/01 01:21:23 tale 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 $
-
-.\"
-.\" $Id: lwres_getipnode.3,v 1.3 2000/08/01 01:21:24 tale 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
-.Nd lookup functions for the lightweight resolver
--.Sh SYNOPSIS
- .Fd #include <lwres/netdb.h>
-.Fd #include <lwres/lwres.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
-These functions use a
--.Dv "struct hostent"
- which is defined in
- .Pa namedb.h :
-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 - usually
-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_getipnodebyname
- looks up addresses of protocol family
- .Fa af
- for the hostname
- .Fa name .
-looks up the hostname
-.Fa name
-of protocol family
-.Fa af .
--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:
-parameter sets bits that indicate how IPv6 and IPv4 addresses
-should presented.
-The value of those flags 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.
-return an IPv4 address mapped to an IPv6 address
--.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.
-return all possible 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.
-only return an IPv6 or IPv4 address if here is an active network
-interface of that type.
--.It Li AI_DEFAULT
- This default sets the
-this default sets the
--.Li AI_V4MAPPED
--and
--.Li AI_ADDRCONFIG
--flag bits.
--.El
-.Pp
-The value of
-.Dv AF_INET6
-is sometimes added to
-.Fa flags .
-When
-.Fa flags
-is set to
-.Li "AI_V4MAPPED + AF_INET6"
-.Fn lwres_getipnodebyname
-will look for an IPv6 address and if this is not found it will look
-for an IPv4 address and map it to an IPv6 address.
-When
-.Fa flags
-is
-.Li "AI_ALL + AI_V4MAPPED + AF_INET6" ,
-.Fn lwres_getipnodebyname
-returns mapped IPv4 addresses and IPv6 addresses.
-.Fn lwres_getipnodebyname
-calls
-.Fn lwres_context_create
-to create a resolver context for the lookup and
-then calls
-.Fn lwres_getaddrsbyname
-to lookup the name using that resolver context.
--.Pp
--.Fn lwres_getipnodebyaddr
- performs a reverse lookup
-performs a thread-safe reverse lookup
--of address
--.Fa src
--which is
--.Fa len
--bytes long.
--.Fa af
- denotes the protocol family, typically
-denotes the protocol family:
--.Dv PF_INET
--or
--.Dv PF_INET6 .
-.Fn lwres_getipnodebyaddr
-also sets up a resolver context by calling
-.Fn lwres_context_create.
-It then calls
-.Fn lwres_getnamebyaddr
-to make the query.
-.Pp
-Both
-.Fn lwres_getipnodebyname
-and
-.Fn lwres_getipnodebyaddr
-will free any memory that was allocated during intermediate stages of the
-lookup by calling
-.Fn lwres_gnbaresponse_free .
-Both functions call
-.Fn lwres_getipnodebyaddr
-immediately before they return so that the created resolver context
-gets discarded.
--.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> :
-.Pa lwres/netdb.h .
--.Bl -tag -width HOST_NOT_FOUND
-.It Li NETDB_INTERNAL
-Internal Error - see
-.Li errno
-.It Li NETDB_SUCCESS
-no problem
--.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.
-Authoritative Answer Host not found
--.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.
-Non-Authoritive Answer Host not found, or
-.Dv SERVERFAIL
--.It Li NO_RECOVERY
- An unexpected failure occurred, and retrying the request
- is pointless.
-Non recoverable errors,
-.Dv FORMERR ,
-.Dv REFUSED ,
-or
-.Dv NOTIMP
-.It Li NO_DATA
-Valid name, but no data record of requested type
-.It Li NO_ADDRESS
-no address, so look for MX record
--.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_res_getaddrsbyname 3 ,
-.Xr lwres_res_context_create 3 ,
-.Xr lwres_res_context_destroy 3 ,
-.Xr lwres_res_gnbaresponse_free 3 ,
-.Xr lwres_res_getaddrsbyaddr 3 ,
-.Xr free 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 $
-
-.\"
-.\" $Id: lwres_getipnodebyaddr.3,v 1.3 2000/08/01 01:21:25 tale 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 $
-
-.\"
-.\" $Id: lwres_getipnodebyname.3,v 1.3 2000/08/01 01:21:26 tale 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 $
-
-.\"
-.\" $Id: lwres_getnamebyaddr.3,v 1.3 2000/08/01 01:21:27 tale 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 $
-
-.\"
-.\" $Id: lwres_getnameinfo.3,v 1.4 2000/08/01 01:21:28 tale 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 #include <lwres/lwres.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.
-- 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.
-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.
-the address in the
-.Dv sockaddr
-structure is presented as a dotted-decimal string for an IPv4
-address or an IPv6 hex address if the hostname is not found in the
-DNS.
--.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.
-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.
--.It Li NI_NUMERICSERV
- The service name is returned as a digit string representing the port number.
-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.
-the service uses a datagram transport protocol
--.El
--.Pp
-When a numeric host address string is needed,
-.Fn lwres_getnameinfo
-calls
-.Fn lwres_net_ntop
-to generate an IPv6 hex address or a dotted decimal IPv4 address.
-If required,
-.Fn lwres_getnameinfo
-will create a resolver context by calling
-.Fn lwres_context_create
-and then using
-.Fn lwres_getnamebyaddr
-to perform the reverse lookup.
-Any memory allocated during that reverse lookup will be
-freed by calling
-.Fn lwres_gnbaresponse_free .
-.Fn lwres_context_destroy
-is called immediately before
-.Fn lwres_getnameinfo
-returns so that the created resolver context gets discarded.
--.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 getnameinfo 3 ,
--.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.
-.Xr lwres_res_net_ntop 3 ,
-.Xr lwres_res_context_create 3,
-.Xr lwres_res_getnamebyaddr 3,
-.Xr lwres_res_gnbaresponse_free 3 ,
-.Xr lwres_res_context_destroy 3 ,
-.Xr lwres_res_net_ntop 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 $
-
-.\"
-.\" $Id: lwres_gnba.3,v 1.3 2000/08/01 01:21:29 tale 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
-.Nd lightweight resolver getnamebyaddress functions
--.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.
-These functions implement the lightweight resolver's getnamebyaddr opcode
-.Dv LWRES_OPCODE_GETNAMEBYADDR .
-They provide a reverse lookup mechanism, mapping an address to its
-hostname.
--.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 $
-
-.\"
-.\" $Id: lwres_gnbarequest_free.3,v 1.3 2000/08/01 01:21:30 tale 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 $
-
-.\"
-.\" $Id: lwres_gnbarequest_parse.3,v 1.3 2000/08/01 01:21:31 tale 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 $
-
-.\"
-.\" $Id: lwres_gnbarequest_render.3,v 1.3 2000/08/01 01:21:33 tale 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 $
-
-.\"
-.\" $Id: lwres_gnbaresponse_free.3,v 1.3 2000/08/01 01:21:34 tale 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 $
-
-.\"
-.\" $Id: lwres_gnbaresponse_parse.3,v 1.3 2000/08/01 01:21:35 tale 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 $
-
-.\"
-.\" $Id: lwres_gnbaresponse_render.3,v 1.3 2000/08/01 01:21:36 tale 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 $
-
-.\"
-.\" $Id: lwres_herror.3,v 1.3 2000/08/01 01:21:37 tale 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 $
-
-.\"
-.\" $Id: lwres_hstrerror.3,v 1.3 2000/08/01 01:21:38 tale 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 $
-
-.\"
-.\" $Id: lwres_inetntop.3,v 1.3 2000/08/01 01:21:41 tale 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 $
-
-.\"
-.\" $Id: lwres_lwpacket_parseheader.3,v 1.3 2000/08/01 01:21:43 tale 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 $
-
-.\"
-.\" $Id: lwres_lwpacket_renderheader.3,v 1.3 2000/08/01 01:21:44 tale 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 $
-
-.\"
-.\" $Id: lwres_net_ntop.3,v 1.3 2000/08/01 01:21:46 tale 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 $
-
-.\"
-.\" $Id: lwres_noop.3,v 1.3 2000/08/01 01:21:48 tale 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
-.Nd lightweight resolver no-op functions
--.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.
-These functions implement the lightweight resolver's no-op opcode
-.Dv LWRES_OPCODE_NOOP .
-This is analogous to a \*qping\*q test: a packet is sent to the
-lightweight 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 $
-
-.\"
-.\" $Id: lwres_nooprequest_free.3,v 1.3 2000/08/01 01:21:50 tale 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 $
-
-.\"
-.\" $Id: lwres_nooprequest_parse.3,v 1.3 2000/08/01 01:21:51 tale 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 $
-
-.\"
-.\" $Id: lwres_nooprequest_render.3,v 1.3 2000/08/01 01:21:52 tale 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 $
-
-.\"
-.\" $Id: lwres_noopresponse_free.3,v 1.3 2000/08/01 01:21:53 tale 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 $
-
-.\"
-.\" $Id: lwres_noopresponse_parse.3,v 1.3 2000/08/01 01:21:54 tale 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 $
-
-.\"
-.\" $Id: lwres_noopresponse_render.3,v 1.3 2000/08/01 01:21:55 tale 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 $
-
-.\"
-.\" $Id: lwres_packet.3,v 1.3 2000/08/01 01:21:56 tale 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.
-the overall packet length, including the entire packet header
--.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.
-and the size of the buffer needed to satisfy a request when the buffer is too large for replies
--.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.
-returns all known addresses for a given name
--.It Li GETNAMEBYADDR
- return the hostname for the given address.
- The lwres_gnba_*() functions should be used for this type.
-return the hostname for the given address
--.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" .
-.Dv "struct lwres_lwpacket" .
--.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 $
-
-.\"
-.\" $Id: lwres_resutil.3,v 1.3 2000/08/01 01:21:57 tale 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 $
-
-.\"
-.\" $Id: lwres_sethostent.3,v 1.3 2000/08/01 01:21:58 tale 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 $
-
-.\"
-.\" $Id: lwres_sethostent_r.3,v 1.3 2000/08/01 01:21:59 tale 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 $
-
-.\"
-.\" $Id: lwres_string_parse.3,v 1.3 2000/08/01 01:22:01 tale Exp $
-.\"
--.so lwres_resutil.3
projects / thirdparty / bind9.git / commitdiff
