UNDODB-GDB

NAME

SYNOPSIS

DESCRIPTION

undodb-gdb may be passed the same options as gdb, plus some additional options (see below).

For the most part undodb-gdb is used exactly as one would use gdb, except that there are some new commands. The new commands all use a b prefix. Most are analogous to existing gdb commands, except that they run time backwards:

bcontinue

Run backwards until a breakpoint or watchpoint is hit. A backwards equivalent of gdb's continue command. (Note that reverse watchpoints are not available in UndoDB starter edition.)

bstep

Step backwards out of the current source line. A backwards equivalent of gdb's step command.

bnext

Step backwards out of the current source line, stepping over function calls. A backwards equivalent of gdb's next command.

bstepi

Step backwards out of the current instruction. A backwards equivalent of gdb's stepi command.

bnexti

Step backwards out of the current instruction, stepping over function calls. A backwards equivalent of gdb's nexti command.

bfinish

Run backwards to the call-site of the current function. A backwards equivalent of gdb's finish command. It may fail if there is no debugging information for the current function or if the current function is compiled without frame-pointers.

buntil

Step backwards out of current source line, stepping over function calls and local loops, but stopping if the program exits the current function. A backwards equivalent of gdb's until command. However, this is not exactly analogous to gdb's until It cannot be given arguments (use bgoton instead). Also, it does nothing when used in code that has not been compiled with debugging information.

If there is no detailed debug line information available, the line-oriented commands bnext bstep and buntil will output a warning and behave like bstepi

There are also some new commands that have no analogue in gdb, which are used to jump around in time arbitrarily:

bget

Output the current time, in simulated nanoseconds.

bgoto *0x<address> | <function> | <file>:<line> | <line>

Unwind time to the specified position. Note that unwinding a long way (e.g. with bgoto main ) can take a long time - up to ten times longer than the time it takes to run forwards. If main is only called once, bgoton 1 followed by advance main will be much faster. Note also that unlike bcontinue this command will not stop at breakpoints or watchpoints.

bgoton <number>

Wind forwards or backwards to the specified time, in simulated nanoseconds. Unlike most UndoDB commands, the length of time this command takes to execute does not depend on how far in time it is moving. e.g. bgoton 1 is usually almost instant, even if done from record mode.

bgoton +<number> | -<number>

Wind forward/backward the specified number of simulated nanoseconds.

bget-exact

Return a precise indication of time. Every instruction will return a unique value.

bgoto-exact t

Goto a time t as returned by bget-exact

bgoto-record-mode

Return the debuggee to the latest point in history - i.e. to record mode.

Breakpoints are not active when the above commands other than bcontinue are executed. For example, using bgoton <big number> to move forwards will not hit a breakpoint where using continue would.

There are also some commands for stepping within threads:

bfinisht bgotot bnextt bnextit bstept bstepit buntilt

These are the same as the commands described earlier except that they stay in the current thread when stepping backwards - i.e. they skip over other threads' time-slices.

UndoDB also provides replacements for some gdb commands unavailable in undodb-gdb:

binfo threads

Output a list of the currently running threads. The current thread is marked with a `*'.

bthread <n>

Change the current thread to thread number n This doesn't effect execution of the debuggee, but does effect information output by gdb commands such as backtrace or info registers.

bset <a> = <b>

Set the debuggee's variable <a> to the expression <b>. This is like gdb's set command, except that it may be used to modify a debuggee's memory, but not its registers, and may not be used in replay mode.

There are also some commands for controlling how UndoDB uses memory:

bset-event-log-size <size> [K|M]

UndoDB's snapshot-and-replay technique means relatively little event log is required, but non-deterministic events must still be stored in the log. All of the program's input (e.g. from disk or network) must be stored in the log, as must all other non-deterministic events such as thread switches, asynchronous signals or shared memory accesses. Memory is allocated dynamically for the event log as required, but this option can be used to limit how big the event log will grow to. The maximum can be adjusted at run-time (see the `bset-event-log-size' command). Note that depending on system resources, less than <size> may be available (it is not advised to allow UndoDB to consume all the system's memory, lest the Linux "Out Of Memory Killer" kick in). See also the --undodb-event-log-max command-line option.

bset-event-log-mode circular | straight

If `circular' then a circular buffer is used to store events. This means that if the debuggee runs for a long time, it may not be possible to go back to the beginning. Default is `straight'. See also the --undodb-set-event-log-mode command-line options.

bset-shared-mem-mode <0 | 0 | 1 | 2 | 3

Control UndoDB's behavior with shared memory. See the --undodb-set-shared-mem-mode command-line option for details of what the modes mean.

UndoDB keeps track of time using `simulated nanoseconds'. These units approximate nanoseconds if the program were to be run outside of the debugger. These units are somewhat abstract - they do not model real-life nanoseconds exactly.

Programs running under the control of UndoDB run in one of two modes. When a program is first executed, it is executed in record mode. This means that this is the first time we've executed the code. Once we step backwards in time through any of the `b' commands, we are in replay mode. For example, if the first thing the user does at the prompt after starting undodb-gdb is to issue the `run' command, the program will be started in record mode. If after two seconds the user interrupts the program and steps backwards two instructions, then the program will be in replay mode. If the user steps forward one instruction, the program is still in replay mode. If the user steps forward a second instruction, the program switches back to record mode. The program will remain in record mode until the user moves backwards in time.

