rr

Record an application

$ rr record [path/to/binary --arg1 --arg2]

$ rr replay

rr dump [<options>] [<trace-dir>] [<event-specs>]
rr gdbinit
rr help [<command>]
rr ps [<trace-dir>]
rr record [<options>] <executable> [<exe-args>]
rr replay [<options>] [<trace-dir>]

Common options

-A <name>, --microarch=<name>

force rr to assume it's running on a CPU with microarch name even if runtime detection says otherwise. name should be a string like `Ivy Bridge'.

-C {on-syscalls,on-all-events,<from-time>}, --checksum={on-syscalls,on-all-events,<from-time>}

compute and store (during recording) or read and verify (during replay) checksums of each of a tracee's memory mappings either at the end of all syscalls (on-syscalls), at all events (on-all-events), or starting from a global timepoint from-time.

-D {<syscall-num,-<signal-num>}, --dump-on={<syscall-num,-<signal-num>}

dump memory at syscall or signal to the file tid.time_{rec,rep} in trace-dir; _rec for dumps during recording, _rep for dumps during replay.

-F, --force-things

force rr to do some things that don't seem like good ideas, such as launching an interactive emergency debugger if stderr isn't a tty.

-K, --check-cached-mmaps

verify that cached task mmaps match /proc/maps.

-E, --fatal-errors

any warning or error that is printed is treated as fatal.

-M, --mark-stdio

mark stdio writes with [rr <pid> <ev>] where ev is the global trace time at which the write occurs and pid is the pid of the process it occurs in.

-N, --version

print the version number and exit.

-S, --suppress-environment-warnings

suppress warnings about issues in the environment that rr has no control over.

-T <time>, --dump-at=<time>

dump memory at global timepoint time

-V, --verbose

log messages that may not be urgently critical to the user

-W <num-secs>, --wait-secs=<num-secs>

wait num-secs seconds just after startup, before initiating recording or replaying.

Syntax for `record'

rr record [<options>] <executable> [<exe-args>]

-b, --force-syscall-buffer

force the systall buffer preload library to be used, even if that's probably a bad idea

-c <num>, --num-cpu-ticks=<num>

maximum number of `CPU ticks' (currently retired conditional branches) to allow a task to run before interrupting it

-e <num>, --num-events=<num>

maximum number of events (syscall enter/exit, signal, CPU interrupt, ...) to allow a task before descheduling it

-i <signal>, --ignore-signal=<signal>

block signal from being delivered to tracees; probably only useful for unit tests

-n, --no-syscall-buffer

disable the syscall buffer preload library even if it would otherwise be used

-u, --cpu-unbound

allow tracees to run on any virtual CPU (default is to bind to CPU 0); this option can cause replay divergence: use with caution

-v <name>=<value>, --env=<name>=<value>

value to add to the environment of the tracee; there can be any number of these

Syntax for `replay'

rr replay [<options>] [<trace-dir>]

-a, --autopilot

replay without debug server

-d <command>, --debugger=<command>

use command as the gdb(1) command

-f <pid>, --onfork=<pid>

start a debug server when pid has been forked, and the target event has been reached

-g <event-num>, --goto=<event-num>

start a debug server on reaching event-num in the trace; see -M in the general options

-p {<pid>,<command>}, --onprocess={<pid>,<command>}

start a debug server when pid or command has been exec'd, and the target event has been reached

-q, --no-redirect-output

don't replay writes to stdout/stderr

-s <port>, --dbgport=<port>

only start a debug server on port; don't automatically launch the debugger client too

-t <event>, --trace=<event>

singlestep instructions and dump register states when replaying towards event or later

-x <file>, --gdb-x=<file>

execute gdb(1) commands from file

Syntax for `dump`

rr dump [<options>] [<trace-dir>] [<event-specs>]

Event specs can be either an event number like `127', or a range like `1000-5000'. By default, all events are dumped.

-b, --syscallbuf

dump syscallbuf contents

-m, --recorded-metadata

dump recorded metadata

-p, --mmaps

dump mmap data

-r, --raw

dump trace frames in a more easily machine-parseable format instead of the default human-readable format

-s, --statistics

dump statistics about the trace

rr was written by Robert O'Callahan, Chris Jones, Nathan Froyd and others.

This manual page was adapted from the help output by Stephen Kitt <skitt@debian.org>, for the Debian GNU/Linux system (but may be used by others). It was last modified for rr version 4.0.1.