UNDODB-GDB

NAME

SYNOPSIS

DESCRIPTION

undodb-gdb is given the same parameters as gdb.

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:

bfinish

Step backwards out of the current function. A backwards equivalent to gdb's finish command. It will fail if there is no symbol for the start of the current function.

bnext

Step backwards out of current source line, skipping function calls. A backwards equivalent to gdb's next command.

bnexti

Step backwards out of current instruction, skipping function calls. A backwards equivalent to gdb's nexti command.

bstep

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

bstepi

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

buntil

Step backwards out of current source line, skipping function calls and local loops, but stopping if the program exits the current function. A backwards equivalent to gdb's until command. However, this is not exactly analogous to gdb's until It cannot be supplied with 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>

Run backwards to the specified position. Note that stepping backwards a long way (e.g. with bgoto main can take a long time - comparable to the time it takes to run forwards.

bgoton <number>

Move forwards or backwards to the specified time, in simulated nanoseconds.

bgoton +<number> | -<number>

Step forward/backward the specified number of simulated nanoseconds.

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

Finally, there are some commands for use with 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' timeslices.

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.

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. Whether in record mode or replay mode, it is not possible to modify the program's state, i.e. changing any memory or a variable's value or a a register's value is not supported.

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). In replay mode, a program can run considerably faster that this, and sometimes even faster than it would run in "real life". There is no correlation between wall-time and simulated nanoseconds, especially when UndoDB is running time backwards. However, the measurement of time is perfectly repeatable - if an event (such as a particular instruction's execution) happened at time X, that event will happen at precisely time X no matter how many times the program's execution is reversed and replayed.

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.  

OPTIONS

--undodb-gdb <gdb>

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

--undodb-heapsize <size>

Size of the fixed internal heap. A size of at least 8MB is recommended, but debugging sessions for programs that run a long time or do a lot of I/O may require more. 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-checkupdates yes | auto | no | never | ask

Controls whether we check for a newer release. If `auto' or `never', the setting is used by default next time. The default is `auto', which checks once per day.

--undodb-map-shared <value>

Control what happens when debuggee attempts to mmap with the MAP_SHARED flag:

<value> = 0 (the default)

Execution is halted.

<value> < 0

Return error <value> from the mmap syscall.

<value> = 1

Ignore the MAP_SHARED flag and map unshared. Also allow attachment to an existing debuggee with shared memory, by forcing all memory regions to be non-shared.

--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 were to be updated during the debugging session, the results are undefined.

--undodb-snapshots <n>

Control the number of 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.

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

Debian Sarge and Etch.

Fedora 7, 8 and 9.

Red Hat Enterprise Linux 3, 4, 5 and 5.1.

SuSE 10.2 and 10.3.

Ubuntu 6.06, 7.10 and 8.04.

undodb-gdb will run on most other 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'. These can 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 only works on 32-bit Linux on x86 CPUs. Programs which use the Intel SSE3, AMD 3DNow! and other extended AMD instructions are not supported. (Programs that use SSE and SSE2 are supported, however.)

Shared memory

UndoDB does not support programmes that use shared memory. This includes programs that mmap shared memory with other processes, and programs that mmap volatile files (i.e. files that are changed by other processes or the system during the process's execution).

Thus mmap() with the MAP_SHARED flag is not supported (though see the --undodb-map-shared option).

Similarly, ipc syscalls that involve shared memory are not supported - this means libc's shmat() shmctl() shmdt() and shmget() functions are not supported.

Threads on old kernels

UndoDB supports multi-threaded programmes only if the underlying kernel provides the __NR_futex syscall, 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 __NR_execve syscall, 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 gcc and objcopy to be present when attaching to an existing debuggee; they are usually already installed on Linux development machines. Attaching to a debuggee that is already using shared memory will fail; use --undodb-map-shared 1 to allow attachment by forcing all memory to be unshared.

SIGKILL

UndoDB will not work reliably when the debuggee is terminated by SIGKILL.

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 SEGV. 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 programme 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 noticable.

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-limits1  

COPYRIGHT

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

USE WITH DDD

FILES

EXAMPLES

SUPPORTED SYSTEMS

STARTUP

LIMITATIONS

BUGS

SEE ALSO

COPYRIGHT

Copyright © Undo Ltd, 2005-2008. Photography © SnapR