Getting started with UDB¶

UDB is Undo’s time travel debugger. It records the execution history of a program, so that the program can be executed forward and backward and its state examined at any time in its history. This makes it possible to diagnose the cause of defects by executing backwards from incorrect results to the code that created the results.

UDB can also load recordings of your software created by LiveRecorder.

Terminal Visual Studio Code

Try the online tutorial: Getting started with UDB.

Launching a program in UDB¶

Terminal Visual Studio Code

Start udb, naming the program to be debugged on the command line:

$ udb examples/hashtable
Reading symbols from examples/hashtable...

Then use the run command in UDB to run the program with command-line arguments:

not running> run 12345
Starting program: examples/hashtable 12345
hashtable: hashtable.c:131: main: Assertion `table_contains(table, element)' failed.

Program received signal SIGABRT, Aborted.
__GI_raise (sig=sig@entry=6) at ../sysdeps/unix/sysv/linux/raise.c:50
50      ../sysdeps/unix/sysv/linux/raise.c: No such file or directory.

Alternatively, start udb with the --args command-line option to specify the program and its command-line arguments:

$ udb --args examples/hashtable 12345
Reading symbols from examples/hashtable...

Then use the run command in UDB to run the program with the arguments already given:

not running> run
Starting program: examples/hashtable 12345
hashtable: hashtable.c:131: main: Assertion `table_contains(table, element)' failed.

Program received signal SIGABRT, Aborted.
__GI_raise (sig=sig@entry=6) at ../sysdeps/unix/sysv/linux/raise.c:50
50      ../sysdeps/unix/sysv/linux/raise.c: No such file or directory.

See Invoking UDB for more details.

Open the project workspace. From the Run menu, select Add Configuration… and then

if the workspace does not yet have a .vscode/launch.json file, select C/C++ (UDB) to create default set of launch configurations; or
if the workspace already has a .vscode/launch.json file, select C/C++: (UDB) Launch to add a UDB launch configuration to your existing set of launch configurations.

In either case, Visual Studio code opens the .vscode/launch.json file. In the launch configuration, set the "program" field to the program to be debugged, and the "args" field to the list of command-line arguments.

If UDB is not runnable via the PATH environment variable, set the "miDebuggerPath" field to the path to UDB.

See the Launch configurations documentation for other options controlling the behaviour of the Time Travel Debug for C/C++ extension.

From the View menu, select Run (Ctrl+Shift+D) and from the drop-down menu at the top of the side bar, select (UDB) Launch.

From the Run menu, select Start Debugging (F5) to launch the program. Or click the green triangle.

Attaching to an existing process¶

Terminal Visual Studio Code

Attach UDB to a running process using the udb --pid PID command-line option. For example:

$ examples/deadlock &
Running as pid 2281491
$ udb --pid 2281491

No more reverse-execution history.
Reading symbols from /lib/x86_64-linux-gnu/libpthread.so.0...
Reading symbols from /usr/lib/debug/.build-id/f0/983025f0e0f327a6da752ff4ffa675e0be393f.debug...
Reading symbols from /lib/x86_64-linux-gnu/libc.so.6...
Reading symbols from /usr/lib/debug//lib/x86_64-linux-gnu/libc-2.31.so...
Reading symbols from /lib64/ld-linux-x86-64.so.2...
(No debugging symbols found in /lib64/ld-linux-x86-64.so.2)
Have reached start of recorded history.
0x00007fa147636cd5 in __pthread_clockjoin_ex (threadid=140330662065920, thread_return=0x0, clockid=<optimized out>, abstime=<optimized out>, block=<optimized out>) at pthread_join_common.c:145
145     pthread_join_common.c: No such file or directory.
recording 1> info threads
  Id   Target Id              Frame
* 1    Thread 2281491.2281491 0x00007fa147636cd5 in __pthread_clockjoin_ex (threadid=140330662065920, thread_return=0x0, clockid=<optimized out>, abstime=<optimized out>, block=<optimized out>) at pthread_join_common.c:145
  2    Thread 2281491.2281492 __lll_lock_wait (futex=futex@entry=0x5557a79a6078 <g_lists+56>, private=0) at lowlevellock.c:52
  3    Thread 2281491.2281493 __lll_lock_wait (futex=futex@entry=0x5557a79a6040 <g_lists>, private=0) at lowlevellock.c:52

From the Run menu, select Add Configuration… and then C/C++: (UDB) Attach. In the launch configuration, set the "program" field to the program to be debugged.

From the View menu, select Run (Ctrl+Shift+D) and from the drop-down menu at the top of the side bar, select (UDB) Attach.

From the Run menu, select Start Debugging (F5). Or click the green triangle. Then, from the menu, select the process to debug, for example, by searching for the name of the executable.

Select the Pause button in the toolbar (F6) to pause the program in order to inspect its variables and call stack, or the Disconnect button (Shift+F5) to stop debugging and allow the program to continue.

Forward and reverse execution¶

Terminal Visual Studio Code

To execute the program forward, use the execution commands. For example, the step command executes the program forward to the next source line, and the continue command continues execution of the program until a breakpoint is hit or the program stops on a signal.

To execute the program backward, use the reverse-execution commands. For example, the reverse-step command executes the program backward to the previous source line, and the reverse-continue command executes the program backward until a breakpoint is hit, or the program stops on a signal, or it reaches the start of execution history.

To execute the program forward, use the forward-execution buttons in the toolbar. For example, the Step Into button (F11) executes the program forward to the next source line, and the Continue button (F5) continues execution of the program until a breakpoint is hit or the program stops on a signal.

To execute the program backward, use the reverse-execution buttons in the toolbar. For example, the Reverse Step Into button (Ctrl+F11) executes the program backward to the previous source line, and the Reverse Continue button (Ctrl+F5) executes the program backward until a breakpoint is hit, or the program stops on a signal, or it reaches the start of execution history.

Other methods of navigation¶

Terminal Visual Studio Code

Use the ugo start or ugo end commands to jump to the beginning or end of the program’s execution history.

Use the ugo undo command to undo the last command that changed the time in execution history.

Jump to a point in the middle of the program’s execution history by jumping to a bookmark that you’ve previously created (see Bookmarks), or by jumping to a wall-clock time (see Log Jump).

Use the Goto Start and Goto End buttons in the toolbar to jump to the beginning or end of the program’s execution history.

Use the Undo button to undo the last command that changed the time in execution history, and the Redo button to reverse the effect of the Undo button.

Jump to a point in the middle of the program’s execution history using the Goto Bookmark button to jump to a bookmark that you’ve previously created using the Set Bookmark button (see Bookmarks), or use the Goto Time button to jump to a wall-clock time (see Log Jump).