Bug#85854: adns-tools: Manpage for adnshost

Julien Patriarca Sun, 28 Oct 2012 13:45:22 -0700

Package: adns-tools
Version: 1.4-2
Followup-For: Bug #85854

Dear Maintainer,


To be compliant with the Debian-Policy, each binary has to have a
manpage.I have written one for the adnshost binary. You will find below a
manpage and a html ouput of it.
Let me know if they are suitable.

Regards,


-- System Information:
Debian Release: wheezy/sid
  APT prefers testing
  APT policy: (500, 'testing'), (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 3.2.0-3-amd64 (SMP w/4 CPU cores)
Locale: LANG=fr_FR.UTF-8, LC_CTYPE=fr_FR.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

Versions of packages adns-tools depends on:
ii  libadns1  1.4-2
ii  libc6     2.13-35

adns-tools recommends no packages.

adns-tools suggests no packages.

-- no debconf information

.TH adnshost "1" "October 2012" "adnshost 1.2" "User Commands"
.IX adnshost
.SH NAME
.B adnshost \- utility to perform domain\-lookups
.SH SYNOPSIS
.B adnshost
.RB [ global\-options ] 
.RB [ query\-options] query\-domain
.LP
.B adnshost 
.RB [[ query\-options] query\-domain ...]
.LP
.B adnshost 
.RB [ global\-options ] 
.RB [ query\-options ] \fB\-f\fR|\-\-pipe
.SH DESCRIPTION
.B adnshost
is a general-purpose DNS lookup utility which can be used easily from the 
command line and in shell scripts to perform domain-lookups. In a more advanced 
mode it can be used as a general-purpose DNS helper program for scripting 
languages which can invoke and communicate with subprocesses
.SH OPTIONS
.BR
.SS "global options:"
.TP
\fB\+e  \fB\-\-no\-env\fR 
Do not take the environment variables in account
.TP
\fB\-f\fR  \fB\-\-pipe\fR
Read queries on stdin instead of using arguments
.TP
\fB\-a\fR  \fB\-\-asynch\fR
Allow answers to be reordered
.BR
.SS "other global options:"
.TP
\fB\-\-config\fR <<config\-text>>
Configuration to use instead of /etc/resolv.conf
.TP
\fB\-\-version\fR
Print version number
.TP
\fB\-\-help\fR
Print usage information
.SS "answers/errors output format and destination :"
.TP
\fB\-Fs\fR \fB\-\-fmt\-simple\fR
Answers will be printed to stdout and errors as messages will be printed to 
stderr (default)
.TP
\fB\-Fi\fR \fB\-\-fmt\-inline\fR
Answers and errors will both be printed to stdout in a parseable format
.TP
\fB\-Fa\fR \fB\-\-fmt\-asynch\fR
Fully\-parseable output format (default for \fB\-\-asynch\fR)
.BR
.SS "global verbosity level:"
.TP
\fB\-Vq\fR \fB\-\-quiet\fR
Do not print anything to stderr
.TP
\fB\-Vn\fR \fB\-\-no\-quiet\fR
Report unexpected problems only (default)
.TP
\fB\-Vd\fR \fB\-\-debug\fR
Debugging mode
.BR
.SS "per-query options:"
.TP
\fB\-t\fR<type> / \fB\-\-type\fR <type>
Query type (see below)
.TP
\fB\-i\fR<addr> / \fB\-\-ptr\fR <addr>
Do reverse query (address \-> name lookup)
.TP
\fB\-\-reverse\fR <addr> <zone>
Lookup in in\-addr\-like `zone' (eg MAPS RBL)
.BR
.SS "per-query binary options:"
.TP
\fB\-s\fR  \fB\-\-search\fR
Use the search list
.TP
\fB\-Qq\fR \fB\-\-qc\-query\fR
Allow query domains contain quote\-requiring chars
.TP
\fB\-Qa\fR \fB\-\-qc\-anshost\fR
Let hostnames in answers contain <...>
.TP
\fB\-Qc \fB\-\-no\-qc\-cname\fR
Prevent CNAME target domains from containing <...>
.TP
\fB\-u\fR  \fB\-\-tcp\fR
Force use of a virtual circuit
.TP
\fB\+Do \fB\-\-no\-show\-owner\fR
Do not display owner name in output
.TP
\fB\+Dt \fB\-\-no\-show\-type\fR
Do not display RR type in output
.TP
\fB\+Dc \fB\-\-no\-show\-cname\fR
Do not display CNAME target in output
.BR
.SS "per-query TTL mode (NB TTL is minimum across all info in reply):"
.TP
\fB\-Tt\fR \fB\-\-ttl\-ttl\fR
Show the TTL as a TTL
.TP
\fB\-Ta\fR \fB\-\-ttl\-abs\fR
Show the TTL as a time_t when the data might expire
.TP
\fB\-Tn\fR \fB\-\-no\-ttl\fR
Do not show the TTL value (default)
.BR
.SS "per-query CNAME handling mode:"
.TP
\fB\-Cf\fR \fB\-\-cname\-reject\fR
Call it an error if a CNAME is found
.TP
\fB\-Cl\fR \fB\-\-cname\-loose\fR
Allow references to CNAMEs in other RRs
.TP
\fB\-Cs\fR \fB\-\-cname\-ok\fR
CNAME will be allowed for query domain, but not for RRs (default)
.BR
.SS "asynchronous/pipe mode options:"
.TP
\fB\-\-asynch\-id\fR <id>
Set <id>, default is decimal sequence starting 0
.TP
\fB\-\-cancel\-id\fR <id>
Cancel the query with id <id> (no errorw will be reported if not found)
.BR
.SS "Escaping domains which might start with `-':"
.TP
\- <domain>
Next argument is a domain, but more options may follow.
Query domains should always be quoted according to master file format.
.PP
For binary options, \fB\-\-FOO\fR and \fB\-\-no\-FOO\fR are opposites, as are
\fB\-X\fR and +X. In each case the default is the one not listed. Per query 
options stay set until they are reset, whether they appear on the command line 
or on stdin.
All global options must preceed the first query domain.
.PP
With \fB\-f\fR, the input should be lines with either an option, possibly
with a value argument (separated from the option by a space if it's a long
option), or a domain (possibly preceded by a hyphen and a space to
distinguish it from an option).
.BR
.SS "Output format is master file format without class or TTL by default:"
.BR
.PP
[<owner>] [<ttl>] [<type>] <data>
.PP
or if the <owner> domain refers to a CNAME and \fB\-\-show\-cname\fR is on :
.BR
.PP
[<owner>] [<ttl>] CNAME <cname>
[<cname>] [<ttl>] <type> <data>
.PP
When a query fails you get an error message to stderr (with 
\fB\-\-fmt\-simple\fR).
Specify \fB\-\-fmt\-inline\fR for lines like this :
.BR
.PP
\fB\ failed <statustype> <statusnum> <statusabbrev> [<owner>] [<ttl>] [<cname>] 
"<status string>"
.PP
If you use \fB\-\-fmt\-asynch\fR, which is the default for \fB\-\-asynch\fR,
each answer (success or failure) is preceded by a line :
.BR
.PP
\fB\<id> <nrrs> <statustype> <statusnum> <statusabbrev> [<owner>] [<ttl>] 
[<cname>] "<status string>"
.PP
where <nrrs> is the number of RRs that follow and <cname> will be '$' or
the CNAME target; the CNAME indirection and error formats above are not used.
.SH EXIT STATUS
.B adnshost
can exit with multiple status. Here they are :
.TP
0
all went well
.TP
1\-6
at least one query failed with statustype:
.TP
1
localfail   
.TP
2
remotefail   temporary errors
.TP
3
tempfail   temporary errors
.TP
4
misconfig   
.TP
5
misquery     permanent errors
.TP
6
permfail    
.TP
10
system trouble
.TP
11
usage problems
.BR
.SS "Query types (see adns.h; default is addr):"
ns soa  ptr  mx  rp  srv  addr       \- enhanced versions
.TP
cname hinfo  txt                     \- types with only one version
.TP
a ns\-  soa\-  ptr\-  mx\-  rp\-  srv\-    \- raw versions
.TP
type<number> \- `unknown' type, RFC3597
.TP
Default is addr, or ptr for \fB\-i\fR/\-\-ptr queries
.SH "SEE ALSO"
.BR adnsheloex(1)
.BR adnslogres(1)
.BR adnsresfilter(1)

Title: Man page of adnshost

adnshost

Section: User Commands (1)
Updated: October 2012
Index Return to Main Contents

NAME

adnshost - utility to perform domain-lookups

SYNOPSIS

adnshost [global-options] [query-options]query-domain

adnshost [[query-options]query-domain...]

adnshost [global-options] [query-options]-f|--pipe

DESCRIPTION

adnshost is a general-purpose DNS lookup utility which can be used easily from the command line and in shell scripts to perform domain-lookups. In a more advanced mode it can be used as a general-purpose DNS helper program for scripting languages which can invoke and communicate with subprocesses

OPTIONS

global options:

+e --no-env: Do not take the environment variables in account
-f --pipe: Read queries on stdin instead of using arguments
-a --asynch: Allow answers to be reordered

other global options:

--config <<config-text>>: Configuration to use instead of /etc/resolv.conf
--version: Print version number
--help: Print usage information

answers/errors output format and destination :

-Fs --fmt-simple: Answers will be printed to stdout and errors as messages will be printed to stderr (default)
-Fi --fmt-inline: Answers and errors will both be printed to stdout in a parseable format
-Fa --fmt-asynch: Fully-parseable output format (default for --asynch)

global verbosity level:

-Vq --quiet: Do not print anything to stderr
-Vn --no-quiet: Report unexpected problems only (default)
-Vd --debug: Debugging mode

per-query options:

-t<type> / --type <type>: Query type (see below)
-i<addr> / --ptr <addr>: Do reverse query (address -> name lookup)
--reverse <addr> <zone>: Lookup in in-addr-like `zone' (eg MAPS RBL)

per-query binary options:

-s --search: Use the search list
-Qq --qc-query: Allow query domains contain quote-requiring chars
-Qa --qc-anshost: Let hostnames in answers contain <...>
-Qc --no-qc-cname: Prevent CNAME target domains from containing <...>
-u --tcp: Force use of a virtual circuit
+Do --no-show-owner: Do not display owner name in output
+Dt --no-show-type: Do not display RR type in output
+Dc --no-show-cname: Do not display CNAME target in output

per-query TTL mode (NB TTL is minimum across all info in reply):

-Tt --ttl-ttl: Show the TTL as a TTL
-Ta --ttl-abs: Show the TTL as a time_t when the data might expire
-Tn --no-ttl: Do not show the TTL value (default)

per-query CNAME handling mode:

-Cf --cname-reject: Call it an error if a CNAME is found
-Cl --cname-loose: Allow references to CNAMEs in other RRs
-Cs --cname-ok: CNAME will be allowed for query domain, but not for RRs (default)

asynchronous/pipe mode options:

--asynch-id <id>: Set <id>, default is decimal sequence starting 0
--cancel-id <id>: Cancel the query with id <id> (no errorw will be reported if not found)

Escaping domains which might start with `-':

- <domain>: Next argument is a domain, but more options may follow. Query domains should always be quoted according to master file format.

For binary options, --FOO and --no-FOO are opposites, as are -X and +X. In each case the default is the one not listed. Per query options stay set until they are reset, whether they appear on the command line or on stdin. All global options must preceed the first query domain.

With -f, the input should be lines with either an option, possibly with a value argument (separated from the option by a space if it's a long option), or a domain (possibly preceded by a hyphen and a space to distinguish it from an option).

Output format is master file format without class or TTL by default:

[<owner>] [<ttl>] [<type>] <data>

or if the <owner> domain refers to a CNAME and --show-cname is on :

[<owner>] [<ttl>] CNAME <cname> [<cname>] [<ttl>] <type> <data>

When a query fails you get an error message to stderr (with --fmt-simple). Specify --fmt-inline for lines like this :

failed <statustype> <statusnum> <statusabbrev> [<owner>] [<ttl>] [<cname>] "<status string>"

If you use --fmt-asynch, which is the default for --asynch, each answer (success or failure) is preceded by a line :

<id> <nrrs> <statustype> <statusnum> <statusabbrev> [<owner>] [<ttl>] [<cname>] "<status string>"

where <nrrs> is the number of RRs that follow and <cname> will be '$' or the CNAME target; the CNAME indirection and error formats above are not used.