Core Library0.xAPI Reference

Choose documentation 3

latest

Current version

latest
English

Early release libtmux is released, and its APIs may still change between releases. This site's structure and URLs may change too.

method libtmux-rs latest

Window.panes

List this window's panes, preserving any failure.

Source and package
Qualified name
libtmux::window::Window::panes
Module
window
Declared in
Window
Package
libtmux
Source
crates/libtmux/src/window/navigation.rs
Other languages
Perlmethod Erlangfunction PowerShellcmdlet Juliafunction Elixir Haskell Common Lispfunction PythonRuby Lua TypeScriptGoJavaC#C++SwiftKotlinScalaOCamlfunction F#function Clojurefunction
pub async fn panes(&self) -> Result<Vec<Pane>, Error>

Description#

Panes are addressed by window id rather than by session and index, so this returns the same panes through every link to the window.

Errors

Returns an error when the list command cannot run, or when its output cannot be decoded into snapshots.

Examples#

List sessions, windows and panes. Read each collection and its relations, then inspect a hierarchy snapshot. Use Rust 1.85 or newer with Cargo, and tmux 3.3a or newer, on a Unix system. In an empty directory, create a project and add the published crates:

Terminal window
$ cargo init --name libtmux-api-example &&
cargo add libtmux@0.1.2 tempfile@3.20 &&
cargo add tokio@1.40 --features macros,rt,time

Replace src/main.rs with this complete program. It owns a private tmux socket, applies a ten-second task deadline, and reports both task and cleanup errors. Server::kill() stops its daemon; Server::shutdown() closes its client executor. Successful cleanup removes the temporary directory even when the task fails. View source

//! List sessions, windows and panes, then read their hierarchy.
use std::error::Error;
use std::time::Duration;
use libtmux::{NewSessionOptions, NewWindowOptions, Server};
type ExampleError = Box<dyn Error>;
fn check(condition: bool, message: &str) -> Result<(), ExampleError> {
if condition {
Ok(())
} else {
Err(message.into())
}
}
async fn demonstrate(server: &Server) -> Result<(), ExampleError> {
let session = server
.new_session(
NewSessionOptions::new("work")
.window_name("editor")
.command("cat"),
)
.await?;
session
.new_window(NewWindowOptions::new("logs").command("cat"))
.await?;
let sessions = server.sessions().await?;
let windows = server.windows().await?;
let panes = server.panes().await?;
check(sessions.len() == 1, "expected one session")?;
check(windows.len() == 2, "expected two windows")?;
check(panes.len() == 2, "expected two panes")?;
check(
session.windows().await?.len() == 2,
"expected two session windows",
)?;
check(
session.panes().await?.len() == 2,
"expected two session panes",
)?;
for window in &windows {
check(
window.session_id() == session.id(),
"window belongs to another session",
)?;
check(
window.panes().await?.len() == 1,
"expected one pane per window",
)?;
}
let hierarchy = server.hierarchy().await?;
let branch = hierarchy.first().ok_or("hierarchy has no session")?;
check(
branch.session.id() == session.id(),
"hierarchy session differs",
)?;
check(branch.windows.len() == 2, "expected two hierarchy windows")?;
check(
branch.windows.iter().all(|window| window.panes.len() == 1),
"hierarchy panes differ",
)?;
println!("listings: 1 session, 2 windows, 2 panes");
Ok(())
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), ExampleError> {
let root = std::path::Path::new("/tmp/libtmux-rs-dev");
std::fs::create_dir_all(root)?;
let directory = tempfile::Builder::new()
.prefix("api-listings-")
.tempdir_in(root)?;
std::fs::write(
directory.path().join("owner"),
std::process::id().to_string(),
)?;
let server = Server::builder()
.socket_path(directory.path().join("tmux.sock"))
.config_file("/dev/null")
.default_timeout(Duration::from_secs(5))
.build()?;
let outcome = tokio::time::timeout(Duration::from_secs(10), demonstrate(&server)).await;
// Stop the owned daemon before closing the client executor.
let killed = server.kill().await;
let closed = server.shutdown().await;
let cleanup_failed = killed.is_err() || closed.is_err();
let mut failures = Vec::new();
match outcome {
Ok(Ok(())) => {}
Ok(Err(error)) => failures.push(format!("example failed: {error}")),
Err(error) => failures.push(format!("example deadline: {error}")),
}
if let Err(error) = killed {
failures.push(format!("daemon cleanup: {error}"));
}
if let Err(error) = closed {
failures.push(format!("executor cleanup: {error}"));
}
if cleanup_failed {
let retained = directory.keep();
failures.push(format!("inspect retained directory {}", retained.display()));
} else if let Err(error) = directory.close() {
failures.push(format!("directory cleanup: {error}"));
}
if failures.is_empty() {
Ok(())
} else {
Err(failures.join("; ").into())
}
}

Run the consumer. Success exits with status 0; setup, operation, deadline or cleanup failures exit unsuccessfully and print diagnostics to stderr:

Terminal window
$ cargo run --quiet

Expected output:

listings: 1 session, 2 windows, 2 panes

tmux command#

The tmux commands behind panes.

tmux C API#

The C declarations in tmux that implement these commands.

Guides#

Pages that discuss panes.

In other ports#

List a window's panes

Equivalents of List a window's panes in other languages
Language Equivalent
Python libtmux.Window.panes
Ruby LibTmux::Window#list_panes
PowerShell LibTmux\Get-TmuxPane Use the -Window parameter set to acquire panes in one window.
Julia LibTmux.panes panes with a captured WindowSnapshot reads panes in that window; missing coverage is an error.
Erlang tmux_snapshot:related/3 Pass panes, a captured physical window and its snapshot for a local relationship read.
Haskell No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing.
Common Lisp libtmux:panes panes traverses a captured window without contacting tmux.
TypeScript window.Window.panes
Go tmux.Window.Panes
Java io.github.libtmux.Window.panes
Clojure libtmux.data/panes Traverses one capture locally. It does not issue a list-panes command.
Kotlin io.github.libtmux.kotlin.Window.panes
Scala io.github.libtmux.scaladsl.Window.panes
C# LibTmux.Window.Panes
F# LibTmux.FSharp.Window.panes Builds a deferred pane query from one LibTmux.Window and its server. Query.list acquires panes scoped to that window ID.
C++ libtmux::Window::panes
Swift Snapshot.panes(of:)
OCaml Libtmux.Window.panes Reads captured panes in one global window without I/O.
Perl LibTmux::Window::panes Reads this physical window’s captured panes without I/O.

No equivalent is recorded in Lua or Elixir.

Esc

Type to search.

Reference previewOpen reference