Client.capture
Acquire a complete graph over a recorded interval, with a fixed number of listing commands. Races fail validation. Access to returned values performs no I/O, including after closing the client.
Source and package
- Qualified name
-
Libtmux_unix .Client. capture - Module
- Libtmux_unix
- Declared in
Client- Package
- libtmux-unix
- Source
- unix/libtmux_unix.mli
- Other languages
- Perlmethod Erlangfunction PowerShellcmdlet Juliafunction Elixirfunction Haskell Common Lispfunction Python RubyLuaTypeScriptRustmethod GoJavaC# C++ SwiftKotlinScalaF#function Clojurefunction
- val capture : ?cancel:Cancellation
.t -> t -> (Libtmux.Snapshot , Libtmux.t .Error ) result.t -
Public owner:
Libtmux_unixExamples#
Navigate the typed object graph. This complete program creates a private daemon, checks its result and closes its clients. Use OCaml 5.5.2 on Linux with tmux 3.3a through 3.8. Run it from the source checkout after following the installation guide. View source
open Libtmuxmodule Client = Libtmux_unix.Clientmodule Workspace = Libtmux_unix.Workspacemodule Config = Libtmux_workspace.Configmodule Plan = Libtmux_workspace.Planmodule Execution = Libtmux_workspace.Executionlet get = function| Ok value -> value| Error error -> failwith (Format.asprintf "%a" Error.pp error)let capture_graph client (initial : Created.t) spawn =let linked =get(Client.create_session client ~name:"linked" ~window_name:"linked-home"~spawn ())inlet pane =Snapshot.find_pane(get (Client.capture client))(Pane.Target.id linked.pane)|> Option.getinlet text = "showcase ready" inignore (get (Client.wait_for_text ~timeout:0.5 client pane ~text));get(Client.link_window client initial.window ~session:linked.session ~index:7);get (Client.capture client)let print_graph snapshot =Snapshot.sessions snapshot|> Iarray.iter (fun session ->Session.window_links session|> Iarray.iter (fun link ->let window = Window_link.window link inPrintf.printf "%s/%d %s: %d pane(s)\n" (Session.name session)(Window_link.index link) (Window.name window)(Iarray.length (Window.panes window))));assert (Iarray.length (Snapshot.sessions snapshot) = 2);assert (Iarray.length (Snapshot.windows snapshot) = 2);assert (Iarray.length (Snapshot.window_links snapshot) = 3);assert (Iarray.length (Snapshot.panes snapshot) = 2);print_endline "graph: 2 sessions, 2 windows, 3 links, 2 panes"let with_demo binary use =let directory = Filename.temp_dir "libtmux-ocaml-showcase-" "" inFun.protect~finally:(fun () ->Sys.readdir directory|> Array.iter (fun name -> Sys.remove (Filename.concat directory name));Unix.rmdir directory)(fun () ->let socket = Filename.concat directory "server" in(* Give this private daemon a lifetime even if startup fails. *)let config_file = Filename.concat directory "tmux.conf" inOut_channel.with_open_text config_file (fun output ->output_string output "set-option -s exit-unattached on\n");let wrapper = Filename.concat directory "tmux" inOut_channel.with_open_text wrapper (fun output ->Printf.fprintf output "#!/bin/sh\nexec %s -f %s \"$@\"\n"(Filename.quote binary)(Filename.quote config_file));Unix.chmod wrapper 0o700;let channel = Unix.open_process_args_in binary [| binary; "-V" |] inlet version =Fun.protect~finally:(fun () ->if Unix.close_process_in channel <> Unix.WEXITED 0 thenfailwith "tmux version discovery failed")(fun () -> String.trim (input_line channel))inif not (String.starts_with ~prefix:"tmux " version) thenfailwith "invalid tmux version";let version = String.sub version 5 (String.length version - 5) inlet ready = Filename.concat directory "ready.txt" inOut_channel.with_open_text ready (fun output ->output_string output "showcase ready\n");let spawn =Spawn.make (Exec { program = "/bin/cat"; args = [ "-u"; ready; "-" ] })inlet config =matchConfig.make ~directory ~session:"showcase"[ Config.window ~name:"editor" [ Config.pane ~spawn () ] ]with| Ok value -> value| Error error -> failwith (Format.asprintf "%a" Config.pp_error error)inlet plan =matchPlan.make~endpoint:(Endpoint.socket_path socket)~version ~observed:None configwith| Ok value -> value| Error error -> failwith (Format.asprintf "%a" Plan.pp_error error)inlet operation = get (Workspace.submit_bootstrap ~binary:wrapper plan) inFun.protect~finally:(fun () -> get (Workspace.close operation))(fun () ->let receipt = get (Workspace.await operation) inif receipt.status <> Execution.Succeeded thenfailwith "workspace setup failed";let client = Option.get (Workspace.client operation) inlet initial = List.hd (Iarray.get receipt.steps 0).created inPrintf.printf "socket=%s\n%!" socket;let pane =Snapshot.find_pane(get (Client.capture client))(Pane.Target.id initial.pane)|> Option.getinignore(get(Client.wait_for_text ~timeout:0.5 client pane~text:"showcase ready"));use client initial spawn))let () =let binary = if Array.length Sys.argv = 2 then Sys.argv.(1) else "tmux" inlet snapshot = with_demo binary capture_graph inprint_graph snapshotRun the recorded entry point:
Terminal window $ opam exec -- dune exec examples/showcase_graph.exe -- tmuxExpected outcome line, after the temporary socket path:
graph: 2 sessions, 2 windows, 3 links, 2 panes
tmux command#
The tmux commands behind capture.
list-clients list-panes -a server scope, cmd_list_panes_server list-sessions list-windows -a server scope, cmd_list_windows_exec tmux C API#
The C declarations in tmux that implement these commands.
In other ports#
Capture the tmux hierarchy
| Language | Equivalent |
|---|---|
| Python | no equivalent on Server |
| Ruby | Lib |
| Lua | libtmux |
| PowerShell | Lib Acquires a replacement LibTmux.Server to -Depth (panes by default). Acquisition is not atomic; retained handles do not refresh. |
| Julia | Lib Acquires a new Snapshot over an observation interval. Topology checks do not make it a transaction; earlier snapshots do not refresh. |
| Erlang | tmux Captures a new graph over an observation interval. Retained snapshots never refresh. |
| Elixir | Lib Captures a new graph over an observation interval. A retained Snapshot never refreshes. |
| Haskell | No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing. |
| Common Lisp | libtmux: fetch-snapshot acquires a new interval observation. Retained snapshots never refresh in place. |
| TypeScript | server |
| Rust | server Fetches the whole hierarchy with list-sessions, list-windows -a and list-panes -a, and stitches the rows by winlink. The three listings are separate commands, so the capture is not an atomic transaction. |
| Go | tmux |
| Java | io |
| Clojure | libtmux Acquires a captured graph of persistent values. Retained values do not refresh after mutation or close. |
| Kotlin | io |
| Scala | io |
| C# | Lib |
| F# | Lib Acquires a replacement shared .NET LibTmux.Server to the requested depth. Acquisition is not atomic; retained handles do not refresh. |
| C++ | no equivalent on Server: sessions, windows, panes and clients each take a snapshot of one listing, and Snapshot::take needs the internal detail::Backend, so no public call reads the whole hierarchy at once |
| Swift | Server |
| Perl | Lib Strict acquisition observes an interval, not an atomic transaction; retained handles do not refresh. |