UDB commands reference

Also see the printable Quick Reference Guide (PDF).

Starting and stopping the program

attach process-id

Attach to the process with the given id and start debugging it.

UDB starts debugging the program in record mode by default, so that reverse-execution commands and time-travel commands are available. To start in deferred-recording mode instead, use the Starting UDB with recording disabled configuration parameter.

detach

Detach UDB from the program being debugged. The program continues its execution from the latest point reached in its recorded history.

file filename

Specify the program that gets executed by the run, start, and starti commands.

If the program is not found in the current directory, UDB searches for it in the directories in the PATH environment variable.

run args

Start debugging a program in UDB. The program that gets executed is the one named by the most recent file filename command, if any, or the one named on the UDB command line.

UDB passes args as command-line arguments to the program, if given, or the arguments specified by the udb --args command-line option, otherwise.

UDB starts debugging the process in record mode by default, so that reverse-execution commands and time-travel commands are available. To start in deferred-recording mode instead, use the Starting UDB with recording disabled configuration parameter.

start args

Start debugging a program in UDB, stopping at the program’s main function. For programs written in C and C++, this is the function named main().

See the run command for other details.

starti args

Start debugging a program in UDB, stopping at the program’s first instruction.

See the run command for other details.

Executing the program

These commands execute the program in the forwards direction.

All execution commands are affected by the Time limits, if any.

continue [ignore-count]

Continue the execution of the program until it reaches the end of execution, or hits a breakpoint.

If the program was stopped due to hitting a breakpoint, the optional ignore-count argument tells UDB to stop only when the breakpoint is hit that many times.

finish

Continue the execution of the program until just after it returns from the selected stack frame, until it reaches the end of execution, or until it hits a breakpoint.

You can go to the end of a function call by using finish to execute forwards until the function returns, followed by reverse-step to execute backward to the last line of the function.

nexti

Execute one instruction (not counting subroutine calls).

Behaves like stepi as long as a subroutine call does not happen; when it does, execution continues through the subroutine call and stops on the instruction after the call.

Note

For the purposes of this command, “subroutine calls” don’t include inline function calls or tail calls.

step

Continue the execution of the program until it reaches the beginning of a different source line, or until it hits a breakpoint.

If the program is stopped at a location for which UDB lacks debugging information, execution continues until it reaches a location for which UDB does have debugging information.

stepi

Execute one instruction.

stepit [thread-id]

Execute one instruction in the current thread, or in the thread with the given id if the optional thread-id argument is provided. Other threads may or may not run.

This may cause the program to make a lot of progress in other threads, for example if the current thread is blocked in a system call, execution continues until the system call returns.

until

Continue the execution of the program until it reaches the beginning of a higher-numbered source line (not counting subroutine calls), until it reaches the end of execution, or until it hits a breakpoint.

Behaves like next as long as the program does not jump to a lower-numbered source line; when it does, execution continues until a higher-numbered source line is reached. Hence this command can be used to step out of a loop without going around again.

Note

This is actually implemented using program counter values rather than source line numbers, so that if an optimizing compiler moves code around, you may have to issue several until commands to get to a higher-numbered source line.

Executing the program in reverse

UDB must be in record mode or replay mode to use these commands. If UDB is in deferred-recording mode, use the urecord command to switch to record mode.

If the program has multiple threads, then (except for reverse-continue and reverse-stepi), it is the current thread that the described condition applies to. For example reverse-step runs backward to a new source line in the current thread. Other threads may or may not run.

All reverse-execution commands are affected by the Time limits, if any.

reverse-continue [ignore-count]

Execute program backward until it reaches the start of recorded history, or until it hits a breakpoint.

If the program was stopped due to hitting a breakpoint, the optional ignore-count argument tells UDB to stop only when the same breakpoint is hit that many times.

reverse-finish

Execute program backward to the line that called the current function.

reverse-next

Execute program backward until it reaches a different source line (not counting subroutine calls), or until it reaches the start of recorded history.

Behaves like reverse-step as long as subroutine calls do not happen; when they do, execution continues backward through the subroutine calls.

If the program is stopped at a location for which UDB lacks debugging information, this steps backward one instruction, like reverse-stepi.

reverse-nexti

Step program backward one instruction (not counting subroutine calls).

Behaves like reverse-stepi as long as a subroutine call does not happen; when it does, execution continues backward through the subroutine calls.

reverse-step

