Next: , Previous: Logging Statement, Up: configuration

2.2.4 Debug Statement

Syntax

     debug {
       # Set Mailutils debugging level.
       level spec;
       # Prefix debug messages with Mailutils source locations.
       line-info bool;
     }

Description

The debug statement configures debugging output. Although it is mostly useful for Mailutils developers, it may be of interest for casual users as well. In particular, you may use it to obtain more information about Mailutils actions, which may help in configuring it, or in filling a bug report.

Debugging output is controlled by a set of levels, each of which can be enabled or disabled independently of others. A debugging level consists of a module name, which defines a Mailutils module affected by this level, and a level number, which defines the verbosity of the debugging output. Valid debugging levels are:

error
Display only error messages.
trace0 through trace7
Eight levels of verbosity, ‘trace0’ producing less output, ‘trace7’ producing maximum possible output.
prot
Display network protocol interactions, where appropriate.

Table 2.2: Debugging levels

The most important debugging modules are:

acl
Debug access control lists. .
config
Debug configuration parser and/or lexical analyzer. The following levels are supported:
trace0
Minimal information about configuration statements.
trace2
Trace lexical structure of the configuration files.
trace7
Trace execution of the configuration parser.

Due to its specific nature, this debugging module cannot be enabled using level statement below. The --debug-level command line option should be used instead (). Alternatively, you may use the following hook, provided to facilitate debugging of the configuration parser: a pragmatic comment in form: 

          #debug=level

is understood as a request to set debugging level of module ‘config’ to level.

ip_server
IP based servers, such as imap4d and pop3d. This module supports ‘trace0’ and ‘error’ levels. See Server Settings, for more information about servers.
udp_server
UDP based servers, such as comsatd. This module supports ‘trace0’ and ‘error’ levels. See Server Settings, for more information about servers.
mailbox
Operations over mailboxes. This module supports the following levels: ‘error’, ‘trace0’, ‘trace1’, and ‘proto’. The latter is used by remote mailbox support libraries.
sieve
Debug Sieve parser and run-time evaluator. Currently supported levels are ‘error’, ‘trace1’ and ‘trace7’.
— Configuration: level spec

This statement enables debugging levels given by spec. The argument is an list of debugging specifications or a string with specifications delimited by semicolons. The syntax of a specification is: 

            module[[:]=level]

where module is the name of a module, and level is the level to be set. The level may be optionally prefixed with the following symbols:

‘!’
All levels except this one. E.g. ‘config=!trace7’ means set all debugging levels, except ‘trace7’ for the ‘config’ module.
‘<’
All levels up to and including this. The words ‘up to’ refer to the position of levels in Table 2.2 table, so that, e.g. ‘<trace2’ means levels ‘error’, ‘trace0’, ‘trace1’ and ‘trace2’.

Both prefixes can be used together, in this order: ‘!<’. This means all levels except this one and ones listed before it in the table.

A comma before equal sign, as in ‘mailbox:=<trace7’ means set this debugging levels in all modules, invoked by this one.

The level in the level specification can also be a comma-separated list of valid levels, e.g.: 

             mailbox=<trace2,!<trace4

which means “levels trace3 and trace4”.

The following example illustrates two equivalent ways of setting debugging level in a configuration file: 

            level ("mailbox=!proto", "acl=<trace7");
            level "mailbox=!proto;acl=<trace7";

The --debug-level command line option overrides the settings of the level configuration statement.

— Configuration: line-info bool

If bool is ‘true’ (see boolean value), each debugging message will be preceded by a corresponding source file location, i.e. the file name and line number where this message was generated.