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
r 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]
c [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
fin

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]
n [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]
ni [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.

resume

Resume the execution of a command which was prematurely stopped by hitting a breakpoint or watchpoint, or by stopping at a signal.

This is useful when you execute a command, for instance next, to reach a specific point in the program, but the program stops before that at a breakpoint that is not interesting or relevant to what you are currently investigating. For example:

main () at cache.c:65
65          cache_init();
3% 8,304> list
60      }
61
62      int
63      main(void)
64      {
65          cache_init();
66
67          /* Repeatedly check cache_calculate(). */
68          int i;
69          for (i = 0;; ++i)
3% 8,304> next

Breakpoint 2, cache_init () at cache.c:23
23          for (i = 0; i < g_cache_size; ++i)

The command was interrupted because a breakpoint was hit, so execution may
have stopped at a different location than expected. Use the "resume" command
to resume the operation without stopping at breakpoints, watchpoints, or
signals.
3% 8,305> resume
Resuming interrupted "next" command without stopping at breakpoints,
watchpoints, or signals.

69          for (i = 0;; ++i)

The resume command can only resume commands that have a specific stopping-point, such as the next command, which stops at the next source line, but not the continue command, which is normally used to run until a breakpoint is hit or the program exits.

step [count]
s [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]
si [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]
sit [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 thread.

until
u

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 behavior 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]
rc [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
rf

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]
rn [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]
rni [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]
rs [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]
rsi [-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.

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.

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 redo
ur

Reverse the effect of the ugo undo command.

New in version 6.4.

ugo time

See ugo time.

ugo undo
uu

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

For example:

recording 72,052> info time -a
Current time is: 72,052:0x5555555554bc (in recorded range: [1 - 72,052])
recording 72,052> 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% 71,444> ugo undo
Have switched to record mode.

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

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.

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|bookmark]

Set the minimum time limit to bbcount or bookmark. If no argument is given, use the current bbcount.

unset time-limits min

Unset the minimum time limit.

set time-limits max [bbcount|bookmark]

Set the maximum time limit to bbcount or bookmark. If no argument is given, use the current 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

See Multi-Process Correlation for Shared Memory.

info event-log-size

See 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 an Undo recording.

info snapshots

See Snapshots.

info time

See info time.

info timeline
it

Overview of key moments in execution history, including the current time, the previous time (in other words, where ugo undo would go), the Time limits if set, and any bookmarks that have been set.

New in version 8.0.

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 event-log-mode circular|straight

See set event-log-mode.

show event-log-mode

See show event-log-mode.

set history filename [path]

Set where to save command history (if set history save is on).

If path is omitted, then history saving is disabled.

By default, history is saved to $XDG_DATA_HOME/undo/udb/command_history.txt where $XDG_DATA_HOME, if unset, defaults to ~/.local/share/.

show history filename

Where to save command history (if set history save is on).

set history save [on|off]

Set whether to save command history to a file. Omitting the on or off arguments is equivalent to specifying on.

The up/down arrow keys (or control-P/control-N) navigate through previously typed commands. If history saving is set to on (the default), commands from the current session and previous sessions are available. Otherwise, only commands from the current session are available.

History is saved when UDB exits.

If set history filename is set to an empty string, no history is saved, even if this setting is on.

show history save

Whether to save command history to a file.

See the set history save command for details.

set max-event-log-size size

See set max-event-log-size.

show max-event-log-size

See show max-event-log-size.

set net-promoter-score [on|off]

Set whether UDB can prompt for a Net Promoter Score on exit.

The value of this option is saved across invocations of UDB.

show net-promoter-score

Whether collection of Net Promoter Scores is enabled.

See the set net-promoter-score command for details.

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 scheduler-locking on|off|step

Set the scheduler-locking mode. This controls which threads are allowed to run when the program is resumed. This only applies when in record mode.

The available modes are:

• off: There is no locking and any thread may run at any time.

• on: Only the current thread may run when the program being debugged is resumed.

• step: Behaves like off with commands that run the program freely (continue, finish, signal, until), and like on with stepping commands.

New in version 8.2.

show scheduler-locking

Show the current scheduler-locking mode.

set share-usage-statistics licensing-only|anonymized|on

Set which usage statistics are shared with Undo.

UDB collects some usage statistics to protect Undo from unlicensed or unlawful use of our software and services, plus some additional usage data to help us improve our products. This does not include any data about or from the programs being debugged.

By default, the additional usage data is anonymized. However, we encourage you to opt in to share full, and personally-identifying, usage statistics; this will help us to improve our products and to improve our customer support.

Valid values are:

• licensing-only: Only share information required for license enforcement.

• anonymized: As licensing-only, and also share anonymized additional usage data.

• on: As anonymized, but additional usage data is not anonymized. That is, full usage statistics are shared, and licensing data can be correlated with the additional usage data.

The value of this option is saved across invocations of UDB.

Please see our technical documentation and our privacy policy for more information on the data that UDB transmits and the reasons for our processing of the data.

Changed in version 7.0: Added the anonymized and licensing-only values and removed off to support the new usage statistics collection system.

New in version 6.3.

show share-usage-statistics

Show whether UDB usage statistics are being shared with Undo.

See the set share-usage-statistics command for details.

Changed in version 7.0: Added the anonymized and licensing-only values and removed off to support the new usage statistics collection system.

New in version 6.3.

uexperimental set timeline-file FILE

Set a file to which a timeline will be written in Markdown format. The file will be updated when the current time changes, or when bookmarks are created or deleted.

The intended use is with editors which can automatically refresh their view of a file when it changes. The editor window then acts as a live view of the timeline.

Warning

When this command is combined with uexperimental set timeline-probe-file FILE, the entire execution history is scanned for Post Failure Logging output every time a command is executed which can update the timeline file, such as any forward-execution, reverse-execution, or time-travel operation. This severely affects UDB’s responsiveness when used with long recordings.

uexperimental unset timeline-file

Unset the configured timeline output file.

uexperimental show timeline-file

The currently configured timeline output file.

See the uexperimental set timeline-file FILE command for details.

uexperimental set timeline-probe-file FILE

Set a Post Failure Logging probe file to be used when info timeline is executed.

See Post Failure Logging for details of writing probe files.

uexperimental unset timeline-probe-file

Unset the Post Failure Logging probe file to be used when info timeline is executed.

uexperimental show timeline-probe-file

The currently configured Post Failure Logging probe file. This file will be used when info timeline is executed.

See the uexperimental set timeline-probe-file FILE command for details.

UDB session commands

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

show session

Show whether a UDB session is enabled.

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

usession clear

Clear the state associated with the currently loaded session.

All bookmarks, breakpoints and so on are deleted. The recording remains loaded and the current position in history is preserved.

New in version 6.3.

usession import file

Replace the current session state with data from file.

file must contain session state for the currently loaded recording; otherwise, the file is not imported.

Importing a file adds its state to your UDB session, so that it will be restored automatically the next time the recording is loaded.

New in version 7.2.

usession export file

Write out the current session state to file.

New in version 7.2.