8.7 Add Debugging for Detail

In rule-testing mode the -d command (Section 16.1) can be used to turn debugging output on and off. Prior to V8.7 sendmail, the -d could be specified only on the command line. Beginning with V8.7 sendmail, the -d can also be specified in rule-testing mode. We illustrate the latter technique here.

Debugging output can reveal in great detail how individual rules are being handled. A debugging category and level of 21.12 (-d21.1), for example, causes sendmail to print the LHS of each rule as it is tried. To illustrate, consider the following (highly simplified) configuration-file rule set:

V10
STest
R @                  $#local $:$n                 handle <> form
R $* < @ $+ > $*     $#$M $@$R $:$1<@$2>$3        user@some.where
R $+                 $#local $:$1                 local names

Normal output that is produced when a rule set name and an address are entered at the > prompt looks like this:

> Test george
Test               input: george
Test             returns: $# local $: george

But if we turn on debugging using the -d rule-testing command:

> -d21.12

the output that is produced when the same rule set number and address are entered is more verbose than it was before:

>  Test george
Test               input: george
-----trying rule: @
----- rule fails
-----trying rule: $* < @ $+ > $*
----- rule fails
-----trying rule: $+
-----rule matches: $# local $: $1
rewritten as: $# local $: george
Test             returns: $# local $: george

Observe that the first rule in the Test rule set (the lone @) does not match george in the workspace. Therefore, that rule fails and is skipped. Then the more complicated rule ($*<@$+>$*) is tried, and it too fails. Finally, the $+ operator in the last rule matches george, and the workspace is rewritten.

Note that the extra output that is produced by -d can potentially run to many lines. To capture the output for later examination, consider running sendmail in rule-testing mode from within a script(1), emacs(1), or similar session.

To turn off the extra debugging output, just reuse the -d rule-testing command and specify a level of zero:

> -d21.0

A -d with no category or level behaves the same as the -d command-line switch (Section 16.1). It sets a default of 0-99.1.

8.7.1 A Trick

In debugging large configuration files, the output that is produced by the -d21.15 switch can become too huge to examine conveniently. A good alternative (when modifying or adding rules) is to temporarily insert a fake subroutine call before and after individual rules to see what they do:

R$*      $:$>TEST $1   fake subroutine call
Rlhs     rhs           new rule
R$*      $:$>TEST $1   fake subroutine call

With the fake wrapper around the new rule (the name TEST is arbitrary), ordinary rule testing with -bt now shows how the address is rewritten by that rule:

3                  input: ...
TEST               input: ...
TEST             returns: ...
                              new rule acted here
TEST               input: ...
TEST             returns: ...
3                returns: ...
>

If you use this technique, remember, of course, to remove the fake subroutine calls before putting that configuration file into use.