rr(1)

✨ NAME ✨

rr — record and replay application execution 💅

🌈 SYNOPSIS 🌈

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

🦋 DESCRIPTION 🦋

okay so bestie, rr records an application's execution and then lets you replay it. literally time travel but for processes. no cap. 🕰️✨

Below are the options, grouped by vibe. The common ones work everywhere, and then each subcommand has its own little stash of flags. 👑

💖 Common options 💖

• -A <name>, --microarch=<name> — forces rr to pretend it's running on a CPU whose microarch is name, even when runtime detection is out here saying otherwise. name should be a string like Ivy Bridge. it's giving "trust me bro, I know my CPU" 🧠
• -C {on-syscalls,on-all-events,<from-time>}, --checksum={on-syscalls,on-all-events,<from-time>} — compute and store checksums (while recording) or read and verify them (while replaying) for every one of a tracee's memory mappings. when do they get checked? your choice: at the end of all syscalls (on-syscalls), at all events (on-all-events), or starting from a global timepoint from-time. pick your fighter ⚔️
• -D {<syscall-num,-<signal-num>}, --dump-on={<syscall-num,-<signal-num>} — dumps memory at a syscall or signal into the file tid.time_{rec,rep} inside trace-dir. _rec is for dumps during recording, _rep is for dumps during replay. two eras, two suffixes 🫶
• -F, --force-things — forces rr to do things that don't seem like good ideas, such as launching an interactive emergency debugger when stderr isn't a tty. chaos mode activated, proceed with caution 💀
• -K, --check-cached-mmaps — verifies that cached task mmaps actually match /proc/maps. vibe check on your memory map 🧚
• -E, --fatal-errors — any warning or error that gets printed is treated as fatal. zero tolerance policy, periodt 🚫
• -M, --mark-stdio — marks stdio writes with [rr <pid> <ev>], where ev is the global trace time at which the write happens and pid is the pid of the process it happens in. little receipts for every write 📝
• -N, --version — prints the version number and dips. bye bestie 👋
• -S, --suppress-environment-warnings — suppresses warnings about issues in the environment that rr has no control over. not her fault, not her problem 💅
• -T <time>, --dump-at=<time> — dumps memory at global timepoint time 📸
• -V, --verbose — logs messages that may not be urgently critical to the user. the yapping setting, we love her 🗣️
• -W <num-secs>, --wait-secs=<num-secs> — waits num-secs seconds right after startup, before kicking off recording or replaying. lil pause for dramatic effect ⏸️

🎀 Syntax for record 🎀

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

• -b, --force-syscall-buffer — forces the systall buffer preload library to be used, even though that's probably a bad idea. bestie why 😭
• -c <num>, --num-cpu-ticks=<num> — the maximum number of CPU ticks (currently retired conditional branches) a task gets to run before it gets interrupted. tick tock ⏰
• -e <num>, --num-events=<num> — the maximum number of events (syscall enter/exit, signal, CPU interrupt, ...) a task gets before it gets descheduled. event budget, spend it wisely 🎟️
• -i <signal>, --ignore-signal=<signal> — blocks signal from being delivered to tracees; probably only useful for unit tests. niche but iconic 🧪
• -n, --no-syscall-buffer — disables the syscall buffer preload library even if it would otherwise be used. hard pass on the buffer 🚫
• -u, --cpu-unbound — lets tracees run on any virtual CPU (the default is to bind to CPU 0). heads up though: this option can cause replay divergence, so use with caution ⚠️✨
• -v <name>=<value>, --env=<name>=<value> — a value to add to the environment of the tracee; you can have any number of these. stack 'em up 🥞

🌸 Syntax for replay 🌸

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

• -a, --autopilot — replays without a debug server. she's got this, no copilot needed ✈️
• -d <command>, --debugger=<command> — uses command as the gdb(1) command. bring your own debugger 💅
• -f <pid>, --onfork=<pid> — starts a debug server when pid has been forked and the target event has been reached. new process just dropped 👶
• -g <event-num>, --goto=<event-num> — starts a debug server on reaching event-num in the trace; peep -M in the general options for the deets. fast travel to an event 🌀
• -p {<pid>,<command>}, --onprocess={<pid>,<command>} — starts a debug server when pid or command has been exec'd and the target event has been reached. exec'd means it's main character time 🎬
• -q, --no-redirect-output — doesn't replay writes to stdout/stderr. silence, but make it intentional 🤫
• -s <port>, --dbgport=<port> — only starts a debug server on port; it won't automatically launch the debugger client too. DIY debugger client, you got this 🛠️
• -t <event>, --trace=<event> — singlesteps instructions and dumps register states when replaying towards event or later. step by step, register by register 👣
• -x <file>, --gdb-x=<file> — executes gdb(1) commands from file. scripted slay 📜

⭐ 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. everything, everywhere, all at once 🫶

• -b, --syscallbuf — dumps syscallbuf contents. peek inside the buffer 🧺
• -m, --recorded-metadata — dumps recorded metadata. the lore, archived 📚
• -p, --mmaps — dumps mmap data. memory map reveal 🔍
• -r, --raw — dumps trace frames in a more easily machine-parseable format instead of the default human-readable format. for the robots 🤖
• -s, --statistics — dumps statistics about the trace. numbers!! we love numbers 📊

👑 AUTHORS 👑

rr was written by Robert O'Callahan, Chris Jones, Nathan Froyd and others. legends, all of them 🌟

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

and that's the whole page bestie — <rainbow>rr - record and replay application execution</rainbow>, from November 2015, version 4.0.1, manual section rr(1). go forth and replay 💖🎀🦋