UDB commands reference

This section lists the most important UDB commands.

These commands are summarized in the printable Quick Reference Guide (PDF).

See the GDB manual, Debugging with GDB, for other commands.

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 execution 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.

If any thread hits a breakpoint or receives a signal, execution stops.

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

In multi-threaded programs, all execution commands progress the selected thread as requested, for example, the stepi command executes one instruction in the selected thread. Other threads will also be executed in the background, if necessary. This may cause the program to make a noticeable amount of progress, for example if the selected thread is blocked in a system call, other threads will continue to run until the system call exits.

Use the thread command to change the selected thread.

continue [ignore-count]

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

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, hits a breakpoint, or stops on a signal.

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.

next [count]

Continue the execution of the program until it reaches the beginning of a different source line (not counting subroutine calls), until it reaches the end of execution, hits a breakpoint, or stops on a signal.

Behaves like step as long as subroutine calls do not happen; when they do, execution does not stop at source lines in subroutine calls.

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.

The optional count argument tells UDB to step that many times, or until it reaches the end of execution, hits a breakpoint, or stops on a signal.

nexti [count]

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.

The optional count argument tells UDB to step that many times, or until it reaches the end of execution, hits a breakpoint, or stops on a signal.

Note

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

step [count]

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

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.

The optional count argument tells UDB to step that many times, or until it reaches the end of execution, hits a breakpoint, or stops on a signal.

stepi [count]

Execute one instruction.

The optional count argument tells UDB to step that many times, or until it reaches the end of execution, hits a breakpoint, or stops on a signal.

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.

Specify an argument of 0 to step forward exactly one instruction through execution history, without the requirement to remain in the same thead.

until

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

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 any thread hits a breakpoint or receives a signal, execution stops.

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

If the program has multiple threads, then (except for reverse-continue), 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.

Note

The reverse-execution commands are not, in general, the opposites of the corresponding forward-execution commands, because of their behaviour with respect to subroutine calls. For example, the next command may step out of a subroutine call, but the reverse-next command will not step backwards into the subroutine call.

If you have just run a command and want to get back to the point in recorded history before you did so, use the ugo undo command.

reverse-continue [ignore-count]

Execute program backward until it reaches the start of execution history, hits a breakpoint, or stops on a signal.

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 just before calling the function in the selected stack frame, or until it reaches the start of execution history, hits a breakpoints, or stops on a signal.

You can go to the beginning of a function call by using reverse-finish to execute backwards until just before the function, followed by step to execute forwards to the first line of the function.

reverse-next [count]

Execute program backward until it reaches a different source line (not counting subroutine calls), until it reaches the start of execution history, hits a breakpoint, or stops on a signal.

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.

The optional count argument tells UDB to step that many times, or until it reaches the start of execution history, hits a breakpoint, or stops on a signal.

reverse-nexti [count]

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, stopping at breakpoints and signals.

The optional count argument tells UDB to step that many times, or until it reaches the start of execution history, hits a breakpoint, or stops on a signal.

reverse-step [count]

Execute program backward until it reaches a different source line, until it reaches the start of execution history, hits a breakpoint, or stops on a signal.

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

The optional count argument tells UDB to step that many times, or until it reaches the start of execution history, hits a breakpoint, or stops on a signal.

reverse-stepi [-any-thread] [count]

Step program backward exactly one instruction.

-any-thread

Step back exactly one instruction through execution history, without the requirement to remain in the same thread.

The optional count argument tells UDB to step that many times, or until it reaches the start of execution history, hits a breakpoint, or stops on a signal.

reverse-until

Execute program backward until it reaches a lower-numbered source line (not counting subroutine calls), until it reaches the start of execution history, hits a breakpoint, or stops on a signal.

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 a 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.

Time-travel commands do not stop at breakpoints or signals.

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

ugo bookmark

See Bookmarks.

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

See ugo time.

ugo undo

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

For example:

recording 81,797> info time -a
Current time is: 81,797:0x5555555554a7 (in recorded range: [1 - 81,797])
recording 81,797> 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% 81,156> ugo undo
Have switched to record mode.

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

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

New in version 6.4.

ugo wallclock

See Log Jump.

last [-f|-forward] [expression]

Jump to the last time in execution history when the value of expression was modified. See When did an expression last change value?.

New in version 6.9.

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.

set time-limits min bbcount

Set the minimum time limit to bbcount.

unset time-limits min

Unset the minimum time limit.

set time-limits max bbcount

Set the maximum time limit to bbcount.

unset time-limits max

Unset the maximum time limit.

show time-limits

The minimum and maximum time limits.

Inspection commands

These commands inspect the state of the program being debugged.

info event-log-size

info events

See Event log.

info 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.

info snapshots

See Snapshots.

info time

See info time.

info wallclock

See Log Jump.

info wallclock-extent

See Log Jump.

Configuration commands

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

set max-event-log-size size

show max-event-log-size

set event-log-mode circular|straight

show event-log-mode

set replay-standard-streams on|off

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

show replay-standard-streams

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

set share-usage-statistics on|off

Set whether UDB usage statistics may be shared with Undo.

This option is saved across invocations of UDB.

Please see our privacy policy.

show 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.

show 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.