There can sometimes be a significant difference in the time programs take to execute in record and replay modes. Generally, when in record mode, a program will run slower than in "real life" (exactly how much slower depends varies a lot between programs, though a slow-down of around 1.7x is typical for CPU-intensive applications). When running forwards in replay mode, a program can run considerably faster that this, and sometimes even faster than it would run in "real life". Running backwards will generally be around ten times slower than running forwards in replay mode.

Although there is no correlation between wall-time and simulated nanoseconds, the measurement of time is perfectly repeatable - if an event (such as the execution of a particular instruction or receiption of a signal) happened at time X in record mode, then that event will always happen at precisely time X in replay mode.

Any side-effects a program has on the rest of the system do not occur when in replay mode. For example, if a program issues a printf, then when the printf is encountered in record mode, text is displayed on stdout. However, when the printf is replayed, no output is generated. As another example, if a file is unlinked, in record mode the file will be really unlinked from the file-system; when in replay mode, the program will not really interact with the operating system. Instead, whatever result the system returned at the unlink in record mode is replayed to the process in replay mode.

UndoDB creates many extra processes, usually around thirty in normal operation, but many more in certain pathological situations. These will appear in the output of the ps command. (See the documentation of the --undodb-snapshots command-line option below for more on this.)  

OPTIONS

--undodb-x32

This option must be passed if debugging a 32-bit executable on a 64-bit host.

--undodb-gdb <gdb>

Sets the location of gdb. The default is simply `gdb'.

--undodb-event-log-max <size>[M|K]

Maximum size of the event log UndoDB will use. The maximum may be modified at run-time using the `bset-event-log-size' command (see that command's documentation above for more details). To find the default heap size, specify a negative number - the heap size will be displayed by UndoDB when your program is started. Append `M' or `K' to specify the heapsize in Megabytes or Kilobytes respectively.

--undodb-event-log-mode straight | circular

Controls what happens when the maximum event log is consumed or no more memory may be allocated from the system in order to grow the event log. If `circular' then a circular buffer is used to store events. This means that if the debuggee runs for a long time, it may not be possible to go back to the beginning. Default is `straight'. This may be toggled at run-time using the `bset-event-log-mode' command. If the maximum event log size is reached, UndoDB will stop execution of the debuggee and display a message explaining that the event log is full. At that point the maximum event log size can be increased or the event log set to circular, and then execution of the debuggee can be continued.

--undodb-checkupdates yes | auto | no | never | ask

Controls whether undodb-gdb will check for a newer release at start-up. If `auto' or `never', the setting is used by default next time. The default is `auto', which checks once per day.

--undodb-set-shared-mem-mode <value>

Control what happens when debuggee attempts to map shared memory (i.e. use of mmap() with the MAP_SHARED flag or use of shmat()).

<value> = 0

Execution of the debuggee is halted. (The mode may then be adjusted.)

<value> < 0

Return error <value> from the system call.

<value> = 1

Use unshared memory in place of the shared memory. In practice this means the MAP_SHARED flag to mmap() is ignored and that shmat() is turned into an equivalent but unshared mmap(). Also, when attaching to a process any shared maps are remapped as unshared.

<value> = 2

Use the MMU to trap and record all shared-memory access. This can be quite slow if the debuggee makes very frequent accesses to shared memory.

<value> = 3

Use UndoDB's optimized binary translation based shared memory support. Even debuggee's which make very heavy use of shared memory should perform well with this mode.

The default is the highest value supported by your license. There is usually no reason to change this setting, although if your license does not support mode 3 then mode 1 may perform better than mode 2, but of course may affect the operation of your debuggee.

May be modified at run-time using the `bset-shared-mem-mode' command.

--undodb-optimize-shlibs

Speeds up programs that use large shared libraries. However, this optimization assumes that shared libraries the debuggee program uses do not change during the lifetime of the program. If the shared libraries are updated during the debugging session, the results are undefined.

--undodb-snapshots <n>

Rather than recording in the log everything the debuggee does, UndoDB uses a snapshot-and-replay technique. This option is a hint to UndoDB as to how many snapshots to preserve. Snapshots are implemented using "fork", meaning one process is used per snapshot. Too many snapshots leads to poor performance due to pressure on system resources, and too few can mean that backwards operations take a long time to complete. Generally UndoDB will attempt to keep no more than <n> snapshots, but more may be required in some situations. The default value is 35.

--undodb-instr-heapsize <size>[M|K]

UndoDB uses dynamic binary translation in order to instrument the running debuggee. This option controls the size of the translation cache. The default is 16MB, which will allow approximately 1.6MB of x86 native code to be stored. Programs with a very large working set of instructions may benefit from a larger value. There is no way to change this value at run-time.

--undodb-instr-reclaim yes | no

If `yes' then when the translation cache is full not recently used translations are ejected. If `no', execution of the debuggee is haulted if the translation cache becomes full. The default is `yes'. There is no way to change this value at run-time, but there is usually no need to change from the default.

--undodb-keyfile <path>

Gives a path to the UndoDB keyfile. By default UndoDB will search for a file named `key' in the current working directory, in the directory in which it's installed and in the user's home directory.

