16.1 The Syntax of -d

The form for the -d command-line switch is:

-dcategory.level,category.level,....
-dANSI                                     V8.8 and above
-dexpression.level,expression.level,....   V8.12 and above

The -d can appear alone, or it can be followed by one or more category.level pairs separated by commas or, beginning with V8.8, by the word ANSI. We cover the category.level pairs first, then ANSI, and finally the expression form.

The category limits debugging to an aspect of sendmail (such as queuing or aliasing). The level limits the verbosity of sendmail (with low levels producing the least output).

The category is either a positive integer or a range of integer values specified as:

first-last

When category is a range, first is a positive integer that specifies the first category in the range. It is followed by a hyphen character (-) and then last, a positive integer that specifies the last category in the range. The value of first must be less than the value of last, or the range will be ignored.

The level is a positive integer. A level of 0 causes sendmail to produce no output for the category.

When the -d is specified with neither category nor level, an internal sendmail default is used:

0-99.1

This default causes sendmail to set all the categories, from zero through 99 inclusive, to a level of 1.

When category is included but level is omitted, the value for level defaults to 1. When a dot (.) and level are included, but category is omitted, the value for category defaults to 0.

The maximum value that can be specified for a single category is 99. The maximum value for level is that of an unsigned char (255 decimal). Any value specified above the maximum is reduced to the maximum. Nondigits for the category or range evaluate to zero. Nondigits for the level evaluate to 1.

The level specifies the maximum amount of verbose output to produce. All levels below the level specified also produce output.

The expression that produces the maximum debugging output is:

-d0-99.127

But beware that debugging levels of 100 or greater can cause sendmail to modify its behavior. (For example, one category at such a high level prevents sendmail from removing its temporary files.) For this reason, -d0-99.99 is the maximum level recommended.

Debugging can be turned on from the command line and from within -bt rule-testing mode (Section 8.7).

Beginning with V8.8 sendmail, a special debugging word can be specified at the command line to cause debugging output to become clearer:

-dANSI    V8.8 and above

ANSI is case-sensitive and must be the only argument following the -d. If you wish to combine it with other debugging switches, you must specify them separately:

-dANSI -d0.4

ANSI causes defined macros, class macros, and operators to be displayed in reverse video, as shown in Figure 16-1.

Figure 16-1. Reverse video display using ANSI

This is truly a "hack." The escape code to highlight characters is hardcoded into sendmail. Your display must support ANSI standard escape sequences for this to work. There is no plan to use standard termcap(5) library support for this "aid to rule-set hackers."

Beginning with V8.12, sendmail has begun transitioning to more easily remembered alphanumeric debugging categories. For the V8 series this is being accomplished by adding alphanumeric categories rather than replacing the existing numeric categories entirely.

The forms for this new way of specifying a debug category look like this:

-dprogram_check_process.level  
-dprogram_trace_process.level

Here, the -d is literal. The program_ specifies the program for which the debugging flag applies. Currently, the only program_ available is "sm_" for sendmail.

The check lets you know that a particular category is intended for checks on limits, states, or the rationality of values. The trace lets you know that a particular category is intended to trace the behavior of a section of code, or of behavior common to many sections of code.

The _process specifies just what aspect of the code will be checked or traced. Table 16-1, we list the handful of new categories that currently use this new form.

Table 16-1. New alphanumeric debug categories
Category	Does what
sm_check_assert	Enable expensive SM_ASSERT checking
sm_check_require	Enable expensive SM_REQUIRE checking
sm_check_ensure	Enable expensive SM_ENSURE checking
sm_trace_heap	Trace sm_{malloc,realloc,free} calls
sm_check_heap	Enable memory leak detection

All of these new categories are intended to be used by sendmail developers and are not generally useful to mail administrators. If you suspect you might need to use one of these categories, examine the sendmail code first to determine the effect of each, then apply them in one window while examining the source in another.