Recording forks with live-record

By default, live-record only records the process specified on the command line as a command or a pid. If that process forks child processes, the children are not recorded. The --on-fork option allows you to control what happens when the recorded process forks.

Using --on-fork

The --on-fork option accepts three values:

parent (default)

Child processes are not recorded.

child

When the parent process forks, live-record detaches and saves a recording of the parent at the fork, and starts a new recording of the child process.

both

When the parent process forks, live-record continues to record the parent and starts a new recording of the child process.

Basic usage:

# Record only the parent (default behavior)
live-record --on-fork parent ./my_program

# Follow the child, stop recording the parent
live-record --on-fork child ./my_program

# Record parent and children
live-record --on-fork both ./my_program

The --on-fork option is propagated when recording a forked child, making it possible to record an entire process tree.

Note

The --on-fork option does not change the behavior if the process execs. See the later section on using --on-fork with --record-on program:PROGRAM for recording process trees that fork and exec.

The behaviour can also be controlled with the UNDO_live_record_on_fork environment variable.

Saving recordings

When using using --on-fork both, live-record creates separate recordings for each process and automatically names them. For example, if your program’s parent process is process id 1234, and a child process is forked with process id 5678:

live-record --on-fork both ./myapp

This creates two recordings: - myapp-1234-TIMESTAMP.undo — Recording of the parent process - 5678-TIMESTAMP.undo — Recording of the child process

If the program forks multiple times, each child process gets its own recording. Each recording file is completely self-contained.

As the --on-fork functionality is likely to produce multiple recordings, using the -o or --recording-file options are not allowed. The option --recording-dir DIRECTORY option may be specified to put all the recordings in DIRECTORY. The --save-on options are compatible with --on-fork , with each recorded process being considered separately. For example, if you use --on-fork both with --save-on error only processes that end in an error are saved, regardless of their relationship to other processes. The default remains --save-on always.

Each recorded process has its own associated live-record process, with all live-record processes associated with a process tree being in the same process group. It is possible to control these processes individually or as a group:

  • A signal sent to a live-record pid only affects that particular recording.

  • A terminal signal (for example SIGINT from control-C on the terminal) affects all live-record processes in that process tree.

  • A signal sent to the process group (for example using the negative pid syntax kill -usr1 -<pgid>) affects all live-record processes in the group. For example, sending SIGUSR1 to all processes causes all program:live-record: processes to detach and save.

For example, to detach and save the recording of a single process:

$ ps -efj | { head -1; grep live-record; }
UID          PID    PPID    PGID     SID  C STIME TTY          TIME CMD
ismith    140198    2626  140198  128899  0 15:58 pts/4    00:00:00 /home/user/undo/undolr/live-record_x64 --on-fork both ./test_long_running
ismith    140220    2626  140198  128899  1 15:58 pts/4    00:00:00 /home/user/undo/undolr/live-record_x64 -p 140218 --on-fork both

$ kill -usr1 140220

To detach and save the recordings from all processes in a process tree:

$ ps -efj | { head -1; grep live-record; }
UID          PID    PPID    PGID     SID  C STIME TTY          TIME CMD
ismith    140198    2626  140198  128899  0 15:58 pts/4    00:00:00 /home/user/undo/undolr/live-record_x64 --on-fork both ./test_long_running
ismith    140220    2626  140198  128899  1 15:58 pts/4    00:00:00 /home/user/undo/undolr/live-record_x64 -p 140218 --on-fork both

$ kill -usr1 -140198

See Using the LiveRecorder tool for further information about controlling live-record with signals.

Note

This grouping refers only to live-record` processes, not to the recorded processes. The process groups of the recorded processes are preserved by live-record.

Unsupported options

Most options are supported with --on-fork and are propagated to forked children, with the following exceptions:

Using with --record-on program:PROGRAM

The --on-fork option does not affect the behavior at an exec system call. It can be combined with --record-on program: to enable recording of process trees that use both fork and exec.

Note

If your program forks then execs immediately, --on-fork produces a trivial recording between the fork and exec. In this case it is best to use --record-on program:PROGRAM without --on-fork . The --on-fork option is intended for use with programs with interesting code after the fork.

When using --on-fork and --record-on program:PROGRAM together, the following rules apply:

  • --record-on propagates through the whole process tree.

  • Any time --record-on matches its pattern it begins recordings (starting it again if the current PID previously stopped recording).

  • --on-fork determines which processes are recorded after a fork system call.

For example:

live-record --on-fork both --record-on program:worker_process ./launcher

This starts recording when worker_process begins, in parent or any child. When recording has started, both the parent and child processes are recorded if worker_process forks.

Debugging recordings

Each recording created can be loaded independently into UDB:

# Load the parent process recording
udb myapp-1234-2025-09-22T14-56-06.572.undo

# Or load a child process recording
udb 5678-2025-09-22T14-56-06.803.undo

You can debug each process independently, set breakpoints, examine memory, and use all standard UDB debugging features on each recording.

Equivalent GDB Commands

The --on-fork option provides similar functionality to GDB’s set detach-on-fork and set follow-fork commands.

live-record option

Similar GDB command

--on-fork parent

set follow-fork-mode parent

--on-fork child

set follow-fork-mode child

--on-fork both

set detach-on-fork off