--undodb-heapsize <size>[M|K]

Size of UndoDB's fixed internal heap. Specifying a negative number will show the default heap size when your program is started. UndoDB is designed never to need more internal heap than the default, so there is usually no need to use this option.

USE WITH DDD

FILES

~/.undodb

Used to store some preferences which are chosen by the user at run-time. Not human-readable.

EXAMPLES

ddd --debugger undodb-gdb myprogram  

SUPPORTED SYSTEMS

Red Hat Enterprise Linux 3, 4 and 5.

Fedora 9, 10, 11 and 12.

SuSE Enterprise Linux 10 and 11.

Ubuntu 6.06, 8.04, 8.10, 9.04 and 9.10.

Debian Sarge, Etch, Lenny and Sid.

undodb-gdb will run on most other reasonably modern Linux distributions and versions.

STARTUP

Warnings on startup

When undodb-gdb starts, it may display warnings about not being unable to debug pthreads and/or a warning about `undefined symbol: td_ta_map_id2thr' and/or a warning about being unable to find libthread_db. These can all be safely ignored.

Checking for updates

undodb-gdb will check whether a newer version is available on undo-software.com's server. This checking can be controlled with the --undodb-checkupdates option.

LIMITATIONS

OS/CPU

UndoDB works on Linux on x86 CPUs (32-bit and 64-bit). Programs which use the Intel AMD 3DNow! and other extended AMD instructions are not supported. (Programs that use SSE, SSE2, SSE3 and SSE4 are supported.)

Threads on old kernels

UndoDB supports multi-threaded programs only if the underlying kernel provides the futex system call, which was introduced in Linux 2.5.40 (and back-ported to some 2.4 series kernels shipped with some Red Hat distributions, such as RHEL3).

Threads are hidden from gdb

undodb-gdb hides the existence of threads from gdb, so gdb's info threads and thread commands do nothing. The new commands binfo threads and bthread <n> commands can be used instead. Note that there is currently no equivalent to gdb's thread apply ... command.

Exec

UndoDB does not support the execve system call, as used by libc's execl() execlp() , execle() , execv() , execvp() and execve() functions.

Disk usage

Depending on the debuggee, UndoDB can create large temporary files within /tmp

Attaching to existing debuggees with --pid

UndoDB requires ld and objcopy to be present when attaching to an existing debuggee; they are usually already installed on Linux development machines.

SIGKILL

UndoDB cannot continue if the debuggee is terminated by SIGKILL. Instead, the debugging session is closed immediately as with a conventional debugger.

Statically-linked debuggees

UndoDB cannot start a statically-linked debuggee. However it can attach to an existing statically-linked debuggee process.

Use of gdb user defined command-hooks

undodb-gdb uses `user defined commands' to hook most of gdb's standard commands, so these hooks are not available to the user.

Pagination not supported in UndoDB commands

Pagination on UndoDB commands is disabled due to the way gdb interfaces with UndoDB itself. Pagination still works with gdb commands, however.

Consult undodb-limits(1) for other, rather more obscure limitations of UndoDB  

BUGS

Use with GNU gdb 6.3-5mdk (Mandriva Linux release 2006.0)

There seems to be a bug in this gdb where the `info line ...' command can cause a SIGSEGV. undodb-gdb uses `info line ...' internally, so this can prevent undodb-gdb from working. Replacing the default gdb with a vanilla build of gdb-6.4 or later will fix this.

Backwards stepping when in non-debug code can fail silently

Some undodb-gdb commands (e.g. bnext can fail silently if the program is in a function with no debugging information. (The ultimate cause of this is that gdb user-defined commands terminate silently if a sub-command fails).

Use in a Midnight Commander terminal

undodb-gdb has problems when run from Midnight Commander's terminal - it appears to go into the background.

Spurious SIGCHLD signals with old Linux kernels

The debuggee may receive extra SIGCHLD signals when run with undodb-gdb on Linux kernel 2.4.x. gdb passes SIGCHLD silently to the debuggee by default, and the default is to ignore SIGCHLD, so this will not normally be noticeable.

The first stepi after a system call returns may appear to do nothing.

Subsequent stepi's will work as expected, however.

If you come across other problems, please email the details to support@undo-software.com Please include as much information as you can, for example the output from uname -a and as much of the output from undodb-gdb as possible.  

SEE ALSO

http://undo-software.com/

gdb(1)

ddd(1)

undodb-limits(1)  

COPYRIGHT

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

USE WITH DDD

FILES

EXAMPLES

SUPPORTED SYSTEMS

STARTUP

LIMITATIONS

BUGS

SEE ALSO

COPYRIGHT