# Libtmux_unix.Client.capture

- **Module:** Libtmux_unix
- **Package:** libtmux-unix
- **Language:** OCaml
- **Kind:** function
- **Source:** https://github.com/libtmux/libtmux-ocaml/blob/205dfda49742592b479247049d186956e4a4cfe9/unix/libtmux_unix.mli#L278
- **Public owner:** Libtmux_unix
- **Page:** https://libtmux.org/en/ocaml/latest/reference/libtmux_unix-client-capture/

```
val capture :
  ?cancel:Cancellation.t -> t -> (Libtmux.Snapshot.t, Libtmux.Error.t) result
```

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.

## Examples

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.

[Source example](https://github.com/libtmux/libtmux-ocaml/blob/205dfda49742592b479247049d186956e4a4cfe9/examples/showcase_graph.ml).

```ocaml
open Libtmux
module Client = Libtmux_unix.Client
module Workspace = Libtmux_unix.Workspace
module Config = Libtmux_workspace.Config
module Plan = Libtmux_workspace.Plan
module Execution = Libtmux_workspace.Execution

let 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 ())
  in
  let pane =
    Snapshot.find_pane
      (get (Client.capture client))
      (Pane.Target.id linked.pane)
    |> Option.get
  in
  let text = "showcase ready" in
  ignore (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 in
          Printf.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-" "" in
  Fun.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" in
      Out_channel.with_open_text config_file (fun output ->
          output_string output "set-option -s exit-unattached on\n");
      let wrapper = Filename.concat directory "tmux" in
      Out_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" |] in
      let version =
        Fun.protect
          ~finally:(fun () ->
            if Unix.close_process_in channel <> Unix.WEXITED 0 then
              failwith "tmux version discovery failed")
          (fun () -> String.trim (input_line channel))
      in
      if not (String.starts_with ~prefix:"tmux " version) then
        failwith "invalid tmux version";
      let version = String.sub version 5 (String.length version - 5) in
      let ready = Filename.concat directory "ready.txt" in
      Out_channel.with_open_text ready (fun output ->
          output_string output "showcase ready\n");
      let spawn =
        Spawn.make (Exec { program = "/bin/cat"; args = [ "-u"; ready; "-" ] })
      in
      let config =
        match
          Config.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)
      in
      let plan =
        match
          Plan.make
            ~endpoint:(Endpoint.socket_path socket)
            ~version ~observed:None config
        with
        | Ok value -> value
        | Error error -> failwith (Format.asprintf "%a" Plan.pp_error error)
      in
      let operation = get (Workspace.submit_bootstrap ~binary:wrapper plan) in
      Fun.protect
        ~finally:(fun () -> get (Workspace.close operation))
        (fun () ->
          let receipt = get (Workspace.await operation) in
          if receipt.status <> Execution.Succeeded then
            failwith "workspace setup failed";
          let client = Option.get (Workspace.client operation) in
          let initial = List.hd (Iarray.get receipt.steps 0).created in
          Printf.printf "socket=%s\n%!" socket;
          let pane =
            Snapshot.find_pane
              (get (Client.capture client))
              (Pane.Target.id initial.pane)
            |> Option.get
          in
          ignore
            (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" in
  let snapshot = with_demo binary capture_graph in
  print_graph snapshot
```

Run the recorded entry point:

```console
$ opam exec -- dune exec examples/showcase_graph.exe -- tmux
```

Expected outcome line, after the temporary socket path:

```text
graph: 2 sessions, 2 windows, 3 links, 2 panes
```

## Parameters

- `cancel?` (`Cancellation.t`)
- `arg1` (`t`)

## tmux command

The tmux commands behind `capture`.

- [`list-clients`](/en/tmux/latest/manual/list-clients/)
- [`list-panes`](/en/tmux/latest/manual/list-panes/) `-a` server scope, [`cmd_list_panes_server`](/en/tmux/latest/reference/c-function-cmd-list-panes-c-cmd_list_panes_server/) (source: `unix/acquisition.ml:65`)
- [`list-sessions`](/en/tmux/latest/manual/list-sessions/)
- [`list-windows`](/en/tmux/latest/manual/list-windows/) `-a` server scope, [`cmd_list_windows_exec`](/en/tmux/latest/reference/c-function-cmd-list-windows-c-cmd_list_windows_exec/) (source: `unix/acquisition.ml:30`)

## tmux C API

The C declarations in tmux that implement these commands.

- [`cmd_list_clients_entry`](/en/tmux/latest/reference/c-variable-cmd_list_clients_entry/) (attribute)
- [`cmd_list_clients_exec`](/en/tmux/latest/reference/c-function-cmd-list-clients-c-cmd_list_clients_exec/) (function)
- [`cmd_list_panes_entry`](/en/tmux/latest/reference/c-variable-cmd_list_panes_entry/) (attribute)
- [`cmd_list_panes_server`](/en/tmux/latest/reference/c-function-cmd-list-panes-c-cmd_list_panes_server/) (function)
- [`cmd_list_sessions_entry`](/en/tmux/latest/reference/c-variable-cmd_list_sessions_entry/) (attribute)
- [`cmd_list_sessions_exec`](/en/tmux/latest/reference/c-function-cmd-list-sessions-c-cmd_list_sessions_exec/) (function)
- [`cmd_list_windows_entry`](/en/tmux/latest/reference/c-variable-cmd_list_windows_entry/) (attribute)
- [`cmd_list_windows_exec`](/en/tmux/latest/reference/c-function-cmd-list-windows-c-cmd_list_windows_exec/) (function)

## In other ports

Capture the tmux hierarchy

| Language | Equivalent |
| --- | --- |
| Python | no equivalent on `Server` |
| Ruby | [`LibTmux::Server#snapshot`](/en/ruby/latest/reference/libtmux-server-snapshot/) (method) |
| Lua | [`libtmux.Server:snapshot`](/en/lua/latest/reference/libtmux-server-snapshot/) (method) |
| PowerShell | [`LibTmux\Get-TmuxSnapshot`](/en/powershell/latest/reference/libtmux-get-tmuxsnapshot/) (cmdlet). Acquires a replacement `LibTmux.Server` to [`-Depth`](/en/powershell/latest/reference/libtmux-get-tmuxsnapshot/#LibTmux%5CGet-TmuxSnapshot.parameter.Depth) (panes by default). Acquisition is not atomic; retained handles do not refresh. |
| Julia | [`LibTmux.snapshot`](/en/julia/latest/reference/libtmux-snapshot-1gv6/) (function). Acquires a new `Snapshot` over an observation interval. Topology checks do not make it a transaction; earlier snapshots do not refresh. |
| Erlang | [`tmux_server:snapshot/1`](/en/erlang/latest/reference/tmux_server-snapshot-1/) (function). Captures a new graph over an observation interval. Retained snapshots never refresh. |
| Elixir | [`LibTmux.Server.snapshot/2`](/en/elixir/latest/reference/libtmux-server-snapshot-2/) (function). 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`](/en/lisp/latest/reference/libtmux-fetch-snapshot/) (function). `fetch-snapshot` acquires a new interval observation. Retained snapshots never refresh in place. |
| TypeScript | [`server.Server.snapshot`](/en/ts/latest/reference/server-server-snapshot/) (method) |
| Rust | [`server.Server.hierarchy`](/en/rs/latest/reference/server-server-hierarchy/) (method). 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.Server.Snapshot`](/en/go/latest/reference/tmux-server-snapshot/) (method) |
| Java | [`io.github.libtmux.Server.snapshot`](/en/java/latest/reference/io-github-libtmux-server-server-snapshot/) (method) |
| Clojure | [`libtmux.core/snapshot!`](/en/clojure/latest/reference/libtmux-core-snapshot/) (function). Acquires a captured graph of persistent values. Retained values do not refresh after mutation or close. |
| Kotlin | [`io.github.libtmux.kotlin.Server.snapshot`](/en/kotlin/latest/reference/io-github-libtmux-kotlin-server-snapshot/) (method) |
| Scala | [`io.github.libtmux.scaladsl.Server.snapshot`](/en/scala/latest/reference/io-github-libtmux-scaladsl-server-snapshot/) (method) |
| C# | [`LibTmux.Server.CaptureSnapshotAsync`](/en/csharp/latest/reference/libtmux-server-capturesnapshotasync/) (method) |
| F# | [`LibTmux.FSharp.Server.capture`](/en/fsharp/latest/reference/libtmux-fsharp-server-capture/) (function). 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.snapshot()`](/en/swift/latest/reference/server-snapshot()/) (method) |
| Perl | [`LibTmux::Server::snapshot`](/en/perl/latest/reference/libtmux-server-snapshot/) (method). Strict acquisition observes an interval, not an atomic transaction; retained handles do not refresh. |