Execute program backward until it reaches a different source line, or until it reaches the start of recorded history.

If the program is stopped at a location for which UDB lacks debugging information, this steps backward one instruction, like reverse-stepi.

reverse-stepi

Step program backward exactly one instruction.

reverse-until

Execute program backward until it reaches a lower-numbered source line (not counting subroutine calls), or until it reaches the start of recorded history.

Behaves like reverse-next as long as the program does not jump to a higher-numbered source line; when it does, execution continues in reverse until a lower-numbered source line is reached. Hence this command can be used to step backward out of a loop without going around again.

Note

This is actually implemented using program counter values rather than source line numbers, so that if an optimizing compiler moves code around, you may have to issue several reverse-until commands to get to a lower-numbered source line.

Time-travel commands

These commands jump directly to time in the program’s execution history. UDB must be in record mode or replay mode to use these commands. If UDB is in deferred-recording mode, use the urecord command to switch to record mode.

All time-travel commands are affected by the Time limits, if any.

ugo bookmark

ugo start

Jump to the start of the program’s execution history.

ugo end

Jump to the end of the program’s execution history.

ugo pc pc

Jump backward to a program counter value.

That is, jump to the latest time in execution history before the current time, when the program counter had the specified value.

If the program did not reach the specified program counter, the time-travel operation fails.

ugo redo

Reverse the effect of the ugo undo command.

New in version 6.4.

ugo time

ugo undo

Undo the last command that changed the time in execution history.

For example:

recording 91,200> uinfo time -a
Current time is: 91,200:0x5555555553ab (in recorded range: [1 - 91,200])
recording 91,200> reverse-continue
Continuing.

Breakpoint 1, sine (x=0.00057270308) at sine.c:41
41          double halfpi = 1.5707963267948966;

At this point the ugo undo command returns to the time in execution history when the reverse-continue was started:

99% 90,479> ugo undo
Have switched to record mode.

Breakpoint 1, sine (x=1.12879349e-07) at sine.c:41
41          double halfpi = 1.5707963267948966;
recording 91,200> uinfo time -a
Current time is: 91,200:0x5555555553ab (in recorded range: [1 - 91,200])

The effect of the ugo undo command can itself be reversed using the ugo redo command.

New in version 6.4.

ugo wallclock

Time limits

It is easy to get lost in the execution history of a long-running program. Time limits prevent execution commands, reverse-execution commands and time-travel commands from going outside a range of bbcounts in execution history. These limits can be used to focus on a time of interest.

uset time-limits min bbcount

Set the minimum time limit to bbcount.

uclear time-limits min

Clear the minimum time limit.

uset time-limits max bbcount

Set the maximum time limit to bbcount.

uclear time-limits max

Clear the maximum time limit.

ushow time-limits

The minimum and maximum time limits.

Inspection commands

These commands inspect the state of the program being debugged.

uinfo execution-mode

The execution mode.

This indicates whether debugging has started, and if so, whether UDB is in record mode, replay mode, deferred-recording mode, or replaying a LiveRecorder recording.

uinfo snapshots

uinfo time

uinfo wallclock

uinfo wallclock-extent

Configuration commands

These commands update or query UDB’s configuration parameters. See Configuring UDB.

uset max-event-log-size size

ushow max-event-log-size

uset event-log-mode circular|straight

uset replay-standard-streams

Set whether to replay writes to standard output and standard error. See Replay standard streams.

ushow replay-standard-streams

Whether to replay writes to standard output and standard error. See Replay standard streams.

uset share-usage-statistics

Set whether UDB usage statistics may be shared with Undo.

This option is saved across invocations of UDB.

Please see our privacy policy.

ushow share-usage-statistics

Show whether UDB usage statistics are being shared with Undo.

This option is saved across invocations of UDB.

Please see our privacy policy.

UDB session commands

A UDB session is a record of user data associated with a LiveRecorder recording. Sessions preserve bookmarks referring to a recording; they are automatically loaded when the recording is loaded; and the session data is written to a subdirectory of the user’s configuration directory (for example, to ~/.local/share/undo/sessions/).

usession clear

Clear the UDB session data associated with the currently loaded session.

After clearing a session, the session data stored on-disk and in-memory are cleared. This command does not affect the current state of the session.

New in version 6.3.

ushow session

Show whether a UDB session is enabled.

A UDB session is enabled by default, and the user-created artefacts are saved and loaded automatically in the UDB session.