5.42 Debugging Functions

These functions are designed for debugging the MFL programs.

Built-in Function: void debug (string spec)

Enable debugging. The value of spec sets the debugging level. See debugging level specification, for a description of its format.

For compatibility with previous versions, this function is also available under the name ‘mailutils_set_debug_level’.

Built-in Function: number debug_level ([string srcname])

This function returns the debugging level currently in effect for the source module srcname, or the global debugging level, if called without arguments.

For example, if the program was started with --debug='all.trace5;engine.trace8' option, then:

debug_level() ⇒ 127
debug_level("engine") ⇒ 1023
debug_level("db") ⇒ 0

Built-in Function: boolean callout_transcript ([boolean value])

Returns the current state of the callout SMTP transcript. The result is 1 if the transcript is enabled and 0 otherwise. The transcript is normally enabled either by the use of the --transcript command line option (see SMTP transcript) or via the ‘transcript’ configuration statement (see transcript).

The optional value, supplies the new state for SMTP transcript. Thus, calling ‘callout_transcript(0)’ disables the transcript.

This function can be used in bracket-like fashion to enable transcript for a certain part of MFL program, e.g.:

number xstate callout_transcript(1)
on poll $f do
  …
done
set xstate callout_transcript(0)

Note, that the use of this function (as well as the use of the --transcript option) makes sense only if callouts are performed by the mailfromd daemon itself. It will not work if a dedicated callout server is used for that purpose (see calloutd).

Built-in Function: string debug_spec ([string catnames, bool showunset])

Returns the current debugging level specification, as given by --debug command line option or by the debug configuration statement (see conf-debug).

If the argument srcnames is specified, it is treated as a semicolon-separated list of categories for which the debugging specification is to be returned.

For example, if mailfromd was started with --debug=all.trace5;spf.trace1;engine.trace8;db.trace0, then:

debug_spec() ⇒ "all.trace5,engine.trace8"
debug_spec("all;engine") ⇒ "all.trace5,engine.trace8"
debug_spec("engine;db") ⇒ "db.trace0;engine.trace8"
debug_spec("prog") ⇒ ""

When called without arguments, debug_spec returns only those categories which have been set, as shown in the first example above.

Optional showunset parameters controls whether to return unset module specifications. To print all debugging specifications, whether set or not, use

debug_spec("", 1)

These three functions are intended to complement each other. The calls to debug can be placed around some piece of code you wish to debug, to enable specific debugging information for this code fragment only. For example:

    /* Save debugging level for dns.c source */
    set dlev debug_spec("dns", 1)
    /* Set new debugging level */
    debug("dns.trace8")
    .
    .
    .
    /* Restore previous level */
    debug(dlev)

Built-in Function: void program_trace (string module)

Enable tracing for a set of modules given in module argument. See --trace-program, for a description of its format.

Built-in Function: void cancel_program_trace (string module)

Disable tracing for given modules.

This pair of functions is also designed to be used together in a bracket-like fashion. They are useful for debugging mailfromd, but are not advised to use otherwise, since tracing slows down the execution considerably.

Built-in Function: void stack_trace ()

Generate a stack trace in this point. See tracing runtime errors, for the detailed description of stack traces.

The functions below are intended mainly for debugging MFL run-time engine and for use in mailfromd testsuite. You will hardly need to use them in your programs.

Built-in Function: void _expand_dataseg (number n)

Expands the run-time data segment by at least n words.

Built-in Function: number _reg (number r)

Returns the value of the register r at the moment of the call. Symbolic names for run-time registers are provided in the module _register:

Name	Register
REG_PC	Program counter
REG_TOS	Top of stack
REG_TOH	Top of heap
REG_BASE	Frame base
REG_REG	General-purpose accumulator
REG_MATCHSTR	Last matched string pointer

Built-in Function: number _stack_free ()

Returns number of words available for use in stack. This is the same as

_reg(REG_TOS) - _reg(REG_TOH)

Built-in Function: number _heap_reserve (number n)

Use up next n words in the heap. Return the address of the first word.

Built-in Function: void _wd ([number n])

Enters a time-consuming loop and waits there for n seconds (by default – indefinitely). The intention is to facilitate attaching to mailfromd with the debugger. Before entering the loop, a diagnostic message is printed on the ‘crit’ facility, informing about the PID of the process and suggesting the command to be used to attach to it, e.g.:

mailfromd: process 21831 is waiting for debug
mailfromd: to attach: gdb -ex 'set variable mu_wd::_count_down=0'
 /usr/sbib/mailfromd 21831