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¶
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.
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 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 undo¶
Undo the last command that changed the time in execution history.
For example:
recording 82,960> info time -a Current time is: 82,960:0x5555555554a7 (in recorded range: [1 - 82,960]) recording 82,960> 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% 82,310> ugo undo Have switched to record mode. Breakpoint 1, sine (x=1.12879349e-07) at sine.c:41 41 double halfpi = 1.5707963267948966; recording 82,960> info time -a Current time is: 82,960:0x5555555554a7 (in recorded range: [1 - 82,960])The effect of the
ugo undo
command can itself be reversed using the ugo redo command.New in version 6.4.
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 blame¶
info event-log-size¶
See info event-log-size.
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.
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¶
See set event-log-mode.
show event-log-mode¶
See 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.
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.