Pane.CaptureToFile

Description#

Printed captures cannot safely cross a control connection, so Pane.Capture and Pane.CaptureBytes use a subprocess or reject a connection. CaptureToFile stages through a scratch buffer so capture, save, and cleanup can all use the connection's command lanes.

path must name a file the tmux server can write and this process can read. It is replaced and left for the caller. A file this call creates has mode 0600, whatever the umask, because the screen it holds may be secret; a file that already exists keeps its mode. A relative path is made in the working directory p's Server was built in. If the capture fails, the file this call created is removed, except when ctx ended first. Concurrent calls must use distinct paths. The scratch tmux buffer is staged, saved, and deleted in one tmux command list, so a cancellation cannot land between those steps.

The scratch buffer is deleted before return on every path, including after ctx is cancelled or its deadline passes and when the capture reports an error after tmux ran it. That delete runs on a context detached from ctx's cancellation and bounded to two seconds, so a server that does not answer in that time delays the return by at most that long. A buffer tmux already reports absent is clean. If the delete fails, the failure is joined into the returned error, so an error that says the cleanup failed means a buffer may remain.

Safe named-buffer cleanup requires tmux 3.4 before staging. Other version gates match Pane.Capture. Capture, save, and file-read failures return an error with no lines. A call whose command list ran to completion before ctx ending was observed returns its lines and a nil error: the file is written and the buffer is gone, so ctx ending afterward does not turn that into a failure.