zonemaster.es/zonemaster-ldns/ldns/pcat/pcat-diff.1

'\" t
.TH PCAT-DIFF 1 "08 Mar 2006" "pcat utils"
.SH NAME
pcat-diff \- show the difference between two pcat files.
.SH SYNOPSIS
.B pcat-diff
.IR PCAT_FILE1
.IR PCAT_FILE2

.SH DESCRIPTION
\fBpcat-diff\fR reads in two pcat files and show the differences
between them.
Its output is another pcat stream which can then be interpreted by
pcat-print.

pcat-diff can also do advanced checking against a number of specification,
for instance to count the number of known differences between two
implementations.

You can let pcat-diff do more intelligent checking on the differences between
two outputs of pcat. In this mode, pcat-diff takes an argument specifying a
directory containing files whose name end in .match. These files specify
'Known' differences. It works like this:

If a difference between two answer packets is found, the packet is first
normalized; the packet dates is changed to match, and each section is
sorted. If these changes still don't make the packets equal, the
match-specifications in the specified directory are consulted.

These specifications contain 3 elements; a 1-line description of the type of
difference, a specification the question must match, and a specification
that both answer packets must match.

The first line contains the specification, the following lines the
specifications, separated by a line starting with an exclamation mark.

A specification looks like the normal output of drill and dig. It is based
on the text representation format from the DNS RFCs. It can contain the
following special characters:

    * whitespace: whitespace is skipped and ignored
    * ?:  Following a question mark, all characters up to the 
          next whitespace are optional, so they can either
          exist or not in the answer
    * []: Square brackets contain a list of words/values of 
          which exactly one must be present in the packets.
    * *:  A star specifies that the packets may contain 
          everything until it matches the next character in 
          the specification. You can use multiple stars in a 
          row, the number of stars specify the number of next
          characters that must match before continuing.
    * &:  The ampersand works the same as the *, but in this 
          case the value that matches must be exactly the 
          same in both packets.

There are 2 special cases that can be used instead of a packet description:

    * BADPACKET: if you use this as the complete description
                 of the query packet, this matches any query
                 that cannot be parsed
    * NOANSWER:  if you use this as the complete description
                 of the answer packet, this matches *both*
                 packets if *one* had no answer (the other 
                 packet is ignored, if both packets had no
                 answer, they were equal anyway)


Example:

Different additional section
*
!
;; ->>HEADER<<- opcode: &, rcode: &, id: &
;; flags: & ; QUERY: &, ANSWER: &, AUTHORITY: &, ADDITIONAL: &
;; QUESTION SECTION:
;; &&&&&

;; ANSWER SECTION:
&&&&&

;; AUTHORITY SECTION:
&&&&&

;; ADDITIONAL SECTION:
*****

;; Query time: & msec
&&&&&
;; WHEN: &
;; MSG SIZE  rcvd: &

The description of this examples is 'Different additional section'.

The query specification contains only one *, so every query matches this.

The answer specification specifies that the packets must be completely
equal, except for the additional part. The additional part must, however,
contain an equal amount of entries (see the & after ADDITIONAL in line 2).

In the question section, 5 &'s are used, so that everything passes until the
packets contain the text ';; AU'. This could of course be expanded to
completely match the text ';; AUTHORITY SECTION', by using even more
ampersands.


If pcat-diff in advanced mode encounters a difference which is not known, it
prints the index number, query, and both answers, and then quits. It is
expected that the user studies the new and unexpected difference, captures
it in a match specification, and runs pcat-diff again. To speed up the
process of finding all differences, you can start from the index number that
was printed by using the option -s <index>.

If you want to know a bit more about why the packets did not match, you can
specify verbose mode with -v. It is not advisable to do this on the complete
input, but rather use -s to start with the offending packet. Verbose mode
produces a LOT of output.

If the complete files have been read, and no unknown differences have been
found, statistics are printed about the known differences encountered.
Because this can take a long time, you can use '-p <nr>' to print
preliminary results every nr packets.


.PP
If PCAT_FILE2 is not given, standard input is read.

.SH OPTIONS
.TP
\fB-d\fR \fIdirectory\fR
Directory containing match files, this options sets the advanced checking mode, see manpage

.TP
\fB-h\fR 
Show usage

.TP
\fB-m\fR \fInumber\fR 
only check up to <number> packets

.TP
\fB-o\fR 
show original packets when printing diffs (by default, packets are normalized)

.TP
\fB-p\fR \fInumber\fR 
show intermediate results every <number> packets

.TP
\fB-s\fR \fInumber\fR 
only start checking after <number> packets

.TP
\fB-v\fR
verbose mode


.SH OUTPUT FORMAT
The default output of \fBpcat-diff\fR consists "records". Each record has four lines:
.PP
    1. xxx         - (decimal) sequence number
    2. hex dump    - query in hex, network order
    3. hex dump    - answer of FILE1 in hex, network order
    4. hex dump    - answer of FILE2 in hex, network order.

The advanced output only prints statistics about the types of differences
found and their percentages. If an unknown difference is found it prints
the relevant packets and exits.


.SH ALSO SEE
Also see pcat(1) and pcat-print(1).

.SH AUTHOR
Written by Miek Gieben for NLnet Labs.

.SH REPORTING BUGS
Report bugs to <dns-team@nlnetlabs.nl>.

.SH COPYRIGHT
Copyright (C) 2005, 2006 NLnet Labs. This is free software. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.
.PP
Licensed under the BSD License.