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

Session.windows

List the windows linked into this session, preserving any failure.

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

Description#

A window linked into other sessions appears here once, under this session's own index for it.

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 windows.

tmux C API#

The C declarations in tmux that implement these commands.

Guides#

Pages that discuss windows.

In other ports#

List a session's windows

Equivalents of List a session's windows in other languages
Language Equivalent
Python libtmux.Session.windows
Ruby LibTmux::Session#list_windows
PowerShell LibTmux\Get-TmuxWindow Use the -Session parameter set to acquire placements in one session.
Julia LibTmux.windows windows with a captured SessionSnapshot reads distinct physical windows in that session. Use windowlinks for placements.
Erlang tmux_snapshot:related/3 Pass windows, a captured session 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:windows windows traverses a captured session. Repeated links preserve their physical-window multiplicity.
TypeScript session.Session.windows
Go tmux.Session.Windows
Java io.github.libtmux.Session.windows
Clojure libtmux.data/windows Traverses one capture locally. It does not issue a list-windows command.
Kotlin io.github.libtmux.kotlin.Session.windows
Scala io.github.libtmux.scaladsl.Session.windows
C# LibTmux.Session.Windows
F# LibTmux.FSharp.Session.windows Builds a deferred window query from one LibTmux.Session and its server. Query.list acquires placements scoped to that session ID.
C++ libtmux::Session::windows
Swift Snapshot.windows(of:)
OCaml Libtmux.Session.windows Reads distinct captured global windows in this session. window_links preserves individual indexed placements.
Perl Traverse Session::window_links and resolve each link’s window, preserving explicit session placement and multiplicity.

No equivalent is recorded in Lua or Elixir.

Esc

Type to search.

Reference previewOpen reference