21.3.3 The DBUG Package

The MySQL server and most MySQL clients are compiled with the
DBUG package originally created by Fred Fish. When you have
configured MySQL for debugging, this package makes it possible
to get a trace file of what the program is doing. See
Section 21.3.1.2, “Creating Trace Files”.

This section summarizes the argument values that you can specify
in debug options on the command line for MySQL programs that
have been built with debugging support. For more information
about programming with the DBUG package, see the DBUG manual in
the dbug directory of MySQL source
distributions. It's best to use a recent distribution to get the
most updated DBUG manual.

The DBUG package can be used by invoking a program with the
--debug[=debug_options]
or -#
[debug_options] option. If
you specify the --debug or -#
option without a debug_options value,
most MySQL programs use a default value. The server default is
d:t:i:o,/tmp/mysqld.trace on Unix and
d:t:i:O,\mysqld.trace on Windows. The effect
of this default is:

d: Enable output for all debug macros

t: Trace function calls and exits

i: Add PID to output lines

o,/tmp/mysqld.trace,
O,\mysqld.trace: Set the debug output
file.

Most client programs use a default
debug_options value of
d:t:o,/tmp/program_name.trace,
regardless of platform.

Here are some example debug control strings as they might be
specified on a shell command line:

Enable output from DBUG_XXX
macros for the current state. May be followed by a
list of keywords, which enables output only for the
DBUG macros with that keyword. An empty list of
keywords enables output for all macros.

In MySQL, common debug macro keywords to enable are
enter, exit,
error, warning,
info, and loop.

D

Delay after each debugger output line. The argument is
the delay, in tenths of seconds, subject to machine
capabilities. For example, D,20
specifies a delay of two seconds.

f

Limit debugging, tracing, and profiling to the list of
named functions. An empty list enables all functions.
The appropriate d or
t flags must still be given; this
flag only limits their actions if they are enabled.

F

Identify the source file name for each line of debug
or trace output.

i

Identify the process with the PID or thread ID for
each line of debug or trace output.

L

Identify the source file line number for each line of
debug or trace output.

n

Print the current function nesting depth for each line
of debug or trace output.

N

Number each line of debug output.

o

Redirect the debugger output stream to the specified
file. The default output is stderr.

O

Like o, but the file is really
flushed between each write. When needed, the file is
closed and reopened between each write.

p

Limit debugger actions to specified processes. A
process must be identified with the
DBUG_PROCESS macro and match one in
the list for debugger actions to occur.

P

Print the current process name for each line of debug
or trace output.

r

When pushing a new state, do not inherit the previous
state's function nesting level. Useful when the output
is to start at the left margin.

S

Do function _sanity(_file_,_line_)
at each debugged function until
_sanity() returns something that
differs from 0. (Mostly used with
safemalloc to find memory leaks.)

t

Enable function call/exit trace lines. May be followed
by a list (containing only one modifier) giving a
numeric maximum trace level, beyond which no output
occurs for either debugging or tracing macros. The
default is a compile time option.

The leading + or -
character and trailing list of modifiers are used for flag
characters such as d or f
that can enable a debug operation for all applicable modifiers
or just some of them:

With no leading + or
-, the flag value is set to exactly the
modifier list as given.

With a leading + or -,
the modifiers in the list are added to or subtracted from
the current modifier list.