PCAT-DIFF(1)

NAME
pcat-diff - show the difference between two pcat files.

SYNOPSIS
pcat-diff PCAT_FILE1 PCAT_FILE2

DESCRIPTION
pcat-diff 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 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.

If PCAT_FILE2 is not given, standard input is read.

OPTIONS

-d directory
    Directory containing match files, this options sets the advanced checking mode, see manpage

-h  Show usage

-m number
    only check up to <number> packets

-o  show original packets when printing diffs (by default, packets are normalized)

-p number
    show intermediate results every <number> packets

-s number
    only start checking after <number> packets

-v  verbose mode

OUTPUT FORMAT
The default output of pcat-diff consists "records". Each record has four lines:

    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.

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

AUTHOR
Written by Miek Gieben for NLnet Labs.

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

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.

Licensed under the BSD License.